Skip to content

Getting Started zh

Jump to bottom
Lex edited this page Aug 21, 2026 · 3 revisions

快速上手

从零开始，直到你的第一次通过验收的交付。命令细节见 CLI 参考；底层模型见核心概念。

前置条件

  • Node.js ≥ 20.19.0 —— 用 node --version 检查
  • git —— SpecGit 基于真实仓库验证交付，离开仓库无法运行
  • gh（GitHub）—— 需已认证：gh auth login，用 gh auth status 验证
  • glab ≥ 1.113.0（仅声明的自建 GitLab 需要）—— 按主机认证：glab auth login --hostname git.example.com

Forge CLI 是 provider 接缝：SpecGit 通过 gh 或 glab 读取 issues、pull request 与 check runs。SpecGit 本身不读取、不回显、不保存任何 token —— 完全依赖你已有的认证会话。

安装

npm install -g specgit
specgit --version
specgit doctor --json     # 探测环境；退出码 0 = 就绪

一屏看懂整个循环

# 一次性操作，每个仓库执行一次
specgit init            # 自动探测必需检查（无 CI 时为空列表）

# 每次交付：一条命令创建 issues、分支、草稿 PR、记录文件
specgit issue "feat: add login flow"

# 当 CI（含 SpecGit Acceptance 任务）在 PR 上全绿后
specgit finish
# 退出码 0 → 通过 · 1 → 拒绝（附证据）· 3 → 无法判定

这就是全部产品界面。其余都是诊断和 JSON。（bind / unbind / accept 保留为脚本别名。）

分步指南

1. 初始化策略与护栏

在仓库默认分支上：

specgit init                                  # 从 CI 文件自动探测
specgit init --required-check "Build"         # 或显式指定（可重复）

不带参数时，检查名从仓库的 CI 文件自动探测（GitHub workflow 的 job 名、GitLab CI 的 job key）。完全没有 CI 的仓库得到空列表 —— 此时 SpecGit Acceptance 任务本身就是门禁。

该命令创建策略文件 spec_git/policy.yaml 并生成护栏：验收 workflow .github/workflows/specgit-accept.yml（在每个 PR 上运行 specgit finish --json）和 AGENTS.md 中的受管 agent 区块。重复运行 init 会幂等地刷新护栏，且绝不改动已有策略；specgit init --force 则重建两者。

2. 一条命令引导交付

specgit issue "feat: add login flow"

每个参数都是一个可独立验证的 WHY：带引号的标题创建新 issue；纯数字复用已有 issue。N 个参数把 N 个 issue 绑定到一次交付。该命令创建分支 feat/<首个 issue 号>-<slug>，打开一个草稿 PR（正文为每个绑定 issue 写入 Closes #n），写入 .specgit.yaml，提交并推送。任何中途失败后重新运行同一命令即可续跑 —— 它是幂等的。

记录文件（.specgit.yaml，提交在交付分支上）：

version: 1
delivery: add-login-flow
context:
  kind: branch
  branch: feat/123-add-login-flow
issues: [123]
pr: 42

重要规则：

  • 一个 issue = 一个可独立验证的 WHY；如果交付物无法凭自身证据验证，绑定前先拆分。
  • 新标题必须匹配 <type>: <english title>；<type> 来自固定白名单（feat、fix、refactor、perf、docs、test、chore、style、build、ci、revert、security、deprecate、dogfood）。
  • context 由 git 实时状态自动填充 —— 绝不手工编辑。

3. 开发、推送，并保留关闭引用

在引导命令创建的分支上开发。PR 正文必须用关闭引用关闭每一个绑定的 issue：

Closes #123

支持的形式：Closes #123、owner/repo#123 以及完整 issue URL，关闭关键词可用 closes、fixes、resolves 及其时态变体。缺失引用会在验收时产生 closing_refs_incomplete。如果 PR 绑定丢失，specgit pr 会按头分支自动发现 PR 并修复记录。

4. 通过必需检查

你的 CI 必须产生与 required_checks 名称完全一致的检查，且报告在 PR 头提交上 —— 包括生成的 SpecGit Acceptance 任务。草稿 PR 永远无法通过验收（pr_draft）：结束前先把 PR 标记为可评审 —— GitHub 用 gh pr ready <number>，GitLab 用 glab mr update <number> --ready。

5. 收尾

specgit finish

SpecGit 重新读取记录与策略，探测 git 实时状态，并通过 forge（gh 或 glab）获取 issue、PR 与检查证据。每个关卡要么带证据通过，要么带错误码和修复建议失败。退出码 0 表示通过验收：交付已绑定，每个 issue 都被 PR 关闭，每个必需检查都在 PR 头提交上为绿。

文件都在哪里

SpecGit 的全部足迹是三层文件：

层级 路径 是什么 是否提交
权威文件 spec_git/policy.yaml 项目的必需检查策略（init 创建） 是
权威文件 .specgit.yaml 本次交付的绑定记录（issue 创建） 是，在交付分支上
权威文件 spec_git/providers.yaml 可选的平台声明（声明的 GitLab 主机） 是
派生护栏 .github/workflows/specgit-accept.yml 生成的验收门禁 —— 用 init --force 重新生成 是
派生护栏 AGENTS.md / CLAUDE.md 受管区块 specgit 标记之间生成的 agent 契约 是
本地集成 守卫钩子、setup 入口 本机布线，非破坏性合并 自行决定

没有产物目录、没有存储、没有缓存。验收结论从不保存 —— 每次运行都重新计算。

英文版：Getting-Started

SpecGit Wiki

中文

Repository documentation

Clone this wiki locally