Files
bot042/docs/architecture.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

37 KiB
Raw Blame History

bot042 架构设计

  • 状态:描述当前代码(2026-11-09),含已完成的阶段 1/2 重构与尚未实施的阶段 3
  • 范围:src/bot042/(agent / channels / flows / db / 入口与配置)
  • 目标读者:项目维护者、需要接入新渠道或新任务的同学

相关文档:

文档 内容
docs/channel-eventbus-design.md Channel × EventBus 重构的方案与迁移计划(阶段 3 仍待做)
docs/task-tutorial.md Task 编写教程(触发、堆叠策略、运行跟踪)
本文 系统现状的整体结构、数据流、并发与契约

1. 系统定位

bot042 是基于 deepagents 的自主行动机器人原型:接收来自渠道(CLI / 企业微信)的消息或定时触发, 交给智能体(LangGraph 图)规划并调用工具执行,再把结果写回数据库并回复渠道。

设计上要满足四个约束:

  1. 全异步:渠道回调、智能体 ainvoke、工具、数据库(aiosqlite)统一跑在一个事件循环里;
  2. 入站与出站解耦:渠道只负责协议适配,不承载业务处理;
  3. 同一会话严格串行、不同会话并行:聊天连发不能乱序,多用户不能互相阻塞;
  4. 依赖方向单向:channels 不感知 flows,靠注入回调解耦,保证渠道可单测。

2. 分层视图

┌──────────────────────────────────────────────────────────────────────┐
│ 入口层                                                                │
│ __main__.py  bot init / bot db / 单次任务 / -i 交互                    │
│ cli.py       数据库管理子命令(providers/models/sessions/...)          │
└───────────────┬──────────────────────────────────────────────────────┘
                │
┌───────────────▼──────────────┐   ┌──────────────────────────────────┐
│ 编排层 flows/                 │   │ 渠道层 channels/                  │
│ EventBus     发布/订阅        │◄──┤ BaseChannel   入站模板/三层出站    │
│ RpcHub       请求-响应        │   │ ChannelManager 队列·worker·会话锁 │
│ TaskRunner   分区串行·堆叠    │   │ registry.py   kind 工厂/凭据探测  │
│ Scheduler    cron/once/间隔   │   │ cli.py / im/wecom.py  适配器      │
│ builtin.py   AgentReply       │   │                                  │
│ stream.py    流式发送/续流     │   │                                  │
│ runtime.py   统一装配与关停    │   │                                  │
│ service.py   常驻 IM 服务      │   └──────────────────────────────────┘
│ session.py   单渠道交互会话    │
└───────────────┬──────────────┘
                │
┌───────────────▼──────────────┐   ┌──────────────────────────────────┐
│ 智能体层 agent/               │   │ 基础设施                          │
│ base.create_agent             │   │ config.py  Settings(环境变量)    │
│ prompts.py                    │   │ home.py    ~/.bot042 目录与 bot.db │
│ tools.py   perceive/move/speak │   │ db/        aiosqlite schema + repo │
└──────────────────────────────┘   └──────────────────────────────────┘

依赖方向(import 关系,无环):

__main__ → flows → channels → (models, base)
__main__ → flows → agent  → config
flows → db, config          channels ✗→ flows(只用注入的 publish 回调)
db → (aiosqlite)            home → db

channels 不 import flows 是硬约束:入站通过 PublishFn = Callable[[ChannelMessage], None] 注入(src/bot042/channels/base.py:46),出站通过 RpcHub 的 server 端回调注入。

3. 核心抽象

3.1 内容与消息模型(channels/models.py)

全部用 pydantic,跨层传递的唯一定义来源:

类型 作用
ContentPart 判别联合:TextContent / Image / Video / Audio / File,按 type 路由。媒体分片携带 data(base64) > local_path > url 三级字节来源
ChannelSubject 出站路由句柄(单聊用户或群会话),metadata 承载平台路由信息(webhook、response_url、chat_id…)
InboundMessage 归一化后的入站消息:content + channel_subject + group_context + metadata
MessageEvent processor 契约的事件(MESSAGE/DELTA/THINKING/…/COMPLETED),过渡期保留
ChannelMessage 发布到总线的入站载荷(frozen):channel_id / subject_id / session_key / message
OutboundText / OutboundContent channel.send RPC 的请求载荷(frozen)
ChannelConfig / ChannelRuntimeStatus 渠道配置基类(required_credentials / field_aliases)与状态快照

ChannelMessage.of() 的 session_key 缺省回退 subject_id,这是后续所有分区/串行判断的键。

3.2 出站三层(channels/base.py)

调用方        reply_text/reply_content/reply_media     push_text/push_message
                  │ 入站上下文                            │ 无入站上下文
                  │                                      ├─ resolve_push_subject()
                  │                                      │   合并已登记路由 + 平台补充
                  │                                      │   剥离 response_url 等临时字段
                  ▼                                      ▼
             _acquire_rate_slot()  ← 限速占位钩子(每条用户可见消息一次)
                  │
                  ▼
        _send_text / _send_content / _send_media   ← 子类实现的平台原语

流式(reply_stream)是这一层的第四种形态:同样落到 _send_* 的语义上, 但由 ReplyStream 控制推送节奏、去重与 10 分钟续流(见 5.8)。

规则:

  • 平台原语内部禁止回调 reply_*/push_*,否则同一条消息占两个限速位;
  • _deliver_text() 是内部漏斗,空文本短路,不消耗限速位;
  • 流式投递由 _process_inbound() 完成:DELTA 累积、FLUSH/COMPLETED 冲刷、 THINKING_DELTA 单独累积、TOOL_START/END 受 show_tool_hints 控制。

4. 渠道层

4.1 入站模板

BaseChannel.handle_inbound() 是所有渠道共用的模板,双轨:

        message = (
            raw_payload
            if isinstance(raw_payload, InboundMessage)
            else self.parse_inbound(raw_payload)
        )
        await self._preprocess_inbound(message)
        self._track_subject(message)

        subject_id = message.channel_subject.subject_id if message.channel_subject else ""
        subject = self._known_subjects.get(subject_id) or ChannelSubject(
            subject_id=subject_id,
            first_seen=message.timestamp or time.time(),
            last_seen=message.timestamp or time.time(),
        )
        message.channel_subject = subject
        self._publish_inbound(message)
        if self._processor is not None:
            await self._process_inbound(message, subject)
        elif self._publish is None:
            raise RuntimeError(
                f"渠道 {self._channel_id} 未配置消息处理器或入站发布回调"
            )
  • 新路径(推荐):_publish_inbound → 注入的 publish 回调 → bus.publish_threadsafe("channel.inbound");
  • 旧路径(过渡):_processor 异步生成器产出 MessageEvent,渠道负责渲染发送。 只有在显式注入 processor 时才会走到,run_session 不注入。

_track_subject() 在首条消息到达时登记 ChannelSubject,之后每条消息刷新 metadata, 这是主动推送(push_*)能定位路由的前提。

4.2 ChannelManager(channels/manager.py)

当前仍是完整的编排运行时,职责比目标架构(ChannelRegistry)多:

组 能力
注册 add_channel / remove_channel / enable_channel / disable_channel / get_channel / channel_ids
生命周期 start / stop,每渠道 workers_per_channel 个 worker(默认 1)
入站 enqueue(线程安全)+ 每渠道 asyncio.Queue(maxsize=queue_maxsize)
串行 _session_lock(channel_id, session_key),run_in_session() 供主动操作复用同一把锁
合批 should_batch_inbound 为真时,_drain_same_session 非阻塞取出队首相邻同会话消息,上限 batch_max
钩子 set_pre_lock_handler,抢锁前调用(宿主可处理 /stop 类控制指令)
状态 status() 惰性刷新(disabled / unregistered / error / connected)
缓存 get_latest_message(按 (channel_id, subject_id) 与按渠道两级,返回深拷贝)
出站 send_text / send_content / push_text / push_content(主动推送)、rpc_send(载荷带 metadata 时走回复语义)、stream_text / rpc_stream(覆盖式流式)、supports_stream、resolve_subject / list_subjects

构造参数:

ChannelManager(
    processor=None,          # 默认处理器(渠道未自带时使用)
    publisher=None,          # 入站发布回调,run_session 注入 bus.publish_threadsafe
    workers_per_channel=1,   # 每渠道 worker 数;>1 才有跨会话并行
    queue_maxsize=1000,      # 有界队列,满了丢消息并 error 日志
    batch_max=20,            # 单次合批条数上限
)

worker 循环(_worker_loop)每轮:wait_for(queue.get(), 1.0) → 解析 → 取 session_key → 可选合批与 merge_inbound → _on_pre_lock 钩子 → 会话锁内 handle_inbound。 单条消息的解析/处理异常只记日志,不拖垮 worker。

线程安全:enqueue 在事件循环线程内直接 put_nowait;SDK 回调线程经 loop.call_soon_threadsafe 转投。这条路径是 WeCom 等 SDK 的唯一入站通道。

4.3 会话锁的引用计数回收

会话锁按 (channel_id, session_key) 元组存于 _session_locks,条目带引用计数:

    @asynccontextmanager
    async def _session_lock(
        self, channel_id: str, session_key: str
    ) -> AsyncIterator[None]:
        """会话锁上下文:同键串行,最后一个使用者退出后自动回收条目。

        引用计数同时覆盖"持有锁"和"等待锁"两类协程,条目只在两者皆无时删除,
        因此不会出现"条目被删除 → 新协程拿到新锁 → 与旧持有者并行"的互斥失效。
        """
        lock_key = (channel_id, session_key)
        entry = self._session_locks.get(lock_key)
        if entry is None:
            entry = _SessionLockEntry()
            self._session_locks[lock_key] = entry
        # 取条目与计数之间不能有 await,否则同 tick 内可能被其他协程回收
        entry.refs += 1
        try:
            async with entry.lock:
                yield
        finally:
            entry.refs -= 1
            if entry.refs <= 0 and self._session_locks.get(lock_key) is entry:
                del self._session_locks[lock_key]

设计取舍:

  • 不用 WeakValueDictionary:持锁协程强引用锁对象,弱引用表里的键会先消失, 新协程取不到旧锁而新建一把 → 互斥被打穿;
  • 计数同时覆盖「持锁」与「等待锁」,只在两者皆无时删除,且「取条目 → 加计数」之间没有 await,同 tick 内无回收窗口;
  • _purge_session_locks() 兜底清理异常路径残留,接入 stop() 与 remove_channel();
  • 内存口径因此是「并发活跃会话数」,而不是「历史会话总数」。

4.4 kind 工厂注册表(channels/registry.py)

与 ChannelManager 是两件事,注意区分:

  • ChannelManager:管理已实例化的渠道对象(运行期编排);
  • registry.py:维护 kind → (渠道类, 配置类) 映射,提供 register_channel / create_channel / probe_channel / known_kinds,供 CLI 与配置驱动装配使用。

各渠道模块在导入时自登记(register_channel("cli", CliChannel, CliConfig))。 probe_channel 会构建临时实例 → start() → 立即 stop(),把失败映射成 ChannelRuntimeStatus 而不抛异常,供管理端做「凭据是否可用」探测。

4.5 适配器

适配器 入站来源 出站原语 备注
CliChannel asyncio.to_thread(input) 输入泵 print(编码降级为 ?) should_batch_inbound=False,每行独立;EOF/exit/quit 触发 wait_closed
WeComChannel wecom-aibot-sdk WebSocket 长连接 reply_stream > response_url > send_message SDK 惰性导入;无限重连;媒体上传后按原生类型投递

5. 编排层

5.1 EventBus(flows/bus.py)

进程内异步发布/订阅,基于 pyee 的 AsyncIOEventEmitter 精简改造。语义要点:

  • emit / publish 是 fire-and-forget:handler 必须是 async 函数(注册时校验), 异常统一转发到 error 事件,不外泄给调用方;
  • 同一事件重复注册同一 handler 抛 BusError(静默覆盖会让 once 的自注销失效);
  • bind_loop() + publish_threadsafe() 解决跨线程投递:同循环直接 emit, 其他线程走 call_soon_threadsafe;未绑定且无线程内循环时抛 BusError(宁可启动即失败,也不静默丢消息);
  • wait_for_complete() 等待已调度 handler 全部结束,cancel() 取消未完成的 —— 关停时用。

5.2 RpcHub(flows/rpc.py)

在总线上实现请求-响应,用于出站发送这类「必须知道成功与否」的调用。

  • 只用两个总线事件:rpc.request / rpc.reply,方法名放在载荷里路由,不引入 rpc.<method> 动态事件;
  • serve(method, handler) 单方法单服务端,重复注册报错;
  • call(method, payload, timeout=5.0):默认 first-response-wins;超时清理 pending 并抛 RpcTimeoutError,迟到响应按 correlation_id 找不到即丢弃;
  • pending_limit=1000 防泄漏;close() 注销监听并对在途调用抛 RpcAborted。

错误映射:本地未注册方法 → RpcError;远端 handler 异常 → RpcRemoteError(remote_type, remote_message)。

5.3 TaskRunner(flows/tasks.py)

任务执行与并发控制中心。

任务模型:任务是类,name / overlap 显式声明;任务体二选一(run() 或 build_graph()); 每次执行新建实例(cls(ctx) → await instance.run()),实例间状态隔离;deps 由运行器注入。

分区串行:槽位键为 (task_name, partition_key)。Task.partition_key(ctx) 默认 "" (整个任务一个槽); AgentReply 覆写为 payload.db_session_id(= message.channel_session_id, 缺省回退 渠道:主体,与会话历史 messages.session_id 完全一致), 所以「同一会话一条链,不同会话并行」。注意它与渠道锁键 session_key (群聊下是发送者)语义不同,两者不能混用。

堆叠策略(OverlapPolicy):

策略 上一次未结束时的行为
SKIP(默认) 记 SKIPPED 并丢弃本次
QUEUE 每分区 FIFO 排队,上限 queue_limit=100;溢出记 FAILED(error="queue overflow")并发 task.failed
PARALLEL 各自并发(不占槽位,wait_idle 不覆盖)
REPLACE 取消当前运行(记 CANCELLED)后立即起新的

运行跟踪:每次执行一条 TaskRun(run_id/status/error/key),runs() / stats() 查询, 保留 runs_limit=200 条;成功发 task.<name>(任务链用)与 task.done,失败额外发 task.failed。

调度无竞态:_dispatch 全部在同步代码里决策(无 await 间隙),因此占位判断天然原子。

5.4 Scheduler(flows/scheduler.py)

三类触发器统一抽象为 Trigger.next_after(after, anchor):

触发器 语义
CronTrigger(expr) 5 字段 cron(分 时 日 月 周),构造时解析,非法即报错
OnceTrigger(at) 定点一次
IntervalTrigger(every) 固定间隔;给 anchor 时按锚点对齐网格,避免漂移

Schedule 追加生效窗口 [start_time, end_time](含端点),窗口外跳过、错过的触发不补发。 每条调度一个独立 asyncio.Task,到点发 schedule.<name> 与全局 schedule.fired,载荷 Fire (scheduled_time 可作业务幂等键)。单次等待上限 60s,分段等待以便系统时间调整后重新对齐。

时间约定:naive datetime 一律视为 Asia/Shanghai(固定 UTC+8,不依赖 tzdata)。

5.5 内置任务 AgentReply(flows/builtin.py)

name = "channel.agent"、overlap = QUEUE、partition_key = db_session_id、 supports_steer = True。处理链路:

ChannelMessage → 校验文本(空文本/纯媒体给固定提示)
  → ensure_db → ensure_session → list_messages → build_history
  → add_message(user)
  → open_stream()  ┬ 支持流式:update(ACK) → stream_task 边生成边覆盖 → finish
                    └ 不支持:run_task → send_text 一次性发送
  → 补记插话(_persist_steered)→ add_message(assistant)

ChannelServices 是它的运行期依赖(channels / settings / db / hub / cache / 历史条数与字符预算 / 发送超时),由 TaskRunner(deps=...) 注入。 on_error 钩子会尽量回一句 ERROR_REPLY,发送失败只记日志(避免错误处理再次抛错)。

两个细节:

  • stream.finish() 放在 finally:无论生成成功还是抛异常都要收尾,否则客户端会 停在一条永远转圈的半成品上;
  • 插话不逐条落库(steer() 是同步回调,无法 await),而是在本轮结束时按序补记为 user 消息,保证下一轮读取历史时上下文完整。

5.6 运行时装配(flows/runtime.py)

装配逻辑集中在 build_runtime(),两个生命周期入口共用,保证只有一条入站链路:

runtime = build_runtime(settings, db=db)   # bus + manager + hub + runner
await runtime.manager.add_channel(channel)  # 启动前只登记
await start_runtime(runtime)                # 渠道 worker → 任务运行器
await drain_runtime(runtime)                # 渠道队列 → 任务分区
await stop_runtime(runtime)                 # 停任务 → 关 RPC → 停渠道

build_runtime() 内部固定做四件事:

  1. EventBus.bind_loop(),并构造 ChannelManager(publisher=bus.publish_threadsafe);
  2. RpcHub(bus) 并 serve("channel.send", manager.rpc_send);
  3. ChannelServices(...) 作为 TaskRunner 的 deps;
  4. register(AgentReply) + add_task(AgentReply.name, EventTrigger("channel.inbound"))。

5.7 两个生命周期入口

入口 结束条件 场景
run_session(channel) channel.wait_closed()(CLI 的 EOF/exit) bot "任务" / bot -i
run_service(...) 停止信号(SIGINT/SIGTERM)或任一渠道关闭 bot serve

run_service()(flows/service.py)额外做三件事:

  • 启动前先 resolve_model_settings(),把数据库里的默认模型与凭据注入配置;
  • 从 channels 表按 enabled 构建渠道(load_channels()),默认排除虚拟的 cli; 未注册 kind 或非法 JSON 只警告跳过,全部跳过时给出可操作的错误信息;
  • 安装 SIGINT/SIGTERM 处理器把信号转成 stop.set()(Windows 不支持 loop.add_signal_handler,用 signal.signal + call_soon_threadsafe);
  • 关停冲刷带超时(默认 30 秒),避免智能体长任务把 Ctrl+C 拖成永久等待。

顺序不能颠倒:先让渠道把队列排空(消息进入总线),再等任务分区空闲(真正处理完), 最后才停任务与渠道。

5.8 流式回复(flows/stream.py + agent_task.stream_task)

生成侧:stream_task() 用 agent.astream(stream_mode="messages") 逐 token 产出 累积文本。两个必要的过滤:

  • 只累积 AIMessageChunk:messages 模式同时会吐出 ToolMessage(工具返回值)与 HumanMessage,不过滤会把 [感知] 位置=(0,0) 这类内部数据混进用户回答;
  • 丢弃带 tool_call_chunks 的轮次:模型在发起工具调用前可能先输出一段叙述 (「我先看一下环境」),那段话不该成为可见答案。

发送侧:ReplyStream 负责节奏,规则如下:

行为 规则
首帧 force=True 立即发送(ack 与第一段内容都不等节流)
节流 默认 1 秒一次,内容未变化直接跳过
去重 与上次发送内容相同则不发
续流 单段存活超过 540 秒 → 旧段 finish=True 定稿,换新 stream_id 首帧铺上现有内容
失败 单次推送异常只记日志,最终答案由 finish 帧兜底

企业微信的 10 分钟限制是平台侧的,客户端会看到两条首尾相接的消息——这是续流的 必然表现。ReplyStream.segments > 1 即为发生过续流。

不支持流式的渠道(如 CLI)走 run_task + send_text,功能完全一致,只是没有打字机效果。

5.9 插话(steer)

用户在一轮回复生成过程中继续发消息时,期望的是「补充/改方向」,而不是排队等下一轮。

派发侧:TaskRunner 的分区槽新增 steer_sink。同分区有新触发时,若运行中任务 声明了 supports_steer 且实例提供了 steer(payload) -> bool,就把载荷直接交给它, 既不排队也不按 SKIP 丢弃。这一步在 _dispatch 的同步段完成,与堆叠策略的决策 同批执行,因此没有竞态。

注入侧:SteeringMiddleware.abefore_model 在每次模型调用前取出缓冲内容,以 [用户在你回复期间补充] … 的形式追加为 user 消息,交给 LangGraph 的 messages reducer。

隔离:缓冲存在 contextvars 里而不是中间件实例上。AgentCache 让同一张图被多个 会话复用,用实例属性会串台;contextvar 按 asyncio 任务隔离,天然正确。

边界:注入发生在「下一次模型调用前」。如果当前已经是最后一步(模型不再调用工具), 插话会作为下一轮的输入被消费——这正是 steer 的语义,文档与代码注释都按此约定。

6. 智能体层(agent/)

模型来源:Settings 里的 model / api_key / base_url 由 flows/model_settings.resolve_model_settings() 在装配阶段补全,优先级 环境变量 > 数据库 > 内置默认。_build_model() 在拿到显式凭据时直接构造 ChatOpenAI(支持 OpenAI 兼容网关),否则回退成 "provider:model" 字符串交给 langchain 从环境变量取凭据。

create_agent() 直接消费 deepagents 默认中间件栈:FilesystemMiddleware(文件读写/grep/execute)、 SubAgentMiddleware(task 子智能体派发)、SummarizationMiddleware(上下文压缩); HumanInTheLoopMiddleware 通过 interrupt_on 按需启用。

工具是虚拟世界模拟:perceive() 读位置/朝向,move(direction, distance) 校验方向与距离 ((0, 10])并更新共享 RobotState,speak(text) 记录播报。状态是进程内单例, reset_robot() 在会话开始与测试前复位。

联网工具(agent/web.py,HTTP 走 primp 的浏览器指纹)补齐外部信息:web_search() 取必应 结果的标题/链接/摘要,web_fetch() 抓页面并按 max_chars 截断。HTML 由自写的流式转换器 转成 Markdown——保留标题、列表、代码、引用与表格,链接一律内联并补全相对地址, script/nav/sidebar 等噪音整块丢弃,代码块保留缩进。抓取结果用 wrap_untrusted() 套上「外部网页内容开始/结束」前后缀,明确告知模型这是数据而不是指令,降低提示注入风险。 两个工具失败时返回文本而不是抛异常,模型可以自行换策略。

执行后端:_build_backend() 用 LocalShellBackend 取代了原先的 StateBackend—— 文件真实落盘、命令直接在宿主机执行,没有沙箱隔离:

能力 来源 说明
ls / read_file / write_file / edit_file / delete / glob / grep FilesystemMiddleware 路径锚定 home 目录(virtual_mode=True),相对路径与 /xxx 都落在 ~/.bot042 内
execute 同上,后端支持执行时自动挂载 宿主机 shell(Windows 为 cmd),可跑 bash 命令、调用解释器;默认超时 120s
run_python agent/execution.py 代码写入临时 .py 后交给 sys.executable(venv 解释器)执行,回传 stdout/stderr 与退出码,默认 60s、上限 600s

inherit_env=True 让子进程继承 PATH(否则找不到解释器),代价是模型也能读到进程环境里的 密钥;virtual_mode 只约束文件工具,execute 仍可访问全盘。这是本地单机原型的取舍, 上生产必须换回隔离后端并开启 interrupt_on={"execute": True} 的人工确认。

AgentCache(flows/agent_task.py)按需构建并复用同一张图:图构建(中间件装配 + 编译)成本远高于 一次 ainvoke,但缓存由持有者(ChannelServices)决定生命周期,不做模块级单例, 避免配置不同或测试替换 create_agent 时串味。

run_task() 把历史转成 {"messages": [...]},以 recursion_limit=settings.max_steps 调用 ainvoke, 返回最终 state;last_message_text() 负责从多模态 content 中只取文本块(按行拼接)。

max_steps 默认 200,优先级 环境变量 BOT042_MAX_STEPS > settings.agent.max_steps > 默认: 联网检索类任务一轮要连续消耗十几个图步数(搜索 → 抓取 → 再搜索 → 汇总),上限过低时 GraphRecursionError 会被渠道兜底成用户看到的「处理消息时出错,请稍后再试。」, 所以它和模型配置一起由 resolve_model_settings() 解析进 Settings。

7. 存储层(db/)

SQLite + aiosqlite,connect() 统一开启外键约束与 WAL。schema 版本记录在 PRAGMA user_version (当前 v3),升级逻辑集中在 _migrate(),默认数据由 _seed() 幂等写入。

表 用途
providers 大模型提供商(kind、base_url、api_key 明文存储)
models 模型参数(上下文窗口、最大输出、温度、is_default)
sessions 会话(channel、title、status、model_id)
channels 通道配置(kind + JSON config)
settings 系统参数(agent.default_model / agent.max_steps / log.level)
messages 会话消息(session_id 外键级联删除,(session_id, id) 索引)

providers / models 不只是配置存储:repo.get_default_model() 在运行期给出 默认模型及其凭据,由 resolve_model_settings() 注入 Settings,因此改配置 不需要动环境变量。

关联同步规则由 repo.py 显式维护:删 provider 先解引用再级联删 models;删 model 置空 sessions.model_id;设默认模型时其他 is_default 清零;写 message 前会话必须存在。

会话键规则(_session_key / AgentReply):优先 channel_session_id,缺省 f"{channel_id}:{subject_id}",因此同一渠道的同一用户共享一条历史。

历史裁剪 build_history() 三条规则:丢弃末尾「无助手回复」的 user(上一轮失败残留)、 按字符预算(默认 8000)从新到旧截断、保证首条是 user(部分模型 API 不接受 assistant 打头)。

8. 端到端数据流

8.1 入站消息

平台/SDK 线程               事件循环
   │ enqueue(raw)             │
   │──call_soon_threadsafe──► ChannelManager 队列
                              │  worker: get → parse_inbound → get_session_key
                              │  可选合批(相邻同会话,上限 batch_max)
                              │  pre-lock 钩子
                              │  会话锁内 handle_inbound:
                              │    preprocess → track_subject → publish
                              ▼
                    bus.publish("channel.inbound", ChannelMessage)
                              │  TaskRunner handler → _dispatch(partition=session_key)
                              ▼
                    AgentReply.run(): 读历史 → run_task → 落库 → hub.call("channel.send")
                              ▼
                    ChannelManager.rpc_send
                      → 带回复上下文:reply_text(保留 _frame/response_url)
                      → 无上下文:resolve_subject → push_text(主动推送)
                      → _send_text

注意串行的真实归属:publish 是同步 fire-and-forget,因此在当前装配(渠道未注入 processor)下,manager 的会话锁只覆盖「解析 → 登记 → 发布」这一段,外加 run_in_session 的主动操作;同一会话的业务处理串行由 TaskRunner 的分区槽保证。若显式给渠道注入 processor(旧路径),锁会一直覆盖到流式处理结束。两套机制并存是阶段 2 的过渡结果, 阶段 3 会删掉前者。

8.2 主动推送 / 定时任务

Scheduler 到点 → bus.emit("schedule.<name>", Fire)
  → TaskRunner(若绑定了定时触发器)→ Task.run()
  → 需要发消息时:hub.call("channel.send", OutboundText) → 同 8.1 出站段

主动推送依赖 ChannelSubject 已登记:目标用户必须先发过消息,否则 resolve_subject 抛 LookupError,错误信息会明确提示「主动推送需先收到该用户/会话的消息」。

9. 并发模型

层面 机制 作用域
渠道入站 每渠道 N 个 worker + 有界队列 渠道内并发度;满队列丢消息(error 日志)
渠道串行 _session_lock + 引用计数回收 (channel_id, session_key)
任务执行 _Slot + OverlapPolicy (task_name, partition_key)
插话 _Slot.steer_sink + contextvar 运行中的 (task_name, partition_key)
调度 每调度一个 asyncio.Task 调度名
RPC future + correlation_id 单次调用(pending_limit 上限)

不变量:

  1. 同一 (渠道, 会话) 的业务处理不会交错(由 TaskRunner 分区保证);
  2. 不同会话完全并行;
  3. 所有「决策型」状态变更(入队、占位、堆叠选择)都在同步代码段完成,不跨 await;
  4. 计数器与表项的生命周期必须成对:_inflight 在 finally 递减,会话锁计数在 finally 递减, _Slot.running 在 finally 释放(否则该分区此后永远 SKIP)。

10. 事件与 RPC 契约

名称 类型 载荷 生产者 → 消费者
channel.inbound 事件 ChannelMessage ChannelManager/BaseChannel → TaskRunner
channel.send RPC OutboundText / OutboundContent(含可选 metadata 回复上下文) ChannelServices → ChannelManager.rpc_send
channel.stream RPC OutboundStream(stream_id + text + finish) ReplyStream → ChannelManager.rpc_stream
schedule.<name> 事件 Fire Scheduler → TaskRunner / 业务订阅者
schedule.fired 事件 Fire Scheduler → 审计/日志
task.<name> 事件 TaskContext TaskRunner → 任务链
task.done 事件 TaskRun TaskRunner → 观测
task.failed 事件 TaskRun TaskRunner → 告警/补偿
rpc.request / rpc.reply 事件 RpcRequest / RpcReply RpcHub 内部,不建议业务订阅
error 事件 异常 EventBus → 全局错误处理

RPC 与方法名的选择理由:出站必须能拿到发送结果,纯事件化拿不到;用固定两个总线事件承载, 避免动态事件名污染事件空间。channel.send 的返回值约定为 {"sent": True}。

11. 错误处理与可观测性

层 策略
handler 异常 EventBus 转发为 error 事件;转发自身失败只记日志(曾导致 TaskRunner 占位卡死)
worker 单条消息 记 logger.exception,继续下一轮;不影响其他消息
任务失败 TaskRun.status=FAILED + error 文本 + task.failed + on_error 钩子
出站失败 RPC 抛 RpcRemoteError / RpcTimeoutError,由任务决定是否向用户回错误文案
渠道状态 ChannelRuntimeStatus(connected, reason ∈ {disabled, unregistered, error}, detail) 惰性刷新
运行记录 runner.runs(name, limit, key) / runner.stats(...)(含 last_error)
日志 统一 logging,任务日志带 run_id,RPC 失败带方法名

12. 生命周期与关停

启动: settings → init_db → bus.bind_loop → manager.add_channel/start
      → hub.serve("channel.send") → runner.register/add_task → runner.start

运行: channel.wait_closed()(CLI 的 EOF/exit;IM 由显式关停触发)

收尾: manager.wait_idle()   # 渠道队列排空,消息已进总线
      → runner.wait_idle()  # 分区队列清空且无在途
      → runner.stop() → hub.close()(在途 RPC 收到 RpcAborted)→ manager.stop()

stop() 的顺序保证:先停止接受新触发,再中止等待中的 RPC,最后断开渠道; ChannelManager.stop() 会 cancel 全部 worker 并 gather(return_exceptions=True), 随后兜底回收无引用的会话锁。

13. 测试与质量门禁

  • tests/ 共 18 个测试文件、187 个用例:test_channels*(模型/渠道/管理器)、test_bus、 test_rpc、test_tasks、test_scheduler、test_cron、test_processor、test_flows_async、 test_db_crud、test_builtin、test_service(渠道装配与端到端闭环)、 test_model_settings(模型配置优先级)、test_stream(节流/续流/ack)、 test_steering(插话注入与派发)、test_init、test_bot042;
  • 并发行为用真实 asyncio 断言而非 mock:如 test_session_lock_reclaimed_when_idle (200 个会话后锁表为 0)、test_session_lock_kept_while_waiter_pending (有等待者时条目保留且严格串行)、test_tasks 的同分区串行/跨分区并行;
  • 门禁:uv run pytest、uv run ruff check。

14. 已知边界与演进

已接受的边界

项 说明
进程内总线 不跨进程/跨机器;重启丢在途消息(无持久化队列)
双轨入站 publish 与 processor 并存,flows/processor.py 仍导出 make_processor
双套排队 ChannelManager 的队列/会话锁与 TaskRunner 的分区槽语义重叠
合批解析失败 _drain_same_session 中解析异常会丢已取出的那条消息(仅合批路径)
主动推送前提 必须先收到过该用户/会话的消息,否则无路由句柄
模型协议 显式 api_key / base_url 只对 openai 前缀生效(OpenAI 兼容网关);其他协议回退环境变量
流式续流 超过平台存活上限会换 stream_id,客户端表现为两条首尾相接的消息
插话时机 steer 在下一次模型调用前生效;若当前已是最后一步,则作为下一轮输入
流式节流 默认 1 秒一次,极短回复可能只看到 ack 直接变成最终答案

阶段 3(待做,见 docs/channel-eventbus-design.md §10)

  1. ChannelManager → ChannelRegistry:删除 _queues / _workers / _session_locks / _inflight / wait_idle / _worker_loop / _drain_same_session;
  2. 退役 MessageProcessor / MessageEvent 契约与 flows/processor.py;
  3. BaseChannel 只保留连接、解析、发送原语,入站唯一出口是 publish;
  4. 重写 tests/test_channels*,迁移 test_processor.py。

阶段 3 完成后,串行/排队/统计只剩 TaskRunner 一套实现,channels 不再承担调度职责。

后续扩展点(未排期):同分区短窗口合批(batch_window_ms)、RPC 多响应者/服务发现、 出站审计事件、每分区并发上限。

15. 术语

术语 含义
渠道(channel) 一个平台连接的适配器实例,用 channel_id 唯一标识
主体(subject) 出站路由目标:单聊用户或群会话,ChannelSubject.subject_id
会话键(session_key) 串行/分区的最小单位,默认等于 subject_id
分区(partition) (任务名, session_key) 组成的并发作用域
入站(inbound) 从平台到系统的消息,归一到 InboundMessage 后发 channel.inbound
出站(outbound) 从系统到平台的消息,统一走 channel.send RPC
堆叠策略(overlap) 同一分区上一次运行未结束时,新触发如何处理