从 npx 一键启动到工作区、Goal/Plan、图片输入、PPT Skill、插件管理和安全卸载，一篇跑通 DSH。
DeepSeek Harness（简称 DSH）不是一个单纯的聊天网页，而是一套开源 Agent Harness：它把模型、工具、Skills、会话、沙箱、存储和界面组织成可组合的插件。对新手来说，最直观的理解是——它像一盒“赛博乐高”，你可以先用默认 Web UI 跑起来，再按任务逐步添加能力。
一、DeepSeek Harness 是什么？适合谁用
DSH 的核心价值，是把“模型会思考”与“模型能执行”连接起来。模型负责理解目标和生成计划，Harness 则负责提供文件、终端、搜索、浏览器、子代理、持久会话等运行能力，并通过权限策略决定哪些操作需要确认。
它更适合希望在本地项目中使用 Agent、需要观察工具调用过程、想组合不同模型和插件的开发者与内容创作者。若你只是偶尔问答，普通聊天产品更省事；若你希望 Agent 真正读写工作区、运行命令和维护计划，DSH 的可扩展结构更有吸引力。
二、安装前准备：Node.js、终端与独立工作区
先在终端检查 Node.js 与 npm：
node -v
npm -v若命令没有返回版本号，请先安装 Node.js 的长期支持版。Windows 可使用 PowerShell 或 Windows Terminal，macOS、Linux 使用系统终端即可。随后新建一个专用测试目录，用于第一次运行和权限验证。
官方项目入口已收录到站内导航：DeepSeek Harness 导航页。后续查看项目地址、功能简介和相关教程，建议从这个前端页面进入。
三、最快安装：一条 npx 命令启动 Web UI
零基础用户优先使用官方推荐的 npm 启动方式：
npx @deepseek-ai/dsh web首次运行需要下载依赖，时间取决于网络和磁盘速度。终端出现服务地址后，在浏览器打开 http://127.0.0.1:3080。该地址默认只供本机访问，不应在不了解认证和网络边界时直接暴露到公网。
如果 3080 端口被占用，可尝试：
npx @deepseek-ai/dsh web --port 3081四、源码安装：适合二次开发与插件调试
需要阅读源码、调试插件或跟踪最新代码时，再使用源码方式：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web这条路线要求本机已经安装 Git 和 pnpm。若安装 Git 源码插件时 pnpm 提示构建脚本被阻止，应先阅读终端给出的 allowBuilds 提示、确认依赖来源，再按官方说明允许构建，不要为了省事全局放开未知脚本。
五、第一次使用：配置模型、选择工作区、发送任务
打开 Web UI 后，先进入设置页配置模型与密钥。密钥应保存在 DSH 的配置界面或环境变量中，不要写进提示词、截图、公开仓库或文章。保存后选择工作区；官方说明中，未选择工作区前会话输入区可能保持不可用。
第一个任务建议足够小，例如“阅读这个目录并总结主要文件，不做任何修改”。先验证读取与总结，再逐步允许写文件或执行命令。这样更容易判断模型、工具和权限是否正常。
六、Goal、Plan 与审批：让 Agent 可控地执行
复杂任务先写清目标，再让 Agent 生成计划。Goal 负责定义最终结果，Plan 把工作拆成可检查步骤；当 Agent 准备运行终端、修改文件或调用高风险工具时，界面会依据当前权限策略请求批准。
七、多模态输入：Harness 支持图片，不等于模型一定看得懂
DSH 的输入管线可以承载图片、文件引用、Goal 与 Plan 等上下文，但最终能否理解图片，仍取决于你选择的模型适配器是否支持视觉输入。若模型是纯文本接口，上传图片也不会自动获得视觉能力。
多图任务要控制图片数量与尺寸。超大图片、长历史和大量附件会迅速占用上下文，增加延迟与 Token 消耗。建议先压缩图片、一次处理一个明确问题，必要时开启新会话。
八、Skills 实战：让 DSH 按固定流程生成 PPT
Skill 可以把专业流程、提示词约束、文件规范和工具用法封装起来。以 PPT Master 为例，可让 Agent 阅读其 SKILL.md，再按规范生成演示文稿。安装或使用第三方 Skill 前，应先检查仓库、脚本与权限要求，确认没有危险命令和不必要的数据上传。
不要把陌生仓库地址直接交给拥有高权限的 Agent 自动执行。更稳妥的顺序是：先只读审查 SKILL.md，列出需要的命令、依赖和写入位置；确认后再在专用工作区安装。
九、插件系统：从“能对话”扩展到“能完成工作”
DSH 基于 Cordis 构建“Everything is a Plugin”的架构。模型适配器、工具、Skills、会话、沙箱、存储、Agent Loop、调度和 UI 都可以由插件提供。插件由配置和依赖关系装配，既方便扩展，也意味着插件来源与权限必须认真审核。
官方 CLI 的插件管理形式为：
dsh plugin --profile web add <package>想了解更多已整理扩展，可继续阅读站内的 DeepSeek Harness 插件推荐与实测，以及 DeepSeek Harness 多模态与子代理更新解析。
十、Trace 与 Token：看懂 Agent 到底做了什么
Trace 页面可以追踪助手回复、工具调用、上下文注入与用量信息。遇到结果不符合预期时，不要只看最后一句回答，应沿时间顺序检查：模型收到了什么、调用了哪个工具、参数是什么、工具返回了什么，以及是否因为权限或上下文压缩而丢失信息。
如果你关心上下文成本，可参考站内的 Agent Token 经济学与上下文管理，先从缩短历史、减少重复附件和拆分任务入手。
十一、常见故障排查
| 现象 | 优先检查 |
|---|---|
| node / npm 找不到 | 安装 Node.js LTS，重开终端并检查 PATH |
| 3080 无法打开 | 确认进程仍在运行、终端无报错，或改用其他端口 |
| 无法发送消息 | 先配置模型，再选择工作区 |
| 模型鉴权失败 | 检查 API Key、接口地址、模型名与账户额度 |
| 上传图片但模型不识图 | 确认模型适配器本身支持视觉输入 |
| 源码构建失败 | 核对 Node/pnpm 版本、依赖网络与官方仓库最新说明 |
十二、更新与卸载：先停服务，再决定是否清理数据
npx 快速体验：回到终端按 Ctrl+C 停止进程即可，通常没有单独的全局程序需要卸载。下次运行 npx 会按 npm 机制解析版本。
源码安装：停止服务后，可移除你明确克隆的 deepseek-harness 项目目录。删除前先确认其中没有自己新增的插件、配置或工作成果。
配置与会话：~/.dsh 可能保存配置、凭据、profiles 和会话数据。只有在确定不再需要并完成备份/导出后才考虑删除；不建议把“删掉整个目录”当作普通卸载步骤。
十三、FAQ：零基础最常问的 5 个问题
1. DeepSeek Harness 是免费的吗？
项目采用 MIT 许可证开源；但你连接的模型 API、搜索服务或第三方插件可能产生费用。
2. 一定要安装到本地吗？
官方 Web UI 通过本机 Node.js 进程运行。npx 是最省事的本地体验方式，源码方式更适合开发。
3. 为什么页面打开后不能输入？
通常是尚未配置模型或未选择工作区。先完成这两项，再创建会话。
4. DSH 支持图片吗？
Harness 可以承载图片输入，但模型端也必须具备视觉能力；纯文本模型无法因此自动识图。
5. 能不能让 Agent 自动安装所有插件？
技术上可以自动执行，但不建议对未知仓库开放全权限。应先审查插件来源、脚本、依赖和写入范围，再逐步授权。
下一步：先从 DeepSeek Harness 站内导航入口 启动官方项目，再用一个独立测试目录完成“配置模型—选择工作区—只读总结—批准单次工具调用”的最小闭环。
