CLI Reference zh

CLI 参考

specgit CLI 共有十个命令。面向人的主线是 issue → finish；setup 安装 agent 入口；bind / unbind / accept 是供脚本使用的机器别名。所有评估都从证据推导，且 fail-closed。

命令总览

命令	用途	网络	退出码
specgit init	创建项目策略并生成护栏	gh（保护探测）	0 · 2 · 3
specgit setup	安装 agent 入口（opencode 命令、其他工具的便携 skills）	无	0 · 2 · 3
specgit issue	一条命令引导交付（issues、分支、草稿 PR、记录、提交、推送）	是	0 · 2 · 3
specgit finish	验收结论 —— 针对 git + forge 的完整评估	是	0 · 1 · 2 · 3
specgit pr	修复 PR 绑定（按头分支自动发现，或显式绑定）	是	0 · 2 · 3
specgit bind	创建/更新交付记录（.specgit.yaml）—— 脚本别名	无	0 · 2 · 3
specgit unbind	删除交付记录 —— 脚本别名	无	0 · 2
specgit status	仅本地证据（记录、策略、git 事实、漂移）	无	0 · 2 · 3
specgit accept	与 finish 相同的评估 —— 脚本/CI 别名	是	0 · 1 · 2 · 3
specgit doctor	探测前置条件（git、仓库、origin、provider CLI、策略）	仅 provider 认证	0 · 3

另有 --version 与 --help（退出码 0；用法错误退出码 2）。

退出码契约

码	含义
0	成功 / 通过验收（所有关卡带证据通过）
1	拒绝且证据完整（所有证据已收集，至少一个关卡失败）
2	用法错误（错误的标志、非法参数）
3	Fail-closed 未知 —— 证据无法收集：记录/策略缺失或无效、provider 缺失或未认证、传输失败、不在 git 仓库内。一个成文例外：specgit status 把缺失的记录视为健康的绑定前状态 —— 退出码 0，状态 unbound；只有无效记录才在那里 fail-closed。
130	中断例外 —— 交互提示期间按 Ctrl-C（SIGINT）。进程向 stderr 打印 Interrupted. 并以 130 退出；不输出 JSON 封套。

1 与 3 的区别是契约性的：1 表示证据已收集且结论为否；3 表示无法得出结论。自动化应按退出码分支，而不是按措辞。

全局标志

• --json —— 每个命令都可用。stdout 变为恰好一个合法 JSON 文档（下文的封套）；所有人类可读文本走 stderr。唯一例外是 Ctrl-C 130 中断路径，不输出封套。

环境变量

变量	含义
SPECGIT_GH	gh 可执行文件路径。默认取 PATH 上的 gh。
SPECGIT_GH_TIMEOUT_MS	单次 gh 调用超时（毫秒）。默认 15000。超时即 gh_transport（退出码 3）。
SPECGIT_GLAB	GitLab 适配器使用的 glab 可执行文件路径。默认取 PATH 上的 glab。
SPECGIT_GLAB_TIMEOUT_MS	单次 glab 调用超时（毫秒）。默认 15000。超时即 glab_transport（退出码 3）。

绝不从环境变量读取 token —— 认证完全依赖你已有的 gh / glab 会话。

语言配置

spec_git/policy.yaml 中的可选 language 键（默认 en，或 zh；用 specgit init --language zh 设置）选择生成文本的语言：issue/PR 脚手架、AGENTS.md 受管区块、成功路径的 stderr 文案。机器契约永不本地化：退出码、--json 字段名、诊断 code、关闭引用（Closes #n）、生成的 workflow YAML、钩子脚本、提交信息。分支名在任何语言下都保持 ASCII —— 非 ASCII 标题回退为 feat/<n>-issue<n>。

specgit init

创建 spec_git/policy.yaml（一次写入；拒绝覆盖）并生成交付护栏。初始化是非破坏性的：先验证后改动、护栏写入错误原子化（部分失败时回滚）、钩子只合并不覆盖。已有策略时再运行 init 退出码 2（policy_exists）；--force 重建策略并刷新护栏。

标志	含义
--required-check <name>	每次交付必须通过的 CI 检查名。可重复。省略时从 CI 文件自动探测；无 CI 的仓库得到空列表。
--gitlab-host <hostname>	声明 origin 平台为自建 GitLab（host 或 host:port）。持久化到 spec_git/providers.yaml。
--language <lang>	en | zh（默认 en）。不支持的值 fail-closed（language_invalid，退出码 2）。
--protect	不再询问，直接启用分支保护 + 自动合并。
--no-protect	完全跳过保护探测和警告。

产物：验收 workflow .github/workflows/specgit-accept.yml（任务名 SpecGit Acceptance，在每个 PR 上运行 specgit finish --json；它从不列入 policy.required_checks —— 避免自我死锁）和 AGENTS.md（缺失则创建）与 CLAUDE.md（仅已存在时）中 <!-- specgit:block:start --> … <!-- specgit:block:end --> 之间的受管提示区块。GitLab 模式下不写 GitHub Actions workflow（gitlab_harness_pending 警告）。

写入后，init 探测默认分支：如果 SpecGit Acceptance 不是那里的必需状态检查，门禁可被绕过 —— init 发出警告并提供启用保护 + 自动合并的选项（--protect 供脚本直接应用；更新是读-改-写，绝不弱化既有规则）。

specgit setup

安装 agent 入口。幂等，可安全重复运行。

specgit setup                 # 自动探测工具
specgit setup --tool opencode # 仅 opencode 命令
specgit setup --tool generic  # 任意工具可用的便携 skills
specgit setup --tool all      # 全部

specgit issue

一条命令引导交付：创建/复用 N 个 issue（一个 issue = 一个可独立验证的 WHY），创建分支 <type>/<首个 issue 号>-<slug>，打开一个正文为确定性脚手架的草稿 PR（每个绑定 issue 一行 Closes #n，然后是 Why / What changed / Evidence / Checklist 小节），写入 .specgit.yaml，提交并推送。重新运行即续跑：已完成的步骤会被检测并跳过。

specgit issue "feat: add login" "Harden the session model"   # 两个新 issue，一次交付
specgit issue 4 "Extend the harness"                          # 复用 #4，新建一个
specgit issue                                                 # 续跑未完成的引导

每个位置参数要么是带引号的标题（<type>: <english title>，type 白名单：feat、fix、refactor、perf、docs、test、chore、style、build、ci、revert、security、deprecate、dogfood），要么是纯数字（复用已有 issue）。slug 取标题前三个 ASCII 单词的 kebab-case。PR 正文在草稿创建时恰好写入一次；续跑和 specgit pr 绝不编辑已有 PR 正文。

关键诊断（退出码 2，零副作用）：issue_resume_drift、issue_delivery_merged、issue_title_ambiguous。Provider 失败（gh_missing、gh_unauthenticated、gh_transport、evidence_truncated）退出码 3，可续跑。

specgit finish

验收结论命令 —— CI 门禁在每个 PR 上以 --json 运行它。通过与 accept 相同的 fail-closed 评估器执行完整的十一关卡评估；检查在 PR 头提交上验证。

specgit finish            # 人类可读的结论
specgit finish --json     # 机器可读的结论（CI 解析这个）

退出码语义：0 通过 · 1 拒绝且证据完整 · 3 无法判定。

specgit pr

修复 PR 绑定。不带参数时按记录分支自动发现处于 open 状态、头分支匹配的 pull request：恰好一个候选则绑定；零个报错并给修复建议（pr_not_found）；多个拒绝并列出候选（pr_ambiguous）。带显式编号或 URL 则直接绑定。

specgit bind

脚本别名：逐字段创建或更新 .specgit.yaml。纯本地，从不访问网络。

specgit bind --delivery add-login-flow --issue 123
specgit bind --issue 124            # 合并进 issues
specgit bind --pr 42                # 设置/替换 PR

specgit unbind

删除当前检出的 .specgit.yaml：specgit unbind --yes（必选标志，无交互提示）。策略文件不受影响。

specgit status

仅报告本地证据 —— 记录、策略、git 实时上下文、上游漂移、origin —— 零网络调用。记录缺失是健康的绑定前状态：退出码 0，状态 unbound，并附指向 specgit issue 的警告。真正的证据失败（record_invalid、policy_missing、policy_invalid、git_unavailable、not_a_git_repo）fail-closed，退出码 3。

specgit accept

specgit finish 的脚本/CI 别名：评估与退出码完全相同，仅封套的 command 字段不同。

specgit doctor

按顺序探测前置条件：git 存在 → 在仓库内 → origin 可解析 → provider CLI 存在 → provider CLI 已认证（GitHub origin 用 gh，声明的 GitLab origin 用 glab）→ 策略存在。全部通过退出码 0，否则 3。

JSON 封套

每次 --json 调用向 stdout 写入恰好一个 JSON 文档：

{
  "tool": "specgit",
  "version": "1.0.0",
  "command": "accept",
  "status": "rejected",
  "exit": 1,
  "state": "bound",
  "verdict": {
    "accepted": false,
    "gates": [
      {
        "id": "closing",
        "status": "fail",
        "code": "closing_refs_incomplete",
        "detail": { "missing": [124] },
        "fix": "Add \"Closes #124\" to the PR body"
      }
    ],
    "evidence": {
      "repo": "LeXwDeX/SpecGit",
      "branch": "feat/123-login",
      "context": { "kind": "branch" },
      "pr": 42,
      "prHead": "abc123…"
    }
  },
  "errors": [
    {
      "severity": "error",
      "code": "closing_refs_incomplete",
      "message": "PR 42 does not close issue #124",
      "target": "pr:42",
      "fix": "Add \"Closes #124\" to the PR body"
    }
  ]
}

字段说明：

• status —— ok | rejected | unknown | error
• exit —— 进程实际退出码（0 | 1 | 2 | 3），与 status 的映射一致
• state —— 推导出的交付状态：unbound | draft | bound | accepted | rejected | unknown
• verdict.gates[] —— 每个被评估关卡一条，含 id、status、失败 code、结构化 detail 和 fix
• verdict.evidence —— 结论所依据的事实
• errors[] —— 诊断项，含 severity、code、message、target、fix

--json 模式下 stdout 不再出现任何其他内容；请解析整个文档，而不是片段。

---

英文版：CLI-Reference