dsh-ptc-plus 0.4.1 → 0.4.3

package/README.md

@@ -1,24 +1,13 @@
 <p align="center">
-  <img src="assets/dsh-ptc-plus-banner-zh.webp" width="100%" alt="dsh-ptc-plus 横幅">
+  <img src="assets/dsh-ptc-plus-banner-zh.webp" width="100%" alt="PTC Plus：不用从头来，改一改，接着算！">
 </p>
 
 <p align="center">
-  <strong>简体中文</strong> ·
-  <a href="README.en.md">English</a>
-</p>
-
-<p align="center">
-  <a href="#%E9%BB%98%E8%AE%A4-ptc-%E6%A8%A1%E5%BC%8F%E7%9A%84%E9%97%AE%E9%A2%98">问题</a> ·
-  <a href="#%E4%B8%89%E4%B8%AA%E6%9C%80%E7%9B%B4%E6%8E%A5%E7%9A%84%E5%9C%BA%E6%99%AF">场景</a> ·
-  <a href="#%E8%AE%BE%E7%BD%AE">设置</a> ·
-  <a href="#%E8%8C%83%E5%9B%B4">范围</a> ·
-  <a href="#%E5%AE%89%E8%A3%85">安装</a> ·
-  <a href="#%E6%96%87%E6%A1%A3">文档</a>
+  <strong>简体中文</strong> · <a href="README.en.md">English</a>
 </p>
 
 <p align="center">
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img alt="DeepSeek Harness PTC mode" src="https://img.shields.io/badge/DeepSeek%20Harness-PTC%20mode-4b6bfb"></a>
-  <a href="package.json"><img alt="Node.js ^22.19.0 || >=24.0.0" src="https://img.shields.io/badge/Node.js-%5E22.19.0%20%7C%7C%20%3E%3D24.0.0-5fa04e?logo=nodedotjs&logoColor=white"></a>
   <a href="https://www.npmjs.com/package/dsh-ptc-plus"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-ptc-plus?logo=npm"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
 </p>
@@ -27,53 +16,132 @@
   <a href="https://awesome-dsh-plugin.com/zh/"><img alt="Awesome DSH Plugin" src="https://awesome-dsh-plugin.com/badge.svg"></a>
 </p>
 
----
+**让模型在同一会话中持续计算、直接修订，减少重复工作和可避免的工具调用错误。**
 
-**PTC Plus 让 DSH 的 PTC 模式拥有连续的 TypeScript REPL。** 上一次 `run_code` 的变量、导入和计算结果，下一次可以直接复用。默认允许直接同名修订：已有闭包读取更新后的绑定，导入可被局部覆盖再重新导入，失败的声明不会永久占住名称。
+PTC Plus 为 DSH 的 **PTC 模式**提供有状态的 TypeScript 计算环境。它基于 REPL，让变量、函数、导入和中间结果跨工具调用复用；针对模型连续编写和修改代码的需要，扩展声明更新规则，并提供模块语法适配、调用容错和代码编辑能力。
 
-> [!NOTE]
-> 社区插件，与 DeepSeek 或 DSH 无隶属、无背书。
+- **接着算**：读取和整理过的数据留在会话里，下一次调用直接继续。
+- **直接改**：同名修订变量或函数，已有闭包读取更新后的绑定；小改动可以只发送代码差异。
+- **少些调用错误**：适配常用模块语法，处理可准确识别的调用遗漏，并为可验证的语法错误提供修正建议。
+- **复用常用能力**：把常用函数保存为全局绑定，向模型提供接口与使用提示，在多个会话中使用。
 
-> [!IMPORTANT]
-> 面向 `danger-full-access` 设计：代码可直接访问 Node.js 与操作系统，插件不另加沙箱。仅在可接受此权限的环境使用。
+[快速开始](#快速开始) · [功能概览](#功能概览) · [连续计算](#连续计算与语言扩展) · [代码编辑与容错](#代码编辑与调用容错) · [全局绑定](#全局绑定跨会话复用常用函数) · [界面与设置](#界面与设置) · [状态与恢复](#值传递与状态恢复)
 
-## 安装
+## 快速开始
 
-需要 Node.js `^22.19.0 || >=24.0.0` 和支持 TypeScript PTC 模式的官方 DSH。安装到你使用的 profile，然后重启 DSH 并选择 PTC 模式：
+需要 Node.js `^22.19.0 || >=24.0.0` 和最新可用的官方 DSH。将插件安装到实际使用的 profile：
 
 ```sh
 dsh plugin --profile <profile> add dsh-ptc-plus
 ```
 
-无需修改 DSH 或使用定制版本。其他安装方式、升级和故障排查见[安装指南](docs/installation.md)。
+将 `<profile>` 替换为实际 profile 名称。安装后重启 DSH，在会话中选择 **PTC 模式**。连续计算、调用容错和全局绑定默认开启；已有配置中显式关闭的选项会保持关闭。
 
-## 默认 PTC 模式的问题
+在默认界面设置下，会话中会出现 **REPL** 页签；宽屏顶部还会显示绿色 **PTC Plus** 标志。输入框旁的星光按钮可打开全局绑定菜单和 **PTC Plus 设置**。也可从侧边栏 **插件 → 已安装 → dsh-ptc-plus → 配置** 检查插件总开关和全部设置。
 
-默认 PTC 模式每次执行都从新环境开始，模型需要重新发送准备代码。PTC Plus 保留会话中的计算状态，让后续调用可以接着完成任务。
+安装完成后正常向模型描述任务即可，下面的 `run_code` 和 `edit_run_code` 示例说明模型如何使用这些能力。其他安装方式、Desktop、本地开发启动器、升级和故障排查见[安装指南](docs/installation.md)。
+
+## 功能概览
+
+默认 PTC 模式的每次调用都从新环境开始：上次的变量不再存在，改动依赖前面的结果时只能重发准备代码。PTC Plus 把 `run_code` 变成会话级的 TypeScript REPL，补上下面的落差。
 
 | 场景 | 默认 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 会话分开 |
-| 重启后继续 | 没有跨调用的计算状态可恢复 | 从会话记录恢复可验证的状态，无法恢复的部分明确提示 |
+| 接着上一次处理数据 | 每次从新环境开始，准备代码要重新发送 | 变量、函数、导入和中间结果留在会话里，下一次调用直接继续 |
+| 修订已有的名称 | 没有已建立的绑定可更新，只能重发整段代码 | 同名修订变量、函数、类和导入绑定，已有闭包读取更新后的值 |
+| 只改一小段代码 | 改动一行也要重新发送整段源码 | `edit_run_code` 只提交差异，再执行修改后的完整代码 |
+| 使用模块语法 | 函数体里不能直接写静态 `import` / `export` | 在 cell 中直接写，插件自动适配模块语法 |
+| 调用漏填摘要 | 缺少 `run_code.description` 时校验失败 | 自动补充显示摘要，其余参数合法的代码继续执行 |
+| 误发顶层工具调用 | PTC 模式下未声明的顶层调用被拒绝 | 当前工具定义能唯一确认目标且参数合法时，转为对应的 `run_code` |
+| 定位代码错误 | 只返回原生错误与堆栈 | 对应到 cell 源码位置；末尾缺少闭合符且修正可唯一验证时给出编辑建议 |
+| 访问当前项目 | 相对路径按宿主进程目录解析 | 按会话项目目录解析文件路径、会话模块导入和默认子进程目录 |
+| 查找工具和参数 | 只能翻已经提供给模型的工具说明 | 在代码中列出、搜索当前可用能力，按需查看接口说明 |
+| 传递 JSON 不易表达的数据 | JSON 无法完整表达 `undefined`、BigInt、循环引用等 | 在支持的值范围内保留特殊值和引用关系，供后续计算与恢复 |
+| 查看当前计算状态 | 执行结束后没有可继续使用的会话变量可查 | REPL 页签展示保留的名称、定义来源、复用次数和有界值预览 |
+| 跨会话使用常用函数 | 自己保存代码，并在后续调用中重新加载 | 全局绑定保存 TypeScript 源码，并向模型提供接口与使用提示 |
+| 编写和测试全局绑定 | 没有全局绑定的专用工作台 | 让模型生成待审阅草稿，或在工作台试运行未保存的源码 |
+| 重启后继续工作 | 没有跨调用的计算状态可供恢复 | 从会话记录恢复可验证的状态，无法恢复的部分明确提示 |
+
+以下各节介绍具体用法和边界；完整语言规则、配置字段与诊断见[运行时参考](docs/runtime-reference.md)。
+
+## 连续计算与语言扩展
+
+以下代码由模型通过 `run_code` 执行。每次调用的代码称为一个 **cell**。
+
+第一次，建立数据和计算函数：
+
+```ts
+const amounts: number[] = [12, 8, 5]
+function total() {
+  return amounts.reduce((sum, value) => sum + value, 0)
+}
+return total() // 25
+```
+
+下一次，直接修订数据并复用函数：
+
+```ts
+const amounts = amounts.filter(value => value >= 8)
+return total() // 20
+```
+
+无需重新定义 `total`，也无需为了避开重复声明而另起变量名。`total()` 读取的是更新后的 `amounts`。
+
+默认的 **有状态语义**（`bindingUpdates: 'stateful'`）为连续修订扩展了 JavaScript/TypeScript 的绑定规则：
+
+- 同一作用域内的变量、函数、类和导入绑定可以更新，包括用 `const` 声明的绑定；同一 cell 内也允许同名修订。
+- 已有闭包读取更新后的绑定；提前保存的函数值仍是原来的函数。
+- 不同块、函数和循环迭代的作用域仍然区分。
+- 声明初始化失败时，尚未成功建立的名称不会永久阻止后续声明；失败前已经发生的其他修改不会因此回滚。
+
+cell 支持 TypeScript、顶层 `await` / `return` 和静态 `import` / `export`。需要检测名称覆盖时，可在设置中关闭“允许重声明和覆盖”，使用 `protected` 策略。`tools` 等受保护的运行时名称仍不能覆盖。
+
+<details>
+<summary>静态导入与局部覆盖的时机</summary>
 
-全局绑定需在设置中开启；其余可选行为和恢复范围见下方[设置](#设置)与[范围](#范围)。
+静态导入在 **整个 cell 的正文执行前** 生效，正文中的赋值或普通声明随后可以覆盖它。要恢复跟随模块导出，可在后续 cell 中再次静态导入。同一 cell 中，即使把 import 写在普通声明后面，也不会在那个文本位置重新覆盖局部值；若要在某一步取回当前导出值，可以显式赋值：
 
-## 三个最直接的场景
+```ts
+join = (await import('node:path')).join
+```
+
+这会取得当时的函数值；静态导入则持续跟随模块来源。更多规则见[运行时参考](docs/runtime-reference.md#cell-semantics)。
+
+</details>
+
+`run_code`、编辑后的代码和全局绑定工作台采用相同的语言策略；工作台的临时状态与模型会话分开。显式使用 `eval`、`Function`、`node:vm` 或独立运行时仍受对应原生边界约束。详细的作用域、模块互操作与历史会话规则见[语言参考](docs/runtime-reference.md#cell-semantics)。
+
+## 代码编辑与调用容错
+
+### 小改动只发送差异
+
+模型可以调用 `edit_run_code` 修改当前轮模型运行中最近的可编辑 cell，无需重新发送整段源码。假设前面的第二个 cell 刚执行完，且仍在同一轮运行中，可以把筛选条件改为 `value >= 10`：
+
+```js
+edit_run_code({
+  edits: [{ old_string: 'value >= 8', new_string: 'value >= 10' }]
+})
+```
+
+修改后会**重新执行整个 cell**，以上例子返回 `12`。已发生的状态修改不会回滚；如果代码涉及写文件或外部服务，重跑仍需考虑重复效果。编辑既可用于修复失败的代码，也可用于微调已成功的计算。
 
-### 状态跨调用
+### 处理可以确定的调用问题
 
-模型第一次执行：
+| 情况 | PTC Plus 的处理 |
+| --- | --- |
+| `run_code` 漏填外层 `description` | 补充显示摘要，让其余参数合法的代码继续执行 |
+| 模型误发 PTC 直接工具列表之外的原生工具调用 | 当前工具定义能唯一确认目标且参数合法时，转为对应的 `run_code` |
+| 代码解析失败 | 标出源码位置；若错误在末尾，且追加一到两个闭合符只有一种通过验证的修正，给出绑定原调用的编辑建议 |
+
+前两项默认开启，可在设置中关闭。语法建议不会自动执行，也不代表插件能判断代码是否符合任务意图。
+
+## 项目文件与工具能力
+
+### 从会话项目目录开始
+
+模型可以直接使用 Node.js 读取文件、处理数据和运行程序。相对文件路径与会话内的模块导入按会话记录的项目目录解析；子进程未指定 `cwd` 时，也使用这个目录。显式指定的目录仍然生效。
+
+例如，在包含 `package.json` 的项目中，第一次调用读取依赖：
 
 ```ts
 import { readFile } from 'node:fs/promises'
@@ -82,83 +150,101 @@ const deps = Object.keys(manifest.dependencies ?? {})
 return deps.length
 ```
 
-下一次直接接着用：
+下一次直接整理已读取的数据：
 
 ```ts
 return deps.map(dep => dep + '@' + manifest.dependencies[dep])
 ```
 
-`deps` 和 `manifest` 仍在当前会话里，无需重发准备代码。
+这里没有重新读文件，结果来自会话中已有的 `manifest`。直接文件、网络等外部输入可以在当前环境继续使用，但不保证能跨重启恢复。
 
-### 修错不重发
+### 按需发现工具
 
-模型可以只提交替换内容：
+模型仍可通过 `tools.*` 使用 DSH 当前提供的原生工具。需要了解可用能力时，`capabilities.tree()` 列出目录，`find()` 搜索名称和描述，`inspect()` 查看选中接口的参数说明：
 
 ```ts
-edit_run_code({ edits: [{ old_string: 'deps.length', new_string: 'deps' }] })
+const matches = await capabilities.find('read')
+return capabilities.inspect({
+  symbols: matches.slice(0, 4).map(item => item.symbol),
+  budget: 4,
+})
 ```
 
-编辑会重新执行完整 cell。已经写文件或调用外部服务的代码，仍需确认可以安全重试。语法错误会指出位置；能够明确定位的末尾缺符号错误还会给出修正建议。
+搜索使用词法匹配，适合 `read`、`session` 这样的短关键词；没有匹配不代表工具一定不存在。发现工具不会增加权限，实际调用仍由 DSH 校验和调度。更多用法见[能力发现](docs/runtime-reference.md#capability-discovery)。
 
-![被拒的 run_code 与随后的 edit_run_code 修复调用](assets/ptc-plus-repair-zh.png)
+## 全局绑定：跨会话复用常用函数
 
-### 让 Agent 编写可复用 helper
+会话变量服务于当前任务；**全局绑定**把常用 TypeScript 函数保存下来，供多个会话加载。例如，保存名为 `textTools` 的绑定后，模型可以使用 `textTools.clean(text)`。
 
-在设置中开启“全局用户绑定”，然后输入：
+全局绑定和星光入口默认开启。你可以手动创建、导入 `.ts` 文件，也可以让模型帮忙编写和修改：
 
 ```text
-/binding new 创建 textTools，清理文本首尾空白，保留内部空格
+/binding new 创建 textTools，去掉文本首尾空白并保留内部空格
 /binding edit <id> 增加逐行清理功能
 ```
 
-Agent 可以在会话 REPL 中用内存样例逐步测试和修正，再交出草稿；编写时的测试不得修改外部文件或服务。草稿在输入框上方展开，你可以检查源码和模型提示词，选择“保存为停用”“保存并启用”或“丢弃草稿”。测试和提交本身不会保存全局绑定。
+`<id>` 是工作台中的条目标识，也可以从星光菜单选择要修改的绑定。
 
-草稿面板可折叠或关闭，输入框星光按钮上的角标可重新打开。保存或丢弃成功后自动关闭，历史请求保留当时的源码和结果。
+### 编写、审阅与启用
 
-会话开始前也可以悬停或点击星光按钮，查看并启停全局绑定；这些选择对所有会话生效，但该入口只在当前会话使用 `ptc` 或兼容 `code` preset 时注册。菜单同时提供编写新绑定、修改已有绑定、完整管理入口和 PTC Plus 设置快捷入口；设置快捷入口直接打开包含全部插件配置的应用内窗口，悬浮提示仍标明宿主原生设置页的路径。REPL 可复用绑定列表按后续 cell 源码中的静态引用显示每项复用次数和总复用次数，重定义或重声明不会清零。
+模型可先用内存样例测试，再提交草稿。草稿显示在输入框上方，由你检查源码、接口和给模型的提示词，并选择 **保存并启用**、**保存为停用** 或 **丢弃草稿**。提交草稿本身不会保存或启用绑定；关闭面板后，可从星光按钮的草稿角标重新打开。
 
-已启用绑定的接口会提供给新会话中的模型，也会在现有会话的下一次允许请求中更新。每个绑定可以另写使用提示词，或关闭接口展示；仅改提示词不会重置 helper 的运行状态。在会话中给某个名字赋值或重声明只覆盖该名字，同一条目的其他名字继续可用，会话内的覆盖也不会写回保存的条目。详细操作见[全局绑定使用指南](docs/user-bindings.md)。
+星光菜单可在首条消息发出前查看、启停条目，选择对所有会话生效。已启用条目的接口和使用提示会提供给新会话中的模型；中途修改后，在现有会话的下一次允许请求中更新。
 
-## 设置
+### 接口提示与独立试运行
 
-可以从输入框旁的星光菜单选择 **PTC Plus 设置**，直接打开完整设置窗口。宿主原生入口也保留：当前 DSH 在侧栏 **Plugins** 页面里找到本插件的条目并点 **Configure**，旧版 DSH 在 **设置 → 插件配置 → PTC Plus**。总开关控制插件，其余设置按用途分组：
+每个条目可以从源码生成公开接口，并附加用途、输入约束或使用示例。仅修改提示词不会重置已加载函数的运行状态。会话中的同名赋值或重声明只覆盖对应名称，不会改写保存的全局条目。
 
-- **调用容错**：允许缺少摘要的 `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 页签和绑定编写快捷入口。
-- **资源限制**：调整执行时间、内存和输出上限。
+工作台支持运行尚未保存的源码，并在连续执行间保留临时变量。它与模型会话的计算状态分开，适合手动检查函数；文件和网络操作仍会产生真实效果。没有当前 PTC 会话也可管理条目。源码格式、接口生成、保存位置和完整流程见[全局绑定指南](docs/user-bindings.md)。
 
-全局绑定与 Cordis 工具默认关闭。设置通常即时生效；活动 worker 存在时不能更改其内存上限。字段、默认值和限制见[配置参考](docs/runtime-reference.md#configuration)。
+## 界面与设置
 
-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 页签**可搜索当前保留的名称，查看定义来源、复用次数和有界值预览，也可打开全局绑定工作台。预览有类型和大小限制，未采集、不完整或不可读取时会明确标注，不会为展示调用用户 getter。宽屏顶部的绿色 **PTC Plus** 标志提供快捷绑定清单，窄屏可使用 REPL 页签。
 
-间接 `eval` 和四种 `Function` 构造器使用所属 realm 的 root，作为原生回调传递时也一样，例如 `const value=41` 后的 `["typeof value"].map(eval)` 返回 `["number"]`。函数源码观察保留原始 JavaScript 源码及其真实依赖，自包含函数可用 `Function` 重新编译；函数值本身、用户改写和另外创建的 realm 保持各自语义。
+![REPL 页签中的会话状态与全局绑定工作台](assets/ptc-plus-repl-workspace-zh.png)
 
-切换计算模式时，旧闭包仍保留原有执行环境和已保存的函数身份，包括异步继续执行中的直接 `eval` 与 `Function.prototype.toString`。各代源码取得稳定的回调接口，全局和原型属性保持原值；兼容模式通过原生 REPL 环境复用已有逻辑绑定，原有原生声明仍优先，其模块导入也通过 PTC 管理的 namespace 读取。
+输入框旁的星光菜单将绑定编写、条目管理和 **PTC Plus 设置** 分组提供。设置弹窗与侧边栏插件配置页使用同一套配置：
+
+| 分组 | 可以调整的内容 |
+| --- | --- |
+| 插件开关 | 启用或停用 PTC Plus |
+| 调用容错 | 缺少摘要的调用、可准确识别的顶层工具误调用 |
+| REPL 语法 | 允许同名修订，或选择名称保护策略 |
+| 状态与恢复 | 重启恢复、按需提示与提示频率 |
+| 工具扩展 | 全局绑定及其管理入口、官方 Cordis 工具集成 |
+| 界面显示 | 增强工具卡片、REPL 页签与星光快捷入口 |
+| 资源限制 | 执行时间、内存和输出上限 |
+
+面向日常计算的功能默认开启。**Cordis 开发工具默认关闭**，适用于检查或开发 DSH 插件，按需开启即可；详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。已有配置中显式关闭的选项会保持关闭，条目是否启用也由各自的保存状态决定。
+
+设置通常即时生效；活动 worker 存在时不能修改其内存上限。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
 
 ![PTC Plus 设置卡片](assets/ptc-plus-settings-zh.png)
 
-在 **REPL** 页签查看会话绑定、搜索名称和检查定义，也可以管理全局绑定。全局绑定工作台中的代码控制台支持试运行未保存的源码，拥有独立的临时状态；执行的文件或网络操作仍会产生真实效果。
+## 值传递与状态恢复
+
+### 保留超出普通 JSON 的值
+
+在支持的值范围内，工具参数、结果和恢复记录可以保留 `undefined`、BigInt、`NaN`、无穷大、稀疏数组、循环引用和共享引用关系。普通 JSON 结果仍以结构化值返回；特殊值会以可读文本展示给模型，其程序内值与展示文本分别处理。
 
-![REPL 工作区：会话绑定检查与全局绑定管理](assets/ptc-plus-repl-workspace-zh.png)
+这不等于任意 JavaScript 对象都可传递或持久化：函数、Promise、类实例、Date、Map、Set 等不属于值传递的支持域。在 REPL 中保留函数供后续调用，与把函数作为工具结果返回，是不同的能力。需要继续计算时应复用会话变量；完整支持域见[值传递说明](docs/value-wire.md)。
 
-宽屏下，会话头部的绿色 **PTC Plus** 标识提供快捷绑定清单；窄屏可从 **REPL** 页签查看：
+### 恢复有依据的计算状态
 
-![REPL 可复用绑定](assets/ptc-plus-bindings-zh.png)
+会话级状态不等于永久内存。重启、执行环境重置或上下文压缩后，只保留能从会话记录验证、且其来源仍在模型上下文中的计算状态。直接读取外部文件或网络、历史记录损坏、来源被压缩等情况，都可能缩小可保留的范围。
 
-## 范围
+无法证明的状态会被丢弃并给出提示，必要时从空环境继续当前计算。恢复不会重新派发已记录的原生工具调用，也不会撤销历史外部效果。恢复依据和限制见[运行时参考](docs/runtime-reference.md)。
 
-DSH 继续负责工具权限、审批、取消和沙箱策略。会话求值运行在插件自有的 helper 进程内；卡住或无响应的 helper 会被回收，DSH 宿主进程不执行 in-host worker 强杀。PTC Plus 不保证所有状态都能跨重启恢复；外部输入、无法验证的历史或上下文压缩都可能缩小恢复范围。恢复不会重做或撤销历史外部操作。
+## 使用边界
 
-值预览有大小和类型限制，无法可靠读取的对象会显示“不可读取”。绑定的启用配置也不等于初始化一定成功，具体失败会在执行结果中说明。更多行为见[运行时参考](docs/runtime-reference.md)。
+- **执行权限**：主要面向 `danger-full-access`。代码可直接访问 Node.js 与操作系统；插件不额外提供安全沙箱。DSH 继续负责原生工具权限、审批、取消和沙箱策略。
+- **失败与重跑**：代码执行失败不代表此前语句没有生效。进程隔离、编辑和恢复都不保证外部操作可以安全重复；超时或输出超限等情况也可能释放计算环境。
+- **错误与开销**：语言适配和调用容错不保证所有代码成功。实际调用次数与 token 用量取决于任务和模型；已有对照观察及限制见[评测说明](docs/evaluation.md#recorded-paired-observation)。
 
-模型调用和 token 用量取决于任务与模型；已有配对观测及其限制见[评测说明](docs/evaluation.md#recorded-paired-observation)。
+PTC Plus 是社区插件，与 DeepSeek 或 DSH 无隶属或背书关系。
 
-## 文档
+## 进一步阅读
 
-[全局绑定使用指南](docs/user-bindings.md) · [安装与升级](docs/installation.md) · [运行时参考](docs/runtime-reference.md) · [开发与架构](docs/architecture.md) · [验证与测试并发](docs/verification.md) · [全部文档](docs/README.md)
+[安装与升级](docs/installation.md) · [全局绑定](docs/user-bindings.md) · [运行时参考](docs/runtime-reference.md) · [架构与开发](docs/architecture.md) · [验证指南](docs/verification.md) · [全部文档](docs/README.md)
 
-使用 [MIT License](LICENSE)。
+[MIT License](LICENSE)

package/assets/ptc-plus-icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="16" fill="#087f5b"/>
+  <path d="m23 20-12 12 12 12m18-24 12 12-12 12" fill="none" stroke="#fff" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M32 25v14m-7-7h14" fill="none" stroke="#b7f7d7" stroke-width="4" stroke-linecap="round"/>
+</svg>