dsh-ptc-plus 0.4.10 → 0.5.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/dsh-ptc-plus-banner-zh.webp" width="100%" alt="PTC Plus：不用从头来，改一改，接着算！">
+  <img src="assets/dsh-ptc-plus-banner-v2-zh.webp" width="100%" alt="PTC Plus：不用从头来，改一改，接着算！">
 </p>
 
 <p align="center">
@@ -25,29 +25,23 @@ PTC Plus 为 DSH 的 **PTC 模式**提供有状态的 TypeScript 计算环境。
 - **少些调用错误**：适配常用模块语法，处理可准确识别的调用遗漏，并为可验证的语法错误提供修正建议。
 - **复用常用能力**：把常用函数保存为全局绑定，向模型提供接口与使用提示，在多个会话中使用。
 
-[快速开始](#快速开始) · [功能概览](#功能概览) · [连续计算](#连续计算与语言扩展) · [代码编辑与容错](#代码编辑与调用容错) · [全局绑定](#全局绑定跨会话复用常用函数) · [界面与设置](#界面与设置) · [状态与恢复](#值传递与状态恢复)
+[快速开始](#快速开始) · [功能概览](#功能概览) · [连续计算](#连续计算与语言扩展) · [代码编辑与容错](#代码编辑与调用容错) · [全局绑定](#全局绑定跨会话复用常用函数) · [界面与设置](#界面与设置) · [状态与恢复](#值传递与状态恢复) · [开发](#开发)
 
 ## 快速开始
 
-需要 Node.js `^22.19.0 || >=24.0.0` 和最新可用的官方 DSH。将插件安装到实际使用的 profile：
+需要 Node.js `^22.19.0 || >=24.0.0` 和最新可用的官方 DSH：
 
 ```sh
 dsh plugin --profile <profile> add dsh-ptc-plus
 ```
 
-将 `<profile>` 替换为实际 profile 名称。安装后重启 DSH，在会话中选择 **PTC 模式**。连续计算、调用容错和全局绑定默认开启；已有配置中显式关闭的选项会保持关闭。
+把 `<profile>` 换成实际 profile 名称，重启 DSH，在会话中选择 **PTC 模式**。连续计算、调用容错和全局绑定默认开启；升级用 `dsh plugin --profile <profile> add dsh-ptc-plus@latest` 再重启宿主，其他安装方式、Desktop、本地开发启动器和故障排查见[安装指南](docs/installation.md)。
 
-会话历史通过 DSH 的公开 reader 读取，提示事实由 Host 增量投影维护；读取面缺失或旧格式事件数组损坏时会明确报错，不把不可用历史当作成功恢复的空会话。
-
-在默认界面设置下，会话中会出现 **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)。
+界面默认显示会话里的 **REPL** 页签，宽屏顶部还有 **PTC Plus** 标志。输入框旁的星光按钮打开全局绑定菜单、会话能力工作台和 **PTC Plus 设置**，侧边栏的 **插件 → 已安装 → dsh-ptc-plus → 配置** 是同一套设置。
 
 ## 功能概览
 
-默认 PTC 模式的每次调用都从新环境开始：上次的变量不再存在，改动依赖前面的结果时只能重发准备代码。PTC Plus 把 `run_code` 变成会话级的 TypeScript REPL，补上下面的落差。
+默认 PTC 模式的每次调用都从新环境开始：上次的变量已经不在了，想改动依赖前面的结果就只能重发准备代码。PTC Plus 把 `run_code` 变成会话级的 TypeScript REPL，补上这些差距。
 
 | 场景 | 默认 PTC 模式 | 使用 PTC Plus |
 | --- | --- | --- |
@@ -56,24 +50,20 @@ Windows 源码测试：双击 `scripts\run-upstream-dsh.cmd`，拉取官方 DSH
 | 只改一小段代码 | 改动一行也要重新发送整段源码 | `edit_run_code` 只提交差异，再执行修改后的完整代码 |
 | 使用模块语法 | 函数体里不能直接写静态 `import` / `export` | 在 cell 中直接写，插件自动适配模块语法 |
 | 调用漏填摘要 | 缺少 `run_code.description` 时校验失败 | 自动补充显示摘要，其余参数合法的代码继续执行 |
-| 提供方拒绝畸形工具 JSON | 整个 turn 以 provider 错误终止 | 缓冲的工具调用尾部仅含工具块和至多一个用量事件时可修复或保留参数；其他缓冲尾部转为 schema 拒绝结果，模型继续下一步 |
+| 提供方拒绝畸形工具 JSON | 整个 turn 以 provider 错误终止 | 可修复的调用尾部继续执行，其余转为 schema 拒绝结果，模型继续下一步 |
 | 误发顶层工具调用 | PTC 模式下未声明的顶层调用被拒绝 | 当前工具定义能唯一确认目标且参数合法时，转为对应的 `run_code` |
 | 定位代码错误 | 只返回原生错误与堆栈 | 对应到 cell 源码位置；末尾缺少闭合符且修正可唯一验证时给出编辑建议 |
-| 访问当前项目 | 相对路径按宿主进程目录解析 | 按会话项目目录解析文件路径、会话模块导入和默认子进程目录 |
-| 查找工具和参数 | 只能翻已经提供给模型的工具说明 | 在代码中列出、搜索当前可用能力，按需查看接口说明 |
+| 访问当前目录 | 按宿主为当前调用解析的目录执行 | 相对文件操作和默认子进程按执行时的会话当前目录解析，格内 `tools.working_directory({ cd })` 立即作用于本格剩余语句；模块导入保持进入目录，旧模块和导入闭包保留原来源 |
+| 查找工具和参数 | 只能翻已经提供给模型的工具说明 | 用 `capabilities.search` 一次取得匹配接口，按字节限制响应；也可列目录或单项检查 |
 | 传递 JSON 不易表达的数据 | JSON 无法完整表达 `undefined`、BigInt、循环引用等 | 在支持的值范围内保留特殊值和引用关系，供后续计算与恢复 |
-| 查看当前计算状态 | 执行结束后没有可继续使用的会话变量可查 | REPL 页签展示保留的名称、定义来源、复用次数和有界值预览 |
+| 查看当前计算状态 | 执行结束后没有可继续使用的会话变量可查 | REPL 页签展示保留的名称、定义来源、复用次数和值预览 |
 | 跨会话使用常用函数 | 自己保存代码，并在后续调用中重新加载 | 全局绑定保存 TypeScript 源码，并向模型提供接口与使用提示 |
 | 编写和测试全局绑定 | 没有全局绑定的专用工作台 | 让模型生成待审阅草稿，或在工作台试运行未保存的源码 |
 | 重启后继续工作 | 没有跨调用的计算状态可供恢复 | 从会话记录恢复可验证的状态，无法恢复的部分明确提示 |
 
-以下各节介绍具体用法和边界；完整语言规则、配置字段与诊断见[运行时参考](docs/runtime-reference.md)。
-
 ## 连续计算与语言扩展
 
-以下代码由模型通过 `run_code` 执行。每次调用的代码称为一个 **cell**。
-
-第一次，建立数据和计算函数：
+以下代码由模型通过 `run_code` 执行，每次调用的代码称为一个 **cell**。
 
 ```ts
 const amounts: number[] = [12, 8, 5]
@@ -83,56 +73,35 @@ function total() {
 return total() // 25
 ```
 
-下一次，直接修订数据并复用函数：
+下一次直接修订数据，`total` 不用重新定义：
 
 ```ts
 const amounts = amounts.filter(value => value >= 8)
 return total() // 20
 ```
 
-无需重新定义 `total`，也无需为了避开重复声明而另起变量名。`total()` 读取的是更新后的 `amounts`。
-
-默认的 **有状态语义**（`bindingUpdates: 'stateful'`）为连续修订扩展了 JavaScript/TypeScript 的绑定规则：
+默认的 **有状态语义**（`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
-```
+- 同一作用域里的变量、函数、类和导入绑定都能更新，包括 `const` 声明的；同一个 cell 内也允许同名修订。
+- 已有闭包读到更新后的绑定，提前保存的函数值仍是原来的函数；不同块、函数和循环迭代的作用域照常区分。
+- 声明初始化失败不会永久占住这个名称，失败前已经生效的修改也不会回滚。
 
-这会取得当时的函数值；静态导入则持续跟随模块来源。更多规则见[运行时参考](docs/runtime-reference.md#cell-semantics)。
+cell 支持 TypeScript（含运行时 `enum` 和 `namespace`）、顶层 `await` / `return` 和静态 `import` / `export`；静态导入在整个 cell 正文执行前生效，正文里的赋值随后可以覆盖它。想检测名称覆盖，可以在设置里关掉“允许重声明和覆盖”改用 `protected` 策略；`tools` 这类受保护的运行时名称任何时候都不能覆盖。
 
-</details>
-
-`run_code`、编辑后的代码和全局绑定工作台采用相同的语言策略；工作台的临时状态与模型会话分开。显式使用 `eval`、`Function`、`node:vm` 或独立运行时仍受对应原生边界约束。详细的作用域、模块互操作与历史会话规则见[语言参考](docs/runtime-reference.md#cell-semantics)。
+`run_code`、编辑后的代码和全局绑定工作台采用同一套语言策略；显式 `eval`、`Function`、`node:vm` 或独立运行时仍受各自的原生边界约束。作用域、模块互操作和历史会话规则见[语言参考](docs/runtime-reference.md#cell-semantics)，完整的语言规则、配置字段与诊断见[运行时参考](docs/runtime-reference.md)。
 
 ## 代码编辑与调用容错
 
-### 小改动只发送差异
-
-模型可以调用 `edit_run_code` 修改当前轮模型运行中最近的可编辑 cell，无需重新发送整段源码。假设前面的第二个 cell 刚执行完，且仍在同一轮运行中，可以把筛选条件改为 `value >= 10`：
+模型可以在新的 `run_code` cell 内调用 `tools.edit_run_code`，修改当前轮最近的可编辑 cell，不必重发整段源码：
 
 ```js
-edit_run_code({
+const receipt = await tools.edit_run_code({
   edits: [{ old_string: 'value >= 8', new_string: 'value >= 10' }]
 })
+return receipt
 ```
 
-修改后会**重新执行整个 cell**，以上例子返回 `12`。已发生的状态修改不会回滚；如果代码涉及写文件或外部服务，重跑仍需考虑重复效果。编辑既可用于修复失败的代码，也可用于微调已成功的计算。
-
-历史结果被压缩为新的显示条目，不算再次执行，也不会把旧 cell 变成新的编辑目标；较新的失败 cell 仍可继续修正。
-
-### 处理可以确定的调用问题
+收据里 `accepted: true, scheduled: true` 表示编辑已经安排：外层 cell 结束后才重新执行整个目标 cell，下一次 cell 读到的是修订后的值（上例是 `12`）。同一次调用里再读仍是旧状态，已经发生的状态修改不会回滚，写过文件或调用过外部服务的代码重跑时要考虑重复效果。正则编辑的每项必须给出 `pattern`、`flags`、`replacement`、`expected_matches`，不需要标志时显式传 `""`。
 
 | 情况 | PTC Plus 的处理 |
 | --- | --- |
@@ -141,122 +110,83 @@ edit_run_code({
 | 参数校验报告缺少 `description` | 区分外层与嵌套工具参数并给出修正提示；提示以完整消息保存，保持会话历史可加载 |
 | 代码解析失败 | 标出源码位置；若错误在末尾，且追加一到两个闭合符只有一种通过验证的修正，给出绑定原调用的编辑建议 |
 
-前两项默认开启，可在设置中关闭。语法建议不会自动执行，也不代表插件能判断代码是否符合任务意图。
+前两项默认开启，可以在设置里关掉。语法建议不会自动执行，也不代表代码符合任务意图。volatile 状态存不成 durable 检查点，但保存被拒绝后当前变量还能接着用；恢复不撤销外部效果，也不改全局绑定配置。
 
 ## 项目文件与工具能力
 
-### 从会话项目目录开始
-
-模型可以直接使用 Node.js 读取文件、处理数据和运行程序。相对文件路径与会话内的模块导入按会话记录的项目目录解析；子进程未指定 `cwd` 时，也使用这个目录。显式指定的目录仍然生效。
+模型可以直接用 Node.js 读文件、处理数据、跑程序。相对路径和没指定 `cwd` 的子进程按执行时的会话当前目录解析：格内调用 `tools.working_directory({ cd })` 后，本格剩余操作就用新目录，与宿主工具同一基准。模块导入和 `import.meta` 仍按进入目录，已加载模块、旧导入闭包和已捕获的 `require` 保留原来源；`process.chdir` 在 cell 内不可用。文件、网络等外部输入在当前环境里可以继续用，但不保证跨重启还能恢复。
 
-例如，在包含 `package.json` 的项目中，第一次调用读取依赖：
+`capabilities.search()` 一次查找并返回完整接口，预算按字节计算，过长条目保持完整并给出单项读取指针；原有的 `tree()`、`find()`、`inspect()` 仍可用。
 
 ```ts
-import { readFile } from 'node:fs/promises'
-const manifest = JSON.parse(await readFile('package.json', 'utf8'))
-const deps = Object.keys(manifest.dependencies ?? {})
-return deps.length
+return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 ```
 
-下一次直接整理已读取的数据：
-
-```ts
-return deps.map(dep => dep + '@' + manifest.dependencies[dep])
-```
-
-这里没有重新读文件，结果来自会话中已有的 `manifest`。直接文件、网络等外部输入可以在当前环境继续使用，但不保证能跨重启恢复。
-
-### 按需发现工具
-
-模型仍可通过 `tools.*` 使用 DSH 当前提供的原生工具。需要了解可用能力时，`capabilities.tree()` 列出目录，`find()` 搜索名称和描述，`inspect()` 查看选中接口的参数说明：
-
-```ts
-const matches = await capabilities.find('read')
-return capabilities.inspect({
-  symbols: matches.slice(0, 4).map(item => item.symbol),
-  budget: 4,
-})
-```
-
-搜索使用词法匹配，适合 `read`、`session` 这样的短关键词；没有匹配不代表工具一定不存在。发现工具不会增加权限，实际调用仍由 DSH 校验和调度。更多用法见[能力发现](docs/runtime-reference.md#capability-discovery)。
+搜索按中英文词法匹配，没匹配到不代表工具不存在。发现工具不会增加权限，实际调用仍由 DSH 校验和调度，更多用法见[能力发现](docs/runtime-reference.md#capability-discovery)。
 
 ## 全局绑定：跨会话复用常用函数
 
-会话变量服务于当前任务；**全局绑定**把常用 TypeScript 函数保存下来，供多个会话加载。例如，保存名为 `textTools` 的绑定后，模型可以使用 `textTools.clean(text)`。
-
-全局绑定和星光入口默认开启。你可以手动创建、导入 `.ts` 文件，也可以让模型帮忙编写和修改：
+会话变量服务于当前任务，**全局绑定**把常用 TypeScript 函数保存下来供多个会话加载：保存 `textTools` 之后，模型就能调用 `textTools.clean(text)`。你可以手动创建、导入 `.ts` 文件，也可以让模型帮忙：
 
 ```text
 /binding new 创建 textTools，去掉文本首尾空白并保留内部空格
 /binding edit <id> 增加逐行清理功能
 ```
 
-`<id>` 是工作台中的条目标识，也可以从星光菜单选择要修改的绑定。
-
-### 编写、审阅与启用
-
-模型可先用内存样例测试，再提交草稿。草稿悬浮在输入框上方，展开或折叠不挤动对话；从星光菜单或原请求打开草稿时，直接进入大窗口。点击 **放大查看绑定草稿** 可在大窗口内审阅完整源码，正文独立滚动，底部保留保存与丢弃按钮；标题栏的放大、缩小与关闭操作分开显示，点击 **缩小显示绑定草稿** 返回预览；由你检查源码、接口和给模型的提示词，并选择 **保存并启用**、**保存为停用** 或 **丢弃草稿**。提交草稿本身不会保存或启用绑定；关闭面板后，可从星光按钮的草稿角标重新打开。
-
-星光菜单可在首条消息发出前查看、启停条目，选择对所有会话生效。已启用条目优先展示，停用组显示数量并默认折叠；只有绑定列表滚动，底部编写、修改、管理和设置按钮始终可见。已启用条目的接口和使用提示会提供给新会话中的模型；中途修改后，在现有会话的下一次允许请求中更新。
-
-### 接口提示与独立试运行
-
-每个条目可以从源码生成公开接口，并附加用途、输入约束或使用示例。仅修改提示词不会重置已加载函数的运行状态。会话中的同名赋值或重声明只覆盖对应名称，不会改写保存的全局条目。
+模型提交的草稿浮在输入框上方，你在大窗口里看完整源码、接口和给模型的提示词，再选 **保存并启用**、**保存为停用** 或 **丢弃草稿**；提交草稿本身不会保存或启用绑定。已启用条目的接口和使用提示会提供给新会话中的模型，中途修改在现有会话的下一次允许请求中生效。
 
-工作台支持运行尚未保存的源码，并在连续执行间保留临时变量。它与模型会话的计算状态分开，适合手动检查函数；文件和网络操作仍会产生真实效果。没有当前 PTC 会话也可管理条目。源码格式、接口生成、保存位置和完整流程见[全局绑定指南](docs/user-bindings.md)。
+工作台可以运行尚未保存的源码，并在连续执行之间保留临时变量；它的计算状态和模型会话分开，文件和网络操作仍会产生真实效果，没有 PTC 会话时也能管理条目。源码格式、接口生成、保存位置和完整流程见[全局绑定指南](docs/user-bindings.md)。
 
 ## 界面与设置
 
-**REPL 页签**可搜索当前保留的名称，查看定义来源、复用次数和有界值预览，也可打开全局绑定工作台。预览有类型和大小限制，未采集、不完整或不可读取时会明确标注，不会为展示调用用户 getter。宽屏顶部的绿色 **PTC Plus** 标志提供快捷绑定清单，窄屏可使用 REPL 页签。
-
-工作台控件提供可见的键盘焦点和禁用反馈，REPL 名称在明暗主题下保持可读；关键控件的浏览器回归检查及覆盖边界见[视觉契约](docs/client-visual-contract.md)。
+**REPL 页签**列出会话里保留的名称、定义来源、复用次数和值预览，也能打开全局绑定工作台。执行卡片收起后，鼠标停留 400ms 或键盘聚焦会弹出一份源码、结果和功能标记的摘录，点击或按 Enter／空格展开完整内容并复制代码；不需要时可以在设置的“界面显示”里关掉“悬停预览执行内容”。
 
 ![REPL 页签中的会话状态与全局绑定工作台](assets/ptc-plus-repl-workspace-zh.png)
 
-输入框旁的星光菜单将绑定编写、条目管理和 **PTC Plus 设置** 分组提供。设置弹窗与侧边栏插件配置页使用同一套配置：
+设置窗口和侧边栏的插件配置页是同一套配置，分组如下：
 
-| 分组 | 可以调整的内容 |
-| --- | --- |
-| 插件开关 | 启用或停用 PTC Plus |
-| 调用容错 | 缺少摘要的调用、可准确识别的顶层工具误调用 |
-| REPL 语法 | 允许同名修订，或选择名称保护策略 |
-| 状态与恢复 | 重启恢复、按需提示与提示频率 |
-| 工具扩展 | 全局绑定及其管理入口、官方 Cordis 工具集成 |
-| 界面显示 | 增强工具卡片、REPL 页签与星光快捷入口 |
-| 资源限制 | 执行时间、内存和输出上限 |
+| 功能模块 | 分组 | 可以调整的内容 |
+| --- | --- | --- |
+| 插件开关 | PTC Plus 标题总开关 | 启用或停用 PTC Plus |
+| 核心工作区 | REPL 语法 | 允许同名修订或选择名称保护 |
+| 核心工作区 | 状态与恢复 | 重启恢复、上下文提示及其频率 |
+| 扩展与容错 | 工具扩展 | 全局绑定及其管理入口、官方 Cordis 工具集成 |
+| 扩展与容错 | 调用容错 | 缺失调用摘要、可识别的错位原生工具调用 |
+| 界面与资源 | 界面显示 | 增强工具卡片、REPL 页签和星光快捷入口 |
+| 界面与资源 | 资源限制 | 执行时间、内存和输出预算 |
+| 实验性 | 能力与上下文 | 实验性能力管理（默认关闭）、独立统计、常用集、单项选择和展示预算 |
 
-面向日常计算的功能默认开启。**Cordis 开发工具默认关闭**，适用于检查或开发 DSH 插件，按需开启即可；详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。已有配置中显式关闭的选项会保持关闭，条目是否启用也由各自的保存状态决定。
+面向日常计算的功能默认开启，**Cordis 开发工具默认关闭**，要检查或开发 DSH 插件时再打开，详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。
 
-设置通常即时生效；活动 worker 存在或已提交的 cell 正在准备执行时不能修改其内存上限。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
+“能力与上下文”是实验性设置，默认关闭。打开后可以按类别、来源和单项选择 Skills、Tools 和 MCP 能力的启停与说明方式，初始提示、提示恢复、输出节选和使用统计也在这里；标题旁的总开关一次暂停整组并保留原有选择，改动对新会话或明确刷新后的会话生效。星光菜单里还有一个会话能力工作台，用来按类别、来源和状态查看、调整当前会话的能力，改动先放进草稿，可以只写进本会话，也可以保存成全局默认。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
 
-宿主执行 provider 必须使用 TypeScript。热重载改为其他语言时，PTC Plus 撤出当前接管并报告诊断；恢复 TypeScript 后重新启用，插件开关保持原选择。
+宿主执行 provider 必须使用 TypeScript；热重载换成别的语言时插件会撤出并报出诊断，换回来就重新启用。
 
-![PTC Plus 设置卡片](assets/ptc-plus-settings-zh.png)
+![PTC Plus 设置窗口](assets/ptc-plus-settings-zh.png)
 
 ## 值传递与状态恢复
 
-### 保留超出普通 JSON 的值
-
-在支持的值范围内，工具参数、结果和恢复记录可以保留 `undefined`、BigInt、`NaN`、无穷大、稀疏数组、循环引用和共享引用关系。普通 JSON 结果仍以结构化值返回；特殊值会以可读文本展示给模型，其程序内值与展示文本分别处理。
-
-这不等于任意 JavaScript 对象都可传递或持久化：函数、Promise、类实例、Date、Map、Set 等不属于值传递的支持域。在 REPL 中保留函数供后续调用，与把函数作为工具结果返回，是不同的能力。需要继续计算时应复用会话变量；完整支持域见[值传递说明](docs/value-wire.md)。
-
-### 恢复有依据的计算状态
+在插件 graph IPC 支持的值范围内，程序参数、结果和恢复记录能保留 `undefined`、BigInt、`NaN`、无穷大、稀疏数组、循环引用和共享引用关系，支持的值直接返回即可，不必自己写 `JSON.stringify`（它会丢掉对象里的 `undefined`，把 `NaN` 和无穷大变成 `null`、把 `-0` 变成 `0`，还会拒绝 BigInt）。函数、Promise、类实例、Date、Map、Set 不在这个范围内，原生 `tools.*` 的 JSON 参数与结果契约也不受影响，详见[值契约](docs/value-wire.md)。
 
-会话级状态不等于永久内存。重启、执行环境重置或上下文压缩后，只保留能从会话记录验证、且其来源仍在模型上下文中的计算状态。直接读取外部文件或网络、历史记录损坏、来源被压缩等情况，都可能缩小可保留的范围。
-
-无法证明的状态会被丢弃并给出提示，必要时从空环境继续当前计算。恢复不会重新派发已记录的原生工具调用，也不会撤销历史外部效果。恢复依据和限制见[运行时参考](docs/runtime-reference.md)。
+会话状态不是永久内存：重启、执行环境重置或上下文压缩后，只保留能从会话记录验证、且来源仍在模型上下文中的状态，其余会被丢弃并给出提示，必要时从空环境继续当前计算。会话记录本身缺失或损坏时会明确报错，不会被当作成功恢复的空会话。恢复不会重新派发已记录的原生工具调用，也不会撤销历史外部效果，依据和限制见[运行时参考](docs/runtime-reference.md)。
 
 ## 使用边界
 
-- **执行权限**：主要面向 `danger-full-access`。代码可直接访问 Node.js 与操作系统；插件不额外提供安全沙箱。DSH 继续负责原生工具权限、审批、取消和沙箱策略。
-- **失败与重跑**：代码执行失败不代表此前语句没有生效。进程隔离、编辑和恢复都不保证外部操作可以安全重复；超时或输出超限等情况也可能释放计算环境。
-- **错误与开销**：语言适配和调用容错不保证所有代码成功。实际调用次数与 token 用量取决于任务和模型；已有对照观察及限制见[评测说明](docs/evaluation.md#recorded-paired-observation)。
+- **执行权限**：主要面向 `danger-full-access`。代码可以直接访问 Node.js 和操作系统，插件不额外提供安全沙箱；原生工具权限、审批、取消和沙箱策略仍归 DSH。
+- **失败与重跑**：代码执行失败不代表之前的语句没生效。进程隔离、编辑和恢复都不保证外部操作可以安全重复，超时或输出超限也可能释放计算环境。
+- **错误与开销**：语言适配和调用容错不保证所有代码都能跑通，实际调用次数和 token 用量取决于任务和模型，已有对照观察及限制见[评测说明](docs/evaluation.md#recorded-paired-observation)。
 
 PTC Plus 是社区插件，与 DeepSeek 或 DSH 无隶属或背书关系。
 
-## 进一步阅读
+## 开发
+
+开发在仓库根目录进行：`npm ci` 安装依赖，`npm run build` 重新生成 `client.cjs` 和 compiler 产物。聚焦测试必须指定用例：
+
+```sh
+npm run test:backend:focus -- --file test/<owner>.test.js --test-name-pattern="<case>"
+npm run test:client:focus -- "<test name pattern>"
+```
 
-[安装与升级](docs/installation.md) · [全局绑定](docs/user-bindings.md) · [运行时参考](docs/runtime-reference.md) · [架构与开发](docs/architecture.md) · [验证指南](docs/verification.md) · [全部文档](docs/README.md)
+交付前按[变更分类](docs/verification.md#change-classification)选检查：只改文档跑 `npm run verify:docs`，其他改动跑 `npm run check`，然后走[评审流程](docs/review-procedure.md)。架构和数据面见[架构与开发](docs/architecture.md)，全部文档见[文档索引](docs/README.md)，安装与发布见[安装指南](docs/installation.md)和[发布流程](docs/publishing.md)。
 
 [MIT License](LICENSE)