AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(platform): implement ObjectStorage and file authority

Abierto
#442 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI、部署资源与评审窗口尚未确定,Start/Target 留空。

## Problem

M1 已确定附件与结果文件使用 S3 兼容 ObjectStorage Adapter,业务接口只传文件引用和元数据,并通过短期、按使用者或 Execution 绑定的访问提供数据面能力。当前仓库只有 `attachments[]`、Execution Grant 的附件声明、`result.file` 事件和 capability 字段;Platform DB 没有文件元数据权威,Conversation dispatch 仍固定发送空附件,也没有对象存储 Adapter、预签名上传/下载或 Runtime 执行期临时访问生产者。继续由 Web、Channel 或各 Runtime Driver 各自补实现会产生多套对象键、授权、生命周期和恢复语义。

## Scope

- 在 Platform Module 定义一个部署中立的文件服务边界和窄 `ObjectStorageAdapter` Port,并提供受控 Fake 与 S3 兼容部署 Adapter。S3 SDK、bucket、role、endpoint 和部署凭证只存在于部署 Adapter/装配层,不进入 `platform-core`、公共 wire contract 或 Runtime。
- 以 Platform DB 作为文件元数据与授权关系的唯一权威,保存平台生成的 `fileId`/对象引用、种类(输入附件或结果文件)、当前 owner `actorId`、Agent、Channel、Conversation、Message/Execution 绑定、原始文件名、媒体类型、大小、内容 Hash、对象版本/etag、生命周期状态及必要时间;数据库不保存文件字节、长期凭证或可复用 URL。
- 实现幂等的上传意图、短期预签名数据面上传、完成确认和失败/过期收敛。对象键由服务端生成;API 在签发前及数据面每次使用前按当前认证用户、Agent、Channel、Conversation 和已验证 capability/限制授权并持久记录范围,完成时从实际对象校验大小、类型、Hash 和版本,只有完整且匹配的对象进入可引用状态。同一幂等请求返回同一意图;同 `fileId` 变更内容或绑定时拒绝。
- coordinator 决定:浏览器和 Runtime 使用平台签发的短期文件数据面入口,入口在每次实际使用时校验当前用户会话或当前 Execution 授权及对象/操作绑定,再由服务端流式访问 S3;不向调用方重定向或返回可绕过主体校验的 S3 bearer URL。S3 预签名能力只作为服务端内部实现,不能冒充用户身份证明。数据面采用有界流式传输,不把文件字节放进业务 JSON、Core 或数据库。Agent Owner 身份本身不能读取普通使用者文件;合法历史在停止、重启、升级或停用后按当前历史权限和保留政策读取。
- 实现执行期临时文件访问生产者:输入附件只允许当前 Execution Grant 明确列出的 `fileId` 和 `read` 操作;RuntimeHost/Worker 只能为本次 Grant 换取对象级短期访问,不能获得 bucket 长期凭证、枚举对象或扩大到其他文件。
- 当前 `ExecutionGrantClaimsV1.attachments` 只定义 `read`。coordinator 决定:结果写入由 Platform 文件授权用例先分配不可跨主体改绑的对象引用,再经可信平台签发边界授予仅该对象、当前 Agent/actor/Channel/Conversation/Execution/generation、write 操作及有限大小/期限的临时权限;Runtime 不能自选 owner、对象键或签发权限。实际使用与完成确认再次检查当前绑定和操作;同一写入意图重试保持同一对象,迟到/过期/撤销或代次变化拒绝。首次代码实现前先将结果写入和上述数据面入口的签发方、audience、消费方、重放/撤权与 wire 版本写入工程 Spec/必要 ADR,完成 Worker、RuntimeHost、Web/Channel 和 ObjectStorage 消费方评审;不得直接扩展旧 Grant 或降低现有用户绑定要求。
- 结果文件在对象写入确认后才登记为可见文件并可被 `result.file` 引用。重复完成、Worker/RuntimeHost 重启、访问过期、对象状态未知和迟到提交必须收敛到同一文件记录,不得产生第二个对象、跨 Execution 改绑或把 unknown 写成成功。
- 文件状态与对象清理由有界协调任务对账;孤立、失败和过期上传不能无限保留。会话、附件和结果文件保留遵循部署环境数据政策,平台不新增产品级保留期限,也不增加 M1 未支持的用户删除或会话导出能力。
- 复用并按兼容规则扩展现有 Browser、RuntimeHost、Execution Grant 和 `result.file` Schema;不建立第二套 DTO。既有 #179/#180/#181 保持基础契约归属,本票只拥有文件数据面所需增量。
- 本票不实现 Web 文件控件、企微媒体映射、任何具体 Runtime Driver 的文件桥接或四模板端到端验收;这些消费者由后续文件整装票统一接入。Connection 不参与文件对象授权。

## Acceptance criteria

- [ ] **AC-1:** 一个窄 ObjectStorage Port 同时驱动 Fake 与 S3 兼容 Adapter;部署类型、bucket/role/endpoint/credential 不进入领域、Store、公共 Schema、日志或 Runtime,调用方不能覆盖对象存储位置或对象键。
- [ ] **AC-2:** Platform DB 对输入附件和结果文件保存完整、不可跨 owner/Conversation/Execution 改绑的元数据与生命周期;文件字节、长期凭证和可复用 URL 不进入数据库,Hash/大小/类型来自完成时对实际对象的校验。
- [ ] **AC-3:** 上传意图、URL 签发记录和完成确认按当前 actor、Agent、Channel、Conversation、capability、限制及 Idempotency-Key 绑定;API 授权发生在 URL 签发前。合法重放返回原结果,冲突重放、超限、类型不支持、对象缺失或内容不匹配均在文件可引用前拒绝。
- [ ] **AC-4:** 文件 API 在签发及数据面实际使用时均认证当前用户或 Execution 并校验 actor、Conversation、Channel、单一对象和操作;跨用户、跨 Agent/Conversation/Channel、Owner 越权、过期或伪造引用不返回对象存在性或数据。另一用户拿到同一数据面 URL 也不能访问,撤权后的新访问被拒绝;入口不泄露可绕过检查的 S3 bearer URL。
- [ ] **AC-5:** Runtime 输入只可读取 Execution Grant 中精确授权的附件;结果写入只可使用经 Spec/ADR 和消费方评审的最小 execution-bound 临时授权,并绑定当前 Agent/actor/Channel/Conversation/Execution/generation/operation。服务身份、请求字段、文件引用或 Runtime 返回值均不能单独授权,Runtime 无长期 S3 凭证或对象枚举能力。
- [ ] **AC-6:** 结果对象确认与文件元数据提交幂等;上传/写入响应丢失、进程重启、临时访问过期、对象状态 unknown、重复或迟到完成不会生成第二文件、错误改绑或虚报可用。
- [ ] **AC-7:** 生命周期对账能识别并有界处理未完成、失败、过期和孤立对象;正式文件按部署数据政策保留,Agent 停止、重启、升级和停用不删除合法历史引用。平台不自行设定新期限或开放删除/导出。
- [ ] **AC-8:** Schema/Store/Core/API/Worker、Fake/S3 Adapter、授权、幂等、崩溃窗口、对账和脱敏测试通过;真实 S3 兼容环境与平台数据面证明上传、读取、结果写入、过期和跨主体拒绝,证据绑定 source SHA、配置版本和对象存储实现且不含 URL、对象内容或凭证。

## Validation

- 先完成结果文件临时写入和认证数据面 wire 的 Spec/ADR 与 Worker、RuntimeHost、Web/Channel、ObjectStorage 消费方评审,再运行文件 Schema 生成/兼容、迁移、状态机、对象元数据校验、幂等、预签名、Execution 临时访问和生命周期对账测试;证明业务接口与持久层只传引用和元数据。
- 对 Fake 与部署 S3 Adapter 运行同一 contract suite,覆盖上传/下载/结果写入、URL 过期、重复完成、响应丢失、对象缺失/篡改、清理重试和 Adapter 暂时不可用。
- 运行双用户、双 Conversation、双 Execution 和跨 Channel 负向测试;分别证明合法正向访问与跨 owner/绑定/代次/操作拒绝,Owner 不能读取普通使用者文件。
- 在获准 S3 兼容环境完成真实上传、读取、结果写入和对账;验证签发与实际访问两处授权、同一 URL 被另一用户使用和撤权后的拒绝,以及内部 S3 bearer URL 不外泄,只保留脱敏的版本、Hash/大小结果与测试结论,不保存短期 URL、对象正文或部署凭证。
- 执行 `AGENTS.md` 完整仓库验证及 current-head Standards/Spec Review。

## Blocked by

None

## Authority

- Agent Platform PRD §§4、5.4、7、11、12、14;工程 Spec §§6、8.1、9.3、15.1、15.4、19、20、24;Runtime HLD §§4、5、7、9、11。正式依据为 `main@f0e8aa58ca90dec2583459818c1167781979235f`。
- #165 只把文件从首个 Pilot 延后,不能从完整 M1 删除;#179/#180/#181 已交付公共 contract 与 RuntimeHost 基础,未交付 ObjectStorage 或文件数据权威。
- #192 明确排除 Pilot 文件 UI;#437/#438/#439/#440 明确排除完整文件链路。后续文件整装票消费本票,不在各 Driver 或 Channel 重复对象存储、文件授权和生命周期 ownership。

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.