paper2blog

双语论文编辑稿

目的

根据学术论文材料，为编辑团队制作一套编辑稿。默认包含两项必需交付物，均为 .docx：

• <blog_outdir>/blog_zh.docx — 一篇中文微信公众号文章。
• <blog_outdir>/blog_en.docx — 一篇英文研究博客文章。

两篇文章都应具备清晰的内容逻辑、图文协调、图注和来源链接。它们共用一份证据图谱和一套提取或裁剪后的图片——论文分析和图片准备只需做一次，然后分别用两种语言撰写文章。若已有 paper2assets 包，应将其作为共享的事实来源，确保博客、海报、幻灯片和视频对章节论点、图片、数字和旁白脚本的表述一致。视觉润色次于内容，因为编辑可能会重新排版文章。

两个版本并非相互对应的直译。它们报告相同的事实、图片、数字和论点，但各自采用适合目标读者的表达方式：_zh 版本采用克制的微信公众号语体；_en 版本采用中立的西方研究博客语体（参见 references/editorial-style.md）。请分别用各自的语言自然撰写，不要逐句翻译。

默认读者对技术感兴趣，但未必是论文所属细分领域的专家。在保证学术准确性的同时，让读者理解这项贡献并愿意继续阅读。

自主完成工作。阅读论文，自行做出编辑判断，并交付两份完整初稿——不要停下来让用户确认切入点、结构、图片、图注或标题。唯一不能猜测的是可核实的硬事实（论文或代码链接、DOI、单位、录用状态）：如果输入中没有，就省略，不要编造。其他事项自行决定并继续。

输出约定

遵循共享的 paper2assets v2 布局。paper2blog 包的顶层仅包含交付文件和 manifest.json；依赖项和构建产物统一放在 assets/ 容器下：

<blog_outdir>/
  blog_zh.docx
  blog_en.docx
  manifest.json
  assets/
    figures/
    meta/
      outline_zh.json
      outline_en.json
      reports/blog_qa_report.json
      previews/blog_qa_preview/

选择 <blog_outdir>（在写入任何文件之前解析）。 此包目录由所有 paper2* 技能共享——当 paper2assets、paper2blog、paper2poster 和 paper2video 指向同一根目录时，博客图片会与海报图片、共享旁白脚本及其他交付物并列，构成一个完整、自包含的包。按以下规则确定目录：

1. 若调用方明确传入 <blog_outdir> 参数，则以该参数为准——原样使用。只有未传入路径时，才使用以下默认规则。
2. 若已有 paper2assets 包 → 原样复用其文件夹作为 <blog_outdir>。标准检测标志是 <dir>/assets/meta/paper_spec.md（paper2assets 第 4 步生成的跨技能事实来源）；若存在 <dir>/manifest.json 且其中 "layout": "v2-assets"，则可作为佐证。将文件写入同一包，意味着两份 .docx 共用已有的 assets/figures/，QA 报告写入 assets/meta/reports/，下游工具读取 manifest.json 时也能看到博客交付物与其他内容并列，无需更换路径。
3. 否则（仅有一个 PDF 文件作为输入） → 默认使用 <input_pdf_dir>/<pdf_stem>/——即输入 PDF 所在目录下、以 PDF 基本文件名（不含扩展名）命名的子文件夹。例如：papers/8008_Ink3D_Sculpting.pdf → <blog_outdir> = papers/8008_Ink3D_Sculpting/。这与 paper2assets 的默认约定一致，因此若在下方工作流第 2 步调用 paper2assets，它会写入同一个包目录，无需之后更换路径。

# 1. Resolve $BLOG_OUT per the rule above
if [[ -n "$blog_outdir_arg" ]]; then
  BLOG_OUT="$blog_outdir_arg"                                  # explicit caller arg wins
elif [[ -f "$paper2assets_dir/assets/meta/paper_spec.md" ]]; then
  BLOG_OUT="$paper2assets_dir"                                 # reuse the paper2assets bundle
else
  BLOG_OUT="$(dirname "$paper_pdf")/$(basename "$paper_pdf" .pdf)"
fi

# 2. Create the assets/ scaffolding under that root
BLOG_ASSETS=$BLOG_OUT/assets
BLOG_META=$BLOG_ASSETS/meta
mkdir -p "$BLOG_ASSETS/figures" "$BLOG_META/reports" "$BLOG_META/previews"

manifest.json 记录相对于根目录的路径，并包含 "layout": "v2-assets"。 旧版 final/ / intermedia/ 输出仍可供 QA 检查器读取，以兼容旧演示；但新运行必须使用上述 v2 包结构。

加载参考资料

• 撰写文章文案前，请先阅读 references/editorial-style.md。
• 创建 .docx 前，请先阅读 references/output-contract.md。
• 选择、裁剪、编辑图片或编写图片提示词前，请先阅读 references/image-guidelines.md——其中包含图表裁剪审查流程（scripts/crop_figure.py）。
• 最终交付前，请先阅读 references/review-checklist.md。
• 只有在需要具体风格示例时，才阅读 references/case-study-acl2026.md。

工作流

1. 收集输入：

   • 论文 PDF 或源文件、标题、作者、会议或期刊、链接、代码或代码仓库链接。
   • 如有现成的 paper2assets 包，则收集其中的文件：manifest.json、assets/meta/sections.json、assets/meta/narration.json、assets/meta/figures.json、assets/meta/captions.json、assets/meta/text.txt 和 assets/figures/。
   • 当前项目中的现有示例，尤其是示例输入／输出对。
   • 论文中的图表、海报素材、README 摘要，以及用户提供的任何约束。
   • 编辑团队要求的输出格式。默认使用 .docx。

2. 从 PDF 中提取图表、文本和说明：

   • 如果工作文件夹中已有共享的 paper2assets 包，请先读取：

     • manifest.json：了解文件位置和数量。
     • assets/meta/sections.json：了解规范化主张、章节顺序、所选图表引用和可复用证据。
     • assets/meta/figures.json / assets/meta/captions.json / assets/figures/：用于选择图片和说明。
     • assets/meta/text.txt：用于核对来源，以及查阅章节文件中未包含的细节。

   • 如果从 PDF 开始，且尚无共享包，请直接在 $BLOG_OUT 中初始化该包（根据上文的输出约定解析该路径）——将 $BLOG_OUT 重用为 paper2assets 的 --outdir，可让每项 paper2* 技能都写入同一个包根目录，因此 paper2assets 生成的图表／说明／规范／旁白会与本技能稍后写入的 .docx 文件并列存放。在仓库根目录运行：

     python skills/paper2assets/scripts/build_package.py <paper.pdf> --outdir "$BLOG_OUT"
     

     在 paper_spec.md 或等效的章节规范文件创建后，同步该包：

     python skills/paper2assets/scripts/build_package.py <paper.pdf> \
       --outdir "$BLOG_OUT" \
       --skip-extract \
       --paper-spec "$BLOG_OUT/assets/meta/paper_spec.md"
     

   • 输入为论文 PDF 时，请运行随附的提取器，而不要手动收集图表。它能处理繁琐且容易出错的工作——定位页面上的每张图、将多面板子图拼成一张图片，并从底部裁掉论文自身的说明文字——比人工目测或手动截取页面区域可靠得多。

     python scripts/extract_pdf.py <paper.pdf> --outdir "$BLOG_OUT"
     

     仅当 paper2assets 不可用时，才将这个旧版提取器命令用作备用方案；新的跨技能工作流应先初始化 paper2assets。$BLOG_OUT 是根据上文的输出约定解析出的值——它也是稍后存放 blog_zh.docx / blog_en.docx 的同一个包根目录。 outdir 是这篇文章的工作文件夹（例如，以 PDF 命名的文件夹）。它会生成：

     • assets/meta/text.txt — 论文全文（保留版面，保留分页）
     • assets/figures/ — 每幅图对应一张干净的 PNG
     • assets/meta/figures.json — 清单，包含每幅图的 file、page、width、height、caption_label 和 caption
     • assets/meta/captions.json — 所有按标签索引的“Figure N: …”／“Table N: …”图注
     • assets/meta/metadata.json — 封面页元数据的尽力提取结果（venue、year、emails、code_url、paper_url、arxiv_id、doi）；字段可能为空，但绝不捏造

   • 阅读 assets/meta/figures.json，了解有哪些图以及每幅图展示的内容——图注是判断哪幅图能证明哪个观点的最快线索。

   • 如果用户提供的是单独的图像文件而不是 PDF（或除了 PDF 还提供了图像文件），你仍可直接放置这些文件；提取器用于从 PDF 中提取干净的图。

3. 构建证据图：

   • 核心问题，以及它为何在当下至关重要。
   • 论文所回应的先前工作或常见做法。
   • 主要贡献、方法和命名组件。
   • 关键实验结果，包含精确数值以及数据集和模型名称。
   • 局限性、假设，以及不得夸大的主张。
   • 可用的图及每幅图所能证明的内容（参照 assets/meta/figures.json 中的图注）。

4. 有可用示例时，先研究示例：

   • 提取文章结构、标题风格、开篇节奏、章节层次、配图密度和图注风格。
   • 将示例视为编辑风格参考，不要机械模仿其文本。
   • 如果示例输出是 .docx，检查其段落顺序和媒体数量。

5. 写作前规划文章：

   • 选择一个面向读者的切入点或类比。
   • 一并确定章节顺序和配图顺序。
   • 选出 3–7 幅值得使用的图（见 references/image-guidelines.md）；记下它们在 assets/meta/figures.json 中的文件名。
   • 将每幅图放在帮助读者理解它的段落之后。
   • 仅在进行紧凑的数值比较或基准测试摘要时使用表格。

6. 准备选定的图片（检查裁剪效果）：

   • 提取器采用启发式方法，通常能干净地完成裁剪，但仍会出现少数瑕疵；而裁剪不佳是成稿中最明显的缺陷之一——例如，图片周围留有大片空白，或论文原始英文“Figure N: …”图注被嵌入图片，而你又会在图片下方写中文图注。因此，请检查每幅实际选用的图（而不是整个 figures/ 文件夹——未使用的图不会呈现给读者），并使用随附的 scripts/crop_figure.py 进行清理。
   • 对每幅选定的图，依次运行两项安全的自动处理：先运行 decaption（去除嵌入的图注条），再运行 autotrim（去除多余的边缘空白）；然后目测检查，并用明确的 box 裁剪修复任何邻图残留或过厚的图注条。
   • 阅读 references/image-guidelines.md，了解完整的裁剪检查流程、需要留意的四种缺陷以及准确的命令。不要跳过这一步——它是提升图片质量最有效的方法。

7. 撰写两种语言版本：

   • 根据共享证据图谱（步骤 3）和共享数据（步骤 5–6）撰写——两个版本的结构、数据、数字和论断保持一致。改变的是表达方式，而不是事实。
   • **_zh（微信公众号中文稿）：**正文以中文为主；保留必要的英文术语、论文名称、方法名称、基准、数据集和模型名称。首次使用时，如有帮助，可为英文技术术语附上中文释义。
   • **_en（英文研究博客）：**面向西方技术读者，使用流畅地道的英语——不要逐句翻译中文。行文节奏和措辞可以不同，但内容必须一致。
   • **自主完成。**自行做出编辑判断——包括切入点、结构、数据图选择、图注、标题以及如何表述贡献——并交付一份完整初稿。不要停下来询问用户是否确认这些选择；他们会自行修改想调整的内容。
   • 两种语言的版本都应采用清晰、克制、达到出版水准的表达，避免营销文案风格。不要编造论断或结果，也不要捏造可核查的硬性事实——例如论文链接、代码链接、DOI、作者单位或录用状态——因为一旦出错，就会直接进入编辑流程。如果输入中缺少这类事实，就自然省略，不要猜测具体值，也不要留下“待确认”占位符。所有编辑判断都由你自行决定。
   • 阅读 references/editorial-style.md，了解每种语言的表达风格要求（其中包含微信公众号中文稿和英文研究博客的风格规范）。

8. 创建两个 .docx 文件：

   • **输出位置和文件名：**将最终交付文件写入 $BLOG_OUT/blog_zh.docx 和 $BLOG_OUT/blog_en.docx，并将大纲、裁剪后的图、预览和报告保存在 $BLOG_ASSETS / $BLOG_META 下。文件名固定，不受论文标题或文件名影响——中文标题应写在 _zh 文档中，绝不能放在文件名里。
   • 版式应简洁、便于编辑：标题、副标题、正文段落、标题、插入的图片、图注、可选结果表、来源链接。
   • 两个文件名已确保仅含 ASCII 字符（blog_zh.docx / blog_en.docx）；同目录下的资源文件名（JSON 大纲、提取的图片）也必须仅含 ASCII 字符。原因见 references/output-contract.md（下游 CMS、zip 和上传工具会破坏非 ASCII 文件名）。
   • 两份文档都嵌入来自 assets/figures/ 的同一组裁剪后图片（使用稳定的图片路径，并将图片嵌入文档，而不是链接）。每张图片都要使用对应文档语言撰写图注。
   • 如果使用 Python 且已安装 python-docx，可以通过 scripts/build_wechat_docx.py 根据 JSON 大纲组装每份文档——每种语言各运行一次，并指定各自的大纲和输出路径。中文文档传入 --lang zh，英文文档传入 --lang en，以便应用正确字体（_zh → 中文使用微软雅黑 / Microsoft YaHei，拉丁文字使用 Arial；_en → 拉丁文字使用 Arial）。如果省略 --lang，脚本会根据 blog_zh.docx / blog_en.docx 输出文件名推断语言。如果编辑器要求特定字体，可设置大纲级 "fonts" 对象，或传入 --latin-font / --east-asia-font；这些覆盖设置不会改变文章内容。
   • 如果有适用于当前平台的文档工具，请使用，但最终仍须提供两个 .docx 文件。

9. 审阅并迭代：

   • 按照 references/review-checklist.md 中的清单进行检查。

   • 交付前运行机器 QA 门禁：

     python skills/paper2blog/scripts/check_blog_package.py "$BLOG_OUT" --strict
     

     该检查会确认两个 .docx 文件都存在、嵌入相同的一组图片、声明了预期字体、没有 TODO 占位符，并确保双语版本中的数字和术语一致。它还会检查分页风险：图片前的大块空白、图片填充不足，以及可能孤立的末尾内容。

   • 在严格模式下，检查器会尝试使用 LibreOffice 和 PyMuPDF 将两个 DOCX 文件渲染为 PDF/PNG 预览，然后执行页面级布局检查，检查非末页底部空白、近乎空白的页面和内容稀疏的页面。如果机器无法直接渲染 DOCX，请使用可用的文档工具渲染页面，并传入：

     python skills/paper2blog/scripts/check_blog_package.py "$BLOG_OUT" \
       --strict \
       --zh-preview-dir <rendered_cn_page_pngs> \
       --en-preview-dir <rendered_en_page_pngs>
     

     严格交付时不得悄悄跳过预览检查。

   • 编写 <blog_outdir>/manifest.json，为两个 DOCX 文件、assets/figures/、大纲和 QA 报告提供相对于根目录的路径。包含 "layout": "v2-assets"。如果 QA 检查报告任何 ERROR，请停止并修复博客包，除非用户明确批准了某个指定的降级方案。

   • 交付一份完整、出色的初稿，而不是停下来让用户选择方案或询问方向——自行判断、起草并提交完成的 .docx 文件。让用户基于实际成品迭代，而不是对着一串问题作答。

   • 如果用户为个人偏好修改内容，请保留这些偏好，除非它们造成事实或逻辑问题。

默认文章结构

除非用户提供的示例表明应采用其他结构，否则每个语言版本都以此结构为起点。两个版本采用相同的结构和图片，仅语言和语气不同。

1. 标题和副标题。
2. 两到三段导语：
   • 人们通常怎么想或怎么做，
   • 为什么论文提出的问题在当下很重要，
   • 论文的核心观点。
3. 首张概览图及其说明文字。
4. 来源链接：论文和代码（如有）。
5. 背景／问题部分。
6. 方法或贡献部分，通常拆分为几个命名组件。
7. 以图片为主的证据章节。
8. 仅在有助于快速浏览时添加简洁的结果表格。
9. 总结部分，说明实际意义和局限性。

质量标准

优质成品应达到这样的水平：编辑只需稍作文字润色，就能将其送入制作流程。_zh 和 _en 两个版本都应易于理解、忠实于技术内容，并且在专业排版前也便于浏览；两者必须在所有数字、论断和图片上保持一致。

切勿用格式上的精致来弥补内容薄弱。段落逻辑、图片说明和论断准确性才是最重要的。

工具

scripts/
├── extract_pdf.py        ← CLI: paper.pdf → text.txt + figures/ + figures.json + captions.json + metadata.json
├── crop_figure.py        ← CLI: clean a selected figure PNG (inspect / decaption / autotrim / box)
├── build_wechat_docx.py  ← CLI: JSON outline → editor-friendly .docx
└── check_blog_package.py ← CLI: hard QA gate for bilingual DOCX deliverables

• extract_pdf.py 以图注为锚点：它会根据图注查找每个图，拼接多面板子图，并裁掉裁剪区域底部的图注文本。每篇论文 PDF 运行一次（工作流步骤 2）。
• crop_figure.py 是用于裁剪检查步骤的修正工具（工作流步骤 6）。写入前，它总会先备份为 <file>.png.bak，并确保 figures.json 中的尺寸保持同步。完整流程和命令参考见 references/image-guidelines.md。
• build_wechat_docx.py 根据 JSON 大纲（段落、标题、嵌入的图片、图注、表格）生成一个 .docx。每种语言都要用 --lang 运行一次——_zh 大纲 → $BLOG_FINAL/blog_zh.docx --lang zh（中文字体：微软雅黑，拉丁文字体：Arial），_en 大纲 → $BLOG_FINAL/blog_en.docx --lang en（拉丁文字体：Arial），两者嵌入相同的图片。文章逻辑必须由 Agent 规划；该脚本仅用于辅助组装。
• check_blog_package.py 用于验证最终的双语包及渲染后的版面预览。交付前使用 --strict 运行，并反复迭代直至通过。
• Python 包依赖列于 requirements.txt；extract_pdf.py 还需要 PATH 中包含 Poppler 的 pdftotext 可执行文件。