GitHub、Cloudflare 与团队共创

为什么需要部署

当前 MkDocs 站点如果只在个人电脑上运行，就只能本地访问。对于一个五六人的 AI 原生创业团队，更合理的方式是把源码放在 GitHub private repo，把站点部署到 Cloudflare Pages，并用 Cloudflare Access 做访问控制。

这样可以同时获得：

• 团队所有人都能访问。
• Git 天然支持多人协作。
• GitHub PR 支持 review、讨论和变更记录。
• GitHub Actions 做构建验证。
• Cloudflare Pages 自动部署。
• Cloudflare Access 做邮箱白名单或 SSO 访问控制。
• 微信群继续作为日常讨论和通知入口。

推荐结构

GitHub Repository
  - workspaces/variai/site/*.md
  - mkdocs.yml
  - pyproject.toml
  - GitHub Actions CI
        ↓
Cloudflare Pages
        ↓
Cloudflare Access
        ↓
微信群发布链接

当前 Cloudflare Pages 站点：

• https://harness-3xv.pages.dev/

当前发布关系：

• VariAI/OrgReOrg 是团队协作仓库，也是 fetch/pull 来源。
• alpc91/harness 是 Cloudflare Pages 绑定的发布镜像。
• 团队成员和 Agent 应从团队仓库拉取变更；发布时把同一个 main 推送到两个仓库。

当前阶段：私有仓库

当前建议先使用 private repo。虽然目前内容还不涉及核心敏感信息，但后续会逐渐沉淀真实组织场景、内部流程和交付方法，早一点把访问边界立住更稳。

适合放在仓库中的内容：

• 产品理念。
• 抽象架构。
• 教程结构。
• 非客户敏感的路线图。
• 通用方法论。

不适合公开的内容：

• 客户名称和合同信息。
• 内部账号、token、密钥。
• 未公开商业数据。
• 客户真实流程细节。
• 具有竞争敏感性的交付方案。

GitHub Team 和协作者

早期可以直接邀请协作者。团队稳定后，建议创建 GitHub Organization，用 team 管理权限。

建议权限：

角色	权限	说明
Founder / Maintainer	Admin / Maintain	管理仓库、Pages、权限和发布策略
Core Engineer	Write	直接创建分支、提交 PR、修复文档和代码
Contributor	Triage / Write	提交 issue、讨论、PR
External Advisor	Read	只读访问指定材料

Agent 原生协作方式

团队成员全部使用 Agent 做任务时，可以约定：

• 每个重要想法都落到 issue、PR 或飞书纪要。
• Agent 修改文档后可跑 mkdocs build --strict 做站点局部快查；提交 PR 前跑 bash scripts/ci_check.sh（与 CI 同一套门禁），全绿即就绪。
• 重要架构变化写入 workspaces/variai/site/knowledge/decision-log.md。
• 新场景写入对应专题页。
• 每次合并到 main 自动发布 Pages。

标准 GitHub 协作流程

main 是共享集成分支，也是 Cloudflare Pages 的发布源，不作为日常开发分支。每个团队成员和他的 Agent 都应该使用自己的工作分支：

main
  <- PR from alpc91
  <- PR from <github-handle>
  <- PR from <github-handle>/<topic>

ALPC91 负责的工作默认使用 alpc91 分支。其他协作者应使用自己的 GitHub handle 或 handle/topic 作为分支名，例如 wecom-adapter 负责人可以使用自己的名字或 name/wecom-adapter。

标准流程：

git fetch origin
git switch <your-branch>
git merge origin/main

# 开发、生成文档、运行测试
git add <changed-files>
git commit -m "type: short summary"

git fetch origin
git merge origin/main
# 如果有冲突，只在当前工作分支解决，解决后重新运行测试

git push origin <your-branch>
# 打开 <your-branch> -> main 的 PR

PR 描述必须说明：

• 本轮目标是什么。
• 改了哪些代码、Evidence、Knowledge、Registry 或 Site 页面。
• 跑了哪些验证命令。
• 有没有未解决风险、外部依赖或需要人工 review 的地方。

冲突必须在工作分支本地解决，不在 GitHub 网页上临时处理复杂冲突。原因是本地可以重新跑测试、生成页面、检查 package boundary 和 MkDocs strict build，能避免漏生成文件、漏更新 registry 或引入只在线上才暴露的问题。

main 的合并记录应体现一次完整研发单元。默认不直接 push main、不 fast-forward 本地 main 代替 PR、也不 squash 掉上下文。只有在维护者明确授权“一次性直接推 main”时，才允许跳过 PR。

PR 合并到 main 后，再把同一个 main 推送到 ALPC91 mirror，用于触发 Cloudflare Pages 发布。ALPC91 mirror 只是发布镜像，不作为团队开发的 pull/fetch 来源。

与飞书的关系

当前阶段不一定需要飞书 Wiki。对于五六个 AI 原生工程师组成的小团队，更轻的组合是：

• GitHub：正式文档、PR、review、版本历史。
• Cloudflare Pages：团队私有阅读网站。
• 微信群：日常讨论和链接通知。

当团队成员增多、非工程成员增多、会议纪要和流程文档变复杂时，再考虑引入飞书 Wiki 或其他知识库。

Cloudflare Pages 构建配置

Root directory：

/

构建命令：

python -m pip install uv
uv sync --locked
uv run mkdocs build --strict

输出目录：

site

MkDocs 源码目录不需要在 Cloudflare 单独配置；仓库里的 mkdocs.yml 已经设置：

docs_dir: workspaces/variai/site
site_dir: site

依赖源规则：

• 仓库提交的 uv.lock 必须使用公共 PyPI 作为可复现来源，仓库级 uv.toml 会把默认 index 固定到 PyPI。
• 国内镜像只用于本地临时加速，例如通过单次命令的 UV_DEFAULT_INDEX 覆盖。
• 不要把清华源、公司内网源或其他环境专属源写进提交的 lockfile；GitHub Actions 和 Cloudflare Pages 的外部 runner 可能无法访问这些镜像，导致发布镜像构建失败。