跳到主要内容

自研模块技术特性总结

1. 文档目标​

本文把 LLM-WIKI MVP 中必须自研的模块拆成可开发的技术 features。

每个 feature 回答三个问题：

  • What：要实现什么能力。
  • Why：为什么这个能力必须存在。
  • How to Implement：工程上如何实现。

本文不重复非自研系统实施方案。GitHub、Docusaurus、RAGFlow、Meilisearch、商业 LLM API 等外部系统只作为依赖出现。

2. 自研模块总览​

模块类型MVP 形态核心职责
ConfigManagerCLI/library必须实现配置读取、schema 校验、配置影响分析
SyncEngineCLI/library必须实现来源同步、三方 diff、冲突报告
WorkspaceStorelibrary必须实现publish/** 和 state/manifest 管理
ReviewBridgeCLI/library必须实现Sync PR / Release PR 创建和更新
AgentBridgeCLI/workflow必须实现RAGFlow 输出到 Git diff / Release PR
DisplayBackend AdapterCLI adapter必须实现 Docusaurus adapter发布目录到展示后端
Index AdapterCLI adapter必须实现 RAGFlow + Meilisearch adapter已审批文档索引同步
Answer APIHTTP service/serverlessMVP 可轻量实现面向人的问答封装
Agent Access APIHTTP service/serverlessMVP 可轻量实现面向智能体的工具入口

3. ConfigManager​

3.1 配置加载与合并​

WhatWhyHow to Implement
加载 config/*.yaml 并形成统一运行配置。所有同步、发布、索引、问答行为都必须由 Git 可审查配置驱动。定义 ConfigBundle，读取 sources.yaml、publish.yaml、ragflow.yaml、agent-access.yaml、index.yaml、model-policy.yaml，禁止运行时隐式配置。

3.2 schema 校验​

WhatWhyHow to Implement
校验字段类型、必填项、枚举值和路径约束。错误配置会导致文档错发、覆盖或权限泄露。使用 JSON Schema、Pydantic 或等价校验器；CI 和 workflow 运行前必须执行。

3.3 publishPath 唯一性校验​

WhatWhyHow to Implement
确保多个 source 的 publishPath 唯一且不能互为父子目录。防止两个来源互相覆盖、删除或污染三方 diff 基线。对所有 publishPath 做规范化路径比较；发现相同、父子目录或越界路径时失败退出。

3.4 配置影响报告​

WhatWhyHow to Implement
配置变更时生成 config-impact-report。ref/sourcePath/publishPath/include/exclude 变化会影响 source lock 和同步结果，不能当作普通内容变更。比较 PR base/head 的配置差异，输出受影响 source、旧配置、新配置、预估新增/删除/迁移路径，并写入 PR summary。

4. SyncEngine​

4.1 来源读取​

WhatWhyHow to Implement
按 source 配置读取 GitHub 来源仓库固定 ref 下的 sourcePath。LLM-WIKI 只消费稳定发布分支或固定发布 tag，不读取 main 半成品。使用 git clone/fetch 或 GitHub API；只读取 include 命中的文件，应用 exclude。

4.2 三方 diff​

WhatWhyHow to Implement
基于 A 上次来源基线、B 当前来源、C 当前 publish 判断 add/update/delete/keep/conflict。自动同步不能覆盖人工或智能体整理后的文档。实现 SyncChange 决策表；hash 使用规范化内容，不使用文件时间。

4.3 source-lock 管理​

WhatWhyHow to Implement
只在成功 apply 后更新 source-lock.json。冲突时推进 lock 会丢失 A/B/C 对比，导致后续误判。add/update/delete 更新 lock；conflict/delete_conflict 保留旧 A，并在 source-changes.json 记录 B hash。

4.4 冲突报告​

WhatWhyHow to Implement
输出结构化冲突报告并注入 Sync PR。维护者必须看到哪些文件不能自动同步，以及为什么。生成 state/source-changes.json，包含 conflictType、baseHash、sourceHash、publishHash、建议处理方式。

4.5 rename/move 策略​

WhatWhyHow to Implement
MVP 将来源路径变化按 delete + add 处理。不做智能 rename 检测可以降低复杂度，但必须暴露 URL 影响。旧路径按删除策略处理，新路径按新增处理；发布影响报告展示旧 URL 删除和新 URL 新增。

5. WorkspaceStore​

5.1 publish/** 目录访问​

WhatWhyHow to Implement
提供对受管发布目录的规范化读写接口。所有模块都应通过同一套路径、hash、frontmatter 规则处理文档。实现路径规范化、越界检查、内容读取、写入、删除、hash 计算。

5.2 state 文件管理​

WhatWhyHow to Implement
管理 source lock、page manifest、publish manifest、index manifest、site manifest。状态文件是审计、对账、回滚和故障排查的基础。定义 JSON schema；写入时使用原子写；manifest 必须可重建，不能成为内容事实源。

5.3 页面元数据生成​

WhatWhyHow to Implement
从路径、frontmatter、source lock、Git 历史生成 DocumentRecord。搜索、问答、页面状态和发布影响都依赖统一页面元数据。提取 sourceProject、sourceRef、contentHash、qualityStatus、qaVisible、indexable、relatedIssues。

5.4 内容规范化​

WhatWhyHow to Implement
统一 Markdown hash 和路径规则。不同换行、frontmatter 顺序或路径分隔符会导致错误 diff。统一 UTF-8、LF、路径 /、可选 frontmatter 规范化，再计算 hash。

6. ReviewBridge​

6.1 Sync PR 创建和更新​

WhatWhyHow to Implement
将同步结果推送到 docs-sync/source-updates 并创建 Draft PR。同步只是材料收集，不等于发布。使用 GitHub CLI/API；PR body 包含 source changes、冲突数量、配置影响、影响路径。

6.2 Release PR 创建和更新​

WhatWhyHow to Implement
为 AgentBridge 或人工整理结果创建 docs-release/* PR。正式内容变更必须人工审批。创建分支、提交变更、生成 PR body，关联 Issue 和发布影响报告。

6.3 PR body 注入​

WhatWhyHow to Implement
把变更来源、影响页面、风险、引用、AgentBridge report 写入 PR。审批者不能只看文件 diff，需要理解用户侧影响和智能体依据。使用固定 PR 模板和机器生成区块，重复更新时保留人工评论。

6.4 GitHub 状态检查​

WhatWhyHow to Implement
将 validate、build、impact、index dry-run 等结果转为 checks。分支保护需要机器可判定的通过/失败状态。GitHub Actions 输出 summary，必要时通过 Checks API 写状态。

7. AgentBridge​

7.1 IterationTask 生成​

WhatWhyHow to Implement
从 Issue、人工命令或质量事件生成文档迭代任务。RAGFlow 需要清晰目标、scope、约束和基线，不能自由改文档。生成 IterationTask，包含 goal、scope、allowedActions、requireCitations、base files hash。

7.2 RAGFlow 输出校验​

WhatWhyHow to Implement
校验 RAGFlow 输出的路径、action、baseHash、evidence、draftContent/patch。防止越权修改、无依据补全和并发覆盖。按 AgentBridge 协议验证；不合格 change 拒绝写入并记录 report。

7.3 patch / whole-file 应用​

WhatWhyHow to Implement
支持局部 patch 和整文件改写两种模式。长文档整文件改写风险高，局部 patch 更可审查。MVP 可先 whole-file，但保留 patch 字段；patch 失败不能 fallback 为整文件覆盖。

7.4 并发保护​

WhatWhyHow to Implement
写入前校验当前文件 hash 与 baseHash 一致。避免把基于旧内容生成的草稿覆盖到新文件上。hash 不匹配时拒绝写入，记录 concurrent_change，生成 Issue 或 report。

7.5 PR 产物生成​

WhatWhyHow to Implement
将通过校验的变更写入分支并交给 ReviewBridge 创建 PR。RAGFlow 不直接参与 Git 治理。写 docs-release/* 分支，生成 AgentBridge report、影响报告、PR body。

8. DisplayBackend Adapter​

8.1 Docusaurus 输入生成​

WhatWhyHow to Implement
从 publish/** 生成 Docusaurus docs 目录。Docusaurus 不应成为内容事实源。构建时复制或映射 Markdown，注入 frontmatter 和页面 metadata。

8.2 sidebar 生成​

WhatWhyHow to Implement
生成可浏览的 Docusaurus sidebar。用户需要按项目、目录、主题定位文档。根据 publishPath、page manifest、frontmatter topic 生成 sidebars.ts。

8.3 页面组件挂载​

WhatWhyHow to Implement
挂载问答、反馈、质量状态、编辑入口组件。阅读、问答、反馈和编辑是人的主要入口。生成页面 metadata，前端组件读取 path、qualityStatus、EditContext、Answer API endpoint。

8.4 site manifest 生成​

WhatWhyHow to Implement
构建后生成 site-manifest.json。发布后需要检测展示层漂移和缺页。记录 URL、sourceHash、renderedHash、httpStatus、expectedStatus、redirectTarget、cacheValidUntil。

9. Index Adapter​

9.1 RAGFlow dataset 同步​

WhatWhyHow to Implement
将已审批文档同步到 llm-wiki-approved，将工作区文档同步到 llm-wiki-working。正式问答不能使用未审批内容，迭代任务又需要工作区上下文。调用 RagflowAdapter upsert/delete，按 manifest 控制 qaVisible、indexable、dataset。

9.2 Meilisearch index 同步​

WhatWhyHow to Implement
将页面标题、路径、内容、标签、主题、质量状态写入 Meilisearch。支撑人和智能体的关键词搜索、过滤和分组。使用稳定 documentId；配置 searchable/filterable/sortable/facet attributes。

9.3 删除同步​

WhatWhyHow to Implement
对删除页面执行 RAGFlow 和 Meilisearch delete。已删除文档不能继续被问答或搜索召回。根据 publish manifest diff 生成 delete 列表；删除不存在时幂等视为成功。

9.4 index manifest​

WhatWhyHow to Implement
记录每次索引运行状态、target、attempt、error。索引失败不能污染内容事实，但必须可排障。写 state/index-manifest.json，包含 publishRunId、gitCommit、target status、startedAt、finishedAt。

10. Answer API​

10.1 单轮问答​

WhatWhyHow to Implement
提供 POST /answer/ask，返回结构化答案。人在页面中需要自然语言提问，并获得可追溯答案。调用 RAGFlow QA，标准化为 answer、summary、citations、confidence、noAnswerReason、actions。

10.2 引用标准化​

WhatWhyHow to Implement
将 RAGFlow 引用转换为页面 path、URL、anchor、chunkId。用户和智能体需要回到原文验证依据。使用 page manifest 和 RAGFlow chunk metadata 补齐 URL、sourceProject、version。

10.3 无答案处理​

WhatWhyHow to Implement
证据不足时返回 noAnswerReason 和反馈 action。无答案是知识缺口，不能编造答案。confidence=low，生成 dedupeKey，提供 create_feedback/create_improvement_task。

10.4 多轮会话​

WhatWhyHow to Implement
支持 sessionId + sessionToken 的多轮追问。用户真实问题通常需要连续澄清，同时不能扩大 scope。创建 AnswerSession，绑定 owner、scope、expiresAt；每轮校验 session token、owner 和 scope。

10.5 人类调用者授权​

WhatWhyHow to Implement
支持 public-read 和 authenticated-read 两种模式。文档站可能公开，也可能要求登录。根据站点模式决定匿名或登录态；默认只允许访问 approved dataset。

11. Agent Access API​

11.1 工具入口​

WhatWhyHow to Implement
提供 search、ask、get_page、get_context、create_feedback、create_improvement_task。智能体需要稳定工具，而不是模拟网页。每个工具使用统一请求结构和审计字段，底层调用 RAGFlow、Meilisearch、GitHub 或 WorkspaceStore。

11.2 服务端 policy 授权​

WhatWhyHow to Implement
token 映射 agent identity、allowedTools、allowedPaths、allowedDatasets、writePermissions。智能体声明的 scope 不能作为授权事实。加载 config/agent-access.yaml 或运行配置；请求 scope 必须是授权 scope 子集。

11.3 ContextPack 生成​

WhatWhyHow to Implement
按任务目标、scope、limits 返回结构化上下文包。智能体执行任务需要一组可引用、可裁剪、可追踪上下文。聚合 Meilisearch 搜索结果、RAGFlow 片段、page manifest 和质量状态。

11.4 反馈与改进任务幂等​

WhatWhyHow to Implement
create_feedback/create_improvement_task 使用 dedupeKey 和 idempotencyKey。防止用户或智能体重复提交导致 GitHub Issue 爆炸。基于 eventType、normalizedQuestion、normalizedScope、citationPaths 生成 dedupeKey；已有开放 Issue 时追加评论或计数。

11.5 调用审计​

WhatWhyHow to Implement
记录 requestId、caller、scope、tool、结果和错误。智能体访问必须可追踪，便于排障和权限审计。每次调用写结构化日志；敏感内容脱敏；错误码按协议返回。

12. 模块依赖关系​

13. MVP 开发顺序建议​

顺序模块原因
1ConfigManager没有配置校验，后续模块输入不稳定
2WorkspaceStore所有模块依赖路径、hash、manifest 规则
3SyncEngine先打通来源收集和三方 diff 主链路
4ReviewBridgeSync PR 和 Release PR 是治理闭环
5DisplayBackend Adapter已审批文档需要可读站点
6Index Adapter搜索和问答依赖索引
7Answer API面向人的问答入口
8Agent Access API面向智能体的工具入口
9AgentBridge文档迭代智能体进入 PR 闭环

AgentBridge 可以和 Answer/Agent Access 并行推进，但不能早于 WorkspaceStore、ReviewBridge 和协议实现。

编辑此页
◇对此页面有疑问？

问答功能将在后续接入 Answer API。当前可通过页面底部的反馈链接提交问题。

页面来源草稿
来源项目kunora-wiki
分支docs-publish
路径technology/components/kunora-wiki/product/07-mvp-technical-solution/14-self-developed-module-features.md