内容一致性验证器
概述
检查多个文档源（网站、GitHub 仓库、本地文档）在语气、术语、格式和结构上的一致性。生成只读差异报告，按严重级别分类发现的问题，并提供可操作的建议（包括文件路径和行号）。
示例
- 发布前审计：在标记新版本之前，运行验证器以捕捉 README、文档站点和更新日志之间的版本不匹配——例如，网站显示 v2.1.0，但 GitHub README 仍引用 v2.0.0。
- 品牌更新后检查：在重命名产品或更新术语（例如，将“plugin”改为“extension”）后，验证所有文档、登录页面和贡献指南是否一致地使用新术语。
- 新人入职审查：当新贡献者指出文档令人困惑时，运行一致性检查，以揭示跨文档源的矛盾功能声明、过时的联系信息或缺失的部分。
前提条件
- 至少访问两个内容源（网站、GitHub 仓库或本地文档目录）
- 为远程 URL（已部署的站点、GitHub 原始内容）配置 WebFetch 权限
- 本地文档存储在可识别的路径中（
docs/、claudes-docs/、internal/）
操作说明
- 发现源——扫描构建目录（
dist/、build/、public/、out/、_site/）、GitHub README/CONTRIBUTING 文件以及本地文档文件夹：find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - 提取结构化数据——从每个源中提取：版本号、功能声明、产品名称、标语、联系信息、URL 和技术要求：
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - 验证提取——确认每个源至少包含 3 个数据点。如果某个源返回空，在继续之前查阅错误处理表。
- 构建对比矩阵——将每个源与其它源配对（网站 vs GitHub、网站 vs 本地文档、GitHub vs 本地文档）：
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - 按严重级别分类差异：
- 严重：版本号冲突、功能列表矛盾、联系信息不匹配、交叉引用损坏
- 警告：术语不一致（例如，“plugin” vs “extension”）、某个源缺少信息、日期过时
- 信息性：风格差异、特定平台的措辞、详细程度不同
- 应用信任优先级：网站（最高权威）> GitHub（面向开发者）> 本地文档（内部使用）。
- 生成报告格式为 Markdown，包含：执行摘要、每对源的对比表格、术语一致性矩阵以及带有文件路径和行号的优先操作项。
- 保存到
consistency-reports/YYYY-MM-DD-HH-MM-SS.md。
报告格式
# 一致性报告 — YYYY-MM-DD
## 执行摘要
| 严重级别 | 数量 |
|----------|------|
| 严重 | 2 |
| 警告 | 5 |
| 信息性 | 3 |
## 网站 vs GitHub
| 字段 | 网站 | GitHub | 严重级别 |
|-----------|------------|------------|----------|
| 版本 | v2.1.0 | v2.0.0 | 严重 |
| 功能 X | 已列出 | 缺失 | 警告 |
## 操作项
1. **严重** — 更新 `README.md:14` 版本从 v2.0.0 → v2.1.0
2. **警告** — 将“功能 X”添加到 `README.md` 功能列表中
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 网站内容无法访问 | URL 返回 4xx/5xx 或构建目录缺失 | 确认站点已部署或运行本地构建；检查 WebFetch 权限 |
| GitHub API 速率限制 | 短时间内请求过多 | 暂停并在重置窗口后重试；使用经过身份验证的请求 |
| 无文档目录 | 预期路径不存在 | 确认工作目录；明确指定文档路径 |
| 内容提取为空 | 客户端渲染对 fetch 不可见 | 使用本地构建输出目录而非实时 URL |
| diff 命令失败 | 文件路径包含特殊字符 | 传递给 diff 和 grep 的所有文件路径需加引号 |
资源
- 内容源发现逻辑：
${CLAUDE_SKILL_DIR}/references/how-it-works.md - 信任优先级和验证时机：
${CLAUDE_SKILL_DIR}/references/best-practices.md - 用例演练：
${CLAUDE_SKILL_DIR}/references/example-use-cases.md