# 全局绑定使用指南

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

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

## 创建和使用

全局绑定和星光入口默认开启；新安装无需先改设置。若已有配置显式关闭了全局绑定，可从 **插件 → 已安装 → dsh-ptc-plus → 配置** 重新开启；若只隐藏了快捷入口，可打开“显示 PTC Plus 快捷入口”。功能开关不改变已保存条目的启停状态。

1. 在 PTC 会话中打开输入框星光按钮的菜单，选择“编写新绑定”，或输入 `/binding new <需求>`。
2. 等待 Agent 提交草稿，在输入框上方检查源码、接口和给模型的提示词。
3. 选择“保存并启用”。后续 `run_code` 会加载该绑定；如果初始化失败，执行结果会说明原因。

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

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

## 草稿面板

新草稿自动悬浮在输入框上方。点击标题栏或使用 Enter/Space 折叠、展开，不挤动对话和输入框；长内容可在面板内滚动；输入框上方空间不足时只显示标题栏，仍可放大查看；连标题也放不下时保留星光菜单和历史请求的草稿入口，手动草稿入口始终直接打开大窗口。点击 **放大查看绑定草稿** 打开大尺寸审阅窗口，正文独立滚动，底部始终保留保存与丢弃按钮。标题栏的尺寸切换与关闭按钮之间留有间距。按 Escape、点击遮罩或 **缩小显示绑定草稿** 返回预览；预览没有可用空间时焦点回到星光入口，不保存或丢弃草稿。独立关闭按钮隐藏草稿面板，可从星光菜单重新打开。

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

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

星光按钮的 PTC Plus 提示延迟显示，说明它是全局绑定与设置入口；有待处理草稿时改为提示草稿状态。菜单、管理窗口或设置窗口打开时隐藏提示，避免遮挡。星光菜单在首条消息发出前即可使用，鼠标停留一下才展开，扫过输入区不会弹出。悬停打开后鼠标移开菜单即自动关闭；点击可让菜单保持常开，再点一次、点击别处或按 Escape 关闭。全局绑定按启用、停用分组并显示数量，已启用条目优先展示，停用组每次打开菜单时默认折叠，可点击或用 Enter/Space 展开；条目保留名称、用途与状态文字。只有绑定列表滚动，底部编写、修改、管理与设置操作固定可见，“修改绑定”第二步的“返回”也固定在底部；点击条目切换启停，配置对所有会话生效。目录在后台刷新，刷新期间沿用上一次的列表并可以继续操作；切换写入逐条串行化，写入进行中条目保持可用，重复请求被直接丢弃；发生冲突或失败时可重新加载后再操作。启停后条目进入对应分组；焦点仍在菜单中时跟随该条目，若条目进入折叠的停用组则回到组按钮，不抢走菜单外的焦点。焦点恢复仅滚动绑定列表来显示目标，不移动底栏或对话。“管理全局绑定”打开完整工作台；编写命令可用时显示“编写新绑定”和“修改绑定”，“修改绑定”第二步从已有条目中选择后预填 `/binding edit <id> `。“刷新会话能力”沿用相同输入框保护，预填 `/capabilities refresh` 后由用户发送，不直接执行；输入框已有草稿时保留原文。菜单从已启用分组开始，不显示全局生效范围说明；停用组使用与面板一致的浅色折叠行，主菜单与“修改绑定”列表共用状态小胶囊，启用显示绿色、停用显示灰色，编写与四个工具操作采用双列按钮，图标两侧留出对称空间以保持文字居中，柔和底色替代描边。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 则从会话项目目录解析。

## 只在本会话关闭某个绑定

全局条目决定"目录里有什么"，某个会话用不用它是另一件事。在会话里输入：

| 命令 | 作用 |
| --- | --- |
| `/binding status` | 列出目录里的每个条目，并标明本会话是否使用它 |
| `/binding skip <id>` | 本会话不使用某个条目；`id` 是 `status` 里括号前那个标识 |
| `/binding use <id>` | 撤销上一步，恢复为使用 |
| `/binding reset` | 清空本会话的全部选择，回到"目录给什么就用什么" |

它只改变**本会话**：全局条目和其他会话都不受影响，改完立即对下一个单元格生效，会话重启后依然有效（记录在会话日志里，可重建）。

它只能"少用一个目录里已有的条目"，不能凭空增加一个。目录里没有或已停用的条目，本会话也拿不到——所以不存在"全局关掉、会话又把它复活"的情况。

## 使用限制

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

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