Soul of Waifu Companion事件驱动架构剖析:如何在桌面上创造一个会自主行动的AI
Soul of Waifu Companion事件驱动架构剖析:如何在桌面上创造一个会自主行动的AI
Soul of Waifu 的 Companion(桌伴)是一款运行在你桌面上的自主 AI 伴侣:它会观察你的屏幕、主动找你说话、甚至代你操作电脑。这篇文章从源码层面剖析它的事件驱动架构——事件总线、神经激素系统、LLM 决策循环与工具链,带你看看一个"会自主行动的 AI"是如何在工程上实现的。
一、Soul Companion 是什么:住在桌面上的 AI 伴侣
Soul of Waifu 的核心理念是"给你的角色注入灵魂"。除了常规的沉浸式聊天和 RPG 冒险,它还有一个独特模块——Soul Companion:一个无框、置顶的透明桌面浮层,你的 Live2D/VRM 角色会以"居民"的身份陪伴你工作、游戏、刷网页。
它与"一问一答"的聊天机器人最大的区别在于:它不需要你先开口。当你切换窗口、离开座位、或者只是过了几分钟,它都可能主动做出反应——说一句心里话、换个表情、甚至提醒你去喝口水。
Companion 模式可以在调用方式中一键切换(无框桌面浮层,始终位于其他窗口之上),相关入口在 custom_widgets.py 中定义,整体介绍见 README.md 的 "Soul Companion — Autonomous Desktop Agent" 一节。
二、事件驱动架构总览:一个事件总线串联一切
整个 Companion 的心脏在 soul_companion.py 中,其中 SoulCompanionEventBus 是架构的关键。它的设计非常经典:
| 组件 | 作用 |
|---|---|
| 独立守护线程 | 跑一个专属的 asyncio 事件循环,与 Qt 主线程彻底隔离 |
| asyncio.Queue | 所有事件(带类型、负载、时间戳)统一排队 |
emit_threadsafe() |
任何线程(GUI 线程、回调线程)都能安全投递事件 |
| 消费协程 | _event_loop() 以 2 秒超时轮询队列,逐个交给 _handle_event() 处理 |
为什么值得这样设计?
- 线程安全:Qt 主线程的定时器、语音识别回调、工具执行线程,全都通过
emit_threadsafe()把消息"扔进队列",决策逻辑只在单条事件循环里串行执行,天然避免竞态。 - 解耦:事件"生产方"(传感器、定时器、用户操作)完全不知道"消费方"是谁,新增一种事件只需扩展事件类型,不用改动主循环。
- 优雅停机:
stop()时向队列投递一个shutdown事件,循环收到后干净退出。
系统内流转的事件类型大致如下:
| 事件 | 触发源 | 含义 |
|---|---|---|
startup |
启动宽限期结束(25 秒) | 生成一条"自然"的开场问候 |
vad_trigger |
语音识别(VAD + ASR) | 用户说话了 |
user_click |
点击角色浮层 | 用户"戳"了一下 AI |
os_context |
OS 轮询 + 4 秒防抖 | 前台窗口标题变了 |
heartbeat_proactive |
30 秒心跳定时器 | 主动行为的"心跳" |
idle_away / idle_return |
空闲检测(5 分钟阈值) | 用户离开 / 回来 |
tool_complete |
工具执行完毕 | 把工具结果重新喂回决策循环 |
manual_screenshot / manual_clipboard / manual_scratchpad |
用户手动按钮 | "看看我的屏幕 / 读剪贴板 / 说说你在想什么" |
shutdown |
系统停止 | 优雅退出 |
三、事件的来源:四类"传感器"
SoulCompanion 在 start() 中启动了 4 个 Qt 定时器,相当于给 AI 装上了 4 组"感官器官"。
1. 屏幕感知:OS 轮询 + 防抖 + 隐私过滤
每 20 秒,_qt_poll_os() 会读取前台窗口标题。三个细节让这个过程既灵敏又克制:
- 去重:标题没变就跳过,不产生事件;
- 隐私过滤:标题含 password、bank、login 等敏感关键词(多语言关键词表)时直接忽略,避免"密码管理器开着,AI 突然插嘴"的尴尬;
- 4 秒防抖:_os_debounce_coro() 等待 4 秒,若期间你又切走了窗口就取消事件——只有你"稳定地"停在新窗口上,AI 才会注意到。
2. 心跳:两层门控的主动行为
每 30 秒触发一次 _qt_heartbeat(),它采用**双门控(Two-Gate)**策略决定是否"主动开口":
- 第一道门(启发式):按优先级判断——有到期的"承诺任务"(最高优先级)> 孤独值过高(40% 概率)> 随机灵感(25% 概率);否则直接静默返回,零成本。
- 第二道门(策略):_can_speak() 检查 AI 是否在"睡觉"、距上次说话是否超过冷却期(默认 5 分钟,可在浮层菜单里调成 3~60 分钟)、以及是否正在听你说话。
这套门控的意义在于:主动行为在绝大多数心跳里根本不消耗一次 LLM 调用,既省 token 又不会聒噪。
3. 用户交互:说话、点击、离开
- 语音(VAD 触发)→ on_user_spoke():提升催产素/多巴胺并投递
vad_trigger; - 点击角色 → on_user_click():随机触发一个俏皮表情(amused / excited / playful…);
- 离开 5 分钟后再回来 →
idle_return,AI 会感知到你"回来啦"。
4. 手动触发按钮
GUI 浮层提供三个按钮(见 sow_system_signals.py),直接调用 event_bus.emit_threadsafe() 注入事件——这正体现了事件驱动的优势:用户交互与自主行为走的是同一条管道,下游决策逻辑无需区分"这话是谁触发的"。
四、神经激素系统:让 AI 拥有"身体状态"
多数 AI 伴侣的"情绪"只是提示词里的一句话,而 Soul of Waifu 把内环境做成了一个真实的动力学模型——NeurohormoneSystem。
它维护四种 0~1 的"激素"水平,各自拥有独立的时间常数:
| 激素 | 角色 | 动态规则 |
|---|---|---|
| Oxytocin 催产素 | 与你的亲密感 | 你活跃时缓慢上升,闲置时每分钟衰减 0.008 |
| Dopamine 多巴胺 | 兴趣与兴奋 | 收到新 OS 事件 +0.08,闲置时衰减 |
| Cortisol 皮质醇 | 压力 | 被你打断说话 +0.05,随时间衰减 |
| Energy 能量 | 精力值 | 说话耗 0.06 / 思考耗 0.03,闲置恢复 0.025/分钟 |
由此涌现出两个关键状态:
- 睡眠:能量低于 0.05 会"睡着"(不再主动说话),回到 0.20 才醒来;
- 孤独:催产素跌破 0.25 时被判定"孤独",心跳第一道门就会给它更高的主动开口概率。
每 60 秒 _qt_hormone_tick() 推进一次模拟,再用 EmotionState 通过 EMA 指数平滑把激素值映射为 10 种离散情绪(warm、sleepy、melancholy、excited…),驱动头像表情变化。配套还有:
- Scratchpad:最多 8 条"内心独白"小抄,持久化到
.soul/{角色}/companion/scratchpad.json,AI 的inner_thought会写进去,下次对话时又成为提示词的一部分——**跨事件的"记忆"**就此形成; - GoalsManager:当 AI 说出"I'll check later / 我回头提醒你"这类承诺(用正则模式识别并换算到期时间),会写入
goals.json,心跳轮询到期后强制优先触发一次"兑现承诺"。
激素状态还会随配置持久化(保存/加载并补算离线衰减)——你关掉程序去睡觉,第二天回来时,她的催产素确实"降了一整夜"。
五、决策循环:一个事件如何变成 JSON 行动
这是整个架构最精彩的部分。每当事件被消费,_handle_event() 会先做两件事:
- 检查是否有反应式插件订阅了该事件(
subscribes_to机制),有则并行执行; - 组装提示词,调用 LLM。
_call_companion() 把当前全部"身体状态"注入 COMPANION_SYSTEM_PROMPT:激素数值、当前情绪、Scratchpad、最近 5 轮对话、记忆快照(MEMORY.md + USER.md + 主题 RAG)、可用工具清单、事件上下文。随后 LLM 以流式方式输出一段严格 JSON,包含:
{
"thought": "深度推理……",
"action": "speak|idle|micro_react|inner_thought|use_tool",
"emotion": "warm",
"hormonal_delta": { "oxytocin": 0.05, "energy": -0.06 },
"spoken_response": "(当 action 为 speak 时的台词)"
}
五个 action 构成一个极简的行为决策空间:开口说话、保持沉默、只做表情微反应、写内心独白、调用工具。这里有两个工程亮点:
① 流式句子级 TTS。StreamingCompanionParser 是一个手写状态机,在 JSON 流还没生成完时,就实时截取出 spoken_response 字段,按句送去 TTS——第一句话的声音不用等整个响应结束,显著压低"开口延迟"。
② 工具调用闭环。当 action 是 use_tool,_execute_tool() 执行后会把结果包成 tool_complete 事件重新塞回事件队列,让 AI 基于真实结果再决策一次(比如"搜到了 → 组织语言告诉你")。防失控靠两条保险丝:链式深度上限 10 步,以及"连续两次相同工具调用"的循环检测,触发后强制转为 speak。
本地模型的选择可以在 Models Hub 中完成,ModelsHub.py 相关源码:
六、工具体系与插件:让 AI 真正"动手"
所有能力都抽象为继承 BaseTool 的工具类,统一提供 name、description、JSON Schema 和 execute()。PluginLoader 负责装配:
- 8 个内置工具:媒体控制、网页搜索(ddgs → Brave → SearXNG 三级回退)、打开网址、系统时间、硬件规格、截图、剪贴板读取、应用管理(AppControlTool 支持开/聚焦/关闭 Windows 应用);
- 用户插件:在 app/utils/soul_companion/plugins/ 目录放入一个继承 BaseTool 的 Python 文件即可热加载,仓库甚至会自动生成带注释的示例插件模板(含如何给角色换表情、播台词的示范);
- MCP 服务器:通过 MCPManager 接入任意外部 MCP 工具,其 schema 会被动态合并进提示词。
真正让 Companion 从"聊天"升级为"Agent"的,是 agentic_tools.py 中的一组 Agentic 工具:
| 工具 | 能力 |
|---|---|
gui_action |
移动鼠标、点击、打字、快捷键、滚轮——GUIActionTool 可"操作任意窗口" |
| Browser Agent | 无头浏览器自主导航、提取正文、填表、下载 |
| Code Execution | 沙箱内运行 Python/PowerShell 脚本,带超时保护 |
| File Organizer | 扫描桌面并自动归类文件 |
| Task Planner | 把复杂口头目标拆成多步工具链(plan_and_execute) |
| System Vitals | 监控低电量、GPU 过热、下载完成并主动提醒 |
值得注意的防护:_is_protected_path() 把 C:\Windows、Program Files、AppData\Microsoft 等目录设为禁区,文件操作默认拒绝碰系统路径。
七、安全设计:Human-in-the-Loop 审批横幅
一个能控制鼠标键盘的 AI,安全是生命线。Soul of Waifu 的答案是审批门 + 超时失败安全(Fail-Safe):
- 每个工具可声明
requires_approval(如 GUIActionTool 除"查询光标位置"外全部需要审批); - 执行前 _gate_approval() 拦截,通过 Qt 跨线程信号 [sc_request_approval_slot] 弹出审批横幅,展示人类可读的操作摘要(如"Force-close 'Steam' (any unsaved work may be lost)");
- 你点确认才执行;27 秒内不回应则自动拒绝(
<a href="https://link.gitcode.com/i/2ece8896a316fad577839fc55406353d" target="_blank">APPROVAL_TIMEOUT_SEC</a>),且拒绝信息会明确告知 AI"用户否决了,别重试"; - 若工具自身抛异常,审批系统会失败安全地默认走审批流程而不是放行。
再叠加前面的隐私关键词过滤、激素睡眠机制(累了就不主动开口)与 5 分钟主动冷却,构成了"有边界感"的 AI 伴侣:它想做事,但始终尊重你的主权。
八、写在最后:这套架构的 5 个可借鉴要点
如果你也想给自己的 AI 应用加上"主动性",Soul Companion 给出了一份相当完整的参考答案:
- 独立线程 + 队列的事件总线:AI 决策与 GUI 生命周期解耦,任何来源的刺激都能以统一格式进入决策循环;
- 两级门控:先用廉价的规则/状态判断拦截大部分心跳,只有值得时才花 LLM 调用;
- 把"人格状态"做成动力学系统:激素衰减、睡眠、孤独、承诺兑现,让行为随时间真实演化,而不是每次对话都"重置";
- 行动空间极简 + 结果回灌:5 个 action + 工具结果重新入队的闭环,配合深度上限和循环检测,简单而可控;
- 默认保守的安全层:审批超时即拒绝、系统路径禁区、敏感窗口标题过滤——自主性与安全性缺一不可。
核心源码索引:
- Companion 核心(事件总线 + 决策循环):soul_companion.py
- Agentic 工具(GUI 控制/浏览器/代码执行):agentic_tools.py
- GUI 集成(TTS/表情/审批槽函数):sow_system_signals.py
- 用户插件目录:plugins/
- 功能总览:README.md
一个"会自主行动的 AI",本质上是传感器 → 事件总线 → 状态模型 → 决策器 → 行动器这条流水线的循环运转。理解了这条线,你就理解了 Soul of Waifu Companion 的全部秘密。




