description: "动态 Cordis 包的 host 半说明，供选择、组合或排查注册表、沙箱与运行往返的 agent（智能体）与维护者阅读。" kind: "package-reference"

@x1a0f3n9/dsh-cordis-host-runner

English | 中文

概述

dsh-cordis-host-runner 提供运行时检查，并为程序调用方和浏览器控件保留进程内动态定义。Host 部分在 node:vm 中运行；浏览器部分使用 Client runner 和审批 UI。定义在重启后消失。Agent 通过 tool-cordis 发现 API，通过 Plugin Manager 安装持久化 bundle；没有模型工具创建动态定义。

目录

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

使用本包

需要检查注册表或程序侧动态包生命周期时挂载此插件。浏览器生命周期消费者还需要 Client runner 和 UI 包。内置 Creator 流程使用已安装 bundle，不使用此定义注册表。

最小配置

- name: '@x1a0f3n9/dsh-cordis-host-runner'
  config:
    vmTimeoutMs: 5000

| 字段 | 默认值 | 含义 | |---|---|---| | vmTimeoutMs | 5000 | host 半在 vm 中同步执行的那部分被中止求值前可运行的毫秒数 |

生成的配置目录是每个受支持字段的穷尽式真源。

run 会做什么

程序调用方使用 define、run、stop 和 undefine；浏览器面板操作已有定义。仅含 Host 的包在本进程激活。带浏览器部分的包等待审批或取消，批准后先加载 Host 再加载 Client。mode: "run" 启动当前版本，mode: "update" 替换版本。Stop 释放运行中的 effect 并保留定义；undefine 还会移除定义。

定义的去向

定义按会话隔离且仅在进程内存在：其他会话无法读取，重启会清空。历史日志保留工具参数和回执，但不会恢复注册表。浏览器页面重载后，需要再次显式运行才能加载 Client 部分。

信任立场

沙箱隔离全局变量，但不是安全边界：Node 全局变量不存在，或重定向到 Cordis 服务（ctx.fs、ctx.web、ctx.bash 与定时器 helper），host 半收到的是不含框架内部机制的 façade，但它声明的服务仍会触达存活运行时。对待动态包要像对待 bash 访问一样，参见自引用工具集 Agent Note。

理解实现

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

设计理念

runner 基于两项职责划分。注册表与沙箱是同一个服务。 DynamicCordisRunnerService 拥有定义注册表、vm 沙箱、host 半 fiber 生命周期与 invoke handler 表，因此一个定义的整个生命周期只有一个 owner。版本是不可变的包。 插件持有 define 之后永不变化的包；currentPackageId 与 nextPackageId 指向运行中与目标版本，mode: "run" 与 "update" 编码目标是否等于当前版本。浏览器往返之所以存在，是因为浏览器半只能由页面执行：服务 emit 请求并挂起，由页面的结论结算，调用方的 AbortSignal 是唯一的另一条出路。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | 服务入口：Config、注册表接线、生命周期动词、steering（中途引导）消息 | | src/registry.ts | 定义存储：插件与包标识、运行尝试、审批请求 | | src/sandbox.ts | node:vm 求值：全局变量、Node API 陷阱、define 时语法预检 | | src/guard.ts | 注册边界：schema 规范化、沙箱 ctx façade、插件形态检查 | | src/lifecycle.ts | 在 cordis-dynamic fiber 组下启动 host 半 | | src/inspect-registry.ts | ctx.cordisInspect 注册表：host 提供方加镜像的 client manifest（元数据清单） | | src/types.ts | dynamicCordisRunner remote namespace 与转发事件共享的 client 安全载荷形态 |

一次 run 的流程

define 对元数据做首尾去空白与必填校验，用编译预检每一半的语法（不执行任何代码），铸出插件与包标识，并把定义登记在发起调用的会话名下。run 对照 currentPackageId 与 nextPackageId 解析目标：纯 host 包在沙箱中求值并立即提交，带浏览器半的包则建立一次审批请求、emit cordis/request-run 并挂起。作答页面依次走 runHostHalf、getClientCode 与 resolveRequestRun；命名存活 revision 的成功会提交激活、设置 currentPackageId，cordis/request-run-resolved 让其他每个页面撤下待作答入口。stop 回退存活下发——handler disposer、fiber dispose（资源释放）与 cordis/dynamic-retract 广播——并让定义保持可运行。四条转发事件（cordis/request-run、cordis/request-run-resolved、cordis/dynamic-package、cordis/dynamic-retract）声明在 client 安全的 ./types 子路径上，并由 @x1a0f3n9/dsh-api-remotes 的白名单准许投递——正是这一点让浏览器能经 ctx.remote.$on 收到它们。

进一步探索

当包级约定不够用时阅读以下页面。它们从 runner 逐步进入调用它的工具、应答它的浏览器半与生成的表面。

• 工具包——使用其检查注册表的只读工具。
• Client runner——应答运行请求并装载浏览器半代码的浏览器半。
• UI 包——用户批准并操作运行的面板。
• 生成的配置目录——每个受支持配置字段。
• extensions 子系统——生成的 ctx.cordisInspect 与 ctx.dynamicCordisRunner API 及 cordis/* 事件。
• 自引用 Cordis 工具集 Agent Note——沙箱语义、生命周期与组合的理由。

模型体验

转达给所属会话的运行结果、拒绝与诊断

模型看到的内容

本包不注册工具或提示。程序侧 run 调用和浏览器控件可向所属会话发送结果与诊断；停止和移除操作注入用户消息。内置模型工具无法创建或更新动态定义。

Token 影响

有条件且随数据而定：消息只在事件发生时到达，每条都携带一段有界的说明；没有固定的每请求成本。

KV Cache 影响

本包自身没有。注册工具的 host 半会改变下一次请求的工具视图，从第一个变化的 schema token 起使前缀复用失效；运行或停止一个不注册任何工具的包对前缀不产生影响。

已知限制与延期工作

这些限制说明 runner 何时需要特别小心。它们是当前包约束，不是任务积压。

• 运行成功不代表 UI 已渲染——React 在加载回执之后渲染；失败通过 steering 发送到所属会话，并显示在浏览器面板中。
• 带浏览器半的包在没有页面连接的地方挂起——headless 与 ACP（Agent Client Protocol）部署会把 run 一直挂到提问的轮次被取消；纯 host 包不受影响。
• 挂起的 run 请求没有超时——它一直等人，直到提问的轮次被取消，因此无人值守的自动化用不了带浏览器半的包。
• vmTimeoutMs 只约束同步求值——async 的 host 半函数体会逃出该上限，这与工具集基于协作的信任立场一致。
• 陈旧成功的拒绝会让请求继续挂起——作答页面点名的 revision 已被注册表越过时，该结论会被拒绝（accepted: false），请求保持可作答，直到另一个页面作答或调用方取消；浏览器半不读这个 ack。
• 运行播报不携带服务声明——浏览器半声明的 inject 是从它在页面里返回的插件上读出的，因此 cordis/request-run 只携带元数据，绝无代码或服务清单。
• zod 是生成的 Typert 契约面的运行时依赖，不是 src 的依赖——./typert 与 ./remote 解析到未打包的 lib 文件，其中带有裸的 import { z } from 'zod'，所以即使 src 里没有任何代码 import zod，本包也要声明它。

开发备注

无。

运行时不变式： 不发布伴生入口。definition registry 位于进程内存中且没有可观察的事件流；它唯一负责的关系是运行中的 definition 拥有已结算的 host-half fiber 及其 handler table，该关系在单个等待完成的操作中建立和解除，因此由包测试直接断言。