LLM-WIKI MVP 实现路线图
# LLM-WIKI MVP 实现路线图
1. 文档目标
本文把已经完成的产品设计、技术选型和 MVP 技术协议转化为实现路线图。
路线图只回答“先做什么、做到什么程度、如何验收、什么不做”。它不替代具体技术协议，也不在文档中提前实现代码。
实现路线图的核心目标：
- 用最短路径打通
来源同步 -> PR 审批 -> 展示发布 -> 索引问答 -> 反馈迭代主链路。 - 先稳定 Git、配置、状态和三方 diff，再接入展示、索引、问答和智能体。
- 每个阶段都必须有可运行、可审查、可回滚的交付物。
- 不让 RAGFlow、Meilisearch、Docusaurus 或 GitHub 之间产生第二套事实源。
2. 实现原则
| 原则 | 约束 |
|---|---|
| Git 先行 | 正式内容、配置、状态和审查入口必须先进入 Git 管理。 |
| 协议先行 | 先实现 schema、输入输出和 dry-run，再实现外部副作用。 |
| PR 治理 | 同步、整理、发布都必须通过 PR 或可审查报告，不直写 main。 |
| 小闭环优先 | 每个阶段都要形成一个可验收闭环，而不是只堆模块。 |
| 外部系统后接 | RAGFlow、Meilisearch、Docusaurus 的真实写入放在本地 dry-run 和 manifest 稳定之后。 |
| 人工可绕过 | MVP 允许人工模拟智能体或外部系统输出，但协议和审查链路不能省略。 |
| 失败显式化 | 冲突、无答案、索引失败、发布漂移必须形成报告或 Issue，不能静默忽略。 |
3. MVP 实现总览
MVP 的最小可运行切片不是完整问答体验，而是：
- 至少两个来源项目可通过配置同步到
publish/**。 - 同步结果生成可审查 Draft PR，冲突不会覆盖人工整理内容。
main上已审批内容能构建为 Docusaurus 站点。- 已审批内容能同步到 RAGFlow approved dataset 和 Meilisearch index。
- Answer API 能返回答案、引用或明确无答案。
- Agent Access API 能受控提供 search、ask、get_page、get_context 和反馈入口。
- 文档改进能从 Issue 或任务进入 AgentBridge，并形成 Release PR。
4. 阶段 0：工程骨架与 schema
4.1 目标
建立后续实现的共同语言：目录结构、配置文件、状态文件、schema、命令入口和测试样例。
本阶段不接真实 GitHub PR、不调用 RAGFlow、不写 Meilisearch、不部署 Docusaurus。
4.2 主要工作
| 工作项 | 产物 | 依赖 |
|---|---|---|
| 定义仓库目录结构 | src/、config/、schemas/、state/、publish/、fixtures/、.github/workflows/ 规划 | 产品架构和技术协议 |
| 固化核心 schema | SourceConfig、source-lock、source-changes、publish-impact-report、page-manifest、index-manifest、AnswerResult、IterationTask | 技术协议 |
| 准备 fixtures | 两个 mock source、一个已整理 publish 工作区、冲突样例、删除样例 | SyncEngine 协议 |
| 定义 CLI 命令草案 | config validate、sync dry-run、publish dry-run、index dry-run、answer mock | 控制面技术方案 |
| 明确测试层级 | schema 单测、三方 diff 单测、dry-run 集成测试、workflow smoke test | MVP 验收标准 |
4.3 验收标准
- 所有核心 JSON/YAML schema 有示例和校验命令。
- fixtures 能覆盖新增、更新、保留、冲突、删除和删除冲突。
- 不接外部服务时也能跑通 schema 校验和 dry-run 输出。
- README 或开发文档能说明如何本地执行最小验证。
4.4 不做
- 不实现真实 GitHub PR 创建。
- 不调用真实 RAGFlow、Meilisearch 或 LLM API。
- 不建设前端页面。
5. 阶段 1：配置、工作区与三方同步
5.1 目标
实现 MVP 的地基：config/sources.yaml 驱动来源读取，SyncEngine 按 A/B/C 三方模型把上游文档安全同步到 publish/**。
5.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| ConfigManager | 加载、合并和校验 sources.yaml、publish.yaml、index.yaml | ConfigBundle、配置影响报告 |
| WorkspaceStore | 规范化路径、读取/写入 publish/**、计算内容 hash | DocumentRecord、规范化 hash |
| SyncEngine | 执行 A/B/C 三方 diff | add/update/delete/keep/conflict/delete_conflict |
| State | 维护 state/source-lock.json 和 state/source-changes.json | 同步基线和冲突报告 |
| Safety | 限制写入范围，只允许修改受控 publish/** 和 state/** | 写入边界检查 |
5.3 验收标准
| 场景 | 期望 |
|---|---|
| 上游新增文件，publish 不存在 | 自动写入 publish，记录 add。 |
| 上游更新文件，publish 未修改 | 自动更新 publish，记录 update。 |
| 上游未变，publish 已整理 | 保留 publish，记录 keep。 |
| 上游和 publish 同时修改 | 不覆盖 publish，记录 conflict。 |
| 上游删除，publish 未修改 | 按删除策略删除或生成删除报告。 |
| 上游删除，publish 已整理 | 不删除 publish，记录 delete_conflict。 |
publishPath 冲突 | 配置校验失败，不执行同步。 |
5.4 不做
- 不自动解决冲突。
- 不做智能 rename/move 检测，MVP 按
delete + add处理。 - 不让同步任务触发正式发布。
6. 阶段 2：PR 治理与 发布 dry-run
6.1 目标
把同步结果和发布影响变成 GitHub 可审查单元。先完成 PR body、workflow summary、影响报告和分支策略，再考虑自动化合并或高级治理台。
6.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| ReviewBridge | 创建或更新 Sync Draft PR | docs-sync/source-updates 分支、PR body |
| Publish dry-run | 对 PR 变更生成发布影响报告 | publish-impact-report.json |
| Checks | 在 PR 中展示 schema、sync、build dry-run 状态 | GitHub Actions summary |
| PR Template | 固定同步来源、冲突数量、影响页面、人工处理提示 | Sync PR 模板 |
| Branch Protection | main 禁止直接写入，要求 PR 和必要检查 | GitHub 分支保护配置 |
6.3 验收标准
- 手动触发同步 workflow 后，能生成或更新 Draft PR。
- PR 描述包含来源列表、变更数量、冲突数量、删除影响和人工处理建议。
- PR 检查失败时不会产生误导性的“可发布”状 态。
- 未审批 PR 不能进入
main。
6.4 不做
- 不建设独立审批系统。
- 不让 GitHub Actions 直接合并 PR。
- 不把 Draft Sync PR 当作正式发布 PR。
7. 阶段 3：Docusaurus 展示与 manifest
7.1 目标
让 main 上已审批的 publish/** 能构建为可阅读站点，并生成可对账的发布和展示 manifest。
7.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| DisplayBackend Adapter | 从 publish/** 生成 Docusaurus docs 输入 | 站点文档目录、frontmatter 补充 |
| Navigation | 生成 sidebar 或导航配置 | sidebars.ts 或等价配置 |
| Page Metadata | 聚合来源、版本、hash、质量状态和编辑入口 | page-manifest.json |
| Publish Manifest | 记录本次发布的 commit、页面、URL、contentHash | publish-manifest.json |
| Site Manifest | 记录构建后的 URL、 状态、sourceHash、renderedHash | site-manifest.json |
| Drift Check | 比较 publish/site/index 状态 | 漂移检测报告 |
7.3 验收标准
main中至少一个publish/**页面能构建成可访问文档页面。- 页面 URL、内容 hash、来源信息能进入 manifest。
- 删除页面能在影响报告中显式列出。
- Docusaurus 构建失败时，不更新成功态 manifest。
7.4 不做
- 不把 Docusaurus 作为内容事实源。
- 不在 Docusaurus 后台编辑受管页面。
- 不实现完整在线编辑器，MVP 只保留 GitHub PR 编辑路径。
8. 阶段 4：RAGFlow / Meilisearch 索引
8.1 目标
把已审批、已发布或可发布的文档同步到 RAGFlow approved dataset 和 Meilisearch，并用 index manifest 记录状态。
8.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| RAGFlow Adapter | upsert/delete approved 文档 | RAGFlow dataset 同步结果 |
| Meilisearch Adapter | upsert/delete 搜索文档 | Meilisearch index 同步结果 |
| Metadata Mapping | 统一 documentId、path、url、title、sourceProject、contentHash | 索引文档结构 |
| Index Manifest | 记录每个 target 的状态、数量、错误和时间 | index-manifest.json |
| Delete Sync | 根据 publish manifest 同步删除 | 删除报告 |
| Retry / Idempotency | 用 documentId + contentHash 控制重复 upsert | 可重试索引流程 |
8.3 验收标准
- 同一份已审批文档能进入 RAGFlow approved dataset 和 Meilisearch。
- 重复运行索引不会产生重复文档。
- 删除页面后，RAGFlow 和 Meilisearch 不再召回已删除内容。
- RAGFlow 或 Meilisearch 失败时，Git 内容不回滚，但 index manifest 标记失败。
8.4 不做
- 不建设独立向量数据库产品。
- 不让 Meilisearch 参与答案事实链。
- 不让 RAGFlow 修改 Git 正式内容。
9. 阶段 5：Answer API 与 Agent Access
9.1 目标
为人和智能体提供稳定、受控、可审计的知识访问入口。Answer API 是 RAGFlow 问答能力的薄封装，Agent Access API 是工具化访问层。
9.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| Answer API | ask、session、引用标准化、无答案处理 | AnswerResult |
| Agent Access API | search、ask、get_page、get_context、create_feedback、create_improvement_task | 工具化 HTTP API |
| Policy | token 到 agent identity、allowed tools、allowed paths、allowed datasets 的映射 | agent-access.yaml 或等价配置 |
| ContextPack | 聚合页面、片段、引用、质量状态和 scope | ContextPack |
| Feedback Bridge | 无答案、低置信、错误答案转 GitHub Issue | 反馈 Issue / 改进任务 |
| Audit | 记录 requestId、caller、scope、tool、结果和错误 | 调用审计日志 |
9.3 验收标准
| 场景 | 期望 |
|---|---|
| 页面内提问 | 返回 answer、citations、confidence 或 noAnswerReason。 |
| 证据不足 | 不编造答案，返回无答案和反馈动作。 |
| 智能体越权访问 path | 返回 forbidden_scope 并记录审计。 |
| 智能体调用未授权工具 | 返回 forbidden_tool。 |
| 搜索关键词 | Meilisearch 返回标题、路径、片段和可问答 scope。 |
| 创建反馈 | 使用 dedupeKey 避免重复 Issue。 |
9.4 不做
- 不让 Answer API 重新实现 RAG 引擎。
- 不让 Agent Access API 直接生成第二套答案。
- 不允许调用方声明 scope 后自动获得授权。
- 不默认开放 working docs 给普通问答。
10. 阶段 6：AgentBridge 文档迭代闭环
10.1 目标
让反馈、Issue 或人工任务能进入文档迭代流程；RAGFlow 生成结构化建议，AgentBridge 校验后转成 Git diff 和 Release PR。
10.2 主要工作
| 模块 | 工作项 | 产物 |
|---|---|---|
| IterationTask | 从 Issue、人工 命令或质量事件生成任务 | IterationTask |
| RAGFlow Integration | 调用 RAGFlow 文档迭代工作流 | RagflowIterationResult |
| Validation | 校验 path、action、baseHash、evidence、allowedActions | 拒绝报告 / 通过报告 |
| Patch Apply | 支持 whole-file，保留 patch 扩展点 | Git diff |
| Release PR | 创建 docs-release/* 分支和 PR | Release PR body |
| AgentBridge Report | 记录 taskId、变更数量、拒绝项、错误 | AgentBridgeReport |
10.3 验收标准
- 一个无答案 Issue 能生成受限 scope 的
IterationTask。 - RAGFlow 返回的修改建议必须带 reason 和 evidence。
baseHash不匹配时拒绝写入，标记并发变更。- 合法修改只能写入任务授权的
publish/**路径。 - Release PR 包含 what、why、risk、citations、impact 和相关 Issue。
10.4 不做
- 不允许 RAGFlow 直接 push main。
- 不允许 AgentBridge 自动批准或合并 PR。
- 不允许无引用补全事实性内容。
- 不把任务完成等同于文档发布完成。
11. 阶段依赖矩阵
| 阶段 | 依赖 | 阻塞后续 |
|---|---|---|
| 阶段 0 | 无 | 所有实现都依赖 schema 和 fixtures。 |
| 阶段 1 | 阶段 0 | 发布、索引、问答都依赖稳定 publish/** 和 state。 |
| 阶段 2 | 阶段 1 | 没有 PR 治理就不能接自动发布和智能体改写。 |
| 阶段 3 | 阶段 2 | 索引和引用回跳依赖页面 URL 与 manifest。 |
| 阶段 4 | 阶段 3 | Answer API 和 Agent Access 依赖索引和引用 metadata。 |
| 阶段 5 | 阶段 4 | 反馈闭环和智能体任务依赖受控访问层。 |
| 阶段 6 | 阶段 1、2、5 | AgentBridge 需要工作区、PR 治理和任务来源。 |
AgentBridge 可以提前做 mock 输入验证，但不能在 ReviewBridge 和 WorkspaceStore 稳定前接真实写入。
12. MVP 验收清单
| 能力 | 最低验收 |
|---|---|
| 来源同步 | 至少两个来源项目从固定 ref 同步到不同 publishPath。 |
| 三方 diff | 覆盖 add/update/delete/keep/conflict/delete_conflict。 |
| 配置治理 | 配置变更可校验、可审查、可生成影响报告。 |
| PR 治理 | 同步和发布变更都通过 PR，不直写 main。 |
| 发布展示 | main/publish/** 能构建成 Docusaurus 页面。 |
| Manifest | publish、site、index 状态可通过 manifest 对账。 |
| 搜索 | Meilisearch 能按标题、路径、标签、片段搜索。 |
| 问答 | RAGFlow 结果经 Answer API 标准化，答案有引用或明确无答案。 |
| 智能体访问 | Agent Access API 对工具、scope、path、dataset 做服务端授权。 |
| 反馈闭环 | 无答案或错误答案能创建去重 Issue。 |
| 智能体迭代 | RAGFlow 建议能经 AgentBridge 变成 Release PR。 |
| 审计排障 | 每次同步、发布、索引、问答和 agent 调用有 request/run id。 |
13. 风险与处理
| 风险 | 处理 |
|---|---|
| 三方 diff 实现不严谨导致覆盖人工整理 | 先做 fixtures 和冲突单测，冲突默认不覆盖。 |
| RAGFlow 与 Meilisearch 事实边界混淆 | RAGFlow 负责问答事实链，Meilisearch 只做人用关键词搜索。 |
| manifest 与真实发布状态漂移 | 每次发布和索引都记录 commit、hash、target status，并提供 drift check。 |
| Agent 输出越权修改 | AgentBridge 校验 path、action、baseHash、evidence 和 allowedActions。 |
| 无答案反馈重复刷 Issue | 使用 dedupeKey 和 idempotencyKey。 |
| 外部服务不可用阻塞内容治理 | Git 内容和 PR 流程独立；索引、问答失败只标记状态，不回滚内容。 |
| scope 被调用方伪造 | scope 只作为请求，授权事实来自服务端 policy。 |
14. 进入编码前的文档补充
完成本路线图后，建议在编码前再补两类文档：
- 仓库物理结构设计：明确
src/、config/、schemas/、state/、publish/、fixtures/、workflow 和部署目录。 - schema 索引：把所有协议中的 JSON/YAML 对象集中列出，避免实现阶段字段名漂移。
这两类文档完成后，MVP 可以从阶段 0 和阶段 1 开始进入实现。