dsh-ptc-plus 0.3.2 → 0.4.1

package/README.en.md

@@ -29,39 +29,51 @@
 
 ---
 
-**PTC Plus gives DSH PTC mode a session-bound persistent TypeScript REPL.** Every `run_code` continues in the same session. Variables, imports, and results from one `run_code` are still available in the next one.
+**PTC Plus gives DSH PTC mode a persistent TypeScript REPL.** Variables, imports, and computed results from one `run_code` remain available to the next. By default, revise names directly: existing closures observe updated bindings, imports can be overridden and re-imported, and failed declarations do not permanently occupy a name.
 
 > [!NOTE]
-> Community plugin, no affiliation with or endorsement from DeepSeek or DSH.
+> Community plugin, with no affiliation with or endorsement from DeepSeek or DSH.
 
 > [!IMPORTANT]
-> Built for `danger-full-access`: direct Node.js and OS access with no extra sandbox. Use it only where that permission scope is acceptable.
+> Built for `danger-full-access`: code can access Node.js and the operating system directly. The plugin adds no sandbox. Use it where that permission scope is acceptable.
 
-![PTC Plus settings card](assets/ptc-plus-settings-en.png)
+## Install
+
+Requires Node.js `^22.19.0 || >=24.0.0` and official DSH with TypeScript PTC mode. Install into your profile, restart DSH, and select PTC mode:
+
+```sh
+dsh plugin --profile <profile> add dsh-ptc-plus
+```
 
-*The settings card exposes live configuration and the `enabled` kill switch.*
+No DSH modifications or custom build are required. See the [installation guide](docs/installation.md) for other installation methods, upgrades, and troubleshooting.
 
 ## What default PTC mode gets wrong
 
-DSH PTC mode starts every `run_code` in a fresh environment. The model computes something, then has to send the same setup code again. One bad line means the whole thing is resent. This plugin attaches `run_code` to a session-backed environment, so later calls reuse what was already there.
+Default PTC mode starts each execution in a fresh environment, so the model must resend setup code. PTC Plus keeps the session's computation state available for subsequent calls.
 
-| Situation | Default PTC mode | With PTC Plus |
+| Scenario | Default PTC mode | With PTC Plus |
 | --- | --- | --- |
-| State | starts from zero, setup resent ❌ | previous `run_code` results stay ✅ |
-| Fixing | wrong result resends the code ❌ | one diff ✅ |
-| Modules | `import` / `export` cannot be written ❌ | written normally, AST handles it ✅ |
-| Values | JSON changes or loses special values ❌ | those values stay intact ✅ |
-| Restart | everything is lost ❌ | recoverable parts come back ✅ |
-| Output and errors | printing floods, errors point elsewhere ❌ | output trimmed, errors map to your line ✅ |
-| Tools | list invisible, miscalls fail ❌ | can inspect; known miscalls become `run_code` ✅ |
-| Paths | relative paths can drift ❌ | session remembers the project directory ✅ |
-| Agent tools | tools needing the agent are rejected ❌ | context restored, goal works ✅ |
+| Continue a calculation | Each call starts fresh and needs the setup code again | Reuse existing variables, functions, imports, and results directly |
+| Fix one mistake | Resend the complete corrected code | Send only the changes with `edit_run_code`, then execute the complete corrected cell |
+| Use module syntax | Static `import` and `export` are invalid inside the function body | Write them directly in cells; the plugin adapts them |
+| Pass special values | JSON cannot fully represent `undefined`, BigInt, cycles, and similar values | Preserve supported special values and reference relationships for further computation and recovery |
+| Find an available tool | Look through the tool interfaces supplied to the model | List and search tools from code, then inspect their parameters as needed |
+| Omit a call summary | Missing `run_code.description` fails validation | Supply a display summary automatically so valid code can proceed |
+| Recover a top-level tool miscall | Undeclared top-level calls are rejected in PTC mode | Convert a miscall to `run_code` when current tool definitions uniquely identify its target and validate the arguments |
+| Access project files | Relative Node paths depend on the host process directory | Resolve file paths, modules, and the default child-process directory from the recorded session project |
+| Locate a code error | Return the native error and stack | Map errors to cell source positions; suggest an edit when a single missing closing delimiter has one verified correction |
+| Inspect computation state | No reusable session variables remain after execution | Inspect retained variables, definitions, and bounded value previews in the REPL tab |
+| Author and reuse helpers | Save the code yourself and load it again in later calls | Author drafts with `/binding`, review them above the composer, and save; enabled bindings work across sessions and supply their interfaces to the model |
+| Try a helper manually | No dedicated code workbench for global bindings | Run unsaved source, test it across successive inputs, and inspect results in a workbench with temporary state separate from the Agent session |
+| Continue after a restart | No computation state spans calls for recovery | Restore verifiable state from the session record and report what could not be recovered |
+
+Global bindings must be enabled in settings. See [Settings](#settings) and [Scope](#scope) below for optional behavior and recovery limits.
 
 ## Three scenes that matter most
 
 ### State carries over
 
-First `run_code`:
+The model first executes:
 
 ```ts
 import { readFile } from 'node:fs/promises'
@@ -70,108 +82,83 @@ const deps = Object.keys(manifest.dependencies ?? {})
 return deps.length
 ```
 
-The next one keeps going:
+The next call continues directly:
 
 ```ts
 return deps.map(dep => dep + '@' + manifest.dependencies[dep])
 ```
 
-`deps` and `manifest` are still there. The setup code is sent only once.
+`deps` and `manifest` remain in the current session. No repeated setup is needed.
 
 ### Fix without resending
 
-By default, a wrong result or a failure sends the whole code block again.
-
-With PTC Plus, it sends one line:
+The model can submit just the replacement:
 
 ```ts
 edit_run_code({ edits: [{ old_string: 'deps.length', new_string: 'deps' }] })
 ```
 
-Only the diff goes in. The full source stays out of the conversation. Exact replacements and regular expressions both have limits, so a bad pattern cannot hang.
-
-When a rejected cell has exactly one validated missing closing token at the end, its diagnostic includes the complete `edit_run_code(...)` call needed to apply that correction and rerun the cell. That generated call carries an `expected_target_call_seq` precondition, so it is rejected without execution if another cell becomes the edit target first. PTC Plus never applies the suggestion automatically; ambiguous repairs or repairs without a persistent target identity still require corrected source.
+Editing reruns the entire cell. Code that has written files or called external services still requires a safe retry. Syntax errors identify the location; an unambiguous missing closing delimiter can also receive a correction suggestion.
 
-### Module syntax
+![Rejected run_code followed by an edit_run_code correction](assets/ptc-plus-repair-en.png)
 
-DSH PTC mode executes each `run_code` as an async function body, where static `import` and `export` declarations are invalid. PTC Plus adapts those forms before execution with AST analysis.
+### Have the Agent author a reusable helper
 
-The model writes normally:
+Enable **Global User Bindings** in settings, then enter:
 
-```ts
-import { readFile } from 'node:fs/promises'
+```text
+/binding new Create textTools to trim outer whitespace while preserving interior spaces
+/binding edit <id> Add line-by-line trimming
 ```
 
-Imports resolve from your project, and named/default imports stay live and read-only. The model never has to know that a `run_code` is really a function body.
-
-## One measured A/B
-
-One identity-blind paired run used `opencode-go/deepseek-v4-flash`. Both arms used the same versioned fixture, task prompts, permissions, and two replicates per task, so 18 sessions per arm.
-
-| Across all 9 tasks | PTC Plus | DSH PTC mode (PTC Plus disabled) | Observed change |
-| --- | ---: | ---: | ---: |
-| Model requests | 66 | 88 | 25.0% fewer |
-| Tool calls | 50 | 79 | 36.7% fewer |
-| Token traffic | 729,642 | 942,901 | 22.6% fewer |
-| Identity-blind rubric score | 138 / 162 | 118 / 162 | +12.3 percentage points |
+The Agent can test and revise the helper incrementally with in-memory REPL examples before submitting a draft. Authoring tests must not modify external files or services. The draft opens above the composer, where you can inspect its source and model prompt, then choose **Save as disabled**, **Save and enable**, or **Discard draft**. Testing and submission do not save a global binding.
 
-The module-syntax task separated the two arms most clearly. PTC Plus finished both replicates with one `run_code` each. DSH PTC mode without PTC Plus finished neither static-import requirement and used eight tool calls across its attempts.
+The panel can be collapsed or closed; the sparkle button's badge reopens it. A successful save or discard closes the panel automatically. The original request retains its source and outcome in history.
 
-This is one stochastic paired observation, not a performance guarantee. Machine budgets were exceeded in 2 of the 18 PTC Plus sessions and 5 of the 18 sessions without PTC Plus, so the matrix as a whole did not pass machine acceptance. Token traffic includes input, cache-read, cache-write, and output tokens. The fixture, pairing rules, metrics, and blind-review protocol are documented in [Evaluation](docs/evaluation.md).
+Before the first message, hover over or click the sparkle button to view and toggle global bindings. These choices apply to all sessions, while the entry itself is registered only while the current session uses the `ptc` or compatible `code` preset. The menu also provides new-binding authoring, existing-binding revision, full management, and a PTC Plus settings shortcut. The settings shortcut opens an in-app dialog containing every plugin setting, while its hover hint still names the host's native settings path. The reusable REPL binding list shows per-binding and total reuse counts from static references in later cells' compiled source, and a redeclaration never resets them.
 
-![Rejected run_code and the follow-up edit_run_code repair](assets/ptc-plus-repair-en.png)
-
-*A real session: the long code and the truthful `edit_run_code` repair call. The repair never resends the source.*
+Enabled binding interfaces are supplied to the model in new sessions and updated at the next permitted request in an existing session. Each binding can include a separate usage prompt or omit its interface. Changing only the prompt preserves the helper's runtime state. Assigning or redeclaring one name in a session overrides only that name; the entry's other names keep working, and the session-local override never writes back to the saved entry. See the [global binding guide](docs/user-bindings.en.md) for details.
 
 ## Settings
 
-Open **Settings → Plugin configuration** to use the card shown above. The card follows the DSH UI language: it renders in English when the harness is set to English, and in Chinese when set to Chinese. The `enabled` switch is live: turning it off leaves only the card and that switch, while turning it on restores the session runtime and `run_code`/`edit_run_code`.
-
-Settings are separated into common and compatibility controls, optional capabilities, advanced behavior, and resource limits. Decisions that need user attention appear before resource limits.
+Choose **PTC Plus settings** in the sparkle menu beside the composer to open the complete settings dialog directly. The host's native entry remains available: on the current release, find the plugin's entry on the side-bar **Plugins** page and choose **Configure**; on the preceding release, open **Settings → Plugin configuration → PTC Plus**. The main switch controls the plugin; other settings are grouped by purpose:
 
-“Use enhanced PTC Plus tool cards” is on by default and provides expandable source, results, execution state, and feature markers. When disabled, `run_code` and `edit_run_code` use DSH's native tool cards. This setting affects presentation only.
+- **Tool call tolerance**: accept `run_code` without a summary and repair uniquely identifiable top-level native-tool miscalls.
+- **REPL syntax**: `bindingUpdates` defaults to `stateful`, allowing cross-cell updates of variables, functions, classes, and import aliases, and letting a repeated declaration in one logical scope of one cell update the same identity; choose `protected` to keep name protection. The five legacy switches apply only while migrating an old configuration; the settings page identifies that state and lets you choose either unified policy directly. Module syntax is enabled by default. `tools` and the injected error classes are request-reserved program bindings that can be neither redeclared nor written: a declaration collision reports `PTC-N001` in preflight, and an assignment fails during execution with an error that names the binding instead of being discarded silently.
+- **Module interoperability**: PTC-managed namespaces support live reads and local overrides, including when passed to external functions. External code independently importing a compiled module through native APIs does not receive the same namespace or writable-export guarantee. See the [runtime reference](docs/runtime-reference.md#cell-semantics).
+- **State and recovery**: control restart recovery and contextual error tips.
+- **Tool extensions**: enable global bindings or official Cordis tools for advanced use.
+- **Interface display**: control enhanced tool cards, the REPL tab, and the binding authoring shortcut.
+- **Resource limits**: adjust execution time, memory, and output limits.
 
-“Allow `run_code` execution without a summary” is on by default. Code still executes when the model omits the outer `description`; with enhanced tool cards enabled, the UI shows a fallback summary. When this setting is disabled, DSH validates the field normally. This setting does not change model requests or original call arguments.
+Global bindings and Cordis tools default to off. Settings generally apply immediately; a worker's memory limit cannot change while it is active. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and limits.
 
-“Allow top-level function/class redeclarations” is independent from the existing variable-redeclaration switch and defaults to off. When enabled, a later cell can use an ordinary named `function` or `class` declaration to replace an existing writable binding. Replacement takes effect at the declaration position and does not emulate function hoisting. Imports, immutable `const` bindings, reserved names, and bindings with unknown provenance are still rejected before execution. Live changes affect subsequently submitted cells; cold recovery always uses the policy recorded for each cell.
+PTC Plus uses a shared stateful computation contract for `run_code`, `edit_run_code`, plugin-owned child computation, and user binding entry points. Source passed to `eval`, `Function`, `node:vm`, or other external engines retains the corresponding native syntax rules and results. Direct `eval` must still access its caller's logical scope; indirect `eval` and `Function` use their owning realm's logical root. Internal name rewriting must not change which state they read. The module interface and native interoperability boundary are described in [ADR 0025](docs/adr/0025-use-versioned-logical-binding-identities.md#managed-module-interface).
 
-In an enabled `ptc` session, the header shows a green `PTC Plus` indicator. Hover, focus, or click it to inspect the variables, functions, classes, and imports available to the next cell and expand their bounded definition source. The card reads submitted source only; it does not inspect runtime values, trigger getters, or execute code. `run_code` and `edit_run_code` remain expandable in the conversation body. A feature marker appears only when result metadata proves that the feature affected that execution.
-
-![Reusable REPL bindings](assets/ptc-plus-bindings-en.png)
+Indirect `eval` and all four `Function` constructors use their owning realm's root, including when passed as native callbacks: after `const value=41`, `["typeof value"].map(eval)` returns `["number"]`. Function source observations retain original JavaScript source and its actual dependencies, so self-contained functions can be recompiled with `Function`. Function values, user overrides, and separately created realms retain their respective semantics.
 
-*A real session: “Reusable REPL bindings” shows the bindings available to the next cell.*
+Switching computation modes preserves existing closures' execution environments and saved function identities, including direct `eval` in asynchronous continuations and `Function.prototype.toString`. Each source generation selects stable callback interfaces while global and prototype properties retain their original values. Legacy code reuses established logical bindings through its native REPL environment, with existing native declarations retaining precedence, and reads modules through PTC-managed namespaces.
 
-Every setting applies live and keeps existing bindings. A submitted cell uses one configuration for its complete execution; changes made while it runs apply to cells submitted afterward. A failed change rolls back. Node fixes a worker's V8 old-generation limit when the worker starts, so that one setting is rejected while a session worker is active and can be changed after the session is disposed. A failed enable is rolled back and persisted as disabled.
+![PTC Plus settings card](assets/ptc-plus-settings-en.png)
 
-`cordisToolsEnabled` is off by default. Turning it on atomically adds DSH's official Cordis tools, owner guidance, and exactly the `cordis-plugin-development` companion Skill to PTC agents; sibling Skills in the shipped preset are not exposed. Turning it off removes all three. It neither switches presets nor changes the direct `run_code`/`edit_run_code` surface. Cordis runs model-written plugins against the live DSH runtime, so enabling it requires shell-level trust.
+The **REPL** tab lets you search session bindings, inspect definitions, and manage global bindings. The global binding workbench's code console can run unsaved source with independent temporary state. File and network operations performed there still have real effects.
 
-When a Cordis call rejects after a cell has assigned a large host or client source string, that top-level binding remains live. Retry only the Cordis call from a short later cell and reuse the binding instead of resending the source.
+![REPL workspace with session inspection and global binding management](assets/ptc-plus-repl-workspace-en.png)
 
-After cold recovery or re-enabling Cordis, recorded Cordis values remain journal data but do not prove that process-local Plugins, Runs, approvals, or earlier Inspect observations are still live. PTC Plus adds a bounded recovery context until a new successful Cordis Inspect call validates the current process.
+On wide screens, the green **PTC Plus** header indicator offers a quick binding list. On narrow screens, use the **REPL** tab:
 
-See [Client UI](docs/client-ui.md), [ADR 0019](docs/adr/0019-plugin-settings-and-kill-switch.md), and [ADR 0020](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md).
+![Reusable REPL bindings](assets/ptc-plus-bindings-en.png)
 
 ## Scope
 
-PTC Plus provides the session-bound persistent `run_code` layer. DSH and the operating system continue to own native-tool authority, policy, approval, cancellation, sandboxing and process governance.
-
-## Install
-
-Requires Node.js `^22.19.0 || >=24.0.0` and DSH with TypeScript PTC mode. Install the published package from npm into the profile you use:
-
-```sh
-dsh plugin --profile <profile> add dsh-ptc-plus
-dsh --profile <profile> --dump-config
-```
-
-Restart that DSH profile after installation. Version-pinned npm, GitHub, local-checkout, and tarball installs are covered in the [installation guide](docs/installation.md).
+DSH continues to own tool permissions, approvals, cancellation, and sandbox policy. Session evaluation runs in a plugin-owned helper process; a stuck or unresponsive helper is reclaimed there, and DSH does not perform an in-host worker kill. PTC Plus cannot recover every state across restarts: external inputs, unverifiable history, and context compaction can reduce the recovered state. Recovery neither repeats nor reverses historical external operations.
 
-For Windows development, double-click `scripts\run-dev-dsh.cmd` to launch an isolated DSH installation from the latest `alpha` dist-tag with only this plugin installed. DSH, plugin snapshots, and the pnpm store are cached and old entries are pruned automatically. The launcher de-duplicates Windows `PATH` in the current process only; it creates no drive mappings or junction trees and does not change the system environment. If a genuinely unique PATH remains too long for `cmd.exe`, it stops before npm or DSH runs and asks you to shorten PATH. When no Web port is supplied, the launcher selects a free loopback port so an existing service on 3080 cannot block the test instance. The default cache is `%LOCALAPPDATA%\dsh-ptc-plus-dev`, outside this repository. See the [installation guide](docs/installation.md) for overrides.
+Value previews have size and type limits; objects that cannot be read reliably appear as unavailable. An enabled binding can also fail initialization, with failures reported in execution results. See the [runtime reference](docs/runtime-reference.md) for details.
 
-`danger-full-access` is the primary supported experience. The worker isolates lifecycle, not malicious code.
+Model calls and token usage depend on the task and model. A recorded paired observation and its limitations are in the [evaluation guide](docs/evaluation.md#recorded-paired-observation).
 
 ## Documentation
 
-[Installation](docs/installation.md) · [Runtime reference](docs/runtime-reference.md) · [Architecture](docs/architecture.md) · [Publishing](docs/publishing.md) · [All docs](docs/README.md)
+[Global binding guide](docs/user-bindings.en.md) · [Installation and upgrades](docs/installation.md) · [Runtime reference](docs/runtime-reference.md) · [Development and architecture](docs/architecture.md) · [Verification and test concurrency](docs/verification.md) · [All documentation](docs/README.md)
 
-MIT licensed. See [LICENSE](LICENSE).
+[MIT License](LICENSE).

package/README.md

@@ -29,39 +29,51 @@
 
 ---
 
-**PTC Plus 给 DSH 的 PTC 模式一个会话绑定的持久 TypeScript REPL。** 每次 `run_code` 都在同一个会话里继续。上一次 `run_code` 的变量、导入和结果，下一次还能直接用。
+**PTC Plus 让 DSH 的 PTC 模式拥有连续的 TypeScript REPL。** 上一次 `run_code` 的变量、导入和计算结果，下一次可以直接复用。默认允许直接同名修订：已有闭包读取更新后的绑定，导入可被局部覆盖再重新导入，失败的声明不会永久占住名称。
 
 > [!NOTE]
 > 社区插件，与 DeepSeek 或 DSH 无隶属、无背书。
 
 > [!IMPORTANT]
-> 面向 `danger-full-access` 设计：可直接访问 Node.js 与操作系统，不另加沙箱。仅在可接受此权限的环境使用。
+> 面向 `danger-full-access` 设计：代码可直接访问 Node.js 与操作系统，插件不另加沙箱。仅在可接受此权限的环境使用。
 
-![PTC Plus 设置卡片](assets/ptc-plus-settings-zh.png)
+## 安装
 
-*设置卡片展示即时配置和 `enabled` 开关。*
+需要 Node.js `^22.19.0 || >=24.0.0` 和支持 TypeScript PTC 模式的官方 DSH。安装到你使用的 profile，然后重启 DSH 并选择 PTC 模式：
 
-## 默认 PTC 模式的问题
+```sh
+dsh plugin --profile <profile> add dsh-ptc-plus
+```
 
-DSH 的 PTC 模式让每次 `run_code` 都从新环境开始。模型算过的东西，下一次还要重发。写错一行，整段代码重发。这个插件把 `run_code` 接到一个会话级环境里，后面的调用直接复用之前的东西。
+无需修改 DSH 或使用定制版本。其他安装方式、升级和故障排查见[安装指南](docs/installation.md)。
+
+## 默认 PTC 模式的问题
 
-| 场景 | 默认 PTC 模式 | 使用 PTC Plus                 |
-| --- | --- |----------------------------|
-| 状态 | 每次从零开始，setup 重发 ❌ | 上一次 `run_code` 的结果直接能用 ✅   |
-| 修错 | 结果不对或失败，整段重发 ❌ | 只发一行 diff ✅                |
-| 模块 | `import` / `export` 不能写 ❌ | 照常写，后台 AST 重写 ✅            |
-| 值 | JSON 改掉或丢失特殊值 ❌ | 这些值原样保留 ✅                  |
-| 重启 | 重启后一切丢失 ❌ | 能恢复的会回来 ✅                  |
-| 输出报错 | 大打印刷屏，报错指到别处 ❌ | 输出裁剪，报错回错的行 ✅              |
-| 工具 | 列表看不见，顶层误发失败 ❌ | 可查看；可确定的误发自动转 `run_code` ✅ |
-| 路径 | 相对路径可能跑偏 ❌ | session 记住项目目录 ✅           |
-| agent 工具 | 需要当前 agent 的工具被拒绝 ❌ | 恢复上下文，goal 等可调 ✅           |
+默认 PTC 模式每次执行都从新环境开始，模型需要重新发送准备代码。PTC Plus 保留会话中的计算状态，让后续调用可以接着完成任务。
+
+| 场景 | 默认 PTC 模式 | 使用 PTC Plus |
+| --- | --- | --- |
+| 接着上次计算 | 每次从新环境开始，需重发准备代码 | 直接复用已有变量、函数、导入和结果 |
+| 修改一处错误 | 修正后重新发送整段代码 | 用 `edit_run_code` 只发修改内容，再执行修正后的完整代码 |
+| 使用模块语法 | 函数体内不能直接写静态 `import`、`export` | 在 cell 中直接写，插件自动适配 |
+| 传递特殊值 | JSON 无法完整表达 `undefined`、BigInt、循环引用等 | 在支持的值范围内保留特殊值及引用关系，供后续计算与恢复 |
+| 查找可用工具 | 从提供给模型的工具接口说明中查找 | 可在代码中列出、搜索工具，并按需查看参数说明 |
+| 调用漏填摘要 | 缺少 `run_code.description` 时校验失败 | 自动补充显示摘要，合法代码可继续执行 |
+| 误发顶层工具调用 | PTC 模式下未声明的顶层调用被拒绝 | 当前工具定义能唯一确认目标且参数合法时，自动转为 `run_code` |
+| 访问项目文件 | Node 相对路径依赖宿主进程目录 | 按会话记录的项目目录解析文件路径、模块和默认子进程目录 |
+| 定位代码错误 | 返回原生错误与堆栈 | 对应到 cell 源码位置；末尾缺少单个闭合符且修正可唯一验证时，给出编辑建议 |
+| 查看计算状态 | 执行结束后不保留可继续使用的会话变量 | REPL 页签展示保留的变量、定义来源和有界值预览 |
+| 编写并复用 helper | 需自行保存代码，并在后续执行中重新加载 | 用 `/binding` 编写草稿，在输入框上方审阅后保存；启用后跨会话使用，并向模型提供接口说明 |
+| 手动试运行 helper | 没有全局绑定的专用代码工作台 | 在工作台运行未保存源码，连续测试并查看结果，临时状态与 Agent 会话分开 |
+| 重启后继续 | 没有跨调用的计算状态可恢复 | 从会话记录恢复可验证的状态，无法恢复的部分明确提示 |
+
+全局绑定需在设置中开启；其余可选行为和恢复范围见下方[设置](#设置)与[范围](#范围)。
 
 ## 三个最直接的场景
 
 ### 状态跨调用
 
-第一个 `run_code` 算完：
+模型第一次执行：
 
 ```ts
 import { readFile } from 'node:fs/promises'
@@ -70,108 +82,83 @@ const deps = Object.keys(manifest.dependencies ?? {})
 return deps.length
 ```
 
-第二个直接接着用：
+下一次直接接着用：
 
 ```ts
 return deps.map(dep => dep + '@' + manifest.dependencies[dep])
 ```
 
-`deps` 和 `manifest` 还在。setup 代码只发一次。
+`deps` 和 `manifest` 仍在当前会话里，无需重发准备代码。
 
 ### 修错不重发
 
-默认情况下，结果不对或执行失败，模型只能把整个代码块再发一遍。
-
-PTC Plus 下它只发这一行：
+模型可以只提交替换内容：
 
 ```ts
 edit_run_code({ edits: [{ old_string: 'deps.length', new_string: 'deps' }] })
 ```
 
-模型只发改动，完整源码留在对话之外。精确文本替换和正则替换都有限制，坏的正则不会卡住。
-
-当被拒 cell 的末尾可唯一验证为缺少一个闭合符时，诊断会直接给出应用该修正并重运行所需的完整 `edit_run_code(...)` 调用。生成的调用带有 `expected_target_call_seq` 前置条件；如果另一个 cell 已先成为 edit 目标，它会拒绝且不执行。PTC Plus 不会自动应用这项建议；有歧义或没有持久目标身份的修复仍需提交修正后的源码。
+编辑会重新执行完整 cell。已经写文件或调用外部服务的代码，仍需确认可以安全重试。语法错误会指出位置；能够明确定位的末尾缺符号错误还会给出修正建议。
 
-### 模块语法
+![被拒的 run_code 与随后的 edit_run_code 修复调用](assets/ptc-plus-repair-zh.png)
 
-DSH 的 PTC 模式把每个 `run_code` 当作 async function body 执行，静态 `import` 和 `export` 声明在这个函数体里无效。PTC Plus 会在执行前用 AST 分析适配这些形式。
+### 让 Agent 编写可复用 helper
 
-模型照常写：
+在设置中开启“全局用户绑定”，然后输入：
 
-```ts
-import { readFile } from 'node:fs/promises'
+```text
+/binding new 创建 textTools，清理文本首尾空白，保留内部空格
+/binding edit <id> 增加逐行清理功能
 ```
 
-依赖从项目解析，具名和默认导入保持 live 且只读。模型不需要知道 `run_code` 其实是一个函数体。
-
-## 一次配对实测
+Agent 可以在会话 REPL 中用内存样例逐步测试和修正，再交出草稿；编写时的测试不得修改外部文件或服务。草稿在输入框上方展开，你可以检查源码和模型提示词，选择“保存为停用”“保存并启用”或“丢弃草稿”。测试和提交本身不会保存全局绑定。
 
-一次身份盲化的配对实验使用了 `opencode-go/deepseek-v4-flash`。两个 arm 使用同一版本夹具、任务 prompt、权限，每个任务重复两次，每个 arm 共 18 个 session。
+草稿面板可折叠或关闭，输入框星光按钮上的角标可重新打开。保存或丢弃成功后自动关闭，历史请求保留当时的源码和结果。
 
-| 9 个任务合计 | PTC Plus | DSH PTC 模式（未启用 PTC Plus） | 本次观测变化 |
-| --- | ---: | ---: | ---: |
-| 模型请求 | 66 | 88 | 减少 25.0% |
-| 工具调用 | 50 | 79 | 减少 36.7% |
-| Token 流量 | 729,642 | 942,901 | 减少 22.6% |
-| 身份盲评量表得分 | 138 / 162 | 118 / 162 | 提高 12.3 个百分点 |
+会话开始前也可以悬停或点击星光按钮，查看并启停全局绑定；这些选择对所有会话生效，但该入口只在当前会话使用 `ptc` 或兼容 `code` preset 时注册。菜单同时提供编写新绑定、修改已有绑定、完整管理入口和 PTC Plus 设置快捷入口；设置快捷入口直接打开包含全部插件配置的应用内窗口，悬浮提示仍标明宿主原生设置页的路径。REPL 可复用绑定列表按后续 cell 源码中的静态引用显示每项复用次数和总复用次数，重定义或重声明不会清零。
 
-模块语法任务的区分最清楚：PTC Plus 两次都只用一次 `run_code` 完成；未启用 PTC Plus 的 DSH PTC 模式两次都未满足静态 import 要求，尝试过程合计用了 8 次工具调用。
-
-这是一次有随机性的配对观测，不是性能保证。预设机器预算在 PTC Plus 的 18 个 session 中有 2 个超限，未启用 PTC Plus 的 18 个 session 中有 5 个超限，因此整组矩阵没有通过 machine acceptance。Token 流量包含 input、cache-read、cache-write 和 output token。夹具、配对规则、指标与盲评流程见[评测说明](docs/evaluation.md)。
-
-![被拒的 run_code 与随后的 edit_run_code 修复调用](assets/ptc-plus-repair-zh.png)
-
-*真实会话：长代码与真实的 `edit_run_code` 修复调用；修复从未重发源码。*
+已启用绑定的接口会提供给新会话中的模型，也会在现有会话的下一次允许请求中更新。每个绑定可以另写使用提示词，或关闭接口展示；仅改提示词不会重置 helper 的运行状态。在会话中给某个名字赋值或重声明只覆盖该名字，同一条目的其他名字继续可用，会话内的覆盖也不会写回保存的条目。详细操作见[全局绑定使用指南](docs/user-bindings.md)。
 
 ## 设置
 
-打开 **设置 → 插件配置** 使用上面的设置卡片。卡片跟随 DSH 界面语言：界面设为 English 时显示英文，设为中文时显示中文。`enabled` 是即时生效的总开关：关闭后只保留卡片和这个开关，开启后恢复 session runtime 以及 `run_code`/`edit_run_code`。
-
-设置按常用与兼容性、可选能力、高级行为和资源限制分区；需要主动决策的选项位于前面，资源限制位于后面。
-
-“使用 PTC Plus 增强工具卡片”默认开启，提供可展开的源码、结果、执行状态和功能标记。关闭后，`run_code` 与 `edit_run_code` 使用 DSH 原生工具卡片；这个开关只影响显示。
+可以从输入框旁的星光菜单选择 **PTC Plus 设置**，直接打开完整设置窗口。宿主原生入口也保留：当前 DSH 在侧栏 **Plugins** 页面里找到本插件的条目并点 **Configure**，旧版 DSH 在 **设置 → 插件配置 → PTC Plus**。总开关控制插件，其余设置按用途分组：
 
-“允许执行缺少摘要的 `run_code`”默认开启。模型没有提供外层 `description` 时，代码仍会执行；启用增强工具卡片时，界面显示备用摘要。关闭本设置后按 DSH 原生规则校验。这个开关不改变模型请求或原始调用参数。
+- **调用容错**：允许缺少摘要的 `run_code`，修复可以准确识别的顶层工具误调用。
+- **REPL 语法**：`bindingUpdates` 默认是 `stateful`，允许跨 cell 更新变量、函数、类和 import alias，也允许同一 cell 内同一逻辑 scope 的重复声明更新同一身份；`protected` 可选择名称保护。`tools` 与注入的错误类是请求保留的程序绑定，既不能重声明也不能写入：冲突在 preflight 报 `PTC-N001`，赋值在执行时以指明该名称的错误失败，不会静默丢弃。旧版五个细分开关仅在迁移旧配置时生效；设置页明确显示尚未迁移的状态，可直接选择任一种统一策略。模块语法默认可用。
+- **模块互操作**：PTC 管理的 namespace 支持实时读取和局部覆盖，传给外部函数后仍保留这些语义。外部代码自行原生导入编译模块不承诺同一 namespace 或可写导出语义，详见[运行时说明](docs/runtime-reference.md#cell-semantics)。
+- **状态与恢复**：控制重启恢复和按需错误提示。
+- **工具扩展**：开启全局绑定，或供高级用户使用的官方 Cordis 工具。
+- **界面显示**：控制增强工具卡片、REPL 页签和绑定编写快捷入口。
+- **资源限制**：调整执行时间、内存和输出上限。
 
-“允许顶层函数/类重声明”与已有的变量重声明开关相互独立，默认关闭。开启后，后续 cell 可以用普通 named `function` / `class` 声明替换已有的可写 binding；替换在声明所在位置生效，不模拟函数提升。import、不可写 `const`、保留名称和来源不明的 binding 仍会在执行前拒绝。开关变化只影响随后提交的 cell，cold recovery 始终按每个 cell 已记录的策略重放。
+全局绑定与 Cordis 工具默认关闭。设置通常即时生效；活动 worker 存在时不能更改其内存上限。字段、默认值和限制见[配置参考](docs/runtime-reference.md#configuration)。
 
-插件启用且会话使用 `ptc` preset 时，会话头部显示绿色 `PTC Plus` 标识。悬浮、聚焦或点击后可以查看下一 cell 可复用的变量、函数、类和 import，并展开其有界定义源码。卡片只读取已提交的源码，不读取运行时值、不触发 getter，也不执行代码。正文中的 `run_code` 与 `edit_run_code` 仍可展开查看源码和结果；只有结果 metadata 能证明某项功能确实生效时，预览才显示对应标记。
+PTC Plus 对 `run_code`、`edit_run_code`、插件自有子计算及用户绑定入口使用共同的有状态计算契约。用户主动调用 `eval`、`Function`、`node:vm` 或其他外部引擎时，动态源码保留对应的原生语法规则与结果；直接 `eval` 仍须访问调用处的逻辑作用域，间接 `eval` 和 `Function` 使用所属 realm 的逻辑根环境，不能因内部名称改写而读错状态。模块接口与原生互操作边界见 [ADR 0025](docs/adr/0025-use-versioned-logical-binding-identities.md#managed-module-interface)。
 
-![REPL 可复用绑定](assets/ptc-plus-bindings-zh.png)
+间接 `eval` 和四种 `Function` 构造器使用所属 realm 的 root，作为原生回调传递时也一样，例如 `const value=41` 后的 `["typeof value"].map(eval)` 返回 `["number"]`。函数源码观察保留原始 JavaScript 源码及其真实依赖，自包含函数可用 `Function` 重新编译；函数值本身、用户改写和另外创建的 realm 保持各自语义。
 
-*真实会话：“REPL 可复用绑定”卡片展示下一 cell 可直接复用的 binding。*
+切换计算模式时，旧闭包仍保留原有执行环境和已保存的函数身份，包括异步继续执行中的直接 `eval` 与 `Function.prototype.toString`。各代源码取得稳定的回调接口，全局和原型属性保持原值；兼容模式通过原生 REPL 环境复用已有逻辑绑定，原有原生声明仍优先，其模块导入也通过 PTC 管理的 namespace 读取。
 
-所有设置都会实时应用，并保留已有 binding。已提交的 cell 在完整执行期间使用同一份配置；执行期间发生的更新用于随后提交的 cell。更新失败会回滚。Node 在 worker 创建时固定 V8 old-generation 上限，因此活动 session worker 存在时修改这一项会被拒绝，释放 session 后才能修改。启用失败时，运行时会回滚并把设置保持为停用。
+![PTC Plus 设置卡片](assets/ptc-plus-settings-zh.png)
 
-`cordisToolsEnabled` 默认关闭。打开后，DSH 官方 Cordis 工具、owner guidance 与精确的 `cordis-plugin-development` companion Skill 会作为一个整体加入 PTC agent；同一 shipped preset 目录中的其他 Skill 不会随之暴露。关闭时这三项也会一起移除；它不切换 preset，也不改变 `run_code`/`edit_run_code` 的直接调用面。Cordis 能在实时 DSH runtime 中运行模型编写的插件，开启它需要接受 shell 级信任。
+在 **REPL** 页签查看会话绑定、搜索名称和检查定义，也可以管理全局绑定。全局绑定工作台中的代码控制台支持试运行未保存的源码，拥有独立的临时状态；执行的文件或网络操作仍会产生真实效果。
 
-如果 Cordis 调用在 cell 已经赋值大段 host 或 client 源码之后才失败，这些顶层 binding 仍会保留。后续只需在短 cell 中重试 Cordis 调用并复用该 binding，无需再次传输源码。
+![REPL 工作区：会话绑定检查与全局绑定管理](assets/ptc-plus-repl-workspace-zh.png)
 
-cold recovery 或重新启用 Cordis 后，已记录的 Cordis value 仍是历史数据，但不能证明进程内 Plugin、Run、approval 或先前 Inspect observation 仍然存活。PTC Plus 会提供有界恢复 context，直到一次新的成功 Cordis Inspect 调用验证当前进程。
+宽屏下，会话头部的绿色 **PTC Plus** 标识提供快捷绑定清单；窄屏可从 **REPL** 页签查看：
 
-详见 [客户端 UI](docs/client-ui.md)、[ADR 0019](docs/adr/0019-plugin-settings-and-kill-switch.md) 与 [ADR 0020](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。
+![REPL 可复用绑定](assets/ptc-plus-bindings-zh.png)
 
 ## 范围
 
-PTC Plus 提供会话绑定的持久 `run_code` 层。原生工具的权限、策略、审批、取消、sandbox 和进程治理仍由 DSH 与操作系统负责。
-
-## 安装
-
-要求 Node.js `^22.19.0 || >=24.0.0`，并已安装带 TypeScript PTC 模式的 DSH。把 npm 正式包安装到你实际使用的 profile：
-
-```sh
-dsh plugin --profile <profile> add dsh-ptc-plus
-dsh --profile <profile> --dump-config
-```
-
-安装后重启对应的 DSH profile。固定 npm 版本、GitHub、本地 checkout 和 tarball 安装方式见[安装指南](docs/installation.md)。
+DSH 继续负责工具权限、审批、取消和沙箱策略。会话求值运行在插件自有的 helper 进程内；卡住或无响应的 helper 会被回收，DSH 宿主进程不执行 in-host worker 强杀。PTC Plus 不保证所有状态都能跨重启恢复；外部输入、无法验证的历史或上下文压缩都可能缩小恢复范围。恢复不会重做或撤销历史外部操作。
 
-Windows 开发时可双击 `scripts\run-dev-dsh.cmd` 启动一个独立的 DSH alpha 最新版并只安装本插件。脚本会缓存 DSH、插件快照和 pnpm 依赖，仅在版本或源码内容变化时更新，并自动清理旧缓存；它会在当前进程内去重 Windows `PATH`，不会创建盘符映射、目录联接或修改系统环境；如果去重后仍超过 `cmd.exe` 限制，会在运行 npm/DSH 前直接提示缩短 PATH。Web 未指定端口时会自动选择空闲回环端口，不会因 3080 被占用而失败。缓存默认位于 `%LOCALAPPDATA%\dsh-ptc-plus-dev`，不会写入本仓库。详细选项见[安装指南](docs/installation.md)。
+值预览有大小和类型限制，无法可靠读取的对象会显示“不可读取”。绑定的启用配置也不等于初始化一定成功，具体失败会在执行结果中说明。更多行为见[运行时参考](docs/runtime-reference.md)。
 
-`danger-full-access` 是首要支持方式。worker 只隔离生命周期，不隔离恶意代码。
+模型调用和 token 用量取决于任务与模型；已有配对观测及其限制见[评测说明](docs/evaluation.md#recorded-paired-observation)。
 
 ## 文档
 
-[安装指南](docs/installation.md) · [运行时参考](docs/runtime-reference.md) · [架构](docs/architecture.md) · [发布](docs/publishing.md) · [全部文档](docs/README.md)
+[全局绑定使用指南](docs/user-bindings.md) · [安装与升级](docs/installation.md) · [运行时参考](docs/runtime-reference.md) · [开发与架构](docs/architecture.md) · [验证与测试并发](docs/verification.md) · [全部文档](docs/README.md)
 
 使用 [MIT License](LICENSE)。