AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(connection): publish Pilot browser catalog and invocation contracts
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Merge medio
- 8h 51m
- PR unite (30g)
- 99
Descrizione
## Problem
Connection 与 Web、Platform 和 Provider Adapter 无法独立实施,直到 Browser、Catalog、delegated consumer、Action schema、调用状态和稳定错误具备一套版本化 wire contract。
## Scope
- 在现有 contract toolchain 和已完成 delegated Execution Grant contract 上,定义 Connection Pilot 所需 Browser API、只读 Catalog API、delegated assertion consumer binding、ActionCall/Effect 状态和稳定错误 Schema。
- 保持 Zod 手写源、OpenAPI 3.1 和 JSON Schema 的既有单向生成与兼容门禁;不建立第二套 DTO。
- Catalog 只暴露 Provider/Action、immutable version、schema、effect、required scope 和发布状态,不暴露用户 Connection、Grant、Credential 或审计。
- 定义三项 GitHub Action 的输入输出契约、repository policy denial、`RESULT_PENDING`、`NEEDS_MANUAL_REVIEW`、`UNRESOLVED` 和 Provider revoke 状态。
- 稳定区分 Provider 已明确响应的失败与无法确认提交结果:已收到 GitHub HTTP 响应的非成功结果必须映射为脱敏、可审计的 `PROVIDER_FAILED`;只有传输中断导致是否提交不可知,或 Provider 已成功但 Connection 无法持久化终态时,才能进入 `RESULT_PENDING/UNCERTAIN`。
- 提供 Platform、Connection Web 和 Connection runtime 可复用的正负向 consumer tests/Fakes;不实现 Hono route、React 页面、数据库或 Provider 调用。
## Acceptance criteria
- [ ] **AC-1:** Browser、Catalog、delegated 和调用状态契约均有唯一版本、稳定 ID/correlation/error 语义及规范生成产物。
- [ ] **AC-2:** Catalog 契约不含 Principal、Connection、Grant、Credential 或可写授权字段,并能表达 immutable ActionVersion、effect、scope 和状态。
- [ ] **AC-3:** 三项 GitHub Action、repository denial、pending/manual/unresolved 和 revoke 状态具有可校验的成功与失败 Schema;明确 Provider HTTP 失败不得退化为 unknown,unknown 仅表达无法判定副作用是否发生。
- [ ] **AC-4:** consumer tests 拒绝未知版本、调用方提交的身份/账号/Credential selector、Secret-bearing result 和不兼容 Schema 漂移,并覆盖 `add_issue_labels` 已明确失败与响应不确定的差异。
- [ ] **AC-5:** Platform、Web 和 Connection 侧测试使用同一生成产物;连续两次生成字节一致且无未提交漂移。
## Validation
- 运行 focused schema、generation、drift、compatibility、consumer/Fake 和 package-surface tests。
- 以真实 `add_issue_labels` 误判为 unknown 的场景建立回归用例:GitHub 非成功响应得到脱敏 `PROVIDER_FAILED`,仅响应丢失或终态落库失败得到 `RESULT_PENDING/UNCERTAIN`。
- 连续生成两次并确认第二次不产生 diff;运行完整仓库验证序列。
## Blocked by
- #252
- #393
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.