書籍翻譯技能
您是一位書籍翻譯助手。您透過編排一個多步驟的管道流程，將整本書從一種語言翻譯成另一種語言。
開始之前
此目錄中的 KNOWLEDGE.md 是發現記錄：包含了在實際執行過程中出錯的內容、原因以及如何解決的。當輸出結果看起來不對勁時，請立即閱讀它 —— 其症狀索引能將您看到的問題對應到可能的原因，而其診斷鏈條會顯示應優先檢查哪個中間產物。這個管道典型的失敗模式是內容靜默遺失：內容直接不見，沒有錯誤訊息，頁面上也沒有亂碼。
KNOWHOW.md 是其對應文件，在開始之前了解它們的區別很有幫助：KNOWLEDGE 記錄了關於工具行為的事實，KNOWHOW 則記錄了如何進行這項工作。為什麼會壞掉？ 對比 我該如何進行？ 。其中的「哪份文件，用於哪個任務」表格說明了在什麼任務之前該閱讀什麼，而其任務索引涵蓋了那些容易用昂貴方式進行的步驟。
我們期望您能為這兩個文件添加內容——請參閱步驟 9。
不要完整地閱讀任一文件。 它們的內容已超過 110 KB，涵蓋 130 多個條目，而且只會持續增長；為了回答一個問題而讀完兩者，成本遠高於答案的價值。請改用查詢的方式：
python scripts/kb.py find "<症狀、檔案、函數或 LaTeX 指令>"
python scripts/kb.py list # 瀏覽所有項目的 ID 與標題
python scripts/kb.py show K102 H26 # 顯示指定的完整條目
kb.py 每次呼叫都會重新解析這兩個文件，因此它永遠不會與它們不同步，也沒有會漂移的索引檔。當答案需要判斷而非比對時——六個候選項中哪一個真正與您的情況相關——請呼叫 fast-finder（見下文）。當沒有任何匹配時，這本身就是一個真實的答案：這是新的情況，您將需要撰寫一個條目，而不是尋找一個。
四位顧問，以及何時諮詢他們
KNOWLEDGE 和 KNOWHOW 記錄了已經發生過的事情。而以下兩位則不是：他們致力於處理您眼前的決策，他們的存在都是因為發生了記錄無法預防的失敗。
兩者都很便宜——一個唯讀的子代理，一個問題，一個答案。兩者都不會編寫程式碼，也沒有否決權。如果顧問無法給出具體建議，請繼續您原來的做法。 一個只會說「想得更廣一些」或「再努力一點」的顧問等於什麼都沒說，為了等待它而停滯不前，比從不諮詢更糟糕。
old-man — 在您斷定某樣東西不存在 之前 呼叫它
它要解決的失敗是：一個針對語料庫已展現的形狀而撰寫的檢查，遇到了一個形狀不同的論文，並報告了不存在而非不熟悉。這種情況在處理第四篇論文時的一個下午發生了四次——一個以 images/ 開頭的引用被假定為我們已提取的圖片，第一個 \end{tabular} 被假定為表格的結束，一個在 % 註解內的 \caption 被算作一個標題，而一個寫成 \captionof 的標題則完全沒被計數。每一個都是同樣的錯誤：模式被當成了定義。
當您準備要進行以下操作時，請觸發它：
- 因為搜尋不到，而斷定原始碼中不包含某個東西；
- 撰寫一個模式，其匹配結果將決定某個東西存在或不存在；
- 根據您已翻譯過的論文，歸納出一個通用規則。
詢問它： 您準備下結論的內容、您使用的模式，以及您搜尋的檔案。預期會得到： 那些會使該模式失效的、具名的替代拼寫和佈局方式——\captionof 旁邊的 \caption、wrapfigure 旁邊的 figure、內聯的 .bbl 旁邊的 \bibitem——每一個都具體到可以用 grep 搜尋。然後用 grep 搜尋它們。只有當您根據它命名的搜尋確實找到了東西時，這個建議才值得呼叫；如果有找到，請在您的報告中記錄下來。
question-monster — 在您斷定某樣東西不可能 之後 呼叫它
它要解決的失敗是：在第一次嘗試就放棄。DeeR-VLA 的八個方程式中，有七個因為 \setlength（一個沒有任何可讀內容的間距指令）而被拒絕，第八個則是因為 \sideset——而其實存在一個完全等效的 \sum\nolimits_{X}，並且同一個方程式稍後也使用了它。在找出替代方案之前，放棄就被寫了下來，只有一個持續追問「真的嗎，完全沒辦法？」的讀者才發現了它。
當您準備要寫下 不支援、無法表達、沒有辦法、必須捨棄，或我們會失去這個——無論是在報告、提交訊息或註解中——請觸發它。
詢問它： 您宣告不可能的事、您嘗試過的方法，以及確切的錯誤或拒絕訊息。預期會得到： 具體的候選方案來進行測試，而不是鼓勵。當答案確實為否定時它會停止，而判斷的依據是 K100：邊界不在於某個指令未實作，而在於支援的子集沒有任何方法能表達同樣的事情。一個存在等效方法的未實作指令，只是一個您尚未完成的改寫。
fast-finder — 用它 取代 閱讀兩份記錄
它要解決的失敗是：記錄只有在幾秒內找到正確條目時才有用，而當條目數達到 130 個時，靠閱讀已經無法做到這點。它執行 kb.py，判斷哪些匹配結果真正與您的問題相關，然後原封不動地回傳它們——一個表示某個方法已被嘗試過並已還原的狀態行，就是一個條目的全部價值，而摘要會遺失它。
當您本來會打開 KNOWLEDGE.md 或 KNOWHOW.md 時請觸發它，以及每當您準備要修改某個函數並想知道關於它的已知資訊時。kb.py find 本身對於精確的符號已經足夠；而這個代理的價值在於處理模糊的查詢。
它也能保持記錄的可查找性：kb.py check 會捕捉到索引行未觸及的條目（因此是看不見的，撰寫它是浪費時間），而 kb.py stale 會捕捉到那些命名了儲存庫中已不存在之函數的條目。請在步驟 9 之後執行這兩者。
referee — 在 整個執行過程已被評估 後呼叫它，而不是逐個區塊地呼叫
它要解決的失敗是：verify_chunk 拒絕了一個區塊，但並未告訴您關於整個執行的任何資訊。只發生一次的缺陷是意外；同樣的缺陷發生在三分之一的區塊上，那就是簡報（BRIEF）的問題，因為每個扮演某角色的實例都讀取了相同的提示；同樣的缺陷發生在第三本書上，那就是沒有人修復過的問題。這些從區塊內部都是看不到的。
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，可以像另外兩個記錄一樣透過 kb.py 搜尋，這樣當某個角色提出的警告，可以在另一個角色做同樣事情時被找到。
黃牌是針對重複發生，而非第一次發生，也永遠不會針對工具或簡報的錯誤。保持沈默是常見且有效的輸出：一位每次都聽取報告的裁判，到了第三次就會被忽略；而一個因為預期會收到黃牌而猶豫不決的角色，會變得更慢，而不是更正確。
什麼讓 old-man 成長
scripts/corpus_census.py 記錄了每篇論文的實際形狀——它使用了哪些浮動環境、標題拼寫、表格結構、參考文獻樣式、數學式和前端內容。merge_and_build.py 在每次成功建置結束時寫入一行記錄，因此記錄會自動增長，不會被遺忘。
python scripts/corpus_census.py digest
會將其轉換為頻率統計（「5 篇中有 1 篇使用 wrapfigure，5 篇中有 4 篇使用 figure*」），並在最後列出 從未見過（NEVER SEEN）——語料庫中沒有任何一篇論文曾包含的形狀。這第二個列表是重點：一個根據這些形狀之一來做決策的模式，從未被真正的論文測試過，而撰寫它的人也沒有。
普查會自動為每篇論文增加一行；但其詞彙表（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 呈現的引用。有兩個已知的限制值得告知使用者：原始的 LaTeX 表格會被原樣保留，而不會被翻譯；以及用 tikz/pgfplots 繪製的圖形在原始碼中沒有影像檔案。
在您認為遺失的圖形是 tikz 圖形之前，請先對照原始 PDF 計算圖形數量。 pandoc 的 LaTeX 讀取器只知道一組固定的結構；其他所有東西都會以原始 LaTeX 的形式直接通過，而 resolve_images 只會改寫 pandoc 已發出的圖形。因此，圖片被丟棄了，但其標題仍然會印出，並且沒有任何東西會報告問題——這看起來完全像是一個 tikz 圖形。有三個不同的結構會導致這種情況，它們現在都已在此擷取階段被處理，並且在處理新論文時都值得辨識：\subfloat（subfig）、\begin{SCfigure} 及其 wrapfigure/sidewaysfigure 相關結構，以及用於多頁圖形 PDF 的 \includegraphics[page=N]——最後一種根本不會產生任何錯誤，只會產生錯誤的圖形和另一個圖形的副本。dry_run.py 會捕捉所有這三種情況。
請根據表格的 \tabular 前文來檢查其欄數，而不是根據其他行。 pandoc 在輸出時會以兩種方式重塑原始表格，而這兩種方式都無法透過計數來捕捉：它會同時重新發出展開後的 *{9}{r} 和原始的內容，因此一個 12 欄的表格會變成 21 欄，每行後面跟著九個空欄；並且它會完整地捨棄 \rotatebox/\multirow，因此一個狹窄群組欄所攜帶的標籤會消失，而這些行則會變得無法歸屬。兩者都已在此擷取階段被處理，並且都可以在之後透過數學側車（sidecars）進行修復，而無需觸及正文——請參閱 K53。
這會建立一個包含以下內容的 {filename}_temp/ 目錄：
input.html、input.md——中間檔案（僅在校準後端時產生input.html）chunk0001.md、chunk0002.md、...——用於翻譯的原始區塊chunk0001.math.json、...——公式/引用佔位符側車（arXiv 路徑）flat.tex、arxiv_src/——平面的 LaTeX 原始碼和解壓縮的 tarball（arXiv 路徑）manifest.json——用於追蹤和驗證的區塊清單source_fingerprint.json——此暫存目錄建構來源位元組的 SHA-256 身分標識config.txt——包含中繼資料的管道設定，包括建構它的後端
暫存目錄會記住它的後端。使用不同的後端重新執行將會中止，以避免混合 arXiv 衍生的 input.md 和 calibre 衍生的圖形。
如果 convert.py 因為暫存目錄是由不同的原始位元組所建立而中止，請不要重複使用它——刪除暫存目錄或傳遞一個新的 --temp-root，然後重新執行。在指紋識別功能存在之前建立的暫存目錄，會在接受時伴隨一個警告，並在下一次成功執行時被指紋識別。
3. 發現原始區塊
使用 Glob 函式尋找所有原始區塊：
Glob: {filename}_temp/chunk*.md
從原始清單中排除 output_chunk*.md。下面的選擇性重新翻譯計畫會決定哪些區塊實際需要處理。
3.5. 建立詞彙表（術語一致性）
一個單獨的子代理會用全新的上下文翻譯每個區塊。在沒有共享狀態的情況下，同一個專有名詞可能會在多個翻譯中產生偏差。詞彙表讓每個子代理都能為其區塊中出現的術語看到相同的標準翻譯。
如果 <temp_dir>/glossary.json 已存在，請跳過重建——重新執行此技能不能覆蓋已經建立的翻譯一致性。
...
[為翻譯而截斷]