@xiongtao.xt/tau-plugins 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 更新记录
 
+## 0.21.0
+
+- 新增 context.publish 发布提供方、publishConfig 配置表单和文件式／快照式提交协议，本地导出仍由宿主提供。
+- 新增受控 Git 快照发布与缓存目录选择服务，插件不获得任意命令或宿主文件访问。
+- 插件分类新增博客发布。
+
+## 0.20.0
+
+- manifest 支持 `categories`（插件中心分类）与 `keywords`（目录搜索），门户上传严格校验，客户端忽略未知值。
+- 博客模板包（`template` 分支）同样支持分类与关键词，只含静态站点产物，不能同时声明代码插件入口。
+- publish-data：站点级数据（`settings`、`collections`、`cardTagTree`、`projectTrees`）改为只在清单中出现；内容文件新增 `links`，只含本文用到且已发布的站内链接目标。
+- publish-client：`readData` 随正文带回清单的 `settings`；检索引擎按索引缓存，不再每次查询重建。
+
 ## 0.19.0
 
 - 补齐 publish-data 类型、publish-client 纯数据客户端及 publish-artifacts 协议校验/定义求值入口；数据与产物声明不连带载入 Editor/React/UI 类型。

package/PUBLISH-DATA.md

@@ -2,7 +2,7 @@
 
 普通 Tau 插件仍然使用 SDK 类型开发，构建时将宿主注入模块设为 external。SDK 根入口和 UI 包不携带编辑器、组件或页面的运行实现。
 
-独立站点可使用 `@tau/plugins/publish-data` 的纯数据类型，以及 `@tau/plugins/publish-client` 的可执行辅助客户端。后者只有数据读取、摘要校验、取消和搜索，不包含 React、渲染器、路由或预览界面。
+博客模板一般直接使用 `@tau/blog`：它包含数据读取、搜索、正文渲染和内容插件接入，见该包 README。只想读取数据、自己渲染正文的站点，可使用 `@tau/plugins/publish-data` 的纯数据类型和 `@tau/plugins/publish-client` 的数据客户端。客户端只有数据读取、摘要校验、取消和搜索，不包含 React、渲染器、路由或预览界面。
 
 ```ts
 import { createClient } from "@tau/plugins/publish-client";
@@ -12,8 +12,18 @@ const manifest = await client.readManifest();
 const result = await client.readData({ key: manifest.items[0].key });
 ```
 
-模板也可以自行读取协议 JSON。模板自行携带渲染实现并消费 C23 插件产物；宿主不为站点提供 UI 模块。资源以清单或所属数据文件的 URL 为上下文解析，公开路由由模板决定。
+## 数据分布
 
-`@tau/plugins/publish-artifacts` 提供 C23 清单校验、定义求值与节点归属检查，仅处理协议，不提供 UI、模块映射或资源生命周期。其声明不连带加载 SDK 根入口的 Editor/Slate/UI 类型；共享模块由模板通过实际公开能力提供。
+- 清单 `site.<摘要>.json`：站点信息、全部内容的 key 与数据文件、搜索索引引用，以及只出现一次的站点级数据——`settings`（发布外观设置）、`collections`（项目列表）、`cardTagTree`（卡片标签树）、`projectTrees`（按项目 id 的文档目录）。`readData` 会把 `settings` 一并带回。
+- 内容文件：`key`、`meta`、`content`，以及可选的 `links`（本文正文里已发布的站内链接目标）、`pluginRenderers`（内容插件产物）和 `contentStyles`（正文动态样式）。资源以所属数据文件的 URL 为上下文解析。
+- 公开路由完全由模板决定，数据里只有 ContentRef（`{ key, type, id? }`），没有 URL。
 
-可选 `@tau/editor` 是单独的可执行通用编辑器，包含默认内置功能和已编译样式。模板起步工程中的 PublishedContent 负责读取已验证正文、加载插件产物和伴生 CSS，再将扩展及节点交给 Editor；dataUrl 和发布协议不进入 Editor 的 props。普通 SDK/UI 根入口继续保持类型与 Tau 注入边界。
+正文的站内链接由 `@tau/blog` 按 `links` 渲染，模板只提供 `hrefFor`。自己渲染正文的站点按 `links` 的键（`${contentType}:${refId}`，与求索资料的 `citeKey` 同一口径）查目标，查不到即目标未发布。
+
+## 样式
+
+`contentStyles` 是宿主为正文里的 HTML 节点编译的 Tailwind 工具类，属于过渡产物：按原文加载，含 `:root` 主题变量和全局类名，正文挂载期间对整个页面生效。模板若自定义了同名 Tailwind 主题变量，正文挂载时可能被这些默认值覆盖。
+
+## 插件产物
+
+`@tau/plugins/publish-artifacts` 提供 C23 清单校验、定义求值与节点归属检查，仅处理协议，不提供 UI、模块映射或资源生命周期。共享模块由模板通过实际公开能力提供；`@tau/blog` 已内置这部分接入。

package/PUBLISH.md

@@ -0,0 +1,17 @@
+# 博客发布提供方
+
+需要 SDK 0.21.0 及包含博客发布能力的客户端。提供方只在渲染进程注册和执行，网络使用 `context.fetch`。本地导出由宿主提供，不注册本地发布插件。
+
+在 activate 中调用 `context.publish.register({ id: context.pluginId, name, create(config) })`。create 返回文件式或快照式实例，配置是本轮固定的 JSON 副本。提供方 ID 必须等于所属插件 ID。
+
+两种实例都实现 `describe(signal)` 与 `checkConnection(signal)`；describe 返回 `identity`、`basePath`、可选 `publicUrl`。identity 是不含密钥的物理目标稳定身份，不随插件版本、模板、Token 或提交方式变化。basePath 以斜杠开头和结尾，根路径为 `/`。
+
+文件式实例声明 `mode: "files"`，实现 `uploadFile(path, Uint8Array, signal)` 与 `deleteFile(path, signal)`，可用 `concurrency` 声明 1–32 的上限。方法成功返回 void，失败抛出异常。宿主负责增量、重试、依赖先行和入口后置、旧资源清理，不把远端目录当成可任意删除的文件清单。
+
+快照式实例声明 `mode: "snapshot"`，实现 `publish(snapshot, signal)`。snapshot 包含本轮临时 id、待上传文件的路径和摘要及删除路径。只有远端确认整轮提交后才返回；失败抛异常，不返回部分成功。可选 dispose 在会话关闭时回收连接。
+
+Git 快照使用 `context.services.git.publishSnapshot({ publicationId: snapshot.id, remote, branch, author: { name, email }, authentication: { username, password }, cacheId? }, { signal })`。remote 只接受不含凭据的 HTTPS 地址；认证通过任务通道使用，不写入 remote URL。publicationId 仅在所属窗口本轮发布中有效，不能用于读取任意本地文件。需要缓存目录时调用 `context.services.git.selectCacheDirectory({})`，由宿主选择并返回 `{ id, label }`；只保存 id 和展示用 label，不传入任意 cwd 或 shell 命令。
+
+配置视图使用 `context.settings.register({ id, title, target: "publish", component })`。组件接收 `PluginSettingsProps.publishConfig` 的 value 与 save，保存成功后再提交表单值，不用按工作区隔离的 context.storage 保存账号。普通插件详情页提供前往博客发布页的入口。
+
+离开发布页继续运行；停用、切库和发起窗口关闭使旧会话失效。每次请求都传递 signal，错误信息不得包含凭据。新安装默认停用，插件缺失或未启用时宿主保留用户配置及选择，不自动切换其他目标。

package/package.json

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

package/publish-artifacts.js

@@ -36,6 +36,54 @@ function comparePluginVersions(left, right) {
   return 0;
 }
 
+// packages/plugins/src/categories.ts
+var PLUGIN_CATEGORIES = [
+  { id: "sync", label: "\u540C\u6B65" },
+  { id: "upload", label: "\u8D44\u6E90\u4E0A\u4F20" },
+  { id: "editor", label: "\u7F16\u8F91\u5668" },
+  { id: "whiteboard", label: "\u767D\u677F" },
+  { id: "blog-template", label: "\u535A\u5BA2\u6A21\u677F" },
+  { id: "blog-publish", label: "\u535A\u5BA2\u53D1\u5E03" },
+  { id: "ai", label: "AI" },
+  { id: "voice", label: "\u8BED\u97F3" },
+  { id: "page", label: "\u9875\u9762" }
+];
+var PLUGIN_KEYWORD_LIMIT = 5;
+var PLUGIN_KEYWORD_MAX_LENGTH = 20;
+var categoryIds = new Set(PLUGIN_CATEGORIES.map((item) => item.id));
+var isPluginCategory = (value) => typeof value === "string" && categoryIds.has(value);
+function readCatalogFields(item, strict) {
+  const fail = (message) => {
+    if (strict) throw new Error(message);
+  };
+  const list = (value, name) => {
+    if (value === void 0) return [];
+    if (Array.isArray(value)) return value;
+    fail(`${name} \u5FC5\u987B\u662F\u6570\u7EC4`);
+    return [];
+  };
+  const categories = [];
+  for (const value of list(item.categories, "categories")) {
+    if (!isPluginCategory(value)) fail(`\u672A\u77E5\u63D2\u4EF6\u5206\u7C7B\uFF1A${String(value)}`);
+    else if (!categories.includes(value)) categories.push(value);
+  }
+  const keywords = [];
+  for (const value of list(item.keywords, "keywords")) {
+    const keyword = typeof value === "string" ? value.trim() : "";
+    if (!keyword || keyword.length > PLUGIN_KEYWORD_MAX_LENGTH)
+      fail(`\u5173\u952E\u8BCD\u5FC5\u987B\u4E3A 1 \u81F3 ${PLUGIN_KEYWORD_MAX_LENGTH} \u5B57`);
+    else if (!keywords.includes(keyword)) keywords.push(keyword);
+  }
+  if (keywords.length > PLUGIN_KEYWORD_LIMIT) {
+    fail(`\u5173\u952E\u8BCD\u6700\u591A ${PLUGIN_KEYWORD_LIMIT} \u4E2A`);
+    keywords.length = PLUGIN_KEYWORD_LIMIT;
+  }
+  return {
+    ...categories.length ? { categories: Object.freeze(categories) } : {},
+    ...keywords.length ? { keywords: Object.freeze(keywords) } : {}
+  };
+}
+
 // packages/plugins/src/package.ts
 var PLUGIN_SHARED_MODULES = [
   "@tau/plugins",
@@ -48,7 +96,7 @@ var PLUGIN_SHARED_MODULES = [
   "react/jsx-runtime",
   "react/jsx-dev-runtime"
 ];
-function validatePluginManifest(value) {
+function validatePluginManifest(value, options = {}) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("\u63D2\u4EF6\u6E05\u5355\u5FC5\u987B\u662F\u5BF9\u8C61");
   const item = value;
@@ -73,6 +121,7 @@ function validatePluginManifest(value) {
   if (item.editor !== void 0 && item.editor !== true) throw new Error("editor \u53EA\u80FD\u58F0\u660E\u4E3A true");
   if (item.whiteboard !== void 0 && item.whiteboard !== true)
     throw new Error("whiteboard \u53EA\u80FD\u58F0\u660E\u4E3A true");
+  const catalog = readCatalogFields(item, options.strict === true);
   const integrity = {};
   for (const name of [main, ...styles ? [styles] : []]) {
     const hash = item.integrity && typeof item.integrity === "object" ? item.integrity[name] : void 0;
@@ -92,21 +141,12 @@ function validatePluginManifest(value) {
     main,
     ...item.editor === true ? { editor: true } : {},
     ...item.whiteboard === true ? { whiteboard: true } : {},
+    ...catalog,
     integrity: Object.freeze(integrity),
     ...styles === void 0 ? {} : { styles }
   });
 }
 
-// packages/plugins/src/sidebar.ts
-var SIDEBAR_GROUPS = Object.freeze({
-  daily: "daily",
-  knowledge: "knowledge",
-  learning: "learning",
-  ai: "ai",
-  sharing: "sharing",
-  plugins: "plugins"
-});
-
 // packages/plugins/src/rendering.ts
 var PLUGIN_RENDER_VERSION = 1;
 function evaluatePluginPackage(artifact, modules) {
@@ -197,7 +237,6 @@ function assertRenderTypes(definition, expected) {
 }
 
 // packages/plugins/src/publish-artifacts.ts
-var SIDEBAR_GROUPS2 = SIDEBAR_GROUPS;
 var PLUGIN_RENDER_VERSION2 = PLUGIN_RENDER_VERSION;
 function evaluatePluginPackage2(artifact, modules) {
   return evaluatePluginPackage(artifact, modules);
@@ -208,7 +247,6 @@ function assertRenderTypes2(definition, types) {
 export {
   PLUGIN_RENDER_VERSION2 as PLUGIN_RENDER_VERSION,
   PLUGIN_SHARED_MODULES,
-  SIDEBAR_GROUPS2 as SIDEBAR_GROUPS,
   assertRenderTypes2 as assertRenderTypes,
   evaluatePluginPackage2 as evaluatePluginPackage,
   validatePluginManifest

package/publish-client.js

@@ -45,6 +45,7 @@ function createClient({ manifestUrl }) {
   const cache = /* @__PURE__ */ new Map();
   let manifestPromise;
   let searchPromise;
+  let engine;
   function json(url, expected) {
     assert(/^[a-f0-9]{64}$/.test(expected), "INVALID_DATA", "\u6458\u8981\u683C\u5F0F\u9519\u8BEF");
     const filenameHash = new URL(url).pathname.match(/\.([a-f0-9]{64})\.json$/)?.[1];
@@ -207,7 +208,11 @@ function createClient({ manifestUrl }) {
         "IDENTITY_MISMATCH",
         "\u5185\u5BB9\u8EAB\u4EFD\u4E0D\u5339\u914D"
       );
-      return { data: value, dataUrl };
+      return {
+        data: value,
+        dataUrl,
+        ...source.settings ? { settings: source.settings } : {}
+      };
     },
     async search(query, { limit = 12, signal } = {}) {
       cancelled(signal);
@@ -219,13 +224,17 @@ function createClient({ manifestUrl }) {
         signal
       );
       cancelled(signal);
-      const engine = new Fuse(documents, {
-        keys: ["title", "summary", "content", "tags"],
-        includeMatches: true,
-        threshold: 0.3,
-        ignoreLocation: true
-      });
-      return engine.search(normalized, { limit }).map(({ item, matches }) => {
+      if (engine?.documents !== documents)
+        engine = {
+          documents,
+          fuse: new Fuse(documents, {
+            keys: ["title", "summary", "content", "tags"],
+            includeMatches: true,
+            threshold: 0.3,
+            ignoreLocation: true
+          })
+        };
+      return engine.fuse.search(normalized, { limit }).map(({ item, matches }) => {
         const { content: _content, ...hit } = item;
         const ranges = (matches ?? []).flatMap((match) => {
           if (!match.value || !["title", "summary", "content", "tags"].includes(match.key ?? ""))

package/types/packages/markdown/src/codec.d.ts

@@ -41,7 +41,7 @@ export interface MarkdownCodec {
      */
     fence?: {
         language: string | readonly string[];
-        /** 源码落进元素的字段名，默认 "content"（mermaid 用 "chart"） */
+        /** 源码落进元素的字段名，默认 "content"，由领域声明覆盖。 */
         property?: string;
     };
     /**
@@ -69,7 +69,7 @@ export interface MarkdownCodec {
         parent: Descendant | null;
         previousSibling: Descendant | null;
         nextSibling: Descendant | null;
-        /** 把块级子元素降级为行内形态（image→inline-image、html-block→html-inline），无声明则原样返回 */
+        /** 按领域声明把块级子元素降级为行内形态，无声明则原样返回。 */
         demote: (child: Descendant) => Descendant;
     }) => Descendant[] | null;
     /** 按目标类型贡献规范化，先于该类型自身 normalize；按 codec 顺序首个非 null 替换生效。 */

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

@@ -0,0 +1,43 @@
+/** 插件中心分类按扩展点划分，顺序即展示顺序；新增面向用户的扩展点时同步扩充。 */
+export declare const PLUGIN_CATEGORIES: readonly [{
+    readonly id: "sync";
+    readonly label: "同步";
+}, {
+    readonly id: "upload";
+    readonly label: "资源上传";
+}, {
+    readonly id: "editor";
+    readonly label: "编辑器";
+}, {
+    readonly id: "whiteboard";
+    readonly label: "白板";
+}, {
+    readonly id: "blog-template";
+    readonly label: "博客模板";
+}, {
+    readonly id: "blog-publish";
+    readonly label: "博客发布";
+}, {
+    readonly id: "ai";
+    readonly label: "AI";
+}, {
+    readonly id: "voice";
+    readonly label: "语音";
+}, {
+    readonly id: "page";
+    readonly label: "页面";
+}];
+export type PluginCategory = (typeof PLUGIN_CATEGORIES)[number]["id"];
+export declare const PLUGIN_KEYWORD_LIMIT = 5;
+export declare const PLUGIN_KEYWORD_MAX_LENGTH = 20;
+export declare const isPluginCategory: (value: unknown) => value is PluginCategory;
+export interface PluginCatalogFields {
+    categories?: readonly PluginCategory[];
+    keywords?: readonly string[];
+}
+/**
+ * 读取 manifest 中的分类与关键词。
+ * strict 用于门户上传，非法值直接报错；客户端用宽松模式静默丢弃，
+ * 使老客户端不会因词表新增或上限调整而拒收插件。
+ */
+export declare function readCatalogFields(item: Record<string, unknown>, strict: boolean): PluginCatalogFields;

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

@@ -11,6 +11,7 @@ import type { PluginSync } from "./sync";
 import type { PluginUpload } from "./upload";
 import type { PluginTTS } from "./tts";
 import type { PluginImages } from "./images";
+import type { PluginPublish } from "./publish";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { PluginMCP } from "./mcp";
@@ -46,6 +47,7 @@ export interface PluginContext {
     readonly upload: PluginUpload;
     readonly tts: PluginTTS;
     readonly images: PluginImages;
+    readonly publish: PluginPublish;
     readonly sidebar: PluginSidebar;
     readonly excerpts: PluginExcerpts;
     readonly materials: PluginMaterials;

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

@@ -2,6 +2,7 @@ import type { PluginDefinition } from "./contract";
 export type * from "./upload";
 export type * from "./tts";
 export type * from "./images";
+export type * from "./publish";
 export type { JsonValue, Disposable, PluginStorage, PluginCommand, PluginContext, PluginInstance, PluginDefinition, } from "./contract";
 export type { PluginSettings, PluginSettingsDefinition, PluginSettingsProps, PluginSettingsHandle, } from "./settings";
 export * from "./editor";

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

@@ -1,5 +1,7 @@
 export { assertLocalId } from "./ids";
+import { type PluginCategory } from "./categories";
 export { comparePluginVersions } from "./version";
+export { PLUGIN_CATEGORIES, PLUGIN_KEYWORD_LIMIT, PLUGIN_KEYWORD_MAX_LENGTH, isPluginCategory, type PluginCategory, } from "./categories";
 export declare const PLUGIN_SHARED_MODULES: readonly ["@tau/plugins", "@tau/plugins/whiteboard", "@tau/plugins/sync", "@tau/ui", "react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"];
 export interface PluginManifest {
     formatVersion: 1;
@@ -16,6 +18,10 @@ export interface PluginManifest {
     /** 静态编辑器贡献在窗口启动时装配，启停需重启。 */
     editor?: true;
     whiteboard?: true;
+    /** 插件中心分类，作者自填，不与实际注册对账。 */
+    categories?: readonly PluginCategory[];
+    /** 仅参与搜索匹配。 */
+    keywords?: readonly string[];
     integrity: Record<string, string>;
 }
 /** 宿主内部传输的已读取产物，不属于作者运行时 API。 */
@@ -24,6 +30,9 @@ export interface DevelopmentPluginPackage {
     code: string;
     css?: string;
 }
-export declare function validatePluginManifest(value: unknown): PluginManifest;
+/** strict 供门户上传使用：分类或关键词不合规时报错，客户端默认静默丢弃。 */
+export declare function validatePluginManifest(value: unknown, options?: {
+    strict?: boolean;
+}): PluginManifest;
 /** 静态内容贡献在启动时固定，启停与更新需要重启。 */
 export declare const isContentPlugin: (manifest: Pick<PluginManifest, "editor" | "whiteboard">) => boolean;

package/types/packages/plugins/src/publish-artifacts.d.ts

@@ -1,5 +1,4 @@
 export { validatePluginManifest, PLUGIN_SHARED_MODULES } from "./package";
-export declare const SIDEBAR_GROUPS: Readonly<Record<string, string>>;
 import type { DevelopmentPluginPackage } from "./package";
 export declare const PLUGIN_RENDER_VERSION: 1;
 export type { PublishedPluginRender } from "./render-artifact";

package/types/packages/plugins/src/publish-data.d.ts

@@ -27,6 +27,15 @@ export interface SiteData {
         mimeType: string;
     };
 }
+export interface PublishSettings {
+    appearance?: {
+        image?: {
+            borderRadius?: string;
+            shadow?: string | boolean;
+        };
+    };
+}
+/** 站点级数据只在清单中出现一次，各内容文件不重复携带。 */
 export interface DataManifest {
     version: 1;
     site: SiteData;
@@ -35,6 +44,11 @@ export interface DataManifest {
         integrity: string;
     };
     items: ManifestItem[];
+    settings?: PublishSettings;
+    collections?: Collection[];
+    cardTagTree?: CardTagTree[];
+    /** 键为项目 id。 */
+    projectTrees?: Record<string, TreeItem[]>;
 }
 export interface ContentNode {
     [field: string]: unknown;
@@ -205,20 +219,10 @@ export interface CardTagTree {
 export interface PublishedCommon {
     version: 1;
     key: string;
-    tree?: TreeItem[];
-    collections?: Collection[];
-    cardTagTree?: CardTagTree[];
-    contentLinkTargets?: Record<string, ContentRef>;
+    /** 本文正文里已发布的站内链接目标，键与 QuestMaterial.citeKey 同一口径；未发布的链接不在其中。 */
+    links?: Record<string, ContentRef>;
     pluginRenderers?: import("./render-artifact").PublishedPluginRender[];
     contentStyles?: ResourceRef[];
-    settings?: {
-        appearance?: {
-            image?: {
-                borderRadius?: string;
-                shadow?: string | boolean;
-            };
-        };
-    };
 }
 export type PublishedData = {
     [K in DataKind]: PublishedCommon & {
@@ -239,6 +243,8 @@ export type PublishedData = {
 export interface DataResult {
     data: PublishedData;
     dataUrl: string;
+    /** 清单中的发布设置，由客户端随正文带回。 */
+    settings?: PublishSettings;
 }
 export interface SearchDocument extends ContentRef {
     type: "card" | "article" | "doc" | "quest";

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

@@ -0,0 +1,59 @@
+import type { Disposable, JsonValue } from "./contract";
+export interface PublishTarget {
+    /** 物理目标的稳定身份，不包含凭据、插件或模板版本。 */
+    identity: string;
+    basePath: string;
+    publicUrl?: string;
+}
+export interface PublicationSnapshot {
+    /** 宿主为本轮文件计划颁发的临时句柄，不能读取任意本地文件。 */
+    id: string;
+    files: readonly {
+        path: string;
+        hash: string;
+    }[];
+    deletions: readonly string[];
+}
+interface PublishInstanceBase {
+    describe(signal: AbortSignal): Promise<PublishTarget>;
+    checkConnection(signal: AbortSignal): Promise<boolean>;
+    dispose?(): void | Promise<void>;
+}
+export interface FilePublishInstance extends PublishInstanceBase {
+    mode: "files";
+    concurrency?: number;
+    uploadFile(path: string, content: Uint8Array, signal: AbortSignal): Promise<void>;
+    deleteFile(path: string, signal: AbortSignal): Promise<void>;
+}
+export interface SnapshotPublishInstance extends PublishInstanceBase {
+    mode: "snapshot";
+    publish(snapshot: PublicationSnapshot, signal: AbortSignal): Promise<void>;
+}
+export type PublishInstance = FilePublishInstance | SnapshotPublishInstance;
+export interface PublishProviderDefinition {
+    id: string;
+    name: string;
+    create(config: JsonValue): PublishInstance;
+}
+export interface PluginPublish {
+    register(definition: PublishProviderDefinition): Disposable;
+}
+export interface GitSnapshotRequest {
+    publicationId: string;
+    remote: string;
+    branch: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    authentication: {
+        username: string;
+        password: string;
+    };
+    cacheId?: string;
+}
+export interface GitCacheDirectory {
+    id: string;
+    label: string;
+}
+export {};

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

@@ -1,5 +1,6 @@
 import type { Descendant } from "slate";
 import type { MarkdownCodec } from "../../markdown/src/index";
+import type { GitSnapshotRequest, GitCacheDirectory } from "./publish";
 export type { Descendant } from "slate";
 export interface ServiceOptions {
     signal?: AbortSignal;
@@ -39,6 +40,10 @@ export interface MediaInfo {
     }[];
 }
 export interface PluginServices {
+    git: {
+        publishSnapshot(input: GitSnapshotRequest, options?: ServiceOptions): Promise<void>;
+        selectCacheDirectory(input: Record<string, never>, options?: ServiceOptions): Promise<GitCacheDirectory | null>;
+    };
     tailwind: {
         compile(input: {
             source: string;

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 publishConfig?: {
+        readonly value: JsonValue;
+        save(value: JsonValue): Promise<void>;
+    };
     readonly imageConfig?: {
         readonly instanceId: string;
         readonly value: JsonValue;
@@ -35,7 +39,7 @@ export interface PluginSettingsDefinition {
     title: string;
     description?: string;
     /** 提供方配置表单挂载到对应宿主设置；普通插件设置省略。 */
-    target?: "sync" | "upload" | "tts" | "images";
+    target?: "sync" | "upload" | "tts" | "images" | "publish";
     component: ComponentType<PluginSettingsProps>;
 }
 export interface PluginSettingsHandle extends Disposable {