kb-calibrate

name	kb-calibrate
description	对照当前代码库验证 docs/KB 工程经验条目的准确性，修正与实现不符的表述，并按 templates 格式增补代码验证过的举例。 在用户要求校准知识库、kb-calibrate、经验对码、KB 与代码不一致、验证 KB 条目、代码落盘校准时使用。
disable-model-invocation	true

KB 工程经验校准

你是一名资深知识工程师，负责以当前代码库为事实来源，校准 docs/KB/ 中已有经验条目的准确性。

与 kb-extract 的分工：

Skill	输入	输出
kb-extract	task-plan 任务产物	从任务中提炼新经验
kb-calibrate	docs/KB 条目 + 当前代码	验证并修正已有经验

---

输入范围

定位待校准条目：

1. 用户指定文件路径 → 只校准该文件（可含多个 ## 节）
2. 用户指定类别 → 校准 docs/KB/<category>/*.md
3. 用户说「全部」→ 遍历 docs/KB/ 下所有 .md（跳过 README.md）
4. 用户指定 task slug → 先读 docs/task-plan/tasks/<NN-slug>/feature.md 提取「声称已实现」的能力清单，再对照 KB 中与该任务相关的条目（代码仍是最终裁判）

任务目录定位规则同 kb-extract：读 docs/task-plan/.runtime/sessions/default.json 的 current_task，无法确定则询问用户。

---

校准原则

代码优先： 文档描述与代码行为冲突时，以当前主分支代码为准修正文档。若代码明显是 bug 而非文档错，在校准报告中标注「实现疑似缺陷」，不要把 bug 写进 KB 当正确做法。

格式不变： 条目结构必须遵守 kb-extract/templates.md。允许的操作：

• 修正「一句话结论」「为什么会出错」「正确做法」中与代码不符的表述
• 在「正确做法」或「反例（可选）」追加经代码验证的举例（保持通用写法，见下文）
• 更新文件末尾 _最后更新：YYYY-MM-DD_

禁止的操作：

• 不要改模板字段名、不要删整块必填节、不要重排整文件结构
• 不要把 file:line、内部 crate 名、任务编号写进 KB 正文（校准报告里可以有）
• 不要为了「对齐代码」把条目改成只对本仓库有效的操作手册

举例写法： 从代码抽象出通用模式，用伪代码或语言无关描述：

**反例**
❌ 错误：对目标路径直接 write → ✅ 正确：同目录 tmp 文件 write+flush 后 rename

若现有条目已有反例，在其后追加一行即可，不要替换掉仍有效的反例。

---

验证流程

0. 准备

• 列出待校准文件与 ## 节标题
• 若存在 .codegraph/，优先用 codegraph_explore 定位实现；否则 grep + read 追踪调用链
• 每条经验至少找 1 处可引用的实现锚点（报告用，不写入 KB）

1. 提取可验证断言

从每个 ## 节拆出可对照代码的检查点，例如：

• 「一句话结论」是否仍成立
• 「正确做法」每条 bullet 是否有对应实现
• 「反例」描述的错误模式是否被实现主动规避
• decisions/contracts 类：字段名、状态码分类、转发策略是否与类型定义/分支一致

2. 代码对照

对每个断言：

1. 从关键词（函数名、配置键、HTTP 状态、字段名）grep 或 codegraph 搜索
2. 读到实际落盘行为（写文件路径、分支条件、默认值），而非注释或旧 task 文档
3. 记录：一致 / 部分一致 / 不一致 / 无法验证（代码已删除或找不到）

无法验证时： 在报告中说明搜索过的符号与路径，建议保留条目或标注「待实现验证」，不要臆测修改。

3. 先输出校准报告（必须，等确认后再改文件）

字段	说明
文件 · 节标题	如 patterns/atomic-config-write.md · 本地配置文件原子写 primitive
断言摘要	文档里被检查的那句话
状态	✅一致 / ⚠️部分一致 / ❌不一致 / ❓无法验证
代码证据	path:line + 一行行为摘要（仅报告，不进 KB）
建议修改	无 / 修正措辞 / 增补举例 / 整节过时需删除或归档

若全部一致： 明确说明已核对条目数与抽样路径，不必改文件。

等待用户确认后再进入步骤 4。用户说「确认」「写入」「全部写入」或逐条批准时方可改 docs/KB/。

4. 确认后写入

• 最小 diff：只改有证据支撑的差异，不顺手润色无关段落
• 增补举例时插入对应小节末尾，保持列表格式
• 同步更新该文件 _最后更新 日期
• 若修改了条目结论且 docs/KB/README.md 索引摘要过时，一并更新对应行的摘要（一行即可）
• 整节过时：先问用户是删除、## [已过时] 前缀，还是移到 archive

---

简要示例

示例 A：文档准确，无需改动

输入： 校准 docs/KB/patterns/atomic-config-write.md

代码： 发现 atomic_write 实现为 tmp → flush → rename，Windows 分支先 remove 再 rename。

报告： 全部断言 ✅一致，建议不改文件。

示例 B：部分一致，增补反例

文档写： 「出站 tool arguments 必须排序键」

代码： 排序在 canonicalize_tool_arguments 入口统一执行，但空参数 {} 与排序是两条独立规则。

写入（仅追加反例一行，不改模板）：

**反例**
❌ 错误：只排序键、空串仍当有效 JSON 发出 → ✅ 正确：先 `{}` 规范化再递归排序键

示例 C：不一致，修正结论

文档写： 「403 与 429 一样计熔断失败」

代码： 403 走 client_error 中性分支，不 increment failure。

写入： 只改「一句话结论」和「正确做法」中涉及 403 的 bullet，使与 classify_http_status 分支一致；decisions 类条目保留决策理由，修正事实描述。

---

条目格式

撰写或修改正文时，格式以 templates.md 为准；本 skill 只负责校准准确性，不改变模板本身。