Jack.Shang的技术博客

实测：OpenClaw 如何实现大文档报告

用一个完整的 20 章测试案例，验证 AI Agent 生成超长文档的可行性。
背景
核心问题：AI 写长文的三大死穴
问题 表现
上下文不够 目标300页/实际80 页 ≈ 目标16.5万字/实际 4.39 万字，远超任何模型窗口。写到第 50 页时，已经不记得第 1 页写了什么
逻辑断裂 前面说”采用方案 A”，后面又说”方案 B 更优”，前后矛盾
术语漂移 前半篇叫”平台”，后半篇变成”系统”，风格不统一
本质是同一个问题：模型没有”全局记忆”。
解法：用文件系统当外部记忆
我的思路很简单——既然模型记不住，那就帮它记。

┌─────────────────────────────────────────────┐
│              大文档写作架构                    │
├─────────────────────────────────────────────┤
│                                             │
│   doc-outline.md    ← 大纲（全局骨架）        │
│   doc-style.md      ← 术语表 + 风格指南       │
│   doc-deps.md       ← 章节依赖关系           │
│                                             │
│          ↓ 每章写入前读取                     │
│                                             │
│   doc-state.md      ← 已完成章节摘要（桥梁）   │
│          ↑ 每章写完后更新                     │
│                                             │
│   chapter-01.md                          │
│   chapter-02.md     ← 逐章写入              │
│   ...                                     │
│   chapter-20.md                          │
│          ↓ 合并                             │
│                                             │
│   full-report.md    → 蓝风格转换 → .docx     │
└─────────────────────────────────────────────┘

关键文件是 doc-state.md——它是章节间的唯一桥梁。每写完一章，往里面追加摘要（核心结论、关键数据、术语使用）。写下一章前先读它，就知道前面写了什么。
实测：20 章 / 目标300页、实际80页方案文档
测试设计
文档主题：《智慧城市综合管理平台建设方案》（虚构）
项目 数值
章节数 20 章
目标页数 ~300 页 /实际80页
目标字数 ~16.5 万字 /实际4.39万字
表格数 ~40 个
执行方式 子代理后台执行
耗时 ~35 分钟
故意埋错（测试校验能力）
位置 错误类型 具体内容
第 5 章 术语不一致 3 处用了”系统”，应为”平台”
第 8 章 数据矛盾 写”500 路并发”，但第 3 章写的是”1000 路”
第 17 章 术语不一致 2 处用了”软件”，应为”产品”
测试结果
验证项 结果
20 章全部写入 ✅ chapter-01.md ~ chapter-20.md
状态管理正常 ✅ doc-state.md 包含 20 条摘要
埋错 #1 发现 ✅ 第 5 章”系统→平台”被识别并修复
埋错 #2 发现 ✅ 第 8 章 500 vs 1000 路数据矛盾被识别
埋错 #3 发现 ✅ 第 17 章”软件→产品”被识别并修复
合并成功 ✅ full-report.md 80K 字符
docx 生成 ✅ Microsoft Word 2007+ 格式正确
三个故意埋的错误全部被校验阶段抓出来了。
工作流四阶段
Phase 1: 规划（写任何内容之前）
生成三个文件：
大纲 doc-outline.md：20 章的标题、核心论点、关键数据、章节关联
风格指南 doc-style.md：术语表（系统→平台）、语气、数据格式
依赖关系 doc-deps.md：哪些章引用了哪些前序章的内容
这三个文件就是”全局大脑”，后续每章写作都要读取它们。
Phase 2: 逐章写作

对每一章：
  1. 读取 doc-state.md + doc-outline.md + doc-style.md + doc-deps.md
  2. 写入 content/chapter-XX.md
  3. 更新 doc-state.md（追加本章摘要）

核心纪律：每章写完必须更新 doc-state.md。 漏更新 = 后面章节逻辑断裂。
Phase 3: 合并与转换

# 合并 20 章为一个 markdown
for f in content/chapter-*.md; do cat "$f"; done > full-report.md

# 蓝风格 C# 脚本转换为 docx
dotnet-script gen.csx

Phase 4: 校验
读取 doc-state.md + doc-outline.md，检查：
术语是否统一
数据是否矛盾
引用是否对得上
发现问题 → 修复 → 重新生成。
成本分析
40 页（缩小测试） 300 页（完整版）
章节数 10 章 20 章
Input ~475K tokens ~3.5M tokens
Output ~35K tokens ~250K tokens
总计 ~0.5M tokens ~3.75M tokens
成本（mimo-v2.5） ¥0.07 ~¥0.5
80 页文档的生成成本不到一块钱。 主要成本在上下文重复读取（每章都要读大纲+风格+状态），不是内容生成本身。
踩坑经验

1. 内容密度是最大挑战
   子代理每章实际写了 3000-6000 字，低于目标的 6000-10000 字。最终 8 万字 vs 目标 16.5 万字。
   原因： 任务指令中对”每章需要包含什么”描述不够具体。下次需要在大纲里列出每章的二级标题和每节的要点，让子代理有更明确的写作目标。
2. doc-state.md 是命脉
   测试中有一轮子代理忘了更新状态文件，结果后面的章节开始重复前面的术语。加了”每章写完必须更新”的硬性规则后解决。
3. 校验不能省
   即使有术语表，写 20 章还是会出现不一致。校验阶段是兜底，不能因为”有术语表”就跳过。
4. Markdown 中间层是正确选择
   直接用 C# 生成 80 页内容不现实（gen.csx 会超过 10KB 限制）。用 markdown 做中间层，内容管理和格式转换分离，是最务实的方案。
   适用场景
   场景 适合度 说明
   IT 方案文档 ⭐⭐⭐⭐⭐ 结构化强，表格多，最适合
   可行性研究报告 ⭐⭐⭐⭐⭐ 章节清晰，数据密集
   咨询报告 ⭐⭐⭐⭐ 需要更灵活的排版
   学术论文 ⭐⭐⭐ 需要引用管理和格式规范
   小说/长篇叙事 ⭐⭐ 创意内容对一致性要求不同
   总结
   写 80 页文档的技术难点不在 AI 本身，在编排和状态管理：
   用文件系统当外部记忆——弥补上下文窗口不足
   用 doc-state.md 做章节桥梁——保证前后一致
   用校验阶段兜底——抓漏网的不一致
   用 markdown 做中间层——分离内容和格式

OpenClaw 的工具链（write/edit/read/exec/sessions_spawn）完全能支撑这个流程。不需要什么黑科技，就是把工程问题当工程问题解决。

测试环境：OpenClaw v2026.5.28 + xiaomi/mimo-v2.5
完整测试文件：/root/.openclaw/workspace/doc-build/
技能定义：~/.openclaw/skills/blue-word-report/SKILL.md