WorkBuddy Harness 架构图谱

分层视图

flowchart TB
  User["User"]
  Renderer["Renderer UI<br/>React/Vite assets"]
  Preload["Preload Bridge<br/>contextBridge + IPC"]
  Main["Electron Main<br/>window/auth/config/logging"]
  AppServer["Desktop App-Server<br/>daemon client + connector proxy"]
  Sidecar["Sidecar Manager<br/>control socket + process lifecycle"]
  CLI["codebuddy --serve<br/>CLI Harness"]
  ACP["ACP JSON-RPC over SSE<br/>/api/v1/acp"]
  REST["REST Gateway<br/>/api/v1/*"]
  Agent["Agent Loop<br/>model + tools + permissions"]
  Ext["Extensions<br/>Skills / Plugins / MCP"]
  Store["Persistence<br/>SQLite + JSONL + logs + tool-results"]

  User --> Renderer
  Renderer --> Preload
  Preload --> Main
  Main --> AppServer
  AppServer --> Sidecar
  Sidecar --> CLI
  CLI --> ACP
  CLI --> REST
  ACP --> Agent
  REST --> Agent
  Agent --> Ext
  Agent --> Store
  AppServer --> Store

为什么要有 sidecar

直接把 agent loop 放进 Electron renderer 有三个问题：

1. Renderer 是 UI 进程，不适合持有 shell、PTY、文件系统和长任务。
2. Agent session 需要可重启、可恢复、可隔离，进程边界比组件边界可靠。
3. CLI 本身也要独立作为终端工具、daemon、HTTP server、ACP server 使用。

所以 WorkBuddy 的边界是：

Desktop = 产品外壳 + 本地 orchestrator
CLI sidecar = agent runtime
ACP/REST = 两者之间的稳定协议

请求生命周期

一次用户发送消息，大致会经过：

sequenceDiagram
  participant R as Renderer
  participant M as Electron Main
  participant D as App-Server
  participant S as Sidecar
  participant C as CLI --serve
  participant A as Agent Loop

  R->>M: IPC / daemon client call
  M->>D: create or load session
  D->>S: session.create(command,cwd,port)
  S->>C: spawn codebuddy --serve --port <port>
  D->>C: POST /api/v1/acp initialize
  D->>C: POST /api/v1/acp session/load or session/new
  R->>C: session/prompt through daemon bridge
  C->>A: append user message
  A->>A: model -> tool call -> tool result -> model
  A-->>C: session/update events
  C-->>R: SSE chunks rendered into UI

Harness 子系统

子系统	WorkBuddy 中的观察	复刻时的最小实现
Agent Loop	CLI bundle 内的 session/prompt、tool calling、stream-json	while model wants tool: run tool and append result
Tool Registry	内置工具、MCP 工具、defer loading、ToolSearch	ToolRegistry + tool_search
Permission	--permission-mode、approval、sandbox rules	命令危险模式检测 + allow/deny
Output Externalization	tool-results/*.txt，大输出只留摘要和路径	输出超过阈值写磁盘，消息中留指针
Memory	CODEBUDDY.md、rules、local memory、cloud memory	用户记忆 + 项目记忆 + JSONL transcript
Protocol	ACP JSON-RPC/SSE + REST /api/v1/*	标准库 HTTP server + JSON-RPC handler
Sidecar	控制 socket + per-session process	Unix socket + subprocess/session table
Extensions	builtin-skills、plugins、MCP apps、connectors	文件夹扫描 + 延迟描述
Frontend	React renderer 消费 session/update	教学版用 curl/SSE，前端章节解释事件形状

复刻路线

本教程的代码按“从内到外”构造：

1. 先写 agent loop 和工具系统。
2. 再加上下文预算、输出外部化和 JSONL 持久化。
3. 再包成 HTTP/ACP 服务。
4. 再加 sidecar 管理进程。
5. 最后解释桌面前端如何消费协议。

这样做的好处是：读者先理解 agent harness 的心脏，再理解产品壳。