DeepSeek Harness 第一次跑起来:环境探测与最小闭环
从 0.2.2-rc.3 版本号到 3765 端口,把安装形态、数据目录与三个 profile 一次探清,附 Node 版本坑。
我把 DeepSeek Harness(下文简称 DSH)当黑盒用了一个月,直到一次 headless 任务连续三次失败在同一个地方,才发现自己连它的安装形态都没搞清:我以为它是个 npm 包,实际它是 Electron 桌面端 + 一套自带 runtime 的 CLI 壳。这篇把这个最小闭环补上——怎么确认版本、数据落在哪个目录、三个 profile 各自干什么、一条命令怎么真的跑通。所有结论都来自本机实测,路径统一脱敏为 admin。
一、先确认你跑的是哪一个 node
第一刀就砍在这里。系统里装的是:
node -v
# v22.19.0而 Harness 自带的运行时完全是另一套。resources\runtime\versions.json 里写着:
{
"schemaVersion": 1,
"node": "24.21.0",
"pnpm": "11.28.5"
}resources\runtime\primary-runtime\runtime.json 更完整,还带 payloadDigest 和 Python 侧信息:
{
"desktopVersion": "0.2.2-rc.3",
"platform": "win32",
"arch": "x64",
"python": "3.12.14",
"node": "24.21.0",
"pnpm": "11.28.5",
"pythonPackages": { "python-docx": "1.2.0", "openpyxl": "3.1.5", "Pillow": "12.3.0" }
}意思很明确:Harness 里的每个工具都跑在 node 24.21.0 上,跟你的系统 node 没有关系。我最早的一次误判就是拿系统 node 去复现工具里的报错,复现不出来,白花了两小时。Python 也一样——load_workspace_dependencies 这个工具返回的就是内置 3.12.14 那套,里面有 pandas 3.0.1、openpyxl 3.1.5、Pillow 12.3.0,不需要你自己 pip install。
CLI 入口只有一个:
"D:/software/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd" --version
# 0.2.2-rc.3二、app.asar 不是可读的源码目录
我本来想直接读实现来印证行为,结果 app.asar 有 209,021,953 字节(约 199 MB),而 app.asar.unpacked 里只有一个空的 dsh 目录。用文件工具 stat 里面的路径直接被拒:
{ "code": "PATH_RESTRICTED",
"message": "stat: Links, reparse points and special objects are not traversed" }这条错误值得记:它不是"文件不存在",而是"这是一个特殊对象,我不进去"。第一次看到它我以为是权限问题,折腾了半天 ACL 才发现方向错了。所以本文所有涉及内部机制的描述,凡未标注来源的,都是从工具行为反向推断的,不是从源码读出来的。这个区分很重要——凡是我推断的,我都写"推断"。
三、真正的主战场是 ~/.dsh
安装目录只读,数据全在 C:\Users\admin\.dsh。实测结构:
| 路径 | 作用 | 实测证据 |
|---|---|---|
sessions/\<工作区编码\>\<会话ID>\session.v4.jsonl.zstd | 会话事件流 | --D-new-- 下一个会话 716,402 字节 |
storages/workspace.json | 工作区清单 | 含 6 个 workspaceId、archivedSessionIds |
storages/session_projcache/sessions/*.json | 会话投影缓存 | "version": 7,行内是 {ver, seq, val} |
profiles/{desktop,headless,web}/ | 三套配置 | 每套都有 cordis.yml + cordis.patch.yml |
cordis.patch.yml | 全局 patch 层 | rea MCP 就是在这里挂的 |
settings.yaml | provider 与模型表 | 330 行,magpie/anyrouter 等多个 provider |
skills/ | 技能目录 | craft-anything、design-taste-frontend 等 |
dsh-ops/{acl-backups,shells} | 运维产物 | 一份 ACL 备份 JSON(见沙箱篇) |
工作区编码很直观:当前项目 D:\new 对应目录名 --D-new--,路径分隔符换成 -、盘符前加 --。有中文的路径会变成百分号式编码,例如 --D-JY-~65B0~5EFA~6587~4EF6~5939-- 就是 D:\JY\新建文件夹。这个编码规则不是我猜的,是 sessions/ 下 11 个工作区目录并排看出来的。
会话文件是 zstd 多帧压缩的 JSONL,不是一个完整 zstd 流。我第一次用单次 decompress 只解出 1 条 session 事件,还以为文件坏了;改成循环 decompressobj + unused_data 再解,同一个文件得到 199 帧、540 条事件。事件类型分布也印证了架构:
tool/ptc-dispatch-start 90 tool/ptc-dispatch 90
step/start 58 step/end 58
assistant/message 56 tool/call 56 tool/result 56
user/message 17 agent/inbox/spliced 12
job/registered 10 job/settled 10
llm/retry 3 turn/start 2 turn/end 2
session 1 sandbox/mode 1 permission/preset 1ptc-dispatch 比 tool/call 多,正是 PTC 的痕迹:一个程序里发多次派发,模型层只算一次调用。
四、三个 profile 的分工
dsh --help 把机制说清了:profile 是"插件包 patch 层的有序栈",你自己的覆盖压在最上面。
Usage: dsh [--profile] <name> [options] [app-args...]
dsh plugin --profile <name> <pnpm-args...>
Options:
--profile <name> the profile under $DSH_HOME/profiles to boot
--from-default-profile <name> replace a custom profile with a fresh copy of a shipped template
--patch <path> extra patch-list overlay applied after the profile layer (repeatable)
--dump-config print the composed profile tree and exit三个 profile 的差别在 package.json 的 bundles 里。profiles/web/package.json:
{ "name": "dsh-profile-web",
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"] } } }desktop:桌面 GUI 用,就是你现在看到的窗口。web:只跑浏览器 UI,dsh web --help支持--host / --port / --public-url / --trusted-host / --tls-cert / --tls-key / --no-open。--port 0让操作系统分配空闲端口。headless:一次性任务,--json输出 NDJSON 事件流,--approval-policy ask|never,--add-dir给 workspace-write 加目录。默认 600 秒超时、超时返回码 124(见DSH转发使用说明.md)。
一个容易被忽略的语义:--public-url 是广告,不授权;真正决定 /api 接不接受这个 Host 的是 --trusted-host。反代场景配错这两个,表现就是页面能开、接口 403。
五、最小闭环:端口和一条命令
Web GUI 默认落在 127.0.0.1:3765。实测:
netstat -ano | grep ":3765"
TCP 127.0.0.1:3765 0.0.0.0:0 LISTENING 19468PID 19468 的进程名就是 DeepSeek Harness。注意它绑的是 127.0.0.1 而不是 0.0.0.0——想局域网访问必须显式 --host 一个本机网卡字面量,通配地址会被直接拒绝(help 原文:wildcard addresses are rejected)。
另一条闭环走 headless:
dsh --profile headless "列出当前目录的文件,只输出文件名"这条命令会真的动盘。我第一次用它做测试,它在 D:\JY\test 里自己建了文件——这不是聊天,权限直接继承桌面端配置。所以 --cwd 一定要指对,复杂任务前先备份。
六、我踩过的坑
我以为:装好客户端,CLI 就自动在我 PATH 上。 实际:PATH 上没有
dsh,得用resources\runtime\cli\bin\dsh.cmd全路径,或者自己在 profile 里用plugin --profile装。
我以为:
--public-url https://example.com/ui/设了就能对外。 实际:还得--trusted-host example.com,否则浏览器信任栅栏把/api挡掉。
我以为:headless 失败了会重试。 实际:默认 600 秒硬超时,超时就是 124,重试是你自己的事。
复盘
环境探测这一步大概要花 20 分钟,但省下来的是一整天:知道 node 是 24.21.0 而不是系统那个 22,知道数据在 ~/.dsh 而不是 AppData,知道会话是 zstd 多帧而不是单流,知道三个 profile 的数据互不相同——后面所有"为什么我改了配置没生效"的问题都能自己回答。下一篇讲 run_code,为什么我宁可写 15 行程序,也不愿意连着调三次工具。