在 Google Antigravity 中使用 AG Kitrules、skills、workflows 与安全红线完整指南【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本篇指南面向在 Google Antigravity 工作区中引入 AG Kit 的开发者与 AI Agent 使用者系统讲解.agents/组件包rules、skills、workflows、agents、hooks、MCP 配置的正确加载与调用方式以及必须遵守的审批检查点与安全边界。读完本文你将掌握 AG Kit 在 Antigravity 下的组件发现机制、slash-command 工作流的使用原则、多专家代理编排策略以及如何在不削弱 Antigravity 原生权限控制的前提下验证破坏性命令防护。一、AG Kit 在 Antigravity 中的定位AG KitREADME.md是一套面向 Google Antigravity 的agent 工程套件仓库安装了一套完整的.agents/工作区契约由 Antigravity 作为生产运行时来发现和执行。项目在.agents/antigravity.json中声明了六个集成阶段discovery、mcp、hooks、orchestration、plugin、validation每个阶段都有对应的原生实现。.agents/hooks/plugin/GEMINI.md是该插件包附带的运行时使用说明其核心思路可以概括为七条规则规则持久化、技能渐进加载、命令可复用、角色专业化、审批保留、MCP 占位符禁用、Hook 边界克制。下面逐一展开并结合仓库源码说明底层原理。二、七条运行时使用规则详解1. 将rules/视为持久化工程约束AG Kit 要求把rules/作为始终生效的工程约束而不是一次性提示。仓库中的 .agents/rules/ 包含 6 份规则文件规则文件用途core-protocol.md核心协议always_on触发request-routing.md请求路由always_on触发universal-rules.md通用规则always_on触发code-rules.md编码约束model_decision触发design-rules.md设计约束glob触发quick-reference.md速查参考model_decision触发这些规则在 .agents/manifest.json 中被声明为带priorityP0/P2与trigger语义的受管组件例如core-protocol的触发方式为always_on而quick-reference优先级为 P2、按需决策加载。从清单结构看rules 是工作区路由、安全、设计与编码约束的地基Agent 在任意任务开始前都应先加载相关规则。2. 渐进发现skills/*/SKILL.md只加载相关技能AG Kit 不要求一次性加载全部技能而是渐进式发现每个技能目录内有一个SKILL.md作为入口元数据必要时再读取其引用文档references与脚本scripts。仓库中 .agents/skills/ 下共有 47 个技能例如api-patterns、frontend-design、database-design、systematic-debugging等。从 .agents/manifest.json 可以确认技能的契约结构api-patterns: { allowedTools: [Read, Write, Edit, Glob, Grep], path: skills/api-patterns/SKILL.md, scripts: [skills/api-patterns/scripts/api_validator.py], version: 1.0.0 }每个技能都有 SemVer 版本、允许的工具白名单和可选的校验脚本。技能的加载协议读取SKILL.md元数据 → 按需加载引用文档 → 按需执行脚本 → 应用规则与模式在 AGENT_FLOW.md 中有完整图示。需要注意的是脚本不会自动执行而是由 Agent 建议运行、用户批准后才执行这是 GEMINI.md 强调只加载相关技能在实操中的延伸——保持上下文精简避免无关技能占用上下文窗口。3. 使用commands/ag-kit/承载可复用的斜杠命令工作流在 Antigravity 工作区中AG Kit 的 13 个工作流以斜杠命令形式提供/brainstorm、/coordinate、/create、/debug、/deploy、/enhance、/orchestrate、/plan、/preview、/remember、/status、/test、/verify定义文件位于 .agents/workflows/。文档中提到的commands/ag-kit/命名空间对应的是插件打包阶段的行为由 .agents/hooks/build-plugin.mjs或npm run build:antigravity-plugin构建dist/antigravity-plugin/时工作流会被转换为带命名空间的命令 TOML 文件安装到 Antigravity CLI 后即形成commands/ag-kit/下的可复用命令参见 .agents/hooks/README.md。每个工作流文件如 .agents/workflows/orchestrate.md的 frontmatter 都声明了requires_agents、requires_skills与artifact_outputs以便在Markdown 优先的运行时中做确定性编排。4. 使用agents/作为 Antigravity 子代理的专家角色定义.agents/agent/ 下定义了 20 个专家角色如frontend-specialist、backend-specialist、database-architect、security-auditor、orchestrator等。在 Antigravity 中委派子代理subagent时应当直接引用这些角色定义。从 manifest 可以看到每个角色与其技能集的绑定关系例如orchestrator依赖parallel-agents、coordinator-mode、plan-writing、verify-changes等编排类技能security-auditor依赖vulnerability-scanner、red-team-tactics。这意味着委派时角色会自带对应领域的技能上下文无需手工拼接。5. 在规划、部署、破坏性操作与安全敏感工作中保留用户审批检查点GEMINI.md 强调的这条规则在编排工作流中有明确的代码级实现。.agents/workflows/orchestrate.md 定义了严格的两阶段编排PHASE 1规划阶段仅允许project-planner创建{task-slug}.md计划文件可选explorer-agent做代码库勘察禁止其他代理并行介入。审批检查点计划完成后必须向用户确认——Do you approve? (Y/N)只有获得明确批准才能进入第二阶段。PHASE 2实施阶段获批后按 Foundationdatabase-architect、security-auditor、Corebackend-specialist、frontend-specialist、Polishtest-engineer、devops-engineer三个并行组委派代理最后运行验证脚本并合成结果。同时 .agents/hooks/README.md 的运行时安全规则也明确规划、部署、破坏性操作与安全敏感工作都必须保留人工审批关卡。这条原则与AG Kit 不要求自动合并、自动部署、自动同步 MCP的发布策略一致见 README.md。6. 内置 MCP 文件仅是示例绝不激活占位凭证仓库中的 .agents/mcp_config.json 是示例配置默认包含YOUR_API_KEY等占位符。.agents/hooks/sync-mcp.mjs 是配套的同步辅助脚本其安全设计体现在--check/--print仅查看合并计划不会向 home 目录写入任何内容只有替换占位符之后才能显式执行--apply --target suite写入~/.gemini/config/mcp_config.json或--apply --target cli写入~/.gemini/antigravity-cli/mcp_config.json占位符未解析会阻止写入同名的既有服务器不会被覆盖除非传入--force写入前会创建带时间戳的备份绝不允许把真实的 MCP 凭证提交到仓库。此外.agents/hooks/antigravity-doctor.mjs 会因默认 MCP 示例中的YOUR_API_KEY而报告警告这是预期行为只有在所有占位符解析完成后才应使用--strict严格模式见 README.md。7. 内置PreToolUseHook 只拦截明确的破坏性根盘操作不替代 Antigravity 原生权限控制Antigravity 通过 .agents/hooks.json 注册原生 Hook{ enabled: true, PreToolUse: [ { matcher: run_command, command: node .agents/hooks/validate-tool-call.mjs, timeout: 10 } ] }.agents/hooks/validate-tool-call.mjs 实现了窄而精确的拦截策略BLOCK_RULES只匹配五类高置信度破坏性模式规则 ID拦截对象示例unix-root-delete递归删除文件系统根目录rm -rf /filesystem-format文件系统格式化mkfs系列命令raw-disk-overwrite原始磁盘覆写dd ... of/dev/sd*windows-drive-formatWindows 盘符格式化format C:windows-root-deleteWindows 驱动器根目录递归删除Remove-Item -Recurse -Force从源码看该 Hook 的设计边界非常清晰故意放行正常的项目清理如删除dist/或node_modules/遇到无效 JSON 或未知载荷时fail open放行并警告以避免上游载荷变更导致运行时全面锁死Hook 仅从 stdin 读取一次工具载荷、不做任何网络调用。Hook 不是沙箱不能替代 Antigravity 自身的权限设置、工作区信任、沙箱或人工审批见 .agents/hooks/README.md 与 SECURITY.md。诊断兼容性问题时可临时将enabled设为false并重开工作区但不应删除 Antigravity 的原生权限控制。三、复杂跨域任务优先选择 orchestrate / coordinateGEMINI.md 的最后一条建议明确了复杂任务的编排策略优先使用orchestrate或coordinate命令处理多域交叉工作且只有在子任务能够干净拆分时才动用三个及以上独立专家最终必须合成并验证结果。两者的分工在 .agents/antigravity.json 与 .agents/hooks/README.md 中有明确界定/coordinate用于可分离的并行研究/阅读任务——并行执行、最后合成。对应coordinator-mode、parallel-agents等技能。/orchestrate用于规划 → 审批 → 专家实施 → 验证的完整编排链路至少需要 3 个不同角色的专家参与.agents/workflows/orchestrate.md 中硬性要求invoked_agents 3少于 3 个即视为只是委派而非编排。需要强调的是Antigravity 的/agents与/tasks视图仍是活跃工作的运行时事实来源AG Kit不会创建第二套调度器。所谓并行在多数场景下是 Agent 在多个专家 persona 间顺序切换上下文、并保持代码一致性详见 AGENT_FLOW.md 的完整请求生命周期示例。四、实操在 Antigravity 中验证与使用 AG Kit1. 安装并打开工作区npx vudovn/ag-kit init # 或全局安装 npm install -g vudovn/ag-kit ag-kit init以受信任工作区方式打开仓库后依次确认/plan、/coordinate、/orchestrate等斜杠命令已被发现相关技能已从.agents/skills/中被正确选中运行npm test等普通命令被允许执行用模拟载荷验证安全 Hook切勿直接执行破坏性命令printf %s {tool_args:{CommandLine:rm -rf /}} \ | node .agents/hooks/validate-tool-call.mjs该命令必须以非零码退出并输出BLOCKED by AG Kit见 README.md。2. 校验工作区健康npm run check:agents npm run check:antigravity npm run test:antigravitycheck:antigravity为只读检查antigravity-doctor.mjs支持--json输出与--strict严格模式相关回归测试位于 .agents/hooks/tests/antigravity.test.mjs。3. 构建并安装本地插件可选npm run build:antigravity-plugin agy plugin install ./dist/antigravity-plugin agy plugin list插件安装是可选项仓库原生.agents/工作区始终是项目开发的事实来源source of truth即使安装了插件包工作区内的.agents/树仍优先见 .agents/hooks/README.md。五、总结AG Kit 在 Antigravity 中的使用边界回到 GEMINI.md 的核心结论AG Kit 在 Antigravity 中的正确打开方式是分层使用、克制安全加载层rules 常驻、skills 渐进、workflows 复用、agents 专职四者由 .agents/manifest.json 与 .agents/DEPENDENCY_GRAPH.md 保证可复现、可检测漂移审批层规划、部署、破坏性操作与安全敏感工作始终保留人工关卡未经用户批准不得进入实施阶段安全层MCP 示例配置不得直接激活占位凭证PreToolUseHook 仅拦截明确的根盘级破坏操作且不替代Antigravity 的原生权限与信任控制。这一套约定让 AG Kit 既能提供可复用的工程化能力又不会僭越运行时自身的权限体系——这也是它被设计为Antigravity-native而非跨运行时抽象的根本原因。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考