github

DeepSeek Harness 全面解析：从安装到实战的 AI Agent 框架指南

📅 2026/8/14 👁️ 215 阅读 ✏️ 2026/8/14 更新

什么是 DeepSeek Harness

2026年8月13日，DeepSeek 在发布 V4 Pro 正式版的同一晚，突然以 MIT 协议开源了一个名为 DeepSeek Harness（简称 DSH，命令行工具名 dsh）的项目。上线不到24小时，GitHub Star 数突破8万，成为2026年开源社区最受关注的 AI 基础设施项目之一。

DeepSeek 在招聘时提出过一个公式：

text
Agent = Model + Harness

光有模型，它只会跟你聊天；加上 Harness，它才能读你的代码、跑你的命令、改你的文件、搜索网页、调度子任务——直到把一整件事办完。模型是灵魂，Harness 是让灵魂能在你电脑上动手的那具身体。

简单来说，DeepSeek Harness 是一个让大语言模型变成真正可用 Agent 的运行框架。它替模型记住上下文、调用工具、在文件和终端之间跑腿，把模型从一个「只能对话的聊天机器人」变成一个「能干活的智能体」。

与传统评测框架的区别

需要特别澄清一个概念混淆：在 AI 领域，"Harness" 一词有两种含义。一种是评测框架（如 lm-eval-harness），用于在 MMLU、GSM8K、HumanEval 等基准上测试模型性能，不执行具体业务任务。另一种是 Agent 运行框架，如 DeepSeek Harness，它让模型能够在真实环境中执行任务。

DeepSeek Harness 属于后者——它不「出考卷打分」，而是让模型在真实开发环境中干活。

定位：对标 Claude Code 和 Codex

DeepSeek Harness 的直接竞品是 Anthropic 的 Claude Code 和 OpenAI 的 Codex。但 DSH 走了一条截然不同的路：

| 特性 | Claude Code | OpenAI Codex | DeepSeek Harness |
|------|------------|--------------|------------------|
| 开源协议 | 闭源 | 闭源 | MIT 开源 |
| 模型绑定 | Anthropic 模型 | OpenAI 模型 | 任意模型可替换 |
| 工具能力 | 固定工具集 | 固定工具集 | 一切皆插件 |
| 界面可改 | 不可改 | 不可改 | UI 也是插件 |
| 价格策略 | 模型+外壳一起卖 | 模型+外壳一起卖 | 外壳免费开源 |

DeepSeek 的策略很清晰：把 Agent 外壳这一层拉平为公共品，让竞争回到模型本身的能力和价格上——而那正是 DeepSeek 的主场。

核心架构：一切皆插件

DeepSeek Harness 最核心的设计理念只有一句话：Everything is a Plugin（一切皆插件）。

这意味着框架中的每一个能力模块都是可插拔、可替换的：

  • 模型：DeepSeek 自己的模型也只是又一个插件，换成 Kimi、GLM、Qwen 或任何 OpenAI 兼容端点，操作和换皮肤一样简单

  • 工具：文件编辑、Shell 命令、网页搜索等都是独立插件

  • 技能：可加载/卸载的能力包

  • 会话：会话管理策略可替换

  • 沙箱：代码执行隔离方案可选

  • 存储：持久化方案可配置

  • 调度循环：Agent 的工作循环机制可定制

  • UI：连你看到的 Web 界面都是插件

    • Cordis 微内核

    这一切的基础是 Cordis——一个从 Koishi（国内老牌 QQ 机器人框架）中抽取的微内核，作者是 GitHub 上的 Shigma。Cordis 只管三件事：

  • 加载插件

  • 卸载插件

  • 管理插件之间的依赖关系

    • Cordis 本身不提供任何 Agent 能力，它是主板上的插槽，具体能力全靠插上去的插件卡。它有一个关键特性叫可逆副作用——每个插件注册时产生的所有副作用都会被追踪，卸载时自动回收，不留垃圾、不漏内存。这意味着插件可以热插拔：装插件、卸插件、换整套 UI，都不用重启。

    配置即组合

    开发者无需改动 DeepSeek Harness 源码，仅通过配置文件就能选择、替换或扩展任意一项能力。这种设计让 DSH 的灵活性达到了前所未有的程度——你甚至可以同时挂载多个模型插件，在不同任务间自动切换。

    Session Log：每次运行都可追溯

    DeepSeek Harness 的另一个关键设计是 Session Log（会话日志）。

    项目规定了一条铁律：凡是模型看到的内容，都必须能够从日志中重建。

    具体来说，以下所有内容都会被写入只增不改（append-only）的事件流：

  • 用户消息

  • 运行环境上下文

  • 模型请求信息

  • 流式输出

  • 工具调用和结果

  • 压缩事件

  • 权限切换记录

  • 取消原因

  • 子 Agent 调度

  • 每一次上下文注入

    • 在 Web UI 的 Trajectory（轨迹） 视图中，你可以按来源逐条检查这些记录。恢复（Resume）、分叉（Fork）、搜索（Search）、重放（Replay）都基于同一个事件流操作。

    这个设计解决了 Agent 系统中最难的问题：当 Agent 出了错，你能不能搞清楚它当时到底看到了什么、为什么这么做。 传统工具全程黑盒，最后只甩给你一个结果；DSH 把每一步都摊开在时间线上，出了问题可以逐条复盘。

    前缀缓存与成本优化

    Session Log 的只增不改特性还有一个重要的副作用：天然优化前缀缓存命中率。

    每一回合请求中，系统提示词、工具定义、已注入的技能、会话历史这些内容全部排在消息序列最前面，只要你不中途切模型或切模式，它们字节级不变。这正是前缀缓存最理想的命中对象。

    实测数据显示，在一次6轮、115步的 Agent 任务中，缓存命中率高达 99%——1540万输入 token 中只有不到1%是真正新发给模型的。DeepSeek 的缓存命中输入价比未命中价低一到两个数量级，99% 命中意味着实际输入成本只有全 miss 的零头。

    四种运行模式

    DeepSeek Harness 内置四种运行模式，本质是四份不同的插件配置清单。官方模式和社区做的整合包在地位上没有任何差别——都是插件组合。

    标准模式（Standard Mode）

    完整的编程 Agent，开箱即用工具包括：

  • 文件编辑器

  • Shell 命令执行

  • 文件搜索和网页搜索

  • 技能系统

  • 任务规划和目标管理

  • 子 Agent 调度

  • 工作流编排

    • 适合日常开发场景，新手首选。

    代码模式（Code Mode / PTC）

    PTC（Programmatic Tool Calling，程序化工具调用）是 DSH 最有特色的模式。

    传统模式下，模型每调用一次工具就需要跟客户端来回一次——十次工具调用就是十轮网络往返。PTC 模式换了个思路：让模型直接产出一段 TypeScript 脚本，把多步操作串起来一次执行完毕。

    typescript
    // PTC 模式示例：模型生成的工具编排脚本
import { tools } from '@deepseek-ai/dsh-code-sdk';

async function main() {
  // 一次性读取多个文件，不需要逐轮往返
  const files = await tools.readFiles(['src/index.ts', 'src/utils.ts', 'package.json']);
  
  // 批量执行 Shell 命令
  const lintResult = await tools.shell('npm run lint');
  const testResult = await tools.shell('npm test');
  
  // 根据结果决定下一步
  if (lintResult.exitCode !== 0) {
    await tools.fileEdit('src/index.ts', lintResult.fixes);
  }
  
  return { files, lint: lintResult, test: testResult };
}

    好处是快、省 token（十次来回合并成一次执行）；坏处是这段代码跑起来你需要想清楚它在干什么——所以沙箱和权限策略要配好。

    极简模式（Minimal Mode）

    只保留两个工具：一个持久化 bash 和一个文件编辑器（str_replace_editor）。没有搜索、没有技能、没有子 Agent——干净利落，啥花活都没有。

    适合两类场景：

  • 跑基准测试，看模型裸实力

  • 在最小环境中验证模型基础能力

    • 创造模式（Creator Mode）

    面向高阶玩家，支持：

  • 检查当前运行时状态

  • 在内存中热加载 Cordis 插件

  • 测试插件组合

  • 创建自定义 Agent 预设

    • 属于"用框架改框架，自己套自己"的玩法。

    模式选择建议

    | 场景 | 推荐模式 | 原因 |
    |------|---------|------|
    | 第一次使用 | 极简模式 | 感受 DSH 节奏，小目录跑简单任务 |
    | 日常开发 | 标准模式 | 全能工具集，开箱即用 |
    | 高频工具调用 | 代码模式 | 省时省 token，批量操作 |
    | 开发插件 | 创造模式 | 热加载测试，运行时检查 |

    安装教程：四种方式任选

    前置要求


  • Node.js v22.19 以上 或 v24+（用 node --version 确认，低版本会报错）

  • 操作系统：macOS、Linux、Windows 均可（Windows 优先用 Web UI）

    • 方式一：npx 一键启动（推荐新手）

    最快的方式，不需要全局安装：

    bash
    # 确认 Node.js 版本
node --version
# 输出应为 v22.19.0 或更高

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

    执行后会自动下载最新版 DSH 并启动本地服务，终端会显示：

    text
    DeepSeek Harness is running at http://127.0.0.1:3080

    浏览器打开 http://127.0.0.1:3080 即可进入 Web UI。默认地址是本地回环，不对外暴露，不用担心别人连进来。

    方式二：全局安装（适合日常使用）

    如果你打算长期使用，全局安装更方便：

    bash
    # 全局安装 DSH CLI
npm install -g @deepseek-ai/dsh

# 启动 Web UI
dsh web

# 查看帮助
dsh --help

    全局安装的好处是版本固定，不会每次 npx 都检查更新，启动更快。

    方式三：源码编译安装（适合开发者）

    想读源码、追最新提交或贡献代码的用户：

    bash
    # 安装 pnpm（如果没有）
npm install -g pnpm

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装依赖
pnpm install

# 构建
pnpm run build

# 启动
pnpm dsh web

    源码安装后可以修改代码、调试插件、提交 PR。项目使用 TypeScript，架构分为 Host 和 Client 两个聚合，分别对应 tsconfig.host.json 和 tsconfig.client.json。

    方式四：Python SDK（适合 CI/CD 集成）

    DSH 还提供了 Python SDK，可以嵌入 CI/CD 管道或自动化脚本中：

    bash
    pip install deepseek-harness-sdk

    python
    from deepseek_harness import DSHClient

# 初始化客户端
client = DSHClient(
    api_key="sk-your-deepseek-api-key",
    workspace="./my-project"
)

# 创建 Agent 会话
session = client.create_session(mode="standard")

# 发送任务
result = session.run("分析这个项目的架构，列出主要模块和它们的依赖关系")

print(result.summary)
print(f"Steps: {result.steps}")
print(f"Cache hit rate: {result.cache_hit_rate}%")

    首次使用配置指南

    第一步：配置 API Key

    Web UI 加载完成后，输入框默认是灰色的，必须先配置 API Key。

  • 进入 Settings → Models

  • 找到 DeepSeek 那张卡片

  • 填入你的 sk-... API Key（在 DeepSeek 开放平台创建）

  • 点击保存

    • Key 存储在本地配置目录中，界面只显示脱敏后的描述符，不会回显明文。第一次打开会直接弹出填 Key 的引导页面。

    第二步：切换语言为中文


  • 点击左下角 Settings

  • 找到 Language 选项

  • 切换为中文

    • 第三步：添加工作区


  • 点击「选择工作区」

  • 添加一个你想让 Agent 操作的项目目录

  • 选中该目录，输入框才会解锁

    • 你在哪个目录启动的 dsh web，那个目录就是默认工作区，但需要手动点一下选中。

    第四步：选择运行模式

    根据前面的模式选择建议，初次使用建议选择极简模式或标准模式。

    第五步：开始使用

    在输入框输入任务，例如：

    text
    总结这个仓库，告诉我主要的包结构和模块依赖关系

    Agent 会自动读文件、跑命令、维护执行计划。涉及写操作时，UI 会按权限策略弹出审批确认。

    模型切换：不限于 DeepSeek

    DSH 最实用的特性之一是模型可替换——DeepSeek 自己的模型也只是又一个插件。

    预设模型接入

    设置中点 Models → 添加提供方，可以看到一长串预设列表：

    | 模型厂商 | 提供方标识 | 说明 |
    |---------|-----------|------|
    | DeepSeek | deepseek | 默认，官方模型 |
    | 智谱 GLM | zai-coding-cn | 国产，性价比高 |
    | 阿里千问 | qwen-token-plan-cn | 通义千问系列 |
    | 小米大模型 | xiaomi | 小米 MiMo 系列 |
    | OpenAI | openai | GPT 系列 |
    | Anthropic | anthropic | Claude 系列 |

    选择对应提供方，填入 API Key 保存即可，回到首页就能在模型列表中切换。

    自定义模型接入

    不在预设列表中的厂商（如火山方舟），可以添加自定义提供方：

  • 协议选择 OpenAI 兼容

  • 填入 API 地址（如火山方舟的 coding 接口地址）

  • 填入 API Key

  • 点击「获取可用模型」验证连通性

  • 选择需要的模型（建议只挑常用的，不要全选）

  • 回到会话发送测试消息验证

    • 插件生态

    DeepSeek Harness 开源后，社区反应极快。GitHub 上打 dsh-plugin 标签的仓库在发布一周内就超过 1000 个。

    推荐插件

    以下是一些高质量的社区插件：

    dsh-vision-toolkit：给纯文本的 DeepSeek 模型加上视觉能力，支持带意图的图片问答、长截图 OCR、UI 还原、像素对比。

    dsh-TUI：把整个交互换成 Claude Code 风格的全屏终端界面，包含像素鲸鱼顶栏、流式思考展开、上下文进度条和 TPS 表。

    dsh-web-ui：Web UI 增强全家桶，包含任务看板、Git 图谱、右侧面板、手机端远程界面、实时 token 统计和皮肤中心。

    DSH-better-sidebar：侧边栏改造为完整工作台，内置文件渲染编辑器、终端、Git 面板和子代理管理。

    dsh-ui-whale：在会话标题栏养一只手绘像素鲸鱼桌宠，空闲时眨眼游来游去，思考时会动，回合结束时喷水。

    插件安装方式

    最 DSH 的安装方式是：把仓库地址丢给对话框里的 Agent，用自然语言说「帮我装这个插件」，它自己读完 README 就把活干了。遇到需要改配置或重启时会停下来等你批权限。

    插件开发

    开发者可以参考项目文档中的插件开发指南，为你的插件仓库添加 dsh-plugin 话题标签，便于社区发现。官方提供了完整的 Cordis 插件 API 文档和示例代码。

    Session Log 实战分析

    以下是一次真实 Agent 任务的 Trajectory 统计数据：

    text
    6 轮 · 115 步
LLM 思考时间: 16m20s
工具调用时间: 2m33s
首 token 平均延迟: 1.6s
输出速度: 145 tok/s
缓存命中率: 99%
输入 token: 15.4M
输出 token: 1.16M

    关键分析：

  • 115 步：6 轮对话中真正干活的只有4轮，但 Agent 在后台跑了115步操作（读文件、调工具等），说明 Agent 场景下 token 消耗和聊天轮数基本无关，全看它在背后调了多少轮工具

  • 99% 缓存命中率：1540万输入 token 中只有不到1%是真正新发给模型的，DeepSeek 的缓存命中价比未命中价低1-2个数量级，实际输入成本只有全 miss 的零头

  • 缓存命中率保持方法：不要在会话中途反复启停会影响系统提示词或工具列表的插件，不要中途切模型或切模式

    • 与竞品对比分析

    | 维度 | DeepSeek Harness | Claude Code | Cursor | Aider |
    |------|-----------------|-------------|--------|-------|
    | 开源协议 | MIT | 闭源 | 闭源 | Apache 2.0 |
    | 模型可替换 | 任意模型 | 仅 Claude | 多模型 | 多模型 |
    | 插件系统 | 完整插件架构 | 无 | 有限扩展 | 无 |
    | 运行模式 | 4种模式 | 1种 | 1种 | 1种 |
    | 可追溯性 | 完整 Session Log | 部分 | 无 | 部分 |
    | 热插拔 | 支持 | 不支持 | 不支持 | 不支持 |
    | UI 可定制 | UI 也是插件 | 不可改 | 有限 | 不可改 |
    | 部署方式 | 本地部署 | 云端+本地 | 本地应用 | CLI |
    | 成本 | 框架免费，仅付模型 API | 订阅制 | 订阅制 | 免费+模型费 |

    注意事项与常见坑

    1. Node.js 版本必须够新

    官方要求 Node.js v22.19 以上或 v24+。低版本 npx 会报一堆看不懂的错误，先 node --version 确认，不要拿 v18/v20 硬怼。

    2. 目前是开发者预览版

    官方 README 用全大写字母写了一句话：THERE WILL BE COMPATIBILITY-BREAKING CHANGES。一定会有破坏兼容性的变更，不要现在就把它接到生产关键路径上。

    3. Bash 空转 Bug

    某些情况下 Agent 会反复执行空的 Bash 命令不推进任务，这是已知 Bug。遇到就手动中断重新发起。

    4. 安全攻击面较大

    插件能接触你的 Shell 和文件系统，第三方插件安装前务必看一眼源码。已有安全团队发布了可复现的攻击链演示和验证工具。

    5. Windows 用户优先用 Web UI

    Windows 原生环境下 Python SDK 的兼容性可能有问题，建议直接使用 npx @deepseek-ai/dsh web，需要脚本化时考虑 WSL。

    6. 装完插件记得重启

    安装新插件后需要重启 DSH 并硬刷新浏览器页面（Ctrl+Shift+R 或 Cmd+Shift+R），否则缓存可能导致插件不生效。

    总结

    DeepSeek Harness 代表了 AI Agent 框架的一个新方向：不再把 Agent 外壳当作封闭的商业壁垒，而是将其开源为公共基础设施。

    对于开发者来说，DSH 提供了几个独特价值：

  • 零成本上手：npx @deepseek-ai/dsh web 一行命令启动

  • 极致灵活：模型、工具、UI 都可替换，一切皆插件

  • 完全可追溯：Session Log 让每次 Agent 运行都可复盘

  • 成本优化：99% 前缀缓存命中率大幅降低 API 费用

  • 生态繁荣：社区已贡献超过1000个插件

    • 无论你是想找一个更好的编码助手、研究 Agent 架构、还是开发自己的 AI 工具，DeepSeek Harness 都值得一试。开源第一天8万 Star 的热度已经说明了一切——这个项目正在重新定义 AI Agent 的构建方式。

    项目地址：https://github.com/deepseek-ai/deepseek-harness

    官方文档：https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart

    社区插件目录：https://github.com/topics/dsh-plugin

    💬 评论区 (0)

    0/500

    暂无评论，快来抢沙发吧！