docsor1212/humanize-ai-text

學術風格工具包 (humanize-ai-text)

學術與醫學寫作的雙語（中/英）風格自然化：找出僵硬、模板化或帶有機器味的模式，清理機械化殘留，提升清晰度與自然語域——每一步都設有完整性護欄。 閱讀導覽（30 秒快速指引；等同於 references/INDEX.md）：首次使用 → 快速入門 · 疑難排解 → 陷阱與錯誤 · CI/代理 → 自動化 · 限制 → honest_boundaries · 情境 → best_practices · 深度改寫 → deep_rewrite_guide · PDF 信心度 → pdf_confidence · 權限 → permissions · 程式化 → api。 一體兩層：機械清理（transform/pipeline，確定性）vs 品質修訂（代理遵循風格指南）——先執行 pipeline，閱讀報告，再決定哪些需要深度修訂。

一句話導航：需要文法/流暢度/期刊格式潤飾 → 使用潤飾工具（paper-polisher-pro）；去模板化、模型殘留清理、AI 風格自我檢查與改寫 → 使用此工具。兩者都需要？先潤飾，再執行此 pipeline。

功能狀態（v5.6.0）

⚠️ 行 = 實驗性（可能拒絕有效檔案；請審查輸出）。完整的每代功能列表已移至 references/feature_status.md；每個項目的詳細資訊位於 references/errors.md 和主題文件。穩定亮點（全部穩定，v1.0–5.6）：核心五項 · 感知區段 · 改寫計畫 · 學習防護 · 機器退出碼 · 區塊降解 · 批次恢復/並行隔離 · 跨檔案術語漂移 · 統計一致性防護 · 術語變體分組 · 編碼自動偵測 · 投稿自我檢查套件（--bundle） · pipeline --handoff · 驗證處方輸出 · docx 寫回 · 術語統一表 · EN 2026 訊號（模糊語 / rule-of-three / em-dash 密度 / 段落開頭） · 每區段焦點（--section） · CN 密度鏡像（破折號過度使用 / 公式化段落開頭） · 比較大檔案的分段掃描 · 每個訊號的解釋（為何標記） · 通用評分降權矩陣（全部 8 個結構群組） · 批次工作表 + 統計卡 · 命中行號（每個範例上的 L{line}） · 健康報告儀表板（bundle 2.0） · CN 特徵庫 v2 · handoff 行錨點 · 文件計數核對 · 儀表板操作清單 · 套件改寫表（09） · 批次修訂記錄 · 寫入清單自我證據（00_写入清单.json） · 比較行錨點 + 解釋 · 可列印報告 · 防護庫匯出/匯入。

功能	狀態	起始版本
⚠️ PDF 直接讀取 + 信心度自我報告（嘗試 embedded-font/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-09-01 生效）、期刊揭露政策和 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
數字一致性	百分比列表總和（依分區提示）/ 跨檔案群組 n / p 與 P 風格	不是統計審查——原始資料是權威	check_stats.py（--batch）

快速入門

如何用簡單的話提出需求（完整片語對照表的英文摘要請見 SKILL_ZH.md）：「去除這篇論文的 AI 味」/「這篇讀起來太模板化」/「清理 oaicite 和 [cite:] 殘留」/「告訴我哪些句子應該先改」/「檢查我的改寫有沒有破壞數字」/「給我一份風格報告」/「停止標記這個合法的術語」——這些分別對應到 pipeline、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 掃描整個目錄（pipeline 寫入 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 起支援文字 PDF，包括 embedded-font/ToUnicode——嘗試萃取，信心度上限為「中」並附有抽查註記；CJK CID 檔案仍會因垃圾探測而被拒絕，並提供匯出指引。規模：800K 字元區塊（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 → 執行上述 pipeline。（中文變體觸發詞見 SKILL_ZH.md —— 中文分寸詞不入英文檔案；數字自洽/術語混用類請求路由到 check_stats.py / check_terms.py，見下文）（參數速查表位於快速入門；退出碼表格在 references/errors.md —— 兩者均從此處連結，避免跨區段查找。）
• 消歧義（此工具 vs 潤飾工具）：「論文改寫潤色」在此專指風格自然化/去模板化（去除學術散文的機器味）。決策規則 —— 當需求僅涉及語言正確性/流暢度時，路由到潤飾工具（paper-polisher-pro）：「幫我改下語法」「按期刊風格改寫摘要」；當需求涉及模板化語氣或模型殘留時，路由到此工具包：「這篇讀起來像 AI 寫的」「文裡有 [cite: 1] 這種殘留」；當兩者都適用時，先潤飾，再執行此 pipeline —— 兩者無法互相取代。
• 術語不一致（縮寫 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 目錄 跨檔案彙總群組 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 完整性失敗，僅適用於 pipeline）；誤報處理 → learn_guards.py from-text 術語 樣本.txt；深度修訂從何開始 → pipeline 原稿 -o 改稿 --handoff 交接塊.md（單一指令，無需單獨執行 plan）。
• 多章節術語統一 → check_terms.py --batch 目錄（跨檔案變體漂移：每個檔案內部一致，但集合不一致）。
• 掃描標記了合法術語（誤報）→ 不要編輯模式檔案；改用學習防護來持久化：learn_guards.py from-text 術語 樣本.txt（或 add）——該防護

…

[為翻譯已截斷]