From 768d52f509042fda29da01f4b4083a6aa18637af Mon Sep 17 00:00:00 2001 From: huanghuoguoguo <1051233107@qq.com> Date: Sat, 30 May 2026 09:10:51 +0800 Subject: [PATCH] docs(agent-runner): document external MCP bridge --- .../OFFICIAL_RUNNER_PLUGINS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md b/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md index 9b04fde5..33872d7e 100644 --- a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md +++ b/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md @@ -240,6 +240,21 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/ LangBot-managed 执行隔离。 - 外部 harness 的 permission mode、allowed/disallowed tools、MCP 配置只是一层执行约束；LangBot 仍负责调用前的资源授权、路径策略、secret 过滤和审计。发布级要求见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 +### 7.2 SDK-owned LangBot MCP bridge + +Claude Code / Codex 这类外部 harness 不能直接持有 Python 进程内的 +`plugin_runtime_handler`，因此不能像 `local-agent` 一样直接调用 +`AgentRunAPIProxy`。当前轻量方案是由 SDK 提供一层 per-run MCP bridge： + +- `AgentRunner.create_external_mcp_bridge(ctx)` 是 runner 父类入口。 +- Bridge 由 `AgentRunAPIProxy` 和 `AgentRunContext` 构造，生命周期只覆盖当前 run。 +- Bridge 暴露 SDK 中显式注解的 `AgentRunExternalTools`，而不是扫描或导出全部 SDK action。 +- MCP tool schema 由注解和 Pydantic args model 生成；runner 插件不各自手写 LangBot tool schema。 +- stdio MCP proxy 只把外部 harness 的 MCP 调用转发回当前 run 的本地 bridge。 +- run 结束后 bridge 关闭；这不是 LangBot 主程序全局 MCP server。 + +第一批工具保持很小：当前事件快照、history page、knowledge retrieve、authorized tool call。后续新增工具必须先进入 SDK-owned annotated surface，再由 MCP adapter 自动投影。 + ## 8. Claude Code runner 当前形态 当前 `claude-code-agent` 是最小可运行 MVP，用来证明外部 harness runner 可以接入同一套 AgentRunner 协议。 @@ -262,6 +277,7 @@ Claude Code runner 当前把 LangBot event-first context 投影给外部 harness - 将 prompt prefix 指向 context 文件路径 - 可把 binding 提供的 `skills-json` 写入 Claude Code 原生 `.claude/skills//SKILL.md` - 可把 binding 提供的 `mcp-config-json` 写成每次 run 的 MCP config，并通过 `--mcp-config` / `--strict-mcp-config` 传给 Claude Code +- 可通过 `enable-langbot-mcp=true` 启用 SDK-owned per-run LangBot MCP bridge，使 Claude Code 通过 MCP 调用受限的 `AgentRunAPIProxy` 能力 这些投影目前由 runner adapter 完成；长期更理想的形态是 LangBot Host 负责生成 scoped resource projection，runner 只负责适配 Claude Code 的原生目录和 CLI 参数。 @@ -273,8 +289,10 @@ Claude Code runner 当前把 LangBot event-first context 投影给外部 harness - Claude Code 能读取 LangBot context 文件并按指令输出 sentinel - Skill 文件可以投影到 `.claude/skills/` - MCP config 可以通过 binding config 投影为 Claude Code CLI 参数 +- SDK-owned per-run LangBot MCP bridge 可以被真实 Claude Code CLI 调用，并通过 `langbot_get_current_event` 读取当前 run_id - `external.session_id` 与 `external.working_directory` 可以写入 host-owned state，用于后续 resume - `codex-agent` 可通过 WebUI Debug Chat 调用本机 Codex CLI，读取 LangBot event context，并把 Codex `thread_id` 写入 host-owned state +- SDK-owned per-run LangBot MCP bridge 可以被真实 Codex CLI 调用，并通过 `langbot_get_current_event` 读取当前 run_id - 对需要代理的本地运行环境，`codex-agent` 可通过 binding config 的 `environment-json` 显式传递非 secret 环境变量 下一轮测试入口见 [PHASE1_QA_ACCEPTANCE_MATRIX.md](./PHASE1_QA_ACCEPTANCE_MATRIX.md)。