1. 痛点突围：它究竟击穿了什么工程死穴？

传统的桌面 AI 代理大多受限于死板的网页插件容器或资源消耗巨大的 Electron 沉重壳子，难以在保证渲染帧率的同时与宿主大模型会话状态进行深度绑定。开发者如果想在本地日常开发时直观感知大模型的思考、工作、等待与报错状态，往往需要自行维护一套复杂的窗口通信及透明渲染管线。dsh-pet 放弃了臃肿的 Webview 方案，直接将桌面透明置顶小窗与 DeepSeek Harness 的会话事件进行底层打通。

项目通过纯函数物理引擎与双缓冲交叉淡入机制，彻底消除了帧切换时的空白闪烁。用户在多显示器或异构缩放环境下，依然能保持稳定的屏幕边缘碰撞反弹与抛物线轨迹计算。

💡 架构核心洞见：dsh-pet 的本质是一个将大模型异步会话状态转化为实时位移动画的轻量化表现层解耦器，用纯函数物理契约绕过了沉重的游戏引擎依赖。

2. 核心架构与底层数据流向解析

项目整体采用插件化解耦设计，宿主端与客户端通过独立的进程管道和轻量化协议进行数据交换。核心状态机通过监听 DSH 会话事件触发对应的动画档位，同时利用候选数组随机轮换机制避免动作单一。

[ DSH Session Events ] ---> [ State Machine / Event Dispatcher ] ---> [ Animation Selector ]
                                        │                                         │
                                        ▼                                         ▼
                            [ HTTP / Cordis Channels ]            [ Shared Core Physics & VP9-Alpha Engine ]
                                        │                                         │
                                        ▼                                         ▼
                           [ Third-party API Consumers ]         [ Browser Overlay & Electron Desktop Host ]

在数据流向设计中，shared-core.js 统一了浏览器端与桌面端的纯函数物理挤压曲线和碰撞检测逻辑。无论是点击挤压、拖拽阻尼弹簧还是甩抛抛物线计算，两端共用同一套数学模型。当桌面宿主未就绪或处于 Linux headless 环境时，系统会自动捕获显示环境异常并平滑降级，仅保留浏览器 Overlay 渲染，保证核心业务进程不发生崩溃。

3. 技术选型与性能横向硬核对比

选型维度 本方案 (dsh-pet) 传统实现范式 典型竞品方案 生产环境收益
渲染管线 VP9-Alpha 硬件加速透明流 重型 3D 引擎 (Three.js/Canvas) 静态 GIF 序列帧 内存占用缩减 60%，杜绝色彩溢出
多端同构 浏览器 Overlay + 独立 Electron 窗 纯浏览器端隔离 独立桌面客户端独立运行 共享状态配置，多开资源开销极低
通信架构 HTTP 本地无鉴权 + Cordis 客户端零拷贝 WebSocket 繁重鉴权 无外部调用接口 第三方脚本毫秒级控制桌宠状态
物理引擎 自研纯函数物理模型 (Shared Physics) 接入 Box2D 等重型物理库 无物理反馈，硬切坐标 抛掷反弹触感真实，CPU 占用趋近零
环境适配 三端覆盖 (Win/Linux/macOS) 仅支持单一平台 仅支持 Web 页面 完美支持多显示器异构 DPI 缩放

这种选型策略避开了将 3D 渲染框架引入桌面轻量化场景的性能黑洞，依靠视频编码自带的 Alpha 通道实现了极高的像素渲染效率。

4. 手把手极客实操：从零构建最小闭环

开发者在本地环境中部署 dsh-pet 插件，需要确保 Node.js 运行时及 pnpm 包管理器已经就绪。以下是在开发机上从源码克隆、构建到挂载到 DSH web 服务的标准工程命令。

# 克隆 dsh-pet 官方仓库到本地工作目录
git clone https://github.com/PC2005-cloud/dsh-pet.git
cd dsh-pet/dsh-pet

# 安装项目运行所需的全部依赖包
npm install

# 手动执行构建脚本，产出 lib、shared-core.js 桌面共享核心及类型声明文件
npm run build

# 将本地构建好的插件目录挂载到 DSH web 运行时实例中
dsh plugin --profile web add file:$(pwd)

完成上述步骤后，重启 DSH 服务即可在界面右上角观察到默认的桌面宠物实例，同时后台会自动触发 Electron 运行时的按需下载与透明置顶窗口拉起。

5. 生产落地踩坑指南与避坑建议 (Gotchas)

在生产环境或多开重度使用场景下，开发者需要注意底层运行环境的特定限制，避免因版本或媒体解码问题导致渲染异常。

⚠️ 避坑预警 [macOS 平台透明底色失效]：macOS 系统对默认的 webm 格式 Alpha 通道支持不佳，会导致桌面宠物窗口背景渲染为纯黑色。解决方案是在 GitHub Release 的 assets-mov 中下载兼容素材，并将配置文件中的素材后缀变量修改为 .mov。

⚠️ 避坑预警 [Electron 离线冷启动延迟]：在无外网或网络受限的隔离环境中，插件首次启动时自动下载 Electron 运行时可能会触发超时。生产环境部署前应当提前将对应平台的 Electron 压缩包放置于 ~/.dsh/electron/ 目录中，或者通过设置环境变量 DSH_PET_ELECTRON_PATH 直接指向本地现成的可执行文件路径。