get-shit-done 的 gsd-tools.cjs 编程式 API 参考：一套覆盖状态、阶段、校验与脚手架的全能 CLI

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-doneGSD内部工具链的核心参考资料系统讲解get-shit-done/bin/gsd-tools.cjs这一 Node.js CLI 的全量命令面State、Phase、Roadmap、Config、模型解析、Verification、Validation、Template、Frontmatter、Scaffold、Init、Milestone 与各类工具命令。读者既能把它当作快速查询的手册也能理解这些命令如何在 GSD 的工作流与 Agent 编排中被反复调用掌握在自己编写或调试 GSD 项目时直接复用这批原子能力的方法。GSDget-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 Nroadmap 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-countverify 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 namescaffold 解决了每个阶段/验证周期都要从零敲一遍目录和文档骨架的重复劳动新阶段启动时一次性铺好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 上下文窗口这一高频诉求一次性返回包含项目信息、配置、状态与工作流特有数据的 JSONnode 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 被广泛用于阶段目录命名与文档 IDcurrent-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 按命令前缀路由到对应模块模块文件导出内容Coreget-shit-done/bin/lib/core.cjserror()、output()、parseArgs()与公共工具Stateget-shit-done/bin/lib/state.cjs全部state子命令、state-snapshotPhaseget-shit-done/bin/lib/phase.cjs阶段 CRUD、find-phase、phase-plan-index、phases listRoadmapget-shit-done/bin/lib/roadmap.cjsRoadmap 解析、阶段提取、进度更新Configget-shit-done/bin/lib/config.cjs配置读写、区块初始化Verifyget-shit-done/bin/lib/verify.cjs全部验证与校验命令Templateget-shit-done/bin/lib/template.cjs模板选择与变量填充Frontmatterget-shit-done/bin/lib/frontmatter.cjsYAML frontmatter CRUDInitget-shit-done/bin/lib/init.cjs全工作流复合上下文加载Milestoneget-shit-done/bin/lib/milestone.cjs里程碑归档、需求标记Commandsget-shit-done/bin/lib/commands.cjs其余杂项slug、时间戳、TODO、scaffold、统计、Web 搜索Model Profilesget-shit-done/bin/lib/model-profiles.cjsProfile 解析表UATget-shit-done/bin/lib/uat.cjs跨阶段 UAT/验证审计Profile Outputget-shit-done/bin/lib/profile-output.cjs开发者 profile 的格式化Profile Pipelineget-shit-done/bin/lib/profile-pipeline.cjs会话分析流水线从该目录的现状看除上述 15 个模块外仓库还新增了planning-workspace.cjs规划工作区接缝规划目录解析与.planning/.lock锁、graphify.cjs知识图谱、learnings.cjs经验提取、audit.cjs审计队列、intel.cjs可查询的代码库智能索引、gsd2-import.cjsGSD-2 反向迁移导入等模块印证了这套单一入口 领域模块架构的持续演进能力。一致性守护与延伸阅读gsd-tools.cjs的命令面之所以能长期保持稳定离不开测试层的系统性守护。仓库以文档平价doc parity为原则对文档中声明的命令面与真实 CLI 实现做双向核对相关用例包括 tests/cli-modules-doc-parity.test.cjs 与 tests/commands-doc-parity.test.cjstests/command-contract.test.cjs 则校验命令契约参数、标志、退出语义。后续如需继续深入推荐按以下路径阅读用户面向的/gsd-斜杠命令清单docs/COMMANDS.md日文版见 docs/ja-JP/COMMANDS.md英文权威版 CLI 工具面含 SDK 迁移矩阵、graphify、skill-manifest、Reviewer CLI 路由与密钥掩码等扩展内容docs/CLI-TOOLS.mdSDK 查询注册表与 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），仅供参考