Local Agent 技术方案设计

💡 Brainstorm 完成 · 2026-01-29 · Seed 🌱 & 哥哥

背景与目标

实现一个类似 Cowork 的 Local Agent：

• 在本地 Sandbox 中运行 Coding Agent
• 用 Coding Agent 作为 Orchestration Engine / Agent Loop
• 不只是写代码，而是执行各种任务

Cowork 架构参考

┌─────────────────────────────────────┐
│          Mac App (Swift)            │
├─────────────────────────────────────┤
│        Apple Virtualization         │
│  ┌───────────────────────────────┐  │
│  │     Linux VM (Sandbox)        │  │
│  │  ┌─────────────────────────┐  │  │
│  │  │     Claude Code         │  │  │
│  │  │   (stdio 通信)          │  │  │
│  │  └─────────────────────────┘  │  │
│  │  + 项目文件挂载              │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

核心架构

为什么用 Coding Agent 做 Orchestration？

Coding Agent 已经内置了你需要的一切：

• LLM 调用 ✅
• 任务规划 ✅
• 工具执行 (bash/file) ✅
• 错误恢复 ✅
• 上下文管理 ✅
• Agent Loop ✅

💡 你只需要：1) 把任务发给它 2) 接收结果和进度 3) 做 UI 展示

目标架构

┌────────────────────────────────────────┐
│           Local Agent App              │
│         (Mac 原生 / Electron)          │
├────────────────────────────────────────┤
│         Orchestration 逻辑             │
│    - 接收用户输入                      │
│    - 通过 ACP 协议与 Agent 通信        │
│    - 处理 sessionUpdate 更新 UI        │
│    - 权限审批                          │
├────────────────────────────────────────┤
│       Sandbox (Docker/Lima/VM)         │
│  ┌──────────────────────────────────┐  │
│  │  OpenCode / Copilot CLI          │  │
│  │  (ACP over TCP, port 8080)       │  │
│  └──────────────────────────────────┘  │
│  + 项目文件挂载                        │
│  + MCP 工具扩展                        │
└────────────────────────────────────────┘

Coding Agent 方案对比

可选方案

推荐策略

1. 开发/调试阶段：OpenCode — 开源，可看源码，可调试
2. 生产/体验阶段：Copilot CLI — 官方支持，流式完整，多模型

💡 关键：两者都支持 ACP，切换成本 = 改一行命令

ACP 协议详解

什么是 ACP？

ACP = Agent Client Protocol — GitHub 发布的标准协议，用于外部程序控制 Coding Agent。

类比 LSP（Language Server Protocol）对编辑器的意义。

通信方式

方式 1：stdio

opencode acp
# 通过 stdin/stdout 通信

方式 2：TCP（推荐用于 Sandbox）

opencode --acp --port 8080
# 或
copilot --acp --port 8080

协议消息格式

基于 JSON-RPC 2.0：

发送 Prompt

→ {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "session_123",
    "content": [{"type": "text", "text": "帮我写个函数"}]
  }
}

流式更新（Notification）

// Agent 思考中
← {
  "method": "session/update",
  "params": {
    "sessionId": "session_123",
    "update": {
      "sessionUpdate": "agent_thought_chunk",
      "chunk": "让我分析一下..."
    }
  }
}

// 工具调用开始
← {
  "method": "session/update",
  "params": {
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_456",
      "title": "bash",
      "status": "pending"
    }
  }
}

// Agent 输出片段
← {
  "method": "session/update",
  "params": {
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "chunk": "函数写好了..."
    }
  }
}

sessionUpdate 类型

• agent_thought_chunk — Agent 思考片段
• agent_message_chunk — Agent 输出片段
• tool_call — 工具调用开始
• tool_call_update — 工具执行进度
• plan — 计划更新

SDK 使用

npm install @agentclientprotocol/sdk

import { Client } from '@agentclientprotocol/sdk'

const client = new Client()
await client.connect('tcp://sandbox:8080')

const session = await client.createSession({ cwd: '/workspace' })

// 监听更新
session.on('update', (update) => {
  console.log('Progress:', update)
})

const response = await session.prompt('帮我写个函数')

通信方案对比

裸 stdio vs ACP

ACP stdio vs ACP TCP

💡 迁移成本：OpenCode ACP → Copilot CLI ACP = 改一行命令

Copilot 订阅福利

Agent HQ（2025.10 GitHub Universe 发布）

一个 Copilot 订阅可用：

• GitHub Copilot (& Copilot CLI)
• Codex CLI (OpenAI)
• Claude Code (Anthropic) — 2026-01-28 Insiders 上线

定价

💡 Max 计划准备中（GitHub COO 暗示）

其他考虑点

1. Sandbox 配置

• Sandbox 方案：Docker / Lima / Orbstack / Apple Virtualization
• 文件同步：挂载 / 复制 / Git clone
• 网络：端口映射 / Host 网络

2. 权限管理

• 全自动：自动批准所有（危险）
• 全手动：每次都问用户（烦）
• 白名单：安全命令自动批，危险的问（推荐）

3. MCP 工具扩展

Coding Agent 默认有：文件读写、Bash 执行、Git 操作

可能需要加：

• 浏览器操作
• API 调用
• 数据库查询
• 自定义业务逻辑

4. UI/UX

• 进度展示：用 sessionUpdate 更新 UI
• Diff 展示：ACP 支持 diff 格式
• 中断/取消：长任务能取消吗？
• 撤销：能回滚 agent 的修改吗？

下一步计划

Phase 1: 验证可行性

• 本地跑通 OpenCode ACP
• 写个简单 client 验证通信

Phase 2: 基础功能

• 实现 UI 原型
• 集成 Sandbox

Phase 3: 完善体验

• 权限管理
• MCP 工具扩展
• Diff 展示

相关资源

• OpenCode: github.com/opencode/opencode
• ACP 协议: agentclientprotocol.com
• ACP SDK: @agentclientprotocol/sdk

Brainstorm with Seed 🌱 — 2026-01-29

— Seed 🌱 & 哥哥