@xiongtao.xt/tau-plugins 0.10.0 → 0.12.0

package/MCP.md

@@ -0,0 +1,89 @@
+# 插件 MCP
+
+通过 `context.mcp.register()` 向 Tau 的 AI 提供工具，一个插件可以注册多个 MCP。它们直接出现在已有 MCP 页面和聊天快捷面板，用户可以整项启停、逐工具启停，不需要插件自行开发管理界面。
+
+需要 SDK 0.11.0 和包含此能力的 Tau 0.59.0 桌面客户端构建。旧客户端没有 `context.mcp`，应检查并明确提示升级；SDK 类型版本不能替代客户端能力检查。
+
+## 本地工具和外部服务器
+
+每次注册填写局部 `id`、`name` 和可选 `description`，再提供 `tools` 或 `transport`，两者互斥。相同插件内 MCP 的 ID 不能重复；不同插件可以使用相同局部 ID。每个 MCP 中的工具名称唯一。
+
+下面是一个完整插件示例。第一项提供本地查询函数；第二项连接外部 MCP，示例地址须替换成真实服务。
+
+```ts
+import { definePlugin } from "@tau/plugins";
+
+declare const __PLUGIN_META__: { id: string; name: string; version: string };
+
+export default definePlugin({
+  ...__PLUGIN_META__,
+  create: () => ({
+    activate(context) {
+      if (!context.mcp) throw new Error("请升级到支持插件 MCP 的 Tau 客户端");
+
+      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 }) {
+              signal.throwIfAborted();
+              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) };
+            },
+          },
+        ],
+      });
+
+      context.mcp.register({
+        id: "remote",
+        name: "外部知识服务",
+        transport: { type: "streamable-http", url: "https://your-service.example/mcp" },
+      });
+    },
+  }),
+});
+```
+
+本地工具填写 `name`、`description`、对象类型的 JSON Schema `inputSchema`，以及 `execute(args, { signal })`。执行结果为 `{ content: string }`，结构化数据可用 JSON.stringify 返回。工具名称使用 1–128 位字母、数字、点、横线或下划线；宿主会生成全局工具名称，作者不要自行拼接命名空间。所有插件工具沿用现有 execute 级审批。
+
+需要本地进程时，把 transport 改为下面的结构，命令、参数、工作目录与应用内手动添加 MCP 的含义相同：
+
+```ts
+context.mcp.register({
+  id: "local-server",
+  name: "本地 MCP 服务",
+  transport: {
+    type: "stdio",
+    command: "node",
+    args: ["/path/to/your-server.mjs"],
+  },
+});
+```
+
+该片段放在 activate(context) 内，路径须替换。不会自动安装 Node、Python、npm 包或其他依赖，启动前须具备对应运行环境。stdio 支持可选 args、env、cwd；streamable-http 支持可选 headers。不要把密钥、令牌或用户机器路径打进分发包，用户可在 MCP 页面配置本机连接参数。
+
+## 管理和生命周期
+
+- 激活成功后才展示和提供工具；重复启用不会重复登记。激活失败、插件停用、切库或卸载自动回收。
+- MCP 页面关闭一项只关闭该项 AI 能力，不停用插件的页面、命令或其他 MCP。用户选择会跨启用和重启保留，重新注册不会强行开启。
+- 用户可管理每个工具的开关。插件提供的名称和说明由作者维护；外部服务器支持连接配置、日志和重连，插件函数没有连接配置。
+- 返回的 Disposable 可提前注销单项 MCP，无需再交给 context.register。
+- 工具调用 signal 在取消、插件停用、整项或对应工具关闭时中止，调用上限为 60 秒。异步代码应响应 signal；取消不能撤销已经完成的写入或外部请求。
+- 旧实例、旧数据库和重连前的调用不能转交给新实例。不要缓存上下文到下一次启用。
+- Skill 可描述这些工具的用途；ctx.ai.chat/stream 仍是文本生成接口，不会因为注册 MCP 而自动获得工具调用能力。
+
+## 验证
+
+检查类型并打包后，在包含此实现的客户端启用插件：确认两项 MCP 出现在现有页面和快捷面板；测试整项开关、逐工具开关、外部连接配置和重连，再测试停用、重新启用及重启后偏好保留。真实服务器连接与模型调用需使用自己的服务和已配置的模型。

package/UPLOAD.md

@@ -0,0 +1,33 @@
+# 资源上传插件
+
+需要 SDK 0.12.0 和包含资源上传插件能力的 Tau 0.59.0 客户端。上传返回正文可直接引用的 HTTP(S) 地址；数据库和资源目录同步使用 SYNC.md 的另一套接口。
+
+在 activate 中注册提供方：
+
+```tsx
+context.upload.register({
+  id: context.pluginId,
+  name: "我的资源存储",
+  async upload(file, config) {
+    // 用 context.fetch 请求服务商，认证与路径由本次 config 决定。
+    // file.name 已唯一命名，file.mimeType 是 MIME，file.content 为 Uint8Array。
+    return uploadToStorage(context.fetch, file, config);
+  },
+});
+context.settings.register({
+  id: "upload",
+  title: "我的资源存储",
+  target: "upload",
+  component: UploadSettings,
+});
+```
+
+UploadSettings 接收 PluginSettingsProps。读取 uploadConfig.value，在用户保存时调用 await uploadConfig.save(config)，宿主保存并选中该提供方；不要将同一份上传配置再存到 context.storage。配置是 JsonValue，读取时自行校验字段并给出错误提示。组件在资源存储设置页显示；插件详情页提供跳转入口。
+
+每个插件只能注册一个上传提供方，id 必须等于 context.pluginId。宿主负责压缩、文件唯一命名、本地保存和跨窗口转发。插件只负责远端上传和返回资源地址，不读取用户文件路径，也不修改笔记内容。
+
+请求通过 context.fetch 发送，失败抛出错误，不返回空地址或吞掉失败。停用插件会取消上下文请求并拒绝迟到结果。插件在渲染进程执行，不使用 Node 模块或额外后台入口。
+
+返回地址必须长期可引用；不要返回短期签名 URL。桶或仓库的公开读取策略由用户配置，上传成功不等于匿名用户可以访问。不要自动修改用户桶权限。需要自定义公开域名时由插件设置提供，按对象路径返回完整 URL。
+
+完成后验证：本地模式不调用插件、远端上传成功及失败、保存配置、停用、独立窗口上传、重启恢复。README.md 应说明如何配置公开访问和常见服务商错误。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/types/packages/plugins/src/contract.d.ts

@@ -8,8 +8,10 @@ import type { PluginEditorExtension } from "./editor";
 import type { MarkdownCodec } from "../../markdown/src/index";
 import type { PluginSettings } from "./settings";
 import type { PluginSync } from "./sync";
+import type { PluginUpload } from "./upload";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
+import type { PluginMCP } from "./mcp";
 import type { JsonValue } from "./json";
 export type { JsonValue } from "./json";
 export interface Disposable {
@@ -38,12 +40,14 @@ export interface PluginContext {
     readonly editor: PluginEditor;
     readonly settings: PluginSettings;
     readonly sync: PluginSync;
+    readonly upload: PluginUpload;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;
     readonly fetch: typeof globalThis.fetch;
     readonly services: PluginServices;
     readonly ai: PluginAI;
+    readonly mcp: PluginMCP;
     /** 将订阅等资源交给宿主，在停用或激活失败时逆序回收。 */
     register(resource: Disposable): Disposable;
 }

package/types/packages/plugins/src/index.d.ts

@@ -1,4 +1,5 @@
 import type { PluginDefinition } from "./contract";
+export type * from "./upload";
 export type { JsonValue, Disposable, PluginStorage, PluginCommand, PluginContext, PluginInstance, PluginDefinition, } from "./contract";
 export type { PluginSettings, PluginSettingsDefinition, PluginSettingsProps, PluginSettingsHandle, } from "./settings";
 export * from "./editor";
@@ -8,6 +9,7 @@ export * from "./sidebar";
 export type * from "./excerpts";
 export type * from "./services";
 export type { PluginSkill } from "./skills";
+export type { PluginMCP, PluginMCPDefinition, PluginMCPTool, PluginMCPTransport } from "./mcp";
 export type { PluginPageDefinition, PluginPageHandle, PluginPageParams, PluginPageProps, PluginPages, } from "./pages";
 export declare function definePlugin(definition: Omit<PluginDefinition, "apiVersion" | "create"> & Partial<Pick<PluginDefinition, "create">>): PluginDefinition;
 export type { PluginAI, PluginAIFeature, PluginAIRequest, PluginAIResult, PluginAIEvent, } from "./ai";

package/types/packages/plugins/src/mcp.d.ts

@@ -0,0 +1,45 @@
+import type { Disposable } from "./contract";
+import type { JsonValue } from "./json";
+export type PluginMCPTransport = {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+} | {
+    type: "streamable-http";
+    url: string;
+    headers?: Record<string, string>;
+};
+export interface PluginMCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, JsonValue>;
+        [key: string]: JsonValue | undefined;
+    };
+    execute(args: Record<string, JsonValue>, context: {
+        signal: AbortSignal;
+    }): Promise<{
+        content: string;
+    }> | {
+        content: string;
+    };
+}
+export type PluginMCPDefinition = {
+    id: string;
+    name: string;
+    description?: string;
+} & ({
+    tools: readonly PluginMCPTool[];
+    transport?: never;
+} | {
+    transport: PluginMCPTransport;
+    tools?: never;
+});
+export interface PluginMCP {
+    /** 同一插件可注册多个 MCP；停用时由宿主自动回收。 */
+    register(definition: PluginMCPDefinition): Disposable;
+}
+export declare function snapshotMCPDefinition(definition: PluginMCPDefinition): PluginMCPDefinition;

package/types/packages/plugins/src/settings.d.ts

@@ -3,6 +3,10 @@ import type { Disposable, PluginContext } from "./index";
 import type { JsonValue } from "./json";
 export interface PluginSettingsProps {
     readonly context: PluginContext;
+    readonly uploadConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly syncConfig?: {
         readonly value: JsonValue;
         save(value: JsonValue): Promise<void>;
@@ -13,7 +17,7 @@ export interface PluginSettingsDefinition {
     title: string;
     description?: string;
     /** 同步提供方的配置表单挂载到宿主同步设置。 */
-    target?: "sync";
+    target?: "sync" | "upload";
     component: ComponentType<PluginSettingsProps>;
 }
 export interface PluginSettingsHandle extends Disposable {

package/types/packages/plugins/src/upload.d.ts

@@ -0,0 +1,16 @@
+import type { Disposable, JsonValue } from "./contract";
+export interface UploadFile {
+    /** 宿主已完成压缩和唯一命名，插件只负责追加远端路径前缀。 */
+    name: string;
+    mimeType: string;
+    content: Uint8Array;
+}
+export interface UploadProviderDefinition {
+    id: string;
+    name: string;
+    /** 返回可供正文直接引用的HTTP(S)地址，不返回临时签名URL。 */
+    upload(file: UploadFile, config: JsonValue): Promise<string>;
+}
+export interface PluginUpload {
+    register(definition: UploadProviderDefinition): Disposable;
+}