Docx Chapter Clean

Research-backed chapter pipeline: outline → parallel ACP research → MD synthesis → DOCX generation → source verification → screenshot verification (mandatory)

ccmxigua@ccmxigua

Install

openclaw skills install @ccmxigua/docx-chapter

docx-chapter

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

依赖

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

输入格式

yaml

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/

工作流程

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

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

阶段二：并行 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（快速结构化搜索）

text

/unified_search <英文关键词>

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

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

bash

node ~/clawd/skills/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：

text

{
  "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": "基于来源的正文草稿"
}

阶段三：内容合成

更新 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"
合并所有子代理返回结果
⚠️ 跨 agent URL 去重（强制硬步骤，不可依赖 LLM 自觉）：
bash
```
python3 scripts/dedup_sources.py <research_dir>
```
脚本自动完成：
- 检测 research_results.json 中所有重复 URL
- 保留脚注号最小的版本，删掉冗余条目
- 重新连续编号所有来源
- 重映射 chapter.md 中所有 [^N] 引用
- 删除 chapter.md 中同一脚注号的重复定义
- 同步更新 verification_keywords.json
- 输出 dedup_report.json 记录去重详情
必须在生成 chapter.md 正文之前执行此步骤。
生成 MD 正文：每处数据/观点标注脚注引用 [^N]（每个来源只有一个脚注号，全文统一使用该号引用）
脚注格式：[^N]: 作者/机构。《标题》。发布日期。URL
脚注从 0 起连续编号
同步输出 verification_keywords.json：每写入一处 [^N] 时，顺带记录：
- footnote_id：N
- source_url：对应的来源 URL
- keywords：该处引用的核心术语/数据（2-5 个英文词/短语，如 ["defect reduction", "85%", "alpha testing"]）
- 格式：{ "footnotes": [ { "id": "0", "url": "...", "keywords": [...] }, ... ] }
- 原则：写脚注的人最清楚自己在引用什么，关键词当场定下来。
输出草稿 → 人工审阅（必须，不可跳过）

事后 Claim-Driven 关键词生成

当 verification_keywords.json 未在阶段三同步产出（或关键词来自 research quote 而非声明），可使用 keyword_generator.py 基于声明（claim）反向生成关键词：

bash

python3 scripts/keyword_generator.py chapter.json research_results.json verification_keywords.json

原理：遍历 chapter.json 中每个 [^N] 脚注，提取其所在句作为中文声明（claim），在 research_results.json 中查找该脚注对应的英文研究原文，调用 claim_keyword_extractor.py（LLM）将中文声明翻译为英文关键词。

关键差异：

旧方式：从 research quote 中提取高频英文短语（可能不反映声明中的断言）
新方式：从中文声明出发，反向翻译为英文关键词，确保截图验证高亮的是"声明中实际断言的内容"

示例（fn#2 "CLSC 的关键特征包括：产品可回收性设计优先…"）：

旧方式输出："Jones Elite Logistics The", "Closed Loop Supply Chain", "includes product design"
新方式输出："closed-loop supply chain", "recyclable product design", "forward reverse logistics", "full lifecycle value", "re-use and recycling"

原则：同一套关键词既驱动内容写作，也驱动截图验证——声明驱动，追溯闭环。

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

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

扫描正则（Python）：

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')'
)

检测流程：

bash

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

处理规则：

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

常见坑：

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

阶段四：DOCX 生成

bash

{{- 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：

bash

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。

后处理原理：

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

阶段五：来源验证（Two-Pass 架构）

借鉴 citation-check v2 的 Two-Pass Architecture、Status Decision Tree、Numerical Precision Rules、Mandatory Search Templates。 Pass 1 提取声明 → 直接进入 Pass 2 验证（无需人工闸门）。

阶段 5A — Pass 1：声明提取

从 chapter.md 提取所有可验证的事实声明。使用 scripts/extract_claims.py：

bash

python3 scripts/extract_claims.py chapter.md claims_pass1.json

提取规则（8 类声明，对齐 citation-check v2）：

类型	模式	示例
Statistic	含数字+单位的断言	"准确率达 92.3%", "$4.7B 市场"
Comparative	X 比 Y 更/快/高/大	"比基线快 3 倍"
Temporal	时间限定断言	"2024 年采用率达到…"
Attribution	引用来源的声明	"据 WHO…", "Smith 等发现…"
Causal	因果关系	"这使延迟降低了 40%"
Existence	断言存在/为真	"有 500M 用户"
Ranking	排名/排他声明	"最大", "首次", "前 3"
Quote	直接引用	引号内归因文本

排除（不提取）：定义、明确标注的观点、假设、问题、无法来源的未来预测、方法论描述、致谢。

脚本输出 claims_pass1.json，包含每条声明的 claim_id、text、claim_type、footnote_ids。

阶段 5B — Pass 2：内容级验证

对 Pass 1 输出的每条声明，使用以下决策树逐条验证。

核心工具：/unified_search（三引擎搜索）执行 Mandatory Search Templates。

Status Decision Tree（逐条应用）

text

START
│
├─ 是否为 Attribution 类型（引用论文/报告/来源）？
│   ├─ YES → 进入 CITATION VALIDATION
│   └─ NO  → 进入 STATISTIC/FACT VALIDATION
│
│
CITATION VALIDATION
│
├─ Step 1: 引用来源是否存在？
│   │   运行 Academic Search Templates（见 references/search_templates.md）
│   │
│   ├─ NO  → Status: "Citation Not Found"
│   │         Issue: "无法在任何数据库中定位 [引用]"
│   │         STOP
│   │
│   └─ YES → Step 2: 来源是否讨论声明所述主题？
│             │
│             ├─ NO  → Status: "Misquoted"
│             │         Issue: "来源存在但不讨论 [主题]"
│             │         STOP
│             │
│             └─ YES → Step 3: 来源是否支持原句？
│                       │
│                       ├─ YES (exact match)    → Verified (exact)
│                       ├─ YES (paraphrase)      → Verified (paraphrase)
│                       ├─ PARTIALLY (缺上下文)   → Misleading
│                       └─ NO (矛盾)              → Hallucination
│
│
STATISTIC/FACT VALIDATION
│
├─ Step 1: 能否找到权威来源？
│   │   按声明类型运行对应 Search Templates
│   │
│   ├─ NO  → Status: "Unverified"
│   │         Issue: "未找到权威来源"
│   │         STOP
│   │
│   └─ YES → Step 2: 数值是否精确匹配？
│             │
│             ├─ YES → Verified (exact)
│             │         STOP
│             │
│             └─ NO  → 进入 NUMERICAL ERROR DETAILS
│
│
NUMERICAL ERROR DETAILS
│
├─ 记录：来源值 / 声明值 / 偏差 / 来源位置
├─ 分类规则：
│   • 任何四舍五入    → Numerical Error
│   • 任何截断        → Numerical Error
│   • 有效位数不匹配  → Numerical Error
│   • 单位不匹配      → Numerical Error
│   • 方向反转        → Hallucination
│   • 数量级错误      → Hallucination
└─ 例外：来源自身提供近似值时（如 "96.555% (约 97%)"）→ Verified

数值精度规则（学术标准）

规则	来源	声明	状态
精确匹配	96.555%	96.555%	✓ Verified
任何四舍五入	96.555%	97%	✗ Numerical Error
截断	96.555%	96.5%	✗ Numerical Error
有效位不匹配	0.834	0.83	✗ Numerical Error
单位不匹配	96.555%	0.96555	✗ Numerical Error
方向反转	+12% growth	+15% growth	✗ Hallucination
数量级错误	$4.7B	$47B	✗ Hallucination

来源权威度分级

Rank	来源类型	示例
1	Primary source	原始研究、官方报告、原始数据
2	Government / Institutional	WHO, CDC, World Bank, 国家统计局
3	Peer-reviewed	Nature, Science, IEEE, ACM
4	Industry reports (named)	Gartner, McKinsey, Statista
5	Reputable news citing primary	NYT, Reuters 引用原始来源
6	Secondary compilations	Wikipedia（需核实其来源）

规则：仅 Rank 5-6 来源 → Status = "Unverified" + 标注 "仅找到二级来源"。

Confidence 分类

Level	标准	使用场景
exact	≥95% 词重叠或同数字同单位	直接引用、精确统计
paraphrase	同事实，不同措辞，未加解读	重述发现
interpretation	从来源数据推断	从来源计算、综合得出

不确定时使用更保守的级别并标记审核。

多源交叉验证

条件	所需来源
找到 Primary source	1 个（若权威：.gov, peer-reviewed, 官方）
仅有二级来源	≥2 个独立来源一致
来源冲突	Status = "Unverified"，标注冲突

Tie-Breaker Rules（边缘情况）

情况	规则
声明缺日期	假定指最近可用年份；标记 "需补充日期"
来源冲突	使用最新权威来源；引用双方；标注冲突
所有搜索模板跑完未找到	Status = "Unverified"（不是 Hallucination）
数字因币种/单位转换不同	标记 "需澄清：币种/单位"
同一机构多份报告	使用最新；标注日期
声明使用 "约""大约" 等	仍验证基数在来源 ±10% 范围内
来源 paywalled	标注 "来源有付费墙，无法验证精确文本"
来源为其他语言	翻译后验证；标注翻译

结构性检查（继承原阶段五）

保留 verify_docx.py 的 DOCX 结构检查，合并进统一报告：

bash

python3 verify_docx.py chapter.docx

检查项：URL 重复（坑 #4）、URL 无 hyperlink（补漏）、footnoteRef 缺失（坑 #6）、字体污染（坑 #7）、hyperlink 无样式、脚注编号缺口。

搜索模板

详见 references/search_templates.md。按声明类型分 5 组：Academic / Statistics / Company / Health / Government。

Pass 2 优先复用 Phase 2 的 research_results.json 中的搜索结果作为缓存（标注 source: phase2_cache），未覆盖的独立执行搜索。

Pass 2 输出

合并为统一验证报告 chapter_verification.json（Schema 见 references/claim_verification_schema.json）：

json

{
  "metadata": { ... },
  "pass1_extraction": { ... },
  "pass2_verification": {
    "summary": { "verified": N, "numerical_errors": N, "hallucinations": N, ... },
    "verified": [...],
    "numerical_errors": [...],
    "hallucinations": [...],
    "unverified": [...],
    "misleading": [...],
    "structural_issues": [...]
  },
  "sources_consulted": [...]
}

阶段六：截图标注验证

Phase 6 触发前必须经用户确认（见 6A）。用户批准后方可执行截图。

阶段 6A — 用户确认闸门（强制）

在截图开始前，输出以下信息并要求用户批准：

text

即将对 N 个来源进行截图验证：
  - 可达 URL: X 个
  - PDF（跳过）: Y 个
  - 不可达（跳过）: Z 个
  - 骨架网站（跳过）: W 个

每个截图将使用 Playwright 紫色高亮关键词标注。
预计耗时约 X 分钟。

请批准：回复 "批准截图" 继续 / "跳过截图" 跳过此阶段

未收到用户批准前，绝对不执行任何截图操作。

阶段 6B — 截图执行

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

bash

# 单 URL 截图（Claim-Driven 推荐）
python3 scripts/purple_highlight_screenshot.py --smart --keywords-file verification_keywords.json <URL> <output.png>

# 单 URL 截图（手动指定关键词）
python3 scripts/purple_highlight_screenshot.py --smart <URL> <output.png> <keyword1> [keyword2] ...

# 批量截图（Claim-Driven 推荐）
python3 scripts/screenshot_verify.py <chapter.json> <output_dir> \
  --research research_results.json \
  --url-status url_status.json \
  --keywords-file verification_keywords.json

--smart 模式：自动提取页面文本，用 LLM 匹配关键词（处理同义改写）。

--keywords-file：从 verification_keywords.json（由 keyword_generator.py 或阶段三生成）中读取 Claim-Driven 关键词。传递后，截图脚本使用声明驱动的英文关键词定位页面位置并高亮，而非从 research quote 中提取关键词。

关键词来源（优先级）：

--keywords-file 传入的 Claim-Driven 关键词（推荐）
verification_keywords.json（阶段三或 keyword_generator.py 产出）
chapter.md 上下文中脚注所在句的关键词
research_results.json 中的 excerpt

特殊来源处理：

PDF 来源 → 跳过截图，标注 reason: PDF
图片骨架网站 → curl -s <URL> 检查 HTML < 2000 chars → 跳过
不可达 URL（4xx/超时）→ 跳过，标注 reason: unreachable

阶段 6C — 截图质量与声明对齐

每张截图分级（Grade）：

Grade	标准	含义
A	`highlighted_count > 0` AND body 含相关正文	高亮有效，可验证
B	页面加载正常但 `highlighted_count == 0`	关键词不在页面或同义改写未匹配
C	页面加载但 body text < 100 chars	骨架页/反爬/JS 渲染失败
F	截图失败（网络/超时/Roxy 额度不足）	截图不可用
N/A	跳过（PDF/不可达/骨架网站）	非截图问题

声明对齐：对 Grade A/B 的截图，提取页面中可见的数值/关键短语，与 Pass 1 对应声明做值级对比：

text

截图 fn03 → 声明 C004 "准确率 92.1%"
  页面可见文本："92.1% accuracy" → exact match ✓
  判定：Verified

阶段六输出

截图的 summary.json 合并到统一验证报告 chapter_verification.json 的 phase6_screenshots 字段中（同 Schema）。

正文措辞审核规则

以下规则已纳入阶段五的 Pass 1 声明提取规则。声明提取时会自动标记以下类型的声明确保严格验证。

措辞类型	示例	Pass 1 检查	Claim Type
排他性声明	"列为重点""核心行动""首次提出"	提取为 Ranking / Attribution	来源原文必须逐字匹配
框架性声明	"纳入…框架""建立…机制"	提取为 Attribution / Existence	需查看官方文件原文
量化断言	"占比 X%""排名第 N"	提取为 Statistic / Ranking	来源直接引用，适用数值精度规则
时间关联	"自 X 年起""Y 年 Z 月至"	提取为 Temporal	日期需与 HTTP Last-Modified 一致

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

DOCX 修改规范

修改已有 DOCX 正文前：

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

搜索注意事项

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

错误处理矩阵

严重度	定义	处理策略	示例
FATAL	管线无法继续	中断执行，报告用户	大纲解析失败、Pandoc 未安装
ERROR	某阶段失败但管线可降级	降级走 `/unified_search`（非 llm-task），跳过后继不阻塞	ACP 返回空/失败、URL 不可达、Tavily Research 超时/失败
WARN	非阻塞异常	记录到报告，不中断	某个脚注缺 footnoteRef、字体异常
INFO	信息性提示	仅日志	使用了默认 reference.docx

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

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

正确链路：

text

@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

关键约束：

不要调 get_connection_info 拿 WS URL — 它返回所有已打开浏览器，regex 可能选错 → playwright-mcp 启动崩溃
MCP stdio 交互用 Node.js 实现 — Python stdout 有缓冲，bufsize=0 不生效
openapi MCP 进程保持存活 — 关闭会导致浏览器被清理，CDP WS 失效
优先复用已有浏览器 — 窗口额度有限，用完截图 close + delete
截图输出路径：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 不自动编号

已知陷阱与规避

坑	描述	规避方法
#50597	ACP 空返回（~30%）	自动重试 2 次 → 降级 `/unified_search`
llm-task 幻觉	llm-task 直接搜索会编造 URL（404）	禁止 llm-task 降级，必须走 `/unified_search`
URL 重复	同一 URL 在 `<w:t>` 和 `<w:hyperlink>` 各一份	`verify_docx.py` 自动检测
footnoteRef 缺失	ACP 修改后丢失 `<w:footnoteRef>`	`verify_docx.py` 检查
字体污染	ACP 引入显式字体声明	`verify_docx.py` 检查 BANNED_FONTS
URL 不可点击	Pandoc 输出纯文本 URL	`add_hyperlink_footnotes.py` 后处理
footnote_gap	Pandoc 重复引用同一脚注时，后续出现复制到不同连续 ID，中间 ID 被跳过（如 16→18、28→30）	非阻塞 warning；由 `verify_docx.py` 报告，不影响脚注功能。原因：Markdown 中同一 `[^N]` 被多次引用时 Pandoc 会占用新 ID
超链接无样式	URL 可点击但无蓝色下划线（缺 `rStyle="Hyperlink"`）	`add_hyperlink_footnotes.py` 已自动添加；`verify_docx.py` 检查 `hyperlink_no_style`
Roxy CDP WS 取错	`get_connection_info` 返回所有浏览器，regex 可能匹配错误的 WS URL → playwright-mcp init timeout + EPIPE	从 `open_browsers` 响应中按 dirId 精确提取 CDP WebSocket URL
Roxy 窗口额度不足	创建新浏览器报「窗口额度不足」	优先复用已有浏览器；截图后 close + delete 释放额度
MCP stdio Python 缓冲	Python `subprocess.Popen` stdout 在 `text=True` 下有缓冲 → MCP 响应延迟 → 脚本卡死	用 Node.js `child_process.spawn` + `stdout.on('data')` 逐行解析 JSON-RPC

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

Checkpoint 持久化

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

阶段	产物	保存路径
阶段一	主题拆分 JSON	`output_dir/topics.json`
阶段二	研究结果 JSON	`output_dir/research_results.json`
阶段三	正文草稿 MD	`output_dir/chapter.md`
阶段三	验证关键词 JSON	`output_dir/verification_keywords.json`

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

输出

chapter.md — 正文 + 脚注
chapter.docx — 样式化的 DOCX（含 reference.docx 样式）
chapter_verification.json — 验证结果（Phase 6）
verification_keywords.json — 脚注 → 关键词映射（可由阶段三同步产出，或事后通过 keyword_generator.py 生成）
scripts/keyword_generator.py — Claim-Driven 关键词生成编排器
scripts/claim_keyword_extractor.py — LLM 驱动的声明→英文关键词翻译器
screenshots/ — 来源截图（Playwright 紫色高亮）

Docx Chapter Clean

Install

docx-chapter

依赖

输入格式

工作流程

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

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

阶段三：内容合成

事后 Claim-Driven 关键词生成

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

阶段四：DOCX 生成

阶段五：来源验证（Two-Pass 架构）

阶段 5A — Pass 1：声明提取

阶段 5B — Pass 2：内容级验证

Status Decision Tree（逐条应用）

数值精度规则（学术标准）

来源权威度分级

Confidence 分类

多源交叉验证

Tie-Breaker Rules（边缘情况）

结构性检查（继承原阶段五）

搜索模板

Pass 2 输出

阶段六：截图标注验证

阶段 6A — 用户确认闸门（强制）

阶段 6B — 截图执行

阶段 6C — 截图质量与声明对齐

阶段六输出

正文措辞审核规则

DOCX 修改规范

搜索注意事项

错误处理矩阵

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

规则优先级

脚注格式规范

已知陷阱与规避

Checkpoint 持久化

输出

致谢 / Acknowledgments

Related skills