mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-30 04:40:37 +00:00
docs: rebuild the documentation skill and standards (#2983)
This commit is contained in:
Magolor
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-python/README.md
|
||||
README.md: 1fc19b89b751ce5063d6937d588b96f2f36ae69e
|
||||
README.zh.md: 779b802b4013995bc526150c21b3d86391c6dc74
|
||||
README.md: 22015809b88dd9d71d6cc8410b993a8b2ca0d93b
|
||||
README.zh.md: 124ac64d326c5d0a779ceefe6f17cb18bcca8904
|
||||
|
||||
@@ -1,23 +1,100 @@
|
||||
---
|
||||
description: "fd-3 wire protocol between a Node host and a CPython subprocess for users and maintainers building or debugging the Python code-execution backend."
|
||||
kind: "package-library"
|
||||
---
|
||||
|
||||
# @deepseek-ai/dsh-code-runtime-python
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
CPython-subprocess implementation of the [`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam. Companion to [`@deepseek-ai/dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.md); trades the Node worker thread for a fresh `python3` subprocess so model code is Python instead of TypeScript.
|
||||
## Summary
|
||||
|
||||
The package owns the wire protocol for that seam: the host-side frame codec and the Python-side mirror of the same message vocabulary.
|
||||
`dsh-code-runtime-python` owns the versionless wire protocol between a Node host and a CPython subprocess for the [`dsh-code-runtime`](../code-runtime/README.md) seam: one JSON object per line on the child's fd 3, leaving stdout/stderr free for the program's own output. The package ships the host-side frame codec and hostile-frame validators (`src/protocol.ts`) plus the Python-side mirror of the same message vocabulary (`py/protocol.py`), so every consumer of the wire shares one vocabulary. It is the protocol layer for the Python backend — the package carries no subprocess execution path, so nothing here spawns `python3` outside the cross-language mirror test. The host treats every inbound frame as hostile, because model code has full access to fd 3 and can post anything through it.
|
||||
|
||||
## Wire protocol
|
||||
## Table of Contents
|
||||
|
||||
The host and the CPython subprocess exchange a versionless, JSON-lines protocol on the child's fd 3 — one JSON object per line, leaving stdout/stderr free for the program's own output. `src/protocol.ts` is the host side; `py/protocol.py` mirrors its message shapes and the shared truncation-marker text on the Python side.
|
||||
- [Use this package](#use-this-package)
|
||||
- [Understand the implementation](#understand-the-implementation)
|
||||
- [Further Exploration](#further-exploration)
|
||||
- [Model Experience](#model-experience)
|
||||
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
||||
- [Dev Note](#dev-note)
|
||||
|
||||
- **fd 3, not stdout** — Node pins the channel positionally with `stdio: ['pipe','pipe','pipe','pipe']`; the Python bootstrap reads the same `PROTOCOL_FD` constant. JSON-lines framing.
|
||||
- **Host treats every inbound frame as hostile** — model code has full access to fd 3 and can post anything through it, so `validateChildFrame` shape-validates and REBUILDS each frame before the host reads it: forged extra fields never ride along, a non-number call id can never be echoed into a reply, and junk drops to `undefined` rather than throwing in the host's message handler. The Python side trusts host replies (the host is not model-controlled).
|
||||
- **Lossless-JSON crossing** — completion values and binding arguments cross as exact JSON. `encodeJsonPlain` serializes a `JSON.parse`-produced value without recursion, so a deep value below the byte budget crosses intact instead of dying on `JSON.stringify`'s stack limit; `checkDoneValue` meters a forged completion value's byte length AND number losslessness in one traversal that rejects an over-budget payload before the incremental work it would add (the enqueued children; strings and keys are metered by a non-allocating escaped-size scan, so the escaped copy is never materialized) — the frame's own width is already parsed and capped upstream by the host's fd-3 receive buffer, not re-bounded here; `hasUnsafeIntegerToken` reads the raw frame text to catch an integer token that `JSON.parse` would silently round; `hasNonLosslessNumber` rejects a non-finite or negative-zero number in unbounded `call.args`. Beyond-safe-range integral doubles serialize through `BigInt` digits so the exact integer crosses, not the rounded `String()` form.
|
||||
- **Shared truncation marker** — `logTruncationMarker(maxBytes)` produces byte-identical text on both sides, so a truncated log run reads the same however the cap was hit. The `log` frame's `truncated` flag distinguishes the child ledger's own marker from program output.
|
||||
-----
|
||||
|
||||
<a id="use-this-package"></a>
|
||||
## Use this package
|
||||
|
||||
Choose this package when you build or consume the CPython code-runtime wire: implement the Python backend or the host that drives it, or debug a Python code run's framing. The package is the wire protocol intended for a CPython code-runtime provider — such a provider runs each model program in a fresh `python3 -I` subprocess — and this package supplies the protocol both sides speak, so its exports are the single TS-side source of truth for the wire.
|
||||
|
||||
### What you get
|
||||
|
||||
The package re-exports the host-side protocol vocabulary from `src/index.ts`: `validateChildFrame` (rebuilds every inbound frame before the host reads it), the lossless-JSON codec and meters (`encodeJsonPlain`, `checkDoneValue`, `hasUnsafeIntegerToken`, `hasNonLosslessNumber`), and `logTruncationMarker` (the shared truncation-marker text). The Python side mirrors the message shapes as `TypedDict`s in `py/protocol.py` and re-declares the two surfaces both sides execute against — `PROTOCOL_FD = 3` and the marker text.
|
||||
|
||||
### The wire
|
||||
|
||||
Frames travel on the child's fd 3 as JSON-lines — one object per line — so stdout/stderr stay clear for the program's own output. Child → host: `boot-ack`, `call`, `log`, `done`. Host → child: `boot` (first frame, carrying every cap and the namespace declarations), `run` (after `boot-ack`, carrying only the program body), and one `reply` per `call`. A forged frame can carry both `value` and `error` on `done`, so a consumer must check `error` first and ignore `value` when it is set.
|
||||
|
||||
### What can go wrong
|
||||
|
||||
Host-side validation drops junk without throwing, so a malformed or forged frame never crashes the host process: `validateChildFrame` returns `undefined` for anything that does not rebuild cleanly, a non-number call id can never be echoed into a reply, and forged extra fields never ride along. A completion value that is not lossless JSON, or that exceeds the configured byte budget, is rejected explicitly (`non-lossless` / `over-budget`) rather than silently rounded or truncated.
|
||||
|
||||
-----
|
||||
|
||||
<a id="understand-the-implementation"></a>
|
||||
## Understand the implementation
|
||||
|
||||
<details>
|
||||
<summary>Implementation internals — click to expand</summary>
|
||||
|
||||
This section explains the design behind the wire protocol; observable behavior is fully covered in [Use this package](#use-this-package).
|
||||
|
||||
### Design concept
|
||||
|
||||
The protocol assumes one direction of trust: the host treats every inbound frame as hostile (model code can forge anything on fd 3) and REBUILDS it field by field before reading; the Python side trusts host replies, because the host is not model-controlled. The package is deliberately the protocol layer only — the Python-side JSON codec lives in the backend's bootstrap, not in `py/protocol.py`, so the mirror stays the pure wire-vocabulary counterpart of `src/protocol.ts`.
|
||||
|
||||
### Wire contract
|
||||
|
||||
The frames are `boot` / `run` (host → child) and `boot-ack` / `call` / `log` / `done` plus one `reply` per call (child → host). The `log` frame's `truncated` flag marks the frame that IS the child ledger's truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`; wall/CPU budgets, aborts, and substrate death are observed host-side, not carried as frames.
|
||||
|
||||
### Lossless JSON crossing
|
||||
|
||||
Completion values and binding arguments cross as exact JSON: values serialize without recursion, so a deep payload below the byte budget survives instead of dying on `JSON.stringify`'s stack limit, and integral doubles beyond the safe range cross as exact digits rather than silently rounded tokens; the meters in [`src/protocol.ts`](src/protocol.ts) enforce byte budgets and number losslessness before anything else reads the payload.
|
||||
|
||||
### Mirror alignment
|
||||
|
||||
`tests/protocol-mirror.e2e.ts` spawns a real `python3` and asserts, against `src/protocol.ts`, both `PROTOCOL_FD` / the truncation-marker text and each `TypedDict`'s required/optional wire field set in `py/protocol.py`, so a renamed or dropped field — or one side making a field optional the other requires — fails the test. Field *types* are not compared across the language boundary; that residue stays with review plus the backend's real-subprocess suite.
|
||||
|
||||
### Source map
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| [`src/index.ts`](src/index.ts) | Plugin entry: re-exports the protocol vocabulary for every consumer of the wire |
|
||||
| [`src/protocol.ts`](src/protocol.ts) | Host side: frame codec, hostile-frame validators, lossless-JSON meters, shared marker text |
|
||||
| [`py/protocol.py`](py/protocol.py) | Python side: `PROTOCOL_FD`, `TypedDict` frame mirrors, `log_truncation_marker` |
|
||||
| [`tests/protocol-mirror.e2e.ts`](tests/protocol-mirror.e2e.ts) | Cross-language mirror test against a real `python3` |
|
||||
| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the package registers no mutable data relation) |
|
||||
|
||||
</details>
|
||||
|
||||
-----
|
||||
|
||||
<a id="further-exploration"></a>
|
||||
## Further Exploration
|
||||
|
||||
Read these when the protocol contract is not enough. They move from the seam definition to the protocol's design record and the companion backend.
|
||||
|
||||
- [Code runtime seam](../code-runtime/README.md) — the abstract contract the Python backend implements.
|
||||
- [fd-3 protocol Agent Note](../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md) — design rationale, wire contract, and the mirror-alignment decision.
|
||||
- [Worker-thread backend](../code-runtime-worker-thread/README.md) — the shipped TypeScript sibling, the model for the Python backend's behavior.
|
||||
- [Code runtime subsystem reference](../../../docs/subsystems/code-runtime.md) — request/result vocabulary, bindings, and failure taxonomy.
|
||||
|
||||
-----
|
||||
|
||||
<a id="model-experience"></a>
|
||||
## Model Experience
|
||||
|
||||
Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders this backend's exact completion value when it fits (or an explicit `invalid-output` / `output-limit` failure), plus the exact `[dsh-code-runtime-python] log capture truncated at <maxLogBytes> bytes` log marker, into a retained `run_code` result.
|
||||
Indirectly, through Code Mode in `dsh-tools`, which renders the program's completion value or failure into a retained `run_code` result.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
@@ -25,5 +102,20 @@ No direct invalidation; the named consumer owns any request-prefix changes.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **The cross-language guard covers the runtime-executed surfaces and the frame field shapes** — `tests/protocol-mirror.e2e.ts` spawns a real `python3` and asserts, against `src/protocol.ts`, both `PROTOCOL_FD` / the log truncation marker text AND each `TypedDict`'s required/optional wire field set in `py/protocol.py`. What it does not compare is the field *types* (e.g. that `cpuSeconds` is an `int` on both sides): comparing type declarations across TypeScript and Python has no mechanical equivalent here, so a type-level drift is still caught by review plus the backend's real-subprocess suite rather than this package's tests.
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
|
||||
These limits define what the package does and does not cover; they are current package constraints, not a task backlog.
|
||||
|
||||
- **The cross-language guard covers the executed surfaces and the frame field shapes, not the field types** — the mirror e2e compares required/optional field sets, not that `cpuSeconds` is an `int` on both sides; comparing type declarations across TypeScript and Python has no mechanical equivalent here, so a type-level drift is caught by review plus the backend's real-subprocess suite.
|
||||
- **`src/index.ts` exports the protocol vocabulary only** — the package carries no subprocess execution path and no Python-side JSON codec, so nothing here spawns `python3` outside the mirror test.
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### Dev Note
|
||||
|
||||
<details>
|
||||
<summary>Working context for maintainers — click to expand</summary>
|
||||
|
||||
None.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -1,29 +1,121 @@
|
||||
---
|
||||
description: "Node host 与 CPython 子进程之间的 fd-3 协议格式（wire protocol），供用户与维护者构建或排查 Python 代码执行后端。"
|
||||
kind: "package-library"
|
||||
---
|
||||
|
||||
# @deepseek-ai/dsh-code-runtime-python
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
[`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.zh.md) seam 的 CPython 子进程实现。与 [`@deepseek-ai/dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.zh.md) 配套；以全新的 `python3` 子进程取代 Node worker 线程，让模型代码从 TypeScript 换成 Python。
|
||||
## 概述
|
||||
|
||||
本包持有该 seam 的 wire protocol：host 侧的帧编解码，以及 Python 侧对同一套消息词汇的镜像。
|
||||
`dsh-code-runtime-python` 持有 [`dsh-code-runtime`](../code-runtime/README.zh.md) 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 有完全访问权、可通过它发送任意内容。
|
||||
|
||||
## Wire protocol
|
||||
## 目录
|
||||
|
||||
host 与 CPython 子进程在子进程的 fd 3 上交换一个无版本号的 JSON-lines 协议——每行一个 JSON 对象，让 stdout/stderr 空出给程序自己的输出。`src/protocol.ts` 是 host 侧；`py/protocol.py` 在 Python 侧镜像其帧词汇与共享的截断标记文本。
|
||||
- [使用本包](#use-this-package)
|
||||
- [理解实现](#understand-the-implementation)
|
||||
- [进一步探索](#further-exploration)
|
||||
- [模型体验](#model-experience)
|
||||
- [已知限制与延期工作](#known-limitations-and-deferred-work)
|
||||
- [开发备注](#dev-note)
|
||||
|
||||
- **fd 3，而非 stdout** —— Node 通过 `stdio: ['pipe','pipe','pipe','pipe']` 按位置钉住通道；Python bootstrap 读取相同的 `PROTOCOL_FD` 常量。JSON-lines 帧。
|
||||
- **host 把每个入站帧当作敌意输入** —— 模型代码对 fd 3 有完全访问权、可通过它发送任意内容，所以 `validateChildFrame` 在 host 读取前对每个帧做形状校验并重建：伪造的额外字段绝不随行，非数字的 call id 绝不会被回显进 reply，垃圾降为 `undefined` 被丢弃，而不是在 host 的 message handler 里抛错。Python 侧信任 host 回复（host 不受模型控制）。
|
||||
- **lossless-JSON 穿越** —— 完成值与 binding 参数以精确 JSON 穿越。`encodeJsonPlain` 无递归地序列化一个 `JSON.parse` 产出的值，使低于字节预算的深层值能完整穿越，而不是死在 `JSON.stringify` 的栈限制上；`checkDoneValue` 在一次遍历中同时计量伪造完成值的字节长度与数字无损性，在它本会新增的增量工作之前就拒绝超预算 payload（即入栈子节点；字符串与 key 由非分配的转义尺寸扫描计量，从不物化转义副本）——帧自身的宽度已被上游 `JSON.parse` 支付、由 host 的 fd-3 接收缓冲封顶，并非在此重新约束；`hasUnsafeIntegerToken` 读取原始帧文本，捕获 `JSON.parse` 会静默舍入的整数 token；`hasNonLosslessNumber` 拒绝无字节上限的 `call.args` 中的非有限数或负零。超出安全范围的整数型 double 通过 `BigInt` 数字序列化，穿越的是精确整数而非 `String()` 的舍入形式。
|
||||
- **共享截断标记** —— `logTruncationMarker(maxBytes)` 在两侧产出逐字节一致的文本，使被截断的日志运行无论从哪侧触达上限都读起来一致。`log` 帧的 `truncated` 标志把子进程 ledger 自身的标记与程序输出区分开。
|
||||
-----
|
||||
|
||||
## Model Experience
|
||||
<a id="use-this-package"></a>
|
||||
## 使用本包
|
||||
|
||||
经由 [`dsh-tools`](../../core/tools/README.zh.md) 里的 Code Mode 间接生效：Code Mode 把本后端的精确完成值（放得下时）或一个明确的 `invalid-output` / `output-limit` 失败，连同精确的 `[dsh-code-runtime-python] log capture truncated at <maxLogBytes> bytes` 日志标记，渲染进一个保留的 `run_code` 结果。
|
||||
当你要构建或消费 CPython 代码运行时 wire 时选择本包：实现 Python 后端或驱动它的 host，或排查 Python 代码运行的帧。本包是为 CPython code-runtime 提供方准备的 wire 协议——这样的提供方会在全新的 `python3 -I` 子进程中运行每个模型程序——本包提供两侧共同使用的协议，因此其导出是 wire 的 TS 侧唯一真源。
|
||||
|
||||
#### KV Cache effect
|
||||
### 你得到什么
|
||||
|
||||
无直接失效；具名消费者拥有任何请求前缀的变更。
|
||||
本包从 `src/index.ts` 重新导出 host 侧的协议词汇：`validateChildFrame`（在 host 读取前重建每个入站帧）、无损 JSON 编解码与计量器（`encodeJsonPlain`、`checkDoneValue`、`hasUnsafeIntegerToken`、`hasNonLosslessNumber`），以及 `logTruncationMarker`（共享的截断标记文本）。Python 侧在 `py/protocol.py` 中把消息形状镜像为 `TypedDict`，并重新声明两侧都执行的两个表面——`PROTOCOL_FD = 3` 与标记文本。
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
### 协议格式
|
||||
|
||||
- **跨语言 guard 覆盖运行时执行的面与帧字段形状** —— `tests/protocol-mirror.e2e.ts` 启动一个真实 `python3`，对照 `src/protocol.ts` 断言 `PROTOCOL_FD` / 日志截断标记文本，以及 `py/protocol.py` 中每个 `TypedDict` 的必填/可选 wire 字段集。它不比较字段的*类型*（例如 `cpuSeconds` 两侧都是 `int`）：跨 TypeScript 与 Python 比较类型声明在此无机械等价物，故类型级漂移仍由 review 加后端真子进程套件捕获，而非本包的测试。
|
||||
- **`src/index.ts` 只导出协议词汇** —— 本包不含子进程执行路径，也不含 Python 侧的 JSON codec，因此除 mirror 测试之外没有任何地方会启动 `python3`。
|
||||
帧在子进程 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`），而不会被静默舍入或截断。
|
||||
|
||||
-----
|
||||
|
||||
<a id="understand-the-implementation"></a>
|
||||
## 理解实现
|
||||
|
||||
<details>
|
||||
<summary>实现细节——点击展开</summary>
|
||||
|
||||
本节解释协议格式（wire protocol）背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
|
||||
|
||||
### 设计理念
|
||||
|
||||
协议假定单向信任：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`](src/protocol.ts) 中的计量器在任何其他代码读取 payload 之前强制执行字节预算与数字无损性。
|
||||
|
||||
### 镜像对齐
|
||||
|
||||
`tests/protocol-mirror.e2e.ts` 启动一个真实 `python3`，对照 `src/protocol.ts` 断言 `PROTOCOL_FD`／截断标记文本，以及 `py/protocol.py` 中每个 `TypedDict` 的必填/可选 wire 字段集，因此重命名或删除字段——或一侧把另一侧必填的字段改为可选——都会让测试失败。跨语言边界不比较字段*类型*；该残留由 review 加后端的真子进程套件负责。
|
||||
|
||||
### 源码地图
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| [`src/index.ts`](src/index.ts) | 插件入口：为每个 wire 消费方重新导出协议词汇 |
|
||||
| [`src/protocol.ts`](src/protocol.ts) | host 侧：帧编解码、敌意帧校验器、无损 JSON 计量器、共享标记文本 |
|
||||
| [`py/protocol.py`](py/protocol.py) | Python 侧：`PROTOCOL_FD`、`TypedDict` 帧镜像、`log_truncation_marker` |
|
||||
| [`tests/protocol-mirror.e2e.ts`](tests/protocol-mirror.e2e.ts) | 对照真实 `python3` 的跨语言镜像测试 |
|
||||
| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；本包不注册任何可变数据关系） |
|
||||
|
||||
</details>
|
||||
|
||||
-----
|
||||
|
||||
<a id="further-exploration"></a>
|
||||
## 进一步探索
|
||||
|
||||
当协议约定不够用时阅读以下内容。它们从 seam 定义进入协议的设计记录与配套后端。
|
||||
|
||||
- [代码运行时 seam](../code-runtime/README.zh.md)——Python 后端实现的抽象约定。
|
||||
- [fd-3 协议 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md)——设计理由、协议约定与镜像对齐决策。
|
||||
- [Worker 线程后端](../code-runtime-worker-thread/README.zh.md)——已发布的 TypeScript 兄弟包，是 Python 后端行为的模板。
|
||||
- [代码运行时子系统参考](../../../docs/subsystems/code-runtime.zh.md)——请求／结果词汇、绑定与失败分类体系。
|
||||
|
||||
-----
|
||||
|
||||
<a id="model-experience"></a>
|
||||
## 模型体验
|
||||
|
||||
通过 `dsh-tools` 中的 Code Mode 间接提供；后者把程序的完成值或失败渲染进一个保留的 `run_code` 结果。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
不会直接失效；由上述消费方负责请求前缀变更。
|
||||
|
||||
## 已知限制与延期工作
|
||||
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
|
||||
这些限制说明本包覆盖什么、不覆盖什么；它们是当前包约束，不是任务积压。
|
||||
|
||||
- **跨语言 guard 覆盖执行表面与帧字段形状，但不覆盖字段类型**——镜像 e2e 比较必填/可选字段集，而不比较 `cpuSeconds` 两侧是否都是 `int`；跨 TypeScript 与 Python 比较类型声明在此无机械等价物，因此类型级漂移由 review 加后端的真子进程套件捕获。
|
||||
- **`src/index.ts` 只导出协议词汇**——本包不含子进程执行路径，也不含 Python 侧的 JSON codec，因此除镜像测试之外没有任何地方会启动 `python3`。
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### 开发备注
|
||||
|
||||
<details>
|
||||
<summary>维护者的工作上下文——点击展开</summary>
|
||||
|
||||
无。
|
||||
|
||||
</details>
|
||||
|
||||
Reference in New Issue
Block a user