AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(connection): support compatible patch upgrades from persistent baseline

Abierto
#462 1 comentario 0 reacciones 0 asignados Ver en GitHub
enhancement ready-for-human
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

## Problem

Connection 目前缺少两项稳定交付边界。第一,已部署的 Connection 功能分散在多个串行 Issue 分支,后续工作仍可能错误地从 `main` 或旧功能分支开始,遗漏尚未回收进默认分支的完整 Connection 基线。第二,Provider Adapter 的实现修复会产生新的 immutable ProviderRelease/ActionVersion;即使 endpoint、认证、Credential profile、Action schema、effect 和 scope 完全不变,现有 Provider Connection 与 Grant 仍被标记为必须重新连接和重新授权,给用户造成不必要的凭证输入和服务中断。

## Scope

- 将持久 `connection` 分支定义为仅 Connection 改动的累积基线;新的 Connection Issue 分支必须从最新远端 `connection` 创建,完成后先回收并验证到 `connection`,再按既有 PR 流程进入默认分支。
- 在开发工作流 Spec 和 `AGENTS.md` 记录该例外;非 Connection 改动继续以默认分支为基线,Worker cycle、primary Issue、PR、Gate 和禁止 force-push 规则不变。
- 定义严格的兼容补丁升级判定:Provider、deployment、endpoint、auth/Credential profile、Action stable name、input schema、effect、required scopes 和账号 identity 必须保持一致,只允许 executor 实现或返回值修复。
- 新 ProviderRelease/ActionVersion 仍不可变;不得修改旧 release/version、旧 Consent 或旧 Grant。
- 对满足兼容判定的 replacement release,复用现有加密 Credential 完成服务端 identity proof,创建审计可追踪的 replacement Grant 并原子切换当前 Connection,不要求用户重新输入 Provider Credential 或重复确认相同能力。
- 任一兼容字段变化、identity proof 失败、旧授权失效、跨 Principal/Consumer/Connection 不匹配或升级竞态均 fail closed,并继续走现有重新连接/重新授权流程。
- Connection Web 和 MCP 状态区分 compatible upgrade、reauthorization required 和 reconnect required;兼容升级最多显示非阻塞完成状态。
- 不为 WRITE scope 扩张、endpoint/auth 变化或新 Action 提供自动授权。

## Acceptance criteria

- [ ] **AC-1:** 项目文档明确:仅 Connection 改动从最新 `origin/connection` 派生并回收到 `connection`;其他改动继续遵循默认分支流程,且 primary Issue/PR/Gate 规则不变。
- [ ] **AC-2:** compatible replacement 使用确定性比较证明 Provider、deployment、endpoint、auth/Credential profile、Action 名称、schema、effect 和 scopes 完全相同;任何差异均拒绝自动升级。
- [ ] **AC-3:** compatible replacement 创建新的 immutable ProviderRelease、ActionVersion 和 replacement Grant,不 UPDATE 或伪装旧 release/version/Consent/Grant。
- [ ] **AC-4:** 现有有效 Credential 通过服务端 identity proof 后可切换到 compatible release,用户无需重新输入 Provider 密码或 Token。
- [ ] **AC-5:** 对相同能力的有效 Grant,系统原子创建并切换 replacement Grant;旧 Grant 保留审计且不可继续成为 current,不要求用户重复确认相同权限。
- [ ] **AC-6:** schema、effect、scope、endpoint、auth、identity 或 Credential 状态变化时保持 `PROVIDER_REAUTHORIZATION_REQUIRED` 或 reconnect 语义,不自动迁移。
- [ ] **AC-7:** 覆盖跨 Principal、跨 Consumer、跨 Connection、失效 Credential、并发升级和 capability drift 的负向测试。
- [ ] **AC-8:** 使用 Jira v4 到 v5 的返回值修复作为兼容升级回归场景,验证升级后 `jira.search_issues` 可读取非空分页结果且用户无需重连或重新授权。
- [ ] **AC-9:** HLD、PRD、工程 Spec、OpenAPI/MCP 状态词汇和审计契约保持一致,完整仓库验证通过。

## Validation

- Connection Core/Store/API/Web 定向测试覆盖兼容与非兼容 replacement。
- 临时 PostgreSQL 集成测试验证 Credential identity proof、replacement Grant 原子切换、竞态和跨主体拒绝。
- Jira Adapter 回归测试及真实受监督 Jira READ 验证。
- `pnpm install --frozen-lockfile`
- `pnpm check`
- `pnpm check-types`
- `pnpm test`
- `pnpm build`
- `pnpm smoke`
- `pnpm docker:build`
- Markdown lint/link、workflow policy、actionlint 和 `git diff --check`。

## Blocked by

None

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.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.