DeepSeek Harness（dsh）怎么用

0030 秒速览：三句话 + 按处境直接用

读完这篇你能做到一件事：在自己的电脑上把 DeepSeek Harness（一款开源的「智能体框架」，下面都叫它 dsh）跑起来，给它一个真实的小任务，并且在它动手之前就知道它会碰到哪些文件、花的是谁的钱、错了怎么回退。不需要你会写代码——但你要愿意在终端（那个能打字下命令的黑窗口）里复制粘贴几条命令。

按你的处境，直接用这个

一条可执行的上手路径（四步，约 20 分钟）

node -v

mkdir -p ~/Desktop/dsh-playground
cd ~/Desktop/dsh-playground
npx @deepseek-ai/dsh web

读完你应该能

• 用自己的话讲清它是怎么回事：一句话版本在 01，为什么需要它在 02。
• 分清四组最容易混的东西：它不是聊天框、dsh 不是网页版 DeepSeek、模式（Mode）不是模型、权限不是审批——对照在 01 与 16。
• 预判新手最容易踩的坑：输入框灰色、401/404、它改了你没让改的文件——15 一张表全列了。
• 拿你自己的场景举一个例子（这条只有你能验）：读完 13 的四份清单后，挑一件你手头真实的重复劳动，改写成「读 → 做 → 交」三段式，跑一次。跑不通就带着轨迹回来查 15。

01它到底是什么（先把四件容易混的事分开）

先说名字：「Harness」这个词到底指什么

Harness 直译是「马具、套具」——套在马身上、把马的力量接到马车上的那套东西。这个比喻正好是它的定位：模型是马，harness 是马具。马会跑（会思考、会写字），但马自己拖不动车；马具本身不会跑，可它让马的力气变成了真正的位移——读你硬盘里的文件、敲命令、上网查、跑错了再改，直到事情干完。

这个类比到这里就不准了：马具不会替马决定去哪儿，而 dsh 会替你拆解任务、安排先后、在危险动作前拦你一下。它更像「马具 + 车夫」的合体。

官方把这件事写成一句公式：Agent = Model + Harness（智能体 = 模型 + 马具）。仓库首页的副标题更直接：Everything is a Plugin（一切皆插件）。

正式一点的定义：DeepSeek Harness（命令名 dsh）是 DeepSeek 开源的一个「智能体框架」（智能体＝会自己动手干活的 AI）——MIT 协议开源，驱动它的是 Cordis 这个插件内核。你可以把它理解成一套「把只会说话的大模型接上手脚」的架子；官方顺手用这套架子拼了一个完整的编程助手，所以你也能拿它当一款 AI 编程工具直接用。

它不是什么（四个最容易搞混的错想）

它替你把哪一段接上了

记住这条分工，后面所有概念都能对号入座：凡是「思考」，都是模型的活；凡是「动手」，都是 harness 通过工具干的。它们之间那个「读文件 → 想 → 改 → 跑命令验证 → 再想」的小循环，官方文档里叫 agent loop（智能体循环）。

它和成品编程助手差在哪：一张表看完

「一切皆插件」落到使用上是什么意思

官方文档的原话是：模型、工具、技能、会话、沙箱、存储、循环、调度、界面……全部由插件（可以理解成「随时能装卸的能力包」）提供，由 Cordis 这个插件内核负责装载与依赖管理。想换掉某一块，改配置即可，不必改它的源码。

听起来抽象，但你平时只接触最外面那一层——网页界面里能切换的那几个模式（Mode）。每个模式本质就是「一套挑好的插件组合」，也就是一份 preset（预置套餐）。这就是为什么同一句任务，切个模式结果可能不一样：不是模型变了，是它手上有哪些工具变了。

02没有它会怎样：搬砖的那一段到底是谁在干

同一件事，两种干法

它省掉的到底是哪一段

省掉的不是「思考」，是「在你和 AI 之间来回搬运」。上面右边那一列里，读文件、跑命令、看报错、再改，全都发生在同一台电脑上、同一个循环里，不需要你把报错复制回去。对完全不会编程的人，这一点的价值更实在：你不需要看懂报错——它自己看、自己改、自己重跑。你要提供的只是「想做成什么样」和「边界在哪里」。

它解决不了什么（这半屏很值钱）

• 它不会替你把需求想清楚。你说得含糊，它就干得含糊——写提示词的模板在 14。
• 预览版会变。官方 README 明确写着处于开发者预览阶段，「未来将出现破坏兼容性的变更」，命令与配置项都可能调整。
• 它会栽在细节上。社区实测的结论是「能扛重活，但会栽细节」：长任务要中途回来看看中间产物，别撒手就等（见 14）。
• 它不能替你保证结果对。最后一眼验收永远是你：文件在不在、内容对不对（06 给了「跑通」的三条定义）。

03什么场景该用它、什么时候别用

四类真值得上手的场景

三种别用它的情况

• 只说一句就想让它猜对复杂需求。先把需求写成「读 → 做 → 交」（模板在 13），再动手。
• 无人值守地干破坏性操作。删除、覆盖、大批量改动、涉及付款或对外发消息——这类必须有人在旁边把最后一道关。
• 要绝对稳定的生产系统。预览版会有不兼容变更；关键流程请固定版本、先备份配置（15）。

那它到底适合谁

• 适合：愿意尝鲜的 AI 爱好者；想搞明白「智能体到底怎么拼出来」的人；希望模型能自己换、不绑定某一家的人；想把手上的重复流程固化成一套预设的人。
• 暂不适合：追求开箱即用、生产环境零折腾的人——预览版迭代快，会有不兼容变更。

说句公平话：如果你只想尽快把活干完，Claude Code 那类成品工具通常更省心。dsh 的价值更多在「可组合、可定制、开源可控」——这篇教程默认带你把它当一款编程助手用起来，这部分体验已经完整。

04装它要几步：Node → Key → 装 → 起

动手前先认三个会反复出现的「命令行亲戚」

所以 npx @deepseek-ai/dsh web 读作：临时叫来 @deepseek-ai/dsh 这个包，然后执行它的 web 命令。带 @ 的写法表示「某个组织发布的包」——@deepseek-ai/dsh 就是 DeepSeek 官方发布的 dsh 包。

第一步：装 Node.js

node -v              # 看装了没、什么版本
brew install node     # macOS 上没装过才需要（Homebrew 是 macOS 的软件安装器）

能打印 v22.x、v24.x 之类就没问题。版本口径说清楚：官方仓库根目录的 package.json 要求 Node ^22.19.0 || >=24.0.0（这是从源码构建的门槛）；npm 包依赖里的原生组件要求 Node >=20。所以最稳的选择是装 Node 22 LTS 或更新。没有 Homebrew 就去 brew.sh 复制官方安装命令，或者直接去 nodejs.org 下 LTS 安装包双击安装。

Windows / Linux 也能跑：dsh 通过 npm 分发、以浏览器为界面，三个系统都支持。Windows 上装完若提示命令找不到，重开一次终端刷新 PATH（PATH 是系统「去哪里找命令」的目录清单）即可。

第二步：注册开放平台，拿一把 API Key

去 DeepSeek 开放平台（platform.deepseek.com）注册登录，在「API Keys」里创建一个，形如：

sk-2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p   # 形如（示例，不是真 Key）

创建时复制下来存好——平台一般只完整显示一次。

第三步：划一块试验田（工作区）

mkdir -p ~/Desktop/dsh-playground   # 在桌面建一个文件夹当试验田
cd ~/Desktop/dsh-playground          # 进入这个文件夹

（~ 就是你自己的用户主目录；mkdir -p 的意思是「建这个文件夹，已经存在也不报错」。）让 AI 动你的文件之前，先给它划一块地盘——它即使搞砸了也只砸在这一个文件夹里。

第四步：三条安装路线，先选一条别都装

# 路线一（推荐先试）
npx @deepseek-ai/dsh web

# 路线二（长期用）：装全局后，任意目录直接敲 dsh
npm install -g @deepseek-ai/dsh
dsh web

# 路线三（进阶，需先装 pnpm：brew install pnpm）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

怎么知道装好了：三步自检

启动后终端会打印一行 dsh web: 的地址，里面带一个一次性的访问令牌（一串临时口令，防止同网络里别人打开你的界面）。浏览器默认会自动打开；通过 SSH（一种远程登录另一台电脑的方式）启动时不会自动开，用 --no-open 也能明确关掉这个行为：

npx @deepseek-ai/dsh web --no-open   # 只跑服务，不自动弹浏览器

这个终端窗口要一直开着——关掉它 dsh 就停了；想主动停就按 Ctrl + C。

两个常见麻烦

05接上「大脑」：Key 填哪、模型怎么换

界面已经打开了，但它此刻「没有大脑」——还没有任何模型可用。你填进去的每一个动作，底层都落在两个文件里；万一界面按钮位置变了，知道去哪改就不慌：

# ~/.dsh/settings.yaml —— 主要配置文件（字段名以你安装版本为准）
# 这里能设默认用哪个提供方的哪个模型

# ~/.dsh/.credentials.yaml —— 你填的 Key 私有存放在这里
# 一般不需要手改

（~/.dsh 是 dsh 的用户数据目录；如果你设过 DSH_HOME 这个环境变量，它就会落在那个位置。）

界面法：设置 → 模型

想接别家的模型：自定义提供方要填哪几个字段

官方文档给的自定义提供方表单有意保持精简，只放开「让一条路由得以存在」的字段：

dsh 自带若干内置提供方可以一键添加（官方文档举的例子包括 anthropic、openai、Kimi 对应的 moonshotai、GLM 对应的 zai）。通过 OAuth（一种「用别家账号授权登录」的方式）登录的提供方目前暂不支持。多供应商并存之后，输入框右下角的模型选择器就是切换开关——同一个会话里也能换模型继续聊。

点「获取可用模型」报 401 / 404 怎么办

这多半不是你的错。有些网关不提供「列出可用模型」的接口，探测自然失败。官方文档说得很直白：探测只是便利手段不是保证，手动添加模型 ID 效果完全一样。401 / 403 则是另一回事——那是 Key 错误、过期或没开通该模型；模型 ID 打错也会报 404 / model not found，照服务商文档原样抄。这两种都要回平台查余额与权限。能聊天、但一让它调工具就报错多半与模型无关，去 15 按「启动 / 模型 / 工具」三层排障。

不花钱行不行：本机模型也能接

可以。dsh 是「接大脑的框架」：只要你在本机起一个按 OpenAI 格式说话的本地服务，就在设置里把它加成一个自定义提供方，基础 URL 指向本机端口（形如 http://127.0.0.1:11434/v1，具体看你本地服务怎么暴露），模型名写它起的那个。能力完全取决于你本地模型的水平。

06最小例子：从 hello.txt 到 summary.md

先约定「跑通」算不算数：三问

• 有产出吗？目录里出现了它说会生成的文件（比如 summary.md）。
• 只动了该动的吗？hello.txt 原文还在，没有多出奇怪的文件。
• 内容对得上吗？打开文件，内容确实基于它读到的东西写的。

三问全过，说明「命令 → 模型 → 工具 → 文件」整条链路通了。之后你想让它干什么，都是在这条链路上加需求而已。

五步跑通第一个任务

原则只有一条：第一次实验一定在专门的空文件夹里、用低风险任务。

cd ~/Desktop/dsh-playground
npx @deepseek-ai/dsh web

echo "今天是练习 DeepSeek Harness 的日子" > hello.txt

请先浏览当前文件夹里有哪些文件，读一下 hello.txt 的内容，
然后用中文写一份 summary.md 保存到当前目录，
总结你看到了什么。除了新建 summary.md，不要改动任何文件。

第一次就撞墙的三种情况

结果不满意：第二轮这样追着问

验收发现问题时，别只丢一句「不对」。给它具体信号，它才能快速收敛：

总结得还可以，但有两处要改：
1. 第一段太啰嗦，压缩成三句话
2. 把「文件清单」单独拆成一个小节，用列表展示
其它保持原样，直接修改 summary.md

注意最后那句「其它保持原样，直接改 X」——它给修改划了边界，防止模型顺手重写你本来满意的部分。

跑通之后，往三个方向延伸

• 让它干点实事：13 给了四份可以直接抄的任务清单。
• 学会控制它：14 是两套提示词模板和实测经验，15 是排错顺序。
• 玩高级的：切模式（08）、用轨迹复盘（10）、上命令行（11）。

07界面里的第一道闸：工作区

为什么输入框是灰的

几乎一定是没选工作区。官方指南写得很明确：全新打开的 Web 界面不会选中任何工作区，选中之前会话输入框不可用。点「选择工作区」，添加你启动 dsh 时所在的那个目录，再选中它，就能打字了。

界面大致分三块：左边是会话列表与工作区里的文件树，中间是对话与它滚动的动作流，右下角是模型选择、模式切换和设置入口。

为什么非要这么设计？因为工作区就是允许 AI 触碰的文件夹范围，也是你唯一真正需要操心的一条安全边界。它不只是「默认目录」——它后面还会决定沙箱能写哪里（见 09）。

界面里三块区域各管什么

它默认到底能看见哪个文件夹

官方文档：运行命令时所在的目录会成为默认的 workspace 根目录。所以「先 cd 进项目目录，再启动」是个好习惯；但 Web 界面里你仍然要显式选中它才会生效。工作区周边还挂着一份「项目列表」——最近打开过的目录和每个目录里跑过的会话，这就是你换项目的入口。

换项目时该怎么做

• 换工作区：在界面上方把工作区切到另一个文件夹。
• 顺手新开一个会话：让「一个会话只干一个项目的事」，逻辑最清爽，历史也更好翻。
• 别在一个工作区里塞两个不相关的项目：它会觉得整个目录都是它的地盘，检索和检索出来的东西都会变脏。

08四种模式：标准和极简到底差在哪

模式到底是什么

界面上能点的每个模式，官方叫 preset（预置套餐）：它规定「这个会话用哪些工具、带哪些提示词段落、能调哪些技能」。换句话说，模式不是模型的档位，而是工具和规矩的档位——换个模式，不是 AI 变聪明了，是它手上的牌换了。官方内置四套：standard、ptc、minimal、cordis，界面上分别显示为：

标准模式：默认就待在它里面

它就是「一套完整的编程助手」，官方文档的口径是「绝大多数任务用它」。旧版这篇教程给过一个体感数字——「能覆盖 90% 的场景」，那是个经验说法不是官方指标，但结论方向是对的：默认就待在里面，先别折腾。

它日常带的工具包括：读写编辑文件（改配置、补注释、生成文件）；跑终端命令（装依赖、跑测试、看目录）；glob / grep（按文件名模式找文件 / 按内容搜关键字，比如「找出所有写死 8080 的地方」）；联网搜索与抓网页（查一下最新用法再改）；调用技能（预先写好的操作规程）；先出计划；挂长期目标（跨会话记住「本周把这个项目跑上线」）；派子代理（它派出的小助手）并行干活；跑工作流。你要做的事只有一件：把任务说清楚。

PTC 模式：把「按十次遥控器」录成一段宏

PTC 是 Programmatic Tool Calling（程序化工具调用）的缩写。标准模式像遥控器——模型每按一个键你都看得见；PTC 像「把一连串按键录成宏再一次性执行」——模型写一段程序，程序里连着调好几个工具。它适合步骤固定、可预判的流程，比如「下载 → 解压 → 改名 → 打表」。官方文档说它的收益是「本来要五个来回，现在一次」，省的是往返，不是思考。所以别以为它一定更快：临时小任务切过去只会多一层理解成本。另外两种叫法你都可能见到——官方产品页早期把它叫 Code mode，现在叫 PTC，指的是同一件事。

极简模式：就一把锤子

只给一个持久终端工具，连系统提示词都被换成了固定的一句话，也不做上下文压缩。它的用途很明确：想让 AI 「别啰嗦、直接干」，或者要做模型对比测试时用它。旧资料里说它是「终端 + 一个文件编辑器两个工具」，那是更早版本的形态；本文校对的 0.1.5-rc.1 里，官方注释写的是「单工具」。

创造模式：给造工具的人的试验田

它和标准模式能力几乎一样，多出来的是运行时检查、插件实验和写 preset 的指导技能。官方推荐的自造流程是：先在创造模式里检查活着的运行时、在内存里试验插件组合 → 试满意了打包成一个组合包 → 挂到某个 profile 上变成常态。普通用户知道它存在就行，别在里面长时间待着。

30 秒选模式

两个新手一定想知道的问题

09它要动我的文件，怎么刹车

三层刹车，从外到内

1. 工作区——先划小地盘，别把整个桌面交出去（07）。
2. 沙箱模式——决定进程「能写哪些地方」，这一层由系统强制，不靠模型自觉。
3. 审批——每一个高危动作前，界面先问你要不要放行。

官方把前两者里最常调的沙箱与审批捆成一个选择器，叫权限预设。这三个词经常被混着说，下面逐层拆。

沙箱三档：它到底能写哪里

沙箱（Sandbox）指的是「把 AI 干活的进程关进一个围栏里，限制它能产生哪些文件改动」。官方定义了三档：

还有一条官方明确写在文档里的边界：沙箱只管文件系统效果，网络和进程可见性不在它的承诺范围内。所以「它会不会把代码传到网上」这类问题，沙箱档位回答不了。

审批两种策略：要不要问你

注意 never 不是「全都允许」，是「都不问、按拒绝处理」。这一点特别容易搞反。

权限预设：一个选择器把两档捆起来

在对话里可以用 /permission 查看或切换当前预设。如果当前组合不在预设表里，界面会显示一个派生的「custom」状态——它只能显示，不能选。

最后一道防线：动手前先做一个 Git 快照

前面的闸都是「防」，这一手是「兜」。允许 AI 改动某个目录前，先在里面存一个还原点（Git 是记录文件改动的版本管理工具，快照就是一次提交）：

cd ~/Desktop/dsh-playground
git init                                   # 把这个目录纳入版本管理
git add -A && git commit -m "初始状态"      # 先存一个起点（&& 表示前一条成功才跑后一条）

翻车了想还原：

git checkout -- .   # 把所有改动还原到上次提交的样子

这一手比任何界面设置都管用，也是社区老手的默认习惯。要更省心，就用「先只读跑一遍，确认行为正确，再放开写权限」的顺序。

10它干错了，怎么知道错在哪

轨迹是什么：一份只增不改的流水账

大多数 AI 工具只给你看「润色后的对话」。dsh 多给一层 Trajectory（轨迹）：它是一个会话里所有原始事件的账本，只追加、不修改。长得大概是这样：

# ===== Trajectory 视角下的片段（示意） =====
[system]   加载系统提示词（约 X tokens）
[user]     请把 hello.txt 改名为 greeting.txt
[think]    目标明确：只需一次 rename 工具调用
[tool]     调用 rename(from=hello.txt, to=greeting.txt)
[tool:ok]  返回：重命名成功
[tool]     调用 shell: ls
[tool:ok]  返回：greeting.txt
[finish]   任务完成，共 3 次工具调用，Token 消耗 N

（token 是模型计费与容量的小单位，可以粗略理解成「一个词或半个词」；上面的 N 只是示意，实际值看你的记录。）这条流水就是「它到底干了啥」的证据，比靠感觉猜靠谱得多。

轨迹里记了什么，各自能回答什么问题

一次翻车的标准复盘动作

轨迹能做的四件事

• 回放（Replay）：像看录像一样重看整个执行过程。
• 恢复（Resume）：中断或失败的任务，从中断点接着干。
• 分叉（Fork）：从历史某一步另起一个分支，试试不同做法。
• 检索（Search）：在事件流里搜关键词找线索。

界面上它是以「一轮一轮」分组的账本，还带一个时间总览；记录点开能看到 token 用量、耗时、输入输出、图片与附件摘要。历史很长时它会从最新的地方打开，往上翻才继续加载。

什么时候看对话、什么时候看轨迹

两个必须知道的边界

• 轨迹里可能有敏感信息。它记录模型看到的一切：文件内容、命令输出、配置上下文。要截图或导出会话发到网上之前，先检查有没有露出密钥、密码、隐私路径。
• 它也占空间、也拖慢对话。对话太长会变慢变笨，可以用 /compact 压缩历史，或者干脆新开一个会话、把关键结论带过去。换了一个完全不同的任务时，也应该新开会话，别让旧上下文干扰新任务。

11不开界面也能干：一次性任务与命令行

什么情况该走命令行

Web 界面适合人机互动。但如果你想让它在没人盯着的时候跑完一件事，就用一次性（headless，「无头」）模式——不开界面、跑完就退出。

一条命令跑完一件事

# 进入工作区 → 跑一次性任务 → 检查有没有产出
cd ~/Desktop/dsh-playground
dsh --profile headless "把当前目录的 .md 文件合并成 README.md，保留各自标题"
ls -la README.md   # 验证产物存在

命令的读法：--profile headless 表示用「无头」这套配置档（不开网页界面），后面整段中文就是任务。官方对无头模式的描述很干净：一次调用只跑一个任务，打印最终答案、然后退出；不开端口，也不留后台进程。它的边界同样干净——没有交互式追问，跑完就结束。

成没成，看退出码

另外，任务文本可以留空吗？不行——空白任务会在开始前就被拒绝。

无人值守的两条铁律

• Key 用环境变量注入，别把 sk-... 写死在任务文本或脚本里（脚本可能会进版本库）。
• 工作区用绝对路径，别依赖「当前在哪个目录」这种随缘状态——定时任务的工作目录常常不是你以为的那个。

还有一点可以放心：无头任务同样受权限与审批策略约束。撞到策略边界时它会停下来回报，而不是硬闯。

CLI（命令行界面）与 Web：同一件事的两种入口

规律很朴素：要交互、要看过程 → 用网页；要自动化、要可脚本化 → 用命令行。

12插件：给智能体加装备

「一切皆插件」在文件层面长什么样

官方文档把两个概念分得很清：组合包（bundle）是一个 npm 包，它多带一层配置补丁，回答「这个包贡献什么能力」；profile 是 $DSH_HOME/profiles/<名字> 下的一个目录，回答「这套配置由哪些组合包按什么顺序叠起来」。你写的、分发的叫组合包；用户用 --profile 启动的那个东西叫 profile。同一份东西不会既是这个又是那个。

这就是「一切皆插件」的落地方式：不是嘴上说说，而是文件层面真的能加、能换、能卸。给 dsh 加新能力不必等官方发版。

去哪找插件

• 官方核心：跟着 dsh 一起发布、默认就有的工具与技能——直接用，别折腾。
• 官方扩展 / 内置技能：仓库里有、但未必默认装（比如代码审查、找冗余之类），按文档用插件命令按需安装。
• 社区插件：给 GitHub 仓库打上 dsh-plugin 话题标签的，就是社区 dsh 插件，GitHub 上搜这个标签即可；插件通常也以 npm 包发布。
• 官方讨论区：GitHub Discussions 里能看到别人分享的插件与踩坑经验。

怎么装、怎么卸

插件是通过把命令转发给 pnpm 来管理的，所以写法就是「dsh plugin + 平时会敲的 pnpm 参数」：

dsh plugin --profile web add <插件包名或 GitHub 地址>   # 装到 web 这个 profile
dsh plugin --profile web remove <插件包名>               # 卸载

有个细节值得知道：装进去的包只有声明了「我是一个组合包」才会成为配置层；只是个普通库的话，命令会警告你一句「装成了普通依赖，没进配置层」。所以看到一个插件装了没效果，先看它是不是正经的组合包。

装完怎么确认生效

• 重启 dsh：Ctrl + C 停掉，再重新启动。
• 看列表有没有多出新条目：很多插件表现为多出一个模式 / 预设，或者多出几个工具。
• 开个小任务试它：让它用上插件宣称的能力，对照插件文档看结果对不对。
• 不对就卸：dsh plugin remove，或者去插件仓库提 issue。

怎么判断一个社区插件能不能信

想自己造：先在创造模式里试

官方推荐的工作流是：在创造模式的运行时里试插件组合 → 满意了打包成一个组合包 → 挂到某个 profile 上变成常态。文档里也写明了：每个自己写出来的 preset 都要当作可信配置来对待，因为它会授予它选中插件的能力。新手不必深究，记住「创造模式是插件试验田」就够了。

四个词的关系，一张表收尾

13四份可以直接抄的任务清单

下面全是「今天就能试」的真实任务，难度递增。建议都在临时文件夹里进行。

让它读别人写的项目

痛点：下载了一个开源小工具，全是英文说明，看不懂怎么用。做法：把项目放进工作区，让它读一遍，交一份中文说明书。

请阅读当前文件夹的项目：先看 README，再扫一眼代码结构。
用中文给我写一份说明.md，讲清楚：
1. 这个项目是做什么的
2. 需要什么环境、怎么跑起来
3. 主要文件各自的作用
不要修改项目里任何其他文件。

让它从零做一个单页小网站

痛点：想给朋友做个「咖啡店宣传单页」，自己完全不会写网页。做法：在空文件夹里让它直接生成，然后用浏览器打开成品。

在【当前文件夹】里帮我做一个咖啡店的一页式宣传网站 index.html：
- 店名「山风咖啡」，主打手冲，风格清新、米白 + 木色
- 包含：店名大标题、一句 slogan、菜单 3 栏、地址和营业时间
- 纯 HTML + CSS，不要任何外部 CDN，双击 index.html 就能在浏览器打开
做完后告诉我文件路径，以及我如何用浏览器打开它。

（提示词里那句「不要任何外部 CDN」的意思是：页面的样式不要从网上别人的服务器加载，只用一个本地文件，双击就能离线打开。）验收时双击 index.html 就能看效果。不满意就继续追问，比如「菜单改成 4 栏、主色换成偏绿的」——它会在同一个文件上迭代。

让它整理一堆乱文档

痛点：下载文件夹里几十个文件乱成一团。做法：（先复制一份到试验目录！）让它按规则归类。

请扫描当前文件夹里的所有文件，不要读取内容：
按扩展名把文件移动到 图片/ 文档/ 压缩包/ 其他/ 四个子文件夹里，
如果某类为空就不要创建。移动前先列一个计划给我确认。

注意特意写了「移动前先列计划给我确认」——这是保护自己文件的好习惯：让 AI 先汇报再动手，等于你当最后一道审批。

让它按固定流程跑批（无人值守热身）

回到终端，用无头模式把「整理图片」这类活直接交出去，体会「不开界面也能干」：

cd ~/Desktop/dsh-playground
dsh --profile headless "把当前目录所有 .png 和 .jpg 移到 图片/ 子目录；先列计划，确认前不要动手"

无人值守时它撞到权限策略边界会停下回报，而不是硬闯——这反而是道保险。

让它帮你写今日小结

没有技术含量但很实用：让它读你的笔记，整理成一段日报。

读 notes/ 里今天命名的文件（例如 2026-09-13.md），
按「已完成 / 进行中 / 阻塞」三类整理成一段日报，
直接在对话里打印给我看，不用写文件。

注意收尾的「打印即可，不用写文件」——这类约束能阻止它顺手造一堆文件。

万能任务骨架：读 → 做 → 交

把上面的场景抽象一下，几乎所有「让 AI 干活」都能套这个三段式：

【读】先看 {范围}，把 {背景} 弄清楚
【做】然后 {要做的事}，注意 {边界、不许碰的}
【交】完成后写到 {文件}，并告诉我怎么验收

14提示词模板与省钱经验

先背两套能复用的模板

同一个任务，「描述清楚 + 选对模式」和「随口一句 + 重模式硬扛」，结果与花费可以差出好几倍。与其记一堆命令，不如先收下这两副模板：

# 模板 A：小任务（配合极简模式最省）
只做一件事：{具体改动}。
改完只告诉我文件路径，不用解释过程。

# 模板 B：大任务（配合标准模式）
背景：{一句话背景}
目标：{做成什么样}
范围：只能在 {哪些目录/文件} 动手，别的不要碰
先列出计划，我确认后你再执行
完成后用 {想要的格式} 汇报结果

你会发现模板 B 正好把「边界 + 输出 + 刹车」都盖住了（13 的三条公式）。套用这两副模板，你已经站在水平线之上。

八条来自实测的经验

再补两条压箱底的

• 让 AI 先解释、再动手：遇到看不懂的代码，先让它「用中文讲讲这段在干嘛」，确认它真理解了再让它改——理解错导致的返工能省一大半。
• 一次只说一件大事：把「同时改五件事」拆成五轮，每轮验收完再继续。出问题好定位，想回滚也好回滚。

「换个模型会不会更聪明」

媒体横评发现：同一个模型套在不同 harness 上表现会有差异；dsh 作为预览版，速度和成熟工具相比还有差距，但效果已属超预期。如果你觉得「这个模型不太聪明」，先试两件事：换个模式，或者换个供应商的模型——别急着下结论。另外，模型与模型的切换在同一段对话里也能做。

15常见坑与排错顺序

第一步永远是分层：是没起来、没连上，还是干错了

现象 → 原因 → 解法（从高频到低频）

版本对不上命令？三步自救

• 先 dsh --help，认本机真实支持哪些命令（选项属于哪个层也会说明：dsh --profile web --help 是网页应用的参数，dsh --help 才是启动器的）。
• 再查官方 Release / Discussions 看这个版本改了什么。
• 还不行就把 dsh --profile web --dump-config 的输出贴到社区问，附上你的版本号。

16术语对照表

读前面还有哪个英文词卡壳？这张表按「这个词在这套体系里有什么用」来讲，不做英汉对译。

17一页纸：命令速查

三个先记住的锚点

• 网页入口永远是 http://127.0.0.1:3080。
• 命令都从 dsh（或 npx @deepseek-ai/dsh）开头。界面上摸不清有哪些斜杠命令时，在输入框敲一个 / 看它弹出什么——版本会变，这一招永远成立。
• 配置与密钥集中在 ~/.dsh 目录（除非你设了 DSH_HOME）。

环境与启动

node -v                          # 检查 Node，需 ≥ 20（建议 22 LTS 或更新）
brew install node                 # macOS 装 Node（未装才需要）
cd ~/Desktop/dsh-playground       # 进工作区
npx @deepseek-ai/dsh web          # 一键启动，默认 http://127.0.0.1:3080
dsh web                           # 全局安装版启动
dsh web --no-open                 # 启动但不自动开浏览器

命令行任务

dsh --profile headless "你的任务文字"   # 跑一次即退出，适合脚本

插件管理

dsh plugin --profile web add <包名>     # 装插件
dsh plugin --profile web remove <包名>  # 卸插件

排障

dsh --profile web --dump-config   # 打印当前真实生效的配置
dsh --help                         # 看本机支持的命令
dsh --version                      # 看版本

对话里的斜杠命令

/plan   /permission   /goal   /compact   /export   /feedback
# /model 是输入框里的模型弹窗，同样以斜杠唤起

命令会过期，这份「保鲜」动作请照做

• 记命令时顺手记下当时的版本号（dsh --version）。
• 把命令里的 Key 写成占位符（如 sk-xxxx），别存真实 Key。
• 升级后回来对一眼 dsh --help，变了就更新便签。
• 升级前备份 ~/.dsh 目录。

18常见问题 FAQ

99一句话总结

98参考来源与证据边界

一手来源（本文逐字核对过）

• 官方仓库 deepseek-ai/deepseek-harness：README.zh.md（运行方式、默认端口 3080、开发者预览声明、社区入口）、docs/user/guide/index.zh.md（设置 → 模型、选择工作区、输入框禁用条件）、docs/user/guide/providers.zh.md（自定义提供方字段、三种 API 协议、探测模型的边界）、apps/cli/README.zh.md（profile 与启动器参数）、docs/subsystems/sandbox.zh.md（三档沙箱）、docs/subsystems/permission-presets.zh.md（权限预设表）、docs/subsystems/approval.zh.md（ask / never）、docs/subsystems/skills.zh.md、docs/tool-catalog.zh.md（工具清单）、docs/user/develop/basic/publish.zh.md（组合包与 profile）。
• npm 注册表：@deepseek-ai/dsh 的发布记录——latest 为 0.1.5-rc.1（2026-09-10 发布），仓库首次发布 0.1.5-alpha 系列可追溯到 8 月；本文只用它核准版本号与日期，没有引用下载量。
• 本机安装的官方包：@deepseek-ai/dsh@0.1.5-rc.1 及其 dsh-agent-presets 包内的四份 preset.yml（四种模式的中文名与官方描述）、minimal/agent.cordis.yml（极简模式只有一个持久终端工具）、standard/agent.cordis.yml（标准模式的插件清单）。
• DeepSeek 开放平台（platform.deepseek.com）：API Key 的申请入口。
• 官方文档站：deepseek-harness.github.io/deepseek-harness；社区与反馈入口：GitHub Discussions、dsh-plugin 话题标签。

沿用上一版、本次未重新核验的第三方来源

下面这些是上一版文章用过的来源，本文保留了由它们带来的体感数字与实测结论（如「能扛重活但会栽细节」「一句你好烧掉上万 token」「极简开销约为标准模式的十分之一」）。这次我没有逐篇重读它们，所以只当作「经验说法」引用，不当作官方口径：阿里云 Model Studio 帮助文档、腾讯云文档（界面操作口径）；界面新闻实测《上线 12 小时 5 万星，DeepSeek Harness 实测：能干活，但得盯着》；社区实测《四种运行模式实测：标准、PTC、极简、创造到底差在哪》；社区手册 deepseek-harness-handbook。

本文自己做的核对

• 版本锚点：旧版这篇文章锚在「v0.1 developer preview（2026-08-13）」。本文改为 npm 上的 0.1.5-rc.1，并核对了它的发布日期与包内实际内容。
• 极简模式的工具数：旧版写「两个工具：持久终端 + 一个文件编辑器」。我读了本机 0.1.5-rc.1 的 minimal/agent.cordis.yml：注释写的是 single-tool coding-agent composition，实际只挂了一个持久 shell 工具（POSIX 上是 bash，Windows 上是 pwsh），且系统提示词被换成固定的一句、不做上下文压缩。本文按现状修正为「只有一个持久终端工具」。
• Node 版本口径：旧版说来源之间「v18 与 v22 都有提及」。本文直接读官方仓库根的 package.json，engines 为 ^22.19.0 || >=24.0.0（源码构建口径）；npm 包依赖里的原生组件要求 Node >=20。所以文中给的建议是「Node 22 LTS 或更新」，不再保留 v18 的说法。
• 社区入口：旧版提到 Discord。当前官方 README 列出的入口是 GitHub Discussions、dsh-plugin 话题与企微群，没有 Discord，所以本文不再把 Discord 写成官方渠道。
• 斜杠命令：/plan、/permission、/goal、/compact、/export、/feedback 都能在本机安装的包里找到对应的命令插件；/model 在包里是输入框的模型弹窗（不是命令插件），本文照实标注。

证据边界与时效

• 版本口径：本文校对于 @deepseek-ai/dsh @ 0.1.5-rc.1（2026-09-10 发布）。它是开发者预览版，官方明确写了会有破坏性变更，命令名、模式名、配置文件字段都可能调整。
• 没有做的事：我没有真的安装并跑完文中每条命令，也没有逐个验证社区插件；没有覆盖架构、插件开发、Python SDK、MCP（一种给模型接外部工具的协议）、定时任务（Schedule）、终端工具这些更深的主题——那些官方文档里有专页。
• 易变数据未采用：仓库的 star 数、下载量、媒体评测里的具体耗时这类数字本文一律不引用（它们每天都在变），需要时就近去官方仓库与 npm 页面看。
• 一处口径提醒：文中「四种模式」的名称与描述取自包内 preset.yml；如果你装到的版本里多出或少了某种模式，以你界面上的为准。