AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

基于换行分隔 stdio 的 JSON-RPC 2.0 ​

模型 client 和 tool server 之间的 transport，就是跑在 stdio 上的 JSON-RPC。自己手搓一遍，你才知道每一层 framing 到底在替你付什么成本。

类型： Build 语言： Python 前置要求： 第 13 阶段第 01-07 课、第 14 阶段第 01 课 预计时间： ~90 分钟

学习目标 ​

  • 通过 stdin/stdout 说 JSON-RPC 2.0，framing 采用按行分隔的 JSON。
  • 正确映射 5 个标准错误码（-32700、-32600、-32601、-32602、-32603），并给出对得上的语义。
  • 区分 request、response、notification 和 batch，而不是发明新的 envelope key。
  • 每一行最多吞掉一个 parse error，不能把后续整条流一起毒死。
  • 用 io.BytesIO 做一个可自终止 demo，让这节课不用起子进程也能跑。
figure
cf-jsonrpc-frames

为什么 JSON-RPC 还在当通用语 ​

2026 年，一个 coding agent 在一场 session 里会同时跟十来个 tool server 说话。每个 server 要么是单独的进程，要么是远端 endpoint。线上的线协议其实十多年都没怎么变：JSON-RPC 2.0 还是那套。它能活到现在，不是因为完美，而是因为它两页纸、足够对称，而且不强迫你在 streaming、batching、transport coupling 里三选一。

JSON-RPC 可以同样跑在 stdio、socket、websocket、HTTP 上。只要 client 和 server 都守规矩，client 就能驱动一个自己没见过的 server。

这节课做的是 stdio 变体。每个请求一行 JSON，每个响应一行 JSON，transport 边界就是 \n。

Wire Shape ​

一共 4 种 envelope。两种由 client 发，两种由 server 回。

mermaid
sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端
    Client->>Server: 请求 {jsonrpc:"2.0", id:7, method:"foo", params:{...}}
    Server-->>Client: 成功 {jsonrpc:"2.0", id:7, result:{...}}
    Client->>Server: 通知 {jsonrpc:"2.0", method:"bar", params:{...}}（无 id）
    Note over Server: 通知不回响应
    Client->>Server: 会失败的请求
    Server-->>Client: 错误 {jsonrpc:"2.0", id:7 or null, error:{code, message, data?}}

notification 没有 id，server 就不能回它。如果 server 对 notification 也写回响应，client 根本不知道该把这条消息挂回哪个调用点。正是这一条规则，把 framing 的复杂度压了下来。

batch 则是一个 JSON 数组，里面装 request 或 notification。server 返回一个响应数组，顺序可以不同，但每个非 notification 条目都要对应一个响应。如果整个 batch 全是 notification，server 什么都不回。

5 个错误码 ​

text
-32700  Parse error      JSON 解析失败
-32600  Invalid Request  envelope 形状错了
-32601  Method not found
-32602  Invalid params
-32603  Internal error

-32000 到 -32099 保留给 server 自定义错误。其余值交给应用自己定。这节课只守 5 个标准码。如果 handler 抛错，transport 就把它包成 -32603，并在 data.exception 里带上异常类名。

parse error 有一条特殊规则：响应里的 id 必须是 null，因为请求连解析都没成功，自然拿不到 id。

换行 framing 与 BytesIO Demo ​

transport 每次读一整行字节，直到 \n。如果一行解析失败，就写回一条 -32700 且 id: null 的错误，然后继续读下一行。整条流不能因此报废。

这节课里我们用一对 io.BytesIO 包起来充当 stdin/stdout。server 读请求直到 EOF，为每条请求写响应，然后退出。client 再把响应读回来。既不用 spawn 进程，也不用处理 timeout。因为 Python 的 io 接口给的是同样的 .readline() / .write() 契约，所以行为和真实子进程管道是一致的。

方法分发 ​

transport 不知道系统里到底有哪些方法。它只把 (method, params) 交给 harness 提供的 handler(method, params)。handler 返回结果，或者抛异常。这里定义 3 个异常类来映射特定错误码：

text
MethodNotFound -> -32601
InvalidParams  -> -32602
Anything else  -> -32603 with exception name in data

transport 不该知道 tool registry。registry 在 handler 背后。这种分层是故意的：transport 只管 JSON-RPC，registry 只管 tool shape，dispatcher（第 23 课）再把两者粘起来。

流上的错误行为 ​

text
client writes              server reads             server writes
---------------            -----------              -------------
{...valid request...}      parses ok                {...response, id matches...}
{...broken json...         parse fails              {id:null, error: -32700}
{...valid request...}      parses ok                {...response, id matches...}
{...missing method...}     invalid envelope         {id:X, error: -32600}

一行坏 JSON，不能停整个 loop。缺 method 字段，也不能停。handler 抛错，同样不能停。transport 一直读到 EOF 为止。

Notification 与非对称流 ​

notification 是 fire-and-forget。harness 会用它发进度事件、取消信号和日志行。一个长时间运行的 tool 可以靠 notification 侧向流式汇报状态，而不用每次都 round-trip。

这节课实现了一个 outbound notification helper：write_notification。server 可以在处理 request 期间用它写出进度。demo 里会展示这种形状：请求进来，handler 发两条进度 notification，最后再写最终响应。

怎么读代码 ​

code/main.py 定义了 StdioTransport、解析辅助函数 parse_request、3 个写辅助函数（write_response、write_error、write_notification），以及主分发循环 serve。错误码常量放在模块顶层。

code/tests/test_transport.py 覆盖了：

  • 5 个标准错误码
  • notification 不应有响应
  • batch 输入输出
  • 坏 JSON 后继续读流
  • handler 在处理中途写 notification 的非对称流程

往前走 ​

这份 transport 足够支撑后面的课程。生产 transport 通常会再补 3 件事：

  • 一个能跨转发链存活的 correlation id
  • 一条取消通道（如 $/cancelRequest）
  • 一次 content-type negotiation handshake，让同一条 socket 能说 JSON-RPC 也能说 Streamable HTTP

注意，这些都不会改变 wire 本身，只是在外面再加一层元数据。