ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 PTC 运行时:宿主函数绑定、输出捕获与失败分类到底怎么接才最稳

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessPTC绑定失败分类
PTC 程序能跑,但宿主函数拿不到,或失败后分不清超时与代码错误。本文讲 resolve 与 run 的分工、绑定全局的可移植命名、输出捕获上限,以及 PtcRunFailure 的八种正交分类。

“绑定拿不到”和“失败分不清”是 PTC 接入的两大坑,原因都在边界没对齐。 DSH plugin 的 PTC 运行时把调用方输入和执行输入拆成两个类型,把失败当成结果字段而不是异常。先把这两条边界理顺,再去调程序。 DSH插件 写 PTC 程序时,绑定名要可移植,失败要按 kind 分类读。

PTC 是可选能力,resolve 与 run 分工明确

resolve() 补默认值,run() 只接完全解析的输入。(来源)

PTC 执行能力 seam 通过 dsh-ptc-runtime 提供 ctx.ptcRuntime。它针对宿主绑定运行一个程序,报告输出、失败与适用的沙箱事实。这套能力是可选的,不属于 agent 循环主干。

PtcRunRequest 包含程序、绑定、取消与可选执行选择。提供方的 resolve 验证支持的选择并应用部署默认值;run 接收目录与截止选择明确的 PtcRunSpec。超时语义有三档:

  1. 省略 timeoutMs — 用提供方默认值;
  2. 传数字 — 请求经过时间预算,提供方会验证并封顶;
  3. 传 null — 不设经过时间截止。

提供方会在执行前拒绝不支持的选择,所以“选项写错”应当表现为 resolve 抛错,而不是运行到一半才发现。

程序形态与保留状态是两件事

programFormat 管语法,stateOwner 管内存,二者互不影响。(来源)

PtcProgramFormat 有三种:function-body、repl、script。函数体支持顶层 await 与 return;REPL 与 Script 支持顶层声明、await 与末尾表达式,但不支持顶层 return。Node Script 提供方会转换顶层 await 并等待完成值,其声明限制适用于转换后的程序。

完成值会变成 PtcRunResult.value。注意它必须是跨越运行时无损 JSON 边界的值;无效或超限的完成值会让运行失败,而不是被替换成一段渲染字符串。

stateOwner 是一个进程内对象身份,用来标识可选的保留内存。不同对象相互隔离;无状态提供方直接忽略这个字段。消费者必须在所有者结束时等待 release(owner),清理失败时该调用会拒绝。省略所有者表示只执行一次。

还有一条硬边界:保留对象不会进入持久 Session 格式。所以别把“跨轮次记忆”寄托在 stateOwner 上,它不是持久化机制。

绑定成为全局对象,名字必须可移植

每个命名空间对应程序里的一个全局对象,名字要过可移植性检查。(来源)

PtcBindingNamespace 的说明很直接:每个命名空间成为一个异步可调用函数的全局对象,PTC 传入的是 tools。参数与返回值必须是无损 JSON;提供方强制各自的传输上限,seam 不设统一的绑定字节上限。

命名有三条硬规则:

  1. global 必须匹配语言可移植的标识符子集 [A-Za-z_][A-Za-z0-9_]*,且不能是任何语言的保留字——仅 JS 合法的 $tools 会被所有后端拒绝,这是设计如此;
  2. 满足标识符规则但占用了后端保留槽位的名字(RESERVED_BINDING_GLOBALS,例如 console、__dsh_main__)同样被拒绝;
  3. 绑定名是自有属性,因此 __proto__ 不能遍历原型,运行时必须用空原型构造。

可选的 errorClass 让拒绝变成程序可见的类型化错误:运行时在 name 下注入真实的错误构造函数,被拒绝的成员调用成为它的实例,并通过 memberNameProperty 暴露确切的成员名。可用的成员名属性名有排除集——RESERVED_ERROR_MEMBERS 加上双下划线形式——每个后端执行同一套规则。

输出捕获的通道与上限

日志是纯字符串,通道间的交错顺序不由 seam 保证。(来源)

每个来源通道保留自身的发出顺序;因为通道元数据不属于 seam,相互独立的通道如何交错由后端决定。运行时捕获程序的 console 与流输出,Consumer 只负责渲染文本。

上限的计量口径很具体:实现会对序列化后的外层日志数组,以及完成值或失败消息的组合载荷设置上限;固定的结果封装语法与 Consumer 展示空白不计入这份可变载荷计量。超限会显式失败,而不会在值里插入替代内容。

这条规则意味着你不能指望“超长输出被自动截断成提示”。要么控制程序输出量,要么接受 output-limit 失败。

失败分类是正交结果

八种 kind 分别描述不同事实,不能互相替代。(来源)

kind含义
exception程序抛出,或解析与转换失败
timeout实现拥有的预算到期
abortPtcRunRequest.signal 触发
worker-exit执行基底未结算就死亡,例如 OOM
invalid-output完成值不是无损 JSON
output-limit序列化后的日志、值或诊断超过配置上限
protocol程序发出无效或超预算的控制流量
sandbox-unavailable无法建立要求的约束

官方的定位是“正交结果独立报告”:预算耗尽不是异常,中止不是超时,基底崩溃也不是二者中的任何一个。message 是适合回喂给模型自我修正的人类可读细节。

还有一条结构性约定:错误是 resolved result 上的字段,永远不是 run() 的拒绝。只有 Service Definition 契约被误用时才 reject。所以调用方不该用 try/catch 接程序失败。

沙箱事实与执行边界

沙箱事实独立于终态,程序成功不等于约束都生效了。(来源)

PtcRunSandbox 有三部分:mode(本次执行的文件效果模式)、denied(程序失败文本匹配到后端诊断,它不是强制执行的证明,也不是完整的拒绝记录)、enforcement(所选约束后端报告的完整度,完全访问时缺失)。

官方特别强调三者是独立事实,因此程序成功本身不能证明每项请求限制都已强制执行。提供方如果本身不做约束,会拒绝显式传入的策略。

另外两个能力事实要分清:isolation 描述执行基底,不作安全声明;sandboxMode 声明文件策略支持,不提供约束的提供方返回 undefined。把 isolation 当安全保证,是常见的误读。

验证:绑定一个会抛错的宿主函数

验证要覆盖绑定可见性、错误类型化与失败分类三处。(来源) 六步:

  1. 注册一个 tools 命名空间,断言程序里能调用到它,且返回值为无损 JSON。
  2. 用一个 $tools 命名空间做负例,断言在 resolve 阶段就被拒绝。
  3. 绑定一个会抛错的宿主函数,断言程序内收到的是 rejection,而不是整个运行中断。
  4. 配置 errorClass,断言被拒绝的调用是注入构造函数的实例,且成员名可从 memberNameProperty 读到。
  5. 制造一次超时,断言 kind 是 timeout 且 run 没有 reject。
  6. 用已中止的 signal 再跑一次,断言 kind 是 abort,并且进行中的绑定调用仍需调用方自行收尾。

如果第 3 步程序直接崩溃,先检查绑定函数是否返回了非 JSON 值——运行时宁愿用描述性错误拒绝,也不会让有损值破坏整次运行。

PTC 的接入流程与超时取消,可以对照PTC 运行时概览;沙箱模式的边界见沙箱模式。

一句话收束: resolve 补默认、run 只接规格,绑定名要可移植,日志交错由后端定,八种失败是结果字段,沙箱事实不等于成功保证。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 PTC 程序抛错会让 run 直接 reject 吗?

不会,DSH plugin 把程序失败作为结果上的字段返回。DSH plugin 的 run 只在 Service Definition 契约被误用时 reject,程序异常、超时、中止都会以 PtcRunResult.error 形式 resolve。

DSH plugin 的绑定命名空间可以叫 $tools 吗?

不可以,DSH plugin 要求全局名匹配语言可移植的标识符子集。DSH plugin 明确说 $tools 这种仅 JS 合法的写法会被所有后端拒绝,不只是 Python 后端。

DSH plugin 的 timeoutMs 省略与 null 有区别吗?

有,DSH plugin 把两者当成不同请求。DSH plugin 省略时用提供方默认值,传 null 表示不设经过时间截止,传数字则会被验证并封顶。

DSH plugin 中止 PTC 运行时,会等正在进行的绑定调用结束吗?

不会,DSH plugin 只停止程序本身。DSH plugin 用 signal 中止时会以 abort 失败 resolve,但进行中的绑定调用仍由调用方自己收尾。

相关术语

PtcRunRequest
PtcRunRequest 是一次 PTC 运行的调用方输入,含程序、绑定、可选 cwd、超时、沙箱策略与取消信号。— packages/ptc-runtime/ptc-runtime/src/types.ts
PtcBindingNamespace
PtcBindingNamespace 是一组宿主函数,运行时把它暴露为程序里的一个全局对象,例如 tools。— packages/ptc-runtime/ptc-runtime/src/types.ts
PtcRunFailure
PtcRunFailure 是运行失败的正交分类,含 kind 与人类可读 message,kind 有八种取值。— packages/ptc-runtime/ptc-runtime/src/types.ts
PtcRunSandbox
PtcRunSandbox 是一次运行的文件约束事实,含模式、是否观察到拒绝与强制执行完整度。— packages/ptc-runtime/ptc-runtime/src/types.ts

来源