Index Adapter 技术设计
# Index Adapter 技术设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 摘要
Index Adapter 负责把已发布、可索引的 kunora-wiki 文档转换为标准 IndexDocument，并同步到 RAGFlow、Meilisearch 等外部索引目标。RAGFlow 和 Meilisearch 的部署、常规配置和运维属于产品实施；进入 development 的部分是自研 adapter 契约、索引文档结构、幂等 upsert/delete、错误映射和 IndexManifest。
Index Adapter 不生成答案、不修改 Git 内容、不决定页面是否正式发布。它只消费 PageManifest、PublishManifest、DocumentRecord 和 IndexConfig，输出索引目标状态与可审计的 IndexManifest。
2. 模块目标
- 根据
IndexConfig选择 enabled index targets，包括 RAGFlow approved/working datasets 和 Meilisearch index。 - 从已发布页面生成标准
IndexDocument。 - 对 RAGFlow、Meilisearch 执行幂等 upsert/delete。
- 记录每个 target 的 indexed/partial/failed 状态。
- 生成
IndexManifest，供 Answer API、Agent Access API 和 drift check 使用。 - 把外部索引服务错误转换为标准
ErrorObject。
3. 非目标
- 不实现第二套 RAG 问答。
- 不把 RAGFlow 或 Meilisearch 的内部 ID 作为 LLM-WIKI 主 ID。
- 不修改
publish/**或state/page-manifest.json。 - 不决定页面质量状态，只消费
qaVisible和includeQualityStatus。 - 不直接创建 PR 或 check；失败状态交给 ReviewBridge。
- 不管理外部索引服务部署、容量、备份和权限产品化配置。
4. 上下文边界
Index Adapter 位于 L2 Publish/Index 层。它可以依赖 ConfigManager、WorkspaceStore、RagflowClient、SearchIndexClient，但不能依赖 Answer API 或 AgentBridge。
5. 输入与输出
5.1 输入
| 输入 | 来源 | 说明 |
|---|---|---|
IndexConfig | ConfigManager | 索引目标、启用状态、可索引质量状态。 |
RagflowConfig | ConfigManager | RAGFlow dataset 和连接引用。 |
PageManifest | WorkspaceStore / Display Adapter | 页面 URL、qaVisible、qualityStatus。 |
PublishManifest | DisplayBackend Adapter | 本次发布页面和 publishRunId。 |
DocumentRecord[] | WorkspaceStore | 文档内容、hash、source metadata。 |
previous IndexManifest | WorkspaceStore/state | delete/drift 对账。 |
5.2 输出
| 输出 | 消费者 | 说明 |
|---|---|---|
IndexDocument[] | RagflowClient、SearchIndexClient | 标准索引输入。 |
IndexManifest | Answer API、Agent Access API、ReviewBridge | 索引目标状态。 |
| target operation report | workflow、ReviewBridge | upsert/delete 成功失败明细。 |
SearchResult[] | Answer API、Agent Access API | 可选搜索查询契约。 |
ErrorObject[] | ReviewBridge、workflow | target 不可用、部分失败、schema 错误。 |
6. 依赖的 common 契约
| 契约 | 用途 |
|---|---|
IndexConfig | target 选择和过滤规则。 |
RagflowConfig | RAGFlow target 连接和 dataset。 |
PageManifest | qaVisible、URL、qualityStatus。 |
PublishManifest | 本次发布事实。 |
DocumentRecord | 文档内容和 hash。 |
IndexDocument | 外部索引 upsert 标准输入。 |
IndexManifest | 索引状态持久化。 |
SearchResult | 查询结果标准化。 |
RagflowClient / SearchIndexClient | 外部目标 adapter。 |
ErrorObject | 错误与降级输出。 |
7. 索引选择规则
文档进入索引必须同时满足：
- 页面存在于当前
PageManifest。 - 页面在当前
PublishManifest中属于已发布或可见状态。 qaVisible=true。qualityStatus属于 target 的includeQualityStatus。publishPath和siteUrl合法。- 文档内容可读取且
contentHash与 manifest 一致。
不满足条件的文档不得 upsert；如果上一版索引中存在，需要根据 delete 策略生成 delete 操作。
7.1 RAGFlow Dataset 分层
MVP 固定使用两个 RAGFlow dataset 语义：
| Dataset | 用途 | 内容来源 | 消费者 |
|---|---|---|---|
llm-wiki-approved | 正式问答事实链 | 已审批、已发布或可发布、qaVisible=true 的正式文档 | Answer API、Agent Access API 的正式 ask。 |
llm-wiki-working | 智能体迭代上下文 | 允许迭代的工作区文档、待整理内容或冲突处理上下文 | AgentBridge、受控 Agent Access 工具。 |
规则：
- 正式问答默认只能访问
llm-wiki-approved。 - AgentBridge 可以通过授权 scope 使用
llm-wiki-working，但输出仍必须回到 Release PR。 - 两个 dataset 必须分别记录 target status，不能用 working dataset 结果替代 approved dataset。
llm-wiki-working失败只阻断对应迭代任务，不影响正式问答。
8. 核心流程
8.1 构建索引计划
8.2 执行索引计划
流程要求：
- 各 target 独立执行，单个 target 失败不回滚其他 target。
- 同一 target 内部分失败必须记录到
IndexManifest。 - Git 内容和 publish manifest 不因索引失败而回滚。
- target 不可用时 Answer API 应能根据
IndexManifest降级。
9. IndexDocument 生成规则
| 字段 | 规则 |
|---|---|
documentId | 来自 DocumentRecord.documentId。 |
path | 来自 publishPath。 |
url | 来自 PageManifestEntry.url。 |
title | frontmatter title 优先，其次 H1。 |
content | 规范化 Markdown 正文，可移除 frontmatter。 |
contentHash | 来自 DocumentRecord.contentHash。 |
sourceId | 来自 DocumentRecord.sourceId。 |
qualityStatus | 来自 PageManifest 或 DocumentRecord。 |
metadata | 只包含标准字段，不包含外部私有结构。 |
MVP 不要求稳定自研 chunkId；如果外部目标返回 chunk id，只能作为 externalChunkId 或 target metadata，不能作为主键。
10. Upsert/Delete 幂等规则
| 操作 | 幂等键 | 行为 |
|---|---|---|
| upsert | targetId + documentId + contentHash | 相同内容重复 upsert 为 safe no-op。 |
| delete | targetId + documentId | 已删除再次 delete 为 safe no-op。 |
| rebuild target | targetId + publishRunId | 可重复执行，最终 manifest 一致。 |
| partial retry | targetId + failed document ids | 只重试失败文档。 |
Delete 触发条件：
- 当前 publish/page manifest 不再包含该 documentId 。
qaVisible从 true 变为 false。qualityStatus不再满足 target include 列表。- 文档路径非法或内容不可读，且上一版 manifest 标记已索引。
11. IndexManifest 状态规则
| target 结果 | target status | 说明 |
|---|---|---|
| 全部 upsert/delete 成功 | passed | target 与 publishRunId 对齐。 |
| 部分文档失败 | partial | 可降级使用成功文档，但需 ReviewBridge 警告。 |
| target 完全不可用 | failed | Answer API 不应使用该 target 的新状态。 |
| target disabled | skipped | 配置关闭，不视为错误。 |
| manifest 与 publish 不一致 | 保持原 target status，另记录 index.drift_detected | drift 是对账错误/check 语义，不是 IndexTargetStatus.status 枚举值。 |
IndexManifest 必须包含 publishRunId、gitCommit、target 状态、成功/失败计数、错误列表和可追溯 document ids。
12. SearchResult 标准化
当 Index Adapter 暴露搜索能力给 Answer API 或 Agent Access API 时，必须把外部结果转换为 SearchResult：
- RAGFlow/Meilisearch score 归一化为可比较但不承诺跨 target 等价。
- 结果必须包含
documentId或可映射回documentId的 path/hash。 - citation 回跳优先使用
PageManifest.url。 - 外部 chunk id 不作为主引用。
- 未授权或不可见页面不得返回。
13. 状态与持久化
| 数据 | 位置 | owner |
|---|---|---|
IndexDocument | in-memory / target payload | Index Adapter |
IndexManifest | state/index-manifest.json | Index Adapter |
| target operation report | workflow summary / ReviewBridge input | Index Adapter |
| external target state | RAGFlow / Meilisearch | 外部产品，经 adapter 管理 |
Index Adapter 不写 publish/** 和 state/page-manifest.json。
14. 错误处理
| 错误码 | retryable | 场景 | 处理 |
|---|---|---|---|
index.config_invalid | false | IndexConfig/RagflowConfig 非法 | 阻断索引。 |
index.manifest_invalid | false | Page/Publish manifest 不可用 | 阻断索引。 |
index.document_unreadable | true | 文档读取失败 | 标记该文档失败。 |
index.target_unavailable | true | RAGFlow/Meilisearch 不可用 | target failed，可重试。 |
index.upsert_failed | true | 单文档 upsert 失败 | target partial。 |
index.delete_failed | true | 单文档 delete 失败 | target partial。 |
index.drift_detected | false | target 与 manifest 不一致 | drift check failed。 |
adapter.ragflow_unavailable | true | RAGFlow adapter 调用失败 | 映射为 target failure。 |
错误必须包含 targetId、documentId/path、publishRunId；不得包含 token 或完整外部私有响应。
15. 降级策略
- 索引失败不回滚 Git 内容和展示发布。
- Answer API 可使用上一版成功 index manifest，但必须标明索引滞后或不可用。
- 单 target 失败不影响其他 target。
- RAGFlow 不可用时不能伪造 RAG 答案。
- Meilisearch 部分失败时搜索结果必须排除失败文档或标记索引滞后。
16. 测试要求
| 测试 | Fixture | 预期 |
|---|---|---|
| index partial | fixtures/common/manifest/index-manifest.partial.json | target status 标记 partial。 |
| upsert/delete idempotent | fixtures/common/index/upsert-delete-idempotent.json | 重复执行无重复副作用。 |
| search citation | fixtures/common/index/search-result-citation.json | SearchResult 可映射到 citation。 |
| qa invisible | future index visibility fixture | 不 upsert，不返回搜索结果。 |
| target unavailable | future index target failure fixture | target failed，Git 内容不回滚。 |
| valid manifest | fixtures/common/manifest/publish-manifest.valid.json | 可生成 IndexDocument。 |
模块验收标准：
- IndexDocument schema 有 contract test。
- upsert/delete 幂等有 golden 或 contract test。
- 部分失败不覆盖成功 target 状态。
- 外部 adapter mock 不泄漏私有响应结构。
- SearchResult 不返回未授权或不可见页面。
17. 设计决策
| 决策 | 说明 | 取舍 |
|---|---|---|
| Index Adapter 不生成答案 | 索引和问答职责分离。 | Answer API 需要再组装 context 和答案。 |
| 单 target 失败不回滚其他 target | 提高发布链路韧性。 | 需要 manifest 明确 partial/failed。 |
| documentId 不使用外部 ID | 保持跨 target 可对账。 | 需要维护外部 ID 映射。 |
| qaVisible 作为索引硬门槛 | 防止草稿或低质量内容进入问答。 | 需要上游稳定质量状态。 |
18. 待确认问题
- Meilisearch 是否作为正式搜索目标进入 MVP，还是只保留 adapter 契约。
IndexManifest是否记录每个 document 的外部 target id 映射。- Answer API 使用上一版成功索引时，滞后提 示的标准字段放在哪个契约中。