如何自動化Google反重力審計：構建自我維護的自定義技能和規則

📅 發布日: 2026/07/12, 更新日: 2026/07/12 ⏱️ 預計閱讀時間約10分鐘 (3,813字)

當你定製像Google Antigravity這樣的人工智慧助手時，規則和技能可能會變得太多而無法管理。
本文介紹如何構建自我維護的自定義技能（反重力審計），讓AI代理稽核並自動最佳化自己的配置。

概述
“配置混亂”問題
設計“反重力審計”
1. 主要特點
2. 🔄 執行流程
🔍“反重力審計”掃描的具體審計觀點
1. 1.靜態驗證（程式設計檢查）
2. 2. AI定性審查和調整建議（LLM驅動的檢查）
🌐 透過 Selenium 自動同步“外部規範和規則”
1. 執行流程
📊 真實的審計報告示例
🛠️“自動修復”的機制
🔄 日常開發和工作流程整合
🔗 GitHub 儲存庫
結論

如何自動化Google反重力審計：構建自我維護的自定義技能和規則

概述

當您使用人工智慧編碼助手（例如 Google Antigravity 或 Claude Code）時，您會注意到配置檔案和自定義技能快速積累。這可能會導致所謂的“配置混亂”。在本文中，我們介紹如何構建一種名為“反重力稽核”的自我維護自定義技能，它可以自動掃描、診斷和最佳化您的配置，以及乾淨的行動式設計模式。

“配置混亂”問題

AI 編碼助手的引入通常會導致在專案本地和使用者全域性資料夾中快速構建行為規則（例如 RULES.md、AGENTS.md）和自定義指令碼（例如 SKILL.md）。

這種快速增長帶來了一些管理挑戰：
1. 過時的規則 ：過時的指令保持活動狀態，使人工智慧的上下文視窗變得混亂。
2. 損壞的技能 ：缺少指令碼引用或過時的依賴項會中斷執行。
3. 不同步的雙語文件 ：一種語言的文件更新使另一種語言過時。

手動檢查這些檔案非常繁瑣。一個優雅的解決方案是 將 AI 配置的稽核委託給 AI 助手本身 。

設計“反重力審計”

“antigravity-audit”自定義技能掃描目標目錄，診斷配置和技能，建立乾淨的 Markdown 診斷報告，並嘗試自動修復小問題。

主要特點

雙語工作空間檢測 ：
掃描根檔案（例如 SKILL.md、README.md）以檢測日語字元的比例。根據該比率，技能動態確定是否以日語或英語輸出審計報告。
技能完整性檢查 ：
驗證 YAML frontmatter 是否包含必需的屬性（“name”、“description”）並標記死指令碼引用。
規則重複資料刪除 ：
掃描全域性和專案級別的冗餘規則，並提出清理建議。

🔄 執行流程

下圖說明了從觸發稽核技能到應用環境補丁的操作順序。

sequenceDiagram autonumber actor Developer as Developer participant Audit as audit.py participant Selenium as Selenium (Headless) participant Spec as Spec Site (Web) participant Agent as AI Agent (LLM) participant Patch as apply_patch.py Developer->>Audit: Launch Skill (python3 scripts/audit.py) rect rgb(240, 248, 255) note right of Audit: Self-Update Phase Audit->>Selenium: Instruct Spec Scraping Selenium->>Spec: Fetch Live Guidelines (Antigravity 2.x) Spec-->>Selenium: Rendered Page DOM Selenium-->>Audit: Crawled Spec Data (Markdown/JSON) note right of Audit: Compare and self-update script if out-of-date end rect rgb(245, 245, 245) note right of Audit: Workspace Scan Phase Audit->>Audit: Scan target folder (.agents/) Audit->>Audit: Detect document language ratio end rect rgb(255, 245, 238) note right of Audit: Verification & Review Phase Audit->>Audit: Run static validations (YAML/JSON schema, Sidecar, MCP etc) Audit-->>Agent: Present static result and file list Agent->>Agent: Run LLM Qualitative Review (analyzing Hooks, Subagents, etc) Agent-->>Audit: Return Qualitative Tuning proposals end Audit-->>Developer: Output Audit Report (audit_report.md) Developer->>Developer: Review suggestions and approve patch Developer->>Patch: Run Patch Command (python3 apply_patch.py --patch [file]) Patch-->>Developer: Safely apply changes to target files

①自我更新階段 ：
為了確保與最新指南同步，該技能在啟動時啟動基於 Selenium 的官方規範抓取，如果發生不匹配，則會自動修補並重新啟動。
②工作空間掃描階段 ：
發現全域性和專案級“.agents/”設定，解析日語/英語比率，以正確的目標語言格式化輸出報告。
③驗證和審查階段 ：
執行程式設計檢查器（架構佈局、MCP 端點、鉤子語法、Sidecar 鍵），然後將資料傳輸到 AI 代理，以根據調優檢查表生成定性最佳化。
④ 報告和補丁申請 ：
儲存 Markdown 審計報告（ audit_report.md ）以供使用者驗證。一旦獲得批准，補丁將使用“apply_patch.py”安全應用。

🔍“反重力審計”掃描的具體審計觀點

為了防止人工智慧開發環境惡化，該技能結合了法學碩士支援的程式化“靜態驗證”和“人工智慧定性審查”進行檢查。

1.靜態驗證（程式設計檢查）

使用“audit.py”和診斷子模組，可以自動驗證以下專案：

評價專案	檢視詳情	目標/目的
模式一致性	檢查“SKILL.md”是否包含有效的 YAML frontmatter 和正確的 JSON 語法/強制屬性。	確保系統正確解析並載入自定義技能。
規則說明規則	驗證規則 frontmatter ( `rules/*.md` ) 中的 `description` 是否在 150 個字元以內。	在 UI 環境中保持清晰的列表可讀性。
物理複製	檢測跨全域性（ `~/.gemini/config/` ）和本地（ `.agents/` ）位置物理複製的重複規則或技能檔案。	防止配置衝突並修剪冗餘檔案。
Sidecar 支援 ⚡	如果“sidecar.json”存在，則驗證“~/.gemini/config/config.json”中的“sidecars. .enabled”是否設定為“false”。	防止後臺守護程式因缺少配置金鑰而無法啟動。
外掛放置⚡	驗證外掛是否正確放置在支援的路徑中：“.agents/plugins/”或“_agents/plugins/”。	防止執行時外掛載入異常。
MCP 架構檢查 ⚡	檢查“mcp_config.json”中的遠端配置是否使用有效的“serverUrl”欄位而不是不支援的欄位。	避免與外部 MCP 主機的遠端連線異常。
Hook Agent停止驗證 ⚡	確保“hooks.json”中定義的“AgentStop”事件返回包含“decision”欄位的 JSON 輸出。	防止未處理的鉤子導致執行流突然終止。
大腦日誌歷史分析 ⚡	掃描最近的會話日誌和錯誤發生情況，以動態診斷反重力配置最佳化（AUD-08 至 AUD-10）。	自動解決重複編譯/執行異常和工作流程摩擦。

2. AI定性審查和調整建議（LLM驅動的檢查）

執行靜態檢查後，AI 代理會審查配置檔案以提出結構改進建議：

評價專案	檢視詳情	目標/目的
掛鉤轉換	建議將 Linter、格式化或測試指令碼遷移到“hooks.json”事件中，而不是主動技能步驟中。	自動執行關鍵斷言並避免手動執行疏忽。
全球/本地安置	建議將可重用的一般準則移至全域性設定，並將特定於專案的上下文移至專案本地路徑。	最佳化上下文視窗的使用並提高規則重用。
邊車遷移	建議將後臺偵聽器或重複的 cron 作業包裝到“sidecar.json”結構中以作為系統守護程序執行。	從活動對話執行中解除安裝阻塞操作。
子代理委託	建議使用“invoke_subagent”將繁重的操作（例如大規模程式碼庫掃描或E2E測試）解除安裝給子代理。	繞過父上下文視窗限制（65,536 個令牌）並執行非同步任務。
外掛包裝	建議將相關技能、規則、MCP 設定和掛鉤打包到一個名稱空間分隔的外掛中。	簡化自定義功能管理並乾淨地分配設定。
最低許可權	建議將萬用字元 ( `*` ) 執行許可權縮小到特定命令字首或目錄。	維護沙箱完整性並防止危險的命令執行。
邏輯整合	解決在不同檔名下共享相似指令的規則，使用“現狀 -> 未來”比較表合併它們。	修剪冗餘準則並保持規則令牌佔用空間較小。
故障安全鉤	建議使用鉤子來阻止代理嘗試使用“–no-verify”提交或修改設定配置。	避免意外繞過驗證標準。
記憶體一致性	驗證進度檔案 ( `task.md` ) 和狀態快取 JSON 之間的一致性。	保持代理的進度指示器同步。
鉤子成本評估	稽核掛鉤超時和數量，以避免響應延遲和不必要的令牌計費。	透過避免緩慢的往返來最佳化開發人員體驗 (DX)。
規則/技能建議	提出與專案獨特技術堆疊或 API（例如 Vertex AI）相匹配的自定義規則/技能。	防範技術堆疊特定的陷阱並加快實施速度。

🌐 透過 Selenium 自動同步“外部規範和規則”

規則稽核的另一個關鍵支柱是 “規則集新鮮度管理” 。
AWS 和 GCP 等雲服務的官方規範以及 AI 工具文件（例如 Antigravity 本身）會頻繁更新。如果本地儲存的規則 (RULES.md) 保持靜態，AI 助手將繼續生成過時的配置和已棄用的命令呼叫。

為了解決這個問題，“antigravity-audit”支援 使用 Selenium（無頭 Chrome） 自動網路爬行和抓取官方規範網站**以獲取最新指南。

執行流程

動態文件獲取 ：Selenium 控制無頭 Chrome 例項來導航缺乏標準化 API 的公共參考站點或發行說明，將 HTML 表/文件轉換為 Markdown 或 JSON。
差異檢測 ：根據爬取的實時規範解析並比較本地規則（例如“port_allocation.md”埠表或命令引數）。
自動規則修補 ：在稽核報告中提醒使用者不推薦使用的命令或更新的端點，為可自動更新的欄位生成補丁檔案。

此機制可確保您的本地規則上下文與最新的行業規範保持同步，而無需人工干預。

📊 真實的審計報告示例

以下是執行“antigravity-audit”時生成的實際 Markdown 報告輸出的示例。它使用視覺警報（“❌錯誤”、“⚠️警告”）和 GitHub 風格的警報來輕鬆識別問題。

# 🛡️ Antigravity Environment Audit Report

> [!NOTE]
> Scan completed at: 2026-07-12 19:40:00 (JST)
> Detected primary language: English (en)

## 📈 Diagnostic Summary

| Category | Checks Run | Issues Found | Auto-fix Status |
| :--- | :---: | :---: | :---: |
| Global Rules (AGENTS.md) | 12 | 1 | 🛠️ Auto-fixed |
| Project Rules (RULES.md) | 8 | 0 | ✅ No issues |
| Custom Skills (skills/) | 15 | 2 | ⚠️ Action Required |

---

## 🚨 Diagnostic Alert Details

### 1. Duplicate Rule in Global Settings
- **File**: `~/.gemini/config/AGENTS.md`
- **Status**: `⚠️ Warning`
- **Details**: The rule forbidding "Chrome automation" duplicates a project-level definition in `.agents/RULES.md`.
- **Action**: Automatically removed the duplicate rule section from the global configuration to optimize context. (**Auto-fix completed**)

### 2. Missing YAML Frontmatter Field in Custom Skill
- **File**: `skills/aws-deploy/SKILL.md`
- **Status**: `❌ Error`
- **Details**: Missing the mandatory `description` field required by the skill loader.
- **Action**: Please open `skills/aws-deploy/SKILL.md` manually and add a suitable description to its frontmatter block.

### 3. Broken Executable Reference in Custom Skill
- **File**: `skills/house-keeping/SKILL.md`
- **Status**: `❌ Error`
- **Details**: The helper script `scripts/cleanup.sh` referenced in `SKILL.md` is missing or lacks executable permissions.
- **Action**: Check if the file exists and verify if `chmod +x` has been run.

🛠️“自動修復”的機制

除了簡單地報告問題之外，“antigravity-audit”還可以安全地解決特定配置：

自動填充 YAML Frontmatter ：
如果“SKILL.md”缺少 YAML frontmatter，AI 模型會解析技能內容，動態推導名稱和描述，並自動在檔案頂部插入 frontmatter 塊。
合併冗餘規則 ：
當全域性和本地存在相同的規則時，它會註釋掉或清除優先順序較低的全域性規則，從而幫助將代幣消耗保持在最低限度。

🔄 日常開發和工作流程整合

我們建議將此稽核工作流程整合到您的日常開發週期中：

每週或每月定期稽核（推薦） ：
由於規則上下文和技能不斷增長，因此請安排 每週或每月維護日 來執行稽核指令碼。這允許環境執行狀況檢查和清理任務，而不會降低本地提交速度（DX）。
CI/CD 管道整合 ：
建立或合併 Pull 請求時，在 CI/CD 環境（例如 GitHub Actions）中自動執行稽核指令碼，以驗證規則和技能的格式是否正確，而不會降低本地提交速度。
手動按需指令 ：
當開始與 AI 代理的會話時，使用簡單的提示請求掃描：
> “執行自動稽核技能來掃描我當前的自定義技能和規則。自動解決任何冗餘規則或格式錯誤。”

🔗 GitHub 儲存庫

自動稽核技能的配置模板和本部落格的原始碼可在以下 GitHub 儲存庫中找到：

👉 kanji-shinohara/web-gcp-us-firebase-moderniser-repo

結論

為了最大限度地提高人工智慧編碼代理的效率，我們的開發環境必須保持組織和最佳化。將自我維護任務委託給自定義技能可以讓開發人員專注於主動編碼。