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