architect

摘要

Agent: architect (architect)
Confidence: 61%
Cost: $2.2508
Duration: 11m 28s
Task ID: 900f7210-d54c-4970-b0dc-f82b73f7eb6c

★ Insight ─────────────────────────────────────
本次架構設計的三個關鍵決策：

  1. Worktree 放 ext4 而非 9p：/mnt/d 是 WSL2 透過 Plan 9 protocol 掛載的 NTFS，I/O 性能比 native ext4 慢 3-10 倍。把 worktree 放在 /home/arc/worktrees/ 可以大幅提升 git 操作和 TypeScript 編譯的速度，同時透過 symlink 回指 /mnt/d/.../soul/ 保持 runtime state 共享。

  2. Programmer/Reviewer 不感知 worktree：worktree 的建立和清理完全在 worker-scheduler.ts 的 executeTask() 中處理，agent 只知道自己的 cwd 已經被設定好。這避免了在所有 agent 的 systemPrompt 中加入 worktree 知識，降低了 prompt 複雜度和出錯機會。

  3. Per-agent 序列化改為條件式：核心瓶頸是 reservedAgents Set，它讓同類 agent 不能並行。改造後，有 worktree 的 code agent 不再受此限制（因為各自在獨立目錄工作），而 secretary 的 merge 操作仍序列化（因為 merge 到 main 天然需要序列化）。
    ─────────────────────────────────────────────────

技術方案已產出，存放在 soul/agent-reports/architect/git-worktree-isolation-spec-2026-02-26.md。

摘要

核心改動（5 個檔案）

檔案 改動
新增 src/agents/worktree-manager.ts Worktree 生命週期管理（建立、symlink、清理、孤兒回收）
改 src/agents/worker-scheduler.ts executeTask() 指向 worktree cwd；per-agent 序列化改為條件式
改 src/mcp/bot-tools-server.ts dispatch_task 繼承父 task 的 worktree 路徑
改 soul/agents/secretary.json 新 systemPrompt（branch + PR 流程）+ 新增 gh pr 權限
改 src/agents/agent-config.ts AgentTask 增加 worktreePath, branchName 欄位

5 個 Phase 的實施順序

  1. Phase 1 — Worktree 基礎設施（低風險，純新增）
  2. Phase 2 — Worker spawner 改造（中風險，cwd 指向 worktree）
  3. Phase 3 — Secretary workflow 改造（高風險，git 工作流程改變）
  4. Phase 4 — 放開 concurrency 限制（中風險，性能改善）
  5. Phase 5 — Molt 自動化（低風險，便利性）

關鍵風險與緩解

  • WSL2 symlink：✅ 低風險（已驗證跨 fs symlink 正常）
  • node_modules symlink：⚠️ 低風險（需 Phase 1 手動測試 tsgo）
  • 記憶體壓力：⚠️ 中等（7.7GB RAM，最壞 4GB 使用 → 可承受）
  • Merge conflict：⚠️ 中等（secretary concurrency=1 序列化，衝突時回報 CTO）
  • Worktree 清理失敗：✅ 低風險（fallback rm -rf + prune）

開放問題（需 CEO 決策）

  1. PR 自動 merge 還是等人工 approve？
  2. gh CLI 是否已安裝並認證？
  3. blog-writer 是否也需要 worktree？