@xiongtao.xt/tau-plugins 0.31.1 → 0.33.0

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

@@ -12,6 +12,10 @@ export { SourceBlockEditor, useSourceBlock, useReportPreviewError, insertSourceB
 export type { SourceBlockEditorProps, PluginRuntimeStyleCompiler } from "./source-editor";
 export { useInlineSource, insertInlineSource, InlineSourceBoundary } from "./inline-source";
 export { ContentEditor, ContentPreview } from "./components";
+export { useElement, useMediaViewer, BlockToolbar, BlockToolbarButton, BlockToolbarGap, } from "./element";
+export type { ElementAccess, BlockToolbarProps, BlockToolbarButtonProps, EditorElementFrame, } from "./element";
+export { MediaImage, MediaVideo, MediaAudio, useResource, useResourceUpload, useMediaAppearance, } from "./media";
+export type { ResourceKind, ResourceState, ResourceUpload, MediaAppearance, MediaAppearancePreset, MediaImageProps, MediaVideoProps, MediaAudioProps, MediaRuntime, } from "./media";
 export type { ContentEditorProps, ContentPreviewProps } from "./components";
 export * from "./sidebar";
 export type * from "./icons";
@@ -29,7 +33,6 @@ export type { PluginPermission, PluginPermissions, PluginPermissionState, Plugin
 export type * from "./flashcards";
 export type * from "./services";
 export { usePluginServices } from "./service-access";
-export type { PluginSkill } from "./skills";
 export type { PluginMCP, PluginMCPDefinition, PluginMCPTool, PluginMCPTransport } from "./mcp";
 export type { PluginMCPToolResult } from "./mcp";
 export type { PluginChat, PluginToolRendererDefinition, PluginToolRendererProps, ToolCallExecutionState, } from "./chat";

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

@@ -0,0 +1,69 @@
+import type { CSSProperties, ImgHTMLAttributes, MouseEventHandler, ReactElement, ReactNode, Ref, SyntheticEvent, VideoHTMLAttributes } from "react";
+import type { ContentResourceKind } from "../../db-schema/content-resources";
+export type ResourceKind = ContentResourceKind;
+export interface ResourceState {
+    /** 可直接给 img / video / audio 的地址；解析中或失败时为 undefined */
+    src: string | undefined;
+    status: "loading" | "ready" | "error";
+    /** 元素加载失败时调用：作废宿主缓存后重新解析 */
+    retry(): void;
+}
+/** 上传到用户当前的资源存储（本地库、远端或共享文档），返回可写入节点的地址 */
+export type ResourceUpload = (file: File) => Promise<string>;
+export type MediaAppearancePreset = "none" | "sm" | "md" | "lg";
+/** 用户设置（发布站为发布设置）里的媒体默认外观；节点自身的设置优先 */
+export interface MediaAppearance {
+    borderRadius?: MediaAppearancePreset;
+    shadow?: MediaAppearancePreset | boolean;
+}
+export interface MediaImageProps {
+    url: string;
+    alt?: string;
+    className?: string;
+    style?: CSSProperties;
+    onClick?: MouseEventHandler<HTMLImageElement>;
+    onDoubleClick?: MouseEventHandler<HTMLImageElement>;
+    onLoad?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 宿主的回退地址也加载失败后回调 */
+    onLoadError?: () => void;
+    crossOrigin?: ImgHTMLAttributes<HTMLImageElement>["crossOrigin"];
+    /** 默认懒加载 */
+    loading?: "eager" | "lazy";
+    draggable?: boolean;
+    ref?: Ref<HTMLImageElement>;
+}
+export type MediaVideoProps = VideoHTMLAttributes<HTMLVideoElement> & {
+    src: string;
+    playbackRate?: number;
+    onPlaybackRateChange?: (rate: number) => void;
+    /** 播放器底栏信息位，宿主播放器不支持时忽略 */
+    info?: ReactNode;
+    ref?: Ref<HTMLVideoElement>;
+};
+export interface MediaAudioProps {
+    src: string;
+    controls?: boolean;
+    label?: string;
+    labelSlot?: ReactNode;
+    className?: string;
+    ref?: Ref<HTMLAudioElement>;
+}
+/** 宿主注入的实现；在编辑器内按当前文档的作用域生效（共享文档走协作资源），编辑器外用应用默认实现。 */
+export interface MediaRuntime {
+    useResource(url: string, options: {
+        kind: ResourceKind;
+    }): ResourceState;
+    /** 只读编辑器与没有资源存储的宿主（发布站）返回 undefined */
+    useResourceUpload(): ResourceUpload | undefined;
+    useMediaAppearance(): MediaAppearance | undefined;
+    MediaImage(props: MediaImageProps): ReactElement | null;
+    MediaVideo(props: MediaVideoProps): ReactElement | null;
+    MediaAudio(props: MediaAudioProps): ReactElement | null;
+}
+export declare function configureMedia(value: MediaRuntime): void;
+export declare const useResource: MediaRuntime["useResource"];
+export declare const useResourceUpload: MediaRuntime["useResourceUpload"];
+export declare const useMediaAppearance: MediaRuntime["useMediaAppearance"];
+export declare const MediaImage: (props: MediaImageProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+export declare const MediaVideo: (props: MediaVideoProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+export declare const MediaAudio: (props: MediaAudioProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;

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

@@ -29,6 +29,8 @@ export interface PluginManifest {
     keywords?: readonly string[];
     /** 可申请的业务数据权限上限；实际授权由用户在调用时决定。 */
     permissions?: readonly PluginPermission[];
+    /** 包内 `skills/<id>/` 目录，随插件启停。 */
+    skills?: readonly string[];
     integrity: Record<string, string>;
 }
 /** 宿主内部传输的已读取产物，不属于作者运行时 API。 */

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

@@ -44,6 +44,7 @@ export * from "./primitives/datepicker/DateRangePicker";
 export * from "./primitives/ImagePreview";
 export * from "./primitives/Tabs";
 export * from "./primitives/FileDropZone";
+export * from "./primitives/Sortable";
 export * from "./primitives/LoadingOverlay";
 export { lockBodyScroll } from "./hooks/lockBodyScroll";
 export { mergeRefs } from "./primitives/mergeRefs";

package/types/packages/ui/src/primitives/Sortable.d.ts

@@ -0,0 +1,32 @@
+import { type KeyboardEvent, type PointerEvent, type ReactNode } from "react";
+export interface SortableHandleProps {
+    onPointerDown(event: PointerEvent<HTMLElement>): void;
+    onKeyDown(event: KeyboardEvent<HTMLElement>): void;
+    tabIndex: number;
+    "aria-roledescription": string;
+}
+export interface SortableItemState {
+    index: number;
+    /** 正在被拖动的那一项 */
+    dragging: boolean;
+    /** 拖动经过、松手后会放到这里 */
+    over: boolean;
+    /** 展开到拖动手柄上；也可以展开到整项上，整项都能拖 */
+    handleProps: SortableHandleProps;
+}
+export interface SortableProps<T> {
+    items: readonly T[];
+    getKey(item: T): string;
+    /** 把 from 位置的项移到 to 位置 */
+    onMove(from: number, to: number): void;
+    renderItem(item: T, state: SortableItemState): ReactNode;
+    className?: string;
+    /** 每一项外层容器的类名 */
+    itemClassName?: string;
+    disabled?: boolean;
+}
+/**
+ * 列表与网格排序：按住手柄拖到另一项上松手即移到那里；手柄获得焦点时方向键前后移动一位，Esc 取消拖动。
+ * 用指针事件实现，不依赖拖放 API，任何容器（含编辑器里的块）都能用。
+ */
+export declare function Sortable<T>({ items, getKey, onMove, renderItem, className, itemClassName, disabled, }: SortableProps<T>): import("react/jsx-runtime").JSX.Element;

package/types/packages/ui/src/primitives/Tabs.d.ts

@@ -12,8 +12,6 @@ export interface TabsProps<K extends string = string> {
     /** 标签居中（默认左对齐） */
     centered?: boolean;
     className?: string;
-    /** 面板容器类名：标签栏固定、面板独立滚动时由调用方给出高度约束 */
-    panelClassName?: string;
 }
 /** 下划线式标签页（与 desktop 设置页同一视觉语言）；方向键在标签间移动 */
-export declare function Tabs<K extends string = string>({ items, activeKey: activeKeyProp, defaultActiveKey, onChange, centered, className, panelClassName, }: TabsProps<K>): import("react/jsx-runtime").JSX.Element;
+export declare function Tabs<K extends string = string>({ items, activeKey: activeKeyProp, defaultActiveKey, onChange, centered, className, }: TabsProps<K>): import("react/jsx-runtime").JSX.Element;

package/AI.md

@@ -1,116 +0,0 @@
-# AI 服务
-
-自定义 AI 功能需要 SDK 0.7.0；申请应用已有的模型分配需要 SDK 0.27.0。两者都需要包含对应实现的 Tau 客户端。
-
-自定义 AI 功能由插件声明，用户在插件详情的「设置 → AI 配置」分配已有模型并开启授权。全局「大语言模型」设置管理服务商和密钥；这类功能通过 `ctx.ai` 请求模型，接口不返回密钥、连接地址或用户的聊天历史。
-
-## 使用应用已有模型分配
-
-无需声明 `ai.features` 或另配模型。先在 manifest 中声明 `ai:<能力名>` 权限，再申请对应客户端：
-
-```json
-{ "permissions": ["ai:titleSummary"] }
-```
-
-```ts
-const model = await context.ai.requestCapability("titleSummary");
-const result = await model.chat({
-  messages: [{ role: "user", content: "为这段文字拟一个简短标题：……" }],
-});
-console.log(result.text);
-```
-
-申请时由用户选择允许或拒绝；能力分别授权，未声明的申请会被拒绝。返回客户端提供 `chat(request)` 和 `stream(request)`，参数与下文自定义 AI 相同，但不传 `feature`。每次调用复核权限，撤权、停用或切库取消在途生成；额度、并发和用量审计按插件统计。缺少应用模型分配时明确失败，不自动选择其他模型。
-
-当前全部 12 项大模型功能分配均可申请，能力清单也可从 `PLUGIN_AI_CAPABILITIES` 导入：
-
-| 能力名                         | 沿用的应用分配 |
-| ------------------------------ | -------------- |
-| `chat`                         | 对话功能       |
-| `titleSummary`                 | 标题总结       |
-| `webClip`                      | 网页剪藏       |
-| `podcastGeneration`            | 播客生成       |
-| `flashcardGeneration`          | 闪卡生成       |
-| `aiJudgement`                  | 答案评判       |
-| `transcriptionOptimization`    | 转录断句优化   |
-| `videoSummary`                 | 视频总结       |
-| `videoEbookRewrite`            | 视频电子书重写 |
-| `vibeLearningImageDescription` | 图片理解       |
-| `contentMetadata`              | 笔记元信息     |
-| `contentInsights`              | AI 洞见        |
-
-这里复用模型分配，不自动执行宿主的业务流程或读取业务数据；插件传入自己的消息。已有闪卡业务流程由 `context.flashcards` 提供，它内部调用同一通用机制，需声明 `ai:flashcardGeneration`，详见 [FLASHCARDS.md](FLASHCARDS.md)。
-
-图片理解可在 user 消息中传入 `images: [{ data: imageBase64, mimeType: "image/png" }]`。`data` 不带 data: 前缀；支持 PNG、JPEG、WebP、GIF，每条消息最多 10 张，整次请求的 Base64 总长最多 20 MiB，模型须支持图片。图片与消息正文不会写入用量审计。
-
-## 声明自定义 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(ctx) {
-      ctx.commands.register({
-        id: "summary",
-        title: "生成摘要",
-        async run(input) {
-          const status = await ctx.ai.getStatus("summary");
-          if (!status.configured || !status.enabled) {
-            ctx.ai.openSettings("summary");
-            return null;
-          }
-          const result = await ctx.ai.chat({
-            feature: "summary",
-            messages: [
-              { role: "system", content: "概括主要内容，不添加原文以外的信息。" },
-              { role: "user", content: typeof input === "string" ? input : "请先选择正文。" },
-            ],
-            maxOutputTokens: 1024,
-          });
-          return result.text;
-        },
-      });
-    },
-  }),
-});
-```
-
-## 接口
-
-| 接口                     | 返回与用途                                                                          |
-| ------------------------ | ----------------------------------------------------------------------------------- |
-| `getStatus(feature)`     | `{ configured, enabled }`；模型被删除也视为未配置                                   |
-| `openSettings(feature?)` | 打开当前插件设置，由用户分配模型、管理授权                                          |
-| `chat(request)`          | `{ text, usage }`；usage 未知时为 null                                              |
-| `stream(request)`        | 异步迭代器，依次产生 `{ type: "text", delta }`，最后产生 `{ type: "done", result }` |
-
-请求字段：`feature` 必须是插件声明的功能 ID；`messages` 为 system/user/assistant 文本消息数组；`maxOutputTokens` 是可选的最大输出 Token；`signal` 为可选的取消信号。多轮历史由插件传入。多个 system 消息合并为系统提示，不提供工具调用或自动代理执行。
-
-```ts
-const controller = new AbortController();
-for await (const event of ctx.ai.stream({
-  feature: "summary",
-  messages: [{ role: "user", content: article }],
-  signal: controller.signal,
-})) {
-  if (event.type === "text") appendText(event.delta);
-  else showUsage(event.result.usage);
-}
-```
-
-退出迭代、取消 signal、停用插件或用户撤销 AI 授权都会请求取消。不要在模块顶层调用 AI，也不要在遇到额度不足或拒绝授权后自动循环重试。
-
-## 审计与额度
-
-所有模型调用由宿主归属到插件及功能，进入「大语言模型 → 用量统计」，插件设置的「查看用量」会跳转并筛选本插件。记录包含时间、模型、状态、Token、估算费用和耗时，不保存提示词或回复正文。运行中的请求可取消，也可一次关闭插件的 AI 授权。
-
-额度按本机自然日统计，所有窗口共用，并在重启后保留。每日请求次数、每日 Token 和并发限制由用户设置；并发达到上限直接拒绝，不排队。宿主按模型上下文容量加输出上限保守预占 Token，结束后按实际已知用量结算；未知用量保留预占。供应商未报告用量时不能当作零消费；费用为估算，不替代账单。取消无法撤销已经产生的消费。
-
-错误消息以稳定代码开头：`AI_NOT_CONFIGURED`（未配置）、`AI_DISABLED`（未授权或插件已停用）、`AI_UNDECLARED_FEATURE`（未声明）、`AI_QUOTA_EXCEEDED`（每日额度不足）、`AI_CONCURRENCY_LIMIT`（并发已满）、`AI_CONFIG_CHANGED`（模型分配变化）、`AI_ABORTED`（取消）、`AI_REQUEST_FAILED`（模型或审计失败）。本地 AbortSignal 取消也可能抛出标准 AbortError。