dsh-plugin-guide 0.3.2 → 0.3.3

package/README.es.md

@@ -25,7 +25,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `0.1.2-alpha.3` (adaptado el 2026-09-01): el sobre de sesión conserva su campo ignorable solo para compatibilidad de lectura de logs almacenados - Session.append aún no puede estamparlo, por lo que el comportamiento de la puerta no cambia. |
+| Harness | DeepSeek Harness `0.1.2-alpha.5` (adaptado el 2026-09-02): el sobre de sesión conserva su campo ignorable solo para compatibilidad de lectura de logs almacenados - Session.append aún no puede estamparlo, por lo que el comportamiento de la puerta no cambia. |
 | Node | `^22.19.0 || >=24.0.0` (runtime de DeepSeek Harness) |
 | Platforms | Todas (bundle ESM plano; sin código nativo, sin red) |
 | Model | Cualquiera (sin interacción con el modelo) |

package/README.hi.md

@@ -25,7 +25,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `0.1.2-alpha.3` (2026-09-01 को अनुकूलित): सत्र लिफ़ाफ़ा अपना ignorable फ़ील्ड केवल संग्रहीत-लॉग पठन संगतता के लिए रखता है - Session.append अभी भी इसे स्टैम्प नहीं कर सकता, इसलिए गेट व्यवहार अपरिवर्तित है। |
+| Harness | DeepSeek Harness `0.1.2-alpha.5` (2026-09-02 को अनुकूलित): सत्र लिफ़ाफ़ा अपना ignorable फ़ील्ड केवल संग्रहीत-लॉग पठन संगतता के लिए रखता है - Session.append अभी भी इसे स्टैम्प नहीं कर सकता, इसलिए गेट व्यवहार अपरिवर्तित है। |
 | Node | `^22.19.0 || >=24.0.0` (DeepSeek Harness रनटाइम) |
 | Platforms | सभी (सादा ESM बंडल; कोई नेटिव कोड नहीं, कोई नेटवर्क नहीं) |
 | Model | कोई भी (कोई मॉडल अंतःक्रिया नहीं) |

package/README.md

@@ -28,7 +28,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `0.1.2-alpha.3` (adapted 2026-09-01): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged. |
+| Harness | DeepSeek Harness `0.1.2-alpha.5` (adapted 2026-09-02): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged. |
 | Node | `^22.19.0 || >=24.0.0` (DeepSeek Harness runtime) |
 | Platforms | All (plain ESM bundle; no native code, no network) |
 | Model | Any (no model interaction) |

package/README.pt.md

@@ -25,7 +25,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `0.1.2-alpha.3` (adaptado em 2026-09-01): o envelope de sessão mantém seu campo ignorable apenas para compatibilidade de leitura de logs armazenados - o Session.append ainda não consegue estampá-lo, então o comportamento da porta não muda. |
+| Harness | DeepSeek Harness `0.1.2-alpha.5` (adaptado em 2026-09-02): o envelope de sessão mantém seu campo ignorable apenas para compatibilidade de leitura de logs armazenados - o Session.append ainda não consegue estampá-lo, então o comportamento da porta não muda. |
 | Node | `^22.19.0 || >=24.0.0` (runtime do DeepSeek Harness) |
 | Platforms | Todas (bundle ESM puro; sem código nativo, sem rede) |
 | Model | Qualquer (sem interação com o modelo) |

package/README.zh.md

@@ -27,7 +27,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `0.1.2-alpha.3`（2026-09-01 已适配）：会话信封保留 ignorable 字段但仅用于存量日志读取兼容——Session.append 仍无法盖章，门控行为不变。 |
+| Harness | DeepSeek Harness `0.1.2-alpha.5`（2026-09-02 已适配）：会话信封保留 ignorable 字段但仅用于存量日志读取兼容——Session.append 仍无法盖章，门控行为不变。 |
 | Node | `^22.19.0 || >=24.0.0`（DeepSeek Harness 运行时） |
 | Platforms | 全部（纯 ESM bundle；无原生代码、无网络） |
 | Model | 任意（无模型交互） |

package/dist/dsh-plugin-dev.js

@@ -1466,7 +1466,7 @@ function suggestionsFor(step, result) {
 	const base = [`tail of "${step}":\n${tailOf(result)}`];
 	if (result.timedOut) base.push(`command timed out; raise --timeout or --smoke-timeout`);
 	if (step === "install") {
-		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.1.2-alpha.3 (older rc.6 PATH builds do not satisfy the compat pin)");
+		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.1.2-alpha.5 (older rc.6 PATH builds do not satisfy the compat pin)");
 		base.push("confirm the profile allowlist matches the repo compat workflow (native builds allowlisted)");
 	}
 	if (step === "headless") base.push("a hang usually means an injected service stayed pending; the smoke timeout surfaces exactly that");
@@ -1587,8 +1587,8 @@ async function main(argv, cwd = process.cwd()) {
 					dshBin: resolveDsh(flagString(flags, "dsh")),
 					pnpmBin: resolvePnpm(flagString(flags, "pnpm")),
 					profile: flagString(flags, "profile", "compat") ?? "compat",
-					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.1.2-alpha.3") ?? "@deepseek-ai/dsh-base@0.1.2-alpha.3",
-					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.1.2-alpha.3") ?? "@deepseek-ai/dsh-headless@0.1.2-alpha.3",
+					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.1.2-alpha.5") ?? "@deepseek-ai/dsh-base@0.1.2-alpha.5",
+					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.1.2-alpha.5") ?? "@deepseek-ai/dsh-headless@0.1.2-alpha.5",
 					timeoutMs: timeoutMs(flags, "timeout", "DSH_PLUGIN_DEV_TIMEOUT", DEFAULT_TIMEOUT_MS),
 					smokeTimeoutMs: timeoutMs(flags, "smoke-timeout", "DSH_PLUGIN_DEV_SMOKE_TIMEOUT", DEFAULT_SMOKE_TIMEOUT_MS)
 				});

package/guide/plugin-dev-guide.md

@@ -185,7 +185,7 @@ export function apply(ctx: Context, config: Config) { /* config 已校验+补默
 2. **waterfall 监听器必须调 `next()`**。
 3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。运行时不变式会断言这一点。
 4. **跨边界 opaque id 用 branded**：`Branded<B>`（`dsh-brand`，纯类型、零运行时依赖），从不裸 `string`；构造走 per-type factory（`SessionId` / `CallId` / `JobId` / `GoalId` 等），防止不同 id 在类型层互换。
-5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read，无信封豁免——`0.1.2-alpha.1` 已移除 `ignorable` 信封、读路径 fail-closed，不认识该事件类型的 build 一律拒绝日志；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。`0.1.2-alpha.3` 恢复信封 `ignorable?: true` 字段但仅用于存量日志读取兼容——其 `Session.append` 第三参为仅 surface 事件的 `SurfaceIntent`，仍无法盖章标记，故自适应门在该线上继续停写（行为不变）。插件新增会话事件时按此契约设计：下游插件事件目前无注册面，写自定义事件的插件用自适应门在无信封宿主上停写（新增模型可见输入见红线 3）。
+5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read，无信封豁免——`0.1.2-alpha.1` 已移除 `ignorable` 信封、读路径 fail-closed，不认识该事件类型的 build 一律拒绝日志；只有结构格式变更才 bump `SESSION_FORMAT_VERSION`。`0.1.2-alpha.5` 恢复信封 `ignorable?: true` 字段但仅用于存量日志读取兼容——其 `Session.append` 第三参为仅 surface 事件的 `SurfaceIntent`，仍无法盖章标记，故自适应门在该线上继续停写（行为不变）。插件新增会话事件时按此契约设计：下游插件事件目前无注册面，写自定义事件的插件用自适应门在无信封宿主上停写（新增模型可见输入见红线 3）。
 
 ---
 

package/guide/quick-reference.es.md

@@ -138,7 +138,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloque com
 5. Paquetes de plugin independientes: cordis es peerDependency con la misma identidad del host (mezclar scoped `@deepseek-ai/cordis` y unscoped divide identidades); ESM; manifiesto `dsh.bundle`; instalaciones git necesitan `prepare` + `allowBuilds`; publica `lib/` o un tarball.
 6. Documentación bilingüe en pares; descripciones/prompts son comportamiento; cambios no triviales llevan Agent Note; ejecuta el conjunto mínimo de checks antes de empujar (dsh-pre-push-checks).
 7. Los ids opacos entre límites son branded (`Branded<B>` de `dsh-brand`), nunca `string` pelado.
-8. Los miembros de `SessionEventMap` son required-on-read: el sobre `ignorable` desaparece en 0.1.2-alpha.1 (la lectura falla cerrada — un build que no conoce un tipo de evento rechaza el log), y los appends de eventos propios de plugins cruzan una puerta adaptativa que deja de escribir en hosts sin sobre; 0.1.2-alpha.3 conserva el campo ignorable?: true solo para compatibilidad de lectura de logs almacenados (su Session.append sigue sin poder estampar el marcador), por lo que la puerta continúa sin escribir (sin cambio de comportamiento). Solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION`. El switch sobre `SessionEvent` cae por un `default` documentado — sin `assertNever` (unión merge-extensible).
+8. Los miembros de `SessionEventMap` son required-on-read: el sobre `ignorable` desaparece en 0.1.2-alpha.1 (la lectura falla cerrada — un build que no conoce un tipo de evento rechaza el log), y los appends de eventos propios de plugins cruzan una puerta adaptativa que deja de escribir en hosts sin sobre; 0.1.2-alpha.5 conserva el campo ignorable?: true solo para compatibilidad de lectura de logs almacenados (su Session.append sigue sin poder estampar el marcador), por lo que la puerta continúa sin escribir (sin cambio de comportamiento). Solo los cambios de formato estructural bumpan `SESSION_FORMAT_VERSION`. El switch sobre `SessionEvent` cae por un `default` documentado — sin `assertNever` (unión merge-extensible).
 
 ## Lista rápida de trampas comunitarias (detalles: guía §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.md

@@ -138,7 +138,7 @@ Chunk protocol: `block-start` → `text-delta*` → `block-end` (complete block)
 5. Standalone plugin packages: cordis is a peerDependency matching the host identity (mixing scoped `@deepseek-ai/cordis` and unscoped splits identities); ESM; `dsh.bundle` manifest; git installs need `prepare` + `allowBuilds`; ship `lib/` or a tarball.
 6. Bilingual docs in pairs; tool descriptions/prompts are behavior; non-trivial changes need an Agent Note; run the minimal check set before pushing (dsh-pre-push-checks).
 7. Opaque cross-boundary ids are branded (`Branded<B>` from `dsh-brand`), never bare `string`.
-8. `SessionEventMap` members are required-on-read: the `ignorable` envelope is gone on 0.1.2-alpha.1 (reads fail closed — a build that does not know an event type refuses the log), and plugin appends of custom events ride an adaptive gate that stops writing on envelope-less hosts; only structural format changes bump `SESSION_FORMAT_VERSION`. 0.1.2-alpha.3 retains the `ignorable?: true` field for stored-log read compatibility only — its `Session.append` third argument is a `SurfaceIntent` for surface events and still cannot stamp the marker, so the gate keeps skipping custom-event appends there (no behavior change). Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
+8. `SessionEventMap` members are required-on-read: the `ignorable` envelope is gone on 0.1.2-alpha.1 (reads fail closed — a build that does not know an event type refuses the log), and plugin appends of custom events ride an adaptive gate that stops writing on envelope-less hosts; only structural format changes bump `SESSION_FORMAT_VERSION`. 0.1.2-alpha.5 retains the `ignorable?: true` field for stored-log read compatibility only — its `Session.append` third argument is a `SurfaceIntent` for surface events and still cannot stamp the marker, so the gate keeps skipping custom-event appends there (no behavior change). Switch over `SessionEvent` falls through a documented `default` — no `assertNever` (merge-extensible union).
 
 ## Community pitfalls quick list (details: guide §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.pt.md

@@ -138,7 +138,7 @@ Protocolo de chunks: `block-start` → `text-delta*` → `block-end` (bloco comp
 5. Pacotes de plugin independentes: cordis é peerDependency com a mesma identidade do host (misturar scoped `@deepseek-ai/cordis` e unscoped divide identidades); ESM; manifesto `dsh.bundle`; instalações git precisam de `prepare` + `allowBuilds`; publique `lib/` ou um tarball.
 6. Documentação bilíngue em pares; descrições/prompts são comportamento; mudanças não triviais levam Agent Note; rode o conjunto mínimo de verificações antes de empurrar (dsh-pre-push-checks).
 7. IDs opacos entre limites são branded (`Branded<B>` de `dsh-brand`), nunca `string` crua.
-8. Membros de `SessionEventMap` são required-on-read: o envelope `ignorable` desaparece no 0.1.2-alpha.1 (a leitura falha fechada — um build que não conhece um tipo de evento recusa o log), e appends de eventos próprios de plugins cruzam uma porta adaptativa que para de gravar em hosts sem envelope; 0.1.2-alpha.3 mantém o campo ignorable?: true apenas para compatibilidade de leitura de logs armazenados (seu Session.append ainda não consegue estampar o marcador), então a porta continua sem gravar (sem mudança de comportamento). Apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION`. O switch sobre `SessionEvent` cai num `default` documentado — sem `assertNever` (união merge-extensible).
+8. Membros de `SessionEventMap` são required-on-read: o envelope `ignorable` desaparece no 0.1.2-alpha.1 (a leitura falha fechada — um build que não conhece um tipo de evento recusa o log), e appends de eventos próprios de plugins cruzam uma porta adaptativa que para de gravar em hosts sem envelope; 0.1.2-alpha.5 mantém o campo ignorable?: true apenas para compatibilidade de leitura de logs armazenados (seu Session.append ainda não consegue estampar o marcador), então a porta continua sem gravar (sem mudança de comportamento). Apenas mudanças de formato estrutural bumpam `SESSION_FORMAT_VERSION`. O switch sobre `SessionEvent` cai num `default` documentado — sem `assertNever` (união merge-extensible).
 
 ## Lista rápida de armadilhas da comunidade (detalhes: guia §7.3 / community-repo-deep-dive.md)
 

package/guide/quick-reference.zh-CN.md

@@ -1,4 +1,4 @@
-# DeepSeek Harness  0.1.2-alpha.3 恢复信封 ignorable?: true 字段但仅用于存量日志读取兼容（其 Session.append 仍无法盖章），门控行为不变。 插件开发速查表
+# DeepSeek Harness  0.1.2-alpha.5 恢复信封 ignorable?: true 字段但仅用于存量日志读取兼容（其 Session.append 仍无法盖章），门控行为不变。 插件开发速查表
 
 > 一页式速查。细节回到 [plugin-dev-guide.md](plugin-dev-guide.md) 与 [references](../references/)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "The dsh-plugin-guide knowledge base plus the dsh-plugin-dev CLI toolchain: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill, with a scaffolder, static checker, and pack verifier for building DSH plugins.",
   "type": "module",
   "main": "index.js",
@@ -62,7 +62,7 @@
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3"
   },
-  "devDependencies": {"@deepseek-ai/dsh-attachment": "0.1.2-alpha.3", 
+  "devDependencies": {"@deepseek-ai/dsh-attachment": "0.1.2-alpha.5", 
     "@types/node": "^22.20.1",
     "vitest": "^3.2.7"
   },
@@ -105,7 +105,7 @@
     ],
     "compatibility": {
       "dshVersions": [
-        "0.1.2-alpha.3"
+        "0.1.2-alpha.5"
       ]
     },
     "capability": {

package/references/official-docs/AGENTS.md

@@ -103,7 +103,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.
 - ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
-- **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct ([package invariant rules](packages/AGENTS.md)).
+- **Runtime invariants assert owned relationships.** Publish `./invariant` only when independent observations can diverge. Otherwise omit its source and wiring and record why in its README; empty installers and checks of service presence, plugin metadata, effects, or fixed examples are invalid ([package invariant rules](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. `SessionEventMap` members are required-on-read by default — builds that do not know a type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).

package/references/official-docs/SNAPSHOT.md

@@ -7,10 +7,10 @@
 |---|---|
 | Source checkout | `D:\deepseek-harness` |
 | Source ref | `origin/master` |
-| Source commit | `dd6322d604e00eec1ba5e0c8541159906a21094a` |
-| Synced at (UTC) | 2026-09-01T15:17:06Z |
+| Source commit | `49a606bc5b5934603f22a26957a07dc799ab0291` |
+| Synced at (UTC) | 2026-09-02T11:48:22Z |
 | Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md` (symlink target text), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml` (the upstream English `README.md` is not in this dir; its snapshot lives in `downloads/github/harness/README.md`), `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |
 | File counts | docs/: 239 md files (117 .zh.md pairs) |
-| Pruned this run | 17 out-of-scope/upstream-deleted entries |
+| Pruned this run | 15 out-of-scope/upstream-deleted entries |
 
 Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).

package/references/official-docs/docs/architecture.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/architecture.md
-architecture.md: ea1719b68e1109ca5446699a59ebb503f7f989e2
-architecture.zh.md: 3e7bbe7d51559d91858ba1062656c36bb390ec96
+architecture.md: 902fd7b53fe7493127da68f9a8f381a33b8edc18
+architecture.zh.md: 2890b32b5db1ac30f6eafef47b019a03c6acedd4

package/references/official-docs/docs/architecture.md

@@ -139,7 +139,8 @@ New behavior attaches to a documented extension point. Changing the loop itself
 | Add durable session state | extend `SessionEventMap`; render and replay from the log |
 | Generate session titles | register the sole `ctx.sessionTitle` provider |
 | Manage a same-session objective | use `ctx.goals`; continue through `agent/*` |
-| Fork a live session | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| Fork a session at a turn boundary | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })` — only agent-loop-published sessions persist |
+| Store sessions in a new backend | implement `SessionPersistence` (`create`/`open`/`stat`/`list`/`export`) over the shared handle scaffolding |
 | Scope a registration to one agent | use that agent's `agent.ctx` |
 
 The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [settings cards](cookbook/adding-a-settings-card.md). The [Conversation subsystem](subsystems/conversation.md) owns Chat-node assembly.

package/references/official-docs/docs/architecture.zh.md

@@ -143,7 +143,8 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统
 | 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 |
 | 生成会话标题 | 注册唯一的 `ctx.sessionTitle` 提供方 |
 | 管理同会话目标 | 使用 `ctx.goals`；通过 `agent/*` 续跑 |
-| fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| 在轮次边界 fork 会话 | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })`——只有经 agent-loop 发布的会话才会持久化 |
+| 在新后端存储会话 | 基于共享的句柄脚手架实现 `SessionPersistence`（`create`/`open`/`stat`/`list`/`export`） |
 | 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` |
 
 [扩展实操手册](cookbook/extension-cookbook.zh.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.zh.md)、[工具](cookbook/adding-a-tool.zh.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.zh.md)和[设置卡片](cookbook/adding-a-settings-card.zh.md)的分步指南。[Conversation 子系统](subsystems/conversation.zh.md)负责 Chat node 组装。

package/references/official-docs/docs/capability-seams.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/capability-seams.md
-capability-seams.md: a6cca7fd2f1d5bd8ee4f3516fa6eb1f5fe828ef8
-capability-seams.zh.md: dcd5e4c71ae0f6db9faf667628b5bee2f27fc862
+capability-seams.md: 83868afe952c5dbc179114ff52228fc1dc8b8fdb
+capability-seams.zh.md: 064797bbc3e5d71c0bdb0b2afe09560577a1b029

package/references/official-docs/docs/capability-seams.md

@@ -162,6 +162,7 @@ flowchart LR
   pkg_code_runtime["code-runtime"]
   svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"]
   pkg_code_runtime_worker_thread["code-runtime-worker-thread"]
+  pkg_experimental_code_runtime_python["experimental-code-runtime-python"]
   pkg_fs["fs"]
   svc_fs["ctx.fs<br/>Filesystem provider seam"]
   pkg_fs_local["fs-local"]
@@ -248,6 +249,7 @@ flowchart LR
   pkg_deepseek_llm_api_extensions --> svc_deepseekLlmApiExtensions
   pkg_e2b --> svc_e2b
   pkg_experimental_agent_team --> svc_agentTeams
+  pkg_experimental_code_runtime_python --> svc_codeRuntime
   pkg_file_reference --> svc_fileReferences
   pkg_file_reference_local --> svc_fileReferences
   pkg_fs --> svc_fs
@@ -515,7 +517,7 @@ flowchart LR
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/shell/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
 | `ctx.approval` | `seam` | [`user-approval`](../packages/interaction/user-approval) | - | [`tools`](../packages/core/tools), [`tool-bash`](../packages/shell/tool-bash), [`acp`](../packages/acp/acp) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
 | `ctx.permissionPresets` | `core` | [`permission-presets`](../packages/interaction/permission-presets) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
-| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for PTC mode). |
+| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread), [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for PTC mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-observation-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compaction` | `seam` | [`compaction`](../packages/compaction/compaction) | [`compaction-basic`](../packages/compaction/compaction-basic) | [`compaction-basic`](../packages/compaction/compaction-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |

package/references/official-docs/docs/capability-seams.zh.md

@@ -164,6 +164,7 @@ flowchart LR
   pkg_code_runtime["code-runtime"]
   svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"]
   pkg_code_runtime_worker_thread["code-runtime-worker-thread"]
+  pkg_experimental_code_runtime_python["experimental-code-runtime-python"]
   pkg_fs["fs"]
   svc_fs["ctx.fs<br/>Filesystem provider seam"]
   pkg_fs_local["fs-local"]
@@ -250,6 +251,7 @@ flowchart LR
   pkg_deepseek_llm_api_extensions --> svc_deepseekLlmApiExtensions
   pkg_e2b --> svc_e2b
   pkg_experimental_agent_team --> svc_agentTeams
+  pkg_experimental_code_runtime_python --> svc_codeRuntime
   pkg_file_reference --> svc_fileReferences
   pkg_file_reference_local --> svc_fileReferences
   pkg_fs --> svc_fs
@@ -517,7 +519,7 @@ flowchart LR
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/shell/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 `sandbox/mode` 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 |
 | `ctx.approval` | `seam` | [`user-approval`](../packages/interaction/user-approval) | - | [`tools`](../packages/core/tools), [`tool-bash`](../packages/shell/tool-bash), [`acp`](../packages/acp/acp) | - | 一次性权限决策通过 `approval/request` waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 `unavailable` 关闭失败。 |
 | `ctx.permissionPresets` | `core` | [`permission-presets`](../packages/interaction/permission-presets) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
-| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 PTC mode 下消费该服务）。 |
+| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread), [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 PTC mode 下消费该服务）。 |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-observation-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
 | `ctx.compaction` | `seam` | [`compaction`](../packages/compaction/compaction) | [`compaction-basic`](../packages/compaction/compaction-basic) | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |

package/references/official-docs/docs/config-catalog.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/config-catalog.md
-config-catalog.md: 5d19ab42f0423cd92fd6227bf1c169db1269d9d4
-config-catalog.zh.md: 77fdabb9da9b78aba6c9704fd0ec5c095ea14679
+config-catalog.md: 6a0f7f23885cd85ccb1ff20e9322f133767aed4a
+config-catalog.zh.md: cae9fa49a6986130c8b7261cf41e04b4d6b4e0e1