# 全局绑定使用指南

简体中文 · [English](user-bindings.en.md)

全局绑定把常用 TypeScript helper 保存下来，供多个会话复用。例如，保存名为 `textTools` 的绑定后，模型可以在 `run_code` 中调用 `textTools.clean(text)`。

## 创建和使用

1. 打开 PTC Plus 设置（已有星光入口时可直接选择菜单中的 **PTC Plus 设置**；根据 DSH 界面，也可以在侧栏 **Plugins** 页面找到本插件并点 **Configure**，或打开 **设置 → 插件配置 → PTC Plus**），开启“全局用户绑定”。
2. 在 PTC 会话中打开输入框星光按钮的菜单，选择“编写新绑定”，或输入 `/binding new <需求>`。
3. 等待 Agent 提交草稿，在输入框上方检查源码、接口和给模型的提示词。
4. 选择“保存并启用”。后续 `run_code` 会加载该绑定；如果初始化失败，执行结果会说明原因。

编写过程中，Agent 会先用小型内存样例验证核心行为，再用 `node:assert/strict` 补充正常、边界和失败断言。批量测试只报告总数和少量代表性失败，避免把每个成功样例写入上下文。测试不得修改外部文件或服务；文件和网络 helper 可以用内存替代对象验证参数转发与错误传播，未实际验证的集成部分应在回答中说明。提交草稿只交给你审阅，保存与启用由你决定。

编辑已有绑定可用 `/binding edit <id> <需求>`。`id` 是管理工作台中的存储标识，不一定与调用名称相同；也可以在绑定清单中选择 Agent 编辑入口。

## 草稿面板

新草稿自动在输入框上方展开。点击标题栏或使用 Enter/Space 折叠、展开；长内容可在面板内滚动。

- **保存为停用**：保存到全局列表，暂不加载。
- **保存并启用**：保存并允许后续调用加载。
- **丢弃草稿**：放弃这份未保存候选。
- **关闭面板**：只隐藏面板，不保存或丢弃。

输入框星光按钮显示待处理草稿的角标。悬停、点击或键盘打开菜单后，选择草稿即可重新显示。每个会话保留一份当前候选。保存或丢弃确认成功后面板关闭；失败时保留草稿供重试。

星光按钮悬浮或聚焦时显示 PTC Plus 提示，说明它是全局用户绑定入口；有待处理草稿时改为提示草稿状态。星光菜单在首条消息发出前即可使用，鼠标停留一下才展开，扫过输入区不会弹出。悬停打开后鼠标移开菜单即自动关闭；点击可让菜单保持常开，再点一次、点击别处或按 Escape 关闭。全局绑定按名称和用途列出，选中标记与文字表示启用状态；点击条目切换启停，配置对所有会话生效。目录在后台刷新，刷新期间沿用上一次的列表并可以继续操作；保存期间暂时禁用切换，发生冲突或失败时可重新加载后再操作。“管理全局绑定”打开完整工作台；编写命令可用时显示“编写新绑定”和“修改绑定”，“修改绑定”第二步从已有条目中选择后预填 `/binding edit <id> `。REPL 可复用绑定列表会显示每项被后续 cell 复用的次数，并在区块标题显示总复用次数；次数按后续 cell 编译后源码中的静态引用统计，重定义或重声明本身不算一次复用，也不会把已累计的次数清零。

历史中的“绑定编写”请求保留需求、状态和接受时的源码。它供查看当时内容，不重新获得保存资格。目录发生并发修改时，重新加载最新状态后再决定是否保存。

## 接口和给模型的提示词

每个条目有两个独立设置：

| 设置 | 用途 |
| --- | --- |
| 将接口声明提供给模型 | 默认开启。从源码生成名称、参数、返回类型、相关类型和 API 注释，无需另写声明 |
| 给模型的提示词 | 可留空。补充类型未表达的使用时机、输入约束或示例 |

例如，一个接受字节数的格式化函数可补充：“输入单位为字节，显示时使用 IEC 单位。”函数签名已经清楚的用法无需再写一遍。

接口会保留公开签名使用的标准全局类型，并带上实际引用的本地 `interface`、`type`、`enum` 和 `class`。类接口包含公开实例字段、参数属性、方法、访问器和可自包含表示的继承链，不暴露 private、protected 或 static 成员；抽象类仍以抽象构造签名公开，不能被模型当作普通构造器，不同条目中的同名本地类型彼此隔离。`import('package').Type` 形式可以保留，无法脱离源码 import 独立表示的类型或基类会在保存前给出错误，不会静默改成 `unknown`。

模型收到一行 `run_code` 调用位置和接口参考文档更新说明，以及各条目的名称、已配置提示词和所选接口。内容未变时不会因普通调用重复发送。

关闭接口展示不会关闭独立提示词；两者都省略也不会禁用绑定执行。已启用条目的说明在新会话首轮提供，中途保存、启停、删除或修改后在下一次允许的请求中更新。若 DSH 暂停运行时上下文投递，更新会暂缓。

仅修改提示词、声明开关、用途说明或 top-level 显示名会保留已加载模块状态。修改实现源码、scope、namespace 调用名或导出列表会在后续执行时重新加载。

## 手动管理和试运行

从设置中的“管理全局绑定”或会话 **REPL** 页签打开工作台。没有当前 PTC 会话也可以手动创建、导入 `.ts`、检查声明、编辑、启停或删除绑定。

源码必须是带具名值导出的 TypeScript 模块，不支持默认导出或转出其他模块的导出。`namespace` 将选中导出放在一个对象下；`top-level` 直接暴露选中导出。导出列表留空时使用全部具名值导出。名称冲突会在启用前被拒绝。

代码控制台运行当前条目的未保存草稿，支持顶层 `await`，并在连续输入之间保留临时变量。它与 Agent 会话的变量分开，但拥有相同的进程权限；你手动执行的文件、网络等操作会产生真实效果。停止、重置、切换条目或离开工作台会释放环境；源码修改后的下一次运行重新开始。连续十分钟不运行代码也会释放环境，界面中的输入输出记录仍保留。

绑定保存在 `$DSH_HOME/ptc-plus/bindings.json`。条目源码中的相对 import 从该文件所在目录解析，普通会话 REPL 的 import 则从会话项目目录解析。

## 使用限制

已启用表示绑定配置允许加载，不保证每次初始化都成功。当前会话中同名变量的赋值或重声明可以覆盖全局默认值，不会修改保存的条目。

重启后只能恢复可验证的会话状态，不能保证外部文件或服务仍与历史执行时相同。恢复不会重发历史工具操作；无法恢复的部分通过诊断说明。源码格式、资源上限和恢复机制见[运行时参考](runtime-reference.md#global-user-bindings)；工作台详细交互见[客户端 UI](client-ui.md)。