LLM-WIKI 产品架构设计
1. 设计目标
本文定义 LLM-WIKI 需要哪些产品支撑，以及这些产品之间的关系、数据流和控制流。
本文只做产品架构设计，不做具体技术选型。除 GitHub 外，所有组件均定义为产品能力或产品模块，具体实现留到技术方案阶段。
2. 产品架构总览
LLM-WIKI 由以下产品组成：
| 产品 | 类型 | 作用 |
|---|---|---|
| GitHub 文档源 | 外部软件产品 | 承载各项目稳定文档来源 |
| LLM-WIKI 控制仓库 | 软件产品 | 管理发布工作目录、配置、状态、PR 和发布记录 |
| 文档收集器 | 软件产品 | 从 GitHub 文档源同步文档到发布工作目录 |
| 发布工作目录 | 数据产品 | 承载被收集、被迭代、被发布的文档 |
| 文档迭代智能体 | 软件产品 | 基于发布 工作目录改进文档 |
| 审批与治理台 | 软件产品 | 通过 PR 管理文档审批、审计和回滚 |
| 文档展示产品 | 软件产品 | 给人提供文档阅读、导航和展示 |
| 文档编辑产品 | 软件产品 | 给人提供文档编辑和变更提交入口 |
| 知识索引产品 | 软件产品 | 将已审批文档转化为可检索知识 |
| 问答产品 | 软件产品 | 给人和智能体提供基于文档的问题答案 |
| 智能体访问产品 | 软件产品 | 给外部智能体提供受控的文档、检索、问答、上下文包和反馈接口 |
| 反馈与任务产品 | 软件产品 | 将问答失败、用户反馈转化为文档改进任务 |
| 权限与身份产品 | 软件产品 | 管理人、智能体、系统任务的访问边界 |
| 配置管理产品 | 软件产品 | 管理来源、发布、索引、问答和权限配置 |
| 运行基础设施 | 硬件/基础设施产品 | 承载定时任务、服务、存储、计算和网络 |
产品关系：
GitHub 文档源
-> 文档收集器
-> LLM-WIKI 控制仓库 / 发布工作目录
-> 文档迭代智能体
-> 审批与治理台
-> 文档展示产品
-> 知识索引产品
-> 问答产品
-> 智能体访问产品
-> 反馈与任务产品
-> 文档迭代智能体
3. 产品边界
3.1 GitHub 文档源
GitHub 文档源是上游项目提供文档材料的地方。
确定约束：
- 使用 GitHub。
- 每个来源项目通过
docs-publish分支暴露稳定文档。 - 默认文档目录为
docs/**。
不承担：
- 不直接发布到文档展示产品。
- 不决定最终知识库结构。
- 不参与问答索引。
3.2 LLM-WIKI 控制仓库
LLM-WIKI 控制仓库是产品治理中心。
它保存：
- 来源配置。
- 发布工作目录。
- 同步状态。
- 发布状态。
- 文档变更历史。
- 审批记录。
它是整个系统的权威内容源。
3.3 文档收集器
文档收集器负责把上游项目文档收集到发布工作目录。
它只做确定性同步：
- 新增。
- 更新。
- 删除。
- 冲突检测。
它不做：
- 文档理解。
- 内容改写。
- 页面重组。
- 质量判断。
3.4 发布工作目录
发布工作目录是 LLM-WIKI 的核心数据产品。
它同时是：
- 文档收集器的写入目标。
- 文档迭代智能体的工作空间。
- 审批者查看 diff 的对象。
- 文档展示产品的发布来源。
- 知识索引产品的索引来源。
3.5 文档迭代智能体
文档迭代智能体负责让知识库变好。
它读取：
- 发布工作目录。
- 问答反馈。
- 文档改进任务。
- 可用的检索上下文。
它输出：
- 文档变更。
- 改进说明。
- PR 或可审查变更集。
3.6 审批与治理台
审批与治理台负责文档变更的审查和合并。
产品上它可以复用 GitHub PR，也可以在前端中聚合展示 PR 状态。但治理事实仍然以 GitHub 为准。
3.7 文档展示产品
文档展示产品给人提供阅读入口。
它可以是 Wiki 类产品、自研 Docs 前端或其他文档展示系统。蓝图不绑定具体选型。
它不是权威内容源。
3.8 文档编辑产品
文档编辑产品给人提供编辑入口。
它可以表现为：
- 在线 Markdown 编辑。
- 页面改进建议。
- 发起编辑请求。
- 生成 PR。
编辑结果必须进入治理流程，不直接修 改生产知识库。
3.9 知识索引产品
知识索引产品将审批后的文档转化为可检索知识。
它产生的是派生数据，不是权威内容。
3.10 问答产品
问答产品基于文档和索引回答问题。
它服务两类对象：
- 人。
- 智能体。
答案需要尽量可追溯，能够说明引用了哪些文档。
3.11 智能体访问产品
智能体访问产品负责让外部智能体把 LLM-WIKI 当作可信知识工具使用。
它服务的不是文档迭代智能体本身，而是任何需要消费 LLM-WIKI 知识的智能体。
它提供：
- 文档读取。
- 结构化检索。
- 问答。
- 页面元数据。
- 面向任务的上下文包。
- 引用和版本信息。
- 反馈和文档改进任务入口。
它不允许：
- 直接写
publish/**。 - 直接写
main。 - 直接发布到展示后端。
- 绕过 PR 创建正式文档改动。
3.12 反馈与任务产品
反馈与任务产品把问答结果和用户反馈转化为改进任务。
它连接问答产品和文档迭代智能体。
3.13 权限与身份产品
权限与身份产品负责定义谁可以读取、编辑、审批、发布和调用问答接口。
它覆盖三类主体：
- 人。
- 智能体。
- 系统任务。
权限与身份产品必须防止智能体、前端编辑器或自动任务绕过治理边界。
3.14 配置管理产品
配置管理产品负责管理 LLM-WIKI 的运行配置。
它管理：
- 来源配置。
- 发布路径配置。
- 展示后端配置。
- 索引策略配置。
- 问答策略配置。
- 权限策略配置。
配置本身也应进入 Git 管理，避免运行行为不可审计。
3.15 运行基础设施
运行基础设施支撑所有软件产品运行。
它包含但不限定：
- 计算资源。
- 存储资源。
- 网络资源。
- 定时任务运行环境。
- 密钥管理。
- 日志和监控。
本文不指定具体硬件或云厂商。
4. 数据流
4.1 文档收集数据流
GitHub 文档源
-> 文档收集器读取 repo/ref/sourcePath
-> 三方 diff
-> 写入发布工作目录
-> 写入同步状态
-> 创建或更新同步 PR
数据对象：
- Source Doc。
- Source Baseline。
- Collected Doc。
- Sync Change。
- Sync Conflict。
4.2 文档迭代数据流
发布工作目录
-> 文档迭代智能体读取
-> 智能体生成文档变更
-> 写回发布工作目录
-> 创建 release PR
-> 审批与治理台审查
数据对象：
- Collected Doc。
- Iteration Task。
- Iterated Doc。
- Document Change。
- Release PR。
4.3 发布数据流
已审批 release PR
-> 合并到 main
-> 发布器读取发布工作目录
-> 生成 dry-run 发布计划
-> 执行真实发布
-> 写入发布 manifest
-> 文档展示产品可见
数据对象：
- Reviewed Doc。
- Publish Plan。
- Published Page。
- Publish Manifest。
4.4 索引数据流
已审批/已发布文档
-> 知识索引产品
-> 文档切片
-> 元数据和引用关系
-> 检索索引
数据对象：
- Published Doc。
- Knowledge Chunk。
- Metadata。
- Citation。
- Index Record。
4.5 问答数据流
人或智能体提问
-> 问答产品
-> 检索相关知识
-> 生成答案
-> 返回引用
-> 接收反馈
-> 生成文档改进任务
数据对象：
- Question。
- Retrieved Context。
- Answer。
- Citation。
- Feedback。
- Iteration Task。
4.6 智能体访问数据流
外部智能体执行任务
-> 智能体访问产品校验 caller / scope / tool
-> 调用搜索、问答、页面读取或上下文包能力
-> 返回结构化结果、引用、版本和审计信息
-> 必要时创建反馈或改进任务
数据对象：
- Agent Access Request。
- Scope。
- Tool Call。
- Context Pack。
- Citation。
- Audit Record。
- Feedback。
5. 控制流
5.1 定时控制流
定时触发
-> 文档收集器
-> 同步发布工作目录
-> 生成同步报告
-> 创建 draft PR
控制目标：
- 保持上游文档材料进入 LLM-WIKI。
- 不自动进入正式发布。
5.2 智能体控制流
任务触发
-> 文档迭代智能体读取上下文
-> 修改发布工作目录
-> 生成变更说明
-> 创建 release PR
触发来源：
- 人工创建任务。
- 问答反馈。
- 同步 PR。
- 定期质量检查。
5.3 审批控制流
release PR 创建
-> 审批者查看 diff
-> 请求修改或批准
-> 合并 main
控制目标：
- 保证所有正式内容变更都经过人审。
5.4 发布控制流
main 变更
-> 发布 dry-run
-> 发布条件满足
-> 执行发布
-> 记录发布状态
控制目标：
- 只发布经过审批的内容。
- 发布失败时中断并可追踪。
5.5 问答反馈控制流
答案反馈
-> 判断是否需要文档改进
-> 创建改进任务
-> 进入智能体控制流
控制目标：
- 让知识消费反向驱动知识生产。
5.6 智能体访问控制流
智能体调用工具
-> 校验身份和 scope
-> 读取已授权知识或生成上下文包
-> 返回可引用结果
-> 写入类动作转为 Issue / 任务 / PR 草稿
控制目标：
- 让智能体可以使用知识。
- 防止智能体绕过 GitHub PR 改写正式内容。
- 保留调用审计。
6. 产品间关系
| 上游产品 | 下游产品 | 关系 |
|---|---|---|
| GitHub 文档源 | 文档收集器 | 提供稳定文档材料 |
| 文档收集器 | 发布工作目录 | 执行三方 diff 写入 |
| 发布工作目录 | 文档迭代智能体 | 提供可迭代文档 |
| 文档迭代智能体 | 审批与治理台 | 提交可审查变更 |
| 审批与治理台 | 发布工作目录 | 合并已审批文档 |
| 发布工作目录 | 文档展示产品 | 提供发布来源 |
| 发布工作目录 | 知识索引产品 | 提供索引来源 |
| 知识索引产品 | 问答产品 | 提供检索上下文 |
| 知识索引产品 | 智能体访问产品 | 提供可检索知识 |
| 问答产品 | 智能体访问产品 | 提供 ask 能力 |
| 智能体访问产品 | 反馈与任务产品 | 创建反馈和改进任务 |
| 问答产品 | 反馈与任务产品 | 输出问题和反馈 |
| 反馈与任务产品 | 文档迭代智能体 | 触发新一轮文档改进 |
| 权限与身份产品 | 所有产品 | 提供访问控制和主体识别 |
| 配置管理产品 | 文档收集器/发布系统/问答产品 | 提供可审计运行配置 |
7. 产品架构不变量
- GitHub 是确定的治理底座。
- 除 GitHub 外，不在产品架构层绑定具体软件选型。
- 发布工作目录是系统协作中心。
- 文档展示产品不是权威内容源。
- 问答产品不是权威内容源。
- 智能体不是发布审批者。
- 所有正式文档发布必须可追溯。
- 所有用户可见答案必须尽量可引用。
- 所有写操作必须有明确主体和权限边界。
- 所有运行配置必须可审计。
8. 第一阶段产品架构范围
第一阶段只要求打通核心闭环：
GitHub 文档源
-> 文档收集器
-> 发布工作目录
-> 文档迭代智能体
-> 审批与治理台
-> 文档展示产品
-> 知识索引产品
-> 问答产品 / 智能体访问产品
问答产品、智能体访问产品、反馈与任务产品、权限与身份产品、配置管理产品可以先定义接口边界，再逐步实现。
9. 产品分阶段边界
第一阶段不是把所有产品都做完整，而是按主链路分层落地。
| 产品 | 第一阶段形态 | 原因 |
|---|---|---|
| GitHub 文档源 | 完整接入 | 治理底座和来源约束必须先稳定 |
| LLM-WIKI 控制仓库 | 完整接入 | 所有流程依赖配置、状态和 Git 历史 |
| 文档收集器 | 完整接入 | 主链路第一步 |
| 发布工作目录 | 完整接入 | 系统协作中心 |
| 文档迭代智能体 | 半自动接入 | 允许先由智能体或人工辅助修改文档 |
| 审批与治理台 | 复用 GitHub PR | 避免过早自建审批产品 |
| 文档展示产品 | 最小可发布 | 只要求能展示审批后的内容 |
| 文档编辑产品 | 接口边界 | MVP 可先通过 PR 或本地编辑完成 |
| 知识索引产品 | 接口边界 | 先定义输入输出，后续增强检索质量 |
| 问答产品 | 接口边界 | 先定义问答契约，后续完善体验 |
| 智能体访问产品 | 接口边界 | MVP 至少定义工具集合、scope、上下文包和反馈入口 |
| 反馈与任务产品 | 轻量接入 | 先记录反馈和任务，不要求完整任务系统 |
| 权限与身份产品 | 最小边界 | 至少区分人、智能体、系统任务 |
| 配置管理产品 | Git 配置文件 | 不单独建设配置后台 |
| 运行基础设施 | 最小运行环境 | 支撑定时、脚本、发布即可 |
10. 架构成立标准
产品架构成立需要满足：
- 每个产品职责清晰。
- 数据流能闭环。
- 控制流能保证审批。
- GitHub 之外没有提前绑定技术选型。
- 文档收集不会覆盖智能体改动。
- 文档展示产品可替换。
- 问答结果可追溯。
- 智能体可以通过受控接口消费知识。
- 反馈能回到文档迭代。
- 写入权限不会绕过 PR 治理。
- 配置变化本身可审查。