CH 03 · 安装与启动
本章目标
这一章把 dsh 从零跑起来：先确认/安装 Node.js，再一条命令启动 Web UI，然后完成首次配置（模型密钥 + 工作区），最后发出第一条真实任务。做完你就正式上手了。
动手前：你只需要两样东西
- Node.js——dsh 运行在 Node 上，这是唯一的环境依赖，不装数据库、不配 Java。
- 一个 DeepSeek API Key——dsh 本身免费开源，但调用模型要花钱。去 DeepSeek 开放平台 注册登录，左侧"API Keys"→ 创建，复制保存。Key 只完整显示一次，格式是
sk-开头一长串，先存到安全的地方再关页面。
第 1 步：检查本机 Node.js
打开终端（Windows 按 Win + R，输入 cmd 回车），敲：
node --version
npm --version看到版本号就说明装好了。dsh 对 Node 版本有要求，官方声明是 ^22.19 || >=24，翻译成大白话：Node 22.x 里 22.19 及以上的版本，或者 Node 24 及以上。换句话说：22.19 之前的旧 22.x、以及 Node 23 这类奇数版本都不支持，装了会直接启动失败。
如果你和我一样早就装过 Node，版本又达标，直接跳到第 3 步。
第 2 步：没有 Node.js？先装一个（Windows）
打开 Node.js 官网，下载 LTS 版本的 Windows 安装包（.msi，64 位），双击一路"下一步"即可。默认会同时装好 npm 并写入系统 PATH。
装完一定记得重新打开终端再验证——很多时候"明明装了却找不到命令"只是环境变量没刷新：
node --version
npm --version第 3 步：给 npm 换国内镜像（可选但强烈推荐）
国内网络直接拉 npm 包经常很慢或超时。换成淘宝镜像能快很多：
npm config set registry https://registry.npmmirror.com
npm config get registry看到 https://registry.npmmirror.com 就是生效了。
第 4 步：安装并启动 dsh
本教程用 npm 全局安装：一条命令装好，之后
dsh命令随处可用，不用每次现场下载，对新手最省心。
装好全局包：
npm install -g @deepseek-ai/dsh装完验证一下版本：
dsh --version然后启动 Web UI：
dsh web第一次运行会花一两分钟下载依赖，终端滚动输出一堆日志，正常。看到类似下面这样，就是启动成功了：
dsh web: http://127.0.0.1:3080
dsh web: opening the default browser; pass --no-open to disable
想更新到最新版（全局安装不会自动更新，手动来）：
npm install -g @deepseek-ai/dsh@latest第 5 步：打开 Web UI
第一次运行 dsh web 会自动打开浏览器进入界面。如果没自动弹出来，就手动打开浏览器访问：
http://127.0.0.1:3080这是本地回环地址，只在本机生效，不会暴露给外网。
第一次打开会弹一个内测声明——DeepSeek Harness 0.1 还是面向开发者的测试版本，会持续快速迭代。点继续进主界面。
第 6 步：首次配置（密钥 + 工作区）
6.1 填 API Key 上一步点完继续后，dsh 会直接弹出"添加一个 API Key 开始使用"引导框——把 sk- 开头的密钥粘进输入框，点保存并继续。（之后想改 Key 或换模型，走左下角设置 → 模型 也行。）
Key 只写在本地
C:\Users\<你的用户名>\.dsh\.credentials.yaml，界面不回显明文，不要截图发出去。
6.2 选工作区 填完 Key 就进入主界面了。点选择工作区下拉，选一个你想让 Agent 干活的工作目录（比如你的项目文件夹）即可。选中工作区之前，底部输入框一直提示"选择一个工作区开始"，这是刻意设计——没告诉 Agent 在哪个地盘干活，它不敢动。
6.3 选模型和权限（发第一条任务前定好） 选中工作区后，右下角弹出模型选择面板，可以看到 DeepSeek 的三种模型：
| 模型 ID | 定位 |
|---|---|
deepseek-v4-pro | 旗舰，最强但最贵 |
deepseek-v4-flash | 快速、高性价比 |
deepseek-v4-flash-vision-exp | 多模态视觉版：能读图、看截图、分析图表，纯文本能力与 flash 持平，多模态能力大幅领先 |
deepseek-v4-flash-vision-exp 是 DeepSeek V4 家族第一款视觉模型（实验版，2026 年 8 月 21 日上线 API、8 月 31 日开源权重）。它能读图、看截图、分析图表，也能跑普通文本任务，本蓝皮书所有演示统一使用这个模型——在面板里选中它，推理等级按需（默认 High 就行），保存后立即生效，不用重启。
底部输入框左侧还有一个权限选型（截图里是 Workspace Write），决定 Agent 能动你电脑的哪些地方，先保持默认。这些选项的详细区别（三个权限各能干什么、推理等级怎么取舍）到 CH 04 讲界面时再展开。
第 7 步：跑通第一个任务
新建一个会话，输入一句话，比如：
总结一下 DeepSeek harness 这个仓库，指出它的主要模块。
Agent 会开始读文件、跑命令、维护计划，每一步工具调用都摊开在界面上——截图里能看到 上下文注入 → Think → Pwsh → Read 的完整执行链。涉及敏感操作时，按当前权限策略它会先弹窗问你。界面左上角有 对话 / 轨迹 两个标签，轨迹就是 CH 02 说的 Trajectory，后面会专门讲。
等它跑完，会给你一份完整总结——我这次的回答标题是"DeepSeek Harness 仓库总结"：一句话定位是"一切皆插件的 AI Agent 运行框架/工作台，基于 Cordis 构建"，还梳理了仓库 packages/apps/docs 的目录结构和 dsh-* 系列包的主要模块。
跑通这一步，你就正式上手了。
进阶玩法
换端口（3080 被占用时）：启动的时候用下面的命令替代 dsh web——
dsh web --port 8080然后访问 http://127.0.0.1:8080。
命令行一次性任务（headless）：
dsh --profile headless "把当前目录的测试跑一遍并汇总结果"跑完打印结果退出，适合脚本和 CI。headless 的完整玩法（多入口、CLI 参数、真实实操）我们放到 CH 05 专门展开。
查看实际生效的配置树（排障很有用）：
dsh web --dump-config常见问题排查
| 现象 | 处理 |
|---|---|
node 不是内部或外部命令 | Node 没装好或没重开终端，重新打开 PowerShell 再试 |
| Node version ... is not supported | 版本低于 22.19 或用了 Node 23，升级到 22.19+ / 24 |
| 首次安装卡住或下载失败 | 网络问题，先配 npmmirror 镜像再重试 |
| 端口 3080 被占用 | 换端口 dsh web --port 8080 |
| 页面打不开 | 确认启动命令的终端窗口还开着，地址是 http://127.0.0.1:3080 |
报 MISSING_CREDENTIAL | 没存 API Key（去设置 → 模型填）或没重开窗口 |
报 UNKNOWN_MODEL | 选了没配置的模型，去自定义供应商把模型 ID 补上 |
| 报原生编译错误（node-pty 等） | Windows 需装 Visual Studio Build Tools（含 C++ 组件） |
安全提醒：API Key 就是你的钱袋子，别截图发群里、别提交进 git 仓库；怀疑泄露就去平台吊销重建，旧 Key 立即失效。
这一章你学到了什么
能自己完成下面几条，就算过关：
- [ ] 能用
node --version确认 Node 版本在 22.19+ / 24+（不在就按第 1 步装好） - [ ] 用
npm install -g @deepseek-ai/dsh装好 dsh，dsh web启动并在http://127.0.0.1:3080打开界面 - [ ] 完成首次配置：设置 → 模型填好 API Key，并选中工作区
- [ ] 成功发出第一条真实任务并看到 Agent 干活