mcpField
D
doc-drift-detector

doc-drift-detector

github.com/borghei测试与质量1.0k94 次安装5 天前更新
代码仓库

关于 doc-drift-detector

用于检测代码与文档不同步的技能，面向维护代码库和文档的团队。它结合 Git 历史、Python AST、链接校验和新鲜度评分，并提供 CI 门禁支持。

主要功能

  1. 01代码与文档漂移分析
  2. 02Python API 文档校验
  3. 03文档新鲜度评分
  4. 04Markdown 链接与锚点审计
  5. 05问题分类及修复路由
  6. 06CI 阈值与 JSON 输出

适用场景

  1. 01发布前评估文档新鲜度
  2. 02在 CI 中阻止严重文档问题
  3. 03核对 Python API 文档与源码
  4. 04重构后检查 README 链接

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/borghei/claude-skills --skill doc-drift-detector

安装后在 Claude Code 中输入/doc-drift-detector确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
drift_report_template.md
sample_drift_data.json
references/
documentation_standards.md
drift_prevention_guide.md
scoring-categories-and-troubleshooting.md
workflows-and-tool-reference.md
scripts/
api_doc_validator.py
doc_staleness_scorer.py
drift_analyzer.py
link_checker.py

详细介绍

文档漂移检测器

该 Agent 通过将代码目录映射到对应文档、比较 Git 修改历史、使用 AST 提取 Python 函数签名、验证每个 Markdown 链接和锚点，并按加权 0-100 分制评估新鲜度，来检测文档漂移。所有四个 CLI 工具都仅使用 Python 标准库。

核心功能

  • 全面漂移分析 — 将文档映射到代码，比较 Git 历史，检测重命名文件、版本漂移、失效引用和结构缺漏；按类别、严重程度和修复类型对每个问题进行分类。
  • API 文档验证 — 基于 AST 提取 Python 签名和类，并与 Markdown API 文档进行比较（未记录的项目、虚构文档、参数不匹配、弃用项）。
  • 过时程度评分 — 从五个维度按加权 0-100 分制评估新鲜度，支持 CI 阈值门控和 README 专注模式。
  • 链接完整性审计 — 验证本地文件、锚点、跨文档锚点、图片、大小写敏感性和重复锚点；可选检查外部 URL。
  • 漂移分类 — 分为结构、事实、引用、时间、语义类别，并为每项标注 [AUTO]/[SEMI]/[MANUAL]，以便分派修复工作。
  • CI/CD 集成 — 提供非零退出码、JSON 输出、GitHub Actions 和 pre-commit 配置方案，用于持续监控。

适用场景

  • 文档已与代码脱节 — 运行全面漂移分析。
  • 准备发布 — 根据总体过时程度评分设置门控。
  • 运行 CI 文档门控 — 对高严重程度或关键漂移、失效链接导致的 PR 检查失败。
  • 根据 Python 源代码审计 API 文档的准确性。
  • 重构后检查 README 状况和链接完整性。

首先确认

运行检测前，请确认以下输入。如果有任何一项未知或含糊不清，请先询问 — 不要自行假设：

  • 检查类型 — 全面漂移分析、过时程度评分、API 文档验证或链接审计（决定使用 drift_analyzer.py、doc_staleness_scorer.py、api_doc_validator.py 还是 link_checker.py）
  • 仓库和文档/源代码路径 — 要比较的仓库，以及代码和文档目录（工具扫描的输入）
  • 阈值和门控 — CI 失败的最低严重程度或过时程度阈值（设置 --min-severity/--threshold 和退出码门控）

停止规则：只询问最能影响输出的 2-3 项。如果用户说“直接起草”，则继续操作，并在产出内容顶部列出你的假设。

工具

工具用途命令
drift_analyzer.py全面分析代码和文档之间的漂移python scripts/drift_analyzer.py <repo> --min-severity high --json
doc_staleness_scorer.py为文档新鲜度打 0-100 分python scripts/doc_staleness_scorer.py <repo> --threshold 60
api_doc_validator.py根据 Python 源代码（AST）验证 API 文档python scripts/api_doc_validator.py <src> <docs> --recursive
link_checker.py审计所有 Markdown 链接和锚点python scripts/link_checker.py <repo> --broken-only

所有工具：仅使用 Python 3.8+ 标准库，支持 --json 和 --help，为 CI 提供非零退出码，适用于任何操作系统。

参考资料

按任务加载对应的参考资料——保持此文件精简，按需查阅详细内容：

资源

资源说明
Drift Report Template漂移分析报告模板
Sample Drift Data用于测试和演示的示例 JSON

范围与限制

涵盖内容：

  • 检测任意 git 仓库中相对于 git 历史的文档漂移
  • 基于 AST 验证 Python API 文档（函数签名、类定义、参数、返回类型）
  • 内部链接验证，包括本地文件、Markdown 锚点、跨文档锚点、图片和大小写敏感性检查
  • 多维度过时度评分，支持配置权重和 CI/CD 阈值强制执行

不涵盖：

  • 非 Python 源代码的 API 验证——基于 AST 的验证器仅解析 Python；对于 TypeScript、Go、Rust 或 Java API，请使用特定语言的文档生成器并配合链接检查器
  • 外部 URL 可用性监控——--check-external 会执行一次性 HEAD 请求，但不提供持续监控；可使用 senior-devops 技能设置可用性仪表板
  • 自动重写文档——工具会将问题分类为 [AUTO]、[SEMI] 或 [MANUAL]，但不会生成替换文本；可使用 code-reviewer 技能获取 AI 辅助的文档建议
  • 内容质量或可读性评估——过时度评分衡量的是新鲜度和结构完整性，而非行文质量；写作指南请参阅 standards/communication 知识库

集成点

技能集成方式数据流
code-reviewer在 PR 评审评论中包含漂移报告drift_analyzer.py --json 的输出会作为文档健康度部分纳入评审清单
senior-devops在 CI/CD 流水线中添加过时度门禁doc_staleness_scorer.py --threshold 50 失败时返回退出代码 1，从而阻止部署
senior-qa将文档质量纳入 QA 验收link_checker.py --json 的输出会与测试覆盖率指标合并到 QA 仪表板中
senior-fullstack验证脚手架生成后的项目文档对脚手架生成的 docs/ 目录运行 api_doc_validator.py，确认生成的 API 文档与源代码一致
senior-secops审计安全文档的时效性drift_analyzer.py --scope security/ 会检测安全文档是否落后于策略变更
senior-architect架构决策记录（ADR）的时效性doc_staleness_scorer.py --required-sections "Status,Context,Decision,Consequences" 会验证 ADR 的完整性

评论

支持 Markdown