easy-agent 接入编辑器或桌面应用:eagent --rpc 的 JSON-RPC over stdio 协议入门指南

原创2026-10-17 16:59:131,964 阅读

easy-agent 接入编辑器或桌面应用:eagent --rpc 的 JSON-RPC over stdio 协议入门指南

Easy Agent(eagent)是一个生产可用的开源终端编码 Agent,支持权限规则、OS 沙箱、MCP、技能(skills)与子代理。除了交互式终端,它还提供 eagent --rpc 模式:把完整的会话 SDK 以 JSON-RPC 2.0 over stdio 的形式服务出去,让编辑器插件、桌面应用,乃至任何非 Node.js 编写的程序都能嵌入它。本文带你用 10 分钟搞懂这套 RPC 协议的传输规则、生命周期和核心方法。

easy-agent 终端编码代理分层架构与 RPC 接入示意

什么是 eagent --rpc?

普通用户在终端里输入 eagent 启动交互式 REPL;加上 --rpc 后,它就变成一个"哑"的 RPC 服务器:

  • 一条命令即服务器:进程只读 stdin、只写 stdout,stdout 上流动的只有 JSON-RPC 消息;
  • 一个进程服务一个工作区:以启动时的当前目录为工作区,同一连接内可同时持有多个会话(session);
  • 双向能力完整:读文件、改代码、跑命令、MCP 工具、插件、权限确认、计划审批、上下文窗口查看,全部通过协议方法暴露。

协议目前处于 experimental 阶段(0.x 版本),携带 protocolVersion(当前为 1):只增不改则保持版本号,删除或改变字段含义才会升版,双方都必须忽略不认识的新字段。完整的机器可读定义见 rpc-protocol.schema.json,官方文档见 rpc.md。

安装与快速上手

先全局安装(需要 Node.js ≥ 22):

npm install -g --ignore-scripts eagent
eagent --version

仓库自带一个约 80 行的完整客户端示例 rpc-client.mjs,它只用了 Node 内置模块。进入你的项目目录运行:

node /path/to/easy-agent/examples/rpc-client.mjs "Explain the build setup"

它会启动 eagent --rpc、初始化工作区、创建会话、发送提示词、流式打印回复,遇到需要确认的工具调用时在终端问你(加 --yes 可全部放行),最后优雅关闭服务器。这就是接入 easy-agent RPC 的最短路径。

传输规则:一行一条 JSON 消息

理解 stdio 传输只需记住 5 条规则:

  1. 一消息一行:每条 JSON-RPC 2.0 消息以换行分隔,UTF-8 编码,双向一致,不支持批量(batch);
  2. stdout 只跑协议:诊断信息一律走 stderr,进程内其他组件想写 stdout 的内容也会被重定向到 stderr;
  3. 请求并发处理:一个耗时的 session/send 不会阻塞 session/interrupt,响应到达顺序不保证,客户端按 id 匹配即可;
  4. 没有 id 就是通知:请求不写 id 即视为 notification,服务端执行但不回包;
  5. 服务器从不发起请求:它需要的一切(比如权限决策)都以事件推送,客户端用 session/respond 应答。

请求发出后即可继续管道式地发下一个;进程在应答 shutdown 或 stdin 关闭后以退出码 0 结束,内部故障则以 1 退出并把错误写入 stderr。

生命周期:从 initialize 到 shutdown

client                                   server
  │  initialize {protocolVersion: 1}        │  启动工作区
  │ ─────────────────────────────────────▶ │
  │ ◀───────────────────────────────────── │  {protocolVersion, workspace, capabilities}
  │  session/create                         │
  │ ─────────────────────────────────────▶ │
  │ ◀── session/event (state_snapshot) ─── │
  │  session/send {sessionId, input}        │
  │ ─────────────────────────────────────▶ │
  │ ◀── session/event (turn_started, text_delta, …)
  │ ◀── session/event (request_opened) ─── │  工具需要确认
  │  session/respond {requestId, response}  │
  │ ─────────────────────────────────────▶ │
  │ ◀── session/event (…, turn_completed) ─│
  │  shutdown                               │  进程退出(exit 0)

initialize 期间会完成工作区引导(信任检查、.env、skills、agents、插件、沙箱),所以客户端可以在此时选择信任模式——任何由工作区配置驱动的东西都在此之后才执行。一个典型请求长这样:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientInfo":{"name":"my-editor"}}}

核心方法速查表

方法 用途
initialize 启动工作区,返回协议版本、工作区信息、能力清单
session/create / session/resume 新建会话 / 恢复已有会话
session/send 发送提示词,一轮对话结束后返回 TurnResult;queue: true 可排队等待
session/event(服务器推送) 流式事件:state_snapshot、text_delta、tool_started、turn_completed 等
session/respond 应答权限、计划审批、提问三类交互请求
session/interrupt 中断当前回合或取消待处理请求
session/rewind 回滚到某个检查点(可恢复文件或对话)
session/checkpoints 列出会话可回退的检查点
config/read / config/write 读取/写入用户、项目、本地三级配置
mcp/approve / mcp/reconnect 审批并管理 .mcp.json 里的 MCP 服务器
plugins/list / plugins/install 插件市场:预览、安装、启停、更新
runtime/reload 重新加载 skills、命令、子代理、插件等
models/check / models/list 检查模型连通性、列出可用模型
shutdown 关闭所有会话,进程以 0 退出

全部方法清单、参数与返回值见 rpc.md 的 Methods 一节,字段级定义见 rpc-protocol.schema.json。

处理权限确认:request_opened 事件

这是编辑器集成里最关键的交互——当 Agent 想执行写文件、跑 shell 等敏感操作时,服务器推送一条事件:

{"jsonrpc":"2.0","method":"session/event","params":{"type":"request_opened","sessionId":"…","seq":12,
 "request":{"kind":"permission","id":"…","toolName":"Write",
            "input":{"file_path":"notes.txt"},"summary":"…","risk":"…","ruleHint":"Write"}}}

客户端展示给用户后,用 session/respond 作答:

请求类型 应答格式
permission {"decision": "allow_once" | "allow_always" | "deny"}
plan_approval {"decision": "approve"} 或 {"decision": "reject","feedback":"…"}
question {"answers": {"<问题>": "<选项>"}} 或 {"cancelled": true}

注意:拒绝规则、沙箱和 Auto Mode 分类器在事件发出之前就已裁决,客户端无法批准被配置明确拒绝的操作——安全边界始终在 easy-agent 一侧。

真实案例:桌面应用里的 RpcClient

easy-agent 仓库自带的桌面端(Electron)就是按这套协议实现的:主进程用 Node 的 child_process 启动 eagent --rpc,然后用一个 RpcClient 类封装收发——按 id 匹配并发响应、把无 id 的消息当作通知分发给 UI 层。相关代码可参考 rpc.ts、host.ts 与 client.ts。

easy-agent 桌面应用首启界面:每个工作区独立运行一个 Agent 进程

它的 UI 层则通过事件投影(projector)把 session/event 流转换成视图状态,见 projector。这套"主进程管协议、渲染进程管展示"的分层思路,可以直接迁移到你自己的 Electron 应用。

常见错误码

错误码 含义
-32700 该行不是合法 JSON
-32601 未知方法
-32602 参数校验失败(data.issues 给出明细)
-32001 在 initialize 成功前调用了其他方法
-32002 协议版本不受支持(data.supported 给出可用版本)
-32003 该连接上没有此 id 的打开会话
-32000 SDK 层拒绝,data.code 区分 busy、closed、untrusted 等具体原因

总结与延伸阅读

  • 一条命令 eagent --rpc,就能把终端编码 Agent 变成跨语言可嵌入的服务;
  • 传输极简:一行一条 JSON、stdout 只跑协议、按 id 匹配并发响应;
  • 交互统一:权限、审批、提问都走 request_opened + session/respond,客户端只处理一种服务器消息;
  • 想深入:docs/rpc.md(协议全文)、docs/sdk.md(事件与库存细节)、examples/rpc-client.mjs(80 行可运行客户端)、src/rpc/protocol.ts(协议 schema 源码)。

把 easy-agent 接进你的编辑器,只需要一个 stdin/stdout 管道。🚀

登录后查看全文
easy-agent