跳到主要内容

GitHub 技术方案

# GitHub 技术方案

1. 覆盖范围​

GitHub 在 MVP 中不是单一工具，而是 LLM-WIKI 的治理底座。

它支撑以下产品和特性：

LLM-WIKI 产品GitHub 支撑能力产品特性
GitHub 文档源来源项目仓库、docs-publish 分支、tag稳定文档发布源
LLM-WIKI 控制仓库kunora-docs repo、配置、状态、发布目录受管内容源
文档收集器Actions、token、跨仓库 clone定时收集、手动收集
发布工作目录publish/** Git diff可审查发布工作区
审批与治理台Pull Requests、reviews、branch protection、checksHuman-approved
反馈与任务产品Issues、labels、assignees、PR 关联问答反馈和文档改进任务
权限与身份产品GitHub users/teams、PAT、后续 GitHub App权限控制和审计
运行基础设施GitHub Actions schedule/workflow_dispatch定时执行和发布流水线

2. 如何购买​

2.1 MVP 购买建议​

MVP 可以从 GitHub Free 或 GitHub Team 开始。

选择规则：

场景建议
仓库公开，团队小，Actions 用量低GitHub Free 可启动
私有仓库、团队协作、需要更稳定权限治理GitHub Team
企业 SSO、审计、组织级安全、更多 Actions 用量GitHub Enterprise Cloud，暂不作为 MVP 必需

GitHub Actions 对公开仓库的标准托管 runner 通常免费；私有仓库按计划包含免费分钟数，超出后计费。具体额度和价格以 GitHub 官方 billing 页面为准。

2.2 MVP 不建议购买的能力​

  • 不需要先购买 GitHub Enterprise。
  • 不需要先上大型 runner。
  • 不需要先建设自托管 runner，除非 Actions 用量或网络访问成为瓶颈。

3. 如何开发​

3.1 仓库结构​

MVP 使用一个控制仓库：

kunora-docs/
  config/
    sources.yaml
    site.yaml
    publish.yaml
  docs/
    llm-wiki/
  publish/
    system/components/...
  scripts/
    sync_sources.py
    detect_changes.py
    validate_docs.py
    publish_backend.py
    index_docs.py
  state/
    source-lock.json
    source-changes.json
  .github/workflows/
    docs-sync.yml
    docs-publish.yml
    docs-index.yml

3.2 分支模型​

分支用途写入者
main已审批正式内容PR merge
docs-sync/source-updates上游同步 PR 分支GitHub Actions
docs-release/*智能体或人工整理后的 release PR智能体/人
来源项目 docs-publish来源项目稳定文档发布分支来源项目维护者

规则：

  • main 必须保护，禁止直接 push。
  • 来源项目必须提供 docs-publish 或约定 tag 前缀。
  • 智能体不能直接写 main。
  • 发布系统只读取 main 上已审批内容。

3.3 PR 类型​

PR 类型触发源内容审批要求
Sync PR定时同步或手动同步上游文档进入 publish/** 的 diff可快速审查，冲突必须人工处理
Release PR智能体/人工整理面向发布的正式文档改动必须人工审批
Config PR配置调整config/**、workflow、adapter 配置必须审批

4. 如何部署​

4.1 GitHub Actions 工作流​

MVP 需要三个 workflow：

Workflow触发作用
docs-sync.ymlschedule + workflow_dispatch同步来源项目，生成 Sync PR
docs-publish.ymlPR/main 变更校验文档，构建 Docusaurus，生成发布计划
docs-index.ymlmain 合并或发布成功更新 RAGFlow dataset 和 Meilisearch 索引

4.2 docs-sync.yml 要求​

必须包含：

  • on.schedule 定时触发。
  • on.workflow_dispatch 手动触发。
  • permissions.contents: write 用于提交分支。
  • permissions.pull-requests: write 用于创建 PR。
  • concurrency 避免多个同步任务并发覆盖。

4.3 Secrets​

Secret用途MVP 是否必需
GH_DOCS_TOKEN跨私有来源仓库读取、创建 PR私有仓库必需
OPENAI_API_KEY 或其他模型 keyRAGFlow/Agent 调用模型智能体阶段必需
RAGFLOW_API_KEY调用 RAGFlow API智能体阶段必需
MEILI_MASTER_KEY访问 Meilisearch必需

MVP 可以先用 fine-grained PAT；进入长期运行后应升级为 GitHub App installation token。

5. 如何配置​

5.1 来源项目配置​

config/sources.yaml 示例：

sources:
  - id: kunora-kgent
    owner: innuama-coder
    repo: kunora-kgent
    ref: docs-publish
    sourcePath: docs
    publishPath: publish/system/components/kunora-kgent
    include:
      - "**/*.md"
      - "**/*.png"
      - "**/*.svg"
    deletePolicy: sync-if-unmodified
    conflictPolicy: report

5.2 分支保护配置​

main 分支应启用：

  • Require a pull request before merging。
  • Require approvals。
  • Require status checks to pass。
  • Restrict force pushes。
  • Restrict deletions。

5.3 Issue 标签​

MVP 建议标签：

Label用途
docs-feedback用户页面反馈
qa-no-answer问答无答案
qa-wrong-answer问答错误
agent-ready可交给智能体处理
source-conflict上游同步冲突
release-blocker阻塞发布

6. 如何使用​

6.1 来源项目维护者​

  1. 在来源项目维护 docs/**。
  2. 将准备发布的文档合入 docs-publish。
  3. 不直接发布到文档站。

6.2 LLM-WIKI 维护者​

  1. 查看 Sync PR。
  2. 处理冲突。
  3. 合并进入发布工作目录。
  4. 创建或触发智能体迭代任务。
  5. 审批 Release PR。
  6. 合并后触发发布和索引。

6.3 智能体​

  1. 读取 GitHub Issue 或人工任务。
  2. 读取 publish/** 和索引上下文。
  3. 生成文档修改。
  4. 创建 Release PR。
  5. 等待人工审批。

7. 验收标准​

验收项标准
来源治理至少两个来源项目通过固定 docs-publish 分支接入。
自动同步Actions 能定时同步并创建 PR。
审批治理main 禁止直接写入，所有正式变更经过 PR。
任务闭环问答反馈能生成 GitHub Issue。
权限最小化token 只具备所需仓库和权限。
可审计每次同步、整理、发布都有 commit、PR 或 workflow run。

8. 官方资料​

编辑此页
◇对此页面有疑问？

问答功能将在后续接入 Answer API。当前可通过页面底部的反馈链接提交问题。

页面来源草稿
来源项目kunora-wiki
分支docs-publish
路径technology/components/kunora-wiki/product/07-mvp-technical-solution/01-github.md