Metadata-Version: 2.5
Name: aicsync
Version: 0.1.0
Summary: AI client config sync CLI — back up / migrate Claude Code & Cursor config (MCP, skills, plugins, rules, extensions).
Project-URL: Homepage, https://github.com/hanjinxin/aics
Author: hanjinxin
License-Expression: MIT
License-File: LICENSE
Keywords: backup,claude-code,cli,config,cursor,mcp,sync
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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 填这个空。

## 安装

```bash
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` — 看本机有什么

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

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

### `export` — 打包配置

```bash
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 内容

```bash
python3 aics.py list ./my-bundle
```



### `diff` — bundle vs 本机

```bash
python3 aics.py diff ./my-bundle
```

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

### `install` — 应用到本机

```bash
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

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

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

## 两条使用路径

```mermaid
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 中断。

最小三步:

```bash
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