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