【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-orchestrator点击查看免费下载导读aoagents/cloud-client是 Agent Orchestrator 仓库中面向 AO Cloud 公开 API 的运行时中立 TypeScript 契约包同时内置一个零依赖的 fetch 客户端实现。它定义了客户端与云端之间的调用边界既为桌面、Web、移动端提供面向组织、项目、会话的CloudClient也为沙箱 Worker 提供覆盖 bootstrap、心跳、fenced turn、凭据、checkout-grant、子编排、工作区与终端传输的WorkerClient。读完本文你将掌握该包的配置方式、认证模型、两类客户端的完整 API 面、SSE 事件流重连机制、幂等与分页约定以及如何基于仓库内的 OpenAPI 契约自行生成类型。一、包定位只定义客户端边界不实现服务端路由从 packages/cloud-client/README.md 的定位描述可以明确本包是runtime-neutral TypeScript contracts and a small fetch-based client for AO Clouds public API。它只负责定义客户端边界client boundary当前仓库并不实现 Cloud 的服务端路由服务端由独立的 AO Cloud 实现提供。这一点在 contracts/cloud/openapi.yaml 的info.description中同样被强调这是 Client-facing contract for a separate AO Cloud implementation. This repository does not serve these routes其中 Worker 部分文档化了沙箱 Worker 使用的精确出站 HTTP 协议——一次性 bootstrap、轮换凭据、fenced turn 执行、编排以及持久化的工作区与终端传输。包结构非常精简见 packages/cloud-client文件作用src/client.tsCloudClient、WorkerClient两个类的完整实现与工厂函数src/index.ts包入口重新导出客户端类、工厂函数与全部类型src/types.ts从生成 schema 映射出来的领域类型别名与请求选项接口src/schema.ts由 OpenAPI 契约生成的 TypeScript 类型提交进仓库test/client.test.ts基于 vitest 的客户端行为测试package.json包元信息与generate、build、typecheck、test脚本从 package.json 可以看出它同时导出了主入口.和./schema子路径type: module、sideEffects: false打包产物只包含dist与 READMEpublishConfig.access为public。二、快速上手两个客户端的最小用法2.1 CloudClient面向用户/组织资源的客户端import { createCloudClient } from aoagents/cloud-client; const cloud createCloudClient({ baseUrl: https://cloud.example.com, getAccessToken: () authSession.getAccessToken(), fetch, }); const sessions await cloud.listSessions(orgId, { limit: 50 });配置项说明对应 client.ts 中的CloudClientConfig配置项类型说明baseUrlstringCloud 服务根地址。构造时会被new URL()校验若包含查询串或片段query/fragment会抛出TypeError尾部的/会被去除getAccessToken() MaybePromisestring \| null \| undefined每个请求发起前立即调用的取 token 回调由调用方负责认证与刷新fetchtypeof globalThis.fetch可选注入自定义 fetch 实现便于测试如 Node/测试环境 mock或自定义传输2.2 WorkerClient面向沙箱 Worker 的客户端import { createWorkerClient } from aoagents/cloud-client; let workerToken: string | null null; const worker createWorkerClient({ baseUrl: https://cloud.example.com, getWorkerToken: () workerToken, fetch, }); const bootstrap await worker.bootstrap({ bootstrapToken: oneTimeTicket, version: workerVersion, capabilities, }); workerToken bootstrap.workerToken; const heartbeat await worker.heartbeat({ version: workerVersion, capabilities }); workerToken heartbeat.workerToken;WorkerClientConfigclient.ts与CloudClientConfig结构相同只是 token 回调是getWorkerToken。三、认证模型调用方持有 token客户端按请求即时取用该包的核心设计原则是The caller owns authentication and token refreshcreateCloudClient会在每次用户请求之前立即调用getAccessToken()获取最新 tokencreateWorkerClient对每个已认证的 Worker 请求做同样的事。这一点在源码里有明确体现CloudClient.authorizedFetchclient.ts每次请求前调用getAccessToken()token 缺失时抛出 401 的CloudApiError随后以Authorization: Bearer token注入请求头WorkerClient.authorizedFetchclient.ts则以Authorization: Worker token前缀注入。测试 client.test.ts 专门验证了这一行为连续两次listProviderConnections调用会触发getAccessToken两次且两次请求头分别为Bearer first-token与Bearer second-token证明客户端不会缓存 token永远取最新值——这为 token 刷新场景提供了天然支持。Worker 侧的认证细节由契约定义。在 openapi.yaml 的securitySchemes中bearerAuthHTTP Bearer 认证JWT用于用户侧 APIworkerAuthheader 中的 apiKey格式为Worker token要求 token 携带当前 worker ID 与 epoch沙箱被替换时未过期 token 会被STALE_WORKER_TOKEN围栏fence掉路由级作用域包括worker:connect心跳、worker:event事件、worker:turn:claim/worker:turn:poll/worker:turn:completeturn 执行、worker:credential:readagent 密钥、worker:gitcheckout grant、worker:orchestrate子编排、worker:transport工作区与终端传输。四、Worker 生命周期bootstrap → 心跳 → 轮换凭据4.1 一次性 bootstrap 交换WorkerClient.bootstrapclient.ts是唯一的免认证请求走unauthenticatedRequest即不会附加Authorization头测试 client.test.ts 明确断言 bootstrap 请求没有 Authorization 头。契约 openapi.yaml 说明bootstrap token 是一次性one-time票据原子消费、不可重放成功响应会分配 worker epoch 并返回首个短生命周期 worker token该 token 携带票据的 scopes禁止被记录日志或持久化。测试中的响应体{ workerToken, workerId, epoch, expiresIn, sessionId, launch }client.test.ts展示了 bootstrap 成功后的完整返回结构launch内含 sessionId、projectId、harness、displayName、branch、repositoryUrl、defaultBranch 等启动上下文。4.2 心跳与 token 轮换WorkerClient.heartbeatclient.ts在每次心跳时都会返回一个新签发的 token同一 worker 身份、epoch 与 scopes调用方需要把返回值中的workerToken写回内存供下次使用——这正是 README 示例中workerToken heartbeat.workerToken;的意义。契约 openapi.yaml 补充了底层语义心跳记录 worker 存活将引导中的沙箱提升为运行中且旧 token 不会被吊销在过期前仍有效除非 worker epoch 被替换。WorkerClient.bootstrap与heartbeat都使用cache: no-store测试断言了这一点client.test.ts。4.3 凭据与 checkout-grant 的安全处理README 明确规定bootstrap、worker、agent-credential、checkout-grant 四类秘密只能保存在内存中绝不写入日志。携带秘密的请求统一使用cache: no-store且 credential 与 checkout-grant 的响应还要求服务端返回Cache-Control: no-store。对应源码getCredentialclient.ts与createCheckoutGrantclient.ts均带cache: no-store契约侧 openapi.yaml 与 openapi.yaml 在响应头中要求Cache-Control: no-store。测试 client.test.ts 同样覆盖了这两个请求的 no-store 断言。五、CloudClient 全 API 面账户、GitHub、项目、会话、工作区与 ProviderCloudClientclient.ts的方法围绕组织作用域资源组织路由统一以/api/cloud/v1/orgs/{orgId}/...拼接orgPathclient.ts并会对orgId、sessionId、projectId等做encodeURIComponent编码测试 client.test.ts 验证了含空格、/、?等特殊字符的编码行为。按功能域划分账户getCurrentAccount()→/api/cloud/v1/me返回当前用户与组织成员关系AgentslistAgents(orgId)→/orgs/{orgId}/agents返回运行时与组织宿主提供的 agent profile含 capabilities 与 availability 状态见测试 client.test.tsProjectslistProjects支持 cursor/limit 分页、createProject、updateProjectPATCH、deleteProject返回 202 持久化删除GitHub 集成用户级getGitHubUserConnection、startGitHubUserAuthorization、disconnectGitHubUser组织级listGitHubInstallations、startGitHubInstallation、syncGitHubInstallation、disconnectGitHubInstallation、listGitHubRepositories、createProjectFromGitHub、createGitHubScratchProjectSessionslistSessions可按projectId过滤、getSession、createSession、deleteSession、sendMessage、cancelTurn、listSessionPullRequests、getSessionReviewState事件流replayEvents游标回放与streamEvents实时 SSE 流TerminalcreateTerminalTicket与terminalUrl构造wss://WebSocket URL见 client.tsWorkspacelistWorkspaceFiles、readWorkspaceFile、writeWorkspaceFilePUT、getWorkspaceDiffProvider 连接listProviderConnections、putAgentProviderConnectionclaude-code/codex/cursor三选一、deleteAgentProviderConnection用于管理 coding-agent 的凭据连接测试见 client.test.ts。六、SSE 事件流断线重连与游标续传streamEventsclient.ts是客户端最复杂也最值得研究的方法它以AsyncGenerator形式消费text/event-stream以Accept: text/event-stream请求/sessions/{sessionId}/events?aftersequence使用ReadableStreamreader 按块解码将\r\n归一为\n按\n\n边界解析 SSE 块parseSSEBlock只提取data:行每个事件带单调递增的sequence序号仅当event.sequence after时才 yield天然实现去重与续传流中断或可重试错误时isRetryableStreamError判定 408/425/429/5xxclient.ts用已消费的最大 sequence作为新的after参数重新连接重试退避采用指数退避加抖动waitForRetryclient.ts上限 4 秒支持AbortSignal优雅取消。测试 client.test.ts 展示了重连语义第一次连接收到 sequence 8断开后用after8重连即使服务端重发 sequence 8 也会被跳过最终只 yield 8、9 两个事件而 401 这类不可重试错误client.test.ts不会触发重连。七、幂等与分页防重复与游标约定7.1 幂等键Idempotency-Key所有变更类操作创建项目、发送消息、取消 turn、创建子会话等都接受IdempotentRequestOptions其中idempotencyKey为必填字符串通过Idempotency-Key请求头传递。validateIdempotencyKeyclient.ts强制1200 个字符。契约侧语义openapi.yaml同一 key 用于相同命令时返回原始结果用于不同命令时返回IDEMPOTENCY_CONFLICT。测试 client.test.ts 验证了冲突场景下CloudApiError携带status: 409、code: IDEMPOTENCY_CONFLICT、requestId与details的完整错误信封。7.2 分页与事件游标分页统一使用PaginationOptions { cursor?, limit?, signal? }types.tslimit默认 50、最大 100契约Limit参数openapi.yaml。事件回放使用EventReplayOptions { after?, limit?, signal? }after为 int64 序号默认 0limit默认 100、最大 500契约EventLimit/After参数openapi.yaml。withQuery辅助方法client.ts保证未提供的查询参数不会被序列化。八、错误处理统一错误信封CloudApiError客户端把所有失败响应统一归一为CloudApiErrorclient.ts其字段字段来源statusHTTP 状态码code错误信封中的机器可读 code如AUTH_REQUIRED、IDEMPOTENCY_CONFLICTrequestId服务端错误信封或x-request-id响应头details可选的附加结构化信息envelope完整错误信封ErrorEnvelope非 JSON 的失败响应会被包装为INVALID_RESPONSE错误本地缺少 token 时抛出AUTH_REQUIRED/WORKER_AUTH_REQUIRED。toErrorEnvelopeclient.ts负责从响应体或响应头中尽力恢复错误结构。九、契约驱动开发从 OpenAPI 生成类型README 明确了契约驱动工作流The source contract iscontracts/cloud/openapi.yaml. Runnpm run generatefrom this directory after changing it. The generatedsrc/schema.tsfile is committed so consumers do not need an OpenAPI toolchain.即契约唯一事实来源是仓库根目录的 contracts/cloud/openapi.yaml约 3700 行OpenAPI 3.1.0覆盖 Account/Agents/Projects/Sessions/GitHub/Pull Requests/Reviews/Events/Terminal/Workspace/Providers/Worker Lifecycle/Worker Execution/Worker Orchestration/Worker Transport 等标签修改契约后在packages/cloud-client目录下执行npm run generate脚本为openapi-typescript ../../contracts/cloud/openapi.yaml -o src/schema.ts见 package.json生成的 src/schema.ts直接提交进仓库消费者无需安装 OpenAPI 工具链即可获得完整类型src/types.ts 再从 schema 的components[schemas]映射出全部领域类型Session、Project、ClientEvent、WorkerTurn、WorkerTransportRequest等并定义PaginationOptions、EventReplayOptions、IdempotentRequestOptions、RequestOptions四个请求选项接口。测试与类型检查脚本npm run typecheck同时检查主 tsconfig 与测试 tsconfig、npm testvitest 运行 test/client.test.ts。十、Worker 路由覆盖范围明确包含与明确排除README 对 Worker 客户端的边界做了精确声明明确覆盖与 openapi.yaml 的 worker 路由一一对应bootstrap / heartbeatPOST /worker/bootstrap、POST /worker/heartbeateventPOST /worker/eventsworker.ready、agent.activity、chat.assistant_delta等 allowlist 事件fenced turnPOST /worker/turns/claim、GET /worker/turns/{turnId}/cancellation?attempt、POST /worker/turns/{turnId}/complete、POST /worker/turns/{turnId}/failcredentialGET /worker/credentialcheckout-grantPOST /worker/checkout-grantchild orchestrationGET/POST /worker/children、DELETE /worker/children/{sessionId}、POST /worker/children/{sessionId}/messages另有契约中的父会话上报POST /worker/parent/messagesworkspace transportPOST /worker/transport/claim、POST /worker/transport/{requestId}/complete、POST /worker/transport/{requestId}/fail承载 workspace list/read/write/diff 等操作terminal transportPOST /worker/terminals/agent、POST /worker/terminals/{terminalId}/output、POST /worker/terminals/{terminalId}/exit。明确排除worker provisioning沙箱供应、数据库细节、秘密存储、本地 daemon 路由——这些不属于公开客户端契约消费者不应期待在包内找到对应方法。claimTurn与claimTransport在无任务可领时返回null服务端返回{ turn: null }/{ request: null }测试 client.test.ts 专门验证了这一空领取语义完整的 19 个路由调用链端到端断言见 client.test.ts可作为理解 Worker 客户端全生命周期的最佳参考。结语aoagents/cloud-client是一个小而精的契约型客户端通过getAccessToken/getWorkerToken回调把认证与刷新完全交给调用方通过 OpenAPI 契约生成提交进仓库的完整类型通过CloudApiError统一错误信封、Idempotency-Key保证幂等、SSE 游标实现可续传事件流并严格划分用户侧CloudClient与沙箱侧WorkerClient的边界。无论你要为桌面/移动端接入 AO Cloud 的组织、项目与会话 API还是为沙箱 Worker 实现 bootstrap、fenced turn 与传输协议本包都是开箱即用的 TypeScript 边界层。深入阅读 src/client.ts、test/client.test.ts 与 contracts/cloud/openapi.yaml 三份文件即可完整掌握其实现细节。赞分享【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址https://gitcode.com/gh_mirrors/ag/agent-orchestrator点击查看免费下载相关推荐SpacetimeDB 客户端连接实战指南从 DbConnection 建立到生命周期管理SpacetimeDB 客户端连接实战指南从 DbConnection 建立到生命周期管理 本篇技术指南围绕 SpacetimeDB 1.12.0 客户端的核数据库关系型数据库后端python-sdk 的 MCP 客户端 Client连接、生命周期与全部协议操作实战指南python sdk 的 MCP 客户端 Client 连接、生命周期与全部协议操作实战指南 本篇指南以 Model Context ProtocolMCP人工智能MCP 服务MCP Clients5分钟上手 Mermaid Live Editor免费实时预览与图表分享的在线编辑器5分钟上手 Mermaid Live Editor免费实时预览与图表分享的在线编辑器 Mermaid Live EditorMermaid 在线编辑器是一前端开发者工具数据可视化上一篇Seafile自定义文件格式渲染器开发终极指南打造专属预览体验下一篇Flexbugs完全攻略Web工程师必备的Flexbox兼容性解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
相关推荐
Salt 执行模块 test 全面指南：连接探测、参数传递验证与调试实战
运维配置管理后端 【免费下载链接】salt Software to automate the management and configuration of infrastructure and applications at scale. 项目地址： https://gitcode.com/gh_mirrors/sa/salt 点击查看 免费下载 test 是 Salt 项目中一个特殊的执行模块&am… · 2026/9/23 23:23:26
五子棋AI实战：用C++实现α-β剪枝与博弈树搜索优化
简介：基于C与α-β剪枝算法实现的AI五子棋项目，是一份面向算法学习者、竞赛选手及游戏开发者的完整源码与文档资源。项目以五子棋人机对战为载体，演示了博弈树搜索的核心优化思路：借助α-β剪枝裁剪大量无效分支，只在当… · 2026/9/23 23:23:26
基于Java五子棋对战系统源码：核心模型、网络通信与AI评估
简介：一套基于Java的五子棋对战系统课程设计源码包，面向Java初学者、课设学生及游戏开发爱好者，提供完整可运行的项目与清晰的模块划分，解决从零搭建对战逻辑和界面交互的难题。包内共290个文件，大小18.26MB࿰… · 2026/9/23 23:23:20
合法合规的轻量级媒体播放器开发指南
我无法根据该标题生成符合要求的博文内容。原因如下：标题“橙子电视绿化版_1.0_20240417绿化精简”属于典型的应用软件非官方修改版本命名格式，其中“绿化版”“精简版”等表述，在国内软件分发与版权合规语境下，普遍指向对正版软件… · 2026/9/24 0:02:45
Asterix 开源项目：航空监视数据编解码框架解析与实操
1. 初识 Asterix：这个开源项目到底在解决什么问题第一次看到 Asterix 这个项目名，很多人会联想到那个法国漫画角色，但在开源圈子里，Asterix 指的是一套围绕航空监视数据编解码构建的开源工具集。它的核心任务非常明确：… · 2026/9/24 0:02:39
图联邦学习毕设实战：GCN拆解、结构感知聚合与灾难性遗忘防护
简介：本资源是一套面向本科毕业设计与人工智能课程实践的图联邦学习系统实现方案，聚焦社交网络、知识图谱与推荐系统等典型图数据场景，为算法工程师与高校研究者提供可复现的联邦化GNN开发范例。压缩包共149个文件，含32个核心Pyth… · 2026/9/24 0:02:22
JavaWeb购物车系统实现：基于Session存储的完整工程示例
简介：这是一份面向Java Web初学者的简易购物车系统案例，完整演示了基于Servlet与Tomcat的商品选购流程；案例来自课程设计或实验场景，需求中要求设计商品展示页面，点击“添加到购物车”超链接后进入Servlet记录选购信息… · 2026/9/24 0:01:28
面向对象综合训练：从图书管理系统掌握封装、继承与多态
面向对象学完语法之后，最尴尬的阶段就是“懂的都懂，一写就懵”。day09这个综合训练，说白了就是把前面封装、继承、多态、抽象这些概念，从“背概念”切换到“用概念”。这篇我把自己的练习过程完整拆开，从选题思路到代码… · 2026/9/24 0:01:16
JSP+JDBC+MySQL+Servlet图书管理系统实战：从源码部署到性能优化
简介：面向Java Web初学者，这份图书管理项目源码以图书信息增删改查为主线，完整整合了JSP、JDBC、MySQL与Servlet技术栈，演示了从页面展示、请求处理到数据库读写的基本路径，适合用来理解MVC分层与原生Web开发流程。压缩… · 2026/9/24 0:01:10
基于YOLOv8的渔船作业监控系统：从环境搭建到边缘部署全流程
简介：这是一套面向计算机、人工智能、自动化等专业学生与教师的毕业设计级项目资源，围绕YOLOv8实现渔船作业监控系统，可用于毕设、课程设计、大作业或项目立项演示。压缩包共97个文件，约24.21MB，以70个Python源码文件为… · 2026/9/24 0:00:13
1D-CNN时间序列建模实战：从Conv1d原理到工业落地
简介：面向时间序列数据建模的一维卷积神经网络完整实现，适合深度学习入门者及需要快速验证时序模型的研究者，能够从音频、文本、传感器或股价等序列中挖掘局部特征与时间依赖。压缩包体积很小，只有3KB，内含3个Python脚… · 2026/9/24 0:00:26
柔软的L：汉语语流中被忽视的舌肌张力控制
1. 这个“L”不是字母表里的L，而是舌尖上的L最近在几个方言群和语音教学社群里，反复看到有人发一句：“也说字母L：柔软的长舌”。初看以为是英语发音课笔记，点开才发现全是方言爱好者、播音系学生、语言康复师甚至戏曲演… · 2026/9/24 0:00:44