手把手入门DeepSeek Harness：万物皆插件架构（附实战）- 惊觉

DeepSeek Harness 插件生态：「一切皆插件」到底怎么拼？

关键词：DeepSeek Harness、Cordis 插件架构、dsh plugin、Agent 运行时、插件开发

一、导语：为什么这条消息值得关注
二、它到底是什么？先做概念澄清
- 2.1 Harness 不是模型，是 Agent 运行时
- 2.2 Cordis：插件元框架
三、核心设计拆解
四、实际影响与适用场景
五、安装与上手实践
六、实战项目：开发一个「AI 编程番茄钟」插件
- 6.1 项目目标
- 6.2 开发步骤
七、冷静视角：边界、风险与未解问题
总结

一、导语：为什么这条消息值得关注

DeepSeek Harness（dsh）开源后，社区迅速涌现出一批实用插件：优化侧边栏交互的 DSH-better-sidebar、支持 @ 快速引用文件的 dsh-at-file、第一个视觉插件 modlens（把图片解析为结构化 JSON）。更有趣的是，知名技术博主鱼皮用「创造模式」让 AI 自己开发了一个桌宠插件 dsh-kun-like-pet，还能通过 GitHub MCP 插件一键推送到开源仓库。

这条消息的核心价值不在于"有哪些好玩插件"，而在于它验证了一个架构判断：当 Agent 框架把「一切皆插件」做到极致时，社区能自己补齐产品短板，甚至长出官方没想到的能力。

对 AI 应用开发者来说，理解 Harness 的 Cordis 插件架构，意味着你可以：

不修改框架源码，就能替换模型、工具、UI、沙箱
用 AI 辅助开发插件，几分钟就能发布一个
在已有内部 Agent 平台的基础上，只替换某一层而不重写全部

二、它到底是什么？先做概念澄清

2.1 Harness 不是模型，是 Agent 运行时

很多人看到 DeepSeek Harness，第一反应是"又一个 DeepSeek 模型"。实际上：

不是：一个新的 LLM 模型
而是：一个开源的 Agent 编排运行时，基于 TypeScript，跑在浏览器里（Web UI）或终端里（CLI）

它和 Claude Code、Codex 是同一类产品——AI 编程工具，但架构思路完全不同：Claude Code 和 Codex 是单体应用，能力内置；Harness 把所有能力都拆成插件，包括模型适配器、工具注册表、会话日志、Agent 循环本身，全部可替换。

2.2 Cordis：插件元框架

Harness 的底层是一个叫 Cordis 的插件元框架。Cordis 不关心你怎么实现工具，它只做三件事：

插件生命周期管理：加载、初始化、卸载
依赖注入：插件按依赖顺序启动
事件总线：插件通过服务（service）和类型化事件（typed event）彼此协作

插件卸载时，它的所有注册会被反向撤销，不留孤儿状态。这意味着你可以随时热插拔，不需要重启整个运行时。

三、核心设计拆解

3.1 一切皆插件：模型、工具、UI、沙箱全可替换

Harness 的插件覆盖范围：

插件类型	职责	可替换示例
Model Adapter	模型调用适配	DeepSeek V4 Pro ↔ Claude ↔ GPT-4 ↔ 本地模型
Tool Registry	工具注册与调用	文件读写、终端执行、网络搜索
Web UI	浏览器界面	默认界面 ↔ 2005 年老站风格皮肤 ↔ 自定义主题
Session Log	会话记录	追加日志 ↔ 数据库持久化
Sandbox	代码执行沙箱	本地沙箱 ↔ Docker ↔ 远程服务器
Agent Loop	Agent 循环逻辑	默认循环 ↔ 自定义决策流

没有特权核心：你不需要 patch 框架源码来扩展功能，只需要挂载一个插件到配置里。

3.2 服务 + 类型化事件 + 可逆副作用

Cordis 插件协作的三要素：

┌─────────────────────────────────────────────────┐
│                   Cordis 运行时                   │
├──────────┬──────────────┬───────────────────────┤
│ Service  │ Typed Event  │ Reversible Effect     │
│ (服务)    │ (类型化事件)  │ (可逆副作用)           │
│          │              │                       │
│ 插件注册  │ 插件发布/订阅  │ 插件卸载时自动撤销     │
│ 共享能力  │ 跨插件通信    │ 不留孤儿状态           │
└──────────┴──────────────┴───────────────────────┘

Service：插件向运行时注册的能力（如"文件读写服务"、“模型调用服务”）
Typed Event：插件之间通过类型化事件通信（如"任务完成事件"、“用户输入事件”）
Reversible Effect：插件产生的副作用在卸载时会被自动撤销（如临时文件清理、端口释放）

3.3 与现有 Agent 框架的关键差异

对比维度	DeepSeek Harness	LangGraph	AutoGen
架构哲学	一切皆插件，运行时极简	图编排，节点即步骤	多 Agent 对话
扩展方式	配置文件挂载插件，不改源码	自定义节点/边	自定义 Agent 类
UI	内置 Web UI（本身也是插件）	无内置 UI	无内置 UI
可追溯性	追加式会话日志，每步可查	需自行实现	需自行实现
热插拔	支持（可逆副作用）	不支持	不支持
语言	TypeScript	Python	Python

四、实际影响与适用场景

对个人开发者

学习成本：低。一键启动后，安装插件只需一条命令。开发插件可以用「创造模式」让 AI 帮你写。
实际用途：如果你用 AI 编程工具，Harness 的插件生态让你可以按需组装：需要看图就装 modlens，需要文件引用就装 dsh-at-file，想要个性化就自己写皮肤插件。

对企业/团队

接入成本：对于已有内部 Agent 平台的企业，Harness 的插件化意味着可以只替换沙箱层或模型层，而不重写业务逻辑。
部署选项：可以部署到服务器上，让整个团队共享一个 Harness 实例。

对生态

填补空白：在 Harness 之前，AI 编程工具（Claude Code、Codex）都是封闭的单体应用。Harness 是第一个把「一切皆插件」做到极致的开源 Agent 运行时。
可能冲击谁：封闭的 AI 编程工具。如果社区能自己补齐产品短板，官方迭代压力会更大。

五、安装与上手实践

5.1 环境准备

要求：Node.js 版本 ^22.19 || >=24（奇数版本不支持，Node 23 会启动失败）

# 检查当前 Node.js 版本
node -v

# 如果版本不符，需要安装 Node 24

在这里插入图片描述

这里我的node版本是v18.20.4，比较老了，跟我一样的朋友这里我推荐，一个办法来解决:用 nvm-windows 管理多版本

# 1. 下载 nvm-windows
# 去 https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe 安装

# 2. 安装 Node 24
nvm install 24
nvm use 24

# 3. 验证版本
node -v
# 应该显示 v24.x.x

在这里插入图片描述

# 方式 A：npx 一键启动（无需全局安装）
npx @deepseek-ai/dsh web

第一次下载的时候时间可能有点久，请耐心等一会儿，别失手退出了（别问我怎么知道的恼）
在这里插入图片描述
之后浏览器输入地址就好http://127.0.0.1:3080
首次进入要API Key

我这边有API Key,没有的朋友可以去官网

在这里插入图片描述
在这里点击创建API 可以就好。我前面的博文也有相关内容，感兴趣的可以去翻一翻。

在这里插入图片描述

5.3 安装社区插件

# 安装插件的通用命令格式
dsh plugin --profile web add "github:owner/repo#ref"

# 示例：安装视觉插件 modlens
dsh plugin --profile web add "github:liustack/modlens#main"

其他热门插件：

# 优化侧边栏交互
dsh plugin --profile web add "github:xxx/DSH-better-sidebar#main"

# @ 符号快速引用文件
dsh plugin --profile web add "github:xxx/dsh-at-file#main"

六、实战项目：开发一个「AI 编程番茄钟」插件

6.1 项目目标

开发一个 dsh-pomodoro-timer 插件，功能：

在 Web 界面右下角显示番茄钟悬浮窗
支持 25 分钟专注 + 5 分钟休息的标准番茄钟
专注期间锁定 AI 对话（防止分心），休息期间解锁
番茄钟完成后，AI 自动生成一段「本次专注期间完成的工作摘要」

6.2 开发步骤

步骤 1：使用 create-dsh-plugin 脚手架创建插件

# 创建插件项目
npx create-dsh-plugin dsh-pomodoro-timer -t webui

步骤 2：编写插件核心代码

进入项目目录，编辑插件主文件：

cd dsh-pomodoro-timer

编辑 src/index.ts（或 src/my-plugin.ts）：

/**
 * dsh-pomodoro-timer: AI 编程番茄钟插件
 * 
 * 功能：
 * - 25 分钟专注 + 5 分钟休息
 * - 专注期间锁定 AI 对话
 * - 完成后 AI 生成工作摘要
 */
import { Plugin } from '@deepseek-ai/cordis';

export const pomodoroPlugin: Plugin = {
  id: 'pomodoro-timer',
  name: 'AI 编程番茄钟',
  
  // 注册服务
  services: {
    timer: createTimerService(),
    ui: createFloatingWindowUI(),
  },
  
  // 订阅事件
  onEvent(event) {
    if (event.type === 'timer:completed') {
      // 番茄钟完成，请求 AI 生成工作摘要
      generateWorkSummary(event.sessionId);
    }
    if (event.type === 'timer:started') {
      // 专注开始，锁定 AI 对话
      lockChatSession();
    }
    if (event.type === 'timer:break') {
      // 休息开始，解锁 AI 对话
      unlockChatSession();
    }
  },
};

步骤 3：登记插件并启动

编辑 cordis.patch.yml，登记你的插件：

- insert:
  - id: pomodoro-timer
    name: './src/index.ts'

启动开发模式测试插件：

# 方式 A：从源码启动（适合开发插件）
pnpm install
pnpm run build
pnpm dsh web

# 方式 B：本地开发模式（热重载）
pnpm run dev

步骤 4：测试番茄钟功能

点击右下角番茄钟悬浮窗，点击「开始专注」
25 分钟倒计时开始，AI 对话被锁定
专注完成后，AI 自动生成工作摘要
进入 5 分钟休息，AI 对话解锁

步骤 5：发布到 GitHub

# 初始化 git 仓库
git init
git add .
git commit -m "feat: AI 编程番茄钟插件"

# 推送到 GitHub
git remote add origin https://github.com/YOUR_USERNAME/dsh-pomodoro-timer.git
git push -u origin main

# 给仓库打上 dsh-plugin 标签
<!-- 操作提示：在 GitHub 仓库页面，Settings -> Topics，添加 dsh-plugin 标签 -->

七、冷静视角：边界、风险与未解问题

1. 插件质量参差不齐

社区插件由开发者自行发布，没有官方审核机制。像 modlens 这种实用插件是少数，更多插件可能只是实验性质。安装第三方插件前，建议先审查代码。

2. 创造模式的安全性

「创造模式」下 AI 可以帮你检查插件树、试验新插件、打包发布。虽然安装前有人工审批环节，但 AI 生成的代码可能存在安全隐患（如意外访问敏感文件、网络请求泄露数据）。

3. 生态早期

Harness 才刚开源，插件生态处于早期阶段。目前社区插件数量还不多，很多实用场景（如企业级权限管理、多租户隔离、审计日志）还没有成熟插件。

4. 与 Claude Code/Codex 的定位差异

Harness 走的是「极致开放」路线，但开放也意味着学习成本。对于只想快速写代码的开发者，Claude Code 和 Codex 的开箱即用体验可能更好。Harness 更适合喜欢折腾、有定制需求的开发者。

总结

DeepSeek Harness 的「一切皆插件」架构，把 Agent 运行时从单体应用拆成了可自由组装的积木。Cordis 插件元框架通过服务、类型化事件、可逆副作用，实现了真正的热插拔。

核心要点：

Harness 不是模型，是开源的 Agent 编排运行时——所有能力（模型、工具、UI、沙箱）都是插件
Cordis 是底层插件元框架——只做生命周期管理、依赖注入、事件总线三件事
社区能自己补齐产品短板——modlens 补了视觉能力，桌宠插件补了趣味性，番茄钟补了专注管理
开发插件可以用 AI 辅助——「创造模式」让 AI 帮你写插件、打包、发布到 GitHub

这场「开源 + 一切皆插件」的实验才刚开始。也许用不了多久，每个人手里的 AI 编程工具都长得不一样——因为每个人都可以根据自己的需求自由组装。

t 运行时从单体应用拆成了可自由组装的积木。Cordis 插件元框架通过服务、类型化事件、可逆副作用，实现了真正的热插拔。

核心要点：

Harness 不是模型，是开源的 Agent 编排运行时——所有能力（模型、工具、UI、沙箱）都是插件
Cordis 是底层插件元框架——只做生命周期管理、依赖注入、事件总线三件事
社区能自己补齐产品短板——modlens 补了视觉能力，桌宠插件补了趣味性，番茄钟补了专注管理
开发插件可以用 AI 辅助——「创造模式」让 AI 帮你写插件、打包、发布到 GitHub

#DeepSeek_Harness #Cordis #插件架构 #dsh_plugin #Agent运行时 #AI编程工具 #开源项目 #番茄钟

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/2203_75871132/article/details/163831802

手把手入门DeepSeek Harness：万物皆插件架构（附实战）

DeepSeek Harness 插件生态：「一切皆插件」到底怎么拼？

目录

一、导语：为什么这条消息值得关注

二、它到底是什么？先做概念澄清

2.1 Harness 不是模型，是 Agent 运行时

2.2 Cordis：插件元框架

三、核心设计拆解

3.1 一切皆插件：模型、工具、UI、沙箱全可替换

3.2 服务 + 类型化事件 + 可逆副作用

3.3 与现有 Agent 框架的关键差异

四、实际影响与适用场景

对个人开发者

对企业/团队

对生态

五、安装与上手实践

5.1 环境准备

5.3 安装社区插件

六、实战项目：开发一个「AI 编程番茄钟」插件

6.1 项目目标

6.2 开发步骤

步骤 1：使用 create-dsh-plugin 脚手架创建插件

步骤 2：编写插件核心代码

步骤 3：登记插件并启动

步骤 4：测试番茄钟功能

步骤 5：发布到 GitHub

七、冷静视角：边界、风险与未解问题

1. 插件质量参差不齐

2. 创造模式的安全性

3. 生态早期

4. 与 Claude Code/Codex 的定位差异

总结

评论

评论列表

微信小程序

QQ小程序

关于作者