Skip to content

Commit 930d951

Browse files
ruibabyruibaby
authored
docs: add search-engine and excerpt-generator extension point documentation (#587)
1 parent 7a5ca0a commit 930d951

4 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎docs/developer-guide/plugin/extension-points/server/excerpt-generator.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: 摘要生成器
3+
description: 为文章和页面提供摘要生成逻辑的扩展点，可用于自定义摘要生成方式。
4+
---
5+
6+
摘要生成器扩展点用于自定义 Halo 中文章和页面的摘要生成逻辑，例如：使用算法提取关键内容、接入 AI 生成摘要等。
7+
8+
```java
9+
public interface ExcerptGenerator extends ExtensionPoint {
10+
11+
Mono<String> generate(ExcerptGenerator.Context context);
12+
13+
@Data
14+
@Accessors(chain = true)
15+
class Context {
16+
private String raw;
17+
private String content;
18+
private String rawType;
19+
private Set<String> keywords;
20+
private int maxLength;
21+
}
22+
}
23+
```
24+
25+
- `generate` 方法用于生成摘要，参数 `context` 为摘要生成上下文，返回 `Mono<String>` 即生成的摘要内容。
26+
27+
`Context` 包含以下字段：
28+
29+
- `raw`：原始内容。
30+
- `content`：HTML 格式的内容。
31+
- `rawType`：原始内容类型。
32+
- `keywords`：内容中的关键词，用于辅助生成更准确的摘要。
33+
- `maxLength`：生成摘要的最大长度限制。
34+
35+
Halo 在生成文章或页面摘要时，会查找启用的 `ExcerptGenerator` 扩展（单实例扩展点），如果未找到则使用默认实现。默认实现从 HTML 内容中提取纯文本并截取前 150 个字符。
36+
37+
`ExcerptGenerator` 对应的 `ExtensionPointDefinition` 如下：
38+
39+
```yaml
40+
apiVersion: plugin.halo.run/v1alpha1
41+
kind: ExtensionPointDefinition
42+
metadata:
43+
name: excerpt-generator
44+
spec:
45+
className: run.halo.app.content.ExcerptGenerator
46+
displayName: "摘要生成器"
47+
type: SINGLETON
48+
description: "提供自动生成摘要的方式扩展，如使用算法提取或使用 AI 生成。"
49+
```
50+
51+
即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `excerpt-generator`。
52+
53+
使用案例可以参考：[Halo 默认摘要生成器](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/core/reconciler/PostReconciler.java)

‎docs/developer-guide/plugin/extension-points/server/search-engine.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: 搜索引擎
3+
description: 为 Halo 提供内容搜索引擎的扩展点，可用于替换默认的搜索实现。
4+
---
5+
6+
搜索引擎扩展点用于扩展 Halo 的内容搜索能力，例如：使用 Elasticsearch、Meilisearch 等替代内置的 Lucene 搜索引擎。
7+
8+
```java
9+
public interface SearchEngine extends ExtensionPoint {
10+
11+
boolean available();
12+
13+
void addOrUpdate(Iterable<HaloDocument> haloDocuments);
14+
15+
void deleteDocument(Iterable<String> haloDocIds);
16+
17+
void deleteAll();
18+
19+
SearchResult search(SearchOption option);
20+
}
21+
```
22+
23+
- `available` 方法用于判断搜索引擎是否可用，返回 `true` 表示可用。
24+
- `addOrUpdate` 方法用于添加或更新搜索文档。
25+
- `deleteDocument` 方法用于根据文档 ID 删除搜索文档。
26+
- `deleteAll` 方法用于删除所有搜索文档。
27+
- `search` 方法用于执行搜索，参数 `option` 为搜索选项，返回 `SearchResult` 搜索结果。
28+
29+
`SearchOption` 包含以下常用字段：
30+
31+
- `keyword`：搜索关键词。
32+
- `limit`：返回结果数量限制，默认 10，最大 1000。
33+
- `highlightPreTag` / `highlightPostTag`：高亮标签，默认 `<B>` / `</B>`。
34+
- `filterExposed` / `filterRecycled` / `filterPublished`：是否过滤公开/回收站/已发布内容。
35+
- `includeTypes`：包含的文档类型，例如 `post.content.halo.run`、`singlepage.content.halo.run`。
36+
- `includeOwnerNames`：包含的文档所有者。
37+
- `includeCategoryNames` / `includeTagNames`：包含的分类和标签。
38+
39+
`HaloDocument` 为搜索文档对象，包含以下字段：
40+
41+
- `id`：全局唯一文档 ID。
42+
- `metadataName`：对应扩展的 metadata name。
43+
- `title`：文档标题。
44+
- `description`：文档描述。
45+
- `content`：文档内容（安全内容，无 HTML 标签）。
46+
- `categories` / `tags`：分类和标签的 metadata name 列表。
47+
- `published` / `recycled` / `exposed`：发布、回收站、公开状态。
48+
- `ownerName`：文档所有者。
49+
- `creationTimestamp` / `updateTimestamp`：创建和更新时间。
50+
- `permalink`：文档永久链接。
51+
- `type`：文档类型，例如 `post.content.halo.run`。
52+
53+
`SearchEngine` 对应的 `ExtensionPointDefinition` 如下：
54+
55+
```yaml
56+
apiVersion: plugin.halo.run/v1alpha1
57+
kind: ExtensionPointDefinition
58+
metadata:
59+
name: search-engine
60+
spec:
61+
className: run.halo.app.search.SearchEngine
62+
displayName: "搜索引擎"
63+
type: SINGLETON
64+
description: "扩展内容搜索引擎"
65+
```
66+
67+
即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `search-engine`。
68+
69+
使用案例可以参考：
70+
71+
- [Halo 内置 Lucene 搜索引擎](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/search/lucene/LuceneSearchEngine.java)
72+
- [Meilisearch 搜索插件](https://github.com/halo-sigs/plugin-meilisearch)

‎versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/excerpt-generator.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: 摘要生成器
3+
description: 为文章和页面提供摘要生成逻辑的扩展点，可用于自定义摘要生成方式。
4+
---
5+
6+
摘要生成器扩展点用于自定义 Halo 中文章和页面的摘要生成逻辑，例如：使用算法提取关键内容、接入 AI 生成摘要等。
7+
8+
```java
9+
public interface ExcerptGenerator extends ExtensionPoint {
10+
11+
Mono<String> generate(ExcerptGenerator.Context context);
12+
13+
@Data
14+
@Accessors(chain = true)
15+
class Context {
16+
private String raw;
17+
private String content;
18+
private String rawType;
19+
private Set<String> keywords;
20+
private int maxLength;
21+
}
22+
}
23+
```
24+
25+
- `generate` 方法用于生成摘要，参数 `context` 为摘要生成上下文，返回 `Mono<String>` 即生成的摘要内容。
26+
27+
`Context` 包含以下字段：
28+
29+
- `raw`：原始内容。
30+
- `content`：HTML 格式的内容。
31+
- `rawType`：原始内容类型。
32+
- `keywords`：内容中的关键词，用于辅助生成更准确的摘要。
33+
- `maxLength`：生成摘要的最大长度限制。
34+
35+
Halo 在生成文章或页面摘要时，会查找启用的 `ExcerptGenerator` 扩展（单实例扩展点），如果未找到则使用默认实现。默认实现从 HTML 内容中提取纯文本并截取前 150 个字符。
36+
37+
`ExcerptGenerator` 对应的 `ExtensionPointDefinition` 如下：
38+
39+
```yaml
40+
apiVersion: plugin.halo.run/v1alpha1
41+
kind: ExtensionPointDefinition
42+
metadata:
43+
name: excerpt-generator
44+
spec:
45+
className: run.halo.app.content.ExcerptGenerator
46+
displayName: "摘要生成器"
47+
type: SINGLETON
48+
description: "提供自动生成摘要的方式扩展，如使用算法提取或使用 AI 生成。"
49+
```
50+
51+
即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `excerpt-generator`。
52+
53+
使用案例可以参考：[Halo 默认摘要生成器](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/core/reconciler/PostReconciler.java)

‎versioned_docs/version-2.24/developer-guide/plugin/extension-points/server/search-engine.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: 搜索引擎
3+
description: 为 Halo 提供内容搜索引擎的扩展点，可用于替换默认的搜索实现。
4+
---
5+
6+
搜索引擎扩展点用于扩展 Halo 的内容搜索能力，例如：使用 Elasticsearch、Meilisearch 等替代内置的 Lucene 搜索引擎。
7+
8+
```java
9+
public interface SearchEngine extends ExtensionPoint {
10+
11+
boolean available();
12+
13+
void addOrUpdate(Iterable<HaloDocument> haloDocuments);
14+
15+
void deleteDocument(Iterable<String> haloDocIds);
16+
17+
void deleteAll();
18+
19+
SearchResult search(SearchOption option);
20+
}
21+
```
22+
23+
- `available` 方法用于判断搜索引擎是否可用，返回 `true` 表示可用。
24+
- `addOrUpdate` 方法用于添加或更新搜索文档。
25+
- `deleteDocument` 方法用于根据文档 ID 删除搜索文档。
26+
- `deleteAll` 方法用于删除所有搜索文档。
27+
- `search` 方法用于执行搜索，参数 `option` 为搜索选项，返回 `SearchResult` 搜索结果。
28+
29+
`SearchOption` 包含以下常用字段：
30+
31+
- `keyword`：搜索关键词。
32+
- `limit`：返回结果数量限制，默认 10，最大 1000。
33+
- `highlightPreTag` / `highlightPostTag`：高亮标签，默认 `<B>` / `</B>`。
34+
- `filterExposed` / `filterRecycled` / `filterPublished`：是否过滤公开/回收站/已发布内容。
35+
- `includeTypes`：包含的文档类型，例如 `post.content.halo.run`、`singlepage.content.halo.run`。
36+
- `includeOwnerNames`：包含的文档所有者。
37+
- `includeCategoryNames` / `includeTagNames`：包含的分类和标签。
38+
39+
`HaloDocument` 为搜索文档对象，包含以下字段：
40+
41+
- `id`：全局唯一文档 ID。
42+
- `metadataName`：对应扩展的 metadata name。
43+
- `title`：文档标题。
44+
- `description`：文档描述。
45+
- `content`：文档内容（安全内容，无 HTML 标签）。
46+
- `categories` / `tags`：分类和标签的 metadata name 列表。
47+
- `published` / `recycled` / `exposed`：发布、回收站、公开状态。
48+
- `ownerName`：文档所有者。
49+
- `creationTimestamp` / `updateTimestamp`：创建和更新时间。
50+
- `permalink`：文档永久链接。
51+
- `type`：文档类型，例如 `post.content.halo.run`。
52+
53+
`SearchEngine` 对应的 `ExtensionPointDefinition` 如下：
54+
55+
```yaml
56+
apiVersion: plugin.halo.run/v1alpha1
57+
kind: ExtensionPointDefinition
58+
metadata:
59+
name: search-engine
60+
spec:
61+
className: run.halo.app.search.SearchEngine
62+
displayName: "搜索引擎"
63+
type: SINGLETON
64+
description: "扩展内容搜索引擎"
65+
```
66+
67+
即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `search-engine`。
68+
69+
使用案例可以参考：
70+
71+
- [Halo 内置 Lucene 搜索引擎](https://github.com/halo-dev/halo/blob/main/application/src/main/java/run/halo/app/search/lucene/LuceneSearchEngine.java)
72+
- [Meilisearch 搜索插件](https://github.com/halo-sigs/plugin-meilisearch)

0 commit comments

Comments
 (0)