# 一错误一规则

> 记录智能体工作中的错误。记录过的错误禁止再犯。

---

## 错误清单

| 编号 | 日期 | 错误简述 | 详情 |
|:--:|------|------|------|
| 001 | 2026-09-16 | 假设同大项的事件性别相同 | [001-event-gender-assumption.md](knowledge/errors/001-event-gender-assumption.md) |
| 002 | 2026-09-16 | 大项名称映射不完整 | [002-sport-name-mapping.md](knowledge/errors/002-sport-name-mapping.md) |
| 003 | 2026-09-17 | 同一 eventID 下男女赛事混用，性别前缀映射不可靠 | [003-event-gender-same-eventid.md](knowledge/errors/003-event-gender-same-eventid.md) |
| 004 | 2026-09-20 | 新增识别去重键缺陷：仅凭队名误判重复，漏收跨事件/跨时段比赛 | [004-dedup-key-missing-eventid.md](knowledge/errors/004-dedup-key-missing-eventid.md) |
| 005 | 2026-09-20 | HotRio 关键词组内多个词被错误合并为一个 tag，导致召回配置失效 | 强制每个逗号分隔的关键词单独输入并按回车生成独立 tag；每个 tag 必须有独立的 × 删除按钮。分号只用于区分关键词组，绝不允许把组内多个词作为一个字符串 tag 提交。 |
| 006 | 2026-09-20 | 复用早先空映射，漏掉稍后才建立的 Hotrio | 每次更新必须对所有空 HotrioID 行实时调用 `live-rooms/{liveID}`；任务结束前再做一次空值二次扫描，禁止把早先“未创建”当成当次结论。 |
| 007 | 2026-09-20 | 未区分 Hotrio Tab，或未逐页抓全，导致对阵直播间漏收 | 只取 `tabHotrioMappings` 中 `tabID=27` 的 `amosID`；赛事列表翻页直到短页，并以线上 contest/liveID 集合对表格做反向差集验收。 |
| 008 | 2026-09-20 | 补齐 HotrioID 后未同步读取配置，导致“已发布？/关键词/排序方式/关键词匹配/最近发文时间”为空或沿用旧值 | 完整流程中 HotrioID 与五项配置字段最终必须对齐线上；Step 1 只同步赛事事实与发布状态，Step 5 使用发布后页面回读统一写回五项配置，禁止用接口默认值冒充线上配置。 |
| 009 | 2026-09-21 | 只使用 GIP 简写标题，丢失“女子/男子、团体赛/个人赛”等关键限定 | GIP `contests.title` 可能是简写。对有 Hotrio ID 的记录必须用 HotRio 页面运营标题交叉核验；名称字段只写完整赛事名，参赛双方写入独立“参赛”字段。写前逐条检查性别、团体/个人、项目限定均未丢失。 |
| 010 | 2026-09-21 | 关键词使用长国家名并加入排名赛/淘汰赛等阶段词，导致召回过严 | 国家/地区使用自然且稳定的短称（如吉尔、哈萨、印尼、香港、澳门、台北）；禁止把排名赛、淘汰赛、冠军赛、小组赛等阶段词作为召回约束。关键词以“双方短称 + 项目/性别/团体属性”的短词交集为主。 |
| 011 | 2026-09-24 | 把 HotRio 外层容器“已发布”误判成“热点资讯”子区块已发布 | [011-hotrio-container-status-not-block-status.md](knowledge/errors/011-hotrio-container-status-not-block-status.md) |
| 012 | 2026-09-27 | HotRio 只发布默认配置，或修改错误 BSON 层导致关键词未真正写入 | [012-hotrio-default-config-and-bson-input.md](knowledge/errors/012-hotrio-default-config-and-bson-input.md) |
| 013 | 2026-09-27 | 浏览器回传的 `bsonRawData` 形态与落盘快照不同，直接 `bytes(value)` 解码失败 | HotRio 浏览器接口回传值可能是 `{"data":[...]}`，历史落盘也可能是裸字节数组；解码前必须统一归一化为 `raw.get("data", []) if isinstance(raw, dict) else raw`，再执行 BSON 解码。 |
| 014 | 2026-09-28 | live-room API 响应包装层变化后仍按旧路径读取，误判 `tabID=27` Hotrio 不存在 | 兼容读取 `data.liveRoom` 与顶层 `liveRoom`，按 `tabID` 建索引后只取 `tabID=27` 的非空 `amosID`；空映射至少重试 3 次，任务收尾再全量复扫所有因缺映射而“暂不处理”的记录。 |
| 015 | 2026-09-29 | 飞书原生排序按内部存储类型分组，显示相同的日期文本仍产生逆序 | 新增或更新日期/时间后，排序验收必须按显示值全量计算相邻逆序；若原生排序因混合存储类型留下逆序，禁止直接交付，改为按显示值将异常行整行移动到正确位置，并再次断言逆序为 0。 |
| 016 | 2026-09-29 | 把 live-room 请求失败写成 warning，且未区分“确认无 Hotrio”与“未知” | 请求成功且确认没有 `tabID=27` 才能记“确认无 Hotrio”，这是正常结果、不计 warning；`TypeError: Failed to fetch`、超时、认证或网络/CORS/代理链路失败均表示 HotRio 状态未知，必须记 error。Step 1 汇报同时列出“已确认有/已确认无/未知”三类。 |
| 017 | 2026-09-30 | live-room HTTP 502 后未切换 live 实体页，导致 29 条已有 Hotrio 映射被误留为未知 | live-room 不可判定时必须打开 `https://hot.bytedance.net/main/v2?entityType=live&id={liveID}`，在“完整 Tab 配置”中读取 `Tab ID=27 / 看点` 的 Hotrio ID；只有 API 与页面回退都失败时才记未知和 error。 |
| 018 | 2026-09-30 | 发布接口成功后立即回读，把尚未异步收敛的区块误报为发布失败 | 发布响应成功后轮询刷新，直到 `status=3 && onlineVersion=version` 或达到明确超时；首次短延时回读不一致只表示状态尚未收敛，不能提前写成功，也不能直接认定最终失败。 |
| 019 | 2026-09-30 | 历史“待修改/待输入”记录直接重配，忽略线上可能已正确发布 | 补跑历史队列必须先批量只读 audit；线上配置与队列期望完全一致时只回填“已输入”，不重复保存或发布。只有配置不一致且关键词已校验的记录才进入重配。 |
| 020 | 2026-10-01 | 逐个修复相邻逆序不等于最少整行移动 | 排序规划必须先对目标顺序计算最长递增子序列（LIS），只移动非 LIS 行；新增回归测试覆盖“贪心需 2 次、最优仅 1 次”的排列，执行后仍需断言逆序为 0 且全行多重集不变。 |
| 021 | 2026-10-01 | 稀疏批量写入凭近期区块硬编码范围，漏掉更早的目标行 | 写入范围必须由完整目标行集合的最小/最大真实行号推导，并在请求前断言每个目标行都落入范围；写后全量比较计划与实际 changeset，漏项立即补写，禁止只抽查首中末。 |
| 022 | 2026-10-01 | 多个同 Bundle ID 的 Chrome 使普通 AppleScript 投递到错误实例 | 不得暂停、关闭或终止其它实例。每次命令动态枚举 Chrome，排除临时 profile/远程调试实例，再用目标标签与 JavaScript 探针唯一确认用户 Chrome；通过 ScriptingBridge 按本轮 PID 执行。Chrome 重启后重新发现，禁止缓存 PID或使用模糊 AppleScript。 |
| 023 | 2026-10-04 | 大批次执行期间过早轮询、或一次性经 Apple Event 回传完整结果，导致桥接队列阻塞 | `map-live` 启动后先等待 60 秒再发首个轮询；轮询只返回任务状态和序列化长度，完整结果按不超过 32KB 分块回收并处理代理对边界。只读 Apple Event 超时可有限重试；持续阻塞时只允许重建本轮 Agent 创建的标签，禁止关闭用户原有标签或干预其它 Chrome 进程。 |

---

## 通用规则

1. **不假设**：同一 sportID 下的不同 eventID 可能有不同的性别/属性，必须逐条从页面验证
2. **不全则缺**：名称映射必须覆盖全部可能值，不能只映射已知的几种
3. **页面为准**：API 返回的标题可能不完整（如缺失性别前缀），必须以页面显示的名称为准
4. **验证优先**：修复后必须逐条抽查校验，特别是边界情况（如跨性别事件）
5. **eventID 不可靠**：同一 eventID 下可能同时存在男女赛事（如排球 2145307），不能仅凭 eventID 推断性别
6. **身份靠 ID 不靠名字**：判定两场比赛是否相同，权威键为 `(eventID, contestID, liveID, scheduledStartAtMs)`；参赛方/标题名称永远不得单独作为去重依据；队名无序匹配仅限同 eventID + 同开赛时间内使用
7. **反向覆盖审计**：每次比对必须逐事件列出"线上有、表内无"的全部 contest，并核对计数，防止漏收
8. **写前重读表头**：列位置可能被人工调整，每次写入前必须重新读取表头并按当前列位置组装数据，禁止盲写
9. **对阵顺序规范化**：表内统一按 API side=home 在前记录，避免顺序不一致造成人工漏看
10. **HotRio 关键词逐词成 tag**：分号用于划分关键词组；组内逗号分隔的每一个词都必须单独输入并按回车，形成带独立 × 删除按钮的 tag。禁止把“乌兹，日，女子团体”整体作为一个 tag；验收时必须逐词核对 tag 数量和内容。
11. **空 HotrioID 必须实时重查**：每次总表更新都对全部空 HotrioID 行调用 `live-rooms/{liveID}`；任务收尾前必须二次扫描，覆盖晚建直播间。
12. **tabID 不能混用**：看点 HotrioID 固定取 `tabID=27` 的 `amosID`，不得误取 `tabID=25`。
13. **分页必须跑到短页**：必须记录抓取页数、总条数和唯一 contestID 数；固定页数、首屏结果或旧缓存均不得作为完整数据集。
14. **线上反向差集必须为零或逐条解释**：以 `(contestID, liveID, scheduledStartAtMs)` 对比线上与表内；每个差异都要新增或留下排除理由。
15. **HotrioID 与配置字段必须原子补全**：凡 HotrioID 非空，必须实时读取并回填「已发布？、关键词、排序方式、关键词匹配、最近发文时间」五列。新增/补 ID 后必须立刻查配置；任务收尾再对全部非空 ID 做全量审计，断言发布状态非空，其他四列若为空必须有“无热点资讯区块”等明确线上原因，禁止只填 ID 和链接。
16. **保存真值只认 BSON `t_form_input`**：配置“热点资讯”时必须修改 `recall_forum_info.t_form_input`，保存回读确认关键词二维数组和固定参数后才允许发布；外层副本、默认值或发布成功响应均不能替代 UI 真值验收。
17. **BSON 原始值先归一化**：浏览器接口返回的 `bsonRawData` 可能是 `{"data":[...]}`，历史文件可能是裸数组；任何解码脚本都必须兼容两种形态，禁止直接假设一种类型。
18. **live-room 响应路径必须兼容并复扫**：HotRio 映射读取必须兼容 `data.liveRoom` 和顶层 `liveRoom`，显式匹配 `tabID=27`；空映射不得立即落结论，必须重试，并在任务收尾全量复扫“缺映射/暂不处理”记录。
19. **live 实体页是映射回退真值源**：live-room 请求失败或结构不可判定时，必须使用已登录浏览器访问 live 实体页并读取“完整 Tab 配置”的 `Tab ID=27`；页面成功判定后应消除该条接口 error。
20. **发布状态必须等待版本收敛**：`SaveBlock` 发布成功后持续回读目标子区块；只有 `status=3 && onlineVersion=version` 才算发布完成，轮询超时才记失败。
21. **浏览器实例冲突动态定位且不干预其他任务**：每次命令重新枚举普通用户 Chrome，排除临时 `user-data-dir`、远程调试、headless 和 agent-browser 实例，再以目标标签和 JavaScript 探针唯一确认；随后用 ScriptingBridge 按本轮 PID 绑定。Chrome 重启后不得复用旧 PID；无法唯一绑定时停止并报告，不干预任何其它进程。
22. **大批次 Apple Event 必须延迟轮询并分块回收**：`map-live` 启动后先等待 60 秒，避免执行期间并发 Apple Event；轮询只返回小状态，完整 JSON 按不超过 32KB 分块拉取。持续超时恢复时只重建本轮 Agent 创建的目标标签，禁止关闭用户已有标签、暂停或终止其它 Chrome 实例。