@xiongtao.xt/tau-plugins 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 更新记录
 
+## 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/package.json

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

package/publish-artifacts.js

@@ -36,6 +36,53 @@ 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: "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 +95,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 +120,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 +140,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 +236,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 +246,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,40 @@
+/** 插件中心分类按扩展点划分，顺序即展示顺序；新增面向用户的扩展点时同步扩充。 */
+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: "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/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";