文档评审

本文档定义了技术文档评审的标准操作规范和检查清单。为了提高评审效率并减少大模型的注意力分散（Attention Dilution），文档评审被拆分为四种独立的评审类型。根据用户的需求，Agent 可以扮演专门的角色，使用对应的专属规则集进行单项审查。

---

1. 评审类型

Agent 在执行评审时，应根据用户的指令或文档的实际状态，选择以下某一种或多种类型独立执行。每种类型的评审都应作为一个独立的 Prompt 任务来处理，并输出独立的评审报告。

1. 大纲评审 (Outline Review)
   • 角色：结构架构师 (Structure Architect)
   • 动作：仅提取文档的所有标题（TOC），对文档骨架进行全局审视。发现结构问题并提供重构建议。
2. 内容评审 (Content Review)
   • 角色：技术编辑 (Technical Editor)
   • 动作：将文档按章节（或子小节）切块，逐个 Chunk 深度阅读。专注于文字质量、技术准确性和代码逻辑。
3. 资产与链接评审 (Assets & References Review)
   • 角色：合规与资产巡检员 (Compliance & Asset Inspector)
   • 动作：提取所有超链接、图片路径、文件引用和参考文献进行批量检查。确保外部依赖有效且合规。
4. 格式评审 (Format Review)
   • 角色：排版校对员 (Typography Proofreader)
   • 动作：对文本进行快速扫描，专注于纯粹的视觉排版和标点规范。此类问题通常支持静默/自动一键修正。

---

2. 评审规则

2.1 大纲评审规则 (结构架构师)

本类型的核心是宏观审查章节安排的逻辑性与合理性，通过分析文档的所有标题（大纲），确保文档骨架具备良好的叙事结构和阅读体验。

• 逻辑闭环与叙事主线：评估整体章节排布是否形成完整的逻辑闭环。
  • 检查目录是否符合该类文档的标准叙事逻辑（如：教程类的“基础-进阶-实战”、架构文档的“背景-架构-模块-部署”、问题排查的“现象-分析-解决-总结”）。
  • 确保文档有清晰的上下文引入和收尾，避免逻辑断层或突兀的章节跳跃。
• 层级关系与包含逻辑：
  • 检查标题层级（H1->H2->H3）是否发生不合理的跳跃（如 H1 直接接 H3）。
  • 检查父子章节之间的包含关系是否严密（子章节的内容必须从属于父章节）。
• 颗粒度与权重对等：检查同级章节的内容颗粒度是否对等，避免出现某一个二级章节庞大无比，而另一个同级章节极其单薄的情况（此时应考虑降级或拆分）。

2.2 内容评审规则 (技术编辑)

本类型的核心是深度阅读与内容质量把控。 执行策略：必须一个章节一个章节、甚至一个子小节一个子小节地进行切块（Chunk）评审，切忌全文泛读。确保内容的准确性、完整性、可读性，以及前后描述的一致性和文风统一。所有纯排版格式问题请留至“格式评审”处理。

• 文字质量：
  • 准确性 (Accuracy)：技术描述必须准确无误，原理推导、数据指标均需正确，避免含糊其辞或技术硬伤。
  • 完整性 (Completeness)：检查当前章节是否完整覆盖了标题所承诺的范围；是否存在关键信息缺失、步骤跳跃或缺乏必要的前提条件说明。
  • 可读性 (Readability)：评估段落结构是否清晰，句子是否过长，逻辑是否容易被读者理解。必要时建议将复杂长句拆分为短句，或将密集文本转换为列表/表格。
  • 文风与语态 (Tone & Voice)：语言风格需严谨、专业，避免口语化和情绪化用语（避免使用"更新："、"现状："等元数据前缀）。尽量使用主动语态，精简冗长、拖沓或被动语态泛滥的句子。
  • 人称代词：中文文档避免使用“你”。泛指受众用“大家”；特指开发者用“我们”；上下文清晰时可省略人称或改用客观表述（如“Agent 理解软件能力”）。
  • 信息溯源：引用的数据、实验结果须说明明确来源；专业术语或缩写首次出现时需提供全称或简要解释。
  • [强制删除] 无效过渡句：大语言模型极易生成“本节将介绍…”、“下面将展示……”等废话。审查规则：如果标题后的第一句话没有提供任何新的技术或业务信息（信息熵为零），必须直接删除该句，绝对不要尝试重写或保留。
    • 🔴 输入：## 缓存设计\n本节主要介绍系统缓存层的设计与实现。为了提升系统吞吐量...
    • 🟢 动作：识别到第一句为无信息量过渡句，直接删除。
    • ✅ 输出：## 缓存设计\n为了提升系统吞吐量...
  • 概述段落要求：章节或子小节标题后的内容必须直接融入业务或技术上下文，提供实质性信息。若父标题下紧接子标题（如 ## 1. 后紧接 ### 1.1）、表格或列表，必须在两者之间补充一段有信息量的总结性文字引出下文。若下文已有详细介绍则不重复。
• 一致性把控：
  • 术语统一：全文的专有名词、核心概念前后必须保持绝对一致（如选定 "KV Cache" 后，通篇不得混用 "键值缓存"）。
  • 逻辑连贯：前后文的设定与描述不能自相矛盾，确保跨章节的上下文逻辑推演顺畅。
• 代码质量：
  • 逻辑与风格：代码示例逻辑必须正确，遵循良好编程风格，兼顾可读性、性能优化与可维护性。
  • 注释说明：代码块必须包含适当的注释，以说明关键逻辑，帮助读者理解。
• 可视化质量：
  • 评估图表（如架构图、时序图）和公式的内容是否准确反映了文字意图。
  • 检查可视化元素与正文描述是否一致，是否存在逻辑漏洞、信息缺失或冗余（注：排版渲染语法问题留至“格式评审”）。

2.3 资产与链接评审规则 (合规与资产巡检员)

本类型的核心是排查文档外部依赖的有效性与内容安全性。 执行策略：全局提取文档中的所有链接、图片路径、配置文件及参考文献进行批量校验，确保文档“资产”无损、合规且安全。

• 文件与目录命名规范：审查文档本身及相关链接中的文件名，建议统一使用小写字母和中划线分隔（如 lowercase-with-hyphens.md），避免使用空格、下划线或驼峰命名。
• 链接有效性：确保文档中的所有内部跳转链接（锚点）和外部超链接格式正确，逻辑上可达。
• 图片引用：使用相对路径，路径中的空格需编码为 %20。
• 安全与脱敏：检查代码块或配置示例中是否包含真实的 API Key、密码、内部 IP 或私人敏感信息，要求使用如 YOUR_API_KEY 等占位符。
• 参考文献:
  • 单引用标记：正文中使用方括号编号引用（如 [1]），引用标记通常置于标点符号之前。
  • 多引用标记：当在同一处引用多个文献时，必须合并在一个方括号内，用逗号分隔（如 [1, 2, 3] 或连续文献 [1-3]）。严禁使用分离的方括号（如错误示例：[1][2][3] 或 [1], [2]）。
  • 格式规范：文末文献列表的排版需高度专业化。[强制跨技能协同] 当发现参考文献列表不规范或需要补充元数据时，你必须直接调用 reference-organizer 技能（通过使用你的 Skill 调用工具 invoke reference-organizer，或输出 /reference-organizer 指令提示用户协同处理）。绝对不要尝试自己捏造引用格式！ 只有在系统明确报错表示该技能不存在时，才允许降级使用以下基础规范：
    • 博客/网页级别 (GB/T 7714-2015)：[序号] [主要责任者]. [题名][EB/OL]. ([更新或修改日期])[引用日期]. [获取和访问路径].
    • 白皮书/技术报告级别 (APA 7th)：[发布机构]. ([发布年份]). *[报告题名]*. [URL]
    • 论文级别 (IEEE)：
      • 期刊论文：[序号] [作者(名首字母. 姓)], "[论文标题]," *[期刊名称缩写]*, vol. [卷号], no. [期号], pp. [起止页码], [发布月份缩写]. [年份].
      • 会议论文：[序号] [作者], "[论文标题]," in *Proc. [会议名称缩写]*, [会议城市], [会议国家], [年份], pp. [起止页码].
      • 预印本：[序号] [作者], "[论文标题]," arXiv preprint arXiv:[ID], [年份].
  • 无需介绍：参考文献章节作为纯列表性质的特殊章节，不需要开头介绍段落，直接列出文献即可。
  • 一致性校验：必须检查正文中的所有引用编号（如 [1]）在文末参考文献列表中是否存在对应项；反之亦然，文末列出的文献必须在正文中被引用过。

2.4 格式评审规则 (排版校对员)

本类型的核心是纯粹的视觉排版与 Markdown 语法规范。 执行策略：在内容定稿后，对全文进行快速扫描。重点关注中英文排版、标点符号、缩进对齐等细粒度格式问题。此类型的评审发现的问题通常强烈建议 Agent 提供一键静默自动修复。

• 文档导航 (TOC)：对于篇幅较长（如包含多个二级/三级标题）的文档，检查开头是否包含 TOC (Table of Contents) 目录，以增强导航友好性。

• 标题语言：标题只使用一种语言，不使用双语标题。

  • 正确：## 核心架构设计
  • 错误：## 核心架构设计 (Core Architecture Design)

• 章节编号：文档必须采用逐级编号的结构（如 1., 1.1, 1.1.1）。注意编号的位置：编号必须写在标题文本内部，而不是尝试去给 Markdown 的井号（#, ##, ###）进行编号。同时，文档的最顶级大标题（# Document Title）不需要编号。

  • 正确：## 1. 核心概念
  • 错误：## 1. 1. 核心概念（重复编号）
  • 错误：## 核心概念（丢失了必要的章节编号）

• 中英文空格：中英文内容之间必须有空格。

  • 正确：使用 Python 编写、基于 RDMA 的传输
  • 错误：使用Python编写、基于RDMA的传输

• 中文与数字空格：中文与数字之间也须有空格。

  • 正确：延迟低于 50 μs
  • 错误：延迟低于50μs

• 标点符号：中文文档主要使用全角标点（，。：；？！），但数字、英文单词、代码片段周围使用半角标点。

  • 正确：支持 vLLM、TGI 等框架。
  • 错误：支持vLLM,TGI等框架.

• 专有名词：严格遵循官方大小写规范。

  • 正确：vLLM, Redis, MySQL, iOS
  • 错误：vllm, redis, mysql, ios

• 表格格式：Markdown 表格中不使用 <br> 等 HTML 标签。表格内容需对齐，列宽合理。对比表格：当需要对比多个方案或特性时，使用 Markdown 表格清晰呈现。

• 列表格式：使用加粗关键词 + 冒号的格式组织定义列表。列表项若为完整句子，结尾需加标点；若为短语，可不加。

  • 正确：- **L1 极速内存层**：GPU 显存，保存活跃数据。

• 提示与警告框 (Alerts/Callouts)：优先使用标准 GitHub 风格的扩展语法（如 > [!NOTE], > [!WARNING], > [!TIP]），避免仅使用粗体或不规范的自定义前缀。

  • 正确：

    > [!WARNING]
    > 生产环境中请勿使用默认密码。
    

  • 错误：**警告**：生产环境中请勿使用默认密码。

• 避免格式滥用：检查是否存在过度使用粗体、斜体或高亮（如连续多行全部加粗）的情况。强调的重点应当精简，避免破坏整体阅读体验。

• 章节分隔：主要顶级章节之间使用 --- 水平线分隔。

• 代码块格式：代码块必须标注对应的语言类型（如 ```python）。

• 可视化元素：

  • Mermaid 图表：优先使用 Mermaid 绘制架构图和流程图，避免使用外部工具生成的不可编辑图片。

  • ASCII 图：对于简单的示意图，可使用 ASCII 图快速表达，例如：

    +--------+     +--------+     +--------+
    | Client | --> | Server | --> |  DB    |
    +--------+     +--------+     +--------+
    

  • LaTeX 公式：

    • 基础语法：数学公式使用 $...$（行内）或 $$...$$（块级）LaTeX 语法。
    • 公式前后空格：行内公式 $...$ 与前后文本之间必须有空格，以确保 GitHub 等平台正确渲染。正确示例：长度： $P$ tokens；错误示例：长度：$P$ tokens。
    • 文本与下标：公式中的描述性文本或多字符下标使用 \text{...}（如 \text{Memory}_{KV}）。
    • 代码变量：涉及代码变量名时，使用 \texttt{...} 包裹以保持等宽字体风格（如 \texttt{block\_size}）。
    • 运算符与符号：乘法使用 \times 而非 *；近似关系使用 \approx；千分位分隔符使用 {,}（如 57{,}344）。
    • 单位标注：数值与单位之间使用 \, 分隔，单位使用正体 \text{...}（如 1.12\,\text{GiB}）。

---

3. 评审输出格式

对于任何一种类型的评审，必须按以下标准格式输出评审报告：

## 评审结果 - [评审类型名称]

### 发现的问题

1. **[类别] 行 XX / 第 N 节**：问题描述。
   - 建议：具体修改建议或重构示例。

### 总结

共发现 X 个问题。

---

4. 示例

用户："帮我进行内容评审，检查 architecture.md 的第 2 节。"

Agent： （触发内容评审规则，加载技术编辑角色）

[内容评审]

发现的问题

1. [文字质量] 第 2 节 标题下：缺少概述段落，直接进入了子小节。
   • 建议：增加一段关于本节架构核心目标的介绍。
2. [一致性] 行 32：术语不一致，前文使用 "KV Cache"，此处为 "键值缓存"。
   • 建议：统一替换为 "KV Cache"。

总结

共发现 2 个问题。是否需要我为您直接应用这些修改？