@xiongtao.xt/tau-plugins 0.4.0 → 0.7.0

package/AI.md

@@ -0,0 +1,75 @@
+# AI 服务
+
+此能力需要 SDK 0.7.0 及以上，以及支持插件 AI 服务的 Tau 客户端。
+
+插件声明 AI 功能，由用户在插件详情的「设置 → AI 配置」分配已有模型并开启授权。全局「大语言模型」设置管理服务商和密钥；插件只能通过 `ctx.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。

package/EDITOR.md

@@ -0,0 +1,188 @@
+# 编辑器扩展
+
+在文档中添加自己的块：比如交互演示、图表、特殊格式的卡片。本文还介绍源码预览块和插件 Skill。需要 Tau 0.59.0 或更高版本。
+
+## 定义一个块
+
+先在 `manifest.json` 中加入 `"editor": true`（完整示例见下文），然后在插件定义里声明 `editorExtensions`：
+
+```tsx
+import { useState } from "react";
+import { definePlugin, defineEditorElement, defineEditorExtension } from "@tau/plugins";
+
+interface CounterElement {
+  type: "example.counter";
+  initial: number;
+  children: { type: "formatted"; text: string }[];
+}
+
+declare module "@tau/plugins" {
+  interface EditorElementMap {
+    "example.counter": CounterElement;
+  }
+}
+
+function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial);
+  return (
+    <div contentEditable={false}>
+      <button onMouseDown={event => event.preventDefault()} onClick={() => setCount(n => n + 1)}>
+        计数：{count}
+      </button>
+    </div>
+  );
+}
+
+export default definePlugin({
+  id: "example.counter",
+  name: "计数块",
+  version: "1.0.0",
+  editorExtensions: [
+    defineEditorExtension({
+      id: "example.counter",
+      elements: [
+        defineEditorElement<CounterElement>({
+          type: "example.counter",
+          kind: "block",
+          isVoid: true,
+          render: ({ attributes, element, children }) => (
+            <div {...attributes}>
+              <Counter initial={element.initial} />
+              {children}
+            </div>
+          ),
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+几点说明：
+
+- 节点上的字段（如 `initial`）是文档数据，会随文档保存；组件里的 `useState` 只是本次显示的状态，不会改动原文。不要把文档内容放进插件私有存储。
+- `editorExtensions` 与插件定义一起静态导出。只提供编辑器扩展的插件可以省略 `create`；同时有命令、页面或设置时照常提供 `create/activate`。
+- 扩展可声明 `elements`、`commands`、`hotkeys`、`menu`、`blockPanel`、`behaviorsFor`，至少包含一个节点类型。`blockPanel` 的 `onClick` 会收到当前编辑器，可用来插入节点。
+- 节点类型和扩展 ID 使用自己的命名空间（如 `yourname.chart`），不要与内置或其他插件的类型重名。
+
+完整的 manifest 示例：
+
+```json
+{
+  "formatVersion": 1,
+  "id": "example.counter",
+  "name": "计数块",
+  "description": "在文档中放入交互计数块。",
+  "version": "1.0.0",
+  "minAppVersion": "0.59.0",
+  "apiVersion": 1,
+  "platform": "desktop",
+  "format": "cjs",
+  "main": "main.js",
+  "editor": true
+}
+```
+
+`styles`、`integrity` 由构建脚本生成，不用手写。
+
+## 启用、停用与卸载
+
+- 编辑器插件的启用、停用和升级在完整重启 Tau 后生效。
+- 停用后，文档里已有的节点会保留，并显示为不可用占位，不会被删除；重新启用后恢复显示。
+- 卸载正在使用的编辑器插件前，需要先停用并重启。
+
+## 块会在哪里显示
+
+块除了显示在桌面编辑器里，还会出现在移动端、浏览器扩展和用户发布的网页中，这些地方都直接使用你在 `elements.render` 中写的同一个组件，不需要另写入口。因此渲染代码要满足：
+
+- 模块顶层和渲染组件能在浏览器中运行，不导入 Electron、Node 或 Tau 客户端内部路径。
+- 不依赖 `activate` 中才赋值的变量，也不调用 `context` 的存储、页面、服务等桌面能力。
+- React、ReactDOM、`@tau/plugins`、`@tau/ui` 由 Tau 提供，保持模板的 external 配置；其他浏览器兼容的 npm 依赖会打进 `main.js`。
+- JS 与 CSS 自包含，图片等静态资源内联为 data URL。
+- 样式使用插件自己的类名前缀，不覆盖 `body` 或 Tau 自身组件的样式。
+- 只读场景下文档不可编辑，但组件自己的交互（按钮、图表缩放等）照常可用。
+
+## Markdown
+
+在插件定义中提供 `editorCodecs`（类型为 `EditorMarkdownCodec[]`），让自定义节点支持 Markdown 导入导出、复制和搜索摘要。序列化与反序列化需要成对设计，只写输出函数不会自动获得导入能力。
+
+codec 会在后台转换时单独加载，不经过 `create/activate`，所以必须是纯转换函数，模块顶层不能访问 `window`、`document` 或激活后的上下文。
+
+## 源码预览块
+
+`SourceBlockEditor` 复用 Tau 的源码预览组件，包括编辑、全屏、错误条、删除与相邻块导航。它不是第二份渲染入口，放在同一 `elements.render` 组件中使用。
+
+```tsx
+import type { ReactNode } from "react";
+import { SourceBlockEditor, useSourceBlock } from "@tau/plugins";
+import { Code } from "lucide-react";
+
+interface SourceElement {
+  type: "example.source";
+  content: string;
+  children: { type: "formatted"; text: string }[];
+}
+declare module "@tau/plugins" {
+  interface EditorElementMap {
+    "example.source": SourceElement;
+  }
+}
+
+function SourceView({ element, children }: { element: SourceElement; children: ReactNode }) {
+  const { update } = useSourceBlock(element);
+  return (
+    <SourceBlockEditor
+      element={element}
+      mode="jsx"
+      title="示例"
+      icon={Code}
+      initValue={element.content}
+      onChange={content => update({ content })}
+    >
+      {children}
+    </SourceBlockEditor>
+  );
+}
+```
+
+| API                                         | 用途                                                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `SourceBlockEditor`                         | `element/mode/title/icon/initValue/onChange` 为必填；`center/extend/fluid` 控制预览布局，`children` 是预览内容 |
+| `useSourceBlock(element)`                   | 返回当前主题 `theme`、可选样式编译器 `compiler` 与节点字段更新函数 `update`；只能在编辑器内调用                |
+| `useReportPreviewError(message, {stale})`   | 向源码预览块上报错误，传 null 清除；stale 表示是否保留了上次预览                                               |
+| `insertSourceBlock(editor, element, line?)` | 插入或替换空段落并聚焦源码，返回插入路径；不能插入时返回 undefined                                             |
+| `sourceBlockParagraphBehavior(type)`        | 放入扩展 `behaviorsFor.paragraph`，支持段首退格聚焦前一源码块                                                  |
+
+`theme` 提供 `isDark` 和 `token(word)`，渲染应响应主题变化。`compiler.compile({source, language})` 返回 Tailwind CSS，language 为 html 或 tsx；它只在桌面编辑器中可用，其他场景读不到编译器，需配合下文的 `styleSources` 使用。这些组件和 hook 由 Tau 提供，不要打包自己的编辑器、Slate React 或源码编辑器实例。
+
+## 动态样式与静态导出
+
+若节点源码中包含动态 Tailwind 类名，在同一个扩展上声明字段：
+
+```ts
+defineEditorExtension({
+  id: "example.demo",
+  elements: [/* 当前扩展的元素定义 */],
+  styleSources: [{ type: "example.demo", field: "content", language: "tsx" }],
+});
+```
+
+在无法运行时编译的场景（如发布的网页），Tau 会据此读取这些节点的 `content` 字段，预先生成样式。源码字段须为字符串，只能登记本插件声明的节点类型。拼接出来的类名（如 `` `bg-${color}` ``）扫描不到，类名要完整写在源码里。
+
+可选 `htmlSerializers: [{type, toHtml(element)}]` 用于复制 HTML、HTML/EPUB 等静态导出，返回 HTML 字符串并自行转义文本。它只用于静态导出，网页显示仍使用 `elements.render`。不声明时按未知节点的默认规则导出，交互式组件在 EPUB 中不会执行。
+
+## 插件 Skill
+
+在 `definePlugin` 的 `skills` 数组中声明 `{id, name, description, content, invocation?}`，为 AI 提供与你的插件配套的写作规范：
+
+| 字段          | 说明                                                   |
+| ------------- | ------------------------------------------------------ |
+| `id`          | 插件内唯一标识；AI 以 `插件ID:技能ID` 引用             |
+| `name`        | Skill 页面显示的名称                                   |
+| `description` | AI 据此判断何时加载，写清适用场景                      |
+| `content`     | 完整的 SKILL.md 正文                                   |
+| `invocation`  | 默认 `auto`（AI 自行加载），设为 `manual` 则仅手动点名 |
+
+插件启用后 Skill 才可用，停用时自动移除。Skill 页面会标明它来自你的插件，用户可以调整调用方式、停用或复制到自己的 Skill 目录。目前每个 Skill 只有一份正文，不支持脚本和附件。
+
+正文可以写在单独的 SKILL.md 中，构建时用 esbuild 的 `.md: text` loader 作为字符串导入。

package/README.md

@@ -1,5 +1,7 @@
-# Tau plugins 作者契约
+# Tau 插件开发包 @tau/plugins
 
-通过 npm 别名安装为 `@tau/plugins`。运行时由 Tau 桌面宿主提供，构建时必须 external；不可在普通 Node.js 程序中直接执行。
+开发 Tau 插件所需的类型与接口，通过 npm 别名安装为 `@tau/plugins`。实际实现由 Tau 客户端在运行时提供，构建时需设为 external，不能在普通 Node.js 程序中直接运行。
 
-模板与使用说明：https://github.com/LastKnightCoder/tau-plugin-template
+从模板开始开发：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)。

package/SERVICES.md

@@ -0,0 +1,139 @@
+# 编译与转换服务
+
+需要在插件里编译 Tailwind、Typst、TikZ，转换 Markdown，或处理音视频时，可以使用这些服务。通过 `context.services` 调用，类型从 `@tau/plugins` 导入，需要 Tau 0.59.0 或更高版本。
+
+所有服务都是异步方法，只处理传入数据并返回结果，不读写笔记、不选择或保存文件、不自动注入样式。
+
+## API 一览
+
+| 方法                                     | 输入                                              | 返回                                |
+| ---------------------------------------- | ------------------------------------------------- | ----------------------------------- |
+| `tailwind.compile(input, options?)`      | `{ source, language?: "html" \| "tsx" \| "jsx" }` | `{ css }`                           |
+| `typst.compile(input, options?)`         | `{ source, format?: "html", inputs?, files? }`    | `{ html }`                          |
+| `markdown.deserialize(source, options?)` | Markdown 字符串                                   | `{ nodes: Descendant[], warnings }` |
+| `markdown.serialize(nodes, options?)`    | `Descendant[]`                                    | `{ markdown, warnings }`            |
+| `markdown.render(source, options?)`      | Markdown 字符串                                   | `{ html, css, warnings }`           |
+| `tikz.compile(input, options?)`          | `{ source }`，包含 `tikzpicture` 环境             | `{ svg }`                           |
+| `ffmpeg.probe(file, options?)`           | `{ name, data: Blob }`                            | `{ format, streams }`               |
+| `ffmpeg.run(input, options?)`            | `{ files, args, outputs }`                        | `{ files, log }`                    |
+
+## 取消与错误
+
+第二个参数均支持 `{ signal: AbortSignal }`。插件停用会自动取消本实例的任务，不必重复传入 `context.signal`。用户主动取消可使用单次任务的 `AbortController`。
+
+```ts
+const controller = new AbortController();
+try {
+  const { html } = await context.services.typst.compile(
+    { source: "= 阅读报告\n本周阅读记录" },
+    { signal: controller.signal }
+  );
+  // 将 html 用于插件自己的预览。
+} catch (error) {
+  if (error instanceof Error && error.name === "AbortError") return;
+  throw error;
+}
+// 对应取消按钮：controller.abort();
+```
+
+失败通过 Promise 拒绝返回 `Error`，`message` 包含可展示的错误信息；不要匹配内部错误文本决定业务流程。Markdown 同步解析/序列化只能在调用前后检查取消，不能中断正在执行的 JavaScript。HTML 转换内部已开始的渲染可能继续完成，但取消后不会交回结果。
+
+## Tailwind
+
+```ts
+const { css } = await context.services.tailwind.compile({
+  source: '<section class="p-4 rounded-tau-md bg-surface text-ink-1">Hello</section>',
+  language: "html",
+});
+```
+
+使用 Tailwind 4，支持 Tau 语义类。返回 theme/utilities，不重复提供 preflight。源码只用于提取完整类名，不执行 TSX/JSX，也不编译 React。动态拼接类名不能保证被提取。Tau 语义类依赖 Tau 提供的 `--tau-*` 变量，离开 Tau 的页面需要自行提供相应主题变量。
+
+固定插件界面通常在打包时编译样式；此服务主要用于运行时生成内容。返回 CSS 由插件自行使用并在停用时清理。
+
+## Typst
+
+目前只输出 HTML 正文片段，不支持 PDF 和 SVG。`inputs` 对应 Typst 的 `sys.inputs`：
+
+```ts
+const { html } = await context.services.typst.compile({
+  source: '#include "parts/intro.typ"\n#sys.inputs.at("title")',
+  inputs: { title: "阅读报告" },
+  files: [{ name: "parts/intro.typ", data: new Blob(["本周阅读记录"]) }],
+});
+```
+
+附件名是本次编译中的相对路径，不能使用绝对路径、`..` 或反斜杠。图片和包含文件等需显式通过 `files` 提供。可用字体依赖客户端运行环境；不承诺任意宏包或排版效果均可导出为 HTML。公式需要使用 Typst 相应的 HTML 写法，不能把 PDF 能力等同于 HTML 支持。
+
+## Markdown 与编辑器节点
+
+```ts
+import type { Descendant } from "@tau/plugins";
+
+const parsed = await context.services.markdown.deserialize("# 标题\n\n* [x] 已完成");
+const nodes: Descendant[] = parsed.nodes;
+const result = await context.services.markdown.serialize(nodes);
+const preview = await context.services.markdown.render(result.markdown, { theme: "light" });
+```
+
+使用与 Tau 客户端一致的语法，包括标题、段落、列表和任务列表、表格、代码、数学公式、图片与媒体、Tau directive 等。`Descendant[]` 是数据，不关联某篇笔记，不写入编辑器。转换可能生成新的节点 UUID，不要依靠反复解析保留节点身份。
+
+优先处理解析得到的节点。Tau 文本节点包含 `type: "formatted"`，不是只写 `{ text: "..." }`；直接构造节点时遵循 SDK 类型。
+
+自定义节点可通过单次调用的 `codecs` 提供编解码器：
+
+```ts
+const result = await context.services.markdown.serialize(nodes, {
+  codecs: [
+    {
+      type: "example.note",
+      serializer: { toMarkdown: (_node: unknown, children: string) => `> ${children}` },
+    },
+  ],
+});
+```
+
+`codecs` 类型为 `EditorMarkdownCodec[]`；同类型替换本次转换的默认 codec，调用结束不保留。编辑器贡献的 codec 不隐式加入服务，需明确传入。仅声明序列化器不会自动得到反序列化规则；需要往返时还需提供相应的 directive 或解析规则。
+
+`warnings` 每项包含 `code`、`message` 和可选节点 `path`。当前报告未识别节点和 HTML 已知降级，不是任意语法、属性的完整无损审计。未知节点序列化可能保留为 Tau 扩展编码，其他 Markdown 工具未必理解。
+
+HTML 渲染不自动执行 TikZ、Typst、Mermaid 编译器；相关节点可能显示源码并返回 `DISPLAY_FALLBACK`，音视频可能显示链接。原始 HTML 和远程资源按客户端导出规则保留，输出不是经过净化的 HTML。`css` 是本次生成内容附带的样式，不包含完整 Tau 页面主题，也不打包图片附件。
+
+## TikZ
+
+```ts
+const { svg } = await context.services.tikz.compile({
+  source: String.raw`\begin{tikzpicture}
+  \draw (0,0) -- (1,1);
+\end{tikzpicture}`,
+});
+```
+
+不要添加 `documentclass` 或 `document` 环境。服务负责包装，返回包含字体样式的 SVG 字符串。这不是完整 LaTeX 文档编译器，不提供任意宏包安装。语法或宏包不支持时明确报错；单次最长 120 秒，可通过 signal 提前取消。
+
+## FFmpeg
+
+`ServiceFile` 为 `{ name: string, data: Blob }`；文件名仅在任务内使用，不是客户端路径。输入输出名称不得重复，目录使用 `/`。文件整体经内存传输，适合可以放进内存的素材，不支持大文件流式处理。
+
+```ts
+const input = { name: "input.wav", data: audioBlob };
+const info = await context.services.ffmpeg.probe(input);
+// format: name、duration（秒或 null）、size（字节或 null）。
+// streams: index、type、codec，可选 width/height/sampleRate/channels。
+
+const result = await context.services.ffmpeg.run(
+  {
+    files: [input],
+    args: ["-i", "input.wav", "-c:a", "pcm_s16le", "output.wav"],
+    outputs: [{ name: "output.wav", mimeType: "audio/wav" }],
+  },
+  {
+    onProgress: ({ time }) => console.log("已处理秒数", time),
+  }
+);
+const outputBlob = result.files[0].data;
+```
+
+`args` 不包含程序名；含空格的参数作为一个数组元素，不额外加 shell 引号。服务设置非交互、覆盖临时输出和进度通道，不要覆盖 `-progress` 或依赖交互 stdin。`outputs` 声明要取回的产物，名称与参数中的输出一致；文件未生成会报错，退出非零不会返回部分成功结果。
+
+`onProgress.time` 是已处理媒体时间（秒），不是百分比。首次使用 FFmpeg 时 Tau 可能需要联网下载，之后会复用；取消任务不会删除已下载的 FFmpeg。`log` 保留最后 64 KiB 诊断输出。返回 MIME 类型由 `outputs.mimeType` 指定，调用者须确保与实际格式一致。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,7 +11,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "type": "module",
-  "description": "Tau 桌面开发插件契约；运行时由宿主提供",
+  "description": "Tau 插件作者类型契约；运行时由宿主提供",
   "exports": {
     ".": {
       "types": "./types/packages/plugins/src/index.d.ts",

package/runtime.js

@@ -1 +1 @@
-throw new Error("Tau 插件模块由桌面宿主提供，请在插件构建中设为 external");
+throw new Error("Tau 插件模块由宿主提供，请在插件构建中设为 external");

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

@@ -25,6 +25,8 @@ export interface EditorRef {
     deselect: () => void;
     /** Get the underlying Slate editor instance */
     getEditor: () => SlateEditor;
+    /** 获取可编辑区根节点（[data-slate-editor]），未挂载时返回 null；宿主测量尺寸用，不要依赖内部 DOM 层级 */
+    getEditableElement: () => HTMLElement | null;
     /** Check if the editor is currently focused */
     isFocus: () => boolean;
 }

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

@@ -0,0 +1,40 @@
+export interface PluginAIFeature {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface PluginAIRequest {
+    feature: string;
+    messages: readonly {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+}
+export interface PluginAIResult {
+    text: string;
+    /** 供应商未报告用量时为 null。 */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    } | null;
+}
+export type PluginAIEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "done";
+    result: PluginAIResult;
+};
+export interface PluginAI {
+    getStatus(feature: string): Promise<{
+        configured: boolean;
+        enabled: boolean;
+    }>;
+    openSettings(feature?: string): void;
+    chat(request: PluginAIRequest): Promise<PluginAIResult>;
+    stream(request: PluginAIRequest): AsyncIterable<PluginAIEvent>;
+}
+export declare const unavailableAI: PluginAI;

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

@@ -1,5 +1,10 @@
 import type { PluginPages } from "./pages";
+import type { PluginSkill } from "./skills";
+import type { PluginAI, PluginAIFeature } from "./ai";
+import type { PluginServices } from "./services";
 import type { PluginEditor } from "./editor";
+import type { PluginEditorExtension } from "./editor";
+import type { MarkdownCodec } from "../../markdown/src/index";
 import type { PluginSettings } from "./settings";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
@@ -35,6 +40,8 @@ export interface PluginContext {
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;
     readonly fetch: typeof globalThis.fetch;
+    readonly services: PluginServices;
+    readonly ai: PluginAI;
     /** 将订阅等资源交给宿主，在停用或激活失败时逆序回收。 */
     register(resource: Disposable): Disposable;
 }
@@ -47,6 +54,13 @@ export interface PluginDefinition {
     readonly name: string;
     readonly version: string;
     readonly apiVersion: 1;
+    /** 静态声明，桌面与博客均装配同一份扩展；模块加载不得依赖桌面激活。 */
+    readonly editorExtensions?: readonly PluginEditorExtension[];
+    readonly editorCodecs?: readonly MarkdownCodec[];
+    readonly skills?: readonly PluginSkill[];
+    readonly ai?: {
+        readonly features: readonly PluginAIFeature[];
+    };
     /** 每次启用创建新实例，运行状态不放在定义对象上。 */
     create(): PluginInstance;
 }

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

@@ -21,8 +21,19 @@ declare module "../../editor/api" {
         [inlineMapBrand]: never;
     }
 }
-export type PluginEditorExtension = Pick<InternalExtension, "id" | "apiVersion" | "elements" | "commands" | "hotkeys" | "menu"> & {
+export type PluginEditorExtension = Pick<InternalExtension, "id" | "apiVersion" | "elements" | "commands" | "hotkeys" | "menu" | "blockPanel" | "behaviorsFor"> & {
     plugins?: never;
+    /** 发布时从节点字段收集 Tailwind 源码，复用宿主编译器。 */
+    styleSources?: readonly {
+        type: string;
+        field: string;
+        language: "html" | "tsx";
+    }[];
+    /** 静态 HTML/EPUB 导出；博客始终使用 elements.render，不经过这里。 */
+    htmlSerializers?: readonly {
+        type: string;
+        toHtml(element: Record<string, unknown>): string;
+    }[];
 };
 export declare function defineEditorExtension(definition: Omit<PluginEditorExtension, "apiVersion">): PluginEditorExtension;
 export interface PluginEditorContribution {

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

@@ -2,7 +2,12 @@ import type { PluginDefinition } from "./contract";
 export type { JsonValue, Disposable, PluginStorage, PluginCommand, PluginContext, PluginInstance, PluginDefinition, } from "./contract";
 export type { PluginSettings, PluginSettingsDefinition, PluginSettingsProps, PluginSettingsHandle, } from "./settings";
 export * from "./editor";
+export { SourceBlockEditor, useSourceBlock, useReportPreviewError, insertSourceBlock, sourceBlockParagraphBehavior, } from "./source-editor";
+export type { SourceBlockEditorProps, PluginRuntimeStyleCompiler } from "./source-editor";
 export * from "./sidebar";
 export type * from "./excerpts";
+export type * from "./services";
+export type { PluginSkill } from "./skills";
 export type { PluginPageDefinition, PluginPageHandle, PluginPageParams, PluginPageProps, PluginPages, } from "./pages";
-export declare function definePlugin(definition: Omit<PluginDefinition, "apiVersion">): PluginDefinition;
+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/services.d.ts

@@ -0,0 +1,103 @@
+import type { Descendant } from "slate";
+import type { MarkdownCodec } from "../../markdown/src/index";
+export type { Descendant } from "slate";
+export interface ServiceOptions {
+    signal?: AbortSignal;
+}
+export interface ServiceWarning {
+    code: string;
+    message: string;
+    path?: number[];
+}
+export interface ServiceFile {
+    /** 任务内的相对文件名，不是宿主文件路径。 */
+    name: string;
+    data: Blob;
+}
+export interface MarkdownServiceOptions extends ServiceOptions {
+    /** 仅参与本次转换，不修改全局编辑器。 */
+    codecs?: readonly MarkdownCodec[];
+}
+export interface MediaProgress {
+    /** 已处理的媒体时间，单位秒；不推测总时长或百分比。 */
+    time: number;
+}
+export interface MediaInfo {
+    format: {
+        name: string;
+        duration: number | null;
+        size: number | null;
+    };
+    streams: {
+        index: number;
+        type: string;
+        codec: string;
+        width?: number;
+        height?: number;
+        sampleRate?: number;
+        channels?: number;
+    }[];
+}
+export interface PluginServices {
+    tailwind: {
+        compile(input: {
+            source: string;
+            language?: "html" | "tsx" | "jsx";
+        }, options?: ServiceOptions): Promise<{
+            css: string;
+        }>;
+    };
+    typst: {
+        compile(input: {
+            source: string;
+            format?: "html";
+            inputs?: Record<string, string>;
+            files?: ServiceFile[];
+        }, options?: ServiceOptions): Promise<{
+            html: string;
+        }>;
+    };
+    markdown: {
+        deserialize(source: string, options?: MarkdownServiceOptions): Promise<{
+            nodes: Descendant[];
+            warnings: ServiceWarning[];
+        }>;
+        serialize(nodes: Descendant[], options?: MarkdownServiceOptions): Promise<{
+            markdown: string;
+            warnings: ServiceWarning[];
+        }>;
+        render(source: string, options?: MarkdownServiceOptions & {
+            theme?: "light" | "dark";
+        }): Promise<{
+            html: string;
+            css: string;
+            warnings: ServiceWarning[];
+        }>;
+    };
+    tikz: {
+        compile(input: {
+            source: string;
+        }, options?: ServiceOptions): Promise<{
+            svg: string;
+        }>;
+    };
+    ffmpeg: {
+        probe(input: ServiceFile, options?: ServiceOptions): Promise<MediaInfo>;
+        /** args 中用任务文件名引用输入和输出；不接受 shell 命令。 */
+        run(input: {
+            files: ServiceFile[];
+            args: string[];
+            outputs: {
+                name: string;
+                mimeType: string;
+            }[];
+        }, options?: ServiceOptions & {
+            onProgress?: (progress: MediaProgress) => void;
+        }): Promise<{
+            files: ServiceFile[];
+            log: string;
+        }>;
+    };
+}
+/** 每个调用同时受调用方与插件实例生命周期约束。 */
+export declare function bindPluginServices(adapter: PluginServices | undefined, lifetime: AbortSignal, assertActive: () => void): PluginServices;

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

@@ -0,0 +1,8 @@
+/** 随插件打包的只读技能；正文可由构建工具从 SKILL.md 导入为字符串。 */
+export interface PluginSkill {
+    id: string;
+    name: string;
+    description: string;
+    content: string;
+    invocation?: "auto" | "manual";
+}

package/types/packages/plugins/src/source-editor.d.ts

@@ -0,0 +1,44 @@
+import type { ReactNode, ReactElement } from "react";
+import type { LucideIcon } from "lucide-react";
+import type { Editor, Element, Path } from "slate";
+import type { ElementBehaviors, ParagraphElement, BlockElement } from "../../editor/api";
+export interface SourceBlockEditorProps {
+    mode: string;
+    title: string;
+    icon: LucideIcon;
+    initValue: string;
+    onChange(value: string): void;
+    element: Element;
+    center?: boolean;
+    extend?: boolean;
+    fluid?: boolean;
+    children?: ReactNode;
+}
+export interface PluginRuntimeStyleCompiler {
+    compile(request: {
+        source: string;
+        language: "html" | "tsx";
+    }): Promise<string>;
+}
+export interface SourceEditorRuntime {
+    SourceBlockEditor(props: SourceBlockEditorProps): ReactElement;
+    useSourceBlock(element: Element): {
+        theme: {
+            isDark: boolean;
+            token(word: string): string;
+        };
+        compiler: PluginRuntimeStyleCompiler | undefined;
+        update(properties: Record<string, unknown>): void;
+    };
+    useReportPreviewError(error: string | null, options?: {
+        stale?: boolean;
+    }): boolean;
+    insertSourceBlock(editor: Editor, element: BlockElement, line?: number): Path | undefined;
+    sourceBlockParagraphBehavior(type: string): ElementBehaviors<ParagraphElement>;
+}
+export declare function configureSourceEditor(value: SourceEditorRuntime): void;
+export declare const SourceBlockEditor: SourceEditorRuntime["SourceBlockEditor"];
+export declare const useSourceBlock: SourceEditorRuntime["useSourceBlock"];
+export declare const useReportPreviewError: SourceEditorRuntime["useReportPreviewError"];
+export declare const insertSourceBlock: SourceEditorRuntime["insertSourceBlock"];
+export declare const sourceBlockParagraphBehavior: SourceEditorRuntime["sourceBlockParagraphBehavior"];

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

@@ -30,7 +30,7 @@
  *
  * 尺寸档是预设不是牢笼（D-011）：sm 380 / md 440（默认）/ lg 560，width 任意值覆盖；
  * 高度默认随内容（上限 78vh），height 定高（仍不超 82vh）。
- * 层级：遮罩容器 z-[340]（Toast 200 < Select/Menu 250 < Tooltip 300 之上）。
+ * 层级：遮罩容器 z-[340]（Select/Menu 250 < Tooltip 300 之上，Toast 360 之下——弹窗里的操作反馈须可见）。
  */
 import { type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type Ref } from "react";
 export interface DialogProps {

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

@@ -19,7 +19,7 @@
  *    D-003 全局注册表（那是命令面板等壳层浮层的仲裁，ui 基础件不反向依赖 page/）
  *
  * 表单控件家族口径：触发器与弹层内搜索框 = surface 亮底 + line-1 描边 + radius-sm——「浮起物」语感，白卡上同底靠描边显形。
- * 层级 z-[250]（命令面板 101 < Toast 200 < Select/Menu 250 < Tooltip 300）。
+ * 层级 z-[250]（命令面板 101 < Select/Menu 250 < Tooltip 300 < Dialog 340 < Toast 360）。
  *
  * 明确不做（M0）：多选/标签模式（M1 value: V[]）· 异步 loading prop（换数组即异步，
  * 过渡态用 emptyText）· 虚拟化（M1）· renderOption 逃生舱（label: ReactNode 已覆盖

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

@@ -5,8 +5,8 @@
  * 可选动作；无关闭钮——整条点击关闭（Sonner 惯例），悬停冻结自动关闭，
  * 同一位置上限 4 条（挤掉最老）。
  * 位置四选一：top-center（默认）/ top-right / bottom-right / bottom-center，
- * 全局默认可经 toast.config 调整、单条可覆写；层级 z-[200]，高于命令面板
- * （z-[101]），搜索报错等反馈在面板打开时仍可见。不接 Esc（浮层退场注册表
+ * 全局默认可经 toast.config 调整、单条可覆写；层级 z-[360]，高于命令面板
+ * （z-[101]）与 Dialog / Drawer（z-[340]），面板或弹窗打开时操作反馈仍可见。不接 Esc（浮层退场注册表
  * 只登记阻断后退的浮层，见 D-003）。
  *
  * 用法：app 壳层挂载 <ToastHost /> 一次；任意处调用 toast.success("已保存")、
@@ -23,6 +23,8 @@ export interface ToastOptions {
     position?: ToastPosition;
     /** 落定后的停留毫秒数；0 = 落定后也常驻（只靠点击关闭）。载入中恒常驻，与本值无关 */
     duration?: number;
+    /** 关闭时回调（自动到时 / 点击整条 / 动作点击 / 同位置超限被挤出 / Host 卸载）；动作 onClick 先于它触发 */
+    onClose?: () => void;
 }
 /**
  * 单条胶囊（受 item 驱动的纯展示件）。导出供样板间（src/showcase）构造
@@ -35,6 +37,7 @@ export interface ToastItem {
     action?: ToastOptions["action"];
     position: ToastPosition;
     duration: number;
+    onClose?: ToastOptions["onClose"];
 }
 declare const defaults: {
     position: ToastPosition;