Home zh

SpecGit 中文 Wiki

SpecGit 是一个交付绑定与验收护栏：把一个分支或 worktree 绑定到 forge issues 和一个 pull request，然后从真实的 git、PR 与 CI 证据推导出验收结论。交付完成的唯一标准是 specgit finish 退出码为 0。如果证据无法收集，结论是 unknown 而绝不是 accepted —— SpecGit 是 fail-closed 的（宁可报未知，也不放行）。

一句话模型

执行上下文（分支或 worktree）+ issues[] + 一个 PR（或 MR）+ 必需的 CI 检查

一次交付 = 一个执行上下文 + N 个 issue + 一个 PR/MR + 必需的 CI 检查。证据通过你已认证的 forge CLI 获取 —— GitHub 用 gh，声明的自建 GitLab 用 glab。不读取 token，不做遥测。

三个核心思想

1. AI Agent 的交付护栏

SpecGit 是 AI 编码 agent 的交付护栏（delivery harness）：它不替 agent 写代码，而是通过绑定、证据和退出码约束 agent 的行为边界。Agent 在护栏内自由工作，但只有满足证据门槛，才能声明"完成"。这正是让大模型开发更顺畅的关键：护栏不是限制，而是给 agent 一个确定性的"完成"定义。

2. 一个 issue = 一个可独立验证的 WHY

如果一个交付不能用自己的证据证明其价值，就应该拆分。SpecGit 支持把 N 个 issue 绑定到一个 PR，但每个 issue 必须作为可独立验证的 WHY 独立成立。这是拆解粒度的核心原则：小到可验证，不再更小。

3. 严格线性流程

specgit issue → 实现 → specgit finish —— 一条严格的线性流水线，finish 是唯一的"完成"判定：退出码 0 才算交付完成，其他退出码一律 fail-closed。这消除了 agent 的模糊空间：不存在"我觉得做完了"，只有"证据说做完了"。

目录

页面	内容
快速上手	安装、specgit init 初始化、第一次交付
CLI 参考	十个命令、退出码契约（0/1/2/3/130）、--json 输出
核心概念	三层文件模型、交付绑定、fail-closed 验收、一个 issue = 一个 WHY
Provider 架构	ForgeProvider 端口、gh/glab 适配器、路由机制
GitLab 支持	版本窗口、与 GitHub 的差异
团队协作流程	交付循环、策略即团队契约、评审

关键事实

• 仓库：https://github.com/LeXwDeX/SpecGit
• 安装：npm install -g specgit
• 运行要求：Node.js ≥ 20.19.0、git，以及已认证的 gh（GitHub）或 glab ≥ 1.113.0（声明的 GitLab）
• 命令：init、setup、issue、pr、finish、bind、unbind、status、accept、doctor —— 恰好十个
• 退出码：0 通过/成功 · 1 拒绝 · 2 用法错误 · 3 fail-closed 未知 · 130 被中断
• 许可证：MIT

---

英文版：Home