安装流程简图
这份指南带你在一台 Mac 上完成 DeepSeek Harness 的本地启动、模型配置、工作区选择和最小对话验证。完成后，你会得到一个运行在 http://127.0.0.1:3080 的本地 Web UI，并能让 Harness 在指定工作区内处理文件任务。
一、准备工作
- 一台已安装 Node.js 与 npm 的 Mac；
- 可访问 DeepSeek API 开放平台的账号；
- 一个 DeepSeek API Key；
- 一个专门用于教学或项目的本地工作目录。
安全提醒： API Key 相当于调用服务的凭据。完整 Key 通常只在创建时显示一次，请单独保存，不要发给他人，也不要出现在截图、录屏、代码仓库或公开文档中。
官方开源仓库为 ：
二、创建 DeepSeek API Key
- 打开 DeepSeek 官方 API 平台并登录。
- 进入左侧的 API keys。
- 点击右上角 创建 API key，输入便于识别的临时名称。
- 创建成功后立即复制并妥善保存完整 Key。
回到列表看到新记录，只能说明 Key 已准备好；是否能被 Harness 正常使用，要到“最小对话验证”步骤确认。
三、确认官方项目与启动命令
官方项目名为 DeepSeek Harness，命令行启动器为 dsh。当前录屏中的官方 README 标注为开发者预览阶段，未来可能出现不兼容变化。
普通用户无需克隆源码，最短启动命令是：
npx @deepseek-ai/dsh web
默认本地地址是：
http://127.0.0.1:3080
四、检查环境并启动本地 Web UI
1. 检查 Node.js 与 npm
打开终端，依次执行：
node -v
npm -v
本次实录返回 Node v26.0.0 与 npm 11.12.1。这两个版本只是本次成功实录值，不是本文证明过的最低版本要求。
2. 启动 DeepSeek Harness
npx @deepseek-ai/dsh web
第一次执行会获取并初始化所需内容。终端出现以下输出，才说明本地 Web 服务已启动：
dsh web: http://127.0.0.1:3080
3. 打开本地页面
保持终端进程运行，在浏览器打开 http://127.0.0.1:3080。首次进入时会看到内部声明或 API Key 配置提示。
五、配置模型、权限与工作区
- 在首次弹窗中粘贴 DeepSeek API Key 并保存；也可以稍后进入 设置 → 模型 → DeepSeek 配置。
- 在通用设置里确认语言与 Agent 预设；需要生成或修改文件时，将权限设为 Workspace Write。
- 创建或选择一个独立工作区。建议使用空目录，避免误改其他项目文件。
- 选择 DeepSeek 模型与推理等级。实录界面提供 Off / High / Max 等选项；入门阶段先选择能稳定响应的配置即可。
权限提示：
Workspace Write会允许 Harness 写入所选目录。不要把家目录、含隐私资料的目录或重要仓库根目录直接作为练习工作区。
六、用最小对话验证部署
- 新建会话。
- 确认工作区、模型和推理等级已经选好。
- 发送：
你好 - 收到真实回复后，再进入文件生成任务。
这一步能证明当前这台 Mac 上的 Harness、API Key 和模型已经连通；它不证明文件写入、复杂任务、跨平台兼容或长期稳定性。
我们选定模式，点击新会话，输入需求即可开启对话：
使用过程还会帮我们分析需求：
DeepSeek Harness 权限用于控制智能体（Agent）访问本机文件、执行命令的范围，安全等级从高到低：Read Only > Workspace Write > Full access。
- Read Only： 仅可读取工作区文件，无法修改文件、执行终端命令，安全性最高。
- Workspace Write： 允许读写当前工作目录内文件，可在工作目录执行命令，无法访问工作目录以外文件，日常开发推荐使用。
- Full access： 拥有完整文件系统访问权限，可读写任意路径文件、执行各类终端指令，存在较高安全风险。
七、提交第一个文件任务
- 在独立工作区中新建会话。
- 一次性提交完整任务，至少写清：目标、内容事实、页面或文件结构、视觉与交互要求、禁止项和完成标准。
- 等待 Harness 返回“已完成”和本地文件绝对路径。
- 把返回路径放进浏览器或对应应用中，人工打开检查。
实录案例最终返回 /Users/mac/Documents/deepseektest1/index.html，并在 Chrome 中成功打开生成页面。Harness 报告静态检查通过，但自动浏览器检查受本机沙箱环境限制中断，因此不能据此宣称完成了像素级视觉验收、移动端验收或跨浏览器验收。
八、常见问题
终端没有返回本地地址：确认 Node.js、npm、网络状态和命令拼写与官方 README 一致。
浏览器打不开 127.0.0.1:3080：确认终端中的 dsh 进程仍在运行，并以终端实际返回的地址为准。
模型不可用或无回复：重新检查 API Key、模型配置、账号余额或调用额度。
无法写入文件：确认已选择正确工作区，并将权限设为 Workspace Write。
自动浏览器验证失败：手动打开返回路径，并如实记录未验证项。
| 现象 | 先检查什么 |
|---|---|
| 终端没有返回本地地址 | 确认 Node.js、npm、网络状态和命令拼写与官方 README 一致；不要继续录制或假设已经启动。 |
| 浏览器打不开 127.0.0.1:3080 | 确认终端中的 dsh 进程仍在运行，并以终端实际返回的地址为准。 |
| 页面能打开，但模型不可用 | 进入“设置 → 模型 → DeepSeek”，重新检查 API Key 与模型配置。 |
| 对话无回复或报认证错误 | 检查 Key 是否复制完整、是否有效，以及账号余额或调用额度；必要时新建临时 Key 后重试。 |
| 无法写入文件 | 确认已选择正确工作区，并将权限设为 Workspace Write。 |
| 自动浏览器验证失败 | 区分“文件已生成”“静态检查通过”和“视觉验收完成”；自动验证失败时，手动打开返回路径检查并如实记录未验证项。 |
九、完成检查清单
- Node.js 与 npm 能在终端正常返回版本；
npx @deepseek-ai/dsh web返回本地地址；- 浏览器能打开 Harness Web UI；
- DeepSeek API Key 已保存且没有泄露；
- 工作区、模型、推理等级与 Workspace Write 权限已确认；
- 发送“你好”后收到真实回复；
- 如执行文件任务，已人工打开返回路径检查结果，并记录未验证项。
DeepSeek Harness社区：dshai.net/
