docs-review

docs-review

通用文档审查工具：读取 docs/ 中的每个 Markdown 文件，通过扫描文件路径、标志名称、命令语法、状态名称和配置示例，识别文档所描述的源代码，然后将这些说法与实际源文件交叉核对。报告偏差（文档写着 X，代码却是 Y），并提供文件:行号作为证据。

适用场景

• 定期（每周通过 cron 运行），检查文档是否落后于代码变更
• 发布前，确保文档与当前代码库一致
• 重构命令、配置架构或状态机后
• 如果不存在 docs/，则跳过并正常退出，同时给出提示

不适用场景

• 没有可验证源代码声明的纯叙述性章节（历史、理念、理由）
• 你不拥有其源代码的外部 API 文档——无法通过 grep 搜索其源代码
• 格式或风格审查——只关注语义偏差

调用方式

/docs-review
/docs-review --since 2026-04-01
/docs-review --output reports/docs-drift.md

标志	效果
(无)	审查所有 docs/*.md 文件
--since <date>	将范围缩小到自 <date> 以来修改的文档文件（git log --since）
--output <path>	除标准输出外，将发现结果写入文件

---

工作流

步骤 1：查找文档

ls docs/*.md 2>/dev/null || echo "No docs/ directory found"

如果不存在 docs/ 目录，则正常退出：

No docs/ directory found — nothing to review.
Exit 0.

如果提供了 --since <date>，则缩小文件列表范围：

git log --since="<date>" --name-only --pretty=format: -- docs/*.md | sort -u | grep '\.md$'

如果没有返回结果，则正常退出：

No docs files modified since <date> — nothing to review.
Exit 0.

步骤 2：提取每个文档文件中的可验证声明

阅读每份文档，提取可与源代码交叉核对的声明：

声明类型	查找内容	示例
命令标志	--flag-name 模式	--group-id、--not-before
状态名称/转换	state/ → state/ 或带引号的状态字符串	pending/ → running/ → done/
配置键	配置上下文中用反引号括起来的键名	`max_concurrent`、`not_before`
文件路径	以“位于 X”或“参见 X”提及的路径	dispatch.sh、executor.sh
退出码	“以 N 退出”或“返回 N”	exit 0、exit 1
调用示例	代码块中的命令示例	./dispatch.sh --agent lexgo

跳过明显无法验证的章节：介绍性文字、动机、设计理由、未来计划。

步骤 3：将每条声明与源代码交叉核对

命令标志——搜索 shell 脚本和代码文件：

grep -rn "\-\-flag-name" --include="*.sh" --include="*.mjs" --include="*.js" --include="*.py" --include="*.ts" .

如果没有匹配项，则视为潜在偏差。报告前确认该标志确实不存在。

状态名称——在执行器/调度器脚本中搜索状态字符串：

grep -rn "pending\|running\|done\|failed" --include="*.sh" --include="*.js" --include="*.py" .

将文档中描述的确切转换顺序与代码实际强制执行的顺序进行交叉核对。

配置键——在相关配置文件及读取这些配置的代码中 grep 搜索：

grep -rn "max_concurrent\|not_before" --include="*.sh" --include="*.yml" --include="*.json" --include="*.js" .

文件路径——检查路径是否存在：

[ -f "path/to/file" ] && echo "EXISTS" || echo "MISSING"

目录则检查：

[ -d "path/to/dir" ] && echo "EXISTS" || echo "MISSING"

退出码——在相关脚本中 grep 搜索实际的退出调用：

grep -n "exit [0-9]" script.sh

调用示例——验证二进制文件/脚本是否存在，以及示例中使用的标志是否有效：

[ -x "./dispatch.sh" ] && echo "executable exists" || echo "MISSING"
grep -n "\-\-agent" dispatch.sh

步骤 4：整理发现结果

对于每项偏差：

DRIFT: docs/dispatch.md:42 claims "--context" flag exists
  Source check: grep "--context" *.sh → not found
  Evidence: no match in dispatch.sh, executor.sh, or any .sh file

对于每项已验证声明：

OK: docs/dispatch.md:15 "--group-id" → dispatch.sh:47 (confirmed)

对于每项跳过的声明（无法验证）：

SKIP: docs/overview.md:1-10 — intro prose, no verifiable source claims

步骤 5：汇总

处理完所有文件后，输出：

=== docs-review summary ===
Docs reviewed: N files
Claims checked: M
  OK:    X verified
  DRIFT: Y items
  SKIP:  Z non-verifiable

Drift items:
  - docs/dispatch.md:42 — "--context" flag not found in source
  - docs/executor.md:18 — state "queued" not found; code uses "pending"

Exit 0 if no drift found, exit 1 if any drift items exist.

如果提供了 --output <path>，则将完整发现结果（所有 OK/DRIFT/SKIP 行及汇总）写入该文件。

---

需要执行的检查

六项规范检查——全部执行：

检查	搜索内容	检查位置
标志一致性	文档中的 --flag-name 模式	*.sh、*.js、*.py、*.ts
状态一致性	状态字符串和转换顺序	执行器、分发器脚本
配置键一致性	配置键名称	配置文件、读取这些配置的脚本
链接有效性	[text](./path) 或 [text](path.md) 内部链接	对照文件系统解析
路径存在性	提及的实际路径	[ -f path ] 或 [ -d path ]
退出码准确性	“exits N” 或 “returns N”	grep -n "exit [0-9]" script

链接有效性检查——提取并验证所有内部 Markdown 链接：

# Extract internal links (not http/https)
grep -oP '\[.*?\]\(\K[^)]+(?=\))' docs/file.md | grep -v '^https\?://' | while read link; do
  [ -f "$link" ] || [ -d "$link" ] && echo "OK: $link" || echo "DRIFT: broken link → $link"
done

---

反模式

请勿执行以下操作：

• 捏造偏差——只报告通过 grep/读取实际验证的内容。如果 grep 有结果，但找不到确切说法，标记为 SKIP，而不是 DRIFT。
• 跳过看似正确的文档——每份文档都要检查；直觉不是证据。
• 因格式问题判定失败——缩进错误、正确内容的措辞不同，都不算偏差。
• 报告风格问题——“这个示例可以更清楚”不算偏差。
• 检查外部 API 文档——如果文档描述的是第三方 API，请跳过。
• 过度 grep——匹配确切的标志名称，而不是子字符串。--group 不应匹配 --group-id。

---

添加到团队 Cron

要按计划自动运行 docs-review：

# In crew.yml, under the team's cron section:
cron:
  - schedule: "0 6 * * 1"  # Weekly Monday 6am UTC
    task: "Run docs-review: check docs/ for drift against code"

对于文档有活跃变更的仓库，请使用每日计划：

cron:
  - schedule: "0 7 * * *"  # Daily 7am UTC
    task: "Run docs-review --since yesterday: check docs/ for overnight drift"

---

退出码

退出码	含义
0	未发现偏差（或没有需要审查的文档）
1	发现一项或多项偏差