DSH 入门：
从下载到第一个插件

DSH 是 DeepSeek 开源的 Agent 框架，走的是一条不太一样的路：一切都是插件。 模型负责想，外面那层负责跑——读写文件、开终端、连浏览器；而这外面一层的每个零件，包括界面本身，都是可以单独装卸的 npm 包。

好处是你能把它捏成自己要的形状；代价是第一次打开时会有点懵：没有「下一步」按钮，没有新手引导，左边一排设置项看不出优先级。 这篇就是补上那段引导：装好 → 拿到 Key → 跑通第一个任务 → 装三个真正有用的插件。中间不展开原理，只给能跑的命令。

1 · 先搞清楚你在装什么

DSH 本身不是一个安装包。它是 Node.js 上的一个 npm 包，核心那句 Agent = Model + Harness 里的 Harness，就是它。所以更准确的说法是：你装的是一个运行时，然后让它在本地起一个 Web 服务，你在浏览器里跟它说话。

也因此，只要机器上有 Node.js，剩下的都是一条命令的事。现在有两条路可以走：

DSH 目前还在开发者预览阶段，版本迭代很快，接口和插件生态都还会变。这不是劝退，只是提醒你：遇到教程和实际界面对不上时，先怀疑版本，用 dsh --version 对一下。

2 · 安装：两行命令

前置条件只有 Node.js 一个：Node.js 22 LTS 或更新（node -v 看版本）。插件管理额外需要 pnpm，没装的话先 npm i -g pnpm，等用到再装——第 6 章会说要它干什么。下面按系统给，第一行是「没装就顺手装上」，第二行才是 DSH 本体——跑完这两行就能进界面，第三行（改成全局命令）是可选的，放在本节末尾。

Windows

打开 PowerShell（右键开始菜单 →「终端」），整段粘进去：

# 没装 Node.js 就先用 winget 装一个
if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
  winget install OpenJS.NodeJS.LTS
}

# 启动（每次都会去 registry 取最新版）
npx @deepseek-ai/dsh web

装完 Node 之后要重开一个终端，否则 PATH 还没刷新，第二行会报 node 不是内部或外部命令。

macOS

用 Homebrew 装 Node，再启动。没有 Homebrew 的话，去 nodejs.org 下 LTS 的 pkg 也可以：

command -v node >/dev/null 2>&1 || brew install node
npx @deepseek-ai/dsh web

Linux / WSL

Debian、Ubuntu 系用 NodeSource 的源最省事。注意 WSL 里跑的 DSH 是 WSL 里的一个进程， 工作区要选 Linux 侧的路径（/home/you/project），从 Windows 盘符访问的性能会明显差一些。

command -v node >/dev/null 2>&1 || (
  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - &&
  sudo apt-get install -y nodejs
)
npx @deepseek-ai/dsh web

把 dsh 变成全局命令（可选，但建议）

npx 每次启动都要重新解析一遍包，慢，而且版本会飘。用久了就把它装成全局命令：

npm install -g @deepseek-ai/dsh
dsh --version        # 确认装上了，顺便记下版本号
dsh web              # 以后都用这条启动

安装过程中如果哪条命令和你机器上对不上，别照着搜索结果瞎试：命令、参数和版本号以官方文档为准——dshbase.com。

3 · 第一次启动

命令跑完，终端只会打出一行地址，形如（端口号和 token 每次都可能不同）：

dsh web: http://127.0.0.1:3099/?token=SY9stAfNBFPofXXCvPhddEr2sJekqC_XJCdZfO4lDMk

多数情况下它会自己把浏览器打开，那一行你不用管。没自动开的话，把整行地址连 ?token= 一起复制到浏览器——去掉 ?token= 只会得到一个 401 页面，那不是装错了，是地址不全。WSL 和 SSH 里自动开浏览器通常不生效，这条对你尤其重要。

第一次打开会先弹一个「添加一个 API Key 开始使用」的框，上面还挂着一条「预览版说明」的欢迎条。这个框来得有点早——先点「稍后配置」跳过，我们按顺序来，Key 在第 4 章拿。关掉之后看到的是：左边是会话列表，中间是对话区，设置入口在左下角，跟着那排小图标找。先别急着发消息——现在还没有 Key，发出去只会得到一句报错。

顺序应该是：填 Key → 选工作区 → 发第一个任务。顺便说一句，第 4 章填完 Key 之后，那个弹窗就再也不会出现了。

4 · 获取 API Key

模型是要花钱的，所以这一步绕不开。整个过程大概五分钟。

不用 Web 界面的话，Key 怎么给

跑无头模式、或者写脚本的人，Key 有两个来源。优先用环境变量——一行就够、跨平台，不会踩文件格式：

DEEPSEEK_API_KEY=sk-你的key dsh web

$env:DEEPSEEK_API_KEY="sk-你的key"; dsh web

要长期生效就改文件：~/.dsh/.credentials.yaml（Windows 是 %USERPROFILE%\.dsh\.credentials.yaml）。这个文件在你第一次 dsh web 时就已经存在了，所以是往里加一段，不是覆盖它；必须加在 refs: 下面，加到顶层会被静默忽略，重启也不报错：

version: 1

refs:
  DEEPSEEK_API_KEY: sk-你的key

records: {}

5 · 设置工作区

这一步比看起来重要。Agent 能做的所有文件操作，都被限制在你指定的目录里——选错了，它要么什么都改不了，要么在一个你不想被改的地方动手。

建议第一次就做三件事：

• 新建一个空目录当试验田，别一上来就选你的主力项目。
• 在 DSH 里把这个目录添加为工作区，然后确认界面显示的是绝对路径。
• 发一个不痛不痒的验证任务，比如「在工作区根目录建一个 hello.txt，写一句话进去」。能建出来，说明读写权限是通的（「工作区根目录」指你刚添加的那个目录，不是你磁盘的根目录）。

之后你对 Agent 说的每一句「改一下这个文件」，作用范围都在这块地里。这也是为什么后面装沙箱类插件时，你需要再回来检查一次这里的设置。

6 · 插件：选三个就够

插件生态很大，但入门阶段装太多只会互相打架，还拖慢每次启动。下面三个是我自己留在配置里、并且几乎每天都会碰到的。它们解决三个不同层面的问题：安全、上下文、体验。

命令里会带一个 --profile web，第一次见容易懵：profile 指的是你启动时用的是哪一套插件组合。 dsh web 用的就是 web 这一套，插件装在它上面才会被加载；如果你用别的 profile 启动，这里装的就不生效——这也是「插件装了但没反应」最常见的原因。

用桌面客户端的注意了：那边是独立的 desktop profile，这个名字保留给 Electron，上面这些命令会被 CLI 直接拒绝。桌面客户端请在应用内的「插件」面板里装，下面的命令只适用于 CLI。

下面块里给的是真实包名，你装别的就把包名换掉；行尾 # 后面是注释，复制进终端不影响执行。

dsh plugin --profile web add cc-safety-net   # 装，最后的包名换成你要装的
dsh plugin --profile web list                # 看装了什么
dsh plugin --profile web remove cc-safety-net # 卸

怎么判断一个插件值不值得装

生态里同类的包很多，质量差得也挺远。我的判断顺序是这样：

1. 它替你省下的是哪一步？如果那一步你一天做不了一次，就不值得为它增加一次启动开销。
2. 出错时会怎样？插件是在你的机器上跑代码的。安全类、文件类插件，优先选有明确边界和拒绝行为的。
3. 还维护吗？看最近一次发布的时间，比看 Star 数有用得多。

还有一个反直觉的建议：装完一个插件，先用一周再装下一个。同时装五个，出问题时你根本不知道该卸哪个。

7 · 把它跑成一个完整工作流

到这儿零件都齐了。用一个真实的小任务串一遍，你会更清楚它擅长什么、不擅长什么：

这套流程的核心不是命令，而是语气：先读后写、小步验证、要求证据。 对 Agent 和对实习生，其实是一回事。

8 · 常见错误对照表

把第一次安装最可能撞上的几个坑先放这儿，省得你再去搜：

先对一下版本：本文的界面位置和终端输出基于 dsh 0.2.1-rc.2 实测核对，你敲 dsh --version 看到的如果比这更新，个别按钮可能挪了位置——以你屏幕上的为准，下面的报错文本一般不会变。

9 · 接下来可以去哪

走完这一遍，DSH 对你来说就不再是黑盒了：你知道它是个本地服务、知道能力从哪来、知道出问题先看哪儿。 再往下有三个方向，选一个顺手的就好：

• 想用得更好——继续挖插件，但一次只加一个，加完用一周。
• 想动手写——插件就是一个导出 apply 函数的 TypeScript 模块，注册工具的部分不到二十行，找个下午就能跑起来。
• 想接进工作流——先把它用在「写测试」「改文档」「读陌生代码库」这三类任务上，收益最直接。

想读源码、或者想提 issue：github.com/deepseek-ai/DeepSeek。装不上、报错看不懂的时候，先去那儿搜一遍，多半已经有人踩过同一个坑。

最后一句经验：它最大的价值不是替你打字，是替你试错。 那些你懒得跑一遍的命令、懒得读的文件，扔给它；但结论要自己看一遍。这个习惯养成了，工具才真的开始省时间。