LLM-WIKI 产品级技术选型矩阵

# LLM-WIKI 产品级技术选型矩阵

1. 文档定位

本文用于逐一讨论 LLM-WIKI 产品架构中各独立产品的技术选型。

本文不改变既有蓝图约束：

GitHub 是唯一确定选型。
其他技术产品均为候选或阶段性推荐。
Wiki.js、Docusaurus、RAGFlow、Mintlify、向量数据库和模型供应商都不能写死到蓝图层。
LLM-WIKI 只自研现成商业服务和开源方案无法覆盖的文档治理控制面。

2. 选型总览

产品	推荐选型	备选选型	自研边界
GitHub 文档源	GitHub 仓库 + `docs-publish` 分支	固定 tag 前缀	不自研 Git 托管
LLM-WIKI 控制仓库	GitHub repo + YAML/JSON	后续管理 UI	自研配置模型和状态模型
文档收集器	自研 Python CLI + GitHub Actions	GitHub App 服务化 Collector	必须自研
发布工作目录	`publish/**` Git 目录	对象存储镜像	自研目录规范和状态约束
文档迭代智能体	RAGFlow + 商业 LLM	Flowise / LangChain / LlamaIndex	自研 AgentBridge
审批与治理台	GitHub PR + branch protection	GitHub PR + 自研治理视图	不替代 PR，只做视图和编排
文档展示产品	Docusaurus	Wiki.js / Mintlify / GitBook / ReadMe	自研 DisplayBackend adapter
文档编辑产品	GitHub 编辑 + PR	商业文档平台编辑器 / 自研轻量编辑器	自研时只提交 PR
知识索引产品	RAGFlow RAG 索引 + Meilisearch	pgvector / Algolia / 专用向量库	自研索引元数据协议，向量存储不单列为 MVP 产品
问答产品	RAGFlow 问答应用	自研 API + LangChain/LlamaIndex	自研 Answer API 适配层
智能体访问产品	LLM-WIKI Agent Access API/tool adapter	MCP server / Agent Gateway	自研访问协议、scope、审计和反馈桥接
反馈与任务产品	GitHub Issues	Jira/Linear/商业反馈系统	自研反馈到任务映射
权限与身份产品	GitHub 权限 + GitHub App/PAT	企业 SSO/IdP	自研权限映射，不自研 IdP
配置管理产品	Git-managed YAML + schema 校验	配置 UI	自研 schema 和校验器
运行基础设施	GitHub Actions + 静态/轻量服务托管	托管 PaaS / 自建服务器	自研编排，不自研基础设施

3. 逐产品选型

3.1 GitHub 文档源

技术产品

技术产品	关键特性	适配度
GitHub Repository	分支、tag、commit、PR、权限、审计	高
GitHub protected branches	限制 force push、要求 PR 和检查	高
GitHub CODEOWNERS	自动指定评审人	中

理由

已经确定所有来源项目都在 GitHub。
固定发布分支比 main 更稳定，能隔离开发中未准备发布的文档。
LLM-WIKI 只读取该分支或固定 tag 前缀，避免隐式消费未发布内容。

关键约束

每个来源项目必须显式配置 repo、ref、sourcePath、publishPath。
来源项目内文档如何组织，不由 LLM-WIKI 干预。
LLM-WIKI 只把整个 sourcePath 同步到配置指定的 publishPath。

3.2 LLM-WIKI 控制仓库

技术产品

技术产品	关键特性	适配度
GitHub Repository	配置、状态、发布目录、PR 统一审计	高
YAML/JSON 文件	可读、可审查、适合自动化	高
GitHub App	细粒度权限和自动化身份	中，适合后续

理由

当前最核心的是让配置和状态可审查、可回滚。
不需要先建设数据库或后台管理系统。
后续如果配置复杂，再补管理 UI，但 UI 也应通过 PR 修改配置。

关键特性映射

产品特性	技术支撑
来源配置管理	`config/sources.yaml`
发布路径配置	`publishPath` 字段
同步状态追踪	`state/source-lock.json`
变更审计	Git commit + PR

3.3 文档收集器

技术产品

技术产品	关键特性	适配度
自研 Python CLI	精确控制 Git 读取、文件同步、三方 diff	高
GitHub Actions	定时执行、手动触发、Secrets、PR 自动化	高
GitHub App	更安全的跨仓库访问	中，适合后续服务化
rsync / copy 工具	目录镜像	低，不能表达三方 diff

理由

文档收集器是 LLM-WIKI 的核心差异点，不能简单用目录同步工具替代。它必须知道：

上一次同步的来源基线是什么。
当前上游来源变了什么。
当前 publish/** 是否已经被智能体或人整理过。
什么时候自动更新，什么时候保留，什么时候报冲突。

必须支持的特性

特性	要求
新增	上游新增文件，目标未修改时写入 `publishPath`
更新	上游更新文件，目标未修改时更新
删除	上游删除文件，目标未修改时删除
保留	上游未变、目标已变时保留目标
冲突	上游和目标同时变更时生成冲突报告
PR 输出	同步结果必须通过 draft PR 呈现

3.4 发布工作目录

技术产品

技术产品	关键特性	适配度
Git directory `publish/**`	可 diff、可审查、可回滚	高
Markdown/MDX	文档源格式，适合展示和智能体处理	高
Object storage	可做发布产物存储	低，不适合作为编辑事实源

理由

它不是临时缓存，而是文档生产流水线的事实源。
上游同步、智能体迭代、人工编辑、发布系统都围绕它工作。
Git diff 是最直接、最低成本、最可审计的治理机制。

关键约束

收集器不能无条件覆盖 publish/**。
智能体不能直接发布，只能修改 publish/** 并生成 PR。
发布系统只读取已审批合并的 publish/**。

3.5 文档迭代智能体

技术产品

技术产品	关键特性	适配度
RAGFlow	文档理解、RAG、Agent 编排、引用能力	高
Flowise	可视化 Agent/LLM workflow、API、human-in-loop	中
LangChain	代码化 Agent/RAG 编排，生态丰富	中
LlamaIndex	数据连接、索引、Agent over data	中
OpenAI / Anthropic / Gemini API	高质量商业模型	高
Ollama	本地模型运行	中，适合低成本/离线场景

理由

智能体平台本身不是 LLM-WIKI 的核心壁垒，不应从零自研。
RAGFlow 已部署，且能支撑文档问答、RAG、工具调用和 Agent 编排。
商业模型在文档重写、结构化、问答准确性方面通常比本地低成本模型更稳。

LLM-WIKI 需要自研的部分

自研项	原因
AgentBridge	外部智能体平台不知道 LLM-WIKI 的 Git/PR 协议
任务输入协议	需要声明目标目录、上下文、约束、输出格式
输出 diff 协议	智能体结果必须变成可审查 Git diff
变更说明协议	PR 审批需要知道改了什么、为什么改
失败处理	智能体失败不能污染发布目录

3.6 审批与治理台

技术产品

技术产品	关键特性	适配度
GitHub Pull Requests	diff、评论、审批、合并、冲突处理	高
GitHub branch protection	要求审批、状态检查、限制直接推送	高
GitHub Actions checks	自动校验、dry-run、发布检查	高
自研治理视图	汇总来源、影响页面、冲突、发布状态	中，适合后续

理由

PR 是当前最成熟的 human-approved 机制。
审批结论、讨论和合并记录都保留在 GitHub。
自研审批系统会重复建设，并降低可信度。

后续增强

可以建设治理台，但只能作为 GitHub PR 的聚合视图：

显示这次变更来自哪个上游项目。
显示哪些页面受影响。
显示哪些变更来自智能体。
显示发布 dry-run 结果。
跳转到 GitHub PR 完成最终审批。

3.7 文档展示产品

技术产品

技术产品	关键特性	适配度
Docusaurus	开源、Markdown/MDX、静态站点、版本化、搜索可扩展	高
Wiki.js	开源 Wiki、内置编辑、权限、搜索、数据库支撑	中
Mintlify	商业文档平台、Web editor、Git sync、AI assistant、MCP	高，体验优先
GitBook	商业文档平台、Git sync、AI assistant、权限、协作	高，体验优先
ReadMe	商业 API 文档平台、API reference、AI、双向同步	中到高，偏 API docs

理由

Docusaurus 与 Git + Markdown 最贴合，部署和迁移成本低。
商业文档平台能显著提升阅读、编辑、搜索、AI 助手和非工程用户体验。
Wiki.js 有自建优势，但会引入服务端和数据库运维，也不能成为蓝图固定前提。

必须抽象

展示产品必须通过 DisplayBackend 接入：

Adapter	用途
`DocusaurusBackend`	从 `publish/**` 构建静态站点
`WikiJsBackend`	调用 Wiki.js API 或 Git storage 发布页面
`MintlifyBackend`	生成 Mintlify 兼容结构或触发 Git sync
`GitBookBackend`	生成 GitBook 兼容结构或触发同步
`ReadMeBackend`	发布 API docs 或指南内容

3.8 文档编辑产品

技术产品

技术产品	关键特性	适配度
GitHub Web editor	在线改文件、提交分支、创建 PR	高，MVP
GitHub Codespaces / 本地 IDE	工程化编辑和预览	中
商业文档平台编辑器	非工程用户友好、预览、协作	高，体验优先
自研轻量编辑器	页面内编辑、预览、提交 PR	中，后续可做

理由

最少系统建设。
完全符合 GitHub 审批主线。
对工程用户足够可用。

何时自研编辑器

当出现以下问题时再做：

非工程用户无法使用 GitHub 编辑。
需要页面内“阅读 -> 编辑 -> 预览 -> 提交 PR”的闭环。
需要在编辑界面显示来源、质量状态、问答反馈和相关页面。

3.9 知识索引产品

技术产品

技术产品	关键特性	适配度
pgvector	PostgreSQL 向量扩展，作为 RAGFlow 内部向量存储倾向	中，RAGFlow 实施细节
Meilisearch	开源/托管全文搜索，低成本、易集成	高
Pinecone	托管向量数据库，适合生产级语义检索	高，体验优先
Algolia	托管搜索，搜索体验、分析和 AI 搜索能力强	高，体验优先
Elasticsearch/OpenSearch	强全文检索和分析	中，运维较重

理由

RAGFlow 负责文档解析、chunk、embedding、召回、重排和引用。
向量存储不单列为 MVP 技术产品，RAGFlow 实施中优先评估 pgvector。
Meilisearch 负责站内搜索，支撑人和智能体使用的标题、路径、标签、片段搜索。

LLM-WIKI 自研边界

不自研搜索引擎，但需要自研索引元数据协议：

元数据	用途
page path	引用回跳
heading anchor	精确定位答案来源
source project	追踪内容来源
version/ref	判断答案对应的文档版本
chunk id	连接问答引用和索引记录
quality status	控制低质量文档是否进入问答

3.10 问答产品

技术产品

技术产品	关键特性	适配度
RAGFlow	文档理解、RAG、引用、Agent 能力	高
LangChain/LangGraph	深度定制问答流程	中
LlamaIndex	数据索引和 query engine	中
OpenAI / Anthropic / Gemini API	高质量生成和推理	高
本地模型/Ollama	低成本、可离线	中

理由

问答产品需要快速验证“用户是否真的通过文档问答解决问题”。
直接自研完整 RAG 系统投入大，且早期需求还会变化。
统一 Answer API 可以避免未来切换 RAGFlow/自研服务时影响前端和智能体。

必须支持的输出

输出	要求
answer	结构化答案，而不是纯聊天文本
citations	必须包含页面、标题、片段、路径
confidence/grounding	能表达证据是否充分
no-answer reason	无答案时说明原因
improvement task hook	可转成文档改进任务

3.11 智能体访问产品

技术产品

技术产品	关键特性	适配度
LLM-WIKI Agent Access API	稳定 schema、scope、引用、反馈、任务提交	高，MVP
RAGFlow API	问答、RAG、引用、Agent 执行	高
Meilisearch API	关键词搜索、过滤、分组	高
GitHub Issues API	反馈和改进任务创建	高
MCP server	标准化智能体工具协议	中，后续

理由

智能体不是普通网页用户，需要稳定工具接口。
问答只是智能体访问的一部分，智能体还需要 search、get-page、get-context、create-feedback 和 create-improvement-task。
访问层必须做 scope、权限、引用标准化和审计，不能让外部智能体直接调用所有底层系统。

MVP 工具集合

工具	作用
`search`	搜索文档和页面片段
`ask`	基于 RAGFlow 获取带引用答案
`get_page`	读取指定页面和元数据
`get_context`	获取面向任务的上下文包
`create_feedback`	提交答案错误、无答案、引用不足等反馈
`create_improvement_task`	创建文档改进任务，后续进入 PR 流程

3.12 反馈与任务产品

技术产品

技术产品	关键特性	适配度
GitHub Issues	任务追踪、标签、负责人、PR 关联	高
GitHub Discussions	用户讨论和知识沉淀	中
Jira / Linear	专业项目管理	中，团队已有时适配
商业反馈系统	外部用户反馈、投票、客服流转	中，外部化后适配

理由

与 GitHub PR、commit、文档改进任务天然关联。
不需要引入新的任务系统。
智能体可从 Issue 读取任务，再提交文档改进 PR。

自研边界

需要自研 FeedbackBridge：

页面反馈转 Issue。
问答“无答案/答案错误”转 Issue。
Issue 与文档路径、chunk、问答记录关联。
Issue 触发智能体迭代任务。

3.13 权限与身份产品

技术产品

技术产品	关键特性	适配度
GitHub users/teams	仓库权限、团队权限	高
GitHub App	细粒度自动化权限	高
PAT	快速接入，但权限边界较粗	中，MVP 可用
企业 SSO/IdP	企业身份、统一登录、审计	中，后续适配
文档平台内置权限	阅读权限、编辑权限	取决于展示产品

理由

当前所有正式改动都走 GitHub，因此权限也应先复用 GitHub。
GitHub App 比 PAT 更适合长期自动化，但实现复杂度更高。
企业 SSO 等到文档门户有明确访问控制需求后再引入。

权限原则

智能体不能直写 main。
收集器不能绕过 PR 发布正式内容。
发布系统只能读取已审批内容。
外部问答接口不能暴露未发布草稿，除非显式授权。

3.14 配置管理产品

技术产品

技术产品	关键特性	适配度
YAML	人可读、PR 可审查	高
JSON Schema / Pydantic	配置校验、错误提示	高
GitHub PR	配置变更审批	高
自研配置 UI	非工程用户维护配置	中，后续

理由

配置本身影响发布结果，必须可审计。
早期配置项不复杂，不需要数据库和后台。
schema 校验能降低误配置风险。

配置范围

配置	示例
来源配置	repo、ref、sourcePath、publishPath
同步配置	include、exclude、deletePolicy、conflictPolicy
展示配置	backend、basePath、slug policy
索引配置	chunk size、embedding model、index target
问答配置	retrieval policy、answer model、citation required
权限配置	allowed readers、allowed editors、agent role

3.15 运行基础设施

技术产品

技术产品	关键特性	适配度
GitHub Actions	schedule、manual dispatch、Secrets、checks	高
GitHub Pages / 静态托管	静态站点发布	中
PaaS/容器平台	长驻 API、问答服务、索引服务	中
VPS/内网服务器	低成本自建	中
托管数据库/搜索/向量库	降低运维	高，体验优先

理由

同步、校验、PR 创建天然是仓库流水线任务。
GitHub Actions 能同时支撑定时执行和手动触发。
问答服务、索引服务如果需要长驻，再引入 PaaS 或自建服务器。

定时机制

任务	机制
同步来源文档	GitHub Actions schedule + workflow_dispatch
生成同步 PR	GitHub Actions + GitHub token/App token
发布检查	PR/main workflow checks
正式发布	main 合并后触发 publish workflow
索引更新	发布成功后触发 index workflow

4. 当前推荐的 MVP 技术产品清单

层级	技术产品	采用状态
源码与治理	GitHub	固定采用
自动化	GitHub Actions	推荐采用
配置	YAML + JSON/Pydantic schema	推荐采用
收集器	自研 Python CLI	必须自研
发布目录	`publish/**`	固定工作区
展示	Docusaurus	推荐 MVP
智能体/RAG	RAGFlow	已部署，MVP 采用
模型	商业 LLM API	推荐 MVP
RAG/向量存储	RAGFlow 内部实施，优先评估 pgvector	不作为独立 MVP 产品
站内搜索	Meilisearch	推荐 MVP
问答 API	RAGFlow + LLM-WIKI wrapper	推荐 MVP
智能体访问	LLM-WIKI Agent Access API/tool adapter	推荐 MVP
反馈任务	GitHub Issues	推荐 MVP
权限	GitHub permissions + PAT，后续 GitHub App	阶段采用

5. 需要下一步确认的选型点

以下点不建议继续停留在抽象层，需要进入小范围技术验证：

Docusaurus 的目录结构、sidebar 生成和页面元数据是否满足 MVP 展示要求。
RAGFlow 当前部署是否支持 pgvector，或需要沿用现有向量存储。
Agent Access API 先提供 HTTP API，还是同时提供 MCP server。
商业模型供应商是否先做可配置抽象，不绑定单一模型。
GitHub 自动化先用 PAT 还是直接建设 GitHub App。

建议顺序：先验证展示后端和三方 diff，因为它们决定发布目录结构和后续所有 adapter 的接口。

来源项目	`kunora-wiki`
分支	`docs-publish`
路径	`technology/components/kunora-wiki/product/06-technology-product-selection.md`

1. 文档定位​

2. 选型总览​

3. 逐产品选型​

3.1 GitHub 文档源​

技术产品​

推荐选型​

理由​

关键约束​

3.2 LLM-WIKI 控制仓库​

技术产品​

推荐选型​

理由​

关键特性映射​

3.3 文档收集器​

技术产品​

推荐选型​

理由​

必须支持的特性​

3.4 发布工作目录​

技术产品​

推荐选型​

理由​

关键约束​

3.5 文档迭代智能体​

技术产品​

推荐选型​

理由​

LLM-WIKI 需要自研的部分​

3.6 审批与治理台​

技术产品​

推荐选型​

理由​

后续增强​

3.7 文档展示产品​

技术产品​

推荐选型​

理由​

必须抽象​

3.8 文档编辑产品​

技术产品​

推荐选型​

理由​

何时自研编辑器​

3.9 知识索引产品​

技术产品​

推荐选型​

理由​

LLM-WIKI 自研边界​

3.10 问答产品​

技术产品​

推荐选型​

理由​

必须支持的输出​

3.11 智能体访问产品​

技术产品​

推荐选型​

理由​

MVP 工具集合​

3.12 反馈与任务产品​

技术产品​

推荐选型​

理由​

自研边界​

3.13 权限与身份产品​

技术产品​

推荐选型​

理由​

权限原则​

3.14 配置管理产品​

技术产品​

推荐选型​

理由​

配置范围​

3.15 运行基础设施​

技术产品​

推荐选型​

理由​

定时机制​

4. 当前推荐的 MVP 技术产品清单​

5. 需要下一步确认的选型点​

1. 文档定位

2. 选型总览

3. 逐产品选型

3.1 GitHub 文档源

技术产品

推荐选型

理由

关键约束

3.2 LLM-WIKI 控制仓库

技术产品

推荐选型

理由

关键特性映射

3.3 文档收集器

技术产品

推荐选型

理由

必须支持的特性

3.4 发布工作目录

技术产品

推荐选型

理由

关键约束

3.5 文档迭代智能体

技术产品

推荐选型

理由

LLM-WIKI 需要自研的部分

3.6 审批与治理台

技术产品

推荐选型

理由

后续增强

3.7 文档展示产品

技术产品

推荐选型

理由

必须抽象

3.8 文档编辑产品

技术产品

推荐选型

理由

何时自研编辑器

3.9 知识索引产品

技术产品

推荐选型

理由

LLM-WIKI 自研边界

3.10 问答产品

技术产品

推荐选型

理由

必须支持的输出

3.11 智能体访问产品

技术产品

推荐选型

理由

MVP 工具集合

3.12 反馈与任务产品

技术产品

推荐选型

理由

自研边界

3.13 权限与身份产品

技术产品

推荐选型

理由

权限原则

3.14 配置管理产品

技术产品

推荐选型

理由

配置范围

3.15 运行基础设施

技术产品

推荐选型

理由

定时机制

4. 当前推荐的 MVP 技术产品清单

5. 需要下一步确认的选型点