Coze Studio 前端上传体系解析：`@coze-arch/uploader-interface` 类型契约包的设计与实战

Coze Studio 前端上传体系解析coze-arch/uploader-interface类型契约包的设计与实战【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio本文围绕 Coze Studio 前端 monorepo 中的 uploader-interface 包 展开它是一个纯类型定义包为整个前端文件上传体系视频、图片、普通对象文件统一了 STS 临时凭证、上传配置、事件回调与上传结果的结构化契约。读完本文你能掌握该包导出接口的完整字段语义理解它如何被 uploader-adapter 适配落地、并在 bot-utils 上传工具 中驱动真实的“获取上传凭证 → 创建 Uploader → 监听进度 → 返回上传结果”全链路。一、包定位与安装方式包 README 明确了该包在 monorepo 中的角色它是 Coze Studio 前端工作区的一部分提供面向上传场景的接口层能力。从 package.json 可以看到几个关键事实包名为coze-arch/uploader-interface当前版本0.0.1许可协议 Apache-2.0main直接指向 src/index.ts即 TypeScript 源码即入口build脚本为exit 0——说明该包不做独立产物构建由 monorepo 的 workspace 依赖机制在消费方直接引用源码test使用 Vitestvitest --run --passWithNoTests代码质量由 ESLint 保障与 README 中 Development 一节“TypeScript / Modern JavaScript / Vitest / ESLint”的描述一致。README 给出的引用方式是标准 Rush workspace 依赖{ dependencies: { coze-arch/uploader-interface: workspace:* } }然后执行rush update完成依赖链接。仓库中实际这样消费它的包是 uploader-adapter它在package.json中声明了对本包的workspace:*依赖。二、核心类型契约src/index.ts 逐项解析该包的全部实现就是这一个入口文件src/index.ts导出了一套完整的上传 SDK 契约。下面按“凭证 → 配置 → 任务 → 事件 → 结果 → 实例接口”的顺序拆解。2.1 STSToken上传临时凭证STSToken 定义了对象存储TOS临时授权的五个字段export interface STSToken { AccessKeyId: string; SecretAccessKey: string; SessionToken: string; ExpiredTime: string; CurrentTime: string; }其中CurrentTime与ExpiredTime让前端可以在本地比较时间戳判断凭证是否临近过期从而触发 SDK 的refreshSTSToken方法刷新见 2.6 节。这一结构在业务层的真实构造过程可参考 upload-file.tsbizConfig中bot与workflow两个业务各自的getAuthToken都会调用后端GetUploadAuthToken接口把响应里的auth.access_key_id、auth.session_token等字段逐一映射为STSToken结构同时取出service_id、upload_host、schema作为上传宿主参数。2.2 Config全局上传配置Config 是创建 Uploader 实例时的入参字段可归纳为几组必填身份项字段类型说明userIdstring当前用户 ID必填appIdnumber应用 ID必填区域与宿主路由stsToken?: STSToken可选的全局凭证单个文件也可在FileOption中单独携带region?枚举限定为cn-north-1 | us-east-1 | ap-singapore-1 | us-east-red | boe | boei18n | US-TTP | gcp用于选择上传链路区域videoHost/videoFallbackHost/imageHost/imageFallbackHost主、备上传网关域名适配器层会优先取主域名、缺失时回退到 fallback该回退逻辑有单测覆盖见 3.2 节schema?: string源码注释说明它对应 Tt-uploader 的逻辑——协议 schema 需要根据当前用户的部署环境动态获取只支持 HTTPS/HTTPSDK 内部消费该值而不暴露类型定义。分类型处理管线videoConfig?: VideoConfigspaceName必填 processAction?imageConfig?: ImageConfigserviceId必填 processAction?objectConfig?: ObjectConfigserviceId?/spaceName?processAction?其中 Action 的name限定为GetMeta | StartWorkflow | Snapshot | Encryption | AddOptionInfo | CaptionUpload即上传完成后可串联的云端处理动作取元信息、启动处理工作流、截帧封面、加密等。分片、超时与行为开关关键项摘录自源码注释字段语义getSliceFunc?: (fileSize: number) number自定义按文件大小计算分片大小uploadSliceCount?: number分片上传并发/片数控制uploadHttpMethod?: string上传 HTTP 方法uploadTimeout?/gatewayTimeout?上传超时 / 上传网关超时skipDownload?: boolean跳过下载环节仅视频上传支持skipMeta?: boolean跳过元信息获取仅图片上传支持skipCommit?: boolean跳过 1005 提交阶段仅支持 ImageXenableDiskBreakpoint?: boolean是否启用断点续传clientEncrypt?: boolean客户端加密开关instanceId?: string多实例识别useFileExtension?/useServerCurrentTime?/openExperiment?/noLog?/bizType?文件名扩展名策略、服务器时间基准、实验透传、日志静默、业务类型UpdateOptionsL115-L141是Config的全选子集对应运行时通过setOption热更新配置的能力。2.3 文件与任务选项FileOptionaddFile的入参核心是file: BlobstsTokentype限定video | image | object另有objectSync?跨通道同步的源/目标通道与DataType、BizID、storeKey?、useDirectUpload?、serviceType?: vod | imagex区分点播与 ImageX 服务ImageFileOptionaddImageFile的入参与FileOption的差异在于file允许Blob | Blob[]批量图片StartOptionsstart的可选参数提供selectRoute系列字段路由选择开关、客户端 IP、路由选择超时/缓存时长/文件大小阈值用于上传前择优路由StreamTaskOption / StreamSliceOption流式上传任务stsToken 可选fileSize与流式分片fileSlice: Blob 序号index配合addStreamUploadTask/addStreamSlice/completeStreamUpload三个 API 完成边收边传的场景。2.4 事件系统README 导出的三个类型只是冰山一角README 的 API Reference 列出了三个导出类型别名ProgressEventInfo、StreamProgressEventInfo、ErrorEventInfo。在源码中L286-L294它们都指向同一个 BaseEventInfo 基础结构interface BaseEventInfo { startTime: number; // 文件开始上传时间戳毫秒 endTime: number; // 文件上传完成时间戳 stageStartTime: number; // 当前阶段开始时间戳 stageEndTime: number; // 当前阶段结束时间戳 duration: number; // 阶段耗时 stageEndTime - stageStartTime fileSize: number; // 当前文件大小 key: string; // 文件 keyaddFile 时自动生成 oid: string; // 存储文件 IDpreUpload 阶段产生 percent: number; // 整体进度百分比% signature: string; // preUpload 阶段取得的签名信息 sliceLength: number; // 每个分片大小crc32 获取 stage: string; // 当前生命周期阶段不支持的浏览器为 browserError status: 1 | 2 | 3; // 1 运行中 / 2 取消中 / 3 暂停 task: any; // 任务队列实例 type: success | error; uploadID: string; // get initUploadID 取得的 uploadID extra: { error?: any; errorCode?: number; message: string }; }这组字段完整刻画了上传任务的生命周期stagestageStartTime/stageEndTime描述当前处于哪个阶段及耗时percent描述整体进度status与type共同表达运行态与成败。基于BaseEventInfo事件载荷通过 EventPayloadMaps 做了精确映射export interface EventPayloadMaps { complete: CompleteEventInfo; // BaseEventInfo uploadResult: UploadResult progress: ProgressEventInfo; stream-progress: StreamProgressEventInfo; error: ErrorEventInfo; }四个事件名complete | error | progress | stream-progress与BytedUploader.on的泛型参数一一对应回调函数会拿到精确的EventPayloadMaps[T]类型业务侧无需再做载荷断言。2.5 UploadResult按文件类型归一化的结果结构UploadResult 把视频、图片、普通文件三种结果平铺在同一接口中源码注释明确说明了取舍“不同类型字段有差异用范式discriminated union处理略显繁琐因此直接全量定义”。按类型分组的字段包括视频Vid视频 VID、VideoMeta?UploadResultVideoMeta时长、宽高、格式、码率、大小、Md5、Uri等其中Md5注释特别说明“MD5 需下载计算默认仅在小于 100M 且非 M3U8 文件时返回强依赖需联系手动配置”、PosterUri?封面需配置截图动作后返回图片ImageUribucket/oid格式、ImageWidth/ImageHeight/ImageMd5、FileName与ImageUri中 oid 段一致普通文件ObjectMeta?Md5Uri。Uri字段注释提醒它是 TOS 中的源文件 URI格式为bucket/oid图片场景与ImageUri保持一致。2.6 BytedUploader实例能力的完整契约BytedUploader 以接口形式约定了上传实例的全部 API可视为对底层tt-uploaderSDK 的“能力契约”方法签名要点用途constructor(config: Config)构造入参即 2.2 节Config创建实例setOption(options: UpdateOptions)运行时更新配置热更新addFile(fileOption): string返回文件 key添加视频/图片/对象文件addImageFile(imageFileOption): string返回文件 key添加批量图片start(key?, startOptions?)可选按 key 启动启动上传pause(key?)/cancel(key?)/removeFile(key?)均可指定 key暂停 / 取消 / 移除refreshSTSToken(stsToken)传入新凭证凭证过期刷新addStreamUploadTask/addStreamSlice/completeStreamUpload流式三件套边接收边上传on/once/removeListener/removeAllListeners泛型T extends UploadEventName事件订阅与退订由于on的回调参数类型由EventPayloadMaps精确约束业务监听complete时拿到的必然是带uploadResult的CompleteEventInfo——这是该契约包给前端最大的工程收益上传全链路的类型安全由类型包统一保证而非散落在各业务实现里。三、仓库中的真实消费链从接口包到可运行上传3.1 uploader-adapter把契约落到 tt-uploaderuploader-adapter 是直接依赖本包的适配层。它导入tt-uploader的Uploader实现类同时从coze-arch/uploader-interface复用Config、STSToken、ObjectSync类型并对外转导出Config与EventPayloadMapsL74-L77形成“接口包定义契约 → 适配器提供实现 → 业务只依赖契约”的清晰分层。其getUploader(config, isOversea?)工厂函数做了三件契约之外的落地工作区域路由region: isOversea ? ap-singapore-1 : cn-north-1L39-L52。同目录 utils.ts 中的REGION_MAP还给出了更完整的区域归一化思路如us-east-1因“Volcengine 无 va 环境”而映射到ap-singapore-1imageHost 归一化优先config.imageHost缺失回退config.imageFallbackHost再缺失取空串同时按config.schema动态替换协议头兼容 HTTP 特化场景L34-L38addFile 收窄为图片链路适配器把uploader.addFile重写为只透传{ file, stsToken }给底层addImageFile返回的文件 key 即底层生成值L54-L63。其导出的CozeUploader Uploader { addFile; removeAllListeners }类型就是业务侧实际使用的上传器类型。3.2 测试对契约行为的验证适配器单测tests/index.test.ts 通过 mocktt-uploader验证了上述契约行为可作为“接口 → 实现”一致性的证据构造配置断言国内默认region: cn-north-1isOversea为 true 时切换ap-singapore-1L66-L84addFile确实只透传{ file, stsToken }并返回底层 keyL86-L92imageHost会剥离https://前缀、缺失时回退imageFallbackHost、两者皆缺时回退空串L94-L118。3.3 业务用法bot-utils 中的 upLoadFilebot-utils 的 upload-file.ts 展示了接口契约在业务侧的典型用法L101-L117入口upLoadFile({ biz, file, fileType, getProgress, getUploader, getUploadAuthToken })支持biz: bot | workflow不同业务对应不同 ImageX 服务各自通过DeveloperApi.GetUploadAuthToken/workflowApi.GetUploadAuthTokenscene 分别为bot_task、imageflow换取serviceId、uploadHost、stsToken、schema文件类型支持image | object进度通过getProgress回调上报——这正是 2.4 节progress事件percent字段的落地该文件还做了export type BytedUploader CozeUploader的类型别名导出让更上层业务只面向契约类型编程。从源码结构看整条链路是uploader-interface契约→uploader-adaptertt-uploader 适配与区域/宿主归一化→bot-utils upLoadFile凭证获取与业务编排→ 各 IDE 功能bot 素材、workflow 图标等上传入口。四、开发与质量保障该包遵循 monorepo 统一的工程基线参考 package.json 与 README 的 Development 一节测试Vitest命令npm run test即vitest --run --passWithNoTests纯类型包允许零测试用例通过与npm run test:cov静态检查npm run lint调用eslint ./ --cache配置文件见 eslint.config.jsTypeScript 工程tsconfig.json 复用coze-arch/ts-configworkspace 包构建build为空操作exit 0消费方以源码形式引用。作为 monorepo 的一员贡献流程遵循仓库整体的贡献指南见根目录 CONTRIBUTING.md协议为 Apache-2.0。五、小结coze-arch/uploader-interface虽只有单个入口文件却以一套完整的 TypeScript 契约约束了 Coze Studio 前端上传体系的全部关键面STSToken与Config解决“用什么凭证、走哪条链路”FileOption/ 流式选项解决“传什么”EventPayloadMaps解决“过程如何感知”UploadResult解决“结果如何消费”BytedUploader则把实例 API 固化为可静态检查的接口。对需要扩展上传能力的开发者而言最实际的做法是先对照本包类型定义补齐自己的配置与事件处理再参考 uploader-adapter 的区域归一化与宿主回退策略实现适配层最后用 bot-utils/upload-file.ts 的“业务换取上传凭证 → 创建 uploader → 监听 progress/complete”模式接入业务。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考