agit

# Agit Git 记录代码变更。Agit 记录自主代理的工作。 Agit 是一个开放的协议和命令行界面，用于跟踪、证明、回放和安全地回滚 AI 代理在代码、工具、数据库和基础设施上的操作。 Agit 不是用来取代 Git。它与 Git 并存，记录 Git 历史无法捕捉的工作：意图、代理运行时、工具调用、命令输出、证明工件、风险级别和可用的回滚路径。 ## 为什么 AI 代理开始编辑仓库、安装包、运行迁移、调用 API、部署服务和影响生产系统。普通的提交历史只能回答： > 哪些文件发生了变化？ Agit 回答： > 自主工作发生了什么，为什么发生，使用了哪些工具，存在什么证明，可以撤销吗？ ## 代理原生用法 人类通常不需要手动操作 Agit。一个人类说： > “取消上次更改。” 代理调用： ```sh agit revert latest ``` 一个人类说： > “在你触摸数据库之前，确保我们可以返回。” 代理调用： ```sh agit plan --intent "delete inactive users" -- psql -c "delete from users where ..." agit guard -- psql -c "delete from users where ..." agit db snapshot --table users --where "status = 'inactive'" "before database cleanup" agit exec --intent "delete inactive users" --allow-risk R3 --db-snapshot db-... -- psql -c "delete from users where status = 'inactive'" ``` ## 快速开始 对于本地开发： ```sh npm install npm link --workspace packages/cli npm link --workspace packages/mcp agit install codex ``` `agit install codex` 安装 Codex 技能并注册 `agit-mcp` 服务器。安装完成后重启 Codex，以便加载新的技能和 MCP 工具服务器。 ```sh node packages/cli/bin/agit.js init node packages/cli/bin/agit.js checkpoint "before agent work" node packages/cli/bin/agit.js start "multi-step agent work" node packages/cli/bin/agit.js finish node packages/cli/bin/agit.js exec --intent "change README" -- node -e "require('fs').appendFileSync('README.md', '\nhello\n')" node packages/cli/bin/agit.js prove latest node packages/cli/bin/agit.js log node packages/cli/bin/agit.js show latest node packages/cli/bin/agit.js revert latest ``` 打包后，预期的命令是： ```sh agit init agit start "multi-step agent work" agit finish agit exec --intent "fix failing tests" -- npm test agit guard -- terraform apply agit plan --intent "delete dummy users" -- psql -c "delete from users where status='inactive'" agit install codex agit provider status package agit db snapshot --table users --where "status = 'inactive'" "before delete" agit exec --intent "delete inactive users" --allow-risk R3 --db-snapshot db-... -- psql -c "delete from users where status='inactive'" agit revert latest --url postgresql:///mydb agit package snapshot "before dependency install" agit package restore latest agit prove latest agit revert latest ``` ## 当前原型范围 - 本地 `.agit/` 工作区存储。 - 具有意图、工具调用、风险、git 前/后状态、stdout、stderr 和证明元数据的代理会话记录。 - `exec` 命令/工具调用的包装器。 - 当运行从干净的 Git 工作树开始时，文件更改的可逆转。 - 用于 JavaScript 包清单和锁定文件的包快照和恢复提供程序。 - 用于 `npm`、`pnpm`、`yarn` 和 `bun` 变更命令的自动包快照。 - 用于显式表/WHERE 范围的 PostgreSQL 行快照和恢复提供程序。 - 数据库快照可以与 `agit exec --db-snapshot <id>` 附加到会话，并通过 `agit revert` 恢复。 - 提供程序注册表和用于已实现和计划的可逆转提供程序的通用提供程序命令。 - 通过 `agit-mcp` 的 MCP 服务器基础。 - 用于 Agit 技能和 MCP 注册的 Codex 安装程序。 - 常见危险命令的保守风险分类。 - 具有 `agit guard` 和 `agit exec --allow-risk` 的策略门。 - 使用 `agit plan` 进行撤销规划。 - 检查点、会话和撤销的 Nix 样式生成。 - 用于代理审计历史的 JSONL 操作账本。 - 使用 `agit prove` 的证明摘要。 - 使用 `agit blame <file>` 的代理归责。 - 使用 `agit memory` 的跨代理内存笔记。 - 用于 Codex、Claude Code、Hermes、Mercury、OpenClaw 和 MCP 的适配器模板。 ## v0.1 的非目标 - Agit 不会神奇地恢复 Agit 存在之前更改的数据。 - Agit 不承诺对发送电子邮件、转移资金或部署不可变合约等不可逆操作进行真正的撤销。 - Agit 不会取代数据库备份、快照、Git 或人工审批。 ## 核心思想 每个代理操作都应具有可逆转合约： ```txt R0 只读 R1 文件可逆转 R2 事务可逆转 R3 快照可逆转 R4 补偿操作 R5 不可逆转 ``` Agit 应该让代理在采取实际操作之前询问：“返回的方式是什么？” ## 命令 ```sh agit init agit checkpoint <label> agit start <intent> agit finish [current|session-id] agit exec [--intent <text>] [--allow-risk R3] [--db-snapshot <id>] -- <command> [args...] agit risk -- <command> [args...] agit guard -- <command> [args...] agit plan [--intent <text>] -- <command> [args...] agit policy agit install codex-skill [--force] agit install codex-mcp agit install codex [--force] agit provider list agit provider show <provider> agit provider status <provider> agit provider snapshot <provider> [label] agit provider restore <provider> [latest|snapshot-id] agit db status [--url <connection>] agit db snapshot --table <table> [--where <sql>] [--primary-key <column>] [--url <connection>] [label] agit db list agit db restore [latest|snapshot-id] [--url <connection>] agit package status agit package snapshot [label] agit package list agit package restore [latest|snapshot-id] agit proof add [--label <label>] [--file <path>] [--text <text>] agit prove [latest|session-id] agit blame <file> agit generations agit memory list agit memory add [--label <label>] <text> agit log agit show [latest|session-id] agit revert [latest|session-id] [--url <database-connection>] ``` ## MCP Agit 附带一个最小的 stdio MCP 服务器： ```sh agit-mcp ``` 当前 MCP 工具包括 checkpoint、guard、plan、add proof、prove、revert、blame、provider discovery/status/snapshot/restore、database status/snapshot/restore/list、package status/snapshot/restore/list 和 memory add/list。 对于 Codex： ```sh agit install codex-mcp ``` ## 路线图 参见 [ROADMAP.md](./ROADMAP.md)。 ## 项目跟踪 - [VISION.md](./VISION.md)：产品愿景和长期方向。 - [STATUS.md](./STATUS.md)：当前实现状态和下一个里程碑。 - [DECISIONS.md](./DECISIONS.md)：持久的设计决策。