battle-management

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 沉浸感的同時，提供了現代多任務管理的便利性！