DeepSeek Harness
DeepSeek Harness（dsh）官方 Agent 安装与使用指南
DeepSeek 官方开源的 agent harness，一条命令在本机跑起图形界面。模型可换，能力全部由插件组成，MIT 许可。
本站其他指南讲的是把第三方 Agent 接到 DeepSeek。DeepSeek Harness 属于另一类：它是 DeepSeek 自己的 Agent 运行时，2026 年 8 月 13 日随 V4-Pro 一同开源，两天内 GitHub star 超过 10 万。
本指南由 deepseekagent.io 维护，内容基于 0.1.0-rc.6 实测，数据统计到 2026 年 8 月 15 日。
Agent = Model + Harness
官方对 harness 的定位：
模型是 Agent 的灵魂；harness 让它读懂环境、使用工具、把任务真正跑完。
模型只输出文字，它自己打不开文件、跑不了命令，也记不住上一轮对话。harness 是模型外面那一层：工作区、工具、权限、会话记忆，以及驱动任务继续执行的循环。
Claude Code、Codex 也是 harness，但它们是成品。dsh 的区别在于模型适配、工具注册表、会话日志乃至 agent 循环本身都是可替换的插件，文档称之为「没有需要打补丁的特权内核」。
适用场景
| 你的情况 | 建议 |
|---|---|
| 想用 DeepSeek 官方出品的编程 Agent | 直接用 dsh，它默认以 DeepSeek 为第一优先 |
| 想自己掌控 Agent 运行时，而不是用封闭产品 | 首选 dsh，这是它的核心设计目标 |
| 需要干净稳定的工具面做模型评测 | 用 Minimal 模式，只暴露两个工具 |
| 想给团队搭内部 Agent 平台 | 可行，用插件和 profile 组合出需要的形态 |
| 只想让 Claude Code 用上更便宜的模型 | 不必用 dsh，参考 CC Switch 或 Claude Code 教程 |
| 需要立即上生产、要求 API 稳定 | 暂缓，当前是开发者预览，官方声明会有破坏兼容的变更 |
准备工作
1. Node.js 版本要对
dsh 要求 ^22.19 || >=24，奇数版本不在支持范围内，Node 23 会直接启动失败。先确认当前版本：
node -v
版本不符时安装 Node 24（macOS Homebrew）：
brew install node@24
brew link --overwrite --force node@24
2. 准备 DeepSeek API Key
- 打开 DeepSeek 开放平台
- 登录后创建 API Key，复制保存（只显示一次）
- 确保账户有余额或可用额度
第一步：一条命令启动
在你想让 Agent 工作的项目目录里执行：
cd 你的项目目录
npx @deepseek-ai/dsh web
终端会打印访问地址，在浏览器打开：
dsh web: http://127.0.0.1:3080
首次运行会在 ~/.dsh 下自动初始化配置（profile、凭证、设置都在这里）。
它只服务本机。传 --host 0.0.0.0 会被 CLI 拒绝并退出，官方没有把它设计成对外托管的服务，无法用这种方式共享给同事。
第二步：配置模型
打开 Settings → Models，在 DeepSeek 卡片里填入 API Key 并保存，改完立即生效，无需重启服务。
Key 是只写的：保存后页面只能拿到一个脱敏描述符，真实密钥存放在 ~/.dsh/.credentials.yaml，设置文件里只保留一个引用。
默认可选的模型：
| 模型 | 说明 |
|---|---|
deepseek-v4-pro | 旗舰，面向 Agent 任务优化 |
deepseek-v4-flash | 更快、更省，适合日常任务 |
两者默认都按 100 万上下文、单次输出上限 256k、推理档位 high 配置。
dsh 不绑定 DeepSeek。Add provider 里内置了 Anthropic、OpenAI、Bedrock、Azure、Vertex 等目录；Add a custom provider 可以接自己的网关或自建服务，填写小写 Provider ID、Base URL、协议、Key 和至少一个模型即可，也可以用 Fetch available models 自动拉取模型列表。
手填的模型默认按纯文本处理，发送图片会在请求前被拒绝。视觉模型需要在
~/.dsh/settings.yaml里补一行input: [text, image]。
第三步：选工作区，跑第一个任务
点 Choose workspace，把启动 dsh 的项目目录加进来并选中。未选择工作区时输入框不可用。
然后开一个会话，试一句：
总结一下这个仓库，指出它的主要模块。
它可以读写文件、执行命令、派发子 Agent、维护计划清单。按当前权限策略需要审批的操作，界面会先弹窗确认。
四种运行模式
每种模式对应一棵不同的插件树，可用工具随之变化：
| 模式 | 能力 | 什么时候用 |
|---|---|---|
| Standard | 完整编程 Agent：文件编辑、shell、文件与网页搜索、skills、计划、目标、子 Agent、工作流 | 日常写代码，默认模式 |
| Code mode | Standard 全部能力，但工具通过 Code Mode SDK 暴露，模型写一段 TypeScript 把多步操作编排进一次调用 | 多步操作密集，希望减少往返轮次 |
| Minimal | 只有两个工具：持久 bash 和 str_replace_editor | 模型评测，需要极简可控的环境 |
| Creator | Standard 全部能力 + 运行时自省、内存里试插件、preset 编写指导 | 自己定制 Agent 形态 |
举例说明 Code mode 的作用：原本需要五轮工具调用的序列，模型写成一段程序，一次执行完成。
与 Claude Code / Codex 的差异
| Claude Code / Codex | DeepSeek Harness | |
|---|---|---|
| 形态 | 成品 Agent | 造 Agent 的框架，附带可用界面 |
| 界面 | 终端为主 | 本地 Web UI 为主，也有无界面模式 |
| 扩展 | hooks / MCP | Cordis 插件，连 agent 循环都能换 |
| 模型 | 自家为主 | 多厂商，DeepSeek 优先 |
| 源码 | 闭源或半开 | MIT 全开 |
| 成熟度 | 生产可用 | 开发者预览，会有破坏兼容的变更 |
它对同类工具的兼容做得比较彻底：内置 Claude Code 和 Codex 的 hooks 桥，可以直接复用现成的 hooks.json；也能把任务委托给本机已安装的 Claude Code / Codex（默认关闭）。此外它会读取 AGENTS.md 和 CLAUDE.md，并作为客户端支持 MCP。
「一切皆插件」的两层含义
两个设计决定了它的扩展空间。
1. 每个能力都可以在配置里替换
运行中的 dsh 是启动时按顺序叠加出来的插件树：bundle 补丁、profile 补丁、机器级补丁、命令行覆盖。查看本机实际启动的配置：
npx @deepseek-ai/dsh web --dump-config
打印出来的任何一项都可以用自己的补丁覆盖。
2. 每次运行都可追溯
模型看见的一切都写进只增不改的会话日志：系统提示、推理过程、工具调用与结果、子 Agent 调度、每一次上下文注入。界面里的 Trajectory（轨迹） 视图可以按来源逐条查看。续跑、分叉、搜索、回放都基于同一条事件流。
官方把这条写成硬性约束：模型可见等于已记录，任何进入模型请求的内容都必须能从日志重建。
无头模式与 SDK
不需要界面时，可以一次性执行任务、打印结果并退出：
npx @deepseek-ai/dsh --profile headless "把失败的测试修好"
另外还提供 Python SDK（pip install deepseek-harness-sdk，自带 Node 运行时，目标机器不用装 Node）、JSON-RPC SDK 和 ACP 服务端，便于嵌入自己的程序。
常见问题
启动报错提示 Node 版本不对？
dsh 要求 ^22.19 || >=24。Node 23 这类奇数版本不在支持范围内，且已停止维护，安装 Node 24 即可。
3080 端口被占用怎么办？
web 后面的参数会交给 Web 应用，用 npx @deepseek-ai/dsh web --port 8080 换端口。
能让局域网里的同事访问吗？
不能。CLI 会拒绝 --host 0.0.0.0 并报用法错误，它被设计成只服务本机。
输入框是灰色的，无法输入？
还没选工作区，点 Choose workspace 添加并选中目录。如果模型下拉显示 Select model，说明默认模型指向了已删除的供应商，重新选一个即可。
报 MISSING_CREDENTIAL 或 UNKNOWN_MODEL？
前者是没存 Key（去 Models 页面填，或设置好被引用的环境变量）；后者是选了没配置的模型，去自定义供应商里把模型 ID 补上。
配置和会话存在哪？
都在 ~/.dsh：profiles/ 是 profile 目录，.credentials.yaml 存密钥，settings.yaml 存设置，cordis.patch.yml 是你自己的补丁层。
Windows 能用吗？
Web UI 可以跑，但持久终端（PTY）依赖 POSIX 环境，官方打包的自带运行时也只发 Linux 和 macOS。Windows 上部分能力受限。
现在能用在正式项目上吗？
建议谨慎。它是开发者预览，README 明确警告会有破坏兼容的变更；会话格式不提供兼容承诺，升级后旧的会话记录可能无法读取。适合评估和内部试验，不适合作为唯一的生产工具。
我能给它提 PR 吗？
暂时不接收外部 PR。官方建议在 GitHub Discussions 反馈，或者自己写插件，并给仓库打上 dsh-plugin 标签便于被检索。官方也说明：主仓库里的包并不比社区的包更重要。
相关链接
- 源码：github.com/deepseek-ai/deepseek-harness
- 官方介绍页：deepseek.com/harness
- 插件框架 Cordis：github.com/cordiverse/cordis
- DeepSeek API 文档：platform.deepseek.com/api-docs
- 本站全部指南：首页工具列表