DeepSeek Harness 保姆级入门：1 小时破 2.2 万星的开源 Agent 框架，安装 + 上手全攻略

大威001

385人浏览 · 2026-08-14 22:37:24

大威001 · 2026-08-14 22:37:24 发布

DeepSeek Harness 保姆级入门：1 小时破 2.2 万星的开源 Agent 框架，安装 + 上手全攻略

还在眼馋 Claude Code / OpenAI Codex？DeepSeek 官方 Agent 框架 Harness 终于开源了！
GitHub 史上最快涨星纪录、“一切皆插件”、省 Token 神技，本文带你从零安装到跑通第一个任务。

在这里插入图片描述

一、为什么这篇值得你读完？

先看几个数字：

2026 年 8 月 13 日，DeepSeek 正式开源其首款 Agent 产品 DeepSeek Harness（简称 dsh），采用 MIT 协议，v0.1 开发者预览版。
仓库公开后 半小时破万星，约 1.5 小时突破 2.2 万星，发布 12 小时左右冲到 5 万星，创下 GitHub 史上最快涨星纪录。
作为对比：此前增长最快的 xAI Grok-1 破 2 万星用了约 1.2 天，DeepSeek R1 用了 5.7 天。
发布当天，DeepSeek 还同步发布了 V4 Pro 正式版，形成"模型 + 框架"的组合拳。

一句话总结：这是"AI 界的 Android"，是 DeepSeek 正面迎战 Claude Code 和 OpenAI Codex 的杀手锏。

这篇文章会从"是什么 → 为什么火 → 怎么装 → 怎么用 → 注意事项"完整带你走一遍，跟着做就能跑起来。

二、DeepSeek Harness 是什么？

2.1 一句话定义

DeepSeek Harness 是一个"一切皆插件"的 Agent 运行时框架（Agent Harness），用 TypeScript 编写，让大模型从"只会回答问题"变成"能替你干活"。

它不是一个封闭的产品（不像 Claude Code），而是一个元框架（Meta-framework）——你可以把它理解成"组装 Agent 的乐高底座"。

2.2 核心公式

Model + Harness = Agent

Model（模型）：负责"思考"，是大脑。
Harness（框架）：负责"执行"，是手脚——调度上下文、调用工具、维护任务状态、处理反馈。

聊天机器人交付的是一段话，而 Agent 交付的是一件做完的事（读写文件、执行命令、拆分任务、持续工作……）。

2.3 产品定位

维度	说明
对标产品	Anthropic Claude Code、OpenAI Codex
主打场景	编程、办公等 AI 生产力场景
技术栈	Node.js / TypeScript（而非 AI 圈常见的 Python）
架构基础	Cordis 驱动（开源聊天机器人框架 Koishi 的同源技术）
设计依据	论文《A Programming Paradigm for Spatiotemporal Composability》
模型兼容	支持 40+ 家模型供应商（DeepSeek、Anthropic、OpenAI 等，模型无关）
开源协议	MIT

小知识：Harness 架构负责人是崔添翼——正是 Koishi 作者（前 Jane Street 量化交易开发，2026 年 3 月加入 DeepSeek）。所以你能在架构里看到很多 Koishi / Cordis 的影子。

三、核心设计理念：“一切皆插件”（Everything is a Plugin）

这是 Harness 最核心、最性感的特性。

在 Harness 里，几乎每一个能力都是一个插件：

模型适配器
工具注册
会话日志
Agent 主循环
沙箱
审批策略
甚至 UI 前端

全部可以自由替换、灵活重组。开发者无需修改任何源码，就能独立选择、替换或扩展任意一个能力——甚至可以让 Agent"改装自己"。

这带来的实际价值：

模型无关：今天用 DeepSeek，明天换 Claude/OpenAI，改个插件就行。
极致可扩展：任何团队都能为它写自己的插件，生态滚雪球。
省 Token：见下文 PTC 模式。

四、四种运行模式，一次看懂

Harness 官方预设了 4 种模式，开箱即用：

模式	说明	适用场景
标准模式	提供完整工具组合	日常复杂任务、日常开发
PTC 模式	程序化工具调用（Programmatic Tool Calling）：让模型生成 TypeScript 代码来编排多轮工具调用，中间数据留在运行环境	大幅降低 Token 消耗，高 Token 场景福音
极简模式	只保留 Shell 和文件编辑工具	最小环境下的模型基准测试（V4-Flash 刷榜 Terminal Bench 用的就是它）
创造模式	检查当前运行时、在内存中试验 Cordis 插件并创作新模式	插件开发、让 Agent 改装自身

划重点：PTC 模式是省钱神器。传统 Agent 每轮工具调用都要把上下文传来传去，Token 烧得飞快；PTC 让模型写代码把多轮调用"编成程序"在本地跑，中间数据不用来回传，Token 消耗大幅下降。

五、核心特性盘点

✅ 开源 + MIT 协议，可商用、可二开
✅ 本地运行，数据自己掌控，隐私友好
✅ 工作区隔离：Agent 只能操作你明确选择的目录，危险操作弹确认
✅ 仅追加（append-only）会话日志：支持恢复、分叉、检索、回放
✅ CLI + Web UI + Python SDK 三种接入方式
✅ 40+ 模型供应商，模型随便换
✅ 跨端：Web、桌面端、移动端、服务端都能跑

六、安装教程（保姆级，建议收藏）

6.1 环境要求

项目	要求
操作系统	Windows 10+ / macOS 10.15+ / 主流 Linux（x64 / arm64）
Node.js	建议 v22.19 及以上（v18+ 也可运行，推荐 v22+）
包管理器	源码安装需要 pnpm（`npm install -g pnpm`）
API Key	DeepSeek 或其他兼容提供方密钥（启动后在界面里配置）
可选	Python 3.10+（用 Python SDK 时）、Git

⚠️ 安装前先确认 Node.js 版本：
node -v
版本低于 v18 的话，建议先去 nodejs.org 装一个 LTS 版本。

6.2 方法一：npm 一行命令启动（推荐，最快）

只要装了 Node.js，在终端执行：

npx -y @deepseek-ai/dsh web

首次运行会自动下载相关包，耐心等一会儿。
启动成功后，浏览器打开：http://127.0.0.1:3080
默认端口 3080，想换端口加参数：npx -y @deepseek-ai/dsh --profile web --port 8080

💡 想全局安装以后直接用 dsh 命令的话：
npm install -g @deepseek-ai/dsh
dsh web

6.3 方法二：从源码运行（适合想二次开发的同学）

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

# 2. 安装依赖
pnpm install

# 3. 构建
pnpm run build

# 4. 启动 Web UI
pnpm dsh web

6.4 方法三：Python SDK（程序化调用，适合脚本/自动化）

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

# 2. 创建虚拟环境（推荐）
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate

# 3. 安装 SDK
pip install deepseek-harness-sdk

# 4. 配置密钥
export DEEPSEEK_API_KEY=你的密钥

之后可以参考仓库 examples 目录下的示例脚本进行调用。

📌 小贴士：SDK 的包名和 API 在快速迭代中可能调整，以官方仓库最新 README 为准。

6.5 三种方式怎么选？

需求	选哪种
只是体验一下、快速上手	方法一 npx
想改源码 / 贡献代码 / 写插件	方法二源码
想集成进自己的 Python 项目 / 脚本	方法三 Python SDK

七、快速上手：跑通你的第一个任务

7.1 Web UI 三步走

配置模型：打开 设置 → 模型，填入 API Key（DeepSeek 或其他供应商），保存。
选择工作区：添加/选择一个工作目录（Agent 只能在这个目录里活动）。
选模式、发任务：选标准模式（或 PTC 模式省 Token），输入你的任务，回车。

7.2 Headless 模式（命令行跑一次性任务）

适合脚本化、CI 集成的场景：

dsh --profile headless "你好，请用一句话介绍你自己"

特点：

创建全新的持久化 Agent → 提交任务 → 等待完成 → 输出最后一个非空回复。
成功退出码 0，失败退出码 1。
不挂载 HTTP 服务、不监听端口，纯净命令行运行。

八、进阶：dsh CLI 常用参数

8.1 Launcher 参数（必须写在最前面）

dsh --profile <名称>          # 启动指定 profile（web / headless 首次自动初始化）
dsh --patch <文件路径>        # 叠加配置覆盖层，可重复指定
dsh -V / --version            # 查看启动器版本
dsh --dump-default-config     # 打印默认配置树（不启动）

8.2 配置分层机制（了解即可）

生效配置按层叠加，后应用层优先：

空根节点
  → profile 自带的 bundles patch
  → profile 的 cordis.patch.yml
  → 全局 $DSH_HOME/cordis.patch.yml（机器级偏好）
  → 各 --patch 覆盖层

配置出问题时，dsh --dump-default-config 是排查神器。

九、重要提醒 & 避坑指南

这是开发者预览版！ 官方明确警告会有 Breaking Changes，插件 API 和配置 schema 尚未稳定，不适合直接上生产环境的关键流程。
安装命令认准官方仓库：GitHub 上出现了同名但不同来源的第三方 Python 项目（pip install deepseek-harness-cli），它的 dsh 子命令和官方不一样，注意区分。官方仓库是 deepseek-ai/deepseek-harness。
供应链风险：用 npx 执行远程代码或安装第三方插件时，注意版本锁定和权限策略，别乱装不明插件。
Coding Agent 成熟度：目前与 Claude Code / Codex 在权限模型、差异审阅、IDE 集成等方面还有差距，别期待一步到位。
硬件要求不高：普通笔记本就能跑 Web 界面，但建议单独准备一个练习目录作为工作区，避免误操作重要文件。
Community 反馈渠道：GitHub Discussions；写插件想被更多人发现，可以给插件仓库加 dsh-plugin 话题。