循環） 是做什麼的？
將英文論文 PDF 當作熟悉學術論文的英文校稿者進行校稿。基準是 Linda Olson 的 Guide to Academic and Scientific Publication（Proof-Reading-Service.com, 2014）整理成的校稿項目清單 references/proofreading_checklist.md。該指南的核心思想是「遵循投稿規定，準確且一致」。許多寫法本身都正確，但在同一篇論文中若不一致，就成為錯誤。因此，所有寫法決定會記錄在 style_sheet.md 中，並在整個過程中遵循。
| 模式 | 做的事 | 提供給用戶的產出 |
|---|---|---|
| 單次校稿 | 對指定 PDF 進行一次校稿 | 紅字 PDF（含高亮與修正建議的註解）、校稿報告、style sheet |
| loop | 校稿 → 將修改反映至原稿（LaTeX）→ 重新產生 PDF → 由另一位校稿者再次校稿，重複直到無建議或達到上限輪數 | 修正後的 PDF、原始 PDF 的紅字版、每輪報告與趨勢、變更記錄、需作者確認事項 |
以下，<skill_dir> 代表此 SKILL.md 所在的目錄，<ws> 代表工作資料夾，AWL 是 python <skill_dir>/scripts/awl.py 的縮寫。若環境中無 python 則使用 python3。
0. 啟動：決定模式與 PDF
使用方式：
/academic-writing-loop 單次校稿 paper.pdf
/academic-writing-loop loop paper.pdf
/academic-writing-loop loop 3 paper.pdf ← 指定最大輪數（預設 5）
loop N 表示「最多校稿 N 次，反映（重新產生 PDF）最多 N−1 次」。最後必定以校稿結束，因此可了解最終版 PDF 中仍有哪些問題。
預估所需時間（測試：2 頁・640 字的論文）：單次校稿約 15 分鐘。loop 模式的第一輪校稿最長，總計約 45 分鐘（3 次校稿・2 次反映）。時間大致與頁數成正比增加。
- 從訊息（技能的引數）中讀取模式與 PDF。分隔符可為空白、「、」或「,」。
- 單次校稿：
單次校稿單次一次oncesingle1 - loop：
loop循環重複。緊接的數字為最大輪數（校稿次數，預設 5） - PDF：以
.pdf結尾。相對路徑從工作目錄解析，若找不到則依檔名搜尋。 - 若無模式，則透過提問工具（AskUserQuestion 等，如無則用聊天）詢問：
單次校稿/loop（校稿→修改→再校稿重複）。若無 PDF，也一併詢問。
- 單次校稿：
- 若訊息中包含投稿期刊名稱、投稿規定 URL、美式/英式拼寫指定，則直接採用。若無則不詢問（無投稿規定時，依一般學術英文慣例；拼寫則依原稿多數）。
- 檢查 PyMuPDF：
python -c "import fitz"。若無則執行python -m pip install pymupdf（紅字 PDF 與位置資訊所需；若無法安裝則繼續但不產出紅字 PDF，並告知用戶）。
1. 設定（兩模式共通）
工作資料夾為 <PDF 所在資料夾>/<PDF 名稱>_awl/（若無法寫入則在工作目錄下）。
AWL init <ws> --pdf <pdf> --mode once|loop [--max-rounds 5] [--journal "<投稿先>"]
AWL extract <ws>/rounds/r01/paper.pdf -o <ws>/rounds/r01/paper.txt
AWL scan <ws>/rounds/r01/paper.txt -o <ws>/rounds/r01/scan.md
<ws>/
├── state.json 模式・上限輪數・結束原因（由 awl.py 管理）
├── style_sheet.md 寫法決定（所有輪次共用）
├── original/ 收到的 PDF，不做修改
├── src/ 編輯用原始碼（僅 loop）
├── rounds/rNN/ paper.pdf paper.txt scan.md corrections.json report.md annotated.pdf
│ revision_log.json（loop） src/ changes.diff（loop）
├── author_queries.md 需作者確認事項（loop）
└── work/ 頁面圖片等
- 若
extract警告「very little text per page」，表示為掃描 PDF。需告知用戶需要 OCR（pdf 技能）。若內文非英文，則告知此技能不適用並停止。 - 若已知投稿期刊且可存取 Web，則讀取官方投稿規定（Author guidelines / Instructions for authors），將語言・格式規則（美式/英式、字數、摘要結構、標題、引用格式、圖表、縮寫、關鍵字數量）寫入
style_sheet.md的「投稿規定」欄及對應行。規定為最高優先（指南 §3）。 - loop 模式下，在此處用 2～3 行告知用戶：工作資料夾、上限輪數，以及後續將不再確認直接進行。單次校稿模式較短，可在最後回覆中一併說明。
2. 一輪校稿（兩模式共用流程）
校稿內容請遵循 references/proofreader_brief.md（流程・指摘撰寫方式・JSON 格式）與 references/proofreading_checklist.md（分類與嚴重程度）。
誰來校稿
- 單次校稿模式：可由自己執行。
- loop 模式：每輪應交給新的子代理人（透過 Agent 工具）。由修改者自身的脈絡出發，校稿者無法得知「打算改什麼」，只能根據「PDF 上實際寫了什麼」來判斷。若由同一脈絡重讀自己的修改，容易遺漏。
- 長論文（正文超過約 12 頁・7,000 字）：應分成數個頁面範圍（每 6～8 頁，以章節斷點為界），交給多個子代理人並行處理，再透過
AWL merge合併，之後由自己或負責統整者檢查論文整體一致性（拼寫、術語、縮寫、引用與參考文獻、圖表編號、標題），並搭配scan.md的統計進行確認。 - 若環境無法使用子代理人，則全部由自己依序進行。loop 的第二輪以後，務必閱讀從新 PDF 抽出的文字來校稿（不要憑記憶判斷）。
給校稿者的任務指示（所有路徑請用絕對路徑，因為子代理人的 shell 在每次呼叫時工作目錄可能重置）
您是學術英文的專業校稿者。請先完整閱讀 <skill_dir>/references/proofreader_brief.md 與
<skill_dir>/references/proofreading_checklist.md，並依照其流程・標準・輸出格式進行。
- 要校稿的 PDF：<ws>/rounds/rNN/paper.pdf（抽出文字：<ws>/rounds/rNN/paper.txt）
- 機械檢查的候選：<ws>/rounds/rNN/scan.md
- 寫法決定：<ws>/style_sheet.md（第一輪需填入基本設定・術語・縮寫）
- 前一輪的指摘：<ws>/rounds/r(NN-1)/corrections.json ← 僅第二輪以後
- 負責頁面：全部頁面 ← 若分頁時改為「p.1–8」等
- 輸出：<ws>/rounds/rNN/corrections.json（分頁時為 corrections.partK.json）
- 工具：python <skill_dir>/scripts/awl.py（validate / report / annotate）、
python <skill_dir>/scripts/pdf_tools.py render（以圖片檢視圖表頁面）
- 環境注意：<例：Windows。路徑含日文・空白，需用引號包圍。請勿寫入 <ws> 與 <skill_dir> 之外>
請勿改變作者原意。請勿修改數值・數學式・引用文・參考文獻標題，若有疑慮則列為 query。
最後請回報「件數（錯誤/清晰度/文體/作者確認）・常見錯誤趨勢・validate 結果」。
校稿後務必確認（即使交給子代理人，也需自行執行）
AWL validate <ws>/rounds/rNN/corrections.json # 需為 VALID 才可；否則請校稿者修正
AWL report <ws>/rounds/rNN/corrections.json # → report.md
AWL annotate <ws>/rounds/rNN/paper.pdf <ws>/rounds/rNN/corrections.json -o <ws>/rounds/rNN/annotated.pdf
validate 會逐一比對每項指摘的 original 是否確實存在於 PDF 文字中。找不到的指摘，可能是抄寫錯誤或是針對不存在的句子的指摘，兩者都無法用於紅字標記或修改。
3. 單次校稿模式
- 對 r01 執行 §2 流程。
- 執行
AWL finalize <ws>→ 產出<ws>/<PDF 名稱>_proofread.pdf（紅字版）與<ws>/report.md。 - 回覆用戶時請簡潔：
- 件數（錯誤 / 清晰度 / 文體 / 作者確認）與整體意見（2～3 句）
- 最常見的錯誤類型前 3～5 項，每項附一個實際例子（原文 → 修正建議）及規則名稱
- 作者確認（query）清單（簡短）
- 檔案位置（紅字 PDF 可透過滑鼠停留或註解列表查看建議與理由）
- 請勿貼整份報告。最後，可補充一句若使用 loop 模式，可進一步反映修改並重新產生 PDF。
4. loop 模式
4.1 準備編輯用原始碼（可與 r01 校稿並行）
init 會顯示 PDF 旁邊可能存在的原始碼候選。
- 有 LaTeX 原始碼（.tex、資料夾、Overleaf 或 arXiv 的 .zip / .tar.gz）：複製・解壓縮至
<ws>/src/（包含\documentclass與\begin{document}的檔案為主）。先編譯一次，確認原始碼與 PDF 為相同版本：
若相似度低於 0.95，表示版本很可能不同。請詢問用戶要使用哪個版本。python <skill_dir>/scripts/build_pdf.py <ws>/src/<main>.tex --out <ws>/work/source_build.pdf AWL extract <ws>/work/source_build.pdf -o <ws>/work/source_build.txt AWL compare <ws>/rounds/r01/paper.txt <ws>/work/source_build.txt - 找不到候選：僅詢問一次是否有原始碼（LaTeX / Overleaf 的 zip）。若有原始碼，反映修改會更準確且快速。
- 無原始碼：依照
references/pdf_to_latex.md的流程從 PDF 重建 LaTeX（可交給子代理人，並與 r01 校稿並行。10 頁約需 20～40 分鐘）。要求：版面僅為近似，英文部分（含錯誤）應完全照抄。 - 若原稿為 Word（.docx）：此循環會編輯 LaTeX。若希望維持版面，建議參考單次校稿的紅字 PDF 與報告，直接在 Word 中修改較可靠，請詢問用戶偏好哪種方式。
- 準備完成後，執行
python <skill_dir>/scripts/snapshot.py <ws>/src <ws>/rounds/r01。
4.2 輪次 r（r = 1, 2, …）
(a) 校稿：執行 §2。結束後，向用戶回報一行進度。範例：r02 校稿完成：錯誤 9 / 清晰度 4（前次 41 / 17）、前次指摘已解決 52/58
(b) 判斷是否繼續：執行 AWL status <ws>，依最終行的 NEXT: 指示。停止條件由腳本判斷（不憑當下印象決定）：
- 錯誤＋清晰度指摘數量變為 0（收斂）
- 已達上限輪數
- 錯誤＋清晰度件數未較前一輪減少（表示修改只是在往返，無實質進展）
若
NEXT: STOP則前往 §4.3。判斷在校稿完成後立即進行，因此最終版 PDF 必定已校稿過。
(c) 反映修改（將第 r 輪的指摘反映至原始碼，產生 r+1 版的 PDF）：依下方任務指示啟動修改者的子代理人，並等待完成。完成後自行確認：
rounds/r{r+1}/paper.pdf、paper.txt、scan.md均已存在。編譯成功，且無未定義引用rounds/r{r}/revision_log.json存在，且AWL verify <ws> --round r成功（因文字抽取限制而卡住的項目，可透過頁面圖片確認，若有verified_manually標記即可）- 若編譯失敗，從
rounds/r{r}/src/還原受損檔案，重新進行反映修改。切勿將舊版 PDF 當作新版交給校稿者。
→ 前往 r+1 的 (a)。
給修改者的任務指示（路徑請用絕對路徑）
您是作者方的編輯，負責將英文校稿的指摘反映至原稿。請先完整閱讀
<skill_dir>/references/reviser_brief.md，並依照其規則（不改變意義與資料、
query 不應修改內文、遵循 local → global 順序）進行。
- 要編輯的原始碼：<ws>/src/（主檔：<main>.tex）
- 本次的指摘：<ws>/rounds/rNN/corrections.json（也可參考 report.md）
- 寫法決定：<ws>/style_sheet.md（若因作者意圖或領域慣例而決定不修改，請在「不修改之處」中記錄）
- 需作者確認事項：<ws>/author_queries.md（請追加 query）
- 新的 PDF：<ws>/rounds/rMM/paper.pdf（MM = NN+1）。編譯・抽出・scan・snapshot・revision_log.json・verify 的
流程請依 reviser_brief.md 的 §4 進行。
- 環境注意：<同校稿者>
最後請回報「套用/不修改/作者確認的件數・編譯結果・verify 結果・在 style sheet 中追加的內容」。
4.3 結束處理
- 執行
AWL finalize <ws>（若因用戶中斷等非判斷理由停止，需加--reason "<原因>"）。產出<PDF 名稱>_corrected.pdf（最終版）、<PDF 名稱>_proofread_r01.pdf（原始 PDF 的紅字版）、若有剩餘指摘則產出<PDF 名稱>_corrected_remaining.pdf、changelog.md、progress.md。最後一輪的作者確認未經修改者處理，因此finalize會將其追加至author_queries.md。 - 產生有變更處標色的 PDF（選擇性）：為避免汙染
src/，先複製至<ws>/work/diff_src/再產生。cp -r <ws>/src <ws>/work/diff_src latexdiff <ws>/rounds/r01/src/<main>.tex <ws>/src/<main>.tex > <ws>/work/diff_src/diff.texlatexdiff回傳非零或diff.tex為空（MiKTeX 下可能因缺少 Perl 模組而失敗），則跳過並在回覆中簡述原因。成功後執行build_pdf.py <ws>/work/diff_src/diff.tex --out <ws>/<PDF 名稱>_diff.pdf。 - 撰寫
<ws>/final_report.md：# 英文校稿報告：<論文標題> - 模式 / 輪數 / 結束原因 / 投稿期刊・拼寫・引用格式（style sheet） ## 趨勢 （progress.md 的表格） ## 原始稿件英文傾向 （r01 的 summary 與分類件數。常見錯誤範例與規則） ## 已反映的主要修改 （changelog.md 中的代表性範例） ## 需作者確認事項 （author_queries.md，依優先順序） ## 剩餘指摘 （最終輪 report.md 的重點） ## 檔案清單 - 回覆用戶時請簡潔：輪數與趨勢（錯誤＋清晰度件數）、常見錯誤類型、優先作者確認事項、剩餘指摘、檔案位置。請勿貼整份報告。
中斷後重新開始
若 <ws>/state.json 存在，可透過 AWL status <ws> 檢視狀態，並從 NEXT: 指出的步驟繼續。init 不會覆蓋現有工作資料夾（僅在重新執行時可用 --force）。
原則與理由
- 不改變意義・不虛構內容：校稿的對象是語言，而非研究內容。請勿修改數值・數據・數學式・引用文・參考文獻標題・主張的強度。無法由校稿者單方決定的事項，應以 query 形式回報作者。由於是實際的原稿，僅憑猜測改寫將扭曲作者的主張。
- 一致性透過 style sheet 維護：由於每輪由不同校稿者閱讀，若不記錄決策，就會發生「改為英式 → 改回美式」的來回往返。決策順序為：投稿規定 → 已發表論文 → 原稿多數，且中途不改變。
- 校稿與修改分離：校稿者只根據 PDF 提出指摘；修改者先確認指摘的正確性再反映；下一輪校稿者則獨立驗證結果。這樣比修改者自我檢查更容易發現遺漏與修改時引入的錯誤。
- 穿插機械性比對：
validate（確認指摘是否針對實際存在的句子）、verify（確認修改是否已反映在 PDF 中）、compare（確認重建內容是否與原版一致）是用數字確認語言模型自我幻覺的工具。不可省略。 - 停止判斷交由腳本：依
status的NEXT:指示。校稿者只要細心找，一定能找到問題，因此若憑感覺繼續，只會造成來回修改風格偏好。 - 輪次之間不詢問用戶：選擇 loop 模式時，即已授權執行至上限輪數。報告僅限於一行進度；只有在發生阻礙（編譯無法修復、原始碼與 PDF 版本不符、PDF 無法讀取）時才停下來與用戶討論。
- 不修改原始檔案：勿寫入
original/以及用戶資料夾中的原始 PDF 與原始碼。所有編輯均在<ws>/src/的複製中進行。 - 指南中的過時規則視為風格：該指南（2014 年版）傾向避免分裂不定詞與單數 they，但現今許多風格指南已允許。如投稿規定未要求，則不視為錯誤。