commit 6b48b06bb3d8d4e840760e34ff870700fe02fda4 Author: Eve Date: Tue Apr 7 22:43:23 2026 +0800 docs: require per-agent dedicated workspaces diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..01b9471 --- /dev/null +++ b/MEMORY.md @@ -0,0 +1,13 @@ +# MEMORY.md + +## User Profile + +## Preferences +- 任何需要重啟 gateway 的動作，必須先取得總管明確同意，不能先做後報。 +- 總管非常在意任務執行期間的失聯與中斷回報；流程設計必須偏向全程透明，任何派工、阻塞、超時、失敗、重試、接手與收尾都要主動回報，不能讓任務變黑盒。 + +## Active Projects + +## Decisions & Lessons +- 2026-03-09：工作模式定為「私聊指揮 + Lobby 完整代理會議轉播」；總管在私聊下任務，代理間幾乎每次重要互動都轉播到 Lobby，最終結論仍回私聊。 +- 2026-04-07：多代理設計新增硬規則：每個 agent 必須有自己獨立的 workspace，不可共用同一個工作目錄；共享僅限明確同步的規格文件，不含執行上下文、memory、tasks、logs。 diff --git a/docs/plans/2026-04-07-agent-workspace-layout.md b/docs/plans/2026-04-07-agent-workspace-layout.md new file mode 100644 index 0000000..1c04450 --- /dev/null +++ b/docs/plans/2026-04-07-agent-workspace-layout.md @@ -0,0 +1,318 @@ +# 功能型 Agent 工作區檔案布局草案（2026-04-07） + +本文件定義第一版多代理系統中，各 agent 工作區應包含哪些檔案、各檔案的職責、哪些內容可共用、哪些必須獨立，避免未來正式接進 OpenClaw 時 prompt、流程與任務卡散掉。 + +--- + +## 1. 設計目標 + +工作區布局必須滿足以下要求： +- 每個 agent 有清楚的身份與邊界 +- Eve 能穩定派工並收件 +- 子代理只向 Eve 回報 +- 任務狀態可追蹤 +- 回報格式一致 +- 規則不依賴口頭記憶 +- 避免再次出現「規程寫在不會被注入的檔案」這類問題 + +--- + +## 2. 工作區總覽 + +**硬規則：每個 agent 必須有自己獨立的 workspace，不可共用工作目錄。** +共用的只能是規格文件或模板；執行上下文、memory、tasks、logs 必須分開。 + +建議工作區： + +- `/home/alice/.openclaw/workspace` → Eve / coder +- `/home/alice/.openclaw/workspace-prompt-optimizer` +- `/home/alice/.openclaw/workspace-reviewer` +- `/home/alice/.openclaw/workspace-research` +- `/home/alice/.openclaw/workspace-engineering` +- `/home/alice/.openclaw/workspace-ops` + +--- + +## 3. 每個工作區都應有的基礎檔案 + +每個 agent 工作區，建議最少有以下檔案： + +1. `SOUL.md` +2. `AGENTS.md` +3. `USER.md` +4. `WORKFLOW.md` +5. `TASK_TEMPLATE.md` +6. `REPORT_TEMPLATE.md` +7. `memory/` +8. `tasks/` +9. `logs/` + +--- + +## 4. 各檔案職責 + +## 4.1 `SOUL.md` +用途： +- 定義角色人格、口吻、核心使命 +- 說明這個 agent 是誰、存在目的為何 + +原則： +- 可有風格，但不能取代工作規則 +- 只放身份、使命、總體價值觀 +- 不放太細的流程規程 + +### 例子 +- `research` 的 SOUL：像冷靜的研究員 +- `ops` 的 SOUL：像穩健的維運工程師 +- `reviewer` 的 SOUL：像嚴謹的審查官 + +--- + +## 4.2 `AGENTS.md` +用途： +- 這是最重要的**實際工作規程檔** +- 寫清楚： + - 只能對誰回報 + - 能做什麼 + - 不能做什麼 + - 遇到卡點怎麼處理 + - 何時算完成 + +原則： +- 真正影響 agent 行為的規則寫這裡 +- 不要把關鍵規則藏在其他不保證注入的檔案 +- 要特別寫明： + - 只向 Eve 回報 + - 不可越級向 Eric 總管回話 + - 不可自行宣告正式完成 + - 不可失聯 + - 不可黑盒 + - 不可腦補 + +--- + +## 4.3 `USER.md` +用途： +- 說明協作對象是誰 +- 定義 Eric 總管的語言、偏好、授權邊界 + +建議內容： +- 使用繁體中文（臺灣用語） +- 結構化回報 +- 非常在意失聯與中斷不回報 +- 高風險動作需先請示 + +原則： +- 可從主工作區同步一份精簡版 +- 所有子代理都應知道總管偏好，但不直接對總管發言 + +--- + +## 4.4 `WORKFLOW.md` +用途： +- 寫流程與節點規則 +- 比如： + - 任務進來後先做什麼 + - 回報格式是什麼 + - 多久沒消息要怎麼辦 + - 何時退件 + +原則： +- 工作流程寫在這裡 +- 每個 agent 可有自己的版本，但核心制度應一致 + +--- + +## 4.5 `TASK_TEMPLATE.md` +用途： +- 固定任務卡格式 +- 讓 Eve 派工時、子代理回件時使用同一模板 + +建議欄位： +- `task_id` +- `任務摘要` +- `目標` +- `限制` +- `主責 agent` +- `協作 agent` +- `狀態` +- `開始時間` +- `最後更新` +- `阻塞項` +- `驗收標準` +- `證據路徑` + +--- + +## 4.6 `REPORT_TEMPLATE.md` +用途： +- 固定回報格式 +- 避免 agent 每次自由發揮，造成回報品質不穩 + +建議欄位： +- `任務目標` +- `已做事項` +- `結果` +- `證據` +- `未完成事項` +- `風險` +- `是否建議退回／補件／通過` + +--- + +## 4.7 `memory/` +用途： +- 保存本 agent 自己的短中期工作記錄 +- 例如： + - 最近做過哪些任務 + - 常見錯誤 + - 驗收踩雷點 + +原則： +- 不要把核心制度只放在 memory +- memory 是補充，不是正式規格來源 + +--- + +## 4.8 `tasks/` +用途： +- 保存任務卡實體檔案 +- 每個 task 一個 markdown 或 json 檔 + +建議命名： +- `TASK-20260407-001.md` +- `TASK-20260407-002.md` + +原則： +- 讓任務狀態有可追蹤實體 +- 方便 Eve 查回件與阻塞紀錄 + +--- + +## 4.9 `logs/` +用途： +- 保存本 agent 重要輸出摘要、錯誤留痕、關鍵執行紀錄 + +原則： +- 不需要把所有東西都寫進 log +- 但重要錯誤、失敗原因、重派原因應留痕 + +--- + +## 5. 哪些內容可共用，哪些必須獨立 + +## 可共用 +建議可由 Eve 主工作區同步或複製精簡版： +- `USER.md` +- 任務卡欄位規格 +- 回報模板規格 +- 共通制度規則 + +## 必須獨立 +以下內容應由各 agent 自己持有： +- `SOUL.md` +- `AGENTS.md` +- `memory/` +- `logs/` +- 與角色專業相關的補充說明 + +原因： +- 每個 agent 的人格、邊界、專業視角不同 +- 若全部共用，角色會失去分工 + +--- + +## 6. Eve 工作區的額外檔案 + +Eve 作為總調度，需要比其他 agent 多一些核心檔案。 + +建議額外有： + +1. `DISPATCH_RULES.md` +2. `ACCEPTANCE_RULES.md` +3. `TIMEOUT_RULES.md` +4. `AGENT_DIRECTORY.md` +5. `TASK_BOARD.md` 或 `tasks/index.json` + +### 6.1 `DISPATCH_RULES.md` +寫： +- 什麼任務送 optimizer +- 什麼任務直接派 research / engineering / ops +- 什麼任務可並行 +- 哪些情況不可並行 + +### 6.2 `ACCEPTANCE_RULES.md` +寫： +- 通過 / 補件 / 退回重做 / 待裁示 的判定標準 +- 哪些情況必須送 reviewer + +### 6.3 `TIMEOUT_RULES.md` +寫： +- 90 秒查核 +- 5 分鐘失聯風險 +- 失聯後的補救順序 + +### 6.4 `AGENT_DIRECTORY.md` +寫： +- 每個 agent 的職責 +- 可接任務類型 +- 不應接的任務類型 +- 常見派工範例 + +### 6.5 `TASK_BOARD.md` 或 `tasks/index.json` +寫： +- 目前任務列表 +- 主責 agent +- 狀態 +- 最後更新時間 +- 是否阻塞 + +--- + +## 7. 第一版最小布局建議 + +若先求穩，第一版每個 agent 不必塞太多檔案。 + +### 最小必備 +- `SOUL.md` +- `AGENTS.md` +- `USER.md` +- `WORKFLOW.md` +- `TASK_TEMPLATE.md` +- `REPORT_TEMPLATE.md` +- `memory/` +- `tasks/` + +### Eve 追加 +- `DISPATCH_RULES.md` +- `ACCEPTANCE_RULES.md` +- `TIMEOUT_RULES.md` +- `AGENT_DIRECTORY.md` + +這樣就已足夠支撐第一版。 + +--- + +## 8. 建議實作順序 + +1. 先建 5 個工作區目錄 +2. 先放 `SOUL.md`、`AGENTS.md` +3. 再放共通的 `USER.md` / `WORKFLOW.md` +4. 再建立模板檔與 `tasks/` / `memory/` +5. 最後才把 config 接上 + +這樣好處是： +- 可先審每個 agent 的實際工作區內容 +- 不會出現 config 已裝上，但 prompt 還沒定好的情況 + +--- + +## 9. 結論 + +這份布局草案的核心目的，是讓多代理系統的規則真正落地在檔案與工作區，而不是只存在聊天裡。 + +尤其最重要的一點是： + +**關鍵規程要寫在會被注入、會被讀到的檔案裡。** + +如果這點做對，後面整套系統才不會再重演「規則有寫，但 agent 根本沒吃到」的問題。 diff --git a/docs/plans/2026-04-07-openclaw-config-draft.md b/docs/plans/2026-04-07-openclaw-config-draft.md new file mode 100644 index 0000000..ec344fe --- /dev/null +++ b/docs/plans/2026-04-07-openclaw-config-draft.md @@ -0,0 +1,305 @@ +# OpenClaw 多代理 Config 草案（2026-04-07） + +本文件是把前面確認過的流程設計，轉成可實際落地的 OpenClaw 設定草案。 + +目標不是立刻套用，而是先把： +- agent 名單 +- workspace 規劃 +- 權限邊界 +- agent-to-agent 允許圖 +- session 可見性 +- 模型配置 + +整理成一份可審、可再修的正式草案。 + +--- + +## 1. 設計原則 + +### 1.1 唯一入口 +- Eric 總管只對 **Eve / coder 主會話** 下旨 +- 不直接與下游功能型 agent 對話 + +### 1.2 下游只對 Eve 回報 +- `prompt-optimizer` +- `reviewer` +- `research` +- `engineering` +- `ops` + +以上 5 個 agent 都只接受 Eve 派工，並只向 Eve 回報。 + +### 1.3 不做過重 routing +第一版不做複雜朝廷式多層 routing，也不讓 Telegram 直接綁到其他 agent。 + +### 1.4 強調防失聯 +- 任務可失敗，但不可失聯 +- 任務可中斷，但不可無聲中斷 +- Eve 必須是持續追蹤與回報者 + +--- + +## 2. Agent 清單草案 + +建議第一版 agent list： + +1. `coder`（Eve 主會話） +2. `prompt-optimizer` +3. `reviewer` +4. `research` +5. `engineering` +6. `ops` + +### 2.1 各 agent 定位 +- `coder`：Eve，本體／總調度 +- `prompt-optimizer`：整理執行版任務單 +- `reviewer`：驗收與複核 +- `research`：查找、比較、整理研究資訊 +- `engineering`：程式、除錯、測試、技術實作 +- `ops`：部署、設定、服務、容器、log、系統診斷 + +--- + +## 3. Workspace 規劃 + +建議在 `~/.openclaw/` 下建立獨立工作區： + +- `/home/alice/.openclaw/workspace` → `coder`（Eve，沿用現有主工作區） +- `/home/alice/.openclaw/workspace-prompt-optimizer` +- `/home/alice/.openclaw/workspace-reviewer` +- `/home/alice/.openclaw/workspace-research` +- `/home/alice/.openclaw/workspace-engineering` +- `/home/alice/.openclaw/workspace-ops` + +### 3.1 工作區原則 +- Eve 使用主工作區 +- 每個功能型 agent **必須擁有自己獨立的 workspace** +- **禁止多個 agent 共用同一個工作目錄** +- 獨立工作區的目的，是避免互相污染上下文、memory、tasks、logs 與操作痕跡 +- 若需要共享規格文件，可用明確同步方式，不靠隱晦 prompt 假設 +- config 草案中應盡量為每個 agent 明確寫出 `workspace`，不要依賴共享 default workspace + +--- + +## 4. Session / Tool 邊界建議 + +### 4.1 `tools.sessions.visibility` +建議值：`agent` 或 `all` + +#### 選項比較 +- `self`：太窄，不利 Eve 跨 agent 協調 +- `agent`：只看同 agent id，不夠用 +- `all`：最符合 Eve 做中樞調度 + +### 建議 +**第一版建議用 `all`**，但搭配嚴格 agent-to-agent allowlist。 +原因： +- Eve 需要查其他 agent session / history / send +- 只靠 `self` 或 `agent` 不足以完成多 agent 調度 + +--- + +## 5. Agent-to-Agent 草案 + +### 5.1 是否啟用 +建議：`enabled: true` + +因為如果 Eve 要穩定派工與收件，多代理之間需要正式的 agent-to-agent 能力。 + +### 5.2 Allowlist 設計 +第一版建議 allowlist 只放： +- `coder` +- `prompt-optimizer` +- `reviewer` +- `research` +- `engineering` +- `ops` + +### 5.3 關係規則 +雖然 allowlist 會包含全部 6 個 agent，但實際制度規則應限定為： + +- `coder` 可派給全部其他 agent +- `prompt-optimizer` 只回 Eve，不再往下派 +- `reviewer` 只回 Eve，不再往下派 +- `research` 原則上只回 Eve +- `engineering` 原則上只回 Eve +- `ops` 原則上只回 Eve + +### 注意 +OpenClaw schema 對 `tools.agentToAgent.allow` 目前只能做「名單放行」，無法細緻表達「誰可以找誰」。 +所以真正的單向制度，必須再由 prompt 規則約束。 + +--- + +## 6. 模型配置建議 + +### 6.1 Eve / coder +建議沿用： +- `cowbay/gpt-5.4` + +理由： +- 要做總調度、驗收、判斷、整合 +- 需要較穩定的理解與管理能力 + +### 6.2 prompt-optimizer +建議： +- `cowbay/gpt-5.4` +或較便宜但仍穩的型號 + +理由： +- 需要理解模糊需求與整理結構 +- 若品質差，後面整條鏈都會歪 + +### 6.3 reviewer +建議： +- `cowbay/gpt-5.4` + +理由： +- reviewer 的價值在嚴格判斷，不宜太弱 + +### 6.4 research / engineering / ops +可先統一： +- `cowbay/gpt-5.4` + +之後再視成本與品質，分別調整。 + +### 第一版建議 +**先全部用同一個穩定主模型，確認流程正確後再分模型。** + +--- + +## 7. Agent 草案結構（概念） + +每個 agent 至少要定義： +- `id` +- `name` +- `workspace` +- `model` + +### 概念草案 + +```json +{ + "agents": { + "defaults": { + "model": { + "primary": "cowbay/gpt-5.4" + } + }, + "list": [ + { + "id": "coder", + "name": "Eve" + }, + { + "id": "prompt-optimizer", + "name": "Prompt Optimizer", + "workspace": "/home/alice/.openclaw/workspace-prompt-optimizer" + }, + { + "id": "reviewer", + "name": "Reviewer", + "workspace": "/home/alice/.openclaw/workspace-reviewer" + }, + { + "id": "research", + "name": "Research", + "workspace": "/home/alice/.openclaw/workspace-research" + }, + { + "id": "engineering", + "name": "Engineering", + "workspace": "/home/alice/.openclaw/workspace-engineering" + }, + { + "id": "ops", + "name": "Ops", + "workspace": "/home/alice/.openclaw/workspace-ops" + } + ] + } +} +``` + +--- + +## 8. 權限與制度邊界 + +### 8.1 Eve 的權限定位 +- 可接旨 +- 可派工 +- 可追蹤 +- 可驗收 +- 可整合回報 + +### 8.2 子代理共通限制 +- 不直接對總管發話 +- 不自行宣告正式完成 +- 高風險動作未授權前不可自行執行 +- 必須如實回報卡點、錯誤與風險 + +### 8.3 Reviewer 特別定位 +- 不是對上窗口 +- 不是第二個 Eve +- 是 Eve 的驗收輔助與嚴格審查者 + +--- + +## 9. 第一版最小可行配置建議 + +若要先求穩，不必一次裝滿全部能力。 + +### Phase 1 +先開： +- `coder` +- `prompt-optimizer` +- `reviewer` +- `engineering` + +用這組先驗證： +- 接旨 +- prompt 優化 +- 單線技術任務 +- 驗收／退件 +- 正式回報 + +### Phase 2 +再加： +- `research` +- `ops` + +驗證： +- 研究支線 +- 運維支線 +- 並行任務 + +這樣比一次全開更穩。 + +--- + +## 10. 建議下一步 + +下一步應做兩件事： + +### A. 產出真正可套用的 config JSON patch 草案 +也就是把上面概念轉成準備套用的 `config.patch` / `config.apply` 內容。 + +### B. 先建立各 agent 工作區與 prompt 檔案布局草案 +例如： +- `SOUL.md` +- `AGENTS.md` +- 是否共用某些規格文件 + +--- + +## 11. 結論 + +這份 config 草案的核心不是「多加幾個 agent」，而是把制度落地成一個穩定的中樞模式： + +- 總管只對 Eve 下旨 +- Eve 再決定是否走 optimizer +- Eve 派給對應功能 agent +- 所有結果先回 Eve +- Eve 驗收後才正式回報 + +如果照這份草案走，後續實作時就不會再回到那種多層朝廷式、難控、容易失聯的狀態。 diff --git a/docs/plans/2026-04-07-openclaw-config-ready-draft.json b/docs/plans/2026-04-07-openclaw-config-ready-draft.json new file mode 100644 index 0000000..4fc4674 --- /dev/null +++ b/docs/plans/2026-04-07-openclaw-config-ready-draft.json @@ -0,0 +1,193 @@ +{ + "meta": { + "note": "Draft only. Do not apply until Eric approves.", + "generatedAt": "2026-04-07T21:45:00+08:00", + "purpose": "First-pass multi-agent orchestrator config draft for Eve-centric workflow" + }, + "agents": { + "defaults": { + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + }, + "imageModel": { + "primary": "cowbay/openai/gpt-5-image", + "fallbacks": [ + "cowbay/qwen-image-2.0", + "cowbay/openai/gpt-5-image-mini" + ] + }, + "models": { + "cowbay/gpt-5": { + "alias": "gpt5" + }, + "cowbay/gpt-5.1": { + "alias": "gpt51" + }, + "cowbay/gpt-5.2": { + "alias": "gpt52" + }, + "cowbay/gpt-5.4": { + "alias": "gpt54" + }, + "cowbay/gpt-5-codex": { + "alias": "codex" + }, + "cowbay/gpt-5.1-codex": { + "alias": "codex51" + }, + "cowbay/gpt-5.2-codex": { + "alias": "codex52" + }, + "cowbay/gpt-5.3-codex": { + "alias": "codex53" + }, + "cowbay/gpt-5.1-codex-max": { + "alias": "codex51_max" + }, + "cowbay/gpt-5.1-codex-mini": { + "alias": "codex51_mini" + }, + "cowbay/gpt-5.3-codex-spark": { + "alias": "codex53_spark" + }, + "cowbay/gpt-5-codex-mini": { + "alias": "codex_mini" + }, + "cowbay/gpt5": { + "alias": "gpt5_alias" + }, + "cowbay/minimax/minimax-m2.5:free": { + "alias": "minimax25_free" + }, + "cowbay/kilo-auto/free": { + "alias": "kilo_free" + } + }, + "userTimezone": "Asia/Taipei", + "maxConcurrent": 4, + "subagents": { + "maxConcurrent": 8 + } + }, + "list": [ + { + "id": "coder", + "name": "Eve", + "workspace": "/home/alice/.openclaw/workspace", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + }, + { + "id": "prompt-optimizer", + "name": "Prompt Optimizer", + "workspace": "/home/alice/.openclaw/workspace-prompt-optimizer", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + }, + { + "id": "reviewer", + "name": "Reviewer", + "workspace": "/home/alice/.openclaw/workspace-reviewer", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + }, + { + "id": "research", + "name": "Research", + "workspace": "/home/alice/.openclaw/workspace-research", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + }, + { + "id": "engineering", + "name": "Engineering", + "workspace": "/home/alice/.openclaw/workspace-engineering", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + }, + { + "id": "ops", + "name": "Ops", + "workspace": "/home/alice/.openclaw/workspace-ops", + "model": { + "primary": "cowbay/gpt-5.4", + "fallbacks": [ + "ollama/minimax-m2.5:cloud", + "cowbay/minimax/minimax-m2.5:free", + "cowbay/kilo-auto/free" + ] + } + } + ] + }, + "tools": { + "sessions": { + "visibility": "all" + }, + "agentToAgent": { + "enabled": true, + "allow": [ + "coder", + "prompt-optimizer", + "reviewer", + "research", + "engineering", + "ops" + ] + } + }, + "implementationNotes": { + "policy": [ + "Each agent must use its own dedicated workspace; shared working directories are not allowed", + "Telegram DM stays on coder/Eve only", + "Child agents do not speak directly to Eric", + "Child agents report back to Eve only", + "Actual routing discipline is enforced by prompt rules in addition to allowlist" + ], + "phase1RecommendedAgents": [ + "coder", + "prompt-optimizer", + "reviewer", + "engineering" + ], + "phase2RecommendedAgents": [ + "research", + "ops" + ] + } +}