上手指南hydrogenfluoride233/dsh-guide

DSH 快速上手

官网：<https://www.deepseek.com/harness/>

DSH 是一个 AI 助手，但它和网页版的聊天机器人不一样——它能真的动手操作你电脑上的文件。

先搞清两个词

| 词 | 大白话 |
| AI Agent（智能体） | 能"动手干活"的 AI。普通的聊天 AI 只能跟你对话，你说"帮我改个文件"，它只能告诉你怎么改；Agent 可以自己去改。 |
| DSH | 全名 DeepSeek Harness，是 DeepSeek 出的一个 AI Agent 工具。装在你自己的电脑上，通过浏览器操作，能读写你的文件、执行命令、联网查资料。 |

用它能干什么？ 下面这些是常见的用法：

| 类型 | 例子 |
| 整理文件 | 批量按规则改名、按日期归档、找出重复文件 |
| 处理文档 | 总结长文档、从一堆资料里提取信息做成表格、汇总 Word/PDF/TXT 里的数据 |
| 表格数据 | 合并两份名单、去重、对比差异、把乱数据整理成规范表格 |
| 写作辅助 | 起草邮件通知报告、把口语改成正式表达、查错别字 |
| 翻译 | 中英互译并保持专业说法 |
| 查资料 | 上网查资料整理成说明、解释看不懂的术语和报错 |

怎么用：在界面下方的输入框里，用大白话把要做的事说清楚就行。比如：

把 D:\照片 里所有图片按拍摄日期改名

说得越具体，它做得越准。

一个现成的例子：这份指南就是 DSH 写的

你现在读的这篇文档，从头到尾由一个 DSH agent 在一次对话里完成。 它做的事包括：

| 它做了什么 | 具体经过 |
| 查证事实 | 不确定 npx 的下载提示长什么样，就去翻程序源码，拿到确切文字 |
| 实测行为 | 怀疑 token 到底是不是必需，就在另一个端口起测试服务，亲自发出请求，抓到服务器返回的 401 和错误原文 |
| 排查问题 | 文档里 12 条排错记录，全部是实际踩过的坑，不是想出来的 |
| 生成图片 | 把官方 SVG 图标转成了电脑用的 .ico 文件 |
| 整理成文 | 写成本文 1000 多行，并拆成"新手照着做"和"出问题查附录"两层结构 |
| 发布上线 | 通过 GitHub 提交并推送，让它变成你能访问的网页 |

你看到的每一条命令、每一个提示文字，都是它验证过才写进去的。这就是 Agent 和普通聊天 AI 的区别——不是"告诉你该怎么做"，而是"自己查、自己试、自己做、最后交给你"。

⚠️ 也正因为它真的会动手改文件，所以建议先拿不重要文件夹试手，熟悉了再处理重要的东西。

这份指南讲什么

跟着做 10 分钟就能用起来，一共四步：

第 1 步 装 Node.js ← DSH 需要的运行环境第 2 步 启动 DSH ← 一条命令第 3 步 配置密钥 ← 让它能调用模型第 4 步 测试 ← 发一句话试试

完全没接触过也不用怕，每一步都会告诉你"会看到什么""出错了怎么办"。遇到不懂的词，翻到后面的名词对照表。

懒人版（只有命令）

已经装过 Node.js 的话，你只需要这三条：

1. 启动（第一次运行会问是否下载，直接回车）
npx @deepseek-ai/dsh web

2. 把打印出来的完整地址复制到浏览器，大概长这样：
dsh web: http://127.0.0.1:3080/?token=一堆字母数字
#
⚠️ 后面那串 ?token=... 要一起复制。
如果打印出来的没有这一段，也照样打开试试——那只说明你用的是另一个版本，不影响使用。

3. 首次打开会弹内测提示 → 点 Continue 然后填 API 密钥（在 platform.deepseek.com 申请）

没装过 Node.js、或者想搞明白每一步在干什么，往下看正文。

鸿蒙电脑 / 平板 / 手机用户请注意

先用下面这张表确认你的设备能不能装，免得照着装了半小时才发现不行：

| 你的设备 | 能不能装 | 怎么办 |
| Windows 电脑 | ✅ 能 | 按下面正文走 |
| Mac 电脑 | ✅ 能 | 按下面正文走（用 brew 装 Node.js） |
| 华为鸿蒙电脑（系统是 HarmonyOS） | ❌ 不能 | 见下方说明 |
| 鸿蒙 / 安卓平板、手机 | ❌ 不能 | 见下方说明 |
| 华为笔记本但系统是 Windows | ✅ 能 | 按下面正文走 |

怎么判断自己是哪种：

- 桌面上有「此电脑」这个图标 → Windows
- 在桌面空白处右键，菜单里有「显示设置」「个性化」→ Windows

华为的鸿蒙电脑没有「此电脑」，所以只要你没在桌面见过这个图标，基本就是鸿蒙。

为什么鸿蒙电脑装不了

DSH 需要 Node.js 才能运行，而 Node.js 官方不提供鸿蒙版——鸿蒙电脑跑不了 Windows 程序，也没有对应的安装包。

这不是配置问题，是根本没有这个东西，所以没法绕过。

那鸿蒙用户能用 DSH 吗

不能直接装，但可以换个思路——用别的电脑。

思路一：找一台 Windows 电脑（推荐）

如果你手边有一台 Windows 电脑（台式、笔记本都行），那台就能按本指南装。鸿蒙笔记本本身不用管。

思路二：鸿蒙上装虚拟机

鸿蒙电脑可以跑 Windows 虚拟机，理论上能在虚拟机里装 DSH。但实际上：

- 要装虚拟机软件、下载 Windows 镜像、分配磁盘和内存……对不熟悉电脑的人来说很折腾
- 虚拟机里跑 AI 工具，性能会打折
- 出问题时排查更麻烦

除非你本来就在用虚拟机，否则不建议为这个专门折腾。

为什么不能"在别的电脑装、用鸿蒙笔记本打开"

有人会想到：家里台式机装好 DSH，鸿蒙笔记本用浏览器访问行不行？

目前不行。 出于安全考虑，DSH 被设计成只能本机访问——官方明确禁止了对网络开放：

error: --host 0.0.0.0 is intentionally not supported yet for safety:
it would expose remote code execution to the network

（翻译：有意不支持，因为那会把「能执行命令」的能力暴露到网络上。）

这个限制是合理的——DSH 能读写文件、执行命令，如果开放到局域网，同一 WiFi 下任何人都能指挥你那台电脑。

总结一下

| 你的情况 | 建议 |
| 有 Windows 台式机 / 笔记本 | ✅ 用那台装，最简单 |
| 单位/公司有 Windows 电脑 | ✅ 可以用那台（注意别违反公司规定） |
| 只有鸿蒙设备 | ⚠️ 要么装虚拟机（折腾），要么等以后支持 |

一句话：鸿蒙设备本身装不了，但只要你还能碰到一台 Windows 电脑，这事就成立。

第 1 步：装 Node.js

DSH 自己不是个能直接双击运行的软件，它需要 Node.js 才能跑起来。所以先把 Node.js 装上。

不知道 Node.js 是什么也没关系，就把它当成「DSH 需要的运行环境」。装一次就行，以后不用管。

怎么打开「命令行」

后面的操作都要在命令行里输入（就是那个黑底白字的窗口）。第一次用的话，按这个方法打开：

1. 按键盘上的 Win 键 + R 键（Win 键就是键盘左下角那个 Windows 徽标键）
2. 左下角会弹出一个小窗口，里面有个输入框
3. 在框里输入三个字母：cmd
4. 按 回车（或点「确定」）

然后会出现一个黑底白字的窗口，窗口里有一行字，大概长这样：

C:\Users\你的名字>

看到这个就对了。 后面说「输入命令」，就是指在这个窗口里打字，然后按回车。

💡 想复制粘贴：在这个窗口里右键就是粘贴（不用按 Ctrl+V 也行）。或者用 Ctrl+V 试试。

💡 如果命令打错了，重来就行，不会弄坏电脑。

安装 Node.js

1. 用浏览器打开 <https://nodejs.org>
2. 找到写着 LTS 的那个下载按钮（LTS 是「长期支持版」的意思，选它最稳），下载 .msi 安装包
3. 双击下载好的文件，一路点「下一步」，不需要改任何选项，最后点「完成」
4. ⚠️ 装完必须重新开一个命令行窗口（把刚才那个关掉，重开一个）

第 4 点很重要。 不重开窗口的话，下面的命令会提示「找不到」，让你以为装失败了。

检查是否装好

重新打开命令行（Win + R → cmd → 回车），输入这行，然后按回车：

node --version

看到一串版本号就成功了，比如：

v26.5.1

（数字不一样没关系，只要能看到类似的东西就行。）

如果提示「不是内部或外部命令」，说明没装上或没重开窗口。先重开一个窗口再试；还不行就重新安装一次，注意装完一定要重开窗口。

macOS 用户：打开「终端」（在「启动台」里搜 终端 或 Terminal），输入 brew install node 即可。没有 brew 的话去 <https://brew.sh> 按提示装。

第 2 步：启动 DSH

在命令行窗口里输入这一行，然后按回车：

npx @deepseek-ai/dsh web

会看到什么

第一次运行会先问你要不要下载，大概长这样：

Need to install the following packages:
@deepseek-ai/dsh@0.1.5-rc.1
Ok to proceed? (y)

直接按回车就行（也可以先打一个 y 再回车，效果一样）。

这是正常的——DSH 第一次用需要先下载到自己电脑上。以后就不会再问了。

然后会开始下载，需要等几分钟（大约 214 MB）。下载时屏幕上有进度，别关窗口。

不想每次都被问的话，可以把命令写成 npx -y @deepseek-ai/dsh web，-y 就是「直接同意」的意思。

下载完之后

屏幕上会打印一行地址，长这样：

dsh web: http://127.0.0.1:3080/?token=一堆字母数字

把这一整行地址复制下来，粘贴到浏览器打开（建议用 Edge 或 Chrome）。

⚠️ 一定要连 ?token=... 一起复制。

token 是一次性的通行证。只输 http://127.0.0.1:3080 会显示 authentication required（需要身份验证），因为它没法确认是本人打开。

打开后就能看到 DSH 的界面了。这时候命令行窗口不要关——它是 DSH 的「发动机」，关了界面就用不了了。

以后怎么关掉 DSH

在命令行窗口里按 Ctrl + C 就能停掉。或者直接把窗口关掉。

不小心关了窗口、界面用不了了？重新运行第 2 步那条命令就行。

第 3 步：配置 API 密钥

先说说第一次打开界面会看到什么

第一次用浏览器打开那个地址，会先弹两个东西，别慌，都是正常的：

① 一个「内测说明」弹窗（Internal Testing Notice）

内容是英文的，大意是「DSH 还是测试版，功能会快速迭代」。不用细看，点 Continue 关掉就行。

点过一次之后就不再弹了——DSH 会记住你已经确认过。

② 一个「添加 API 密钥」的框（Add an API key to get started）

这个就是接下来要做的。它提示你配置 API 密钥，否则 DSH 没法干活。

如果它有个「稍后配置」之类的按钮，先跳过也行，之后再按下面步骤补上。

去申请密钥

DSH 自己不会思考，它要调用 DeepSeek 的模型来干活，所以需要一把「钥匙」。密钥在 DeepSeek 开放平台申请。

1. 打开 <https://platform.deepseek.com/usage>（未登录会先让你注册或登录）
2. 登录后，在控制台里找到 API keys / API 密钥 一栏
3. 点创建，名字随便起（比如 dsh），然后 复制生成的密钥
4. 密钥长这样：sk-xxxxxxxxxxxxxxxx

- 密钥只在创建时显示一次，关掉就再也看不到了，务必当场复制存好。丢了只能删掉重建。
- 如果还没充值，调用模型会失败。在同一个控制台的 充值 / 用量 页面处理，具体计费和免费额度以平台说明为准。

把密钥填给 DSH

两种办法，挑一个：

办法一：在界面上填（推荐）

如果刚才那个「添加 API 密钥」的框还在，直接在它里面粘贴。

如果已经关掉了：进 DSH 的 设置，找到模型 / API 密钥相关的配置项，粘贴进去保存。

不同版本的菜单位置可能略有不同，认准 「模型」 或 「API Key」 字样即可。

办法二：用配置文件

新建一个文本文件 C:\Users\你的用户名\.dsh\.env（macOS 是 ~/.dsh/.env），内容写：

DEEPSEEK_API_KEY=sk-你的密钥

保存后，重启 DSH（在命令行窗口里按 Ctrl+C 停掉，再重新运行第 2 步的命令）。

注意 .dsh 文件夹以点开头，Windows 资源管理器可能看不到。在地址栏直接输 %USERPROFILE%\.dsh 就能进去。

密钥是敏感信息，别把它截图或发群里。

界面是中文还是英文？

DSH 内置英文和中文两种界面，自动跟随你的浏览器语言——中文浏览器显示中文界面，不用手动设置。

但上面说的那两个首次启动弹窗只有英文版，这个没办法，点掉就行。

第 4 步：测试能不能用

在 DSH 界面下方输入框里，随便发一句话试试，比如：

你好，介绍一下你自己

能正常回复就成功了。

如果报错，看下面对应情况。

出问题了看这里

| 报错/现象 | 原因和解法 |
| 命令提示 node 不是内部或外部命令 | Node.js 没装好，或装完没新开命令行窗口 |
| 界面提示 401 / 未授权 | 地址漏了 ?token=...，回命令行把完整地址复制过来 |
| 提示 端口被占用 | 已经有一个 DSH 在跑了，直接用那个；或换成 npx @deepseek-ai/dsh web --port 3081 |
| 发消息报鉴权失败 / 没有可用模型 | 密钥没配好。检查是否填对、是否重启了 DSH |
| 报余额不足 / insufficient balance | 去 <https://platform.deepseek.com/usage> 充值 |
| 一直卡住不动 | 第一次启动要下载插件，耐心等；网络不好会很久 |
| 想停掉 DSH | 在命令行窗口按 Ctrl+C |

关于密钥安全：别把密钥发到群里、截图里或提交到 GitHub。DSH 本身不会在界面上回显密钥。

之后每次怎么用

DSH 每次使用都要重新启动一次。步骤是：

1. 打开命令行窗口（Win + R → 输入 cmd → 回车，和第 1 步一样）

2. 切换到你想让 DSH 干活的文件夹（可选）

如果想让它处理某个具体项目，就先告诉它那个项目在哪。在命令行里输入 cd 加一个空格，然后把文件夹从资源管理器直接拖进命令行窗口（路径会自动填好），再按回车：

cd "拖进来的文件夹路径"

cd 是「切换文件夹」的意思。不切换也行——那就默认在打开命令行时所在的文件夹里干活。

拖拽是最省事的办法，不用手打路径。也可以右键文件夹 → 复制文件地址，然后粘贴。

3. 启动

npx @deepseek-ai/dsh web

然后和第一次一样：把打印出来的完整地址（带 ?token=）复制到浏览器。

之后启动不会再问「是否下载」了，会直接跑起来。

嫌每次都要开浏览器标签页的话，见下面的进阶用法，可以把它做成一个像桌面软件一样的独立窗口。

名词对照表

文档里出现的这些词，第一次接触可能不熟。看不懂的时候回来查：

| 词 | 大白话解释 |
| AI Agent（智能体） | 能「动手干活」的 AI。普通聊天 AI 只能告诉你怎么做，Agent 可以自己去做 |
| DSH | DeepSeek Harness，一个 AI Agent 工具。装在自己电脑上，用浏览器操作 |
| Node.js | 一个运行环境。DSH 要靠它才能跑，装一次就好 |
| npm / npx | 下载和管理软件的工具，装 Node.js 时自带，不用单独装 |
| 命令行 / 终端 / cmd | 那个黑底白字的窗口，用来输入命令。Win + R → cmd 打开 |
| 端口 / 3080 | DSH 在你电脑上占的「门牌号」，浏览器靠它找到 DSH |
| token | 一次性的通行证，证明是你本人打开界面 |
| API 密钥 | 让 DSH 能调用模型的「钥匙」，要去 DeepSeek 平台申请 |
| .dsh 文件夹 | DSH 存自己配置和资料的地方，在你的用户文件夹里 |
| AGENTS.md | 一份文本文件，用来告诉 DSH「我希望你怎么干活」 |

可选：把文件装到别的盘（比如 C 盘紧张）

DSH 通过 npx 下载的文件默认放在 C 盘：

C:\Users\<你的用户名>\AppData\Local\npm-cache

实际占用大约 214 MB，不算大。如果你的 C 盘空间充足，这一节可以不看。

想放到别的盘（比如 D 盘），改一次设置即可，以后所有 npm/npx 下载的东西都会去新位置：

1. 打开「文件资源管理器」，在地址栏输入 %USERPROFILE% 后回车（这会打开你的用户文件夹）
2. 新建一个文本文件，把文件名改成 .npmrc（注意前面有个点，没有 .txt 后缀）

如果改不了后缀：在资源管理器上方点「查看」→ 勾选「文件扩展名」，然后就能改全名了。

如果提示「必须输入文件名」：说明没打开扩展名显示，直接用英文引号包住文件名输入即可，比如输入 ".npmrc"。

3. 用记事本打开它，填入下面两行（把 D:\ 换成你想放的盘）：

cache=D:\nodejs\npm-cache
prefix=D:\nodejs\npm-global

4. 保存，然后关掉命令行窗口，重新打开一个（设置才会生效）

之后 DSH 下载的文件就会进 D:\nodejs\npm-cache。

这个设置影响所有 npm 相关的下载，不只是 DSH。如果你装完想改回来，把这两行删掉即可。

也可以不建文件，改用系统环境变量设置 npm_config_cache 和 npm_config_prefix，效果一样。

进阶用法

入门四步做完就能正常用了。下面两件事是可选的，但能明显提升体验。

一、让 DSH 记住你的习惯（AGENTS.md）

用久了你会发现，有些话每次都要重复交代——「用中文回答」「改文件前先说一声」「我的资料在哪个文件夹」。

这些可以写成一个文件让 DSH 自动遵守，不用每次重复。这个文件就叫 AGENTS.md。

三步就能用上：

1. 用记事本新建一个文件，写上你的要求（比如「回答使用中文」）
2. 存到 C:\Users\<你的用户名>\.dsh\AGENTS.md
3. 不用重启，直接问 DSH：「你看到我的 AGENTS.md 了吗？」

它能复述出来，就说明生效了。它就是个纯文本文件，不需要会编程。

完整写法（怎么组织内容、有哪些坑、可直接复制的模板）见 附录 B。

二、把它整成「伪桌面端」

DSH 默认在浏览器标签页里打开。如果你希望它看起来像个正常的桌面软件——独立窗口、任务栏图标、双击即用——可以花几分钟配一下。

操作流程见 附录 A，出问题查 附录 C。

参考

- 官网：<https://www.deepseek.com/harness/>
- 开放平台（申请密钥、看用量）：<https://platform.deepseek.com/usage>
- 开发者文档：<https://deepseek-harness.github.io/deepseek-harness/guide/quickstart>
- 源码：<https://github.com/deepseek-ai/deepseek-harness>
- Node.js：<https://nodejs.org>

附录 A：让智能体帮你整成「伪桌面端」

做完之后，DSH 会变成一个独立的应用窗口——有自己的任务栏图标，没有地址栏和标签页，双击就能打开，用起来和普通桌面软件差不多。

遇到问题先翻 附录 C：排错手册，那里按「现象」整理，比从头读快。

你自己不用动手，把下面这段话整个复制，发给你正在用的任意一个 AI 智能体（包括 DSH 自己）就行。

把方括号里的内容换成你自己的：

复制这段话发给智能体

请帮我把 DSH（DeepSeek Harness）的网页界面做成一个独立的桌面应用窗口。

我的情况：

- 系统是 Windows
- DSH 的界面地址是 http://127.0.0.1:3080/
- 我用的浏览器是 Edge
- Edge 应用的 app-id 是 [在这里粘贴你的 app-id]（获取方法见下，如果你能从系统里自己找到，就不用我填）

我希望你做到：

1. 做一个启动器脚本 DSH.cmd，双击后：先检查 3080 端口上有没有 DSH 服务在跑；没有的话就用 npx @deepseek-ai/dsh web --no-open 把它启动起来（--no-open 必须有，否则会多弹一个浏览器标签页）；轮询等端口就绪后再打开应用窗口。
2. 启动服务器时不要硬编码 npx 缓存路径，用 npx 加包名 @deepseek-ai/dsh。
3. 等就绪要有真实探测，不要用固定 sleep，最长等 45 秒后给出明确报错。
4. 用 Edge 应用模式打开窗口，命令是 msedge_proxy.exe --profile-directory=Default --app-id=<app-id> --app-launch-source=4 --app-url=<地址> （--app-url 放最后，避免 URL 里的 & 截断后面的参数）。
5. 做一个桌面快捷方式指向这个脚本，运行方式设为「最小化」。
6. 做完后实际测试一遍：确认服务能起来、应用窗口能打开、并且没有多余的浏览器标签页。

需要你注意：

- 不要动我正在运行的服务进程，那会中断我当前的会话。
- 如果 3080 上已经有服务在跑，测试时就用已有的，别去杀掉它。
- 写批处理脚本时，echo 的提示文字用英文——中文存成 UTF-8 后在 cmd 窗口里会乱码。
- 密码/密钥类信息不要写进脚本。

怎么拿到 app-id

如果上面那段话里的 app-id 你填不出来，先做这一步（只需一次）：

1. 先启动 DSH，用 Edge 打开界面地址
2. 点 Edge 右上角 … → 应用 → 将此站点作为应用安装，名字随便填
3. 桌面上会出现一个快捷方式，右键 → 属性
4. 看「目标」那一栏，末尾有 --app-id= 后面跟的一串字符，复制那一串
5. 把它填进上面那段话里

这串东西每台电脑都不一样，必须用你自己复制到的。换电脑或重装 Edge 之后会变，得重新拿一次。

做完了会是什么样

- 桌面上多一个 DSH 快捷方式，双击就打开 DSH，不用再开终端敲命令
- 打开后是一个独立窗口，没有地址栏和标签页，任务栏上有自己的图标
- 可以右键固定到任务栏

两个要知道的点

- 启动时会有一个最小化的黑窗口留在任务栏，那是 DSH 服务器本体，别关它，关了服务就停了。
- 想把这个黑窗口也藏掉需要额外折腾（用 VBScript 包一层），稳定性会差一些，不太建议。

出问题（弹出两个界面、窗口空白、图标不对等）见 附录 C：排错手册。想彻底隐藏黑窗口见附录 C 的「现象 8」。

附录 B：怎么写 AGENTS.md

一、AGENTS.md 是什么

它是一个普通的 Markdown 文本文件。DSH 启动后会自动读取它，当成工作指令交给 AI。

写与不写的区别：

| 不写 | 写了 |
| 每次都要重复说「用中文回答」「改文件前先说一声」 | 说一次，以后每次都遵守 |
| AI 不知道你的项目结构，每次都要现找 | 直接告诉它文件在哪、该去哪查 |
| AI 可能凭记忆瞎猜，写出跑不了的东西 | 明确要求「必须查过再写」 |

一句话：把口头交代固化成文件。

二、放在哪里

有两个位置，作用范围不同：

| 位置 | 作用范围 |
| C:\Users\<你的用户名>\.dsh\AGENTS.md | 全局，你在任何文件夹里用 DSH 都生效 |
| <项目文件夹>\AGENTS.md | 只对该项目生效 |

建议：

- 通用规矩（回答语言、输出格式、工作习惯）放全局
- 项目专属信息（项目结构、参考资料在哪）放项目里

两者可以同时存在，会叠加生效（全局的先加载，项目级的后加载，越具体越靠后）。

Windows 上 .dsh 这个文件夹以点开头，资源管理器可能看不到。在地址栏直接输 %USERPROFILE%\.dsh 就能进去。

三、怎么确认它生效了

改完不用重启。DSH 会在你新建或修改文件后自动重新读取。

验证方法：写完之后，直接问 AI：

你看到我的 AGENTS.md 了吗？里面写了什么？

如果它能复述出来，就说明生效了。

有个例外：如果文件一开始不存在、你在会话中途才创建，一般也能立刻生效（DSH 会跟随文件操作重新扫描）。如果发现没生效，新开一个会话即可。

四、通用模板（可直接复制）

下面这份可以直接用。方括号里的内容改成你自己的，用不上的段落删掉。

复制下面整个代码块的内容，存成 AGENTS.md 即可——标题层级已经是正确的，不用调整。

工作指南

回答风格

- 回答使用中文。
- 对总结、方案、清单类的长内容，先用 Table 整理再输出；普通对话正常回答。
- 不要长篇铺垫，先给结论，再给理由。

工具使用

- 查找文件用 glob，搜索内容用 grep，不要用命令行去跑 find/grep。
- 改已有文件用 edit（局部替换）；新建或整体重写用 write。
- 改文件前必须先用 read 读过，不要凭印象改。
- 动手前如果涉及多个文件或不可逆操作，先说清楚打算改什么再执行。
- 改完报告实际产物的完整路径，不要只说"改好了"。

工作习惯

- 不确定的事先验证，不要猜。 猜出来的结论要说"我不确定"，并说明可以怎么验证。
- 验证时要用已知为假的条件做对照，避免"测了环境却以为测了代码"。
- 不要连续叠加没验证过的复杂度；一层没跑通之前不要加第二层。
- 不要动我正在运行的程序或服务进程，那会中断我的工作。

项目信息

- 项目路径：[你的项目路径]
- 这个项目是做什么的：[一句话说明]
- 重要文件在哪：[列出关键文件夹和用途]

信息检索顺序

需要查资料时，按这个顺序找，不要跳过前面直接上网搜：

1. [本地第一优先来源，例如某个自动生成的索引文件]
2. [本地第二优先来源，例如现成的同类文件]
3. [本地第三优先来源]
4. GitHub / 网上（前三步都查不到时才用）

输出格式模板

方案表格

| 文件 | 改动内容 | 预期效果 |
| path/to/file | 具体做什么 | 会变成什么样 |

禁止行为

- 禁止在没查证的情况下凭记忆编造具体名称、编号、参数。
- 禁止改动我没让你动的文件。
- 禁止把密钥、密码之类的敏感信息写进代码或配置。

五、各部分怎么写才有用

回答风格

最容易写、也最立竿见影的一段。直接写你想要的，比如：

- 用中文 / 用英文
- 简短直接 / 详细解释
- 要不要用表格、要不要列步骤

反例：回答要专业、准确、有帮助——这种话等于没说，任何 AI 默认都"想"这样。

正例：先给结论再给理由，超过 3 条的内容用表格——具体、可执行。

工具使用

如果你不知道 DSH 有哪些工具，可以先问它：

你能用哪些工具？各自适合干什么？

然后把答案整理进去。这一段的价值在于避免它用错工具（比如用命令行跑 grep，或者不打磨就直接删文件）。

信息检索顺序

这是最能提升产出质量的一段，尤其适合有本地资料的项目。

它的逻辑是：让 AI 先去查你的现成资料，查不到才允许它自己发挥。这能显著减少"看着像模像样、实际是编的"内容。

写的时候要具体到路径，例如：

1. 先查 D:\project\docs\ 下的设计文档
2. 再查 src\ 里的同类文件，复用现有写法
3. 最后才允许上网搜

禁止行为

把你踩过的坑写进来。比如：

- 上次它删错文件了 → 写"删文件前必须先确认"
- 上次它编了个不存在的名字 → 写"命名必须从 XX 文件里查，禁止自创"
- 上次它改了不该改的配置 → 写"禁止修改 XX 目录"

这段是长出来的，不是一次写完的。 每次发现 AI 做错什么，就补一条。

六、写完怎么迭代

建议这样用：

1. 先只写「回答风格」和「工具使用」两段——这两段最通用，马上有效果
2. 用几天，每次发现它做得不对就补一条
3. 攒到一定量后整理归类，删掉重复和没用的

不要太长。 DSH 对这份文件有 64 KB 的容量上限，超了会先丢掉范围更宽的内容——也就是说，写太多反而可能把重要规矩挤掉。控制在几 KB 以内最好。

判断标准：每一条都应该能对应一个具体的、它曾经做错或可能做错的行为。 写不出对应场景的，删掉。

七、几个容易踩的坑

1. 别把它当成"愿望清单"

写"希望 AI 聪明一点""要理解我的意图"这类没用。AGENTS.md 只对具体行为有效。

2. 别照抄别人的

别人的项目结构、参考资料路径都跟你不一样。结构可以参考，具体内容必须换成你自己的，尤其是路径。

3. 工具名要写对

不同 AI 工具的工具名不一样。写之前先问清楚你用的这个有哪些工具，否则写了它也没有。

4. 引用的路径要真实存在

写完之后逐个确认文件/文件夹真的在。引用一个不存在的路径，AI 会去找、找不到、然后开始猜——比不写还糟。

5. 不要在文件里放密钥

AGENTS.md 是明文文件，可能被同步、被分享。永远不要把 API Key、密码写进去。

八、参考：一份真实在用的 AGENTS.md

下面是作者本人正在用的一份（~\.dsh\AGENTS.md），可以直接看它的结构：

| 章节 | 作用 |
| 回答风格 | 中文 + 表格 |
| 工具使用 | 列出该环境实际可用的工具，以及"改文件前必须先读"这类硬规矩 |
| 角色定位 | 告诉 AI"你是谁""我的项目是什么" |
| 信息检索优先级 | ①→②→③→④ 四级，最后才允许上网 |
| 附属优先 | 有现成轮子就别自己造 |
| 知识索引 | 参考资料都在哪个路径 |
| 任务执行规范 | 收到需求后按哪几步走 |
| 命名规范 | 专有名词必须从哪个文件里查，禁止自创 |
| 输出格式模板 | 固定几种表格样式 |
| 禁止行为 | 红线清单，长出来的 |

注意它的写法：几乎每一条都是「去哪里查」或「不许做什么」，而不是「希望你怎么样」。这就是它有效的原因。

附录 C：伪桌面端排错手册

附录 A 是「怎么做」，这份是「做坏了怎么查」。按你看到的现象找对应条目。

这一节里的每条都是实际踩过的坑，不是推测。

现象 1：一次点击弹出两个界面

一个浏览器标签页 + 一个应用窗口，同时冒出来。

原因：dsh web 启动时默认会自动打开一个浏览器标签页。你的启动器又拉起了应用窗口，于是两个。

解法：启动服务器的命令里必须加 --no-open：

npx @deepseek-ai/dsh web --no-open

现象 2：应用窗口打开是空白页 / 连不上

原因：服务器还没起来，启动器就把窗口打开了。指向一个没人监听的端口，当然连不上——而且看起来像成功了（窗口确实开了）。

解法：启动器要有真实的就绪探测，不能用固定 sleep。

探测方法（VBScript / PowerShell 都可以）：

Set h = CreateObject("WinHttp.WinHttpRequest.5.1")
h.SetTimeouts 800, 800, 800, 1500
h.Open "GET", "http://127.0.0.1:3080/", False
h.Send
' 任何 HTTP 状态码（包括 401）都说明服务器活着 If Err.Number = 0 And h.Status > 0 Then WScript.Echo "server is up"

⚠️ 别用 MSWinsock.Winsock 这个组件——它在 Win10/11 上默认没有注册。

实测 WinHttp 探测只要 181 毫秒，比拉起一个 PowerShell 进程快得多。

现象 3：任务栏图标不对，或点开变成标签页

原因：没用 --app-id 启动。没有它，Edge 只会开一个普通标签页，不会给你独立窗口。

解法：确认启动命令里有 --app-id=<你的32位id>。

现象 4：改了图标，桌面还是显示旧的

原因：Windows 有图标缓存。

解法：刷新一下：

& "$env:SystemRoot\System32\ie4uinit.exe" -show

现象 5：固定「开始屏幕磁贴」做不到

原因：这不是你的问题——微软对 pintostartscreen 这个动作做了哈希校验，脚本模拟不了，杀软也会拦。

解法：只能手动。把快捷方式放进 %APPDATA%\Microsoft\Windows\Start Menu\Programs\，然后在开始菜单搜索它 → 右键 → 固定到「开始」屏幕。

现象 6：快捷方式点了没反应，或窗口一闪而过

原因：启动器里的某个路径失效了。最常见的是硬编码了 npx 缓存路径（里面有版本哈希，DSH 升级或缓存清理后就变了）。

解法：启动服务器时用包名，不要用缓存路径：

npx @deepseek-ai/dsh web --no-open

不要写成 C:\Users\...\npm-cache\_npx\<哈希>\...\dsh.cmd 这种。

现象 7：怎么确认 Edge 应用还注册着？

有时候图标文件夹会被 Edge 清理掉，让人以为应用失效了。其实注册信息在 Edge 的配置里，搜一下就知道：

$pref = "$env:LOCALAPPDATA\Microsoft\Edge\User Data\Default\Preferences"
这个文件是 UTF-8 且含中文，按字节读再解码，别直接 ConvertFrom-Json
$text = [System.Text.Encoding]::UTF8.GetString([System.IO.File]::ReadAllBytes($pref))

$text.Contains('你的app-id') # True = 还注册着
$text.Contains('"effective_display_mode":3') # 3 = 独立应用窗口模式
$text | Select-String -Pattern 'app_window_placement' -SimpleMatch

判断标准：

| 找到什么 | 说明 |
| app_window_placement._crx__<app-id> | 这个应用窗口确实以独立窗口运行过，注册有效 |
| "effective_display_mode":3 | 独立窗口模式（不是标签页） |
| Web Applications\_crx__<app-id>\ 文件夹没了 | 不代表失效，图标另有一份在 Web Applications\Manifest Resources\<app-id>\ |

现象 8：想彻底隐藏那个 cmd 黑窗口

先想清楚值不值。 start /min 已经能让它最小化到任务栏了。真要完全隐藏，得用 .vbs 包一层（wscript 是无窗口宿主）——复杂度显著上升。

如果决定要做，下面两个坑几乎必踩：

坑 1：VBScript 的 rem 是保留字

不要拿它当变量名。Dim rem 会直接编译失败，而且报错信息很隐晦（在别的行上报「缺少标识符」）。

坑 2：手写 Base64 极易出错

如果走 -EncodedCommand 传 PowerShell 命令，需要在 VBScript 里手写 Base64。两个必踩的点：

1. AscW 返回的是 UTF-16 码元，Base64 要按小端字节序输出：低字节在前，高字节在后。写反了单字符测试可能碰巧通过，长字符串就全错。
2. 必须按 3 字节一组编码。把「逐字符处理」和「分组编码」混在一个循环里，几乎必然写错。

写完一定要对照 .NET 输出验证，别凭感觉：

powershell
[Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes("AB"))

我实际试过这条路并最终回退了——考虑到上面两个坑，性价比不高。

现象 9：想给服务器输出存日志，但路径被拼坏了

这样写是错的： bat rem 错误示范 start "t" /min cmd /c ""%NPX_CMD%" @deepseek-ai/dsh web >>"%LOG%" 2>&1"

Windows 会弹窗报「找不到文件 ...\logs\test.log C:\Users\...」——路径被拼坏了。

原因：cmd /c "..." 里，重定向符必须在引号外面，但又不能破坏整体的引号配对。别试图用「加个哨兵参数」之类的技巧去打平衡，容易越修越乱。

稳妥做法：干脆不要重定向。服务器输出本来就在那个 cmd 窗口里，看得见。

现象 10：参数顺序写错，导致应用窗口打不开

--app-url 必须放在所有参数的最后一个。
bat
rem ✅ 正确 start "" "%EDGE_PROXY%" --profile-directory=Default --app-id=%EDGE_APPID% --app-launch-source=4 --app-url=%DSH_URL%

rem ❌ 错误：app-url 后面还有参数 start "" "%EDGE_PROXY%" --profile-directory=Default --app-url=%DSH_URL% --app-id=%EDGE_APPID% --app-launch-source=4

原因：URL 里如果带 &（比如 ?token=xxx&foo=bar），在命令行里会被当成参数分隔符，把后面的参数截断。

现象 11：想换一个自定义图标

Edge 应用自带一份图标缓存，路径是：

%LOCALAPPDATA%\Microsoft\Edge\User Data\Default\Web Applications\Manifest Resources\<app-id>\
32.png 48.png 64.png 96.png 128.png 256.png

⚠️ 注意这里全是 .png，不是 .ico。网上有些教程会写一个并不存在的 _crx__<app-id>\<名字>.ico，那是旧版 Edge 的路径，现在已经没有了。

做法：把你自己的 .ico 文件随便放个稳妥的地方（比如 ~\.dsh\assets\），然后在快捷方式属性里把「图标」指向它。

改完记得刷新图标缓存——见现象 4。

现象 12：用 cmd /c 调 PowerShell 报「不是内部或外部命令」

这样是错的（路径带空格时被截断）： bat cmd /c "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe" -Command "..." rem 报错：'C:\WINDOWS\...\powershell.exe" -Command "try{$c' 不是内部或外部命令

解法：优先考虑不用 PowerShell（见现象 2 的 WinHttp 方案）。确实要用的话，用 -EncodedCommand 传 base64，绕开引号问题。

一条方法论：验证方法本身也会骗你

这条比上面所有具体问题都重要。

我曾经用「这条命令能不能连上 3080」来验证命令是否可用——但 3080 本来就开着，命令即使失败也返回成功，于是一个错误结论被「验证通过」了。

规则：验证时要用已知为假的条件做对照（比如拿一个确定空闲的端口测），否则你测的是环境，不是你的代码。

给 AI 智能体的检查清单

如果你的智能体要帮你做这件事，让它逐条确认：

- [ ] 先确认 DSH 服务能正常启动、界面能打开（拿到带 token 的完整地址）
- [ ] 手动让 Edge 生成应用，从生成的快捷方式里读出 --app-id（不要猜）
- [ ] 启动器保留 --no-open，否则会出现两个界面（现象 1）
- [ ] 服务器启动用 npx @deepseek-ai/dsh web，不要硬编码 npx 缓存路径（现象 6）
- [ ] 端口就绪用真实 HTTP/TCP 探测，不要用固定 sleep（现象 2）
- [ ] --app-url 放到参数最后（现象 10）
- [ ] 改完快捷方式后刷新图标缓存（现象 4）
- [ ] 验证时用已知为假的条件做对照
- [ ] 不要动用户正在使用的服务器进程（会导致会话中断）
- [ ] 批处理脚本里的提示文字用英文——中文存成 UTF-8 后在 cmd 窗口里会乱码

一些取舍

| 需求 | 做法 | 代价 |
| 不要浏览器标签页 | 加 --no-open | 无 |
| 启动时不出现黑框 | 需要 .vbs 包一层 | 复杂度显著上升，不熟练容易翻车 |
| 任务栏独立图标 | 必须用 --app-id 启动 | 无 |
| 固定到开始屏幕磁贴 | 只能手动 | 无 |
| 免去 npm 每次检查版本 | 加 --no-install | 缓存被清理后启动器失效（实测省下的时间几乎为 0，不划算） |

附录 D：界面上的按钮都是啥意思

第一次打开界面，左边右边一堆东西，不知道点哪个。这份按区域解释一遍。

界面控件会随版本变化，位置可能略有不同，但含义是一样的。

先搞懂「工作区」（Workspace）

这是新手最容易卡住的地方。你可能会看到提示让你「选择一个工作区」，但你根本不知道工作区是什么。

工作区 = 一个文件夹。

DSH 是来帮你干活的，它得知道「在哪个文件夹里干活」。这个文件夹就叫工作区。比如：

- 你想让它整理 D:\照片 里的图片 → 就把 D:\照片 设为工作区
- 你想让它改某个项目的代码 → 就把那个项目文件夹设为工作区

怎么设？

1. 新建会话时，界面上会让你选择一个文件夹（通常有个「选择文件夹」或文件夹图标）
2. 点进去，浏览到你想让它操作的文件夹，确认
3. 这个文件夹就成了这次会话的工作区——DSH 之后的操作都围绕它进行

注意：

- 每个会话可以有不同的工作区（这次整理照片，下次改代码，互不影响）
- 你可以添加多个工作区，之后在列表里切换
- 没有「现成的工作区」要你选——工作区是你自己指定的文件夹，不是 DSH 预置的东西

💡 实在不确定选什么：就新建一个空文件夹给它，先熟悉功能再说。别一上来就指向重要文件。

文件访问权限（重要）

界面下方或设置里会有个权限选项，通常是这三个：

| 界面上的名字 | 含义 | 适合什么时候用 |
| 仅可查看 | DSH 只能看文件，不能改 | 只想让它读代码、分析问题 |
| 工作区内修改 ⭐ | 只能改工作区里的文件；想动外面的东西要先问你 | 推荐日常使用 |
| 完全权限 | 能改电脑上任何文件，不再询问 | 你完全信任这个任务时 |

怎么选？

- 新手建议用「工作区内修改」——它在便利和安全之间平衡得最好
- 选「完全权限」时，DSH 会弹一个警告框，要你确认「我已了解风险」。这不是走过场——它真的可以改你电脑上任何地方的文件，包括系统文件

⚠️ 「完全权限」的实际含义：DSH 改文件、执行命令都不会再问你。方便，但出错时也没人拦着。建议只在明确知道要做什么、并且工作区里没有重要文件时用。

模型选择

界面上能找到模型的下拉选项（可能叫 模型 或显示当前模型名，比如 deepseek-flash）。

| 术语 | 含义 |
| 模型 | 干活的 AI 大脑。不同模型能力、速度、价格不一样 |
| 推理强度 / Effort | 同一模型下，让它「想多久」。high 想得更多、更准但更慢更贵；low 快但可能粗糙 |

什么时候改？

- 日常用默认的就行，不用折腾
- 遇到需要仔细推理的难题（复杂逻辑、难调试的 bug），可以调到高推理强度试试
- 选完对下一次请求生效，正在跑的这一步不受影响（不会中途换脑子）

注意：如果某个模型显示选不了/不可用，通常是 API 密钥没配好，或者账号没有那个模型的权限。

代理模式（Agent 模式）

新建会话时可能让你选一个「模式」，常见的有四种：

| 模式 | 干什么用的 |
| 标准模式 | 功能最全，能干绝大多数活。默认选这个 |
| PTC 模式 | 让 AI 写一段程序来批量调用工具，擅长处理「要对很多文件做同样操作」的任务 |
| 极简模式 | 只给最基本的两个工具，用来测试模型裸能力（普通用户用不上） |
| 创造模式 | 用来自己定制新的 Agent 模式，属于进阶玩法 |

新手就用标准模式，别管其他的。

模式只能在空白新会话里切换——会话开始后就不能改了。

其他常见的按钮

| 你看到的 | 意思 |
| 新会话 | 开一个新对话。不同会话是独立的，互不干扰 |
| 设置（齿轮图标） | 配置 API 密钥、权限、界面语言等 |
| 模型选择 | 见上面「模型选择」一节 |
| 轨迹 / Trajectory | 看 AI 每一步具体做了什么（调用了什么工具、看到什么结果）。排查问题很有用 |
| 附件 / 回形针图标 | 上传文件给 AI 看（图片、文档等） |
| @ 引用 | 引用某个文件/文件夹，让 AI 直接去读，不用你描述路径 |
| 停止按钮 | 中断 AI 当前正在做的事 |

一个建议：第一次先别给重要文件夹

因为 DSH 真的会改文件，建议第一周这么做：

1. 新建一个空文件夹，比如 D:\AI试试
2. 把工作区设成它
3. 丢几个不重要的文件进去，让它练手
4. 熟悉了它的行为方式后，再指向真正重要的文件夹

- 官网：<https://www.deepseek.com/harness/>
- 开放平台（申请密钥、看用量）：<https://platform.deepseek.com/usage>
- 开发者文档：<https://deepseek-harness.github.io/deepseek-harness/guide/quickstart>
- 源码：<https://github.com/deepseek-ai/deepseek-harness>
- Node.js：<https://nodejs.org>