AG Kit：为 Google Antigravity 而生的安全钩子型 Agent 工作区

项目类型Infrastructure / Runtime

最适合已选择 Google Antigravity 作为主力运行时，并希望获得带版本管理、可校验的 agent 工作区契约的团队。

风险等级medium

评估时间1–2 小时即可完成项目初始化、运行 Antigravity Doctor 并确认斜杠命令与技能已被发现。

核心问题: 你的团队是否以 Google Antigravity 作为主要 agent 运行时，并希望在 .agents/ 契约中内置防护栏？

91/100

RepoDaily 采用评分

RepoDaily 将该项目的采用分评为 91/100（强）：分数来自文章来源、安装路径、生产风险、差异化、许可证清晰度以及 AI/Agent 适配度。

基于 RepoDaily 来源和采用说明的方向性评分，不是基准测试。风险: 中

100证据质量

包含 5 个来源、覆盖 4 类来源；如有 RepoDaily 独有模块，会进一步提高证据分。

100可安装/可试用性

检测到 5 个工作流步骤、5 个下一步动作，以及 4 个命令/安装信号。

61维护可信度

趋势热度为 +211 stars；如内容中有 release、issue 或维护信号，会提高维护可信度。

94生产准备度

采纳风险标记为 medium，并包含 6 条安全说明与 3 条跳过条件。

100差异化

3 个机会视角、3 个替代方案，以及 3 个类型化模块支撑差异化判断。

82许可证清晰度

文章中包含许可证来源或许可证表述。

90Agent / AI 适配度

文章正文和元数据中检测到 7 个 AI/Agent 相关信号。

项目概览

AG Kit 是由 VUDOVN 以 MIT 许可证开源的 agent 工程套件，采用 YYYY.M.D 日历版本号，当前版本为 2026.7.27。它不是模型、不是框架抽象层，也不是独立的 agent 运行时，而是在单一受支持的运行时——Google Antigravity——之上安装一套完整的 .agents/ 工作区契约，包含规则、技能、工作流、记忆、编排命令、MCP 配置指引，以及一个原生安全钩子。

该项目的差异化在于明确的边界。README 明确指出 Antigravity 是本版本受支持的生产运行时，其他工具可以读取 Markdown 组件，但 Antigravity 之外的运行时行为不在生产兼容性保证范围内。这一边界由专门的 Antigravity Compatibility GitHub Actions 工作流、针对钩子载荷与销毁式模式的回归测试，以及名为 Antigravity Doctor 的只读诊断工具共同支撑。

AG Kit 值得关注的核心是安全层。.agents/hooks.json 中注册的原生 PreToolUse 钩子拦截 run_command 调用，阻断五类高置信度的销毁模式：Unix 根目录递归删除、文件系统格式化、使用 dd 的裸盘覆写、Windows 驱动器格式化，以及 Windows 根目录强制递归删除。正常的清理操作，例如删除 dist/ 或 node_modules/，被有意放行。钩子从 stdin 最多读取 1 MiB JSON，不发起网络请求，对识别出的销毁命令以非零退出码失败关闭，对无法识别的载荷形状则以警告失败开启，避免上游 schema 变更导致全部工具调用被锁死。

在钩子之外，AG Kit 还内置了 20 个角色定义与智能路由技能、.agents/memory/ 下的持久化上下文与上下文压缩指引、/plan、/coordinate、/orchestrate 等斜杠命令编排，以及一个 MCP 同步助手——默认只检查、拒绝未解析占位符、除非强制否则保留同名冲突、在替换目标文件前生成带时间戳的备份。

解决什么问题

agent 运行时在被诱导或投毒时可能执行销毁式 shell 命令；AG Kit 的 PreToolUse 钩子在命令触达主机前阻断五类高危模式。
MCP 配置中嵌入凭据是反复出现的泄露路径；AG Kit 的同步助手拒绝未解析的占位符（如 YOUR_API_KEY），且在未显式传递 --apply 时绝不写入。
agent 工作区在不同机器和贡献者之间容易漂移；AG Kit 将 .agents/ 视为带版本管理的契约，覆盖 Antigravity 契约、钩子配置、schemas、插件模板与测试的完整性。
插件产物被篡改难以察觉；构建器只在 dist/antigravity-plugin/ 下生成带 SHA-256 内容清单的 PLUGIN_CONTENTS.json，且仅读取仓库文件，排除环境变量与家目录配置。

工作原理

运行 `npx @vudovn/ag-kit init` 或先 `npm install -g @vudovn/ag-kit` 再执行 `ag-kit init`，在项目中脚手架出 .agents/ 工作区。
如果 Antigravity 需要索引规则、技能或工作流，不要把 .agents/ 加入 .gitignore；需要本地忽略时改用 .git/info/exclude。
运行 `npm run check:agents`（校验器）、`npm run check:antigravity`（只读诊断）、`npm run test:antigravity`（钩子载荷测试）验证工作区。
在 Antigravity 中以受信任工作区打开仓库，确认 /plan、/coordinate、/orchestrate 等斜杠命令已被发现。
可选地用 `npm run build:antigravity-plugin` 构建本地 Antigravity 插件，产物位于 dist/antigravity-plugin/ 并附带 SHA-256 内容清单。

产品演示与界面预览

AG Kit 项目 Logo — README 中的 AG Kit Logo 在其 Antigravity 原生文档与各类徽章中标识该项目。 README.md image

命令与脚本面

`npx @vudovn/ag-kit init` 脚手架生成 .agents/ 工作区契约。
`npm run check:agents` 运行 generate_manifest.py --check、dependency_graph.py --check 与 validate_kit.py。
`npm run check:antigravity` 以只读模式调用 .agents/hooks/antigravity-doctor.mjs。
`npm run test:antigravity` 运行 `node --test .agents/hooks/tests/antigravity.test.mjs`。
`npm run build:antigravity-plugin` 调用 .agents/hooks/build-plugin.mjs 生成插件包。
`node .agents/hooks/antigravity-doctor.mjs --strict` 仅在所有 MCP 占位符都已解析后启用严格诊断。
校验器与工具脚本需 Python 3.10+；Antigravity 集成检查需 Node.js 22+。

采用清单

确认每台贡献者机器均已安装 Node.js 22+ 与 Python 3.10+。
确认已有受信任的 Google Antigravity 工作区；其他运行时仅作为 Markdown 可移植性的尽力而为。
运行 `npm run check:antigravity`，在默认 MCP 示例的 YOUR_API_KEY 占位符被替换前会收到警告。
启用严格模式前检查 .agents/hooks.json；钩子默认启用，但可设为 "enabled": false 以便兼容性诊断。
不要把 .agents/ 加入 .gitignore，否则 Antigravity 无法索引规则、技能与工作流。

集成面

AG Kit 通过三个主要面与 Google Antigravity 集成：机器可读的 .agents/antigravity.json 契约、针对 run_command 的原生 .agents/hooks.json PreToolUse 注册，以及可选的生成到 dist/antigravity-plugin/ 的插件包。Antigravity Doctor 在一次只读流程中检查发现、MCP、钩子、编排、插件与发布就绪情况。MCP 同步针对选定的 Antigravity 套件或 CLI 目标文件，拒绝在存在占位符时执行 --apply，并在未显式传递 --force 时保留同名既有服务器。

谁适合关注

适合关注

已选择 Google Antigravity 并希望获得结构化、可校验的 .agents/ 契约与防护栏的团队。
需要一条窄而明确的销毁式命令安全网，且不打算替代 Antigravity 自身权限与工作区信任控制的项目。
希望 MCP 配置具备占位符阻断、冲突保留与时间戳备份能力的组织。

可以先跳过

以其他 agent 运行时为主、Antigravity 兼容性无关紧要的团队。
需要沙箱的项目；AG Kit 明确声明自己不是沙箱，也不能替代操作系统隔离。
无法在验证机上运行 Node.js 22+ 与 Python 3.10+ 的用户。

风险与注意事项

中

运行时锁定在 Google Antigravity，安全钩子按设计保持窄范围，跨运行时行为仅为尽力而为。

README 明确将生产兼容性限定在 Antigravity；其他工具可读取 Markdown，但运行时行为不受支持。
原生钩子仅阻断五类高置信度销毁模式，不替代 Antigravity 权限、工作区信任、沙箱或人工审批。
默认 MCP 示例包含 YOUR_API_KEY，在配置完成前 Doctor 会持续报告警告。
Antigravity 集成检查要求 Node.js 22+，而发布的 CLI 支持 Node.js 18+。
日历版本号意味着安全修复仅针对最新发布版本提供。

PreToolUse 钩子从 stdin 最多读取 1 MiB JSON，不发起网络请求。
识别出的销毁命令以非零退出码失败关闭；无效、超大或无法识别的载荷以警告失败开启，避免全工作区锁死。
MCP 同步默认只检查，拒绝未解析占位符，除非 --force 否则保留冲突，并在替换目标文件前创建带时间戳的备份。
插件构建器仅读取仓库文件，排除环境变量与家目录配置。
SECURITY.md 威胁模型覆盖提示注入、销毁式 shell 命令、MCP 配置中的密钥泄露、恶意 MCP 服务器、产物篡改、配置冲突、上游载荷变更与供应链投毒。
漏洞报告仅限 GitHub 私密漏洞报告；公开 issue 不得包含密钥、利用载荷或概念验证数据。

替代方案比较

方案	适用场景	代价
Cursor Rules / .cursorrules	主力编辑器是 Cursor 而非 Antigravity，且只需更轻量的规则文件即可。	免费，编辑器专属。
Claude Code subagents	运行时是 Claude Code，需要专家 agent 路由但不需完整 .agents/ 契约时。	随 Claude Code 使用量包含。
自定义 .agents/ 脚手架	团队希望完全掌控工作区契约，并能自行构建钩子与校验流水线时。	工程时间。

这个趋势说明了什么

销毁式命令策略作为可移植模式

五类被阻断模式——Unix 根删除、文件系统格式化、dd 裸盘覆写、Windows 驱动器格式化、Windows 根强制删除——都是具体可审计的。Antigravity 之外的运行时维护者可以为自己的 PreToolUse 类钩子采用同样的失败关闭/失败开启拆分。

审阅 .agents/hooks.json 与 .agents/hooks/tests/ 下的钩子测试，确认模式列表与失败行为与 SECURITY.md 描述一致。

MCP 占位符阻断工作流

sync-mcp.mjs 在存在占位符时拒绝 --apply，并在未强制时保留同名服务器。对任何需要跨多个套件或 CLI 目标管理 MCP 配置的团队来说，这都是一种可复用的安全模式。

在全新 init 后运行 npm run check:antigravity，确认 Doctor 在严格模式可用前会对默认的 YOUR_API_KEY 占位符报告警告。

通过 SHA-256 清单实现插件产物完整性

插件构建器生成带 SHA-256 内容清单的 PLUGIN_CONTENTS.json，为审阅者在安装到 Antigravity 前提供确定性产物。

运行 npm run build:antigravity-plugin，并将 dist/antigravity-plugin/PLUGIN_CONTENTS.json 与 .agents/VERSION 对照检查。

下一步建议

在临时仓库中初始化 AG Kit 并运行 Antigravity Doctor

评估 AG Kit 最快的方式是在全新仓库中脚手架安装、运行只读诊断，并在正式接入项目前观察 MCP 占位符警告。

新建一个 git 仓库并运行 `npx @vudovn/ag-kit init`。
运行 `npm run check:agents` 校验 .agents/ 清单、依赖图与工具包。
运行 `npm run check:antigravity`，留意默认 YOUR_API_KEY 示例触发的 MCP 占位符警告。
在 Antigravity 中以受信任工作区打开仓库，确认 /plan、/coordinate、/orchestrate 已被发现。
可选地运行 `npm run build:antigravity-plugin`，在安装插件前审阅 PLUGIN_CONTENTS.json。

RepoDaily 判断

AG Kit 是一套范围明确、安全意识强的 .agents/ 工作区契约，面向 Google Antigravity，具备真实的销毁式命令网关、MCP 占位符阻断与只读诊断流水线。对 Antigravity 优先的团队是高匹配，对期望跨运行时生产一致性或完整沙箱的用户则不合适。