DeepSeek 昨晚刚开源了 Harness：附万少的2 万字保姆级教程

DeepSeek 昨晚刚开源了 Harness：附万少的2 万字保姆级教程

就在昨天（8 月 13 日），DeepSeek 正式发布首款 Agent 产品 DeepSeek Harness（dsh），并以 MIT 协议全面开源，直接对标 Claude Code 和 Codex。

消息一出，开发者圈就炸了。内测期间 769 位开发者报名、约 300 个社区插件已冒出来，有人甚至喊出 向 Claude Code 说再见。

这篇文章把完整入门教程合并成 2 万字，打开 dsh web 就能对照操作。收藏这篇，等于随身带了一本 dsh 手册。

---

Part 0 · 准备

第一站：搞清楚 dsh 是什么、装好运行环境、启动 Web UI 并看懂界面布局。

0.1 先认识 dsh：它是什么、能干什么

你将学会 搞清楚 dsh 是什么、能做什么、和你用过的 ChatGPT 网页版有什么区别，然后决定要不要继续读下去。

dsh 是什么

dsh 的全称是 DeepSeek Harness ，由 DeepSeek AI 开源。它是一个 agent Harness ，翻译成人话就是智能体运行框架：一个让 AI 助手能读写你的文件、执行命令、调用工具、按流程干活的"驾驶舱"。

它有四个很实在的特点：

• 图形化界面。运行一条命令后打开网页，所有的配置、对话、工具调用过程都看得见，鼠标点点就能用，不需要写代码。
• 一切皆插件。底层用 Cordis 框架组装，读文件、跑命令、查网页、调大模型，每一块能力都是可插拔的插件，想要什么就装什么。
• 安全可控。agent 想动你的文件、执行命令时，会先征求你的同意，每一步都清清楚楚。
• 开源免费。MIT 协议，代码托管在 GitHub，可以自己部署、改造、二次开发。

能做什么

装好之后，你可以让 dsh 帮你干这些类型的活：

场景	一句话指令
读懂代码	"总结这个仓库是干什么的，有哪些主要模块"
改代码	"把登录接口的错误提示统一改成中文"
跑任务	"运行测试，把失败的用例列出来并修掉"
查资料	"查一下 VitePress 最新版怎么配置本地搜索"
写文档	"根据这个项目的 README 生成一份发布说明"
干杂活	"把这批图片压缩到 200KB 以下"

关键是它工作在你的真实电脑上，读的是你的文件、跑的是你的命令，而不是一个封闭的聊天框。

和 ChatGPT 网页版有什么不一样

这是初学者最容易混淆的地方，用一张表说清楚：

对比项	ChatGPT 网页版	dsh
能不能看到你的文件	不能，只能聊	能，选中工作区后真实读写
能不能执行命令	不能	能，跑测试、装依赖、起服务
改完的代码在哪	在聊天记录里	直接改在你的项目里
过程透不透明	只给结论	工具调用树全程可见
要不要审批	不需要	敏感操作会先问你
能不能扩展	不能	插件随便装

一句话总结：网页版是"问它"，dsh 是"让它干"。

你需要什么基础

不多，两条就够：

1. 会安装软件。本文会带你装 Node.js 和 dsh，跟着步骤点就行。
2. 会打开终端敲一行命令。不需要会写代码，不需要懂 AI 原理。

这篇文章怎么带你入门

这篇文章的章节顺序就是 dsh 图形化界面的使用顺序。你打开界面后先看到什么、先要点什么，文章就先讲什么：

1. 配置模型，让 dsh 有"大脑"可用
2. 选择工作区，告诉 dsh 在哪个地盘干活
3. 发出第一条指令，看它怎么干活
4. 逐个点亮会话里的进阶功能
5. 最后学会设置、CLI 和常见问题

跟着界面走一遍，整篇文章就学完了。

先看一眼真身

这是 dsh 启动后的主界面，先混个脸熟：

左边是工作区与会话 导航，中间是对话区 ，底部是输入框 ，右上角是设置入口。具体每个区域干什么，下面会详细拆解。

0.2 环境准备

你将学会 安装 Node.js，用一条命令启动 dsh，打开图形化界面。整个过程大约 10 分钟。

在动手之前先说清楚，你只需要装两样东西：Node.js （dsh 的运行底座）和 dsh 本体（通过 npm 一条命令装好）。不需要装数据库、不需要配 Java、不需要懂任何编程。

第一步：安装 Node.js

dsh 是用 TypeScript 写的，运行在 Node.js 上，所以第一步是装 Node.js。

1. 打开 Node.js 官网 nodejs.org/
2. 下载 LTS（长期支持）版本的安装包，推荐 22 及以上版本
3. 双击安装，一路默认下一步即可

装完后，打开你的终端（Windows 用 PowerShell 或 CMD，macOS 用终端 App），输入下面两行命令验证：

node -v
npm -v

能看到类似这样的版本号就说明装好了：

v22.19.0
10.9.4

⚠️ 版本提示 dsh 目前处于预览阶段，要求 Node.js 22 及以上 。如果 node -v 显示的是 18 或更老，请升级到最新 LTS 再继续。

第二步：用一条命令启动 dsh

不需要单独安装 dsh，直接运行下面这条命令，npm 会自动下载并启动它：

npx @deepseek-ai/dsh web

第一次运行会花一两分钟下载依赖，终端里会滚动输出一堆日志，这是正常的。看到类似下面的内容，就说明启动成功了：

DeepSeek Harness
  http://127.0.0.1:3080/

想先装好再启动？ 如果你不想每次都用 npx 现场下载，可以先把 dsh 全局装好，再运行：

npm install -g @deepseek-ai/dsh
dsh web

两种方式效果一样，新手推荐直接用 npx，少一步概念。

第三步：打开图形化界面

启动成功后，打开浏览器，访问：

http://127.0.0.1:3080/

看到 dsh 的主界面，环境准备就算完成了。

现在这个界面还是"空"的：左边没有工作区，中间没有会话，底部输入框还不能用。别急，这正是我们后面几章要逐个解锁的。

0.3 启动与界面总览

你将学会 认识 dsh 主界面的每一个区域：侧边栏、对话区、输入框、顶部状态和设置入口，知道每一步该点哪里。

打开 http://127.0.0.1:3080/，你会看到下面这个界面：

一眼看过去信息不多，但每个角落都有讲究。我们从上到下、从左到右拆一遍。

左上角：新会话按钮

界面最左上角是新会话按钮。每点一次，就新建一个独立的对话，你可以理解成开了个新聊天窗口。多个会话之间互不干扰，各自有各自的上下文。

左侧边栏：工作区和会话导航

左边界面上有一栏导航，目前只显示工作区一个入口。

工作区这个概念贯穿整个 dsh，它就是你让 agent 干活的那个项目目录 。没选工作区之前，dsh 不知道你的文件在哪，所以对话区是"闲置"的。我们在 Part 2 专门讲它，这里先记住一句话：没有工作区，dsh 就没法真正动手干活。

顶部状态区：模型、权限和预设

对话区上方有一排状态信息，这排信息新手最容易忽略，但很重要：

• 模型：当前会话使用的模型名称。你可以把它理解成"这单活交给哪个大脑"。示例界面里显示的是 DeepSeek 的模型，后面 1.1 节教你配置和更换。
• 权限 ：当前会话的权限级别。示例界面显示 High，意思是 agent 可以执行较高权限的操作。权限越高，agent 能干的事越多，但越要小心它乱来，4.4 节和 7.2 节会细讲。
• Agent 预设 ：示例界面显示标准模式，它决定了新建会话时 agent 的角色和默认行为。在设置里可以换，6.3 节会讲。

中间主区：对话区

中间一大片空白就是对话区。你发出的指令、agent 的回复、它调用工具的每一步，都会在这里滚动展示。

初次打开时它显示"探索未至之境"和预览版标识，这是 dsh 的启动页。等我们发出第一条指令后，这里就会热闹起来。

底部：输入框

对话区下方是输入框 ，这是你给 agent 下指令的地方。注意现在它是不可用的，因为还没有选中工作区。选中工作区后输入框才会解锁，我们在 3.1 节发出第一条指令。

右上角：设置入口

右上角有一个设置按钮，点开后弹出设置面板：

设置面板有四个 tab，后面会逐个用到：

Tab	干什么的	学习章节
通用设置	Agent 预设、权限模式、语言、外观主题	Part 6
模型	配置 API 密钥、选择模型提供方	Part 1
插件	查看和启停插件	6.2
Agent 预设	选择或编写会话预设	6.3

在继续之前，你可以先点开设置面板逛一圈，只看不点，放心不会弄坏什么。

Part 1 · 配置模型

界面的第一道必做配置：告诉 dsh 用哪个模型、密钥在哪填。

1.1 配置第一个模型

你将学会 给 dsh 填上第一个 DeepSeek API 密钥，让"大脑"上线。这是整个界面第一道必做配置，做完模型立即可用。

为什么第一步是配置模型

前面我们看到了 dsh 的界面，它什么都好，但还缺一样东西：大脑。

dsh 本身不生产模型，它负责调度、干活，而真正"想问题、写代码、回话"的是背后的大模型服务。所以开工前必须先告诉 dsh：用哪家的模型、用什么密钥。配置好之前，会话输入框是没法真正干活的。

第一步：申请 DeepSeek API 密钥

dsh 对 DeepSeek 支持得最好，开箱即用，我们先用它。

1. 打开 DeepSeek 开放平台 platform.deepseek.com/
2. 注册并登录账号（支持手机号或邮箱）
3. 在左侧菜单找到 API 密钥（API Keys）
4. 点击创建 API 密钥 ，给密钥起个名字，比如 dsh-tutorial
5. 创建后立刻复制保存，格式是 sk- 开头的一长串字符

⚠️ 密钥只显示一次 DeepSeek 平台的密钥创建后只在页面上完整显示一次，关闭页面就再也看不到了。请先复制到安全的地方再关页面。

第二步：打开设置里的模型页

回到 dsh 界面，点右上角设置 ，在弹出的面板里点模型这个 tab：

页面上方有一句话：填入各提供方的 API 密钥即可使用其模型。下面列出了 DeepSeek 提供方，已经默认预置好了。

第三步：填入密钥并保存

1. 在 DeepSeek 提供方的卡片上，点编辑按钮
2. 弹出编辑表单，找到 API 密钥一栏：

3. 把上一步复制的 sk- 开头的密钥粘贴进去
4. 不用动其他配置，Base URL 默认就是 https://api.deepseek.com，模型列表里也已经列好了可用的模型（V4-Flash 和 V4-Pro）
5. 点保存

保存后，模型路由立即生效，不需要重启 dsh。

验证一下

回到主界面，看对话区上方的模型状态，如果显示的是 DeepSeek 的模型名（比如 DeepSeek-V4-Flash），就说明配置成功了。

还没配置时的样子 如果你在配置前看这个位置，它不会显示具体模型。配置好之后模型名才会出现，并且可以点开它切换其他模型，这部分在 4.1 节讲。

安全提醒

API 密钥就是你的钱袋子，按使用量计费，请把它当密码对待：

• 不要把密钥截图发到群里、贴到博客里
• 不要提交到 git 仓库
• 如果怀疑泄露，到 DeepSeek 平台吊销重建一个就行，旧密钥立即失效

1.2 多模型与自定义端点

你将学会 除了 DeepSeek，学会接入更多模型提供方，以及把 dsh 接到任意 OpenAI 兼容的服务上，比如本地的模型或者公司内部的网关。

两种接法

模型页上有两个入口，对应两种场景：

• 添加提供方：从 dsh 内置支持的提供方列表里选，填个密钥就能用，最省事
• 添加自定义提供方：手动填一个服务地址，适合本地模型、中转网关、公司内部服务

这一节两种都讲。

方式一：从内置列表添加

1. 打开设置 → 模型
2. 点添加提供方
3. 在弹出的列表里选择你用的服务，内置支持的有 OpenAI、OpenRouter、xAI、通义千问（qwen）、MiniMax、Moonshot（月之暗面）、Mistral、智谱（zai）、小米、NVIDIA、Together 等二十多家
4. 选中后会进入该提供方的配置表单，填上对应的 API 密钥 ，点保存

每个提供方的表单都长得差不多，都是密钥加可选的模型列表，和 1.1 节 DeepSeek 的编辑表单一致。

拿不到某家的密钥？ 各家平台都有自己的开放平台，去对应官网注册申请即可。填完后和 DeepSeek 一样，模型立即可用。

方式二：添加自定义提供方

这个入口是给"标准 OpenAI 兼容接口"准备的。你的服务只要实现了 OpenAI 的接口协议，就能被 dsh 识别。典型的场景有三个：

• 本地跑的模型，比如 Ollama、vLLM、LM Studio
• 第三方中转服务，统一转发到多家大模型
• 公司内部网关，只对员工开放

点添加自定义提供方，弹出下面的表单：

逐个字段解释：

字段	填什么	例子
Provider ID	小写字母开头的唯一标识，用于派生凭据名	my-gateway
显示名称	界面上显示的名字	我的网关
API 地址	服务的完整地址	https://gateway.example/v1
API 协议	接口协议，三种可选	openai-completions
API 密钥	该服务的密钥	sk-...
模型目录	列出可用的模型 ID	见下方说明

API 协议选哪个

• openai-completions：标准 OpenAI 对话补全协议，绝大多数服务都兼容，默认选这个
• openai-responses：OpenAI 新版 Responses 协议，只有 OpenAI 自家最新服务用
• anthropic-messages：Anthropic（Claude）的消息协议

不确定就选第一个。

模型目录怎么填

表单里有一个模型目录区域，两种填法：

1. 点获取可用模型，dsh 会自动请求服务把模型列表拉下来，不用手敲
2. 如果服务不支持列举模型，点添加模型 手动填：先填模型 ID（请求里用的原始 ID，比如 qwen2.5-7b），再填显示名称（界面下拉里看到的）

填完点创建提供方就完成了。

实战：接一个本地 Ollama

拿最常见的本地模型场景举例。假设你装了 Ollama 并跑起了 qwen2.5:7b：

1. 模型页点添加自定义提供方
2. Provider ID 填 ollama-local
3. 显示名称填 本地 Ollama
4. API 地址填 http://localhost:11434/v1
5. API 协议选 openai-completions
6. API 密钥随便填一个占位（本地服务通常不校验）
7. 点获取可用模型 ，或手动添加模型 ID qwen2.5:7b
8. 点创建提供方

之后就能在主界面的模型选择器里看到本地 Ollama了。

⚠️ 本地服务的地址 本机服务用 localhost 就行。如果 Ollama 跑在另一台机器上，地址要换成那台机器的局域网 IP，并确认服务监听了非本机端口。

Part 2 · 工作区

dsh 干活的地盘。选好工作区，会话输入框才会解锁。

2.1 什么是工作区

你将学会 理解工作区这个概念：它是什么、为什么必须先选它、它管着哪些东西。

一个比喻

想象你雇了一位远程助理，他住在线上，看不到你的电脑。你要让他帮你干活，第一件事是什么？告诉他你的项目在哪。要不然他不知道去哪个文件夹翻文件，也不知道改完的东西放哪。

工作区就是这个"项目在哪"的答案。

工作区的官方定义

在 dsh 里，工作区是一个项目目录的持久化记录。它记着三样东西：

• 目录路径：你让 agent 干活的那个文件夹的真实位置
• 显示名称：界面上显示的名字，默认取目录名
• 会话归属：在这个工作区里开过的所有会话

一句话：工作区 = 目录 + 名字 + 它的会话清单。

为什么必须先选工作区

因为 dsh 的所有"动手"都建立在工作区上：

动作	依赖工作区的地方
读文件	在哪个目录里找文件
改代码	改完写回哪个目录
跑命令	在哪个目录下执行命令
会话归属	这次对话算哪个项目的

不选工作区，agent 就没有"地盘"，自然没法真正干活。这也是为什么主界面上，选中工作区之前，会话输入框是锁着的。

一个目录一个工作区，可以有很多个

• 一个工作区对应一个目录，路径会做规范化处理，同一个目录不会重复创建
• 可以添加多个工作区，对应你手头的多个项目
• 工作区和你的文件系统是引用关系：添加工作区不会复制、移动你的任何文件，删掉工作区也不会删除你的文件，只是把这条"记录"从界面上去掉

工作区在界面上长什么样

打开 dsh 主界面，左侧边栏最上方就是工作区分区：

分区里会列出你添加过的工作区，每个工作区下面展开属于它的会话。你添加的第一个工作区，马上就会出现在这里。

2.2 添加选择与创建

你将学会 动手添加你的第一个工作区：找到入口、选择目录、确认添加，最后在侧边栏看到它。

入口在哪

工作区有两个添加入口，都在主界面上：

1. 对话区顶部的选择工作区按钮。全新安装的 dsh，打开后对话区会提示选择工作区，点它即可
2. 侧边栏工作区分区的添加按钮 。鼠标移到侧边栏工作区分区标题上，右侧会出现一个添加图标，点它也行

两个入口殊途同归，都会打开系统目录选择器（就是你在资源管理器里选文件夹的那个对话框）。

第一步：选择目录

点击添加入口后，系统弹出目录选择对话框：

1. 找到你想让 agent 干活的项目目录，比如 my-project
2. 选中这个文件夹（注意是选文件夹本身，不是进到里面选某个文件）
3. 点确定

选哪个目录合适 选项目根目录最合适，比如你的仓库根目录、网站源码目录。这样 agent 能读到你项目里的所有文件。别选 C 盘、用户主目录 这种大而全的目录，范围太大会让 agent 找东西很慢，误操作风险也高。

第二步：确认添加

目录选好后，dsh 会自动完成两件事：

1. 在工作区列表里创建一条记录，显示名称默认取目录名
2. 自动选中这个工作区，让它成为当前工作区

回到主界面，看左侧边栏工作区分区下面，你的项目目录名已经出现了。把鼠标悬停在它上面，可以看到完整的目录路径。

同时你会发现，底部会话输入框已经解锁，可以开始发指令了。

管理工作区

工作区出现在列表后，悬停在工作区行上会出现操作菜单，常用的有三个：

操作	干什么	注意
重命名	改显示名称	只是改界面显示名，不影响真实目录名
删除	从列表移除该工作区	有确认弹窗，不会删除你的文件和会话，会话会归入"未分组"
归档会话	把会话收进归档	非破坏性，随时可恢复展示

多工作区切换

如果你有多个项目，就再走一遍添加流程，每个项目一个工作区。之后点侧边栏里的任意工作区名，就能切换当前工作区，对应会话也会跟着切换。

每个工作区是独立的，这个项目里的会话不会混进另一个项目。

Part 3 · 第一次会话

发出第一条指令，见证 agent 怎么读文件、跑命令、给你交差。

3.1 新建会话与第一条指令

你将学会 新建一个会话，向 agent 发出第一条指令，亲眼看着它在你的工作区里读文件、跑命令、给你交差。

第一步：新建会话

主界面左上角是新会话按钮，点它创建一个全新会话。每点一次就是一个独立对话，各自的上下文互不干扰。

新建后，对话区显示欢迎页，底部输入框已经解锁（工作区选好后输入框就可用）。输入框里有句提示：描述你想要构建的内容。

第二步：输入第一条指令

在输入框里输入你的第一句话。第一次用，推荐这种"总结式"的指令，只读、安全、立刻见效：

列出当前工作区目录下的文件，并简要说明这个项目是做什么的

也可以换成任何你想让它干的事，比如：

类型	示例指令
读懂项目	"总结这个仓库的模块结构"
找东西	"找出所有写着 TODO 的地方"
改东西	"把登录页的标题改成 欢迎回来"
跑任务	"运行测试并汇报结果"

指令写得越具体越好 agent 是按指令干活的，指令含糊它就只能猜。想要它干什么、范围在哪、产出什么格式，一次性说清楚，后面省很多来回。

第三步：发送并观察

输入好后按 Enter 发送（或者点发送按钮）。消息发出后，你会看到两件事同时发生：

1. 你的消息出现在对话区
2. 消息下方开始滚动出现一串工具行，这是 agent 干活的轨迹

第一次跑会花一点时间。它要先思考你的指令，再调用工具去看工作区里的文件，最后汇总成回答。短任务十几秒，长任务几分钟都正常。

第四步：等它交差

agent 完成后，对话区会留下完整的记录：你的问题、它调用工具的每一步、最后的回答。底部还有一行统计信息，告诉你这次任务用了多久、调了多少轮工具、消耗了多少 token。

你的第一条指令，通常会让 agent 列出工作区并介绍项目。它的回答可能超出预期地详细，这正是它"真在干活"的证据。

3.2 看懂工具调用树

你将学会 搞懂对话里那些工具行是什么：agent 是怎么思考、怎么调工具、怎么一步步干完活的。

什么是工具调用树

普通聊天里，AI 给你一段文字就结束了。但 dsh 的 agent 不一样，它要真正动手 ：读文件、搜代码、跑命令。它每做一步，界面上就会多一行记录，这些记录串起来，就是工具调用树。

一句话：工具调用树 = agent 干活的每一步的流水账。

看一棵真实的工具调用树

下面是我发了一条"列出工作区文件并介绍项目"的指令后，agent 实际产生的工具调用树：

从下往上看，它是这样的一个流程：

工具行	干了什么
上下文注入 · 系统提示词	给 agent 装上"怎么干活"的出厂设定
上下文注入 · 技能目录	加载可用的技能清单，让它知道手里有什么牌
Think	先想一步：用户要什么，第一步该做什么
Pwsh	执行命令，列出工作区目录里的文件
Glob	按模式搜索文件，比如找 README 文件
Think	看结果，想下一步：每个项目都要了解一下
Pwsh	再执行命令，读取每个项目的关键信息
Think	信息齐了，开始组织最终回答

看到规律了吗？agent 的干活节奏是：想一下，动一下，看结果，再想，再动。每一行工具调用，都是它真实执行过的一步，不是摆样子。

点开工具行看细节

每一行工具都可以点击展开，看这一步的完整内容。比如点开一个 Think 行，能看到 agent 当时的思考过程：

点开 Pwsh 行，能看到它实际执行的命令和命令的输出。点开上下文注入行，能看到注入的提示词内容。想确认 agent 到底对你的项目做了什么，就逐行点开看，一切透明。

几种常见工具行

不同任务会用到不同工具，认识几个常见的：

工具行	作用	常见场景
Think	模型内部思考	几乎每次行动前都有
Pwsh / Bash	执行命令	列目录、跑测试、装依赖
Glob	按文件名模式搜索	找 README、找配置文件
Read	读取文件内容	看代码、看文档
Write / Edit	写入、修改文件	改代码、写文档
上下文注入	注入系统提示、技能	每次会话开始

工具越多，agent 能干的事越多。前面列的都是内置能力，后面章节会看到更多（子代理、工作流、网页搜索等）。

消息流底部的统计信息

一次任务完成后，工具调用树的下方会显示一行统计，比如：

1 轮 · 4 步 | LLM 14.9s · 工具调用 45.5s | 缓存命中 71% | 输入 76K tok · 输出 1.6K tok

逐个拆解：

• 1 轮：这次任务跑了几轮（一轮 = 一次完整的思考加行动）
• 4 步：总共调用了多少次工具
• LLM 14.9s：模型思考花了多久
• 工具调用 45.5s：执行命令、读文件这些实际动作花了多久
• 缓存命中：多少内容命中了上下文缓存，命中越高越省钱
• 输入 / 输出 tok ：这次任务消耗的 Token 量

任务变长时，这些数字会帮你判断时间花在了"想"还是"干"上。

Part 4 · 会话进阶

会话里藏着的十个进阶功能：从切换模型到轨迹视图，逐个点亮。

4.1 切换模型

你将学会 学会在会话里切换模型，并根据任务难度调整推理等级。

模型就是"大脑"，可以随时换

配置好模型之后，dsh 默认会用你配置的那个。但实际干活时你会发现，不同任务适合不同模型：

• 简单任务（查资料、整理格式）用轻量模型，快又省
• 复杂任务（重构代码、设计架构）用更强的模型，思考更深入

好消息是切换不需要重启，会话进行到一半也能换。

模型选择器在哪

有两个入口，都在主界面上：

1. 输入框左侧：有一个显示"选择模型，当前 DeepSeek-V4-Flash，推理等级 High"的按钮
2. 顶部状态区：显示当前模型名的那一块，点它同样打开

点开后弹出模型选择器：

两个设置：模型 + 推理等级

选择器里有两项：

模型：列出所有已配置且可用的模型。你配了哪些 provider，这里就有哪些模型可选。点一下模型名就切换，立即生效。

推理等级：控制模型"想多深"。选项一般是 High、Medium、Low 这样的档位：

等级	适合场景	代价
High	复杂推理、架构设计、疑难排查	更慢、token 更多
Medium	日常开发、中等任务	均衡
Low	简单问答、格式整理	最快、最省

建议 先用默认档跑，觉得回答太浅就调高一档，觉得太慢就调低。没有绝对正确的设置，按任务手感来。

切换后会发生什么

切换是即时的，界面上的模型名会立刻更新。需要注意的是：

• 切换模型不会清空当前会话，之前的对话记录还在
• 切换后，从下一条消息开始用新模型
• 如果换的模型没配好密钥，会提示不可用，回 Part 1 检查

4.2 添加附件

你将学会 学会把文件、图片喂给 agent，让它基于你的资料干活。

为什么要喂附件

对话只靠文字，很多场景说不清楚：

• 你想让它照着设计稿做页面，光描述颜色、间距太费劲，把图拖进去它直接看
• 你想让它分析一份数据，把 CSV 文件拖进去，它读完就能算
• 你想让它按某个文档改代码，把文档拖进去，它照着改

这就是附件的作用：让 agent 直接"看到"你的材料，而不是靠转述。

怎么添加附件

添加方式很直接，和聊天软件传文件一样：

1. 把文件或图片直接拖进输入框区域，松开即添加
2. 或者点输入框里的附件入口选择文件

添加成功后，输入框上方会出现附件的缩略图或文件条，确认无误后正常发送即可。

发送后，附件会作为消息的一部分出现在对话流里，agent 会先"看"附件再回答你。

实际能传什么

dsh 支持常见的文件类型，实践中用得最多的是：

类型	典型用途
图片	设计稿、截图、流程图，让它照着实现
文本文件	代码、文档、配置，让它基于内容分析
数据文件	CSV、JSON，让它统计、提取、清洗
压缩包	一整个项目的代码，让它读懂结构

大文件怎么处理 文件过大会挤占上下文空间。如果是一整个项目，更推荐把项目目录设为工作区（Part 2），让 agent 自己读，而不是压缩上传。

附件进了上下文，就占 token

每个附件都会被转成模型能理解的内容，占用上下文的 token。附件越多越大，对话开销越高。用完的文件可以删除，控制上下文在合理范围。

这也是为什么：能靠工作区读的文件，就不用附件传。

4.3 命令与引用

你将学会 学会用斜杠命令调用技能、用引用把技能和子代理带进会话，输入框的效率翻倍。

输入框里藏着的两个快捷键

dsh 的输入框不只是打字的地方。在输入框里敲两个符号，会弹出两个快捷面板：

• 敲 /，弹出命令与技能列表
• 敲 @，弹出引用列表

先混个脸熟，然后逐个说。

斜杠命令：让 agent 带上技能干活

在输入框里敲 /，会弹出命令列表。这个列表里既有 dsh 内置的命令，也有你安装的技能：

选一个技能，它就会以"让 agent 用这个技能干活"的方式加入你的指令。举个例子，如果你安装了视频制作类技能，输入 / 选它，再补一句"把这个网址做成一条介绍视频"，agent 就会按那个技能的工作流去执行。

斜杠命令的好处是把复杂能力变成一句话。技能怎么装、怎么用，dsh 的插件体系管着，你只要会选。

引用：把技能或子代理带进上下文

在输入框里敲 @，弹出引用面板：

引用的作用是把某个东西"点名"出来，让它参与这次对话。可以引用的包括：

• 技能：指定让 agent 用哪个技能
• 子代理：把子代理带进来协同（4.7 节细讲）
• 文件：直接引用工作区里的文件

引用和斜杠命令有点像，但更灵活：可以夹在句子里用，比如"用 @某某技能 把这份文档翻译成英文"。

怎么判断该用哪个

情况	用哪个
想让它用某个技能干活	斜杠 / 或引用 @ 都行
想引用某个具体文件	引用 @
想带一个子代理协同	引用 @
想执行某个内置命令	斜杠 /

先记住一句话：想给 agent 加能力，敲 /；想点名某个东西，敲 @。

4.4 权限与审批

你将学会 理解权限模式是什么、怎么切换，以及 agent 想做"出格"操作时，审批弹窗该怎么处理。

权限模式：给 agent 划边界

agent 在你电脑上干活，总要有个"能干什么、不能干什么"的边界。dsh 用权限模式来管这件事。

权限模式决定了两件事：

• 沙箱：agent 的命令在什么范围内执行（只能动工作区，还是整个系统）
• 审批：超出范围的操作，是询问你，还是直接拒绝

权限模式在哪切

输入框左侧有一个访问模式按钮，显示当前模式，比如"访问模式，当前：Workspace Write"。点它弹出权限选择器：

常见的档位从低到高：

模式	能干什么	适合
Read Only	只能读，不能改任何东西	只问问题、看代码、查资料
Workspace Write	能读写工作区内的文件、跑命令	日常干活（推荐）
Full access	整个系统都能碰	需要全局操作的场景，慎用

切换即时生效。注意：权限模式切换只影响之后的操作，已经跑起来的任务保持它开始时的模式。

审批：超出边界的操作会问你

即使模式设好了，agent 也可能遇到"这一步超权限了"的情况。这时候 dsh 会停下来问你，界面上弹出一个审批卡片：

1. 显示 agent 想执行的操作内容
2. 你选择允许这一次 或拒绝

关键点：允许是一次性的。agent 每做一步超权限操作，都要单独问一次，批准只放行当前这一步，不会"一劳永逸"。这正是 dsh 安全性的核心：agent 永远不能绕过你自作主张。

审批时看什么 别只看"允许"两个字就点。先看审批卡片上写的具体操作：它想改哪个文件、跑什么命令、访问什么地址。看清了再决定。

审批策略：ask 还是 never

权限模式背后有两条审批策略：

• ask：默认。每次超权限操作都问你
• never：永不询问，直接拒绝。适合无人值守的自动化场景，宁可干不成也不冒险

日常使用保持 ask 就好。never 模式主要是给自动化、CI 这类场景用的，后面进阶内容会展开。

实践建议

• 日常用 Workspace Write，既能干活又有边界
• 只查不改时切 Read Only，最安心
• Full access 只在明确需要时临时切，用完切回来
• 审批弹窗认真看再点，这是最后一道闸

4.5 设定目标

你将学会 学会用目标功能让 agent 聚焦一件事，不被中途的枝节带偏。

为什么需要目标

agent 干活时，经常会出现一种情况：你让它"修登录页 bug"，它修着修着开始优化布局、整理代码风格，最后方向跑偏了。

目标 就是用来治这个的。你先把"这次会话要完成什么"明确告诉 agent，它就会在每轮决策时对照目标，跑偏了就拉回来。

怎么设定目标

设定目标不需要找特殊的界面按钮，直接在对话里告诉 agent 就行。有两种说法：

方式一：和任务一起说

本次会话的目标是：修复登录页在手机端显示错乱的问题。现在开始排查。

方式二：任务中途补设

设定目标：先把登录页 bug 修完，其他优化都先不做。

说完之后，dsh 会把目标记下来，界面上会出现当前的目标状态，让你随时看到这次会话在朝哪个方向走。agent 的每一步都会对照这个目标。

目标有哪些状态

一个目标不是"设了就完"，它有生命周期，界面上会显示当前处于哪个阶段：

状态	含义
进行中	正在朝目标推进
已暂停	暂时搁置，可能被其他事打断
受阻	卡住了，需要你介入（比如缺权限、缺信息）
已完成	目标达成

卡住的时候，agent 会说明原因并等你处理。这也是它主动"求助"的机制：干不动就告诉你，而不是硬编。

一个完整例子

看这个会话怎么靠目标保持专注：

1. 你发：设定目标：把这个项目的 README 补全，只做这个，然后开始
2. agent 确认目标，开始读现有 README 和代码
3. 中间 agent 想"顺手修一下排版"，对照目标发现和 README 无关，跳过
4. README 补全后，agent 汇报并标记目标已完成

全程没跑偏，因为每一步都有目标对照。

目标写得越收敛越好 "把 README 补全"比"把这个项目完善一下"管用得多。目标模糊，agent 就没法判断什么算跑偏。

4.6 计划模式

你将学会 学会用计划模式让 agent 先把步骤摊开给你看，批准后再动手。

什么时候需要计划模式

大部分任务，agent 边想边干没问题。但有些任务不适合"边干边想"：

• 改动大的活：比如重构整个模块，干到一半发现方向错了，返工成本高
• 牵扯面广的活：改一个地方影响十几个文件，最好先看清全貌
• 不容出错的活：比如数据库迁移，一步错就麻烦

这类任务，你希望它先交方案，你点头，再动手。计划模式就是干这个的。

怎么进入计划模式

计划模式用斜杠命令控制，在输入框里输入：

/plan

发送后，dsh 进入计划模式。它的效果是：接下来的每一步，agent 先思考、再出计划、等你审阅，不会直接执行。

退出计划模式，输入：

/plan off

也可以带着消息进入，比如：

/plan 帮我重构登录模块的权限校验部分

这条命令会同时进入计划模式，并把你的需求作为下一步的任务提交给 agent。

计划模式里会发生什么

进入计划模式后，你发一个任务，agent 会：

1. 先研究：读相关代码、理清现状（这阶段它只读不动）
2. 出计划：把要做的步骤整理成一份计划，展示给你
3. 等你审阅：你检查这份计划，批准或提修改意见
4. 批准后执行：你点头了，它才开始真正动手

界面会显示计划模式的状态，让你清楚当前处于"等待审阅"还是"执行中"。agent 的每一步改动都严格按批准的计划走。

一个完整例子

假设你要重构一个模块：

1. 输入 /plan 重构登录模块的权限校验
2. agent 开始读代码，只读不改
3. 几分钟后，它给出计划：第 1 步抽公共校验函数，第 2 步替换三处调用，第 3 步补测试
4. 你检查，觉得第 2 步还要改一处注释里提到的旧接口，让它加上
5. agent 更新计划，你批准
6. 它按计划一步步执行，每一步都对应计划里的一项

全程你都知道它要干什么、干到哪了。

计划模式不是万能药 计划模式是"软约束"，它引导 agent 先计划后执行，但不额外限制它的工具权限。权限边界还是靠前面讲的权限模式管。日常小任务没必要开计划模式，反而多一道审阅。

4.7 子代理

你将学会 学会让 agent 把任务拆给子代理，多个子代理并行干活，主代理统筹汇总。

什么是子代理

agent 干活是一个线程从头跑到尾。但有些任务天然适合分工：

• 调研任务：同时查文档、查代码、查社区，三个方向互不干扰
• 大项目改造：一个子代理改前端，一个改后端
• 独立子任务：让一个子代理专门核对数据，另一个专门写测试

子代理就是 agent 委派出去的子 agent。主 agent 把任务拆开，分配给子代理并行执行，最后收集结果汇总给你。相当于主代理当项目经理，子代理是干活的组员。

怎么触发子代理

不需要专门的按钮，直接在指令里说就行：

用两个子代理并行调研：一个查这个框架的文档，一个查社区的实践案例，最后汇总

agent 判断任务适合拆分时，也会自己决定使用子代理。你会在消息流里看到子代理行：它们像工具调用一样展示，但展开后是子代理自己的完整对话记录。

界面上的子代理

子代理在界面上的呈现有几个特点：

• 子代理行：消息流里每个子代理一行，显示它领了什么任务
• 完整转写：点开子代理行，能看到子代理自己的完整对话（它思考了什么、调用了哪些工具、怎么交的差）
• 子代理导航：从父会话可以进入子代理的会话视图，就像打开一个子对话
• 并行状态：多个子代理同时跑时，各自的状态独立显示

能对子代理做什么

除了"派活"，你还可以：

• 给子代理发消息：中途补充信息、调整方向
• 打断子代理：跑偏了让它停下来
• 查看子代理列表：看清当前有哪些子代理在跑、什么状态

什么时候用子代理

场景	用子代理的收益
多方向调研	并行查，省时间
前后端/多模块并行改	互不阻塞
独立子任务	上下文隔离，不互相干扰

提示 子代理适合"拆得开、各干各"的任务。任务紧密耦合、改一处影响全局的，反而不适合拆，交给一个 agent 从头做更稳。

4.8 后台任务

你将学会 学会把耗时的活丢到后台执行，让对话不被卡住，随时回来收结果。

什么时候需要后台任务

agent 干有些活很慢：

• 跑一次完整的测试套件，要几分钟
• 批量处理一批文件，要跑很久
• 构建一个大项目，编译要等

这种任务如果让 agent 一路干完，你的对话就一直"转圈"，期间想让它干别的都不行。后台任务就是解法：把这种耗时任务放到后台跑，对话立刻恢复可用，任务完成后再回来收结果。

怎么把任务放后台

和子代理一样，直接说就行：

把这个批量压缩任务放到后台执行，完成后告诉我结果

agent 会把任务注册成后台任务，对话立刻恢复。你会看到会话头部出现后台任务列表，实时显示每个任务的状态。

界面上的后台任务

后台任务在界面上有专门的位置：

• 会话头部任务列表：当前会话的后台任务都列在这里
• 状态实时显示：运行中、停止中、已完成、失败、被终止，一目了然
• 任务详情：点开可以看任务的具体进度和产出

任务跑完后，agent 会把结果汇报到对话里，你也可以随时从任务列表查看。

后台任务的状态

状态	含义
运行中	正在执行
停止中	收到停止指令，正在收尾
已完成	跑完了，可以查看结果
失败	出错了，看详情找原因
已终止	被手动终止

常见后台任务的类型有命令行任务、子代理任务等，它们统一由后台任务系统管理。

实践建议

• 长任务默认丢后台：测试、构建、批量处理这类，直接说"放后台执行"
• 任务多时注意管理：后台任务太多会互相抢资源，没用的及时终止
• 结果要确认：任务完成不等于结果正确，收到汇报后抽验一下

4.9 工作流

你将学会 认识工作流：把多步流程编排成脚本，自动启动子代理，一次跑完一条流水线。

什么是工作流

子代理解决"拆分"问题，后台任务解决"等待"问题，但都还差一层：流程的编排。

比如你有一个固定套路：拉取数据、清洗、生成报告、发布。这套流程每次都要走一遍，如果靠手发指令，一遍遍重复太累。

工作流 就是把这类流程写成一段编排脚本：脚本按顺序定义每一步干什么、什么时候启动子代理、子代理之间怎么衔接。agent 写好脚本后，一条命令跑完整个流水线。

工作流和普通任务的区别

对比	普通任务	工作流
流程	临时决定，边想边干	脚本固化，按步执行
子代理	现场拆	脚本里编排，自动启动
复用	每次重新来	一套脚本反复跑
适合	一次性任务	重复性流程

一句话：普通任务是"干一次"，工作流是"定个流程，以后照跑"。

怎么用工作流

工作流目前是偏进阶的能力，用法上记住两点：

1. 让 agent 用工作流执行：对重复流程，告诉 agent"把这个流程写成工作流跑一遍"。agent 会编写编排脚本并执行，脚本里的每一步（包括启动子代理）都会按顺序推进
2. 查看运行过程 ：工作流跑起来后，界面上会以嵌套展开的方式展示每一步，你可以一层层展开看：这步调了哪个子代理、子代理干了什么、结果如何

什么时候值得用

• 固定流程反复跑：比如每周生成一次数据报告
• 多步骤强依赖：第 1 步的产物是第 2 步的输入
• 涉及多个子代理协作：脚本统一编排，避免现场临时拼

学习建议 工作流是这一章里最进阶的功能。初学者先做到"认识它、能用它跑现成流程"即可。想深入编排和写脚本，等基础功能都熟了再看进阶内容。

4.10 轨迹视图

你将学会 学会切换到轨迹视图，从"原始记录"的角度回看 agent 每一步到底做了什么。

一个会话，两种视图

打开一个会话，对话区顶部有两个视图 tab ：对话 和轨迹。

• 对话视图：默认。展示的是"人话版"：你的消息、agent 的回复、折叠的工具行。适合日常查看
• 轨迹视图：展示的是"原始版"：会话里每一轮的完整原始记录，一字不落

大多数时候看对话视图就够了。当你想搞清楚"agent 到底干了什么"时，切到轨迹视图。

对话视图 vs 轨迹视图

这是同一个会话的两种呈现。对话视图长这样：

它把 agent 的工作流整理成了清晰的消息流。而同一个会话切到轨迹视图，长这样：

轨迹视图按轮次组织，每一轮完整记录这些内容：

记录段	内容
Turn	第几轮、第几步
USER	你的原始输入
CONTEXT	注入的运行时上下文（当前权限、工作区、可用技能等）
ASSISTANT	agent 的完整思考过程
TOOL	工具调用的原始 JSON 和返回结果

什么时候用轨迹视图

• 排查"它为什么这么干"：对话视图只给结论，轨迹视图能看到它每一步的思考和原始上下文
• 看上下文注入：想知道 agent 看到了哪些系统提示和技能清单，轨迹里都有
• 核对工具调用：对话视图的工具行是摘要，轨迹里是工具调用的完整参数和原始返回

怎么切换

点对话区顶部的轨迹 tab 即可切换，再点对话切回来。切换不影响会话内容，只是换一种看法。

小提示 轨迹视图信息量大，是给"查细节"用的。日常干活看对话视图就好，别被原始记录淹没。

Part 5 · 会话管理

侧边栏是会话的总控台：多会话切换、恢复历史，一个都不落。

5.1 会话列表与历史

你将学会 学会用侧边栏管理会话：新建、切换、搜索、恢复历史，以及重命名、分叉和归档。

侧边栏就是会话的总控台

dsh 的左侧边栏不只是导航，它是会话的总控台。所有会话都在这里，按工作区分组排列，一眼看清每个项目下有哪些对话。

侧边栏从上到下包含：新建会话 按钮、工作区分区（工作区 + 它下面的会话列表）、会话搜索框、视图选项和设置入口。

新建会话

两种方式：

1. 点侧边栏顶部的新建会话按钮，新建一个独立会话
2. 在工作区行的菜单里选在此工作区中新建会话，新会话直接归属到该项目

打开历史会话

想回到之前的对话继续干？直接点侧边栏里对应的会话行，对话区就会加载那个会话的完整历史，从头到尾都能翻看和续聊。

会话行上还会显示一些状态信息：正在运行的会话有运行指示，等待你审批的会标出来，方便你一眼找到需要处理的会话。

搜索会话

会话多了以后靠翻很累，用搜索：

1. 点侧边栏的搜索会话（放大镜图标）
2. 输入关键词，比如"README"
3. 结果按相关度列出，点一下直达

搜索范围包括会话标题和内容，标题搜不到就搜内容试试。

会话行的操作

鼠标悬停在某个会话行上，会出现操作按钮，点开有这些常用操作：

操作	干什么	什么时候用
重命名	给会话改个更好认的名字	自动标题不满意时
分叉	从该会话某个节点复制出一条新线	想基于旧对话换个方向试
归档	把会话收进归档，从列表隐藏	暂时不用的会话，留着以后找

分叉是神器 分叉不会动原会话，它从你选的位置复制出新会话，原会话原样保留。做实验、试不同方案特别好用。

工作区行的操作

工作区行同样有操作菜单：重命名 （改显示名）、删除（移除记录，不删文件不删会话，会话归入未分组）。这块在 2.2 节讲过，这里不重复。

视图选项

侧边栏的视图选项按钮可以调整会话的展示方式，比如按最近更新排序、手动排序、按工作区分组还是平铺成一张列表。按你的习惯选就行。

Part 6 · 设置与个性化

把 dsh 调成你的形状：常规、插件、Agent 预设、主题。

6.1 常规设置

你将学会 把 dsh 的通用偏好设置过一遍：预设、权限、语言、外观、回车行为。

设置面板在哪里

点主界面右上角的设置 按钮，弹出设置面板。第一个 tab 就是通用设置，日常用到的偏好都在这。

通用设置都有什么

设置项	作用	默认
Agent 预设	新会话默认用什么 Agent（标准模式等）	标准模式
权限	新会话的默认权限模式	Workspace Write
语言	界面语言	中文
外观	界面主题（浅色/深色/跟随系统）	跟随系统
繁忙时 Enter 行为	agent 运行时按 Enter 怎么处理	排队发送

逐个说明一下。

Agent 预设：决定新会话的 agent 类型。切到"标准模式"，新会话就是功能完整的编码 Agent。具体有哪几种，6.3 节细讲。

权限：新会话默认的权限模式，对应 4.4 节的档位。日常保持 Workspace Write，需要全局操作再手动切。

语言：界面语言。目前支持中文，切过去立即生效。

外观：主题设置，浅色、深色、跟随系统三选一，6.4 节细讲。

繁忙时 Enter 行为 ：agent 正在运行时，你按 Enter 会怎样。默认排队发送：回车后消息排着队，agent 忙完自动继续处理。想要别的行为就换选项。

打开配置文件

设置面板里还有个打开配置文件入口，点开可以看到 dsh 的实际配置文件。新手不建议直接改配置文件，界面能设置的先用界面，改错了配置反而容易出问题。

6.2 插件

你将学会 认识设置里的插件页：怎么查看已装的插件、怎么调整核心插件的行为。

插件页在哪里

设置面板点插件 tab。页面上方一句话点题：配置和查看本部署已安装的插件。

核心插件配置

插件页列出了几个核心插件的配置项，它们是 dsh 能力的地基：

插件	控制什么
终端	限制 agent 运行的每一条命令
Agent 循环	Agent 如何派发工具调用
网页搜索	DeepSeek 搜索提供方

以终端为例：它负责给 agent 的命令执行兜底。在这里可以配置命令的执行范围、是否启用沙箱等，是安全边界的一部分。

插件列表

插件页还有一个插件列表视图，列出当前部署里已经安装的全部插件。每个插件都能看到：

• 插件名称：比如各种能力插件、UI 插件
• 运行状态：是否在运行
• 配置入口：有配置的插件可以从这里进

插件和技能的关系

你可能会问：插件和 4.3 节说的技能（Skills）是一回事吗？

不完全一样，理解成两层：

• 技能是给 agent 用的"说明书"，告诉它怎么完成某类任务
• 插件是能力的"零件"，技能、工具、界面组件都是通过插件装配起来的

技能在会话里用斜杠 / 调用，插件在设置里管理，它们是 dsh 插件体系的两个侧面。

6.3 Agent 预设

你将学会 理解 Agent 预设是什么，学会在预设之间切换，并知道怎么创建一个自定义预设。

预设决定"agent 是什么样"

同样一个 dsh，agent 可以有不同的"形态"：有的功能全、有的精简、有的可以自己扩展。Agent 预设就是这些形态的出厂配置，它决定一个新会话里的 agent 是什么样。

设置面板点 Agent 预设 tab，就能看到所有预设：

内置的四个预设

dsh 内置了四个预设，从上到下能力从全到简：

预设	能力	适合
标准模式	功能完整的编码 Agent：文件编辑、Shell、文件与网页检索、技能、计划、目标、子代理、工作流	日常默认（推荐）
PTC 模式	标准模式的全部能力，但工具通过 Code Mode SDK 呈现，模型用 TypeScript 程序组合多步操作	喜欢程序化控制的玩家
极简模式	只保留两个工具：持久 bash 和文件编辑	极简环境、专注跑命令
创造模式	标准模式全部能力，附加运行时检查、插件实验和创作指导	用来制作自定义预设

标准模式是大多数人的日常选择，也是默认预设。它是"功能完整的编码 Agent"，前面几章讲的所有能力它都具备。

怎么切换预设

设置 → Agent 预设 → 点选目标预设即可。切换后：

• 新会话使用新预设
• 已存在的会话保持开始时的预设不变

主界面顶部状态区也会显示当前会话用的预设，比如标准模式。

创建自定义预设

内置预设不够用？用创造模式：

1. 先切到创造模式，它自带创作指导
2. 按指导调整 agent 的行为、插件组合
3. 保存成你自己的预设

自定义预设适合对 agent 行为有特殊要求的场景，属于进阶玩法，先知道有这条路就行。

6.4 主题

你将学会 切换界面主题，选择浅色、深色或跟随系统，让 dsh 看着顺眼。

主题在哪设置

设置面板的通用设置 tab 里，外观一栏就是主题设置，三个选项：

选项	效果
浅色	白底深字，明亮清爽
深色	黑底浅字，夜间友好
跟随系统	跟随操作系统的明暗设置，系统深色它就深色

切换立即生效，不用重启。

怎么选

纯看个人习惯：

• 白天工作多：浅色，字迹清晰
• 经常熬夜写代码：深色，护眼
• 系统本来就开了深色模式：跟随系统，全平台一致

小建议 如果拿不准，就选跟随系统。它自动匹配你整个电脑的明暗风格，最省心。

主题只影响界面

主题只是界面外观，不影响任何功能。浅色还是深色下，对话、工具调用、设置全部一样用。

Part 7 · 进阶与 FAQ

毕业篇：脱离界面的 CLI 玩法、安全边界、一个完整实战，外加常见问题答疑。

7.1 CLI 模式

你将学会 认识 dsh 的命令行玩法：一次运行、自定义配置、插件管理，脱离图形界面也能用。

图形界面之外，还有命令行

前面整篇文章都在讲 Web UI，但 dsh 不只有图形界面。dsh 命令本身是一个多模式启动器 ，除了 dsh web，还有几个有意思的模式。

四种入口模式

命令	干什么	适合
dsh web	启动图形界面（整篇文章的主角）	日常交互
dsh --profile headless "任务"	跑一次任务，打印结果后退出	自动化、脚本、CI
dsh --profile <名字>	启动指定配置档案	自定义场景
dsh plugin --profile <名字> <参数>	管理该档案的插件	插件安装维护

headless：一句话跑完一个任务

最有意思的是 headless 模式。它不需要界面，一条命令把任务干完就退出：

dsh --profile headless "总结当前目录下这个项目的结构"

跑完后终端里直接打印 agent 的回答，适合写进脚本、定时任务、CI 流水线。可以把它理解成 dsh 的"命令行版"。

profile：你的专属配置档案

dsh 用 profile 管理不同的运行配置。每个 profile 是一套独立的插件组合和配置：

• web 和 headless 是内置的，首次使用自动初始化
• 其他 profile 通过 dsh plugin 命令创建
• 每个 profile 有自己的插件、补丁和配置，互不干扰

运行 headless 需要什么

和图形界面一样需要模型密钥。headless 模式通过环境变量读取：

export DEEPSEEK_API_KEY="你的密钥"
dsh --profile headless "任务"

7.2 权限预设与沙箱

你将学会 把 4.4 节的权限机制往深挖一层：理解沙箱的三个档位、权限预设怎么捆绑它们，以及 Windows 上的实际边界。

权限预设：一个档位，管两件事

4.4 节讲了权限模式。现在把背后的机制说透：每个权限预设实际上捆绑了两件独立的事：

1. 沙箱模式：agent 的命令在文件系统上能做什么
2. 审批策略：超范围操作是问你还是直接拒绝

界面上的一个档位，背后就是这两个开关的组合。

沙箱的三个档位

沙箱只管理文件系统效果，三个档位由松到严：

模式	允许什么	典型用途
danger-full-access	不设限制，想碰哪碰哪	需要全局操作
workspace-write	工作区目录 + 临时区可写	日常干活
read-only	只读，禁止写入	只看不动

注意：沙箱只管文件读写。网络访问、进程可见性不归沙箱管，那是另一套机制。

审批策略的两个档位

• ask：超范围操作先问你，允许只放行这一次
• never：不问，直接拒绝。无人值守场景宁可干不成也不冒险

预设怎么组合

界面上的权限选择器，背后就是这些组合：

界面档位	沙箱	审批
Read Only	read-only	ask
Workspace Write	workspace-write	ask
Full access	danger-full-access	never

看出规律了吗？档位越高，沙箱越松；Full access 连审批都直接关了。这就是为什么 4.4 节强调 Full access 要慎用。

沙箱在不同系统上的实现

沙箱的"护栏"由操作系统机制实现：

• Linux：bwrap 或 Landlock
• macOS：Seatbelt
• Windows：ACL 受限令牌

不同系统的护栏强度有差异，某些边界（比如硬链接）可能只能做到"部分限制"。对日常使用来说，记住一条：只读和写工作区内，是最常见也最稳妥的组合。

实践建议

• 日常用 Workspace Write（workspace-write + ask），能干活的底限配置
• 只查不改切 Read Only
• Full access 只在明确需要时用，用完全即切回
• 自动化和无人值守场景才考虑 never 审批

7.3 完整实战

你将学会 把全文知识串起来，走一遍完整的实战流程：从装好环境到让 dsh 完成一个真实项目任务。

实战任务

这一部分我们完成一个真实的小项目任务：给一个已有项目生成一份 README。它用到全文的主线能力：工作区、会话、工具调用、目标、审阅。

任务目标：

分析当前工作区的项目，生成一份 README.md，包含项目简介、主要功能和使用说明。

第一步：确认环境

开工前确认三件事，缺一不可：

1. 环境：dsh 已经启动，浏览器能打开界面（0.2 节）
2. 模型：顶部状态区显示可用的模型（1.1 节）
3. 工作区：侧边栏已有你的项目工作区，输入框可用（2.2 节）

三样都齐，开始。

第二步：新建会话，设定目标

点新会话，先设定目标，防止 agent 跑偏：

设定目标：为当前工作区的项目生成 README.md，只做这一件事。

第三步：发出任务指令

把任务说清楚：

分析这个项目是做什么的，然后生成一份 README.md，包含项目简介、主要功能和使用说明。先读一下项目的关键文件再动笔。

注意指令里的三个要点：做什么 （生成 README）、产出在哪 （README.md）、怎么干（先读关键文件再动笔）。指令越具体，结果越可控。

第四步：观察它干活

发送后，盯住消息流的工具调用树（3.2 节）：

• Pwsh / Bash：列目录、看文件
• Glob：找 README、package.json、源码入口
• Read：读关键文件，了解项目
• Think：组织 README 的结构

整个过程你可能看到它反复"读一下、想一下、再读一下"，这是正常的，它正在理解你的项目。

第五步：审阅结果

agent 完成后，对话区出现 README 的草稿，工作区里多了 README.md 文件。别急着收工，做两件事：

1. 看文件：打开 README.md 检查内容，简介、功能、使用说明是不是都到位了
2. 提修改：不满意就直接说，比如"把使用说明写详细点，加一个安装步骤"，agent 会改

第六步：收尾

满意后，这单任务就完成了。你可以：

• 顺手做一次总结："总结一下这次任务的过程"（顺便看看轨迹视图，7.4 节讲过怎么切）
• 把会话归档（5.1 节），保持侧边栏干净
• 开新会话，干下一件事

这个实战用到了什么

环节	用到的能力	章节
环境确认	启动、模型、工作区	Part 0-2
防跑偏	目标	4.5
指挥干活	会话与指令	Part 3
观察过程	工具调用树	3.2
安全边界	权限模式	4.4
收尾管理	归档、轨迹	5.1、4.10

一本教程的主线，在这个小任务里全部用上了。

扩展：进阶实战方向

做完这个小任务，你可以往这些方向继续：

• 计划模式跑大改造（4.6 节）：重构前先让 agent 出方案
• 子代理并行调研（4.7 节）：多方向同时查
• 后台任务跑长活（4.8 节）：构建、批量处理不堵对话

7.4 常见问题

你将学会 把全文出现过的问题汇总成一张速查表，遇到坑先来这里翻。

安装与启动

问：npx 下载很慢或失败？

检查网络和代理。可以临时换 npm 国内镜像：

npm config set registry https://registry.npmmirror.com

问：端口被占用怎么办？

换端口启动：

npx @deepseek-ai/dsh web --port 8080

然后访问 http://127.0.0.1:8080/。

问：node -v 版本太老？

dsh 需要 Node.js 22 及以上。去官网下载最新 LTS 覆盖安装即可。

问：浏览器打不开界面？

以终端打印的地址为准。确认端口一致，终端没报错，再刷新一次。

配置模型

问：保存后模型不可用，提示密钥无效？

密钥可能没复制全（sk- 开头一整串），或刚创建还没生效。到 DeepSeek 平台重新创建一个试试。

问：提示余额不足？

DeepSeek 按量付费，新账号可能需要充值。到平台费用页查看。

问：想用别的模型？

设置 → 模型 → 添加提供方（内置 20 多家），或添加自定义提供方接 OpenAI 兼容服务（1.2 节）。

问：API 密钥泄露了怎么办？

到 DeepSeek 平台吊销重建，旧密钥立即失效。别把密钥截图发群里、提交到 git。

工作区与会话

问：添加了工作区但侧边栏没有？

确认选的是文件夹不是文件。同一目录只能添加一次。

问：删了工作区文件会丢吗？

不会。删除只是移除分组记录，文件与会话都保留。

问：会话太多找不到？

用侧边栏搜索框，按标题或内容搜。不用的会话归档（5.1 节）。

问：想回到昨天的对话继续干？

点侧边栏会话行，历史完整加载，直接续聊。

运行与结果

问：agent 跑偏了？

先设目标（4.5 节）再发任务，跑偏了直接说"停，回到目标上"。也可以用计划模式先审方案（4.6 节）。

问：agent 运行太久？

看工具调用树它卡在哪一步。长任务让它放后台（4.8 节），或者指令里限定范围。

问：agent 的回答不满意？

先换更强的模型（4.1 节）或调高推理等级，再检查指令是否足够具体。指令含糊，结果必然含糊。

问：agent 老是弹审批？

说明它想动工作区以外的东西。看清操作内容再决定：该放行的放行，不该放行的拒绝（4.4 节）。

界面与视图

问：对话视图和轨迹视图什么区别？

对话视图是人话版，轨迹视图是原始轮次记录（USER/CONTEXT/ASSISTANT/TOOL），排查细节用轨迹（4.10 节）。

问：界面是英文，想换中文？

设置 → 通用设置 → 语言 → 中文。

问：界面太亮/太暗？

设置 → 通用设置 → 外观，选浅色/深色/跟随系统（6.4 节）。

进阶

问：怎么在无人值守时跑任务？

用 headless 模式（7.1 节）：

export DEEPSEEK_API_KEY="你的密钥"
dsh --profile headless "任务"

问：想限制 agent 的权限更严一点？

切 Read Only 模式（只读），或保持 Workspace Write 并在审批时拒绝超范围操作（7.2 节）。

问：想给 dsh 加新能力？

装插件或技能。插件在设置 → 插件查看，技能在会话里用 / 调用（4.3、6.2 节）。写自己的插件属于开发进阶，官方文档有专门教程。

结语

到这里，这篇教程就全部讲完了。回顾一下你走过的路：

• Part 0：认识 dsh，装好环境，看懂界面
• Part 1-2：配好模型，圈好工作区
• Part 3：发出第一条指令，看懂工具调用
• Part 4：点亮会话里的全部进阶功能
• Part 5-6：管好会话，调成自己的形状
• Part 7：了解 CLI、安全机制，完成实战

从"dsh 是什么"到"用 dsh 完成真实任务"，你已经完成了从零到一的跨越。接下来，去你的项目里让 agent 帮你干活吧。遇到问题，回来翻这篇教程。

---

写在最后

关于作者

万绍业（万少）：华为 HDE（HUAWEI Developer Experts）、华为云 HCDE（Huawei Cloud Developer Experts）、51CTO 鸿蒙开发者社区核心专家，HarmonyOS 应用开发者高级认证，鸿蒙应用开发培训讲师，十年互联网全栈开发经验，持续输出 AI 与鸿蒙生态实战内容。

我们下篇文章再见。