AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(runtime): implement Generic ACP and OpenCode core conformance
- Lenguaje dominante
- TypeScript
- Estrellas
- 0
- Forks
- 0
- Merge medio
- 8 h 51 min
- PR fusionados (30 d)
- 99
Descripción
> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI 容量、真实资源与评审窗口尚未确定,Start/Target 留空。
## Problem
M1 要求 OpenCode 标准模板。当前公共 RuntimeHost/RuntimeDriver、Fake 与 Codex 实现不能证明 OpenCode 的真实模型选择、Session/Turn 恢复、事件规范化和多用户隔离。#436/#471 当前仅提供 Codex/Responses 配置链路,尚未证明本模板实际模型协议与原生配置可用。本票交付 Generic ACP 核心 Driver 与真实文本/模型/恢复 conformance,为完整模板整装提供独立可验收的基础。
## Scope
- 在 `packages/agent-runtime` 实现固定的 Generic ACP Driver,复用现有 `RuntimeDriver`;`apps/agent-runtime-host` 只负责进程启动、装配与 HTTP/SSE。实现唯一 Generic ACP Driver,OpenCode 使用它;后续兼容自定义 Agent 复用同一边界,不增加 OpenCode 专用 ACP 分叉。本票不实施自定义镜像准入、身份入口或 UI。
- 按 #150 的复用约定,优先采用下列固定上游模块与回归场景;记录最终版本、文件/函数、采用方式、许可证/必要声明及本仓差异。静态绑定模板与 Driver、固定镜像 Digest,不增加插件发现或通用协议框架。
- 映射 submit、supplement、stop、status、lookup、replay、subscription 和 capability。原生 Session/Turn/request ID、协议帧与 vendor 类型不得越过 RuntimeHost。
- 消费 #436 及 #437 扩展后的 active 每选项配置;本票负责 OpenCode 实际使用的 provider/profile 验证和原生配置映射,沿用共同 Schema/投影/候选激活流程。精确应用 submit V2 的 `modelOptionId`/`reasoningLevel`,不在 Driver 重查目录、SecretRef 或 Platform 默认值,不静默换模型,保留 V1 兼容。
- 在 Agent PVC 持久保存必要的 Session/Turn、请求去重和事件游标映射。重启恢复原 Session;恢复失败只隔离对应 Conversation,不静默新建 Session。
- 将文本、状态、工具摘要、完成和错误规范化为既有 Schema;原生文件引用可做协议映射,但公共 ObjectStorage 和端到端文件传输不属于本票。日志与错误不记录凭证、敏感 endpoint、原生帧、供应商响应正文或普通会话正文。
- 复用现有公共 conformance 的断言和 fixture 工厂,按需做最小抽取,不复制三份 Codex 测试或新建测试框架;协议特有回归优先采用上游场景。覆盖重复/冲突命令、接受结果不确定、繁忙、停止竞态、重放和进程退出;真实原生验证不能由 Fake 或旧版本报告替代。
- 核心必需操作不能用 unsupported 代替交付。补充指令等可选能力仅在 Registry 声明和 conformance 均通过时启用。文件与 Connection 对产品入口保持不可用,待 #150 后续完整整装票验收;不削减正式 M1 必交能力。
### 实施起点与 ACP 差异
- 官方 [ACP TypeScript SDK](https://github.com/agentclientprotocol/typescript-sdk/blob/c88bb0da97fe1059d4e3032df2724bf39c96f3d2/src/acp.ts#L3398-L3436) 负责 wire/framing/correlation;优先复用 Paseo [ACPAgentClient/ACPAgentSession](https://github.com/getpaseo/paseo/blob/d1b705a0cd91617a5707fae25d80cb0be3057950/packages/server/src/server/agent/providers/acp-agent.ts) 的 initialize/new/load/resume、transport 与退出清理,以及 Open Design [模型解析函数](https://github.com/nexu-io/open-design/blob/ad9078b87c2d08e537ca3e041c46c124e7380c9c/apps/daemon/src/agent-protocol/acp/models.ts)。替换产品自动授权、默认模型回退与内存 Turn 状态,不另写 OpenCode Native 路线。
- `session/prompt` 响应发生在 Turn 结束,`cancel` 是通知;发送成功、内存 Turn ID 或 `loadSession` 成功都不证明旧请求的接受/终态。复用 Host 既有 durable request/fence/WAL/unknown 契约,按原生可观测证据收敛状态;无法确认时不盲重投。
- 建立未发送、已发送未确认、流式执行、结束未落盘、cancel 竞态、进程/Pod 重启的接受与恢复矩阵。unknown 是不确定状态,不是核心恢复 conformance 的替代;若固定 OpenCode 无法满足必需场景,先报告具体缺口并对齐 HLD/Spec,不能以 unsupported、伪造终态或静默替换 Session 通过。新 Session 仅随用户明确新建 Conversation 创建。
- 明确平台 `modelOptionId` 到 OpenCode 原生 `providerID/modelID` 及必要 variant 的映射,来源为 [OpenCode config-option.ts](https://github.com/anomalyco/opencode/blob/95daf90670b7c039c436c85537da5fbfe2205b41/packages/opencode/src/acp/config-option.ts#L118-L160)。不因原生标识含 `/` 就放宽所有平台 ID;验证模型列表变化、失效选择和实际 endpoint/credential 绑定。
- 本票拥有同一 ACP Driver 内部的原生模型发现、当前选择和设置映射及协议测试,供 #444 复用;#444 拥有必要的 Host/Worker/Web 契约对齐、列表呈现与提交前复验。Manifest 布尔 capability 不代替该链路;本票不实现自定义镜像准入、身份入口或 UI。
## Acceptance criteria
- [ ] **AC-1:** 固定版本的 Generic ACP 实现既有 Driver 核心操作与静态模板装配;原生 ID、对象、协议帧和客户端类型不暴露给 Worker、Web 或公共 wire contract。
- [ ] **AC-2:** submit V2 在每次原生执行入口应用准确的 active model option/reasoning;缺失、失效、不支持或冲突的选择在 Turn 副作用前稳定拒绝,不使用其他选项或进程默认值。获准的有效选择必须真实成功。平台选项到原生 provider/model/variant 的确定映射经真实 OpenCode 验证;目录验证与原生实际协议一致。
- [ ] **AC-3:** 相同请求重放一个持久结果,变更请求稳定冲突;accepted/unknown/busy/stop 均有明确状态,不重复启动 Turn。可选补充指令未通过持久去重 conformance 时不启用。
- [ ] **AC-4:** Host/原生进程和 Pod 重启后恢复原 Session、Turn 状态与事件游标;损坏或不可恢复状态只使该 Conversation 不可用,保留历史且不静默替换 Session;其他 Conversation 继续工作。已确认状态有原生证据;仅恢复 Session 或全部返回 unknown 不算该项通过,不确定请求不得自动重投。
- [ ] **AC-5:** 规范化事件保持稳定排序、去重、重放与终态;未知、畸形和迟到消息按既有契约处理。日志、错误、审计和证据均不暴露原始凭证、敏感 endpoint、供应商正文或普通会话正文。
- [ ] **AC-6:** 自动化负向测试覆盖跨 Agent/Conversation/generation、旧 fence 和伪造原生引用;真实原生双用户验证包含各自有效正向对照、会话/工作区/个人记忆/上下文隔离、并行使用和重启后隔离,不能只凭 Host 拒绝或未观察到泄漏判断通过。
- [ ] **AC-7:** 固定模板镜像采用不可变来源和 Digest,以 non-root、只读根文件系统及明确可写挂载运行;通过 #405 的依赖与镜像政策,不降低门禁或自批例外。
- [ ] **AC-8:** 公共及专属 conformance、真实 OpenCode 文本/模型/恢复/隔离测试通过,证据绑定干净 source SHA、实际镜像 Digest、配置版本、原生版本与实际模型。文件和 Connection 明确未验收且产品入口不可用,不宣称完整模板上线。
- [ ] **AC-9:** 同一 Generic ACP Driver 的模型发现、当前选择、设置及失效/不支持行为有协议测试;#444 能复用该原生映射而无需另一套 ACP Driver。能力声明不单独证明模型选择链路完成。
## Validation
- 运行协议 framing/correlation、模型选择、状态/lookup、replay/subscription、停止、崩溃窗口、畸形/迟到通知、脱敏和跨绑定负向测试。
- 对真实 Driver 运行现有共享 conformance;分别验证核心操作、可选能力和 V1/V2 兼容,不按协议名称推断能力。
- 构建并检查固定镜像、权限、挂载与扫描报告;在获准隔离环境用真实原生 Runtime、获准模型和当前镜像完成 AC-4/AC-6/AC-8。资源未提供时保持未验收,不以合成结果替代。
- 执行 `AGENTS.md` 完整仓库验证序列与 current-head Standards/Spec Review;只保留脱敏版本、命令、结果和证据引用。
- 按上述矩阵逐项验证 `prompt` 响应时机、cancel 通知、Session 恢复与旧 Turn 可观测性,保留未解决核心缺口;覆盖 provider/model/variant 映射及原生模型列表变化,禁止默认回退、盲重投和自动许可。
## Blocked by
- #405
- #436
- #437
## Authority
- Agent Platform PRD §§4、7、8、12、14;工程 Spec §§10.7、11、17、19;Runtime HLD §§3–8、11。正式依据为 `main@f0e8aa58ca90dec2583459818c1167781979235f`。
- #181 的公共 RuntimeHost/Driver、#376 的 submit V2 与 #436 的已交付配置基础保持唯一归属;#437 负责 HLD 复用条款和首个非 Responses 共享配置扩展,本票在其共同契约上接入实际原生协议。
- #165 只将文件从首个 Pilot 延后,完整 M1 文件能力仍必交;#432 对齐前不实施 Connection 路线。#150 继续拥有文件、Connection 和完整模板整装验收的毕业责任。本票完成不等于完整模板或 M1 上线。
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Evaluación
Este issue todavía no se ha evaluado.