# PHIBABox 应用插件开发指南（API v1）

适用版本：PHIBABox 0.4.0 起，macOS 12.0 及以上。应用插件与 Chrome / Edge 浏览器采集扩展是两种不同格式。

## 在线获取

- [下载本开发指南](https://phiba.jdad.online/downloads/PHIBABox-Plugin-Development-v1.md)
- [下载完整开发套件（含文档、类型定义、示例和打包脚本）](https://phiba.jdad.online/downloads/PHIBABox-PluginSDK-v1.zip)

PHIBABox 0.4.37 起，在「设置 → 插件扩展 → 打开插件商店 → 开发中心」中通过默认浏览器下载指南和 SDK，也可离线导出应用内置的开发套件。

## 在插件商店发布

先在 PHIBABox 中测试插件，再用 SDK 的 `scripts/package-extension.py` 打包成 ZIP。在插件商店的「开发中心」点击「发布插件」，创建并备份投稿凭证，随后上传并送审。首次和后续版本都需审核，后续版本请使用原项目的凭证，并提高版本号。名称和作者要与清单完全一致。商店按声明的最低应用版本选择兼容的版本。[发布插件](https://phiba.jdad.online/phibabox/plugins/submit/)


## 1. 运行方式

插件是 HTML、CSS、JavaScript 组成的本地目录包，由 App 内置 WebKit 在独立、非持久化网页环境中运行。无需 Xcode、Node 或编译器。可制作批量标签、分类工具、素材统计、信息整理等功能。App 注入 `window.phibabox`，所有资料库操作通过声明并获准的 API 完成。

首版只支持用户主动打开的插件界面，不提供后台常驻、自动事件订阅、远程网络、原生可执行程序、任意磁盘访问、原图文件路径、删除素材或直接调用用户 AI 密钥的能力。图片预览可通过授权接口取得。网络调用和后台插件可在后续 API 版本扩展；不要把远程 SDK 或 CDN 依赖用于 API v1。

## 2. 快速开始

在插件商店「开发中心」点击「导出开发套件」取得文档、类型定义、示例和打包脚本，或点击「安装示例插件」并确认权限。

1. 复制 `PluginSDK/examples/TagTools.phibaplugin`，修改 `manifest.json` 的 ID、名称、作者与版本。
2. 编辑 `index.html`、`style.css`、`app.js`，使用普通浏览器查看纯界面，宿主 API 需要在 App 中测试。
3. 打开 PHIBABox → 设置 → 插件扩展 → 从文件夹安装，选择该文件夹。ZIP 需要先解压。
4. 检查安装权限，点击“同意并安装”。安装成功后启用并点击“打开插件”。
5. 在图库中先选中素材，再打开示例插件，点击读取当前选择。可以添加标签、创建文件夹、添加分类。

安装时复制代码到应用支持目录；修改开发源目录不会自动改变已安装插件。调试新代码时提升版本号并重新安装。无需重启或重打包 App。

### 图库右键入口（0.4.3+）

已安装、已启用并声明 `assets.read` 的插件会直接出现在图片的右键菜单中，例如“使用 PHIBABox 抠图助手”。现有插件无需修改即可使用该入口；设置页仍用于首次安装、权限管理与启停。

从右键启动时，`assets.selection` 固定返回这次选中的图片，混选的视频和链接不会传入；不会因后台导入改变图库选择而切换处理目标。用户关闭插件后，可右键另一组图片重新启动。在设置页打开插件时仍读取图库实时选择。插件运行期间暂不允许切换资料库或安装应用更新，已提交的写入仍按原有保存流程完成。

## 3. 插件目录与清单

```text
my-plugin.phibaplugin/
  manifest.json
  index.html
  app.js
  style.css
  images/
    icon.png
```

```json
{
  "manifestVersion": 1,
  "apiVersion": 1,
  "id": "com.example.my-plugin",
  "name": "我的素材工具",
  "version": "1.0.0",
  "author": "开发者名称",
  "description": "为选中素材添加标签",
  "entry": "index.html",
  "permissions": ["assets.read", "assets.write"]
}
```

示例中的字段均必填。另可声明 `minAppVersion`，格式与 `version` 一致。商店用此值和发布时填写的最低应用版本选择兼容版本。`id` 使用反向域名形式，小写英文字母开头，各段仅小写字母、数字、连字符，最多 120 字符。`version` 是三段整数，每段最多六位。ID 一旦发布保持稳定；更新时版本必须严格提高。名称最多 80 字符，作者最多 120 字符，说明最多 1000 字符。`entry` 是包内 HTML 相对路径，不能有 `..`、绝对路径、反斜线或 URL。

清单不超过 64 KiB；包最多 1000 个文件及目录，文件内容合计 20 MiB，单文件 5 MiB。允许 html、js、css、json、png、jpg、jpeg、svg、webp、gif、txt、woff、woff2、ico。不支持点号开头的隐藏文件、隐藏目录或入口（Finder 的 .DS_Store 会忽略）。禁止符号链接、可执行文件及保留文件 `.phibabox-install.json`。

## 4. 权限

| 权限 | 能力 |
| --- | --- |
| `assets.read` | 素材信息、当前选择、最多 512 像素 JPEG 预览 |
| `assets.write` | 修改手动标签与手动批注 |
| `folders.read` | 文件夹名称、ID 和父文件夹 ID |
| `folders.write` | 创建文件夹，将素材添加到已有文件夹 |
| `clipboard.write` | 写入系统剪贴板，不支持读取 |
| `images.process` | 读取原图并执行本机主体抠图（0.4.2+，macOS 14+） |
| `images.write` | 保存透明 PNG、替换和恢复本库原素材（0.4.2+） |
| `storage` | 读写插件独立 JSON 设置，最多 64 KiB |

首次安装与本地安装会展示权限清单。商店更新增加权限时，需要确认新增权限。同 ID 更新保留插件启用状态和独立数据。安装、更新和卸载前，请关闭此插件的所有窗口。每次 API 调用再次检查安装状态、启用状态、版本清单及权限。没有声明的权限会导致 Promise 拒绝。

## 5. JavaScript SDK

宿主在入口文档执行前注入只读 `window.phibabox`。不需要自行安装 SDK。

```js
const info = await window.phibabox.call('app.info');
const selected = await window.phibabox.call('assets.selection', { limit: 100 });
for (const asset of selected.items) {
  await window.phibabox.call('assets.update', {
    id: asset.id,
    tags: [...new Set([...asset.tags, '已整理'])]
  });
}
```

所有调用返回 Promise；使用 `try/catch` 展示错误。每个运行窗口同一时刻仅处理一个请求，请串行 `await`，不要使用 `Promise.all` 并发宿主 API。关闭插件后不再接收新调用；已经提交的写入会按应用保存流程完成。外层消息参数上限 128 KiB。

类型定义位于 `PluginSDK/phibabox.d.ts`，可在开发工程中引用；打包时不要将 TypeScript 源文件或 node_modules 放入插件包。运行文件必须为编译后的 JavaScript。需要使用 `textContent` 等方式展示素材名称，避免把用户输入直接插入 HTML。

## 6. API 参考

### app.info

无需权限。参数 `{}`。

返回 `{name, version, apiVersion: 1, libraryOpen}`。开发构建的 version 为 `development`。

### assets.list / assets.selection

权限：`assets.read`。参数 `{offset?: 0, limit?: 100}`。limit 限制为 1–200。`assets.selection` 仅返回当前选中素材，未选择时是空数组，不自动切换为全库。

返回 `{items, total, offset}`。`assets.list` 读取当前库全部素材，按库中顺序分页，与当前图库筛选无关。需要完整处理时依次请求分页；读取过程中用户可能修改库，没有跨分页事务快照。

每个素材：

```js
{
  id: 'UUID', name: '素材名称', kind: 'image',
  width: 1920, height: 1080, createdAt: '2026-11-04T00:00:00Z',
  folderIDs: [], tags: [], note: '', aiTags: [], aiAnnotation: '', favorite: false
}
```

kind 为 `image`、`video`、`link`。不返回文件路径、Eagle 引用、采集来源地址或密钥。AI 字段只读。

### assets.thumbnail

权限：`assets.read`。参数 `{id: '素材 UUID'}`。返回 `{dataURL: 'data:image/jpeg;base64,...'}`，最长边最多 512 像素的 JPEG 预览，视频返回缩略图，链接不支持。可设置 `img.src` 或在 Canvas 处理；预览不代表原图，JPEG 不保留透明通道。

### assets.update

权限：`assets.write`。参数 `{id, tags?, note?}`，至少提供 tags / note 之一。tags 最多 100 个，每个最多 100 字符；note 最多 10000 字符。提供的字段替换对应手动字段，未提供的保持不变。清空用 `tags: []` 或 `note: ''`。

返回 `{ok:true}`。要追加标签，请先读取旧标签并合并。本接口不修改原文件、AI 标签、收藏或素材名称。图片处理须使用独立的 images.* API 和权限。写入使用宿主保存队列，持久化成功后才返回；失败会抛出错误并沿用宿主回滚机制。单个请求保存独立完成，多个请求不是整批事务。

### folders.list

权限：`folders.read`。参数 `{}`。返回 `[{id, name, parentID: null | 'UUID'}]`。需要层级路径时使用 parentID 递归组装，并处理循环保护。

### folders.create

权限：`folders.write`。参数 `{name, parentID?: null | 'UUID'}`。name 非空，最多 100 字符。返回 `{id:'新文件夹 UUID'}`。不自动处理同名文件夹，插件应先查询和判断。

### folders.assign

权限：`folders.write`。参数 `{folderID, assetIDs: ['UUID']}`，一次 1–200 项。返回 `{ok:true}`。仅添加分类关系，保留素材已有分类；不会移动或复制原文件。素材或目标文件夹不存在时整次调用失败。

### clipboard.write

权限：`clipboard.write`。参数 `{text}`，UTF-8 最多 64 KiB。返回 `{ok:true}`。

### storage.get / storage.set

权限：`storage`。get 参数 `{}`，返回插件独立 JSON 对象，首次为 `{}`。set 参数 `{value: {...}}`，替换整个对象，最多 64 KiB，返回 `{ok:true}`。数据按插件 ID 隔离，不随当前资料库切换。

不要使用浏览器 localStorage 保存重要设置：插件网页数据使用非持久化环境。卸载保留独立设置，重装同 ID 可恢复；清理设置可以调用 set 写入空对象。用户可在 Finder 中删除对应 ExtensionData 子目录，但应先关闭插件。

### images.beginBatch / images.endBatch（批量会话能力）

权限：`images.process`。调用前检查 `app.info.capabilities['images.batchSession']`。

begin 参数 `{}`，返回 `{automaticAIPaused:true}`：宿主暂时关闭“自动分析新素材”，取消并等待正在进行的自动分析释放资料库；不会取消手动分析。每个插件会话只允许一个批量任务。结束、停止或失败时在 finally 中调用 end，参数 `{}`，返回 `{ok:true}`。关闭插件或插件网页进程退出时宿主也会恢复原设置；原本关闭的开关仍保持关闭。嵌套或多个会话不会提前恢复开关。批量期间生成的 PNG 不自动加入 AI 分析队列。

`assets.thumbnail` 新增可选参数 `preserveAlpha:true`，返回透明 PNG；通过 `capabilities['assets.transparentThumbnail']` 检查。默认仍为 JPEG。批量结果只保留保存后的素材 ID，点击时读取缩略图，不累积完整分辨率图像。

### images.cutout（0.4.2+）

权限：`images.process`。参数 `{id, crop?: false}`。需要 macOS 14+，使用本机 Vision，不上传图片。支持单帧静态图片，文件不超过 64 MiB、尺寸不超过 2500 万像素。返回 `{token, previewDataURL, width, height, canReplace}`；previewDataURL 是最多 512 像素的透明 PNG 预览，完整分辨率结果留在宿主内存中。

`crop` 为 true 时裁剪至已识别主体的边缘；默认保留原画布。保留所有识别到的前景实例，不保证每张图片都能准确识别。生成结果不改动资料库。每个运行窗口仅保留一个待保存结果；令牌 15 分钟后过期，关闭插件或开始新处理后失效。令牌绑定当前资料库和源素材，不接受插件自行传入 PNG、文件路径或原始数据。

### images.saveCutout（0.4.2+）

权限：`images.write`。参数 `{token, mode: 'copy' | 'replace'}`。返回 `{assetID, restoreToken: null | string, mode}`。

copy：另存为 PNG 新素材，继承原分类、手动标签和批注，保持原图不变；新素材不继承收藏、堆叠、采集请求 ID 或旧 AI 分析。如果打开了自动分析开关，新素材会进入分析队列。

replace：当前本地素材保持 ID、分类、手动信息、收藏和堆叠，媒体路径变为新的 PNG；旧文件和恢复记录保留。重新提取颜色，清空旧 AI 分析。Eagle 共用素材禁止替换，仅允许 copy。保存前会验证原文件内容是否与抠图时一致，变化时要求重新处理。

### images.restoreOriginal（0.4.2+）

权限：`images.write`。参数 `{restoreToken}`。返回 `{assetID}`。仅允许同一插件在原资料库中恢复对应替换，且素材仍引用那次替换的 PNG；后续再次替换后旧令牌不可用。恢复原图尺寸、颜色与旧 AI 信息，保留当前分类、手动标签和批注。恢复凭据可放入插件 storage；插件代码更新或重启后也可恢复。

替换和恢复会刷新图片缓存。为了保证恢复和资料库元数据备份仍可读取，原文件及处理结果保留在本库 media 目录，恢复记录在 `.cutout-backups`。请勿手工清理这些记录引用的文件；它们也会占用磁盘空间。写入任务纳入 App 退出等待。抠图时不阻止其他浏览操作，实际写入时需等待当前资料库或 AI 任务结束。

通过 `app.info` 的 `capabilities['images.cutout']` 判断是否支持本机抠图。旧版 App 没有此字段；返回 false 时提示升级 App / 系统。API v1 的这些方法是可选能力，不影响原有插件。

## 7. 页面与隔离规则

入口通过 `phibaplugin://runtime/` 加载，只允许包内资源。禁止远程脚本、CDN、fetch/WebSocket 访问、iframe、弹窗、表单外部提交与跳转。脚本必须存为本地 `.js` 并由 `<script src="app.js">` 引入；禁止内联脚本、onclick HTML 属性、eval 和 new Function。样式支持本地 CSS 与内联 style。

应用不会提供 Node.js、Electron、require、文件系统或 shell。通过 API 读取资料库与预览；不要尝试猜测本地文件路径。插件仍可能利用获准的写入接口修改大量资料，因此应遵循最小权限并给破坏性批量操作提供插件自身的确认界面。

## 8. 调试、打包与分发

在项目根目录运行：

```sh
python3 scripts/package-extension.py PluginSDK/examples/TagTools.phibaplugin
```

工具检查清单、文件类型、体积与链接，输出 `dist/plugins/online.phiba.tag-tools-1.0.0.zip`。ZIP 包含单个 `.phibaplugin` 目录。向用户分发 ZIP，用户解压后在 App 里安装该目录。

更新：保持 ID 不变，提高版本号，重新分发插件包，用户使用“安装插件”选择新目录。应用保留旧版启用状态及独立设置，升级失败时保留旧版。首版不提供第三方插件市场或自动联网更新源；浏览器采集插件继续使用原有独立更新入口。

本机代码位置：`~/Library/Application Support/PHIBABox/Extensions/<id>/`。
独立设置位置：`~/Library/Application Support/PHIBABox/ExtensionData/<id>/storage.json`。

常见错误：未授权先检查 permissions；请先打开资料库；资料库忙时稍后重试；同版本不能覆盖，必须提高版本；API 找不到 window.phibabox 时请在 App 内打开插件。错误通过 Promise rejection 返回，示例会在页面底部显示。

发布前至少验证：全新安装、未开库、无选择、多选、标签追加、文件夹不存在、启停、卸载重装、版本升级、权限变更、保存失败与停止运行。API v1 只支持当前 macOS 客户端；Windows 客户端尚未集成本扩展系统。


### 裁剪助手（PHIBABox 0.4.34 起）

在插件商店的「官方」分类中安装裁剪助手。选择图片后，从右键菜单打开「PHIBABox 裁剪助手」。拖动四角自由裁剪，按住 Command 保持比例；用户选择另存或替换，替换后可恢复原图。

`images.cropPreview({id})` 需要 `images.process` 权限，返回 token、dataURL、原图 width/height 和 canReplace。`images.saveCrop({token,mode,rect})` 需要 `images.write` 权限；mode 为 copy 或 replace，rect 为基于原图左上角的归一化 x/y/width/height。保存使用原图分辨率，返回 assetID、width、height 和 restoreToken。使用 `images.restoreOriginal({restoreToken})` 恢复替换前的图片。

PHIBABox 0.4.36 起，裁剪不再要求透明通道，也不再套用抠图流程的 64 MiB 文件、2500 万像素输入/输出门槛。系统能够解码且本机资源允许的静态图片可按原像素裁剪，输出仍为 PNG。抠图 API 的输入和透明输出要求独立保留。
