DeepSeek Harness 插件系统全解析｜基于 dsh‑workspace‑enhance 实战：安装、原理 给DeepSeek Harness 装上侧边栏

DeepSeek 官方开源 Agent 运行时 DeepSeek HarnessDSH核心哲学是一切皆插件。本文从底层 Cordis 内核讲透插件运行机制结合开源项目dsh‑workspace‑enhance文件列表增强插件完整演示插件安装、源码解读、从零手写一个 DSH 插件的完整流程适合想扩展 DSH 能力、自定义 Agent 工具链的开发者。DeepSeek‑Harness 官方仓库https://github.com/deepseek-ai/deepseek-harnessdsh-workspace-enhancehttps://github.com/luis1232023/dsh-workspace-enhance一、前言DeepSeek Harness简称 DSH8 月 13 日正式开源它不是大模型而是Agent 运行时底座公式Agent 大模型 HarnessDeepSeek。 不同于 Claude Code、Codex 这类成品应用DSH 所有能力全部由插件提供模型适配器、工具函数、会话存储、Agent 主循环、Web 界面全部是插件可以热插拔替换不需要修改框架源码。默认 DSH 的 Web 端缺少直观的工作区文件树Agent 只能通过工具调用扫描目录模型反复遍历目录会消耗大量 tokendsh‑workspace‑enhance就是解决该痛点的社区开源插件给 DSH Web UI 增加可视化文件列表面板同时向 Agent 注入结构化工作区上下文减少不必要文件扫描提升 VibeCoding 效率。二、DeepSeek Harness 插件系统底层原理2.1 底层内核 CordisDSH 插件完全基于自研 Cordis 元框架三个核心概念Context 上下文、inject 依赖注入、apply 插件入口。Context全局共享上下文对象所有服务tools、systemPrompt、webview 等挂载在这里。插件之间不直接互相 import全部通过 Context 获取服务。inject 数组声明当前插件依赖哪些服务框架等待依赖全部就绪才执行插件逻辑。apply(ctx)插件唯一入口函数Cordis 内核自动调用传入上下文。插件在这里注册工具、注册 web 插槽、监听事件、注册配置项。副作用自动回收插件卸载时ctx.effect()注册的所有监听、工具注册会自动清理避免内存泄漏。2.2 DSH 插件两大分类类型运行位置能力范围典型例子Host 插件Node 侧后端 Node 运行时注册工具函数、文件读写、命令执行、系统 Prompt 注入自定义文件工具、git 操作插件Client 插件Web 侧浏览器前端扩展 Web UI、新增侧边栏 Tab、增加弹窗、页面组件dsh‑workspace‑enhance、各类 UI 美化插件重点很多新手踩坑Host 插件不能操作 DOMClient 插件不能直接访问本地文件系统二者通过 DSH 内部事件总线通信。2.3 插件加载流程dsh 启动读取 profile 配置解析bundles插件清单Cordis 内核解析每个插件inject依赖拓扑排序确定启动顺序依次调用每个插件apply(context)注册工具 / UI / 事件Agent‑loop 插件启动大模型就可以调用插件注册的全部工具。profile 配置存放目录~/.dsh/profiles/web插件实际安装到 profile 下面的 node_modules 中DeepS...。三、实战 1安装 dsh‑workspace‑enhance 插件插件功能给 DSH Web 页面新增侧边栏文件树实时展示工作区文件结构同时向 Agent 注入精简工作区摘要减少模型重复调用 ls 扫描目录降低 token 消耗。前置条件已经全局安装 dshnpm install -g deepseek‑ai/dsh安装命令直接拉 GitHub 仓库安装# web profile 是我们网页端使用的配置集 dsh plugin --profile web add githttps://github.com/luis1232023/dsh‑workspace‑enhance或者 直接 让deepseek 帮我们安装帮我安装插件 https://github.com/luis1232023/dsh‑workspace‑enhance安装成功提示输出类似✅ plugin dsh‑workspace‑enhance installed into profile web ⚠️ Please restart dsh web service to load new plugin重启 dsh 服务# 关闭旧进程重新启动web服务 dsh web访问http://127.0.0.1:3080侧边栏会多出Workspace Files标签加载当前工作目录的文件树。卸载插件dsh plugin --profile web remove dsh‑workspace‑enhance常见踩坑安装插件之后没有效果必须重启 dsh web热重载不生效文件树空白确认已经在 DSH 界面选择工作区文件夹报错 git not found本地需要安装 git 环境dsh 通过 git 协议拉取 github 插件源码。四、dsh‑workspace‑enhance 源码深度解读克隆源码到本地分析git clone https://github.com/luis1232023/dsh‑workspace‑enhance cd dsh‑workspace‑enhance目录结构dsh‑workspace‑enhance ├── package.json # dsh插件标识dsh字段声明插件元信息 ├── src │ ├── index.ts # Host侧插件入口 apply(ctx) │ └── client.ts # Client浏览器侧UI插件入口 └── tsconfig.json4.1 package.json 关键片段DSH 插件识别标记{ name: dsh‑workspace‑enhance, dsh: { bundles: { host: ./lib/index.js, client: ./lib/client.js } } }dsh.bundles是 DSH 识别插件的核心标记hostNode 后端插件编译产物client浏览器 Web 前端插件编译产物4.2 Host 侧 src/index.ts 核心逻辑import type { Context } from deepseek‑ai/cordis // 声明依赖需要systemPrompt服务用于注入系统提示词片段 export const inject [systemPrompt,workspace] export function apply(ctx: Context) { // 监听工作区变更事件 ctx.on(workspace:change, async (workspacePath){ // 读取目录结构生成精简的文件树摘要 const fileTree await scanDirectory(workspacePath) // 将文件树摘要注入系统Prompt模型自动感知当前项目结构 ctx.systemPrompt.section(workspace‑context, 【当前工作区文件摘要】 ${JSON.stringify(fileTree,null,2)} 不要反复调用ls扫描目录优先使用上面给出的文件列表 ) }) } async function scanDirectory(path:string){ // 递归扫描本地目录过滤node_modules、.git等忽略目录 }Host 插件做两件事监听workspace:change事件工作区切换时扫描本地目录将精简文件树注入systemPrompt给大模型直接提供项目概览减少工具调用次数。4.3 Client 侧 src/client.ts 前端 UI 逻辑import type { Context } from deepseek‑ai/cordis/client // 前端依赖webview服务用于注册侧边栏tab export const inject [webview] export function apply(ctx: Context) { // 向DSH Web侧边栏注册新Tab标签页 ctx.webview.registerSidebarTab({ id:workspace‑files, label:Workspace Files, async render(el){ // el是DOM容器在这里渲染文件树组件 el.innerHTML div idfile‑tree/div // 监听后端推送过来的文件树数据渲染到页面 ctx.events.on(workspace‑enhance:file‑tree,(tree){ renderFileTree(el.querySelector(#file‑tree),tree) }) } }) }Client 插件只负责 UI 展示不直接读取本地磁盘文件扫描全部交给 Host 后端通过事件总线把数据推送到前端渲染。架构优势前后端分离符合 DSH 设计规范不会出现浏览器跨域、本地文件权限问题。五、从零手写第一个 DSH 插件实战 demo我们写一个极简插件注册一个 host 工具demo_echo同时在 web 侧边栏新增一个简单 tab。步骤 1初始化插件项目mkdir dsh‑plugin‑demo cd dsh‑plugin‑demo pnpm init pnpm add deepseek‑ai/cordis deepseek‑ai/dsh‑tools typescripttsconfig.json{ compilerOptions: { target:ES2022, module:CommonJS, outDir:./lib, strict:true }, include:[src/**/*] }package.json 核心配置{ name:dsh‑plugin‑demo, scripts:{build:tsc}, dsh:{ bundles:{ host:./lib/index.js, client:./lib/client.js } } }步骤 2编写 Host 插件 src/index.tstypescriptimport type { Context } from deepseek‑ai/cordis import { defineTool } from deepseek‑ai/dsh‑tools import z from schemastery // 声明依赖需要tools工具注册服务 export const inject [tools] export function apply(ctx: Context) { // 注册工具给大模型调用 ctx.tools.register(defineTool({ name:demo_echo, description:测试回显工具把输入内容原样返回, schema: z.object({ msg:z.string().describe(输入消息) }), async invoke({msg}){ return { result:demo插件收到消息${msg} } } })) }步骤 3编写 Client 前端插件 src/client.tsimport type { Context } from deepseek‑ai/cordis/client export const inject [webview] export function apply(ctx: Context){ ctx.webview.registerSidebarTab({ id:demo‑tab, label:Demo插件面板, render(el){ el.innerHTML h3我的第一个DSH插件/h3 } }) }步骤 4编译 本地安装插件pnpm run build # 本地路径安装插件 dsh plugin --profile web add ./重启 dsh webWeb 侧边栏出现 Demo 插件面板对话中让模型调用demo_echo工具即可执行我们自定义逻辑。六、DSH 插件开发避坑清单区分 Host 与 Client 环境Host 插件index.ts运行 Node可以读写文件Clientclient.ts浏览器环境不能 fs 读写二者靠事件总线通信不要混用 API。inject 一定要写全依赖如果用到tools、webview、systemPrompt必须写进 inject 数组否则插件启动的时候服务还未初始化直接报错。不要修改 DSH 源码所有扩展全部通过插件完成升级 DSH 版本不会丢失自定义能力。插件卸载自动回收资源定时器、事件监听统一使用ctx.effect((){/*清理逻辑*/})插件卸载自动执行清理防止内存泄露。profile 隔离web、headless 是两套独立配置安装插件要指定--profile webheadless 环境不会复用 web 的插件。七、什么时候适合开发 DSH 插件需要给 Agent 新增自定义工具能力需要扩展 Web UI增加侧边栏、自定义面板需要注入自定义 systemPrompt 片段修改 Agent 行为需要监听 Agent 生命周期事件会话开始、工具调用前后。如果只是简单提示词直接对话写 prompt 即可需要持久化能力、UI 扩展、工具注册再开发插件。八、总结DeepSeek Harness 的一切皆插件不是营销口号是落实在 Cordis 内核的架构设计。dsh‑workspace‑enhance是非常好的入门样板插件完整演示 Host‑Client 分离的开发范式后端做业务逻辑前端只负责渲染 UI。DSH 生态刚刚爆发大量第三方插件可以直接拿来扩展 Agent 能力同时上手门槛并不高掌握 Context、inject、apply 三个核心概念就可以自定义属于自己的 AI Agent 工具链。