| name | battle-management |
| description | **Roadmap — 尚未實作。** Battle management system (Code Quest RPG vision) — AI dispatch, multi-battle handling, worktree-based battle isolation. See `rpg-roadmap` / `project-overview` for framing. Use when designing future combat flow, planning parallel AI battles, or reading legacy design docs.
|
戰鬥管理系統 - 多 AI 並行戰鬥設計（Roadmap，尚未實作）
⚠️ 本 skill 描述 Code Quest RPG 願景的戰鬥系統，目前 cc-office 未實作。當前專案是 Claude Code web client — 現況見 project-overview。
核心設計理念
Code Quest 採用 Dragon Quest (DQ) 風格 的戰鬥管理：
- 單一焦點：同一時間只顯示一場戰鬥（全螢幕）
- 選單驅動：使用彈出式選單切換戰鬥（非持續顯示的 Tab）
- 沉浸式體驗：保持傳統 RPG 的視覺純粹性
同時支援多 AI 並行：可以同時派遣 Haiku、Sonnet、Opus 三個 AI 代理處理不同任務。
混合方案：派遣 + 快速選單
設計決策
經過多方案比較，選擇了混合方案：
| 方案 | DQ純粹性 | 便利性 | 採用 |
|---|
| 純派遣系統 | ⭐⭐⭐⭐⭐ | ⭐⭐ | ❌ 太純粹，缺乏監控 |
| PIP子視窗 | ⭐ | ⭐⭐⭐⭐ | ❌ 破壞沉浸感 |
| Tab分頁系統 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ 持續顯示Tab列 |
| 混合方案 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ 平衡最佳 |
混合方案特點：
- ✅ 主要模式：背景派遣（不可見）
- ✅ 便利補充：DQ風格彈出選單（按需顯示）
- ✅ 完美平衡：保持沉浸感 + 提供監控能力
派遣系統 (6 步驟)
步驟 1：進入派遣介面
觸發方式：
- 城鎮「公會大廳」→「派遣任務」
- 野外遇到任務時選擇「派遣代理」
步驟 2：選擇 AI 代理
三種 AI 代理：
| 代理 | 特性 | MP消耗 | 適用場景 |
|---|
| Haiku 🌸 | 速度快、成本低 | 5 MP/回合 | 簡單任務、快速迭代、測試想法 |
| Sonnet 🎵 | 平衡、可靠 | 15 MP/回合 | 一般開發任務、程式碼重構 |
| Opus 👑 | 強大、深思熟慮 | 50 MP/回合 | 複雜架構、關鍵決策、棘手Bug |
選擇建議：
- 簡單 Bug 修復 → Haiku（快速、便宜）
- 功能開發 → Sonnet（平衡、可靠）
- 架構重構 → Opus（強大、深思）
步驟 3：選擇監控模式
三種監控模式：
| 模式 | 說明 | 適用情境 |
|---|
| 完全背景 🔇 | AI自主工作，只在需要決策時通知 | 簡單任務、信任AI能力 |
| 觀察模式 👁️ | 可透過快速選單查看進度，不主動通知 | 想掌握進度，但不想被打斷 |
| 即時監控 📺 | 切換到該戰鬥畫面，即時查看AI動作 | 學習、調試、關鍵任務 |
模式選擇建議：
- 高信任：完全背景（「交給AI，我去做其他事」）
- 中等信任：觀察模式（「我想知道進度，但不想一直盯著」）
- 學習/調試：即時監控（「我想看AI怎麼做」）
步驟 4：選擇工作環境
兩種環境選項：
| 環境 | 視覺標示 | 說明 | 適用情境 |
|---|
| 當前目錄 | 🔵 藍色 | 直接在專案目錄工作 | 小型修改、測試 |
| Worktree 隔離 | 🟣 紫色 | 建立獨立工作樹，完全隔離 | 大型重構、實驗性功能 |
設計理由：
- 視覺區分：顏色讓你一眼看出戰鬥的隔離狀態
- 風險提示：當前目錄會提示風險，引導複雜任務使用Worktree
- 自動建議：系統根據任務複雜度自動推薦環境
步驟 5：自動戰鬥設定
AI 可自動處理：
- ✅ 選擇工具（Read, Write, Grep等）
- ✅ 讀取檔案
- ✅ 編輯程式碼
- ✅ 執行測試
- ✅ 簡單git操作（add, commit）
需要玩家決策：
- ❌ git push（影響遠端）
- ❌ 刪除檔案（不可逆）
- ❌ 安裝新套件（改變依賴）
- ❌ 修改設定檔（影響專案）
- ❌ 遇到複雜錯誤（需要策略）
平衡點：
- 90% 操作自動化（便利）
- 10% 關鍵操作需確認（安全）
步驟 6：派遣確認
確認派遣後：
- AI 開始在背景工作
- 玩家回到主畫面繼續自己的戰鬥/探索
- 可透過快速選單隨時查看進度
快速切換選單（DQ風格）
觸發方式
按下 Tab 或 Q 鍵 → 彈出選單
選單設計
┌─────────────────────────────────┐
│ 🎯 活躍戰鬥列表 │
├─────────────────────────────────┤
│ │
│ 1. 🔵 [Haiku] 實作登入功能 │
│ HP: ████████░░ 80% │
│ 進度: 步驟 3/5 │
│ 最後動作: 編輯 auth.ts │
│ │
│ 2. 🔵 [Sonnet] 修復支付流程 ⭐ │
│ HP: ██████████ 100% │
│ 進度: 等待決策 ⚠️ │
│ 需要: git push 確認 │
│ │
│ 3. 🟣 [Opus] 重構資料庫架構 │
│ HP: ████░░░░░░ 40% │
│ 進度: 步驟 8/12 (worktree) │
│ 最後動作: 執行測試 │
│ │
│ [選擇戰鬥 1-3] [ESC 關閉] │
│ │
└─────────────────────────────────┘
視覺標示
- 🔵 藍色圖示：當前目錄戰鬥
- 🟣 紫色圖示：Worktree隔離戰鬥
- ⭐ 星號：目前聚焦的戰鬥
- ⚠️ 警告：需要玩家決策
操作方式
- 按
1-3 數字鍵：快速切換到該戰鬥
- 按
ESC 或再按 Tab：關閉選單
為何使用彈出選單而非Tab列？
彈出選單的優勢：
- ✅ 只在需要時顯示（符合DQ「選單隱藏」哲學）
- ✅ 視覺設計完全DQ化（黑底金框）
- ✅ 單一戰鬥時畫面完全乾淨
- ✅ 顯示更豐富的資訊（不只標題）
Tab列的問題：
- ❌ 持續顯示在畫面上（即使只有一場戰鬥）
- ❌ 讓遊戲感覺像「瀏覽器」或「IDE」
- ❌ 破壞DQ沉浸感
四層 UI 架構
第 1 層：主戰鬥畫面
- 功能：顯示當前聚焦的戰鬥
- 特點：全螢幕、單一焦點、沉浸式
- 設計：完全DQ風格（黑底、金框、選單式）
第 2 層：快速切換選單
- 功能：列出所有活躍戰鬥、顯示關鍵資訊
- 觸發：按
Tab 或 Q
- 設計：DQ傳統彈出選單
第 3 層：通知系統
- 功能：背景戰鬥需要決策時通知
- 位置：畫面右上角（非侵入式）
- 類型：
- ⚠️ 需要決策（黃色，中優先級）
- ✅ 戰鬥完成（綠色，低優先級）
- ❌ 遇到錯誤（紅色，高優先級）
- 🔋 MP不足（黃色，中優先級）
第 4 層：戰鬥歷史記錄
- 功能：記錄所有戰鬥的完整歷史
- 觸發：按
H 鍵或在選單選擇「查看歷史」
- 用途：學習AI策略、調試、回顧錯誤
完整使用流程示例
流程 1：派遣一個簡單任務
1. 在「公會大廳」選擇「派遣任務」
2. 輸入：「修復登入頁面的 CSS 問題」
3. 選擇 Haiku（簡單任務，速度快）
4. 選擇「完全背景」模式（信任AI）
5. 選擇「當前目錄」環境（小修改）
6. 確認派遣 → AI開始工作
7. 玩家繼續探索/購物
8. 5分鐘後收到通知：✅ Haiku完成！
9. 獲得獎勵：+50 EXP, +20 Gold
流程 2：監控複雜任務
1. 派遣任務：「重構資料庫架構，改用 PostgreSQL」
2. 選擇 Opus（複雜任務）
3. 選擇「即時監控」模式（想要學習）
4. 選擇「Worktree 隔離」環境（大型重構）
5. 畫面切換到 Opus 的戰鬥
6. 即時看到 Opus 的每個動作：
- [回合 1] Read database.ts
- [回合 2] Grep 搜尋相關程式碼
- [回合 3] 請求決策：「是否安裝 PostgreSQL？」
- [回合 4-8] 修改程式碼、執行測試、修復錯誤
7. 戰鬥完成：+500 EXP, +200 Gold
8. 獲得成就「資料庫大師」
流程 3：並行管理多個任務
1. 派遣三個任務：
- Haiku: 「更新 README」（完全背景）
- Sonnet: 「實作設定頁面」（觀察模式）
- Opus: 「優化 API」（觀察模式）
2. 玩家繼續自己的工作（在「商業街」購物）
3. 收到通知：⚠️ Sonnet需要決策
4. 按 Tab 開啟快速選單：
- 看到三個戰鬥的狀態
- Haiku: 進度 4/5
- Sonnet: 等待決策 ⚠️
- Opus: 進度 2/8
5. 按 2 切換到 Sonnet 戰鬥
- 查看詳情後批准安裝套件
6. 按 Tab 回到選單，選擇回到自己的戰鬥
7. 最終三個任務都完成
- 總共獲得 800 EXP, 350 Gold
視覺區分設計
環境類型的顏色標示
當前目錄戰鬥（藍色）：
⚔️ 🔵 戰鬥：修復 CSS 問題 (Haiku)
- 代表直接在專案目錄工作
- 風險：可能影響其他進行中的工作
Worktree 隔離戰鬥（紫色）：
⚔️ 🟣 戰鬥：重構資料庫 (Opus) [WORKTREE]
工作樹: /worktrees/db-refactor
- 代表在隔離環境中工作
- 優點：完全隔離，不互相干擾
- 完成後需要合併回主分支
戰鬥狀態的標示
- 一般戰鬥：正常顯示
- 需要決策：⚠️ + [需要決策] 標籤 + 黃色高亮
- 戰鬥完成：✅ + [完成] 標籤 + 綠色高亮
- 戰鬥失敗：❌ + [失敗] 標籤 + 紅色高亮
關鍵設計決策說明
為何選擇混合方案而非純派遣？
雖然純派遣系統DQ純粹性最高，但實際使用場景顯示：
- 開發者需要監控AI進度（完全看不到會造成焦慮）
- 新手想要學習AI如何解決問題（即時監控有教育價值）
- 初期用戶需要透過觀察建立信任
平衡點：
- 預設使用派遣系統（維持DQ風格）
- 提供快速選單查看進度（滿足監控需求）
- 選單採用DQ傳統彈出式設計（不破壞沉浸感）
為何背景戰鬥不可見？
同時顯示多個戰鬥違反DQ核心設計哲學：
- 單一焦點原則：DQ設計的核心是「同一時間只專注一件事」
- 視覺清晰度：PIP視窗會遮擋主畫面、讓畫面擁擠
- 心理負擔：同時看到多個戰鬥增加認知負擔
替代方案：
- 使用通知系統（非侵入式）
- 使用快速選單（主動查看）
- 平衡了可見性與沉浸感
為何自動戰鬥不完全自動？
某些操作具有不可逆性或外部影響：
- 不可逆操作：刪除檔案無法復原
- 外部影響：git push影響遠端儲存庫和其他開發者
- 風險控制：修改設定檔可能影響整個專案
- 學習機會：關鍵決策點提供教育價值
與其他系統的整合
與場景系統的整合
- 派遣任務屬於「公會大廳」場景
- 查看戰鬥屬於「戰鬥」場景
- 切換戰鬥 = 切換場景
與Worktree系統的整合
- 紫色標示 Worktree 戰鬥
- 藍色標示當前目錄戰鬥
- 複雜任務自動建議使用 Worktree
快捷鍵總覽
Tab 或 Q：開啟快速切換選單1-3：選擇對應戰鬥（在選單中）ESC：關閉選單H：查看戰鬥歷史
相關文檔
想了解更多？查看：
- 專案總覽：
/project-overview
- 地圖系統：
/map-system
- 詳細設計文檔：
docs/ui-design/05-BATTLE-MANAGEMENT.md
- 戰鬥系統技術文檔：
docs/ui-design/systems/03-battle-system.md
記住：Code Quest 的戰鬥管理在保持 DQ 沉浸感的同時，提供了現代多任務管理的便利性！
