aics

AI client config sync — 在不同机器之间备份/迁移你的 Claude Code 与 Cursor 配置(MCP、skills、plugins、commands、agents、rules、extensions)。

纯 Python 标准库,零依赖,零构建。python3 aics.py 直接跑。

为什么需要

你在 Claude Code 和 Cursor 上攒了一套个人配置——MCP servers、skills、plugins、自定义命令、Cursor rules、扩展。换机器或重装系统时,这些散落在 ~/.claude.json、~/.claude/、~/.cursor/ 各处的配置没法一键带走,手动拷贝既容易漏,又容易把明文密钥(API token)带走泄露到别处。

市面已有的工具(Smithery、社区 mcp-sync)只管「从零安装 MCP server」,没有「把我这套配置整体打包、到新机器一键还原」的同端迁移工具。aics 填这个空。

安装

git clone <your-repo> aics && cd aics
chmod +x aics.py bin/aics
# 可选:加到 PATH
ln -s "$(pwd)/bin/aics" /usr/local/bin/aics

要求:Python 3.10+(仅标准库)。

全局选项

-V, --version     版本号
-v, --verbose     详细日志输出到 stderr
-q, --quiet       静默(抑制进度日志)
-h, --help        帮助

结果走 stdout,日志/错误走 stderr,可安全用于管道。退出码:0 成功,1 失败,130 中断。可用 AICS_HOME 环境变量覆盖目标 home(测试/沙箱用)。

交互模式

aics 是 CLI + interactive layer(非全屏 TUI)。TTY 里自动开,管道/agent 走纯文本:

• 无参 aics:TTY 进数字菜单(status/export/list/diff/install/convert/quit),逐项收参;非 TTY 打印 help。
• 颜色:TTY 时 status/diff/list 自动加色(标题青、== 绿、+bundle 黄、redacted 红)。设 NO_COLOR 或非 TTY → 纯文本。
• install 确认门:TTY 且非 --yes 时,先打彩色 diff,再 Apply these changes? [y/N]。答 n 中止(不备份不改);答 y 才备份+应用。非 TTY / --yes 跳过确认,自动化路径不变。

人类有颜色有确认有菜单,agent / aics install bundle | bash / CI 走的仍是干净 stdout + 退出码。

命令

status — 看本机有什么

python3 aics.py status              # 两端都看
python3 aics.py status --client claude

输出 markdown 清单:每个 MCP server 的安装命令、每个 plugin 的 claude plugin install 命令、skills/commands/agents 列表、Cursor 扩展列表。密钥默认脱敏。

export — 打包配置

python3 aics.py export -o ./my-bundle          # 默认脱敏
python3 aics.py export -o ./my-bundle --tar     # 额外打 tar.gz
python3 aics.py export -o ./my-bundle --include-secrets   # 保留明文密钥

生成 bundle 目录:

my-bundle/
├── INSTALL.md            # agent 可读的安装指南(含每项的安装命令)
├── manifest.json         # 机器可读索引(counts / redacted / assets)
├── claude_mcp.json       # MCP servers + settings + plugins 清单
├── cursor_config.json    # MCP + settings + extensions 清单
└── assets/
    ├── claude/{skills,commands,agents}/   # 纯文本资产,直接拷贝
    └── cursor/rules/                     # .mdc 规则文件

list — 看 bundle 内容

python3 aics.py list ./my-bundle

diff — bundle vs 本机

python3 aics.py diff ./my-bundle

逐项对比 MCP/plugins/skills/extensions 的数量差异。

install — 应用到本机

python3 aics.py install ./my-bundle                # 文件类直接应用,网络类只打印
python3 aics.py install ./my-bundle --client claude
python3 aics.py install ./my-bundle --force         # 覆盖已存在项
python3 aics.py install ./my-bundle --yes           # 连网络安装(plugins/扩展)一起跑

行为:

• 执行前先备份当前配置到 ~/.aics/backup/<timestamp>/
• 文件类(MCP JSON 合并、skills/commands/agents/rules 拷贝、settings 合并)直接执行,幂等(已存在跳过,--force 才覆盖)
• 网络类(claude plugin install、cursor --install-extension)默认只打印命令,--yes 才真跑
• 密钥:脱敏字段保持空值并提示手动回填,绝不猜值

convert — Claude skill → Cursor rule

python3 aics.py convert --skill ~/.claude/skills/foo/SKILL.md --out foo.mdc

把 SKILL.md 的 frontmatter 翻译成 Cursor .mdc 格式,无法表达的触发语义打 <!-- TODO -->。

两条使用路径

flowchart LR
    A["aics export"] --> B["bundle + INSTALL.md"]
    B --> C{谁来装?}
    C -->|让 CLI 自己装| D["aics install bundle --yes"]
    C -->|交给 agent| E["agent 读 INSTALL.md\n逐段执行命令"]
    B -.->|密钥| F["redacted 列表\n手动回填"]

Agent 用法

非 TTY 自动无色、无确认门、无菜单。stdout 只放结果(可 grep/parse),stderr 放进度日志。exit code:0 成功 / 1 失败 / 130 中断。

最小三步:

aics export -o b        # 打包(密钥默认脱敏,产物 b/INSTALL.md + manifest.json)
aics install b --yes   # 应用(非交互,--yes 连网络安装一起跑,幂等可重试)
aics diff b            # 验证(全 == 即还原完成)

要点:

• aics status stdout 是 markdown,claude mcp add ... / claude plugin install ... 行可直接执行。
• 密钥在 bundle 里是 null,agent 不猜值;把 manifest.json 的 redacted 列表抛给用户回填。
• 沙箱试跑:AICS_HOME=/tmp/sb aics install b --yes,不碰真实 home。
• install 幂等,重复执行跳过已存在项。

设计:插件为什么是「重装」而不是「拷贝」

~/.claude/plugins/cache/ 里的插件缓存含平台编译产物(darwin-x64 二进制)、git 工作树状态、绝对路径,且全部信息可由 installed_plugins.json 的 name@marketplace + git sha 重建。所以 aics 只导出安装清单,install 时跑 claude plugin install <name>@<marketplace> 按 sha 精确重装——迁的是「安装意图」,不是「缓存尸体」。

skills/commands/agents/rules 是纯文本,直接拷贝,无需重装。

安全模型

• 默认脱敏:所有 JSON 值中匹配 token|key|secret|password|auth|credential 的字段在 export/status 时置空,记入 manifest.redacted
• --include-secrets 显式 opt-in 才保留明文
• install 时不猜密钥值,提示用户手动回填
• install 前自动备份原配置

客户端适配

目前支持 Claude Code + Cursor。新增客户端只需写一个 scan 函数 + apply 函数。

License

MIT