讀取規格書展開測試項目，支援多遊戲 ref 架構
v1.4下載這份部署包，即可一鍵還原/設定「QA 測項展開系統」的兩個協作機器人（含 SKILL-022 測項展開 + SKILL-023 規格書轉 MD 的完整規則）。
包內含 7 個檔案：主 SOP（規則 1~24）、Phase1 轉 MD 規範、A8/A9 用語對照、schema、部署包使用說明、使用者指南 v5。
將 QA 規格書（.xlsx）的指定規格行展開為測試項目，產出 A0 格式的 Excel / Google Sheet 測試項目檔。
以下規則優先於所有其他規則。違反任何一條 = 產出無效。
本技能將使用者指定的 .xlsx 規格書指定行，展開為符合 A0 範本格式的測試項目，輸出帶有正確樣式的檔案。所有遊戲專屬資料（硬體清單、操控用語、數量基準）均由獨立的 ref 檔案提供，主文不包含任何遊戲專屬硬體名稱。
觸發關鍵字： 「展開測項」「把規格展開成測試項目」「產出 Excel 格式」「請把 XXX 規格書第 YY 項展開測項」
適用範圍： 後台規格書、操作員選單規格、跨屏規格書、流程規格等任何 .xlsx 格式規格書。
收到請求 → 有 ref 嗎？
├── 沒有 → 模式 A（首次建立）
└── 有 → 版本一致嗎？
├── 一致 → 模式 B（日常展開）
└── 不一致 → 模式 A'（更新 ref）
當目標遊戲尚無對應的 ref 檔案時，執行此流程。
用戶提供規格資料，Bot 接收並解析。
Bot 從資料中提取：
如果是從其他 ref 複製的，列出和原 ref 的差異讓用戶確認：
用戶逐項確認提取結果是否正確。
產出 SKILL-022-{機台代號}-ref.md，標注信心等級：
| 信心等級 | 來源 |
|---|---|
| 🟢 高 | 實機確認 |
| 🟡 中 | 手冊/規格書 |
| 🔴 低 | 口述/推測 |
立刻試展 2～3 項規格，確認 ref 可正常使用。若有問題回到 A-6 修正。
觸發條件： 用戶規格版本 ≠ ref 中記載的版本
比對新規格 vs 現有 ref，列出差異清單。
用戶確認哪些是：
更新 ref 檔案，保留版本紀錄（在「資料來源」區塊記錄更新歷程）。
ref 更新完成後，正常執行日常展開。
必填：
選填：
有選填資訊 → 自動調整優先度 + 新增迴歸測項。
Bot 載入對應 ref 檔，回報：
已載入 [{遊戲代號} v{版本}]，確認？
用戶確認後繼續。若版本不一致，轉入模式 A'。
Bot 列出該 ref 中的章節清單讓用戶勾選要展開的範圍。
使用 scripts/read_spec.py 讀取指定頁籤指定行：
python3 scripts/read_spec.py "<規格書路徑>" --sheet "<頁籤名>" --rows "65,66,100-110"
Step A：讀取內容
spreadsheets.values.get(range="'{頁籤名}'") 讀取整份頁籤 — 不帶欄位/行數限制Step B：掃描隱藏行和灰色行（必做，不可跳過）
spreadsheets.get(includeGridData=True) 取得格式資訊rowMetadata 找出所有隱藏行（hiddenByUser / hiddenByFilter）effectiveFormat.backgroundColor 找出所有灰色背景行Step C：建立章節目錄
Step D：展開
讀出後辨識：
0518新增、NEW、刪除、XX專屬 等標記讀取規格後，逐項檢查以下要素：
判讀結果：
[待確認] 需要提供：XXXX，並加上使用者操作指引 （請將此段刪除，替換為已知規格，完成後回報「改好了」）設計原則：
只展開規格書中有寫到的內容。規格沒寫的不要自己加測試項目。
禁止：
規格書列出的選單項目、子項目、測試項目，必須完整逐一列出。
禁止：
規則：規格列幾個就寫幾個，一個不多一個不少。
粗略/詳細判斷規則：
| 規格詳細程度 | 判斷標準 | 展開方式 |
|---|---|---|
| 粗略 | 只有功能名稱，沒有設定值範圍/步驟說明/預期結果 | 展開 1 項基本驗證 |
| 詳細 | 有具體設定值、操作步驟、預期行為描述 | 展開正常 + 最大最小值（2～3 項） |
操控用語替換規則：
| 驗證項目 | 方式 |
|---|---|
| 數量驗證 | ref 中子項目數 vs 展開數，有落差則列出具體漏哪個 |
| 用語驗證 | 確認鍵名稱是否正確，掃描 ref 中「禁用詞」欄位 |
| 漏項檢查 | 比對 ref 清單和展開結果，有落差問用戶「刻意跳過還是補上？」 |
| BAR 提示文案 | 測項中的選單操作提示須與 ref 中定義的確認鍵一致 |
Sheet 產出規則：
| 情境 | 行為 |
|---|---|
| 第一次展開這個章節 | 建新分頁，名稱 = 「{遊戲} {章節名}測試」 |
| 同章節分批展開（如先做 5 項確認，再做剩下 5 項） | 追加到同一分頁，依原規格順序排列，不開第二個分頁 |
| 同章節完全重新展開 | 問用戶：「已有舊的，要覆蓋還是追加？」 |
| 多章節一起展開 | 每章節各自一個分頁 |
| 不確定時 | 直接問用戶「要追加到現有分頁還是開新的？」 |
亦可使用 scripts/write_excel.py 輸出本地 Excel：
python3 scripts/write_excel.py items.json 輸出路徑.xlsx --format standard
展開完成回覆格式：
📊 本次展開：{N} 項 | ✅ 可直接測試：{X} 項 | 🟡 需確認後可測：{Y} 項 | 🔴 無法測試：{Z} 項
✅ 已展開 {遊戲代號} {章節名} {N} 項。
🟡 以下 Y 項有推測值 [?]，請確認：
- #{編號} {項目名}：{推測內容摘要}
🔴 以下 Z 項缺關鍵資訊 [待確認]，需要你提供：
- #{編號} {項目名}：{需要什麼資訊}
對的就刪 [?]，錯的改掉，缺的補上。改好跟我說「改好了」。
如全部為 ✅，則只顯示第一行統計 + 第二行。
| 等級 | 要素 | 對應欄位 | 缺少時的行為 |
|---|---|---|---|
| 🔴 必要 | 功能/項目名稱 | 項目 | 停下來問用戶 |
| 🔴 必要 | 操作步驟或觸發方式 | 步驟 | 停下來問用戶 |
| 🔴 必要 | 預期結果/正確行為 | 預期結果 | 停下來問用戶 |
| 🟡 建議 | 設定值範圍 | 步驟+預期結果 | 只展基本驗證，標 [規格不完整] |
| 🟡 建議 | 預設值 | 預期結果 | 無法展恢復測試 |
| 🟡 建議 | 限制/例外 | 步驟+預期結果 | 無法展異常案例 |
| 🟢 加分 | UI 截圖 | — | 正常展開 |
| 🟢 加分 | 編號/層級 | 備註 | 正常展開 |
| 🟢 加分 | 版本/區域標記 | 備註 | 正常展開 |
| 測試類型 | 模板 | 範例 |
|---|---|---|
| 基本驗證 | 「驗證 {項目名} 操作後 {預期結果} 正確」 | 驗證音量設定調整後數值正確更新 |
| 最大最小值測試 | 「驗證 {項目名} 設定到最大值({max})和最小值({min})時能正常運作」 | 驗證群組編號設定到最大值(99)和最小值(0)時能正常運作 |
| 異常測試 | 「驗證 {項目名} 在 {例外情境} 時正確處理」 | 驗證網路斷線時版本更新正確處理 |
| 恢復測試 | 「驗證 {項目名} 恢復預設後回到 {預設值}」 | 驗證音量設定恢復預設後回到 50% |
✅ 正確寫法：
Bot 根據規格內容自動選擇模板，填入對應欄位值。
| 優先度 | 適用項目 |
|---|---|
| 高 | 投幣/金流、連線、安全裝置、動感平台啟停 |
| 中 | 遊戲設定、音量、燈光、I/O 基本功能 |
| 低 | 外觀、資訊顯示、版本號確認 |
自動調整邏輯：
| 錯誤類型 | 防範方式 |
|---|---|
| 給錯版本規格書 | 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 自己數的數字，改用列舉所有項目名（見下方規則） |
預期結果中涉及「項目清單」時：
禁止：
正確：
✅ 由上而下顯示以下項目： 『投币设定』 『彩票設定』 『音量设定』 『离开』
唯一例外： 規格書明確定義的數字可以用（如「最多支援 4 台連線」= 規格寫的值，不是 Bot 數的）
流程保障：
當規格格式無法辨識（截圖標注型/散落多份文件/非結構化）：
以最完整版本為 ref 基準（通常 CN 或 FA），差異用標記：
| 標記 | 意義 |
|---|---|
[CN-only] | 僅中國版有 |
[not-in-TW] | 台灣版沒有 |
[FA-only] | 僅外銷版（Foreign Area）有 |
[not-in-FA] | 外銷版沒有 |
一個有子功能的章節必須至少展開以下層級：
| 情境 | 展開方式 |
|---|---|
| 連線組合測試（機台A × n + 機台B × m） | 每個有效組合 = 1 條測項 |
| 動感平台各方向測試 | 每個方向 = 1 條測項（不合併） |
| 燈光測試各燈項 | 每個燈項 = 1 條測項 |
| 音量各子項（總音量/待機/選單...） | 合併為 1 條，步驟中逐一列出 |
| I/O 各按鍵 | 合併為 1 條，預期結果中列出全部項目 |
| 版號各子項（M/G/T/L/N） | 每個版號 = 1 條測項 |
| 情境 | 處理方式 |
|---|---|
| 測項同時提到兩台機器（如連線測試） | 標記 [共用]，步驟中明確列出各機台的操作 |
| ref 中找不到對應用語（新功能/新硬體） | 保留原文，備註加「[待確認用語]」 |
| 用語替換後語句不通順 | 人工微調，但不改變測試意圖 |
| 規格書中已標記機台專屬 | 直接採用規格書標記 |
| 不確定某功能是否共用 | 標記 [待確認]，不猜測 |
備註欄中加入以下標記之一：
| 標記 | 條件 |
|---|---|
[{遊戲代號}專用] | 僅適用該機台的功能（如獨有硬體） |
[共用] | 所有機台操作步驟和預期結果完全相同 |
判斷邏輯：
| 欄位 | 填寫方式 |
|---|---|
| 編號 | 狀態標記 + 兩位數字（✅ 01、🟡 02、🔴 03） |
| 類別 | 規格所在頁籤名或功能模組名 |
| 項目 | 簡短功能描述（不超過 3 行） |
| 測試目的 | 「驗證…」開頭，1 句話（依測試目的生成規則） |
| 步驟 | 編號列表：1. xxx / 2. xxx / 3. xxx |
| 預期結果 | 編號列表，每條對應一個可觀察結果。直接寫「最大值/最小值」+ 具體會發生什麼，不寫「邊界值」 |
| 執行人員 | 空白 |
| 測試結果 | 空白 |
| 測試日期 | 空白 |
| 備註(規格參照) | HYPERLINK 超連結：規格書名─頁籤名規格第X項 [機台標記]（點擊跳轉規格書）+ 換行接推測依據（如有） |
| 優先度 | 依優先度預設規則自動帶入，用戶可覆寫 |
同上，但「備註(規格參照)」拆成兩欄：備註（J）+ 規格參照（K，HYPERLINK）+ 優先度（L）
預期結果寫法：
原則：不寫「邊界值」，直接寫「最大值/最小值」+ 具體會發生什麼。
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 |
| 機器人 | 角色 |
|---|---|
| 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 → 用戶：回報結果
展開時如果規格書有 CN 和 FA 兩個版本的文案，必須先問用戶：
「這次要展開 CN（簡體）的測試項目還是 FA（英文）的？或是兩個都要分開展？」
| 標記 | 顏色 | 意思 | 用戶要做什麼 |
|---|---|---|---|
| [?] | 橘色 | AI 有推測值，可能對 | 看一下，對就刪 [?]，錯就改 |
| [待確認] | 紅色 | 完全不知道，AI 無法推測 | 你要自己填答案 |
| 狀態 | 編號前標記 | 意思 |
|---|---|---|
| ✅ | 可直接測試 | 規格完整，所有欄位確定 |
| 🟡 | 需確認後可測 | 有 [?] 推測值，確認 yes/no 就能測 |
| 🔴 | 無法測試 | 關鍵資訊全缺，需提供規格才能測 |
每次展開後，在 Sheet 最上方顯示：
📊 本次展開：X 項 | ✅ 可直接測試：X 項 | 🟡 需確認後可測：X 項 | 🔴 無法測試：X 項
用戶確認後 AI 同步更新此統計。
預期結果： 1. 能量集滿後觸發升級動畫 2. 顯示升級球演出 3. 上屏顯示「LEVEL UP / POWER UP」 4. 角色頭旁顯示「LEVEL UP / POWER UP」提示，LV 等級即時 +1 [?] 升級後攻擊力是否提升？ （沒問題請填 OK：_______ / 有問題請描述：_______）
步驟： [待確認] 需要提供：版面設計稿（PNG）的具體內容 （請將此段刪除，替換為已知規格，完成後回報「改好了」） 預期結果： [待確認] 需要提供：各 UI 元素的排版位置、對齊規則 （請將此段刪除，替換為已知規格，完成後回報「改好了」）
規則：
| 項目 | 格式 |
|---|---|
| ✅ 行 | 全黑字，白色背景；編號欄 = HYPERLINK（點擊跳規格書） |
| 🟡 行 | 整行黃色背景；[?] 橘色字體；編號欄 = HYPERLINK（點擊跳規格書）；備註欄加強橘黃色背景 |
| 🔴 行 | [待確認] 紅色字體，備註橘色背景；編號欄 = HYPERLINK（點擊跳規格書） |
| Summary 行 | 淡灰色背景 |
| 確認後 | [?] / [待確認] → 綠色 ✅ 已確認 |
所有行的編號欄一律是超連結（=HYPERLINK(URL, "✅ XX") 或 =HYPERLINK(URL, "🟡 XX")），點擊跳到規格書對應位置。
🟡 行額外重點：
Bot 讀取用戶在 Sheet 上的修改時，判斷邏輯：
[?] 標記的判讀：
| 用戶動作 | Bot 判讀 |
|---|---|
| 刪了 [?] 沒改內容 | = 推測正確，已確認 |
| 改了 [?] 後面的值 | = 確認為新值 |
| [?] 完全沒動 | = 仍為推測，不處理 |
[待確認] 標記的判讀：
| 用戶寫的 | Bot 判讀 |
|---|---|
| 正確 / OK / 對 / 是 / ✓ | = 推測正確，已確認 |
| 沒有 / 不會 / 無 | = 確認為否定 |
| 具體數值（如「0~128~255」） | = 確認為該值 |
| 選了 A/B/C 其中一個 | = 確認為該選項 |
| 多個選項都回答了 | = 全部確認 |
| [待確認] 完全沒被動過 | = 仍未確認，不處理 |
| 只刪了 [待確認] 但沒寫答案 | = 意圖不明，詢問用戶 |
展開後全部是 ✅ 的項目，用戶事後發現問題（描述不精確、規格有誤等）：
流程（和 🟡🔴 相同）：
不分 🟡🔴✅，統一走「改好了」→ Bot 比對 → 確認 → 更新。
備註： ✅ 被改的項目，補充欄記錄「[用戶修正 日期]」（不是 [AI修改]）。
| 項目 | 修正前 | 修正後 |
|---|---|---|
| [?] 推測值 | 🟡 [?] 橘色字 | ✅ 已確認：{正確值}（黑色字體） |
| [待確認] | 🔴 紅色字 | ✅ 已確認：{正確值}（黑色字體） |
| 備註欄 | 🟠 推測依據... | 🟢 超連結（去掉 [規格不完整] 標記） |
| 行背景 | 黃色/紅色 | 白色 |
確認後必須同步完成以下 3 件事（缺一不可）：
□ 測項 Sheet 改了嗎？（格式改正、去色、編號改 ✅） □ ref 更新了嗎？（有 ref 的情況下） □ 規格書補充欄寫了嗎？← 最容易忘的
三個都打勾才能回覆「已完成」。
格式修正技術注意事項：
當同一格中有多個 [?] 或 [待確認]，用戶只回答了部分：
規格連結直接嵌入備註欄，不另開獨立欄位。
=HYPERLINK("URL", "顯示文字")https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit#gid={GID}&range=A{ROW}& CHAR(10) & 接續禁止憑記憶/印象/ref 填 Row 號。每一條規格連結都必須即時搜尋驗證。
[連結待確認]絕對禁止：
所有面向使用者的文字（測試目的、預期結果、對話回覆）禁止使用以下專業術語，統一用白話替代：
| ❌ 禁用 | ✅ 白話替代 |
|---|---|
| 邊界值測試 | 最大值/最小值測試 |
| 邊界條件 | 設定到最大或最小時 |
| 超出邊界 | 超過允許範圍 |
| 邊界行為 | 超過限制時的反應 |
| sanity check | 基本正確性確認 |
此規則適用於：
✅ 確認標題顯示『声音测试』/ Sound Test ✅ 進入『I/O按键测试』頁面，確認所有按鍵可觸發 ❌ 進入「I/O按鍵測試」頁面（擅自轉繁體）
所有步驟和預期結果必須用白話易懂的方式撰寫，但不可脫離原始規格內容。
| ❌ 不好 | ✅ 白話 |
|---|---|
| 觀察進度條各節點 | 觀察進度條上的 8 個節點圖案，特別注意第 5 個和第 8 個 |
| 累積能量到 100% | 持續打倒敵人，等能量條集滿 |
| 使用攻擊鈕後等待 CD 完成 | 按一下攻擊鈕後等大約 1 秒（CD 結束） |
| 觸發操作提示 | 等待操作提示出現（20 秒不按按鈕） |
| 投幣接關復活 | 讓角色死亡後投幣接關 |
| ❌ 不好 | ✅ 白話 |
|---|---|
| 以打倒淨化小怪的數量累積 | 每打倒一隻小怪，進度條就會往前推進一點 |
| 累積到指定數量推進到下一波 | 推進到滿的時候，進入下一波 |
| CD 中狀態：壓暗/按鈕凹下去的光影 | 冷卻中 → ICON 壓暗，看起來像按鈕凹下去 |
| 有持續時間 | 護盾有時間限制 |
| 時間快到時整條閃爍 | 快要消失前 → 整條護盾開始閃爍提醒 |
修正寫回 ref，不動規格書原始欄位。
下次展開同一章節時，Bot 自動比對 Sheet vs ref：
| 觸發 | 行為 | 時機 |
|---|---|---|
| 用戶說「改好了」 | 立即讀取 → 列出哪些改了/哪些還沒 → 確認後更新 | 即時 |
| 下次展開同遊戲時 | 自動比對 Sheet vs ref → 發現差異就問「要更新嗎？」 | 被動 |
| 7 天沒回報 | 溫和提醒：「{分頁名} 還有 {N} 個待確認項目，有空時填寫後回報即可。」 | 定時 |
| 30 天仍沒回報 | 最後一次提醒，之後不再打擾 | 定時 |
Bot 讀取修改後必須回報：
偵測到 Row X, Y, Z 有修改 ✅ Row A, B 仍為 [待確認]。 → 剩下的是還沒確認？還是確認後維持原值？
用戶回覆後才執行更新（避免「以為全改了但其實漏了」）。
在展開結果的 Summary 行下方加一行（灰色小字）：
💡 填寫完 🟡🔴 項目後，到頻道回報「改好了」，AI 會自動整理格式並更新。
在規格書最右邊加一欄「測試補充（AI 修改）」：
[AI修改 YYYY-MM-DD] 補充內容[AI修改 YYYY-MM-DD] 一律紅色粗體（每格都要確認有改到）以下檢查在每次展開完成後由 Bot 自動執行，不需要用戶操作：
展開完後逐條檢查：
所有步驟必須用以下句型：
禁止：
[待確認] 操作方式？（搖桿/按鈕/觸控/其他：_______） 紅色粗體如果同一章節之前已展開過（Sheet 中有舊測項）：
所有檢查完成後，在回覆中附上：
🔍 品質檢查： Self-Review: ✅ 通過 矛盾偵測: ✅ 無矛盾 Sanity Check: ✅ 全通過 句型規範: ✅ 符合 定位驗證: ✅ 每條連結已即時搜尋確認 隱藏行掃描: ✅ 已執行（排除 X 行） 差異警報: ℹ️ 首次展開（無舊資料比對）
品質報告後必須附上完整的規格連結驗證表，包含狀態標記：
| # | 項目 | 驗證 Row | 狀態 | |---|------|---------|------| | 01 | XXX | Row XX | ✅ | | 14 | XXX | Row XX | 🟡 需確認 | | 20 | XXX | Row XX | 🔴 無法測試 |
每一項都要標出對應狀態（✅/🟡/🔴），不可省略。
如果有任何一項未通過 → 列出具體問題讓用戶知道。
每次展開完成、每次修正完成，回報用戶前必須逐條確認：
【Self-Check】 1. ✓/✗ 規格補充欄全部有值？ 2. ✓/✗ 測項數量 ≥ 規格子項數量？（未濃縮） 3. ✓/✗ UI 文案用『』包裹且未轉繁體？ 4. ✓/✗ 無概括詞（等/相關/其他）出現在項目名中？ 5. ✓/✗ Summary 數字和實際測項數一致？ 6. ✓/✗ 每條規格連結已即時搜尋驗證？ 7. ✓/✗ 隱藏行已掃描排除？ 8. ✓/✗ 每個標題都有 CN + FA 雙語？（規格「其他文案」區有寫的都要帶） 9. ✓/✗ 每個有子功能的章節展開了 ≥ 3 條？（只有 1 條就重檢）
| 檔案 | 用途 |
|---|---|
SKILL-022-{機台代號}-ref.md | 各遊戲專屬資料 |
新增遊戲時，執行模式 A 即可自動產出對應 ref 檔。
| 資料 | 來源 | 版本/日期 |
|---|---|---|
| 對照表最後更新 | — | 2026-08-17 |
| 日期 | 版本 | 更新內容 |
|---|---|---|
| 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：_______ / 已廢棄請填 刪除：_______ / 有修改請描述：_______） ※ 填寫完畢後，請到頻道回報「改好了」⚠️ 部分內容引用自灰色標記區域（Row XX），請確認規格是否仍有效（橘色）加 🩶 含灰色引用：X 項
| 用戶填 | Bot 動作 |
|---|---|
| OK | 去掉 [灰色規格]，改為正常黑色 ✅ |
| 刪除 | 該條從預期結果中移除 |
| 具體描述 | 替換為新內容 |
| 規格來源 | 處理方式 |
|---|---|
| 正常（白底/無色） | 直接引用，黑色字 |
| 灰色背景 | 引用但標 [灰色規格]，加選項行讓用戶確認 |
| 隱藏行 | 跳過不展開，放到最下方 ⏭️ 區 |
⏭️ 跳過：X 項讀取規格書時，排除以下項目不列入展開範圍：
| 類型 | 特徵 | 處理 |
|---|---|---|
| 隱藏行 | 視覺上看不到但資料存在 | 掃描後排除 |
| 已移除項目 | 視覺上看得到但語義上不存在 | 讀取時排除 |
當測項本身沒問題，但步驟中某個具體資訊缺失（哪一關、哪個位置、什麼數值）時：
格式： [待確認：具體問題？]（請補充：_______） 整段紅色粗體
範例：
展開時：2. 觸發夥伴出現 [待確認：如何召喚夥伴？什麼條件會出現？]（請補充：_______） 確認後：2. 累積能量到 100% 後按技能鍵召喚夥伴
與其他標記的對照：
| 類型 | 位置 | 格式 | 選項行 |
|---|---|---|---|
| 整條缺失 🔴 | 步驟/預期結果整欄 | 紅色粗體 | （請將此段刪除，替換為已知規格，完成後回報「改好了」） |
| 灰色規格 🩶 | 預期結果行尾 | [灰色規格] 灰色 | （規格仍有效請填 OK / 已廢棄請填 刪除 / 有修改請描述） |
| 推測 🟡 | 預期結果末尾 | 推測：XXX 灰色 | （沒問題請填 OK：_______ / 有問題請描述：_______） |
| 行內缺資訊 | 步驟中某處 | [待確認：問題？]（請補充：_______） 紅色粗體 | 無額外選項行 |
用戶確認後處理：
判斷邏輯（必須按順序執行）：
[待確認：問題？]（紅色）流程：搜尋 → 找到就用 → 找不到才標紅。不是一遇到「不確定」就標。
補充判斷：
與整條 🔴 [待確認] 的區分：
| 類型 | 格式 | 用途 |
|---|---|---|
| 整條缺失 | 🔴 整段紅色粗體 + OK/描述選項行 | 規格完全沒寫這個功能，整條不確定 |
| 行內缺資訊 | 步驟中 [待確認：問題？] 紅色 | 測項沒問題，只是某個具體資訊缺失 |
防膨脹規則：
不需要加 OK/描述選項行。 用戶直接在 Sheet 中改掉 [待確認：XXX] 即可，回報「改好了」統一處理。
展開時主動偵測規格書中模糊不清的描述，用行內 [待確認：問題] 標出讓使用者知道要補什麼。
| 模糊描述 | Bot 標記 |
|---|---|
| 「進入指定關卡/場景」 | [待確認：哪一關/哪個場景？] |
| 「到達指定位置」 | [待確認：什麼位置/座標？] |
| 「等待一段時間」 | [待確認：等多久？幾秒？] |
| 「特定條件下觸發」 | [待確認：什麼條件？] |
| 「某些機台」 | [待確認：哪些機台型號？] |
| 「玩家操作後」 | [待確認：什麼操作？按什麼鍵？] |
| 「達到特定分數/等級」 | [待確認：多少分/幾等？] |
| 「指定時間內」 | [待確認：幾秒內？] |
| 「特定道具/物件」 | [待確認：哪個道具/物件？] |
| 「特殊事件」 | [待確認：什麼事件？觸發方式？] |
以下為第一階段測試累積、經用戶確認的正式規則。與前述核心紀律一併適用。
所有展開的測項預設為 🟡。只有符合以下條件才能升級為 ✅：
無法指出出處 = 保持 🟡，禁止升級。
🟡 項目格式：
[推測] 前綴 + 依據說明[推測] 音量調整為 70%（依據：同類機台常見行為）| 模式 | 表現 | 防範 |
|---|---|---|
| 合理推導偽裝事實 | 規格寫「有音量設定」→ Bot 寫「範圍 0-100」但範圍是猜的 | 強制標出處，沒寫就是 🟡 |
| 常識填充 | 規格沒寫但「所有機台都有」→ Bot 當確定 | 常識 ≠ 規格，無出處 = 🟡 |
| 數字捏造 | 規格寫「可調」→ Bot 自己決定「0-100」 | 沒寫具體數字就不能寫數字 |
| 語氣確定化 | 規格寫「可能支援 4 台」→ Bot 去掉「可能」 | 保留原文語氣，不強化 |
| 上文汙染 | 之前展 A9+ 有某功能，現在展 A8+ 也寫了 | 每次確認機台類型，不跨遊戲假設 |
每次展開測試項目時，自動在 M 欄（第 13 欄）加入「職能」標籤。
欄位名稱： 職能 位置： M 欄（緊接在 L 欄「規格連結」後面）
標籤值（下拉選單）： 程式 / 美術 / 企劃 / 程式/美術 / 程式/企劃 / 美術/企劃
自動判斷邏輯（按章節整批標）：
/ 分隔 無法判斷 → 加 [?]格式要求： M 欄格式與同行一致；設定資料驗證（下拉選單），strict=False 允許自訂值。
| 位置 | 字體大小 |
|---|---|
| Row 1~3（凍結欄：標題 + Summary + 提示行） | 14 |
| Row 4 以下（所有測試項目） | 12 |
套用範圍：A~M 所有欄位。
在提示行（Row 3）追加：
⚠️ 如果看到的測項比預期少，請檢查是否有啟用篩選（欄位標題出現綠色漏斗圖示 = 篩選中）
格式：灰色斜體，與現有提示行一致。
觸發條件： 用戶指定的遊戲沒有對應的 SKILL-022-XX-ref.md
流程：
用戶跳過時： 以通用模式展開（不做用語替換），備註標 [無用語對照表，用語未驗證]。
展開前列出分頁清單時，必須檢查每個頁籤的 sheet.properties.hidden 屬性。
spreadsheets.get 取得所有頁籤，檢查 properties.hidden，隱藏頁籤標注 [隱藏]所有展開都必須先轉 MD，再從 MD 展開。
規格書(Sheet) → qa-sheet-worker 轉 MD → 用戶確認 → qa-test-expander 讀 MD 展開
禁止： 直接讀 Sheet 後展開（跳過轉 MD）、用「摘要」代替 MD。
唯一例外： 已有現成 MD 且未過期（轉換日期 vs Sheet 最後修改時間一致）→ 直接用。
MD 存放位置： /root/.agend/wiki/specs/[遊戲名]/[頁籤名].md
為什麼強制： 確保輸入一致、可 review、可追溯、避免直讀 Sheet 格式解析不穩。
當測項引用其他頁籤/其他 Sheet 的定義時，備註欄必須標明出處。
[主要出處] 規格書名─頁籤名 Row XX [引用] 另一份規格書名─頁籤名 Row XX~XX（引用內容說明）
禁止在文字描述中寫 GID（❌ GID=2002629856）。HYPERLINK 公式中仍需 GID（跳轉用），但備註顯示文字不放 GID。
原因： 測試人員需要知道定義出處，GID 是技術細節，人不需要看。
用戶確認/修正 🟡 項目並回報「改好了」後，整合時必須加綠色確認標記。
（✅ 已確認：推測正確） 或 （✅ 已確認：已修正為 XXX） — 綠色 rgb(0.2, 0.66, 0.33)✅ 已由測試確認（YYYY-MM-DD） — 綠色（✅ 已確認：此功能不存在，移除此測項） 綠色，再刪格式實作： 用 textFormatRuns，綠色與紅色 [推測] 共存於同 cell。
自動產生的反面測試，必須排在對應正面測項的下一行。
#05 ✅ 密碼：預設密碼 0000 驗證通過（正面） #06 🟡 密碼：修改後舊密碼失效（反面）[自動產生反面測試] 對應 #05
核心原則： 一個可獨立判斷 Pass/Fail 的驗證點 = 一條獨立測試項目。
判斷標準： 一條測項中有多個驗證點，任一單獨出錯時測試人員無法只標記那一個 → 必須拆分。
禁止合併： 多角色/物件、多升級階段、多獨立欄位放同一條。
適用範圍：
| 規格類型 | 拆分方式 |
|---|---|
| DataTable | 每物件 × 每欄位 × 每階段 = 獨立一條 |
| 功能規格 | 每個獨立可驗證的行為 = 獨立一條 |
| UI 規格 | 每個獨立顯示元素 = 獨立一條 |
膨脹控制（同邏輯重複超過 50 次時）： 觸發後問用戶 — A. 全量展開 / B. 抽樣展開（5 個代表完整測，其餘格式驗證）。注意：50 個不同邏輯的項目不觸發，直接全展。
DataTable 特殊規則： 跨表引用透過 Key 追蹤（備註標 [引用]）；「還沒製作」欄位跳過；額外展開關聯完整性驗證（外鍵存在性、ID 唯一性、必填非空、數值範圍合理性）。
觸發條件： 收到任何規格準備展開時。
1. 掃描規格，識別引用外部資料的線索（ID/Key/Code、提到其他頁籤、「參照 XXX」） 2. 建立引用清單（本規格定義什麼 / 引用什麼外部資料） 3. 檢查引用資料是否已提供：有 → 完整讀取；沒有 → 主動問用戶 4. 全部關聯確認後，列出完整結構讓用戶確認 5. 確認後才展開
禁止： 看到引用不追蹤、沒看到關聯表就假設不存在、不問就猜。
步驟和預期結果都禁止使用「是否」。必須用肯定句。
原因：「是否」= 問題不是答案。測試人員需要知道「正確的結果是什麼」。
有「通過/成功/允許」語義的正面測項，自動補一條反面測項。
[自動產生反面測試] + 對應正面編號UI 規格的預期結果允許寫「與設計稿 [XXX] 一致」。
備註必須附設計稿引用（名稱或連結），讓測試人員找得到。
建立時機： 在任何 Sheet 中第一次展開測試項目時，自動建立「測試進度總覽」分頁。
位置： 永遠在 Sheet 最前面（index=0）
結構： Row 1 標題行（深橄欖色背景+白色粗體 fontSize 14）；Row 2+ 每行一個測試項目分頁；最下方總計行。
欄位：
| 欄 | 標題 | 內容 |
|---|---|---|
| A | # | 序號 |
| B | 項目頁籤 | 分頁名稱 |
| C | 平台 | 倍數（通常=1） |
| D | 狀態欄 | 測試結果的欄位字母（=H） |
| E | 原測項數量 | 公式自動計算 |
| F | 測項數量 | =E-J-K |
| G | 已完成數量 | =PASS+FAIL |
| H | PASS | 自動統計 |
| I | FAIL | 自動統計（紅色文字） |
| J | N/A | 自動統計 |
| K | BLOCK | 自動統計 |
| L | 進度 | =G/F（百分比） |
| M | 通過率 | =H/F（百分比） |
自動維護： 展開新分頁時自動追加一行（分頁名+公式）；有總計行時更新 SUM 範圍；測試人員填 PASS/FAIL/N/A/BLOCK，總覽自動統計。
格式： FAIL 欄紅色文字、進度/通過率百分比格式、凍結第 1 行。