便携安装器 RiveDroite1795/deepseek-harness-portable

deepseek-harness-portable

把 DeepSeek Harness 装进一个文件夹：命令行走天下，删掉文件夹就是卸载。

English · 简体中文 · 故障排查

一个零依赖的 Python 安装器，为 DeepSeek Harness（@deepseek-ai/dsh）一次性解决三件事：

| 你想要的 | 本工具怎么做 |
| 终端里敲 dsh 就能用 | 生成入口脚本，并把所在目录写入用户 PATH |
| 只占一个文件夹，卸载=删文件夹 | npm --prefix + --cache 双锁定在安装根目录内，程序与缓存同进同出 |
| 桌面双击打开 Web 界面 | 生成启动器，自动抓取一次性 token 链接并打开浏览器 |

DeepSeek Harness 是什么

DeepSeek Harness（DSH）是 DeepSeek 官方以 npm 包 @deepseek-ai/dsh 形式发布的 agent harness，带命令行界面，并在 http://127.0.0.1:3080 提供本地 Web 界面。上游给了三条安装路径：npx @deepseek-ai/dsh web、全局 npm i -g @deepseek-ai/dsh、或源码构建 pnpm。

这三条都会把状态散落各处：全局安装写进共享的 npm prefix，npm 缓存落到全局目录。本安装器面向相反的需求：一个自包含文件夹、一个真正的终端命令、其余地方不留任何残留。

为什么用 Python 而不是 shell 脚本

.cmd 或 .ps1 安装器只在它所属的 shell 里好用。Python 安装器在 cmd、PowerShell、bash、zsh、fish 下行为完全一致，也不受执行策略、引号规则、代码页影响。不需要 pip 步骤——全部为标准库，Python 3.8+ 即可。

环境要求

- Python 3.8 或更高
- Node.js ^22.19.0 || >=24.0.0
- Node 23.x 会被明确拒绝 —— 这是奇数版本、非 LTS，上游 engines 已排除。请用 22.19+ 或 24+。
- 不需要管理员权限，全部装在用户目录下。

快速开始

git clone https://github.com/RiveDroite1795/deepseek-harness-portable.git
cd deepseek-harness-portable
python dsh_installer.py

五步向导会依次询问：

1. 文件夹名称 —— 默认 DeepSeekHarness。若输入 dsh 会告警，因为它与配置目录 ~/.dsh 冲突。
2. 安装位置 —— 默认在用户目录下，并在动手前先校验盘符是否存在。
3. 代理 —— 可选，留空表示直连。
4. 加入 PATH —— 是否让 dsh 成为终端命令。
5. 桌面启动器 —— 是否创建双击快捷方式。

免交互等价写法：

走本地代理装到默认位置
python dsh_installer.py install --yes --proxy http://127.0.0.1:7890

指定位置与文件夹名
python dsh_installer.py install --yes --path D:/Apps --folder DeepSeekHarness

只预览，不写任何文件
python dsh_installer.py install --dry-run

不使用代理
python dsh_installer.py install --yes

装完请新开一个终端（PATH 变更对已打开的窗口不可见），然后：

dsh # 打开 Web 界面
dsh --help # 查看命令行用法
dsh web # 与不带参数相同
dsh # 原样转发给 Harness CLI

命令一览

python dsh_installer.py status # 装在哪、什么版本、PATH 状态
python dsh_installer.py doctor # 体检：文件 / 端口 / 陈旧锁 / PATH
python dsh_installer.py doctor --fix # 顺带修复可安全修复的项目
python dsh_installer.py uninstall # 先列出，再询问，然后才删除
python dsh_installer.py uninstall --purge-config # 连 ~/.dsh（账号与凭据）一起删
python dsh_installer.py uninstall --dry-run # 只列出，绝不删除
python dsh_installer.py purge # 彻底清空回收目录
python dsh_installer.py path-restore # 从备份还原用户 PATH

全局参数 --no-colour 放在子命令前后都可以。status 与 doctor 不需要任何权限。

卸载到底删了什么

默认只删本安装器自己创建的东西：

✓ 安装目录 \DeepSeekHarness\ （程序 + 私有 npm 缓存） ✓ 终端入口 ~\bin\dsh.cmd ✓ 桌面启动器 ~\Desktop\DSH Web.cmd ~ ~\bin 从用户 PATH 中移除（只删这一条，其它条目不动） ✗ 配置目录 ~\.dsh 默认保留 —— 加 --purge-config 才删

两条安全设计：

1. 先列表、再确认，默认答案是「否」。 uninstall 会先打印每一项的路径与体积，再问任何问题。
2. 删除是「移动到回收目录」，不是销毁。 文件进入 ~/.dsh-portable/trash//。确认无误后跑 purge；想反悔就直接把文件夹移回原位。

uninstall --dry-run 的保证在代码层，而非靠约定：只要 execute() 拿到的 plan 被标记为 dry-run，它就会抛异常而不是删除。

安装做了什么

六个阶段，全部记入运行报告：

| 阶段 | 内容 |
| 1. 环境检查 | 校验 Node 与 npm；版本不合规会拒绝并说明原因 |
| 2. 准备目录 | 非空且不是上次安装的目录时中止，而不是覆盖 |
| 3. npm install | 执行 node npm-cli.js，--prefix 与 --cache 都锁在安装根目录内 |
| 4. 安装脚本 | 按需重跑 npm 跳过的脚本 |
| 5. 生成启动器 | 写入 launch-web.cmd / dsh.cmd / 桌面启动器；POSIX 下生成对应的 .sh |
| 6. 配置 PATH | 读-改-写注册表，保留 REG_EXPAND_SZ，改动前先备份 |

每次运行都会在 ~/.dsh-portable/ 写入 install-report-.json，包含环境、耗时、各阶段结果，以及每一条警告和错误。安装成功还额外写 last-install.json 作为清单，卸载时按它精确删除。

跨平台支持

| 平台 | 支持情况 |
| Windows 10 / 11 | 完整支持 —— PATH 走注册表，启动器为 .cmd |
| Linux / macOS | 安装、启动器、PATH 写入均已实现（.sh + shell profile 中的标记块）；桌面启动器仅 Windows |

Windows 路径是端到端实测过的。POSIX 路径的代码已写完并做过静态核对，但尚未在真实 Linux/macOS 机器上跑过，请按"未验证"看待，遇到问题欢迎反馈。

实测踩过的坑（均已处理）

以下都不是推测，都是开发中真实复现并修掉的。

dsh web 需要一次性 token

裸访 http://127.0.0.1:3080/ 返回 HTTP 401，只有带 token 的 URL 才返回 303。token 由 dsh web 启动时打印：

dsh web: http://127.0.0.1:3080/?token=...

因此启动器必须抓取这一行，写死 URL 不可能工作。本项目在 Windows 用 findstr、在 POSIX 用 sed 抓取，并另有一份等价的 Python 正则用于交叉校验。

让 npm 走 npm-cli.js 入口，而不是包装脚本

受限环境里，npm.cmd 外面往往还套了一层策略脚本。npm 的清理阶段会一次性删除数百个临时文件，这一步被中断时整个安装随之回滚并以非零码退出——尽管所有下载都已成功。执行 node 是直接走 npm 自己的 JavaScript 入口，不经过包装脚本，清理阶段因此能正常跑完。

.cmd 文件里绝不能放非 ASCII 文本

中文 Windows 用 OEM 代码页（GBK）重读批处理文件。含中文注释的 UTF-8 文件会被解码出破坏命令解析的字节。本项目生成的所有 .cmd 一律使用纯 ASCII 英文注释与 CRLF 行尾。

绝不要用 setx 改 PATH

setx 会在 1024 字符处截断，并把 REG_EXPAND_SZ 悄悄降级为 REG_SZ，导致正常 PATH 里其它 %USERPROFILE% 之类变量不再展开。本安装器直接读改写 HKCU\Environment\Path，保留原类型，并先备份。

陈旧锁文件会让启动永久失败

dsh 在写 .credentials.yaml 前会拿写锁。若上一个进程被强杀——Ctrl+C、关窗口、taskkill /F、崩溃——锁文件会残留，之后每次启动都永久失败并报：

atomic-write: timed out waiting for the writer lock at
~/.dsh/.credentials.yaml.lock

锁文件里只有持有者 PID，所以死活是可判定的。doctor --fix 仅在确认该 PID 已死时才删除；活进程持有的锁一律保留，因为误删活锁会造成数据竞争，比启动失败严重得多。~/.dsh/profiles/node_modules.lock 同样会残留。

其它已处理的细节

- 别把文件夹叫 dsh —— 配置目录是 ~/.dsh。向导会告警，默认值为 DeepSeekHarness。
- dsh --help 会初始化 profile。 它不只是打印文本，而是在 ~/.dsh/profiles/ 下安装完整依赖树。首次调用较慢，属正常。
- 盘符不存在时报的是干巴巴的 WinError 3: 'D:\'。向导与安装器都会校验盘符并直说。
- 桌面启动器用 .cmd 而非 .lnk。 创建快捷方式需要 COM（WScript.Shell），受限环境下不可用；一个小批处理文件到处能跑。

项目结构

deepseek-harness-portable/
├── dsh_installer.py 入口：argparse 子命令 + 交互向导 ├── dshportable/ │ ├── ui.py 彩色输出、提问、五步向导 │ ├── platform.py Node/npm 探测与版本门禁 │ ├── npm.py npm 驱动（一律经 npm-cli.js） │ ├── launcher.py 生成 .cmd / .sh 启动器 │ ├── pathsetup.py PATH 增删改（注册表 / shell profile） │ ├── installer.py 安装编排 + 结构化报告 │ ├── uninstaller.py 卸载：清单、列出、回收站式删除 │ └── diagnostics.py 健康检查与安全修复 ├── docs/TROUBLESHOOTING.md 详细的故障模式与解法 ├── README.md 英文版 ├── README.zh-CN.md 本文件（简体中文） └── LICENSE MIT

环境变量

| 变量 | 作用 |
| NO_COLOR | 关闭彩色输出（等同 --no-colour） |
| LOCALAPPDATA | Windows 下默认安装位置的父目录 |
| DSH_HOME | 覆盖 Harness 自身的配置位置（本安装器不设置它） |

生成的启动器会设 NO_PROXY=localhost,127.0.0.1,::1，确保本地 Web 界面流量不经过代理。

常见问题

需要管理员权限吗？
不需要。全部位于用户目录下，PATH 改动针对 HKCU\Environment\Path。

能装到非默认位置吗？
可以——用 --path 与 --folder，或回答向导第 2 步。路径请避免非 ASCII 字符与空格。

怎样彻底删干净？
先 python dsh_installer.py uninstall --purge-config，再 python dsh_installer.py purge。

为什么首次 dsh --help 很慢？
它会触发 profile 初始化，将完整依赖树装进 ~/.dsh/profiles/。

为什么拒绝 Node 23？
上游 engines 为 ^22.19.0 || >=24.0.0。23.x 是奇数版本线，该包明确排除。

Web 界面显示 401 怎么办？
裸地址返回 401 是预期行为。请使用 dsh web 打印的带 token 的 URL，或直接运行启动器。

报告文件在哪？
~/.dsh-portable/ —— 含 install-report-.json、uninstall-report-.json、last-install.json、PATH 备份与回收目录。

许可

MIT，见 LICENSE。