LLM Wiki 产品故事

# LLM Wiki 产品故事

1. 一句话

LLM Wiki 是一个 Git-backed、Agent-iterated、Human-approved 的知识库系统：Git 管版本，智能体管迭代，人管审批，前端管阅读、编辑和问答。

2. 为什么需要它

Kunora 的知识首先产生在工程项目里。每个项目都会沉淀 README、设计文档、架构说明、使用说明和决策记录。这些文档对项目维护者有价值，但它们天然分散在多个 GitHub 仓库中，结构、术语、粒度和更新节奏都不一致。

如果直接让每个项目把文档发布到某个具体文档展示系统，会出现几个问题：

• 多个仓库同时写 Wiki，发布入口失控。
• 项目文档只是原材料，通常不适合直接作为统一知识库页面。
• 传统 Wiki 或展示系统的后台编辑通常缺少 Git 级别的审计、回滚和审批。
• 文档变化无法自然触发智能体整理和知识库改进。
• 人和智能体提问时，难以确认答案来自哪个版本、哪个页面、哪个来源。

如果只使用传统 Wiki，也会遇到另一个问题：Wiki 更像展示和编辑界面，而不是一个能持续吸收工程文档、让智能体参与迭代、并保持人工治理的知识系统。

因此，Kunora 需要的不是普通文档同步工具，而是 LLM Wiki：一个把 GitHub、智能体、人工审批、前端阅读编辑和问答接口串起来的知识库系统。

3. 系统承诺

LLM Wiki 要保证五件事同时成立：

1. 项目文档可以稳定进入统一知识库。
2. 智能体可以持续改进文档，但不能绕过人类审批。
3. 人可以阅读、编辑、搜索和审核文档。
4. 人和智能体都可以通过接口获得可追溯的问题答案。
5. 智能体可以把 LLM-WIKI 当作受治理的知识工具使用，而不是只能像人一样阅读页面。
6. 文档展示前端只是展示和交互层，不是失控的内容源。

这些承诺共同构成 LLM Wiki 的核心闭环：

GitHub 项目文档
  -> 文档收集
  -> 发布工作目录
  -> 智能体迭代
  -> PR 审批
  -> 文档展示后端发布
  -> 阅读 / 编辑 / 问答
  -> 反馈新的文档改进需求

4. 关键角色

4.1 项目维护者

项目维护者负责在各自项目中维护原始文档，并把稳定版本发布到项目的 docs-publish 分支。

他们不直接操作文档展示后端，也不需要理解统一知识库的全部组织方式。他们只需要保证项目提供可靠的文档材料。

4.2 文档迭代智能体

文档迭代智能体负责把收集来的项目文档变成更适合知识库使用的内容。

它可以整理结构、统一术语、改写页面、补充 FAQ、修复链接、合并重复内容，也可以根据问答失败记录补齐缺失文档。

但智能体不是发布者。它的修改必须进入 GitHub PR，并由人审批。

4.3 审批者

审批者负责判断文档是否准确、完整、适合发布。

审批者不是逐字手工维护所有文档的人，而是知识质量的最终守门人。

4.4 阅读和编辑用户

用户通过前端阅读文档、搜索内容、发起编辑或反馈问题。

编辑不是直接绕过治理写入生产 Wiki，而是进入 Git/PR 流程，保持审计和回滚能力。

4.5 提问者

提问者可以是人，也可以是另一个智能体。

他们通过问答接口获取答案。答案必须尽量带来源、版本和引用页面，避免知识库变成不可追溯的黑盒。

4.6 知识使用智能体

知识使用智能体不是文档迭代智能体。它不一定负责改文档，而是在执行研发、运维、客服、分析或其他任务时，需要把 LLM-WIKI 当作可信知识工具使用。

它需要的不只是“问一个问题”：

• 按任务 scope 获取相关文档上下文。
• 获取可引用、可回跳、可审计的答案。
• 判断答案是否足够可靠。
• 在发现知识缺口时创建反馈或改进任务。
• 在被授权时触发文档迭代流程，但不能绕过 PR 审批。

5. 后端故事

后端的核心是 GitHub 管理文档生命周期。

各项目将稳定文档发布到 docs-publish:docs/**。kunora-docs 定时读取这些来源，并按照配置把整个文档目录同步到指定的发布工作目录：

kunora-kgent/docs/**
  -> kunora-docs/publish/system/components/kunora-kgent/**

这个同步过程必须是确定性的，只做三类文件动作：

动作	条件	结果
新增	来源有文件，目标没有	写入发布目录
更新	来源和目标内容不同	更新发布目录
删除	来源没有文件，目标仍存在	从发布目录删除

同步流程不解释文档含义，不重组目录，也不决定页面是否适合发布。它只是把各项目的稳定文档材料收集到 LLM Wiki 的工作区。

后端随后通过类似 RAGFlow 的机制，或其他文档迭代智能体，读取 publish/** 并执行文档改进。智能体完成改动后创建 PR。审批通过后，合并到 main，再由发布器把受管内容同步到选定的文档展示后端。

因此，后端不是一个单次同步脚本，而是一套文档生命周期控制机制：

收集 -> 迭代 -> 审批 -> 发布 -> 索引 -> 问答 -> 反馈 -> 再迭代

6. 前端故事

前端不是简单的 Markdown 阅读器。它需要同时服务人和智能体。

面向人，前端要提供：

• 文档阅读和导航。
• 搜索。
• 在线编辑或编辑请求。
• 页面来源、版本和发布状态展示。
• 问答入口。
• 答案引用和反馈入口。

面向智能体，前端或 API 层要提供：

• 文档读取接口。
• 检索接口。
• 问答接口。
• 页面元数据接口。
• 面向任务的上下文包接口。
• 反馈和缺口上报接口。
• 文档改进提交入口。

这个访问面应当对智能体友好，而不是只复用人类网页。智能体需要稳定 schema、scope、权限、引用、版本和错误语义。它可以消费知识，也可以反馈知识缺口，但不能直接改写正式知识库。

这里的关键点是：阅读、编辑和问答不能分裂成三套互不相干的系统。用户阅读时发现问题，可以触发编辑；问答发现缺口，可以触发文档改进；智能体改进文档后，又回到 PR 审批和发布流程。

7. 问答闭环

LLM Wiki 的问答能力不是附加功能，而是文档质量改进的入口。

当用户或智能体提问时，系统基于已发布文档和索引生成答案，并返回引用来源。

如果答案缺少依据、置信度低，或用户反馈答案不正确，系统应该把这个问题转化为文档改进信号：

问题回答失败
  -> 定位缺失或冲突文档
  -> 生成改进任务
  -> 智能体修改 publish/**
  -> PR 审批
  -> 发布
  -> 下次回答变好

这样，问答不只是消费知识，也反向驱动知识库进化。

8. 治理边界

LLM Wiki 必须避免两个极端。

第一个极端是完全手工维护。这样文档无法跟上工程变化，也无法充分利用智能体。

第二个极端是完全自动发布。这样智能体或上游项目的错误会直接进入用户可见知识库。

因此，系统采用中间路线：

• 项目文档自动收集。
• 智能体自动或半自动迭代。
• GitHub PR 负责审计和审批。
• 合并到 main 后才发布。
• 选定的文档展示后端只接受 kunora-docs 的发布结果。

这个治理模型保证了效率和可控性同时存在。

9. 成功故事

当 LLM Wiki 正常运转时，一个典型场景应该是这样的：

1. kunora-agent-memory 更新了产品和架构文档。
2. 项目维护者把稳定文档发布到 docs-publish 分支。
3. kunora-docs 定时任务把这些文档同步到 publish/system/components/kunora-agent-memory/**。
4. 文档迭代智能体发现新内容与 Kgent 的 memory 文档存在交叉，于是补充一篇跨组件说明，并调整相关页面链接。
5. 智能体创建 PR。
6. 审批者确认术语、链接和事实无误后合并。
7. 发布器把文档同步到选定的文档展示后端。
8. 用户在前端提问“Kunora Kgent 如何使用 Agent Memory？”
9. 问答接口返回答案，并引用 Kgent 页面、Agent Memory 页面和跨组件说明。
10. 如果用户反馈答案不完整，系统生成新的文档改进任务，进入下一轮迭代。

这个故事说明：LLM Wiki 的价值不是某一次发布，而是让知识库持续变好。

10. 第一阶段范围

第一阶段不追求完整平台化，但必须打通主链路：

• 从 GitHub 项目 docs-publish 分支收集文档。
• 按配置同步到 publish/**。
• 允许文档迭代智能体修改 publish/**。
• 所有改动走 PR 审批。
• 合并后发布到选定的文档展示后端。
• 为后续前端阅读、编辑和问答 API 留出清晰边界。

11. 后续文档路径

后续按以下顺序继续展开：

1. 蓝图：定义系统结构、生命周期、核心对象和边界。
2. 产品特性：定义人、审批者、项目维护者和智能体可见的能力。
3. 技术特性：定义同步、索引、问答、编辑、发布、权限和审计能力。
4. 技术方案：定义服务架构、接口、数据模型、工作流和部署方式。
5. 产品使用说明：定义用户、项目维护者和智能体如何使用系统。