zhongwei/gh-penkzhou-swiss-army-knife-plugin-swiss-army-knife
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-penkzhou-swiss-army-knif…/commands/fix-frontend.md
Zhongwei Li 7422bc109d Initial commit
2025-11-30 08:47:07 +08:00

13 KiB
Raw Permalink Blame History

description, argument-hint, allowed-tools
description argument-hint allowed-tools
执行标准化 Frontend Bugfix 工作流（六阶段流程） [--phase=0,1,2,3,4,5|all] [--dry-run]
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 记录所有待处理错误，格式：

- 处理错误 #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 创建文档：

文件路径: [从 init_ctx["config"]["docs"]["bugfix_dir"] 获取]/{YYYY-MM-DD}-{issue-slug}.md

文档模板：

# [问题描述] Bugfix 报告

> 日期：{date}
> 置信度：{confidence}/100

## 1. 问题概述

### 1.1 错误信息
[结构化错误列表]

### 1.2 根因分析
[根因描述 + 证据]

## 2. 修复方案

### 2.1 主方案
[方案描述]

### 2.2 TDD 计划

#### RED Phase
```typescript
// 先写失败测试

GREEN Phase

// 最小实现

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. **用户确认**：关键决策点等待用户反馈
Reference in New Issue View Git Blame Copy Permalink