源码版本47f9438 (dsh@0.1)

插件上下文 API

dsh 通过 tool-cordis 扩展把"Cordis 运行时内省"暴露给 agent——七个工具覆盖发现/查询/定义/激活/停止/删除全流程。Inspect Provider 模型把 Host/Client 两端的 Service/Event/Builtin/Tool/Slot/Theme 都变成"渐进式目录 → 精确契约"两步式查询;API catalog 由 scripts/gen-cordis-api.ts 与文档同源生成,保证 agent 看到的签名与人类文档一致。

tool-cordis 扩展

packages/extensions/tool-cordis/src/index.ts:26-40:

export const name = 'tool-cordis'
export const inject = ['tools', 'systemPrompt', 'dynamicCordisRunner', 'cordisInspect']

export function apply(ctx) {
  // 注册系统 prompt section
  // 注册 host inspect providers
  // 注册七个工具
}

七个工具

1. cordis_inspect_list:发现

packages/extensions/tool-cordis/src/index.ts:41-58:

cordis_inspect_list  // 无参数
  → ctx.cordisInspect.list()
  → 全部 Provider 的 manifest(id/description/methods/input-output schema)

2. cordis_inspect_query:精确契约

packages/extensions/tool-cordis/src/index.ts:60-94:

cordis_inspect_query
  → platform / provider / method / input
  → ctx.cordisInspect.query(...)

Agent 必须先 list 再 query——禁止猜名字。

3. cordis_inspect_self:自检

packages/extensions/tool-cordis/src/index.ts:96-120:

• 无 ID → 列出当前 Session 的全部 Plugin 摘要
• 只给 pluginId → 返回版本指针 + 最近 Run
• 同时给 pluginId/packageId → 返回源码与诊断

cordis_inspect_self 是 agent 自检工具:发现 PENDING 原因(用 missingServices)、读自己 Package 的源码做修复、看 latestRun 的失败诊断。

4. cordis_define:定义不执行

packages/extensions/tool-cordis/src/index.ts:148-200 的 cordis_define:

1. 校验 name/purpose/idPrefix([a-z]{3,6})
2. precheckCode 沙箱预解析
3. mint pluginId/packageId
4. 写 definition——定义不执行

idPrefix 校验 [a-z]{3,6}:防 agent 乱起 ID,语义前缀让人类在 UI 里能辨认"这是谁家的 plugin"。

5-7. cordis_run / cordis_stop / cordis_undefine

激活、停止、删除——对应动态插件的全生命周期(详见 插件注册机制)。

渐进式发现:Host Provider

packages/extensions/tool-cordis/src/providers.ts:26-65 的 hostInspectProviders(ctx) 注册四个 Host Provider:

• Service.listService
• Event.listEvents
• Builtin.listBuiltins
• Tool.listTools

Service/Event 用"无入参 = 紧凑目录,有入参 = 精确契约"的两步设计。

Host Provider 静态(Service/Event/Builtin 来自生成目录),Client Provider 动态(Slot/Theme 等需页面响应);cordis_inspect_query 对 Client 查询会 pending 直到首个页面回答。

API catalog:文档与工具同源

packages/extensions/tool-cordis/src/api-catalog.ts:83-160 的 SERVICE_API(2156 行)+ EVENT_API(在 L2159):由 gen-cordis-api.ts 生成,每个 entry 含 key/type/methods/source 指针,与 docs/cordis-catalog 文档同 AST walk。packages/extensions/tool-cordis/src/api-catalog.ts:4691-4760 的 queryServiceApi(key?, services=SERVICE_API) 与 queryEventApi(name?, events=EVENT_API):无 key 返回紧凑目录,有 key 返回该 service/event 的结构化契约 + 引用类型闭包。

这意味着拆解站引用 docs/cordis-api/*.md 的签名等价于引用源码——verify-cordis-catalog 是 doc-sync gate。

系统提示词:agent 的工作流与红线

packages/extensions/tool-cordis/src/prompt.ts:3-107 的 CORDIS_SYSTEM_PROMPT 定义:

• 工作流:inspect → query → define → run → stop → undefine
• 身份/版本/授权语义
• Host vs Client 选择
• 高频错误清单:
  • plain JS only,不能用 JSX/TS
  • 不要序列化 live data
  • 每个 side effect 必须可逆

系统提示词禁止"把 Inspect 数据当业务数据缓存":Service/Event/Slot 是 live 对象,JSON.stringify/structuredClone 会爆;只读必要 leaf 字段构造最小 owned 数据。

两步式查询总结

整个设计的核心是"agent 不能猜"——必须先看目录再下钻,这既是对 LLM 幻觉的防御,也是让动态插件可审计的前提。

接下来读什么

• 插件注册机制 — DynamicCordisRegistry 的三层身份
• Web UI 与插件交互 — UI 如何展示这些工具的结果