Files
bot042/docs/channel-eventbus-design.md
T
openbot fbb01c4c83 feat: 重构为 agent / channels / flows / db 分层架构
- agent: 新增 base.py 执行基类、execution.py 执行器、web.py 网络工具,
  middlewares/steering.py 中间件;移除旧的 agent.py
- channels: 新增 ChannelManager、registry、models 与 IM 渠道(企业微信),
  扩展 base.py
- flows: 新增 agent_task / bus / cron / scheduler / service / stream / rpc /
  processor / tasks / model_settings / builtin;移除旧的 task.py
- db: 新增 sqlite schema 与 repo 层
- docs: 新增架构说明、Channel × EventBus 设计、任务编写教程
- 依赖新增 aiosqlite / httpx / langgraph / primp / pydantic / ripgrep /
  wecom-aibot-sdk;新增 bot 命令入口
- 测试:232 passed
2026-11-09 20:32:25 +08:00

22 KiB
Raw Blame History

Channel × EventBus 重构设计(含 RPC 扩展)

  • 状态:阶段 1、2 已实施;阶段 3 待做
  • 日期:2026-11-09(阶段 2 实施完成)
  • 范围:src/bot042/channels/、src/bot042/flows/、docs/
  • 目标读者:项目维护者

1. 背景

当前 channels/ 与 flows/ 各自维护了一套完整的消息调度:

  • 通道层:ChannelManager._queues + _worker_loop + _session_locks + _inflight + handle_inbound 里的 processor 异步生成器 + MessageEvent 投递。
  • 编排层:EventBus(on/once/emit)+ TaskRunner(_Slot、overlap、TaskRun、runs/stats)。

两套并存带来的实际问题:

能力 通道层现状 编排层现状 结果
串行 _session_locks(按 subject) _Slot + overlap(按任务) 语义重复且不同,改一处不影响另一处
排队/背压 asyncio.Queue(默认无界) QUEUE 积压上限 1 两个上限,都不适合聊天连发
在途统计 _inflight + wait_idle() runs() / stats() 收尾要分别等待,容易漏
错误口径 MessageEvent.error_event task.failed 事件 两套可观测指标
处理入口 processor 生成器 Task.run() 同一件事两种写法

结论:消息处理逻辑实际上"藏在通道层",EventBus 只服务于脚本任务(tasks/scheduler), 所以两个子系统关联很弱。

2. 设计目标

  1. EventBus 成为唯一分发面:入站消息、出站发送、定时触发、任务结果都通过总线。
  2. channel 退化为协议适配层:连接、解析、发送原语;不再有队列、worker、会话锁、处理器。
  3. 执行统一收敛到 TaskRunner:串行/排队/重试/统计只有一套实现。
  4. 给 EventBus 增加 RPC:请求-响应语义,用来解决"事件化之后拿不到结果"的问题(尤其是发送失败反馈)。
  5. 保持 channels 不 import bot042.flows(依赖方向不变),通过注入回调解耦。

3. 非目标(本轮不做)

  • 跨进程 / 跨机器消息(仍是进程内总线)。
  • RPC 多播聚合、流式响应、双向长连接。
  • 消息合批(batch_window_ms):本轮放弃,留作后续扩展点(见 §15)。
  • 通道 SDK 的重连、ACK、回调线程管理——这些必须留在 channel 内。
  • 持久化消息队列(进程重启丢在途消息,与现状一致)。

4. 总体架构

┌─ 协议适配(channels/)──────────────────────────────────────────────┐
│ BaseChannel: start/stop · parse_inbound · send_text/send_content     │
│              send_typing/send_delta/flush · _known_subjects          │
│                                                                      │
│ 入站唯一出口: publish(InboundMessage)   ← 注入的同步回调              │
│ 出站唯一入口: send_text(...)            ← 被 RPC server 调用          │
│ 没有:队列 / worker / 会话锁 / processor / MessageEvent 流            │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ bootstrap 注入的 publisher
┌───────────────────────────────▼──────────────────────────────────────┐
│ 分发(flows/bus.py + flows/rpc.py)                                   │
│ EventBus: publish / subscribe / once / error 路由 / 线程安全桥        │
│ RpcHub:   serve(method, handler) / await call(method, payload)        │
│ 事件空间: channel.inbound · channel.* · task.* · schedule.* · rpc.*   │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ 订阅 + 分区串行
┌───────────────────────────────▼──────────────────────────────────────┐
│ 执行(flows/tasks.py)                                                │
│ TaskRunner: 每 (task, partition_key) 一条串行链                       │
│ Task: run() 或 build_graph()+ainvoke;deps 注入外部服务                │
└──────────────────────────────────────────────────────────────────────┘

启动装配(伪代码):

bus = EventBus()
bus.bind_loop()

registry = ChannelRegistry()                       # 原 ChannelManager 收缩后
runner = TaskRunner(bus, deps=AppServices(channels=registry, settings=settings))

bus.serve("channel.send", registry.rpc_send)       # 出站 RPC server
publisher = lambda msg: bus.publish_threadsafe("channel.inbound", ChannelMessage.of(msg))
registry.attach_all(publish=publisher)             # 每个 channel 注入 publish

runner.register(AgentReply)                        # 内置任务
runner.add_task("channel.agent", EventTrigger(event="channel.inbound"))
await runner.start()

5. EventBus 扩展

5.1 保持不变的语义

  • emit(fire-and-forget):handler 必须 async;异常路由到 error 事件;不向调用方抛。
  • on/once 注册;wait_for_complete();cancel()。
  • 上一轮已修复的约束:重复注册同一 handler 抛 BusError;handler 同步异常不外泄。

5.2 新增别名

贴合"subscribe / publish"的叫法,纯别名、不改语义:

publish = emit            # 方法别名
subscribe = on
subscribe_once = once

5.3 线程安全桥(必须)

SDK 回调常在工作线程,emit 需要事件循环:

def bind_loop(self, loop: asyncio.AbstractEventLoop | None = None) -> None: ...
def publish_threadsafe(self, event: str, *args: object) -> None:
    """同线程直接 emit;跨线程用 loop.call_soon_threadsafe。未 bind 时抛 BusError。"""

有了它,ChannelManager 的 _queues/_worker_loop/enqueue 才有条件删除。

5.4 RPC 封装(新增 flows/rpc.py)

语义

"有返回值的 publish":调用方 await 拿到响应或异常,超时可控。进程内。

class RpcError(Exception): ...
class RpcTimeoutError(RpcError): ...
class RpcRemoteError(RpcError):     # 远端 handler 抛异常
    remote_type: str
    remote_message: str
class RpcAborted(RpcError): ...     # 总线关闭 / cancel()

RpcHandler = Callable[[object], Awaitable[object]]

class RpcHub:
    def __init__(self, bus: EventBus, *, pending_limit: int = 1000) -> None: ...
    def serve(self, method: str, handler: RpcHandler) -> None: ...
    def unserve(self, method: str) -> None: ...
    def served(self) -> list[str]: ...
    async def call(self, method: str, payload: object = None, *, timeout: float | None = 5.0) -> object: ...
    def abort_all(self) -> None: ...

时序

caller                    EventBus(+RpcHub)                    server handler
  │ call(m, p) ──创建 Future(cid)──► publish("rpc.request",
  │                                   RpcRequest(cid, m, p))
  │                                       │  RpcHub._on_request
  │                                       ├─ 查 method 路由 ──► await handler(p)
  │                                       │                        │
  │                                       │◄── 返回值/异常 ─────────┘
  │                                       ├─ publish("rpc.reply",
  │                                       │     RpcReply(cid, ok, value|error))
  │◄── Future 解析 / 抛错 ◄────────────────┘
  • 只用两个总线事件:rpc.request、rpc.reply,方法名在载荷里路由。 理由:避免动态事件名(rpc.<method>)污染事件空间,也不需要在 EventBus 里加通配订阅。
  • 同一时刻同一 method 只允许一个 server(serve 重复注册报 ValueError)。
  • 默认 first-response-wins:响应到达即完成 Future,后续回复丢弃(单响应者场景已够)。
  • 请求方 timeout 到点:清理 pending 并抛 RpcTimeoutError;迟到响应被忽略。
  • pending 数量超 pending_limit:直接抛 RpcError(防泄漏)。
  • 总线 cancel() / 应用关停:abort_all() 让所有 pending 抛 RpcAborted。
  • 审计(可选,默认关闭):rpc.audit 事件带 method/耗时/结果,避免默认产生噪音。

为什么用 RPC 而不是"两段事件"

普通事件化出站的痛点是发送结果无法回传:任务 emit("channel.send", ...) 之后不知道成功失败。 RPC 让"事件化"与"能拿到结果"同时成立:

# 任务内
await self.deps.bus.call(
    "channel.send",
    OutboundText(channel_id=cid, subject_id=uid, text=answer),
    timeout=10,
)
# bootstrap
async def _send(payload: object) -> object:
    assert isinstance(payload, OutboundText)
    await registry.send_text(payload.channel_id, payload.subject_id, payload.text)
    return {"sent": True}

bus.serve("channel.send", _send)

与 TaskRunner 的关系

RPC 不替代任务触发:task.* / schedule.* / channel.inbound 仍是 fire-and-forget 事件; RPC 只用于"需要结果"的调用(出站发送、配置查询、工具调用代理)。 RpcHub 是 EventBus 之上的薄封装,不引入新的调度器。


6. Channel 层重构

6.1 职责收缩

现有 处置
handle_inbound() 的 processor 事件流(typing/delta/thinking/tool/text/error/completed 投递) 删除,替换为 publish(raw)
_processor / has_processor / attach(processor=) 删除
MessageProcessor / MessageEvent 契约退役(MessageEvent 的投递语义由 §6.3 原语承担)
parse_inbound / _preprocess / _register_subject 保留
_enqueue_callback / enqueue 保留为线程安全入口,内部转 publish
reply_text / reply_content 保留(出站 RPC server 调它)
_TypingKeepalive 保留为可选工具:channel.typing(subject) 上下文管理器
get_session_key / should_batch_inbound / merge_inbound 保留(get_session_key 供分区键;后两个本轮不用)

6.2 新的入站入口

class BaseChannel:
    def attach(self, publish: PublishFn) -> None:
        """注入入站发布回调(由 registry 在注册时调用)。"""

    def publish(self, raw: object) -> None:
        """解析 → 预处理 → 主体登记 → 交给 publish 回调。线程安全。"""

publish 回调在 bootstrap 里就是 bus.publish_threadsafe("channel.inbound", ...), channel 仍然不感知 EventBus(不 import flows),保留可单测性。

6.3 ChannelManager → ChannelRegistry

保留:注册/启用/禁用/移除、运行时状态、start/stop、出站路由。 删除:_queues、_workers、_session_locks、_inflight、wait_idle、enqueue、_worker_loop、_drain_same_session。

对外接口(新增):

def get_latest_message(
    self, channel_id: str, *, subject_id: str | None = None
) -> InboundMessage | None: ...

async def send_text(self, channel_id: str, subject_id: str, text: str) -> None: ...
async def send_content(
    self, channel_id: str, subject_id: str, parts: list[ContentPart]
) -> None: ...

def resolve_subject(self, channel_id: str, subject_id: str) -> ChannelSubject: ...
def list_subjects(self, channel_id: str) -> list[ChannelSubject]: ...
  • 最新消息:_latest[(channel_id, subject_id)] + _latest_by_channel[channel_id],进程内,model_copy(deep=True) 返回。
  • 语义:最近收到的消息,不保证等于当前正在处理的那条(任务应以 payload.message 为准)。
  • send_*:resolve_subject 未登记时抛 LookupError(主动推送依赖首条消息登记路由)。

6.4 发送原语(替代 processor 的 delta 缓冲)

async def send_typing(self, subject: ChannelSubject) -> None: ...
async def send_delta(self, subject: ChannelSubject, text: str) -> None: ...
async def flush_delta(self, subject: ChannelSubject) -> None: ...

任务需要流式输出时自行组合;typing 的周期刷新由 channel.typing(subject) 上下文管理器负责。


7. 消息处理任务化

7.1 分区串行("一个渠道一条链")

class Task:
    def partition_key(self, ctx: TaskContext) -> str:
        """并发分区键;默认 ''(= 现有单槽行为)。"""
        return ""
  • _slots 键由 task_name 变为 (task_name, key);REPLACE 的 current 同样按分区隔离。
  • 同一分区内:QUEUE 串行、SKIP/PARALLEL/REPLACE 语义不变(作用域变成分区)。
  • 不同分区完全并行。

内置消息任务:

class AgentReply(Task):
    name = "channel.agent"
    overlap = OverlapPolicy.QUEUE

    def partition_key(self, ctx: TaskContext) -> str:
        env = ctx.payload
        return getattr(env, "db_session_id", "") or getattr(env, "channel_id", "")

分区键必须与会话历史(messages.session_id)的键一致,内置任务取 ChannelMessage.db_session_id(群聊下是群 ID);不要用渠道锁键 session_key——群聊里它是发送者,会把同一会话拆成多条并发链。 若希望"整条渠道全串行",返回 channel_id 即可,机制不变。

7.2 队列上限与溢出

现状 QUEUE 积压上限 1,对聊天等于丢消息。改为每分区一个 deque:

参数 默认 说明
queue_limit 100 每分区最大积压
overflow drop_new 可选 drop_oldest / block
  • drop_new:新触发记 RunStatus.FAILED(error="queue overflow")并发 task.failed,便于告警。
  • block:_dispatch 变协程等待空位(会阻塞渠道 publisher → 需注意死锁,默认不用)。
  • drop_oldest:丢最早一条并记 SKIPPED。

7.3 依赖注入

@dataclass(frozen=True)
class AppServices:
    channels: ChannelRegistry
    bus: EventBus
    settings: Settings

runner = TaskRunner(bus, deps=AppServices(...))
# _execute 内:
instance = task_cls(ctx)
instance.deps = self._deps      # 属性注入,不改子类构造函数(零破坏)
  • Task.deps 为类属性 None 默认;不放进 TaskContext(ctx 会随 task.<名> 事件外发,服务对象不可序列化且破坏 frozen 语义)。

7.4 内置任务 channel.agent

把现在 flows/processor.py 的逻辑搬进任务:

payload(ChannelMessage) → 校验文本 → init_db/ensure_session
  → list_messages → build_history(去悬空 user / 字符预算 / 首条 user)
  → add_message(user) → run_task(cache=AgentCache)
  → answer 非空才 add_message(assistant)
  → bus.call("channel.send", OutboundText(...))

失败 → 记录 TaskRun.FAILED + task.failed 事件;是否向用户回错误文案由任务决定 (默认回一句"处理消息时出错,请稍后再试。",走同一个 channel.send)。

7.5 收尾顺序

await registry.start()
await runner.start()
await channel.wait_closed()      # CLI: EOF/exit;IM: 显式关停
await runner.wait_idle()         # 新增:所有分区队列空 + 无在途(带 timeout)
await runner.stop()
await registry.stop()

runner.wait_idle() 是新增接口;不要再用旧的 manager.wait_idle()(消息 emit 后它立刻认为空闲)。


8. 出站方案对比

A. 直调服务 B. RPC 出站(推荐)
写法 await self.deps.channels.send_text(...) await self.deps.bus.call("channel.send", OutboundText(...))
错误反馈 try/except 直接拿到 RpcRemoteError / RpcTimeoutError
可拦截(审计/脱敏/限流) 需改任务或包一层 在 server 端统一拦截
与总线的一致性 出入站不对称 入站事件、出站 RPC,同一套总线
依赖 任务依赖 registry 任务只依赖 bus

推荐 B,并把 A 作为"没有 bus 的单元测试"替代路径保留。


9. 事件契约总表

事件 方向 载荷 说明
channel.inbound channel → bus ChannelMessage 已解析/已登记主体;fire-and-forget
channel.send 任务 → registry OutboundText / OutboundContent RPC,返回 {"sent": True} 或抛错
schedule.<name> scheduler → bus Fire 定时触发
schedule.fired scheduler → bus Fire 全局审计
task.<name> runner → bus TaskContext 任务链
task.done / task.failed runner → bus TaskRun 运行结果
rpc.request / rpc.reply RpcHub 内部 RpcRequest / RpcReply 不建议业务直接订阅
error bus 内部 异常 handler 异常统一出口
class ChannelMessage(BaseModel):
    model_config = ConfigDict(frozen=True)
    channel_id: str
    channel_type: str
    subject_id: str
    session_key: str
    message: InboundMessage
    received_at: datetime

class OutboundText(BaseModel):
    channel_id: str
    subject_id: str
    text: str

10. 迁移计划

阶段 1:加桥,不改行为(✅ 已实施)

  • EventBus:bind_loop / publish_threadsafe / publish·subscribe 别名。
  • flows/rpc.py:RpcHub + 单测(成功/超时/远端异常/未注册方法/并发)。
  • BaseChannel.attach(publish=...) 与旧 processor 双轨:handle_inbound 先 publish 再走旧逻辑。
  • ChannelRegistry 补 get_latest_message / send_text / resolve_subject(复用现有 _known_subjects)。

验收:现有 141 个测试全绿 + 新增 RPC 测试;行为无变化(旧 processor 仍在跑)。

阶段 2:切执行面(✅ 已实施)

  • TaskRunner:分区槽、queue_limit/overflow、wait_idle、deps。
  • 内置 AgentReply 任务;run_session 改新链路;processor 仅保留未迁移调用方。
  • 出站 RPC server 注册。

验收:CLI 会话端到端可用;同一 session 消息严格串行、不同 session 并行;发送失败可在任务侧捕获。

阶段 3:拆通道

  • 删除 _queues/_workers/_session_locks/_inflight/wait_idle/_worker_loop/_drain_same_session。
  • 删除 MessageProcessor/MessageEvent 契约与 flows/processor.py。
  • 重写 tests/test_channels*、迁移 test_processor.py。

验收:channels 中不再出现"队列/处理器"字样;全量测试与 lint 通过。


11. 影响面

文件 改动
flows/bus.py bind_loop / publish_threadsafe / 别名 / abort 钩子
flows/rpc.py 新增 RpcHub 与错误类型
flows/tasks.py 分区槽、队列上限、wait_idle、deps、partition_key
flows/builtin.py 新增 AgentReply 等内置任务
flows/processor.py 逻辑迁出,阶段 3 删除
flows/session.py 装配与收尾顺序重写
flows/__init__.py 导出 RpcHub/错误类型/ChannelMessage/OutboundText
channels/base.py publish 入口;删除 processor 流;typing/delta 原语;resolve_subject
channels/manager.py 收缩为 ChannelRegistry;两个对外接口;RPC server 实现
channels/models.py MessageEvent/MessageProcessor 退役
__main__.py 装配调整(一次性任务路径不变)
tests/* 见 §12
docs/task-tutorial.md 新增"渠道消息任务"一节,链接本文

12. 测试计划

模块 用例
RPC 正常往返;超时;远端异常映射;未注册方法;并发 100 次;超时后迟到响应被丢弃;abort_all
EventBus 线程安全发布(跨线程 emit);重复注册;handler 异常不外泄(已有)
channel publish 只调用一次;主体登记;线程安全;resolve_subject 未知时报错
registry get_latest_message 返回副本;send_text 路由到正确 subject;未知 channel/subject 报错
TaskRunner 同分区串行(顺序断言);跨分区并行(最大并发 > 1);队列溢出策略;wait_idle 真等到完成;deps 注入
会话 CLI 端到端:多条消息串行处理、回复经 RPC 发出、退出时冲刷

13. 风险与缓解

风险 缓解
删除 manager 队列后入站无背压 TaskRunner 分区队列设上限 + 溢出告警;必要时 overflow=block
block 策略可能导致 publisher 阻塞 → 渠道回调卡死 默认 drop_new;block 仅在显式配置时启用并加超时
RPC 增加一跳,延迟增加 进程内一跳(microtask 级),可忽略;出站若极端敏感可走直调 A
事件化后调试链路变长 统一 run_id/correlation_id 打日志;rpc.audit 可选开启
阶段 1 双轨期存在两条处理路径 双轨仅一个阶段,验收标准明确(旧测试全绿 + 新事件被发布)

14. 已确认决策(2026-11-09)

  1. 分区键:session_key(一用户/一群一条链,同渠道不同用户并行)。channel_id 作为 session_key 缺失时的兜底。
  2. 队列溢出:drop_new —— 新触发记 RunStatus.FAILED(error="queue overflow")+ 发 task.failed,不做背压阻塞。
  3. 出站:采用 RPC 出站(§8 B),方法名 channel.send;直调 registry.send_text 保留为单元测试与无总线场景的替代路径。
  4. RPC 命名:方法名点分(channel.send);总线事件固定为 rpc.request / rpc.reply,不引入 rpc.<method> 动态事件。

15. 后续扩展(本轮不做)

  • batch_window_ms:同分区短窗口合并多条入站消息再派发(替代原 merge_inbound)。
  • RPC 多响应者/聚合模式、服务发现(served() 已预留)。
  • 出站事件旁路审计:channel.outbound(只观测不发送)与 RPC 并存。
  • 任务级并发上限(每分区 max_concurrency)。