AI 智能体犯错模式库与自我纠错纪律
从一次真实工作会话的 7 个错误中提炼。核心发现：翻车主力不是能力问题，是"库里有的知识没用上"——7 个错误中 3 个是"笔记在、检索失败"。 适用：任何带持久记忆/笔记系统的 AI 智能体（self-improving agent、个人助理、长会话助手）。
何时使用（When to Use）
- 搭建或改进 agent 的记忆/笔记系统时（想预知它会怎么犯错）
- agent 反复犯同类错误、用户纠正后不长记性时（对照本库找模式）
- 做错误复盘/错误档案时（用本库的分类框架归因）
- 给 agent 设计"动手前自检"流程时
何时不使用（When NOT to Use）
- 纯一次性的无状态任务（无记忆系统，模式不适用）
- 用户只需要一次性问题解答
一、核心模式（4 类，附真实案例）
模式 M1 · 记忆检索失败（占比最高，最隐蔽）
症状：库里明明有现成记录，动手时却凭（不可靠的）直觉或外部信息行事。
真实案例（一次会话三连中招）：
- 把"IP+账号组合锁定"说成"账号被锁，需重置密码"——锁定维度笔记 20 天前就记了
- 把目标站管理员叫成"站长"——身份备注一直在用户档案里
- 新会话打 API 连续 404 两次——API Base 双路径的坑记录在案
根因：agent 每次唤醒是"无状态"的，笔记不会自动进上下文；服务端/外部的响应文案会反向诱导（"账号已锁定"话说满，实际只是 IP 组合锁定——照单全收就翻车）。
对策（固化纪律）：
- 动已知目标/已知机制前，先 grep 自己的笔记。检索词映射表（遇到 X → 查 Y）：
- 登录锁定 / 被锁 → 查笔记"IP 锁定"
- 报告署名 / 称呼 → 查笔记"身份"
- 新会话调用已知 API → 查笔记"API Base / 双路径"
- 生成文件 → 查笔记"编码 / CRLF"
- 发布 / 推送 → 查笔记"版本链 / 审核机制"
- 事实判断以本地档案为准，外部响应文案只是线索。文案与档案冲突时，先信档案，再验证。
- 一次 grep 几秒钟，远比翻车后修正+道歉便宜。
模式 M2 · 流程步骤缺失
症状：单步操作都对，但前置确认步骤不在执行路径里。
真实案例：
- 安全测试发现"API 返回敏感字段"直接定级，没核对前端界面是否本就公开展示 → 误报漏洞
- 故意发送错误凭据前没确认该 IP 组合的失败计数存量 → 1 次试探触发历史累积的第 5 次锁定
对策：
- 每类高频操作写前置检查清单，执行时过一遍（不是凭"记得"）
- 判断类动作（定级/定责/断言）必须有对照步骤：API 说泄露 → 先看界面；测试要失败 → 先查存量
- 清单放在工作区可见处，随错误复盘持续增补
模式 M3 · 编辑锚点错误（文件操作规范）
症状：用"文件末尾/最后一行"当锚点追加内容，new_str 忘记携带 old_str 原文 → 原内容被覆盖。同一会话内连犯两次说明这是模式不是手滑。
对策：
- 追加内容的标准姿势：old_str = 现有最后一行，new_str = 原行 + 新行（永远带着旧内容走）
- 追加后立即回读文件确认结构（层级/顺序）未乱——尤其编辑层级敏感的笔记（缩进/列表嵌套）
- 长笔记的追加优先选"语义锚点"（小节标题行），别用"最后一行"（最后一行经常是子项，追加会破坏层级）
模式 M4 · 低效排查路径
症状：工具坏了绕着修（正则全文捞字符串七八个回合），其实正确答案在集中的定义文件里（路由表 30 秒读完）。
对策：
- 排查前先问：这类信息有没有"集中定义处"（路由表/配置文件/schema/清单）？有 → 直接读，无 → 再全文搜
- 工具报错时读它的源码目录结构（
dist/下找routes.js、schema/、config.js这类名字），比黑盒猜快 - 绕行方案（直接调底层 API）成功后，记录端点和姿势，下次跳过坏工具直接走通途
二、错误归档方法（复盘框架）
每次翻车后写错误档案，格式五要素：
# YYYY-MM-DD 主题
## 错误清单（逐条：经过 / 真相 / 根因 / 对策）
## 根因归因（用模式分类表统计占比）
## 已落地的固化（改了哪些规则/清单/笔记）
根因分类表（对照打标签）：
| 模式 | 识别特征 | 修复位置 |
|---|---|---|
| M1 记忆检索失败 | "笔记里有，当时没查" | 检索词映射表 + 动手前 grep 纪律 |
| M2 流程步骤缺失 | "单步都对，链条断了" | 前置检查清单增补 |
| M3 编辑锚点错误 | "覆盖了不该覆盖的" | 编辑姿势规范 + 回读习惯 |
| M4 低效路径 | "绕远了但到了" | 集中定义处索引 |
归因纪律：
- 不用"粗心""疏忽"当根因——它们是症状不是原因，追问"为什么没拦住"才有对策
- 同一根因多次出现 → 升级为"元教训"写进最高优先级笔记区（每次唤醒必读的位置）
- 对策必须落到具体文件的具体条目，"下次注意"不算对策
三、修复验证闭环
- 立即修正：错误输出（报告/文件/消息）发现后第一时间改正并重发
- 同步所有副本：错误若已扩散到多个文件（报告/笔记/账本），逐个 grep 旧表述确认清零
- 反向受益检查：错误是否暴露了新信息？（案例：锁定误报反向证明了"IP 维度设计天然免疫账号 DoS"——错误有时是免费的验证）
- 沉淀三件套：方法论 → 规则库（可公开的）；个人纪律 → 私有笔记；案例 → 错误档案。三层各管各的，别混
四、快速参考（动手前自检卡）
- 这是已知目标/已知机制吗？→ 是：先 grep 笔记相关关键词
- 外部响应和本地档案冲突了吗？→ 冲突：先信档案再验证
- 这个判断动作有对照步骤吗？（定级→看界面；失败测试→查存量）
- 编辑文件：锚点带原文了吗？追加后回读了吗？
- 排查卡住超过 3 轮：有没有"集中定义处"没读？
- 犯错了：档案写了吗？模式分类了吗？对策落到具体条目了吗？
五、真实案例完整档案
来源会话：安全测试三轮（当晚连续执行）+ 平台 skill 发布流程，7 个错误全景与五要素复盘见会话错误档案。本库所有规则均由该档案提炼，已脱敏——不含站点名、账号、路径等可溯源信息。
许可
MIT-0（自由使用、修改、再分发，无需署名）