kunora-docs 文档发布契约与实施方案

# kunora-docs 文档发布契约与实施方案

修订记录

版本	日期	修订说明
v0.1	2026-05-01	建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。

1. 文档目标

本文定义 kunora-docs 项目的文档发布契约和 GitHub 产品侧实施方案。

kunora-docs 不是单纯的展示站仓库，它同时承担三类职责：

• 收集：从来源项目读取稳定文档，形成可审查同步变更。
• 治理：通过 GitHub PR、checks、Issues 管理同步、整理、反馈和发布审批。
• 发布：把已审批的 publish/** 内容发布到展示站，并同步到搜索和问答索引。

本文不展开 GitHub UI 的逐项配置细节，也不设计自研模块内部实现。自研模块契约仍以 docs/development 为准。

2. 核心结论

kunora-docs 是 LLM-WIKI MVP 的控制仓库和文档发布工作区。

它的核心契约是：

source repos/docs-publish -> Sync PR -> publish/** -> Release PR -> main -> display/index/answer

任何正式对外发布、索引或问答使用的内容，都必须来自 main 上已审批的 publish/**，而不是来源仓库、Docusaurus 构建产物、RAGFlow dataset 或 Meilisearch index。

3. 范围

3.1 本方案覆盖

范围	说明
Repository 契约	kunora-docs 的目录、分支、状态和发布工作区。
文档收集契约	来源项目如何进入 publish/**。
文档发布契约	什么内容可以发布、何时发布、产出什么 manifest。
GitHub PR 治理	Sync PR、Release PR、Config PR 的边界。
GitHub Issues	反馈、无答案、冲突和改进任务的承载方式。
GitHub Actions	sync、publish、index、agent 四类流程的职责。
Secrets/Variables	外部产品接入所需的最小配置边界。

3.2 本方案不覆盖

不覆盖	归属
SyncEngine 三方 diff 内部算法	docs/development/modules/sync-engine。
WorkspaceStore 路径、hash、manifest 读写实现	docs/development/modules/workspace-store。
Docusaurus 主题和前端页面设计	后续展示实施文档。
RAGFlow dataset 具体配置界面	03-ragflow-implementation.md。
Meilisearch index settings 细节	04-meilisearch-implementation.md。
Answer API / Agent Access API 部署细节	05-runtime-implementation.md。

4. kunora-docs 仓库契约

4.1 目录契约

路径	是否事实源	写入者	消费者	说明
config/**	是，配置事实源	人工 PR	ConfigManager、workflows	来源、发布、索引、agent policy、模型策略。
publish/**	是，正式内容事实源	Sync PR、Release PR、人工 PR	Display、Index、Answer、AgentBridge	已治理文档工作区。
state/**	否，可重建状态	workflows / 自研模块	Review、Display、Index、Answer	lock、changes、manifest、report。
schemas/**	是，契约校验源	人工 PR	CI、自研模块	JSON/YAML schema。
fixtures/**	是，测试样例源	人工 PR	CI、自研模块	contract/golden/negative fixtures。
scripts/**	是，自研执行入口	人工 PR	workflows	CLI、adapter、工具脚本。
.github/**	是，治理配置源	人工 PR	GitHub	workflows、Issue/PR templates。

规则：

• publish/** 是唯一正式文档内容事实源。
• state/** 不能单独作为内容事实源，丢失后应可从 Git 内容、配置和外部状态重建。
• 外部产品产物不得反向覆盖 publish/**。
• config/** 变更必须走 PR，并生成配置影响说明。

4.2 分支契约

分支	用途	可写入者	合并要求
main	已审批正式内容、配置和状态	仅 PR merge	必须受保护。
docs-sync/source-updates	来源收集候选变更	sync workflow / ReviewBridge	Draft Sync PR。
docs-release/*	人工或 agent 整理后的发布候选	维护者 / AgentBridge	Release PR。
docs-config/*	配置变更候选	维护者	Config PR。

禁止：

• 任何 workflow 直接推送到 main。
• AgentBridge 直接推送到 main。
• Docusaurus、RAGFlow、Meilisearch 反向写入 publish/**。

5. 文档收集契约

5.1 来源项目输入

来源项目必须提供稳定输入：

输入	要求
repo	GitHub 仓库。
ref	推荐 docs-publish 分支或固定 tag。
sourcePath	来源仓库内文档根路径。
include/exclude	明确文件范围。
publishPath	映射到 kunora-docs/publish/** 的目标路径。

5.2 收集输出

同步运行输出：

输出	路径/位置	说明
publish candidate diff	docs-sync/source-updates	对 publish/** 的新增、更新、删除候选。
source lock	state/source-lock.json	上次成功同步基线。
source changes	state/source-changes.json	本次同步变更、冲突和删除报告。
Sync PR	GitHub PR	人工审查入口。

5.3 收集规则

• 上游新增且目标不存在：生成 add。
• 上游更新且目标未被本地整理：生成 update。
• 上游未变但目标已整理：保留本地内容。
• 上游和目标同时变化：生成冲突，不覆盖目标。
• 上游删除：按 delete policy 生成删除候选或删除报告。
• 来源路径移动：MVP 按 delete + add 处理。

6. 文档发布契约

6.1 发布输入

发布只读取 main 上已审批内容：

输入	说明
publish/**	正式文档内容。
state/page-manifest.json	页面 URL、质量、索引、编辑上下文等机器可读信息。
config/publish.yaml	展示后端和 base URL 配置。
config/index.yaml	索引目标配置。
config/ragflow.yaml	RAGFlow dataset 配置。

6.2 发布输出

输出	路径/位置	说明
Docusaurus input	build workspace	从 publish/** 派生，不作为事实源。
sidebar / metadata	build workspace	从 page manifest 和 frontmatter 派生。
EditContext	page metadata / manifest	编辑入口、Issue、PR 上下文。
PublishManifest	state/publish-manifest.json	发布读取的 commit、页面、URL、contentHash。
SiteManifest	state/site-manifest.json	展示构建和部署对账状态。
IndexManifest	state/index-manifest.json	RAGFlow/Meilisearch target 状态。

6.3 发布前置条件

发布成功态必须满足：

• 内容来自 main/publish/**。
• config/** 校验通过。
• page manifest 可生成且无阻断错误。
• Docusaurus build 通过。
• 发布 manifest、site manifest 和 index manifest 必须写入 state/** 作为正式 handoff；artifact 只能作为审查和调试副本。

索引失败不回滚 Git 内容，但必须写入失败或 partial 状态。

7. PR 治理契约

7.1 Sync PR

用途：把来源项目文档收集结果提交给维护者审查。

必须包含：

• source 列表。
• add/update/delete/keep/conflict/delete_conflict 数量。
• 冲突文件和删除候选。
• source changes 报告链接或摘要。
• 是否更新 source lock。

合并效果：同步候选内容进入 main/publish/**，之后可进入发布链路。

7.2 Release PR

用途：人工整理或 AgentBridge 输出的正式发布候选。

必须包含：

• 变更意图。
• 影响页面和 URL。
• 相关 Issue。
• citation / evidence。
• publish impact report。
• build / index dry-run 状态。
• 风险和回滚说明。

合并效果：内容进入 main/publish/**，触发展示发布和索引。

7.3 Config PR

用途：调整来源、发布、索引、RAGFlow、Agent Access 或模型策略。

必须包含：

• 变更配置文件。
• 影响 source / publishPath / dataset / policy。
• 是否扩大 agent scope。
• 是否可能造成删除、迁移或重建索引。

8. Issues 契约

GitHub Issues 是 MVP 的反馈和任务承载面。

Issue 类型	来源	后续流转
docs-feedback	Docusaurus 页面反馈	维护者 triage，必要时转改进任务。
qa-no-answer	Answer API / Agent Access API	FeedbackBridge 去重，维护者确认后可加 agent-ready。
qa-low-confidence	Answer API	同上。
qa-wrong-answer	用户反馈	人工优先确认。
search-no-result	Agent Access API / Meilisearch	检查索引或补文档。
source-conflict	SyncEngine	维护者处理 Sync PR 冲突。
improvement-task	人工或 FeedbackBridge	AgentBridge 候选输入。

去重规则：

• FeedbackBridge 属于 Agent Access API 内部能力。
• IssueTracker adapter 负责 GitHub Issues API 差异。
• dedupeKey 命中开放 Issue 时，不创建新 Issue，只追加上下文或计数。

9. Actions 契约

Workflow	触发	职责	主要产物
docs-sync.yml	schedule / manual	收集来源文档，生成 Sync PR	source changes、Sync PR。
docs-publish.yml	PR / main push	校验内容，生成发布影响，构建展示站	publish impact、publish/site manifest、checks。
docs-index.yml	publish success / manual	同步 RAGFlow 和 Meilisearch	index manifest。
docs-agent.yml	manual / issue labeled	执行 AgentBridge 任务，生成 Release PR	AgentBridge report、Release PR。

共同要求：

• workflow 必须输出可审计 summary。
• workflow 必须使用 concurrency 防止同一目标分支被并发覆盖。
• workflow 失败必须显式化，不允许静默忽略。
• 外部产品失败不得反向污染 Git 内容事实源。

10. Secrets 与 Variables 契约

10.1 Secrets

Secret	用途	消费者
GH_DOCS_TOKEN	跨仓库读取、创建 PR、写 Issues	docs-sync、docs-agent、ReviewBridge。
RAGFLOW_API_KEY	RAGFlow dataset、问答、迭代调用	docs-index、docs-agent、Answer API。
MEILI_MASTER_KEY	Meilisearch index 写入	docs-index。
MODEL_API_KEY	模型调用，优先由 RAGFlow 消费	RAGFlow / agent runtime。
ANSWER_API_TOKEN	Answer API 调用保护	runtime / frontend。
AGENT_ACCESS_TOKEN	Agent Access API 调用保护	agent runtime。

10.2 Variables

Variable	用途
DOCS_SYNC_BRANCH	默认 docs-sync/source-updates。
DOCS_RELEASE_PREFIX	默认 docs-release/。
RAGFLOW_APPROVED_DATASET	默认 llm-wiki-approved。
RAGFLOW_WORKING_DATASET	默认 llm-wiki-working。
MEILI_INDEX_NAME	Meilisearch index 名。
DOCUSAURUS_BASE_URL	展示站 base URL。

原则：

• MVP 可先使用 fine-grained PAT。
• 不使用全权限 classic PAT。
• Secrets 不进入日志、Issue、PR body 或 manifest。
• 后续稳定运行应迁移到 GitHub App。

11. 实施阶段

阶段 1：仓库和治理骨架

目标：让 kunora-docs 具备可审查的控制仓库形态。

交付：

• 目录结构落地。
• main 分支保护。
• Issue labels / templates。
• PR templates。
• 基础 repository variables。

验收：不能直接 push main；Issue/PR 能按模板创建。

阶段 2：收集链路 dry-run

目标：先验证来源项目到 Sync PR 的契约。

交付：

• config/sources.yaml。
• docs-sync.yml placeholder 或 dry-run。
• state/source-changes.json 示例。
• Sync Draft PR 模板。

验收：至少一个来源项目能生成同步报告和 Sync PR，不覆盖人工整理内容。

阶段 3：发布链路 dry-run

目标：验证 publish/** 到展示和 manifest 的契约。

交付：

• page manifest。
• publish impact report。
• Docusaurus build dry-run。
• publish/site manifest 示例。

验收：main/publish/** 至少一个页面可构建；构建失败不生成成功态 manifest。

阶段 4：索引链路

目标：把已审批内容同步到 RAGFlow approved dataset 和 Meilisearch。

交付：

• RAGFlow llm-wiki-approved dataset 同步。
• RAGFlow llm-wiki-working dataset 同步策略。
• Meilisearch index 同步。
• index manifest。

验收：同一文档可被 approved dataset 问答和 Meilisearch 搜索召回；删除后不再召回。

阶段 5：反馈与 agent 任务

目标：让无答案、低置信和人工反馈进入 Issue，并可触发 AgentBridge。

交付：

• FeedbackBridge 去重规则。
• Issue 创建/复用流程。
• agent-ready 标签触发或人工触发 docs-agent.yml。
• AgentBridge Release PR。

验收：无答案反馈不会重复刷 Issue；agent 变更只进入 Release PR，不直接发布。

12. 最小验收清单

类别	验收标准
收集	至少一个来源 repo 的 docs-publish 可进入 Sync PR。
治理	main 受保护，正式内容只能 PR merge。
发布	main/publish/** 可构建为 Docusaurus 页面。
Manifest	page/publish/site/index manifest 可写入 state/**，artifact 副本可用于审查。
Issues	无答案、页面反馈、来源冲突有模板和标签。
Secrets	外部 token 均走 GitHub Secrets，不出现在日志和 manifest。
索引	approved 与 working dataset 语义分离。
审计	每次 sync/publish/index/agent 都有 run id、PR 或 workflow summary。

13. 可执行改造清单

本节是改造 kunora-docs 文档发布环节的执行清单。每一项都必须能在仓库中看到文件、PR、workflow 输出或 manifest 结果。

13.1 仓库骨架

编号	交付物	验收方式	阻断条件
G1	config/ 目录存在	仓库中可见 config/*.yaml 占位或正式配置	缺少配置入口，后续 workflow 不能运行。
G2	publish/ 目录存在	至少有 .gitkeep 或一个样例页面	没有正式内容工作区。
G3	state/ 目录存在	至少有 .gitkeep	manifest 和 report 无落点。
G4	schemas/ 目录存在	schema 占位或首批 schema 文件	无法执行 schema 校验。
G5	fixtures/ 目录存在	fixtures 占位或首批 common fixture	无法执行 dry-run/contract 测试。
G6	.github/workflows/ 存在	四类 workflow 文件或 placeholder 存在	无自动化入口。
G7	.github/ISSUE_TEMPLATE/ 存在	反馈、无答案、改进任务、冲突模板存在	Issues 无结构化输入。
G8	.github/PULL_REQUEST_TEMPLATE/ 存在	Sync/Release/Config PR 模板存在	PR 治理上下文缺失。

13.2 配置文件

编号	文件	最低字段	消费者
C1	config/sources.yaml	id、repo、ref、sourcePath、publishPath、include、exclude、deletePolicy	docs-sync / ConfigManager。
C2	config/publish.yaml	backend、site.url、site.baseUrl、site.routeBasePath、managedPath、websitePath、generatedDocsPath、buildOutputPath、editUrlBase	docs-publish / DisplayBackend Adapter。
C3	config/index.yaml	targets、target id/type/enabled、quality filter	docs-index / Index Adapter。
C4	config/ragflow.yaml	approved dataset、working dataset、endpoint ref	docs-index、docs-agent、Answer API。
C5	config/agent-access.yaml	agent identity、allowed tools、allowed paths、allowed datasets	Agent Access API、docs-agent。
C6	config/model-policy.yaml	purpose、provider、model、fallback	RAGFlow / future ModelClient。

配置验收：

• 配置文件必须能被 schema 校验。
• publishPath 必须位于 publish/**。
• 多个 source 的 publishPath 不能相同或互为父子目录。
• llm-wiki-approved 和 llm-wiki-working 必须在 RAGFlow 配置中可区分。

13.3 Workflow 占位到真实执行的升级路径

阶段	Workflow	初始状态	升级完成标准
W1	docs-sync.yml	可手动触发，占位输出 config/source summary	能读取 config/sources.yaml，生成 state/source-changes.json 和 Sync PR。
W2	docs-publish.yml	PR 触发，占位输出 publish dry-run summary	能生成 page manifest、publish impact、Docusaurus build 结果和 site manifest。
W3	docs-index.yml	手动触发，占位输出 target summary	能同步 RAGFlow approved/working dataset 和 Meilisearch，并写 index manifest。
W4	docs-agent.yml	手动触发，占位读取 issue/task id	能从 Issue/任务生成 AgentBridge report 和 Release PR。

所有 workflow 必须满足：

• 有固定 check 名称。
• 有 workflow_dispatch。
• 对写同一目标分支的流程设置 concurrency。
• 失败时输出 summary 和错误原因。
• 不直接写 main。

13.4 PR 治理落地

PR 类型	分支	必须携带	合并前阻断条件
Sync PR	docs-sync/source-updates	source changes、冲突、删除候选、source lock 说明	schema 失败、路径越界、冲突未说明。
Release PR	docs-release/*	影响页面、证据、build/index dry-run、相关 Issue	Docusaurus build 失败、无证据事实改写、越权路径。
Config PR	docs-config/*	config impact、受影响 source/dataset/policy	publishPath 冲突、agent scope 扩大未说明、secret 明文。

PR 验收：

• main 只能通过 PR merge 更新。
• Sync PR 默认可以是 Draft。
• Release PR 必须人工审批。
• Config PR 必须说明影响范围。

13.5 Manifest 落地

Manifest	生成时机	必须字段	失败处理
state/source-changes.json	sync dry-run / sync run	runId、sourceId、changes、conflicts、errors	失败时仍输出错误报告。
state/page-manifest.json	publish dry-run / publish run	documentId、path、url、contentHash、qualityStatus、qaVisible、indexable、EditContext	无法生成则阻断发布。
state/publish-impact-report.json	PR / release dry-run	baseRef、headRef、changedPages、build、errors	阻断项进入 PR check。
state/publish-manifest.json	publish success	publishRunId、gitCommit、pages	Docusaurus 失败不得生成成功态。
state/site-manifest.json	display build/deploy	url、sourceHash、renderedHash、status	缺页或漂移进入 failed/partial。
state/index-manifest.json	index run	publishRunId、gitCommit、targets、errors	target 失败不回滚 Git。

13.6 Issues 落地

Issue 流程	输入	输出	验收
页面反馈	page path、message、caller	docs-feedback Issue	包含 pagePath、sourceProject、dedupeKey。
无答案反馈	question、scope、noAnswerReason	qa-no-answer Issue	重复问题命中同一开放 Issue。
来源冲突	sourceId、publishPath、hashes	source-conflict Issue 或 Sync PR section	不覆盖 publish 内容。
改进任务	goal、scope、evidence	improvement-task Issue	可加 agent-ready 进入 AgentBridge。

13.7 Secrets / Variables 落地

项	验收	阻断条件
GH_DOCS_TOKEN	能读来源仓库、写候选分支、创建 PR/Issue	使用 classic 全权限 PAT。
RAGFLOW_API_KEY	能访问 approved/working dataset	key 出现在日志或 manifest。
MEILI_MASTER_KEY	能写目标 index	key 出现在日志或 PR。
RAGFLOW_APPROVED_DATASET	值为 approved dataset	正式问答 dataset 缺失。
RAGFLOW_WORKING_DATASET	值为 working dataset	AgentBridge 无工作上下文 dataset。

14. 文档发布环节完成定义

kunora-docs 文档发布环节改造完成，必须同时满足以下条件：

1. 来源项目文档可以通过 config/sources.yaml 进入 Sync PR。
2. Sync PR 合并后，内容进入 main/publish/**。
3. docs-publish.yml 可以基于 main/publish/** 生成 page manifest、publish impact、publish manifest 和 site manifest。
4. Docusaurus 构建失败不会生成成功态 manifest。
5. docs-index.yml 可以基于 publish/site manifest 生成 index manifest。
6. RAGFlow approved dataset 与 working dataset 在配置和 manifest 中语义分离。
7. Meilisearch 只作为搜索目标，不参与答案事实链。
8. 页面 metadata 包含 EditContext，能支撑 GitHub 编辑/Issue/PR 入口。
9. 无答案或低置信反馈能进入 GitHub Issue，并通过 dedupeKey 去重。
10. 所有正式内容变更都经过 PR，不存在 workflow 或 agent 直写 main。
11. page/publish/site/index manifest 的正式交接文件位于 state/**；GitHub artifact 不作为下游唯一输入。

15. 改造顺序建议

优先级：

1. 先完成仓库骨架、配置和 schema。
2. 再完成 sync dry-run 和 Sync PR。
3. 再完成 publish dry-run、Docusaurus build 和 manifest。
4. 再接入 RAGFlow/Meilisearch。
5. 最后接入反馈和 AgentBridge。

16. 开放问题

• kunora-docs 初始是公开仓库还是私有仓库。
• 初始来源项目清单和各自 docs-publish 分支是否已准备好。
• Docusaurus 静态托管使用 GitHub Pages 还是其他平台。
• Answer API / Agent Access API 是否先部署为 serverless，还是先以内部服务形式运行。