三审并行架构

框架文档 — 按数据依赖分割审查维度，实现并行审查的核心创新这是多Agent编辑系统中效率提升最显著的设计模式

1. 设计动机

传统审查的瓶颈

传统做法: 一个Reviewer完成所有维度的审查。

传统单Reviewer审查:

  需要加载的上下文:
  ┌─────────────────────────────────────────────────┐
  │  output/chapters/draft/chXX-draft.md       — 待审查初稿        │
  │  {{源码根目录}}/{{文件列表}} — 验证代码准确性     │
  │  output/memory/chapter-summaries.md   — 检查跨章一致性    │
  │  output/memory/glossary.md            — 检查术语一致性    │
  │  output/memory/metaphor-registry.md  — 检查比喻一致性     │
  │  output/memory/style-guide.md         — 检查写作风格      │
  │  output/memory/source-map.md               — 定位源码文件      │
  └─────────────────────────────────────────────────┘

  总上下文量 = 初稿 + 源码 + 长记忆 + 风格指南
             ≈ 15K + 20K + 15K + 3K
             = 53K tokens

  问题: 上下文窗口可能不够！即使够，注意力也会被稀释。

关键洞察

不同的审查维度需要的数据集合几乎不重叠。

审查维度分析:

  "代码准确吗?"   → 需要: 源码 + 初稿        → 不需要: 长记忆, 风格指南
  "跨章一致吗?"   → 需要: 长记忆 + 初稿       → 不需要: 源码, 风格指南
  "写得好读吗?"   → 需要: 风格指南 + 初稿      → 不需要: 源码, 长记忆

  三个维度的数据需求几乎正交！
  → 可以拆分为三个独立的审查Agent
  → 每个Agent只需加载自己需要的数据子集
  → 三个Agent可以并行执行

2. 三审分工

架构总览

                    output/chapters/draft/chXX-draft.md
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ R1 源码   │ │ R2 一致性│ │ R3 内容  │
        │ 审查      │ │ 审查     │ │ 审查     │
        │          │ │          │ │          │
        │ +源码文件 │ │ +长记忆  │ │ +style   │
        │ +source  │ │  文件    │ │  guide   │
        │  map     │ │          │ │          │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
             ▼            ▼            ▼
        r1.md       r2.md           r3.md
              │            │            │
              └────────────┼────────────┘
                           ▼
                   output/reviews/chXX-review.md
                      （合并报告）

R1: 源码审查

职责: 验证章节中所有代码相关内容的准确性

Agent类型: explore（适合大量源码搜索和比对）

审查项:
  ✅ 代码片段是否与源码一致
  ✅ 函数签名、参数、返回值是否正确
  ✅ 执行流程描述是否与实际代码路径匹配
  ✅ 数据结构描述是否完整准确
  ✅ 设计决策的分析是否有理有据

File Pointers:
  📖 读取: output/chapters/draft/chXX-draft.md          — 待审初稿
  📖 读取: output/memory/source-map.md                 — 定位源码文件
  📖 读取: {{源码根目录}}/{{文件列表}}    — 实际源码
  ✏️ 写入: output/reviews/chXX-r1.md       — 源码审查报告

不读取:
  ✗ output/memory/chapter-summaries.md  — R1不关心跨章一致性
  ✗ output/memory/glossary.md           — R1不检查术语使用
  ✗ output/memory/style-guide.md        — R1不审查写作风格

上下文预算:
  初稿: ~15K tokens
  源码: ~20K tokens（仅本章相关文件）
  source-map: ~2K tokens
  ─────────────────
  总计: ~37K tokens（比53K大幅减少）

R1 报告格式

markdown

# R1 源码审查报告 — 第{{章节号}}章

审查时间: {{时间戳}}
对应初稿: output/chapters/draft/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:
  📖 读取: output/chapters/draft/chXX-draft.md          — 待审初稿
  📖 读取: output/memory/chapter-summaries.md     — 前序章节摘要
  📖 读取: output/memory/glossary.md              — 术语表
  📖 读取: output/memory/metaphor-registry.md    — 比喻注册表
  📖 读取: output/memory/cross-references.md     — 交叉引用表
  ✏️ 写入: output/reviews/chXX-r2.md — 一致性审查报告

不读取:
  ✗ 源码文件        — R2不验证代码
  ✗ style-guide     — R2不审查写作风格

上下文预算:
  初稿: ~15K tokens
  长记忆文件: ~15K tokens（随章节增多而增长）
  ─────────────────
  总计: ~30K tokens

R2 报告格式

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:
  📖 读取: output/chapters/draft/chXX-draft.md     — 待审初稿
  📖 读取: output/memory/style-guide.md      — 写作风格指南
  ✏️ 写入: output/reviews/chXX-r3.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都读取同一份 output/chapters/draft/chXX-draft.md
   但全部是只读操作 → 无竞争

2. 写入无冲突
   R1 写入: output/reviews/chXX-r1.md
   R2 写入: output/reviews/chXX-r2.md
   R3 写入: output/reviews/chXX-r3.md
   三个输出文件完全不同 → 无竞争

3. 无共享可变状态
   三个Reviewer不修改任何共享文件
   长记忆文件在审查阶段是只读的
   → 无副作用冲突

数据隔离矩阵

            │ 源码文件 │ 长记忆文件 │ style-guide │ draft │
────────────┼─────────┼───────────┼────────────┼───────┤
R1 源码审查  │  读取 ✅ │    —      │     —      │ 读取  │
R2 一致性    │    —    │  读取 ✅  │     —      │ 读取  │
R3 内容审查  │    —    │    —      │  读取 ✅   │ 读取  │
────────────┼─────────┼───────────┼────────────┼───────┤
冲突?       │   无    │    无     │     无     │ 无    │
            │(只有R1读)│(只有R2读) │ (只有R3读) │(都只读)│

4. 报告合并

合并时机

三份独立报告完成后，由主编排Agent合并为统一的审查报告。

触发条件:
  output/reviews/chXX-r1.md         存在且有 R1_CODE_REVIEW_COMPLETE
  output/reviews/chXX-r2.md  存在且有 R2_CONSISTENCY_REVIEW_COMPLETE
  output/reviews/chXX-r3.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: output/chapters/draft/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 性能审查:
  📖 读取: output/chapters/draft/chXX-draft.md + 性能基准数据
  ✏️ 写入: output/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: 可扩展可裁剪
  三审不是固定数字，可以根据项目需要增减
  核心是确保每个维度有独立的数据需求

三审并行架构 ​

1. 设计动机 ​

传统审查的瓶颈 ​

关键洞察 ​

2. 三审分工 ​

架构总览 ​

R1: 源码审查 ​

R1 报告格式 ​

R2: 一致性审查 ​

R2 报告格式 ​

R3: 内容审查 ​

R3 报告格式 ​

3. 并行安全性分析 ​

为什么三审并行是安全的 ​

数据隔离矩阵 ​

4. 报告合并 ​

合并时机 ​

合并规则 ​

合并报告格式 ​

合并后的流转 ​

5. 与读者评审团的区别 ​

角色定位对比 ​

执行顺序的理由 ​

读者评审团的数据需求 ​

6. 效率分析 ​

时间对比 ​

质量对比 ​

成本分析 ​

7. 扩展: 自定义审查维度 ​

添加新的Reviewer ​

减少Reviewer ​

8. 设计原则总结 ​

三审并行架构

1. 设计动机

传统审查的瓶颈

关键洞察

2. 三审分工

架构总览

R1: 源码审查

R1 报告格式

R2: 一致性审查

R2 报告格式

R3: 内容审查

R3 报告格式

3. 并行安全性分析

为什么三审并行是安全的

数据隔离矩阵

4. 报告合并

合并时机

合并规则

合并报告格式

合并后的流转

5. 与读者评审团的区别

角色定位对比

执行顺序的理由

读者评审团的数据需求

6. 效率分析

时间对比

质量对比

成本分析

7. 扩展: 自定义审查维度

添加新的Reviewer

减少Reviewer

8. 设计原则总结