用途
Documentation Audit 用于系统性地验证文档中的声明是否与代码库实际情况相符。其核心原则是：低召回率比误报更糟糕——被遗漏的声明会一直隐藏下去。该技能适合在文档可能过时、代码已变更但文档未同步更新时使用。
主要能力
该技能采用两遍式流程：
- 第一遍（Pass 1）：直接从文档中提取并验证声明。
- 第二遍 A（Pass 2A）：从错误声明中扩展模式，查找类似问题。
- 第二遍 B（Pass 2B）：比较代码库清单与文档条目，进行差距检测。
可验证的声明类型包括：
| 类型 | 示例 | 验证方式 |
|---|---|---|
| file_ref | scripts/foo.py | 文件是否存在？ |
| config_default | "defaults to 'AI Radio'" | 检查 schema/代码 |
| env_var | STATION_NAME | 是否在 .env.example 和代码中？ |
| cli_command | --normalize flag | 脚本是否支持？ |
| behavior | "runs every 2 minutes" | 检查定时器/代码 |
验证置信度分为三层：
- Tier 1（自动）：file_ref、config_default、env_var、cli_command
- Tier 2（半自动）：symbol_ref、version_req
- Tier 3（人工复核）：behavior、constraint
第二遍模式扩展会在第一遍之后分析错误声明并搜索相似模式，例如：发现死脚本后搜索所有脚本引用；发现错误间隔后搜索类似时间表达式；发现错误服务名后搜索服务/定时器名称。常见需检查的模式包括：死脚本、定时器间隔、服务名称、配置变量、CLI 标志。
使用方式
快速开始步骤：
- 确定目标文档（仅面向用户的文档，跳过 plans/、audits/ 目录）
- 记录当前 git commit 用于报告头部
- 使用并行代理运行第一遍提取（每个文档一个代理）
- 分析错误声明中的模式
- 运行第二遍扩展搜索
- 生成 docs/audits/AUDIT_REPORT_YYYY-MM-DD.md
输出报告格式包含：执行摘要（扫描文档数、验证声明数、验证为真/假的数量）、需要修复的错误声明（按文档列出，含行号、声明、实际情况、修复建议）、模式总结（模式、数量、根本原因）、人工复核队列。
详细参考：执行清单和反模式见 checklist.md；声明提取模式见 extraction-patterns.md。
适用场景
- 代码库经过多次迭代后，需要确认文档是否仍然准确
- 发布前对用户文档进行质量检查
- 发现文档中存在过时的文件引用、配置默认值、环境变量或命令标志
- 需要系统性地检测文档与代码之间的差距
限制
- 仅针对面向用户的文档，跳过 plans/、audits/ 等目录
- 部分声明类型（如行为、约束）需要人工复核，无法完全自动验证
- 需要记录 git commit 以生成报告头部
- 具体安装命令、收费模式、平台支持等信息暂未提供