From efdc78cba3e9094a73b2e0433f806b466b7ffdcd Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Sat, 1 Aug 2026 13:57:49 +0800 Subject: [PATCH] docs(code-runtime): fix remaining dunder/backend wording and document exports in README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - index.ts: RESERVED_ERROR_MEMBERS JSDoc now says `__x__` (non-empty middle), matching DUNDER_MEMBER and the derivative docs; and PORTABLE_RESERVED_WORDS is described as covering portable *target* languages (Python is a later-PR backend, not yet shipped). - types.ts + type-equiv docs: CodeBindingNamespace.global points to RESERVED_BINDING_GLOBALS by name with an `e.g.` sample rather than enumerating the set (single home), no longer implying `__debug__` is a seeded slot. - Agent Note: separate `__debug__` (CPython compile-time constant) from the seeded bootstrap globals. - README (en/zh): document the four exported exclusion sets and the portable identifier/naming contract — no cross-package link needed. - Regenerate cordis services catalog for the shifted source line. --- ...code-runtime-portable-identifier-seam.i18n.yaml | 4 ++-- ...-07-31-code-runtime-portable-identifier-seam.md | 2 +- ...-31-code-runtime-portable-identifier-seam.zh.md | 2 +- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/code-runtime.i18n.yaml | 4 ++-- docs/core-data-structures/code-runtime.md | 6 +++--- docs/core-data-structures/code-runtime.zh.md | 6 +++--- .../code-runtime/code-runtime/README.i18n.yaml | 4 ++-- packages/code-runtime/code-runtime/README.md | 2 ++ packages/code-runtime/code-runtime/README.zh.md | 2 ++ packages/code-runtime/code-runtime/src/index.ts | 14 ++++++++------ packages/code-runtime/code-runtime/src/types.ts | 6 +++--- 12 files changed, 30 insertions(+), 24 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml index be124ffcbd..45436c96e6 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml @@ -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 .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md -2026-07-31-code-runtime-portable-identifier-seam.md: 72796458d75dc04d094372f13d7253a6a4dad511 -2026-07-31-code-runtime-portable-identifier-seam.zh.md: ce709d5924d0835cd475af6d439c07e1dbceecd0 +2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183 +2026-07-31-code-runtime-portable-identifier-seam.zh.md: 31d2410ee4809d0693f2e7897e61c50163bb0758 diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md index 72796458d7..9e9df50235 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md @@ -15,7 +15,7 @@ A second backend written against a different language (CPython, arriving in a la The seam package (`@deepseek-ai/dsh-code-runtime`) exports the portable-identifier exclusion contract as four named constants, and every backend imports them rather than re-declaring: - `PORTABLE_RESERVED_WORDS` — the union of ECMAScript and Python reserved words. A namespace global or error-class name matching any is refused on all backends, so `lambda` is refused even though it is a legal JS parameter name. Adding a language widens this union, which is a deliberate breaking review of existing binding names. -- `RESERVED_BINDING_GLOBALS` — globals some backend owns in the program's namespace: `console` (the worker's log capture) and `__dsh_main__`/`__builtins__`/`__name__`/`__debug__` (the Python bootstrap's wrapper and seeded module globals). Refused everywhere so a namespace list cannot pick a name that works on one backend and collides on another. +- `RESERVED_BINDING_GLOBALS` — globals some backend owns in the program's namespace: `console` (the worker's log capture), `__dsh_main__`/`__builtins__`/`__name__` (the Python bootstrap's wrapper and seeded module globals), and `__debug__` (not a seeded slot but a CPython compile-time constant that rejects assignment, so an injected global under that name is unreachable — the same portability split by a different mechanism). Refused everywhere so a namespace list cannot pick a name that works on one backend and collides on another. - `RESERVED_ERROR_MEMBERS` — error-member names every backend refuses: the JS `Error` slots (`name`, `message`, `stack`) and Python's exception-protocol members (`args`, `with_traceback`, `add_note`). - `DUNDER_MEMBER` — the dunder-form regex (`__x__`, non-empty middle), refused as an error member wholesale because several are constrained CPython descriptors whose exact set is an interpreter-version detail. diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md index ce709d5924..31d2410ee4 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md @@ -15,7 +15,7 @@ code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表 seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除契约，每个后端导入它们而非重新声明： - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。 -- `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）与 `__dsh_main__`/`__builtins__`/`__name__`/`__debug__`（Python bootstrap 的包装器与预置模块 global）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。 +- `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。 - `RESERVED_ERROR_MEMBERS`——每个后端都拒绝的 error-member 名称：JS `Error` 槽位（`name`、`message`、`stack`）与 Python 异常协议成员（`args`、`with_traceback`、`add_note`）。 - `DUNDER_MEMBER`——dunder 形式正则（`__x__`，非空中缀），作为 error member 被整体拒绝，因为其中若干是受约束的 CPython 描述符，其确切集合是解释器版本细节。 diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 6c670942b2..c2951fa9b2 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -398,7 +398,7 @@ abstract run(request: CodeRunRequest): Promise Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md) -Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts) +Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts) ## `ctx.commands` — `CommandService` diff --git a/docs/core-data-structures/code-runtime.i18n.yaml b/docs/core-data-structures/code-runtime.i18n.yaml index c4bbc64d27..12e29f632a 100644 --- a/docs/core-data-structures/code-runtime.i18n.yaml +++ b/docs/core-data-structures/code-runtime.i18n.yaml @@ -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 docs/core-data-structures/code-runtime.md -code-runtime.md: e7b5a86513abcab90eb81fc0b24296760bf3b926 -code-runtime.zh.md: 17ddbb0f685d97ba3c2dd6a23744771e88a40ed0 +code-runtime.md: 77e4438d16cf83f2a66fbe688c8aface3647e8cb +code-runtime.zh.md: ffd9b5583ee066b837408a03a595962786f192cf diff --git a/docs/core-data-structures/code-runtime.md b/docs/core-data-structures/code-runtime.md index e7b5a86513..77e4438d16 100644 --- a/docs/core-data-structures/code-runtime.md +++ b/docs/core-data-structures/code-runtime.md @@ -99,9 +99,9 @@ interface CodeBindingNamespace { * words, so the same namespace list works against every backend regardless * of `language` — a JS-only spelling like `$tools` is rejected by design, * not just by the Python backend. Names that satisfy the identifier rule but - * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`: `console`, - * `__dsh_main__`, `__builtins__`, `__name__`, `__debug__`) are also refused - * everywhere, since some backend seeds that slot in the program's namespace. + * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`, + * `__dsh_main__`) are also refused everywhere; see its declaration for the + * exact set and why each entry is reserved. */ global: string /** The callable members, keyed by the exact name the program calls. */ diff --git a/docs/core-data-structures/code-runtime.zh.md b/docs/core-data-structures/code-runtime.zh.md index 17ddbb0f68..ffd9b5583e 100644 --- a/docs/core-data-structures/code-runtime.zh.md +++ b/docs/core-data-structures/code-runtime.zh.md @@ -99,9 +99,9 @@ interface CodeBindingNamespace { * words, so the same namespace list works against every backend regardless * of `language` — a JS-only spelling like `$tools` is rejected by design, * not just by the Python backend. Names that satisfy the identifier rule but - * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`: `console`, - * `__dsh_main__`, `__builtins__`, `__name__`, `__debug__`) are also refused - * everywhere, since some backend seeds that slot in the program's namespace. + * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`, + * `__dsh_main__`) are also refused everywhere; see its declaration for the + * exact set and why each entry is reserved. */ global: string /** The callable members, keyed by the exact name the program calls. */ diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml index 8e45c6265b..33f092d79b 100644 --- a/packages/code-runtime/code-runtime/README.i18n.yaml +++ b/packages/code-runtime/code-runtime/README.i18n.yaml @@ -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/README.md -README.md: c7a2d519e47d160f5ab123bfc887e7e9f24ec602 -README.zh.md: 22d0b120d7cea50b578a184b3e40d77707ebc489 +README.md: fafaca85ac63e83e16882ef17f9f8995103866fd +README.zh.md: dc771bc16557d4b68529f2fde29eef1c09f299b5 diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md index c7a2d519e4..fafaca85ac 100644 --- a/packages/code-runtime/code-runtime/README.md +++ b/packages/code-runtime/code-runtime/README.md @@ -20,6 +20,8 @@ Semantics every implementation must honor (contract details in the class JSDoc): `CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the seam-local structural equivalent of canonical `JsonValue` that keeps this interface package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts. +Binding-global and error-class names are **language-portable**: they must match the identifier subset `[A-Za-z_][A-Za-z0-9_]*` (no JS-only `$`) and clear the seam-exported exclusion sets, so one `bindings` list is valid against every backend regardless of its `language`. The package exports the contract every backend enforces — `PORTABLE_RESERVED_WORDS` (ECMAScript ∪ Python reserved words), `RESERVED_BINDING_GLOBALS` (backend-owned globals such as `console`), `RESERVED_ERROR_MEMBERS` and `DUNDER_MEMBER` (error-member exclusions) — so a name like `$tools`, `lambda`, or `__dsh_main__` makes `run()` reject as seam misuse on any backend, not just some. See `src/index.ts` for the exact sets and rationale. + ## Model Experience Indirectly, through Code Mode in `dsh-tools`, which exposes `run_code` and returns program logs, values, or failures as retained tool-result tokens. diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md index 22d0b120d7..dc771bc165 100644 --- a/packages/code-runtime/code-runtime/README.zh.md +++ b/packages/code-runtime/code-runtime/README.zh.md @@ -20,6 +20,8 @@ `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`。 + ## 模型体验 通过 `dsh-tools` 中的 Code Mode 间接提供；后者公开 `run_code`，并将程序日志、值或失败作为保留的工具结果 token 返回。 diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts index 2e4f18a2e2..3aeb6a39a8 100644 --- a/packages/code-runtime/code-runtime/src/index.ts +++ b/packages/code-runtime/code-runtime/src/index.ts @@ -48,10 +48,10 @@ export const RESERVED_BINDING_GLOBALS: ReadonlySet = new Set([ * one shared contract so a request valid on one backend is valid on all. The * JS `Error` exclusions (`name`, `message`, `stack`) and Python's * exception-protocol members (`args`, `with_traceback`, `add_note`) are - * listed by name; dunder-form names (`__*__`) are refused wholesale — several - * are constrained CPython descriptors whose `setattr` raises while - * constructing the rejection, and the exact set is an interpreter version - * detail. Any other non-empty own property name is accepted everywhere. + * listed by name; dunder-form names (`__x__`, non-empty middle) are refused + * wholesale — several are constrained CPython descriptors whose `setattr` + * raises while constructing the rejection, and the exact set is an interpreter + * version detail. Any other non-empty own property name is accepted everywhere. */ export const RESERVED_ERROR_MEMBERS: ReadonlySet = new Set([ 'name', 'message', 'stack', @@ -65,9 +65,11 @@ export const RESERVED_ERROR_MEMBERS: ReadonlySet = new Set([ export const DUNDER_MEMBER = /^__.+__$/ /** - * Reserved words of EVERY shipped backend language (ECMAScript ∪ Python), + * Reserved words of every portable target language (ECMAScript ∪ Python), * refused as {@link CodeBindingNamespace.global} / error-class names by all - * backends. The portable-identifier contract promises a namespace list valid + * backends. Python is a portability target here even though only the + * TypeScript worker ships in this PR (the CPython backend is a later PR in the + * stack). The portable-identifier contract promises a namespace list valid * on one backend is valid on every backend; a per-language check would let * `lambda` pass the TypeScript backend and fail the Python one. Extending the * seam with a new language means widening this union (a breaking review of diff --git a/packages/code-runtime/code-runtime/src/types.ts b/packages/code-runtime/code-runtime/src/types.ts index e6c3b5ddc2..6d83ace689 100644 --- a/packages/code-runtime/code-runtime/src/types.ts +++ b/packages/code-runtime/code-runtime/src/types.ts @@ -53,9 +53,9 @@ export interface CodeBindingNamespace { * words, so the same namespace list works against every backend regardless * of `language` — a JS-only spelling like `$tools` is rejected by design, * not just by the Python backend. Names that satisfy the identifier rule but - * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`: `console`, - * `__dsh_main__`, `__builtins__`, `__name__`, `__debug__`) are also refused - * everywhere, since some backend seeds that slot in the program's namespace. + * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`, + * `__dsh_main__`) are also refused everywhere; see its declaration for the + * exact set and why each entry is reserved. */ global: string /** The callable members, keyed by the exact name the program calls. */