@xiongtao.xt/tau-plugins 0.31.1 → 0.33.0

package/docs/plugin-basics.md

@@ -0,0 +1,209 @@
+# 插件的组成
+
+一个 Tau 插件由以下几部分组成：
+
+- **manifest.json**：插件是谁、需要什么。Tau 不运行代码就能读到它。
+- **入口模块**（构建后是 `main.js`）：默认导出一个插件定义，包含静态声明和运行时逻辑。
+- **样式**（构建后是 `main.css`，可选）。
+- **Skill 目录**（`skills/<id>/`，可选）：给 AI 看的使用说明，见 [Skill](skills.md)。
+
+这一篇依次讲 manifest 和入口，以及贯穿所有能力的几条规则：生命周期、`context`、ID、取消与清理。
+
+## manifest
+
+模板的 `manifest.json`：
+
+```json
+{
+  "formatVersion": 1,
+  "id": "example.external-counter",
+  "name": "计数器示例",
+  "description": "在侧边栏记录并保存计数。",
+  "categories": ["page"],
+  "keywords": ["计数", "打卡"],
+  "version": "1.0.0",
+  "minAppVersion": "0.59.0",
+  "apiVersion": 1,
+  "platform": "desktop",
+  "format": "cjs",
+  "main": "main.js"
+}
+```
+
+### 需要你填写的字段
+
+| 字段            | 说明                                                                                                      |
+| --------------- | --------------------------------------------------------------------------------------------------------- |
+| `id`            | 插件的唯一标识，由小写字母、数字组成，用点或连字符分段，例如 `yourname.counter`。发布后不要再改           |
+| `name`          | 插件名称，显示在插件页和插件中心                                                                          |
+| `description`   | 一句话简介，1 至 160 字                                                                                   |
+| `version`       | 插件版本，格式为 `主版本.次版本.修订号`，可带预发布后缀，如 `1.2.0-beta.1`                                |
+| `minAppVersion` | 需要的最低 Tau 版本，如 `0.59.0`。写完整版本号，不写 `>=`、`^` 之类的范围。客户端版本低于它时不会加载插件 |
+| `categories`    | 插件中心的分类，可多选，也可以不写，见下表                                                                |
+| `keywords`      | 插件中心的搜索词，最多 5 个，每个不超过 20 字。例如 S3 插件可以写 `MinIO`、`R2`                           |
+| `permissions`   | 插件可能申请的用户数据权限，见[用户数据 · 权限](user-data.md#权限)和 [AI](ai.md)                          |
+| `editor`        | 声明了编辑器扩展时写 `true`，见[编辑器扩展](editor.md)                                                    |
+| `whiteboard`    | 声明了白板扩展时写 `true`，见[白板扩展](whiteboard.md)                                                    |
+| `backend`       | 需要本机后台时填写，同时把 `formatVersion` 改为 `2`，见[本机后台](backend.md)                             |
+
+| 分类            | 适合的插件                    |
+| --------------- | ----------------------------- |
+| `page`          | 提供页面和侧边栏入口          |
+| `editor`        | 在文档中添加块                |
+| `whiteboard`    | 在白板中添加元素或工具        |
+| `ai`            | MCP 工具、AI 功能、图片生成   |
+| `skill`         | Skill 包，或附带 Skill 的插件 |
+| `sync`          | 同步存储                      |
+| `upload`        | 图片与附件上传                |
+| `voice`         | 语音合成                      |
+| `video`         | 在线视频来源                  |
+| `blog-publish`  | 博客发布目标                  |
+| `blog-template` | 博客模板                      |
+
+分类只影响插件中心的展示，不授予任何能力。只提供命令或普通设置的插件可以不写分类。
+
+### 保持模板值的字段
+
+`formatVersion`、`apiVersion`、`platform`、`format`、`main` 保持模板里的值。`styles`、`skills` 和 `integrity`（文件摘要）由 `pnpm build` 自动写入构建产物，不要手写，也不要直接修改 ZIP 里的文件。
+
+## 入口与插件定义
+
+入口模块默认导出 `definePlugin(...)` 的结果。最小的插件长这样：
+
+```tsx
+import { definePlugin } from "@tau/plugins";
+
+declare const __PLUGIN_META__: { id: string; name: string; version: string };
+
+export default definePlugin({
+  ...__PLUGIN_META__,
+  create: () => ({
+    activate(context) {
+      context.commands.register({
+        id: "hello",
+        title: "打个招呼",
+        run: () => {
+          context.notifications.send({ title: "你好" });
+          return null;
+        },
+      });
+    },
+  }),
+});
+```
+
+`__PLUGIN_META__` 由构建脚本从 manifest 注入，包含 `id`、`name`、`version`，这样插件定义和 manifest 始终一致。
+
+插件定义里的字段分两类：
+
+| 字段                   | 类型       | 说明                                                                  |
+| ---------------------- | ---------- | --------------------------------------------------------------------- |
+| `create`               | 运行时逻辑 | 每次启用时调用，返回本次运行的实例。只有静态声明的插件可以省略        |
+| `editorExtensions`     | 静态声明   | 编辑器块，见[编辑器扩展](editor.md)                                   |
+| `editorCodecs`         | 静态声明   | 编辑器块的 Markdown 转换，见[编辑器扩展](editor.md#markdown-导入导出) |
+| `whiteboardExtensions` | 静态声明   | 白板元素与工具，见[白板扩展](whiteboard.md)                           |
+| `ai`                   | 静态声明   | 插件自定义的 AI 功能，见 [AI](ai.md#自定义-ai-功能)                   |
+
+**静态声明**直接写在插件定义上，Tau 读取插件包时就能拿到，不依赖 `activate`。例如编辑器块不仅在桌面端显示，也会出现在用户发布的博客里，那里根本不会运行 `activate`。**运行时逻辑**则写在 `activate` 里，通过 `context` 注册。
+
+## 生命周期
+
+```tsx
+create: () => ({
+  async activate(context) {
+    // 注册功能，读取必要的配置
+  },
+  async deactivate() {
+    // 可选：额外清理
+  },
+}),
+```
+
+- **启用**：Tau 调用 `create()` 得到一个新实例，再调用 `activate(context)`。`activate` 完成后插件才算启用成功；它抛出异常则启用失败，已注册的内容全部撤销。
+- **停用**：用户停用插件、切换工作区，或者 Tau 退出时，本次运行结束。通过 `context` 注册的命令、页面、设置等全部自动撤销，`context.signal` 被中止，然后调用 `deactivate`（如果有）。
+- **再次启用**：重新调用 `create()` 和 `activate()`，拿到一个全新的 `context`。
+
+据此有几条规则：
+
+- 运行状态放在 `create` 返回的闭包或 React 组件里，不放在模块顶层。模块只会加载一次，顶层变量会跨越多次启用残留下来。
+- 需要跨启用、跨重启保留的数据，存进 [`context.storage`](storage-and-network.md)。
+- `activate` 应尽快返回。不要在里面等待用户操作或永不结束的任务；长时间的工作在后台启动，并响应 `context.signal`。
+- 不要依赖 `deactivate` 保存数据，它不保证在所有情况下都有机会执行完。数据应该在用户操作时就保存。
+- 不要把 `context` 保存下来留到下次启用使用。旧的 `context` 失效后，调用它的方法会报错。
+
+## context
+
+`activate` 收到的 `context` 是插件使用 Tau 能力的唯一入口。页面、设置组件也会通过 props 拿到同一个 `context`。
+
+| 属性                                                  | 用途                                         | 文档                                          |
+| ----------------------------------------------------- | -------------------------------------------- | --------------------------------------------- |
+| `pluginId`、`workspaceId`                             | 当前插件 ID 与工作区 ID（不要解析工作区 ID） |                                               |
+| `signal`                                              | 本次运行结束时中止                           | [取消与清理](#取消与清理)                     |
+| `register`                                            | 托管需要清理的资源                           | [取消与清理](#取消与清理)                     |
+| `commands`                                            | 注册命令                                     | [界面](ui.md#命令)                            |
+| `pages`、`sidebar`                                    | 注册页面与侧边栏入口                         | [界面](ui.md#页面)                            |
+| `settings`                                            | 注册设置区域                                 | [界面](ui.md#设置)                            |
+| `notifications`                                       | 发送通知                                     | [界面](ui.md#通知)                            |
+| `storage`                                             | 插件私有存储                                 | [存储与网络](storage-and-network.md)          |
+| `fetch`                                               | 网络请求                                     | [存储与网络](storage-and-network.md#网络请求) |
+| `permissions`                                         | 查询与申请权限                               | [用户数据](user-data.md#权限)                 |
+| `data`、`content`、`events`                           | 读写用户数据与正文、订阅变化                 | [用户数据](user-data.md)                      |
+| `app`                                                 | 选择与打开已有内容、导出与演示               | [用户数据](user-data.md#选择并打开已有内容)   |
+| `entities`                                            | 插件自己的内容                               | [用户数据](user-data.md#插件内容)             |
+| `excerpts`、`materials`                               | 摘录与材料动作                               | [摘录](excerpts.md)                           |
+| `ai`                                                  | 调用大模型                                   | [AI](ai.md)                                   |
+| `mcp`、`chat`                                         | 给 AI 提供工具、自定义工具结果的展示         | [MCP 工具](mcp.md)                            |
+| `flashcards`                                          | 闪卡                                         | [闪卡](flashcards.md)                         |
+| `services`                                            | 编译与转换服务                               | [编译与转换服务](services.md)                 |
+| `backend`                                             | 调用本机后台                                 | [本机后台](backend.md)                        |
+| `sync`、`upload`、`tts`、`images`、`video`、`publish` | 注册服务提供方                               | [服务提供方](providers/README.md)             |
+
+## ID 规则
+
+命令、页面、设置、侧边栏条目、MCP 等注册时填写的 `id` 都是**插件内的局部 ID**：Tau 会自动加上插件命名空间，你不需要也不应该自己拼接插件 ID。不同插件可以使用相同的局部 ID，互不影响。
+
+局部 ID 和存储的 key 都是 1 至 128 个字符，以字母或数字开头，后面可以是字母、数字、点、横线和下划线。同一类注册里重复的 ID 会报错。
+
+## 取消与清理
+
+**通过 `context` 注册的东西都会自动清理**，包括命令、页面、设置、侧边栏、MCP、通知、事件订阅等。注册方法返回的 `Disposable` 可以用来提前撤销：
+
+```ts
+const command = context.commands.register({ id: "temp", title: "临时命令", run: () => null });
+// 不再需要时
+await command.dispose();
+```
+
+**你自己创建的资源**，如计时器、DOM 事件监听、第三方库的连接，交给 `context.register` 托管，停用时按注册顺序的逆序清理：
+
+```ts
+const timer = setInterval(refresh, 60_000);
+context.register({ dispose: () => clearInterval(timer) });
+
+const onOnline = () => refresh();
+window.addEventListener("online", onOnline);
+context.register({ dispose: () => window.removeEventListener("online", onOnline) });
+```
+
+React 组件内的订阅照常在 `useEffect` 的清理函数里处理。
+
+**异步任务**要响应 `context.signal`。网络请求用 [`context.fetch`](storage-and-network.md#网络请求)，它会随插件停用自动取消。异步结果写回界面前检查 `context.signal.aborted`，避免切换工作区后旧请求的结果出现在新界面上：
+
+```ts
+const result = await loadSomething();
+if (context.signal.aborted) return;
+setState(result);
+```
+
+## 错误处理
+
+- 预期内的失败（网络错误、配置缺失、用户拒绝授权）要在界面上给出可读的提示，并提供重试或修复的入口。
+- 命令的 `run` 抛出异常表示执行失败。需要告诉用户失败原因时，自己发送[通知](ui.md#通知)或在页面上显示。
+- 读取存储、网络响应、用户配置等外部数据时，先校验类型再使用，不要假定数据一定符合预期。
+- 不要在遇到额度不足、拒绝授权这类错误后自动循环重试。
+
+## 运行环境
+
+插件代码与 Tau 运行在同一个浏览器环境中，可以使用标准的 Web API 和浏览器兼容的 npm 包，但不能导入 Node.js 内置模块（`fs`、`path`、`child_process` 等）。需要 Node.js 能力时，使用[本机后台](backend.md)。
+
+插件中心会审核提交的版本，但插件与 Tau 之间没有安全沙箱。只申请功能确实需要的权限，不要把密钥、令牌或你机器上的路径写进源码和插件包。

package/docs/providers/README.md

@@ -0,0 +1,108 @@
+# 服务提供方
+
+Tau 的一些功能允许用户选择背后的服务：同步到哪个存储、图片上传到哪个图床、用哪家的语音合成等等。插件可以注册为这些功能的**提供方**，把一个新的服务接入进来。
+
+| 提供方                 | 接入后用户可以                           | 配置界面出现在               |
+| ---------------------- | ---------------------------------------- | ---------------------------- |
+| [同步存储](sync.md)    | 把笔记库同步到你接入的存储服务           | 设置 · 同步                  |
+| [资源上传](upload.md)  | 把编辑器里的图片、附件上传到你接入的存储 | 设置 · 资源存储              |
+| [语音合成](tts.md)     | 用你接入的服务朗读、生成播客、复刻音色   | 设置 · 语音                  |
+| [图片生成](images.md)  | 用你接入的模型生成和编辑图片             | 设置 · 图片生成              |
+| [视频来源](video.md)   | 从你接入的视频网站或服务添加视频         | 设置 · 账号与连接 · 在线视频 |
+| [博客发布](publish.md) | 把博客发布到你接入的目标                 | 发布 · 站点设置 · 发布目标   |
+
+## 共同的模式
+
+所有提供方都遵循同一套写法，理解了一个，其他的就很容易上手。
+
+### 1. 注册提供方
+
+在 `activate` 中注册，`id` 固定为 `context.pluginId`。每个插件只能注册一个同类提供方。
+
+```ts
+context.upload.register({
+  id: context.pluginId,
+  name: "我的图床",
+  async upload(file, config, signal) {
+    // ...
+  },
+});
+```
+
+多数提供方用 `create(config)` 根据用户配置创建实例：
+
+```ts
+context.sync.register({
+  id: context.pluginId,
+  name: "我的存储",
+  create: config => createStorage(context, parseConfig(config)),
+});
+```
+
+`create` 是同步的，只根据配置创建对象，**不发起网络请求**。真正的连接在实例的方法被调用时才发生。Tau 在每次任务开始时调用 `create`，同一次任务中配置保持不变。
+
+### 2. 注册配置表单
+
+用户需要填写账号、地址等配置。用 `context.settings.register` 注册一个带 `target` 的设置区域，它会出现在对应功能的设置里，而不是插件详情页：
+
+```tsx
+import type { PluginSettingsProps } from "@tau/plugins";
+
+function UploadSettings({ uploadConfig }: PluginSettingsProps) {
+  if (!uploadConfig) return null;
+  const initial = parseConfig(uploadConfig.value);
+  // 表单...
+  async function save(next: MyConfig) {
+    await uploadConfig.save(next);
+  }
+}
+
+context.settings.register({
+  id: "upload",
+  title: "我的图床",
+  target: "upload",
+  component: UploadSettings,
+});
+```
+
+| `target`  | 组件收到的配置属性 | 保存方法               |
+| --------- | ------------------ | ---------------------- |
+| `sync`    | `syncConfig`       | `save(value)`          |
+| `upload`  | `uploadConfig`     | `save(value)`          |
+| `tts`     | `ttsConfig`        | `save(value, models)`  |
+| `images`  | `imageConfig`      | `save(value, modelId)` |
+| `video`   | `videoConfig`      | `save(value)`          |
+| `publish` | `publishConfig`    | `save(value)`          |
+
+- 配置属性是可选的，使用前先检查是否存在。
+- `value` 是之前保存的 JSON 值，用户还没保存过时可能为空。读取后自己校验结构，缺失的字段用默认值。
+- `save` 失败时保留用户的输入并显示错误；成功后再提示已保存。
+- 配置由 Tau 保存，**不要再存一份到 `context.storage`**：`storage` 会随笔记库同步，不适合放凭据。
+- `create(config)` 收到的就是这里保存的值。
+
+注册后，插件详情页会提供跳转到这个配置表单的入口，`register` 返回的句柄的 `open()` 也会跳转过去。
+
+### 3. 网络请求与取消
+
+- 请求统一用 [`context.fetch`](../storage-and-network.md#网络请求)。
+- 提供方的方法会收到 `signal`，把它传给 `context.fetch`。重试前的等待、轮询也要响应取消。
+- 自己设置超时时，用 `AbortSignal.any([signal, AbortSignal.timeout(ms)])` 组合，不要丢掉 Tau 传入的 `signal`。
+- 取消后不要把 `AbortError` 当成可重试的错误。
+
+### 4. 错误处理
+
+- 失败时抛出带可读信息的错误，不要吞掉异常后返回"成功"或空结果，否则 Tau 会误以为操作完成了。
+- 错误信息里不要包含 Token、密码等凭据。
+- 插件停用时，进行中的请求会被取消，迟到的结果会被丢弃。
+
+### 5. 运行环境
+
+提供方运行在浏览器环境中，可以使用浏览器兼容的 npm 包，但不能使用 Node.js 模块（`fs`、`http`、`Buffer` 等）。很多服务商的 SDK 允许替换 HTTP 实现，把它接到 `context.fetch` 上即可。
+
+### 6. 在 manifest 中选择分类
+
+在 `categories` 中写上对应的分类（`sync`、`upload`、`voice`、`ai`、`video`、`blog-publish`），用户在插件中心按分类筛选时就能找到你的插件。分类只影响展示，注册提供方的是代码。
+
+### 7. 写好 README
+
+提供方插件通常需要用户在服务商那里做一些准备，比如创建存储桶、开放公开读取、生成 Token。把这些步骤和常见错误写进插件的 `README.md`。

package/docs/providers/images.md

@@ -0,0 +1,65 @@
+# 图片生成
+
+图片提供方让用户用你接入的模型生成图片，或基于参考图编辑图片。
+
+先读[服务提供方](README.md)了解共同的写法。
+
+## 注册
+
+```ts
+context.images.register({
+  id: context.pluginId,
+  name: "我的图片服务",
+  create: (config, modelId) => ({
+    async generate({ prompt, options }, signal) {
+      // 调用服务商接口，返回图片
+      return [{ name: "image.png", mimeType: "image/png", content: bytes }];
+    },
+    async edit({ prompt, options, images }, signal) {
+      // 基于参考图编辑
+      return [{ name: "edited.png", mimeType: "image/png", content: bytes }];
+    },
+  }),
+});
+```
+
+`create(config, modelId)` 用一个账号的配置和模型创建实例，不发起网络请求。和语音一样，用户可以添加多个账号。
+
+实例至少实现一个方法，没实现的方法在 Tau 中不会显示对应入口：
+
+| 方法                                        | 说明                     |
+| ------------------------------------------- | ------------------------ |
+| `generate({ prompt, options }, signal)`     | 根据文字生成图片         |
+| `edit({ prompt, options, images }, signal)` | 基于一张或多张参考图编辑 |
+
+输入和输出的图片都是 `{ name, mimeType, content: Uint8Array }`，输出可以额外附带 `revisedPrompt`（服务商改写后的提示词）。
+
+## 参数
+
+`options` 包含 `size`、`quality`、`outputFormat`（`png`、`jpeg`、`webp`）、`background`、`count`，都是可选的。
+
+- 只把用户显式设置的参数传给服务商。
+- 服务商不支持某个参数时，抛出错误说明，不要悄悄忽略；也不要通过多次调用来凑够 `count`。
+
+## 限制
+
+- 支持 PNG、JPEG、WebP。
+- 单次最多 16 张；输入、输出的总大小各不超过 128 MiB。
+- 服务商返回的是临时下载地址时，由插件下载成字节再返回。下载其他域名的文件时，不要带上服务商的 API 凭据。
+
+## 配置表单
+
+```ts
+context.settings.register({
+  id: "images",
+  title: "我的图片服务",
+  target: "images",
+  component: ImageSettings,
+});
+```
+
+组件收到 `imageConfig`：`instanceId`（正在编辑的账号）、`value`、`modelId`，以及 `save(value, modelId)`。模型 ID 由你的表单让用户填写。只编辑当前这一个账号，不要把它当成全局的当前账号。
+
+## 职责划分
+
+协议、鉴权、超时、重试和轮询由插件负责；文件解析、上传到用户的资源存储、插入正文由 Tau 负责。插件停用或用户取消时，进行中的任务会被取消，迟到的结果被丢弃；但远端已经开始的任务和产生的费用无法撤回。

package/docs/providers/publish.md

@@ -0,0 +1,144 @@
+# 博客发布
+
+发布提供方让用户把 Tau 生成的博客站点发布到你接入的目标，比如对象存储、静态托管服务或 Git 仓库。Tau 负责生成站点文件、计算增量、重试和清理旧文件；插件只负责把文件送到远端。
+
+先读[服务提供方](README.md)了解共同的写法。开发博客模板或独立站点请看[站点数据](../site-data.md)。
+
+## 两种发布方式
+
+| 方式     | `mode`       | 适合                                   | 需要实现                   |
+| -------- | ------------ | -------------------------------------- | -------------------------- |
+| 逐个文件 | `"files"`    | 对象存储、支持单文件上传的托管服务     | `uploadFile`、`deleteFile` |
+| 整体快照 | `"snapshot"` | Git 仓库等需要一次性提交全部变化的目标 | `publish`                  |
+
+## 注册
+
+```ts
+import type { PublishInstance } from "@tau/plugins";
+
+context.publish.register({
+  id: context.pluginId,
+  name: "我的存储",
+  create: (config): PublishInstance => {
+    const settings = parseConfig(config);
+    return {
+      mode: "files",
+      concurrency: 8,
+      async describe(signal) {
+        return {
+          identity: `my-storage:${settings.bucket}`,
+          basePath: "/",
+          publicUrl: settings.publicUrl,
+        };
+      },
+      async checkConnection(signal) {
+        const response = await context.fetch(settings.endpoint, { method: "HEAD", signal });
+        return response.ok;
+      },
+      async uploadFile(path, content, signal) {
+        const response = await context.fetch(`${settings.endpoint}/${path}`, {
+          method: "PUT",
+          body: content,
+          signal,
+        });
+        if (!response.ok) throw new Error(`上传 ${path} 失败：${response.status}`);
+      },
+      async deleteFile(path, signal) {
+        const response = await context.fetch(`${settings.endpoint}/${path}`, {
+          method: "DELETE",
+          signal,
+        });
+        if (!response.ok && response.status !== 404)
+          throw new Error(`删除 ${path} 失败：${response.status}`);
+      },
+    };
+  },
+});
+```
+
+### 两种方式都要实现的方法
+
+| 方法                      | 说明                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `describe(signal)`        | 返回发布目标的信息，见下表                                                     |
+| `checkConnection(signal)` | 检查目标能否访问，返回 `true` 或 `false`；网络、认证错误可以直接抛出可读的错误 |
+| `dispose()`               | 可选。发布结束时释放连接                                                       |
+
+| `describe` 返回的字段 | 说明                                                                              |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `identity`            | 发布目标的稳定标识，如存储桶名加路径。不含凭据，也不随插件版本、模板或 Token 变化 |
+| `basePath`            | 站点的根路径，以 `/` 开头和结尾，根目录就是 `/`                                   |
+| `publicUrl`           | 可选。站点的公开访问地址                                                          |
+
+### 逐个文件
+
+| 成员                                | 说明                                             |
+| ----------------------------------- | ------------------------------------------------ |
+| `uploadFile(path, content, signal)` | 上传一个文件，`content` 是 `Uint8Array`          |
+| `deleteFile(path, signal)`          | 删除一个文件。文件已经不存在时视为成功，便于重试 |
+| `concurrency`                       | 可选。并发上限，1 至 32                          |
+
+`path` 是站点内的相对路径。拼接远端地址时保留路径结构并正确编码，不要拼成 Shell 命令。
+
+### 整体快照
+
+| 成员                        | 说明                                           |
+| --------------------------- | ---------------------------------------------- |
+| `publish(snapshot, signal)` | 提交本轮全部变化，远端确认整体提交成功后才返回 |
+
+`snapshot` 包含本轮的临时 `id`、待上传的文件（`path` 与 `hash`）和待删除的路径。失败时抛出异常，不要返回部分成功。
+
+## Git 仓库
+
+发布到 Git 仓库时，不需要自己实现 Git 协议，使用 Tau 提供的服务：
+
+```ts
+async publish(snapshot, signal) {
+  await context.services.git.publishSnapshot(
+    {
+      publicationId: snapshot.id,
+      remote: "https://github.com/yourname/blog.git",
+      branch: "main",
+      author: { name: "Your Name", email: "you@example.com" },
+      authentication: { username: "x-access-token", password: settings.token },
+      cacheId: settings.cacheId,
+    },
+    { signal }
+  );
+}
+```
+
+- `remote` 只接受不含凭据的 HTTPS 地址，凭据通过 `authentication` 传入。
+- `publicationId` 只在本轮发布中有效。
+- 需要本地缓存目录加快发布时，调用 `context.services.git.selectCacheDirectory({})`，由用户选择目录，返回 `{ id, label }`；用户取消时返回 `null`。只保存 `id` 和用于显示的 `label`，作为 `cacheId` 传入。
+
+## 配置表单
+
+```ts
+context.settings.register({
+  id: "publish",
+  title: "我的存储",
+  target: "publish",
+  component: PublishSettings,
+});
+```
+
+组件收到 `publishConfig`：`value` 和 `save(value)`。表单显示在「站点设置 · 发布目标」的卡片里，位于 Tau 的连接状态和「服务」行之后。为了和周围的界面一致：
+
+- **按行排列**：每行左侧是 64px 宽的标签，右侧是控件；行高至少 46px，内边距 `8px 12px`，行与行之间用 `--tau-line-2` 的顶部边线分隔。标签字号用 `--tau-text-meta`，颜色用 `--tau-ink-2`。
+- **不要再包一层卡片或标题**。
+- **自动保存**：不提供「保存」和「测试连接」按钮，测试连接与完成由 Tau 提供。用户停止输入约 600ms 或输入框失焦时调用 `save`，组件卸载前保存未提交的修改。Tau 回写的配置与你最近一次保存的值相同时，不要覆盖用户正在输入的内容。
+- 辅助操作（如「读取仓库列表」）放在对应输入框的尾部；不常用的选项收进「高级选项」折叠区。
+- `save` 失败时，在表单末行显示错误，保留用户输入。
+
+## 注意事项
+
+- 用户离开发布页后，发布会在后台继续；插件停用、切换工作区或发起发布的窗口关闭时，本轮发布会中止。
+- 每个请求都传入 `signal`，检查 `response.ok`。不要吞掉异常后返回成功，否则 Tau 会误以为文件已经发布。
+- Token 不要出现在 `identity`、公开地址、错误信息、README 和日志里。
+- `create` 同步返回实例，连接和上传放在各个异步方法里。
+- 新安装的发布插件默认停用。插件缺失或未启用时，Tau 会保留用户的配置和选择，不会自动切换到其他目标。
+
+## 测试清单
+
+用真实的远端验证成功之后，再声称支持该目标。至少覆盖：配置保存失败、连接失败、重复发布、远端文件已存在或已删除、用户取消、插件停用、切换工作区，以及快照提交中途失败后的重试。

package/docs/providers/sync.md

@@ -0,0 +1,75 @@
+# 同步存储
+
+同步存储提供方让用户把笔记库同步到你接入的存储服务（对象存储、网盘等）。你只需要实现"读写远端文件"的几个基本操作；同步什么、怎么命名、版本与冲突、断点恢复都由 Tau 负责。
+
+先读[服务提供方](README.md)了解共同的写法。
+
+## 注册
+
+```ts
+import type { SyncProvider } from "@tau/plugins/sync";
+
+context.sync.register({
+  id: context.pluginId,
+  name: "我的存储",
+  create: config => createStorage(context, parseConfig(config)),
+});
+
+function createStorage(context: PluginContext, config: MyConfig): SyncProvider {
+  return {
+    async uploadFile(name, bytes) {
+      /* ... */ return true;
+    },
+    async downloadFile(name) {
+      /* ... */ return new Uint8Array();
+    },
+    async fileExists(name) {
+      /* ... */ return false;
+    },
+    async listFiles(prefix) {
+      /* ... */ return [];
+    },
+    async createFileIfAbsent(name, bytes) {
+      /* ... */ return true;
+    },
+  };
+}
+```
+
+类型 `SyncProvider`、`SyncProviderDefinition`、`RemoteFileInfo` 从 `@tau/plugins/sync` 导入。
+
+## 需要实现的方法
+
+| 方法                              | 返回                        | 说明                                                         |
+| --------------------------------- | --------------------------- | ------------------------------------------------------------ |
+| `uploadFile(name, bytes)`         | `Promise<boolean>`          | 上传对象，已存在时覆盖                                       |
+| `downloadFile(name)`              | `Promise<Uint8Array>`       | 下载对象                                                     |
+| `fileExists(name)`                | `Promise<boolean>`          | 对象是否存在                                                 |
+| `listFiles(prefix?)`              | `Promise<RemoteFileInfo[]>` | 列出前缀下的全部对象，**分页由你在内部处理完**，返回完整列表 |
+| `createFileIfAbsent(name, bytes)` | `Promise<boolean>`          | 只在对象不存在时创建，已存在时返回 `false`                   |
+
+`RemoteFileInfo` 包含 `name`、`path`（相对路径）、`size`，以及可选的 `lastModified`、`hash`。
+
+### createFileIfAbsent 必须是原子的
+
+Tau 用它来保证多台设备同时同步时不会互相覆盖。它必须使用存储服务本身的条件写入能力（如 S3 的 `If-None-Match: *`），**不能用"先查是否存在、再上传"来模拟**，那样在并发时会出错。
+
+请求失败、无法确定结果时直接抛出错误，Tau 会按自己的规则核实。
+
+## 配置表单
+
+```ts
+context.settings.register({
+  id: "sync",
+  title: "我的存储",
+  target: "sync",
+  component: SyncSettings,
+});
+```
+
+组件从 `syncConfig.value` 读取配置，用 `await syncConfig.save(config)` 保存。字段和校验由你决定。
+
+- 每次同步任务开始时，Tau 用当时的配置调用 `create`，任务过程中配置不变。
+- 关闭设置页不影响进行中的同步。
+- 同步进行中，插件不能被停用或卸载。
+- 停用插件后，配置会保留。

package/docs/providers/tts.md

@@ -0,0 +1,62 @@
+# 语音合成
+
+语音提供方让用户用你接入的服务朗读文字、生成播客，以及复刻音色。
+
+先读[服务提供方](README.md)了解共同的写法。
+
+## 注册
+
+```ts
+context.tts.register({
+  id: context.pluginId,
+  name: "我的语音服务",
+  create: (config, modelId) => createVoiceService(context, parseConfig(config), modelId),
+});
+```
+
+`create(config, modelId)` 用用户的一个账号配置和所选模型创建实例，不发起网络请求。
+
+**用户可以为同一个插件添加多个账号**，每个账号是一份独立的配置。所以不要把"当前的 API Key"存在模块级变量里，一切都从 `create` 收到的 `config` 读取。
+
+## 实例
+
+| 成员                                                | 说明                                                                                                      |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `getVoices(signal)`                                 | 返回音色列表：`{ id, name, type, description? }`，`type` 为 `system`（预置）、`cloned`（复刻）或 `custom` |
+| `synthesize({ text, voiceId, options }, signal)`    | 合成语音，返回 `{ audio: Uint8Array, mime }`。`options` 包含可选的 `speed`、`volume`、`pitch`             |
+| `cloneVoice({ file, requestedId?, name? }, signal)` | 可选。用一个参考音频文件复刻音色，返回新建的音色                                                          |
+| `textInstructions`                                  | 可选。当前模型支持的文本标记规则（如停顿、语气标签），Tau 生成播客脚本时会参考                            |
+
+- 网络请求使用 `context.fetch`，并传入方法收到的 `signal`。
+- `cloneVoice` 的 `file` 是 `{ name, mimeType, content }`，每次一个文件。返回实际创建的音色，不要返回上传文件的 ID。
+
+## 配置表单
+
+```ts
+context.settings.register({
+  id: "tts",
+  title: "我的语音服务",
+  target: "tts",
+  component: TTSSettings,
+});
+```
+
+组件收到 `ttsConfig`：
+
+| 字段                  | 说明                                   |
+| --------------------- | -------------------------------------- |
+| `instanceId`          | 正在编辑的账号 ID                      |
+| `value`               | 这个账号的配置                         |
+| `models`              | 这个账号的模型列表，`{ id, label? }[]` |
+| `save(value, models)` | 保存这个账号的配置和模型列表           |
+
+- 表单只编辑当前这一个账号，不要影响同插件的其他账号，也不要把它设为默认。
+- 模型列表由你的表单提供，可以允许用户填写自定义模型。
+
+## 上传参考音频
+
+服务需要参考音频的公开地址时，用 `context.upload.uploadRemote(file, { signal })` 上传，它使用用户选择的上传配置，见[资源上传](upload.md#在其他功能中使用上传)。不要自己选择用户的上传插件或读取上传凭据。服务商自带文件上传接口的，直接用服务商的接口即可。
+
+## 职责划分
+
+音频的播放、拼接和保存由 Tau 负责，插件只负责调用服务商接口，不直接写笔记或文件。