dsh-ptc-plus 0.4.3 → 0.4.10

package/README.en.md

@@ -37,10 +37,14 @@ dsh plugin --profile <profile> add dsh-ptc-plus
 
 Replace `<profile>` with your profile name. Restart DSH and select **PTC mode** in the session. Continuous computation, call tolerance, and global bindings default to on. Explicitly disabled options in an existing configuration stay disabled.
 
+Session history uses DSH's public reader, and the Host incrementally projects prompt facts. Missing read surfaces or malformed historical event arrays produce explicit diagnostics, not a claim that unavailable history was successfully recovered as an empty session.
+
 With the default interface settings, the session has a **REPL** tab; wide screens also show a green **PTC Plus** header indicator. The sparkle button beside the composer opens the global binding menu and **PTC Plus settings**. You can also open **Plugins → Installed → dsh-ptc-plus → Configure** in the sidebar to check the main switch and all plugin settings.
 
 Once installed, describe your task to the model as usual. The `run_code` and `edit_run_code` examples below show how the model uses these features. See the [installation guide](docs/installation.md) for other installation methods, Desktop, the local development launcher, upgrades, and troubleshooting.
 
+For Windows source testing, double-click `scripts\run-upstream-dsh.cmd` to fetch the official DSH default branch, reuse an isolated build cache, and load this plugin checkout. The first run installs dependencies and builds DSH; see [upstream source testing](docs/installation.md#upstream-source-development-launcher-windows).
+
 ## Feature overview
 
 Default PTC mode starts every execution in a fresh environment: variables from the previous call are gone, and a change that depends on earlier results means resending the setup code. PTC Plus turns `run_code` into a session-bound TypeScript REPL and closes the gaps below.
@@ -52,6 +56,7 @@ Default PTC mode starts every execution in a fresh environment: variables from t
 | Change a small part of the code | A one-line change means resending the complete source | Submit a delta through `edit_run_code`, then execute the complete revised cell |
 | Use module syntax | Static `import` and `export` are invalid inside the function body | Write them directly in a cell; the plugin adapts the module syntax |
 | Omit a call summary | Missing `run_code.description` fails validation | Supply a display summary automatically so otherwise valid code proceeds |
+| Provider rejects malformed tool JSON | The whole turn ends with a provider error | Repair or preserve a buffered tool-call tail containing only tool framing and at most one usage event; route every other buffered tail through schema rejection so the model continues |
 | Recover a misplaced top-level tool call | Undeclared top-level calls are rejected in PTC mode | Convert the call to `run_code` when the live tool definitions uniquely identify the target and validate its arguments |
 | Locate a code error | Return the native error and stack | Map the error to the cell source; suggest an edit when a missing trailing delimiter has one verified correction |
 | Work with the current project | Relative Node paths depend on the host process directory | Resolve file paths, session module imports, and default child-process directories from the session project directory |
@@ -125,12 +130,15 @@ edit_run_code({
 
 An edit **reruns the entire cell**; this example returns `12`. Earlier state changes are not rolled back. If the code writes files or calls external services, rerunning still requires considering duplicate effects. Edits can repair failed code or refine a successful computation.
 
+Republishing a historical result as a compacted display entry is not another execution and does not make the older cell the new edit target. A newer failed cell remains available for correction.
+
 ### Recover from identifiable call problems
 
 | Situation | PTC Plus behavior |
 | --- | --- |
 | `run_code` omits its outer `description` | Supply a display summary so code with otherwise valid arguments can execute |
 | The model calls a native tool outside the PTC direct-tool list | Convert it to the corresponding `run_code` when current tool definitions uniquely identify the target and validate the arguments |
+| Argument validation reports a missing `description` | Distinguish outer and nested tool arguments and provide correction guidance, saved as a complete message so session history remains loadable |
 | Code fails to parse | Identify the source position; at EOF, suggest a target-bound edit if appending one or two closing delimiters has exactly one validated correction |
 
 The first two behaviors default to on and can be disabled in settings. Syntax suggestions do not execute automatically or establish that the code matches the task's intent.
@@ -187,9 +195,9 @@ Global bindings and the sparkle shortcut default to on. Create entries manually,
 
 ### Author, review, and enable
 
-The model can test with in-memory examples before submitting a draft. The draft appears above the composer, where you review its source, interface, and model instructions, then choose **Save and enable**, **Save disabled**, or **Discard draft**. Submission alone neither saves nor enables a binding. If you close the panel, the sparkle button's draft badge lets you reopen it.
+The model can test with in-memory examples before submitting a draft. The draft floats above the composer; expanding or collapsing it leaves the conversation in place. Opening a draft from the composer menu or original request goes directly to the large dialog. Choose **Enlarge binding draft** to review the complete source in a large dialog with independent scrolling and save/discard actions at the bottom. The header separates resize and close controls; **Shrink binding draft** returns to preview. Review its source, interface, and model instructions, then choose **Save and enable**, **Save disabled**, or **Discard draft**. Submission alone neither saves nor enables a binding. If you close the panel, the sparkle button's draft badge lets you reopen it.
 
-The sparkle menu lists and toggles entries even before the first message; these choices apply across sessions. Enabled entries' interfaces and usage notes are provided to the model in new sessions. Changes during a session are delivered on its next allowed request.
+The sparkle menu lists and toggles entries even before the first message; these choices apply across sessions. Enabled entries appear first; the disabled group shows its count and starts collapsed. Only the binding list scrolls, keeping authoring, revision, management, and settings actions visible at the bottom. Enabled entries' interfaces and usage notes are provided to the model in new sessions. Changes during a session are delivered on its next allowed request.
 
 ### Interface guidance and independent trial runs
 
@@ -201,6 +209,8 @@ The workbench can run unsaved source and retain temporary variables across execu
 
 The **REPL tab** lets you search retained names, inspect definitions, see reuse counts and bounded value previews, and open the global binding workbench. Previews have type and size limits; missing, incomplete, or unreadable previews are identified explicitly, and display does not invoke user getters. The green **PTC Plus** header indicator offers a quick binding list on wide screens; use the REPL tab on narrow screens.
 
+Workbench controls provide visible keyboard focus and disabled feedback, and REPL names remain readable in light and dark themes. See the [visual contract](docs/client-visual-contract.md) for browser regression checks and their coverage limits.
+
 ![Session state and the global binding workbench in the REPL tab](assets/ptc-plus-repl-workspace-en.png)
 
 The sparkle menu beside the composer groups binding authoring, entry management, and **PTC Plus settings**. Its settings dialog and the sidebar plugin configuration page share the same configuration:
@@ -217,7 +227,9 @@ The sparkle menu beside the composer groups binding authoring, entry management,
 
 Everyday computation features default to on. **Cordis development tools default to off** and can be enabled when inspecting or developing DSH plugins; see the [integration notes](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md). Explicitly disabled options stay disabled, and each saved binding keeps its own enabled state.
 
-Settings usually apply immediately. A worker's memory limit cannot be changed while that worker is active. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and full limits.
+Settings usually apply immediately. A worker's memory limit cannot be changed while that worker is active or a submitted cell is preparing to execute. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and full limits.
+
+The host execution provider must use TypeScript. Changing it to another language during reload withdraws the active PTC runtime and reports a diagnostic; returning to TypeScript reactivates it without changing the plugin setting.
 
 ![PTC Plus settings card](assets/ptc-plus-settings-en.png)
 

package/README.md

@@ -37,10 +37,14 @@ dsh plugin --profile <profile> add dsh-ptc-plus
 
 将 `<profile>` 替换为实际 profile 名称。安装后重启 DSH，在会话中选择 **PTC 模式**。连续计算、调用容错和全局绑定默认开启；已有配置中显式关闭的选项会保持关闭。
 
+会话历史通过 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)。
+
 ## 功能概览
 
 默认 PTC 模式的每次调用都从新环境开始：上次的变量不再存在，改动依赖前面的结果时只能重发准备代码。PTC Plus 把 `run_code` 变成会话级的 TypeScript REPL，补上下面的落差。
@@ -52,6 +56,7 @@ dsh plugin --profile <profile> add dsh-ptc-plus
 | 只改一小段代码 | 改动一行也要重新发送整段源码 | `edit_run_code` 只提交差异，再执行修改后的完整代码 |
 | 使用模块语法 | 函数体里不能直接写静态 `import` / `export` | 在 cell 中直接写，插件自动适配模块语法 |
 | 调用漏填摘要 | 缺少 `run_code.description` 时校验失败 | 自动补充显示摘要，其余参数合法的代码继续执行 |
+| 提供方拒绝畸形工具 JSON | 整个 turn 以 provider 错误终止 | 缓冲的工具调用尾部仅含工具块和至多一个用量事件时可修复或保留参数；其他缓冲尾部转为 schema 拒绝结果，模型继续下一步 |
 | 误发顶层工具调用 | PTC 模式下未声明的顶层调用被拒绝 | 当前工具定义能唯一确认目标且参数合法时，转为对应的 `run_code` |
 | 定位代码错误 | 只返回原生错误与堆栈 | 对应到 cell 源码位置；末尾缺少闭合符且修正可唯一验证时给出编辑建议 |
 | 访问当前项目 | 相对路径按宿主进程目录解析 | 按会话项目目录解析文件路径、会话模块导入和默认子进程目录 |
@@ -125,12 +130,15 @@ edit_run_code({
 
 修改后会**重新执行整个 cell**，以上例子返回 `12`。已发生的状态修改不会回滚；如果代码涉及写文件或外部服务，重跑仍需考虑重复效果。编辑既可用于修复失败的代码，也可用于微调已成功的计算。
 
+历史结果被压缩为新的显示条目，不算再次执行，也不会把旧 cell 变成新的编辑目标；较新的失败 cell 仍可继续修正。
+
 ### 处理可以确定的调用问题
 
 | 情况 | PTC Plus 的处理 |
 | --- | --- |
 | `run_code` 漏填外层 `description` | 补充显示摘要，让其余参数合法的代码继续执行 |
 | 模型误发 PTC 直接工具列表之外的原生工具调用 | 当前工具定义能唯一确认目标且参数合法时，转为对应的 `run_code` |
+| 参数校验报告缺少 `description` | 区分外层与嵌套工具参数并给出修正提示；提示以完整消息保存，保持会话历史可加载 |
 | 代码解析失败 | 标出源码位置；若错误在末尾，且追加一到两个闭合符只有一种通过验证的修正，给出绑定原调用的编辑建议 |
 
 前两项默认开启，可在设置中关闭。语法建议不会自动执行，也不代表插件能判断代码是否符合任务意图。
@@ -187,9 +195,9 @@ return capabilities.inspect({
 
 ### 编写、审阅与启用
 
-模型可先用内存样例测试，再提交草稿。草稿显示在输入框上方，由你检查源码、接口和给模型的提示词，并选择 **保存并启用**、**保存为停用** 或 **丢弃草稿**。提交草稿本身不会保存或启用绑定；关闭面板后，可从星光按钮的草稿角标重新打开。
+模型可先用内存样例测试，再提交草稿。草稿悬浮在输入框上方，展开或折叠不挤动对话；从星光菜单或原请求打开草稿时，直接进入大窗口。点击 **放大查看绑定草稿** 可在大窗口内审阅完整源码，正文独立滚动，底部保留保存与丢弃按钮；标题栏的放大、缩小与关闭操作分开显示，点击 **缩小显示绑定草稿** 返回预览；由你检查源码、接口和给模型的提示词，并选择 **保存并启用**、**保存为停用** 或 **丢弃草稿**。提交草稿本身不会保存或启用绑定；关闭面板后，可从星光按钮的草稿角标重新打开。
 
-星光菜单可在首条消息发出前查看、启停条目，选择对所有会话生效。已启用条目的接口和使用提示会提供给新会话中的模型；中途修改后，在现有会话的下一次允许请求中更新。
+星光菜单可在首条消息发出前查看、启停条目，选择对所有会话生效。已启用条目优先展示，停用组显示数量并默认折叠；只有绑定列表滚动，底部编写、修改、管理和设置按钮始终可见。已启用条目的接口和使用提示会提供给新会话中的模型；中途修改后，在现有会话的下一次允许请求中更新。
 
 ### 接口提示与独立试运行
 
@@ -201,6 +209,8 @@ return capabilities.inspect({
 
 **REPL 页签**可搜索当前保留的名称，查看定义来源、复用次数和有界值预览，也可打开全局绑定工作台。预览有类型和大小限制，未采集、不完整或不可读取时会明确标注，不会为展示调用用户 getter。宽屏顶部的绿色 **PTC Plus** 标志提供快捷绑定清单，窄屏可使用 REPL 页签。
 
+工作台控件提供可见的键盘焦点和禁用反馈，REPL 名称在明暗主题下保持可读；关键控件的浏览器回归检查及覆盖边界见[视觉契约](docs/client-visual-contract.md)。
+
 ![REPL 页签中的会话状态与全局绑定工作台](assets/ptc-plus-repl-workspace-zh.png)
 
 输入框旁的星光菜单将绑定编写、条目管理和 **PTC Plus 设置** 分组提供。设置弹窗与侧边栏插件配置页使用同一套配置：
@@ -217,7 +227,9 @@ return capabilities.inspect({
 
 面向日常计算的功能默认开启。**Cordis 开发工具默认关闭**，适用于检查或开发 DSH 插件，按需开启即可；详见[集成说明](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md)。已有配置中显式关闭的选项会保持关闭，条目是否启用也由各自的保存状态决定。
 
-设置通常即时生效；活动 worker 存在时不能修改其内存上限。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
+设置通常即时生效；活动 worker 存在或已提交的 cell 正在准备执行时不能修改其内存上限。字段、默认值和完整限制见[配置参考](docs/runtime-reference.md#configuration)。
+
+宿主执行 provider 必须使用 TypeScript。热重载改为其他语言时，PTC Plus 撤出当前接管并报告诊断；恢复 TypeScript 后重新启用，插件开关保持原选择。
 
 ![PTC Plus 设置卡片](assets/ptc-plus-settings-zh.png)