（来源：机器学习算法那些事）

一行命令跑起来的本地 Agent 工作台

DeepSeek Harness 全面解读：功能、架构与上手指南

2026 年 8 月 16 日

2026 年 8 月 13 日晚 20:30，DeepSeek 正式开源 Harness（简称 dsh） 开发者预览版，并同步上线 DeepSeek V4-Pro 正式版。一夜之间，GitHub Star 数迅速突破 5 万，被开发者社区称为 “Agent 界的 Android”。如果说 V4-Pro 是这个 Agent 的 “灵魂”，那 Harness 就是它的 “脚手架”：工作区、工具、权限、会话记忆、驱动任务继续执行的循环——全都在本地。

本文是一篇 功能 + 架构 + 上手 完整解读。你会看到：

阅读收获

•Harness 到底是什么？跟 Claude Code、Codex 有什么本质区别？

•“一切皆插件” 的设计哲学到底意味着什么？

•四条命令跑起来：从 npx 到完整配置模型与工作区

•四种运行模式与 “轨迹” 可观测性的实战价值

•开发者预览版的真实边界：能不能用于生产？

一、它到底是什么？

DeepSeek Harness（命令行名 dsh）是一个开源 Agent 运行时。它不是模型，也不是聊天界面，而是把 “模型 + 工具 + 工作区 + 权限 + 会话记忆 + 任务循环” 串起来的中间层。官方给的定义很直白：「Model + Harness = Agent」。

这意味着你既可以在本地把 Harness 当作 Claude Code 或 Codex 的替代品，也可以换掉模型、换掉工具、换掉整个 Agent Loop，把它当作 Agent 平台的基础设施来用。项目以 MIT 协议开源，源代码与 npm 包同时在 GitHub 发布（github.com/deepseek-ai/deepseek-harness，包名 @deepseek-ai/dsh）。

版本与定位

二、“一切皆插件” 意味着什么？

这是官方在 README 和 architecture.md 里反复强调的设计理念。一句话概括：没有需要打补丁的特权内核，模型适配器、工具注册表、会话日志、Agent 循环本身，全是插件，都可以替换。

实现这一点的，是它底层的 Cordis 框架——一个 “时空调度可组合” 的内核。每启动一次 dsh，它都会按顺序叠加出一棵插件树：官方组合包（Bundle）打底、profile 的 patch 层覆盖、机器级 patch、命令行 –patch 覆盖。越往后叠加的层优先级越高。换句话说：你想要的行为，几乎都能通过配置文件覆盖，而不用 fork 整个项目。

“我们把模型、工具、技能、会话、沙箱、文件系统、循环、调度、UI，都做成了插件。任何一项都可以被替换、被组合、被扩展。——DeepSeek Harness 官方公告（2026.08.13）”

可观测性：会话日志 + 轨迹视图

Agent 一旦开始读写文件、执行命令，“它为什么做出这个决定” 就成了最值得回答的问题。Harness 给出的答案是 “会话日志 + 轨迹”：

可观测性设计

•追加只写的会话日志：系统提示、思维链、工具调用、执行结果、子 Agent 调度、上下文注入全部记录

•Trajectory 视图：按时间线查看 System Prompt、用户输入、模型请求、工具执行

•可恢复（Resume）/可分叉（Fork）/可回放（Replay）/可审查（Audit）

•硬性约束：「模型可见 = 已记录」，任何进入模型请求的内容都必须能从日志重建

▲ 轨迹视图：左侧按时间线展示 System / User / Assistant / Tool / Context，右侧可展开查看 Payload / Result / Schema / Timing（来源：DeepSeek Harness Web UI 实测）

三、四种运行模式

官方在第一个版本里就内置了四种工作模式，每种模式对应一棵不同的插件树，可用的工具与权限随之切换：

值得一提的是 PTC 模式：原本可能需要 5 轮工具调用才能完成的操作，模型写一段程序，一次执行即可，中间数据留在执行环境里不进入上下文。对长流程任务来说，省 Token 的效果非常明显。

四、一条命令跑起来

上手成本低到令人发指——只要本机装了 Node.js，复制一行命令到终端即可：

Terminal — Mac / Linux                  

# 推荐：先用 npx 试一下，无需安装                  

npx @deepseek-ai/dsh web                  

# 或者：全局安装                  

npm install -g @deepseek-ai/dsh                  

dsh web

终端会输出访问地址：

Terminal                  

dsh web: http://127.0.0.1:3080

在浏览器打开后，你会看到一个极简的登录态界面——是的，第一步就是要先 填一个 API Key。首次运行会在 ~/.dsh 下自动初始化配置，profile、凭证、设置都在这里。

三条注意事项

•CLI 故意拒绝 –host 0.0.0.0：官方明确表示它只服务本机，不是 bug，是安全设计

•端口被占用时用 dsh web –port 8090 换端口

•工作目录就是 Agent 的默认工作区根目录——务必在有意选择的目录里启动

•Node 23 这种奇数版本不在支持范围，会启动失败，建议安装 Node 24 LTS

五、配置 API Key 与模型

Harness 默认以 DeepSeek 为第一优先，但你不必受限于 DeepSeek。打开 Settings → Models，在 DeepSeek 卡片里填入 API Key 保存即可生效，Key 是只写的：保存后页面只能看到脱敏描述符，真实密钥存在 ~/.dsh/.credentials.yaml。

默认可选模型包括 deepseek-v4-pro（旗舰，面向 Agent 任务优化）与 deepseek-v4-flash （更快、更省）。两者都默认按 100 万上下文、单次输出上限 256k、推理档位 high 配置。

模型无关性：随时切换

Add provider 里内置了 Anthropic、OpenAI、Bedrock、Azure、Vertex 等目录；Add a custom provider 可以接自己的网关或自建服务，填写 Provider ID、Base URL、协议、Key 和至少一个模型即可，也可以用 Fetch available models 自动拉取模型列表。也就是说：Harness 卖的不是 “DeepSeek 版 Claude Code”，而是一套可以持续生长的 Agent 基础设施。

▲ 用户自定义主题后的 Web UI：左侧工作区列表，右侧对话面板，左下角的 “Cordis Plugin” 是插件入口（来源：新京报 AI 研究院）

六、选工作区，跑第一个任务

点 Choose workspace，把启动 dsh 的项目目录加进来并选中——未选择工作区时输入框不可用。然后开一个会话，试一句：

Prompt                  

总结一下这个仓库，指出它的主要模块。

它可以读写文件、执行命令、派发子 Agent、维护计划清单。按当前权限策略需要审批的操作，界面会先弹窗确认。整个过程你会在轨迹视图里看到全部细节。

▲ Token 消耗信息：上下文占用、当前轮次耗时、首 Token 延迟、吞吐、缓存命中率、累计输入 Token 一目了然 ▲ Token 消耗信息：上下文占用、当前轮次耗时、首 Token 延迟、吞吐、缓存命中率、累计输入 Token 一目了然

▲ 轨迹面板：每一步的工具调用、命令行、模型思考链都可以逐条回溯（来源：新京报 AI 研究院实测） ▲ 轨迹面板：每一步的工具调用、命令行、模型思考链都可以逐条回溯（来源：新京报 AI 研究院实测）

七、Headless 模式与 SDK

不需要界面？一条命令跑完即退出：

Terminal                  

npx @deepseek-ai/dsh –profile headless “把失败的测试修好”

它会在一个全新且持久化的会话里执行任务，打印最终答案后自动退出，非常适合脚本化批量任务、CI 流水线接入、服务器上无人值守运行。

另外还提供 Python SDK（pip install deepseek-harness-sdk，自带 Node 运行时，目标机器不用装 Node）、JSON-RPC SDK 和 ACP 服务端，便于嵌入自己的程序。

八、实战展示：Agent 自己写游戏

媒体实测中，有记者让 Harness 制作一个 “肉鸽元素贪吃蛇游戏”。在 10 分钟左右的运行后，除了普通贪吃蛇机制外，Harness 还增加了随机地图、随机道具、可选择的祝福等肉鸽元素设计理念，出色地完成了任务。整个过程的轨迹在执行过程中可以随时回溯。

▲ 新京报 AI 研究院使用 DeepSeek Harness 制作的 “肉鸽元素贪吃蛇游戏”：随机地图、随机道具、肉鸽祝福系统俱全 ▲ 新京报 AI 研究院使用 DeepSeek Harness 制作的 “肉鸽元素贪吃蛇游戏”：随机地图、随机道具、肉鸽祝福系统俱全

九、常见问题与真实边界

FAQ

•端口被占用：dsh web –port 8090 换端口

•网页连不上模型：99% 是 API Key 没配好，去 Models 页或环境变量里确认

•想让局域网同事访问：不能，CLI 会拒绝 –host 0.0.0.0 并报错——设计如此

•输入框灰色无法输入：还没选工作区，点 Choose workspace 添加并选中目录

•报 MISSING_CREDENTIAL / UNKNOWN_MODEL：前者是 Key 没存，后者是选了没配置的模型

•会话存在哪里：~/.dsh/profiles/ 是 profile 目录，.credentials.yaml 存密钥，settings.yaml 存设置

•Windows 能用吗：Web UI 可以跑，但持久终端依赖 POSIX，官方只发 Linux/macOS 包

能不能用于生产？

官方在 README 里写得很直白：「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」。当前是 Developer Preview，会话格式不提供兼容承诺，升级后旧的会话记录可能无法读取。适合评估和内部试验，不适合作为唯一的生产工具。

另外一个值得开发者注意的细节：主仓库暂时不接收外部 PR，官方建议在 GitHub Discussions 反馈，或者自己写插件，并给仓库打上 dsh-plugin 标签便于被检索。官方明确：「主仓库里的包并不比社区的包更重要」——这是一个真把 “插件生态” 当成基础设施在做的项目。

十、参考资料

本文功能介绍与上手指南部分综合参考：新京报《实测 DeepSeek Harness》、InfoQ、极客公园、腾讯云开发者社区《玩转 DeepSeek Harness》、pandaily 评测、sakutto.ai、cnblogs 与 ai-indeed.com 等多篇公开实测；架构与设计细节以官方 GitHub 仓库与官方文档站为准。

— 本文完 —

海量资讯、精准解读，尽在新浪财经APP