如何自动化Google反重力审计：构建自我维护的自定义技能和规则

📅 发布日: 2026/07/12, 更新日: 2026/07/12 ⏱️ 预计阅读时间约9分钟 (3,777字)

当你定制像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

结论

为了最大限度地提高人工智能编码代理的效率，我们的开发环境必须保持组织和优化。将自我维护任务委托给自定义技能可以让开发人员专注于主动编码。