受控对象上传

platform:object-upload 让插件在宿主同源执行环境中把一个 Blob 上传到对象存储，用于证据图片、日志包等场景。清单声明 platform:object-upload 权限，代码里 await ctx.capabilities.get('platform:object-upload') 获取并判空。

当前只在驾驶舱宿主能获取到这个能力，其他宿主（计划、消息、项目）会得到 undefined。运行环境要求由平台决定，不是插件可声明的。

fh2-plugin-sdk 是插件开发 SDK；下文模块名用于说明，实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。

方法清单

方法	输入	返回
`upload`	临时对象存储参数 + `blob`	`Promise<{ etag: string \| null }>`

临时对象存储参数（怎么和后端配合）

当前公共契约要求插件把短期临时上传参数传给宿主，由宿主执行受控 S3 putObject。这些参数应由你的后端在可信链路中签发，并通过 ctx.apiCall 获取；本页不指定签发接口路径。输入字段为：

interface ObjectUploadCredentials {
  readonly endpoint: string
  readonly bucket: string
  readonly region: string
  readonly objectKey: string
  readonly accessKeyId: string
  readonly secretAccessKey: string
  readonly securityToken: string
  readonly usePathStyle?: boolean
}

安全要求：

只接受后端为本次上传签发的短期 STS 参数，不使用长期账号或固定密钥；字段缺失时不要发起上传。

插件会接触这些临时字段。不要把它们写入日志、本地存储、诊断详情或后端以外的第三方；业务确认只传 etag 与业务对象 ID。

上传完成后，调用你的后端接口做业务确认。后端应对确认接口做幂等处理，避免确认重试造成重复记录。

宿主在上传前会做这些检查，不满足会失败：

endpoint 必须是 HTTP(S) URL；bucket 必须符合对象存储桶名规则；region、objectKey 和三个 STS 凭证字段必须是非空字符串。

blob 必须是原生 Blob；大小不超过 1 GiB。MIME 类型没有额外 allowlist，宿主会按 Blob 的实际 type 设置上传 Content-Type。

usePathStyle 可选，缺省按 path-style 访问。

注意：

etag 可能为 null，不能当业务对象 ID 用；业务 ID、下载地址由插件后端接口返回。

不要持久化临时上传参数，也不要把凭证字段、完整上传地址或对象键写进日志。

生产联调前确认后端已部署短期 STS 签发接口和上传确认接口——只有前端提供方完成不了上传。

集成片段

先按第一个前端插件建立可运行工程。下面不是完整的 fh2-plugin.json，不可整份替换：将 permissions 去重合并到现有清单，保留现有宿主扩展、界面声明/注册和入口。权限不会触发激活；清单若只有 extensions: []，activate() 不会执行。

合并到 fh2-plugin.json 的字段：

{
  "permissions": ["platform:http", "platform:object-upload"]
}

下面的 definePlugin 只示范入口逻辑组织，不是可直接替换完整工程的入口；保留生成工程的 SDK 导入路径，将能力逻辑合入已有驾驶舱 activate，保留原有扩展贡献与界面注册。把 uploadEvidence 接到现有已声明扩展的截图/确认回调；短期参数签发和业务确认接口需由后端提供。

// plugin.ts
import { definePlugin } from 'fh2-plugin-sdk'

export default definePlugin({
  async activate (ctx) {
    // 当前只在驾驶舱宿主可用；其他宿主在这里停用上传入口。
    const objectUpload = await ctx.capabilities.get('platform:object-upload')
    if (!objectUpload) {
      ctx.logger.warn('受控对象上传在当前宿主或运行条件下不可用')
      return
    }

    async function uploadEvidence (
      jpeg: Blob,
      credentials: ObjectUploadCredentials,
      evidenceId: string,
    ): Promise<string> {
      if (jpeg.type !== 'image/jpeg') throw new Error('证据文件必须是 JPEG')
      const { etag } = await objectUpload.upload({
        endpoint: credentials.endpoint,
        bucket: credentials.bucket,
        region: credentials.region,
        objectKey: credentials.objectKey,
        accessKeyId: credentials.accessKeyId,
        secretAccessKey: credentials.secretAccessKey,
        securityToken: credentials.securityToken,
        usePathStyle: credentials.usePathStyle,
        blob: jpeg,
      })
      await ctx.apiCall('/evidence/upload-complete', {
        method: 'POST',
        body: { evidenceId, etag },
        idempotencyKey: `complete-${evidenceId}`,
      })
      return evidenceId
    }

    // 实际业务应把该函数接到明确的截图/确认动作，而不是后台自动上传。
    ctx.logger.debug('证据上传器就绪', { uploadEvidence: typeof uploadEvidence === 'function' })
  },
})

错误与生命周期

宿主卸载会中止进行中的上传，后续调用以 HOST_RUNTIME_DISPOSED 失败；对象存储请求失败包装为 PLUGIN_GATEWAY_ERROR。错误码见错误码。

上传成功但业务确认失败时，应由后端幂等确认或回收任务处理，不能只靠前端重传。

常见问题

现象	原因与处理
`get()` 返回 `undefined`	当前宿主不提供该能力（目前仅驾驶舱）；该宿主隐藏上传入口即可
上传被拒绝	核对临时参数是否完整、endpoint 是否为 HTTP(S)、bucket 是否合法、Blob 是否超过 1 GiB
拿不到下载地址	`etag` 不是业务 ID；下载地址由插件后端返回
离开驾驶舱后上传中断	宿主卸载会中止请求，属预期行为；业务侧重试需重新签发短期上传参数

方法清单#

临时对象存储参数（怎么和后端配合）#

集成片段#

错误与生命周期#

常见问题#

方法清单

临时对象存储参数（怎么和后端配合）

集成片段

错误与生命周期

常见问题