reporting-governance-plugin/docs/plans/2026-04-07-agent-workspace-layout.md

功能型 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 根本沒吃到」的問題。