如何为 B 贡献代码:目录结构、模块边界与事件契约完整开发指南
如何为 B 贡献代码:目录结构、模块边界与事件契约完整开发指南
B 是一个用 Python 构建的自主型桌面 AI 伴侣(AI desktop companion):他会实时"看"屏幕、追踪你正在使用的窗口、用本地 ONNX 模型合成语音,并以 60fps 的悬浮表情与你互动。B 最特别的地方在于它的事件总线(EventBus)架构——所有模块之间互不直接调用,全部通过发布/订阅(pub/sub)契约通信。如果你想在 B 上开发新功能、修 Bug 或扩展传感器,理解这套目录结构、模块边界与事件契约,就是第一把钥匙。
认识 B:一个事件驱动的桌面 AI 伴侣
传统助手是"你问我答",而 B 是主动感知型的数字生命:他观察你的工作流、理解当前窗口内容,并选择有价值时才开口。
整个系统的数据流遵循一条确定性管线:感知(Perception)→ 认知(Cognition)→ 表达(Expression)。
想深入了解设计理念,建议先阅读 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 的注释里,这也是贡献者必须遵守的模块边界契约:
- 模块之间永不互相 import。每个模块只认识
EventBus,不知道其他模块的存在; - 所有跨模块通信必须走事件——
bus.publish()发,bus.subscribe()收; 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):
WindowTracker检测到切窗 → 发布active_window_changed;- 语义传感器走 UIA 树提取内容;失败则发布
semantic_extraction_failed,OCR 管线接管; - 内容经 MD5 去重后发布
context_updated; - 认知引擎完成 LLM 推理,逐句发布
b_spoke; - 语音引擎合成并播放,发布
assistant_speaking_start/b_finished_speaking; - 自主引擎在静默后评估是否触发下一次
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 报告需附复现步骤、系统与硬件信息、相关日志(先脱敏)。
新人贡献路线图
- 只读通读:先跑通
python main.py,再对照 docs/ARCHITECTURE.md 把"事件契约表"过一遍; - 从小事件入手:新模块 = 一个订阅者 + 一个发布者。例如给 B 加"剪贴板感知",只需订阅
tick或active_window_changed、发布自定义事件,零侵入现有代码; - 注意优先级:涉及动画/UI 的订阅请设置较小的
priority值,避免被推理类回调拖慢; - 验证线程安全:你的模块若在后台线程运行,直接调用
bus.publish()即可,bus 会自动桥接到主线程,不要自己操作 Qt 控件。
💡 提示:仓库中还有 PRIVACY.md 说明数据采集边界、SECURITY.md 说明安全注意事项,贡献涉及屏幕/音频的功能前请先阅读。
B 的架构像一张精心接线的电路:目录即分层、bus 即契约。当你下一次打开 main.py,看到那行 "Wiring the Soul" 时,你已经知道每一根线该插在哪里了。

