@xiongtao.xt/tau-plugins 0.31.1 → 0.33.0

package/docs/excerpts.md

@@ -0,0 +1,126 @@
+# 摘录
+
+如果你的插件从外部服务读取划线、批注或收藏（读书笔记、网页高亮、文献批注等），可以把它们写成 Tau 的**摘录**。写入后，用户能在全局搜索和 AI 对话中找到它们，在文档中引用，也能把它们转为卡片或问题。
+
+摘录属于用户：插件停用或卸载后，已经写入的摘录和引用都会保留。
+
+## 注册提供方
+
+写入摘录之前，先在 `activate` 中注册一次提供方：
+
+```ts
+const bookPage = context.pages.register({
+  id: "book",
+  title: "书籍",
+  component: BookPage,
+  match: "params",
+});
+
+context.excerpts.register({
+  label: "我的读书笔记",
+  open: ({ sourceKey, externalId }) => bookPage.open({ bookId: sourceKey, noteId: externalId }),
+});
+```
+
+| 字段    | 说明                                                                                       |
+| ------- | ------------------------------------------------------------------------------------------ |
+| `label` | 摘录来源的显示名称，1 至 100 字。插件停用后仍用它显示来源                                  |
+| `open`  | 可选。用户点「打开原处」时调用，通常打开插件自己的页面并定位；省略时打开摘录或来源的 `url` |
+
+每次启用只能注册一次，没有注册就写入会报错。
+
+## 写入
+
+摘录按**来源**分组写入，一个来源可以是一本书、一个网页或一篇文献。写入有两种方式：
+
+```ts
+const source = { key: "book-42", title: "设计心理学", url: "https://example.com/books/42" };
+
+// 全量：以这批条目为准，不在其中的已有条目会被移除
+await context.excerpts.replace(source, [
+  {
+    externalId: "n1",
+    quote: "好的设计是让人一眼就知道怎么用。",
+    location: "第 1 章",
+    time: 1760000000000,
+  },
+  { externalId: "n2", quote: "示能决定了可能的操作。", note: "和交互设计课的观点一致" },
+]);
+
+// 增量：只新增、更新或移除指定条目
+await context.excerpts.patch(source, {
+  upsert: [{ externalId: "n3", quote: "反馈要及时。" }],
+  remove: ["n1"],
+});
+```
+
+外部服务能一次给出某个来源的全部条目时用 `replace`，只拿到变化时用 `patch`。两者都返回 `{ inserted, updated, deleted }`。`replace` 传入空数组表示整个来源已经不存在。
+
+| 来源字段 | 说明                                                    |
+| -------- | ------------------------------------------------------- |
+| `key`    | 来源在本插件内的稳定标识，必填，最长 512 字             |
+| `title`  | 来源标题，最长 500 字                                   |
+| `url`    | 可选。http(s) 地址，条目没有自己的 `url` 时用它打开原处 |
+
+| 条目字段     | 说明                                                                            |
+| ------------ | ------------------------------------------------------------------------------- |
+| `externalId` | 条目在本插件内的唯一标识，必填，最长 512 字                                     |
+| `quote`      | 摘录原文，必填，最长 20000 字                                                   |
+| `note`       | 可选。用户写的想法或批注                                                        |
+| `location`   | 可选。给人看的位置，如「第 3 章 · 标题」「第 12 页」，最长 500 字               |
+| `url`        | 可选。条目级的 http(s) 深链，优先于来源的 `url`                                 |
+| `anchor`     | 可选。插件自己的定位数据，JSON 对象，序列化后不超过 8000 字；Tau 只保存，不解读 |
+| `color`      | 可选。划线颜色，最长 50 字                                                      |
+| `time`       | 可选。在原服务中的创建时间（毫秒时间戳）                                        |
+
+### externalId 要稳定
+
+Tau 中对一条摘录的引用，靠 `externalId` 找到它。只要 `externalId` 不变，引用就一直有效。
+
+- 用外部数据里稳定的标识生成 `externalId`，例如原服务的笔记 ID。改变生成规则，会让旧摘录被移除、用户的引用失效。
+- 被移除的摘录不会真正删除：原文仍然保留，引用仍然能显示。以后同一个 `externalId` 再次写入时，它会恢复。
+
+### 限制
+
+- 单次写入最多 20000 条。同一批中 `externalId` 不能重复，同一次 `patch` 不能同时写入和移除同一条。
+- 任何一条不合法时，整批拒绝。
+- 外部服务分页返回时，确认拿到完整列表后再调用 `replace`。用不完整的结果覆盖，会误移除条目。
+
+## 读回
+
+```ts
+const sources = await context.excerpts.sources(); // [{ key, title, count }]
+const entries = await context.excerpts.items("book-42");
+```
+
+- `sources()` 列出本插件写入过的来源，`count` 是未移除的条目数。
+- `items(sourceKey)` 返回该来源的全部条目，包括已移除的（`deleted: true`），可以用来离线展示，或与外部数据比对。
+- 每个条目带有 `ref`，用于下面的材料动作。
+
+## 材料动作
+
+摘录等内容在 Tau 中统称**材料**。`context.materials.actions(ref)` 返回 Tau 当前能对这条材料执行的操作，例如「转为卡片」「转为问题」，适合放在插件自己的列表或详情页里：
+
+```tsx
+import { useEffect, useState } from "react";
+import { Button } from "@tau/ui";
+import type { PluginContext, PluginMaterialAction, PluginMaterialRef } from "@tau/plugins";
+
+function NoteActions({ context, target }: { context: PluginContext; target: PluginMaterialRef }) {
+  const [actions, setActions] = useState<PluginMaterialAction[]>([]);
+  useEffect(() => {
+    void context.materials.actions(target).then(list => {
+      if (!context.signal.aborted) setActions(list);
+    });
+  }, [context, target]);
+  return actions.map(action => (
+    <Button key={action.id} variant="ghost" onClick={() => void action.run()}>
+      {action.label}
+    </Button>
+  ));
+}
+```
+
+- `ref` 来自 `excerpts.items()` 返回的条目，原样传回即可，不要自己构造或解析。
+- 直接用 `label` 作为按钮文字，不要按 `id` 写死列表，Tau 以后可能增加新的动作。
+- 动作执行后由 Tau 给出成功或失败的提示，插件不需要再提示。

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>`，注册失败时抛出异常。插件停用时自动注销。