【DeepSeek Harness】从安装到使用完整指南-三亩地-编程学习日记

本文基于 deepseek-harness 官方仓库及其相关文档整理，涵盖安装、模型配置、Web UI 使用与常见问题排查，适合第一次接触该项目的开发者。

一、什么是 DeepSeek Harness

DeepSeek Harness（命令行简称dsh）是 DeepSeek AI 开源的一个 Agent Harness（智能体运行框架）。它采用"一切皆插件"（Everything is a Plugin）的架构理念，底层由 Cordis 驱动，相关设计思想可参考论文《A Programming Paradigm for Spatiotemporal Composability》。

需要注意的是，该项目目前处于开发者预览（Developer Preview）阶段，仍在快速迭代中，官方明确提示后续版本可能出现不兼容改动，生产环境使用需谨慎。

二、安装方式

官方 README 提供了两种运行方式：通过 npm 直接运行，或者从源码克隆构建。

方式一：通过 npm 运行（推荐新手）

只需要先安装好Node.js，然后执行一条命令即可：

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认监听地址为：

http://127.0.0.1:3080

启动后浏览器打开这个地址，就能看到管理界面了。这是最简单的体验方式，不需要克隆仓库、不需要本地构建。

方式二：从源码运行

如果你想参与开发、调试插件，或者需要使用最新的 master 分支代码，可以从源码运行：

git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web

这里需要注意，项目使用pnpm作为包管理器，如果本地没有安装，需要先执行npm install -g pnpm进行全局安装。构建（pnpm run build）这一步不能省略，否则pnpm dsh web可能无法正常启动。

两种方式最终效果一致：都会启动本地 Web UI 服务。

三、配置模型

Web UI 启动之后，一个"全新"的实例其实还不能直接使用——因为它既没有配置任何模型，也没有选定工作区。这一步是很多新手容易卡住的地方，下面分别说明。

3.1 配置 DeepSeek 官方模型

打开Settings → Models（设置 → 模型），你会看到一个 DeepSeek 卡片，里面只有一个 API Key 输入框。填入你的 DeepSeek API Key 并保存即可，保存后立即生效，无需重启服务。

需要特别说明的是安全机制：Key 是只写的，页面保存后只会返回一个脱敏后的描述符，永远不会把明文密钥再显示出来。密钥实际存储在$DSH_HOME/.credentials.yaml文件中，而settings.yaml里只保留对这个凭证的引用，不会明文落盘在配置文件里。

3.2 添加目录内其他厂商模型（如 Anthropic、OpenAI）

点击Add provider（添加提供商），选择目录中已内置的厂商（比如 Anthropic、OpenAI），填入对应 API Key 并保存。这类"目录内"厂商会自动带出预置的接口地址、协议和模型列表，不需要手动填写。

但要注意，像 Bedrock、Vertex、Azure、Codex 这几类提供商用的是"原生认证"方式（分别对应 AWS 凭证 + region、ADC 项目、api-version、OAuth），只填 API Key 字段是配置不好的，需要按各自的原生凭证要求填写。

3.3 添加自定义提供商（企业网关 / 自建服务）

如果你用的是公司内部网关、自建的模型服务，或者是目录里没有收录的提供商，选择Add a custom provider（添加自定义提供商），需要填写：

小写的 Provider ID（永久不可更改，因为请求记录、已保存会话、模型默认值、凭证引用都会用到它；如果要改名，只能新建一个再删除旧的）
Base URL
API 协议
凭证
至少一个模型

也可以点击Fetch available models（获取可用模型），系统会用当前表单里的 Base URL 和凭证去请求该服务的模型列表；注意，选中的候选模型只是更新了草稿，必须点击保存才会真正生效。

3.4 关于图片输入（视觉模型）配置

这是一个容易踩坑的细节：手动录入的模型默认会被当作"纯文本"模型，因为系统本身无法探测某个接口到底支持哪些模态。如果你给这种模型发送图片，请求会在发出前就被拒绝，并明确提示是哪个模型不支持。

如果你的自定义提供商里有支持视觉的模型，需要手动在$DSH_HOME/settings.yaml里给该模型加一行input配置：

llm-pi-ai: providers: my-gateway: apiKeyEnv: GATEWAY_API_KEY api: openai-completions baseURL: https://gateway.example/v1 models: - id: legacy-chat - id: vision-preview input: [text, image]

input只能填text和image，且只对当前这一个模型生效，方便同一个 provider 下不同模型区别对待。[这部分还没测，后续更新]如果不写（或写成空列表），则会沿用目录内该模型的默认记录，若目录里也没有描述,再退回使用 provider 级别的defaultInput。

如果某个网关下所有手动录入的模型都支持图片，可以直接在 provider 级别统一设置defaultInput，就不用逐个模型加：

llm-pi-ai: providers: vision-gateway: apiKeyEnv: GATEWAY_API_KEY api: openai-completions baseURL: https://vision.example/v1 defaultInput: [text, image] models: - id: first-model - id: second-model

要注意defaultInput只是"兜底值"，不是"强制覆盖"，默认值本身是[text]。对于目录厂商（如 Anthropic），它只对目录没有描述的模型生效，不会把目录里本来支持图片的模型改成不支持。如果确实要收窄某个目录模型的模态，需要写在modelOverrides里：

llm-pi-ai: providers: anthropic: modelOverrides: claude-sonnet-4-5: input: [text]

另外这两个字段（input/defaultInput）只是"声明"，系统并不会替你去验证接口真实能力——如果你声明了图片支持,但接口其实不支持,请求依然会被下游服务拒绝，而不是在本地拦截。

3.5 选择模型

配置好的提供商会出现在模型选择器里。选中某个模型后，它会成为新会话的默认模型；已经发过请求的旧会话则会继续沿用当时记录在日志里的模型，不会被新的默认值影响。

如果之前设置的默认模型所属的提供商被删除了，会话输入框会显示"Select model"（请选择模型）并锁定输入，直到你重新选一个可用模型。

四、开始使用 Web UI

模型配置完成后，就可以正式进入使用流程了。

4.1 选择工作区

点击Choose workspace（选择工作区），添加你启动dsh时所在的项目目录并选中它。这一步不能跳过——没有选定工作区之前，会话输入框是不可用的。

这里有个细节：dsh进程默认会以它被调用时所在的目录作为文件系统的默认位置，但即便如此，全新启动的 Web UI 仍然不会自动带出这个工作区，需要你手动添加、选中。

4.2 发起一个任务

工作区选好之后，就可以开启一个会话，直接对话即可，比如输入：

Summarize this repository and identify its main packages. （总结一下这个仓库，并指出它的主要模块。）

Agent 具备的能力包括：读写工作区文件、执行命令、任务委派、维护执行计划。在当前权限策略下，如果某个操作需要审批，Web UI 会先弹出确认再执行，避免"未经允许"的高风险操作。

五、常见问题排查

官方文档给出的几个高频报错和解决办法：

报错/现象	原因与解决办法
`MISSING_CREDENTIAL`	缺少凭证。到 Models 页面配置对应厂商的 Key，或提供文档中引用的环境变量。
`UNKNOWN_MODEL`	选择了未配置的模型。请在模型选择器中选一个已配置的模型，或在自定义提供商里补上这个模型。
Fetch available models 返回 401	Key 不对。另外注意：模型发现功能调用的是 OpenAI 兼容的`GET /models`接口，如果对方接口没有这个端点，只能手动填写模型列表。
图片在发送前就被拒绝	该模型没有声明图片模态。给自定义提供商的模型加上`input: [text, image]`；注意 DeepSeek 官方 chat-completions 接口本身是纯文本的，无法通过配置开启图片支持。
服务端拒绝携带图片的请求	说明模型声明了图片能力，但实际接口不支持。需要去掉相应`input`或`defaultInput`里的`image`，并开一个新会话——因为已经发出的图片会留在会话日志里，同一会话继续沿用旧配置会反复报错。

六、进阶与延伸阅读

如果基础使用已经跑通，想进一步深入，可以参考以下几个方向：

多提供商 / 高级配置：完整字段和默认值可查阅插件配置目录文档，以及dsh-llm-pi-ai、dsh-llm-deepseek两个包各自的 README，里面有更细的凭证、推理控制、适配器报错说明。
Python SDK：如果想用代码而非 Web UI 驱动 Agent，可参考官方的 Python SDK 使用文档。
其他 CLI 模式：除了dsh web启动网页端，CLI 还有别的运行模式，可参考apps/cli下的 README。
插件开发：项目的核心卖点就是"一切皆插件"，如果想自己写插件扩展能力，可以从开发指南入手。
参与社区：可以通过 GitHub Discussions 提反馈或报 Bug；如果自己写了插件，给仓库打上dsh-plugin这个 topic 标签方便别人发现；官方也有 Discord 社区可以加入交流。

七、小结

总体来看，DeepSeek Harness 的上手路径是这样一条主线：

装环境：npx @deepseek-ai/dsh web（或源码构建）启动 Web UI；
配模型：在 Settings → Models 里填 DeepSeek Key，或接入其他厂商/自定义网关；
选工作区：把项目目录添加为工作区；
发消息：像聊天一样直接把任务交给 Agent。

由于项目仍处于开发者预览阶段，建议关注官方仓库的更新动态，遇到接口或配置字段变化属于正常现象，以官方 README 为准即可。

参考链接：

项目主页：https://github.com/deepseek-ai/deepseek-harness
Web UI 使用指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md
模型配置指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md

日记详情

【DeepSeek Harness】从安装到使用完整指南