三審並行架構
框架文檔 — 按數據依賴分割審查維度，實現並行審查的核心創新 這是多Agent編輯系統中效率提升最顯著的設計模式
1. 設計動機
傳統審查的瓶頸
傳統做法: 一個Reviewer完成所有維度的審查。
传统单Reviewer审查:
需要加载的上下文:
┌─────────────────────────────────────────────────┐
│ drafts/chXX-draft.md — 待审查初稿 │
│ {{源码根目录}}/{{文件列表}} — 验证代码准确性 │
│ meta/chapter-summaries.md — 检查跨章一致性 │
│ meta/glossary.md — 检查术语一致性 │
│ meta/metaphor-registry.md — 检查比喻一致性 │
│ meta/style-guide.md — 检查写作风格 │
│ source-map.md — 定位源码文件 │
└─────────────────────────────────────────────────┘
总上下文量 = 初稿 + 源码 + 长记忆 + 风格指南
≈ 15K + 20K + 15K + 3K
= 53K tokens
问题: 上下文窗口可能不够！即使够，注意力也会被稀释。關鍵洞察
不同的審查維度需要的數據集合幾乎不重疊。
审查维度分析:
"代码准确吗?" → 需要: 源码 + 初稿 → 不需要: 长记忆, 风格指南
"跨章一致吗?" → 需要: 长记忆 + 初稿 → 不需要: 源码, 风格指南
"写得好读吗?" → 需要: 风格指南 + 初稿 → 不需要: 源码, 长记忆
三个维度的数据需求几乎正交！
→ 可以拆分为三个独立的审查Agent
→ 每个Agent只需加载自己需要的数据子集
→ 三个Agent可以并行执行2. 三審分工
架構總覽
drafts/chXX-draft.md
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ R1 源码 │ │ R2 一致性│ │ R3 内容 │
│ 审查 │ │ 审查 │ │ 审查 │
│ │ │ │ │ │
│ +源码文件 │ │ +长记忆 │ │ +style │
│ +source │ │ 文件 │ │ guide │
│ map │ │ │ │ │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
r1-code.md r2-consistency r3-content
.md .md
│ │ │
└────────────┼────────────┘
▼
reviews/chXX-review.md
（合并报告）R1: 源碼審查
职责: 验证章节中所有代码相关内容的准确性
Agent类型: explore（适合大量源码搜索和比对）
审查项:
✅ 代码片段是否与源码一致
✅ 函数签名、参数、返回值是否正确
✅ 执行流程描述是否与实际代码路径匹配
✅ 数据结构描述是否完整准确
✅ 设计决策的分析是否有理有据
File Pointers:
📖 读取: drafts/chXX-draft.md — 待审初稿
📖 读取: source-map.md — 定位源码文件
📖 读取: {{源码根目录}}/{{文件列表}} — 实际源码
✏️ 写入: reviews/chXX-r1-code.md — 源码审查报告
不读取:
✗ meta/chapter-summaries.md — R1不关心跨章一致性
✗ meta/glossary.md — R1不检查术语使用
✗ meta/style-guide.md — R1不审查写作风格
上下文预算:
初稿: ~15K tokens
源码: ~20K tokens（仅本章相关文件）
source-map: ~2K tokens
─────────────────
总计: ~37K tokens（比53K大幅减少）R1 報告格式
markdown
# R1 源码审查报告 — 第{{章节号}}章
审查时间: {{时间戳}}
对应初稿: drafts/ch{{章节号}}-draft.md
参考源码: {{源码文件列表}}
## 审查结果
### ❌ 严重错误（必须修正）
1. [位置: §X.X 第N段]
- 问题: {{描述代码错误}}
- 初稿原文: "{{引用初稿中的错误描述}}"
- 源码实际: "{{引用实际源码}}"
- 建议修正: {{修正建议}}
### ⚠️ 不准确（建议修正）
1. [位置: §X.X 第N段]
- 问题: {{描述不准确之处}}
- 建议: {{修正建议}}
### ✅ 确认正确
- §X.X 中对{{功能A}}的描述准确
- §X.X 中的代码片段与源码一致
- ...
## 总评
- 严重错误: N处
- 不准确: M处
- 建议: {{通过/需修改}}
<!-- R1_CODE_REVIEW_COMPLETE -->R2: 一致性審查
职责: 验证本章与全书已有内容的一致性
Agent类型: explore（适合跨文件搜索和比对）
审查项:
✅ 术语使用是否与glossary一致
✅ 比喻/类比是否与metaphor-registry中的重复或矛盾
✅ 概念解释是否与前序章节一致
✅ 交叉引用是否正确（"如第X章所述"）
✅ 知识递进是否合理（不重复解释已讲过的概念）
File Pointers:
📖 读取: drafts/chXX-draft.md — 待审初稿
📖 读取: meta/chapter-summaries.md — 前序章节摘要
📖 读取: meta/glossary.md — 术语表
📖 读取: meta/metaphor-registry.md — 比喻注册表
📖 读取: meta/cross-references.md — 交叉引用表
✏️ 写入: reviews/chXX-r2-consistency.md — 一致性审查报告
不读取:
✗ 源码文件 — R2不验证代码
✗ style-guide — R2不审查写作风格
上下文预算:
初稿: ~15K tokens
长记忆文件: ~15K tokens（随章节增多而增长）
─────────────────
总计: ~30K tokensR2 報告格式
markdown
# R2 一致性审查报告 — 第{{章节号}}章
审查时间: {{时间戳}}
对比基准: 前{{已完成章节数}}章的长记忆文件
## 审查结果
### ⚠️ 术语不一致
1. [位置: §X.X]
- 本章使用: "{{术语A}}"
- glossary定义: "{{术语B}}"
- 建议: 统一为"{{推荐术语}}"
### ⚠️ 比喻冲突/重复
1. [位置: §X.X]
- 本章比喻: "{{比喻描述}}"
- 已有比喻(第Y章): "{{已有比喻描述}}"
- 建议: {{修改建议}}
### ⚠️ 交叉引用问题
1. [位置: §X.X]
- 原文: "如第Z章所述..."
- 问题: 第Z章未涉及此内容
- 建议: {{修正建议}}
### ✅ 一致性确认
- 术语使用与前序章节一致
- 概念递进合理，未重复已讲内容
- ...
## 新增项（需追加到长记忆）
### 新术语
- {{术语1}}: {{定义}}
### 新比喻
- {{比喻1}}: 用于解释{{概念}}
## 总评
- 不一致项: N处
- 建议: {{通过/需修改}}
<!-- R2_CONSISTENCY_REVIEW_COMPLETE -->R3: 內容審查
职责: 验证可读性、写作质量、{{敏感性检查项}}
Agent类型: general-purpose（需要深度理解和判断）
审查项:
✅ 是否符合style-guide的写作规范
✅ 段落结构是否清晰
✅ 技术概念解释是否通俗易懂
✅ 过渡段落是否自然
✅ {{敏感性检查项}}
✅ 字数是否达标（{{每章目标字数}} ± 20%）
✅ 代码与文字的比例是否合理
File Pointers:
📖 读取: drafts/chXX-draft.md — 待审初稿
📖 读取: meta/style-guide.md — 写作风格指南
✏️ 写入: reviews/chXX-r3-content.md — 内容审查报告
不读取:
✗ 源码文件 — R3不验证代码准确性
✗ 长记忆文件 — R3不检查跨章一致性
上下文预算:
初稿: ~15K tokens
style-guide: ~3K tokens
─────────────────
总计: ~18K tokens（三者中最少）R3 報告格式
markdown
# R3 内容审查报告 — 第{{章节号}}章
审查时间: {{时间戳}}
字数统计: {{实际字数}} / {{目标字数}}（{{百分比}}%）
## 审查结果
### ❌ 敏感性问题
1. [位置: §X.X 第N段]
- 问题: {{敏感性问题描述}}
- 建议: {{修改建议}}
### ⚠️ 可读性问题
1. [位置: §X.X]
- 问题: 技术概念解释过于晦涩
- 原文: "{{引用原文}}"
- 建议: {{改写建议}}
### 💡 写作建议
1. [位置: §X.X]
- 建议: {{改进建议}}
### ✅ 写作质量确认
- 开篇引入自然流畅
- 代码与文字比例合理
- ...
## 总评
- 敏感性问题: N处
- 可读性问题: M处
- 字数达标: {{是/否}}
- 建议: {{通过/需修改}}
<!-- R3_CONTENT_REVIEW_COMPLETE -->3. 並行安全性分析
爲什麼三審並行是安全的
并发安全的三个条件:
1. 读取无冲突
三个Reviewer都读取同一份 drafts/chXX-draft.md
但全部是只读操作 → 无竞争
2. 写入无冲突
R1 写入: reviews/chXX-r1-code.md
R2 写入: reviews/chXX-r2-consistency.md
R3 写入: reviews/chXX-r3-content.md
三个输出文件完全不同 → 无竞争
3. 无共享可变状态
三个Reviewer不修改任何共享文件
长记忆文件在审查阶段是只读的
→ 无副作用冲突數據隔離矩陣
│ 源码文件 │ 长记忆文件 │ style-guide │ draft │
────────────┼─────────┼───────────┼────────────┼───────┤
R1 源码审查 │ 读取 ✅ │ — │ — │ 读取 │
R2 一致性 │ — │ 读取 ✅ │ — │ 读取 │
R3 内容审查 │ — │ — │ 读取 ✅ │ 读取 │
────────────┼─────────┼───────────┼────────────┼───────┤
冲突? │ 无 │ 无 │ 无 │ 无 │
│(只有R1读)│(只有R2读) │ (只有R3读) │(都只读)│4. 報告合併
合併時機
三份獨立報告完成後，由主編排Agent合併爲統一的審查報告。
触发条件:
reviews/chXX-r1-code.md 存在且有 R1_CODE_REVIEW_COMPLETE
reviews/chXX-r2-consistency.md 存在且有 R2_CONSISTENCY_REVIEW_COMPLETE
reviews/chXX-r3-content.md 存在且有 R3_CONTENT_REVIEW_COMPLETE
三个条件全部满足 → 触发合并合併規則
优先级（从高到低）:
1. R1的 ❌（代码错误） — 最高优先级
代码不准确是技术书籍的致命伤
任何❌都必须修正后才能通过
2. R3的 ❌（敏感性问题） — 高优先级
敏感性问题必须处理
3. R2的 ⚠️（不一致） — 中优先级
跨章不一致影响阅读体验
建议修正但不阻塞
4. R3的 ⚠️（可读性问题） — 中优先级
影响阅读体验
5. 所有 💡（建议） — 低优先级
可以采纳也可以忽略合併報告格式
markdown
# 综合审查报告 — 第{{章节号}}章
合并时间: {{时间戳}}
来源: R1源码审查 + R2一致性审查 + R3内容审查
## 总体判定: {{通过 / 需修改}}
## ❌ 必须修正（来自R1/R3）
1. [R1] {{代码错误描述}} → {{修正建议}}
2. [R3] {{敏感性问题描述}} → {{修正建议}}
## ⚠️ 建议修正（来自R2/R3）
1. [R2] {{一致性问题描述}} → {{修正建议}}
2. [R3] {{可读性问题描述}} → {{改写建议}}
## 💡 可选改进
1. [R3] {{建议描述}}
## 新增长记忆项（来自R2）
### 新术语
- {{术语}}: {{定义}}
### 新比喻
- {{比喻描述}}
## 各审查员总评
- R1 源码审查: {{通过/需修改}} (❌×N, ⚠️×M)
- R2 一致性审查: {{通过/需修改}} (⚠️×N)
- R3 内容审查: {{通过/需修改}} (❌×N, ⚠️×M, 💡×K)
<!-- REVIEW_COMPLETE -->合併後的流轉
合并报告判定为"通过":
→ 进入Step 4（读者评审团）
→ 不需要作家修改
合并报告判定为"需修改":
→ 将合并报告 + 原draft发送给作家(#4)
→ 作家针对❌和⚠️项进行修改
→ 输出新版draft: drafts/chXX-draft-v2.md
→ 重新审查（仅重审相关维度）
→ 最大重试次数: {{最大审查重试次数，默认2}}5. 與讀者評審團的區別
角色定位對比
┌────────────────────────┬──────────────────────────┐
│ 审查组 (R1/R2/R3) │ 读者评审团 (RS/RE/RH) │
├────────────────────────┼──────────────────────────┤
│ 审查技术质量 │ 评估阅读体验 │
│ 有"通过/不通过"权力 │ 只提建议，无否决权 │
│ 发现错误必须修正 │ 意见仅供参考 │
│ 在Step 3执行 │ 在Step 4执行 │
│ 关注: 对不对 │ 关注: 好不好读 │
│ 基于客观标准 │ 基于主观感受 │
│ 必须全部通过才能继续 │ 不影响流程推进 │
└────────────────────────┴──────────────────────────┘執行順序的理由
为什么审查组在前，读者评审在后?
1. 如果代码有错，读者评审毫无意义
→ 先确保内容正确，再评估体验
2. 审查可能导致修改，修改后内容变化
→ 让读者评审在最终版本上执行
3. 审查有否决权，可能触发重写
→ 先过"硬指标"再过"软指标"
流程:
写作 → 审查组(R1+R2+R3) → [可能修改] → 读者评审(RS+RE+RH) → 完成讀者評審團的數據需求
读者评审团不需要源码或长记忆:
RS {{读者画像_学生}}:
📖 读取: draft + 合并审查报告
关注: 学习曲线、前置知识假设、示例难度
RE {{读者画像_工程师}}:
📖 读取: draft + 合并审查报告
关注: 实用价值、可操作性、工程实践
RH {{读者画像_高手}}:
📖 读取: draft + 合并审查报告
关注: 技术深度、高级用法、性能分析6. 效率分析
時間對比
假设:
单个Reviewer加载全部上下文审查: T_full 分钟
R1审查（仅源码维度）: T_r1 ≈ 0.6 × T_full
R2审查（仅一致性维度）: T_r2 ≈ 0.4 × T_full
R3审查（仅内容维度）: T_r3 ≈ 0.3 × T_full
合并报告: T_merge ≈ 0.1 × T_full
串行审查: T_serial = T_full
三审并行: T_parallel = max(T_r1, T_r2, T_r3) + T_merge
= 0.6 × T_full + 0.1 × T_full
= 0.7 × T_full
效率提升: 约30%的时间节约質量對比
串行（单Reviewer）:
优势: 单一视角，内部一致
劣势: 注意力分散，容易遗漏，上下文窗口压力大
并行（三Reviewer）:
优势:
- 每个Reviewer专注一个维度，注意力集中
- 每个Reviewer的上下文窗口压力小
- 三个独立视角，不容易同时遗漏
劣势:
- 需要额外的合并步骤
- 三个Reviewer可能对同一段落有不同意见（通过优先级规则解决）
结论: 三审并行在时间和质量上都优于串行审查。成本分析
API调用成本:
串行: 1次调用 × 大上下文 = 高单次成本
并行: 3次调用 × 小上下文 = 3倍调用次数但每次成本低
由于大多数API按token计费:
串行: 53K input tokens × 1 = 53K tokens
并行: 37K + 30K + 18K = 85K tokens
并行的总输入token略多（因为draft被读取了3次），
但考虑时间节约和质量提升，通常是值得的。
优化: 如果成本敏感，可以在R2和R3中使用较小/便宜的模型，
因为它们的任务复杂度低于R1。7. 擴展: 自定義審查維度
添加新的Reviewer
三審架構可以擴展爲N審。關鍵是確保新維度有獨立的數據需求。
示例: 添加R4 性能审查
R4 性能审查:
📖 读取: drafts/chXX-draft.md + 性能基准数据
✏️ 写入: reviews/chXX-r4-performance.md
审查项: 代码示例的性能影响描述是否准确，是否遗漏重要的性能考量
完成标记: <!-- R4_PERFORMANCE_REVIEW_COMPLETE -->
与R1/R2/R3并行安全: ✅ （写入不同文件，读取不重叠的辅助数据）減少Reviewer
對於不需要所有維度的簡單項目:
精简方案1: 只保留R1+R3
- R1验证代码，R3验证可读性
- 省略R2一致性（适用于短书/独立章节）
精简方案2: 只保留R1
- 只验证代码准确性
- 适用于技术笔记/文档而非正式书籍
注意: 无论怎么精简，R1源码审查都建议保留，
因为代码准确性是技术书籍的底线。8. 設計原則總結
原则1: 按数据依赖分割
不同审查维度需要不同的数据 → 让它们各取所需
原则2: 读取共享，写入隔离
所有Reviewer共享同一份draft的只读访问
但各自写入独立的报告文件
原则3: 优先级解决冲突
不同Reviewer可能对同一问题有不同看法
通过明确的优先级规则解决冲突
原则4: 可扩展可裁剪
三审不是固定数字，可以根据项目需要增减
核心是确保每个维度有独立的数据需求