mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-07-17 01:46:07 +00:00
feat(agent-runner): enforce 4.x host-owned execution
This commit is contained in:
huanghuoguoguo
@@ -80,13 +80,22 @@ EBA 后 `action.requested`（PROTOCOL_V1 §7.3，当前仅 telemetry 不执行
|
||||
Host 必须校验：binding / platform action policy 是否授权该 action、actor / bot / workspace 是否允许、是否需要人工审批，以及当前 run session / caller identity 是否匹配。EBA 还可能预留 `delivery.requested`（请求投递到某 surface）。
|
||||
|
||||
Delivery 方面，event 不一定回复到当前聊天窗口：消息事件通常带 reply target；系统事件可能没有默认 reply target，需要 runner 返回 `action.requested` 或由 binding 的 delivery policy 决定投递位置（`DeliveryContext` 见 PROTOCOL_V1 §5.7）。
|
||||
当前 Host 会把 adapter 声明的通用 API 投影到
|
||||
`DeliveryContext.platform_capabilities.supported_apis`，并据此设置
|
||||
`supports_edit` / `supports_reaction`。该投影只供 runner 选择输出形态，不构成
|
||||
平台动作授权；合成测试 adapter 会移除副作用能力并抑制实际出站调用。
|
||||
|
||||
## 7. 与 Context 协议的关系
|
||||
|
||||
EBA 事件进入 AgentRunner 时仍遵循 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)：inline 当前事件、大 payload 用 raw/staged file ref、不默认 inline 完整 history、agent 按需通过 API 拉取、Host 保留 EventLog 和权限 guardrail。非消息事件可以被投影进 Transcript，但不能强制伪装为 user message；AgentRunner 根据 event type 自己决定是否纳入模型上下文。
|
||||
|
||||
## 8. EBA 分支联调内容
|
||||
## 8. 当前集成状态
|
||||
|
||||
外部 EBA 分支负责联调 EventGateway 完整实现、Pipeline / Agent 处理器路由、AgentBindingResolver 集成、事件绑定持久模型和 UI、`DeliveryContext` 完整实现、platform action permission model 和执行器、真实平台事件接入。
|
||||
当前分支已完成 EventRouter、Pipeline / Agent 平级处理器路由、Bot
|
||||
`event_bindings` 持久化与 WebUI、AgentBinding 投影、路由 dry-run、合成测试事件、
|
||||
运行状态和真实 OneBot 非消息事件到 Agent 的闭环。Pipeline 消息链和独立 Agent
|
||||
均复用同一个 AgentRunner orchestrator / context / result 协议。
|
||||
|
||||
当前底座已完成：① Pipeline 消息链可投影 `message.received` 并在 AI Stage 复用 AgentRunner → ② 独立 Agent 可从 EBA 路由直接生成 `AgentBinding` → ③ context builder 从 event + binding 构造 runner context → ④ 引入 EventLog / Transcript。外部 EBA 分支在此基础上联调真实事件来源、处理器路由、binding persistence / UI 和 platform action。
|
||||
尚未落地的是 platform action permission model 和 `action.requested` 执行器；在显式
|
||||
action allowlist、binding policy、adapter capability 和审批模型完成前，该 result 仍只
|
||||
记录 telemetry，不执行平台副作用。
|
||||
|
||||
@@ -295,6 +295,11 @@ class DeliveryContext(BaseModel):
|
||||
```
|
||||
|
||||
Runner 可参考 delivery 能力决定返回 `message.delta`、`message.completed` 或 `action.requested`。
|
||||
平台事件进入独立 Agent 时，Host 会从当前 adapter 的 `get_supported_apis()` 投影
|
||||
`supports_edit`、`supports_reaction`，并把去重后的 API 名称写入
|
||||
`platform_capabilities.supported_apis`。这些字段只描述当前投递表面的能力，不授予
|
||||
平台动作权限；`action.requested` 仍受 §7.3 的 reserved 约束。合成路由测试使用的
|
||||
adapter 会过滤所有已知副作用 API，因此测试事件不会向 runner 宣告真实出站能力。
|
||||
|
||||
### 5.8 ContextAccess
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
本文档是 `docs/agent-runner-pluginization/` 的状态事实源。协议 schema 仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准；测试步骤以 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md) 为准；安全发布门槛以 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 为准。
|
||||
|
||||
状态快照日期：2026-06-23。
|
||||
状态快照日期：2026-07-12。
|
||||
|
||||
## 实现状态
|
||||
|
||||
@@ -20,11 +20,12 @@
|
||||
| Security boundary | Done | 当前口径降级为轻量边界：LangBot 保护自身持有资源；external harness 的 OS / process / network / workspace 风险由用户或部署环境承担；managed sandbox 不是当前承诺。 |
|
||||
| Steering control path | Done | claim 异常不再逃逸 consumer loop；queue 有上限；未 pull 的 claimed 输入在 run 结束时写 `steering.dropped` 审计终态。 |
|
||||
| SDK v1 contract closure | Done | SDK 提供 `AgentAPIError` / `AgentAPIException`、typed `SteeringPullResult`、未知 result type 宽容解析、result `sequence` 注入与取消传播。 |
|
||||
| EBA processor routing | Done; clean-instance catalog gate pending | Bot `event_bindings`、Pipeline / Agent 平级路由、WebUI dry-run / 合成测试 / 状态、OneBot 非消息事件到 Agent 及平台回复已闭环；全新实例 Runner Marketplace 用例仍需独立空白环境。 |
|
||||
|
||||
## Spec 与实现已知差距
|
||||
|
||||
- `action.requested` 仍只作为 telemetry / reserved surface；platform action executor 不在本分支执行。
|
||||
- EventGateway / EventRouter 完整实现由外部 EBA 分支联调；本分支只提供 event-first host envelope / binding / run 入口。
|
||||
- `action.requested` 权限模型完成前，DeliveryContext 的 adapter capability 投影只用于输出决策，不提供平台动作执行权限。
|
||||
- State 与 storage 的长期类型边界仍可继续收窄；当前合同只要求 JSON-safe state 与受控 storage API。
|
||||
- `ToolResource.parameters` 已作为 best-effort full schema 由 Host 在构造 `ctx.resources` 时一次塞齐；无 schema 时 runner 仍需兼容 `parameters=None` 或按需调用 detail API。
|
||||
- EventLog / Transcript 已提供显式 cleanup primitive；长期 retention 默认值、TTL 调度接入和 sandbox/workspace 文件清理仍是运维收尾项，应在 Runtime Control Plane 产品化前补齐。
|
||||
@@ -44,7 +45,7 @@
|
||||
|
||||
| 范围 | 状态 | 最近证据 |
|
||||
| --- | --- | --- |
|
||||
| LangBot Runtime Control Plane v2 foundation | Unit-pass; product E2E pending | 2026-06-23 `tests/unit_tests/agent`、`tests/unit_tests/plugin/test_handler_actions.py`、`tests/unit_tests/provider/test_skill_tools.py`、pipeline preproc/chat handler tests 和 Telegram EBA adapter tests 通过，覆盖 ledger、admin permissions、runtime heartbeat、claim/reconcile、orchestrator 持久化、取消传播、skill activation persistence 和插件化 runner pipeline path。 |
|
||||
| LangBot Runtime Control Plane v2 foundation | Unit-pass; EBA product flow pass | 2026-07-12 事件路由与 Agent 协议针对性测试通过；WebUI 已验证 Quick Start 场景筛选、事件路由 dry-run / 合成派发、Runner 健康状态，以及真实 OneBot `group.member_joined` → Agent → `send_group_msg` 链路。clean-instance Runner Marketplace 用例因当前实例已有插件与 runner 未执行。 |
|
||||
| SDK AgentRunner control entities / proxy | Unit-pass | 2026-06-23 SDK `tests/api/entities/builtin/agent_runner`、`tests/api/proxies`、`tests/api/test_agent_tools_mcp_bridge.py`、`tests/runtime/plugin/test_mgr_agent_runner.py`、`tests/runtime/test_pull_api_handlers.py`、`tests/runtime/io/handlers/test_plugin_handler.py`、EBA event entities 和 message tests 通过，覆盖 typed entities、AgentRunAPIProxy、MCP bridge、runtime manager 与 pull API handlers。 |
|
||||
|
||||
## 历史高价值记录
|
||||
|
||||
@@ -48,7 +48,9 @@ MessageAggregator (消息聚合)
|
||||
QueryPool → Controller → Pipeline (固定阶段链)
|
||||
│ │
|
||||
│ ▼
|
||||
│ RequestRunner (local-agent / dify / n8n / ...)
|
||||
│ AgentRunner Host orchestrator
|
||||
│ ▼
|
||||
│ plugin AgentRunner
|
||||
│
|
||||
▼
|
||||
adapter.reply_message() / adapter.send_message()
|
||||
@@ -71,13 +73,14 @@ adapter.reply_message() / adapter.send_message()
|
||||
▼
|
||||
EventBus (统一事件总线)
|
||||
│
|
||||
▼
|
||||
EventRouter (事件路由引擎, 读取 Bot 的 event_handlers 配置)
|
||||
├─→ Plugin EventListener observers（始终广播，不参与响应仲裁）
|
||||
│
|
||||
├─→ PipelineHandler — 现有流水线（完整 Stage 链）
|
||||
├─→ AgentHandler — 直接调用 RequestRunner（轻量 AI 处理）
|
||||
├─→ WebhookHandler — POST 到外部服务（Dify/n8n webhook 等）
|
||||
└─→ PluginHandler — 分发给插件 EventListener
|
||||
▼
|
||||
EventRouter (读取 Bot 的 event_bindings)
|
||||
│
|
||||
├─→ Pipeline target — 完整 Stage 链，仅消息事件
|
||||
├─→ Agent target — 独立 Agent，经插件 AgentRunner 执行
|
||||
└─→ discard — 明确丢弃
|
||||
│
|
||||
▼
|
||||
统一平台 API
|
||||
@@ -141,20 +144,13 @@ pkg/platform/adapters/
|
||||
|
||||
详见 [03-adapter-structure.md](./03-adapter-structure.md)。
|
||||
|
||||
### 3.4 事件处理器（Event Handler）
|
||||
### 3.4 事件响应目标与观察者
|
||||
|
||||
> **2026-06 方向修订**：四种 Handler 分类法已演进为「事件 → 处理器」统一路由。Pipeline 与 Agent 是长期并存、场景不同的同级处理器：Pipeline 面向消息事件的完整 Stage 链，Agent 面向其声明支持的消息或非消息事件；插件 EventListener 保留为观察者角色。详见 [07-agent-orchestration.md](./07-agent-orchestration.md)。本节保留原设计供对照。
|
||||
Pipeline 与 Agent 是长期并存、场景不同的同级处理器。Pipeline 保留完整 Stage 链，面向消息处理；Agent 是独立配置对象，选择一个已安装的插件 AgentRunner，并可声明消息或非消息事件能力。Bot 的 `event_bindings` 只负责把事件绑定到既有 Pipeline、独立 Agent 或 `discard`。
|
||||
|
||||
四种处理器类型，用户在 WebUI 的 Bot 管理页面配置：
|
||||
插件 EventListener 是观察者：事件先广播给有权限的监听器，随后路由器再选择一个响应目标。Webhook、Dify、n8n 等外部执行方式若需要作为响应者，应由对应 AgentRunner 插件表达，而不是增加另一套 Host Handler 主链。
|
||||
|
||||
| 类型 | 说明 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **pipeline** | 现有流水线机制，完整的多 Stage 处理链（PreProcessor → MessageProcessor → PostProcessor 等） | 复杂消息处理，需要完整的预处理/后处理流程 |
|
||||
| **agent** | 直接调用 RequestRunner（local-agent / dify / n8n / coze / dashscope / langflow / tbox），从 Pipeline 中解耦 | 轻量级 AI 处理、直接对接外部 LLMOps 平台处理各类事件 |
|
||||
| **webhook** | 将事件 POST 到外部 URL，根据响应执行动作 | 对接自建服务、Dify/n8n 的 Webhook 触发器、自定义后端 |
|
||||
| **plugin** | 分发给插件 EventListener 处理 | 插件自定义逻辑 |
|
||||
|
||||
配置存储在 Bot 表的 `event_handlers` JSON 字段中，通过 WebUI 编排面板管理。
|
||||
现有 Pipeline 不会被转换为 Agent，Pipeline 内的 runner 配置也不会复制到独立 Agent。用户需要 Agent 时自行创建并绑定。
|
||||
|
||||
详见 [04-event-routing.md](./04-event-routing.md)。
|
||||
|
||||
@@ -173,8 +169,8 @@ pkg/platform/adapters/
|
||||
| 1 | 事件处理器配置粒度 | 每个 Bot 独立配置 | Bot 是用户操作的核心单元，不同 Bot 可能对接不同业务场景 |
|
||||
| 2 | 适配器特有 API | 统一抽象 + `call_platform_api` 透传 | 通用 API 覆盖大部分场景，透传机制保证灵活性，避免每个适配器导出独立的类型化 API 包 |
|
||||
| 3 | 向后兼容策略 | 兼容层适配 | 保留旧事件类型和 API 作为新系统的 alias/wrapper，现有插件无需修改 |
|
||||
| 4 | 处理器配置存储 | Bot 表新增 `event_handlers` JSON 字段 | 简单直接，避免新增关联表；替代现有 `use_pipeline_uuid` |
|
||||
| 5 | Agent 处理器定位 | 从 Pipeline 中解耦 RequestRunner | 不是所有事件都需要完整 Pipeline Stage 链；Agent 处理器提供轻量级 AI 处理路径，支持所有现有 Runner |
|
||||
| 4 | 处理器配置存储 | Bot 表使用 `event_bindings`，目标引用原始 Pipeline 或独立 Agent UUID | 路由关系不复制处理器配置，Pipeline/Agent 各自保持事实源 |
|
||||
| 5 | Agent 处理器定位 | 独立 Agent + 插件 AgentRunner | Host 不再内置具体 runner；不同 AgentRunner 通过统一协议接入 |
|
||||
| 6 | 事件命名方式 | 命名空间式（`message.received`） | 清晰的分类层级，便于通配匹配（`message.*`），与 WebUI 配置天然对应 |
|
||||
|
||||
## 5. 文档索引
|
||||
@@ -194,7 +190,7 @@ pkg/platform/adapters/
|
||||
| 仓库 | 改动范围 |
|
||||
|------|----------|
|
||||
| **langbot-plugin-sdk** | 事件定义、实体模型、API 接口、适配器基类、通信协议扩展 |
|
||||
| **LangBot**（后端） | 适配器实现、事件路由引擎、Bot 实体扩展、数据库迁移、RequestRunner 解耦 |
|
||||
| **LangBot**（后端） | 适配器实现、事件路由引擎、Bot/Agent 实体、AgentRunner Host 编排 |
|
||||
| **LangBot**（前端） | Bot 事件处理器编排面板 |
|
||||
| **langbot-wiki** | 新架构文档、插件开发指南更新、适配器开发指南 |
|
||||
| **langbot-plugin-demo** | 示例更新（使用新事件和 API） |
|
||||
|
||||
@@ -490,18 +490,19 @@ class PlatformSpecificEvent(Event):
|
||||
│
|
||||
5. EventBus 分发
|
||||
│
|
||||
6. EventRouter 查询 Bot 的 event_handlers 配置
|
||||
│ 匹配事件类型 → 找到对应的 Handler
|
||||
│ 支持通配符：'message.*' 匹配所有消息事件
|
||||
│ 未匹配到 → 走默认 Handler（plugin，保持向后兼容）
|
||||
6. EventBus 向有权限的 Plugin EventListener 广播观察者事件
|
||||
│ observer 不占用响应目标，也不参与 priority 仲裁
|
||||
│
|
||||
7. Handler 处理事件
|
||||
│ PipelineHandler → 进入 Pipeline 流水线
|
||||
│ AgentHandler → 调用 RequestRunner
|
||||
│ WebhookHandler → POST 到外部 URL
|
||||
│ PluginHandler → 分发给插件 EventListener
|
||||
7. EventRouter 查询 Bot 的 event_bindings
|
||||
│ 精确/通配匹配 event_pattern，应用 filters 与 priority
|
||||
│ 选择一个 Pipeline、Agent 或 discard 目标
|
||||
│
|
||||
8. Handler 执行完毕，可能通过 API 执行响应动作
|
||||
8. 目标处理事件
|
||||
│ Pipeline → 进入完整 Pipeline 流水线（仅消息事件）
|
||||
│ Agent → Host 编排已安装的插件 AgentRunner
|
||||
│ discard → 不产生响应
|
||||
│
|
||||
9. 处理器执行完毕，可能通过 Host 授权 API 执行响应动作
|
||||
（发消息、编辑消息、踢人、同意好友请求等）
|
||||
```
|
||||
|
||||
|
||||
@@ -1,747 +1,174 @@
|
||||
# 事件路由与编排
|
||||
|
||||
> **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）仍然有效。
|
||||
> 状态：当前实施模型（2026-07-12）。本文以 Pipeline / Agent 平级并存为准，不再保留早期 `pipeline / agent / webhook / plugin` 四种 Handler 草案。
|
||||
|
||||
## 1. 概述
|
||||
## 1. 路由边界
|
||||
|
||||
事件路由是 EBA 架构的核心机制：事件从适配器产生后，经由 EventBus 进入 EventRouter，由 EventRouter 根据 Bot 的配置将事件分发到对应的处理器（Handler）。
|
||||
EBA 将事件处理拆成两个互不替代的阶段：
|
||||
|
||||
**配置方式**：用户在 WebUI 的 Bot 管理页面通过可视化编排面板管理事件处理器配置，配置数据存储在数据库的 Bot 表 `event_handlers` JSON 字段中。
|
||||
1. **观察者广播**：EventBus 把事件广播给有权限的插件 EventListener。观察者可记录、同步或执行受控副作用，但不占用响应目标。
|
||||
2. **响应者仲裁**：EventRouter 按 Bot 的 `event_bindings` 选择一个 Pipeline、独立 Agent 或 `discard`。
|
||||
|
||||
Pipeline 与 Agent 是平级处理器：
|
||||
|
||||
| 处理器 | 配置事实源 | 执行路径 | 事件范围 |
|
||||
| --- | --- | --- | --- |
|
||||
| Pipeline | Pipeline 表与完整 Stage 配置 | MessageAggregator -> QueryPool -> RuntimePipeline | 消息事件，首版为 `message.received` |
|
||||
| Agent | Agent 表中的 runner 与 runner config | AgentRunner Host orchestrator -> plugin AgentRunner | Agent/Runner 声明支持的消息或非消息事件 |
|
||||
| discard | 无处理器配置 | 明确结束路由 | 任意事件 |
|
||||
|
||||
插件 EventListener 不是第三种响应目标。Webhook、Dify、n8n、Coze 等外部系统需要响应事件时，由对应 AgentRunner 插件承接。
|
||||
|
||||
## 2. 数据模型
|
||||
|
||||
### 2.1 Bot 实体扩展
|
||||
### 2.1 独立 Agent
|
||||
|
||||
在 `bots` 表新增 `event_handlers` 字段：
|
||||
Agent 保存自己的 Runner 选择与配置，不嵌入 Pipeline，也不复制 Pipeline 的 AI stage：
|
||||
|
||||
```python
|
||||
class Bot(Base):
|
||||
__tablename__ = "bots"
|
||||
|
||||
uuid: str # 主键
|
||||
class Agent(Base):
|
||||
uuid: str
|
||||
name: str
|
||||
description: str
|
||||
adapter: str
|
||||
adapter_config: dict # JSON
|
||||
enable: bool
|
||||
|
||||
# 新增
|
||||
event_handlers: list # JSON — 事件处理器配置列表
|
||||
|
||||
# 保留（过渡期后弃用）
|
||||
use_pipeline_name: str # deprecated
|
||||
use_pipeline_uuid: str # deprecated
|
||||
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
emoji: str
|
||||
kind: str # 固定为 "agent"
|
||||
component_ref: str # AgentRunner id
|
||||
config: dict # runner + runner_config
|
||||
enabled: bool
|
||||
supported_event_patterns: list[str]
|
||||
```
|
||||
|
||||
### 2.2 EventHandler 配置结构
|
||||
当前配置形状：
|
||||
|
||||
`event_handlers` 字段存储一个 JSON 数组，每个元素定义一条事件路由规则：
|
||||
```json
|
||||
{
|
||||
"runner": {
|
||||
"id": "plugin:langbot-team/LocalAgent/default"
|
||||
},
|
||||
"runner_config": {
|
||||
"plugin:langbot-team/LocalAgent/default": {
|
||||
"model": {
|
||||
"primary": "model-uuid",
|
||||
"fallbacks": []
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Runner id 来自已安装插件的 AgentRunner manifest。Host 不维护 LocalAgent、Dify 或其他具体实现的内置分支。
|
||||
|
||||
### 2.2 EventBinding
|
||||
|
||||
Bot 维护事件到处理器的引用：
|
||||
|
||||
```python
|
||||
class EventHandlerConfig(pydantic.BaseModel):
|
||||
"""单条事件处理器配置"""
|
||||
|
||||
event_type: str
|
||||
"""匹配的事件类型
|
||||
|
||||
支持精确匹配和通配符：
|
||||
- "message.received" — 精确匹配
|
||||
- "message.*" — 匹配 message 命名空间下所有事件
|
||||
- "group.*" — 匹配 group 命名空间下所有事件
|
||||
- "*" — 匹配所有事件（兜底）
|
||||
"""
|
||||
|
||||
handler_type: str
|
||||
"""处理器类型: "pipeline" | "agent" | "webhook" | "plugin" """
|
||||
|
||||
handler_config: dict = {}
|
||||
"""处理器的具体配置，结构取决于 handler_type"""
|
||||
|
||||
enabled: bool = True
|
||||
"""是否启用此规则"""
|
||||
|
||||
priority: int = 0
|
||||
"""优先级，数字越大越先匹配（同一事件类型有多条规则时）"""
|
||||
|
||||
description: str = ""
|
||||
"""规则描述（供 WebUI 显示）"""
|
||||
class EventBinding(BaseModel):
|
||||
id: str
|
||||
event_pattern: str # 精确、namespace.* 或 *
|
||||
target_type: str # agent | pipeline | discard
|
||||
target_uuid: str | None # Agent/Pipeline 原始 UUID
|
||||
filters: list[dict]
|
||||
priority: int
|
||||
enabled: bool
|
||||
description: str
|
||||
```
|
||||
|
||||
### 2.3 各 Handler 类型的 handler_config 结构
|
||||
|
||||
#### pipeline
|
||||
|
||||
```json
|
||||
{
|
||||
"handler_type": "pipeline",
|
||||
"handler_config": {
|
||||
"pipeline_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将事件作为消息事件传入现有 Pipeline 流水线。仅适用于 `message.received` 事件。
|
||||
|
||||
#### agent
|
||||
|
||||
```json
|
||||
{
|
||||
"handler_type": "agent",
|
||||
"handler_config": {
|
||||
"runner": "local-agent",
|
||||
"runner_config": {
|
||||
"model_uuid": "...",
|
||||
"prompt": "你是一个群组助理，请处理以下事件：{event_summary}",
|
||||
"tools_enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"handler_type": "agent",
|
||||
"handler_config": {
|
||||
"runner": "dify-service-api",
|
||||
"runner_config": {
|
||||
"base_url": "https://api.dify.ai/v1",
|
||||
"api_key": "...",
|
||||
"app_type": "agent"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
直接调用 RequestRunner 处理事件。可用的 runner 包括：
|
||||
- `local-agent` — 内置 LLM Agent
|
||||
- `dify-service-api` — Dify 平台
|
||||
- `n8n-service-api` — n8n 工作流
|
||||
- `coze-api` — Coze (扣子)
|
||||
- `dashscope-app-api` — 阿里百炼
|
||||
- `langflow-api` — Langflow
|
||||
- `tbox-app-api` — 蚂蚁 Tbox
|
||||
|
||||
Agent 处理器不经过 Pipeline 的多 Stage 流程，而是直接构建上下文并调用 Runner。适用于所有事件类型。
|
||||
|
||||
**Agent Handler 与 Pipeline 的关系**：
|
||||
- Pipeline 是完整的多 Stage 处理链（PreProcessor → MessageProcessor(内含Runner) → PostProcessor → ...），适合复杂消息处理
|
||||
- Agent Handler 是轻量级的，直接调用 Runner，跳过 PreProcessor/PostProcessor 等阶段
|
||||
- Pipeline 内部的 AI Stage 仍然使用 Runner，所以 Runner 本身被两种 Handler 共享
|
||||
- 用户可以根据场景选择：消息处理用 Pipeline（更多控制），其他事件用 Agent（更直接）
|
||||
|
||||
#### webhook
|
||||
|
||||
```json
|
||||
{
|
||||
"handler_type": "webhook",
|
||||
"handler_config": {
|
||||
"url": "https://example.com/webhook/langbot-events",
|
||||
"method": "POST",
|
||||
"headers": {
|
||||
"Authorization": "Bearer xxx"
|
||||
},
|
||||
"timeout": 30,
|
||||
"retry_count": 3,
|
||||
"retry_interval": 5,
|
||||
"response_actions": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将事件序列化为 JSON POST 到外部 URL。支持的特性：
|
||||
- **认证**：通过 headers 配置（Bearer Token、API Key 等）
|
||||
- **重试**：配置重试次数和间隔
|
||||
- **响应动作**：如果 `response_actions` 为 true，解析响应 JSON 中的 `actions` 字段并执行（如发送消息、同意好友请求等）
|
||||
|
||||
Webhook 请求体格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"event": {
|
||||
"type": "group.member_joined",
|
||||
"timestamp": 1700000000.0,
|
||||
"bot_uuid": "...",
|
||||
"adapter_name": "telegram",
|
||||
"group": { "id": "...", "name": "..." },
|
||||
"member": { "id": "...", "nickname": "..." }
|
||||
},
|
||||
"bot": {
|
||||
"uuid": "...",
|
||||
"name": "...",
|
||||
"adapter": "telegram"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
响应体格式（当 `response_actions` 为 true 时）：
|
||||
|
||||
```json
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"type": "send_message",
|
||||
"params": {
|
||||
"target_type": "group",
|
||||
"target_id": "123456",
|
||||
"message": [{ "type": "Plain", "text": "欢迎新成员！" }]
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "call_platform_api",
|
||||
"params": {
|
||||
"action": "pin_message",
|
||||
"params": { "chat_id": "123456", "message_id": "789" }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### plugin
|
||||
|
||||
```json
|
||||
{
|
||||
"handler_type": "plugin",
|
||||
"handler_config": {
|
||||
"plugin_filter": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
将事件分发给插件的 EventListener 处理。
|
||||
|
||||
- `plugin_filter`：可选的插件名过滤列表，为空表示分发给所有插件
|
||||
- 沿用现有的插件事件分发机制（按优先级遍历插件，支持 `prevent_postorder`）
|
||||
|
||||
### 2.4 完整配置示例
|
||||
|
||||
一个 Bot 的 `event_handlers` 配置示例：
|
||||
示例：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"event_type": "message.received",
|
||||
"handler_type": "pipeline",
|
||||
"handler_config": {
|
||||
"pipeline_uuid": "default-pipeline-uuid"
|
||||
},
|
||||
"enabled": true,
|
||||
"priority": 10,
|
||||
"description": "消息事件使用默认流水线处理"
|
||||
},
|
||||
{
|
||||
"event_type": "group.member_joined",
|
||||
"handler_type": "agent",
|
||||
"handler_config": {
|
||||
"runner": "local-agent",
|
||||
"runner_config": {
|
||||
"model_uuid": "gpt-4o-mini",
|
||||
"prompt": "有新成员 {member_name} 加入了群组 {group_name}，请生成一条欢迎消息。"
|
||||
}
|
||||
},
|
||||
"enabled": true,
|
||||
"priority": 0,
|
||||
"description": "新成员入群时用 AI 生成欢迎消息"
|
||||
},
|
||||
{
|
||||
"event_type": "friend.request_received",
|
||||
"handler_type": "webhook",
|
||||
"handler_config": {
|
||||
"url": "https://my-server.com/api/friend-request",
|
||||
"response_actions": true
|
||||
},
|
||||
"enabled": true,
|
||||
"priority": 0,
|
||||
"description": "好友请求转发到自建服务处理"
|
||||
},
|
||||
{
|
||||
"event_type": "*",
|
||||
"handler_type": "plugin",
|
||||
"handler_config": {},
|
||||
"enabled": true,
|
||||
"priority": -100,
|
||||
"description": "所有事件兜底发给插件处理"
|
||||
}
|
||||
{
|
||||
"id": "binding-message",
|
||||
"event_pattern": "message.received",
|
||||
"target_type": "pipeline",
|
||||
"target_uuid": "pipeline-uuid",
|
||||
"filters": [],
|
||||
"priority": 100,
|
||||
"enabled": true
|
||||
},
|
||||
{
|
||||
"id": "binding-member-joined",
|
||||
"event_pattern": "group.member_joined",
|
||||
"target_type": "agent",
|
||||
"target_uuid": "agent-uuid",
|
||||
"filters": [],
|
||||
"priority": 50,
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 3. EventBus 设计
|
||||
Binding 只保存引用与路由条件。它不复制 Pipeline 或 Agent 配置。
|
||||
|
||||
EventBus 是事件的中转站，接收来自各个 RuntimeBot 的事件，交由 EventRouter 处理。
|
||||
## 3. 匹配与仲裁
|
||||
|
||||
```python
|
||||
class EventBus:
|
||||
"""事件总线"""
|
||||
事件模式支持：
|
||||
|
||||
def __init__(self, ap: Application):
|
||||
self.ap = ap
|
||||
self.event_router = EventRouter(ap)
|
||||
- 精确匹配：`group.member_joined`
|
||||
- 命名空间通配：`group.*`
|
||||
- 全局通配：`*`
|
||||
|
||||
async def emit(
|
||||
self,
|
||||
event: Event,
|
||||
adapter: AbstractPlatformAdapter,
|
||||
):
|
||||
"""接收并分发事件
|
||||
路由按以下顺序处理：
|
||||
|
||||
Args:
|
||||
event: 统一事件对象
|
||||
adapter: 产生此事件的适配器实例
|
||||
"""
|
||||
# 1. 全局事件日志
|
||||
self.ap.logger.debug(
|
||||
f"EventBus: {event.type} from bot {event.bot_uuid}"
|
||||
)
|
||||
1. 忽略 `enabled = false` 的 binding。
|
||||
2. 检查 `event_pattern` 与结构化 filters。
|
||||
3. 校验目标存在、启用且声明支持该事件。
|
||||
4. 按 `priority` 从高到低选择；同优先级按稳定列表顺序。
|
||||
5. 只执行一个响应目标。
|
||||
|
||||
# 2. 交由 EventRouter 路由处理
|
||||
await self.event_router.route(event, adapter)
|
||||
Pipeline 目标只能匹配消息事件。非消息事件不得伪装成用户文本塞进 Pipeline。
|
||||
|
||||
## 4. 执行流程
|
||||
|
||||
```text
|
||||
Platform adapter
|
||||
-> normalized event
|
||||
-> EventBus
|
||||
-> authorized Plugin EventListener observers
|
||||
-> EventRouter
|
||||
-> Pipeline target -> full Pipeline stage chain
|
||||
-> Agent target -> AgentRunner Host orchestrator
|
||||
-> discard -> stop
|
||||
-> Host delivery/platform API
|
||||
```
|
||||
|
||||
## 4. EventRouter 设计
|
||||
### 4.1 Pipeline target
|
||||
|
||||
EventRouter 是事件路由引擎，根据 Bot 的 `event_handlers` 配置决定事件的处理方式。
|
||||
消息事件按原有方式构造 Query，经 MessageAggregator、QueryPool 和完整 Pipeline Stage 链执行。Pipeline 可以继续使用 AgentRunner 作为 AI stage 的实现，但 Pipeline 本身不会因此变成 Agent。
|
||||
|
||||
```python
|
||||
class EventRouter:
|
||||
"""事件路由引擎"""
|
||||
### 4.2 Agent target
|
||||
|
||||
def __init__(self, ap: Application):
|
||||
self.ap = ap
|
||||
self.handlers: dict[str, AbstractEventHandler] = {
|
||||
"pipeline": PipelineHandler(ap),
|
||||
"agent": AgentHandler(ap),
|
||||
"webhook": WebhookHandler(ap),
|
||||
"plugin": PluginHandler(ap),
|
||||
}
|
||||
Host 读取独立 Agent 的 Runner id/config，构造 event-first context、run-scoped resources 与 delivery policy，再调用插件 AgentRunner。Runner 输出由 Host 统一归一化、记录和投递。
|
||||
|
||||
async def route(
|
||||
self,
|
||||
event: Event,
|
||||
adapter: AbstractPlatformAdapter,
|
||||
):
|
||||
"""路由事件到对应处理器"""
|
||||
AgentRunner 可通过 SDK/Python `AgentRunAPIProxy.call_tool` 或 SDK-owned scoped MCP bridge 回调 Host 能力。两条路径都映射到 `PluginToRuntimeAction.CALL_TOOL`，使用相同的 run authorization、Host execution Query、ToolManager 和 Box session 规则。Box session 是 Host canonical scope 的固定长度安全哈希；同一平台会话稳定、不同 scope 隔离、缺少 identity 时 fail closed，Runner 不配置 sandbox scope。
|
||||
|
||||
# 1. 获取 Bot 配置
|
||||
bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
|
||||
if not bot:
|
||||
return
|
||||
### 4.3 Observer side effects
|
||||
|
||||
# 2. 获取事件处理器配置
|
||||
event_handlers = bot.bot_entity.event_handlers or []
|
||||
观察者与响应者可以同时工作。为避免编辑、reaction 等合成事件重复触发不可逆操作，Host 应按事件能力和授权过滤观察者可用 API，并记录副作用结果。Observer 广播不作为 fallback 响应。
|
||||
|
||||
# 3. 匹配规则（按 priority 降序排列）
|
||||
matched_handlers = self._match_handlers(event.type, event_handlers)
|
||||
## 5. Pipeline 与 Agent 的并存规则
|
||||
|
||||
if not matched_handlers:
|
||||
# 未匹配到任何规则 → 默认交给插件处理（向后兼容）
|
||||
await self.handlers["plugin"].handle(event, adapter, {})
|
||||
return
|
||||
1. Pipeline 与 Agent 保留各自的持久化、编辑和执行语义。
|
||||
2. 处理器聚合页面可以统一展示二者，但不会创建第三份处理器记录。
|
||||
3. 旧 Pipeline 仍是 Pipeline；其 runner config 不迁移、不复制为独立 Agent。
|
||||
4. 需要 Agent 的用户新建 Agent、选择已安装 AgentRunner，再建立 event binding。
|
||||
5. 一个 Bot 可按不同事件同时绑定 Pipeline 与 Agent。
|
||||
|
||||
# 4. 执行第一个匹配的 Handler
|
||||
# （未来可扩展为多个 Handler 串行/并行执行）
|
||||
handler_config = matched_handlers[0]
|
||||
handler = self.handlers.get(handler_config.handler_type)
|
||||
## 6. WebUI 约束
|
||||
|
||||
if handler:
|
||||
await handler.handle(event, adapter, handler_config.handler_config)
|
||||
else:
|
||||
self.ap.logger.warning(
|
||||
f"Unknown handler type: {handler_config.handler_type}"
|
||||
)
|
||||
处理器入口展示带类型标识的 Agent 与 Pipeline。Bot 事件编排器应：
|
||||
|
||||
def _match_handlers(
|
||||
self,
|
||||
event_type: str,
|
||||
handlers: list[EventHandlerConfig],
|
||||
) -> list[EventHandlerConfig]:
|
||||
"""匹配事件类型到处理器配置
|
||||
- 按 adapter manifest 展示可用事件；
|
||||
- 非消息事件不提供 Pipeline 目标；
|
||||
- Agent 目标按 `supported_event_patterns` 过滤；
|
||||
- 展示 priority、filters、enabled 与 discard；
|
||||
- 保存前校验目标 UUID 与 `target_type` 一致。
|
||||
|
||||
匹配规则：
|
||||
1. 精确匹配：event_type == handler.event_type
|
||||
2. 命名空间通配：handler.event_type 为 "message.*" 时匹配所有 "message.xxx"
|
||||
3. 全局通配：handler.event_type 为 "*" 时匹配所有事件
|
||||
4. 按 priority 降序排列
|
||||
5. 只返回 enabled=True 的规则
|
||||
"""
|
||||
matched = []
|
||||
for handler in handlers:
|
||||
if not handler.enabled:
|
||||
continue
|
||||
if self._event_type_matches(event_type, handler.event_type):
|
||||
matched.append(handler)
|
||||
Pipeline 的配置、Debug Chat 和 Monitoring 继续使用 Pipeline 页面；Agent 使用独立表单配置 Runner 与事件能力。
|
||||
|
||||
matched.sort(key=lambda h: h.priority, reverse=True)
|
||||
return matched
|
||||
## 7. 版本与迁移边界
|
||||
|
||||
@staticmethod
|
||||
def _event_type_matches(event_type: str, pattern: str) -> bool:
|
||||
"""判断事件类型是否匹配模式"""
|
||||
if pattern == "*":
|
||||
return True
|
||||
if pattern == event_type:
|
||||
return True
|
||||
if pattern.endswith(".*"):
|
||||
namespace = pattern[:-2]
|
||||
return event_type.startswith(namespace + ".")
|
||||
return False
|
||||
```
|
||||
此功能按当前 4.x schema 直接实现，不提供 LangBot 3.x 数据库或配置升级路径，也不读取旧 Runner 字段作为 fallback。旧 Pipeline 中的 runner 配置不会生成独立 Agent；用户按新产品模型添加 Agent 即可。
|
||||
|
||||
## 5. 事件处理器（Handler）实现
|
||||
|
||||
### 5.1 Handler 基类
|
||||
|
||||
```python
|
||||
class AbstractEventHandler(abc.ABC):
|
||||
"""事件处理器基类"""
|
||||
|
||||
def __init__(self, ap: Application):
|
||||
self.ap = ap
|
||||
|
||||
@abc.abstractmethod
|
||||
async def handle(
|
||||
self,
|
||||
event: Event,
|
||||
adapter: AbstractPlatformAdapter,
|
||||
config: dict,
|
||||
) -> None:
|
||||
"""处理事件
|
||||
|
||||
Args:
|
||||
event: 统一事件对象
|
||||
adapter: 适配器实例（用于调用平台 API 发送响应）
|
||||
config: handler_config 配置
|
||||
"""
|
||||
...
|
||||
```
|
||||
|
||||
### 5.2 PipelineHandler
|
||||
|
||||
将消息事件注入现有 Pipeline 流水线处理。
|
||||
|
||||
```python
|
||||
class PipelineHandler(AbstractEventHandler):
|
||||
"""Pipeline 处理器 — 将事件送入现有 Pipeline 流水线"""
|
||||
|
||||
async def handle(self, event, adapter, config):
|
||||
pipeline_uuid = config.get("pipeline_uuid")
|
||||
|
||||
if not isinstance(event, MessageReceivedEvent):
|
||||
self.ap.logger.warning(
|
||||
f"PipelineHandler only supports MessageReceivedEvent, "
|
||||
f"got {event.type}"
|
||||
)
|
||||
return
|
||||
|
||||
# 将 MessageReceivedEvent 转换为现有的 Query 并投入 QueryPool
|
||||
# 复用现有的 MessageAggregator + QueryPool + Pipeline 机制
|
||||
launcher_type = (
|
||||
LauncherTypes.PERSON
|
||||
if event.chat_type == ChatType.PRIVATE
|
||||
else LauncherTypes.GROUP
|
||||
)
|
||||
|
||||
await self.ap.msg_aggregator.add_message(
|
||||
bot_uuid=event.bot_uuid,
|
||||
launcher_type=launcher_type,
|
||||
launcher_id=event.chat_id,
|
||||
sender_id=event.sender.id,
|
||||
message_event=event.to_legacy_event(), # 转换为 FriendMessage/GroupMessage
|
||||
message_chain=event.message_chain,
|
||||
adapter=adapter,
|
||||
pipeline_uuid=pipeline_uuid,
|
||||
)
|
||||
```
|
||||
|
||||
### 5.3 AgentHandler
|
||||
|
||||
直接调用 RequestRunner 处理事件，不经过 Pipeline Stage 链。
|
||||
|
||||
```python
|
||||
class AgentHandler(AbstractEventHandler):
|
||||
"""Agent 处理器 — 直接调用 RequestRunner 处理事件"""
|
||||
|
||||
async def handle(self, event, adapter, config):
|
||||
runner_name = config.get("runner", "local-agent")
|
||||
runner_config = config.get("runner_config", {})
|
||||
|
||||
# 1. 查找 Runner 类
|
||||
runner_cls = None
|
||||
for r in preregistered_runners:
|
||||
if r.name == runner_name:
|
||||
runner_cls = r
|
||||
break
|
||||
|
||||
if not runner_cls:
|
||||
self.ap.logger.error(f"Runner not found: {runner_name}")
|
||||
return
|
||||
|
||||
# 2. 构建事件上下文（将事件信息整理为 Runner 可处理的格式）
|
||||
event_context = self._build_event_context(event, runner_config)
|
||||
|
||||
# 3. 实例化并调用 Runner
|
||||
runner = runner_cls(self.ap, self._build_runner_pipeline_config(config))
|
||||
|
||||
response_messages = []
|
||||
async for result in runner.run(event_context):
|
||||
response_messages.append(result)
|
||||
|
||||
# 4. 发送响应（如果 Runner 产生了回复）
|
||||
if response_messages and isinstance(event, MessageReceivedEvent):
|
||||
# 将 Runner 输出转换为 MessageChain 并回复
|
||||
reply_chain = self._build_reply_chain(response_messages)
|
||||
await adapter.reply_message(event, reply_chain)
|
||||
|
||||
def _build_event_context(self, event, runner_config):
|
||||
"""将事件构建为 Runner 可处理的上下文
|
||||
|
||||
对于消息事件，直接使用消息内容。
|
||||
对于其他事件，根据 runner_config 中的 prompt 模板生成描述文本。
|
||||
"""
|
||||
...
|
||||
|
||||
def _build_runner_pipeline_config(self, config):
|
||||
"""将 handler_config 转换为 Runner 需要的 pipeline_config 格式"""
|
||||
...
|
||||
```
|
||||
|
||||
### 5.4 WebhookHandler
|
||||
|
||||
将事件 POST 到外部 URL。
|
||||
|
||||
```python
|
||||
class WebhookHandler(AbstractEventHandler):
|
||||
"""Webhook 处理器 — 将事件 POST 到外部 URL"""
|
||||
|
||||
async def handle(self, event, adapter, config):
|
||||
url = config.get("url")
|
||||
method = config.get("method", "POST")
|
||||
headers = config.get("headers", {})
|
||||
timeout = config.get("timeout", 30)
|
||||
retry_count = config.get("retry_count", 3)
|
||||
response_actions = config.get("response_actions", False)
|
||||
|
||||
# 1. 构建请求体
|
||||
bot = await self.ap.platform_mgr.get_bot_by_uuid(event.bot_uuid)
|
||||
payload = {
|
||||
"event": event.model_dump(),
|
||||
"bot": {
|
||||
"uuid": bot.bot_entity.uuid,
|
||||
"name": bot.bot_entity.name,
|
||||
"adapter": bot.bot_entity.adapter,
|
||||
}
|
||||
}
|
||||
|
||||
# 2. 发送请求（带重试）
|
||||
response = await self._send_with_retry(
|
||||
url, method, headers, payload, timeout, retry_count
|
||||
)
|
||||
|
||||
# 3. 处理响应动作
|
||||
if response_actions and response:
|
||||
await self._execute_response_actions(
|
||||
response, adapter, event
|
||||
)
|
||||
|
||||
async def _execute_response_actions(self, response, adapter, event):
|
||||
"""执行响应中的动作列表"""
|
||||
actions = response.get("actions", [])
|
||||
for action in actions:
|
||||
action_type = action.get("type")
|
||||
params = action.get("params", {})
|
||||
|
||||
if action_type == "send_message":
|
||||
chain = MessageChain.model_validate(params.get("message", []))
|
||||
await adapter.send_message(
|
||||
params["target_type"],
|
||||
params["target_id"],
|
||||
chain,
|
||||
)
|
||||
elif action_type == "reply":
|
||||
chain = MessageChain.model_validate(params.get("message", []))
|
||||
await adapter.reply_message(event, chain)
|
||||
elif action_type == "call_platform_api":
|
||||
await adapter.call_platform_api(
|
||||
params["action"],
|
||||
params.get("params", {}),
|
||||
)
|
||||
elif action_type == "approve_friend_request":
|
||||
await adapter.approve_friend_request(
|
||||
params["request_id"],
|
||||
params.get("approve", True),
|
||||
)
|
||||
# ... 更多动作类型
|
||||
```
|
||||
|
||||
### 5.5 PluginHandler
|
||||
|
||||
将事件分发给插件的 EventListener。
|
||||
|
||||
```python
|
||||
class PluginHandler(AbstractEventHandler):
|
||||
"""Plugin 处理器 — 分发给插件 EventListener"""
|
||||
|
||||
async def handle(self, event, adapter, config):
|
||||
plugin_filter = config.get("plugin_filter", [])
|
||||
|
||||
# 复用现有的插件事件分发机制
|
||||
# 通过 plugin_connector 将事件发送给 Plugin Runtime
|
||||
await self.ap.plugin_connector.emit_event(
|
||||
event=event,
|
||||
adapter=adapter,
|
||||
plugin_filter=plugin_filter,
|
||||
)
|
||||
```
|
||||
|
||||
## 6. use_pipeline_uuid 迁移
|
||||
|
||||
### 6.1 自动迁移
|
||||
|
||||
数据库迁移脚本将现有的 `use_pipeline_uuid` 自动转换为 `event_handlers`：
|
||||
|
||||
这里迁移的只有 Bot 路由字段：binding 仍指向原 Pipeline，不会新建 Agent，也不会复制 Pipeline 内嵌的 runner 配置。
|
||||
|
||||
```python
|
||||
# 迁移逻辑
|
||||
for bot in all_bots:
|
||||
if bot.use_pipeline_uuid and not bot.event_handlers:
|
||||
bot.event_handlers = [
|
||||
{
|
||||
"event_type": "message.received",
|
||||
"handler_type": "pipeline",
|
||||
"handler_config": {
|
||||
"pipeline_uuid": bot.use_pipeline_uuid
|
||||
},
|
||||
"enabled": True,
|
||||
"priority": 10,
|
||||
"description": "Auto-migrated from use_pipeline_uuid"
|
||||
},
|
||||
{
|
||||
"event_type": "*",
|
||||
"handler_type": "plugin",
|
||||
"handler_config": {},
|
||||
"enabled": True,
|
||||
"priority": -100,
|
||||
"description": "Default plugin handler"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 6.2 过渡期兼容
|
||||
|
||||
在过渡期内，如果 `event_handlers` 为空且 `use_pipeline_uuid` 非空，EventRouter 自动回退到旧行为：
|
||||
|
||||
```python
|
||||
# EventRouter.route() 中的兼容逻辑
|
||||
if not event_handlers and bot.bot_entity.use_pipeline_uuid:
|
||||
# 回退：消息事件走 Pipeline，其他事件走 Plugin
|
||||
if isinstance(event, MessageReceivedEvent):
|
||||
await self.handlers["pipeline"].handle(
|
||||
event, adapter,
|
||||
{"pipeline_uuid": bot.bot_entity.use_pipeline_uuid}
|
||||
)
|
||||
else:
|
||||
await self.handlers["plugin"].handle(event, adapter, {})
|
||||
return
|
||||
```
|
||||
|
||||
## 7. WebUI 编排面板数据模型
|
||||
|
||||
### 7.1 交互设计概要
|
||||
|
||||
在 WebUI 的 Bot 管理页面，新增"事件处理器"标签页（或区域），呈现为一个**规则列表**：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 事件处理器 [+ 添加规则] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─ 规则 1 ─────────────────────────────────── [启用] [删除] ─┐ │
|
||||
│ │ 事件类型: [message.received ▾] │ │
|
||||
│ │ 处理器: [Pipeline ▾] │ │
|
||||
│ │ Pipeline: [默认流水线 ▾] │ │
|
||||
│ │ 优先级: [10] │ │
|
||||
│ │ 描述: 消息事件使用默认流水线处理 │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─ 规则 2 ─────────────────────────────────── [启用] [删除] ─┐ │
|
||||
│ │ 事件类型: [group.member_joined ▾] │ │
|
||||
│ │ 处理器: [Agent ▾] │ │
|
||||
│ │ Runner: [local-agent ▾] │ │
|
||||
│ │ 模型: [gpt-4o-mini ▾] │ │
|
||||
│ │ Prompt: [有新成员加入...] │ │
|
||||
│ │ 优先级: [0] │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─ 规则 3 (兜底) ──────────────────────────── [启用] [删除] ─┐ │
|
||||
│ │ 事件类型: [* ▾] │ │
|
||||
│ │ 处理器: [Plugin ▾] │ │
|
||||
│ │ 优先级: [-100] │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.2 前端数据结构
|
||||
|
||||
```typescript
|
||||
interface EventHandlerRule {
|
||||
event_type: string; // 下拉选择，选项从适配器 manifest 的 supported_events 获取
|
||||
handler_type: string; // "pipeline" | "agent" | "webhook" | "plugin"
|
||||
handler_config: Record<string, any>; // 根据 handler_type 动态渲染不同的配置表单
|
||||
enabled: boolean;
|
||||
priority: number;
|
||||
description: string;
|
||||
}
|
||||
|
||||
// Bot 编辑接口扩展
|
||||
interface BotConfig {
|
||||
uuid: string;
|
||||
name: string;
|
||||
adapter: string;
|
||||
adapter_config: Record<string, any>;
|
||||
enable: boolean;
|
||||
event_handlers: EventHandlerRule[]; // 新增
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 事件类型下拉选项
|
||||
|
||||
从 Bot 关联的适配器 manifest 中获取 `supported_events`，加上通配符选项：
|
||||
|
||||
```
|
||||
- message.received
|
||||
- message.edited
|
||||
- message.deleted
|
||||
- message.reaction
|
||||
- feedback.received
|
||||
- group.member_joined
|
||||
- group.member_left
|
||||
- group.member_banned
|
||||
- group.info_updated
|
||||
- friend.request_received
|
||||
- friend.added
|
||||
- bot.invited_to_group
|
||||
- bot.removed_from_group
|
||||
- bot.muted
|
||||
- bot.unmuted
|
||||
- platform.specific
|
||||
─────────────────
|
||||
- message.* (所有消息事件)
|
||||
- feedback.* (所有反馈事件)
|
||||
- group.* (所有群组事件)
|
||||
- friend.* (所有好友事件)
|
||||
- bot.* (所有 Bot 事件)
|
||||
- * (所有事件)
|
||||
```
|
||||
|
||||
### 7.4 HTTP API
|
||||
|
||||
```
|
||||
GET /api/v1/bots/{uuid}/event-handlers 获取 Bot 的事件处理器配置
|
||||
PUT /api/v1/bots/{uuid}/event-handlers 更新 Bot 的事件处理器配置
|
||||
GET /api/v1/adapters/{name}/supported-events 获取适配器支持的事件类型
|
||||
GET /api/v1/adapters/{name}/supported-apis 获取适配器支持的 API
|
||||
```
|
||||
详见 [07-agent-orchestration.md](./07-agent-orchestration.md) 与 [08-agent-page-and-event-orchestration.md](./08-agent-page-and-event-orchestration.md)。
|
||||
|
||||
@@ -1,433 +1,145 @@
|
||||
# 分阶段迁移计划
|
||||
# EBA 分阶段实施计划
|
||||
|
||||
> **2026-06 方向修订**：Phase 3 的「四种 Handler 框架」与 Phase 5 的编排面板形态，按 [07-agent-orchestration.md](./07-agent-orchestration.md) 调整为「事件 → 处理器」统一路由。EventRouter 通过 `target_type` 在同级 Pipeline / Agent 间选择；二者分别保留自己的实体、配置和执行链。阶段划分、依赖关系与验收标准按 Processor 模型解读；发布节奏见 07 §5「发布火车」。
|
||||
> 更新：2026-07-12。文件名沿用早期设计，但这里的“迁移”仅指代码架构逐步接入 EBA，不代表 LangBot 3.x 数据库或配置升级。
|
||||
|
||||
## 1. 概述
|
||||
## 1. 发布边界
|
||||
|
||||
EBA 架构涉及 langbot-plugin-sdk、LangBot 后端、LangBot 前端、文档和示例插件等多个仓库的改动。为降低风险、保证系统稳定性，采用分阶段渐进式迁移策略。
|
||||
EBA 跨越 SDK、平台适配器、LangBot Host、WebUI 与插件生态，按可验证阶段落地。当前发布遵守以下硬边界：
|
||||
|
||||
### 1.1 阶段总览
|
||||
- LangBot 4.x 不支持从 3.x 数据库或配置升级；不保留 legacy migration chain、旧 JSON 模板或旧 Runner 字段读取。
|
||||
- Pipeline 与 Agent 平级且长期并存，分别保留持久化模型与执行链。
|
||||
- 现有 Pipeline 不迁移为 Agent，Pipeline 内的 runner config 不复制到 Agent。
|
||||
- 用户需要 Agent 时新建独立 Agent并选择已安装的 AgentRunner。
|
||||
- Host 不按 LocalAgent id 做运行时、Box 或 WebUI 特判。
|
||||
- AgentRunner 的 SDK/Python 与 scoped MCP bridge 回调共享 Host 授权与事件 session 规则。
|
||||
|
||||
| 阶段 | 名称 | 范围 | 依赖 |
|
||||
|------|------|------|------|
|
||||
| Phase 1 | SDK 实体层 | langbot-plugin-sdk | 无 |
|
||||
| Phase 2 | 适配器重构 | LangBot 后端 | Phase 1 |
|
||||
| Phase 3 | 核心系统 | LangBot 后端 | Phase 2 |
|
||||
| Phase 4 | 插件 SDK 集成 | langbot-plugin-sdk + LangBot | Phase 3 |
|
||||
| Phase 5 | WebUI 编排面板 | LangBot 前端 | Phase 3 |
|
||||
| Phase 6 | 文档与示例 | langbot-wiki + langbot-plugin-demo | Phase 4, 5 |
|
||||
## 2. 阶段总览
|
||||
|
||||
### 1.2 核心原则
|
||||
| 阶段 | 目标 | 主要仓库 | 完成条件 |
|
||||
| --- | --- | --- | --- |
|
||||
| P0 | SDK 事件、能力与 AgentRunner 协议 | `langbot-plugin-sdk` | typed entities、manifest、proxy、runtime action 通过测试 |
|
||||
| P1 | 平台适配器 EBA 化 | LangBot + SDK | 事件转换、能力声明、通用/透传 API 通过 adapter checklist |
|
||||
| P2 | Host 观察者与响应者路由 | LangBot backend | observer 广播 + Pipeline/Agent/discard 单目标仲裁可运行 |
|
||||
| P3 | 独立 Agent 与 Runner 注册 | LangBot backend + plugins | Agent CRUD、registry、run authorization、delivery 可运行 |
|
||||
| P4 | WebUI 处理器与事件编排 | LangBot web | Agent/Pipeline 聚合入口和 Bot binding 编辑器可用 |
|
||||
| P5 | 发布门禁与文档 | LangBot skills/docs + runner plugins | 单测、UI E2E、真实 adapter smoke 和插件预检通过 |
|
||||
|
||||
- **每个阶段结束后系统可运行**：任何阶段完成后，现有功能不受影响
|
||||
- **向后兼容贯穿全程**：旧接口在整个迁移期间保持可用
|
||||
- **先 SDK 后实现**：先定义好接口和模型，再做具体实现
|
||||
- **先核心适配器后边缘**：优先迁移用户量大的适配器
|
||||
## 3. P0：SDK 契约
|
||||
|
||||
---
|
||||
### 工作项
|
||||
|
||||
## 2. Phase 1：SDK 实体层
|
||||
- 定义规范化平台事件、actor/subject/conversation/delivery context。
|
||||
- 定义 adapter `supported_events`、`supported_apis` 与平台透传 API。
|
||||
- 定义 AgentRunner manifest、run context/result、resource handles 和 pull/callback API。
|
||||
- 提供 `AgentRunAPIProxy` 与 SDK-owned scoped MCP bridge。
|
||||
- 保持协议传输与权限校验可测试，不把 Host 私有 Query 对象暴露给插件。
|
||||
|
||||
**目标**：在 langbot-plugin-sdk 中定义新的事件体系、通用实体、API 接口和适配器基类。
|
||||
### 验收
|
||||
|
||||
**仓库**：`langbot-plugin-sdk`
|
||||
- stdio/WebSocket runtime 对 typed action 的序列化一致。
|
||||
- 无 `run_id` 或越权资源调用被拒绝。
|
||||
- Python proxy 与 MCP bridge 对同一 Host tool 呈现一致结果/错误形状。
|
||||
|
||||
### 2.1 任务清单
|
||||
## 4. P1：平台适配器
|
||||
|
||||
| # | 任务 | 文件/模块 | 说明 |
|
||||
|---|------|----------|------|
|
||||
| 1.1 | 定义通用事件基类层次 | `api/entities/builtin/platform/events.py` | 新增 `MessageReceivedEvent`, `MessageEditedEvent`, `GroupMemberJoinedEvent` 等，保留现有 `FriendMessage`/`GroupMessage` |
|
||||
| 1.2 | 定义平台特有事件基类 | `api/entities/builtin/platform/events.py` | 新增 `PlatformSpecificEvent` |
|
||||
| 1.3 | 扩展通用实体 | `api/entities/builtin/platform/entities.py` | 新增 `User`（统一 Friend/GroupMember 的基础）、`Channel` 等，保留现有实体 |
|
||||
| 1.4 | 清理消息组件 | `api/entities/builtin/platform/message.py` | 将 `WeChatMiniPrograms` 等 WeChat 特有组件标记为 platform-specific，不再作为通用组件 |
|
||||
| 1.5 | 定义新适配器基类 | `api/definition/abstract/platform/adapter.py` | 新增 `AbstractPlatformAdapter`（继承现有 `AbstractMessagePlatformAdapter` 并扩展通用 API 方法），保留旧基类 |
|
||||
| 1.6 | 定义 API 能力声明 | `api/definition/abstract/platform/capabilities.py`（新文件） | `AdapterCapabilities` 数据类，声明适配器支持的事件和 API |
|
||||
| 1.7 | 定义 `NotSupportedError` | `api/entities/builtin/platform/errors.py`（新文件） | 可选 API 未实现时抛出的异常 |
|
||||
每个适配器按自己的能力增量接入，而不是要求所有平台一次性支持全部事件。
|
||||
|
||||
### 2.2 关键设计约束
|
||||
### 单适配器步骤
|
||||
|
||||
- 所有新增定义以**新增文件或新增类**的方式引入，**不修改**现有类的字段和方法签名
|
||||
- 现有 `AbstractMessagePlatformAdapter` 保留不动，新基类 `AbstractPlatformAdapter` 继承它
|
||||
- 新事件类与旧事件类并存，通过 `event_type` 字段（命名空间字符串）区分
|
||||
1. 将原生 SDK callback 转换为规范化事件。
|
||||
2. 声明实际支持的事件与 API，不把缺失能力伪装为成功。
|
||||
3. 实现 send/reply/edit/delete/group/user 等适用 API 与平台透传。
|
||||
4. 对消息链、媒体、reply target 和错误语义写单元测试。
|
||||
5. 按 `adapters/acceptance-checklist.md` 记录真实平台 probe。
|
||||
|
||||
### 2.3 验收标准
|
||||
### 验收
|
||||
|
||||
- [ ] 所有新增类可正常 import 且通过类型检查
|
||||
- [ ] 现有 `FriendMessage`, `GroupMessage`, `AbstractMessagePlatformAdapter` 等类行为不变
|
||||
- [ ] 新增单元测试覆盖事件序列化/反序列化、实体构造
|
||||
- [ ] SDK 版本号 minor bump（如 `0.x.0` → `0.x+1.0`）
|
||||
- `message.received` 保持正常收发。
|
||||
- 新事件不会重复转换或产生循环合成事件。
|
||||
- `supported_apis` 与实际调用能力一致。
|
||||
|
||||
---
|
||||
## 5. P2：Host 路由
|
||||
|
||||
## 3. Phase 2：适配器重构
|
||||
### 执行顺序
|
||||
|
||||
**目标**：将现有单文件适配器迁移到独立目录结构，实现新事件监听和通用 API。
|
||||
|
||||
**仓库**：`LangBot`（后端）
|
||||
|
||||
### 3.1 适配器迁移优先级
|
||||
|
||||
根据用户量和代表性，建议按以下顺序迁移：
|
||||
|
||||
| 优先级 | 适配器 | 理由 |
|
||||
|--------|--------|------|
|
||||
| P0 | **Telegram** | 用户量大，API 最完善，适合作为参考实现 |
|
||||
| P0 | **Discord** | 国际用户主要平台，事件类型丰富 |
|
||||
| P1 | **aiocqhttp**（OneBot v11） | 国内 QQ 用户主要适配器 |
|
||||
| P1 | **Satori** | 通用协议适配器，覆盖多个平台 |
|
||||
| P2 | **Lark** / **DingTalk** / **Slack** | 企业平台，用户量中等 |
|
||||
| P2 | **qqofficial** / **WeChat 系列** | 国内用户 |
|
||||
| P3 | **Kook** / **LINE** / **WeCom 系列** | 用户量较小 |
|
||||
| P3 | **WebSocket** | 内置适配器，相对简单 |
|
||||
| P4 | **legacy/*** | 遗留适配器，按需决定是否迁移或废弃 |
|
||||
|
||||
### 3.2 单个适配器迁移步骤（以 Telegram 为例）
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|------|------|
|
||||
| 2.1 | 创建目录结构 | `pkg/platform/adapters/telegram/` 下创建 `__init__.py`, `adapter.py`, `event_converter.py`, `message_converter.py`, `api_impl.py`, `types.py`, `manifest.yaml` |
|
||||
| 2.2 | 迁移消息转换器 | 将 `TelegramMessageConverter` 从 `sources/telegram.py` 搬到 `adapters/telegram/message_converter.py`，逻辑不变 |
|
||||
| 2.3 | 重写事件转换器 | 新的 `TelegramEventConverter` 支持将 Telegram Update 转换为所有通用事件类型（不只是消息），不支持的事件转为 `PlatformSpecificEvent` |
|
||||
| 2.4 | 实现通用 API | 在 `api_impl.py` 中实现 `edit_message`, `delete_message`, `get_group_info` 等 Telegram 支持的通用 API |
|
||||
| 2.5 | 实现透传 API | 在 `adapter.py` 中实现 `call_platform_api`，将 action 映射到 Telegram Bot API 调用 |
|
||||
| 2.6 | 声明能力 | 在 `manifest.yaml` 或适配器类中声明支持的事件和 API 列表 |
|
||||
| 2.7 | 新建 Adapter 主类 | `TelegramAdapter` 继承 `AbstractPlatformAdapter`（新基类），委托各模块实现 |
|
||||
| 2.8 | 更新 manifest.yaml | 更新 `execution.python.path` 指向新位置 |
|
||||
| 2.9 | 验证 | 确保新适配器通过现有消息收发流程的测试 |
|
||||
|
||||
### 3.3 基础设施任务
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|------|------|
|
||||
| 2.A | 创建 `adapters/_base/` | 将 SDK 中新基类的运行时辅助代码放在此处（如事件分发辅助函数） |
|
||||
| 2.B | 更新 ComponentDiscovery | 使 `discover_blueprint` 支持扫描 `adapters/` 子目录中的 YAML |
|
||||
| 2.C | 更新 `templates/components.yaml` | 将 `fromDirs` 从 `pkg/platform/sources/` 改为 `pkg/platform/adapters/`（过渡期两个都扫描） |
|
||||
| 2.D | 保留旧 sources/ | 过渡期不删除旧文件，通过 manifest 的 `deprecated: true` 标记 |
|
||||
|
||||
### 3.4 验收标准
|
||||
|
||||
- [ ] 已迁移的适配器在新目录结构下正常启动和收发消息
|
||||
- [ ] 新事件（如 `message.edited`）在支持的平台上正确触发
|
||||
- [ ] 通用 API（如 `edit_message`）在支持的平台上正确执行
|
||||
- [ ] 未迁移的适配器（仍在 `sources/`）继续正常工作
|
||||
- [ ] ComponentDiscovery 同时扫描新旧目录
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase 3：核心系统
|
||||
|
||||
**目标**：实现 EventBus、EventRouter 和事件处理器框架，将事件从适配器分发到不同的处理器。
|
||||
|
||||
**仓库**：`LangBot`（后端）
|
||||
|
||||
### 4.1 任务清单
|
||||
|
||||
| # | 任务 | 文件/模块 | 说明 |
|
||||
|---|------|----------|------|
|
||||
| 3.1 | 实现 EventBus | `pkg/platform/event_bus.py`（新文件） | 事件总线：接收适配器事件，进行日志记录，分发给 EventRouter |
|
||||
| 3.2 | 实现 EventRouter | `pkg/platform/event_router.py`（新文件） | 事件路由引擎：读取 Bot 的 `event_handlers` 配置，匹配事件类型，分发到对应 Handler |
|
||||
| 3.3 | 实现 PipelineHandler | `pkg/platform/handlers/pipeline_handler.py` | 将 `message.received` 事件转为现有 Query，进入 Pipeline 流水线 |
|
||||
| 3.4 | 实现 AgentHandler | `pkg/platform/handlers/agent_handler.py` | 直接调用 RequestRunner 处理事件，不经过 Pipeline 多 Stage 流程 |
|
||||
| 3.5 | 实现 WebhookHandler | `pkg/platform/handlers/webhook_handler.py` | 将事件 POST 到外部 URL，解析响应执行动作（重构现有 WebhookPusher） |
|
||||
| 3.6 | 实现 PluginHandler | `pkg/platform/handlers/plugin_handler.py` | 将事件分发给插件 EventListener（复用现有 plugin_connector 机制） |
|
||||
| 3.7 | Bot 实体扩展 | `pkg/entity/persistence/bot.py` | 新增 `event_handlers` JSON 字段 |
|
||||
| 3.8 | 数据库迁移 | `pkg/persistence/migrations/` | 新增迁移脚本：添加 `event_handlers` 列，将现有 `use_pipeline_uuid` 数据迁移为 `event_handlers` 格式 |
|
||||
| 3.9 | 重构 RuntimeBot | `pkg/platform/botmgr.py` | 将 `initialize()` 中硬编码的 `on_friend_message`/`on_group_message` 回调替换为通过 EventBus 分发所有事件 |
|
||||
| 3.10 | 重构 MessageAggregator | `pkg/pipeline/aggregator.py` | 从 RuntimeBot 解耦，作为 PipelineHandler 的内部机制（只对 `message.received` 事件生效） |
|
||||
| 3.11 | Agent Handler 中 RequestRunner 解耦 | `pkg/provider/runner.py` + handlers | RequestRunner 需要能独立于 Pipeline Stage 运行，为 Agent Handler 提供轻量调用路径 |
|
||||
| 3.12 | HTTP API 扩展 | `pkg/api/http/controller/` | 新增/更新 Bot API 端点以支持 `event_handlers` 的 CRUD |
|
||||
|
||||
### 4.2 数据迁移策略
|
||||
|
||||
现有 Bot 表有 `use_pipeline_uuid` 字段，需要自动迁移为 `event_handlers`：
|
||||
|
||||
该步骤只改写 Bot 的路由表示，仍通过原 UUID 指向原 Pipeline；不得创建独立 Agent，也不得复制 Pipeline 内嵌的 runner 配置。用户需要 Agent 时自行新增并绑定。
|
||||
|
||||
```python
|
||||
# 迁移逻辑伪代码
|
||||
for bot in all_bots:
|
||||
if bot.use_pipeline_uuid:
|
||||
bot.event_handlers = [
|
||||
{
|
||||
"event_type": "message.received",
|
||||
"handler_type": "pipeline",
|
||||
"handler_config": {
|
||||
"pipeline_uuid": bot.use_pipeline_uuid
|
||||
}
|
||||
}
|
||||
]
|
||||
else:
|
||||
bot.event_handlers = []
|
||||
```text
|
||||
adapter event
|
||||
-> EventBus observer broadcast
|
||||
-> EventRouter match event_bindings
|
||||
-> one target: Pipeline | Agent | discard
|
||||
-> Host delivery
|
||||
```
|
||||
|
||||
### 4.3 RuntimeBot 重构要点
|
||||
### 约束
|
||||
|
||||
当前 `RuntimeBot.initialize()` 硬编码注册两个回调：
|
||||
- Plugin EventListener 是 observer，不作为 priority fallback。
|
||||
- Pipeline 只处理消息事件并复用完整 Stage 链。
|
||||
- Agent 使用独立 Agent 配置和 AgentRunner Host orchestrator。
|
||||
- edit/reaction 等事件的 observer 副作用能力按事件和 adapter 能力过滤。
|
||||
- dry-run 与合成派发必须使用同一匹配器，避免 UI 预览与真实路由漂移。
|
||||
|
||||
```python
|
||||
# 现有代码 (botmgr.py)
|
||||
self.adapter.register_listener(FriendMessage, on_friend_message)
|
||||
self.adapter.register_listener(GroupMessage, on_group_message)
|
||||
```
|
||||
### 验收
|
||||
|
||||
重构后改为注册通用事件回调：
|
||||
- 精确、namespace wildcard、全局 wildcard、filters 与 priority 有单元覆盖。
|
||||
- 同一事件最多一个响应目标，但 observer 仍能收到事件。
|
||||
- Pipeline 与 Agent 可以在同一个 Bot 的不同 binding 中同时生效。
|
||||
|
||||
```python
|
||||
# 新代码
|
||||
async def on_event(event: Event, adapter: AbstractPlatformAdapter):
|
||||
await self.event_bus.emit(
|
||||
bot_uuid=self.bot_entity.uuid,
|
||||
event=event,
|
||||
adapter=adapter,
|
||||
)
|
||||
## 6. P3：独立 Agent 与 AgentRunner
|
||||
|
||||
# 注册所有事件类型的统一回调
|
||||
self.adapter.register_listener(Event, on_event)
|
||||
```
|
||||
### 工作项
|
||||
|
||||
EventBus 接收事件后，调用 EventRouter 按配置分发。
|
||||
- `agents` 只保存 Agent；Pipeline 继续使用自己的表和 API。
|
||||
- Agent config 使用 `runner.id` 与 `runner_config[runner_id]`。
|
||||
- registry 只展示已安装、有效的插件 AgentRunner。
|
||||
- Host 构造 run-scoped resources、state、delivery 与 event log/transcript。
|
||||
- SDK/Python `call_tool` 和 scoped MCP bridge 都回到同一个 Host ToolManager。
|
||||
- Box session 由 Host 将 instance/workspace/bot/adapter/target/thread scope 规范化并哈希为固定长度 `lb-box-<sha256>`；同 scope 稳定、不同 scope 隔离、缺少 identity 时 fail closed。
|
||||
|
||||
### 4.4 事件处理器执行流程
|
||||
### 验收
|
||||
|
||||
```
|
||||
EventBus.emit(bot_uuid, event, adapter)
|
||||
│
|
||||
▼
|
||||
EventRouter.route(bot_uuid, event)
|
||||
│ 查询 bot.event_handlers 配置
|
||||
│ 匹配 event_type（精确匹配 > 通配符 *）
|
||||
▼
|
||||
匹配到的 Handler(s)
|
||||
│
|
||||
├── PipelineHandler.handle(event, adapter)
|
||||
│ │ 仅支持 message.received
|
||||
│ │ 构造 Query → MessageAggregator → QueryPool → Pipeline
|
||||
│ └── 沿用现有完整流水线机制
|
||||
│
|
||||
├── AgentHandler.handle(event, adapter)
|
||||
│ │ 根据 handler_config 选择 RequestRunner
|
||||
│ │ 直接调用 runner.run() 处理事件
|
||||
│ └── 将结果通过 adapter API 回复
|
||||
│
|
||||
├── WebhookHandler.handle(event, adapter)
|
||||
│ │ 序列化事件为 JSON
|
||||
│ │ POST 到 handler_config.url
|
||||
│ └── 解析响应，执行动作（回复消息、调用 API 等）
|
||||
│
|
||||
└── PluginHandler.handle(event, adapter)
|
||||
│ 通过 plugin_connector 分发给插件
|
||||
└── 插件 EventListener 处理
|
||||
```
|
||||
- 安装/卸载 Runner 后 metadata 与表单选项同步。
|
||||
- Runner 无法调用未授权 model/tool/knowledge/state。
|
||||
- 两种 Host callback transport 不能覆盖 sandbox session id。
|
||||
- LocalAgent、ACP/ClaudeCode/Codex 与外部服务 Runner 不需要 Host id 特判。
|
||||
|
||||
### 4.5 验收标准
|
||||
## 7. P4：WebUI
|
||||
|
||||
- [ ] `message.received` 事件通过 PipelineHandler 正确进入现有 Pipeline（与旧行为一致）
|
||||
- [ ] 新增事件（如 `group.member_joined`）能通过 PluginHandler 分发给插件
|
||||
- [ ] AgentHandler 能直接调用 RequestRunner（至少 `local-agent`）处理事件并回复
|
||||
- [ ] WebhookHandler 能将事件 POST 到外部 URL
|
||||
- [ ] 数据库迁移正确执行，`use_pipeline_uuid` 数据迁移到 `event_handlers`
|
||||
- [ ] 现有 Bot 在不修改配置的情况下行为不变（自动迁移保证）
|
||||
### 工作项
|
||||
|
||||
---
|
||||
- `/home/agents` 聚合显示 Agent 与 Pipeline，并明确类型。
|
||||
- 创建时选择 Agent 或 Pipeline，编辑时进入各自表单。
|
||||
- Agent 表单读取动态 Runner metadata，保存当前 `runner` / `runner_config` 形状。
|
||||
- Bot 事件编排器编辑 `event_pattern`、target、filters、priority 与 enabled。
|
||||
- 非消息事件过滤 Pipeline；Agent 按声明事件能力过滤。
|
||||
|
||||
## 5. Phase 4：插件 SDK 集成
|
||||
### 验收
|
||||
|
||||
**目标**：将新事件和 API 通过插件 SDK 暴露给插件开发者，同时实现兼容层。
|
||||
- 页面不出现 LocalAgent 专属 banner、变量隐藏或 Box/Pipeline 注入逻辑。
|
||||
- 空 Runner 市场状态给出可安装 AgentRunner 的正常路径。
|
||||
- Pipeline Debug Chat/Monitoring 与 Agent 运行日志分别可用。
|
||||
|
||||
**仓库**：`langbot-plugin-sdk` + `LangBot`
|
||||
## 8. P5：发布门禁
|
||||
|
||||
### 5.1 任务清单
|
||||
### 自动化
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|------|------|
|
||||
| 4.1 | 新增插件事件包装 | 在 `api/entities/events.py` 中为每个通用事件新增插件级事件类（如 `MessageEditedReceived`, `MemberJoinedReceived`） |
|
||||
| 4.2 | 兼容层实现 | `PersonMessageReceived` / `GroupMessageReceived` 由新的 `MessageReceivedEvent` 自动生成，旧事件作为新事件的 alias |
|
||||
| 4.3 | 新 API 暴露 | 在 `LangBotAPIProxy` 中新增方法：`edit_message`, `delete_message`, `get_group_info`, `get_user_info`, `call_platform_api` 等 |
|
||||
| 4.4 | 通信协议扩展 | 在 `entities/io/actions/enums.py` 中新增 action 枚举（如 `EDIT_MESSAGE`, `DELETE_MESSAGE`, `GET_GROUP_INFO`, `CALL_PLATFORM_API`） |
|
||||
| 4.5 | Runtime Handler 扩展 | 在 PluginConnectionHandler / ControlConnectionHandler 中添加新 action 的处理逻辑 |
|
||||
| 4.6 | EventListener 扩展 | 确保 `@handler()` 装饰器支持注册新事件类型 |
|
||||
| 4.7 | QueryBasedAPI 扩展 | 在 `QueryBasedAPIProxy` 中新增事件上下文相关的 API（如 `get_event_source_adapter`） |
|
||||
- LangBot backend unit/integration tests 与 Ruff。
|
||||
- SDK AgentRunner/proxy/MCP bridge tests。
|
||||
- Web lint/build 与关键 Playwright cases。
|
||||
- `skills/bin/lbs validate`、`skills/bin/lbs index --check`。
|
||||
- LocalAgent 与其他官方 Runner plugin package/test gate。
|
||||
|
||||
### 5.2 兼容层详细设计
|
||||
### 真实环境
|
||||
|
||||
```
|
||||
新事件系统 旧事件系统（兼容层）
|
||||
───────────── ─────────────────
|
||||
MessageReceivedEvent ┌→ PersonMessageReceived (chat_type == "private")
|
||||
(chat_type: "private"|"group") ┤
|
||||
└→ GroupMessageReceived (chat_type == "group")
|
||||
```
|
||||
- 至少一个消息事件走 Pipeline。
|
||||
- 至少一个非消息事件走独立 Agent 并执行平台动作。
|
||||
- SDK/Python 和 MCP bridge 各完成一次受权工具调用，并证明二者都进入同一个 `PluginToRuntimeAction.CALL_TOOL` Host handler。
|
||||
- Box 可用/不可用的降级路径可观察且无 Runner 特判。
|
||||
|
||||
**实现方式**：在 RuntimeEventDispatcher 中，当分发 `MessageReceivedEvent` 给插件时，同时生成对应的旧事件类实例。插件可以用新事件类或旧事件类注册 handler，都能收到。
|
||||
## 9. 非目标
|
||||
|
||||
### 5.3 验收标准
|
||||
|
||||
- [ ] 现有插件（使用旧事件和 API）无需修改即可运行
|
||||
- [ ] 新插件可以使用新事件类型（如 `MemberJoinedReceived`）注册 handler
|
||||
- [ ] 新 API（如 `edit_message`）可通过 `self.edit_message()` 或 `event_context.edit_message()` 调用
|
||||
- [ ] 透传 API `call_platform_api` 可正常调用适配器特有功能
|
||||
- [ ] 所有新 action 的通信协议正确工作（stdio / WebSocket）
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 5：WebUI 编排面板
|
||||
|
||||
**目标**：在 WebUI 的 Bot 管理页面实现事件处理器的可视化编排。
|
||||
|
||||
**仓库**：`LangBot`（前端 `web/`）
|
||||
|
||||
### 6.1 任务清单
|
||||
|
||||
| # | 任务 | 说明 |
|
||||
|---|------|------|
|
||||
| 5.1 | Bot 编辑页面扩展 | 在 Bot 编辑页面新增「事件处理」面板 |
|
||||
| 5.2 | 事件处理器列表组件 | 可视化展示当前 Bot 的 `event_handlers` 列表，支持增删改排序 |
|
||||
| 5.3 | 事件类型选择器 | 下拉选择事件类型（命名空间分组展示），支持通配符 `*` |
|
||||
| 5.4 | Handler 类型选择与配置 | 选择 handler 类型后展示对应的配置表单（Pipeline 选择器、Runner 选择器、Webhook URL 等） |
|
||||
| 5.5 | Pipeline Handler 配置 | 复用现有的 Pipeline 选择 UI（从现有 `use_pipeline_uuid` 选择器迁移） |
|
||||
| 5.6 | Agent Handler 配置 | Runner 选择器（local-agent / dify / n8n / coze 等）+ Runner 参数配置表单 |
|
||||
| 5.7 | Webhook Handler 配置 | URL 输入、认证方式选择、Header 配置 |
|
||||
| 5.8 | Plugin Handler 配置 | 通常无需额外配置，分发给所有匹配的插件 EventListener |
|
||||
| 5.9 | HTTP API 对接 | 前端调用后端 API 保存/读取 `event_handlers` 配置 |
|
||||
| 5.10 | 迁移提示 | 对于从旧版本升级的用户，如果检测到 `use_pipeline_uuid` 已自动迁移，展示提示说明 |
|
||||
|
||||
### 6.2 UI 交互设计概要
|
||||
|
||||
```
|
||||
┌─ Bot 编辑页面 ─────────────────────────────────────┐
|
||||
│ │
|
||||
│ 基本信息 │ 适配器配置 │ ★ 事件处理 │ │
|
||||
│ │
|
||||
│ ┌─ 事件处理器列表 ────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ ① message.received → Pipeline: "主流水线" │ │
|
||||
│ │ [编辑] [删除] │ │
|
||||
│ │ │ │
|
||||
│ │ ② group.member_joined → Agent: local-agent │ │
|
||||
│ │ [编辑] [删除] │ │
|
||||
│ │ │ │
|
||||
│ │ ③ * (默认) → Plugin │ │
|
||||
│ │ [编辑] [删除] │ │
|
||||
│ │ │ │
|
||||
│ │ [+ 添加事件处理器] │ │
|
||||
│ │ │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [保存] [取消] │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.3 验收标准
|
||||
|
||||
- [ ] 用户可以在 WebUI 上为 Bot 添加/编辑/删除事件处理器
|
||||
- [ ] 四种 Handler 类型均有对应的配置表单
|
||||
- [ ] 配置保存后正确写入数据库 `event_handlers` 字段
|
||||
- [ ] 旧版本升级后，自动迁移的配置在 UI 上正确展示
|
||||
- [ ] Pipeline Handler 的行为与旧的 `use_pipeline_uuid` 完全一致
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase 6：文档与示例
|
||||
|
||||
**目标**：更新所有面向开发者的文档和示例。
|
||||
|
||||
**仓库**：`langbot-wiki`, `langbot-plugin-demo`
|
||||
|
||||
### 7.1 任务清单
|
||||
|
||||
| # | 任务 | 仓库 | 说明 |
|
||||
|---|------|------|------|
|
||||
| 6.1 | EBA 架构概览文档 | langbot-wiki | 面向用户的新架构说明 |
|
||||
| 6.2 | 适配器开发指南更新 | langbot-wiki | 如何开发一个新的适配器（新目录结构、新基类、事件转换等） |
|
||||
| 6.3 | 插件开发指南更新 | langbot-wiki | 新事件类型、新 API 的使用说明 |
|
||||
| 6.4 | 插件迁移指南 | langbot-wiki | 现有插件如何迁移到新事件/API（如果需要使用新能力） |
|
||||
| 6.5 | 事件处理器配置指南 | langbot-wiki | WebUI 上如何配置事件处理器 |
|
||||
| 6.6 | 示例插件更新 | langbot-plugin-demo | HelloPlugin 增加新事件监听示例、新 API 调用示例 |
|
||||
| 6.7 | 新示例插件 | langbot-plugin-demo | 新建一个示例展示非消息事件处理（如入群欢迎） |
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险评估与缓解
|
||||
|
||||
### 8.1 技术风险
|
||||
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|----------|
|
||||
| 适配器迁移中断现有功能 | 高 | 中 | 新旧目录并存，ComponentDiscovery 同时扫描两个目录，逐个适配器迁移验证 |
|
||||
| 事件模型不兼容导致插件崩溃 | 高 | 低 | 兼容层保证旧事件类型继续工作，新增类不修改旧类 |
|
||||
| 数据库迁移失败 | 高 | 低 | 迁移脚本做前置校验，`use_pipeline_uuid` 在过渡期保留不删除 |
|
||||
| RequestRunner 解耦破坏 Pipeline | 高 | 中 | Agent Handler 调用 Runner 的路径独立于 Pipeline，不修改现有 Pipeline Stage 中的 Runner 调用逻辑 |
|
||||
| 性能回退（EventBus 额外开销） | 中 | 低 | EventBus 在进程内同步分发，无额外序列化/网络开销 |
|
||||
| 各平台事件差异大难以统一 | 中 | 中 | 通用事件只抽象最大公约数字段，差异部分保留在 `source_platform_object`；不支持的事件走 `PlatformSpecificEvent` |
|
||||
|
||||
### 8.2 兼容性风险
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|------|----------|
|
||||
| 现有插件使用旧事件类 | 兼容层自动将新事件转为旧事件分发，两种事件类都能注册 handler |
|
||||
| 现有插件调用 `reply()` / `send_message()` | 这两个 API 保持不变，只是底层实现可能微调 |
|
||||
| 第三方基于 `AbstractMessagePlatformAdapter` 开发的适配器 | 旧基类保留，新基类继承旧基类，第三方适配器无需立即迁移 |
|
||||
| 用户自定义 Pipeline 配置 | Pipeline 机制完整保留，PipelineHandler 只是入口变了（从 RuntimeBot 硬编码变为 EventRouter 配置） |
|
||||
|
||||
### 8.3 回滚策略
|
||||
|
||||
每个 Phase 独立可回滚：
|
||||
|
||||
- **Phase 1**（SDK 新增类）：删除新增文件，回退 SDK 版本号
|
||||
- **Phase 2**（适配器目录）：恢复 `components.yaml` 的 `fromDirs` 指向旧目录，旧 sources/ 未删除
|
||||
- **Phase 3**（核心系统）：回退数据库迁移，恢复 RuntimeBot 旧的硬编码回调
|
||||
- **Phase 4**（插件集成）：回退 SDK 版本，插件使用旧版 SDK
|
||||
- **Phase 5**（WebUI）：前端回退，Bot 编辑页面隐藏事件处理面板
|
||||
|
||||
---
|
||||
|
||||
## 9. 里程碑与时间线建议
|
||||
|
||||
| 里程碑 | 阶段 | 预期产出 |
|
||||
|--------|------|----------|
|
||||
| M1 | Phase 1 完成 | SDK 新版本发布，包含新事件/实体/基类定义 |
|
||||
| M2 | Phase 2 首批适配器（Telegram + Discord） | 两个参考实现，验证目录结构和事件/API 体系 |
|
||||
| M3 | Phase 3 核心系统 | EventBus + EventRouter + 四种 Handler 可用 |
|
||||
| M4 | Phase 2 剩余适配器 | 所有活跃适配器迁移完成 |
|
||||
| M5 | Phase 4 插件集成 | 新 SDK 发布，插件可使用新事件和 API |
|
||||
| M6 | Phase 5 WebUI | 事件处理器编排面板上线 |
|
||||
| M7 | Phase 6 文档 | 开发者文档和示例更新完毕 |
|
||||
|
||||
建议 M1-M3 作为第一个大版本发布（如 v5.0），M4-M7 在后续小版本迭代中完成。
|
||||
|
||||
---
|
||||
|
||||
## 10. 开发指引
|
||||
|
||||
### 10.1 分支策略
|
||||
|
||||
建议在主仓库创建 `feature/eba` 长期特性分支，各 Phase 在子分支上开发后合入特性分支：
|
||||
|
||||
```
|
||||
main
|
||||
└── feature/eba
|
||||
├── feature/eba-sdk-entities (Phase 1)
|
||||
├── feature/eba-adapter-telegram (Phase 2)
|
||||
├── feature/eba-adapter-discord (Phase 2)
|
||||
├── feature/eba-core-system (Phase 3)
|
||||
├── feature/eba-plugin-sdk (Phase 4)
|
||||
└── feature/eba-webui (Phase 5)
|
||||
```
|
||||
|
||||
### 10.2 测试策略
|
||||
|
||||
| 层次 | 测试内容 | 工具 |
|
||||
|------|----------|------|
|
||||
| 单元测试 | 事件序列化/反序列化、实体构造、API 调用 mock | pytest |
|
||||
| 集成测试 | EventBus → EventRouter → Handler 全链路 | pytest + asyncio |
|
||||
| 适配器测试 | 各适配器的事件转换、消息转换、API 调用 | pytest + mock SDK |
|
||||
| 端到端测试 | 从模拟平台事件到完整处理流程 | staging 环境 |
|
||||
| 插件兼容性测试 | 旧插件在新系统下的行为 | langbot-plugin-demo |
|
||||
|
||||
### 10.3 代码审查关注点
|
||||
|
||||
- 新增代码是否影响现有行为
|
||||
- 兼容层是否正确映射所有旧事件/API 场景
|
||||
- 数据库迁移是否可逆
|
||||
- 新 API 的错误处理（`NotSupportedError`）是否一致
|
||||
- 事件模型的序列化在 stdio/WebSocket 通信中是否正确
|
||||
- 不把 Pipeline 改名或包装成 Agent。
|
||||
- 不自动把 Pipeline 内 runner 配置迁移成 Agent。
|
||||
- 不为 3.x 保留数据库迁移、旧模板或配置 fallback。
|
||||
- 不要求所有 Runner 经 MCP；本地 Python Runner 可以直接使用 SDK。
|
||||
- 不允许 Runner 自定义 Box session scope。
|
||||
- 不在首版实现多 Agent 串并联；多步骤编排留给后续 workflow。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Box 系统架构深度分析
|
||||
|
||||
> 更新日期: 2026-06-02
|
||||
> 更新日期: 2026-07-12
|
||||
> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
|
||||
> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
|
||||
> 相关文档: [SaaS 阻塞项](./box-issues.md) | [Session 作用域](./box-session-scope.md) | [Runtime 对比](./box-vs-plugin-runtime.md) | [测试覆盖](./box-test-coverage.md) | [toB 分析](./box-tob-analysis.md)
|
||||
@@ -13,7 +13,9 @@
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ LangBot 主进程 │
|
||||
│ │
|
||||
│ LocalAgentRunner ──> ToolManager ──> NativeToolLoader │
|
||||
│ AgentRunner ──> SDK call_tool / scoped MCP bridge │
|
||||
│ │ │ │
|
||||
│ └────────────────> ToolManager ──> NativeToolLoader │
|
||||
│ │ │ │ │
|
||||
│ │ │ exec / read / write / edit │
|
||||
│ │ │ glob / grep │
|
||||
@@ -32,7 +34,7 @@
|
||||
│ ├─ Host mount 校验 (allowed_mount_roots) │
|
||||
│ ├─ Workspace quota 检查 │
|
||||
│ ├─ 输出截断 (head+tail) │
|
||||
│ ├─ Session ID 模板解析 (resolve_box_session_id) │
|
||||
│ ├─ Host scope 哈希 (resolve_box_session_id) │
|
||||
│ ├─ 技能挂载组装 (build_skill_extra_mounts) │
|
||||
│ ├─ 重连循环 (_reconnect_loop, 指数退避) │
|
||||
│ └─ BoxRuntimeConnector │
|
||||
@@ -85,7 +87,8 @@
|
||||
**核心设计原则**:
|
||||
- Box Runtime 作为独立进程运行，通过 Action RPC 与 LangBot 主进程通信，两者复用 SDK 的 IO 层（Handler → Connection → Controller）
|
||||
- 一个 session_id 对应一个容器/沙箱实例。同一 session 内可并存多条 mount 与多个 managed process
|
||||
- Skill / 默认 exec / MCP Server 共享同一个 session 容器（详见 [box-session-scope.md](./box-session-scope.md)）
|
||||
- AgentRunner 无权指定 session scope。SDK/Python `call_tool` 与 scoped MCP bridge 都发出同一个 `PluginToRuntimeAction.CALL_TOOL`，最终由 Host 的 ToolManager 执行，并使用当前 run 保存的同一个 execution Query
|
||||
- Box 内托管的 stdio MCP server 使用独立的长期 `mcp-shared` session；它不是 AgentRunner 本次事件的 sandbox session（详见 [box-session-scope.md](./box-session-scope.md)）
|
||||
|
||||
---
|
||||
|
||||
@@ -93,7 +96,7 @@
|
||||
|
||||
### 2.1 BoxService (`pkg/box/service.py`, 722 行)
|
||||
|
||||
应用层门面，协调 Profile、安全校验、配额、连接、Skill 挂载与 Session 模板：
|
||||
应用层门面，协调 Profile、安全校验、配额、连接、Skill 挂载与 Host scope 哈希：
|
||||
|
||||
主要公开方法（按定义顺序）：
|
||||
|
||||
@@ -104,7 +107,7 @@ BoxService
|
||||
├─ _reconnect_loop(connector) 指数退避重连
|
||||
├─ available (property) 连接状态
|
||||
│
|
||||
├─ resolve_box_session_id(query) 从 pipeline 模板解析 session_id
|
||||
├─ resolve_box_session_id(query) 哈希 Host 私有 scope，生成固定长度 session_id
|
||||
├─ build_skill_extra_mounts(query) 组装 pipeline-bound skill 的挂载列表
|
||||
│
|
||||
├─ execute_tool(parameters, query) Agent 调用 exec 时的入口
|
||||
@@ -137,6 +140,8 @@ BoxService
|
||||
|
||||
**输出截断**: 默认 4000 字符上限，保留前 60% + 后 40%，中间插入 `[...truncated...]`。
|
||||
|
||||
**Session 所有权**: `resolve_box_session_id(query)` 只接受 Host 已确定的私有 scope 或 Query launcher/session identity，并输出 `lb-box-` + 64 位小写 SHA-256 十六进制摘要（固定 71 个 ASCII 字符）。哈希输入是 canonical JSON，包含 instance、workspace、bot、platform adapter、target type/id 与 thread；原始用户、群组、conversation 或 event id 不会出现在 Box session id 中。相同 Host scope 稳定复用，不同 target/thread/workspace/bot/adapter/instance 相互隔离；缺少可用 identity 时 fail closed。Pipeline、Agent 或 AgentRunner 配置都不能覆盖该规则。
|
||||
|
||||
**Skill 挂载合并**: `execute_tool()` 调用时，`build_skill_extra_mounts(query)` 会把当前 pipeline-bound 的所有 skill 的 `package_root` 作为 `extra_mounts` 加入 BoxSpec，挂在 `/workspace/.skills/<name>`。LLM 通过 `activate` 工具显式激活某个 skill 后，工具调用才允许引用这个 skill 的虚拟路径。
|
||||
|
||||
### 2.2 BoxRuntimeConnector (`pkg/box/connector.py`, 357 行)
|
||||
@@ -414,7 +419,9 @@ ToolManager.initialize()
|
||||
1. 验证 skill 已激活
|
||||
2. 单次 exec 只能引用一个 skill 包
|
||||
3. 若 skill 是 Python 项目（有 `requirements.txt` 或 `pyproject.toml`），命令会被 venv bootstrap 包裹（在 skill 挂载点内创建 `.venv`）
|
||||
4. 调用 `box_service.execute_tool()` → 走默认 session_id 与已组装好的 `extra_mounts`，**不再为每 skill 起独立 session**
|
||||
4. 调用 `box_service.execute_tool()` → 走 Host 从当前事件生成的 session_id 与已组装好的 `extra_mounts`，**不再为每 skill 起独立 session**
|
||||
|
||||
AgentRunner 可以直接通过 SDK/Python `AgentRunAPIProxy.call_tool` 调用这些工具，也可以让外部 harness 通过 SDK-owned scoped MCP bridge 回调。两条入口都发送 `PluginToRuntimeAction.CALL_TOOL`，共享同一个 run authorization、Host session 中保存的 execution Query、ToolManager 与 `resolve_box_session_id(query)` 规则；Runner 不能提交自定义 Box session id。Pipeline run 保存原 Query；纯 EBA run 由 Host 构造 `pipeline_config=None`、`pipeline_uuid=None` 的最小 Query。
|
||||
|
||||
### 4.3 MCP-in-Box (`mcp_stdio.py`, 354 行)
|
||||
|
||||
@@ -422,7 +429,7 @@ ToolManager.initialize()
|
||||
|
||||
```
|
||||
initialize()
|
||||
1. 复用/创建共享 session (session_id = _build_box_session_id())
|
||||
1. 复用/创建共享 session (`session_id = mcp-shared`)
|
||||
- persistent=True，长期保持
|
||||
2. workspace.execute_raw(install_cmd) 安装依赖 (可选)
|
||||
3. 将每个 MCP server 文件 stage 到 /workspace/.mcp/<process_id>/
|
||||
@@ -435,6 +442,8 @@ initialize()
|
||||
|
||||
每条 MCP server 是同一 session 中的一个 managed process，独立的 `process_id`、独立 attach URL，互不阻塞。
|
||||
|
||||
这里的 `mcp-shared` 只承载 LangBot 管理的 stdio MCP server 进程。AgentRunner 的 scoped MCP bridge 是回调 Host 工具的协议入口，不会把事件运行的 exec/read/write 改到 `mcp-shared`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 启动与生命周期
|
||||
@@ -566,22 +575,14 @@ volumes:
|
||||
| http/sse MCP server | 正常 | 正常(不依赖 Box) |
|
||||
| Skill 列表/读取 (`list_skills`/`get_skill`/`read_skill_file`) | 走 Box runtime | 走 LangBot 本地 `data/skills/` 只读 fallback |
|
||||
| Skill 创建/编辑/安装/写文件 | 走 Box runtime | **HTTP 400** + 明确错误信息(`_require_box_for_write`) |
|
||||
| Pipeline AI 配置中 `box-session-id-template` | 正常生效 | **前端 banner** 提示字段无效 |
|
||||
| Pipeline 扩展页 `enable_all_skills` / 绑定 skill | 可编辑 | **前端禁用** + banner |
|
||||
| 仪表盘 Box 状态卡片 | 绿点 / "已连接" | 灰点 / "已禁用"(disabled) 或 红点 / "已断开"(failed) |
|
||||
|
||||
> 后端拒写的边界条件:如果 `ap.box_service` **完全没装**(老式 dev mode,没经过 BuildAppStage),`_require_box_for_write` 视作 no-op,保留 `data/skills/` 本地路径——以兼容历史测试与最小化设置。生产环境总会装 `ap.box_service`,因此该 fallback 不会被触发。
|
||||
|
||||
### Pipeline 配置 (templates/metadata/pipeline/ai.yaml)
|
||||
### Session scope
|
||||
|
||||
`local-agent.config.box-session-id-template` 控制 session 作用域，预设：
|
||||
|
||||
- `{launcher_type}_{launcher_id}` — 每个会话 (推荐，默认)
|
||||
- `{launcher_type}_{launcher_id}_{sender_id}` — 群聊每个用户
|
||||
- `{launcher_type}_{launcher_id}_{conversation_id}` — 每个对话上下文
|
||||
- `{query_id}` — 每条消息（完全隔离）
|
||||
|
||||
详见 [box-session-scope.md](./box-session-scope.md)。
|
||||
Pipeline 与 AgentRunner 配置不再暴露 sandbox session 模板。Host 将当前平台会话/事件 scope 规范化后哈希成固定长度的 `lb-box-<sha256>`；相同 scope 稳定复用，不同 scope 隔离，缺少 identity 时拒绝执行。SDK/Python 与 scoped MCP bridge 的工具调用遵守同一规则。详见 [box-session-scope.md](./box-session-scope.md)。
|
||||
|
||||
### REST API
|
||||
|
||||
|
||||
+144
-365
@@ -1,402 +1,181 @@
|
||||
# Box Session Scope Design
|
||||
# Box Session Scope
|
||||
|
||||
> Date: 2026-04-18 (last reviewed 2026-06-02)
|
||||
> Status (2026-06-02): the self-hosted community edition is release-ready (box optional, clean degradation, no migration debt). Tool-call loop cap, async quota scan, and the host_path mount allowlist have landed. Remaining multi-tenant / security hardening is tracked in [box-issues.md](./box-issues.md).
|
||||
> Branch: `feat/sandbox` (LangBot + langbot-plugin-sdk)
|
||||
> Last reviewed: 2026-07-12
|
||||
> Status: implemented Host-owned, hashed execution scope; Runner/Pipeline session templates are removed.
|
||||
> Related: [Box Architecture](./box-architecture.md) | [Box vs Plugin Runtime](./box-vs-plugin-runtime.md)
|
||||
|
||||
---
|
||||
## 1. Decision
|
||||
|
||||
## 0. Implementation Status (2026-05-19)
|
||||
The LangBot Host owns the Box session used by an event run. A Pipeline, Agent,
|
||||
or AgentRunner cannot choose a global, per-user, per-conversation, or per-query
|
||||
sandbox mode.
|
||||
|
||||
This document was authored as a design proposal. The current `feat/sandbox` branch
|
||||
has shipped the design largely as written:
|
||||
`BoxService.resolve_box_session_id(query)` always returns this shape:
|
||||
|
||||
| Item | Status | Notes |
|
||||
|------|--------|-------|
|
||||
| `BoxMountSpec` + `BoxSpec.extra_mounts` | ✅ Shipped | SDK `box/models.py` |
|
||||
| Docker / nsjail / E2B backends apply extra mounts | ✅ Shipped | Last gap closed by SDK commit `0fea9b1` (E2B) |
|
||||
| `box-session-id-template` in `local-agent` pipeline config | ✅ Shipped | `templates/metadata/pipeline/ai.yaml`, default `{launcher_type}_{launcher_id}` |
|
||||
| `BoxService.resolve_box_session_id(query)` | ✅ Shipped | `pkg/box/service.py:166` |
|
||||
| `BoxService.build_skill_extra_mounts(query)` | ✅ Shipped | `pkg/box/service.py:189` |
|
||||
| Skill exec uses unified container + extra mounts | ✅ Shipped | `pkg/provider/tools/loaders/native.py` skill branch |
|
||||
| MCP-in-Box uses shared persistent session, multi-process | ✅ Shipped (earlier than originally scoped) | SDK commit `529088e`, LangBot `mcp_stdio.py:_build_box_session_id` |
|
||||
| `BoxManagedProcessSpec.process_id` + multi-process per session | ✅ Shipped | `BoxRuntime` keeps `managed_processes: dict[pid, _ManagedProcess]` |
|
||||
| Per-tenant / quota integration with templates | ❌ Not started | See [box-tob-analysis.md](./box-tob-analysis.md) |
|
||||
|
||||
The "Phase 2 deferred" note in §10 is **out of date** — MCP unification went in on
|
||||
the same line. Pipeline-scoped (not user-scoped) MCP container is the realized
|
||||
behavior: each pipeline's MCP servers share one `mcp-<pipeline>` session, and
|
||||
user exec sessions use the template-derived id.
|
||||
|
||||
The remaining open work is multi-tenant overlays (tenant_id in session_id,
|
||||
quota counters keyed by tenant), tracked in the toB analysis doc rather than here.
|
||||
|
||||
---
|
||||
|
||||
## 1. Problems
|
||||
|
||||
### 1.1 Default exec: per-message containers
|
||||
|
||||
Currently, `BoxService.execute_tool()` sets `session_id = str(query.query_id)` — an
|
||||
auto-incrementing integer per incoming message. Every user message creates a new sandbox
|
||||
container. Dependencies installed and in-container state are lost between messages.
|
||||
|
||||
### 1.2 Three isolated container pools
|
||||
|
||||
Default exec, skills, and MCP servers each manage their own containers with
|
||||
independent session IDs:
|
||||
|
||||
| Path | Session ID | Container |
|
||||
|--------------|-----------------------------------------------|-------------|
|
||||
| Default exec | `str(query_id)` (per message) | Ephemeral |
|
||||
| Skill exec | `skill-{launcher}_{id}-{skill_name}` | Per skill |
|
||||
| MCP stdio | `mcp-{server_uuid}` | Per server |
|
||||
|
||||
This means a single logical user interaction can spawn 3+ containers that cannot
|
||||
share state, see each other's files, or reuse installed dependencies.
|
||||
|
||||
### 1.3 Single bind mount limitation
|
||||
|
||||
`BoxSpec` currently supports only **one** `host_path` → `mount_path` bind mount.
|
||||
This prevents mounting both a default workspace and skill directories into the
|
||||
same container.
|
||||
|
||||
---
|
||||
|
||||
## 2. Concept Model
|
||||
|
||||
```
|
||||
Platform Message
|
||||
→ Query (query_id: int, auto-increment, per message)
|
||||
→ Session (launcher_type + launcher_id, per chat window)
|
||||
→ Conversation (uuid, per dialogue context within a Session)
|
||||
```text
|
||||
lb-box-<64 lowercase SHA-256 hex characters>
|
||||
```
|
||||
|
||||
| Concept | Key | Example | Scope |
|
||||
|---------------|-------------------------------------|----------------------------|------------------------------|
|
||||
| Query | `query_id` | `42` | Single message |
|
||||
| Session | `launcher_type` + `launcher_id` | `group_123456` | Chat window (group or PM) |
|
||||
| Conversation | `conversation_id` (UUID) | `a1b2c3d4-...` | Dialogue context within a Session |
|
||||
| Sender | `sender_id` | `789` | Individual user |
|
||||
The result is exactly 71 ASCII characters. Raw platform, user, group,
|
||||
conversation, thread, and event identifiers never appear in the Box session
|
||||
id. This avoids unsafe path characters, unbounded identifier length, and
|
||||
identity leakage through runtime/container metadata.
|
||||
|
||||
Note: in a **group chat**, all users share the same Session (keyed by `group_id`). The
|
||||
individual sender is tracked as `sender_id` but does not affect Session/Conversation routing.
|
||||
This rule replaces all former concepts of:
|
||||
|
||||
---
|
||||
- Pipeline or Runner `box-session-id-template` fields;
|
||||
- a global forced session template;
|
||||
- API fields that let a caller supply sandbox scope;
|
||||
- LocalAgent-specific Host injection of Box availability, scope, or Pipeline id.
|
||||
|
||||
## 3. Target Scenarios
|
||||
## 2. Canonical Host scope
|
||||
|
||||
| # | Scenario | Box Granularity | Desired `session_id` |
|
||||
|----|--------------------------------|------------------------------------------|---------------------------------------------------------|
|
||||
| 1 | Personal assistant | 1 Box per user, long-lived | `{launcher_type}_{launcher_id}` |
|
||||
| 2 | Customer service | 1 Box per customer, cross-pipeline | `{launcher_type}_{launcher_id}` |
|
||||
| 3 | Internal employee tool | 1 Box per employee | `{launcher_type}_{launcher_id}` |
|
||||
| 4 | Group chat shared assistant | 1 Box per group | `{launcher_type}_{launcher_id}` |
|
||||
| 5 | Group chat isolated per user | 1 Box per user within a group | `{launcher_type}_{launcher_id}_{sender_id}` |
|
||||
| 6 | Teaching (cross-channel) | 1 Box per student across groups/PMs | `{sender_id}` |
|
||||
| 7 | One-off execution | 1 Box per message (current behavior) | `{query_id}` |
|
||||
| 8 | Multi-project development | 1 Box per conversation context | `{launcher_type}_{launcher_id}_{conversation_id}` |
|
||||
Before hashing, the Host creates a canonical, sorted JSON scope with these
|
||||
dimensions:
|
||||
|
||||
No single fixed granularity covers all scenarios. A template-based approach is needed.
|
||||
| Dimension | Purpose |
|
||||
| --- | --- |
|
||||
| `instance_id` | Isolate separate LangBot installations |
|
||||
| `workspace_id` | Preserve workspace/tenant boundary when available |
|
||||
| `bot_id` | Prevent two bots from sharing a sandbox accidentally |
|
||||
| `platform_adapter` | Separate identical target ids from different adapters |
|
||||
| `target_type` / `target_id` | Identify the platform session or event target |
|
||||
| `thread_id` | Isolate threads within a target when available |
|
||||
|
||||
---
|
||||
The canonical JSON is domain-separated and hashed by the Host. Runner input,
|
||||
runner config, and tool parameters are not trusted sources for this scope.
|
||||
|
||||
## 4. Design Overview
|
||||
### 2.1 Target identity priority
|
||||
|
||||
Two key changes:
|
||||
The Host resolves `target_type` / `target_id` in this order:
|
||||
|
||||
1. **Unified container**: exec, skills, and MCP all share the same container per
|
||||
session scope. No more separate container pools.
|
||||
2. **Configurable session scope**: `session_id` is generated from a template with
|
||||
pipeline variables, configurable per pipeline.
|
||||
1. For a Pipeline-backed run, use the exact Query launcher tuple.
|
||||
2. For a pure EBA run, use `delivery.reply_target.target_type/target_id`
|
||||
(`launcher_type/launcher_id` aliases are accepted).
|
||||
3. If there is no delivery target, use `conversation_id`.
|
||||
4. For a non-message event without a conversation, use `event_id`, producing
|
||||
an event-scoped sandbox.
|
||||
|
||||
### 4.1 Unified Container with Multiple Mounts
|
||||
The adapter class or declared adapter capability supplies platform adapter
|
||||
identity. The Host includes the active LangBot instance, workspace, bot, and
|
||||
thread dimensions when they exist.
|
||||
|
||||
A single container per session scope is created on first use. It has:
|
||||
### 2.2 Stability and isolation
|
||||
|
||||
- **Primary mount**: default workspace at `/workspace` (from `default_host_workspace`)
|
||||
- **Skill mounts**: each pipeline-bound skill's `package_root` mounted at
|
||||
`/workspace/.skills/{skill_name}/`
|
||||
- **MCP servers**: run as managed processes inside the same container
|
||||
The same normalized scope always produces the same hash, so repeated runs in
|
||||
the same platform conversation reuse the same Box workspace. A rotating
|
||||
transcript/conversation id does not change the scope when an explicit platform
|
||||
reply target remains the same.
|
||||
|
||||
```
|
||||
Container (session_id = "group_123456")
|
||||
/workspace/ ← default workspace (bind mount, rw)
|
||||
/workspace/.skills/web-search/ ← skill package (bind mount, rw)
|
||||
/workspace/.skills/data-analysis/ ← skill package (bind mount, rw)
|
||||
[managed process: mcp-server-a] ← MCP server running inside
|
||||
[managed process: mcp-server-b] ← MCP server running inside
|
||||
A different target, thread, workspace, bot, platform adapter, or LangBot
|
||||
instance changes the hash. If delivery target is unavailable and
|
||||
`conversation_id` is the fallback, different conversations also produce
|
||||
different hashes. Event-scoped fallback isolates unrelated non-message events.
|
||||
|
||||
### 2.3 Fail closed
|
||||
|
||||
If the private Host scope marker is present but empty or malformed, Box rejects
|
||||
execution with `BoxValidationError`. A direct Query without either a valid
|
||||
Host scope or launcher/session identity is also rejected. There is no
|
||||
`unknown`, raw query id, global, or caller-selected fallback.
|
||||
|
||||
## 3. Host execution Query
|
||||
|
||||
AgentRunner callbacks need a Host-owned Query view because model/tool loaders
|
||||
already consume that type. The Query is internal and is never exposed as a
|
||||
Runner-controlled object.
|
||||
|
||||
- A Pipeline run stores the exact current Query in `AgentRunSession`.
|
||||
- A pure EBA run builds a minimal Query with a valid Session and
|
||||
`pipeline_config=None`, `pipeline_uuid=None`.
|
||||
- The Host attaches canonical `_host_box_scope` and the authorized skill names
|
||||
in `_pipeline_bound_skills`.
|
||||
- `PluginToRuntimeAction.CALL_TOOL` restores this Query from the active
|
||||
`run_id` before dispatching to `ToolManager`.
|
||||
|
||||
This gives Pipeline and pure EBA execution the same Host tool path without
|
||||
inventing a fake Pipeline for an independent Agent.
|
||||
|
||||
## 4. AgentRunner callback paths
|
||||
|
||||
AgentRunner implementations may use either callback transport:
|
||||
|
||||
1. SDK/Python runners call `AgentRunAPIProxy.call_tool`.
|
||||
2. External harnesses call the SDK-owned scoped MCP bridge.
|
||||
|
||||
Both transports emit the same `PluginToRuntimeAction.CALL_TOOL`. The Host then
|
||||
validates the same run authorization, restores the same execution Query, and
|
||||
dispatches to the same ToolManager and BoxService.
|
||||
|
||||
```text
|
||||
AgentRunner
|
||||
+-- AgentRunAPIProxy.call_tool --------+
|
||||
| |
|
||||
+-- SDK-owned scoped MCP bridge -------+--> PluginToRuntimeAction.CALL_TOOL
|
||||
--> run authorization
|
||||
--> execution Query
|
||||
--> ToolManager
|
||||
--> BoxService
|
||||
--> lb-box-<sha256>
|
||||
```
|
||||
|
||||
This requires extending `BoxSpec` to support multiple mounts (see §5).
|
||||
An AgentRunner is not required to use MCP. Local Python runners can use the SDK
|
||||
directly; code-agent harnesses can use the bridge. The transports do not define
|
||||
different authorization or sandbox semantics.
|
||||
|
||||
### 4.2 Session ID Template
|
||||
## 5. Skills and mounts
|
||||
|
||||
A new field `box-session-id-template` in the `local-agent` pipeline runner config
|
||||
controls the session scope:
|
||||
Native exec and skill-backed exec for one Host scope use the same hashed
|
||||
session. `BoxService.build_skill_extra_mounts(query)` adds visible, authorized
|
||||
skill packages under `/workspace/.skills/<name>` when the session is created.
|
||||
|
||||
```yaml
|
||||
# templates/metadata/pipeline/ai.yaml (under local-agent.config)
|
||||
- name: box-session-id-template
|
||||
label:
|
||||
en_US: Sandbox Scope
|
||||
zh_Hans: 沙箱作用域
|
||||
description:
|
||||
en_US: >-
|
||||
Determines how sandbox environments are shared. Use variables to
|
||||
control isolation granularity.
|
||||
zh_Hans: >-
|
||||
决定沙箱环境的共享方式。使用变量控制隔离粒度。
|
||||
type: select
|
||||
required: false
|
||||
default: "{launcher_type}_{launcher_id}"
|
||||
options:
|
||||
- value: "{launcher_type}_{launcher_id}"
|
||||
label:
|
||||
en_US: Per chat (Recommended)
|
||||
zh_Hans: 每个会话（推荐）
|
||||
- value: "{launcher_type}_{launcher_id}_{sender_id}"
|
||||
label:
|
||||
en_US: Per user in chat
|
||||
zh_Hans: 会话中每个用户
|
||||
- value: "{launcher_type}_{launcher_id}_{conversation_id}"
|
||||
label:
|
||||
en_US: Per conversation context
|
||||
zh_Hans: 每个对话上下文
|
||||
- value: "{query_id}"
|
||||
label:
|
||||
en_US: Per message (isolated)
|
||||
zh_Hans: 每条消息（完全隔离）
|
||||
```
|
||||
Skill activation controls which skill-backed tools and paths are available. It
|
||||
does not create a different session and does not grant the Runner authority to
|
||||
change the session id.
|
||||
|
||||
Available template variables (populated by PreProcessor in `query.variables`):
|
||||
## 6. `mcp-shared` is a different session
|
||||
|
||||
| Variable | Source | Example |
|
||||
|---------------------|---------------------------------|----------------------|
|
||||
| `{launcher_type}` | `query.session.launcher_type` | `person` / `group` |
|
||||
| `{launcher_id}` | `query.session.launcher_id` | `123456` |
|
||||
| `{sender_id}` | `query.sender_id` | `789` |
|
||||
| `{conversation_id}` | `conversation.uuid` | `a1b2c3d4-...` |
|
||||
| `{query_id}` | `query.query_id` | `42` |
|
||||
LangBot can host configured stdio MCP servers as managed processes inside Box.
|
||||
Those long-lived infrastructure processes share the dedicated `mcp-shared`
|
||||
session and are isolated from one another by `process_id`.
|
||||
|
||||
Default `{launcher_type}_{launcher_id}` covers scenarios 1–4 out of the box.
|
||||
This is separate from the scoped MCP bridge above:
|
||||
|
||||
---
|
||||
| Path | Purpose | Session rule |
|
||||
| --- | --- | --- |
|
||||
| AgentRunner scoped MCP bridge | Call authorized Host tools for one active run | Host-owned `lb-box-<sha256>` from the run execution Query |
|
||||
| MCP-in-Box stdio server | Keep configured MCP server processes running | Dedicated persistent `mcp-shared` session |
|
||||
|
||||
## 5. SDK Changes: Multi-Mount BoxSpec
|
||||
Calling a sandbox tool through the AgentRunner bridge never redirects the run
|
||||
workspace into `mcp-shared`. Conversely, an MCP server's managed-process
|
||||
lifecycle does not inherit the current event scope.
|
||||
|
||||
### 5.1 Model Extension
|
||||
## 7. Configuration and compatibility
|
||||
|
||||
```python
|
||||
# box/models.py
|
||||
There is no Box session scope field in Pipeline metadata, AgentRunner config,
|
||||
or the public Pipeline/Runner API. Operators configure the Box subsystem itself
|
||||
(`box.enabled`, backend/runtime settings, profiles, mount allowlists, quotas,
|
||||
and workspace roots), not per-Runner session templates.
|
||||
|
||||
class BoxMountSpec(pydantic.BaseModel):
|
||||
"""A single bind mount specification."""
|
||||
host_path: str
|
||||
mount_path: str
|
||||
mode: BoxHostMountMode = BoxHostMountMode.READ_WRITE
|
||||
Old configuration containing `box-session-id-template` is unsupported in the
|
||||
4.x contract. LangBot 4.x does not migrate LangBot 3.x configuration or
|
||||
databases, so the removed field is not read as a compatibility fallback.
|
||||
|
||||
class BoxSpec(pydantic.BaseModel):
|
||||
# ... existing fields ...
|
||||
host_path: str | None = None # Primary mount (backward compat)
|
||||
host_path_mode: BoxHostMountMode = BoxHostMountMode.READ_WRITE
|
||||
mount_path: str = DEFAULT_BOX_MOUNT_PATH
|
||||
extra_mounts: list[BoxMountSpec] = [] # NEW: additional mounts
|
||||
```
|
||||
## 8. Regression coverage
|
||||
|
||||
`extra_mounts` is additive — the existing `host_path` / `mount_path` pair remains
|
||||
the primary mount for backward compatibility.
|
||||
Release tests should prove:
|
||||
|
||||
### 5.2 Backend: Apply Extra Mounts
|
||||
|
||||
```python
|
||||
# box/backend.py — CLISandboxBackend.start_session()
|
||||
|
||||
# Primary mount (unchanged)
|
||||
if spec.host_path is not None and spec.host_path_mode != BoxHostMountMode.NONE:
|
||||
args.extend(['-v', f'{spec.host_path}:{spec.mount_path}:{spec.host_path_mode.value}'])
|
||||
|
||||
# Extra mounts (NEW)
|
||||
for mount in spec.extra_mounts:
|
||||
if mount.mode != BoxHostMountMode.NONE:
|
||||
args.extend(['-v', f'{mount.host_path}:{mount.mount_path}:{mount.mode.value}'])
|
||||
```
|
||||
|
||||
Same pattern for nsjail backend.
|
||||
|
||||
---
|
||||
|
||||
## 6. LangBot Changes
|
||||
|
||||
### 6.1 Session ID Resolution
|
||||
|
||||
In `BoxService.execute_tool()`:
|
||||
|
||||
```python
|
||||
# Before:
|
||||
spec_payload.setdefault('session_id', str(query.query_id))
|
||||
|
||||
# After:
|
||||
template = (query.pipeline_config or {}).get('ai', {}) \
|
||||
.get('local-agent', {}).get('box-session-id-template',
|
||||
'{launcher_type}_{launcher_id}')
|
||||
variables = query.variables or {}
|
||||
session_id = template.format_map(collections.defaultdict(
|
||||
lambda: 'unknown', variables
|
||||
))
|
||||
spec_payload.setdefault('session_id', session_id)
|
||||
```
|
||||
|
||||
### 6.2 Skill Exec: Use Same Container
|
||||
|
||||
Currently `native.py:_invoke_exec` creates a separate `BoxWorkspaceSession` per
|
||||
skill with `host_path=package_root`. Instead:
|
||||
|
||||
1. Use the **same session_id** as default exec (from the template).
|
||||
2. Pass the skill's `package_root` as an **extra mount** at
|
||||
`/workspace/.skills/{skill_name}/` instead of replacing `/workspace`.
|
||||
3. The container already has the default workspace at `/workspace`.
|
||||
|
||||
```python
|
||||
# native.py — _invoke_exec, skill branch (REVISED)
|
||||
|
||||
# Same session_id as default exec
|
||||
session_id = resolve_box_session_id(query)
|
||||
|
||||
spec_payload = {
|
||||
'cmd': rewritten_command,
|
||||
'workdir': rewritten_workdir,
|
||||
'session_id': session_id,
|
||||
'extra_mounts': [{
|
||||
'host_path': package_root,
|
||||
'mount_path': f'/workspace/.skills/{selected_skill_name}',
|
||||
'mode': 'rw',
|
||||
}],
|
||||
}
|
||||
result = await self.ap.box_service.execute_spec_payload(spec_payload, query)
|
||||
```
|
||||
|
||||
The virtual path `/workspace/.skills/{name}` no longer needs rewriting at the
|
||||
command level — it maps directly to the bind mount path inside the container.
|
||||
|
||||
### 6.3 MCP: Use Same Container
|
||||
|
||||
MCP servers should run inside the same container as exec and skills. Changes:
|
||||
|
||||
1. `BoxStdioSessionRuntime` uses the pipeline's session_id template instead of
|
||||
`mcp-{server_uuid}`.
|
||||
2. MCP server's working directory is a subdirectory (e.g. `/workspace/.mcp/{name}/`).
|
||||
3. MCP server's dependencies are mounted or installed into that subdirectory.
|
||||
4. The MCP server runs as a managed process inside the shared container.
|
||||
|
||||
Since MCP servers start at LangBot boot (not per-query), the session must be
|
||||
created eagerly. The container will be kept alive by the managed process
|
||||
exemption in TTL reaping (`runtime.py:259`).
|
||||
|
||||
**Note**: MCP sessions are pipeline-scoped (not per-launcher), so their session_id
|
||||
should be a **fixed identifier per pipeline** rather than the user-facing template.
|
||||
This means one shared MCP container per pipeline, with user exec sessions separate.
|
||||
|
||||
Alternatively, in a future iteration, MCP managed processes could be launched
|
||||
lazily into the user's container on first MCP tool call. This is more complex
|
||||
but maximizes sharing. For V1, keeping MCP containers at pipeline scope is
|
||||
simpler and more predictable.
|
||||
|
||||
---
|
||||
|
||||
## 7. Mount Layout Summary
|
||||
|
||||
### Default exec (no skills activated)
|
||||
|
||||
```
|
||||
Container (session_id from template)
|
||||
/workspace/ ← default_host_workspace (rw)
|
||||
```
|
||||
|
||||
### Exec with activated skills
|
||||
|
||||
```
|
||||
Container (same session_id)
|
||||
/workspace/ ← default_host_workspace (rw)
|
||||
/workspace/.skills/web-search/ ← skill package_root (rw)
|
||||
/workspace/.skills/data-analysis/ ← skill package_root (rw)
|
||||
```
|
||||
|
||||
Extra mounts are **additive** — they are added when the container is first
|
||||
created (or on the first exec that references a skill). Since Docker bind
|
||||
mounts are specified at container creation time, skills must be known at
|
||||
creation time.
|
||||
|
||||
**Resolution**: When creating a container, inject `extra_mounts` for **all
|
||||
pipeline-bound skills** (from `extensions_preferences`), not just the
|
||||
currently activated one. This way any skill can be activated later without
|
||||
recreating the container.
|
||||
|
||||
### MCP servers (V1: pipeline-scoped)
|
||||
|
||||
```
|
||||
Container (session_id = "mcp-pipeline-{pipeline_uuid}")
|
||||
/workspace/ ← MCP shared workspace
|
||||
/workspace/.mcp/server-a/ ← MCP server A files
|
||||
/workspace/.mcp/server-b/ ← MCP server B files
|
||||
[managed process: server-a]
|
||||
[managed process: server-b]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Data Migration
|
||||
|
||||
Existing pipelines do not have `box-session-id-template`. The backend uses
|
||||
`.get(..., default)` so missing keys fall back to `{launcher_type}_{launcher_id}`.
|
||||
This changes behavior from per-message to per-launcher for existing pipelines.
|
||||
|
||||
Recommendation: **accept the behavior change** — per-launcher is the more
|
||||
intuitive default, and the old per-message behavior was rarely desired.
|
||||
|
||||
---
|
||||
|
||||
## 9. Cloud Quota Implications
|
||||
|
||||
| Scope | Typical concurrent containers |
|
||||
|-----------------------------------------------|-------------------------------|
|
||||
| `{query_id}` (per message) | Many, short-lived |
|
||||
| `{launcher_type}_{launcher_id}` (per chat) | = active chat count |
|
||||
| `{sender_id}` (per user) | = active user count |
|
||||
| `{conversation_id}` (per conversation) | Between per-chat and per-msg |
|
||||
|
||||
With the unified container model, each scope value maps to exactly **one**
|
||||
container (instead of potentially 3+ per-message). This significantly reduces
|
||||
resource usage.
|
||||
|
||||
Quota enforcement point: `BoxRuntime._get_or_create_session()` in the SDK.
|
||||
|
||||
---
|
||||
|
||||
## 10. Implementation Phases
|
||||
|
||||
### Phase 1: Session scope + skill unification (this PR)
|
||||
|
||||
1. **SDK**: Extend `BoxSpec` with `extra_mounts: list[BoxMountSpec]`.
|
||||
2. **SDK**: Update Docker/nsjail backends to apply extra mounts.
|
||||
3. **LangBot**: Add `box-session-id-template` to `local-agent` YAML metadata
|
||||
and default pipeline config JSON.
|
||||
4. **LangBot**: Update `BoxService.execute_tool()` to use template interpolation.
|
||||
5. **LangBot**: Update `native.py:_invoke_exec` skill branch to use same
|
||||
session_id + extra mounts instead of separate `BoxWorkspaceSession`.
|
||||
6. **LangBot**: On container creation, inject extra mounts for all
|
||||
pipeline-bound skills.
|
||||
7. **Frontend**: No code change — `DynamicFormComponent` renders `select` fields.
|
||||
8. **Tests**: Unit tests for template interpolation and multi-mount specs.
|
||||
|
||||
### Phase 2: MCP unification (future)
|
||||
|
||||
1. Refactor `BoxStdioSessionRuntime` to use pipeline-scoped shared container.
|
||||
2. MCP servers become managed processes in the shared container.
|
||||
3. Support multiple concurrent managed processes per container.
|
||||
|
||||
MCP unification is deferred because it requires changes to the managed process
|
||||
model (currently 1 managed process per session) and has startup ordering
|
||||
concerns (MCP servers start at boot, before any user query determines
|
||||
a session_id).
|
||||
- every event-run session id matches `lb-box-[0-9a-f]{64}` and contains no raw
|
||||
identity;
|
||||
- the same canonical Host scope is stable while different targets,
|
||||
conversations, threads, bots, adapters, workspaces, or instances are
|
||||
isolated;
|
||||
- Pipeline and pure EBA runs representing the same platform session produce
|
||||
the same canonical scope;
|
||||
- missing Host/Query identity fails closed;
|
||||
- SDK/Python `call_tool` and the scoped MCP bridge both enter
|
||||
`PluginToRuntimeAction.CALL_TOOL` and restore the run execution Query;
|
||||
- Runner payload/config cannot override the session id;
|
||||
- stdio MCP processes remain in `mcp-shared` and are isolated by process id;
|
||||
- authorized skills are mounted into the hashed run session without creating
|
||||
per-skill sessions.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Box 系统测试覆盖分析
|
||||
|
||||
> 更新日期: 2026-06-02
|
||||
> 更新日期: 2026-07-12
|
||||
> 状态更新: 自部署社区版已具备发布条件（box 可选、降级完善、无迁移欠债）；工具调用循环上限、配额遍历异步化、`host_path` 挂载白名单等已落地。剩余多租户 / 安全硬化项见 [SaaS 阻塞项清单](./box-issues.md)。
|
||||
> 分支: `feat/sandbox` (LangBot + langbot-plugin-sdk)
|
||||
|
||||
@@ -15,13 +15,14 @@
|
||||
| `tests/unit_tests/box/test_box_connector.py` | 106 | 是 | Connector 传输决策、WS relay URL、dispose、心跳/重连 |
|
||||
| `tests/unit_tests/box/test_box_service.py` | 1224 | 是 | Service 核心逻辑（最全面） |
|
||||
| `tests/unit_tests/box/test_workspace.py` | 147 | 是 | WorkspaceSession 路径重写、payload 构建 |
|
||||
| `tests/unit_tests/agent/test_execution_context.py` | 144 | 是 | Pipeline/纯 EBA execution Query、canonical Host scope、adapter/instance 隔离 |
|
||||
| `tests/unit_tests/plugin/test_handler_actions.py` | 1071 | 是 | AgentRun CALL_TOOL 恢复 execution Query、纯 EBA native exec |
|
||||
| `tests/unit_tests/provider/test_mcp_box_integration.py` | 707 | 是 | MCP Box 配置、路径重写、payload、shared-session/multi-process、runtime info |
|
||||
| `tests/unit_tests/provider/test_localagent_sandbox_exec.py` | 444 | 是 | LocalAgent exec 流程、流式、Skill 激活 (Tool Call) |
|
||||
| `tests/unit_tests/provider/test_tool_manager_native.py` | 249 | 是 | ToolManager 路由、native tool CRUD、路径穿越、6 工具暴露 |
|
||||
| `tests/unit_tests/provider/test_skill_tools.py` | 582 | 是 | Skill 管理、Tool Call 激活、路径、authoring CRUD |
|
||||
| `tests/unit_tests/test_skill_service.py` | 396 | 是 | HTTP service：skill CRUD、zip/GitHub install、文件浏览 |
|
||||
| `tests/unit_tests/test_paths.py` | 23 | 是 | paths 工具 |
|
||||
| `tests/unit_tests/test_preproc.py` | 134 | 是 | PreProcessor 注入 session 变量、bound skill 解析 |
|
||||
| `tests/unit_tests/test_preproc.py` | 134 | 是 | PreProcessor 的模型、历史与 bound skill 解析 |
|
||||
| `tests/unit_tests/pipeline/test_chat_handler_logging.py` | 78 | 是 | Chat handler 日志相关回归 |
|
||||
| `tests/integration_tests/box/test_box_integration.py` | 329 | **否** | 真实容器执行、超时、网络隔离 |
|
||||
| `tests/integration_tests/box/test_box_mcp_integration.py` | 368 | **否** | Managed process、WS attach、shared-session 清理 |
|
||||
@@ -35,7 +36,7 @@
|
||||
| `tests/box/test_e2b_backend.py` | 482 | 是 | E2B SDK mock、session 生命周期、extra_mounts 同步 |
|
||||
| `tests/box/test_skill_store.py` | 88 | 是 | zip preview/install、基础 file CRUD |
|
||||
|
||||
**总计**: 17 个测试文件, ~6,500 行测试代码; 其中 2 个集成测试（约 700 行）在 CI 中不运行。
|
||||
**说明**: 本表按当前主链列出 Box 相关测试；其中 2 个真实容器集成测试默认不在 CI 中运行。
|
||||
|
||||
> 较 2026-04-16 版增加：`test_skill_service.py`、`test_paths.py`、`test_preproc.py`、`test_chat_handler_logging.py` (LangBot)，`test_backend_selection.py`、`test_e2b_backend.py`、`test_skill_store.py` (SDK)。`test_nsjail_backend.py` 增加 CLI 兼容性 case (commit `feed530`)。
|
||||
|
||||
@@ -51,7 +52,7 @@
|
||||
| BoxService workspace quota | 优秀 | 前置/后置配额检查、超额清理 |
|
||||
| BoxService 输出截断 | 优秀 | 短/精确边界/长输出、独立 stderr |
|
||||
| BoxService 可观测性 | 优秀 | 状态报告、error ring buffer、buffer 上限 |
|
||||
| BoxService session 模板 | 良好 | `resolve_box_session_id` + `build_skill_extra_mounts` 在 service / native / mcp 三处都有覆盖 |
|
||||
| BoxService Host-owned session | 优秀 | 覆盖 `lb-box-<sha256>` 固定格式、原始 identity 不泄露、同 scope 稳定、不同 conversation/scope 隔离、缺 identity fail closed |
|
||||
| RPC client/server 协议 | 优秀 | execute/get_sessions/delete/create/conflict error |
|
||||
| BoxRuntimeConnector | 良好 | local/remote 模式、Docker 平台、relay URL、心跳与重连回调 |
|
||||
| BoxWorkspaceSession | 良好 | payload 构建、managed process 路径重写、stage host file |
|
||||
@@ -61,7 +62,7 @@
|
||||
| Backend selection | 良好 | 显式 backend 优先级、local 探测顺序、配置变更触发 reselect |
|
||||
| MCP Box 集成 | 良好 | config model、路径重写、payload、shared-session 多 process |
|
||||
| Native tool loader | 良好 | 6 工具（exec/read/write/edit/glob/grep）、路径穿越拦截 |
|
||||
| LocalAgent exec 流程 | 良好 | 完整 tool call 循环、流式、system prompt 注入、Tool Call 激活 |
|
||||
| AgentRunner 工具入口 | 良好 | SDK proxy 与 MCP bridge 都映射到 `PluginToRuntimeAction.CALL_TOOL`；Host action 测试覆盖 run-scoped execution Query 与纯 EBA native exec |
|
||||
| Skill 系统 | 良好 | 加载、Tool Call 激活、marker、路径解析、authoring CRUD、HTTP service |
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user