Alih-b/fox-pet

Fox Pet

Fox Pet（fox-pet）将 Folio——一只桌面伴侣狐狸——添加到你的 Omarchy
工作区。她会沿着你屏幕的底部漫步，在你闲置时休息，随着平滑的伸展过渡醒来，
并响应鼠标交互和物理效果。

MIT
Omarchy
DSH

该插件使用同一套资源在两个 shell 中运行。

| | Omarchy | DeepSeek Harness |
|---|---|---|
| 运行时 | Quickshell | Dynamic Cordis 插件 |
| 源码 | Service.qml、Panel.qml、BarWidget.qml | dsh/ |
| 安装 | 见下文 | dsh/README.md |

两者都读取 assets/spritesheet.webp 和 assets/pet.json。DSH 移植版不附带
该美术资源的副本。

安装

通过 Omarchy 插件管理器安装：

omarchy plugin add https://github.com/Alih-b/fox-pet --enable

对于本地开发，在做出更改后从你的检出目录运行以下命令：

./install.sh

这会安装你当前的工作文件（包括未提交的编辑），重新加载插件，启用它，并显示狐狸。
它会验证 shell 已加载安装的代码，并打印先前插件备份的位置。
你无需先移除插件或提交更改。
omarchy plugin add "$PWD" 克隆已提交的 Git 历史，不包含未提交的编辑。

要将常规 Git 安装更新到最新发布的版本：

omarchy plugin update fox-pet

控制

你可以使用 Fox Pet 状态栏小部件召唤或关闭 Folio，或者使用鼠标直接与她交互：

| 输入 | Folio 的响应 |
|---|---|
| 左键单击 | 戳一下 Folio——她会挥动一只爪子，或从睡眠中轻柔地醒来；唤醒过程中再次戳她会让起身动作完成 |
| 双击 | 切换睡眠状态——她会蜷缩成一团，或伸展着醒来 |
| 向下滚动 | 让她入睡 |
| 向上滚动 | 促使她跳跃 |
| 单击并拖动 | 让她在屏幕间移动（如果在休息时被移动，她会保持睡眠状态） |
| 甩动 | 在快速拖动过程中松开，会带着动量将她水平抛出 |
| 抚摸 | 用光标在她的毛发上来回抚摸会触发俏皮的跳跃 |
| 右键单击 | 将她置于活动显示器的中央 |

命令

通过 omarchy-shell 从脚本或终端控制 Folio：

omarchy-shell fox-pet toggle       # 召唤或隐藏 Folio
omarchy-shell fox-pet sleepToggle  # 切换睡眠 / 唤醒
omarchy-shell fox-pet jump         # 让 Folio 跳跃
omarchy-shell fox-pet reset        # 将 Folio 居中于当前活动显示器
omarchy-shell fox-pet state        # 查询状态（开/关、状态、方向、帧）

帧图集

assets/spritesheet.webp 中的每个精灵帧在 assets/frame-names.json 中都有唯一的名称——在讨论动画或渲染问题时，请使用这些名称（例如 sleep-deep-curl、turn-quarter-right）。

一个包含所有命名帧、行元数据和实时节奏预览的私有查看器可以在本地重新生成（输出已被 gitignore）：

python3 tools/build-frame-atlas.py
xdg-open scratch/frame-atlas.html

行走验证（需要 Quickshell 和 Qt Quick Test）：

python3 -m unittest discover -s tests
QT_QPA_PLATFORM=offscreen QT_QPA_PLATFORMTHEME= QT_QUICK_BACKEND=software /usr/lib/qt6/bin/qmltestrunner -input tests/tst_walk_render.qml

这些测试检查不同刷新率下的距离和步幅连续性、起步和撞墙折返、真实的定时器驱动行走，以及在两个方向上与六个作者制作的行走裁剪图进行渲染像素对比。

动画调优

先召唤 Folio，然后使用开发命令重复某个动作：

omarchy-shell fox-pet preview walk -1   # 从当前屏幕中心向左行走
omarchy-shell fox-pet preview greet 1   # 播放一次问候，然后保持空闲
omarchy-shell fox-pet debugState        # 请求的动作、实际姿态、运动、重载状态
omarchy-shell fox-pet reloadAnimationMeta
omarchy-shell fox-pet resume            # 恢复正常自主行为

preview 需要方向为 1 或 -1，并接受 idle、walk、
sitRight、sitLeft、greet、sleep、play、alert、yawn、think、
spin、somersault 和 jump。每次调用都会清除临时运动，并从当前显示器中心的地面位置开始。作者设定的朝向限制仍然适用；例如，问候动作无论方向如何都面向前方。
空闲、行走、坐下和睡眠会保持，直到收到另一个命令。其他片段播放一次后返回空闲；跳跃在落地后结束。行走和跳跃需要启用 Wander around 设置。在预览或恢复之前，请释放任何拖拽。

使用帧图集选择姿态，编辑 assets/pet.json 中的 sequence 和 durations，运行 reloadAnimationMeta，并检查 debugState 直到 metadataStatus 为 ok。然后重复预览命令，使用实际渲染器和新的片段时长来审查更改。重载是异步的；无效或无法读取的元数据会保持工作副本不变，并在 metadataStatus 中报告错误。元数据更改无需重启 shell。

预览模式会暂停随机行为而不更改设置。鼠标操作仍然有效，因此在比较重复预览时请让指针远离。预览状态是临时的，预览期间会抑制位置保存，隐藏狐狸会清除预览模式。resume 会重置为地面空闲状态并重新启动
普通动作计时器。上述测试还使用资源的私有副本覆盖了预览控件和元数据重载。

DeepSeek Harness

DSH 无法加载 QML，因此相同的行为被重新实现为一个 Dynamic Cordis 插件。它分为两部分：宿主部分通过本地路由提供 assets/spritesheet.webp，客户端部分在 Web UI 中运行动画、物理和输入处理。它使用相同的 pet.json 时间参数，但 idle 和 sitting 除外，这两个被重新编排了——参见 dsh/README.md。

手势与桌面版不同：

| 输入 | 响应 |
|---|---|
| 左键单击 | 戳一下——她会挥手，或者伸个懒腰醒来 |
| 下落中左键单击 | 接住她；该高度成为她站立的表面 |
| 双击或中键单击 | 切换睡眠状态 |
| 向下滚动 / 向上滚动 | 睡觉 / 跳跃 |
| 单击并拖动 | 移动她；松开后她会掉落，并以限定的速度下落 |
| 甩动 | 快速松开会使她滑行至停止；足够快的甩动会使她旋转 |
| 猛烈撞墙 | 她会在原地翻筋斗；墙壁不会将她弹回 |
| 用光标在她身上划过 | 俏皮地跳跃 |
| 右键单击 | 将她重新置于地板中央 |

该移植版本由五个仅需 Node 的测试套件验证：

cd dsh
npm test

它们覆盖了插件的形态、225000 个 tick 内的引擎不变量、idle 和 sitting 的编排、组件发出的 CSS，以及 60 项交互、物理和布局断言。

资源

assets/ 是美术资源的唯一副本：1536×2288 图集、帧名称映射，以及动画规范 pet.json。两个外壳都从中读取，因此新增一帧只需添加一次。

许可证

MIT。参见 LICENSE。