Docusaurus 展示发布实施方案
# Docusaurus 展示发布实施方案
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 文档目标
本文定义 kunora-docs 项目中 Docusaurus 展示发布环节的实施方案。
Docusaurus 在 LLM-WIKI MVP 中是非自研展示产品，负责把 main/publish/** 中已审批的正式文档渲染为静态文档站。它不拥有内容事实源，不参与文档收集决策，不直接生成答案，也不反向修改 publish/**。
本文重点定义：
kunora-docs如何把publish/**转换为 Docusaurus 输入。- Docusaurus 构建产物、页面 metadata、sidebar、EditContext 和 site manifest 的契约。
- GitHub Actions 中展示发布环节的执行顺序、失败处理和验收标准。
2. 核心结论
Docusaurus 是展示后端，不是内容仓库。
kunora-docs 的展示发布链路必须遵守以下契约：
main/publish/** + state/page-manifest.json + config/publish.yaml
-> generated website input
-> Docusaurus build
-> build artifact + state/site-manifest.json
规则：
- 正式内容事实源只来自
main/publish/**。 website/docs/**是生成目录，不能手工维护正式内容。- Docusaurus build 成功不等于内容审批成功；内容审批仍由 GitHub PR 完成。
- Docusaurus build 失败必须阻断展示发布成功态 manifest。
- 页面 URL、metadata、EditContext 和 site manifest 必须可被下游 display/index/answer/agent 链路审计。
- 正式
page-manifest.json、publish-manifest.json、site-manifest.json的落点固定为state/**；GitHub artifact 只能作为审查和调试副本。
3. 范围
3.1 本方案覆盖
| 范围 | 说明 |
|---|---|
| Docusaurus 目录契约 | website/ 及生成目录的职责边界。 |
| 输入契约 | publish/**、state/page-manifest.json、config/publish.yaml、EditContext。 |
| 输出契约 | 生成 docs、sidebar、page metadata、build artifact、site-manifest.json。 |
| 构建流程 | GitHub Actions 中的生成、构建、校验、部署顺序。 |
| 页面展示契约 | URL、标题、质量状态、反馈入口、编辑入口、Q&A 挂载点。 |
| 漂移检测 | publish manifest 与 site manifest 对账。 |
| 验收标准 | kunora-docs 完成 Docusaurus 发布改造的定义。 |
3.2 本方案不覆盖
| 不覆盖 | 归属 |
|---|---|
| Docusaurus 主题视觉设计 | 后续展示体验设计或前端任务。 |
| DisplayBackend Adapter 内部实现 | docs/development/modules/display-backend-adapter。 |
| PageManifest / EditContext 数据结构定义 | docs/development/common/03-data-structures.md。 |
| GitHub Repository / Actions / Issues / Secrets 总体治理 | docs/implementation/01-github-repository-actions-issues-secrets.md。 |
| RAGFlow / Meilisearch 索引实施 | 03-ragflow-implementation.md、04-meilisearch-implementation.md。 |
| Answer API 运行时部署 | 05-runtime-implementation.md。 |
4. Docusaurus 在 kunora-docs 中的位置
边界：
publish/**是正式内容事实源。- DisplayBackend Adapter 负责把正式内容转换为 Docusaurus 可消费输入。
- Docusaurus 负责静态站点构建。
- 静态托管只承载构建产物。
site-manifest.json记录展示结果，不反向决定内容事实。
5. 目录契约
5.1 kunora-docs 目录
| 路径 | 职责 | 写入者 | 是否可手工编辑正式内容 |
|---|---|---|---|
publish/** | 正式文档内容 | Sync PR、Release PR、人工 PR | 是，但必须走 PR。 |
state/page-manifest.json | 页面治理和展示输入 | DisplayBackend Adapter / workflow | 否。 |
state/publish-manifest.json | 发布内容事实记录 | publish workflow | 否。 |
state/site-manifest.json | 展示构建和部署事实记录 | Docusaurus publish workflow | 否。 |
config/publish.yaml | 展示发布配置 | Config PR | 是，必须走 PR。 |
website/ | Docusaurus 项目 | 前端维护者 / workflow | 仅可编辑站点代码和配置。 |
website/docs/** | Docusaurus docs 输入 | workflow 生成 | 否。 |
website/build/** | 静态构建产物 | Docusaurus build | 否，不提交为事实源。 |
5.2 website 目录建议
website/
docusaurus.config.ts
sidebars.ts
docs/ # generated from ../publish
src/components/PageAskBox.tsx
src/components/PageQualityBadge.tsx
src/components/EditContextPanel.tsx
src/theme/ # optional theme customization
build/ # generated build output
规则：
website/docs/**由发布流程清空并重新生成。- 正式文档修改必须发生在
publish/**。 - 组件代码可以在
website/src/**中维护，但组件不能把展示站状态写回publish/**。 website/build/**不作为 Git 内容事实源；只作为 artifact 或部署产物。state/page-manifest.json、state/publish-manifest.json、state/site-manifest.json是后续索引、问答和漂移检测的正式 handoff 文件，必须写入state/**或由同一 workflow 在合并前更新到目标分支；artifact 副本不能替代正式 handoff。
6. 输入契约
6.1 publish/**
Docusaurus 只消费 main 上已审批的 publish/**。
最低要求：
| 字段/内容 | 要求 |
|---|---|
| 文件格式 | MVP 以 Markdown/MDX 为主。 |
| 路径 | 必须满足 publish/** 路径规则。 |
| 标题 | 优先从 frontmatter title 获取，否则从第一个 H1 获取。 |
| 内容 hash | 用于 PublishManifest.contentHash 和 SiteManifest.sourceHash 对账。 |
| 质量状态 | 不从 Docusaurus 推导，来自 page manifest 或治理状态。 |
6.2 state/page-manifest.json
Docusaurus 生成输入时必须读取 page manifest。
页面至少需要以下信息：
| 字段 | 用途 |
|---|---|
documentId | 页面稳定身份。 |
path / publishPath | 映射到 generated docs 路径。 |
url | Docusaurus 页面 URL。 |
title | sidebar 和页面 metadata。 |
sourceProject | 页面来源项目展示和反馈上下文。 |
qualityStatus | PageQualityBadge 数据。 |
qaVisible | 是否挂载 Q&A 入口。 |
indexable | 是否纳入搜索和问答索引。 |
feedbackOpen | 是否展示反馈入口。 |
hasSourceConflict | 是否展示来源冲突提示。 |
lastApprovedAt | 页面更新时间/审批时间。 |
relatedIssues | 页面相关 Issue。 |
relatedPullRequests | 页面相关 PR。 |
editContext | GitHub 编辑、Issue、PR 入口上下文。 |
6.3 config/publish.yaml
Docusaurus 发布至少需要以下配置：
| 字段 | 示例 | 说明 |
|---|---|---|
backend | docusaurus | 展示后端类型。 |
site.url | https://docs.example.com | 正式站点域名。 |
site.baseUrl | / | 站点路径前缀。 |
managedPath | publish/ | 正式内容根路径。 |
websitePath | website/ | Docusaurus 项目路径。 |
generatedDocsPath | website/docs/ | 生成 docs 输入路径。 |
buildOutputPath | website/build/ | Docusaurus 构建输出路径。 |
editUrlBase | GitHub edit/PR URL | 编辑入口基础地址。 |
routeBasePath | / 或 /docs/ | Docusaurus docs 路由根。 |
配置规则：
managedPath必须位于publish/。generatedDocsPath不得等于publish/。site.url + site.baseUrl + page.url必须能组成稳定页面 URL。editUrlBase不得包含 secret 或一次性 token。
7. 输出契约
7.1 Docusaurus 输入
| 输出 | 位置 | 说明 |
|---|---|---|
| generated docs | website/docs/** | 从 publish/** 复制或转换。 |
| generated sidebar | website/sidebars.ts 或 generated sidebar data | 由 page manifest、frontmatter 和路径层级生成。 |
| page metadata | frontmatter / sidecar metadata | 页面来源、质量、反馈、EditContext。 |
| component config | page metadata 或站点配置 | Q&A、质量标识、反馈入口的挂载参数。 |
生成规则：
- 输出必须确定性排序。
- 同一
documentId在重复构建中应生成相同目标路径。 - URL 冲突必须阻断构建。
- markdown 正文不应被 Docusaurus 生成流程改写语义。
7.2 页面 metadata
页面 metadata 是展示层和用户交互入口的最小契约。
| metadata | 页面用途 |
|---|---|
documentId | 反馈、问答、日志关联。 |
sourceProject | 显示来源项目。 |
sourceRef / sourceCommit | 编辑上下文和追溯。 |
qualityStatus | PageQualityBadge。 |
lastApprovedAt | 页面更新时间。 |
qaVisible | 是否显示 PageAskBox。 |
feedbackOpen | 是否显示反馈入口。 |
hasSourceConflict | 是否提示来源冲突。 |
relatedIssues | 反馈和改进入口。 |
relatedPullRequests | 历史变更入口。 |
editContextId 或 editContext | 编辑入口上下文。 |
7.3 state/site-manifest.json
Docusaurus build 完成后必须生成 site manifest。
最低字段：
| 字段 | 说明 |
|---|---|
publishRunId | 本次发布运行 ID。 |
publishedAt | 展示构建完成时间。 |
gitCommit | 本次读取的 main commit。 |
pages[].path | 对应 publish/** 页面。 |
pages[].url | 站点 URL。 |
pages[].sourceHash | 必须等于 publish manifest 中同页 contentHash。 |
pages[].renderedHash | 构建后页面内容 hash。 |
pages[].status | published、missing、redirected、failed 等展示状态。 |
pages[].httpStatus | 部署后可访问性检查结果。 |
pages[].expectedStatus | 预期状态，删除页可为 404/410/redirect。 |
pages[].redirectTarget | 删除或迁移页面的目标。 |
pages[].cacheValidUntil | CDN/cache 宽限期。 |
规则：
- build 失败不得生成成功态
site-manifest.json。 sourceHash必须与 publish manifest 对账。renderedHash用于展示产物漂移检测，不能拿 markdown hash 替代。- 部署后至少要对关键 URL 做可访问性检查。
8. 构建流程契约
8.1 PR dry-run
Release PR 或影响展示的 Config PR 必须执行 dry-run：
checkout PR head
validate config
validate publish paths
generate page manifest
generate Docusaurus input
run Docusaurus build
write publish impact report artifact
write site manifest dry-run artifact
post PR summary/check
要求：
- dry-run 不发布正式站点。
- dry-run 可以生成 artifact，但不得把成功态 manifest 直接写入
main。 - build 失败必须成为 PR 阻断 check。
8.2 main publish
main 更新后执行正式展示发布：
checkout main
read publish/**
read config/publish.yaml
generate page manifest
write state/page-manifest.json
generate Docusaurus input
run Docusaurus build
write state/publish-manifest.json
write state/site-manifest.json
deploy build artifact
verify key URLs
publish workflow summary
要求：
- workflow 不直接改写
publish/**。 - 构建成功后才允许生成成功态 publish/site manifest。
- 部署失败需要把
site-manifest标记为 failed 或 partial，不得静默成功。 state/page-manifest.json、state/publish-manifest.json、state/site-manifest.json必须作为正式 handoff 更新；artifact 只用于审查副本。- 同一
publishRunId重跑应幂等。
9. URL 与 sidebar 规则
9.1 URL 规则
| 规则 | 说明 |
|---|---|
| 稳定推导 | URL 由 publishPath、frontmatter slug 或 page manifest 规则稳定推导。 |
| 不允许冲突 | 两个页面不能生成相同 URL。 |
| 删除可追踪 | 删除页面必须进入 publish impact 和 site manifest。 |
| 迁移显式化 | URL 变化在 MVP 视为 high risk。 |
| baseUrl 一致 | Docusaurus baseUrl 必须与 config/publish.yaml 一致。 |
9.2 sidebar 规则
sidebar 由机器生成，默认顺序：
- 显式 frontmatter/sidebar 配置。
- page manifest 中的 display order。
- 路径层级和标题。
- URL 字典序兜底。
要求：
- 生成顺序必须稳定。
- 不允许孤儿页面无入口，除非页面 metadata 明确
hiddenFromSidebar=true。 - sidebar 生成失败应阻断构建或至少标记 failed check。
10. EditContext 与页面交互入口
Docusaurus 页面必须能承载以下入口：
| 入口 | 数据来源 | 行为 |
|---|---|---|
| 编辑此页 | EditContext.editUrl | 跳转 GitHub 编辑/PR 流程。 |
| 反馈 | feedbackOpen + EditContext | 创建或复用 GitHub Issue。 |
| 页面问答 | qaVisible + page scope | 调用 Answer API 或 Agent Access API。 |
| 质量状态 | qualityStatus | 展示 PageQualityBadge。 |
| 来源追溯 | source metadata | 展示 sourceProject、sourceRef、lastApprovedAt。 |
规则：
- Docusaurus 只展示 EditContext，不拥有 EditContext 事实源。
- 用户在展示站触发的反馈必须进入 GitHub Issue 或后端反馈接口，不能直接修改页面。
- 页面问答组件只能按当前页面或允许 scope 请求答案，不能绕过
qaVisible和权限策略。
11. 错误处理与漂移检测
| 错误/漂移 | 判断 | 处理 |
|---|---|---|
display.config_invalid | config/publish.yaml 无效 | 阻断构建。 |
display.url_conflict | 多页面生成同一 URL | 阻断构建。 |
display.build_failed | Docusaurus build 失败 | PR/main check failed，不生成成功 manifest。 |
display.output_missing | build 产物缺失 | 标记 failed，可重试。 |
site_outdated | site manifest gitCommit 落后 | 标记 drift，触发修复任务。 |
page_missing | publish manifest 有页但 site manifest 无 URL | 标记 failed。 |
source_hash_mismatch | site sourceHash 与 publish contentHash 不一致 | 标记 failed。 |
rendered_hash_mismatch | 部署产物 hash 与 manifest 不一致 | 标记 drift。 |
deleted_page_still_visible | 删除页超过宽限期仍返回 200 | 标记 drift，必要时建 Issue。 |
错误输出要求：
- 必须包含
publishRunId、gitCommit、path 或 URL 上下文。 - 不得包含本地绝对路径、secret、token。
- PR summary 必须显示阻断项和非阻断告警。
12. GitHub Actions 落地
Docusaurus 展示发布归入 docs-publish.yml。
12.1 PR 触发
| 步骤 | 产物 | 验收 |
|---|---|---|
| validate config | check summary | config 错误阻断。 |
| generate page manifest | artifact | URL、metadata、EditContext 可生成。 |
| generate site input | artifact | website/docs/** 可生成。 |
| Docusaurus build | check | build 失败阻断 PR。 |
| publish impact | PR summary | 显示新增、更新、删除、URL 变化。 |
| site dry-run manifest | artifact | 可用于 review，不发布。 |
12.2 main 触发
| 步骤 | 产物 | 验收 |
|---|---|---|
| generate display input | website/docs/** | 来自 main/publish/**。 |
| Docusaurus build | website/build/** | 构建成功。 |
| generate publish manifest | state/publish-manifest.json | contentHash 可对账。 |
| generate site manifest | state/site-manifest.json | sourceHash/renderedHash/httpStatus 完整。 |
| deploy | static hosting | 关键 URL 可访问。 |
| summarize | workflow summary | run id、commit、页面数、失败数可见。 |
13. 实施阶段
阶段 D1：Docusaurus 骨架
交付：
website/目录。- Docusaurus 基础配置。
- docs route 和 baseUrl 配置。
- 允许本地或 CI 执行 build。
验收：空站或样例页可 build。
阶段 D2：生成输入 dry-run
交付：
- 从
publish/**生成website/docs/**。 - 生成 sidebar。
- 生成页面 metadata。
验收：不手工编辑 website/docs/**，重复生成结果稳定。
阶段 D3：EditContext 和页面组件挂载
交付：
EditContextPanel数据入口。PageQualityBadge数据入口。PageAskBox挂载开关。- 反馈入口上下文。
验收：每个页面都能追溯 sourceProject、相关 Issue/PR 和编辑入口。
阶段 D4：PR dry-run check
交付：
docs-publish.yml在 PR 上运行 Docusaurus build。- 输出 publish impact 和 site dry-run manifest。
验收：Docusaurus build 失败阻断 Release PR。
阶段 D5：main 展示发布
交付：
- main push 后生成正式 build artifact。
- 生成 publish/site manifest。
- 部署到静态托管。
验收：关键 URL 可访问，manifest 与当前 commit 对账。
阶段 D6：漂移检测
交付：
- site manifest 与 publish manifest 对账。
- 关键 URL 可访问性检查。
- 漂移失败进入 workflow summary 或 Issue。
验收：缺页、hash 不一致、删除页仍可见能够被发现。
14. 完成定义
Docusaurus 展示发布改造完成，必须同时满足以下条件：
kunora-docs中存在可构建的website/Docusaurus 项目。- 正式页面只从
main/publish/**生成。 website/docs/**不作为人工维护的正式内容目录。- page manifest 能为每个页面提供 URL、质量状态、来源、EditContext、反馈和问答开关。
- sidebar 能稳定生成。
- Release PR 上 Docusaurus build 失败会阻断合并。
- main 发布后能生成
publish-manifest.json和site-manifest.json。 site-manifest.sourceHash能与publish-manifest.contentHash对账。- 至少关键 URL 有部署后可访问性检查。
- 页面包含编辑入口、反馈入口、质量状态和 Q&A 挂载点。
- 正式 manifest handoff 固定写入
state/**，artifact 副本不能作为下游唯一输入。
15. 替代方案与取舍
| 方案 | 结论 | 原因 |
|---|---|---|
直接在 website/docs/** 维护正式内容 | 不采用 | 会让 Docusaurus 目录成为第二事实源，破坏 publish/** 治理链。 |
Docusaurus build 成功后反写 publish/** | 不采用 | 展示产物不应修改正式内容。 |
| 不生成 site manifest，只依赖部署成功 | 不采用 | 无法做展示漂移、删除页和 hash 对账。 |
| 先不做页面组件，只生成静态文档 | 可作为 D1/D2 过渡 | 但 v1 MVP 完成定义仍要求 EditContext、反馈、质量和 Q&A 挂载点。 |
| 使用其他静态站生成器 | 暂不采用 | 产品文档已选定 Docusaurus，MVP 优先降低变量。 |
16. 开放问题
- 静态托管首选 GitHub Pages、Vercel/Netlify，还是内网静态服务。
website/docs/**在 CI 中生成后是否提交到仓库，还是只存在于 build workspace。MVP 默认只作为生成输入，不作为正式内容事实源。- 初始主题是否只做最小可用，还是同时实现 PageQualityBadge、EditContextPanel 和 PageAskBox 的正式 UI。