feat(agent-runner): align protocol adapter terminology

2026-06-02 12:05:54 +00:00 · 2026-05-24 09:13:15 +08:00
parent ea6c8fba57
commit 90dffa7cd8
26 changed files with 471 additions and 342 deletions
--- a/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
+++ b/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
@@ -2,6 +2,20 @@

 本文档描述插件化 AgentRunner 场景下的上下文边界。结论先行：LangBot 不应成为最终 agentic context manager；LangBot 应提供 context substrate，AgentRunner 或其背后的 agent runtime 自己决定如何管理历史、压缩、召回和 KV cache。

+## 当前状态
+
+**当前分支已落地**：
+
+- ✅ `AgentRunContext` — event-first context 模型
+- ✅ `ContextAccess` — cursor、inline policy、available APIs
+- ✅ `AgentRunAPIProxy.history` — page/search API
+- ✅ `AgentRunAPIProxy.events` — get/page API
+- ✅ `AgentRunAPIProxy.artifacts` — metadata/read_range API
+- ✅ `AgentRunAPIProxy.state` — get/set/delete API
+- ✅ EventLog / Transcript / ArtifactStore — host 事实源
+- ✅ PersistentStateStore — 持久化状态存储
+- ✅ `max-round` 已从协议实体中移除，只在 Pipeline adapter 中处理
+
 ## 1. 设计原则

 ### 1.1 Agent 拥有上下文策略
@@ -21,7 +35,7 @@

 ### 1.2 不再把 `max-round` 作为目标设计

-旧 `max-round` 是 Pipeline local-agent 时代的兼容配置。它可以在迁移期被读取并转换为某种默认 bootstrap policy，但不应继续作为 AgentRunner 协议的核心概念。
+Pipeline adapter 的 `max-round` 配置可以在运行时被读取并转换为某种默认 bootstrap policy，但不应继续作为 AgentRunner 协议的核心概念。

 新协议不应该问“LangBot 每轮裁几轮历史给 agent”，而应该问：

@@ -112,7 +126,7 @@ context:

 - 自管 runtime：`bootstrap: current_event`
 - 简单 HTTP runner：`bootstrap: recent_tail`
- 兼容旧 local-agent：迁移期可以把旧 `max-round` 映射为 `recent_tail` 的配置，但不再作为协议字段扩展。
+- Pipeline adapter 的 `max-round` 可映射为 `recent_tail` 配置，但不再作为协议字段扩展。

 ## 3. ContextAccess

@@ -296,13 +310,13 @@ LangBot core 不应内置官方 agent 的业务流程：

 ## 9. 当前实现需要调整

-当前代码已有 `AgentContextPackager`，它按 legacy `max-round` 裁剪 `query.messages`。目标方向不是继续增强它，而是把它降级为兼容 adapter：
+**已完成（当前分支）**：

- `max-round` 迁移为旧 binding 的 bootstrap 配置。
- 新 runner 默认不收到历史窗口。
- `AgentRunContext` 增加 `context` / cursor / access capabilities。
- `AgentRunAPIProxy` 增加 history / events / artifacts API。
- Host 增加持久 EventLog / Transcript / ArtifactStore。
- local-agent 插件再基于这些 API 决定是否拉历史、怎么压缩、怎么组 prompt。
+- ✅ `max-round` 在 Pipeline adapter 中处理（不影响协议实体）
+- ✅ 新 runner 默认不收到历史窗口
+- ✅ `AgentRunContext` 增加 `context` / cursor / access capabilities
+- ✅ `AgentRunAPIProxy` 增加 history / events / artifacts / state API
+- ✅ Host 增加持久 EventLog / Transcript / ArtifactStore / PersistentStateStore
+- ✅ `run_from_query()` 委托到 event-first `run(event, binding)`

 这样 LangBot 既能服务依附 host 基础设施的官方 runner，也能服务自带 memory/session/cache 的外部 agent runtime。
--- a/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md
+++ b/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md
@@ -1,5 +1,10 @@
 # Event Based Agent 预留设计

+> **注意**：本文档是 future design note，不是当前分支实现范围。
+>
+> EventGateway、EventRouter、Event subscription/notification 由其他分支实现。
+> 本分支只预留 event-first 入口和 envelope/binding models。
+
 本文档描述未来 EBA 接入时，事件如何进入 LangBot、如何触发 AgentRunner，以及如何复用插件化 agent 基础设施。

 本阶段不实现完整 EventBus / EventRouter / Platform API。本阶段要做的是把协议边界设计对，避免当前消息入口继续绑死 Pipeline 和用户文本消息。
@@ -188,22 +193,36 @@ EBA 事件进入 AgentRunner 时仍使用 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CO

 ## 10. 当前实现与目标差距

-当前已有：
+**当前分支已落地（Event-first 基础设施）**：

- `AgentRunOrchestrator`
- `AgentRunContextBuilder`
- `AgentRunResult` 基础消息流
- `ctx.event` 的最小消息事件封装
+- ✅ `AgentRunOrchestrator` — event-first `run(event, binding)` 入口
+- ✅ `AgentRunContextBuilder` — event-first context 构建
+- ✅ `AgentEventEnvelope` 模型
+- ✅ `AgentBinding` 模型
+- ✅ `AgentRunResult` 基础消息流
+- ✅ `ctx.event` 的最小消息事件封装
+- ✅ `PipelineAdapter` — Query → Event + Binding 转换
+- ✅ `run_from_query()` → `run(event, binding)` 委托
+- ✅ EventLog / Transcript / ArtifactStore
+- ✅ History / Event / Artifact / State pull APIs

-仍需要：
+**其他分支负责（非本分支范围）**：

- `AgentEventEnvelope` 独立模型。
- EventLog 持久化。
- AgentBinding 持久模型。
- EventRouter。
- DeliveryContext。
- platform action permission model。
- `run_from_query()` 到 `run(event, binding)` 的迁移。
+- EventGateway 实现
+- EventRouter 实现
+- Event subscription / notification
+- EventLog 持久化管理 UI
+- AgentBinding 持久化 UI
+- 平台动作执行 (`action.requested` 执行器)
+
+**未来 EBA 完整落地需要**：
+
+- EventGateway 完整实现
+- EventRouter 与 BindingResolver 集成
+- AgentBinding 持久模型和 UI
+- DeliveryContext 完整实现
+- platform action permission model 和执行器
+- 真实平台事件接入

 ## 11. 落地顺序

--- a/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
+++ b/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
@@ -27,16 +27,17 @@ SDK 要提供稳定协议：
 - 不要求官方 local-agent 的旧行为反向塑造 host 协议。
 - 不在 host 中实现通用 agentic prompt assembler。
 - 不强制 runner 使用 LangBot state / storage；LangBot 只提供可选、受控的寄宿能力。
+- **不实现 EventGateway**：EventGateway 是 future integration point，由外部 event branch 提供。本分支只定义 host-side envelope/binding models 和 `run(event, binding)` 入口。

 ## 3. 分层架构

 目标结构：

 ```text
-IM / WebUI / API / EventRouter
+IM / WebUI / API / EventRouter (future)
        |
        v
-Event Gateway
+Event Gateway (future - external event branch)
        |
        v
 AgentBindingResolver
@@ -47,7 +48,7 @@ AgentRunOrchestrator
        |-- AgentResourceBuilder
        |-- AgentContextBuilder
        |-- AgentRunSessionRegistry
-        |-- AgentStateStore / Storage / EventLog / ArtifactStore
+        |-- PersistentStateStore / EventLogStore / TranscriptStore / ArtifactStore
        v
 Plugin Runtime / AgentRunner
        |
@@ -58,13 +59,21 @@ AgentRunResult stream
 Delivery / Renderer / Platform API
 ```

-当前 Pipeline 只应接入在 `Event Gateway` 或兼容 adapter 位置。它可以继续产生 `message.received`，但不应继续拥有 runner 选择、上下文裁剪和业务 agent 执行的核心语义。
+**当前状态**：
+- `PipelineAdapter` 作为当前 transition adapter，将 Pipeline Query 转换为 `AgentEventEnvelope` + `AgentBinding`
+- `run_from_query()` 内部委托到 `run(event, binding)`
+- EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地
+- EventGateway 由外部 event branch 实现
+
+当前 Pipeline 只应接入在 Pipeline adapter 位置。它可以继续产生 `message.received`，但不应继续拥有 runner 选择、上下文裁剪和业务 agent 执行的核心语义。

 ## 4. LangBot 侧能力

-### 4.1 Event Gateway
+### 4.1 Event Gateway（Future Integration Point）

-Event Gateway 负责把入口统一成 host event：
+> **注意**：EventGateway 由外部 event branch 实现，不在本分支范围。本分支只预留 event-first 入口和 envelope/binding models。
+
+Event Gateway 将负责把入口统一成 host event：

 - IM 平台消息。
 - WebUI debug chat 消息。
@@ -90,11 +99,13 @@ class AgentEventEnvelope(BaseModel):
    raw_ref: RawEventRef | None
 ```

+**当前 transition source**：`PipelineAdapter.query_to_event(query)` 从 Pipeline Query 生成 `AgentEventEnvelope`。
+
 原始平台 payload 可以存为 raw event 或 artifact ref；不要把平台私有字段直接扩散到 AgentRunner 顶层协议。

 ### 4.2 Agent Binding

-Agent binding 是“什么事件调用哪个 runner、带什么绑定配置”的持久配置。它替代长期依赖 Pipeline runner config 的角色。
+Agent binding 是”什么事件调用哪个 runner、带什么绑定配置”的持久配置。它替代长期依赖 Pipeline runner config 的角色。

 建议模型：

@@ -111,11 +122,13 @@ class AgentBinding(BaseModel):
    enabled: bool
 ```

+**当前 transition source**：`PipelineAdapter.pipeline_config_to_binding(query, runner_id)` 从 Pipeline config 生成临时 `AgentBinding`。
+
 Pipeline 当前可以被迁移为一种 binding source：

- 旧 Pipeline AI runner config -> `AgentBinding`
- 旧 Pipeline extension preference -> `resource_policy`
- 旧 Pipeline output settings -> `delivery_policy`
+- Pipeline AI runner config -> `AgentBinding`
+- Pipeline extension preference -> `resource_policy`
+- Pipeline output settings -> `delivery_policy`

 但新设计不应再把这些字段命名为 Pipeline 专属概念。

@@ -168,7 +181,7 @@ run(event, binding)
 - state.updated 处理。
 - delivery backpressure 和 telemetry。

-`run_from_query()` 这类 API 可以保留为兼容 adapter，但内部应转换成 event + binding 后走统一 `run()`。
+`run_from_query()` 这类 API 可以保留为 Pipeline adapter 入口，但内部应转换成 event + binding 后走统一 `run()`。

 ### 4.5 Resource Authorization

@@ -335,30 +348,43 @@ Proxy 是 runner 访问 host 能力的唯一入口：

 ## 6. 当前实现与目标差距

-已落地：
+**已落地（当前分支）**：

- `AgentRunnerRegistry`
- `AgentRunOrchestrator`
- `AgentRunContextBuilder`
- `AgentResourceBuilder`
- `AgentRunSessionRegistry`
- `AgentRunAPIProxy` 基础模型 / 工具 / 知识库授权路径
+- ✅ `AgentRunnerRegistry`
+- ✅ `AgentRunOrchestrator` — event-first `run(event, binding)`
+- ✅ `AgentRunContextBuilder` — event-first context
+- ✅ `AgentResourceBuilder`
+- ✅ `AgentRunSessionRegistry`
+- ✅ `AgentRunAPIProxy` — model / tool / knowledge / history / event / artifact / state APIs
+- ✅ `PipelineAdapter` — Query → Event + Binding
+- ✅ `AgentBinding` 抽象
+- ✅ `AgentEventEnvelope` 抽象
+- ✅ `max-round` 从目标设计中移除，只在 Pipeline adapter 中处理
+- ✅ `PersistentStateStore` — 持久化状态存储
+- ✅ `EventLogStore` / `TranscriptStore` / `ArtifactStore`
+- ✅ history / artifact / event 的受限拉取 API

-需要调整：
+**其他分支负责（非本分支范围）**：

- 把 `pipeline_config` 语义抽象为 `AgentBinding`。
- 把 `Query` 输入抽象为 `AgentEventEnvelope`。
- 把 legacy `max-round` 从目标设计中移除，只作为旧配置兼容处理。
- 把 state store 改为持久 host storage backend。
- 增加 EventLog / Transcript / ArtifactStore。
- 增加 history / artifact / event 的受限拉取 API。
+- EventGateway 实现
+- EventRouter 实现
+- AgentBinding 持久化 UI
+- platform API 动作执行

 ## 7. 落地顺序

-1. 固化 README 路由和专题文档边界。
-2. 在 Host 中抽象 `AgentBinding`，先由 Pipeline adapter 生成。
-3. 将 `AgentRunContextBuilder` 改为 event-first。
-4. 增加持久 transcript/event log 的最小存储模型。
-5. 扩展 `AgentRunAPIProxy` 的 history / artifact / state API。
-6. 将 Pipeline-only 字段逐步下沉到兼容 adapter。
-7. 再设计官方 local-agent 插件如何消费这些基础设施。
+**已完成**：
+
+1. ✅ 固化 README 路由和专题文档边界。
+2. ✅ 在 Host 中抽象 `AgentBinding`，由 Pipeline adapter 生成。
+3. ✅ 将 `AgentRunContextBuilder` 改为 event-first。
+4. ✅ 增加持久 transcript/event log/artifact/state 存储模型。
+5. ✅ 扩展 `AgentRunAPIProxy` 的 history / artifact / state API。
+6. ✅ 将 Pipeline-only 字段下沉到 Pipeline adapter。
+7. ✅ 官方 runner 插件迁移完成（7 个插件）。
+
+**后续工作（其他分支）**：
+
+- EventGateway 实现
+- EventRouter 与 BindingResolver 集成
+- 平台动作执行器
--- a/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md
+++ b/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md
@@ -188,16 +188,16 @@ ctx.prompt + ctx.messages + [current_user_message_from_ctx.input]

 现阶段不要优化裁剪算法，也不要把新的压缩或 token-budget 裁剪塞回 Pipeline stage。
 插件化 AgentRunner 路径应跳过 Pipeline `msgtrun` 的破坏性截断，然后由
-`AgentContextPackager` 在 AgentRunner 边界执行同一套 legacy max-round user-round 规则。
+`AgentContextPackager` 在 AgentRunner 边界执行同一套 max-round user-round 规则。
 当前 SDK v1 还没有顶层 context packaging 字段，LangBot 先把本次 packaging
 元数据放在 `ctx.runtime.metadata.context_packaging`。这是实际下发结果说明，不是 LangBot 侧的长期策略控制面。
 后续 LiteLLM 接入后再把真实 context window、token 预算和摘要策略接到这个边界上。

 ### 3.4.1 Agentic context plan

-本轮只落地 `AgentContextPackager` 的 `legacy_max_round` working window，不改变旧裁剪算法。
+本轮只落地 `AgentContextPackager` 的 `max_round` working window，不改变 user-round 选择规则。
 下面的 `ConversationStore` / `EventLog`、`ContextCompressor` 和 host history API 仍是设计预留。
-目标是让 Pipeline 逐步退化为 legacy 入口，让 AgentRunner 层拥有上下文打包职责。
+目标是让 Pipeline 逐步退化为入口 adapter，让 AgentRunner 层拥有上下文打包职责。

 建议最终拆成四个 host-side 服务：

@@ -217,7 +217,7 @@ ContextCompressor
 - 完整历史属于 LangBot host，不属于插件实例。插件仍是 singleton/stateless。
 - `ctx.messages` 是 working context window，不是完整 conversation dump。
 - 每轮不能全量复制/序列化完整历史给插件 runtime；否则长会话会产生 O(n) 成本和跨进程 payload 膨胀。
- `max-round` 的旧 user-round 规则可以先搬到 `AgentContextPackager`，作为 `legacy_max_round` 策略。
+- `max-round` 的 user-round 规则可以先搬到 `AgentContextPackager`，作为 `max_round` adapter 策略。
 - LiteLLM 接入后，`AgentContextPackager` 再读取模型 context window，升级为 token budget 策略。
 - `ContextCompressor` 生成的是派生 summary/checkpoint，不能覆盖或删除 raw history。
 - 重启恢复依赖持久化 store 和 summary checkpoint，不依赖 `SessionManager` 里的进程内 conversation list。
@@ -231,7 +231,7 @@ context_packaging: ContextPackagingMetadata

 建议语义：

- `context_request.mode`: AgentRunner manifest / binding config 请求的 `legacy_max_round`、`token_budget`、`summary_hybrid`、`external_session`
+- `context_request.mode`: AgentRunner manifest / binding config 请求的 `max_round`、`token_budget`、`summary_hybrid`、`external_session`
 - `context_request.budget`: 模型窗口、预留输出 token、工具/RAG 预算等偏好
 - `context_packaging.policy`: Host 本次实际采用的打包策略
 - `context_packaging.delivered_count`: 本次下发的历史消息数
--- a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
+++ b/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
@@ -175,8 +175,7 @@ LangBot core 不应为了 local-agent 保留业务编排逻辑。local-agent 的
 - `ctx.runtime.metadata.streaming_supported`：当前 adapter 是否能消费流式输出。
 - 宿主代理 action：模型、工具、知识库、rerank 调用必须通过 `run_id` 校验资源权限。

-旧 `max-round` 只能作为历史配置迁移输入。如果需要兼容旧 Pipeline 行为，可以把它转成
-local-agent 插件自己的 bootstrap/history policy；不要把它继续提升为 LangBot host 的目标协议。
+`max-round` 可作为 Pipeline adapter 的历史配置输入。如需适配 Pipeline 行为，可以把 `max-round` 转成 local-agent 插件自己的 bootstrap/history policy；不要把它提升为 LangBot host 的目标协议字段。

 建议 local-agent manifest 使用 hybrid 或 self-managed context：

--- a/docs/agent-runner-pluginization/PROGRESS.md
+++ b/docs/agent-runner-pluginization/PROGRESS.md
@@ -4,7 +4,7 @@

 ## 总体进度

-**当前阶段**: Phase 3 已完成，Phase 4 预留/部分上下文字段已填充
+**当前阶段**: Phase 3 已完成，Event-first 基础设施已完成

 | Phase | 描述 | 状态 |
 |-------|------|------|
@@ -12,7 +12,8 @@
 | Phase 1 | 核心架构（Registry、Orchestrator、上下文模型） | ✅ 完成 |
 | Phase 2 | 权限、能力声明、资源注入 | ✅ 完成 |
 | Phase 3 | 内置 runner 迁移到插件 | ✅ 完成（7/7） |
-| Phase 4 | EBA 事件支持 | 🔲 未开始（已预留稳定事件名，message event/actor/subject 上下文已预填充） |
+| Phase 3.5 | Event-first 基础设施 | ✅ 完成 |
+| Phase 4 | EBA 事件支持 | 🔲 未开始（已预留 event-first 入口，EventGateway 由其他分支实现） |

 ---

@@ -31,21 +32,34 @@
 | `LIST_AGENT_RUNNERS` action | ✅ | `runtime/io/handlers/control.py` |
 | `RUN_AGENT` action | ✅ | `runtime/io/handlers/control.py` |
 | `AgentRunAPIProxy` | ✅ | `api/proxies/agent_run_api.py` |
+| Pull API handlers (State/History/Event/Artifact) | ✅ | `runtime/io/handlers/plugin.py` |
+| `caller_plugin_identity` injection | ✅ | Pull API handlers inject caller identity |

 ### LangBot 侧

 | 组件 | 状态 | 备注 |
 |------|------|------|
 | `AgentRunnerRegistry` | ✅ | `pkg/agent/runner/registry.py` |
-| `AgentRunOrchestrator` | ✅ | `pkg/agent/runner/orchestrator.py` |
+| `AgentRunOrchestrator` | ✅ | `pkg/agent/runner/orchestrator.py` - event-first `run(event, binding)` |
 | `AgentRunnerDescriptor` | ✅ | `pkg/agent/runner/descriptor.py` |
 | `AgentResourceBuilder` | ✅ | `pkg/agent/runner/resource_builder.py` |
-| `AgentRunContextBuilder` | ✅ | `pkg/agent/runner/context_builder.py` |
+| `AgentRunContextBuilder` | ✅ | `pkg/agent/runner/context_builder.py` - event-first context |
 | `AgentResultNormalizer` | ✅ | `pkg/agent/runner/result_normalizer.py` |
 | `ConfigMigration` | ✅ | `pkg/agent/runner/config_migration.py` |
+| `PipelineAdapter` | ✅ | `pkg/agent/runner/pipeline_adapter.py` - Query → Event + Binding |
+| `run_from_query()` → `run(event, binding)` | ✅ | Pipeline 路径委托到 event-first path |
 | `ChatMessageHandler` 集成 | ✅ | 使用 orchestrator 替代 wrapper |
 | `PipelineService` 集成 | ✅ | 从 registry 获取 runner metadata |
 | Plugin connector | ✅ | `list_agent_runners()` / `run_agent()` |
+| `EventLogStore` | ✅ | `pkg/agent/runner/event_log_store.py` |
+| `TranscriptStore` | ✅ | `pkg/agent/runner/transcript_store.py` |
+| `ArtifactStore` | ✅ | `pkg/agent/runner/artifact_store.py` |
+| `PersistentStateStore` | ✅ | `pkg/agent/runner/persistent_state_store.py` |
+| History / Event pull APIs | ✅ | Orchestrator + APIProxy |
+| Artifact pull APIs | ✅ | Orchestrator + APIProxy |
+| State pull APIs | ✅ | Orchestrator + APIProxy |
+| `artifact.created` / `state.updated` handling | ✅ | Event-first handlers in orchestrator |
+| Pipeline path host capability coverage | ✅ | EventLog/Transcript/ArtifactStore/PersistentStateStore |

 ### 官方插件

@@ -62,7 +76,31 @@
 | `langflow-agent` | ✅ 已完成 | SSE 流式，tweaks 配置支持 |
 | `tbox-agent` | ✅ 已完成 | 蚂蚁百宝箱，多模态输入 |

-**注意**: LangBot 内置的旧 runner（`pkg/provider/runners/`）已标记为 legacy，文件顶部添加了 DEPRECATED 注释。
+**注意**: LangBot 内置 runner（`pkg/provider/runners/`）已停用，文件顶部添加了 DEPRECATED 注释。
+
+---
+
+## 未完成但仍属本分支收尾
+
+以下项目属于本分支收尾工作：
+
+- [ ] Smoke / manual validation
+- [ ] Docs final QA
+- [ ] 也许需要 minimal official runner adaptation（如果当前分支需要）
+
+---
+
+## 非本分支范围
+
+以下能力由其他分支负责：
+
+| 能力 | 负责分支 | 备注 |
+|------|----------|------|
+| EventGateway implementation | event branch | 完整事件网关、事件路由、持久化管理 |
+| Event subscription / notification | event branch | 事件订阅、推送通知 |
+| BindingResolver persistence UI | 其他模块 | 绑定配置的持久化 UI |
+| Event router integration | event branch | 与 BindingResolver 集成 |
+| Scheduler / background event source | 其他模块 | 定时任务、后台事件源 |

 ---

@@ -71,10 +109,14 @@
 ### 高优先级

 - [x] 工具详情 API — SDK `GET_TOOL_DETAIL` action、`AgentRunAPIProxy.get_tool_detail()` 与 Host 侧授权校验已接通
+- [x] Pipeline `run_from_query()` → `run(event, binding)` — 已完成
+- [x] EventLog / Transcript / ArtifactStore / PersistentStateStore — 已完成
+- [x] History / Event / Artifact / State pull APIs — 已完成
+- [x] `caller_plugin_identity` 验证路径 — 已完成

 ### 低优先级 / 未来

- [ ] EBA 完整集成 — 稳定事件名与 message event/actor/subject 上下文已预留，完整事件路由与非消息事件仍待实现
+- [ ] EBA 完整集成 — EventGateway、event subscription、event notification 由其他分支实现
 - [ ] 平台 API 动作执行 — `action.requested` 结果类型存在但未执行

 ---
@@ -85,6 +127,7 @@
 |------|------|
 | 2026-05-10 | Phase 0 集成测试通过，SDK v1 协议验证成功 |
 | 2026-05-13 | Phase 3 完成：所有 7 个官方 runner 插件迁移完成 |
+| 2026-05-23 | Phase 3.5 完成：`run_from_query()` 委托到 event-first `run(event, binding)`，Pipeline path 获得 host capabilities |

 ---

--- a/docs/agent-runner-pluginization/PROTOCOL_V1.md
+++ b/docs/agent-runner-pluginization/PROTOCOL_V1.md
@@ -1,8 +1,20 @@
 # LangBot AgentRunner Protocol v1

-本文档定义 LangBot Host 与插件 SDK / Runtime / AgentRunner 之间的协议合同。它优先描述“稳定接口应是什么”，不描述具体落地任务。
+本文档定义 LangBot Host 与插件 SDK / Runtime / AgentRunner 之间的协议合同。它优先描述”稳定接口应是什么”，不描述具体落地任务。

-当前分支已有 Protocol v1 的早期实现，但仍带有 Query、Pipeline、`max-round` 等兼容语义。本文档定义的是目标 v1 合同，用于后续同步改造 LangBot 和 SDK。
+## 当前状态
+
+**Protocol v1 已在当前分支落地**：
+
+- ✅ SDK 定义 `AgentRunnerManifest`、`AgentRunContext`、`AgentRunResult`、`AgentRunAPIProxy`
+- ✅ Runtime 支持 `LIST_AGENT_RUNNERS` 和 `RUN_AGENT`
+- ✅ Host 支持 `run_id` session authorization
+- ✅ Host 能从当前 Pipeline 入口生成 event-first context
+- ✅ `messages` 降级为 optional bootstrap
+- ✅ `max-round` 不出现在协议实体中（只在 Pipeline adapter 中处理）
+- ✅ Proxy 覆盖 model、tool、knowledge、state/storage
+- ✅ History / Event / Artifact / State API 已落地
+- ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地

 ## 1. 协议目标

@@ -168,7 +180,7 @@ class AgentRunContext(BaseModel):
    runtime: AgentRuntimeContext
    config: dict[str, Any] = {}
    bootstrap: BootstrapContext | None = None
-    compatibility: CompatibilityContext | None = None
+    adapter: AdapterContext | None = None
    metadata: dict[str, Any] = {}
 ```

@@ -177,7 +189,7 @@ class AgentRunContext(BaseModel):
 - `event` 是必选字段，Protocol v1 是 event-first。
 - `input` 表示当前事件的主输入，不等于历史消息。
 - `bootstrap` 是可选字段，不是完整 history。
- `compatibility` 只放旧 Query / Pipeline 迁移字段，runner 不应依赖它做长期能力。
+- `adapter` 只放 Pipeline adapter 字段，runner 不应依赖它做长期能力。
 - `config` 是 Host binding config，不是插件实例状态。

 ### 4.3 AgentTrigger
@@ -185,7 +197,7 @@ class AgentRunContext(BaseModel):
 ```python
 class AgentTrigger(BaseModel):
    type: str
-    source: Literal["platform", "webui", "api", "scheduler", "system", "pipeline_compat"]
+    source: Literal["platform", "webui", "api", "scheduler", "system", "pipeline_adapter"]
    timestamp: int | None = None
 ```

@@ -194,7 +206,7 @@ class AgentTrigger(BaseModel):
 ```json
 {
  "type": "message.received",
-  "source": "pipeline_compat"
+  "source": "pipeline_adapter"
 }
 ```

@@ -327,8 +339,8 @@ class BootstrapContext(BaseModel):

 - `bootstrap.messages` 是 host convenience，不是协议核心。
 - 自管 context runner 默认应收到空 bootstrap 或只收到当前 event。
- Host 不应为了“帮 agent 更聪明”而自动拼接完整 transcript。
- 旧 `max-round` 只能影响兼容 adapter 如何生成 `bootstrap.messages`，不能成为 Protocol v1 字段。
+- Host 不应为了”帮 agent 更聪明”而自动拼接完整 transcript。
+- Pipeline adapter 的 `max-round` 配置只影响 adapter 如何生成 `bootstrap.messages`，不能成为 Protocol v1 字段。

 ### 4.10 RuntimeContext

@@ -628,32 +640,41 @@ Host 不负责业务编排：

 这些能力可以由官方或第三方 AgentRunner 插件实现，并通过公开 Host APIs 消费 LangBot 的状态、历史、存储、artifact、模型、工具和知识库能力。

-## 11. Pipeline 兼容
+## 11. Pipeline Adapter

-Pipeline 是兼容入口，不是协议中心。
+Pipeline 是当前入口 adapter，不是协议中心。

-兼容 adapter 应负责：
+**当前分支已实现**：
+
+- ✅ `PipelineAdapter.query_to_event(query)` — 从 `Query` 构造 `AgentEventEnvelope`
+- ✅ `PipelineAdapter.pipeline_config_to_binding(query, runner_id)` — 从 Pipeline config 构造临时 AgentBinding
+- ✅ `run_from_query()` 委托到 `run(event, binding)`
+- ✅ `max-round` 在 Pipeline adapter 中处理，不进入协议实体
+- ✅ Query-only 字段放入 `adapter` context
+
+Pipeline adapter 负责：

 - 从 `Query` 构造 `AgentEventContext`。
 - 从 Pipeline config 构造临时 AgentBinding。
 - 从旧 runner config 构造 `ctx.config`。
- 将旧 `max-round` 转换为 `bootstrap` policy。
- 将旧 Query-only 字段放入 `compatibility`。
+- 将 `max-round` 转换为 `bootstrap` policy。
+- 将 Query-only 字段放入 `adapter`。

-Runner 不应长期依赖 `compatibility`。新 runner 应只依赖 event-first context 和 Host APIs。
+Runner 不应长期依赖 `adapter`。新 runner 应只依赖 event-first context 和 Host APIs。

 ## 12. 最小 v1 完成标准

-Protocol v1 可认为稳定，至少需要：
+Protocol v1 已在当前分支完成：

- SDK 定义 `AgentRunnerManifest`、`AgentRunContext`、`AgentRunResult`、`AgentRunAPIProxy`。
- Runtime 支持 `LIST_AGENT_RUNNERS` 和 `RUN_AGENT`。
- Host 支持 `run_id` session authorization。
- Host 能从当前 Pipeline 入口生成 event-first context。
- `messages` 降级为 optional bootstrap。
- `max-round` 不出现在协议实体中。
- Proxy 至少覆盖 model、tool、knowledge、state/storage。
- History / event / artifact API 的方法签名确定，即使实现可以分阶段落地。
+- ✅ SDK 定义 `AgentRunnerManifest`、`AgentRunContext`、`AgentRunResult`、`AgentRunAPIProxy`
+- ✅ Runtime 支持 `LIST_AGENT_RUNNERS` 和 `RUN_AGENT`
+- ✅ Host 支持 `run_id` session authorization
+- ✅ Host 能从当前 Pipeline 入口生成 event-first context
+- ✅ `messages` 降级为 optional bootstrap
+- ✅ `max-round` 不出现在协议实体中
+- ✅ Proxy 至少覆盖 model、tool、knowledge、state/storage
+- ✅ History / event / artifact API 已落地
+- ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地

 ## 13. 开放问题

--- a/docs/agent-runner-pluginization/README.md
+++ b/docs/agent-runner-pluginization/README.md
@@ -2,24 +2,55 @@

 本文档是 agent-runner 插件化工作的路由页。具体设计拆到独立文档中维护，避免把 LangBot 宿主架构、SDK 协议、上下文管理、EBA 预留和官方 runner 迁移混在同一份 README 里。

-## 核心方向
+## 本分支目标

-LangBot 的目标不是把旧 Pipeline runner 机制简单搬进插件系统，而是逐步转为一个面向 Agent 的宿主层：
+**本分支目标：AgentRunner 外化 / 插件化基础设施**

- LangBot 负责 IM / WebUI / API / 未来事件入口、会话和身份解析、权限、存储、资源授权、运行生命周期、结果投递和审计。
- SDK 负责定义 AgentRunner 组件协议、上下文实体、返回事件流、运行期受限 API 和插件 runtime 协作方式。
- AgentRunner 负责具体 agent runtime 的上下文策略、prompt 组装、压缩、召回、模型调用策略和业务行为。
+本分支只做 LangBot 作为 Agent Host 的基础能力建设：

-后续会逐步弱化 Pipeline。当前 Pipeline 只能视为现有消息入口和兼容层，不应作为新架构设计的中心假设。
+- LangBot 与 SDK 的稳定协议合同（Protocol v1）
+- Host-side `AgentEventEnvelope` / `AgentBinding` 模型
+- `run(event, binding)` event-first 入口
+- `PipelineAdapter`：Pipeline Query → AgentEventEnvelope + AgentBinding
+- EventLog / Transcript / ArtifactStore / PersistentStateStore
+- History / Event / Artifact / State pull APIs
+- SDK runtime forwarding pull APIs + `caller_plugin_identity` 验证路径
+
+## 本分支不实现
+
+以下能力由其他分支负责，本分支只预留 integration point：
+
+- **EventGateway**：完整事件网关实现、事件路由、事件持久化管理
+- **Event subscription / Event notification**：事件订阅、推送通知
+- **BindingResolver persistence UI**：绑定配置的持久化 UI 和 event router 集成（如由其他模块负责）
+- **Scheduler / Background event source**：定时任务、后台事件源
+
+EventGateway 在本文档中描述为 **future integration point**，由外部 event branch 提供。本分支只定义 host-side envelope/binding models 和 `run(event, binding)` orchestrator 入口。
+
+## 当前状态
+
+**当前 Pipeline 是 transition adapter，不再是 agent runner 设计核心。**
+
+当前主入口仍可由 Pipeline 触发，但内部已转换成 event-first path：
+
+1. `run_from_query()` 使用 `PipelineAdapter.query_to_event(query)` 转换为 `AgentEventEnvelope`
+2. `run_from_query()` 使用 `PipelineAdapter.pipeline_config_to_binding(query, runner_id)` 转换为 `AgentBinding`
+3. `run_from_query()` 委托到 `run(event, binding, bound_plugins, adapter_context)`
+
+Pipeline path 已获得 event-first host capabilities：
+- EventLog / Transcript 写入
+- ArtifactStore 注册
+- PersistentStateStore 状态持久化
+- History / Event / Artifact / State pull APIs 可用

 ## 设计文档

 | 文档 | 关注点 |
 | --- | --- |
-| [PROTOCOL_V1.md](./PROTOCOL_V1.md) | LangBot Host 与 SDK / Runtime / AgentRunner 的协议合同：discovery、run context、result stream、proxy actions、错误和兼容边界。 |
+| [PROTOCOL_V1.md](./PROTOCOL_V1.md) | LangBot Host 与 SDK / Runtime / AgentRunner 的协议合同：run context、result stream、proxy actions、错误和 adapter 边界。 |
 | [HOST_SDK_INFRASTRUCTURE.md](./HOST_SDK_INFRASTRUCTURE.md) | LangBot 宿主能力、SDK 协议、runner 发现、绑定、权限、状态、存储、生命周期和调用链。 |
 | [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md) | Agent-owned context 方向：事件到来时 LangBot 传什么，agent 如何按需拉取更多历史 / artifact / state，以及如何支持 KV cache 友好的上下文管理。 |
-| [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md) | EBA 预留：事件模型、事件来源、触发绑定、非消息事件如何复用 AgentRunner 调度。 |
+| [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md) | EBA 预留：事件模型、事件来源、触发绑定、非消息事件如何复用 AgentRunner 调度。**标注为 future design note**。 |
 | [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md) | 官方 runner 插件迁移，包括 local-agent 和外部 runner。它是下游落地计划，不是 LangBot 基础能力设计的前置约束。 |
 | [PHASE1_QA_ACCEPTANCE_MATRIX.md](./PHASE1_QA_ACCEPTANCE_MATRIX.md) | 当前阶段的 QA 验收矩阵。它验证现有分支的兼容性，不代表最终架构边界。 |

@@ -45,15 +76,19 @@ LangBot 的目标不是把旧 Pipeline runner 机制简单搬进插件系统，

 LangBot 不应成为最终 agentic context manager。它应提供事实源、默认上下文引用和按需读取 API；agent 或其背后的 runtime 负责历史剪裁、摘要、召回和 KV cache 策略。

-当前代码中的 legacy `max-round` 只能视为旧 Pipeline 兼容行为，不应作为目标协议继续扩展。
+当前代码中的 `max-round` 是 Pipeline adapter 配置，不应作为目标协议继续扩展。

 详见 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CONTEXT_PROTOCOL.md)。

-### 3. Event Based Agent
+### 3. Event Based Agent（Future）

 消息只是事件的一种。后续 `message.received`、`message.recalled`、`group.member_joined`、`friend.request_received` 等事件都应能通过统一事件 envelope 触发 AgentRunner。

-EBA 设计要复用同一套 runner registry、resource authorization、session registry、state 更新、result normalization 和 delivery lifecycle，不能另起一套调用协议。
+**本分支不实现 EBA 完整能力，只预留：**
+- event-first envelope (`AgentEventEnvelope`)
+- AgentBinding model
+- `run(event, binding)` 入口
+- PipelineAdapter（当前 AgentEventEnvelope / AgentBinding 的 Pipeline adapter source）

 详见 [EVENT_BASED_AGENT.md](./EVENT_BASED_AGENT.md)。

@@ -65,24 +100,6 @@ EBA 设计要复用同一套 runner registry、resource authorization、session

 详见 [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md)。

-## 当前实现状态
-
-当前分支已经具备一部分基础设施：
-
- LangBot 已有 `AgentRunnerRegistry`、`AgentRunOrchestrator`、`AgentRunContextBuilder`、`AgentResourceBuilder`、`AgentResultNormalizer`。
- `ChatMessageHandler` 主路径已经委托 orchestrator。
- Pipeline metadata 已经能从 registry 动态生成 runner 选项和配置 stage。
- SDK 已有 Protocol v1 的 `AgentRunContext`、`AgentRunResult`、capabilities、permissions、`AgentRunAPIProxy`。
- 宿主侧已有 `run_id` session registry，用于模型、工具、知识库、storage 等 runtime action 的授权校验。
-
-仍需要从当前实现中继续剥离的部分：
-
- Pipeline 绑定仍是当前主要入口，后续需要抽象为通用 `AgentBinding`。
- `AgentRunContext` 仍带有旧 Query / Pipeline 语义，需要迁移到 event-first envelope。
- context packaging 仍受 legacy `max-round` 影响，后续应改为 context reference + pull API。
- state store 当前是进程内实现，需要明确 host storage backend。
- artifact / transcript / event log 还没有成为完整宿主能力。
-
 ## 已确认决策

 - 一个插件可以声明多个 `AgentRunner` 组件，每个组件独立暴露 manifest、配置 schema、能力和权限。
@@ -90,4 +107,5 @@ EBA 设计要复用同一套 runner registry、resource authorization、session
 - 绑定只保存 runner id 和绑定配置，不代表插件实例状态。
 - LangBot 可以提供 host-owned state / storage 能力，让 runner 把状态寄宿在 LangBot；但这应该是授权能力，不是强制要求。
 - 官方 runner 插件是协议消费者，不是协议设计的优先约束。
- Pipeline 是当前兼容入口，不是未来架构中心。
+- Pipeline 是当前入口 adapter，不是未来架构中心。
+- EventGateway 是 future integration point，由外部 event branch 提供。