docs(agent-runner): update pluginization design status

2026-06-02 12:05:54 +00:00 · 2026-05-29 21:03:21 +08:00
parent 9330a684fe
commit 056e62aa03
11 changed files with 340 additions and 12 deletions
--- 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/<name>/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。
--- 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

 **其他分支负责（非本分支范围）**：

--- 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。

 **后续工作（其他分支）**：

--- 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. 高层架构

--- 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/<name>/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 保持一致；代码结构不需要相同。
--- 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)。
--- a/docs/agent-runner-pluginization/PHASE1_QA_REPORT_2026-05-29.md
+++ 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。
+
--- 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) — 具体实施细节
--- 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。
--- 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 验收记录。 |

 ## 工作拆分

--- a/docs/agent-runner-pluginization/SECURITY_HARDENING.md
+++ 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 的完整实现。
+