jaaty/dsh-gsd-bundle

dsh-gsd-bundle
CI License npm version

一个 DeepSeek Harness（dsh）的插件包，将 opengsd-core —— Git Ship Done (GSD) —— 重新实现为一组宿主平面 Cordis 插件。它用 GSD 阶段循环替换默认的 agent-loop 行为，使每个会话都成为一个有纪律的、以产物驱动的工程循环。

Spec → Discuss → (UI design, optional) → Plan → Execute → Verify → Ship

每个工作单元都是一个阶段（phase），按顺序经过这些步骤，并由建议性软门禁包裹（Plan 之后的 gap-analysis，Execute 之后的 code-review 和 UI-review，Ship 之前的 validate）。状态在会话之间和上下文重置后仍保留在磁盘上的 .planning/ 目录中，以 STATE.md 作为导航主干。繁重的工作（研究、规划、执行、验证、审查）由编排器生成的全新上下文子代理运行，因此主会话保持精简。

发布状态

里程碑 core-loop-helpers v3.1 已完成并作为 v3.1.0 发布 —— 这最后的 8 阶段增量（阶段 52–59）完成了该插件包与上游 opengsd-core 命令面的对等：阶段管理、智能入口、自由形式路由、快速批处理、快速模式、MVP 范围界定、有界节点修复，以及重建的代码审查修复配套工具。它紧随 v3.0 upstream-parity 里程碑之后，后者带来了完整的上游步骤面（spec、gap-analysis、code-review、UI-review、validate、undo、health、milestone-audit、learnings、graphify、mempalace、assumption-delta、pause/resume-work、autonomous、add-tests，以及直接的阶段分支 clean-PR 模型）。更早的 v2.2 public-launch、v2.1 public-release-readiness、v2.0 graceful-removal 和 v1.7 job-intel-multiwindow 里程碑仍为之前的发布版本。如今的表面：28 行 Cordis 插件（1 个覆盖 + 27 个插入）、37 个 gsd_ 工具，以及 34 个 /gsd- 命令 —— 全部由挂载和逐插件移除测试套件验证。

v3.1 发布说明 —— core-loop-helpers

v3.1 里程碑新增了八个核心循环辅助命令，完成了阶段循环工具面。它交付了：

- 阶段管理 —— gsd_phase（/gsd-phase-manage）：直接在 ROADMAP.md 中添加、插入、移除、重排和编辑阶段，并带有验证和完整性检查；ROADMAP.md、其 ## Progress 表以及 STATE.md 进度保持一致并原子提交。
- 智能入口 —— gsd_next（/gsd-next）：检测当前项目状态并路由到最佳下一步操作，带有自动推进选项。
- 自由形式路由 — gsd_route（/gsd-route）：解析纯英文意图并将其分派到最合适的 GSD 命令——仅推荐；绝不自动运行。
- 快速批处理 — gsd_quick_batch（/gsd-quick-batch）：在单个批次中运行多个快速任务，提供每任务结果和故障隔离。
- 快速模式 — gsd_fast_mode（/gsd-fast-mode）：针对简单阶段的轻量级单遍快速路径（自动推导 CONTEXT → 执行 → 总结 → 验证 → 交付）。
- MVP 阶段 — gsd_mvp_phase（/gsd-mvp-phase）：一种交互式的先提议后确认的范围界定流程，生成真实的 PLAN.md 并委托给常规循环；拒绝已完成的阶段，且失败时绝不自动重试。
- 节点修复 — gsd_repair（/gsd-repair）：针对验证返回缺口的阶段进行有界自动恢复——最多 2 轮 gsd_plan --gaps → gsd_execute --gaps-only → gsd_verify --gaps，并以明确原因停止；写入 -REPAIR.md。
- 审查修复配套工具 — 基于有界锚点编辑契约重建的 gsd_code_review --fix 配套工具：每次修复的原子提交带有真实提交哈希、跳过并继续的故障隔离、写入前的 node --check 解析门禁，以及在实时会话中可用的 REVIEW-FIX.md 报告。

v3.0 发布说明 — 上游对等

v3.0 里程碑使该捆绑包与上游 opengsd-core 的阶段循环和步骤表面完全对等。它交付了：

- 规格阶段 — gsd_spec_phase：一个规格步骤，生成带有可证伪的 Current/Target/Acceptance 需求的 SPEC.md，并由歧义评分门禁把关（在四个加权清晰度维度上 ≤ 0.20）。
- 缺口分析 — gsd_gap_analysis：一个规划后覆盖工具，输出确定性的 REQ-ID/D-ID 与计划正文覆盖表（-COVERAGE.md）。
- 代码审查 — gsd_code_review：一个执行后审查环节，生成带有严重性分类发现（BLOCKER/WARNING/INFO）的 REVIEW.md。
- UI 审查 — gsd_ui_review：一次追溯性的 6 支柱 UI 审计，生成 UI-REVIEW.md（总分 /24）。
- 验证阶段 — gsd_validate_phase：一次追溯审计，将每个阶段需求映射到测试基础设施，分类为 COVERED/PARTIAL/MISSING/Manual-Only（-VALIDATION.md）。
- 撤销 — gsd_undo：通过 git revert 的安全回滚路径，带有依赖检查和默认试运行的确认门禁。
- 健康检查 — gsd_health：.planning/ 完整性诊断（阶段/计划编号、孤立 SUMMARY、STATE/ROADMAP 不一致），并带有非破坏性的仅配置修复。
- 里程碑审计 — gsd_milestone_audit：里程碑关闭门禁，汇总各阶段验证，外加跨阶段 UAT 未完成事项列表。
- 经验教训 — gsd_extract_learnings：跨阶段经验教训提取，汇入可延续的 .planning/LEARNINGS.md。
- 图谱化 — gsd_graphify：在 .planning/graphs/ 中构建项目知识图谱，具有构建/查询/状态模式。
- Mempalace — 跨会话记忆捕获/召回（参见 Mempalace）。
- Assumption-delta — 一个接入 gsd_plan（plan:pre）的咨询式架构检查点：当某个阶段将原本单一/必需/派生的事物变为复数/可选/可选定时，它会浮现一个身份模型问题（提升 vs 并列添加）。由 workflow.assumption_delta 控制；纯确定性扫描，绝非 LLM 判断。
- Pause-resume-work — gsd_pause_work / gsd_resume_work：结构化的阶段中期上下文交接（HANDOFF.json + 一个 .continue-here.md 指针，作为 WIP 提交进行提交）及其恢复对应项。
- Autonomous — gsd_autonomous：端到端驱动活动里程碑中每个剩余未完成阶段（每个阶段 discuss → plan → execute → verify），无需逐阶段手动提示；遇到硬失败即停止，绝不发布。
- Add-tests — gsd_add_tests：一个测试生成器，根据已完成阶段的 SUMMARY/CONTEXT/VERIFICATION 及实现为其创建单元/集成测试，并以原子方式提交（-ATEST.md）。
- Drop-clean-branch — gsd_ship 现在直接推送并 PR 阶段- 分支（每个阶段一个分支）；不再构建单独的干净审查分支。

v2.2 发布说明 — 公开发布

v2.2 里程碑使 GSD 包可供 npm 发布，并让其健康状况一目了然。它交付了：

- 来源/健康徽章行 — README 现在在 H1 正下方带有一行三个可点击徽章：整个 CI 工作流状态、MIT 许可证，以及静态固定到已发布版本的 npm 版本徽章。
- 仓库可发现性 — 配置了仓库主题和 homepage，使该包在 GitHub 和 npm registry 上可被找到。
- 随包发布 README 链接的文档 — 扩展了 npm files 白名单，以在包中发布 DISTRIBUTION.md、CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 CHANGELOG.md。
- 安全 + 贡献界面 — 添加了 SECURITY.md 和 GitHub issue/PR 模板，使仓库为外部贡献者做好准备。
- 以 v2.2.0 发布 — @dsh-gsd/bundle 包已发布，带有完整的 npm 元数据（repository、homepage、bugs、keywords、engines、author）。

v2.1 发布说明 — 公开发布就绪

v2.1 里程碑强化了 GSD 包以准备公开发布——许可与署名、仓库卫生、CI 与安全、分发研究，以及一个确定性的发布前验证门。它交付了：

- 许可与署名 — 添加了 MIT LICENSE，在 NOTICE 中验证了 opengsd-core 署名和许可证合规性，并修复了 README 中损坏的 opengsd-core 引用。
- 仓库卫生 — 添加了 CHANGELOG.md、CONTRIBUTING.md 和 CODE_OF_CONDUCT.md，并应用了 .planning/ 保留 vs gitignore vs 整理的决策。
- Ci-and-security — 添加了一个 GitHub Actions 测试工作流（.github/workflows/ci.yml），在拉取请求和推送到 main 时运行测试套件，提交了 package-lock.json 以实现可复现的 npm ci 安装，并添加了一个 gitleaks 密钥扫描防护，如果引入新密钥则使 PR 失败。
- Publish-research — 针对该 bundle 的基于研究的发布决策，记录在 DISTRIBUTION.md 中。
- Pre-ship-verify — 在 gsd_ship 中新增了一个确定性的发布前验证门禁，在推送前于仓库的临时副本中运行 npm ci + npm test，可通过标志跳过。

v2.0 发布说明 — graceful-removal

v2.0 里程碑证明了整个 GSD 插件 bundle 是可替换且可定制的——每个步骤插件都可以被移除，而循环仍能继续工作。它交付了：

- Capability-services — 每个步骤插件发布一个能力服务，声明它所提供的循环步骤；persona 和斜杠命令层对它们所需的能力声明 coeffects。
- Reactive-loop-rendering — persona、运行时上下文快照和 gsd_status 根据可用的步骤能力重新渲染，因此缺失的步骤会被跳过，且绝不会指示不存在的工具。
- Removal-verification — 一个自动化的逐插件移除测试，证明每一个步骤插件都可以被移除、其效果被还原，而剩余的循环仍能端到端正常工作。
- Composability-hardening — 后台作业实时注册表的作用域限定在其所属 fiber 上，因此卸载/HMR 会取消正在运行的作业，并且 subagents coeffect 在每个消费插件中都有声明，因此时间与空间可组合性对作业运行时和 subagent 路径均成立。

功能

阶段循环，作为面向模型的工具：

- Spec → Discuss → (UI) → Plan → Execute → Verify → Ship — 每个步骤都是一个工具：gsd_spec_phase（可选的、可证伪的 SPEC.md）、gsd_discuss（CONTEXT.md）、gsd_ui_phase（UI-SPEC.md）、gsd_plan（researcher → planner → plan-checker，依赖波次）、gsd_execute（全新上下文的执行器、原子提交、检查点恢复）、gsd_verify（VERIFICATION.md + 状态路由）、gsd_ship（预检、能力门禁、发布前验证、PR）。
- 围绕循环的咨询性软门禁 — gsd_gap_analysis（计划后覆盖表）、gsd_code_review（REVIEW.md，附带一个可选的 --fix 配套工具，将发现的问题以每次修复一个原子提交的方式应用到 REVIEW-FIX.md 中）、gsd_ui_review（6 支柱 UI 审计）、gsd_validate_phase（需求→测试覆盖审计）。每个都由其各自的 workflow. 配置标志控制，且绝不会阻塞下一个循环步骤。
- 有界自动恢复 — gsd_repair 针对验证发现缺口的阶段，最多运行 2 轮 plan(gaps) → execute(gaps-only) → verify(gaps)，对于任何无法恢复的情况，会以明确的原因停止。
- 自主路径 — gsd_autonomous 端到端驱动活动里程碑中所有剩余未完成阶段（在缺失时自动推导 CONTEXT），并报告每个阶段的 STATUS；它在硬失败时停止，绝不发布，也绝不运行里程碑生命周期。
- 定位辅助工具 — gsd_init、gsd_status、gsd_progress、gsd_next（状态检测 + 下一步行动路由，支持自动推进）、gsd_route（仅建议的纯英文意图分派）、gsd_progress 和 gsd_new_milestone。
- 低于阈值的快速路径 — gsd_quick 用于单轮任务，另有 gsd_quick_batch 用于带故障隔离的批量任务，gsd_fast_mode 用于简单阶段，gsd_mvp_phase 用于先提议后确认的最小可行范围界定。
- 阶段管理 + 带外工具 — gsd_phase（添加/插入/移除/重排/编辑阶段，并带有 ROADMAP/STATE 完整性检查）、gsd_undo（带依赖检查的 git-revert 回滚）、gsd_health（.planning/ 完整性诊断）、gsd_pause_work / gsd_resume_work（阶段中途交接 + 恢复），以及 gsd_intel_updater（对漂移路径进行有针对性的代码库地图重新映射）。

里程碑收尾与记忆：

- 里程碑审计、经验教训、图谱化 — gsd_milestone_audit（收尾门禁审计报告）、gsd_extract_learnings（结转的 LEARNINGS.md）和 gsd_graphify（位于 .planning/graphs/ 的项目知识图谱，支持构建/查询/状态）。
- Mempalace — 可选的跨会话记忆：在讨论/规划前进行有意识的回忆（MEMORY-RECALL.md），并在阶段边界逐字捕获产物，通过可注入的 CLI 接缝实现。
- 添加测试 — gsd_add_tests 根据已完成阶段的产物为其生成单元/集成测试，并以原子方式提交。
- 假设增量检查点 — 当某个阶段将先前单一/必需/派生的概念泛化时，由 gsd_plan 浮现的一个很少触发的咨询性身份模型问题。

平台属性（继承自更早的里程碑）：

- 持久的 .planning/ 产物模型 — PROJECT.md、ROADMAP.md、REQUIREMENTS.md、STATE.md、config.json、各阶段产物、里程碑审计报告、代码库地图和知识图谱（见下方完整树状结构）。
- 检查点恢复与对话式 UAT — 被中断的 gsd_execute 从其最后一个检查点恢复；checkpoint:decision / checkpoint:human-action 任务会浮现一个面向人类的问题，计划在应用答案后继续。
- 能力门禁与发布前验证 — gsd_ship 在推送前运行安全 / 破窗 / TDD 审计门禁（带有 skip_gates 逃生舱），并在仓库的临时副本中执行确定性的 npm ci + npm test 验证。
- 真实后台作业运行时 — gsd_job 启动带超时、取消和重试的 shell/子代理作业；生命周期在 async-jobs.json 清单中跟踪，并通过 gsd_status 反映。
- 窗口台账 — 根级 WINDOWS.md 多窗口台账，通过 gsd_status 呈现。
- 棕地代码库映射 — gsd_map_codebase 使用并行的全新上下文映射器（7 个文档）分析现有代码库，针对映射回答 --query 问题，检测漂移，并通过 gsd_intel_updater 重新映射目标路径。
- 能力服务与响应式渲染 — 每个步骤插件都会发布一个能力服务；persona、运行时上下文快照和 gsd_status 会根据可用能力重新渲染，因此被停用或替换的步骤会被直接跳过。
- 可替换且可自定义 — 一套自动化的逐插件移除测试套件证明，每个步骤插件都可以被停用、其影响可被还原，且整个循环仍能端到端正常运行。
- 两种驱动式 UX — 自然语言（persona 让 agent 成为 GSD 驱动者）和 /gsd- 斜杠命令层。

前置条件

- DeepSeek Harness (dsh)，且 dsh CLI 在 PATH 中可用。
- Node.js ≥ 20（通过包的 engines 字段声明）。
- 一个 git 仓库，用于你想要用 GSD 驱动的项目（循环会以原子方式提交，并通过 gh CLI 提交 PR）。
- 如果你希望 gsd_ship 创建拉取请求，则需要安装并认证 GitHub CLI (gh)。

安装

关于基于研究的发行决策，请参阅 DISTRIBUTION.md。

将 bundle 添加到 dsh profile（它会叠加在 dsh-base 之后）。主要安装路径是 npm registry：

dsh plugin --profile  add @dsh-gsd/bundle
dsh --profile  web   # or tui / headless

替代方案 — 从源码安装

如果你更喜欢本地/git 检出而非 registry 包，请克隆此仓库并将 dsh plugin add 指向检出路径（pnpm 解析本地 spec 的方式与解析 registry 名称的方式相同）：

git clone https://github.com/jaaty/dsh-gsd-bundle.git
dsh plugin --profile  add
dsh --profile  web   # or tui / headless

bundle 的 cordis.patch.yml 会覆盖宿主 agent-loop 行，以配置一个 gsd agent，并插入 27 个 GSD 插件行。CLI profile 会获得 gsd 启动 agent；web 会话按需创建，并继承 GSD persona + 工具。

关于 peer 依赖： @deepseek-ai/dsh-tools 和 @deepseek-ai/dsh-llm 由 bundle 的模块直接导入。@deepseek-ai/schemastery 和 @deepseek-ai/cordis 是宿主契约 peer — 没有任何模块导入它们；声明它们是为了让 npm 安装兼容的宿主运行时，而宿主会在运行时通过注入的 ctx（tools/provide/get）提供它们。这两项声明都是有意为之。

快速开始

在已挂载 bundle 的 profile 上的会话中：

1. 引导 — gsd_init 创建 .planning/ 项目（名称、里程碑、需求、有序阶段）。
2. 定位 — gsd_status（或 gsd_next / /gsd-next）查看循环当前所处位置以及下一步该做什么。
3. 运行循环 — gsd_spec_phase（可选）→ gsd_discuss →（可选 gsd_ui_phase）→ gsd_plan → gsd_execute → gsd_verify → gsd_ship，需要时在步骤之间插入建议性软门禁（gsd_gap_analysis、gsd_code_review、gsd_ui_review、gsd_validate_phase）。

或者直接说 “让我们用 GSD 构建 X” —— 该 persona 已经让 agent 成为 GSD 阶段循环驱动者，在决策点暂停。你也可以直接驱动单个步骤：“规划阶段 1”、“执行阶段 1”、“验证阶段 1” —— 或者让 gsd_route 为一段纯英文意图推荐合适的命令。

gsd_ 工具

所有工具都由该 bundle 的插件注册，并在已挂载配置的任何会话中对模型可用（27 个插件共 37 个工具，已由挂载测试验证）。

定位与入口（gsd-core-tools）

| 工具 | 用途 |
|---|---|
| gsd_init | 引导创建 .planning/ 项目（名称、里程碑、需求、阶段）。 |
| gsd_status | 读取 STATE.md + ROADMAP.md；呈现循环位置、窗口和异步任务。 |
| gsd_progress | 各阶段的计划完成计数及下一步推荐操作。 |
| gsd_new_milestone | 开始新里程碑，并将其阶段追加到 ROADMAP.md。 |
| gsd_next | 检测当前项目状态并路由到最佳下一步操作，支持自动推进。 |
| gsd_route | 解析纯英文意图并将其分派到最合适的 GSD 命令（仅推荐）。 |
| gsd_pause_work | 阶段中途暂停：写入 HANDOFF.json + 一个 .continue-here.md 指针作为 WIP 提交。 |
| gsd_resume_work | 从 HANDOFF.json 恢复（或检测未完成的工作），并给出完整状态 + 下一步操作。 |
| gsd_job | 启动并管理后台 shell/subagent 任务（状态、取消、重试）。 |

循环步骤

| 工具 | 插件 | 用途 |
|---|---|---|
| gsd_spec_phase | gsd-spec | 生成可证伪的 SPEC.md（Current/Target/Acceptance），并以歧义分数 ≤ 0.20 作为门禁。 |
| gsd_discuss | gsd-discuss | 将阶段的 HOW 决策封存到 CONTEXT.md（7 个块、D-NN 决策、规范引用）。 |
| gsd_ui_phase | gsd-ui | 为具有视觉组件的阶段生成 UI-SPEC.md 设计契约。 |
| gsd_plan | gsd-plan | 研究 + 按依赖波次分解为有边界的 PLAN.md 文件（researcher → planner → plan-checker）。 |
| gsd_execute | gsd-execute | 使用全新上下文的执行器逐波运行计划，原子提交、检查点恢复、对话式 UAT。 |
| gsd_verify | gsd-verify | 验证目标是否真正达成；写入 VERIFICATION.md 并根据其状态进行路由。 |
| gsd_ship | gsd-ship | 预检 + 能力门禁 + 发布前验证，推送分支、创建 PR、将阶段标记为已发布。 |

建议性软门禁

| 工具 | 插件 | 用途 |
|---|---|---|
| gsd_gap_analysis | gsd-gap-analysis | 确定性的 REQ-ID/D-ID 与计划正文覆盖表（-COVERAGE.md），在 gsd_plan 之后运行。 |
| gsd_code_review | gsd-code-review | 全新上下文审查，生成 REVIEW.md（BLOCKER/WARNING/INFO）；fix: true 将发现的问题按每项修复原子提交应用到 REVIEW-FIX.md。 |
| gsd_ui_review | gsd-ui-review | 追溯性 6 支柱 UI 审计，生成 UI-REVIEW.md（总分 /24）。 |
| gsd_validate_phase | gsd-validate-phase | 需求→测试覆盖审计（COVERED/PARTIAL/MISSING/Manual-Only），写入 -VALIDATION.md。 |

修复与编排

| 工具 | 插件 | 用途 |
|---|---|---|
| gsd_repair | gsd-repair | 有界（≤ 2 轮）自动恢复：gsd_plan --gaps → gsd_execute --gaps-only → gsd_verify --gaps。 |
| gsd_autonomous | gsd-autonomous | 端到端驱动所有剩余未完成阶段；遇到硬失败即停止，绝不交付。 |

带外与收尾

| 工具 | 插件 | 用途 |
|---|---|---|
| gsd_phase | gsd-phase-management | 在 ROADMAP.md 中添加/插入/移除/重排/编辑阶段并进行验证；ROADMAP 与 STATE 保持一致。 |
| gsd_undo | gsd-undo | 通过 git revert 回滚某个阶段或计划的提交；默认试运行，带依赖检查。 |
| gsd_health | gsd-health | .planning/ 完整性诊断（默认试运行），仅进行非破坏性的配置修复。 |
| gsd_milestone_audit | gsd-milestone-audit | 里程碑收尾门禁，汇总各阶段验证结果 + 跨阶段 UAT 未完成项。 |
| gsd_extract_learnings | gsd-learnings | 将决策/经验/模式提取到每阶段的 -LEARNINGS.md + 结转的 LEARNINGS.md。 |
| gsd_graphify | gsd-graphify | 在 .planning/graphs/ 中构建/查询/检查项目知识图谱。 |
| gsd_add_tests | gsd-add-tests | 为已完成的阶段生成单元/集成测试并以原子方式提交。 |

入门、快速工作与记忆

| 工具 | 插件 | 用途 |
|---|---|---|
| gsd_map_codebase | gsd-map-codebase | 使用并行全新上下文映射器映射现有代码库 → .planning/codebase/（7 个文档）；还可回答 --query 问题。 |
| gsd_intel_updater | gsd-map-codebase | 对漂移的映射路径进行针对性重新映射（自动检测或显式指定）。 |
| gsd_quick | gsd-quick | 适用于小到不值得走完整循环的工作的低于阈值的轻量路径。 |
| gsd_quick_batch | gsd-quick | 在一批中运行多个快速任务，具有每任务结果和故障隔离。 |
| gsd_fast_mode | gsd-quick | 适用于简单阶段的轻量单遍快速路径。 |
| gsd_mvp_phase | gsd-quick | 先提议再确认的最小可行阶段范围界定，然后委托给正常循环。 |
| gsd_mempalace_recall | gsd-mempalace | 在讨论/规划之前进行有意回忆——从 MemPalace CLI 生成 MEMORY-RECALL.md。 |
| gsd_mempalace_capture | gsd-mempalace | 在阶段边界将 CONTEXT/PLAN/SUMMARY 逐字归档到 palace 中。 |

斜杠命令
gsd-commands 插件将 /gsd- 命令注册为轻量路由器——每个命令注入一条用户消息，告诉 agent 运行匹配的工具，然后返回一个简短的确认：

| 命令 | 工具 |
|---|---|
| /gsd-init [brief] | gsd_init |
| /gsd-status | gsd_status |
| /gsd-progress [phase] | gsd_progress |
| /gsd-next | gsd_next |
| /gsd-route  | gsd_route |
| /gsd-pause-work | gsd_pause_work |
| /gsd-resume-work | gsd_resume_work |
| /gsd-spec-phase  [--auto] | gsd_spec_phase |
| /gsd-discuss-phase  | gsd_discuss |
| /gsd-ui-phase  | gsd_ui_phase |
| /gsd-plan-phase  | gsd_plan |
| /gsd-gap-analysis  | gsd_gap_analysis |
| /gsd-execute-phase  [--wave N] [--gaps-only] | gsd_execute |
| /gsd-code-review  | gsd_code_review |
| /gsd-ui-review  [--mode=re-audit\|view] | gsd_ui_review |
| /gsd-verify-work  | gsd_verify |
| /gsd-validate-phase  [--auto] | gsd_validate_phase |
| /gsd-undo  [plan ] [--confirm] | gsd_undo |
| /gsd-health  [--repair] | gsd_health |
| /gsd-ship  | gsd_ship |
| /gsd-quick  | gsd_quick |
| /gsd-quick-batch  \|  \| ... | gsd_quick_batch |
| /gsd-fast-mode  | gsd_fast_mode |
| /gsd-mvp-phase  | gsd_mvp_phase |
| /gsd-repair  [--rounds 1\|2] | gsd_repair |
| /gsd-autonomous | gsd_autonomous |
| /gsd-add-tests  | gsd_add_tests |
| /gsd-phase-manage add\|insert\|remove\|reorder\|edit ... | gsd_phase |
| /gsd-map-codebase [--fast [--focus tech\|arch\|quality\|concerns\|tech+arch]] [--paths p1,p2] | gsd_map_codebase |
| /gsd-extract-learnings  [--force] | gsd_extract_learnings |
| /gsd-graphify build\|status\|query  | gsd_graphify |
| /gsd-mempalace-recall  | gsd_mempalace_recall |
| /gsd-mempalace-capture   | gsd_mempalace_capture |
| /gsd-new-milestone   | gsd_new_milestone |

例如 /gsd-plan-phase 1 路由到 gsd_plan；/gsd-ship 2 --draft 路由到 gsd_ship；/gsd-next 会在任意时刻告诉你最佳的下一步操作。

Mempalace（跨会话记忆）

gsd-mempalace 插件添加了一个跨会话记忆集成，它在 discuss/plan 之前执行刻意回忆，并在阶段边界处进行逐字捕获，通过一个可注入的 CLI exec 接缝与外部 MemPalace 服务通信。它是一个建议性软门控：它从不推进 STATE，也从不阻塞循环步骤——每个自动钩子都是 onError: skip，因此当 palace 不可达时会写入一个存根，循环继续。

两个工具：
- gsd_mempalace_recall({ phase }) — 执行刻意回忆（通过 MemPalace CLI 进行唤醒 + 搜索），并在 phase 目录中写入 MEMORY-RECALL.md，其中包含 Prior decisions / Patterns / Surprises 三个部分，每个条目都带有来源信息。当 CLI 无法访问时，它会写入一个 'unavailable' 存根，指明原生回退方案，然后继续执行。
- gsd_mempalace_capture({ phase, artifact }) — 通过暂存 + mempalace mine 将指定的 artifact（CONTEXT/PLAN/SUMMARY）逐字归档到相应的 palace room（decisions/planning/milestones）中。捕获是幂等的（基于内容哈希去重），并且绝不写入有损摘要。

自动钩子已接入循环工具，由 mempalace.enabled 及相关子键控制：在 discuss:pre / plan:pre 处回忆，在 discuss:post / plan:post / verify:post / ship:post 处捕获。独立工具保留用于手动调用。

配置面

通过 config.json 中的 mempalace.enabled 选择启用（默认 false —— 未设置时循环保持不变）：

| 键 | 默认值 | 含义 |
|---|---|---|
| mempalace.enabled | false | 整个插件的主选择启用开关。 |
| mempalace.memory_mode | "augment" | 回忆模式。augment 已完全实现：palace 是与原生记忆（.planning/graphs/、LEARNINGS.md、STATE）并存的附加回忆层，原生记忆仍保持权威。kg_backend 和 replace 在配置中被接受，但在本阶段被视为附加模式。 |
| mempalace.wing | "" | 用于回忆 / 挖掘的 MemPalace wing。回退到 project_code，然后是仓库目录名。 |
| mempalace.recall_on_discuss | true | 在 discuss:pre 处触发回忆。 |
| mempalace.recall_on_plan | true | 在 plan:pre 处触发回忆。 |
| mempalace.capture_artifacts | true | 在 phase 边界处触发捕获。 |
| mempalace.mirror_kg | true | 是否镜像知识图谱事实。注意： KG 镜像需要 MCP（mempalace_kg_add）—— 在此仅 CLI 的捆绑包中不可用；mirror_kg 在配置中被接受，但实际的 KG 写入在后续支持 MCP 的阶段之前是一个已记录的空操作。 |

工作原理

“替换默认 agent 循环插件”的含义

@deepseek-ai/dsh-agent-loop 中的机械式回合机器（工具调度、上下文组装、会话准备）保持不变 —— 那是 DeepSeek Harness 的核心运行时，没有它会话无法运行。该捆绑包替换的是 agent 循环的行为：

- cordis.patch.yml 覆盖宿主 agent-loop 行的 config（按行最后写入者胜出），将 agents: [] 替换为配置好的 gsd agent。
- gsd-persona 将 opengsd 的 phase-loop 心智模型安装为每个会话都会读取的系统提示词部分（顺序为 -100，位于部署 persona 之前），并提供一个运行时上下文贡献，使每个模型步骤都定位于当前的 STATE.md 位置。
- gsd_ phase 工具就是循环步骤。

插件
所有插件都是这一个包（@dsh-gsd/bundle/）的子路径导出，与随附预设使用的模式相同（例如 @deepseek-ai/dsh-tool-subagent-control/list-agents）。下表按补丁顺序列出了插入的 27 行（第 28 行是 agent-loop 覆盖）。

| 行 | 子路径 | 提供 / 注册 |
|---|---|---|
| gsd-persona | ./persona | systemPrompt 部分 gsd:persona + 上下文 gsd:state |
| gsd-state | ./state | gsdState 宿主服务 — .planning/ 产物 + STATE.md/ROADMAP.md/REQUIREMENTS.md 管理器、WINDOWS.md 台账、异步作业清单 |
| gsd-core-tools | ./core-tools | gsd_init、gsd_status、gsd_progress、gsd_new_milestone、gsd_next、gsd_route、gsd_pause_work、gsd_resume_work、gsd_job |
| gsd-discuss | ./discuss | gsd_discuss — 封存 CONTEXT.md（7 个块、D-NN 决策、canonical_refs） |
| gsd-spec | ./spec | gsd_spec_phase — 可证伪的 SPEC.md、歧义评分门禁 |
| gsd-plan | ./plan | gsd_plan — 研究员 → 规划器 → 计划检查器全新上下文子代理、3 次迭代修订循环；接入假设增量 plan:pre 检查点 |
| gsd-gap-analysis | ./gap-analysis | gsd_gap_analysis — 确定性的 REQ-ID/D-ID 与计划覆盖表 |
| gsd-execute | ./execute | gsd_execute — 基于波次的全新上下文执行器、原子提交、检查点恢复、对话式 UAT |
| gsd-code-review | ./code-review | gsd_code_review — REVIEW.md 发现 + --fix 锚点编辑配套工具 |
| gsd-ui-review | ./ui-review | gsd_ui_review — 6 支柱 UI 审计 → UI-REVIEW.md |
| gsd-verify | ./verify | gsd_verify — 验证器子代理 → VERIFICATION.md、状态决策树路由 |
| gsd-validate-phase | ./validate | gsd_validate_phase — 需求→测试覆盖审计 → VALIDATION.md |
| gsd-undo | ./undo | gsd_undo — git 回滚、默认试运行 |
| gsd-health | ./health | gsd_health — .planning/ 完整性诊断 + 非破坏性修复 |
| gsd-phase-management | ./phase-management | gsd_phase — 带完整性检查的 ROADMAP 阶段 CRUD |
| gsd-milestone-audit | ./milestone-audit | gsd_milestone_audit — 里程碑关闭门禁审计 |
| gsd-learnings | ./learnings | gsd_extract_learnings — 结转 LEARNINGS.md |
| gsd-graphify | ./graphify | gsd_graphify — 项目知识图谱 |
| gsd-mempalace | ./mempalace | gsd_mempalace_recall / gsd_mempalace_capture — 跨会话记忆 |
| gsd-autonomous | ./autonomous | gsd_autonomous — 端到端驱动剩余阶段 |
| gsd-add-tests | ./add-tests | gsd_add_tests — 为已完成阶段生成测试 |
| gsd-repair | ./repair | gsd_repair — 有界自动恢复轮次 |
| gsd-ship | ./ship | gsd_ship — 预检 + 能力门禁 + 发布前验证、PR 正文组装、gh pr create、STATE 更新 |
| gsd-ui | ./ui | gsd_ui_phase — UI-SPEC.md（ui-researcher + ui-checker） |
| gsd-quick | ./quick | gsd_quick、gsd_quick_batch、gsd_fast_mode、gsd_mvp_phase — 低于阈值 + 轻量路径 → .planning/quick/ |
| gsd-map-codebase | ./map-codebase | gsd_map_codebase（map + --query intel）和 gsd_intel_updater — 并行映射器 → .planning/codebase/（7 个文档） |
| gsd-commands | ./commands | /gsd- 斜杠命令 — 轻量路由器，注入一条用户消息，告知 agent 运行匹配的工具 |

扩展 bundle

我们鼓励你为自己的 bundle 编写自己的插件，并按需替换。每个插件都是该包的子路径导出（@dsh-gsd/bundle/），它发布一个能力服务，并通过 apply(ctx) 注册其工具/命令。要添加或替换一个步骤：

1. 按照相同的模式编写一个插件模块 — 一个 name、一个 inject 协效应列表，以及一个注册工具并发布能力的 apply(ctx)。
2. 在你的 cordis.patch.yml 中将其添加为一行，或覆盖现有行的 name 以指向你的模块。
3. 由于 persona、运行时上下文快照和 gsd_status 会根据可用能力响应式渲染，被停用或替换的步骤会被直接跳过 — 剩余的循环仍可继续工作。

自动化的逐插件移除测试套件证明了这一点：每个步骤插件都可以被停用，其效果被回滚，而循环仍能端到端正常运行。

.planning/ 产物（忠实于 opengsd-core）

.planning/
├── PROJECT.md
├── ROADMAP.md            里程碑 + 阶段表（#, Phase, Goal, Requirements）
├── REQUIREMENTS.md      编号的验收标准（REQ-ID）
├── STATE.md             YAML frontmatter（机器）+ Markdown 正文（人类），-AUDIT.md   里程碑关闭门审计报告（gsd_milestone_audit）
└── phases/-/
├── -CONTEXT.md          7 个块：domain、decisions（D-NN）、canonical_refs、code_context、specifics、deferred
├── -SPEC.md             可证伪需求 + 歧义评分（可选，gsd_spec_phase）
├── -RESEARCH.md         领域分析、包合法性、风险、开放问题、责任映射、验证架构；来源标签
├── --PLAN.md        YAML frontmatter（phase、plan、type、wave、depends_on、files_modified、autonomous、requirements、must_haves）+ // 正文
├── --CHECKPOINT.md  为恢复而持久化的检查点状态（last_completed_task、decision_id、human_answer）
├── --SUMMARY.md     执行记录（status: complete）
├── -COVERAGE.md         规划后 REQ-ID/D-ID 与计划的覆盖表（gsd_gap_analysis）
├── -REVIEW.md           代码审查发现（BLOCKER/WARNING/INFO）—— 以及来自 --fix 配套的 -REVIEW-FIX.md
├── -UI-REVIEW.md        6 支柱 UI 审计评分 + 发现（gsd_ui_review）
├── -VERIFICATION.md     frontmatter（status: passed|gaps_found|human_needed、score、gaps、human_verification）
├── -VALIDATION.md       需求→测试覆盖分类（gsd_validate_phase）
├── -ATEST.md            add-tests 生成器记录（gsd_add_tests）
├── -REPAIR.md           有界自动恢复记录（gsd_repair）
├── -UNDO.md             回滚记录（gsd_undo）
├── -HEALTH.md           .planning/ 完整性诊断（gsd_health）
├── -MEMORY-RECALL.md    MemPalace 召回会话（可选加入）
├── -UAT.md              持久化 UAT 会话状态
└── -UI-SPEC.md          UI 设计契约（可选）

= 零填充的阶段编号； = 阶段内零填充的计划编号。STATE.md frontmatter 携带 gsd_state_version、milestone、status、active_phase、next_action、progress 以及会话连续性字段，与 opengsd schema 匹配。

精心挑选，不要提交所有内容。 GSD 循环用于定位的持久产物——PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md、config.json、codebase/ 映射，以及每个阶段的 CONTEXT / RESEARCH / PLAN / SUMMARY / VERIFICATION 文档——都纳入 git 跟踪。易变的变动内容——async-jobs.json、WINDOWS.md、quick/ 记录，以及每个阶段的 DISCUSSION-LOG.md 文件——被 gitignore（参见 .gitignore）。这些易变文件保留在磁盘上（GSD 工具会持续写入它们），但不会被提交。由于持久子集会被提交，切勿将真实凭据或令牌粘贴到 .planning/ 产物中。

全新上下文子代理
研究、规划、执行、验证、审查和测试生成都作为一次性全新上下文子代理运行，通过宿主 subagents 服务的进程内 spawn 提供者启动（ctx.subagents.start('spawn', { prompt, parent, signal })）——正是 opengsd 的全新上下文模型。角色提示词（researcher、planner、plan-checker、executor、verifier、ui-researcher、ui-checker、codebase-mapper、code-reviewer、ui-auditor、add-tests-writer）忠实浓缩自 opengsd 的 agents/.md：角色、工具、输入、输出、planner 的目标回溯式 must_haves、plan-checker 的 12 个维度与对抗性 FORCE 立场、executor 的原子提交 + worktree 纪律、verifier 的“不要信任 SUMMARY.md”升级门禁及三值状态决策树，以及 codebase-mapper 的 focus→document 模板与禁止机密规则。

忠实性与范围

这是对 opengsd-core 的阶段循环与产物模式的忠实重新实现，而非其 CLI（gsd_run）或完整能力/门禁生态系统的移植。有意的简化：

- 没有按计划的 git worktree。 Executor 在共享工作树上运行。plan-checker 的同波次非重叠保证（维度 3）使共享树是安全的；合并后回归门禁变为按波次运行测试，而非 worktree 合并。

Clean-PR 分支

gsd_ship 直接推送阶段- 分支并为其创建 PR——每个阶段一个分支。PR 的 head 是当前的阶段- 分支（不会构建或推送单独的干净审查分支），完成状态提交落在阶段- 上，并且只推送到那里。用户对 PR 进行压缩合并，这已经在 main 上产生一个干净的提交。

- gsd_run 未被包装。 opengsd CLI 的 query/check/state 命令被重新实现为进程内的 gsdState 服务方法（没有单独的 gsd_run 进程）。
- 能力门禁被实现为一组聚焦的集合——security、broken_windows、tdd_audit——由 gsd_ship 在创建 PR 之前运行，并带有按门禁的通过/失败报告以及 skip_gates 逃生舱。更广泛的 opengsd 门禁生态系统（例如 ui.safety-gate）未被移植。
- gsd_map_codebase 的 --query 情报模式已实现（intel.enabled 能力生态系统——通过 .map-manifest.json 进行漂移检测、gsd_intel_updater 定向重新映射、结构化答案对象，以及子树 queryScope 作用域）。完整的并行映射、--fast 单焦点扫描和 --paths 增量重映射作用域均已实现；现有检查的交互式刷新/更新/跳过选择以 force / paths 参数形式呈现（工具无法持有多次往返的访谈）。
- 斜杠命令风格的标志（--gaps、--tdd、--mvp、--no-tracer、--granularity、--wave、--gaps-only、--auto、--confirm、--repair、--rounds、--force）作为工具参数和 /gsd- 路由器上的命令行标志暴露。
- 该捆绑包被刻意设计为可替换且可自定义。 每个步骤插件都会发布一个能力服务，而 persona / runtime-context / gsd_status 会根据可用能力进行响应式渲染，因此任何步骤插件都可以被停用（或替换），而剩余的循环仍能正常工作——这一点已由自动化的逐插件移除测试套件所证明。这是一种设计特性，而非限制。

用于构建此项目的参考是 opengsd-core 仓库。

状态

里程碑 core-loop-helpers v3.1.0 已完成并发布——五个里程碑的全部 59 个阶段均已交付（v1.7 job-intel-multiwindow、v2.0 graceful-removal、v2.1 public-release-readiness、v2.2 public-launch、v3.0 upstream-parity，外加八个 v3.1 辅助命令阶段）。挂载测试套件证明全部 28 行 Cordis 配置（1 个 override + 27 个 insert）按补丁顺序激活，并注册了 37 个工具 / 34 个命令 / 28 个能力服务，且 schema 均有效；移除测试套件证明每个步骤插件都可以被停用，而循环仍能正常工作；完整测试套件（1,100+ 个测试）在每次拉取请求和推送到 main 时都会在 CI 中运行，同时还有 gitleaks 密钥扫描防护。

贡献

欢迎贡献。请阅读 CONTRIBUTING.md 以了解开发环境搭建、如何运行测试套件、PR/贡献工作流，以及驱动本仓库的 GSD 阶段循环的简要说明。所有参与者都应遵守 CODE_OF_CONDUCT.md。发布历史请参见 CHANGELOG.md。请通过 SECURITY.md 报告安全漏洞。

测试套件通过 GitHub Actions 工作流（.github/workflows/ci.yml）在每次拉取请求和推送到 main 时于 CI 中运行，因此 PR 受到门禁控制，且 main 始终经过验证。gitleaks 密钥扫描防护也会在拉取请求上运行，如果引入了新的凭据或令牌，则会使该 PR 失败。

许可证

MIT