Files
bot042/docs/architecture.md
openbot 5ca40c6b0e feat(channels): 平台解密、下载限长与 CLI 媒体命令(issue #1 P1)
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)未构造响应实测中断逻辑
2026-11-10 09:47:30 +08:00

690 lines
40 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.<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()`,两个生命周期入口共用,保证只有一条入站链路:
```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.<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) | 同一分区上一次运行未结束时,新触发如何处理 |