docs(i18n): standardize contract terminology

2026-08-09 11:33:14 +08:00
parent 5d46c11784
commit a7af54a8d3
848 changed files with 1506 additions and 1506 deletions
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime/README.md
 README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: fff62b97b8ef76901e4680fb6c6c8ff4820ba35d
+README.zh.md: 2a68e6f05d12b737bdff530a351aa038628d85fc
@@ -14,11 +14,11 @@
 | `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |

-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整约定见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。

 ## 词汇

-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。

 binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。

@@ -33,6 +33,6 @@ binding-global 与 error-class 名称是**语言可移植**的：必须匹配标
 ## 已知限制与暂缓事项

 - **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
+- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的约定继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
 - **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。