name: documentation-audit description: 此技能用于验证文档声明与代码库实际情况的一致性。触发词包括“audit docs”、“verify documentation”、“check docs”、“docs accurate”、“documentation drift”、“before release”、“after refactor”、“docs don’t match”。采用两阶段提取与模式扩展进行综合检测。 context: fork agent: Plan
<!-- ABOUTME: 用于验证文档声明与代码库一致性的文档审计技能 --> <!-- ABOUTME: 采用两阶段提取与模式扩展进行综合检测 -->
文档审计
使用两阶段方法，系统性地验证文档中的声明与实际代码库的一致性。
概述
核心原则： 低召回率比误报更糟糕——未发现的声明会一直隐藏。
两阶段流程：
- 阶段1： 直接从文档中提取并验证声明
- 阶段2A： 根据误报声明扩展模式，以发现类似问题
- 阶段2B： 对比代码库清单与文档记录项（差距检测）
快速开始
- 识别目标文档（仅限面向用户的文档，跳过
plans/、audits/） - 记录当前 git 提交信息用于报告标题
- 运行阶段1提取（使用并行代理，每个文档一个）
- 分析误报声明的模式
- 运行阶段2扩展搜索
- 生成
docs/audits/AUDIT_REPORT_YYYY-MM-DD.md
声明类型
| 类型 | 示例 | 验证方式 |
|---|---|---|
file_ref |
scripts/foo.py |
文件是否存在？ |
config_default |
“默认值为 ‘AI Radio’” | 检查架构/代码 |
env_var |
STATION_NAME |
是否在 .env.example 和代码中？ |
cli_command |
--normalize 标志 |
脚本是否支持？ |
behavior |
“每2分钟运行一次” | 检查计时器/代码 |
验证置信度：
- 层级1（自动）： file_ref、config_default、env_var、cli_command
- 层级2（半自动）： symbol_ref、version_req
- 层级3（人工审核）： behavior、constraint
阶段2 模式扩展
阶段1之后，分析误报声明并搜索类似模式：
发现无效脚本：diagnose_track_selection.py
→ 搜索：所有脚本引用 → 发现另外8个无效脚本
错误间隔：“每10秒”
→ 搜索：“每 \d+ (秒|分钟)” → 发现另外3处
错误服务名称：ai-radio-break-gen.service
→ 搜索：服务/定时器名称 → 发现命名不一致
始终检查的常见模式：
- 无效脚本：
scripts/*.py引用 - 定时器间隔：
每 \d+ (秒|分钟) - 服务名称：
ai-radio-*.service、*.timer - 配置变量：
RADIO_*环境变量 - CLI 标志：bash 代码块中的
--flag模式
输出格式
生成 docs/audits/AUDIT_REPORT_YYYY-MM-DD.md：
# 文档审计报告
生成日期：YYYY-MM-DD | 提交：abc123
## 执行摘要
| 指标 | 数量 |
|--------|-------|
| 扫描文档数 | 12 |
| 验证声明数 | ~180 |
| 验证为真 | ~145 (81%) |
| **验证为假** | **31 (17%)** |
## 需要修复的错误声明
### CONFIGURATION.md
| 行号 | 声明 | 实际情况 | 修复建议 |
|------|-------|---------|-----|
| 135 | `claude-sonnet-4-5` | 实际：`claude-3-5-sonnet-latest` | 更新 |
## 模式摘要
| 模式 | 数量 | 根本原因 |
|---------|-------|------------|
| 无效脚本 | 9 | 脚本已删除，文档未更新 |
## 人工审核队列
- [ ] 第436行：行为声明需要验证
详细参考
执行清单和反模式：checklist.md 声明提取模式：extraction-patterns.md