LLM-WIKI 产品蓝图

# LLM-WIKI 产品蓝图

1. 产品定义

LLM-WIKI 是一个 Git-backed、Agent-iterated、Human-approved 的知识库系统。

它把工程项目文档、智能体文档迭代、人类审批、前端阅读编辑和问答接口连接成一个持续演进的知识系统。

LLM-WIKI = GitHub 文档治理 + 文档收集 + 智能体迭代 + 人工审批 + Wiki/Docs 前端 + 智能体访问接口 + 问答接口

LLM-WIKI 的核心目标不是“把 Markdown 发布到某个具体 Wiki 系统”，而是让知识库形成闭环：

工程文档产生知识
  -> 系统收集知识
  -> 智能体迭代知识
  -> 人审批知识
  -> 前端消费知识
  -> 问答暴露知识缺口
  -> 缺口再次进入文档迭代

2. 产品原则

2.1 Git 是治理底座

所有正式文档内容都必须经过 Git 版本管理。

GitHub PR 是审批、审计、回滚和协作的基础。任何绕过 GitHub 直接修改正式知识库的路径，都不是 LLM-WIKI 的主路径。

2.2 上游项目提供材料，不直接控制最终知识库

上游 GitHub 项目通过 docs-publish:docs/** 暴露稳定文档材料。

这些材料可以被收集到 LLM-WIKI，但上游项目不直接发布到最终文档展示后端，也不直接决定最终知识库结构。

2.3 智能体提高效率，不替代审批

文档迭代智能体可以整理、改写、补充和重组文档，但它不能绕过人工审批直接发布。

智能体的输出必须表现为可审查的 Git diff 和 PR。

2.4 前端是工作台，不只是阅读器

前端要提供阅读、编辑、搜索和问答入口，也要展示来源、版本、引用和发布状态。

前端编辑不应直接写生产知识库，而应进入 Git/PR 流程。

2.5 问答是知识改进入口

问答不仅消费文档，还暴露文档缺口。

低质量答案、无依据答案和用户反馈都应转化为文档改进信号。

2.6 智能体是一等使用者

LLM-WIKI 不只服务人，也服务智能体。

智能体访问不能只等同于网页阅读或普通问答。系统必须提供面向智能体的稳定访问面，包括文档读取、检索、问答、上下文包、引用、反馈和任务提交能力。

智能体可以消费知识和提出改进，但不能绕过 GitHub PR 修改正式内容。

3. 系统不变量

LLM-WIKI 必须长期保持以下不变量：

不变量	说明
单一发布入口	最终文档展示后端只接受 kunora-docs 发布
单一正式分支	kunora-docs/main 是唯一正式发布分支
稳定来源分支	上游项目默认只从 docs-publish 收集
配置决定路径	config/sources.yaml 决定来源目录写入哪个 publishPath
同步不做语义判断	自动收集只处理文件 diff，不理解文档内容
智能体不直接发布	智能体只能提交改动，不能直接写最终文档展示后端
发布前可预演	所有发布必须支持 dry-run
问答可追溯	答案应尽量返回引用、页面和版本
智能体访问受控	智能体只能通过受控 API/工具访问知识、提交反馈或创建任务，不能直接改写正式内容

这些不变量比具体技术实现更重要。后续技术方案可以调整，但不能破坏这些约束。

4. 产品边界

4.1 LLM-WIKI 负责什么

• 管理来源项目配置。
• 从 GitHub 项目收集稳定文档。
• 维护发布工作目录 publish/**。
• 让文档迭代智能体基于 publish/** 进行改进。
• 通过 PR 管理文档审批。
• 将审批后的文档发布到可替换的文档展示后端。
• 建立文档索引，支持搜索和问答。
• 给人和智能体提供文档读取、编辑、检索和问答接口。
• 给智能体提供面向任务的知识访问、上下文包、引用和反馈接口。

4.2 LLM-WIKI 不负责什么

• 不管理上游项目代码生命周期。
• 不要求上游项目内部文档结构统一。
• 不保证智能体改动自动正确。
• 不把问答答案当作权威内容源。
• 不让任何文档展示后端的后台成为受管页面的主编辑入口。
• 不在无审批情况下自动把智能体结果发布给用户。

4.3 展示后端选型状态

蓝图不绑定具体展示后端。Wiki.js 可以作为当前候选或过渡实现，但不是产品蓝图的不变量。

产品层只要求存在一个可替换的文档展示后端，能够承载审批后的文档阅读、导航、搜索入口和受管发布。具体使用 Wiki.js、自研前端或其他文档系统，应在技术方案阶段决策。

5. 系统分层

┌──────────────────────────────────────────────┐
│ Experience Layer                              │
│ 阅读 / 编辑 / 搜索 / 问答 / 反馈 / 审批视图       │
└───────────────────────┬──────────────────────┘
                        │
┌───────────────────────▼──────────────────────┐
│ API Layer                                      │
│ Document API / Edit API / Search API / Ask API / Agent Access API │
└──────────────┬───────────────────────┬───────┘
               │                       │
┌──────────────▼────────────┐   ┌──────▼─────────┐
│ Knowledge Layer            │   │ Agent Layer     │
│ 索引 / 切片 / 引用 / RAG     │   │ 文档迭代智能体   │
└──────────────┬────────────┘   └──────┬─────────┘
               │                       │
┌──────────────▼───────────────────────▼───────┐
│ Repository Layer                              │
│ kunora-docs / publish/** / PR / Git history    │
└──────────────┬───────────────────────────────┘
               │
┌──────────────▼───────────────────────────────┐
│ Source Layer                                  │
│ GitHub projects / docs-publish:docs/**         │
└──────────────────────────────────────────────┘

分层含义：

• Source Layer 负责产生材料。
• Repository Layer 负责保存、审计和审批材料。
• Agent Layer 负责改进材料。
• Knowledge Layer 负责让材料可检索、可问答。
• API Layer 负责给人和智能体提供稳定能力，其中 Agent Access API 是智能体使用 LLM-WIKI 的明确入口。
• Experience Layer 负责产品体验。

6. 核心子系统

6.1 文档来源系统

由多个 GitHub 项目组成。

每个项目通过固定分支和目录暴露稳定文档：

{repo}/docs-publish:docs/**

来源系统只承诺提供稳定材料，不承诺材料已经适合最终知识库阅读。

6.2 文档收集系统

文档收集系统读取 config/sources.yaml，把每个来源项目的 sourcePath 完整同步到 publishPath。

收集系统必须支持：

• 新增文件。
• 更新文件。
• 删除文件。
• 记录来源 commit。
• 记录同步动作。
• 发现冲突。

收集系统不负责：

• 改标题。
• 改结构。
• 合并页面。
• 补充内容。
• 判断内容正确性。

6.3 发布工作目录

publish/** 是 LLM-WIKI 的核心工作区。

它既接收自动收集结果，也接收智能体迭代结果，还作为发布系统输入。

因此它不是单纯缓存目录。它是版本化工作区，必须能被 Git diff、PR 和人类审查。

6.4 文档迭代智能体

文档迭代智能体读取 publish/** 和知识反馈，产生文档改进。

可执行动作包括：

• 统一术语。
• 优化标题和层级。
• 补充缺失说明。
• 将项目文档改写为知识库页面。
• 添加跨项目关系说明。
• 修复断链。
• 根据问答失败补充 FAQ。

智能体必须输出可审查变更，而不是直接发布。

6.5 审批系统

审批系统基于 GitHub PR。

PR 是三类变更的共同审查入口：

• 自动收集带来的来源变化。
• 智能体迭代带来的内容变化。
• 人工编辑带来的内容变化。

审批系统必须能回答：

• 哪些文件来自上游变化。
• 哪些文件是智能体改写。
• 哪些页面会影响发布。
• 哪些变更需要人重点确认。

6.6 发布系统

发布系统读取 main 上的 publish/**，发布到可替换的文档展示后端。

发布系统必须支持：

• dry-run。
• 新增页面。
• 更新页面。
• 删除受管页面。
• 不删除非受管页面。
• 发布 manifest。
• 失败时停止而不是静默跳过。

6.7 知识索引系统

知识索引系统把审批后的文档转化为可检索知识。

它负责：

• 文档切片。
• 元数据抽取。
• 语义表示或检索表示。
• 引用关系。
• 版本记录。
• 检索排序。

索引是派生数据，不是权威内容源。

6.8 问答系统

问答系统基于已发布文档和知识索引回答问题。

答案应尽量包含：

• 直接回答。
• 引用页面。
• 来源片段。
• 版本信息。
• 不确定性说明。

问答系统还要把失败或低质量答案转化为文档改进信号。

6.9 智能体访问系统

智能体访问系统是 LLM-WIKI 面向外部智能体的使用入口。

它提供：

• 文档读取 API。
• 结构化检索 API。
• 问答 API。
• 页面元数据 API。
• 面向任务的上下文包 API。
• 反馈和缺口上报 API。
• 文档改进任务创建 API。

它不提供：

• 直接写 main。
• 直接发布文档。
• 绕过审批的文档修改。
• 不带引用和版本的权威答案。

6.10 前端系统

前端是人使用 LLM-WIKI 的主入口。

它需要提供：

• 文档阅读。
• 目录导航。
• 搜索。
• 问答。
• 编辑入口。
• 反馈入口。
• 页面来源和版本展示。
• 审批和发布状态展示。

前端编辑必须进入 Git/PR 流程。

7. 核心对象模型

对象	含义	权威来源
Source Project	上游 GitHub 项目	GitHub 项目配置
Source Ref	稳定文档来源分支	config/sources.yaml
Source Path	上游文档根目录	config/sources.yaml
Publish Path	写入发布工作区的目标目录	config/sources.yaml
Source Baseline	上一次成功收集的来源文件状态	state/source-lock.json
Publish Workspace	publish/** 工作目录	kunora-docs Git
Document Page	可阅读、可发布的文档文件	publish/**
Document Change	文档新增、更新、删除或改写	Git diff
Sync Conflict	来源变化和本地迭代同时修改同一文件	sync report / PR
Iteration Task	文档改进任务	问答反馈或人工创建
Release PR	待审批的发布变更	GitHub PR
Published Page	已发布到文档展示后端的页面	publish manifest + selected backend
Knowledge Chunk	检索和问答使用的文档片段	索引系统
Answer	基于知识库生成的答案	问答系统
Feedback	用户或智能体对答案/文档的反馈	前端/API

8. 文档生命周期

Source Doc
  -> Collected Doc
  -> Iterated Doc
  -> Reviewed Doc
  -> Published Doc
  -> Indexed Knowledge
  -> Answered Knowledge
  -> Feedback
  -> Iteration Task

生命周期说明：

阶段	说明	是否权威
Source Doc	上游项目文档	对项目局部权威
Collected Doc	收集到 publish/** 的文档	工作区内容
Iterated Doc	智能体或人改进后的文档	待审批
Reviewed Doc	PR 审批通过的文档	发布前权威
Published Doc	已发布到文档展示后端的文档	用户可见权威
Indexed Knowledge	从文档派生的索引	非权威派生数据
Answered Knowledge	基于索引生成的答案	非权威输出
Feedback	用户或智能体反馈	改进信号
Iteration Task	下一轮文档改进任务	工作项

9. 同步语义：必须是三方模型

这是蓝图中最关键的约束。

因为自动收集和文档迭代智能体都会影响 publish/**，所以同步不能简单地用“当前上游文件覆盖当前 publish 文件”。否则智能体改动会被下一次自动同步覆盖。

同步必须基于三方状态：

A = 上一次成功收集的 Source Baseline
B = 当前上游 Source
C = 当前 publish/** 工作目录

同步判断规则：

场景	判断	动作
B 变了，C 没变	上游单方变化	自动更新 C
B 没变，C 变了	本地/智能体单方变化	保留 C
B 变了，C 也变了，且改动不同	双方变化	标记冲突，不自动覆盖
B 新增文件	来源新增	新增到 C
B 删除文件，C 未改	来源删除	删除 C
B 删除文件，C 已改	删除冲突	标记冲突，不自动删除

这条规则保证：

• 上游文档变化能进入系统。
• 智能体改动不会被无条件覆盖。
• 真正冲突会进入 PR，让人处理。

10. 两条主流程

10.1 自动收集流程

GitHub project docs-publish:docs/**
  -> sync_sources.py
  -> three-way diff
  -> publishPath
  -> source-lock.json
  -> source-changes.json
  -> draft PR

目的：把工程项目文档稳定带入 LLM-WIKI。

输出：

• publish/** 的文件变更。
• state/source-lock.json。
• state/source-changes.json。
• draft PR。

10.2 迭代发布流程

publish/**
  -> 文档迭代智能体
  -> release PR
  -> 人工审批
  -> main
  -> 文档展示后端发布
  -> 索引
  -> 问答
  -> 反馈

目的：把收集来的材料变成可信知识库内容。

输出：

• 审批后的文档。
• 发布页面。
• 知识索引。
• 可追溯答案。
• 新的改进任务。

11. 前端蓝图

11.1 阅读视图

用于浏览发布后的知识库。

必须展示：

• 页面标题。
• 正文。
• 目录位置。
• 更新时间。
• 来源信息。
• 发布状态。
• 相关页面。
• 提问入口。

11.2 编辑视图

用于发起文档修改。

编辑结果必须进入 PR 或等价审批流，不能直接绕过治理写入正式发布内容。

11.3 搜索视图

用于搜索页面、标题、标签和内容片段。

搜索结果应能跳转到文档页面，也能作为问答上下文。

11.4 问答视图

用于自然语言提问。

答案必须尽量展示引用来源，并允许用户反馈答案质量。

11.5 任务视图

用于查看知识库运维状态：

• 待处理同步 PR。
• 同步冲突。
• 智能体改进任务。
• 待审批 release PR。
• 发布状态。
• 问答反馈形成的文档缺口。

12. 后端蓝图

后端提供五类能力：

能力	说明
Source Sync	从上游项目收集文档，执行三方 diff
Repository Governance	通过 GitHub 管理版本、PR、审批和回滚
Agent Iteration	让智能体读取、修改并提交文档改进
Knowledge Service	索引、检索、问答、引用和反馈
Publishing	将审批后的文档发布到选定文档展示后端

后端的核心不是单个服务，而是一组围绕 GitHub 和 publish/** 协作的流程。

13. MVP 蓝图

13.1 MVP 必须闭合的链路

MVP 必须打通这条链路：

docs-publish 文档
  -> publish/** 收集
  -> 智能体或人工迭代
  -> PR 审批
  -> 文档展示后端发布
  -> RAG/搜索索引
  -> 问答与智能体访问

13.2 MVP 必须有

• config/sources.yaml 管理来源。
• 从上游 docs-publish:docs/** 收集文档。
• 三方同步语义，至少不能覆盖本地/智能体改动。当前脚本已具备文件级 add/update/delete，同步语义后续必须升级到三方 diff。
• 新增、更新、删除三类文件动作。
• 同步冲突报告。
• draft PR 展示自动收集结果。
• 文档迭代智能体可以修改 publish/**。
• release PR 人工审批。
• 文档展示后端 dry-run 发布计划。
• 选定文档展示后端的真实发布能力。
• 初版问答接口或问答服务边界定义。
• 初版智能体访问接口，至少支持 search、ask、get-context 和 create-feedback。

13.3 MVP 可以后置

• 完整在线编辑器。
• 多租户权限。
• 高级导航编排。
• 复杂知识图谱。
• 大规模自动文档重构。
• 多文档展示后端适配。
• 高级评价和自动质量评分。

14. 关键设计决策

14.1 为什么用 GitHub 做治理底座

因为文档需要版本、审计、回滚、审批和协作。GitHub 已经提供这些能力。

14.2 为什么 publish/** 既是收集目录又是工作目录

因为系统需要一个可被同步、可被智能体修改、可被人审查、可被发布器读取的统一工作区。

这个设计要求同步必须使用三方 diff，否则会覆盖智能体改动。

14.3 为什么智能体不能直接发布

因为知识库需要可信治理。智能体提高效率，但不能替代最终审批。

14.4 为什么问答要进入主流程

因为问答会暴露知识缺口。LLM-WIKI 不只是回答问题，还要把回答失败转化为文档改进。

14.5 为什么展示后端不是权威源

文档展示后端只是展示和交互层，可以是 Wiki.js，也可以是未来自研前端或其他系统。权威源必须是 Git 中经过审批的文档，否则无法可靠审计和回滚。

15. 主要风险与缓解

风险	影响	缓解
同步覆盖智能体改动	文档迭代结果丢失	三方 diff 和冲突报告
智能体生成错误内容	错误知识进入用户可见知识库	PR 审批和来源引用
问答无依据幻觉	用户获得错误答案	引用来源、置信度、反馈机制
展示后端后台被手工修改	Git 和展示层漂移	受管标记、manifest、漂移检测
上游文档质量低	知识库质量低	文档迭代智能体和审批机制
MVP 范围过大	无法落地	先打通收集、迭代、审批、发布主链路

16. 成功标准

蓝图成立的标准：

• 项目文档能稳定进入 publish/**。
• 自动同步不会无条件覆盖智能体改动。
• 冲突能被报告并进入人工处理。
• 文档迭代智能体能产生可审查改动。
• 人能通过 PR 审批文档。
• 审批后的文档能发布到选定文档展示后端。
• 用户能阅读、搜索、编辑和提问。
• 问答结果能返回引用来源。
• 问答反馈能进入下一轮文档迭代。

17. 下一步

蓝图下一步不是直接进入技术实现，而是继续拆解产品特性。

产品特性文档需要回答：

• 用户具体能做什么。
• 智能体具体能做什么。
• 审批者具体看到什么。
• 每个能力的输入、输出和成功状态是什么。
• 哪些能力属于 MVP，哪些后置。