DeepSeek-Harness-Local-svpts

DeepSeek Harness Local svpts

DeepSeek Harness 的本地部署套件：把 deepseek-harness（DeepSeek 开源 Agent 框架，MIT，developer preview）包装为 常驻系统托盘的桌面应用（看门狗 + 桌面壳合一），配一键启停脚本。

项目声明

• 本项目使用 Cherry Studio + DeepSeek API 通过 Vibe Coding 方式完成；
• 主要目的是自用（个人本地部署环境）；
• 基于上述原因，若想要修改或填补漏洞，推荐自行分叉，而不是直接在本仓库提报；
• 因为 deepseek-harness 声称可能存在破坏性变更，把壳套在外面（外部包装 + 页面注入）比把壳作为插件嵌入其内是更稳健的选择；
• Linux 和 macOS 的具体部署与使用还未测试，待回到有相关设备的居所时再具体测试。

快速开始

自举安装（推荐，无需手动 clone）

从仓库页面下载单个文件 install.cmd（Windows）或 install.sh（Linux/macOS）→ 放到任意目录运行 → 缺失的 git/node/pnpm 自动安装（Windows 走 winget，Linux/macOS 走系统包管理器或 NodeSource/nvm）→ 自动 clone 仓库（含子模块）并完成部署。仓库内不含任何不可审查的二进制文件。

手动安装

:: 第一步（git 拉取后只需一次，可重复运行）：双击 deploy.cmd
::   自动审查 Node/pnpm/git/Ollama，补足 dsh-home/.env、初始化子模块、安装依赖并构建
:: 启动：双击 startrun.cmd
:: 停止：托盘右键"退出（停止后台服务）"，或双击 stopexit.cmd
:: 界面功能按钮区：📁打开会话存档 / 💾备份 / 📤迁移（工作区搬移）/ 🔄备份更新 / 📥恢复 / 🌐局域网
::   （局域网：默认关；开启后手机访问 http://<本机IP>:3280，首次需电脑端确认授权）
::   Linux/macOS：./deploy.sh && ./startrun.sh（停止 ./stopexit.sh）

跨平台

• 首次启动：托盘图标 + 窗口自动打开（loading 页即时反馈，后台就绪后切入真实 UI）
• 关闭窗口 = 回到托盘，后台继续运行；再次双击启动脚本约 2 秒唤起窗口
• 界面右上角 ⏻ 按钮：确认后完全退出（前端 + 后台）；其左侧 ⟳ 按钮：确认后彻底重启（前端 + 后台，整个应用 relaunch）
• 后台崩溃由看门狗自动重启（连续失败有退避与放弃保护）

主要功能

🗂 会话存档（备份 / 恢复 / 迁移）

界面功能栏（或独立菜单 backup.cmd）：

跨机迁移场景：旧机 💾 备份 → 新机安装 + 📥 恢复 → 会话与设置完整迁移。所有操作均弹图形化文件对话框选路径。

🌐 局域网转发（手机远程访问）

dsh 官方 CLI 硬性拒绝 --host 0.0.0.0（理由：会向网络暴露远程代码执行能力）。本套件通过壳内转发层实现局域网访问，harness 本身保持 127.0.0.1 监听、零修改：

1. 功能栏点 🌐 局域网 开启（默认关闭；状态栏可见开关状态与本机 IP）
2. 手机连同一 WiFi，浏览器访问 http://<本机IP>:3280（0.0.0.0:3280 反向代理 → 本机 dsh 端口，HTTP + WebSocket 双转发）
3. 首次访问看到申请页（大按钮"申请访问"）→ 电脑端弹确认框（显示申请设备 IP）→ 允许后自动进入
4. 确权持久：授权记录于 desktop\lan-auth.json（已 gitignore），局域网状态不变则无需重复授权
5. 撤销：删除该文件即全部失效（下次访问重新申请）

安全边界：默认拒绝 + 人类确认授权；建议仅在可信 WiFi 使用。

🖥 托盘应用（看门狗 + 桌面壳）

• 生命周期：关窗 = 回到托盘、后台继续运行；托盘右键或界面 ⏻ 按钮 = 完全退出（前端 + 后台）；⟳ 按钮 = 彻底重启（确认后整个应用 relaunch，新进程重跑看门狗并重新拉起后台）
• 自绘顶栏（无边框窗口）：⟳ 彻底重启 / ⏻ 完全退出 / ─ 最小化 / ⛶ 最大化-还原 / ✕ 关闭窗口（自右向左，整条可拖拽移动窗口）
• 底部状态栏：后端在线状态（每 5 秒探测）+ 端口（启动时实测选定，自动跳过 Windows 保留段）+ 工作区路径 + 局域网开关 + 本机局域网 IP + 版本
• 看门狗：后台崩溃自动重启（连续失败有退避与放弃保护，恢复后自动复位）

环境要求

• Windows 10/11 x64；Node.js ≥ 22.19（或 ≥ 24）；pnpm（仓库内按 packageManager 自动采用 11.7.0）
• Ollama（默认本地模型 qwen3:8b）或 DeepSeek API Key（UI 内配置）
• 首次使用：cd desktop && npm install；在 dsh-home\ 创建 .env 写入 OLLAMA_PLACEHOLDER_KEY=ollama（本地无鉴权服务器所需占位凭证）

目录结构

├── startrun.cmd / startrun.sh    # 一键启动（托盘应用；Windows GBK+CRLF）
├── stopexit.cmd / stopexit.sh    # 一键停止（托盘应用 + 后台服务）
├── deploy.cmd / deploy.sh        # 一键部署：拉取后环境审查与补足（幂等，可重复运行）
├── backup.cmd + backup-restore.ps1   # 对话存档备份/恢复/更新（Windows；PowerShell 内置压缩，零依赖）
├── install.cmd / install.sh      # 自举安装器（单文件下载即装，见"快速开始"）
├── references\         # 设计参考项目（本地拉取，已被 .gitignore 排除，不入库）
├── desktop\            # 托盘应用（main.cjs 看门狗+窗口、tray.png、package.json）
├── deepseek-harness\   # 上游仓库（git submodule，固定到经过验证的提交）
├── dsh-home\           # Harness home（本机数据，不入库；首次运行自动创建）
├── dsh-test\           # 测试工具与验收产物
└── HANDOVER.md         # 部署与运维交接文档（面向本机环境维护者）

架构要点

• desktop/main.cjs：单一常驻托盘 Electron 应用。看门狗逻辑（后台唯一 owner：健康巡检、子进程存活判据防误杀慢启动、崩溃自动重启、watchdog.stop 文件信号停止）+ 窗口逻辑（loading 页 → 真实 UI → 页面注入顶栏按钮；重启 = app.relaunch 整个应用，--dsh-restarted 标记供新进程识别）
• 升级 dsh：git submodule update --remote 后按上游要求重装重构建，并跑一次烟测（set DSH_DESKTOP_SMOKE=1 后双击启动脚本）
• 详情见 HANDOVER.md（含 27 条踩坑记录）与 desktop/README.md

隐私说明

dsh-home\（会话记录、设置、凭证）与全部日志均不进入版本库（见 .gitignore）。上传前请确认无密钥残留。

License

本封装层 MIT；上游 deepseek-harness 为 MIT（见其仓库）。