第 9 章 · 02 全书回顾

第 9 章 · 02 全书回顾

本节摘要:全书最后一节。我们把九站导览重新串成一条完整航线:①总控台(多仓库拆分史 + 多后端架构 + ingress 单端口)→ ②对话舱(WebSocket 事件流消费 + tool visualizers + 确认模式)→ ③接入坞(backend-registry 四类后端 + agent-server-adapter 统一接口)→ ④ACP 适配口(JSON-RPC over stdio 接入 Claude Code/Codex/Gemini)→ ⑤自动化塔(五类触发器把 agent 变常驻工程团队)→ ⑥插件架(Skills/MCP/Canvas Extensions)→ ⑦协议管线(禁止直接 fetch 的 API 纪律 + OpenAPI → client 生成)→ ⑧工程保障舱(mock-LLM e2e + Stryker + i18n + AGENTS.md)→ ⑨停机坪(五种部署形态)。然后提炼 Agent Canvas 的核心哲学四点:多后端单驾驶舱、ACP 标准化、产品化思维、工程纪律。最后给出读者的下一步行动清单。

内容来源:全书第 1-9 章各站精读内容回顾,源码引用均为前文已逐段拆解过的文件。

⚠️ 注意:本节不再贴大段新代码,只做航线串讲与提炼。每站提到的文件名与行数都出自前八章的精读,可按站回看对应章节。

学习目标

阅读完本节,你应当能够:

1. 按顺序复述九站各自的"一句话核心"与代表性源码。
2. 说清九站之间的依赖关系:为什么事件流(②)依赖 ingress(①),为什么 ACP(④)建在接入坞(③)之上。
3. 用自己的话讲出 Agent Canvas 核心哲学的四点,并为每点举一个源码证据。
4. 为自己制定下一步的实践清单。

一、九站串讲:一条完整的航线

先用一张航线图把九站的关系摆上仪表盘:

各站一句话与代表源码速查:

下面逐站展开。

① 总控台:多仓库拆分与单端口架构(第 1 章)

航线的起点是历史与全景。OpenHands 从单体 OpenDevin 走来,演化成今天的多仓库体系:本仓库(前端 agent-canvas)、software-agent-sdk(Python SDK + agent-server)、typescript-client(契约镜像)、automation(调度后端)各司其职。AGENTS.md 的分工表把"什么改动落在哪个仓库"写成硬规则——新端点进 SDK、新访问方法进 client、UI 与前端服务留在本仓库。

运行时架构的骨架是 ingress 单端口:static-server 一个进程同时做静态前端服务与反向代理,/api/* 与 /sockets 转 agent-server、/api/automation/* 转 automation、其余走 SPA——浏览器永远只见一个源,没有 CORS、没有多端口配置。这一骨架贯穿全书:第 2 章的 WebSocket、第 8 章的 e2e(单 URL 同吃浏览器与后端断言)、第 9 章的 Docker entrypoint 十余条 --route,全是它的变奏。

② 对话舱:事件流的消费与可视化(第 2 章)

产品的心脏是那条约 1278 行的 WebSocket 消费链:订阅 /sockets、把 agent-server 推来的事件流(思考、行动、观察、错误)增量渲染进对话界面,断线后用 events API 分页补拉。tool visualizers 把机器视角的工具调用翻译成人类可读的卡片——终端命令带输出、文件编辑带 diff、浏览器操作带截图;确认模式在危险动作前插一道人工闸门。这一站确立的观点贯穿全书:agent 产品的竞争力一半在模型,一半在"把模型的行为变成人能审阅、能干预的界面"。

③ 接入坞:后端管理(第 3 章)

backend-registry 管理四类后端(本地 agent-server、云端、外部 URL、ACP),约 1638 行的 agent-server-adapter 把"连哪个后端、用什么凭据、怎么解析 host"统一成一套接口。活动后端是全局状态,切换对业务代码透明——第 7 章的 getAgentServerClientOptions() 正是从这里读配置:接入坞是协议管线的地基。

④ ACP 适配口:万能 agent 接入 ★(第 4 章)

全书第一个高潮:Agent Client Protocol,JSON-RPC over stdio。agent-server 以子进程方式拉起任何符合 ACP 的 agent(Claude Code、Codex、Gemini CLI、自研脚本),用标准化的 initialize/session/prompt/update 消息对话——进程输入输出一对,协议即接通。这一站的意义是生态级的:Canvas 不绑定自家后端,任何 agent 都能插进这个驾驶舱。第 8 章测试框架里那个 50 行的 mock ACP 服务器,反向证明了协议的开放红利:能接入的东西,就能被替身测试。

⑤ 自动化塔:把 agent 变常驻团队(第 5 章)

五类触发器(定时 cron、间隔、webhook、事件、手动)加 automation 后端的派发与重试,把"人发起的一次对话"升级为"无人值守的工程流程":夜间代码评审、告警响应、例行报告。会话状态机(创建 → 派发 → 运行 → COMPLETED/FAILED)与第 2 章的事件流共用渲染管线——自动化不是新系统,而是对话舱的调度化封装;<RUNTIME_SERVICES> 块把本地服务拓扑注入 agent 系统提示,让它知道自动化 API 就在手边。

⑥ 插件架:三种扩展维度(第 6 章)

Skills 给 agent 技能(它自己会按任务取用的操作手册)、MCP 给工具(标准化的外部能力接入,GitHub/Slack 等数百服务器即插即用)、Canvas Extensions 改 App 本身(运行时安装的界面扩展)。三个维度分别作用在模型侧、工具侧、界面侧——一个扩展体系是否成熟,看它能不能把"改产品"也变成插件。

⑦ 协议管线:契约驱动的协作(第 7 章)

前端与 agent-server 之间不许有"自由恋爱":CI 守卫测试(no-direct-agent-server-calls.test.ts,80 行)递归扫描 src/ 全部源码,六组正则把裸 axios/fetch 打 /api/、直接构造底层 HttpClient 等违规当场击落,白名单只放三个基础设施文件;所有调用走 @openhands/typescript-client(1.39.0)——它由 software-agent-sdk 的 OpenAPI 契约生成,契约变更 → client 重新生成 → 前端编译期报错。config/defaults.json 钉扎 agent-server 1.44.1 与最低兼容 1.28.0,sdk-version-sync.yml 三通道触发跨仓库自动对表。接口漂移这个前后端协作的千年顽疾,在这里被"测试守卫 + 生成链路 + 版本钉扎"三件套制度性消灭。

⑧ 工程保障舱:测试与全球化 ★(第 8 章)

全书第二个高潮,保障舱六件套:602 个单测文件(Vitest 4,根 __tests__/ 镜像 src 结构)打底;src/mocks/ 约 3.6K 行 MSW(13 组按服务分文件的 handler)让前端无后端开发;mock-LLM e2e 用 TestLLM 两轮剧本(terminal 工具调用 + 文本收尾)替换大模型,让"浏览器 → ingress → agent-server → 工具执行 → 结果渲染"的全链路回归不花一个 token、每个 PR 都跑,四套 Playwright 配置再覆盖 Docker 镜像与真 LLM 抽样;Stryker 变异测试(diff 级)审计测试本身的有效性;TESTING_MATRIX 用 OS × 安装方式 × Agent 的人工冒烟矩阵守住机器守不住的组合;i18n 2445 键 × 全语言(含简繁中文)100% 翻译加 make-i18n 生成管线;898 行遥测服务(install 事件分级、四层退出开关)与 120KB 的 AGENTS.md 把"AI 参与开发"本身也纪律化。

⑨ 停机坪:五种部署形态(第 9 章第 01 节)

npm 全局包(bin 脚本用 uvx 编排 Python 栈,一条命令)、Docker 三合一(单镜像单端口 8000,urandom 自动生成密钥并持久化,ingress 十余条路由)、Electron 三平台(afterPack 把 600MB node_modules 削到约 10MB,dmg/exe/deb)、Helm(企业 K8s,StatefulSet 随镜像自动 bump)、Vercel(前端托管)。release-please 按 Conventional Commits 自动发版,20 个 workflows 分工协同。五种形态共享同一份构建产物与 defaults.json——交付的多样性没有破坏工程的一致性。

二、Agent Canvas 核心哲学四点

四点哲学与源码证据速查:

2.1 多后端单驾驶舱

一个 Canvas 管所有 agent,不分厂商。接入坞的四类后端注册表、活动后端的全局解析、getAgentServerClientOptions() 的单一配置出口,共同保证"切后端"是用户级的开关而非代码级的重构。证据落到源码:任何 client 调用都不自带 URL,host 一律从注册表解析(第 3、7 章)。

2.2 ACP 标准化

不绑定自家后端,是比"多后端"更进一步的宣言:用开放协议把 agent 接入变成 commodity。任何说 JSON-RPC over stdio 的 agent 都能插进驾驶舱,Canvas 的价值随之从"我家的模型界面"转移到"所有人的操作中枢"。当模型层持续洗牌,标准化接口是最深的护城河(第 4 章)。

2.3 产品化思维

事件流可视化(第 2 章)、确认模式(第 2 章)、自动化调度(第 5 章)、Skills/MCP/Extensions(第 6 章)——这一系列能力的共同方向是:把 agent 的原始能力加工成 agent 产品。原始事件流是机器日志,tool visualizers 让它变成人类可审的叙述;原始工具调用有风险,确认模式给它装上刹车;原始对话需要人在场,自动化让它值守。demo 与产品的分界线,就在这些"第二层加工"里。

2.4 工程纪律

API 守卫测试(第 7 章)、mock-LLM e2e(第 8 章)、2445 键全量 i18n(第 8 章)、120KB 的 AGENTS.md(第 8 章)——当仓库的主要贡献者包括 AI agent,纪律不再是风格偏好,而是系统能持续演化的前提。每条纪律都配着强制机制:违规的代码过不了 CI,过期的文档违反元规则,缺译的键编译不过。

💡 驾驶舱要点:四点哲学其实是一个判断的四个推论——模型会变、厂商会变、界面形态会变,但"人类需要安全地指挥与审阅 agent 工作"这件事不变。围绕不变量组织架构(标准化接入、可视化、确认、纪律),把变化的部分(具体模型、具体后端)全部做成可插拔。这是 Agent Canvas 给所有 agent 产品开发者的最重要一课。

三、下一步行动清单

合上这本教程,建议按这个顺序把知识变成肌肉记忆:

1. 本地跑通:npm i -g @openhands/agent-canvas 起一个真实栈,用 --info 对照第 7 章的版本钉扎(agent-server 1.44.1/最低兼容 1.28.0),再开浏览器把九站讲过的界面——事件流、确认模式、后端切换、自动化面板——逐一认脸。想省钱就用 npm run dev:mock:MSW 让你在零后端的情况下点遍全部功能(第 8 章第 01 节)。
2. 接入一个 ACP agent:挑 Claude Code、Codex 或 Gemini CLI 之一,在第 4 章的知识下完成接入;有精力再照着 tests/e2e/mock-llm/scripts/mock-acp-server.py 写一个属于你自己的最小 ACP agent——initialize/session/new/session/prompt 四个方法写完,你对协议的理解就落地了。
3. 读一遍 AGENTS.md:不为贡献,为学规范。带着第 8 章第 03 节给的四个观察点(可执行规则优先、给决策留理由、元规则防过期、为非人类读者优化结构)通读 120KB,对照自己团队的文档找差距。然后看一两个真实 PR 怎么遵守这些规则——规范文本与代码实践的互证,是最快的进阶。
4. 深入感兴趣的站点:想做界面,精读第 2 章的事件流渲染与 visualizer 注册表;想做调度,精读第 5 章的触发器与 automation 生命周期;想做工程质量,把第 8 章的 mock-LLM 框架与 Stryker 搬回自己的项目——剧本化外部依赖、生产保真启动、diff 级选择性执行这三招,在任何依赖 LLM 的项目里都成立。
5. 带着批判回看:这个仓库也有它的取舍——宽表式 i18n 的合并冲突成本、120KB 文档的维护负担(靠元规则硬撑)、单容器全栈的伸缩上限、多仓库协作的沟通开销。理解一项工程"放弃了什么",才算真正读懂了它"选择了什么"。

四、写给读者:能力清单与告别

读完这九章,你已经具备:

• 读:src/ 下任何一个模块都能定位它的职责边界——服务层看 src/api/、状态看 stores、事件看第 2 章的管线、扩展点看第 6 章的三维体系;遇到没讲过的文件,先查 AGENTS.md 的仓库地图。
• 改:给 Canvas 加功能时知道三仓库的改动落点(第 7 章第 02 节的贡献路径),知道新文案要进宽表再 make-i18n,知道新事件要按遥测字典复用契约,知道改测试框架要同 PR 更新 AGENTS.md。
• 建:更重要的是,你见过了一套完整参照系——多后端注册表怎么设计、开放协议怎么接入、外部智能怎么 mock、AI 协作怎么纪律化。这些模式不属于 OpenHands,它们是 agent 时代的通用工程语言。

agent 应用的复杂度,不在任何一行代码里,而在人、agent、工具、流程如何被组织进同一个系统。Agent Canvas 给出了一个完成度极高的答案:它把"指挥 agent"做成了驾驶舱,把"信任 agent"做成了可视化与确认,把"扩展 agent"做成了协议与插件,把"维系这一切"做成了纪律与测试。

九站航程到此结束。愿你亲手造出的驾驶舱,配得上你指挥的每一位 agent。

本节要点回顾

1. 九站航线:总控台(多仓库 + ingress 单端口)→ 对话舱(1278 行事件流 + visualizers + 确认)→ 接入坞(四类后端 + 1638 行 adapter)→ ACP 适配口(JSON-RPC over stdio 万能接入 ★)→ 自动化塔(五类触发器常驻团队)→ 插件架(Skills/MCP/Extensions 三维扩展)→ 协议管线(CI 守卫 + OpenAPI 生成)→ 工程保障舱(mock-LLM e2e + Stryker + i18n + AGENTS.md ★)→ 停机坪(五种部署形态)。
2. 哲学一:多后端单驾驶舱——一个 Canvas 管所有 agent,配置出口唯一,切换是运行时开关。
3. 哲学二:ACP 标准化——开放协议让任何 agent 可插拔,价值从模型界面转移到操作中枢。
4. 哲学三:产品化思维——可视化、确认、自动化、插件化,把 agent 能力加工成 agent 产品而非 demo。
5. 哲学四:工程纪律——守卫测试、mock-LLM e2e、全量 i18n、AI 协作规范,每条纪律配强制机制;贡献者包含 AI 时,纪律是演化的前提。
6. 不变量判断:模型与厂商皆变,"人类安全地指挥与审阅 agent"不变——围绕不变量组织架构,把变化做成可插拔。
7. 下一步:本地跑通 → 接入一个 ACP agent → 通读 AGENTS.md 学规范 → 深入感兴趣站点 → 带批判回看取舍;能力清单——能读(职责定位)、能改(三仓库落点与各项纪律)、能建(多后端/开放协议/mock/纪律四套通用模式)。