AG KIT

Antigravity 优先的 agent 工程套件，包含 rules、skills、专家 agents、workflows、持久化 memory、MCP 指南、orchestration 以及原生安全 hook。

主要 runtime：Google Antigravity
Tiếng Việt · 迁移指南 · 生产环境检查清单 · 安全策略

## 生产环境配置 AG Kit 安装了一个完整的 `.agents/` 工作区契约。Antigravity 是此版本支持的生产环境 runtime。其他工具可能可以读取这些 Markdown 组件，但 Antigravity 之外的 runtime 行为不属于生产环境兼容性保证的一部分。 | 能力 | 生产环境实现 | | --- | --- | | Rules 与 skills 发现 | `.agents/rules/`, `.agents/skills/`, `.agents/workflows/` | | 专家路由 | 20 个角色定义和智能路由 skills | | 持久化 context | `.agents/memory/` 和 context 压缩指南 | | Orchestration | `/coordinate`, `/orchestrate`，Antigravity `/agents` 和 `/tasks` | | MCP | 工作区配置以及显式的、具备备份感知的同步辅助工具 | | 工具安全 | 用于高置信度破坏性命令的原生 `PreToolUse` 门控 | | 打包 | 本地 Antigravity 插件包，带有 SHA-256 内容清单 | | 验证 | 工具包 CI、Antigravity Doctor、回归测试、Dependency Review、CLI 和 Web 检查 | 原生 hook 的设计范围特意做得极其保守。它会阻止根文件系统删除、驱动器格式化和原始磁盘覆写模式，同时允许正常的项目清理，例如删除 `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 需要索引 rules、skills 或 workflows 时，请勿将 `.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/` 中选择了相关的 skills。 3. 运行常规命令（如 `npm test`）并确认其已被允许。 4. 使用模拟的 payload 验证安全 hook，而不是执行破坏性命令： ``` printf '%s' '{"tool_args":{"CommandLine":"rm -rf /"}}' \ | node .agents/hooks/validate-tool-call.mjs ``` 该命令必须以非零状态退出，并打印 `BLOCKED by AG Kit`。 ## 安全更新与回滚 AG Kit 更新具备合并感知能力。默认情况下，会保留用户拥有的文件和在本地修改过的托管文件。 ``` ag-kit update --dry-run # Preview the exact plan ag-kit update # Merge safely and create a backup ag-kit update --strategy replace # Explicit full replacement, still backed up ag-kit rollback # Restore the newest pre-update backup ``` 更新元数据存储在 `.agents/.ag-kit/` 中。备份存储在受管理工具包树之外的 `.ag-kit-backups/` 中。在将现有安装升级到 Antigravity 原生版本之前，请阅读 [MIGRATION.md](MIGRATION.md)。 ## Antigravity 原生集成 ### Runtime 契约 `.agents/antigravity.json` 声明了六个受支持的集成阶段，以及 AG Kit 所使用的、已记录在案的 Antigravity CLI 功能。当上游文档未定义最小语义版本时，它会避免凭空设定该版本。 ### 原生安全 hook Antigravity 会加载 `.agents/hooks.json`，该文件注册了： ``` { "enabled": true, "PreToolUse": [ { "matcher": "run_command", "command": "node .agents/hooks/validate-tool-call.mjs", "timeout": 10 } ] } ``` 在诊断兼容性问题时，若要暂时禁用 AG Kit hook，请将 `"enabled"` 设置为 `false`，重新打开工作区，如果 payload 可能包含敏感数据，请私下报告其结构。请勿删除 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/`。该包包含打包的 skills、agents、rules、转换后的 workflow 命令、原生 hook、MCP 示例，以及带有 SHA-256 条目的 `PLUGIN_CONTENTS.json`。 ``` agy plugin install ./dist/antigravity-plugin agy plugin list ``` 插件安装是可选的；仓库原生的 `.agents/` 工作区仍然是项目开发的唯一事实来源。 ## 包含的组件 | 组件 | 数量 | 用途 | | --- | ---: | --- | | Agents | 20 | 领域专家与 orchestration 角色定义 | | Skills | 47 | 渐进式领域知识和可执行的验证辅助工具 | | Workflows | 13 | 可重复的斜杠命令程序 | | Rules | 6 | 工作区范围的路由、安全、设计和编码约束 | | Memory 主题 | 4 个必选主题加上索引 | 持久化的项目约定、决策、偏好和反馈 | 每个 agent、skill、workflow 和 rule 都有一个 SemVer 契约。`.agents/manifest.json`、`.agents/manifest.lock.json` 和 `.agents/DEPENDENCY_GRAPH.md` 使受管理的工具包可重现并能够检测偏差。 ``` npm run generate:agents npm run check:agents ``` ## 常用工作流 | 命令 | 用途 | | --- | --- | | `/brainstorm` | 在实现之前探索选项和架构 | | `/coordinate` | 并行运行可分离的研究或审查任务，然后进行综合 | | `/create` | 通过结构化的关卡创建功能或应用程序 | | `/debug` | 执行基于证据的根因分析 | | `/deploy` | 执行生产环境飞行前检查和部署工作流 | | `/enhance` | 安全地修改现有代码库 | | `/orchestrate` | 计划、获取批准、委派给专家并进行验证 | | `/plan` | 创建详细的实施计划和清单 | | `/preview` | 管理本地预览服务器 | | `/remember` | 将持久化的项目信息保存到 memory 中 | | `/status` | 总结当前的工作和阻碍因素 | | `/test` | 设计并执行测试 | | `/verify` | 通过运行检查而不是依赖审查来证明更改有效 | ## 发布与生产环境门控 在完成所有自动化检查和 [PRODUCTION_CHECKLIST.md](PRODUCTION_CHECKLIST.md) 中的 Antigravity 实践冒烟测试之前，发布候选版本不会被批准用于生产环境。 必需的 GitHub 检查： - 工具包验证 - CLI 测试和包验证 - Web lint、typecheck、构建和审计 - Antigravity 原生契约 - Dependency Review AG Kit 从不需要自动合并、自动部署或自动 MCP 同步。生产环境的更改应保持可审查和可逆的状态。 ## 文档 - [Antigravity 实现细节](.agents/hooks/README.md) - [迁移指南](MIGRATION.md) - [生产环境发布清单](PRODUCTION_CHECKLIST.md) - [安全策略与运行时威胁模型](SECURITY.md) - [Agent 流架构](AGENT_FLOW.md) - [工具包架构](.agents/ARCHITECTURE.md) - [更新日志](CHANGELOG.md) - [发布设置](.github/RELEASE_SETUP.md) ## 参考与致谢 AG Kit 是基于 Markdown 的 agent 工程模式的原创开源实现。未包含任何专有的源文件。Runtime 集成决策基于 [.agents/hooks/README.md](.agents/hooks/README.md) 中链接的公开 Antigravity 文档和 codelabs。 ## 许可证 基于 [MIT License](LICENSE) 发布 © [Vudovn](https://github.com/vudovn)。

标签：AI工程框架, AI智能体, MCP协议, MITM代理, 上下文管理, 工作流编排, 自动化攻击, 逆向工具, 防御加固