CLI 命令参考（qiongli）

本文件整理本仓库所有“可执行入口”（pipx CLI / Python module / Bash scripts），用于本地与 GitHub CI 保持一致的调用方式。

0) 命令名约定

qiongli：主 CLI（pipx/venv 安装后可用，或通过 shell bootstrap 安装）
ql：短主别名。research-skills、rsk、rsw：旧兼容别名，与 qiongli 等价

下文统一用 qiongli 作为示例。

1) Upstream（上游仓库）如何确定（如何省略 `--repo`）

很多命令需要知道“去哪个 GitHub 仓库查询/下载 release”。qiongli 的上游解析优先级如下（从高到低）：

CLI 参数：--repo <owner/repo|Git URL>
环境变量：QIONGLI_REPO=<owner/repo|Git URL>
旧环境变量 fallback：RESEARCH_SKILLS_REPO=<owner/repo|Git URL>
项目配置文件（从当前目录或 --project-dir 向上搜索）：
- qiongli.toml
- .qiongli.toml
打包默认（pipx 安装的包内）：qiongli/project.toml（由 CI 注入）
如果你正在 qiongli 仓库 clone 内运行：从 git remote 推断（优先 upstream，其次 origin）

支持的 repo 形式：

owner/repo
https://github.com/owner/repo.git
[email protected]:owner/repo.git

推荐把上游提交到你的项目仓库（适合 CI）：

toml

# qiongli.toml
[upstream]
repo = "owner/repo"   # 或 url = "https://github.com/owner/repo.git"

2) `qiongli`（安装/升级器 CLI）

这个 CLI 现在有两种分发方式：

Python CLI：通过 pip/pipx 安装
Shell CLI：由 bootstrap_qiongli.sh 默认安装到 ${QIONGLI_BIN_DIR:-${RESEARCH_SKILLS_BIN_DIR:-~/.local/bin}}

2.1 `qiongli check`（检查版本/是否有更新）

用途：

输出 CLI 版本、本地 repo 版本（若在仓库内运行）、三端已安装版本
可选：查询上游最新 release tag，并判断是否需要升级

bash

qiongli check [--repo <owner/repo|url>] [--json] [--strict-network]

关键参数：

--repo：指定上游（可省略，见“上游解析”）
--json：只输出 JSON（便于 CI/脚本）
--strict-network：如果上游查询失败则返回失败（默认仅提示并继续）

JSON 输出会包含每个 target 当前安装的 active subject 和 coverage。旧 managed install 如果没有 SUBJECT_MANIFEST.json 或 SUBJECT marker，会按 legacy core / complete 处理。

退出码约定：

0：无更新/或跳过上游检查
1：检测到更新可用
2：参数错误

2.2 `qiongli install`（安装包内 subject payload）

用途：

把 PyPI 包内携带的 subject payload 安装到全局客户端 skill 目录。
默认是 --subject core --coverage complete；--subject economics、--subject political-economy 或 --subject geoeconomics 表示全量 Qiongli 加所选 subject 专精。

bash

qiongli install \
  [--subject core|economics|accounting|business|finance|political-economy|geoeconomics|economics-accounting] \
  [--coverage complete|focused] \
  [--target codex|claude|gemini|antigravity|all] \
  [--mode copy|link] \
  [--project-dir <path>] \
  [--overwrite] \
  [--doctor] \
  [--dry-run]

示例：

bash

qiongli install --target all
qiongli install --subject economics --target all
qiongli install --subject accounting --target all
qiongli install --subject political-economy --target all
qiongli install --subject geoeconomics --target all
qiongli install --subject economics-accounting --target all
qiongli install --subject economics --coverage focused --target all

Subject package 是专精安装包，不是降质删减版。默认安装是 core/complete。--subject economics、--subject business、--subject finance、--subject political-economy 和 --subject geoeconomics 表示 complete 专精安装，不是缩水包；--subject accounting 表示 accounting/complete，即全量框架加 accounting 专精。focused coverage 只选择该 subject 的 profiles 和 active effective skills，用于有意选择的精简安装和 Desktop/Web ZIP。当前官方 subjects 是 core、economics、accounting、business、finance、political-economy、geoeconomics 和命名 composite subject economics-accounting；political-economy 和 geoeconomics 是两个独立 subject 选择，不是一个 composite。官方 composite subjects 不是任意逗号分隔叠加。本阶段公开 Desktop ZIP subjects 是 core、economics、business、finance、political-economy、geoeconomics 和 economics-accounting，还没有 standalone accounting Desktop ZIP。切换 subject 或 coverage 时，重新运行 install 或 upgrade 并指定新参数。

2.3 `qiongli upgrade`（下载 release 并执行三端安装脚本）

用途：

下载上游 release（默认 latest tag 的 tar.gz）
解压后运行其中的 scripts/install_qiongli.sh
默认只刷新全局 skill 目录；项目资产需要显式请求

bash

qiongli upgrade \
  [--repo <owner/repo|url>] \
  [--ref <tag-or-branch>] \
  [--ref-type tag|branch] \
  [--subject core|economics|accounting|business|finance|political-economy|geoeconomics|economics-accounting] \
  [--coverage complete|focused] \
  [--target codex|claude|gemini|antigravity|all] \
  [--project-dir <path>] \
  [--no-overwrite] \
  [--doctor] \
  [--dry-run]

说明：

--project-dir 主要在你显式请求项目侧安装面时生效，例如 --parts project。
现在默认的 upgrade 是全局刷新。项目接线建议走 qiongli init --project-dir .；如果确实要在升级时重写项目文件，再显式加 --parts project。
--subject 默认是 core，--coverage 默认是 complete；使用 --subject economics 会安装全量 Qiongli 加 economics 专精，使用 --subject accounting 会安装全量 Qiongli 加 accounting 专精，显式加 --coverage focused 时才安装精简 selected 包。
示例：qiongli upgrade --subject accounting --target all。
全局安装后，upgrade 会自动创建工作流发现 symlink：~/.claude/commands/*.md 和 ~/.gemini/workflows/*.md，可直接使用 /paper、/lit-review 等 slash 命令。
Shell CLI 会通过随附的 bootstrap helper 执行升级，不依赖 Python。
退出码为底层安装器返回码（若安装失败，沿用其错误码）。

2.4 `qiongli align`（快速参考）

用途：打印“pipx 安装了什么 / upgrade 会修改哪些路径 / 常见用法”。

bash

qiongli align [--repo <owner/repo|url>]

2.5 `qiongli init`（项目初始化）

用途：在项目目录中创建 .env 等项目配置。

bash

qiongli init [--project-dir <path>] [--target all|codex|claude|gemini] [--dry-run]

2.6 `qiongli clean`（清理过期资产）

用途：移除旧版本安装留下的项目本地资产。

bash

qiongli clean [--project-dir <path>] [--dry-run] [--globals]

参数说明：

--project-dir：要清理的目录（默认当前目录）。
--globals：同时移除全局工作流发现 symlink（~/.claude/commands/ 和 ~/.gemini/workflows/）。只移除指向 qiongli-workflow 的 symlink，用户自建的命令不受影响。
--dry-run：只显示将要移除的内容，不实际删除。

2.7 `qiongli doctor`（环境预检）

bash

qiongli doctor [--cwd <path>]

2.8 `qiongli customize`（创建 custom subject overlay）

用途：

为 Python/source checkout materialization 工作流创建本地 custom overlay scaffold。
Custom overlays 只影响 generated output，不会改写 canonical source files。
npm runtime installs 在这个阶段使用预生成 payloads，不会在 install 时 materialize --custom-dir overlays。

bash

qiongli customize --subject economics --name my-econ-lab --out ./qiongli-custom/econ-lab
python3 scripts/materialize_subject_package.py --subject economics --custom-dir ./qiongli-custom/econ-lab --source . --out /tmp/qiongli-workflow

开发或加深一个 subject 时，需要同步更新 subjects/catalog.yaml、subject overlays、subject-specific registry and markdown、选定的 domain and venue profiles、subject eval fixtures、specialization audit expected terms、materializer tests、该 subject 可通过 npm 安装时的 npm payload tests，以及该 subject 有 Desktop/Web artifact 时的 release validation。

3) 编排器 CLI：`python3 -m bridges.orchestrator`

这是“三端并发/降级 + task-run 标准合同落盘”的执行入口。

bash

python3 -m bridges.orchestrator <mode> [args...]

mode 列表：

doctor：环境预检

bash

python3 -m bridges.orchestrator doctor --cwd .

parallel：三端并发分析 + 总结端综合（自动降级为双端/单端）

bash

python3 -m bridges.orchestrator parallel \
  --prompt "Analyze this study design" \
  --cwd . \
  --summarizer claude \
  --profile-file standards/agent-profiles.example.json \
  --profile default

task-run：按 Task ID 跑标准链（plan -> evidence -> draft -> review -> gates -> 写入 RESEARCH/）
bash
```
python3 -m bridges.orchestrator task-run \
  --task-id F3 \
  --paper-type empirical \
  --topic your-topic \
  --cwd . \
  --triad
```
常用可选参数：
- --domain <name>：把运行时领域 profile（例如 econ、cs、psychology）注入 task packet 和 prompts
- --venue <name> / --context <text>
- --mcp-strict / --skills-strict
- --profile-file <path> + --profile <name>（以及 --draft-profile / --review-profile / --triad-profile）
- --focus-output <path>（可重复）+ --output-budget <n>：把本次运行收敛到更小的 active outputs，其余 contract outputs 明确标记为 deferred，而不是继续扩写
- --research-depth standard|deep + --max-rounds <n>：提高证据扩展强度，并把 review/revision loop 拉深
- --only-target <id>（可重复）：针对结构化 Stage-I 任务 I4-I8，回读 RESEARCH/[topic]/code/ 下的现有 artifact，并且只重跑指定 actionable target
- --skip-validation：关闭严格的 MCP/skill 可用性校验，并跳过 artifact validator gate；运行结果会明确给出 warning，同时把 validator_gate.skipped=true 写进结果数据
- --update-academic-context：对支持的阶段收口任务（A5、B6、C5、D3、E5、F6、H4），把 context/research_state.md 和 context/decision_log.md 追加进本次 active outputs，并向 draft prompt 注入阶段化的 academic continuity 更新约束
- 内置 profile 新增 focused-delivery、deep-research；原有 default、rapid-draft、strict-review 仍可用
示例：减少辅助文件，但保持更强的深度审查
bash
```
python3 -m bridges.orchestrator task-run \
  --task-id F3 \
  --paper-type empirical \
  --topic your-topic \
  --cwd . \
  --focus-output manuscript/manuscript.md \
  --research-depth deep \
  --draft-profile deep-research \
  --review-profile strict-review \
  --triad-profile deep-research \
  --triad \
  --max-rounds 4
```
示例：只重跑某个 Stage-I planning step
bash
```
python3 -m bridges.orchestrator task-run \
  --task-id I6 \
  --paper-type methods \
  --topic llm-bias \
  --cwd . \
  --only-target S1
```
示例：在阶段收口任务中强制刷新项目级学术上下文连续性产物
bash
```
python3 -m bridges.orchestrator task-run \
  --task-id F6 \
  --paper-type empirical \
  --topic your-topic \
  --cwd . \
  --update-academic-context
```

task-plan：从合同渲染依赖任务顺序（用于“从哪一步开始做”）

bash

python3 -m bridges.orchestrator task-plan --task-id F3 --paper-type empirical --topic your-topic --cwd .

code-build：学术代码工作流入口
bash
```
python3 -m bridges.orchestrator code-build \
  --method "Staggered DID" \
  --topic policy-effects \
  --domain econ \
  --focus full \
  --cwd .
```
关键参数：
- --topic <slug>：提供后会进入严格 Stage I 工作流；不提供时才回落到 legacy prompt-only 模式
- --focus <name>：映射到 I1/I2/I3/I4/I5/I6/I7/I8，或用 full 跑 I5 -> I6 -> I7 -> I8
- --domain <name>：注入对应的 skills/domain-profiles/*.yaml
- --paper-type <type>：严格 Stage-I 路由使用的论文类型
- --triad：在最终严格 review 阶段追加第三个独立审计
- --paper <path-or-url>：可选论文引用，会带入任务上下文
- --only-target <selector>（可重复）：定向 follow-up 模式
  - 单阶段 focus：直接用 S1、P1-01 这类 target ID
  - --focus full：必须写成 STAGE_ID:TARGET，例如 I5:decision-1、I8:P1-01
示例：只跑高级 CS 方法的 spec 阶段
bash
```
python3 -m bridges.orchestrator code-build \
  --method "Transformer Fine-Tuning" \
  --topic llm-bias \
  --domain cs \
  --tier advanced \
  --focus code_specification \
  --paper-type methods \
  --cwd .
```
示例：在 full 流程里只重跑特定 target
bash
```
python3 -m bridges.orchestrator code-build \
  --method "Transformer Fine-Tuning" \
  --topic llm-bias \
  --domain cs \
  --focus full \
  --only-target I5:decision-1 \
  --only-target I8:P1-01 \
  --cwd .
```

single：单模型执行（调试/快速跑）

bash

python3 -m bridges.orchestrator single --prompt "..." --cwd . --model codex

chain：一端生成、另一端验证

bash

python3 -m bridges.orchestrator chain --prompt "..." --cwd . --generator codex

role：按专长拆分任务

bash

python3 -m bridges.orchestrator role --cwd . --codex-task "..." --claude-task "..." --gemini-task "..."

4) Bash 脚本入口（不依赖 pipx）

4.1 远程 bootstrap 安装器：`./scripts/bootstrap_qiongli.sh`

用途：

在没有 Python 的机器上完成安装或刷新。
下载 GitHub release/branch 压缩包，解压后转调其中的 scripts/install_qiongli.sh。

bash

./scripts/bootstrap_qiongli.sh \
  --repo owner/repo \
  --target all \
  --project-dir /path/to/project \
  --overwrite

说明：

依赖 bash 和 curl 或 wget，以及 tar。
支持 --ref <tag-or-branch> 配合 --ref-type tag|branch。
默认会安装 shell CLI 命令：qiongli、ql、research-skills、rsk、rsw。
如果你不想安装 shell CLI，可加 --no-cli；如需改目录，可用 --cli-dir <path>。
远程 bootstrap 只支持 --mode copy。
--doctor 在没有 python3 时会自动跳过。

4.2 安装脚本：`./scripts/install_qiongli.sh`

bash

./scripts/install_qiongli.sh \
  --target all \
  --mode copy \
  --project-dir /path/to/project \
  --install-cli \
  --overwrite \
  --doctor

说明：

这是本地仓库安装器。
copy/link 安装路径本身不再依赖 Python。
如果需要同时安装 shell CLI，可加 --install-cli；默认目录为 ${QIONGLI_BIN_DIR:-${RESEARCH_SKILLS_BIN_DIR:-~/.local/bin}}，也可用 --cli-dir <path> 覆盖。
--doctor 仅在系统存在 python3 时运行 python3 -m bridges.orchestrator doctor --cwd <project>。

4.3 Release 自动化：`./scripts/release_automation.sh`

bash

./scripts/release_automation.sh publish --version 0.1.0 --from-tag v0.1.0-beta.X
./scripts/release_automation.sh pre  --tag v0.1.0-beta.X
./scripts/release_automation.sh post --tag v0.1.0-beta.X --create-release

推荐方式：

日常发布只用 publish
只有诊断或恢复时才用 pre / post
让 publish 统一负责 commit、tag、push、等待 branch CI、等待 tag publish、GitHub Release 和 acceptance receipt
stable 正式版从 CHANGELOG.md 对应章节发布
beta / prerelease 继续从 release/<tag>.md 发布

也可单独运行：

bash

./scripts/release_preflight.sh [--tag v0.1.0-beta.X] [--skip-smoke] [--maintainer-smoke] [--no-strict]
./scripts/release_postflight.sh --tag v0.1.0-beta.X [--skip-remote] [--skip-ci-status] [--wait-ci] [--create-release]

4.4 Beta smoke：`./scripts/run_beta_smoke.sh`

bash

./scripts/run_beta_smoke.sh
./scripts/run_beta_smoke.sh --tier release
./scripts/run_beta_smoke.sh --tier maintainer

这个主 smoke 入口现在支持两档：

release：内置 literature pipeline smoke + doctor
maintainer：包含 release 全部内容，并额外执行 parallel 和 task-run 的 profile 路径检查

release preflight 默认只跑 release 档。只有在你明确想补跑维护者级别检查时，才加 --maintainer-smoke。

4.5 Literature smoke：`./scripts/run_literature_smoke.sh`

bash

./scripts/run_literature_smoke.sh

4.6 CI 注入打包默认上游：`./scripts/inject_project_toml.sh`

GitHub Actions 构建时会运行它，把当前仓库 slug 写入 qiongli/project.toml，让 pipx 安装后的 CLI 默认指向正确上游。

bash

bash scripts/inject_project_toml.sh

# 或覆盖（用于构建时切换到别的 upstream repo）
QIONGLI_REPO_SLUG="other-owner/other-repo" bash scripts/inject_project_toml.sh

5) 校验器（推荐在 CI/发布前运行）

bash

python3 scripts/validate_research_standard.py --strict
python3 -m unittest tests.test_orchestrator_workflows -v

项目产物校验（在你的项目里跑）：

bash

python3 scripts/validate_project_artifacts.py \
  --cwd /path/to/project \
  --topic your-topic \
  --task-id H1 \
  --strict

CLI 命令参考（qiongli） ​

0) 命令名约定 ​

1) Upstream（上游仓库）如何确定（如何省略 --repo） ​

2) qiongli（安装/升级器 CLI） ​

2.1 qiongli check（检查版本/是否有更新） ​

2.2 qiongli install（安装包内 subject payload） ​

2.3 qiongli upgrade（下载 release 并执行三端安装脚本） ​

2.4 qiongli align（快速参考） ​

2.5 qiongli init（项目初始化） ​

2.6 qiongli clean（清理过期资产） ​

2.7 qiongli doctor（环境预检） ​

2.8 qiongli customize（创建 custom subject overlay） ​

3) 编排器 CLI：python3 -m bridges.orchestrator ​

4) Bash 脚本入口（不依赖 pipx） ​

4.1 远程 bootstrap 安装器：./scripts/bootstrap_qiongli.sh ​

4.2 安装脚本：./scripts/install_qiongli.sh ​

4.3 Release 自动化：./scripts/release_automation.sh ​

4.4 Beta smoke：./scripts/run_beta_smoke.sh ​

4.5 Literature smoke：./scripts/run_literature_smoke.sh ​

4.6 CI 注入打包默认上游：./scripts/inject_project_toml.sh ​

5) 校验器（推荐在 CI/发布前运行） ​

CLI 命令参考（qiongli）

0) 命令名约定

1) Upstream（上游仓库）如何确定（如何省略 `--repo`）

2) `qiongli`（安装/升级器 CLI）

2.1 `qiongli check`（检查版本/是否有更新）

2.2 `qiongli install`（安装包内 subject payload）

2.3 `qiongli upgrade`（下载 release 并执行三端安装脚本）

2.4 `qiongli align`（快速参考）

2.5 `qiongli init`（项目初始化）

2.6 `qiongli clean`（清理过期资产）

2.7 `qiongli doctor`（环境预检）

2.8 `qiongli customize`（创建 custom subject overlay）

3) 编排器 CLI：`python3 -m bridges.orchestrator`

4) Bash 脚本入口（不依赖 pipx）

4.1 远程 bootstrap 安装器：`./scripts/bootstrap_qiongli.sh`

4.2 安装脚本：`./scripts/install_qiongli.sh`

4.3 Release 自动化：`./scripts/release_automation.sh`

4.4 Beta smoke：`./scripts/run_beta_smoke.sh`

4.5 Literature smoke：`./scripts/run_literature_smoke.sh`

4.6 CI 注入打包默认上游：`./scripts/inject_project_toml.sh`

5) 校验器（推荐在 CI/发布前运行）