AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(platform): implement ObjectStorage and file authority
- Lingua principale
- TypeScript
- Stelle
- 0
- Fork
- 0
- Merge medio
- 8h 51m
- PR unite (30g)
- 99
Descrizione
> 由 #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。
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.