DisplayBackend Adapter 技术设计
# DisplayBackend Adapter 技术设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 摘要
DisplayBackend Adapter 负责把 kunora-wiki 的 publish/** 正式文档转换为展示后端可消费的输入，并生成发布相关 manifest。MVP 展示后端是 Docusaurus，但 Docusaurus 的常规配置、主题和部署属于产品实施；进入 development 的部分只包括自研 adapter 契约、输入输出结构、构建状态映射和发布影响报告。
DisplayBackend Adapter 不拥有正式内容事实源，不修改业务文档正文，不生成答案，也不直接驱动索引。它只消费 Git 中已审批的 publish/** 和 WorkspaceStore 派生的文档记录，输出 PageManifest、PublishImpactReport、PublishManifest、SiteManifest 和标准错误。
2. 模块目标
- 将
DocumentRecord[]转换为展示后端输入。 - 为每个页面生成稳定 URL、标题、质量状态和展示元数据。
- 生成 Docusaurus sidebar、页面 metadata 和
EditContext，支撑编辑入口、反馈入口和 PR/Issue 上下文。 - 在发布前生 成
PublishImpactReport，供 ReviewBridge 审查页面新增、更新、删除和 URL 变化。 - 在发布后生成
PublishManifest和SiteManifest。 - 把 Docusaurus 构建结果映射为标准
OperationStatus、DriftStatus和ErrorObject。 - 隔离 Docusaurus 文件布局和 build output 等后端细节；sidebar 生成属于 MVP adapter 契约。
3. 非目标
- 不把 Docusaurus 作为正式内容事实源。
- 不把构建产物写回
publish/**。 - 不决定文档是否应该同步或进入 Release PR。
- 不调用 RAGFlow、Meilisearch 或 Answer API。
- 不修复 Markdown 内容语义错误。
- 不管理产品级站点主题、导航体验、部署域名和 CDN 策略。 但 MVP 必须生成可审查的 sidebar 输入、页面 metadata 和 EditContext。
4. 上下文边界
DisplayBackend Adapter 位于 L2 Publish/Index 层。它可以依赖 ConfigManager、WorkspaceStore 和 DisplayBackend adapter interface，但不能依赖 Answer API、Agent Access API 或 AgentBridge。
5. 输入与输出
5.1 输入
| 输入 | 来源 | 说明 |
|---|---|---|
PublishConfig | ConfigManager | 展示后端、baseUrl、managedPath、build output。 |
DocumentRecord[] | WorkspaceStore | 当前正式文档视图。 |
| previous manifests | WorkspaceStore/state | 用于发布影响 diff 和 drift 检查。 |
| git metadata | GitProvider/workflow | commit、baseRef、headRef、publishRunId。 |
| display backend result | Docusaurus adapter | 构建状态、页面输出、错误。 |
5.2 输出
| 输出 | 消费者 | 说明 |
|---|---|---|
PageManifest | Index Adapter、Answer API、Agent Access API、AgentBridge | 页面清单、URL、质量状态。 |
PublishImpactReport | ReviewBridge、维护者 | 发布前影响分析。 |
PublishManifest | Index Adapter、Answer API、drift check | 发布动作事实记录。 |
SiteManifest | ReviewBridge、drift check、维护者 | 站点构建和可访问页面状态。 |
EditContext | Docusaurus、ReviewBridge、IssueTracker | 编辑入口和 PR/Issue 上下文。 |
ErrorObject[] | ReviewBridge、workflow | 构建失败、URL 冲突、manifest 错误。 |
6. 依赖的 common 契约
| 契约 | 用途 |
|---|---|
PublishConfig | 展示后端配置和路径范围。 |
DocumentRecord | 页面输入事实。 |
PageManifest | 页面 URL 和可见状态。 |
PublishImpactReport | Release PR 审查材料。 |
PublishManifest | 发布成功事实。 |
SiteManifest | 站点构建和漂移状态。 |
EditContext | 编辑入口、反馈和 PR/Issue 上下文。 |
DisplayBackend | Docusaurus 等外部展示后端隔离接口。 |
ContentHash / NormalizedPath / SiteUrl | 页面身份、变更和 URL 稳定性。 |
ErrorObject | 标准错误输出。 |
7. 核心流程
7.1 页面 manifest 生成
规则：
- URL 由
PublishConfig.baseUrl和publishPath稳定推导。 - 同一
siteUrl不允许对应多个documentId。 qaVisible不能仅由展示状态决定，必须结合页面质量状态和配置策略。- 页面排序必须稳定，优先按 URL 或 publishPath。
7.2 Sidebar 与 EditContext 生成
DisplayBackend Adapter 必须从 PageManifestEntry、frontmatter topic 和路径层级生成 Docusaurus sidebar 输入，并为每个页面生成 EditContext。
规则：
- sidebar 生成是 MVP adapter 契约，不是待确认的前端实现细节。
EditContext.editUrl指向 GitHub 编辑或 PR 入口。EditContext必须包含来源项目、来源 ref/commit、最近审批 commit、关联 issue/PR 和期望改动意图。- Docusaurus 只展示
EditContext，不能把展示站编辑结果作为正式内容事实源。
7.3 发布影响分析
PublishImpactReport 比较 base/head 的 PageManifest 或 DocumentRecord：
| 变更类型 | 判断依据 | 风险 |
|---|---|---|
added | head 有、base 无 | low/medium。 |
updated | documentId 相同，contentHash 变化 | low/medium。 |
deleted | base 有、head 无 | high，需人工确认。 |
renamed | MVP 视为 delete + add | high。 |
url_changed | documentId 相同，siteUrl 变化 | high，影响引用回跳。 |
qa_visibility_changed | qaVisible 变化 | medium/high。 |
发布影响报告不修改站点，只为 ReviewBridge 提供审查输入。
7.4 展示构建与发布 manifest
构建失败时不得生成成功态 PublishManifest 或成功态 SiteManifest。
8. DisplayBackend 接口语义
| 接口 | 输入 | 输出 | 说明 |
|---|---|---|---|
prepareSiteInput | records、publish config | backend input plan | 生成展示后端输入，不写正式内容。 |
buildSite | backend input plan | build result | 执行或模拟构建。 |
deriveSiteUrl | publishPath、baseUrl | SiteUrl | URL 推导。 |
buildSidebar | PageManifest、frontmatter | sidebar input | 生成 Docusaurus sidebar。 |
buildEditContext | PageManifestEntry、Git/Issue metadata | EditContext | 生成编辑入口上下文。 |
readBuildOutput | build output path | site page list | 读取构建产物元数据。 |
mapError | backend error | ErrorObject | 转换 Docusaurus 错误。 |
Docusaurus adapter 的私有结构不能进入 PageManifest、PublishManifest 或 SiteManifest。
9. 状态与持久化
| 文件 | owner | 写入时机 | 说明 |
|---|---|---|---|
state/page-manifest.json | WorkspaceStore / DisplayBackend Adapter | 页面视图生成后 | 页面 URL、hash、qaVisible。 |
state/publish-impact-report.json | DisplayBackend Adapter / ReviewBridge | Release PR dry-run | 发布影响分析。 |
state/publish-manifest.json | DisplayBackend Adapter | 成功发布后 | 发布事实记录。 |
state/site-manifest.json | DisplayBackend Adapter | 构建完成后 | 站点状态。 |
DisplayBackend Adapter 不写 publish/** 正文内容。
10. 错误处理
| 错误码 | retryable | 场景 | 处理 |
|---|---|---|---|
display.config_invalid | false | PublishConfig 不可用 | 阻断构建。 |
display.url_conflict | false | 多页面 URL 冲突 | 阻断 manifest。 |
display.page_manifest_invalid | false | PageManifest schema 错误 | 阻断下游。 |
display.build_failed | false | Docusaurus build 失败 | 不生成成功 manifest，ReviewBridge failed check。 |
display.output_missing | true | 构建产物缺失或不可读 | 可重试。 |
display.drift_detected | false | SiteManifest 与 PublishManifest 不一致 | 标记 drift failed。 |
错误必须包含 publishRunId 或 runId、gitCommit、path/url 上下文；不得包含本地绝对路径。
11. 幂等与确定性
- 相同
DocumentRecord[]和PublishConfig必须生成相同PageManifest。 - URL 推导必须不依赖当前时间。
PublishImpactReport对相同 base/head 输入必须稳定排序和稳定输出。- 重复 publish 同一
publishRunId应返回同一成功 manifest 或安全 no-op。 - 构建失败重试不得留下成功态 manifest。
12. 安全与降级
- 构建失败不回滚 Git 内容，但阻断发布成功态。
- 站点不可用不影响 Git 中正式内容事实源。
- 删除页面必须在
PublishImpactReport中显式列出。 - URL 变化必须被视为引用回跳风险。
- DisplayBackend Adapter 不读取未授权
config/**或 secret 明文。
13. 测试要求
| 测试 | Fixture | 预期 |
|---|---|---|
| page manifest | fixtures/common/manifest/publish-manifest.valid.json | manifest canonical 输出稳定。 |
| build failed | fixtures/common/manifest/site-manifest-build-failed.json | 不生成成功态 site manifest。 |
| path/anchor | fixtures/common/path/valid-publish-paths.json | URL 和 anchor 可稳定推导。 |
| invalid path | fixtures/common/path/invalid-paths.json | 拒绝非法 publishPath。 |
| publish impact delete | future publish impact fixture | 删除和 URL 变化进入 high risk。 |
模块验收标准：
- URL 唯一性有 contract test。
- 构建失败不会生成成功 manifest。
- PageManifest、PublishManifest、SiteManifest 可 round-trip 校验。
- Docusaurus adapter mock 不泄漏私有结构。
- 删除和 URL 变化在 ReviewBridge 可见。
14. 设计决策
| 决策 | 说明 | 取舍 |
|---|---|---|
| Docusaurus 只作为 DisplayBackend | 外部产品差异被 adapter 隔离。 | 需要维护映射层。 |
| 构建失败不回滚 Git 内容 | Git 是正式内容事实源，发布失败是运行状态。 | 需要清晰 manifest 表达失败。 |
| rename 在 MVP 视为 delete + add | 与 documentId 路径规则一致。 | 会把部分移动标成高风险。 |
| 发布影响先于发布执行 | 让 Release PR 可审查。 | 需要维护 base/head manifest 对比。 |
15. 待确认问题
- PageManifest owner 是否最终归 WorkspaceStore，DisplayBackend 只补 URL，还是继续共同 owner。
qaVisible默认推导规则是否放在 DisplayBackend Adapter，还是由单独内容质量模块提供。- URL 变化是否在 MVP 统一阻断 Release PR。