DSH plugin 的 PTC 运行时:宿主函数绑定、输出捕获与失败分类到底怎么接才最稳
“绑定拿不到”和“失败分不清”是 PTC 接入的两大坑,原因都在边界没对齐。 DSH plugin 的 PTC 运行时把调用方输入和执行输入拆成两个类型,把失败当成结果字段而不是异常。先把这两条边界理顺,再去调程序。 DSH插件 写 PTC 程序时,绑定名要可移植,失败要按 kind 分类读。
PTC 是可选能力,resolve 与 run 分工明确
resolve() 补默认值,run() 只接完全解析的输入。(来源)
PTC 执行能力 seam 通过 dsh-ptc-runtime 提供 ctx.ptcRuntime。它针对宿主绑定运行一个程序,报告输出、失败与适用的沙箱事实。这套能力是可选的,不属于 agent 循环主干。
PtcRunRequest 包含程序、绑定、取消与可选执行选择。提供方的 resolve 验证支持的选择并应用部署默认值;run 接收目录与截止选择明确的 PtcRunSpec。超时语义有三档:
- 省略
timeoutMs— 用提供方默认值; - 传数字 — 请求经过时间预算,提供方会验证并封顶;
- 传
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 不设统一的绑定字节上限。
命名有三条硬规则:
global必须匹配语言可移植的标识符子集[A-Za-z_][A-Za-z0-9_]*,且不能是任何语言的保留字——仅 JS 合法的$tools会被所有后端拒绝,这是设计如此;- 满足标识符规则但占用了后端保留槽位的名字(
RESERVED_BINDING_GLOBALS,例如console、__dsh_main__)同样被拒绝; - 绑定名是自有属性,因此
__proto__不能遍历原型,运行时必须用空原型构造。
可选的 errorClass 让拒绝变成程序可见的类型化错误:运行时在 name 下注入真实的错误构造函数,被拒绝的成员调用成为它的实例,并通过 memberNameProperty 暴露确切的成员名。可用的成员名属性名有排除集——RESERVED_ERROR_MEMBERS 加上双下划线形式——每个后端执行同一套规则。
输出捕获的通道与上限
日志是纯字符串,通道间的交错顺序不由 seam 保证。(来源)
每个来源通道保留自身的发出顺序;因为通道元数据不属于 seam,相互独立的通道如何交错由后端决定。运行时捕获程序的 console 与流输出,Consumer 只负责渲染文本。
上限的计量口径很具体:实现会对序列化后的外层日志数组,以及完成值或失败消息的组合载荷设置上限;固定的结果封装语法与 Consumer 展示空白不计入这份可变载荷计量。超限会显式失败,而不会在值里插入替代内容。
这条规则意味着你不能指望“超长输出被自动截断成提示”。要么控制程序输出量,要么接受 output-limit 失败。
失败分类是正交结果
八种 kind 分别描述不同事实,不能互相替代。(来源)
| kind | 含义 |
|---|---|
exception | 程序抛出,或解析与转换失败 |
timeout | 实现拥有的预算到期 |
abort | PtcRunRequest.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 当安全保证,是常见的误读。
验证:绑定一个会抛错的宿主函数
验证要覆盖绑定可见性、错误类型化与失败分类三处。(来源) 六步:
- 注册一个
tools命名空间,断言程序里能调用到它,且返回值为无损 JSON。 - 用一个
$tools命名空间做负例,断言在resolve阶段就被拒绝。 - 绑定一个会抛错的宿主函数,断言程序内收到的是 rejection,而不是整个运行中断。
- 配置
errorClass,断言被拒绝的调用是注入构造函数的实例,且成员名可从memberNameProperty读到。 - 制造一次超时,断言
kind是timeout且run没有 reject。 - 用已中止的
signal再跑一次,断言kind是abort,并且进行中的绑定调用仍需调用方自行收尾。
如果第 3 步程序直接崩溃,先检查绑定函数是否返回了非 JSON 值——运行时宁愿用描述性错误拒绝,也不会让有损值破坏整次运行。
PTC 的接入流程与超时取消,可以对照PTC 运行时概览;沙箱模式的边界见沙箱模式。
一句话收束: resolve 补默认、run 只接规格,绑定名要可移植,日志交错由后端定,八种失败是结果字段,沙箱事实不等于成功保证。
常见问题
不会,DSH plugin 把程序失败作为结果上的字段返回。DSH plugin 的 run 只在 Service Definition 契约被误用时 reject,程序异常、超时、中止都会以 PtcRunResult.error 形式 resolve。
不可以,DSH plugin 要求全局名匹配语言可移植的标识符子集。DSH plugin 明确说 $tools 这种仅 JS 合法的写法会被所有后端拒绝,不只是 Python 后端。
有,DSH plugin 把两者当成不同请求。DSH plugin 省略时用提供方默认值,传 null 表示不设经过时间截止,传数字则会被验证并封顶。
不会,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
来源
- DeepSeek Harness 官方参考 - PTC 运行时· deepseek-ai
- packages/ptc-runtime/ptc-runtime/src/types.ts· deepseek-ai