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"改装自己"。

这带来的实际价值：

  1. 模型无关：今天用 DeepSeek，明天换 Claude/OpenAI，改个插件就行。
  2. 极致可扩展：任何团队都能为它写自己的插件，生态滚雪球。
  3. 省 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 三步走

  1. 配置模型：打开 设置 → 模型，填入 API Key（DeepSeek 或其他供应商），保存。
  2. 选择工作区：添加/选择一个工作目录（Agent 只能在这个目录里活动）。
  3. 选模式、发任务：选标准模式（或 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 是排查神器。

九、重要提醒 & 避坑指南

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

十、总结

DeepSeek Harness 的意义，不只是多了一个开源框架，而是DeepSeek 正式把"模型 + 框架"组合拳打出来了：

  • 对开发者：一个模型无关、可插拔、省 Token 的 Agent 底座，生态刚刚起步，上车越早红利越大。
  • 对普通用户：本地可控、隐私友好的 AI 助手，自己动手搭建一个专属 Agent 不再是程序员专利。
  • 对行业：GitHub 史上最快涨星纪录，说明"开源 Agent 框架"的需求被严重低估了。

如果你还在观望，不如现在就打开终端跑一句：

npx -y @deepseek-ai/dsh web

这个框架迭代极快，今天写的教程可能下个月就变了。建议收藏本文 + Star 官方仓库，持续跟进。

如果你觉得这篇文章有用，欢迎 点赞 👍 + 收藏 ⭐ + 关注 🚀，我会持续输出 DeepSeek / Agent 方向的最新实践！

参考资料

⚠️ 本教程写于 2026-08-14，基于当时公开信息整理。由于项目处于快速迭代期，安装命令、包名、API 均以官方仓库最新 README 为准。

# 开源
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

初识智能体

在过去两年中，几乎所有人都体验过大语言模型（如 ChatGPT、Claude、DeepSeek）的强大能力：写周报、润色邮件、解答编程疑难。被动响应：你问一句，它答一句。如果你的 Prompt 没有写清楚约束条件，它无法主动追问或修正目标。知行脱节：大模型能用流畅的文字告诉你“如何部署一个高可用 K8s 集群”，但它无法替你登录服务器敲下命令、查看报错日志并自动回滚。信息孤岛：大模型的知识止步于预

avatar DeepSeek技术社区

DeepSeek总结的时间旅行者的主键

来源：https://www.pgedge.com/blog/the-time-traveler-s-primary-key。

avatar DeepSeek技术社区

Google能索引，AI却抓不到

很多技术团队有个错觉：只要Google能正常收录，内容就没问题。但现实是，你的页面在Google搜索结果里好好的，在ChatGPT、Perplexity、Claude的答案里却像从未存在过一样。

avatar DeepSeek技术社区