SkyDome（天穹桌宠 · 开源版）

一只住在桌面右下角的天穹少女——随 Agent 工作状态切换 9 种动作， 任务完成时自动播放提示音。支持 DSH Web 插件与 Flutter 原生悬浮窗两种形态。

---

✨ 功能特性

• 9 种状态动作：待机 / 工作 / 思考 / 等待 / 出错 / 挥手 / 跳跃 / 左右跑 / 点击挥手 （精灵表 8 列 × 9 行、单格 192×208，契约驱动）
• 双运行形态：
  • TianQiong-Pet/ —— DSH 动态插件（注入 Web 界面 shell.overlay，Host 端自动检测状态）
  • dsh_pet_flutter/ —— Flutter 原生透明置顶窗口（Windows / Android，可跨应用显示）
• 完成音自动触发：任务完成（running → idle）播放提示音，去重防双响、可开关、可调音量
• 自由拖动：全视口/全虚拟桌面拖动（多显示器负坐标支持、DPI 统一、边缘 clamp 无回弹）
• 可观测：tianqiong_pet_debug 工具、window.__tianqiongPetDebug、原生拖动日志
• Codex 桥接：AGENTS.md + pet-status.ps1 让对话任务完成时桌宠自动庆祝发声

---

🚀 快速开始

Flutter 原生桌宠（Windows）

cd dsh_pet_flutter
flutter pub get
flutter run -d windows      # 或 flutter build windows

前置：Flutter SDK 3.x + Visual Studio（C++ 桌面开发）。

DSH Web 插件

用 TianQiong-Pet/skydome.package.json（一键安装载荷）在 DSH 会话中：

cordis_define（粘贴载荷）→ cordis_run → 在 UI 批准

---

📖 文档索引

文档	内容
桌宠教程.md	9 个动作触发条件、完成音规则、会话触发声音示例
TianQiong-Pet/README.md	DSH 插件安装与状态机说明
dsh_pet_flutter/README.md	Flutter 版配置与打包
GIT_GUIDE.md	Git 基础操作快速参考

---

⚙️ Agent 状态协议（agent_status.txt）

状态文件支持纯文本或 JSON，内容变化时桌宠切换动作：

working

{"status": "complete"}

状态词	桌宠动作
idle	呼吸待机
working / running / busy	专注干活
review / thinking / processing	思考循环
waiting / approval / blocked	期待等待
complete / success / done	挥手+跳跃庆祝 ＋ 完成音
error / failed / failure	难过低落

推荐写入方式（自动处理编码）：

pwsh -NoProfile -File "D:\codex code\DesktPetPlugin\pet-status.ps1" complete

---

🔊 完成音触发规则

同时满足以下条件才播放一次：

1. Agent 曾进入 running，随后转换为 idle（完成边沿）；
2. 当前没有其他 running 的 Agent；
3. 不是等待审批/回复、也不是等待工具输入；
4. 本次任务未以错误结束；
5. 同一任务只播放一次（庆祝期间重复完成仅延长、不重复发声）。

DSH 插件由 Host 端 ffplay 播放 voice.mp3；Flutter 版由 audioplayers 播放 config.json 指定的 MP3（enableAudioFeedback / volume 可调）。

---

🗂️ 目录结构

DesktPetPlugin/
├── TianQiong-Pet/          # DSH 动态插件（Host 状态机 + Client 渲染）
│   ├── src/host.js         # 状态机、完成音触发规则、pet-state RPC
│   ├── src/client.js       # shell.overlay 渲染、拖动、9 种动画
│   ├── skydome.package.json# 一键安装载荷（构建产物）
│   └── demo/index.html     # 独立动画演示页
├── dsh_pet_flutter/        # Flutter 原生桌宠（Windows / Android）
│   └── lib/                # 状态机、动画、拖动、音频、配置、Win 屏幕辅助
├── AGENTS.md               # Codex 任务完成 → 桌宠发声桥接约定
├── pet-status.ps1          # 状态写入脚本（UTF-8 无 BOM）
├── 桌宠教程.md             # 使用教程
└── GIT_GUIDE.md            # Git 快速参考

---

📄 License

代码以 MIT License 开源； 精灵表素材版权归原参考素材方，仅供个人学习交流使用。