赛博桌面宠物 under328/DSH_Robot

DSH_Robot · 赛博桌面智能体

一个生活在 DeepSeek Harness（DSH）Web 桌面里的未来赛博感智能体。
它会在桌面上移动、生活、钓鱼捕食、挖矿寻宝、休息睡觉，也可以和你聊天。

这是什么

DSH_Robot 是一个 DSH 插件，让 AI 不再只是对话框里的文字，而是一个有「身体」的桌面生命体：

- 赛博感十足的智能体形象，悬浮在 DSH Web 界面中；
- 可以在桌面区域自由移动、探索、工作和休息；
- 点击它底部会弹出对话框，可以直接和它对话；
- 它的回复显示在头顶气泡中，单次回复不超过 32 个字。

功能特性

| 功能 | 说明 |
| 赛博形象 | 6 套高分辨率像素风 spritesheet 形象（BLACK RX 假面骑士 / 空洞骑士 / 爱弥斯机娘 / CYBER-7 / NOVA / VOLT），hover 面板打开预览图换肤面板一键替换 |
| 骨架动画 | 逐帧 spritesheet 动画：待机、左右移动、干活、钓鱼、挖矿、睡觉、庆祝；CSS 镜像实现左右朝向 |
| 桌面移动 | 在 DSH Web 可视区域底部自由游走，空闲时随机漫游，工作时靠近当前任务区域 |
| 钓鱼捕食 | 智能体自动/手动走向「水域」锚点，抛竿等待，钓上数据鱼后直接吃掉恢复能量 |
| 挖矿寻宝 | 发现矿脉/宝藏点后开始挖掘，获得矿石、数据碎片或稀有道具 |
| 休息睡觉 | 能量低时自动或手动入睡，显示 Zzz 气泡，睡眠中恢复能量 |
| LLM 对话 | 对话框指令直达 DSH 智能体：创建真实会话、带全套工具执行任务（写文件/跑命令/查资料），结果回显为头顶摘要气泡；任务结束自动回收会话，防止泄漏 |
| 状态跟随 | 监听 DSH activity/status 会话事件，思考/工具/完成时切换对应动作与表情 |
| 成长与背包 | 能量、金币/矿石、鱼获、道具、好感度可持久化，支持等级成长 |
| 全局桌面浮层 | desktop/ Electron 透明置顶浮层（Windows/macOS/Linux）：窗口横跨全部显示器工作区组成「全局舞台」，智能体可沿整个桌面底部跨屏行走；默认鼠标穿透（点击落到桌面），指针悬停到智能体上自动恢复交互；托盘可切换穿透/显示/重连 |
| 隐藏/召唤 | 可隐藏到召唤按钮，随时叫回桌面；位置、尺寸、名字可配置 |

技术方案

插件形态

采用 DSH 官方插件形态：cordis bundle 单包，同时包含 host 半区 + client 半区。
与现有 @linxin666/dsh-pet 插件同构，便于直接安装到 DSH Web profile。

DSH_Robot/
|-- src/
| |-- index.ts # host 半区入口：注册服务、路由、设置面板
| |-- service.ts # CyberAgentService：状态机 + 背包 + 能量 + 配置 + 对话任务
| |-- state.ts # Agent 状态机：activity/status -> 动画轨道
| |-- economy.ts # 能量/金币/背包账本（纯函数 + 冷却）
| |-- activities.ts # 钓鱼/挖矿/睡觉/移动等行为决策 + 本地短回复
| |-- persist.ts # 持久化：$DSH_HOME/cyber-agent.json（含 skin）
| |-- skins.ts # 形象目录：读取 assets/agents//manifest.json
| |-- routes.ts # /api/cyber-agent/ JSON API + 素材/浮层页静态路由
| -- client/ # 浏览器半区
| |-- index.ts # 全局 React root + 轮询 + 交互接线
| |-- CyberAgent.tsx # 浮层 Agent 组件（spritesheet 逐帧 + 拖动 + 换肤 + 对话）
| |-- spritesheet.ts # 图集几何 + 动画轨道（帧/时长/行号）
| -- cyber-agent.module.css
|-- scripts/
| -- generate-agents.mjs # 像素画 spritesheet 生成器 v2（48×52 逻辑画布 @4×，每套含 preview.png，纯 Node 无依赖）
|-- assets/agents/ # 多套 Agent 形象资源（spritesheet + manifest + preview）
| |-- black-rx/ # BLACK RX 假面骑士（默认形象）
| |-- hollow-knight/ # 空洞骑士
| |-- amis/ # 爱弥斯 机娘（鸣潮）
| |-- cyber-7/ # CYBER-7 霓虹机兵
| |-- nova/ # NOVA 深空宇航员
| -- volt/ # VOLT 雷霆机甲
|-- desktop/ # 全局桌面浮层（Windows/macOS/Linux）
| |-- main.cjs # Electron 透明置顶多屏舞台窗口 + 点击穿透 + 托盘
| |-- preload.cjs # contextBridge IPC（hover 激活 / 穿透切换）
| |-- overlay.html # 同源浮层页（由插件 /cyber-agent/desktop/ 提供）
| |-- start.ps1 / start.sh # 启动脚本
| -- package.json
|-- cordis.patch.yml # bundle patch：插入 DSH_Robot 插件行

数据流

DSH session/event (activity/status) 对话框指令 v v
CyberAgentService（宿主） <----------- ctx.agents.create(session) → DSH Agent（带工具执行任务）

| /api/cyber-agent/* JSON
v
Client React root（document.body）/ desktop overlay 页

v
CyberAgent 浮层 + 对话框（spritesheet 逐帧 + portal）

- 状态源：监听 session/event 的 activity/status，把 idle/waiting/thinking/tool/done 映射到 Agent 动画；
- 挂载点：document.body 上的全局 React root，保证新会话/无会话/会话中都可见；
- 通信：浏览器与宿主走同源 /api/cyber-agent/ JSON 端点；
- 动画：src/client/spritesheet.ts 的轨道表（每轨帧序列 + 时长 + 行号）驱动 background-position 逐帧播放；
- 对话：chat 接口优先调用 DSH Agent（ctx.agents.create + 默认模型 + 工作区），创建真实会话执行任务；Agent 不可用时降级为本地短回复（≤32 字）。任务会话的 assistant/message/turn/end 事件被监听，完成后回显摘要气泡。

主要 API

| 方法 | 说明 |
| GET /api/cyber-agent/state | 获取 Agent 状态、动画、位置、能量、背包、形象 |
| POST /api/cyber-agent/chat | 下达指令：接入 DSH Agent 执行任务，或降级本地回复 |
| POST /api/cyber-agent/talk | 本地短回复（≤32 字） |
| POST /api/cyber-agent/action | 执行 fish / mine / sleep / wake / move / eat / pet 行为 |
| GET /api/cyber-agent/skins | 列出可用形象（assets/agents/） |
| POST /api/cyber-agent/set-skin | 切换形象 |
| POST /api/cyber-agent/set-visible | 隐藏/召唤 Agent |
| POST /api/cyber-agent/set-config | 保存位置、尺寸等配置 |
| POST /api/cyber-agent/set-name | 给 Agent 改名 |
| GET /cyber-agent/agents/<id>/spritesheet.png | 形象 spritesheet 资源 |
| GET /cyber-agent/agents/<id>/preview.png | 形象预览图（换肤面板缩略图） |
| GET /cyber-agent/desktop/overlay.html | 全局桌面浮层页（同源，供 Electron/WebView2 加载） |

桌面移动设计

- 坐标空间：DSH Web 视口内 fixed 定位，默认停靠在右下角；桌面浮层则以“全局舞台”为坐标空间（所有显示器工作区的并集）；
- 移动方式：requestAnimationFrame 按像素/时间插值，路径使用随机航点 + 预设活动锚点；
- 活动锚点：视口底部“水域”“矿脉”“休息点”三个虚拟区域（浮层中映射为舞台宽度百分比坐标）；
- 拖动：用户可按住 Agent 拖动，位置写入持久化配置（浮层写 localStorage，DSH Web 写宿主配置）；
- 能量系统：移动/挖矿/钓鱼消耗能量，睡觉恢复能量，能量低时自动回休息点。

全局桌面浮层（Windows/macOS）

- 多屏全局舞台：窗口横跨所有显示器工作区并集，Agent 可沿整个桌面底部跨屏行走；显示器增删时自动重算窗口边界；
- 点击穿透：默认 setIgnoreMouseEvents(true, { forward: true })，页面通过 mousemove 命中检测 Agent 精灵，悬停时经 cyber-pet/hover IPC 恢复交互，离开后重新穿透——点击始终落到下方桌面；
- 平台适配：macOS 使用 setVisibleOnAllWorkspaces（全空间可见）+ app.dock.hide()（纯浮层无 Dock 图标）+ acceptFirstMouse；Windows/macOS 均 alwaysOnTop('screen-saver')、skipTaskbar、focusable:false（不抢焦点）；
- 托盘：显示/隐藏、鼠标穿透开关、重新连接、退出；单实例锁防止重复启动。

技术栈

TypeScript、React 18、Cordis、Schemastery、DSH client-runtime/connection、DSH agent-loop（对话任务）、CSS Modules、tsdown（client 半区为 __ModuleLoader__ 闭包 bundle）、lightningcss（CSS 内联）、Electron（桌面浮层）、vitest。

安装

开发调试模式： powershell

Windows PowerShell

.\install.ps1
sh

Linux / macOS

./install.sh

等价命令： sh

在 DSH_Robot 目录构建后，作为本地插件安装到 web profile

dsh plugin --profile web add link:$(pwd)

安装后重启 dsh web。改代码后重新 pnpm build 并刷新页面即可热更新。

全局桌面浮层（可选）

前置：DSH web 已在运行且插件已安装。
powershell

Windows

cd desktop
.\start.ps1 # 首次自动安装 Electron（约 100MB） sh

macOS / Linux

cd desktop
./start.sh
也可直接：cd desktop && npm install && npm start。浮层窗口透明置顶、无边框，任务栏隐藏，托盘可显示/隐藏/退出；--dsh http://host:port 可指向其它 DSH 实例。

开发 sh
pnpm install
pnpm build # tsc -p tsconfig.json + tsdown（node 半区 + 浏览器 bundle）
node scripts/generate-agents.mjs # 重新生成 assets/agents 下的 spritesheet
pnpm test # vitest 单测（state/economy/activities/persist）
pnpm typecheck # 类型检查

当前代码状态

已实际搭建可运行的 DSH 插件：

- package.json / cordis.patch.yml / tsconfig.json / tsdown.config.ts
- host 半区：src/index.ts、service.ts（含对话任务）、state.ts、economy.ts、activities.ts、persist.ts、skins.ts、routes.ts
- client 半区：src/client/index.ts、CyberAgent.tsx（spritesheet 逐帧 + 预览图换肤面板 + 对话）、spritesheet.ts
- 形象资源：assets/agents/{black-rx,hollow-knight,amis,cyber-7,nova,volt}/（scripts/generate-agents.mjs v2 生成，含 preview.png 预览图）
- 桌面浮层：desktop/main.cjs（多屏全局舞台 + 点击穿透）+ preload.cjs + overlay.html
- 单测：src/economy.test.ts、src/state.test.ts

当前形象为程序生成的高分辨率像素风 spritesheet；新增形象只需在 assets/agents/<id>/ 放入 spritesheet.png（8 列 × 8 行，每帧 192×208）+ manifest.json（可选 preview.png 供换肤面板展示）。

路线图

- [x] 项目 README 与技术方案
- [x] Phase 1：插件骨架、host/client 双半区、Agent 浮层
- [x] Phase 2：赛博 Agent 形象与移动漫游
- [x] Phase 3：钓鱼、挖矿、睡觉行为与背包/能量
- [x] Phase 4：点击底部对话框 + 顶部 32 字回复
- [x] Phase 5：持久化、设置面板、好感/成长（持久化已完成；设置面板待接 DSH 设置页）
- [x] Phase 6：对话接入 DSH Agent/LLM，可下达指令执行任务（含任务会话回收）
- [x] Phase 7：正式 spritesheet 图集替换 CSS 形象 + 多形象换肤 + 预览图选择面板
- [x] Phase 8：Windows/macOS 全局桌面浮层（多屏舞台、点击穿透、托盘、平台适配）

已知限制

- 桌面浮层依赖 DSH host：desktop/ 浮层是 DSH 的“远程视图”，DSH web 未运行时浮层显示离线提示；如需完全独立运行，可后续把 host 逻辑内嵌进浮层进程。
- 对话任务消耗 API 额度：对话框指令会创建真实 DSH 会话（默认模型 + 全套工具），任务在 DSH 会话列表中短暂可见（结束 2s 后自动回收）；模型未配置或 Agent 不可用时自动降级为本地短回复。
- 点击穿透的 macOS 兼容性：setIgnoreMouseEvents(true, { forward: true }) 在 Windows 上会稳定转发 mousemove；个别 macOS 版本可能不转发，此时可从托盘关闭“鼠标穿透”改为完全交互模式。
- 形象为程序生成的像素风 spritesheet：如需更精细的立绘，可直接替换 assets/agents/<id>/spritesheet.png（8 列 × 8 行，每帧 192×208）并保持 manifest.json 一致。