名称: ai-factory.fix 描述: 修复代码库中的特定bug或问题。支持两种模式 - 立即修复或先计划后修复。无参数时执行现有的FIX_PLAN.md。总是建议测试覆盖并添加日志记录。当用户说“修复bug”、“调试这个”、“某处出错”或粘贴错误消息时使用。 参数提示: <bug描述或错误消息> 允许工具: 读取、写入、编辑、全局搜索、Grep、Bash、询问用户问题、提问 禁用模型调用: false
修复 - Bug修复工作流程
修复代码库中的特定bug或问题。支持两种模式：立即修复或先计划后修复。
工作流程
步骤0: 检查现有修复计划
在任何操作之前，检查是否存在.ai-factory/FIX_PLAN.md。
如果文件存在:
- 读取
.ai-factory/FIX_PLAN.md - 通知用户: “发现现有修复计划。基于计划执行修复。”
- 跳过步骤0.1到步骤1 — 直接进入步骤2: 调查代码库，使用计划作为指导
- 按计划逐步执行
- 修复完全应用并验证后，删除
.ai-factory/FIX_PLAN.md:rm .ai-factory/FIX_PLAN.md - 继续步骤4（验证）、步骤5（测试建议）、步骤6（补丁）
如果文件不存在且$ARGUMENTS为空:
- 告诉用户: “未找到修复计划且未提供问题描述。请提供bug描述（
/ai-factory.fix <描述>）或先创建修复计划。” - 停止。
如果文件不存在且$ARGUMENTS已提供:
- 继续到步骤0.1。
步骤0.1: 加载项目上下文和过往经验
读取.ai-factory/DESCRIPTION.md（如果存在）以理解:
- 技术栈（语言、框架、数据库）
- 项目架构
- 编码规范
读取.ai-factory/patches/中的所有补丁（如果目录存在）:
- 使用
Glob在.ai-factory/patches/中查找所有*.md文件 - 读取每个补丁文件以从过往修复中学习
- 注意重复模式、根本原因和解决方案
- 如果当前问题类似过往补丁 — 应用相同方法或避免相同错误
- 这是你积累的经验。使用它。
步骤1: 理解问题并选择模式
从$ARGUMENTS中识别:
- 错误消息或意外行为
- 发生位置（文件、函数、端点）
- 重现步骤（如果提供）
如果不清晰，询问:
为了有效修复，我需要更多上下文:
1. 预期行为是什么？
2. 实际发生什么？
3. 可以分享错误消息/堆栈跟踪吗？
4. 何时开始发生？
理解问题后，使用AskUserQuestion让用户选择模式:
问题: “你希望如何进行修复？”
选项:
- 立即修复 — 调查并立即应用修复
- 先计划 — 创建修复计划供审查，稍后修复
如果用户选择“先计划”:
- 继续到步骤1.1: 创建修复计划
如果用户选择“立即修复”:
- 跳过步骤1.1，直接继续到步骤2: 调查代码库
步骤1.1: 创建修复计划
调查代码库以理解问题并创建计划。
- 使用Glob/Grep搜索相关文件
- 阅读问题周围的代码
- 跟踪数据流
- 识别根本原因（或最可能候选）
然后创建.ai-factory/FIX_PLAN.md，结构如下:
# 修复计划: [简短标题]
**问题:** [什么被破坏 — 来自用户描述]
**创建时间:** YYYY-MM-DD HH:mm
## 分析
调查期间发现的内容:
- 根本原因（或怀疑的根本原因）
- 受影响文件和函数
- 影响范围
## 修复步骤
实施修复的逐步计划:
1. [ ] 第一步 — 更改内容和原因
2. [ ] 第二步 — ...
3. [ ] 第三步 — ...
## 要修改的文件
- `路径/到/文件.ts` — 需要什么更改
- `路径/到/另一个文件.ts` — 需要什么更改
## 风险和考虑
- 潜在副作用
- 修复后需要验证的事项
- 需要注意的边缘情况
## 测试覆盖
- 应添加什么测试
- 覆盖什么边缘情况
创建计划后，输出:
## 修复计划已创建 ✅
计划已保存到`.ai-factory/FIX_PLAN.md`。
审查计划，准备执行时运行:
/ai-factory.fix
在此停止。不应用修复。
步骤2: 调查代码库
搜索问题:
- 使用Glob/Grep查找相关文件
- 阅读问题周围的代码
- 跟踪数据流
- 检查其他地方的类似模式
寻找:
- 根本原因（不仅仅是症状）
- 可能受影响的相关代码
- 现有错误处理
步骤3: 实施修复
应用修复并添加日志记录:
// ✅ 必需: 在修复周围添加日志记录
console.log('[FIX] 处理用户输入', { userId, input });
try {
// 实际修复
const result = fixedLogic(input);
console.log('[FIX] 成功', { userId, result });
return result;
} catch (error) {
console.error('[FIX] fixedLogic中的错误', {
userId,
input,
error: error.message,
stack: error.stack
});
throw error;
}
日志记录是强制的，因为:
- 用户需要验证修复是否有效
- 如果无效，日志帮助进一步调试
- 反馈循环: 用户提供日志 → 我们迭代
步骤4: 验证修复
- 检查代码是否编译/运行
- 验证逻辑是否正确
- 确保未引入回归错误
步骤5: 建议测试覆盖
总是建议用测试覆盖此情况:
## 修复已应用 ✅
问题: [简短解释]
修复方式: [更改内容]
### 已添加日志记录
修复包括前缀为`[FIX]`的日志记录。
请测试并分享任何日志如果问题持续。
### 推荐: 添加测试
此bug应通过测试覆盖以防止回归:
\`\`\`typescript
describe('函数名', () => {
it('应处理[导致bug的边缘情况]', () => {
// 安排
const input = /* 有问题的输入 */;
// 行动
const result = 函数名(input);
// 断言
expect(result).toBe(/* 预期值 */);
});
});
\`\`\`
你想我创建此测试吗？
- [ ] 是的，创建测试
- [ ] 不，暂时跳过
日志记录要求
所有修复必须包括日志记录:
- 日志前缀: 使用
[FIX]或[FIX:<问题id>]以便轻松过滤 - 日志输入: 处理的数据是什么
- 日志成功: 确认修复有效
- 日志错误: 如果失败，完整上下文
- 可配置: 如果可用，使用LOG_LEVEL
// 修复模式
const LOG_FIX = process.env.LOG_LEVEL === 'debug' || process.env.DEBUG_FIX;
function fixedFunction(input) {
if (LOG_FIX) console.log('[FIX] 输入:', input);
// ... 修复逻辑 ...
if (LOG_FIX) console.log('[FIX] 输出:', result);
return result;
}
示例
示例1: 空引用错误
用户: /ai-factory.fix TypeError: 无法读取undefined的'name'属性在UserProfile中
操作:
- 搜索UserProfile组件/函数
- 找到访问
.name的位置 - 添加空检查并日志记录
- 建议空用户情况的测试
示例2: API返回错误数据
用户: /ai-factory.fix /api/orders 返回空数组给认证用户
操作:
- 找到orders API端点
- 跟踪查询逻辑
- 找到bug（例如，错误过滤器）
- 修复并日志记录
- 建议集成测试
示例3: 表单验证不工作
用户: /ai-factory.fix 邮箱验证接受无效邮箱
操作:
- 找到邮箱验证逻辑
- 检查正则表达式或验证库用法
- 修复验证
- 添加验证失败的日志记录
- 建议带边缘情况的单元测试
重要规则
- 先检查FIX_PLAN.md - 总是在任何操作前检查现有计划
- 计划模式 = 仅计划 - 当用户选择“先计划”时，只创建计划并停止。不修复。
- 执行模式 = 遵循计划 - 当FIX_PLAN.md存在时，逐步遵循，然后删除
- 无报告 - 不创建总结文档（补丁是学习工件，不是报告）
- 总是日志记录 - 每个修复必须有日志以供反馈
- 总是建议测试 - 帮助防止回归错误
- 根本原因 - 修复实际问题，不是症状
- 最小更改 - 不重构无关代码
- 一次一个修复 - 不范围蔓延
- 清理 - 成功修复执行后删除FIX_PLAN.md
修复后
## 修复已应用 ✅
**问题:** [什么被破坏]
**原因:** [为什么被破坏]
**修复:** [更改内容]
**修改的文件:**
- 路径/到/文件.ts (行X)
**已添加日志记录:** 是的，前缀`[FIX]`
**已建议测试:** 是的
请测试修复并分享任何日志如果问题持续。
添加建议的测试:
- [ ] 是的，创建测试
- [ ] 不，跳过
步骤6: 创建自我改进补丁
每次修复后总是创建补丁。 这为未来修复构建知识库。
创建补丁:
-
如果目录不存在，创建目录:
mkdir -p .ai-factory/patches -
使用当前时间戳作为文件名创建补丁文件。 格式:
YYYY-MM-DD-HH.mm.md(例如，2026-02-07-14.30.md) -
使用此模板:
# [描述修复的简短标题]
**日期:** YYYY-MM-DD HH:mm
**文件:** 修改文件列表
**严重性:** 低 | 中 | 高 | 关键
## 问题
什么被破坏。如何表现（错误消息、错误行为）。
具体 — 包括实际错误或症状。
## 根本原因
为什么问题发生。这是最有价值的部分。
不是“什么错了”而是“为什么错”:
- 逻辑错误？为什么逻辑不正确？
- 缺失检查？为什么缺失？
- 错误假设？假设了什么？
- 竞态条件？什么序列导致？
## 解决方案
如何实施修复。关键代码更改和推理。
包括方法，不仅仅是“更改行X”。
## 预防
如何预防此类未来问题:
- 应遵循什么模式/实践？
- 代码审查中应检查什么？
- 什么测试能捕获此问题？
## 标签
用于分类的空格分隔标签，例如:
`#空检查` `#异步` `#验证` `#typescript` `#api` `#数据库`
示例补丁:
# 当用户无头像时UserProfile中的空引用
**日期:** 2026-02-07 14:30
**文件:** src/components/UserProfile.tsx
**严重性:** 中
## 问题
TypeError: 无法读取undefined的'url'属性，当渲染无上传头像的用户的UserProfile时。
## 根本原因
`user.avatar`字段在数据库模式中是可选的，但组件访问`user.avatar.url`时无空检查。这是在提交abc123中添加头像显示时引入的 — 开发者只测试了有头像的用户。
## 解决方案
添加可选链: `user.avatar?.url` 并回退到默认头像URL。同时在Avatar子组件中添加空检查。
## 预防
- 总是检查标记为`nullable` / `optional`的数据库字段是否在UI层处理为空检查
- 添加“空状态”测试用例 — 数据最少的用户
- 考虑访问嵌套可选属性的lint规则
## 标签
`#空检查` `#react` `#可选字段` `#typescript`
这不是可选的。 每次修复生成补丁。补丁是你的学习。
上下文清理
调查、修复和补丁生成后，上下文很重。所有结果已保存 — 建议释放空间:
询问用户问题: 在继续前释放上下文？
选项:
1. /clear — 完全重置（推荐）
2. /compact — 压缩历史
3. 保持原样
不要:
- ❌ 当用户选择“先计划”时应用修复 — 只创建FIX_PLAN.md并停止
- ❌ 在开始时跳过FIX_PLAN.md检查
- ❌ 成功修复执行后留下FIX_PLAN.md — 总是删除它
- ❌ 生成报告或总结（补丁不是报告 — 它们是学习工件）
- ❌ 重构无关代码
- ❌ 修复时添加功能
- ❌ 跳过日志记录
- ❌ 跳过测试建议
- ❌ 跳过补丁创建