docs(agent-runner): sync EBA and harness resource docs

This commit is contained in:
huanghuoguoguo
2026-06-09 10:04:49 +08:00
parent 466023b471
commit f92029e245
10 changed files with 66 additions and 61 deletions

View File

@@ -88,7 +88,7 @@ execution:
### 5.1 Native Execution / Skills 后续接入
本阶段不把 sandbox/skills 做成 AgentRunner 协议字段。后续 sandbox/skills 分支合并后命令执行、文件操作、skill、MCP managed process 应先由 Host 封装成 scoped tools再通过 `ctx.resources.tools` 暴露给 runner。这让 local-agent 只消费授权后的 Host 基础设施,而不是直接持有宿主机执行能力。
本阶段不把 sandbox/skills 做成 AgentRunner 协议字段。后续 sandbox/skills 分支合并后命令执行、文件操作、skill、MCP managed process 应先由 Host / sandbox 封装成 scoped tools再通过 `ctx.resources.tools` 和 SDK runtime 转发暴露给 runner。这让 local-agent 只消费授权后的 Host 基础设施,而不是直接持有宿主机执行能力。
## 6. 外部 runner 插件要求
@@ -96,7 +96,7 @@ execution:
### 6.1 Code-agent harness runner
Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/工具 loop 执行,可以依赖自己的 harness但仍必须遵守 Host 边界:输入来自 `ctx.event` / `ctx.input`,不依赖 Pipeline 私有 `Query`;授权资源投影为 harness 可读的 context 文件、MCP 配置、skill 目录、环境变量或 CLI 参数(投影形态见 AGENT_CONTEXT_PROTOCOL §4.5);外部 session id / workspace / checkpoint 写入 Host state 或 plugin storage插件实例边界见 PROTOCOL_V1 §13CLI / subprocess runner 必须处理 timeout、取消、空输出、非零退出和 stderr 映射harness 的 permission mode / allow-deny / MCP 配置只是一层执行约束Host 仍负责调用前的资源授权、路径策略、secret 过滤和审计(发布级要求见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md))。
Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/工具 loop 执行,可以依赖自己的 harness但仍必须遵守 Host 边界:输入来自 `ctx.event` / `ctx.input`,不依赖 Pipeline 私有 `Query`;授权资源投影为 harness 可读的 context、资源句柄、SDK-owned MCP bridge 配置、受限环境变量或 CLI 参数(投影形态见 AGENT_CONTEXT_PROTOCOL §4.5访问任何 LangBot 资源都必须通过 SDK runtime / `AgentRunAPIProxy` / SDK-owned MCP bridge 转发,不能由 harness native tools 直接访问;外部 session id / workspace / checkpoint 写入 Host state 或 plugin storage插件实例边界见 PROTOCOL_V1 §13CLI / subprocess runner 必须处理 timeout、取消、空输出、非零退出和 stderr 映射harness 的 permission mode / allow-deny / MCP 配置只是一层执行约束Host 仍负责调用前的资源授权、路径策略、secret 过滤和审计(发布级要求见 [SECURITY_HARDENING.md](./SECURITY_HARDENING.md))。
实现结构应把 provider-native output 解析与 LangBot result stream 组装分开Claude stream-json、Codex JSONL、Kimi / OpenCode 事件等只在 runner adapter 内解析,输出统一归一为 `AgentRunResult``message.completed` / `message.delta``state.updated``artifact.created``run.completed` / `run.failed`)。未知 native event 不应导致 run 崩溃;应记录诊断 metadata 或 warning。新增 harness 时优先补 native fixture -> `AgentRunResult` 的转换测试,再接 WebUI smoke。
@@ -104,12 +104,12 @@ Claude Code、Codex、Kimi Code 这类 runner 不一定通过 LangBot 的模型/
### 6.2 SDK-owned LangBot MCP bridge
外部 harness 不能直接持有进程内的 `plugin_runtime_handler`因此不能像 `local-agent` 一样直接调用 `AgentRunAPIProxy`。当前轻量方案是由 SDK 提供一层 per-run MCP bridge
外部 harness 不能直接持有进程内的 `plugin_runtime_handler`也不能用自己的 native tools 直接访问 LangBot 资源。当前轻量方案是由 SDK 提供一层 per-run MCP bridge把 harness 的工具请求转回 SDK runtime / Host API
- `AgentRunner.create_external_mcp_bridge(ctx)` 是 runner 父类入口。
- Bridge 由 `AgentRunAPIProxy``AgentRunContext` 构造,生命周期只覆盖当前 run。
- Bridge 暴露 SDK 中显式注解的 `AgentRunExternalTools`,而不是导出全部 SDK actionMCP tool schema 由注解和 Pydantic args model 生成。
- stdio MCP proxy 只把外部 harness 的 MCP 调用转发回当前 run 的本地 bridgerun 结束后 bridge 关闭。
- stdio MCP proxy 只把外部 harness 的 MCP 调用转发回当前 run 的本地 bridgerun 结束后 bridge 关闭。所有 LangBot 资源访问仍由 Host 按 `run_id`、caller identity 和授权快照校验。
第一批工具保持很小当前事件快照、history page、knowledge retrieve、authorized tool call。新增工具必须先进入 SDK-owned annotated surface再由 MCP adapter 自动投影。
@@ -125,7 +125,7 @@ workspace lifecycle、secret projection、团队级 audit 或 runtime sidecar
- 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`可把 `skills-json` 投影到 `.claude/skills/<name>/SKILL.md`;可把 `mcp-config-json` 写成每次 run 的 MCP config 经 `--mcp-config` / `--strict-mcp-config` 传入;可通过 `enable-langbot-mcp=true` 启用 SDK-owned per-run LangBot MCP bridge。
- 投影:写入 `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.2 Codex runner