Coze Studio uploader-adapter 包解析用适配层统一 tt-uploader 上传 SDK 的接入方式【免费下载链接】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-studiocoze-studio/uploader-adapter是 Coze Studio 前端 monorepo 中的上传适配包它的职责是把字节系上传 SDKtt-uploader封装成一个面向业务侧的统一入口getUploader并在其上重新导出标准配置与事件类型。本文结合该包的 README、源码与单元测试完整讲解它的安装方式、核心 API、配置语义与事件模型以及测试用例如何验证 region 选择与 imageHost 回退等关键行为。一、包的定位一个薄适配层从 package.json 可以看到这个包的全部运行时依赖只有两个tt-uploader1.5.0真正的上传 SDK火山/字节对象存储上传coze-arch/uploader-interfaceworkspace:*monorepo 内部的纯类型包定义Config、STSToken、EventPayloadMaps等接口。也就是说adapter 本身不实现任何上传逻辑而是做三件事按部署环境国内/海外决定 region构造tt-uploader实例用统一的FileOption入参包装底层addImageFile调用重新导出Config、EventPayloadMaps两个类型让业务方只依赖 adapter而不直接耦合底层 SDK 的类型定义。包的入口文件是 src/index.ts与main: src/index.ts的声明一致即以 TypeScript 源码形式被消费配合 Rush monorepo 的源码直用模式build脚本为exit 0占位。二、安装与引入方式按 README 的说明在 monorepo 内的消费方包中按如下方式声明依赖{ dependencies: { coze-studio/uploader-adapter: workspace:* } }然后在仓库根目录执行rush update导入用法README 中的模板 源码实际导出import { getUploader } from coze-studio/uploader-adapter; // adapter 实际导出的内容 // - getUploader(config, isOversea?): CozeUploader // - 类型FileOption、CozeUploader // - 透传类型Config、EventPayloadMaps来自 coze-arch/uploader-interface源码中的完整导出清单见 src/index.ts 末尾的export { type Config, type EventPayloadMaps } from coze-arch/uploader-interface与 README API Reference / Exports 一节列出的type Config, type EventPayloadMaps一致。三、核心 APIgetUploader工厂函数getUploader(config: Config, isOversea?: boolean)是整个包的唯一运行时导出其实现要点如下源码 src/index.ts#L33-L653.1 region 的自动选择region: isOversea ? ap-singapore-1 : cn-north-1,第二参数isOversea决定使用新加坡还是北京 region。单元测试tests/index.test.ts#L66-L84分别验证了两种调用默认调用得到region: cn-north-1传入true得到region: ap-singapore-1。值得注意的一个细节src/下还有一个 utils.ts定义了更大的 region 映射表export const REGION_MAP { cn-north-1: cn-north-1, ap-singapore-1: ap-singapore-1, // Volcengine has no va environment us-east-1: ap-singapore-1, };即us-east-1会被归一到新加坡。从源码结构看该映射表目前未被index.ts引用index.ts内采用三元表达式硬编码属于为更细粒度 region 选择预留的工具函数。3.2 imageHost 的解析与 schema 兼容const imageHost ( config.imageHost || config.imageFallbackHost || ).replace(/^https:\/\//, config.schema ? ${config.schema}:// : );这段逻辑有三层语义且每一层都被单元测试覆盖场景行为测试用例imageHost https://img.example.com剥掉https://前缀得到img.example.comshould strip https:// from imageHost缺少imageHost提供imageFallbackHost回退到fallback.example.comshould fallback to imageFallbackHost...两者都缺失使用空字符串should use empty string if no imageHost or fallback剥掉协议前缀后如果配置了config.schema见 uploader-interface 的 Config.schema 注释schema 需根据当前用户部署环境动态获取仅支持https与http两个值则再拼回对应的${schema}://前缀否则保持无协议形式。这样做的目的是让最终 URL 的协议跟随部署环境比如本地 HTTP 调试而不是被写死为 HTTPS。3.3 透传给 tt-uploader 的完整配置工厂函数最终执行new Uploader({...})透传的字段为{ schema: config.schema, region, // 由 isOversea 推导 imageHost, // 上面解析后的 host appId: config.appId, userId: config.userId, useFileExtension: config.useFileExtension, uploadTimeout: config.uploadTimeout, imageConfig: config.imageConfig, }测试用例 should create uploader with correct config (domestic)index.test.ts#L66-L77断言了这组入参其中未提供的useFileExtension、uploadTimeout、imageConfig均为undefined。四、addFile的统一封装adapter 在构造出的Uploader实例上覆写了addFilesrc/index.ts#L54-L63uploader.addFile function (options: FileOption) { const imageOptions: ImageXFileOption { file: options.file, stsToken: options.stsToken, }; return originalAddImageFile(imageOptions); };设计意图业务侧只需传fileBlob和stsToken两个核心字段adapter 负责将其转换为底层 SDK 的ImageXFileOption并调用addImageFile。测试用例 addFile should call addImageFile with correct params 验证了入参原样透传、返回值文件 key如mock-key原样返回。adapter 自定义的FileOption比透传字段更宽src/index.ts#L24-L31保留了type、callbackArgs、testHost、objectSync等可选字段与 uploader-interface 中的 FileOption含type?: video | image | object、serviceType?: vod | imagex等在命名上保持一致便于未来扩展视频/对象直传。CozeUploader类型则声明了 adapter 实例的完整能力面type UploadEventName complete | error | progress | stream-progress; export type CozeUploader Uploader { addFile: (options: FileOption) string; removeAllListeners: (eventName: UploadEventName) void; };即继承tt-uploader的Uploader全部方法start、pause、cancel、removeFile、refreshSTSToken、on/once/removeListener等可参考 uploader-interface 的 BytedUploader 接口 了解完整方法签名约定并叠加适配层覆写的addFile。五、配置与事件类型Config与EventPayloadMapsadapter 从 coze-arch/uploader-interface 透传的两个类型是整个上传体系的契约业务方按它组织配置与监听事件。5.1Config实例级配置关键字段完整定义见 index.ts#L59-L113字段类型说明userId/appIdstring/number必填用户与空间标识stsTokenSTSToken?实例级 STS 凭证也可在addFile时按文件传入region枚举cn-north-1、ap-singapore-1、us-east-1、gcp等imageHost/imageFallbackHoststring?图片 host 与回退 hostadapter 实际消费这两个字段videoHost/videoFallbackHoststring?视频 host本 adapter 未透传供接口层其他实现使用schemastring?协议 schemahttps/http需按部署环境动态获取useFileExtension/uploadTimeoutboolean?/number?是否使用文件后缀 / 上传超时adapter 透传项imageConfigImageConfig?{ serviceId, processAction? }图片处理动作链如CaptionUpload、EncryptionuploadSliceCount/getSliceFunc/uploadHttpMethod—分片上传相关调优skipDownload/skipMeta/skipCommit/clientEncrypt/enableDiskBreakpointboolean?跳过下载视频、跳过元信息图片、跳过 commit、客户端加密、断点续传等开关STSToken结构为AccessKeyId、SecretAccessKey、SessionToken、ExpiredTime、CurrentTime五元组index.ts#L17-L23processAction的Action.name支持GetMeta、StartWorkflow、Snapshot、Encryption、AddOptionInfo、CaptionUploadindex.ts#L32-L41。5.2EventPayloadMaps事件载荷映射export interface EventPayloadMaps { complete: CompleteEventInfo; // 含 uploadResult: UploadResult progress: ProgressEventInfo; stream-progress: StreamProgressEventInfo; error: ErrorEventInfo; }四类事件的公共载荷BaseEventInfo携带startTime/endTime/stageStartTime/stageEndTime/duration时间戳、fileSize、key、oid、percent、stage、status1 运行 / 2 取消中 / 3 暂停、extra.message与extra.errorCode等index.ts#L184-L222。complete事件的uploadResult结构因文件类型而异图片返回ImageUri、ImageWidth/ImageHeight、ImageMd5、FileName视频返回Vid、VideoMeta、PosterUri文件返回ObjectMetaUploadResult 定义。对业务侧来说监听上传完成的最小可用写法是const uploader getUploader(config, isOversea); uploader.on(complete, (info) { // info.uploadResult.ImageUri / info.uploadResult.Vid ... console.log(info.key, info.uploadResult); }); uploader.on(progress, (info) { console.log(上传进度 ${info.percent}%); }); uploader.on(error, (info) { console.error(info.extra.errorCode, info.extra.message); }); uploader.addFile({ file, stsToken }); uploader.start();六、测试与工程化单元测试位于tests/index.test.ts通过vi.mock(tt-uploader)替换底层 SDK覆盖 region 选择国内/海外、imageHost 前缀剥离与回退、空值兜底、addFile透传共 6 个用例是验证适配层行为契约的唯一依据脚本package.jsonrushx test等价于vitest --run --passWithNoTests另有test:covv8 覆盖率与lintESLint工具链遵循 monorepo 规范coze-arch/eslint-config、coze-arch/ts-config、coze-arch/vitest-config均为workspace:*内部包测试使用vitest/coverage-v8与sucrase转换Vitest 版本锁定在~3.0.5。七、小结coze-studio/uploader-adapter展示了 Coze Studio 前端处理底层云上传 SDK的典型分层方式接口层coze-arch/uploader-interface沉淀Config、事件载荷等纯类型契约SDK 层tt-uploader1.5.0负责真正的分片上传、STS 鉴权与断点续传适配层本包以getUploader工厂收敛环境差异region、schema、imageHost 回退并以统一的addFile(FileOption)面向业务暴露 API。对需要在 Coze Studio 内接入上传能力的开发者核心动作就是实现方提供Config含userId/appId/imageHost与每次上传的STSToken通过getUploader(config, isOversea)拿到实例后addFilestart再按EventPayloadMaps监听complete/progress/error事件即可。【免费下载链接】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），仅供参考 
长河君 · 2026/9/13 6:54:29 · 阅读 1.2k Coze Studio uploader-adapter 包解析：用适配层统一 tt-uploader 上传 SDK 的接入方式
Coze Studio uploader-adapter 包解析用适配层统一 tt-uploader 上传 SDK 的接入方式【免费下载链接】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-studiocoze-studio/uploader-adapter是 Coze Studio 前端 monorepo 中的上传适配包它的职责是把字节系上传 SDKtt-uploader封装成一个面向业务侧的统一入口getUploader并在其上重新导出标准配置与事件类型。本文结合该包的 README、源码与单元测试完整讲解它的安装方式、核心 API、配置语义与事件模型以及测试用例如何验证 region 选择与 imageHost 回退等关键行为。一、包的定位一个薄适配层从 package.json 可以看到这个包的全部运行时依赖只有两个tt-uploader1.5.0真正的上传 SDK火山/字节对象存储上传coze-arch/uploader-interfaceworkspace:*monorepo 内部的纯类型包定义Config、STSToken、EventPayloadMaps等接口。也就是说adapter 本身不实现任何上传逻辑而是做三件事按部署环境国内/海外决定 region构造tt-uploader实例用统一的FileOption入参包装底层addImageFile调用重新导出Config、EventPayloadMaps两个类型让业务方只依赖 adapter而不直接耦合底层 SDK 的类型定义。包的入口文件是 src/index.ts与main: src/index.ts的声明一致即以 TypeScript 源码形式被消费配合 Rush monorepo 的源码直用模式build脚本为exit 0占位。二、安装与引入方式按 README 的说明在 monorepo 内的消费方包中按如下方式声明依赖{ dependencies: { coze-studio/uploader-adapter: workspace:* } }然后在仓库根目录执行rush update导入用法README 中的模板 源码实际导出import { getUploader } from coze-studio/uploader-adapter; // adapter 实际导出的内容 // - getUploader(config, isOversea?): CozeUploader // - 类型FileOption、CozeUploader // - 透传类型Config、EventPayloadMaps来自 coze-arch/uploader-interface源码中的完整导出清单见 src/index.ts 末尾的export { type Config, type EventPayloadMaps } from coze-arch/uploader-interface与 README API Reference / Exports 一节列出的type Config, type EventPayloadMaps一致。三、核心 APIgetUploader工厂函数getUploader(config: Config, isOversea?: boolean)是整个包的唯一运行时导出其实现要点如下源码 src/index.ts#L33-L653.1 region 的自动选择region: isOversea ? ap-singapore-1 : cn-north-1,第二参数isOversea决定使用新加坡还是北京 region。单元测试tests/index.test.ts#L66-L84分别验证了两种调用默认调用得到region: cn-north-1传入true得到region: ap-singapore-1。值得注意的一个细节src/下还有一个 utils.ts定义了更大的 region 映射表export const REGION_MAP { cn-north-1: cn-north-1, ap-singapore-1: ap-singapore-1, // Volcengine has no va environment us-east-1: ap-singapore-1, };即us-east-1会被归一到新加坡。从源码结构看该映射表目前未被index.ts引用index.ts内采用三元表达式硬编码属于为更细粒度 region 选择预留的工具函数。3.2 imageHost 的解析与 schema 兼容const imageHost ( config.imageHost || config.imageFallbackHost || ).replace(/^https:\/\//, config.schema ? ${config.schema}:// : );这段逻辑有三层语义且每一层都被单元测试覆盖场景行为测试用例imageHost https://img.example.com剥掉https://前缀得到img.example.comshould strip https:// from imageHost缺少imageHost提供imageFallbackHost回退到fallback.example.comshould fallback to imageFallbackHost...两者都缺失使用空字符串should use empty string if no imageHost or fallback剥掉协议前缀后如果配置了config.schema见 uploader-interface 的 Config.schema 注释schema 需根据当前用户部署环境动态获取仅支持https与http两个值则再拼回对应的${schema}://前缀否则保持无协议形式。这样做的目的是让最终 URL 的协议跟随部署环境比如本地 HTTP 调试而不是被写死为 HTTPS。3.3 透传给 tt-uploader 的完整配置工厂函数最终执行new Uploader({...})透传的字段为{ schema: config.schema, region, // 由 isOversea 推导 imageHost, // 上面解析后的 host appId: config.appId, userId: config.userId, useFileExtension: config.useFileExtension, uploadTimeout: config.uploadTimeout, imageConfig: config.imageConfig, }测试用例 should create uploader with correct config (domestic)index.test.ts#L66-L77断言了这组入参其中未提供的useFileExtension、uploadTimeout、imageConfig均为undefined。四、addFile的统一封装adapter 在构造出的Uploader实例上覆写了addFilesrc/index.ts#L54-L63uploader.addFile function (options: FileOption) { const imageOptions: ImageXFileOption { file: options.file, stsToken: options.stsToken, }; return originalAddImageFile(imageOptions); };设计意图业务侧只需传fileBlob和stsToken两个核心字段adapter 负责将其转换为底层 SDK 的ImageXFileOption并调用addImageFile。测试用例 addFile should call addImageFile with correct params 验证了入参原样透传、返回值文件 key如mock-key原样返回。adapter 自定义的FileOption比透传字段更宽src/index.ts#L24-L31保留了type、callbackArgs、testHost、objectSync等可选字段与 uploader-interface 中的 FileOption含type?: video | image | object、serviceType?: vod | imagex等在命名上保持一致便于未来扩展视频/对象直传。CozeUploader类型则声明了 adapter 实例的完整能力面type UploadEventName complete | error | progress | stream-progress; export type CozeUploader Uploader { addFile: (options: FileOption) string; removeAllListeners: (eventName: UploadEventName) void; };即继承tt-uploader的Uploader全部方法start、pause、cancel、removeFile、refreshSTSToken、on/once/removeListener等可参考 uploader-interface 的 BytedUploader 接口 了解完整方法签名约定并叠加适配层覆写的addFile。五、配置与事件类型Config与EventPayloadMapsadapter 从 coze-arch/uploader-interface 透传的两个类型是整个上传体系的契约业务方按它组织配置与监听事件。5.1Config实例级配置关键字段完整定义见 index.ts#L59-L113字段类型说明userId/appIdstring/number必填用户与空间标识stsTokenSTSToken?实例级 STS 凭证也可在addFile时按文件传入region枚举cn-north-1、ap-singapore-1、us-east-1、gcp等imageHost/imageFallbackHoststring?图片 host 与回退 hostadapter 实际消费这两个字段videoHost/videoFallbackHoststring?视频 host本 adapter 未透传供接口层其他实现使用schemastring?协议 schemahttps/http需按部署环境动态获取useFileExtension/uploadTimeoutboolean?/number?是否使用文件后缀 / 上传超时adapter 透传项imageConfigImageConfig?{ serviceId, processAction? }图片处理动作链如CaptionUpload、EncryptionuploadSliceCount/getSliceFunc/uploadHttpMethod—分片上传相关调优skipDownload/skipMeta/skipCommit/clientEncrypt/enableDiskBreakpointboolean?跳过下载视频、跳过元信息图片、跳过 commit、客户端加密、断点续传等开关STSToken结构为AccessKeyId、SecretAccessKey、SessionToken、ExpiredTime、CurrentTime五元组index.ts#L17-L23processAction的Action.name支持GetMeta、StartWorkflow、Snapshot、Encryption、AddOptionInfo、CaptionUploadindex.ts#L32-L41。5.2EventPayloadMaps事件载荷映射export interface EventPayloadMaps { complete: CompleteEventInfo; // 含 uploadResult: UploadResult progress: ProgressEventInfo; stream-progress: StreamProgressEventInfo; error: ErrorEventInfo; }四类事件的公共载荷BaseEventInfo携带startTime/endTime/stageStartTime/stageEndTime/duration时间戳、fileSize、key、oid、percent、stage、status1 运行 / 2 取消中 / 3 暂停、extra.message与extra.errorCode等index.ts#L184-L222。complete事件的uploadResult结构因文件类型而异图片返回ImageUri、ImageWidth/ImageHeight、ImageMd5、FileName视频返回Vid、VideoMeta、PosterUri文件返回ObjectMetaUploadResult 定义。对业务侧来说监听上传完成的最小可用写法是const uploader getUploader(config, isOversea); uploader.on(complete, (info) { // info.uploadResult.ImageUri / info.uploadResult.Vid ... console.log(info.key, info.uploadResult); }); uploader.on(progress, (info) { console.log(上传进度 ${info.percent}%); }); uploader.on(error, (info) { console.error(info.extra.errorCode, info.extra.message); }); uploader.addFile({ file, stsToken }); uploader.start();六、测试与工程化单元测试位于tests/index.test.ts通过vi.mock(tt-uploader)替换底层 SDK覆盖 region 选择国内/海外、imageHost 前缀剥离与回退、空值兜底、addFile透传共 6 个用例是验证适配层行为契约的唯一依据脚本package.jsonrushx test等价于vitest --run --passWithNoTests另有test:covv8 覆盖率与lintESLint工具链遵循 monorepo 规范coze-arch/eslint-config、coze-arch/ts-config、coze-arch/vitest-config均为workspace:*内部包测试使用vitest/coverage-v8与sucrase转换Vitest 版本锁定在~3.0.5。七、小结coze-studio/uploader-adapter展示了 Coze Studio 前端处理底层云上传 SDK的典型分层方式接口层coze-arch/uploader-interface沉淀Config、事件载荷等纯类型契约SDK 层tt-uploader1.5.0负责真正的分片上传、STS 鉴权与断点续传适配层本包以getUploader工厂收敛环境差异region、schema、imageHost 回退并以统一的addFile(FileOption)面向业务暴露 API。对需要在 Coze Studio 内接入上传能力的开发者核心动作就是实现方提供Config含userId/appId/imageHost与每次上传的STSToken通过getUploader(config, isOversea)拿到实例后addFilestart再按EventPayloadMaps监听complete/progress/error事件即可。【免费下载链接】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），仅供参考