argon

Argon — MongoDB 的 Git

为 MongoDB 创建分支、穿越时光、合并和撤销操作。支持任何驱动，底层使用真实的 mongod，并保留版本历史。专为 AI Agent 打造。

三个要点，三十秒了解：

1. 分支是指针，而不是副本——通过写入元数据创建。检出操作会单独物化数据。
2. checkout 将分支变成真正的 MongoDB 数据库——pymongo、 mongoose、mongosh、索引、聚合、事务：一切都是真实的；捕获功能正常时，受支持的文档写入都会成为历史记录。
3. 审查和恢复更改——在配置的保留期限和捕获保障范围内，比较差异、合并、撤销并固定状态。

安装

使用 npm 时，请安装 Node.js 24 LTS 和 npm 11.16 或更高版本。包级审批允许安装程序在 npm 12 上下载 Argon 的二进制文件。

brew install argon-lab/tap/argonctl      # macOS
npm install -g argonctl --allow-scripts=argonctl # cross-platform

# MongoDB must run as a replica set (one-node is fine):
docker run -d --name argon-mongo -p 127.0.0.1:27017:27017 mongo:7 --replSet rs0
docker exec argon-mongo mongosh --quiet --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"localhost:27017"}]})'
argon doctor

在生产环境中使用当前受支持的 MongoDB 补丁版本。根据 go.mod 的声明，从源代码构建需要 Go 1.26.9 或更高版本。请使用已修补的工具链：Go 1.27.0–1.27.1 也存在 2026 年 10 月的标准库漏洞。

工作流程

main ──branch──▶ experiment ──checkout──▶ mongodb://…  ← any driver
                                              │
                     ┌── argon diff ──────────┤  document history
                     ▼                        ▼
        merge (a data PR)          or   undo / discard / rewind

# 0 · Stop source writers and DDL for the import — or: argon projects create myapp
argon import database --uri mongodb://localhost:27017 --database myapp --project myapp --source-quiesced

# 1 · Branch — instant, no copy
argon branches create experiment -p myapp

# 2 · In terminal A, capture writes with a branch actor label
argon checkout -p myapp -b experiment      # prints a connection string
argon watch    -p myapp -b experiment --actor agent:experiment

# In terminal B, write through the printed URI. Then:

# 3 · Review and merge back — a data pull request
argon diff          -p myapp -b experiment
argon merge preview -p myapp -b experiment
argon merge apply <plan-id>

# …or rewind instead of merging
argon restore reset -p myapp -b main --time 2026-07-07T09:00:00Z --backup pre-incident

更喜欢点击操作？argon console 会启动本地 Web 控制台（UI + REST API），管理捕获流程，每分钟清理过期沙箱，并打开浏览器。 控制台采用 MIT 许可，其源代码位于 web/；请参阅重建说明。 如需完整的托管工作流，请运行双 Agent 固定数据集示例。

你将获得

	命令	一句话说明
分支	argon branches create	写入元数据——即时完成，零复制
真实数据库	argon checkout / argon proxy	支持任意驱动，使用真正的 mongod；代理提供稳定的 mongodb://host/<project>~<branch> URI
写入捕获	argon watch	精确的变更流快照 → 历史记录，每个分支对应一个操作者标签
时间旅行	argon time-travel query	查询保留的 LSN 对应的已捕获文档状态；还原和固定操作也接受时间戳
撤销	argon undo --actor <a>	撤销一个范围或操作者标签；仅追加、可感知冲突
还原	argon restore preview/reset/branch	回退已发布的分支，或从保留的历史记录派生分支
数据 PR	argon merge preview/apply	将三方合并作为可审查的计划；冲突绝不会被静默处理
沙箱	argon sandbox create --ttl 1h	一步完成派生分支、检出和 TTL 设置——可随时丢弃的 Agent 工作区
数据集固定	argon pin create / pin sandbox	命名的已捕获状态；固定存在期间可防止 GC 和重置操作影响这些状态
Web 控制台	argon console	一条命令启动本地 UI 和 REST API

数据历史涵盖文档插入、更新、替换和删除。删除/重命名集合会导致捕获能力降级；索引和集合选项不会进行版本管理。原生写入是异步的；控制操作会等待捕获完成。发布前请停止写入程序。现有固定项会保护其引用的状态，但 GC 可能会使审计和撤销历史过期。恢复和凭据请参阅运维文档。

存储保留策略使用快照和保留窗口 GC 来保留当前状态及一段时间的历史记录，而非永久保留每次写入。详情和一致性模型（如实说明）：ARCHITECTURE.md。

面向 AI Agent

claude mcp add argon -- argon mcp        # 13 tools: sandbox, diff, merge, undo, pins
# Install the published Python SDK and LangGraph adapter.
python3 -m pip install 'argon-agents[langgraph]==0.2.0'

在另一个终端中运行 argon console --no-browser，然后：

from argon_agents import ArgonClient, ArgonCheckpointSaver

argon = ArgonClient("http://127.0.0.1:1818")
argon.get_or_create_project("myapp")
saver = ArgonCheckpointSaver.from_sandbox(argon, "myapp")
# Compile and run your LangGraph graph with checkpointer=saver, then review:
plan = argon.merge_preview("myapp", saver.sandbox.branch)
print(plan)
# After reviewing this exact plan, apply it explicitly:
# argon.merge_apply(plan["id"])
# Or reject the run: saver.discard()

argon.create_pin("myapp", "eval-v1")                        # pin the dataset once
run = argon.sandbox_from_pin("myapp", "eval-v1")            # identical state, every eval run

saver.merge() 是一个便捷调用，会立即预览并应用；需要审批时，请改用上面的独立调用。固定项存在期间会保护已捕获的文档状态；请保留独立备份。

完整的 Agent 工作流：docs/AGENTS.md。

文档

快速入门	从安装到首次合并，逐步介绍
CLI 参考	所有命令
Agent	沙箱、固定项、MCP、REST API、argon-agents、代理
架构	工作原理及保证内容
运维	部署、分块存储（S3/FS）、GC、v1→v2 迁移
性能	所有性能数据均来自可复现的基准测试——根据政策，此处不列出数据

社区

问题反馈 · 讨论 · 贡献指南 · argonlabs.tech · 博客

---