DeepSeek Harness (dsh) 从0到1保姆式实战教程

官方文档擅长把功能讲全，但对第一次接触的人不太友好：看完一圈，还是不知道第一个按钮该点哪里。这份教程换了个顺序——先让你在十分钟内跑起来，再回过头解释每一步背后的原理。等你亲手让 AI 完成第一个任务，后面的概念会自然接得上。

读完这份教程，你能做到：

• 在自己的电脑上把 dsh 的 Web 工作台跑起来；
• 正确配置模型账号、选定工作区，让 AI 只在你允许的文件夹里干活；
• 用自然语言让它读文件、改代码、跑命令；
• 看懂它的执行日志，出问题知道从哪里查、怎么把损失收回来；
• 独立完成一个多步骤的真实任务，并把它变成可以定时自动执行的流程；
• 写出并加载第一个自定义插件。

第一章 先弄明白它是什么

1.1 一句话说清楚

DeepSeek Harness（命令行里叫 dsh）是一个把大模型接到你自己电脑上的工作台。它本身不"聪明"，聪明的是背后的模型；它负责的是另一半——给模型配上真正能干活的手脚：读你的文件、改你的代码、执行命令，然后把结果拿回来给模型看，让模型决定下一步。

你可以这样理解：普通的 AI 聊天像打电话咨询，你描述情况，它给你建议，挂电话之后活还得你自己干。Harness 更像请来一位坐在你电脑前的助手，你交代清楚要什么，它直接动手，做完给你看结果。

你输入一句指令→模型拆解成几步→调用工具读文件 / 改代码 / 跑命令→把结果写回工作区

1.2 和普通 AI 对话到底差在哪

差别集中在一点：它有没有权限碰你的文件和系统。这既是它好用的原因，也是你必须小心配置权限的原因。

1.3 三个概念，先记名字就行

后面反复出现，先混个眼熟：

• 工作区（Workspace）：你交给 AI 的那个文件夹，是它能读写的边界。选得越精确，它误碰其他文件的可能性越小。这是整个使用过程中最需要你操心的一项设置。
• 工具 / 插件（Tool / Plugin）：AI 能执行的具体动作，比如"读文件""写文件""执行命令"。Harness 采用"一切皆插件"的架构，能力都是插件提供的，可以按需增删。
• 轨迹（Trajectory）：一份完整记录，写明它每一步调用了什么工具、传了什么参数、拿到了什么结果。排查问题时第一眼看的就是它。

顺便记住这几个词：Agent（智能体，指模型 + 工具 + 循环执行的整体）、Prompt（提示词，你输入的指令）、上下文（模型当前能看到的全部信息，包括对话历史和工具返回的结果）。面试和文档里高频出现，但本文不会再用它们绕圈。

1.4 什么时候值得用，什么时候别用

值得用：重复性的文件处理（批量改格式、汇总多份文档）、需要动手验证的编码任务、步骤固定的流程（每周把几份报表合一份）。判断标准很简单——这件事是不是"需要操作文件或命令的重复劳动"。

别用：只是想问问题、要个解释，普通对话就够了，套上工作台反而更慢；手头是没有本地模型可用的涉密资料，用它等于把内容发给外部服务；文件重要且没有备份，而你又没耐心逐个确认它的操作。

1.5 界面里的三种 Agent 预设

dsh 的 Web 界面内置了三套预设（preset），切换按钮在界面左上角，默认是 Standard mode：

• Standard mode：默认的完整形态，日常任务用它就行。
• Minimal mode：精简形态，挂载的能力更少，适合任务简单、想减少干扰的场景。
• Creator mode：给"创建、调试自定义 Agent 预设"准备的入口，属于进阶用法。

在 Settings → Agent presets 里，你可以关闭"允许切换 Agent 模式"来固定住预设，也可以设置新任务的默认预设。初学者建议先别动，用默认值即可。

第二章 把环境跑起来

顺利的话十分钟内跑通；卡住了，对照每步的"出错时怎么办"排查，通常不用半小时。章节后半段还包含两件长期使用必然会遇到的事：版本升级和费用控制。

2.1 先选路线：npx 还是源码

不确定选哪个就选方案 A。体验完想深入，再回来走方案 B，两者可以共存，互不影响。

2.2 安装 Node。js（两种方案都要）

dsh 是用 Node。js 写的程序，必须先装运行环境。这里有一个容易踩的坑：官方要求的版本是 Node。js 22.19 及以上，或 24 以上（对应 package.json 里的 ^22.19.0 || >=24.0.0）。网上很多教程还在推荐 Node 18 或 20，那两版跑不起来，装了等于白装。

到 nodejs。org 下载 LTS 版本安装即可。装完打开终端（Windows 的 CMD 或 PowerShell、macOS 的 Terminal 都行）验证：

node -vnpm -v

✅ 第一条命令输出的版本号以 v22.19 及以上或 v24 开头，就符合要求。

❌ 版本低于 22.19，说明装的是旧版，需要重新下载；提示"不是内部或外部命令"，说明 PATH 没配好——最简单的办法是装完后关掉终端重新开一个再试。

2.3 方案 A：一条命令启动

打开终端，输入：

npx @deepseek-ai/dsh web

这条命令的意思是：让 npm 去下载官方的 dsh 包并启动它的 Web 界面。第一次执行会多花几十秒下载，属于正常现象，之后再启动就快了。

成功的样子：终端开始滚动启动日志，浏览器自动打开一个页面，地址是 http://127.0.0.1:3080。这个 127.0.0.1 表示"只在你本机访问"，服务不会暴露到外网。

✅ 看到浏览器页面打开、地址栏显示 3080 端口，方案 A 就成功了。接下来直接跳到 2.5 节做首次配置。

没自动打开浏览器？手动访问 http://127.0.0.1:3080 即可。也可以给命令加参数 --no-open，让它只启动服务、不弹浏览器。提示端口被占用？换成：npx @deepseek-ai/dsh web --port 3081，然后访问 http://127.0.0.1:3081。--port 是 Web 应用自己的参数，必须写在 web 后面。

2.4 方案 B：从源码构建（想改代码或写插件时用）

方案 B 多了三步，但每一步的作用都很清楚，慢慢来：

第一步：把代码拉到本地

git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harness

克隆完成后你会得到一个 deepseek-harness 文件夹，后面的命令都要在这个文件夹里执行。如果终端提示找不到 git，就先去 git-scm。com 装一个 Git。

第二步：安装依赖

corepack enablepnpm install

这行在干什么：这个项目用 pnpm 管理依赖，并且通过 Corepack 固定了版本（官方仓库固定 pnpm 11.7。0）。corepack enable 是启用 Node 自带的包管理器转发工具；如果执行时报错或不认识这个命令，改用 npm install -g pnpm 装一个全局的也行。

第一次 pnpm install 会下载不少东西，几分钟到十几分钟都算正常，取决于网络。看到命令行提示符重新出现、没有报错，就算完成。

第三步：构建

pnpm run build

这一步把源码编译成可运行的产物。同样是首次较慢、之后再跑会快很多。

第四步：启动

pnpm dsh web

启动效果和方案 A 一样：浏览器打开 http://127.0.0.1:3080。区别只在于，方案 B 运行的代码来自你本地这份源码。

❌ 常见卡点：构建阶段报 Node 版本或 engine 错误，回去看 2.2 节，八成是 Node 版本不够；pnpm install 中途失败，先删掉项目里的 node_modules 目录再重跑一次，多数是网络抖动导致的半成品。

2.5 首次使用必做两步（两种方案都一样）

不管走哪条路线，界面打开后都用不了——还差两步配置。很多人卡在这里以为程序坏了，其实只是没配置。

第一步：配置模型（Settings → Models）

点击界面上的 Settings（设置），进入 Models 页面，在 DeepSeek 卡片里粘贴你的 API Key 并保存。

还没有 Key？到 DeepSeek 开放平台注册账号，在 "API keys" 页面创建一个并复制。这个 Key 相当于你调用模型的凭证，按用量计费，建议创建后在平台上留意余额。

✅ 保存成功后不需要重启服务，模型立即生效。界面只保存 Key 的引用，真实密钥存放在你本机的凭据文件里。

第二步：选择工作区（Choose workspace）

点击界面上的 Choose workspace，选一个具体项目文件夹，比如 D:\work\project-demo。这一步是在划定 AI 的活动范围——它会把你选中的文件夹当作自己的"办公桌"，只在这里读写文件。

❗没选工作区之前，对话输入框是不可用的，这是新手最常遇到的"为什么打不了字"。另外，请把工作区指向具体的项目文件夹，不要直接选整个盘符（例如整个 D 盘），范围给得越大，它误碰无关文件的机会就越多。

没选前：

选择后：

2.6 不想把文件发给外部服务？接本地模型

前面这套配置默认把你的指令和相关文件内容发给 DeepSeek 的云端服务。如果手头是公司内部资料、合同、客户数据，就不能这么用了。解决办法是：在本机或内网跑一个模型服务，把 dsh 接过去。

只要对方提供 OpenAI 兼容接口（vLLM、内网网关通常都提供），配置步骤并不复杂：

1. 先把本地推理服务跑起来。以 vLLM 为例：vllm serve 你的模型 --port 8001，然后用 curl http://127.0.0.1:8001/v1/models 确认它已经就绪——这条命令能返回一串模型信息，说明服务通了。
2. 打开 dsh 界面，进入 设置 → 模型 → 添加自定义提供方。
3. 按表单逐项填写，含义如下：

表单里还有 Fetch available models（获取可用模型），点一下可以让它自己去问服务端有哪些模型，勾选后保存即可。

✅ 保存后新模型马上出现在模型选择器里，不用重启服务。之后所有计算都在你自己的机器上完成，文件不出本机。

2.7 三条安全底线

dsh 官方在 SAFETY。md 里说得很直接：这是实验性软件，没做过安全审计，它会执行模型生成的命令、能访问你给它的文件和网络，出错可能造成数据损坏或泄露。不需要因此不用它，但下面三条建议别省：

1. 工作区给到最小范围。需要处理哪个文件夹，就只选那个文件夹。这是成本最低、效果最明显的一道防线。
2. 用云端模型时，别把涉密内容放进去。API 模式下文件内容会离开你的电脑，这是原理决定的，不是配置能绕开的。
3. 重要文件先备份，危险操作保持人工确认。官方建议在虚拟机、容器或独立环境里运行它，并保留命令执行的确认环节。确认弹窗会打断你的节奏，但它拦下的可能是一次不可逆的删除。

万一还是出了错，怎么把损失收回来，第五章有完整的处置方法。这里先记住一句话：发现不对立刻停手，不要在错误的方向上继续让它"修复"。

2.8 版本升级与锁定：developer preview 的必修课

官方在仓库首页用大写字母写着：会有不兼容改动。这意味着升级不是"顺手更新一下"的小事，它可能导致按钮位置变化、参数改名、配置文件失效。你需要先决定自己的策略：

npx 路线：怎么升级、怎么锁定

npx 默认取最新版，所以"升级"就是重新执行一次启动命令。锁定版本则是在包名后面加 @版本号：

# 启动最新版（默认行为）npx @deepseek-ai/dsh web# 锁定到指定版本npx @deepseek-ai/dsh@0.1.0 web

想知道当前最新版本是什么，可以查一下：

npm view @deepseek-ai/dsh version

源码路线：怎么升级、怎么回退

升级就是拉最新代码重新构建：

git pullpnpm installpnpm run build

想回退到升级前，用 git 切回原来的提交或标签，再重新构建一次即可。所以升级前建议先记下当前所在的提交版本：

git log -1 --format="%H %s"

💡 升级后的第一件事：别急着上生产任务，先用第三章那个"新建 test。txt"的小练习验证一遍。三个动作全部正常，再处理真正要紧的文件。

❌ 升级后界面和本文对不上怎么办？这是正常现象，本文也标注了会过时。以官方文档为准；如果新版用不了、你又急着干活，先把版本切回原来那个能用的。

2.9 一次任务花多少钱：成本控制

用云端 API 就绕不开费用。它按用量计费，而用量主要取决于模型读了多少内容、说了多少话。不需要精确算账，但要知道钱花在哪：

三条能省下大部分费用的习惯：先小样本试跑、发现跑偏立即中断、一个任务一个会话。至于实际花了多少，登录 DeepSeek 开放平台在用量页面查看，养成定期看一眼的习惯。具体单价和计费口径会调整，做预算时以平台当前页面为准，不要照抄旧教程里的价格表。

走本地模型路线的话，没有按次计费，但换来的是硬件成本：显卡、电费和时间。判断标准也很简单——涉密内容或高频重复使用，本地更划算；偶尔用一次的轻量任务，云端 API 更省事。

第三章 界面与日常使用习惯

界面不复杂，分成四块。这一章按你实际使用的顺序讲一遍，顺便说明每一块存在的意义，以及几条能让它长期好用的习惯。

3.1 会话侧边栏：一个任务开一个会话

左侧是会话列表，点 + New Session 新建。这里有一个值得养成的习惯：一个独立任务对应一个会话。因为模型只能看到当前会话的历史，如果文档处理、代码调试、报表汇总全挤在一个会话里，它会不断被无关内容干扰，回答质量下降，排查问题也变难。

工作区是全局设置，不属于某个会话。要换项目，重新点 Choose workspace 选另一个文件夹即可，旧会话的记录不受影响。

3.2 模式与设置：需要时才改

左上角的模式按钮用来切换 Agent 预设（第一章 1.5 节讲过的 Standard / Minimal / Creator）。旁边的 Settings 里集中了几项关键配置：

• Models：配置模型和 API Key，就是 2.5 节做的事；
• Agent presets：管理预设，包括是否允许切换、新任务的默认预设；
• 权限策略：控制哪些操作需要你手动确认，与安全直接相关，不建议为了省事全部关掉。

3.3 对话输入框：指令质量决定结果质量

所有任务都从这里发起。输入框里敲一个 / 会弹出斜杠命令目录，里面列着当前可用的命令，可以用它快速调用功能，不用记全。

同样一件事，指令写得好不好，结果差距很大。对比一下：

记一个够用的公式：做什么 + 处理哪些文件 + 结果存哪里 + 有什么限制。第四章会给出完整模板，第七章会用真实案例完整演示一遍。

3.4 Trajectory（轨迹） 视图：出问题时第一个看的地方

对话区可以切换到 Trajectory 轨迹 视图。它把 AI 这一步一步在干什么完整摊开：系统提示词是什么、思考过程是什么、调用了哪个工具、传了什么参数、工具返回了什么、哪里报错。

为什么强调它？因为新手遇到结果不对，第一反应往往是"换个说法再问一遍"。但对于 Agent 来说，问题八成出在中间某一环——工具没被调用、路径写错了、或者权限被拦下了。这些都会出现在 Trajectory 里，看一眼比重新提问十次都管用。

3.5 会话与上下文：为什么它会"忘事"，怎么办

模型没有记忆。它每一轮能看到的，只有当前会话的历史记录加上工作区里的文件。这就解释了几件新手常困惑的事：

• 你在会话 A 里交代过的要求，在会话 B 里它完全不知道；
• 对话拖得越长，它越容易忽略早期的要求，也越容易把不同任务的细节混在一起；
• 同时，会话越长越贵，因为历史记录每轮都要重新送进模型。

对应的做法有四条：

1. 一个任务一个会话任务做完就开新的，别把无关内容堆在一起；
2. 需要长期遵守的规范，写进工作区的文件里，而不是靠对话记忆。比如在项目目录放一份说明文件，把编码风格、目录约定、命名规则写进去，让它每次先读这份文件再动手。这样换个会话、隔一周再来，规范依然有效。
3. 需要反复使用的流程，做成可复用的能力。dsh 支持 skill 机制来承载这类流程；注意它不是所有预设都加载——Standard mode 会加载本地 skill，Minimal mode 不会。具体放置位置和格式以官方文档为准。
4. 复杂任务先对齐步骤再动手。标准预设带计划模式，可以让它先把执行计划列出来，你确认没问题再往下走，避免它闷头做完一大半才发现方向错了。

判断标准很简单：如果一条要求你希望"下次它还知道"，那就别只写在对话框里——写进文件、做成 skill，或者写进你自己的任务模板里。

3.6 第一个练习：让它创建一个文件

跑通环境后，别急着上复杂任务，先用这个练习确认整条链路是通的：

1. 选好工作区，新建一个会话；
2. 在输入框里发送：在当前工作区新建 test.txt，内容写入 hello harness
3. 等它执行完，打开你选择的那个文件夹，看有没有出现 test。txt。

✅ 文件出现了，而且内容正确，说明模型配置、工作区权限、文件工具这条链路全部正常，可以放心做正式任务了。

❌ 文件没出现，先打开 Trajectory 看一眼：是工具压根没被调用，还是被权限策略拦下了，还是写到了别的地方。这三个原因覆盖了绝大多数情况，具体排查方法见第五章。

第四章 让它自己完成多步骤任务

前面的练习只涉及一个动作。Harness 真正省时间的地方，是它能自己把一件事拆成好几步、依次做完。这一章讲清楚它是怎么做到的，以及你怎么下达这类任务。

4.1 Agent 是怎么"干活"的

你不需要给它写流程图。它拿到指令后会自己拆解：先做什么、再做什么、需要调用哪个工具。执行完一步，工具返回的结果会进入它的"视野"，它据此判断下一步，直到任务完成，或者遇到需要你拍板的地方停下来问你。

这意味着两件事：第一，你只要把目标和验收标准说清楚，中间的步骤不用操心；第二，如果目标本身模糊，它会拆出一堆看起来合理但方向不对的步骤，而且执行得很认真。所以指令里"验收标准"比"步骤"更重要。

4.2 完整走一遍：对比两份文档

假设工作区里有两个文件 old.md 和 new.md，你想知道改了什么。发送：

读取工作区里的 old.md 与 new.md，找出两者的内容差异，把差异整理成清单保存为 diff_result.md

发送之后你会看到它依次做这些事：先读 old。md，再读 new。md，对比内容，最后把结果写入 diff_result。md。整个过程都记录在 Trajectory 里，你可以随时回看每一步。

结束后验证很简单：打开工作区文件夹，双击 diff_result。md 看内容是否合理。不要只看它说"已完成"就当完成了——AI 说完成和结果正确是两件事，打开文件核对是唯一可靠的验收方式。

4.3 指令模板：四个要素

把下面四项都交代清楚，绝大多数任务都能顺利执行：

拼起来就是一条可以直接用的指令：

把当前工作区 reports 目录下所有 md 文件里的待办事项提取出来，按文件名分节汇总，保存为 todo-summary.md。只读取原文件，不要修改它们；遇到无法解析的文件，在汇总里标注出来。

再看一个编码场景的例子：

阅读 src/utils/date.ts，找出其中处理时区时可能出错的地方，给出修改方案并直接修改文件。改完运行现有的单元测试，把测试结果告诉我；如果有测试失败，不要继续改其他文件。

注意最后一句：它设定了一个"停下来"的条件。任务越复杂，越值得加上这类边界，避免它在你没注意的时候越改越多。

4.4 权限确认：被打断是件好事

当 Agent 准备执行权限策略要求批准的操作时——最典型的是运行终端命令——界面会弹出确认窗口，你点确认它才真正执行。

这个弹窗会打断你的节奏，可以关，但建议保留。它拦住的是那些"模型觉得合理、但对你的机器不合适"的操作：删除文件、覆盖目录、安装依赖、改系统配置。你在弹窗里能看到它到底要执行什么命令，这本身就是一次复核机会。

第五章 出问题时的排查与恢复

这一章讲两件事：任务结果不对时怎么查（大概率是配置或指令问题），以及真的动了不该动的文件时怎么把损失收回来。第二件希望你永远用不上，但必须提前知道。

5.1 排查顺序：按这五步走

结果不对，别急着换个说法重新提问。按顺序看，能覆盖绝大多数情况：

1. 看 Trajectory：工具到底被调用了没有？调用的参数对不对？有没有报错信息？这一步能解决一半以上的问题。
2. 检查路径：它找的文件名、目录名和你以为的一致吗？工作区选对了吗？中文文件名、空格、相对路径都是常见坑。
3. 检查权限：是不是某一步的确认弹窗被你点了取消，或者被权限策略拦下了？
4. 检查模型：当前会话用的是哪个模型？简单模型确实会做错复杂任务，换一个能力更强的模型重试。
5. 拆小任务：把一步做完的大任务拆成几个小任务分别执行，看它卡在哪一步。这招最笨，但最有效。

一个高频误区：结果不对不等于模型不行。先确认"工具有没有正确执行"，再怀疑"模型够不够聪明"。顺序反了，就会陷入不断换模型、换说法，但问题其实在路径或权限上。

5.2 出错后的恢复手段

先说最重要的那条原则：发现不对，立刻中断，不要让它"自己修复"。它在错误的方向上继续操作，只会把问题放大。停手之后，按下面的顺序处理。

第一层保险：把工作区放在 git 仓库里

这是最有效的一招。如果你的项目本身就在 git 仓库里，那你天然拥有完整的后悔药：

• 任务开始前执行 git status，确认当前没有未提交的改动。这一步让你心里有底——出问题后能分清哪些是它改的。
• 任务结束后执行 git diff，逐项确认它到底改了什么，确认无误再提交。
• 改错了就回滚。单个文件改坏，用 git restore 文件名 丢弃未提交的改动；整个任务失败，用 git restore . 恢复到上次提交的状态。

⚠️ git restore 会直接丢弃未提交的改动，且不可恢复。执行前先确认改动确实都是 AI 造成的；如果里面有你自己还没保存的工作，先用 git stash 存起来，或者干脆手动备份一份。

⚠️ git restore 只能恢复已经纳入 git 的文件。AI 新建但从未提交过的文件不会被它删掉，需要你在确认内容后手动处理。不要为了图快随手执行 git clean -fd，它会永久删除未跟踪文件，风险更高。

第二层保险：没有 git 就手动备份

不是所有文件都值得建仓库。处理一批 Excel、几份合同、一个共享盘的目录时，用最朴素的办法：动手前把整个文件夹复制一份。听起来笨，但它比任何补救手段都可靠，而且准备时间不到一分钟。

几种具体情况的处置

5.3 把风险压到最低的四条习惯

1. 工作区最小化：只选需要的文件夹，别图省事选整个盘；
2. 重要任务先备份：git 或手动复制，二选一，别跳过；
3. 保留确认弹窗：多花三秒看命令，可能省掉三天找文件；
4. 小样本先试：先拿一两个文件验证指令效果，确认了再全量执行。

这四条都不难做，真正的成本只是每次多花半分钟。但它们把"可能出大事"变成了"最多浪费一点时间"。

第六章 三个常用能力，逐个上手试

这一章给的是可以直接复制粘贴的测试指令。每条都说明了它验证的是什么能力、成功是什么样、失败说明什么。建议按顺序各跑一遍，跑完你就对自己的环境有底了。

6.1 文件读写：最基础也最常用

这条指令验证的是"读取多个文件 → 处理内容 → 写出新文件"这条完整链路：

遍历当前工作区，列出全部 .md 文件；对比 a.md 与 b.md 的内容差异，并把差异整理保存为 compare_result.md

✅ 成功的样子：工作区里出现 compare_result。md，打开能清楚看到两份文件的差异。

❌ 失败说明什么：如果提示找不到文件，通常是工作区里没有 a。md / b。md，先放两个测试文件进去；如果提示权限问题，检查工作区是不是选对了。

6.2 写代码：生成代码和测试

这条指令验证的是代码生成与文件落盘能力：

编写一个 TypeScript 函数实现冒泡排序，生成对应的单元测试代码，并保存至当前工作区

✅ 成功的样子：工作区里出现源码文件和测试文件，代码符合你的命名与风格要求。

💡 一个必须养成的习惯：AI 写的代码一定要 review 之后再合并进正式项目。它能帮你把活干快，但不会替你承担正确性责任。跑一遍它生成的测试，再自己看上两眼。

6.3 执行命令：确认弹窗出现即正常

这条验证的是终端执行能力和权限确认机制：

执行命令查看当前工作区的文件列表，不要做删除修改操作

✅ 成功的样子：界面上弹出确认窗口，你点击确认后，它返回目录里的文件列表。弹窗出现本身就是功能正常的证明。

💡 练习阶段尽量用只读命令。等你对确认机制和权限策略都熟悉了，再放开更复杂的操作。

第七章 完整实战：把 12 份周报合并成一份

前面几章用的是玩具例子。这一章走一遍真实任务：把 12 份周报合并成一份季度汇总，并提取出所有待办事项。请跟着做一遍——做完这个，同类任务（月报汇总、会议纪要合并、多份调研整合）你都能自己拆解。

7.1 场景与准备

假设你的工作区是 D:\work\weekly-reports，结构如下：

dsh/└── reports/    ├── week-01.md    ├── week-02.md    └── ... 共 12 份

这些周报格式大致相同，但细节不一致：有的用"待办"、有的写"下一步计划"，个别还漏写了负责人。这种"看起来规整、其实有出入"的脏数据，正是真实工作里的常态，也是这章要处理的重点。

7.2 第一步：先侦察，别急着动手

很多人的第一反应是直接说"帮我合并周报"。更稳的做法是先花几十秒摸清情况：

列出 reports 目录下所有文件名，并简要说明每个文件的结构。不要修改任何文件。

它会返回 12 个文件名和各自动结构。这一步有两个作用：确认文件数量对不对（12 份，不多不少），以及观察各文件结构差异——后面写指令时，你就能提前说清楚"遇到格式不一致怎么办"。

7.3 第二步：先看一个反例

假设你直接发送这句：

把这些周报合并一下

典型结果通常不理想：它可能只凭猜测挑了几份文件、输出格式完全不合你的预期、把重复内容合并掉了，或者干脆停下来反问你一堆问题。浪费了一次调用，还得推翻重来。

这不是模型不行，而是指令里缺少验收标准——它无法判断什么算"合并好了"。

7.4 第三步：用四要素写出完整指令

套用第四章的模板，把目标、输入、输出、约束都写清楚：

把 reports 目录下 week-01.md 到 week-12.md 共 12 份周报合并成一份季度汇总，要求：1. 按周次顺序排列，每周一节，节标题用文件名；2. 每节包含三部分：本周完成事项、问题与风险、下周计划；3. 原文没有对应内容的，写"未提及"，不要编造；4. 汇总末尾单独列出所有周报提到的待办事项，按周次编号；5. 保存为 quarterly-summary.md，不要修改任何原始文件。

这条指令和反例的差别，就是它把"什么算合格"讲清楚了：数量（12 份）、结构（三部分）、缺失处理（写未提及）、输出位置（quarterly-summary。md）、安全约束（不改原文件）。

7.5 第四步：盯着 Trajectory 执行

发送之后切到 Trajectory 视图，你会看到它依次：读取 week-01。md → 读取 week-02。md → …… → 读完 12 份 → 汇总生成内容 → 写入 quarterly-summary。md。

盯这个过程不是为了看热闹，而是为了尽早发现问题：比如它只读了 8 个文件就开始写结果、或者某个文件读取报错但被它跳过了。这类问题在 Trajectory 里一眼可见，而不是等你打开结果文件才发现少了内容。发现了就直接中断，别等它写完。

7.6 第五步：验收，别只看"已完成"

它的任务结束后，按这个清单验收：

1. 打开 quarterly-summary。md，先看整体结构是不是 12 节；
2. 抽查 2～3 周的内容，和原始周报对照，确认没有编造、没有张冠李戴；
3. 核对待办清单，看条目数量与原文是否对得上；
4. 确认原始文件没被改动——在 git 仓库里执行 git status，或者对比文件修改时间。

✅ 四项都通过，这次任务才算真正完成。整个过程大概两三分钟，比你手动合并 12 份文档快得多，而且可复查。

❌ 如果发现内容有编造或遗漏，别让它"重新做一遍"就完事——把具体问题写进指令，例如加上"第 5 周的下周计划原文没有，不要补写"，然后重跑。指令越具体，返工越少。

7.7 这个案例教会我们的通用套路

把这个流程抽象出来，就是处理任何批量任务的标准动作：

先侦察文件→用四要素写指令→盯 Trajectory 执行→按清单抽查验收

如果文件特别多（比如上百份），再加一招：分批处理。先合并前一半、再合并后一半，最后把两个中间结果合成一份。这样既能控制单次任务的范围，也能避免一次读太多内容导致费用和出错率上升。

第八章 更多任务配方

下面是六个可以直接改用的任务模板，覆盖职场里最常见的一类需求。使用时记住同一条纪律：先拿一两个文件试跑，确认效果再全量执行。

8.1 批量重命名文件

场景：一堆文件命名混乱，想统一加上日期前缀或统一编号。

把当前工作区 photos 目录下的图片按修改时间排序，重命名为 trip-001.jpg、trip-002.jpg……依次类推。重命名前先列出新旧文件名对照表保存为 rename-log.md，我确认后你再执行。

注意：重命名属于不可逆操作，务必保留对照表。稳妥做法是分两步——先让它生成方案，你确认后再让它执行。

8.2 从多份文档里提取表格

场景：十几份格式相同的报告，想把里面的数据表汇总成一张总表。

读取 reports 目录下所有 .docx 转出的 md 文件，提取其中的数据表格，合并成一张总表保存为 all-data.csv，并在表格中增加一列标明数据来源的文件名。格式不一致、无法确定的数据标注为"待确认"，不要猜测。

注意：提取类任务的成败取决于原文格式是否统一。先跑一两个文件，确认提取规则对了再全量。对 .docx、.xlsx 这类二进制文件，最稳的做法是先转换成 Markdown、CSV 等文本格式，再让它读取；如果环境里能直接解析，也先用一份测试文件确认结果没有漏项。

8.3 快速读懂一个陌生代码库

场景：接手一个项目或开源仓库，想先摸清结构再动手。

阅读当前工作区的代码库，说明它的整体结构：列出主要目录和各自职责、核心入口文件、使用的技术栈，以及新手上手需要先看哪几个文件。把结果保存为 codebase-guide.md。不要修改任何代码。

注意：这一步是纯读取，风险低、收益高，适合作为接触任何新仓库的第一个动作。

8.4 根据改动生成变更说明

场景：开发完一批修改，要写提交说明或版本变更记录，懒得逐条翻 diff。

查看当前 git 工作区的未提交改动，按功能、修复、重构三类归纳，生成一份中文变更说明保存为 CHANGELOG-draft.md。只描述实际改动，不要添加没有发生的内容。

注意：生成的是草稿，提交前自己过一遍——AI 归纳得可能过于笼统，或者漏掉你重视的细节。

8.5 代码审查：只找问题，不改代码

场景：想让它帮忙看看有没有潜在问题，但不想让它在没确认前就动手改。

审查 src 目录下的代码，找出潜在的空值处理问题、未捕获的异常和明显的性能隐患，按严重程度排序列成清单，每条给出文件名、行号和修改建议。不要直接修改任何文件。

注意：明确写"不要直接修改"很关键。审查类任务让你保留全部决定权，是新手最安全的使用方式之一。

8.6 文档一致性检查

场景：一套说明文档写了一段时间，术语、格式、链接开始出现不一致。

检查 docs 目录下所有 md 文件：找出同一概念用了不同称呼的地方、格式风格不一致的地方、以及指向不存在文件的链接。整理成问题清单，标注每个问题的文件名和位置，保存为 docs-check.md。不要修改原文。

注意：链接是否有效取决于它能不能访问网络。如果环境不允许联网，就让它在结果里标明"未验证"。

第九章 进阶：把跑通的流程变成定时任务

前面所有操作都要你点开界面、输入指令。如果某个任务每周甚至每天都做，值得把它变成自动执行的流程——这才是 Harness 长期省时间的形态。

9.1 什么时候该做这件事

三个条件同时满足时才值得：任务重复且步骤固定（比如每周一汇总上周的日志）、你已经手动跑通过多次、失败后果可控（输出文件而不是直接改动重要数据）。三个条件缺一个，都建议先继续手动执行。

9.2 第一步：用 headless 模式跑通同一条指令

dsh 提供无界面的命令行模式，适合放进脚本或计划任务。把你在界面里验证好的指令原样交给它：

# 源码环境下pnpm dsh --profile headless "汇总 reports 目录下本周的日志，生成周报保存到 output 目录"# 使用 npx 安装的版本时，命令形式以官方 CLI 文档为准

先手动执行几次，确认模型凭证可用、结果稳定、输出路径正确。计划任务运行时不会继承你当前终端里临时设置的环境变量；如果 headless 依赖 API Key 环境变量，必须在计划任务中单独配置好。这一步不通过，就不要往下做定时任务。

⚠️ 非交互模式没有界面，遇到需要人工确认的操作时行为会不同。所以定时任务里的指令要尽量设计成只读或只写新文件，不要依赖弹窗确认。这一点建议你实测确认后再投入正式使用。

9.3 第二步：交给系统计划任务

跑通之后，就是让操作系统定时调用这条命令：

以 Linux 的 cron 为例，每周一早上九点执行一次，规则大概长这样（路径和命令按自己环境调整）：

0 9 * * 1 cd /path/to/project && pnpm dsh --profile headless "汇总 reports 目录下本周的日志，生成周报保存到 output 目录" > logs/weekly-$(date +\%F).log 2>&1

9.4 三条落地建议

1. 手动跑通至少三次再上定时。一次成功可能是运气，任务里有没有不稳定因素，多跑几次才看得出来。
2. 输出文件带时间戳。否则每次执行都会覆盖上次结果，出了问题连对比的样本都没有。
3. 把日志留下来。上面的命令示例把输出重定向到日志文件，就是为了出问题时能回看它到底做了什么。自动任务最怕的不是失败，而是失败了没人知道。

❌ developer preview 阶段命令行参数可能变化。本文给出的 headless 用法仅作示意，正式使用前请对照仓库里的 CLI 文档确认当前版本的准确写法。

附录

常见问题排查表

术语速查

官方链接

• 项目仓库：github。com/deepseek-ai/deepseek-harness
• 官方文档：deepseek-harness。github。io/deepseek-harness
• API Key 申请与用量查询：platform。deepseek。com
• 问题反馈与交流：仓库 README 中的 GitHub Discussions 与官方 Discord 入口
• 安全说明：仓库根目录的 SAFETY.md，动手前值得花两分钟读一遍