DeepSeek Harness（dsh）

DeepSeek 官方开源的 Agent 运行框架，命令行叫 dsh。 它的作用是让模型能真正「动手干活」：读取你的项目文件、修改代码、执行命令、拆解长任务， 并且每一步都能看到推理过程和工具调用。本页教你把它接到聚合AI。

本页内容

1. 完全新手篇：终端怎么开、命令怎么粘（务必先看）
2. 准备三样东西
3. 第 1 步：启动 dsh
4. 第 2 步：把本站配置进去
5. 第 3 步：选择工作区
6. 第 4 步：发第一个任务
7. 第 5 步：确认已接上本站
8. 常见问题（照着查）
9. 进阶：直接改配置文件（可选）
10. 费用与安全提醒

完全新手篇：终端怎么开、命令怎么粘

如果你没用过「终端」「命令行」「PowerShell」这些词，这一节就是为你写的。整个过程只有三个动作：打开终端 → 复制命令 → 粘贴并回车。

① 先打开一个「终端」窗口

终端就是一个可以用文字下命令的黑框框，你电脑里本来就有，不用装。按你的系统照做：

你的系统	怎么打开（任选一种）
Windows 10 / 11	方法一：按键盘 Win 键 → 直接输入 powershell → 点出来的「Windows PowerShell」。 方法二：按 Win + X → 在菜单里点「终端」或「Windows PowerShell」。 （Windows 里黑色的「命令提示符 cmd」也能用，但推荐 PowerShell。）
macOS	方法一：按 Command + 空格 → 输入 终端（或 Terminal）→ 回车。 方法二：访达 → 应用程序 → 实用工具 → 终端。
Linux	多数桌面环境按 Ctrl + Alt + T 即可；或在应用菜单里搜「终端 / Terminal」。

打开后你会看到一个窗口，里面有类似 PS C:\Users\你的名字> 或 你的名字@MacBook ~ % 的字样，最后那个符号（> 或 % 或 $）表示它在等你的命令。这就是对的。

② 复制本页的命令

本页每一个灰色代码框的右上角都有一个「复制」按钮，点一下，整条命令就复制好了。不用手动拖鼠标选中。

③ 粘贴进终端，然后按回车执行

在终端窗口里粘贴，粘贴完必须按一下回车键（Enter），命令才会开始跑。粘贴快捷键对照：

系统	在终端里粘贴	补充说明
Windows	Ctrl + V，或在窗口里点鼠标右键	Win10 老版本控制台：右键就是粘贴。Ctrl+V 不行时用右键。
macOS	Command + V	—
Linux	Ctrl + Shift + V	Linux 终端里 Ctrl+V 不是粘贴，要用组合键或右键。

粘贴后你应该能看到命令文字出现在窗口里，光标停在末尾 —— 再按回车，它就开始执行了。

④ 怎么算成功、怎么算失败

你看到的	说明
窗口滚出一堆文字后停住，出现 http://127.0.0.1:3080 这样的网址	成功。浏览器通常会自动打开这个页面；没自动开就手动复制这个网址到浏览器地址栏。
窗口滚出很多 npm warn 开头的黄字	多数只是警告，不影响使用，继续等它跑完即可。
出现 'node' 不是内部或外部命令 / command not found: node	电脑还没装 Node.js，去做第 0 步。
出现 npm.ps1 ... 禁止运行脚本（Windows 常见）	PowerShell 的安全策略拦住了 npm。见下面「Windows 的两个常见坑」。
窗口像卡住了，好几分钟没有任何新文字	多半在联网下载（第一次要下载程序本体）。先等够 5 分钟；仍不动就按 Ctrl+C 停掉，换国内镜像后重试（见下）。
其它任何看不懂的红色报错	不用怕，把终端里最后 5～10 行文字复制下来发给客服，我们帮你看。

⑤ Windows 的两个常见坑

坑一：提示「禁止运行脚本」（无法加载文件 npm.ps1）。这是 PowerShell 默认策略导致的，不是命令写错了。两种解法，任选一种：

• 解法 A（推荐，一次解决）：把下面这条命令粘进 PowerShell 并回车（它会问一句，输入 Y 再回车）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

• 解法 B：不用 PowerShell，改用「命令提示符」：按 Win 键 → 输入 cmd → 打开后在黑窗口里执行同样的命令。

坑二：下载卡住不动。换成国内镜像再试（只影响本机 npm 的下载来源，不影响使用）：

npm config set registry https://registry.npmmirror.com

想改回官方源：把上面那条的地址换成 https://registry.npmjs.org 再执行一次即可。

⑥ 怎么停、怎么再开、怎么换目录

想做的事	怎么做
停止服务	在正在运行它的那个终端窗口里按 Ctrl + C（macOS 也是 Ctrl+C）。直接关掉窗口也可以。
下次再用	重新打开终端，再执行一次第 1 步那条命令即可（配置会记住，不用重填）。
先进入某个文件夹	用 cd 命令，例如 cd "D:\我的项目"（macOS/Linux：cd ~/Projects/demo）。路径里有空格一定要加英文双引号。不是必须的，第 3 步在网页里选工作区也可以。
怎么知道文件夹的完整路径	Windows：在资源管理器里进到该文件夹，点一下顶部地址栏，路径会变成可复制的文本。macOS：右键该文件夹 → 按住 Option 键 → 选「拷贝…为路径名称」。

开始之前：准备三样东西

1. 一台装了 Node.js 的电脑（下面第 0 步教你怎么装、怎么确认）。
2. 一把聚合AI 的 API 密钥：登录本站控制台 → 左侧「API 密钥」→ 新建，复制形如 sk-xxxxxxxx 的那串字符（只显示一次，先粘到记事本）。
3. 一个准备让它干活的文件夹：比如你的代码项目目录。记住它在哪，第 3 步要选它。

0安装 Node.js（已装可跳过）

在刚打开的终端里，粘贴下面这行并回车，能显示版本号（v20 以上）就说明装好了：

node -v

看到 v22.13.0 这样的输出 = 成功，可以直接跳到第 1 步。
看到「不是内部或外部命令 / command not found」= 还没装，按下表装完再回来。

系统	怎么装
Windows	打开 nodejs.org 下载 LTS 版，双击一路点「下一步」；或在 PowerShell 里执行 winget install OpenJS.NodeJS.LTS。装完关掉旧窗口、重新开一个终端，再执行 node -v。
macOS	到 nodejs.org 下载 LTS 的 .pkg 双击安装；装了 Homebrew 的话执行 brew install node。
Linux	执行 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt install -y nodejs。

1启动 dsh（就一条命令）

在终端里粘贴这一条，回车：

npx @deepseek-ai/dsh web

第一次运行会联网下载程序，等 1～3 分钟属正常（屏幕不动也在下载）；之后启动只要几秒。
跑完会自动打开浏览器，地址是 http://127.0.0.1:3080；没自动打开就手动把地址复制到浏览器。

2把本站配置进去（关键一步）

全部在刚才打开的网页里点鼠标操作，不需要改任何配置文件：

1. 在网页左侧打开 设置 → 模型（Settings → Models）。
2. 点 添加模型提供商（Add model provider）。
3. 把卡片顶部切换成 自定义模型 API（Custom model API）。
4. 按下表把 5 个字段照抄进去（「填什么」那一列可以直接复制）：

字段	填什么	说明
Provider ID	juheai	小写字母。填了就不能改，改只能删掉重建，所以别乱填。
显示名称	聚合AI	随便写，只用于你自己辨认。
Base URL	https://api.juheai.shop/v1	末尾的 /v1 必须带，末尾也不要多打斜杠。
API 协议	OpenAI Chat Completions	在下拉里选这一项（本站按此协议对接）。
API 密钥	你复制的 sk-xxxxxxxx	粘贴时注意前后不要带空格或换行，粘完可以再看一眼首尾字符。
模型	deepseek-v4-pro deepseek-v4-flash	点 获取可用模型（Fetch available models）可自动列出并勾选；如果拉取失败，就手动把这两个模型 id 一个一个填进去，效果完全一样。

最后点保存。配置改完立即生效，不需要重启服务。

3选择工作区（新手最容易漏的一步）

点界面上的 选择工作区（Choose workspace），添加并选中一个文件夹—— 它就是 AI 被允许操作的目录。建议先用一个不重要的小项目试手。

4发第一个任务

工作区选中后，在底部输入框里粘贴下面这句（这是一个只读任务，不会改动你的文件），然后发送：

分析这个项目的目录结构，说明它是做什么的、怎么启动，列出主要模块。不要修改任何文件。

稍等片刻，你会看到它一边思考一边调用工具（读文件、列目录等）。 如果某个操作需要你确认，界面会先弹出来问你，你点同意它才继续。

5确认已经接上本站

• 回到本站控制台 → 使用日志，能看到刚刚的调用记录（模型名、token 数、扣费），说明走的就是本站额度。
• 如果日志里没有记录，说明请求没发到本站，回到第 2 步检查 Base URL 和密钥。

常见问题（照着查）

现象	原因与处理
不知道终端在哪、命令没地方贴	看本页最上面的完全新手篇，里面有各系统打开终端的步骤和粘贴快捷键。
粘贴后没有任何反应	大概率是没按回车。命令只是被贴进窗口，还需要按一下 Enter 才会执行。
输入框是灰的，发不出消息	没选工作区。点「选择工作区」添加并选中一个文件夹。
MISSING_CREDENTIAL / 提示密钥缺失	密钥没保存成功。回「设置 → 模型」重新粘贴密钥并保存；粘贴时注意不要带上多余空格或换行。
UNKNOWN_MODEL	你选的模型没在这个提供商里登记。编辑该提供商，把 deepseek-v4-pro / deepseek-v4-flash 补进模型列表。
报 401 / Unauthorized	密钥错误或已删除（控制台里核对一下）；也可能是 Base URL 漏了 /v1。两者都检查一遍。
「获取可用模型」返回 401 或列表为空	该功能是便利选项，不是必须的。改成手动填写模型 id 即可正常使用。
密钥和地址都对，但所有请求都被网关拒绝	部分中转网关不接受 OpenAI 的原样请求。按下面「进阶」加两行兼容开关（supportsDeveloperRole: false、maxTokensField: max_tokens）。
只有「会思考的模型」失败	同上：这类模型的系统提示会以 developer 角色发送，网关不认。加 supportsDeveloperRole: false。
浏览器打不开 127.0.0.1:3080	终端窗口被关了，或换了目录重新运行过。重新执行第 1 步的命令；端口被占用时可用 npx @deepseek-ai/dsh web --port 3081。
提示没有权限、命令执行失败	工作区目录选得不对，或系统权限限制。换一个你有完全权限的项目目录再试。
重启电脑后又要重新弄一遍吗	不用。配置会被记住，只要重新执行第 1 步那条命令即可。

进阶（可选）：直接改配置文件

网页上能配的字段是基础项。如果你想加兼容开关、限制超时、声明模型能力，可以编辑这个文件（dsh web 默认档案名为 web）：

$DSH_HOME/profiles/web/cordis.patch.yml

接入本站的最小配置长这样，可直接复制后替换密钥环境变量名：

- id: llm-pi-ai
  config:
    providers:
      juheai:
        apiKeyEnv: JUHEAI_API_KEY
        api: openai-completions
        baseURL: https://api.juheai.shop/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: deepseek-v4-pro
          - id: deepseek-v4-flash

· 密钥文件在 $DSH_HOME/.credentials.yaml（网页上保存的密钥存这里），也可以用 apiKeyEnv 指向环境变量。
· 改完不需要重启，下一次请求就会读取新配置。
· compat 两行是「网关挑食」时的万金油：先加上，若一切正常也可以去掉。

费用与安全提醒

• 费用：Agent 任务是一轮轮工具调用串起来的，token 消耗比普通对话高不少。日常建议用 deepseek-v4-flash，复杂任务再切 deepseek-v4-pro。本站缓存读的单价远低于输入价，重复读取同一份大文件时更省。
• 安全：它会真的读写你指定的文件夹、执行命令。不要把密钥文件、客户数据、生产环境目录设为工作区；敏感操作留意确认弹窗。
• 版本：dsh 目前处于开发者预览阶段，官方明确说会有破坏兼容性的更新。升级后用不了就按本页步骤重新配置一次。
• 官方文档：deepseek-harness.github.io　源码：github.com/deepseek-ai/deepseek-harness