AG Kit CLI 完全指南安全安装、合并式更新与回滚【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kitAG KitAntigravity Kit是一个面向 Google Antigravity 的 Agent 工程套件包含 agents、skills、workflows、rules、持久化记忆约定与校验工具其官方 CLIvudovn/ag-kit负责把这些组件安装进项目的.agents/目录并围绕 SHA-256 基线提供绝不覆盖本地改动的合并式安全更新与一键回滚能力。读完本文你将掌握 CLI 的安装方式、init/update/rollback/status四个命令的完整用法、merge与replace两种更新策略的取舍以及底层基于清单manifest与三方哈希比较的更新决策原理。CLI 是什么AG Kit CLI 是一个 Node.js 命令行工具npm 包名为vudovn/ag-kit当前仓库版本为2026.8.31见 cli/package.json。它把 AG Kit 的整套组件20 个专业 agent、47 个 skills、13 个 workflows、共享规则、持久化记忆约定、MCP 配置与校验脚本作为受管工具包安装到用户项目的.agents/目录下并负责后续的安全升级。CLI 的命令解析基于commander下载模板基于giget输出美化使用chalk与ora文件操作基于fs-extra。其可执行入口是 cli/bin/index.js核心的树快照、哈希、清单、备份、恢复逻辑全部集中在 cli/lib/managed-tree.js 这一个模块中测试覆盖见 cli/test/managed-tree.test.js 与 cli/test/index.test.js。安装 CLI一次性执行无需全局安装npx vudovn/ag-kit initnpx会临时拉取vudovn/ag-kit并直接运行init适合首次尝试。全局安装npm install -g vudovn/ag-kit ag-kit init全局安装后ag-kit命令对所有项目可用。仓库的 cli/package.json 声明了bin字段ag-kit→bin/index.js、type: module以及engines.node 18即需要 Node.js 18 或更高版本仓库级 Antigravity 集成工具链则建议 Node.js 22见 README.md 的 Requirements 一节。CLI 每次运行时还会异步检查 npm registry 上的最新版本1.5 秒超时失败静默忽略若有新版会提示Update available: 2026.8.31 → x.y.z Run: npm install -g vudovn/ag-kit命令总览命令说明ag-kit init安装.agents已存在安装时进行安全合并ag-kit update更新受管文件同时保留本地改动ag-kit rollback恢复最新或指定的更新前备份ag-kit status显示安装状态、清单、工具包版本、备份与 CLI 状态这四个命令的生命周期由 cli/test/index.test.js 中的测试断言保证[init, update, rollback, status]。不带任何参数直接运行ag-kit会输出帮助信息。安全更新模型三方比较AG Kit 的更新模型基于.agents/.ag-kit/manifest.json中记录的 SHA-256 基线。执行更新时CLI 会同时比较三方数据上一个上游版本manifest 中记录的文件哈希当前本地文件重新扫描计算出的哈希新上游文件新下载工具包的哈希。比较逻辑的核心实现在 cli/lib/managed-tree.js 的createUpdatePlan中每个文件最终归入五类结果之一干净受管文件clean managed files上游有改动、本地未改动 → 自动更新仅本地改动的文件上游未变、本地已改 → 保留本地版本用户自建文件不在清单中、上游也没有同名文件 → 保留本地与上游同时改动→ 报告为冲突conflict不覆盖冲突文件的上游副本写入.agents/.ag-kit/conflicts/runId/下以.incoming后缀保存供手动审阅。整个过程通过 SHA-256 哈希判定而非行级 diff因此即使是改了一行又改回去这类内容等价情况只要哈希一致就不会误判为冲突。清单本身的健壮性也有防护loadManifest会校验schemaVersion是否为 1、files是否为对象、路径是否安全拒绝..或绝对路径、哈希是否严格匹配 64 位十六进制任一不合格即视为无效清单对应测试 cli/test/managed-tree.test.js 中的 malformed manifest paths are rejected 用例。更新前备份无论哪种策略每次真正的更新都会先创建一份完整备份默认存放在.ag-kit-backups/位于项目根目录、受管工具包.agents/之外目录名为运行 IDYYYYMMDD-HHMMSS-mmm格式UTC 时间内部包含.agents/快照和一份backup.json元数据记录createdAt与源路径。createBackup的实现会先确保agentDir存在再整体复制目录。运行示例# 预览本次更新将执行的动作不落盘 ag-kit update --dry-run # 默认策略合并式更新保留本地改动 ag-kit update --strategy merge # 显式全量替换仍会创建备份除非加 --no-backup ag-kit update --strategy replace # 回滚到最新备份 ag-kit rollback # 回滚到指定备份 ag-kit rollback --backup 20260712-090000-000merge是默认策略。replace必须显式指定且依然会先做备份除非提供--no-backup。执行更新后CLI 会打印变更摘要Changes / Preserved / Conflicts / Unchanged并提示备份目录与报告文件路径更新报告默认写入.agents/.ag-kit/reports/update-runId.json。无清单的旧安装legacy处理若.agents/已存在但缺少 manifest旧版本安装createUpdatePlan会走降级分支与上游一致的文件视为未变上游没有的本地文件保留既有且与上游不一致的文件全部列为冲突绝不覆盖。测试 legacy installation never overwrites an existing differing file 验证了这一行为——rules/local.md的本地版本在更新后原样保留。replace 策略删旧加新replace策略不关心清单凡上游不存在而本地存在的文件一律删除上游新增的添加哈希不一致的覆盖。测试 replace creates a backup that can be rolled back 验证了old.txt、local-only.txt被删除、new.txt被加入且可通过restoreBackup完整还原。更新与回滚的底层实现完整调用链为CLI 命令cli/bin/index.js→ 下载工具包downloadToolkit基于 giget 拉取github:vudovn/ag-kit仓库的.agents目录支持#branch选择分支→snapshotTree计算本地与传入目录的哈希快照 →createUpdatePlan生成动作计划 →applyUpdatePlan执行计划。applyUpdatePlan的职责包括创建备份createBackup执行 add / update / delete 动作删除后还会清理空父目录将冲突文件的上游副本写入.agents/.ag-kit/conflicts/runId/file.incoming写入更新报告默认或--conflict-report指定路径用新的传入快照覆写 manifest更新toolkitVersion、updatedAt、lastRunId并保留首次installedAt。rollback对应的restoreBackup会按 ID或默认取最新选择备份恢复前若keepCurrent为真还会先给当前状态做一次pre-rollback-runId的安全备份然后删除.agents/并从备份整体复制还原——回滚本身也是可逆的。常用选项与组合# 指定项目目录默认当前工作目录 ag-kit init --path ./myapp # 从指定分支安装 ag-kit init --branch dev # 跳过确认提示已存在安装时 ag-kit update --force # 静默模式对已存在安装必须配合 --force ag-kit update --quiet --force # 把更新报告写到自定义路径 ag-kit update --conflict-report ./ag-kit-update.json # 只展示将要恢复的备份 ag-kit rollback --dry-run注意当使用--quiet且目标已存在安装时CLI 无法安全地向用户请求确认因此必须同时提供--force否则会直接报错requireConfirmation中的实现。交互确认默认采用? 问题 (y/N)形式只有输入y或yes才继续。--no-backup仅用于你明确知道无需备份的场景。update与init支持相同的一组选项--force、--path、--branch、--quiet、--dry-run、--no-backup、--conflict-report、--strategymerge/replace默认merge。rollback另有--backup id与--no-keep-current。退出码退出码含义0成功或无需任何变更1下载、校验、文件系统或配置失败2更新完成但存在一个或多个冲突需要人工处理130被用户中断SIGINT130的实现在 cli/bin/index.js 的 SIGINT 处理中中断时会清理临时目录.temp_ag_kit/并以process.exit(130)退出。发生冲突时initCommand/updateCommand会设置process.exitCode 2此时虽然更新已落盘但你应该查看冲突报告并手工合并.incoming副本。检查安装状态ag-kit status输出会显示CLI 版本、[OK] Installed或[X] Not installed、.agents的路径与修改时间、是否受管Managed: yes / legacy/no manifest、工具包版本对应.agents/manifest.json记录的toolkitVersion、本地备份数量以及 CLI 是否有可用更新。安装位置与磁盘布局一次init后项目内会形成如下结构.agents/—— 受管工具包agents、skills、workflows、rules、memory、hooks、manifest 等是 Antigravity 工作区的实际内容.agents/.ag-kit/manifest.json—— SHA-256 基线清单schemaVersion: 1、toolkitVersion、installedAt、updatedAt、lastRunId、files.agents/.ag-kit/conflicts/runId/—— 冲突文件的上游副本.incoming后缀.agents/.ag-kit/reports/update-runId.json—— 更新报告.ag-kit-backups/runId/—— 更新前完整备份.temp_ag_kit/—— 下载与解压的临时目录操作结束后自动清理。当前仓库根目录即包含一个完整安装示例.agents/manifest.json1332 行记录全部 20 个 agent、47 个 skills、13 个 workflows 的版本依赖与工具声明、.agents/VERSION2026.8.31以及规则、记忆、hooks含validate-tool-call.mjs安全钩子与sync-mcp.mjsMCP 同步脚本、schemas、校验脚本等真实组件可随时对照学习。使用建议更新前养成ag-kit update --dry-run的习惯先在计划中确认 Conflicts 为 0 再真正执行不要让本地改动与上游版本积压太久——两边同时改动是冲突的主要来源及时合并式更新反而冲突更少replace只在明确要放弃所有本地定制时使用且务必保留备份目录退出码为2时不要忽略逐个处理.agents/.ag-kit/conflicts/下的.incoming文件不要在项目.gitignore中忽略.agents/Antigravity 需要索引其中的规则、技能与工作流若只想让它留在本地改用.git/info/exclude详见 README.md 的 Quick start 一节。许可AG Kit CLI 以 MIT 许可发布。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考