DeepSeek Harness 上手指南

认识它 → 跑起来 → 用好它

PS B:\node\ds_harness>
PS dsh web
# 打开 http://127.0.0.1:3080 开始使用

1 认识 DeepSeek Harness

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

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

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

DeepSeek Harness 平台已经帮你组装好两款现车：dsh web（网页界面，新手首选）和 dsh --profile headless（命令行一次性任务）；想有自己的车，也可以用 dsh plugin 按零部件清单自己拼一辆。

1.1DeepSeek Harness・平台 + 零部件体系

• 一切皆插件：模型适配器・文件工具・Shell・沙箱・会话・网页界面 …… 自由装卸、可替换，模型无关
• 按 profile 的 bundles 组装：
  • dsh web：出厂现车 A：网页界面（base + web-app）
  • dsh --profile headless：命令行一次性任务（base + headless）
  • 自定义 profile：自己改装，用 dsh plugin 拼装你的车

1.2相关链接

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

1.3核心名词表

名词	解释
dsh	启动命令，所有操作都从它开始。
Profile	一套预先配好的助手。自带 web（网页版）和 headless（命令行一次性任务）两种。
插件包（bundle）	一组能力的集合，例如「文件工具」「子代理」。Profile 就是若干插件包按顺序叠加的结果。
工作区（workspace）	助手默认读写文件的目录，也就是你启动 dsh 时所在的文件夹。
会话（session）	你和助手的一次对话，会自动保存，之后能接着聊。
预设（preset）	决定助手「用哪些工具、是什么性格」。有标准、PTC、极简、创造四种。

1.4快速建立直觉

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

2 它能做什么

2.1 三种使用方式

使用方式	特点	命令
网页界面	最直观，有界面有按钮，适合大多数人，新手首选	dsh web
命令行一次性任务	跑一次、输出结果、退出，适合脚本化和批量场景	dsh --profile headless "任务"
自定义 Profile	自己组装能力，适合进阶用户	dsh --profile 名称

2.2 四种预设

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

• 标准模式（默认・推荐）：「瑞士军刀」全能助手，工具最全，绝大多数人、尤其新手的默认选择。
• PTC 模式：会「写脚本」的程序员管家，把「读→改→测」等多步操作写成一个程序一次跑完。
• 极简模式：只带两件工具的轻装助手：持久 Shell + 文本替换编辑器，最省资源。
• 创造模式：自己造专属助手的工作台，标准能力 + 运行时检查、插件实验、创作指导。

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

2.3 内置工具

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

2.4 协作与自动化

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

2.5 上下文与安全

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

3 安装

3.1 环境要求

• 系统：Windows /macOS/ Linux 均可
• Node.js：建议 20 及以上版本（推荐最新 LTS），自带 npm 和 npx
  • 下载地址：nodejs.org

验证环境：

node -v
npm -v

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

3.2 方式一：临时运行

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

npx @deepseek-ai/dsh web

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

npm install -g @deepseek-ai/dsh

装完验证：

dsh --version
dsh --help

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

3.4 升级与卸载

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

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

4 第一次使用

4.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；受限沙箱下部分命令以只读模式运行，需要更宽权限时会先向你请求批准。

4.2 dsh-web 方式工作区介绍

浏览器打开 http://127.0.0.1:3080 后，即可进入助手工作界面，界面包含：

• 新会话入口、工作区切换
• 对话输入区，支持预设模式切换、权限切换、模型切换
• 侧边栏设置、会话管理等功能入口
  

4.3 预设 4 种模式

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

模式	一句话理解	核心工具	适合人群	新手建议
标准模式（默认・推荐）	「瑞士军刀」全能助手	文件读写、Shell、检索、网页搜索、Skills、计划、目标、子代理、工作流……	绝大多数人，尤其新手	默认就用它，不用纠结
PTC 模式	会「写脚本」的程序员管家	标准模式全部工具，还能用 TypeScript 把「读→改→测」等多步写成一个程序一次跑完	步骤多、逻辑固定的连环任务	熟练后遇到连环任务再试
极简模式	只带两件工具的轻装助手	只有两个：持久 Shell + 文本替换编辑器	只做简单编辑、想要最省资源	想要极简时可切换
创造模式	自己造专属助手的工作台	标准能力 + 运行时检查、插件实验、创作指导	想定制新预设的进阶用户	先不用碰，等熟悉了再说

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

4.4 3 种权限模式

Harness 用一个文件沙箱约束助手能碰哪些文件，共有三种权限模式：

权限模式	标识	能做什么	越界 / 审批规则	适用场景
只读	read-only	只能读文件、跑只读命令，改不了任何文件（包括工作区内的）	一旦要写会被拒绝，需批准才升级	只想让它读代码、调研，还不放心它动文件时
工作区可写（默认）	workspace-write	可读写工作区目录里的文件，以及平台允许的临时目录	想写工作区以外，会先弹审批问你	日常使用
完全访问	danger-full-access	文件系统不受限，哪里都能改	不再弹审批	完全信任、或确需全局改动时（谨慎）

• 切换方式：当前会话在输入框敲 /permission 选一个；修改以后新会话的默认值，走「设置 → 通用 → 权限」，只对之后新建的会话生效。
• 三种模式是一条升级阶梯：read-only → workspace-write → danger-full-access。助手在较严模式下被拦下时，会请求升级到更宽模式，并弹审批让你拍板。选「完全访问」时系统会先要你确认风险。

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

4.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）。敲一个不认识的命令会被直接拒绝，而不会当成普通消息发给模型。

4.6 命令行一次性任务

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

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

4.7 常用命令速查

命令	作用
dsh web	启动网页界面（等于 dsh --profile web）
dsh web --port 8080	改用 8080 端口
dsh web --help	查看网页应用自己的参数
dsh --profile headless " 任务 "	跑一次任务并输出结果后退出
dsh --help	查看启动器帮助

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

4.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、系统服务等），属于进阶内容。

4.9 使用 dsh web 实践一下

SDD（Specification-Driven Development，规范驱动开发）：先让助手产出规范文档，再按依赖关系拆解任务、一步步执行。

先 cd 到一个空项目目录再启动 dsh web，然后把下面这段提示词粘贴到对话框里即可：

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

5 设置与默认插件

5.1 入口与保存位置

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

5.2 三大分区

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

5.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-pruner	Token 计量、自动压缩、裁剪过长的工具结果。
网页界面	dsh-host-webserver + 一系列 ui-*	Web 服务器（默认 127.0.0.1:3080）、侧边栏、会话、设置、作业、目标、计划等界面。

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

5.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。

5.5 插件市场

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

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

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

6 用得更顺的几个习惯

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

6.1 把需求说清楚

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

不够清楚	更清楚
“帮我看看这个代码”	“找出 app.js 登录功能的 bug，说明原因并修掉，然后跑测试确认”
“优化一下”	“把首页加载速度优化到 2 秒以内，列出改了哪些地方”
“写个爬虫”	“用 Python 写一个爬某网站标题的脚本，存成 CSV，并告诉我怎么运行”

6.2 大改动先走计划模式

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

6.3 在正确的目录里启动

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

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

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

6.5 复杂任务拆小步

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

6.6 做错了就纠正

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

6.7 一个话题一个会话

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

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

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

6.9 守住安全和成本

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

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

7 常见问题

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

本次介绍到这里就结束了，感兴趣的朋友可以点个关注~后续还会继续分享别的Agent使用教程，咱们下一章再会！！！