docx-chapter

> 大纲 → 并行搜索 → 内容合成 → DOCX 生成 → 来源验证 → 交付

依赖

• unified-search skill → https://clawhub.ai/ccmxigua/unified-search-suite
• tavily-research skill → requires Tavily API key

输入格式

title: "章节标题"
description: "章节定位与目标"
sections:
  - heading: "3.1 第一级标题"
    topics:
      - "子主题 1"
      - "子主题 2"
  - heading: "3.2 第一级标题"
    topics:
      - "..."
reference_docx: "/path/to/reference.docx"  # 可选，DOCX 样式参考
output_dir: "/path/to/output"              # 可选，默认 ~/.openclaw/media/outbound/

工作流程

阶段一：大纲解析 → 并行研究计划

1. 解析大纲 YAML，将每个 section 拆为独立研究主题
2. 为每个主题生成 ACP agent 任务：/unified_search <关键词> + Tavily Research 深度搜索 → 来源采集
3. 输出研究计划清单：主题 → 搜索关键词 → 预期来源数

阶段二：并行 ACP 研究（双搜索源：unified_search + Tavily Research）

必须使用 sessions_spawn(runtime="acp", agentId="claude", mode="run")，禁止默认 runtime="subagent"（继承 Telegram 路由会失败）。

> ACP 参数固定规则：以上参数为固定模板，禁止添加 lightContext（仅 subagent 有效，ACP 不认）、
> 禁止添加 runTimeoutSeconds 等额外参数。AC 使用各自后端默认超时。

> ⚠️ #50597 警告：ACP Claude CLI 有 ~30% 概率返回空结果（只含 thinking block，0 输出 token）。
> 见 GitHub #50597。
> 降级策略：子代理返回空、超时、或 Internal error 时，触发自动重试（最多 2 次）。
> 若 3 次全空/全失败，降级走 /unified_search（三引擎搜索），禁止直接使用 llm-task。
>
> 为什么禁止 llm-task 降级：llm-task 让模型直接搜索时，模型会编造/猜测 URL
>（已验证：BrowserStack /guide/beta-testing、/guide/alpha-vs-beta-testing、
> Testim /blog/beta-testing/、SoftwareTestingHelp /alpha-testing-vs-beta-testing/
> 均为 llm-task 幻觉 URL，返回 404）。/unified_search 返回真实可访问的 URL。

每个 ACP 子代理执行两路搜索后合并：

① unified_search（快速结构化搜索）

/unified_search <英文关键词>

记录每个来源的 URL、标题、日期、权威度、原文摘录。

② Tavily 深度研究（补充覆盖面与深度）

node <tavily-research>/scripts/research.mjs \
  "<英语研究问题>" --model pro --out /tmp/tavily_<topic>.md

读取 /tmp/tavily_<topic>.md，从报告中提取：
- 所有被引用的 URL、标题
- 与主题最相关的 2-3 句原文
- 补充 unified_search 未覆盖的来源

> Tavily Research 耗时 20-60s，等待期间可先整理 unified_search 的结果。

③ 合并去重
- 按 URL 去重，同一 URL 出现两次时保留内容更丰富的版本
- unified_search 优先用于 URL 准确性，tavily 用于深度补充
- 标注每个来源的搜索渠道：source_channel

返回结构化 JSON：

{
  "topic": "...",
  "sources": [
    {
      "url": "...",
      "title": "...",
      "date": "...",
      "authority": "gov|academic|news|commercial",
      "source_channel": "unified_search|tavily_research|both",
      "quotes": ["原文句1", "原文句2"],
      "key_data": {"metric": "value"}
    }
  ],
  "suggested_body": "基于来源的正文草稿"
}

阶段三：内容合成

0. 更新 research_results.json：回填研究数据（仅更新，不覆盖已存在的 sources）：
   - name ← 从 topics.json 取对应的 heading（如 "Alpha 测试"）
   - summary ← 从 ACP agent 返回的 suggested_body 提取摘要（2-4 句）
   - key_findings ← 从 suggested_body/sources 提取 3-5 条关键发现
   - status ← "research_completed"
1. 合并所有子代理返回结果
2. 去重 + 冲突检测：同一 URL 被多个子代理返回时保留权威度最高的版本；对同一事实的不同表述标记为 ⚠️ 冲突
3. 生成 MD 正文：每处数据/观点标注脚注引用 [^N]
4. 脚注格式：[^N]: 作者/机构。《标题》。发布日期。URL
5. 脚注从 0 起连续编号
6. 同步输出 verification_keywords.json：每写入一处 [^N] 时，顺带记录：
   - footnote_id：N
   - source_url：对应的来源 URL
   - keywords：该处引用的核心术语/数据（2-5 个英文词/短语，如 ["defect reduction", "85%", "alpha testing"]）
   - 格式：{ "footnotes": [ { "id": "0", "url": "...", "keywords": [...] }, ... ] }
   - 原则：写脚注的人最清楚自己在引用什么，关键词当场定下来。
7. 输出草稿 → 人工审阅（必须，不可跳过）

阶段 3.5：正文脚注完整性检查（必须）

此阶段不可跳过。 在进入 DOCX 生成前，对 chapter.md 正文扫描行内引用残留——即未纳入 [^N] 脚注系统的括号引用。

扫描正则（Python）：

INLINE_CITE_RE = re.compile(
    r'(?:'
    r'[（(][A-Z][A-Za-z]+(?:\s+et\s+al\.?|\s+等)?[，,\s]+\d{4}[a-z]?[)）]'  # （MDPI, 2022） / (Author, 2023)
    r'|[A-Z][A-Za-z]+[（(]\d{4}[)）]'                                         # Nature（2025）
    r')'
)

检测流程：

python3 -c "
import re, sys
with open(sys.argv[1], 'r') as f:
    text = f.read()
INLINE_CITE_RE = re.compile(
    r'(?:'
    r'[\（(][A-Z][A-Za-z]+(?:\s+et\s+al\.?|\s+等)?[，,\s]+\d{4}[a-z]?[)）]'
    r'|[A-Z][A-Za-z]+[\（(]\d{4}[)）]'
    r')'
)
for i, line in enumerate(text.split('\n'), 1):
    if line.lstrip().startswith('[^'):  # skip footnote definitions
        continue
    for m in INLINE_CITE_RE.finditer(line):
        print(f'L{i}: \"{m.group()}\" — 未纳入 [^N] 脚注系统')
" chapter.md

处理规则：
1. 每处匹配 → ERROR 级别。必须逐条回答：
- 该引用对应哪个已验证的来源（URL）？
- 若可对应 → 替换为 [^N] 脚注引用
- 若无法对应任何已验证来源 → 删除该句或降级措辞（移除引用）
2. 检查通过条件：扫描零输出
3. 此检查必须在 pandoc 生成 DOCX 之前完成；若任一 ERROR 未解决，阻断进入阶段四

常见坑：
- 全大写缩写（如 MDPI、OECD）也会被捕获
- 中文/英文括号混合情况均覆盖
- 脚注定义行（[^N]:）自动跳过，不误报

阶段四：DOCX 生成

{{- if .args.reference_docx }}
# 先验证 reference.docx 存在，不存在则去掉 --reference-doc（否则 Pandoc exit 99）
pandoc chapter.md -o chapter.docx \
  --reference-doc="{{ .args.reference_docx }}" \
  --from markdown+footnotes+tex_math_dollars --to docx
{{- else }}
pandoc chapter.md -o chapter.docx \
  --from markdown+footnotes+tex_math_dollars --to docx
{{- end }}

> --reference-doc 可选：不指定时 Pandoc 使用内置默认样式。
>
> ⚠️ Pandoc 3.7 兼容性：tex_math_single_dollar 扩展在 Pandoc 3.7.0.2 中不再支持，
> 仅使用 tex_math_dollars。若 --reference-doc 指向不存在的文件，Pandoc 会以 exit code 99 失败；
> 执行前必须 test -f 验证文件存在。

Heading 层级映射：
Pandoc 将 Markdown heading 映射为 Word 内置样式：
- # → Heading1
- ## → Heading2
- ### → Heading3
- #### → Heading4
章节编号需手动写入标题文字，Pandoc 不自动编号。

脚注 URL 超链接化（强制）：
Pandoc 默认将脚注中的 URL 输出为纯文本，在 Word 中不可点击。
生成 DOCX 后必须执行后处理脚本 add_hyperlink_footnotes.py：

python3 add_hyperlink_footnotes.py chapter.docx chapter.docx

> ⚠️ Pandoc 会重编号脚注：markdown 中的 [^42] 在 DOCX 中可能被重编号为 ID 37、38 等
> （Pandoc 按出现顺序分配连续 ID，且重复引用会被复制到不同 ID）。
> 排查时必须按 URL 内容定位，不可假设 markdown 编号 = DOCX 编号。

> ⚠️ add_hyperlink_footnotes.py 依赖 research_results.json：
> 脚本从 research_results.json 读取 URL→脚注映射来构建超链接。
> 若在修改 chapter.md / research_results.json 后未重跑此脚本，
> DOCX 中的脚注 URL 可能仍为旧值。变更三文件后必须重新执行：
> pandoc → add_hyperlink_footnotes.py → verify_docx.py。

后处理原理：
1. 解压 DOCX，解析 word/footnotes.xml
2. 找到每个脚注正文中的 URL（正确正则含 （））
3. 将 URL 文本拆出独立的 <w:hyperlink> 元素（不含 （日期访问） 等中文后缀）
4. 为超链接内的 <w:r> 添加 <w:rStyle w:val="Hyperlink"/> 以显示蓝色下划线
5. 在 word/_rels/footnotes.xml.rels 中注册对应的 relationship
6. 重新打包 DOCX

阶段五：来源验证（自动）

对每个脚注执行以下检查：

URL 提取正则（已修正）：

# ❌ 错误：中文标点不在排除集，会合并 URL
re.findall(r'https?://[^\s<>"]+', text)

# ✅ 正确：包含全角括号等中文标点
re.findall(r'https?://[^\s<>"」。，；：\!\?」』（）、《》【】…—～]+', text)

阶段六：截图验证（必须）

此阶段不可跳过。 对所有脚注来源执行截图验证。

必须使用 scripts/purple_highlight_screenshot.py，禁止自行编写普通截图脚本。

python3 scripts/purple_highlight_screenshot.py <URL> <output.png> <keyword1> [keyword2] ...

关键词从 verification_keywords.json 中按脚注 ID 查找。若某脚注缺失关键词，回退从 chapter.md 上下文提取。

特殊来源处理：

1. PDF 来源：跳过截图，只做 keyword 匹配（坑 #9）
2. 图片骨架网站：curl -s <URL> 检查 HTML < 2000 chars 基本无正文（坑 #10）

正文措辞审核规则

以下措辞类型必须触发人工确认：

原则：如果源文件中找不到逐字匹配的原句，降级措辞。宁可保守，不可夸大。

DOCX 修改规范

修改已有 DOCX 正文前：

1. 先 dump 所有 run：提取每个 <ns0:r> 的文本和脚注引用
2. 确认分隔边界：脚注引用可能独占空 run（坑 #11）
3. 修改后连读验证：确保 run 间逗号/句号完整
4. 保存前 git diff：对比原始版本确认改动范围

搜索注意事项

• 中文主题：用英文关键词搜索，避免 tokenizer 拆散整词（坑 #3）
• 双搜索源：unified_search 提供结构化快速结果，Tavily Research 提供深度研究补充
• Tavily Research 失败（超时/API 错误/网络问题）→ 静默降级，仅使用 unified_search 结果，不阻断 agent 执行
• 来源筛选：每个主题 3-5 个高质量来源，优先官方/学术
• 对不可达网站：尝试 web.archive.org 缓存版本

错误处理矩阵

Roxy 截图排坑（2026-05-28）

当截图验证（阶段六）遇到普通 Playwright 打不开的 URL（如 ACM DL、BMC、Splunk、ScyllaDB、CAP FAQ、AWS、HBase），需要走 Roxy 严格链路：

正确链路：

@roxybrowser/openapi MCP 开浏览器 → 从 open_browsers 响应提取 CDP WS
  → @roxybrowser/playwright-mcp --cdp-endpoint <ws_url>
  → browser_connect_roxy({ cdpEndpoint: ws_url })
  → browser_navigate → browser_take_screenshot

关键约束：
1. 不要调 get_connection_info 拿 WS URL — 它返回所有已打开浏览器，regex 可能选错 → playwright-mcp 启动崩溃
2. MCP stdio 交互用 Node.js 实现 — Python stdout 有缓冲，bufsize=0 不生效
3. openapi MCP 进程保持存活 — 关闭会导致浏览器被清理，CDP WS 失效
4. 优先复用已有浏览器 — 窗口额度有限，用完截图 close + delete
5. 截图输出路径：browser_take_screenshot 的 filename 为完整绝对路径时，文件保存到该路径（~/.openclaw/media/outbound/xxx/screenshots_roxy/ 需提前 mkdir -p）

参考实现：/tmp/roxy_full.cjs（Node.js，2026-05-28 验证通过，6/7 URL 截图成功）

规则优先级

规则优先级：所有 DOCX 结构检查规则以 verify_docx.py 代码实现为准，本文档描述为辅助说明。若本文档与代码不一致，以代码为准。

脚注格式规范

• 多段脚注：后续段落必须缩进 4 空格。未缩进时 Pandoc 将后续段落视为新脚注定义，导致正文截断
• 脚注内代码块：禁止使用围栏代码块（```），改用 8 空格缩进
• 脚注内表格：需额外 4 空格缩进（共 8 空格）；脚注内表格极易出错（行解析错误、跨列错位），建议尽量避免
• 章节标题编号：需手动编写，Pandoc 不自动编号

已知陷阱与规避

• pandoc（MD → DOCX 转换）
• ACP Claude CLI agent（并行研究 + DOCX 审查）
• curl（URL 可达性检查）
• Playwright（截图验证）
• python3 + lxml（DOCX XML 检查）

Checkpoint 持久化

大型章节管线执行时间较长（10+ 分钟），为避免重启丢失进度，每阶段完成后应将中间产物保存到 output_dir：

恢复时从最近的 checkpoint 继续，跳过已完成的阶段。在 lobster pipeline 中可通过 {{ .args.checkpoint_dir }} 指定 checkpoint 目录（默认同 output_dir）。

输出

• chapter.md — 正文 + 脚注
• chapter.docx — 样式化的 DOCX（含 reference.docx 样式）
• chapter_verification.json — 验证结果（Phase 6）
• verification_keywords.json — 脚注 → 关键词映射（Phase 3 同步产出）
• screenshots/ — 来源截图（Playwright 紫色高亮）

```