docs: require per-agent dedicated workspaces
This commit is contained in:
Eve
318
docs/plans/2026-04-07-agent-workspace-layout.md
Normal file
318
docs/plans/2026-04-07-agent-workspace-layout.md
Normal file
@@ -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 根本沒吃到」的問題。
|
||||
Reference in New Issue
Block a user