description: "Worker 线程代码执行，面向组装、容量规划或调试已发布 TypeScript 后端的用户与维护者；该后端在全新的 Node worker 中运行每个程序。" kind: "package-reference"

@x1a0f3n9/dsh-code-runtime-worker-thread

English | 中文

概述

本包让 PTC 组合能够使用宿主提供的绑定执行模型编写的 TypeScript，并取得完成值、顺序日志或结构化失败。每次请求都不继承先前运行的状态；语法错误、预算到期、中止、内存耗尽和输出溢出等失败会作为结果返回，而不是抛出。应将执行的代码视为与 bash 拥有同等权限：本包限制环境暴露和资源使用，但不将代码与宿主隔离。可配置的计算时间、墙钟时间、堆和输出上限会终止运行并限制其结果大小。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

当组合需要执行模型编写的 TypeScript 程序时，连同 code-runtime seam 一起挂载此后端；只要模型调用 run_code，dsh-tools 中的 PTC mode 就会通过 ctx.codeRuntime 驱动它。每个执行上限都是已验证的配置，因此你可以从 cordis.yml 为部署调整运行时规模。

最小配置

- name: '@x1a0f3n9/dsh-code-runtime'
- name: '@x1a0f3n9/dsh-code-runtime-worker-thread'
  config:
    computeMs: 60000            # busy-time budget (measured event-loop active time)
    maxWallMs: 600000           # wall-clock ceiling; never pauses for anything
    maxOutputBytes: 67108864    # combined serialized outer-output cap (64 MiB)
    maxOldGenerationSizeMb: 512 # worker heap cap

| 字段 | 默认值 | 含义 | |---|---|---| | computeMs | 60,000 | 忙碌时间预算：worker 实测事件循环活跃时间超过该值时，运行以 timeout 失败 | | maxWallMs | 600,000 | 墙钟上限，为忙碌时间无法观测的等待兜底；最大 2_147_483_647 | | maxOutputBytes | 67,108,864 | 序列化日志加完成值或失败消息的硬上限；至少 4 | | maxOldGenerationSizeMb | 512 | worker 堆上限；溢出会杀死 worker，并以 worker-exit 呈现 |

每个字段在加载时都会验证并提供默认值；没有其他可调项。生成的配置目录是所有受支持字段的完整参考。

运行返回什么

成功的运行把程序的无损 JSON 完成值作为 result.value 返回，把程序打印的文本按顺序作为 result.logs 返回。顶层 await／return 可用，程序可以把宿主提供的绑定函数（PTC mode 暴露一个 tools 对象）当作普通异步调用。

隔离措施，而非安全边界

程序运行时的权限与 bash 工具相当：它可以访问 Node API，后端也刻意不承诺与宿主的隔离。它提供的是隔离措施：独立 isolate、空环境（没有环境变量凭据，也不继承 loader 标志）、可配置堆上限，以及也能终止同步热循环的强制终止。程序派生的 OS 进程在 terminate() 后仍然存活，需要部署层面的清理。

可能出什么问题

每次程序运行都会通过 resolve 返回结果，因此运行失败会体现在 result.error 中，而不是触发 rejection：语法错误或不可擦除的 TypeScript（enum、namespace）在任何 worker 启动前就以 exception 失败；预算到期是 timeout；中止信号是 abort；堆溢出或其他 worker 终止是 worker-exit；不是无损 JSON 的完成值是 invalid-output；超出上限的序列化输出是 output-limit——并保留能容纳的已捕获日志前缀。只有调用方误用才会触发 rejection，例如在 dispose（资源释放）后提交运行。

理解实现

本节解释后端背后的设计；可观察行为已在使用本包中完整说明。

设计理念

后端基于一项明确区分：这是隔离措施，而非安全边界。模型代码按与 bash 等价的信任等级处理（PTC mode Agent Note 的 Trust posture），因此设计追求可重建性与有界资源使用，而非硬性的多租户边界——那需要等待容器级后端。每次运行使用一个全新的 worker，程序的世界随 worker 一同终止：不存在可泄漏、也无需记录的跨运行状态，仅凭会话日志即可重建一次运行。

执行流程

一次运行在宿主侧剥离类型（node:module 的 stripTypeScriptTypes，保持字节位置不变），包裹为异步函数的函数体使顶层 await／return 可用，然后发送给全新的 worker，由 bootstrap 物化绑定命名空间。绑定调用以无损 JSON 跨消息端口传递，每个调用 id 至多应答一次。日志文本主动流向宿主，因此被终止的程序仍会显示已打印的内容。恰好一个结果结算运行——done 帧、预算到期、中止或 worker 终止——之后宿主终止 worker 并等待其退出。

把对端视为不可信

模型代码能够访问 parentPort 并伪造通信，因此任何代码读取入站消息前，系统都会逐字段验证并重建：伪造的额外字段绝不随行，非数字的 call id 绝不会被回显进 reply，绑定名称只解析为自有属性（伪造的 constructor 无法沿原型链访问），垃圾被静默丢弃。worker 侧命名空间使用 null-prototype，因此形似 __proto__ 的绑定名称只是普通键。

预算

存在两个独立预算，因为对端不可信：computeMs 计量 worker 的实测忙碌时间（每 25 ms 轮询一次 eventLoopUtilization()），因此热循环无论是否有诱饵 dispatch 在途都会到期，而等待慢绑定的程序不累计；maxWallMs 为忙碌时间无法观测的情况兜底，例如永远不会 resolve 的 promise。二者最终都会调用 worker.terminate()。maxWallMs 在加载时对照 MAX_TIMER_DELAY_MS 做范围校验，因为 setTimeout 会把更长的延迟限制为 1 ms。

输出账本

maxOutputBytes 统计外层 logs 数组加完成值或失败消息载荷的 JSON 序列化；固定的 CodeRunResult 字段名与外层封装语法不计入这份账本。未超过上限时返回精确值；有损完成值属于 invalid-output，组合溢出属于 output-limit，不会用 inspected string 代替。失败会保留日志中能容纳的已捕获前缀。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | 插件入口：Config schema、WorkerThreadCodeRuntime、运行编排、输出账本 | | src/worker.ts | 源码模式 worker 入口（可擦除 TypeScript，不依赖 lib/） | | src/bootstrap.ts | worker 侧 bootstrap：命名空间物化、console shim、日志捕获 | | src/protocol.ts | host 与 worker 之间的端口消息词汇 | | src/worker-json.ts | worker 侧无损 JSON 编解码 | | src/output-json.ts | 外层账本的字节计量与截断 | | — | 不发布运行时不变式伴生入口；这个进程边界实现不暴露同进程事件关系，worker 协议测试与构建后 worker 测试负责覆盖。 |

未构建与已构建的 worker 入口

源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 src/worker.ts；其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 lib/ 导出。构建模式会把兄弟文件 lib/worker.cjs 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。

进一步探索

当后端约定不够用时阅读以下内容。它们从 seam 定义进入消费方与配置面。

• 代码运行时 seam——此后端实现的抽象约定。
• PTC mode Agent Note——dsh-tools 如何消费 ctx.codeRuntime 并呈现 run_code。
• 代码运行时子系统参考——请求／结果词汇、绑定与失败分类体系。
• 生成配置目录——每个受支持配置字段及其源声明。

模型体验

通过 dsh-tools 中的 PTC mode 间接提供，如果外层值能容纳则原样渲染，否则返回明确的 invalid-output／output-limit 失败，且只有外层 run_code 结果在其普通 spill 策略下进入模型上下文，绑定通信与中间值始终只存在于执行环境中。

KV Cache 影响

不会直接失效；由上述消费方负责请求前缀变更。

已知限制与延期工作

这些限制说明此后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。

• 程序派生的 OS 进程在程序终止后仍会存活——worker.terminate() 只结束线程，比 bash-local 的进程组终止更弱；在容器后端出现前，孤儿进程清理属于部署职责。
• 类型剥离依赖 Node 的实验性 stripTypeScriptTypes API——如依赖的行为发生变化，amaro 或 sucrase 是已经点名的直接替代品。
• computeMs 到期最多可能超过一个轮询间隔——系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
• 程序获得一个含 5 个方法的 console shim（log／info／warn／error／debug）——有意不提供 Node 的完整 console 接口。
• 中间绑定值没有字节上限——程序可以用永远不会成为外层输出的值耗尽进程或 worker 内存。
• 默认 64 MiB 上限是拒绝边界，不是可恢复存储——外层 spill 机制只能保存发生 output-limit 后返回的有界日志和诊断；在运行时上限之外被拒绝的字节永远不会到达 spill 层。

开发备注

无。