DeepSeek Harness

DeepSeek Harness 快速入门

DeepSeek 于 2026-08-13 发布的开源 Agent 运行框架（开发者预览版 v0.1）：一切皆插件、模型可换、每次运行全程可追溯，MIT 协议。

这是什么？适合谁？

DeepSeek Harness（命令行名 dsh）是 DeepSeek 出品的开源 Agent Harness——用官方的话说，“模型是智能体的灵魂，Harness 让智能体理解环境、使用工具、在真实场景中持续工作”。它把模型、工具、技能、会话、沙箱、存储、运行循环、调度乃至 UI 全部做成插件，由 Cordis 内核管理插件的挂载、卸载与依赖；开发者不改框架源码，只在配置里选择、替换或扩展任意能力。内置四种运行模式：Standard（完整编程 Agent）、Code（模型生成 TypeScript 代码编排多轮工具调用，即 PTC）、Minimal（只保留 Shell 和文件编辑，用于模型基准测试）、Creator（运行时内试验插件并组合成自定义预设）。所有会话写入同一份仅追加日志，Trajectory 视图可按来源检视系统提示词、推理、工具调用与子代理调度，支持恢复、分叉、检索与回放。发布当天 GitHub 即破 2.4 万 stars（2026-08-13 核验）。

适合谁？三类用户：一是想搭建或研究 Agent 运行框架的开发者——插件化架构和 MIT 协议意味着可以整套拿走改造；二是想低成本用上 DeepSeek 模型的编程用户——一条 npx 命令启动 Web UI，填 API Key 即可干活，按量计费无订阅门槛；三是做模型评测的研究者——Minimal 模式提供最小工具集的纯净基准环境。不适合追求稳定的生产用户：官方明示 v0.1 处于开发者预览，“后续更新可能包含破坏兼容性的改动”。

准备工作

• 运行环境：Node.js（官方未标注最低版本，建议最新 LTS）；源码安装另需 pnpm
• 账号要求：无需注册账号，Web UI 在本机运行（默认 http://127.0.0.1:3080）
• 付费要求：软件本身免费；模型能力走 DeepSeek API 按量计费，需到 platform.deepseek.com 充值并生成 API Key（注意：DeepSeek 官方 2026-08 已公告计划近期上调 API 定价）
• 网络：模型在云端，必须联网；DeepSeek API 国内直连无障碍
• 安全建议：Harness 能在本机执行代码和操作，官方建议在受限虚拟机或容器中运行，并对重要操作开启人工审批

3 步快速上手

第 1 步：一条命令启动 Web UI

npx @deepseek-ai/dsh web

预期输出：命令行打印 Web UI 访问地址（默认 http://127.0.0.1:3080），浏览器打开即可，界面含中文。

第 2 步：配置模型

在 Web UI 打开 设置 → 模型，填入 DeepSeek API 密钥并保存。模型路由立即生效，无需重启服务。想接其他厂商模型，按模型配置指南填自定义 OpenAI 兼容端点。

第 3 步：选工作区，跑第一个任务

点击 选择工作区，添加启动 dsh 时所在的项目目录并选中（未选中工作区时会话输入框不可用）。然后发起会话，例如输入：“Summarize this repository and identify its main packages.”预期输出：Agent 会读取工作区文件、运行命令、维护计划并给出结构说明；遇到权限策略要求审批的操作时，Web UI 会先弹窗询问。

常见踩坑

踩坑 1：会话输入框灰色不可输入

• 症状：打开 Web UI 后无法发送消息
• 原因：未选中工作区
• 解决：点击”选择工作区”，添加启动 dsh 时的项目目录并选中它

踩坑 2：模型始终无响应

• 症状：发消息后直接报错或无输出
• 原因：未配置 API Key，或 Key 对应账户余额不足
• 解决：设置 → 模型 检查密钥；到 platform.deepseek.com 控制台确认余额与 Key 状态

踩坑 3：找不到 3080 端口的页面

• 症状：浏览器访问 127.0.0.1:3080 打不开
• 原因：默认端口被占用或启动失败
• 解决：以命令行实际打印的地址为准；检查终端报错信息

踩坑 4：升级后配置或插件失效

• 症状：某次 npx 拉到新版本后旧预设/插件报错
• 原因：v0.1 开发者预览期，官方明示存在兼容性破坏变更
• 解决：锁定版本号使用（如 npx @deepseek-ai/dsh@0.1.0-rc.6 web），升级前读仓库 release 说明

踩坑 5：Agent 执行了意料之外的命令

• 症状：会话中出现未预期的文件改动或 Shell 命令
• 原因：提示注入或指令过于宽泛，Agent 权限过高
• 解决：官方建议将重要操作设为需人工审批、复杂指令拆成小步、在容器/虚拟机中运行，只安装可信来源的插件与 MCP 服务

初级用法

1. Standard 模式日常编程：完整工具集（文件编辑、Shell、文件/网页搜索、技能、计划、子代理、工作流），覆盖大多数编码任务。

2. 用 Trajectory 视图审计每次运行：系统提示词、推理、工具调用、上下文注入全部按来源可查——调试 Agent 行为、定位”它为什么这么干”的利器。

3. 会话分叉（fork）做方案对比：同一任务分叉出两条会话分别尝试不同思路，比较结果后保留优解，日志同源可回放。

高级玩法

1. Code 模式（PTC）编排复杂任务：模型把多步操作写成一个 TypeScript 程序连续调用工具，适合”批量重构 + 跑测试 + 汇总报告”这类多轮流水线，比逐次工具调用更省轮次。

2. Creator 模式自造 Agent 预设：在运行时内检视当前环境、在内存中试验 Cordis 插件并组合成新模式，配合预设编写指引产出自己的 Agent 配置。

3. 开发 dsh 插件接入生态：模型、工具、UI 都是插件，可按开发文档编写自己的 Cordis 插件；给仓库加 dsh-plugin topic 即可被社区插件市场发现。需要程序化集成时用官方 Python SDK 而非 shell 包裹。

小技巧

• 国内拉 npm 包慢时切换镜像源；锁定具体版本号可避免预览期破坏性更新
• 本地会话、API Key 默认不上传服务器；如在意匿名配置上报，可在设置中关闭
• 跑不可信项目时放进 Docker 容器，限制文件系统与网络权限
• Minimal 模式只有两个工具，是横向对比不同模型裸能力的干净环境
• 模型端点可换成任何 OpenAI 兼容服务，本地开源模型也能接

常见问题 FAQ

Q: DeepSeek Harness 免费吗？ A: 软件 MIT 协议开源免费；模型能力按 DeepSeek API 用量计费（价格见官方定价页），也可接入自有的 OpenAI 兼容端点，无订阅门槛。

Q: 和 Claude Code 比怎么选？ A: Claude Code 是闭源订阅制的成品工具，开箱即用、生态成熟；DeepSeek Harness 是开源的 Agent 框架/运行时——模型可换、所有能力都是插件可重组、可自托管，但 v0.1 仍是早期预览。要稳定省心选前者，要可定制和低成本选后者。

Q: 必须用 DeepSeek 的模型吗？ A: 不是。官方文档明确支持其他模型提供方和自定义 OpenAI 兼容端点，模型本身也是可替换的插件。

Q: 我的代码和会话会被上传或用于训练吗？ A: 官方数据处理政策写明：Harness 是 local-first 产品，用户输入、模型输出、工具调用记录、API Key 等默认本地存储、未经同意不上传；会为改进产品上报匿名化配置信息，可关闭。但若你调用了第三方模型、网页工具、MCP 服务或插件，那部分数据由对应服务商按其政策处理。

Q: 能用于生产环境吗？ A: 不建议。当前为 v0.1 开发者预览，官方明示核心插件与 API 会持续调整、更新可能破坏兼容性，适合评估、研究和二次开发，关键生产环境请等稳定版。

参考链接

• 官网（产品页）：https://www.deepseek.com/harness/
• GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
• 开发者文档（快速上手）：https://deepseek-harness.github.io/deepseek-harness/guide/quickstart
• npm 包 @deepseek-ai/dsh：https://www.npmjs.com/package/@deepseek-ai/dsh
• 数据处理政策：https://www.deepseek.com/harness/data-processing/
• 使用政策（安全建议与限制）：https://www.deepseek.com/harness/privacy/
• DeepSeek API 定价：https://api-docs.deepseek.com/quick_start/pricing
• Cordis 插件框架（底层内核）：https://github.com/cordiverse/cordis

相关产品

• DeepSeek：本工具默认调用的模型提供方——V4 系列模型与 API 详情见收录页

本文基于官方文档和公开资料整理，AI辅助生成。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。