AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(platform): deliver user and application Agent management API

Abierto
#481 1 comentario 0 reacciones 1 asignado Reclamado por @LichKing-2234 Ver en GitHub
needs-triage
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

本票由 [M1 交付汇合](https://github.com/AgoraIO-Extensions/agent-infra/issues/150) 已确认的新增范围建立,当前为 `needs-triage` 的实施契约候选,不进入既有冻结执行 snapshot。主责:LichKing-2234;执行方式、资源窗口与 Start/Target 尚未确定。开始实现前须完成候选权威文档的跨系统对齐、适用评审与合入,回读全部原生依赖,并在本票确认执行准入。文档票关闭不单独授予执行权限。

## Problem

现有员工 Web 申请/审批与 Agent 管理基础不能提供用户和独立应用的 API 身份、凭证、无审批创建及显式初始授权闭环。本票交付这一独立增量,保留员工 Web 创建审批路径。

## Scope

- 在既有 Platform Core/Store/API/Web 完成用户/应用及其凭证管理、应用自然人责任人登记、当前身份/组织/权限解析;凭证具有操作范围、有效期及单独撤销,凭证值不进入普通读取、日志或审计。
- 实现创建、启动、停止和重启 Agent 的公开 API,复用原生命周期/Workload 调谐;创建返回稳定 Agent 标识与状态,显式启动已停止 Agent,禁止恢复被管理员停用的 Agent。创建按可信主体、操作和幂等键持久绑定,同请求返回原对象,冲突拒绝。
- API 创建不增加逐次审批或预审批。服务端确定创建主体与人类 Owner;独立应用的创建主体仍是应用,责任人只作为人类 Owner。向创建主体显式授予可分别撤销的管理/使用权限,保持凭证范围与当前主体权限的交集。
- 提供个人凭证、应用/责任人、应用凭证及 Agent 应用授权的基础管理入口;凭证失效与主体/Agent 授权撤销提供不同的服务端事实,供任务用例消费,不在本票再实现任务取消状态机。
- 本票负责这些治理操作、API 访问/拒绝和初始授权的必要事务审计;同步真实调用的版本化 Zod 契约、生成 OpenAPI/Client、migration 与 API/Web 消费测试。复用现有审计写入及身份模块,不建立新的身份服务或权限平台。
- 任务提交/流/取消由持久任务票负责,审计查询由审计查询票负责;不实现 Connection 客户端认证或授权,不修改其数据库、DAG 或负责人。

## Acceptance criteria

- [ ] **AC-1:** 用户与独立应用均可用各自有效凭证完成创建、启动、停止、重启;创建操作无审批,员工 Web 创建审批与生命周期限制保持。
- [ ] **AC-2:** 服务端解析主体类型、稳定 ID、组织与当前权限;应用创建者、自然人 Owner/责任人和独立初始管理/使用授权正确,撤销一项不隐式撤销另一项,责任人权限不能被应用继承。
- [ ] **AC-3:** 相同主体/操作/幂等键的同请求返回原 Agent 与状态;不同主体隔离,同键不同请求冲突;响应丢失及重启不重复创建或调谐业务操作。
- [ ] **AC-4:** 个人/应用凭证管理及授权页面可用;范围、到期、单独撤销和主体失效实时生效,原始凭证不出现在普通读取、日志、Trace 或审计,越权查询不能探知对象存在。
- [ ] **AC-5:** 治理/访问/拒绝、Owner/责任人及初始授权变更可追溯;必要审计与业务变更一起提交,审计失败不能返回虚假成功或把拒绝变为放行。
- [ ] **AC-6:** 真实 API/Worker/PostgreSQL 装配和浏览器管理流程通过;证明 API 导致实际 Workload 创建/生命周期变化,并覆盖跨主体、凭证范围缩窄、独立授权撤销、重启和幂等负向场景。

## Validation

- 对照 PRD §§2、6、7.3、10.4、11、13 和工程 Spec §§8–9、12、15–19,验证 API 与 Web 授权路径的区别。
- 使用两个用户和独立应用的正式身份与 HTTP 入口验证正负向用例;以真实 PostgreSQL、Worker 和隔离 Workload 环境验证实例调谐;记录源码、镜像/配置及实际状态,Fake 不替代实例启动证据。
- 执行管理页面浏览器流程、契约/生成漂移及必要事务故障测试;合成敏感哨兵验证错误和审计不泄漏;执行 AGENTS.md 完整仓库验证及当前提交 Standards/Spec Review。

## Blocked by

- #474
- #476

## Authority

- 产品输入:[平台 PRD 候选](https://github.com/AgoraIO-Extensions/agent-infra/blob/2eb2762b889a27372c259039d27279cf646c5b1e/docs/prd/PRD-agent-platform-M1.md)。
- 工程输入:[工程 Spec 候选](https://github.com/AgoraIO-Extensions/agent-infra/blob/7f3b2083d44191ab4b280d7eb8222d7785937b8e/docs/architecture/SPEC-agent-infra-M1-engineering-architecture.md)、[Runtime HLD 候选](https://github.com/AgoraIO-Extensions/agent-infra/blob/5da6fff274ffc7a7ee36ae3ebd61d6100ccc9571/docs/architecture/HLD-agent-runtime-M1.md)。
- 上述固定版本用于评审和追溯;实施前消费合入后的权威版本,差额在本票复核,不能用历史候选覆盖新结论。

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.