@xiongtao.xt/tau-plugins 0.31.1 → 0.33.0

package/docs/skills.md

@@ -0,0 +1,129 @@
+# Skill
+
+Skill 是给 Tau 的 AI 助手看的使用说明：什么时候该做什么、按什么步骤做，必要时还可以附带参考资料和脚本。Tau 的 Skill 使用通用的 Agent Skills 目录格式，和 Claude Code、Codex 等工具里的 Skill 是同一种东西。
+
+你可以用两种方式分发 Skill：
+
+| 方式                                | 适合                                             | 用户看到的                       |
+| ----------------------------------- | ------------------------------------------------ | -------------------------------- |
+| [随插件附带](#随插件附带)           | 插件提供了块、工具或页面，需要教 AI 怎么配合使用 | Skill 随插件启用出现，停用后消失 |
+| [独立的 Skill 包](#独立的-skill-包) | 一套写作规范、工作流程等，不需要任何插件代码     | 从插件中心安装后，Skill 直接可用 |
+
+两种方式的 Skill 目录写法完全相同。
+
+## 一个 Skill 目录
+
+```text
+skills/
+  chart-authoring/
+    SKILL.md            # 必需：说明正文
+    references/         # 可选：参考资料，AI 需要时再读
+      chart-types.md
+    scripts/            # 可选：AI 可以执行的脚本
+      validate.py
+```
+
+- `skills/` 下的每个子目录是一个 Skill，目录名就是 Skill 的 ID，只能使用字母、数字、点、横线和下划线。
+- 一个包最多 32 个 Skill。
+- 目录里的文件会原样打进插件包。以 `.` 开头的文件、`node_modules` 和 `__pycache__` 会被忽略；不能包含符号链接。
+
+### SKILL.md
+
+```markdown
+---
+name: 图表写作
+description: 用户要在文档里插入或修改图表块时加载，说明图表块的数据格式和常见写法
+---
+
+# 图表写作
+
+## 什么时候用
+
+……
+
+## 步骤
+
+1. ……
+```
+
+开头的 front matter 决定 Skill 在 Tau 中如何显示和调用：
+
+| 字段                       | 说明                                                           |
+| -------------------------- | -------------------------------------------------------------- |
+| `name`                     | 可选。Skill 页显示的名称，省略时使用目录名                     |
+| `description`              | 必需。AI 根据它判断什么时候加载这份 Skill                      |
+| `disable-model-invocation` | 可选。为 `true` 时 AI 不会自动加载，只在用户用 `$` 点名时使用  |
+| `allowed-tools`            | 可选。与 Claude Code 的同名字段一致，列出 Skill 建议使用的工具 |
+
+缺少 `description` 时构建会失败，插件中心也会拒绝提交。
+
+### 附带文件与脚本
+
+- **参考资料**：AI 加载 Skill 后，可以按需读取目录里的其他文件。在 SKILL.md 里写清楚什么情况下该读哪个文件，比把所有内容塞进 SKILL.md 更省上下文。
+- **脚本**：AI 可以执行目录里的脚本，工作目录就是这个 Skill 目录。按扩展名选择解释器：`.py` 用 python3，`.js`、`.mjs`、`.cjs` 用 Node.js，`.sh` 用 bash，`.ts` 用 tsx；其他文件需要有可执行权限。
+- 每次执行脚本前，Tau 都会请用户确认。单次执行最长 120 秒，输出最多保留 64 KiB。
+- 脚本以用户身份运行，没有沙箱。Tau 不会替用户安装 Python 等运行环境，需要时在 README 里写清楚。
+- **带脚本的版本需要插件中心人工审核**（包括 `scripts/` 下的任何文件，以及目录里的 `.js`、`.mjs`、`.cjs`、`.ts`、`.py`、`.sh` 文件），不能通过自动发布直接上架。只含文档的 Skill 不受此限制。
+
+## 随插件附带
+
+在插件项目根目录建一个 `skills/` 目录，放进你的 Skill，然后照常 `pnpm build`：
+
+```text
+my-plugin/
+  manifest.json
+  src/index.tsx
+  skills/
+    chart-authoring/
+      SKILL.md
+```
+
+构建脚本会把 `skills/` 下的每个目录打进插件包，并在打包后的 manifest 中自动写入 `skills` 字段和文件摘要，你不需要改 manifest 或插件代码。
+
+- 插件启用后，Skill 出现在 Tau 的 Skill 页，标注「插件 · 插件名」；插件停用后自动消失。
+- 用户可以在 Skill 页调整它的调用方式（自动、仅手动、停用），或者复制一份到自己的 Skill 目录修改。
+- AI 引用它时使用 `插件ID:目录名`，例如 `yourname.chart:chart-authoring`。
+- 你的插件提供了 [MCP 工具](mcp.md)时，可以在 SKILL.md 里说明什么时候调用哪个工具、参数怎么填。
+
+## 独立的 Skill 包
+
+不需要任何插件代码时，把 Skill 单独做成一个包。用插件模板创建项目，删掉 `src/` 目录，把 `manifest.json` 改成：
+
+```json
+{
+  "formatVersion": 1,
+  "id": "yourname.writing-style",
+  "name": "写作风格",
+  "description": "让 AI 按统一的风格写文章和卡片。",
+  "categories": ["skill"],
+  "keywords": ["写作", "风格"],
+  "version": "1.0.0",
+  "minAppVersion": "0.59.0",
+  "apiVersion": 1,
+  "platform": "desktop"
+}
+```
+
+和代码插件相比，Skill 包**没有** `main`、`format`，也不能声明 `permissions`、`backend`、`editor`、`whiteboard`。构建脚本看到 manifest 里没有 `main`，就会跳过代码打包，只打包 `skills/` 目录。
+
+```text
+writing-style/
+  manifest.json
+  README.md
+  skills/
+    writing-style/
+      SKILL.md
+```
+
+- `pnpm build` 和 `pnpm install:local` 的用法与代码插件相同。安装后在插件页点「重新扫描」，Skill 就会出现在 Skill 页，标注「Skill 包 · 包名」。
+- Skill 包不参与插件启停，用户在 Skill 页逐个调整调用方式或停用。
+- 发布流程与代码插件完全相同，见[发布与更新](release.md)。分类建议填 `skill`。
+- README 照样是给用户看的：这套 Skill 能让 AI 做什么，用户怎么点名使用。
+
+## 写好一份 Skill
+
+- **`description` 决定 AI 会不会在合适的时候用它**。写"在什么情况下加载"，而不是"这份文档是什么"。例如"用户要求生成周报时加载"，而不是"周报指南"。
+- **正文写给 AI 看**：什么时候用、具体步骤、参数含义、正确与错误的例子。
+- **只写与这件事相关的内容**。通用的写作建议对 AI 没有帮助，反而占用上下文。
+- **大段参考资料放进单独的文件**，在 SKILL.md 中说明何时读取。
+- **脚本要能独立运行**：参数通过命令行传入，结果打印到标准输出，失败时以非 0 退出码结束，并输出可读的错误信息。

package/docs/storage-and-network.md

@@ -0,0 +1,62 @@
+# 存储与网络
+
+## 私有存储
+
+`context.storage` 是插件自己的键值存储，适合保存设置、进度、缓存等小块数据。
+
+```ts
+const saved = await context.storage.get("count");
+const count = typeof saved === "number" ? saved : 0;
+await context.storage.set("count", count + 1);
+```
+
+| 方法              | 说明                           |
+| ----------------- | ------------------------------ |
+| `get(key)`        | 读取，不存在时返回 `undefined` |
+| `set(key, value)` | 保存或覆盖                     |
+| `delete(key)`     | 删除                           |
+
+### 数据保存在哪里
+
+- 按插件和工作区隔离：同一个插件在不同工作区读到的是各自的数据，也读不到其他插件的数据。
+- 保存在工作区的笔记库里，随云同步。用户换一台设备，也能读到同样的数据。
+- 停用、重启、更新插件都不会删除数据。用户卸载插件时可以选择是否一并删除。
+- 数据跟随插件 ID。改了 ID，就成了另一个插件，读不到原来的数据。
+
+### 能存什么
+
+值必须是 JSON：`null`、布尔值、字符串、有限数字，以及由它们组成的数组和普通对象。不能存 `undefined`、函数、`Date`、`Map`、`NaN`、`Infinity` 或循环引用；日期先转成字符串或时间戳。
+
+单个值不超过 1 MB。更大的内容（比如一篇长文）放进[插件内容](user-data.md#插件内容)的正文里。
+
+### 使用要点
+
+- **读取后校验**。`get` 返回的是 `JsonValue`，不带类型保证。数据可能来自旧版本的插件，也可能在其他设备上被修改过，使用前先检查结构，不符合时用默认值或提示错误。
+- **改了要保存**。修改 `get` 返回的对象不会自动写回，必须再调用 `set`。
+- **读写不是原子的**。"先 `get` 再 `set`"之间如果有另一次写入，后写的会覆盖先写的。保存期间禁用重复提交，模板的计数器按钮就是这样做的。
+- **兼顾新旧版本**。用户可以把插件恢复到上一版，但数据不会跟着回退。改变数据结构时，让新版本能读懂旧数据，也尽量让旧版本读到新数据时不出错（例如只新增字段，不改已有字段的含义）。
+- **不要存凭据**。账号、Token 这类配置会随笔记库同步，不应放在这里。服务提供方的账号配置使用专门的配置保存接口，见[服务提供方](providers/README.md)。
+
+## 网络请求
+
+用 `context.fetch` 发起网络请求。它的参数和返回值与标准的 `fetch` 相同：
+
+```ts
+const response = await context.fetch("https://api.example.com/status", {
+  headers: { Authorization: `Bearer ${token}` },
+});
+if (!response.ok) throw new Error(`请求失败：${response.status}`);
+const data: unknown = await response.json();
+```
+
+与直接调用浏览器的 `fetch` 相比：
+
+- 请求由 Tau 代为发出，不受浏览器跨域（CORS）限制，也不会携带浏览器的 Cookie。需要认证时，自己在请求头里提供。
+- 插件停用时，进行中的请求会被自动取消。你也可以照常传入自己的 `signal`，两者任一中止都会取消请求。
+
+注意：
+
+- 和标准 `fetch` 一样，HTTP 4xx、5xx 不会抛出异常，要检查 `response.ok`。
+- 响应数据先校验再使用，尤其是写入存储之前。
+- 不要把私人的 API Key 写进源码。需要用户自己的凭据时，让用户在设置中填写。
+- 能读到的用户数据都可以通过网络发送出去。只在功能确实需要时这样做，并在 README 里向用户说明。

package/docs/ui.md

@@ -0,0 +1,336 @@
+# 界面
+
+插件可以通过四种方式出现在 Tau 的界面里：
+
+- **命令**：出现在 Ctrl+K 命令面板中，用户搜索后执行。
+- **页面**：一个完整的 React 页面，和 Tau 自己的页面一样参与前进、后退。
+- **侧边栏入口**：在侧边栏放一个条目，点击打开某个页面。
+- **设置**：插件详情页「设置」中的一个区域。
+
+另外，插件可以随时发送**通知**。
+
+这些都在 `activate(context)` 里注册，插件停用时自动撤销。
+
+## 命令
+
+```ts
+context.commands.register({
+  id: "reset-count",
+  title: "重置计数",
+  run: async () => {
+    await context.storage.set("count", 0);
+    return null;
+  },
+});
+```
+
+| 字段    | 说明                                                                |
+| ------- | ------------------------------------------------------------------- |
+| `id`    | 局部 ID，见 [ID 规则](plugin-basics.md#id-规则)                     |
+| `title` | 命令标题，用户在命令面板里按它搜索                                  |
+| `run`   | 执行函数，可以是异步的。返回值必须是 JSON 值，没有结果时返回 `null` |
+
+- 注册时不会执行命令，用户选中它时才调用 `run`。
+- `run` 的参数 `input` 不保证有内容，命令面板执行时不会传自定义参数。需要用户输入时，打开一个页面或设置让用户填写。
+- `run` 抛出异常表示执行失败。耗时较长的命令应该在界面上给出进度或结果反馈。
+
+## 页面
+
+```tsx
+import type { PluginPageProps } from "@tau/plugins";
+
+function StatsPage({ context }: PluginPageProps) {
+  return <h1>统计</h1>;
+}
+
+// activate 内
+const stats = context.pages.register({ id: "stats", title: "统计", component: StatsPage });
+await stats.open();
+```
+
+| 字段        | 说明                                                                       |
+| ----------- | -------------------------------------------------------------------------- |
+| `id`        | 局部 ID                                                                    |
+| `title`     | 页面标题                                                                   |
+| `component` | React 组件，收到 `context`、`params`、`pageContext` 三个属性               |
+| `match`     | 可选。默认 `"single"`，页面只有一个实例；`"params"` 表示按参数区分多个实例 |
+| `getId`     | 可选。`match: "params"` 时，用它从参数算出实例身份；默认按全部参数区分     |
+
+`register` 返回页面句柄，提供 `open(params?)` 和 `dispose()`。用 `open` 打开页面，不要自己操作浏览器地址或历史记录。
+
+### 带参数的页面
+
+同一个页面需要展示不同对象（例如不同的书）时，使用 `match: "params"`：
+
+```tsx
+function BookPage({ params }: PluginPageProps) {
+  return <h1>书籍：{String(params.bookId)}</h1>;
+}
+
+const book = context.pages.register({
+  id: "book",
+  title: "书籍",
+  component: BookPage,
+  match: "params",
+  getId: params => String(params.bookId),
+});
+
+await book.open({ bookId: "42" });
+```
+
+- 参数是一个扁平对象，值只能是字符串、有限数字或布尔值，不支持数组、嵌套对象和 `null`。
+- 已经打开的同一实例会被复用，不会重复打开。
+- 有了 `getId`，`{ bookId: "42", tab: "notes" }` 和 `{ bookId: "42" }` 会打开同一个实例；没有 `getId` 时它们是两个实例。
+
+### 向 AI 提供页面上下文
+
+用户在你的页面上和 AI 对话时，AI 可以通过 Tau 内置的「获取当前上下文」工具了解用户正在看什么。用 `pageContext.register` 告诉 AI 当前页面的状态：
+
+```tsx
+import { useEffect, useState } from "react";
+import type { PluginPageProps } from "@tau/plugins";
+
+function BookPage({ params, pageContext }: PluginPageProps) {
+  const [chapter, setChapter] = useState(1);
+
+  useEffect(() => {
+    const registration = pageContext.register(() => ({
+      bookId: String(params.bookId),
+      chapter,
+    }));
+    return () => {
+      registration.dispose();
+    };
+  }, [pageContext, params.bookId, chapter]);
+
+  // ...
+}
+```
+
+- 提供函数返回任意 JSON 值，内容和形状完全由你决定。它应该只读取现有状态，不发起请求，也不修改数据。
+- 状态变化时像示例一样重新注册，避免提供函数读到旧值。
+- 每个页面实例同一时间只有一个提供函数。页面隐藏、卸载或插件停用时会自动清理。
+- 只有当前显示的页面实例会被读取。
+
+页面上下文只是让 AI 知道用户在看什么。需要让 AI 能对页面执行操作，另外用 [MCP 工具](mcp.md)提供。
+
+## 侧边栏
+
+侧边栏条目关联一个已注册的页面，点击时打开它，并在该页面显示时高亮。
+
+```ts
+import { SIDEBAR_GROUPS } from "@tau/plugins";
+
+const page = context.pages.register({ id: "counter", title: "计数", component: CounterPage });
+context.sidebar.registerItem({
+  id: "counter",
+  title: "计数",
+  icon: CounterIcon,
+  group: SIDEBAR_GROUPS.daily,
+  page,
+});
+```
+
+| 字段     | 说明                                   |
+| -------- | -------------------------------------- |
+| `id`     | 局部 ID                                |
+| `title`  | 入口名称                               |
+| `page`   | 本次启用中注册的页面句柄               |
+| `params` | 可选。点击时传给页面的参数             |
+| `icon`   | 可选。图标组件，省略时使用默认插件图标 |
+| `group`  | 可选。所在分组，省略时放进「插件」分组 |
+
+### 分组
+
+放进 Tau 已有的分组时，使用 `SIDEBAR_GROUPS` 常量：
+
+| 常量                       | 分组 |
+| -------------------------- | ---- |
+| `SIDEBAR_GROUPS.daily`     | 日常 |
+| `SIDEBAR_GROUPS.knowledge` | 知识 |
+| `SIDEBAR_GROUPS.learning`  | 学习 |
+| `SIDEBAR_GROUPS.ai`        | AI   |
+| `SIDEBAR_GROUPS.sharing`   | 分享 |
+| `SIDEBAR_GROUPS.plugins`   | 插件 |
+
+也可以创建自己的分组，它会显示在 Tau 的分组之后：
+
+```ts
+const group = context.sidebar.registerGroup({ id: "habits", title: "习惯" });
+context.sidebar.registerItem({ id: "water", title: "喝水", group: group.id, page });
+```
+
+引用自建分组时使用返回的 `group.id`，不要直接写 `"habits"`。没有条目的分组不显示；分组被撤销后，其中的条目移到「插件」分组。
+
+同一个带参数的页面可以注册多个入口，分别传不同的 `params`。
+
+### 图标
+
+`icon` 接收组件本身（`icon: CounterIcon`），不是 `<CounterIcon />`，也不是图片地址。图标是一个线性单色的 SVG 组件：
+
+```tsx
+import type { PluginIconProps } from "@tau/plugins";
+
+export function WaterDropIcon({ size = 24, strokeWidth = 2, ...props }: PluginIconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M12 3C9 7 5 11 5 15a7 7 0 0 0 14 0c0-4-4-8-7-12Z" />
+    </svg>
+  );
+}
+```
+
+- Tau 会传入 `size`、`strokeWidth`、`className` 和 `aria-hidden`，图标要把它们透传给 `<svg>`。
+- 颜色用 `currentColor`，这样会跟随明暗主题和选中状态。不要写死宽高和颜色。
+- 也可以直接使用 [lucide-react](https://lucide.dev) 等图标库的组件（先 `pnpm add lucide-react`）。
+
+## 设置
+
+```tsx
+import type { PluginSettingsProps } from "@tau/plugins";
+
+function Preferences({ context }: PluginSettingsProps) {
+  // 用 context.storage 读写设置值
+}
+
+const preferences = context.settings.register({
+  id: "preferences",
+  title: "计数设置",
+  description: "调整计数的步长",
+  component: Preferences,
+});
+```
+
+| 字段          | 说明                                                            |
+| ------------- | --------------------------------------------------------------- |
+| `id`          | 局部 ID                                                         |
+| `title`       | 设置区域的标题                                                  |
+| `description` | 可选。说明文字                                                  |
+| `component`   | React 组件，收到 `context`                                      |
+| `target`      | 服务提供方的配置表单才需要，见[服务提供方](providers/README.md) |
+
+设置区域显示在插件详情页的「设置」里。`register` 返回的句柄提供 `open()`，可以从命令或页面里跳转过去：
+
+```ts
+context.commands.register({
+  id: "open-preferences",
+  title: "打开计数设置",
+  run: async () => {
+    await preferences.open();
+    return null;
+  },
+});
+```
+
+设置值不会自动保存，组件需要自己用 [`context.storage`](storage-and-network.md) 读写。页面和设置同时显示同一份数据时，保存后要刷新另一处的状态，`storage` 本身不会通知变化。模板用 React Query 管理读取、保存和失败状态，可以照着写。
+
+## 通知
+
+```ts
+context.notifications.send({
+  title: "导入完成",
+  body: "新增了 12 条摘录。",
+  tone: "ok",
+});
+```
+
+| 字段      | 说明                                           |
+| --------- | ---------------------------------------------- |
+| `title`   | 标题，必填，最多 200 字                        |
+| `body`    | 可选。正文，最多 5000 字                       |
+| `tone`    | 可选。`neutral`（默认）、`ok`、`danger`        |
+| `mode`    | 可选。通知出现的位置，见下表                   |
+| `sticky`  | 可选。为 `true` 时一直显示，直到用户处理或关闭 |
+| `actions` | 可选。最多两个按钮，其中最多一个主按钮         |
+
+| `mode`         | 出现的位置                                             |
+| -------------- | ------------------------------------------------------ |
+| `auto`（默认） | Tau 窗口在前台时显示在窗口内，否则显示在独立的通知窗口 |
+| `in-app`       | 总是显示在窗口内                                       |
+| `system`       | 总是显示在独立的通知窗口                               |
+
+通知的来源固定显示为你的插件名称。
+
+### 带按钮的通知
+
+```ts
+context.notifications.send({
+  title: "扫描完成",
+  body: "发现 3 处断开的链接。",
+  sticky: true,
+  actions: [
+    {
+      label: "查看",
+      primary: true,
+      onClick: async () => {
+        await reportPage.open();
+      },
+    },
+  ],
+});
+```
+
+| 按钮字段       | 说明                                                      |
+| -------------- | --------------------------------------------------------- |
+| `label`        | 按钮文字，最多 100 字                                     |
+| `onClick`      | 点击时执行，可以是异步的；执行期间按钮显示加载状态        |
+| `primary`      | 可选。是否为主按钮                                        |
+| `resolvedText` | 可选。`onClick` 成功后在通知里显示的结果文字，最多 500 字 |
+
+`onClick` 失败时，错误显示在通知里。插件停用后，旧通知上的按钮不再可用。
+
+### 撤销通知
+
+`send` 返回一个 `Disposable`，调用 `dispose()` 撤销这一条通知。插件停用时，它发出的通知会自动撤销。
+
+发送通知不需要权限，也不需要用户操作触发，适合在异步任务完成时提醒用户。返回句柄只表示通知已经发出，不代表用户已经看到。
+
+## 界面组件与样式
+
+插件界面用 React 编写，可以使用 `@tau/ui` 提供的组件，它们会自动适配 Tau 的主题：
+
+```tsx
+import { useState } from "react";
+import { Button, Dialog, DialogBody, Panel } from "@tau/ui";
+
+export function Help() {
+  const [open, setOpen] = useState(false);
+  return (
+    <Panel>
+      <Button variant="ghost" onClick={() => setOpen(true)}>
+        查看说明
+      </Button>
+      <Dialog open={open} onOpenChange={setOpen} title="使用说明">
+        <DialogBody>数据保存在当前工作区。</DialogBody>
+      </Dialog>
+    </Panel>
+  );
+}
+```
+
+| 组件         | 常用属性                                                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`     | `onClick`、`disabled`、`loading`、`loadingText`；`variant` 可选 `primary`、`secondary`、`soft`、`ghost`、`danger`、`danger-soft`                  |
+| `Panel`      | 内容容器                                                                                                                                          |
+| `Dialog`     | `open`、`onOpenChange`、`title`，`footer` 放操作按钮                                                                                              |
+| `DialogBody` | 弹窗正文                                                                                                                                          |
+| `Sortable`   | 拖动排序：`items`、`getKey`、`onMove(from, to)`、`renderItem(item, state)`，把 `state.handleProps` 展开到拖动手柄上；手柄获得焦点时方向键前后移动 |
+
+完整的组件列表和属性见 `@tau/ui` 的类型提示。
+
+自己写的样式放在 CSS 文件里，在入口中 `import`：
+
+- 选择器加上插件专属前缀（如 `.yourname-counter`），不要修改 `body` 或 Tau 自身元素的样式。
+- 颜色、圆角等使用 Tau 的主题变量（如 `var(--tau-accent)`），这样会跟随用户的主题切换。
+- SVG 图片可以直接在 CSS 里用 `url()` 引用，构建时会内联进样式，不需要额外复制文件。
+- 如果你用 Tailwind 构建插件样式，可以导入 `@tau/plugins/tailwind.css`，它把 Tau 的主题变量映射成 Tailwind 语义类（如 `bg-surface`、`text-ink-1`）。Tau 不会替插件生成 Tailwind 样式，需要你在构建时自己编译。