Qwen Code 的 Bugfix Skill 实战reproduce-first 工作流全解析【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen Code 开源仓库内置的bugfixSkill.qwen/skills/bugfix/SKILL.md展开完整拆解其“先复现、再修复、后验证”reproduce-first的 GitHub Issue 缺陷修复流程从用gh拉取 Issue 生成工单文件到派出test-engineer子代理做端到端复现再到构建产物、回归测试、自我审计与代码评审的完整闭环。读完本文你将掌握这套 6 步工作流的具体命令、子代理协作机制与迭代规则并理解为什么不先复现就直接改代码是缺陷修复中最常见的失败根源。一、Skill 的定位与触发方式bugfixSkill 是 Qwen Code 项目中沉淀在仓库内的可复用工作流定义其 frontmatterSKILL.md 头部明确声明了它的输入与适用场景namebugfixdescription修复来自 GitHub Issue 的缺陷遵循reproduce-first 工作流当用户要求修复 bug、调查 GitHub Issue 或调试用户上报的问题时启用输入一个 GitHub Issue 的 URL 或编号。使用斜杠命令Slash-command时其参数会被追加到该 Skill 的正文中由 Qwen Code 注入执行上下文。也就是说它是一条输入 Issue 编号、输出 可合并的修复的端到端流水线而不是零散的改几行代码的提示词。该 Skill 在仓库的工程约定中也有一席之地项目根目录的 AGENTS.md 在 Bugfix 一节明确指示使用/bugfixSkill 执行 reproduce-first 工作流即复现 → 修复 → 验证 → 测试 → 自我审计 → 代码评审。二、全局设计原则为什么必须先复现SKILL.md 开篇就给出了整个工作流的立场SKILL.md#L10-L12请勿跳过复现步骤不先复现就修复往往导致不完整的修复和回归。这条原则与同仓库的 structured-debugging Skill 一脉相承——后者明确指出直接形成理论并立刻动手修复是最常见的失败模式修复指向了错误根因、引入了额外复杂度、制造了虚假信心、掩盖了真正的问题。因此bugfix工作流把复现设计为不可跳过的硬性前置步骤用子代理专职负责。三、工件路径约定.qwen/issues/工作流的核心工件是一个Issue Markdown 文件所有步骤都围绕它展开SKILL.md#L19-L22目录仓库内的.qwen/issues/命名issue-number.md文中issue-file即指该文件。该目录与仓库约定的其他工作产物目录.qwen/e2e-tests/、.qwen/pr-drafts/等并列具体可见 AGENTS.md 的 Project Directories 小节。Issue 文件是唯一事实来源single source of truthtest-engineer代理的复现报告、验证报告都会回写到这个文件中保证所有协作方主代理与子代理看到的都是同一份最新状态。四、Step 1读取 Issue 并落盘为工单文件工作流的第一步是拉取 GitHub Issue 并写入工件文件SKILL.md#L24-L47。命令如下mkdir -p .qwen/issues gh issue view number \ --json number,title,body \ -t # Issue #{{.number}}: {{.title}} {{.body}} --- ## Reproduction report _Pending - to be filled by the test engineer._ ## Verification report _Pending - to be filled by the test engineer._ .qwen/issues/issue-number.md要点说明使用 GitHub 官方 CLIgh issue view以--json结构化取值配合-t模板生成带章节骨架的 Markdown 文件模板中预置了两个占位章节Reproduction report复现报告与Verification report验证报告后续步骤会由test-engineer填充项目整体约定 GitHub 操作一律走ghCLI见 AGENTS.md 的 GitHub Operations 小节本步骤正是这一约定的直接体现。五、Step 2复现——派发test-engineer子代理复现环节的关键设计是主代理不亲自复现而是委派专职子代理SKILL.md#L49-L56。向test-engineer代理传入issue-file路径只陈述目标复现这个 bugreproduce the bug保持提示词最小化——复现策略完全由测试工程师代理负责等待其完成后读取issue-file获取复现报告若状态为NOT_REPRODUCED未复现则向用户报告并停止。为什么把复现外包给独立代理查看 .qwen/agents/test-engineer.md 即可找到答案——该代理的角色边界非常清晰唯一职责是复现 bug 与验证修复绝不允许修复 bug 或修改源码它的工具集包含read_file、edit、write_file、run_shell_command、skill、web_fetch等但edit/write_file仅限两种用途更新 issue 文件的报告章节、编写作为回退手段的测试脚本复现时优先做端到端E2E复现逻辑类问题用无头模式headlessTUI 渲染/键盘/视觉类问题用交互模式tmux复现必须使用全局安装的qwen命令与用户上报时的环境一致禁止在复现阶段使用npm run build/node dist/cli.js若 E2E 确实不可行如 bug 深埋在内部逻辑、没有可观察的 CLI 行为才允许退化为编写一个能捕获该 bug 的失败测试且必须在报告中说明原因。复现报告的输出格式test-engineer.md#L102-L126包含状态、方法、二进制、执行命令、观察到的行为、期望行为与关键上下文其中状态机是REPRODUCED | NOT_REPRODUCED | VERIFIED_FIXED | STILL_BROKEN这一设计在制度上保证了复现与修复两种角色互不越权避免测试者顺手改代码导致证据失真。六、Step 3修复复现报告确认 bug 存在后才进入修复环节SKILL.md#L58-L65阅读相关代码并实施修复复现报告是上下文核心应包含观察到的行为、期望行为与有用的代码路径如果 bug 足够复杂、第一轮修复不奏效则应启用structured-debuggingSkill系统地推进假设验证而不是随机猜测。关于structured-debugging的核心方法详见 .qwen/skills/structured-debugging/SKILL.md形成可证伪的假设Hypothesize→ 在关键判定点植入精确日志Design Instrumentation优先记录数据值而非仅记录代码路径→ 确认日志可被采集 → 运行并逐行读取真实输出数据与假设矛盾时相信数据→ 把发现写进旁注文件Document Findings→ 带着新证据迭代。它同时列出了必须规避的失败模式无证据就动手、甩锅外部系统、只查代码路径不查数据、重构用户报告而不是调查环境差异、跨尝试丢失上下文。七、Step 4验证——构建产物后再次派发测试工程师修复完成后进入验证闭环SKILL.md#L67-L80npm run build npm run bundle这两个命令的实际定义可在 package.json 的 scripts 中找到build执行 TypeScript 编译与资源拷贝node scripts/build.jsbundle先执行npm run generate生成 Git 提交信息再通过 esbuild 配置把dist/打成单个dist/cli.jsnode esbuild.config.js。在 AGENTS.md 的 Common Commands 中也有对应说明bundle依赖先前的build产物。构建完成后再次派出test-engineer代理指向同一个 issue 文件目标改为使用node dist/cli.js验证修复而不是复现阶段使用的全局qwen——这样测的才是本地改动。若验证状态为STILL_BROKEN则读取更新后的 issue 文件、回到 Step 3 继续迭代在返回VERIFIED_FIXED之前不得继续前进。验证阶段的具体行为约束同样见 test-engineer.md#L87-L100重跑此前触发 bug 的同一套复现步骤同时确认基本 happy path 仍然工作若当初是通过测试脚本复现的则重跑该测试确认通过。八、Step 5测试与回归覆盖验证通过后补全测试SKILL.md#L82-L86为修改过的包运行单元测试若测试工程师在复现阶段已写出失败测试则确认它在修复后通过否则为失败场景补充聚焦的回归测试。项目的单测约定AGENTS.md#L70-L124是测试必须在具体包目录内运行且优先跑单个文件例如cd packages/core npx vitest run src/path/to/file.test.ts cd packages/cli npx vitest run src/path/to/file.test.ts测试文件与源码同目录file.test.ts紧挨file.ts使用 vitest 框架。同时要避免两个常见的坑从项目根目录执行npx vitest会因包级 vitest 配置不匹配而失败、使用npm run test -- --filter...不会过滤、会跑全量。此外在 CLI 测试中被vi.mock()消费的 mock 必须用vi.hoisted()包裹mock 工厂在模块加载期执行早于测试执行。九、Step 6自我审计与代码评审最后一道质量闸门SKILL.md#L88-L104自我审计完整 diff按 AGENTS.md 的 General workflow 中的 self-audit 步骤执行——以开放式的多轮通读而非定向找茬审阅整个 diff并对依赖的每项绿色测试做假设它错了的验证通过不代表断言正确。要求连续两轮干净通过才算完成平凡修复一轮即可审计若改动源码需在继续前重跑 Step 4。代码评审除单行或平凡的配置修复外一律执行/review并在评审任务中列出所有变更文件。对评审意见逐一打上裁决verdictValid有效真实 bug 或有意义的改进 → 修复它False positive误报评审者遗漏了上下文 → 跳过Overthinking过度设计技术上可行但不值得增加复杂度 → 跳过。修复有效问题后重跑单元测试与一次快速验证冒烟检查。评审的仓库级规则可见 AGENTS.md 的 Code Review 小节例如报告前必须对照被评审的精确 commit 复核引用行、缺失测试通常只是 Suggestion 而非 Critical、新增字段/参数必须 grep 全部读取点防止出现死开关等。十、迭代规则闭环与终止条件工作流对迭代行为做了显式约束防止无限循环SKILL.md#L106-L111若 Step 4 验证失败 → 回到 Step 3再重跑 Step 4若 Step 6 发现有效问题 → 修复后重跑 Step 4 作为冒烟检查并重跑自我审计Step 36 之间循环不得超过 3 次超过必须停下来询问用户。这套最多 3 轮的护栏确保了代理既不会在一条错误思路上无限空转也不会在未确认修复有效时就把改动交付出去。十一、完整工作流速览把六个步骤与协作关系汇总如下步骤动作责任人关键命令 / 状态Step 1拉取 Issue 落盘主代理gh issue view number --json ... .qwen/issues/issue-number.mdStep 2复现test-engineer子代理全局qwenE2E 优先NOT_REPRODUCED则停止Step 3修复主代理复杂 bug 转structured-debuggingStep 4验证test-engineer子代理npm run build npm run bundle用node dist/cli.jsVERIFIED_FIXED才放行Step 5回归测试主代理cd packages/pkg npx vitest run ...Step 6自审 评审主代理/review意见按 Valid / False positive / Overthinking 裁决十二、设计思路解读这条工作流解决了什么问题从 SKILL.md 与配套的 test-engineer.md、structured-debugging SKILL.md 的相互印证中可以提炼出这套工作流针对的核心问题修复前移的复现责任把复现从主代理的自觉行为变成制度化的子代理委派并用未复现即停止的硬规则兜底杜绝边猜边改角色与权限分离测试工程师只观察与报告、绝不改源码保证复现证据与验证结论的可信度主代理持有修复权二者通过 issue 文件交换信息形成干净的生产者-消费者协议二进制与环境的严格区分复现用用户环境的全局qwen验证用本地构建的node dist/cli.js确保复现的是用户的 bug验证的是自己的修复证据留痕复现报告、验证报告全部回写进.qwen/issues/issue-number.md跨会话可追溯这与structured-debugging中旁注文件跨 turn 持久化的设计哲学一致有界迭代Step 36 的循环上限 3 次超出即询问用户避免代理在复杂缺陷上无限消耗资源。这套流程可以直接复用到任何以 GitHub Issue 为缺陷入口的 CLI 项目只需把构建/打包命令和子代理定义替换为对应仓库的版本即可获得一套带角色隔离、证据留痕与迭代护栏的自动化缺陷修复流水线。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Qwen Code 的 Bugfix Skill 实战：reproduce-first 工作流全解析
Qwen Code 的 Bugfix Skill 实战reproduce-first 工作流全解析【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文围绕 Qwen Code 开源仓库内置的bugfixSkill.qwen/skills/bugfix/SKILL.md展开完整拆解其“先复现、再修复、后验证”reproduce-first的 GitHub Issue 缺陷修复流程从用gh拉取 Issue 生成工单文件到派出test-engineer子代理做端到端复现再到构建产物、回归测试、自我审计与代码评审的完整闭环。读完本文你将掌握这套 6 步工作流的具体命令、子代理协作机制与迭代规则并理解为什么不先复现就直接改代码是缺陷修复中最常见的失败根源。一、Skill 的定位与触发方式bugfixSkill 是 Qwen Code 项目中沉淀在仓库内的可复用工作流定义其 frontmatterSKILL.md 头部明确声明了它的输入与适用场景namebugfixdescription修复来自 GitHub Issue 的缺陷遵循reproduce-first 工作流当用户要求修复 bug、调查 GitHub Issue 或调试用户上报的问题时启用输入一个 GitHub Issue 的 URL 或编号。使用斜杠命令Slash-command时其参数会被追加到该 Skill 的正文中由 Qwen Code 注入执行上下文。也就是说它是一条输入 Issue 编号、输出 可合并的修复的端到端流水线而不是零散的改几行代码的提示词。该 Skill 在仓库的工程约定中也有一席之地项目根目录的 AGENTS.md 在 Bugfix 一节明确指示使用/bugfixSkill 执行 reproduce-first 工作流即复现 → 修复 → 验证 → 测试 → 自我审计 → 代码评审。二、全局设计原则为什么必须先复现SKILL.md 开篇就给出了整个工作流的立场SKILL.md#L10-L12请勿跳过复现步骤不先复现就修复往往导致不完整的修复和回归。这条原则与同仓库的 structured-debugging Skill 一脉相承——后者明确指出直接形成理论并立刻动手修复是最常见的失败模式修复指向了错误根因、引入了额外复杂度、制造了虚假信心、掩盖了真正的问题。因此bugfix工作流把复现设计为不可跳过的硬性前置步骤用子代理专职负责。三、工件路径约定.qwen/issues/工作流的核心工件是一个Issue Markdown 文件所有步骤都围绕它展开SKILL.md#L19-L22目录仓库内的.qwen/issues/命名issue-number.md文中issue-file即指该文件。该目录与仓库约定的其他工作产物目录.qwen/e2e-tests/、.qwen/pr-drafts/等并列具体可见 AGENTS.md 的 Project Directories 小节。Issue 文件是唯一事实来源single source of truthtest-engineer代理的复现报告、验证报告都会回写到这个文件中保证所有协作方主代理与子代理看到的都是同一份最新状态。四、Step 1读取 Issue 并落盘为工单文件工作流的第一步是拉取 GitHub Issue 并写入工件文件SKILL.md#L24-L47。命令如下mkdir -p .qwen/issues gh issue view number \ --json number,title,body \ -t # Issue #{{.number}}: {{.title}} {{.body}} --- ## Reproduction report _Pending - to be filled by the test engineer._ ## Verification report _Pending - to be filled by the test engineer._ .qwen/issues/issue-number.md要点说明使用 GitHub 官方 CLIgh issue view以--json结构化取值配合-t模板生成带章节骨架的 Markdown 文件模板中预置了两个占位章节Reproduction report复现报告与Verification report验证报告后续步骤会由test-engineer填充项目整体约定 GitHub 操作一律走ghCLI见 AGENTS.md 的 GitHub Operations 小节本步骤正是这一约定的直接体现。五、Step 2复现——派发test-engineer子代理复现环节的关键设计是主代理不亲自复现而是委派专职子代理SKILL.md#L49-L56。向test-engineer代理传入issue-file路径只陈述目标复现这个 bugreproduce the bug保持提示词最小化——复现策略完全由测试工程师代理负责等待其完成后读取issue-file获取复现报告若状态为NOT_REPRODUCED未复现则向用户报告并停止。为什么把复现外包给独立代理查看 .qwen/agents/test-engineer.md 即可找到答案——该代理的角色边界非常清晰唯一职责是复现 bug 与验证修复绝不允许修复 bug 或修改源码它的工具集包含read_file、edit、write_file、run_shell_command、skill、web_fetch等但edit/write_file仅限两种用途更新 issue 文件的报告章节、编写作为回退手段的测试脚本复现时优先做端到端E2E复现逻辑类问题用无头模式headlessTUI 渲染/键盘/视觉类问题用交互模式tmux复现必须使用全局安装的qwen命令与用户上报时的环境一致禁止在复现阶段使用npm run build/node dist/cli.js若 E2E 确实不可行如 bug 深埋在内部逻辑、没有可观察的 CLI 行为才允许退化为编写一个能捕获该 bug 的失败测试且必须在报告中说明原因。复现报告的输出格式test-engineer.md#L102-L126包含状态、方法、二进制、执行命令、观察到的行为、期望行为与关键上下文其中状态机是REPRODUCED | NOT_REPRODUCED | VERIFIED_FIXED | STILL_BROKEN这一设计在制度上保证了复现与修复两种角色互不越权避免测试者顺手改代码导致证据失真。六、Step 3修复复现报告确认 bug 存在后才进入修复环节SKILL.md#L58-L65阅读相关代码并实施修复复现报告是上下文核心应包含观察到的行为、期望行为与有用的代码路径如果 bug 足够复杂、第一轮修复不奏效则应启用structured-debuggingSkill系统地推进假设验证而不是随机猜测。关于structured-debugging的核心方法详见 .qwen/skills/structured-debugging/SKILL.md形成可证伪的假设Hypothesize→ 在关键判定点植入精确日志Design Instrumentation优先记录数据值而非仅记录代码路径→ 确认日志可被采集 → 运行并逐行读取真实输出数据与假设矛盾时相信数据→ 把发现写进旁注文件Document Findings→ 带着新证据迭代。它同时列出了必须规避的失败模式无证据就动手、甩锅外部系统、只查代码路径不查数据、重构用户报告而不是调查环境差异、跨尝试丢失上下文。七、Step 4验证——构建产物后再次派发测试工程师修复完成后进入验证闭环SKILL.md#L67-L80npm run build npm run bundle这两个命令的实际定义可在 package.json 的 scripts 中找到build执行 TypeScript 编译与资源拷贝node scripts/build.jsbundle先执行npm run generate生成 Git 提交信息再通过 esbuild 配置把dist/打成单个dist/cli.jsnode esbuild.config.js。在 AGENTS.md 的 Common Commands 中也有对应说明bundle依赖先前的build产物。构建完成后再次派出test-engineer代理指向同一个 issue 文件目标改为使用node dist/cli.js验证修复而不是复现阶段使用的全局qwen——这样测的才是本地改动。若验证状态为STILL_BROKEN则读取更新后的 issue 文件、回到 Step 3 继续迭代在返回VERIFIED_FIXED之前不得继续前进。验证阶段的具体行为约束同样见 test-engineer.md#L87-L100重跑此前触发 bug 的同一套复现步骤同时确认基本 happy path 仍然工作若当初是通过测试脚本复现的则重跑该测试确认通过。八、Step 5测试与回归覆盖验证通过后补全测试SKILL.md#L82-L86为修改过的包运行单元测试若测试工程师在复现阶段已写出失败测试则确认它在修复后通过否则为失败场景补充聚焦的回归测试。项目的单测约定AGENTS.md#L70-L124是测试必须在具体包目录内运行且优先跑单个文件例如cd packages/core npx vitest run src/path/to/file.test.ts cd packages/cli npx vitest run src/path/to/file.test.ts测试文件与源码同目录file.test.ts紧挨file.ts使用 vitest 框架。同时要避免两个常见的坑从项目根目录执行npx vitest会因包级 vitest 配置不匹配而失败、使用npm run test -- --filter...不会过滤、会跑全量。此外在 CLI 测试中被vi.mock()消费的 mock 必须用vi.hoisted()包裹mock 工厂在模块加载期执行早于测试执行。九、Step 6自我审计与代码评审最后一道质量闸门SKILL.md#L88-L104自我审计完整 diff按 AGENTS.md 的 General workflow 中的 self-audit 步骤执行——以开放式的多轮通读而非定向找茬审阅整个 diff并对依赖的每项绿色测试做假设它错了的验证通过不代表断言正确。要求连续两轮干净通过才算完成平凡修复一轮即可审计若改动源码需在继续前重跑 Step 4。代码评审除单行或平凡的配置修复外一律执行/review并在评审任务中列出所有变更文件。对评审意见逐一打上裁决verdictValid有效真实 bug 或有意义的改进 → 修复它False positive误报评审者遗漏了上下文 → 跳过Overthinking过度设计技术上可行但不值得增加复杂度 → 跳过。修复有效问题后重跑单元测试与一次快速验证冒烟检查。评审的仓库级规则可见 AGENTS.md 的 Code Review 小节例如报告前必须对照被评审的精确 commit 复核引用行、缺失测试通常只是 Suggestion 而非 Critical、新增字段/参数必须 grep 全部读取点防止出现死开关等。十、迭代规则闭环与终止条件工作流对迭代行为做了显式约束防止无限循环SKILL.md#L106-L111若 Step 4 验证失败 → 回到 Step 3再重跑 Step 4若 Step 6 发现有效问题 → 修复后重跑 Step 4 作为冒烟检查并重跑自我审计Step 36 之间循环不得超过 3 次超过必须停下来询问用户。这套最多 3 轮的护栏确保了代理既不会在一条错误思路上无限空转也不会在未确认修复有效时就把改动交付出去。十一、完整工作流速览把六个步骤与协作关系汇总如下步骤动作责任人关键命令 / 状态Step 1拉取 Issue 落盘主代理gh issue view number --json ... .qwen/issues/issue-number.mdStep 2复现test-engineer子代理全局qwenE2E 优先NOT_REPRODUCED则停止Step 3修复主代理复杂 bug 转structured-debuggingStep 4验证test-engineer子代理npm run build npm run bundle用node dist/cli.jsVERIFIED_FIXED才放行Step 5回归测试主代理cd packages/pkg npx vitest run ...Step 6自审 评审主代理/review意见按 Valid / False positive / Overthinking 裁决十二、设计思路解读这条工作流解决了什么问题从 SKILL.md 与配套的 test-engineer.md、structured-debugging SKILL.md 的相互印证中可以提炼出这套工作流针对的核心问题修复前移的复现责任把复现从主代理的自觉行为变成制度化的子代理委派并用未复现即停止的硬规则兜底杜绝边猜边改角色与权限分离测试工程师只观察与报告、绝不改源码保证复现证据与验证结论的可信度主代理持有修复权二者通过 issue 文件交换信息形成干净的生产者-消费者协议二进制与环境的严格区分复现用用户环境的全局qwen验证用本地构建的node dist/cli.js确保复现的是用户的 bug验证的是自己的修复证据留痕复现报告、验证报告全部回写进.qwen/issues/issue-number.md跨会话可追溯这与structured-debugging中旁注文件跨 turn 持久化的设计哲学一致有界迭代Step 36 的循环上限 3 次超出即询问用户避免代理在复杂缺陷上无限消耗资源。这套流程可以直接复用到任何以 GitHub Issue 为缺陷入口的 CLI 项目只需把构建/打包命令和子代理定义替换为对应仓库的版本即可获得一套带角色隔离、证据留痕与迭代护栏的自动化缺陷修复流水线。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 评估与优化终端前景/背景可读性)
