Initial commit
This commit is contained in:
Zhongwei Li
433
commands/fix-backend.md
Normal file
433
commands/fix-backend.md
Normal file
@@ -0,0 +1,433 @@
|
||||
---
|
||||
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. **用户确认**：关键决策点等待用户反馈
|
||||
437
commands/fix-e2e.md
Normal file
437
commands/fix-e2e.md
Normal file
@@ -0,0 +1,437 @@
|
||||
---
|
||||
description: 执行标准化 E2E 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 E2E Workflow v2.2
|
||||
|
||||
基于测试失败的端到端用例，执行标准化 bugfix 流程。
|
||||
|
||||
**宣布**："我正在使用 Bugfix E2E 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 调用 e2e-init-collector agent 初始化工作流上下文：
|
||||
|
||||
> 使用 e2e-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"]` |
|
||||
| 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["project_info"]["browser_config"]` |
|
||||
|
||||
**注意**：E2E 测试不需要独立的 `typecheck_command`，类型检查通常集成在构建流程中。
|
||||
|
||||
**init_ctx 持久化**：
|
||||
- `init_ctx` 存储在当前会话内存中
|
||||
- 跨会话恢复时需重新运行 Phase 0
|
||||
- 使用 `--phase=N`（N > 0）跳过时，系统会验证 init_ctx 是否存在
|
||||
|
||||
**可选字段防护**：
|
||||
构建 agent prompt 时，检查可选字段是否为 `null`：
|
||||
- 如果 `init_ctx["project_info"]["git"]` 为 `null`：使用 "(Git 信息不可用)" 替代 git 相关字段
|
||||
- 如果 `init_ctx["project_info"]["browser_config"]` 为 `null`：使用 "(浏览器配置不可用)" 替代
|
||||
- 在 prompt 中明确标注哪些信息因不可用而缺失
|
||||
|
||||
### 0.4 启动 error-analyzer agent
|
||||
|
||||
使用 Task tool 调用 e2e-error-analyzer agent，**使用 init_ctx 中的数据**：
|
||||
|
||||
> 使用 e2e-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"] 获取]
|
||||
> - 浏览器配置: [如果 init_ctx["project_info"]["browser_config"] 非 null，获取配置；否则填 "(浏览器配置不可用)"]
|
||||
|
||||
### 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 调用 e2e-root-cause agent，prompt 示例：
|
||||
|
||||
> 使用 e2e-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 信息不可用)"]
|
||||
> - 浏览器配置: [如果 init_ctx["project_info"]["browser_config"] 非 null，获取配置；否则填 "(浏览器配置不可用)"]
|
||||
|
||||
### 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 调用 e2e-solution agent，prompt 示例：
|
||||
|
||||
> 使用 e2e-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 安全审查
|
||||
|
||||
如果涉及以下文件类型，进行安全审查：
|
||||
|
||||
- 认证流程 (`login`, `auth`, `session`)
|
||||
- 敏感数据展示 (`password`, `token`, `secret`)
|
||||
- 网络拦截 (`intercept`, `route`, `mock`)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```typescript
|
||||
// 先写失败测试
|
||||
```
|
||||
|
||||
#### GREEN Phase
|
||||
|
||||
```typescript
|
||||
// 最小实现
|
||||
```
|
||||
|
||||
#### REFACTOR Phase
|
||||
|
||||
- [ ] 重构项 1
|
||||
- [ ] 重构项 2
|
||||
|
||||
### 2.3 影响分析
|
||||
|
||||
[影响范围]
|
||||
|
||||
### 2.4 风险评估
|
||||
|
||||
[风险列表]
|
||||
|
||||
## 3. 验证计划
|
||||
|
||||
- [ ] E2E 测试通过
|
||||
- [ ] 无视觉回归
|
||||
- [ ] 无功能回归
|
||||
```
|
||||
|
||||
### 3.2 等待用户确认
|
||||
|
||||
**询问用户**：
|
||||
> "Bugfix 方案已生成，请查看 [init_ctx["config"]["docs"]["bugfix_dir"]]/{date}-{issue}.md。
|
||||
> 确认后开始实施，或提出调整意见。"
|
||||
|
||||
如果是 `--dry-run` 模式，到此结束。
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: 实施执行
|
||||
|
||||
### 4.1 启动 executor agent
|
||||
|
||||
使用 Task tool 调用 e2e-executor agent，prompt 示例：
|
||||
|
||||
> 使用 e2e-executor agent 执行 TDD 修复流程：
|
||||
>
|
||||
> ## TDD 计划
|
||||
> [Phase 2 的 TDD 计划]
|
||||
>
|
||||
> ## 执行要求
|
||||
> 1. RED: 先运行测试确认失败
|
||||
> 2. GREEN: 实现最小代码使测试通过
|
||||
> 3. REFACTOR: 重构代码保持测试通过
|
||||
>
|
||||
> ## 验证命令
|
||||
> - [从 init_ctx["config"]["test_command"] 获取]
|
||||
> - [从 init_ctx["config"]["lint_command"] 获取]
|
||||
|
||||
### 4.2 批次报告
|
||||
|
||||
每批完成后向用户报告进度，等待确认后继续。
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: 验证与沉淀
|
||||
|
||||
### 5.1 启动 quality-gate agent
|
||||
|
||||
使用 Task tool 调用 e2e-quality-gate agent，prompt 示例：
|
||||
|
||||
> 使用 e2e-quality-gate agent 执行质量门禁检查：
|
||||
>
|
||||
> ## 变更文件
|
||||
> [变更文件列表]
|
||||
>
|
||||
> ## 门禁标准
|
||||
> - 所有 E2E 测试通过
|
||||
> - 无视觉回归
|
||||
> - lint 必须通过
|
||||
> - 无功能回归
|
||||
|
||||
### 5.2 启动 knowledge agent
|
||||
|
||||
如果质量门禁通过，使用 Task tool 调用 e2e-knowledge agent，prompt 示例：
|
||||
|
||||
> 使用 e2e-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. **用户确认**：关键决策点等待用户反馈
|
||||
7. **环境隔离**：确保测试环境稳定可重现
|
||||
439
commands/fix-frontend.md
Normal file
439
commands/fix-frontend.md
Normal file
@@ -0,0 +1,439 @@
|
||||
---
|
||||
description: 执行标准化 Frontend 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 Frontend Workflow v2.2
|
||||
|
||||
基于测试失败的前端用例，执行标准化 bugfix 流程。
|
||||
|
||||
**宣布**："我正在使用 Bugfix Frontend 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 调用 frontend-init-collector agent 初始化工作流上下文：
|
||||
|
||||
> 使用 frontend-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["project_info"]["test_framework"]` |
|
||||
| 构建工具 | `init_ctx["project_info"]["bundler"]` |
|
||||
| 包管理器 | `init_ctx["project_info"]["package_manager"]` |
|
||||
|
||||
**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 调用 frontend-error-analyzer agent，**使用 init_ctx 中的数据**：
|
||||
|
||||
> 使用 frontend-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"] 获取]
|
||||
> - 构建工具: [从 init_ctx["project_info"]["bundler"] 获取]
|
||||
|
||||
### 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 调用 frontend-root-cause agent，prompt 示例：
|
||||
|
||||
> 使用 frontend-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 信息不可用)"]
|
||||
> - 测试框架: [从 init_ctx["project_info"]["test_framework"] 获取]
|
||||
> - 构建工具: [从 init_ctx["project_info"]["bundler"] 获取]
|
||||
|
||||
### 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 调用 frontend-solution agent，prompt 示例：
|
||||
|
||||
> 使用 frontend-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`)
|
||||
- API 调用 (`api`, `fetch`, `axios`)
|
||||
- 用户输入处理（XSS 风险）
|
||||
- 敏感数据展示（localStorage, sessionStorage）
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```typescript
|
||||
// 先写失败测试
|
||||
```
|
||||
|
||||
#### GREEN Phase
|
||||
|
||||
```typescript
|
||||
// 最小实现
|
||||
```
|
||||
|
||||
#### 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 调用 frontend-executor agent，prompt 示例：
|
||||
|
||||
> 使用 frontend-executor agent 执行 TDD 修复流程：
|
||||
>
|
||||
> ## TDD 计划
|
||||
> [Phase 2 solution 的 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 调用 frontend-quality-gate agent，prompt 示例：
|
||||
|
||||
> 使用 frontend-quality-gate agent 执行质量门禁检查：
|
||||
>
|
||||
> ## 变更文件
|
||||
> [变更文件列表]
|
||||
>
|
||||
> ## 门禁标准
|
||||
> - 覆盖率 >= 90%
|
||||
> - 新增代码覆盖率 = 100%
|
||||
> - lint/typecheck 必须通过
|
||||
> - 无回归
|
||||
|
||||
### 5.2 启动 knowledge agent
|
||||
|
||||
如果质量门禁通过，启动 frontend-knowledge agent 进行知识沉淀：
|
||||
|
||||
> 使用 frontend-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. **用户确认**：关键决策点等待用户反馈
|
||||
202
commands/release.md
Normal file
202
commands/release.md
Normal file
@@ -0,0 +1,202 @@
|
||||
---
|
||||
description: 自动化发版流程：更新 CHANGELOG、plugin.json、创建 git tag 并推送
|
||||
argument-hint: "<version> [--no-push] [--dry-run]"
|
||||
allowed-tools: ["Read", "Write", "Edit", "Bash", "AskUserQuestion"]
|
||||
---
|
||||
|
||||
# Release Command
|
||||
|
||||
自动化插件发版流程，包括更新文档、版本号、创建 tag 和推送。
|
||||
|
||||
**宣布**："我正在使用 release 命令执行自动化发版流程。"
|
||||
|
||||
---
|
||||
|
||||
## 参数解析
|
||||
|
||||
从用户输入中解析参数：
|
||||
|
||||
- `<version>`：新版本号（必需，格式：X.Y.Z，例如 0.3.0）
|
||||
- `--no-push`：不自动推送 tag 到远程仓库
|
||||
- `--dry-run`：预览操作但不实际执行
|
||||
|
||||
**示例**：
|
||||
- `/release 0.3.0` - 发布 0.3.0 版本并推送
|
||||
- `/release 0.3.0 --no-push` - 发布 0.3.0 但不推送
|
||||
- `/release 0.3.0 --dry-run` - 预览发布操作
|
||||
|
||||
---
|
||||
|
||||
## 步骤 1: 参数验证
|
||||
|
||||
### 1.1 验证版本号格式
|
||||
|
||||
检查版本号是否符合语义化版本格式（X.Y.Z）：
|
||||
|
||||
```bash
|
||||
if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "错误：版本号格式不正确。应为 X.Y.Z 格式（例如：0.3.0）"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### 1.2 读取当前版本
|
||||
|
||||
读取 `.claude-plugin/plugin.json` 获取当前版本号，确保新版本号大于当前版本。
|
||||
|
||||
**验证规则**：
|
||||
- 如果当前是 0.2.0，新版本应该是 0.2.1、0.3.0 或 1.0.0
|
||||
- 不允许降级版本或使用相同版本号
|
||||
|
||||
---
|
||||
|
||||
## 步骤 2: 工作区检查
|
||||
|
||||
### 2.1 检查 git 状态
|
||||
|
||||
确保工作区干净，避免意外提交未完成的工作：
|
||||
|
||||
```bash
|
||||
# 检查是否有未提交的更改
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
如果有未提交的更改，询问用户：
|
||||
- "检测到未提交的更改。是否继续？这些更改将包含在发版提交中。"
|
||||
- 选项：[继续] [取消]
|
||||
|
||||
### 2.2 验证 CHANGELOG.md
|
||||
|
||||
读取 `CHANGELOG.md` 并验证：
|
||||
1. 文件存在
|
||||
2. 包含 `## [未发布]` 区域
|
||||
3. [未发布] 区域下有实际内容（不只是空标题）
|
||||
|
||||
如果 [未发布] 区域为空，警告用户：
|
||||
- "CHANGELOG.md 的 [未发布] 区域为空。是否继续发版？"
|
||||
- 选项：[继续] [取消]
|
||||
|
||||
---
|
||||
|
||||
## 步骤 3: 更新文件
|
||||
|
||||
### 3.1 更新 CHANGELOG.md
|
||||
|
||||
执行以下转换：
|
||||
|
||||
1. **添加新版本标题**：
|
||||
```markdown
|
||||
## [未发布]
|
||||
|
||||
## [X.Y.Z] - YYYY-MM-DD
|
||||
```
|
||||
将 [未发布] 下的内容移到新版本标题下。
|
||||
|
||||
2. **更新底部链接**：
|
||||
```markdown
|
||||
[未发布]: https://github.com/penkzhou/swiss-army-knife-plugin/compare/vX.Y.Z...HEAD
|
||||
[X.Y.Z]: https://github.com/penkzhou/swiss-army-knife-plugin/compare/vPREV...vX.Y.Z
|
||||
```
|
||||
|
||||
**实现**：使用 Read 读取文件，使用 Edit 工具进行精确替换。
|
||||
|
||||
### 3.2 更新 plugin.json
|
||||
|
||||
更新 `.claude-plugin/plugin.json` 中的版本号：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "X.Y.Z"
|
||||
}
|
||||
```
|
||||
|
||||
**实现**：使用 Read 和 Edit 工具进行精确替换。
|
||||
|
||||
---
|
||||
|
||||
## 步骤 4: Git 操作
|
||||
|
||||
### 4.1 创建提交
|
||||
|
||||
**如果不是 dry-run 模式**：
|
||||
|
||||
```bash
|
||||
git add CHANGELOG.md .claude-plugin/plugin.json
|
||||
git commit -m "chore: release version X.Y.Z"
|
||||
```
|
||||
|
||||
### 4.2 创建 tag
|
||||
|
||||
```bash
|
||||
git tag -a vX.Y.Z -m "Release version X.Y.Z"
|
||||
```
|
||||
|
||||
### 4.3 推送（可选）
|
||||
|
||||
**如果没有 --no-push 标志**：
|
||||
|
||||
```bash
|
||||
git push origin main
|
||||
git push origin vX.Y.Z
|
||||
```
|
||||
|
||||
**如果有 --no-push 标志**：
|
||||
|
||||
提示用户：
|
||||
```
|
||||
✅ 发版完成！Tag vX.Y.Z 已创建。
|
||||
|
||||
要推送到远程仓库，请运行：
|
||||
git push origin main
|
||||
git push origin vX.Y.Z
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤 5: 完成报告
|
||||
|
||||
输出发版摘要：
|
||||
|
||||
```
|
||||
🎉 版本 X.Y.Z 发布成功！
|
||||
|
||||
✅ 已更新 CHANGELOG.md
|
||||
✅ 已更新 .claude-plugin/plugin.json
|
||||
✅ 已创建 git commit
|
||||
✅ 已创建 tag vX.Y.Z
|
||||
[✅ 已推送到远程仓库] （如果执行了推送）
|
||||
|
||||
下一步：
|
||||
1. 在 GitHub 上创建 Release：https://github.com/penkzhou/swiss-army-knife-plugin/releases/new?tag=vX.Y.Z
|
||||
2. 更新 CHANGELOG.md 的 [未发布] 区域，记录下一个版本的变更
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
在每个步骤中，如果遇到错误：
|
||||
1. 清晰地报告错误信息
|
||||
2. 如果已经修改了文件，提供恢复命令：
|
||||
```bash
|
||||
git checkout CHANGELOG.md .claude-plugin/plugin.json
|
||||
git tag -d vX.Y.Z # 如果 tag 已创建
|
||||
```
|
||||
3. 停止执行，不继续后续步骤
|
||||
|
||||
---
|
||||
|
||||
## Dry-run 模式
|
||||
|
||||
如果指定了 `--dry-run`：
|
||||
1. 执行所有验证步骤
|
||||
2. 显示将要进行的操作（不实际执行）：
|
||||
```
|
||||
[DRY RUN] 将执行以下操作：
|
||||
1. 更新 CHANGELOG.md：将 [未发布] 内容移到 [X.Y.Z] - YYYY-MM-DD
|
||||
2. 更新 .claude-plugin/plugin.json：version: "0.2.0" → "X.Y.Z"
|
||||
3. 创建 git commit：chore: release version X.Y.Z
|
||||
4. 创建 git tag：vX.Y.Z
|
||||
[5. 推送到远程仓库] （如果没有 --no-push）
|
||||
```
|
||||
3. 不修改任何文件，不执行 git 操作
|
||||
Reference in New Issue
Block a user