AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(runtime): implement Generic ACP and OpenCode core conformance

Offen
#438 4 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
TypeScript
Sterne
0
Forks
0
Ø Merge
8 Std. 51 Min.
Gemergte PRs (30 T.)
99

Beschreibung

> 由 #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 上线。

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.