Files
bot042/docs/task-tutorial.md
openbot fbb01c4c83 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
2026-11-09 20:32:25 +08:00

632 lines
21 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.
# 任务(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", ...}`,别用魔法推断。