TRPG Abbreviation Wrap

將 TRPG 規則/劇本/角色卡檔案中的英文縮寫（屬性、衍生值、DC/HP/AC 等）統一包裝為 「中文全稱（縮寫）」格式，供不認識縮寫的玩家與 GM 閱讀。支援 .md/.txt 與 .xlsx， 具冪等性（不會把已正確的「（ABBR）」再包一層），自動跳過舊版/備份/v1/draft 過渡檔。 適用於任何 TRPG 專案發布前的術語一致性清理。

TRPG 縮寫包裝工具（中文全稱（縮寫））

何時使用

• 使用者要求「檢查並替換規則/劇本中的英文縮寫」「統一術語格式」「讓玩家看得懂縮寫」。
• 發布前清理：玩家規則書、GM 規則書、劇本、設計文檔、Excel 角色卡文字標籤。

核心原則

• 目標格式：中文全稱（縮寫），例如 速度（SPD）、難度（DC）、生命值（HP）、防禦值（AC）。
• 跳過過渡檔案：檔名含 舊版/備份/v1/draft 者不處理（除非使用者明確要求）。
• 絕不處理 briefing_package/（AI GM 內部格式）。
• 冪等性優先：重複執行必須產生 0 變更，否則表示有 double-wrap 錯誤。

關鍵陷阱（必看）

1. Double-wrap 錯誤：移動力（MV） 被錯誤包成 移動力（移動力（MV））。 原因：用 （MV → （移動力（MV） 這種 regex，會命中已正確的 （MV） 形式。 解法：正確形式一定是 （ABBR）（ABBR 前必有 （）。所有替換都必須用 negative lookbehind (?<![（...]) 排除「ABBR 前面是 （」的情況。
2. 空間分隔的屬性形式：速度 SPD、| **速度** | SPD |、SPD 8、GUT 檢定、 NEG 縮寫 都是裸縮寫，需用 regex (?<![（一-鿿])ABBR 統一包裝。

替換規則（依序，全部冪等）

⚠️ 縮寫對照表（FULL）是「依專案替換」的，不是通用常數。 下方僅為範例； 執行前必須先用 Grep 掃描目標檔案，確認該專案實際使用的縮寫與全稱，再填入 正確的 FULL 映射。不同 TRPG 專案（武俠/修仙/恐怖/SCP…）屬性與衍生值縮寫 完全不同，套用錯誤的映射會毀掉術語。

範例 A：心理恐怖專案（原有預設）

FULL = {SPD:速度, PER:知覺, GUT:膽量, TEC:技術, NEG:交涉, MV:移動力, FS:前兆感知, PT:恐慌閾值, TR:時間抗性, HP:生命值, DC:難度, AC:防禦值}

範例 B：天機·修真心（玄幻修仙 d100 專案）

FULL = {GUG:根骨, WUX:悟性, SHS:神識, RSS:肉身, LIL:靈力, SHF:身法, JIY:機緣, DAX:道心, HP:生命值, TN:目標值, MoS:成功度, MoF:失敗度, DC:難度, GS:大成功上限, CR:挑戰等級, EL:遭遇等級, AC:防禦值, AOE:範圍效果}

注意：該專案 肉身 同時出現 RSS 與 ROU 兩種縮寫，兩者皆映射到 肉身。

不包裝：GM / NPC / PC / BOSS / TRPG / RP / Lv.（角色與等級通用記法，使用者慣用）。

1. 裸括號+空白：（ABBR → （FULL（ABBR） （正確形式 （ABBR） 無空白，不會命中）
2. 通用屬性「X ABBR 空白」：regex (?<![（一-鿿])ABBR → FULL（ABBR） 一次涵蓋：速度 SPD、SPD 8、GUT 檢定、NEG 縮寫、表格 **速度** | SPD。
3. 通用代幣 HP/DC/AC：regex (?<![（])ABBR\b → FULL（ABBR） 涵蓋 交涉 DC 10 → 交涉 難度（DC） 10、玩家 HP 降至 → 玩家 生命值（HP） 降至。
4. 「檢定ABBR」（中文緊接無空白）：檢定ABBR → 檢定 FULL（ABBR） ⚠️ 必須排在規則 3 之前，否則會變成 檢定難度（DC）（缺空白）。
5. 半形括號斜槓清單：(SPD/PER/GUT/TEC/NEG) → （速度（SPD）/知覺（PER）/膽量（GUT）/技術（TEC）/交涉（NEG））
6. 設定字串 / 組合字串（dice 設計文檔）：SPD 5 / PER 5 / ... 與 高 SPD/PER、高 GUT/TEC、低 GUT、低 SPD 用明確字串替換。

XLSX 處理

• 用 openpyxl.load_workbook 讀取，逐 cell 對字串值套用上述替換，非字串 cell 跳過。
• wb.save() 會保留格式（與讀取時一致）。
• Excel 中常見裸形式：檢定DC（中文緊接），由規則 4 處理。

驗證腳本（每次修改後必跑）

掃描所有目標檔案，預期 0 命中：

python

import re
ABBR=['SPD','PER','GUT','TEC','NEG','MV','FS','PT','TR','HP','AC','DC']
BARE = re.compile(r'(?<![（\u4e00-\u9fff])(?:'+'|'.join(ABBR)+r')\b')
CN   = re.compile(r'[一-鿿](?:'+'|'.join(ABBR)+r')\b')      # 中文緊接
PB   = re.compile(r'(?<![一-鿿])（(?:'+'|'.join(ABBR)+r')\b') # 裸括號（前無中文）
# 對每個 .md/.txt 與 .xlsx cell 掃描上述三個 pattern；有任何命中即代表還有裸縮寫。

注意：PB pattern 若誤報 速度（SPD），是因為 pattern 沒排除 （ 前的中文， 修正為 (?<![一-鿿])（ABBR 即可（正確形式 中文（ 前是中文，不會命中）。

交付檢查清單

• 所有目標 .md/.txt 經驗證腳本掃描為 CLEAN
• 所有目標 .xlsx 經驗證腳本掃描為 CLEAN
• 重跑腳本 --dry 顯示 TOTAL CHANGED: 0（冪等確認）
• 實際 Read 2~3 處確認包裝後讀起來通順
• 跳過的舊版/備份檔若有裸縮寫，向使用者回報並詢問是否處理