文章目录前言一、认识 DeepSeek Harness它是什么1.1 一切皆插件1.2 先记几个名词1.3 它能做什么二、安装两分钟跑起来2.1 环境要求2.2 Windows 上执行 npm -v 报错怎么办2.3 npm 和 npx 的区别2.4 方式一临时运行2.5 方式二全局安装推荐2.6 升级与卸载三、第一次使用从启动到上手3.1 dsh web 方式启动3.2 dsh web 工作区介绍3.3 预设4 种模式怎么选PTC 模式详解与示例3.4 权限3 种模式守住底线3.5 7 个斜杠命令3.6 命令行一次性任务3.7 常用命令速查3.8 关闭后怎么再次打开3.9 实践一下用 SDD 开发扫雷游戏四、设置与默认插件4.1 入口与保存位置4.2 三大分区4.3 默认插件速览4.4 参考文档在哪4.5 插件市场五、用得更顺的几个习惯5.1 把需求说清楚5.2 大改动先走计划模式5.3 在正确的目录里启动5.4 让它自己查而不是凭记忆猜5.5 复杂任务拆小步5.6 做错了就纠正5.7 一个话题一个会话5.8 用子代理和工作流并行提速5.9 守住安全和成本六、常见问题 FAQ✒️总结前言最近折腾了一下 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」。平台已经帮你组装好两款现车现车命令说明出厂现车 Adsh web网页界面base web-app新手首选出厂现车 Bdsh --profile headless命令行一次性任务base headless自定义 profiledsh plugin自己改装按零部件清单自己拼一辆相关链接官网www.deepseek.com/harness/GitHub 开源仓库github.com/deepseek-ai/deepseek-harness1.2 先记几个名词名词解释dsh启动命令所有操作都从它开始。Profile一套预先配好的助手。自带web网页版和headless命令行一次性任务两种。插件包bundle一组能力的集合例如「文件工具」「子代理」。Profile 就是若干插件包按顺序叠加的结果。工作区workspace助手默认读写文件的目录也就是你启动dsh时所在的文件夹。会话session你和助手的一次对话会自动保存之后能接着聊。预设preset决定助手「用哪些工具、是什么性格」。有标准、PTC、极简、创造四种。1.3 它能做什么三种使用方式方式命令说明网页界面最直观dsh web有界面有按钮适合大多数人新手首选。命令行一次性任务dsh --profile headless 任务跑一次、输出结果、退出适合脚本化和批量场景。自定义 Profiledsh --profile 名称自己组装能力适合进阶用户。内置工具文件读写与编辑读取、创建、覆盖、精确修改文本文件。文件检索按文件名glob、按内容grep搜整个项目。执行命令Windows 用 PowerShellpwshmacOS/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的脚本文件被系统的安全机制阻止了于是报错。解决方法推荐以管理员身份运行 PowerShell在 Windows 搜索框搜「PowerShell」右键「Windows PowerShell」→「以管理员身份运行」。执行更改策略的命令在打开的管理员 PowerShell 窗口里输入下面命令并回车Set-ExecutionPolicyRemoteSigned确认更改系统询问是否更改执行策略输入Y或A回车确认。重新测试关闭当前 PowerShell 窗口重新打开一个普通的 PowerShell 窗口再输入npm -v就能正常输出版本号了。2.3 npm 和 npx 的区别一句话npm 负责「装」npx 负责「跑」。npm —— 包管理器负责安装npmNode 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 web2.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 上助手默认用 PowerShellpwsh执行命令不是 bash受限沙箱下部分命令以只读模式运行需要更宽权限时会先向你请求批准。3.2 dsh web 工作区介绍浏览器打开http://127.0.0.1:3080后看到的就是助手的工作界面3.3 预设4 种模式怎么选预设就是给助手选的「装备包」决定它有哪些工具、能干什么活。标准模式默认 · 推荐PTC 模式极简模式创造模式一句话理解「瑞士军刀」全能助手会「写脚本」的程序员管家只带两件工具的轻装助手自己造专属助手的工作台工具文件读写、Shell、检索、网页搜索、Skills、计划、目标、子代理、工作流……标准模式全部工具还能用 TypeScript 把「读→改→测」等多步写成一个程序一次跑完只有两个持久 Shell 文本替换编辑器标准能力 运行时检查、插件实验、创作指导适合谁绝大多数人尤其新手步骤多、逻辑固定的连环任务只做简单编辑、想要最省资源想定制新预设的进阶用户新手怎么选默认就用它不用纠结熟练后遇到连环任务再试想要极简时可切换先不用碰等熟悉了再说新手直接留在标准模式即可其余三种等有具体需求时再切。PTC 模式详解与示例PTC 模式的原理和标准模式是同一套工具区别只在呈现方式——标准模式一次调用一个工具PTC 模式下模型写一段 TypeScript 程序用run_code一次性执行多步操作。工具、沙箱、审批都和标准模式完全一样。适合做什么步骤固定的流水线任务读文件 → 统计 → 生成报告批量改文件 → 跑测试 → 汇总。批量操作对一批文件做同一套处理并发安全的读取默认可并行上限 10 个。省上下文的场景程序只把日志和返回值传回对话中间过程不来回灌。不适合做什么探索式任务排查 bug、理解陌生代码、写新功能——这些需要边看结果边决定下一步。需要反复和你确认的交互场景。程序员的建议默认用标准模式编程是探索加迭代的过程逐步调用更可控且标准模式能力最全。遇到「批量改文件」「跑一遍完整重构流程」这类确定性任务时再临时切到 PTC。示例批量给 src/ 下的 .ts 文件补文件头注释并跑类型检查// 找文件 → 判断 → 补头 → 验证一次跑完constheader/** * Copyright © 2025 Example Inc. */;constfilesawaittools.glob({pattern:src/**/*.ts});constchanged[];constskipped[];for(constfoffiles){constrawaittools.read({file_path:f});consttextr.lines.map(ll.text).join(\n);if(text.startsWith(/**)){skipped.push(f);continue;}awaittools.write({file_path:f,content:headertext});changed.push(f);}constcheckawaittools.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 用一个文件沙箱约束助手能碰哪些文件只读read-only工作区可写workspace-write默认完全访问danger-full-access能做什么只能读文件、跑只读命令改不了任何文件包括工作区内的。可读写工作区目录里的文件以及平台允许的临时目录。文件系统不受限哪里都能改。越界 / 审批一旦要写会被拒绝需批准才升级。想写工作区以外会先弹审批问你。不再弹审批。什么时候用只想让它读代码、调研还不放心它动文件时。日常使用。完全信任、或确需全局改动时谨慎。切换方式当前会话在输入框敲/permission选一个改以后新会话的默认值走「设置 → 通用 → 权限」只对之后新建的会话生效。三种模式是一条升级阶梯read-only→workspace-write→danger-full-access。助手在较严模式下被拦下时会请求升级到更宽模式并弹审批让你拍板这就是「ask」的含义。选「完全访问」时系统会先要你确认风险。⚠️安全建议日常保持workspace-write除非确有必要不要长期开danger-full-access。重要项目先备份或提交 git 再让助手动手。3.5 7 个斜杠命令在 dsh web 的输入框里敲/会弹出命令菜单输入框左侧的按钮也可以打开。斜杠命令由界面直接执行不会进入模型的历史、不消耗 token。默认一共 7 个命令作用/plan [消息]进入计划模式先调研出方案、你确认后再动手/plan off退出/permission [预设]查看/切换当前会话的权限模式read-only/workspace-write/danger-full-access不带参数会弹出选择框/model切换模型按提供方分组选择并应用所选模型的默认推理档位/compact手动压缩上下文把较早的对话摘要化省 token/goal [目标]目标管理创建 / 查看 / 编辑 / 暂停 / 恢复 / 清除长期目标如/goal pause、/goal clear/feedback [文本]提交使用反馈会带上匿名用户 ID 一起记录/export导出当前会话日志下载 ZIP含子会话命令支持模糊匹配比如敲/pe也能找到/permission。敲一个不认识的命令会被直接拒绝而不会当成普通消息发给模型。和前面讲的内容怎么对上/plan就是 5.2「大改动先走计划模式」说的方式/permission对应 3.4 的权限模式切换/compact是「自动压缩上下文」的手动版/goal对应「目标Goal」。3.6 命令行一次性任务不想开网页、问一题就走用 headless 模式dsh--profile headless帮我生成100个1~1000之间的随机数写到data.txt文件中每行一个数字3.7 常用命令速查命令作用dsh web启动网页界面等于dsh --profile webdsh web --port 8080改用 8080 端口dsh web --help查看网页应用自己的参数dsh --profile headless 任务跑一次任务并输出结果后退出dsh --help查看启动器帮助⚠️注意参数顺序启动器的参数放最前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 开发扫雷游戏SDDSpecification-Driven Development规范驱动开发先让助手产出规范文档再按依赖关系拆解任务、一步步执行。先cd到一个空项目目录再启动dsh web然后把下面这段提示词粘贴到对话框里即可我想实现一个网页版本的扫雷游戏我希望使用SDD的方式来开发。 先帮我梳理规范文档 然后按照规范文档按照依赖关系拆解任务一步步的执行。 有什么不确定的地方使用question工具向我提问确认。四、设置与默认插件4.1 入口与保存位置点网页界面侧边栏的「设置Settings」。改动保存在~/.dsh/settings.yamlWindows 是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-llm·dsh-llm-deepseek·dsh-agent模型路由、DeepSeek 适配器、代理循环会话dsh-session·dsh-session-persistence-jsonl对话状态与持久化历史存~/.dsh/sessions文件与命令dsh-tool-fs·dsh-tool-fs-search·dsh-pwsh-sandbox/dsh-bash-sandbox文件读写/检索以及被沙箱包起来的 Shell安全dsh-sandbox·dsh-user-approval·dsh-permission-presets文件沙箱、审批弹窗、权限预设协作自动化dsh-goal·dsh-plan-mode·dsh-subagent·dsh-tool-workflow·dsh-tool-ralph目标、计划模式、子代理、工作流、Ralph检索与技能dsh-tool-web·dsh-web-search-deepseek·dsh-skill·dsh-tool-todo网页搜索、技能系统、待办清单上下文管理dsh-token-meter·dsh-compaction-basic·dsh-compaction-tool-result-prunerToken 计量、自动压缩、裁剪过长的工具结果网页界面dsh-host-webserver 一系列ui-*Web 服务器默认127.0.0.1:3080、侧边栏、会话、设置、作业、目标、计划等界面这些都是开箱即用的默认插件不用手动装。只有想加额外能力时才需要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 把需求说清楚给任务时带上「目标 背景 想要的产出」。越具体结果越靠谱。不够清楚更清楚“帮我看看这个代码”“找出app.js登录功能的 bug说明原因并修掉然后跑测试确认”“优化一下”“把首页加载速度优化到 2 秒以内列出改了哪些地方”“写个爬虫”“用 Python 写一个爬某网站标题的脚本存成 CSV并告诉我怎么运行”5.2 大改动先走计划模式要动多处代码、或方案拿不准时先让它调研并给出计划你确认后再执行。直接说「先用计划模式」或敲/plan。5.3 在正确的目录里启动助手方便看到的只有启动时所在的目录。开工前先cd到项目根目录让助手能读到整个项目而不是你一句一句贴代码给它。5.4 让它自己查而不是凭记忆猜它有检索文件、跑命令、上网搜索的能力。遇到「这个函数在哪定义」「这个报错怎么回事」可以补一句「先到项目里搜一下再回答」。查证后的答案比凭空猜可靠。5.5 复杂任务拆小步别一口气塞十个需求。一次给一个明确的小目标先跑通最小版本再往上加。大目标可以用「目标Goal」让它自动多轮推进或让它自己用「待办Todo」跟踪进度。5.6 做错了就纠正助手会犯错。错了直接说「不对我要的是……」它会按你的反馈调整它拿不准时也会主动问你。5.7 一个话题一个会话不同的事分开建会话避免上下文互相干扰同一个长任务中断了下次继续之前的会话而不是从头讲一遍。5.8 用子代理和工作流并行提速几件互不相干的事比如给五个文件分别写注释可以让它派几个子助手并行处理比排队快。更复杂的批量任务用「工作流」一次编排。5.9 守住安全和成本先在副本或测试目录里试确认没问题再上真项目。让它改重要文件前先备份或提交 git。长时间大批量任务会消耗额度留意界面里的 Token 用量。一句话把它当成一个会干活、也会犯错的助手而不是许愿机说清楚目标、给足上下文、让它查证、分步验收。你越会带人它越能替你干活。六、常见问题 FAQQ1报错「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 的上手路径其实就三步认识它一切皆插件的 Agent 运行平台「模型 Harness Agent」跑起来npm install -g deepseek-ai/dsh→cd到项目目录 →dsh web新手保持标准模式 workspace-write权限即可用好它把需求说清楚、大改动先走计划模式、复杂任务拆小步、守住安全和成本——把它当成一个会干活、也会犯错的助手而不是许愿机。你越会带人它越能替你干活。如果这篇【文章】有帮助到你希望可以给我点个赞创作不易如果有对前端端或者对python感兴趣的朋友,请多多关注咱们一起探讨和努力‍ 个人主页 : 前端初见