docs(agent-runner): align runner protocol boundaries

This commit is contained in:
huanghuoguoguo
2026-05-29 22:41:10 +08:00
parent 6afe8b67f8
commit 93febbb342
15 changed files with 504 additions and 399 deletions

View File

@@ -11,7 +11,7 @@
- ✅ Host 支持 `run_id` session authorization
- ✅ Host 能从当前 Pipeline 入口生成 event-first context
-`messages` 降级为 optional bootstrap
-`max-round` 不出现在协议实体中(只在 Pipeline adapter 中处理)
-`max-round` 不出现在协议实体中;类似历史窗口参数若存在,应来自 runner manifest/config schema并作为 binding config 进入 `ctx.config`
- ✅ Proxy 覆盖 model、tool、knowledge、state/storage
- ✅ History / Event / Artifact / State API 已落地
- ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地
@@ -147,7 +147,7 @@ Host 使用该声明决定是否给 runner inline bootstrap history。默认原
- Host 默认只 inline 当前 event / input 和 context handles。
- Runner 拥有 working context assembly。
- Runner 可在授权后通过 Host history / event / artifact / state APIs 拉取更多上下文。
- `max-round` 不属于 Protocol v1 字段。
- `max-round` 不属于 Protocol v1 字段,也不属于 Pipeline / Host 通用语义
## 4. Run 协议
@@ -344,7 +344,7 @@ class BootstrapContext(BaseModel):
- `bootstrap.messages` 是 host convenience不是协议核心。
- 自管 context runner 默认应收到空 bootstrap 或只收到当前 event。
- Host 不应为了”帮 agent 更聪明”而自动拼接完整 transcript。
- Pipeline adapter 的 `max-round` 配置只影响 adapter 如何生成 `bootstrap.messages`,不能成为 Protocol v1 字段
- 类似历史窗口策略应由具体 runner 的 binding config 表达new/official runners 不应依赖 Pipeline adapter 下发的 bootstrap window
### 4.10 RuntimeContext
@@ -638,7 +638,7 @@ Protocol v1 的安全边界在 Host
- 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 侧授权。
- Claude Code / Codex / Kimi Code 等外部 harness 的 native permission mode、allowed/disallowed tools 和执行隔离策略只是额外执行约束,不能替代 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)。
@@ -662,15 +662,15 @@ Pipeline 是当前入口 adapter不是协议中心。
-`PipelineAdapter.query_to_event(query)` — 从 `Query` 构造 `AgentEventEnvelope`
-`PipelineAdapter.pipeline_config_to_binding(query, runner_id)` — 从 Pipeline config 构造临时 AgentBinding
-`run_from_query()` 委托到 `run(event, binding)`
-`max-round` 在 Pipeline adapter 中处理,不进入协议实体
-runner-specific config 从 Pipeline 当前绑定配置透传到 `AgentBinding.runner_config` / `ctx.config`
- ✅ Query-only 字段放入 `adapter` context
Pipeline adapter 负责:
-`Query` 构造 `AgentEventContext`
- 从 Pipeline config 构造临时 AgentBinding。
- runner config 构造 `ctx.config`
- `max-round` 转换为 `bootstrap` policy
-当前 runner binding config 构造 `ctx.config`
- 保留必要的 legacy adapter metadata但不定义历史窗口、prompt 组装或 agentic context 策略
- 将 Query-only 字段放入 `adapter`
Runner 不应长期依赖 `adapter`。新 runner 应只依赖 event-first context 和 Host APIs。
@@ -684,7 +684,7 @@ Protocol v1 已在当前分支完成:
- ✅ Host 支持 `run_id` session authorization
- ✅ Host 能从当前 Pipeline 入口生成 event-first context
-`messages` 降级为 optional bootstrap
-`max-round` 不出现在协议实体中
-`max-round` 不出现在协议实体中;类似参数属于具体 runner binding config
- ✅ Proxy 至少覆盖 model、tool、knowledge、state/storage
- ✅ History / event / artifact API 已落地
- ✅ EventLog / Transcript / ArtifactStore / PersistentStateStore 已落地