docs(code-runtime-python): state the package's current surface, not its stack position

docs/AGENTS.md:38 keeps PRs, commits, and stack positions out of durable
prose. Both README sides described where this layer sits in a PR stack and
what a later PR would add, which goes stale the moment the backend lands.
Describe what the package owns instead: the wire protocol, with an exported
surface that carries no subprocess execution path.

Re-record README.i18n.yaml.
This commit is contained in:
Chinesezjc
2026-08-17 17:46:40 +08:00
parent a95171b084
commit 8833607469
3 changed files with 6 additions and 6 deletions
@@ -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: a87b52ea6352392952a5833c2e88dfe44779efce
README.zh.md: 62f7e654bc431a7e9b0975541590e8b2780dac0c
README.md: 1fc19b89b751ce5063d6937d588b96f2f36ae69e
README.zh.md: 0351001308541b41ba519b70a61d25c48de73a4b
@@ -4,7 +4,7 @@ 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.
This package is built up across the code-runtime-python PR stack. This layer ships the wire protocol; the `PythonCodeRuntime` implementation that drives a `python3 -I` process over it lands on top of it.
The package owns the wire protocol for that seam: the host-side frame codec and the Python-side mirror of the same message vocabulary.
## Wire protocol
@@ -26,4 +26,4 @@ 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.
- **The `PythonCodeRuntime` implementation and its Python-side JSON codec are not in this layer** — they ship in the backend-core PR on top of this branch; `src/index.ts` re-exports only the protocol vocabulary until then.
- **`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.
@@ -4,7 +4,7 @@
[`@deepseek-ai/dsh-code-runtime`](../code-runtime/README.md) seam 的 CPython 子进程实现。与 [`@deepseek-ai/dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.md) 配套;以全新的 `python3` 子进程取代 Node worker 线程,让模型代码从 TypeScript 换成 Python。
本包分多个 code-runtime-python PR 逐层搭建。本层交付 wire protocol;在其之上驱动 `python3 -I` 进程的 `PythonCodeRuntime` 实现随后落地
本包持有该 seam 的 wire protocolhost 侧的帧编解码,以及 Python 侧对同一套消息词汇的镜像
## Wire protocol
@@ -26,4 +26,4 @@ host 与 CPython 子进程在子进程的 fd 3 上交换一个无版本号的 JS
## 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 加后端真子进程套件捕获,而非本包的测试。
- **`PythonCodeRuntime` 实现与 Python 侧 JSON codec 不在本层** —— 它们在基于本分支的 backend-core PR 中交付;在那之前 `src/index.ts` 只 re-export 协议词汇
- **`src/index.ts` 只导出协议词汇** —— 本包不含子进程执行路径,也不含 Python 侧 JSON codec,因此除 mirror 测试之外没有任何地方会启动 `python3`