TRPG Abbreviation Wrap

SKILL.md

---
name: trpg-abbr-wrap
description: >-
  將 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 處確認包裝後讀起來通順
- [ ] 跳過的舊版/備份檔若有裸縮寫，向使用者回報並詢問是否處理