企业官网建设流程全解析

Akagi架构深度解析:抓包、协议桥接与事件总线如何驱动实时分析

【免费下载链接】Akagi支持雀魂、天鳳、麻雀一番街、天月麻將，能夠使用自定義的AI模型實時分析對局並給出建議，內建Mortal AI作為示例。 Supports Majsoul, Tenhou, Riichi City, Amatsuki, with the ability to use custom AI models to analyze games in real time and provide suggestions. Comes with Mortal AI as a built-in example.项目地址: https://gitcode.com/gh_mirrors/ak/Akagi

Akagi 是一款开源实时麻将 AI 辅助工具，支持雀魂、天凤、麻雀一番街、天月麻将等多个平台，能对牌局进行实时分析并给出切牌建议。本文从架构视角拆解 Akagi：抓包层如何截获对局数据、协议桥接如何把各家私有协议统一为 MJAI 标准事件、事件总线如何把数据分发给各子系统，最终驱动毫秒级的实时分析并呈现在 HUD 悬浮窗上。即使你从未写过代码，也能通过这条数据流水线理解实时 AI 辅助工具的工作原理。

⚡ 一、Akagi 整体架构：一条从牌局到建议的数据流水线

概括地说，Akagi 的数据流是一条单向流水线：

游戏客户端 → 抓包截获 → 协议桥接解析 → 事件总线分发 → 状态跟踪 → 实时分析 → HUD 展示

其中四个核心模块各司其职：

• 抓包层（src/capture/）：拿到游戏客户端发出的最原始二进制数据帧；
• 协议桥接层（src/bridge/）：把不同平台的私有协议翻译成统一的 mjai 事件；
• 事件总线（src/event_bus.rs）：把事件广播给所有需要的子系统，实现模块解耦；
• 分析引擎（src/analysis/）：订阅事件，实时计算向听、听牌、和牌率、放铳风险等指标。

下游所有模块（AI 机器人、历史记录、前端 HUD）都只依赖事件流，彼此互不感知，这正是 Akagi 架构优雅的核心。

🔍 二、抓包层：两种方式截获对局数据流

Akagi 提供两套完全独立的抓包后端，共用同一个抽象接口，用户可自由切换。

MITM 代理模式：零侵入的系统代理抓包

第一种方式是 MITM 中间人代理（src/capture/hudsucker_backend.rs）：用户把系统代理指向 Akagi 内置的本地代理，并信任它生成的根证书，游戏流量就会经过 Akagi。代理截获 WebSocket 数据帧后送入解析流程，整个过程不需要修改游戏客户端。

Chromium 内置浏览器模式：CDP 协议抓包

第二种方式是内置浏览器模式（src/capture/chromium/）：Akagi 直接启动一个 Chromium 系浏览器，通过 Chrome DevTools Protocol（CDP）监听 WebSocket 帧。这种方式无需设置代理、无需安装证书，对新手更友好，适合不想动系统网络设置的用户。

统一后端接口与帧路由

两个后端都实现同一个CaptureBackend特征，上层完全感知不到差异。帧的路由也完全一致：

WS 数据帧 →FlowBridges按连接分配桥接实例 → 协议桥接解析 → 发布到事件总线

值得一提的是，两个后端不仅记录 WebSocket 帧，还会记录 HTTP 流量（如版本接口、CDN 地址），供调试面板分析使用。

🔗 三、协议桥接：把异构平台协议统一成 MJAI 事件

不同麻将平台的数据格式千差万别：雀魂是 protobuf 二进制、天凤是 JSON、麻雀一番街是带二进制头的 JSON。协议桥接层（src/bridge/）的存在，就是为了把这些差异统统抹平。

Bridge 特征：双向翻译

桥接层定义了一个极简的Bridge特征，只有两个方法：

• parse：把收到的原始字节翻译成零个或多个 mjai 事件（入站）；
• build：把 AI 的指令翻译回平台原生格式（出站，用于自动打牌）。

其中 mjai 事件定义在src/schema/mjai/，是全项目共享的"通用语言"——桥接输出它、AI 机器人消费它、前端 HUD 展示它。

三大平台桥接实现

• 雀魂（src/bridge/majsoul/parser.rs）：解析 lq 系列 protobuf，按官方 liqi.proto 的 5 层线格式解包，再通过状态机还原为牌局事件；
• 天凤（src/bridge/tenhou/）：纯 JSON 协议，解析直接且天然支持双向；
• 麻雀一番街（src/bridge/riichi_city/）：JSON 外包一层 15 字节二进制头，目前为观察模式。

📡 四、事件总线：实时分析背后的"神经中枢"

如果说抓包是眼睛、桥接是翻译官，那么事件总线（src/event_bus.rs）就是 Akagi 的神经中枢——所有数据都经由它流转。

八条总线各司其职

Akagi 在启动时一次性创建八条广播总线：MjaiBus（桥接解析出的所有牌局事件）、PostTrackerBus（状态跟踪后的精炼事件）、AnalysisBus（分析结果）、BotResponseBus（AI 建议）、BotStatusBus（机器人状态）、CaptureStatusBus（抓包状态）、HistoryBus（历史记录）、NotifyBus（通知）。生产者和消费者通过总线解耦，新增一个子系统只需订阅对应总线，无需改动现有代码。

缓冲策略：宁可丢帧也不阻塞

总线采用固定容量的广播通道（DEFAULT_CAPACITY为 1024）。关键设计是：慢消费者会丢帧，但绝不会拖慢生产者。对实时分析器来说，如果 HUD 跟不上节奏，宁可丢弃旧事件重新同步，也不能让代理阻塞——这正是实时系统的取舍智慧。

PostTrackerBus 与 can_act 的小心思

PostTrackerBus上的每个事件都附带一个can_act字段，标明"当前是否轮到我们的座位行动"。这个标记跟随事件一起传递，而不是事后去查状态机，从而避免了"AI 推理期间状态已前进"的竞态问题——细节之处见功力。

🧠 五、实时分析引擎：毫秒级给出打牌建议

游戏状态跟踪器

分析之前，需要一份"可信的当前局面"。游戏状态模块（src/game_state/）封装了开源的立直麻将引擎 riichienv-core：事件流先经过GameTracker更新内部状态，再生成一份标准化的快照。四人和三人的规则差异也在这里处理。

分析流水线

分析执行器（src/analysis/runner.rs）订阅PostTrackerBus，每收到一个事件就执行一轮完整分析：

取快照 → 定位我方座位 → 生成手牌输入 → 运行分析引擎 → 缓存结果 → 广播到AnalysisBus

得益于 Rust 的性能，一次 13 张牌的状态分析仅需约200 微秒，14 张牌的切牌搜索也不到1 毫秒——完全跟得上实时节奏。

输出哪些指标

分析结果包含：向听数、有效牌、听牌张数、和牌率、听牌率、各家放铳风险、推荐切牌等，通过 IPC 转发到前端 HUD 悬浮窗实时展示，同时也会发送给 AI 机器人供其决策。

✅ 六、总结

Akagi 的架构可以用一句话概括：用抓包获取数据，用桥接统一协议，用事件总线分发消息，用分析引擎驱动决策。四个模块各司其职、通过事件流松耦合协作，使得"支持多平台"与"可插拔自定义 AI 模型"成为可能。理解了这条流水线，你再看 Akagi 的任何功能——从 HUD 提示到 AI 托管、从对局回放到自动打牌——都能一眼看穿它背后的数据流动。对于想研究实时 AI 辅助工具设计、或打算接入自己 AI 模型的开发者来说，这份架构无疑是绝佳的参考范本。

【免费下载链接】Akagi支持雀魂、天鳳、麻雀一番街、天月麻將，能夠使用自定義的AI模型實時分析對局並給出建議，內建Mortal AI作為示例。 Supports Majsoul, Tenhou, Riichi City, Amatsuki, with the ability to use custom AI models to analyze games in real time and provide suggestions. Comes with Mortal AI as a built-in example.项目地址: https://gitcode.com/gh_mirrors/ak/Akagi