判断回溯录（ERR-XXX，原「踩坑错误册」）

任务结束后触发"新坑即录"：凡本轮新踩/复现且解决耗时 ≥ 40min 的坑，强制性在索引新增一行 + 建立独立 .md。

本 reference 收口于 Step 6 复盘沉淀阶段。

定位升级：本册不只记"坑的结果"（根因/修复/防范）来省时间，更要把每一条变成决策失败样本——记录"当时基于什么证据判错、正确判据应是什么、为什么没想到那个信号"，让诊断从"查关键词命中"升级为"见过这种错判长什么样"的模式匹配。

索引模板

文件：{PROJECT_ROOT}/.ai-memory/error_index.md

# 错误索引

| ERR-ID | 一句话描述 | 根因分类 | 触发关键词 | 新增日期 | Recurrence-Count |
| ----------- | -------------------------- | ------------ | ----------------------------------------- | ---------- | ---------------- |
| ERR-001 | 帝国CMS路由表有值但加载失败 | 框架行为假设 | 路由表有值, 不会加载 | 2026-07-11 | 1 |
| ERR-002 | 中文路径致Python安装失败 | 平台差异 | 用户名非英文, 安装失败 | 2026-07-12 | 1 |
| ERR-003 | write_file时间戳副本未覆盖 | 工具行为 | 覆盖, rename-item, 时间戳副本 | 2026-07-20 | 1 |
| ERR-004 | 环检测递归三次都判错环数 | 算法正确性 | 环检测, 递归, 回边, cycle | 2026-08-14 | 1 |
| ERR-005 | 为简单校验过度抽象出策略模式 | 设计取舍(taste) | 过度设计, 抽象, 策略模式 | 2026-08-14 | 1 |
| ERR-006 | build_graph 注释伪符号致假边 | 算法正确性 | 注释伪符号, 假边, strip_php_comments, phantom | 2026-08-14 | 1 |

分类标准（共十类）：框架行为假设 / 平台差异 / 配置冲突 / 缓存/竞态 / 工具行为 / 业务逻辑 / 安全沙箱 / 环境变量 / 算法正确性 / 设计取舍(taste)。

算法正确性：环检测 / 图遍历 / 递归 / 状态机 / 排序等"跑通但结果错"类缺陷（如环检测三次没写对）。此前此类坑进不了册子，属分类缺口，必须单独归类。
设计取舍(taste)：取舍权衡判断失误（过度设计 vs 简化、抽象边界、API 形态、是否引入依赖等），属审美/判断力层面而非纯技术错误。

单条模板

文件：{PROJECT_ROOT}/.ai-memory/errors/ERR-XXX.md

# ERR-XXX: {错误一句话描述}

- **根因分类**：
- **触发条件**：
- **排查路径**：
- **错判点**：（当时基于什么证据判错了——误信了哪个信号、忽略了哪个反例）
- **正确判据**：（应该用什么信号才对——可证伪的判定标准）
- **盲区**：（为什么之前没想到这个信号——认知/经验缺口，而非技术盲区）
- **修复方式（可复用）**：
- **防范措施**：
- **规避方案**：
- **关联知识库**：（列出相关技术或工具的官方文档关键词 / sector）
- **来源会话**：（可选，标记首次发生的会话 ID 或日期）
- **Recurrence-Count**：1（复现次数，capture_learning.py 去重提示驱动累加）
- **First-Seen**：（YYYY-MM-DD，首次发生日期）
- **Last-Seen**：（YYYY-MM-DD，最近复现日期）
- **Tasks**：1（跨不同任务数，Recurrence>=3 且 Tasks>=2 触发 promote 建议）
- **Pattern-Key**：（可选，稳定去重键，如 cms.routing.table_loaded）

上方 4 个 Recurrence 字段由 capture_learning.py / recurrence_promote.py（学习捕获 hook 草案）消费：单条含此字段时，recurrence_promote.py 可评估硬规则（Recurrence-Count>=3 且 Tasks>=2 且 30 天窗口）并输出 promote 建议；缺字段则优雅跳过。

禁止字段：本模板仅含技术信息。禁止记录密码 / Token / API Key / SSH Key / 账号凭证 / 生产 IP / 内部域名。

触发与读取

诊断阶段触发

在 Bug 诊断 / 代码审查 / PHP 内联 JS 等 session 中，Agent 优先按错判形状做模式匹配，而非只查触发关键词：

先匹配 error_index.md 行的触发关键词，命中后读 errors/{ERR-ID}.md 全文
重点比对单条中的 错判点 / 正确判据 / 盲区：当前是否落入同样的"误信信号、忽略反例"模式
若当前症状与记录匹配 → 优先复用修复方式与正确判据，并对本结论先跑证伪门禁，计时从 0 开始
若相似但不完全匹配 → 标记为变体，修复后新建 ERR-ID（不覆盖原条目），并在新条目的错判点中说明与旧条目的差异

新坑即录

任一 session 中踩的新坑且排查耗时超过 40 分钟（从初步定位到 fix 完成），强制性操作：

分配下一个可用的 ERR-ID（如 ERR-004）
按单条模板创建 errors/{ERR-ID}.md
在索引表追加一行
同步更新 project_memory.md 中的 Known Issues 节（写缩写引用：参见 ERR-XXX）
运行 python hooks/recurrence_promote.py 评估本条目及全量错误是否满足升规则硬条件（Recurrence-Count≥3 且 Tasks≥2 且 30 天窗口），满足则输出 promote 建议交用户确认（不自动改写规则文件）

排查时间估算：从首次发现症状到修复方案确认，按 Agent 与用户交互轮次×平均轮耗时估算；≥ 4 轮交互视为接近 40 分钟阈值，建议记录。

归档策略

索引表超过 50 行时触发归档提醒：⚠️ 错误索引已超 50 条（当前 X 条），建议将 3 个月前的旧条目归档至 archive/error_index_{YYYY}.md
单条 ERR-XXX.md 超过 500 行时触发拆分提醒
合并规则：连续 3 个 ERR-ID 同一根因 → 合并为一条，保留各变体修复方式

禁忌

不记录密码 / Token / API Key / 凭据 / 生产 IP
不经确认不写入
不跨项目复用（每项目独立索引）

error-ledger.md 5.7 KB تاريخچه خام