# 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()` 是所有渠道共用的模板,**双轨**: ```313:334:src/bot042/channels/base.py 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` | 构造参数: ```python 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`,条目带引用计数: ```478:500:src/bot042/channels/manager.py @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.` 动态事件; - `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.`(任务链用)与 `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.` 与全局 `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()`,两个生命周期入口共用,保证只有一条入站链路: ```python 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.recursion_limit` 调用 `ainvoke`, 返回最终 state;`last_message_text()` 负责从多模态 content 中只取文本块(按行拼接)。 `max_steps` 默认 200,优先级 **环境变量 `BOT042_MAX_STEPS` > `settings.agent.max_steps` > 默认**: 联网检索类任务一轮要连续消耗十几个图步数(搜索 → 抓取 → 再搜索 → 汇总)。它是**软预算**, 不是 `recursion_limit` 本身—— - `StepBudgetMiddleware`(`agent/middlewares/budget.py`)按模型调用轮数计账(`agent_rounds = max_steps // 2`, 一次「模型 → 工具」往返约耗 2 个图步),剩余 ≤4 轮时注入一条「立刻停止调用工具、给出结论」 的提示,且只提醒一次; - 交给 LangGraph 的硬上限是 `recursion_limit = max_steps + STEP_GRACE(20)`,留给收尾动作; - 真撞上硬上限(模型不听话、或子智能体的步数不在计数内)时,`GraphRecursionError` 会被转成 `StepBudgetExceeded`;`AgentReply` 把它渲染成「本轮执行步数用尽(上限 N 步)」+ 已产出的部分内容, 一并落库为 assistant 消息,并标记 `_reported` 让 `on_error` 不再补发通用错误文案。 两者以前是同值,于是预算耗尽的那一刻必然抛异常,模型连一句话都来不及说——这是 v0.1 的 bug。 ## 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.", 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.` | 事件 | `Fire` | `Scheduler` → `TaskRunner` / 业务订阅者 | | `schedule.fired` | 事件 | `Fire` | `Scheduler` → 审计/日志 | | `task.` | 事件 | `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) | 同一分区上一次运行未结束时,新触发如何处理 |