dsh-ptc-plus 0.4.2 → 0.4.8

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,136 @@
   <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 模式**。连续计算、调用容错和全局绑定默认开启；已有配置中显式关闭的选项会保持关闭。
+
+在默认界面设置下，会话中会出现 **REPL** 页签；宽屏顶部还会显示绿色 **PTC Plus** 标志。输入框旁的星光按钮可打开全局绑定菜单和 **PTC Plus 设置**。也可从侧边栏 **插件 → 已安装 → dsh-ptc-plus → 配置** 检查插件总开关和全部设置。
+
+安装完成后正常向模型描述任务即可，下面的 `run_code` 和 `edit_run_code` 示例说明模型如何使用这些能力。其他安装方式、Desktop、本地开发启动器、升级和故障排查见[安装指南](docs/installation.md)。
+
+Windows 源码测试：双击 `scripts\run-upstream-dsh.cmd`，拉取官方 DSH 默认分支并复用隔离的构建缓存，加载当前插件工作区。首次运行需要安装依赖和构建；详见[上游源码测试](docs/installation.md#upstream-source-development-launcher-windows)。
 
-## 默认 PTC 模式的问题
+## 功能概览
 
-默认 PTC 模式每次执行都从新环境开始，模型需要重新发送准备代码。PTC Plus 保留会话中的计算状态，让后续调用可以接着完成任务。
+默认 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` 时校验失败 | 自动补充显示摘要，其余参数合法的代码继续执行 |
+| 提供方拒绝畸形工具 JSON | 整个 turn 以 provider 错误终止 | 缓冲的工具调用尾部仅含工具块和至多一个用量事件时可修复或保留参数；其他缓冲尾部转为 schema 拒绝结果，模型继续下一步 |
+| 误发顶层工具调用 | 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` |
+| 参数校验报告缺少 `description` | 区分外层与嵌套工具参数并给出修正提示；提示以完整消息保存，保持会话历史可加载 |
+| 代码解析失败 | 标出源码位置；若错误在末尾，且追加一到两个闭合符只有一种通过验证的修正，给出绑定原调用的编辑建议 |
+
+前两项默认开启，可在设置中关闭。语法建议不会自动执行，也不代表插件能判断代码是否符合任务意图。
+
+## 项目文件与工具能力
+
+### 从会话项目目录开始
+
+模型可以直接使用 Node.js 读取文件、处理数据和运行程序。相对文件路径与会话内的模块导入按会话记录的项目目录解析；子进程未指定 `cwd` 时，也使用这个目录。显式指定的目录仍然生效。
+
+例如，在包含 `package.json` 的项目中，第一次调用读取依赖：
 
 ```ts
 import { readFile } from 'node:fs/promises'
@@ -82,79 +154,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 可复用绑定列表显示每项复用次数和总复用次数，重定义或重声明不会清零。
+### 接口提示与独立试运行
 
-已启用绑定的接口会提供给新会话中的模型，也会在现有会话的下一次允许请求中更新。接口从源码保留公开签名引用的标准全局类型、本地类型、可表示的类继承链和类实例字段；抽象类仍不可直接构造，无法生成自足接口的导入类型会在保存前明确报错。每个绑定可以另写使用提示词，或关闭接口展示；仅改提示词不会重置 helper 的运行状态。在会话中给某个名字赋值或重声明只覆盖该名字，同一条目的其他名字继续可用，会话内的覆盖也不会写回保存的条目。详细操作见[全局绑定使用指南](docs/user-bindings.md)。
+每个条目可以从源码生成公开接口，并附加用途、输入约束或使用示例。仅修改提示词不会重置已加载函数的运行状态。会话中的同名赋值或重声明只覆盖对应名称，不会改写保存的全局条目。
 
-## 设置
+工作台支持运行尚未保存的源码，并在连续执行间保留临时变量。它与模型会话的计算状态分开，适合手动检查函数；文件和网络操作仍会产生真实效果。没有当前 PTC 会话也可管理条目。源码格式、接口生成、保存位置和完整流程见[全局绑定指南](docs/user-bindings.md)。
 
-可以从输入框旁的星光菜单选择 **PTC Plus 设置**，直接打开完整设置窗口。宿主原生入口也保留；根据 DSH 界面，可在侧栏 **Plugins** 页面找到本插件并点 **Configure**，或打开 **设置 → 插件配置 → PTC Plus**。总开关控制插件，其余设置按用途分组：
+## 界面与设置
 
-- **调用容错**：允许缺少摘要的 `run_code`，修复可以准确识别的顶层工具误调用。
-- **REPL 语法**：`bindingUpdates` 默认是 `stateful`，允许跨 cell 更新变量、函数、类和 import alias，也允许同一 cell 内同一逻辑 scope 的重复声明更新同一身份；`protected` 可选择名称保护。`tools` 与注入的错误类不能重声明或写入：声明冲突报 `PTC-N001`，赋值失败时会指出对应名称。已有配置若仍含五个细分开关，设置页会显示待迁移状态，可直接选择任一种统一策略。模块语法默认可用。
-- **模块互操作**：PTC 管理的 namespace 支持实时读取和局部覆盖，传给外部函数后仍保留这些语义。外部代码自行原生导入编译模块不承诺同一 namespace 或可写导出语义，详见[运行时说明](docs/runtime-reference.md#cell-semantics)。
-- **状态与恢复**：控制重启恢复和按需错误提示。
-- **工具扩展**：开启全局绑定，或供高级用户使用的官方 Cordis 工具。
-- **界面显示**：控制增强工具卡片、REPL 页签和绑定编写快捷入口。
-- **资源限制**：调整执行时间、内存和输出上限。
+**REPL 页签**可搜索当前保留的名称，查看定义来源、复用次数和有界值预览，也可打开全局绑定工作台。预览有类型和大小限制，未采集、不完整或不可读取时会明确标注，不会为展示调用用户 getter。宽屏顶部的绿色 **PTC Plus** 标志提供快捷绑定清单，窄屏可使用 REPL 页签。
 
-全局绑定与 Cordis 工具默认关闭。设置通常即时生效；活动 worker 存在时不能更改其内存上限。字段、默认值和限制见[配置参考](docs/runtime-reference.md#configuration)。
+![REPL 页签中的会话状态与全局绑定工作台](assets/ptc-plus-repl-workspace-zh.png)
 
-`run_code`、`edit_run_code`、绑定试运行和用户绑定执行遵循同一套有状态语义。每个计算环境中的 cell、PTC 管理模块、`require` 和绑定模块共享该 worker 的 Node realm，因此 `Error` 子类判断与 `globalThis` 写入保持 Node 语义。显式使用 `eval`、`Function`、`node:vm` 或独立运行时仍遵循对应的原生边界；切换绑定更新策略不会改写已有闭包和函数的执行环境。完整的作用域、源码观察、模块互操作和已记录会话兼容规则见[运行时参考](docs/runtime-reference.md#cell-semantics)。
+输入框旁的星光菜单将绑定编写、条目管理和 **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 继续负责工具权限、审批、取消和沙箱策略。PTC Plus 在可回收的 helper 进程中执行会话代码，因此卡住或无响应的计算可以在不结束 DSH 的情况下终止；这一进程边界不是安全沙箱。Electron Desktop 兼容处理不会改变求值代码及其子进程看到的环境。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>