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

古雨蓝枫2026-10-26 13:12

一、DSH 是什么

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

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

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

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

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

形态 启动方式 适合场景
桌面应用 安装 DeepSeek Harness 桌面端 日常交互、文件预览、插件管理
Web GUI ​dsh web​ 或 ​dsh --profile web​ 浏览器访问、局域网使用、与桌面端共用同一套能力
无头 / 程序化 ​dsh --profile headless "任务"​、​dsh --profile sdk​、​dsh --profile acp​ 脚本、CI、SDK 集成、自动化客户端

官方入口：DeepSeek 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 常用工具一览

需求 DSH 中的能力
读文件、找文件、搜内容 ​read​、​glob​、​grep​
改文件 ​write​、​edit​
执行命令 ​pwsh​（Windows）/ ​bash​，支持后台任务
查资料 ​web_search​、​web_fetch​
拆分大任务 ​subagent​、​subagent_fork​、​workflow​
长周期目标 ​create_goal​，可跨多轮继续
定时提醒 / 周期任务 会话内 Schedule，或侧边栏的「自动化任务」
任务清单 ​todo_write​
交付文件 ​present​
向用户追问 ​ask_user_question​
按需加载流程说明 ​skill​
计划模式 先出计划，确认后再执行

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

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 的文件策略大致有三档：

策略 含义 适用场景
​read-only​ 只读，不允许写入 代码审查、资料分析
​workspace-write​ 只能写工作区和会话临时目录 日常开发，推荐默认
​danger-full-access​ 不受工作区限制 一次性容器、可丢弃环境

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

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

3.8 图片、视频与生成式 UI

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

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

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

3.9 典型用途

场景 可以怎么说 主要能力
代码开发与维护 「定位这个报错，做最小修复并跑测试」 文件读写、命令执行、测试、子 Agent
文档与知识整理 「读这个目录，按现有风格补一篇说明」 文件工具、​AGENTS.md​、Skill
资料调研 「查这几个问题，交叉核对后给结论」 网页搜索/抓取、子 Agent、工作流
日常自动化 「每天下午提醒我检查发布状态」 定时任务、后台任务、目标
数据分析 「读这份 CSV，写脚本统计并生成报告」 文件读取、本机脚本/命令、交付文件
图片与视频创作 「按这个分镜生成竖屏短片」 图片/视频插件、工作流

这些场景不需要一次记住所有工具。把目标、输入、输出格式和验收标准说清楚，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. 选择「添加自定义提供方」，手动填写端点、协议和模型。

自定义提供方至少需要：

字段 说明
Provider ID 唯一、稳定的路由名，也是 settings 的键和凭据引用的名字
显示名称 模型选择器里显示的名字，可随时改
端点 / Base URL 必须是可解析的 HTTP(S) 地址；本机 ​localhost​、IPv4、IPv6 和自定义端口都可以
API 协议 决定请求体格式，必须和端点匹配
API 密钥 只写保存，不会回显
模型 至少一个可识别的模型 id；可以手动添加，也可以从端点拉取

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

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

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

4.2 协议怎么选

端点类型 建议协议 典型场景
OpenAI Chat Completions 兼容 ​openai-completions​ 大多数中转站、Ollama、vLLM、LM Studio
OpenAI Responses API ​openai-responses​ OpenAI 官方 Responses 接口或兼容实现
Anthropic Messages ​anthropic-messages​ Claude 官方 API 或兼容网关

协议选错时，最常见的表现是 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 常见问题

现象 可能原因 处理
401 / 403 密钥错误、过期，或端点不认这种鉴权 检查密钥、Base URL 和协议
404 Base URL 路径不对，或端点不支持所选协议 尝试提供方文档给出的根地址或 ​/v1​ 地址
400 / 返回体解析失败 协议选错 OpenAI 兼容多用 ​openai-completions​，Claude 用 ​anthropic-messages​
模型列表为空 端点不支持 ​/models​ 手动填写模型 id
模型不在选择器里 提供方未保存成功，或路由注册失败 回到模型页看诊断信息
长对话突然截断 ​contextWindow​ 填小了 按提供方文档修正
保存被拒绝 另一个标签页或外部编辑造成冲突 重新加载配置后再改

五、插件的安装与使用

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 重启与生效

操作 是否需要重启
启用/禁用已安装插件 通常热生效
安装新的 host 插件 需要重启 profile
安装带客户端入口的插件 通常需要重启，并刷新页面
更新已有插件 按插件提示，通常重启
只改插件配置 多数情况下下一次请求生效

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

5.5 值得先试的插件

插件 用途 说明
​dsh-plugin-shop​ 插件市场 浏览、安装、启用/禁用、更新插件
​dsh-context​ 上下文与成本洞察 上下文组成、token/费用趋势、会话列表、Agent 网络
​dsh-image-gen​ 图片生成与编辑 多家图片提供方，支持图生图和连续编辑
​dsh-genui​ 生成式 UI 把回复变成表单、图表、计算器等可交互界面
​dsh-video-generator​ 视频 / 短剧 / 漫剧 故事、剧本、分镜、成片管线，9:16 输出

插件生态更新很快，安装前建议看一眼仓库的 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，重复性检查可以放进工作流。你要控制的是目标、范围和验收标准，而不是每一步的工具名。

相关推荐
爱编程的小新☆1 小时前
LangChain 智能体实战：构建技术学习规划 Agent
langchain·agent·工具调用·结构化输出·deepseek·流式输出
ZzT2 小时前
Claude Duet 安全设计拆解：替你回邮件、付账单的 agent，碰不到你的密码
ai编程·claude
最强小杰2 小时前
Continue + minimax-m3 接入教程：协议、模型 ID、404 与工具调用排错
arcgis·ai
小七-七牛开发者2 小时前
当 Agent 接手更多工作，我们还能把好关吗？
ai·openai·agent·claude
threerocks2 小时前
天涯神贴《2027年以后，你要活成这个样子》有感，希望 2027 年可以活成自己想要的样子
aigc·openai·ai编程
李航19832 小时前
虚拟盖房子，在游戏中学习房子的建造过程
人工智能·学习·游戏·计算机视觉·ai编程
Carson带你学Android2 小时前
Claude Duet 发布：又一个手机Agent可以用了！
agent·ai编程
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05几个好用的ip纯净度检测网站06苹果iPA游戏软件资源下载网站07昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战08ai安全工具:CyberStrikeAI安装部署与使用09蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接10Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）