Host API 参考

在 component.sidePanel 中声明 fileHandler.extensions。用户打开匹配文件时，宿主按单击／双击偏好打开标准工具面板，并使用清单中的插件图标。

{
  "type": "component.sidePanel",
  "id": "open-document",
  "label": "打开文档",
  "pageId": "document-page",
  "contextMenu": "none",
  "fileHandler": {
    "extensions": [
      ".example"
    ]
  },
  "rpcMethods": [
    "document.open.v1"
  ]
}

“用默认方式打开”始终绕过插件；此声明不改变系统文件关联。停用或卸载插件后，接管与图标自动撤销。

只有 UI context 包含 contributionId；服务公开 context 不包含。操作类型通过 RPC payload 显式传递，服务按已声明操作再次校验。

component.sidePanel 页面可以直接调用 window.photoFlowComponent.openPanelWindow()。它返回 Promise<{ windowId: number }>，在独立原生窗口创建同一入口的第二个实例，原面板继续保留。

const host = window.photoFlowComponent;
if (typeof host.openPanelWindow === 'function') {
  const { windowId } = await host.openPanelWindow();
  console.log('已打开插件窗口', windowId);
}

新实例继承来源面板的项目、目录和安全选择上下文，沿用组件沙箱与该入口的 RPC 白名单。窗口显示插件图标、名称和系统最小化、最大化、关闭按钮，正文只加载插件面板。该方法只用于侧面板实例，不向普通应用页面开放，也不额外授予文件访问权限。

在 componentHost.contributions 中声明 application.homeCard，可在首页内置卡片旁提供插件入口。pageId 必须引用同一清单里的 component.fullPage；rpcMethods 必须属于服务已声明的方法。

{
  "type": "application.homeCard",
  "id": "open-studio",
  "label": "插件名称",
  "description": "打开插件工作区",
  "pageId": "studio-page",
  "rpcMethods": [
    "studio.open.v1"
  ]
}

顶层 icon 和 displayName 提供卡片图标及窗口标题。每次点击会创建独立页面实例；只声明首页卡片和 fullPage 的页面插件也有效，不必再添加工具栏或侧面板入口。

首页卡片使用 context.surface === 'application.homeCard'，没有项目或文件选择。RPC 受该入口的白名单限制，Host 能力沿用应用命令权限：可以使用已授权的应用级能力及网络请求，不能读写项目文件。

工具菜单支持 workspace.videoTools（视频工具）、workspace.imageTools（图片工具）和 workspace.officeTools（Office 文档）。component.sidePanel 和 project.contextAction 可以选择这些位置，同时出现在文件选择右键菜单的对应分组中。可通过 selection 声明数量、类型和后缀筛选，服务仍需校验输入。

灵感库入口的 contentKind 为 inspiration，项目入口为 project。灵感库不提供项目版本树和进度操作。目录或选择变化时，通过 onContextChange 更新页面内容。

如果插件只声明 application.settingsForm，且所有表单都没有 customPage，可以省略服务、工具页面和工具栏按钮。照片流直接显示并保存表单，不启动插件服务。名称、入口、图标和专属许可说明都应由插件清单提供。

表单可声明 notices，每条包含 title、description、license、sourceUrl 和 licenseUrl，最多 64 条。两个链接必须使用 HTTPS，且不能带用户名或密码。只展示许可时可用 groups:[]，但至少要有一条 notice。

提供标准视频播放后端的插件，可在表单中设置 preferenceScope:"videoPlayback"，直接读取和保存共享播放器的 HDR 偏好。只开放 hdrMode、toneMapping 和 targetPeakNits，不允许访问其他应用配置。

hdrMode 和 toneMapping 使用 select；targetPeakNits 使用 number 或 range，范围限制在 100–4000。选项还必须符合清单中播放后端声明的能力，例如 HDR 直通或对应的色调映射算法。普通表单仍保存到插件自己的设置中。

声明 component.panel 接口和同名权限后，页面可调用 host.setPanelInfo({title, subtitle})。服务也可调用 component.panel 的 get/update。标题为 1–160 个字符，副标题最多 240 个字符，均为纯文本；只能修改当前文件夹面板。固定、关闭和排序按钮由照片流提供。

浮动工具面板由宿主测量正文高度，最高为 90vh；文件夹常驻面板则使用文件页分配的空间。不要在插件正文中重复绘制标题栏或关闭按钮。

页面使用 host.notify，服务使用 notifications。

通知格式为 {tone,message,dedupeKey?}。tone 可选 info/success/warning/error，消息最多 360 个字符；可用 dedupeKey 避免重复提示。错误通知由用户关闭，其他通知约 3.5 秒后消失。内容必须是纯文本，不能包含 HTML、路径、URL 或执行命令，也不能设置 durationMs。

component.sidePanel 和 project.contextAction 可声明 selection 与 contextMenu，控制菜单可见性；服务仍须校验真实输入和访问权限。

{
  "type": "component.sidePanel",
  "id": "extract",
  "label": "解压缩",
  "pageId": "archive-page",
  "contextMenu": "root",
  "selection": {
    "minCount": 1,
    "maxCount": 20,
    "kinds": [
      "file"
    ],
    "extensions": [
      ".zip",
      ".7z"
    ]
  },
  "rpcMethods": [
    "archive.extract.v1"
  ]
}

分组位置仍使用 placement。菜单筛选不是服务授权。

project.media.page 每页返回 1–200 项，继续翻页时使用返回的 cursor（分页游标），5 分钟内有效。project.media.variants 可获取最长边 320 像素的缩略图、1600 像素的预览图或原图。传入 variants:[] 只取媒体信息；请求原图时还会得到 10 分钟有效、只能使用一次的读取令牌。

外部文件夹可通过复制、移动或引用原位置导入为项目。引用原位置时，该文件夹就是绑定项目的物理根目录，文件使用普通项目相对路径。项目内创建文件或文件夹外链的功能已删除；旧 External/... 记录、快捷方式和符号链接不能扩大读取范围，以 photoId/versionId 查询也会检查项目归属。

project.files.page 与 project.files.search 用于其他文件、目录和配套文件。project.media.metadata 返回尺寸、相机、镜头、曝光，以及视频编码、时长和帧率等信息；没有的数据返回 null。结果使用项目相对路径，不返回电脑上的绝对路径。

project.versions.page 和 project.version.graph 通过只读快照返回结果，不修改项目数据或索引。评分读取一次接受 1–100 个媒体引用；supported.labels 和 supported.selectionState 为 false，对应字段为 null。

project.files.inputToken 接受 relativePath，可读取当前范围内任何格式的普通文件，包括没有后缀的文件。返回读取令牌、文件大小、SHA-256 摘要和 fileId。文件解析和编辑由插件负责。

随后调用 project.input.tokens 的 materialize，用令牌取得服务可读取的私有副本。令牌 10 分钟有效且只能使用一次，副本路径不能传给页面。可传入 expectedDigest 核对文件内容；文件发生变化时返回冲突，需重新读取。

project.files.watch 使用 subscribe → poll → unsubscribe。一次订阅 1–256 个已有文件；可见页面建议每 2–5 秒检查一次，每次保存返回的 cursor，同一订阅不要同时发起多个 poll。

事件包括 modified、renamed、deleted 和 versionChanged。按 sequence 去重；收到 rescanRequired:true 时重新核对文件。它反映文件状态，两次检查之间的多次变化可能合并，并不是完整操作记录。要读取变化后的内容，还需重新取得读取令牌。

每组件最多 16 个订阅，全宿主最多 256 个；5 分钟不调用就会过期。超过 30 秒没有轮询、游标不匹配或扫描达到上限时，都可能要求重新检查。页面释放或插件卸载时清理订阅。

component.transfer 用于插件页面与服务之间的二进制传输，不会上传到互联网。上传按 create → write → finish → close 执行；write 按 offset 顺序发送 base64，finish 用 expectedDigest 检查 SHA-256 并返回读取令牌。

下载时用 openInput 消费读取令牌，再用 read 按段读取，最后 close。上传每块原始数据最多 1 MiB，单文件及每组件活动上传合计最多 2 GiB；每组件最多 8 个会话，全宿主最多 64 个。10 分钟无操作会过期，宿主重启后需重新建立会话。

每块数据用独立 RPC 转发，避免超过单次 RPC 的 128 次嵌套接口调用限制。协议单帧仍限 2 MiB。服务已经能直接读取的文件，优先使用读取令牌或输出暂存区，减少不必要的数据传输。

声明 project.preview 和 project.preview.read 后，可调用 host.getPreview()，或用 await host.onPreviewChange(callback) 接收状态变化。返回的 video 包含 sessionId、relativePath、time、duration、paused 和 canSeek，时间单位为秒。没有可用视频时，video 为 null。

播放位置约每 250 毫秒更新一次，适合字幕高亮，不保证逐帧同步。页面隐藏或退出时，调用订阅返回的取消函数。接口仅对绑定来源文件页的项目或灵感库页面开放。

跳转还需 project.preview.control。调用 host.seekPreview(sessionId, time) 时使用刚读取的会话 ID，并先检查 canSeek。视频已切换、时间越界或不可跳转时会失败；accepted:true 表示请求被接受，实际位置以随后收到的状态为准。

在 componentHost.service.previewDecoders 中声明 id、label、extensions、method，以及可选的 priority 和 thumbnailMethod。后缀支持自定义格式，也可用 * 匹配无后缀或未知格式；插件仍需检查真实文件内容。明确后缀匹配优先于通配符。解码和缩略图方法都必须列在 service.rpcMethods 中，只能由宿主调用，不能加入普通页面的 RPC 白名单。

只提供解码器的插件可使用空的 contributions:[]。至少声明 project.input.tokens、component.transfer 两项接口，以及 project.input.read 权限。每组件最多 16 个解码器，每个最多 64 条后缀规则，priority 范围为 -100～100。

宿主传入文件读取令牌、name、extension、从 0 开始的 pageIndex 和 maxEdge（64–4096）。服务取得输入副本后解码一页 PNG，通过分块传输接口获得输出令牌，返回 {inputToken, mimeType:"image/png", pageIndex, pageCount}。

PNG 宽高均不能超过 maxEdge，文件最多 32 MiB，总页数为 1–10,000。宿主检查并重新编码后显示图片，不接收 HTML、脚本、任意 URL 或本地路径。此接口也支持下面的视频预览结果，但不提供文档编辑或交互式 3D。

插件自行解包或生成视频，通过 component.transfer 获得输出令牌。使用同一解码方法返回以下结果，无需创建插件页面：

{
  inputToken: videoToken,
  mimeType: 'video/quicktime', // MP4 使用 video/mp4
  pageIndex: 0,
  pageCount: 1
}

视频必须为第 0 页、共 1 页，容器仅支持 MOV/MP4，最大 256 MiB。maxEdge 不要求视频缩小；实际编码能否播放由公共播放器及已安装后端决定。普通 RPC 最多调用 128 次 capability，分块上传时需将 create、write、finish、close 一并计入预算，不能把容器大小上限当作单次解码请求的可上传大小。

宿主在主预览区挂载公共播放器，提供播放、暂停、跳转及播放位置通知。视频保留在私有预览缓存，不写入项目，暂不提供派生预览的截图保存。切换文件、关闭预览或停用插件后，宿主释放媒体授权和播放会话；取消等待会丢弃迟到结果，插件仍需为自身解码算法设置时间与资源上限。

视频结果可额外提供 posterInputToken（PNG 封面令牌）和 presentation: 'live-photo'。封面与视频必须使用不同的一次性令牌，封面尺寸仍受 maxEdge 限制。

{
  inputToken: videoToken,
  mimeType: 'video/mp4',
  pageIndex: 0,
  pageCount: 1,
  posterInputToken: coverToken,
  presentation: 'live-photo'
}

宿主验证封面后，以照片样式自动静音播放一次，结束后恢复封面；左上角 LIVE 按钮用于重播，不显示普通视频工具条。照片与视频的解析和配对由插件负责；没有可解码封面时，省略这两个字段，返回普通视频预览。

{
  "id": "photos",
  "label": "照片预览",
  "extensions": [".custom"],
  "method": "photo.preview.v1",
  "thumbnailMethod": "photo.thumbnail.v1"
}

thumbnailMethod 接收相同的输入令牌、pageIndex 和 maxEdge 字段；pageIndex 固定为 0，maxEdge 为 64–640，只接受 PNG 结果。若主预览方法也返回 PNG，可以复用同一方法。

文件列表、网格和版本树按可见区域请求缩略图，失败时保留系统图标。缩略图最多两个并发请求，同组件最多一个；宿主缓存最多 256 项、64 MiB，每次读取仍校验文件身份与授权，源文件改变会丢弃旧结果。缓存不写入项目，插件无需自行维护宿主缓存。

安装并启用对应解码插件后，文件才会获得预览能力。非媒体文件有匹配解码器时，点击显示预览；普通视频优先走播放器，播放失败后才尝试匹配解码器。解码失败时显示错误、重试和外部打开按钮，不自动打开外部程序；每文件页同时处理一个主预览解码请求，全宿主最多 8 个，普通服务超时为 60 秒。

中断后先按原幂等键查询。该动作绑定当前组件、工作区和项目，不发布或修改文件。

await hostCapability("project.output", {
  action: "status",
  idempotencyKey: savedOperationKey
});

missing / prepared 不表示可以直接重复不可逆操作。核对暂存区、输出和任务记录再恢复；changed 时停止覆盖并处理冲突。

新文件重名默认冲突；onConflict: "rename" 由宿主另取名称，使用返回的 relativePath。替换必须同时提供 replace: true、previousCommitId、previousArtifactId 和 expectedDigest，摘要变化时保留用户改动。

文件变更后检查 undoAvailable；遇到 outcomeUnknown 先核实实际状态，不重复删除或恢复。

output.relativeDirectory 相对绑定项目根目录，"." 表示项目根目录。从选中子文件夹执行任务时，可以输出到项目内同级目录；输入仍受来源 scope 限制，输出拒绝绝对路径、上级跳转和逃出项目的链接。

output: {private:true, argument:"--preview-root"} 会分配绑定组件、项目和来源范围的独立预览缓存目录。播放时的 privateOutputPath 必须由组件服务从自己的预览记录解析，宿主拒绝跨范围路径及链接；页面不获得任意私有文件访问权。

使用 action:"playback"，通过 relativePaths 或保留的 inputGrants 指定输入，并传入 playback 请求。source、backends、start 和 frames 均要求恰好一个已授权媒体文件；服务记录的输出还须经过项目与真实路径校验。

source 返回当前页面可用的媒体 URL；backends 返回宿主播放后端描述；start 创建属于当前页面的会话。control、bounds、stop 只操作自己的会话；frames 最多接受两个有限且非负的秒数时间点，并复用已安装的时间线帧后端。

页面通过 host.onPlaybackState(callback) 监听播放事件，并保存返回的取消订阅函数。host.setPlaybackBounds(sessionId, bounds) 是已有授权会话的单向布局更新，bounds 包含 x、y、width、height、visible；宿主裁切到组件视图并处理缩放，不会因此授予新的媒体访问权。

页面停用、被对话框遮挡或进入裁剪编辑时，应暂停并隐藏播放；销毁视图会关闭原生会话。其他播放操作仍通过服务的 capability 请求执行。

运行时执行默认超时 20 分钟，可在 1 秒至 4 小时内指定 timeoutMs。清单授权、scope、输入令牌和组件归属仍由宿主复核；灵感库任务不应请求项目产物关系登记。

插件页面使用宿主提供的播放器资源，复用主程序的播放界面、快捷键、Chromium 播放和原生后端选择。不要在插件包内复制播放器实现；每次 mount 创建独立实例。

<link rel="stylesheet" href="photoflow-player://runtime/v1/player.css">
<script src="photoflow-player://runtime/v1/player.js"></script>

在插件入口脚本之前加载资源；有 CSP 时，将 photoflow-player: 加入 script-src 和 style-src。初始化前检查 window.PhotoFlowPlayback?.apiVersion === 1，不匹配时提示更新主程序。

const player = PhotoFlowPlayback.mount(container, {
  apiVersion: 1,
  filePath: authorizedRelativeName,
  electronApi: scopedPlaybackFacade,
  onState: ({ time, duration, paused }) => updateTimeline(time, duration, paused),
  onError: message => showError(message),
});
player.playFrom(12.5);
const stoppedAt = await player.pauseAtFrame();
// 页面销毁时释放播放器及插件自己的监听器。
player.close();

示例中的 scopedPlaybackFacade 由插件适配已有授权 RPC 和 Host 播放通道，不能替换全局 window.electronAPI。它提供 getVideoPlaybackSource、getVideoPlaybackBackends、startVideoPlayer、stopVideoPlayer、controlVideoPlayer、setVideoPlayerBounds、onVideoPlayerState、getVideoDisplayCapabilities、captureVideoPlayerFrame、publishVideoPlayerFrame、chooseVideoSubtitle 和 setHostSurfaceSuspended。资源 URL 本身不授予文件或媒体访问权限。

原生窗口 bounds 使用设备像素，并附带 viewportDip 矩形；适配层应转换到组件本地 DIP，处理页面可见性、对话框遮挡与裁切后再提交。

顶层 runtimeContributions 可声明 media.playbackBackend 协议版本 1，包括 backend ID、原生进程 transport、优先级、容器/编码探测和 transforms、HDR、统计、字幕、硬解、截图能力矩阵。

使用 SDK 的 ui.css，同步更新进度填充宽度、可见百分比与 aria-valuenow；任务结束时将 aria-busy 设为 false。

<div class="pf-task-progress" aria-busy="true">
  <div class="pf-task-progress-header">
    <p class="pf-task-progress-message">正在处理</p>
    <span class="pf-task-progress-percentage">42%</span>
  </div>
  <div class="pf-progress-track" role="progressbar"
       aria-valuemin="0" aria-valuemax="100" aria-valuenow="42">
    <div class="pf-progress-fill" style="width:42%"></div>
  </div>
</div>

外框的 data-state 支持 completed、failed 和 publication-failed；取消、重试等操作放在进度旁。CSS 只负责展示，执行、取消、恢复及进度上报仍由插件与 Host tasks 完成。

COMPONENT_HOST_INVALID_REQUEST
COMPONENT_HOST_PERMISSION_DENIED
COMPONENT_HOST_NOT_FOUND
COMPONENT_HOST_TOKEN_EXPIRED
COMPONENT_HOST_TOKEN_SCOPE
COMPONENT_HOST_LIMIT_EXCEEDED
COMPONENT_HOST_VARIANT_UNAVAILABLE
COMPONENT_HOST_CONFLICT
COMPONENT_HOST_CANCELLED
COMPONENT_HOST_TIMEOUT
COMPONENT_HOST_SERVICE_EXITED
COMPONENT_HOST_INTERNAL

沙箱隔离只适用于组件 UI。service、生命周期脚本和 executable 是用户安装的受信本机代码，以当前用户的系统权限运行，可访问该用户的文件、网络和进程。Host API 权限约束正常接口调用，受监管进程不等于操作系统沙箱；应只安装可信来源的组件。

插件应通过 Host API 修改项目数据，并自行管理插件数据库。卸载插件只移除代码，不自动删除组件数据。

GET /v1/plugins 返回 { plugins: [...] }。公开读取不包含管理员凭据、文件名或本地路径。

只返回已发布记录。缓存和活动页面刷新周期为一分钟；失败清除提示且不阻止本地预览，最短重试间隔 15 秒。已有启用的解码器时不提示，快捷方式不触发提示。目录独立于遥测开关。

管理写入使用 POST /v1/admin/plugins 和管理员 Bearer Token；记录另含 published 与 updatedAt。凭据只在管理端使用，不放进插件、前端或示例。