🛠️ DeepSeek Harness（dsh）详细教程

从安装到插件开发：把大模型接进真实工作环境的 Agent 运行框架（MIT 开源 · 一切皆插件）

由 网络精灵 整理 · 2026-08-14 · AI 导航原创指南 · 基于官方 README / architecture.md / 社区实操

📑 目录

  1. 认知篇：它到底是什么
  2. 安装与环境准备
  3. 配置模型与密钥
  4. 第一次跑通（实操）
  5. CLI 与 Headless 自动化
  6. 架构深入
  7. 插件开发实战
  8. 实战案例
  9. 最佳实践与避坑
  10. 附录：速查表 / FAQ / 资源
2026-08-13
dsh 开源日
MIT
开源协议
Cordis
插件元框架
3080
Web UI 端口

1认知篇：它到底是什么

1.1 一句话定义

DeepSeek Harness（dsh）是 DeepSeek 于 2026-08-13 开源的 Agent 运行框架（MIT 协议）。 它不是新模型、不是 API 客户端，而是把大模型接入"真实工作环境"的执行层（Harness）：文件系统、终端、网页、代码工具、其他 Agent，以及上下文管理、工具调用编排、任务执行与边界控制。

官方仓库：github.com/deepseek-ai/deepseek-harness
NPM：@deepseek-ai/dsh

1.2 为什么需要 Harness

同一个模型，放进不同的 Agent 系统，表现可能天差地别。原因很简单：

社区里最经典的例子（评测者 sentdex）：DeepSeek V4-Flash-0731 在极简 harness 下 Terminal-Bench 只拿 44/89，换到功能完整的 Oh My Pi harness 直接跳到 64/89——同一模型、同一基准，差了 20 题。所以"模型易得，Agent 难建"，工程化执行层才是下一阶段竞争焦点。

1.3 核心公式

Model（大脑） + Harness（身体） = Agent（能干活的数字员工）

DeepSeek 给自己的定位：补齐"Vibe Coding / AI 编程执行层"入口，对标 OpenAI Codex、Anthropic Claude Code，但不绑定自家模型。

1.4 "一切皆插件" 到底是什么

这是 dsh 最反常规的设计。在 dsh 里，模型适配器、工具、技能、会话、沙箱、存储、Agent Loop 本身、调度、UI —— 全部是插件，由配置组合，无需改框架源码。

底层是 Cordis 插件元框架（理念来自北大 + DeepSeek 联合论文《A Programming Paradigm for Spatiotemporal Composability》）。Cordis 只管"插件怎么加载/卸载/互相依赖"，具体能力由插件提供。

关键好处：没有"特权内核"要打补丁。装一个插件 = 在插件树旁挂一个插件；卸一个插件 = 它的所有注册自动撤销（可逆效果 reversible effects）。

1.5 四种运行模式（Modes）

模式 = 默认加载不同"插件集"，在 UI 里切换：

模式默认插件集适用场景
Standard 标准完整工具组合日常开发，开箱即用
PTC（Programmatic Tool Calling）模型生成代码来组合多轮工具调用复杂工作流、需要编排多步操作
Minimal 极简仅一个 shell 工具 + 一个文件编辑工具跑分/基准验证的基线
Creation 创造可检视运行时、在内存里试验 Cordis 插件开发新插件、拼装新模式
注意区分 Profile（启动形态） 与 Mode（插件集）：
  • Profile 有 web（带浏览器）、headless（无服务器的一次性运行器）等模板；
  • Mode 是上面四种。两者正交，可以 dsh --profile web（然后 UI 里选标准/PTC…）。

1.6 与其他 Agent 工具对比

维度DeepSeek Harness典型 Harness
架构一切皆插件（Cordis）单体核心 + 扩展点
扩展方式挂插件，不改源码通常要 fork/patch 核心
可观测性追加式会话日志 + 轨迹视图参差不齐，常只记部分
运行模式Standard / PTC / Minimal / Creation通常单一模式
许可证MIT 开源各异
工具调用经典 + PTC（代码组合调用）通常仅经典

2安装与环境准备

2.1 环境要求

node -v        # 期望 v18 或以上
corepack enable  # 让 pnpm 命令可用（Node 16.13+ 自带 corepack）
pnpm -v

2.2 方式一：npx 一条命令（最快，推荐先试）

npx @deepseek-ai/dsh web

2.3 方式二：源码构建（写插件 / 看架构时用）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
源码里能直接读 docs/（architecture.md、cordis-primer.md、cordis-tutorial/）、examples/（acp-agent、native/landlock-run 沙箱）、各类 cookbook。

2.4 Windows 特别注意事项

2.5 验证安装

# 看本机实际会启动的插件树（每行都可被 patch 替换）
npx @deepseek-ai/dsh --profile web --dump-config

能正常打印一大棵配置树，说明安装 OK。

2.6 常见问题排查

现象排查
npx 卡在下载检查 npm 源/代理；可 npm config get registry 后切官方源
启动后打不开 3080netstat -ano | findstr 3080 看是否被占用；关掉占用进程或换端口
Node 版本过低报错升级到 18+，用 nvm 或官方安装包
pnpm 不是命令corepack enable 或全局装 pnpm
启动后白屏清浏览器缓存；看终端日志有无构建报错

3配置模型与密钥

dsh 的模型适配器本身就是插件，所以换模型 = 换/加一个提供方配置，不改代码。

3.1 申请 API Key

V4-Pro 采用峰谷定价，空闲时段价格为高峰时段一半。

3.2 方式一：Web UI 图形化配置（推荐）

3.3 方式二：直接编辑 settings.yaml（适合 CI/CD）

配置文件位于 $DSH_HOME/settings.yaml（$DSH_HOME 是 Harness 主目录，默认 ~/.dsh 之类；如不确定，--dump-config 输出顶部会显示）。

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY      # 从环境变量读 Key
      api: openai-completions         # 协议类型
      baseURL: https://api.example.com/v1
      models:
        - id: model-name-here

然后命令行注入环境变量即可，模型变更无需重启 dsh，下次请求自动生效：

export GATEWAY_API_KEY="your-key-here"
npx @deepseek-ai/dsh web

3.4 三种提供方类型

类型是什么凭据适用
DeepSeek官方端点DeepSeek API Key（只写）默认、最快上手
目录提供方（Catalog）dsh 已收录的厂商（Anthropic、OpenAI、Bedrock、Vertex、Azure、Codex 等）各家 Key；原生认证需各自填接主流厂商
自定义提供方公司网关、自建 OpenAI 兼容服务Provider ID + baseURL + 协议 + 凭据 + 模型目录里没有的端点

添加自定义提供方时字段：

字段说明必填
Provider ID小写永久标识；请求、已存会话、凭据引用都用它。不可改名（要改就删了重建）必填
显示名称界面显示名可选
基础 URL端点 baseURL必填
API 协议如 openai-completions、anthropic必填
凭据API Key 或环境变量引用（如 env:GATEWAY_API_KEY）必填
模型至少一个模型 ID；可"获取可用模型"自动拉必填

3.5 接入第三方 / 自建模型

只要兼容 OpenAI Chat Completions 或 Anthropic 协议，都能接：

3.6 安全提醒（重点）

4第一次跑通（实操）

4.1 启动并添加工作区

npx @deepseek-ai/dsh web

打开 http://127.0.0.1:3080 后：

4.2 界面讲解

4.3 你的第一个任务

直接下自然语言任务，例如：

读取当前工作区 src/ 下所有 .ts 文件，统计每个文件的行数，把结果写到一个 report.md 里。

dsh 会自己完成：找文件 → 读内容 → 计算 → 写文件，全程在轨迹里可见。

更复杂的（它最擅长）：

修复这个仓库里所有 .vue 文件的 ESLint 报错，跑一遍 lint，把修改提交成一个 git commit，并写提交说明。

4.4 看懂"权限审批"与轨迹

4.5 四种模式逐个试

想体验怎么做观察点
Standard默认即可完整工具：文件、Shell、网页、搜索
PTC切到 PTC让模型先"写一段代码"来编排多轮工具调用，再执行
Minimal切到 Minimal只有 shell + 文件编辑，看基线能力
Creation切到 Creation可检视运行时、在内存里临时挂插件试验

5CLI 与 Headless 自动化

5.1 dsh 命令总览

# 启动 Web UI（最常用）
npx @deepseek-ai/dsh web

# 查看本机实际启动的插件树
npx @deepseek-ai/dsh --profile web --dump-config

# 用 patch 覆盖某一行配置（不改动源码）
npx @deepseek-ai/dsh --profile web --patch ./my-overlay.yml web

# Headless：一次性跑完任务自动退出（无服务器）
npx @deepseek-ai/dsh --profile headless "运行测试套件并报告失败的测试"

5.2 Headless 模式

适合脚本调用、CI/CD：

# 单次任务：运行并打印结果后自动退出
npx @deepseek-ai/dsh --profile headless "为 src/utils.ts 补单元测试，覆盖率不低于 80%"

Headless 是"无服务器的一次性运行器"，不会常驻端口。

5.3 Python SDK（嵌入工作流）

官方提供 Python SDK，适合把 Harness 嵌入已有系统（CI/CD、自动化测试、批量代码审查）：

# 示意：具体 API 以官方 SDK 文档为准
from deepseek_harness import Harness

h = Harness(profile="headless")
result = h.run("审查 PR #123 的改动并列出风险点")
print(result)
注：SDK 具体接口以仓库 python/ 目录与官方文档为准；预览期可能变动，使用前先看 docs/development.md。

6架构深入

想改 packages/ 之下的东西前，必须读完本节。前提是先懂 Cordis（仓库内有 cordis-primer.md 和 cordis-tutorial/）。

6.1 Cordis：插件贡献 services / events / reversible effects

// 最小插件：心跳定时器（来自社区拆解，最直白展示 effect 可逆性）
export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('tick'), 200)
    return () => { clearInterval(timer); console.log('heartbeat cleaned up') }
  })
}

卸载时 clearInterval 一定被调用——这就是"装什么、收什么"。

6.2 Profiles 与 Bundles：分层组装

每个包在自己的 package.json 用 dsh 字段声明：

6.3 启动树是怎么拼出来的

一个运行中的 dsh = 启动时从有序分层组装出的插件树。层级顺序：

profile 里列出的每个 bundle（按列表顺序）
  → profile 的 cordis.patch.yml
    → 用户级 patch
      → 命令行 --patch 覆盖层

顶层 dsh-base 是每个 profile 的第一层，提供：模型适配器、工具、持久化、沙箱、审批策略、设置、凭据、遥测。其上：

调试口诀：dsh --profile web --dump-config 打印的树，就是真相；任何一行都能被你的 patch 替换。

6.4 核心包（贡献到 Cordis 树）

包负责ctx key
core/session追加式 SessionEvent 日志 + 内存存储ctx.sessions
core/system-prompt系统提示分区 + 工具 schema 组装ctx.systemPrompt
core/tools作用域化工具注册表 + 受保护执行流水线ctx.tools
core/agentAgent 接口、实时注册表、agent/* 事件ctx.agents
core/agent-loop默认驱动，实现该接口（可整体替换）ctx.agentLoop
core/scope每 Agent 作用域注册原语库，无 key
llm/llm消息/流词汇 + 适配器接缝ctx.llm

6.5 事件系统：四种分发模式

事件就是扩展点。Cordis 明确区分四种分发语义，且这是事件的公开契约一部分：

模式await顺序有返回值语义
emit否按注册顺序否观察（fire-and-forget）
waterfall否按注册顺序是环绕式中间件（around-middleware）
parallel是所有监听器并行否扇出
serial是按注册顺序是顺序执行

最关键是 waterfall：相当于 around-middleware。监听器收到 (...args, next)，调用 next() 把（可能被改过的）结果交给下一个；直接 return 不调 next() 就短路整条链。Agent 框架里的拦截全靠它。

事件分三个域：

agent/pre-step、agent/request、llm/stream、三个 tools/* 是 waterfall（监听器必须调 next()）；agent/turn-stopping 是 serial，无 next()。

6.6 Turn / Step 循环流程

turn/start
  claim 下一步输入 + 一条排队的消息
  组装提示分区 + 工具 schema
  -> agent/pre-step            (reject | enter(messages))
       step/start
       把 enter 的消息作为 user/message 追加
       从日志推导模型历史
       agent/request -> llm/stream -> assistant/chunk* -> assistant/message
       tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
       step/end
       工具还欠一次请求 / 新输入到达 -> claim -> 下一个 step
  -> agent/turn-stopping
turn/end

turn/*、step/*、user/message、assistant/*、tool/* 是持久会话事件；其余是三域的实时扩展点。

6.7 会话日志 = 唯一真相源（Single Source of Truth）

Model-visible means logged.（模型能看到的，必被记录。）

所有"模型可见"的数据都必须能从追加式 SessionEvent 流重建，deriveMessages() 投影出模型历史。assistant/chunk 原始流保留以支撑回放和 UI。分叉（fork）、续跑（resume）、轨迹回放、遥测、持久化都从这条流派生——不需要另写快照逻辑。

因此：任何新的"模型可见输入"都必须新增一个会话事件（扩展 SessionEventMap 并从日志渲染）。

6.8 Capability Seam（能力接缝）

Seam = 一个可替换能力，含三角色：

  1. Service Definition（声明接口）
  2. Service Provider（实现它）
  3. Consumer（使用它，常是面向模型的工具）

一个包可兼任多角色，但三者齐备才构成完整 seam。换掉一个 Provider 就全局改变产品——例如把文件系统与子进程 Provider 指向远程沙箱，Bash、PTY、LSP 会一起迁移，无需 fork 任何 Provider。

7插件开发实战

因为"一切皆插件"，插件开发就是主要扩展路径。架构文档建议先读 Cordis primer/tutorial 再动手。

7.1 插件模型

一个 dsh 插件（Cordis 函数插件）长这样：

export const name = 'my-plugin'

// 声明依赖的服务；Cordis 保证 apply 执行时 ctx.tools 已就绪
export const inject = ['tools']

export async function apply(ctx: Context, config: Config) {
  // 注册一个工具（返回 disposer，卸载自动撤销）
  ctx.tools.register(defineTool({
    name: 'my_tool',
    description: '...',
    parameters: { type: 'object', properties: { q: { type: 'string' } } },
    async execute({ q }) { return `处理结果: ${q}` },
  }))

  // 非 Cordis 原生资源，用 ctx.effect 显式绑定生命周期
  ctx.effect(() => {
    const conn = connectExternal()
    return () => conn.close()   // 卸载时执行
  })
}

服务依赖用 inject 声明；外部资源用 ctx.effect() 绑定到插件 fiber 生命周期。这两个机制组合后：任何外部协议集成，只需把它的资源映射到 ctx 上的注册调用。

7.2 注册各种能力（速查）

目标机制ctx key / 事件
加模型提供方在 ctx.llm 注册适配器ctx.llm
加一个面向模型的工具在 ctx.tools 注册（schema 自动进提示组装）ctx.tools
给某会话不同能力集组合 agent preset（其 service 行需 isolate realm）—
加 shell 执行注册 ctx.shell 后端（本地经 ctx.subprocess 拉起）ctx.shell
加持久终端注册 ctx.terminals 后端 + dsh-tool-terminalctx.terminals
加人工命令（不走模型轮次）注册到 ctx.commandsctx.commands
加后台工作注册到 ctx.jobs（job_* 工具收集/停止）ctx.jobs
加文件系统访问/策略注册 ctx.fs Provider 或监听 fs/*ctx.fs
限制派生进程用 ctx.sandbox 后端，consumer 在 spawn 前包 argvctx.sandbox
拦截请求/工具/轮次用对应 agent/* 或 tools/* 事件agent/*, tools/*
注入模型可见上下文调 agent.inject()agent.inject()
加 UI / 编辑器集成驱动 ctx.agents，从 session/event 渲染ctx.agents
加 Web Chat 节点注册 ConversationNodeDefinition + 键控渲染器—
加持久会话状态扩展 SessionEventMap，从日志渲染/回放SessionEventMap
生成会话标题注册唯一的 ctx.sessionTitle Providerctx.sessionTitle
同会话目标管理用 ctx.goals，经 agent/* 续跑ctx.goals
分叉活跃会话ctx.sessions.fork(source, boundary?, childSessionId?)ctx.sessions
把注册限定到某 Agent用该 Agent 的 agent.ctxagent.ctx

7.3 拦截示例（waterfall）

// 在每次模型请求前改写/拦截（agent/pre-step 是 waterfall）
ctx.on('agent/pre-step', (next) => {
  return (payload) => {
    // 改 payload.messages、或 reject 掉
    return next(payload)
  }
})

tools/pre-execute / tools/execute / tools/post-execute 同理可包一层做审计、超时、权限。

7.4 MCP Bridge 是怎么做的（案例，约 170 行）

官方 @deepseek-ai/dsh-mcp-client 是一个标准 Cordis 函数插件，精髓：

  1. serverName 命名空间是 effect-scoped：ctx.effect(() => { names.add(name); return () => names.delete(name) })。两个实例同名 → 后加载的 apply 阶段直接 throw（不是运行时静默覆盖）；HMR 热替换时旧命名空间自动释放。
  2. 连接 supervisor 与 Cordis 无关：startConnection() 返回普通 { ready, dispose() }，只有 ctx.effect(() => () => connection.dispose()) 这一行把生命周期绑到 fiber。
  3. Tool 注册走和原生完全一样的 ctx.tools.register()：MCP tool 和原生 tool 共用同一注册路径 → 模型看到的 schema、权限策略、timeout、compaction 行为完全一致，不存在"MCP tool 是特殊的"这种概念。命名规范 mcp__<server>__<raw> 是纯函数（有损时附 12 字符 SHA-256 防碰撞）。
  4. 重连是通用状态机：connecting → connected → (断开) → backoff → connecting → …，预算耗尽 → disabled；存活超过 maxDelayMs 会重置预算（偶发崩溃可无限恢复，crash-loop 被正确终止）。

7.5 Skill 系统（分层注册表）

Skill 是完整的 Capability Seam。核心数据结构 ScopedLayers 与 ctx.tools 同款分层模型：

读取时，全局层 + 查看者 scope 链逐层合并，近层同名覆盖远层。registerProvider() / register() 返回 disposer。

7.6 打包成 Bundle 并挂载

  1. 在 package.json 声明 dsh 字段：
    • dsh.bundle 指向该 bundle 的 patch 文件（配置行 + 挂载代码）。
  2. 挂载到 profile：
    • 编辑 profile 的 cordis.patch.yml，或
    • 传 --patch 覆盖层。
  3. 发布：给仓库加 dsh-plugin 话题（GitHub topic）提升可发现性。

7.7 推荐工作流

Creation 模式里先试（检视运行时、内存里挂插件）
  → 打包成 Bundle
    → 挂到 Profile（cordis.patch.yml 或 --patch）
      → 用 --dump-config 核对启动树
官方明确在"招揽插件生态"：邀请全球 harness 开发者在开放、可复用、可组合的基建上共建 DSH 插件生态。

8实战案例

8.1 用 harness 改 Slogan 的 H5 底部菜单

（呼应之前"底部菜单栏排序与首页不一致"的问题。）把工作区指向 C:\soft\Slogan\frontend\h5，下任务：

读 src/App.vue 和 src/views/Home.vue，理解底部菜单栏（首页/优惠券/订单/我的）与首页内容的排序关系。如果两者应一致，给出修改方案并直接改 App.vue 让底部栏顺序与首页逻辑一致；改完跑 pnpm build（或 npm run build）确认不报错，并把改动写成一个 git commit。

dsh 会自己：定位文件 → 读代码 → 判断 → 改 → 构建验证 → 提交。你在 Web UI 里逐条审批它的写文件/跑命令操作即可。

8.2 多 Agent 协作

dsh 支持子 Agent 编排（subagent providers 背后是统一接口：从全新子 Agent 到"把一轮委托给另一个产品"都能换）。可以用 Creation 模式或在 profile 里组合不同 agent preset 来做"一个规划 Agent + 多个执行 Agent"的分工。

8.3 上下文压缩与长期记忆（第三方插件）

仓库 compaction/ 包定义了可替换的压缩接口（含基础实现）。社区已有第三方插件做：自适应上下文压缩（ACP）、长期记忆、因果图检索。要做长任务不爆上下文，就挂这类插件——这正是"一切皆插件"的价值所在。

9最佳实践与避坑

9.1 预览期警告（最重要）

9.2 权限策略要显式配置

9.3 密钥安全

9.4 在远程服务器跑 Web UI（如你的阿里云 ECS）

# 在本机执行，把服务器 3080 转到本机 3080
ssh -N -L 3080:127.0.0.1:3080 user@123.57.12.205

然后本机浏览器开 http://127.0.0.1:3080。你的 ECS 已禁用密码登录、仅密钥，这点做得对，继续保持。

9.5 调试技巧

★附录：速查表 / FAQ / 资源

A. 命令速查

npx @deepseek-ai/dsh web                         # 起 Web UI（默认 3080）
npx @deepseek-ai/dsh --profile web --dump-config # 看实际启动插件树
npx @deepseek-ai/dsh --profile headless "任务"    # 一次性跑完退出
npx @deepseek-ai/dsh --profile web --patch x.yml web  # 覆盖层

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

B. 配置字段速查

C. 资源链接

资源链接
GitHub 仓库github.com/deepseek-ai/deepseek-harness
架构文档仓库 docs/architecture.md
Cordis primer/tutorial仓库 docs/cordis-primer.md、docs/cordis-tutorial/
扩展手册仓库 docs/cookbook/（加包/工具/LLM适配器/Chat节点）
Cordis 框架github.com/cordiverse/cordis
Cordis 论文github.com/cordiverse/paper
DeepSeek API 文档api-docs.deepseek.com
申请 Keyplatform.deepseek.com/api_keys
Discord 社区discord.gg/Ycq5dCaS4
插件话题GitHub topic dsh-plugin

D. FAQ

Q：免费开源吗？
A：是，MIT，源码全在 github.com/deepseek-ai/deepseek-harness。预览版 2026-08-13 开放。

Q：能接非 DeepSeek 模型吗？
A：能。模型适配器本身就是插件，可换/加提供方（OpenAI 兼容、Anthropic、本地 vLLM 等）。

Q：四种模式怎么选？
A：Standard 日常；PTC 复杂工作流（模型写代码编排工具）；Minimal 跑分基线；Creation 开发/试验插件。

Q：能上生产吗？
A：预览期不建议。破坏性变更频繁。

Q：和 Claude Code / Codex 比？
A：最大差异是"无特权核心、一切可配置替换" + 追加式会话日志可完整回放。Claude Code/Codex 多为单体核心 + 扩展点。

Q：插件写错会搞崩整个 dsh 吗？
A：不会全局崩——Cordis 的可逆效果保证插件卸载时注册自动撤销；坏的 bundle 用 --dump-config 核对、用 patch 覆盖或移除即可。

一句话收尾：dsh 把"模型能力工程化落地"做成了插件化的 Agent 运行底座——模型、工具、Agent Loop、UI 全可替换，MIT 开源、不绑模型。先 npx @deepseek-ai/dsh web 跑起来，再在 Creation 模式里试写第一个插件。