手册/第 08 章
扩展与集成:三层组合 + 20 个扩展点
这一章是操作性的:你要改 dsh,先要判断「改哪一层」,再查「注册点叫什么」。 两件事都有明确答案,不需要读完整棵插件树。
三层:profile → bundle → patch
层序是写死的(architecture.md:25):
profile 的有序 bundle → 该 profile 的 cordis.patch.yml → home patch → --patch 覆盖层。
层的作用对象是空的条目列表——不是修改某个已存在的程序,而是一层层往上叠。
| 层 | 是什么 | 怎么声明 |
|---|---|---|
| profile | Harness home 里的一份具名组合:用哪些 bundle、装哪些树外插件、以及用户自己的 cordis.patch.yml | package.json 的 dsh.profile 列出它的 bundle |
| bundle | Cordis 配置行 + 它挂载的代码的分发格式;插进去之后仍可被上层 patch | package.json 的 dsh.bundle 指向它的 patch 文件 |
| patch | 按行 id 定位并整块替换它的 config,或插入新行;preset 则在某个声明的 config.plugins 内做同样操作 | YAML;--patch 可重复叠加 |
关键推论:bundle 里插进去的东西永远可被上层替换。所以「官方实现」在你的 profile 里不占特殊地位—— 你可以在 patch 里把它的 config 整个换掉,而不用 fork。
看树、改树、装插件
# 打印这台机器实际启动的插件树(每一行都能被 patch 替换) dsh --profile web --dump-config # 只看 schema,不挂载 dsh --profile web --dump-config-schema # 去掉用户层与 --patch 之后的裸树 dsh --profile web --dump-default-config # 临时叠一层 patch 启动 dsh tui --patch ./extra.yml # 往某个 profile 里装插件(转发给该 profile 目录下的 pnpm) dsh plugin --profile tui add <package> # 用出厂模板重置一个坏掉的 profile dsh rescue --from-default-profile web
注意 dsh plugin 的语义:它不是自定义包管理器,而是把参数转发给
profile 目录下的 pnpm(cli-help.md:69–70)。所以插件就是普通的 npm 包,
依赖解析、锁文件、私有 registry 全都沿用生态。
20 个扩展点:目标 → 机制
架构文档的最后一张表(architecture.md:146–167)是 dsh 最实用的一页。
下表把它完整译出——左边是「你想做什么」,右边是「在哪注册」:
| 你想做的事 | 机制 |
|---|---|
| 加一个模型供应商 | 在 ctx.llm 上注册它的 adapter |
| 加一个模型可见能力 | 在 ctx.tools 上注册;它的 schema 会进入 prompt 组装 |
| 给某个会话不同的能力集 | 组合一个 agent preset;其中的服务行需要 isolate realm |
| 加 shell 执行 | 注册 ctx.shell 后端;本地实现经 ctx.subprocess 起进程 |
| 加持久终端执行 | 注册 ctx.terminals 后端 + dsh-tool-terminal |
| 加一个人工命令 | 在 ctx.commands 注册;它不经过模型 turn 直接派发 |
| 管后台任务 | 在 ctx.jobs 注册;job_* 工具负责读/停 |
| 从外部 webhook 起一个会话 | 在 ctx.webhookRuntime 注册可信规则并挂一个 provider adapter |
| 加文件系统访问或策略 | 注册 ctx.fs provider,或监听 fs/* 事件 |
| 约束生成的进程 | 用 ctx.sandbox 后端;消费方在 spawn 前包装 argv |
| 拦截请求 / 工具 / turn | 用对应的 agent/* 或 tools/* 事件;agent/turn-stopping 可停 turn |
| 加模型可见上下文 | 调 agent.inject();它落在下一次被准入的请求里 |
| 加 UI 或编辑器集成 | 驱动 ctx.agents,从 session/event 渲染 |
| 加一个 Web 聊天节点 | 注册 ConversationNodeDefinition + 带 key 的 renderer |
| 加持久会话状态 | 扩展 SessionEventMap;从日志渲染与重放 |
| 生成会话标题 | 注册唯一的 ctx.sessionTitle provider |
| 管理同会话内的目标 | 用 ctx.goals;经 agent/* 续跑 |
| 在 turn 边界分叉 | ctx.agents.create({ sessionId, seed, inheritedEventCount, meta: { isSeeded: true } });只有 agent-loop 发布的会话会持久化 |
| 把会话存到新后端 | 实现 SessionPersistence(create/open/stat/list/export),复用共享的 handle 脚手架 |
| 把注册限定到某一个 agent | 用那个 agent 的 agent.ctx |
ctx.* 或事件名。
如果找不到接近的行,通常意味着你该做的是一个新 seam(定义 + 提供者 + 消费方),
而不是硬塞进已有的某一层。
集成的三条外部通道
inject: ['tools'] 的普通插件。
MCP 工具命名 mcp__<serverName>__<rawName>,走同一道执行管线。
sdk profile 里的 dsh-sdk-app 提供 JSON-RPC 服务端;
仓库还带 python/sdk,非 Node 调用方走这条路。
acp profile 的 dsh-acp-app 是「只做自动化」的服务端——
同一份内核的第四种外壳。
architecture.md:25 · 层序 architecture.md:146 · 20 个扩展点 cli-help.md:41 · --patch