Agent Canvas · 第 7 章 协议管线:API 纪律与 typescript-cl...

Agent Canvas · 第 7 章 协议管线:API 纪律与 typescript-client

章节摘要:本章导览第七站——协议管线。Agent Canvas 有一条铁的 API 纪律:前端禁止直接用 axios/fetch 调 agent-server,必须走 @openhands/typescript-client。这条纪律由 CI 守卫测试(no-direct-agent-server-calls.test.ts)强制执行——违反即测试失败。typescript-client 由 Python SDK 的 OpenAPI 契约生成,保证类型安全与接口稳定。这是"契约驱动的前后端协作"的工程范本。本章共 2 节,前置依赖为第 1-6 章。

舱位坐标

学习目标

1. 理解 API 访问纪律(禁止直接 fetch)。
2. 说清 CI 守卫测试的强制机制。
3. 理解 OpenAPI 契约→TS client 生成链路。
4. 认识 typescript-client 的接口面。
5. 理解为什么这样设计(防漂移/类型安全)。

子章节导航

01 API 纪律与 CI 守卫

铁律:前端禁止直接axios/fetch调agent-server;src/api/no-direct-agent-server-calls.test.ts(CI守卫:扫描源码违规则测试失败);例外路径清单(哪些域名允许直连);为什么(接口漂移/类型不安全/绕过缓存与重试)。

02 OpenAPI 契约与 typescript-client

@openhands/typescript-client 1.39.0(本仓库唯一合法访问Agent Server的方式);由software-agent-sdk的OpenAPI(Swagger)契约自动生成;类型安全(接口变化→client重新生成→TS编译报错);AGENTS.md中的API访问规则;conversation/event/git/runtime等服务的client方法。

前置知识与后续延伸

前置:第1-6章。后续:第8站工程保障舱。