坤宠桌面版anticipate218/kun-pet-desktop

🐔 坤宠桌面版 · Kun Pet Desktop

坤宠桌面版 是一个 Windows 桌面坤宠（Kun Like 桌宠）独立客户端：透明、无边框、始终置顶的小宠物常驻桌面，
支持拖动、点击互动、滚轮缩放、一键关闭，并可设置开机自启。

本项目将 dsh-kun-pet（DeepSeek Harness 桌面宠物插件）的
坤宠精灵图与互动玩法，从浏览器插件形态封装为独立运行的 Electron 桌面应用，不依赖 DSH，双击即用。

🎨 素材与动画数据来自原插件 dsh-kun-pet（MIT），
感谢原作者 Practice019 的开源贡献，详见下方 致谢与版权。

🔗 与 DSH 插件 dsh-kun-pet 的关系

| | 本仓库（桌面版） | dsh-kun-pet（插件版） |
|---|---|---|
| 形态 | 独立 Electron 桌面应用 | DeepSeek Harness (DSH) 插件（npm） |
| 运行环境 | Windows 桌面，无需 DSH | DSH Web 界面内（随 Agent 状态切换动画） |
| 安装方式 | 解压便携包 / npm start | dsh plugin --profile web add dsh-kun-pet |
| 独特能力 | 独立置顶窗口、滚轮/按钮缩放、开机自启 | 与 Agent 工作状态联动、任务完成语音 |

两者是同一坤宠形象的两个独立产物，素材同源（见 NOTICE）。
若你在 DeepSeek Harness 中使用，请安装插件版；若想要不依赖 DSH 的常驻桌面宠物，请使用本仓库。

✨ 功能特性

| 功能 | 说明 |
|------|------|
| 🪟 独立桌面应用 | 基于 Electron，透明无边框窗口，不依赖 DSH / 浏览器 |
| 📌 始终置顶 | 常驻桌面最上层（screen-saver 层级），不被普通窗口遮挡 |
| 🖱️ 拖动移动 | 按住坤宠本体，可拖到屏幕任意位置 |
| 🖼️ 多种动画 | 空闲 idle 循环动画；点击后切换挥手 wave 动画 |
| 🔊 点击互动 | 点击坤宠播放语音并挥手打招呼 |
| 🔍 自由缩放 | ＋ / － 按钮或鼠标滚轮，0.5× ~ 3.0× 之间调整大小 |
| ❌ 一键关闭 | 点击 ✕ 按钮彻底退出程序 |
| 🚀 开机自启 | 放入 Windows 启动文件夹即可登录后自动常驻（见下文） |

📸 效果预览

启动后，坤宠会以一个透明无边框的小窗口出现在主屏幕右下角并持续待机动画：

😺 坤宠本体（空闲动画循环） ・
＋ 放大 ・ － 缩小 ・ ✕ 关闭

- 右上角三个圆形按钮：＋ 放大 / － 缩小 / ✕ 关闭；
- 拖动坤宠本体移动窗口，点击触发挥手 + 语音。

欢迎提交 PR 补充实际运行截图到 docs/preview.png。

🚀 快速开始

前置条件

- Windows 10 / 11
- Node.js ≥ 22（Electron 44 要求 Node ≥ 22.12）
- npm（随 Node.js 自带）

方式一：Git 克隆运行

git clone https://github.com/anticipate218/kun-pet-desktop.git
cd kun-pet-desktop
npm install
npm start

⚠️ npm install 会自动从 GitHub Releases 下载 Electron 运行时（约 100 MB）。
中国大陆网络若下载缓慢或失败，可先设置镜像再安装：

PowerShell
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install

方式二：下载发行包

前往 Releases 下载对应版本的安装包 / 免安装包，
解压后双击 坤宠.exe（或 kun-pet-desktop.exe）即可。

🚀 开机自启（可选）

想让坤宠每次登录 Windows 后自动出现：

1. 按 Win + R，输入 shell:startup 回车，打开「启动」文件夹；
2. 将启动坤宠的快捷方式（或 .bat）放入该文件夹；
3. 若使用 .bat，可参考以下内容（按你的实际路径修改）：

@echo off
chcp 65001 >nul
start "" "C:\你的路径\node_modules\electron\dist\electron.exe" "C:\你的路径\kun-pet-desktop"

💡 若使用打包后的发行版，直接把可执行文件的快捷方式放入启动文件夹即可。
不需要自启时，删除启动文件夹中对应快捷方式即可。

🎮 使用说明

| 操作 | 效果 |
|------|------|
| 按住坤宠拖动 | 移动位置 |
| 单击坤宠 | 播放语音 + 挥手动画 |
| 鼠标滚轮（在坤宠上） | 放大 / 缩小 |
| 点击 ＋ | 放大一档 |
| 点击 － | 缩小一档 |
| 点击 ✕ | 关闭坤宠 |

📁 文件结构

kun-pet-desktop/
├── package.json          ← 项目声明（main / scripts / 依赖）
├── main.js               ← Electron 主进程：窗口、置顶、拖动、缩放、关闭
├── preload.js            ← 预加载脚本：向页面安全暴露 pet 能力
├── index.html            ← 渲染进程：精灵图动画、交互、缩放、点击发声
├── spritesheet.webp      ← 坤宠精灵图（8列×9行，192×208/格）
├── voice.mp3             ← 点击互动语音
├── LICENSE               ← 本项目 MIT 许可证
└── NOTICE                ← 第三方致谢与版权声明（必读）

🔧 技术说明

- 窗口：Electron BrowserWindow，transparent: true + frame: false，透明无边框；
- 置顶：setAlwaysOnTop(true, 'screen-saver')，位于屏幕保护层之上；
- 安全：contextIsolation: true、nodeIntegration: false，渲染进程通过 preload 暴露的
window.pet 与主进程通信（拖动/缩放/关闭）；
- 动画：与 dsh-kun-pet 一致的精灵图规格 —— 8 列 × 9 行、单格 192 × 208，
空闲 6 帧（时长 [280,110,110,140,140,320]ms），挥手 4 帧（[140,140,140,280]ms）；
- 拖动：主进程按光标轮询移动窗口，保持按下点相对位置不变；
- 缩放：渲染进程计算新窗口尺寸后通知主进程，主进程贴边收进工作区。

🎓 致谢与版权

本项目基于以下开源项目二次开发，向原作者致以诚挚感谢：

Practice019 / dsh-kun-pet（MIT）

- 作者：Practice019
- 仓库：https://github.com/Practice019/dsh-kun-pet
- npm：https://www.npmjs.com/package/dsh-kun-pet

本项目复用了该插件的：

- spritesheet.webp 坤宠精灵图（全部动画帧素材）；
- voice.mp3 点击互动语音；
- 精灵图布局（8×9 网格、单格 192×208）与动画帧时长数据。

致谢：感谢 Practice019 创作并开源了如此可爱的坤宠桌宠，让 DeepSeek Harness 用户
拥有了一只随 Agent 工作的小伙伴。本项目把这份可爱从浏览器里带到了整个 Windows 桌面。

⚠️ MIT 许可要求保留原版权声明。原插件版权声明全文见项目内 NOTICE 文件，
任何二次分发/修改均须一并保留。

Electron（MIT 等）

- 官网：https://www.electronjs.org
- 本项目仅将 Electron 作为开发依赖，未随仓库分发其二进制。

其他声明

- 本项目为社区二次创作，与 DeepSeek / DeepSeek Harness 及原插件作者无官方隶属关系；
- 角色形象为互联网流行梗文化形象，素材版权归原作者 / 原出处所有，请勿商用或侵权使用；
- 若原作者认为本项目使用不当，欢迎通过 Issues 联系，我们将第一时间处理。

📄 许可证

- 本项目代码与文档：MIT License，见 LICENSE；
- 第三方素材与代码的版权归各自作者所有，详见 NOTICE。

Made with ❤️ for 坤门