@xiongtao.xt/tau-plugins 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新记录
 
+## 0.32.0
+
+- 插件 Skill 改为包内目录：在插件项目根目录放 `skills/<id>/SKILL.md`，可附带参考资料和脚本，构建时打进插件包并写入 manifest 的 `skills` 与文件摘要。名称、描述与调用方式取自 SKILL.md 的 front matter。
+- `definePlugin` 的 `skills` 字段与 `PluginSkill` 类型已移除，已有插件请把正文移到 `skills/<id>/SKILL.md` 后重新构建。
+- 新增独立 Skill 包：manifest 不写 `main`、只声明 `skills`，经插件中心分发，安装后在 Skill 页直接可用。
+- 带脚本的 Skill 与本机后台一样需要插件中心人工审核后才能上架。
+- 插件分类新增 `skill`。
+
 ## 0.31.1
 
 - 修复：数据客户端读取 0.31.0 生成的站点清单时报「站点数据缺失」。客户端改为校验 `site.fields`，不再要求已移除的 `site.description`。

package/README.md

@@ -1,7 +1,7 @@
 # Tau 插件开发包 @tau/plugins
 
-开发 Tau 插件所需的类型与接口，通过 npm 别名安装为 `@tau/plugins`。根入口的实际实现由 Tau 客户端提供，构建时需设为 external。plugins 包另提供独立站点可用的 publish-data 类型和 publish-client 纯数据客户端，见该包 PUBLISH-DATA.md；不包含站点渲染、路由或预览实现。
+开发 Tau 插件所需的类型与接口，通过 npm 别名安装为 `@tau/plugins`。根入口的实现由 Tau 在运行时提供，插件构建时需设为 external。
 
 从模板开始开发：https://github.com/LastKnightCoder/tau-plugin-template
 
-编译与转换服务见 [SERVICES.md](SERVICES.md)，编辑器扩展、源码预览与插件 Skill 见 [EDITOR.md](EDITOR.md)，需要 Tau 0.59.0 及以上。AI 功能声明、模型分配与用量审计见 [AI.md](AI.md)。
+开发文档见 [docs/README.md](docs/README.md)。

package/client/{chunk-ECEBBIHP.js → chunk-SVY5LBAT.js}

@@ -45,6 +45,7 @@ var PLUGIN_CATEGORIES = [
   { id: "blog-template", label: "\u535A\u5BA2\u6A21\u677F" },
   { id: "blog-publish", label: "\u535A\u5BA2\u53D1\u5E03" },
   { id: "ai", label: "AI" },
+  { id: "skill", label: "Skill" },
   { id: "voice", label: "\u8BED\u97F3" },
   { id: "video", label: "\u89C6\u9891" },
   { id: "page", label: "\u9875\u9762" }
@@ -215,6 +216,42 @@ function validateBackendManifest(value) {
   });
 }
 
+// packages/plugins/src/skills.ts
+var SKILL_ROOT = "skills";
+var SKILL_README = "SKILL.md";
+var SKILL_LIMITS = { skills: 32 };
+var skillDirectory = (id) => `${SKILL_ROOT}/${id}`;
+function readSkillsField(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.length > SKILL_LIMITS.skills)
+    throw new Error(`skills \u5FC5\u987B\u662F\u6700\u591A ${SKILL_LIMITS.skills} \u9879\u7684\u6570\u7EC4`);
+  const ids = /* @__PURE__ */ new Set();
+  for (const id of value) {
+    if (typeof id !== "string") throw new Error("Skill ID \u65E0\u6548");
+    assertLocalId(id);
+    if (ids.has(id)) throw new Error(`Skill ID \u91CD\u590D\uFF1A${id}`);
+    ids.add(id);
+  }
+  return ids.size ? Object.freeze([...ids]) : void 0;
+}
+function readSkillFiles(skills, integrity) {
+  const files = {};
+  const declared = new Set(skills ?? []);
+  for (const [name, hash] of Object.entries(integrity)) {
+    if (!name.startsWith(SKILL_ROOT + "/")) continue;
+    const [, id, ...rest] = name.split("/");
+    if (!declared.has(id) || !rest.length || rest.some((part) => !part || part === "." || part === ".."))
+      throw new Error(`Skill \u6587\u4EF6\u4E0D\u5C5E\u4E8E\u5DF2\u58F0\u660E\u7684 Skill\uFF1A${name}`);
+    if (typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))
+      throw new Error("Skill \u6587\u4EF6\u7F3A\u5C11\u6709\u6548\u7684\u5B8C\u6574\u6027\u6458\u8981");
+    files[name] = hash;
+  }
+  for (const id of declared)
+    if (!files[`${skillDirectory(id)}/${SKILL_README}`])
+      throw new Error(`Skill ${id} \u7F3A\u5C11 ${SKILL_README}`);
+  return files;
+}
+
 // packages/plugins/src/package.ts
 var PLUGIN_SHARED_MODULES = [
   "@tau/plugins",
@@ -266,6 +303,12 @@ function validatePluginManifest(value, options = {}) {
       throw new Error("\u63D2\u4EF6\u4EA7\u7269\u7F3A\u5C11\u6709\u6548\u7684\u5B8C\u6574\u6027\u6458\u8981");
     integrity[name] = hash;
   }
+  const skills = readSkillsField(item.skills);
+  if (skills)
+    Object.assign(
+      integrity,
+      readSkillFiles(skills, item.integrity ?? {})
+    );
   return Object.freeze({
     formatVersion: item.formatVersion,
     id: item.id,
@@ -281,6 +324,7 @@ function validatePluginManifest(value, options = {}) {
     ...item.whiteboard === true ? { whiteboard: true } : {},
     ...catalog,
     ...permissions,
+    ...skills ? { skills } : {},
     integrity: Object.freeze(integrity),
     ...styles === void 0 ? {} : { styles }
   });

package/docs/README.md

@@ -0,0 +1,43 @@
+# Tau 插件开发文档
+
+Tau 插件用 TypeScript 和 React 编写，打包成一个 ZIP，安装后在 Tau 桌面端运行。插件可以给 Tau 加页面和侧边栏入口，在文档里放自定义块，给 AI 提供工具，接入第三方存储、语音、视频等服务，或者读写用户的卡片和待办。
+
+这份文档按"从零写出一个插件"的顺序组织。第一次接触时按下面的路线读，之后按需查阅。
+
+## 阅读路线
+
+1. [快速开始](getting-started.md)：装好环境，跑通模板自带的计数器，再把它改成自己的插件。
+2. [插件的组成](plugin-basics.md)：manifest、入口、生命周期和 `context`，所有能力都建立在这些概念上。
+3. 按你要做的功能，读下表中对应的文档。
+4. [发布与更新](release.md)：发布到插件中心，以及之后怎么发新版本。
+
+## 我想……
+
+| 想做的事                                                   | 读这篇                                       |
+| ---------------------------------------------------------- | -------------------------------------------- |
+| 加一个页面、侧边栏入口、命令、设置项，或发送通知           | [界面](ui.md)                                |
+| 保存插件自己的数据、请求网络                               | [存储与网络](storage-and-network.md)         |
+| 读取或修改用户的卡片、文章、项目文档、待办、日程           | [用户数据](user-data.md)                     |
+| 创建插件自己的内容（如周记），带一份可编辑的正文           | [用户数据 · 插件内容](user-data.md#插件内容) |
+| 把外部的划线、批注导入 Tau                                 | [摘录](excerpts.md)                          |
+| 在文档里添加自定义块                                       | [编辑器扩展](editor.md)                      |
+| 在白板上添加自定义元素和工具                               | [白板扩展](whiteboard.md)                    |
+| 调用用户配置的大模型                                       | [AI](ai.md)                                  |
+| 给 Tau 的 AI 助手提供工具                                  | [MCP 工具](mcp.md)                           |
+| 给 AI 提供使用说明，或单独发布一套 Skill                   | [Skill](skills.md)                           |
+| 创建闪卡、打开制卡窗口                                     | [闪卡](flashcards.md)                        |
+| 编译 Tailwind、转换 Markdown、处理音视频                   | [编译与转换服务](services.md)                |
+| 运行 Node.js 代码、调用本机程序                            | [本机后台](backend.md)                       |
+| 接入同步存储、图床、语音、图片生成、视频网站、博客发布目标 | [服务提供方](providers/README.md)            |
+| 开发独立博客站点，读取 Tau 发布的数据                      | [站点数据](site-data.md)                     |
+
+## 约定
+
+- 插件接口从 `@tau/plugins` 导入，界面组件从 `@tau/ui` 导入。它们的实现由 Tau 在运行时提供，模板的构建配置已经处理好，不需要你打包。
+- 文中的 `context` 指 `activate(context)` 收到的插件上下文；代码片段如果没有写出外层结构，默认放在 `activate` 里。
+- 所有接口都有完整的 TypeScript 类型。文档讲用法和规则，参数的精确类型以编辑器里的类型提示为准。
+- 插件需要 Tau 0.59.0 或更高版本。
+
+## 给 AI 编程助手
+
+模板根目录的 `AGENTS.md` 是给 AI 编程助手看的项目指引。用 AI 写插件时，让它先读 `AGENTS.md` 和本目录下与任务相关的文档。

package/docs/ai.md

@@ -0,0 +1,169 @@
+# AI
+
+插件可以调用用户在 Tau 中配置好的大模型。插件拿不到用户的 API Key 和服务地址：请求由 Tau 代为发出，用量记在插件名下，受用户设置的额度约束。
+
+有两种用法：
+
+| 用法                                                | 适合                                                  | 用户需要做什么                   |
+| --------------------------------------------------- | ----------------------------------------------------- | -------------------------------- |
+| [使用 Tau 已有的模型分配](#使用-tau-已有的模型分配) | 功能和 Tau 某项内置 AI 功能相近，如生成标题、理解图片 | 首次使用时授权                   |
+| [自定义 AI 功能](#自定义-ai-功能)                   | 插件特有的功能，需要用户单独选择模型                  | 在插件设置里为功能选择模型并开启 |
+
+大多数插件用第一种就够了，不需要用户额外配置。
+
+## 使用 Tau 已有的模型分配
+
+Tau 的每项内置 AI 功能（对话、标题总结、闪卡制作等）都由用户分配了模型。插件可以申请沿用其中某一项的模型。
+
+### 1. 在 manifest 中声明
+
+```json
+{ "permissions": ["ai:titleSummary"] }
+```
+
+### 2. 申请并调用
+
+```ts
+const model = await context.ai.requestCapability("titleSummary");
+const result = await model.chat({
+  messages: [{ role: "user", content: "为这段文字拟一个简短的标题：……" }],
+});
+console.log(result.text);
+```
+
+第一次申请时，Tau 会询问用户是否允许。每项能力分别授权，用户可以在插件详情页的「权限」中撤销。
+
+可以申请的能力（也可以从 `PLUGIN_AI_CAPABILITIES` 导入）：
+
+| 能力名                         | 沿用的模型分配 |
+| ------------------------------ | -------------- |
+| `chat`                         | 对话功能       |
+| `titleSummary`                 | 标题总结       |
+| `webClip`                      | 网页剪藏       |
+| `podcastGeneration`            | 播客生成       |
+| `flashcardGeneration`          | 闪卡制作       |
+| `aiJudgement`                  | 答案评判       |
+| `transcriptionOptimization`    | 转录断句优化   |
+| `videoSummary`                 | 视频总结       |
+| `videoEbookRewrite`            | 视频电子书重写 |
+| `vibeLearningImageDescription` | 图片理解       |
+| `contentMetadata`              | 笔记元信息     |
+| `contentInsights`              | AI 洞见        |
+
+这里只是借用模型，不会执行 Tau 对应功能的业务流程，也不会自动读取用户数据。提示词和输入由你的插件提供。用户没有为这项能力分配模型时，调用会明确失败，不会自动换成其他模型。
+
+## 自定义 AI 功能
+
+功能和 Tau 已有的能力都不相近时，声明插件自己的 AI 功能。用户在插件详情页的「设置 → AI 配置」中为它选择模型并开启。
+
+```ts
+import { definePlugin } from "@tau/plugins";
+
+declare const __PLUGIN_META__: { id: string; name: string; version: string };
+
+export default definePlugin({
+  ...__PLUGIN_META__,
+  ai: {
+    features: [{ id: "summary", name: "文章摘要", description: "概括用户选择的文章" }],
+  },
+  create: () => ({
+    activate(context) {
+      context.commands.register({
+        id: "summary",
+        title: "生成摘要",
+        async run(input) {
+          const status = await context.ai.getStatus("summary");
+          if (!status.configured || !status.enabled) {
+            context.ai.openSettings("summary");
+            return null;
+          }
+          const result = await context.ai.chat({
+            feature: "summary",
+            messages: [
+              { role: "system", content: "概括主要内容，不添加原文以外的信息。" },
+              { role: "user", content: typeof input === "string" ? input : "请先选择正文。" },
+            ],
+            maxOutputTokens: 1024,
+          });
+          return result.text;
+        },
+      });
+    },
+  }),
+});
+```
+
+`ai.features` 写在插件定义上（静态声明），每项包含 `id`、`name` 和可选的 `description`，最多 32 项。
+
+| 接口                     | 说明                                                     |
+| ------------------------ | -------------------------------------------------------- |
+| `getStatus(feature)`     | 返回 `{ configured, enabled }`：是否已选模型、是否已开启 |
+| `openSettings(feature?)` | 打开插件的 AI 设置，让用户选择模型或开启功能             |
+| `chat(request)`          | 一次性返回完整结果                                       |
+| `stream(request)`        | 流式返回结果                                             |
+
+调用前先用 `getStatus` 检查，没配置好时用 `openSettings` 引导用户，而不是直接报错。
+
+## 发送请求
+
+两种用法的 `chat` 和 `stream` 参数相同，只是自定义功能需要多传一个 `feature`：
+
+| 字段              | 说明                                                |
+| ----------------- | --------------------------------------------------- |
+| `feature`         | 只用于自定义功能：插件声明的功能 ID                 |
+| `messages`        | 消息数组，`role` 为 `system`、`user` 或 `assistant` |
+| `maxOutputTokens` | 可选。最大输出 Token                                |
+| `signal`          | 可选。取消信号                                      |
+
+`chat` 返回 `{ text, usage }`，`usage` 包含输入、输出和总 Token 数，模型服务没有报告用量时为 `null`。
+
+### 流式输出
+
+```ts
+const controller = new AbortController();
+for await (const event of model.stream({
+  messages: [{ role: "user", content: article }],
+  signal: controller.signal,
+})) {
+  if (event.type === "text") appendText(event.delta);
+  else showUsage(event.result.usage);
+}
+// 用户点击「停止」时：controller.abort()
+```
+
+依次产生 `{ type: "text", delta }`，最后产生 `{ type: "done", result }`。
+
+### 多轮对话与图片
+
+- 多轮对话需要你自己维护历史，把之前的消息一起放进 `messages`。多条 `system` 消息会合并成一个系统提示。
+- `user` 消息可以附带图片：`images: [{ data, mimeType }]`。`data` 是不带 `data:` 前缀的 Base64；支持 PNG、JPEG、WebP、GIF，每条消息最多 10 张，整次请求的图片总共不超过 20 MiB。模型本身需要支持图片输入。
+- 接口只提供文本生成，不支持工具调用。需要让 Tau 的 AI 助手调用你的功能，使用 [MCP 工具](mcp.md)。
+
+### 取消
+
+传入 `signal` 并调用 `abort()`，或在 `for await` 中提前 `break`，都会取消请求。插件停用、用户撤销授权时，进行中的请求也会被取消。取消无法退回已经产生的模型费用。
+
+## 用量与额度
+
+插件的所有模型调用都记录在 Tau 的「大语言模型 → 用量统计」中，插件设置里的「查看用量」会跳转并筛选出本插件。记录包含时间、模型、状态、Token、估算费用和耗时，不保存提示词和回复内容。
+
+用户可以为插件设置每日请求次数、每日 Token 和并发数上限。达到并发上限时，新请求直接失败，不会排队。
+
+## 错误
+
+错误消息以稳定的代码开头，可以据此给用户合适的提示：
+
+| 代码                    | 含义                   | 建议                 |
+| ----------------------- | ---------------------- | -------------------- |
+| `AI_NOT_CONFIGURED`     | 没有可用的模型         | 引导用户去设置       |
+| `AI_DISABLED`           | 未授权，或插件已停用   | 引导用户授权         |
+| `AI_UNDECLARED_FEATURE` | 功能没有声明           | 检查 `ai.features`   |
+| `AI_QUOTA_EXCEEDED`     | 今日额度用完           | 提示用户，不要重试   |
+| `AI_CONCURRENCY_LIMIT`  | 同时进行的请求太多     | 等当前请求完成后再发 |
+| `AI_CONFIG_CHANGED`     | 模型分配在请求期间变了 | 可以重试一次         |
+| `AI_ABORTED`            | 已取消                 | 不需要提示           |
+| `AI_REQUEST_FAILED`     | 模型服务请求失败       | 显示错误信息         |
+
+通过 `signal` 取消时，也可能抛出标准的 `AbortError`。
+
+遇到额度不足、拒绝授权这类错误后，不要自动循环重试。不要在模块顶层调用 AI；在 `activate` 中也不要等待 AI 请求完成，以免拖慢插件启用。

package/docs/backend.md

@@ -0,0 +1,168 @@
+# 本机后台
+
+插件的界面代码运行在浏览器环境中，不能使用 Node.js。需要读写本机文件、连接本机设备、调用命令行程序时，给插件加一个**本机后台**：一段在独立 Node.js 进程中运行的代码，界面通过消息调用它。
+
+后台是一个比较重的能力：用户首次运行前需要授权，插件中心也会对带后台的每个版本重点审核。只在浏览器能力确实不够时使用。
+
+## 准备
+
+### 1. 修改 manifest
+
+把 `formatVersion` 改为 `2`，并加上 `backend`：
+
+```json
+{
+  "formatVersion": 2,
+  "minAppVersion": "0.59.0",
+  "main": "main.js",
+  "backend": {
+    "entry": "backend.js",
+    "runtime": "node",
+    "apiVersion": 1,
+    "scope": "application",
+    "activation": "on-demand",
+    "lifetime": "idle",
+    "reason": "读取本机设备状态并显示在插件页面中",
+    "systemAccess": ["network"]
+  }
+}
+```
+
+带后台的插件必须声明 `minAppVersion`。这里只列出相关字段，其余字段与普通插件相同。
+
+| 字段                    | 说明                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- |
+| `entry`                 | 保持 `backend.js`，模板的构建脚本会从 `src/backend.ts` 生成它                                            |
+| `runtime`、`apiVersion` | 保持 `node` 和 `1`                                                                                       |
+| `scope`                 | `application`：整个应用一个后台；`workspace`：每个工作区一个后台                                         |
+| `activation`            | 什么时候启动，见下表                                                                                     |
+| `lifetime`              | `idle`：空闲一段时间后停止，有调用时再启动；`persistent`：一直运行到作用域结束，意外退出时自动重启       |
+| `reason`                | 向用户说明后台用来做什么，1 至 500 字。用户授权时会看到它                                                |
+| `systemAccess`          | 后台会用到的系统能力：`filesystem`（文件）、`network`（网络）、`process`（启动程序），用于告知用户和审核 |
+| `tools`                 | 需要启动外部程序时声明，见[调用外部程序](#调用外部程序)                                                  |
+
+| `activation`      | 启动时机         | 可搭配的 `scope` |
+| ----------------- | ---------------- | ---------------- |
+| `on-demand`       | 界面第一次调用时 | 两者均可         |
+| `app-ready`       | Tau 启动后       | `application`    |
+| `workspace-ready` | 工作区打开后     | `workspace`      |
+
+### 2. 安装 Node.js 类型
+
+```sh
+pnpm add -D @types/node@24.0.0 --save-exact
+```
+
+### 3. 创建 `src/backend.ts`
+
+见下一节。构建脚本检测到 `backend` 声明后，会把 `src/backend.ts` 单独打包成 `backend.js`，和界面代码一起放进同一个 ZIP。
+
+## 定义后台方法
+
+```ts
+// src/backend.ts
+import { defineBackend } from "@tau/plugins/backend";
+import { platform } from "node:os";
+
+export default defineBackend({
+  create() {
+    return {
+      activate(ctx) {
+        ctx.rpc.register(
+          "system.platform",
+          {
+            input: {
+              parse(value: unknown) {
+                if (value !== null) throw new Error("此方法不接受参数");
+                return null;
+              },
+            },
+            output: {
+              parse(value: unknown) {
+                if (typeof value !== "string") throw new Error("平台结果无效");
+                return value;
+              },
+            },
+          },
+          () => platform()
+        );
+      },
+    };
+  },
+});
+```
+
+`ctx.rpc.register(method, schemas, handler)`：
+
+- `schemas.input`、`schemas.output` 是带 `parse` 方法的校验器，必须提供。输入不合法时抛错，错误会返回给调用方。也可以直接使用 zod 等提供 `parse` 方法的校验库。
+- `handler(input, { signal })` 处理请求，`signal` 在调用方取消时中止。
+- 请求和结果必须是 JSON，单条消息不超过 1 MiB。
+
+后台代码可以使用 Node.js 的内置模块，第三方 npm 包会被打进 `backend.js`。只有 `@tau/plugins/backend` 由 Tau 提供。
+
+## 在界面中调用
+
+```ts
+const os = await context.backend.call("system.platform", null, { signal });
+```
+
+| 方法                               | 说明                                                        |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `call(method, input, { signal? })` | 调用后台方法，返回结果                                      |
+| `subscribe(event, listener)`       | 订阅后台推送的事件，返回 `Disposable`                       |
+| `getState()`                       | 查询后台状态：`stopped`、`starting`、`running`、`failed` 等 |
+
+后台用 `ctx.rpc.emit(event, value)` 推送事件，界面用 `subscribe` 接收。插件停用或切换工作区后，旧的连接失效。
+
+不要在界面代码里 `import` 后台文件，两者只通过消息通信。
+
+## 调用外部程序
+
+先在 manifest 的 `backend` 中声明 `process` 能力和要用到的程序：
+
+```json
+{
+  "backend": {
+    "systemAccess": ["process"],
+    "tools": [{ "id": "git", "command": "git", "args": ["--no-pager"] }]
+  }
+}
+```
+
+| 工具字段  | 说明                                   |
+| --------- | -------------------------------------- |
+| `id`      | 工具 ID，以小写字母开头                |
+| `command` | 程序名或绝对路径                       |
+| `args`    | 可选。固定的前置参数，每次调用都会带上 |
+
+最多声明 32 个工具。然后在后台中调用：
+
+```ts
+const result = await ctx.process.run("git", ["status", "--short"], { signal: request.signal });
+// result.exitCode、result.stdout、result.stderr
+```
+
+- 参数按数组原样传递，不经过 Shell，不需要也不能使用引号、管道等 Shell 语法。
+- 单次执行最长 30 秒，stdout 与 stderr 合计最多 512 KiB。
+- 在 Windows 上，`command` 必须能解析到唯一的 `.exe` 文件。
+- 需要取消时，把 RPC 请求的 `signal` 传给 `run`。
+
+## 生命周期与清理
+
+- 不要在模块顶层启动任务，在 `activate` 中开始。
+- 计时器、连接等资源交给 `ctx.register` 托管，后台停止时会自动清理。
+- 长时间运行的任务要响应 `ctx.signal`。
+- `ctx.workspaceId` 在 `workspace` 作用域下是当前工作区，在 `application` 作用域下为 `null`。
+
+## 授权与审核
+
+- 用户首次运行插件的后台前，Tau 会请求本机执行授权。安装插件不等于授权，`app-ready` 等自动启动在没有授权时会等待用户处理。
+- 插件更新后，用户需要重新确认授权。
+- 插件中心会人工审核每个带后台的版本。
+- `systemAccess` 用于告知用户和审核，不是操作系统级的权限限制，后台进程实际上可以访问本机的文件和网络。请如实声明。
+
+## 发布
+
+后台和界面在同一个 ZIP 中，作为一个整体更新，不能只替换 `backend.js`。构建、安装和发布流程与普通插件相同，见[快速开始](getting-started.md)和[发布与更新](release.md)。
+
+插件的管理页面会显示后台的状态、错误、启动耗时和资源占用，便于用户和你排查问题。后台的 stdout、stderr 不会写入 Tau 的日志，需要诊断信息时通过 RPC 返回给界面。