AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(connection): support compatible patch upgrades from persistent baseline
- 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.