LLM-WIKI 产品特性设计
# LLM-WIKI 产品特性设计
1. 设计目标
本文基于产品架构设计，对每个独立产品定义产品特性，并说明每个特性的 What 和 Why。
在完成 MVP 技术方案后，本文同时承担特性落地推演职责：对已经明确 MVP 路径的特性，补充对应技术产品、实现路径、验收方式和边界约束。
2. 特性优先级定义
本文使用三个优先级：
| 优先级 | 含义 |
|---|---|
| P0 | MVP 必须具备，否则主链路不成立 |
| P1 | 第一阶段建议具备，缺失时可人工绕过 |
| P2 | 后续增强，MVP 不依赖 |
P0 的判断标准：是否影响 收集 -> 迭代 -> 审批 -> 发布 主链路闭合。
3. GitHub 文档源
3.1 稳定文档发布分支
What：每个来源项目提供 docs-publish 分支，并在该分支的 docs/** 下提供稳定文档。
Why：避免从开发分支收集半成品文档，保证进入 LLM-WIKI 的材料是项目认可的稳定版本。
落地推演：
- 技术产品：GitHub。
- 实现路径：在所有来源仓库建立或维护
docs-publish分支，LLM-WIKI 的sources.yaml只读取该分支或明确配置的发布 ref。 - 验收方式：同步任务能从
docs-publish:docs/**读取文档，main 分支变化不会被误收集。 - 边界/风险：来源分支由上游项目负责，LLM-WIKI 不替上游判断哪些内容稳定。
3.2 项目级文档自治
What：每个项目自行维护自己的文档结构和内容。
Why：LLM-WIKI 不强迫上游项目采用统一结构，降低接入成本。
落地推演：
- 技术产品：GitHub + LLM-WIKI 文档收集器。
- 实现路径：收集器按
sourcePath整目录读取，不要求上游调整内部目录、标题和页面组织。 - 验收方式：任一来源项目保持自有 docs 结构时仍可同步到指定
publishPath。 - 边界/风险：项目自治不代表最终发布结构不整理；整理发生在
publish/**和 PR 流程中。
4. LLM-WIKI 控制仓库
4.1 来源配置管理
What：通过配置声明来源仓库、来源 ref、来源目录和发布工作目录。
Why：让文档收集规则显式、可审查、可扩展。
落地推演：
- 技术产品：LLM-WIKI 控制面 + YAML 配置。
- 实现路径：用
config/sources.yaml声明 repo、ref、sourcePath、publishPath、include/exclude 和冲突策略。 - 验收方式：新增来源只需提交配置 PR，合并后同步任务可识别该来源。
- 边界/风险：配置变更必须走 PR；不允许运行时手工改配置绕过审计。
4.2 发布工作目录管理
What：控制仓库维护 publish/**，作为文档收集、智能体迭代和发布输入的统一工作目录。
Why：所有文档状态都能被 Git 管理、审查和回滚。
落地推演：
- 技术产品：GitHub +
publish/**。 - 实现路径：控制仓库把
publish/**作为收集、迭代、发布、索引的统一事实工作区。 - 验收方式：同步结果、智能体改动和人工改动都能在
publish/**中形成 Git diff。 - 边界/风险：
publish/**不是 缓存目录，收集器不能无条件覆盖。
4.3 状态记录
What：记录来源 commit、文件 hash、同步动作、冲突、发布状态。
Why：支持审计、故障排查和三方同步。
落地推演：
- 技术产品：LLM-WIKI 控制面 + state 文件。
- 实现路径：维护
state/source-lock.json、同步报告、发布 manifest 和索引 manifest。 - 验收方式：可以追溯每个文件来自哪个来源 ref、hash、同步动作和发布状态。
- 边界/风险：状态文件要可重建；不能让状态文件成为唯一内容事实源。
5. 文档收集器
5.1 定时收集
What：按固定周期从来源项目收集文档。
Why：让工程文档变化能自动进入 LLM-WIKI 工作区。
落地推演：
- 技术产品：GitHub Actions + 文档收集器。
- 实现路径：通过
docs-sync.yml的 schedule 定时运行收集器。 - 验收方式：到达周期后自动检查来源变化并生成同步结果。
- 边界/风险：定时收集只创建同步 PR，不直接发布。
5.2 手动收集
What：允许用户手动触发收集。
Why：支持紧急文档更新和调试。
落地推演：
- 技术产品：GitHub Actions workflow_dispatch。
- 实现路径：在
docs-sync.yml提供手动触发入口，允许维护者按需收集。 - 验收方式：维护者可从 GitHub UI 手动触发，并在日志中看到结果。
- 边界/风险：手动触发仍遵守同样的配置、冲突和 PR 规则。
5.3 三方 diff 同步
What：基于上次来源基线、当前上游来源、当前发布工作目录判断新增、更新、删除和冲突。
Why：避免自动同步覆盖智能体或人工改动。
落地推演：
- 技术产品：LLM-WIKI SyncEngine。
- 实现路径：基于上次来源基线 A、当前来源 B、当前发布工作目录 C 执行三方 diff。
- 验收方式：能区分新增、更新、删除、保留和冲突，且不会覆盖已整理内容。
- 边界/风险：当前文件级同步脚本需要升级到真正三方 diff 后才算完全满足。
5.4 同步冲突报告
What：当上游和发布工作目录同时修改同一文件时，生成冲突报告。
Why：把风险显式暴露给人，而不是静默覆盖。
落地推演：
- 技术产品：LLM-WIKI SyncEngine + GitHub PR。
- 实现路径：冲突时生成结构化报告，写入 PR 描述或报告文件。
- 验收方式：同一文件上游和
publish/**同时变化时，PR 明 确标记 conflict。 - 边界/风险：冲突不能静默解决；需要人工或后续智能体辅助处理。
5.5 Draft PR
What：收集结果通过 draft PR 展示。
Why：区分“材料已收集”和“内容已准备发布”，避免自动收集被误认为正式发布。
落地推演：
- 技术产品：GitHub Pull Requests。
- 实现路径：同步任务把收集结果推到
docs-sync/source-updates并创建 draft PR。 - 验收方式：维护者能在 PR 中查看 diff、来源、冲突和影响路径。
- 边界/风险：Draft PR 表示材料收集完成，不表示可发布。
6. 发布工作目录
6.1 项目映射目录
What：每个来源项目同步到配置指定的 publishPath。
Why：让来源和工作目录之间关系清晰，避免项目之间互相覆盖。
落地推演：
- 技术产品：
sources.yaml+publish/**。 - 实现路径：每个来源通过
publishPath映射到独立目录。 - 验收方式：两个来源项目同步后不会互相覆盖，目录关系可从配置追溯。
- 边界/风险：发布目录由配置决定，不能由上游目录名隐式决定。
6.2 可迭代文档空间
What：智能体和人可以在发布工作目录中修改文档。
Why：让项目文档能被整理成更适合知识库消费的内容。
落地推演：
- 技术产品：Git + RAGFlow + 人工编辑。
- 实现路径：智能体和人只在
publish/**中整理文档，结果进入分支和 PR。 - 验收方式：整理后的页面可被 Docusaurus、RAGFlow 和 Meilisearch 使用。
- 边界/风险：智能体可以修改工作区，但不能绕过 PR 发布。
6.3 Git 可审查变更
What：发布工作目录中的所有变化都表现为 Git diff。
Why：让文档变更可审查、可回滚、可追踪。
落地推演：
- 技术产品：GitHub diff + PR。
- 实现路径：所有
publish/**变化都通过 Git diff 表达。 - 验收方式：审批者能看到文件级差异、提交者和 PR 讨论。
- 边界/风险：二进制资源需谨慎处理，尽量保留可审查元数据。
7. 文档迭代智能体
7.1 文档整理
What：智能体整理标题、结构、链接、重复 内容和术语。
Why：上游项目文档通常不是最终知识库形态，需要转化。
落地推演：
- 技术产品：RAGFlow Agent + LLM-WIKI AgentBridge + GitHub PR。
- 实现路径：RAGFlow 只负责读取任务上下文并输出结构化整理建议或内容草稿；LLM-WIKI AgentBridge 负责校验输出、写入分支、生成 Git diff 并创建 Release PR。
- 验收方式：文档整理结果能形成 Release PR，并附带变更说明、引用依据和 AgentBridge 转换日志。
- 边界/风险：RAGFlow 不是 Git 治理系统，也不是审批者；不能表述为 RAGFlow 原生生成 Git diff 或直接发布。
7.2 文档补全
What：智能体根据缺口补充 FAQ、说明、跨项目关系和使用路径。
Why：提高知识库完整性，减少用户问题无法回答的情况。
落地推演：
- 技术产品：RAGFlow Agent + RAGFlow dataset。
- 实现路径：根据知识缺口、相关文档和问答失败补充 FAQ、说明和跨项目关系。
- 验收方式：补全文档必须附带理由和引用依据。
- 边界/风险：不得无依据补全；证据不足时应生成问题而非直接写结论。
7.3 基于反馈迭代
What：智能体读取问答失败和用户反馈，生成文档改进。
Why：让知识消费反向驱动知识生产。
落地推演：
- 技术产品：GitHub Issues + RAGFlow Agent。
- 实现路径：反馈和无答案记录转为 Issue，触发或辅助 RAGFlow 文档迭代。
- 验收方式：Issue 能关联问题、引用、失败原因和后续 Release PR。
- 边界/风险：反馈不是自动发布指令，只是改进信号。
7.4 变更说明生成
What：智能体为修改生成说明，包括改了什么、为什么改、风险是什么。
Why：降低审批者理解 PR 的成本。
落地推演：
- 技术产品：RAGFlow Agent + PR 模板。
- 实现路径：AgentBridge 要求 RAGFlow 输出 summary、changed files、reason、risk 和 citations。
- 验收方式：Release PR 描述能说明改了什么、为什么改、风险是什么。
- 边界/风险：没有结构化说明的输出应标记失败或要求重试。
7.5 Release PR 创建
What：智能体完成改动后创建或更新 release PR。
Why：保证智能体结果进入人工审批，而不是直接发布。
落地推演：
- 技术产品：GitHub Pull Requests + AgentBridge。
- 实现路径：智能体改动写入
docs-release/*分支并创建 Release PR。 - 验收方式：每次智能体改动都有可审查 PR。
- 边界/风险：禁止智能体直接 push main 或直接触发正式发布。
8. 审批与治理台
8.1 PR 审批
What：审批者通过 PR 审查文档变更。
Why：保证正式知识库内容由人最终把关。
落地推演：
- 技术产品：GitHub PR + branch protection。
- 实现路径：main 分支启用 PR 审批和状态检查。
- 验收方式：未审批 PR 不能合并到 main。
- 边界/风险：MVP 不自建审批系统，治理事实以 GitHub 为准。
8.2 变更来源识别
What：展示哪些变更来自上游收集，哪些来自智能体，哪些来自人工。
Why：帮助审批者判断风险和审查重点。
落地推演：
- 技术产品：LLM-WIKI 控制面 + PR 模板。
- 实现路径：在 PR 描述中标明变更来源：上游同步、智能体、人工、配置。
- 验收方式：审批者能快速识别每类变更的责任主体。
- 边界/风险：来源识别依赖提交元数据和工具规范，需避免人工随意覆盖。
8.3 发布影响预览
What：展示本次 PR 合并后会影响哪些文档页面。
Why：避免审批者只看到文件 diff，看不到用户侧影响。
落地推演：
- 技术产品：发布 dry-run + Docusaurus build。
- 实现路径：PR 或 main workflow 生成发布计划、影响页面和构建结果。
- 验收方式：审批者能看到新增、更新、删 除页面和构建是否通过。
- 边界/风险：MVP 可先用文本报告，不要求完整可视化治理台。
8.4 回滚能力
What：支持通过 Git 历史回滚错误文档变更。
Why：降低错误发布的长期影响。
落地推演：
- 技术产品：GitHub revert + 发布 manifest。
- 实现路径：通过 Git revert 或回滚到上一个发布 manifest 恢复内容。
- 验收方式：错误发布后能定位发布版本并回滚。
- 边界/风险：回滚仍应走治理流程，紧急处理需记录原因。
8.5 发布审批状态
What：展示 PR 当前是否处于草稿、待审、需修改、已批准、已合并状态。
Why：让文档发布进度对人和智能体都可见。
落地推演：
- 技术产品：GitHub checks + 发布 manifest。
- 实现路径：记录 PR、构建、发布、索引状态。
- 验收方式：维护者能知道文档处于待审、已合并、已发布、索引完成或失败状态。
- 边界/风险：状态展示不能替代 GitHub 审批事实。
8.6 展示层漂移检测
What：检测文档展示后端中的受管页面是否偏离 Git 中的审批版本。
Why：防止展示层后台手工修改造成 Git 和用户可见内容不 一致。
落地推演：
- 技术产品：发布后端 adapter + manifest diff。
- 实现路径：比较
main/publish/**、发布 manifest 和展示后端状态。 - 验收方式：发现展示后端页面与 Git 内容不一致时产生告警或报告。
- 边界/风险：MVP Docusaurus 静态站漂移风险较低，但仍需 manifest。
9. 文档展示产品
9.1 文档阅读
What：用户可以阅读审批后发布的文档。
Why：这是知识库最基础的消费场景。
落地推演：
- 技术产品：Docusaurus。
- 实现路径：从
publish/**构建静态文档站。 - 验收方式：审批后的 Markdown 能生成可访问页面。
- 边界/风险：Docusaurus 只展示内容，不是权威编辑源。
9.2 导航浏览
What：用户可以通过目录、项目、主题浏览文档。
Why：帮助用户在复杂知识结构中定位内容。
落地推演：
- 技术产品：Docusaurus sidebar + 控制面生成器。
- 实现路径：根据发布目录和元数据生成导航。
- 验收方式：用户能按组件、主题或目录浏览文档。
- 边界/风险：导航生成规则应可配置，避免完全依赖文件名。
9.3 页面元信息
What：页面展示来源、更新时间、版本、相关页面和发布状态。
Why：让用户知道文档是否可信、是否过期、从哪里来。
落地推演：
- 技术产品：Docusaurus + 控制面 page manifest + 页面 frontmatter。
- 实现路径：控制面从 source lock、Git 历史、发布 manifest、反馈任务和索引状态生成页面元信息，构建期注入 Docusaurus 页面。
- 验收方式：页面能展示来源项目、版本、更新时间、质量状态、反馈状态和发布状态，并能追溯到 manifest。
- 边界/风险：Docusaurus 只负责展示；动态治理状态不能只依赖手写 frontmatter。
9.4 反馈入口
What：用户可以对页面提出问题、纠错或改进建议。
Why：让阅读过程产生文档改进信号。
落地推演：
- 技术产品：Docusaurus 前端 + GitHub Issues。
- 实现路径：页面反馈按钮创建结构化反馈或 GitHub Issue。
- 验收方式：用户能在页面上下文中提交问题，Issue 带页面路径。
- 边界/风险：反馈入口不能直接修改页面。
9.5 页面内问答入口
What：用户可以在当前文档页面直接提问，默认以当前页面及其相关页面作为上下文。
Why：用户阅读时的问题通常和当前页面相关，页面内问答能减少跳转成本，并提高答案相关性。
落地推演：
- 技术产品：Docusaurus 组件 + Agent Access/Answer API。
- 实现路径：页面内挂载问答组件，调用受控 API。
- 验收方式：用户能在当前页面或 scope 内提问。
- 边界/风险：前端不直接调用底层 RAGFlow key，应通过 wrapper。
9.6 引用回跳
What：页面中展示的答案、相关内容和搜索结果可以回跳到具体文档位置。
Why：用户需要从答案回到原文验证依据，避免只消费不可追溯的摘要。
落地推演：
- 技术产品：RAGFlow citations + Docusaurus anchors。
- 实现路径：答案引用包含 path、title、anchor、chunk，前端跳转到对应页面位置。
- 验收方式：点击引用能回到原始文档位置。
- 边界/风险：引用缺失或锚点失效时必须暴露为质量问题。
9.7 页面质量状态
What：页面展示是否存在待处理反馈、过期提示、同步冲突或待发布变更。
Why：让用户理解当前页面的可信状态和维护状态。
落地推演：
- 技术产品：控制面 page manifest + Docusaurus PageQualityBadge。
- 实现路径：控制面聚合 PR、同步冲突、反馈 Issue、索引 manifest 和断链检查结果，生成 approved、needs-review、stale、conflict、feedback-open 等页面状态。
- 验收方式：读者和智能体能识别页面可信程度，并能跳 转到对应 PR、Issue 或报告。
- 边界/风险：状态只是辅助判断，不能替代 GitHub 审批记录；状态生成失败时必须显示 unknown 而不是默认 approved。
10. 文档编辑产品
10.1 在线编辑入口
What：用户可以从页面进入编辑或改进建议流程。
Why：降低文档修改门槛。
落地推演：
- 技术产品：Docusaurus editUrl + GitHub Web editor。
- 实现路径：页面提供编辑入口，跳转到 GitHub 编辑或创建 PR。
- 验收方式：用户能从页面发起改动。
- 边界/风险：MVP 不建设完整在线编辑器。
10.2 PR 化提交
What：编辑结果转化为 PR 或等价审批单元。
Why：保证编辑不绕过治理。
落地推演：
- 技术产品：GitHub PR。
- 实现路径：所有编辑提交到分支并创建 PR。
- 验收方式：人工编辑不直接写 main。
- 边界/风险：展示后端自带后台编辑不得用于受管页面。
10.3 编辑上下文
What：编辑时展示页面来 源、相关页面和历史版本。
Why：减少误改和重复修改。
落地推演：
- 技术产品：控制面 metadata + Docusaurus。
- 实现路径：编辑入口携带页面路径、来源、相关 Issue 和引用上下文。
- 验收方式：编辑者能理解页面来源和影响范围。
- 边界/风险：上下文不完整时仍可编辑，但 PR 需补说明。
10.4 编辑预览
What：用户提交编辑前可以预览页面渲染效果和受影响链接。
Why：降低格式错误、断链和误改进入 PR 的概率。
落地推演：
- 技术产品：Docusaurus build preview + GitHub checks。
- 实现路径：PR 触发构建预览或至少构建校验。
- 验收方式：编辑者和审批者能看到页面是否可构建。
- 边界/风险：MVP 可以先只有 build check，不强制预览环境。
10.5 改动意图说明
What：编辑提交时要求说明改动意图，例如纠错、补充、重构、更新版本。
Why：帮助审批者判断改动是否合理，也帮助智能体理解后续迭代上下文。
落地推演：
- 技术产品：PR 模板 + AgentBridge。
- 实现路径：人工或智能体提交改动时填写意图说明。
- 验收方式：PR body 能说明 why、what、risk。
- 边界/风险：无说明的 PR 应要求补充。
11. 知识索引产品
11.1 文档切片
What：将审批后的文档拆成可检索片段。
Why：支撑搜索和问答。
落地推演：
- 技术产品：RAGFlow。
- 实现路径：RAGFlow 对已审批文档进行解析和 chunk。
- 验收方式：问答召回能返回相关片段。
- 边界/风险：LLM-WIKI 不维护第二套独立向量 chunk。
11.2 元数据抽取
What：抽取标题、路径、来源、版本、标签和引用关系。
Why：提高检索和答案引用质量。
落地推演：
- 技术产品：LLM-WIKI 控制面。
- 实现路径：从 frontmatter、路径、source lock、Git 历史抽取 page path、sourceProject、version、qualityStatus。
- 验收方式：索引记录和答案引用能回溯到页面和来源。
- 边界/风险：元数据 schema 需要稳定，否则影响搜索和问答。
11.3 索引更新
What：文档发布后更新索引。
Why：保证问答使用的是最新审批内容。
落地推演：
- 技术产品：GitHub Actions + RAGFlow + Meilisearch。
- 实现路径：main 合并或发布成功后更新 RAGFlow dataset 和 Meilisearch index。
- 验收方 式：新页面可被问答和搜索命中，删除页面不再出现。
- 边界/风险：索引失败不能篡改已审批文档，但应阻塞“索引完成”状态。
11.4 搜索结果分组
What：搜索结果按页面、片段、项目、标签或更新时间分组展示。
Why：用户需要快速判断结果属于哪个知识域，而不是只看到扁平列表。
落地推演：
- 技术产品：Meilisearch + Search API。
- 实现路径：搜索结果按项目、路径、质量状态分组。
- 验收方式：用户和智能体能快速定位结果来源。
- 边界/风险：分组是检索体验，不作为权限判断依据。
11.5 搜索到问答切换
What：用户搜索后可以基于当前搜索结果继续提问。
Why：搜索和问答是连续的信息获取过程，不应割裂。
落地推演：
- 技术产品：Meilisearch + Agent Access/Answer API。
- 实现路径：搜索无结果或用户需要解释时，提供转问答入口。
- 验收方式：搜索结果页可带 scope 调用 ask。
- 边界/风险：问答答案仍必须来自 RAGFlow 引用，不以搜索结果直接生成权威答案。
12. 问答产品
12.1 面向人的问答
What：用户可以自然语言提问并获得答案。
Why：降低知识获取成本。
落地推演：
- 技术产品：Docusaurus + Answer API + RAGFlow。
- 实现路径：人通过页面问答组件提问，Answer API 调用 RAGFlow 并标准化结果。
- 验收方式：返回答案、引用、不确定性和反馈入口。
- 边界/风险：答案不是权威内容源，必须可追溯。
12.2 面向智能体的问答接口
What：智能体可以通过接口获取问题答案和引用上下文。
Why：让其他智能体复用 LLM-WIKI 知识。
落地推演：
- 技术产品：Agent Access API + RAGFlow。
- 实现路径：智能体通过
ask工具提问并获得结构化答案。 - 验收方式：返回 machine-readable answer、citations、confidence、noAnswerReason。
- 边界/风险：智能体不应直接拿自然语言答案当不可质疑事实。
12.3 引用来源
What：答案返回引用页面和相关片段。
Why：降低幻觉风险，提高可信度。
落地推演：
- 技术产品：RAGFlow citations + 控制面 metadata。
- 实现路径：答案引用包含页面、路径、标题、片段、版本。
- 验收方式： 每条答案至少能追溯到一个已授权来源，无法引用时标记无答案或低置信。
- 边界/风险：引用生成由 RAGFlow 执行，LLM-WIKI 负责标准化和校验。
12.4 不确定性表达
What：当文档不足时，答案明确说明不足。
Why：避免把猜测包装成事实。
落地推演：
- 技术产品：Answer API。
- 实现路径：答案输出 confidence、grounding、noAnswerReason。
- 验收方式：证据不足时用户和智能体能看到不确定性。
- 边界/风险：不确定时不能强行生成确定答案。
12.5 答案结构化呈现
What：答案至少区分直接结论、依据引用、补充说明和不确定部分。
Why：用户需要快速获得结论，同时能追溯依据和识别风险。
落地推演：
- 技术产品：Answer API response schema。
- 实现路径：统一输出 answer、steps/summary、citations、relatedPages、actions。
- 验收方式：前端和智能体都能稳定解析答案。
- 边界/风险：schema 变更需要版本化。
12.6 多轮追问
What：用户可以基于上一个答案继续追问，系统保留问题上下文和引用上下文。
Why：真实知识获取通常是连续澄清过程，而不是单轮问答。
落地推演：
- 技术产品：RAGFlow session + Answer API。
- 实现路径：保留会话上下文和引用上下文，支持追问。
- 验收方式：追问仍能返回引用，不丢失 scope。
- 边界/风险：MVP 可先限制轮数和上下文长度。
12.7 无答案处理
What：当知识库无法回答时，系统明确返回无法回答，并提供提交反馈或创建文档改进任务的入口。
Why：无答案本身是知识缺口，应该进入改进闭环。
落地推演：
- 技术产品：Answer API + GitHub Issues。
- 实现路径：无答案时返回 noAnswerReason，并可创建反馈或改进任务。
- 验收方式：无答案能进入任务池，而不是沉默失败。
- 边界/风险：无答案不是错误；编造答案才是错误。
13. 智能体访问产品
13.1 智能体知识访问 API
What：为外部智能体提供稳定 API，用于读取文档、检索知识、提问、获取引用和查看页面元数据。
Why：LLM-WIKI 不只给人阅读，也要成为智能体可调用的受治理知识工具。
落地推演：
- 技术产品：Agent Access API。
- 实现路径： 提供统一智能体工具入口，封装 RAGFlow、Meilisearch、GitHub 和元数据。
- 验收方式：智能体能用稳定 schema 调用知识能力。
- 边界/风险：访问层不承载第二套知识事实源。
13.2 任务上下文包
What：智能体可以按任务目标、项目、路径、版本或问题获取结构化上下文包。
Why：智能体执行任务时需要的不只是单次答案，而是一组可引用、可裁剪、可追踪的上下文。
落地推演：
- 技术产品：Agent Access API + RAGFlow + Meilisearch。
- 实现路径：按任务 scope 生成 ContextPack。
- 验收方式：ContextPack 包含页面、片段、引用、版本和质量状态。
- 边界/风险：上下文包必须受权限和 scope 约束。
13.3 工具化调用入口
What：智能体可以通过标准工具接口调用 LLM-WIKI 能力，包括 search、ask、get-page、get-context、create-feedback 和 create-improvement-task。
Why：智能体需要稳定、可编排的工具，而不是模拟人类浏览网页。
落地推演：
- 技术产品：HTTP API，后续 MCP server。
- 实现路径：MVP 暴露工具化 HTTP API；后续可扩展 MCP。
- 验收方式：智能体能调用 search、ask、get_page、get_context 等工具。
- 边界/风险：写入类工具只能创建反馈、Issue 或 PR 草稿。
13.4 智能体访问 scope
What：每次智能体调用都必须声明访问范围，包括项目、路径、版本、用途和调用主体。
Why：防止智能体跨越权限边界读取未授权内容，或把未审批内容当作正式知识使用。
落地推演：
- 技术产品：权限与身份产品 + Agent Access API + 服务端 policy。
- 实现路径：每次调用携带 token 和 caller，服务端将 token 映射到 agent identity、allowed tools、allowed paths、allowed datasets 和 write permissions，再校验调用方声明的 scope、tool、purpose。
- 验收方式：未授权 path、dataset、tool 或 working-docs 访问被拒绝并记录审计。
- 边界/风险：scope 不能由智能体单方面扩大；调用方声明只作为请求，不作为授权事实。
13.5 智能体反馈与改进任务提交
What：智能体发现无答案、答案冲突、引用不足或文档缺口时，可以提交反馈或创建文档改进任务。
Why：智能体既是知识消费者，也是知识质量信号来源。
落地推演：
- 技术产品：Agent Access API + GitHub Issues + RAGFlow Agent。
- 实现路径：智能体提交缺口后创建 Issue，必要时触发文档迭代任务。
- 验收方式：反馈能关联调用、问题、引用和后续 PR。
- 边界/风险：触发迭代不等于发布，仍需 Release PR。
14. 反馈与任务产品
14.1 答案反馈
What：用户可以反馈答案是否有用、是否错误、缺少什么。
Why：收集知识质量信号。
落地推演：
- 技术产品：前端反馈组件 + Agent Access API + GitHub Issues。
- 实现路径：用户或智能体对答案给出正确/错误/无帮助反馈。
- 验收方式：反馈记录包含答案、引用、页面和 caller。
- 边界/风险：反馈不能直接改变答案或文档。
14.2 文档缺口识别
What：系统把低质量答案和反馈转化为文档缺口。
Why：让问题成为可处理的改进对象。
落地推演：
- 技术产品：Answer API + RAGFlow + Meilisearch。
- 实现路径：无答案、低置信、搜索无结果、引用缺失形成缺口信号。
- 验收方式：系统能生成可追踪缺口记录。
- 边界/风险：缺口识别可能误报，需要人工或智能体后续判断。
14.3 改进任务生成
What：为智能体或人生成文档改进任务。
Why：连接问答消费和文档生产。
落地推演：
- 技术产品：GitHub Issues + FeedbackBridge。
- 实现路径：把缺口转成 GitHub Issue，带标签和上下文。
- 验收方式：Issue 可被分派、追踪并关联 PR。
- 边界/风险：MVP 不需要完整工单系统。
14.4 任务状态跟踪
What：跟踪改进任务的待处理、处理中、待审批、已完成、已关闭状态。
Why：避免反馈进入系统后丢失，确保知识缺口有闭环。
落地推演：
- 技术产品：GitHub Issues + PR links。
- 实现路径：通过 issue 状态、label、assignee、linked PR 跟踪任务。
- 验收方式：任务从创建到关闭有可追踪记录。
- 边界/风险：状态事实以 GitHub 为准。
14.5 质量信号聚合
What：聚合低置信答案、用户差评、高频问题、断链、过期页面等质量信号。
Why：帮助智能体和人优先处理影响最大的知识问题。
落地推演：
- 技术产品：控制面质量事件模型 + GitHub Issues + 定时报表。
- 实现路径：统一记录
qa_no_answer、qa_low_confidence、search_no_result、page_feedback、broken_link、source_conflict等事件，并按页面、项目、频次、严重度和最近发生时间聚合。 - 验收方式：维护者能看到高影响知识缺口排序，并能从聚合项跳转到原始问题、引用、页面和改进 Issue。
- 边界/风险：MVP 可先生成 Markdown/JSON 报告，不要求实时 dashboard；聚合结果不能自动修改文档。
15. 权限与身份产品
15.1 人员身份
What：识别阅读者、编辑者、审批者、管理员等人员角色。
Why：不同角色拥有不同操作权限，不能混用。
落地推演：
- 技术产品：GitHub users/teams。
- 实现路径：人员身份复用 GitHub 账号和团队。
- 验收方式：PR、Issue、配置变更可追踪到人。
- 边界/风险：外部读者身份可后置。
15.2 智能体身份
What：为文档迭代智能体和问答调用智能体建立独立身份。
Why：智能体操作必须可追踪，且权限应小于或等于其职责需要。
落地推演：
- 技术产品：Agent token + Agent Access API。
- 实现路径：为文档迭代智能体和知识使用智能体分配独立身份。
- 验收方式：审计中能区分哪个 agent 调用了哪个工具。
- 边界/风险：agent 权限不得大于职责需要。
15.3 系统任务身份
What：为定时同步、索引、发布等自动任务建立独立身份。
Why：区分人、智能体和系统任务，便于审计和限制权限。
落地推演：
- 技术产品：GitHub Actions token / GitHub App / PAT。
- 实现路径：系统任务使用独立 token 运行同步、发布、索引。
- 验收方式：日志能区分系统任务与人/agent。
- 边界/风险：PAT 是 MVP 快速方案，长期应升级 GitHub App。
15.4 写入权限边界
What：明确哪些主体可以写发布工作目录、创建 PR、批准 PR、执行发布。
Why：防止任何主体绕过 PR 治理直接影响正式知识库。
落地推演：
- 技术产品：branch protection + Agent Access policy。
- 实现路径：所有写入正式内容的动作必须进入 PR；Agent Access 写入类工具只创建 Issue/任务/PR 草稿。
- 验收方式：尝试直写 main 或发布后端会被拒绝。
- 边界/风险：需要定期审查 token 权限。
16. 配置管理产品
16.1 来源配置
What：管理来源仓库、来源分支、来源目录和目标发布目录。
Why：文档收集行为必须显式、可审查。
落地推演：
- 技术产品：
config/sources.yaml。 - 实现路径：声明来源项目和发布目录映射。
- 验收方式：配置 PR 合并后同步行为可预测。
- 边界/风险：错误配置会影响目录结构，必须校验。
16.2 发布配置
What：管理展示后端、发布路径、受管范围和删除策略。
Why：发布影响用户可见内容，必须可控。
落地推演：
- 技术产品：
config/publish.yaml+ Docusaurus adapter。 - 实现路径：声明展示后端、baseUrl、slug、发布策略。
- 验收方式：发布 workflow 能按配置构建和发布。
- 边界/风险：展示后端可替换，不能写死到产品层。
16.3 索引和问答配置
What：管理索引范围、检索策略、问答边界和引用要求。
Why：问答质量依赖清晰的知识输入和输出约束。
落地推演：
- 技术产品：
config/ragflow.yaml+config/agent-access.yaml+config/index.yaml。 - 实现路径：管理 RAGFlow dataset、Meilisearch index、Agent Access tools、scope、问答策略。
- 验收方式：配置能控制哪些文档可索引、可问答、可被 agent 访问。
- 边界/风险：模型 key 不进入配置文件，使用 Secrets。
16.4 配置审计
What：配置变化进入 Git 审查流程。
Why：配置变化会改变系统行为，应像文档变化一样可追溯。
落地推演：
- 技术产品：GitHub PR。
- 实现路径：所有配置变更通过 PR 审查。
- 验收方式：能追踪谁改了配置、何时生效、影响哪些流程。
- 边界/风险：运行时热修改配置不应成为主路径。
17. 运行基础设施
17.1 定时任务运行
What：支持文档收集器按计划运行。
Why：保证上游变化能持续进入系统。
落地推演：
- 技术产品：GitHub Actions。
- 实现路径：定时同步、发布检查、索引更新和 Agent workflow。
- 验收方式：workflow 可手动触发，也可按 schedule 运行。
- 边界/风险：内网 RAGFlow 可能需要 self-hosted runner 或代理。
17.2 密钥管理
What：管理访问 GitHub、文档展示后端、索引服务和问答服务所需密钥。
Why：防止敏感凭据泄露和发布入口失控。
落地推演：
- 技术产品：GitHub Secrets + 运行环境变量。
- 实现路径：管理 GitHub、RAGFlow、Meilisearch、模型和 Agent Access token。
- 验收方式：密钥不出现在仓库和日志中。
- 边界/风险：需要最小权限和轮换策略。
17.3 日志与状态
What：记录同步、迭代、发布、索引和问答状态。
Why：支持排障、审计和运营。
落地推演：
- 技术产品：GitHub Actions logs + manifests + service logs。
- 实现路径：记录同步、发布、索引、RAGFlow、Agent Access 调用状态。
- 验收方式：失败可定位到 workflow run、requestId、manifest 或 Issue。
- 边界/风险：MVP 可先依赖日志和状态文件，后续再做观测平台。
18. MVP 产品特性
MVP 优先级最高的特性：
- GitHub 文档源配置。
- 文档收集器。
- 三方 diff 同步。
- 发布工作目录。
- Draft PR。
- 文档迭代智能体改动入口。
- Release PR 审批。
- 文档展示产品发布能力。
- 基础权限与身份边界。
- 配置审计。
- 初版问答接口边界。
- 初版智能体访问 API 边界。
MVP 不追求完整前端和完整问答体验，但必须保证主链路闭合。
19. 特性分组
19.1 P0：MVP 主链路
- 稳定文档发布分支。
- 来源配置管理。
- 发布工作目录管理。
- 状态记录。
- 定时收集。
- 手动收集。
- 三方 diff 同步。
- 同步冲突报告。
- Draft PR。
- 项目映射目录。
- Git 可审查变更。
- Release PR 创建。
- PR 审批。
- 变更来源识别。
- 发布影响预览。
- 文档阅读。
- 页面内问答入口。
- 引用回跳。
- 智能体知识访问 API。
- 任务上下文包。
- 工具化调用入口。
- 智能体访问 scope。
- 智能体反馈与改进任务提交。
- PR 化提交。
- 编辑预览。
- 写入权限边界。
- 来源配置。
- 发布配置。
- 配置审计。
- 定时任务运行。
- 密钥管理。
- 日志与状态。
19.2 P1：第一阶段增强
- 文档整理。
- 文档补全。
- 变更说明生成。
- 发布审批状态。
- 展示层漂移检测。
- 页面元信息。
- 反馈入口。
- 页面质量状态。
- 编辑上下文。
- 改动意图说明。
- 文档切片。
- 元数据抽取。
- 索引更新。
- 搜索结果分组。
- 搜索到问答切换。
- 引用来源。
- 不确定性表达。
- 答案结构化呈现。
- 无答案处理。
- 人员身份。
- 智能体身份。
- 系统任务身份。
19.3 P2：后续产品化
- 项目级文档自治的高级管理。
- 可迭代文档空间的可视化管理。
- 基于反馈迭代的自动任务编排。
- 在线编辑入口。
- 面向人的完整问答体验。
- 多轮追问。
- 面向智能体的问答接口产品化。
- 答案反馈。
- 文档缺口识别。
- 改进任务生成。
- 任务状态跟踪。
- 质量信号聚合。
- 索引和问答配置。
20. P0 验收标准
P0 不是完整产品体验，而是主链路可运行的最低验收。
| 产品 | P0 验收标准 |
|---|---|
| GitHub 文档源 | 至少一个来源项目能通过稳定分支提供 docs/** |
| LLM-WIKI 控制仓库 | 来源配置、发布工作目录、状态文件进入 Git 管理 |
| 文档收集器 | 能执行新增、更新、删除，并能识别同步冲突 |
| 发布工作目录 | 能承载收集结果和后续人工/智能体改动 |
| 文档迭代智能体 | 能产生可审查的文档变更或允许人工模拟该角色 |
| 审批与治理台 | 文档变更必须能通过 PR 审批和合并 |
| 文档展示产品 | 审批后的文档能被用户阅读 |
| 文档编辑产品 | 用户改动能转化为 PR，而不是直接写生产内容 |
| 知识索引产品 | 已发布文档能形成可检索材料或明确索引输入输出 |
| 问答产品 | 能定义问题输入、答案 输出、引用和无答案处理边界 |
| 反馈与任务产品 | 用户反馈能形成可追踪的改进项，哪怕第一阶段是轻量记录 |
| 智能体访问产品 | 至少提供 ask/search/get-context/create-feedback 的受控接口 |
| 权限与身份产品 | 至少区分人、智能体、系统任务三类主体 |
| 配置管理产品 | 关键配置变更必须进入 Git 审查 |
| 运行基础设施 | 定时收集、状态记录、发布预演能运行并可排查 |
21. 实现协议覆盖
实现协议是产品特性落地推演的工程约束。P0/P1 特性必须能映射到至少一个实现协议，否则只能说明“方向可行”，不能说明“可开发、可验收”。
| 实现协议 | 覆盖产品特性 |
|---|---|
| SyncEngine 技术协议 | 稳定文档发布分支、来源配置管理、定时收集、手动收集、三方 diff 同步、同步冲突报告、Draft PR、项目映射目录、状态记录 |
| AgentBridge 技术协议 | 文档整理、文档补全、基于反馈迭代、变更说明生成、Release PR 创建、Git 可审查变更、写入权限边界 |
| Answer API 与 Agent Access 技术协议 | 页面内问答入口、面向人的问答、面向智能体的问答接口、引用来源、不确定性表达、答案结构化呈现、多轮追问、无答案处理、智能体知识访问 API、任务上下文包、工具化调用入口、智能体访问 scope、智能体反馈与改进任务提交 |
| Publish / Display Manifest 技术协议 | 发布影响预览、展示层漂移检测、文档阅读、导航浏览、页面元信息、引用回跳、页面质量状态、编辑上下文、编辑预览、文档切片、元数据抽取、索引更新、搜索结果分组、搜索到问答切换、质量信号聚合 |