ag-kit

AG KIT

以 Antigravity 为中心的 agent 工程套件，包含规则、技能、专业 agent、工作流、持久化记忆、MCP 指南、编排以及原生安全钩子。

主运行时：Google Antigravity
Tiếng Việt · 迁移指南 · 生产清单 · 安全

---

生产配置介绍

AG Kit 安装了一个完整的 .agents/ 工作区契约。Antigravity 是本版本支持的生产运行时。其他工具可以读取 Markdown 组件，但 Antigravity 之外的运行时行为不属于生产兼容性保证的范围。

能力	生产实现
规则与技能发现	.agents/rules/、.agents/skills/、.agents/workflows/
专业路由	20 个角色定义与智能路由技能
持久化上下文	.agents/memory/ 及上下文压缩指南
编排	/coordinate、/orchestrate、Antigravity /agents 和 /tasks
MCP	工作区配置，外加显式、支持备份的同步助手
工具安全	原生 PreToolUse 门控，用于高置信度破坏性命令
打包	本地 Antigravity 插件包，包含 SHA-256 内容清单
验证	工具包 CI、Antigravity Doctor、回归测试、依赖审查、CLI 和 Web 检查

原生钩子范围有意限定。它阻止根文件系统删除、磁盘格式化和原始磁盘覆写模式，同时允许正常的项目清理，例如删除 dist/ 或 node_modules/。它不会取代 Antigravity 的权限、工作区信任、沙箱或人工审批。

需求

• Node.js 22 或更高版本，用于仓库级别的 Antigravity 工具。
• Python 3.10 或更高版本，用于 AG Kit 验证器和实用脚本。
• 受信任的 Google Antigravity 工作区。
• Git，用于安全的更新、审查和回滚工作流。

已发布的 CLI 目前支持 Node.js 18 或更高版本；Antigravity 集成检查在 Node.js 22 上运行。

快速开始

安装到项目中

npx @vudovn/ag-kit init

或全局安装 CLI：

npm install -g @vudovn/ag-kit
ag-kit init

当 Antigravity 需要索引规则、技能或工作流时，请勿将 .agents/ 添加到项目的 .gitignore 中。若要将其保留在本地而不禁用发现，请将 .agents/ 添加到 .git/info/exclude 中。

验证工作区

npm run check:agents
npm run check:antigravity
npm run test:antigravity

check:antigravity 是只读的。默认的 MCP 示例包含 YOUR_API_KEY，因此在配置示例之前，正常的 doctor 会报告警告。仅在所有占位符都已解决后才使用严格模式：

node .agents/hooks/antigravity-doctor.mjs --strict

在 Antigravity 中打开

将仓库作为受信任的工作区打开后：

1. 确认斜杠命令（如 /plan、/coordinate 和 /orchestrate）被发现。
2. 确认从 .agents/skills/ 中选择了相关技能。
3. 运行一个普通命令（如 npm test）并确认它被允许。
4. 使用模拟的有效负载（而非执行破坏性命令）验证安全钩子：

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

该命令必须退出非零并打印 BLOCKED by AG Kit。

安全更新与回滚

AG Kit 更新是合并感知的。用户拥有的文件以及本地修改的 managed 文件默认会被保留。

ag-kit update --dry-run          # 预览具体计划
ag-kit update                    # 安全合并并创建备份
ag-kit update --strategy replace # 显式完全替换，仍会备份
ag-kit rollback                  # 恢复最新的更新前备份

更新元数据存储在 .agents/.ag-kit/ 中。备份存储在 managed 工具包树之外的 .ag-kit-backups/ 中。在将现有安装升级到 Antigravity 原生版本之前，请阅读 MIGRATION.md。

Antigravity 原生集成

运行时契约

.agents/antigravity.json 声明了六个受支持的集成阶段以及 AG Kit 使用的、有文档记录的 Antigravity CLI 能力。当上游文档未定义最小语义版本时，它避免自行定义一个。

原生安全钩子

Antigravity 加载 .agents/hooks.json，其中注册了：

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

若要在诊断兼容性问题时临时禁用 AG Kit 钩子，设置 "enabled": false，重新打开工作区，并在有效负载可能包含敏感数据时私下报告其形状。请勿删除 Antigravity 自身的权限控制。

MCP 配置

在不写入家目录的情况下审查工作区 MCP 计划：

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

除非提供 --force，否则具有相同名称的现有服务器将被保留。在更改现有目标文件之前，会创建一个带时间戳的备份。切勿提交真实的 MCP 凭证。

构建并检查插件

npm run build:antigravity-plugin

在本地安装之前检查 dist/antigravity-plugin/。该包包含打包的技能、agent、规则、转换后的工作流命令、原生钩子、MCP 示例以及包含 SHA-256 条目的 PLUGIN_CONTENTS.json。

agy plugin install ./dist/antigravity-plugin
agy plugin list

插件安装是可选的；仓库原生的 .agents/ 工作区仍然是项目开发的真理来源。

包含的组件

组件	数量	用途
Agents	20	领域专业与编排角色定义
技能	47	渐进式领域知识与可执行验证助手
工作流	13	可重复的斜杠命令流程
规则	6	工作区级路由、安全、设计与编码约束
记忆主题	4 个必需主题 + 索引	持久的项目约定、决策、偏好与反馈

每个 agent、技能、工作流和规则都有 SemVer 契约。.agents/manifest.json、.agents/manifest.lock.json 和 .agents/DEPENDENCY_GRAPH.md 使 managed 工具包可重现并可检测漂移。

npm run generate:agents
npm run check:agents

常用工作流

命令	用途
/brainstorm	在实现前探索选项和架构
/coordinate	并行执行可分离的研究或审查任务，然后汇总
/create	通过结构化门控创建功能或应用
/debug	执行基于证据的根因分析
/deploy	执行生产预检检查与部署工作流
/enhance	安全地修改现有代码库
/orchestrate	计划、获得批准、委派给专业 agent 并验证
/plan	创建详细的实施计划与检查清单
/preview	管理本地预览服务器
/remember	将持久的项目信息保存到记忆
/status	汇总活跃工作与阻塞项
/test	设计与执行测试
/verify	通过运行检查来证明变更，而非依赖人工审查

发布与生产门控

发布候选版本在完成所有自动化检查以及 PRODUCTION_CHECKLIST.md 中的实操 Antigravity 冒烟测试之前，不得视为生产批准。

所需的 GitHub 检查：

• 工具包验证
• CLI 测试与包验证
• Web lint、类型检查、构建与审计
• Antigravity 原生契约
• 依赖审查

AG Kit 从不要求自动合并、自动部署或自动 MCP 同步。生产变更应保持可审查和可逆。

文档

• Antigravity 实现细节
• 迁移指南
• 生产发布清单
• 安全策略与运行时威胁模型
• Agent 流程架构
• 工具包架构
• 变更日志
• 发布设置

参考与归属

AG Kit 是基于 Markdown 的 agent 工程模式的原创开源实现。不包含任何专有源文件。运行时集成决策基于 .agents/hooks/README.md 中链接的公共 Antigravity 文档和代码实验室。

支持项目

- 或者 -

CA: Gjpatn3d24dCRhUng7F37K6xJba4R8SDBC18xs1Apump

许可证

以 MIT 许可证 发布 © Vudovn