From cbc89bc04750f93846cced175418825e18adf4e7 Mon Sep 17 00:00:00 2001 From: Ryan Wang Date: Wed, 29 Apr 2026 17:18:54 +0800 Subject: [PATCH] docs: add search-engine and excerpt-generator extension point documentation --- .../server/excerpt-generator.md | 53 ++++++++++++++ .../extension-points/server/search-engine.md | 72 +++++++++++++++++++ .../server/excerpt-generator.md | 53 ++++++++++++++ .../extension-points/server/search-engine.md | 72 +++++++++++++++++++ 4 files changed, 250 insertions(+) create mode 100644 docs/developer-guide/plugin/extension-points/server/excerpt-generator.md create mode 100644 docs/developer-guide/plugin/extension-points/server/search-engine.md create mode 100644 versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/excerpt-generator.md create mode 100644 versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/search-engine.md diff --git a/docs/developer-guide/plugin/extension-points/server/excerpt-generator.md b/docs/developer-guide/plugin/extension-points/server/excerpt-generator.md new file mode 100644 index 00000000..28bc9034 --- /dev/null +++ b/docs/developer-guide/plugin/extension-points/server/excerpt-generator.md @@ -0,0 +1,53 @@ +--- +title: 摘要生成器 +description: 为文章和页面提供摘要生成逻辑的扩展点，可用于自定义摘要生成方式。 +--- + +摘要生成器扩展点用于自定义 Halo 中文章和页面的摘要生成逻辑，例如：使用算法提取关键内容、接入 AI 生成摘要等。 + +```java +public interface ExcerptGenerator extends ExtensionPoint { + + Mono generate(ExcerptGenerator.Context context); + + @Data + @Accessors(chain = true) + class Context { + private String raw; + private String content; + private String rawType; + private Set keywords; + private int maxLength; + } +} +``` + +- `generate` 方法用于生成摘要，参数 `context` 为摘要生成上下文，返回 `Mono` 即生成的摘要内容。 + +`Context` 包含以下字段： + +- `raw`：原始内容。 +- `content`：HTML 格式的内容。 +- `rawType`：原始内容类型。 +- `keywords`：内容中的关键词，用于辅助生成更准确的摘要。 +- `maxLength`：生成摘要的最大长度限制。 + +Halo 在生成文章或页面摘要时，会查找启用的 `ExcerptGenerator` 扩展（单实例扩展点），如果未找到则使用默认实现。默认实现从 HTML 内容中提取纯文本并截取前 150 个字符。 + +`ExcerptGenerator` 对应的 `ExtensionPointDefinition` 如下： + +```yaml +apiVersion: plugin.halo.run/v1alpha1 +kind: ExtensionPointDefinition +metadata: + name: excerpt-generator +spec: + className: run.halo.app.content.ExcerptGenerator + displayName: "摘要生成器" + type: SINGLETON + description: "提供自动生成摘要的方式扩展，如使用算法提取或使用 AI 生成。" +``` + +即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `excerpt-generator`。 + +使用案例可以参考：[Halo 默认摘要生成器](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/core/reconciler/PostReconciler.java) diff --git a/docs/developer-guide/plugin/extension-points/server/search-engine.md b/docs/developer-guide/plugin/extension-points/server/search-engine.md new file mode 100644 index 00000000..c190ea68 --- /dev/null +++ b/docs/developer-guide/plugin/extension-points/server/search-engine.md @@ -0,0 +1,72 @@ +--- +title: 搜索引擎 +description: 为 Halo 提供内容搜索引擎的扩展点，可用于替换默认的搜索实现。 +--- + +搜索引擎扩展点用于扩展 Halo 的内容搜索能力，例如：使用 Elasticsearch、Meilisearch 等替代内置的 Lucene 搜索引擎。 + +```java +public interface SearchEngine extends ExtensionPoint { + + boolean available(); + + void addOrUpdate(Iterable haloDocuments); + + void deleteDocument(Iterable haloDocIds); + + void deleteAll(); + + SearchResult search(SearchOption option); +} +``` + +- `available` 方法用于判断搜索引擎是否可用，返回 `true` 表示可用。 +- `addOrUpdate` 方法用于添加或更新搜索文档。 +- `deleteDocument` 方法用于根据文档 ID 删除搜索文档。 +- `deleteAll` 方法用于删除所有搜索文档。 +- `search` 方法用于执行搜索，参数 `option` 为搜索选项，返回 `SearchResult` 搜索结果。 + +`SearchOption` 包含以下常用字段： + +- `keyword`：搜索关键词。 +- `limit`：返回结果数量限制，默认 10，最大 1000。 +- `highlightPreTag` / `highlightPostTag`：高亮标签，默认 `` / ``。 +- `filterExposed` / `filterRecycled` / `filterPublished`：是否过滤公开/回收站/已发布内容。 +- `includeTypes`：包含的文档类型，例如 `post.content.halo.run`、`singlepage.content.halo.run`。 +- `includeOwnerNames`：包含的文档所有者。 +- `includeCategoryNames` / `includeTagNames`：包含的分类和标签。 + +`HaloDocument` 为搜索文档对象，包含以下字段： + +- `id`：全局唯一文档 ID。 +- `metadataName`：对应扩展的 metadata name。 +- `title`：文档标题。 +- `description`：文档描述。 +- `content`：文档内容（安全内容，无 HTML 标签）。 +- `categories` / `tags`：分类和标签的 metadata name 列表。 +- `published` / `recycled` / `exposed`：发布、回收站、公开状态。 +- `ownerName`：文档所有者。 +- `creationTimestamp` / `updateTimestamp`：创建和更新时间。 +- `permalink`：文档永久链接。 +- `type`：文档类型，例如 `post.content.halo.run`。 + +`SearchEngine` 对应的 `ExtensionPointDefinition` 如下： + +```yaml +apiVersion: plugin.halo.run/v1alpha1 +kind: ExtensionPointDefinition +metadata: + name: search-engine +spec: + className: run.halo.app.search.SearchEngine + displayName: "搜索引擎" + type: SINGLETON + description: "扩展内容搜索引擎" +``` + +即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `search-engine`。 + +使用案例可以参考： + +- [Halo 内置 Lucene 搜索引擎](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/search/lucene/LuceneSearchEngine.java) +- [Meilisearch 搜索插件](https://github.com/halo-sigs/plugin-meilisearch) diff --git a/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/excerpt-generator.md b/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/excerpt-generator.md new file mode 100644 index 00000000..28bc9034 --- /dev/null +++ b/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/excerpt-generator.md @@ -0,0 +1,53 @@ +--- +title: 摘要生成器 +description: 为文章和页面提供摘要生成逻辑的扩展点，可用于自定义摘要生成方式。 +--- + +摘要生成器扩展点用于自定义 Halo 中文章和页面的摘要生成逻辑，例如：使用算法提取关键内容、接入 AI 生成摘要等。 + +```java +public interface ExcerptGenerator extends ExtensionPoint { + + Mono generate(ExcerptGenerator.Context context); + + @Data + @Accessors(chain = true) + class Context { + private String raw; + private String content; + private String rawType; + private Set keywords; + private int maxLength; + } +} +``` + +- `generate` 方法用于生成摘要，参数 `context` 为摘要生成上下文，返回 `Mono` 即生成的摘要内容。 + +`Context` 包含以下字段： + +- `raw`：原始内容。 +- `content`：HTML 格式的内容。 +- `rawType`：原始内容类型。 +- `keywords`：内容中的关键词，用于辅助生成更准确的摘要。 +- `maxLength`：生成摘要的最大长度限制。 + +Halo 在生成文章或页面摘要时，会查找启用的 `ExcerptGenerator` 扩展（单实例扩展点），如果未找到则使用默认实现。默认实现从 HTML 内容中提取纯文本并截取前 150 个字符。 + +`ExcerptGenerator` 对应的 `ExtensionPointDefinition` 如下： + +```yaml +apiVersion: plugin.halo.run/v1alpha1 +kind: ExtensionPointDefinition +metadata: + name: excerpt-generator +spec: + className: run.halo.app.content.ExcerptGenerator + displayName: "摘要生成器" + type: SINGLETON + description: "提供自动生成摘要的方式扩展，如使用算法提取或使用 AI 生成。" +``` + +即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `excerpt-generator`。 + +使用案例可以参考：[Halo 默认摘要生成器](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/core/reconciler/PostReconciler.java) diff --git a/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/search-engine.md b/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/search-engine.md new file mode 100644 index 00000000..c190ea68 --- /dev/null +++ b/versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/search-engine.md @@ -0,0 +1,72 @@ +--- +title: 搜索引擎 +description: 为 Halo 提供内容搜索引擎的扩展点，可用于替换默认的搜索实现。 +--- + +搜索引擎扩展点用于扩展 Halo 的内容搜索能力，例如：使用 Elasticsearch、Meilisearch 等替代内置的 Lucene 搜索引擎。 + +```java +public interface SearchEngine extends ExtensionPoint { + + boolean available(); + + void addOrUpdate(Iterable haloDocuments); + + void deleteDocument(Iterable haloDocIds); + + void deleteAll(); + + SearchResult search(SearchOption option); +} +``` + +- `available` 方法用于判断搜索引擎是否可用，返回 `true` 表示可用。 +- `addOrUpdate` 方法用于添加或更新搜索文档。 +- `deleteDocument` 方法用于根据文档 ID 删除搜索文档。 +- `deleteAll` 方法用于删除所有搜索文档。 +- `search` 方法用于执行搜索，参数 `option` 为搜索选项，返回 `SearchResult` 搜索结果。 + +`SearchOption` 包含以下常用字段： + +- `keyword`：搜索关键词。 +- `limit`：返回结果数量限制，默认 10，最大 1000。 +- `highlightPreTag` / `highlightPostTag`：高亮标签，默认 `` / ``。 +- `filterExposed` / `filterRecycled` / `filterPublished`：是否过滤公开/回收站/已发布内容。 +- `includeTypes`：包含的文档类型，例如 `post.content.halo.run`、`singlepage.content.halo.run`。 +- `includeOwnerNames`：包含的文档所有者。 +- `includeCategoryNames` / `includeTagNames`：包含的分类和标签。 + +`HaloDocument` 为搜索文档对象，包含以下字段： + +- `id`：全局唯一文档 ID。 +- `metadataName`：对应扩展的 metadata name。 +- `title`：文档标题。 +- `description`：文档描述。 +- `content`：文档内容（安全内容，无 HTML 标签）。 +- `categories` / `tags`：分类和标签的 metadata name 列表。 +- `published` / `recycled` / `exposed`：发布、回收站、公开状态。 +- `ownerName`：文档所有者。 +- `creationTimestamp` / `updateTimestamp`：创建和更新时间。 +- `permalink`：文档永久链接。 +- `type`：文档类型，例如 `post.content.halo.run`。 + +`SearchEngine` 对应的 `ExtensionPointDefinition` 如下： + +```yaml +apiVersion: plugin.halo.run/v1alpha1 +kind: ExtensionPointDefinition +metadata: + name: search-engine +spec: + className: run.halo.app.search.SearchEngine + displayName: "搜索引擎" + type: SINGLETON + description: "扩展内容搜索引擎" +``` + +即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `search-engine`。 + +使用案例可以参考： + +- [Halo 内置 Lucene 搜索引擎](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/search/lucene/LuceneSearchEngine.java) +- [Meilisearch 搜索插件](https://github.com/halo-sigs/plugin-meilisearch)