434 lines
12 KiB
Markdown
434 lines
12 KiB
Markdown
---
|
||
description: 执行标准化 Backend Bugfix 工作流（六阶段流程）
|
||
argument-hint: "[--phase=0,1,2,3,4,5|all] [--dry-run]"
|
||
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Task", "TodoWrite", "AskUserQuestion"]
|
||
---
|
||
|
||
# Bugfix Backend Workflow v2.2
|
||
|
||
基于测试失败的后端用例，执行标准化 bugfix 流程。
|
||
|
||
**宣布**："我正在使用 Bugfix Backend v2.2 工作流进行问题修复。"
|
||
|
||
---
|
||
|
||
## 参数解析
|
||
|
||
从用户输入中解析参数：
|
||
|
||
- `--phase=X,Y` 或 `--phase=all`：指定执行阶段（默认 all）
|
||
- `--dry-run`：只分析不执行修改
|
||
|
||
### Phase 依赖关系验证
|
||
|
||
**Phase 依赖关系**：
|
||
|
||
| Phase | 依赖 | 说明 |
|
||
| ----- | ---- | ---- |
|
||
| 0 | 无 | 可独立运行 |
|
||
| 1 | Phase 0 输出 | 需要结构化错误数据 |
|
||
| 2 | Phase 1 输出 | 需要根因分析结果 |
|
||
| 3 | Phase 2 输出 | 需要修复方案 |
|
||
| 4 | Phase 3 输出 + 用户确认 | 需要 bugfix 文档 |
|
||
| 5 | Phase 4 输出 | 需要执行结果 |
|
||
|
||
**跳过 Phase 时的验证**：
|
||
|
||
如果指定 `--phase=N`（N > 0），检查是否存在前置 Phase 的输出：
|
||
- **不存在前置输出**：报错 "Phase N 依赖 Phase M 输出，请先运行 --phase=0,...,M 或使用 --phase=all"
|
||
- **存在前置输出**：继续执行
|
||
|
||
---
|
||
|
||
## Phase 0: 问题收集与分类
|
||
|
||
### 0.1 启动 init-collector agent
|
||
|
||
使用 Task tool 调用 backend-init-collector agent 初始化工作流上下文：
|
||
|
||
> 使用 backend-init-collector agent 初始化 bugfix 工作流：
|
||
>
|
||
> ## 任务
|
||
> 1. 加载配置（defaults.yaml + 项目配置深度合并）
|
||
> 2. 收集测试失败输出（如果用户未提供）
|
||
> 3. 收集项目信息（Git 状态、目录结构、依赖信息）
|
||
>
|
||
> ## 用户提供的测试输出（如有）
|
||
> [如果用户提供了测试输出，粘贴在这里；否则留空让 agent 自动运行测试]
|
||
|
||
### 0.2 验证 init-collector 输出
|
||
|
||
验证 init-collector 返回的 JSON 格式：
|
||
|
||
1. **格式验证**：确保返回有效 JSON
|
||
2. **必填字段检查**：
|
||
- `config.test_command` 存在且非空
|
||
- `config.docs.bugfix_dir` 存在
|
||
- `test_output.raw` 存在且非空
|
||
- `test_output.status` 为有效值（`test_failed` | `command_failed` | `success`）
|
||
- `project_info.plugin_root` 存在
|
||
3. **警告展示**：
|
||
- 如果 `warnings` 数组存在且非空，**立即向用户展示所有警告**：
|
||
```
|
||
⚠️ 初始化警告：
|
||
- [{code}] {message}
|
||
影响：{impact}
|
||
```
|
||
- 如果任何警告的 `critical: true`，暂停询问用户是否继续
|
||
4. **失败处理**：
|
||
- 格式无效：**停止**，报告 "Init collector 输出格式无效"
|
||
- 必填字段缺失：**停止**，报告缺失的字段
|
||
- `test_output.status` 为 `command_failed`：**停止**，报告 "测试命令执行失败，请检查环境配置"
|
||
|
||
### 0.3 提取配置变量
|
||
|
||
从 init-collector 输出中提取配置变量，存储为 `init_ctx`，用于后续 Phase。
|
||
|
||
**常用路径快捷引用**：
|
||
|
||
| 数据 | 路径 |
|
||
|------|------|
|
||
| 测试命令 | `init_ctx["config"]["test_command"]` |
|
||
| Lint 命令 | `init_ctx["config"]["lint_command"]` |
|
||
| 类型检查命令 | `init_ctx["config"]["typecheck_command"]` |
|
||
| Bugfix 文档目录 | `init_ctx["config"]["docs"]["bugfix_dir"]` |
|
||
| 最佳实践目录 | `init_ctx["config"]["docs"]["best_practices_dir"]` |
|
||
| 测试输出 | `init_ctx["test_output"]["raw"]` |
|
||
| 测试状态 | `init_ctx["test_output"]["status"]` |
|
||
| Git 变更文件 | `init_ctx["project_info"]["git"]["modified_files"]` |
|
||
|
||
**init_ctx 持久化**：
|
||
- `init_ctx` 存储在当前会话内存中
|
||
- 跨会话恢复时需重新运行 Phase 0
|
||
- 使用 `--phase=N`（N > 0）跳过时，系统会验证 init_ctx 是否存在
|
||
|
||
**可选字段防护**：
|
||
构建 agent prompt 时，检查可选字段是否为 `null`：
|
||
- 如果 `init_ctx["project_info"]["git"]` 为 `null`：使用 "(Git 信息不可用)" 替代 git 相关字段
|
||
- 在 prompt 中明确标注哪些信息因不可用而缺失
|
||
|
||
### 0.4 启动 error-analyzer agent
|
||
|
||
使用 Task tool 调用 backend-error-analyzer agent，**使用 init_ctx 中的数据**：
|
||
|
||
> 使用 backend-error-analyzer agent 分析以下测试失败输出，完成错误解析、分类、历史匹配和文档匹配。
|
||
>
|
||
> ## 测试输出
|
||
> [从 init_ctx["test_output"]["raw"] 获取]
|
||
>
|
||
> ## 项目路径
|
||
> - bugfix 文档: [从 init_ctx["config"]["docs"]["bugfix_dir"] 获取]
|
||
> - troubleshooting: [从 init_ctx["config"]["docs"]["best_practices_dir"] 获取]/troubleshooting.md
|
||
>
|
||
> ## 项目上下文（供参考）
|
||
> - Git 变更文件: [如果 init_ctx["project_info"]["git"] 非 null，从 modified_files 获取；否则填 "(Git 信息不可用)"]
|
||
> - 最近 commit: [如果 init_ctx["project_info"]["git"] 非 null，从 last_commit 获取；否则填 "(Git 信息不可用)"]
|
||
> - 测试框架: [从 init_ctx["project_info"]["test_framework"] 获取]
|
||
|
||
### 0.5 验证 error-analyzer 输出
|
||
|
||
验证 error-analyzer 返回的 JSON 格式：
|
||
|
||
1. **格式验证**：确保返回有效 JSON
|
||
2. **必填字段检查**：
|
||
- `errors` 数组存在且非空
|
||
- 每个 error 包含 `id`, `file`, `category`
|
||
- `summary.total` 与 `errors.length` 一致
|
||
3. **失败处理**：
|
||
- 格式无效：**停止**，报告 "Error analyzer 输出格式无效"
|
||
- 必填字段缺失：**停止**，报告缺失的字段
|
||
- 空结果：报告 "未检测到错误，请确认测试是否真的失败"
|
||
|
||
### 0.6 记录到 TodoWrite
|
||
|
||
使用 TodoWrite 记录所有待处理错误，格式：
|
||
|
||
```text
|
||
- 处理错误 #1: [文件:行号] [错误类型] - [简述]
|
||
- 处理错误 #2: ...
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1: 诊断分析
|
||
|
||
### 1.1 启动 root-cause agent
|
||
|
||
使用 Task tool 调用 backend-root-cause agent，prompt 示例：
|
||
|
||
> 使用 backend-root-cause agent 进行根因分析：
|
||
>
|
||
> ## 结构化错误
|
||
> [Phase 0 error-analyzer 的输出]
|
||
>
|
||
> ## 相关代码
|
||
> [使用 Read 获取的相关代码]
|
||
>
|
||
> ## 参考诊断文档
|
||
> [从 init_ctx["config"]["docs"]["best_practices_dir"] 获取]/troubleshooting.md
|
||
>
|
||
> ## 项目上下文（供参考）
|
||
> - Git 变更文件: [如果 init_ctx["project_info"]["git"] 非 null，从 modified_files 获取；否则填 "(Git 信息不可用)"]
|
||
> - 最近 commit: [如果 init_ctx["project_info"]["git"] 非 null，从 last_commit 获取；否则填 "(Git 信息不可用)"]
|
||
|
||
### 1.2 验证 Agent 输出
|
||
|
||
验证 root-cause 返回的 JSON 格式：
|
||
|
||
1. **必填字段检查**：
|
||
- `root_cause.description` 非空
|
||
- `confidence.score` 存在
|
||
- `category` 为有效类型
|
||
2. **失败处理**：
|
||
- 格式无效：**停止**，报告错误
|
||
- 必填字段缺失：**停止**，报告缺失的字段
|
||
|
||
### 1.3 置信度验证与决策
|
||
|
||
**验证置信度分数**：
|
||
|
||
1. 检查 `confidence.score` 存在且为数字
|
||
2. 检查范围 0-100
|
||
|
||
**无效分数处理**：
|
||
- 分数缺失：**停止**，报告 "Root-cause agent 未返回置信度分数"
|
||
- 非数字：**停止**，报告 "置信度分数格式无效"
|
||
- 超出范围（<0 或 >100）：**停止**，报告 "置信度分数超出有效范围 (0-100)"
|
||
|
||
**有效分数决策**：
|
||
|
||
| 置信度 | 行为 |
|
||
| -------- | ------ |
|
||
| >= 60 | 继续 Phase 2 |
|
||
| 40-59 | **暂停**，向用户展示分析结果并询问是否继续 |
|
||
| < 40 | **停止**，向用户询问更多信息 |
|
||
|
||
---
|
||
|
||
## Phase 2: 方案设计
|
||
|
||
### 2.1 启动 solution agent
|
||
|
||
使用 Task tool 调用 backend-solution agent，prompt 示例：
|
||
|
||
> 使用 backend-solution agent 设计修复方案：
|
||
>
|
||
> ## 根因分析
|
||
> [Phase 1 root-cause 的输出]
|
||
>
|
||
> ## 参考最佳实践
|
||
> - [从 init_ctx["config"]["docs"]["best_practices_dir"] 获取]/README.md
|
||
> - [从 init_ctx["config"]["docs"]["best_practices_dir"] 获取]/implementation-guide.md
|
||
|
||
### 2.2 安全审查
|
||
|
||
如果涉及以下文件类型，进行安全审查：
|
||
|
||
- 认证相关 (`auth`, `login`, `token`, `jwt`, `session`)
|
||
- 数据库操作 (`query`, `sql`, `orm`, `model`)
|
||
- API 端点 (`endpoint`, `route`, `api`)
|
||
- 用户输入处理 (`request`, `body`, `params`)
|
||
|
||
---
|
||
|
||
## Phase 3: 方案文档化
|
||
|
||
### 3.1 生成 Bugfix 文档
|
||
|
||
如果不是 `--dry-run` 模式，使用 Write tool 创建文档：
|
||
|
||
```text
|
||
文件路径: [从 init_ctx["config"]["docs"]["bugfix_dir"] 获取]/{YYYY-MM-DD}-{issue-slug}.md
|
||
```
|
||
|
||
文档模板：
|
||
|
||
```markdown
|
||
# [问题描述] Bugfix 报告
|
||
|
||
> 日期：{date}
|
||
> 置信度：{confidence}/100
|
||
|
||
## 1. 问题概述
|
||
|
||
### 1.1 错误信息
|
||
[结构化错误列表]
|
||
|
||
### 1.2 根因分析
|
||
[根因描述 + 证据]
|
||
|
||
## 2. 修复方案
|
||
|
||
### 2.1 主方案
|
||
[方案描述]
|
||
|
||
### 2.2 TDD 计划
|
||
|
||
#### RED Phase
|
||
```python
|
||
# 先写失败测试
|
||
```
|
||
|
||
#### GREEN Phase
|
||
|
||
```python
|
||
# 最小实现
|
||
```
|
||
|
||
#### REFACTOR Phase
|
||
|
||
- [ ] 重构项 1
|
||
- [ ] 重构项 2
|
||
|
||
### 2.3 影响分析
|
||
|
||
[影响范围]
|
||
|
||
### 2.4 风险评估
|
||
|
||
[风险列表]
|
||
|
||
## 3. 验证计划
|
||
|
||
- [ ] 单元测试通过
|
||
- [ ] 覆盖率 >= 90%
|
||
- [ ] 无回归
|
||
```
|
||
|
||
### 3.2 等待用户确认
|
||
|
||
**询问用户**：
|
||
> "Bugfix 方案已生成，请查看 [init_ctx["config"]["docs"]["bugfix_dir"]]/{date}-{issue}.md。
|
||
> 确认后开始实施，或提出调整意见。"
|
||
|
||
如果是 `--dry-run` 模式，到此结束。
|
||
|
||
---
|
||
|
||
## Phase 4: 实施执行
|
||
|
||
### 4.1 启动 executor agent
|
||
|
||
使用 Task tool 调用 backend-executor agent，prompt 示例：
|
||
|
||
> 使用 backend-executor agent 执行 TDD 修复流程：
|
||
>
|
||
> ## TDD 计划
|
||
> [Phase 2 的 TDD 计划]
|
||
>
|
||
> ## 执行要求
|
||
> 1. RED: 先运行测试确认失败
|
||
> 2. GREEN: 实现最小代码使测试通过
|
||
> 3. REFACTOR: 重构代码保持测试通过
|
||
>
|
||
> ## 验证命令
|
||
> - [从 init_ctx["config"]["test_command"] 获取] FILTER={test_file}
|
||
> - [从 init_ctx["config"]["lint_command"] 获取]
|
||
> - [从 init_ctx["config"]["typecheck_command"] 获取]
|
||
|
||
### 4.2 批次报告
|
||
|
||
每批完成后向用户报告进度，等待确认后继续。
|
||
|
||
---
|
||
|
||
## Phase 5: 验证与沉淀
|
||
|
||
### 5.1 启动 quality-gate agent
|
||
|
||
使用 Task tool 调用 backend-quality-gate agent，prompt 示例：
|
||
|
||
> 使用 backend-quality-gate agent 执行质量门禁检查：
|
||
>
|
||
> ## 变更文件
|
||
> [变更文件列表]
|
||
>
|
||
> ## 门禁标准
|
||
> - 覆盖率 >= 90%
|
||
> - 新增代码覆盖率 = 100%
|
||
> - lint/typecheck 必须通过
|
||
> - 无回归
|
||
|
||
### 5.2 启动 knowledge agent
|
||
|
||
如果质量门禁通过，使用 Task tool 调用 backend-knowledge agent，prompt 示例：
|
||
|
||
> 使用 backend-knowledge agent 提取可沉淀的知识：
|
||
>
|
||
> ## 修复过程
|
||
> [完整修复过程记录]
|
||
>
|
||
> ## 现有文档
|
||
> - [从 init_ctx["config"]["docs"]["bugfix_dir"] 获取]
|
||
> - [从 init_ctx["config"]["docs"]["best_practices_dir"] 获取]
|
||
>
|
||
> ## 判断标准
|
||
> - 是否是新发现的问题模式？
|
||
> - 解决方案是否可复用？
|
||
> - 是否有值得记录的教训？
|
||
|
||
### 5.3 完成报告
|
||
|
||
汇总整个修复过程，向用户报告：
|
||
|
||
- 修复的问题列表
|
||
- 验证结果
|
||
- 沉淀的知识（如有）
|
||
|
||
---
|
||
|
||
## 异常处理
|
||
|
||
### E1: 置信度低（< 40）
|
||
|
||
- **行为**：停止分析，向用户询问更多信息
|
||
- **输出**：已收集的信息 + 需要澄清的问题
|
||
|
||
### E2: 安全问题
|
||
|
||
- **行为**：阻塞实施，立即报告
|
||
- **输出**：安全漏洞详情 + 修复建议
|
||
|
||
### E3: 测试持续失败
|
||
|
||
- **行为**：最多重试 3 次，然后报告
|
||
- **输出**：失败详情 + 可能原因 + 建议
|
||
|
||
### E4: 覆盖率不达标
|
||
|
||
- **行为**：补充测试用例
|
||
- **输出**：缺失覆盖的代码区域
|
||
|
||
### Agent 调用错误处理
|
||
|
||
所有 Task 工具调用 sub-agent 时应遵循以下错误处理：
|
||
|
||
#### AE1: Agent 调用超时
|
||
|
||
- **检测**：Task 工具超过 30 分钟未返回
|
||
- **行为**：**停止**当前 Phase
|
||
- **输出**："{agent_name} agent 响应超时，可能由于项目复杂度过高或网络问题。建议：1) 简化问题范围 2) 手动提供部分信息 3) 重试"
|
||
|
||
#### AE2: Agent 输出截断
|
||
|
||
- **检测**：返回的 JSON 不完整（解析失败）
|
||
- **行为**：**停止**当前 Phase
|
||
- **输出**："{agent_name} agent 输出被截断，请重试或简化问题范围"
|
||
|
||
#### AE3: Agent 未返回预期格式
|
||
|
||
- **检测**：返回内容不是 JSON 或缺少必要字段
|
||
- **行为**：**停止**当前 Phase
|
||
- **输出**："{agent_name} agent 返回格式异常，预期 JSON 包含 {required_fields}，实际收到：{content_preview}"
|
||
|
||
---
|
||
|
||
## 关键原则
|
||
|
||
1. **TodoWrite 跟踪**：记录所有待处理项，防止遗漏
|
||
2. **置信度驱动**：低置信度时停止，不要猜测
|
||
3. **TDD 强制**：所有代码变更必须先写测试
|
||
4. **增量验证**：每步后验证，不要积累问题
|
||
5. **知识沉淀**：有价值的经验必须记录
|
||
6. **用户确认**：关键决策点等待用户反馈
|