@xiongtao.xt/tau-plugins 0.31.0 → 0.32.0

package/docs/flashcards.md

@@ -0,0 +1,127 @@
+# 闪卡
+
+插件可以帮用户创建闪卡。有三种方式，从轻到重：
+
+| 方式                            | 适合                                      | 需要的权限                                              |
+| ------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
+| [打开制卡窗口](#打开制卡窗口)   | 让用户在 Tau 的制卡界面里确认、编辑后保存 | 不需要（AI 模式需要 `ai:flashcardGeneration`）          |
+| [直接创建](#直接创建卡组与闪卡) | 插件已经整理好了题目，直接写入            | `flashcards:read`、`flashcards:write`                   |
+| [AI 生成](#ai-生成)             | 从一段资料生成草稿，或生成后直接保存      | `ai:flashcardGeneration`，保存还需要 `flashcards:write` |
+
+在 manifest 中声明用到的权限：
+
+```json
+{ "permissions": ["flashcards:read", "flashcards:write", "ai:flashcardGeneration"] }
+```
+
+AI 制卡沿用用户在 Tau 中为「闪卡制作」分配的模型，不需要插件另外配置。用量、额度与授权方式和 [AI](ai.md#使用-tau-已有的模型分配) 中的 `requestCapability` 相同，用户撤销授权会取消进行中的生成。
+
+## 打开制卡窗口
+
+```ts
+const result = await context.flashcards.openCreate({
+  mode: "ai", // 默认 "manual"：手动制卡
+  content: "牛顿第二定律：F = ma。",
+  title: "力学笔记",
+});
+
+// result.status：completed 或 cancelled
+// result.cards：用户在窗口中已经保存的闪卡
+```
+
+| 参数         | 说明                                                                              |
+| ------------ | --------------------------------------------------------------------------------- |
+| `mode`       | `manual`（默认）预填题干和参考资料；`ai` 打开后自动开始生成，用户挑选、编辑后保存 |
+| `content`    | 资料内容，Markdown 字符串或编辑器节点                                             |
+| `title`      | 资料标题                                                                          |
+| `deckId`     | 可选。目标卡组；省略时由用户选择，也可以现场新建                                  |
+| `references` | 可选。闪卡的来源，见下文                                                          |
+
+- 必须在用户操作（点击、按键）中调用。在定时器、后台任务里调用会被拒绝；也不要在 `activate` 中等待它。
+- 返回的 Promise 在用户关闭窗口后才完成。用户取消时，`cards` 里仍包含取消前已经保存的闪卡，取消不会撤销它们。
+- 同一个窗口同一时间只能打开一个制卡会话。
+- 窗口里的保存由用户确认，所以不需要闪卡读写权限。
+
+### 来源
+
+不传 `references` 时，`content` 作为自定义参考资料随闪卡保存，`title` 是来源标题。传 `references: []` 表示不记录来源。
+
+资料来自 Tau 中已有的正文时，传入正文引用，而不是把正文复制一份：
+
+```ts
+await context.flashcards.openCreate({
+  mode: "ai",
+  content: snapshot.markdown,
+  references: [{ refType: "content", contentRef: card.contentRef, title: card.title }],
+});
+```
+
+`contentRef` 来自 [`context.data`](user-data.md) 或 [`context.entities`](user-data.md#插件内容)。引用其他内容的正文时需要对应的读取权限，插件自己的内容不需要。引用已失效或没有权限时，保存会被拒绝。
+
+## 直接创建卡组与闪卡
+
+```ts
+const decks = await context.flashcards.listDecks();
+const deck = await context.flashcards.createDeck({ name: "力学", description: "基础概念" });
+
+const card = await context.flashcards.createCard({
+  deckId: deck.id,
+  type: "qa",
+  prompt: [
+    { type: "paragraph", children: [{ type: "formatted", text: "牛顿第二定律的表达式是什么？" }] },
+  ],
+  data: { answer: "F = ma" },
+  tags: ["力学"],
+  difficulty: "foundation",
+});
+```
+
+| 闪卡字段     | 说明                                                                                                       |
+| ------------ | ---------------------------------------------------------------------------------------------------------- |
+| `deckId`     | 所属卡组                                                                                                   |
+| `type`       | 题型：`qa`（问答）、`boolean`（判断）、`cloze`（填空）、`single-choice`（单选）、`multiple-choice`（多选） |
+| `prompt`     | 题干，编辑器节点                                                                                           |
+| `detail`     | 可选。补充说明，编辑器节点                                                                                 |
+| `data`       | 答案，结构随题型不同，见下表                                                                               |
+| `tags`       | 可选。标签                                                                                                 |
+| `difficulty` | 可选。`foundation`、`standard`、`advanced`                                                                 |
+| `references` | 可选。来源，同上文                                                                                         |
+
+| 题型                               | `data` 中的答案                                                |
+| ---------------------------------- | -------------------------------------------------------------- |
+| `qa`                               | `answer`                                                       |
+| `boolean`                          | `booleanAnswer`                                                |
+| `cloze`                            | `blanks`：`[{ id, placeholder, answer, alternativeAnswers? }]` |
+| `single-choice`、`multiple-choice` | `options`：`[{ id, label, isCorrect, explanation? }]`          |
+
+所有题型都可以附带 `explanation`（解析）、`hint`（提示）和 `referenceNotes`（参考笔记）。
+
+- 这些方法直接写入用户的数据，调用前确认这是用户想要的。
+- 闪卡属于用户，卸载插件不会删除。接口不提供修改和删除已有闪卡的能力。
+- 创建后，打开中的卡组、闪卡列表和计数会自动刷新。
+
+## AI 生成
+
+```ts
+// 只生成草稿，插件可以先筛选，再逐张 createCard
+const drafts = await context.flashcards.generate({ content: "需要学习的内容", title: "资料" });
+
+// 生成后直接保存，跳过用户预览
+const result = await context.flashcards.generateAndSave({
+  content: "需要学习的内容",
+  title: "资料",
+  deckId: deck.id,
+});
+// result.cards：保存成功的闪卡
+// result.failed：保存失败的项，{ index, message }
+```
+
+- `generate` 返回的草稿和 `createCard` 的参数结构相同，可以直接传给 `createCard`。
+- `generateAndSave` 会绕过用户预览直接写入，只在用户明确要求时使用。
+- `generateAndSave` 逐张保存，不是一个整体事务：部分成功、部分失败都有可能。**不要对整个调用重试**，否则已成功的闪卡会重复创建。需要精确重试时，用 `generate` 拿到草稿，再逐张 `createCard`。
+- 取消或切换工作区会阻止后续写入，但已经写入的闪卡不会回滚。
+- 用户没有为「闪卡制作」分配模型、未授权、额度不足或内容为空时，调用会明确失败。
+
+## 适用范围
+
+闪卡接口只在插件运行时中可用，编辑器块的渲染组件、博客中都不能使用。

package/docs/getting-started.md

@@ -0,0 +1,134 @@
+# 快速开始
+
+这一篇带你跑通模板自带的计数器插件，再把它改成你自己的插件。全程大约十分钟。
+
+## 准备环境
+
+- Node.js 22 或更高版本
+- pnpm 11.9.0（模板通过 `packageManager` 字段锁定，用 `corepack enable` 可以自动获得对应版本）
+- Tau 桌面客户端 0.59.0 或更高版本
+
+## 跑通示例
+
+在 GitHub 上打开 [tau-plugin-template](https://github.com/LastKnightCoder/tau-plugin-template)，点击 **Use this template** 创建你自己的仓库，克隆到本地后执行：
+
+```sh
+pnpm install
+pnpm build
+pnpm install:local
+```
+
+- `pnpm build` 检查类型并打包，生成 `dist/<插件ID>-<版本>.zip`。
+- `pnpm install:local` 把这个 ZIP 解压到 Tau 的插件目录 `~/.editor/plugins/<插件ID>/`。
+
+然后在 Tau 中：
+
+1. 打开侧边栏的「插件」页，点右上角的「⋯ → 重新扫描」，列表里会出现「计数器示例」。
+2. 启用它。
+3. 点击侧边栏「日常」分组下的「计数器」，或按 Ctrl+K 搜索「打开计数器」。
+4. 点「增加并保存」。重启 Tau 后再打开，计数还在。
+
+到这里，你已经完成了一次完整的开发、安装和运行。
+
+## 模板里有什么
+
+| 文件                              | 作用                                                      |
+| --------------------------------- | --------------------------------------------------------- |
+| `manifest.json`                   | 插件的身份证：ID、名称、版本、需要的权限等                |
+| `src/index.tsx`                   | 插件入口，计数器的页面、设置和命令都在这里                |
+| `src/styles.css`                  | 插件样式，构建时打包成 `main.css`                         |
+| `src/CounterIcon.tsx`             | 侧边栏图标示例                                            |
+| `README.md`                       | 给使用者看的插件说明，显示在插件详情的「说明」里          |
+| `CHANGELOG.md`（需要时自己创建）  | 给使用者看的更新日志，显示在插件详情的「更新日志」里      |
+| `build.mjs` / `install-local.mjs` | 打包和本地安装脚本，一般不用改                            |
+| `.github/workflows/release.yml`   | 推送版本 tag 后自动构建、发布到 GitHub Release 和插件中心 |
+| `AGENTS.md`                       | 给 AI 编程助手的项目指引                                  |
+| `docs/`                           | 本开发文档，不会打进插件包                                |
+
+打开 `src/index.tsx` 看一下，核心只有这么多：
+
+```tsx
+export default definePlugin({
+  ...__PLUGIN_META__,
+  create: () => ({
+    activate(context) {
+      const page = context.pages.register({ id: "counter", title: "计数器", component: Page });
+      context.sidebar.registerItem({
+        id: "counter",
+        title: "计数器",
+        icon: CounterIcon,
+        group: SIDEBAR_GROUPS.daily,
+        page,
+      });
+      context.settings.register({ id: "preferences", title: "计数设置", component: Settings });
+      context.commands.register({
+        id: "open",
+        title: "打开计数器",
+        run: async () => {
+          await page.open();
+          return null;
+        },
+      });
+    },
+  }),
+});
+```
+
+插件启用时，Tau 调用 `activate`，你在里面注册页面、入口、设置和命令；插件停用时，这些注册会被自动撤销。具体机制见[插件的组成](plugin-basics.md)。
+
+## 改成你自己的插件
+
+1. **改身份**。编辑 `manifest.json`：
+   - `id` 换成你自己的唯一名称，例如 `yourname.water-tracker`。ID 发布后不要再改，改了会被当成另一个插件，用户已保存的数据也找不回来。
+   - `name`、`description` 改成插件的名称和一句话简介（160 字以内）。
+   - `version` 从 `1.0.0` 开始即可。
+   - `categories`、`keywords` 决定插件在插件中心的分类和搜索词，含义见[插件的组成 · manifest](plugin-basics.md#manifest)。
+2. **改项目名**。把 `package.json` 的 `name` 改成你的项目名，`version` 与 manifest 保持一致。
+3. **写功能**。在 `src/index.tsx` 里实现你的功能，样式写在 `src/styles.css`。
+4. **写说明**。把 `README.md` 改成给使用者看的介绍：插件能做什么、怎么开始用、常见问题。不要写开发过程或内部实现，它会原样显示给用户。
+5. **构建并安装**，按下一节的方法在 Tau 中测试。
+
+## 日常开发循环
+
+改完代码后：
+
+```sh
+pnpm build
+```
+
+`pnpm install:local` 只负责首次安装，目标目录已存在时会拒绝覆盖，以免误删。更新已安装的开发版本时：
+
+1. 在 Tau 的插件页停用你的插件。
+2. 删除旧目录 `~/.editor/plugins/<插件ID>/`，再执行 `pnpm install:local`。
+3. 在插件页点「⋯ → 重新扫描」，然后重新启用。
+
+插件保存的数据在笔记库里，不在这个目录中，删除目录不会丢数据。
+
+带有[编辑器扩展](editor.md)或[白板扩展](whiteboard.md)的插件在 Tau 启动时装配，更新代码后需要完全退出并重新打开 Tau 才会生效。
+
+## 常用命令
+
+| 命令                 | 作用                            |
+| -------------------- | ------------------------------- |
+| `pnpm check`         | 只检查 TypeScript 类型          |
+| `pnpm build`         | 检查类型并生成插件 ZIP          |
+| `pnpm install:local` | 把最近构建的 ZIP 首次安装到 Tau |
+
+依赖用 pnpm 管理，添加依赖执行 `pnpm add <包名>`，并提交 `pnpm-lock.yaml`。普通 npm 包会被打进插件，React、`@tau/plugins`、`@tau/ui` 由 Tau 提供，不要改动 `build.mjs` 里的 external 列表，也不要升级模板锁定的 React 版本。
+
+## 排错
+
+| 现象                   | 处理                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| 插件列表里没有我的插件 | 点「重新扫描」；确认解压后的目录是 `~/.editor/plugins/<插件ID>/manifest.json`，没有多套一层 |
+| 提示目标目录已存在     | 按上面「日常开发循环」先删除旧目录                                                          |
+| 改了代码没有变化       | 确认重新构建并安装了；编辑器、白板插件需要重启 Tau                                          |
+| 启用失败               | 看插件卡片上的错误信息，通常是 `activate` 里抛了异常                                        |
+| 提示需要重启           | 完全退出 Tau 再打开                                                                         |
+
+类型检查通过只说明代码能编译。每次改完，至少在 Tau 中试一遍：启用、使用功能、保存数据、停用、重启后再用。
+
+## 下一步
+
+- 读[插件的组成](plugin-basics.md)，理解生命周期和 `context`。
+- 回到[文档首页](README.md)，按你要做的功能找到对应文档。

package/docs/mcp.md

@@ -0,0 +1,173 @@
+# MCP 工具
+
+通过 `context.mcp.register`，你可以给 Tau 的 AI 助手提供工具。用户和 AI 对话时，AI 会按需调用这些工具，比如查询插件里的数据、在插件里执行操作。
+
+注册的工具会出现在 Tau 的 MCP 页面和聊天的快捷面板里，用户可以整组或逐个开关工具。插件不需要自己做管理界面。
+
+一个 MCP 有两种提供方式：
+
+- **本地工具**：在插件里直接写工具函数，最简单。
+- **外部服务器**：连接一个已有的 MCP 服务器，通过 HTTP 或本机进程。
+
+## 本地工具
+
+```ts
+context.mcp.register({
+  id: "notes",
+  name: "我的笔记",
+  description: "读取本插件保存的笔记",
+  tools: [
+    {
+      name: "read_note",
+      description: "按键读取本插件中的一条笔记",
+      inputSchema: {
+        type: "object",
+        properties: { key: { type: "string", description: "笔记的键" } },
+        required: ["key"],
+        additionalProperties: false,
+      },
+      async execute(args, { signal }) {
+        if (typeof args.key !== "string") throw new Error("请提供笔记的键");
+        const note = await context.storage.get(args.key);
+        signal.throwIfAborted();
+        return { content: note === undefined ? "未找到笔记" : JSON.stringify(note) };
+      },
+    },
+  ],
+});
+```
+
+| MCP 字段      | 说明                                      |
+| ------------- | ----------------------------------------- |
+| `id`          | 局部 ID，一个插件可以注册多个 MCP         |
+| `name`        | 显示名称                                  |
+| `description` | 可选。说明                                |
+| `tools`       | 本地工具列表（与 `transport` 二选一）     |
+| `transport`   | 外部服务器的连接方式（与 `tools` 二选一） |
+
+| 工具字段      | 说明                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------- |
+| `name`        | 工具名，同一个 MCP 内唯一，规则同[局部 ID](plugin-basics.md#id-规则)。不要自己加插件前缀 |
+| `description` | 工具说明。AI 根据它判断什么时候调用，要写清楚用途和适用场景                              |
+| `inputSchema` | 参数的 JSON Schema，顶层必须是 `type: "object"`                                          |
+| `execute`     | 执行函数，收到参数和 `{ signal }`，返回 `{ content: string }`                            |
+
+- `content` 是给 AI 读的文本。结构化数据用 `JSON.stringify` 转成字符串。
+- 参数来自 AI，不一定符合 Schema，使用前要校验。
+- 单次调用最长 60 秒。用户取消、关闭工具、插件停用时 `signal` 会中止，异步代码要响应它。取消无法撤销已经完成的写入或外部请求。
+- 工具执行前，Tau 会按用户的设置请求确认。
+
+### 和页面上下文配合
+
+如果你的插件有页面，可以用[页面上下文](ui.md#向-ai-提供页面上下文)告诉 AI 用户正在看什么，再用 MCP 工具让 AI 对它执行操作。例如页面上下文提供当前书籍的 ID，工具 `add_note` 接收书籍 ID 和内容。
+
+## 外部服务器
+
+### HTTP
+
+```ts
+context.mcp.register({
+  id: "remote",
+  name: "知识服务",
+  transport: { type: "streamable-http", url: "https://your-service.example/mcp" },
+});
+```
+
+`streamable-http` 支持可选的 `headers`。
+
+### 本机进程
+
+用 stdio 启动本机的 MCP 服务器进程，需要插件带有[本机后台](backend.md)，并在 manifest 的 `backend` 中声明要启动的程序：
+
+```json
+{
+  "backend": {
+    "systemAccess": ["process"],
+    "tools": [{ "id": "mcp", "command": "node", "args": ["/path/to/your-server.mjs"] }]
+  }
+}
+```
+
+这里只列出相关字段，`backend` 的完整写法见[本机后台](backend.md)。然后注册：
+
+```ts
+context.mcp.register({
+  id: "local-server",
+  name: "本地 MCP 服务",
+  transport: { type: "stdio", command: "node", args: ["/path/to/your-server.mjs"] },
+});
+```
+
+- `stdio` 支持可选的 `args`、`env`、`cwd`。`cwd` 必须是绝对路径。
+- 命令不经过 Shell 执行，参数按数组原样传递。
+- 进程的环境变量只包含最小的系统集合和你显式传入的 `env`。
+- 在 Windows 上，命令必须能解析到一个 `.exe` 文件。
+- Tau 不会替用户安装 Node.js、Python 或其他依赖，启动前需要用户本机已经具备运行环境。在 README 中写清楚要求。
+
+外部服务器的连接配置、日志和重连，用户都可以在 MCP 页面管理。不要把密钥、令牌或你机器上的路径打进插件包，让用户在 MCP 页面里填写。
+
+## 生命周期
+
+- 插件启用成功后，注册的 MCP 才会出现。插件停用、切换工作区或卸载时自动移除。
+- 用户在 MCP 页面关闭某个 MCP，只关闭这一组 AI 工具，不影响插件的其他功能。用户的开关选择会一直保留，插件重新注册不会强行打开。
+- `register` 返回的 `Disposable` 可以提前移除这个 MCP。
+
+## 自定义工具结果的展示
+
+默认情况下，聊天里的工具调用显示为通用的输入、输出。你可以为自己的工具注册一个 React 组件，把结果显示成卡片、图表等更易读的样子。
+
+### 1. 工具返回展示数据
+
+本地工具除了 `content`，还可以返回 `render`：
+
+```ts
+async execute(args) {
+  const books = await searchBooks(String(args.query));
+  return {
+    content: JSON.stringify(books),
+    render: { version: 1, data: { books } },
+  };
+}
+```
+
+- `content` 仍然是给 AI 读的文本，也是默认展示的内容。
+- `render.data` 是给你的组件用的展示数据，必须是 JSON，会随聊天记录保存。
+- `render.version` 是正整数。以后数据结构变化时提高版本，组件按版本处理旧数据。
+
+### 2. 注册组件
+
+在 `async activate` 中，先注册 MCP，再注册组件：
+
+```tsx
+await context.chat.registerToolRenderer({
+  mcpId: "books",
+  toolName: "search_books",
+  component: ({ execution, data, dataVersion, renderDefault }) => {
+    if (execution.status !== "success" || dataVersion !== 1) return renderDefault();
+    return <BookList books={(data as { books: Book[] }).books} />;
+  },
+});
+```
+
+| 字段        | 说明                         |
+| ----------- | ---------------------------- |
+| `mcpId`     | 本插件注册 MCP 时的 `id`     |
+| `toolName`  | 工具的原始名称，不加任何前缀 |
+| `component` | 渲染组件                     |
+
+组件收到的属性：
+
+| 属性                             | 说明                                                               |
+| -------------------------------- | ------------------------------------------------------------------ |
+| `execution`                      | 这次调用的状态和结果，`status` 为 `success` 时 `output` 是结果文本 |
+| `data`、`dataVersion`            | 工具返回的 `render.data` 和 `render.version`，没有时为 `null`      |
+| `parsedInput`、`inputParseError` | 解析后的调用参数，解析失败时的错误                                 |
+| `isDark`                         | 当前是否为暗色主题                                                 |
+| `renderDefault()`                | 渲染默认的通用展示                                                 |
+
+- 只能为本插件的工具注册，包括本地工具和本插件外部服务器提供的工具。外部服务器的工具没有 `render`，组件从 `execution.output` 读取结果。
+- 遇到不认识的 `dataVersion`、失败或进行中的状态，调用 `renderDefault()`。
+- 组件只负责展示，不要在渲染或挂载时自动执行工具。
+- 用 `@tau/ui` 组件和主题变量编写样式，与聊天界面保持一致。
+- 插件停用后，历史消息回到通用展示；重新启用后恢复。
+- `registerToolRenderer` 返回 `Promise<Disposable>`，注册失败时抛出异常。插件停用时自动注销。

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 之间没有安全沙箱。只申请功能确实需要的权限，不要把密钥、令牌或你机器上的路径写进源码和插件包。