2026 年 8 月 13 日，DeepSeek 正式发布首款 Agent 产品 DeepSeek Harness（dsh），以 MIT 协议全面开源，直接对标 Claude Code 与 Codex。本文基于官方设计与早期社区实践，系统拆解 dsh 的核心概念、环境搭建、图形界面、进阶功能与 CLI 玩法，带你从零完成一次真实项目任务。

---

前言：为什么 Harness 值得你花一个晚上

过去两年，大模型从"对话框里的助手"一路演进到"能动手干活的 Agent"。但真正把 Agent 落地到开发者日常工作流里的产品，并不多。

Claude Code 证明了"让 AI 在真实代码库里读写执行"这条路走得通；Codex 证明了"规模化后台任务"有价值。但两者要么是闭源商业产品，要么与特定生态深度绑定，社区很难在其上自由扩展。

DeepSeek 这次的开源动作，信号很明确：把 Agent 的"驾驶舱"交给社区。MIT 协议意味着你可以商用、可以改、可以嵌入自己的产品。内测期间 769 位开发者报名、约 300 个社区插件冒出来——这个数字说明，生态的自驱力已经起来了。

所以这篇文章的目标很朴素：帮你在一个晚上之内，从"听说过 dsh"变成"能用 dsh 完成真实任务"。

我会按照"概念 → 安装 → 界面 → 进阶 → CLI → 实战"的顺序讲。你不需要是 TypeScript 专家，也不需要懂 Agent 框架原理，只要会装软件、会敲命令就行。

---

第一部分：重新理解 dsh——它不是"另一个聊天框"

1.1 dsh 到底是什么

dsh 的全称是 DeepSeek Harness，由 DeepSeek AI 开源。官方给它的定位是 Agent Harness——翻译成人话，就是"智能体运行框架"。官网地址：https://www.deepseek.com/harness/

如果用一个比喻：dsh 是你 AI 助手的操作系统层。它不直接"生产智能"，而是提供让智能体能够：

• 读写你电脑上的文件
• 执行命令、跑脚本
• 调用各种工具（搜索、子代理、工作流）
• 按流程、按权限、按目标持续干活

一句话：网页版 ChatGPT 是"你问它答"，dsh 是"你派它去干"。

1.2 它和网页版、IDE 插件的区别

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

维度	网页版 ChatGPT / 官方对话	IDE 内 AI 插件	dsh
工作位置	封闭对话	编辑器内	你的真实电脑 / 服务器
能读文件？	需手动粘贴	当前项目	任意指定工作区
能跑命令？	不能	有限	完整终端能力
权限控制	无	插件决定	细粒度沙箱 + 审批
可扩展性	官方功能	Marketplace	MIT 开源 + 插件体系
适合场景	问答、写作	写代码辅助	端到端项目任务

看出差别了吗？dsh 的工作对象是你真实的文件系统，而不是一段被粘贴进来的文本。 这个区别决定了它能做的事情量级完全不同。

1.3 dsh 能帮你干哪些活

装好之后，你可以让 dsh 承担这些类型的任务：

• 代码工程：读懂一个陌生仓库、定位 Bug、重构模块、补测试、生成 README
• 自动化脚本：批量处理文件、定时跑数据清洗、生成报告
• 调研与汇总：并行调研多个信息源、交叉验证、输出结构化结论
• 运维辅助：在受控环境里跑命令、排查日志、部署验证
• 工作流编排：把"拉数据 → 清洗 → 生成 → 发布"这种固定套路写成可复用的流水线

关键是：它工作在你的真实电脑上，读的是你的文件，跑的是你的命令。 也因此——权限和安全是 dsh 的一等公民，后面会专门讲。

1.4 两条前置认知

不多，两条就够：

1. dsh 本身不生产模型。它负责调度、干活；真正"想问题、写代码、回话"的是背后的大模型服务（默认 DeepSeek，也可接其他 OpenAI 兼容服务）。
2. 一切动手都基于"工作区"。没有工作区，agent 就不知道你的文件在哪，自然没法干活。这是贯穿全文的核心概念。

理解了这两点，后面所有设计都会显得顺理成章。

---

第二部分：十分钟搭好环境

2.1 你需要装什么

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

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

2.2 安装 Node.js

去 Node.js 官网 下载 最新 LTS 版本，一路下一步安装即可。

⚠️ 版本要求：dsh 处于预览阶段，要求 Node.js 22 及以上。如果你机器上是老版本，请升级再继续。

装完后打开终端验证：

node -v
npm -v

看到类似下面的版本号，说明装好了：

v24.11.1
11.6.2

2.3 启动 dsh

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

npx @deepseek/harness web

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

Harness web UI running at: http://127.0.0.1:3080

想先装好再启动？ 也可以全局安装：

npm install -g @deepseek/harness
dsh web

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

2.4 打开界面

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

http://127.0.0.1:3080/

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

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

2.5 常见问题速查（先收藏）

问题	解法
npx 下载很慢 / 失败	检查网络或代理，可临时换 npm 国内镜像：npm config set registry https://registry.npmmirror.com
端口被占用	换端口启动：dsh web --port 8080，然后访问 http://127.0.0.1:8080/
node -v 版本太老	去官网下载最新 LTS 覆盖安装
浏览器打不开界面	以终端打印的地址为准，确认端口一致、终端没报错，再刷新

---

第三部分：认识主界面——每一个角落都有讲究

3.1 整体布局

打开 http://127.0.0.1:3080/，界面从上到下、从左到右分四个区域：

┌──────────────────────────────────────────┐
│  [+新会话]  工作区列表      [设置 ⚙️]     │  ← 顶部状态栏
├──────────┬───────────────────────────────┤
│          │  对话区（工具调用树 / 轨迹）     │
│  侧边栏  │                               │
│  - 工作区 │                               │
│  - 会话   │                               │
│          │  ┌─────────────────────────┐  │
│          │  │ 输入框（附件 / / / @）   │  │
│          │  └─────────────────────────┘  │
└──────────┴───────────────────────────────┘

• 左上角：新会话按钮。每点一次开一个独立对话，上下文互不干扰。
• 左侧边栏：工作区与会话导航。目前只有一个"工作区"入口——这是 dsh 最核心的概念。
• 中间：对话区。你的指令、agent 的回复、它调用工具的每一步，都在这里滚动展示。
• 底部：输入框。给 agent 下指令的地方。注意它现在是锁定的——因为还没选工作区。
• 右上角：设置按钮。点开有四个 tab，后面逐个用到。

3.2 第一道必做配置：填 API 密钥

界面什么都好，但还缺一样东西：大脑。

dsh 自己不生产模型，真正"想问题、写代码、回话"的是背后的模型服务。所以开工前必须先告诉 dsh：用哪家的模型、用什么密钥。

第一步：去 DeepSeek 平台拿密钥

注册并登录 DeepSeek 开放平台，在"API Keys"里创建一个新密钥。

⚠️ 密钥只显示一次：创建后完整字符串只在页面上出现一次，关闭就看不到了。请先复制到安全地方再关页面。

第二步：在 dsh 里填写

回到 dsh 界面，点右上角设置 → 模型 tab。页面上会列出已预置的 DeepSeek 提供方。把密钥填进去，保存。

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

回到主界面，看对话区上方的模型状态：如果显示 DeepSeek-V4-Flash（或你选的模型名），就说明配置成功了。此时还可以点开它切换其他模型。

第三步：安全提醒

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

• 不要截图发群里、不要提交到 git
• 泄露后立刻去平台 吊销重建，旧密钥立即失效

3.3 接入更多模型（OpenAI 兼容）

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

① 内置提供方：dsh 预置了 20 多家主流模型服务，填密钥即可用。流程与 DeepSeek 完全一致。

② 自定义提供方（OpenAI 兼容）：这是给"标准 OpenAI 兼容接口"准备的。只要你的服务实现了 OpenAI 的接口协议，就能被 dsh 识别。典型场景：

• 本地跑的开源模型（Ollama、vLLM）
• 公司内部的模型网关
• 第三方中转 / 代理服务

点"添加自定义提供方"，填几个字段：

字段	说明
Base URL	服务地址，如 http://localhost:11434/v1
API Key	服务密钥（本地服务可为空）
模型列表	该服务提供的模型名

以最常见的 Ollama + qwen2.5:7b 为例：

Base URL: http://localhost:11434/v1
API Key:   (留空)
Models:    qwen2.5:7b

保存后，主界面的模型选择器里就能看到"本地 Ollama"了。

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

---

第四部分：工作区——Agent 干活的"地盘"

4.1 为什么必须有工作区

想象你雇了一位远程助理：他要帮你干活，第一件事是什么？ 告诉他你的项目在哪。否则他不知道去哪个文件夹翻文件，也不知道改完的东西放哪。

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

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

1. 目录路径
2. 显示名字
3. 属于它的会话清单

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

因为 dsh 所有的"动手"都建立在工作区上：读文件、跑命令、写代码——都得有个根目录。不选工作区，agent 就没有"地盘"，输入框就是锁着的。

4.2 添加你的第一个工作区

界面上有两个添加入口（侧边栏顶部 + 工作区分区），殊途同归，都会打开系统目录选择器。

选哪个目录合适？

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

选好目录后，dsh 会自动完成两件事：记录路径、创建该工作区下的初始会话。

回到主界面，左侧边栏工作区分区下已经出现了你的项目目录名。同时你会发现：底部输入框解锁了。

4.3 工作区操作

鼠标悬停在工作区行上，会出现操作菜单：

• 重命名：改显示名（不改实际目录）
• 删除：移除工作区记录（不删文件、不删会话，会话归入"未分组"）
• 切换：点工作区名即可，对应会话列表会跟着切换

如果你有多个项目，就再走一遍添加流程，每个项目一个工作区。每个工作区互相独立，会话不会串。

⚠️ 注意：同一目录只能添加一次；添加的是"文件夹"而不是"文件"。

---

第五部分：发出第一条指令，看 Agent 怎么干活

5.1 新建会话 + 发指令

点左上角 新会话 按钮，创建独立对话。底部输入框已经可用，提示语是"描述你想要构建的内容"。

第一次用，推荐这种只读、安全、立刻见效的指令：

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

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

按 Enter 发送，你会看到两件事同时发生：

1. 你的消息出现在对话区
2. 下方开始出现工具调用记录（先"思考"，再"执行"）

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

完成后，对话区留下完整记录：你的问题、它调用工具的每一步、最后的回答。底部还有一行统计信息（耗时、工具轮次、token 消耗）。

5.2 读懂"工具调用树"

普通聊天里，AI 给你一段文字就结束了。但 dsh 的 agent 要真正动手，所以它每做一步，界面就多一行记录——这些记录串起来，就是 工具调用树。

一条典型流程（从下往上看）：

[Think]     理解指令：需要列出工作区文件并判断项目类型
[ReadDir]   读取工作区根目录
[ReadFile]  打开 package.json
[ReadFile]  打开 README.md
[Think]     综合信息：这是一个 Next.js 博客项目
[Reply]     向用户汇报结论

看到规律了吗？agent 的干活节奏是：想一下 → 动一下 → 看结果 → 再想 → 再动。

每一行都可以点开展开，看完整内容：

• 点开 Think：看到当时的思考过程
• 点开 Pwsh / Bash：看到实际执行的命令和输出
• 点开"上下文注入"：看到注入的提示词内容

想确认 agent 到底对你的项目做了什么？逐行点开看，一切透明。

常见内置工具有：ReadFile（读文件）、WriteFile（写文件）、ReadDir（列目录）、Bash / Pwsh（执行命令）、Grep（搜索内容）、WebSearch（联网搜索）等。工具越多，agent 能干的事越多。

5.3 读懂统计行

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

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

拆解一下：

部分	含义
1 轮 · 4 步	1 轮对话，共 4 次工具调用
LLM 14.9s	模型"思考"耗时
工具调用 45.5s	实际执行（读文件、跑命令）耗时
缓存命中 71%	输入缓存命中率，越高越省钱越快
输入 76K tok · 输出 1.6K tok	本次 token 消耗

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

---

第六部分：会话里的十个进阶功能

6.1 切换模型 + 推理等级

配置好模型后，dsh 默认用你配置的那个。但不同任务适合不同模型：

• 简单问答 → 轻量 Flash 模型（快、便宜）
• 复杂重构 → 强推理模型（慢、准）

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

入口有两个：对话区上方的模型状态区，或输入框左侧的模型选择器。点开后：

• 模型：列出所有已配置且可用的模型，点一下立即生效
• 推理等级：控制"想多深"，一般是 High / Medium / Low

档位	适用场景
High	复杂架构、难 Bug、多约束任务
Medium（默认）	日常开发主力
Low	简单问答、快速确认

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

6.2 给 Agent 喂附件

有些场景纯文字说不清楚——比如"帮我看下这份报错截图"“基于这份设计稿改代码”。这时候用附件：

添加方式和聊天软件一样：直接拖拽文件到输入框，或点附件按钮选择文件。成功后输入框上方出现缩略图 / 文件条，确认后正常发送即可。

dsh 支持常见类型，实践中用得最多的是：截图 / 图片、PDF、Excel/CSV、日志文件、设计稿。

⚠️ 大文件处理：文件过大会挤占上下文。如果是一整个项目，更推荐把项目目录设为工作区（让 agent 自己读），而不是压缩上传。能靠工作区读的文件，就不用附件传。

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

6.3 斜杠命令 / 与引用 @

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

① 斜杠命令 /

在输入框敲 /，弹出命令列表（内置命令 + 你安装的技能）。选一个，它就以"让 agent 用这个技能干活"的方式加入指令。

举例：装了视频制作类技能后，输入 / 选它，再补一句"把这个网址做成一条介绍视频"，agent 就按该技能的工作流执行。

好处：把复杂能力变成一句话。

② 引用 @

在输入框敲 @，弹出引用面板。作用是**"点名"某个东西参与对话**。可引用的包括：工作区文件、已有会话、已安装的技能、子代理等。

引用比斜杠更灵活，可以夹在句子里用：

用 @视频制作技能 把这份 @设计稿.png 翻译成英文版介绍

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

6.4 权限模式与审批机制

agent 在你电脑上干活，总要有边界。dsh 用权限模式管这件事。

输入框左侧有访问模式按钮，点开弹出权限选择器。档位从低到高：

档位	含义
Read Only	只读，不写文件、不执行命令（最安全）
Workspace Write	可读写工作区内文件，工作区外需审批（日常推荐）
Full Access	放行一切操作，包括工作区外（慎用）

切换即时生效，只影响之后的操作。

审批弹窗：即使设好了模式，agent 遇到"超权限"操作时，dsh 会停下来弹出审批卡片，写明了它想改哪个文件、跑什么命令、访问什么地址。看清了再决定。

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

日常使用保持 Workspace Write + ask 就好。never（永不询问）主要给自动化 / CI 场景用。

6.5 用"目标"锁定方向

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

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

不需要特殊按钮，直接在对话里说就行：

# 方式一：和任务一起说
本次会话的目标是：修复登录页在手机端显示错乱的问题。现在开始排查。

# 方式二：任务中途补设
设定目标：先把登录页 Bug 修完，其他优化都先不做。

dsh 会把目标记下来，界面显示当前目标状态。agent 每一步都会对照它。

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

6.6 计划模式：先审方案再动手

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

• 破坏性改动（删数据、改数据库结构）
• 多步骤、高风险的部署
• 需要你先确认思路的大重构

计划模式就是干这个的：让 agent 先交方案，你点头，再动手。

用斜杠命令控制：

/plan            # 进入计划模式
/plan 重构用户模块的鉴权逻辑   # 带任务进入计划模式
/exit-plan       # 退出计划模式

进入后，你发一个任务，agent 会：

1. 先思考整体思路
2. 输出分步计划（每步干什么、影响哪些文件）
3. 等待你审阅确认
4. 批准后按步骤执行，每步严格按计划走

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

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

6.7 子代理：把任务拆给"组员"并行干

有些任务天然适合分工：

• “调研 3 个方案的优缺点”
• “同时改前端 + 后端 + 文档”
• “并行跑 5 组测试”

子代理就是 agent 委派出去的子 agent：主 agent 拆任务 → 分配给子代理并行执行 → 最后汇总给你。相当于项目经理 + 组员。

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

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

你会在消息流里看到子代理行，展开后是子代理自己的完整对话记录。

💡 适用判断：子代理适合"拆得开、各干各"的任务。任务紧密耦合、改一处影响全局的（如改公共类型定义），反而适合交给一个 agent 从头做，避免不一致。

6.8 后台任务：耗时活丢到后台

agent 有些活很慢：跑全量测试、批量处理、长时间调研。如果让它一路干完，你的对话就一直"转圈"，期间想干别的都不行。

后台任务就是解法：把耗时任务放后台跑，对话立刻恢复可用，完成后再回来收结果。

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

你会看到会话头部出现后台任务列表，实时显示每个任务状态。任务跑完后，agent 把结果汇报到对话里，你也可以随时从列表查看。

常见后台任务类型：命令行任务、子代理任务——统一由后台任务系统管理。

6.9 工作流：把流程编排成脚本

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

比如你有个固定套路：拉取数据 → 清洗 → 生成报告 → 发布。每次都靠手发指令太累。

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

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

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

6.10 轨迹视图：从原始记录回看每一步

对话区顶部有两个视图 tab：对话 和 轨迹。

• 对话视图：整理成清晰消息流，日常够用
• 轨迹视图：按轮次组织的原始记录（USER / CONTEXT / ASSISTANT / TOOL），排查细节用

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

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

---

第七部分：侧边栏——会话的总控台

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

7.1 新建与切换

• 新建：点侧边栏顶部的 [+] 按钮
• 切换：直接点对应会话行，对话区加载完整历史，从头到尾可翻看、可续聊

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

7.2 搜索

会话多了靠翻很累，用搜索框（支持按标题和内容搜）。标题搜不到就搜内容。

7.3 会话操作

鼠标悬停在会话行上，出现操作按钮：

操作	作用
重命名	改会话标题，方便检索
分叉（Fork）	⭐ 从当前位置复制出新会话，原会话原样保留——做实验、试不同方案特别好用
归档	不用的会话收起来，列表更清爽
删除	彻底删除（谨慎）

🌟 分叉是神器：它不动原会话，从你选的位置复制出新分支。想"试试另一种思路又不破坏现有进度"时，先分叉。

7.4 视图选项

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

---

第八部分：设置——把 dsh 调成你的形状

点右上角设置按钮，弹出设置面板。四个 tab：通用、插件、Agent 预设、模型。

8.1 通用设置

选项	说明
Agent 预设	新会话的 agent 类型（见 8.3）
权限	新会话默认权限模式（推荐 Workspace Write）
语言	界面语言，支持中文，切换立即生效
外观	浅色 / 深色 / 跟随系统
Enter 行为	agent 繁忙时按 Enter 怎么办（默认"排队发送"）

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

8.2 插件

设置 → 插件 tab，列出当前部署已安装的插件及其配置项。它们是 dsh 能力的地基，例如：

• 终端插件：给命令执行兜底，可配置执行范围、是否启用沙箱——是安全边界的一部分

你可能想问：插件和 6.3 的技能（Skills）是一回事吗？

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

• 插件：底层能力模块，在设置里管理（如终端、文件系统、搜索）
• 技能：面向任务的可调用工作流，在会话里用 / 调用

它们是 dsh 插件体系的两个侧面。

8.3 Agent 预设

同一个 dsh，agent 可以有不同的"形态"。Agent 预设就是这些形态的出厂配置。

内置四个预设，能力从全到简：

预设	定位
标准模式	功能完整的编码 Agent（大多数人的日常选择，默认）
精简模式	去掉部分工具，适合轻量任务
只读模式	只观察不改动，适合调研
创造模式	可自定义、可扩展，进阶玩法

切换路径：设置 → Agent 预设 → 点选。切换后新会话生效（已有会话不受影响）。

创造模式还支持自定义预设——对 agent 行为有特殊要求时（比如固定系统提示词、限制可用工具集），可以自己创建一个。属于进阶玩法，先知道有这条路。

8.4 主题

通用设置 → 外观：浅色 / 深色 / 跟随系统。切换立即生效，不用重启。

纯看习惯：长时间盯代码推荐深色护眼；如果拿不准，选跟随系统——自动匹配你电脑的明暗风格，最省心。主题只影响外观，不影响任何功能。

---

第九部分：脱离界面的 CLI 玩法

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

9.1 Headless 模式：无人值守跑任务

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

dsh run "分析当前目录的代码结构，生成一份架构说明文档"

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

9.2 Profile 管理

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

dsh --profile work run "..."
dsh --profile personal web

这样你可以在"工作账号"和"个人项目"之间干净地隔离。

9.3 环境变量传密钥

headless 模式通过环境变量读取密钥（不依赖图形界面的设置面板）：

export DEEPSEEK_API_KEY="sk-xxx"
dsh run "..."

这也是它能嵌入 CI 的原因——密钥从环境变量注入，不落盘。

9.4 插件管理命令

dsh plugin list      # 列出已装插件
dsh plugin install <name>   # 安装插件
dsh plugin enable <name>    # 启用插件

---

第十部分：安全边界——权限机制再深挖一层

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

1. 文件系统沙箱范围（能读写哪些目录）
2. 审批策略（超范围时是询问还是放行）

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

10.1 沙箱的三个档位

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

档位	文件读写范围
Read Only	只读，任何位置都不能写
Workspace Write	可读写工作区内，工作区外只读
Full Access	全系统可读写

⚠️ 重要：沙箱只管文件读写。网络访问、进程可见性不归沙箱管，那是另一套机制。所以即便在 Workspace Write 下，agent 依然可以访问网络——这是设计如此（调研、下载依赖都需要）。

10.2 权限组合对照

界面档位背后的真实组合：

权限模式	沙箱	审批策略
Read Only	只读	一律拒绝写操作
Workspace Write	工作区内可写	工作区外操作 → 询问
Full Access	全开放	直接放行，不询问

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

10.3 沙箱的实现

“护栏"由操作系统机制实现（如文件系统权限、隔离目录）。不同系统护栏强度有差异，某些边界（如硬链接）可能只能做到"部分限制”。

日常使用记住一条就够：默认 Workspace Write（只读 + 写工作区内），是最常见也最稳妥的组合。

---

第十一部分：完整实战——为已有项目生成 README

理论讲完，现在把全文知识串起来，走一遍真实小项目任务：给一个已有项目生成一份 README。

这个任务用到了全文主线能力：工作区、会话、工具调用、目标、审阅。

11.1 任务目标

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

11.2 开工前确认三件事（缺一不可）

1. ✅ 已配置好模型（API 密钥有效）
2. ✅ 已添加工作区（指向目标项目根目录）
3. ✅ 权限模式为 Workspace Write（允许写文件）

11.3 Step 1：新建会话 + 设目标

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

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

11.4 Step 2：发任务（指令要具体）

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

注意指令里的三个要点：

• 做什么：生成 README
• 产出在哪：README.md
• 怎么干：先读关键文件再动笔

指令越具体，结果越可控。

11.5 Step 3：盯工具调用树

发送后，盯住消息流的工具调用树（5.2 节）。你会看到它反复"读一下、想一下、再读一下"——这是正常的，它正在理解你的项目。

典型流程：

[Think]     需要确定项目类型，先读清单文件
[ReadFile]  package.json
[ReadFile]  src/index.ts
[ReadDir]   src/
[Think]     这是一个基于 Hono 的 API 服务，含 3 个路由模块
[WriteFile] README.md
[Reply]     已完成，README.md 已生成

11.6 Step 4：审阅 + 调整

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

1. 审阅内容：打开文件看是否准确，项目名、命令、功能描述对不对
2. 不满意就改：直接在对话里说"安装命令应该是 pnpm 不是 npm，改一下"，agent 会就地修订

11.7 Step 5：收尾

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

• 继续让它"补一份 CONTRIBUTING.md"
• 分叉（7.3）出一条新分支试试不同 README 风格
• 归档这个会话，下次回来续聊

回顾一下：工作区、会话、工具调用、目标、审阅——全文主线能力，在这个小任务里全部用上了。

---

第十二部分：FAQ 速查表

全文出现过的问题汇总，遇到坑先来这翻：

问题	解法
npx 下载慢 / 失败	换 npm 国内镜像：npm config set registry https://registry.npmmirror.com
端口被占用	dsh web --port 8080，访问 http://127.0.0.1:8080/
node -v 版本太老	需 Node.js 22+，官网下载最新 LTS 覆盖安装
浏览器打不开界面	以终端打印地址为准，确认端口一致、无报错，再刷新
保存后模型不可用 / 密钥无效	密钥可能没复制全（sk- 开头一整串），或刚创建未生效，重建一个
提示余额不足	DeepSeek 按量付费，新账号可能需充值，去平台费用页查看
想用别的模型	设置 → 模型 → 添加提供方（内置 20+），或添加 OpenAI 兼容自定义提供方
API 密钥泄露	平台吊销重建，旧密钥立即失效；别截图发群、别提交 git
添加工作区但侧边栏没有	确认选的是文件夹不是文件；同一目录只能添加一次
删工作区文件会丢吗	不会。删除只是移除分组记录，文件与会话都保留
会话太多找不到	用侧边栏搜索框，按标题或内容搜；不用的归档
想回到昨天的对话	点侧边栏会话行，历史完整加载，直接续聊
agent 跑偏了	先设目标（6.5）再发任务；跑偏了直接说"停，回到目标上"；或用计划模式（6.6）
agent 运行太久	看工具调用树它卡在哪；长任务放后台（6.8），或指令里限定范围
回答不满意	换更强模型（6.1）或调高推理等级，再检查指令是否具体
老是弹审批	说明它想动工作区外的东西。看清操作再决定：该放行放行，不该放行拒绝（6.4）
对话视图 vs 轨迹视图	对话是"人话版"，轨迹是原始轮次记录（USER/CONTEXT/ASSISTANT/TOOL），排查细节用轨迹（6.10）
界面英文想换中文	设置 → 通用 → 语言 → 中文
界面太亮/太暗	设置 → 通用 → 外观，浅色/深色/跟随系统（8.4）
无人值守跑任务	用 headless：dsh run "..."（9.1）
想限制权限更严	切 Read Only，或保持 Workspace Write 并在审批时拒绝超范围操作（10.1）
想加新能力	装插件或技能。插件在设置 → 插件查看，技能在会话里用 / 调用

---

结语：从"问它"到"让它干"

回顾你走过的路：

dsh 是什么 → 装环境 → 认界面 → 发第一条指令 → 进阶功能 → CLI → 安全边界 → 完成真实任务

你已经完成了从零到一的跨越。

dsh 的真正价值，不在于它用了多强的模型，而在于它把"让 AI 在你的真实工作环境里、按你的规则、持续把一件事干完"这件事，变成了一套可控、可审计、可扩展的流程。

MIT 开源 + 插件生态，意味着它不会停留在今天这个样子。社区已经在冒出插件、工作流模板、预设配置——你现在上车，正好能参与它的演进。

接下来，去你自己的项目里，让 agent 帮你干第一件真实的活吧。遇到问题，回来翻这篇指南。

---

参考资料

• DeepSeek 官方开源仓库（GitHub）：https://github.com/deepseek-ai/deepseek-harness
• DeepSeek 开放平台：API 密钥管理与计费

---

本文基于公开资料与官方设计整理，版本迭代较快，具体以官方最新文档为准。如发现偏差，欢迎在评论区指正。