[Docs] 中文架構分析 — Workspacefile 如同 AI Agent 的 Dockerfile

[Tony427]

動機

讀完原始碼後覺得這個專案的概念很棒，但目前缺少一份從「解決什麼問題」到「內部架構」的完整說明。
以下是我閱讀原始碼後整理的分析，供作者參考，歡迎作為文件素材使用。

---

解決什麼問題？

現在 AI Agent（Claude Code、Codex、Cursor 等）的工作空間都是 ad-hoc 拼湊的：

• 每個 runtime 有自己的設定格式（CLAUDE.md、AGENTS.md）
• MCP server 各自配置、prompt 散落各處
• 多 repo 組合沒有標準化方式
• 換一個 runtime 就要重新手動設定一次

awe 就是 AI Agent 工作空間的 Docker — 用一份宣告式 Workspacefile，build 出所有 runtime 的標準化 bundle。

核心架構（4 階段 Pipeline）

Workspacefile (宣告式 DSL)
      │
      ▼
┌──────────────┐
│  1. Parser   │  文字 → AST（逐行解析、引號感知）
│              │  產出: Document { Instruction[] }
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  2. Planner  │  AST → WorkspaceManifest
│              │  解析 keyword → 填充 manifest
│              │  讀取 prompt/MCP/overlay
│              │  驗證必填欄位
└──────┬───────┘
       │
       ▼
┌──────────────────┐
│  3. Materializer │  Manifest → 實體檔案
│                  │  複製/clone repo
│                  │  套用 overlay
│                  │  處理 attached repos
└──────┬───────────┘
       │
       ▼
┌──────────────┐
│  4. Exporter │  物化結果 → Runtime bundle
│              │  Auth 預檢
│              │  MCP 深度合併
│              │  各 runtime 專屬格式
└──────────────┘

DSL 關鍵字

Keyword	用途
VERSION	Schema 版本號
NAMESPACE	工作空間命名空間（必填）
NAME	工作空間名稱（必填）
FROM	基礎 repo — 本地路徑或 git URL（必填）
ATTACH	附加 repo，掛載到 _attached/
OVERLAY	覆蓋層目錄
PROMPT	引入 prompt 檔案
MCP	MCP 設定檔 / Server 定義
TOOLS	工具白名單
EXPORT	匯出目標 runtime（codex / claude / generic）

Build 產出結構

build/workspace/
├── workspace-manifest.json
├── control-plane-mapping.json
├── workspace/
│   ├── {base repo}
│   └── _attached/{alias}/
└── exports/
    ├── codex/
    │   ├── AGENTS.md
    │   ├── PROMPT.md
    │   ├── runtime.json
    │   └── mcp/merged.json
    └── claude/
        ├── CLAUDE.md
        ├── PROMPT.md
        ├── runtime.json
        └── mcp/merged.json

設計特色

特色	說明
零外部依賴	只用 Go 標準庫
Secrets 不落地	AUTH 只宣告策略，憑證在 build 環境
MCP 深度合併	多個 MCP FILE MERGE → 一份 merged.json
Auth 預檢	build 前驗證 ssh-agent / gh / glab
Overlay 機制	3 個候選路徑搜尋
Runtime 感知	MCP Server 可指定特定 runtime 生效

一句話總結

Workspacefile 之於 AI Agent，如同 Dockerfile 之於 Container。

---

此分析由閱讀原始碼後整理，如有不準確之處歡迎指正。