GitHub、Cloudflare 与团队共创¶
为什么需要部署¶
当前 MkDocs 站点如果只在个人电脑上运行，就只能本地访问。对于一个五六人的 AI 原生创业团队，更合理的方式是把源码放在 GitHub private repo，把站点部署到 Cloudflare Pages，并用 Cloudflare Access 做访问控制。
这样可以同时获得：
- 团队所有人都能访问。
- Git 天然支持多人协作。
- GitHub PR 支持 review、讨论和变更记录。
- GitHub Actions 做构建验证。
- Cloudflare Pages 自动部署。
- Cloudflare Access 做邮箱白名单或 SSO 访问控制。
- 微信群继续作为日常讨论和通知入口。
推荐结构¶
text
GitHub Repository
- docs/*.md
- mkdocs.yml
- pyproject.toml
- GitHub Actions CI
↓
Cloudflare Pages
↓
Cloudflare Access
↓
微信群发布链接
当前 Cloudflare Pages 站点：
当前发布关系：
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。 - 重要架构变化写入
docs/knowledge/decision-log.md。 - 新场景写入对应专题页。
- 每次合并到
main自动发布 Pages。
与飞书的关系¶
当前阶段不一定需要飞书 Wiki。对于五六个 AI 原生工程师组成的小团队，更轻的组合是：
- GitHub：正式文档、PR、review、版本历史。
- Cloudflare Pages：团队私有阅读网站。
- 微信群：日常讨论和链接通知。
当团队成员增多、非工程成员增多、会议纪要和流程文档变复杂时，再考虑引入飞书 Wiki 或其他知识库。
Cloudflare Pages 构建配置¶
构建命令：
bash
python -m pip install uv
python -m uv sync --locked
python -m uv run mkdocs build --strict
输出目录：
text
site