如何为 B 贡献代码:目录结构、模块边界与事件契约完整开发指南

原创2026-10-20 23:55:261,982 阅读

如何为 B 贡献代码:目录结构、模块边界与事件契约完整开发指南

B 是一个用 Python 构建的自主型桌面 AI 伴侣(AI desktop companion):他会实时"看"屏幕、追踪你正在使用的窗口、用本地 ONNX 模型合成语音,并以 60fps 的悬浮表情与你互动。B 最特别的地方在于它的事件总线(EventBus)架构——所有模块之间互不直接调用,全部通过发布/订阅(pub/sub)契约通信。如果你想在 B 上开发新功能、修 Bug 或扩展传感器,理解这套目录结构、模块边界与事件契约,就是第一把钥匙。

B 桌面AI伴侣的桌面悬浮界面

认识 B:一个事件驱动的桌面 AI 伴侣

传统助手是"你问我答",而 B 是主动感知型的数字生命:他观察你的工作流、理解当前窗口内容,并选择有价值时才开口。

B 桌面AI伴侣的概念形象:悬浮在桌面上的发光小球机器人

整个系统的数据流遵循一条确定性管线:感知(Perception)→ 认知(Cognition)→ 表达(Expression)。

B 的四大核心能力

想深入了解设计理念,建议先阅读 README.md 与 docs/ARCHITECTURE.md——后者是完整的系统架构清单,从感知管线到音频 DSP 链路都有说明。

目录结构速览:每个模块住在哪里

B 的目录设计非常"职责单一",每个顶层目录对应一层架构:

目录 定位 关键文件 说明
core/ 核心基础设施 core/bus.py EventBus:线程安全的事件总线,B 的"中枢神经"
brain/ 认知层(大脑) brain/llm.py、brain/soul.py、brain/autonomy_loop.py LLM 推理编排、情绪状态机、主动性思考调度
vision/ 视觉感知 vision/semantic.py、vision/mss_capture.py UIA 语义树提取 + OCR 兜底管线
sensors/ 系统感知 sensors/window_tracker.py 基于 Hook 的活跃窗口检测
audio/ 听觉与发声 audio/speaker.py、audio/ears.py Piper ONNX 语音合成(TTS)与 Whisper 语音识别(STT)
physics/ 运动引擎 physics/kinematics.py 贝塞尔路径插值 + 缓动曲线的物理移动
ui/ 悬浮界面 ui/face.py、ui/chat.py、ui/overlay.py 60fps 脸部渲染、聊天气泡、透明点击穿透层
voices/ 语音模型 voices/b_voice.onnx B 的 ONNX 声音模型
scripts/ 工具脚本 scripts/setup_voice.py 模型下载与环境配置
根目录 入口 main.py 启动序列:实例化所有模块并拉起心跳定时器

一个值得注意的细节:main.py 是唯一引用所有模块的地方,而且只为实例化——运行期间任何模块之间都不允许互相调用。

模块边界:贡献代码前先背下三条铁律

B 的解耦策略写在 main.py 的注释里,这也是贡献者必须遵守的模块边界契约:

  1. 模块之间永不互相 import。每个模块只认识 EventBus,不知道其他模块的存在;
  2. 所有跨模块通信必须走事件——bus.publish() 发,bus.subscribe() 收;
  3. main.py 是唯一"接线板":模块在这里被创建并注入 bus,除此之外不写任何跨模块逻辑。

这套边界带来的直接好处:你想给 B 加一个"鼠标活动检测"或"日历提醒"模块时,不需要改动任何现有代码——新建一个类,订阅它关心的事件、发布它产生的事件即可。

事件契约:EventBus 是怎么工作的

EventBus 定义在 core/bus.py,它有三个核心设计:

  • 线程安全:任何后台线程(视觉提取、LLM 推理、音频播放)都可以 publish,bus 会通过 Qt 信号自动把回调跳转回主线程执行,保证 UI 一致;
  • 优先级调度:subscribe(event, callback, priority=100),数字越小越先执行——例如物理引擎订阅 tick 时用了 priority=10,确保高延迟的推理模块不会拖慢动画;
  • 容错隔离:单个订阅者抛异常只会被记录日志,不会波及其他订阅者(见 core/bus.py)。

核心事件契约表

以下是 B 运行时最常被用到的事件,是开发新功能前必查的"字典":

事件 典型发布者 典型订阅者 含义
tick main.py 运动引擎、状态机、脸部渲染 16ms 心跳(约 60fps),携带 dt 时间增量
active_window_changed sensors/window_tracker.py 语义视觉、OCR 视觉 用户切换了活跃窗口
context_updated vision/semantic.py、brain/context.py 认知引擎、自主引擎 屏幕/窗口上下文刷新
semantic_extraction_failed vision/semantic.py vision/mss_capture.py UIA 提取失败,触发 OCR 兜底
user_spoke audio/ears.py、ui/input_box.py brain/llm.py 用户通过语音或输入框说话
b_spoke brain/soul.py、brain/llm.py audio/speaker.py B 说出一句话(携带文本与情绪)
b_thinking / b_finished_thinking brain/llm.py 两个视觉传感器 通知视觉层大脑忙碌/空闲,暂停采集
b_finished_speaking audio/speaker.py 自主引擎、状态机、聊天气泡 播放完成,触发下一步主动性判断
b_move_request brain/llm.py physics/kinematics.py LLM 要求 B 移动到屏幕某坐标
emotion_changed brain/soul.py ui/face.py 情绪变化,驱动表情切换
position_updated physics/kinematics.py ui/overlay.py、ui/chat.py B 的位置变化,气泡跟随
trigger_proactive_thought brain/autonomy_loop.py brain/llm.py 自主引擎决定主动开口
b_work_mode_toggled main.py 状态机、认知引擎、自主引擎 Ctrl+Shift+Alt+W 切换工作模式

一次"从看到说"的完整数据流

把上面的事件串起来,就是 B 的标准工作流(docs/ARCHITECTURE.md):

  1. WindowTracker 检测到切窗 → 发布 active_window_changed;
  2. 语义传感器走 UIA 树提取内容;失败则发布 semantic_extraction_failed,OCR 管线接管;
  3. 内容经 MD5 去重后发布 context_updated;
  4. 认知引擎完成 LLM 推理,逐句发布 b_spoke;
  5. 语音引擎合成并播放,发布 assistant_speaking_start / b_finished_speaking;
  6. 自主引擎在静默后评估是否触发下一次 trigger_proactive_thought。

调试时可以在日志文件 b_analytics.log / b_session.log 中按 B.<module> 前缀过滤出任意模块的行为。

为 B 贡献代码:从 Clone 到提交

一键获取仓库

git clone https://gitcode.com/gh_mirrors/b9/B
cd B
python -m venv venv
pip install -r requirements.txt
python main.py   # 唤醒 B(记得 Ctrl+Shift+Alt+Q 是全局急救开关)

风格规范(来自 CONTRIBUTING)

项目的贡献约定写在 CONTRIBUTING.md,重点有四条:

  • Python 遵循 PEP 8,尽量使用类型注解,复杂逻辑必须写 Docstring;
  • UI 是"灵魂优先":动画保持 60fps 流畅目标,采用玻璃拟态(glassmorphic)设计语言;
  • 绝不在主线程做阻塞操作——重推理和 DSP 放后台线程,UI 线程只负责渲染;
  • Bug 报告需附复现步骤、系统与硬件信息、相关日志(先脱敏)。

新人贡献路线图

  1. 只读通读:先跑通 python main.py,再对照 docs/ARCHITECTURE.md 把"事件契约表"过一遍;
  2. 从小事件入手:新模块 = 一个订阅者 + 一个发布者。例如给 B 加"剪贴板感知",只需订阅 tick 或 active_window_changed、发布自定义事件,零侵入现有代码;
  3. 注意优先级:涉及动画/UI 的订阅请设置较小的 priority 值,避免被推理类回调拖慢;
  4. 验证线程安全:你的模块若在后台线程运行,直接调用 bus.publish() 即可,bus 会自动桥接到主线程,不要自己操作 Qt 控件。

💡 提示:仓库中还有 PRIVACY.md 说明数据采集边界、SECURITY.md 说明安全注意事项,贡献涉及屏幕/音频的功能前请先阅读。


B 的架构像一张精心接线的电路:目录即分层、bus 即契约。当你下一次打开 main.py,看到那行 "Wiring the Soul" 时,你已经知道每一根线该插在哪里了。

登录后查看全文
B