飞行雪绒事件系统使用说明（LTS1.0.6pre4）

一、核心入口#

- 实现：`lib/core/event/center.py`
- 单例访问：`get_event_center()`
- 事件对象：`Event`
- 事件枚举：`EventType`

二、处理模型#

- `publish(Event)` 将事件放入队列
- 主线程发布时，会尽快在主线程 drain 队列
- 非主线程发布时，会通过 Qt signal 切回主线程处理
- 回调可以调用 `event.mark_handled()` 中断同类型事件后续传播

三、基础用法#

```python
from lib.core.event.center import Event, EventType, get_event_center

ec = get_event_center()

def on_info(event: Event):
    print(event.data)

ec.subscribe(EventType.INFORMATION, on_info)
ec.publish(Event(EventType.INFORMATION, {"text": "hello"}))
ec.unsubscribe(EventType.INFORMATION, on_info)
```

四、输入链路#

- 鼠标：`MOUSE_PRESS` / `MOUSE_MOVE` / `MOUSE_ENTER` / `MOUSE_LEAVE` / `MOUSE_CLICK` / `MOUSE_DOUBLE_CLICK`
- 键盘：`KEY_PRESS` / `KEY_RELEASE`
- 命令框：
  - `/xxx` → `INPUT_COMMAND`
  - `#xxx` → `INPUT_HASH`
  - 普通文本 → `INPUT_CHAT`

五、应用生命周期#

- `APP_PRE_START`
- `APP_INIT_READY`
- `APP_START`
- `APP_MAIN`
- `APP_EXIT`
- `APP_QUIT`

其中：
- `APP_PRE_START` 适合预热、静态准备和后台服务启动检查
- `APP_QUIT` 是统一退出请求入口，适合阻止直接粗暴退出；payload 可传 `restart: true`，由主生命周期在清理完成并释放单实例锁后重启

六、当前高频事件协议#

INFORMATION
- 用途：信息气泡
- 常见字段：
  - `text`
  - `min`
  - `max`
  - `particle`

PARTICLE_REQUEST
- 用途：申请粒子
- 字段：
  - `particle_id`
  - `area_type`
  - `area_data`

SOUND_REQUEST
- 用途：请求播放音频文件
- 字段：
  - `audio_class`
  - `file_path`
  - `volume`
  - `interruptible`

VOICE_REQUEST
- 用途：语音播放抽象层入口
- 当前文本类请求会继续分流到 `AI_VOICE_REQUEST`

AI_VOICE_REQUEST
- 用途：AI 文本转语音申请
- 字段：`text`（保留中英文原文）、可选 `text_lang`（`zh`、`en` 或 `auto`）、`interruptible`
- 当前由 `lib/script/gsvmove/service.py` 消费
- 当 GSV 模块在控制面板中关闭时，这类事件会被直接忽略

MIC_STT_*
- `MIC_STT_START`
- `MIC_STT_STOP`
- `MIC_STT_PARTIAL`
- `MIC_STT_FINAL`
- `MIC_STT_STATE_CHANGE`

MUSIC_*
- 播放控制、登录状态、进度同步、队列操作都在 `MUSIC_*` 命名空间
- 统一由音乐服务和 UI 组件解耦协作

MANAGER_SPAWN_REQUEST
- 用途：请求对象管理器生成实体
- 常见字段：
  - `manager_id`
  - `count`
  - `spawn_type`

MANAGER_QUERY_REQUEST / MANAGER_QUERY_RESPONSE
- 用途：跨管理器查询状态、数量、保护范围等

TARGET_POSITION_QUERY / TARGET_POSITION_RESPONSE
- 用途：统一查询目标位置，减少状态机与具体管理器的直接耦合

PROTECTION_CHECK / PROTECTION_RESPONSE
- 用途：检测主宠保护半径或实体保护区

七、开发约束#

- 回调应尽量短小，避免阻塞 UI
- 所有订阅都必须在 `cleanup()` 中退订
- `mark_handled()` 只用于确实需要阻断传播的场景
- 公共事件字段一旦公开使用，尽量保持兼容，不要频繁改 key