Revayat Novel — 英文 → 波斯語書籍翻譯
請依序執行以下九個步驟。每個步驟包含一個命令以及如何處理其輸出的規則。請勿隨意變更順序，也請勿因為前一步驟看起來沒問題就跳過它。
先設定四個變數，然後在所有地方使用它們：
SKILL_DIR— 存放本檔案的資料夾。在 Claude Code 外掛中，其路徑為${CLAUDE_PLUGIN_ROOT}/skills/revayat-novel。WORK— 用於存放本書的工作資料夾，例如work/。PY— Python 直譯器。請解析一次；python3在大多數 Windows 安裝中不存在，因此硬編碼的命令列只能在三種平台中的兩種上正常運作：- macOS / Linux：
PY=python3 - Windows：
PY=python— 或PY="py -3"（如果已安裝啟動器） - 如果兩者都無法執行，則步驟 1 中的
doctor將無法啟動，這正是需要處理的信號
- macOS / Linux：
OCR_LANG— Tesseract 用於您正在翻譯的書籍中印刷的語言的代碼，而不是您要翻譯成的語言。對於常見的英文 → 波斯語任務，這是eng。波斯語來源是fas；德語是deu，法語是fra，阿拉伯語是ara。**所有 OCR 步驟必須使用相同的值。**使用波斯語模型辨識英文頁面會回傳看起來自信但實際上是垃圾的內容，這比低分數更糟，因為下游的任何環節都無法發現。
每個命令都是 $PY $SKILL_DIR/scripts/revayat-novel.py <stage> …。
絕不可違反的五項規則
- 絕不反轉波斯文字使其呈現從右到左的閱讀順序。排版方向由建構器設定。反轉文字會產生一個除了某個檢視器之外到處都壞掉的檔案。
- **絕不擅自新增、刪除、合併、分割或重新排序
@@ id標頭。**請完全回傳您收到的那些。 - **絕不遺漏任何
[[fn:…]]、**粗體**、*斜體*或`逐字`標記。**它們會被計數；不符會導致品質保證失敗。 - **絕不手動編輯
book.json來修正翻譯。**請修正工作表，然後重新執行合併。 - **絕不縮減書籍內容。**不允許摘要、跳過困難的句子或淡化處理。如果某個步驟回報內容遺失，請重新執行該區塊。
步驟 1 — 檢查工具
$PY $SKILL_DIR/scripts/revayat-novel.py doctor
"ready": true→ 繼續。"ready": false→ 執行pip install -r $SKILL_DIR/requirements.txt，然後再次執行doctor。optional_tools顯示not found暫時沒關係。步驟 2 會告訴您是否真的需要 OCR。
步驟 2 — 萃取
$PY $SKILL_DIR/scripts/revayat-novel.py extract "<input file>" --out $WORK --ocr-lang $OCR_LANG
$OCR_LANG 是書中印刷的語言，已在上面設定一次。如果在這裡用錯，並不會立即顯示失敗：OCR 仍然會回傳文字，但它們只是錯誤的文字。
閱讀它印出的 JSON 並遵循表格：
| 您看到的內容 | 您該怎麼做 |
|---|---|
"kind": "digital" | 無需操作；不需要 OCR |
"kind": "scanned" 或 "mixed" | OCR 已自動執行；檢查 ocr.probe_after.text_share 是否高於 0.7 |
| 一個命名為 OCRmyPDF 的錯誤 | 依照訊息指示安裝它，然後重新執行此步驟 |
clean_scan.cleaned 高於 0 | 已從該數量的頁面中移除彩色浮水印 |
ocr.warning 不是 null | 閱讀它；檔案仍然可用，所以繼續進行 |
page_scans_dropped 高於 0 | 表示有那麼多整頁點陣圖被辨識為掃描本身，而非圖片 |
清理工具絕不會編輯您的檔案：原始檔案保持不變，清理後的副本會寫入 $WORK/cleaned.pdf，並在 clean_scan 中記錄每頁移除了什麼以及保留了什麼。傳遞 --clean-scan off 可完全跳過，或傳遞 --clean-scan force 當有郵戳遺留時使用。
如果書籍是掃描的，請立即執行這兩個額外的步驟。
辨識信心度 — 沒有它，誤讀的單字與正確的單字將無法區分，因為兩者都是來源語言的普通單字，位於一個合乎文法的句子中。管線後續的任何環節都無法區分它們，且翻譯器會忠實地渲染錯誤的單字。
$PY $SKILL_DIR/scripts/revayat-novel.py ocr-sidecar \
--pdf $WORK/ocr.pdf --out $WORK --lang $OCR_LANG --book $WORK/book.json
此處的 --lang 是與您提供給 extract 的 $OCR_LANG 相同的值。必須是：這個步驟會重新辨識相同的頁面，以找出引擎的確信程度，因此不同的模型會讀取不同的單字，並為書中未提到的內容評分。
這會寫入 source.ocr.json — 每個單字的邊界框、信心度和閱讀順序，彙總到行、區塊和頁面，以及執行了哪些預處理 — 和 source.ocr.txt，然後在 book.json 中為每個區塊標記其來源區域的信心度。信心度為 low 的區塊將由 qa check 回報為 ocr-low-confidence，接受一個這樣的區塊意味著需要查看頁面圖像。預設閾值為 85 和 60，可透過 --high / --low 調整。
掃描中的插圖 — 掃描頁面是一張平面圖像，因此上面的照片不是一個獨立的圖片，直到有東西找到它：
mineru -p $WORK/cleaned.pdf -o $WORK/mineru -b pipeline -l en
$PY $SKILL_DIR/scripts/revayat-novel.py extract "<input file>" --out $WORK \
--figures-from-mineru $WORK/mineru
MinerU 的 -l 使用自己的代碼，而非 Tesseract 的：en 用於英文來源，arabic 用於波斯語或阿拉伯語腳本。將其與書籍匹配，方式與 $OCR_LANG 匹配相同 — 版面偵測使用腳本來分割頁面。
在 cleaned.pdf 上執行 MinerU，而不是原始檔案，否則它會將浮水印當作圖形裁剪出來。僅從 MinerU 取得圖片。 根據在真實波斯語掃描上的測量，其自己辨識的文字回傳時，單字以及其中的字母是反轉的，而 Tesseract 正確閱讀了同一頁面 — 因此文字仍然來自上述的 OCR 過程，而 MinerU 僅用於 OCR 無法做到的單一事項：在平面點陣圖中找到圖片的位置。當 MinerU 在頁面範圍上執行時，使用 --figures-page-offset N。
然後在繼續之前檢查結果：
$PY $SKILL_DIR/scripts/revayat-novel.py qa check --book $WORK/book.json --allow-incomplete
忽略此處的 untranslated-block — 尚未翻譯任何內容。您要找的是 asset-missing。如果 stats.text_blocks 對於一本真實書籍低於 20，則萃取失敗：請參閱 references/extraction.md。
步驟 3 — 詞彙表
$PY $SKILL_DIR/scripts/revayat-novel.py glossary scan \
--book $WORK/book.json --out $WORK/glossary.json
報告會列出 needs_persian，最常見的排在最前面。打開
$WORK/glossary.json，對於前 20 個條目中的每一個，填寫四個欄位：
"target": "الیزابت بنت",
"later_form": "الیزابت بنت",
"first_form": "الیزابت بنت (Elizabeth Bennet)",
"locked": true
當一個條目有 aliases — 該書單獨使用的姓氏或名字 — 時，將它們的波斯語放入 alias_targets：
"aliases": ["Ashcroft", "Margaret"],
"alias_targets": ["اشکرافت", "مارگارت"]
當來源僅提到 «Ashcroft» 時，波斯語應僅顯示 «اشکرافت»。留空此項會使漂移檢查每次都要求全名，這不僅使波斯語更糟糕，而且會產生誤報。
保持 first_block_id 完全如原樣 — 管線使用它來決定哪個單一區塊引入該名稱。請勿編輯它，也請勿自行決定首次提及。
刪除不是真實名稱的條目。然後繼續。
步驟 4 — 切割成工作表
整本小說絕不能塞進一個模型上下文，因此首先要將其切割。有兩種切割方式，由來源決定使用哪一種 — 這不是偏好問題：
| 來源 | 路徑 |
|---|---|
| PDF，原生數位或掃描 | 依頁面 — 如下 |
| EPUB, DOCX, 純文字 | 依字元預算 — 步驟 4b |
依頁面切割 PDF。 頁面是書本已有的邊界：在不同執行之間穩定，是審閱者檢視的單位，也是唯一可以與渲染頁面進行比較的單位。依字元預算切割的工作表會在任何預算用完的地方中斷，這沒有任何特定位置 — 而且來源中不存在的頁面無法與來源進行檢查。以下行列的格式沒有自己的頁面可供切割，因此它們採用預算路徑並放棄該檢查。
$PY $SKILL_DIR/scripts/revayat-novel.py pages build \
--book $WORK/book.json --out $WORK/pages --glossary $WORK/glossary.json
這會為每個來源頁面寫入一個工作表 — page0001.md，其翻譯會放在它旁邊的 out_page0001.md 中。請使用這些名稱，而不是步驟 5 的 chunkNNNN.md：格式相同，只有檔名不同，而 pages next 會確切告訴您要打開哪個檔案，因此無需猜測。
它還會寫入 $WORK/pages/source/page-0001.pdf — 每個來源頁面作為獨立的 PDF，複製而非重新渲染，因此邊界框、旋轉和圖像品質都是書本自己的。清單會記錄每個頁面及其 SHA-256，並命名整個執行所讀取的 reference_pdf。從清單中讀取來源 PDF；對於原生數位書籍，它是原始檔案；對於掃描，它是 OCR 後的副本，硬編碼任一個都會對另一個造成錯誤。
每個頁面任務僅攜帶其所需的內容：適用於該頁面的詞彙表行、該處發言的角色、OCR 在那裡不確定的單字，以及標記為不要翻譯的相鄰頁面的有限片段。一個文字超過預算的頁面會被分割成編號的部分，而不是被截斷 — part 和 parts 在清單中會說明 — 並且在判斷頁面之前，這些部分會重新合併。
被頁面中斷切斷的段落屬於它開始的頁面，並且只翻譯一次；它延伸到的頁面僅將其視為上下文。切勿翻譯出現在相鄰上下文標題下的區塊 — 它已經屬於另一個頁面的工作表。
$PY $SKILL_DIR/scripts/revayat-novel.py pages status --pages $WORK/pages
$PY $SKILL_DIR/scripts/revayat-novel.py pages next --pages $WORK/pages
status 回報每個頁面的狀態；next 指出第一個仍需要處理的頁面，因此中斷的執行可以從停止的地方繼續，而不是從頭開始。
頁面循環
來源 PDF 是這次執行所讀取的那一個：對於原生數位 PDF，它是書本自己的；對於掃描，它是 OCR 後的副本。清單會記錄它 — 從那裡取得它，而不是命名一個可能不存在的檔案。
SOURCE_PDF=$($PY -c "import json,sys;print(json.load(open(sys.argv[1]))['reference_pdf'])" $WORK/pages/manifest.json)
一次一個頁面，按此順序。每個命令需要前一個命令產生的結果，因此過早執行的步驟會直接拒絕：
P=12 # 無論 `pages next` 剛剛命名了什麼
# 3. 將翻譯摺疊到書本中
$PY $SKILL_DIR/scripts/revayat-novel.py pages merge \
--book $WORK/book.json --pages $WORK/pages --page $P --glossary $WORK/glossary.json
# 4. 單獨排版該頁面
$PY $SKILL_DIR/scripts/revayat-novel.py pages preview \
--book $WORK/book.json --pages $WORK/pages --page $P
# 5. 與來源頁面進行比較
$PY $SKILL_DIR/scripts/revayat-novel.py render-qa \
--book $WORK/book.json --work $WORK --page $P \
--docx $WORK/previews/page-0012.docx --source-pdf $SOURCE_PDF
# 6. 查看兩個圖像（步驟 8 會說明要檢查什麼）
$PY $SKILL_DIR/scripts/revayat-novel.py pages review \
--pages $WORK/pages --page $P \
--answer figure-placement=yes --answer script-integrity=yes \
--answer no-source-language=yes --answer hierarchy=yes \
--answer reads-as-a-book=yes --note "what you saw"
# 7. 只有在完成上述檢查後
$PY $SKILL_DIR/scripts/revayat-novel.py pages accept \
--book $WORK/book.json --pages $WORK/pages --page $P
然後再次執行 pages next，直到它顯示沒有剩餘內容。
步驟 4 不是可選的，如果您跳過它，步驟 5 會為您執行它 — 不提供 --docx，render-qa 會自行建立預覽。當您想在 Word 中打開頁面並親自查看時，可以使用顯式命令。
預覽是一個來源頁面，單獨排版。 它明確不是整本書：波斯語會重新排版，因此來源頁面 12 不會變成書本的頁面 12，而且在小說的中間，漂移會達到好幾頁。檢查書本的第十二頁是否符合頁面 12 的預期，會回報一個正確頁面缺少其所有文字並包含其相鄰頁面的內容。預覽使用生產建構器設定 — 相同的樣式、字型、RTL、圖像大小、標題邏輯 — 因此您看到的是真實內容的實際排版。
波斯語比英文長的頁面會產生兩頁。這是正常的，兩頁都會保留為 renders/target/page-0012.png 和 page-0012-2.png，QA 會讀取所有這些頁面。
如果沒有通過所有關卡，accept 會拒絕 — 它會讀取證據，而不是相信您的話，因此一個頁面不能透過聲稱已完成來標記為完成。它需要四件事：書本中每個頁面送出的單元都有波斯語翻譯、執行記錄上的渲染 QA 通過、仍然這麼說的報告，以及當前的視覺審查。
重新建構是安全的，絕不會丟棄翻譯。一個其來源文字自上次切割以來已更改的頁面，會列在 invalidated 下 — 只有那些頁面需要再次翻譯。一個因在不同預算下重新建構而遺留的工作表，會列在 orphaned 下：它仍然在磁碟上，但已沒有被讀取，因此其翻譯不會到達書本中。
步驟 4b — 當來源沒有頁面時
僅適用於 EPUB、DOCX 和純文字。對於 PDF，請使用步驟 4。
$PY $SKILL_DIR/scripts/revayat-novel.py chunk build \
--book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json
請注意區塊的數量。每個區塊成為一個翻譯任務。
如果您已經翻譯了一些工作表，並且輸入已更改，這會以 "refused": "stale-worksheets" 拒絕，而不是悄悄給您不再與書本匹配的工作表。R
…
[truncated for translation]