dsh-ui-web/packages/dsh-pet

34Star2Fork0Issue0Watching

在 DSH Web 界面右下角养一只鲸鱼娘养成系宠物：模型会话活动驱动动画切换，摸头喂食攒亲密度升级，自带命名、拖动、隐藏与召唤。

分类🖥️ 界面增强🐾 趣味与陪伴
CAPTAIN1275CAPTAIN1275
·CAPTAIN1275/dsh-ui-web.git
语言
TypeScript
License
Apache-2.0
分支
main
dsh-plugindsh-plugin-marketdsh-plugins

安装

$ dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-pet

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

在 DeepSeek Harness Web 界面的右下角养一只鲸鱼娘养成系宠物：模型在思考、等待、调工具、完成时她会自动切换动画，你可以摸头、喂食、改名、拖动她，亲密度会从幼鲸一路涨到「深海羁绊」。

核心能力

  • 跟随模型会话状态切换动画：思考 / 调用工具时她"工作"、等待时她待机、完成时她跳跃庆祝、空闲时她呼吸
  • 摸头（10 秒冷却，+1 好感）与喂食（30 秒冷却，+5 好感、-1 小鱼干）两种互动，进度实时气泡反馈
  • 亲密度 4 级养成：幼鲸 → 伙伴 → 挚友 → 深海羁绊（100 点封顶），跨级时弹出"升级啦！"提示
  • 小鱼干经济：每完成 3 个模型回合 +1 条，每过 30 分钟自然 +1 条，库存上限 20 条
  • 自定义命名（1–20 字符）、悬浮面板喂食/改名/隐藏、按住拖动重定位（位置持久化）、隐藏后输入框出现"召唤{名字}"按钮
  • 全局浮层：会话生命周期外（新建会话空屏）也始终挂在右下角，不依赖某个会话或 UI 槽位

技术实现

  • 语言: TypeScript（带 JSX）+ Node.js（host 半区）+ React 18（browser 半区）
  • 关键依赖: @deepseek-ai/cordis（插件框架）、@deepseek-ai/dsh-host-webserver（挂 /api/pet/* 与 /pet/whale/* 路由）、@deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-ui-settings（浏览器半区 + 设置卡）、schemastery（DSH 设置 schema 校验）、React 18（由 DSH 外壳注入）
  • 架构模式: 双半区 cordis bundle。src/index.ts 是 host 半区，导出 name='pet' 与 cordis apply：构造 PetService 监听 session/event（turn/start、step/start、tool/call、turn/end 派发到 idle/waiting/thinking/tool/done 五个相位），通过 installSettingsSection 注册名为 pet 的设置分区，按 enabled 状态挂载路由。src/client/index.ts 是 browser 半区，createRoot → document.body 全局挂载浮层，每 800ms 轮询 /api/pet/state，配合 visibilitychange 在标签页回到前台时立即拉取，注册中英字典并把设置卡挂到 web-ui.plugin.item 槽位
  • 入口文件: host 半区 packages/dsh-pet/src/index.ts，browser 半区 packages/dsh-pet/src/client/index.ts，bundle 声明在 packages/dsh-pet/cordis.patch.yml:8-10（插入 id: pet），浏览器依赖注入在 packages/dsh-pet/package.json:37-49

适用场景

长时间盯着 DSH Web 跑模型任务、想要一点陪伴感的用户：模型思考时鲸鱼娘在脚下工作，完成时跳一下庆祝，亲密度随使用时长和工作回合自然增长。也适合想给 DSH 界面增加一点"养成感"、又不需要复杂配置的人——安装即用，关闭、隐藏、改名都能在设置里直接搞定。

前置依赖与兼容性

依赖最低版本说明
DSH 宿主0.1.0-rc.6+peerDependencies 锁到 @deepseek-ai/dsh-* ^0.1.0-rc.6；运行时只依赖 4 个浏览器端 @deepseek-ai/dsh-client-* 包
Node.js^22.19.0 或 >=24.0.0engines.node 字段明确要求
平台web（DSH 浏览器端）包内 dsh.client.platform: "web"，无桌面/终端适配
原生模块无运行时只引入 clsx + schemastery（纯 JS）；CSS Modules 由 lightningcss 内联为 <style data-plugin>
React^18.2.0peerDependency，由 DSH 外壳注入

安装方式

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-pet

配置项

配置类型说明默认值
启用宠物（enabled）开关插件总开关：关闭后浮层、轮询、API 路由一起停用开
显示宠物（visible）开关是否在屏幕上显示浮层；关闭后聊天输入区出现"召唤{名字}"按钮开
大小（size）数字（32–512，px）宠物显示尺寸，等于图集单格高度160
距右侧（right）数字（0–10000，px）距视口右边界的水平偏移（拖动时实时同步）24
距底部（bottom）数字（0–10000，px）距视口底边的垂直偏移（拖动时实时同步）20
名字（name）字符串（1–20 字符）宠物的显示名，会出现在悬浮面板和"召唤{名字}"按钮上"鲸鱼娘"
摸头冷却内部常量（affinity.petCooldownMs）两次摸头之间的最小间隔，源码可调10000 ms
喂食冷却内部常量（affinity.feedCooldownMs）两次喂食之间的最小间隔，源码可调30000 ms
小鱼干上限内部常量（treats.maxTreats）库存硬上限20
亲密度上限内部常量（affinity.AFFINITY_MAX）累计好感点的封顶100

说明：冷却时间、小鱼干经济参数、亲密度上限是源码内置在 affinity.ts / treats.ts 里的常量，普通用户用默认即可；如需调整可由 host 在 PetConfig 中传入 affinity / treats 字段覆盖。

常见问题

Q: 安装之后右下角没看到宠物怎么办？

A: 先确认已经重启了 dsh web——cordis bundle 的注入只在 host 启动时生效。如果还是不显示，打开浏览器控制台看有没有 pet.state transport error，再到设置 → 插件配置 → 宠物把"启用宠物"打开。

Q: 摸头 / 喂食没反应，是不是坏了？

A: 大概率是冷却中。摸头 10 秒内重复点击、喂食 30 秒内重复点击，鲸鱼娘会发气泡提示"今天摸够啦"或"吃饱饱啦"，冷却结束前都不会再生效。喂食还可能因为小鱼干库存为零被拒绝。

Q: 小鱼干用完了怎么补？

A: 不能直接充值。两条补给路径：每完成 3 个模型回合自动 +1 条，每过 30 分钟自然 +1 条。存满 20 条后不再涨，但亲密度仍会随时间缓慢增长（每 30 分钟 +1 点）。

Q: 卸载插件会丢掉亲密度和小鱼干吗？

A: 不会。所有状态（命名、亲密度、库存、位置、自定义）都写在 $DSH_HOME/pet.json（默认 ~/.dsh/pet.json），卸载插件不会删这个文件，重新安装后进度自动恢复。

Q: 能换成自己的角色或加多只宠物吗？

A: 当前版本不支持。本插件只内置了鲸鱼娘这一只，没有多宠物注册表或自定义图集投放机制；想换角色需要直接改源码中的 spritesheet.ts 几何定义与图集资源。

Q: 设置里看不到宠物配置卡怎么办？

A: 说明当前 DSH 版本没有把 pet 这个设置命名空间暴露到设置页（少数部署会限定 WEB_SETTINGS_NAMESPACES 白名单）。遇到这种情况可以直接编辑 $DSH_HOME/settings.yaml，或在 dsh-host-apiproxy 的白名单里加上 pet 后重启。

Q: 宠物的命名能改吗？有长度限制吗？

A: 能在悬浮面板的"改名"入口里直接改，1–20 字符，不能全是空白。改名后召唤按钮、悬浮面板都会同步显示新名字。

上手难度

入门 — 安装即用，零配置启动；可选的高级设置（尺寸、位置、命名）都在设置卡片里点几下就能改，不需要接触代码或配置文件。

已知问题与限制

  • failed 动画已经在 9 状态图集契约里占了一行（row 5），但当前 rc.6 还没有任何 DSH 事件源能点亮它，模型失败时表现等同于 idle
  • 插件依赖 rc.6 的 session/event（turn/start、step/start、tool/call、turn/end）派生动画相位；如果宿主版本低于 rc.6 或会话事件缺失，宠物会一直停在 idle
  • pet.json 文件损坏时，插件会静默回退到默认值继续运行；用户的亲密度、命名、库存、位置会丢失但不会报错提示
  • packages/dsh-pet/package.json 声明 "license": "Apache-2.0"，但子包内的 LICENSE 文件是 BSD-3-Clause——许可证元数据不一致，使用前以仓库根 LICENSE 为准
  • 浏览器半区在 apply 与 mount 时会向控制台输出 console.log 和 console.warn 调试日志，正式使用场景里会留下噪声
返回插件目录