OpenHands Agent Canvas · 中文源码精读教程

OpenHands Agent Canvas · 中文源码精读教程

驾驶舱导览:走进编码 agent 的指挥中心,逐站拆解一个 14 万行的 TS 控制平面

这本教程讲什么

这是一份带读源码的 OpenHands Agent Canvas 精读教程。

⚠️ 开篇必须澄清的身份变迁:如果你印象里的 OpenHands 还是那个 Python 写的 OpenDevin agent 内核——它已经搬家了。2025 年 OpenHands 做了多仓库拆分:Python agent 内核(CodeAct/事件流/runtime 沙箱)拆到了独立的 software-agent-sdk 仓库;而本仓库(OpenHands/OpenHands)现在的身份是 Agent Canvas(v1.16.0,npm 包 @openhands/agent-canvas)——一个用 TypeScript/React(约 14.4 万行) 编写的"自托管编码 agent 控制中心":前端 UI + 本地全栈编排器,能连接多个 agent 后端(本地/远程/Cloud),还能通过 ACP 协议接入 Claude Code、Codex、Gemini CLI 等外部 agent。

Agent Canvas 是什么?想象一个驾驶舱(Cockpit):飞行员(agent)可能来自不同航空公司(OpenHands agent-server/Claude Code/Codex/Gemini),但都在这个驾驶舱里被统一调度、监控、指挥。驾驶舱本身不生产动力——它是控制平面:仪表盘(事件流渲染)、油门切换(多后端)、外接适配口(ACP)、自动巡航(automations)、可更换的仪表面板(Skills/MCP/Canvas Extensions)。

💡 核心心法:Agent Canvas 的教学价值不在"又一个 agent 框架",而在**"如何给 agent 做产品"**——多后端管理、agent 事件流的实时渲染、工具调用的可视化与确认、自动化触发、插件生态、以及企业级前端工程(MSW mock 开发/mock-LLM e2e 不花 token/Stryker 变异测试/16 语言 i18n)。这是把"agent 能力"变成"agent 产品"的完整工程范本。

本教程采用驾驶舱导览式:以"agent 指挥中心"的空间隐喻逐站导览——总控台→对话舱→接入坞→ACP 适配口→自动化塔→插件架→协议管线→工程保障舱→停机坪。每章是一个"站点",讲清这个站点干什么、源码在哪、与其他站点怎么协作。

驾驶舱平面图

九站导览路径

第 1 站(第1章) 总控台:OpenHands 变迁与 Canvas 总览
第 2 站(第2章) 对话舱:事件流渲染
第 3 站(第3章) 接入坞:后端管理
第 4 站(第4章) ACP 适配口:万能 agent 接入 ★
第 5 站(第5章) 自动化塔:把 agent 变常驻团队
第 6 站(第6章) 插件架:Skills/MCP/Canvas Extensions
第 7 站(第7章) 协议管线:API 纪律与 typescript-client
第 8 站(第8章) 工程保障舱:测试矩阵与 i18n ★
第 9 站(第9章) 停机坪:部署形态与全书回顾
​

章节目录

第 1 章 总控台:OpenHands 变迁与 Canvas 总览
OpenDevin→OpenHands→2025 多仓库拆分史(五仓库职责边界表);Agent Canvas 定位(自托管编码 agent 控制中心);多后端架构(一个 Canvas 连多个 Agent Server);ingress 代理(单端口 8000 统一路由);src/ 14.4 万行的模块地图。

第 2 章 对话舱:事件流渲染
WebSocket context(1278 行,socket.io 事件流消费);conversation-events(事件分组/消息渲染);tool visualizers(工具调用可视化:命令行/文件编辑/diff);确认模式(action 确认面板);task tracking;conversation-store/event-message-store 状态管理。

第 3 章 接入坞:后端管理
backend-registry(多后端注册与切换);本地/远程 VM/Docker/Cloud 四类后端;agent-server-adapter(1638 行,核心适配层);backend-form-modal(1629 行);运行模式(docs/architecture.md 的质量门)。

第 4 章 ACP 适配口:万能 agent 接入 ★(高潮之一)
ACP(Agent Client Protocol)详解;JSON-RPC over stdio 驱动外部 agent;接入 Claude Code/Codex/Gemini CLI(docs/ACP_AGENTS.md);acp-service;examples/acp-docker 容器化运行;ACP 与原生 agent-server 的差异。

第 5 章 自动化塔:把 agent 变常驻团队
automations(7700 行);自动化 manifests(3.7K 行);触发器(Slack/GitHub/Linear/webhook/定时);把 agent 变成"常驻工程团队"(自动响应 issue/PR 评审);automation-service。

第 6 章 插件架:Skills/MCP/Canvas Extensions
三套插件体系:Skills(@openhands/extensions 构建期注入+enablement 白名单);MCP 设置页(mcp-page/mcp-service);Canvas Extensions(能改变 App 本身的扩展,specs/canvas-extensions.md);skills-service;skill-enablement.ts。

第 7 章 协议管线:API 纪律与 typescript-client
API 访问纪律:前端禁止直接 axios/fetch 调 agent-server,必须走 @openhands/typescript-client;CI 守卫测试(no-direct-agent-server-calls.test.ts);OpenAPI 契约→TS client 生成;为什么这样设计(契约稳定/类型安全/防漂移)。

第 8 章 工程保障舱:测试矩阵与 i18n ★(高潮之一)
MSW mock 开发(mocks/ 3.6K 行);mock-LLM e2e(不花 token 跑全链路,Playwright 4 套配置);Stryker 变异测试;TESTING_MATRIX(OS×安装方式×Agent 冒烟矩阵);602 个单测;i18n 16 语言(2445 键全量翻译含 zh-CN,make-i18n-translations 管线);PostHog 遥测(telemetry.ts 898 行);AGENTS.md(120KB 的 AI 协作规范)。

第 9 章 停机坪:部署形态与全书回顾
部署全覆盖:npm 全局包/Docker 三合一镜像(agent-server+automation+前端+ingress)/Electron 桌面(三平台)/Helm K8s/Vercel;docker/entrypoint;release-please 自动发版;Windows 特殊处理(README.windows.md);全书九站回顾;Agent Canvas 核心哲学;下一步建议。

适合读者

• 想理解"agent 产品怎么做"的前端/全栈工程师(React 19 + TS)
• 对多后端架构、ACP 协议、agent 事件流 UI 感兴趣的架构师
• 想学习企业级前端工程(mock-LLM e2e/变异测试/16 语言 i18n)的工程师
• 想给 OpenHands 贡献代码或自建 agent 控制台的开发者

前置知识:TypeScript/React 基础(组件/hooks/query);对 agent/LLM 有基本概念;可选:了解 Docker。

⚠️ 重要说明:本仓库是 TypeScript 前端/控制平面。Python agent 内核(CodeAct/事件流/runtime 沙箱)在 software-agent-sdk 仓库,本教程在需要处会说明边界但不在其内展开。

关于源码版本

对照源码来自 OpenHands-main(MIT,OpenHands contributors),Agent Canvas v1.16.0(2026 年中快照)。src/ 约 1250 个 ts/tsx 文件/14.4 万行;依赖版本:openhands-agent-server 1.44.1、@openhands/typescript-client 1.39.0、@openhands/extensions 0.19.0。架构文档 docs/architecture.md 与 ACP_AGENTS.md 质量很高。