桌宠总览

模拟联动演出的第一步（issue #122 第 4 项）：POST /lock 拿一个 lockId，这段时间这只宠物归你独占——它自己不动、也不弹气泡 （随机动画、自主走位、碎碎念、余额、工作状态一概让路）。
占用期间，本页其他卡片里的接口（投喂、点播动画、位置、抛掷、清空气泡） 必须带上这个编号，否则回 lock-required；带错编号回 lock-lost（附 cause：过期 / 已释放 / 被用户抢走）。本页会自动带上，不用手填。
取锁和续期是同一个接口：给 lockId 就是续期。续期是持锁者 每隔几秒要做一次的心跳——不续期的话，到点锁自己就没了。
用户优先：用户拖一下宠物、或把它隐藏/关闭，锁会立刻被撤掉，所以别把它当成能长期占着的东西。 没锁的时候那些接口连 lock 参数都不看，行为跟以前一模一样。

模拟宿主侧其他插件（如巡检类插件）调用 POST /broadcast： 不生成内容，只搬运。 配图两种形态二选一（issue #122 第 1 条）：给名称时只接受该桌宠条目表情包池内的名字 （pet/<素材根>-memes/ 独占 → 用户 memes/ → 包内 assets/memes/）， 下拉框只列磁盘上真实存在的图；给地址时是完整 URL、不查池。 两个都给会被判 bad-request。
时长可调、可关掉动画联动、可提前撤回——这三件事是 issue #122 第 5 条要的。 内容与频率由调用方自己负责：不设长度限制，也不限频；「清空气泡」只收起说话气泡， 正在播的动画、余额气泡、工作状态气泡都不动，没有气泡时也回 ok。

两种形态二选一（issue #122 第 1 条）：给名字时必须是该宠物动画池里真实存在的 （下拉框列的就是池子），效果与右键菜单点「动作」完全一致——文字类先强制朝左的镜像修正、 移动类走真实位移；给地址时是第三方自带的素材，完整 URL、不查池， 消费端直接换源播一次、不走菜单语义（裸地址没有"是不是文字类 / 是不是移动类"这些属性）。 两个都给或都不给都会被判 bad-request。
点播是"插播一段"：播完回到正常动画链；display: both 时两端都会播。 要看回执请用下面那张「播放回执」卡片。

POST /anim 只代表"受理了"，accepted ≠ 播完。 响应里的 playbackId 可以查 GET /playback/<id>：勾选要等的状态，命中即停； 没命中就按「轮询时间」反复挂起等待（长轮询）。

模拟第三方调用 POST /position 与 POST /throw。 两条都是运动指令：写进状态后由渲染端执行，不引入任何新物理——位置按 mode 走三条既有路径（直接 / 弹簧 / 直线），抛掷复用已有的 重力 / 反弹 / 地面摩擦 / 落地 Q 弹。
手指正按在宠物身上时会被静默丢弃：接口仍回 ok， 但宠物不动，而且轮询也看不出来（这是设计上的已知缺口）。

模拟第三方调用 POST /pet-display：只传宠物 id 与目标 display，不用回传整段 pets——层归属（写 main-config.jsonc 还是 pet/<前缀>-config.json）由宿主按 id 反查。 桌面端与浏览器端的右键菜单「显示位置」走的就是它。
这管的是"哪个端"，不是屏幕坐标——屏幕坐标见同页的「位置与抛掷」。 这是持久配置写入，不是临时隐藏：选「都不」后这只宠物两端都不可见， 恢复入口是设置页的「显示在哪端」下拉框。返回体是改动后的成品聚合，本页据此刷新宠物清单。