doc-quality-review

name	doc-quality-review
description	对 docs/ 下的文档进行系统化质量审查（7 个维度）。维度：技术准确性（Context7 MCP + @Since 版本校验）、教学风格合规性、TOC 大纲结构、学习目标完整性、代码引用有效性、排版风格一致性、内容充实度。适用于新增或修改文档后的质量把关。触发词：审查文档、review doc、质量检查、doc audit。

文档内容质量审查

对 docs/ 目录下的 Markdown 文档进行系统化质量审查，输出审查报告并提出修复建议。

严重程度定义

级别	含义	行动
🔴 必须修复	技术事实错误、代码引用失效、会误导读者	审查后立即修复
🟡 建议修复	风格偏差、结构可优化、内容过薄但不影响正确性	建议本次修复，可协商跳过
✅ 通过	无问题	无需操作

审查流程

第一步：确认审查范围

使用 ask_user 确认以下信息：

1. 审查哪些文件：具体文件路径，或「最近修改的文档」
2. 审查深度：快速扫描（仅结构 + 风格）还是深度审查（含技术准确性验证）

第二步：并行收集数据

⚡ 效率关键：以下操作应尽量并行执行，不要串行等待。

同时发起以下调用：

• view 读取目标文档全文
• grep 提取所有 H2/H3 标题（^#{2,3} ）
• grep 提取所有 --8<-- 代码引用
• view 读取学习目标列表（🎯 本文你会学到 所在行）
• explore agent（后台）验证所有代码引用标记是否存在

第三步：执行审查（按以下 7 个维度检查）

⚡ 维度 1 的 Context7 查询与维度 5 的代码引用验证可并行。

---

审查维度 1：技术准确性

目标：确保文档中的 API 用法、版本号、类继承关系、方法签名、行为描述与官方文档一致。

方法：

1. 提取文档中涉及的核心技术断言（如「PrintStream 默认自动刷新」「Scanner 用正则做分词」）
2. 重点关注版本号声明 — 对所有形如「Java X 引入」「JDK X.Y 新增」「@Since: X」的断言，必须通过 Context7 查证 @Since 标签
3. 使用 Context7 MCP 查证关键事实：
   • 先调用 context7-resolve-library-id 解析库 ID（如 java → /websites/oracle_en_java_javase_21_api）
   • 再调用 context7-query-docs 查询具体 API 的 @Since 标签和行为描述
   • ⚡ 多个独立查询可并行发起
4. 对无法通过 Context7 查证的断言，使用 web_search 查找官方文档确认

常见错误模式：

错误类型	示例	查证方法
版本张冠李戴	「FileReader(Charset) 是 Java 18 引入的」（实为 Java 11）	Context7 查 @Since
默认值错误	「BufferedInputStream 默认缓冲区 4KB」（实际是 8KB）	Context7 查源码常量
行为描述不准确	「PrintStream 默认自动刷新」（需构造时传 autoFlush=true）	Context7 查构造函数
弃用 API 未标注	使用已 deprecated 的方法但未说明替代方案	Context7 查 @Deprecated

已验证事实速查（减少重复查询）：

断言	正确值	来源
FileReader(String, Charset)	@Since: 11	Context7 Java SE 21 API
Path.of()	@Since: 11	Context7 Java SE 21 API
BufferedInputStream 默认缓冲区	8192 bytes (8KB)	Context7 Java SE 21 API
Scanner	@Since: 1.5（Java 5）	Context7 Java SE 21 API
PrintStream 默认 autoFlush	false（构造时指定）	Context7 Java SE 21 API

输出格式：

🔴 [准确性] 第 X 行：「原文引用」
   事实：<正确描述>（来源：Context7 @Since / 官方文档）
   修复建议：<具体修改>

---

审查维度 2：教学风格

目标：确保文档符合项目 CLAUDE.md 中定义的教学风格约束（仅适用于非翻译类内容）。

检查项：

检查项	规范要求	审查方法
类比优先	先用生活常识类比，再给精确定义	每个新概念首次出现时是否有类比
循序渐进	先最简版本，再完整细节	复杂主题是否从简单示例入手
术语零门槛	专有名词首次出现先解释	搜索技术术语首次出现位置
知识点结构	What → Why → How → Pitfalls	每个 H3 是否遵循此脉络
代码示例	标注语言、关键行加注释、最小可运行	代码块是否有 title、是否有注释
节奏控制	每 H3 约 5 分钟可读完、每 2-3 个知识点后小结	估算阅读时长
禁止项	不能上来就贴大段代码、不堆砌官方文档原文	代码块前是否有自然语言引导

豁免：docs/document-translation/ 下的翻译文档忠于原书风格，不审查教学风格。

输出格式：

🟡 [教学风格] 第 X 行 H3「标题名」：
   问题：<描述>
   建议：<改进方向>

---

审查维度 3：TOC 大纲结构

目标：确保标题层级 = 知识脉络，读者只看 TOC 就能理解文章推进逻辑。

检查项：

1. 提取所有 H2/H3 标题（用 grep 匹配 ^#{2,3} ）
2. 检查渐进逻辑：H2 从上到下是否体现知识阶段递进
3. 检查 H3 拆分：任何 H2 下涵盖 ≥3 个子概念时是否拆出 H3
4. 检查反模式：
   • 扁平清单（≥5 个连续 H2 无 H3）
   • 孤立术语（H2 标题为纯类名，无上下文）
   • 万能标题（反复出现「概述」「其他」「总结」）
   • 编号代替逻辑（「第一步」「第二步」）
5. ⚠️ 重点检查 H4 可见性：Zensical TOC 只显示 H2+H3，H4 在右侧目录中完全不可见。如果某个 H3 下有 ≥3 个 H4 子节且每个 H4 内容独立，应考虑将这些 H4 提升为 H3（父级 H3 提升为 H2）。这是实际审查中发现的高频问题。

命名风格检查：

推荐	避免
### 为什么需要连接池？	### 连接池概述
### Access Token（父级 H2 已给上下文）	## Access Token（孤立术语作 H2）
### 连接池 vs 直连对比	### 对比

输出格式：

🟠 [TOC 结构] H2「标题」：
   问题：<描述>（反模式：<模式名>）
   建议：<重构方案>

---

审查维度 4：学习目标完整性

目标：确保文档开头的「🎯 本文你会学到」列表与实际 H2 章节一一对应。

检查方法：

1. 提取「🎯 本文你会学到」列表中的条目
2. 提取所有 H2 标题
3. 交叉对比：
   • H2 有但列表中没有 → 遗漏
   • 列表中有但 H2 没有 → 空头承诺
   • 措辞不一致（如列表说「互转」但 H2 说「对比与互转」） → 措辞偏差

输出格式：

🔴 [学习目标] 遗漏：H2「WatchService——监控目录变化」未出现在学习目标列表中
🟡 [学习目标] 措辞偏差：列表「File 与 Path 的互转」 vs H2「File vs Path——对比与互转」

---

审查维度 5：代码引用有效性

目标：确保所有 --8<-- 代码片段引用指向存在的文件和标记。

检查方法：

1. 用 grep 提取文档中所有 --8<-- "..." 引用路径
2. 对每个路径检查文件是否存在（view 工具）
3. 如果引用包含标记名（:marker_name），检查目标文件中是否存在 // --8<-- [start:marker_name] 和 // --8<-- [end:marker_name]

输出格式：

🔴 [代码引用] 第 X 行：文件不存在 — "code/java/javase/io/io-xxx/..."
🔴 [代码引用] 第 X 行：标记不存在 — ":some_marker" 在目标文件中未找到

---

审查维度 6：排版风格一致性

目标：确保文档遵守 CLAUDE.md 中定义的排版约定。

检查项：

规范	检查方法
强调用反引号 `	搜索 **技术术语** 或 *技术术语*，应改为 `技术术语`
补充说明用括号	中文语境中使用全角括号 （说明） 是可接受的，但应全文统一
交叉引用用「」	搜索"第X章"或"见第X节"，应改为「章节标题名」
图片用 <figure> 格式	检查是否有裸 ![]() 图片语法
代码块 ``` 后有空格	带属性时（title= 等），``` 与语言标识符间需有空格
Emoji 不过度	单段落不超过 1 个 Emoji
H2 有 Emoji 前缀	每个 H2 标题前应有 Emoji（仅自编笔记）
导航图标仅二级目录	只有 docs/分类/子分类/index.md 的 front matter 才有 icon:

输出格式：

🟡 [排版] 第 X 行：技术术语「Authorization Code」使用了加粗而非反引号

---

审查维度 7：内容充实度

目标：确保每个章节都有足够的内容支撑，不存在「占位符式」的薄弱段落。

检查方法：

1. 逐个扫描 H2/H3 小节，计算每节的有效散文行数（排除空行、代码块、表格、图片）
2. 标记以下情况为「薄节」：
   • H2 小节有效散文 ≤ 3 行且无代码示例
   • H3 小节有效散文 ≤ 1 行且无代码示例
   • 某个技术概念只用一句话提及但没有展开解释或示例

严重程度判定：

情况	级别
H2 节只有 1-2 句话、无代码、无表格	🟡 建议修复
H3 节只有一句引入语、无实质内容	🟡 建议修复
概念被提及但未解释（假设读者已知）	🔴 必须修复（违反术语零门槛）

输出格式：

🟡 [充实度] 第 X 行 H3「标题」：
   问题：仅有 1 句话（X 字），无代码示例
   建议：补充 What/Why/How 结构，或至少添加一个代码示例

---

第四步：生成审查报告

按以下表格格式汇总所有发现（比列表更清晰易读）：

# 📋 文档审查报告：<文件路径>

## 🔴 必须修复（X 处）

| # | 维度 | 行号 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | 准确性 | L333 | 版本号错误... | 改为... |

## 🟡 建议修复（X 处）

| # | 维度 | 行号 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | 充实度 | L472 | 内容过薄... | 补充... |

## ✅ 审查通过

| 维度 | 状态 | 详情 |
|------|------|------|
| 技术准确性 | ✅ 通过 | 查证了 X 个断言，均正确 |
| 教学风格 | ✅ 通过 | 类比+渐进+术语解释均到位 |
| TOC 结构 | ✅ 通过 | X H2 / Y H3，逻辑清晰 |
| 学习目标 | ✅ 通过 | X 条目标与 X 个 H2 对应 |
| 代码引用 | ✅ 通过 | X/X 引用验证通过 |
| 排版风格 | ✅ 通过 | 格式一致 |
| 内容充实度 | ✅ 通过 | 无薄节 |

第五步：修复

使用 ask_user 询问用户是否需要自动修复。如果用户确认：

1. 按严重程度从高到低修复
2. 每修复一处用 edit 工具直接更改
3. 修复完成后执行 zensical build 验证站点构建
4. 使用 git-commit skill 提交修复