AG Kit 工具包演进实录：从 2026.7.12 到 2026.8.31 的 Antigravity 运行时重构与安全加固

AG Kit 工具包演进实录：从 2026.7.12 到 2026.8.31 的 Antigravity 运行时重构与安全加固

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit

本篇基于 AG Kit（Antigravity-native AI Agent Capability Toolkit）官方变更记录 .agents/CHANGELOG.md，梳理工具包四个版本的演进脉络：从可复现的托管组件注册表（SemVer + SHA-256 完整性锁），到以 Google Antigravity 为主运行时的六阶段契约与原生安全钩子，再到 app-builder 编排流水线强化与 MCP 规范对齐。读完你将理解该工具包每个版本改了什么、为什么改、底层由哪些文件与命令支撑，以及如何用仓库自带的验证体系复现每一次演进。

版本脉络：CalVer 驱动的双轨版本策略

AG Kit 的发布节奏采用CalVer（YYYY.M.D格式），当前工具包版本为2026.8.31，记录在 .agents/VERSION 中，并与根目录 package.json 的version字段保持一致。与此并行，工具包内的agents、skills、workflows、rules 四大类托管组件使用严格SemVer（语义化版本），由 .agents/manifest.json 统一记录。

根据变更记录，工具包共经历四次关键发布：

架构细节可参考 .agents/ARCHITECTURE.md，其明确记载当前规模为20 个专业 Agent、47 个 Skills、13 个 Workflows、6 条 Rules。

2026.7.12：发布安全基线

首个版本聚焦“发布本身的安全”，变更点包括：

• Release-safety 升级：引入发布安全性检查，确保发布流程不携带破坏性风险；
• 非破坏性 CLI 更新：工具包自身的更新路径被设计为不破坏现有工作区；
• 回滚支持：版本升级失败时可回退到上一可用状态；
• CI 集成：将验证纳入持续集成；
• 依赖审查：对依赖关系进行人工与自动双重审查；
• 加固发布流程：规范发布产物与发布门禁。

对应测试可参考 cli/test/release-safety.test.js，该测试文件即针对发布安全场景编写。根目录 MIGRATION.md 提供了升级与回滚的完整说明。

2026.7.18：可复现的托管组件注册表

这一版本把“组件管理”从松散的文件约定升级为机器可读、可校验、可复现的注册表体系，是后续所有验证能力的地基。

严格 SemVer 与组件元数据

• 为全部20 个 agents、47 个 skills、13 个 workflows、6 个 rules写入严格 SemVer 元数据（见各组件文件的 frontmatter，例如 .agents/skills/app-builder/SKILL.md 顶部version: 1.1.0）；
• 生成机器可读的 .agents/manifest.json，其中记录每个组件的路径、版本、可用工具、技能依赖（以 SemVer 区间如^1.0.0表达）以及 Antigravity 运行时元数据；
• 生成确定性的 .agents/manifest.lock.json，以SHA-256 完整性哈希锁定托管组件与运行时工具树，防止未登记的漂移。

依赖图与 Schema

• 自动生成 .agents/DEPENDENCY_GRAPH.md，刻画workflow → agent → skill的编排依赖关系，且该文件必须由脚本生成、禁止手工编辑；
• 提供 JSON Schema 校验组件元数据、manifest、lock 与 memory 主题，分别位于 .agents/schemas/manifest.schema.json、.agents/schemas/manifest-lock.schema.json、.agents/schemas/memory.schema.json 等；
• 引入标准 memory 主题文件：用户偏好、技术决策、反馈历史，见 .agents/memory/user-preferences.md、.agents/memory/tech-decisions.md、.agents/memory/feedback-history.md。

非变更式 --check 模式

注册表与依赖图生成脚本（.agents/scripts/generate_manifest.py、.agents/scripts/dependency_graph.py）都提供非变更的--check模式：仅比对当前文件与应生成结果是否一致，不写入任何文件。这使其可以在 CI 中安全运行。

自校验范围随之扩大：组件版本、workflow 引用、依赖兼容性、注册表漂移、lock 完整性、依赖图漂移、memory 契约全部纳入检查。CI 自此将生成的注册表文件视为发布产物，任何托管组件变更若未重新生成注册表，都会导致校验失败。对应命令封装在根目录 package.json 的脚本中：

npm run generate:agents # 重新生成 manifest 与依赖图 npm run check:agents # 非变更校验注册表、依赖图与工具包自身

2026.7.26：Antigravity 成为主运行时

这是架构上最重大的一次转变：Google Antigravity 被确立为主生产运行时，其他 Markdown 兼容工具仅作为尽力而为（best-effort）的消费方。变更记录明确写道：“组件清单现在记录 Antigravity 运行时元数据”“完整性锁现在覆盖antigravity.json、hooks.json以及完整的hooks/运行时工具树”。

六阶段运行时契约

机器可读的运行时契约定义在 .agents/antigravity.json，包含六个生产集成阶段：

详细说明见 .agents/hooks/README.md 与 .agents/README.md。

原生 PreToolUse 安全钩子

.agents/hooks.json 注册了一个针对run_command的原生PreToolUse门禁：

{ "$schema": "hooks/antigravity-hooks.schema.json", "enabled": true, "PreToolUse": [ { "matcher": "run_command", "command": "node .agents/hooks/validate-tool-call.mjs", "timeout": 10 } ] }

策略实现位于 .agents/hooks/validate-tool-call.mjs，它仅拦截高置信度的根目录/磁盘破坏性命令（如删除文件系统根、格式化磁盘、覆写裸设备），而允许正常的清理操作（如删除dist/或node_modules/）。两个关键设计值得注意：

• Fail-open 失败开放：对于无效或未知的 payload 形状，钩子以警告方式放行，避免上游 payload 变化导致整个运行时被锁死（runtime-wide lockout）；
• 职责边界：钩子不是沙箱，不替代 Antigravity 的权限设置、工作区信任、沙箱或用户批准。

可以用 mock stdin 做最小回归验证，以下命令必须非零退出：

printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' \ | node .agents/hooks/validate-tool-call.mjs

若遇到兼容性问题，可临时将"enabled": false并重新打开工作区诊断。

Antigravity Doctor、MCP 同步与插件构建

• Antigravity Doctor（.agents/hooks/antigravity-doctor.mjs）：只读执行六阶段兼容性与发布诊断，支持--json输出与--strict（将未解决的配置占位符视为失败）；
• MCP 同步助手（.agents/hooks/sync-mcp.mjs）：先审查再显式同步 MCP 配置。默认不写家目录文件，--apply才写入；同名 server 除非显式--force否则不被覆盖；写入前会创建时间戳备份：

node .agents/hooks/sync-mcp.mjs --check node .agents/hooks/sync-mcp.mjs --print node .agents/hooks/sync-mcp.mjs --apply --target suite node .agents/hooks/sync-mcp.mjs --apply --target cli

• 插件构建器（.agents/hooks/build-plugin.mjs）：生成确定性的 Antigravity 插件包到dist/antigravity-plugin/，内含兼容的扩展 manifest、打包的技能与角色定义、转为命令 TOML 的 workflows、rules、原生 hooks、MCP 示例，以及带确定性 SHA-256 的PLUGIN_CONTENTS.json清单。安装前必须审查产物：

npm run build:antigravity-plugin

安全加固清单

该版本的安全边界包括：MCP 写入保持显式、占位符阻断、冲突感知、备份保护；插件产物可审查且不含家目录配置或环境变量密钥；高置信度根目录/磁盘破坏性命令在工具执行前被阻断。信任边界明确覆盖：仓库内容、MCP 响应、工具注解、网页内容、日志与子代理输出。同时加入有限 agent、委派深度、turn/retry、超时、取消、无进展控制，防止递归委派与无终止的 ReAct 循环——这一设计对应了变更记录中“防止递归委派和无限 ReAct 循环”的 Security 条目。

兼容性声明

现有 agent、skill、workflow、rule、memory 名称保持兼容；原生安全钩子默认启用、可临时禁用；插件安装可选，仓库.agents/目录始终是项目的事实来源（source of truth）。

2026.8.31：编排强化与模板标准化

最新版本围绕 app-builder 编排、AI 应用技术栈与 MCP 规范三个方向深化，并首次嵌入auto_preview.py自动化预览验证。

DESIGN.md 设计事实源门禁

变更记录第一条即“将强制的DESIGN.md（Design Source-of-Truth）门禁嵌入 app-builder 编排流水线、脚手架结构与 Next.js 模板”。结合 .agents/skills/app-builder/SKILL.md 可知，app-builder 是版本号为1.1.0的全栈应用构建编排器：它先做项目类型检测、选择技术栈、规划目录结构，再协调各专业 agent 执行。design-spec技能进一步规定：UI 工作开始前必须先有符合 token 规范的 DESIGN.md，作为设计事实源。

2026 AI 应用模式与 SQL-first ORM

.agents/skills/app-builder/tech-stack.md 更新了 2026 默认技术栈（Next.js 16 + TypeScript 5.7+ + Tailwind CSS v4 + Node.js 24 + PostgreSQL + Prisma/Drizzle），并新增AI 应用模式章节：

• 流式输出：使用 Vercel AI SDK 的streamText/streamUI于 Route Handlers 或 Server Actions；
• UI 状态：useChat/useCompletion配合 React 19 乐观更新；
• 向量检索：PostgreSQLpgvector扩展存储向量、余弦相似度查询；
• 限流与校验：AI 端点配限流（见 .agents/skills/api-patterns/rate-limiting.md）与 Zod schema 解析。

同时新增 SQL-first 的Drizzle ORM（drizzle-orm+drizzle-kit）作为 Prisma 之外的替代选项。

项目类型检测与预览验证

• 新增AI/Chatbot 应用与Game 应用的项目类型检测（后者路由到game-development技能，见 .agents/skills/game-development/SKILL.md）；
• 将自动预览验证（.agents/scripts/auto_preview.py）集成进迭代增强与 DevOps 交接流程，实现本地预览服务的启动、停止与检查。

模板标准化与依赖修正

• 将 Next.js 模板的globals.css路径统一为src/app/globals.css（与仓库 web/src/app/globals.css 的结构一致）；
• 修正 Express API 模板依赖：@prisma/client放入 dependencies、prisma作为 devDependency，避免生产环境缺包。

mcp-builder 对齐稳定版 MCP 规范

mcp-builder 技能更新到稳定的MCP 2026-07-28 规范，包括：无状态按请求元数据、server/discover、显式状态句柄、扩展协商、JSON Schema 2020-12、兼容性行为，以及废弃特性的迁移指引。

编排重构与安全加固

• 编排器与parallel-agents指南围绕Antigravity 原生 agent 与任务重构，同时为其他运行时保留尽力而为的可移植性；
• 安全清单新增：外部$ref解析防护、schema 校验资源限制、不受信任工具注解、显式同意、最小权限、密钥处理、执行隔离——这正是把 2026.7.26 的“信任边界”概念落到校验实现层面。

贯穿机制：自校验与回归测试

无论版本如何演进，所有变更都由同一套可执行检查约束，命令集中在根目录 package.json：

npm run check:agents # 注册表 + 依赖图 + 工具包自检（generate_manifest --check / dependency_graph --check / validate_kit.py） npm run check:antigravity # node .agents/hooks/antigravity-doctor.mjs（只读六阶段诊断） npm run test:antigravity # node --test .agents/hooks/tests/antigravity.test.mjs（钩子回归测试） npm run build:antigravity-plugin

对目标项目的快速与完整验证则使用 Python 侧工具：

python .agents/scripts/checklist.py . python .agents/scripts/verify_all.py . --url http://localhost:3000

验证覆盖组件 SemVer、注册表、lock、依赖图、memory、链接引用、Antigravity 六阶段配置形态、MCP 占位符、原生钩子注册、安全与密钥扫描（阻塞性退出码）、依赖文件卫生、lint/类型覆盖/schema/测试、UI/可访问性/SEO/GEO/API/移动端/i18n 审计，以及可选的 Lighthouse 与 Playwright 运行时检查。机制说明见 .agents/scripts/README.md。

升级与兼容性指引

对使用旧版 AG Kit 的团队，MIGRATION.md 提供升级与回滚路径；SECURITY.md 覆盖威胁模型与钩子恢复；PRODUCTION_CHECKLIST.md 定义了自动化与人工双轨发布门禁。三次演进形成的核心原则值得沉淀：组件即产物（manifest + lock 可复现）、运行时契约化（六阶段 Antigravity）、安全默认开启（PreToolUse 钩子 + fail-open 韧性 + 有限循环控制）——这正是 AG Kit 从“一套提示词目录”进化为“可验证的工程化工具包”的关键。

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit