Aion Chat 项目档案

项目定位

技术栈

模块化文件结构

路由

支持的模型

硅基流动（api.siliconflow.cn）

Gemini（generativelanguage.googleapis.com）

AiPro 中转站（vip.aipro.love）

哨兵/向量模型（支持独立 Gemini Free Key）

已实现功能

聊天核心

Debug 透明度面板

向量记忆库（RAG 重构）

语音合成 (TTS) — 服务端流式推送架构

摄像头智能监控（Sentinel/Core 双脑架构）

Core 主动查看监控（[CAM_CHECK]）

Core 主动查看设备动态（[查看动态:n]）

Sentinel/Core 工作流程

语音唤醒 + 半双工通话

语音唤醒工作流程

视频通话（[视频电话]）

AI 生图（[SELFIE:xxx] / [DRAW:xxx]）

AI 生图工作流程

视频通话工作流程

音乐点歌（[MUSIC:xxx]）

音乐点歌工作流程

日程 / 闹铃 / 定时监控系统

定时监控（[Monitor:...]）

密语时刻（BLE 玩具控制）

背景记忆浮现（替代旧版“近期记忆注入”）

高德地图定位系统

核心模块

手机上报流程（Android 端）

服务端研判逻辑（详细）

Core 按需 POI 搜索（[POI_SEARCH:xxx]）

设置与配置

高德地图定位工作流程

日程/闹铃工作流程

/

/

或 分割）→ 段落提取 → 图片提取（封面 + 正文图片）→ 存储到 data/books/{book_id}/ → 写入 book.db（books 表 + book_chapters 表） → 返回 book_id

【阅读 + 批注】 GET /api/books/{id}/chapters/{ch} → 返回章节内容（段落数组）+ 已有批注 + AI名/用户名 → 前端渲染段落 + 批注气泡 → 用户点击「AI 批注」→ POST /api/books/{id}/chapters/{ch}/annotate-all → 后端逐段处理： ├ 加载世界书人设 + 查询书名 ├ 获取前 3 章摘要（每章≤200字） ├ 获取最近 15 条聊天消息 ├ 构建批注 Prompt（人设+时间+书名+上下文+段落文本） ├ stream_ai() 流式生成 → 解析 JSON 批注 └ 存入 book_annotations 表 → SSE 推送前端 → 前端实时渲染批注气泡

【选文聊天】 选中文字 → 弹出工具栏「💬 问问AI」→ 点击 → 弹出提问窗 → 输入问题（可选）→ 提交 → 打开聊天面板 → 加载最近 6 条主聊天消息（GET /api/conversations/{conv_id}/messages?limit=6） → 显示上下文 + 分割线 + 用户消息 → POST /api/conversations/{conv_id}/send（SSE 流式） → AI 回复流式渲染为多气泡（按 \n\n 分段） → 支持继续在面板内追问（同一对话） → 所有消息保存在主聊天历史中

### 小剧场（独立角色扮演聊天）
194. **完全独立** — 小剧场使用独立的数据库表（`theater_conversations` + `theater_messages`），与主聊天完全隔离，所有对话记录**不计入记忆库**，记忆总结时不会涉及小剧场内容
195. **极简 Prompt** — 仅注入选中角色的人设 + 最近 N 条上下文，不注入系统能力（`[MUSIC]`/`[CAM_CHECK]`/`[ALARM]` 等）、不注入记忆/日程/位置/活动日志，干净纯粹的对话体验
196. **多角色管理** — 支持创建/编辑/删除多套角色人设，每个角色可配置独立的名称、人设内容（system prompt）、默认模型、默认温度、默认上下文条数。角色数据存储在 `data/theater_personas.json`
197. **对话管理** — 侧栏对话列表，支持新建/删除/重命名剧场，每个对话绑定一个角色，切换角色时自动更新对话设置
198. **SSE 流式回复** — 与主聊天一致的 SSE 流式输出，逐字显示，等待时显示「思考中/正在输入」循环动画 + 弹跳小圆点
199. **TTS 语音合成** — 完整保留服务端流式 TTS（复用 `tts.py` 的 `TTSStreamer`），支持音色选择和重播。TTS 事件通过 `tm_` 消息前缀与主聊天互相隔离，避免多页面同时播放
200. **茶色暗色主题** — 深棕色背景（`#1e1a16`）+ 茶色强调色（`#c8956c`），与主聊天的暖光风格形成差异化视觉区分
201. **多端同步** — WebSocket 广播 `theater_conv_created/updated/deleted`、`theater_msg_created/updated/deleted` 事件，多设备实时同步
202. **图片上传** — 支持多模态，可上传图片/视频作为附件发送
203. **重新生成** — AI 消息支持一键重新生成

### 奥罗斯幽林（Ghost Forest TRPG）
300. **独立 TRPG 模块** — 完整的桌游风角色扮演冒险游戏，AI 担任 DM（地下城主持人），玩家通过选项和 D20 骰子推进剧情。数据存储为纯 JSON 文件（`data/ghost_forest/`），不使用数据库，与主聊天系统完全隔离
301. **DM/玩家人设管理** — 支持创建/编辑/删除多套 DM 和玩家人设预设，存储在 `data/ghost_forest/_personas.json`，开始新冒险时选择人设组合
302. **AI 生成剧情大纲** — 玩家提供冒险点子，AI（SSE 流式）生成完整剧情大纲：标题、世界观、主线情节、NPC 列表、关键道具、剧情分支、氛围描写
303. **角色属性系统** — 五维属性（力量/敏捷/智力/魅力/运气），初始各 3 点 + 7 点自由分配。HP 100，最大回合 20（±5 弹性）。属性影响选项的 DC（难度等级）判定
304. **D20 骰子判定** — Three.js 3D 实时渲染 D20 骰子动画，物理模拟旋转和弹跳。投骰结果 + 属性修正 ≥ DC 即成功，影响后续剧情走向
305. **AI 叙事回合** — 每回合 AI 生成剧情叙述 + 3-4 个选项（含属性关联和 DC），支持 D 选项自定义行动。AI 回复以 SSE 流式输出，实时渲染 Markdown
306. **道具系统** — AI 可通过 `[ITEM:道具名:数量:描述]` 指令给予玩家道具，选项可设置 `item_cost` 消耗道具。道具栏实时显示在游戏界面底部
307. **AI 对话历史压缩** — 当 AI 历史超过 16 条消息时，使用 `gemini-3.1-flash-lite` 自动压缩旧对话为摘要，保留最近 6 条原文，减少 token 消耗。压缩前备份完整历史到 `ai_history_full`
308. **前情回顾** — 📜 按钮打开全屏回顾面板，显示所有已完成回合的剧情和结果叙述，方便回顾冒险历程。支持 🔊 按钮回放每回合的 TTS 音频（通过 HEAD 探测已缓存分片）
309. **大结局生成** — 冒险结束时，AI 生成 400-800 字的完整大结局叙事（纯文学风格，不含选项），以 SSE 流式呈现。结局存储在 `session.finale`，重新进入时直接展示
314. **TTS 语音合成** — 复用 `tts.py` 的 `TTSStreamer`，通过 SSE 流式推送 `tts_chunk`/`tts_done` 事件。叙述/选择结果/大结局三个 SSE 端点均支持 `tts_enabled`/`tts_voice` 查询参数，AI 生成叙述后自动按句切分合成语音，前端按序播放。TTS 音频缓存以 `gf_{sid}_r{round}_s{seq}.mp3` 命名，支持回放
315. **动态回合数** — 支持游戏中修改最大回合数（±5 弹性范围），AI 根据剩余回合数自动调整叙事节奏
316. **D 选项自定义行动** — 选项列表末尾固定显示「D. 你想做别的...」输入框，玩家可自由输入创意行动
310. **场外求助（剧场联动）** — 📞 按钮打开半屏聊天面板，连接到主聊天系统。聊天 AI 通过 `theater_session_id` 参数自动获取当前游戏状态（属性/HP/道具/最近剧情/当前选项），以 `[剧场属性：xxx ±n]` 和 `[剧场道具：xxx]` 指令直接修改游戏数据，实现跨系统联动
311. **移动端适配** — 游戏界面采用两段布局（固定状态区 + 统一滚动区），正文和选项合并滚动，手机上正文显示面积最大化。属性芯片紧凑排列（nowrap），触屏友好
312. **会话管理** — 支持多局游戏并行，列表显示标题/状态/创建时间，支持暂停/恢复/删除。状态机：draft → outlined → playing → paused/finished
313. **模型切换** — 游戏中可实时切换 AI 模型（下拉框），支持所有已配置的模型（Gemini/硅基流动/中转站）

### 奥罗斯幽林工作流程

【创建冒险】 选择 DM 人设 + 玩家人设 → 输入冒险点子 → POST /api/ghost-forest/sessions → AI 生成剧情大纲（SSE）→ POST .../generate-outline → 解析 JSON 大纲（标题/背景/NPC/道具/分支） → 分配属性点（5 维各 3 + 7 自由分配）→ POST .../start → 状态 playing

【游戏回合（循环）】 POST .../narrate → AI 生成当前回合叙述 + 选项（SSE 流式） → 前端解析 JSON：narration + options[{key, text, stat, dc}] → 玩家选择选项 → 需要骰子？→ Three.js D20 骰子动画 → POST .../choose {chosen, dice_roll, custom_input} → AI 根据判定结果生成后续叙述（SSE 流式） → 更新 HP/属性/道具/回合数 → 下一回合

【AI 历史压缩（自动触发）】 narrate/choose 完成后 → 检查 ai_history 长度 > 16 → gemini-3.1-flash-lite 压缩旧消息为摘要 → 备份 ai_history → ai_history_full → ai_history = [压缩摘要] + [最近 6 条原文]

【场外求助（剧场联动）】 点击 📞 → 打开聊天面板 → 发送消息到主聊天（携带 theater_session_id） → 后端注入游戏状态到聊天 AI prompt → AI 回复中含 [剧场属性：力量 +2] / [剧场道具：神秘钥匙] → 后端解析指令 → 修改游戏会话数据 → SSE theater_update 事件 → 前端接收 → 刷新游戏 UI

【大结局】 回合数到达上限 / HP 归零 / AI 判断冒险结束 → 点击 🏰 大结局 → POST .../finale（SSE 流式 + TTS） → AI 生成 400-800 字结局叙事 → 存储 session.finale → 状态 → finished

【TTS 语音合成（复用 TTSStreamer）】 narrate/choose/finale 端点接收 tts_enabled=true&tts_voice=xxx 查询参数 → AI 生成叙述文本 → 创建 TTSStreamer(msg_id, voice, sse_queue=queue) → TTSStreamer.feed(narration) → 按 100-200 字切分 → 异步合成 mp3 → 合成完成 → SSE 推送 tts_chunk {msg_id, seq, url} → 前端 enqueueTTSChunk() 按序播放 → 全部合成完 → SSE 推送 tts_done → 前端 finishTTSForMsg() 标记完成 → 音频缓存：data/tts_cache/gf_{sid}_r{round}_s{seq}.mp3 → 前情回顾可通过 🔊 按钮回放已缓存的音频（HEAD 探测分片存在性后依次播放）

### 设备活动日志系统（PC + 手机）
170. **双设备活动采集** — 自动记录 PC 前台窗口和手机前台 App 的使用情况，存储为 JSONL 日志，按日期分文件，保留最近 3 小时
171. **PC 前台窗口采集** — 后台守护线程每 60 秒通过 `win32gui.GetForegroundWindow()` 获取当前窗口标题 + `psutil.Process.name()` 获取进程名，**每分钟无条件记录**（窗口没变也写入，确保摘要时长计算准确），自动过滤 Program Manager（桌面）
172. **Android 前台 App 上报** — `AionPushService` 中独立线程每 60 秒通过 `UsageEvents` API（主）/ `UsageStatsManager`（备）获取当前前台应用包名，POST 到 `/api/activity/report`，**每次轮询都上报**（无去重，服务端摘要层负责合并）；同时注册 `BroadcastReceiver` 监听屏幕开关事件
173. **App 名称解析** — 服务端维护 `KNOWN_APPS` 映射表（80+ 常见应用），将包名/进程名转为中文显示名（如 `com.xingin.xhs` → `小红书`、`chrome.exe` → `Chrome`），自动过滤系统应用（桌面、SystemUI 等）
174. **JSONL 存储 + 自动清理** — 每条日志按日期写入 `data/activity_logs/{YYYY-MM-DD}.jsonl`，`cleanup_old_activity_logs()` **每 5 分钟最多执行一次**清理超过 3 小时的旧条目
175. **并发安全** — `threading.Lock` 保护 JSONL 文件读写，防止 PC 后台线程和手机 API 协程并发写入导致数据丢失
176. **10 分钟活动摘要** — `generate_activity_summary()` 将原始日志按 10 分钟窗口分组，**时长权重排序**（主要活动排前面），**carry-forward 状态追溯**（向前找每个设备最后状态填补窗口开头空白），空窗口标记为「没有活动」并自动合并连续空窗口
177. **前端日志查看器** — `/activity-logs` 页面支持「最近 3 小时」和「按日期」两种查看模式，可按设备（全部/PC/手机）筛选，实时 WebSocket 推送新日志，加载后自动滚动到最新位置
178. **前端摘要弹窗** — 📋 按钮打开摘要弹窗（GET `/api/activity/summary`），展示每 10 分钟一条压缩摘要，空闲条目斜体灰色显示，底部统计压缩比
179. **清空日志** — 前端「清空全部日志」按钮（POST `/api/activity/clear`），删除所有 JSONL 文件
180. **依赖** — PC 端需要 `pywin32`（`win32gui`）+ `psutil`，需安装到项目 `.venv` 中

### AI 联动（设备活动 × AI 交互）
181. **AI联动总开关** — `/activity-logs` 页面顶部「AI联动」开关（`activity_tracking_enabled`），控制所有 AI 与设备活动的交互。关闭后 `[查看动态:n]` 能力不注入 prompt、哨兵/监控不注入活动摘要。通过 `GET/PUT /api/activity/config` 管理，WebSocket 广播 `activity_config_changed` 事件多端同步
182. **聊天中查看动态** — AI联动开启时，Chat prompt 注入 `[查看动态:n]` 能力（n=1~12），Core 可主动查看用户设备动态并生成关怀评论，后端自动 clamp n 值防止异常
183. **哨兵注入活动摘要** — Sentinel 分析截图时自动注入近 60 分钟 6 条活动摘要（格式 `[HH:MM~HH:MM] 摘要`），作为辅助判据帮助哨兵更准确判断用户状态
184. **定时监控注入活动摘要** — `[Monitor:...]` 触发 Core 分析时自动注入近 120 分钟 12 条活动摘要，帮助 Core 结合设备使用模式理解用户行为

### 设备活动日志工作流程

【PC 前台窗口采集（activity.py PCActivityTracker）】 服务启动 → lifespan 中 pc_tracker.start() → 守护线程循环（60 秒间隔）： win32gui.GetForegroundWindow() → 获取窗口标题 psutil.Process(pid).name() → 获取进程名 → 过滤 Program Manager（桌面） → 无条件写入 append_activity_log()（加锁） → 标题变化？→ 是 → 控制台打印 + WebSocket 广播 → 每 5 分钟触发 cleanup_old_activity_logs()

【Android 前台 App 上报（AionPushService activityThread）】 服务启动 → startActivityThread() → 独立线程循环（60 秒间隔）： UsageEvents API 查询最近 120 秒事件 → 取最后一个 ACTIVITY_RESUMED 的包名 ├ 成功 → 过滤自身包名 → 无条件 POST /api/activity/report {device:"phone", app:包名} └ 失败 → fallback UsageStatsManager queryUsageStats → BroadcastReceiver 监听 SCREEN_OFF/SCREEN_ON → 立即上报 "screen_off"/"screen_on" ⚠ 需要「使用情况访问权限」（Settings > Special access > Usage access）

【服务端处理（routes/activity.py）】 POST /api/activity/report → resolve_app_name() 包名→中文名（KNOWN_APPS 映射 + 系统应用过滤） → append_activity_log() 加锁写入当天 JSONL 文件 → cleanup_old_activity_logs() 节流清理 >3 小时的条目（5 分钟最多一次） → WebSocket 广播 activity_log 事件 → 前端实时更新

【10 分钟活动摘要（activity.py generate_activity_summary）】 GET /api/activity/summary → read_recent_activity(3h) → 过滤系统应用 + Program Manager → 按 10 分钟窗口分组（时间范围：首条记录 ~ 上一个已结束窗口） → carry_forward：每个窗口向前查找各设备最后状态，填补开头空白 → _summarize_window()：设备分组 → 过滤亮屏 → 构建 (app, titles, duration) 段 → 按 display_name 合并同名段（如 TortoiseProc+TortoiseMerge→SVN） → 按时长降序排列 → 格式化为 "小红书 5分钟, 微信 2分钟" → 空窗口标记「没有活动」→ 连续空窗口合并（如 15:20~15:50 没有活动）

【前端查看（activity-logs.html）】 「最近3小时」→ GET /api/activity/recent → 滚动到底部 「按日期」→ GET /api/activity/dates → GET /api/activity/logs/{date} → 设备筛选 → 列表渲染 → WebSocket 监听 activity_log 事件实时追加 → 📋 摘要按钮 → GET /api/activity/summary → 弹窗展示 → 「清空全部」→ POST /api/activity/clear → 「AI联动」开关 → PUT /api/activity/config → WebSocket 广播 activity_config_changed

【AI联动（activity.py get_activity_summary_for_prompt）】 ├ 哨兵定时截图 → get_activity_summary_for_prompt(6) → 近 60 分钟 6 条摘要注入 Sentinel prompt ├ [Monitor:] 触发 → get_activity_summary_for_prompt(12) → 近 120 分钟 12 条摘要注入 Core trigger prompt └ [查看动态:n] → get_activity_summary_for_prompt(n) → 近 n×10 分钟 n 条摘要 → 组装 prompt → Core 生成回复 → 保存 system 消息 + assistant 回复 → WebSocket 广播 ⚠ AI联动开关关闭时，以上三条路径均返回空字符串，不注入任何摘要

### 爱的印记（AI 礼物系统）
317. **AI 自主送礼** — 每次自动记忆总结完成后，AI 综合判断是否需要给用户送一份礼物。判断依据：今天的聊天是否有特别温馨/感动/有意义的内容、是否是特殊日子（节日/纪念日/生日等）、用户的心情状态。Prompt 注入当前精确时间（年月日星期时分秒）+ 本次总结的所有记忆摘要 + 最近聊天上下文 + 世界书人设，要求 AI 返回结构化 JSON（`givegift` / `image_prompt` / `message`）
318. **硅基流动 Kolors 生图** — AI 决定送礼后，使用 `image_prompt` 调用硅基流动 `Kwai-Kolors/Kolors` 模型（免费）生成 1024×1024 图片。Prompt 约束为 cute cartoon style、不生成真实人物。图片 URL 1 小时过期，后端立即下载保存到 `data/uploads/gift_{timestamp}.png`
319. **礼物弹窗动画（全页面）** — 礼物生成后通过 WebSocket 广播 `gift_pending` 事件。前端任何页面（聊天页 chat.html + 所有子页面 common.js）收到后弹出全屏礼物动画。打开聊天页/子页面时也会自动检查 `GET /api/gift/pending` 并弹窗
320. **礼物盒开启流程** — ① SVG 礼物盒从底部弹跳入场 → ② 用户点击打开 → 播放「打开礼物.mp3」音效 → 盒盖飞走 + 60 个彩色礼花粒子爆炸 → ③ 图片从中心缩放淡入 → ④ 点击图片 → AI 的配图文字滑出 → 「💝 收下礼物」按钮出现 → ⑤ 点击收下 → 整体缩小飞走动画 → POST 标记 received
321. **爱的印记陈列馆** — `/gift` 页面（`gift.html`），暗色画廊风格，3 列缩略图网格展示所有已收到的礼物（缩略图+日期），点击打开详情弹窗（大图+日期+文字+删除按钮），按时间倒序排列
322. **礼物数据** — 存储在 SQLite `gifts` 表（id, image_path, message, created_at, status, received_at），status 为 `pending`（未领取）或 `received`（已领取）。删除礼物时同步清理本地图片文件
323. **不过度送礼** — Prompt 中明确要求 AI「不要每次都送，只在真正值得的时候才送，大部分时候应该返回 false」
324. **测试按钮** — 爱的印记页面右上角「🎁 测试送礼」按钮，取最近 5 条记忆 + 最近 20 条上下文触发完整送礼流程（AI 判断 + 生图 + 入库 + WebSocket 推送）
325. **主页入口** — home.html APPS 数组增加「爱的印记」（`/public/funIcon_0018_爱的印记.png`）

### 爱的印记工作流程

【触发时机（记忆总结完成后）】 _do_digest() 完成记忆总结 + 生成感慨消息 → 调用 gift.judge_and_send_gift() → 构建判断 Prompt（人设 + 当前时间 + 记忆摘要 + 上下文） → simple_ai_call() 调用核心模型 → 返回 JSON → givegift = false？→ 结束 → givegift = true？→ 提取 image_prompt + message

【生图 + 入库】 → POST https://api.siliconflow.cn/v1/images/generations model: Kwai-Kolors/Kolors, 1024x1024 → 下载图片 → 保存 data/uploads/gift_{ts}.png → INSERT INTO gifts (status='pending') → WebSocket 广播 gift_pending 事件

【前端弹窗（chat.html + common.js）】 页面加载 → GET /api/gift/pending → 有未领取？弹窗 WebSocket 收到 gift_pending → 弹窗 → SVG 礼物盒弹入 → 点击打开 → 播放音效 + 礼花 → 图片展示 → 点击图片 → 显示配图文字 → 「收下礼物」 → POST /api/gift/{id}/receive → 飞走动画

【陈列馆（gift.html）】 GET /api/gift/list → 3列缩略图网格 → 点击缩略图 → 详情弹窗（大图+文字+日期） → 可删除 → DELETE /api/gift/{id}（同步清理图片文件）

### 奥罗斯财团（基金持仓监控）
326. **持仓管理** — SQLite `fund_holdings` 表存储基金持仓信息（代码、名称、份额、平均成本、总成本、跌幅/涨幅预警阈值），前端支持添加/编辑/删除，持仓列表可折叠收起
327. **数据拉取（不涉及 AI）** — 使用 akshare 拉取所有持仓基金的最新净值和涨跌幅（`fund_open_fund_daily_em` + `fund_open_fund_info_em` 兜底），新浪财经接口拉取上证指数实时涨跌。根据持仓计算当前市值、浮盈亏金额/百分比，检查是否触发预警阈值。拉取结果缓存到 `fund_cache.json`，刷新页面后仍可显示
328. **历史走势查询** — `fund_open_fund_info_em` 拉取最近 N 天净值走势，分析时注入近 30 日走势摘要（最低/最高/整体趋势）
329. **AI 分析** — 将持仓数据 + 历史走势 + 大盘背景 + 用户投资倾向拼成结构化 prompt，连同世界书人设 + 最近 20 条聊天上下文一起发送给当前聊天模型。AI 回复作为 assistant 消息插入聊天 + TTS 语音播报 + WebSocket 广播
330. **每日定时分析** — `FundScheduler` 后台线程每 30 秒检查，交易日 14:45 自动触发分析。使用 `chinese_calendar.is_workday()` 判断交易日（自动处理周末 + 中国法定节假日含调休）
331. **功能开关** — 顶部 toggle 开关，状态持久化在 `fund_config.json`，关闭后定时任务不触发、不影响其他功能
332. **投资倾向** — 可编辑的文本框，保存后在 AI 分析时注入 prompt（如"计划买入黄金，等合适坑位"），帮助 AI 给出更贴合的建议
333. **手动操作** — 「🔄 刷新数据」仅拉取数据不调 AI；「📊 立即分析」拉数据 + 调 AI + TTS，操作不阻塞页面，可自由切换到其他页面
334. **主页入口** — home.html APPS 数组增加「奥罗斯财团」（`/fund`）

### 奥罗斯财团工作流程

【手动刷新数据（不调 AI）】 点击「🔄 刷新数据」→ POST /api/fund/fetch → akshare 拉取全量基金日数据 + 新浪财经拉取上证指数 → 逐只匹配持仓基金，计算盈亏、检查预警 → 缓存到 fund_cache.json → 返回前端渲染

【手动/定时 AI 分析】 点击「📊 立即分析」→ POST /api/fund/analyze（或 14:45 定时触发） → 拉取持仓数据 + 30 日历史走势 → 生成分析 prompt（持仓明细 + 走势摘要 + 大盘 + 投资倾向） → 组装消息（世界书人设 + 20 条上下文 + prompt） → stream_ai() 流式调用当前模型 → 插入系统消息「💰 奥罗斯财团 — 基金持仓分析」+ AI 回复 → TTS 语音播报 + WebSocket 广播到聊天页

【定时任务（FundScheduler）】 后台线程每 30 秒检查 → 14:45 + 交易日 + 开关开启 → 触发 run_fund_analysis() → 等待到 14:46 避免重复触发

### 浏览器保活 & 系统通知
105. **静音音频保活** — 页面加载后自动创建 AudioContext 播放无声音频（30秒循环），防止手机浏览器后台休眠导致 WebSocket 断连和闹铃失效
106. **Web Notification** — 闹铃触发和监控提醒时通过 `Notification API` 发送系统级推送通知，即使浏览器在后台也能看到

### Android 原生 App（AionApp / Aion Oloth）
107. **WebView 壳应用** — Java Android 项目，WebView 加载 chat.html，支持文件上传、麦克风权限、全屏沉浸
108. **双地址启动页** — LauncherActivity 提供「家庭WiFi」和「Tailscale」两个地址入口，支持「记住选择」下次自动进入
109. **原生录音桥 AudioBridge** — 绕过 WebView 中 `getUserMedia` 需要 HTTPS 的限制，使用 Android 原生 `AudioRecord`（16kHz, VOICE_RECOGNITION）录音，通过 `@JavascriptInterface` 将 base64 PCM 数据回调到 JS。视频录制期间自动转发 PCM 帧给 VideoBridge
110. **原生视频录制桥 VideoBridge** — MediaCodec(H.264) + MediaCodec(AAC) + MediaMuxer 编码 MP4，复用 CameraBridge 的视频帧和 AudioBridge 的音频帧进行视频录制，录制期间摄像头预览不中断。JS 通过 `window.AionVideo` 接口控制录制（`startRecord`/`stopRecord`/`cancel`），`stopRecord` 返回 base64 编码的 MP4 数据
111. **手势导航适配** — 兼容 Vivo X300 Pro 等全面屏手势导航，返回键弹出对话框（切换地址 / 退出 / 取消）

### Android 前台推送服务（AionPushService）
115. **前台服务 + 独立 WebSocket** — `AionPushService` 作为 Android 前台服务运行，通过 OkHttp 维持独立于 WebView 的 WebSocket 长连接（`/ws`），不依赖页面生命周期
115b. **GPS 定位上报** — 独立定位线程每 10 分钟 GET `/api/location/config` 检查 `active` 字段，`active=true` 时获取 GPS 坐标并 POST `/api/location/heartbeat`，`active=false` 时跳过（省电）
115c. **设备活动上报** — 独立活动线程每 60 秒通过 UsageEvents API 获取前台应用包名，POST `/api/activity/report`；BroadcastReceiver 监听屏幕开关事件即时上报。需要 `PACKAGE_USAGE_STATS` 权限（AndroidManifest 声明 + 用户手动在「使用情况访问权限」中授权）
116. **三级通知渠道** — ① `aion_keepalive`（保活）：常驻通知栏"Aion 在线中 ✨"，低优先级不打扰；② `aion_messages`（消息）：AI 回复通知，默认优先级；③ `aion_alarm`（闹铃与监控）：高优先级 heads-up 弹出式通知 + 声音振动 + 锁屏可见
117. **智能通知过滤** — 只推送 3 种消息：`schedule_alarm`（闹铃⏰）、`monitor_alert`（定时监控提醒👁）、`new_message` 中 role=assistant 的 AI 回复（💬）。系统消息/cam_check/msg_created 等均不推送，避免通知轰炸
118. **前后台状态感知** — WebViewActivity 的 `onResume`/`onPause` 通过 Intent 通知 Service 当前是否在前台。app 前台时只推送闹铃和监控（高优先级），不推送 AI 消息（避免重复）；app 后台/锁屏时推送所有类型
119. **WakeLock + WiFi Lock 保活** — `PARTIAL_WAKE_LOCK` 防止 CPU 深度休眠，`WIFI_MODE_FULL_LOW_LATENCY` 防止锁屏后 WiFi 休眠。这是保证锁屏后 WebSocket 不断的关键
120. **独立后台线程心跳** — 使用纯 Java `Thread` + `Thread.sleep(45s)` 做心跳循环（不用 Android 的 HandlerThread/Looper），每 45 秒发送 `{"type":"ping"}` 文本消息保持连接活性，同时检查健康状态（120 秒无消息则强制重连）
121. **Generation 计数器防重连风暴** — 每次新建 WebSocket 连接 `wsGeneration++`，旧连接的 `onClosed`/`onFailure` 回调发现 generation 不匹配则直接 return，不触发重连。关闭旧连接用 `cancel()` 而非 `close()`，`cancel()` 不触发回调
122. **NetworkCallback 网络恢复即重连** — 注册 `ConnectivityManager.NetworkCallback`，网络恢复（WiFi 重连 / Tailscale 启动）瞬间立即触发重连，不用等待心跳周期
123. **指数退避重连** — 连接失败后 3s → 6s → 12s → 24s → 30s（上限），连接成功后退避重置为 3s
124. **onTaskRemoved 自复活** — 用户划掉 app 后，通过 `AlarmManager.setExactAndAllowWhileIdle()` 3 秒后自动重启服务。但"强制停止"仍会彻底杀死服务（Android 系统限制）
125. **WebView 回前台自动刷新** — `WebViewActivity.onResume()` 中检测 WebView 内 WebSocket 状态（readyState !== 1 则重连），并延迟 1.5 秒调用 `loadMessages()` 拉取后台期间错过的消息
126. **服务端 ping/pong** — 服务端 WebSocket 端点处理客户端发来的 `{"type":"ping"}`，回复 `{"type":"pong"}`，作为应用层心跳确认
127. **服务端广播日志** — `ws.py` 的 `broadcast()` 每次广播打印 `type`、成功/失败/总客户端数，方便排查推送问题
128. **服务端连接异常兜底** — WebSocket 端点用 `except Exception` + `finally: manager.disconnect(ws)` 替代仅 `except WebSocketDisconnect`，防止 RST 等异常导致死连接留在 `active` 列表中

### Android 推送服务工作流程

【启动】 LauncherActivity 选择地址 → startForegroundService(AionPushService, wsUrl) → Service 创建前台通知"Aion 在线中 ✨" → 获取 WakeLock + WiFi Lock → OkHttp WebSocket 连接 ws://host:port/ws → 启动心跳线程 + 注册 NetworkCallback → 启动定位线程（10 分钟间隔，独立 Java Thread） → 启动活动上报线程（60 秒间隔，独立 Java Thread）+ 注册屏幕亮灭 BroadcastReceiver

【消息接收与通知】 服务端广播 WebSocket 消息 → OkHttp onMessage 回调 → 解析 JSON type 字段： ├ schedule_alarm → 始终弹高优先级通知（⏰ 闹铃，含内容预览，锁屏可见） ├ monitor_alert → 始终弹高优先级通知（👁 监控提醒，含监控内容） ├ new_message (role=assistant) → 仅 app 后台时弹通知（💬 AI 名: 消息预览） └ 其他（msg_created/cam_check/system 等）→ 忽略，不弹通知

【心跳保活（独立 Java Thread）】 while (running): Thread.sleep(45s) if (已连接): 发送 {"type":"ping"} → 服务端回复 {"type":"pong"} → 更新 lastPongTime if (120秒无 pong): 判定连接死亡 → 关闭 + 重连 if (未连接 && 无重连计划): 立即重连

【断线重连】 onFailure/onClosed → 检查 generation 是否匹配 → 否则 return → 匹配则标记 wsConnected=false → Thread.sleep(退避时间) → connectWebSocket() → 退避时间翻倍（上限 30s）→ 成功后重置为 3s

【网络恢复】 NetworkCallback.onAvailable → 如果 WebSocket 未连接 → 立即重连

【GPS 定位上报（独立 Java Thread，10 分钟间隔）】 while (running): Thread.sleep(10min) GET /api/location/config → 读取 active 字段 ├ active = false → 跳过本轮（安静时段或功能关闭，不采集 GPS） └ active = true: LocationManager.requestSingleUpdate(GPS_PROVIDER / NETWORK_PROVIDER, 60s超时) → 获取坐标（WGS84） → POST /api/location/heartbeat {lng, lat, accuracy} → 服务端三级研判处理

【app 划掉自复活】 onTaskRemoved → AlarmManager.setExactAndAllowWhileIdle(3s后) → 重启 Service

【设备活动上报（独立 Java Thread，60 秒间隔）】 while (running): Thread.sleep(60s) UsageEvents API 查询最近 60 秒内的 MOVE_TO_FOREGROUND 事件 → 取最后一个包名 ├ 失败 → fallback UsageStatsManager queryUsageStats ├ 过滤自身包名 → 5 分钟内同一应用不重复上报 └ POST /api/activity/report {device:"phone", app:包名}

• BroadcastReceiver 监听 SCREEN_OFF/SCREEN_ON → 即时上报 "screen_off"/"screen_on"

### 手机端语音唤醒（远程模式）
111. **麦克风来源选择** — 语音设置面板提供「本机麦克风」和「手机端麦克风」两种模式，手机端自动选择远程模式
112. **能量 VAD** — 手机端使用能量阈值 VAD 替代 WebRTC VAD（后者依赖 PC 端 sounddevice），基于 PCM 帧 RMS 能量判断人声
113. **远程 ASR** — 手机录音通过 AudioBridge → JS 拼接 WAV → POST `/api/voice/remote-asr` → 服务端硅基流动 ASR 识别
114. **完整通话流程** — 唤醒 → 录音 → ASR → 发送消息到聊天 → AI 回复 + TTS → 暂停录音 → TTS 播完恢复录音，与 PC 端体验一致

### 手机端语音工作流程

【AudioBridge 原生录音】 WebViewActivity 注入 window.AionAudio JS 接口 → remoteVoice.start() 调用 AionAudio.start() → AudioRecord(16kHz, VOICE_RECOGNITION) 启动录音线程 → 每 40ms 帧 base64 编码 → evaluateJavascript("remoteVoice._onNativeChunk(...)") → JS 端能量 VAD 判断人声（RMS > 阈值） → 静音超时 → 拼接 WAV → POST /api/voice/remote-asr → 服务端硅基流动 ASR → 返回识别文本 → 检查唤醒词 / 挂断词 / 发送消息

### 性能优化
49. **数据库索引** — messages 表 (conv_id, created_at) 复合索引 + conversations 表 (updated_at DESC) 索引
50. **消息分页加载** — API 支持 `?limit=50&before=时间戳`，默认只加载最新 50 条消息
51. **前端懒加载** — 打开对话秒加载最新 50 条，滚动到顶部自动加载更早消息
52. **发送历史优化** — 发消息时用 SQL LIMIT 直接取最近 N 条，不再全量加载再截断
53. **WebSocket 事件扩展** — cam_check 和 debug 事件同时通过 SSE + WebSocket 双通道广播，语音发送的消息也能获得完整 debug 信息

### PWA 支持（Progressive Web App）
54. **Web App Manifest** — `manifest.json` 声明 App 名称（Aion Chat）、图标（192/512）、主题色、全屏 standalone 模式
55. **Service Worker** — `sw.js` 从根路径 `/sw.js` 提供，作用域覆盖全站，让浏览器识别为可安装 PWA
56. **手机安装为独立 App** — Android Chrome 添加到主屏幕后全屏运行，无地址栏/标签栏，体验接近原生 App
57. **iOS 支持** — 通过 `apple-mobile-web-app-capable` + `apple-touch-icon` meta 标签支持 Safari 添加到主屏幕

### 外网远程访问（Tailscale）
58. **Tailscale 虚拟组网** — 电脑和手机安装 Tailscale 并登录同一账号，通过 WireGuard 加密隧道直连，无需公网 IP 或端口转发
59. **安全性** — 8080 端口不对公网开放，仅 Tailscale 虚拟网络内设备可访问，数据端到端加密
60. **固定 IP 访问** — 通过 Tailscale 分配的 `100.x.x.x` 固定 IP 访问，手机 4G/5G 外网环境可用
61. **PWA + Tailscale 配合** — 手机 Chrome `chrome://flags` 将 Tailscale IP 标记为安全源后，可正常安装 PWA

### 记忆系统工作流程

【即时哨兵 instant_digest — 每次发消息自动触发】 用户发消息 → flash-lite 分析最近对话 → 返回 JSON: { "is_search_needed": true/false, // 是否需要搜索记忆 "keywords": ["关键词1", "关键词2"], // 搜索关键词 "require_detail": true/false, // 是否需要追溯原文 "status": "用户当前状态" // 状态变化时更新 chat_status } ↓ (如果 is_search_needed = true) recall_memories: 向量相似度×0.6 + 关键词命中率×0.3 + 重要度×0.1 → Top 5 记忆注入 prompt（自动与背景记忆去重） ↓ (如果 require_detail = true 且有召回) fetch_source_details: 在记忆 source 时间范围内按关键词筛选原始对话 → 原文细节追加注入 prompt

【记忆总结 _do_digest — 手动点击按钮 / 自动定时触发】 自动触发条件：每 30 分钟检测，用户已 30 分钟未对话 且 未总结消息 ≥ 30 条 手动触发：无最低条数限制，共用锚点不会重复总结 从锚点时间之后取消息 → 每 30 条一组（余数<10合并）→ 串行处理： 核心模型（当前聊天模型）分析，注入世界书 AI/用户人设 → 输出 JSON: {"summary": "...", "keywords": [...], "importance": 0.8, "unresolved": true/false} → embedding 向量化 → 存入 SQLite → 更新锚点 全部组处理完毕后 → 核心模型带上下文生成感慨 → 插入系统胶囊 + assistant 消息

### 向量记忆库工作流程

【背景记忆浮现 build_surfacing_memories — 每次发消息/重新生成时】 即时哨兵返回 topic → 三层浮现策略： ① unresolved 优先：memories 表 unresolved=1 的记忆（最多 2 条） ② 话题相关：用 topic 做 embedding，余弦相似度 ≥ 0.50 的 Top 3 ③ 近期补充：最近 3 天的记忆，补满 8 条 → 去重后以 [背景记忆] 块注入 prompt → 返回 surfaced_ids 供 RAG 召回去重

【RAG 精确召回 — 仅 is_search_needed=true 时】 recall_memories: 向量相似度×0.6 + 关键词×0.3 + 重要度×0.1 → 过滤掉已在背景记忆中的 id → Top 5 注入 [相关记忆]

【写入】手动按钮 / 自动定时触发（共用 _do_digest） → 核心模型（当前聊天模型）+ 世界书人设注入，从消息提取记忆 （summary + keywords + importance + unresolved） → gemini-embedding-001 向量化（3072维） → 存入 SQLite memories 表 + WebSocket 广播 → 全部完成后生成感慨，插入聊天（系统胶囊 + assistant 消息）

## API 一览

### 对话/消息
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/conversations` | GET | 对话列表 |
| `/api/conversations` | POST | 创建对话 |
| `/api/conversations/{conv_id}` | PUT | 更新对话（标题/模型） |
| `/api/conversations/{conv_id}` | DELETE | 删除对话 |
| `/api/conversations/{conv_id}/messages` | GET | 消息列表（支持 `?limit=50&before=时间戳` 分页） |
| `/api/conversations/{conv_id}/send` | POST | 发送消息（SSE 流式） |
| `/api/conversations/{conv_id}/regenerate` | POST | 重新生成 AI 回复（SSE 流式） |
| `/api/messages/{msg_id}` | PUT | 编辑消息 |
| `/api/messages/{msg_id}` | DELETE | 删除消息 |
| `/api/cam-check-trigger` | POST | Core 主动查看监控触发（前端延迟 5 秒后调用） |

### 摄像头
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/cam/status` | GET | 摄像头和监控状态 |
| `/api/cam/cameras` | GET | 可用摄像头列表 |
| `/api/cam/open` | POST | 打开摄像头 |
| `/api/cam/close` | POST | 关闭摄像头 |
| `/api/cam/monitor/start` | POST | 开始定时监控 |
| `/api/cam/monitor/stop` | POST | 停止定时监控 |
| `/api/cam/config` | GET/POST | 读取/保存摄像头配置 |
| `/api/cam/frame` | GET | 获取当前帧（JPEG） |
| `/api/cam/screenshot` | POST | 手动截图 |
| `/api/cam/logs` | GET | 日志日期列表 |
| `/api/cam/logs/{date}` | GET | 指定日期的日志条目 |

### 设置/世界书/状态
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/settings` | GET/POST | 读取/保存设置（API Key 等） |
| `/api/worldbook` | GET/POST | 读取/保存世界书 |
| `/api/chat_status` | GET | 获取当前聊天状态摘要 |
| `/api/models` | GET | 可用模型列表 |

### 记忆库
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/memories` | GET | 获取所有记忆（按时间倒序） |
| `/api/memories` | POST | 手动添加记忆（自动向量化） |
| `/api/memories/{id}` | PUT | 编辑记忆（重新向量化，支持 unresolved 字段） |
| `/api/memories/{id}` | DELETE | 删除记忆 |
| `/api/memories/{id}/unresolved` | PATCH | 切换记忆的 unresolved 状态 |

### TTS 语音合成
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/tts` | POST | TTS 合成代理，接收 `{text, voice}`，返回 mp3 音频流 |
| `/api/tts/voices` | GET | 获取硅基流动账号下的可用音色列表 |
| `/api/tts/audio/{name}` | GET/HEAD | 获取 TTS 缓存音频分片（`{msg_id}_s{seq}.mp3`），HEAD 用于前端探测分片是否存在 |

### 文件管理
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/files` | GET | 导出文件列表 |
| `/api/files/{filename}` | DELETE | 删除导出文件 |
| `/api/upload` | POST | 上传图片/视频 |

### 音乐
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/music/search` | GET | 搜索歌曲（`?keyword=xxx&limit=5`） |
| `/api/music/detail/{song_id}` | GET | 获取歌曲详情 |
| `/api/music/play` | POST | 获取播放信息（`{song_id}` → 返回歌曲信息 + audio_url + web_url） |
| `/api/music/stream/{song_id}` | GET | 服务端代理推流（后端实时获取 CDN URL 并转发音频流，解决防盗链） |

### 语音唤醒/通话
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/voice/status` | GET | 语音状态（开关/通话中/AI说话中） |
| `/api/voice/toggle` | POST | 开关语音监听（`{enabled, wake_word}`） |
| `/api/voice/ai-speaking` | POST | 前端通知 TTS 播放状态（`{speaking}`） |
| `/api/voice/cam-check-start` | POST | 通知语音模块 CAM_CHECK 开始，保持 AI 说话状态 |
| `/api/voice/remote-asr` | POST | 手机端远程 ASR：接收 WAV 音频文件，转发硅基流动 SenseVoiceSmall 识别 |

### 活动日志
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/activity/report` | POST | 设备活动上报（`{device, app, title?, timestamp?}`），自动名称解析+过滤+JSONL存储+WS广播 |
| `/api/activity/status` | GET | PC 采集线程状态诊断（是否运行、线程状态、上次窗口标题等） |
| `/api/activity/dates` | GET | 返回所有有日志的日期列表 |
| `/api/activity/logs/{date}` | GET | 返回指定日期的活动日志（自动名称解析） |
| `/api/activity/recent` | GET | 返回最近 N 小时的活动日志（默认 8 小时，`?hours=N`） |
| `/api/activity/clear` | POST | 清除所有活动日志文件 |

### 日程/闹铃
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/schedules` | GET | 日程列表（可选 `?status=active`） |
| `/api/schedules` | POST | 手动添加日程（`{type, trigger_at, content}`） |
| `/api/schedules/{id}` | DELETE | 删除日程 |

### 奥罗斯幽林 TRPG
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/ghost-forest/personas` | GET | 列出所有 DM/玩家人设 |
| `/api/ghost-forest/personas` | POST | 创建/更新人设 |
| `/api/ghost-forest/personas/{pid}` | DELETE | 删除人设 |
| `/api/ghost-forest/sessions` | GET | 列出所有游戏会话（摘要） |
| `/api/ghost-forest/sessions` | POST | 创建新游戏会话 |
| `/api/ghost-forest/sessions/{sid}` | GET | 获取完整会话数据 |
| `/api/ghost-forest/sessions/{sid}` | PATCH | 更新会话模型 |
| `/api/ghost-forest/sessions/{sid}` | DELETE | 删除会话 |
| `/api/ghost-forest/sessions/{sid}/generate-outline` | POST | AI 生成剧情大纲（SSE） |
| `/api/ghost-forest/sessions/{sid}/start` | POST | 提交属性分配，开始游戏 |
| `/api/ghost-forest/sessions/{sid}/narrate` | POST | AI 生成当前回合叙述（SSE） |
| `/api/ghost-forest/sessions/{sid}/choose` | POST | 提交选择 + 骰子结果（SSE） |
| `/api/ghost-forest/sessions/{sid}/pause` | POST | 暂停游戏 |
| `/api/ghost-forest/sessions/{sid}/resume` | POST | 恢复游戏 |
| `/api/ghost-forest/sessions/{sid}/finale` | POST | 生成大结局（SSE） |
| `/api/ghost-forest/sessions/{sid}/summary` | POST | 生成冒险总结 |

### 定位/高德地图
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/location/heartbeat` | POST | GPS 心跳上报（`{lng, lat, accuracy}`，可选 `force=true` 强制刷新 API） |
| `/api/location/status` | GET | 当前定位状态（坐标、地址、天气、状态、距离） |
| `/api/location/poi-search` | POST | 手动触发 POI 搜索（`{categories}` 逗号分隔类型） |
| `/api/location/pois` | GET | 获取缓存的 POI 列表 |
| `/api/location/config` | GET | 读取定位配置（含 `active` 字段供 Android 判断是否采集） |
| `/api/location/config` | POST | 保存定位配置（高德Key/开关/安静时段/阈值等） |
| `/api/location/set-home` | POST | 设置家位置（`{lng, lat}` GCJ-02 坐标） |

### SSE 事件类型（send / regenerate）
| type | 说明 |
|------|------|
| `start` | 流开始，含 AI 消息 id |
| `chunk` | 流式文本块 |
| `cam_check` | Core 触发 [CAM_CHECK]，前端播放提示音+延迟触发 |
| `cam_offline` | 摄像头未开启，前端显示提示 |
| `music` | 音乐卡片数据：主推荐歌曲 + 候选列表 |
| `poi_search` | POI 搜索触发：含 msg_id + categories，前端显示蓝色搜索指示器 |
| `toy_command` | 玩具控制指令：含 commands 数组 + msg_id |
| `image_gen_start` | AI 生图开始：含 msg_id + prompt + is_selfie，前端显示橙色生图指示器 |
| `debug` | Debug 数据：模型名、token 用量、召回记忆、完整 prompt |
| `done` | 流结束 |

### WebSocket 事件类型
| type | 说明 |
|------|------|
| `conv_created/updated/deleted` | 对话变动同步 |
| `msg_created/updated/deleted` | 消息变动同步 |
| `monitor_log` | 新监控日志推送 |
| `chat_status` | 聊天状态摘要更新 |
| `memory_added` | 新记忆添加 |
| `voice_state` | 语音状态广播（开关/唤醒/聊天中/AI思考/挂断等） |
| `cam_check` | [CAM_CHECK] 触发通知（SSE + WS 双通道） |
| `music` | 音乐卡片数据广播（SSE + WS 双通道） |
| `debug` | Debug 数据广播（SSE + WS 双通道，语音发送时也能收到） |
| `monitor_alert` | 定时监控触发，前端播放提示音，手机端弹高优先级通知 |
| `schedule_alarm` | 闹铃到期触发，前端弹出确认弹窗，手机端弹高优先级通知 |
| `schedule_changed` | 日程列表变动，前端刷新面板 |
| `toy_command` | 玩具控制指令广播（含 commands 数组，SSE + WS 双通道） |
| `location_update` | 定位状态更新广播（地址、天气、状态变更等） |
| `poi_search` | POI 搜索触发广播（SSE + WS 双通道，前端显示搜索指示器） |
| `activity_log` | 新设备活动日志推送（含 device/app/title/time，前端实时追加） |
| `tts_chunk` | TTS 音频分片推送（含 msg_id/seq/url），前端收到即加入播放队列 |
| `tts_done` | TTS 合成完毕通知（含 msg_id），前端标记该消息队列已结束，播完最后一片后清理 |
| `tts_state` | 客户端→服务端：TTS 开关/音色同步（`{enabled, voice}`），服务端据此判断是否需要合成 |
| `image_gen_start` | AI 生图开始广播（SSE + WS 双通道） |
| `image_gen_done` | AI 生图完成广播（含 conv_id），前端移除指示器 |
| `image_gen_failed` | AI 生图失败广播（含 conv_id），前端移除指示器 |

### 消息角色说明
| 角色 | 说明 | 是否显示在聊天 |
|------|------|---------------|
| `user` | 用户消息 | ✅ |
| `assistant` | AI 回复（含 Core 唤醒/主动查看监控的回复） | ✅ |
| `cam_user` | Sentinel 截图查询（内部） | ❌ 隐藏 |
| `cam_log` | Sentinel 分析结果（内部） | ❌ 隐藏 |
| `cam_trigger` | Core 唤醒时的系统提示（内部） | ❌ 隐藏 |

## Prompt 注入顺序

1. [系统设定 - AI人设] + assistant 确认 ← 缓存命中
2. [系统设定 - 用户信息] + assistant 确认 ← 缓存命中
3. [系统能力] 合并能力提示 + 日程列表 + assistant 确认（不含时间） ← 缓存命中
   • [MUSIC:歌曲名 歌手名] — 点歌（始终可用）
   • [CAM_CHECK] — 主动查看监控（仅摄像头开启时）
   • [POI_SEARCH:类型名] — 搜索附近 POI（仅外出状态 + 定位开启时）
   • [ALARM:datetime|内容] — 设置闹铃（始终可用）
   • [REMINDER:date|内容] — 设置日程提醒（始终可用）
   • [SCHEDULE_DEL:id] — 删除日程（始终可用）
   • [TOY:1]~[TOY:9] — 控制玩具预设档位（仅密语模式开启时）
   • [TOY:STOP] — 停止玩具（仅密语模式开启时）
   • [SELFIE:prompt] — AI 自拍生图（附带参考图，仅 AI 生图开关开启时）
   • [DRAW:prompt] — AI 自由画图（仅 AI 生图开关开启时）
   • 【当前日程列表】 — 活跃日程/闹铃一览
   • 【位置信息】 — 当前地址 + 实时天气 + 离家距离 + 状态（仅有有效坐标时注入）
4. 当前准确时间 ← ⚡缓存分界点
   • [背景记忆] unresolved📌 + 话题相关 + 近期补充（最多8条） ← 动态
5. [相关记忆] 向量召回的记忆（与背景记忆去重） + assistant 确认 ← 动态
6. 聊天历史（受上下文长度滑块限制） ← 动态

## 关键实现细节
- **模块化架构**：main.py 仅约 70 行，业务逻辑拆分到 config/database/ws/ai_providers/memory/camera + routes/ 下 5 个路由模块
- **多模态构建**：`build_multimodal_messages()`（硅基流动 base64 URL）和 `build_gemini_contents()`（Gemini inline_data）
- **Token 用量捕获**：stream_ai 通过 meta dict 在流式过程中捕获 Gemini usageMetadata / 硅基流动 usage
- **Gemini 轮次交替**：Gemini API 要求 user/model 严格交替，所有系统注入都以 user+assistant 对形式插入
- **[CAM_CHECK] 流程**：后端在 SSE 中发 `cam_check` 事件 + WebSocket 广播 → 前端播放音频+5秒 setTimeout → POST trigger API → 后端 asyncio.create_task 异步截图+AI分析
- **cam_check 加载指示器**：前端用 `camCheckMsgId` 全局变量跟踪，`renderMessages()` 重建 DOM 后自动恢复指示器
- **语音唤醒架构**：voice.py 运行在独立线程，通过 `asyncio.run_coroutine_threadsafe` 桥接主事件循环；WebRTC VAD (mode=2) 做帧级人声检测（30ms/帧），不需要噪底校准
- **半双工协调**：`ai_speaking` 标志由服务端 `tts_done` WebSocket 事件驱动（前端收到后调用 `notifyVoiceAiSpeaking(false)`），暂停录音期间持续 `stream.read()` 丢弃数据防止缓冲区溢出；voice.py 的 `_async_send` 在 HTTP POST body 中携带 `tts_enabled`/`tts_voice` 参数
- **消息分页**：后端 `?limit=50&before=时间戳` 参数，前端 `loadOlderMessages()` 滚动到顶部自动加载，保持滚动位置
- **SSE + WS 双通道**：cam_check 和 debug 事件同时写入 SSE 流和 WebSocket 广播，确保语音发送的消息（无 SSE 流读取端）也能被前端接收
- **文件导出**：消息变动自动同步到 `chats/{conv_id}.md`，含 YAML front matter，导出跳过 cam_* 角色
- **监控定时器**：基于时间戳比较（`_next_capture_at`），非 sleep 阻塞，间隔修改即时生效
- **摄像头 DirectShow + 验证机制**：所有 `cv2.VideoCapture` 使用 `CAP_DSHOW` 后端（Windows MSMF 后端对 USB 摄像头不稳定）；`_verify_camera()` 最多等 8 秒读到非垃圾帧（`frame.mean() > 5` 排除绿屏/黑屏）才算成功；`_capture_loop` 运行时也检测绿屏帧，连续 100 帧无效触发重连；重连逐个尝试 index 0-4 并验证，失败后 30 秒重试
- **Sentinel 日志压缩**：哨兵每次分析时输出历史概况摘要（summary），避免 Core 唤醒时全量日志导致 token 过高
- **TTS 流式推送架构**：`tts.py` 的 `TTSStreamer` 在 AI 流式输出过程中实时接收文本（`feed()`），按标点（句号/问号/感叹号/换行等）切分为 100-200 字的片段（`_try_split()` + `_find_cut_position()`），每段 `asyncio.create_task` 异步调用硅基流动 CosyVoice2-0.5B 合成 mp3（`_synthesize()`），合成完成后通过 `_dispatch()` 将音频保存到 `data/tts_cache/{msg_id}_s{seq}.mp3` 并 WebSocket 广播 `tts_chunk` 事件；`flush()` 在 AI 输出结束后处理剩余文本并等待所有合成任务完成，最后广播 `tts_done` 事件
- **TTS 多端状态同步**：前端开启 TTS 后通过 WebSocket 发送 `tts_state` 消息，`ConnectionManager.tts_clients` 字典跟踪各连接的 TTS 状态；HTTP POST（send_message/regenerate）body 中的 `tts_enabled`/`tts_voice` 通过 `set_tts_fallback()` 存入 `_tts_fallback` 作为回落，确保 cam_check/闹铃/定时监控等服务端发起的消息也能正确获取 TTS 状态（`any_tts_enabled()` + `get_tts_voice()` 同时检查两处）
- **PC 活动采集**：`PCActivityTracker` 守护线程通过 `win32gui.GetForegroundWindow()` + `psutil.Process.name()` 每 15 秒检测前台窗口变化，通过 `asyncio.run_coroutine_threadsafe()` 桥接主事件循环上报；`pywin32` 和 `psutil` 必须安装在项目 `.venv` 中（系统 Python 中的无效）
- **App 名称解析**：服务端 `KNOWN_APPS` 字典映射 80+ 常见包名/进程名→中文名，`resolve_app_name()` 返回 `None` 表示需过滤的系统应用（桌面、SystemUI 等），读取历史日志时 `_resolve_entries()` 对旧条目重新解析确保名称一致
- **活动日志清理**：`cleanup_old_activity_logs()` 读取→过滤→重写 JSONL 文件，仅保留 `KEEP_HOURS=8` 小时内的条目，每次上报时顺带执行
- **TTS 前端播放流程**：前端 `ttsQueue`（Map，key=msg_id）维护各消息的播放队列，`playNextTTSChunk()` 按 seq 顺序取出分片 URL 播放；收到 `tts_done` WebSocket 事件后标记 `q.finished = true`，当最后一片播放完毕且队列标记结束时，调用 `finishTTSForMsg()` 清理并通知语音模块（`notifyVoiceAiSpeaking(false)`）恢复录音
- **消息编辑 attachments 修复**：后端 `update_message` 广播前 `json.loads` 解析 attachments，避免前端收到字符串导致渲染崩溃
- **PWA 架构**：`sw.js` 和 `manifest.json` 物理存放在 `static/` 目录，但通过 `main.py` 的独立路由从根路径 `/sw.js`、`/manifest.json` 提供，确保 Service Worker 作用域覆盖全站
- **外网访问**：通过 Tailscale 组建虚拟局域网，WireGuard 端到端加密，无需暴露公网端口；代码层面零改动，仅需两端安装 Tailscale 并登录同一账号
- **BLE 玩具集成**：Web Bluetooth API 连接 SOSEXY BLE 设备（服务 0xEE01，写入 0xEE03），sendData2 封包协议（前缀 00 + 18字节分包 + 随机包头 + 终止包）；`whisper_mode` 参数按需注入 `[TOY:x]` 能力到 prompt，后端 `TOY_CMD_PATTERN` 正则检测+strip+广播+`_toy_sys_msg` 系统消息
- **背景记忆浮现**：`build_surfacing_memories(topic, keywords)` 三层策略构建最多 8 条背景记忆：① unresolved 优先（最多 2 条）→ ② 用即时哨兵的 topic 做 embedding 匹配（Top 3，阈值 0.50）→ ③ 最近 3 天的记忆补充。注入时 unresolved 带 📌 前缀，与后续 RAG 召回自动去重
- **记忆阈值**：cosine ≥ 0.75 才召回，top_k=3，去重阈值 0.85
- **静音保活**：`startSilentKeepAlive()` 创建 AudioContext + OscillatorNode（gain=0.001），30 秒循环，防止手机浏览器后台杀 JS 线程导致 WebSocket 断连和闹铃失效
- **Web Notification**：`sendSystemNotification()` 封装 Notification API，闹铃弹窗和监控提醒时同时发送系统推送，需用户授权 `Notification.requestPermission()`
- **AudioBridge 架构**：`AudioBridge.java` 使用 `AudioRecord(VOICE_RECOGNITION, 16000, MONO, PCM_16BIT)`，录音线程每 40ms 读取 1280 字节（640 samples），base64 编码后通过 `evaluateJavascript` 注入 JS；JS 端 `remoteVoice._onNativeChunk()` 解码 → 存入环形 buffer → 能量 VAD 判断语音段 → 静音截断 → 拼接 WAV 头 → POST 到 `/api/voice/remote-asr`
- **远程 ASR 端点**：`routes/voice.py` 的 `/api/voice/remote-asr` 接收 multipart WAV 文件，用 httpx 转发到硅基流动 `https://api.siliconflow.cn/v1/audio/transcriptions`（model=FunAudioLLM/SenseVoiceSmall），返回 `{text}` JSON
- **手机端语音协调**：`remoteVoice` 对象维护 `aiSpeaking` 状态，通过 `notifyVoiceAiSpeaking()` 和 `notifyVoiceCamCheckStart()` 统一分发给 PC 端 `/api/voice/ai-speaking` 或手机端 `remoteVoice._onAiSpeaking()`，TTS 播放完毕（`tts_done` 事件触发）后自动恢复录音
- **音乐点歌架构**：`music.py` 封装 pyncm（`_ensure_session` 线程安全匿名登录），`routes/music.py` 提供 REST API 并导出 `MUSIC_CMD_PATTERN` 正则；`routes/chat.py` 在 send_message 和 regenerate 流结束后检测 `[MUSIC:xxx]`，搜索并通过 SSE `music` 事件 + WebSocket 广播发送卡片数据
- **能力提示合并**：[MUSIC:xxx] 和 [CAM_CHECK] 合并为单个 `[系统能力]` user+assistant 对注入，减少 token 消耗（从 4 条消息降为 2 条）
- **音乐前端渲染**：`msgMusicCards` 字典按消息 ID 存储卡片数据，`renderMusicCards()` / `buildMusicCardHtml()` 生成卡片 DOM，`playMusicOnline()` 创建固定底部播放器，`closeMusicPlayer()` 停止并移除
- **日程/闹铃架构**：`schedule.py` 的 `ScheduleManager` 在独立线程运行（30 秒间隔），通过 `run_coroutine_threadsafe` 桥接主事件循环执行 DB 操作和 WebSocket 广播；`_fire_alarm` 复用 camera.py 相同的 Core 唤醒模式（世界书前缀+记忆+历史+触发提示）；`_parse_dt` 支持 6 种日期时间格式，仅日期时默认 09:00
- **日程系统消息**：`_sys_msg()` 辅助函数在日程创建/删除时插入 system 角色消息到当前对话，风格与哨兵唤醒消息（📷）一致，使用 📅/🗑️ 图标前缀
- **AionPushService 架构**：前台服务使用 OkHttp 4.12.0 维持独立 WebSocket 连接，与 WebView 内的 JS WebSocket 并行但互不干扰。通知通过 `NotificationManager` 发送，渠道 ID 区分优先级。心跳线程是纯 Java `Thread`（非 HandlerThread），`Thread.sleep()` 不依赖 Android Looper 消息队列，锁屏后仍能正常唤醒
- **推送与前端 WebSocket 的关系**：Service 的 WebSocket 仅用于接收消息并弹通知，不做任何 UI 操作。WebView 内的 JS WebSocket 负责完整的 UI 交互。两条连接同时连到服务端 `/ws`，`ConnectionManager.active` 列表中会有两个客户端
- **高德定位架构**：`location.py` 独立模块，`process_heartbeat(lng, lat, accuracy, is_gcj02, skip_sentinel)` 为核心入口。`skip_sentinel` 参数用于测试脚本避免触发哨兵通知。所有高德 API 调用使用 httpx 异步请求，Key 从 `data/location_config.json` 读取
- **WGS84→GCJ-02 坐标转换**：`wgs84_to_gcj02()` 实现完整的国测局加密偏移算法（含 Krasovsky 椭球参数），中国境内坐标最大偏移约 500-700 米。Android 端不做转换，统一由服务端处理
- **三级心跳研判**：`process_heartbeat` 维护 `last_api_lng/lat` 跟踪上次 API 调用的坐标，通过 Haversine 距离判断是否显著移动（≥`movement_threshold` 500m）。轻量级处理零 API 消耗，刷新级消耗 2 次 API（逆地理+天气），完整级额外消耗 1 次 AI 调用（哨兵通知）
- **状态机防误触**：家坐标为 (0,0) 或未设置时保持 `unknown` 状态不做研判；每次心跳先算距离再判状态，状态切换必须经过完整级处理
- **哨兵通知**：`_notify_sentinel()` 调用 `gemini-3.1-flash-lite-preview`，注入世界书人设 + `chat_status.json` 聊天状态 + 记忆召回 + 详细位置上下文（距离/地址/天气），生成自然语言通知消息
- **POI 按需搜索**：`perform_poi_check()` 模式同 `perform_cam_check()`：异步执行，使用最新缓存坐标重新逆地理编码 + POI 搜索 → 构建 system 消息 → 调用 Core 生成跟进回复 → 插入对话 + WebSocket 广播
- **Android 定位线程**：`AionPushService` 中 `startLocationThread()` 启动独立 Java Thread（非 HandlerThread），`Thread.sleep(10min)` 循环，每次先 GET `/api/location/config` 检查 `active` 字段，`active = enabled && !is_location_quiet_hours()`，false 时完全跳过 GPS 采集
- **定位 UI**：chat.html 设置面板中「📍 定位追踪」为可折叠区块（默认收起），监控日志弹窗底部增加「📍 缓存定位」调试行（显示坐标/状态/地址/精度/更新时间）
- **POI 搜索指示器**：前端 `poiSearchMsgId` + `poiSearchCategories` 全局变量跟踪，`handlePoiSearch()` 创建蓝色弹跳动画指示器（样式同 cam-check 绿色），45 秒安全超时自动消失，新 assistant 消息到达时自动移除
- **前台服务类型扩展**：`AndroidManifest.xml` 中 `foregroundServiceType="dataSync|location"`，`startForeground()` 传入 `FOREGROUND_SERVICE_TYPE_DATA_SYNC | FOREGROUND_SERVICE_TYPE_LOCATION`，同时声明 `ACCESS_FINE_LOCATION` + `ACCESS_COARSE_LOCATION` + `ACCESS_BACKGROUND_LOCATION` 权限
- **服务端广播兼容**：`ws.py` 的 `broadcast()` 使用 `try/except` 逐连接发送，单个连接异常不影响其他连接。新增 `except Exception` 兜底确保 RST/EOF 等异常也能清理死连接

## 踩坑记录 & 经验教训（Android 推送服务）

> 以下是开发 AionPushService 过程中遇到的所有坑和最终解决方案，务必参考避免重复踩坑。

### 坑 1：权限弹窗被 finish() 秒杀
**现象**：安装后不弹通知权限请求和电池优化引导。
**原因**：`requestPermissions()` 和电池优化 Intent 放在 `LauncherActivity` 中，但 `launchWebView()` 执行完 `startActivity(WebViewActivity)` 后紧接着 `finish()`，Activity 销毁了弹窗来不及显示。
**解决**：权限请求和电池优化引导移到 `WebViewActivity.onCreate()` 中，该 Activity 会一直存活。
**教训**：**不要在即将 finish() 的 Activity 中请求权限或弹系统对话框。**

### 坑 2：Android 14 (targetSdk 34) startForeground 崩溃
**现象**：Service 启动后立即崩溃（`MissingForegroundServiceTypeException`）。
**原因**：targetSdk 34 要求 `AndroidManifest.xml` 声明 `android:foregroundServiceType`，且 `startForeground()` 调用时必须传入 serviceType 参数。
**解决**：Manifest 中 `<service>` 标签添加 `android:foregroundServiceType="dataSync"`，`startForeground(id, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC)`。
**教训**：**targetSdk ≥ 34 的前台服务，Manifest 声明和 startForeground 调用都要带 serviceType。**

### 坑 3：WebSocket close() 触发 onClosed 导致重连死循环
**现象**：App 打开后通知栏疯狂弹"连接成功"，一秒一次。
**原因**：`connectWebSocket()` 中先 `oldWs.close()` 关闭旧连接 → 旧连接的 `onClosed` 回调触发 `scheduleReconnect()` → 又调 `connectWebSocket()` → 无限循环。
**解决**：
  ① 引入 `wsGeneration` 计数器，每次新建连接 generation++，旧连接的回调检查 generation 不匹配则直接 return
  ② 关闭旧连接改用 `cancel()` 而非 `close()`，`cancel()` 不会触发 `onClosed` 回调
  ③ `onStartCommand` 中检查 `wsConnected` + URL 是否变化，已连接则跳过
**教训**：**OkHttp WebSocket 的 `close()` 会触发 `onClosed` 回调，如果回调里有重连逻辑则必须做状态保护。用 generation 计数器是最可靠的方式。**

### 坑 4：HandlerThread Looper 被国产 ROM 冻结
**现象**：App 在前台一切正常，但锁屏/切后台后 WebSocket 静默断开，收不到任何消息。常驻通知栏始终显示"在线"，没有任何错误。
**原因**：`HandlerThread` 使用 Android 的 `Looper` 消息队列派发消息，vivo/OPPO/华为等国产 ROM 会在锁屏后冻结非活跃 App 的 Looper 消息分发（即使是前台服务的 HandlerThread 也不例外）。`handler.postDelayed()` 的心跳回调被冻结，永远不执行，WebSocket 断了但无人知晓。
**解决**：用纯 Java `Thread` + `Thread.sleep()` 替代 `HandlerThread` + `Handler.postDelayed()`。`Thread.sleep()` 是 OS 级线程休眠，不经过 Android Looper，国产 ROM 不会冻结前台服务的普通 Java Thread。
**教训**：**在国产 Android ROM 上，前台服务中需要可靠定时执行的逻辑，不要用 Handler/Looper/AlarmManager，直接用 Java Thread + Thread.sleep() 最可靠。**

### 坑 5：onFailure 阻塞 OkHttp 回调线程
**现象**：WebSocket 断线后一直不重连。
**原因**：`onFailure` 回调中直接调 `Thread.sleep()` 做退避等待，阻塞了 OkHttp 的回调线程，导致后续所有 WebSocket 事件无法分发。
**解决**：`onFailure` 中仅设置状态标志（`wsConnected = false`），不做任何阻塞操作。重连逻辑交给独立的心跳线程统一管理。
**教训**：**OkHttp WebSocket 的 onOpen/onMessage/onClosing/onClosed/onFailure 回调都在内部线程执行，绝对不要在回调里做阻塞操作（sleep/网络请求/锁等待）。**

### 坑 6：WakeLock + WiFi Lock 缺失导致锁屏断连
**现象**：锁屏几分钟后 WebSocket 断开（即使心跳线程正常运行）。
**原因**：Android 锁屏后 CPU 进入深度睡眠（Doze），WiFi 芯片也休眠。OkHttp 的网络 I/O 线程虽然在 sleep 中，但 socket 读写操作被阻塞。
**解决**：Service `onCreate()` 中获取 `PowerManager.PARTIAL_WAKE_LOCK`（保持 CPU）+ `WifiManager.WifiLock(WIFI_MODE_FULL_LOW_LATENCY)`（保持 WiFi），`onDestroy()` 中释放。
**教训**：**前台服务 + WebSocket 长连接，WakeLock 和 WiFi Lock 是必须的，缺一不可。FULL_LOW_LATENCY 比 FULL_HIGH_PERF 更省电。**

### 坑 7：覆盖安装不弹新权限请求
**现象**：更新 APK 后覆盖安装，新增的 `POST_NOTIFICATIONS` 权限不弹请求。
**原因**：Android 覆盖安装时不会重新触发 runtime 权限请求，之前没有授权的权限依旧没有。
**解决**：先卸载旧 app 再安装新 APK，或者在代码中 `onCreate()` 动态检查 `checkSelfPermission()` + `requestPermissions()`。
**教训**：**开发阶段每次改权限后，一定先卸载再装。发布后靠代码动态检查。**

### 坑 8：vivo 电池策略默认杀后台
**现象**：所有代码逻辑正确，但 vivo 手机上锁屏后仍然收不到消息。
**原因**：vivo OriginOS 默认开启"智能后台管理"，会冻结或杀掉后台 app 的进程（包括前台服务）。
**解决**：手机设置 → 电池 → 后台耗电管理 → 找到 Aion Oloth → 改为"不限制后台"（关闭智能管理）。
**教训**：**国产 ROM（vivo/OPPO/小米/华为）的电池优化会无视前台服务权限直接冻结进程。必须在 app 内引导用户关闭电池优化（`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` + 手动设置）。这是所有国产安卓推送的终极大坑。**

### 坑 9：服务端 except WebSocketDisconnect 不够
**现象**：手机 WebSocket 被杀后，服务端 `ConnectionManager.active` 列表中残留死连接，广播消息发到死连接上失败但不清理。
**原因**：网络异常断开（RST 包）抛 `RuntimeError` 或 `ConnectionResetError`，不是 `WebSocketDisconnect`。
**解决**：`except Exception` 兜底 + `finally: manager.disconnect(ws)` 确保任何原因断开都清理。
**教训**：**WebSocket 端点的异常处理不要只 catch 特定异常，用 `except Exception` + `finally` 确保连接清理。**

### 坑 10：CLI 管线图片不能用 base64 内嵌
**现象**：用户在 Aion 私聊（Gemini CLI）和 Connor 私聊/群聊（Codex CLI）发送图片时报错。Gemini CLI: `Separator is not found, and chunk exceed the limit`；Codex CLI: `Input exceeds the maximum length of 1048576 characters`。
**原因**：CLI 工具通过 stdin 管道接收 prompt，有长度限制（Codex CLI 明确 1MB 上限）。一张普通照片 base64 编码后几百 KB 到几 MB，直接内嵌必然超限。而 Gemini 原生 API 通过 HTTP POST JSON body 传输，几乎无大小限制，所以同样的 base64 方式在 API 调用中没问题。
**解决**：CLI 管线改为传本地文件绝对路径，让 CLI 自行读取文件。API 管线（硅基流动/Gemini 原生）保持 base64 不变。
**教训**：**不同 AI 调用方式对输入大小的限制不同。CLI stdin 有长度上限，不能简单复用 API 的 base64 方案。CLI 工具原生支持读取本地文件路径，应该利用这个能力。**

### 坑 11：`fetch_merged_timeline` 的 room_id 参数语义混淆
**现象**：Connor 私聊窗口合并时间线查询不到任何群聊消息，只能看到自己的私聊历史。
**原因**：`fetch_merged_timeline(who, limit, room_id=room_id)` 中的 `room_id` 参数用于指定**群聊房间**ID，但 `build_connor_1v1_prompt` 错误地传入了 1v1 私聊的 room_id。函数内部用这个 room_id 去 `chatroom_rooms` 表查 `type='group'` 的房间，自然查不到。
**解决**：Connor 1v1 调用时不传 `room_id`，让函数自动查找最新的群聊房间。
**教训**：**函数参数语义不明确时容易误传。`room_id` 这个参数名无法区分是私聊房间还是群聊房间，应该在文档/注释中明确标注参数用途。**

### 坑 12：Connor 群聊管线手动转纯文本丢失附件
**现象**：Connor 群聊回复时看不到用户发送的图片，即使 `_build_cli_prompt` 已经支持附件处理。
**原因**：`_reply_connor` 在调用 `stream_connor_cli` 之前，先把 `connor_history`（含 attachments）手动转为纯文本字符串（遍历 content 拼接），然后 `stream_connor_cli(prompt_text)` 再包装成 `[{"role": "user", "content": text}]`。附件信息在手动转文本这一步就已丢失，`_build_cli_prompt` 的附件处理逻辑永远触发不到。
**解决**：`stream_connor_cli` 新增 `messages` 参数，`_reply_connor` 直接传 `connor_history`（保留 attachments），跳过手动转文本步骤。
**教训**：**修复底层函数（`_build_cli_prompt`）时，必须检查整条调用链是否有中间层把信息提前丢弃了。"数据在到达修复点之前就已经丢失"是很隐蔽的 bug。**

### 最终技术方案总结
| 组件 | 技术选型 | 关键参数 |
|------|---------|---------|
| WebSocket 客户端 | OkHttp 4.12.0 | connectTimeout=15s, pingInterval=30s |
| 心跳机制 | Java Thread + Thread.sleep | 间隔 45s, 健康超时 120s |
| 保活 | PARTIAL_WAKE_LOCK + WIFI_MODE_FULL_LOW_LATENCY | onCreate 获取, onDestroy 释放 |
| 重连策略 | 指数退避 3s→30s + NetworkCallback 即时重连 | onAvailable 触发 |
| 防重连风暴 | wsGeneration 计数器 + cancel() | 旧回调自动失效 |
| 自复活 | onTaskRemoved + AlarmManager.setExactAndAllowWhileIdle | 3 秒后重启 |
| 前台服务类型 | dataSync &#124; location | targetSdk 34 必须声明，location 用于 GPS 采集 |
| 通知 | 3 渠道分级 | keepalive(LOW) / messages(DEFAULT) / alarm(HIGH) |

## 启动方式
```bash
# 方式一：双击启动脚本
双击 一键启动.bat

# 方式二：命令行
cd aion-chat
python main.py

服务监听 0.0.0.0:8080

访问地址

踩坑记录 & 最终方案

手机端麦克风（getUserMedia vs 原生录音）

远程 ASR 消息发送失败

Gradle 构建

Android 全面屏适配

更新日志

2026-05-10 — CLI 图片管线修复 + Connor 跨窗口上下文 + 多场景群聊集成

2026-05-09 — 统一时间线上下文 + 统一记忆总结

2026-05-08 — Gemini CLI 本地调用接入

2026-04-08 — UI 多页面拆分重构

2026-04-08 — 后台消息保障 + 子页面 iframe 浮层（防切页丢消息/TTS 中断）

动态壁纸（独立显示器全屏壁纸 + AI 气泡）

动态壁纸工作流程

注意事项