DeepSeek Harness 快速上手指南之安装、多模型接入与「自带黑匣子」的会话日志

处理DeepSeek Harness 快速上手指南之安装、多模型接入与「自带黑匣子」的会话日志这类问题时，先确认目标场景，再按步骤核对配置或玩法细节。

DeepSeek Harness 快速上手指南：安装、多模型接入与「自带黑匣子」的会话日志

一、环境准备

DeepSeek Harness（dsh）目前是开发者预览版，基于 Node.js 生态，你需要先准备好：

1. Node.js（官方通过 npm 分发 CLI）；
2. 至少一个模型的 API Key（比如 DeepSeek、Anthropic、OpenAI 等）；
3. 官方明确提示：预览版会频繁迭代，未来有破坏性变更，暂时也不接受外部 PR。

二、安装：一条命令启动

最简单的方式是用 npx 直接拉起 Web UI：

npx @deepseek-ai/dsh web

命令执行后会启动 Web UI，默认地址是：

http://127.0.0.1:3080

浏览器打开这个地址，按照页面引导填入你的 API Key 即可开始对话。

如果你想要「从源码运行」以获得更完整的控制（比如自定义插件、参与调试）：

git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harnesspnpm installpnpm run buildpnpm dsh web

注意：源码安装依赖 pnpm，请先 npm install -g pnpm。

三、接入多个大模型

DSH 的核心卖点之一是不锁定模型。它把「模型适配器」也做成了插件，所以切换模型提供商不需要改核心代码，只需要在配置层完成注册。

官方支持近 40 种提供商，包括：

1. DeepSeek（自家模型）
2. Anthropic（Claude 系列）
3. OpenAI
4. AWS Bedrock / Azure
5. Google Gemini
6. Ollama（本地模型）

在 Web UI 的配置界面里，你只需要选择提供商、填入对应的 API Key 即可。多个模型可以并存，同一会话里也可以按需切换。

此外，DSH 还内置了把 Claude Code 和 Codex 作为子 Agent 调用的 Provider——这意味着你可以把 DSH 当作上层编排器，把已经熟悉的编码工具挂到它下面当「员工」。

四、理解 profile：你的 Agent 是什么，由「叠放」决定

运行中的 dsh 本质上是一棵插件树，由启动时按顺序叠放的多层组合而成。官方文档里有两个关键概念：

1. profile：存放在 Harness home 中的具名组装，列出自己叠放的组合包（bundle），保存你自己安装的树外插件和 cordis.patch.yml 补丁。web 和 headless 是随发行版交付的两个模板 profile。
2. 组合包（bundle）：Cordis 配置项及其挂载代码的分发格式，它插入的内容始终可以被其上层 patch。

想看看你机器上实际启动的配置树，可以：

dsh --profile web --dump-config

它打印出来的每一个条目，都可以被你自己的 patch 替换——这就是「一切皆插件」在工程上的具体落地。

五、可追溯性：自带「黑匣子」的会话日志

DSH 有一个非常实用的能力：所有模型可见的内容、推理过程、工具调用，都会被记录在只增不改的会话日志中。

官方文档用一句话概括了这一设计原则：

模型可见即已记录。

也就是说，凡是送到模型请求里的内容，都必须能够从日志中重建（由一项运行时不变式来保证）。基于这条事件流，DSH 提供了几个关键能力：

1. 恢复（resume）：中断后从日志继续；
2. 分叉（fork）：从一个会话点分出多个分支做对照实验；
3. 回放（replay）：精确重现某一次执行；
4. 遥测（telemetry）：基于事件流做分析和统计。

对需要调试 Agent、复现 bug、或者做评测的研究者来说，这个「黑匣子」的价值很高——出了问题，你不是靠猜，而是能「回放现场」。

六、沙箱安全机制

Agent 要执行 Shell 命令、操作文件系统，安全就是绕不开的问题。DSH 的沙箱机制封装了子进程的执行环境，针对不同平台使用系统原生的隔离能力：

1. Linux：Landlock
2. macOS：Seatbelt
3. Windows：ACL（访问控制列表）

这意味着「限制 Agent 能启动哪些进程、能碰哪些文件」这类策略，是在系统层面强制执行的，而不是靠应用层的字符串过滤。

七、一个最小上手流程

总结一下，最快把 DSH 跑起来的步骤：

1. 安装 Node.js 和 pnpm；
2. 执行 npx @deepseek-ai/dsh web；
3. 打开 http://127.0.0.1:3080；
4. 填入一个模型的 API Key；
5. 开始让它帮你读文件、跑命令、写代码；
6. 出问题时，回到会话日志里「回放现场」定位。

到这里，你已经能跑起来一个可用的 Agent 了。但如果想理解它为什么「看起来能装能拆、很灵活」，就需要深入它的架构——这正好是下一篇的内容。

参考：deepseek-ai/deepseek-harness 官方 README 与架构文档。