huanghuoguoguoAgent Runner 插件化文档入口
本文档是 agent-runner 插件化工作的路由页。具体设计拆到独立文档中维护，避免把 LangBot 宿主架构、SDK 协议、上下文管理、EBA 接入边界和官方 runner 迁移混在同一份 README 里。
背景与问题
旧 runner 路径主要围绕 Pipeline / Query 和 pkg/provider/runners 内置实现展开，扩展外部 agent runtime 时容易把 runner 选择、上下文裁剪、资源授权和消息投递绑在同一条聊天链路里。这个分支要把 LangBot 收敛成 Agent Host：Host 负责事件、绑定、授权、事实源和结果投递；AgentRunner 作为插件或外部 harness 消费统一协议并自主管理 prompt / history / memory。
文档维护原则（单一事实源）
- 协议数据结构（schema）唯一定义在 PROTOCOL_V1.md。 其他文档不得重抄 schema，只能引用，例如"见 PROTOCOL_V1 §4.2"。
- 当前实现状态、spec 差距与 runner 验收状态归 STATUS.md；测试执行入口归 AGENT_RUNNER_QA_GUIDE.md，安全发布门槛归 SECURITY_HARDENING.md。
- Host 内部模型（
AgentEventEnvelope、AgentBinding、Descriptor、各 Store）定义在 HOST_SDK_INFRASTRUCTURE.md，不属于 SDK 协议。 - 其余专题文档只讲"为什么/边界/怎么用"，避免重复叙述。
本分支目标
本分支目标：AgentRunner 外化 / 插件化基础设施
本分支只做 LangBot 作为 Agent Host 的基础能力建设，让现有 Pipeline 与用户新建的独立 Agent 都能调用插件化 AgentRunner；不负责把两者做持久化迁移：
- LangBot 与 SDK 的稳定协议合同（Protocol v1）
- Host-side
AgentEventEnvelope/AgentBinding模型 run(event, binding)event-first 入口QueryEntryAdapter：Query → AgentEventEnvelope + AgentBinding- EventLog / Transcript / PersistentStateStore
- History / Event / State pull APIs
- Sandbox/workspace read/write/exec 文件能力，用于当前 run 的上传文件、工具大结果和临时产物
- SDK runtime forwarding pull APIs +
caller_plugin_identity验证路径
本分支不实现
以下能力由其他分支负责，本分支只保留 integration point。EBA 完整事件网关与事件路由当前由外部 EBA 分支联调：
- EventGateway / EventRouter：完整事件网关实现、事件路由、事件持久化管理
- Event subscription / Event notification：事件订阅、推送通知
- BindingResolver persistence UI：绑定配置的持久化 UI 和 event router 集成（如由其他模块负责）
- Scheduler / Background event source：定时任务、后台事件源
- 完整 Agent Platform / daemon control plane：Host-owned
AgentRun/AgentRunEvent、run control primitives、最小 runtime heartbeat/claim lease 已作为 v2 foundation 落地；业务队列、Platform UI、daemon supervisor、runtime wakeup channel 和分布式 runtime 管控仍不属于 Protocol v1 主线。
EventGateway / EventRouter 在本文档中描述为 external EBA branch integration point，由外部 EBA 分支提供并联调。本分支只定义 host-side envelope/binding models 和 run(event, binding) orchestrator 入口。
本分支与外部 EBA / Agent Platform / Runtime Control Plane 的扩展边界见 EXTENSION_SCOPE_MATRIX.md。
目标产品模型
产品层同时保留 Pipeline 与独立 Agent。现有 Pipeline 保持原实体和执行链，也可继续被 bot 绑定；新建 Agent 则携带 runner id、runner config、resource/state/delivery policy 等配置，并可被多个 bot / IM channel 复用。统一产品列表可以聚合展示两类处理器，但不会把 Pipeline 或其内嵌 runner 配置自动迁移成 Agent；用户需要 Agent 时自行新增并绑定。
调度基数、Agent 复用、插件实例无状态、Pipeline adapter 和 fan-out 边界的规范来源是 PROTOCOL_V1.md §13；README 不复写这些约束。
Pipeline 与 AgentRunner 的关系
Pipeline 与 Agent 是 EBA 中平级的处理器；QueryEntryAdapter 只适配 Pipeline 内部的 AgentRunner 调用。
EBA 先根据 target_type 选择 Pipeline 或 Agent。Pipeline 目标执行完整 Stage 链；当 Pipeline 的 AI Stage 调用 runner 时，run_from_query() 经 QueryEntryAdapter 把 Query 转换为 AgentEventEnvelope + AgentBinding，再委托到统一的 run(event, binding, ...)。Agent 目标则直接从自己的持久配置构造 binding。两条路径可以复用同一套 AgentRunner Host capabilities，但 Pipeline 本身不会被投影或持久化为 Agent。
下一轮测试路径、状态定义和 smoke 记录见 AGENT_RUNNER_QA_GUIDE.md。
术语表
| 术语 | 含义 |
|---|---|
| Protocol v1 | Host 调用 AgentRunner 的 runner 可见合同：discovery、AgentRunContext、result stream、Host pull API 和错误模型。 |
| Processor | EBA 的处理器上位概念；当前平级类型为 Pipeline 与 Agent。 |
| Agent | 目标产品层配置对象，保存 runner id、runner config 和资源/状态/投递策略；不等于插件实例。 |
| AgentConfig | Host 内部的单次 AgentRunner 调用配置投影，可由 Pipeline AI Stage 或持久 Agent 生成；投影本身不会创建 Agent。 |
| AgentBinding / binding | Host 在一次事件运行前解析出的有效绑定，决定调用哪个 runner 以及带什么策略。 |
| envelope | Host 内部事件封装，即 AgentEventEnvelope；runner 看到的是由它投影出的 ctx.event。 |
| descriptor / manifest | runner discovery 的能力和配置描述；manifest 来自插件，descriptor 是 Host 校验后的注册表视图。 |
| EBA | Event Based Agent，把消息、撤回、入群、定时任务等都统一成 host event 的接入方向；完整网关和路由在外部 EBA 分支联调。 |
| harness runner | ACP、Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
| projection | Host 把内部事实源、授权资源或配置裁剪成 runner / harness 可消费视图的过程。 |
| Runtime Control Plane | v2 Host 能力层，当前已落地 Host-owned run/result ledger、run control primitives、最小 runtime heartbeat/claim lease；完整 daemon worker 管控、task wakeup 和 Agent Platform 产品形态不是 Protocol v1 主线。 |
设计文档
| 文档 | 关注点 |
|---|---|
| PROTOCOL_V1.md | 🔒 唯一 schema 事实源。LangBot Host 与 SDK / Runtime / AgentRunner 的协议合同：版本协商、discovery、run context、result stream、proxy actions、错误和 adapter 边界。 |
| HOST_SDK_INFRASTRUCTURE.md | LangBot 宿主能力与分层架构、Host 内部模型（AgentEventEnvelope / AgentBinding / Descriptor / 各 Store）、runner 发现、绑定、资源授权、状态、存储、生命周期和调用链。 |
| AGENT_CONTEXT_PROTOCOL.md | Agent-owned context 方向：事件到来时 LangBot 传什么，agent 如何按需拉取更多历史 / state、如何访问 sandbox/workspace 文件，以及如何支持 KV cache 友好的上下文管理。 |
| EXTENSION_SCOPE_MATRIX.md | AgentRunner 外化与外部 EBA / Agent Platform / Runtime Control Plane 的扩展边界矩阵，说明哪些是本分支底座、哪些由外部分支接入。 |
| EVENT_BASED_AGENT.md | EBA 接入边界：事件模型、事件来源、触发绑定、非消息事件如何复用 AgentRunner 调度；完整 EventGateway / EventRouter 由外部 EBA 分支联调。 |
| eba-productization-release.md | EBA 适配器与 AgentRunner 插件化合并后的产品化 / 发布计划，说明非技术用户快速上手差距、Bot 与处理器边界、未来 Solution 分发标的，以及多 namespace SaaS 支持要求。 |
| RUNTIME_CONTROL_PLANE_V2.md | Agent Platform v2 / runtime 管控面决策：AgentRun / AgentRunEvent / run control 已作为 Host 事实源落地，最小 runtime heartbeat/claim lease 已落地；完整 runtime registry / daemon 管控仍是后续可选阶段。 |
| OFFICIAL_RUNNER_PLUGINS.md | 官方 runner 插件迁移，包括 local-agent 和外部 runner。它是下游落地计划，不是 LangBot 基础能力设计的前置约束。 |
| RUN_STEERING_AND_CHECKPOINT.md | 运行中消息注入（steering / follow-up）与压缩摘要持久化（compaction checkpoint）的设计与落地状态记录；schema 仍以 PROTOCOL_V1 为准。 |
| STATUS.md | 当前实现状态、spec 与实现已知差距、runner 验收状态和历史高价值记录。 |
| AGENT_RUNNER_QA_GUIDE.md | Agent Runner QA 指南：保留最高价值测试路径，指导 agent 开展下一轮 WebUI / runner smoke 验证。 |
| SECURITY_HARDENING.md | 安全发布级 hardening 的后续发布门槛：路径隔离、权限边界、secret、资源配额、MCP / skill 投影和审计。 |
工作拆分
1. LangBot + SDK 基础设施
目标是把 LangBot 从内置 runner 执行器变成 agent host：
- LangBot 与 SDK 的稳定协议合同
- runner manifest / descriptor / registry
- Agent / binding 配置解析
- run orchestration 和生命周期管理
- resource authorization 与
run_id级权限校验 - host-owned state / storage / event log / transcript 能力
- sandbox/workspace 文件 staging 与 read/write/exec 能力
- SDK
AgentRunner、AgentRunContext、AgentRunResult、AgentRunAPIProxy
协议合同详见 PROTOCOL_V1.md。
详见 HOST_SDK_INFRASTRUCTURE.md。
2. Agent-owned context
LangBot 不应成为最终 agentic context manager。它应提供事实源、默认上下文引用和按需读取 API；agent 或其背后的 runtime 负责历史剪裁、摘要、召回和 KV cache 策略。
Host 不定义通用历史窗口字段或策略；runner 通过 Host pull API 按需拉取历史并自行管理 working context。
3. Event Based Agent（External Branch）
消息只是事件的一种。外部 EBA 分支中的 message.received、message.recalled、group.member_joined、friend.request_received 等事件都应能通过统一事件 envelope 触发 AgentRunner。
EBA dispatch 的基数和 fan-out 边界仍以 PROTOCOL_V1 §13 为准；本文档只列出本分支提供给外部 EBA 分支复用的入口点。
本分支不实现 EBA 完整能力，只提供：
- event-first envelope (
AgentEventEnvelope) - AgentBinding model
run(event, binding)入口- QueryEntryAdapter（当前 AgentEventEnvelope / AgentBinding 的 Query entry adapter source）
4. 官方 runner 插件
官方 local-agent 和外部 runner 迁移是下游工作。它们需要依附 LangBot 提供的宿主能力，但不应反过来决定宿主协议。
local-agent 可以外移，也可以重写。验收重点是它能完整消费 LangBot 的模型、工具、知识库、存储、事件、history API 和 result stream，而不是保留旧内置 runner 的内部结构。
详见 OFFICIAL_RUNNER_PLUGINS.md。
5. Runtime Control Plane v2（Foundation Partial）
当前 AgentRunner v1 主线仍以 event -> binding -> runner.run(ctx) -> result stream 为 runner 可见合同。Host 侧已经新增持久 AgentRun / AgentRunEvent、result persistence、cancel/finalize/query 等通用 run control primitives，并提供受权限保护的最小 runtime register/heartbeat/list、claim/renew/release 和 reconcile 原语。
在这些 Host 能力之上，可以构建独立 agent 管控面插件；插件负责 UI、策略和编排体验，runtime/task 的事实源仍由 Host 持有。完整 daemon supervisor、任务唤醒/长轮询/WebSocket、跨 Host 分布式锁、provider 登录态诊断和产品化业务队列仍是后续工作。
详见 RUNTIME_CONTROL_PLANE_V2.md。
约束事实源
本分支已确认约束不在 README 重写：
- Runner 可见协议、result stream 和调度边界见 PROTOCOL_V1.md。
- Host 内部
AgentConfig/AgentBinding投影见 HOST_SDK_INFRASTRUCTURE.md。 - 外部 EBA / Agent Platform / Runtime Control Plane 接入边界见 EXTENSION_SCOPE_MATRIX.md。