把acpx嵌入你的应用：acpx/runtime嵌入API与共享会话完全指南

把acpx嵌入你的应用acpx/runtime嵌入API与共享会话完全指南【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx不仅是命令行工具它还是Agent Client ProtocolACP的无头客户端——通过acpx/runtime嵌入 API你可以直接在 Node.js 应用里管理有状态的 AI 编码代理会话无需启动子进程、无需解析终端输出。本指南带你掌握两种嵌入模式进程内运行时与共享会话让你把 Codex、Claude Code 等代理无缝接入自己的应用。为什么选择嵌入从敲命令到调 API平时你用acpx codex summarize this repository时其实每次都在启动进程、建立 ACP 连接。如果你的产品需要一个常驻的 AI 会话能力IDE 插件、Web 后台、自动化编排器每次都 spawn 进程就太慢了。好消息是acpx的 npm 包直接导出了运行时入口 ./runtime: ./dist/runtime.js安装后即可import { createAcpRuntime } from acpx/runtime在进程内获得完整的会话管理、权限策略、事件流和模型控制能力。两种嵌入运行时一张表看懂怎么选acpx/runtime提供两套运行时对应两种典型场景对比项createAcpRuntime进程内createSharedAcpRuntime共享会话会话所有者你的应用自己持有应用与 acpx CLI共享同一个本地会话oneshot一次性会话✅ 支持❌ 仅persistentsteer引导式回合✅ 支持❌ 仅prompt每回合权限回调onPermissionRequest✅ 支持❌ 只能静态策略自定义会话存储 / MCP 注入 / 子进程环境变量✅ 支持❌ 不支持与终端 CLI 共用同一对话❌ 各自独立✅ 天然支持选择口诀会话只给你自己用 → 进程内应用和终端要说同一句话、看同一段对话→ 共享会话。三步跑通第一个进程内会话进程内运行时的完整契约定义在 src/runtime/public/contract.ts实现入口是 src/runtime.ts。核心流程只有三步创建运行时指定工作目录、会话存储和权限模式准备会话ensureSession按sessionKey agent复用一个持久会话发起回合startTurn提交提示词消费events事件流等待resultimport { createAcpRuntime, createRuntimeStore } from acpx/runtime; const runtime createAcpRuntime({ cwd: process.cwd(), sessionStore: createRuntimeStore({ stateDir: ~/.acpx }), agentRegistry: undefined, // 使用内置代理注册表 permissionMode: approve-reads, }); const handle await runtime.ensureSession({ sessionKey: reviewer, agent: pi, mode: persistent, }); const turn runtime.startTurn({ handle, requestId: crypto.randomUUID(), mode: prompt, text: Summarize the repository, }); for await (const event of turn.events) { if (event.type text_delta) process.stdout.write(event.text); } console.log(await turn.result);会话状态默认落在~/.acpx/重启应用后同名会话可以带着上下文继续聊——这就是有状态的含义。共享会话让终端和你的应用聊同一个天这是嵌入 API 里最惊艳的能力 ⚡createSharedAcpRuntime()让你的应用和acpxCLI 连接到同一个本地会话所有者源码见 src/runtime/shared.ts官方文档见 docs/shared-sessions.mdimport { createSharedAcpRuntime } from acpx/runtime; const runtime createSharedAcpRuntime({ cwd: process.cwd(), permissionMode: deny-all, }); const handle await runtime.ensureSession({ sessionKey: reviewer, agent: pi, mode: persistent, }); const turn runtime.startTurn({ handle, requestId: crypto.randomUUID(), mode: prompt, text: Summarize the repository, });创建好这个reviewer会话后你的终端立刻就能加入同一场对话acpx pi -s reviewer Review the previous summary acpx pi cancel -s reviewer acpx pi sessions show reviewer应用和终端不会互相抢占连接也不会产生两个竞争性的代理会话。几个使用要点身份作用域共享查找按(agentCommand, cwd, sessionKey)精确匹配不会向父目录回溯。终端必须与你的应用使用相同的用户、主目录、工作目录和代理命令。requestId 每次都要新的重复使用正在排队的 ID 会被拒绝它用于追踪请求不提供幂等重试。取消语义清晰turn.cancel()只针对当前请求不会误伤终端正在跑的回合runtime.cancel({ handle })则像 CLI 一样取消会话当前的活动回合。只读旁听runtime.watchSession({ handle })可以旁观其他客户端的会话事件流适合做实时 UI 面板。shutdown 只是断开runtime.shutdown()让客户端脱身并等待已接纳的操作收尾不会杀掉共享所有者也不会取消已接纳的回合。回合生命周期四个关键信号无论进程内还是共享模式startTurn返回的回合对象都由四个信号组成理解它们就能优雅地驱动 UI信号含义用途promptStarted传输层真正接受了提示词排队结束后再亮发送中状态events异步事件流text_delta、tool_call、status等打字机渲染、工具调用面板result回合结束completed/cancelled/failed收尾逻辑的唯一权威信号cancel()取消本回合也响应你传入的AbortSignal用户点停止 老式写法runTurn(...)会把done/error终止事件混进事件流属于兼容适配器新代码建议直接用startTurn把实时事件和最终结果分开处理。回合失败时result会带结构化错误code、detailCode和retryable字段你可以据此决定提示用户还是自动重试。权限、诊断与错误处理嵌入时最容易踩的坑是权限。运行时支持三档静态权限模式approve-all自动批准第一个允许项approve-reads自动批准读/搜索其余询问deny-all尽量拒绝——CI 和无人值守场景的推荐起点进程内模式还可以传入onPermissionRequest回调把审批弹到你自己的 UI 里共享模式则只接受静态策略因为回合实际运行在所有者进程中无法回调你的进程。两个实用工具runtime.doctor()返回健康报告ok/message/installCommand启动时自检代理是否可用比裸试错友好得多。AcpRuntimeError/isAcpRuntimeError所有运行时错误都带稳定错误码如ACP_BACKEND_UNAVAILABLE、ACP_TURN_FAILED方便你写分支逻辑。错误码全表可参考 docs/ACPX_ERROR_STRATEGY.mdCLI 侧退出码见 docs/exit-codes.md。关键源码与文档索引想深挖实现按这个顺序读想理解什么看哪里嵌入 API 总入口与导出src/runtime.tsAcpRuntime契约、事件与结果类型src/runtime/public/contract.ts进程内运行时实现AcpxRuntime类src/runtime.ts共享运行时SharedAcpRuntimesrc/runtime/shared.ts会话所有者与队列生命周期docs/sessions.md、docs/2026-02-17-architecture.md共享会话完整语义取消/断连/兼容docs/shared-sessions.md会话控制cancel / mode / model / statusdocs/session-control.md内置代理注册表与自定义代理src/agent-registry.ts、docs/custom-agents.md权限模型docs/permissions.md常见疑问 FAQQ共享会话和 CLI 的会话记录是同一份吗是。sessionKey直接映射为 CLI 的会话名查找使用精确的(agentCommand, cwd, name)作用域应用和终端天然看到同一条记录。Q为什么共享模式不支持oneshot和steer共享回合实际运行在会话所有者进程里无法回调你的进程做交互式引导也不能像进程内模式那样排队旁观活动回合——所以 API 在设计上直接拒绝这两种模式避免隐式降级。一次性会话请用进程内运行时。QfindSession和ensureSession有什么区别findSession只查本地记录不会启动代理适合这个会话还开着吗的判断ensureSession会按需创建或复用会话可能拉起整个 ACP 连接。Q嵌入 API 稳定吗acpx目前处于 1.0 之前README 明确提示 CLI 与 runtime 接口仍在演进。建议锁定版本号升级前跑一遍你的集成测试。总结acpx/runtime把无头调用编码代理从命令行脚本升级成了可编程的应用能力 进程内createAcpRuntime完整控制——自定义存储、MCP 注入、交互权限回调、一次性会话一应俱全⚡ 共享createSharedAcpRuntime应用与终端共用一个会话所有者同一场对话、同一份记录、互不抢占 回合四信号promptStarted/events/result/cancel让状态管理与取消逻辑清晰可预测从npm install acpx开始几十行代码就能给你的应用装上持久 AI 会话引擎。【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考