| name | fix |
| description | 问题诊断与修复:验证 + 根因 + 复杂度分级 + 修复方案 + GitHub Issues 登记。当用户说'这个问题存在吗''帮我分析这个 bug''诊断一下这个模块''修复这个问题'时触发。支持单条与批量(review 报告)输入。 |
| argument-hint | <问题描述|文件:行号|review 报告路径|#issue> |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash","Agent","AskUserQuestion"] |
gocell-web 问题诊断与修复
gh 命令均 dangerouslyDisableSandbox: true;创建/查询前 gh auth status;issue 写入幂等(先 search 再 create)。Backlog 真值源 = GitHub Issues(label backlog + priority/p0..p3)。
输入解析
支持单条(自然语言 / 文件:行号 / #NNN 或裸数字 issue 号)或批量(review 文档路径 / --from-review <stage>)。
解析规则:
- 含
文件路径:行号 → 直接定位到代码
- 含 GitHub issue 编号(
#720 或裸数字 720)→ gh issue view <num> 解析(title / body / labels)
- issue 不存在(404)→ 报错
指定 issue #<num> 不存在 并停止
- issue 存在但缺
backlog label → 警告后继续,将其视为外部上下文(非 backlog 工作流)
- 指向 review 文档(.md 文件含多条 findings)→ 进入批量模式
- 自然语言 → 用 Grep/Glob 在代码库中定位相关代码
批量模式(review 报告)
当输入是 review 文档时:
-
解析所有 findings(按 ID、文件、描述提取)
-
按包聚类(@gocell/<pkg> 各为一组;apps/web/、tools/codegen/、docs/ 各一组)
-
决定并发度:
| finding 数 | 并发 sub-agent 数 |
|---|
| ≤ 3 | 0(主 agent 直接处理) |
| 4-9 | 2 |
| ≥ 10 | 3 |
-
Triage 并行(subagent_type: Explore):聚类后的组分发,每组完整执行阶段 1.1→1.3 + 2.4,返回结构化表。同包必须分给同一 agent(避免重复 Read + 防 fix 阶段写冲突)。Sub-agent prompt 自包含(finding 列表、当前分支 diff 摘要、CLAUDE.md 关键约束)。
-
主 agent 汇总,输出状态/归属表:
| 状态 | 归属 | 处理方式 |
|---|
| CONFIRMED | IN_SCOPE | 在当前分支修 |
| CONFIRMED | RELATED | 建议搭车修,标注"搭车" |
| CONFIRMED | OUT_OF_SCOPE | 按 §沟通规则闸门输出 issue 建议命令 |
| RESOLVED | — | 标注已修,跳过 |
| CANNOT_VERIFY | — | 标注待确认,跳过 |
-
只修 IN_SCOPE + RELATED,按分析结果决策:
- IN_SCOPE + Cx1 + 满足自动执行条件 → 直接修
- IN_SCOPE + Cx2 → 执行推荐方案
- IN_SCOPE + Cx3 / Cx4 → 只输出方案,标注"需人工决策"
- RELATED + Cx1 / Cx2 → 搭车修,标注"搭车"
- OUT_OF_SCOPE → 不修;按 §沟通规则闸门输出建议命令
-
修复并行(subagent_type: vue-developer):按包聚类分发,并发数同步骤 3。每个 sub-agent 串行处理组内 finding(同包内串行避免写冲突),跑阶段 4.2 的 Edit-Test Loop。Cx1 + Cx2 都并行;Cx3 / Cx4 只输出方案不派发。
-
主 agent 汇总修复结果,跑阶段 4.3 最终测试 + 4.6 git 收尾 + issue 闭合/创建。
阶段 1:问题定位
1.0 Backlog 关联检查
gh issue list --label backlog --search "<关键词>" --state open --json number,title,labels → 确认是否已登记
- 命中 →
gh issue view <num> 读取上下文
- 未命中 → 记录;修复完成后在阶段 4.6 按 §沟通规则闸门处理
1.1 找到问题代码
按精度递进:明确路径 → Read;模糊描述 → Grep 类型/函数名 → Grep 错误码/i18n key → Agent(Explore) 调用图。三层均无果 → AskUserQuestion。
1.2 追踪调用链 + 数据流
从问题代码向上(调用方 / 父组件 / 路由 / store action)和向下(子组件 / Composables / API client)追踪。跨 3+ 包用 Agent(Explore)。同时追踪数据流:API → store → Composable → 组件 props → DOM。
1.3 确认问题是否存在
| 状态 | 含义 | 下一步 |
|---|
| CONFIRMED | 问题真实存在,可复现 | → 阶段 2 |
| RESOLVED | 已被修复(给出证据:哪行、哪个 PR) | → 报告,结束 |
| CHANGED | 代码重构过,问题形态变化 | → 描述新形态,确认是否继续 |
| CANNOT_VERIFY | 无法确认(缺上下文 / 需运行时) | → AskUserQuestion 请求更多信息 |
输出含:状态 / 位置 / 调用链 / 数据流 / 问题描述。
1.4 复现测试(Reproduction Test First)
CONFIRMED 后、修复前,构造一个能复现问题的测试用例:
| 场景 | 操作 |
|---|
| 已有测试可稍改复现 | 修改已有测试 + 确认 FAIL |
| 需新写 vitest 单测 | <file>.spec.ts 新增 it('reproduces #<NNN>', ...) |
| 需 Playwright E2E 才能触发 | tests/e2e/<feature>.spec.ts 新增;标注 RUNTIME_ONLY 时跳过此步 |
| 视觉/样式回归 | 无法机器复现 → 标 MANUAL_ONLY,附复现步骤截图 |
运行确认 FAIL:pnpm -F @gocell/<pkg> test --run -t "<test name>"。
阶段 2:根因分析 + 复杂度分级
2.1 根因三维度
- 代码层面:哪行代码、哪个设计决策导致
- 架构层面:是否系统性(Grep 同模式,1 处=局部,3+=架构缺陷)。架构缺陷 → AskUserQuestion 局部修 vs 系统性重构
- 历史层面:
git log -S "<片段>" 搜同类已有修复,发现团队惯例避免退化
2.2 影响范围
直接 / 间接(列受影响文件)/ 同类(Grep 数量)
2.3 复杂度分级
Cx = 改动量 / 实现风险。 Cx1 = "容易修",不代表"不重要"。IN_SCOPE / OUT_OF_SCOPE 由文件归属(2.4)决定,与 Cx 无关。
| 等级 | 判定 | 方案形态 |
|---|
| Cx1 易修 | 改 1-2 个文件,不跨包,不改 exports | 直接修 |
| Cx2 适中 | 改 3-5 个文件,跨 1-2 个包,exports 不变 | 最小修复 + 可选彻底方案 |
| Cx3 复杂 | 改 5+ 个文件,跨 3+ 个包,或需改 exports / contract | 必须给三级方案(最小/彻底/重构) |
| Cx4 架构级 | 需新增包 / 重构 store 拓扑 / 改变数据流方向 / 改 codegen 链路 | 只做方案设计,不直接执行 |
判定按顺序检查:
- 修复涉及多少文件?(
Grep 搜所有受影响调用点)
- 是否需改
@gocell/core 的 exports 或 packages/contracts/(codegen 重跑)?
- 是否需新增 Pinia store / 新增 i18n key 命名空间?
- 是否影响路由表 / 全局守卫 / Axios 拦截器?
- 同类问题在其他包是否重复出现?(1 处=局部,3+=系统性)
2.4 当前分支归属判定
判断问题是否属于当前分支/PR 的修复范围。默认当前分支处理。
判定:
git diff --name-only origin/develop...HEAD 获取当前分支改动文件列表
- 对比 finding 涉及文件是否在列表中
- 当前分支有关联 PR(
gh pr view --json title,body)→ 检查 PR 描述是否包含该 finding ID 或关键词
结果:
| 结果 | 条件 | 下一步 |
|---|
| IN_SCOPE | finding 文件在 diff 中,或 PR 描述明确包含该 ID | 当前分支修 |
| RELATED | 文件不在 diff 中但与当前分支功能主题直接相关(同包遗留) | 建议搭车修,标"搭车" |
| OUT_OF_SCOPE | 完全不同的包 / 子系统 | 不在当前分支修;§沟通规则闸门 |
快速规则:当前分支 diff 包含 → IN_SCOPE;同包但 diff 外 → RELATED;不同包 → OUT_OF_SCOPE。
输出含:代码/架构/历史三维度根因、Cx、当前分支归属(含理由)、影响范围、历史修复。
阶段 3:修复方案设计
方案设计原则(贯穿 3.0-3.4;进入阶段 4 / 输出 Cx3+ 方案 / 批量汇总前强制自检)
- 彻底:根因级修复,不留 TODO / FIXME / follow-up;2.2 列出的"同类"一并纳入
- 不向后兼容:直接改签名 / 删字段 / 换实现,不留 deprecation 别名、shim、双路径
- 优雅简洁:最少代码、最少抽象、最少新文件,不预设未来需求
不通过 → 修订;必须保留的违反项 → 显式列入"遗留 / 取舍说明"。默认走彻底方案;Cx2 最小修复仅在 3.2 明确"不能现在做"时启用,必须给升级窗口 + 按 §沟通规则闸门输出 issue 建议命令。批量"搭车修"同样适用。
3.0 对标参考查询(Cx2+ 必须执行)
Cx2+ 问题,先查参考再动手。三层按权威性递减:
- Vue / Pinia / Vue Router 官方文档(含 Pitfalls / Cookbook)→ 有做法必须遵循
- AntD Vue / 关键依赖 Issues / RFC → 检查已知陷阱
- 对标项目(Vben、Pure Admin、AntD Pro Vue 等)→ 参考,可偏离但须注明
决策优先级:层 1 > 层 2 > 层 3 > WebSearch "vue 3 best practice <topic>"
何时跳过:Cx1 全跳过;纯业务 bug 全跳过
不可跳过(即使 Cx2):异步竞态、生命周期 / unmount 清理、SSR 边界、安全(XSS / CSP / token 处理)、a11y 焦点管理
3.1 方案分级
| 等级 | 方案数 | 形态 |
|---|
| Cx1 | 1 | 直接修 |
| Cx2 | 2 | A 最小修复 + B 彻底方案 |
| Cx3 | 3 | A 最小 + B 彻底 + C 重构 |
| Cx4 | 设计文档 | 只输出方案,不执行 |
每方案须含:改动范围、原理、优缺点、遗留(仅最小修复)、预估改动量、参考来源(Cx2+ 必填)。
3.2 时机判断
Q0:是否属于当前分支?(2.4 优先)
| 归属 | 时机 |
|---|
| IN_SCOPE | 当前 PR 修,进 Q1 |
| RELATED | 建议搭车,改动大可 defer |
| OUT_OF_SCOPE | 不修;§沟通规则闸门 |
Q1:现在做还是后面做?(IN_SCOPE / RELATED 继续)
| 推荐 | 判定 |
|---|
| 现在做 | 安全漏洞 / 运行时崩溃 / 阻塞他人 / 改动 ≤ 50 行 |
| 本迭代做 | 有影响不紧急 / 改动 50-200 行 / 不阻塞 |
| 下迭代做 | 设计级问题 / 改动 200+ 行 / 需前置工作 |
| 记录不做 | 理论风险但实际不触发 / 修复代价远大于收益 |
Q2:能不能现在做? 检查已有 issue 依赖、活跃分支冲突、exports 消费方。
Q3:最小修复有效期? 给彻底方案的建议时间窗口。
3.3 详细修复计划
文件级改动清单 + 验证命令:pnpm -F <pkg> typecheck、pnpm -F <pkg> test --run、pnpm -w lint、pnpm -F @gocell/web build(涉及 bundle 影响时)、pnpm codegen && git diff --exit-code packages/contracts/src/(涉及 contract 时)。
3.4 执行决策
| 复杂度 | 条件 | 决策 |
|---|
Cx1 + IN_SCOPE + ≤2 文件 + 不改 exports / contract / 路由表 | 全满足 | [AUTO-FIX] 直接修 |
| Cx2 + IN_SCOPE + 能做 | — | 执行推荐方案 |
| Cx2 + 不能做(有前置) | — | 记录报告,标阻塞 |
| Cx3 / Cx4 | 任何 | 只输出方案,"需人工决策" |
| 任何 + OUT_OF_SCOPE | — | 不修,§沟通规则闸门 |
不可自动执行:异步 / 并发语义变更、exports 修改、新增依赖、数据流方向变更、Cx2+。
仅以下用 AskUserQuestion:测试失败且 4 轮回退仍无法修正;修复中发现新问题超出 scope。
3.5 执行前任务清单(阶段 3 → 4 门禁)
用 TaskCreate 注册每项任务,执行时 TaskUpdate 更新状态。
- 所有 finding 都建 task,OUT_OF_SCOPE 标注
[→ 输出 issue 建议命令;等用户确认]
- 单条 Cx1 IN_SCOPE → 跳过清单直接修;批量或 Cx2+ → 必须建
- 最后两项固定:
commit + push + 闭合/创建 GitHub issues
- 创建后立即执行,不等确认
阶段 4:执行修复
4.1 Commit 格式
在当前分支直接修改。Commit: fix(<scope>): <问题简述> + 根因 + 复杂度 + Refs + Co-Authored-By。
scope = 包短名(access / audit / core / web 等)。安全约束:只 add 修复文件(不 add -A);不 amend。
4.2 Edit-Test Loop
批量并行:4+ 条 finding 按批量模式步骤 7 派发 vue-developer sub-agent,下面循环在每个 sub-agent 内对其分组的 finding 串行执行;单条 / ≤3 条由主 agent 直接执行。
对每个任务:
- TaskUpdate → in_progress
- Read 目标文件
- Edit / Write 修改代码
pnpm -F @gocell/<pkg> typecheck — 类型检查
pnpm -F @gocell/<pkg> test --run -t "<test>" — 立即跑相关测试(含 1.4 复现测试)
- 失败:
- 当前编辑引入 → 立即修正,重回 3
- 暴露后续依赖 → 记录,继续下一步
- 通过 → TaskUpdate → completed → 下一任务
4.3 最终测试
pnpm -w lint
pnpm -w typecheck
pnpm -F @gocell/<pkg> test --run
pnpm codegen && git diff --exit-code packages/contracts/src/
pnpm -F @gocell/web build
4.4 测试失败处理(分层回退)
| Round | 策略 |
|---|
| 1-2 | 在当前方案上迭代修正 |
| 3 | git stash + 切换备选方案 |
| 4 | 回滚(git checkout -- <文件>),Cx1 标 ESCALATE,Cx2 降级最小修复标遗留 |
4.5 验证修复
重新执行阶段 1 的定位,确认:原问题代码已被替换 / 数据流已正确保护 / 测试覆盖了问题场景。
4.6 Git 收尾
步骤 1:提交分支代码
git add 修复涉及的代码文件
- 按 4.1 关联模式 commit → push → PR
步骤 2:更新 GitHub backlog issues
写入前 gh issue list --label backlog --search "<关键词>" 查重。gh issue close / gh issue edit 自动执行;gh issue create 按 §沟通规则闸门走。
Priority 决定(CLI 创建 issue 必须显式贴 --label priority/pX):
- review finding 含
[P0]/[P1]/[P2]/[P3] → 直接采用
- /fix 派生新 finding:默认
priority/p2(常规债务)
priority/p0 红线:仅 incident-driven(线上故障 / 数据完整性 / 安全 CVE),/fix 不默认 P0;如确属红线 → AskUserQuestion 确认升级
| Finding 状态 | /fix 行为 | 命令模板(user 确认后) | body / comment |
|---|
| IN_SCOPE 已修 + 对应已有 issue | 自动执行 | gh issue close <num> --reason completed --comment "Fixed in PR #<NNN>" | — |
| IN_SCOPE 已修 + 无对应 issue | 输出建议命令 + AskUserQuestion | gh issue create --label backlog --label priority/pX --title "..." --body-file <tmp> → 立即 gh issue close <new> --comment "..." | body 含 Found and fixed in PR #<NNN> |
| OUT_OF_SCOPE finding | 输出建议命令,不自动创建 | gh issue create --label backlog --label priority/pX --title "..." --body-file <tmp> → gh issue edit <new> --add-label pkg/<name>,batch/<N> | body 含:现状 / 修复方向 / 涉及文件 / 触发条件 / 来源 |
| /fix 中发现新问题 | 输出建议命令,不自动创建 | 同 OUT_OF_SCOPE | body 含 Discovered via /fix #<original> |
完成后 TaskUpdate → completed。
阶段 5:输出 + 验证
- 诊断报告(未修)
- 修复报告(已修)
- 批量验证(review 报告)
Backlog 验证(4.6 已执行,此处 gh 复核):
- FIXED finding 对应 issue 已 closed + comment 引用了 PR 编号
- OUT_OF_SCOPE finding:按 §沟通规则闸门输出建议命令,必须含
priority/pX + pkg/<name> 或 batch/<N> 至少一个分类 label
- /fix 派生新问题:同 OUT_OF_SCOPE;body 草稿含
Discovered via /fix #<original>
沟通规则
默认按分析结果自动决策。 仅以下情况用 AskUserQuestion:
- 无法定位问题代码
- 测试失败且 4 轮回退后仍无法修正
- 修复过程中发现新问题超出原始 scope
- Cx3 / Cx4 用户追加了
--auto 参数(矛盾,需确认)
- 任何
gh issue create 调用前(OUT_OF_SCOPE / /fix 派生新问题 / 4.6 表格中"输出建议命令"行):先输出建议命令 + body 草稿,再 AskUserQuestion "是否帮你 run 此命令?"。用户拒绝 → 留命令在最终报告供手工 run,/fix 不自动 create
priority/p0 红线升级(incident-driven 或安全 CVE)