# SKILL-022 — QA 測項展開工具

> 將 QA 規格書（.xlsx）的指定規格行展開為測試項目，產出 A0 格式的 Excel / Google Sheet 測試項目檔。

---

## ⛔ 核心紀律（絕對不可違反）

以下規則優先於所有其他規則。違反任何一條 = 產出無效。

1. **忠於規格** — 規格列幾個就展幾個，不合併、不發明、不省略
2. **不確定必標記** — 推測標灰色[?]，無法推測標紅[待確認]，禁止偽裝確定
3. **三步缺一不可** — 確認後必做：測項 Sheet + ref 更新 + 規格書補充欄
4. **UI 文案原文不動** — 引號內禁止繁簡轉換
5. **步驟白話可執行** — 看一遍就知道做什麼，預期結果必須具體可驗證
6. **禁止概括用詞** — 禁止「正常」「正確」「沒問題」「等」「相關」
7. **連結即時驗證** — 禁止憑記憶填 Row 號，必須當下搜尋確認
8. **隱藏行掃描不可跳過** — Step B 必做，禁止只用 values.get 就展開
9. **展開粒度** — 有子功能的章節至少 3 條測項，只展 1 條「標題顯示」= 未完成

---

## 概述

本技能將使用者指定的 .xlsx 規格書指定行，展開為符合 A0 範本格式的測試項目，輸出帶有正確樣式的檔案。所有遊戲專屬資料（硬體清單、操控用語、數量基準）均由獨立的 ref 檔案提供，主文不包含任何遊戲專屬硬體名稱。

**觸發關鍵字：** 「展開測項」「把規格展開成測試項目」「產出 Excel 格式」「請把 XXX 規格書第 YY 項展開測項」

**適用範圍：** 後台規格書、操作員選單規格、跨屏規格書、流程規格等任何 .xlsx 格式規格書。

---

## 模式判斷邏輯

```
收到請求 → 有 ref 嗎？
├── 沒有 → 模式 A（首次建立）
└── 有 → 版本一致嗎？
      ├── 一致 → 模式 B（日常展開）
      └── 不一致 → 模式 A'（更新 ref）
```

---

## 一步到位使用流程

### 用戶只需要做：
1. 貼規格書連結
2. 說「展開測項」
3. 選章節（或說「全部」）

### Bot 自動做：
- 偵測遊戲名稱（偵測後回報確認：「偵測到是 XX，對嗎？」）
- 偵測語言（簡/繁/英）
- 判斷有無 ref → 有就模式 B，沒有就模式 A
- 掃描規格書結構
- 列出章節讓用戶選（預設全部，用戶可取消不要的）
- 展開測項
- 在規格書自動建新分頁（命名：「{遊戲名} {章節} 測試項目」）
- 加 Summary + 標記 + 連結
- 回報結果 + 給 Sheet 連結

### 預設行為
- 測項建在規格書的新分頁中（不另開檔案）
- 如果用戶想用別的表單，問：「要建在規格書新分頁嗎？或者你有其他表單？」

---

## 模式 A：首次建立 ref

當目標遊戲尚無對應的 ref 檔案時，執行此流程。

### A-1：確認可用資料來源
- 手冊（PDF/紙本）
- 規格表（Google Sheets / .xlsx）
- 實機確認
- 口述

### A-2：有無相似機台可參考？
- 有 → 複製現有 ref 為基礎，再修改差異
- 沒有 → 從零建立

### A-3：上傳規格書/手冊
用戶提供規格資料，Bot 接收並解析。

### A-4：提取硬體清單 + 格式辨識
Bot 從資料中提取：
- I/O 裝置清單
- 操控用語
- 硬體測試子選單
- 燈光/動感平台項目
- 系統設定選單
- 獨有功能

### A-5：差異比對（若為複製）
如果是從其他 ref 複製的，列出和原 ref 的差異讓用戶確認：
- 新增了什麼
- 刪除了什麼
- 修改了什麼

### A-6：用戶確認硬體清單
用戶逐項確認提取結果是否正確。

### A-7：產出 ref 檔案
產出 `SKILL-022-{機台代號}-ref.md`，標注信心等級：

| 信心等級 | 來源 |
|---------|------|
| 🟢 高 | 實機確認 |
| 🟡 中 | 手冊/規格書 |
| 🔴 低 | 口述/推測 |

### A-8：冒煙測試
立刻試展 2～3 項規格，確認 ref 可正常使用。若有問題回到 A-6 修正。

---

## 模式 A'：更新 ref

**觸發條件：** 用戶規格版本 ≠ ref 中記載的版本

### A'-1：自動比對
比對新規格 vs 現有 ref，列出差異清單。

### A'-2：用戶確認
用戶確認哪些是：
- 新增項目
- 刪除項目
- 修改項目

### A'-3：更新 ref
更新 ref 檔案，保留版本紀錄（在「資料來源」區塊記錄更新歷程）。

### A'-4：回到模式 B
ref 更新完成後，正常執行日常展開。

---

## 模式 B：日常展開

### B-1：用戶指定遊戲與範圍

**必填：**
- 遊戲/機台
- 章節（從 ref 清單勾選）

**選填：**
- 本次重點（如「這次只看音量設定」）
- 變更項目（如「這版新增了 XXX」）
- 上次未通過清單（未過項目自動提升優先度為「高」，並新增迴歸測項）

有選填資訊 → 自動調整優先度 + 新增迴歸測項。

### B-2：載入 ref 並確認
Bot 載入對應 ref 檔，回報：
```
已載入 [{遊戲代號} v{版本}]，確認？
```
用戶確認後繼續。若版本不一致，轉入模式 A'。

### B-3：列出章節清單（強制勾選）
Bot 列出該 ref 中的章節清單讓用戶勾選要展開的範圍。

**⚠️ 不接受自由輸入。** 必須從清單中選擇。
**⚠️ 若用戶說「全部」，需二次確認：** 「確定要全部展開嗎？包含 XX 項。」

### B-4：讀取規格
使用 `scripts/read_spec.py` 讀取指定頁籤指定行：
```bash
python3 scripts/read_spec.py "<規格書路徑>" --sheet "<頁籤名>" --rows "65,66,100-110"
```

**⚠️ 必須先執行結構掃描 + 隱藏行/灰色掃描（防止缺漏）：**

**Step A：讀取內容**
1. 用 `spreadsheets.values.get(range="'{頁籤名}'")` 讀取整份頁籤 — **不帶欄位/行數限制**

**Step B：掃描隱藏行和灰色行（必做，不可跳過）**
2. 用 `spreadsheets.get(includeGridData=True)` 取得格式資訊
3. 掃描 `rowMetadata` 找出所有隱藏行（hiddenByUser / hiddenByFilter）
4. 掃描 `effectiveFormat.backgroundColor` 找出所有灰色背景行
5. 建立「隱藏行清單」和「灰色行清單」

**Step C：建立章節目錄**
6. 從非隱藏行中提取所有章節標題（不管在哪一欄）
7. 建立完整章節目錄清單
8. 回報用戶：「本頁籤共 N 個章節：[清單]，是否全部展開？」
9. 如有隱藏行，同時回報：「⚠️ 偵測到 X 個隱藏行，已排除不展開。」

**Step D：展開**
10. 用戶確認範圍後才開始逐章節展開
11. 展開時：隱藏行的內容 → 放到 ⏭️ 跳過區；灰色行的內容 → 標 [灰色規格]
12. 展開完後比對：展開測項涵蓋的章節數 = 目錄中的章節數，有落差就報錯

**⚠️ Step B 不可跳過。每次展開都必須執行隱藏行掃描。**
**⚠️ 禁止只用 values.get 就開始展開（它讀不出隱藏狀態）。**
**⚠️ 禁止自行限制讀取範圍（如 A1:Z500）。一律讀整份頁籤。**

讀出後辨識：
- 哪些行是「規格條目」（有編號或功能說明）
- 哪些是補充說明 / 圖片位置
- 注意 `0518新增`、`NEW`、`刪除`、`XX專屬` 等標記
- 強制確認規格書版本號/日期

### B-4.5：規格判讀 Checklist

讀取規格後，逐項檢查以下要素：

#### 🔴 必要（缺少就不能展開，停下來請用戶補充）
- □ 功能/項目名稱 → 填「項目」欄
- □ 操作步驟或觸發方式 → 填「步驟」欄
- □ 預期結果/正確行為 → 填「預期結果」欄

#### 🟡 建議有（沒有只能展基本驗證，標 [規格不完整]）
- □ 設定值範圍 → 展最大值/最小值測試
- □ 預設值 → 展恢復測試
- □ 限制/例外 → 展異常案例

#### 🟢 加分（提高品質）
- □ UI 截圖 → 輔助確認操作位置
- □ 編號/層級 → 備註欄追溯
- □ 版本/區域標記 → 判斷適用範圍

#### ⚙️ 自動帶入（不需規格提供）
- 類別 ← ref 層級結構
- 測試目的 ← 模板自動生成
- 優先度 ← 預設規則 + 用戶覆寫
- 執行人員/結果/日期 ← 執行時填

**判讀結果：**
- 缺 🔴 → 照常展開，步驟和預期結果用紅色粗體標記 `[待確認] 需要提供：XXXX`，並加上使用者操作指引 `（請將此段刪除，替換為已知規格，完成後回報「改好了」）`
- 缺 🟡 → 照常展開，在相關描述後面接 [?] 疑慮 + 選項
- 缺 🟢 → 正常展開

**⚠️ 不管規格完不完整都要展開測試項目，不可以跳過不開。** 缺的地方用標記告訴用戶需要補什麼。

### B-5：展開測項

**設計原則：**
- 每條規格展開 1～3 個測試項目
- 「正常流程」+「最大最小值/例外」→ 各展一項
- 多個子條件可合併 → 一項，步驟中逐一列出
- 新功能 → 至少一項驗證存在性 + 一項驗證行為

**⚠️ 展開紀律（最重要規則）：**

**只展開規格書中有寫到的內容。規格沒寫的不要自己加測試項目。**

- ✅ 規格寫了 → 展開
- ❌ 規格沒寫 → 不展開，不發明
- ⚠️ 規格暗示但沒明確寫 → 預期結果標 [待確認]，讓用戶判斷

禁止：
- 禁止根據「常識」自己加測試項目
- 禁止把其他遊戲的規格混入
- 禁止推測功能存在（規格沒提到的功能就不測）
- 禁止在規格書已寫明的內容上標 [?]（規格有寫就是 ✅，不是 🟡）
- 禁止合併/濃縮規格項目（規格列幾個就寫幾個，一個不多一個不少）

### 禁止合併/濃縮規格項目

規格書列出的選單項目、子項目、測試項目，必須完整逐一列出。

禁止：
- ❌ 把「右前升测试」+「右前降测试」合併成「右前升降」
- ❌ 把 13 個項目壓縮成 6 個
- ❌ 自行判斷「這些可以合在一起」

規則：**規格列幾個就寫幾個，一個不多一個不少。**

**粗略/詳細判斷規則：**

| 規格詳細程度 | 判斷標準 | 展開方式 |
|-------------|---------|---------|
| 粗略 | 只有功能名稱，沒有設定值範圍/步驟說明/預期結果 | 展開 1 項基本驗證 |
| 詳細 | 有具體設定值、操作步驟、預期行為描述 | 展開正常 + 最大最小值（2～3 項） |

**操控用語替換規則：**
- 展開時，所有操作描述必須使用 ref 中的「正確用語」
- 替換條件：描述「玩家操作」或「操作員選單操作」時替換
- 不替換情境：描述物理零件維修/硬體結構時保留原文
- 不替換情境：連線測試中提到對方機台名稱時保留
- 若 ref 中找不到對應用語 → 保留原文，備註加「[待確認用語]」

### B-6：自動驗證

| 驗證項目 | 方式 |
|---------|------|
| 數量驗證 | ref 中子項目數 vs 展開數，有落差則列出具體漏哪個 |
| 用語驗證 | 確認鍵名稱是否正確，掃描 ref 中「禁用詞」欄位 |
| 漏項檢查 | 比對 ref 清單和展開結果，有落差問用戶「刻意跳過還是補上？」 |
| BAR 提示文案 | 測項中的選單操作提示須與 ref 中定義的確認鍵一致 |

### B-7：產出到 Google Sheet

**Sheet 產出規則：**

| 情境 | 行為 |
|------|------|
| 第一次展開這個章節 | 建新分頁，名稱 = 「{遊戲} {章節名}測試」 |
| 同章節分批展開（如先做 5 項確認，再做剩下 5 項） | **追加到同一分頁**，依原規格順序排列，不開第二個分頁 |
| 同章節完全重新展開 | 問用戶：「已有舊的，要覆蓋還是追加？」 |
| 多章節一起展開 | 每章節各自一個分頁 |
| 不確定時 | 直接問用戶「要追加到現有分頁還是開新的？」 |

**⚠️ 核心原則：同一個測試項目章節只有一個分頁，避免同一測項開好幾個分頁。**

亦可使用 `scripts/write_excel.py` 輸出本地 Excel：
```bash
python3 scripts/write_excel.py items.json 輸出路徑.xlsx --format standard
```

### B-8：用戶確認（必要步驟）

**⚠️ 不可跳過。** 告知用戶：
- 共展開幾項測試項目
- 對應哪些規格行
- 使用的 ref 版本
- 驗證結果（通過/有落差）
- 等待用戶回覆「確認」後才算完成

**展開完成回覆格式：**

```
📊 本次展開：{N} 項 | ✅ 可直接測試：{X} 項 | 🟡 需確認後可測：{Y} 項 | 🔴 無法測試：{Z} 項

✅ 已展開 {遊戲代號} {章節名} {N} 項。

🟡 以下 Y 項有推測值 [?]，請確認：
- #{編號} {項目名}：{推測內容摘要}

🔴 以下 Z 項缺關鍵資訊 [待確認]，需要你提供：
- #{編號} {項目名}：{需要什麼資訊}

對的就刪 [?]，錯的改掉，缺的補上。改好跟我說「改好了」。
```

如全部為 ✅，則只顯示第一行統計 + 第二行。

---

## 規格判讀 Checklist（快速參照）

| 等級 | 要素 | 對應欄位 | 缺少時的行為 |
|------|------|---------|-------------|
| 🔴 必要 | 功能/項目名稱 | 項目 | 停下來問用戶 |
| 🔴 必要 | 操作步驟或觸發方式 | 步驟 | 停下來問用戶 |
| 🔴 必要 | 預期結果/正確行為 | 預期結果 | 停下來問用戶 |
| 🟡 建議 | 設定值範圍 | 步驟+預期結果 | 只展基本驗證，標 [規格不完整] |
| 🟡 建議 | 預設值 | 預期結果 | 無法展恢復測試 |
| 🟡 建議 | 限制/例外 | 步驟+預期結果 | 無法展異常案例 |
| 🟢 加分 | UI 截圖 | — | 正常展開 |
| 🟢 加分 | 編號/層級 | 備註 | 正常展開 |
| 🟢 加分 | 版本/區域標記 | 備註 | 正常展開 |

---

## 測試目的生成規則

| 測試類型 | 模板 | 範例 |
|---------|------|------|
| 基本驗證 | 「驗證 {項目名} 操作後 {預期結果} 正確」 | 驗證音量設定調整後數值正確更新 |
| 最大最小值測試 | 「驗證 {項目名} 設定到最大值({max})和最小值({min})時能正常運作」 | 驗證群組編號設定到最大值(99)和最小值(0)時能正常運作 |
| 異常測試 | 「驗證 {項目名} 在 {例外情境} 時正確處理」 | 驗證網路斷線時版本更新正確處理 |
| 恢復測試 | 「驗證 {項目名} 恢復預設後回到 {預設值}」 | 驗證音量設定恢復預設後回到 50% |

**⚠️ 禁止寫法：**
- ❌「驗證邊界值行為正確」
- ❌「驗證邊界條件下系統正常」

**✅ 正確寫法：**
- ✅「驗證設定到最大值(99)和最小值(0)時能正常運作」
- ✅「驗證超過允許範圍時系統正確拒絕」

Bot 根據規格內容自動選擇模板，填入對應欄位值。

---

## 優先度預設規則

| 優先度 | 適用項目 |
|--------|---------|
| 高 | 投幣/金流、連線、安全裝置、動感平台啟停 |
| 中 | 遊戲設定、音量、燈光、I/O 基本功能 |
| 低 | 外觀、資訊顯示、版本號確認 |

**自動調整邏輯：**
- Bot 根據類別自動帶入預設值
- 用戶可覆寫任何優先度
- 若用戶提供「上次未通過清單」→ 未過項目自動提升為「高」
- 若用戶標注「本次重點」→ 相關項目優先度 +1 級

---

## 防範常見錯誤

| 錯誤類型 | 防範方式 |
|---------|---------|
| 給錯版本規格書 | B-4 強制確認版本號/日期 |
| 說「全部展開」 | B-3 列清單勾選，「全部」需二次確認 |
| 展開後不看直接用 | B-8 用戶確認為必要步驟，不可跳過 |
| 手動改了 Sheet 沒更新 ref | 提醒「是否同步更新 ref？」 |
| 混用不同遊戲 ref | B-2 載入後強制回報確認 |
| 用語混用（複製忘改） | B-6 自動掃描禁用詞 |
| 規格讀取截斷（漏章節） | B-4 用 API 讀整份頁籤（不限制欄位/行數範圍），禁止自行限制如 A1:Z500 |
| 引用隱藏行內容 | B-4 Step B 必須用 includeGridData=True 掃描隱藏行，每次都做不可跳過 |
| 規格有寫卻標 [?] | 展開紀律：規格書有寫的內容一律 ✅，[?] 只用於規格完全沒提到的推測 |
| 推測混入確定結果 | 展開紀律：推測一律灰色「推測：XXX」+ 選項行，不可混入黑色預期結果 |
| 自行濃縮規格項目 | 禁止合併/濃縮：規格列幾個就寫幾個，一個不多一個不少 |
| 預期結果硬寫數量 | 禁止寫 Bot 自己數的數字，改用列舉所有項目名（見下方規則） |

### 展開前防呆

1. **權限檢查**：展開前先測試 Sheet 寫入權限，失敗就提醒用戶授權
2. **偵測確認**：偵測遊戲/語言後一律確認一句（不自動跳過）
3. **分批展開**：超過 50 項分批處理（每批最多 50 項），完成一批再下一批
4. **分頁重複檢查**：建分頁前檢查同名是否已存在，已有就問「覆蓋還是追加？」
5. **模式 A 確認**：建 ref 後必須用戶確認才繼續展開

### 項目清單列舉規則（禁止硬寫數量）

預期結果中涉及「項目清單」時：
- **列舉所有項目名稱**（每項一行），不寫總數
- 來源：從規格書（或結構化摘要）直接抄錄項目名，不自己歸納
- 簡體 UI 文案用『』包裹

**禁止：**
- ❌ 「顯示 8 個設定項目」（Bot 自己數的數字）
- ❌ 「共 N 項」「部分項目」
- ❌ 用 / 分隔在同一行（如「『A』/『B』/『C』」）

**正確：**
```
✅ 由上而下顯示以下項目：
『投币设定』
『彩票設定』
『音量设定』
『离开』
```

**唯一例外：** 規格書明確定義的數字可以用（如「最多支援 4 台連線」= 規格寫的值，不是 Bot 數的）

**流程保障：**
1. qa-sheet-worker 從規格書讀取完整項目清單（排除隱藏/已移除）
2. qa-test-expander 直接抄錄到預期結果（不自己數）
3. Self-Check 比對：預期結果中的項目名 = 摘要中的清單

---

## 格式不明的 fallback

當規格格式無法辨識（截圖標注型/散落多份文件/非結構化）：
1. 先提取所有可辨識的選單項目名稱
2. 逐項詢問用戶「這個項目的子選單/設定值有哪些？」
3. 逐步建構結構化 ref
4. 建構完成後回到模式 B

---

## 多區域版本處理

以最完整版本為 ref 基準（通常 CN 或 FA），差異用標記：

| 標記 | 意義 |
|------|------|
| `[CN-only]` | 僅中國版有 |
| `[not-in-TW]` | 台灣版沒有 |
| `[FA-only]` | 僅外銷版（Foreign Area）有 |
| `[not-in-FA]` | 外銷版沒有 |

---

## 展開粒度規則

### 最低標準
一個有子功能的章節必須至少展開以下層級：
- 進入該功能的驗證（標題/UI 正確性）
- 每個子設定項的操作驗證
- 預設值/邊界值驗證（規格有寫的話）
- 異常操作/錯誤提示驗證（規格有寫的話）

### 禁止
- ❌ 一個章節只展一條「標題顯示 XXX」
- ❌ 規格書有 10 個子功能但只展 1-2 條
- ❌ 把多個子功能壓成一條步驟

### 判斷方式
- 有子功能的章節 → 最少 3 條測項
- 某章只有 1 條 → 重新檢視是否漏展子功能
- 規格書列了 N 個子項/狀態/提示 → 至少展 N 條

### 情境對照表

| 情境 | 展開方式 |
|------|---------|
| 連線組合測試（機台A × n + 機台B × m） | 每個有效組合 = 1 條測項 |
| 動感平台各方向測試 | 每個方向 = 1 條測項（不合併） |
| 燈光測試各燈項 | 每個燈項 = 1 條測項 |
| 音量各子項（總音量/待機/選單...） | 合併為 1 條，步驟中逐一列出 |
| I/O 各按鍵 | 合併為 1 條，預期結果中列出全部項目 |
| 版號各子項（M/G/T/L/N） | 每個版號 = 1 條測項 |

### 分批展開限制
- ⚠️ 一次展開請求不超過 3 個章節（有 qa-sheet-worker 協作時可提高到 5-6 個）
- 超過上限 → Bot 自己控制分批節奏，用戶不需要手動管
- 每個章節都要深入讀完所有規格再展開
- 每輪完成 Self-Check 後再進下一輪

### Context 監控
- Context > 60%：提醒用戶「建議完成當前章節後暫停」
- Context > 70%：建議 replace 後再繼續
- 不要在 context 高壓下做大量展開（品質會退化）

---

## 例外處理

| 情境 | 處理方式 |
|------|---------|
| 測項同時提到兩台機器（如連線測試） | 標記 [共用]，步驟中明確列出各機台的操作 |
| ref 中找不到對應用語（新功能/新硬體） | 保留原文，備註加「[待確認用語]」 |
| 用語替換後語句不通順 | 人工微調，但不改變測試意圖 |
| 規格書中已標記機台專屬 | 直接採用規格書標記 |
| 不確定某功能是否共用 | 標記 [待確認]，不猜測 |

---

## 機台標記規則

備註欄中加入以下標記之一：

| 標記 | 條件 |
|------|------|
| `[{遊戲代號}專用]` | 僅適用該機台的功能（如獨有硬體） |
| `[共用]` | 所有機台操作步驟和預期結果完全相同 |

判斷邏輯：
- 步驟和預期結果完全一樣 → [共用]
- 目的相同但步驟/預期值不同 → 拆成兩條，各標對應機台專用

---

## 輸出格式

### standard 格式（11 欄）

| 欄位 | 填寫方式 |
|------|---------|
| 編號 | 狀態標記 + 兩位數字（✅ 01、🟡 02、🔴 03） |
| 類別 | 規格所在頁籤名或功能模組名 |
| 項目 | 簡短功能描述（不超過 3 行） |
| 測試目的 | 「驗證…」開頭，1 句話（依測試目的生成規則） |
| 步驟 | 編號列表：1. xxx / 2. xxx / 3. xxx |
| 預期結果 | 編號列表，每條對應一個可觀察結果。直接寫「最大值/最小值」+ 具體會發生什麼，不寫「邊界值」 |
| 執行人員 | 空白 |
| 測試結果 | 空白 |
| 測試日期 | 空白 |
| 備註(規格參照) | HYPERLINK 超連結：`規格書名─頁籤名規格第X項 [機台標記]`（點擊跳轉規格書）+ 換行接推測依據（如有） |
| 優先度 | 依優先度預設規則自動帶入，用戶可覆寫 |

### cutscene 格式（12 欄）
同上，但「備註(規格參照)」拆成兩欄：備註（J）+ 規格參照（K，HYPERLINK）+ 優先度（L）

**預期結果寫法：**
- ❌「邊界值 99 時系統正確處理」
- ✅「設定 99（最大值）→ 可以正常儲存；嘗試設定 100（超過最大值）→ 系統不允許」

原則：不寫「邊界值」，直接寫「最大值/最小值」+ 具體會發生什麼。

### 格式選擇
- 提到「跨屏 cutscene 頁籤」→ `cutscene`（12 欄）
- 其他所有情況 → `standard`（11 欄）

---

## 備註欄位格式範例

```
=HYPERLINK("https://docs.google.com/spreadsheets/d/{ID}/edit#gid={GID}&range=A68", "後台規格書─機台選單設置規格第68、69項 [共用]") & CHAR(10) & "（0518新增─篩選欄位連線版本捲軸小視窗）"
```

```
=HYPERLINK("https://docs.google.com/spreadsheets/d/{ID}/edit#gid={GID}&range=A333", "操作員選單規格─系統設定規格第333~343項 [A9+專用]") & CHAR(10) & "（2026/5/22新增─超過最大連線數錯誤訊息觸發條件）"
```

顯示效果：
- 第一行是藍色可點擊超連結（跳到規格書對應行）
- 第二行是灰色補充說明

---

## 常見規格書與頁籤

| 規格書 | 常用頁籤 |
|--------|---------|
| A8A9Plus_後台規格書.xlsx | 操作須知、機台營收、機台選單設置、玩家數據 |
| A9_PLUS操作員選單規格.xlsx | 系统设定、联机测试页 |
| A8A9Plus_跨屏&PV規格書.xlsx | 跨屏需求規格、A9+跨屏Cutscene驗證表單 |
| 彩票相關規則.xlsx | 詳細規格、彩票UI規格 |
| A9++++流程.xlsx | Ingame |

---

## 涉及腳本與機器人

### 腳本

| 腳本 | 用途 |
|------|------|
| `scripts/read_spec.py` | 讀取 .xlsx 規格書指定頁籤/行 |
| `scripts/write_excel.py` | 產出帶樣式的 A0 格式 Excel |

### 機器人（2 Agent 協作架構）

| 機器人 | 角色 |
|--------|------|
| **qa-test-expander**（主腦） | 展開決策 + 生成測項 + 標記 + 白話化 + Self-Check + 修正 + 回報用戶 |
| **qa-sheet-worker**（讀寫工） | 讀取規格書 + 寫入 Sheet + 格式化 + 連結驗證 + 補充欄寫入 |

### 協作流程
```
用戶 → qa-test-expander：「展開 XX 章節」
qa-test-expander → qa-sheet-worker：「讀取規格書，回傳結構化摘要」
qa-sheet-worker → qa-test-expander：{ 子項清單, 規格內容, 隱藏行, Row }
qa-test-expander：生成測項 + Self-Check
qa-test-expander → qa-sheet-worker：「寫入測項 + 格式化 + 連結驗證」
qa-sheet-worker → qa-test-expander：「完成」
qa-test-expander → 用戶：回報結果
```

### 分工原則
- qa-test-expander 不讀原始規格、不寫 Sheet（交給 worker）
- qa-sheet-worker 不做展開判斷，嚴格按主腦給的數據寫入
- qa-sheet-worker 的紀律只有 3 條：不遺漏隱藏行、不修改內容、連結即時驗證

---

## CN/FA 版本必問規則

展開時如果規格書有 CN 和 FA 兩個版本的文案，**必須先問用戶：**

「這次要展開 CN（簡體）的測試項目還是 FA（英文）的？或是兩個都要分開展？」

### 禁止
- ❌ CN 和 FA 混在同一份測試項目中
- ❌ 不問就自行決定展哪個版本

### 如果兩個都要
- 分成兩個分頁（如「密碼設定測試項目(CN)」「密碼設定測試項目(FA)」）
- 或用戶指定只做一個版本

---

## 標記系統

### 兩種標記

| 標記 | 顏色 | 意思 | 用戶要做什麼 |
|------|------|------|------------|
| **[?]** | 橘色 | AI 有推測值，可能對 | 看一下，對就刪 [?]，錯就改 |
| **[待確認]** | 紅色 | 完全不知道，AI 無法推測 | 你要自己填答案 |

**⚠️ [?] 使用條件（嚴格遵守）：**
- ✅ 規格書有寫（不管是直接寫、列表、圖表、備註呈現）→ 不標 [?]，直接寫入，狀態為 ✅
- [?] 只用於「規格完全沒提到，Bot 從 ref/手冊/同類機台推測」的情況
- 禁止在規格書已經寫明的內容上加 [?]

### 三種狀態

| 狀態 | 編號前標記 | 意思 |
|------|-----------|------|
| ✅ | 可直接測試 | 規格完整，所有欄位確定 |
| 🟡 | 需確認後可測 | 有 [?] 推測值，確認 yes/no 就能測 |
| 🔴 | 無法測試 | 關鍵資訊全缺，需提供規格才能測 |

### 頂部 Summary 統計行

每次展開後，在 Sheet 最上方顯示：

```
📊 本次展開：X 項 | ✅ 可直接測試：X 項 | 🟡 需確認後可測：X 項 | 🔴 無法測試：X 項
```

用戶確認後 AI 同步更新此統計。

### 精簡原則

- 欄位中不寫「規格未提供」（太冗長）
- AI 的疑問/問題清單收到備註欄
- 推測依據放備註欄（一句話：「推測依據：同類機台常見」或「無依據，需實機確認」）
- 測試目的不加括號疑問（如不寫「具體驗證什麼？」）
- **[?] 不獨立成編號**：直接接在相關描述後面
- **[?] 必須同時給選項**：寫出疑慮 +（沒問題請填 OK / 有問題請修改：____）

### [?] 寫法範例

```
預期結果：
1. 能量集滿後觸發升級動畫
2. 顯示升級球演出
3. 上屏顯示「LEVEL UP / POWER UP」
4. 角色頭旁顯示「LEVEL UP / POWER UP」提示，LV 等級即時 +1
   [?] 升級後攻擊力是否提升？
   （沒問題請填 OK：_______ / 有問題請描述：_______）
```

### [待確認] 寫法範例（🔴 紅色項目）

```
步驟：
[待確認] 需要提供：版面設計稿（PNG）的具體內容
（請將此段刪除，替換為已知規格，完成後回報「改好了」）

預期結果：
[待確認] 需要提供：各 UI 元素的排版位置、對齊規則
（請將此段刪除，替換為已知規格，完成後回報「改好了」）
```

**規則：**
- [?] 接在相關描述的下一行，縮排對齊
- [?] 和選項行都用**紅色粗體**
- [待確認] 整段都用**紅色粗體**
- 寫出「具體疑慮問題」或「需要提供什麼」
- OK 和描述兩個選項都有 _______ 填寫位置
- 用戶直接在 Sheet 原地作答
- 不要把推測另起一個編號

### 格式規則

| 項目 | 格式 |
|------|------|
| ✅ 行 | 全黑字，白色背景；編號欄 = HYPERLINK（點擊跳規格書） |
| 🟡 行 | 整行黃色背景；[?] 橘色字體；編號欄 = HYPERLINK（點擊跳規格書）；備註欄加強橘黃色背景 |
| 🔴 行 | [待確認] 紅色字體，備註橘色背景；編號欄 = HYPERLINK（點擊跳規格書） |
| Summary 行 | 淡灰色背景 |
| 確認後 | [?] / [待確認] → 綠色 ✅ 已確認 |

**所有行的編號欄一律是超連結**（`=HYPERLINK(URL, "✅ XX")` 或 `=HYPERLINK(URL, "🟡 XX")`），點擊跳到規格書對應位置。

**🟡 行額外重點：**
- 整行淡黃色背景讓使用者一眼辨識
- 備註欄超連結 + 橘黃色背景加強顯示

---

## 用戶修改判讀規則

Bot 讀取用戶在 Sheet 上的修改時，判斷邏輯：

**[?] 標記的判讀：**

| 用戶動作 | Bot 判讀 |
|---------|---------|
| 刪了 [?] 沒改內容 | = 推測正確，已確認 |
| 改了 [?] 後面的值 | = 確認為新值 |
| [?] 完全沒動 | = 仍為推測，不處理 |

**[待確認] 標記的判讀：**

| 用戶寫的 | Bot 判讀 |
|---------|---------|
| 正確 / OK / 對 / 是 / ✓ | = 推測正確，已確認 |
| 沒有 / 不會 / 無 | = 確認為否定 |
| 具體數值（如「0~128~255」） | = 確認為該值 |
| 選了 A/B/C 其中一個 | = 確認為該選項 |
| 多個選項都回答了 | = 全部確認 |
| [待確認] 完全沒被動過 | = 仍未確認，不處理 |
| 只刪了 [待確認] 但沒寫答案 | = 意圖不明，詢問用戶 |

### ✅ 項目事後修正

展開後全部是 ✅ 的項目，用戶事後發現問題（描述不精確、規格有誤等）：

**流程（和 🟡🔴 相同）：**
1. 用戶直接在 Sheet 改內容
2. 到頻道說「改好了」
3. Bot 比對差異 → 列出哪些改了：「偵測到 #03, #07 有修改」
4. 用戶確認
5. Bot 更新 ref + 規格書補充欄記錄「[用戶修正 YYYY-MM-DD] 原值→新值」

**不分 🟡🔴✅，統一走「改好了」→ Bot 比對 → 確認 → 更新。**

**備註：** ✅ 被改的項目，補充欄記錄「[用戶修正 日期]」（不是 [AI修改]）。

---

## 確認後格式修正

| 項目 | 修正前 | 修正後 |
|------|--------|--------|
| [?] 推測值 | 🟡 [?] 橘色字 | ✅ 已確認：{正確值}（黑色字體） |
| [待確認] | 🔴 紅色字 | ✅ 已確認：{正確值}（黑色字體） |
| 備註欄 | 🟠 推測依據... | 🟢 超連結（去掉 [規格不完整] 標記） |
| 行背景 | 黃色/紅色 | 白色 |

**確認後必須同步完成以下 3 件事（缺一不可）：**

```
□ 測項 Sheet 改了嗎？（格式改正、去色、編號改 ✅）
□ ref 更新了嗎？（有 ref 的情況下）
□ 規格書補充欄寫了嗎？← 最容易忘的
```

三個都打勾才能回覆「已完成」。

**格式修正技術注意事項：**
1. 先完成所有 cell 值的寫入
2. **最後一步**統一重新套用所有需要紅色粗體的 textFormatRuns
3. 不要假設之前設的格式還在（Google Sheets API 重寫 cell 值時會清除同行的 textFormatRuns）
4. 確認完的項目字體必須改回黑色（不能留紅色）
5. 修改完畢後，檢查未修改的 🟡 項目的紅色格式是否還在，如果消失要重新套用

---

## 部分確認處理

當同一格中有多個 [?] 或 [待確認]，用戶只回答了部分：
- 已確認的部分 → 修正為綠色 ✅
- 未確認的部分 → 保持原色（[?] 橘色 / [待確認] 紅色）
- 行狀態：仍有 [待確認] → 維持 🔴；仍有 [?] 但無 [待確認] → 維持 🟡
- 只有全部確認後才改為 ✅
- 頂部 Summary 同步更新

---

## 規格連結欄位

規格連結直接嵌入備註欄，不另開獨立欄位。

### 備註欄超連結格式
- 備註欄的「規格書名─頁籤名規格第X項 [機台標記]」本身就是超連結
- 點擊即可跳轉到規格書對應位置
- 使用 Google Sheets HYPERLINK 公式：`=HYPERLINK("URL", "顯示文字")`
- URL 格式：`https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit#gid={GID}&range=A{ROW}`
- 若備註有多行（如推測依據），第一行為超連結，後續行用 `& CHAR(10) &` 接續

### 定位驗證流程（⚠️ 強制執行，每一條連結都必須做，不可跳過）

**禁止憑記憶/印象/ref 填 Row 號。每一條規格連結都必須即時搜尋驗證。**

1. 用關鍵字（項目名稱/章節標題）在**可見行**中搜尋目標內容的確切 Row
2. 組合 URL（Sheet ID + gid + range=A{Row}）
3. **驗證：讀取該 Row 確認內容和預期一致**
4. 不一致 → 重新搜尋正確位置
5. 真的找不到 → 標記 `[連結待確認]`

**絕對禁止：**
- ❌ 憑記憶/印象填 Row 號
- ❌ 從 ref 直接引用 Row 號（ref 可能過時）
- ❌ 假設行號沒有變過
- ❌ 跳過驗證步驟（第 3 步）
- ❌ ref 中存放 Row 號（Row 號必須每次即時搜尋，不可快取）

### ⚠️ 重要
- **不要另開「規格連結」欄位**，連結嵌入備註欄即可
- Standard 格式維持 11 欄（不是 12 欄）
- Cutscene 格式維持 12 欄（不是 13 欄）

---

## 白話用語規則

所有面向使用者的文字（測試目的、預期結果、對話回覆）禁止使用以下專業術語，統一用白話替代：

| ❌ 禁用 | ✅ 白話替代 |
|---------|-----------|
| 邊界值測試 | 最大值/最小值測試 |
| 邊界條件 | 設定到最大或最小時 |
| 超出邊界 | 超過允許範圍 |
| 邊界行為 | 超過限制時的反應 |
| sanity check | 基本正確性確認 |

此規則適用於：
- 測試目的欄位
- 預期結果欄位
- 展開完成後的對話回覆
- 任何呈現給用戶的文字

---

## 繁簡體規則（方案 C）

### 原則
- 步驟描述、測試目的、預期結果 → 一律繁體中文
- UI 文案引用（畫面上顯示的文字）→ 原文不動，用『』包裹
- 格式：「確認畫面顯示『原文文案』」
- **禁止：擅自轉換引號內的文字**

### 文案引用優先序
1. 「其他文案」區列出的 → 直接用（最準確）
2. 規格書正文中出現的選單名 → 用原文
3. 兩者不一致 → 標 [?] 請用戶確認以哪個為準

### 多版本注意
- CN 機台 → 引號內用簡體文案
- TW 機台 → 引號內用繁體文案
- FA 機台 → 引號內用英文文案
- 如果不確定測試的是哪個版本 → [待確認：測試哪個版本的機台？]

### 範例
```
✅ 確認標題顯示『声音测试』/ Sound Test
✅ 進入『I/O按键测试』頁面，確認所有按鍵可觸發
❌ 進入「I/O按鍵測試」頁面（擅自轉繁體）
```

---

## 步驟與預期結果白話化規則

所有步驟和預期結果必須用白話易懂的方式撰寫，但不可脫離原始規格內容。

### 原則
- 測試人員看一遍就知道要做什麼、會看到什麼
- 不需要回頭查規格書就能執行
- 不使用規格書的技術/內部用語，改用操作者視角的描述

### 步驟白話化

| ❌ 不好 | ✅ 白話 |
|---------|--------|
| 觀察進度條各節點 | 觀察進度條上的 8 個節點圖案，特別注意第 5 個和第 8 個 |
| 累積能量到 100% | 持續打倒敵人，等能量條集滿 |
| 使用攻擊鈕後等待 CD 完成 | 按一下攻擊鈕後等大約 1 秒（CD 結束） |
| 觸發操作提示 | 等待操作提示出現（20 秒不按按鈕） |
| 投幣接關復活 | 讓角色死亡後投幣接關 |

### 預期結果白話化

| ❌ 不好 | ✅ 白話 |
|---------|--------|
| 以打倒淨化小怪的數量累積 | 每打倒一隻小怪，進度條就會往前推進一點 |
| 累積到指定數量推進到下一波 | 推進到滿的時候，進入下一波 |
| CD 中狀態：壓暗/按鈕凹下去的光影 | 冷卻中 → ICON 壓暗，看起來像按鈕凹下去 |
| 有持續時間 | 護盾有時間限制 |
| 時間快到時整條閃爍 | 快要消失前 → 整條護盾開始閃爍提醒 |

### 注意事項
- 不可脫離原始規格內容（不能加沒寫的東西）
- 專有名詞保留（如 SPINE、ICON、CD、Trigger）— 這些是業界通用的
- 數值/時間保留原始描述（如 0.8~1 秒、20 秒、1.5~2 秒）
- 用「→」表示因果關係（如「按住時 → 文字變紅」）

---

## 用戶確認後的更新流程（方案 C）

修正寫回 ref，不動規格書原始欄位。

### 流程
1. 用戶在測項 Sheet 修改 [待確認] 為正確值
2. 用戶跟 Bot 說「改好了」（或下次展開同章節時 Bot 自動比對發現差異）
3. Bot 讀取修改內容 → 判讀用戶意圖（見用戶修改判讀規則）
4. Bot 修正 Sheet 格式（去掉紅色、加 ✅ 綠色）
5. Bot 更新 ref 檔案（下次展開自動用新值）
6. Bot 在規格書「測試補充（AI 修改）」欄寫入確認結果

### 不動規格書原始欄位的原因
- 規格書是原始來源，不可被隨意覆蓋
- ref 才是 Bot 展開時讀取的，改 ref 就夠了
- 規格書只加「補充欄」記錄，不改原文

### 自動比對觸發
下次展開同一章節時，Bot 自動比對 Sheet vs ref：
- 發現差異 → 問用戶「要更新 ref 嗎？」
- 用戶確認 → 更新 ref
- 用戶拒絕 → 維持現有 ref

---

## 用戶回報觸發機制

### 三層觸發（不重複）

| 觸發 | 行為 | 時機 |
|------|------|------|
| 用戶說「改好了」 | 立即讀取 → 列出哪些改了/哪些還沒 → 確認後更新 | 即時 |
| 下次展開同遊戲時 | 自動比對 Sheet vs ref → 發現差異就問「要更新嗎？」 | 被動 |
| 7 天沒回報 | 溫和提醒：「{分頁名} 還有 {N} 個待確認項目，有空時填寫後回報即可。」 | 定時 |
| 30 天仍沒回報 | 最後一次提醒，之後不再打擾 | 定時 |

### 去重規則
- 用戶已說「改好了」→ 取消 7/30 天提醒
- 下次展開已自動比對 → 取消 7/30 天提醒
- 7 天提醒後用戶回報了 → 正常流程，取消 30 天提醒
- 提醒最多 2 次（7天+30天），之後不再打擾

### 「改好了」回報後的確認流程
Bot 讀取修改後必須回報：

```
偵測到 Row X, Y, Z 有修改 ✅
Row A, B 仍為 [待確認]。
→ 剩下的是還沒確認？還是確認後維持原值？
```

用戶回覆後才執行更新（避免「以為全改了但其實漏了」）。

### Sheet 提示語
在展開結果的 Summary 行下方加一行（灰色小字）：
`💡 填寫完 🟡🔴 項目後，到頻道回報「改好了」，AI 會自動整理格式並更新。`

---

## 規格書補充欄規則

在規格書最右邊加一欄「測試補充（AI 修改）」：
- Header：黃色背景
- 內容格式：`[AI修改 YYYY-MM-DD] 補充內容`
- `[AI修改 YYYY-MM-DD]` 一律紅色粗體（每格都要確認有改到）
- 不動規格書原始任何欄位
- 只有已確認的內容才會寫入（[待確認] 不寫）

---

## 自動品質檢查（展開後自動執行）

以下檢查在每次展開完成後由 Bot 自動執行，不需要用戶操作：

### 1. Self-Review Pass（自我覆查）
展開完後逐條檢查：
- □ 步驟中的按鍵/選單名稱和「項目」欄一致？
- □ 預期結果和步驟的操作邏輯匹配？
- □ 沒有兩條測項步驟完全重複？
- □ [?] 數量是否合理？（超過 50% → 建議用戶提供更詳細規格）

### 2. 矛盾偵測（Contradiction Check）
- □ 預設值和範圍不矛盾（預設 70 但範圍 80-100 → 報錯）
- □ 步驟和預期不矛盾（「調高音量」但預期「音量降低」→ 報錯）
- □ 前後測項不矛盾（兩條的預設值不同 → 報警）
- □ 機台用語不混用（同份不會出現 Start 又出現氮氣鍵）

### 3. Sanity Check 清單
- □ 總測項數 > 0
- □ 必填欄位（項目/步驟/預期結果）非空
- □ 沒有連續兩條「項目」完全相同
- □ 步驟中出現的選單名稱在本章節能找到
- □ 預期結果不是步驟的複述

### 4. 步驟句型規範
所有步驟必須用以下句型：
- 導航：「進入{選單路徑}」
- 操作：「將{項目名}設定為{值}」或「按下{按鍵名}」
- 確認：「確認{觀察點}顯示{預期狀態}」
- 退出：「返回{目標頁面}」

禁止：
- 「操作 XX 功能」（太模糊）
- 「測試是否正常」（什麼叫正常？）
- 「檢查結果」（什麼結果？在哪裡看？）

### 步驟引用規則
- **本頁籤有寫操作方式** → 直接使用，黑色正常字
- **本頁籤沒寫但其他頁籤有寫** → 使用其他頁籤的描述，備註欄標明「引用自 {頁籤名} Row XX」
- **整份規格書都沒寫** → 步驟中標 `[待確認] 操作方式？（搖桿/按鈕/觸控/其他：_______）` 紅色粗體
- **導航型步驟**（如「進入某頁面」）→ 直接寫，不需標記（測試必經路徑）

### 5. 差異警報（跨次展開比對）
如果同一章節之前已展開過（Sheet 中有舊測項）：
- 數量不同 → 報告「本次多/少了 X 條」
- 項目名不同 → 報告「新增/刪除了 XXX」
- 只是措辭不同 → 不報告（正常）

### 品質報告
所有檢查完成後，在回覆中附上：

```
🔍 品質檢查：
  Self-Review: ✅ 通過
  矛盾偵測: ✅ 無矛盾
  Sanity Check: ✅ 全通過
  句型規範: ✅ 符合
  定位驗證: ✅ 每條連結已即時搜尋確認
  隱藏行掃描: ✅ 已執行（排除 X 行）
  差異警報: ℹ️ 首次展開（無舊資料比對）
```

### 規格連結驗證結果表
品質報告後必須附上完整的規格連結驗證表，**包含狀態標記**：

```
| # | 項目 | 驗證 Row | 狀態 |
|---|------|---------|------|
| 01 | XXX | Row XX | ✅ |
| 14 | XXX | Row XX | 🟡 需確認 |
| 20 | XXX | Row XX | 🔴 無法測試 |
```

**每一項都要標出對應狀態（✅/🟡/🔴），不可省略。**

如果有任何一項未通過 → 列出具體問題讓用戶知道。

---

## 展開完成 Self-Check（強制，不可跳過）

每次展開完成、每次修正完成，回報用戶前必須逐條確認：

```
【Self-Check】
1. ✓/✗ 規格補充欄全部有值？
2. ✓/✗ 測項數量 ≥ 規格子項數量？（未濃縮）
3. ✓/✗ UI 文案用『』包裹且未轉繁體？
4. ✓/✗ 無概括詞（等/相關/其他）出現在項目名中？
5. ✓/✗ Summary 數字和實際測項數一致？
6. ✓/✗ 每條規格連結已即時搜尋驗證？
7. ✓/✗ 隱藏行已掃描排除？
8. ✓/✗ 每個標題都有 CN + FA 雙語？（規格「其他文案」區有寫的都要帶）
9. ✓/✗ 每個有子功能的章節展開了 ≥ 3 條？（只有 1 條就重檢）
```

- 有任何 ✗ → 立即修正 → 重跑 Self-Check
- 全部 ✓ → 才能回報完成
- **在回覆用戶時附上 Self-Check 結果**

---

## 附錄檔案

| 檔案 | 用途 |
|------|------|
| `SKILL-022-{機台代號}-ref.md` | 各遊戲專屬資料 |

新增遊戲時，執行模式 A 即可自動產出對應 ref 檔。

---

## 資料來源版本

| 資料 | 來源 | 版本/日期 |
|------|------|----------|
| 對照表最後更新 | — | 2026-08-17 |

⚠️ 當硬體改版時，需重新驗證 ref 檔案是否過時（觸發模式 A'）。


---

## 更新歷程

| 日期 | 版本 | 更新內容 |
|------|------|---------|
| 2026-08-21 | 1335行 | 新增：核心紀律9條、Self-Check 9條、模糊描述偵測、步驟白話化、繁簡體方案C、行內[待確認]、✅事後修正流程、禁止合併/濃縮、展開粒度規則、分批限制+Context監控、CN/FA版本必問、2Agent協作架構、已移除項目處理、項目清單列舉規則（每項一行禁止硬寫數量）、SKILL-023規格書轉MD |
| 2026-08-19 | 1006行 | 新增：B-4結構掃描4Step（StepB不可跳過）、定位驗證「絕對不可跳過」+5條禁令、品質報告連結驗證表、ref禁存Row號、灰色規格處理、隱藏行處理、凍結+文字換行、提示行、步驟引用規則、補充欄技術規則、用戶回報觸發機制（三層觸發+去重）、自動品質檢查5項、一步到位UX流程、展開前防呆5項、規格不完整也展開、推測用灰色、[待確認]操作指引、確認後三步缺一不可、格式修正技術規則、結構掃描防缺漏根本解法 |
| 2026-08-18 | 662行 | 新增：標記系統([?]/[待確認])、✅🟡🔴三狀態、Summary統計行、方案C回寫ref、規格書補充欄、用戶修改判讀、確認後格式修正、白話用語規則、展開紀律 |
| 2026-08-17 | 518行 | 新增：規格判讀Checklist、測試目的模板、優先度預設規則、B-3同分頁追加、缺失影響回報、EN→FA統一 |
| 2026-08-17 | 429行 | 新增：三模式架構(A/A'/B)、ref拆檔(主文+A9+A8)、模式A'更新ref、粗略/詳細判斷、格式不明fallback、多區域版本 |
| 2026-08-17 | 初版 | 基礎版：6步流程、standard/cutscene格式、A8+/A9+ I/O差異對照 |


---

## 灰色規格處理

規格書中灰色背景的內容可以引用展開，但需標記提醒用戶確認。

### 預期結果欄
- 引用灰色來源的內容後面標 `[灰色規格]`（灰色字體）
- 末尾加選項行（紅色粗體）：
  `（規格仍有效請填 OK：_______ / 已廢棄請填 刪除：_______ / 有修改請描述：_______）`
  `※ 填寫完畢後，請到頻道回報「改好了」`

### 備註欄
第 2 行加：`⚠️ 部分內容引用自灰色標記區域（Row XX），請確認規格是否仍有效`（橘色）

### Summary
加 `🩶 含灰色引用：X 項`

### 用戶回報後判讀
| 用戶填 | Bot 動作 |
|--------|---------|
| OK | 去掉 [灰色規格]，改為正常黑色 ✅ |
| 刪除 | 該條從預期結果中移除 |
| 具體描述 | 替換為新內容 |

### 處理邏輯
| 規格來源 | 處理方式 |
|---------|---------|
| 正常（白底/無色） | 直接引用，黑色字 |
| 灰色背景 | 引用但標 [灰色規格]，加選項行讓用戶確認 |
| 隱藏行 | 跳過不展開，放到最下方 ⏭️ 區 |

---

## 隱藏行處理

- 隱藏行跳過不展開
- 最下方加灰色區塊「⏭️ 跳過項目」列出被跳過的項目
- 灰色背景 + 灰色字體
- 含規格連結可點擊
- Summary 加 `⏭️ 跳過：X 項`
- 提示行加：「⚠️ 本次已跳過 X 個隱藏項目（詳見最下方）」
- 對話回覆中也要列出被跳過的項目

---

## 已移除項目處理

讀取規格書時，排除以下項目不列入展開範圍：

### 排除條件
- 標記「移除」「刪除」「removed」「deprecated」的項目
- 標記具體移除日期的項目（如「2026/1/30 移除」）
- 刪除線文字
- 灰色 + 刪除線的行

### 處理方式
- 排除的項目不出現在結構化摘要中
- 排除後附註：「已排除 N 個已移除項目：[列表]」
- 遇到不確定是否有效的標記 → 標 [?] 詢問用戶

### 責任歸屬
- **qa-sheet-worker**：讀取時就過濾掉，摘要中不包含已移除項目
- **qa-test-expander**：如果自己讀取，Step C 建目錄時排除

### 與隱藏行的差異
| 類型 | 特徵 | 處理 |
|------|------|------|
| 隱藏行 | 視覺上看不到但資料存在 | 掃描後排除 |
| 已移除項目 | 視覺上看得到但語義上不存在 | 讀取時排除 |

---

## 每次新建分頁必做

1. 凍結前 3 列（Header + Summary + 💡 提示行）
2. D/E/F/J 欄（測試目的/步驟/預期結果/備註）設為文字換行（wrapStrategy: WRAP）

---

## 提示行（第 3 行）

- 位置：Summary 下方
- 格式：灰色斜體小字，淺灰色背景
- 內容：「💡 填寫完 🟡🔴 項目後，到頻道回報「改好了」，AI 會自動整理格式並更新。」
- 如有跳過項目加：「⚠️ 本次已跳過 X 個隱藏項目（詳見最下方）。」

---

## 步驟引用規則

- 本頁籤有寫操作方式 → 直接使用，黑色正常字
- 本頁籤沒寫但其他頁籤有寫 → 使用其他頁籤的描述，備註欄標明「引用自 {頁籤名} Row XX」
- 整份規格書都沒寫 → 步驟中標 [待確認] 紅色粗體
- 導航型步驟（如「進入某頁面」）→ 直接寫，不需標記

### 步驟行內 [待確認] 標記

當測項本身沒問題，但步驟中某個**具體資訊**缺失（哪一關、哪個位置、什麼數值）時：

**格式：** `[待確認：具體問題？]（請補充：_______）` 整段紅色粗體

**範例：**
```
展開時：2. 觸發夥伴出現 [待確認：如何召喚夥伴？什麼條件會出現？]（請補充：_______）
確認後：2. 累積能量到 100% 後按技能鍵召喚夥伴
```

**與其他標記的對照：**

| 類型 | 位置 | 格式 | 選項行 |
|------|------|------|--------|
| 整條缺失 🔴 | 步驟/預期結果整欄 | 紅色粗體 | `（請將此段刪除，替換為已知規格，完成後回報「改好了」）` |
| 灰色規格 🩶 | 預期結果行尾 | `[灰色規格]` 灰色 | `（規格仍有效請填 OK / 已廢棄請填 刪除 / 有修改請描述）` |
| 推測 🟡 | 預期結果末尾 | `推測：XXX` 灰色 | `（沒問題請填 OK：_______ / 有問題請描述：_______）` |
| 行內缺資訊 | 步驟中某處 | `[待確認：問題？]（請補充：_______）` 紅色粗體 | 無額外選項行 |

**用戶確認後處理：**
- 用戶直接把整段紅字刪掉，替換為具體內容（黑色）
- 回報「改好了」統一處理

**判斷邏輯（必須按順序執行）：**
1. 先搜尋本頁籤 → 有寫就直接用（黑色）
2. 再搜尋其他頁籤 → 有寫就引用 + 備註標來源
3. 搜遍整份規格書都找不到 → 才標 `[待確認：問題？]`（紅色）

**流程：搜尋 → 找到就用 → 找不到才標紅。不是一遇到「不確定」就標。**

**補充判斷：**
- 步驟中提到「某個地方」「某個關卡」「某個位置」但不具體 → 先搜尋，找不到才補行內 [待確認]
- 測試人員看完不知道「去哪裡」「按什麼」「等多久」→ 先搜尋，找不到才補
- 規格本身就是通用描述（如「任意關卡」）→ 不補

**與整條 🔴 [待確認] 的區分：**

| 類型 | 格式 | 用途 |
|------|------|------|
| 整條缺失 | 🔴 整段紅色粗體 + OK/描述選項行 | 規格完全沒寫這個功能，整條不確定 |
| 行內缺資訊 | 步驟中 `[待確認：問題？]` 紅色 | 測項沒問題，只是某個具體資訊缺失 |

**防膨脹規則：**
- 不限數量，全部列出讓使用者知道缺什麼
- 行內 [待確認] 和整條 🔴 [待確認] 不衝突（整條 = 功能完全沒寫，行內 = 具體參數缺失）

**不需要加 OK/描述選項行。** 用戶直接在 Sheet 中改掉 [待確認：XXX] 即可，回報「改好了」統一處理。

---

## 模糊描述偵測

展開時主動偵測規格書中模糊不清的描述，用行內 [待確認：問題] 標出讓使用者知道要補什麼。

### 偵測流程
1. 讀到模糊描述 → 先搜尋整份規格書（所有頁籤）
2. 找到具體資訊 → 直接引用，備註標來源
3. 找不到 → 步驟中標 [待確認：具體問題]（紅色）

### 常見模糊情境清單（通用，適用所有遊戲）

| 模糊描述 | Bot 標記 |
|---------|---------|
| 「進入指定關卡/場景」 | [待確認：哪一關/哪個場景？] |
| 「到達指定位置」 | [待確認：什麼位置/座標？] |
| 「等待一段時間」 | [待確認：等多久？幾秒？] |
| 「特定條件下觸發」 | [待確認：什麼條件？] |
| 「某些機台」 | [待確認：哪些機台型號？] |
| 「玩家操作後」 | [待確認：什麼操作？按什麼鍵？] |
| 「達到特定分數/等級」 | [待確認：多少分/幾等？] |
| 「指定時間內」 | [待確認：幾秒內？] |
| 「特定道具/物件」 | [待確認：哪個道具/物件？] |
| 「特殊事件」 | [待確認：什麼事件？觸發方式？] |

### 規則
- 不限數量，全部列出
- 先搜尋再標（找到就不標）
- 使用者看到後補充具體內容 → 回報「改好了」→ Bot 更新
- 和整條 🔴 [待確認] 不衝突（整條=功能完全沒寫，行內=具體參數缺失）

---

## 規格書補充欄技術注意

- 寫入前先檢查 Sheet 最大欄數
- 如果需要新欄位，用 appendDimension 擴充後再寫入
- 不可寫到已有資料的欄位
- 永遠使用最右邊的空白欄