人工智能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-2 内置的 Bugfix 工作流模板src/resources/extensions/gsd/workflow-templates/bugfix.md为 Agent 提供了从缺陷发现到 PR 提交的完整自动化修复路径其核心理念是在动手改代码之前先做根因分析。本文将以该模板为骨架结合注册表、命令实现与单元测试等仓库源码讲解模板元数据、四个阶段triage → fix → verify → ship的执行细节、/gsd start的启动方式与底层运行机制。读完本文你将掌握如何用一条命令让 Agent 以规范的四阶段流程完成 bug 修复并能依据源码理解模板是如何被解析、匹配、派发和恢复的。一、Bugfix 模板在 GSD 工作流体系中的定位在 GSD-2 中工作流模板是一组预置的、面向特定任务类型的 Markdown或 YAML流程文件统一存放在 src/resources/extensions/gsd/workflow-templates/ 目录下。每个模板在 registry.json 中登记包含名称、描述、模式、阶段、触发词等元信息。Bugfix 模板在注册表中的完整条目如下bugfix: { name: Bug Fix, description: Triage, reproduce, fix, test, and ship a bug fix, file: bugfix.md, mode: markdown-phase, phases: [triage, fix, verify, ship], triggers: [bug, issue, fix, broken, regression, error, crash, failing, github.com/*/issues/*], artifact_dir: .gsd/workflows/bugfixes/, estimated_complexity: low, requires_project: false }几个关键字段的解读mode:markdown-phase—— 表明这是一个Markdown 分阶段工作流模板内容由 Agent 按process中的阶段顺序执行。从源码看workflow-templates.ts 定义了四种模式oneshot一次性、无状态、yaml-stepYAML 引擎、markdown-phaseMarkdown 分阶段与auto-milestone基于数据库的里程碑路径其中markdown-phase属于走旧版引擎的legacy 模式。phases—— 四个阶段的执行顺序也是/gsd templates info bugfix展示的流程。triggers—— 触发词表是自动检测模板的核心依据下文会详细展开。artifact_dir:.gsd/workflows/bugfixes/—— 每次执行的工作产物目录用于存放TRIAGE.md与STATE.json。requires_project:false—— 不要求项目已初始化.gsd/目录可以随时启动。二、模板内部结构与元数据解析打开 bugfix.md可以看到模板文件分为四个明确的区块template_meta、purpose、phases与process。2.1template_meta模板元数据template_meta name: bugfix version: 1 mode: markdown-phase requires_project: false artifact_dir: .gsd/workflows/bugfixes/ /template_metaname是模板的唯一标识也是/gsd start bugfix中使用的 ID。mode与requires_project与注册表条目保持一致。artifact_dir指定本次 bugfix 工作流的产物目录相对路径其下会生成TRIAGE.md阶段一的产出与STATE.json断点续跑状态。2.2purpose模板的设计意图Fix a bug from identification through to PR submission. Designed for issues reported via GitHub, user reports, or developer discovery. Emphasizes root cause analysis before jumping to fixes.这里明确指出了模板的三个适用来源GitHub issue、用户反馈、开发者自查以及最重要的设计原则——在跳到修复之前先做根因分析。这一原则贯穿了 Phase 1 的全部动作。2.3phases阶段总览1. triage — Identify root cause, reproduce the bug 2. fix — Implement the fix with tests 3. verify — Run full test suite, check for regressions 4. ship — Create PR with detailed explanation四阶段环环相扣先理解与复现再实现与测试然后全量验证最后提交 PR。与同目录下的 hotfix.md仅fix → ship两阶段、artifact_dir: null、最小仪式形成鲜明对比bugfix 面向普通缺陷讲究流程完整hotfix 面向生产故障追求速度。三、Phase 1Triage —— 先弄清 Bug 再动代码阶段一的目标是在触碰任何代码之前理解 Bug包含五个步骤。3.1 收集上下文Gather context如果关联了 GitHub issue阅读 issue 的描述、标签labels和评论识别期望行为与实际行为的差异记录提供的错误信息、堆栈追踪或复现步骤。3.2 复现Reproduce找到最小复现路径定位受影响的代码路径文件、函数、行号如果 Bug 是间歇性的记录触发它的条件。3.3 根因分析Root cause analysis将 Bug 追溯到根因而不是停留在症状层面尽量通过git blame/git log定位 Bug 是何时被引入的评估爆炸半径blast radius还有哪些功能可能受影响。3.4 产出TRIAGE.md在产物目录中编写简短的TRIAGE.md内容需包含根因解释、复现步骤、受影响的文件/函数、建议的修复方案。3.5 闸门Gate将 triage 结论与建议修复方案呈现给用户确认确认后才进入 Phase 2。这是 GSD 强调的人在环中human-in-the-loop设计Agent 自主分析用户在关键决策点把关。四、Phase 2Fix —— 实现干净、有测试的修复阶段二的目标是实现一个干净且有测试的修复规划修复写一个简短计划最多 1~3 个任务避免过度设计编写修复代码实现代码变更编写/更新测试测试需要满足三个条件能复现原始 Bug没有修复时测试失败能验证修复有效覆盖边界情况原子提交使用fix(scope): description格式的提交信息。没有修复时测试必须失败这条规则至关重要——它保证了测试真正捕获了回归而不是一个永远通过的摆设。五、Phase 3Verify —— 确保修复没有破坏任何东西阶段三的目标是确保修复不引入回归需要依次执行运行项目完整测试套件运行构建如适用运行 linter如适用检查相关功能的回归如有任何失败先修复再继续。这一阶段不允许带病前进任何失败都会阻塞进入 Phase 4。六、Phase 4Ship —— 提交一份文档完善的 PR阶段四的目标是创建一份文档完善的 PR确保所有变更都已提交到 workflow 分支构建 PR 正文需要包含指向原始 issue 的链接如适用根因解释修复方案的描述新增的测试覆盖说明将 PR 细节呈现给用户审阅在用户批准后通过gh pr create创建 PR。七、实战用/gsd start启动 Bugfix 工作流模板的实际派发由 commands-workflow-templates.ts 中的handleStart实现对应命令为/gsd start。以下是启动 bugfix 的几种典型用法。7.1 显式指定模板/gsd start bugfix 修复登录按钮无响应的问题handleStart会先将第一个单词bugfix通过resolveByName解析为模板 ID源码见 workflow-templates.ts剩余文本作为描述注入到工作流提示词中。7.2 关联 GitHub issue快捷方式/gsd start bugfix 修复偶发崩溃 --issue https://github.com/xxx/yyy/issues/123--issue ref标志会把 issue 引用带入工作流提示词的issueRef字段让 Agent 在 Triage 阶段自动去阅读该 issue。7.3 不指定模板触发词自动检测/gsd start 登录按钮点击后报错崩溃当第一个单词不是模板名时handleStart会调用autoDetect(description)。从 workflow-templates.ts 的实现可以看到检测逻辑描述文本中包含触发词短语如regression、broken时得分更高多词触发词按词数 ×2 计分单词触发词如bug、fix、error、crash与描述中的单词完全匹配时计 1 分得分 ≥4 判为high置信度≥2 为medium≥1 为low若唯一命中或首选项达到high直接采用若有多个候选则列出前 4 个让用户选择。因此描述中含bug、fix、crash、error、regression、broken等词或包含形如github.com/*/issues/*的 issue 链接时都会被自动路由到 bugfix 模板。7.4 其他实用标志用法说明/gsd start --list等同于/gsd templates列出全部模板/gsd start bugfix ... --dry-run预览将创建的产物目录、分支名等不执行任何操作/gsd start --resume恢复最近一个未完成的工作流/gsd start无参数若存在进行中的工作流则提示如何续跑八、源码视角启动一次 bugfix 时底层发生了什么从 commands-workflow-templates.ts 的handleStart实现可以还原一次 bugfix 启动的完整调用链自动模式冲突守卫如果 auto-mode 正在运行isAutoActive()会拒绝启动并提示先执行/gsd pause因为工作流模板会自己派发消息并切换 git 分支与 auto-mode 的派发循环冲突加载模板内容优先查找项目/全局插件覆盖resolvePlugin否则从内置目录读取 bugfix.mdloadWorkflowTemplate创建产物目录在.gsd/workflows/bugfixes/下按YYMMDD-序号-slug命名规则创建目录如260106-1-fix-login-buttongetNextWorkflowNum通过扫描已有目录序号自动递增源码见 commands-workflow-templates.ts创建 git 分支默认切换到gsd/bugfix/slug分支除非prefs.isolation none并先对当前工作区做一次自动提交autoCommit(workflow-template, templateId, [])以避免污染新分支写入STATE.json记录模板、描述、分支、各阶段状态首个阶段标记为active这是/gsd start --resume断点续跑的数据基础派发工作流提示词通过loadPrompt(workflow-start, {...})组装提示词将模板 ID、阶段序列、复杂度、产物目录、分支名、issue 引用与完整的workflowContent即 bugfix.md 全文注入然后以gsd-workflow-template自定义消息类型触发 Agent 的一轮执行pi.sendMessage(..., { triggerTurn: true })。九、断点续跑与模板检查命令9.1 恢复进行中的工作流/gsd start无参数时findInProgressWorkflows会扫描.gsd/workflows/下所有分类目录中的STATE.json找出没有completedAt字段的进行中工作流并提示。执行/gsd start --resume后handleStart会读取最近一次工作流的STATE.json统计已完成/激活/待处理的阶段重新加载对应模板并派发提示词指示 Agent 从当前激活阶段继续。9.2 查看模板详情/gsd templates # 列出所有模板及阶段、复杂度 /gsd templates info bugfix # 查看 bugfix 的详细信息getTemplateInfo会展示名称、描述、复杂度、是否要求.gsd/、阶段列表、触发词与产物目录源码见 workflow-templates.ts。/gsd templates info name还支持通过getTemplateCompletions做命令补全。十、质量保障单元测试如何验证模板体系模板体系的正确性由 tests/workflow-templates.test.ts 中的单元测试保障覆盖了与本文相关的主要行为注册表加载验证loadRegistry()返回版本 1且至少包含 8 个核心模板其中明确断言bugfix存在于注册表别名解析resolveByName(bug)应解析为bugfix源码中的别名表在 workflow-templates.ts自动检测autoDetect(fix the login button)必须包含bugfix模板加载loadWorkflowTemplate(bugfix)返回的内容必须包含Bugfix Workflow、Phase 1: Triage与Phase 4: Ship。这些测试为模板注册、匹配与内容加载提供了可回归的验证基线。十一、何时用 bugfix何时用 hotfix两者同属缺陷修复类模板但适用场景截然不同维度bugfix本文主题hotfix阶段triage → fix → verify → shipfix → ship复杂度评级lowminimal产物目录.gsd/workflows/bugfixes/无artifact_dir: null设计原则先根因分析再修复测试完备最小仪式速度优先典型场景普通 issue、可复现缺陷、需要完整回归验证生产环境故障、紧急修复若描述中出现hotfix、urgent、critical、production down、p0等触发词则会被自动路由到 hotfix 模板见 registry.json。两者的注册表配置与模板文件均为现成对照便于深入研读。总结GSD-2 的 Bugfix 工作流模板把一次高质量的缺陷修复拆解为 triage、fix、verify、ship 四个可控阶段将根因分析前置、测试与验证内建、用户在关键闸门把关并通过/gsd start bugfix [描述] [--issue]一条命令即可启动底层由注册表、触发词自动检测、STATE.json断点续跑与 git 分支隔离共同支撑。对希望让 Agent 自主、安全、可恢复地完成 bug 修复的团队来说这套模板及其源码实现提供了完整的可复用参考。赞分享人工智能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 工作流模板Workflow Templates实战指南从 /gsd start 到自动化分阶段执行GSD 工作流模板Workflow Templates实战指南从 /gsd start 到自动化分阶段执行 导读 本文基于 gsd 2 仓库项目路径 g人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD Security Audit 工作流模板四阶段自动化代码安全审计实战指南GSD Security Audit 工作流模板四阶段自动化代码安全审计实战指南 导读 本文围绕 GSD 扩展内置的 security audit 工作流模板人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD-2 Hotfix 工作流模板解析生产故障下的极简两阶段热修复实战指南GSD 2 Hotfix 工作流模板解析生产故障下的极简两阶段热修复实战指南 导读 本文围绕 GSD 2 内置的 hotfix 工作流模板 src/res人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇华为warpdrive硬件加速库解密高性能加密与压缩的终极指南下一篇LMCache-mindspore性能测试实测数据告诉你到底有多快创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考