Agent-desktop-pet
Health Gecti
- License — License: NOASSERTION
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 20 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
跟随 Codex / Claude Code / Gemini 等 12 个 Agent 实时状态换表情的 Windows Live2D 桌面宠物(只读本地、不联网)
Agent 桌宠
原名「Codex 桌宠」(CodexPet);2.0 起接入 12 个 Agent,正式更名为 Agent 桌宠。
一只贴在 Windows 桌面上的 Live2D 小桌宠:它跟着 Codex(或你接入的其它 Agent)的实时状态换表情——
思考中、执行中、等待你、审阅找工具、同步中、被挡住、出错了、完成了、被打断,
一共 9 个状态各有各的表情。眼睛会跟着鼠标转(带惯性和回正动画),旁边有一张任务进度卡片,
右下角三个图标(撤回 / 铅笔 / 橡皮擦)能自己配功能。
状态来源是各 agent 写在本地会话记录里的数据(默认 Codex,可在设置里切换),只读、不联网。
当前版本 2.0(2026-10-11):多 Agent 接入、任务栏等系统覆盖层输入隔离、状态判定优化、点击 / 拖动修复,
详情见更新日志。

目录
特性
- 状态跟着 Agent 走:读 Codex 的本地会话记录(也可在设置里切换成接进来的其它 11 个 Agent),翻译成 9 个状态;每个状态可以单独指定表情。
- 状态判定有兜底:工具结果延迟或丢失、回合长时间安静、Agent 提问等场景都有对应判断 ——
不会卡在“执行中”,也不会误报“等待你”;“完成了”稳定显示 90 秒。 - 眼神会跟着你:按鼠标相对窗口中心的偏移映射,眼睛先动、头慢半拍、身体再慢一点;
鼠标离开跟随范围会先顿一下再缓入缓出地回正(不是硬拽回去)。 - 表情不是死的:每个状态有一“池”表情,隔一会儿换个心情;有 40+ 个表情可逐条开关,
道具/贴纸类表情可以整体屏蔽。 - 任务进度卡片:显示当前任务名、已用时、工具调用数、上下文用量;两种外观(半透明毛玻璃 / 实色)。
开着 / 收起的状态会记住:下次启动桌宠时保持上次收起前的样子(开着就自动展开,收起就保持收起)。 - 底部三个图标可编程:撤回 / 铅笔 / 橡皮擦,每个的单击和右键都能配功能
(打开设置、切编辑模式、撤销表情、清空卡片、隐藏到托盘、静音动画…… 或者 Codex 联动那套)。 - 图标按图上的实际位置命中,点画纸空白处不会串格。
- 系统覆盖层让路:光标在任务栏 / 开始菜单 / 任务栏预览 / 托盘弹出等系统 Shell 覆盖层上时,
点击、拖动、滚轮都原样交给系统,桌宠不抢输入;桌面、编辑器等普通窗口上的互动不受影响。 - 快速点按不丢:左键单击 / 双击 / 拖动统一由鼠标钩子判定(带按下 / 抬起脉冲队列),
两次轮询之间的快速操作不会漏;点在角色身上也不会选中下面窗口的文字。 - 四种互动:摸头(脸红/爱心眼)、双击换表情、拖动搬家、滚轮缩放(30%–160%)。
- 跟随虚拟桌面:切桌面时它跟着过去,不会“看不见”。
- 纯本地:不联网、不读密钥、日志自动截断。
运行环境
| 项目 | 要求 |
|---|---|
| 系统 | Windows 10 1809 以上 / Windows 11(详见兼容性与适配) |
| Python | 64 位 CPython 3.12(vendor/ 里的二进制是按 3.12 编译的) |
| 运行时 | Microsoft Edge WebView2 Runtime(Win11 自带;Win10 一般随 Edge 装好,没有的话点这里装) |
| 权限 | 普通用户即可,不需要管理员,不写注册表敏感项、不装驱动 |
| 网络 | 不需要(只有 127.0.0.1 上的一个本地网页服务,用来把界面喂给 WebView2) |
Python 依赖(pythonnet 等)已经放在 vendor/ 里,开箱即用;
如果你想自己装,见 requirements.txt。
安装与启动
- 把整个文件夹放到一个不会被误删的位置(比如
D:\CodexPet)。 - 确认
pythonw.exe能被找到,二选一:- 把 Python 的安装目录加进
PATH; - 或设一个环境变量
CODEXPET_PYTHON指向python.exe的完整路径。
- 把 Python 的安装目录加进
- 双击
启动桌宠.cmd(能看到报错)或启动桌宠.vbs(无黑框)。形象会出现在屏幕右下角。 - 想要桌面快捷方式:右键
启动桌宠.vbs→ 发送到 → 桌面快捷方式。
其它脚本:
| 脚本 | 作用 |
|---|---|
停止桌宠.cmd / 重启桌宠.cmd |
关闭 / 关闭再启动 |
诊断.cmd |
自检一次(约 25 秒),把日志打出来并导出 selftest.png |
开机自启-开启.cmd / -关闭.cmd |
登录 Windows 自动启动 |
清理缓存-释放空间.cmd |
删掉 WebView2 缓存(通常 200–400MB),下次启动自动重建 |
创建桌面快捷方式.cmd |
在桌面创建带桌宠图标的「Agent 桌宠」快捷方式(已有则不重复;名字可自己改) |
首次启动会自动在桌面创建 「Agent 桌宠」 快捷方式(图标 = 形象头像,指向本文件夹的启动器)。
已有同名、或已有指向本桌宠的快捷方式时不会重复创建;不喜欢可以在「设置 → 排查」里删掉,
删掉后不会再自动出现(想用时可在设置里重建,或双击文件夹里的创建桌面快捷方式.cmd)。
想彻底卸载:先
停止桌宠.cmd,再删掉整个文件夹;如果开过开机自启,
顺便删掉shell:startup里的CodexPet.lnk,或在设置里把开关关掉再保存一次。
怎么玩
| 操作 | 效果 |
|---|---|
| 鼠标靠近 | 眼睛 + 头跟着转,离开范围后平滑回正 |
| 左键单击角色 | 摸头:脸红 / 爱心眼 / 做个动作 |
| 左键双击角色 | 换表情(在允许的表情里循环) |
| 左键单击底部图标 | 执行那里配好的功能(弹出「确认 / 取消」后再执行) |
| 右键单击图标 | 执行那一项配的右键功能 |
| 右键单击角色 | 菜单:进度卡片 / 刷新卡片信息 / 摸头 / 换表情 / 随机动作 / 设置 / 切到 Agent 窗口 / 切换卡片 Agent(子菜单)/ 重新载入 / 重画窗口 / 退出 |
| 左键按住拖动 | 把桌宠搬到别处(松开即停) |
| 滚轮 | 光标在角色身上滚动 = 缩放(30%–160%) |
| 双击桌宠 | 打开设置窗口(也可以用右键菜单里的「设置…」) |
设置项一览
设置窗口里分 7 栏,每一栏标题右边都有一个 ↻ 圆圈按钮 = 只把这一栏恢复默认,
右下角还有整页的「恢复默认」。改完点「保存并应用」才生效(不想改就点「放弃更改」)。
| 栏 | 内容 |
|---|---|
| 外观 | 桌宠大小(30%–160%)、不透明度、视线跟随范围、自动切换表情、自动动作/闲置表演、始终置顶、显示状态小标签、渲染帧率上限(30/60/90/120/144/165/240 帧或不限制,旁边实时显示当前 fps) |
| 行为 | 接入的 Agent(现在 12 个,见接入其它 Agent)、进度卡片外观(半透明+模糊 / 实色)、卡片与桌宠间距、卡片跟着桌宠放大、跟随虚拟桌面、开机自动启动、滚轮缩放开关、卡片毛玻璃开关 |
| 底部按钮与功能方案 | 桌宠编辑 / 恢复 / 清理,或 Codex 联动;每个图标的单击 / 右键各选一个功能 |
| 状态对应的表情 | 9 个状态各选一个表情(模型里 40+ 个随你挑) |
| 表情白名单 | 逐条勾选哪些表情允许出现(不想要的贴纸/道具类取消勾选) |
| 动作与表情播放 | 表情最短保持时间、换表情概率、顺带做动作的概率、闲置动作间隔、动作逐条开关、动作间隔 |
| 排查 | 记录鼠标事件到日志、打开日志、清空日志、打开程序文件夹、重新载入形象、清除缓存并重启(显示 WebView2 缓存占用)、桌面快捷方式(创建/删除)、退出桌宠 |
「开机自动启动」这行字是微红色的,提醒你注意:它会往启动文件夹放快捷方式。
底部三个图标的配置长这样(每个按钮的「单击 / 右键」各配一个功能):
性能实测
下面这组数字是在作者机器上实测的,不是估算:
测试机:Windows 11 25H2(Build 26200)/ 20 逻辑核 / 屏幕 2560×1600 @150% 缩放 /
桌宠缩放 100%(窗口 600×930 物理像素)/ 空闲(不动鼠标、不做动作)。
CPU
| 项目 | 实测 |
|---|---|
| 空闲 CPU | 15 秒采样只花掉 0.41 秒 CPU ≈ 单核 2.7%、整机(20 核)0.14% |
| 渲染帧率 | 由设置里的「渲染帧率上限」决定,默认 60 帧;实测把上限设成 30 / 90 / 60 时,实际渲染帧数分别是 29 / 86 / 59 fps,设成"不限制"时 149 fps(跟着屏幕刷新率走) |
| 拖动 / 缩放瞬间 | 短时升高:拖动时每秒约 60 次窗口移动(日志实测 63 次/秒);停止即回落 |
帧率上限越高越顺滑,也越费电。60 帧在 60Hz 屏上已经足够;
120/144/165/240Hz 屏想更丝滑就往上调,"不限制"= 跑满屏幕刷新率。
设置里那一行会显示当前实际帧率,改完 3 秒内就能看到效果。
内存(任务管理器里整棵树)
| 进程 | 占用 |
|---|---|
pythonw.exe(宿主:窗口、鼠标、状态翻译) |
约 104 MB |
msedgewebview2.exe ×3(浏览器主进程 + 渲染 + GPU) |
约 178 MB(125 / 39 / 14 MB) |
| 合计 | 约 282 MB |
说明:大头是 WebView2(相当于一个精简版 Edge)。模型贴图是固定的两张(2048 / 1024),
缩放不会重新上传纹理,所以缩放大小对内存影响有限。关闭桌宠后这些内存全部释放;
屏幕高度有限时,放大上限会自动收(见下一节)。
磁盘
| 项目 | 占用 |
|---|---|
程序本体(run.py + web/ 界面与模型 + 脚本 + 文档) |
约 11 MB |
vendor/(Python 依赖,可删改走 pip) |
约 24 MB |
.webview2/(运行期浏览器缓存,可清) |
200–400 MB(实测 372 MB) |
pet.log |
每天几 KB,超过 512KB 自动只留最近 300 行 |
想省空间:双击
清理缓存-释放空间.cmd;
想省内存:不用的时候停止桌宠.cmd(或右键 → 退出桌宠)。
启动耗时
日志实测:服务启动 → 窗口创建 → WebView2 就绪 → 界面就绪 都在同一秒内(约 1 秒),
首帧渲染紧随其后;不需要预热。
兼容性与适配
Windows 版本
| 系统 | 支持情况 | 说明 |
|---|---|---|
| Windows 11(21H2 – 25H2) | ✅ 实测可用(作者用 25H2 / Build 26200) | 圆角走系统 DWM;毛玻璃走 SetWindowCompositionAttribute(需要系统「透明效果」开着) |
| Windows 10(1809 – 22H2) | ✅ 可用 | 没有 DWM 圆角接口时自动退回 Region 裁剪(日志会写「改用 Region 裁剪」);毛玻璃需要系统透明效果,否则只有半透明 |
| Windows 10 早期版本 / 8.1 / 7 | ❌ 不建议 | WebView2 与 per-monitor DPI v2 都缺;界面会异常 |
| Windows Server / LTSC | ⚠️ 未测试 | 需要自行装 WebView2 Runtime |
其它平台(macOS / Linux):不支持,整套实现依赖 Win32 分层窗口 + WebView2。
分辨率与 DPI 适配
窗口逻辑尺寸固定 400×620,实际像素 = 400×620 × DPI缩放 × 桌宠缩放,
内容按比例渲染(矢量 + Live2D,不糊)。常见组合:
| 屏幕 / DPI | 桌宠缩放 50% | 100% | 160%(上限) |
|---|---|---|---|
| 1920×1080 @100% | 200×310 | 400×620 | 640×992 |
| 2560×1440 @125% | 250×388 | 500×775 | 800×1240 |
| 2560×1600 @150% | 300×465 | 600×930 | 960×1488 |
| 3840×2160 @200% | 400×620 | 800×1240 | 1280×1984 |
- 放大上限自动算:默认给到 160%,但如果屏幕不够高会往下收
(允许窗口比屏幕高出 20%,因为窗口上方那块是空的、留给进度卡片,角色贴着底边画)。
实测:2560×1600 / 2560×1440 / 1920×1080 都能到 160%;1366×768 约 147%;1280×720 约 137%。 - 缩小下限:30%(再小基本看不清;2026-10-11 从 12% 抬上来的)。
- DPI 在启动时读取一次:把桌宠拖到另一块不同缩放比例的显示器上,或者中途改了系统缩放,
大小不会自动重算 —— 重启一次桌宠即可(已知限制)。 - 多显示器:可以放在任意显示器上;会跟着当前显示器的工作区摆放(避开任务栏);
缩放以窗口中心为锚点,不会“飞走”。 - 远程桌面 / 虚拟机:能跑,但透明窗口 + GPU 合成在部分虚拟显卡上会退化成半透明或残留黑边
(见常见问题里的重画处理)。
其它适配细节
- 高刷屏:帧率上限可以按屏幕来配(60 / 90 / 120 / 144 / 165 / 240 或不限制),
默认 60 帧;帧率越高 CPU 越高(60 帧时空闲仍 <3% 单核),觉得费电就往低调。 - 多虚拟桌面:跟随切换(用系统的虚拟桌面 COM 接口),不会留在看不见的桌面上。
- 单实例:重复启动不会有第二只(靠命名互斥量拦住);想换新代码要
重启桌宠.cmd。 - 虚拟桌面 / 锁屏 / 休眠:休眠唤醒后如果发现位置或大小不对,重启一次即可。
接入其它 Agent
桌宠不只会跟着 Codex:**设置 → 行为 →「接入的 Agent」**里直接切换,
进度卡片(任务名 / 已用时 / 工具数 / 上下文用量)和 9 个状态表情就跟着那个 agent 走。
懒得开设置窗口时,右键点角色 → 「切换卡片 Agent」,弹出和设置页同款的选择面板:
点一下要用的那个(格子变色选中),再按底部「确认」才生效;点面板外面或按 Esc = 取消。
现在一共接了 12 个(设置里分两列排:左列是最早那批 CLI,右列是桌面端那批):
| 下拉框里的名字 | 读的数据 | 说明 |
|---|---|---|
| Codex | ~/.codex/ |
桌面版(ChatGPT)和 codex CLI 共用同一份记录,所以名字后面不写 CLI |
| Claude Code CLI | ~/.claude/projects/**/*.jsonl |
只接了 Claude Code,Claude 桌面版是另一套数据 |
| Gemini CLI | ~/.gemini/tmp/*/chats/session-*.jsonl |
Gemini CLI 的会话录像 |
| OpenClaw CLI | ~/.openclaw/agents/*/sessions/*.jsonl |
记录还没生成时退化成“数据新旧 + 进程在不在”的忙闲判断 |
| Hermes CLI | %LOCALAPPDATA%\hermes\state.db |
Hermes 的会话库(sessions / messages 表) |
| OpenCode | %LOCALAPPDATA%\opencode\opencode.db |
桌面版和 CLI 共用同一份会话库 |
| DeepSeek Harness | ~/.dsh/storages/session_projcache/sessions/*.json |
桌面版和 CLI 共用 ~/.dsh;另看 sessions/**/session.v4.jsonl.zstd 的动静 |
| WorkBuddy | ~/.workbuddy/projects/**/*.jsonl |
另用 workbuddy.db 的数据新旧做忙闲兜底 |
| Xiaomi MiMo | ~/.local/share/mimocode/mimocode.db |
桌面版 = mimocode 引擎,和 mimo CLI 共用一份会话库 |
| ZCode | ~/.zcode/cli/db/db.sqlite |
桌面版和 CLI 落在同一个会话库 |
| Kimi Code | ~/.kimi-code/sessions/**/state.json(+ agents/main/wire.jsonl) |
桌面版和 CLI 共用 ~/.kimi-code |
| Qwen Code CLI | ~/.qwen/projects/**/chats/*.jsonl |
只有 CLI(Gemini CLI 同族);另读 *.runtime.json 判断回合在不在跑 |
名字后面带 CLI 的 = 桌宠只读了这个命令行工具的本地记录;
不带 CLI 的(桌面版和 CLI 共用一份记录)不用特别标注。
下拉框下面只有 CLI 类的 agent 会显示“有没有读到记录”的提示,共用记录的不提示。
读不到记录怎么办:状态桥
OpenClaw、Hermes 这类记录格式比较深的 agent,桌宠至少能显示“忙闲”;
想显示任务名 / 工具数,用状态桥最简单 —— 在 agent 的 hook / 插件 / 计划任务里调一行:
python status-bridge.py --agent openclaw --state working --title "修复登录 bug" --activity "运行测试"
python status-bridge.py --agent openclaw --state done --say "改好了"
它写进 ~/.codexpet/status/<agent>.json;桌宠每秒读一次,取 3 分钟内更新过的那份
覆盖在本地记录解析出来的状态上(任务名、工具数、用量都能补)。
字段都可以省略,state 取值:idle / thinking / working / waiting / review / syncing / blocked / error / done / interrupted。
自检
python agent_state.py --list # 有哪些 agent、各自能不能读到记录
python agent_state.py claude # 打印桌宠此刻看到的 claude 状态
python run.py --state-only --agent gemini
以后再加新 Agent:agent_state.py 里加一条注册表 + 一个适配器即可(现在这 12 个就是这么接进来的)。
对卡顿比较敏感的话:设一个用户环境变量
CODEXPET_NO_PROC_SCAN=1,桌宠就完全不起子进程
做进程检测(Gemini / OpenClaw 这类 npm 装的 CLI 就只能靠会话记录判断忙闲;
Codex / Claude / Hermes 是原生 exe,不受影响)。想恢复删掉这个变量即可。
常见问题
选了 Claude Code CLI / Gemini CLI,卡片一直显示空闲?
先确认那个 agent 确实在跑、并且在用它的命令行版本聊天(桌宠读的是 CLI 的会话记录)。
再 python agent_state.py --list 看它的“能不能读到记录”;没有记录就用一次,或者走状态桥
(见上面「接入其它 Agent」)。设置里下拉框下面也有提示,读到了会显示“最近更新 X 分钟前”。
双击启动没反应?
先看是不是已经有桌宠在跑(任务栏没有它,看任务管理器里的 pythonw.exe);
再双击 诊断.cmd,它会自检并打印 pet.log 的最后部分,里面通常直接写着原因。
滚轮缩放后偶尔残留一块黑边?
这是 Win11 对“挖空背景的透明分层窗口”改尺寸时的老毛病(切一下别的窗口也会自己掉)。
程序每次改完尺寸会自动连着重画 9 次(约 1.2 秒),把概率压得很低;
万一还留着:右键桌宠 → 重画窗口。
提示 WebView2 初始化失败?
装一下 WebView2 Runtime;
如果已经装了,双击 清理缓存-释放空间.cmd 清掉损坏的缓存再启动。
点「设置…」没反应 / 设置窗口打不开?
设置窗口会置顶、并在任务栏留一个图标,找不到时点任务栏那个;
它跑在独立线程上,日志里会写 打开设置窗口… / 设置窗口 WebView2 就绪…。
右键桌宠,弹出了「还原 / 移动 / 大小 / 关闭」那个系统菜单?
那是光标底下那个窗口自己的系统菜单 —— 说明这次右键落在角色的透明空隙上,点穿过去了。
桌宠现在按画布像素判断“点在不在角色身上”(透明像素 = 洋红键色 = 本来就该穿过去),
落空时不会再顺手弹出桌宠自己的菜单,“两个菜单一起冒出来”就没有了。
关键的一手在底层鼠标钩子里:只要这一下右键点在角色像素上,就在系统分发之前把它吃掉
(钩子返回 1,事件不再往下传)。桌面/别的程序根本收不到这次右键,自然不会弹它们自己的菜单;
吃掉之后按键状态也跟着“消失”了,所以这次右键从按下到抬起都在钩子里自己处理,菜单由 33ms 的定时器弹出。
点在透明处时不动它,照旧穿过去。
(实测这台机器上桌宠窗口对鼠标是全穿透的:WindowFromPoint 把角色像素判给了 Progman/桌面,
所以不主动吃掉的话,桌面菜单必然弹出,而且画在桌宠菜单上面。)
想确认这条链路在工作,可以设环境变量 CODEXPET_TRACE_HIT=1,再看 pet.log 里的「像素命中」记录。
右键菜单弹出来了,我不想选,怎么取消?
直接左键点桌面上任意别处即可:菜单当场消失,而且这一下点击照常生效
(不会像有些程序那样“第一次点只用于关菜单、第二次才点到桌面”)。
点菜单里的条目仍然是正常选择;右键点别处也会关掉它。
拖桌宠的时候怎么不把下面窗口的文字选中了?
点在角色身上的那一下左键,在系统分发之前就被桌宠吃掉了 —— 下面那个窗口既收不到按下、
也收不到抬起,不会框选文字、也不会误点到它上面的按钮;按住拖动就是拖桌宠。
点在角色旁边的透明处不吃,照旧穿透;快速“按下—松开”也不会漏(靠钩子里的按下 / 抬起脉冲队列)。
光标在任务栏 / 开始菜单上时,点击和滚轮会作用到桌宠吗?
不会。光标落在任务栏、二级任务栏、开始菜单、搜索、任务栏预览、托盘弹出等明确的系统 Shell 覆盖层上时,
左键拖动、左右键点击、滚轮缩放全部让给系统本身,桌宠一概不响应;只认这几类系统覆盖层窗口,
所以在桌面、编辑器等普通窗口上的互动不受影响,不会误伤。
「重新载入形象」和「刷新卡片信息」有什么区别?
「重新载入形象」是重新加载整个页面(模型、表情都在这一份里)—— 它不会再让进度卡片消失,
重新载入后卡片保持原来的显示状态。
「刷新卡片信息」只重读一次状态数据并立刻推给卡片(不等后台那一秒一次的自检,也不做“内容没变就不发”的去重);
卡片当时是收起的,它会顺手打开,不然点了没反应容易以为坏了。
卡片底部那行小字是什么?
是用量显示,在「设置 → 行为 → 卡片底部显示用量」里切换:
「今日新增」=今天(本地日期)所有已接入 agent 的 token 消耗合计;
「本会话累积」=当前这一次会话从头到现在的消耗;也可以选「不显示」。
数据全部来自本机记录(Codex 的会话文件),不联网、不碰密钥。
卡片状态和实际对不上?
状态翻译带一层兜底:工具结果延迟或丢失时,只要后面有思考、回复等新进展就不会一直卡“执行中”;
回合还在进行、长时间安静会显示“思考中”;Agent 明确提问、等确认时优先“等待你”;
“完成了”会稳定显示 90 秒再转“等待你”。想立刻重算一次:右键 →「刷新卡片信息」;
想看数据来源:「设置 → 排查」里打开日志。
拖动很卡?
拖动是 15ms 一个的 UI 定时器直接搬窗口,正常跟手;如果卡,通常是显卡驱动让分层窗口合成变慢,
可以试试把「卡片毛玻璃」关掉,或在设置里关掉「鼠标滚轮缩放桌宠」。
怎么让它别出现在屏幕上?
右键 → 更多功能里可以「隐藏到系统托盘」(可配到某个图标上),或者直接 停止桌宠.cmd。
隐私与安全
这个程序不联网、不上传任何东西(只有 127.0.0.1 上一个随机端口的本地网页服务,
用来把界面喂给 WebView2;不监听局域网)。它读的东西只有两类:
- 你当前选中的 agent 写在本机的会话记录(全部只读打开,SQLite 用
mode=ro,绝不写入;
每个 agent 具体读什么见接入其它 Agent)。以 Codex 为例:~/.codex/thread_history_1.sqlite—— 每个回合的状态、步骤类型与时间~/.codex/state_5.sqlite—— 任务标题、工作目录、token 用量~/.codex/sessions/**/*.jsonl—— 事件流,用来判断某个工具是否还在跑
- 自己的设置与位置:
pet_settings.json、pet_position.json(都在本目录里)。
设置窗口自己调过的大小/位置也会记住(settings_window.json),关掉再开就是你摆好的样子。
隐私相关的几个细节:
- 状态翻译时只取任务名、工具名、类型、时间等字段;命令行里的
key / token / secret / password / authorization / cookie之类字段会被跳过,不写进卡片,也不写日志。 - 日志默认不记录鼠标事件(要在设置里勾「记录鼠标事件到日志」才写),
平时只有启动信息、设置变更、每分钟一行帧率、以及报错;超过 512KB 自动截断。 - 卡片上显示的“上下文用量”是 Codex 自己记录的 token 百分比数字,不是内容。
- 想确认没有联网行为:看
run.py里的start_server()(只绑127.0.0.1);
也可以用防火墙/抓包工具盯一下。
换成你自己的 Live2D 模型
模型放在 web/model/,入口是 web/model/settings.json(就是 Live2D 的 *.model3.json 格式,
只是换了个名字)。最小可用长这样:
{
"Version": 3,
"FileReferences": {
"Moc": "你的模型.moc3",
"Textures": ["textures/texture_00.png"],
"Physics": "你的模型.physics3.json",
"DisplayInfo": "你的模型.cdi3.json",
"Motions": {
"Idle": [{ "File": "motions/idle.motion3.json", "FadeInTime": 0.6, "FadeOutTime": 0.6 }]
},
"Expressions": [
{ "Name": "开心兴奋", "File": "expressions/开心.exp3.json" }
]
}
}
Motions里的组名建议保留Idle(闲置循环)和Show(表演);设置窗口会把它们列出来。Expressions里的Name就是设置里「状态对应的表情 / 表情白名单」显示的名字。- 只支持 Cubism 4(
.moc3)模型;Cubism 2 不支持。 - 换了模型后,桌宠的三处尺寸常量(
run.py顶部WINDOW_W / WINDOW_H / CHAR_BASE_H)
和“底部三个图标”的命中比例(TOOL_MARK_X / TOOL_MARK_Y)需要按你的构图微调。
目录结构
CodexPet/
├─ 启动桌宠.cmd / 启动桌宠.vbs 启动(cmd 能看到报错,vbs 无黑框)
├─ 停止桌宠.cmd / 重启桌宠.cmd 关闭 / 重启
├─ 诊断.cmd 自检 + 打印日志 + 导出 selftest.png
├─ 开机自启-*.cmd
├─ 清理缓存-释放空间.cmd 删除 .webview2 缓存
├─ 创建桌面快捷方式.cmd 在桌面创建「Agent 桌宠」快捷方式(可删可重建)
├─ pet-launcher.ps1 所有启动脚本的落点:找 Python、拉起 run.py
├─ run.py 宿主:透明窗口、点击穿透、鼠标钩子、拖动、缩放、卡片、设置窗口、日志
├─ agent_state.py 多 Agent 状态源:选谁就读谁的本地记录(含忙闲兜底与状态桥)
├─ status-bridge.py 状态桥写入器:一行命令把任意 agent 的状态喂给桌宠
├─ usage_stats.py 卡片底部用量统计(今日新增 / 本会话累积)
├─ codex_state.py 只读 Codex 本地记录 → 状态(agent_state 里的 codex 适配器)
├─ settings_store.py 设置读写、老配置自动升级
├─ requirements.txt / LICENSE / THIRD-PARTY.md
├─ web/
│ ├─ index.html / pet.js / pet.css 桌宠本体(Live2D 渲染、状态表情、进度卡片)
│ ├─ settings.html / settings.js / .css 设置窗口
│ ├─ card.html / card.js / card.css 独立卡片窗口(默认不用)
│ ├─ icon.ico / icon-transparent.ico 窗口 / 桌面快捷方式图标
│ ├─ lib/ pixi + pixi-live2d-display + Cubism Core
│ ├─ model/ 模型(moc3 / 贴图 / 动作 / 表情)+ settings.json、README.md(模型授权说明)
│ │ (另外几个 `*.vtube.json`、`items_pinned_to_model.json`
│ │ 等是 VTube Studio 的工程文件,程序不读,可自行决定留删)
├─ vendor/ Python 依赖(pythonnet、WebView2 .NET 组件等)
└─ docs/
├─ 实现笔记.md 工程实现笔记(怎么演的、踩过的坑、调试方法)
├─ 文件清单.md 哪些文件必须留、哪些能删、哪些不会进仓库
└─ images/ README 用图
.gitignore 已经排除了日志、pet_settings.json、.webview2/ 缓存等运行期文件,
直接 git init && git add . 不会把你的本机数据带上去。
更新日志
2.0(2026-10-11)
输入体验
- 光标位于任务栏 / 开始菜单 / 任务栏预览 / 托盘弹出等系统 Shell 覆盖层时,桌宠不再响应:
左键拖动、左右键点击、滚轮缩放都原样交给系统本身;只识别明确的 Shell 覆盖层窗口,
桌面、编辑器等普通窗口上的正常互动不受影响。 - 左键点在角色身上时,在系统分发前吃掉 WM_LBUTTONDOWN 与配对的抬起事件 ——
不会再选中下面窗口的文字、也不会误点下面的图标;拖动结束后立刻再点,命中的是新位置。 - 新增左键按下 / 抬起脉冲队列:两次 33ms 轮询之间的快速单击、双击不会漏判;
快速“按下—移动—松开”稳定判定为拖动。 - 设置窗口始终置于桌宠上方,并注册为独立辅助窗口:光标在设置窗口上时,滚轮只滚动设置项、
左右键只操作设置窗口,不会缩放桌宠,也不会误弹桌宠菜单。
状态显示
- 工具结果延迟或丢失时,只要后续出现思考、回复等新进展,不再永久卡在“执行中”。
- 回合仍在进行时,长时间安静显示“思考中”,不再误判成“等待你”。
- “完成了”稳定显示 90 秒,之后转为“等待你”,长时间无操作才转“空闲”。
- Agent 明确提问、等待确认时优先显示“等待你”,不会被残留的工具状态覆盖。
- 统一识别 running / in_progress / completed / needs_input / cancelled / failed 等状态写法,
Codex、DeepSeek Harness、ZCode、WorkBuddy、Kimi Code 等 12 个适配器的状态优先级一起优化过。
其它
- 项目更名:「Codex 桌宠」→「Agent 桌宠」(2.0 起不止跟着 Codex,名字与界面统一)。
- 接入 12 个 Agent,详见接入其它 Agent;卡片底部新增用量小字
(今日新增 / 本会话累积);状态桥status-bridge.py支持把任意 Agent 的状态喂给桌宠。 - 桌面快捷方式「Agent 桌宠」首次启动自动创建(设置 → 排查里可删、可重建),新增
创建桌面快捷方式.cmd。 - 缩放后的黑边补救升级为 9 段重画节奏(约 1.15 秒),残留概率进一步降低;缩小下限从 12% 提高到 30%。
- 仓库清理:移除不再使用的跟随启动 / 道具恢复 / 黑边切换脚本和
web/model_backup_props/备份模型;
运行期文件(日志、缓存、位置等)都写在.gitignore里,不会进仓库。
第三方与许可
本仓库自己的代码:MIT(见
LICENSE)。Live2D Cubism Core (
web/lib/live2dcubismcore.min.js):Live2D 公司专有授权,随程序分发可以,但商用/再分发请读官方条款。pixi.js / pixi-live2d-display:MIT。
pythonnet / pywebview / Pillow / bottle / cffi 等 (
vendor/):各自的 MIT / BSD 许可,原文都在vendor/*.dist-info/licenses/。web/model/里的 Live2D 模型:授权独立于代码。如果你 Fork 本仓库:请把
LICENSE里的版权换成你的名字,并务必保留上述关于 Live2D 模型和第三方库的来源声明。
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi