人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本文是 GSD 项目内部架构决策 ADR-008将 GSD 工作流工具契约通过 MCP 暴露为无法直接访问进程内工具注册表的 Provider 提供统一兼容层的完整实施计划解读。文章围绕 ADR-008-IMPLEMENTATION-PLAN.md 展开结合仓库中已落地的源码与测试说明 GSD 如何在不改变原生 Provider 行为的前提下让 Claude Code 等 MCP 客户端通过标准工具面完成 discuss/plan/execute/complete 全生命周期工作流。读完本文你将掌握 GSD 共享 Handler 抽取的架构思路、MCP 工作流工具面的最小工具集划分、安全护栏write-gate / discussion-gate在 MCP 路径上的等效力执行方式以及从 Spike 到端到端验证的六阶段落地节奏。一、背景为什么需要一套「传输无关」的工具契约GSD 仓库当前存在两套不同的工具面见 ADR-008-gsd-tools-over-mcp-for-provider-parity.md进程内扩展工具通过pi.registerTool(...)直接注册进运行时位于 db-tools.ts、query-tools.ts 等 bootstrap 模块是gsd_summary_save、gsd_plan_milestone、gsd_task_complete等核心工作流工具的唯一原生入口。外部 MCP 服务器server.ts 暴露的是 session 编排与只读项目检查工具gsd_execute、gsd_status、gsd_progress、gsd_roadmap等它不是内部工作流/变更工具的传输通道。由此产生一个真实的 Provider 兼容问题Claude Code CLI Provider 通过 stream-adapter.ts 使用 Anthropic Agent SDK但该适配器既不把内部 GSD 工具注册表转发进 SDK session也不为这些工具挂载 GSD MCP 服务器。结果就是prompt 要求模型调用gsd_complete_task工具在 GSD 中存在但 Claude Code session 里根本收不到这些工具——契约在传输层断裂。实施计划的根本目标是让工作流契约传输无关transport-neutralProvider 能访问原生工具就走原生路径访问不了就退回 MCP 工作流工具面两者共享同一份业务逻辑。二、目标、非目标与硬性约束目标Objective计划的首个可用成果被明确定义为Claude Code 驱动的执行会话可以使用规范canonicalGSD 工具完成任务不需要任何手动写 summary 的降级兜底原生 Provider 行为保持不变。非目标Non-Goals计划刻意排除了以下范围避免第一次 rollout 失控用 MCP取代原生进程内 GSD 工具在第一版就把所有历史别名全部导出在证明工作流工具面可行之前重构整个面向 session 的 MCP 服务器在 Claude Code 端到端跑通之前支持所有 Provider 路径。约束Constraints四条约束决定了实现的下限约束含义共享业务逻辑原生与 MCP 工具路径必须共用同一套业务逻辑禁止各写一份安全护栏不可绕过MCP 不得绕过 write-gate 与 discussion-gate 保护状态必须 DB 落地规范 GSD 状态迁移必须继续由数据库承载能力不匹配必须早失败Provider 能力不匹配必须快速失败而不是静默降级三、六个工作流Workstreams逐项拆解1. Shared Handler Extraction共享 Handler 抽取目标是把业务逻辑从传输注册中分离。主要改造对象是 db-tools.ts、query-tools.ts、complete-task.ts 及其兄弟模块planning/summary/validation 工具。交付物为三层结构传输无关的 Handler 入口覆盖最小工作流工具集调用这些 Handler 的薄原生注册包装调用这些 Handler 的薄 MCP 注册包装。退出标准原生工具行为不变且 MCP 服务器代码中不存在任何工作流工具逻辑的复制。仓库中的落地证据这一工作流已由 workflow-tool-executors.ts 完成——它导出了 11 个传输无关的执行器executeSummarySave、executeTaskComplete、executePlanMilestone、executePlanSlice、executeSliceComplete、executeCompleteMilestone、executeValidateMilestone、executeReplanSlice、executeReassessRoadmap、executeSaveGateResult、executeMilestoneStatus等原生注册db-tools.ts与 MCP 注册workflow-tools.ts都只做参数解析、护栏检查与结果适配真正的状态变更逻辑全部收敛在共享执行器里。2. Workflow-Tool MCP Surface工作流工具 MCP 面为真实 GSD 工作流工具新增一个 MCP 服务器面与现有 session/read API 明确区分。首选最小工具集如下工具名用途gsd_summary_save保存 summary/research/context/assessment 工件到 DB 与磁盘gsd_decision_save记录项目决策到 DB 并重新生成 DECISIONS.mdgsd_plan_milestone写入里程碑规划状态并基于 DB 渲染 ROADMAP.mdgsd_plan_slice写入 slice/task 规划状态并渲染规划工件gsd_plan_task写入任务规划状态并渲染 tasks/T##-PLAN.mdgsd_task_complete记录任务完成并渲染 SUMMARY.mdgsd_slice_complete记录 slice 完成并渲染 SUMMARY.md UAT.mdgsd_complete_milestone记录里程碑完成并渲染 SUMMARY.mdgsd_validate_milestone校验里程碑并渲染 VALIDATION.mdgsd_replan_slice遇到 blocker 后重排 slice保留已完成任务gsd_reassess_roadmapslice 完成后重估路线图并渲染 ASSESSMENT.md ROADMAP.mdgsd_save_gate_result保存质量门禁结果到 DBgsd_milestone_status只读查询里程碑及其所有 slice 的状态实现期间需要拍板的三个决策扩展现有 MCP 包还是新建packages/mcp-gsd-tools-server只导出规范名还是选择性导出别名用单一合并服务器还是拆成「session」与「workflow」两种服务器模式。仓库中的落地证据实际选择了扩展现有包registerWorkflowTools 在 server.ts 的基础上注册了完整工作流面别名如gsd_complete_task、gsd_complete_slice、gsd_milestone_complete、gsd_save_decision等通过logAliasUsage做遥测统计并转发到规范名。规范名与别名的对应关系集中在契约元数据 workflow.tsWORKFLOW_TOOL_CONTRACTS每个工具都声明了canonicalName、aliases、writePolicyread/write与auditEvent供跨包复用。3. Safety and Policy Parity安全与策略对齐确保 MCP 变更与原生工具调用执行相同的规则。重点改造 write-gate.ts、任何仅绑定原生运行时的工具调用门控钩子以及共享 Handler 调用前的 MCP 包装层。必须保留的保护discussion gate 阻断队列模式queue-mode限制写路径限制规范 DB/文件渲染顺序。仓库中的落地证据enforceWorkflowWriteGate(toolName, projectDir, milestoneId)被置于每个 MCP 变更 Handler 的头部workflow-tools.ts内部先loadWriteGateSnapshot(projectDir)加载持久化的门控快照再调用shouldBlockPendingGateInSnapshot与shouldBlockQueueExecutionInSnapshot做双重判定任一命中即抛出明确错误。write-gate 本身在 write-gate.ts 维护按 basePath 隔离的内存状态verifiedDepthMilestones、activeQueuePhase、pendingGateId并通过GSD_PERSIST_WRITE_GATE_STATE1跨进程持久化。只读工具如gsd_milestone_status则有意不过 write-gate与进程内 query-tools.ts 行为保持一致避免 pending-gate / queue-mode 状态下误伤读操作。4. Claude Code Provider IntegrationClaude Code Provider 接入将 GSD 工作流 MCP 面挂载进 Claude Code session。改造对象是 stream-adapter.ts 与 index.ts。预期工作为 Claude SDK session 构建一个 GSD 托管的mcpServers配置仅当 session 需要 GSD 工具时才挂载工作流 MCP 服务器保持现有 Claude Code 流式行为不变。仓库中的落地证据buildWorkflowMcpServers(sdkCwd)workflow-mcp.ts通过detectWorkflowMcpLaunchConfig解析启动配置按优先级依次探测显式GSD_WORKFLOW_MCP_COMMAND→ 项目内packages/mcp-server/dist/cli.js→ 捆绑 CLI 路径GSD_BIN_PATH/GSD_CLI_PATH/GSD_WORKFLOW_PATH锚点向上查找→ PATH 中的gsd-mcp-server随后 stream-adapter.ts 在 1354 行调用buildWorkflowMcpServers(sdkCwd)1359 行取服务器名1365-1369 行检查项目级.claude/settings.json中是否已声明该服务器避免重复注入最终在 1431 行把mcpServers传给 Anthropic Agent SDK session。启动环境由buildWorkflowLaunchEnv组装自动注入GSD_CLI_PATH/GSD_BIN_PATH、GSD_WORKFLOW_EXECUTORS_MODULE、GSD_WORKFLOW_WRITE_GATE_MODULE、GSD_WORKFLOW_PROJECT_ROOT与GSD_PERSIST_WRITE_GATE_STATE1并在需要运行 TypeScript 源码时追加--experimental-strip-types与 resolve-ts 钩子。5. Capability Detection and Failure Path能力检测与失败路径在依赖工具的流程启动前拒绝启动是安全性的最后一道闸。目标文件覆盖 GSD dispatch / auto-mode 预检、Provider 选择与路由检查、面向用户的兼容性错误。要求的判定顺序原生 GSD 工具可用 → 继续 GSD 工作流 MCP 可用 → 继续 两者皆不可用 → 带精确信息的快速失败仓库中的落地证据getWorkflowTransportSupportError(provider, requiredTools, options)workflow-mcp.ts在 dispatch 前从 auto/phases.ts、guided-flow.ts 等位置触发。每个单元类型都声明了所需工具清单getRequiredWorkflowToolsForAutoUnit/getRequiredWorkflowToolsForGuidedUnit例如execute-task需要gsd_task_completecomplete-slice需要gsd_slice_complete、gsd_task_reopen、gsd_replan_slicevalidate-milestone需要gsd_milestone_status、gsd_validate_milestone、gsd_reassess_roadmap。检测时既核对当前 active runtime toolset支持mcp__server__tool前缀形式也对照MCP_WORKFLOW_TOOL_SURFACE集合workflow-mcp.ts 中列出了 40 个可用工具名。缺失时返回可行动的报错信息例如提示「Detected Claude Code model but no workflow MCP. Please run/gsd mcp init .」。无能力组合的用户得到硬错误而不是虚假降级。该模块由 workflow-mcp.test.ts 的 27 个测试锁定。6. Prompt and Documentation AlignmentPrompt 与文档对齐让工作流契约保持严格同时从文档和运行时消息里移除传输假设。目标文件是 execute-task.md 及相关 planning/discuss prompt、Provider 与 MCP 文档。三条规则prompt 继续强制要求规范 GSD 完成/规划工具prompt 不得暗示「仅进程内原生工具」文档必须解释原生与 MCP 两种 fulfillment 路径。从源码看prompts 目录 下的 prompt 已统一改为引用「DB-backed canonical write path」不再出现「manual summary fallback」措辞prompt-contracts.test.ts持续校验 prompt 契约与运行时现实一致。四、六阶段落地计划Phase Plan阶段范围验证方式Phase 1: Spike and Handler 抽取先抽gsd_summary_save、gsd_task_complete、gsd_milestone_status三个工具的共享逻辑并证明原生包装仍然可用现有原生测试全通过新增单测直接覆盖共享 Handler 入口Phase 2: 最小工作流 MCP 服务器把上述三个工具暴露到 MCP保证发现 schema 干净且规范MCP discovery 返回全部三个工具对 fixture 项目直接调用成功Phase 3: Claude Code 端到端证明把最小工作流 MCP 服务器接入 Claude SDK session跑完一条以任务完成收尾的执行路径Claude Code 能调用gsd_task_completesummary 文件、DB 状态、plan 勾选同步更新Phase 4: 扩展到完整最小工作流集增加 planning、slice 完成、里程碑完成、路线图重估、门禁结果工具discuss/plan/execute/complete 生命周期在受支持的流程集上经 MCP 跑通Phase 5: 能力门控与 UX 加固增加预检能力检查与清晰的错误消息不支持的 Provider/session 组合在执行开始前失败Phase 6: Prompt 与文档清理对齐 prompt 与文档到新的传输无关契约prompt 引用准确文档描述受支持的架构与限制选择从三个工具开始 Spike 的理由这三个工具足以在不迁移全量目录的前提下测试端到端的完成语义。仓库中的落地证据Phase 1-6 均已按关联 ADR 文档的状态表完成。其中「MCP 调用的工作流工具与原生工具调用产生相同的 DB 更新、渲染工件与状态迁移」这一验证标准由 workflow-tools-parity.test.ts2026-05 经 PR #5760 加入锁定同目录下的 workflow-tools.test.ts 覆盖 schema 解析、参数必填约束与门控行为。五、文件级起始映射File-Level Starting Map计划给出首批实施的高概率文件清单与仓库现状对照如下计划中的文件仓库实际路径状态src/resources/extensions/gsd/bootstrap/db-tools.ts✅ 存在原生注册入口src/resources/extensions/gsd/bootstrap/query-tools.ts✅ 存在只读查询工具src/resources/extensions/gsd/bootstrap/write-gate.ts✅ 存在写门控策略src/resources/extensions/gsd/tools/complete-task.ts✅ 存在handleCompleteTasksrc/resources/extensions/claude-code-cli/stream-adapter.ts✅ 存在buildWorkflowMcpServers注入点src/resources/extensions/claude-code-cli/index.ts✅ 存在packages/mcp-server/src/server.ts✅ 存在session/read 工具面packages/mcp-server/src/session-manager.ts✅ 存在packages/mcp-server/README.md✅ 存在含 Claude Code / Cursor 配置示例src/resources/extensions/gsd/prompts/execute-task.md✅ 存在六、测试策略单元测试Unit共享 HandlerMCP 包装适配器门控 / 能力检查辅助函数。集成测试Integration对 fixture 项目直接调用 MCP 工具原生工具调用回归覆盖挂载 MCP 的 Claude Code Provider 路径。端到端测试E2E规划或执行一个小型 fixture 任务并通过规范 GSD 工具完成确认 DB 行、渲染后的 summary、plan 状态保持同步。仓库中的落地证据除上述 MCP 侧测试外GSD 扩展侧还沉淀了一批针对性测试原生完成语义由 complete-task.test.ts 覆盖门控语义由 write-gate.test.ts、worktree-write-gate.test.ts 覆盖状态查询由 milestone-status-tool.test.ts 覆盖MCP 与项目配置联动由 mcp-project-config.test.ts 覆盖工具命名与参数可选性由 tool-naming.test.ts 与 tool-param-optionality.test.ts 覆盖。E2E 层则由 tiny-milestone-completion.e2e.test.ts 等测试驱动完整里程碑收尾。七、风险与缓解Risks风险具体担忧缓解策略逻辑漂移原生与 MCP 包装各自演化出不同行为parity 迅速崩塌在广泛暴露 MCP 之前先完成共享 Handler 抽取安全回归MCP 成为绕过原生门控的后门架构比以前更糟在共享 Handler 调用前集中/复用门控检查首次 rollout 过宽立刻导出所有工具和别名scope 与测试负担激增先交付最小工作流工具集Claude SDK session 接入复杂度动态挂载 MCP 服务器可能暴露 cwd、权限、子进程生命周期的边界问题先用 2-3 个工具做窄 Spike再扩张八、ADR-008 完成标准与推荐下一步完成标准Exit CriteriaADR-008 视为实现完成需同时满足Claude Code 驱动的执行能通过 MCP 使用规范 GSD 工作流工具原生 Provider 行为保持不变共享 Handler 同时支撑原生与 MCP 调用门控与状态完整性保护对 MCP 变更同等生效能力检查阻止 prompt 要求不可用的工具。推荐的第一个任务Narrow Spike抽取gsd_summary_save、gsd_task_complete、gsd_milestone_status的共享 Handler通过一个最小工作流 MCP 服务器暴露这三个工具把该 MCP 服务器挂载到 Claude Code session在 fixture 项目上证明端到端任务完成。仓库中的落地证据这一系列步骤的最终形态可以在当前仓库直接查看——workflow-tools.ts 中三个 Spike 工具均有完整实现且gsd_task_complete的 Handler 使用了解构后原样透传参数的模式源码注释明确指出「destructure-then-rebuild」是曾导致 ADR-011 的escalation负载被静默丢弃的缺陷类别透传模式从构造上消除该类回归。若要在项目中使用该 MCP 面可按 packages/mcp-server/README.md 在项目.mcp.json或.cursor/mcp.json中声明gsd服务器npx gsd-mcp-server或全局gsd-mcp-server并视需要配置GSD_CLI_PATH。九、从实施计划到落地关键设计原则总结一份逻辑多路传输业务逻辑收敛在共享执行器原生与 MCP 都只是薄适配层从源头消灭逻辑漂移。MCP 是兼容层而非替代品进程内原生路径继续保留MCP 只为无法访问原生注册表的 Provider 提供等效力入口。安全护栏传输无关write-gate、discussion-gate、queue-mode 限制在 MCP Handler 头部强制执行MCP 永远不是绕过门控的后门。能力先行快速失败每个单元类型声明所需工具dispatch 前校验 active toolset 或 MCP surface缺失即报错绝不发送要求不可用工具的执行 prompt。最小集优先先以 3 个工具证明端到端完成语义再扩展全量工作流集避免首次 rollout 失控。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐voltagent/mcp-server 全解析用 Model Context Protocol 暴露 VoltAgent Agent、工作流与工具voltagent/mcp server 全解析用 Model Context Protocol 暴露 VoltAgent Agent、工作流与工具 导读人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音GSD Import 工作流深度解析外部计划导入、冲突检测与 gsd-plan-checker 校验GSD Import 工作流深度解析外部计划导入、冲突检测与 gsd plan checker 校验 导读 本文围绕 GSDget shit done的人工智能AI 应用提示工程开发工具工作流自动化AI Agent使用 VoltAgent MCP Server 将 Agents、工作流与工具暴露给任意 MCP 客户端使用 VoltAgent MCP Server 将 Agents、工作流与工具暴露给任意 MCP 客户端 本文围绕仓库中的 with mcp server 示例人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇三步完成国家中小学智慧教育平台电子课本解析与下载完整指南下一篇终极鸣潮自动化工具如何3分钟实现后台自动战斗与资源收集创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考