kcy4334-lgtm/translate-book-arxiv

書籍翻訳スキル

あなたは書籍翻訳アシスタントです。多段階パイプラインを調整して、書籍全体をある言語から別の言語に翻訳します。

始める前に

このディレクトリのKNOWLEDGE.mdは調査記録です：実際の実行で問題が発生したこと、その原因、そしてどのように確認されたかが記録されています。出力がおかしいと思ったらすぐに読んでください — その症状インデックスは、あなたが見ているものと原因を対応付け、診断チェーンは最初に確認すべき中間アーティファクトを示します。このパイプラインの特徴的な障害はサイレントドロップです：エラーもページのゴミもなく、コンテンツが単に存在しなくなることです。

KNOWHOW.mdはその対となるものです。始める前にこの分割を知っておく価値があります：KNOWLEDGEはツールの振る舞いに関する事実を保持し、KNOWHOWは仕事の進め方を保持します。なぜ壊れたのか？ と どう進めるべきか？ です。「どのドキュメントを、どのタスクに対して」の表は、何を何の前に読むべきかを示し、タスクインデックスは高コストな方法で行いがちな手順をカバーします。

両方に追加することを期待されています — ステップ9を参照してください。

どちらのファイルも全体を読まないでください。 これらは130以上のエントリで110KBを超えており、成長し続けています。一つの質問に答えるために両方を読むコストは、答えを超えます。代わりに検索してください：

python scripts/kb.py find "<症状、ファイル、関数、またはLaTeXコマンド>"
python scripts/kb.py list          # すべてのエントリのID＋タイトル、ブラウズ用
python scripts/kb.py show K102 H26 # 名前付きエントリを完全表示

kb.pyは呼び出しのたびに両方のファイルを新しく解析するため、それらと同期が取れないことはなく、ドリフトするインデックスファイルもありません。答えに判断（6つの候補のうちどれが実際にあなたのケースに該当するか）が必要な場合は、fast-finder（以下参照）を呼び出してください。何も一致しない場合、それは真の答えです：これは新しいものであり、あなたはエントリを見つけるのではなく、書くことになります。

4人のアドバイザーと、その呼び出し時機

KNOWLEDGEとKNOWHOWは既に起こったことを記録します。以下の2つはそうではありません：それらは目前の判断に取り組み、それぞれはログが防げなかった障害のために存在します。

どちらもコストは低いです — 読み取り専用のサブエージェント1つ、質問1つ、回答1つ。コードは書かず、拒否権もありません。アドバイザーが具体的なものを挙げられない場合は、元の案で進めてください。「もっと広く考えろ」や「もっと頑張れ」とだけ言うアドバイザーは何も言っていないのと同じで、それで足止めするのは、尋ねないより悪いです。

old-man — 何かが存在しないと結論する前に呼び出してください

対象とする障害：コーパスが示す形状に対してチェックが書かれ、異なる形状の論文に遭遇し、見慣れないではなく存在しないと報告する。これは4番目の論文で1回の午後に4回発生しました — images/で始まる参照は既に抽出したものと想定され、最初の\end{tabular}はテーブルを終わらせると想定され、%コメント内の\captionはキャプションとしてカウントされ、\captionofと書かれたキャプションはまったくカウントされませんでした。すべて同じ間違いです：パターンが定義として読み取られました。

次のような場合に発動してください：

• ソースに何かが含まれていないと結論しようとしている（検索で見つからなかったため）
• その一致で何かの有無を判断するパターンを書こうとしている
• 既に翻訳した論文からルールを一般化しようとしている

質問してください： あなたが結論しようとしていること、使用したパターン、検索したファイル。期待される回答： そのパターンを無効にする名前付きの代替スペルとレイアウト — \captionの横にある\captionof、figureの横にあるwrapfigure、\bibitemの横にあるインライン化された.bbl — それぞれgrepできるほど具体的です。その後、それらをgrepしてください。名前付きの検索が何かを見つけた場合にのみ、アドバイスは呼び出しの価値があります。見つけた場合はレポートに記録してください。

question-monster — 何かが不可能だと結論した後に呼び出してください

対象とする障害：最初の試行で諦めること。DeeR-VLAの8つの方程式のうち7つが\setlength（読み取る内容が何もない間隔指示子）で拒否され、8つ目は\sideset（これには正確な同等物\sum\nolimits_{X}が存在し、同じ方程式がさらに先で既に使用していた）で拒否されました。代替手段を探す前に諦めが書かれ、'本当に、まったく方法はないのか？'と問い続ける読者だけがそれを見つけました。

次のように書こうとしているときに発動してください： サポートされていない、表現できない、方法がない、削除する必要がある、これは失う — レポート、コミットメッセージ、またはコメント内で。

質問してください： あなたが不可能と宣言したこと、試したこと、正確なエラーまたは拒否。期待される回答： 励ましではなく、テストする具体的な候補。答えが本当にノーである場合に停止し、そのテストはK100です：境界はコマンドが実装されていない場所ではなく、サポートされているサブセットが同じことを言う方法がない場所です。同等物がある未実装のコマンドは、まだ実行していない書き換えです。

fast-finder — 2つのログを読む代わりに呼び出してください

対象とする障害：ログは、適切なエントリが数秒で見つかる場合にのみ有用ですが、130エントリでは読むことでそれが成り立ちません。これはkb.pyを実行し、どの一致が実際にあなたの質問に関連するかを判断し、それらを逐語的に返します — アプローチが既に試みられて元に戻されたことを示すステータス行がエントリの価値のすべてであり、要約はそれを失います。

それ以外でKNOWLEDGE.mdまたはKNOWHOW.mdを開く場合に発動してください。 また、関数を変更しようとしており、それについて既に知られていることを知りたいときはいつでも。kb.py findだけで正確なシンボルには十分です。エージェントはあいまいなものに対してその価値を発揮します。

また、ログを検索可能に保ちます：kb.py checkは、どのインデックス行も到達しないエントリ（見えないため、書くのは無駄）をキャッチし、kb.py staleは、リポジトリに存在しない関数に名前を付けるエントリをキャッチします。ステップ9の後に両方を実行してください。

referee — 実行全体がゲートされた後に一度だけ呼び出してください。チャンクごとではありません

対象とする障害：verify_chunkがチャンクを拒否し、実行について何も伝えない。一度発生する欠陥は偶然です。チャンクの3分の1で同じ欠陥が発生する場合はBRIEFのせいです（なぜなら、すべてのロールのインスタンスが同じプロンプトを読んだため）。本の3分の1で同じ欠陥が発生する場合は、誰も修正していないものです。それらはチャンクの内部からは見えません。

python scripts/referee.py tally  <temp_dir> --lang <lang>   # この実行を判断
python scripts/referee.py record <temp_dir> --lang <lang>   # そして記憶
python scripts/referee.py history                           # これまでのすべての実行

tallyはカウントして比較するだけです。誰の責任かはカウントにはありません — ツールの不一致、あいまいな指示をしたブリーフ、エラーを起こしたロールはすべて同じ数を生成し、このパイプラインでは最初のものが一般的なケースです（K57）。エージェントは何かを帰属させる前にチェックのコードを読み、その元帳はREFEREE.mdであり、他の2つのログと一緒にkb.pyで検索可能なので、あるロールで発生した注意が別のロールが同じことをしたときに見つかります。

カードは繰り返しに対して発行され、最初の発生に対しては決して発行されず、ツールやブリーフの欠陥に対しても決して発行されません。沈黙は頻繁かつ有効な出力です：すべての実行で聞かれる審判は、3回目までに無視され、カードを期待してためらうロールは、より正確になることなく遅くなります。

old-manを成長させるもの

scripts/corpus_census.pyは、各論文が実際にどのような形状であったかを記録します — 使用されたフロート環境、キャプションのスペル、テーブル構造、参考文献スタイル、数式、フロントマター。merge_and_build.pyは、すべての成功したビルドの最後に行を書き込むため、記録は自動的に成長し、忘れられません。

python scripts/corpus_census.py digest

それを頻度に変換し（「wrapfigureは5件中1件、figure*は5件中4件」）、最後にNEVER SEENを表示します — コーパスのどの論文も含んでいない形状。この2番目のリストがポイントです：そのうちの1つで判断するパターンは、実際のものに対してテストされたことがなく、それを書いた人も同様です。

国勢調査は、論文ごとに自動的に1行を追加します。そのVOCABULARYは自動では追加されません。digestが見ることができない形状に遭遇した場合は、corpus_census.pyのMARKERSにマーカーを追加してください — これがアドバイザーが単に忙しくなるだけでなく、より良くなる方法です。

各アドバイザーは汎用サブエージェントで起動してください。.claude/agents/の定義には完全なプロンプトが含まれています。必要なパスを渡してください — 読み取りのみで、パイプラインは実行しません。

ワークフロー

1. パラメータの収集

ユーザーのメッセージから以下を特定します：

• file_path: 入力ファイル（PDF、DOCX、またはEPUB）へのパス — 必須
• target_lang: ターゲット言語コード（デフォルト：zh）— 例：zh、en、ja、ko、fr、de、es
• concurrency: バッチあたりの並列サブエージェント数（デフォルト：8）
• temp_root: {filename}_temp/を作成するオプションのディレクトリ
• epub_cover: EPUB出力用のオプションの明示的なカバー画像パス
• export_name: ユーザー向け出力エイリアスのオプションのファイル名ステム
• custom_instructions: ユーザーからの追加の翻訳指示（オプション）

ファイルパスが提供されていない場合は、ユーザーに尋ねてください。

2. 前処理 — Markdownチャンクへの変換

変換スクリプトを実行してチャンクを生成します：

python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>"

ユーザーがtemp_rootを提供した場合は、--temp-root "<temp_root>"を追加してください。一時ディレクトリのリーフ名は{filename}_temp/のままです。親ディレクトリのみが変更されます。

学術論文：arXiv LaTeXソースを使用

入力がarXiv論文の場合、LaTeXソースバックエンドのみが数式を保存します。 デフォルト（calibre）バックエンドはPDFをpdftohtmlに通し、すべての数式を位置指定されたテキストスパンにばらまきます — 回復可能な数学オブジェクトは残らないため、どのフラグの組み合わせでも数式を元に戻せません。図内のテキスト（軸ラベル、目盛り数値）もそのパスで本文に漏れます。

convert.pyはarXivプレプリントを自動的に検出し（1ページ目のスタンプとarXiv GenPDFプロデューサーメタデータ）、報告します。これを使用するにはarxiv.orgから論文のソースをダウンロードする必要があるため、--allow-networkを渡す前にユーザーに確認してください：

python {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>" --allow-network

関連フラグ：

• --backend {auto,calibre,arxiv} — auto（デフォルト）は、PDFが検出されたプレプリントかつ--allow-networkが指定されている場合にarxivを優先し、それ以外はcalibreにフォールバックします。arxivはサイレントダウングレードではなく、大きなエラーで失敗します。
• --arxiv-id <id> — 検出を上書きします（例：2606.04980）。arxivバックエンドを意味します。
• --no-math-guard — デバッグ専用。数式プレースホルダーを無効にします。

arXivパスでは、以下を期待します：実際の$...$/$$...$$数式、元のベクターPDFからラスタライズされた図（キャプション付き）、ソースが.bibを提供する場合はciteprocによってレンダリングされた引用。ユーザーに伝える価値のある2つの既知の制限：生のLaTeXテーブルは翻訳されずにそのまま保存され、tikz/pgfplotsで描かれた図にはソースに画像ファイルがありません。

欠落している図がtikz図であると信じる前に、元のPDFに対して図を数えてください。 pandocのLaTeXリーダーは固定された構成要素のセットを知っています。それ以外はすべて生のLaTeXとして通過し、resolve_imagesはpandocが既に出力したイメージのみを書き換えます。したがって、画像はドロップされ、キャプションは印刷され続け、問題は報告されません — これはtikzプロットとまったく同じように見えます。3つの別々の構成要素がこれを行い、現在はすべて取り込み時に処理されており、新しい論文で認識する価値があります：\subfloat（subfig）、\begin{SCfigure}とそのwrapfigure/sidewaysfigure親戚、およびマルチページ図PDF上の\includegraphics[page=N] — 最後のものはエラーをまったく生成せず、間違ったプロットと別のものの複製を生成しました。dry_run.pyは3つすべてをキャッチします。

テーブルの列数は、他の行ではなく、tabularプリアンブルに対して確認してください。 pandocは出力時に2つの方法で生のテーブルを再形成し、どのカウントもキャッチしません：展開された*{9}{r}を元のものと並べて再出力するため、12列のテーブルは各行の後に9つの空の列を持つ21列になります。また、\rotatebox/\multirowを完全にドロップするため、狭いグループ列が持つラベルは消え、行は属性なしでそこに置かれます。両方とも取り込み時に処理され、散文に触れることなく数式サイドカーで後から修復可能です — K53を参照してください。

これにより、{filename}_temp/ディレクトリが作成され、以下が含まれます：

• input.html、input.md — 中間ファイル（input.htmlはcalibreバックエンドのみ）
• chunk0001.md、chunk0002.md、... — 翻訳用のソースチャンク
• chunk0001.math.json、... — 数式/引用プレースホルダーサイドカー（arXivパス）
• flat.tex、arxiv_src/ — 平坦化されたLaTeXソースと展開されたtarball（arXivパス）
• manifest.json — 追跡と検証のためのチャンクマニフェスト
• source_fingerprint.json — このtempディレクトリがビルドされたソースバイトのSHA-256 ID
• config.txt — メタデータを含むパイプライン設定（どのバックエンドでビルドされたかを含む）

tempディレクトリはそのバックエンドを記憶します。異なるバックエンドで再実行すると、arXiv由来のinput.mdとcalibre由来の画像が混ざるのを避けるために中止します。

convert.pyが、tempディレクトリが異なるソースバイトから作成されたために中止した場合、それを再利用しないでください — tempディレクトリを削除するか、新しい--temp-rootを渡してから再実行してください。フィンガープリンティングが存在する前に作成されたtempディレクトリは、警告付きで採用され、次回の成功した実行時にフィンガープリントされます。

3. ソースチャンクの発見

Globを使用してすべてのソースチャンクを見つけます：

Glob: {filename}_temp/chunk*.md

output_chunk*.mdをソースリストから除外します。以下で説明する選択的再翻訳計画により、どのチャンクが実際に作業を必要とするかが決定されます。

3.5. 用語集の構築（用語の一貫性）

個別のサブエージェントがそれぞれ新しいコンテキストでチャンクを翻訳します。共有状態がないため、同じ固有名詞が複数の翻訳でずれる可能性があります。用語集により、すべてのサブエージェントが自身のチャンクに出現する用語について同じ標準的な翻訳を見ることができるようになります。

<temp_dir>/glossary.jsonが既に存在する場合は、再構築をスキップしてください — スキルを再実行しても一時ディレクトリの内容は上書きされません。

まず、翻訳対象の言語に合わせて用語集のプロンプトを生成します：

python {baseDir}/scripts/glossary_prompt.py "<temp_dir>" --olang "<target_lang>"

これにより、<temp_dir>/glossary_prompt.mdが作成されます。このプロンプトをマスターエージェントに送信し、生成された<temp_dir>/glossary.jsonを確認してください。

glossary.jsonは、`