English

组件与模块结构（Components & Module Layout）

服务端的分层与模块归属：核心骨架、双层 component/、ling 作为特殊节点。 这些层级为什么长成这样，见管道演进记录。

核心骨架

数据流/包含层级自上而下：

socket / other → filter → session → round → pipeline → ling
  • socket：传输入口（WebSocket / Matrix）。api/src/ws/、api/src/matrix/
  • filter：入/出站过滤器（MCP 路由、录像）。api/src/ws/filter/
  • session：连接生命周期、phase 状态机、Round 生命周期管理（shadow/upgrade/stop）。 service/src/session/
  • round：每轮对话（用户发言 → 服务端响应），拥有单条 NodeChain。service/src/session/round.rs
  • pipeline：外层节点链（opus→vad→asr→turn→ling→tts），Node/NodeChain/PipelineEvent 框架。service/src/pipeline/
  • ling：决策中枢（特殊节点），接收已识别结果 → 决策 → 产出表达意图。service/src/ling/； 实现位于 api/src/component/ling/

service/src 顶层模块

service/src/
  lib.rs        # pub mod component; pub mod frame; pub mod ling; pub mod message; pub mod pipeline; pub mod session; pub mod types;
  component/    # 引擎契约：vad.rs  asr.rs  tts.rs  llm/{mod,token_converter}.rs  mcp/{mod,registry}.rs
  ling/         # Ling 决策引擎（特殊节点）：Ling trait（ask → OutputBlock stream）
  pipeline/     # Node 框架：mod.rs + nodes/
  session/      # session / round / history；TurnEvent 在 round.rs
  message/      # 传输协议：hello/audio/close/llm/mcp/stt/tts + Message/Type/Transport/AudioFormat
  frame.rs      # Frame / FrameResult / OutputMessage（传输呈现层）
  types.rs      # 共享类型：EmptyKind / Sentence / Input / OutputBlock / ContentBlock

要点：

  • component/ = 引擎契约（trait + 类型），不绑定具体模型；被 pipeline 节点与 ling 引用。
  • ling/ = 仅 Ling trait（决策引擎）。因需判断/处理一切，作为特殊节点必须显式定义全部 可能 node（见下文「Ling 特殊节点」）。
  • types.rs = 跨层共享类型（EmptyKind/Sentence/Input/OutputBlock/ContentBlock），被 pipeline、session、component、api 引用。
  • message/ + frame.rs = 传输协议/呈现层，对应骨架最外层的「socket」。
  • TurnEvent 在 session/round.rs（回合事件属 round 生命周期）。

双层 component

service 与 api 双层各自收拢引擎：

层内容用途关键路径
service component/引擎契约（trait + 协议类型）被 pipeline 节点、ling 引用；不绑定具体模型service/src/component/{vad,asr,tts,llm,mcp}
api component/引擎实现（Manager + model）启动时按配置择模型，实现契约api/src/component/{vad,asr,llm,tts,mcp}
  • 范围只含五引擎：vad / asr / llm / tts / mcp。
  • 依赖方向严格单向：api 依赖 service，service 不依赖 api。
  • Ling 实现 LingCore 位于 api/src/component/ling/，与其它引擎实现同层（对称）。
  • 引擎可独立实例化（composition root 决定挂哪里），并从 component/ 能力 look up 中复用 AudioSpec 等下行情报。

Ling 特殊节点

Ling（service/src/ling/）是决策中枢，作为 pipeline 链上的一个节点（LingNode）工作，但 与普通纯变换节点不同：

  • 它需要判断/处理一切（LLM 流、MCP 工具、历史、切句），因此必须显式定义其内部可能出现的 全部 node。
  • 实现侧是 api/src/component/ling/ 的 LingCore（LLM + MCP + history + splitter 编排），产出 逐句表达意图。

相关文档

  • 核心架构：Session/Round/pipeline 语义
  • 统一管道：单链 + 观察者协议、能力 look up、节点生命周期