201 lines
6.7 KiB
Markdown
201 lines
6.7 KiB
Markdown
# 規劃 (Plan) - 多模型協作規劃
|
||
|
||
多模型協作規劃 - 上下文檢索 + 雙模型分析 → 生成逐步實作計畫。
|
||
|
||
$ARGUMENTS
|
||
|
||
---
|
||
|
||
## 核心協議 (Core Protocols)
|
||
|
||
- **語言協議**：與工具/模型互動時使用 **英文 (English)**，與使用者溝通時使用使用者的語言。
|
||
- **強制平行**：對 Codex/Gemini 的呼叫 **必須** 使用 `run_in_background: true` (包括單一模型呼叫，以避免阻塞主執行緒)。
|
||
- **程式碼主權 (Code Sovereignty)**：外部模型 **完全沒有檔案系統寫入權限**，所有修改均由 Claude 執行。
|
||
- **止損機制**：在驗證當前階段輸出之前，不要進入下一階段。
|
||
- **僅限規劃**：此指令允許讀取上下文並寫入 `.claude/plan/*` 計畫檔案，但 **絕對禁止修改生產程式碼**。
|
||
|
||
---
|
||
|
||
## 多模型呼叫規範
|
||
|
||
**呼叫語法** (平行處理：使用 `run_in_background: true`)：
|
||
|
||
```
|
||
Bash({
|
||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
|
||
ROLE_FILE: <角色提示詞路徑>
|
||
<TASK>
|
||
需求：<增強後的需求>
|
||
上下文：<檢索到的專案上下文>
|
||
</TASK>
|
||
輸出：包含偽代碼的逐步實作計畫。請勿修改任何檔案。
|
||
EOF",
|
||
run_in_background: true,
|
||
timeout: 3600000,
|
||
description: "簡短描述"
|
||
})
|
||
```
|
||
|
||
**模型參數說明**：
|
||
- `{{GEMINI_MODEL_FLAG}}`：當使用 `--backend gemini` 時，請替換為 `--gemini-model gemini-3-pro-preview` (注意後方空格)；對於 codex 請使用空字串。
|
||
|
||
**角色提示詞 (Role Prompts)**：
|
||
|
||
| 階段 | Codex | Gemini |
|
||
|-------|-------|--------|
|
||
| 分析 (Analysis) | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
|
||
| 規劃 (Planning) | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
|
||
|
||
**會話重用**：每次呼叫都會返回 `SESSION_ID: xxx`（通常由 wrapper 輸出），**必須儲存** 以供後續 `/ccg:execute` 使用。
|
||
|
||
**等待背景任務** (最大逾時 600000ms = 10 分鐘)：
|
||
|
||
```
|
||
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
|
||
```
|
||
|
||
**重要 (IMPORTANT)**：
|
||
- 必須指定 `timeout: 600000`，否則預設的 30 秒會導致提前逾時。
|
||
- 若 10 分鐘後仍未完成，請使用 `TaskOutput` 繼續輪詢，**絕對不要殺死進程 (Kill the process)**。
|
||
- 若因逾時跳過等待，**必須呼叫 `AskUserQuestion` 詢問使用者是否繼續等待或殺死任務。**
|
||
|
||
---
|
||
|
||
## 執行工作流
|
||
|
||
**規劃任務**：$ARGUMENTS
|
||
|
||
### 階段 1：完整上下文檢索 (Full Context Retrieval)
|
||
|
||
`[Mode: Research]`
|
||
|
||
#### 1.1 提示詞增強 (必須首先執行)
|
||
|
||
**必須呼叫 `mcp__ace-tool__enhance_prompt` 工具**：
|
||
|
||
```
|
||
mcp__ace-tool__enhance_prompt({
|
||
prompt: "$ARGUMENTS",
|
||
conversation_history: "<最近 5-10 輪對話>",
|
||
project_root_path: "$PWD"
|
||
})
|
||
```
|
||
|
||
等待增強後的提示詞，並在後續所有階段中 **將原始 $ARGUMENTS 替換為增強後的結果**。
|
||
|
||
#### 1.2 上下文檢索
|
||
|
||
**呼叫 `mcp__ace-tool__search_context` 工具**：
|
||
|
||
```
|
||
mcp__ace-tool__search_context({
|
||
query: "<基於增強後需求的語義查詢>",
|
||
project_root_path: "$PWD"
|
||
})
|
||
```
|
||
|
||
- 使用自然語言構建語義查詢 (Where/What/How)。
|
||
- **絕對不要基於假設進行回答。**
|
||
- 若 MCP 不可用：回退到使用 Glob + Grep 進行檔案發現與關鍵符號定位。
|
||
|
||
#### 1.3 完整性檢查
|
||
|
||
- 必須獲取相關類別、函式、變數的 **完整定義與簽名**。
|
||
- 若上下文不足，觸發 **遞迴檢索**。
|
||
- 優先輸出：入口檔案 + 行號 + 關鍵符號名稱；僅在消除歧義必要時加入最小代碼片段。
|
||
|
||
#### 1.4 需求對齊
|
||
|
||
- 若需求仍有歧義，**必須** 輸出引導性問題供使用者回答。
|
||
- 直到需求邊界清晰 (無遺漏、無冗餘)。
|
||
|
||
### 階段 2：多模型協作分析 (Multi-Model Collaborative Analysis)
|
||
|
||
`[Mode: Analysis]`
|
||
|
||
#### 2.1 分派輸入
|
||
|
||
**平行呼叫** Codex 與 Gemini (`run_in_background: true`)：
|
||
|
||
將 **原始需求** (不帶預設意見) 分派給兩個模型：
|
||
|
||
1. **Codex 後端分析**：
|
||
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
|
||
- 關注點：技術可行性、架構影響、效能考量、潛在風險。
|
||
- 輸出：多維度解決方案 + 優缺點分析。
|
||
|
||
2. **Gemini 前端分析**：
|
||
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
|
||
- 關注點：UI/UX 影響、使用者體驗、視覺設計。
|
||
- 輸出：多維度解決方案 + 優缺點分析。
|
||
|
||
使用 `TaskOutput` 等待兩個模型的完整結果。**儲存 SESSION_ID** (`CODEX_SESSION` 與 `GEMINI_SESSION`)。
|
||
|
||
#### 2.2 交叉驗證
|
||
|
||
整合觀點並進行優化迭代：
|
||
|
||
1. **識別共識** (強力信號)。
|
||
2. **識別分歧** (需要權衡)。
|
||
3. **優勢互補**：後端邏輯以 Codex 為準，前端設計以 Gemini 為準。
|
||
4. **邏輯推理**：消除方案中的邏輯漏洞。
|
||
|
||
#### 2.3 (選擇性但建議執行) 雙模型計畫草案
|
||
|
||
為了減少 Claude 綜合計畫中的遺漏風險，可以平行要求兩個模型輸出「計畫草案」 (依然 **不允許** 修改檔案)：
|
||
|
||
1. **Codex 計畫草案** (後端權威)：
|
||
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
|
||
- 輸出：逐步計畫 + 偽代碼 (關注點：資料流/邊緣情況/錯誤處理/測試策略)。
|
||
|
||
2. **Gemini 計畫草案** (前端權威)：
|
||
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
|
||
- 輸出：逐步計畫 + 偽代碼 (關注點：資訊架構/互動/無障礙/視覺一致性)。
|
||
|
||
使用 `TaskOutput` 等待結果，記錄建議中的關鍵差異。
|
||
|
||
#### 2.4 生成實作計畫 (Claude 最終版本)
|
||
|
||
綜合雙方分析，生成 **逐步實作計畫**：
|
||
|
||
```markdown
|
||
## 實作計畫：<任務名稱>
|
||
|
||
### 任務類型
|
||
- [ ] 前端 (→ Gemini)
|
||
- [ ] 後端 (→ Codex)
|
||
- [ ] 全端 (→ 平行處理)
|
||
|
||
### 技術方案
|
||
<從 Codex + Gemini 分析中綜合出的最佳方案>
|
||
|
||
### 實作步驟
|
||
1. <步驟 1> - 預期交付物
|
||
2. <步驟 2> - 預期交付物
|
||
...
|
||
|
||
### 關鍵檔案
|
||
| 檔案 | 操作 | 描述 |
|
||
|------|-----------|-------------|
|
||
| path/to/file.ts:L10-L50 | 修改 | 描述 |
|
||
|
||
### 風險與修補建議
|
||
| 風險 | 修補建議 |
|
||
|------|------------|
|
||
|
||
### SESSION_ID (供 /ccg:execute 使用)
|
||
- CODEX_SESSION: <session_id>
|
||
- GEMINI_SESSION: <session_id>
|
||
```
|
||
|
||
### 階段 2 結束：計畫交付 (而非執行)
|
||
|
||
**`/ccg:plan` 的職責到此結束，必須執行以下動作**：
|
||
|
||
1. 向使用者展示完整的實作計畫 (包含偽代碼)。
|
||
2. 將計畫儲存至 `.claude/plan/<功能名稱>.md` (從需求中擷取功能名稱，例如：`user-auth`, `payment-module`)。
|
||
3. 以 **粗體文字** 輸出提示訊息 (必須使用實際儲存的檔案路徑)：
|
||
|
||
---
|
||
**計畫已生成並儲存至 `.claude/plan/實際功能名稱.md`**
|