xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-06-12 16:56:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document litellm agent platform runner path

Browse Source
This commit is contained in:
huanghuoguoguo
2026-06-12 01:46:52 +08:00
parent b0a2315029
commit 8da5fecfbf
10 changed files with 58 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md
View File

@@ -114,7 +114,7 @@ Claude Code、Codex、Kimi Code 这类 runtime 通常已有自己的 session、
- `MCP config`：只投影 per-run、scoped 的 SDK-owned bridge 或外部 MCP 连接配置；LangBot 资源访问必须回到 SDK runtime / Host API，不允许 harness 通过自带 MCP/native tool 直接读 Host 内部资源。
- `state pointers`：外部 session id、working directory、checkpoint 等小型 JSON 状态通过 Host state API 保存。
当前 Claude Code runner 使用 schema `langbot.agent_runner.external_harness_context.v1`（现状见 OFFICIAL_RUNNER_PLUGINS §7）。这类 projection 是"把 LangBot 事实源和授权资源句柄交给 harness"，不是"把 LangBot 资源本体或内部权限交给 harness"，也不是"由 LangBot 决定最终模型上下文"。
当前官方外部 harness 路径由 LiteLLM Agent Platform runner 承担（现状见 OFFICIAL_RUNNER_PLUGINS §7）。这类 projection 是"把 LangBot 事实源和授权资源句柄交给 harness"，不是"把 LangBot 资源本体或内部权限交给 harness"，也不是"由 LangBot 决定最终模型上下文"。
## 5. Runner 上下文边界

54
docs/agent-runner-pluginization/AGENT_RUNNER_QA_GUIDE.md
View File

@@ -17,7 +17,7 @@ event -> binding -> runner.run(ctx) -> result stream
- Host 能通过当前 Query entry adapter 进入 event-first `run(event, binding)` 主链路。
- Runner 来自插件 registry，而不是旧内置 runner 分支。
- `local-agent` 能消费 Host 模型、工具、知识库、history、state、artifact 等基础设施。
- 外部 harness runner（Claude Code / Codex）能消费 event-first context，并把 session / working directory 等指针写回 host-owned state。
- 外部 harness runner（当前为 LiteLLM Agent Platform 统一入口）能消费 event-first context，并把外部 session 指针写回 host-owned state。
- 错误、权限裁剪、无输出、timeout 等路径不会破坏主聊天流程。
本指南不验证：
@@ -49,7 +49,7 @@ event -> binding -> runner.run(ctx) -> result stream
1. Host / SDK / runner 单测。
2. WebUI 登录与 Pipeline Debug Chat 基础 smoke。
3. `local-agent` 高价值场景。
4. Claude Code / Codex 外部 harness smoke。
4. LiteLLM Agent Platform 外部 harness smoke。
5. 权限和错误路径补充检查。
6. 汇总 PASS / FAIL / BLOCKED，并给出下一步建议。
@@ -148,52 +148,32 @@ bin/lbs case list
Rerank、remove-think、文件输入等场景只在本次改动直接涉及时补测，不作为每轮必跑项。
## 7. 外部 Harness Runner Smoke
## 7. LiteLLM Agent Platform Harness Smoke
这些测试用于验证 Claude Code / Codex 这类自管 runtime 能走同一条 Host 协议路径。若本机没有 CLI、登录态或代理配置，标记 BLOCKED，不要伪造 PASS。
这些测试用于验证 Claude Code / Codex 这类自管 runtime 经 LiteLLM Agent Platform 能走同一条 Host 协议路径。若 LiteLLM Agent Platform 服务不可用、目标 harness 没有 CLI/登录态/代理配置，标记 BLOCKED，不要伪造 PASS。
Smoke 前应优先保留一层轻量单测或 fixture 测试：provider-native output（Claude stream-json、Codex JSONL、外部 API SSE / JSON）必须能稳定转换成 `AgentRunResult`，未知 native event 只记录诊断，不导致解析器崩溃。WebUI smoke 证明真实链路可用，但不能替代转换层和错误映射测试。
Smoke 前应优先保留一层轻量单测或 fixture 测试：LiteLLM Agent Platform HTTP session、消息发送、结果解析、`run_id` 提示词注入和 LangBot MCP gateway 必须有稳定测试覆盖。WebUI smoke 证明真实链路可用，但不能替代转换层和错误映射测试。
### 7.1 Claude Code runner
### 7.1 LiteLLM Agent Platform runner
步骤：
1. 确认 `claude` CLI 在 LangBot runtime host 上可执行。
2. 绑定 `plugin:langbot/claude-code-agent/default`。
3. 使用保守权限模式和确定性 prompt。
4. 在 Debug Chat 执行一次真实 smoke。
5. 检查 context / SDK-owned MCP bridge / skill-backed scoped tools 和 host-owned state。
1. 确认 LiteLLM Agent Platform 服务可访问，目标 harness（例如 Claude Code 或 Codex）在该服务所在机器上可执行且已登录。
2. 绑定 `plugin:langbot/litellm-agent-platform-agent/default`。
3. 配置 `base-url`、`api-mode`、`agent-id` 或 `harness` 等必要字段。
4. 在 Debug Chat 执行一次确定性真实 smoke。
5. 检查 LangBot MCP gateway、`run_id` 回填和 host-owned state。
通过条件：
- WebUI 可见回复包含预期 sentinel。
- context JSON schema 为 `langbot.agent_runner.external_harness_context.v1` 或当前文档声明的等价 schema。
- context 包含 event、input、delivery、resources、context、state。
- 如启用 LangBot skills / MCP，Claude Code 只能通过 SDK-owned MCP bridge 或 skill-backed scoped tools 访问 LangBot 资源；不能用 native tools 直接访问。
- `external.session_id` / `external.working_directory` 写入 host-owned state。
- CLI missing、nonzero exit、timeout、empty output 都转成受控 `run.failed`。
- resume 到同一 `external.session_id` 时，不并发写入同一 native session；全局锁边界符合 PROTOCOL_V1 §13。
- 发送给 LiteLLM 的消息包含当前 LangBot `run_id` 和可访问资源摘要。
- Harness 通过 gateway 调用 `langbot_history_page`、`langbot_retrieve_knowledge` 或 `langbot_call_tool` 时必须携带正确 `run_id`；错误 run id 被拒绝。
- `external.session_id` 写入 host-owned state。
- LiteLLM 服务错误、timeout、empty output 都转成受控 `run.failed`。
- resume 到同一 external session 时，全局锁边界符合 PROTOCOL_V1 §13。
### 7.2 Codex runner
步骤：
1. 确认 `codex` CLI 在 LangBot runtime host 上可执行。
2. 绑定 `plugin:langbot/codex-agent/default`。
3. 如需要代理，使用 Agent/runner config 的 `environment-json` 显式传入。
4. 在 Debug Chat 执行一次真实 smoke。
5. 检查 JSONL 事件、last message、host-owned state。
通过条件：
- WebUI 可见回复包含预期 sentinel。
- Codex JSONL 至少包含 thread/session 起始事件、agent message、turn completed。
- `external.session_id` / `external.working_directory` 写入 host-owned state。
- timeout/cancel 不遗留 orphan CLI 子进程。
- CLI missing、nonzero exit、timeout、empty output 都转成受控 `run.failed`。
- resume 到同一 `thread_id` / `external.session_id` 时，不并发写入同一 native session；全局锁边界符合 PROTOCOL_V1 §13。
### 7.3 API 型外部 runner
### 7.2 API 型外部 runner
Dify、n8n、Coze、DashScope、Langflow、Tbox 等外部服务 runner 不作为每轮必跑项。只有在本次改动触及对应 runner 或凭据已经可用时执行 smoke。

4
docs/agent-runner-pluginization/EXTENSION_SCOPE_MATRIX.md
View File

@@ -28,10 +28,10 @@
| Scheduler / Automation | 不实现。文档中只把 `scheduler` 作为 future event source。 | EBA / Agent Platform。 | 定时任务触发 `schedule.triggered` host event，复用 EventGateway -> EventRouter -> `run(event, binding)`。 | 不直接调用某个 runner 插件；不绕过 EventLog / authorization。 |
| Integration provider | 不实现。IM platform adapter 仍是当前平台接入系统。 | EBA / Agent Platform。 | OAuth/webhook/outbound provider 应先转成 canonical host event 或 platform action，再交给 AgentRunner。 | 不把 Linear/Slack/GitHub 等 provider 私有 payload 扩散到 runner 协议顶层。 |
| Platform action / delivery | `action.requested` 已预留但当前仅 telemetry，不执行。`DeliveryContext` 只作为上下文/策略投影。 | EBA / platform action executor。 | 后续 executor 校验 runner capability、binding policy、actor/bot/workspace 权限和审批后执行。 | 不让 runner 直接调用平台 adapter 私有 API；不把平台动作伪装成文本回复副作用。 |
| Runtime registry / worker / task queue | 不实现。当前 Claude Code / Codex 是本机 subprocess MVP path。 | Runtime Control Plane v2。 | 第一阶段先补 Host-owned `AgentRun` / `AgentRunEvent` / run control primitives；完整 runtime registry、heartbeat、task queue、daemon claim、progress/audit 是后续可选阶段。 | 不把 heartbeat/task/warm pool 放进 Protocol v1；不让管理插件拥有 runtime/task 事实源。 |
| Runtime registry / worker / task queue | 不实现。当前官方外部 harness 通过 LiteLLM Agent Platform runner 调用外部平台，不在本分支维护本机 subprocess worker。 | Runtime Control Plane v2。 | 第一阶段先补 Host-owned `AgentRun` / `AgentRunEvent` / run control primitives；完整 runtime registry、heartbeat、task queue、daemon claim、progress/audit 是后续可选阶段。 | 不把 heartbeat/task/warm pool 放进 Protocol v1；不让管理插件拥有 runtime/task 事实源。 |
| Warm pool / reconcile / diagnose | 不实现。 | Runtime Control Plane v2 / deployment layer。 | 作为 task/runtime 的运维能力，围绕 Host-owned runtime/task/audit 表实现。 | 不把 runtime 运维语义写进普通 runner 协议；不把 pod/task 细节泄漏给普通 runner。 |
| Agent memory | 不实现通用长期记忆产品层；提供 history/state/storage/artifact 基础能力。 | Agent Platform 或具体 runner/plugin。 | 平台 memory 可通过 Host storage/state 或独立产品表实现，runner 通过授权 API 拉取。 | 不在 Host core 内置通用 agentic memory 策略；不默认把 memory 全量 inline 到 context。 |
| External harness native session | 已支持 external session id / working directory state handoff 和 resource projection。 | 官方 runner 后续增强；Runtime Control Plane v2 可接管执行。 | 一次性 CLI runner 可继续走 `runner.run(ctx)`；长连接/daemon 模式按 external session key 串行 turn，reader 独占 native stream。 | 不把 Claude/Codex native wire 变成 LangBot 协议；全局锁边界见 PROTOCOL_V1 §13。 |
| External harness native session | LiteLLM Agent Platform runner 支持 external session id state handoff 和 LangBot resource projection。 | 官方 runner 后续增强；Runtime Control Plane v2 可接管执行。 | 外部平台调用继续走 `runner.run(ctx)`；如后续引入长连接/daemon 模式，按 external session key 串行 turn，reader 独占 native stream。 | 不把具体 provider native wire 变成 LangBot 协议；全局锁边界见 PROTOCOL_V1 §13。 |
## 3. 后续分支接入规则

2
docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md
View File

@@ -234,7 +234,7 @@ LangBot 可提供 host-owned state 让 runner 寄宿状态（conversation / acto
Claude Code、Codex、Kimi Code 等外部 harness runner 可能不直接调用 LangBot 的 model/tool loop，而是把 LangBot 事件和授权资源句柄投影到自己的 harness 执行。Host 侧仍保持统一边界：Host 负责构造 event-first context、资源授权、state/storage、EventLog/Transcript/ArtifactStore 和审计；Host 或 binding policy 决定哪些 MCP bridge、skill-backed tool、artifact、history/state 句柄可投影给 runner；runner plugin 把 scoped projection 转成目标 harness 可消费形式；所有 LangBot 资源访问必须经 SDK runtime / `AgentRunAPIProxy` / SDK-owned MCP bridge 转发并接受 Host 校验；外部 harness 负责自己的 native session、tool loop、压缩、权限模式和 resume，但不能用 native tools 绕过 Host 授权。
投影的具体形态（context 文件、resource handles、SDK-owned MCP bridge、state pointers）见 AGENT_CONTEXT_PROTOCOL §4.5；Claude Code / Codex 当前实现见 OFFICIAL_RUNNER_PLUGINS §7。发布级隔离要求见 SECURITY_HARDENING。
投影的具体形态（context 文件、resource handles、LangBot MCP gateway、state pointers）见 AGENT_CONTEXT_PROTOCOL §4.5；当前 LiteLLM Agent Platform runner 形态见 OFFICIAL_RUNNER_PLUGINS §7。发布级隔离要求见 SECURITY_HARDENING。
## 5. SDK 侧协议

49
docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md
View File

@@ -16,7 +16,7 @@ langbot-app/
manifest.yaml
components/agent_runner/default.{yaml,py}
langbot-agent-runner/ # 外部服务 runner 仓库
claude-code-agent/ codex-agent/ dify-agent/ n8n-agent/ ...
litellm-agent-platform-agent/ dify-agent/ n8n-agent/ ...
```
后续可聚合进 monorepo，也可继续独立发布——这个选择不影响协议设计。重复逻辑优先沉淀到 SDK 或明确的共享 helper 包，不要把宿主私有结构泄漏给插件。旧 `src/langbot/pkg/provider/runners/*` 只作为历史行为对齐基准；当前未发布分支不提供旧内置 runner 的运行时 fallback。
@@ -29,8 +29,7 @@ langbot-app/
| `dify-service-api` | `langbot/dify-agent` | `plugin:langbot/dify-agent/default` |
| `n8n-service-api` | `langbot/n8n-agent` | `plugin:langbot/n8n-agent/default` |
| `coze-api` | `langbot/coze-agent` | `plugin:langbot/coze-agent/default` |
| - | `langbot/claude-code-agent` | `plugin:langbot/claude-code-agent/default` |
| - | `langbot/codex-agent` | `plugin:langbot/codex-agent/default` |
| - | `langbot/litellm-agent-platform-agent` | `plugin:langbot/litellm-agent-platform-agent/default` |
| `dashscope-app-api` | `langbot/dashscope-agent` | `plugin:langbot/dashscope-agent/default` |
| `langflow-api` | `langbot/langflow-agent` | `plugin:langbot/langflow-agent/default` |
| `tbox-app-api` | `langbot/tbox-agent` | `plugin:langbot/tbox-agent/default` |
@@ -39,7 +38,7 @@ langbot-app/
## 3. 迁移批次
- **Batch 1（打通协议）**：`local-agent`（能力最完整基准）、`claude-code-agent` / `codex-agent`（外部 code-agent harness 边界）、`dify-agent`（传统 service API runner）。
- **Batch 1（打通协议）**：`local-agent`（能力最完整基准）、`litellm-agent-platform-agent`（外部 code-agent harness 统一入口）、`dify-agent`（传统 service API runner）。
- **Batch 2（外部 workflow）**：`n8n-agent`、`langflow-agent`（webhook/workflow 输入输出、timeout、外部 conversation id）。
- **Batch 3（平台 Agent API）**：`coze-agent`、`dashscope-agent`、`tbox-agent`（平台特有响应格式、引用资料、文件/图片输入）。
@@ -96,40 +95,30 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/
并发约束应按外部 session 粒度表达，而不是按 Agent / runner id / 插件实例表达；Agent 复用和全局锁边界见 PROTOCOL_V1 §13。若 runner 使用 `external.session_id` / `thread_id` resume 到同一 native session，且该 harness 不支持并发 turn，runner 应按稳定 external session key 串行写入；一次性 subprocess runner 可以只在单次 `run(ctx)` 内处理，长连接/daemon runner 则应采用 reader 独占 native stream、turn writer 串行写入的结构。
### 6.2 SDK-owned LangBot MCP bridge
### 6.2 LangBot MCP gateway
外部 harness 不能直接持有进程内的 `plugin_runtime_handler`，也不能用自己的 native tools 直接访问 LangBot 资源。当前轻量方案是由 SDK 提供一层 per-run MCP bridge，把 harness 的工具请求转回 SDK runtime / Host API：
外部 harness 不能直接持有进程内的 `plugin_runtime_handler`，也不能用自己的 native tools 直接访问 LangBot 资源。当前 LiteLLM Agent Platform runner 通过稳定 HTTP MCP gateway 把 harness 的工具请求转回 SDK runtime / Host API：
- `AgentRunner.create_external_mcp_bridge(ctx)` 是 runner 父类入口。
- Bridge 由 `AgentRunAPIProxy` 和 `AgentRunContext` 构造，生命周期只覆盖当前 run。
- Bridge 暴露 SDK 中显式注解的 `AgentRunExternalTools`，而不是导出全部 SDK action；MCP tool schema 由注解和 Pydantic args model 生成。
- stdio MCP proxy 只把外部 harness 的 MCP 调用转发回当前 run 的本地 bridge；run 结束后 bridge 关闭。所有 LangBot 资源访问仍由 Host 按 `run_id`、caller identity 和授权快照校验。
- Gateway 由 runner 插件启动，暴露稳定的 `langbot_history_page`、`langbot_retrieve_knowledge`、`langbot_call_tool` 等最小工具面。
- Harness 每次调用必须携带当前 LangBot `run_id`；Host 仍按 run session、caller identity 和授权快照校验。
- Gateway 只转发 LangBot 资产访问，不承担外部 harness 的文件、进程或 native tool 权限边界。
第一批工具保持很小：当前事件快照、history page、knowledge retrieve、authorized tool call。新增工具必须先进入 SDK-owned annotated surface，再由 MCP adapter 自动投影。
第一批工具保持很小：history page、knowledge retrieve、authorized tool call。新增工具必须先有 Host action 权限与 run-scoped authorization，再由 gateway 投影。
## 7. Claude Code / Codex runner 当前形态
## 7. LiteLLM Agent Platform runner 当前形态
`claude-code-agent` 与 `codex-agent` 是最小可运行 MVP / dev path，用来证明外部 harness runner 可以接入同一套 AgentRunner 协议。本地 smoke 验收入口与记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
`litellm-agent-platform-agent` 是当前外部 harness runner 的统一入口，用来把 Claude Code、Codex 等具体执行器交给 LiteLLM Agent Platform / lite-harness 管理，而不是在 LangBot 官方 runner 仓库中维护每个 CLI provider 的独立适配器。本地 smoke 验收入口与记录见 [AGENT_RUNNER_QA_GUIDE.md](./AGENT_RUNNER_QA_GUIDE.md)。
MVP 含义：已验证 event-first context、resource projection、result stream 和
基础 resume state 可以跑通；不表示 Docker 生产部署、发布级执行隔离、
workspace lifecycle、secret projection、团队级 audit 或 runtime sidecar 已完成。
当前形态：
### 7.1 Claude Code runner
- Runner ID：`plugin:langbot/litellm-agent-platform-agent/default`。
- Runner 通过 HTTP 调用 LiteLLM Agent Platform，外部 harness 的安装、登录态、workspace 和 provider-native 权限由该平台所在运行环境负责。
- Runner 会把当前 LangBot `run_id`、可访问资源摘要和 gateway 使用规则注入本次消息；harness 通过 gateway 回填 `run_id` 后访问 LangBot 资产。
- 外部 session id 写回 Host state，后续轮次可复用目标平台会话。
- Runner ID：`plugin:langbot/claude-code-agent/default`，执行方式：本地 Claude Code CLI print mode（默认 `claude -p`）。
- 默认输出 `message.completed` + `run.completed`；默认权限 `permission-mode=plan`、`max-turns=1`、`disallowedTools=AskUserQuestion`。
- 投影：写入 `agent-context.json`（schema `langbot.agent_runner.external_harness_context.v1`）和 `LANGBOT_CONTEXT.md`；LangBot skills 通过 Host / sandbox scoped tools 与 SDK-owned per-run LangBot MCP bridge 访问，不作为 harness native skill 目录直接授权；可把 scoped `mcp-config-json` 写成每次 run 的 MCP config 经 `--mcp-config` / `--strict-mcp-config` 传入；可通过 `enable-langbot-mcp=true` 启用 SDK-owned per-run LangBot MCP bridge。
- 状态：Claude Code 返回 `session_id` 时通过 `state.updated` 写回 `external.session_id`；工作目录优先用 config 的 `working-directory`，其次用 Host state 的 `external.working_directory`。
### 7.1 当前限制
### 7.2 Codex runner
- Runner ID：`plugin:langbot/codex-agent/default`，执行方式：本地 Codex CLI，读取 LangBot event context。
- Codex `thread_id` 写回 host-owned state；支持 SDK-owned per-run LangBot MCP bridge；需要代理的本地环境可通过 config 的 `environment-json` 显式传递非 secret 环境变量。
### 7.3 当前限制
不是发布级安全边界实现；默认只做本地 CLI 调用，不实现完整执行隔离或 workspace 生命周期；不实现 issue-centric 队列、复杂 workflow engine 或长期任务调度；Docker 环境只能访问容器内 CLI 和凭据；Codex 仅验证协议形态，不代表 Codex 发布级能力或 Kimi runner 已完成。runtime 管控面方向见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
这不是发布级安全边界实现；LangBot 只约束 LangBot 持有资产的访问，外部 harness 的文件、进程、workspace、provider-native MCP 和模型凭据由 LiteLLM Agent Platform 部署侧承担。当前 `run_id` 由系统提示词传递给 harness 并由 gateway 校验，后续若 LiteLLM 原生支持 run-scoped MCP session，可切换为平台级传递。runtime 管控面方向见 [RUNTIME_CONTROL_PLANE_V2.md](./RUNTIME_CONTROL_PLANE_V2.md)。
## 8. 发布和安装策略
@@ -141,5 +130,5 @@ workspace lifecycle、secret projection、团队级 audit 或 runtime sidecar
- LangBot 主聊天路径不再通过 `RequestRunner` 执行业务 runner。
- 官方插件测试覆盖非流式、流式、错误、timeout、配置缺失。
- `local-agent` 能完成模型 fallback、tool calling、知识库检索、多模态输入、静态绑定 prompt 消费、history API 拉取、rerank。
- `claude-code-agent` 或同类 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。
- `litellm-agent-platform-agent` 或同类 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。
- `local-agent` 覆盖旧内置 runner 的用户可见核心能力；代码结构和运行路径不需要相同。

2
docs/agent-runner-pluginization/PROTOCOL_V1.md
View File

@@ -660,7 +660,7 @@ Runner 失败使用 `run.failed`：
- Host 在 `ctx.runtime.deadline_at` 下发总 deadline；SDK proxy 必须用该 deadline 限制单次 action timeout。
- Host 可以取消 active run；Runtime 应尽力中断 runner。
- Protocol v1 的 run 绑定当前 Host 进程和当前 runtime channel，不保证跨 Host 重启恢复。Host 重启、runtime channel 断开或 run session 丢失时，Runtime / remote daemon 必须 fail-fast 并尽力取消仍在执行的 runner，不得继续使用旧 `run_id` 调用 Host API。
- Protocol v1 的 run 绑定当前 Host 进程和当前 runtime channel，不保证跨 Host 重启恢复。Host 重启、runtime channel 断开或 run session 丢失时，Runtime / external harness connector 必须 fail-fast 并尽力取消仍在执行的 runner，不得继续使用旧 `run_id` 调用 Host API。
- Runner 支持中断时应返回或触发 `run.failed`，code 为 `cancelled`。
- Host 必须 unregister active run session。

2
docs/agent-runner-pluginization/README.md
View File

@@ -67,7 +67,7 @@ EventGateway / EventRouter 在本文档中描述为 **external EBA branch integr
| envelope | Host 内部事件封装，即 `AgentEventEnvelope`；runner 看到的是由它投影出的 `ctx.event`。 |
| descriptor / manifest | runner discovery 的能力和配置描述；manifest 来自插件，descriptor 是 Host 校验后的注册表视图。 |
| EBA | Event Based Agent，把消息、撤回、入群、定时任务等都统一成 host event 的接入方向；完整网关和路由在外部 EBA 分支联调。 |
| harness runner | Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
| harness runner | LiteLLM Agent Platform、Claude Code、Codex 等已有自身 session / tool loop / MCP / 压缩机制的外部 runtime adapter。 |
| projection | Host 把内部事实源、授权资源或配置裁剪成 runner / harness 可消费视图的过程。 |
| Runtime Control Plane | v2 Host 能力层，第一阶段重点是 Host-owned run/result ledger 与 control primitives；runtime registry、heartbeat、task queue 和 daemon claim 是后续可选阶段，不是 Protocol v1 主线。 |

6
docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md
View File

@@ -26,8 +26,8 @@ Agent Platform plugin
Agent management UI / project-task model / event routing policy
Business queue / multi-agent orchestration / runtime selection policy
AgentRunner plugin / SDK remote daemon / external harness
Connects Claude Code / Codex / remote agent / subprocess / HTTP API
AgentRunner plugin / external harness runtime
Connects LiteLLM Agent Platform / remote agent / subprocess / HTTP API
Executes and converts provider-native events to AgentRunResult
```
@@ -500,6 +500,6 @@ Tests: 40+ 个文件
- Platform 插件创建 run 时，是否传完整 `AgentBinding` snapshot，还是引用 Host-owned binding id。
- `AgentRunEvent` 与现有 `EventLog` / `Transcript` 的查询关系：直接 join，还是通过专门 view 聚合。
- `run.append_result` 的认证粒度：runner plugin identity、run token、scoped capability token，或 SDK runtime 内部 channel。
- 取消语义：同步 runner、remote daemon、external harness session 如何统一感知 cancel。
- 取消语义：同步 runner、external harness runtime/session 如何统一感知 cancel。
- 何时把插件私有 daemon heartbeat 提升为 Host `RuntimeLease`。
- 若未来 Host 做 claim lease，Platform 插件业务 queue 与 Host execution queue 如何避免双队列混乱。

20
docs/agent-runner-pluginization/SECURITY_HARDENING.md
View File

@@ -6,7 +6,7 @@
**当前结论：暂不塞进本阶段 agent-runner plugin 协议闭环。**
本阶段目标是验证 LangBot 可以通过统一的 `run(event, binding)` 协议接入 `local-agent` 与外部 harness runner（如 Claude Code runner），并能传递事件、上下文、资源句柄、状态和结果流。
本阶段目标是验证 LangBot 可以通过统一的 `run(event, binding)` 协议接入 `local-agent` 与外部 harness runner（当前官方路径为 LiteLLM Agent Platform runner），并能传递事件、上下文、资源句柄、状态和结果流。
安全发布级 hardening 是后续 release gate，不应阻塞当前协议闭环，但必须作为进入生产默认启用前的验收条件。
@@ -63,7 +63,7 @@ Claude Code、Codex、Kimi Code 等外部 harness 可以继续使用自身的权
- 由可信管理员配置 runner binding，并显式启用外部 harness 风险模式。
- 工作目录和 context 输出目录为显式配置或 host 生成路径。
- 外部 runner 应尽量使用保守权限，例如 plan / no-write 模式或禁用高风险工具；当前 Claude Code MVP 仍包含高风险执行模式，只能作为 dev / smoke path。
- 外部 runner 应尽量使用保守权限，例如 plan / no-write 模式或禁用高风险工具；具体 provider-native 高风险模式只能作为管理员显式 opt-in 的 dev / smoke path。
- 通过 timeout、max turns、输出长度和进程取消降低失控风险。
- 通过 host-owned state 保存 `external.session_id`、`external.working_directory` 等 resume 所需指针。
@@ -89,16 +89,16 @@ Claude Code、Codex、Kimi Code 等外部 harness 可以继续使用自身的权
| 项目 | 状态 | 当前已补 | 仍缺口 / 发布前要求 |
| --- | --- | --- | --- |
| Path isolation | Partial | 本地 Claude / Codex runner 会规范化 `working-directory`，拒绝系统根目录、用户 home 和不存在路径；context directory 必须是工作目录内相对路径，拒绝绝对路径、`..` 和 symlink 逃逸；remote daemon 对投影文件使用相对路径 + `realpath` containment，拒绝绝对路径、`..` 和 workspace 内 symlink 写出；ArtifactStore 对 file artifact 使用 `realpath` + root containment 复核。 | Host 生成 workspace / context / artifact root 还缺统一 allowlist、mount 策略、TTL cleanup 和 orphan cleanup；管理员显式 `working-directory` 仍是 operator-owned local directory，LangBot 不承诺阻止外部 CLI 访问同一 OS 用户可访问的所有路径。 |
| Permission boundary | Partial | Host 已有 manifest permissions 与 binding resource policy 交集、run-scoped authorization snapshot、`ctx.context.available_apis`、proxy action `caller_plugin_identity` 校验；Claude Code `--dangerously-skip-permissions` 已改为显式配置，默认 false；Codex 默认 `sandbox=read-only`、`approval_policy=never`，并过滤用户 `mcp_servers.*` config override。 | 外部 CLI 的 native 文件 / 进程 / tool 能力仍属于 operator-owned execution；manifest permissions 只约束 LangBot 持有资源，生产默认或 managed runner 需要容器/VM/OS 级隔离、tool allow/deny 和可审计审批，不能把 runner manifest 当成外部 CLI 的完整权限边界。 |
| Secret handling | Partial | 子进程不再继承完整 LangBot / daemon 环境，只保留 CLI auth、proxy、locale、CA 等 allowlisted env；Codex `environment-json` 禁止覆盖 `HOME`、`PATH`、`CODEX_HOME`、`PYTHONPATH` 和 `LANGBOT_*`；Codex per-run `CODEX_HOME` 会继承 runtime 用户的 Codex auth/session 和非 MCP provider config，但剥离全局 `mcp_servers`；LangBot managed MCP 写入 per-run `CODEX_HOME/config.toml` 且 `0600`，scoped secret 不进入 argv；remote daemon MCP config / `mcp.json` 使用 `0600`；stdout/stderr、错误和 diagnostic artifact 做 redaction + 输出截断；相关单测覆盖 secret/env 泄漏。 | 仍缺 Host 全链路统一 redaction policy、transcript / artifact metadata / admin UI 脱敏规则、secret 来源与轮换策略、跨 runner 的配置脱敏审计。 |
| MCP policy | Partial | SDK-owned per-run LangBot MCP bridge 已有；remote MCP channel 有 per-run secret；bridge 只暴露 SDK annotated tool surface；Codex managed MCP 不允许用户通过 `config-overrides` 注入/覆盖 `mcp_servers.*`，也不继承 runtime 用户全局 `mcp_servers`；remote Codex MCP secret 不进 argv。 | 缺 Host / Admin 级外部 MCP server allowlist、scoped token 生命周期、tool allow / deny 策略、危险工具审批和 MCP 调用审计。 |
| Path isolation | Partial | ArtifactStore 对 file artifact 使用 `realpath` + root containment 复核；Host 侧 run/session 生命周期和 resource authorization 已建立。 | LiteLLM Agent Platform 所在机器的 workspace、挂载、CLI 可访问路径和 cleanup 由部署侧承担；Host 生成 workspace / context / artifact root 还缺统一 allowlist、mount 策略、TTL cleanup 和 orphan cleanup。 |
| Permission boundary | Partial | Host 已有 manifest permissions 与 binding resource policy 交集、run-scoped authorization snapshot、`ctx.context.available_apis`、proxy action `caller_plugin_identity` 校验；LiteLLM gateway 回访 LangBot 资产时必须携带 `run_id` 并接受 Host 校验。 | 外部 harness 的 native 文件 / 进程 / tool 能力仍属于 operator-owned execution；manifest permissions 只约束 LangBot 持有资源，生产默认或 managed runner 需要容器/VM/OS 级隔离、tool allow/deny 和可审计审批。 |
| Secret handling | Partial | LangBot 持有的资源访问不直接投影 secret 给 harness；LiteLLM gateway 使用 bearer token 保护入口，真实 LangBot 资产请求回到 Host action 校验。 | 仍缺 Host 全链路统一 redaction policy、transcript / artifact metadata / admin UI 脱敏规则、secret 来源与轮换策略、跨 runner 的配置脱敏审计；LiteLLM 部署侧的 provider token、CLI auth 和日志脱敏另行负责。 |
| MCP policy | Partial | LiteLLM runner 暴露稳定 HTTP MCP gateway，只提供 history page、knowledge retrieve、authorized tool call 等最小工具面；错误或过期 `run_id` 会被 Host 拒绝。 | 缺 Host / Admin 级外部 MCP server allowlist、scoped token 生命周期、tool allow / deny 策略、危险工具审批和 MCP 调用审计；后续如 LiteLLM 原生支持 run-scoped MCP session，应改为平台级传递 run scope。 |
| Skill access policy | Partial | Host resource builder 会按 runner capability 和 resource policy 暴露 skill-backed scoped tool；当前 code-agent runner 不再接受用户手写 `skills-json`，避免 runner binding 任意投影 skill；skill tool 路径和可见性已有部分单测。 | 缺 code-agent harness 的发布级 skill 来源验证、版本 / hash 记录、projection cleanup 和审计；如后续需要 harness-native skill 文件，也必须由 Host / sandbox 生成受限 tool surface，不能绕过 SDK runtime 访问 LangBot 资源。 |
| Process isolation | Partial | Host runtime deadline、runner subprocess timeout、timeout 后 kill、remote request size limit 已有；本地 Claude / Codex 和 remote daemon 子进程使用新进程组，timeout / cancel 路径会杀进程组；stdout/stderr 有输出上限；Codex 默认使用 `sandbox=read-only`、`approval_policy=never`；Claude Code 高风险 bypass 默认关闭。 | CPU / 内存 / 文件 / 容器 hard quota、网络策略、长期 workspace GC 和平台级 cancel/audit 仍只作为 managed/cloud/default external harness 的 full gate。self-host stdio 只能做到 runner wrapper 层的 timeout / kill / output bound。 |
| State lifecycle | Partial | PersistentStateStore 有 runner / binding / scope 隔离、JSON size limit、state get / set / list / delete；外部 runner 已写回 `external.session_id`、本地 `external.working_directory`、远端 `external.runtime_id` / `external.workspace_key`，避免把远端绝对路径当成 Host resume 事实。 | 缺 session / workspace / artifact TTL、过期清理、迁移策略、orphan cleanup 和 lifecycle audit；managed/default runner 需要 Host first-class workspace 生命周期。 |
| Process isolation | Partial | Host runtime deadline 和 runner timeout 已有；LiteLLM runner 对 HTTP 调用设置 timeout 并把服务错误映射为受控失败。 | 外部 harness 子进程、取消、输出上限、CPU / 内存 / 文件 / 容器 hard quota、网络策略、长期 workspace GC 和平台级 cancel/audit 由 LiteLLM 部署侧或后续 managed/cloud/default external harness gate 负责。 |
| State lifecycle | Partial | PersistentStateStore 有 runner / binding / scope 隔离、JSON size limit、state get / set / list / delete；LiteLLM runner 会写回外部 session id，避免把具体 provider 的内部路径当成 Host resume 事实。 | 缺 session / workspace / artifact TTL、过期清理、迁移策略、orphan cleanup 和 lifecycle audit；managed/default runner 需要 Host first-class workspace 生命周期。 |
| Audit first-class | Partial | EventLog、Transcript、ArtifactStore、PersistentStateStore 已能记录主链路事实；proxy 校验失败会写 warning。 | 资源授权快照、外部命令、MCP tool 决策、secret redaction、cleanup、resume / workspace 生命周期还不是一等 audit surface。 |
| UI / Admin control | Missing | 当前 Pipeline runner 配置能选择插件 runner。 | 缺管理员可见的 runner 权限摘要、风险提示、生产禁用 / 启用入口、resource binding 管理、MCP / skill / workspace 策略 UI。 |
| Test matrix | Partial | 已有 run authorization、caller identity、artifact、state、history / event pull API、local / remote path escape、remote symlink escape、env allowlist / secret 泄漏、Claude dangerous mode 显式启用、timeout、进程组 kill、MCP bridge、remote MCP 回访、Codex MCP secret 不进 argv、Codex per-run auth/config seed、skill visibility 等单测；runner 仓库 `pytest` / `ruff` 已通过；本机真实 Claude Code CLI 与 Codex CLI 的 runner 级 E2E 已通过。 | 仍缺 Host UI smoke、生产禁用入口、MCP deny / dangerous tool 审计、workspace cleanup / audit 完整性矩阵；CPU / memory / container quota 测试属于 managed/cloud/default full gate。 |
| Test matrix | Partial | 已有 run authorization、caller identity、artifact、state、history / event pull API、LiteLLM HTTP session、run_id prompt 注入、gateway MCP 回访、错误 run_id 拒绝、skill visibility 等单测；runner 仓库 `pytest` / `ruff` 应保持通过。 | 仍缺 Host UI smoke、真实 LiteLLM Agent Platform harness E2E、生产禁用入口、MCP deny / dangerous tool 审计、workspace cleanup / audit 完整性矩阵；CPU / memory / container quota 测试属于 managed/cloud/default full gate。 |
## 非当前范围
@@ -106,6 +106,6 @@ Claude Code、Codex、Kimi Code 等外部 harness 可以继续使用自身的权
- 完整异步队列与 issue-centric 产品模型。
- 复杂 workflow engine。
- Codex / Kimi runner 全量接入。
- 具体 CLI provider 直连适配器全量接入。
- EBA 分支的完整迁移由外部 EBA 分支联调；本阶段只复用其需要的 AgentRunner Host 底座。
- 发布级安全 hardening 的完整实现。

9
docs/agent-runner-pluginization/STATUS.md
View File

@@ -14,7 +14,7 @@
| Run authorization snapshot | Done | active run session 冻结 run-scoped resources 与 available APIs；runtime handler 按 snapshot 校验 pull API。 |
| Result payload validation | Done | Wire 保持 `{type, data}`；Host 对投递/副作用类 payload 严格校验，tool-call telemetry 宽松，未知 type 忽略并 warning。 |
| Old built-in runners | Done | 旧 `src/langbot/pkg/provider/runners/*` 与 `RequestRunner` 路径已从本分支删除。 |
| Official runner manifests | Done | `local-agent`、Claude Code / Codex、外部服务 runner 已重新声明真实生效的 LangBot resource permissions。 |
| Official runner manifests | Done | `local-agent`、LiteLLM Agent Platform、外部服务 runner 已重新声明真实生效的 LangBot resource permissions。 |
| Runtime Control Plane v2 | Future | 第一阶段设计为 Host-owned Run Ledger；runtime registry / heartbeat / daemon claim 是后续可选阶段。 |
| Full release security gate | Future | self-host / container opt-in 可继续；managed/default external harness 需完成 SECURITY_HARDENING full gate。 |
@@ -31,8 +31,7 @@
| Runner | 状态 | 最近证据 |
| --- | --- | --- |
| `plugin:langbot/local-agent/default` | Unit-pass; UI smoke pending | 2026-06-10 本地 pytest / ruff 通过；WebUI smoke 由人工统一执行。 |
| `plugin:langbot/claude-code-agent/default` | Unit-pass; CLI smoke environment-dependent | 2026-06-10 本地 pytest / ruff 通过；真实 CLI 取决于本机登录态和代理。 |
| `plugin:langbot/codex-agent/default` | Unit-pass; CLI smoke environment-dependent | 2026-06-10 本地 pytest / ruff 通过；真实 CLI 取决于本机登录态和代理。 |
| `plugin:langbot/litellm-agent-platform-agent/default` | Unit-pass; E2E pending | 通过 runner 仓库单测覆盖 HTTP session、run_id prompt 注入和 LangBot MCP gateway；真实 harness E2E 取决于 LiteLLM Agent Platform 部署和 provider 登录态。 |
| Dify / n8n / Coze / DashScope / Langflow / Tbox | Unit-pass; credential smoke optional | 2026-06-10 plugin layout / parser tests 通过；真实服务凭据 smoke 非每轮必跑。 |
## 历史高价值记录
@@ -42,8 +41,6 @@
截至 2026-05-29，已有本地 smoke 证明：
- `local-agent` 可以通过 Pipeline Debug Chat 走插件化 `AgentRunOrchestrator` 主链路。
- Claude Code runner 可以通过同一条 `run(event, binding)` 路径执行。
- Claude Code runner 可以读取 LangBot event-first context，并通过 SDK-owned MCP bridge / skill-backed scoped tools 访问授权资源，随后写回 `external.session_id` / `external.working_directory`。
- Codex runner 可以通过同一条路径执行，并把 Codex `thread_id` 写回 host-owned state。
- 外部 harness runner 可以通过同一条 `run(event, binding)` 路径执行；当前官方实现已收敛到 LiteLLM Agent Platform runner，具体 Claude Code / Codex CLI provider 不再由本仓库直接维护。
这些记录只证明本地协议闭环可用，不代表发布级 security hardening 已完成。