这份指南带你在一台 Mac 上完成 DeepSeek Harness 的本地启动、模型配置、工作区选择和最小对话验证。完成后，你会得到一个运行在 http://127.0.0.1:3080 的本地 Web UI ，并能让 Harness 在指定工作区内处理文件任务。
一、准备工作
- 一台已安装 Node.js 与 npm 的 Mac ；
- 可访问 DeepSeek API 开放平台的账号；
- 一个 DeepSeek API Key ；
- 一个专门用于教学或项目的本地工作目录。
安全提醒：API Key 相当于调用服务的凭据。完整 Key 通常只在创建时显示一次，请单独保存，不要发给他人，也不要出现在截图、录屏、代码仓库或公开文档中。
官方开源仓库为 ：
https://github.com/deepseek-ai/deepseek-harness
二、创建 DeepSeek API Key
1. 打开 DeepSeek 官方 API 平台并登录。
2. 进入左侧的 API keys 。
3. 点击右上角 创建 API key ，输入便于识别的临时名称。
4. 创建成功后立即复制并妥善保存完整 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 配置提示。
五、配置模型、权限与工作区
1. 在首次弹窗中粘贴 DeepSeek API Key 并保存；也可以稍后进入 设置 → 模型 → DeepSeek 配置。
2. 在通用设置里确认语言与 Agent 预设；需要生成或修改文件时，将权限设为 Workspace Write 。
3. 创建或选择一个独立工作区。建议使用空目录，避免误改其他项目文件。
4. 选择 DeepSeek 模型与推理等级。实录界面提供 Off / High / Max 等选项；入门阶段先选择能稳定响应的配置即可。
权限提示：Workspace Write 会允许 Harness 写入所选目录。不要把家目录、含隐私资料的目录或重要仓库根目录直接作为练习工作区。
六、用最小对话验证部署
1. 新建会话。
2. 确认工作区、模型和推理等级已经选好。
3. 发送：你好
4. 收到真实回复后，再进入文件生成任务。
这一步能证明当前这台 Mac 上的 Harness 、API Key 和模型已经连通；它不证明文件写入、复杂任务、跨平台兼容或长期稳定性。
我们选定模式，点击新会话，输入需求即可开启对话：
使用过程还会帮我们分析需求：
DeepSeek Harness 权限用于控制智能体（ Agent ）访问本机文件、执行命令的范围，安全等级从高到低：Read Only > Workspace Write > Full access 。
- Read Only：仅可读取工作区文件，无法修改文件、执行终端命令，安全性最高。
- Workspace Write：允许读写当前工作目录内文件，可在工作目录执行命令，无法访问工作目录以外文件，日常开发推荐使用。
- Full access： 拥有完整文件系统访问权限，可读写任意路径文件、执行各类终端指令，存在较高安全风险。
七、提交第一个文件任务
1. 在独立工作区中新建会话。
2. 一次性提交完整任务，至少写清：目标、内容事实、页面或文件结构、视觉与交互要求、禁止项和完成标准。
3. 等待 Harness 返回“已完成”和本地文件绝对路径。
4. 把返回路径放进浏览器或对应应用中，人工打开检查。
实录案例最终返回 /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 能在终端正常返回版本；
- npx @deepseek-ai/dsh web 返回本地地址；
- 浏览器能打开 Harness Web UI ；
- DeepSeek API Key 已保存且没有泄露；
- 工作区、模型、推理等级与 Workspace Write 权限已确认；
- 发送“你好”后收到真实回复；
- 如执行文件任务，已人工打开返回路径检查结果，并记录未验证项。
DeepSeek Harness 社区： https://dshai.net/
