# SKILL-023：規格書轉 MD

> 將任何格式的 Google Sheet 規格書轉換為統一結構的 MD 檔案，供 AI 讀取展開測試項目。

---

## 概述

| 項目 | 說明 |
|------|------|
| 觸發 | 用戶說「轉換 XX 規格書」或「規格書更新了」 |
| 輸入 | Google Sheet 連結 + 指定頁籤（或全部） |
| 輸出 | 統一格式 MD 檔案 + 轉換報告 |
| 執行者 | qa-sheet-worker |
| Schema | `/root/.agend/wiki/specs/_schema.md` |

---

## 轉換流程

```
Step 1：用戶提供 Sheet 連結 + 指定頁籤
Step 2：qa-sheet-worker 用 API 讀取（includeGridData=True）
Step 3：程式化判斷每行狀態（hidden/背景色/刪除線/移除標記）
Step 4：按 _schema.md 格式轉換為 MD
Step 5：產出 MD 檔案 + _index.md + 轉換統計報告
Step 6：用戶確認（首次轉換需逐章節確認）
```

---

## 轉換規則

### 狀態判斷（程式化，非 AI 判斷）

| Sheet 特徵 | MD 狀態 |
|-----------|---------|
| 正常可見行 | ✅ |
| hidden=true | 🔒 |
| 背景灰色 | 💡 |
| 文字刪除線 | ❌ |
| 內容含「移除」「刪除」+日期 | ❌(日期) |
| 灰色+刪除線 | ❌ |

### 層級判斷

| Sheet 特徵 | MD 層級 |
|-----------|---------|
| 合併儲存格（跨欄） | 章節標題（## H2） |
| 粗體/較大字 | 子章節（### H3） |
| 一般行 | 項目（清單項） |

### 缺少欄位

- 必填欄位缺少 → 標 `[⚠️ 缺少：欄位名]`
- 建議填欄位缺少 → 用 `[未提供]` 佔位
- 選填欄位缺少 → 省略不寫

---

## 產出檔案結構

```
wiki/specs/
  _schema.md              ← 格式規範
  [遊戲代號]/
    _index.md             ← 頁籤目錄 + meta
    [頁籤名].md           ← 各頁籤轉換結果
```

### 命名規則

| 項目 | 規則 | 範例 |
|------|------|------|
| 遊戲資料夾 | 遊戲代號（英文） | `A9+/`、`A8+/`、`ladybug/` |
| 頁籤檔名 | 小寫英文+連字號 | `system-settings.md` |

---

## 轉換統計報告

每次轉換完成後必須回報：

```
轉換完成：
- 總行數：X 行
- ✅ 有效：X 項
- 🔒 隱藏：X 項
- ❌ 已移除：X 項
- 💡 灰色：X 項
- 章節數：X 個
- 缺少必填欄位：X 個（列出）
```

---

## 同步規則（規格書更新時）

| 步驟 | 做法 |
|------|------|
| 觸發 | 用戶說「規格更新了」 |
| 方式 | 全量重轉（覆蓋舊檔） |
| 合併 | `[未提供]` → 有新值則覆蓋；已有值 → 不覆蓋；衝突 → 標 `[衝突]` |
| AI 補充 | 永遠不覆蓋（用戶確認過的） |
| 產出 | diff 報告：「新增 X 項、修改 X 項、移除 X 項」 |

---

## 紀律（qa-sheet-worker 遵守）

1. 用 `includeGridData=True` 讀取，不遺漏隱藏行/格式資訊
2. 嚴格按 _schema.md 格式產出，不自創結構
3. 不修改原始內容，忠實轉換
4. 轉換後必須產出統計報告

---

## 涉及機器人

| 機器人 | 角色 |
|--------|------|
| qa-sheet-worker | 執行轉換 |
| general | 協調、觸發 |
| qa-test-expander | 使用轉換後的 MD 展開測項 |