gsd-plugin

<p align="center"> <img src="assets/gsd-plugin-logo.png" alt="GSD 插件" width="320" /> </p> # 让 Claude 代码变得井然有序 **插件版本：** `4.0.0` **适用于 Claude Code 的 GSD 插件** 确保你的编码工作以系统化、结构化的方式完成。它只会提示你重要的设计和架构决策，这些决策实际上需要你的判断，并将每个步骤分成自己的专注子上下文，以便在长时间的项目中优化令牌使用。 在幕后，GSD 插件针对 Claude Code 进行了性能优化的演进：减少了每轮令牌开销约 92%，添加了 MCP 支持的项目状态，自动在 `/compact` 之间恢复，并将所有内容捆绑到一个单一安装的插件中。 ## 安装 GSD 插件在 Claude Code 会话内部安装，而不是从主机 Shell 安装。如果你以前从未使用过 Claude Code 插件，请按顺序执行以下步骤。 ### 无前提条件 从 **v2.42.0** 开始，插件会捆绑自己的 GSD SDK 副本，位于 `sdk/dist/cli.js`，并附带一个 `bin/gsd-sdk` 包装器，Claude Code 会自动将其添加到 `PATH` 中，以便进行插件 Bash 调用。你不再需要运行 `npm install -g get-shit-done-cc`（或其后续版本 `get-shit-done-redux`）。 关闭了 [#4](https://github.com/jnuyens/gsd-plugin/issues/4)。 ### 预安装：删除任何预 v2.42.0 的全局 SDK 安装 如果你之前通过 `npm -g`（或 `npx`）安装了 `get-shit-done-cc` / `get-shit-done-redux` 或 `@gsd-build/sdk` / `@gsd-redux/sdk`，位于 `/opt/homebrew/bin/gsd-sdk`（Apple Silicon）或 `/usr/local/bin/gsd-sdk`（Intel macOS / Linux）的全局二进制文件在 `$PATH` 中的优先级高于插件的捆绑包装器。全局 SDK 不会遵守 `CLAUDE_PLUGIN_ROOT`，因此每个调用裸 `gsd-sdk` 的插件工作流（初始化查询、代理技能查找、配置读取）都会报告 `agents_installed: false`，并且诸如 `/gsd:new-project` 之类的技能会通过跳过并行研究路径而静默降级。插件的 v2.42.5 包装器-env-export 补丁仅在包装器本身被调用时才会触发，因此遮蔽全局会绕过它。 检查你是否有一个遮蔽安装： ```bash which gsd-sdk ``` 如果输出是 `~/.claude/plugins/cache/gsd-plugin/` 下的路径以外的任何路径（典型的错误输出是 `/opt/homebrew/bin/gsd-sdk` 或 `/usr/local/bin/gsd-sdk`），请在继续之前从主机 Shell 卸载： ```bash npm uninstall -g @gsd-build/sdk npm uninstall -g get-shit-done-cc npm uninstall -g @gsd-redux/sdk npm uninstall -g @opengsd/get-shit-done-redux npm uninstall -g get-shit-done-redux # 如果你尝试过无作用域的名称（npm 上为 404；v2.43.x 文档错误地引用了此表单，在 v2.44.6 中修复） ``` 重新运行 `which gsd-sdk`。预期的卸载后输出要么是 `~/.claude/plugins/cache/gsd-plugin/` 下的路径（在步骤 3 中安装插件后），要么是 `gsd-sdk not found`（安装前）。两者都是正确的。 如果你跳过此步骤并安装插件，请 v2.43.1 及更高版本会附带一个 `gsd-shadowing-sdk-detector` SessionStart 钩子，它将在每次 Claude Code 会话开始时检测冲突并发出一次性通知，指向此部分。 ### 步骤 1：信任 GitHub 的 SSH 主机密钥（仅在新机器上首次） `/plugin marketplace add` 通过 SSH 克隆。在新机器上，GitHub 的主机密钥是未知的，这使得 Claude Code 运行的非交互式 `git clone` 静默失败。在主机 Shell 上一次性初始化 `known_hosts`: ```bash ssh -T git@github.com ``` 在 *"Are you sure you want to continue connecting?"* 提示符下输入 `yes`。后续 *"Permission denied (publickey)"* 消息对于通过 SSH 进行公共仓库克隆是预期的，并且是无害的；你只需要将主机密钥指纹放入 `~/.ssh/known_hosts`。如果你已经从该机器使用过 `git@github.com`，请跳过此步骤。 ### 步骤 2：启动 Claude Code 从你的主机 Shell（Terminal、iTerm 等）中，在任何目录中： ```bash claude --dangerously-skip-permissions ``` 在安装流程中，建议使用 `--dangerously-skip-permissions` 标志：它允许插件市场添加、插件安装和 MCP 服务器启动，而不会出现一堆权限提示。如果你愿意，你可以稍后使用普通的 `claude` 启动。 ### 步骤 3：添加市场并安装插件 你现在应该在 Claude Code 会话中（你将看到 Claude Code 提示，而不是你的 Shell 提示）。在 Claude Code 提示下输入以下三个命令： ``` /plugin marketplace add jnuyens/gsd-plugin /plugin install gsd@gsd-plugin /reload-plugins ``` 就是这样。这安装了所有内容：斜杠命令、代理定义、钩子和一个用于项目状态的 MCP 服务器。`/reload-plugins` 步骤激活了当前会话中新安装的插件；如果没有它，斜杠命令和钩子不会在你重启 Claude Code 之前加载。启用 Claude Code 设置中的市场自动更新，以自动接收更新。 ## 快速开始 假设你已经完成了上面的安装部分（Claude Code 正在运行并安装了插件）。以下命令都在 Claude Code 提示下输入，而不是在你的 Shell 中。 1. 启动新项目：`/gsd:new-project` 2. 计划你的第一个阶段：`/gsd:plan-phase` 3. 执行：`/gsd:execute-phase` 4. 验证：`/gsd:verify-work` ## 更新 在 Claude Code 设置中启用市场自动更新，更新将自动应用。 要手动更新： 1. **刷新磁盘上的插件。** 运行 `/plugins`，打开 **Marketplace**，然后选择 **gsd-plugin** 以刷新它。 然后按 **Esc 两次** 退出市场。 这会更新文件系统上的 gsd-plugin。 2. **在打开的会话中激活它。** 在你已经打开的每个 Claude Code 会话中运行 `/reload-plugins`，以便它们使用新版本而无需重启。 注意：市场步骤（1）会更新磁盘上的插件；`/reload-plugins`（2）是使已经运行的会话使用新版本的方法。 你启动的后续会话会自动加载新版本，无需重新加载（因此，只有你已经打开的会话需要该命令）。 不需要 `/exit` 或重启。 gsd-plugin 附带一个 MCP 服务器，但其工具按需加载，因此重新加载可以干净地应用； 在 Claude Code v2.1.163+ 上，在极少数情况下，重新加载会强制重新读取整个上下文，`/reload-plugins` 会打印警告，你可以重新运行它为 `/reload-plugins --force`。 ## 新增功能 **v4.0.0**：**一致性和代码完整性保障，以及第二个上游。** GSD 现在派生项目的命名和架构约定，并将更改与它们进行对比（`verify conventions`，连接到模式映射器和代码审查），并提供本地漂移检测，查找复制的逻辑、幻影/占位符脚手架和存储库中的结构近克隆（`verify drift`，`/gsd:scan --drift`，以及一个可选的 `audit-milestone` 完整性门控）。 所有检测都是 100% 本地的，具有零运行时依赖。 此版本还正式将 **[VibeDrift](https://www.npmjs.com/package/@vibedrift/cli) 作为第二个上游**：GSD 永远不会运行它，但会移植其漂移检测启发式并监视其发布以选择未来的启发式。 主要版本号升级到 4.0 标志着 gsd-plugin 作为其自己的版本号，表明它与上游 GSD 有多远（参见 [上游项目](#upstream-projects) 和 [版本控制](#versioning)）。 **v3.7.2**：`/gsd:autonomous` 不再停止询问你重新确认然后启动。 工作流没有确认范围步骤，因此协调器谨慎地编造了一个：它打印阶段计划，然后等待你再次确认，这会阻碍自主命令。 一个新的显式合约使规则明确（显示计划，然后在同一回合中继续执行；在发现的约束（如迁移链冲突）作为一行通知它会采取的行动，而不是等待确认的门控）。 剩下的唯一暂停是真正的决策点：人工验证、单个自动重试后的空白/技术债务，以及阻止因素。 **v3.7.1**：修复 `/gsd:version` 在你更新时报告 `Error: Exit code 1`（更新提示链以非零退出，但正确打印；Claude Code 标记它，但插件版本检查正确）。 并修剪其 bash。 将恢复扫描扩展到 `/gsd:validate-phase` 和 `/gsd:secure-phase`，因此修复操作是推荐的（不是中立的菜单）。 **v3.7.0**：**提高会话中断时的恢复能力。** 当会话中断并恢复时，阶段可能部分交付，GSD 以前会丢失线程或面对难以阅读的内部问题。 现在它会愈合： - **中断的 UAT 永远不会丢失。** 如果你在验证中间有中断（一个错误到 `/gsd:quick`，想法到 `/gsd:add-phase` / `/gsd:explore`），未完成的 UAT 成为 `/gsd:next` 中的一个硬不变量（在任何进一步路由之前恢复），而中断本身会留下一个“↩ 恢复 UAT”的导航线索。 - **覆盖门控自动恢复而不是询问。** 当决策/需求覆盖门控发现一个实现决策的计划但没有字面标记时，GSD 现在会回填 `(D-NN)` /REQ-ID 标签并默默继续（计划检查者已经确认工作已覆盖）。 只有在 *没有* 计划中实现的决策才会以纯语言显示，并建议修复。 - **精简 `/gsd:version`** — 内联且无节点依赖，因此即使节点损坏也能正常工作。 **v3.6.3**：UI-SPEC 门控现在遵守 `auto_advance`（默认为开启）。 对前端阶段的手动 `plan-phase` 会自动生成 UI 设计合约并继续，而不是以“运行 `/gsd:ui-phase` 然后重新运行”的门控结束。 `--no-auto` / `--skip-ui` 保留手动路径，而 `/gsd:ui-phase` 仍然用于交互式设计会话。 **v3.6.2**：更正“如何更新”的说明（`/plugins` 市场刷新流程，在 README 和 `/gsd:version` 中），并使 `/gsd:version` 更精简，与节点无关，因此即使节点损坏也能正常工作。 **v3.6.1**：修复 `/gsd:profile-user` 和 dev-preferences 安装失败，提示“模板未找到”（捆绑的 SDK 在一个过时的嵌套路径下解析模板），并使新项目默认的 `commit_docs` 在 CJS 和 SDK 解析器之间保持一致。 **v3.6.0**：**减少 GSD 维护提示。** GSD 现在只会在关于你正在构建的内容的决策上打断你，而不是其自身的管道。 - **不再有确认提示。** 以前确认建议的流程提示现在会自动跟进（已宣布，并带有每次运行的退出路径）：“研究第一（推荐）？” 门控，讨论阶段的“准备好获取上下文？” 门控，以及大约 8 个问题的新项目设置严酷考验（现在提供单个“使用推荐默认值”的门控）。 构建和设计提示仍为交互式。 - **默认自动继续，上下文感知。** `auto_advance` 现已默认开启：廉价阶段（<=2 个计划）会无手干预地从计划流到执行；大型阶段会暂停以便 `/clear` 交接（干净的上下文和实时波检查点）。 discuss 到 plan 仍为交互式。 `--no-auto` 退出每个运行。 - **间隙自动路由，按严重程度。** 验证间隙如果破坏阶段目标会自动升级到间隙关闭；仅限小间隙会自动停放到后台，并附带“如何处理这些间隙？”的提示。 最近：v4.0.0 添加了约定一致性门控、本机漂移检测和第二个上游（VibeDrift），并将插件移到了其自己的版本号；v3.7.0 添加了会话恢复能力。 完整的历史记录在 [CHANGELOG.md](./CHANGELOG.md) 中。 > ### 上游更改（2026 年 5 月） > > 2026 年 5 月，原 GSD 维护者 TÂCHES（Lex Christopherson）变得无法联系，删除了他的社交账户，相关的 `$GSD` Solana 代币被公开链接到一个拉毯子（参见外部报道： [intellectia.ai](https://intellectia.ai/news/crypto/gsd-token-allegedly-rugpulled-after-founder-exit)， [ourcryptotalk](https://ourcryptotalk.com/news/bags-hackathon-winner-gsd-cloud-rug-pull)）。 > > 2026-05-22，GSD 协作者 [trek-e](https://github.com/trek-e) 启动了一个社区继续在 [open-gsd/get-shit-done-redux](https://github.com/open-gsd/get-shit-done-redux)：相同的 MIT 许可代码，所有 394 个分支和 229 个标签按位镜像，没有代币引用。 [迁移公告](https://github.com/open-gsd/get-shit-done-redux/discussions/109) 详细说明了下游消费者发生的变化。 原始的 `gsd-build/get-shit-done` 现在已锁定并自动关闭新的问题和 PRs。 > > 此插件从 `v2.43.6` 开始将 `open-gsd/get-shit-done-redux` 视为上游。 代码在切换时没有更改（redux 与预拉 rug 树完全相同）；只有 URL 和 npm 包名称发生了变化。 有关 [版本控制](#versioning) 和 [Credits](#credits) 的历史关系，请参见。 ## GSD 插件提供的内容 - **82 个斜杠命令** (`/gsd:*`) 用于项目规划、执行、调试和验证 - **33 个代理定义** 用于专门的工作流角色（计划器、执行器、研究人员、验证器等） - **85 个工作流主体** 在 `workflows/` 中：操作逻辑，技能通过 `@${CLAUDE_PLUGIN_ROOT}/workflows/<name>.md` 委托 - **MCP 服务器** 将项目状态公开为可查询的资源和突变工具 - **钩子** 用于会话启动上下文加载、工作流强制、compact 上的检查点和工具使用监控 - **跨 `/compact` 自动恢复**：PreCompact 钩子写入 `.planning/HANDOFF.json`；在下一个会话启动时，SessionStart 钩子检测到交接并自动调用 `/gsd:resume-work`，无需用户干预。 CLAUDE.md 带有相同的指令，作为 CLI 中钩子不触发的备用。 - **执行上下文配置文件** （dev、research、review）用于角色特定的行为 - **模板和引用** 用于规划工件、摘要、验证检查清单和思维模型指导 - **内存集成**：阶段结果通过 Claude Code 的 memdir 在会话之间持续存在 ## 会话连续性和漂移恢复能力 **会话连续性。** 当 Claude Code 运行 `/compact`（手动或自动）时，此插件的 PreCompact 钩子捕获当前会话状态到 `.planning/HANDOFF.json`：阶段、计划位置、未提交的文件、最近的决策和恢复提示。 在下一个会话启动时，SessionStart 钩子检测到交接并自动调用 `/gsd:resume-work`，无需用户干预。 CLAUDE.md 带有相同的指令，作为 CLI 中钩子不触发的备用。 交接文件在成功恢复后删除，因此过时的状态不会触发幻影恢复尝试。 **漂移恢复能力。** 插件位于 [上游 GSD](https://github.com/open-gsd/get-shit-done-redux) 下游，该上游 GSD 提供了频繁的功能发布。 为了在用户收到之前捕获结构漂移，三个检测器在 CI 上每个推送运行：**文件布局漂移检测器** 标记悬空的 `@~/.claude/get-shit-done/*` 引用（例如，技能文件委派给不存在的工作流正文）；**HANDOFF 模式验证器** 确认 `checkpoint.cjs` 输出与提交的 JSON 模式一致；**命名空间漂移检查器** 如果任何 `/gsd-<skill>` 样式命令引用被重新引入，则会触发。 每个检测器都有一个提交的基准；回归会失败。 在每次上游同步后，会运行额外的 **上游模式漂移检测器** (`check-upstream-schema.cjs`)，将上游的 `/gsd:pause-work` 输出与我们的模式捕获早期漂移。 ## 新增功能 本插件以 GSD 的源代码为起点，但添加了 GSD 原始设计中无法实现的功能。如果您想了解本插件与 GSD 有什么不同，以下是主要功能： | 功能 | 描述 | 命令 / 钩子 | |---------|--------------|----------------| | **原生偏移检测** (v4.0.0) | 全仓库范围内，零依赖检测重复逻辑、结构近克隆和幻影/存根代码，并带有可审计的允许列表。排名报告和可选的里程碑门槛。 | `gsd-tools verify drift`，`/gsd:scan --drift` | | **约定和架构一致性门槛** (v4.0.0) | 通过多数投票推导出项目的命名和架构约定，并标记偏离的已更改文件，在现有的审查路径中。永远不会阻止。 | `gsd-tools verify conventions`，与 pattern-mapper + code-review 联动 | | **每周插件自我更新监视** (v4.0.0) | 每周 cron 邮件通知您，当您的安装落后于最新标签时（Claude Code 自动更新不可靠）。永远不会失败 cron。 | `bin/check-plugin-update.sh`（cron，不是 GSD 命令） | | **VibeDrift 第二上游监视** (v4.0.0) | 监视 `@vibedrift/cli` 版本，以便其偏移启发式可以随着时间推移移植到本地。仅 cron 通知器；vibedrift 从未运行。 | `bin/check-vibedrift-release.sh`（cron，不是 GSD 命令） | | **改进的会话中断恢复能力** (v3.7.0) | 在会话中断/恢复时，中断的 UAT 不会丢失，覆盖率标记间隙会自动愈合，而不是询问您。 | `/gsd:next`，`workflows/plan-phase.md`，`workflows/verify-work.md`，`references/continuation-format.md` | | **减少 GSD 例行维护提示** (v3.6.0) | 橡皮图章过程提示会自动遵循其建议；`auto_advance` 是开启的，并且是上下文感知的；间隙会自动根据严重程度路由。构建/设计提示保持交互式。 | `workflows/plan-phase.md`，`workflows/discuss-phase/`，`workflows/execute-phase.md`，`workflow.auto_advance`，`--no-auto` | | **可靠的默认分支解析（不再有 main-vs-master 偏移）** (v3.4.11；修复后于上游) | 一个默认分支解析器（配置，origin/HEAD，`git remote show`，本地），因此 GSD 停止为不存在的 `main` 分支创建分支。 | `gsd-tools.cjs base-branch` | | **减少所有指令文档的令牌开销** (v3.4.10) | 从 173 个指令文件中修剪了约 1,810 行纯开销，行为不变（通过多代理压缩然后反驳管道验证）。 | （所有 `workflows/`，`skills/`，`agents/`，`references/`） | | **`/gsd:version` 命令** (v3.4.9) | 打印已安装的版本并检查 GitHub 标签以获取最新版本，仅在您落后时显示更新步骤。只读，永远不会失败命令。 | `/gsd:version` | | **Ultrcode 协调信号** (v3.4.8) | 一个信号，运行扇出友好命令（map-codebase，code-review，review）在最大多代理深度而不是其默认深度。 | `workflow.ultracode`，`references/ultracode-mode.md` | | **Claude Fable 5 层，自动回退到 Opus** (v3.4.4；于 2026-06-12 撤回) | 为最重的代理添加了一个 `fable` 模型层；由于 Fable 被撤回，它会自动回退到 `opus`，由可调的 `fable.mode`/`fable.until` 控制。 | `bin/lib/core.cjs`，`sdk/src/query/config-query.ts` | | **自动捕获临时决策** (v3.4.1) | `/gsd:quick`，`/gsd:debug`，`/gsd:fast` 在结尾时将临时决策保存到 Claude Code 内存中，以便上下文在里程碑之间存活。默认保守。 | `workflow.auto_memory_capture` | | **间隙自动路由按阻塞严重性** (v2.45.9；于 v3.6.0 自动) | 验证器 `gaps_found` 按严重性自动路由间隙：破坏目标的间隙升级到后续阶段，次要间隙进入后台。无提示。 | `workflows/execute-phase.md`，`agents/gsd-verifier.md` | | **将文档修正到工作提交** (v2.45.7) | `/gsd:quick` 将 PLAN/SUMMARY/STATE 折叠到前面的工作提交中（每个任务一个提交，而不是两个），在不安全时回退到单独的提交。 | `workflows/quick.md` | | **执行者自我测试偏差** (v2.45.6) | 推动执行者进行自动化自我检查，而不是打断您的 `human-verify` 提示。 | `agents/gsd-executor.md` | | **用户文档术语拉链** (v2.45.4) | 在提交时和 CI 中捕获用户文档中的 GSD 术语泄漏（原始路径，计划 ID，“阶段 N”散文），针对基线。 | `bin/maintenance/check-user-docs-jargon.cjs` | | **默认 Opus 提升到 `claude-opus-4-8`** (v2.45.1) | 在 Anthropic 兼容运行时，将 `opus` 解析为 `claude-opus-4-8`。Sonnet 和 Haiku 不变。 | `sdk/shared/model-catalog.json` | | **文档驱动开发模式** (v2.44.0) | 与新项目类似：编写用户文档 `docs/SPEC.md`，验证它，然后从其章节中推导出阶段。最适合 CLI，库，API。 | `/gsd:new-ddd` | | **身份验证配方内存** (v2.44.5) | 通过带有秘密删除的钩子检测身份验证命令（gh/aws/ssh，凭据环境变量）；将它们提升为可重用的每个项目或跨项目配方。 | `/gsd:remember-access` | | **自动批准非关键工件** (v2.44.4) | 放弃对 ROADMAP/SPEC 草稿的 AFK 阻止提示（记录以供审查）；真正的风险，如验证间隙仍然提示。 | `workflow.auto_approve_non_critical` | | **计划恢复** | 在设定的时间（`HH:MM`，ISO，或 `+2h`）安排未来的 Claude Code 会话以自动运行 GSD 命令。适用于配额窗口。 | `/gsd:resume-at <time>` | | **跨 `/compact` 自动恢复** | 在压缩时，写入 `HANDOFF.json`，下一个会话自动运行 `/gsd:resume-work`，无需手动输入。 | PreCompact + SessionStart 钩子 | | **会话中检查点** | PostToolUse 钩子在大多数工具调用后（限流）写入一个新的检查点，涵盖 Claude Code 的无声微压缩间隙。 | PostToolUse 钩子 | | **插件版本变更回退** | 如果插件在运行中更新，钩子通过回退到最新的缓存版本来解决，只要长时间会话存活。 | 钩子命令解析器 | | **CI 强制偏移检测** | 三个 CI 检测器（文件布局，HANDOFF 模式，命名空间）带有拉链基线，硬失败于回归。 | `bin/maintenance/check-drift.cjs` | | **92% 每转令牌减少** | 技能主体在 `context: fork` 子代理中运行，状态使用 MCP 代替 CLI 往返，保持父上下文清洁。 | 插件架构 | | **插件本地工作流主体** | 所有 85 个工作流主体都在插件中提供，并通过 `${CLAUDE_PLUGIN_ROOT}` 解析，而不是在丢失时无声失败的全局目录。 | `workflows/` 目录 | | **标准化继续提示** | 6 个终端技能发出“下一步”块，带有 `/clear`-then-next 建议和一个安全的清除页脚。 | 所有终端技能 | | **跨会话内存** | 阶段结果通过 Claude Code 的 memdir 持续存在，并在会话开始时自动回忆（上游从冷启动开始）。 | 内置 | 有关实现细节，请参阅下面的 [GSD 上游用户](#for-users-of-upstream-gsd) 中的深入表格。 ## 维护脚本 `bin/maintenance/` 目录中包含用于插件维护任务的轻量级 Node 脚本，这些任务不是用户界面 CLI 的一部分。 - `node bin/maintenance/check-file-layout.cjs`：**文件布局偏移检测器。** 扫描插件内容中的 `@~/.claude/get-shit-done/*` 引用，将每个分类为可修复（插件具有本地对应项）或真正缺失，并将计数与 `tests/drift-baseline.json` 进行比较。如果偏移量超过基线，则退出非零。在每次推送和拉取请求时在 CI 中运行。传递 `--dry` 以预览或 `--write-baseline` 以在有意减少后重新生成基线。 - `node bin/maintenance/rewrite-command-namespace.cjs`：**命名空间规范化。** 在插件内容中将 `/gsd-<skill>` 重写为 `/gsd:<skill>`。在上游 GSD 同步后运行，因为上游使用短横线形式。 - `node bin/maintenance/check-handoff-schema.cjs`：**HANDOFF 模式验证器。** 通过 `bin/lib/checkpoint.cjs` 的 `writeCheckpoint()` 生成一个临时目录中的新鲜 `HANDOFF.json`，然后使用 ajv 将其验证为 `schema/handoff-v1.json`。不触摸真正的 `.planning/HANDOFF.json`；验证隔离到一个临时目录，该目录在 `finally` 块中被清理。在每次推送和拉取请求时在 CI 中运行（`.github/workflows/check-drift.yml` 中的第二个作业）。在模式有效时退出 0，在违规时退出 1，在环境错误时退出 2（ajv 丢失，不在仓库根目录等）。 - `node bin/maintenance/check-upstream-schema.cjs`：**上游偏移检测器。** 下载最新的上游 GSD 发布 tarball（或使用来自先前同步的缓存的 `/tmp/gsd-sync-<version>/` 目录），从 `get-shit-done/workflows/pause-work.md` 中提取声明的字段列表，然后将其与 `schema/handoff-v1.json` 进行比较。**不**在 CI 中运行；在每次上游同步后调用（手动或通过同步快速任务模板；参见 `.planning/PROJECT.md` “每次上游 GSD 同步后”的检查清单）。设置 `UPSTREAM_VERSION=v1.38.x` 以目标特定版本；否则默认为 `gh release view` 以获取最新标签。 - `node bin/maintenance/check-drift.cjs`：**统一偏移检查（伞形）。** 顺序运行文件布局，HANDOFF 模式和命名空间检测器，并报告综合通过/失败。适用于本地开发循环和上游同步后验证。不添加到 CI；CI 分别运行每个分类检测器以获得快速反馈粒度。上游模式检测器故意被排除（依赖网络+仅上游同步后）。 - `bash bin/maintenance/install-git-hooks.sh`：**安装本地预提交钩子。** 每个克隆的一次性设置。将 `.git/hooks/pre-commit` 链接到 `bin/maintenance/pre-commit-drift-baseline.sh`。钩子在功能提交添加新的跟踪工作流/技能/代理文件时自动重新生成 `tests/drift-baseline.json`。如果“真正缺失”回归（真正的偏移错误），则中止提交。覆盖每次提交：`git commit --no-verify`。幂等。 --- ## GSD 上游用户 如果您已经通过 `npx get-shit-done-cc`，`npx @opengsd/get-shit-done-redux` 或旧版 `~/.claude/get-shit-done/` 设置安装了 GSD，本节涵盖迁移到插件的内容。如果您是新用户，请完全跳过本节。 ### 上游 GSD 有何变化 本插件从 GSD 的源代码树开始，并添加了 GSD 原始设计中无法实现的功能。插件有意义地偏离的领域： #### 安装 + 运行时架构 | 方面 | 上游 GSD | 本插件 | |--------|-------------|-------------| | 安装 | `npx @opengsd/get-shit-done-redux`（或 pre-rug `get-shit-done-cc`） | `/plugin marketplace add jnuyens/gsd-plugin && /plugin install gsd@gsd-plugin`（在 Claude Code 中运行） | | 上下文开销 | ~3,000-5,000 令牌/回合通过 CLAUDE.md | ~200 令牌（92% 减少） | | 技能隔离 | 内联执行；编排提示污染父上下文 | `context: fork` 子代理隔离；编排在干净的子上下文中运行 | | 状态访问 | BashTool 往返到 `gsd-tools` CLI | MCP 资源 + 工具；结构化查询取代提示注入 | | 代理定义 | 技能主体中的内联提示角色描述 | `.claude/agents/*.md` 带有类型化前置信息（模型覆盖，工具限制，努力预算） | | 跨会话内存 | 无；每个会话从冷启动开始 | 阶段结果通过 Claude Code 的 memdir 持续存在；会话开始时自动回忆 | | 命令 ID | `/gsd-<skill>`（短横线；因为上游的平面安装中没有命名空间） | `/gsd:<skill>`（冒号；匹配 Claude Code 的插件命名空间，正确自动完成） | #### 会话连续性（上游没有这些） | 方面 | 上游 GSD | 本插件 | |--------|-------------|-------------| | `/compact` 行为 | 会话崩溃；阶段位置丢失；用户手动重新定向下一个会话 | **PreCompact 钩子** 编写一个 19 字段的 `HANDOFF.json`，捕获阶段，计划，任务，决策，未提交的文件。 **SessionStart 钩子** 在下一个会话中检测到它并自动调用 `/gsd:resume-work`，无需用户输入。 | | 会话中定期检查点 | 无；仅当用户手动 `/gsd:pause-work` 捕获状态 | **PostToolUse 钩子** 在大多数工具调用后（限流）写入新的检查点，涵盖 Claude Code 的无声 *微压缩* 路径和读重研究阶段。在意外会话结束（使用上限，杀死，网络掉线）后，HANDOFF 反映了从中断前约 60 秒的状态。 | | 无钩子环境 | 不适用 | **CLAUDE.md 备用部分** 带有相同的恢复指令，以便 CLI 无钩子支持（或钩子失败的会话）仍在下一个会话中触发恢复。 | | 移交生命周期 | 不适用 | `/gsd:resume-work` 在成功恢复后删除 `HANDOFF.json`，防止陈旧移交触发幻影恢复。 | #### 偏移恢复能力（CI 强制执行；上游没有） | 方面 | 上游 GSD | 本插件 | |--------|-------------|-------------| | 文件布局偏移 | 无；损坏的 `@` 包含静默运输 | **`check-file-layout.cjs`** 扫描插件内容中的悬空 `@~/.claude/...` 引用，将每个分类为可修复或真正缺失，对比提交的基线。在回归时 CI 硬失败。 | | HANDOFF 模式完整性 | 无；模式仅在上游的 `pause-work.md` 中作为散文存在 | **`schema/handoff-v1.json`**（JSON 模式草案-07，19 个字段）。 **`check-handoff-schema.cjs`** 在 CI 中验证 `writeCheckpoint()` 输出与模式。 **`check-upstream-schema.cjs`** 在同步后运行，以尽早捕获上游格式偏移。 | | 命名空间规范化 | 不适用；上游命令以短横线形式存在 | **`rewrite-command-namespace.cjs`** 在所有插件内容中将 `/gsd-<skill>` 重写为 `/gsd:<skill>`。在每次上游同步后运行；偏移由综合检查检测。 | | 统一偏移检查 | 无 | **`check-drift.cjs`** 伞式运行所有三个检测器。用于本地开发和上游同步后验证。 | #### 插件环境鲁棒性 | 方面 | 上游 GSD | 本插件 | |--------|-------------|-------------| | 会话中插件版本变更 | 不适用 | 钩子命令通过 Node 内联解析器解决，该解析器在烘焙的 `${CLAUDE_PLUGIN_ROOT}` 路径被修剪时（例如在另一个会话升级插件后）回退到最新的缓存插件版本。长时间会话在插件更新中幸存。 | | 工作流主体位置 | `~/.claude/get-shit-done/workflows/<name>.md`（旧安装目录；插件用户缺失 → 静默“回退到旧文件”失败） | **插件本地 `workflows/` 目录**，带有所有 78 个主体；技能 `@` 包含通过 `${CLAUDE_PLUGIN_ROOT}/workflows/<name>.md`，Claude Code 的插件加载器将其解析为版本戳安装路径 | | 流程结束继续提示 | 不一致；一些技能发出 `/clear-then-X` 块，许多技能不发出 | 标准化：6 个终端技能（`execute-phase`，`complete-milestone`，`verify-work`，`quick`，`plan-phase`，`ship`）根据 `references/continuation-format.md` 发出 Next Up 块，带有 `/clear-then-[next]` 和“/clear 是安全的”括号（恢复从 HANDOFF 中） | ### 安装后自动迁移 在安装插件后的第一个会话中，GSD 会自动迁移。这些更改可防止重复的斜杠命令、死亡的 MCP 条目和陈旧的钩子脚本： - **移动** `~/.claude/get-shit-done/` 到 `~/.claude/get-shit-done-legacy/`（安全备份，不删除） - **移动** `~/.claude/commands/gsd/` 到 `~/.claude/commands/gsd-legacy/`（防止重复斜杠命令） - **删除** 来自 `~/.claude/skills/` 的旧 GSD 技能目录 (`gsd-*`) - **删除** 来自 `~/.claude/agents/` 的旧 GSD 代理文件 (`gsd-*.md`) - **删除** 项目的 `.mcp.json` 中的旧 GSD MCP 服务器条目 - **删除** 来自 `~/.claude/settings.json` 的旧 GSD 钩子条目 - **删除** 旧钩子脚本 (`gsd-check-update.js`, `gsd-context-monitor.js`, `gsd-prompt-guard.js`, `gsd-statusline.js`) 来自 `~/.claude/hooks/` 您将在会话输出中看到已迁移内容的摘要。 ### 手动迁移步骤 自动迁移无法为您完成几件事情： #### 1. 安装插件 在克劳德代码提示中输入以下内容： ``` /plugin marketplace add jnuyens/gsd-plugin /plugin install gsd@gsd-plugin /reload-plugins ``` #### 2. 卸载全局 `get-shit-done-*` npm 包（现在安全 - v2.42.0+） ```bash npm uninstall -g get-shit-done-cc # pre-rug 包，可能仍安装 npm uninstall -g @opengsd/get-shit-done-redux # post-rug 包，如果您安装了它 ``` > **历史：** 本步骤的措辞已更改两次。版本 ≤ v2.41.0 告诉用户在插件仍需要该包的 `gsd-sdk` 二进制文件时卸载，这会默默地破坏每个 `/gsd:*` 命令 ([#4](https://github.com/jnuyens/gsd-plugin/issues/4))。v2.41.1 更正了 README 以“保留已安装”，直到 v2.42.0 将 SDK 捆绑在插件中，使其再次安全。rug 后的包名 (`get-shit-done-redux`) 在 v2.43.6 中添加。 如果您使用 **v2.42.0 或更高版本**，则插件的 `bin/gsd-sdk` 包装器在全局包装器被删除后接管；没有任何问题。如果您使用的是较旧的插件版本，请在升级插件之前保留全局包。 #### 3. 停止使用 `/gsd:update` `/gsd:update` 命令已弃用。通过 `/plugins` -> 市场 -> 选择 gsd-plugin 以刷新，然后 `/reload-plugins`（参见上面的更新部分）来更新。 #### 4. 清理备份（可选，在验证插件有效后） ```bash rm -rf ~/.claude/get-shit-done-legacy/ ``` ### 在不影响当前安装的情况下测试插件 如果您想在不影响现有 `~/.claude/get-shit-done/` 配置的情况下测试插件，请在隔离环境中运行： ```bash # 1. 将此存储库克隆到某个位置 git clone https://github.com/jnuyens/gsd-plugin.git ~/src/gsd-plugin # 2. 将旧安装移出（防止重复命令） mv ~/.claude/get-shit-done ~/.claude/get-shit-done-legacy # 3. 创建一个测试项目 mkdir ~/test-gsd-plugin && cd ~/test-gsd-plugin git init # 4. 使用插件根目录覆盖启动 Claude Code CLAUDE_PLUGIN_ROOT=~/src/gsd-plugin claude --dangerously-skip-permissions # 5. 在会话中，仅限插件 GSD 命令有效 ``` 测试完成后恢复旧安装： ```bash mv ~/.claude/get-shit-done-legacy ~/.claude/get-shit-done ``` `CLAUDE_PLUGIN_ROOT` 环境变量告诉插件的 `bin/lib/core.cjs` 从指定目录解析所有路径，而不是默认的插件缓存。 ### 回滚 在测试或完全迁移后恢复到上游 GSD： ```bash # 删除插件 claude plugin uninstall gsd # 您的旧 ~/.claude/get-shit-done/ 备份仍然存在并正常工作 # （或从 ~/.claude/get-shit-done-legacy/ 恢复，如果您已经切换） ``` 如果您想从旧备份切换到 post-rug 上游（`get-shit-done-redux`），请通过 `npx @opengsd/get-shit-done-redux@latest` 安装；它保留了 pre-rug 树中的所有提交/分支/标签，因此任何使用旧安装构建的 `.planning/` 目录都无需更改继续工作。 ### 迁移审计 检查迁移后是否遗留旧 GSD 工件： ```bash node bin/gsd-tools.cjs migrate ``` 这将打印在您的系统上发现的所有旧 GSD 工件。要删除它们（需确认）： ```bash node bin/gsd-tools.cjs migrate --clean ``` ### 验证迁移 迁移后，验证插件是否激活： 1. 启动新的 Claude Code 会话 2. 运行 `/gsd:help` -- 应该列出所有命令 3. 运行 `/gsd:progress` -- 显示项目状态（或提示创建） 4. 检查 MCP 资源是否可用（GSD MCP 服务器应该通过插件清单自动启动） ## 上游项目 gsd-plugin 依赖于三个上游项目，但方式不同：它 **打包** 一个，**移植理念** 自另一个，并 **实现格式规范** 的第三个。没有任何运行时依赖：插件捆绑了它需要的一切。 **1. GSD（`@opengsd/gsd-core`）：主要上游。** 这是插件打包和优化的工作流引擎。插件从 gsd-core 的源代码树（阶段/计划/执行/验证生命周期、代理、SDK）开始，并在其上添加了 Claude-Code 特有的功能：通过 `context: fork` 实现技能隔离、MCP 支持的项目状态、跨会话内存、跨 `/compact` 自动恢复，以及减少令牌开销。从 gsd-core 中选择性地挑选内容，而不是完整的供应商同步，并且 `bin/check-gsd-release.sh` 监视 gsd-core 的新版本。出处：gsd-core 是 [open-gsd/get-shit-done-redux](https://github.com/open-gsd/get-shit-done-redux) 社区在 TÂCHES（参见上方的[上游变更](#whats-new)说明和[致谢](#credits)）原始 GSD 的继续。 **2. VibeDrift（`@vibedrift/cli`）：第二个仅理念上游。** 从 v4.0.0 开始，GSD 以与 gsd-core 相同的方式对待 VibeDrift：作为一个理念来源。但关系故意保持较窄。GSD **从不安装或运行 VibeDrift**。相反，它移植 VibeDrift 的漂移检测启发式（此版本中的 MinHash+LCS 结构重复检测器是一个此类移植，其常量固定在 v0.14.0 想法基准上），并监视包的新版本（`bin/check-vibedrift-release.sh`），以便未来可以挑选启发式。这保持漂移检测 100% 原生和零依赖，同时仍然受益于 VibeDrift 的研究。VibeDrift 是一个理念来源，而不是运行时组件。 **3. workspace.json（`workspace-json/spec`）：一种被消费的格式规范。** gsd-plugin 是 [workspace.json 规范](https://github.com/workspace-json/spec) 的消费者实现：当存在符合规范的 `.agents/workspace.json` 文件时，插件在 SessionStart 时读取它，并将结构化的代码库智能（脆弱文件、框架、共同更改注释）注入模型的上下文中，严格的主要版本控制和提示注入净化。插件既不生成也不捆绑文件；它实现了开放规范的读取端，因此任何发出规范一致的 `workspace.json` 的工具都相互操作。集成由 [Qwynn Marcelle](https://github.com/qmarcelle) 贡献（参见[致谢](#credits)）。 这种多上游姿态是 v4.0.0 成为重大更新的原因之一：插件现在累积了大量的功能（一个约定一致性门控、原生漂移检测、一个完整性门控），这些功能在上游 GSD 中不存在，从第二个项目中提取理念，并实现了第三个项目的开放格式。参见[版本控制](#versioning)。 ## 版本控制 **v4.0.0** 及以后，插件版本是**其自己的版本线**。早期版本机械地跟踪 gsd-core（`plugin_major = gsd-core_major + 2`），但插件已经有足够的差异（第二个上游，加上没有上游等效的功能），以至于与 gsd-core 的主要版本耦合不再反映版本的含义。现在，主要版本更新信号**插件自己的重要里程碑**（大型功能集，与上游的差异），而不是 gsd-core 的主要版本。 ``` plugin_major = 插件自己的里程碑线 （4.x = 分歧后时代） plugin_minor = 该线上的功能版本 plugin_patch = 功能版本之间的插件修复 ``` 为了溯源，每个版本仍然记录它遵循的 gsd-core 版本（此 `4.0.0` 版本遵循 gsd-core `1.x` 版本线；参见“基于”标题和 `bin/check-gsd-release.sh`），但版本号不再同步。如果 gsd-core 达到其自己的主要版本（2.0），则在版本说明和选取日志中记录，而不是强制进入插件的主要版本。 **历史：**原始 `gsd-build/get-shit-done` 1.x 版本线在 `+1` 处跟踪（插件达到 `2.45.x`）。在上游移动到 `@opengsd/gsd-core` 并在 `1.x` 处重启后，`+2` 偏移量重新对齐了小版本，同时保持在先前的 `2.x` 版本线之上，从而产生了 `3.x` 系列。v4.0.0 完全淘汰了偏移量方案，转而采用独立版本线。 **关于 v3.7.2 → v4.0.0 跳跃的说明：** 此主要版本更新是**分歧信号，而不是破坏性变更**。对于用户来说，没有破坏性变更：现有的命令、配置和规划工件无需更改即可工作，新增功能（漂移检测、完整性门控）是附加且需选择加入的。像对待任何版本更新一样进行更新。 该项目将 GSD 工作流系统重新包装为原生 Claude Code 插件，并具有额外的优化：通过 `context: fork` 实现技能隔离，用结构化的 MCP 工具取代提示注入，以及通过 memdir 实现跨会话内存。 ## 致谢 - **GSD（Get Shit Done）** by TACHES（Lex Christopherson）-- 本插件基于的原始工作流框架。原始存储库在 [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) （2026 年 5 月在创始人 rug-pulled 关联的 `$GSD` 代币并删除他的账户后锁定）。 - **[open-gsd/get-shit-done-redux](https://github.com/open-gsd/get-shit-done-redux)** by [trek-e](https://github.com/trek-e)（Tom Boucher）and contributors -- 位元完美的社区继续托管后续代码库。 - **[workspace.json 规范](https://github.com/workspace-json/spec)** -- 开放的代码智能格式，gsd-plugin 在 SessionStart 时读取；消费者集成由 [Qwynn Marcelle](https://github.com/qmarcelle) 贡献。 - Jasper Nuyens 负责插件打包、MCP 集成、令牌优化和内存系统。 ## 许可证 MIT