鲸鱼桌宠 miku00039-01/dsh-whale-pet

🐋 DSH 桌宠 (DSH Whale Pet)

Awesome DSH Plugin

一个 Windows 桌面宠物程序，把 DeepSeek Harness 的服务启动、停止、状态监测和 GUI 唤起整合到一个零依赖的 .exe 里。

English: README.en.md · 版本记录: CHANGELOG.md · 安全: SECURITY.md

whale

✨ 功能

| 功能 | 说明 |
| 一键启动 | 双击 exe = 检测 DSH 服务 → 未运行则后台拉起 → 就绪后打开 GUI → 鲸鱼娘出现 |
| 两种模式自动识别 | 桌面端模式(Electron 应用)：只做伴侣——唤起它的窗口、看它状态，不再另起实例；CLI 模式：沿用下面的完整服务管理 |
| 人形桌宠 | 逐像素透明悬浮窗，按图片原形状显示，可拖动、记住位置 |
| 双击唤起 | 桌面端模式 = 把桌面端窗口置顶；CLI 模式 = 打开 GUI(复用同一 PWA 窗口，不堆标签页) |
| 右键菜单 | 打开程序 / 最小化至托盘 / 关闭程序 / 查看状态 / 退出 |
| 最小化至托盘 | 选「🗕 最小化至托盘」隐藏鲸鱼娘(仅留托盘图标)；单击托盘图标即可唤起，再次运行 exe 同样能唤回(位置不变) |
| 关闭程序 | 桌面端模式 = 只关桌面端窗口(不动服务进程)；CLI 模式 = 停服务 + 关 GUI 窗口(不影响其他浏览器页面) |
| 退出 | 确认框后退出(CLI 模式连服务一起退；桌面端模式不动桌面端进程) |
| 托盘图标 | 常驻；鲸鱼娘已隐藏时左键单击 = 唤起，未隐藏时左键单击 = 打开 GUI；右键菜单(兜底入口) |
| 状态监测 | 仅绿/红两态(无黄色中间态)，自适应频率：在线 5 秒 / 离线 2 秒 |
| 状态卡片 | 悬浮卡片显示服务状态/地址/PID/运行时长 + 桌宠内存/GDI 句柄(自检防泄漏) |
| 单实例 | 重复双击不会开第二个，只会唤起已有实例 |
| 崩溃日志 | 未捕获异常自动写入 dsh-whale-pet-crash.log，方便排查 |

📦 依赖(前置条件)

| 依赖 | 必选? | 说明 |
| Windows 10 / 11 | ✅ 必选 | 使用了 WinForms / 分层窗口 / netstat 等 Windows 能力 |
| .NET Framework 4.x | ✅ 必选 | 系统自带，无需安装；exe 由系统自带 csc.exe 编译，目标框架 4.x |
| DeepSeek Harness | ✅ 必选 | 需要正确安装：① Node.js(提供 node 运行环境)② dsh CLI 全局安装(npm i -g @deepseek-ai/dsh)③ 已配置 API 凭证(~/.dsh/.credentials.yaml 中的 DEEPSEEK_API_KEY)。桌宠通过 node <dsh的bin.js> web 拉起服务，监听 127.0.0.1:3080 |
| Chrome | ⚪ 可选 | 用于 PWA 独立窗口模式(由 DSH GUI 生成 DeepSeek Harness.lnk 快捷方式)。未安装/未找到时自动回落到默认浏览器打开 |

简言之：装好 DeepSeek Harness 就能跑；装 Chrome 并获得 PWA 快捷方式可获得最佳体验。

🚀 快速开始

方式一：作为 DSH 插件安装(推荐)

从 npm 安装(推荐,npm 包名为 @miku00039-01/dsh-whale-pet)
dsh plugin --profile web add @miku00039-01/dsh-whale-pet

或直接从 GitHub 安装(无需 npm)
dsh plugin --profile web add github:miku00039-01/dsh-whale-pet

安装后在 DSH 里输入 /whalepet 即可启动鲸鱼娘桌宠。插件市场(dsh-market)里搜索 dsh-whale-pet 也能一键安装。

关于包名：npm 上 dsh-whale-pet 已被他人占用，因此本插件发布在作用域下 @miku00039-01/dsh-whale-pet。
package.json 的 name、cordis.patch.yml 的 name 与 profile 里的依赖键必须三处一致。

关于宿主要求：插件市场卡片上的「宿主要求」读自 npm manifest 的 engines.dsh(本包声明 >=0.1.0-rc.6)；只从 GitHub 安装、未发布到 npm 的插件，市场读不到 manifest，会显示「宿主要求未知」——这是市场刻意不猜测的设计。

方式二：直接下载 exe

1. 从 Releases 下载 DSH桌宠.exe(或按下方「从源码构建」)
2. 双击运行 → 鲸鱼娘出现在屏幕右下角
3. 首次运行会在 exe 同目录生成 dsh-whale-pet.conf(自动检测的路径)，可按需修改

⚙️ 配置(dsh-whale-pet.conf，INI 格式)

| 键 | 默认 | 说明 |
| workspace | (exe 所在目录) | DSH 工作区目录(决定会话归属；建议设为你的工作目录) |
| nodePath | 自动检测 | node.exe 路径 |
| dshBin | 自动检测 | @deepseek-ai/dsh 的 lib/bin.js 路径 |
| pwaShortcut | 自动查找 | Chrome PWA 快捷方式路径；留空且找不到则用浏览器打开 |
| pwaWindowTitle | DeepSeek Harness | GUI 应用窗口标题前缀(用于「关闭程序」时精确关窗) |
| openMode | auto | 开窗方式：auto（优先用令牌地址自愈 cookie）/ pwa（只走快捷方式）/ token（只用令牌地址） |
| chromeProfile | 从快捷方式读取 | Chrome 配置目录名（令牌地址开窗时与 PWA 共用 cookie）；留空 = 自动读取 |
| mode | auto | 运行模式：auto（检测到桌面端就用桌面端逻辑，否则回落 CLI）/ desktop（只认桌面端）/ cli（只认命令行服务） |
| desktopExe | 自动探测 | DSH 桌面端（Electron 应用）exe 路径；留空则自动探测（见下方「桌面端怎么被找到」） |
| port | 3080 | CLI 模式的 DSH 服务端口（桌面端模式下不使用） |
| lastX / lastY | -1 | 鲸鱼娘上次位置（自动记录） |

所有键留空 = 自动检测；修改后重启桌宠生效。示例见 dsh-whale-pet.conf.example。

🖥️ 两种运行模式（桌面端 / 命令行）

DSH 现在有两种形态，桌宠会自动识别并切换行为（mode=auto）：

| 桌宠行为 | 桌面端模式（检测到 DeepSeek Harness.exe / 其进程） | CLI 模式（回落到原逻辑） |
| 在线判定 | 桌面端进程是否在运行 | 127.0.0.1:<port> 端口是否可连 |
| 双击 / 打开程序 | 把桌面端窗口置顶（最小化了就还原）；没在跑就先启动它 | 用令牌地址打开 GUI（自愈 cookie） |
| 关闭程序 | 只关桌面端窗口，不动它的服务进程 | 停掉桌宠自己拉起的服务 + 关闭 GUI 窗口 |
| 启动服务 | 不启动任何实例（桌面端自己管服务） | dsh web --no-open 由桌宠拉起 |
| 状态卡片 | 显示桌面端进程 PID 与运行时长 | 显示服务地址与 PID |

为什么要分模式：桌面端是 Electron 应用，自带 dsh 服务并自带窗口（端口由应用自己分配，实测 19387，且同样有令牌围栏）。
如果桌宠还按老逻辑去拉一个 CLI 实例，就会出现两套 GUI、两份会话、两个端口——所以桌面端模式下桌宠只做「伴侣」（唤起窗口/看状态），不再碰服务生命周期。
强制指定模式：把 mode 设为 desktop 或 cli。

桌面端怎么被找到（不依赖安装路径）

别人的安装位置可能完全不同，所以桌宠按 5 条途径依次探测，任意一条命中即可：

| # | 途径 | 说明 |
| 1 | desktopExe 配置 | 你手工指定的完整路径（最稳） |
| 2 | 注册表卸载信息 | DisplayName 含 DeepSeek Harness → 读 InstallLocation / DisplayIcon / UninstallString |
| 3 | 开始菜单快捷方式 | 名字含 Harness 的 .lnk → 解析其目标路径 |
| 4 | 常见安装位置 | Program Files、%LOCALAPPDATA%\Programs、C:\dsh、D:\dsh |
| 5 | 运行中的进程反查 | 从桌面端进程读它的可执行文件路径 |

并且即使一个 exe 都没探到，只要桌面端进程在跑、或存在桌面端用户数据目录（%APPDATA%\@deepseek-ai\dsh-desktop），也会判定为桌面端模式——所以不会因为「路径不同」而误起 CLI 实例。
进程与窗口匹配也会用上探测到的 exe 文件名（改名版、便携版同样能认）。

🖥️ 打开行为与开关（CLI 模式）

- 桌宠打开 GUI 的方式：优先打开 Chrome PWA 独立窗口（通过 pwaShortcut 指定的快捷方式）；未找到快捷方式时回落到默认浏览器标签页。
- 服务启动开关：桌宠以 dsh web --no-open 启动服务——新版 dsh（0.1.1+）默认会自动打开浏览器，--no-open 让开窗完全由桌宠控制，避免出现「先开网页再开应用窗口」的双窗口。
- 裸地址会 401？这是 dsh 的浏览器信任围栏：新版 dsh 对裸地址 http://127.0.0.1:3080/ 要求浏览器持有 dsh-auth- cookie（默认 30 天）。服务每次启动都会打印一行带进程令牌的地址（dsh web: http://127.0.0.1:3080/?token=...），浏览器访问一次即换取新 cookie 并 303 跳回干净地址。
- 桌宠会自动捕获这一行，启动后首次开窗优先使用令牌地址（自动换取/续期 cookie），之后回落到 PWA 快捷方式复用同一窗口——不必再手动贴令牌地址。
- cookie 到期或被清理后，桌宠下一次启动服务时就会自动续期；若服务由外部（如 CMD 里 dsh web）启动，桌宠拿不到令牌，此时可用 openMode=token 以外的方式，或手动打开日志里那行地址一次。
- 想改打开方式？
- 修改 dsh-whale-pet.conf 的 pwaShortcut → 指向别的 PWA 快捷方式；置空则始终用默认浏览器打开。
- 手动运行 dsh web（不带 --no-open）时，服务会自动打开浏览器——这是 dsh 自带行为，与桌宠无关。

🔨 从源码构建

要求:Windows 10/11(自带 csc.exe 与 .NET Framework),PowerShell 7 或 5.1 pwsh -File build.ps1

构建脚本会：① 从 assets/whale.png 生成多尺寸 pet.ico；② 用系统 csc.exe 编译 src/DSHPet.cs → DSH桌宠.exe（零第三方依赖）。

🚀 发布新版本（CI 自动构建 Release）

仓库已配置 GitHub Actions：推送 v 标签时，自动在 Windows 环境构建并上传 exe 到 Release。

git tag v1.0.0
git push origin v1.0.0

推送 main 分支也会触发一次构建校验（不发布）。
Release 正文自动取自 CHANGELOG：发布任务会调用 .github/scripts/extract-changelog.sh，按 tag 从 CHANGELOG.md 提取对应版本小节，作为 Release 说明（所以发版前请先在 CHANGELOG.md 写好该版本小节；小节标题用 ## [v1.14] 或 ## [v1.14.0] 都能匹配）。匹配不到时退化为一段简短说明，不会导致发布失败。

📁 目录结构

dsh-whale-pet/
├── package.json # dsh 插件 manifest(dsh.bundle) ├── cordis.patch.yml # 插件注册(/whalepet 命令) ├── lib/index.js # 插件实现:注册命令并启动桌宠 exe ├── dist/DSH桌宠.exe # 随插件分发的桌宠 exe ├── src/DSHPet.cs # 桌宠全部源码(单文件,WinForms + P/Invoke) ├── assets/whale.png # 桌宠形象素材(见下方授权) ├── assets/pet.ico # 构建生成的 exe 图标 ├── assets/WHALE_ATTRIBUTION.md # 素材授权说明 ├── build.ps1 # 一键构建脚本(支持 -OutDir) ├── .github/workflows/ci.yml # CI:push 构建校验,tag 自动发 Release ├── dsh-whale-pet.conf.example # 配置示例 ├── CHANGELOG.md # 版本记录 └── README.md

🖼️ 素材授权

桌宠形象（鲸鱼娘）素材的出处与许可详见 assets/WHALE_ATTRIBUTION.md。使用或分发前，请先确认符合其许可要求。

📄 License

代码部分：MIT，见 LICENSE。素材部分遵循上述授权说明。