{"_id":"@buddhilive/dsh-tool-cordis","name":"@buddhilive/dsh-tool-cordis","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-tool-cordis","description":"Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/extensions/tool-cordis"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-cordis-host-runner":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-scope":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-cordis-host-runner":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-scope":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-tool-cordis@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-mfX899JxLGj98OAk2bW6KwvnhSV75uZ060aYvmEydSs2PK7GMvNAopJXwoW2HvrjTaUFhh+0msIc3OYszbrZvg==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-tool-cordis-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-tool-cordis-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-mfX899JxLGj98OAk2bW6KwvnhSV75uZ060aYvmEydSs2PK7GMvNAopJXwoW2HvrjTaUFhh+0msIc3OYszbrZvg==","shasum":"8bb167acfafaa99ef64b1e2e91a2ed4b5cb6d9ac","tarball":"https://registry.npmjs.org/@buddhilive/dsh-tool-cordis/-/dsh-tool-cordis-0.1.2-alpha.3.tgz","fileCount":15,"unpackedSize":527668,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDactb/FSonyNOYk81afBPmOoTun9ilf1e1PRjBneSYRgIgQNCBHjqZQ4mF+eKpg4YsTfruKP5kqKtnQ+5oGMEsFx4="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-tool-cordis_0.1.2-alpha.3_1788166627009_0.44119304242242596"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:57:06.819Z","0.1.2-alpha.3":"2026-08-31T08:57:07.157Z","modified":"2026-08-31T08:57:07.347Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/extensions/tool-cordis"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向 agent 与维护者的 Cordis 运行时工具说明，用于选择、组合或排查动态包工作流。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-tool-cordis\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-tool-cordis` 给模型提供七个作用于当前 DSH 进程实时 Cordis 运行时的工具：检查已加载的内容与动态包可用之物，定义包含 host 半、浏览器半或两者的包，运行它、停止它并移除它。包带版本——插件持有若干不可变的包版本，模型在失败后可以追加修正版并更新过去。定义只存在于进程内存中，DSH 重启即消失；本包不写仓库文件、不安装任何包、不改 `cordis.yml`。它还增加一个教这套工作流的系统提示词章节；把它与 `@buddhilive/dsh-cordis-host-runner` 一同组合，后者负责沙箱与运行往返。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当某个会话应当能临时扩展它自己的运行时——例如一个对当前工作有用、但不应成为仓库插件的模型编写的工具、服务或浏览器 UI——挂载本插件。请与 host runner 一同组合；没有 runner，这些工具永远不会激活，而且任何已发布的 bundle 都不会挂载这套工具集（web profile 已挂载 host runner 与浏览器侧组件），所以要显式地添加工具行。\n\n### 最小组合\n\n```yaml\n- name: '@buddhilive/dsh-cordis-host-runner'\n  config:\n    vmTimeoutMs: 5000\n- name: '@buddhilive/dsh-tool-cordis'\n```\n\nCLI 示例 [`apps/cli/config/examples/cordis/cordis.yml`](../../../apps/cli/config/examples/cordis/cordis.yml) 同时组合了这两者。带浏览器半的包还额外需要客户端组合里的浏览器 runner 与 UI 包；纯 host 包则两者都不需要。\n\n### 工具能做什么\n\n三个检查工具只读；四个生命周期工具定义并管理包。所有结果都是渲染成文本的 JSON。\n\n- `cordis_inspect_list`——列出 Inspect Provider（host 与 client）及其查询方法。\n- `cordis_inspect_query`——执行一次 provider 查询：精确的服务方法、事件分发模式、builtin 签名、工具 schema、主题 token 或实时 slot 树。\n- `cordis_inspect_self`——本会话的动态插件：版本指针、最近一次运行，以及（对某个精确包而言）源码与运行时诊断。\n- `cordis_define`——登记一个包：新插件（`plugin.kind: \"new\"`，配 3–6 个字母的 `idPrefix`），或既有插件的新版本（`plugin.kind: \"existing\"`，配其 `pluginId`）。它只校验参数与语法；不运行任何东西，也不请求审批。\n- `cordis_run`——激活一个包（首次激活或重启用 `mode: \"run\"`，切换版本用 `mode: \"update\"`）。带浏览器半的包可能先返回 `awaiting-approval`，直到有人允许；工具从不等待最终结果。\n- `cordis_stop`——停止当前运行并取消任何待审批请求，保留插件与全部包版本。\n- `cordis_undefine`——停止并彻底移除一个插件及其全部包。\n\n### 典型工作流\n\n先检查、再定义、后运行：`cordis_inspect_query` 读取包要用的服务或 slot 的精确约定，`cordis_define` 记录源码（会话里会出现一张 define 卡片，指向存放运行控件的面板），`cordis_run` 激活它。当用户输入 `@pluginId` 时，本包注入一条上下文消息，钉住所引用的插件、其基准包与更新路径。技术性失败之后，用 `cordis_inspect_self` 读取诊断，向同一插件追加修正版，再更新过去。\n\n### 需要规划的边界\n\n定义以会话为界、以进程为本：包只在定义它的会话里可见可控，可跨后续轮次保持活跃，运行时也可能影响同一进程中的其他会话。停止、移除、卸载工具集或重启 DSH 都会清除它。沙箱隔离全局变量，但不是安全边界——对待动态包要像对待 bash 访问一样，加载本插件时也要像授予 bash 工具那样慎重。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释工具背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。\n\n### 设计理念\n\n工具集建立在一个分离之上：工具是 runner 服务之上薄薄的一层模型面向层。检查数据来自生成的目录与实时服务存储的交集；定义与生命周期动词委托给 `ctx.dynamicCordisRunner`，它拥有注册表、vm 沙箱与浏览器往返。工具负责模型面向的判断：只展示可调用的方法、只点名 host 半够得到的键，并且每次拒绝都是模型可以直接行动的教学错误。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、系统提示词章节、`@pluginId` 上下文注入 |\n| [`src/inspect.ts`](src/inspect.ts) | 报告渲染：把生成的 API 目录与实时服务存储相交 |\n| [`src/api-catalog.ts`](src/api-catalog.ts) | 工作区 Cordis 声明的生成投影（由 `pnpm run gen-cordis-api` 重新生成，`verify-cordis-api` 守其新鲜度） |\n| [`src/prompt.ts`](src/prompt.ts) | `tool:cordis` 系统提示词章节 |\n| [`src/providers.ts`](src/providers.ts) | 第一方 host Inspect Provider：Service、Event、Builtin、Tool |\n| [`src/present.ts`](src/present.ts) | 可回放的通用卡片渲染意图 |\n\n### 一次调用的流程\n\n检查调用查询 `ctx.cordisInspect`：host provider 本地执行，client provider 等待第一个有效的页面应答。define 用与沙箱相同的包装器编译每一半来做语法预检，因此无法解析的代码在拿到 id 之前就被拒绝。run 委托给 runner：纯 host 包在进程内激活，带浏览器半的包挂起在 `cordis/request-run` 往返上；工具返回 runner 的回执（`awaiting-approval`、`starting` 或 `running`）。当用户写下 `@pluginId` 时，一个 `agent/pre-step` 处理器读取引用，并注入一条 user 角色的上下文消息，点明基准包与必须的后续步骤。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面。它们从共享工具集逐步进入 runner 内部、生成 schema 与子系统表面。\n\n- [Host runner](../cordis-host-runner/README.zh.md)——这些工具委托的注册表、沙箱与运行往返。\n- [Client runner](../cordis-client-runner/README.zh.md)——应答运行请求并装载浏览器半代码的浏览器半。\n- [UI 包](../ui-cordis/README.zh.md)——用户操作定义所用的面板与工具卡片。\n- [生成的工具目录](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-cordis)——模型收到的确切 schema。\n- [extensions 子系统](../../../docs/subsystems/extensions.zh.md)——生成的 `ctx.cordisInspect` 与 `ctx.dynamicCordisRunner` API。\n- [自引用 Cordis 工具集 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md)——设计居所：沙箱语义、动态包生命周期与组合。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到的内容\n\n该插件可见时，会话模型会看到生成的 [`cordis_inspect_list`、`cordis_inspect_query`、`cordis_inspect_self`、`cordis_define`、`cordis_run`、`cordis_stop` 和 `cordis_undefine` schema](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-cordis)。\n\n#### Token 影响\n\n该工具视图中的每次请求承担固定 schema 成本。\n\n#### KV Cache 影响\n\n只要该工具视图不变，前缀就保持稳定。隐藏这些定义的 scope 或插件生命周期变更，可能使从第一个变化的 schema token 起的复用失效。\n\n### 系统提示词章节\n\n#### 模型看到的内容\n\n本包注册一个系统提示词章节（`tool:cordis`，order 115），教模型何时以及如何使用动态包工作流、推荐的工具顺序与必须避免的高频错误；完整文本在 [`src/prompt.ts`](src/prompt.ts) 中。章节开头如下：\n\n##### 章节开头\n\n```markdown\n# Dynamic Cordis Plugins\n\nDynamic Cordis plugins temporarily extend the current DSH process. A Plugin uses apply(ctx) to consume Services, listen to Events, provide Services, register model Tools, or register browser UI in Slots.\n```\n\n#### Token 影响\n\n该插件可见时，章节渲染出的文本会在每次请求中重复。\n\n#### KV Cache 影响\n\n只要章节文本与顺序不变，前缀就保持稳定；编辑提示词或改变其顺序可能使从第一个变化 token 起的复用失效。\n\n### 工具调用历史与结果\n\n#### 模型看到的内容\n\n检查输出是渲染成文本的 JSON：`cordis_inspect_list` 返回 provider 目录，`cordis_inspect_query` 返回查询数据，`cordis_inspect_self` 返回插件、版本与包摘要，并在指定精确包时给出源码与诊断。define 回答该包已定义、尚未运行，并给出用于运行的 id。run 报告 `awaiting-approval`、`starting` 或 `running`，附运行 id 与版本指针。stop 与 undefine 各以一行确认。每一次拒绝都是携带 runner 教学文本的工具错误，提交的程序保留在 assistant 工具调用历史中。\n\n#### Token 影响\n\n检查输出与提交的包代码取决于数据，并在压缩（compaction）前重复发送；生命周期确认文本很短。\n\n#### KV Cache 影响\n\n仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n### cordis_run 之后的后续请求\n\n#### 模型看到的内容\n\n运行中的包可能注册工具、提示词贡献或监听器，改变其目标 scope 的后续请求；`cordis_stop` 与 `cordis_undefine` 会在完全停稳后移除这些贡献。当用户输入 `@pluginId` 时，注入的引用上下文还会增加一条 user 角色的消息，点明基准包与后续步骤。\n\n#### Token 影响\n\n间接 token 影响等于运行中包的贡献，且只在其进程内生命周期内持续。\n\n#### KV Cache 影响\n\n运行或停止提示词／工具贡献会改变后续请求前缀，并可能使从第一个变化的贡献起的复用失效；运行集合不变时，前缀保持稳定。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明工具集何时不合适或需要特别小心。它们是当前包约束，不是任务积压。\n\n- **沙箱只用于约束诚实代码，并非安全边界**——可以触及沙箱全局变量上的 host realm helper，因此包代码可以触达 Node；加载本插件时，应当像授予 bash 工具一样慎重。\n- **只支持纯 JavaScript**——动态包代码不做任何转换：没有 TypeScript、JSX 或 import，沙箱还扣下 `require`、`setTimeout`、`fetch` 等 Node 全局，把文件、网络与进程工作重定向到 Cordis 服务。\n- **vm 与审批边界属于 runner**——见它的[已知限制](../cordis-host-runner/README.zh.md#known-limitations-and-deferred-work)；async 的 host 半主体可逃出 `vmTimeoutMs`。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-a05d85754b9a5d0d1a0f6b1f22eb94ab"}