前言¶
在 DeepSeek Harness（DSH）里写提示、等模型回复时，界面往往是静态的：你知道 AI 在忙，但视觉反馈有限。社区插件 dsh-pet-lucky 把一只会动的 3D 虎皮鹦鹉「Lucky」挂在 Web UI 右下角，并根据你是否在打字、消息是否已发出、答案是否到达来切换待机、走路、奔跑和飞行动作。下面介绍它是什么、怎么装、日常怎么用，以及 3D 不可用时的兜底行为。
这是什么¶
dsh-pet-lucky（仓库 don2ccc/dsh-pet-lucky）由维护者 don2ccc 发布，在 SkillHub 插件目录 中归类为 趣味换装。简介写明：以作者家虎皮鹦鹉 Lucky 命名，是一只面向 DeepSeek Harness Web UI 的 3D 桌面宠物。插件在客户端侧运行（package.json 中 dsh.client.platform 为 web，immediately: true），不依赖 ESP32 等外部硬件。
核心功能¶
经过上面的步骤理解定位后，可以把能力与交互分开看。
与 Harness 状态联动的动作¶
鹦鹉会随你在界面里的行为切换动画（剪辑之间约 0.26 秒交叉淡入淡出，非硬切）：
| 你在做什么 | 它在做什么 |
|---|---|
| 没有操作 | Idle (folded wings) 收翅站立，轻轻呼吸晃动 |
| 在输入框打字 | Walk (folded wings) 走 |
| 消息已发出、AI 在干活 | Run (folded wings) 跑 |
| 把它拖起来 / 答案到达 | Fly 张开翅膀飞 |
相机为 3/4 视角（方位 44°、俯角 12°）；飞行时会轻微拉远，避免翅膀被裁切。
桌面宠物式交互¶
- 可拖动位置。
- 单击可听一句台词；右键可触发「播报」。
- 约 4 分钟无操作会打瞌睡；窗口切走再回来会有欢迎行为。
3D 与 2D 兜底¶
- 正常路径使用 WebGL 2 渲染 GLTF 模型（内联 three.js r147）；模型带骨骼，实际使用 4 段动画（收翅待机、收翅走、收翅跑、飞）。
- 首次显示需联网：从 Polyfork CDN 下载约 6.1 MB 模型，之后缓存在 IndexedDB，不再重复下载。
- 若 WebGL 不可用或模型下载失败，会自动退回内联的 2D 立绘（base64 WebP），界面不会空白，也不会拖垮主 UI。
安装与启用¶
先做环境确认，再安装插件。
环境要求¶
- 使用 DeepSeek Harness 的 Web UI（桌面版或
dsh web）。 - 显卡需支持 WebGL 2（README 说明 2015 年之后多数集显/独显可满足）。
- 首次展示 3D 模型时需要网络，用于拉取 CDN 资源。
安装命令¶
命令行安装（与 README 原文一致）：
dsh plugin add github:don2ccc/dsh-pet-lucky
也可使用完整 GitHub 地址：
dsh plugin add https://github.com/don2ccc/dsh-pet-lucky
不用命令行时：设置 → 插件 → 添加插件，在输入框填入 github:don2ccc/dsh-pet-lucky。
装完后须 完全退出 DeepSeek Harness 再重新打开（插件在启动时加载，热更新不生效），鹦鹉会出现在右下角。
卸载：
dsh plugin remove dsh-pet-lucky
典型用法¶
安装并重启后，无需额外配置即可使用：在右下角观察鹦鹉随打字与回复节奏变化即可。
改台词与显示名字¶
所有可见文案在仓库 tools/3d/lines.json，含中文、英文两套字段：名字、点击台词、打字碎碎念、唤醒/完成/重连/播报等。新增 line9、line10 等键会被自动发现，无需改业务代码。
若要从源码改文案并写回构建产物，README 给出的流程为：
git clone https://github.com/don2ccc/dsh-pet-lucky
cd dsh-pet-lucky
# 编辑 tools/3d/lines.json
python tools/3d/apply_lines.py # 写回 client.js，自动备份并校验
dsh plugin add /absolute/path/to/dsh-pet-lucky # 用本地目录替换线上版本
再重启应用。注意：line1..line8 与 chatter1..chatter8 为必填，缺任一项时 apply_lines.py 会拒绝写入。
想调整动作快慢、机位、状态映射，可编辑 client.js 中的 CLIP_SPEED、CAMERA、const sceneState 等常量；说明见 tools/3d/README.md。改源码后可用 python tools/3d/build3d.py 重新生成 client.js。
适用场景与注意¶
适合谁：长期在 DSH Web UI 里对话、希望用轻量视觉反馈感知「空闲 / 输入中 / 模型工作中 / 回答到达」的开发者或个人用户。
权限与信任：插件随当前 DSH 进程在浏览器环境中执行前端逻辑；安装前建议阅读仓库源码与 MIT 许可证（package.json 标注版本 1.0.0，作者 don2ccc）。社区目录 SkillHub 为独立生态站点，与 DeepSeek / 幻方无官方从属关系；DSH 本身奉行「一切皆插件」，本文介绍的是社区贡献而非官方内置功能。
排查提示：
- 装了没反应：确认是否完整重启而非仅刷新页面。
- 变成不动 2D 图：3D 路径未走通；可向
localStorage键名dsh-pet:trace查看加载日志（WebGL、下载、渲染哪一步失败），提 issue 时可附上。 - 首帧等待一两秒：首次下载模型属正常现象。
3D 模型致谢：Cove Parrot by Polyfork，CC BY 4.0；渲染栈为 three.js r147（MIT）。完整第三方声明见仓库 THIRD-PARTY-NOTICES.md。
结尾¶
dsh-pet-lucky 把状态机式的动画和可拖动的桌宠交互叠在 DSH Web UI 上，并在 WebGL 或 CDN 不可用时退回 2D，适合作为写 Harness 时的伴生小部件。目录页：https://www.skillhub.cn/plugins/don2ccc/dsh-pet-lucky；源码与安装说明：https://github.com/don2ccc/dsh-pet-lucky。
