用途:核对文档对代码的描述是否真实。它同时阅读文档、代码与测试,找出并报告(可选修复)三者不一致之处。v0.2 取消了 v0.1 的注释 DSL,改由智能体直接理解散文含义,再与代码行为和测试断言比对,避免“注释通过但散文说谎”。
主要能力:提取文档中所有可核对的断言(签名、行为、返回结构、默认值、保证、示例),对照公开 API 与测试清单判定,并按严重程度输出漂移报告。判定分为 PASS(与代码一致且有测试覆盖)、FAIL(代码与陈述矛盾)、UNSUPPORTED(与当前代码一致但无测试保护,视为缺失测试)、STALE(引用了已删除或改名之物)。
使用方式:先确定要检查的文档及其描述的代码与测试;运行 scripts/gather_context.py --doc DOC --src SRC --tests TESTS 收集一致输入(仅做 AST 解析,不导入、不执行),打包文档文本、公开 API 表面与测试清单;然后阅读并提取断言,逐条判定,输出按严重度排序的报告,每条引用文档陈述与矛盾现实(文件/函数)。可选修复:改写文档以符合现实,或标记需要补测试的断言。典型触发语如“发布前检查 README 与代码是否一致”“docs/api.md 是否仍匹配 pkg/”“重构后扫描文档漂移”。适合在发布前、重构后、文档 PR 等关键时刻运行,而非每次提交。
限制:它不设合并门禁,也不是测试框架;行为契约由测试套件(TDD/CI)负责,本技能只负责散文层。结果非确定性且可能出错,应视为仔细审查而非证明;读取三份产物并推理的成本与延迟高于跑测试;它不验证测试本身是否正确,垃圾测试会导致自信但错误的 PASS。不适用于 CI 合并门禁、验证行为(应写测试)、以及不含代码事实断言的散文。文件包括 scripts/gather_context.py 与 references/drift-report-example.md。