Meilisearch 实施方案

# Meilisearch 实施方案

修订记录

版本	日期	修订说明
v0.1	2026-05-01	建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。

1. 文档目标

本文定义 kunora-docs 中 Meilisearch 搜索索引的实施方案。Meilisearch 是非自研搜索产品，只负责全文搜索召回；它不是答案事实链，也不是正式内容事实源。

2. 核心契约

main/publish/** + PageManifest + PublishManifest
  -> Index Adapter
  -> Meilisearch index
  -> SearchResult

规则：

• Meilisearch 只索引 indexable=true 且符合质量策略的页面。
• SearchResult 必须映射回 documentId、path 和 url。
• Meilisearch 失败不回滚 Git 内容和 Docusaurus 发布。
• Meilisearch 结果不能绕过 Answer API / Agent Access API 的 scope 权限。

3. 配置契约

config/index.yaml 中 Meilisearch target 必须包含：

字段	要求
id	推荐 meilisearch。
type	必须为 meilisearch。
enabled	默认 true。
indexName	目标 index 名。
includeQualityStatus	可索引质量状态。

Secrets / Variables：

名称	用途
MEILI_MASTER_KEY	Meilisearch 写入。
MEILI_INDEX_NAME	默认 index 名。
MEILI_HOST	Meilisearch endpoint 引用，不能写入 manifest。

4. 索引文档契约

Meilisearch 文档由 IndexDocument 转换，不暴露外部私有字段。

字段	来源
documentId	LLM-WIKI 主 ID。
path	publish/** 路径。
url	PageManifest。
title	frontmatter 或 H1。
content	规范化正文。
contentHash	DocumentRecord。
qualityStatus	PageManifest。
sourceId	DocumentRecord。

5. Workflow 落地

Meilisearch 同步归入 docs-index.yml。

步骤	产物
validate target config	config check。
build search documents	IndexDocument[]。
upsert changed docs	operation report。
delete removed/invisible docs	operation report。
write target status	state/index-manifest.json 中 meilisearch target。

6. 失败处理

场景	处理
index disabled	target skipped。
target unavailable	target failed，搜索降级为不可用或上一版结果。
部分文档失败	target partial，失败文档不得返回。
delete 失败	target partial，ReviewBridge 产生警告或阻断项。
result 无法映射 documentId	丢弃结果并记录 index.result_unmapped。

7. 完成定义

1. config/index.yaml 定义 Meilisearch target。
2. docs-index.yml 能执行 upsert/delete。
3. state/index-manifest.json 记录 meilisearch target 状态。
4. SearchResult 能映射到 citation/page URL。
5. 未授权、不可见或失败文档不会被搜索返回。
6. Meilisearch key 不出现在日志、manifest、PR body 或 Issue。