feat(agent-runner): finalize 4.x processor integration

2026-07-17 01:46:07 +00:00 · 2026-07-12 15:44:05 +08:00
parent 29689962f3
commit e6384aae5d
109 changed files with 2200 additions and 1204 deletions
@@ -143,7 +143,7 @@ pkg/platform/adapters/

 ### 3.4 事件处理器（Event Handler）

-> **2026-06 方向修订**：四种处理器的分类法已演进为「事件 → Agent」统一编排——所有编排目标（流水线、RequestRunner、webhook、工作流）收编为 Agent 抽象，插件 EventListener 保留为观察者角色。详见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本节保留原设计供对照。
+> **2026-06 方向修订**：四种 Handler 分类法已演进为「事件 → 处理器」统一路由。Pipeline 与 Agent 是长期并存、场景不同的同级处理器：Pipeline 面向消息事件的完整 Stage 链，Agent 面向其声明支持的消息或非消息事件；插件 EventListener 保留为观察者角色。详见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本节保留原设计供对照。

 四种处理器类型，用户在 WebUI 的 Bot 管理页面配置：

@@ -187,7 +187,7 @@ pkg/platform/adapters/
 | [04-event-routing.md](./04-event-routing.md) | 事件路由与编排：路由引擎、处理器类型、WebUI 数据模型 |
 | [05-plugin-sdk.md](./05-plugin-sdk.md) | 插件 SDK 改造：新事件/API、兼容层 |
 | [06-migration-plan.md](./06-migration-plan.md) | 分阶段迁移计划 |
-| [07-agent-orchestration.md](./07-agent-orchestration.md) | **产品最终形态（2026-06 修订）**：Agent 统一编排、SDK Agent 组件契约、发布火车 |
+| [07-agent-orchestration.md](./07-agent-orchestration.md) | **产品最终形态（2026-06 修订）**：Pipeline / Agent 同级处理器编排、SDK Agent 组件契约、发布火车 |

 ## 6. 涉及的代码仓库

@@ -1,6 +1,6 @@
 # 事件路由与编排

-> **2026-06 方向修订**：本文档的四种 handler_type（pipeline / agent / webhook / plugin）分类法已被「事件 → Agent」统一编排取代，收编映射与新数据模型见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本文档中的事件匹配规则（§4）、`use_pipeline_uuid` 迁移策略（§6）、WebUI 交互骨架（§7）与 webhook 请求/响应格式（§5.4）仍然有效，将在 Agent 模型下沿用。
+> **2026-06 方向修订**：本文档的四种 handler_type（pipeline / agent / webhook / plugin）分类法已被「事件 → 处理器（Agent / Pipeline）」统一编排取代，收编映射与新数据模型见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本文档中的事件匹配规则（§4）、`use_pipeline_uuid` 路由迁移策略（§6）、WebUI 交互骨架（§7）与 webhook 请求/响应格式（§5.4）仍然有效。

 ## 1. 概述

@@ -601,6 +601,8 @@ class PluginHandler(AbstractEventHandler):

 数据库迁移脚本将现有的 `use_pipeline_uuid` 自动转换为 `event_handlers`：

+这里迁移的只有 Bot 路由字段：binding 仍指向原 Pipeline，不会新建 Agent，也不会复制 Pipeline 内嵌的 runner 配置。
+
 ```python
 # 迁移逻辑
 for bot in all_bots:
@@ -1,6 +1,6 @@
 # 分阶段迁移计划

-> **2026-06 方向修订**：Phase 3 的「四种 Handler 框架」与 Phase 5 的编排面板形态，按 [07-agent-orchestration.md](./07-agent-orchestration.md) 调整为「事件 → Agent」统一编排（EventRouter + Agent 实体 + 绑定模型 + SDK Agent 组件契约）。阶段划分、依赖关系与验收标准仍然适用，按 Agent 模型重新解读即可；发布节奏见 07 §5「发布火车」。
+> **2026-06 方向修订**：Phase 3 的「四种 Handler 框架」与 Phase 5 的编排面板形态，按 [07-agent-orchestration.md](./07-agent-orchestration.md) 调整为「事件 → 处理器」统一路由。EventRouter 通过 `target_type` 在同级 Pipeline / Agent 间选择；二者分别保留自己的实体、配置和执行链。阶段划分、依赖关系与验收标准按 Processor 模型解读；发布节奏见 07 §5「发布火车」。

 ## 1. 概述

@@ -141,6 +141,8 @@ EBA 架构涉及 langbot-plugin-sdk、LangBot 后端、LangBot 前端、文档

 现有 Bot 表有 `use_pipeline_uuid` 字段，需要自动迁移为 `event_handlers`：

+该步骤只改写 Bot 的路由表示，仍通过原 UUID 指向原 Pipeline；不得创建独立 Agent，也不得复制 Pipeline 内嵌的 runner 配置。用户需要 Agent 时自行新增并绑定。
+
 ```python
 # 迁移逻辑伪代码
 for bot in all_bots:
@@ -1,12 +1,12 @@
-# Agent 统一编排（产品最终形态）
+# Agent 与 Pipeline 统一编排（产品最终形态）

 > **状态**：方向修订稿（2026-06-12），供「适配器改造 / Agent 插件化 / 工作流引擎」三条工作线评审。
 >
-> 本文档修订 [00-overview.md](./00-overview.md) §3.4 与 [04-event-routing.md](./04-event-routing.md) 中"四种 Handler"的编排模型：**所有编排目标统一收编为 Agent 抽象**。事件路由的匹配机制、数据迁移策略、WebUI 交互骨架等内容仍以 04 为准，仅 handler 分类法被本文档取代。
+> 本文档修订 [00-overview.md](./00-overview.md) §3.4 与 [04-event-routing.md](./04-event-routing.md) 中"四种 Handler"的编排模型：**所有编排目标统一进入处理器选择与事件绑定界面，但独立 Agent 与现有 Pipeline 保持不同类型**。事件路由的匹配机制、数据迁移策略、WebUI 交互骨架等内容仍以 04 为准，仅 handler 分类法被本文档取代。

 ## 1. 产品最终形态

-**适配器接收各种事件 → 用户编排处理逻辑 → Agent 统一抽象**，实现从 0 代码到低代码再到全代码的全层面支持：
+**适配器接收各种事件 → 用户编排处理逻辑 → 处理器统一选择表面**，实现从 0 代码到低代码再到全代码的全层面支持：

 ```
 消息平台 (Telegram / Discord / 企微 / ...)
@@ -15,20 +15,18 @@
 平台适配器（EBA 新结构，已迁移 12 个）
  │ EBAEvent (message.* / group.* / friend.* / bot.* / feedback.* / platform.*)
  ▼
-EventRouter（事件 → Agent 绑定）
-  ├─→ 选中的 Agent（响应者，单一仲裁）
-  │     ├─ 内置：pipeline-wrapper（旧流水线收编）/ local-agent
-  │     ├─ 插件：SDK Agent 组件（全代码）
-  │     ├─ 低代码：工作流定义的 Agent（内部工作流引擎）
-  │     └─ 外部：dify / n8n / coze / dashscope / webhook（RequestRunner 体系收编）
+EventRouter（事件 → 处理器绑定）
+  ├─→ 选中的处理器（响应者，单一仲裁）
+  │     ├─ Pipeline：保留现有实体和执行链，仅处理消息事件
+  │     └─ Agent：用户新建并选择 AgentRunner 插件，可接本地、低代码或外部 runtime
  │
  └─→ 插件 EventListener（观察者，N 个广播，可 prevent_default）
 ```

-| 编写方式 | Agent 形态 | 代码化程度 |
+| 编写方式 | 处理器形态 | 代码化程度 |
 |----------|-----------|-----------|
-| WebUI 配置模型 + 提示词 + 工具 | 内置 local-agent | 0 代码 |
-| 沿用现有流水线 | pipeline-wrapper 内置 Agent | 0 代码（兼容） |
+| WebUI 配置模型 + 提示词 + 工具 | 独立 Agent + LocalAgent 插件 | 0 代码 |
+| 可视化消息编排 | Pipeline（`kind=pipeline`，完整多 Stage 链） | 0 代码 |
 | 市场安装 | Agent 插件（市场分发） | 0 代码（使用者视角） |
 | 可视化工作流 | 工作流引擎定义的 Agent | 低代码 |
 | 对接外部平台 | dify / n8n / coze / webhook 外部 Agent | 集成 |
@@ -42,24 +40,24 @@ EventRouter（事件 → Agent 绑定）
 | Agent 插件化 | Agent 抽象、Agent 组件类型、市场分发 | 事件的**消费侧**统一抽象 |
 | 工作流引擎 | 内部低代码工作流 | Agent 的一种**编写方式** |

-**汇合点是 SDK 的 Agent 组件契约（§4）与 event→agent 绑定模型（§3）**。这两个接口冻结后，三条线可彼此 mock 独立推进。契约由本分支（EBA）牵头起草，三线评审后在 langbot-plugin-sdk 落地（发布通道：0.5.0aX pre-release 已打通）。
+**汇合点是 SDK 的 Agent 组件契约（§4）与 event→处理器绑定模型（§3）**。这两个接口冻结后，三条线可彼此 mock 独立推进。契约由本分支（EBA）牵头起草，三线评审后在 langbot-plugin-sdk 落地（发布通道：0.5.0aX pre-release 已打通）。

-## 2. 从四种 Handler 到 Agent 统一抽象
+## 2. 从四种 Handler 到统一处理器表面

 ### 2.1 演进理由

-04 文档中的 pipeline / agent / webhook / plugin 四种 handler_type，本质上都是"对事件作出响应的逻辑"，差别只在编写和部署方式。为四种类型分别设计配置表单、执行语义和扩展机制，等于把同一个概念做四遍。统一为 Agent 后：
+04 文档中的 pipeline / agent / webhook / plugin 四种 handler_type，本质上都是"对事件作出响应的逻辑"，差别只在编写和部署方式。产品层统一展示和绑定这些处理器，但不会把既有 Pipeline 持久化为 Agent：

- **产品**：用户只学一个概念——"给 Bot 的事件绑 Agent"；
- **工程**：路由层退化为很薄的 event → agent 分发，所有扩展集中到 Agent 抽象；
+- **产品**：用户只需理解"给 Bot 的事件绑定处理器"，处理器可以是 Pipeline 或 Agent；
+- **工程**：路由层按 `target_type` 分发到 Pipeline 或 Agent，Agent 的扩展集中到 AgentRunner 抽象；
 - **生态**：Agent 成为市场上可分发、可复用的一等公民。

 ### 2.2 收编映射

 | 原 handler_type（04 文档） | 收编后 |
 |---------------------------|--------|
-| `pipeline` | 内置 `pipeline-wrapper` Agent：实例配置为 `pipeline_uuid`，进程内直接复用 MessageAggregator → QueryPool → Pipeline 机制 |
-| `agent`（RequestRunner） | 现有 Runner 体系（local-agent / dify / n8n / coze / dashscope / langflow / tbox）整体收编为内置 Agent 家族——Runner 本来就是"Agent 抽象"的前身 |
+| `pipeline` | 保留 Pipeline 实体；binding 使用 `target_type=pipeline` 和原 `pipeline_uuid`，进程内直接复用 MessageAggregator → QueryPool → Pipeline 机制 |
+| `agent`（RequestRunner） | 用户新建独立 Agent，并选择对应 AgentRunner 插件；不读取或复制旧 Pipeline 内嵌 runner 配置 |
 | `webhook` | 外部 Agent 的一种：事件 POST 出去、响应解析为动作（保留 04 §5.4 的请求/响应格式） |
 | `plugin`（EventListener 分发） | **不收编**——角色不同，见 §2.3 |

@@ -67,26 +65,25 @@ EventRouter（事件 → Agent 绑定）

 事件的消费方有两种角色，不应混为一谈：

- **响应者（Agent）**：路由选中**一个**，负责对事件作出回应（回复消息、执行动作）。多条绑定匹配同一事件时按 priority 仲裁，只取最高者。
- **观察者（插件 EventListener）**：**广播**给所有注册插件，做旁路逻辑（日志、审计、风控、统计）。沿用现有机制不变，包括 `prevent_default()`——观察者可拦截本次事件，使 Agent 不被调用（与现有"插件拦截流水线"行为完全兼容）。
+- **响应者（Pipeline 或 Agent）**：路由选中**一个**，负责对事件作出回应（回复消息、执行动作）。多条绑定匹配同一事件时按 priority 仲裁，只取最高者。
+- **观察者（插件 EventListener）**：**广播**给所有注册插件，做旁路逻辑（日志、审计、风控、统计）。沿用现有机制不变，包括 `prevent_default()`——观察者可拦截本次事件，使处理器不被调用（与现有"插件拦截流水线"行为完全兼容）。

-执行顺序：事件到达 → 先广播观察者（按插件优先级）→ 若未被 prevent_default → 分发给选中的 Agent。
+执行顺序：事件到达 → 先广播观察者（按插件优先级）→ 若未被 prevent_default → 分发给选中的处理器。

-## 3. 数据模型：event → agent 绑定
+## 3. 数据模型：event → 处理器绑定

-### 3.1 Agent 实体化（推荐）
+### 3.1 独立 Agent 与现有 Pipeline

-Agent 作为一等实体（独立表），用户先创建/安装 Agent，再在 Bot 上把事件绑定到 Agent。好处：跨 Bot 复用、市场分发、独立的配置页面。
+Agent 与 Pipeline 都是一等处理器。用户创建 Agent、选择已安装的 AgentRunner，再把适合的事件绑定到 Agent；Pipeline 继续保存在 Pipeline 表中，以完整 Stage 链处理消息事件。两者可在同一处理器列表中以不同 `kind` 展示和选择；这种聚合展示不会创建额外记录，也不会在两种模型之间复制配置。

 ```python
 class Agent(Base):
    """Agent 实例：一个具体配置过的、可被事件绑定的响应者"""
    uuid: str                # 主键
    name: str
-    kind: str                # "builtin" | "plugin"
-    component_ref: str       # 内置: "pipeline-wrapper" / "local-agent" / "dify" / "webhook" / ...
-                             # 插件: "<plugin_author>/<plugin_name>/<agent_component_name>"
-    config: dict             # JSON — 实例配置（pipeline_uuid / 模型与提示词 / 外部平台凭据 / 工作流 id ...）
+    kind: str                # 固定为 "agent"；Pipeline 使用自己的持久模型
+    component_ref: str       # AgentRunner id，例如 plugin:<author>/<plugin>/<runner>
+    config: dict             # JSON — runner id、runner config 与资源/状态/投递策略
    # 多租户预留：归属主体字段（tenant/workspace），首版可空
 ```

@@ -94,14 +91,15 @@ Bot 上的绑定配置（替代 04 §2.2 的 EventHandlerConfig，沿用其匹

 ```python
 class EventBinding(pydantic.BaseModel):
-    event_type: str          # 精确 / "message.*" / "*"，匹配规则同 04 §4
-    agent_uuid: str          # 绑定的 Agent 实例
+    event_pattern: str       # 精确 / "message.*" / "*"，匹配规则同 04 §4
+    target_type: str         # "agent" | "pipeline" | "discard"
+    target_uuid: str         # Agent 或 Pipeline 的原始 UUID；discard 时为空
    enabled: bool = True
    priority: int = 0        # 多条匹配时取最高者（单一仲裁）
    description: str = ''
 ```

-`use_pipeline_uuid` 自动迁移：为每个被引用的 pipeline 生成一个 `pipeline-wrapper` Agent 实例，并写入 `{"event_type": "message.received", "agent_uuid": <wrapper>}` 绑定。观察者广播不需要配置（始终发生），04 中"兜底 plugin 规则"不再需要。
+`use_pipeline_uuid` 只迁移 Bot 的路由结构：写入 `{"event_pattern": "message.received", "target_type": "pipeline", "target_uuid": <原 pipeline uuid>}`，继续引用原 Pipeline。迁移不会创建独立 Agent，也不会复制 Pipeline 内嵌的 runner 配置；需要 Agent 的用户自行新增 Agent 并修改 binding。观察者广播不需要配置（始终发生），04 中"兜底 plugin 规则"不再需要。

 ## 4. SDK Agent 组件契约（草案）

@@ -156,16 +154,16 @@ class AgentChunk:
 ```

 **流式**：复用 SDK 通信协议既有的 `chunk_status: continue/end` 机制，`handle()` 的每次 yield 对应一个 chunk。
-**内置与插件同构**：内置 Agent（pipeline-wrapper、local-agent、各外部平台）在 LangBot 进程内实现同一接口注册，不过 RPC；插件 Agent 经 plugin runtime 分发。对路由层二者不可区分。
+**Pipeline 与 Agent 分流**：Pipeline target 继续走 LangBot 进程内的 Pipeline 执行链；独立 Agent 经 AgentRunner 插件 runtime 分发。路由层通过 binding 的 `target_type` 明确区分二者。

 ### 4.3 执行语义与可靠性

 | 关注点 | 约定 |
 |--------|------|
 | 仲裁 | 单响应者：priority 最高的匹配绑定生效，其余忽略 |
-| 性能 | 内置 Agent 进程内零额外开销；插件 Agent 每事件过一次 RPC 边界，消息场景需设延迟预算（评审项：目标 P95 附加延迟） |
+| 性能 | Pipeline 继续走进程内链路；插件 Agent 每事件过一次 RPC 边界，消息场景需设延迟预算（评审项：目标 P95 附加延迟） |
 | 会话状态 | 归 LangBot 侧（SessionHandle），插件 Agent 原则上无状态，崩溃重启不丢会话 |
-| 降级 | Agent 调用失败/超时：可配置 fallback（回错误提示，或指定备用 Agent）；pipeline-wrapper 作为进程内兜底与性能对照组 |
+| 降级 | Agent 调用失败/超时：可配置 fallback（回错误提示，或指定备用处理器）；不会隐式回退到旧 Pipeline 配置 |
 | 多租户预留 | AgentContext / SessionHandle / 存储接口显式携带归属主体标识，禁止新增全局单例状态——为后续轻量 SaaS 多租户铺路 |

 ## 5. 发布火车
@@ -173,7 +171,7 @@ class AgentChunk:
 | 版本 | 内容 | 备注 |
 |------|------|------|
 | 4.11（可选） | 现状成果：12 个 EBA 适配器、插件全事件订阅、`call_platform_api` | 对用户不可见的管道工程 + 插件新能力，不动产品概念 |
-| **5.0** | 产品形态首发：EventRouter + event→agent 绑定 + WebUI 编排 + 数据迁移 + 内置 Agent（pipeline-wrapper、local-agent、外部平台家族）+ SDK Agent 组件契约（可标 experimental） | 资格线不依赖其他两线交付；配 SDK 0.5.0 正式版；走 beta 周期；deprecation（旧 sources 适配器、legacy/*、use_pipeline_uuid）集中在此窗口处理 |
+| **5.0** | 产品形态首发：EventRouter + event→处理器绑定 + WebUI 编排 + 旧 Bot 路由迁移 + 独立 Agent / AgentRunner 插件 + SDK Agent 组件契约（可标 experimental） | `use_pipeline_uuid` 仅改写为指向原 Pipeline 的 binding，不生成 Agent；配 SDK 0.5.0 正式版；走 beta 周期 |
 | 5.x | 工作流 Agent（工作流引擎线挂入）、Agent 市场生态、剩余适配器（satori 等）、Agent 插件化收尾 | 验证开放注册机制 |
 | 多租户 | 独立评估：仅数据隔离 → 5.x 部署选项；伴随权限/计费/产品定位变化 → 6.0 | 前置条件是 §4.3 的归属主体预留已落实 |

@@ -183,5 +181,5 @@ class AgentChunk:
 2. **多 Agent 协作**：单一仲裁之外，是否需要"串联/并联多个 Agent"的场景？（建议 5.0 不做，留给工作流引擎表达）
 3. **工作流引擎的宿主**：核心内置，还是自身也作为一个插件交付（解释工作流定义的 Agent 插件）？
 4. **插件 Agent 的延迟预算**：消息主链路过 RPC 的 P95 目标值与压测方案。
-5. **Pipeline 的长期命运**：pipeline-wrapper 兼容期多长，Stage 体系是否在 6.0 退役或被工作流引擎吸收。
+5. **Workflow 的处理器边界**：未来 Workflow 应作为与 Pipeline、Agent 平级的处理器，还是作为其中一种处理器的内部编排实现。
 6. **SDK 1.0 时机**：Agent 契约稳定后是否随 LangBot 5.x 给插件生态一个 API 稳定承诺。
@@ -1,8 +1,8 @@
-# Agent 页面与事件编排产品设计
+# 处理器页面与事件编排产品设计

 > 状态：实施稿（2026-06-23）
 >
-> 本文档修订 [07-agent-orchestration.md](./07-agent-orchestration.md) 中“Agent 替代 Pipeline”的表述。当前产品形态应保留两种同级处理单元：**Agent 编排**与**Pipeline**。Agent 页面是统一入口，但不是把 Pipeline 消除。
+> 本文档修订 [07-agent-orchestration.md](./07-agent-orchestration.md) 中“Agent 替代 Pipeline”的表述。当前产品形态保留两种长期并存的同级处理器：**Agent** 与 **Pipeline**。处理器页面只是共享入口，不改变二者各自的持久化模型和执行语义。

 ## 1. 产品边界

@@ -10,33 +10,33 @@ LangBot 的处理逻辑分成两种同级形态：

 | 形态 | 定位 | 可处理事件 | 典型用户 |
 | --- | --- | --- | --- |
-| Agent 编排 | 面向 EBA 的事件优先处理单元，承载 AgentRunner / 外部 runner / 后续工作流 | `message.*`、`group.*`、`friend.*`、`bot.*`、`feedback.*`、`platform.*` 等 | 希望按事件类型配置不同智能处理逻辑的用户 |
-| Pipeline | 现有无代码消息流水线与向后兼容形态 | 仅 `message.*`，首版等价于 `message.received` | 已有 Pipeline 用户、只需要消息处理的用户 |
+| Agent | runner 驱动的事件优先处理器，承载 AgentRunner / 外部 runner | `message.*`、`group.*`、`friend.*`、`bot.*`、`feedback.*`、`platform.*` 等声明范围 | 需要直接处理多类平台事件或接入外部 agent runtime 的用户 |
+| Pipeline | 可视化、可控、可组合的消息处理流水线，执行完整 Stage 链 | 仅 `message.*`，首版等价于 `message.received` | 需要预处理、AI、后处理、扩展和输出控制的消息场景 |

-Agent 页面负责统一管理这两种处理单元：
+处理器页面负责统一管理这两种处理单元：

- 创建时选择 **Agent 编排** 或 **Pipeline**；
+- 创建时选择 **Agent** 或 **Pipeline**；
 - 列表中清晰标注类型与事件能力；
 - Pipeline 的编辑、调试、监控继续复用现有能力；
- Agent 编排保存 runner 配置与事件能力，并通过 Bot 事件绑定进入运行时执行。
+- Agent 保存 runner 配置与事件能力，并通过 Bot 事件绑定进入运行时执行。

 ## 2. 信息架构

-### 2.1 Agent 页面
+### 2.1 处理器页面

 路径：`/home/agents`

 职责：

-1. 展示所有可被事件绑定的处理单元，包括 Agent 编排与 Pipeline。
+1. 展示所有可被事件绑定的处理单元，包括 Agent 与 Pipeline。
 2. 创建时先选择类型：
-   - Agent 编排：创建一条 Agent 配置对象，默认支持所有 EBA 事件；
-   - Pipeline：创建现有 legacy pipeline，只能处理消息事件。
+   - Agent：创建一条独立 Agent 配置对象，默认支持其 runner 声明的事件范围；
+   - Pipeline：创建一条独立 Pipeline，执行完整消息 Stage 链。
 3. 编辑时按类型进入不同表单：
   - Pipeline：沿用原 Pipeline 配置页，包括 AI、触发、安全、输出、扩展、Debug、Monitoring；
-   - Agent 编排：配置基础信息、runner、runner config 和事件能力。
+   - Agent：配置基础信息、runner、runner config 和事件能力。

-`/home/pipelines` 保留为兼容路由，但新导航入口使用 `/home/agents`。
+`/home/pipelines` 继续提供 Pipeline 直接编辑路径；共享处理器入口当前使用 `/home/agents`。URL 是实现路径，不代表 Agent 包含 Pipeline。

 ### 2.2 Bot 的事件编排

@@ -57,9 +57,9 @@ Pipeline 只能被绑定到 `message.*`。如果用户选择非消息事件，

 ## 3. 持久化模型

-### 3.1 Agent 编排实例
+### 3.1 Agent 实例与 Pipeline 实例

-新增 `agents` 表，只保存 Agent 编排形态。Pipeline 继续保存在 `legacy_pipelines`。
+`agents` 表只保存 Agent；Pipeline 继续保存在 Pipeline 表中。当前物理表名 `legacy_pipelines` 是既有存储名称，不代表 Pipeline 在产品架构中是遗留或过渡形态。

 ```python
 class Agent(Base):
@@ -76,7 +76,7 @@ class Agent(Base):
    updated_at: datetime
 ```

-Agent 聚合 API 把 `agents` 与 `legacy_pipelines` 投影成同一个前端列表：
+处理器聚合服务把 `agents` 与 Pipeline 表投影成同一个前端列表：

 ```json
 {
@@ -137,27 +137,27 @@ Bot 新增 `event_bindings` JSON 字段，首版作为轻量配置面。后续
 4. `priority` 数值高者优先
 5. 同优先级按列表顺序

-## 5. 兼容策略
+## 5. 并存策略

-1. 现有 `legacy_pipelines` 不迁移、不改语义。
-2. 现有 Bot 的 `use_pipeline_uuid` 仍作为消息事件默认 Pipeline。
+1. Pipeline 与 Agent 长期并存，各自保存配置并执行自己的运行链路。
+2. 现有 Bot 的 `use_pipeline_uuid` 转换为仍指向原 Pipeline 的消息事件绑定。
 3. 现有 `pipeline_routing_rules` 仍只作用于消息事件。
-4. 新增 `event_bindings` 是 EBA 事件编排配置，允许 Pipeline 目标但只限 `message.*`。
-5. `/api/v1/pipelines` 继续存在；新增 `/api/v1/agents` 作为聚合入口。
+4. `event_bindings` 允许 `target_type=pipeline|agent|discard`；Pipeline 目标只限 `message.*`。
+5. Pipeline 与 Agent 保留各自的持久化和编辑语义；处理器聚合入口只负责统一展示和选择。

 ## 6. 分阶段落地

-### P0：产品入口统一
+### P0：处理器入口统一

 - 新增 `/home/agents`。
- 侧边栏显示“Agent”，但列表包含 Agent 编排与 Pipeline。
- 创建时选择 Agent 编排或 Pipeline。
- `/home/pipelines` 保留兼容。
+- 侧边栏显示“处理器”，列表包含平级的 Agent 与 Pipeline。
+- 创建时选择 Agent 或 Pipeline。
+- `/home/pipelines` 继续作为 Pipeline 直接编辑路径。

 ### P1：配置模型落地

 - 新增 `agents` 表与 `/api/v1/agents`。
- Agent 编排可保存 runner 与 runner_config。
+- Agent 可保存 runner 与 runner_config。
 - Pipeline 继续使用原 Pipeline 表单与 API。

 ### P2：事件编排配置面
@@ -169,12 +169,13 @@ Bot 新增 `event_bindings` JSON 字段，首版作为轻量配置面。后续
 ### P3：EventRouter 执行接入

 - EBA 事件先广播插件 observer。
- 然后按 `event_bindings` 的事件模式、filters、priority 和顺序选择 Agent 编排。
- 消息事件继续优先保留现有 Pipeline / MessageAggregator 兼容路径。
- 非消息事件只调用 Agent 编排，不调用 Pipeline；AgentRunner 输出有平台 reply target 时会投递回平台。
+- 然后按 `event_bindings` 的事件模式、filters、priority 和顺序选择一个处理器。
+- Pipeline 目标通过 MessageAggregator 进入完整 Pipeline Stage 链；Agent 目标直接进入 AgentRunner 链路。
+- 非消息事件只选择声明支持该事件的 Agent，不调用 Pipeline；AgentRunner 输出有平台 reply target 时会投递回平台。

 ## 7. 不做的事

 - 不把 Pipeline 改名成 Agent，也不删除 Pipeline 的配置模型。
+- 不把 Pipeline 降级为兼容层、Agent 子类型或临时运行入口。
 - 不把非消息事件伪装成用户文本塞入 Pipeline。
 - 不在首版做多 Agent 串并联；需要多步骤处理时留给后续 workflow。