LLM-WIKI 技术选型方案
# LLM-WIKI 技术选型方案
1. 结论
LLM-WIKI 的技术选型应采用“GitHub 固定、业务控制面自研、外围能力优先采购或选用成熟开源”的策略。
推荐默认走“成本体验平衡”方案：
- GitHub 继续作为唯一确定的治理底座，承载仓库、分支、PR、审批、Actions 定时任务和审计记录。
- LLM-WIKI 自研最小控制面，只覆盖文档源配置、三方 diff、发布目录治理、冲突报告、PR 自动化和后端适配器。
- 文档展示优先使用可替换的展示后端，MVP 推荐 Docusaurus；如果更看重编辑体验和 AI-native docs，可以评估 Mintlify、GitBook、ReadMe 等商业服务。
- 智能体迭代与问答不从零自研，MVP 复用已部署 RAGFlow；其他 Agent/RAG 框架只作为后续替代或增强候选。
- 知识索引拆成两类：RAG 索引由 RAGFlow 负责，向量存储作为 RAGFlow 实施细节优先评估 pgvector；站内全文搜索独立采用 Meilisearch。
不能直接采购或复用的部分，才进入自研范围。当前必须自研的是 LLM-WIKI 的“文档治理控制面”，不是文档站、RAG 平台、模型服务或向量数据库本身。
2. 选型原则
2.1 固定前提
- GitHub 是唯一确定选型。
- 其他产品均不在蓝图层固定，包括 Wiki.js、RAGFlow、Docusaurus、Mintlify、向量数据库和模型供应商。
- GitHub 项目文档源必须通过固定发布分支或固定 tag 前缀进入 LLM-WIKI。
- 发布目录
publish/**是智能体、人、发布系统共同工作的受管目录，不能被简单的上游同步覆盖。 - 正式发布必须经过 PR 审批。
2.2 选型优先级
- 能用成熟商业服务解决，并且体验收益大于成本和锁定风险时，优先商业服务。
- 能用成熟开源自建解决，并且运维成本可控时，优先开源自建。
- 只有当商业服务和开源方案都不能表达 LLM-WIKI 的核心业务约束时，才自研。
2.3 三类方案定义
| 方案 | 目标 | 适用场景 |
|---|---|---|
| 成本体验平衡 | 在较低定制成本下获得可用体验和可演进架构 | MVP、早期产品化、内部试点 |
| 最佳体验 | 优先降低用户摩擦、提升协作和问答体验 | 面向外部用户、商业化文档门户、团队规模扩大 |
| 最佳成本 | 最大化利用开源和已有基础设施 | 预算敏感、内部使用、可接受较多运维工作 |
3. 总体技术架构
技术架构的关键点不是某一个展示系统，而是每个外围能力都必须通过 LLM-WIKI 控制面接入：
SourceAdapter：读取上游 GitHub 项目文档。SyncEngine：执行三方 diff，生成新增、更新、删除和冲突结果。WorkspaceStore：维护publish/**、source lock、sync report、publish manifest。AgentBridge：把文档迭代任务交给智能体平台，并把结果转回 Git diff。ReviewBridge：创建 PR、检查状态、收集审批结果。DisplayBackend：把已审批文档发布到实际文档展示产品。KnowledgeIndex：把已审批文档切分、索引并提供检索。AnswerService：对人和智能体提供问答 API。AgentAccessService：给外部智能体提供受控的 search、ask、get-page、get-context、create-feedback 和 create-improvement-task 工具接口。
4. 分产品技术选型
4.1 GitHub 文档源
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub 仓库 + docs-publish 分支 | 已确定使用 GitHub，固定发布分支比 main 更稳定，适合自动同步。 |
| 最佳体验 | GitHub Enterprise/组织级规则 + CODEOWNERS + 受保护分支 | 适合多人协作、权限隔离和强制审批。 |
| 最佳成本 | GitHub 免费/低成本计划 + 约定分支 | 足够支撑早期项目文档源治理。 |
约束：每个来源项目必须显式声明 repo、ref、sourcePath、publishPath，不能隐式扫描所有仓库。
4.2 LLM-WIKI 控制仓库
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub 单仓库 + YAML 配置 + JSON 状态文件 | 配置、状态、发布目录和 PR 记录都可审计。 |
| 最佳体验 | GitHub 仓库 + 管理 UI + GitHub App | 降低配置门槛，权限更细，适合团队化运营。 |
| 最佳成本 | 纯 Git 文件约定 | 不引入数据库和后台服务。 |
自研范围：配置 schema、状态文件格式、目录约束、检查脚本。商业和开源产品通常不能直接表达这些 LLM-WIKI 专属约束。
4.3 文档收集器
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | 自研 Python/CLI 收集器 + GitHub Actions | 实现成本低，能精确控制三方 diff 和发布目录映射。 |
| 最佳体验 | 自研收集器 + GitHub App + Web 管理台 | 更好的权限、触发、可视化冲突处理。 |
| 最佳成本 | 自研脚本 + 定时 Actions | 只消耗 Actions 分钟数和少量维护成本。 |
必须自研。原因是现成同步工具通常只能做源到目标的镜像，无法满足：
- 来源目录到发布目录的显式映射。
- 上游新增、更新、删除三类变更识别。
- 上游变更与智能体/人工编辑并存时的三方 diff。
- 冲突不覆盖，必须生成 PR 可审查结果。
4.4 发布工作目录
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | Git 管理的 publish/** | 与 PR 审批天然一致，是智能体、人和发布系统的共同事实源。 |
| 最佳体验 | publish/** + 可视化状态页 | 让编辑者看到页面状态、来源、冲突和发布结果。 |
| 最佳成本 | 仅使用目录约定和 Markdown frontmatter | 无额外系统成本。 |
发布目录不是缓存目录，不能被上游同步无条件覆盖。它是受管文档工作区。
4.5 文档迭代智能体
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | RAGFlow + 商业 LLM API | RAGFlow 已部署，能支撑文档理解、RAG、问答和 Agent 编排，减少平台引入成本。 |
| 最佳体验 | 商业托管智能体平台 + 高质量商业模型 + 人工审核闭环 | 交互、观测、稳定性和模型质量最好。 |
| 最佳成本 | 复用自建 RAGFlow + pgvector/现有向量存储 + 低成本模型 | 现金成本低，但需要承担模型质量、部署和调优成本。 |
不建议从零自研完整智能体平台。LLM-WIKI 只需要自研 AgentBridge：定义任务输入、输出 diff、解释说明、失败回滚和 PR 创建协议。
4.6 审批与治理台
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub Pull Requests + branch protection + Actions checks | PR 天然支持审查、讨论、状态检查和合并记录。 |
| 最佳体验 | GitHub PR + LLM-WIKI 治理面板 | 治理面板汇总来源、智能体改动、影响页面、发布状态。 |
| 最佳成本 | GitHub PR | 无需单独建设审批产品。 |
MVP 不自研审批系统。若后续建设治理台，也应作为 GitHub PR 的视图层，而不是替代 PR。
4.7 文档展示产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | Docusaurus | 开源、静态站点、Markdown 友好、部署成本低，适合从 publish/** 构建。 |
| 最佳体验 | Mintlify / GitBook / ReadMe 等商业文档平台 | 提供 Web 编辑、搜索、AI 助手、预览、分析、权限等完整体验。 |
| 最佳成本 | Docusaurus 或 Wiki.js 自建 | Docusaurus 部署简单；Wiki.js 自带编辑和权限，但需要服务端和数据库运维。 |
结论：不要在技术方案中把 Wiki.js 固化为唯一后端。应抽象 DisplayBackend，MVP 可先实现 Docusaurus 或 Wiki.js 适配，后续替换为商业服务时不影响收集、迭代和审批流程。
4.8 文档编辑产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub Web 编辑 / 本地编辑 + PR | 保持 Git 治理一致，MVP 成本最低。 |
| 最佳体验 | 商业文档平台 Web 编辑器，或自研轻量编辑 UI + GitHub PR | 非工程用户体验更好，能在页面上下文中编辑。 |
| 最佳成本 | GitHub Web 编辑器 | 无需额外系统。 |
如果自研编辑 UI，边界应很窄：只负责页面编辑、预览、提交 PR，不直接绕过 Git 修改生产内容。
4.9 知识索引产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | RAGFlow RAG 索引 + Meilisearch | RAGFlow 负责文档 chunk、embedding、检索和引用；Meilisearch 负责人用全文搜索。 |
| 最佳体验 | Pinecone / Algolia 等托管搜索与向量服务 | 降低运维，提供更强可用性、扩展和搜索体验。 |
| 最佳成本 | RAGFlow 内部向量存储优先 pgvector + 自建 Meilisearch | 复用 PostgreSQL 运维体系，减少独立向量数据库成本。 |
搜索应支持两类能力：
- 面向人的站内搜索：标题、路径、标签、关键词、片段。
- 面向问答的检索：由 RAGFlow 管理 chunk、embedding、引用、版本、页面锚点；LLM-WIKI 只同步元数据和访问策略。
4.10 问答产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | RAGFlow 问答应用 + OpenAI/Anthropic/Gemini 等商业模型 | 已有 RAGFlow 可复用，模型质量和引用体验相对稳定。 |
| 最佳体验 | 托管 RAG/Agent 平台 + 高质量模型 + 托管搜索/向量库 | 最少运维，最佳响应质量、观测和用户体验。 |
| 最佳成本 | 自建 RAGFlow + 本地/低成本模型 | 可控成本低，但需要接受质量和维护成本。 |
问答产品必须对外提供两类接口：
- 人使用的页面内问答、搜索到问答切换、多轮追问和引用回跳。
- 智能体使用的 API，包括检索、答案、引用、无答案原因和改进任务创建入口。
4.11 智能体访问产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | LLM-WIKI 自研薄 API/tool adapter + RAGFlow + Meilisearch + GitHub Issues | 智能体访问需要稳定 schema、scope、引用、权限和任务闭环，通用文档站无法直接提供。 |
| 最佳体验 | Agent Gateway / MCP server + 企业身份 + 观测审计 | 更适合多个智能体团队共享知识工具。 |
| 最佳成本 | HTTP API + GitHub token + RAGFlow API | 不引入独立网关，先满足 MVP 工具调用。 |
智能体访问产品不是第二套 RAG 或第二套文档系统。它是受控访问面：
- search：调用 Meilisearch 或 RAGFlow 检索。
- ask：调用 RAGFlow 问答。
- get-page：读取已授权文档页面。
- get-context：生成任务上下文包。
- create-feedback：创建反馈记录或 GitHub Issue。
- create-improvement-task：触发文档改进任务，但最终仍必须进入 PR。
4.12 反馈与任务产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub Issues + 轻量反馈入口 | 反馈可以直接进入可跟踪任务池。 |
| 最佳体验 | 专业工单/反馈系统 + GitHub 同步 | 对外部用户更友好，适合客服、产品和文档团队协作。 |
| 最佳成本 | GitHub Issues | 不引入新系统。 |
MVP 可只实现从页面反馈或问答反馈生成 GitHub Issue。后续再考虑专业工单系统。
4.13 权限与身份产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub 账号、团队、GitHub App/PAT | 与 PR、仓库、Actions 权限一致，减少身份系统复杂度。 |
| 最佳体验 | 企业 IdP/SSO + GitHub App + 文档前端权限 | 适合企业级访问控制和审计。 |
| 最佳成本 | GitHub 权限模型 | 读写边界清晰，成本最低。 |
权限原则：智能体不能直接写 main；人和智能体都必须通过 PR 修改正式文档。
4.14 配置管理产品
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | Git 管理 YAML 配置 + schema 校验 | 可审计、可回滚、易于自动化。 |
| 最佳体验 | 配置 UI + schema 校验 + PR 提交 | 非工程用户可维护来源和发布策略。 |
| 最佳成本 | YAML + CLI 校验 | 无额外服务。 |
配置必须包括：来源项目、来源 ref、来源目录、目标发布目录、发布后端、索引策略、问答策略、权限策略。
4.15 运行基础设施
| 维度 | 选型 | 理由 |
|---|---|---|
| 成本体验平衡 | GitHub Actions 定时任务 + 静态站点/轻量服务托管 + 托管或自建索引 | 自动化简单，成本可控。 |
| 最佳体验 | 托管运行平台 + 托管数据库/搜索/向量库 + 完整观测 | 降低故障处理和运维压力。 |
| 最佳成本 | GitHub Actions + 单机/VPS 自建服务 | 费用最低，但需要自己承担稳定性。 |
定时执行优先用 GitHub Actions schedule，因为它与仓库状态、PR、Secrets 和审计天然相连。
5. 三套组合方案
5.1 推荐方案：成本体验平衡
| 产品能力 | 推荐选型 |
|---|---|
| 文档源与治理 | GitHub 仓库、docs-publish 分支、PR、branch protection、Actions |
| 控制仓库 | kunora-docs + YAML 配置 + state lock |
| 文档收集 | 自研 CLI + 三方 diff + draft PR |
| 发布目录 | publish/** |
| 智能体迭代 | RAGFlow + 商业 LLM API |
| 展示产品 | Docusaurus 优先；保留 Wiki.js/Mintlify/GitBook/ReadMe adapter |
| 编辑产品 | GitHub PR 编辑，后续补轻量 Web 编辑入口 |
| 知识索引 | RAGFlow RAG 索引（向量存储优先 pgvector）+ Meilisearch |
| 问答产品 | RAGFlow 问答应用 + LLM-WIKI Answer API 薄封装 |
| 智能体访问 | LLM-WIKI Agent Access API/tool adapter，复用 RAGFlow、Meilisearch、GitHub Issues |
| 反馈任务 | GitHub Issues |
| 权限身份 | GitHub 权限 + GitHub App/PAT |
| 基础设施 | GitHub Actions + 静态站点/轻量服务托管 |
推荐原因：
- 保留 GitHub 审批主线，符合故事中的 human-approved。
- 不把大量精力花在文档站、RAG 平台、向量数据库这类成熟能力上。
- 自研部分集中在 LLM-WIKI 独有的文档治理控制面，范围可控。
- 未来可以从 Docusaurus 切到商业文档平台，从自建索引切到托管索引，不破坏主流程。
5.2 最佳体验方案
| 产品能力 | 推荐选型 |
|---|---|
| 文档源与治理 | GitHub Enterprise/组织级治理、强制 review、CODEOWNERS、GitHub App |
| 控制仓库 | kunora-docs + 管理 UI + 变更审计视图 |
| 文档收集 | 自研服务化 Collector + GitHub App webhooks |
| 智能体迭代 | 托管 Agent/RAG 平台 + 高质量商业模型 |
| 展示产品 | Mintlify / GitBook / ReadMe 等商业文档平台 |
| 编辑产品 | 商业平台 Web 编辑器 + PR 同步，或 LLM-WIKI 自研编辑台 |
| 知识索引 | Pinecone / Algolia 等托管服务 |
| 问答产品 | 托管问答/Agent 能力 + 自定义引用和反馈闭环 |
| 智能体访问 | Agent Gateway / MCP server + 企业身份 + 完整审计 |
| 反馈任务 | 专业反馈/工单系统 + GitHub 同步 |
| 权限身份 | 企业 SSO/IdP + GitHub App |
| 基础设施 | 托管应用平台、托管数据库、托管搜索、完整观测 |
体验收益：
- 非工程用户能直接阅读、搜索、问答、编辑和反馈。
- 文档平台提供更完整的预览、分析、AI 助手和品牌体验。
- 运维压力显著下降。
主要代价：
- 月度成本更高。
- 商业平台能力和数据模型会产生锁定。
- 仍然需要自研 LLM-WIKI 控制面，否则无法保证 GitHub 审批和发布目录治理。
5.3 最佳成本方案
| 产品能力 | 推荐选型 |
|---|---|
| 文档源与治理 | GitHub 免费/低成本计划 + PR |
| 控制仓库 | kunora-docs + YAML/JSON 文件 |
| 文档收集 | 自研脚本 + GitHub Actions |
| 智能体迭代 | 自建 RAGFlow，必要时用 LangChain/LlamaIndex 脚本补充 |
| 展示产品 | Docusaurus 静态站点，或 Wiki.js 自建 |
| 编辑产品 | GitHub Web 编辑器 |
| 知识索引 | RAGFlow 内部向量存储优先 pgvector + 自建 Meilisearch |
| 问答产品 | 自建 RAG 服务 + Ollama/低成本模型 |
| 智能体访问 | 轻量 HTTP API + GitHub Issues |
| 反馈任务 | GitHub Issues |
| 权限身份 | GitHub 权限 |
| 基础设施 | GitHub Actions + 单机/VPS/内网服务器 |
成本收益：
- 现金成本最低。
- 组件大多可本地部署。
- 数据控制权强。
主要代价：
- 运维、升级、安全加固和监控成本转移给团队。
- 本地模型质量和响应速度可能不稳定。
- 非工程用户体验弱，需要更多培训和流程约束。
6. 必须自研的范围
以下能力无法被通用商业服务或开源项目完整替代，应纳入 LLM-WIKI 自研控制面：
- 来源配置模型：统一管理 GitHub 项目、ref、sourcePath、publishPath、include/exclude、发布策略。
- 三方 diff 同步引擎：基于 previous source baseline、current source、current publish workspace 判断新增、更新、删除、保留和冲突。
- 发布目录治理：确保
publish/**既能接收上游文档，又能承载智能体整理后的正式内容。 - 冲突报告与 PR 自动化：同步完成后生成 draft PR，冲突必须显式呈现，不能静默覆盖。
- 智能体输出协议：智能体只能输出可审查 diff、变更说明和引用依据，不能直接发布。
- 发布后端适配器：把已审批文档发布到 Docusaurus、Wiki.js、商业文档平台或其他后端。
- 索引与问答元数据协议：统一页面路径、版本、来源、chunk、引用和反馈任务之间的关系。
- 治理状态视图：后续如需要 UI，只展示 GitHub 与 LLM-WIKI 状态，不替代 GitHub 审批。
不应自研的范围：
- 通用文档站渲染。
- 通用 Markdown 编辑器。
- 通用 RAG 平台。
- 通用向量数据库。
- 通用大模型服务。
- 通用身份系统。
7. MVP 技术落地顺序
- 完成
sources.yaml、publish/**、source lock 和三方 diff 同步。 - 用 GitHub Actions 定时同步上游文档，并自动创建 draft PR。
- 把发布后端抽象为
DisplayBackend，先实现一个最低成本后端。 - 接入一个智能体/RAG 平台，先支持“读取发布目录、生成文档改动、创建 release PR”。
- 接入基础索引与问答，先支持页面内问答、引用回跳、无答案反馈。
- 把问答反馈转成 GitHub Issue 或文档改进任务。
- 根据真实使用数据决定是否升级到商业文档平台、托管索引或企业身份。
8. 风险与约束
| 风险 | 影响 | 处理方式 |
|---|---|---|
| 商业平台锁定 | 迁移成本高 | 所有展示和问答后端必须走 adapter，不把平台字段写死到核心模型。 |
| 开源自建运维不足 | 服务不稳定 | MVP 优先减少长驻服务，能用 GitHub Actions 和静态站点就不用后台。 |
| 智能体误改文档 | 正式知识污染 | 智能体只能提交 PR，不允许直写 main 或直接发布。 |
| 上游同步覆盖整理内容 | 丢失人工/智能体整理成果 | 必须实现三方 diff 和冲突报告。 |
| 问答幻觉 | 用户信任下降 | 答案必须带引用；无证据时返回无答案 并创建改进任务。 |
| 成本失控 | 商业 LLM、搜索和文档平台费用增长 | 记录 token、检索、索引和问答用量；区分生产模型和离线批处理模型。 |
9. 当前仓库的技术调整建议
当前仓库已经具备部分 MVP 雏形，但需要按本选型做两项调整：
publish_wikijs.py应重命名或抽象为发布后端适配器，不应让 Wiki.js 成为代码层默认事实。sync_sources.py需要从目标镜像同步升级为真正的三方 diff，同步时保护已经被智能体或人工整理过的publish/**内容。
这两项属于技术方案阶段的实现任务，不影响本选型结论。
10. 官方资料依据
- GitHub Pull Requests 支持通过分支提出、审查和合并变更；适合作为正式审批主线：https://docs.github.com/en/pull-requests
- GitHub branch protection 可要求 PR 审批、状态检查等合并条件：https://docs.github.com/github/administering-a-repository/about-protected-branches
- GitHub Apps 可使用安装 token 访问组织资源，适合后续做细权限自动化：https://docs.github.com/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app
- GitHub Actions runner 按分钟计费并支持托管 runner，适合定时同步任务：https://docs.github.com/billing/reference/actions-runner-pricing
- Docusaurus 是面向 Markdown 文档的静态站点生成器：https://docusaurus.io/docs.html
- Wiki.js 是 AGPLv3 的开源 Wiki 软件，支持多数据库和多种集成：https://js.wiki/
- Mintlify、GitBook、ReadMe 提供商业文档平台、Web 编辑、AI/搜索/分析等能力：https://www.mintlify.com/pricing、https://www.gitbook.com/pricing、https://readme.com/pricing
- RAGFlow 是开源 RAG 与 Agent 能力平台：https://www.ragflow.io/、https://github.com/infiniflow/ragflow
- Flowise 是开源生成式 AI 开发平台，支持 Agent 和 LLM workflows：https://docs.flowiseai.com/
- LangChain 和 LlamaIndex 可作为更代码化的 Agent/RAG 编排框架：https://docs.langchain.com/oss/python/langchain/overview、https://docs.llamaindex.ai/
- Meilisearch、Algolia 分别覆盖全文搜索的自建/托管候选：https://www.meilisearch.com/pricing、https://www.algolia.com/pricing
- OpenAI、Anthropic 等商业模型服务按 token 收费，适合作为体验优先或平衡方案的模型供应商：https://openai.com/api/pricing/、https://docs.anthropic.com/en/docs/about-claude/pricing