aicsync 0.1.0__tar.gz

aicsync-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+build/
+.aics-bundle/

aicsync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hanjinxin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aicsync-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+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

aicsync-0.1.0/README.md

@@ -0,0 +1,177 @@
+# 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

aicsync-0.1.0/aics/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

aicsync-0.1.0/aics/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

aicsync-0.1.0/aics/bundle.py

@@ -0,0 +1,180 @@
+import hashlib
+import json
+import shutil
+import tarfile
+from pathlib import Path
+
+from .config import CLAUDE_DIR, CURSOR_DIR
+from .render import now_iso, host, render_markdown
+from .sanitize import sanitize
+from .scan import scan_claude, scan_cursor
+
+_c = {
+    "reset": "0",
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "magenta": "35",
+    "cyan": "36",
+    "gray": "90",
+}
+
+
+def sha256_file(p: Path):
+    h = hashlib.sha256()
+    with open(p, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def copy_dir(src: Path, dst: Path):
+    if not src.exists():
+        return []
+    copied = []
+    dst.mkdir(parents=True, exist_ok=True)
+    for item in src.iterdir():
+        if item.name.startswith("."):
+            continue
+        target = dst / item.name
+        if item.is_dir():
+            shutil.copytree(item, target, dirs_exist_ok=True)
+            for f in target.rglob("*"):
+                if f.is_file():
+                    copied.append(str(f.relative_to(dst.parent.parent)))
+        else:
+            shutil.copy2(item, target)
+            copied.append(str(target.relative_to(dst.parent.parent)))
+    return copied
+
+
+def export_bundle(out_dir: Path, include_secrets=False):
+    claude = scan_claude()
+    cursor = scan_cursor()
+    csettings, cred = sanitize(claude["settings"], include_secrets)
+    cursor_settings, rred = sanitize(cursor["settings"], include_secrets)
+    claude["settings"] = csettings
+    cursor["settings"] = cursor_settings
+    redacted = cred + rred
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    assets = out_dir / "assets"
+    asset_files = []
+    for kind in ("skills", "commands", "agents"):
+        asset_files += copy_dir(CLAUDE_DIR / kind, assets / "claude" / kind)
+    asset_files += copy_dir(CURSOR_DIR / "rules", assets / "cursor" / "rules")
+
+    (out_dir / "claude_mcp.json").write_text(
+        json.dumps(
+            {
+                "global": claude["mcpServers"],
+                "projects": claude["projects"],
+                "settings": csettings,
+                "plugins": claude["plugins"],
+                "enabledPlugins": claude["enabledPlugins"],
+            },
+            indent=2,
+            ensure_ascii=False,
+        )
+    )
+    (out_dir / "cursor_config.json").write_text(
+        json.dumps(
+            {"mcp": cursor["mcp"], "settings": cursor_settings, "extensions": cursor["extensions"]},
+            indent=2,
+            ensure_ascii=False,
+        )
+    )
+    (out_dir / "INSTALL.md").write_text(render_markdown(claude, cursor, redacted, guide=True))
+
+    manifest = {
+        "tool": "aics",
+        "version": 1,
+        "exportedAt": now_iso(),
+        "sourceHost": host(),
+        "clients": ["claude", "cursor"],
+        "redacted": redacted,
+        "assets": asset_files,
+        "counts": {
+            "claude": {
+                "mcp": len(claude["mcpServers"]),
+                "plugins": len(claude["plugins"]),
+                "skills": len(claude["skills"]),
+                "commands": len(claude["commands"]),
+                "agents": len(claude["agents"]),
+            },
+            "cursor": {
+                "mcp": len(cursor["mcp"]),
+                "rules": len(cursor["rules"]),
+                "extensions": len(cursor["extensions"]),
+            },
+        },
+    }
+    (out_dir / "manifest.json").write_text(json.dumps(manifest, indent=2, ensure_ascii=False))
+    return manifest
+
+
+def make_tar(bundle_dir: Path) -> Path:
+    tar_path = bundle_dir.parent / f"{bundle_dir.name}.tar.gz"
+    with tarfile.open(tar_path, "w:gz") as tar:
+        tar.add(bundle_dir, arcname=bundle_dir.name)
+    return tar_path
+
+
+def load_manifest(bundle: Path):
+    mf = bundle / "manifest.json"
+    if not mf.exists():
+        return None
+    return json.loads(mf.read_text())
+
+
+def list_bundle(bundle: Path, color=False) -> str:
+    def p(text, *styles):
+        return f"\033[{';'.join(_c[s] for s in styles)}m{text}\033[0m" if color else text
+
+    m = load_manifest(bundle)
+    if not m:
+        return f"not an aics bundle (no manifest.json): {bundle}"
+    out = [p(f"bundle @ {bundle}", "bold", "cyan"), f"exported: {m['exportedAt']} from {m['sourceHost']}"]
+    for c, counts in m["counts"].items():
+        out.append(f"{c}: " + ", ".join(f"{k}={v}" for k, v in counts.items()))
+    out.append(f"assets: {len(m['assets'])} files")
+    out.append(f"redacted: {len(m['redacted'])} fields")
+    return "\n".join(out) + "\n"
+
+
+def diff_bundle(bundle: Path, color=False) -> str:
+    def p(text, *styles):
+        return f"\033[{';'.join(_c[s] for s in styles)}m{text}\033[0m" if color else text
+
+    m = load_manifest(bundle)
+    if not m:
+        return "not an aics bundle"
+    claude = scan_claude()
+    cursor = scan_cursor()
+    out = [p("diff (bundle -> local):", "bold", "cyan")]
+    bc = m["counts"]["claude"]
+    cc = {
+        "mcp": len(claude["mcpServers"]),
+        "plugins": len(claude["plugins"]),
+        "skills": len(claude["skills"]),
+        "commands": len(claude["commands"]),
+        "agents": len(claude["agents"]),
+    }
+    for k in bc:
+        sign = "==" if bc[k] == cc[k] else ("+local" if cc[k] > bc[k] else "+bundle")
+        style = "green" if sign == "==" else "yellow"
+        out.append(f"  claude.{k}: bundle={bc[k]} local={cc[k]} " + p(sign, style))
+    bcur = m["counts"]["cursor"]
+    curc = {
+        "mcp": len(cursor["mcp"]),
+        "rules": len(cursor["rules"]),
+        "extensions": len(cursor["extensions"]),
+    }
+    for k in bcur:
+        sign = "==" if bcur[k] == curc[k] else ("+local" if curc[k] > bcur[k] else "+bundle")
+        style = "green" if sign == "==" else "yellow"
+        out.append(f"  cursor.{k}: bundle={bcur[k]} local={curc[k]} " + p(sign, style))
+    return "\n".join(out) + "\n"