「一切皆插件」DeepSeek Harness 技术调研:产品形态、插件架构与安全边界
AI 参与说明(Agent:Codex):本文由 Codex 使用 Context7 检索官方文档,结合固定版本源码、Cordis 运行实验与 Anatomy 交互图解整理,并使用项目 humanizer-zh 编辑中文正文。执行入口为 Codex Desktop;完整模型标识、reasoning effort 与运行时版本未取得可核验的任务级记录。
DeepWiki:deepseek-ai/deepseek-harness
修订说明(2026-10-28,Agent:Cursor):站点已撤下 tool-web 的 Anatomy 交互图(tcitry.github.io #319)。正文去掉只为该图存在的引导、
DeepSeekPluginFigure引用和空锚点#plugin-lifecycle;Cordis 服务退出与 provider 退出的说明、状态图和其他 Mermaid 保留。模型grok-4.7-high-fast,提供方 xAI,执行入口 Cursor Cloud。reasoning effort 未作为独立字段取得运行记录。
合并说明(2026-11-12,Agent:OpenBot):本文并入原 CLI 目录的《DeepSeek Harness(dsh):插件化 Agent Harness 的产品形态与运行原理》,只保留这一篇。两文基线不同:机制部分以
22ddee37(2026-10-27)为准,“产品形态”与“安全边界”两节来自 2026-08-21 对528c682的阅读,除安装命令与默认监听地址外未对22ddee37逐条复核。原 URL/docs/AI/CLI/deepseek-harness-dsh-plugin-agent-architecture/已 301 到本文。
DeepSeek Harness(命令名 dsh)将 Agent Loop、模型适配、工具注册、Session、权限策略和 Web UI 都纳入同一套插件组合机制。“一切皆插件”的实质,是让产品的主要能力共享依赖声明、生命周期和扩展契约。工具插件只是其中一种消费者;驱动 Agent 的默认循环本身也可以被替换。架构说明
本文机制部分以 2026-10-27 取得的提交 22ddee379240 为准。根包版本是 0.2.1-rc.3,vendored Cordis 为 4.0.5;项目仍处于 developer preview,接口会发生不兼容变更。官网展示产品体验,以下机制结论以该提交的代码为依据。版本信息、Cordis 版本
| 英文术语 | 中文名称 | 简要解释 |
|---|---|---|
| Harness | Harness,智能体运行框架 | 管理模型调用之外的工具、上下文、会话、权限与界面 |
| Plugin | 插件 | 由运行时加载、拥有独立生命周期的一段能力实现 |
| Context | 上下文 | 插件获取服务、注册行为和持有资源的入口,即 ctx |
| Service | 服务 | 以稳定名称提供的能力,例如 ctx.tools、ctx.web |
| Fiber | 插件运行实例 | 同一插件每次挂载所创建的实例,记录状态、依赖与清理函数 |
| Effect | 副作用 | 注册工具、监听事件或打开连接等对环境的改变;这里强调可清理 |
| Capability Seam | 能力接缝 | Service Definition、Service Provider 与 Consumer 之间的替换边界 |
| Profile / Bundle | 配置档 / 组合包 | Profile 选择要运行的应用组合;Bundle 分发插件配置与代码 |
| Typed Event | 类型化事件 | 服务声明的事件契约,按 emit、waterfall、parallel、serial 分派 |
| HMR | 热模块替换 | 在允许的范围内卸载旧模块并加载新模块 |
产品形态:本地 Agent runtime,而非单一聊天产品
DeepSeek Harness(命令名 dsh)是 DeepSeek 开源的 Agent Harness:它不提供模型,也不是托管服务,而是把模型、会话、工具、权限、沙箱、Subagent 和宿主界面组装起来的本地 Agent runtime。官方 README 把它定义为由 Cordis 驱动的开源 Agent Harness,核心用户是希望深度改变 Agent 行为的开发者和团队——不只配置一个模型,还可以替换工具注册、持久化、文件系统、shell、审批策略和 UI。
dsh web 启动的 Web UI 只是其中一种产品入口。同一运行时还有 headless profile、Python SDK 与 ACP 入口;它们共享 dsh-base、Agent loop 与 Session 组件,是同一套能力的组装差异,而不是几套互不相干的 Agent 实现。
| 入口 | 作用 | 运行边界 |
|---|---|---|
dsh web | 本地 Web UI,选择 workspace 后与 Agent 对话 | 默认只监听 loopback;Agent 可在获准范围内操作该 workspace。 |
headless profile | 一次性或自动化运行 | 不带 HTTP server,适合脚本与编排入口。 |
| Python SDK | 将 dsh runtime 嵌入 Python 程序 | 由宿主明确选择 profile、工具与权限组合。 |
| plugin / bundle | 扩展模型、工具、MCP、subagent、workflow 或产品 UI | 插件代码与被调用的 MCP server 都在本机信任边界内。 |
这也解释了它为什么必须与 Cloudflare OS 分开讨论:Cloudflare OS 是带身份、协作、应用实例和 capability security 的公司级工作区产品;dsh 的核心产物是一个可替换部件很多的 Agent runtime。两者都会“让模型调用工具”,但部署边界、抽象层与安全责任不同。
与 Pi Coding Agent 入门与社区玩法 这类“开箱即可在终端完成编码任务”的工具相比,dsh 更强调构造 Agent 本身:只需稳定、轻量的编码交互时,它的配置面与 Preview 风险可能超过收益;要把 Agent 做成自有产品、内部工作台或高度定制的自动化系统时,它的拆分方式才更有价值。README
从功能到代码:哪些东西成为了插件
The agent loop is a plugin, and the public Agent contract is separate from its default implementation. 扩展插件依赖 dsh-agent 的接口与事件;默认实现位于 dsh-agent-loop。这是判断插件化深度最直接的证据:能替换的范围包括执行任务的驱动层。Core 说明
| 能力 | 主要代码入口,均相对于仓库根目录 | 组合方式 |
|---|---|---|
| Agent API 与默认循环 | packages/core/agent、packages/core/agent-loop | ctx.agents 提供公共入口,ctx.agentLoop 安装默认实现 |
| 模型调用与流式响应 | packages/llm/llm、packages/llm/llm-deepseek | 向 ctx.llm 注册 adapter,Loop 通过共同接口调用 |
| 工具 schema 与执行 | packages/core/tools、各组 tool-* 包 | 向 ctx.tools 注册定义,执行经共享 pipeline |
| Shell 与运行环境 | packages/shell、packages/subprocess、packages/fs、packages/ssh | 消费能力接口,按组合选择本地或远端实现 |
| Session 与持久化 | packages/core/session、packages/session/session-persistence* | 内存日志与落盘 backend 分开 |
| System Prompt 与上下文 | packages/core/system-prompt、packages/context、packages/compaction | 注册 section、运行时事实及压缩策略 |
| Skill、MCP 与 Subagent | packages/skill、packages/mcp、packages/subagent | 各有服务与面向模型的工具;接入共同注册和执行机制 |
| 权限与人工交互 | packages/sandbox、packages/interaction、packages/guard | 在工具、文件或进程的扩展点施加规则 |
| Web UI | packages/client/modules、packages/client/ui-slots、packages/client/ui-renderer | Host 发布模块图,Client 组合服务与 Slot |
| 启动与插件管理 | packages/boot/app-boot、packages/boot/plugin-manager、packages/bundle | Profile、配置 patch、安装管理及重载 |
这张表描述职责入口,不表示每个包都提供一个 ctx key。例如 core/scope 是不注册 Service 的底层库,Bundle 的主体可以是配置文件。项目把产品能力组织成插件,也保留普通类型、纯函数、协议和构建工具。包组织、Architecture
架构基础:一个 Context 同时管理依赖与资源
Cordis 解决两个方向的问题:一个插件需要哪些环境条件,以及它退出后怎样清理自己留下的东西。前者决定能否运行,后者决定能否安全替换。论文分别称为 spatial composability 与 temporal composability,并以 reactive coeffects 和 revertible effects 描述其运行机制。这里采用论文的概念解释实现,不将形式化结论外推为任意第三方插件都能正确回滚。Cordis 论文
flowchart TB
P["Profile + Bundle + patches"] --> L["Loader:配置成为 Plugin tree"]
L --> F["Fiber:一个 Plugin 的运行实例"]
F --> C["Context"]
C --> D["inject:需要哪些 Service"]
C --> E["Effect:拥有何种注册与资源"]
D --> R["Reflect:按隔离标识解析 Service"]
R --> A["依赖满足才执行 apply"]
A --> E
E --> U["卸载时调用 disposer"]
U --> R
上图是机制关系图,表示加载、依赖解析与资源回收之间的联系;不表示每条边都是异步函数调用。对应底层实现是 Context、RegistryService、ReflectService、Fiber 和 EventsService。Context、Registry
Plugin、Service 与 Fiber 分别是什么
一个 Plugin 可以是接收 (ctx, config) 的函数、带 apply() 的对象,或可构造的类。ctx.plugin(plugin, config) 将这些形式标准化并创建 Fiber。同一段插件代码可以挂载多次,每次都有自己的配置、状态和生命周期。Service 子类也是一种 Plugin;super(ctx, 'name') 让它在 Context 中占据一个稳定名称。Plugin 类型、Service
以 ctx.web 为例,消费者只要求这个名字所代表的接口。TypeScript 的 declaration merging 让 ctx.web 获得静态类型;真正的运行时注册由 provide() 或 Service 构造完成。类型声明本身不会加载插件,也不会创建依赖。Services 教程
inject 是持续有效的条件
Required service dependencies remain reactive after startup. inject 并非启动时查一次的清单:依赖发生变化后,运行时会重新判断 consumer 是否还能保持激活。Services 教程
源码中的关键步骤是:
ReflectService.provide()保存带有name、value和提供方fiber的记录;服务可用性发生变化时调用notify()。- 依赖方的
Fiber._checkImpl()重新解析需要的实现;_refresh()用依赖提供方的fiber.uid形成 epoch。 - 任一依赖缺失时,epoch 成为 inactive;即使名称相同,提供方 Fiber 变了也会使 epoch 改变。
_setEpoch()据此安排卸载或加载;重新加载时,apply()取得当前依赖,旧的注册先完成回收。
因此,配置中的行顺序不需要承担所有启动排序。consumer 写在 provider 前面时,可以先停在 PENDING,待服务可用再加载;循环依赖或缺失配置也可能让它一直等待,需要用诊断定位。Reflect 源码、Fiber 源码
Effect 把“注册”变成可撤销的操作
ctx.on() 注册监听器,ctx.plugin() 挂载子插件,ctx.provide() 提供服务,Harness 的 ctx.tools.register() 注册工具,都把清理责任归到调用方生命周期。插件卸载后,这些注册随之移除。自行创建的 timer、连接或 watcher 则要用 ctx.effect() 返回 disposer,运行时无法替插件猜出如何关闭它们。生命周期教程、ToolsService.register
这里撤销的是运行环境中的注册与资源持有关系。插件已经发出的邮件、写入的业务数据或完成的网络操作,不会因为卸载而自动恢复原状。需要补偿的外部操作必须另行设计。
清理顺序也有边界:Fiber 卸载会等待异步清理,但多个独立 disposer 可并发运行;同一个 ctx.effect() 内收集的清理按逆序串接。若必须先停生产者、再排空队列、最后关连接,应在一个 disposer 内明确 await 这个顺序。Fiber.effect 与 _unload
dsh、Cordis 与 Pi:分层复用,而不是二选一
没有找到 DeepSeek 公开说明“因为 Pi 的某项缺陷,所以选择 Cordis”的决策记录,因此以下几点是基于源码结构的架构推断,不是官方选型声明。可证实的事实是:dsh 没有把完整 Pi Coding Agent 或 pi-agent-core 当作自己的 runtime,@deepseek-ai/dsh-llm-pi-ai 只依赖 @earendil-works/pi-ai,把它当作多 Provider 的 LLM adapter 复用 provider catalog、wire protocol 与流式请求;Agent loop、Session、tools、sandbox 与 profile 组合仍由 dsh + Cordis 承担。dsh pi-ai adapter、adapter 依赖
Cordis(dsh 的组合、依赖与生命周期框架)
└─ dsh plugins(Agent loop、session、tools、sandbox、profile)
└─ dsh-llm-pi-ai(可选 LLM adapter)
└─ pi-ai(Provider catalog、协议与 streaming)
由此得到的合理推断是:dsh 要把模型 adapter、工具、持久化、sandbox、subagent 与各入口重组成不同 profile,因此更需要 Cordis 的 service seam、依赖重算和可撤销 effect;而跨 Provider 的协议与 catalog 适配已由 pi-ai 解决,复用它可以避免重复维护同一层。Cordis 解决“运行时怎么组合与演进”,Pi 解决“模型请求怎样跨 Provider 传输”,两者不在同一层争同一职责。Pi 本身也不是单一抽象:pi-coding-agent 是面向终端用户的 Coding Agent,pi-agent-core 提供 Agent loop 与 state,pi-ai 才是统一 Provider API,所以“dsh 不使用完整 Pi”不等于 Pi 缺少扩展能力。Pi package overview、Pi agent core
服务退出与 provider 退出为何不同
真实的 tool-web 插件声明 inject = ['tools', 'web', 'systemPrompt'],按配置注册 web_search、web_fetch。下面假设两个工具都启用,另外两个 Service 持续可用。tool-web 源码
“移除 ctx.web”让 consumer 缺少必需 Service,清理完成后两个工具定义退出 registry。“只移除 HTTP provider”保留 ctx.web,工具插件继续运行,工具定义也保留;调用 web_fetch 时会因选中的 provider 不可用而失败。这两种变化不是同一种卸载。web-fetch-http、Web 能力
一个需要以源码校正文档的状态细节
当前用户文档将依赖丢失概括为 ACTIVE → DISPOSED。但固定版本源码的 _getState() 在 uid 未清空、epoch 已 inactive 时返回 PENDING。本次实验确认:移除 provider 后 consumer 保留同一个 uid,清理资源并回到 PENDING;新的 provider 出现后,这个 consumer 再次加载。显式调用 consumer 的 dispose() 才清空它的运行身份并进入 DISPOSED,之后不会因服务重现自行恢复。用户文档、源码
stateDiagram-v2
[*] --> PENDING
PENDING --> LOADING: 必需 Service 齐全
LOADING --> ACTIVE: apply 完成
LOADING --> FAILED: 配置或 apply 失败
ACTIVE --> UNLOADING: 必需 Service 丢失或改变
UNLOADING --> PENDING: 依赖仍缺失且实例保留
UNLOADING --> LOADING: 新依赖已就绪
ACTIVE --> UNLOADING: 显式 dispose
UNLOADING --> DISPOSED: 显式移除并清理完成
这张图突出两种卸载原因,不穷举失败、加载竞争和父插件退出的所有转移。排障时要同时观察 Fiber 状态、实例身份与实际注册,不能只看插件配置是否还存在。
Capability Seam:接口、实现和模型工具分开
以网页访问为例,dsh-web 提供 Service Definition 与 provider registry;dsh-web-fetch-http 注册 HTTP fetch 实现;dsh-tool-web 作为 Consumer 定义模型能看到的名称、参数和输出。替换 HTTP 实现时,模型仍可使用同一个 web_fetch 工具接口。Web subsystem
flowchart TB
T["Consumer: dsh-tool-web<br/>web_search / web_fetch"] --> W["Service Definition: dsh-web<br/>ctx.web"]
H["Service Provider: web-fetch-http"] -->|注册 fetch 实现| W
S["Service Provider: web-search-deepseek"] -->|注册 search 实现| W
W -->|按配置选择实现| H
W -->|按配置选择实现| S
图中 provider 的注册与调用方向相反:启动时向 registry 提供实现,执行时由 Service 选择实现。它们都是 Plugin,但不全都各占一个 Service 名称。ctx.llm 的 adapter registry 也有类似分层;因此“换 provider”既可能是替换整个 Service 实现,也可能只是修改同一 Service 内注册的一项能力,应按具体接口判断。Capability 定义、LLM streaming
这种拆分把模型协议、基础能力和具体环境分开。以 Shell 为例,Bash 工具不应直接决定在本地 spawn() 还是通过 SSH 执行;filesystem 与 subprocess 必须指向一致的执行环境,才能让 Bash、PTY 和 LSP 对同一套文件工作。替换边界成立的前提是各实现遵守共同契约。Architecture
一次请求如何穿过这些插件
假设用户要求获取一个网页,模型决定调用 web_fetch。默认实现中的主要数据对象包括:
| 对象 | 关键含义 | 代码位置 |
|---|---|---|
Agent | 活跃运行句柄、输入队列、状态与所属 ctx | packages/core/agent |
Session / SessionEvent | 模型历史的事实来源,记录 turn、message、tool 等事件 | packages/core/session |
Message / ContentBlock | user、assistant、tool-call 等模型交互内容 | packages/llm/llm |
PreparedLlmCall | 绑定选定 adapter 及本次调用能力 | packages/llm/llm |
ToolDefinition | 参数、执行函数、输出 schema 与渲染规则 | packages/core/tools/src/contracts.ts |
ScopeKey | 用对象身份区分某个 Agent 的注册范围 | packages/core/scope |
实际主线是 ReactLoopAgent 的 step 准备与执行,以及它对 ctx.tools.execute() 的调用。下图省略重试、压缩和取消分支,但保留模型上下文、工具执行与日志之间的先后关系。Agent 实现、Core 文档
sequenceDiagram
participant A as Agent Loop
participant P as System Prompt
participant L as LLM adapter
participant T as Tool executor
participant W as Web Service
participant S as Session
A->>S: 打开 turn,领取输入
A->>P: 组装 prompt sections 与本 step 工具
A->>A: agent/pre-step 决定是否接纳输入
A->>L: agent/request 后 prepareCall
A->>S: 协调 system/message,提交 user/message 和 request 信息
A->>L: 从日志导出历史,stream 已绑定的请求
L-->>A: assistant 内容与 tool-call
A->>S: 提交 assistant/message
A->>T: ctx.tools.execute
T->>S: tool/call
T->>T: pre-execute → guards → execute
T->>W: web_fetch 的执行函数调用 ctx.web
W-->>T: 选定 provider 返回结果
T->>T: 输出投影、post-execute、最终整理
T->>S: tool/result
A->>S: 后续 step 从日志导出包含结果的新历史
一次 turn 可以包含零个或多个 step;一个 step 就是一次模型请求及其产生的工具调用。agent/pre-step 决定是否接纳本轮输入,agent/request 进入 llm/stream,工具调用先记录 tool/call、再经过策略与守卫,完成后写入一个对模型可见的 tool/result;只有 inbox 或工具结果仍欠下一次模型请求时,才继续下一个 step。默认的 JSONL + Zstd 持久化把 session 写在 $DSH_HOME/sessions,这提供了崩溃恢复与可重放性,同时也意味着 session 文件本身要按敏感本地数据处理——它可能包含任务输入、工具结果、路径与模型可见上下文。Session persistence
Model-visible information must be reconstructable from the Session log. Loop 从日志派生模型请求;插件新增模型可见信息也要有对应的 Session 事实。持久化让换 UI、恢复会话、导出轨迹时仍能读取共同记录,但这不等于重放日志会重新执行已经完成的外部工具。Session 设计
插件可以在 agent/pre-step 改变输入接纳,在工具 pipeline 施加权限或结果处理,在 llm/stream 接入模型传输。扩展沿明确的契约进入,避免每个新功能都修改 ReactLoopAgent。agent/request 在此版本已标为 deprecated,适合了解历史链路,新扩展要按当前公开接口选择切入点。Turn flow
Events 不只负责通知,也承载控制流
Cordis 的 waterfall 是带 next() 的 around middleware。一个监听器可以先做工作、await next()、再处理返回值;有权作决定的监听器也可以不调用 next(),直接短路。忘记调用 next() 会让下游根本没有执行。Waterfall 语义
工具 pipeline 的顺序是 tools/pre-execute、monotonic guards、tools/execute、tools/post-execute,输出投影与最终结果整理也各有位置。权限检查并不只依赖一个可随意替换的监听器:guards 在 pre-execute 之后约束执行,具体文件修改和进程运行还有各自的能力边界。Tool pipeline
其他 dispatch mode 也有明确语义:emit 同步广播且不等待返回的 Promise;parallel 等待并行监听器;serial 依序等待并在首个有效返回值处停止;bail 是同步的短路分派。不能把 serial 理解为保证执行所有异步监听器。Events 源码
多 Agent 如何避免注册互相污染
这里有两种不同的范围机制。
ctx.isolate('name') 给某个 Service 名称建立新的解析标识,使不同子树可以分别提供同名 Service。Context 以原型继承元信息,服务查找再按 isolation label 解析。同一个 label 可以让两处配置共享服务范围。Context.isolate
Harness 的 ScopeKey 则用于同一个 registry 内的按 Agent 注册。默认 Loop 用活跃 Agent 对象作为 scope key;通过 agent.ctx 注册的工具只在对应范围可见,并可遮蔽同名全局工具。全局与同层重复名称会受检查,局部注册退出后不会删除另一个 Agent 的同名注册。Scope、Tools registry
另一个容易混淆的 API 是 ctx.intercept(name, config):它建立带有 Service 专属配置的子 Context,由 Service 的配置合并机制读取。它不等于拦截所有方法调用;实际请求和工具执行的控制流由前文的 Events 与 waterfall 承担。Context.intercept、Service 配置合并
前者分开 Service 的实例解析,后者分开 registry 的贡献与生命周期。它们都不是操作系统沙箱:拥有 Node.js 执行能力的插件仍需受信任,文件和进程的安全性依赖实际采用的 sandbox 与权限方案。Safety notice
Web UI 也通过插件组合
Host 与浏览器各有自己的 Context,跨两端靠模块图、Remote 接口和事件通信。Client 不是直接持有 Node.js 端的同一个 ctx 对象。Web Client architecture
Host 的 ctx.clientModules 生成 Client 模块图;页面 boot 时取得插件入口和共享依赖信息。执行 bundle 首先注册 factory,模块主体在 materialization 时执行,结果进入缓存;CSS 等副作用也跟随模块的生命周期。开启或关闭插件后,页面跟随 Host 模块图更新相应 Loader entry,并等待异步清理。Client modules
UI 组合由 ctx.slots 承担。插件向声明过的 Slot 注册组件,父级只获得其声明范围内的渲染权限;注销入口时,子 Slot、贡献与 Store mount 一并退出。ui-renderer 把这套 React-free 的对象层连接到 React,是统一的渲染适配层。ui-slots、ui-renderer
因此,一个插件可以同时贡献模型工具、后端服务、设置界面和对话展示。官网“创造模式”里的番茄时钟展示了对话生成插件代码、安装 Bundle 和扩展界面的产品入口;架构上的依据则是这些具体注册点。官网演示
前端重载也有版本边界:页面同时核对 Host release 的 version 与 commit;Host 换成另一个 release 时,当前页面暂停应用它的新模块图,保留旧插件,等待整页刷新加载另一 release。不能把开发时局部 HMR 说成任意跨版本的无感升级。Client modules:Host release changes
Profile、Bundle 和 HMR 如何连接安装与运行
安装包、选择组合、运行激活是不同阶段。Profile 是 Harness home 中的命名应用组合;Bundle 用 package.json 的 dsh.bundle 声明配置 patch 与代码。启动时从空列表开始,依次应用 Profile 选中的 Bundle、Profile patch、home patch,最后应用命令行 --patch。Profiles and bundles
启动时的组合按固定顺序叠加,后层可以按 id 替换或插入条目:
profile 指定的 bundles
→ profile 自己的 cordis.patch.yml
→ Harness home 的 patch
→ 命令行 --patch overlay
因此“默认行为”必须理解为当前 profile + 当前 patch 的结果,而不是某个包单独的默认值。想确认机器实际会启动什么,用只读命令查看生效配置树:
dsh --profile web --dump-config
web、headless、sdk、acp 共享 dsh-base,再叠加各自入口;sdk-minimal 用独立 Bundle 声明完整树。这个例外说明“默认产品组合”也可被绕开选择另一套支持的组合,但应用仍通过统一 dsh launcher 启动。sdk-minimal 配置
HMR 由插件及配置决定。该版本 base 默认打开 config-only HMR,headless、SDK 和 ACP 默认关闭,sdk-minimal 不包含它。源码变化能否热替换,还取决于模块是否处于 Loader 管理的依赖图以及是否进入 Host 的静态导入图。Architecture、HMR API
实际更新大致经过:解析新的 Profile 组合、比较模块、停止受影响的 Loader entry、发布新的解析结果、重新导入并激活 entry。runExclusive() 将自动重载和插件管理变更串接,防止同时替换同一组合。无法安全替换的模块会报告 restart reason;替换插件启动失败时也可能留下 inactive entry,而不是自动恢复旧代码。HMR.reconcileProfile
排障时分别看三件事:包是否安装、组合中是否启用、Fiber 是否 ACTIVE。Plugin Manager 的 changed 只表示磁盘编辑,application 还会区分 applied、restart-required、overridden 和 failed,不能把一次安装成功等同于能力已经生效。Profile management
安全边界:有 sandbox,不等于可以把任何内容当作安全
最容易误读 dsh 的地方是 permissions / sandbox 这几个词。以官方 shipped base profile 为准,默认权限预设是 workspace-write + ask:可以在 workspace 写入,但需要审批;可选预设还有 read-only、workspace-write 和 danger-full-access,后者会把 approval 变为 never,不应作为日常默认值。Base profile 权限配置
以下几条边界要一起记住:
- sandbox 主要约束文件效果,不约束网络访问或进程可见性。 Linux 优先 bwrap,其次 Landlock;macOS 使用仍可用但已废弃的
sandbox-exec;Windows 使用 restricted-token ACL。缺少可用 runner 时应 fail closed,但 Windows ACL 与旧版 Landlock 仍可能只有 partial enforcement。Sandbox subsystem - 默认 Web UI 不应暴露到局域网。
dsh web默认绑定127.0.0.1:3080,shipped CLI 会拒绝--host 0.0.0.0,因为那会把能执行 workspace 工具的控制面放到网络上。通用 web-server 组件本身不提供 TLS、认证或 origin policy;若绕过该限制,必须自己补网络层防护。Web app 安全边界、Web server - 第三方 plugin 和 MCP server 是可信本机代码。
dsh plugin … add会通过 pnpm 安装 tree 外的 bundle;MCP client 随附但默认不启用任何 server,因为每个 server command 都在 Agent sandbox 之外执行。审查它们的源码、依赖与权限,不能套用文件 sandbox 的安全承诺。CLI reference - telemetry 默认本地且关闭。 主动设置
DSH_TELEMETRY_MODE=FULL或FEEDBACK_ONLY后,OTLP 导出内容可能包含消息文本、tool arguments/results 与 workspace 路径;base 组合默认没有 redaction 规则。启用前先做数据分类与脱敏验证。Telemetry 说明 - Provider credential 按同一边界处理。 UI 里的 API key 是 write-only,凭据存于
$DSH_HOME/.credentials.yaml,settings 只保存引用;为自定义 endpoint 配置认证时优先用apiKeyEnv,不要在 route 的headers里明文硬编码Authorization。Provider credential 指引
这一节与“产品形态”同源,来自 2026-08-21 对 528c682 的阅读,没有对 22ddee37 逐条复核。
最小试用与选型判断
下面是官方 quick start。本文没有在本机执行该安装命令,运行时下载到的实际 npm 版本以当时 tag 为准;两个基线提交的 README 在这一点上一致。22ddee37 README、528c682 README
# 前提:已安装 Node.js
npx @deepseek-ai/dsh web
预期是在本机启动 Web UI 并打开 http://127.0.0.1:3080。第一次试用应选择没有敏感信息的 disposable workspace,保留默认 loopback 与 approval,不要急于添加第三方 plugin、MCP server 或 danger-full-access。从源码运行时,官方路径是 pnpm install、pnpm run build,再执行 pnpm dsh web。
| 目标 | 判断 |
|---|---|
| 构造可替换模型、工具、sandbox、subagent 与工作流的自有 Agent 产品 | plugin tree、typed events 与 service seams 适合深入定制。 |
| 只需要一个稳定的本地编码助手 | 应先评估 Pi Coding Agent 入门与社区玩法 这类更成品化的工具;Developer Preview 与配置面是实际成本。 |
| 把本地 Web UI 直接发布给团队使用 | 不适合只改 host;必须另行解决 TLS、身份认证、网络隔离、共享 storage 与审计。 |
| 需要一个保证隔离所有网络与本机进程的执行沙箱 | 默认 sandbox 不足以单独承担该承诺,需要额外的容器、VM 或受控远程执行设计。 |
最小实验:直接验证服务替换与资源回收
下面是 Cordis 运行时实验,不调用模型,也不启动 Harness 应用。代码用一个 Set 模拟 registry,验证 consumer 失去依赖后清理资源、保留 Fiber,并在新 provider 出现后重新注册。真实工具 registry 用同样的生命周期机制,但其 schema、执行和 scope 规则未在此模拟。
为避免构建整个 monorepo,可在固定提交根目录保存下列两个文件;环境需要 Node.js 24.9+。临时安装的 esbuild 只用于把该提交的 TypeScript 源码打成可执行 ESM,不修改仓库依赖。
// lifecycle-smoke.ts
import {Context, FiberState} from './vendor/cordis/src/index.ts';
import assert from 'node:assert/strict';
const root = new Context();
const live = new Set();
const trace = [];
const provider = version => ({
name: 'provider-' + version,
apply(ctx) { ctx.provide('researchService', {version}); },
});
const consumer = root.plugin({
name: 'consumer', inject: ['researchService'],
apply(ctx) {
const version = ctx.researchService.version;
ctx.effect(() => {
live.add(version); trace.push('load:' + version);
return () => {live.delete(version); trace.push('clean:' + version);};
});
},
});
await consumer;
assert.equal(consumer.state, FiberState.PENDING);
const a = await root.plugin(provider('A'));
await consumer.await();
assert.deepEqual([...live], ['A']);
const uid = consumer.uid;
await a.dispose(); await consumer.await();
assert.equal(consumer.state, FiberState.PENDING);
assert.equal(consumer.uid, uid);
assert.equal(live.size, 0);
const b = await root.plugin(provider('B'));
await consumer.await();
assert.deepEqual([...live], ['B']);
await consumer.dispose();
assert.equal(consumer.state, FiberState.DISPOSED);
assert.equal(live.size, 0);
await b.dispose();
await root.fiber.dispose();
console.log(trace);
// build-smoke.mjs
import {build} from 'esbuild';
import {resolve} from 'node:path';
await build({
entryPoints: ['lifecycle-smoke.ts'],
bundle: true, platform: 'node', format: 'esm',
outfile: 'lifecycle-smoke.mjs',
alias: {
'@deepseek-ai/cosmokit': resolve('vendor/cosmokit/src/index.ts'),
},
});
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout 22ddee3792402c3e70ec5f86a63c3e3e895a2f60
# 在这里保存上面的两个文件,再执行:
npm install --prefix /tmp/dsh-research-build --no-save esbuild@0.28.2
# 将构建脚本复制到临时工具目录,让其解析到该目录的 esbuild;cwd 仍为仓库根目录。
cp build-smoke.mjs /tmp/dsh-research-build/build-smoke.mjs
node /tmp/dsh-research-build/build-smoke.mjs
node lifecycle-smoke.mjs
本次使用已有 esbuild 0.28.2 对同一固定源码构建并运行上述生命周期代码,得到:
load:A → clean:A → load:B → clean:B
依赖消失:PENDING;consumer uid 不变;registry 为空
显式 dispose:DISPOSED;registry 为空
另外两项运行实验也通过:两个 isolate('researchService') 子树能持有不同实现,移除 A 不影响 B;waterfall 的外层包装会在 next() 返回后执行,而短路分支不会执行底层函数。这些结果验证插件运行机制,不构成完整桌面应用或真实模型调用的验收。
设计取舍与可借鉴的做法
“一切皆插件”最有价值的部分,是把替换能力所需的几项约束一并设计出来:稳定接口决定替换什么,reactive dependencies 决定何时能运行,Effect ownership 决定退出时清理什么,Session 契约决定换实现后还保留哪些事实。缺少其中一环,插件就容易退化为可以加载、难以移除的模块集合。
这套设计也增加了运行时排障成本。能力缺失可能来自未安装、配置被上层覆盖、服务依赖未满足、provider 尚未可用、scope 过滤或 Client 模块同步失败,单看 import graph 很难定位。官方 Inspector、Fiber 状态、有效配置和 Session trace 因此是架构可用性的一部分。Profile management、Client modules
若要在自己的 Harness 中采用类似方案,可以按以下顺序验证边界:
| 场景 | 具体操作 | 验收依据 |
|---|---|---|
| 替换执行环境 | 先抽出 filesystem 与 subprocess 接口,再接入第二个实现 | 同一工具 Consumer 无改动即可运行,且路径和进程处于同一环境 |
| 动态启停插件 | 为每种注册返回 disposer,反复加载、卸载再加载 | 无重复工具、残留监听器或未关闭连接;异步清理能被等待 |
| 替换必需服务 | 先卸载提供方,观察依赖方,再挂载新实现 | consumer 在缺失期间不保持激活,恢复后重新绑定新实现 |
| 多 Agent 定制 | 通过 Agent scope 注册同名局部工具 | A 的覆盖和退出不会改变 B 的工具视图 |
| 上下文可追溯 | 为新增模型可见内容定义日志事件或投影 | 能从 Session 重建实际请求,包含工具结果与必要的运行时事实 |
| 扩展 Web UI | 先声明 Slot 与 props,再注册组件与清理 | 关闭插件后 UI、子 Slot 和订阅一并退出,旧闭包不能继续越权渲染 |
本文的判断是:DeepSeek Harness 的插件化深度来自 Cordis 提供的统一运行约束,再由 dsh 将这些约束贯彻到 Agent、能力层和界面。固定下来的仍包括 Context 解析、生命周期、事件语义、数据协议与启动契约;可组合的是遵守这些契约的实现。理解这个边界,才能既看见它比“多装几个工具”更深的设计,也准确评估重载、兼容性与安全方面的成本。
资料与版本
- Cordis Primer:服务、依赖、事件与 Effect 的入口。
- DeepSeek Harness Architecture:Profile、请求循环、Session 与能力分层。
- A Programming Paradigm for Spatiotemporal Composability:组合机制的理论背景。
- Pi Agent 框架架构:对照另一种模型接口、Core 与 Coding Agent 分层。
- Mastra 项目原理:对照 Workflow 的持久化与恢复边界。
528c682 基线的官方文档
- README(定位、Quick Start、Developer Preview)
- Sandbox subsystem(bwrap、Landlock、sandbox-exec 与 Windows ACL)
- Tool execution pipeline(pre-execute、guards、execute、post-execute)
- CLI reference(plugins、MCP、telemetry)
- dsh vendor policy(锁定且可打补丁的 Cordis framework layer)
- dsh pi-ai adapter、Pi 项目与扩展文档
- DeepWiki:deepseek-ai/deepseek-harness