paper2blog

バイリンガル論文編集

目的

学術論文の資料から、編集チーム向けの編集パッケージを作成します。デフォルトでは、パッケージには必須の成果物が 2 点 含まれ、どちらも .docx 形式です。

• <blog_outdir>/blog_zh.docx — 中国語のWeChat公式アカウント記事。
• <blog_outdir>/blog_en.docx — 英語の研究ブログ記事。

どちらも、強固な内容構成、図と本文の連携、キャプション、出典リンクを備えています。共通のエビデンスマップと、抽出・切り抜き済みの図を 1 セット 使用します。論文の分析と図の準備は一度だけ行い、記事は言語ごとに一度ずつ、合計 2 回執筆します。paper2assets パッケージがある場合は、共有する信頼できる情報源として使用し、ブログ、ポスター、スライド、動画で、同じセクションの主張、図、数値、ナレーション原稿が一致するようにします。編集者が記事を再レイアウトする場合があるため、見た目の仕上がりは二次的な要素です。

2 つのバージョンは、互いをそのまま翻訳したものではありません。同じ事実、図、数値、主張を伝えますが、それぞれの読者に合わせた語り口にします。_zh 版は落ち着いたWeChat公式アカウントの文体、_en 版は中立的な欧米の研究ブログの文体にします（references/editorial-style.md を参照）。一文ずつ訳すのではなく、それぞれの言語で自然に執筆してください。

想定する読者は、技術への関心はあるものの、論文の専門分野に詳しいとは限りません。学術的な正確さを保ちながら、研究の貢献が理解しやすく、読みたくなるようにしてください。

自律的に作業してください。論文を読み、編集上の判断は自分で行い、完成した草稿を 2 本作成してください。切り口、構成、図、キャプション、タイトルについて、ユーザーに確認を求めて作業を止めないでください。推測してはいけないのは、確認可能な確定事実（論文やコードのリンク、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" が含まれている場合は、存在すれば確認の目安になります。同じバンドルに書き込むことで、2 つの .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 から作業を始め、共有パッケージがまだ存在しない場合は、Output Contract に従って解決した $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 の場合は、図を手作業で収集せず、同梱の抽出ツールを実行します。このツールは、ページ上の各図の位置を特定し、複数パネルのサブ図を1つの画像にまとめ、論文のキャプション本文が画像の下部に残らないよう切り取るという、手間がかかりミスの起きやすい作業を、目視やページ領域の手動スクリーンショットよりもはるかに確実に実行します。

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

     このレガシー抽出コマンドは、paper2assets を利用できない場合のフォールバックとしてのみ使用してください。新しいスキル横断ワークフローでは、まず paper2assets を初期化してください。$BLOG_OUT は、上記の Output Contract に従って解決した値です。後で blog_zh.docx／blog_en.docx も格納する同じバンドルルートです。 outdir はこの記事用の作業フォルダーです（例：PDF の名前を付けたフォルダー）。次のものが生成されます：

     • assets/meta/text.txt — 論文の全文（レイアウトを保持し、ページ区切りも維持）
     • assets/figures/ — 図ごとに、余計な要素を取り除いた PNG ファイル 1 点
     • 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. 執筆前に記事の構成を計画します：

   • 読者の関心を引く導入や比喩を 1 つ選びます。
   • セクションの順序と図の順序を合わせて決めます。
   • 採用する価値のある図を 3～7 点選びます（references/image-guidelines.md を参照）。assets/meta/figures.json に記載されたファイル名を控えます。
   • 各図は、読者が理解するための説明を行った段落の直後に配置します。
   • 表を使うのは、簡潔な数値比較やベンチマークの要約に限ります。

6. 選んだ図を準備します（切り抜きの確認）：

   • 抽出ツールはヒューリスティックな手法を用いており、通常はきれいに切り抜けますが、多少の不具合が残ることがあります。切り抜きの失敗は、完成した記事で最も目立つ欠点の 1 つです。たとえば、図が余白の中にぽつんと置かれていたり、図に論文の英語の生の「Figure N: …」というキャプションが焼き込まれていて、そのすぐ下に中国語のキャプションを載せたりする状態です。そのため、実際に選んだ図を 1 点ずつ確認し（figures/ フォルダー全体ではありません。使わない図は読者の目に触れません）、同梱の scripts/crop_figure.py できれいにします。
   • 選んだ図ごとに、安全な自動処理を 2 段階で実行します。まず decaption で焼き込みキャプションの断片を除去し、次に autotrim で余分な余白を取り除きます。その後、目視で確認し、隣接要素の映り込みや太いキャプション帯があれば、明示的な box 切り抜きで修正します。
   • 切り抜き確認の全手順、注意すべき 4 つの不具合、正確なコマンドについては、references/image-guidelines.md を読んでください。ここは省略しないでください。図の品質を左右する最大の要因です。

7. 2言語版の草稿を作成します。

   • 共通のエビデンスマップ（ステップ3）と共通の図表（ステップ5～6）に基づいて執筆します。両バージョンで構成、図表、数値、主張を統一してください。変えるのは文体であり、事実ではありません。
   • _zh（中国語のWeChat向け）： 本文は中国語で記述し、必要な英語の用語、論文名、手法名、ベンチマーク、データセット、モデル名はそのまま残します。必要に応じて、技術用語は初出時に英語と中国語の説明を併記します。
   • _en（英語の研究ブログ向け）： 欧米の技術読者に向けた、流暢で自然な英語で執筆します。中国語の逐語訳にはしません。リズムや言い回しは変えて構いませんが、内容は一致させてください。
   • 自律的に作業してください。 導入、構成、図の選択、キャプション、タイトル、貢献の表現など、編集上の判断は自分で行い、完成した草稿を1本ずつ仕上げてください。ユーザーに確認を求めて作業を止めないでください。変更が必要な箇所はユーザーが編集します。
   • 両言語とも、宣伝調の表現ではなく、明快で抑制の効いた、公開可能な文章を優先してください。主張や結果を捏造したり、確認可能な確定情報（論文リンク、コードリンク、DOI、著者の所属、採択状況など）を作り上げたりしないでください。誤った情報はそのまま編集工程に持ち込まれます。情報が入力にない場合は、推測で具体的な値を補ったり、「確認中」のプレースホルダーを残したりせず、自然に省略してください。編集上の判断はすべて自分で行ってください。
   • 言語ごとの文体については、references/editorial-style.md を参照してください。中国語のWeChat向け文体と、英語の研究ブログ向け文体が記載されています。

8. 2つの .docx ファイルを作成します。

   • 出力先とファイル名： 最終成果物を $BLOG_OUT/blog_zh.docx と $BLOG_OUT/blog_en.docx に保存し、アウトライン、切り抜いた図、プレビュー、レポートは $BLOG_ASSETS / $BLOG_META の下に保存してください。ファイル名は論文のタイトルやファイル名に関係なく固定です。中国語のタイトルは _zh ドキュメント内に記載し、ファイル名には含めないでください。
   • レイアウトはシンプルで編集しやすいものにしてください。タイトル、サブタイトル、本文段落、見出し、挿入図、キャプション、任意の結果表、出典リンクを含めます。
   • 2つのファイル名は、最初からASCII文字のみの blog_zh.docx / blog_en.docx です。関連するアセットのファイル名（JSONアウトライン、抽出した図など）もASCII文字のみを使用してください。下流のCMSやzip・アップロードツールで非ASCII文字のファイル名が文字化けする理由については、references/output-contract.md を参照してください。
   • どちらのドキュメントにも、assets/figures/ の同じ切り抜き図を埋め込んでください。安定した画像パスを使用し、画像をリンクではなく各ドキュメントに埋め込みます。各図には、そのドキュメントの言語でキャプションを付けてください。
   • Pythonを使用していて python-docx が利用可能な場合は、scripts/build_wechat_docx.py を使い、JSONアウトラインから各ドキュメントを組み立てられます。言語ごとにアウトラインと出力先を指定して、それぞれ1回実行してください。中国語ドキュメントには --lang zh、英語ドキュメントには --lang en を指定すると、各言語に適したフォントが設定されます（_zh は中国語に微软雅黑 / Microsoft YaHei、ラテン文字にArial、_en はラテン文字にArial）。--lang を省略した場合、スクリプトは blog_zh.docx / blog_en.docx という出力ファイル名から言語を推定します。編集者が特定のフォントを必要とする場合は、アウトラインの "fonts" オブジェクトを設定するか、--latin-font / --east-asia-font を指定してください。これらの上書き設定は記事の内容には影響しません。
   • プラットフォーム固有のドキュメントツールが利用可能な場合は使用して構いません。ただし、最終成果物は必ず2つの .docx ファイルにしてください。

9. 確認と修正を行います。

   • references/review-checklist.md のチェックリストを実行してください。

   • 納品前に、次の機械QAゲートを実行してください。

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

     ゲートは、両方の .docx ファイルが存在し、同じ図のセットを埋め込み、 想定されたフォントを宣言し、TODO プレースホルダーを避け、バイリンガルの 数値・用語が一致していることをチェックします。また、ページネーションの リスクも探します。画像前の大きな空白領域、内容が不足した画像、および 孤立しそうな末尾です。

   • strict モードでは、チェッカーは 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>
     

     strict での最終納品では、プレビューチェックを黙ってスキップしては いけません。

   • <blog_outdir>/manifest.json を、両方の DOCX ファイル、assets/figures/、 アウトライン、QA レポートのルート相対パスとともに書き出します。 "layout": "v2-assets" を含めます。QA ゲートが ERROR を報告した場合は、 ユーザーが名前付きの縮退パスを明示的に承認しない限り、停止してブログ パッケージを修正します。

   • ユーザーに選択肢を提示したり、どの方向に進むかを尋ねたりするために 止まるのではなく、強力で完全なドラフトを 1 つ納品します。つまり、判断し、 ドラフトを作成し、完成した .docx ファイルを引き渡します。ユーザーは 質問のリストからではなく、実際の成果物からイテレーションします。

   • ユーザーが個人的な好みで編集する場合、事実上または論理上の問題を 持ち込まない限り、その好みを尊重します。

デフォルトの記事構成

ユーザーの例が別の構成を示唆しない限り、各言語版の開始構造として これを使用します。両方のバージョンはこの構成と同じ図を共有し、異なるのは 言語と語り口だけです。

1. タイトルとサブタイトル。
2. 2 ～ 3 のリード段落:
   • 人々が通常考えたり行ったりすること、
   • 論文の問いが今なぜ重要か、
   • 論文の主要なアイデア。
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 ごとに 1 回実行します（ワークフローのステップ 2）。
• crop_figure.py は、切り抜き確認ステップ（ワークフローのステップ 6）で使用する修正ツールです。書き込み前に必ず <file>.png.bak へバックアップし、figures.json の寸法も同期させます。手順の詳細とコマンドのリファレンスは references/image-guidelines.md に記載されています。
• build_wechat_docx.py は、JSON アウトライン（段落、見出し、埋め込み図、キャプション、表）から 1 つの .docx を組み立てます。--lang を指定して言語ごとに 1 回実行します。_zh アウトラインは $BLOG_FINAL/blog_zh.docx --lang zh（フォント：中国語には微软雅黑、ラテン文字には Arial）に、_en アウトラインは $BLOG_FINAL/blog_en.docx --lang en（フォント：ラテン文字のテキストには Arial）に対応し、どちらにも同じ図を埋め込みます。記事の構成はエージェントが計画する必要があります。このスクリプトは組み立てを補助するものです。
• check_blog_package.py は、最終的なバイリンガルパッケージとレンダリングされたレイアウトプレビューを検証します。納品前に --strict を付けて実行し、検証に合格するまで修正を繰り返します。
• Python パッケージの依存関係は requirements.txt に記載されています。extract_pdf.py の実行には、PATH 上に Poppler の pdftotext 実行ファイルも必要です。