AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(platform): integrate files across Web, Runtime, and managed channels
- Ngôn ngữ chính
- TypeScript
- Star
- 0
- Fork
- 0
- Merge trung bình
- 8 giờ 51 phút
- Pull request đã merge (30 ngày)
- 99
Mô tả
> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI、真实模板/企微资源与评审窗口尚未确定,Start/Target 留空。
## Problem
公共 ObjectStorage 和文件权威只能提供安全的数据面生产者,不能单独满足 M1 的附件与结果文件。完整能力还需要 Web 和企微按渠道限制上传/接收文件,Conversation 将文件与幂等消息绑定,Worker 通过 Execution Grant 把精确附件交给 Runtime,各固定 Driver 消费附件并登记结果文件,历史和下载继续按发送者隔离。现有 #192、#437、#438、#439、#440 都明确没有交付这条完整链路,因此需要一个唯一的跨消费者整装与验收入口,而不能让每个 UI、Channel 或 Driver 自建文件存储和授权。
## Scope
- 消费本批次唯一 ObjectStorage/文件权威,不新增对象存储 Adapter、文件元数据表、预签名策略或生命周期实现。复用现有 Browser、Conversation、RuntimeHost、Execution Grant、Runtime event 和 capability 契约,只增加文件旅程所需的兼容字段与操作。
- 在平台 Web 对话中展示当前模板/Agent 与 Web 渠道实际支持的文件类型、大小和附件/结果能力;在上传前校验,提供上传进度、失败/过期重试、附件移除、消息绑定、结果文件展示/预览(适用时)和下载。文件能力不可用时不展示可操作入口。
- Conversation 在同一幂等准入事务中把已完成、当前 actor 有权、属于当前 Agent/Channel/Conversation 的附件绑定到 Message/Execution;文本加附件按正式 Schema 接收;仅附件输入只有在正式 Schema 明确允许时才接收,否则明确拒绝且不产生 Execution。相同请求重放原绑定,冲突请求拒绝;繁忙、撤权、上传未完成或 capability 变化时不得创建悬空 Message、Execution 或 Runtime work。
- Worker 每次投递和恢复前重验当前授权与文件状态,只把本次 Execution Grant 精确列出的只读附件引用交给 RuntimeHost。RuntimeHost 在读文件前校验 Grant 的 issuer、audience、有效期、Agent/actor/Channel/Conversation/Execution/generation、`fileId` 和操作,且不通过引用回读 Platform DB。
- Codex Native、Claude Native、Generic ACP/OpenCode 和 Pi RPC 使用各自已固定的 Driver 将平台附件映射为真实原生输入,并把真实产出通过公共结果写入/确认链路规范化为 `result.file`。核心文件能力不能以空数组、Fake、协议名称或未验证 capability 冒充;不支持的具体类型在副作用前明确拒绝。
- 平台只在结果文件已经由公共文件权威确认并绑定当前 Execution 后持久化和展示 `result.file`。重复/迟到事件、事件重放、Runtime/Worker 重启和结果提交 unknown 不产生第二对象、第二事件或跨 Execution 文件;不可确认时保持明确状态,不盲重写或虚报可下载。
- 在平台托管企微 Channel 上把机器人/自建应用实际支持的图片、文件或媒体映射到同一文件权威和 Conversation/Execution 路径。回调重投不重复上传或执行;外发结果不确定时沿用 #440 的有界恢复语义。群内公开消息和显式公开文件遵循 PRD 的公开可见边界;公开可见不赋予其他发送者 Platform 文件查询或 Runtime 附件引用权,也不能把其内容注入其他发送者的 Runtime 上下文。私有文件不能自动外发为群内公开内容。
- 四个标准模板在 Web 与平台托管企微均按各渠道可传输范围完成真实附件和结果文件验收。使用平台交互入口的自定义 Agent 只在 ACP 准入的附件/结果 capability 及相应 conformance 通过时启用;本票不实施自定义 Agent 的镜像准入、身份入口或其管理 UI;消费本批次独立 Custom Agent 准入票,并将通过准入的受控样例纳入文件 capability 正负验证。self-managed 文件仍由自定义 Agent 负责且不进入平台历史。
- 消费本批次 Platform 工程观测约定,在文件 Adapter/整装边界接入对象存储失败和文件传输结果指标,不把用户/文件标识或内容作为 Metric label,不复制观测生产者。
- 文件和结果历史遵循既有 Conversation 可见性与部署保留政策。Agent 停止、重启、升级或停用后文件引用不丢失;服务不可用时历史只读。Connection 不参与文件授权,本票也不声称 Connection 能力完成。
## Acceptance criteria
- [ ] **AC-1:** Web 在上传前展示当前 Agent/Web 交集后的类型、大小与 capability,完整呈现上传、失败/过期、移除、消息绑定、结果展示和下载状态;能力关闭或限制不满足时在消息/Runtime 副作用前拒绝。
- [ ] **AC-2:** Message/Execution 与已完成附件在一个幂等准入边界绑定;合法重放复用原 Message、Execution 和附件集合,同 Key 变更附件/文本稳定冲突,未完成、越权、跨 Conversation/Channel 或已撤权附件不创建业务副作用。
- [ ] **AC-3:** Worker 与 RuntimeHost 只接受当前 Execution Grant 精确授权的只读附件;投递、补充指令、恢复和重启均重验文件绑定、状态、代次与操作,跨 Agent/actor/Channel/Conversation/Execution/generation 的引用在读取对象前失败。
- [ ] **AC-4:** Codex、Claude、OpenCode 和 Pi 的真实 Driver 都能以获准类型完成附件输入并产生至少一个真实结果文件;能力、文件内容和原生引用不会在模板之间串用,空附件、Fake 或单独 Schema 通过不能作为验收证据。
- [ ] **AC-5:** `result.file` 只引用已确认、绑定当前 Execution 的文件;结果提交/事件响应丢失、重复、迟到、重放及 Worker/Runtime 重启保持一个对象和一个稳定平台事件。unknown 保持可回读且不盲目重试、改绑或显示为已下载。
- [ ] **AC-6:** 企微机器人和自建应用按真实接口能力收发支持的图片/文件/媒体并复用同一文件权威;回调重投、外发 unknown、双发送者群聊/线程、撤权和重启不重复对象/消息/执行,也不暴露另一发送者的非公开文件或 Runtime 上下文;显式群内公开内容与个人文件授权分别验证。
- [ ] **AC-7:** Web、企微机器人、企微应用及不同发送者的历史和文件授权保持隔离;Owner 不能读取普通使用者文件。停止、重启、升级和停用保留合法引用并使不可用会话只读,部署保留政策之外不新增期限或删除行为。
- [ ] **AC-8:** 四标准模板的真实 Web 与平台托管企微文件矩阵通过,证据绑定 current source SHA、实际模板镜像 Digest、Runtime/Driver 版本、文件配置版本、渠道类型和获准测试文件;自定义 platform-adapter 的能力门禁通过正/负 conformance。文件完成不替代 Connection 或完整 M1 上线验收。
## Validation
- 运行 Browser Schema/生成 Client、Web 组件、Core/Store/API/Worker、RuntimeHost Grant、事件和 Channel 集成测试,覆盖类型/大小限制、文本加附件及仅附件输入的合法接收或明确拒绝、消息幂等、撤权、繁忙、重启、重放和 unknown。
- 对四个真实 Driver 运行共享文件 conformance,并在获准模型/模板镜像上分别完成附件读取、结果写入、重启恢复、同用户正向和跨用户/跨 Conversation 负向测试。
- 在真实企微机器人和自建应用中验证各自支持的图片/文件/媒体、双发送者群聊/线程、合法回调重投、外发 unknown 与当前权限变化;不把模拟回调或 Web 成功当作企微通过。
- 运行 Web 和企微的端到端矩阵,回读 Platform DB 元数据、对象 Hash/大小、Conversation 历史与下载授权;测试证据不保存普通文件内容、短期 URL、个人消息或凭证。
- 执行 `AGENTS.md` 完整仓库验证及 current-head Standards/Spec Review;涉及 Web 时按仓库设计流程完成当前 artifact 的桌面/移动端验证。
## Blocked by
- #442
- #192
- #437
- #438
- #439
- #440
- #444
- #441
## Authority
- Agent Platform PRD §§4、5.3–5.4、7、10–12、14;工程 Spec §§6、8、9.3、14.2、15.4、17、19、20、24;Runtime HLD §§3–7、9、11。正式依据为 `main@f0e8aa58ca90dec2583459818c1167781979235f`。
- #165 仅从首个 Pilot 延后附件/结果文件;#192 明确只交付文本 Pilot。#437/#438/#439 交付各 Driver 核心,#440 交付企微文本,均明确把完整文件链路留给 #150 后续票。
- 基础票唯一拥有 ObjectStorage Adapter、文件元数据权威、预签名与生命周期;本票只拥有跨 Web、Conversation、Runtime Driver、企微的消费整装和完整文件验收,避免重复 producer 或按模板复制文件平台能力。
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Đánh giá
Issue này chưa được đánh giá.