如何让T3 Code连接AI智能体：ACP协议对接与effect-acp包完整解析

如何让T3 Code连接AI智能体ACP协议对接与effect-acp包完整解析【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 通过Agent Client ProtocolACP智能体客户端协议与各类 AI 编码智能体对接核心实现就藏在 packages/effect-acp/ 这个effect-acp包里。本文带你读懂 ACP 是什么、effect-acp 如何基于 Effect 框架设计双向通信以及它如何从上游 JSON Schema 一键生成 TypeScript 类型——一篇看懂这套协议对接 代码生成的完整机制。一、先搞懂 ACPAI 智能体与客户端之间的通用插口ACPAgent Client Protocol是一个开放的通信标准AI 智能体Agent和编码客户端Client通过JSON-RPC 消息走标准输入/输出stdio管道对话。双方各守一方Agent 端如 Cursor Agent、Grok 等命令行智能体负责思考与执行可主动向客户端发起请求申请权限、读写文件、创建终端、推送会话更新Client 端如 T3 Code 的服务端运行时负责管理会话生命周期初始化、新建/加载/分叉/恢复会话、切换模型与配置。上图T3 Code 界面中AI 编码智能体正在执行工具调用并汇报进度——这些交互在底层都由 ACP 消息驱动没有 ACP 这类协议每接一个智能体就要写一套私有适配层有了它客户端只需要实现一次协议就能即插即用所有遵循 ACP 的智能体。二、effect-acp 包在 T3 Code 中的定位在 T3 Code 的 monorepo 中docs/internals/workspace-layout.md 对它的定位非常明确packages/effect-acp是基于 Effect 框架的 ACP 客户端与智能体实现专门供会说 ACP 的供应商驱动使用。该包通过 package.json 暴露 7 个细分入口职责清晰分层入口职责./client客户端角色调用 Agent 的会话方法./agent智能体角色调用 Client 的权限/文件/终端方法./protocol底层协议层stdio 上的双向 RPC 通道./schema生成的全部消息 Schema./rpc、./terminal、./errorsRPC 封装、终端流、结构化错误这种客户端/智能体双视角的设计意味着同一个包既能驱动外部智能体T3 Code 的用法也能把 T3 Code 自身暴露成 ACP 服务端。三、生成原理从上游 Schema 到 TypeScript 的一键管线这是 effect-acp 最巧妙的部分。ACP 的消息格式由上游以 JSON Schema 形式发布effect-acp 不手写任何消息类型而是用一条生成管线同步过来。整个入口是 scripts/generate.ts流程分 5 步版本钉住Pin脚本顶部声明CURRENT_SCHEMA_RELEASE v0.11.3生成过程只会拉取该固定版本发布的schema.unstable.json与meta.unstable.json保证类型定义可复现Schema 归一化normalizeNullableTypes函数递归遍历 Schema把type: [string, null]这类联合类型改写成anyOf结构让下游生成器产出更地道的可空类型调用 Effect 官方生成器使用effect/openapi-generator的JsonSchemaGenerator把每个$defs条目按字母序逐个转成Schema.Struct定义落盘两个生成文件位于 src/_generated/schema.gen.ts上万行的全量消息类型每个类型同时导出 TS 接口和 Effect Schema 双份定义兼顾编译期类型与运行时校验meta.gen.ts导出AGENT_METHODS、CLIENT_METHODS两个方法名常量表和PROTOCOL_VERSION如session_prompt: session/prompt、fs_read_text_file: fs/read_text_file——运行时所有方法名都引用常量而非裸字符串自动格式化生成完毕直接调用oxfmt格式化目录失败则整体报错。文件头会写入// This file is generated by the effect-acp package. Do not edit manually.与当前 ACP 版本号防止误改。升级 ACP 协议 改一行版本号 重新运行生成这就是它生成原理的核心。上图T3 Code 的会话与差异视图——这些状态同步依赖 ACP 的 session/update 通知机制四、协议层设计在 stdio 上跑双向 RPC真正的通信逻辑集中在 src/protocol.ts它基于 Effect 实验性 RPC 模块RpcClient/RpcServerND-JSON 序列化器每行一条 JSON构建。设计上有三个值得注意的点五路队列分流入站消息按类型分流——标准 Agent 方法请求进serverQueue交给 RPC 服务端处理session/update、session/elicitation/complete等通知经 Schema 校验后汇入notificationQueue未识别的扩展方法走onExtRequest回调。出站则统一汇入outgoing队列写入 stdout扩展请求的 Deferred 挂起机制Agent/Client 都可以发起协议未定义的扩展请求。发送时分配自增请求 ID 并挂一个DeferredEffect 的一次性承诺响应到达时按 ID 匹配完成它——相当于在 RPC 之上自己实现了 Promise 语义结构化错误与可观测日志所有失败都收敛为 errors.ts 中的AcpError解析错误、传输错误、流意外结束等并支持按原始/解码后/解码失败三阶段记录协议日志方便排查线上问题。在此之上src/agent.ts 和 src/client.ts 把裸通道包装成带文档的服务AcpAgent暴露requestPermission、readTextFile、createTerminal、sessionUpdate等方法AcpClient暴露initialize、createSession、forkSession、setSessionModel等——调用方拿到的全是类型安全、文档注释齐全的 Effect 函数完全感知不到底层 JSON-RPC 的存在。五、实战T3 Code 如何用它接入 Cursor 与 Grok在 apps/server/src/provider/acp/ 下每个 ACP 供应商一个适配器。以 CursorAcpSupport.ts 为例接线步骤只有三步构造 spawn 参数——命令cursor-agent acp可用设置里的binaryPath覆盖由 T3 Code 进程直接拉起智能体子进程通过 AcpSessionRuntime.ts 建立 effect-acp 客户端层传入认证方式与客户端能力声明初始化协商能力后即可调用session/prompt发消息、订阅session/update流——你在界面上看到的进度与差异视图全部来自这条消息流。GrokX AI供应商同样复用这套运行时仅扩展点不同可见协议抽象确实做到了换智能体不换协议。六、快速上手本地重新生成 ACP Schema想跟进 ACP 上游新版本只需两步以 pnpm workspace 为例修改 scripts/generate.ts 中的CURRENT_SCHEMA_RELEASE为新版本号运行包的generate脚本等价于node scripts/generate.ts详见 package.json 的scripts.generate。生成器会重新下载对应版本的 schema/meta 资产、重写src/_generated/下两个文件并完成格式化。全程无需手写一行消息类型。小结effect-acp 包展示了现代 AI 编码工具链对接智能体的标准姿势协议即契约用 ACP 统一 Agent 与 Client 的通信stdio JSON-RPC任何语言可实现类型即生成Schema 版本钉住 生成器管线协议升级零手写、可复现框架即保障基于 Effect 的队列、Deferred 与 Scope让双向通信的错误处理与资源回收天然可控。读懂这套设计你基本就能看懂 T3 Code 如何即插即用接入任意 ACP 智能体了。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考