DeepSeek Harness 简介与使用

解读

DeepSeek Harness（dsh）是由 DeepSeek AI 开发的开源 agent
harness（智能体框架）。它采用一切皆插件的架构，并由 Cordis 驱动，其设计参见论文 A Programming Paradigm
for Spatiotemporal Composability。

定义与设计原则

DeepSeek Harness（简称 dsh）是 DeepSeek 推出的 Agent 运行框架。官方给它的核心设计原则是“一切皆插件“，即 dsh 中的模型、工具、会话、调度、存储、沙箱、循环、技能、UI 等能力，都是可插拔的 Cordis 插件，支持自由替换和灵活重组，开发者无需改动源码，即可在配置层选择、替换或扩展任一能力。

dsh 支持多种运行模式，相当于官方提供的模板，方便开箱即用：

• 标准模式：提供完整的工具组合，拥有完整的代码Agent能力
• PTC 模式：通过模型生成的一段代码组合多轮工具调用
• 极简模式：仅保留一个 shell 工具与一个文件编辑工具，用于最小化环境下的模型基准测试
• 创造模式：检查自己正在运行的 Cordis 环境，在内存中试验插件，帮助创建新的 Agent 和插件

Cordis 的作用？

Cordis 是 Koishi 在开发过程中衍生出的插件元框架，Cordis 内核只负责插件的加载、卸载和依赖关系，不承载 Agent 的具体能力

和 Claude Code、Codex、OpenClaw 的区别在哪里？

Claude Code、Codex、OpenClaw 都是一个固定化的产品，使用时必须按它的规则来。DeepSeek Harness 更像是一套元框架，可以用它来组装个性化的 Agent 产品，任何组件都可以自由替换

dsh 解决了什么痛点？

• 大模型能力越来越强，但缺少能把模型用好的 Harness
• 现有的 Agent 框架扩展成本高，增加或修改能力就要触及核心代码
• 打破了生态封闭局面，Claude Code 闭源且与 Anthropic 强绑定，Codex 与 OpenAI 强绑定，其它的各种 Agent 框架风格迥异

底层原理

其底层核心原理主要包含以下三个方面：一切皆插件 + Cordis 微内核架构 + 时空可组合性

• 一切皆插件：所有能力全部拆解为可独立、组合的插件。开发者无需修改源码，通过修改配置文件即可自由组装、替换和热插拔组件，实现高度定制化
• Cordis 微内核架构：整个框架建立在 Cordis 插件元框架之上，仅负责插件的加载、卸载和依赖解析，插件之间依靠服务与事件机制通信，互不强耦合
• 时空可组合性：支撑了插件的安全与动态调度
  ■ 时间可组合性：通过可逆效应机制，系统自动记录并撤销组件卸载后的副作用，保证运行时热插拔的安全和系统长期稳定
  ■ 空间可组合性：通过响应式共效应实现声明式依赖管理，组件只需声明需求，运行时即可自动协调依赖变化，实现动态激活与停用

运行

通过 npm 运行

安装 Node.js，然后运行以下命令：

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认地址为 http://127.0.0.1:3080

从源码运行

如需从仓库源码运行，需要 Node.js >= 22 与 pnpm

安装 pnpm

npm install -g pnpm

安装 deepseek-harness

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

之后运行时只需执行 pnpm dsh web 即可

配置 API Key

测试

开启一个工作区来测试

可以查看 Agent 执行中的轨迹信息

安装插件

首先在命令行中执行以下命令，全局安装 dsh：

npm install -g @deepseek-ai/dsh

以下是几个常见插件的安装示例

dsh-at-file

dsh-at-file 提供了 DeepSeek Harness 网页界面的工作区路径引用功能。在输入框中输入 @ 符号，即可搜索当前工作区，并插入文件或目录的路径

执行以下命令：

dsh plugin --profile web add https://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.6.0.tar.gz

装完重启 dsh web，设置中有文件提及设置

dsh-web-ui

链接🔗：https://github.com/omdsh-dev/dsh-at-file

dsh-web-ui 是给 DeepSeek Harness（DSH）Web GUI 用的插件和皮肤集合：面向 DeepSeek V4 Pro 的 agent 预设，以及任务看板、Git 图谱、右侧面板、移动端远程、SSH 运维、图像理解、鲸鱼娘宠物、实时吞吐和皮肤中心。所有插件都走官方 profile 机制挂载到 dsh web，不改 DSH 源码；可以逐个安装，也可以用聚合包一次装齐

执行以下命令：

dsh plugin --profile web add @linxin666/dsh-web-ui-all

装完重启 dsh web，侧边栏就有全部插件入口

ModLens

链接🔗：https://github.com/liustack/modlens

DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别。ModLens 借助外挂视觉引擎，为纯文本模型补上视觉能力。ModLens 支持直接粘贴图片识别，无需先保存成文件再提供路径

执行以下命令：

dsh plugin --profile web add @linxin666/dsh-web-ui-all

装完重启 dsh web，侧边栏就有全部插件入口

报错解决

若安装插件过程中报错 PNPM_MISSING_TARBALL_INTEGRITY：

ERR_PNPM_TARBALL_INTEGRITY
此错误表示下载的软件包的 tarball 与预期的完整性校验和不匹配。
如果使用 npm 注册源 (registry.npmjs.org)，那么这可能意味着锁文件中的完整性不正确。 如果锁文件解析时错误地合并冲突，则可能会发生这种情况。
如果使用允许覆盖包的现有版本的注册源，则可能意味着在本地元数据缓存中有旧版本软件包的完整性校验。 在这种情况下，你应该运行 pnpm store prune。 此命令将删除你的本地元数据缓存。 然后你可以重试失败的命令。
但是也要小心并验证软件包是否从正确的 URL 下载。 错误消息中应该打印 URL。

则执行以下命令：

pnpm store prune

并将 用户\.dsh\profiles\web 下的 pnpm-lock.yaml 文件删除，最后重新执行安装命令即可