LangBot/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md

Agent Runner 插件化当前实现与收尾计划

本文档面向实现 agent，用来把当前 AgentRunner 插件化实现推进到可迁移状态。

当前代码已经不是从零开始的 PoC。LangBot 已经具备 registry、orchestrator、context/resource builder、result normalizer 和插件 runtime action。本计划重点描述剩余工作：补齐宿主通用能力、对齐旧内置 runner 行为、完成官方 runner 插件迁移验收。

1. 最终状态

LangBot 最终只保留 Agent Runner 的宿主能力：

• 发现 runner：AgentRunnerRegistry
• 选择 runner：Pipeline 配置和未来事件绑定配置
• 构造上下文：AgentRunContext
• 裁剪资源：模型、工具、知识库、文件、存储、平台能力
• 调度执行：AgentRunOrchestrator
• 归一结果：AgentRunResult -> 当前 Pipeline 的 Message / MessageChunk
• 隔离错误：插件异常、协议错误、超时、结果过大不能破坏主流程
• 迁移旧配置：把旧内置 runner 配置迁到官方 AgentRunner 插件配置
• 转发调用：插件 runtime 只维护已安装插件本身的运行实例，Pipeline 不创建插件实例或 runner 实例

LangBot 不再长期维护内置业务 runner 分支。local-agent、Dify、n8n、Coze、DashScope、Langflow、Tbox 等都迁到官方 AgentRunner 插件。

迁移期间允许旧 RequestRunner 文件继续存在，作为行为对齐基准和回退分析材料。它们不影响当前进度；真正的最终条件是主聊天执行路径不再依赖旧 runner。

1.1 当前状态快照

已完成或基本完成：

• AgentRunnerDescriptor、runner id 解析、registry。
• AgentRunOrchestrator 替换 ChatMessageHandler 内部 runner 调度。
• AgentRunContextBuilder、AgentResourceBuilder、AgentResultNormalizer。
• ai.runner.id + ai.runner_config[id] 的读取与旧配置映射。
• AgentRunner runtime action：LIST_AGENT_RUNNERS、RUN_AGENT。
• run-scoped proxy authorization：模型、工具、知识库、存储、文件。

仍需收尾：

• AgentRunContext 暴露宿主处理后的有效 prompt、结构化输入和 runtime metadata。
• AgentRun proxy action 通过 run_id/query_id 找回当前 Query，保留旧 runner 行为所需上下文。
• AgentResourceBuilder 按 DynamicForm schema 泛化模型/rerank/知识库/文件授权。
• 官方 local-agent 插件完成旧内置 local-agent parity。
• timeout/deadline、取消、插件无输出、协议错误的端到端保护。
• 官方 runner 插件安装/预装/迁移缺失处理。

2. 高层架构

Pipeline MessageProcessor / future EventRouter
        |
        v
AgentRunOrchestrator
        |
        +--> AgentRunnerRegistry
        |       +--> plugin runtime LIST_AGENT_RUNNERS
        |       +--> descriptor cache / validation
        |
        +--> AgentRunContextBuilder
        +--> AgentResourceBuilder
        +--> AgentResultNormalizer
        |
        v
PluginRuntimeConnector.run_agent()
        |
        v
SDK Runtime RUN_AGENT -> plugin AgentRunner.run()

关键约束：

• ChatMessageHandler 不解析 plugin:*，不实例化 wrapper，不知道 runner 组件细节。
• PipelineService.get_pipeline_metadata() 不直接访问插件 runtime，而是读取 registry。
• 旧 RequestRunner 只作为迁移参考，不作为最终运行路径。
• 插件是无状态执行单元：多个 Pipeline 可以绑定同一个 runner id，并分别保存自己的 ai.runner_config[id]；运行时 LangBot 只把当前绑定配置放入 ctx.config 转发给同一个插件 runner。
• 禁止按 Pipeline 或 runner config 创建多个插件实例。需要跨请求持久化的状态必须走明确授权的 plugin storage / workspace storage / 外部服务，不能隐式保存在 per-pipeline 插件对象里。
• EBA 只做字段预留，不在本轮实现 EventBus、EventRouter、平台动作执行。

3. 新增 LangBot 模块

建议新增：

src/langbot/pkg/agent/
  __init__.py
  runner/
    __init__.py
    descriptor.py
    errors.py
    id.py
    registry.py
    context_builder.py
    resource_builder.py
    orchestrator.py
    result_normalizer.py
    config_migration.py

3.1 descriptor.py

定义 LangBot 内部使用的 descriptor：

class AgentRunnerDescriptor(BaseModel):
    id: str
    source: Literal["plugin"]
    label: dict[str, str]
    description: dict[str, str] | None = None
    plugin_author: str
    plugin_name: str
    runner_name: str
    plugin_version: str | None = None
    protocol_version: str = "1"
    config_schema: list[dict[str, Any]] = []
    capabilities: dict[str, bool] = {}
    permissions: dict[str, list[str]] = {}
    raw_manifest: dict[str, Any] = {}

source == "builtin" 不作为最终目标。如果实现阶段需要临时 adapter，必须标记为测试过渡代码，并在官方插件跑通后删除。

3.2 id.py

统一 runner id 解析和生成：

• 插件 runner id：plugin:{author}/{plugin_name}/{runner_name}
• parse_runner_id(id) 返回结构化对象
• 禁止业务代码手写字符串 split
• PoC 已存在的 plugin:author/name/runner 继续作为合法 id

3.3 registry.py

职责：

• 调用 ap.plugin_connector.list_agent_runners(bound_plugins=None) 拉取插件 runner
• 校验 manifest：
  • kind == AgentRunner
  • metadata.name 存在
  • metadata.label 存在
  • spec.protocol_version 兼容，默认 1
  • spec.config 是 list，默认空
  • spec.capabilities 是 dict，默认空
  • spec.permissions 是 dict，默认空
• 输出 AgentRunnerDescriptor
• 缓存 discovery 结果，提供 refresh()
• 单个插件 manifest 失败只记录 warning，不影响其它 runner

刷新触发点：

• 插件安装、卸载、升级、重启后
• Pipeline metadata 请求时发现缓存为空
• 可选 TTL，优先保证正确性

3.4 context_builder.py

把当前 Pipeline query 直接转换成 SDK v1 AgentRunContext。

当前消息 Pipeline 的最小字段：

• run_id: 新 UUID，不使用 query id 作为全局 run id
• trigger.type: message.received
• conversation: launcher、sender、bot、pipeline、历史消息
• event: message event envelope 子集
• actor: sender
• subject: 当前消息或 launcher
• prompt: 宿主已处理的有效 prompt，即 query.prompt.messages
• messages: query.messages
• input: 从 query.user_message 和 query.message_chain 构造
• params: 过滤后的公开业务变量
• resources: 由 resource_builder 注入
• state: host-managed scoped state snapshot
• runtime: host/version/workspace/bot/pipeline/query/trace/deadline
• config: 当前 Pipeline 对该 runner id 的绑定配置，即 ai.runner_config[runner_id]

保留 SDK legacy helper 是 SDK 的责任，LangBot 不再构造 PoC 的 query_id/session/messages/user_message/extra_config 上下文。

prompt 的语义必须明确：它不是静态配置 config["prompt"]，而是 LangBot PreProcessor 和 PromptPreProcessing 插件事件之后的有效 prompt。旧内置 local-agent 请求模型时使用：

query.prompt.messages + query.messages + [query.user_message]

插件化 runner 要保持行为一致，应消费：

ctx.prompt + ctx.messages + [current_user_message_from_ctx.input]

3.5 resource_builder.py

执行前做三层裁剪：

1. runner manifest 声明的 spec.permissions
2. Pipeline 的 extensions_preferences
3. 当前 Pipeline runner 绑定配置中选择的资源范围

输出写入 ctx.resources，至少覆盖：

• models：可调用模型 UUID、类型、能力摘要。包括 LLM、fallback LLM、rerank 等 runner config schema 中选择的模型类资源。
• tools：可见工具 manifest，使用当前 bound plugins / MCP server 范围
• knowledge_bases：可检索知识库列表
• storage：plugin storage / workspace storage 权限摘要
• files：允许读取的配置文件、知识文件摘要
• platform_capabilities：本阶段只声明，不执行平台动作

注意：旧的 unrestricted proxy action 必须二次校验，不能只靠 context 声明。AgentRunner 可用资源应来自 ctx.resources，不是插件 runtime 的全局能力。

资源裁剪要尽量通用，不应只写死 local-agent：

• model-fallback-selector 授权 primary/fallback LLM。
• llm-model-selector 授权 LLM。
• rerank-model-selector 授权 rerank 模型。
• knowledge-base-multi-selector 授权知识库。
• 后续新增 selector 时应在 resource builder 中统一扩展。

3.6 result_normalizer.py

只接受 SDK v1 result：

• message.delta
• message.completed
• tool.call.started
• tool.call.completed
• state.updated
• run.completed
• run.failed
• action.requested 允许实验性返回，但本阶段只记录 telemetry，不执行

映射：

• message.delta.data.chunk -> provider_message.MessageChunk
• message.completed.data.message -> provider_message.Message
• run.completed.data.message -> provider_message.Message
• run.failed -> 抛出受控异常，让 ChatMessageHandler 使用现有错误策略
• 工具和状态事件默认不 yield 到 Pipeline，只记录 debug/telemetry

防护：

• 未知 type warning 后忽略
• 单 result 序列化大小限制
• provider message schema 校验失败转 run.failed
• 插件没有输出任何消息时，按 runner failed 处理

3.7 orchestrator.py

核心入口：

async def run_from_query(query: pipeline_query.Query) -> AsyncGenerator[Message | MessageChunk, None]:
    runner_id = resolve_runner_id(query.pipeline_config)
    descriptor = await registry.get(runner_id, bound_plugins=query.variables.get("_pipeline_bound_plugins"))
    ctx = await context_builder.from_query(query, descriptor)
    async for raw in plugin_connector.run_agent(...):
        async for message in result_normalizer.normalize(raw):
            yield message

必须覆盖：

• runner id 不存在
• 插件系统关闭
• runner 不在 bound plugins 范围内
• 插件 runtime 断连
• runner 协议版本不兼容
• run 超时
• task cancellation

4. 配置模型直接切换

配置模型表达的是 Pipeline 到 runner id 的绑定，不表达插件实例。插件安装后由 plugin runtime 管理单个插件运行实例；不同 Pipeline 选择同一个 runner id 时，只是保存不同的 runner_config[id]，调用时随 AgentRunContext.config 传入。

目标格式：

{
  "ai": {
    "runner": {
      "id": "plugin:langbot/local-agent/default",
      "expire-time": 0
    },
    "runner_config": {
      "plugin:langbot/local-agent/default": {}
    }
  }
}

兼容读取：

• 优先读 ai.runner.id
• 没有 id 时读旧 ai.runner.runner
• 旧内置 runner 名通过迁移表映射：
  • local-agent -> plugin:langbot/local-agent/default
  • dify-service-api -> plugin:langbot/dify-agent/default
  • n8n-service-api -> plugin:langbot/n8n-agent/default
  • coze-api -> plugin:langbot/coze-agent/default
  • dashscope-app-api -> plugin:langbot/dashscope-agent/default
  • langflow-api -> plugin:langbot/langflow-agent/default
  • tbox-app-api -> plugin:langbot/tbox-agent/default

写入策略：

• 新 UI 只写 ai.runner.id 和 ai.runner_config
• 后端 update 接口接受旧字段，但保存时归一成新格式
• migration 最后统一落库

5. 需要修改的 LangBot 范围

必须修改：

• src/langbot/pkg/core/app.py
  • 增加 agent_runner_registry / agent_run_orchestrator 属性
• src/langbot/pkg/core/stages/build_app.py
  • 初始化 Agent 子系统
• src/langbot/pkg/pipeline/process/handlers/chat.py
  • 删除 PluginAgentRunnerWrapper
  • 删除内置 runner 查找逻辑
  • 调用 orchestrator
• src/langbot/pkg/api/http/service/pipeline.py
  • metadata 从 registry 生成
• src/langbot/pkg/plugin/connector.py
  • list_agent_runners() / run_agent() 增加协议校验和 bound plugin 参数
• src/langbot/pkg/plugin/handler.py
  • proxy action 二次权限校验
• src/langbot/pkg/pipeline/preproc/preproc.py
  • 不再只为 local-agent 构造工具、知识库、模型
  • 对所有 agent runner 保留 multimodal input
• src/langbot/pkg/pipeline/pipelinemgr.py
  • runner name 监控改读 runner.id
• src/langbot/templates/metadata/pipeline/ai.yaml
  • runner 字段从 runner 迁到 id
• src/langbot/templates/default-pipeline-config.json
  • 默认 runner 改为官方 local-agent 插件 id
• web/src/app/home/pipelines/components/pipeline-form/PipelineFormComponent.tsx
  • 当前 runner 改读 ai.runner.id
  • runner 配置区改写入 ai.runner_config[id]

最终删除或停用：

• src/langbot/pkg/provider/runner.py 的业务注册路径
• src/langbot/pkg/provider/runners/* 的运行入口

可以暂时保留文件作为官方插件迁移参考，但不应被运行时引用。

6. 收尾实现顺序

Step 1：补齐宿主上下文

• SDK AgentRunContext 增加 prompt，并保持向后兼容默认空列表。
• LangBot context builder 写入 ctx.prompt、ctx.input.contents、ctx.runtime.metadata.streaming_supported、ctx.runtime.metadata.remove_think。
• 保持 ctx.config 只表达静态绑定配置。

Step 2：增强宿主 AgentRun proxy action

• invoke_llm / invoke_llm_stream 通过 run_id/query_id 找回当前 Query。
• 自动合并 model persisted extra_args 与 action-level override。
• 自动应用 pipeline remove-think，并允许 action 显式 override。
• call_tool 传回当前 Query，恢复旧工具调用上下文。
• retrieve_knowledge 保持 bot_uuid、sender_id、session_name 等 settings。
• invoke_rerank 使用 run-scoped model authorization。

Step 3：泛化资源构建

• 按 manifest permissions + bound plugins/MCP + runner config schema 构造资源。
• 支持 primary/fallback LLM、rerank model、KB selector。
• 不把 local-agent 特例扩散到通用资源层。

Step 4：local-agent parity

• 使用 ctx.prompt 而不是重新读取 ctx.config["prompt"]。
• 当前 user message 从 ctx.input.contents 构造，保留多模态内容。
• RAG 只替换/插入文本部分，不丢图片/文件。
• streaming/non-streaming 默认跟随 runtime.metadata.streaming_supported。
• 首轮 fallback 成功后，tool loop 固定使用 committed model。
• tool loop 继续传可用 tools，支持多步工具调用。
• rerank 通过授权模型资源调用。

Step 5：端到端保护和测试

• 插件无输出时按 runner failed 处理。
• timeout/deadline 覆盖 plugin runtime、模型调用和外部 runner 调用。
• runner 协议错误转受控错误。
• 覆盖旧 local-agent 行为 parity：普通回复、流式、工具、多步工具、KB、rerank、多模态、PromptPreProcessing。

Step 6：官方 runner 迁移

• 官方插件 ready 后移除内置 runner registry
• 删除或隔离 provider runners 的运行引用
• 测试旧 runner 名只能通过 migration 映射到插件 id

Step 7：历史配置迁移

• 写 persistence migration
• 更新 default pipeline config
• 对已存在 Pipeline 执行旧字段到新字段迁移
• 对监控/日志里的 runner 字段改用新 id

7. 测试要求

单测：

• runner id parse / format
• registry manifest 校验、失败隔离、bound plugins 过滤
• context builder 从 query 生成完整 v1 context
• resource builder 三层裁剪
• result normalizer 对每种 result type 的映射
• 旧配置 resolve 和 migration

集成测试：

• fake AgentRunner 插件可被 Pipeline 选择
• streaming 输出仍能更新 message card
• 插件异常返回用户可理解错误，不中断 runtime
• runner 不在 bound plugins 时不可执行
• 未授权工具 / 知识库 / 模型 proxy 调用被拒绝
• 旧 local-agent Pipeline 配置迁到官方插件 id

8. 验收标准

• LangBot Pipeline 可以选择插件 AgentRunner 并完成非流式和流式回复。
• ChatMessageHandler 不包含插件 runner 解析和 wrapper。
• PipelineService 不直接拼插件 runner metadata。
• 所有 runner 配置使用 ai.runner.id + ai.runner_config。
• 插件 runtime 不为每个 Pipeline 或 runner 配置创建插件实例；runner_config 只作为绑定配置随 ctx.config 传入。
• 主聊天路径不再通过旧内置 runner 执行业务 runner。迁移期间旧文件可以保留。
• 插件只能访问 ctx.resources 授权的模型、工具、知识库和文件。
• 宿主 action 能为 AgentRunner 调用恢复必要 Query 语义，插件不需要拿裸 Query。
• 官方 local-agent 插件对外行为与旧内置 local-agent 对齐。
• EBA 相关字段只作为 context/result 预留，不执行平台动作。