- 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
21 KiB
任务(Task)编写教程
任务系统解决三件事:什么时候跑(定时 / 监听触发)、堆叠怎么办
(SKIP / QUEUE / PARALLEL / REPLACE)、跑得怎么样(TaskRun 运行记录、
on_error 钩子、事件通知)。任务体二选一:过程式覆写 run();多步编排
(DAG、条件分支、并行扇出)则覆写 build_graph() 把 LangGraph 图作为任务体。
1. 写一个最小任务
任务是一个类:继承 Task,显式声明 name(不从文件名/函数名推断),
实现 run()(多步编排则改覆写 build_graph(),见第 6 章)。每次触发都
新建实例再运行,实例间状态隔离。
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. 注册与触发
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):
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。钩子内的异常只记日志,不影响记录。
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、日志与事件载荷里,可跨系统关联。
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)——通用跟踪/落库。
runner.add_task("a", EventTrigger(event="start"))
runner.add_task("b", EventTrigger(event="task.a")) # a 成功后自动跑 b
任务链不要形成环(如任务监听自己的 task.<名> 会无限触发)。
6. 图任务体:用 build_graph() 把 LangGraph 图作为任务体
任务内部有多个步骤、条件分支或并行扇出时,把任务体写成一张
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 最小骨架
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()):
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。两条纪律:
- 节点只返回增量 dict,绝不
return state——返回值是"要合并进 state 的更新",不是新 state。 - list 字段一律挂 reducer,否则并行节点会互相覆盖:
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 编译期/启动期立刻报错:
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 / 外部服务是另一回事——单点失败不该炸掉整条链路,用 降级返回代替抛异常:
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
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 合并结果:
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)
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:
"""图任务示例:按温度路由到烧烤/火车分支,可定时或事件触发。"""
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——需要跨任务传递时发事件:
async def run(self) -> None:
await super().run()
# 结果交给下游任务(下游 add_task(..., EventTrigger(event="task.advice.weather")))
(成功时系统自动发 task.<任务名> 事件,载荷为 TaskContext;下游任务
监听它即可串成任务链。)
6.7 断点续跑(可选)
传 checkpointer 给 compile() 即可获得断点续跑 + thread 隔离,这是长时
编排的开关:
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():
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):
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. 从脚本目录批量加载
names = runner.load_scripts(home / "scripts") # 扫 *.py 中定义的 Task 子类
# 返回登记的任务名列表;脚本导入失败记日志跳过,
# 任务类声明不合法(缺 name / 重名 / 任务体缺失)直接报错,
# 且此时不会注册任何任务(先整体校验再提交,不留半注册状态)
8. 完整骨架
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。
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,
)
注册方式与普通任务一致:
runner.add_task("channel.echo", EventTrigger(event="channel.inbound"))
要点:
- 载荷是
ChannelMessage(channel_id/subject_id/session_key/message); - 回复必须显式发送:任务不再返回"事件流",用
channel.sendRPC(可拿到 发送成功/失败)或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", ...},别用魔法推断。