| name | doc-quality-review |
| description | 将粗略学习笔记转化为结构清晰的文档。核心能力：设计思维导图风格的 TOC 标题（命令/API/配置项 + 功能描述），让读者仅扫描目录即可定位具体操作，无需跳转正文；同时处理内容补充、代码增强、格式规范、技术校验。适用于 `docs/` 下所有手写笔记，无论输入是零散要点还是半成品。触发词：审查文档、整理笔记、润色粗稿、review doc、质量检查、doc audit、文档审查、文档质量、检查笔记、优化笔记。 |
文档质量审查与增强
处理 docs/ 下的笔记，无论输入是零散要点、粗略草稿还是半成品。TOC 标题思维导图化是最高优先级——让目录本身就是可扫描的速查表。
核心原则
- 不扩展（最高约束）：严格基于已有内容优化，不自行添加新主题、新命令、新概念。改进只发生在用户已记录的内容范围内——润色表述、规范标题、补注释、修格式。如果发现值得扩展的点，标记为「扩展建议」，用
AskUserQuestion 征得用户同意后才新增标题节点或内容段落
- TOC 标题：基于已有内容设计思维导图风格的标题，展示给用户确认后才写入
- 格式排版：自动修复，无需确认
- 代码增强（补注释、补示例）：在已有代码块基础上增强，自动执行，完成后汇总
- 技术事实：查证后直接修正错误
- 内容态度：保留用户原文核心描述，只补充不重写
报告和输出中，强调内容用反引号（`）包裹。结构标签仍用加粗。
工作流程
第一步：确认范围
用 AskUserQuestion 确认：
- 目标文件：具体路径，或「最近修改的文档」
- 审查模式：
- 全量审查：整个文件（默认）
- 增量审查：仅
git diff 变更的 H2/H3 区间
第二步：并行收集数据
同时发起以下调用：
Read 读取目标文档全文Grep 提取所有 H2/H3/H4 标题（^#{2,4} ）Grep 提取 --8<-- 代码引用Read 读取 zensical.toml 的 nav 部分- explore agent（后台）验证代码引用文件是否存在
第三步：TOC 设计（核心，最高优先级）
好的 TOC 让读者仅扫描右侧目录就能定位具体操作。这是本 skill 最重要的环节。
标题模式
标题承载两类信息：定位符（具体的命令/API/配置名，让读者快速定位）和语义描述（一句话说明它做什么，让读者判断是否需要深入阅读）。
| 标题类型 | 格式 | 示例 |
|---|
| 命令 | 命令-功能描述 | git add-将文件添加到暂存区 |
| API / 注解 | 名称-作用描述 | @EnableWebSecurity-启用 Web 安全 |
| 配置项 | 配置键-作用描述 | server.port-服务监听端口 |
| 概念 | 纯名称，可附英文 | 暂存区（Staging Area） |
| 分组 / 分类 | 描述性短语 | 文件状态、三个区域 |
设计规则
- 命令标题必须包含完整名称（
git add，不是 add）
- 描述部分简洁，≤15 字
- 同一命令的不同场景可拆分为多个标题（如
git add-添加新文件 和 git add-添加已修改文件）
- 概念标题不加具体操作，保持抽象
- H2 划分知识维度，H3 拆分具体知识点，H4 用于细分变体
- H4 在 zensical TOC 中不可见——如果某 H3 下 ≥3 个 H4 且内容独立，建议提升为 H3
- 同级标题保持对齐：同为命令型或同为概念型，避免混杂导致扫描不连贯
执行流程
- 从已有内容中提取所有命令、API、配置项、概念
- 基于提取到的内容设计 TOC 层级：
- 无标题的粗稿：将已有要点组织为完整 TOC，每个标题必须对应用户已记录的内容
- 有标题的半成品：按模式规则改进已有标题
- 常见问题检查：
- 命令标题缺少定位符（
添加文件到暂存区 → git add-添加文件到暂存区）
- 孤立术语（
概述 → Docker 网络概述）
- 万能标题反复出现（多处
其他、总结）
- 扁平清单（≥5 个连续 H2 无 H3 → 按逻辑分组）
- 扩展建议（可选）：如果发现用户的内容存在明显的知识缺口（如讲了
git add 和 git commit 但跳过了 git status），在 TOC 末尾单独列出「💡 扩展建议」，用 AskUserQuestion 征求用户意见。用户确认后才新增对应的标题节点和内容
- 用
AskUserQuestion 展示设计的完整 TOC（含扩展建议）和改动说明
- 用户确认后进入下一阶段
标题改进示例
🟠 `## 概述` → `## Docker 网络概述`（消除孤立术语）
🟠 `### 添加文件` → `### git add-将文件添加到暂存区`（补充命令定位符）
🟠 `## 其他` → `## 高级用法`（替换万能标题）
第四步：内容增强
根据确认的 TOC 逐节处理。
代码注释（自动，基于已有代码）
- ≥3 行无注释代码块：为关键行加中文注释
- 纯占位符语法（
xxx、<placeholder>）：用真实参数替换，追加具体示例
- 不新增用户未提及的命令或 API——只为已有的代码块添加注释和示例变体
增强示例：
原文：
git add <file>
增强后：
# 将指定文件添加到暂存区
git add <file>
追加示例：
git add README.md # 添加单个文件
git add . # 添加所有修改
git add -p # 交互式选择
内容清晰度
- 代码块前至少一句引导说明
- 术语首次出现时有解释
- 保留用户原文核心描述，润色表述但不改写
- 不自行添加用户未提及的知识点或段落
第五步：格式合规（自动修复）
| 规范 | 说明 |
|---|
| 代码块 ``` 后有空格（带属性时） | ```java → ``` java |
| Admonition 空行 + 4 格缩进 | !!! 标题行后必须空行，内容缩进 4 格 |
| 列表前有空行 | 段落与无序列表间必须空行 |
| 强调用反引号 | **术语** → `术语` |
图片用 <figure> 格式 | 禁止裸 ![]() |
| 交叉引用用「」 | "第X章" → 「章节名」 |
| 中文标点与间距 | 半角→全角、中英文间补空格、补句号 |
标点修复在汇总行注明数量，不逐条列出。
第六步：元数据与注册
- 补充 front matter（
title、icon 等）
title 必须与 zensical.toml nav 标题完全一致- 新增页面需在 nav 注册
- 元数据修复前展示具体变更供确认
第七步：技术校验
准确性：
- 提取关键技术断言（版本号、API 行为、默认值）
- 先查本地缓存
.claude/doc-review-cache.json
- 未命中 → Context7 查证（
resolve-library-id → query-docs）
- Context7 不可用 → WebSearch 查官方文档
- 新验证事实追加到缓存
缓存格式：
{
"facts": [
{
"assertion": "原文断言",
"correct": "正确信息",
"source": "Context7 / 官方文档",
"verified_at": "2025-01-15"
}
]
}
代码引用：--8<-- 路径和标记是否存在。
第八步：输出报告
# 文档审查报告：`文件路径`
> 审查日期：YYYY-MM-DD
## TOC 结构（X H2 / Y H3 / Z H4）
| # | 级别 | 标题 | 状态 |
|---|------|------|------|
| 1 | H2 | `三个区域` | ✅ |
| 2 | H3 | `git add-将文件添加到暂存区` | 🟠 已补充定位符 |
## 自动修复
- 格式排版：X 处
- 代码增强：X 处
- 技术修正：X 处
## 待确认
- 元数据修复（如有）
修复完成后执行 zensical build 验证站点构建。
