# Skill: 操作員選單文件 SOP

> 適用於大型機台遊戲（A8+ 閃電摩托、A9+ 狂野飆車等）的操作員手冊檢查與修正流程。

---

## 完整流程圖

```
用戶提供文件（Word/PDF）+ 基準版
        ↓
[file-reader] 階段 1：全文比對
        ↓
[file-reader] 階段 2：上下文一致性檢查
        ↓
[file-reader] 階段 3：圖文比對（逐頁）
        ↓
[file-reader] 階段 4：圖片數量比對
        ↓
[qa-checker] 驗證報告品質（未通過→打回補做）
        ↓
產出問題報告 → 用戶確認
        ↓
[word-bot] 階段 1：搜尋標記（回報匹配數+上下文）→ 用戶確認
        ↓
[word-bot] 階段 2：執行修改 + 對比報告 → 傳回修改後檔案
        ↓
用戶確認是否需要 review
        ↓
[file-reader] Review：驗證修改正確性 → 產出 Review 報告
        ↓
用戶做最終決策（通過 / 再修改）
```

---

## file-reader 檢查規範

### ⚠️ 執行標準（必讀）

**「逐字」= 每一句、每一個詞、每一個字母。不可以為省時間降低精度。**

每次比對報告的最前面必須附上 SOP 執行檢查表：
```
📋 SOP 執行確認：
☑️ Priority 1：逐段文字比對（共 X 段，全部完成）
☑️ Priority 2：名詞一致性（標題 vs 截圖 vs 內文，共 X 個名詞）
☑️ Priority 3：逐頁圖文比對（共 X 頁，subagent 分批完成）
☑️ Priority 4：表格/列表完整性
☑️ Priority 5：大圖數量比對
```
如果某個 Priority 沒做到，必須標 ❌ 並說明原因。

---

### Priority 1 — 逐字比對（需基準版）
- 每一行、每一個字和基準版比對
- 缺少任何一個字都要報告
- 不限於「明顯差異」
- **「逐字」= 每一段文字都要有對應，不是只比章節存不存在**
- 每段描述是否完整（有沒有漏翻、漏寫的句子）

### Priority 1.5 — 選單架構 vs 章節標題一致性
- **選單架構頁中的每個項目名稱必須和對應章節的實際標題逐字一致**
- 包含空格、編號、標點都要比對
- 只列出不符合的
- 格式：`| 編號 | 選單架構寫法 | 章節標題寫法 | 差異 |`
- 常見問題：空格差異（如 I/O按鍵 vs I/O 按鍵）、用字差異（安全 vs 壓力）、順序對調

### Priority 2 — 上下文一致性（三者一致）
- **每個章節必須比對「標題 vs 截圖 vs 內文」三者完全一致**
- 例：標題寫 "Coin Option Setting" → 截圖也必須是 "Coin Option Setting" → 內文也必須是 "Coin Option Setting"
- 差異包含：單複數（Setting vs Settings）、大小寫、空格、拼字
- 同一詞彙每次出現都必須一致（如「氮气」不能有地方只寫「氮」）
- 括號【】內文字必須和實際選單項目名稱完全一致
- 選單路徑中每個項目名稱都要核實

**必須逐章節產出對照表：**
```
| 章節 | 標題寫法 | 截圖顯示 | 內文寫法 | 結果 |
```

### Priority 3 — 圖文完全比對（必須用 subagent 讀取截圖）
- **必須用 pdftoppm 轉圖片，再用 subagent 逐頁讀取截圖中的文字**
- 不可以只比對純文字，必須實際「看」截圖圖片內容
- 逐頁掃描，截圖中每個可見文字都和正文比對
- 表格項目名稱、欄位標題和截圖一致
- 文案中「按下【X】鍵」和截圖底部操作提示一致
- 用 subagent 分批處理（每批 5-10 頁）
- **不可跳過任何頁面**
- **不可用「表格比對」代替「截圖讀取」— 兩者都要做**

### Priority 3.5 — LOGO/遊戲歸屬驗證（跨遊戲防錯）
- **每張截圖必須確認 LOGO 副標題是否屬於正確遊戲**
- A8+（閃電摩托）的辨識特徵：
  - LOGO 有「閃電摩托」四個字
  - 圖片有摩托車圖案
  - 版號 `G: A8PLUS.x.xx.xx`
- A9+（狂野飆車）的辨識特徵：
  - LOGO 只有「狂野飆車 DX PLUS」沒有「閃電摩托」
  - 圖片有賽車圖案
  - 版號 `G: A9Plus.x.xx.xx`
- **注意：兩個遊戲 LOGO 都有「狂野飆車」四個字，不能只看這四個字就判斷通過**
- **關鍵差異是「閃電摩托」副標題和摩托車/賽車圖案**
- subagent 指令必須明確要求辨識副標題和圖案，不可只看主標題
- 判斷方式（三重確認）：
  1. LOGO 副標題有無「閃電摩托」
  2. 圖片是摩托車還是賽車
  3. 版號 G: 欄位是 A8PLUS 還是 A9Plus
- 任何一項不符 → 標記 ❌ 報告

**⚠️ 精度要求（不可批量模糊判斷）：**
- **每次只給 subagent 1-2 頁**，不可一次給 10+ 頁批量處理
- subagent 指令只問一個問題：「這張截圖的 LOGO 有沒有『閃電摩托』字樣？圖案是摩托車還是賽車？」
- **不可用版號代替 LOGO 判斷**（版號可能被手動改過）
- 寧可慢也不可漏 — 精度優先於速度

### Priority 3.7 — 截圖語言 vs 手冊語言一致性
- **每張截圖中顯示的 UI 文字語言必須和手冊語言一致**
- 繁體手冊 → 截圖中不可出現簡體字（如「时间设定」「联机设定」）
- 簡體手冊 → 截圖中不可出現繁體字
- 英文手冊 → 截圖中不可出現中文
- 這和 Priority 3 不同：P3 看「圖文內容是否對應」，P3.7 看「截圖 UI 語言是否正確」
- subagent 讀取截圖時，順便確認截圖中的文字語言
- 常見錯誤：從簡體版複製過來忘了換截圖

### Priority 4 — 表格/列表/目錄完整性
- 表格每個項目名稱和說明逐字確認
- 列表編號連續且正確
- **目錄頁碼比對**：逐一確認目錄中每個章節標示的頁碼是否正確
  - 格式：`| 目錄項目 | 標示頁碼 | 實際頁碼 | 結果 |`
  - 實際頁碼以 PDF 為準（用 pdftotext 搭配 page break 確認）
  - 頁碼不符的要列出

### Priority 4.5 — 交叉引用正確性
- 掃描內文中所有「見第 X 頁」「參考 X 章節」「如第 X 頁所述」等引用
- 確認引用的目標頁碼/章節**實際存在且內容相符**
- 改版後最容易壞的就是這些引用（頁數變了但引用沒更新）
- 格式：`| 頁碼 | 引用文字 | 目標是否正確 |`

### Priority 5 — 圖片數量比對
- **只計算大圖**（寬度 > 400px 且高度 > 300px）
- 忽略小圖標、bullet point、裝飾圖
- 以各自文件為基準（不跨遊戲比較章節存不存在）
- 比對「文字描述的步驟數」vs「實際截圖數」
- 如果文字提到「如下圖」但沒有圖 → 報告缺圖
- **不只用 pdfimages 計算，必須用 subagent 逐頁「看」有幾張截圖**
- **每章的圖片要列出「是什麼截圖」（描述內容），不只報數字**
- 格式：`| 章節 | 圖片數 | 各圖描述 |`
- 不同遊戲有各自獨有功能（如 A9+ 有力回饋、安全帶；A8+ 有踏板感測）
- 不要因為一方有某章節而另一方沒有就標記錯誤
- 只比對「同一章節內部」是否完整

### Priority 5.5 — 版本資訊/聯絡資訊檢查
- 封面/頁尾的**版本號、日期、文件編號**是否正確且最新
- 版權聲明年份是否正確
- 客服電話/信箱是否對應正確區域（TW 版不放 CN 客服，反之亦然）
- 適用機型/軟體版本是否標明

### 報告格式
每個問題必須包含：
- 頁碼
- 確切位置（段落/表格/截圖）
- 錯誤內容
- 正確內容
- 問題類型（缺字/一致性/圖文不一致/編號錯誤/缺圖）

---

## word-bot 修改規範

### 兩階段流程

**階段 1：搜尋標記**
- 收到替換清單後，先搜尋所有目標文字
- 回報每項的匹配數量和上下文
- 匹配為 0 的標記「⚠️ 未找到」
- **等用戶確認後才進入階段 2**

**階段 2：執行修改 + 驗證報告**
- 執行替換
- 產出修改前後對比報告
- 附上修改後的檔案

### 圖片替換規範
1. 直接替換 docx zip 中的圖片檔案（不經過壓縮）
2. 調整 document.xml 中 `wp:extent` 和 `a:ext` 的 cx/cy 值
3. **保持高度不變、按新圖實際寬高比縮小寬度**
4. 確保不變形、不失真

### 圖片編輯能力
- 用 Pillow 在截圖上加文字（版號、標註）
- 用黑色矩形覆蓋錯誤文字
- 字型：Courier New 或 DejaVu Sans Mono
- 根據圖片尺寸等比例調整文字位置和大小

---

## Review 階段（file-reader）

當 word-bot 完成修改後，用戶可要求 review：

1. 逐項核對之前報告的問題是否都已修正
2. 確認沒有引入新問題
3. 產出 Review 報告

**報告格式：**
```
📋 Review 結果

✅ 已修正：
- #1 xxx ✅
- #2 xxx ✅

❌ 未修正或新問題：
- #5 仍然存在「xxx」

結論：✅ 全部通過 / ❌ 仍需修改
```

**用戶是最終決策者** — Review 結果僅供參考。

---

## 問題分類與處理

| 類型 | 處理方式 | 負責 |
|------|----------|------|
| 文字缺字/錯字 | word-bot 文字替換 | word-bot |
| 繁體字殘留 | word-bot 文字替換 | word-bot |
| 選單編號錯誤 | word-bot 文字替換 | word-bot |
| 圖片中文字錯誤 | word-bot 圖片編輯覆蓋 | word-bot |
| 截圖需重新擷取 | 用戶手動截圖 → word-bot 替換 | 用戶 + word-bot |
| 版號需加入截圖 | word-bot 圖片編輯 | word-bot |

---

## 截圖替換流程

1. file-reader 產出截圖清單（章節、步驟、操作說明、預期畫面、建議檔名）
2. 用戶按清單在遊戲中截圖
3. 用戶傳圖到 word-bot 頻道，標明對應位置（如 `p20_1.png`）
4. word-bot 用 zip 替換方式插入，保持比例不變形

---

## 涉及的機器人

| 機器人 | 角色 |
|--------|------|
| **general** | 協調、轉交、監控進度 |
| **file-reader** | 文件分析、比對、Review |
| **word-bot** | 文字修改、圖片編輯、圖片替換 |
| **qa-checker** | 驗證報告品質（未通過→打回補做） |

---

## 繁體化完整性檢查 SOP（A8+/A9+ 通用）

### 適用場景
操作員選單從簡體轉繁體後，確認無遺漏。

### 一次到位流程

```
用戶說「執行繁體化」
        ↓
[a8plus-debug / a9plus-debug] Step 1-4（自動執行）
        ↓
[qa-checker] Step 5（驗證沒改錯）
        ↓
用戶開遊戲確認 → 完成
```

### Step 1：opencc 全掃
- 從 TW prefab/scene 中提取**所有含中文的行**（不限特定欄位）
- 用 opencc s2twp 轉換
- 產出差異清單

### Step 1.5：套用已知替換清單（opencc 抓不到的）
- opencc 只能抓字形差異，語境/用詞差異需靠已知清單
- 搜尋以下所有詞彙是否殘留：

```python
known_replacements = {
    '機臺': '機台', '寄臺': '寄台', '空臺': '空台',
    '松開': '鬆開', '聯機': '連線',
    '回復出廠': '還原出廠', '網路連接': '網路連線',
    '后升': '後升', '后降': '後降', '后充氣': '後充氣',
    '后暫停': '後暫停', '后泄氣': '後洩氣', '后感測器': '後感測器',
    '稍后': '稍後', '校正后': '校正後', '完畢后': '完畢後',
    '成功后': '成功後', '右后': '右後', '左后': '左後',
    '平臺': '平台', '二維碼': 'QR Code',
}
```

- 如果找到 → 加入修改清單

### Step 2：排除白名單
- 用戶決定不改的項目排除（如：儀表/設備/查看/打開/地名等）
- 第一次執行時需用戶確認白名單

### Step 3：自動批量修改
- 將差異清單中非白名單的項目全部一次改完
- 修改方式：替換 unicode escape 形式的字串

### Step 4：重跑 opencc 確認 diff=0
- 修改完後立刻重跑 Step 1
- 如果除白名單外 diff=0 → 通過
- 如果仍有差異 → 繼續修正直到 diff=0

### Step 5：qa-checker 驗證
- 確認沒有改到不相關的檔案
- 確認白名單項目沒被誤改
- 通過 → 交付用戶

### Step 6：用戶開遊戲確認
- 視覺確認所有頁面文字正確
- opencc 覆蓋 90%，最後 10% 語境問題靠人眼

### opencc 使用方式
```python
import opencc
converter = opencc.OpenCC('s2twp')
result = converter.convert(original_text)
if result != original_text:
    # 有差異，潛在遺漏
```

### 注意事項
- 搜尋範圍：所有含中文的行（不只 selectionName/pageTitle）
- opencc 覆蓋率約 90%，最後 10% 語境問題需人眼確認
- 某些 diff 是 false positive（如「公里」的「里」）
- 維護一份白名單，確認 OK 的不再報
- A8+ 和 A9+ 共用此 SOP，只需調整提取路徑