DeepSeek Harness 学习手册 第 08 / 11 章 总目录 单页全本 架构图 GitHub

手册/第 08 章

08

扩展与集成:三层组合 + 20 个扩展点

这一章是操作性的:你要改 dsh,先要判断「改哪一层」,再查「注册点叫什么」。 两件事都有明确答案,不需要读完整棵插件树。

三层:profile → bundle → patch

层序是写死的(architecture.md:25): profile 的有序 bundle → 该 profile 的 cordis.patch.yml → home patch → --patch 覆盖层。 层的作用对象是空的条目列表——不是修改某个已存在的程序,而是一层层往上叠。

层是什么怎么声明
profileHarness home 里的一份具名组合:用哪些 bundle、装哪些树外插件、以及用户自己的 cordis.patch.ymlpackage.json 的 dsh.profile 列出它的 bundle
bundleCordis 配置行 + 它挂载的代码的分发格式;插进去之后仍可被上层 patchpackage.json 的 dsh.bundle 指向它的 patch 文件
patch按行 id 定位并整块替换它的 config,或插入新行;preset 则在某个声明的 config.plugins 内做同样操作YAML;--patch 可重复叠加

关键推论:bundle 里插进去的东西永远可被上层替换。所以「官方实现」在你的 profile 里不占特殊地位—— 你可以在 patch 里把它的 config 整个换掉,而不用 fork。

看树、改树、装插件

sh · docs/cli-help.md
# 打印这台机器实际启动的插件树(每一行都能被 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(定义 + 提供者 + 消费方), 而不是硬塞进已有的某一层。

集成的三条外部通道

MMCP
不是特殊协议层,而是一个 inject: ['tools'] 的普通插件。 MCP 工具命名 mcp__<serverName>__<rawName>,走同一道执行管线。
SSDK(JSON-RPC)
sdk profile 里的 dsh-sdk-app 提供 JSON-RPC 服务端; 仓库还带 python/sdk,非 Node 调用方走这条路。
AACP
acp profile 的 dsh-acp-app 是「只做自动化」的服务端—— 同一份内核的第四种外壳。

architecture.md:25 · 层序 architecture.md:146 · 20 个扩展点 cli-help.md:41 · --patch

本章学习记录

记录仅保存在当前浏览器。