用途
docs-audit 是一个文档审计技能，用于对照当前代码库状态审计文档文件，检查其准确性、完整性和时效性。它适合在代码持续演进、文档容易滞后的项目中定期运行，帮助发现文档与实现不一致的问题。
主要能力
审计流程分为五个阶段：
-
发现（Discovery）：运行 discover-docs.ts 脚本，获取所有 Markdown 文件及其 git 元数据的清单，输出 JSON，包含文档总数、活动状态分布（active/recent/idle/stale/ancient）、以及存在相关代码变更的文件（潜在过时指标）。
-
优先级排序（Prioritization）：根据 focus 参数选择深入分析的文件。focus 可选 stale（优先最旧提交、尤其是有近期相关代码变更的文件）、all（跨活动状态均衡采样）、recent（关注最近修改、可能引入错误的文档）。默认选取前 10 个文件。
-
深度分析（Deep Analysis）：对每个选中文件执行三类检查：
- 正确性：代码示例的导入/require 路径、函数签名、配置示例、CLI 命令与标志、环境变量是否与当前实现一致。
- 链接验证：内部 Markdown 链接、锚点链接、图片引用是否有效；外部 URL 仅抽样检查，不阻塞。
- 完整性：必需章节、公共导出文档、复杂功能示例、错误处理说明等是否齐全。
-
Docstring 覆盖率（Docstring Coverage）：检查与文档相关代码文件的 TSDoc/JSDoc/docstring 覆盖率，支持 TypeScript/JavaScript、Python、Rust、Go，通过 grep 统计导出项与已文档化导出项的比例，计算每种语言的覆盖率百分比。
-
报告生成（Report Generation）：使用 report-path.ts 生成报告路径，写入带 YAML frontmatter 的 Markdown 报告，包含摘要表格（正确性、链接、Docstring、时效性）、关键问题、警告、过时文档、各语言 Docstring 覆盖率、优先建议等。
使用方式
基本调用：
/docs-audit # 单份报告写入 .pack/reports/
/docs-audit --path docs/ # 限定 docs/ 目录
/docs-audit --focus all --limit 20 # 分析 20 个文件，覆盖所有状态
/docs-audit --multi # 多文件模式，生成多份报告
/docs-audit --output docs/audits/latest.md # 自定义输出位置
/docs-audit --multi --path src/ # 对 src/ 文档做多文件审计
报告默认写入 .pack/reports/，文件名带前置时间戳。单文件模式为 {timestamp}-docs-audit-{sessionShort}.md，多文件模式为 {timestamp}-docs-audit/ 目录，内含 summary.md、markdown-docs.md、docstrings.md、recommendations.md、meta.json。所有报告均带 YAML frontmatter，包含 type、generated、timestamp、session、session_short、scope、focus、files_analyzed、files_total、status 等字段，便于 grep/ripgrep 搜索和工具聚合。
该技能使用 context: fork 隔离运行，典型审计的 token 预算目标为 15-30k。它使用任务工具（TaskCreate、TaskUpdate、TaskList）跟踪各阶段进度，支持在上下文压缩或中断后通过检查点数据恢复。
适用场景
- 代码库持续演进，需要定期检查文档是否与实现同步。
- 发布前审查文档准确性，避免用户因过时示例或错误命令产生困惑。
- 评估项目 Docstring 覆盖率，识别缺少文档的公共导出。
- 大型仓库中优先处理最可能过时的文档。
限制
- 外部 URL 仅抽样检查，不作为阻塞项。
- 非 git 仓库会跳过 git 元数据，改用文件修改时间，并在报告中注明“Git metadata unavailable”。
- 超大仓库（100+ 文档）需严格使用 limit 参数，聚焦最过时的文件。
- 未提供文档时会报告“No markdown files found in {scope}”。
- 自定义文件名不会自动包含会话 ID 前缀，需通过 frontmatter 追踪。
- 默认 .pack/reports/ 位置建议加入 gitignore，也可选择性提交以保留审计历史。