Architecture
三儲存庫流水線
Section titled “三儲存庫流水線”文件與治理系統涵蓋三個儲存庫，每個儲存庫承擔不同的職責：
| 儲存庫 | 角色 |
|---|---|
| docs-control | 中央治理中心 — 儲存庫設定、分支保護設定、託管檔案清單、可重用 CI 工作流、Antigravity AI 工作流、呼叫方工作流模板、agent skills 和下游分發 |
| docs-builder | Docker 建置映像檔 — Astro + Starlight 建置編排、npm 相依性、Puppeteer PDF 產生、互動式組件 |
| docs-theme | Astro Starlight 外掛程式 — 共享品牌、CSS、字型、標誌、版面組件、astro.config.mjs 和 content.config.ts |
內容儲存庫僅需要一個 docs/ 目錄。建置容器和工作流負責處理其餘所有事務。
當模板檔案或工作流在 docs-control 的 main 分支上發生變更時：
- 分發工作流 觸發並啟動每個下游儲存庫中的強制執行
- 強制執行工作流 將期望狀態與當前狀態進行比較，並修復任何漂移
- 檔案同步工作流 檢測發生漂移的託管檔案，建立一個包含規範內容的 PR，並對其自動合併
- 可重用的 Antigravity AI 工作流（
antigravity-review.yml和antigravity-translate.yml）在已註冊儲存庫的拉取請求上執行
Antigravity AI 自動化
Section titled “Antigravity AI 自動化”整個 Fleet 包含執行在 GitHub Actions runner 上的 Antigravity (agy) AI 自動化：
| 工作流 | 目的 | 觸發與執行 |
|---|---|---|
Antigravity Code Review (antigravity-review.yml) | 自動化的 AI 拉取請求程式碼審查 | 在建立或更新 PR 時執行。使用 Gemini 3.6 Flash (High) 審計 diff 以發現安全性漏洞、硬編碼金鑰、PII 洩漏和程式碼品質問題，並透過 PR 評論發布意見回饋。 |
Antigravity Language Translation (antigravity-translate.yml) | 自動化的 AI 文件語言翻譯 | 在修改 docs/en/**/*.md[x] 的 PR 上執行。執行 .agents/skills/i18n-translate/SKILL.md skill 以更新 12 個目標語言環境（fr, es, de, pt-br, ja, ko, zh-cn, zh-tw, ar, it, hi, th），更新 i18n.sourceHash，並自動提交回 PR 分支。 |
Token 與憑證模型
Section titled “Token 與憑證模型”三組憑證提供最小權限隔離：
| Token / Secret | 權限 / 作用域 | 使用者 |
|---|---|---|
REPO_SETTINGS_TOKEN | Administration R/W, Pages R/W, Contents Read, Metadata Read | enforce-repo-settings.yml, dispatch-downstream.yml, update-governed-workflow-pins.yml |
REPO_SYNC_TOKEN | Contents R/W, Issues R/W, Pull Requests R/W, Metadata Read | sync-managed-files.yml |
ANTIGRAVITY_TOKEN & GCP_PROJECT_ID | Antigravity AI Authentication & GCP Project Access | antigravity-review.yml, antigravity-translate.yml |
強制執行工作流需要管理員權限來修改分支保護和 Pages 設定。同步工作流需要內容和 PR 權限來建立分支、提交檔案和合併 PR。Antigravity AI 工作流使用專用專案憑證向 Gemini 3.6 Flash 進行身分驗證。
Docs-control 既是自身治理設定的提供者，也是使用者。當 enforce-repo-settings.yml 在 docs-control 本身執行（透過 push 觸發器）時，它透過比較 managed_files.source_repo 與 github.repository 來檢測到這一點。這會觸發分支保護中的 self_contexts 覆蓋 — docs-control 直接使用工作流（例如 Shell Unit Tests），而下游儲存庫使用呼叫方包裝器（例如 lint / Shell Unit Tests）。有關 contexts 與 self_contexts 的詳細資訊，請參閱設定頁面。
儲存庫版面配置
Section titled “儲存庫版面配置”| 目錄 / 檔案 | 目的 |
|---|---|
.github/config/repo-settings.json | 中央設定：儲存庫設定、分支保護、Actions 權限、Pages 設定以及託管檔案清單 |
.github/config/downstream-repos.json | 已註冊下游儲存庫的註冊表 |
.github/config/docs-sites.json | 每個下游文件網站的元資料（標籤、URL、描述），供 README 模板化使用 |
.github/workflows/ | 可重用工作流：強制執行、檔案同步、pages 部署、關聯 issue 檢查、分發、antigravity 審查和 antigravity 翻譯 |
.agents/skills/ | Agent skills 治理：demo-components、i18n-translate |
workflows/ | 下游儲存庫安裝到 .github/workflows/ 中的呼叫方模板 |
docs/ | 文件原始碼（透過 Astro Starlight 建置和部署） |
CONTRIBUTING.md | 貢獻者工作流規則（同步到所有下游儲存庫） |
CLAUDE.md | AI 助手指令（同步到所有下游儲存庫） |
AGENTS.md | 儲存庫 agent 指令和治理策略 |
README.md.tpl | 動態產生的下游 README 檔案的模板 |
.pre-commit-config.yaml | Pre-commit hooks 設定（同步到所有下游儲存庫） |
.markdownlint.json | Markdown linter 規則 |
.yamllint.yaml | YAML linter 規則 |