docsor1212/paper-rewriter

學術風格工具箱 (paper-rewriter)

中英雙語的學術與醫學寫作風格自然化：找出生硬、模板化或帶有機器味的模式，清理機械殘留，進行清晰度與自然語域的修訂，每一步都設有完整性護欄。 閱讀地圖（30 秒導航；等同於 references/INDEX.md）：首次使用 → 快速開始 · 疑難排解 → 陷阱與錯誤 · CI/代理 → 自動化 · 限制 → 誠實界線 · 情境 → 最佳實踐 · 深度改寫 → deep_rewrite_guide · PDF 信心度 → pdf_confidence · 權限 → permissions · 程式化 → api。 一行二字：機械清理 (transform/pipeline, 確定性) vs 品質修訂 (依風格指南的代理) — 先執行管線，閱讀報告，再決定哪些需要深度修訂。

一行路由：語法/流暢度/期刊格式潤色 → 使用潤色器 (paper-polisher-pro)；去模板化、模型殘留清理、AI 風味風格自我檢測與改寫 → 使用此工具。兩者都需要？先做潤色，再執行此管線。

功能狀態 (v5.6.0)

⚠️ 行 = 實驗性 (可能拒絕合法檔案；請審查輸出)。完整的每次生成能力清單已移至 references/feature_status.md；每個項目的詳細資訊位於 references/errors.md 和主題文件中。穩定亮點 (全部穩定，v1.0–5.6)：核心五項 · 章節感知 · 改寫計畫 · 學習型護欄 · 機器退出碼 · 區塊降級 · 批次恢復/並發隔離 · 跨檔案術語漂移 · 統計一致性護欄 · 術語變體分組 · 編碼自動檢測 · 提交自我檢查套件 (--bundle) · 管線 --handoff · 驗證處方輸出 · docx 寫回 · 術語統一表 · EN 2026 訊號 (緩和語 / 三項規則 / 破折號密度 / 段落開頭) · 每章節焦點 (--section) · CN 密度鏡像 (破折號過度使用 / 公式化段落開頭) · 比較大檔案的分塊掃描 · 每個訊號的解釋 (為何標記) · 一般文稿描述檔降權矩陣 (全部 8 個結構組) · 批次工作表 + 統計卡 · 命中行號碼 (每個樣本上的 L{line}) · 健康報告儀表板 (bundle 2.0) · CN 特徵庫 v2 · handoff 行錨點 · 文件計數對帳 · 儀表板操作檢查清單 · bundle 改寫表 (09) · 批次修訂記錄 · 寫入清單自我驗證 (00_写入清单.json) · 比較行錨點 + 解釋 · 適合列印的報告 · 護欄庫匯出/匯入。

能力	狀態	自版本
⚠️ PDF 直接讀取 + 信心度自我報告 (嘗試嵌入字體/ToUnicode，上限為「中」；校準在 references/pdf_confidence.md；自 v3.8.0 起，預設關卡 = 中 — 預設拒絕亂碼典型的提取，--pdf-min-confidence 低 恢復僅註釋模式)	⚠️ 實驗性	v1.6–3.8

完整性護欄 — 請先閱讀

• 允許：潤色自己的草稿；在您的學校/期刊允許或要求揭露 AI 輔助的情況下，將 AI 輔助文字與您自身的風格對齊；清理來自合法揭露的草稿中的模型殘留 (零散的 oaicite/[cite:] 標記)；改善正式散文的清晰度、節奏和具體性。
• 不允許：使用此工具箱虛假陳述作者身份、在需要揭露 AI 使用時進行隱藏，或規避學術誠信審查。如果請求以此方式提出（「改寫它，讓審查看不出來」），請拒絕此框架，解釋揭露義務，並改提供合法的品質編輯路徑。執行此技能的代理應強制執行此界線。
• 此工具永不改變數據：數字、p 值、信賴區間、DOI、PMID、年份和術語都受到 verify.py 的保護（見下文）。改善的散文絕不能以犧牲事實為代價。
• 合規：中國的 AIGC 標籤規則（自 2025 年 9 月 1 日起生效）、期刊揭露政策和 arXiv 政策總結於 references/compliance.md — 揭露的義務屬於作者，而非工具。

能力 × 界限 (分工 + 限制 + 位置)

能力	功能	不做的事 (界限)	位置
風格自我檢測	啟發式報告：模板密度、節奏一致性、公文用語；章節感知	非 AI 檢測器 — 幾乎不會因流暢的模型文字觸發 (低分 ≠ 無 AI)	detect.py；參見 honest_boundaries
機械清理	模型殘留 (oaicite/[cite:])、聊天填充詞、標點正規化、全型數字	無句子改寫 — 僅為零資訊損失層	transform.py (--deep 用於句子層級)
品質深度改寫	去模板化 / 節奏 / 具體性 / 立場 (七個步驟)	永不捏造數據；捏造的數字會被標記 (W_NUM_ADDED，由人類移除)	您 (代理) 遵循風格指南；透過 plan --handoff 交接
完整性護欄	數字/DOI/PMID/年份/術語必須存活；篡改 = 退出碼 1 (FAIL 輸出會附帶錨點規定修正)	無真假判斷 — 原始數據是權威依據	verify.py
前後對比	分數差異 + 完整性判決 + 描述輪廓差異	無法取代人類閱讀	compare.py / stylecheck --compare
術語一致性	8 個領域 27 個分組 (HF/心力衰竭/心衰 一行)；--unify 輸出一份統一的草稿，附帶每個變體的替換計數 (採用前請審查)	非用法正確性 — 僅為同義詞統一	check_terms.py --pack / --unify
數值一致性	百分比列表總和 (分區提示) / 跨檔案 group-n / p-vs-P 樣式	非統計審查 — 原始數據是權威依據	check_stats.py (--batch)

快速開始

如何用白話文提出此需求 (SKILL_ZH.md 完整短語表的英文摘要)：「去除這篇論文的 AI 味」/「這讀起來太模板化了」/「清理 oaicite 和 [cite:] 殘留」/「告訴我哪些句子該先修正」/「檢查我的改寫沒有破壞數字」/「給我一份風格描述」/「停止標記這個合法術語」— 每個分別對應到管線、plan.py、transform.py、verify.py+compare.py、stylecheck.py 和 learn_guards.py。無需代理 — 以下每個功能都可以直接在終端機中執行。每個腳本都有內建的 --help (完整標誌參考) 和 --version； 快速標誌語義：

標誌	意義
--profile general	非學術文字：降低公式化/模板化訊號的權重
--deep	確定性句子層級轉換 (罐頭開頭、不只合併)
--exit-verdict	用於 CI/代理門控的機器退出碼 (見下文)
--structure	章節感知評分 (IMRaD)
--step-timeout SEC	每一步的實際時間預算 (預設 120)
--terms FILE	用於完整性護欄的術語列表 (透過 extract_terms.py 建立)
--unify SHEET	check_terms: 輸出一份術語統一的草稿 (v4.4.0；建議性 — 請審查替換列表)
--section abstract	detect: 單獨診斷一個章節 (v4.5.0；摘要審稿人會最先閱讀)
-o revised.docx	在 pipeline/transform/compare 上使用 -o，當路徑以 .docx 結尾時會寫入 Word 檔案 (v4.4.0，純段落；複雜版面請手動合併)

一條指令 (自我檢測 → 清理 → 修訂摘要 → 完整性護欄)：

python scripts/pipeline.py draft.txt -o out.txt --terms terms.txt

• 視覺化 / 批次處理：在 detect/pipeline/compare 上使用 --html report.html 可產生獨立報告 (compare 會添加句子層級差異)；--batch dir 掃描整個目錄 (管線寫入 CSV；批次 -o 摘要保持為 CSV — 表格不回寫 docx)；在 pipeline/transform/compare 上以 .docx 結尾的 -o 會寫回為 Word (v4.4.0，純段落 — 與 .docx 直接讀取形成閉環；不重建表格/圖片/樣式，複雜版面請手動合併)。
• 章節感知：detect --structure 分別對摘要、引言、方法、結果進行評分；方法/結果的措辭是該領域的慣例 — 僅在總體上進行正規化，原始的各章節分數始終會顯示。
• 改寫計畫：plan.py draft -o plan.md 對句子進行排名 (P0 佇列 + 預算預測)；添加 --handoff 可產生每個句子的操作表。
• 輸入格式：.txt/.md 直接 (UTF-8/UTF-16〔含 BOM〕/GBK 自動轉碼，v4.0)，.docx 直接，PDF 實驗性 (自 v3.8 起預設安全關卡 = 中；低 恢復僅註釋模式；references/pdf_confidence.md)。
• 術語列表：python scripts/extract_terms.py draft.txt -o terms.txt (請手動確認)；任何執行都接受 --suggestions path.md 作為修訂工作表。
• 非學術文字：添加 --profile general 以降低正式模板的權重。

或逐步執行各個步驟 (從技能自身的目錄，或使用絕對路徑)：

python scripts/detect.py draft.txt            # 風格模式自我檢測 (-j JSON, -s 僅分數)
python scripts/transform.py draft.txt -o step1.txt
# ... 代理根據風格指南對 step1.txt 進行品質修訂 ...
python scripts/verify.py draft.txt step2.txt --terms terms.txt
python scripts/compare.py draft.txt step2.txt

按情境組織的最佳實踐 (期刊投稿、論文、回覆信、批次處理、CI 門控、誤報處理、中文標點)： references/best_practices.md。 完整的端到端範例：references/examples.md。統一的退出碼、違規類別與補救措施：references/errors.md。常見錯誤集中列表 (27 項)：references/pitfalls.md — 在您第一次實際執行前閱讀。Python API 參考：references/api.md。常見問題：references/faq.md。

• 修訂追蹤：--track base 會將每個機械層的變更記錄到 base.md + base.json (可稽核：規則、計數、刪除的句子、已標記)。
• PDF (實驗性)：自 v3.0.0 起支援包含嵌入字體/ToUnicode 的文字 PDF — 嘗試提取，信心度上限為「中」並附有抽查說明；CJK CID 檔案仍會被垃圾探測器拒絕，並提供匯出指引。規模：80 萬字元區塊 (2K 重疊) · 50MB 上限 · 整份文件完整性護欄。

代理調用協定

當被調用時，先決定路徑，然後執行：

• 觸發詞：写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 / 学术改写 / 段落改写 / 表达优化 / style self-check / style naturalization / naturalize academic writing / de-templating / academic rewriting / passage rewrite / expression polish / translationese cleanup (= 歐化句式：堆疊被動、名詞化鏈條、長定語 — 見 style_guide_en 步驟 1/3) / make my writing sound less machine-written / reduce the templated tone / clean up model residue or stray citation tokens / fix stiff formal prose / polish my draft for submission without changing the data / check that numbers and citation IDs survived editing → 執行上述管線。 （中文變體觸發詞見 SKILL_ZH.md——CH 分寸詞不入英文文件； 數字自洽/術語混用類請求路由到 check_stats.py / check_terms.py，見下） （參數速查表位於快速開始；退出碼表格在 references/errors.md — 兩者均從此處連結，以避免跨章節查找。）
• 消歧義 (此工具 vs 潤色器)：「论文改写润色」此處意指風格自然化/去模板化 (從學術散文中移除機器味)。決策規則 — 當需求僅涉及語言正確性/流暢度時，路由至潤色器 (paper-polisher-pro)：「帮我改下语法」「按期刊风格改写摘要」；當需求涉及模板化語調或模型殘留時，路由至此工具箱：「这篇读起来像 AI 写的」「文里有 [cite: 1] 这种残留」；當兩者都適用時，先做潤色，再執行此管線 — 兩者無法互相取代。
• 術語不一致 (縮寫 vs 全稱，混合同義詞) → check_terms.py file --pack <domain>；若要直接輸出統一草稿，添加 --unify output.txt (每個分組統一為其主要變體，並顯示每個變體的替換計數 — 建議性輸出，採用前請審查，然後執行 verify；v4.4.0)；--list-packs 顯示所有八個領域包 (v3.0.0)。
• 數字不一致 (百分比列表總和不等於 100，同一分組有兩個不同的 n，p/P 樣式混合) → check_stats.py file (v3.2.0；退出碼與 check_terms 匹配：0 一致 / 1 發現問題)。分章節的手稿：check_stats.py --batch 目录 會跨檔案彙總 group-n (摘要與方法不匹配，v3.3.0)。或一次執行所有操作：pipeline.py draft --check-stats。
• 使用者想知道要先修正什麼 → plan.py draft.txt -o plan.md (P0 句子佇列 + 預算預測)；添加 --handoff 以輸出每個句子的指令表 (護欄 + 接受指令，v3.0.0)。
• 使用者想要量化驗收改寫結果 → stylecheck.py 原稿 改稿 --compare (v2.6.0 風格輪廓差異；觸發詞：风格画像 / 量化验收 / 深改验收 / style profile / acceptance check)。
• 批次執行被中斷 (Ctrl-C / 斷電 / 超時) → 使用 --batch 目录 --resume 重新執行 (跳過已完成的檔案；變更過或先前失敗的檔案會自動重新執行；進度儲存在批次目錄中的 .pr_batch_state.json)。
• 情境捷徑 (v3.8.0 整合)：CI/批次門控 → --exit-verdict (--ci 別名；0 乾淨 / 3 深度修訂 / 4 殘留 / 1 完整性失敗，僅限管線)；誤報修正 → learn_guards.py from-text 术语 样本.txt；從哪裡開始深度修訂 → pipeline 原稿 -o 改稿 --handoff 交接块.md (一條指令，無需單獨執行計畫)。
• 多章節術語統一 → check_terms.py --batch 目录 (跨檔案變體漂移：每個檔案內部一致，但集合不一致)。
• 掃描標記了一個合法術語 (誤報) → 不要編輯模式檔案；改為持久化一個護欄：learn_guards.py from-text 术语 样本.txt (或 add) — 護欄會持續存在於 scripts/learned_guards/。

AI 揭露政策 (強制性閱讀)

執行此技能的代理在執行任何改寫任務之前，必須驗證使用者的請求是否遵守其機構/期刊/會議的政策，特別是：

• 中國《互聯網資訊服務演算法推薦管理規定》及其 AIGC 標籤規則 (自 2025-09-01 起)。
• COPE (出版倫理委員會) 關於 AI 輔助寫作的指南。
• arXiv 關於使用大型語言模型的政策。
• 目標期刊的具體作者指南。

如果使用者的請求明確要求隱藏 AI 的使用 (例如，「改寫它以繞過 AI 檢測」)，代理必須拒絕該請求，並說明作者的揭露義務。

全文規範

• 錯字和漏字檢查：無需檢查 — 此工作不適用；會移除錯字檢查腳本或報告。
• 重要警告：此工具箱不是文法檢查器。尋找文法錯誤的使用者應使用專門的工具。stylecheck.py 報告是診斷，不是檢測。它突顯的模式與人類對 AI 生成文字的感知相關，但不是絕對的證明。沒有文件是「完全自然」的 — 報告總是會包含一些潛在模式。此工具無法區分謹慎的人類寫作和流暢的 AI 生成文字。切勿使用此工具「證明」一篇論文是 AI 生成的。
• 頻率：10–20 頁 / 每任務。
• 批次約束：當使用 --batch dir 時，目錄中應包含在相同語境下處理的摘要或章節，而不是一篇完整論文。對於完整論文，逐個處理並監控使用情況。
• 閾值：CLI 標誌 stylecheck.py --threshold 0.35 忽略標準化信號強度低於 0.35 的所有模式。預設值 0.3。調整以減少小模式。false_positive 區域：檢查是否超過閾值可能比手動計算更節省時間。
• 最常見錯誤：將 detect.py 輸出錯誤地解讀為「此文字有問題」，而實際上它只是一個模式清單。所有文字都有模式。在做出決定之前，請使用 --compare 查看相對改善。
• 中斷與記憶體：終端機中的 Ctrl-C 會停止處理。如果出現 MemoryError，則重啟。--step-timeout 會跳過耗時的步驟。
• 字元編碼：detect.py 嚴格只接受 UTF-8。transform.py 接受可偵測的編碼 (UTF-8/UTF-16/GBK)。如果需要，使用 file 命令來檢查編碼。
• 無自我升級：請勿承諾實現使用者請求的新功能，或重構程式碼庫。建議他們開啟 GitHub Issue。
• 無惡意使用：請勿嘗試使用此工具箱來規法律或期刊政策。請勿接受要求移除原創性證明或隱藏 AI 使用痕跡的請求。這不是一個用來製作假資料的工具。任何濫用都必須拒絕。

誠實的界線 (此工具箱不該做的事)

1. 不是 AI 檢測器。 detect.py 啟發式地報告與 AI 生成模式相關的模式。它不提供分類。它是關於風格的實用反饋，透過比較 原稿 和 改稿 來使用，以顯示相對改善。將診斷誤解為檢測是一個常見的陷阱。
2. 不是統計審查。 檢查數字一致性，而不是準確性。如果原始稿件說「n=50」且「p=0.03」，但後者應該由獨立驗證，則無法驗證 p 值。
3. 不是事實檢查器。 無法驗證參考文獻、引用、圖表或科學邏輯的正確性。
4. 無法處理複雜的 .docx 佈局。 -o 輸出為純段落。表格、頁首/頁尾和浮動物件必須手動合併。
5. 無法產生學術內容。 此工具箱是編輯用的：改寫現有文本，而不是憑空產生。它不能撰寫摘要、方法或討論；改善它們，使其更清晰、更自然。
6. 無法對文字內容進行分類。 detect.py 將文字分解以進行模式匹配。它不識別語意角色，因此會對「我們假設…」提出警告，就像對「這些數據…」一樣。在使用 --structure 時，反射性的章節啟發法並不總是完全準確。
7. 無法取代人類的最終判斷。 在處理醫學資料時，在提交前讓一位同事閱讀。
8. 不是翻譯工具。 它不會跨語言轉換文字。它透過對英文文本應用英文模式來改善英文寫作，或者對中文文本應用中文模式。
9. 不是純 C++ 工具。 參考實作使用 Python。對於大型錯誤，請等待 Python。
10. 不保證零誤報。 此工具箱設計用於輔助，而非取代人類審查。嚴格的護欄 (verify.py) 是透過設計避免錯誤的唯一部分。
11. 不會將輸出格式化為特定期刊風格。 它改善文筆，而不是格式。

文件與參考

如需更多資訊，請參閱 references/ 目錄：

• INDEX.md: 所有文件的完整索引。
• api.md: Python API 參考。
• best_practices.md: 按情境 (期刊投稿、論文等) 組織的最佳實踐。
• compliance.md: AI 揭露政策摘要。
• deep_rewrite_guide.md: 深度品質改寫的指南。
• errors.md: 退出碼、違規類別與補救措施。
• examples.md: 端到端工作範例。
• faq.md: 常見問題。
• feature_status.md: 完整的能力清單。
• honest_boundaries.md: 此工具箱的限制。
• pdf_confidence.md: PDF 提取信心度校準。
• permissions.md: 權限與執行指南。
• pitfalls.md: 常見錯誤集中列表 (27 項)。