easy-agent 接入编辑器或桌面应用:eagent --rpc 的 JSON-RPC over stdio 协议入门指南
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 协议的传输规则、生命周期和核心方法。
什么是 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 条规则:
- 一消息一行:每条 JSON-RPC 2.0 消息以换行分隔,UTF-8 编码,双向一致,不支持批量(batch);
- stdout 只跑协议:诊断信息一律走 stderr,进程内其他组件想写 stdout 的内容也会被重定向到 stderr;
- 请求并发处理:一个耗时的
session/send不会阻塞session/interrupt,响应到达顺序不保证,客户端按id匹配即可; - 没有 id 就是通知:请求不写
id即视为 notification,服务端执行但不回包; - 服务器从不发起请求:它需要的一切(比如权限决策)都以事件推送,客户端用
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。
它的 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 管道。🚀

