diff --git a/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md b/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md index c6769709..ccffc21c 100644 --- a/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md +++ b/docs/agent-runner-pluginization/RUNTIME_CONTROL_PLANE_V2.md @@ -1,228 +1,505 @@ -# Agent Runtime Control Plane V2 +# Agent Platform / Runtime Control Plane Decision Note -本文档记录后续 Agent Platform / runtime 管控面的设计方向。它是当前讨论中的 **v2 文档**,但这里的 v2 指 Host capability layer / runtime control plane,不是 `AgentRunner Protocol v2`,也不属于当前 AgentRunner Protocol v1 插件化主线的交付范围。 +本文档记录 AgentRunner 插件化之后,LangBot 如何继续演进成 Agent Platform 基础设施层。这里讨论的是 Host capability layer,不是 `AgentRunner Protocol v2`,也不是把某个具体 Agent Platform 产品写进 LangBot core。 -> **future design note**。协议数据结构见 [PROTOCOL_V1.md](./PROTOCOL_V1.md),实现进度见 [PROGRESS.md](./PROGRESS.md)。本文只讲 v2 管控面方向,不重抄 schema。 -> 与当前 runner 外化分支、EBA 和 Agent Platform 的边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。 +> 本文是当前决策版。协议数据结构仍以 [PROTOCOL_V1.md](./PROTOCOL_V1.md) 为准;实现进度见 [PROGRESS.md](./PROGRESS.md);扩展边界见 [EXTENSION_SCOPE_MATRIX.md](./EXTENSION_SCOPE_MATRIX.md)。 -## 1. 结论 +## 1. 当前决策 -当前主线应继续收口 AgentRunner v1: +LangBot 后续定位应更像 **Agent Host / infrastructure provider / transfer layer**,而不是把某个完整 Agent Platform 产品固化进 core。 + +结论: + +- **Agent Platform 产品形态做成插件**。插件负责 agent 管理、策略、业务队列、UI、编排、多 agent 协作和产品体验。 +- **Agent Platform 所需的基础事实源做进 Host**。Host 保存 event、run、result、artifact、state、transcript、权限快照、审计和通用控制状态。 +- **不在第一阶段把 runtime registry / daemon worker 管控做成 Host 必选能力**。远程 harness / daemon 可以先由 AgentRunner 插件和 SDK remote layer 自己维护连接、心跳和本地执行。 +- **不把业务调度写进 Host**。Host 提供通用 run/result/control primitives,Platform 插件决定哪些事件触发哪些 agent、如何排队、如何分配、是否 fan-out。 + +推荐分层: ```text -message/event -> binding -> runner.run(ctx) -> result stream +LangBot Host + Event / Agent / Binding / Run / RunEvent / Artifact / State / Transcript + Authorization / audit / delivery / result persistence / control primitives + +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 + Executes and converts provider-native events to AgentRunResult ``` -Runtime Control Plane v2 在 Host 侧新增 runtime control plane: +## 2. Platform 与非 Platform 的区别 + +当前 LangBot 已经具备 Agent Host 的核心特征: + +- 抹平不同 AgentRunner。 +- 从 IM / Pipeline 入口触发 runner。 +- 有 event-first context 方向。 +- 有 Host-owned EventLog / Transcript / Artifact / State 的一部分。 +- 有 runner config 下发和 run-scoped authorization。 + +这还不是完整 Agent Platform。完整 Platform 至少还需要: + +- 可管理的 agent 资产:agent profile、binding、resource policy、runner config、可用状态。 +- 可观察的执行生命周期:run status、result stream、失败原因、artifact、审计、回放。 +- 可运营的控制面:取消、重试、排队、并发、超时、恢复、诊断。 +- 可产品化的调度体验:事件订阅、路由策略、任务板、多 agent 协作、项目/工作区视图。 + +因此,区别不只是“有没有调度”,而是是否具备: ```text -event -> task -> runtime selection -> daemon claim -> execute -> progress/audit/result +managed agent assets + observable run lifecycle + operational run control ``` -在 Runtime Control Plane v2 之上,可以构建独立的 agent 管控面插件。插件负责 UI、策略和编排体验;runtime、task、heartbeat、audit 的事实源必须属于 LangBot Host,而不是插件私有 storage。 +Host 负责这些能力的通用事实源和安全边界;Platform 插件负责把它们组装成具体产品。 -## 2. 不影响 v1 主线 +## 3. 基础概念 -v2 不应改变 AgentRunner v1 的基本契约: +### 3.1 Event -- 现有 `local-agent`、Dify、n8n、Coze 等 runner 仍可按 v1 直接执行。 -- 当前 Claude Code / Codex MVP runner 可以继续作为本机 subprocess 开发路径。 -- Host v1 已有的 event-first context、resource authorization、history / event / artifact / state / storage pull APIs 继续保留。 -- Pipeline 仍只是当前入口 adapter,不参与 v2 runtime 管控面的设计中心。 - -v2 只是在 Host 上新增一层可选能力。需要管控面的 runner 或管理插件可以声明使用它;不需要的 runner 不受影响。 - -## 3. 当前 Host 能力与缺口 - -当前 Host 已经具备 v2 的基础设施底座: - -- `AgentEventEnvelope` / `AgentBinding` -- run-scoped resource authorization -- EventLog / Transcript / ArtifactStore / PersistentStateStore -- History / Event / Artifact / State / Storage pull APIs -- AgentRunner result stream 和受控错误回流 -- Agent/runner config 与 host-owned state - -这些能力足够支持一次 `runner.run(ctx)` 内的安全执行,但不足以承担完整 runtime 管控面。 - -v2 还需要 Host 新增: - -- runtime registry:runtime id、所属 workspace、所在机器、provider 能力、状态。 -- capability discovery:`claude` / `codex` / 其它 CLI 是否存在、版本、登录状态、执行隔离能力。 -- heartbeat / liveness:runtime 在线、忙闲、最后心跳、可用 slot。 -- task queue:enqueue、claim、start、progress、complete、fail、cancel。 -- workspace mapping:LangBot workspace / project 如何映射到 runtime 上的真实目录、仓库或挂载。 -- secret / env projection:按授权向 runtime 投影 token、代理、MCP 配置、技能和环境变量。 -- runtime audit:stdout、stderr、事件流、产物、失败原因、执行耗时、使用量。 -- control API / UI:选择 runtime、测试 runtime、查看状态、下线、取消任务、重试任务。 - -## 4. 角色边界 - -### 4.1 LangBot Host - -Host 是事实源和控制面内核: - -- 保存 runtime / task / heartbeat / audit 状态。 -- 做权限校验、资源裁剪、workspace 绑定和审计。 -- 决定任务是否可被某 runtime claim。 -- 将执行结果统一回写到 event / transcript / artifact / state。 - -Host 不应内置具体 agent CLI 的复杂业务逻辑,也不应把某个官方 runner 的特殊行为提升为通用协议。 - -### 4.2 Agent 管控面插件 - -管理插件是 v2 control plane 的产品化管理层: - -- 展示 runtime、agent、task、进度、失败、审计。 -- 提供策略配置,例如默认 runtime、provider 偏好、并发限制、重试策略。 -- 触发 runtime 测试、任务取消、任务重试、手动分配。 - -管理插件不应把 runtime/task 的事实源放进自己的 plugin storage。它应该调用 Host v2 API。 - -### 4.3 Runtime daemon / worker - -Runtime daemon 负责真实执行: - -- 在所在机器上检测 CLI 和版本。 -- 管理工作目录、仓库、挂载、临时文件和进程。 -- 从 Host claim 任务,执行后上报 progress / complete / fail。 -- 将 stdout / stderr / artifacts / session id 回流 Host。 - -Claude Code、Codex、OpenCode、Gemini CLI 等 provider 适配逻辑应主要落在 daemon / worker 或 provider adapter 中。 - -## 5. 部署形态 - -### 5.1 uv / local embedded - -用户用 `uv` 或源码直接启动 LangBot 时,LangBot 进程所在机器就是 runtime host。 - -这种模式下可以直接检测用户主机上的 `claude`、`codex` 等 CLI,也可以直接 subprocess 执行。它适合个人开发和本地 smoke,但不应作为团队级管控面的唯一形态。 - -### 5.2 Docker embedded - -用户用 Docker 启动 LangBot 时,runtime host 是容器,不是宿主机。 - -因此: - -- 只能检测容器内的 `claude`、`codex`。 -- 只能使用容器内的 HOME、PATH、凭据和挂载目录。 -- 如果镜像未安装 CLI,或未挂载认证文件 / workspace,CLI runner 会不可用。 - -Docker embedded 可以作为高级部署选项,但需要用户显式安装 CLI、挂载工作区和凭据。Host 不应假设 Docker 容器能自动访问宿主机 CLI。 - -### 5.3 Sidecar daemon - -推荐的 v2 形态是 sidecar daemon: +Event 表示“发生了什么”: ```text -LangBot Host (Docker or server) - <-> Runtime daemon on user host / worker host - -> claude / codex / other CLI +message.received +github.issue.opened +scheduler.tick +user.approved +system.webhook.received ``` -这种模式下,LangBot 可以跑在 Docker 内,runtime daemon 跑在宿主机或独立 worker 机器上。daemon 负责检测本机 CLI、持有本机凭据和工作区访问能力。 +EBA 负责把外部输入标准化成 event。Event 本身不是 queue,也不等同于一次 agent 执行。 -### 5.4 Remote runtime +### 3.2 Run -团队场景可以使用远端 runtime: +Run 表示“某个 agent / binding / runner 针对某个 event 的一次执行”。 -- 开发机、构建机、云主机或专用 worker。 -- 多个 workspace 可绑定不同 runtime。 -- Host 只通过 registry / task queue / heartbeat / audit 进行管理。 - -### 5.5 API-only agent - -Dify、n8n、Coze、DashScope 等 API 型 runner 不依赖本地 CLI。它们可以继续按 v1 直接执行,也可以在未来按需要接入 v2 task/audit。 - -## 6. 与 Claude Code / Codex MVP runner 的关系 - -当前 Claude Code / Codex runner 是 v1 runner: +Run 应由 Host 持久化,成为执行状态、结果、权限和审计的事实源: ```text -runner.run(ctx) -> subprocess("claude" / "codex") +run_id +event_id +agent_id / binding_id +runner_id +status +created_at / started_at / finished_at +error / failure_reason +delivery target +metadata ``` -它们适合验证 Host context 投影、state resume、result stream 和基础 CLI 调用,但有明确限制: +当前 `AgentRunSessionRegistry` 只保存 active run 的内存态授权信息,不足以支撑 Platform 的回放、审计、取消、重试和异步执行。 -- 命令只在 LangBot runtime host 上执行。 -- Docker 环境只能看到容器内 CLI。 -- 没有 runtime registry、heartbeat、task queue、cancel、workspace lifecycle。 -- 不提供发布级执行隔离、secret projection、团队级 audit。 +### 3.3 RunEvent / RunResult -v2 不需要删除这些 runner。它们可以继续作为 dev / MVP 路径存在。未来若接入管控面,可以增加 runtime-managed 执行模式: +RunEvent 是一次 run 过程中产生的结果事件流,对应 `AgentRunResult`: ```text -runner binding -> Host task -> runtime daemon -> provider CLI -> Host result +message.delta +message.completed +tool.call.started +tool.call.completed +artifact.created +state.updated +action.requested +run.completed +run.failed ``` -## 7. 最小 v2 API 草案 +Host 应保存这些事件,按 `run_id + sequence` 可回放。Transcript、Artifact、State 可以由这些 result event 触发写入现有 store。 -以下仅记录能力边界,不代表最终 API 命名。 +### 3.4 Queue -Runtime: +Queue 不是 EBA 的替代品。 -- `runtime.register` -- `runtime.heartbeat` -- `runtime.list` -- `runtime.get` -- `runtime.disable` -- `runtime.capabilities.report` -- `runtime.capabilities.probe` +EBA 负责产生 event;queue 负责处理“这个 event 对应的执行 work item 何时执行、谁来执行、如何取消/重试/恢复”。 -Task: +队列可以分两层: -- `task.enqueue` -- `task.claim` -- `task.start` -- `task.progress` -- `task.complete` -- `task.fail` -- `task.cancel` -- `task.retry` +- **业务队列**:由 Platform 插件管理,例如项目任务、优先级、agent team、workflow、人工审批。 +- **执行队列 / run queue**:可选 Host 原语,例如 queued / running / completed / failed / cancelled、claim lease、dispatch timeout、orphan recovery。 -Workspace: +第一阶段不要求 Host 内置完整执行队列。Platform 插件可以先管理业务队列,然后调用 Host 创建 run、保存 result。 -- `runtime.workspace.bind` -- `runtime.workspace.unbind` -- `runtime.workspace.resolve` +### 3.5 Runtime / Daemon -Audit / artifacts: +Runtime / daemon 表示执行位置或执行能力,例如某台机器上的 Claude Code / Codex CLI。 -- `task.log.append` -- `task.artifact.create` -- `task.events.page` +当前决策: -这些 API 应由 Host 提供,并受 workspace、runtime、binding、actor 和 plugin identity 约束。 +- Host 不在第一阶段维护完整 runtime registry。 +- AgentRunner 插件可以通过 SDK remote layer 与 daemon 保持连接、心跳和执行通道。 +- 外部 harness / agent 不应直接访问 LangBot Host。访问 LangBot 资源必须通过 daemon / AgentRunner plugin / SDK runtime / `AgentRunAPIProxy` / MCP bridge。 +- 如果后续多个插件都需要共享 runtime 状态,再把薄的 `RuntimeLease` / registry 下沉为 Host 通用能力。 -## 8. 管控面插件可以构建的能力 +## 4. Host 应新增的最小能力 -基于 v2 Host 能力,可以实现一个类似 Multica 的 agent 管控面插件。这里的“类似 Multica”只指产品形态:一个集中页面管理 agent profile、runtime 连接、任务队列、执行进度、失败诊断和审计视图;不是引入新的 runner 协议或把 runtime/task 事实源交给插件。 +第一阶段最重要的不是 daemon registry,而是让 Host 成为 run/result 的事实源。 -- runtime 列表、在线状态、CLI 能力、版本、认证状态。 -- agent profile 与 runtime/provider 绑定。 -- 任务看板、任务详情、进度流、失败原因、重试和取消。 -- workspace 到 runtime 目录 / 仓库的映射管理。 -- provider capability 测试,例如 Claude Code / Codex 是否可执行。 -- 审计视图:输入、输出、工具、artifact、stdout/stderr、session id。 -- 策略配置:并发、队列、默认 runtime、fallback runtime、权限模式。 +### 4.1 AgentRun Store -该插件应该是 Host v2 的消费者,而不是 Host v2 的替代品。 +新增持久 `AgentRun`: -## 9. 设计原则 +```text +id / run_id +event_id +agent_id +binding_id +runner_id +conversation_id / thread_id +workspace_id / bot_id +status +status_reason +created_at / started_at / finished_at / updated_at +deadline_at +cancel_requested_at +metadata_json +``` -- v1 先稳定,v2 可选叠加。 -- Host 保存事实源,插件提供管理体验。 -- Runtime daemon 执行具体 CLI 和本机资源访问。 -- Docker 不假设拥有宿主机 CLI;需要 sidecar 或显式挂载。 -- Pipeline 不进入 v2 控制面中心。 -- 直接 subprocess runner 可保留,但只作为 local/dev/MVP 路径。 -- 发布级能力必须经过 Host 权限、审计和资源边界。 +建议 status 至少包含: -## 10. 待定问题 +```text +created +running +completed +failed +cancelled +timeout +``` -- runtime daemon 与 Host 的认证模型:workspace token、device token、还是 scoped PAT。 -- task 与 AgentRunner binding 的映射关系:由 binding 直接 enqueue,还是由独立 task policy 决定。 -- runtime capability schema 的稳定字段:provider、version、login status、execution isolation、workspace access、slot。 -- secret projection 的边界:Host 存储、用户本机存储、或外部 secret manager。 -- Docker compose 是否提供官方 sidecar daemon 示例。 -- v2 UI 是核心前端的一部分,还是完全由管理插件提供。 +如果后续加执行队列,再引入: + +```text +queued +claimed +dispatching +``` + +### 4.2 AgentRunEvent Store + +新增持久 `AgentRunEvent`: + +```text +id +run_id +sequence +type +data_json +created_at +source +artifact_refs_json +metadata_json +``` + +约束: + +- 同一 `run_id` 内 `sequence` 单调递增。 +- append 必须幂等,支持远程 daemon / plugin 重试。 +- 未知 result type 可保存但 Host 只对已知类型执行副作用。 +- 大 payload 仍应转 artifact,不直接塞入 result event。 + +### 4.3 Run Control API + +Host 提供通用控制原语: + +```text +run.create +run.get +run.list +run.events.page +run.cancel +run.append_result +run.finalize +``` + +语义: + +- `run.create` 创建 Host-owned run 和授权快照。 +- `run.append_result` 只允许受信 SDK/runtime 路径调用,写入 `AgentRunEvent` 并触发 transcript/artifact/state/delivery 副作用。 +- `run.finalize` 关闭 run,更新 terminal status。 +- `run.cancel` 设置取消意图;同步 runner 通过 context/deadline 感知,远程 runner 通过插件/daemon 通道感知。 + +第一阶段可以只暴露给插件 runtime action,不一定先做公开 HTTP API。 + +### 4.4 Result Persistence In Orchestrator + +当前 `AgentRunOrchestrator.run()` 已经处理: + +```text +event -> binding -> context -> runner invocation -> result normalization +``` + +需要补齐: + +- run 开始时创建 `AgentRun`。 +- 每个 `AgentRunResult` 进入 `AgentRunEvent`。 +- `run.completed` / 正常 generator 结束时标记 completed。 +- `run.failed` / exception / timeout 标记 failed 或 timeout。 +- `state.updated`、`artifact.created`、transcript 写入继续走现有 journal,但应与 `AgentRunEvent` 有可追踪关系。 + +### 4.5 Authorization Snapshot + +异步或远程执行时,run 创建时必须固化授权快照: + +- runner identity +- binding identity +- caller plugin identity +- resource policy +- allowed tools/models/files/knowledge bases/storage scopes +- state scopes +- conversation/thread/workspace scope + +后续 append result、state API、artifact API、history API 都以这个 snapshot 校验,不重新扩大权限。 + +## 5. SDK 侧应新增的最小能力 + +SDK 不需要马上定义完整 daemon registry,但需要让插件和 runner 使用 Host run/result 能力。 + +### 5.1 Entities + +新增或补齐: + +```text +AgentRun +AgentRunStatus +AgentRunEvent +RunEventPage +RunCreateRequest / RunCreateResult +RunAppendResultRequest +``` + +这些是 Host control primitives,不替代 `AgentRunContext` / `AgentRunResult`。 + +### 5.2 Proxy Methods + +在 SDK proxy 中提供: + +```python +create_run(...) +get_run(run_id) +list_runs(...) +page_run_events(run_id, cursor=None, limit=...) +cancel_run(run_id) +append_run_result(run_id, result, sequence=None) +finalize_run(run_id, status, error=None) +``` + +访问边界: + +- 普通 AgentRunner 在同步 `run(ctx)` 内不一定需要直接调用这些 API;Host orchestrator 可自动记录。 +- Platform 插件可以创建/查询/取消 run。 +- AgentRunner 插件或 daemon bridge 可以 append/finalize 自己负责的 run。 +- 外部 harness 仍不能直接调用 Host;必须经 SDK runtime / proxy / bridge。 + +### 5.3 Plugin-Daemon Heartbeat + +远程 daemon 的初始心跳可以是 SDK / AgentRunner plugin 私有能力: + +```text +daemon <-> AgentRunner plugin / SDK remote layer <-> LangBot plugin runtime <-> Host +``` + +Host 第一阶段只需要知道: + +- 相关插件是否在线。 +- run 是否有 progress/result。 +- run 是否超时或取消。 + +如果后续需要跨插件共享 daemon 可用性,再把 heartbeat/registry 下沉为 Host 能力。 + +## 6. Platform 插件应负责什么 + +Agent Platform 插件可以负责: + +- 管理哪些 agent 可用。 +- 维护产品层 agent profile、项目、任务板、workflow、team。 +- 订阅 EBA event,决定哪些 event 触发哪些 agent。 +- 维护业务 queue:优先级、重试策略、人工审批、分配规则。 +- 选择 runner / runtime / daemon。 +- 调用 Host run API 创建、取消、查询执行。 +- 展示 run status、result stream、artifact、失败原因和审计。 + +Platform 插件不应负责: + +- 私有保存通用 run/result 事实源。 +- 绕过 Host 直接写 transcript/artifact/state。 +- 让外部 harness 直接访问 LangBot DB 或 Host 内部资源。 +- 把某个业务队列语义强塞进 AgentRunner Protocol v1。 + +## 7. 与 EBA 的关系 + +EBA 做好后,事件流可以进入两种路径。 + +直接执行路径: + +```text +EventGateway + -> EventRouter resolves AgentBinding + -> AgentRunOrchestrator.run(event, binding) + -> Host records AgentRun / AgentRunEvent + -> delivery +``` + +Platform 插件编排路径: + +```text +EventGateway + -> Platform plugin receives/subscribes event + -> plugin applies policy / business queue + -> plugin creates Host run + -> runner/plugin/daemon executes + -> Host records result and state + -> plugin displays / Host delivers +``` + +这两条路径共享 Host run/result/artifact/state 事实源。区别在于是否有 Platform 插件参与产品化调度和业务队列。 + +## 8. 与 AgentRunner Protocol v1 的关系 + +本设计不改变 v1 的 runner 可见合同: + +```text +AgentRunContext -> AgentRunner.run(ctx) -> AgentRunResult stream +``` + +必须保持: + +- `AgentRunContext` 不塞入 daemon/worker/pod 细节。 +- `AgentRunResult` 仍是 runner 输出的统一事件流。 +- 普通 runner 不需要知道 task queue / runtime registry。 +- 远程 harness 可以自管 session、tool loop、MCP、上下文压缩,但访问 LangBot 资源必须通过 SDK proxy / bridge。 +- Runtime-managed execution 是 placement / transport 选择,不是普通 runner 协议的强制概念。 + +## 9. 分阶段实施建议 + +### Phase 1: Run Ledger + +目标:Host 成为执行状态和结果事实源。 + +范围: + +- `AgentRun` 表。 +- `AgentRunEvent` 表。 +- Orchestrator 自动创建/更新 run。 +- Journal 持久化每个 `AgentRunResult`。 +- Run 查询和事件分页 API。 +- SDK entities + proxy 方法。 + +复杂度:中等。 + +预计改动: + +```text +Host: 12-20 个文件 +SDK: 4-8 个文件 +Tests: 8-15 个文件 +``` + +### Phase 2: Platform Plugin Queue On Host Run Primitives + +目标:Platform 插件管理业务 queue,Host 提供 run/result/cancel 原语。 + +范围: + +- `run.create` +- `run.cancel` +- `run.append_result` +- `run.finalize` +- result append 的 sequence/idempotency。 +- 受权限保护的远程 append/finalize。 +- Platform 插件可基于 Host run 构建任务板和调度体验。 + +复杂度:中等偏高。 + +预计改动: + +```text +Host: 20-35 个文件 +SDK: 8-14 个文件 +Tests: 15-25 个文件 +``` + +### Phase 3: Optional Host Execution Queue / Claim Lease + +目标:当多个插件重复实现 claim/cancel/retry/recovery 时,再下沉执行队列到 Host。 + +范围: + +- `queued/running/completed/failed/cancelled` 状态机扩展。 +- `claim_run` / `lease_until`。 +- dispatch timeout。 +- retry / orphan recovery。 +- cancel propagation。 +- 并发 claim 防重。 + +复杂度:高。 + +预计改动: + +```text +Host: 35-55 个文件 +SDK: 12-20 个文件 +Tests: 25-40 个文件 +``` + +### Phase 4: Optional Runtime Registry + +目标:当 Host 需要统一管理多个 daemon / worker 时,再引入 runtime registry。 + +范围: + +- runtime register / heartbeat / deregister。 +- capability report:provider、version、login status、workspace access、slot。 +- runtime online/offline。 +- runtime scoped auth。 +- runtime audit。 +- runtime gone recovery。 +- task wakeup / long polling / websocket。 +- 多 Host 实例下的 relay / distributed lock。 + +复杂度:很高。 + +预计改动: + +```text +Host: 55-80+ 个文件 +SDK: 18-30 个文件 +Tests: 40+ 个文件 +``` + +不建议现在直接进入此阶段。 + +## 10. 设计原则 + +- 先把 run/result 事实源做进 Host,再谈完整 runtime control plane。 +- Agent Platform 产品做插件;Host 做基础设施。 +- Host 不写业务调度策略,但要保存通用状态、结果、权限和审计。 +- EBA event 不是 queue;queue 是执行生命周期问题。 +- 业务 queue 可以先在 Platform 插件里;执行 queue 只有在复用需求明确后再下沉 Host。 +- Daemon registry 不应污染 AgentRunner Protocol v1。 +- 外部 harness 不直接访问 LangBot Host 或 DB。 +- 所有 LangBot 资源访问必须走 SDK runtime / `AgentRunAPIProxy` / scoped MCP bridge。 +- Docker / remote / local subprocess 只是 runtime placement,不是 runner 协议差异。 + +## 11. 非目标 + +当前阶段不做: + +- 完整 Multica 式 runtime registry。 +- Host 内置项目管理、任务板、agent team、workflow 产品逻辑。 +- 把 daemon heartbeat / worker liveness 放进 `AgentRunContext`。 +- 把业务 queue 定义为 AgentRunner Protocol 字段。 +- 让 Platform 插件私有保存 run/result 事实源。 +- 让外部 agent/harness 直连 Host 内部资源。 + +## 12. 待定问题 + +- Host 是否需要最小持久 `Agent` / `Binding` 模型,还是继续由 Pipeline / Platform 插件投影运行期 `AgentBinding`。 +- 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。 +- 何时把插件私有 daemon heartbeat 提升为 Host `RuntimeLease`。 +- 若未来 Host 做 claim lease,Platform 插件业务 queue 与 Host execution queue 如何避免双队列混乱。