deepseek harness傻瓜式操作，一键运行、更新（含桌面快捷方式启动）

概述

DeepSeek Harness 管理技能

目的

管理 DeepSeek Harness（DSH）的完整生命周期：环境体检、自动安装、启动、桌面快捷方式创建、版本检查与平滑升级。

使用时机

在出现以下任一需求时触发此技能：

• 安装 DeepSeek Harness / DSH
• 启动 DeepSeek Harness（Web UI 或命令行）
• 创建 DeepSeek Harness 桌面快捷方式
• 更新 / 升级 DeepSeek Harness
• 卸载 DeepSeek Harness
• DeepSeek Harness 无法启动，或 dsh 命令不可用
• 首次配置 DeepSeek API Key

核心脚本

使用流程

1. 环境体检

运行环境检查，确认 Node.js、npm、DSH 是否就绪：

python scripts/dsh-manager.py doctor

2. 自动安装

自动检测并安装 Node.js（如缺失）和 DeepSeek Harness，同时生成品牌图标与桌面快捷方式：

# Windows PowerShell
.scriptsinstall.ps1

# macOS / Linux
bash scripts/install.sh

# Python（跨平台）
python scripts/dsh-manager.py install --yes

3. 创建桌面快捷方式

# Windows
.scriptscreate-shortcut.ps1 -Force

# macOS / Linux
bash scripts/create-shortcut.sh --force

# Python（跨平台）
python scripts/dsh-manager.py shortcut --force

生成结果：

• Windows：%USERPROFILE%DesktopDeepSeek Harness.lnk（ICO 图标）
• macOS：~/Desktop/DeepSeek Harness.app（ICNS 图标）
• Linux：~/.local/share/applications/deepseek-harness.desktop 与 ~/Desktop/deepseek-harness.desktop（PNG 图标）

4. 启动 DeepSeek Harness

启动 Web UI，并自动检查是否有新版本：

python scripts/dsh-manager.py start --web --check-update

默认监听 http://127.0.0.1:3080。首次打开后，在设置中填入 DeepSeek API Key（格式 sk-...）。

5. 平滑升级

python scripts/dsh-manager.py update --yes

升级前自动备份 DSH_HOME 到 ~/.dsh-manager-backups/config，保留 API Key、工作区等配置。

环境变量

• DSH_HOME：DSH 配置与日志目录，默认 ~/.dsh。API Key 凭据（.credentials.yaml）存储于此。
• 查看建议配置：python scripts/dsh-manager.py env

日志

管理器日志位置：$DSH_HOME/logs/dsh-manager.log

查看最新日志：

python scripts/dsh-manager.py logs --tail 50

图标

品牌图标由 scripts/dsh-manager.py icons 生成，输出到 assets/：

• deepseek-icon.svg（矢量源文件）
• deepseek-icon.png
• deepseek-icon.ico（Windows）
• deepseek-icon.icns（macOS）

错误处理原则

• 所有错误输出均附带中文提示和修复建议。
• 安装 / 升级失败时优先检查网络、npm registry、权限（Windows 管理员 / Linux sudo）。
• 若 dsh 命令找不到，提示重新打开终端以刷新 PATH，或执行 doctor 检查。

启动失败排查（Windows EPERM）

启动时报 EPERM: operation not permitted（如 rename .credentials.yaml.tmp -> .credentials.yaml 或 open profiles/web/cordis.yml）时，按序排查：

1. 沙箱因素：沙箱内启动 DSH 会对 ~/.dsh 下已存在文件的 rename/open 报 EPERM，必须非沙箱（escalation）运行。
2. 残留进程：Get-CimInstance Win32_Process -Filter "Name='node.exe'" 检查是否有 DSH node 进程持有文件句柄（微信支付 MCP 等无关进程忽略）。
3. 文件属性：attrib 确认非只读；icacls 确认 ACL 含当前用户 (F)；cipher /c 确认未 EFS 加密。
4. 决定性测试：touch file + echo x >> file + mv file file.bak。若 touch/cp/mv 成功但 >> 失败 → 单个文件实例损坏/被锁（目录本身正常）。
5. 修复：备份 → mv 重命名坏文件 → 从备份 cp 重建 → 清理残留 → 重新启动。注意 .credentials.yaml 含 API Key，操作前务必备份。

启动成功验证：curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3080/ 返回 200，且 netstat -ano | grep :3080 有 LISTENING。

桌面启动器报"未安装"（PATH 问题）

双击 DeepSeek Harness.bat 时报 [错误] DeepSeek Harness 未安装，无法启动，但 doctor 显示已安装：原因是 dsh 装在 WorkBuddy 托管 Node 的全局目录（~/.workbuddy/binaries/node/versions/<ver>/），而 .bat 的干净环境 PATH 不含该目录，shutil.which("dsh") 返回 None。

修复：在 .bat 中 set MGR 之后注入：

set "NODE_BIN=<你的Node全局目录，如 %USERPROFILE%.workbuddybinariesnodeversions<版本号>>"
set "PATH=%NODE_BIN%;%PATH%"

验证：shutil.which('dsh') 在注入前为 None、注入后返回 dsh.CMD 路径。

重复启动报 EADDRINUSE（端口占用）

再次双击启动器（服务已在运行）时报 EADDRINUSE: address already in use 127.0.0.1:3080 堆栈错误：这是重复启动冲突，不是故障——先 netstat -ano | grep :3080 确认是否已有 DSH 实例监听。

已内置预检：dsh-manager.py 的 start --web 会先探测端口：

• 端口被占用且 HTTP 200（DSH 已在运行）→ 输出 [警告] 检测到 DSH 已在运行，自动打开浏览器，退出码 0，不再二次启动。
• 端口被占用但无 HTTP 响应（其他程序占用）→ 明确报错并建议换端口：start --web --port <新端口>。

手动处理：netstat -ano | grep :3080 找到 PID → Stop-Process -Id <PID> -Force 释放端口后重新启动。

参考文档

• 详细使用说明：references/usage.md
• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• DeepSeek API 平台：https://platform.deepseek.com/