DeepSeek Harness（DSH）使用指南：功能、自定义模型与插件

一、DSH 是什么

DeepSeek Harness（简称 DSH）是一个运行在本地的 Agent Harness。它不直接训练模型，也不把工作流锁死在某个云端产品里，而是把下面几件事组合成一个可扩展的工作台：

DSH = 模型路由 + 工具运行时 + 持久会话 + 权限与沙箱 + 插件系统

和普通聊天客户端相比，DSH 的关键差别是「能动手」：

• 它可以读取和修改工作区文件，执行 PowerShell / Bash 命令。
• 它可以调用网页搜索、网页抓取、后台任务、子 Agent、工作流、定时任务等工具。
• 它会持久化会话，支持恢复、压缩、标题和会话列表。
• 它把不同模型统一成「提供方 + 模型」的路由，可以在设置里接入官方 API、兼容网关或本地模型。
• 它的一切能力几乎都由插件组合而成，插件可以增加工具、命令、页面、设置卡片，甚至新的模型提供方。

DSH 目前主要有三种使用形态：

官方入口：https://www.deepseek.com/harness/

二、安装与第一次启动

2.1 桌面端

从官方入口下载并安装 DeepSeek Harness。首次打开时选择一个项目目录作为工作区，然后就可以在对话框里描述任务。

桌面端适合大多数日常使用：左侧边栏管理会话、工作区和插件，右侧可以打开文件与预览面板；安装上下文类插件后，右侧还会出现上下文面板。插件有独立的安装入口。

2.2 命令行与 Web GUI

命令行方式需要 Node.js 和 pnpm。当前 DSH 要求 Node.js ​^22.19.0​ 或 ​>=24.0.0​。

npm install -g @deepseek-ai/dsh pnpm
dsh --version

如果不想全局安装，也可以直接通过 ​npx​ 启动：

npx -y @deepseek-ai/dsh web

启动 Web GUI：

dsh web

​dsh web​ 等价于 ​dsh --profile web​。启动后终端会打印一个带进程 token 的 URL，通常会自动打开浏览器。常用参数：

dsh --profile web --no-open --port 8080
dsh --profile web --host 0.0.0.0 --trusted-host 192.168.1.10

​--no-open​ 只关闭本次的浏览器自动打开；​--host​ 和 ​--trusted-host​ 用于局域网访问，使用前请确认网络环境可信。

一次性的无头任务：

dsh --profile headless "阅读当前目录的 README，总结项目结构并给出三条改进建议"

程序化集成可以使用 SDK 或 ACP profile：

dsh --profile sdk
dsh --profile acp

这两个入口主要面向客户端和自动化程序，普通用户不必从它们开始。

2.3 目录与 profile

DSH 的用户目录默认是 ​~/.dsh​，Windows 下通常是 ​C:\Users\<用户名>\.dsh​。可以通过 ​DSH_HOME​ 改到其他位置。

~/.dsh/
├─ profiles/          # 每个 profile 一套插件组合
├─ sessions/          # 持久化会话
├─ skills/            # 技能
├─ settings.yaml      # 用户设置
├─ .credentials.yaml  # 受管凭据（只写）
└─ logs/              # 日志

profile 是 DSH 组合能力的单位。可以把它理解成「一套插件清单 + 一层配置覆盖」：​web​、​headless​、​sdk​、​acp​ 是随发行版提供的 profile，​desktop​ 由 Electron 桌面端持有。不同 profile 可以有不同插件、默认模型和权限策略，互不影响。

2.4 第一次对话建议

第一次进入一个项目时，先让 DSH 只读检查，不要直接修改：

请先阅读当前目录的 AGENTS.md 和 README，概括项目结构、主要入口、可用命令和风险点。
这一轮只做检查，不要修改任何文件。

确认它理解正确后，再给明确任务：

请修复登录接口的超时重试问题。先定位相关代码和测试，说明根因，再实施最小修改，最后运行针对性测试。

涉及删除、部署、数据库迁移、批量改写或推送远程时，要求它先给出计划并等待确认。DSH 默认的权限策略是「工作区可写、危险操作询问」，但不要把这句话当成绝对安全边界；真正的安全来自合适的沙箱、权限设置和人工复核。

三、DSH 的核心功能

3.1 文件与命令

DSH 内置了完整的文件工具链：

• ​read​、​glob​、​grep​：读取、按路径查找、按内容搜索。
• ​write​、​edit​：创建和局部修改文件。
• ​pwsh​ / ​bash​：执行命令；Windows 上默认是 PowerShell。
• 后台任务：长时间运行的命令可以放到后台，之后用任务工具查看输出或终止。

在对话里可以直接说「先看一下 ​src​ 下的入口文件」「运行测试」「把结果写到 ​reports/​」，不需要记工具名。

3.2 会话、上下文与压缩

DSH 的会话是持久化的，可以跨重启恢复。它支持：

• 会话列表、标题和按工作区分组。
• 上下文占用与 token 统计。
• 自动压缩和工具结果裁剪，避免长任务把上下文撑爆。
• 会话检查点和恢复。
• 会话全文搜索默认不开启，需要在 profile 配置中启用；日常的会话标题和工作区检索不受影响。

重要任务建议单独开一个会话，并在开始时写清楚目标和验收标准。会话越长，越要主动要求「先总结当前结论，再继续」。

3.3 常用工具一览

这些工具不需要用户手动调用，模型会根据任务选择。你要做的是把目标、约束和验收标准说清楚。

3.4 子 Agent、工作流、目标与定时

这四类能力经常被混在一起，其实分工不同：

• 子 Agent：把一个独立任务交给另一个上下文执行，适合并行调研、独立审查、拆分实现。​subagent_fork​ 会继承当前对话，适合「基于刚才的讨论继续做」。
• 工作流：用一段 JavaScript 编排大量子 Agent，适合批量审计、迁移、多角度研究。它适合「很多个独立小任务」而不是单线任务。
• 目标：为长周期任务建立持续目标，让 DSH 在多轮之间继续推进。适合「把这件事做完」而不是「回答一个问题」。
• 定时任务：在会话内设置一次性或周期性提醒，也可以从侧边栏的自动化任务页面管理。

3.5 技能（Skill）

技能是一份按需加载的流程说明，通常是一个包含 ​SKILL.md​ 的目录。它告诉模型「遇到什么任务、按什么步骤做、注意哪些约束」，而不是直接注册新工具。

本机的技能目录是 ​~/.dsh/skills​。插件也可以自带技能。技能的好处是节省上下文：只有匹配到任务时才加载，而不是把所有说明常驻在系统提示词里。

在对话中可以直接说「用 ​office​ 技能处理这个表格」，也可以使用 ​/skill​ 相关命令。

3.6 MCP 与外部集成

DSH 内置 MCP 客户端，可以把外部 MCP Server 的工具接入进来。接入后，工具会出现在模型的工具列表中，来源通常标记为 ​mcp:<server>​。

DSH 还提供与 Claude Code、Codex hooks 的兼容层，适合把已有的钩子工作流迁移过来。具体配置属于进阶内容，建议先确认版本和配置格式，再修改 profile。

3.7 权限与沙箱

DSH 的文件策略大致有三档：

Windows 上，沙箱通过受限令牌和 ACL 实现，不只是「口头约定」。即使模型想写工作区外的路径，也会被文件策略拦下。网页抓取提供方还会拒绝非公开地址，降低内网探测风险。

权限弹窗出现时，先看清楚「要做什么、影响哪些文件」，再决定是否批准。不要在不理解命令的情况下批量点允许。

3.8 图片、视频与生成式 UI

这些能力由插件提供，安装后才会出现：

• 图片生成与编辑：​dsh-image-gen​，支持多家图片提供方、图生图、连续编辑和本地工作区保存。
• 视频 / 短剧 / 漫剧管线：​dsh-video-generator​，从故事、剧本、分镜到竖屏成片，支持 9:16 输出和字幕。
• 生成式 UI：​dsh-genui​，把回复变成可点击的表单、计算器、图表等界面。

图片和视频插件通常会调用外部付费接口。使用前先看清楚计费方式和模型，避免在不知情的情况下产生费用。

3.9 典型用途

这些场景不需要一次记住所有工具。把目标、输入、输出格式和验收标准说清楚，DSH 会自己组合能力。

四、自定义模型

DSH 的模型配置可以拆成三个概念：

• 提供方（provider）：一条模型路由，例如 ​deepseek-official​ 或你自己命名的 ​my-gateway​。
• 模型（model）：提供方下的具体模型 id，例如某个网关的 ​my-model​ 或本地 Ollama 的 ​qwen3:8b​。
• 协议（api）：请求格式。常见的是 ​openai-completions​、​openai-responses​ 和 ​anthropic-messages​。

DSH 内置两类适配器：

• ​llm-deepseek​：注册 ​deepseek-official​ 路由，适合 DeepSeek 官方 API 或 OpenAI 兼容网关。
• ​llm-pi-ai​：多提供方适配器，支持内置 pi-ai 目录中的提供方，也支持手工声明的自定义路由。

4.1 在界面里添加模型

打开「设置 → 模型 / Models」，可以看到每个已配置提供方的一行。点击「添加提供方」，有两种路径：

1. 从已安装的提供方目录中选择一个（例如 OpenAI、Anthropic 等，具体以本机目录为准）。
2. 选择「添加自定义提供方」，手动填写端点、协议和模型。

自定义提供方至少需要：

填写后点击保存。模型配置会在下一次请求生效，通常不需要重启 DSH。

页面上的状态点值得注意：

• 绿色实心点：该提供方的凭据引用已配置。
• 红色实心点：声明了引用但凭据缺失。
• 保存冲突：另一个标签页或外部编辑修改了 ​settings.yaml​，需要重新加载后再改。

4.2 协议怎么选

协议选错时，最常见的表现是 404、400 或返回体解析失败。不要只看「端点能打开」就判断协议正确；要用一次真实的模型请求验证。

4.3 拉取模型与手动填写

对支持模型列表的端点，可以使用「获取可用模型」：

• ​openai-completions​ 和 ​openai-responses​ 通常请求 ​GET {baseURL}/models​，使用 Bearer 鉴权。
• ​anthropic-messages​ 使用 Anthropic 原生的 ​GET /v1/models​ 语义。
• 其他协议或不支持列表的端点，会提示无法查询，此时手动填写模型 id。

模型发现对 ​baseURL​ 是否带末尾 ​/v1​ 比较宽容，但真正的模型请求会按你填写的 ​baseURL​ 原样发送。因此仍要按提供方文档填写，例如有的网关要求 ​https://example.com/v1​，有的要求根地址。

每个模型还可以填写上下文窗口和最大输出 token。很多兼容网关不会返回这些信息，填错会导致长对话被过早截断，或者请求超过模型上限。以提供方文档为准。

4.4 三种常见场景

场景一：DeepSeek 官方 API 或兼容中转

使用内置的 DeepSeek 提供方，填入 API Key；如果使用中转，把 Base URL 改成中转地址。DeepSeek 适配器走 Chat Completions 语义，适合大多数 OpenAI 兼容中转。

场景二：OpenAI、Claude 或其他云模型

从提供方目录选择对应条目，或新建自定义提供方。按端点选择 ​openai-responses​、​openai-completions​ 或 ​anthropic-messages​，填入密钥和模型 id。

场景三：本地 Ollama / vLLM / LM Studio

新建自定义提供方：

Provider ID: local-ollama
显示名称: 本地 Ollama
Base URL: http://127.0.0.1:11434/v1
协议: openai-completions
模型: qwen3:8b（按你本地实际拉取的模型填写）
API 密钥: 本地服务通常不需要；如果端点要求鉴权再填

本地模型的上下文窗口和输出上限要手动确认。小模型在长上下文、工具调用和结构化输出上的表现通常不如云端大模型，建议先做小任务验证。

4.5 直接编辑 settings.yaml

界面适合日常配置；批量迁移或部署时，也可以直接编辑 ​~/.dsh/settings.yaml​。自定义 pi-ai 提供方的结构如下：

llm-pi-ai:
  providers:
    my-gateway:
      displayName: My Gateway
      apiKeyEnv: MY_GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example.com/v1
      models:
        - id: my-model
          name: My Model
          contextWindow: 131072
          maxTokens: 32768

DeepSeek 官方适配器的分节：

llm-deepseek:
  apiKeyEnv: DEEPSEEK_API_KEY
  baseURL: https://api.deepseek.com
  reasoningEffort: high

注意：​settings.yaml​ 里只放 ​apiKeyEnv​ 这样的引用，不放明文密钥。界面保存密钥时，会以只写方式写入受管凭据（默认是 ​~/.dsh/.credentials.yaml​），设置文件只保留引用。手动配置时，把真实密钥放到环境变量或受管凭据中。

密钥输入还有一些格式限制：首尾空白会被去掉，内容必须是可打印 ASCII；把 ​NAME=value​ 整行粘贴进去会因为格式不符被拒绝，只填值即可。

4.6 切换模型与默认模型

• 会话输入框旁的模型选择器可以切换当前会话使用的模型。
• 设置中的默认模型决定新会话/新 Agent 的起始模型。
• 支持推理等级的模型会提供 ​off​、​low​、​high​、​max​ 等选项；不是所有模型都支持，选错会在请求前报错。
• 多个提供方可以同时存在，路由名不能冲突。

4.7 常见问题

五、插件的安装与使用

5.1 插件是什么

DSH 插件是一个 npm 包，通常包含两部分：

• Host 半：运行在 Node 侧，可以注册工具、命令、服务、会话投影、模型提供方等。
• Client 半：运行在浏览器侧，可以注册页面、面板、设置卡片、聊天区域扩展等。

插件通过 ​dsh.bundle.patch​ 声明自己要插入的配置行，通过 ​dsh.client​ 声明客户端入口。安装插件本质上是把它加入某个 profile 的组合清单，而不是改 DSH 源码。

5.2 从界面安装

桌面端和 Web GUI 都可以从左侧边栏的「插件 / Plugins」进入：

1. 打开「插件」。
2. 在「已安装」里查看已有插件，或点击「添加插件 / Add plugin」。
3. 搜索插件名（npm 包名），点击安装。
4. 安装完成后按提示重启或刷新。

插件卡片通常会显示版本、作者、体积、是否已安装、是否有更新，以及兼容性提示。要求特定 DSH 版本或特定 profile 的插件，会在不满足条件时标记为不兼容。

5.3 从命令行安装

命令行安装需要 ​dsh​ 和 ​pnpm​ 在 PATH 中，并且必须指定 profile：

dsh plugin --profile web add dsh-context@latest
dsh plugin --profile web list --depth 0

安装后启动或重启：

dsh web

常用管理命令：

# 更新
dsh plugin --profile web update dsh-context@latest

# 卸载
dsh plugin --profile web remove dsh-context

# 从 GitHub 安装
dsh plugin --profile web add git+https://github.com/user/repo.git

# 从本地目录安装（开发调试）
dsh plugin --profile web add ./my-plugin

几个容易踩的坑：

• ​--profile​ 是必填的；不写会直接报 ​required option '--profile <name>' not specified​。
• ​dsh plugin​ 会把参数转发给 pnpm，所以本机必须装 pnpm。
• pnpm 11 可能对刚发布的版本有冷却期，装到的版本比 npm 上的 ​latest​ 旧时，改用精确版本号。
• ​desktop​ profile 由桌面端持有，CLI 会拒绝对它的启动、配置 dump 和插件管理请求；桌面端请在应用内插件面板操作。
• 安装完成后检查 ​~/.dsh/profiles/<profile>/package.json​ 的 ​dsh.profile.bundles​ 是否包含插件名。命令成功不等于 profile 一定会加载它。

5.4 重启与生效

插件面板会在需要时给出「重启」或「刷新页面」按钮。重启会中断进行中的任务，操作前先确认没有未完成的对话或后台任务。

5.5 值得先试的插件

插件生态更新很快，安装前建议看一眼仓库的 README、最近提交和 issue。如果你使用 ​dsh-plugin-shop​ 市场，要知道它做的是机械筛选，不等于人工安全审计。

5.6 插件安全

Host 插件拥有 Node 侧的代码执行能力，能访问文件系统、网络和进程；Client 插件运行在页面上下文，能力取决于宿主暴露的接口。安装第三方插件时至少要检查：

1. 仓库、许可证和维护者是否可核验。
2. 是否声明了与你当前 DSH 版本兼容的范围。
3. 是否要求与你任务不匹配的宽泛权限。
4. 是否把密钥、令牌或用户数据写到日志、网络请求或客户端代码里。
5. 是否能在测试 profile 中先跑通，再放进日常 profile。

插件不是「装了就绝对安全」的扩展。把它当成可执行代码来审查，尤其是需要访问文件、网络和凭据的插件。

六、一个完整的工作流示例

假设要给一个项目增加「导出 CSV」功能，可以这样组织对话：

第一步：只读检查

请先阅读 AGENTS.md、README 和导出相关的现有代码，确认：
1. 当前导出流程的入口和数据结构；
2. 已有测试和运行命令；
3. 可能影响的其他模块。
这一轮不要改文件。

第二步：计划与确认

基于上面的检查，给出最小改动计划：要改哪些文件、新增哪些测试、如何验证。
先不要执行，等我确认。

第三步：实施与验证

按确认后的计划实施。每改完一个文件说明意图，最后运行针对性测试和类型检查。
如果发现计划外的风险，先停下来说明。

第四步：复核与交付

请自查 diff，重点看边界条件、空数据、编码和错误处理；把结果整理成一段可粘贴的变更说明。

在这个过程中，DSH 会按需使用文件工具、命令工具和测试工具；长任务可以拆给子 Agent，重复性检查可以放进工作流。你要控制的是目标、范围和验收标准，而不是每一步的工具名。

七、常见问题

DSH 和 DeepSeek 网页版聊天有什么区别？

网页版聊天主要是对话；DSH 是本地 Harness，能读写工作区文件、执行命令、调用工具、持久化会话，并可以接入不同模型和插件。

只用 DeepSeek 模型可以吗？

可以。默认配置就是 DeepSeek 路由；需要其他模型时再添加提供方。

文件会被上传吗？

DSH 本身在本地运行，但对话上下文会发送给你配置的模型提供方。工具读取到的文件内容可能进入上下文，因此敏感文件不要交给不可信的模型或中转。沙箱限制的是写入范围，不是「文件绝不离开本机」。

Windows 能用吗？

可以。Windows 上默认使用 PowerShell 工具，沙箱通过 ACL 受限令牌实现。部分插件可能对 Windows 有额外要求，例如视频插件需要带 ​drawtext​ 的 ffmpeg。

会话保存在哪里？

默认在 ​~/.dsh/sessions​，具体格式随版本变化。迁移或备份时优先备份整个 ​~/.dsh​，并先退出 DSH。

插件装错了怎么办？

在插件面板卸载，或用 ​dsh plugin --profile <profile> remove <包名>​。如果已经影响启动，换一个测试 profile，或从 ​package.json​ 的 ​dsh.profile.bundles​ 中移除后重装。

八、参考来源

• DeepSeek Harness 官方入口：https://www.deepseek.com/harness/
• DSH 仓库：https://github.com/deepseek-ai/deepseek-harness
• npm 包 ​@deepseek-ai/dsh​：https://www.npmjs.com/package/@deepseek-ai/dsh
• 随包文档：​@deepseek-ai/dsh-base​、​@deepseek-ai/dsh-web-app​、​@deepseek-ai/dsh-client-ui-settings-models​、​@deepseek-ai/dsh-llm-pi-ai​、​@deepseek-ai/dsh-llm-deepseek​、​@deepseek-ai/dsh-tools​
• ​dsh-plugin-shop​：https://github.com/LivXue/dsh-plugin-shop
• ​dsh-context​：https://github.com/bowenliang123/dsh-context
• ​dsh-image-gen​：https://github.com/shanliuling/dsh-image-gen