用途
内容一致性校验器用于检查多个文档来源之间的内容一致性，涵盖语气、术语、格式和结构。它支持网站、GitHub 仓库和本地文档三类来源，输出只读的差异报告，按严重程度分类列出发现的问题，并附带可执行的修复建议（含文件路径和行号）。
主要能力
- 跨来源比对：在网站、GitHub 仓库、本地文档之间两两配对比较。
- 结构化数据提取：从各来源提取版本号、功能声明、产品名称、标语、联系信息、URL 和技术要求。
- 严重程度分类：
- Critical（严重）：版本号冲突、功能列表矛盾、联系信息不一致、交叉引用失效。
- Warning（警告）：术语不一致（如 "plugin" 与 "extension"）、某一来源缺失信息、日期过时。
- Informational（提示）：风格差异、平台特定措辞、详细程度不同。
- 信任优先级：网站（最权威）> GitHub（面向开发者）> 本地文档（内部使用）。
- 报告生成：输出 Markdown 报告，包含执行摘要、逐对比较表、术语一致性矩阵，以及按优先级排序的行动项（含文件路径和行号）。
使用方式
- 发现来源：扫描构建目录（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 - 提取结构化数据：
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) - 按严重程度分类差异，并应用信任优先级。
- 生成 Markdown 报告，保存到 consistency-reports/YYYY-MM-DD-HH-MM-SS.md。
报告格式
报告包含：
- 执行摘要：严重程度计数（Critical/Warning/Info）一览。
- 逐对比较表：每个来源对之间的逐字段比较及严重程度分类。
- 术语矩阵：产品名称、版本和关键术语的跨来源一致性检查。
- 优先级行动项：具体修复建议，含文件路径和行号，按严重程度排序。
示例结构：
# Consistency Report — YYYY-MM-DD
## Executive Summary
| Severity | Count |
|----------|-------|
| Critical | 2 |
| Warning | 5 |
| Info | 3 |
## Website vs GitHub
| Field | Website | GitHub | Severity |
|-------------|---------------|---------------|----------|
| Version | v2.1.0 | v2.0.0 | Critical |
| Feature X | listed | missing | Warning |
## Action Items
1. **Critical** — Update `README.md:14` version from v2.0.0 → v2.1.0
2. **Warning** — Add "Feature X" to `README.md` feature list
适用场景
- 发布前审计：在打新版本标签前运行校验器，捕捉 README、文档站点和变更日志之间的版本不一致（例如网站写 v2.1.0，而 GitHub README 仍引用 v2.0.0）。
- 品牌更名后检查：产品更名或术语更新后（如 "plugin" 改为 "extension"），验证所有文档、落地页和贡献指南是否一致使用新术语。
- 新人上手审查：当新贡献者反馈文档令人困惑时，运行一致性检查以发现矛盾的功能声明、过时的联系信息或缺失的章节。
前提条件
- 至少可访问两个内容来源（网站、GitHub 仓库或本地文档目录）。
- 为远程 URL（已部署站点、GitHub 原始内容）配置 WebFetch 权限。
- 本地文档存放在可识别的路径中（docs/、claudes-docs/、internal/）。
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 网站内容不可达 | URL 返回 4xx/5xx 或构建目录缺失 | 确认站点已部署或运行本地构建；检查 WebFetch 权限 |
| GitHub API 速率限制 | 短时间内请求过多 | 暂停并在重置窗口后重试；使用认证请求 |
| 无文档目录 | 预期路径不存在 | 确认工作目录；显式指定文档路径 |
| 内容提取为空 | 客户端渲染对抓取不可见 | 使用本地构建输出目录而非实时 URL |
| diff 命令失败 | 文件路径含特殊字符 | 为传给 diff 和 grep 的所有文件路径加引号 |
限制
- 报告为只读，不会自动修改任何内容。
- 依赖 WebFetch 权限访问远程 URL，且受 GitHub API 速率限制影响。
- 对客户端渲染的页面可能无法提取内容，需改用本地构建输出。
- 需要至少两个内容来源才能进行比对。
资源
- 内容来源发现逻辑：${CLAUDE_SKILL_DIR}/references/how-it-works.md
- 信任优先级与验证时机：${CLAUDE_SKILL_DIR}/references/best-practices.md
- 用例演练：${CLAUDE_SKILL_DIR}/references/example-use-cases.md