DSH 插件开发教程

外观

术语表 ​

本教程与 DSH 文档中反复出现的术语速查。按主题分组排列；每条格式为「英文术语 — 一句话中文解释」，涉及的服务附上 ctx 键。术语保留英文原词，中文仅作解释。

框架基础（Cordis） ​

  • Cordis — DSH 底层以 vendor 方式引入的插件框架：插件向共享上下文贡献服务、类型化事件和可逆副作用；产品的每一部分（包括 agent loop 本身）都是插件，因此都可以从配置替换。
  • Plugin — 实现 Service 的对象：带可选 inject 与 apply(ctx) 的函数，或 Service 子类；生命周期由 Cordis 挂载到当前上下文。
  • Context（ctx） — 服务的容器：一个服务占据稳定的 ctx.<key>（如 ctx.tools），插件按 key 查找服务而非导入具体实现；agent.ctx 是限定单个 agent 的作用域化上下文。
  • Service — 插件提供、其他插件经 ctx 消费的具名能力；运行时注册属于 effect，卸载提供方会移除服务，依赖它的插件回到 PENDING。
  • inject — 插件声明的服务依赖列表；Cordis 保持 PENDING 直到所有依赖服务就绪，加载顺序由依赖表达而非手动编排。
  • effect / disposer — 注册是可逆副作用：经 ctx.effect() 或 ctx.on() 安装，并返回 disposer（资源释放函数），reload/teardown 时按预期撤销；disposer 逆序启动，异步 disposer 并发运行。
  • fiber — ctx.plugin() 挂载插件后返回的运行时句柄（已加载插件实例）；状态机 PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED（配置校验失败进 FAILED）；fiber.dispose() 等待全部清理完成后才结束。

事件与分发模式 ​

  • emit — 同步广播分发：监听器按注册顺序观察，不 await、不收集返回值。
  • waterfall — 环绕中间件分发：监听器收 (...args, next)，调 next() 执行下游并拿到下游返回值（可包装），不调用直接返回即短路；只观察的监听器必须委托（agent/pre-step、llm/stream、tools/* 均为 waterfall）。
  • parallel — 并行分发：所有监听器并发观察并一同 await，无返回值。
  • serial — 按序分发：监听器按注册顺序执行，第一个非空返回值胜出并停止后续（如 agent/turn-stopping）。
  • bail — serial 的同步版本，首个非空返回值短路。

架构角色 ​

  • seam — 可替换能力：含 Service Definition（声明接口）、Service Provider（实现）、Consumer（通常是面向模型的工具）三种角色；替换一个提供方即改变整个产品行为（如 ctx.fs、ctx.shell、ctx.subagents）。
  • core — 核心主干服务：只有一份实现、由主干包直接拥有（如 ctx.sessions、ctx.tools、ctx.agents），插件向其注册扩展。
  • bundle — 组合包：Cordis 配置项及其挂载代码的分发格式（dsh.bundle 指向 patch 文件）；ctx.agentLoop 是唯一的具体循环插件，属 bundle。
  • profile — Harness home 中的具名组装：列出叠放的组合包、树外插件与 cordis.patch.yml；web、headless 作为模板随发行版交付。

会话与日志 ​

  • Session — 类型化 SessionEvent 的仅追加日志（ctx.sessions 拥有，唯一真源）；LLM 历史由 deriveMessages() 派生，而非单独存储。
  • SessionEvent — 持久会话事件：type + 单调 seq + epoch time + data（可带 surfaceOp / sourceEventSeqs / ignorable）；观察者经唯一的 session/event 总线事件接收；完整词汇见 persistence-catalog。
  • surface / log-only — surface 事件（仅 user/message、assistant/message、tool/result 三类）产生 LLM 消息；log-only 是可持久化、可回放但不参与派生历史的所有其他事件。
  • Model-visible⟺logged — 运行时不变量：抵达模型请求的一切都必须能从会话日志重建；新增模型可见输入就必须扩展 SessionEventMap 并从日志渲染。
  • turn / step — 一个 step 是一次模型请求加上它调用的工具；一个 turn 包含零或多个 step，在领取首条输入时打开、不再欠工作时关闭；turn/*、step/* 是持久会话事件。
  • claim / pre-step — claim 是驱动器从 inbox 领取下一步骤批次的纯删除操作；agent/pre-step waterfall 决定模型看到什么，可改写或拒绝已领取消息；拒绝或改写为空仍会关闭一个不含 step 的持久轮次。

工具执行与上下文管理 ​

  • tools/pre-execute — 工具执行流水线的策略前处理 waterfall：结合 permission、sandbox 等做 allow/deny/ask 把关，之后进入已注册的单调守卫；配套还有 tools/execute（环绕实际分派）与 tools/post-execute（接受/阻断/替换结果、注入上下文）。
  • 单调守卫（monotonic guard） — 在 tools/pre-execute 后注册的守卫：deny 或 abstain（弃权），身份受保护，deny 即跳过该工具调用。
  • finalizeContent — ToolDefinition 上的最后一个仅内容不变式回调：在流水线规范化后、tools/result 通知前强制执行同步、仅内容的修正。
  • spill — 把过大的工具文本保存到后端（ctx.spillStore，如 spill-local），返回面向模型的定位信息与取回提示；spill-policy 是 tools/post-execute 消费方，决定何时 spill。
  • compaction — 上下文压缩 seam（ctx.compaction，默认后端 compaction-basic）：在步骤压力/请求错误恢复时用摘要替换 surface 节点；compaction/* 是持久事件，替换必须紧跟邻接的 user/message。
  • token-meter — ctx.tokenMeter：按会话隔离、不可变且带修订版本的回放 token 计量；compaction-basic 消费它做压力判断。
  • system-prompt — ctx.systemPrompt：为每个步骤收集提示词片段与面向模型的工具 schema；system-prompt/assemble 是协作式 waterfall。

作用域与诊断 ​

  • scope / ScopeKey — packages/core/scope 库原语（非服务）：按 agent 划分注册可见性与共享生命周期；ScopeKey 是不透明、按对象身份比较的 key（活跃 Agent 对象即 key），agent.ctx 是作用域化上下文。
  • agent preset — ctx.agentPresets：在受信任根与用户创作根发现的 preset 目录；创建期把 preset 的 cordis.yml 挂载到 agent 作用域下，让不同会话拥有不同能力集合。
  • invariant — ctx.invariants：包自有的运行时不变式注册表；fail(message) 抛带包归属的 InvariantError（如 Model-visible⟺logged 由它断言）；配套插件按包注册检查。

委派与自动化 ​

  • subagent — ctx.subagents seam：具名提供方注册表，从新建进程内子 agent（spawn/fork-in-process）到把轮次委派给外部产品（acp、codex、claude-code、dsh-sdk）；tool-subagent 选择一次性或可延续委派。
  • activation — subagents 的可选延续编排机制：可延续 subagent 在后台运行、按需被唤醒接收后续消息（tool-subagent-control 传递消息，tool-ralph 要求全新结构化输出路由）。
  • workflow — ctx.workflowEngine seam（后端 workflow-worker-thread）：JS 脚本编排多个 agent 扇出执行；tool-workflow 是面向模型的入口，ralph 是固定 fresh-agent 循环消费方。
  • ACP — Agent Client Protocol（JSON-RPC stdio 协议）：acp 包既是 subagent 后端（subagent-acp），也为自身 agent 提供审批桥接（approval/request 的回答方）。
  • Typert — 运行时类型注册表（ctx.typert）：插件或 dsh-typert-loader 注册实时 zod schema 贡献；api-gateway 消费调用描述符，Host/Client 经生成的 Remote 描述符做类型化 RPC。
  • client-modules / DSH_BOOT — ctx.clientModules 经增量 dsh.client 扫描组合浏览器插件表，产出注入 window.__DSH_BOOT__ 的入口图；Web 前端插件借此声明并热重载 UI 贡献。

配置、权限与安全 ​

  • settings / credentials — 两个配置 seam：ctx.settings（后端 settings-file）注册命名空间 schema 并解析分层值（默认 → 组合 base → 用户文档），watch + debounce 热提交；ctx.credentials（后端 credentials-local）让配置只携带对机密信息的引用（CredentialRef，绝不含值），提供方按操作解析实际值，轮换后下一次请求即生效。
  • permission preset — ctx.permissionPresets：面向用户的预设表（workspace-write、danger-full-access），把沙箱模式与审批策略组合；一次切换写一个 permission/preset 事件。
  • sandbox — ctx.sandbox seam（后端 sandbox-local）：消费方交出确切 argv，后端按每次调用的策略包装并报告强制执行；ctx.sandboxPolicy 统一保存默认 mode 与工作区根，保证 bash 与 fs 不限制到不同根。
  • approval — ctx.approval seam：一次性权限决策经 approval/request waterfall 分派；回答方是监听器（如 ACP 桥接），无回答方时以 unavailable fail-closed。
  • plan mode — ctx.planMode：仅记日志的 plan/mode 计划协作状态，在轮次边界冲刷用户选择；exit_plan_mode 工具在批准后退出计划模式。
  • goal / schedule — 两个会话内领域：ctx.goals 从会话日志折叠带修订版本的目标状态，create_goal/update_goal 仅人类根权限可 edit/pause/resume，经 agent/* 续跑；schedule 是仅限 Session 内的提醒记录（持久化转换、活动视图、普通对话交付），schedule_create/delete/list 工具。
  • jobs — ctx.jobs seam（后端 jobs-local）：后台 bash、PTY 发送、subagent 委派等生产者登记正在运行的工作；job_kill/job_list/job_output 是面向模型的控制器。