get-shit-done（GSD）仓库工程指南：从项目结构、构建测试到提交规范的贡献开发全解读

get-shit-done（GSD）是一个面向多编程助手的元提示（meta-prompting）、上下文工程与规格驱动开发系统，仓库同时以 Node.js CLI 与 TypeScript SDK 形态交付。本文以仓库根目录的 AGENTS.md 为准绳，完整梳理该仓库的模块布局、Node 环境要求、构建测试命令、代码风格、测试分层、提交与 PR 规范及安全扫描流程，并结合 package.json、scripts/run-tests.cjs、docs/TESTING-SUITES.md、tests/helpers.cjs 与 SDK 的 vitest.config.ts 等源码级证据做纵深印证。读完本文，你将能在这套仓库中快速定位模块、搭建开发环境、跑通或新增测试，并按照项目约定提交可合入的改动。

一、Active Discussions：仓库的当前工作焦点

AGENTS.md 在正文之前用「Active Discussions」一节指明了一个事实：仓库正在围绕 Grok Build 兼容性，以及 Grok Build、Claude Code、Gemini CLI、Codex 之间的多运行时同步展开工作，相关讨论集中在 docs/discussions/grok-build-support-2026-05.md。

这一背景与 package.json 中对产品的描述互相印证——GSD 面向 Claude Code、OpenCode、Gemini 与 Codex（description 字段明确列出），而 SDK 依赖里还出现了 @anthropic-ai/claude-agent-sdk 等运行时 SDK 依赖。因此，当你在本仓库做改动时，凡是涉及命令、hook、agent 角色文件或安装逻辑的修改，都需要考虑是否需要在多个运行时之间保持行为一致，这正是 AGENTS.md 刻意把讨论入口放在最前面的原因。它提醒贡献者：动手前先核对 docs/discussions/ 下是否有与你改动相关的进行中讨论。

二、项目结构与模块组织

AGENTS.md 给出了仓库布局的总纲。结合根目录的 package.json 的 files 发布清单与 README.md，整体可归纳如下：

目录/文件	职责（依据 AGENTS.md 与 files 清单）
bin/	根包入口点。bin/install.js 是安装器主入口（get-shit-done-cc），bin/gsd-sdk.js 同时映射为 gsd-sdk 与 gsd-tools 两个命令
scripts/	构建、测试、lint 与安全扫描脚本（含 changeset 子目录）
hooks/	运行时 hook（如 gsd-prompt-guard.js、gsd-validate-commit.sh 等），由安装器投影到各编程助手
commands/gsd/	GSD 斜杠命令定义，均为 Markdown 文件，如 plan-phase.md、code-review.md
get-shit-done/	工作流与模板内容（contexts/、references/、templates/、workflows/）以及内部实现 bin/gsd-tools.cjs 与 bin/lib/
agents/	代理（Agent）角色文件，命名统一为 gsd-*.md，如 gsd-planner.md、gsd-executor.md
docs/	文档：ADR（docs/adr/）、多语言 README、讨论、研究等
assets/	Logo 与终端示意图
tests/	根级测试，统一 *.test.cjs，数量在 500+ 量级
sdk/	独立的 TypeScript SDK，源码与 Vitest 测试在 sdk/src/ 下

需要特别注意的是 根包与 SDK 的二元结构：根级 JavaScript 采用 CommonJS，SDK 则是严格 TypeScript + ESM（见后文「编码风格」）。发布侧的证据来自根 package.json 的 files 字段，其中同时打包了根侧资源（bin、commands、get-shit-done、agents、hooks、scripts）与 SDK 侧产物（sdk/src、sdk/shared、sdk/prompts、sdk/dist），说明一次 npm install get-shit-done-cc 即可同时获得 CLI 与可编程 SDK 能力。

三、构建、测试与开发命令

AGENTS.md 明确规定：使用 Node.js >=22，这一点与根 package.json 的 engines 字段（"node": ">=22.0.0"）及 SDK sdk/package.json（同样要求 >=22.0.0）完全一致。因此在动手前，请先执行 node --version 确认版本满足要求。

3.1 根级命令全览

AGENTS.md 列举了以下核心命令，下表同时补充了实际来源与扩展说明：

npm install                     # 安装根依赖
npm test                        # 先构建 SDK，再经 scripts/run-tests.cjs 运行根 node:test 套件
npm run test:coverage           # 用 c8 跑覆盖率，对纳入的 CommonJS 库文件强制 70% 行覆盖率
npm run build:hooks             # 重建生成的 hook 产物
npm run build:sdk               # 安装 SDK 依赖并构建 TypeScript

其中几个关键细节值得展开：

• npm test 并非单一命令。在根 package.json 的 scripts 中，pretest 阶段会先执行 npm run build:sdk && npm run lint:skill-deps，即每次跑测试前都会先构建 SDK 并校验 skill 依赖关系。随后真正的测试体是 node scripts/run-tests.cjs。之所以用 Node 脚本而非 shell 通配符拼接测试文件，正如 scripts/run-tests.cjs 头注释所说明的：Windows PowerShell/cmd 下的 shell 展开行为不可靠，由 Node 读取目录、筛选文件更跨平台。
• 覆盖率阈值是硬性的。package.json 的 test:coverage 定义为 c8 --check-coverage --lines 70 ... --include 'get-shit-done/bin/lib/*.cjs'，即只统计 get-shit-done/bin/lib/ 下的 CommonJS 库文件，行覆盖率红线为 70%，未达标会直接失败。
• npm run build:sdk 会执行 npm ci，即 SDK 侧锁定 package-lock.json 的干净安装，然后执行 tsc 把 TypeScript 编译为 sdk/dist/（参见 sdk/package.json 的 "build": "tsc"）。

3.2 SDK 侧的命令

SDK 作为一个独立子包，需要进入其目录后操作：

cd sdk && npm test             # 运行 SDK Vitest 单元与集成测试
cd sdk && npm run build        # 类型检查并产出 sdk/dist/

SDK 的测试分两个 project，定义在根 vitest.config.ts：名为 unit 的 project 收录 sdk/src/**/*.test.ts（并显式排除集成测试），名为 integration 的 project 收录 sdk/src/**/*.integration.test.ts，且将超时放宽到 120 秒——因为集成测试要真实驱动 Agent SDK。对应脚本见 sdk/package.json：npm test = vitest run，test:unit 与 test:integration 分别限定 project。

3.3 根级测试的套件化执行器

AGENTS.md 只给了最简用法（npm test），但仓库实际提供了一个更细粒度的套件（suite）分层机制，定义于 scripts/run-tests.cjs，完整策略记录在 docs/TESTING-SUITES.md：

node scripts/run-tests.cjs                  # 默认跑全部 *.test.cjs（向后兼容）
node scripts/run-tests.cjs --suite unit     # 仅无标记文件（默认快车道）
node scripts/run-tests.cjs --suite security # 仅 *.security.test.cjs
node scripts/run-tests.cjs --suite install  # 仅 *.install.test.cjs
node scripts/run-tests.cjs --suite slow     # 仅 *.slow.test.cjs

其核心约定是文件名后缀即套件标记：foo.security.test.cjs 属于 security 套件；没有任何标记的 *.test.cjs 默认落入 unit。选择目录式布局（如 tests/security/）之所以被放弃，正是为了不让 500+ 既有测试文件移动位置。此外该执行器还有两个工程细节：通过环境变量 TEST_CONCURRENCY（默认 --test-concurrency=4）控制并发；为避免 Windows CreateProcess 约 32,767 字符的命令行上限，会把测试文件按约 28,000 字符分批执行，相关逻辑见 scripts/run-tests.cjs 中的注释（对应 issue #3597）。

四、编码风格与命名约定

AGENTS.md 的核心原则是「与所改区域的既有风格保持一致」，并给出两套并列规范：

4.1 根级 JavaScript：CommonJS

• 使用 CommonJS 模块系统，整体为 strict mode；
• 两空格缩进、句末分号、优先 const / let；
• 内置模块使用 node: 前缀导入（如 require('node:fs')）。

在代码中可以直接观察到这套约定，例如 scripts/run-tests.cjs 顶部就是 const { readdirSync } = require('fs'); 风格的 CJS 写法，而 bin/install.js 则大量采用 const {...} = require('../get-shit-done/bin/lib/shell-command-projection.cjs') 这种把共享逻辑抽到 lib 目录再引用的结构。

4.2 SDK：严格 TypeScript + ESM/NodeNext

SDK 使用严格 TypeScript，模块体系为 ESM/NodeNext。sdk/package.json 的 "type": "module" 就是直接证据，配合根目录 tsconfig.json 与 sdk/ 内独立的 tsconfig.json 进行类型编译。

4.3 命名约定

• 命令、工作流、测试文件名统一 kebab-case（小写连字符），AGENTS.md 给出的范例与仓库现状完全吻合：命令文件如 commands/gsd/plan-phase.md，测试文件如 tests/bug-2396-makefile-test-priority.test.cjs；
• Agent 文件使用 gsd-*.md 前缀，例如 agents/gsd-planner.md、agents/gsd-executor.md；
• 避免与风格无关的格式化改动、避免引入不必要的新依赖——这是对 diff 可读性与依赖面收敛的双重要求。

五、测试编写准则

AGENTS.md 对「该用哪套测试框架」给出了明确到不容含糊的规定：

5.1 根级测试：只用 Node 内置能力

• 使用 Node 内置的 node:test 与 node:assert/strict；
• 禁止引入 Jest、Mocha 或 Chai；
• 优先复用 tests/helpers.cjs 提供的辅助函数——它封装了临时项目创建、清理与 CLI 执行。其中最核心的是 runGsdTools(args, cwd, env)：支持字符串参数与参数数组两种调用方式，底层通过 execFileSync(process.execPath, [TOOLS_PATH, ...argv], ...) 以 process.execPath 拉起 get-shit-done/bin/gsd-tools.cjs，并返回 { success, output, error, exitCode } 结构化结果，测试可以直接断言这些字段，而无需解析控制台文本。
• 文件名统一为 *.test.cjs；单跑一个测试使用：

node --test tests/你的测试名.test.cjs

5.2 SDK 测试：Vitest

SDK 测试采用 Vitest：*.test.ts 为单元测试，*.integration.test.ts 为集成测试，两者通过 vitest.config.ts 的两个 project 区分。

5.3 跨 Node 版本的前瞻性建议

AGENTS.md 与 docs/TESTING-SUITES.md 共同传递了几条测试最佳实践：CI 会在 Node 22/24/26 上跑矩阵（22 是门槛必须绿、24 是默认开发线、26 为向前兼容且不 gate），因此测试里生成子进程要用 process.execPath 而非硬编码 node，以保证每条矩阵车道用各自版本；断言应落在 err.code、结构化 JSON 字段或枚举上，避免把错误文案写死——Node 小版本会常规性调整报错措辞。覆盖率的采集使用 c8，执行器会透传 NODE_V8_COVERAGE 给子进程。

六、提交与 Pull Request 准则

6.1 Conventional Commits

AGENTS.md 指出近期 git 历史遵循 Conventional Commit 前缀，如 fix:、feat:、ci:，且通常会带上 issue 引用，形如 fix(#2623): resolve parent .planning root...。仓库的完整提交历史中还能看到 docs:、chore:、deprecate: 等其他前缀，建议按实际改动性质选用。原则是：每次提交保持范围聚焦、描述清晰。

6.2 每个 PR 必须关联已批准/确认的 issue

• 在 PR 描述中通过 Closes #123、Fixes #123 或 Resolves #123 显式闭合关联 issue；
• 选用 .github/PULL_REQUEST_TEMPLATE/ 下对应的模板填写 PR；
• PR 内容需覆盖：行为变更说明、根因（如适用）、测试证据、受影响的平台/运行时；
• 涉及用户可见的改动，需同步更新 CHANGELOG.md 或相关文档（仓库根目录的 CHANGELOG.md 即为发布变更日志的汇聚地）。

这条规则与仓库把「多运行时同步」作为核心议题的背景高度相关——改动如果影响 Claude Code / Gemini CLI / Codex / Grok Build 中的某个运行时，PR 中必须明确指出受影响面。

七、安全与配置注意事项

AGENTS.md 的最后一条铁律是不要把密钥、本地配置或生成的工作树（worktree）产物提交进版本库。在做发布级（release-facing）改动之前，务必运行 scripts/ 下的三个扫描脚本：

bash scripts/secret-scan.sh            # 密钥/凭据扫描
bash scripts/base64-scan.sh            # Base64 编码的可疑内容扫描
bash scripts/prompt-injection-scan.sh  # 提示词注入载荷扫描

这三者分别对应仓库安全防护的三种典型威胁面（凭据泄漏、编码混淆的隐藏内容、针对 AI 工作流的提示注入），并且仓库在 tests/ 中存在对应的守卫型测试（如 security 套件下的注入防护测试）。值得注意的是，scripts/prompt-injection-scan.sh 这类脚本的存在，意味着本仓库自身就对「作为 AI 系统提示被注入」这一攻击面有主动防御，贡献者在编写任何会进入提示语/命令模板的文案时也应自觉避免引入非预期的指令性内容。

八、给开发者的上手路线图

综合 AGENTS.md 的全部内容，一个首次接触本仓库的开发者或 AI 代理可以按如下顺序完成「从零到提交」：

1. 确认 Node >= 22（node --version），随后 npm install；
2. 通读目标模块再动手：先判断改动落在 CLI（bin/、commands/gsd/、hooks/）、内容层（get-shit-done/、agents/）还是 SDK（sdk/），遵循「局部风格优先」原则；
3. 为改动补测试：根级用 node:test + tests/helpers.cjs，命名 tests/<feature>.test.cjs；跨模块/真实安装/对抗性/慢速场景，按 docs/TESTING-SUITES.md 加对应后缀（.integration / .install / .security / .slow）；SDK 用 Vitest 的 *.test.ts 或 *.integration.test.ts；
4. 本地跑通相关车道：根级单跑 node --test tests/xxx.test.cjs 或整套 npm test；SDK 跑 cd sdk && npm test；涉及覆盖率门槛可先跑 npm run test:coverage:unit 快速获取信号；
5. 发布级改动前执行三个扫描脚本（secret / base64 / prompt-injection）；
6. 按 Conventional Commit 提交，PR 关联 issue 并选用模板、附测试证据与受影响运行时说明，用户可见改动同步更新 CHANGELOG.md。

九、小结：AGENTS.md 的价值定位

AGENTS.md 虽然篇幅精炼，却是整个仓库开发约定的「总开关」：它把模块地图、环境门槛（Node 22+）、双栈代码风格（CJS 根侧 / ESM TS 的 SDK）、无第三方框架的测试纪律、Conventional Commits + issue 强关联的 PR 规范以及发布前安全扫描收敛在单一入口文档中。对贡献者而言，把 AGENTS.md 当作每次改动前必读的第一份资料，能显著降低「跑错测试框架」「风格不一致」「漏掉 CHANGELOG」这类最常见的返工成本；对维护者而言，它把可验证的规则（如 npm run lint:skill-deps、70% 覆盖率红线、.security.test.cjs 套件约定）沉淀为自动化护栏，让规范不只是纸面条款。