doc-review — 技术文档三审三校插件

Claude Code 插件：借鉴出版业"编辑部三审三校"制度，用 6 个专业 Agent 协作审校技术文档，确保每一个代码引用都经过实际代码库验证。

解决什么问题

使用 AI 生成技术文档时，普遍存在三大痛点：

问题	表现	后果
准确性不足	方法描述与实际代码实现有偏差	需要 2-3 轮反复 review
幻觉严重	引用不存在的方法名、函数名、类名	交付阶段大量返工
路由混淆	同名不同义的变量/路由被混用	语义不准确，误导开发者

本插件通过深度代码验证策略，逐符号、逐签名、逐路由地比对文档与代码库，从根源解决这些问题。

快速开始

安装

claude /install-plugin github:ShieldBytes/doc-review-plugin

使用

# 审校指定文档
/doc-review docs/api-reference.md

# 指定代码库路径（当文档和代码不在同一目录时）
/doc-review docs/api-reference.md --codebase /path/to/code

输出

审校完成后自动生成：

• doc-review-report-{timestamp}.md — 审校报告（按严重程度排序）
• {文档名}.reviewed.md — 修订版文档

审校流程

采用串行三审 + 并行三校的混合调度策略：

  ┌──────────────────────────────────────────────┐
  │              三审（串行流水线）                  │
  │                                              │
  │  T1 初审  ──→  T2 复审  ──→  T3 终审          │
  │  结构+初筛     签名+调用链    交叉+回归         │
  │                    │                         │
  │              ┌─────┘                         │
  │              ▼                               │
  │         三校（与终审并行）                      │
  │                                              │
  │         T4 一校  ──→  T5 二校                 │
  │         逐字符比对     术语+格式               │
  └──────────────────────────────────────────────┘
                        │
                        ▼
                  T6 总编汇总
                  生成报告+修订版

关键特性：T3（终审）和 T4（一校）并行执行，因为它们只依赖 T2 的结果而互不依赖，最大化效率。

Agent 团队

Agent	角色	模型	核心职责
editor-in-chief	总编	opus	协调流程、技术栈检测、汇总报告
first-reviewer	初审员	opus	文档结构完整性 + 代码引用批量 Grep 验证
second-reviewer	复审员	opus	函数签名深度验证 + 调用链追踪 + 同名消歧
final-reviewer	终审员	opus	交叉一致性 + 回归检查 + 反向 API 覆盖
first-proofreader	一校员	opus	逐字符代码块比对 + import 路径校验
second-proofreader	二校员	sonnet	术语一致性 + 格式规范
lang-expert-template	语言专家	—	动态模板，总编根据技术栈实例化

各角色详解

总编（Editor-in-Chief）

整个审校团队的协调者和最终裁决者。

1. 扫描项目技术栈（package.json/go.mod/Cargo.toml 等）
2. 从语言专家模板动态构造 grep 模式
3. 创建 6 个审校任务并管理依赖关系
4. 汇总所有审校结果，按严重程度排序
5. 生成修订版文档

初审员（First Reviewer）

三遍扫描提取文档中的所有代码引用：

• 第一遍：代码块中的符号（函数、类、import、路由）
• 第二遍：行内代码（反引号中的符号）
• 第三遍：自然语言中的技术术语（PascalCase/camelCase）

对每个符号用 Grep 批量验证存在性，未找到的执行模糊搜索检测拼写错误。

复审员（Second Reviewer）

不信任初审结论，对每个符号独立 Read 源文件进行二次验证：

• 函数签名精确比对（参数名、类型、返回值、顺序）
• 调用链追踪（"A 调用 B" → Read A 确认实际调用关系）
• 同名消歧（不同模块同名符号，标注具体指向）

终审员（Final Reviewer）

拥有最终裁决权，初审和复审结论冲突时以终审为准：

• 交叉一致性：同一实体在文档不同位置描述是否一致
• 回归检查：前两审修正是否引入新问题
• 反向检查：代码中的 public API 是否在文档中都有记载
• 边界条件：错误处理流程是否与代码中的 try-catch 一致

一校员（First Proofreader）

逐字符级别的精确比对：

• 文档代码块 vs 源代码的 unified diff
• import 路径是否真实存在
• 行内代码中的方法调用参数数量和名称

二校员（Second Proofreader）

全文一致性守护者（使用 sonnet 模型，格式校对不需最强推理）：

• 术语统一：同一概念全文命名一致
• 格式规范：Markdown 格式、代码块语言标记
• 审校标记完整性：确认所有问题都已处理

变更分类体系

所有审校员使用统一的五级分类标记：

标记	分类	含义	判断依据
🟢	EXISTS	已存在，描述准确	Grep 找到 + Read 确认签名一致
🔵	MODIFY	已存在，描述有偏差	Grep 找到 + 签名/行为与文档不同
🟡	NEW	不存在，计划新增	Grep 未找到 + 文档用"将要/计划/新增"等词
🔴	HALLUCINATION	不存在，错误引用	Grep 未找到 + 文档用"现有的/当前的/调用"等词
🟠	AMBIGUOUS	多义引用	Grep 找到多处 + 无法确定指向

区分 NEW 和 HALLUCINATION

关键在于文档章节的语义：

• 文档在"实现方案/设计/计划"章节且代码中不存在 → NEW（🟡）
• 文档在"API 参考/使用说明/当前架构"章节且代码中不存在 → HALLUCINATION（🔴）

支持的语言和框架

总编自动检测项目技术栈，语言专家模板提供对应的 grep 模式：

语言	检测文件	支持框架
TypeScript/JavaScript	package.json, tsconfig.json	Next.js, Express, Koa, Fastify, React
Python	pyproject.toml, requirements.txt	FastAPI, Django, Flask
Go	go.mod	Gin, Echo, Chi, net/http, GORM
Rust	Cargo.toml	Axum, Actix-web
Java/Kotlin	build.gradle, pom.xml	Spring Boot
Swift	Package.swift	—

多语言项目：总编会为每种语言创建独立的 grep 模式集，跨语言 API 调用（如前端调用后端 API）需要两种模式配合验证。

审校报告示例

📋 文档审校完成

📊 问题统计:
  🔴 HALLUCINATION: 3 个（不存在的引用）
  🟠 AMBIGUOUS: 1 个（多义引用）
  🔵 MODIFY: 5 个（签名不匹配）
  🟡 NEW: 2 个（待实现功能）
  🟢 EXISTS: 42 个（已验证通过）

⚠️ 最严重问题:
  1. L55: `fetchUser()` — 函数不存在，建议改为 `fetchUserData()`
  2. L88: `GetByID(id int64)` — 实际参数类型为 uint64
  3. L102: `/api/v2/users` — 路由不存在，实际为 `/api/v1/users`

📄 审校报告: docs/doc-review-report-20260319.md
📝 修订文档: docs/api-reference.reviewed.md

Hookify 集成（可选）

本插件提供一个 hookify 规则示例，当技术文档被更新时自动提醒执行审校。

启用方式

将 examples/hookify.doc-review-reminder.example.md 复制到你的项目或全局 .claude/ 目录：

# 项目级（仅当前项目生效）
cp examples/hookify.doc-review-reminder.example.md .claude/hookify.doc-review-reminder.local.md

# 全局（所有项目生效）
cp examples/hookify.doc-review-reminder.example.md ~/.claude/hookify.doc-review-reminder.local.md

需要先安装 hookify 插件。

深度调用策略

本插件的核心设计原则：不关心 token 消耗，只关注准确性。

每个审校员的验证要求：

1. 每个代码引用：不仅 Grep 搜索关键字，还要 Read 源文件确认完整上下文
2. 每个函数签名：Read 完整函数定义，比对参数名+类型+返回值
3. 每个路由：Read 路由注册文件，确认路径+HTTP方法+Handler 三者匹配
4. 禁止依赖记忆：每次验证必须通过工具调用获取实际代码
5. 批量搜索优化：同类符号合并正则 Grep，减少调用次数但不降低深度

插件结构

doc-review-plugin/
├── .claude-plugin/
│   └── plugin.json              # 插件元数据
├── agents/                       # 7 个 Agent 定义
│   ├── editor-in-chief.md       # 总编（协调者）
│   ├── first-reviewer.md        # 初审员
│   ├── second-reviewer.md       # 复审员
│   ├── final-reviewer.md        # 终审员
│   ├── first-proofreader.md     # 一校员
│   ├── second-proofreader.md    # 二校员
│   └── lang-expert-template.md  # 语言专家模板
├── commands/
│   └── doc-review.md            # /doc-review 命令入口
├── skills/
│   └── doc-review-workflow/
│       └── SKILL.md             # 审校流程 Skill
├── examples/
│   └── hookify.doc-review-reminder.example.md  # hookify 规则示例
├── .gitignore
├── LICENSE
└── README.md

常见问题

Q: 审校一份文档大概需要多长时间？

取决于文档大小和代码引用数量。由于采用串行审查+并行校对的混合调度，大部分时间花在 T1→T2 的深度验证上。

Q: 可以只运行部分审校步骤吗？

目前 /doc-review 命令执行完整的六轮审校。如果需要快速检查，可以直接调用单个 Agent（如仅运行初审）。

Q: 支持非 Markdown 格式的文档吗？

目前主要针对 Markdown（.md/.mdx）格式优化。对于其他格式（如 AsciiDoc、reStructuredText），代码引用提取的准确度可能有所下降。

Q: 二校员为什么用 sonnet 而不是 opus？

术语一致性和格式规范检查不需要最强的推理能力。使用 sonnet 可以在保证质量的同时降低成本。

Q: 如何处理文档中描述的尚未实现的功能？

审校员会区分 NEW（🟡）和 HALLUCINATION（🔴）：

• 在"实现方案/设计"章节中描述且代码中不存在 → NEW（正常，待实现）
• 在"API 参考/使用说明"章节中描述且代码中不存在 → HALLUCINATION（错误）

贡献

欢迎提交 Issue 和 PR。

许可

MIT License