用途
scan（doc-sentinel:scan）是一个面向全代码库的文档漂移扫描技能。它把仓库中的文档与当前代码状态做交叉比对，定位每一处“文档引用了错误代码现实”的地方。与只检查单次提交所涉文件的 hook 不同，它扫描全部内容。该技能为只读操作，只报告漂移，不修改文件。
主要能力
扫描按六个阶段进行：
- 加载配置：读取 .doc-sentinel.json，未配置时使用默认值——docs_root 为 docs，watch_files 为 AGENTS.md、ARCHITECTURE.md、README.md、CLAUDE.md，ignore_sources 为 .test.、.spec.、tests/**。
- 发现文档：收集 docs/ 目录下全部 .md 文件，以及顶层的 AGENTS.md、ARCHITECTURE.md、CLAUDE.md、README.md、CHANGELOG.md 和配置中的 watch_files。
- 提取引用：从每个文档中提取源文件路径（反引号、链接、代码块中的路径）、shell 命令、端口与 localhost/127.0.0.1 地址、环境变量。
- 校验引用：检查文件与目录是否存在；检查文档中的 pnpm/npm 脚本是否存在于 package.json；将文档端口与 docker-compose.yml/compose.yml、.env/.env.example 以及其他文档交叉比对；检查文档中的环境变量是否仍出现在源码中；检查 CLAUDE.md 是否为指向 AGENTS.md 的符号链接。
- 新鲜度分析：用 git log 比较文档与其引用源文件的最后修改时间，给出四级评分：0 Fresh（文档比所有引用源更新）、1 Current（源变更后 7 天内更新）、2 Stale（源在文档更新后 7-30 天变更）、3 Very Stale（源在文档更新后超过 30 天变更）。ADR 文件豁免新鲜度评分。
- 生成报告：按严重程度输出结构化报告，包含 Critical Drift（断链、缺失脚本）、Stale References（代码变更而文档未更新）、Warnings（端口不一致、环境变量已不存在等）以及统计摘要（关键漂移数、过期引用数、警告数、扫描文档数、检查引用数）。
使用方式
资料未提供安装命令或具体调用命令，仅给出上述扫描流程与配置文件名 .doc-sentinel.json，以及执行的 shell 示例（如 find docs/ -name '*.md' -type f、git log -1 --format="%ai" -- "$doc_file"、jq -r '.scripts | keys[]' package.json 2>/dev/null 等），这些是技能内部使用的检查命令。
适用场景
适合维护大型或多模块项目文档、排查架构说明与 API 文档过期、提交前做文档一致性巡检、发现文档与 compose/.env 之间的端口冲突等。
限制
只读，不修复任何文件；报告基于具体证据（文件路径、行号、日期）而非推测；跳过 node_modules、vendor、.git 等第三方目录；CHANGELOG.md 视为只追加，仅在其引用不存在的版本/标签时告警；ADR 不做新鲜度检查；超过 500 行的文档只抽样前 200 行与后 100 行提取引用。安装与调用方式暂未提供。