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
This commit is contained in:
openbot committed 2026-11-09 20:32:25 +08:00
1 parent 94421e5c2b
commit fbb01c4c83
65 files changed
+15322 -173

No files matched your search

+654
View File
@@ -0,0 +1,654 @@
# 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 → 校验文本(空文本/纯媒体给固定提示)
→ 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.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) | 同一分区上一次运行未结束时,新触发如何处理 |