Soul of Waifu Companion事件驱动架构剖析:如何在桌面上创造一个会自主行动的AI

原创2026-10-12 19:22:061,165 阅读
文章标签:人工智能AI 应用桌面应用本地部署语音AI Agent工具调用MCP ClientsAgent 记忆

Soul of Waifu Companion事件驱动架构剖析:如何在桌面上创造一个会自主行动的AI

Soul of Waifu 的 Companion(桌伴)是一款运行在你桌面上的自主 AI 伴侣:它会观察你的屏幕、主动找你说话、甚至代你操作电脑。这篇文章从源码层面剖析它的事件驱动架构——事件总线、神经激素系统、LLM 决策循环与工具链,带你看看一个"会自主行动的 AI"是如何在工程上实现的。

Soul of Waifu Companion 桌面AI伴侣语音通话界面

一、Soul Companion 是什么:住在桌面上的 AI 伴侣

Soul of Waifu 的核心理念是"给你的角色注入灵魂"。除了常规的沉浸式聊天和 RPG 冒险,它还有一个独特模块——Soul Companion:一个无框、置顶的透明桌面浮层,你的 Live2D/VRM 角色会以"居民"的身份陪伴你工作、游戏、刷网页。

它与"一问一答"的聊天机器人最大的区别在于:它不需要你先开口。当你切换窗口、离开座位、或者只是过了几分钟,它都可能主动做出反应——说一句心里话、换个表情、甚至提醒你去喝口水。

Soul of Waifu 角色库主界面,选择你的AI伴侣

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() 会读取前台窗口标题。三个细节让这个过程既灵敏又克制:

  1. 去重:标题没变就跳过,不产生事件;
  2. 隐私过滤:标题含 password、bank、login 等敏感关键词(多语言关键词表)时直接忽略,避免"密码管理器开着,AI 突然插嘴"的尴尬;
  3. 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。

Soul of Waifu VRM 3D角色模型,情感驱动动画

它维护四种 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() 会先做两件事:

  1. 检查是否有反应式插件订阅了该事件(subscribes_to 机制),有则并行执行;
  2. 组装提示词,调用 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 相关源码:

Soul of Waifu Models Hub 本地LLM模型下载与兼容性检测界面

Soul of Waifu AI伴侣角色扮演聊天演示

六、工具体系与插件:让 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):

  1. 每个工具可声明 requires_approval(如 GUIActionTool 除"查询光标位置"外全部需要审批);
  2. 执行前 _gate_approval() 拦截,通过 Qt 跨线程信号 [sc_request_approval_slot] 弹出审批横幅,展示人类可读的操作摘要(如"Force-close 'Steam' (any unsaved work may be lost)");
  3. 你点确认才执行;27 秒内不回应则自动拒绝(<a href="https://link.gitcode.com/i/2ece8896a316fad577839fc55406353d" target="_blank">APPROVAL_TIMEOUT_SEC</a>),且拒绝信息会明确告知 AI"用户否决了,别重试";
  4. 若工具自身抛异常,审批系统会失败安全地默认走审批流程而不是放行。

再叠加前面的隐私关键词过滤、激素睡眠机制(累了就不主动开口)与 5 分钟主动冷却,构成了"有边界感"的 AI 伴侣:它想做事,但始终尊重你的主权。

八、写在最后:这套架构的 5 个可借鉴要点

如果你也想给自己的 AI 应用加上"主动性",Soul Companion 给出了一份相当完整的参考答案:

  1. 独立线程 + 队列的事件总线:AI 决策与 GUI 生命周期解耦,任何来源的刺激都能以统一格式进入决策循环;
  2. 两级门控:先用廉价的规则/状态判断拦截大部分心跳,只有值得时才花 LLM 调用;
  3. 把"人格状态"做成动力学系统:激素衰减、睡眠、孤独、承诺兑现,让行为随时间真实演化,而不是每次对话都"重置";
  4. 行动空间极简 + 结果回灌:5 个 action + 工具结果重新入队的闭环,配合深度上限和循环检测,简单而可控;
  5. 默认保守的安全层:审批超时即拒绝、系统路径禁区、敏感窗口标题过滤——自主性与安全性缺一不可。

核心源码索引:

一个"会自主行动的 AI",本质上是传感器 → 事件总线 → 状态模型 → 决策器 → 行动器这条流水线的循环运转。理解了这条线,你就理解了 Soul of Waifu Companion 的全部秘密。

登录后查看全文
Soul-of-Waifu