DeepSeek Harness 一键运行

解决的问题

DeepSeek Harness (DSH) 的部署并不复杂，但真正用起来时，环境依赖、快捷方式创建、版本升级这些环节都会消耗时间。尤其是 Windows 上沙箱环境的权限问题、桌面启动器找不到 dsh 命令的 PATH 问题，以及重复启动导致的端口冲突，都是实际使用中高频出现的障碍。

核心能力

• 环境体检：通过 scripts/dsh-manager.py doctor 检查 Node.js、npm、DSH 是否就绪
• 自动安装：检测并安装缺失的 Node.js，安装 DSH 本身，同时生成品牌图标与桌面快捷方式
• 多平台启动：支持 Web UI（默认 http://127.0.0.1:3080）和命令行两种启动方式
• 桌面快捷方式：Windows 生成 .lnk（ICO 图标），macOS 生成 .app（ICNS），Linux 生成 .desktop（PNG）
• 平滑升级：升级前自动备份 DSH_HOME 到 ~/.dsh-manager-backups/config，保留 API Key 和工作区配置
• 卸载支持：清理已安装的 DSH 和相关文件

关键步骤

1. 环境体检：运行 python scripts/dsh-manager.py doctor，确认运行环境是否满足要求
2. 自动安装：执行 python scripts/dsh-manager.py install，自动处理依赖安装和快捷方式创建
3. 启动服务：运行 python scripts/dsh-manager.py start --web --check-update，启动 Web UI 并检查更新
4. 首次配置：在浏览器打开后，在设置中填入 DeepSeek API Key（格式 sk-...）
5. 平滑升级：使用 python scripts/dsh-manager.py update --yes，自动备份并升级

注意点

• Windows EPERM 错误：在沙箱中启动 DSH 会对 ~/.dsh 下已有文件的 rename/open 报 EPERM，必须非沙箱运行。排查时先检查是否有残留的 Node 进程持有文件句柄，再检查文件属性和 ACL
• PATH 问题：如果 dsh 安装在 WorkBuddy 托管 Node 的全局目录，而桌面启动器的干净环境 PATH 不含该目录，会导致 shutil.which("dsh") 返回 None，需要在 .bat 中手动注入 PATH
• 端口占用：重复启动时如果 3080 端口已被 DSH 自身占用，属正常冲突而非故障。dsh-manager.py start --web 内置预检逻辑，会检测 HTTP 响应并自动打开浏览器
• 配置文件位置：DSH 配置和日志默认存储在 ~/.dsh，API Key 凭据在 .credentials.yaml 中，操作前务必备份
• 图标生成：通过 python scripts/dsh-manager.py icons 生成 SVG、PNG、ICO、ICNS 多种格式的品牌图标，输出到 assets/ 目录