5.8 KiB
@deepseek-ai/dsh-tool-cordis
English | 中文
自引用 cordis 工具集：三个面向模型的工具，操作 agent 所处的存活运行时。设计归属（沙箱语义、挂载生命周期、跨挂载组合、生成的 API 目录、既定决策）见工具集 Agent Note。
功能
cordis_inspect：运行时的只读报告，包括服务、已加载插件列表、已注册工具、动态挂载表，以及目录支持的api／events参考。精确的name配合what: "api"或what: "events"可缩窄报告，并附上原始源代码 JSDoc。cordis_mount：在node:vm沙箱中求值模型编写的 JavaScript（一个 async 函数的主体）；代码必须return一个 cordis 插件，系统将其挂载在cordis-dynamic分组 fiber 下，并以dyn-<n>跟踪。cordis_unmount：按 id 释放一项挂载，只在完全停稳后返回。
精确的面向模型 schema 见生成的工具目录。
规范成功值分别为检查字符串、挂载 { id, pluginName, state, provides, waitingFor }，以及卸载 { id, pluginName }。原生 renderer 保留现有文本，因此程序可以使用 mounted.id，普通 Function Calling 仍会看到 mounted dyn-1 (...)。
信任立场
该沙箱隔离全局变量，但不是安全边界。Node 全局变量不存在，或会重定向到 ctx.fs、ctx.web、ctx.bash 等 Cordis 服务；写入 globalThis 的内容保持局部，但 host realm helper 使逃逸成为可能。已挂载插件收到不含框架内部机制的 façade，但获准服务仍会影响存活运行时。动态工具 schema 与 annotation 通过迭代式 JSON 克隆和 schema 规范化跨越 realm，因此有效的深层声明受内存而非调用栈限制；含 JSON 不可见 key 的 record，以及子类化或装饰过的 schema array，会在规范化前被拒绝。应当像对待 bash 访问一样对待该工具集；参见设计与信任立场。
配置
| 字段 | 默认值 | 含义 |
|---|---|---|
vmTimeoutMs |
5000 |
挂载代码求值中同步部分的边界；async 主体可逃出该边界 |
生成的 API 目录
src/api-catalog.ts 由 scripts/gen-cordis-api.ts 生成，使用与 docs/cordis-catalog 相同的 AST 遍历，并由 pnpm run verify-cordis-api（位于 doc-sync 中）实施新鲜度门禁，绝不可手工编辑。cordis_inspect 在调用时把该目录与存活服务 store 取交集。宽泛的 api／events 报告只渲染摘要与签名；精确 name 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
渲染
三个工具都渲染 generic 卡片（read／execute／delete）；cordis_mount 以 rawInput 携带挂载代码。presenter 是 args 的纯函数；结果保留默认文本渲染。
导出形状
Namespace 插件：命名导出 name／inject／Config／apply，无默认导出（docs/postmortem/0001）。
模型体验
工具 schema
模型看到的内容
该插件可见时，会话模型会看到生成的 cordis_inspect、cordis_mount 和 cordis_unmount schema。
Token 影响
该工具视图中的每次请求承担固定 schema 成本。
KV Cache 影响
只要该工具视图不变，前缀就保持稳定。隐藏这些定义的 scope 或插件生命周期变更，可能使从第一个变化的 schema token 起的复用失效。
工具调用历史与结果
模型看到的内容
检查会精确地用 ## <section> 加换行及数据相关主体来拼接选中区段，各区段之间留一个空行。宽泛的 API／事件报告省略 JSDoc；name 配合 what: "api" 或 what: "events" 返回一个精确目标及其原始 JSDoc。挂载返回 mounted <id> (plugin "<name>", state: <state>)，并可在右括号前插入 — waiting for service(s): <names> (activates when provided)。卸载返回 unmounted <id> (plugin "<name>")；未知 id 会变成 Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")。提交的挂载程序保留在 assistant 工具调用历史中。
Token 影响
检查输出与挂载代码取决于数据，并在压缩前重复发送；生命周期确认文本很短。
KV Cache 影响
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
挂载后的后续请求
模型看到的内容
已挂载插件可以注册工具、提示词贡献或监听器，改变其目标 scope 的后续请求；卸载会在完全停稳后移除这些贡献。
Token 影响
间接 token 影响等于已挂载插件的贡献，且只在挂载生命周期内持续。
KV Cache 影响
挂载或卸载提示词／工具贡献会改变后续请求前缀，并可能使从第一个变化的贡献起的复用失效；挂载集合不变时，前缀保持稳定。
已知限制与暂缓事项
- 沙箱只用于约束诚实代码，并非安全边界：可以访问沙箱全局变量上的 host realm helper，因此挂载代码可以触达 Node；加载该插件时，应当像授予 bash 工具一样慎重（见 § 信任立场）。
ctxfaçade 不公开effect()：挂载代码无法注册定制 disposer；on／provide／tools.register已覆盖目前出现的每项挂载，受保护的effect会等待真实需求（FIXME(sandbox-effect)）。vmTimeoutMs只限制同步求值：async 挂载主体可逃出该边界；挂载代码没有 async 预算。