Communitygithub.com

KiaroSama/Revayat-Skill

將整本書翻譯為高品質波斯語並製作專業 Word 檔案的代理技能：支援掃描與混合 PDF 的 OCR、保持原始尺寸的插圖、Word 原生註腳、可點擊目錄、RTL 排版與鎖定名稱詞彙表。適用於 Claude Code、Kiro、Codex、Cursor 和 Cline。

Revayat-Skill 是什麼？

Revayat-Skill 是一個專為 AI 代理設計的技能，可將英文書籍完整翻譯為出版級品質的波斯語，並自動生成專業的 Word (.docx) 檔案。它採用九個步驟的嚴謹流程，包括：工具檢查、文字萃取（支援數位與掃描 PDF，並具備 OCR 功能）、詞彙表建立（鎖定專有名詞）、分塊翻譯（可並行處理多個子代理）、合併、波斯語排版優化、品質保證檢查，以及最終的 Word 檔案建置。此技能支援 Claude Code、Codex、Cursor、Cline 等主流開發代理平台，並內建多項嚴格規則：不反轉波斯文字、不遺漏任何標記（如 `@@ id` 標頭、註腳）、不簡化或跳過困難句子。其獨特功能包括：保留原始插圖大小、產生 Word 原生註腳（而非文字框）、建立可點擊目錄、執行 RTL 排版，以及透過鎖定詞彙表確保人名與術語的一致性。QA 環節可檢測 20 種以上的錯誤類型，確保翻譯品質達到出版標準。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add KiaroSama/Revayat-Skill
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

Revayat — 英文 → 波斯語 書籍翻譯

請依序執行以下九個步驟。每個步驟包含一條命令及處理其輸出結果的規則。請勿隨意變更順序，也請勿因上一步驟結果看似正確而跳過任何步驟。

設定兩個變數，然後在後續步驟中一併使用：

  • SKILL_DIR — 存放此檔案的資料夾。在 Claude Code 插件中，其路徑為 ${CLAUDE_PLUGIN_ROOT}/skills/revayat。
  • WORK — 用於存放此書籍的工作資料夾，例如 work/。

每條命令的格式均為 python3 $SKILL_DIR/scripts/revayat.py <stage> …。

永不可違反的五項規則

  1. 切勿為了使其從右至左閱讀而反轉波斯語文字。 文字方向由建置工具處理。反轉會產出僅能在特定檢視器中正常顯示，在其他環境中卻無法使用的損壞檔案。
  2. 切勿自行發明、刪除、合併、拆分或重新排序 @@ id 標頭。 請將您收到的標頭原封不動地回傳。
  3. 切勿刪除任何 [[fn:…]]、**bold**、*italic* 或 `verbatim` 標記。 這些標記會被計數；數量不符將導致 QA 失敗。
  4. 切勿為了修正翻譯而手動編輯 book.json。 請修正工作表後重新執行合併步驟。
  5. 切勿縮短書籍內容。 不得摘要、不得跳過難句、不得軟化語氣。若某步驟報告內容遺失，請重新處理該段落。

步驟 1 — 檢查工具

python3 $SKILL_DIR/scripts/revayat.py doctor
  • "ready": true → 繼續。
  • "ready": false → 執行 pip install -r $SKILL_DIR/requirements.txt，然後再次執行 doctor。
  • 若 optional_tools 顯示 not found，暫時無妨。步驟 2 會告訴您是否真的需要 OCR。

步驟 2 — 萃取

python3 $SKILL_DIR/scripts/revayat.py extract "<input file>" --out $WORK

若來源為波斯語檔案，請加上 --ocr-lang fas。其他語言請使用對應的 Tesseract 代碼（deu、fra、ara 等）。

閱讀其輸出的 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。

如果該書是掃描而來的，請立即執行以下兩個額外步驟。

辨識信心度 — 若無此資訊，誤讀的字詞與正確的字詞將無法區分，因為兩者都是流暢的波斯語：

python3 $SKILL_DIR/scripts/revayat.py ocr-sidecar   --pdf $WORK/ocr.pdf --out $WORK --lang fas --book $WORK/book.json

此步驟會產生 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 arabic
python3 $SKILL_DIR/scripts/revayat.py extract "<input file>" --out $WORK   --figures-from-mineru $WORK/mineru

請針對 cleaned.pdf（而非原始檔案）執行 MinerU，否則它會將浮水印視為圖片而裁切掉。僅從 MinerU 取得圖片。 MinerU 對波斯語文字自行辨識的結果，會出現單詞及其內部字母順序反轉的問題；而使用 fas 語言的 Tesseract 則能正確讀取同一頁面，因此文字部分應保留原樣。若 MinerU 僅處理了部分頁面範圍，請使用 --figures-page-offset N 參數。

然後，在繼續下一步之前，先檢視結果：

python3 $SKILL_DIR/scripts/revayat.py qa check --book $WORK/book.json --allow-incomplete

此時可忽略 untranslated-block — 因為尚未進行任何翻譯。您需要關注的是 asset-missing。如果一本真實書籍的 stats.text_blocks 低於 20，則表示萃取失敗：請參閱 references/extraction.md。

步驟 3 — 詞彙表

python3 $SKILL_DIR/scripts/revayat.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

請保留 first_block_id 欄位不變 — 流程會依據此欄位來決定哪個區塊應首次引入該名稱。請勿編輯此欄位，也請勿自行決定首次提及的位置。

刪除那些並非真實名稱的條目。然後繼續。

步驟 4 — 分塊

python3 $SKILL_DIR/scripts/revayat.py chunk build \
  --book $WORK/book.json --out $WORK/chunks --glossary $WORK/glossary.json

請記下區塊數量。每個區塊將成為一個獨立的翻譯任務。

如果您已翻譯過部分工作表，而後有輸入內容發生變更，此步驟會拒絕執行並顯示 "refused": "stale-worksheets"，而非靜默地提供已不符書籍內容的工作表。請重新閱讀它所提供的理由；只有在您確定現有的翻譯結果仍然有效時，才加上 --force 參數。

步驟 5 — 翻譯

針對每個 $WORK/chunks/chunkNNNN.md，產出 $WORK/chunks/out_chunkNNNN.md。若您的運行環境支援子代理，請為每個區塊使用一個獨立的子代理，每次最多並行處理 8 個。若不支援，則逐一處理 — 結果相同，只是速度較慢。

請對子代理提供以下精確指示：

請讀取 $WORK/chunks/chunkNNNN.md 並寫入 $WORK/chunks/out_chunkNNNN.md。

翻譯為波斯語。請先讀取 $SKILL_DIR/references/translation-policy.md 並遵循其規範。

輸出格式 — 此為機械性要求，請務必完全正確：

  • 將每個 @@ <id> <kind> 行原封不動地複製，並保持原有順序。
  • 在其下方幾行放置波斯語翻譯。
  • 除此之外，不要輸出任何其他內容：沒有前言、沒有英文、沒有註解、沒有摘要。

規則：

  • 「名稱」表格具有約束力。若某行說明「初次提及，請在此處引入」，請使用該較長形式。其他所有情況請使用簡短形式。請勿自行決定 — 表格已為您決定了。
  • 「周圍文字」僅供參考。請勿翻譯或將其複製出來。
  • 請將 **bold**、*italic*、`verbatim` 和 [[fn:…]] 保留在對應的波斯語單詞周圍，完全原樣。請勿新增或移除任何標記。
  • 完整翻譯每個單元。切勿摘要或跳過。
  • 若要新增自己的註腳：請在句子中寫入 [[fn:tr-01]]，並在結尾處加上一個 @@ tr-01 footnote 區塊來放置其文字。僅限於真正的文化參考或雙關語情況下使用。

隨時檢查剩餘進度：

python3 $SKILL_DIR/scripts/revayat.py chunk status --chunks $WORK/chunks

步驟 6 — 合併

python3 $SKILL_DIR/scripts/revayat.py merge --book $WORK/book.json --chunks $WORK/chunks
欄位意義處理方式
"ok": true所有內容皆已歸位繼續進行步驟 7
missing_outputs這些區塊從未被翻譯翻譯它們
missing_units標頭被刪除了重新處理這些區塊
unknown_units標頭是被發明的重新處理這些區塊

修正問題後重新執行合併總是安全的。

步驟 7 — 波斯語排版

python3 $SKILL_DIR/scripts/revayat.py falint fix --book $WORK/book.json

此步驟僅為機械性處理，且可安全地執行兩次。若書籍必須保留拉丁數字，請加上 --digits keep 參數。

步驟 8 — 閘門檢查，然後建置

python3 $SKILL_DIR/scripts/revayat.py qa check \
  --book $WORK/book.json --assets $WORK/assets --glossary $WORK/glossary.json

當 "ok" 為 false 時，請勿進行建置。 請根據錯誤代碼進行修正：

代碼意義處理方式
untranslated-block某個區塊沒有波斯語翻譯翻譯該區塊
footnote-marker-lost有 [[fn:…]] 標記被刪除重新處理該區塊
footnote-marker-invented某個標記指向不存在的內容重新處理該區塊
possible-omission目標文字遠短於來源文字進行檢查；通常是某個子句被遺漏了
untranslated波斯語翻譯中殘留了英文重新處理該區塊
asset-missing / asset-modified某張圖片遺失或被修改重新萃取
copied-source-run來源文字的子句被原樣保留在波斯語中重新處理該區塊
duplicate-translation兩個不同的來源被翻譯成相同的波斯語某個工作表的回覆被貼了兩次；重新處理這兩個區塊
first-mention-repeated某個名稱在多個位置被首次引入保留第一個，刪除其餘的
image-order圖片在封裝中的順序錯誤重新建置
bookmarks-missing / bookmark-duplicate目錄連結會指向不存在的地方，或指向錯誤的位置重新建置
emphasis-parity（警告）粗體/斜體計數發生變化檢查其中一個；通常無礙
glossary-drift（警告）某個鎖定的名稱被以不同形式呈現重新處理該區塊
ocr-low-confidence（警告）引擎對該區塊的辨識不確定開啟頁面圖像進行比對

對於出版用途，請加上 --strict 參數，使上述最後三個錯誤也變成阻擋條件。

將書籍的標題與作者翻譯至 book.json 中的 meta.title_target 和 meta.author_target 欄位 — 這是唯一被允許的手動編輯，因為沒有對應的工作表可供處理。

然後進行建置：

python3 $SKILL_DIR/scripts/revayat.py build \
  --book $WORK/book.json --assets $WORK/assets --out out/book.fa.docx \
  --font "Vazirmatn" --size 11.5

實用參數：若檔案需要在未安裝波斯語字型的機器上顯示，請使用 --font Tahoma；若要沿用原文的標題字級，請使用 --heading-size source；若要從現有的 Word 檔案繼承樣式，請使用 --template ref.docx。完整清單請參閱 references/docx-and-ooxml.md。

步驟 9 — 驗證與回報

python3 $SKILL_DIR/scripts/revayat.py qa docx --file out/book.fa.docx --book $WORK/book.json

如果 "ok": false，請在告知使用者檔案已準備好之前先進行修正。

然後進行回報：說明檔案位置、章節數量、圖片數量、註腳數量、QA 標記但您選擇不予處理的事項，以及以下限制說明 —

Word 會重新調整文字流向，因此可編輯的波斯語文件無法與原始 PDF 達到逐頁一致。圖片位元組與實際尺寸、章節結構、強調標記、註腳以及章節連結則會完全一致。

參考資料

請僅在步驟指向時才閱讀以下文件：

  • references/translation-policy.md — 提供給翻譯子代理的指示
  • references/persian-typography.md — RTL、ZWNJ、標點符號、混合文字
  • references/extraction.md — OCR 路由、浮水印、困難書籍
  • references/glossary-and-voice.md — 命名原則、別名、角色語氣
  • references/docx-and-ooxml.md — 所有建置選項及其產出
  • references/troubleshooting.md — 您最可能遇到的失敗情況

相關技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community