diff --git a/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md b/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md index 0d64caf7..b406b5e2 100644 --- a/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md +++ b/docs/agent-runner-pluginization/AGENT_CONTEXT_PROTOCOL.md @@ -15,6 +15,7 @@ - ✅ EventLog / Transcript / ArtifactStore — host 事实源 - ✅ PersistentStateStore — 持久化状态存储 - ✅ `max-round` 已从协议实体中移除，只在 Pipeline adapter 中处理 +- ✅ 外部 harness context projection 已用 Claude Code runner 做 MVP 验证：context 文件、skill 投影、MCP 配置和 host-owned resume state ## 1. 设计原则 @@ -31,6 +32,7 @@ - 当前事件的完整结构化信息。 - 稳定身份和会话引用。 - 可授权读取的 history / event / artifact / state API。 +- 可投影给外部 harness 的 scoped context、MCP、skill 和 resource refs。 - payload hard cap 和权限 guardrail。 ### 1.2 不再把 `max-round` 作为目标设计 @@ -232,6 +234,23 @@ await api.state.set(scope="conversation", key="summary.checkpoint", value=...) State 是可选寄宿能力。自管 runtime 可以完全不用；依附 LangBot 的官方 runner 可以使用。 +### 4.6 External harness context projection + +Claude Code、Codex、Kimi Code 这类 runtime 通常已经有自己的 session、工具 loop、MCP 加载、上下文压缩和工作目录。LangBot 不应把这类 runner 强行改造成“host prompt assembler”，而应提供可审计的事件和资源投影。 + +推荐 projection 形态： + +- `agent-context.json`：结构化 JSON，包含 `run_id`、`event`、`actor`、`subject`、`input`、`delivery`、`resources`、`context`、`state`、`runtime`。 +- `LANGBOT_CONTEXT.md`：人类可读摘要，用于 code-agent harness 快速理解当前 IM 事件。 +- `resources`：只包含本次 run 授权后的模型、工具、知识库、artifact、state/storage 句柄，不暴露 Host 内部私有对象。 +- `skills`：Host 或 binding 把已授权 skill 投影为目标 harness 可读目录，例如 Claude Code 的 `.claude/skills//SKILL.md`。 +- `MCP config`：Host 或 binding 提供 scoped MCP 配置，runner adapter 转成目标 harness 的配置文件或 CLI 参数。 +- `state pointers`：外部 session id、working directory、checkpoint 等小型 JSON 状态通过 Host state API 保存，例如 `external.session_id`、`external.working_directory`。 + +当前 Claude Code runner MVP 使用 schema `langbot.agent_runner.external_harness_context.v1`，并已通过 WebUI Debug Chat 验证 context 文件、skill 文件、MCP config 和 resume state 的基本链路。 + +这类 projection 是“把 LangBot 事实源和授权资源交给 harness”，不是“由 LangBot 决定最终模型上下文”。外部 harness 可以继续使用自己的 transcript、工具权限和压缩策略。 + ## 5. Runner manifest 中的上下文声明 建议增加： @@ -318,5 +337,6 @@ LangBot core 不应内置官方 agent 的业务流程： - ✅ `AgentRunAPIProxy` 增加 history / events / artifacts / state API - ✅ Host 增加持久 EventLog / Transcript / ArtifactStore / PersistentStateStore - ✅ `run_from_query()` 委托到 event-first `run(event, binding)` +- ✅ Claude Code external harness smoke：context JSON / Markdown、skill、MCP config、`external.session_id` / `external.working_directory` 这样 LangBot 既能服务依附 host 基础设施的官方 runner，也能服务自带 memory/session/cache 的外部 agent runtime。 diff --git a/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md b/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md index 53f225b1..99c7013d 100644 --- a/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md +++ b/docs/agent-runner-pluginization/EVENT_BASED_AGENT.md @@ -4,6 +4,7 @@ > > EventGateway、EventRouter、Event subscription/notification 由其他分支实现。 > 本分支只预留 event-first 入口和 envelope/binding models。 +> 2026-05-29 的 local-agent / Claude Code runner smoke 只验证本分支的 `run(event, binding)` 调度边界，不表示 EBA 分支已经完成联调。 本文档描述未来 EBA 接入时，事件如何进入 LangBot、如何触发 AgentRunner，以及如何复用插件化 agent 基础设施。 @@ -124,6 +125,7 @@ Platform Adapter / WebUI / API - 不能为 EBA 单独实现另一套 plugin runner 调用协议。 - 不能让非消息事件绕过 resource authorization。 - Delivery 和 platform action 要走统一权限模型。 +- 外部 harness runner 也应通过同一套 envelope/binding/context/result 协议接入；EBA 不应为 Claude Code / Codex / Kimi Code 单独发明队列协议。 ## 7. Delivery Context @@ -205,6 +207,7 @@ EBA 事件进入 AgentRunner 时仍使用 [AGENT_CONTEXT_PROTOCOL.md](./AGENT_CO - ✅ `run_from_query()` → `run(event, binding)` 委托 - ✅ EventLog / Transcript / ArtifactStore - ✅ History / Event / Artifact / State pull APIs +- ✅ 当前消息事件 path 已用 `local-agent` 与 Claude Code external harness runner 做本地 smoke **其他分支负责（非本分支范围）**： diff --git a/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md b/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md index dd5dddb0..fdbf3366 100644 --- a/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md +++ b/docs/agent-runner-pluginization/HOST_SDK_INFRASTRUCTURE.md @@ -63,6 +63,7 @@ Delivery / Renderer / Platform API - `PipelineAdapter` 作为当前入口 adapter，将 Pipeline Query 转换为 `AgentEventEnvelope` + `AgentBinding` - `run_from_query()` 内部委托到 `run(event, binding)` - EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地 +- `local-agent` 与 Claude Code runner 已通过本地 WebUI smoke，验证同一条 `run(event, binding)` path 可服务 host-infra runner 与外部 harness runner - EventGateway 由外部 event branch 实现 当前 Pipeline 只应接入在 Pipeline adapter 位置。它可以继续产生 `message.received`，但不应继续拥有 runner 选择、上下文裁剪和业务 agent 执行的核心语义。 @@ -233,6 +234,23 @@ LangBot 应提供事实源能力： AgentRunner 可以读取这些能力，但不能被迫使用 LangBot 作为唯一记忆系统。 +### 4.8 External harness resource projection + +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 server、skill、artifact、history/state 句柄可以投影给 runner。 +- Runner plugin 负责把 scoped projection 转成目标 harness 可消费的形式，例如 context JSON/Markdown、MCP config、skill 目录、环境变量或 CLI 参数。 +- 外部 harness 负责自己的 native session、tool loop、压缩、权限模式和 resume 机制。 + +当前 Claude Code runner MVP 已验证： + +- LangBot event-first context 可以写入 `agent-context.json` / `LANGBOT_CONTEXT.md`。 +- binding 中的 skill / MCP 配置可以投影到 Claude Code 原生目录和 CLI 参数。 +- `external.session_id` 与 `external.working_directory` 可以通过 Host state 保存并用于 resume。 + +发布级路径隔离、secret 过滤、MCP allowlist、工具白名单、资源配额和 workspace 清理不属于当前协议闭环，详见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 + ## 5. SDK 侧协议 ### 5.1 AgentRunner 组件 @@ -363,6 +381,7 @@ Proxy 是 runner 访问 host 能力的唯一入口： - ✅ `PersistentStateStore` — 持久化状态存储 - ✅ `EventLogStore` / `TranscriptStore` / `ArtifactStore` - ✅ history / artifact / event 的受限拉取 API +- ✅ Claude Code external harness MVP：context/resource projection 与 host-owned resume state smoke **其他分支负责（非本分支范围）**： @@ -370,6 +389,7 @@ Proxy 是 runner 访问 host 能力的唯一入口： - EventRouter 实现 - AgentBinding 持久化 UI - platform API 动作执行 +- 发布级 security hardening ## 7. 落地顺序 @@ -382,6 +402,7 @@ Proxy 是 runner 访问 host 能力的唯一入口： 5. ✅ 扩展 `AgentRunAPIProxy` 的 history / artifact / state API。 6. ✅ 将 Pipeline-only 字段下沉到 Pipeline adapter。 7. ✅ 官方 runner 插件迁移完成（7 个插件）。 +8. ✅ Claude Code runner MVP smoke：外部 harness context 投影和 state handoff。 **后续工作（其他分支）**： diff --git a/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md b/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md index 34a2b569..d6993104 100644 --- a/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md +++ b/docs/agent-runner-pluginization/IMPLEMENTATION_PLAN.md @@ -1,5 +1,7 @@ # Agent Runner 插件化当前实现与收尾计划 +> 2026-05-29 状态说明：本文档是实现推进计划和历史上下文，不是最新验收结论的唯一来源。当前设计入口见 [README.md](./README.md)，协议边界见 [PROTOCOL_V1.md](./PROTOCOL_V1.md)，进度见 [PROGRESS.md](./PROGRESS.md)，最新本地 smoke 见 [PHASE1_QA_REPORT_2026-05-29.md](./PHASE1_QA_REPORT_2026-05-29.md)。 + 本文档面向实现 agent，用来把当前 AgentRunner 插件化实现推进到可迁移状态。 当前代码已经不是从零开始的 PoC。LangBot 已经具备 registry、orchestrator、context/resource builder、result normalizer 和插件 runtime action。本计划重点描述剩余工作：补齐宿主通用能力、对齐旧内置 runner 行为、完成官方 runner 插件迁移验收。 @@ -32,15 +34,17 @@ LangBot 不再长期维护内置业务 runner 分支。`local-agent`、Dify、n8 - `ai.runner.id` + `ai.runner_config[id]` 的读取与旧配置映射。 - AgentRunner runtime action：`LIST_AGENT_RUNNERS`、`RUN_AGENT`。 - run-scoped proxy authorization：模型、工具、知识库、存储、文件。 +- EventLog / Transcript / ArtifactStore / PersistentStateStore。 +- Pipeline adapter 已委托到 event-first `run(event, binding)`。 +- `local-agent` 与 Claude Code runner 已通过本地 WebUI smoke。 仍需收尾： -- `AgentRunContext` 暴露宿主处理后的有效 prompt、结构化输入和 runtime metadata。 -- AgentRun proxy action 通过 `run_id/query_id` 找回当前 Query，保留旧 runner 行为所需上下文。 -- `AgentResourceBuilder` 按 DynamicForm schema 泛化模型/rerank/知识库/文件授权。 -- 官方 `local-agent` 插件完成旧内置 local-agent parity。 +- Docs final QA 与安装/发布文档整理。 - timeout/deadline、取消、插件无输出、协议错误的端到端保护。 - 官方 runner 插件安装/预装/迁移缺失处理。 +- 安全发布级 hardening：路径隔离、权限边界、secret、MCP/skill 投影策略、资源配额、审计。此项不阻塞当前协议闭环，详见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 +- Codex / Kimi runner 全量接入、issue-centric 队列、复杂 workflow engine 和 EBA 分支完整联调。 ## 2. 高层架构 diff --git a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md b/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md index 75d28f76..5cc90411 100644 --- a/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md +++ b/docs/agent-runner-pluginization/OFFICIAL_RUNNER_PLUGINS.md @@ -15,6 +15,7 @@ context/runtime 的 runner，不能被官方插件的实现细节绑死。 - LangBot 主聊天路径通过 `AgentRunOrchestrator` 调用插件化 `AgentRunner`。 - 旧 `src/langbot/pkg/provider/runners/*` 仍保留，作为迁移参考和回退分析材料；在官方插件迁移完成前不要求删除。 - 官方 runner 当前以独立插件目录/仓库推进，例如 `langbot-local-agent/` 和 `langbot-agent-runner/*-agent/`。不再要求先落地单一 monorepo。 +- `claude-code-agent` 已作为外部 harness runner MVP 接入，用来验证 Claude Code / Codex / Kimi Code 这类自管 runtime 的边界。 ## 1. 为什么新仓库 @@ -44,6 +45,7 @@ langbot-app/ pkg/ tests/ langbot-agent-runner/ + claude-code-agent/ n8n-agent/ ... ``` @@ -62,6 +64,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` | | `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` | @@ -73,11 +76,13 @@ langbot-app/ ### Batch 1：打通协议 1. `local-agent` -2. `dify-agent` +2. `claude-code-agent` +3. `dify-agent` 原因： - `local-agent` 覆盖模型、工具、知识库、流式、会话历史，是能力最完整的基准。 +- `claude-code-agent` 代表 Claude Code / Codex / Kimi Code 这类本地或外部 code-agent harness：它们通常自带 session、tool loop、上下文压缩和权限模型，LangBot 主要提供 IM 事件、资源投影、审计和状态指针。 - `dify-agent` 代表外部 Agent 平台调用，配置和错误处理能验证传统 service API runner 的迁移方式。 ### Batch 2：迁移外部 workflow runner @@ -205,7 +210,61 @@ context: - 平台 conversation id 存 plugin storage 或 context runtime state，不能依赖 LangBot 内置 conversation uuid 私有结构 - 流式支持按平台能力声明，没有流式就只发 `message.completed` -## 8. 发布和安装策略 +### 7.1 Code-agent harness runner 要求 + +Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/工具 loop 执行。它们可以依赖自己的 harness，但仍必须遵守 LangBot 的宿主边界： + +- 输入来自 `ctx.event` / `ctx.input`，不能直接依赖 Pipeline 私有 `Query`。 +- LangBot 授权后的资源应被投影为 harness 可读的 context 文件、MCP 配置、skill 目录、环境变量或 CLI 参数。 +- 外部 session id、workspace、checkpoint 等跨轮次指针应写入 Host state 或 plugin storage；插件实例本身保持无状态。 +- CLI / subprocess runner 必须处理 timeout、取消、空输出、非零退出和 stderr 映射。 +- 外部 harness 的 permission mode、allowed/disallowed tools、MCP 配置只是一层执行约束；LangBot 仍负责调用前的资源授权、路径策略、secret 过滤和审计。发布级要求见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 + +## 8. Claude Code runner 当前形态 + +当前 `claude-code-agent` 是最小可运行 MVP，用来证明外部 harness runner 可以接入同一套 AgentRunner 协议。 + +### 8.1 基本行为 + +- 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` +- 默认状态：如果 Claude Code 返回 `session_id`，runner 通过 `state.updated` 写回 `external.session_id` +- 工作目录：优先使用 binding config 的 `working-directory`，其次使用 Host state 中的 `external.working_directory` + +### 8.2 Context / skill / MCP 投影 + +Claude Code runner 当前把 LangBot event-first context 投影给外部 harness： + +- 写入 `agent-context.json`，schema 为 `langbot.agent_runner.external_harness_context.v1` +- 写入 `LANGBOT_CONTEXT.md`，作为人类可读摘要 +- 将 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 + +这些投影目前由 runner adapter 完成；长期更理想的形态是 LangBot Host 负责生成 scoped resource projection，runner 只负责适配 Claude Code 的原生目录和 CLI 参数。 + +### 8.3 已验证能力 + +2026-05-29 本地验证： + +- WebUI Debug Chat 能通过 Pipeline adapter 调用 `claude-code-agent` +- Claude Code 能读取 LangBot context 文件并按指令输出 sentinel +- Skill 文件可以投影到 `.claude/skills/` +- MCP config 可以通过 binding config 投影为 Claude Code CLI 参数 +- `external.session_id` 与 `external.working_directory` 可以写入 host-owned state，用于后续 resume + +详见 [PHASE1_QA_REPORT_2026-05-29.md](./PHASE1_QA_REPORT_2026-05-29.md)。 + +### 8.4 当前限制 + +- 不是发布级安全边界实现。 +- 默认只做本地 CLI 调用，不实现完整 sandbox/workspace 生命周期。 +- 不实现 issue-centric 队列、复杂 workflow engine 或长期任务调度。 +- 不代表 Codex / Kimi runner 已完成；它只验证外部 harness runner 的协议形态。 + +## 9. 发布和安装策略 最终 LangBot 安装或升级时需要保证官方 runner 插件可用。可选方案： @@ -220,11 +279,12 @@ context: - 历史配置 migration 只在官方插件可用时执行。 - 迁移期间保留旧内置 runner 文件，直到对应官方插件通过 parity 验收。 -## 9. 验收标准 +## 10. 验收标准 - 每个旧 runner 都有对应官方 AgentRunner 插件。 - 旧 runner 配置能无损复制到新 `runner_config[id]`。 - LangBot 主聊天路径不再通过 `RequestRunner` 执行业务 runner。 - 官方插件测试覆盖非流式、流式、错误、timeout、配置缺失。 - `local-agent` 插件能完成模型 fallback、tool calling、知识库检索、多模态输入、prompt preprocessing 后的有效 prompt 消费、rerank。 +- `claude-code-agent` 或同类 code-agent harness runner 能消费 event-first context、投影 scoped resources、保存 external session state，并通过 WebUI Debug Chat smoke。 - 对外行为与旧内置 local-agent runner 保持一致；代码结构不需要相同。 diff --git a/docs/agent-runner-pluginization/PHASE1_QA_ACCEPTANCE_MATRIX.md b/docs/agent-runner-pluginization/PHASE1_QA_ACCEPTANCE_MATRIX.md index e20a9c0e..6f38f7be 100644 --- a/docs/agent-runner-pluginization/PHASE1_QA_ACCEPTANCE_MATRIX.md +++ b/docs/agent-runner-pluginization/PHASE1_QA_ACCEPTANCE_MATRIX.md @@ -14,6 +14,7 @@ Phase 1 的目标是让当前聊天 Pipeline 在选择插件化 AgentRunner 后 - Runner 由插件提供，并通过 `AgentRunOrchestrator` 调用。 - `local-agent` 插件达到旧内置 local-agent 的主要行为 parity。 - 官方外部 runner 插件至少完成 smoke 验收。 +- 外部 harness runner（当前以 Claude Code MVP 为代表）至少完成一次 WebUI smoke，验证 event-first context、资源投影和 state handoff。 - 旧 Pipeline 配置兼容，新配置可保存并生效。 - 权限裁剪、错误隔离、运行状态更新不破坏主流程。 @@ -67,6 +68,7 @@ Host 侧 agent runner 单测不通过时，不应进入 UI parity QA。 - WebUI 截图或浏览器操作记录。 - 后端日志中对应 query id/run id 的关键行。 - 对外部 runner，记录外部服务响应摘要或错误码。 +- 对外部 harness runner，记录 context 文件、MCP/skill 投影、外部 session id / working directory state 和 CLI 错误摘要。 用户可见流程必须通过 WebUI 或真实消息平台验证。API/curl 只能作为诊断证据，不能单独让 UI case PASS。 @@ -76,7 +78,7 @@ Host 侧 agent runner 单测不通过时，不应进入 UI parity QA。 | --- | --- | --- | --- | | P0-ENV-01 | LangBot 服务可用 | 启动后端和前端，打开 WebUI。 | WebUI 可登录/访问；后端无启动异常；插件系统按配置启用。 | | P0-ENV-02 | 插件 runtime 可用 | 查看插件列表或后端日志。 | runtime 已启动；官方 runner 插件处于可用状态；无循环重启。 | -| P0-ENV-03 | Runner registry 可发现插件 runner | 打开 Pipeline AI runner 配置。 | runner 下拉列表来自插件 registry；至少能看到 `plugin:langbot/local-agent/default`。 | +| P0-ENV-03 | Runner registry 可发现插件 runner | 打开 Pipeline AI runner 配置。 | runner 下拉列表来自插件 registry；至少能看到 `plugin:langbot/local-agent/default`；若安装了 Claude Code runner，还应看到 `plugin:langbot/claude-code-agent/default`。 | | P0-ENV-04 | 默认 Pipeline 可创建 | 新建 Pipeline 或读取默认 Pipeline。 | 默认配置使用 `ai.runner.id` 与 `ai.runner_config`；默认 runner 可保存。 | | P0-ENV-05 | 主聊天路径调用插件 runner | 使用默认 `local-agent` Pipeline 发送一条普通消息。 | 后端日志显示走 `AgentRunOrchestrator` / `RUN_AGENT`；用户收到正常回复；旧内置 runner 不应作为主路径执行。 | | P0-ENV-06 | 单测基线 | 运行 `uv run --frozen pytest tests/unit_tests/agent`。 | 全部通过；若失败，必须先修复或记录为 P0 FAIL。 | @@ -138,6 +140,17 @@ Host 侧 agent runner 单测不通过时，不应进入 UI parity QA。 | P2-EXT-04 | `dashscope-agent` | 配置 agent 或 workflow 并发送消息。 | 调用成功；失败时错误可控且不影响后续请求。 | | P2-EXT-05 | `langflow-agent` | 配置 flow endpoint 并发送消息。 | 普通或 SSE 流式响应能归一为 LangBot 消息。 | | P2-EXT-06 | `tbox-agent` | 配置 Tbox 应用并发送消息。 | 回复正常；多模态输入按插件能力处理。 | +| P2-EXT-07 | `claude-code-agent` | 配置本地 Claude Code CLI，使用保守权限模式发送确定性 Debug Chat prompt。 | runner 可选、配置可保存、CLI 成功返回；LangBot context 文件可被 Claude Code 读取；`external.session_id` / `external.working_directory` 可写入 host-owned state；CLI 错误、timeout、空输出能被转成受控 `run.failed`。 | + +### 9.1 外部 harness runner 追加检查 + +对 Claude Code / Codex / Kimi Code 这类 runner，P2 smoke 还需要检查： + +- 默认不要求 LangBot 调用自己的模型/工具 loop；runner 可以依赖自身 harness。 +- LangBot 仍要把当前 event、input、delivery、resources、context 和 state 作为 scoped context 传给 runner。 +- skill / MCP / workspace projection 必须来自 binding 或 Host 授权后的资源，不应让 runner 自行读取全局未授权配置。 +- session id、working directory、checkpoint 等跨轮次状态必须进入 Host state 或 plugin storage，不能保存在插件实例内存中。 +- 发布级 path isolation、secret filtering、MCP allowlist、资源配额和 workspace cleanup 只作为 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) 的后续 release gate，不阻塞当前 smoke。 ## 10. P2 事件预留检查 @@ -163,5 +176,18 @@ QA agent 完成后应输出一份报告，至少包含： - P0 全 PASS。 - P1 全 PASS，或只有旧内置 runner 同样不支持的 N/A。 -- P2 外部 runner smoke 对可用凭据全部 PASS。 +- P2 外部 runner smoke 对可用凭据全部 PASS；本地 Claude Code runner 若作为当前 external harness 代表，应至少 PASS 一次 WebUI smoke。 - 剩余问题均为 EBA 预留、外部服务凭据、或非阻塞体验问题。 + +## 12. 当前已知验收记录 + +2026-05-29 本地记录： + +| 范围 | 状态 | 证据 | +| --- | --- | --- | +| `local-agent` WebUI Debug Chat | PASS | `langbot-skills/reports/2026-05-29-17-59-00-462-08-00-pipeline-debug-chat.md` | +| `claude-code-agent` WebUI Debug Chat | PASS | `langbot-skills/reports/2026-05-29-18-03-31-169-08-00-pipeline-debug-chat.md` | +| Claude Code context / skill / MCP projection | PASS | `langbot-skills/reports/claude-code-agent-resource-context-20260529.md` | +| Claude Code resume state | PASS | `langbot-skills/reports/claude-code-agent-real-workdir-20260529.md` | + +完整汇总见 [PHASE1_QA_REPORT_2026-05-29.md](./PHASE1_QA_REPORT_2026-05-29.md)。 diff --git a/docs/agent-runner-pluginization/PHASE1_QA_REPORT_2026-05-29.md b/docs/agent-runner-pluginization/PHASE1_QA_REPORT_2026-05-29.md new file mode 100644 index 00000000..de04e42d --- /dev/null +++ b/docs/agent-runner-pluginization/PHASE1_QA_REPORT_2026-05-29.md @@ -0,0 +1,84 @@ +# Agent Runner Phase 1 QA Report - 2026-05-29 + +本文档记录 2026-05-29 对 agent-runner plugin 协议闭环的本地验收。它不改写 +[PHASE1_QA_REPORT_2026-05-18.md](./PHASE1_QA_REPORT_2026-05-18.md) 的历史结论。 + +## 1. 验收结论 + +当前分支可以认为完成了本地协议闭环 smoke： + +- `local-agent` 插件可以通过 Pipeline Debug Chat 走插件化 `AgentRunOrchestrator` 主链路。 +- `claude-code-agent` 可以作为外部 harness runner 通过同一条 `run(event, binding)` 路径执行。 +- Claude Code runner 可以接收 LangBot event-first context，并把 context / skill / MCP 配置投影给本地 Claude Code CLI。 +- Claude Code runner 可以把外部 session id 和 working directory 写回 LangBot host-owned state，用于后续 resume。 + +这表示当前架构足以支撑 `local-agent` 与一个最小 Claude Code runner 的联调；不表示安全发布级 hardening 已完成。 + +## 2. 环境 + +| 项 | 值 | +| --- | --- | +| LangBot commit | `9330a684` | +| `langbot-agent-runner` commit | `07e235b`，本地存在未提交的 `claude-code-agent/` | +| `langbot-local-agent` commit | `ce1fe46` | +| Claude Code CLI | `2.1.137 (Claude Code)` | +| Frontend | `http://127.0.0.1:3000` | +| Backend | `http://127.0.0.1:5300` | + +## 3. Pipeline 与 Runner + +| Runner | Pipeline | Runner ID | 结果 | +| --- | --- | --- | --- | +| local-agent | `dc75c543-70f9-4d2a-9467-968628e6ca01` | `plugin:langbot/local-agent/default` | PASS | +| Claude Code | `f5c6d8e0-0c5a-4f3f-b7d4-0c1a0dec0de1` | `plugin:langbot/claude-code-agent/default` | PASS | + +## 4. 证据 + +### 4.1 local-agent UI E2E + +- 报告：`/home/glwuy/langbot-app/langbot-skills/reports/2026-05-29-17-59-00-462-08-00-pipeline-debug-chat.md` +- 后端日志成功信号： + - `Processing request from person_websocket` + - `Conversation(1) Streaming completed: 1 chunks, 2 chars` +- 验收点：Debug Chat 用户可见回复正常，后台 log guard 未发现失败信号。 + +### 4.2 Claude Code runner UI E2E + +- 报告：`/home/glwuy/langbot-app/langbot-skills/reports/2026-05-29-18-03-31-169-08-00-pipeline-debug-chat.md` +- 后端日志成功信号： + - `Processing request from person_websocket` + - `Conversation(3) Streaming completed: 1 chunks, 22 chars` +- 验收点：Debug Chat 用户可见回复 `LANGBOT_CLAUDE_E2E_OK2`。 + +### 4.3 Claude Code context / skill / MCP projection + +- 报告：`/home/glwuy/langbot-app/langbot-skills/reports/claude-code-agent-resource-context-20260529.md` +- 通过点： + - 生成的 context JSON schema 为 `langbot.agent_runner.external_harness_context.v1`。 + - context JSON 包含 `event`、`actor`、`delivery`、`input`、`resources`、`context` 和 `state`。 + - Claude Code 可读取 LangBot 注入的 context 文件并输出 `LANGBOT_CLAUDE_CONTEXT_RESOURCE_OK`。 + - skill 文件投影到 `.claude/skills/langbot-e2e-context/SKILL.md`。 + +### 4.4 Claude Code resume state + +- 报告：`/home/glwuy/langbot-app/langbot-skills/reports/claude-code-agent-real-workdir-20260529.md` +- 通过点： + - `agent_runner_state` 中记录了 `external.session_id`。 + - `agent_runner_state` 中记录了 `external.working_directory`。 + - 使用保存的 session id 在对应工作目录执行 Claude Code resume 成功。 + +## 5. 当前未关闭项 + +以下不应作为当前协议闭环的阻塞项： + +- 发布级安全 hardening：见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 +- 完整 EBA 分支联调和 EventGateway 迁移。 +- 完整异步队列、issue-centric 产品模型和复杂 workflow engine。 +- Codex / Kimi runner 全量接入。 + +## 6. 建议状态 + +- 本地 `local-agent` 协议闭环：PASS。 +- 本地 Claude Code external harness smoke：PASS。 +- Phase 1 是否整体关闭：可以关闭本地协议闭环；若定义为所有官方外部服务 runner 都必须有真实凭据，则外部服务 runner 仍按凭据可用性分别 PASS / BLOCKED。 + diff --git a/docs/agent-runner-pluginization/PROGRESS.md b/docs/agent-runner-pluginization/PROGRESS.md index f70d2d66..b24d73b3 100644 --- a/docs/agent-runner-pluginization/PROGRESS.md +++ b/docs/agent-runner-pluginization/PROGRESS.md @@ -4,7 +4,7 @@ ## 总体进度 -**当前阶段**: Phase 3 已完成，Event-first 基础设施已完成 +**当前阶段**: Phase 3.5 已完成，Event-first 基础设施已完成；2026-05-29 已通过本地 `local-agent` 与 Claude Code runner smoke。 | Phase | 描述 | 状态 | |-------|------|------| @@ -13,6 +13,7 @@ | Phase 2 | 权限、能力声明、资源注入 | ✅ 完成 | | Phase 3 | 内置 runner 迁移到插件 | ✅ 完成（7/7） | | Phase 3.5 | Event-first 基础设施 | ✅ 完成 | +| Phase 3.6 | 外部 harness runner 协议 smoke | ✅ 完成（Claude Code MVP） | | Phase 4 | EBA 事件支持 | 🔲 未开始（已预留 event-first 入口，EventGateway 由其他分支实现） | --- @@ -60,6 +61,7 @@ | State pull APIs | ✅ | Orchestrator + APIProxy | | `artifact.created` / `state.updated` handling | ✅ | Event-first handlers in orchestrator | | Pipeline path host capability coverage | ✅ | EventLog/Transcript/ArtifactStore/PersistentStateStore | +| External harness state handoff | ✅ | `external.session_id` / `external.working_directory` 写入 PersistentStateStore | ### 官方插件 @@ -72,21 +74,31 @@ | `dify-agent` | ✅ 已完成 | 支持 chat/agent/workflow 三种应用类型 | | `n8n-agent` | ✅ 已完成 | Webhook 调用，支持 basic/jwt/header 认证 | | `coze-agent` | ✅ 已完成 | 多模态输入，思维链处理 | +| `claude-code-agent` | ✅ MVP smoke 通过 | 本地 Claude Code CLI；context / skill / MCP 投影；host-owned resume state | | `dashscope-agent` | ✅ 已完成 | 阿里云百炼，支持 agent/workflow 两种模式 | | `langflow-agent` | ✅ 已完成 | SSE 流式，tweaks 配置支持 | | `tbox-agent` | ✅ 已完成 | 蚂蚁百宝箱，多模态输入 | **注意**: LangBot 内置 runner（`pkg/provider/runners/`）已停用，文件顶部添加了 DEPRECATED 注释。 +### 本地验收 + +| 日期 | 范围 | 状态 | 证据 | +|------|------|------|------| +| 2026-05-29 | `local-agent` Pipeline Debug Chat | ✅ PASS | `langbot-skills/reports/2026-05-29-17-59-00-462-08-00-pipeline-debug-chat.md` | +| 2026-05-29 | `claude-code-agent` Pipeline Debug Chat | ✅ PASS | `langbot-skills/reports/2026-05-29-18-03-31-169-08-00-pipeline-debug-chat.md` | +| 2026-05-29 | Claude Code context / skill / MCP projection | ✅ PASS | `langbot-skills/reports/claude-code-agent-resource-context-20260529.md` | +| 2026-05-29 | Claude Code resume state | ✅ PASS | `langbot-skills/reports/claude-code-agent-real-workdir-20260529.md` | + --- ## 未完成但仍属本分支收尾 以下项目属于本分支收尾工作： -- [ ] Smoke / manual validation +- [x] Smoke / manual validation — `local-agent` 与 Claude Code MVP 已通过本地 WebUI smoke - [ ] Docs final QA -- [ ] 也许需要 minimal official runner adaptation（如果当前分支需要） +- [ ] Claude Code runner 文档、安装和 marketplace 发布准备 --- @@ -101,6 +113,9 @@ | BindingResolver persistence UI | 其他模块 | 绑定配置的持久化 UI | | Event router integration | event branch | 与 BindingResolver 集成 | | Scheduler / background event source | 其他模块 | 定时任务、后台事件源 | +| Security release hardening | 后续 release gate | 路径隔离、权限边界、secret、MCP/skill 投影策略、资源配额、审计 | +| Codex / Kimi runner 全量接入 | 后续 runner 插件工作 | 当前只验证 Claude Code MVP 形态，不扩大 scope | +| Issue-centric 产品模型 / 异步队列 / workflow engine | 后续产品架构 | 不属于当前 agent-runner plugin 协议闭环 | --- @@ -118,6 +133,7 @@ - [ ] EBA 完整集成 — EventGateway、event subscription、event notification 由其他分支实现 - [ ] 平台 API 动作执行 — `action.requested` 结果类型存在但未执行 +- [ ] 安全发布级 hardening — 作为生产默认启用前的 release gate，不阻塞当前协议闭环 --- @@ -128,6 +144,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 | +| 2026-05-29 | 本地 `local-agent` 与 `claude-code-agent` 通过 WebUI smoke；Claude Code runner 验证 external harness context 投影和 host-owned resume state | --- @@ -135,5 +152,7 @@ - [README.md](./README.md) — 总体设计 - [PHASE1_QA_ACCEPTANCE_MATRIX.md](./PHASE1_QA_ACCEPTANCE_MATRIX.md) — Phase 1 agent QA 验收矩阵 +- [PHASE1_QA_REPORT_2026-05-29.md](./PHASE1_QA_REPORT_2026-05-29.md) — 2026-05-29 本地 smoke 验收记录 - [OFFICIAL_RUNNER_PLUGINS.md](./OFFICIAL_RUNNER_PLUGINS.md) — 官方插件仓库计划 +- [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) — 安全发布级 hardening 后续门槛 - [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) — 具体实施细节 diff --git a/docs/agent-runner-pluginization/PROTOCOL_V1.md b/docs/agent-runner-pluginization/PROTOCOL_V1.md index 0b6f5341..09dea23c 100644 --- a/docs/agent-runner-pluginization/PROTOCOL_V1.md +++ b/docs/agent-runner-pluginization/PROTOCOL_V1.md @@ -15,6 +15,7 @@ - ✅ Proxy 覆盖 model、tool、knowledge、state/storage - ✅ History / Event / Artifact / State API 已落地 - ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地 +- ✅ `local-agent` 与 Claude Code runner 已通过本地 WebUI smoke，验证 host-infra runner 与外部 harness runner 共享同一协议路径 ## 1. 协议目标 @@ -31,6 +32,7 @@ Protocol v1 不定义： - AgentRunner 内部如何组装 prompt、压缩历史、管理 memory。 - 官方 local-agent 的具体实现。 - Pipeline 的长期配置模型。 +- 发布级安全 hardening 的完整实现；当前只定义 Host 侧资源、权限、状态和审计边界，release gate 见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 ## 2. 参与方 @@ -44,6 +46,8 @@ Protocol v1 不定义： `AgentBinding` 只影响 Host 构造出的 `ctx.config`、`ctx.resources`、`ctx.context` 和 `ctx.delivery`。SDK 不需要知道 binding 的持久化形态。 +外部 harness runner（Claude Code、Codex、Kimi Code 等）仍然是 `AgentRunner`。Protocol v1 只要求它们消费 event-first `AgentRunContext`、返回 `AgentRunResult`，并通过 Host 授权的 state/storage/artifact APIs 保存跨轮次指针。它们内部可以继续使用自己的 session、tool loop、MCP、上下文压缩和权限模型。 + ## 3. Discovery 协议 ### 3.1 LIST_AGENT_RUNNERS @@ -630,6 +634,15 @@ Protocol v1 的安全边界在 Host： - 大 payload 必须 artifact 化。 - Host 必须记录 run_id、runner_id、action、resource、scope、result。 +对外部 harness runner，边界进一步拆分为： + +- Host 在调用前完成 binding/resource policy 裁剪、路径策略、secret 过滤和审计记录。 +- Runner plugin 把授权后的 context/resource projection 适配为目标 harness 的 context 文件、MCP 配置、skill 目录、环境变量或 CLI 参数。 +- Claude Code / Codex / Kimi Code 等外部 harness 的 native permission mode、allowed/disallowed tools 和 sandbox 只是额外执行约束，不能替代 Host 侧授权。 +- 外部 session id、working directory、checkpoint 等跨轮次指针应作为小型 JSON state 保存，例如 `external.session_id`、`external.working_directory`。 + +完整路径隔离、MCP allowlist、secret redaction、配额、workspace 清理和发布级安全测试不属于当前 Protocol v1 smoke 闭环，详见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md)。 + Host 不负责业务编排： - 不拼接全量历史。 @@ -675,6 +688,7 @@ Protocol v1 已在当前分支完成： - ✅ Proxy 至少覆盖 model、tool、knowledge、state/storage - ✅ History / event / artifact API 已落地 - ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地 +- ✅ 外部 harness runner 最小 smoke 已落地：Claude Code runner 能消费 event-first context、返回消息、写回 `external.session_id` / `external.working_directory` ## 13. 开放问题 @@ -684,3 +698,4 @@ Protocol v1 已在当前分支完成： - State 与 Storage 的边界是否需要更强类型。 - `platform_api` action 的审批模型如何表达。 - 多 runner 并发处理同一 event 时，result delivery 的冲突策略如何定义。 +- Host 侧 scoped MCP / skill / workspace projection 是否需要从 runner config 上移为一等 resource projection API。 diff --git a/docs/agent-runner-pluginization/README.md b/docs/agent-runner-pluginization/README.md index 9b5cf632..e8b3604c 100644 --- a/docs/agent-runner-pluginization/README.md +++ b/docs/agent-runner-pluginization/README.md @@ -53,6 +53,9 @@ Pipeline path 已获得 event-first host capabilities： | [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 验收矩阵。它验证现有分支的兼容性，不代表最终架构边界。 | +| [SECURITY_HARDENING.md](./SECURITY_HARDENING.md) | 安全发布级 hardening 的后续发布门槛：路径隔离、权限边界、secret、资源配额、MCP / skill 投影和审计。 | +| [PROGRESS.md](./PROGRESS.md) | 当前实现进度、已验收能力、未完成收尾和非本分支范围。 | +| [PHASE1_QA_REPORT_2026-05-29.md](./PHASE1_QA_REPORT_2026-05-29.md) | 2026-05-29 本地 local-agent 与 Claude Code runner 的 UI E2E / smoke 验收记录。 | ## 工作拆分 diff --git a/docs/agent-runner-pluginization/SECURITY_HARDENING.md b/docs/agent-runner-pluginization/SECURITY_HARDENING.md new file mode 100644 index 00000000..0f1319e0 --- /dev/null +++ b/docs/agent-runner-pluginization/SECURITY_HARDENING.md @@ -0,0 +1,73 @@ +# Agent Runner Security Hardening + +本文档记录 agent-runner 插件化进入生产发布前需要补齐的安全与稳定加固项。 + +## 状态 + +**当前结论：暂不塞进本阶段 agent-runner plugin 协议闭环。** + +本阶段目标是验证 LangBot 可以通过统一的 `run(event, binding)` 协议接入 `local-agent` 与外部 harness runner（如 Claude Code runner），并能传递事件、上下文、资源句柄、状态和结果流。 + +安全发布级 hardening 是后续 release gate，不应阻塞当前协议闭环，但必须作为进入生产默认启用前的验收条件。 + +## 责任边界 + +### LangBot Host 负责 + +- 资源授权：决定某个 `run_id` / binding 可以访问哪些模型、RAG、MCP、skill、artifact、history、state。 +- 资源投影：只把授权后的资源句柄、配置片段或上下文文件传给 runner。 +- 路径策略：限制 workspace / context file / artifact 的允许路径和清理策略。 +- Secret 策略：过滤环境变量、配置、日志和 transcript 中的 secret。 +- 运行约束：配置超时、轮次、并发、配额、输出大小和取消路径。 +- 审计记录：记录事件、绑定、资源授权、runner 调用、外部 harness session id、关键错误和结果摘要。 + +### Runner Plugin 负责 + +- 遵守 LangBot 下发的 binding config、授权资源和运行约束。 +- 将 LangBot 资源投影成目标 runner 可消费的形式，例如 context 文件、MCP 配置、环境变量或 CLI 参数。 +- 不把长期状态保存在插件实例内；需要跨轮次保存的外部 session id / working directory 等状态应写入 host-owned state。 +- 对外部进程做最小必要封装，包括命令参数构造、超时、取消、输出解析和错误映射。 + +### 外部 Harness 负责 + +Claude Code、Codex、Kimi Code 等外部 harness 可以继续使用自身的权限模型、工具 allow / deny 规则、MCP 加载策略、session/resume 机制和沙箱能力。 + +但外部 harness 不是 LangBot 的唯一安全边界。LangBot 仍必须在调用前完成资源授权、路径限制、secret 过滤和审计记录。 + +## 当前 MVP 可接受边界 + +当前阶段可以接受以下前提： + +- 由可信管理员配置 runner binding。 +- 工作目录和 context 输出目录为显式配置或 host 生成路径。 +- 外部 runner 默认使用保守权限，例如 plan / no-write 模式或禁用高风险工具。 +- 通过 timeout、max turns、输出长度和进程取消降低失控风险。 +- 通过 host-owned state 保存 `external.session_id`、`external.working_directory` 等 resume 所需指针。 + +这些前提足够做本地 E2E 与协议验收，不等同于生产发布完成。 + +## Release Gate Checklist + +进入生产默认启用前，需要补齐： + +- Path isolation：workspace allowlist、路径规范化、防止 `..` 逃逸、context / artifact 清理。 +- Permission boundary：runner 能力声明、binding 级资源授权、run 级权限校验。 +- Secret handling：环境变量白名单、配置脱敏、日志和 transcript redaction。 +- MCP policy：MCP server allowlist、scoped token、tool allow / deny、危险工具审计。 +- Skill projection policy：skill 来源验证、只读投影、版本和摘要记录。 +- Process isolation：进程组管理、取消、超时、CPU / 内存 / 输出配额。 +- State lifecycle：session id、workspace、artifact 的过期、清理、迁移和审计。 +- Audit first-class：事件、资源授权、外部命令、session id、结果摘要可追踪。 +- UI / Admin control：管理员能看到 runner 权限、风险提示、资源绑定和禁用入口。 +- Test matrix：路径逃逸、secret 泄漏、权限拒绝、timeout、取消、MCP deny、resume、cleanup、audit 完整性。 + +## 非当前范围 + +以下内容不属于本阶段协议闭环： + +- 完整异步队列与 issue-centric 产品模型。 +- 复杂 workflow engine。 +- Codex / Kimi runner 全量接入。 +- EBA 分支完整迁移和联调。 +- 发布级安全 hardening 的完整实现。 +