为 DSH Web 界面添加一只悬浮动画宠物：51 个透明动画自动切换、可点击互动、可拖拽、可屏幕漫游，零 LLM 调用纯前端装饰。
安装
$ dsh plugin --profile web add github:PC2005-cloud/dsh-pet在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
一句话定位
在 DeepSeek Harness 的 Web 界面里养一只会自己动的桌宠。它常驻在右下角，自己呼吸、随机做小动作、偶尔朝你东张西望或在屏幕里走走，你也可以点击或拖拽它到任意位置。
核心能力
- 在 Web 界面右下角常驻一只手绘风透明动画宠物，无需任何配置
- 51 个动画按概率自动接龙：待机呼吸、随机动作（如哼歌、玩魔方、炸毛、小提琴演奏、吃白饭、四季动作等）、偶尔转向
- 屏幕漫游：朝当前朝向方向走，自动检查边界不出屏，漫步距离每次 60~240px
- 点击互动：在人物身上点击随机触发"开心跃动 / 害羞惊讶 / 傲娇生气"三种回应动画
- 拖拽：抓起来拖到屏幕任意位置，松手后宠物停在新位置且窗口缩放时跟随
- 左右朝向：动画按朝向 CSS 镜像，宠物始终朝向你或转身走开
- 双缓冲播放：切换动画时两段视频交叉淡入，永远没有空白帧
- 无障碍：响应系统的"减少动态效果"设置，自动关闭过渡动画
技术实现
- 语言: JavaScript（ESM 宿主半侧 + 官方 CJS bundle 形态浏览器半侧），附 TypeScript 类型声明
- 关键依赖:
@deepseek-ai/cordis（插件框架）、@deepseek-ai/dsh-home-paths（解析 DSH 主目录）、@deepseek-ai/dsh-host-webserver（注册 /pet 路由）、@deepseek-ai/dsh-client-runtime（浏览器半侧运行容器）、React 18（由 DSH 外壳注入） - 架构模式: 双半侧 bundle —— 宿主半侧在 Node 进程注册
/pet/{thumb|full}/<file>路由提供 WebM 资源；浏览器半侧以window.__ModuleLoader__.load({id,factory})形态注册到shell.overlay列表槽，挂载为浮动层（点击穿透、不挡界面操作） - 入口文件: 宿主半侧
dsh-pet/lib/index.js，浏览器半侧dsh-pet/lib/client.js，挂载声明dsh-pet/cordis.patch.yml
适用场景
想让 DSH Web 界面更有人情味、又不愿被插件打断工作流的用户。宠物是纯装饰：没有天气、监控、Agent 状态感知这些业务功能，零 LLM 调用，不消耗模型额度，适合想要一点陪伴感又怕插件拖累体验的人。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+ | peerDependencies 声明 cordis、home-paths、host-webserver、client-runtime、client-ui-slots 均 ^0.1.0-rc.6 |
| Node 运行时 | 未声明 | 包未声明 engines；宿主半侧用 ESM 与 node:fs/node:url，需 Node ≥ 14 起支持 import.meta.url 的 LTS |
| 平台 | web | dsh.client.platform = "web"；未做 desktop/terminal 适配 |
| 原生模块 | 无 | 纯 Node 标准库 + 浏览器标准 API |
安装方式
dsh plugin --profile web add github:PC2005-cloud/dsh-pet
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
size | 数字（px） | 宠物显示高度。浏览器侧目前走代码默认值，调整需改源码；patch 中已声明但暂未下发到浏览器 | 260 |
position | 字符串 | 默认出现的角落：bottom-right 或 bottom-left。同上，浏览器侧未生效 | bottom-right |
fullRoot | 路径字符串 | 高清原始素材目录（1200×1200 母版）。需从 GitHub Releases 下载 assets-videos 后才能生效，否则 /pet/full/ 路由返回 404 | $DSH_HOME/pet-assets |
常见问题
Q: 跑起来会消耗 LLM 或网络资源吗？
A: 不会。运行时零 LLM、零 API 请求；动画是浏览器本地播放的 WebM 文件，命中 1 小时浏览器缓存后不再下载。
Q: 需要额外配置吗？
A: 不需要。安装即用。如果想换角落、调高度或启用高清原始素材，要手动改 DSH_HOME 或源码默认值——当前浏览器侧配置管线尚未打通。
Q: 支持哪些平台？
A: 仅 DeepSeek Harness Web（dsh web）。包声明的运行平台是 web，没有为 desktop/terminal 端做适配。
Q: 如何卸载？
A: 执行 dsh plugin --profile web remove dsh-pet，重启 dsh web 即可恢复原状，插件不会留下任何持久数据。
Q: 想换成自己的角色怎么办？
A: 仓库自带"提示词 → 绿幕视频 → 透明动画"全流程管线（scripts/ 目录下 7 个 Python 脚本 + ffmpeg）。按 prompts/ 配方生成源视频，跑完 4 步处理链得到 thumb 资源，覆盖 dsh-pet/assets/thumb/ 即可替换。
Q: 调整 size / position 后没生效？
A: 这是已知限制。宿主半侧（cordis.patch.yml）声明的 size、position 暂时传不到浏览器，client 实际收到的是空对象，所以行为参数走代码默认值。该项浏览器侧配置化正在规划中。
Q: 浏览器控制台看到 [dsh-pet] roll=... 日志是 bug 吗？
A: 不是 bug。源码中标注为"测试用"的概率打印日志（lib/client.js:339），方便核对动画分布；正式版本可删除，作者保留未移除。
上手难度
入门 — 安装一行命令、无需任何配置即可看到效果，无需阅读文档或调整参数。
已知问题与限制
size/position配置项的浏览器侧下发未打通，patch 配置目前只影响宿主半侧，浏览器走代码默认值（lib/client.js:182-185、README.md:45-49）- 浏览器控制台会持续输出
[dsh-pet] roll=...调试日志，标注为"正式版可删除"但当前未移除（lib/client.js:338-339） - 高清原始素材（1200×1200 母版）未随 npm 包发布，使用前需手动从 GitHub Releases 下载
assets-videos解压到$DSH_HOME/pet-assets/，否则/pet/full/路由返回 404（DESIGN.md:25） - 拖拽时的命中区域由硬编码
HIT_BOX矩形限定（lib/client.js:99），动画人物视觉宽度与命中宽度差异较大时可能影响点击手感
一只住在 DeepSeek Harness Web 界面里的桌面宠物：待机呼吸、随机动作（含打瞌睡）、偶尔转向、屏幕漫游、点击反应、可拖拽。
这不是一个普通插件，而是完整的三件套项目：
① 提示词（配方） → ② 素材生成链（引擎） → ③ 插件（成品）
AI 生成动画的配方 源视频 → 透明动画的管线 运行在 DSH 里的宠物
任何人 clone 本仓库，都可以从零生成自己的桌面宠物——换角色、换动作、换风格，全流程可复现。
快速开始（安装插件）
dsh plugin --profile web add dsh-pet
重启 dsh web，宠物出现在右下角。
从零生成你自己的宠物（完整流程）
① 提示词 → 源视频
用 AI 视频生成工具（如可灵、Runway、豆包等，本项目素材即由豆包生成），按 prompts/桌面宠物 10 秒动作提示词.md 的配方生成 51 个 10 秒绿幕视频：
- 视频比例 16:9，背景纯绿幕（#00FF00）
- 人物位置/大小固定（头顶 ~20% 高度、脚底 ~85% 高度）
- 动作全程在画幅内，首尾帧为标准正面站立
- 每段动画按秒分解（0-10s 各阶段动作）
生成结果放入 video/（51 个 mp4）。
源视频获取：为控制仓库体积，
video/源视频不入 git。需要复现素材链时，从 Releasesassets-videos下载 51 个 mp4（拼音文件名），放入video/即可。一键批量下载（需 gh CLI）：mkdir -p video && cd video && gh release download assets-videos --repo PC2005-cloud/dsh-pet
② 源视频 → 透明动画（素材链）
cd scripts
python watermark_step01.py # 水印遮罩填充 → step01/
python chroma_step02.py # 绿幕抠像转透明（HSV 色相）→ step02/
python normalize_step03.py # 归一化 2160×1215 统一站立居中 → step03/
python encode_thumbs.py # 转码 640×360 播放变体 → step04/
依赖：Python 3 + ffmpeg + numpy + scipy（素材链脚本自动用工作区 .tools/ 下的 ffmpeg）。
③ 动画 → 插件
# 把 step04 的播放变体同步进插件包
cp step04/*.webm dsh-pet/assets/thumb/
# 本地安装插件
dsh plugin --profile web add file:D:/path/to/dsh-pet
中间产物（step01-04）由脚本生成、不入仓库；
video/源视频和脚本是成果、入库维护。
项目结构
├── prompts/ # ① 51 个动作的生成提示词（绿幕规范 + 按秒分解）
├── scripts/ # ② 素材生成链（7 个 Python 脚本）
├── video/ # ② 源视频（51 个绿幕 mp4 + 水印 mask）
├── tools/ # 开发工具：preview.html（素材链各阶段效果预览）
├── dsh-pet/ # ③ 插件（可独立 npm 发布）
│ ├── lib/index.js # host 半侧：/pet 视频路由
│ ├── lib/client.js # 浏览器半侧：动画链 + 双缓冲播放
│ └── assets/thumb/ # 640×360 播放动画（51 个，~36MB）
├── DESIGN.md # 设计与实现文档（含踩坑记录）
└── LICENSE # MIT
插件功能
- 纯粹的桌宠：不掺任何业务功能——没有天气查询、系统监控、Agent 状态感知，就一件事：陪你。零核心改动（不碰 DSH 内核）、零模型成本（运行时不需要调用任何 LLM 或 API）
- 动画链：每个动画（含待机）播完立即按概率选下一个——30% 待机 / 10% 转向 / 40% 动作 / 20% 移动，首尾相接永不停止
- 屏幕漫游：朝 facing 方向行走，先检查空间、不走出屏幕
- 点击/拖拽：点击有回应动画，可拖到任意位置
- 左右朝向：所有动画可镜像，人物可朝左/朝右
- 落地对齐：动画统一脚底线，宠物始终站在地面上
- 流畅切换：双缓冲交叉淡入，切换无空白帧
运行效果
宠物实际运行在 DSH Web 界面中的样子：
效果预览
全部 51 个动画（640×360，插件实际播放用的资源）——GIF 预览存放于仓库 dsh-pet/assets/preview/（raw 直链渲染，文件名采用拼音便于跨平台）；完整透明视频见 dsh-pet/assets/thumb/：
待机 / 转向
移动
动作
点击回应
拖拽
注：动画为透明背景；GIF 预览中透明部分显示为页面底色，实际 webm 播放为透明。
文档
- 设计与实现 —— 架构、动画链模型、素材链、踩坑记录
许可
- 代码：MIT
- 素材（动画/提示词）：见仓库说明
