YierPet 一二桌宠

一只住在你 macOS 桌面上的「一二」宝。它会散步、跳跃、挥手，会提醒你喝水和起身活动，深夜会催你睡觉，你摸鱼它会盯着你，CPU 飙高它会整只烧红，把它甩出去还会气鼓鼓地抗议。

纯 Swift + AppKit 原生实现，零第三方依赖、零额外权限、不起子进程、一条命令构建（可选的 Agent 哨兵会监听一个仅本机回环的事件端口）。

仓库：github.com/wusai2333/YierPet · 图文教程：docs/tutorial/index.html

功能特性

能力	说明
桌面悬浮	无边框透明窗口，置顶悬浮，无 Dock 图标，不打扰工作
四种形象	经典一二 / 活力一二 / 活力布布 / 一二布布合体，右键随时切换（见下节）
9 种动画	待机 / 左右跑 / 挥手 / 跳跃 / 沮丧 / 等待 / 工作中 / 审阅，逐帧图集驱动
自主行为	每 7~15 秒随机散步、跳跃、挥手，碰到屏幕边缘自动掉头
气泡说话	头顶弹出圆角气泡，文案从语料池随机抽取，淡入淡出
健康提醒	久坐 / 喝水 / 深夜关怀 / 摸鱼检测，四项独立开关（见下表）
系统哨兵	CPU 红温 / 内存压力 / 电量 / 磁盘空间，异常时才冒气泡，五项独立开关（见下表）
陪伴模式	早晨 / 午饭 / 下午茶 / 周五 / 编码久战，五项节律问候，独立开关（见下节）
Agent 哨兵	监听 qwen / qodercli / opencode / omp / omo / dsh 六个 agent 工具，等确认 / 报错 / 完成时气泡提醒（带摘要），菜单实时展示会话状态（见下节）
抛掷物理	拖住快速甩出，抛物线飞行、撞墙落地反弹；摔狠了会播放生气表情
零权限	不申请辅助功能、不申请屏幕录制，全部使用公开系统 API

四种形象

右键宠物 → 「形象」，四个版本随时切换，选择自动保存：

形象	内容	素材量
经典一二	原版精灵图集小熊，9 种动作全部可用	1 张图集
活力一二	白熊「一二」表情包动图，含红温全身着火名场面	24 组帧序列
活力布布	棕熊「布布」表情包动图	15 组帧序列
一二布布	一二和布布同框的合体表情包（菜单名「一二布布」）	12 组帧序列

表情包模式下的行为：

• 待机：从 idle / 犯懒 / 开心表情池随机循环播放，隔一会儿自动换一个
• 点击：切换到开心 / 比心表情
• 抛掷重摔：切换到生气表情
• 提醒联动：每个提醒会切换到对应情绪表情——CPU 红温时一二直接全身着火，久坐/摸鱼跳绳，喝水/低电量吃东西，深夜催睡，磁盘满了埋头干活
• 拖拽、抛掷物理、气泡、深夜睡意（播帧变慢）与经典版一致

每个表情是独立的透明帧序列（由 Live Photo 抠图裁剪而来），按需加载、播完释放，不会常驻大内存。素材归档在 Assets/Packs/，构建时拷入 app。

动作图鉴

待机	向右跑	向左跑
挥手	跳跃	沮丧
等待	工作中	审阅

健康提醒

提醒	触发条件	一二的反应
久坐提醒	连续活跃满 1 小时（离开电脑 5 分钟自动清零）	走到屏幕底部中央蹦跶拦你 +「坐了一个小时啦，起来动动嘛！」
喝水提醒	每 30 分钟（人不在时不计时）	举手示意 +「咕噜咕噜～该喝水啦！」
深夜关怀	23 点后进入睡意模式（待机动画变慢像打瞌睡），你还在干活则每 30 分钟关怀一次	担心地看你 +「熬夜会秃的！明天再做也来得及～」
摸鱼检测	视频类 App（B站 / 腾讯视频 / 爱奇艺 / IINA / VLC 等）连续前台 30 分钟	盯着你 +「都摸鱼半小时了哦……我可什么都没看见」

• 判断「你是否在电脑前」使用系统输入空闲时间（CGEventSource），前台 App 检测使用 NSWorkspace，均无需任何权限
• 提醒有优先级和 90 秒全局间隔，不会连环轰炸
• 每项提醒可在右键菜单独立开关，设置自动保存

系统哨兵

平时安静不打扰，只在指标异常时才提醒，全部使用原生系统 API（mach / IOKit / FileManager），不起子进程、不要权限：

哨兵	触发条件	一二的反应
CPU 红温	占用持续 90 秒 ≥ 85%（每 10 分钟最多提醒一次）	整只渐渐烧红 + 惊慌乱跑 +「好烫好烫！CPU 都 97% 了，是谁在偷偷挖矿！」，降下来后自动退烧
内存压力	系统内存压力达到 critical（事件驱动，非轮询）	等待动作 +「内存要被挤爆啦，关几个 App 让我喘口气～」
电量提醒	电量 ≤ 20% 且未插电（降到 10% 再催一次）；台式机无电池自动跳过	沮丧趴下 +「肚子饿了……电池只有 18% 了，插电插电！」
充满提醒	插电且电量 ≥ 98%（每次插电只提醒一次）	开心挥手 +「吃饱啦～电池充满了，可以拔线啦！」
磁盘空间	根分区剩余 < 10%（每 6 小时最多提醒一次）	审阅动作 +「磁盘只剩 9GB 空位啦，该大扫除了！」

红温效果说明：CPU 超过 60% 开始渐渐发红，越高越红（红色叠加层按精灵透明通道蒙版，只染身体不染背景），降回 60% 以下自动恢复。

陪伴模式

按一天节奏主动问候，优先级低于健康提醒与系统哨兵；每项可在右键 →「陪伴模式」独立开关：

项目	触发条件	说明
早晨问候	6～10 点且在电脑前	每天最多一次
午饭提醒	12 点且在电脑前	每天最多一次
下午咖啡	15 点且在电脑前	每天最多一次
周五撒欢	周五 17～19 点且在电脑前	每周最多一次
编码久战	Xcode / VS Code / JetBrains 等 IDE 连续前台满 2 小时	鼓励起身休息

Agent 哨兵

盯着你的 AI coding agent，不用守着终端。默认开启（未安装钩子前不会有任何动静），右键 →「Agent 哨兵」可停用，各工具可独立开关：

能力	说明
状态提醒	qwen / qodercli（官方 hook）、opencode（插件）、omp / omo（扩展）、dsh（Cordis 插件）接入事件上报：agent 等确认、报错、完成一轮时气泡 + 动作 + 提示音（提示音可关）
内容摘要	提醒气泡附带会话摘要：等确认显示要确认什么、完成显示 agent 最后回复片段、报错显示错误信息；截取原文前 60 字，仅本机处理
状态展示	菜单实时列出每个会话：干活中 / 等确认 / 已完成，久无动静的会话自动清掉
本机回环	只监听 127.0.0.1 上的一个最小 HTTP 端口收事件：无网络权限请求、不起子进程、无第三方依赖
静默兜底	YierPet 未运行时钩子静默失败，不影响 agent 本身；安装自动备份原配置，卸载只删 yierpet 自己的条目

使用：右键 → Agent 哨兵 →「安装 Agent 钩子」，卸载同样一键（覆盖 qwen / qodercli / opencode / omp / omo）。

dsh（DeepSeek Harness） 走独立的 Cordis 插件，不在这个一键安装里：

dsh plugin --profile web add github:wusai2333/dsh-yierpet-sentinel
# 用 TUI 的话同样装进 dsh-tui profile；装完重启 dsh 生效

插件仓库：dsh-yierpet-sentinel （零依赖、fire-and-forget：1 秒超时、全错误静默、YierPet 没运行直接跳过，绝不阻塞 dsh； 本仓库 integrations/dsh-sentinel/ 内也保留一份源码）。 配合隐藏 dsh 内置宠物（~/.dsh/settings.yaml 里 pet.visible: false），由一二接管陪伴。

安装（两种方式）

环境要求：macOS 13（Ventura）或更高版本。

方法一：Release 压缩包（推荐）

不用 Git，不用编译，解压后打开即可。

1. 打开 Releases（当前托管在 Gitee 镜像，GitHub 侧后续同步）
2. 下载 YierPet-mac.zip
3. 解压到任意文件夹（建议拖到「应用程序」），双击 YierPet.app

若 macOS 提示「无法打开」或「来自身份不明的开发者」：右键（或 Control+点按）YierPet.app → 打开 → 再点「打开」。

开机自启：把 YierPet.app 添加到 系统设置 → 通用 → 登录项。

方法二：克隆源码自己编译

适合开发者或 Release 尚未更新时。需要先安装 Xcode Command Line Tools（不是完整 Xcode）：

xcode-select --install

git clone https://github.com/wusai2333/YierPet.git
cd YierPet
./build.sh
open build/YierPet.app

国内若 GitHub 较慢，也可从 GitHub 镜像克隆：

git clone https://gh-proxy.com/https://github.com/wusai2333/YierPet.git

不需要完整 Xcode，不需要任何第三方依赖。

📖 图文教程（适合录视频时对照）：docs/tutorial/index.html（本地可用 open docs/tutorial/index.html 打开）。录制分镜见 docs/VIDEO_RECORDING_SCRIPT.md。

使用说明

操作	效果
拖拽	抓着走，宠物朝拖动方向做跑步动画
快速甩出	抛掷！重力 + 反弹的物理飞行，摔狠了会生气
单击	挥手打招呼（表情包模式为开心/比心表情）
右键	菜单：形象 / 动作（仅经典版）/ 随机行为 / 提醒设置 / 系统哨兵 / 陪伴模式 / Agent 哨兵 / 退出
按住 Option + 右键	隐藏的「测试提醒」菜单，立即触发任意提醒看效果

自定义

换台词：所有气泡文案在 ReminderCenter.swift 的 messages 语料池中，每类提醒 4 条随机抽取，直接加减即可。

调手感：常用参数都在 PetController.swift 顶部：

参数	默认值	含义
petSize	154 x 166	宠物尺寸
throwSpeedThreshold	550 pt/s	甩多快算「抛掷」
gravity	-3000 pt/s²	重力
floorBounce / wallBounce	0.45 / 0.6	落地 / 撞墙反弹系数

换形象：替换 Sources/YierPet/Resources/spritesheet.webp。图集契约为 8 列 x 9 行（每格 192 x 208，总图 1536 x 1872），行序：idle、running-right、running-left、waving、jumping、failed、waiting、running、review，未使用格保持透明。各状态帧数与帧时长定义在 SpriteSheet.swift。

改提醒节奏：阈值都在 ReminderCenter.swift 顶部（久坐 1h、喝水 30min、摸鱼 30min、CPU 85%、磁盘 10% 等）。

项目结构

YierPet/
├── Sources/YierPet/
│   ├── main.swift            # 应用入口（accessory 模式，无 Dock 图标）
│   ├── SpriteSheet.swift     # 图集切帧 + 9 状态帧时长定义
│   ├── PetController.swift   # 动画状态机、拖拽、散步、抛掷物理、菜单
│   ├── SpeechBubble.swift    # 头顶气泡（子窗口，自动跟随）
│   ├── ActivityMonitor.swift # 输入空闲时间 + 前台 App 检测
│   ├── SystemMonitor.swift   # CPU / 内存压力 / 电池 / 磁盘采集（纯原生 API）
│   ├── ReminderCenter.swift  # 健康提醒 + 系统哨兵调度 + 文案语料池
│   ├── PackLibrary.swift     # 表情包资源加载（形象枚举 + meta 解析 + 情绪检索）
│   └── Resources/spritesheet.webp
├── Assets/Packs/             # 三套表情包帧序列（yier / bubu / duo + meta.json）
├── docs/                     # README 素材、教程 HTML、视频录制脚本
│   ├── tutorial/index.html   # 安装与使用图文教程
│   └── VIDEO_RECORDING_SCRIPT.md
├── Info.plist                # App 元数据模板
├── build.sh                  # 一键构建脚本
└── Package.swift             # SwiftPM 描述（可选，build.sh 不依赖它）

常见问题

Q: 为什么 Dock 和程序坞里看不到它？ 设计如此（LSUIElement），桌宠不该占一个 Dock 位。退出请右键宠物 → 退出。

Q: 需要给什么系统权限吗？ 不需要。久坐/摸鱼检测用的都是公开 API，不申请辅助功能、屏幕录制等任何权限。

Q: 双击 app 提示"无法打开"？ 如果你是直接下载别人构建好的 .app（而非本地 ./build.sh 构建），macOS Gatekeeper 会拦截未签名应用：右键 app → 打开 → 再点打开即可。本地构建的没有这个问题。

Q: 摸鱼名单里没有我用的 App？ 在 ActivityMonitor.swift 的 slackBundleIDs 里加上它的 bundle id（终端 osascript -e 'id of app "App名字"' 可查询）。

形象来源

宠物形象由黄小B创作，取一张静态图经 ChatGPT 生成 9 行动画帧总表，再用本仓库配套流水线切分、镜像、校验、合成为精灵图集（基于 openai/skills 的 hatch-pet 图集契约）。

致谢

本项目基于原作者 xiaojieshi 的 xiaojieshi-bot/YierPet（Gitee：cat_10/YierPet）继续开发——一二、布布的形象与动画素材、桌宠本体与各类哨兵的原始设计均出自原仓库，在此致谢；本仓库在其基础上增加了 dsh 的 Agent 哨兵接入与若干修复。代码按 MIT 许可证发布，版权归属以 LICENSE 为准；二次分发请保留原作者署名。

许可证

MIT