Kunora Docs 文档收集与发布输入设计

1. 结论

kunora-docs 是 Kunora 文档发布输入仓库。当前确定边界是：main/publish/** 是下游 Docusaurus 服务器、搜索索引和问答索引的唯一正式输入。

系统拆成两个明确流程：

1. 自动收集流程：定时从各组件仓库的稳定文档来源收集 docs/**，按配置同步到 publish/technology/components/<component>/，并发起 Sync PR。
2. 自身文档发布流程：kunora-docs/docs/** 是作者工作区，变更后同步到 publish/technology/components/kunora-docs/，并发起 Self Docs PR。

PR 合并到 main 后，main/publish/** 就是最终发布版内容。Docusaurus 构建和线上部署由下游 Docusaurus 服务器消费 main/publish/** 完成，不在 kunora-docs 内直接构建页面。

2. 核心约束

1. 组件仓库必须提供稳定文档来源：docs-publish ref 下的 docs/**。
2. config/sources.yaml 决定每个组件的来源仓库、来源 ref、来源目录和写入目录。
3. 自动收集不理解组件文档内部结构，只把 sourcePath 整体同步到配置的 publishPath。
4. 同步必须覆盖新增、更新、删除，同时不能覆盖 publish/** 中已发生的人工或智能体整理结果。
5. publishPath 必须唯一，不能重复，不能互为父子目录，避免两个来源互相污染。
6. kunora-docs/main 的 publish/** 是唯一正式发布输入。
7. 工作流不能直接 push main，所有自动写入都必须通过 PR。

3. 仓库结构

kunora-docs/
  config/
    sources.yaml
    self-docs.yaml
    site.yaml
    publish.yaml
    index.yaml

  docs/
    kunora-docs-implementation-design.md

  publish/
    system/
      components/
        kunora-docs/
        kunora-kgent/
        kunora-agent-memory/
        kunora-wiki/

  state/
    source-lock.json
    source-lock.previous.json
    source-changes.json
    publish-plan.json
    publish-impact-report.json
    page-manifest.json
    publish-manifest.json
    site-manifest.json
    index-manifest.json

  scripts/
    sync_sources.py
    render_sync_pr_body.py
    sync_self_docs.py
    validate_docs.py
    publish_wikijs.py
    build_index_manifest.py

  .github/workflows/
    docs-sync.yml
    docs-self-sync.yml
    docs-publish.yml
    docs-index.yml

4. 组件来源配置

config/sources.yaml 示例：

version: 1

sources:
  - id: kunora-kgent
    type: github
    repo: https://github.com/innuama-coder/kunora-kgent.git
    localPath: ../kunora-kgent
    ref: docs-publish
    sourcePath: docs
    publishPath: publish/technology/components/kunora-kgent
    deletePolicy: sync-if-unmodified
    conflictPolicy: report-only
    include:
      - "**/*.md"
      - "**/*.png"
      - "**/*.jpg"
      - "**/*.jpeg"
      - "**/*.svg"
      - "**/*.gif"
    exclude:
      - "**/.DS_Store"

字段含义：

字段	含义
id	来源项目唯一标识。
type	来源类型，当前为 github。
repo	上游 GitHub 仓库。
localPath	本地调试路径，CI 使用 --remote 时不依赖。
ref	稳定文档来源 ref，当前约束为 docs-publish 分支。
sourcePath	上游文档根目录，当前约束为 docs。
publishPath	写入 kunora-docs 的发布目录，必须位于 publish/**。
deletePolicy	来源删除如何应用，当前默认 sync-if-unmodified。
conflictPolicy	来源和发布目录并发变化如何处理，当前为 report-only。
include / exclude	文件过滤规则。

5. 流程一：自动收集组件文档

触发方式：

workflow_dispatch:
schedule:
  - cron: "0 */6 * * *"

执行逻辑：

1. GitHub Actions 每 6 小时运行，也支持手动触发。
2. sync_sources.py --remote 从每个来源的 docs-publish 分支读取 docs/**。
3. 对每个来源执行三方文件 diff。
4. 更新 publishPath 中可安全自动应用的新增、更新、删除。
5. 对并发变化只报告冲突，不覆盖人工或智能体整理结果。
6. 写入 state/source-lock.json、state/source-lock.previous.json、state/source-changes.json。
7. render_sync_pr_body.py 生成本次 Sync PR 的动态说明。
8. peter-evans/create-pull-request 创建或更新 docs-sync/source-updates draft PR。

三方 diff 状态：

A = 上一次 state/source-lock.json 中记录的来源基线
B = 当前组件 docs-publish:docs/**
C = 当前 kunora-docs publishPath/**

动作定义：

动作	条件	结果
add	B 存在，A/C 不存在	复制到 publishPath，更新 lock。
update	B 相对 A 改变，C 等于 A	覆盖 C，更新 lock。
delete	B 删除，C 等于 A，且 deletePolicy=sync-if-unmodified	删除 C，移除 lock。
keep	B 等于 A，C 相对 A 改变	保留 C，不更新 lock。
conflict	B 和 C 都相对 A 改变且内容不同	不写入文件，保留旧 lock，写入冲突报告。
delete_conflict	B 删除但 C 已改变，或删除策略为 report-only	不删除文件，保留旧 lock，写入冲突报告。
unchanged	B/C 与 A 一致，或 B/C 已收敛	不改文件，必要时更新 lock。

6. 流程二：发布 kunora-docs 自身文档

kunora-docs/docs/** 只是作者工作区，不直接被 Docusaurus 或索引消费。自身文档必须先同步到 publish/technology/components/kunora-docs/**，再通过 PR 合并到 main。

触发方式：

1. 手动触发 docs-self-sync.yml。
2. main 分支中 docs/**、config/self-docs.yaml 或 scripts/sync_self_docs.py 变化后自动触发。

7. 发布输入与下游交接

docs-publish.yml 不负责构建 Docusaurus 页面。它负责校验 publish/**，并生成可审计的发布计划和 manifest。下游 Docusaurus 服务器以 main/publish/** 为构建输入。

docs-index.yml 当前生成索引交接 manifest，描述 RAGFlow approved/working dataset 和 Meilisearch 的计划文档数量。它在 workflow_run 模式下读取 docs-publish.yml 上传的 manifest artifact，手动运行时先本地生成 publish manifest。真实外部索引写入属于后续 adapter 工作，不在当前仓库内伪实现。

docs-agent.yml 不运行 LLM。外部智能体必须先把文档迭代结果提交到一个分支，工作流只负责校验该分支只能修改 publish/**，生成发布影响报告，然后创建或更新 draft Release PR。这样可以保证智能体不能绕过 PR 审批直接修改 main。

8. 运行命令

安装依赖：

pip install -r requirements.txt

本地调试组件收集：

python scripts/sync_sources.py
python scripts/render_sync_pr_body.py

CI 组件收集必须使用远端配置 ref：

python scripts/sync_sources.py --remote
python scripts/render_sync_pr_body.py

同步自身文档：

python scripts/sync_self_docs.py

校验发布输入并生成交接产物：

python scripts/validate_docs.py
python scripts/publish_wikijs.py --dry-run --write-manifest
python scripts/build_index_manifest.py

校验智能体产物分支：

python scripts/validate_agent_changes.py --base origin/main --publish-root publish
python scripts/render_agent_pr_body.py

9. 当前来源

Source	Required ref	Source path	Publish path
kunora-kgent	docs-publish	docs/	publish/technology/components/kunora-kgent/
kunora-agent-memory	docs-publish	docs/	publish/technology/components/kunora-agent-memory/
kunora-wiki	docs-publish	docs/	publish/technology/components/kunora-wiki/
kunora-docs	main authoring docs	docs/	publish/technology/components/kunora-docs/