P0 接好了链路与钩子抽象,但几个实际会让功能不可用的点没处理:企业微信的 aeskey 记录下来后被直接丢弃、远端下载把整份响应读进内存、没有真实平台时 无法造出媒体消息来调试。本次补齐这三块。 企业微信解密: - WeComChannel.make_media_transform 按本条消息的 <media>.aeskey 构造闭包, 用 SDK 的 decrypt_file 解密(IV 取密钥前 16 字节、PKCS#7 去填充)。 不在本仓库重写密码学——那只会多出第二份可能与平台不一致的实现 - 没有对应 url 的密钥时原样返回字节,不猜、不抛:由 MIME 嗅探去判定 - SDK 缺失时抛 MediaRejected(含安装提示),不让 ImportError 冒泡打断整轮 下载限长: - BaseChannel.fetch_remote_media 从 resp.content 整份读改成 client.stream 按块累计,Content-Length 先预检、流式累计超限即中断 - 上限取各类型限制的最大值:此方法拿不到分片类型,宁可放到最宽的一档, 精确的按类型判定仍由 store_media 负责 CLI 媒体入口: - /image <路径>、/file <路径> 解析成本地附件分片,走与其他渠道同一套 media.py 策略(存在性、大小上限、MIME 嗅探、文件名净化),不因为 「本地」就跳过 - 拒绝时降级为一条说明文本而非抛异常:CLI 里抛异常会直接终止输入泵 - _send_media 从打印占位行改为回执真实字节的大小与 sha256 前缀。 CLI 里不存在「发送」这回事,所以不打印「已发送」 顺带修的健壮性问题: - store_media 的临时文件名加 uuid 后缀。原先固定 .part,同一会话并发落盘 同名文件时会互相截断,且 try/finally 保证失败不留半份字节 - read_file_limited 的超限文案原先把同一个数写了两遍(「大于 8 MiB (上限 8 MiB)」),改为「文件大于 8 MiB(上限 8 MiB)」,并注明只多读了 1 字节所以只能说「大于」 - cli.py 的 except Exception 收窄为 (OSError, ValueError, TypeError): CancelledError 必须能穿过这一层 测试:新增 tests/test_media_pipeline.py 43 条,按 issue 的六条验收标准逐条 对应(路径穿越与净化、读取与下载限长、MIME 魔数优先、outbox 上限与上下文 隔离、prepare_inbound 多模态与降级、CLI 收发)。文档 architecture.md 补 安全护栏、平台解密、CLI 入口三段。 未验证(见 PR 描述): - 没有一条真实的企业微信加密媒体消息跑过解密路径,单测里这一环是桩 - 分块传输(Transfer-Encoding: chunked)未构造响应实测中断逻辑
40 KiB
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 图)规划并调用工具执行,再把结果写回数据库并回复渠道。
设计上要满足四个约束:
- 全异步:渠道回调、智能体
ainvoke、工具、数据库(aiosqlite)统一跑在一个事件循环里; - 入站与出站解耦:渠道只负责协议适配,不承载业务处理;
- 同一会话严格串行、不同会话并行:聊天连发不能乱序,多用户不能互相阻塞;
- 依赖方向单向:
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 → prepare_inbound(附件落盘;小图内联成 image_url 块)
→ 无可用内容?→ 回「附件未能接收:<原因>」/「(无输出)」并结束
→ ensure_db → ensure_session → list_messages → build_history
→ add_message(user, 正文 + 附件清单)
→ 建 MediaOutbox(本轮出站信箱)
→ open_stream() ┬ 支持流式:update(ACK) → stream_task 边生成边覆盖 → finish
│ → 媒体在文本定稿后单独补一条
└ 不支持:run_task → 有媒体走 send_content,否则 send_text
→ 补记插话(_persist_steered)→ add_message(assistant)
媒体链路(issue #1 的 P0 部分):
- 入站:
flows/media_input.prepare_inbound()把分片整理成多模态块——小图 base64 内联、大图与音视频退化为「路径 + 元信息」、文本类文件抽取正文;单个附件超限/类型 拒绝/下载失败只写进notes,不打断整轮。字节落盘在home/data/inbound/<session>/, 历史只存正文 + 附件清单,不存字节。 - 出站:
agent/outbox.MediaOutbox是本轮的信箱,send_image/send_file工具 往里登记分片;run()结束后drain()出来,与正文合成一条OutboundContent, 由出站管线「先文本、再逐个媒体」下发,避免平台上出现两条消息。只有媒体没有正文时 不再补「(无输出)」;流式通道只送文本,媒体等文本定稿后单独补一条。 - 安全护栏:所有字节来源(
data/local_path/url)都经过channels/media.py的同一套策略——按类型的大小上限、魔数优先的 MIME 判定、 可执行扩展名拉黑、文件名净化与根目录约束;远端下载改为流式按块读取,Content-Length先预检、超限即中断,整份读进内存的路径已移除。 - 平台解密:
BaseChannel.make_media_transform()按单条消息的 metadata 构造 解密钩子(密钥随消息而来,挂在渠道实例上会串台),企业微信用<media>.aeskey走 SDK 的decrypt_file。解密在类型嗅探之前执行,并对 明文再量一次大小——密文没超不等于明文没超。 - CLI 调试入口:
/image <路径>、/file <路径>可以直接在无平台环境造出 媒体入站消息;出站_send_media不再打印占位行,改为回执真实字节的 大小与 sha256 前缀(CLI 里没有「已发送」这回事)。
ChannelServices 是它的运行期依赖(channels / settings / db / hub / cache /
历史条数与字符预算 / 发送超时),由 TaskRunner(deps=...) 注入;media_policy() 从
渠道取媒体大小上限与下载请求头,未知渠道退回默认值(不因为查不到渠道就跳过校验)。
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() 内部固定做四件事:
EventBus.bind_loop(),并构造ChannelManager(publisher=bus.publish_threadsafe);RpcHub(bus)并serve("channel.send", manager.rpc_send);ChannelServices(...)作为TaskRunner的deps;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.<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 上限) |
不变量:
- 同一
(渠道, 会话)的业务处理不会交错(由 TaskRunner 分区保证); - 不同会话完全并行;
- 所有「决策型」状态变更(入队、占位、堆叠选择)都在同步代码段完成,不跨
await; - 计数器与表项的生命周期必须成对:
_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)
ChannelManager→ChannelRegistry:删除_queues/_workers/_session_locks/_inflight/wait_idle/_worker_loop/_drain_same_session;- 退役
MessageProcessor/MessageEvent契约与flows/processor.py; BaseChannel只保留连接、解析、发送原语,入站唯一出口是publish;- 重写
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) | 同一分区上一次运行未结束时,新触发如何处理 |