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:
1 parent
94421e5c2b
commit
fbb01c4c83
65 files changed
+15322
-173
No files matched your search
@@ -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) | 同一分区上一次运行未结束时,新触发如何处理 |
|
||||
@@ -0,0 +1,489 @@
|
||||
# Channel × EventBus 重构设计(含 RPC 扩展)
|
||||
|
||||
- 状态:**阶段 1、2 已实施;阶段 3 待做**
|
||||
- 日期:2026-11-09(阶段 2 实施完成)
|
||||
- 范围:`src/bot042/channels/`、`src/bot042/flows/`、`docs/`
|
||||
- 目标读者:项目维护者
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `channels/` 与 `flows/` 各自维护了一套完整的消息调度:
|
||||
|
||||
- 通道层:`ChannelManager._queues` + `_worker_loop` + `_session_locks` + `_inflight` + `handle_inbound` 里的
|
||||
`processor` 异步生成器 + `MessageEvent` 投递。
|
||||
- 编排层:`EventBus`(`on/once/emit`)+ `TaskRunner`(`_Slot`、overlap、`TaskRun`、`runs/stats`)。
|
||||
|
||||
两套并存带来的实际问题:
|
||||
|
||||
| 能力 | 通道层现状 | 编排层现状 | 结果 |
|
||||
|---|---|---|---|
|
||||
| 串行 | `_session_locks`(按 subject) | `_Slot` + `overlap`(按任务) | 语义重复且不同,改一处不影响另一处 |
|
||||
| 排队/背压 | `asyncio.Queue`(默认无界) | `QUEUE` 积压上限 1 | 两个上限,都不适合聊天连发 |
|
||||
| 在途统计 | `_inflight` + `wait_idle()` | `runs()` / `stats()` | 收尾要分别等待,容易漏 |
|
||||
| 错误口径 | `MessageEvent.error_event` | `task.failed` 事件 | 两套可观测指标 |
|
||||
| 处理入口 | `processor` 生成器 | `Task.run()` | 同一件事两种写法 |
|
||||
|
||||
结论:消息处理逻辑实际上"藏在通道层",`EventBus` 只服务于脚本任务(`tasks/scheduler`),
|
||||
所以两个子系统关联很弱。
|
||||
|
||||
## 2. 设计目标
|
||||
|
||||
1. **EventBus 成为唯一分发面**:入站消息、出站发送、定时触发、任务结果都通过总线。
|
||||
2. **channel 退化为协议适配层**:连接、解析、发送原语;不再有队列、worker、会话锁、处理器。
|
||||
3. **执行统一收敛到 `TaskRunner`**:串行/排队/重试/统计只有一套实现。
|
||||
4. **给 EventBus 增加 RPC**:请求-响应语义,用来解决"事件化之后拿不到结果"的问题(尤其是发送失败反馈)。
|
||||
5. 保持 `channels` 不 `import bot042.flows`(依赖方向不变),通过注入回调解耦。
|
||||
|
||||
## 3. 非目标(本轮不做)
|
||||
|
||||
- 跨进程 / 跨机器消息(仍是进程内总线)。
|
||||
- RPC 多播聚合、流式响应、双向长连接。
|
||||
- 消息合批(`batch_window_ms`):本轮**放弃**,留作后续扩展点(见 §15)。
|
||||
- 通道 SDK 的重连、ACK、回调线程管理——这些必须留在 channel 内。
|
||||
- 持久化消息队列(进程重启丢在途消息,与现状一致)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 总体架构
|
||||
|
||||
```
|
||||
┌─ 协议适配(channels/)──────────────────────────────────────────────┐
|
||||
│ BaseChannel: start/stop · parse_inbound · send_text/send_content │
|
||||
│ send_typing/send_delta/flush · _known_subjects │
|
||||
│ │
|
||||
│ 入站唯一出口: publish(InboundMessage) ← 注入的同步回调 │
|
||||
│ 出站唯一入口: send_text(...) ← 被 RPC server 调用 │
|
||||
│ 没有:队列 / worker / 会话锁 / processor / MessageEvent 流 │
|
||||
└───────────────────────────────┬──────────────────────────────────────┘
|
||||
│ bootstrap 注入的 publisher
|
||||
┌───────────────────────────────▼──────────────────────────────────────┐
|
||||
│ 分发(flows/bus.py + flows/rpc.py) │
|
||||
│ EventBus: publish / subscribe / once / error 路由 / 线程安全桥 │
|
||||
│ RpcHub: serve(method, handler) / await call(method, payload) │
|
||||
│ 事件空间: channel.inbound · channel.* · task.* · schedule.* · rpc.* │
|
||||
└───────────────────────────────┬──────────────────────────────────────┘
|
||||
│ 订阅 + 分区串行
|
||||
┌───────────────────────────────▼──────────────────────────────────────┐
|
||||
│ 执行(flows/tasks.py) │
|
||||
│ TaskRunner: 每 (task, partition_key) 一条串行链 │
|
||||
│ Task: run() 或 build_graph()+ainvoke;deps 注入外部服务 │
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
启动装配(伪代码):
|
||||
|
||||
```python
|
||||
bus = EventBus()
|
||||
bus.bind_loop()
|
||||
|
||||
registry = ChannelRegistry() # 原 ChannelManager 收缩后
|
||||
runner = TaskRunner(bus, deps=AppServices(channels=registry, settings=settings))
|
||||
|
||||
bus.serve("channel.send", registry.rpc_send) # 出站 RPC server
|
||||
publisher = lambda msg: bus.publish_threadsafe("channel.inbound", ChannelMessage.of(msg))
|
||||
registry.attach_all(publish=publisher) # 每个 channel 注入 publish
|
||||
|
||||
runner.register(AgentReply) # 内置任务
|
||||
runner.add_task("channel.agent", EventTrigger(event="channel.inbound"))
|
||||
await runner.start()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. EventBus 扩展
|
||||
|
||||
### 5.1 保持不变的语义
|
||||
|
||||
- `emit`(fire-and-forget):handler 必须 `async`;异常路由到 `error` 事件;不向调用方抛。
|
||||
- `on/once` 注册;`wait_for_complete()`;`cancel()`。
|
||||
- 上一轮已修复的约束:重复注册同一 handler 抛 `BusError`;handler 同步异常不外泄。
|
||||
|
||||
### 5.2 新增别名
|
||||
|
||||
贴合"subscribe / publish"的叫法,纯别名、不改语义:
|
||||
|
||||
```python
|
||||
publish = emit # 方法别名
|
||||
subscribe = on
|
||||
subscribe_once = once
|
||||
```
|
||||
|
||||
### 5.3 线程安全桥(必须)
|
||||
|
||||
SDK 回调常在工作线程,`emit` 需要事件循环:
|
||||
|
||||
```python
|
||||
def bind_loop(self, loop: asyncio.AbstractEventLoop | None = None) -> None: ...
|
||||
def publish_threadsafe(self, event: str, *args: object) -> None:
|
||||
"""同线程直接 emit;跨线程用 loop.call_soon_threadsafe。未 bind 时抛 BusError。"""
|
||||
```
|
||||
|
||||
有了它,`ChannelManager` 的 `_queues`/`_worker_loop`/`enqueue` 才有条件删除。
|
||||
|
||||
### 5.4 RPC 封装(新增 `flows/rpc.py`)
|
||||
|
||||
#### 语义
|
||||
|
||||
"有返回值的 publish":调用方 `await` 拿到响应或异常,超时可控。**进程内**。
|
||||
|
||||
```python
|
||||
class RpcError(Exception): ...
|
||||
class RpcTimeoutError(RpcError): ...
|
||||
class RpcRemoteError(RpcError): # 远端 handler 抛异常
|
||||
remote_type: str
|
||||
remote_message: str
|
||||
class RpcAborted(RpcError): ... # 总线关闭 / cancel()
|
||||
|
||||
RpcHandler = Callable[[object], Awaitable[object]]
|
||||
|
||||
class RpcHub:
|
||||
def __init__(self, bus: EventBus, *, pending_limit: int = 1000) -> None: ...
|
||||
def serve(self, method: str, handler: RpcHandler) -> None: ...
|
||||
def unserve(self, method: str) -> None: ...
|
||||
def served(self) -> list[str]: ...
|
||||
async def call(self, method: str, payload: object = None, *, timeout: float | None = 5.0) -> object: ...
|
||||
def abort_all(self) -> None: ...
|
||||
```
|
||||
|
||||
#### 时序
|
||||
|
||||
```
|
||||
caller EventBus(+RpcHub) server handler
|
||||
│ call(m, p) ──创建 Future(cid)──► publish("rpc.request",
|
||||
│ RpcRequest(cid, m, p))
|
||||
│ │ RpcHub._on_request
|
||||
│ ├─ 查 method 路由 ──► await handler(p)
|
||||
│ │ │
|
||||
│ │◄── 返回值/异常 ─────────┘
|
||||
│ ├─ publish("rpc.reply",
|
||||
│ │ RpcReply(cid, ok, value|error))
|
||||
│◄── Future 解析 / 抛错 ◄────────────────┘
|
||||
```
|
||||
|
||||
- 只用**两个**总线事件:`rpc.request`、`rpc.reply`,方法名在载荷里路由。
|
||||
理由:避免动态事件名(`rpc.<method>`)污染事件空间,也不需要在 `EventBus` 里加通配订阅。
|
||||
- 同一时刻同一 `method` 只允许**一个** server(`serve` 重复注册报 `ValueError`)。
|
||||
- 默认 **first-response-wins**:响应到达即完成 Future,后续回复丢弃(单响应者场景已够)。
|
||||
- 请求方 `timeout` 到点:清理 pending 并抛 `RpcTimeoutError`;迟到响应被忽略。
|
||||
- `pending` 数量超 `pending_limit`:直接抛 `RpcError`(防泄漏)。
|
||||
- 总线 `cancel()` / 应用关停:`abort_all()` 让所有 pending 抛 `RpcAborted`。
|
||||
- 审计(可选,默认关闭):`rpc.audit` 事件带 method/耗时/结果,避免默认产生噪音。
|
||||
|
||||
#### 为什么用 RPC 而不是"两段事件"
|
||||
|
||||
普通事件化出站的痛点是**发送结果无法回传**:任务 `emit("channel.send", ...)` 之后不知道成功失败。
|
||||
RPC 让"事件化"与"能拿到结果"同时成立:
|
||||
|
||||
```python
|
||||
# 任务内
|
||||
await self.deps.bus.call(
|
||||
"channel.send",
|
||||
OutboundText(channel_id=cid, subject_id=uid, text=answer),
|
||||
timeout=10,
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# bootstrap
|
||||
async def _send(payload: object) -> object:
|
||||
assert isinstance(payload, OutboundText)
|
||||
await registry.send_text(payload.channel_id, payload.subject_id, payload.text)
|
||||
return {"sent": True}
|
||||
|
||||
bus.serve("channel.send", _send)
|
||||
```
|
||||
|
||||
#### 与 TaskRunner 的关系
|
||||
|
||||
RPC 不替代任务触发:`task.*` / `schedule.*` / `channel.inbound` 仍是 fire-and-forget 事件;
|
||||
RPC 只用于"需要结果"的调用(出站发送、配置查询、工具调用代理)。
|
||||
`RpcHub` 是 `EventBus` 之上的**薄封装**,不引入新的调度器。
|
||||
|
||||
---
|
||||
|
||||
## 6. Channel 层重构
|
||||
|
||||
### 6.1 职责收缩
|
||||
|
||||
| 现有 | 处置 |
|
||||
|---|---|
|
||||
| `handle_inbound()` 的 processor 事件流(typing/delta/thinking/tool/text/error/completed 投递) | **删除**,替换为 `publish(raw)` |
|
||||
| `_processor` / `has_processor` / `attach(processor=)` | 删除 |
|
||||
| `MessageProcessor` / `MessageEvent` | 契约退役(`MessageEvent` 的投递语义由 §6.3 原语承担) |
|
||||
| `parse_inbound` / `_preprocess` / `_register_subject` | 保留 |
|
||||
| `_enqueue_callback` / `enqueue` | 保留为线程安全入口,内部转 `publish` |
|
||||
| `reply_text` / `reply_content` | 保留(出站 RPC server 调它) |
|
||||
| `_TypingKeepalive` | 保留为可选工具:`channel.typing(subject)` 上下文管理器 |
|
||||
| `get_session_key` / `should_batch_inbound` / `merge_inbound` | 保留(`get_session_key` 供分区键;后两个本轮不用) |
|
||||
|
||||
### 6.2 新的入站入口
|
||||
|
||||
```python
|
||||
class BaseChannel:
|
||||
def attach(self, publish: PublishFn) -> None:
|
||||
"""注入入站发布回调(由 registry 在注册时调用)。"""
|
||||
|
||||
def publish(self, raw: object) -> None:
|
||||
"""解析 → 预处理 → 主体登记 → 交给 publish 回调。线程安全。"""
|
||||
```
|
||||
|
||||
`publish` 回调在 bootstrap 里就是 `bus.publish_threadsafe("channel.inbound", ...)`,
|
||||
**channel 仍然不感知 EventBus**(不 import flows),保留可单测性。
|
||||
|
||||
### 6.3 `ChannelManager` → `ChannelRegistry`
|
||||
|
||||
保留:注册/启用/禁用/移除、运行时状态、`start/stop`、出站路由。
|
||||
删除:`_queues`、`_workers`、`_session_locks`、`_inflight`、`wait_idle`、`enqueue`、`_worker_loop`、`_drain_same_session`。
|
||||
|
||||
对外接口(新增):
|
||||
|
||||
```python
|
||||
def get_latest_message(
|
||||
self, channel_id: str, *, subject_id: str | None = None
|
||||
) -> InboundMessage | None: ...
|
||||
|
||||
async def send_text(self, channel_id: str, subject_id: str, text: str) -> None: ...
|
||||
async def send_content(
|
||||
self, channel_id: str, subject_id: str, parts: list[ContentPart]
|
||||
) -> None: ...
|
||||
|
||||
def resolve_subject(self, channel_id: str, subject_id: str) -> ChannelSubject: ...
|
||||
def list_subjects(self, channel_id: str) -> list[ChannelSubject]: ...
|
||||
```
|
||||
|
||||
- 最新消息:`_latest[(channel_id, subject_id)]` + `_latest_by_channel[channel_id]`,进程内,`model_copy(deep=True)` 返回。
|
||||
- 语义:**最近收到**的消息,不保证等于当前正在处理的那条(任务应以 `payload.message` 为准)。
|
||||
- `send_*`:`resolve_subject` 未登记时抛 `LookupError`(主动推送依赖首条消息登记路由)。
|
||||
|
||||
### 6.4 发送原语(替代 processor 的 delta 缓冲)
|
||||
|
||||
```python
|
||||
async def send_typing(self, subject: ChannelSubject) -> None: ...
|
||||
async def send_delta(self, subject: ChannelSubject, text: str) -> None: ...
|
||||
async def flush_delta(self, subject: ChannelSubject) -> None: ...
|
||||
```
|
||||
|
||||
任务需要流式输出时自行组合;`typing` 的周期刷新由 `channel.typing(subject)` 上下文管理器负责。
|
||||
|
||||
---
|
||||
|
||||
## 7. 消息处理任务化
|
||||
|
||||
### 7.1 分区串行("一个渠道一条链")
|
||||
|
||||
```python
|
||||
class Task:
|
||||
def partition_key(self, ctx: TaskContext) -> str:
|
||||
"""并发分区键;默认 ''(= 现有单槽行为)。"""
|
||||
return ""
|
||||
```
|
||||
|
||||
- `_slots` 键由 `task_name` 变为 `(task_name, key)`;`REPLACE` 的 `current` 同样按分区隔离。
|
||||
- 同一分区内:`QUEUE` 串行、`SKIP`/`PARALLEL`/`REPLACE` 语义不变(作用域变成分区)。
|
||||
- 不同分区完全并行。
|
||||
|
||||
内置消息任务:
|
||||
|
||||
```python
|
||||
class AgentReply(Task):
|
||||
name = "channel.agent"
|
||||
overlap = OverlapPolicy.QUEUE
|
||||
|
||||
def partition_key(self, ctx: TaskContext) -> str:
|
||||
env = ctx.payload
|
||||
return getattr(env, "db_session_id", "") or getattr(env, "channel_id", "")
|
||||
```
|
||||
|
||||
> 分区键必须与会话历史(`messages.session_id`)的键一致,内置任务取
|
||||
> `ChannelMessage.db_session_id`(群聊下是群 ID);**不要**用渠道锁键
|
||||
> `session_key`——群聊里它是发送者,会把同一会话拆成多条并发链。
|
||||
> 若希望"整条渠道全串行",返回 `channel_id` 即可,机制不变。
|
||||
|
||||
### 7.2 队列上限与溢出
|
||||
|
||||
现状 `QUEUE` 积压上限 1,对聊天等于丢消息。改为每分区一个 `deque`:
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `queue_limit` | 100 | 每分区最大积压 |
|
||||
| `overflow` | `drop_new` | 可选 `drop_oldest` / `block` |
|
||||
|
||||
- `drop_new`:新触发记 `RunStatus.FAILED`(`error="queue overflow"`)并发 `task.failed`,便于告警。
|
||||
- `block`:`_dispatch` 变协程等待空位(会阻塞渠道 publisher → 需注意死锁,默认不用)。
|
||||
- `drop_oldest`:丢最早一条并记 `SKIPPED`。
|
||||
|
||||
### 7.3 依赖注入
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class AppServices:
|
||||
channels: ChannelRegistry
|
||||
bus: EventBus
|
||||
settings: Settings
|
||||
|
||||
runner = TaskRunner(bus, deps=AppServices(...))
|
||||
# _execute 内:
|
||||
instance = task_cls(ctx)
|
||||
instance.deps = self._deps # 属性注入,不改子类构造函数(零破坏)
|
||||
```
|
||||
|
||||
- `Task.deps` 为类属性 `None` 默认;不放进 `TaskContext`(`ctx` 会随 `task.<名>` 事件外发,服务对象不可序列化且破坏 frozen 语义)。
|
||||
|
||||
### 7.4 内置任务 `channel.agent`
|
||||
|
||||
把现在 `flows/processor.py` 的逻辑搬进任务:
|
||||
|
||||
```
|
||||
payload(ChannelMessage) → 校验文本 → init_db/ensure_session
|
||||
→ list_messages → build_history(去悬空 user / 字符预算 / 首条 user)
|
||||
→ add_message(user) → run_task(cache=AgentCache)
|
||||
→ answer 非空才 add_message(assistant)
|
||||
→ bus.call("channel.send", OutboundText(...))
|
||||
```
|
||||
|
||||
失败 → 记录 `TaskRun.FAILED` + `task.failed` 事件;是否向用户回错误文案由任务决定
|
||||
(默认回一句"处理消息时出错,请稍后再试。",走同一个 `channel.send`)。
|
||||
|
||||
### 7.5 收尾顺序
|
||||
|
||||
```python
|
||||
await registry.start()
|
||||
await runner.start()
|
||||
await channel.wait_closed() # CLI: EOF/exit;IM: 显式关停
|
||||
await runner.wait_idle() # 新增:所有分区队列空 + 无在途(带 timeout)
|
||||
await runner.stop()
|
||||
await registry.stop()
|
||||
```
|
||||
|
||||
`runner.wait_idle()` 是新增接口;**不要**再用旧的 `manager.wait_idle()`(消息 emit 后它立刻认为空闲)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 出站方案对比
|
||||
|
||||
| | A. 直调服务 | B. RPC 出站(推荐) |
|
||||
|---|---|---|
|
||||
| 写法 | `await self.deps.channels.send_text(...)` | `await self.deps.bus.call("channel.send", OutboundText(...))` |
|
||||
| 错误反馈 | try/except 直接拿到 | `RpcRemoteError` / `RpcTimeoutError` |
|
||||
| 可拦截(审计/脱敏/限流) | 需改任务或包一层 | 在 server 端统一拦截 |
|
||||
| 与总线的一致性 | 出入站不对称 | 入站事件、出站 RPC,同一套总线 |
|
||||
| 依赖 | 任务依赖 registry | 任务只依赖 bus |
|
||||
|
||||
推荐 **B**,并把 A 作为"没有 bus 的单元测试"替代路径保留。
|
||||
|
||||
---
|
||||
|
||||
## 9. 事件契约总表
|
||||
|
||||
| 事件 | 方向 | 载荷 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `channel.inbound` | channel → bus | `ChannelMessage` | 已解析/已登记主体;fire-and-forget |
|
||||
| `channel.send` | 任务 → registry | `OutboundText` / `OutboundContent` | **RPC**,返回 `{"sent": True}` 或抛错 |
|
||||
| `schedule.<name>` | scheduler → bus | `Fire` | 定时触发 |
|
||||
| `schedule.fired` | scheduler → bus | `Fire` | 全局审计 |
|
||||
| `task.<name>` | runner → bus | `TaskContext` | 任务链 |
|
||||
| `task.done` / `task.failed` | runner → bus | `TaskRun` | 运行结果 |
|
||||
| `rpc.request` / `rpc.reply` | RpcHub 内部 | `RpcRequest` / `RpcReply` | 不建议业务直接订阅 |
|
||||
| `error` | bus 内部 | 异常 | handler 异常统一出口 |
|
||||
|
||||
```python
|
||||
class ChannelMessage(BaseModel):
|
||||
model_config = ConfigDict(frozen=True)
|
||||
channel_id: str
|
||||
channel_type: str
|
||||
subject_id: str
|
||||
session_key: str
|
||||
message: InboundMessage
|
||||
received_at: datetime
|
||||
|
||||
class OutboundText(BaseModel):
|
||||
channel_id: str
|
||||
subject_id: str
|
||||
text: str
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 迁移计划
|
||||
|
||||
### 阶段 1:加桥,不改行为(✅ 已实施)
|
||||
|
||||
- `EventBus`:`bind_loop` / `publish_threadsafe` / `publish`·`subscribe` 别名。
|
||||
- `flows/rpc.py`:`RpcHub` + 单测(成功/超时/远端异常/未注册方法/并发)。
|
||||
- `BaseChannel.attach(publish=...)` 与旧 `processor` 双轨:`handle_inbound` 先 `publish` 再走旧逻辑。
|
||||
- `ChannelRegistry` 补 `get_latest_message` / `send_text` / `resolve_subject`(复用现有 `_known_subjects`)。
|
||||
|
||||
验收:现有 141 个测试全绿 + 新增 RPC 测试;行为无变化(旧 processor 仍在跑)。
|
||||
|
||||
### 阶段 2:切执行面(✅ 已实施)
|
||||
|
||||
- `TaskRunner`:分区槽、`queue_limit`/`overflow`、`wait_idle`、`deps`。
|
||||
- 内置 `AgentReply` 任务;`run_session` 改新链路;`processor` 仅保留未迁移调用方。
|
||||
- 出站 RPC server 注册。
|
||||
|
||||
验收:CLI 会话端到端可用;同一 session 消息严格串行、不同 session 并行;发送失败可在任务侧捕获。
|
||||
|
||||
### 阶段 3:拆通道
|
||||
|
||||
- 删除 `_queues`/`_workers`/`_session_locks`/`_inflight`/`wait_idle`/`_worker_loop`/`_drain_same_session`。
|
||||
- 删除 `MessageProcessor`/`MessageEvent` 契约与 `flows/processor.py`。
|
||||
- 重写 `tests/test_channels*`、迁移 `test_processor.py`。
|
||||
|
||||
验收:`channels` 中不再出现"队列/处理器"字样;全量测试与 lint 通过。
|
||||
|
||||
---
|
||||
|
||||
## 11. 影响面
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `flows/bus.py` | `bind_loop` / `publish_threadsafe` / 别名 / `abort` 钩子 |
|
||||
| `flows/rpc.py` | **新增** RpcHub 与错误类型 |
|
||||
| `flows/tasks.py` | 分区槽、队列上限、`wait_idle`、`deps`、`partition_key` |
|
||||
| `flows/builtin.py` | **新增** `AgentReply` 等内置任务 |
|
||||
| `flows/processor.py` | 逻辑迁出,阶段 3 删除 |
|
||||
| `flows/session.py` | 装配与收尾顺序重写 |
|
||||
| `flows/__init__.py` | 导出 `RpcHub`/错误类型/`ChannelMessage`/`OutboundText` |
|
||||
| `channels/base.py` | `publish` 入口;删除 processor 流;`typing/delta` 原语;`resolve_subject` |
|
||||
| `channels/manager.py` | 收缩为 `ChannelRegistry`;两个对外接口;RPC server 实现 |
|
||||
| `channels/models.py` | `MessageEvent`/`MessageProcessor` 退役 |
|
||||
| `__main__.py` | 装配调整(一次性任务路径不变) |
|
||||
| `tests/*` | 见 §12 |
|
||||
| `docs/task-tutorial.md` | 新增"渠道消息任务"一节,链接本文 |
|
||||
|
||||
## 12. 测试计划
|
||||
|
||||
| 模块 | 用例 |
|
||||
|---|---|
|
||||
| RPC | 正常往返;超时;远端异常映射;未注册方法;并发 100 次;超时后迟到响应被丢弃;`abort_all` |
|
||||
| EventBus | 线程安全发布(跨线程 emit);重复注册;handler 异常不外泄(已有) |
|
||||
| channel | `publish` 只调用一次;主体登记;线程安全;`resolve_subject` 未知时报错 |
|
||||
| registry | `get_latest_message` 返回副本;`send_text` 路由到正确 subject;未知 channel/subject 报错 |
|
||||
| TaskRunner | 同分区串行(顺序断言);跨分区并行(最大并发 > 1);队列溢出策略;`wait_idle` 真等到完成;`deps` 注入 |
|
||||
| 会话 | CLI 端到端:多条消息串行处理、回复经 RPC 发出、退出时冲刷 |
|
||||
|
||||
## 13. 风险与缓解
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|---|---|
|
||||
| 删除 manager 队列后入站无背压 | TaskRunner 分区队列设上限 + 溢出告警;必要时 `overflow=block` |
|
||||
| `block` 策略可能导致 publisher 阻塞 → 渠道回调卡死 | 默认 `drop_new`;`block` 仅在显式配置时启用并加超时 |
|
||||
| RPC 增加一跳,延迟增加 | 进程内一跳(microtask 级),可忽略;出站若极端敏感可走直调 A |
|
||||
| 事件化后调试链路变长 | 统一 `run_id`/`correlation_id` 打日志;`rpc.audit` 可选开启 |
|
||||
| 阶段 1 双轨期存在两条处理路径 | 双轨仅一个阶段,验收标准明确(旧测试全绿 + 新事件被发布) |
|
||||
|
||||
## 14. 已确认决策(2026-11-09)
|
||||
|
||||
1. **分区键**:`session_key`(一用户/一群一条链,同渠道不同用户并行)。`channel_id` 作为 `session_key` 缺失时的兜底。
|
||||
2. **队列溢出**:`drop_new` —— 新触发记 `RunStatus.FAILED`(`error="queue overflow"`)+ 发 `task.failed`,不做背压阻塞。
|
||||
3. **出站**:采用 **RPC 出站**(§8 B),方法名 `channel.send`;直调 `registry.send_text` 保留为单元测试与无总线场景的替代路径。
|
||||
4. **RPC 命名**:方法名点分(`channel.send`);总线事件固定为 `rpc.request` / `rpc.reply`,不引入 `rpc.<method>` 动态事件。
|
||||
|
||||
## 15. 后续扩展(本轮不做)
|
||||
|
||||
- `batch_window_ms`:同分区短窗口合并多条入站消息再派发(替代原 `merge_inbound`)。
|
||||
- RPC 多响应者/聚合模式、服务发现(`served()` 已预留)。
|
||||
- 出站事件旁路审计:`channel.outbound`(只观测不发送)与 RPC 并存。
|
||||
- 任务级并发上限(每分区 `max_concurrency`)。
|
||||
@@ -0,0 +1,631 @@
|
||||
# 任务(Task)编写教程
|
||||
|
||||
任务系统解决三件事:**什么时候跑**(定时 / 监听触发)、**堆叠怎么办**
|
||||
(SKIP / QUEUE / PARALLEL / REPLACE)、**跑得怎么样**(`TaskRun` 运行记录、
|
||||
`on_error` 钩子、事件通知)。任务体二选一:过程式覆写 `run()`;多步编排
|
||||
(DAG、条件分支、并行扇出)则覆写 `build_graph()` 把 LangGraph 图作为任务体。
|
||||
|
||||
---
|
||||
|
||||
## 1. 写一个最小任务
|
||||
|
||||
任务是一个类:继承 `Task`,**显式声明** `name`(不从文件名/函数名推断),
|
||||
实现 `run()`(多步编排则改覆写 `build_graph()`,见第 6 章)。每次触发都
|
||||
**新建实例**再运行,实例间状态隔离。
|
||||
|
||||
```python
|
||||
from bot042.flows import Task, TaskContext
|
||||
|
||||
|
||||
class DailyReport(Task):
|
||||
name = "report.daily" # 显式声明:字母数字与 _ . -
|
||||
|
||||
def __init__(self, context: TaskContext) -> None:
|
||||
super().__init__(context)
|
||||
self.rows: list[str] = [] # 本次运行的独立状态
|
||||
|
||||
async def run(self) -> None:
|
||||
self.rows.append("fetch data")
|
||||
self.rows.append("render") # 失败直接抛异常
|
||||
```
|
||||
|
||||
命名规则 `^[A-Za-z0-9_.-]+$`;缺名、非法名、重名都会在注册时报错。
|
||||
|
||||
## 2. 注册与触发
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from datetime import timedelta
|
||||
|
||||
from bot042.flows import (
|
||||
CronTrigger,
|
||||
EventBus,
|
||||
EventTrigger,
|
||||
IntervalTrigger,
|
||||
OnceTrigger,
|
||||
TaskRunner,
|
||||
)
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bus = EventBus()
|
||||
runner = TaskRunner(bus)
|
||||
|
||||
runner.register(DailyReport) # 登记任务类(按其 name)
|
||||
runner.add_task("report.daily", CronTrigger(expr="0 9 * * *")) # 定时
|
||||
runner.add_task("report.daily", EventTrigger(event="demo.hello")) # 监听
|
||||
|
||||
await runner.start()
|
||||
bus.emit("demo.hello", {"from": "cli"}) # 立刻触发一次
|
||||
await bus.wait_for_complete()
|
||||
await runner.stop()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
- **定时触发**:`CronTrigger`(5 字段 cron)/ `OnceTrigger(at=...)` /
|
||||
`IntervalTrigger(every=...)`,复用 `Schedule`/`Scheduler`;内部调度名为
|
||||
`<任务名>.<序号>`(如 `report.daily.1`),触发事件 `schedule.<调度名>`,
|
||||
载荷为 `Fire`(含 `scheduled_time`,可作幂等键)。
|
||||
- **监听触发**:`EventTrigger(event=...)`,载荷为 `emit` 的首个参数。
|
||||
- 同一任务可绑**多个触发器**;`start()` 之后再 `add_task` 立即生效。
|
||||
|
||||
## 3. 堆叠策略(同一任务被重复触发时)
|
||||
|
||||
任务执行需 5s、但要求每 3s 触发一次——上一次没跑完又来了怎么办?
|
||||
用类属性 `overlap` 声明(缺省 `SKIP`):
|
||||
|
||||
```python
|
||||
from bot042.flows import OverlapPolicy
|
||||
|
||||
|
||||
class Slow(Task):
|
||||
name = "demo.slow"
|
||||
overlap = OverlapPolicy.SKIP # 可省略,默认就是 SKIP
|
||||
|
||||
async def run(self) -> None:
|
||||
... # 耗时 5s
|
||||
```
|
||||
|
||||
| 策略 | 行为 | 记录 |
|
||||
|---|---|---|
|
||||
| `SKIP`(默认) | 跳过本次触发 | `skipped` |
|
||||
| `QUEUE` | 串行排队执行;积压上限 1 条,超出跳过 | 排队的正常记录,超出的 `skipped` |
|
||||
| `PARALLEL` | 各自并行执行(并发不设上限) | 各自独立记录 |
|
||||
| `REPLACE` | 取消正在运行的,立即执行新的 | 被取消的记 `cancelled` |
|
||||
|
||||
策略按**任务名**全局生效(跨该任务的全部触发器)。
|
||||
|
||||
## 4. 失败处理:`on_error` 钩子
|
||||
|
||||
`run()` 抛异常 → 运行记 `failed`(含错误文本)、发 `task.failed` 事件,
|
||||
并调用当次实例的 `on_error`。钩子内的异常只记日志,不影响记录。
|
||||
|
||||
```python
|
||||
from bot042.flows import Task, TaskContext, TaskRun
|
||||
|
||||
|
||||
class Notify(Task):
|
||||
name = "demo.notify"
|
||||
|
||||
async def run(self) -> None:
|
||||
raise RuntimeError("smtp down")
|
||||
|
||||
async def on_error(self, exc: BaseException) -> None:
|
||||
# 失败收尾:告警、补偿、清理……(可选覆写)
|
||||
await send_alert(f"{self.context.run_id} failed: {exc}")
|
||||
|
||||
|
||||
async def watch_failures(bus) -> None:
|
||||
@bus.on("task.failed")
|
||||
async def _on_failed(run: TaskRun) -> None:
|
||||
print("失败了:", run.task, run.run_id, run.error)
|
||||
```
|
||||
|
||||
注意:`on_error` 只覆盖 `run()` 抛出的异常;`__init__` 失败仅记录运行
|
||||
(此时无实例,钩子不可用)。
|
||||
|
||||
## 5. 运行跟踪:谁在什么时候失败了
|
||||
|
||||
每次执行生成一条 `TaskRun`(`run_id` / `status` / `error` / 时间戳),
|
||||
`run_id` 同时出现在 `TaskContext`、日志与事件载荷里,可跨系统关联。
|
||||
|
||||
```python
|
||||
runs = runner.runs("report.daily", limit=20) # 最近 20 条运行记录
|
||||
stats = runner.stats("report.daily") # 计数 + 最近一次错误
|
||||
print(stats.succeeded, stats.failed, stats.skipped, stats.last_error)
|
||||
```
|
||||
|
||||
运行记录只保留最近 `runs_limit` 条(`TaskRunner(bus, runs_limit=200)`,缺省
|
||||
200);`runs(limit=0)` 返回全部保留记录。
|
||||
|
||||
任务完成会发两类事件:
|
||||
|
||||
- `task.<任务名>`(仅成功)——用于**任务链**:下游任务监听它即可串联;
|
||||
- `task.done`(每次运行结束,载荷 `TaskRun`)——通用跟踪/落库。
|
||||
|
||||
```python
|
||||
runner.add_task("a", EventTrigger(event="start"))
|
||||
runner.add_task("b", EventTrigger(event="task.a")) # a 成功后自动跑 b
|
||||
```
|
||||
|
||||
任务链不要形成环(如任务监听自己的 `task.<名>` 会无限触发)。
|
||||
|
||||
## 6. 图任务体:用 build_graph() 把 LangGraph 图作为任务体
|
||||
|
||||
任务内部有多个步骤、条件分支或并行扇出时,把任务体写成一张
|
||||
[LangGraph](https://langchain-ai.github.io/langgraph/) 状态图:覆写
|
||||
`build_graph()` 返回编译好的图,缺省的 `run()` 执行该图并把最终 state 存进
|
||||
`self.result`。命名/堆叠/`on_error`/运行跟踪与过程式任务完全一致(同一个
|
||||
`Task` 基类,任务体二选一;`GraphTask` 是 `Task` 的兼容别名,旧代码照常可用)。
|
||||
|
||||
分工:`TaskRunner` 管"什么时候跑、堆叠怎么办、跑得怎么样";图管"一次运行
|
||||
内部怎么走"。
|
||||
|
||||
约定(与 LangGraph 惯用法一致):
|
||||
|
||||
- **每次执行新建图**(在 `build_graph()` 里构建,不要做模块级单例);
|
||||
- 节点只返回**增量 dict**,绝不返回整个 state;
|
||||
- list 字段配 reducer(如 `Annotated[list[str], operator.add]`)避免并行覆盖;
|
||||
- 硬编码阈值放**纯函数路由**里,不要交给 LLM 判断。
|
||||
|
||||
### 6.1 最小骨架
|
||||
|
||||
```python
|
||||
from typing import Any
|
||||
|
||||
from langgraph.graph import END, StateGraph
|
||||
|
||||
from bot042.flows import Task, TaskContext
|
||||
|
||||
|
||||
class DailyReport(Task):
|
||||
name = "report.daily" # 显式命名,照旧
|
||||
|
||||
def build_graph(self) -> Any:
|
||||
builder = StateGraph(State)
|
||||
builder.add_node("collect", self._collect)
|
||||
builder.add_node("render", self._render)
|
||||
builder.set_entry_point("collect")
|
||||
builder.add_edge("collect", "render")
|
||||
builder.add_edge("render", END)
|
||||
return builder.compile() # 每次执行新建图,勿做模块级单例
|
||||
|
||||
def initial_state(self) -> dict[str, Any]:
|
||||
# 运行期数据从 self.context 注入(payload / run_id / fired_at …)
|
||||
return {"query": self.context.payload, "trace": []}
|
||||
|
||||
async def _collect(self, state: State) -> dict[str, Any]:
|
||||
return {"rows": await fetch_rows(state["query"]), "trace": ["collect"]}
|
||||
|
||||
async def _render(self, state: State) -> dict[str, Any]:
|
||||
return {"answer": render(state["rows"]), "trace": ["render"]}
|
||||
```
|
||||
|
||||
缺省 `run()` 的实现(覆写 `build_graph()` 后无需再写 `run()`):
|
||||
|
||||
```python
|
||||
async def run(self) -> None:
|
||||
graph = self.build_graph() # 每次执行新建
|
||||
self.result = dict(await graph.ainvoke(self.initial_state()))
|
||||
```
|
||||
|
||||
最终 state 存在 **`self.result`**(每次执行的实例内独立);要后处理就在子类
|
||||
里覆写 `run()` 并 `await super().run()`。图节点抛异常 → 整次运行记
|
||||
`failed` → `on_error` 钩子照常触发。
|
||||
|
||||
### 6.2 State:图的流转数据
|
||||
|
||||
State 用 `TypedDict`。两条纪律:
|
||||
|
||||
1. **节点只返回增量 dict**,绝不 `return state`——返回值是"要合并进
|
||||
state 的更新",不是新 state。
|
||||
2. **list 字段一律挂 reducer**,否则并行节点会互相覆盖:
|
||||
|
||||
```python
|
||||
import operator
|
||||
from typing import Annotated, TypedDict
|
||||
|
||||
|
||||
class State(TypedDict):
|
||||
query: str
|
||||
rows: list[dict]
|
||||
answer: str
|
||||
# 带 reducer 的审计日志:每个节点 append 自己的记录,不覆盖别人
|
||||
trace: Annotated[list[str], operator.add]
|
||||
```
|
||||
|
||||
常用 reducer:`operator.add`(list 拼接)、`operator.or_`(dict 合并)。
|
||||
标量字段(`str`/`int`/`float`)默认"后写覆盖",让**一个节点独占一个字段**即可。
|
||||
|
||||
### 6.3 路由:纯函数,不交给 LLM
|
||||
|
||||
条件分支的判断逻辑写成**纯函数**(不碰网络、不调 LLM),100% 可单测;
|
||||
映射表要显式写出,拼错 key 编译期/启动期立刻报错:
|
||||
|
||||
```python
|
||||
from typing import Literal
|
||||
|
||||
|
||||
def route_by_temp(state: State) -> Literal["bbq", "train"]:
|
||||
"""硬规则放这里。让模型判断"30 度算不算热"只会引入不确定性。"""
|
||||
temp = state["temp_c"]
|
||||
if temp is None:
|
||||
return "train" # 拿不到数据走保守分支,trace 里留下降级记录
|
||||
return "bbq" if temp > 30.0 else "train"
|
||||
|
||||
|
||||
builder.add_conditional_edges(
|
||||
"read_temp",
|
||||
route_by_temp,
|
||||
{"bbq": "bbq", "train": "train"}, # 显式映射
|
||||
)
|
||||
```
|
||||
|
||||
节点内调 LLM / 外部服务是另一回事——**单点失败不该炸掉整条链路**,用
|
||||
降级返回代替抛异常:
|
||||
|
||||
```python
|
||||
async def read_temp(state: State) -> dict[str, Any]:
|
||||
try:
|
||||
temp = await deps.weather.shenzhen_temp_c()
|
||||
return {"temp_c": temp, "trace": [f"read_temp: {temp:.1f}°C"]}
|
||||
except Exception as exc:
|
||||
return {
|
||||
"temp_c": None,
|
||||
"trace": [f"read_temp: 取温度失败({type(exc).__name__}), 降级走 train"],
|
||||
}
|
||||
```
|
||||
|
||||
### 6.4 DAG 形态
|
||||
|
||||
LangGraph 的图结构天然就是 DAG(无环有向图)。常见四种形态:
|
||||
|
||||
#### 串行流水线
|
||||
|
||||
```
|
||||
collect → enrich → render → END
|
||||
```
|
||||
|
||||
```python
|
||||
builder.add_edge("collect", "enrich")
|
||||
builder.add_edge("enrich", "render")
|
||||
builder.add_edge("render", END)
|
||||
```
|
||||
|
||||
#### 条件分支(二选一 / 多选一)
|
||||
|
||||
```
|
||||
read_temp ──> bbq ──> END
|
||||
└────> train ──> END
|
||||
```
|
||||
|
||||
见 6.3 的 `add_conditional_edges`。
|
||||
|
||||
#### 并行扇出 + 汇合(fan-out / fan-in)
|
||||
|
||||
一个节点出多条边 → 并行执行;汇入同一节点时靠 reducer 合并结果:
|
||||
|
||||
```python
|
||||
class State(TypedDict):
|
||||
query: str
|
||||
answer: str
|
||||
trace: Annotated[list[str], operator.add] # 并行分支各自 append
|
||||
|
||||
|
||||
builder.add_node("bbq", run_bbq)
|
||||
builder.add_node("train", run_train)
|
||||
builder.add_node("merge", merge_answers)
|
||||
|
||||
builder.add_edge("read_temp", "bbq") # read_temp 完成后两个分支
|
||||
builder.add_edge("read_temp", "train") # 并行执行
|
||||
builder.add_edge("bbq", "merge") # 都完成后才进 merge
|
||||
builder.add_edge("train", "merge")
|
||||
builder.add_edge("merge", END)
|
||||
```
|
||||
|
||||
```python
|
||||
async def merge_answers(state: State) -> dict[str, Any]:
|
||||
# 两个分支的 trace 已被 reducer 拼好,直接合并业务结果
|
||||
return {"answer": combine(state.get("bbq_answer"), state.get("train_answer"))}
|
||||
```
|
||||
|
||||
#### 扇出到多个下游再分别收尾
|
||||
|
||||
不需要汇合时,各分支各自 `→ END`,互不等待(与上一节的区别:没有
|
||||
`merge` 节点,先完成的先结束)。
|
||||
|
||||
> 汇合语义提醒:LangGraph 等**所有**入边都完成后才执行汇合节点。
|
||||
> 只要有一条分支走了"跳过"路径,也要让它显式连到汇合节点(空增量
|
||||
> `return {}`),不要断链。
|
||||
|
||||
### 6.5 完整可跑示例
|
||||
|
||||
仿 graph-demo 的"烧烤 / 火车"路由场景,接进 TaskRunner:
|
||||
|
||||
```python
|
||||
"""图任务示例:按温度路由到烧烤/火车分支,可定时或事件触发。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import operator
|
||||
from typing import Annotated, Any, Literal, TypedDict
|
||||
|
||||
from langgraph.graph import END, StateGraph
|
||||
|
||||
from bot042.flows import (
|
||||
EventBus,
|
||||
EventTrigger,
|
||||
OverlapPolicy,
|
||||
Task,
|
||||
TaskRunner,
|
||||
)
|
||||
|
||||
THRESHOLD_C = 30.0 # 严格大于:30.0 不算"大于 30 度"
|
||||
|
||||
|
||||
class State(TypedDict):
|
||||
query: str
|
||||
temp_c: float | None
|
||||
branch: Literal["bbq", "train"] | None
|
||||
answer: str
|
||||
trace: Annotated[list[str], operator.add]
|
||||
|
||||
|
||||
class WeatherAdvice(Task):
|
||||
name = "advice.weather"
|
||||
overlap = OverlapPolicy.SKIP # 防止慢任务被反复触发堆叠
|
||||
|
||||
def build_graph(self) -> Any:
|
||||
builder = StateGraph(State)
|
||||
builder.add_node("read_temp", self._read_temp)
|
||||
builder.add_node("bbq", self._bbq)
|
||||
builder.add_node("train", self._train)
|
||||
builder.set_entry_point("read_temp")
|
||||
builder.add_conditional_edges(
|
||||
"read_temp",
|
||||
self._route_by_temp,
|
||||
{"bbq": "bbq", "train": "train"},
|
||||
)
|
||||
builder.add_edge("bbq", END)
|
||||
builder.add_edge("train", END)
|
||||
return builder.compile()
|
||||
|
||||
def initial_state(self) -> dict[str, Any]:
|
||||
return {
|
||||
"query": self.context.payload, # 触发事件的载荷即用户问题
|
||||
"temp_c": None,
|
||||
"branch": None,
|
||||
"answer": "",
|
||||
"trace": [],
|
||||
}
|
||||
|
||||
# ---- 纯函数路由 ----
|
||||
def _route_by_temp(self, state: State) -> Literal["bbq", "train"]:
|
||||
if state["temp_c"] is None:
|
||||
return "train"
|
||||
return "bbq" if state["temp_c"] > THRESHOLD_C else "train"
|
||||
|
||||
# ---- 节点:只返回增量 ----
|
||||
async def _read_temp(self, state: State) -> dict[str, Any]:
|
||||
_ = state
|
||||
temp = await get_weather() # 换成真实依赖
|
||||
return {"temp_c": temp, "trace": [f"read_temp: {temp:.1f}°C"]}
|
||||
|
||||
async def _bbq(self, state: State) -> dict[str, Any]:
|
||||
spots = await search_bbq(state["query"])
|
||||
return {
|
||||
"branch": "bbq",
|
||||
"answer": format_bbq(spots),
|
||||
"trace": [f"bbq: {len(spots)} 家店"],
|
||||
}
|
||||
|
||||
async def _train(self, state: State) -> dict[str, Any]:
|
||||
options = await query_trains(state["query"])
|
||||
return {
|
||||
"branch": "train",
|
||||
"answer": format_train(options),
|
||||
"trace": [f"train: {len(options)} 个车次"],
|
||||
}
|
||||
|
||||
async def run(self) -> None:
|
||||
await super().run() # 图执行,结果进 self.result
|
||||
# 例:把结果发回通道 / 落库(失败抛异常即可进 on_error)
|
||||
await publish(self.result["answer"])
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bus = EventBus()
|
||||
runner = TaskRunner(bus)
|
||||
runner.register(WeatherAdvice)
|
||||
runner.add_task("advice.weather", EventTrigger(event="user.question"))
|
||||
await runner.start()
|
||||
|
||||
bus.emit("user.question", "深圳晚上有什么烧烤好吃的")
|
||||
await bus.wait_for_complete()
|
||||
|
||||
run = runner.runs("advice.weather")[0]
|
||||
print(run.status, run.run_id) # succeeded / failed 一目了然
|
||||
await runner.stop()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### 6.6 运行期注入:deps 与单例纪律
|
||||
|
||||
- **每次执行新建实例、新建图**。业务依赖(HTTP 客户端、DB、配置)在
|
||||
`__init__`/属性上持有,或从 `self.context` 取——不要做模块级单例图,
|
||||
否则 `initial_state` 和依赖会串到别的运行上。
|
||||
- `self.context`(`TaskContext`)提供:`run_id`(与 `TaskRun`/日志关联)、
|
||||
`task`、`event`、`fired_at`、`payload`。
|
||||
- `self.result` 是图的最终 state——需要跨任务传递时发事件:
|
||||
|
||||
```python
|
||||
async def run(self) -> None:
|
||||
await super().run()
|
||||
# 结果交给下游任务(下游 add_task(..., EventTrigger(event="task.advice.weather")))
|
||||
```
|
||||
|
||||
(成功时系统自动发 `task.<任务名>` 事件,载荷为 `TaskContext`;下游任务
|
||||
监听它即可串成任务链。)
|
||||
|
||||
### 6.7 断点续跑(可选)
|
||||
|
||||
传 checkpointer 给 `compile()` 即可获得断点续跑 + thread 隔离,这是长时
|
||||
编排的开关:
|
||||
|
||||
```python
|
||||
from langgraph.checkpoint.memory import MemorySaver # 落盘用 SqliteSaver
|
||||
|
||||
|
||||
class LongFlow(Task):
|
||||
name = "flow.long"
|
||||
|
||||
def build_graph(self) -> Any:
|
||||
...
|
||||
return builder.compile(checkpointer=MemorySaver())
|
||||
```
|
||||
|
||||
注意:缺省 `run()` 调 `ainvoke` 时未传 `config`,要按 `run_id` 隔离
|
||||
thread 的话覆写 `run()`:
|
||||
|
||||
```python
|
||||
async def run(self) -> None:
|
||||
graph = self.build_graph()
|
||||
self.result = dict(
|
||||
await graph.ainvoke(
|
||||
self.initial_state(),
|
||||
config={"configurable": {"thread_id": self.context.run_id}},
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
### 6.8 测试
|
||||
|
||||
图结构与路由是纯逻辑,离线即可测(参考 graph-demo 的 Stub 模式——依赖
|
||||
换假实现,不烧 token):
|
||||
|
||||
```python
|
||||
def test_route_by_temp() -> None:
|
||||
task = WeatherAdvice.__new__(WeatherAdvice) # 路由不依赖 __init__
|
||||
assert task._route_by_temp({"temp_c": 31.0}) == "bbq"
|
||||
assert task._route_by_temp({"temp_c": 30.0}) == "train" # 严格大于
|
||||
assert task._route_by_temp({"temp_c": None}) == "train" # 降级分支
|
||||
```
|
||||
|
||||
集成层面跑一遍完整生命周期(注册 → 触发 → `runs()` 断言),见
|
||||
`tests/test_tasks.py` 里的 `test_graph_task_*` 用例。
|
||||
|
||||
## 7. 从脚本目录批量加载
|
||||
|
||||
```python
|
||||
names = runner.load_scripts(home / "scripts") # 扫 *.py 中定义的 Task 子类
|
||||
# 返回登记的任务名列表;脚本导入失败记日志跳过,
|
||||
# 任务类声明不合法(缺 name / 重名 / 任务体缺失)直接报错,
|
||||
# 且此时不会注册任何任务(先整体校验再提交,不留半注册状态)
|
||||
```
|
||||
|
||||
## 8. 完整骨架
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from bot042.flows import EventBus, EventTrigger, Task, TaskRunner
|
||||
|
||||
|
||||
class Hello(Task):
|
||||
name = "demo.hello"
|
||||
|
||||
async def run(self) -> None:
|
||||
print(f"[{self.context.run_id}] hello {self.context.payload}")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
bus = EventBus()
|
||||
runner = TaskRunner(bus)
|
||||
runner.register(Hello)
|
||||
runner.add_task("demo.hello", EventTrigger(event="demo.hello"))
|
||||
await runner.start()
|
||||
bus.emit("demo.hello", "world")
|
||||
await bus.wait_for_complete()
|
||||
await runner.stop()
|
||||
print(runner.stats("demo.hello"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## 9. 渠道消息任务(`channel.inbound` → 任务 → RPC 回复)
|
||||
|
||||
渠道不再自带处理器:`handle_inbound` 解析后把消息发布到事件总线,任务负责
|
||||
处理与回复。链路与取舍见 [channel-eventbus-design.md](channel-eventbus-design.md)。
|
||||
|
||||
```python
|
||||
from bot042.flows import ChannelMessage, OutboundText, Task, TaskContext, OverlapPolicy
|
||||
|
||||
|
||||
class Echo(Task):
|
||||
name = "channel.echo"
|
||||
overlap = OverlapPolicy.QUEUE # 同会话排队,不丢消息
|
||||
|
||||
@staticmethod
|
||||
def partition_key(ctx: TaskContext) -> str:
|
||||
# 分区 = 会话历史键:同一会话串行,不同会话并行
|
||||
# (不要用 session_key——群聊里它是发送者,会把同一会话拆成多条链)
|
||||
payload = ctx.payload
|
||||
return payload.db_session_id if isinstance(payload, ChannelMessage) else ""
|
||||
|
||||
async def run(self) -> None:
|
||||
payload = self.context.payload
|
||||
assert isinstance(payload, ChannelMessage)
|
||||
text = payload.message.text.strip()
|
||||
# deps 由 TaskRunner(bus, deps=...) 注入(生产环境是 ChannelServices)
|
||||
await self.deps.hub.call(
|
||||
"channel.send",
|
||||
OutboundText(
|
||||
channel_id=payload.channel_id,
|
||||
subject_id=payload.subject_id,
|
||||
text=text,
|
||||
),
|
||||
timeout=10,
|
||||
)
|
||||
```
|
||||
|
||||
注册方式与普通任务一致:
|
||||
|
||||
```python
|
||||
runner.add_task("channel.echo", EventTrigger(event="channel.inbound"))
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- **载荷**是 `ChannelMessage`(`channel_id` / `subject_id` / `session_key` / `message`);
|
||||
- **回复必须显式发送**:任务不再返回"事件流",用 `channel.send` RPC(可拿到
|
||||
发送成功/失败)或 `deps.channels.send_text(...)`(无总线场景);
|
||||
- **分区键**决定串行范围:`session_key` = 按用户/群,`channel_id` = 整条渠道;
|
||||
- **积压**默认上限 100,超出按 `drop_new` 记 `failed`(`runners.stats` 可见);
|
||||
- 收尾用 `await runner.wait_idle()`,不要用渠道管理器的 `wait_idle`。
|
||||
|
||||
内置的 `AgentReply`(`name="channel.agent"`)已按这套链路实现"读历史 → 调
|
||||
智能体 → 落库 → 回复",用 `run_session` 时自动注册,通常无需自己写。
|
||||
|
||||
## 常见坑
|
||||
|
||||
- **忘记显式 `name`**:注册时报"任务名缺失或非法"——任务名必须写在类上。
|
||||
- **任务名叫 `done` / `failed`**:与运行结束事件同名,注册时直接拒绝。
|
||||
- **任务链成环**:任务监听自己的 `task.<名>` 会无限触发,串链时检查方向。
|
||||
- **`task.<名>` 只在成功时发**:失败要看 `task.failed` / `task.done`。
|
||||
- **消息任务不回复**:任务只"处理"不"发送";忘记 `channel.send` 时用户看不到任何输出。
|
||||
- **节点 `return state`**:会整包覆盖并行分支的更新——只返回增量 dict。
|
||||
- **并行分支写同一 list 字段没挂 reducer**:后写覆盖先写,结果随机丢。
|
||||
- **模块级单例图**:依赖/state 串运行,缓存编译好的图等于放弃"每次新建"。
|
||||
- **路由函数里调 LLM / 网络**:不可测、不确定;硬规则用纯函数,取不到
|
||||
数据走降级分支并在 `trace` 留记录。
|
||||
- **汇合分支断链**:跳过路径也要连到汇合节点(`return {}`),否则汇合
|
||||
永远等不齐。
|
||||
- **条件映射拼错 key**:写显式映射表 `{"bbq": "bbq", ...}`,别用魔法推断。
|
||||
Reference in new issue
Block a user