get-shit-done 的 gsd-tools.cjs 编程式 API 参考：一套覆盖状态、阶段、校验与脚手架的全能 CLI
【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done
本文是 get-shit-done（GSD）内部工具链的核心参考资料，系统讲解
get-shit-done/bin/gsd-tools.cjs这一 Node.js CLI 的全量命令面：State、Phase、Roadmap、Config、模型解析、Verification、Validation、Template、Frontmatter、Scaffold、Init、Milestone 与各类工具命令。读者既能把它当作快速查询的手册，也能理解这些命令如何在 GSD 的工作流与 Agent 编排中被反复调用，掌握在自己编写或调试 GSD 项目时直接复用这批原子能力的方法。
GSD（get-shit-done）是一个基于 Claude Code 的规格驱动开发与上下文工程系统，而gsd-tools.cjs是整个系统底层复用度最高的"胶水层"：它把散布在约 50 个命令、工作流和 Agent 文件中的重复内联 bash 模式，收敛为可编程、可校验、可机械读取的单一 CLI 入口。仓库中对应的权威英文版参考位于 docs/CLI-TOOLS.md，而本文对应的日文版文档为 docs/ja-JP/CLI-TOOLS.md。
定位与使用方式
它解决什么问题
gsd-tools.cjs集中承担了以下原本需要脚本反复手写的能力：
- 配置解析：读写
.planning/config.json； - 模型解析：根据当前 profile 解析各 Agent 应使用的模型层级；
- 阶段查找：按编号定位阶段目录、计算插入用的小数阶段号；
- Git 提交：带配置检查与预提交钩子策略的提交；
- 摘要验证：校验
SUMMARY.md、PLAN.md结构与引用； - 状态管理：维护
.planning/STATE.md这一"项目的活记忆"； - 模板操作：模板选择与变量填充。
从 入口脚本的头部注释 可以看到，它被设计为原子命令集合：每个命令只做一件小而确定的事情，工作流脚本通过组合这些原子命令完成复杂编排。它同样支持state、phase、roadmap、template、frontmatter、scaffold、verify、validate、init、milestone等子命令组。
基本调用
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]全局标志：
| 标志 | 说明 |
|---|---|
--raw | 机器可读输出（JSON 或纯文本，不做格式化） |
--cwd <path> | 覆盖工作目录（面向沙箱化子 Agent） |
值得强调的是：--cwd并非锦上添花，而是工作流安全性的基础。GSD 的多 Agent 编排中，子 Agent 往往运行在独立的临时目录或工作树内，必须通过--cwd把命令锚定到目标项目根，才能在.planning/、STATE.md、ROADMAP.md等相对路径语义上保持一致，避免"读错项目"的串扰。在代码库中，同类路径锚定逻辑由planning-workspace等模块持续强化（对应测试可参见 tests/bug-3521-quick-cleanup-cwd-pin.test.cjs）。
源码与模块布局
- 入口文件：get-shit-done/bin/gsd-tools.cjs
- 领域模块：get-shit-done/bin/lib/ 目录下按领域拆分的 15 个模块（日本语文档的"模块架构"表），当前目录中实际还沉淀了更多辅助模块（如
planning-workspace.cjs、graphify.cjs、learnings.cjs、audit.cjs、intel.cjs、gsd2-import.cjs、uat.cjs等），说明该工具面随仓库演进持续扩展。
入口脚本头部注释同时标注了它当前在仓库内的定位：新编排优先使用gsd-sdk query与@gsd-build/sdk（参见 sdk/src/query/QUERY-HANDLERS.md），而本 CJS CLI 仍是为 shell 脚本与旧工作流保留的兼容实现，并被文档与命令平价测试持续守护。
State 命令：管理项目"活记忆"
.planning/STATE.md记录了项目当前所处位置、计划号、决策、阻塞项、执行指标与上一次活动等状态，是整个系统决策的重要依据。
# 以 JSON 形式加载项目全量配置 + 状态 node gsd-tools.cjs state load # 将 STATE.md 的 frontmatter 输出为 JSON node gsd-tools.cjs state json # 更新单个字段 node gsd-tools.cjs state update <field> <value> # 获取 STATE.md 内容或指定 section node gsd-tools.cjs state get [section] # 批量更新多个字段 node gsd-tools.cjs state patch --field1 val1 --field2 val2 # 递增计划计数器 node gsd-tools.cjs state advance-plan # 记录执行指标 node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] # 重新计算进度条 node gsd-tools.cjs state update-progress # 追加一条决策 node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] # 从文件追加： node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] # 追加/解除阻塞项 node gsd-tools.cjs state add-blocker --text "..." node gsd-tools.cjs state resolve-blocker --text "..." # 记录会话连续性 node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]其中值得关注的两点设计：
- 决策的可追溯性：
add-decision同时支持--phase N关联决策发生的阶段，且支持--summary-file/--rationale-file，便于 Agent 把大段论证写进文件再落库，避免命令行参数超长或被 shell 转义破坏。 - 执行指标的结构化：
record-metric记录--phase、--plan、--duration，可选--tasks、--files，这些指标正是后续progress、stats等展示命令的数据来源。相关状态模板可见 get-shit-done/templates/state.md。
State 快照
state-snapshot对整份STATE.md做结构化解析，一次性返回包含当前位置、阶段、计划、状态、决策、阻塞项、指标与最近一次活动的 JSON，适合在会话恢复（resume）、上下文注入等场景直接消费：
node gsd-tools.cjs state-snapshotPhase 命令：阶段目录、编号与 Roadmap 同步
阶段（phase）是 GSD 推进的基本单位。phase子命令处理"目录、编号、与 ROADMAP.md 的同步"三角关系。
# 按编号查找阶段目录 node gsd-tools.cjs find-phase <phase> # 计算用于插入的下一个小数阶段号 node gsd-tools.cjs phase next-decimal <phase> # 向 ROADMAP.md 追加新阶段 + 创建目录 node gsd-tools.cjs phase add <description> # 在既有阶段之后插入小数阶段 node gsd-tools.cjs phase insert <after> <description> # 删除阶段并给后续阶段重新编号 node gsd-tools.cjs phase remove <phase> [--force] # 将阶段标记为完成，同步更新状态与 ROADMAP node gsd-tools.cjs phase complete <phase> # 用 wave 与状态索引计划 node gsd-tools.cjs phase-plan-index <phase> # 带过滤条件列出阶段 node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]小数阶段编号（如1.1、2.3）是 GSD 在不打乱既有编号的前提下做"就地插入"的机制：next-decimal负责算出合法的小数号，insert负责把它写进 Roadmap 并创建对应目录，remove之后又会触发后续阶段重新编号。仓库中存在专门针对小数阶段与编号语义的测试（如 tests/bug-2554-decimal-phase-filter.test.cjs、tests/next-decimal-roadmap-scan.test.cjs），可印证这套编号约定的严谨性。
Roadmap 命令：解析与更新 ROADMAP.md
# 从 ROADMAP.md 提取阶段区块 node gsd-tools.cjs roadmap get-phase <phase> # 含磁盘状态的全量 Roadmap 解析 node gsd-tools.cjs roadmap analyze # 依据磁盘真实情况刷新进度表行 node gsd-tools.cjs roadmap update-plan-progress <N>roadmap analyze的特别之处在于"含磁盘状态"：它不仅解析 ROADMAP.md 文本，还会对照磁盘上的阶段目录、计划文件实际存在情况给出全貌，是validate consistency等健康检查命令判定"文档与磁盘是否同步"的数据基础。入口脚本头部注释进一步给出了该模块的扩展子命令，例如roadmap annotate-dependencies <N>（为 ROADMAP.md 补充 wave 依赖说明与跨切约束）。
Config 命令：读写.planning/config.json
# 用默认值初始化 config.json node gsd-tools.cjs config-ensure-section # 设置配置值（点记法） node gsd-tools.cjs config-set <key> <value> # 获取配置值 node gsd-tools.cjs config-get <key> # 设置模型 profile node gsd-tools.cjs config-set-model-profile <profile>点记法（dot notation）使得嵌套配置可以被精确定位，例如review.models.codex、graphify.enabled这类多级键都能直接读写。Config 的取值语义、默认值与文档/源码的一致性在仓库中受到多路守护，例如 tests/config-field-docs.test.cjs、tests/config-schema-docs-parity.test.cjs 与 tests/config-get-default.test.cjs。完整字段参考见 docs/CONFIGURATION.md。
模型解析：为 Agent 分配合适模型
# 基于当前 profile 获取指定 Agent 应使用的模型 node gsd-tools.cjs resolve-model <agent-name> # 返回值层级：opus | sonnet | haiku | inherit可解析的 Agent 名包括：gsd-planner、gsd-executor、gsd-phase-researcher、gsd-project-researcher、gsd-research-synthesizer、gsd-verifier、gsd-plan-checker、gsd-integration-checker、gsd-roadmapper、gsd-debugger、gsd-codebase-mapper、gsd-nyquist-auditor。
inherit这一返回值语义值得注意：它表示该 Agent 不单独指定模型、直接继承会话级模型，从而让编排层可以在"显式分配"与"跟随主模型"之间灵活取舍。在英文权威版 docs/CLI-TOOLS.md 中补充说明：--raw输出直接给出模型 ID/层级，JSON 输出则额外包含 profile 与（当运行时可支持时）reasoning_effort字段。该解析器对应的实现与测试可分别参见 get-shit-done/bin/lib/model-profiles.cjs 与 tests/model-profiles.test.cjs。
Verification 命令：校验计划、阶段、引用与提交
# 校验 SUMMARY.md 文件 node gsd-tools.cjs verify-summary <path> [--check-count N] # 检查 PLAN.md 结构与任务 node gsd-tools.cjs verify plan-structure <file> # 确认所有计划都有摘要 node gsd-tools.cjs verify phase-completeness <phase> # 检查 @引用与路径是否可解析 node gsd-tools.cjs verify references <file> # 批量校验提交哈希 node gsd-tools.cjs verify commits <hash1> [hash2] ... # 检查 must_haves.artifacts 是否满足 node gsd-tools.cjs verify artifacts <plan-file> # 检查 must_haves.key_links 是否满足 node gsd-tools.cjs verify key-links <plan-file>这一组命令共同构成 GSD 的"产出物可验收"防线：verify-summary校验摘要完整性（可指定期望计数--check-count），verify phase-completeness从阶段维度兜底检查"每个计划都有摘要"，verify references防止文档中散落的@引用与路径悬空，verify artifacts/verify key-links则对照计划中声明的must_haves逐项核验产物与关键链接是否真实落地。这些校验器的集中实现位于 get-shit-done/bin/lib/verify.cjs，其背后是庞大而系统的回归测试族（如 tests/verify.test.cjs、tests/verification-overrides.test.cjs）。
Validation 命令：检查项目完整性
# 检查阶段编号、磁盘/Roadmap 同步一致性 node gsd-tools.cjs validate consistency # 检查 .planning/ 完整性，可选自动修复 node gsd-tools.cjs validate health [--repair]validate health --repair是"自我修复"入口：普通检查只读报告，追加--repair后会对发现的问题执行可逆修复，常用于会话开始时的一键体检。仓库中的健康检查门禁（如 tests/health-validation.test.cjs）覆盖了对这些校验行为的断言。
Template 命令：模板选择与填充
# 按粒度选择摘要模板 node gsd-tools.cjs template select <type> # 用变量填充模板 node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']fill支持的模板类型：summary、plan、verification。
模板是 GSD 保证文档格式一致性的关键：每类文档都有预结构化骨架，配合变量填充生成标准开篇。以摘要为例，get-shit-done/templates/ 下存放了summary-minimal.md、summary-standard.md、summary-complex.md等多粒度模板，template select正是按上下文复杂程度挑选合适的粒度。实现在 get-shit-done/bin/lib/template.cjs。
Frontmatter 命令：任意 Markdown 的 YAML frontmatter CRUD
# 将 frontmatter 抽取为 JSON node gsd-tools.cjs frontmatter get <file> [--field key] # 更新单个字段 node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal # 将 JSON 合并进 frontmatter node gsd-tools.cjs frontmatter merge <file> --data '{json}' # 校验必填字段 node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verificationGSD 的规划文档大量依赖 YAML frontmatter 承载机器可读元数据（编号、状态、类型、进度等），因此这套 CRUD + 校验原语是"文档即数据"的基石：frontmatter get --field允许精确取单键；frontmatter validate --schema依据plan/summary/verification三套契约校验必填字段，任何一次字段丢失都能在写入前被拦截。仓库对 frontmatter 契约的健壮性有非常密集的测试覆盖（如 tests/frontmatter.test.cjs、tests/feat-3594-parser-adversarial-frontmatter.test.cjs），实现位于 get-shit-done/bin/lib/frontmatter.cjs。
Scaffold 命令：生成预结构化文件与目录
# 生成 CONTEXT.md 模板 node gsd-tools.cjs scaffold context --phase N # 生成 UAT.md 模板 node gsd-tools.cjs scaffold uat --phase N # 生成 VERIFICATION.md 模板 node gsd-tools.cjs scaffold verification --phase N # 创建阶段目录 node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"scaffold 解决了"每个阶段/验证周期都要从零敲一遍目录和文档骨架"的重复劳动：新阶段启动时一次性铺好CONTEXT.md、UAT.md、VERIFICATION.md与目录结构，后续工作流只需聚焦内容填充。可对照的模板源文件包括 get-shit-done/templates/context.md、get-shit-done/templates/verification-report.md 与 get-shit-done/templates/UAT.md。
Init 命令：复合上下文一次加载
init面向的是"某个工作流开场时需要把全部上下文灌入 Agent 上下文窗口"这一高频诉求，一次性返回包含项目信息、配置、状态与工作流特有数据的 JSON：
node gsd-tools.cjs init execute-phase <phase> node gsd-tools.cjs init plan-phase <phase> node gsd-tools.cjs init new-project node gsd-tools.cjs init new-milestone node gsd-tools.cjs init quick <description> node gsd-tools.cjs init resume node gsd-tools.cjs init verify-work <phase> node gsd-tools.cjs init phase-op <phase> node gsd-tools.cjs init todos [area] node gsd-tools.cjs init milestone-op node gsd-tools.cjs init map-codebase node gsd-tools.cjs init progress大体积载荷处理：当输出超过约 50KB 时，CLI 会改写到临时文件并返回@file:/tmp/gsd-init-XXXXX.json。工作流必须检测@file:前缀并从磁盘读取：
INIT=$(node gsd-tools.cjs init execute-phase "1") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi这是一处非常实用的工程细节：命令行输出天然不适合承载数百 KB 的上下文包，@file:协议在"命令返回面"与"磁盘中转"之间划出明确边界，保证 Agent 即使在大项目里也能无截断地拿到完整上下文。该逻辑的上下文度量与注入行为有专门的回归保障（如 tests/context-enrichment.test.cjs、tests/context-utilization.test.cjs）。
Milestone 命令：里程碑归档与需求标记
# 归档里程碑 node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases] # 将需求标记为完成 node gsd-tools.cjs requirements mark-complete <ids> # 接受格式：REQ-01,REQ-02 或 REQ-01 REQ-02 或 [REQ-01, REQ-02]milestone complete --archive-phases会把阶段目录移入里程碑归档区，实现"交付即归档"。而requirements mark-complete对 ID 格式格外宽容——逗号分隔、空格分隔、JSON 数组三种写法都接受，这降低了不同 Agent 在拼接参数时的出错概率。实现参考 get-shit-done/bin/lib/milestone.cjs。
工具命令：日常高频小工具
# 将文本转为 URL 安全的 slug node gsd-tools.cjs generate-slug "Some Text Here" # → some-text-here # 获取时间戳 node gsd-tools.cjs current-timestamp [full|date|filename] # 统计并列出待办 TODO node gsd-tools.cjs list-todos [area] # 检查文件/目录是否存在 node gsd-tools.cjs verify-path-exists <path> # 聚合全部 SUMMARY.md 数据 node gsd-tools.cjs history-digest # 从 SUMMARY.md 抽取结构化数据 node gsd-tools.cjs summary-extract <path> [--fields field1,field2] # 项目统计 node gsd-tools.cjs stats [json|table] # 进度渲染 node gsd-tools.cjs progress [json|table|bar] # 完成一条 TODO node gsd-tools.cjs todo complete <filename> # UAT 审计——扫描所有阶段中未解决的事项 node gsd-tools.cjs audit-uat # 带配置检查的 git 提交 node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]generate-slug生成的some-text-here式 slug 被广泛用于阶段目录命名与文档 ID；current-timestamp的三种格式（full/date/filename）分别适配日志、日期语义与文件名安全场景；progress提供json、table、bar三种渲染，既能给机器，也能给人类看。
关于--no-verify的重要提示
--no-verify会跳过预提交钩子。它专供基于 wave 的并行执行使用：当多个并行 executor Agent 同时提交时，跳过钩子可避免构建锁竞争（例如 Rust 项目中的 cargo 锁冲突）。编排者会在每个 wave 结束后统一执行一次钩子。顺序执行时切勿使用--no-verify，应让钩子正常执行。
这段注释揭示了 GSD 的并发提交策略：并行 Agent 用--no-verify换取构建锁安全，随后由编排者在 wave 边界做一次集中式钩子回补——把"规避竞争"与"不失守防线"同时做到。对提交文件范围、暂存语义与删除行为的深入约束，可以继续阅读英文权威版 docs/CLI-TOOLS.md 中关于--files/--respect-staged/nothing staged的补充说明，以及 tests/commit-files-deletion.test.cjs 等测试。
# Web 搜索（需要 Brave API Key） node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]模块架构一览
日本语文档归纳的领域模块划分如下（入口 get-shit-done/bin/gsd-tools.cjs 按命令前缀路由到对应模块）：
| 模块 | 文件 | 导出内容 |
|---|---|---|
| Core | get-shit-done/bin/lib/core.cjs | error()、output()、parseArgs()与公共工具 |
| State | get-shit-done/bin/lib/state.cjs | 全部state子命令、state-snapshot |
| Phase | get-shit-done/bin/lib/phase.cjs | 阶段 CRUD、find-phase、phase-plan-index、phases list |
| Roadmap | get-shit-done/bin/lib/roadmap.cjs | Roadmap 解析、阶段提取、进度更新 |
| Config | get-shit-done/bin/lib/config.cjs | 配置读写、区块初始化 |
| Verify | get-shit-done/bin/lib/verify.cjs | 全部验证与校验命令 |
| Template | get-shit-done/bin/lib/template.cjs | 模板选择与变量填充 |
| Frontmatter | get-shit-done/bin/lib/frontmatter.cjs | YAML frontmatter CRUD |
| Init | get-shit-done/bin/lib/init.cjs | 全工作流复合上下文加载 |
| Milestone | get-shit-done/bin/lib/milestone.cjs | 里程碑归档、需求标记 |
| Commands | get-shit-done/bin/lib/commands.cjs | 其余杂项：slug、时间戳、TODO、scaffold、统计、Web 搜索 |
| Model Profiles | get-shit-done/bin/lib/model-profiles.cjs | Profile 解析表 |
| UAT | get-shit-done/bin/lib/uat.cjs | 跨阶段 UAT/验证审计 |
| Profile Output | get-shit-done/bin/lib/profile-output.cjs | 开发者 profile 的格式化 |
| Profile Pipeline | get-shit-done/bin/lib/profile-pipeline.cjs | 会话分析流水线 |
从该目录的现状看，除上述 15 个模块外，仓库还新增了planning-workspace.cjs（规划工作区接缝：规划目录解析与.planning/.lock锁）、graphify.cjs（知识图谱）、learnings.cjs（经验提取）、audit.cjs（审计队列）、intel.cjs（可查询的代码库智能索引）、gsd2-import.cjs（GSD-2 反向迁移导入）等模块，印证了这套"单一入口 + 领域模块"架构的持续演进能力。
一致性守护与延伸阅读
gsd-tools.cjs的命令面之所以能长期保持稳定，离不开测试层的系统性守护。仓库以"文档平价（doc parity）"为原则，对文档中声明的命令面与真实 CLI 实现做双向核对，相关用例包括 tests/cli-modules-doc-parity.test.cjs 与 tests/commands-doc-parity.test.cjs；tests/command-contract.test.cjs 则校验命令契约（参数、标志、退出语义）。
后续如需继续深入，推荐按以下路径阅读：
- 用户面向的
/gsd-斜杠命令清单：docs/COMMANDS.md（日文版见 docs/ja-JP/COMMANDS.md）； - 英文权威版 CLI 工具面（含 SDK 迁移矩阵、
graphify、skill-manifest、Reviewer CLI 路由与密钥掩码等扩展内容）：docs/CLI-TOOLS.md； - SDK 查询注册表与 CJS↔SDK 平价规则：sdk/src/query/QUERY-HANDLERS.md；
- 编排架构中工具层的落位：docs/ARCHITECTURE.md 与 docs/ja-JP/ARCHITECTURE.md；
- 配置字段全集：docs/CONFIGURATION.md；
- 各规划文档的模板源：get-shit-done/templates/（含
state.md、summary-standard.md、PLAN与verification-report.md等）。
【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
