dsh-harness-tray

DeepSeek Harness 的 Windows 系统托盘守护程序 —— 独立于 DSH 进程之外运行的原生 C# 程序，为 DSH 提供启动管理、多 Profile 绑定、快照快速恢复、插件启停管理、SQLite 元数据台账等守护能力，确保 DSH"每次干活之前可用"。

English | 中文

---

一、功能特性

#	能力	说明
1	独立守护	托盘是完全独立的 Windows 程序（原生 C#，单 exe），不依赖 Node/DSH 进程；DSH 环境对托盘零感知
2	启动入口	托盘菜单一键 启动/停止/重启 DSH 服务、打开 Web 界面、接管外部服务并重启
3	多 Profile 绑定	可登记多套 Profile + 端口 绑定（SQLite 存储），启动时按 active 绑定拉起 DSH；支持切换/编辑绑定
4	快照快速恢复	记录 DSH 环境快照（配置 + 插件源码 + 版本元数据）；启动失败时一键回退上次正常快照或任意历史快照；.broken 可反悔备份 + dump-config 验证链，杜绝"带病恢复"
5	插件管理	展示 Profile 全部插件（官方 bundle 只读 + 自研 link: 插件可启停）；启停通过 cordis.patch.yml 的 disabled: true 生效（DSH loader 原生机制，不与 DSH 自身管理冲突）
6	SQLite 元数据库	内置 SQLite（P/Invoke 调用 Windows 系统自带 winsqlite3.dll，零额外文件）；记录 DSH 版本台账、绑定、插件清单、快照索引；启动时从库中提取 版本→Profile→端口 决策
7	版本自动入库	DSH 每次启动成功后自动提取版本写入台账并与库中对比：一致不更新、发现新版本立即登记（含 node 版本、首次/最近出现时间）
8	CLI 控制面	配套 dsh-tray-cli.exe（控制台），托盘运行中走命名管道 IPC、未运行则文件级独立执行；--json 输出 + 约定退出码，可脚本化
9	客户端哨兵（L4）	让 DSH 加载一个极小的浏览器哨兵（纯观察、零 token/上下文）；当某插件导致 "Failed to load plugins" 页面时，哨兵上报元凶插件名给托盘 → 托盘把状态灯变橙 + 弹窗让你确认「禁用并重启 / 忽略」→ 禁用即恢复。托盘启停自动装/除哨兵

二、架构总览

┌────────────────────────────────────────────────────────────┐
│ dsh-tray.exe（原生 C#，常驻托盘，树外运行）                    │
│  · 启动守护：按 SQLite active 绑定拉起 DSH（版本→Profile→端口）│
│  · 运行监督：端口/进程监控、接管外部服务、异常退出提示          │
│  · 快照/恢复：known-good 自动快照、一键恢复、.broken 反悔      │
│  · 插件管理 / 绑定管理（托盘菜单 + 对话框）                    │
│  · 状态存储：state\（meta.db / snapshots / logs）             │
└───────────────────────────────┬────────────────────────────┘
        ▲ 命名管道 IPC（JSON）   │ 子进程（node）
┌───────────────────────────────┴────────────────────────────┐
│ dsh-tray-cli.exe（控制台控制面）：status/check/snapshot/     │
│   list/restore/start/stop/restart/versions/binding/plugins  │
└───────────────────────────────┬────────────────────────────┘
                                ▼
                DeepSeek Harness（Node，被守护者，浏览器 UI 不变）

守护思想：DSH 是插件"组合"的程序，存在"一个插件坏了整体无法启动"的特性。托盘的快照/恢复是确保 DSH 正常运行的关键能力 —— 环境损坏时按历史快照快速还原（配置、插件源码、node_modules 链接重建），让 DSH 立即回到可用状态。

三、环境要求

• Windows 10 / 11（需要系统自带 winsqlite3.dll，Win10/11 均内置；缺失时自动降级为 conf 模式）
• .NET Framework 4.8（Windows 自带；build.cmd 使用系统 csc.exe 编译，无需额外 SDK）
• Node.js（启动 DSH 必需；托盘会从常见路径或 PATH 自动探测）
• DeepSeek Harness（@deepseek-ai/dsh 全局安装；托盘自动探测，也可在 conf 中指定路径）

四、构建

build.cmd                 :: 在脚本目录产出 dsh-tray.exe + dsh-tray-cli.exe
build.cmd D:\some\dir     :: 输出到指定目录

一次编译产出两个 exe：dsh-tray.exe（GUI 子系统，托盘本体）+ dsh-tray-cli.exe（控制台子系统，控制面），共享同一套核心源码（逻辑单份）。

自检：

dsh-tray-cli.exe selftest   :: 沙箱单元测试（不触碰真实环境），全绿输出 PASS n FAIL 0

五、部署

5.1 目录结构

dsh-harness-tray\
├── dsh-tray.exe            （托盘本体）
├── dsh-tray-cli.exe        （控制面）
├── dsh-tray.conf           （可选：首启默认值，缺省即默认行为）
└── state\                  （托盘自己的状态目录，自动创建，不在 DSH home 内）
    ├── meta.db             （SQLite 元数据库：版本/绑定/插件/快照索引）
    ├── snapshots\          （快照）
    ├── broken\             （恢复前备份，可反悔）
    ├── logs\               （托盘/服务日志）
    └── last-known.json     （上次启动结果）

5.2 首次运行（自动迁移）

托盘首次启动时：

1. 读取 dsh-tray.conf（不存在则用默认值：port=3080、profile=web、DSH home 为用户目录下的 .dsh）
2. 自动创建 state\meta.db 并登记首条 active 绑定（即 conf 值）
3. 之后启动决策全部以 SQLite 为准（conf 仅作首启兜底）

5.3 配置（dsh-tray.conf，可选）

# dsh-tray.conf — key=value，# 注释；缺省即默认行为
port=3080
# dshDir=C:\path\to\node_modules\@deepseek-ai\dsh   # 默认自动探测
# node=C:\path\to\node.exe                          # 默认自动探测
# dshHome=C:\Users\<you>\.dsh
profile=web
autoRecover=false          # 启动失败后是否自动恢复（默认询问）
snapshotKeep=5             # 快照滚动保留数（known-good 永不淘汰）
includeCredentials=false   # 快照是否包含 .credentials.yaml（默认否）

5.4 开机自启与快捷方式

• 托盘菜单勾选「开机自启」即可（写入当前用户的启动项）
• 桌面/开始菜单快捷方式直接指向 dsh-tray.exe，替换 exe 后无需改快捷方式（state 与 exe 分离，替换不丢快照与台账）

5.5 多 Profile 绑定（托管多个 DSH 环境）

dsh-tray-cli binding list                          :: 查看绑定（* = active）
dsh-tray-cli binding add explore 4100 D:\...\home  :: 新增并激活（profile/端口/DSH home）
dsh-tray-cli binding set-active web                :: 切换 active
dsh-tray-cli binding rm explore                    :: 删除绑定

托盘菜单「绑定管理…」提供图形化操作。切换 active 后重启托盘生效（托盘按新绑定拉起 DSH）。

5.6 接管外部服务

DSH 已被其他进程启动时，托盘进入"监控外部实例"模式，菜单出现「接管外部服务并重启」——点击后托盘停止该进程并重新拉起为托管服务（手动操作，不会自动杀外部进程）。

六、CLI 参考

dsh-tray-cli status [--json]                 托盘/服务/快照/环境事实（退出码 3 = 降级）
dsh-tray-cli check                           静态预检（dump-config + 环境完整性）
dsh-tray-cli snapshot [--reason R]           手动快照
dsh-tray-cli list [--json]                   快照列表（known-good 标记）
dsh-tray-cli restore <id|--good> [--no-verify] [--no-start]   恢复 + 验证链
dsh-tray-cli start | stop | restart          服务生命周期
dsh-tray-cli versions                        版本台账（SQLite）
dsh-tray-cli binding list|add|set-active|rm  绑定管理
dsh-tray-cli plugins list|toggle <name> [on|off]   插件列表 / 启停
dsh-tray-cli selftest                        沙箱单元测试
dsh-tray-cli version | help

退出码约定：0 成功 / 1 失败 / 2 用法错误 / 3 降级（上次启动失败，建议 restore --good）。

七、快照与恢复机制

• 快照内容：DSH 环境配置（settings.yaml + profile 的 package.json/cordis.patch.yml/pnpm-workspace.yaml/pnpm-lock.yaml）+ 自研插件源码（zip）+ 版本元数据（dsh/node 版本）
• 排除项：.credentials.yaml（凭据，默认排除）、会话/附件等用户数据、node_modules（boot 自愈）
• known-good：每次成功启动 15 秒后自动打 known-good 快照；滚动保留（默认 5 份），known-good 永不淘汰
• 恢复流程：停止服务 → 当前状态备份为 .broken（可反悔）→ 还原配置 → 还原插件源码 → 重建 node_modules 链接（junction，无管理员依赖）→ dump-config 验证 → 拉起服务
• 版本联动：快照记录所属 DSH 版本，恢复列表优先显示与当前版本匹配的 known-good（跨版本明确标注）
• 触发方式：托盘菜单「从快照恢复」（上次 known-good / 选择快照…）或 dsh-tray-cli restore --good

八、SQLite 元数据库（state\meta.db）

表	作用
meta	schema 版本、创建时间
dsh_versions	DSH 版本台账（version 唯一；重复启动只刷新 last_seen，发现新版本立即登记）
bindings	Profile+端口+DSH home 绑定（is_active 全局唯一）—— 启动决策来源
plugins	按 DSH 版本登记的插件清单（kind=bundle 官方 / self 自研）
snapshot_index	快照索引（关联版本，恢复按版本匹配）

九、安全与边界

• 快照是环境/配置快照，不是数据备份：会话、附件、凭据不在恢复范围
• 恢复会覆盖当前配置：永远先 .broken 备份，可反悔
• 托盘状态完全在 DSH home 之外（state\ 目录），DSH home 干净
• 插件禁用通过 profile 用户层 patch 生效，不动官方 bundle、不改 DSH 本体；写 patch 前 dump-config 预检、写后校验失败自动回滚
• winsqlite3.dll 缺失时自动降级 conf 模式（仍可启动/停止/监控，元数据能力降级）
• 版本回滚（DSH 降级安装）为预留项，尚未实现

十、更新与维护

• 升级：直接替换 dsh-tray.exe / dsh-tray-cli.exe 即可，state\ 目录（快照/台账/日志）原样保留
• 日志：state\logs\dsh-tray-<port>.log（托盘）、dsh-tray-server-<port>.out/err.log（服务）
• 排障：dsh-tray-cli check（静态预检）→ dsh-tray-cli status（看降级）→ dsh-tray-cli restore --good（一键恢复）

License

MIT