- 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
22 KiB
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. 设计目标
- EventBus 成为唯一分发面:入站消息、出站发送、定时触发、任务结果都通过总线。
- channel 退化为协议适配层:连接、解析、发送原语;不再有队列、worker、会话锁、处理器。
- 执行统一收敛到
TaskRunner:串行/排队/重试/统计只有一套实现。 - 给 EventBus 增加 RPC:请求-响应语义,用来解决"事件化之后拿不到结果"的问题(尤其是发送失败反馈)。
- 保持
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)
- 分区键:
session_key(一用户/一群一条链,同渠道不同用户并行)。channel_id作为session_key缺失时的兜底。 - 队列溢出:
drop_new—— 新触发记RunStatus.FAILED(error="queue overflow")+ 发task.failed,不做背压阻塞。 - 出站:采用 RPC 出站(§8 B),方法名
channel.send;直调registry.send_text保留为单元测试与无总线场景的替代路径。 - RPC 命名:方法名点分(
channel.send);总线事件固定为rpc.request/rpc.reply,不引入rpc.<method>动态事件。
15. 后续扩展(本轮不做)
batch_window_ms:同分区短窗口合并多条入站消息再派发(替代原merge_inbound)。- RPC 多响应者/聚合模式、服务发现(
served()已预留)。 - 出站事件旁路审计:
channel.outbound(只观测不发送)与 RPC 并存。 - 任务级并发上限(每分区
max_concurrency)。