用途
docs-audit-and-refresh 用于审计仓库的 docs/ 内容与当前代码库是否一致，找出缺失、错误或过时的文档，并刷新受影响的页面。它强调从仓库当前实现出发向外检查，把代码、测试和当前配置界面视为权威来源，工作范围限定在 docs/ 内。
主要能力
- 构建当前状态清单：检查定义用户或开发者行为的仓库区域，阅读相关代码、测试、schema 和包接口，关注已发布行为、稳定配置、暴露的命令、集成和开发者工作流。
- 对比实现与 docs/：识别三类问题——现有功能、设置、工具或工作流缺少文档；文档与当前代码库矛盾；文档使用旧名称、默认值、路径或示例而过时。
- 按读者影响排序：优先修复高成本问题，如损坏的入门、安装、认证或命令流程；错误的设置、默认值、路径或功能行为；完全缺失的真实界面文档；影响较低的清晰度或组织改进。
- 刷新文档：更新 docs/ 下最小正确页面集合，优先编辑现有页面，仅为明确且持久的缺口新增页面，新增或移动页面时更新最近的 _meta.ts，保持示例可执行并与当前仓库结构一致，删除无用或误导性文本。
- 验证刷新：搜索 docs/ 中的旧术语和被替换的配置键，检查相邻页面是否有冲突指导，确认新页面出现在正确的 _meta.ts 中，对照代码或测试重新阅读关键示例、命令和路径，并验证捆绑技能文档索引仍与当前 docs/ 树匹配。
使用方式
在广泛审计前，先阅读 references/audit-checklist.md，使扫描聚焦于高信号区域。工作流分为五步：构建当前状态清单、对比实现与 docs/、按读者影响排序、刷新文档、验证刷新。审计标准建议先广度优先发现，再对确认的缺口深入；没有证据表明错误或缺失时，不要重写大范围内容；README 文件不在编辑范围内，变更限于 docs/；如果发现一次无法解决的过大问题，应指出残留缺口。
适用场景
适用于需要让文档与代码库保持一致的场景，例如功能变更后同步文档、排查文档与实现不符的问题，或系统性检查文档覆盖情况。
限制
工作范围限定在 docs/ 内，不编辑 README。需要以仓库证据证明缺口后再编辑，避免凭直觉修改。对于一次无法解决的过大问题，只能指出残留缺口。捆绑技能 qc-helper 的 SKILL.md 维护了主题到文档路径的硬编码表，如果新增、移动、重命名或删除 docs/users/ 下的页面，必须同步更新该表；其他捆绑或项目技能也可能引用文档路径，需在 .qwen/skills/ 和 packages/core/src/skills/bundled/ 中搜索 docs/users/ 以捕获。