使用说明
代理同步
跨AI编码代理同步MCP服务器配置和规则。
问题
您使用多个AI编码代理——Claude Code、Cursor、Codex、Gemini。每个都以自己的格式（JSON、TOML）和自己的位置存储MCP服务器配置。手动保持它们同步是乏味且容易出错的。
解决方案
代理同步 获取单个真实源（您的Claude Code配置），并使用一个命令将其同步到所有代理。
┌──────────────┐
│ Claude Code │ Source of Truth
│ .claude.json│ ─── MCP Servers
│ .mcp.json │ ─── Rules (CLAUDE.md)
│ CLAUDE.md │
└──────┬───────┘
│ agentsync sync
├──────────────────┐─────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Cursor │ │ Codex │ │ Antigravity │
│ mcp.json │ │ config.toml │ │mcp_config.json│
│ project.mdc │ │ AGENTS.md │ │ │
└──────────────┘ └──────────────┘ └──────────────┘
安装
pip install agentsync-cli # pip
pipx install agentsync-cli # pipx (recommended for CLI tools)
uvx agentsync-cli # uv (run without installing)
快速开始
agentsync init # Create agentsync.yaml config
agentsync sync # Sync to all agents
agentsync validate # Verify everything is correct
特性
- MCP服务器同步 --JSON↔ TOML自动转换
- 规则同步 --Markdown→ 使用frontmatter过滤Markdown/MDC
- 不区分大小写的重复数据删除 --手柄
Notion对比notion来自不同来源 - 干运行模式 --编写前预览更改
- 备份 --每次写入前自动备份
- 验证 --结构检查、一致性、重复检测
- 可扩展 --基于适配器的架构用于添加新代理
支持的代理
| 代理 | MCP格式 | 规则格式 | 状态 |
|---|---|---|---|
| 克劳德代码 | JSON | Markdown | 源代码 |
| 游标 | JSON | MDC | 目标 |
| Codex | TOML | Markdown | 目标 |
| 反重力（双子座） | JSON | -- | 目标 |
配置
创建 agentsync.yaml 在项目根目录中：
version: 1
source:
type: claude
global_config: ~/.claude.json
project_mcp: .mcp.json
rules_file: CLAUDE.md
targets:
cursor:
type: cursor
mcp_path: ~/.cursor/mcp.json
rules_path: .cursor/rules/project.mdc
exclude_servers: []
codex:
type: codex
config_path: ~/.codex/config.toml
rules_path: AGENTS.md
exclude_servers: [codex]
antigravity:
type: antigravity
mcp_path: ~/.gemini/antigravity/mcp_config.json
protocols: [stdio]
rules:
exclude_sections:
- "MCP Servers"
- "Context Management & Agents"
CLI参考
全局选项
| 选项 | 描述 |
|---|---|
--config, -c PATH |
agentsync.yaml的路径（默认：自动发现） |
--quiet, -q |
最小输出 |
--version |
显示版本并退出 |
--help |
显示帮助并退出 |
命令
# Sync — push source configs to targets
agentsync sync # Full sync (MCP + rules)
agentsync sync --dry-run # Preview changes without writing
agentsync sync --mcp-only # Only MCP server configs
agentsync sync --rules-only # Only rules files
agentsync sync -t cursor # Sync specific target only
agentsync sync --no-backup # Skip creating backup files
# Validate — check target configs match source
agentsync validate # Full validation
agentsync validate -v # Verbose (show passed checks too)
agentsync validate -t codex # Validate specific target only
# Init — create config
agentsync init # Create agentsync.yaml
agentsync init --force # Overwrite existing config
# Status — show sync state
agentsync status # Source info, target health, drift
退出代码
| 代码 | 含义 |
|---|---|
0 |
成功 |
1 |
运行时错误（同步失败，验证失败） |
2 |
配置错误（缺少配置、YAML错误、适配器未知） |
运作原理
agentsync sync
│
├─ Load config (agentsync.yaml)
├─ Read source (Claude Code)
│ ├─ ~/.claude.json → global MCP servers
│ ├─ .mcp.json → project MCP servers
│ └─ CLAUDE.md → rules sections
│
├─ Deduplicate (case-insensitive)
├─ Filter (exclude_servers, exclude_sections, protocols)
│
└─ Generate + Write per target
├─ Cursor: mcp.json + project.mdc (MDC frontmatter)
├─ Codex: config.toml (marker-based) + AGENTS.md
└─ Antigravity: mcp_config.json (stdio-only)
添加适配器
agentsync是为扩展而设计的。要添加对新AI代理的支持：
- 创建
src/agentsync/adapters/youragent.py--执行TargetAdapter - 在中注册
cli.py(create_targets) - 将类型添加到
KNOWN_TARGET_TYPES在config.py - 在中编写测试
tests/test_adapter_youragent.py - 更新此自述文件
看 贡献.md 了解详细的指南和完整的适配器接口。
贡献
欢迎投稿！看 贡献.md 作为指导方针。
请查看我们的 行为准则 在做出贡献之前。
更新日志
看 更改日志.md 发布历史。
