手把手入门 DeepSeek Harness：插件架构与API 接入与实战

大报言看

242人浏览 · 2026-11-05 11:06:31

大报言看 · 2026-11-05 11:06:31 发布

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

一、导语：为什么这条消息值得关注
二、它到底是什么？先做概念澄清
2.1 Harness 不是模型，是 Agent 运行时
2.2 Cordis：插件元框架
三、核心设计拆解
3.1 一切皆插件：模型、工具、UI、沙箱全可替换
3.2 服务 + 类型化事件 + 可逆副作用
3.3 与现有 Agent 框架的关键差异
四、实际影响与适用场景
五、安装、大模型 API 接入与上手实践
5.1 环境准备
5.2 一键启动
5.3 大模型 API 接入指南（官方直连 vs 国内托管中转站）
5.4 安装社区插件
六、实战项目：开发一个「AI 编程番茄钟」插件
6.1 项目目标
6.2 开发步骤
七、冷静视角：边界、风险与未解问题
总结

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

DeepSeek Harness（dsh）基于 MIT 协议开源后，社区迅速涌现出一批实用插件：将右侧栏改造为完整开发工作台的 DSH-better-sidebar、支持 @ 快速引用文件的 dsh-at-file、以及为纯文本模型补齐视觉能力的第一个视觉插件 modlens（把图片解析为包含 OCR 与布局信息的结构化 JSON）。更有趣的是，知名技术博主鱼皮用「创造模式（Creator Mode）」让 AI 自己开发了一个桌宠插件 dsh-kun-like-pet，还能通过 GitHub MCP 插件一键推送到开源仓库。

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

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

不修改框架源码，就能通过配置替换模型、工具、UI、沙箱
用 AI 辅助开发插件，几分钟就能测试并发布一个新扩展
在已有内部 Agent 平台的基础上，只替换某一层（如模型网关或执行沙箱）而不重写全部业务逻辑

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

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

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

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

它和 Claude Code、Codex 是同一类产品——AI 编程与任务执行工具，但架构思路完全不同：Claude Code 和 Codex 是封闭的单体应用，能力高度内置；Harness 把所有能力都拆成插件，包括模型适配器、工具注册表、追加式会话日志（Session Log）、甚至 Agent 循环本身，全部可独立挂载与替换。

2.2 Cordis：插件元框架

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

插件生命周期管理：负责插件的加载、初始化与卸载
依赖注入：解析插件间依赖并按顺序启动
事件总线：让插件通过服务（Service）和类型化事件（Typed Event）彼此协作

当一个插件被卸载时，它的所有注册项与状态变更会被反向撤销，不留孤儿状态。这意味着你可以随时热插拔（Hot-swapping），不需要重启整个 Agent 运行时。

三、核心设计拆解

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

Harness 的插件覆盖了 Agent 运行的完整生命周期：

插件类型	职责	可替换示例
Model Adapter	模型调用适配与路由	DeepSeek V4 Pro ↔ Claude ↔ GPT ↔ 本地模型 / 聚合网关
Tool Registry	工具注册与调用	文件读写、终端 Shell 执行、免费联网搜索（如 `modsearch`）
Web UI / TUI	交互界面	默认 Web 界面 ↔ 终端界面（`dsh-TUI`）↔ 自定义主题皮肤
Session Log	会话记录与回放	本地追加式日志（Append-only Log）↔ 数据库持久化
Sandbox	代码执行沙箱	本地进程沙箱 ↔ Docker 容器 ↔ 远程 SSH 服务器
Agent Loop	Agent 循环逻辑	标准模式（Standard）↔ 代码编排模式（Code Mode）↔ 自定义决策流

没有特权核心：你不需要 patch 框架源码来扩展功能，只需要将插件或模型网关挂载到配置文件里。

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

Cordis 插件协作的三要素：

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

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

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

对比维度	DeepSeek Harness	LangGraph	AutoGen
架构哲学	一切皆插件，运行时极简	图编排，节点即步骤	多 Agent 对话
扩展方式	配置文件挂载插件，不改源码	自定义节点/边	自定义 Agent 类
交互界面	内置 Web UI 与 CLI（本身也是插件）	无内置 UI	无内置 UI
可追溯性	追加式会话日志，每步推理与调用可回放	需自行接入外部追踪	需自行实现
热插拔	原生支持（基于可逆副作用）	不支持	不支持
开发语言	TypeScript	Python / JS	Python / .NET

四、实际影响与适用场景

对个人开发者：学习与接入成本极低。一键启动后，安装插件只需一条命令；需要看图就装 modlens，需要工作台就装 DSH-better-sidebar，开发新插件还可以开启「创造模式」让 AI 协助编写。
对企业与研发团队：对于已有内部 Agent 平台或特定合规要求的团队，Harness 的插件化意味着可以只替换沙箱层或模型路由层（如统一接入内部网关），而不必重写上层业务逻辑。
对开源生态：在 Harness 之前，主流 AI 编程工具大多是封闭黑盒。Harness 验证了当底层运行时足够开放时，社区能以极快的速度自发填补视觉、记忆（如 dsh-mnemon）和工作流短板。

五、安装、大模型 API 接入与上手实践

5.1 环境准备

环境要求：Node.js 版本需满足 ^22.19.0 或 >=24.0.0（不支持奇数非 LTS 版本，如 Node 23 会启动失败）。

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

如果本地版本较老（例如 v18.x），推荐使用 nvm（Windows 环境可使用 nvm-windows）进行多版本切换：

# 1. Windows 用户可前往 https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe
# 2. 安装并切换至 Node 24
nvm install 24
nvm use 24

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

5.2 一键启动

无需繁琐的全局配置，直接通过 npx 即可拉起 Web 界面：

# npx 一键启动 Web UI
npx @deepseek-ai/dsh web

首次执行会下载相关运行时依赖，请耐心等待不要中途退出。启动成功后，在浏览器访问默认地址即可进入工作台：
[http://127.0.0.1:3080](http://127.0.0.1:3080)

5.3 大模型 API 接入指南（官方直连 vs 国内托管中转站）

首次进入 Web 界面后，需要配置大模型 API 才能驱动 Agent 运转。得益于 Harness 的模型适配器（Model Adapter）设计，它既支持绑定官方原生接口，也支持接入兼容 OpenAI 协议的自定义网关。常见接入方式主要分为以下两种：

方式一：官方订阅/直连接入（适合单一模型使用）

如果你直接使 DeepSeek 官方平台：

前往 DeepSeek 开放平台创建并复制 API Key。
在 Harness Web 界面中，打开 Settings（设置） -> Models（模型）。
找到默认的 DeepSeek 卡片，将 API Key 填入并保存。密钥会以只写（Write-only）方式安全保存在本地 $DSH_HOME/.credentials.yaml（默认路径为 ~/.dsh/.credentials.yaml）中，配置界面仅保留引用标识，防止密钥明文泄露。
保存后即可直接调用官方发布的 DeepSeek-V4-Pro 或 DeepSeek-V4-Flash 等模型。

方式二：国内托管中转站接入（以 4SAPI 为例，适合多模型混用）

在实际开发场景中，如果你除了 DeepSeek 外，还想在同一个 Harness 工作台里无缝切换 Claude、GPT 等海外主流模型来进行代码审查或复杂推理，或者不想折腾海外信用卡绑卡与跨境网络代理，也可以选择接入国内托管的 API 中转服务（例如 4SAPI 等支持标准 OpenAI 协议的聚合网关）。

使用这类国内托管中转站的核心优势很直观：

网络直连更稳定：国内节点直接响应，避免因跨境网络波动导致的 Agent 长链路任务中途断连。
一套配置调用全模型：无需为不同厂商分别配置插件或维护多个账号，仅靠一个统一的 Base URL 和 API Key 就能按需切换不同底座模型。
降低接入与结算门槛：省去海外支付限制与多平台额度管理的繁琐。

接入步骤（支持 UI 界面或配置文件挂载）：

通过 Web UI 添加：进入 Settings -> Models -> Add a custom provider，依次填入自定义的 Provider ID（注意：Provider ID 保存后不可直接重命名）、中转站的 Base URL（通常以 /v1 结尾），协议选择 openai-completions，填入中转站生成的 API Key 并手动添加需要使用的模型 ID（如 deepseek-v4-pro、claude-3-7-sonnet 等）即可。
通过配置文件挂载（推荐进阶开发者）：直接编辑 ~/.dsh/settings.yaml，并在环境变量中导出密钥：

# 在终端设置环境变量（替换为你的实际 Key）
export RELAY_API_KEY="sk-your-key-from-4sapi"

在 ~/.dsh/settings.yaml 中添加路由与兼容性配置：

# 设置默认启动的模型路由
agent-default-model:
  provider: relay-gateway
  model: deepseek-v4-pro

llm-pi-ai:
  providers:
    relay-gateway:
      api: openai-completions
      baseURL: https://www.4sapi.com/v1  
      apiKeyEnv: RELAY_API_KEY
      # 兼容性配置：避免第三方网关因不识别 developer 角色或新字段而报错
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: deepseek-v4-pro
        - id: claude-3-7-sonnet
          input: [text, image]  # 若模型支持多模态看图，可显式声明 image 输入能力

避坑提示：第三方 OpenAI 兼容网关有时不提供 GET /models 自动拉取列表接口，在 Web UI 点击获取模型列表若返回 401/404 属于正常现象，直接手动输入模型 ID 保存即可正常对话。

5.4 安装社区插件

搞定模型连接后，就可以通过命令行按需组装社区插件了：

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

# 示例 1：安装视觉解析插件 modlens（支持指定 npm 版本安装）
npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest

# 示例 2：安装增强版侧边栏工作台 DSH-better-sidebar
dsh plugin --profile web add dsh-better-sidebar@latest

安装完成后，根据插件类型重启 dsh web 或在浏览器按 Ctrl/Cmd + Shift + R 强制刷新即可生效。

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

6.1 项目目标

开发一个名为 dsh-pomodoro-timer 的插件，实现以下功能：

在 Web 界面右下角显示番茄钟悬浮窗
支持 25 分钟专注 + 5 分钟休息 的标准番茄工作法
专注期间自动锁定 AI 对话框（防止频繁依赖 AI 分心），休息期间解锁
番茄钟倒计时结束后，触发事件让 AI 根据当前会话日志自动生成一段「本次专注期间完成的工作摘要」

6.2 开发步骤

步骤 1：使用脚手架创建插件项目

# 创建 Web UI 类型的插件项目
npx create-dsh-plugin dsh-pomodoro-timer -t webui
cd dsh-pomodoro-timer

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

编辑 src/index.ts（或模板生成的入口文件），利用 Cordis 的服务注册与事件机制实现逻辑：

/**
 * dsh-pomodoro-timer: AI 编程番茄钟插件
 * 
 * 功能：
 * - 25 分钟专注 + 5 分钟休息
 * - 专注期间锁定 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:started') {
      // 专注开始，锁定 AI 对话输入
      lockChatSession();
    }
    if (event.type === 'timer:completed') {
      // 番茄钟完成，结合 Session Log 请求 AI 生成工作摘要
      generateWorkSummary(event.sessionId);
    }
    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：测试番茄钟功能

打开浏览器进入 Web UI，点击右下角番茄钟悬浮窗的「开始专注」。
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

生态收录提示：推送后，在 GitHub 仓库页面的 Settings -> Topics 中添加 dsh-plugin 标签，社区插件索引即可自动抓取并收录你的作品。

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

第三方插件质量参差不齐：社区插件可由任何开发者通过 GitHub 自由发布。像 modlens、DSH-better-sidebar 这样经过大量用户验证的高星插件属于少数，更多插件仍处于早期实验阶段。在生产环境安装未知插件前，务必先审阅源码。
「创造模式」的权限与安全边界：「创造模式（Creator Mode）」允许 Agent 实时检查运行时状态并在内存中测试新插件。虽然挂载前有人工确认环节，但 AI 生成的代码仍可能包含非预期的文件读写或外部网络请求，建议配合沙箱环境使用。
企业级套件仍在演进：目前 Harness 处于开发者预览阶段（Developer Preview），核心迭代极快。面向个人工作流的效率插件已经很丰富，但涉及多租户权限隔离、企业级细粒度审计等深水区能力，仍需团队自行二次开发。
与 Claude Code / Codex 的定位差异：Harness 走的是「极致开放与可组装」路线。对于追求零配置、开箱即用的开发者，单体工具依然省心；但对于有多模型路由切换、自定义工具链及私有化部署需求的开发者，Harness 提供了极高的自由度。

总结

DeepSeek Harness 的「一切皆插件」架构，把 AI Agent 运行时从封闭的单体黑盒拆成了可自由组装的乐高积木。底层 Cordis 框架通过服务注册、类型化事件与可逆副作用，实现了真正意义上的运行时热插拔。

核心要点回顾：

定位清晰：Harness 不是新模型，而是开源的 Agent 编排运行时——模型、工具、UI、沙箱皆为插件。
接入灵活：原生支持官方 API 直连，同时完美兼容像 4SAPI 这类遵循 OpenAI 协议的国内托管中转网关，方便开发者在低延迟网络下跨厂商混用主流大模型。
生态自生长：社区插件正在快速补齐视觉理解（modlens）、集成工作台（DSH-better-sidebar）与专注管理等能力。
AI 驱动扩展：借助脚手架与「创造模式」，开发者可以极低成本让 AI 协助编写、测试并发布属于自己的插件。

这场「开源运行时 + 万物皆插件」的实验才刚刚拉开序幕。用不了多久，每位开发者手里的 AI 编程工具或许都长得不一样——因为从底座模型网关到上层交互界面，每一个零件都可以按你自己的工作流自由拼装。