Tianyi Cui
409f9ee304
Apply the rename pass to READMEs and docs the master sweep rewrote, fix PTC mode anchors and the renamed-note links in the spill READMEs, and regenerate the doc graphs.
7.7 KiB
description, kind
| description | kind |
|---|---|
| Node host 与 CPython 子进程之间的 fd-3 协议格式（wire protocol），供用户与维护者构建或排查 Python 代码执行后端。 | package-library |
@deepseek-ai/dsh-code-runtime-python
English | 中文
概述
dsh-code-runtime-python 持有 dsh-code-runtime seam 的 Node host 与 CPython 子进程之间的无版本协议格式（wire protocol）：子进程 fd 3 上每行一个 JSON 对象，让 stdout/stderr 空出给程序自己的输出。本包提供 host 侧的帧编解码与敌意帧校验器（src/protocol.ts），以及同一套消息词汇的 Python 侧镜像（py/protocol.py），因此每个 wire 消费方都共享同一套词汇。它是 Python 后端的协议层——本包不含子进程执行路径，因此除跨语言镜像测试之外，没有任何地方会启动 python3。host 把每个入站帧都当作敌意输入，因为模型代码对 fd 3 有完全访问权、可通过它发送任意内容。
目录
使用本包
当你要构建或消费 CPython 代码运行时 wire 时选择本包：实现 Python 后端或驱动它的 host，或排查 Python 代码运行的帧。本包是为 CPython code-runtime 提供方准备的 wire 协议——这样的提供方会在全新的 python3 -I 子进程中运行每个模型程序——本包提供两侧共同使用的协议，因此其导出是 wire 的 TS 侧唯一真源。
你得到什么
本包从 src/index.ts 重新导出 host 侧的协议词汇：validateChildFrame（在 host 读取前重建每个入站帧）、无损 JSON 编解码与计量器（encodeJsonPlain、checkDoneValue、hasUnsafeIntegerToken、hasNonLosslessNumber），以及 logTruncationMarker（共享的截断标记文本）。Python 侧在 py/protocol.py 中把消息形状镜像为 TypedDict，并重新声明两侧都执行的两个表面——PROTOCOL_FD = 3 与标记文本。
协议格式
帧在子进程 fd 3 上以 JSON-lines 传输——每行一个对象——因此 stdout/stderr 保持空闲，供程序自己的输出使用。子进程 → host：boot-ack、call、log、done。host → 子进程：boot（首帧，携带所有上限与命名空间声明）、run（在 boot-ack 之后，只携带程序主体），以及每个 call 一个 reply。伪造帧可以在 done 上同时携带 value 与 error，因此消费方必须先检查 error，在它存在时忽略 value。
可能出什么问题
host 侧校验会静默丢弃垃圾，因此格式错误或伪造的帧绝不会让宿主进程崩溃：validateChildFrame 对任何无法干净重建的内容返回 undefined，非数字的 call id 绝不会被回显进 reply，伪造的额外字段绝不随行。不是无损 JSON、或超出配置字节预算的完成值会被明确拒绝（non-lossless／over-budget），而不会被静默舍入或截断。
理解实现
实现细节——点击展开
本节解释协议格式（wire protocol）背后的设计；可观察行为已在使用本包中完整说明。
设计理念
协议假定单向信任：host 把每个入站帧都当作敌意输入（模型代码可以在 fd 3 上伪造任何内容），并在读取前逐字段重建；Python 侧信任 host 回复，因为 host 不受模型控制。本包刻意只是协议层——Python 侧 JSON codec 位于后端的 bootstrap 中，而非 py/protocol.py，因此镜像保持为 src/protocol.ts 的纯 wire 词汇对侧。
协议约定
帧为 boot／run（host → 子进程）与 boot-ack／call／log／done 加每个 call 一个 reply（子进程 → host）。log 帧的 truncated 标志标记「就是子进程 ledger 截断标记」的那个帧，因此 host 在子进程停下的同一点停止捕获，而不是根据自己的预算推断。done.error.kind 是 exception、invalid-output、output-limit 之一；墙钟／CPU 预算、中止与基底终止在 host 侧观测，不作为帧携带。
无损 JSON 穿越
完成值与 binding 参数以精确 JSON 穿越：值无递归地序列化，因此低于字节预算的深层 payload 能完整穿越，而不是死在 JSON.stringify 的栈限制上；超出安全范围的整数型 double 以精确数字穿越，而不是被静默舍入的 token；src/protocol.ts 中的计量器在任何其他代码读取 payload 之前强制执行字节预算与数字无损性。
镜像对齐
tests/protocol-mirror.e2e.ts 启动一个真实 python3，对照 src/protocol.ts 断言 PROTOCOL_FD／截断标记文本，以及 py/protocol.py 中每个 TypedDict 的必填/可选 wire 字段集，因此重命名或删除字段——或一侧把另一侧必填的字段改为可选——都会让测试失败。跨语言边界不比较字段类型；该残留由 review 加后端的真子进程套件负责。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
插件入口：为每个 wire 消费方重新导出协议词汇 |
src/protocol.ts |
host 侧：帧编解码、敌意帧校验器、无损 JSON 计量器、共享标记文本 |
py/protocol.py |
Python 侧：PROTOCOL_FD、TypedDict 帧镜像、log_truncation_marker |
tests/protocol-mirror.e2e.ts |
对照真实 python3 的跨语言镜像测试 |
src/invariant.ts |
不变式伴生插件（无运行时不变式；本包不注册任何可变数据关系） |
进一步探索
当协议约定不够用时阅读以下内容。它们从 seam 定义进入协议的设计记录与配套后端。
- 代码运行时 seam——Python 后端实现的抽象约定。
- fd-3 协议 Agent Note——设计理由、协议约定与镜像对齐决策。
- Worker 线程后端——已发布的 TypeScript 兄弟包，是 Python 后端行为的模板。
- 代码运行时子系统参考——请求／结果词汇、绑定与失败分类体系。
模型体验
通过 dsh-tools 中的 PTC mode 间接提供；后者把程序的完成值或失败渲染进一个保留的 run_code 结果。
KV Cache 影响
不会直接失效；由上述消费方负责请求前缀变更。
已知限制与延期工作
这些限制说明本包覆盖什么、不覆盖什么；它们是当前包约束，不是任务积压。
- 跨语言 guard 覆盖执行表面与帧字段形状，但不覆盖字段类型——镜像 e2e 比较必填/可选字段集，而不比较
cpuSeconds两侧是否都是int；跨 TypeScript 与 Python 比较类型声明在此无机械等价物，因此类型级漂移由 review 加后端的真子进程套件捕获。 src/index.ts只导出协议词汇——本包不含子进程执行路径，也不含 Python 侧的 JSON codec，因此除镜像测试之外没有任何地方会启动python3。
开发备注
维护者的工作上下文——点击展开
无。