图图、宝珠、铁蛋、小金宝与小点点桌宠

               

让最爱的宠物，在忙碌工作时也陪在身边。

我为什么做这个项目

做这个项目的初衷很简单：希望忙碌的工作里，也有我最爱的宠物们陪伴。

图图和宝珠不只是屏幕上的装饰。它们会等待、思考、敲键盘、散步、追球、咬尾巴，也会被抱起、落下后重新站稳。把这些小动作做成桌面上的持续陪伴，也是在把它们的样子、神态、习惯和性格记录下来——留下一份可以一直打开的数字记忆。

项目简介

TutuDesktopPet 是一个独立于 Codex 原生宠物叠层的 Windows WPF 桌宠。它以透明窗口显示逐帧动画，支持多会话分配、像素级点击穿透、拖拽与重力、桌面/窗口表面着陆、状态气泡，以及图图、宝珠、铁蛋、小金宝与小点点角色切换。

公开仓库只包含程序运行所需的最终角色帧。宠物原始参考照片、身份参考板、动作源板、生成提示、候选图和视觉 QA 均保留在本地，并通过忽略规则排除。请尊重角色形象的个人使用边界，未经许可不要将其用于训练、商用或再发布。

快速开始

运行环境：Windows 10/11、PowerShell、.NET 8 SDK。

# 仅在项目未附带本地 SDK 时执行
powershell -NoProfile -ExecutionPolicy Bypass -File tools\dotnet-install.ps1 -Channel 8.0 -InstallDir .dotnet

# 编译、发布并安装
powershell -NoProfile -ExecutionPolicy Bypass -File tools\Publish-TutuDesktopPet.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tools\Install-TutuDesktopPet.ps1 -SkipPublish

运行完整回归测试：

powershell -NoProfile -ExecutionPolicy Bypass -File tools\Test-TutuDesktopPet.ps1 -Configuration Release

发布脚本会先写入临时目录并验证角色包，再原子替换正式产物；产物包含 SHA256SUMS 和 release-manifest.json。如本机已有代码签名证书，可向发布脚本传入 -SigningCertificateThumbprint。

安装后可通过 tutu Skill 控制当前会话的桌宠，例如 $tutu on、$tutu off、$tutu status、$tutu role baozhu 和 $tutu role tiedan。

技术说明

TutuDesktopPet is a compiled .NET WPF desktop pet. It is separate from the Codex native pet overlay and therefore owns its window, alpha hit testing, dragging, animation, and multi-session lifecycle.

Current engine capabilities:

• one pet per live root Codex terminal session, with a bounded concurrent current-user-only control pipe;
• ordered role assignment: first terminal Tutu, second Baozhu, third Tiedan, fourth Xiaojinbao, fifth Xiaodiandian, and overflow terminals use Tutu without reshuffling surviving sessions;
• a 60-Hz manifest clock with role-specific animation states; Tutu's walk reuses eight sharp gait bitmaps on a 64-tick procedural motion track, while Baozhu uses a lightweight 12-to-16-frame-per-action pack;
• per-pixel alpha hit testing (transparent canvas clicks through);
• visible-body pickup with a dedicated side-held pose, drag, release, gravity, window-top collision, and landing;
• multi-monitor roaming across desktop, taskbar, and visible window surfaces;
• status bubbles shown after a deliberate 900 ms opaque-body hover, without popping open when progress changes, placed outside the pet in right, left, above, then below priority;
• named-pipe control for $tutu on, $tutu off, global control, status, size, and safe-frame role assignment;
• stable anatomical anchors and a fixed 260 logical-pixel default body height;
• fully opaque photographic frame swaps to avoid translucent double-image flicker, backed by a content-addressed, byte-bounded decoded-frame cache;
• one shared rendering clock for animation, pointer-hover sampling, and active/idle physics dispatch instead of three high-rate timers per pet;
• privacy mode, reduced-motion mode, and user-configurable always-on-top;
• a content-deduplicated runtime character pack that preserves all animation timelines while avoiding thousands of duplicate PNG copies;
• live global sizing from 40% to 160%, with a compact 50% first-release default;
• a multi-resolution cartoon Tutu cat-head icon for the executable and system tray.

The Baozhu role was authored from a private local reference pack that is not included in this public repository. It now ships 18 states as a 284-entry lightweight action pack: seated breathing, ear/tail movement, standing turns, thinking, laptop work, attentive waiting, happy completion, interruption, play-bow stretching, tail chasing, bug inspection, sitting, natural ball-free walking, pouncing, side-held dragging, falling, and landing, plus the restored red-ball chase. Tail chasing uses sixteen distinct 22.5-degree body angles to complete a full turn instead of a head-only reversal. Every non-idle state has its own folder and at least four identity-locked key poses; none fall back to a generic seated frame or to Tutu assets. Baozhu's active working and thinking signals stay on the laptop-typing loop; ordinary walking and ball chasing share roaming duty. Baozhu moves faster and in shorter roaming legs than Tutu, while staying about 90% of Tutu's visual size. Her walk uses sixteen distinct canine phases in a four-beat lateral sequence: each hind paw advances before the forepaw on the same side, with visible toe-off, rear-abdomen, abdomen-centre, front-abdomen, and landing positions. Hind/fore step groups use mildly different 17/16/17/16-tick cadences while the spine and paw baseline remain horizontal.

The first Xiaodiandian role pack was authored from a private local reference pack that is not included in this public repository. It preserves her large blue eyes and compact mountain-shaped seal-brown nose-and-cheek mask, using the lighter, smaller seasonal face pattern selected by the owner. The pack contains light breathing, curious sitting, an eight-phase brisk natural walk, pickup, falling, soft landing, and a four-keyframe social greeting that moves from an alert raised paw to a close playful head tilt. Her idle behavior keeps interaction frequency moderate while the authored actions remain lively.

The first-release Tutu role pack contains breathing, ear/tail movement, standing and turning, thinking, working, waiting, completion, interruption, stretching, tail chasing, bug inspection, sitting, walking, pouncing, side pickup, falling, and landing. Its source art and active animation timelines share one 576-by-384 production canvas and one body-size anchor system. Stretching and seated head turns use dedicated high-detail pose paths rather than the generic action sequence. Multi-pose actions display only exact prebuilt rasters at runtime: the engine never cross-fades, optically warps, morphs, or softens the cat during playback. This preserves whiskers and facial features while preventing delayed double-image trails. Walking now uses an eight-pose, 1.07-second feline gait cycle with explicit near/far hind-leg alternation, continuous ground support, and a level pelvis, so the rear paws no longer read as a parallel two-foot hop at desktop size. The eight PNGs are reused directly; a bounded 60-Hz ground-pivot sway track adds sub-pixel continuity without generating, morphing, or optically warping new anatomy. No video model is shipped or required at runtime. The stretch is rebuilt around feline joint and weight-transfer mechanics: minute breathing, forepaw placement and toe spread, a low chest with a modest rump lift, alternating paw load, and joint-led recovery. Locomotion animations are the only idle states allowed to translate the pet window. During quiet periods, Tutu can wander for two or three short legs, pause to look around, and choose an inward direction near screen or surface edges. Head turns accelerate away from center, decelerate into the final authored angle, then hold a sharp side-looking pose for several seconds; inspection and paw pounces retain uneven observe-act-hold-recover rhythms.

Earlier RIFE and LTX-Video walk experiments may remain locally under the ignored assets/candidates/ and .local/ directories. They are not included in the public repository and are never invoked by build, install, or normal pet playback. Legacy dense walk PNGs remain for comparison but are excluded from the published application.

Control

Install the Skill at %USERPROFILE%\.codex\skills\tutu, then use:

• $tutu on / $tutu off for the current Codex session;
• $tutu status to inspect detected sessions and visible pets;
• $tutu size 50 to set every pet to 50% (40 through 160 are accepted);
• $tutu all on / $tutu all off only when every session should change;
• $tutu role tutu, $tutu role baozhu, $tutu role tiedan, $tutu role xiaojinbao, or $tutu role xiaodiandian to assign a role to the current session at the next safe animation frame.

The installed app lives at %LOCALAPPDATA%\Programs\TutuDesktopPet\TutuDesktopPet.exe and its Startup shortcut launches the supervisor at Windows sign-in.

Right-click the Tutu tray icon to summon or recall all pets, use a top-level 精准召回 entry to pull one exact session pet to the mouse's current screen, control each terminal independently, replace that terminal's role from an avatar menu, toggle status bubbles, privacy mode, reduced motion and always-on-top, and change the global pet size. New terminal pets also start on the screen where the user is working. Recalling the last pet keeps the lightweight tray supervisor running; use 退出桌宠程序 to exit it.