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

21 KiB
Raw Permalink Blame History

任务(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。两条纪律:

  1. 节点只返回增量 dict,绝不 return state——返回值是"要合并进 state 的更新",不是新 state。
  2. 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.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", ...},别用魔法推断。