LLM-WIKI MVP 技术方案
# LLM-WIKI MVP 技术方案
1. 方案目标
本文档集把 MVP 技术选型转化为可执行技术方案。组织方式按“技术产品”划分，而不是按业务产品划分。
每个技术产品文档必须回答：
- 需要支撑哪些 LLM-WIKI 产品和产品特性。
- 如何购买或获取。
- 如何开发。
- 如何部署。
- 如何配置。
- 如何使用。
- 如何验证它确实支撑了蓝图目标。
2. MVP 技术组合
| 技术产品 | MVP 决策 | 覆盖范围 |
|---|---|---|
| GitHub | 固定采用 | 仓库、分支、PR、审批、Actions、Issues、权限、审计 |
| LLM-WIKI 控制面 | 自研 | 来源配置、三方 diff、发布目录治理、PR 自动化、adapter 协议 |
| Docusaurus | MVP 展示后端 | 文档阅读、导航、静态发布、页面内问答挂载点 |
| RAGFlow | MVP 智能体、RAG 与问答编排 | 文档迭代工作流、RAG 索引、问答应用、API 包装、模型调用 |
| 智能体访问层 | MVP Agent Access API/tool adapter | search、ask、get-page、get-context、create-feedback、create-improvement-task |
| Meilisearch | MVP 全文搜索 | 站内搜索、标题/路径/标签/片段检索 |
| 商业 LLM API | MVP 模型服务 | 文档整理、问答生成、摘要、改进建议 |
| 运行部署 | GitHub Actions + 容器/静态托管 | 定时同步、发布、索引更新、服务运行 |
3. 文档目录
- GitHub 技术方案
- LLM-WIKI 控制面技术方案
- Docusaurus 技术方案
- RAGFlow 技术方案
- 智能体访问技术方案
- Meilisearch 技术方案
- 商业 LLM API 技术方案
- 运行部署技术方案
- MVP 技术方案一致性 Review
- SyncEngine 技术协议
- AgentBridge 技术协议
- Answer API 与 Agent Access 技术协议
- Publish / Display Manifest 技术协议
- 自研模块技术特性总结
技术协议是实现推理的最终落点。它把产品特性的落地推演进一步约束为组件间的输入、输出、状态、规则、错误处理和验收用例。
4. MVP 端到端流程
MVP 分为三个相互衔接但不混同的流程：来源同步、文档迭代、发布与索引。
来源同步只负责把上游稳定文档收集到 publish/** 并形成可审查 Sync PR；它不直接触发正式发布，也不默认触发智能体改写。
文档迭代由人工任务、反馈 Issue 或同步后的整理需求触发；RAGFlow 只生成建议或草稿，AgentBridge 负责把结果转成 Git diff 和 Release PR。
发布与索引只读取 main 上已审批内容，更新展示站、RAGFlow approved dataset 和 Meilisearch index。
5. MVP 验收标准
| 能力 | 验收标准 |
|---|---|
| 来源同步 | 能按配置从至少两个 GitHub 项目的固定发布分支同步文档。 |
| 三方 diff | 能识别新增、更新、删除、保留和冲突， 且不会覆盖已整理内容。 |
| PR 治理 | 同步和发布都通过 PR，不允许智能体或脚本直写正式发布内容。 |
| 文档展示 | 已审批的 publish/** 能构建成可阅读文档站。 |
| 文档迭代 | RAGFlow 工作流能读取任务并生成结构化建议，AgentBridge 能把建议转成 Git diff 和 Release PR。 |
| 站内搜索 | 用户能按标题、路径、标签、片段搜索文档。 |
| 问答 | 用户和智能体能通过 API 提问，答案必须包含引用或明确无答案。 |
| 智能体访问 | 智能体能通过受控 API/tool 调用 search、ask、get-context 和 create-feedback。 |
| 反馈闭环 | 无答案、错误答案、页面反馈能生成 GitHub Issue。 |
| 定时执行 | 来源同步、发布检查、索引更新能自动或手动触发。 |
6. 技术协议覆盖矩阵
| 技术协议 | 主要覆盖特性 | 关键验收 |
|---|---|---|
| SyncEngine | 来源同步、三方 diff、同步冲突、Draft PR、项目映射目录 | 不覆盖已整理内容，冲突可审查 |
| AgentBridge | 文档整理、补全、变更说明、Release PR、Git 可审查变更 | RAGFlow 建议能安全转成 Git diff 和 PR |
| Answer API / Agent Access | 页面问答、智能体访问、ContextPack、scope、反馈、无答案、多轮追问 | 答案有引用或无答案，scope 服务端授权 |
| Publish / Display Manifest | 发布影响、页面状态、展示层漂移、索引更新、引用回跳 | Git、站点、索引状态可对账 |
7. 关键决策
7.1 RAGFlow 作为 MVP 智能体/RAG 平台
MVP 选择 RAGFlow。
理由：
- RAGFlow 已经部署，采购和部署成本已经发生，不需要再引入新的智能体平台。
- LLM-WIKI 的核心场景是文档知识库，RAGFlow 的文档理解、RAG、引用和 Agent 能力更贴近该场景。
- MVP 首要目标是打通文档收集、文档迭代、问答、引用和反馈闭环；使用已部署 RAGFlow 可以减少平台验证成本。
- 不再引入其他智能体平台，避免任务、索引、权限和 API 编排分散。
7.2 Docusaurus 作为 MVP 展示后端
理由：
- 与 Git + Markdown 工作方式最贴合。
- 构建产物是静态文件，部署简单。
- 不引入数据库，不影响后续替换 Wiki.js、Mintlify、GitBook 或 ReadMe。
7.3 RAGFlow RAG 索引 + Meilisearch 全文搜索
MVP 不把向量数据库作为独立技术产品单列。
理由：
- RAGFlow 已经承担文档解析、chunk、embedding、检索、重排和问答引用，独立向量数据库会形成第二套向量索引。
- 双向量索引会带来 chunk 粒度、metadata、删除同步和引用回跳不一致。
- Meilisearch 仍然保留，因为它面向人的站内关键词搜索，与 RAGFlow 的问答召回职责不同。
- 向量存储不作为独立产品单列，纳入 RAGFlow 实施方案；当前倾向优先评估 pgvector。
8. 官方资料
- GitHub Pull Requests: https://docs.github.com/en/pull-requests
- GitHub Actions workflow syntax: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
- GitHub Actions billing: https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions
- GitHub Apps authentication: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
- GitHub Issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/about-issues
- Docusaurus deployment: https://docusaurus.io/docs/deployment
- RAGFlow official site: https://www.ragflow.io/
- RAGFlow GitHub: https://github.com/infiniflow/ragflow
- Meilisearch quickstart: https://www.meilisearch.com/docs/learn/getting_started/quick_start