DeepSeek Harness 上手指南

前言

最近折腾了一下 DeepSeek Harness（命令名dsh）——一个运行 AI 助手（Agent）的工具。它最常被用来帮你写代码、改文件、跑命令，但能干的不只是编程：装好对应的插件，数据分析、查资料、写文档也都能做。

这篇文章按照「认识它 → 跑起来 → 用好它」的思路，带你从零上手 DeepSeek Harness。先用一条命令建立直觉：

$cdD:\dev\code\my-project $ dsh web# 打开 http://127.0.0.1:3080 开始使用

打开终端 → 进入项目目录 → 输入dsh web→ 在浏览器里指挥助手干活。整篇文章就是围绕这件事展开。

一、认识 DeepSeek Harness：它是什么

1.1 一切皆插件

DeepSeek Harness（命令名dsh）是一个运行 AI 助手（Agent）的工具。它最大的特点是「一切皆插件」（Everything is a Plugin）：模型适配器、文件工具、Shell、沙箱、会话、网页界面……全部是插件，可以随时装上、卸下、替换，也因此模型无关。

可以把它想成一个能改装的整车平台：读文件、写代码、执行命令、搜索、拆分任务这些能力是一个个可以自由拼装的零部件（插件）。模型是引擎，平台不生产引擎，它只负责把任意引擎装进一辆能干活的车——所以官方说「模型 + Harness = Agent」。

平台已经帮你组装好两款现车：

相关链接：

• 官网：www.deepseek.com/harness/
• GitHub 开源仓库：github.com/deepseek-ai/deepseek-harness

1.2 先记几个名词

1.3 它能做什么

三种使用方式：

内置工具：

• 📄文件读写与编辑：读取、创建、覆盖、精确修改文本文件。
• 🔍文件检索：按文件名glob、按内容grep搜整个项目。
• 💻执行命令：Windows 用 PowerShell（pwsh），macOS/Linux 用bash；支持后台跑长任务。
• 🌐网页搜索：联网查最新信息。
• 📚技能（Skills）：按需加载特定领域的说明手册。
• ✅待办（Todo）：自动拆解并跟踪多步骤任务。
• ❓向你提问：拿不准时先问你，而不是瞎猜。

协作与自动化：

• 计划模式：先调研、出方案给你确认，批准后才动手改。
• 目标（Goal）：为长时间目标自动多轮推进，直到完成。
• 子代理（Subagent）：把独立任务分给多个小助手并行处理。
• 工作流（Workflow）：用一个脚本把大量子任务编排、批量分发。
• Ralph 循环：让全新的助手一轮轮迭代，用共享目录做长期记忆。

上下文与安全：

• 自动压缩上下文：对话太长时自动瘦身，避免越聊越卡、越贵。
• Token 计量：实时看到上下文用量。
• 会话持久化：对话保存在~/.dsh/sessions，可恢复。
• 文件沙箱与审批：读写被限制在允许范围内，危险操作先征求你同意。

二、安装：两分钟跑起来

2.1 环境要求

• Windows / macOS / Linux 都行。
• Node.js：建议 20 及以上版本（推荐最新 LTS），自带npm和npx。下载：nodejs.org

验证环境：

node-vnpm-v

能打印出版本号，就说明环境装好了。

2.2 Windows 上执行 npm -v 报错怎么办

问题现象：在 Windows 的 PowerShell 里输入npm -v，报出执行策略相关的错误。

报错原因：Windows PowerShell 默认的安全策略是「禁止运行任何脚本」。当你输入npm -v时，PowerShell 会尝试去执行一个名为npm.ps1的脚本文件，被系统的安全机制阻止了，于是报错。

解决方法（推荐）：

1. 以管理员身份运行 PowerShell：在 Windows 搜索框搜「PowerShell」，右键「Windows PowerShell」→「以管理员身份运行」。

2. 执行更改策略的命令：在打开的管理员 PowerShell 窗口里输入下面命令并回车：

   Set-ExecutionPolicyRemoteSigned

3. 确认更改：系统询问是否更改执行策略，输入Y或A回车确认。

4. 重新测试：关闭当前 PowerShell 窗口，重新打开一个普通的 PowerShell 窗口，再输入npm -v，就能正常输出版本号了。

2.3 npm 和 npx 的区别

一句话：npm 负责「装」，npx 负责「跑」。

npm —— 包管理器（负责安装）：npm（Node Package Manager）是 Node.js 自带的包管理器，负责下载、安装、更新、卸载软件包，相当于手机上的应用商店：

npm install <包名># 安装npm update <包名># 升级npm uninstall <包名># 卸载

安装位置分两种：npm install -g 包名装到全局（任何终端都能直接用）；不带-g只装进当前项目。

npx —— 执行器（负责运行）：npx 随 npm 一起装好，作用是直接运行某个包里的命令。如果这个包没装过，它会临时下载一个副本到缓存，跑完就走，不装进你的系统。可以把它想成临时工：需要时叫来，干完就走。

两者怎么配合：

npm install-g dsh# 正式装进系统 → 以后任何终端直接敲 dshnpx dsh web# 临时拉副本跑 → 跑完就丢，系统里没装

这正是后面 3.8「命令会消失」的原因：npx方式没有正式安装，关掉终端后命令自然就找不到了。长期使用请用npm install -g。

2.4 方式一：临时运行

不装任何东西，用npx直接跑：

npx @deepseek-ai/dsh web

2.5 方式二：全局安装（推荐）

npm install-g @deepseek-ai/dsh

装完验证：

dsh--version dsh--help

⚠️为什么推荐全局安装：方式一的dsh命令只在那一次npx调用里临时存在，关掉终端就没了（见 3.8）。全局安装后，任何终端都能直接敲dsh。

2.6 升级与卸载

# 升级npm update-g @deepseek-ai/dsh# 卸载npm uninstall-g @deepseek-ai/dsh

三、第一次使用：从启动到上手

3.1 dsh web 方式启动

1️⃣ 打开终端（Windows 用 PowerShell 或 Windows Terminal）。

2️⃣ 进入你的项目目录——这个目录会成为助手的工作区：

cd D:\dev\code\my-project

⚠️注意：目录就是工作区。助手能方便读写的只有你启动dsh时所在的目录。先cd到正确项目再启动，否则它会「看不到」你的项目。

3️⃣ 启动网页界面：

dsh web

启动后终端会打印访问地址，默认是http://127.0.0.1:3080。

4️⃣ 用浏览器打开那个地址。第一次会引导你登录 DeepSeek 账号或配置模型（还没有账号？先去 platform.deepseek.com 注册并获取 API Key）。

⚠️注意：凭证别外传。登录信息保存在~/.dsh/.credentials.yaml。不要把这个文件发给别人，也别提交到 git 仓库。

💡首次启动会自动初始化：web和headless两个 profile 第一次用会自动生成配置，无需手动创建；其他自定义 profile 要用dsh plugin创建。用户数据（会话、配置、凭证）都放在~/.dsh。

💡Windows 用户注意：Windows 上助手默认用 PowerShell（pwsh）执行命令，不是 bash；受限沙箱下部分命令以只读模式运行，需要更宽权限时会先向你请求批准。

3.2 dsh web 工作区介绍

浏览器打开http://127.0.0.1:3080后，看到的就是助手的工作界面：

3.3 预设：4 种模式怎么选

预设就是给助手选的「装备包」，决定它有哪些工具、能干什么活。

新手直接留在标准模式即可，其余三种等有具体需求时再切。

PTC 模式详解与示例

PTC 模式的原理：和标准模式是同一套工具，区别只在呈现方式——标准模式一次调用一个工具，PTC 模式下模型写一段 TypeScript 程序，用run_code一次性执行多步操作。工具、沙箱、审批都和标准模式完全一样。

适合做什么：

• 步骤固定的流水线任务：读文件 → 统计 → 生成报告；批量改文件 → 跑测试 → 汇总。
• 批量操作：对一批文件做同一套处理，并发安全的读取默认可并行（上限 10 个）。
• 省上下文的场景：程序只把日志和返回值传回对话，中间过程不来回灌。

不适合做什么：

• 探索式任务：排查 bug、理解陌生代码、写新功能——这些需要边看结果边决定下一步。
• 需要反复和你确认的交互场景。

程序员的建议：默认用标准模式：编程是探索加迭代的过程，逐步调用更可控，且标准模式能力最全。遇到「批量改文件」「跑一遍完整重构流程」这类确定性任务时，再临时切到 PTC。

示例：批量给 src/ 下的 .ts 文件补文件头注释，并跑类型检查

// 找文件 → 判断 → 补头 → 验证，一次跑完constheader=`/** * Copyright © 2025 Example Inc. */`;constfiles=awaittools.glob({pattern:"src/**/*.ts"});constchanged=[];constskipped=[];for(constfoffiles){constr=awaittools.read({file_path:f});consttext=r.lines.map(l=>l.text).join("\n");if(text.startsWith("/**")){skipped.push(f);continue;}awaittools.write({file_path:f,content:header+text});changed.push(f);}constcheck=awaittools.pwsh({command:"npx tsc --noEmit"});if(check.exitCode!==0)thrownewError("tsc 报错："+check.stderr);console.log(`修改${changed.length}个，跳过${skipped.length}个，类型检查通过`);return{changed,skipped};

这个例子适合 PTC 的原因：步骤在动手前就能列完、是批量操作、中途不需要你介入、有明确的终点验证（tsc 通过）。同样的活，标准模式要一步步来回——glob→ 逐个read→ 逐个write→ 跑检查，20 个文件就是 20 多次往返；PTC 一次run_code跑完，且中间结果不会灌进上下文。

（示例中的工具名和返回字段以会话里实际生成的 SDK 为准，这里是按真实工具的形状写的示意。）

3.4 权限：3 种模式守住底线

Harness 用一个文件沙箱约束助手能碰哪些文件：

切换方式：当前会话在输入框敲/permission选一个；改以后新会话的默认值，走「设置 → 通用 → 权限」，只对之后新建的会话生效。

三种模式是一条升级阶梯：read-only→workspace-write→danger-full-access。助手在较严模式下被拦下时，会请求升级到更宽模式，并弹审批让你拍板（这就是「ask」的含义）。选「完全访问」时系统会先要你确认风险。

⚠️安全建议：日常保持workspace-write，除非确有必要，不要长期开danger-full-access。重要项目先备份或提交 git 再让助手动手。

3.5 7 个斜杠命令

在 dsh web 的输入框里敲/会弹出命令菜单（输入框左侧的+按钮也可以打开）。斜杠命令由界面直接执行，不会进入模型的历史、不消耗 token。默认一共 7 个：

命令支持模糊匹配（比如敲/pe也能找到/permission）。敲一个不认识的命令会被直接拒绝，而不会当成普通消息发给模型。

💡和前面讲的内容怎么对上：/plan就是 5.2「大改动先走计划模式」说的方式；/permission对应 3.4 的权限模式切换；/compact是「自动压缩上下文」的手动版；/goal对应「目标（Goal）」。

3.6 命令行一次性任务

不想开网页、问一题就走，用 headless 模式：

dsh--profile headless"帮我生成100个1~1000之间的随机数，写到data.txt文件中，每行一个数字"

3.7 常用命令速查

⚠️注意参数顺序：启动器的参数放最前，web应用自己的参数放后面：dsh web --port 8080（--port属于 web 应用）。想看 web 应用自己的帮助，用dsh web --help。

3.8 关闭后怎么再次打开

如果你第一次是用npx @deepseek-ai/dsh web启动的，那个dsh只是npx临时加到当前终端的命令。终端一关，新终端里再敲dsh就会报：

dsh: The term 'dsh' is not recognized ...

这不是装坏了，而是压根没全局安装。重新打开分三步：

# 1. 打开一个新终端，进入你的项目目录cd D:\dev\code\my-project# 2. 启动（二选一）npx @deepseek-ai/dsh web# 没全局安装，用这个dsh web# 已全局安装，用这个# 3. 浏览器打开 http://127.0.0.1:3080

执行一次npm install -g @deepseek-ai/dsh，以后每次重启就只剩「进目录 +dsh web」两步。

⚠️注意：终端要一直开着。dsh web在前台运行，关掉这个终端，网页服务就停了。想继续用就再跑一次上面的命令。要让它长期在后台跑，需要额外的手段（后台任务、tmux、系统服务等），属于进阶内容。

3.9 实践一下：用 SDD 开发扫雷游戏

SDD（Specification-Driven Development，规范驱动开发）：先让助手产出规范文档，再按依赖关系拆解任务、一步步执行。先cd到一个空项目目录再启动dsh web，然后把下面这段提示词粘贴到对话框里即可：

我想实现一个网页版本的扫雷游戏，我希望使用SDD的方式来开发。 先帮我梳理规范文档， 然后按照规范文档，按照依赖关系，拆解任务，一步步的执行。 有什么不确定的地方，使用question工具向我提问确认。

四、设置与默认插件

4.1 入口与保存位置

点网页界面侧边栏的「设置（Settings）」。改动保存在~/.dsh/settings.yaml（Windows 是C:\Users\你的用户名\.dsh\settings.yaml），保存后即时生效，多数设置不用重启。也可以在设置里点「打开配置文件」直接用编辑器改。

4.2 三大分区

• 通用：外观主题（浅色 / 深色 / 跟随系统）、语言、权限默认值（见 3.4）、默认预设、打开配置文件。
• 模型：配置 DeepSeek 官方 API Key（或 Bedrock / Vertex / 自定义 OpenAI 兼容端点）、改 baseURL、选默认模型和推理档位。API Key 只写保存，不会明文写进 settings.yaml。
• 插件：两个标签页——「插件配置」（可配置插件做成可展开卡片）和「插件列表」（只读，看当前加载了哪些插件）。

4.3 默认插件速览

一个 profile 由两层插件包叠加：base（每个 profile 都有的核心）加web-app（网页界面）。挑几类有代表性的：

这些都是开箱即用的默认插件，不用手动装。只有想加额外能力时才需要dsh plugin。

4.4 参考文档在哪

• 每个插件自带中英双语说明：node_modules/@deepseek-ai/<插件名>/README.md（英文）和README.zh.md（中文）。想知道某个插件干什么，直接翻它的 README.zh.md。
• CLI 总说明：node_modules/@deepseek-ai/dsh/README.zh.md。
• 看实际加载了哪些插件：dsh --profile web --dump-config（含你的覆盖）或--dump-default-config（只看默认）。
• 完整源码与文档：github.com/deepseek-ai/deepseek-harness，含每个包的 README、组合图、CLI 行为参考。
• 命令行帮助：dsh --help、dsh web --help。

4.5 插件市场

默认插件不够用时，去下面两个地方找第三方插件：

• 官方插件市场：github.com/topics/dsh-plugin——GitHub 上带dsh-plugin话题标签的插件仓库集合。
• 插件分类汇总：awesome-dsh-plugin——按分类整理好的插件清单（含中文说明）。

找到想用的插件后，用dsh plugin --profile web install <包名>装到 web profile，就能在会话里使用，或在设置里配置。

五、用得更顺的几个习惯

同一个助手，给任务的写法不同，结果差很多。下面几条都是能直接照做的习惯。

5.1 把需求说清楚

给任务时带上「目标 + 背景 + 想要的产出」。越具体，结果越靠谱。

5.2 大改动先走计划模式

要动多处代码、或方案拿不准时，先让它调研并给出计划，你确认后再执行。直接说「先用计划模式」，或敲/plan。

5.3 在正确的目录里启动

助手方便看到的只有启动时所在的目录。开工前先cd到项目根目录，让助手能读到整个项目，而不是你一句一句贴代码给它。

5.4 让它自己查，而不是凭记忆猜

它有检索文件、跑命令、上网搜索的能力。遇到「这个函数在哪定义」「这个报错怎么回事」，可以补一句「先到项目里搜一下再回答」。查证后的答案比凭空猜可靠。

5.5 复杂任务拆小步

别一口气塞十个需求。一次给一个明确的小目标，先跑通最小版本再往上加。大目标可以用「目标（Goal）」让它自动多轮推进，或让它自己用「待办（Todo）」跟踪进度。

5.6 做错了就纠正

助手会犯错。错了直接说「不对，我要的是……」，它会按你的反馈调整；它拿不准时也会主动问你。

5.7 一个话题一个会话

不同的事分开建会话，避免上下文互相干扰；同一个长任务中断了，下次继续之前的会话，而不是从头讲一遍。

5.8 用子代理和工作流并行提速

几件互不相干的事（比如给五个文件分别写注释），可以让它派几个子助手并行处理，比排队快。更复杂的批量任务用「工作流」一次编排。

5.9 守住安全和成本

• 先在副本或测试目录里试，确认没问题再上真项目。
• 让它改重要文件前，先备份或提交 git。
• 长时间大批量任务会消耗额度，留意界面里的 Token 用量。

💡一句话：把它当成一个会干活、也会犯错的助手，而不是许愿机：说清楚目标、给足上下文、让它查证、分步验收。你越会带人，它越能替你干活。

六、常见问题 FAQ

Q1：报错「dsh 不是内部或外部命令」
没全局安装。改用npx @deepseek-ai/dsh web，或先npm install -g @deepseek-ai/dsh。

Q2：端口 3080 被占用 / 打不开
换端口：dsh web --port 8080，然后访问http://127.0.0.1:8080。同时确认终端没报错、服务还在前台跑。

Q3：浏览器打不开页面
查三点：终端里的dsh web是否还在运行且没报错；访问的是不是终端打印的地址；是否被防火墙拦（本机地址一般不会）。

Q4：怎么换模型
登录后在网页界面的设置里选模型；偏好保存在~/.dsh/settings.yaml的agent-default-model。

Q5：之前的对话还能找回吗
能。会话持久化保存，重启后在网页界面里继续之前的会话即可。

Q6：怎么让助手先出方案、确认后再动手
告诉它「先用计划模式」，或在界面里切换计划模式。它会先调研并给出方案，你批准后才执行。

✒️总结

DeepSeek Harness 的上手路径其实就三步：

1. 认识它：一切皆插件的 Agent 运行平台，「模型 + Harness = Agent」；
2. 跑起来：npm install -g @deepseek-ai/dsh→cd到项目目录 →dsh web，新手保持标准模式 +workspace-write权限即可；
3. 用好它：把需求说清楚、大改动先走计划模式、复杂任务拆小步、守住安全和成本——把它当成一个会干活、也会犯错的助手，而不是许愿机。你越会带人，它越能替你干活。

如果这篇【文章】有帮助到你💖，希望可以给我点个赞👍，创作不易，如果有对前端端或者对python感兴趣的朋友,请多多关注💖💖💖，咱们一起探讨和努力！！！
👨‍🔧 个人主页 : 前端初见