# ATBClone
**Repository Path**: stonebox/ATBClone
## Basic Information
- **Project Name**: ATBClone
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[中文版](Readme_zh.md) [English](Readme.md) | 📖 **[用户使用手册 (中文)](docs/guide/zh-cn/README.md)** | **[User Guide (EN)](docs/guide/en/README.md)**
# ATBClone (macOS 应用多开引擎)
> 🚀 **ATBClone** 是一个专为 macOS 设计的现代化应用程序多开(Multi-Instancing)与分身管理引擎。支持独立数据隔离、独立网络代理(HTTP / SOCKS5)、自动化规则匹配、重签名与沙盒解除。
>
> 📖 **新手小白入门指引?** 请查阅手把手图文操作指南:**[ATBClone 中文使用手册](docs/guide/zh-cn/README.md)** | **[English Manual](docs/guide/en/README.md)**。
---
## 📥 软件下载 (Download)
请前往 [GitHub Releases](https://github.com/aitobox/ATBClone/releases) 页面下载最新版本的 ATBClone。
Release 页面主要提供两个发布文件,**核心功能完全一致**:
| 发布包 | 适用人群 | 说明 |
| :--- | :--- | :--- |
| **`ATBClone-arm-0.9.7.dmg`** | 👶 **普通用户 / 小白用户(强烈推荐)** | macOS 原生 GUI 桌面客户端安装包 (`.dmg`)。提供现代化卡片式图形界面,零终端操作门槛,开箱即用。 |
| **`ATBCloneCli.tar.gz`** | ⚡ **专业用户 / 开发者** | 独立二进制命令行工具归档(`ATBCloneCli`)。无需安装 Python 环境,专为终端极客、脚本自动化与高级运维场景打造。 |
> 💡 **使用建议与指引**:
> - **普通用户 / 小白用户**:请**优先下载并使用 GUI 图形界面版 (`.dmg`)**。图形化操作简单直观,支持卡片化浏览、一键克隆、状态查看、快捷启动与偏好设置。
> - **专业用户 / 开发者**:推荐使用 **CLI 命令行工具 (`ATBCloneCli` / `atbclone`)**,支持丰富的子命令、深度架构探测、批量脚本与灵活参数调优。
---
## ✨ 核心特性
- 📦 **双引擎克隆架构 (Dual-Engine Cloning Mechanism)**:
- **硬克隆 (Hard Clone)**:面向原生/社交与独立架构应用(微信、QQ、Telegram、AI 客户端、Chrome、Edge、Arc 等)。完整复制 App Bundle,修改 `Info.plist` 与 Bundle Identifier,通过二进制劫持启动脚本注入独立 `HOME` / `TMPDIR` 数据目录,支持按需剥离 App Sandbox 沙盒限制,并完成 Ad-hoc 重新签名。
- **软克隆 (Soft Clone)**:面向现代代码编辑器与浏览器(Cursor、VS Code、Firefox、Brave、Tor、Zed 等)。生成轻量级启动器包装(Wrapper Bundle),自动注入 `--user-data-dir` / `--profile` 参数与独立代理环境变量。
- 🔍 **智能应用探测 (App Prober)**:遇到未预设规则的任意 macOS 应用程序时,自动分析其 Mach-O 架构、Frameworks 与代码签名沙盒权限,动态决定软/硬克隆策略并提取推荐规则。
- 🌐 **独立网络代理 (Isolated Network Proxies)**:为每个分身实例配置独立的 HTTP 或 SOCKS5 代理(支持认证),与系统主网络及母体应用互不干扰。
- 📑 **规则引擎 (Recipe Engine)**:内置 33+ 常用应用与 AI Agent 工具分身规则,支持通过 `~/ATBClone/recipes/` 本地优先级覆盖自定义规则。
- 🪄 **交互式向导 (Interactive Wizard)**:全流程引导式 CLI,支持终端拖拽 `.app` 路径、自动命名递增、自定义数据目录与快捷代理配置。
- 🔄 **生命周期管理**:查看已有分身(`list`)、主应用升级后一键重克隆并保留用户数据(`update`)、安全删除分身(`remove` 支持 `--with-data` / `--keep-data` 与交互确认)。
- 🛡️ **安全与提权机制**:默认克隆至 `~/ATBClone/Apps` 无需 root/sudo 权限;如需写入系统级 `/Applications` 采用原生单次 `osascript` 授权提权;严格使用 `shlex.quote` 保证路径转义安全。
---
## 🖥️ 图形化界面使用指南 (GUI — 推荐普通用户使用)
> 💡 **新手与普通用户提示**:如果您不习惯终端命令行操作,请直接从 [GitHub Releases](https://github.com/aitobox/ATBClone/releases) 下载 `ATBClone-arm-0.9.7.dmg` 安装包,将 `ATBClone.app` 拖入 `应用程序` 文件夹即可直接运行使用!
macOS 原生桌面图形客户端提供直观、全功能的应用分身管理:
1. **仪表盘与分身卡片 (Dashboard)**:
- 以现代卡片式布局清晰展示所有分身应用,直观查看应用图标、克隆策略、独立代理状态与创建时间。
- 支持一键启动分身、一键升级(同步原应用并完整保留聊天记录与登录数据)以及安全卸载清理。
2. **可视化新建分身向导**:
- 支持拖拽或文件选择器选取任意 `.app` 应用本体。
- 自动匹配内置规则或动态触发深度架构探测。
- 可视化自定义分身名称、显示标题、独立数据目录(如外接移动硬盘)以及 HTTP/SOCKS5 专属代理配置。
3. **内置规则库 (Recipe Library)**:
- 分类浏览内置的 32+ 热门应用规则(微信、QQ、Chrome、Cursor、ChatGPT、Claude 等),查看沙盒剥离与隔离策略。
4. **应用深度探测器 (App Prober)**:
- 可视化检测任意未知应用的 Mach-O 架构、Frameworks 与沙盒权限,一键生成专属分身规则。
5. **系统健康自检 (Doctor)**:
- 一键自检系统版本、Xcode 命令行工具、代码签名环境与存储权限,保障分身稳定运行。
6. **多语言与菜单栏托盘**:
- 内置多国语言支持(简体中文、繁體中文、English、日本語、한국어 等),支持最小化至 macOS 菜单栏托盘常驻。
*(开发者如需从源码启动 GUI:运行 `bash scripts/run_gui.sh` 或 `python -m atbclone.gui`)*
---
## 🚀 命令行工具使用指南 (CLI — 专业用户 / 脚本自动化)
> ⚡ **专业用户与自动化场景**:CLI 工具(`atbclone` 或独立二进制 `ATBCloneCli`)提供完整的终端控制能力,支持丰富的子命令与漂亮的 Rich 终端输出,适合极客与脚本集成。
### 1. 交互式向导(CLI 引导模式)
无需记忆参数,根据终端提示一步步操作:
```bash
atbclone wizard
```
*流程包括:拖入 `.app` 路径 ➔ 自动匹配分身规则 ➔ 设置分身名称 ➔ 设置显示名称与图标 ➔ 选择输出路径 ➔ 自定义数据目录(若支持) ➔ 可选配置代理 ➔ 确认生成。*
---
### 2. 命令行快速克隆 (`clone`)
#### 基础克隆(自动递增编号,默认输出至 `~/ATBClone/Apps`)
```bash
atbclone clone /Applications/WeChat.app
```
#### 指定分身名称与输出目录
```bash
atbclone clone /Applications/WeChat.app --name "微信工作版" --output-dir ~/ATBClone/Apps
```
#### 自定义数据存储目录 (`--data-dir`)
对于支持数据隔离的应用(如 Chromium 系列、Firefox、微信等),可指定自定义数据存储路径(例如放置于外部 SSD 或专属工作区):
```bash
atbclone clone /Applications/Chrome.app --name "Chrome-Custom" --data-dir /Volumes/ExternalSSD/ChromeData
```
*注:系统会自动探测应用是否支持数据隔离;若目标应用无数据隔离规则(如 Zed),将自动拦截并提示错误。*
#### 未预设规则应用克隆(自动触发深度探测)
克隆未内置规则的应用时,ATBClone 会自动触发 App Prober 探测架构与沙盒权限,动态生成最佳规则后执行克隆:
```bash
atbclone clone /Applications/ATBCmder.app --name "ATBCmder-Work"
```
#### 为分身配置专属独立网络代理 (HTTP / SOCKS5)
```bash
# 配置 HTTP 代理
atbclone clone /Applications/Telegram.app \
--name "Telegram-Proxy" \
--proxy-host 127.0.0.1 \
--proxy-port 7890 \
--proxy-type http
# 配置 SOCKS5 代理
atbclone clone /Applications/ChatGPT.app \
--name "ChatGPT-US" \
--proxy-host 127.0.0.1 \
--proxy-port 1080 \
--proxy-type socks5
```
---
### 3. 查看分身列表 (`list`)
通过漂亮的 Rich 表格查看所有由 ATBClone 管理的分身状态:
```bash
atbclone list
```
输出示例:
```
┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 名称 ┃ 原 APP ┃ Bundle ID ┃ 策略 ┃ 创建时间 ┃ 代理 ┃
┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 微信2 │ 微信 │ com.tencent.xinWeChat │ hard_clone │ 2026-08-18 22:30 │ 未开启 │
│ TG-Proxy │ Telegram│ ru.keepcoder.Telegram │ hard_clone │ 2026-08-18 22:45 │ http://127.0.0.1:7890 │
│ Chrome2 │ Chrome │ com.google.Chrome │ hard_clone │ 2026-08-18 23:00 │ 未开启 │
└──────────┴─────────┴━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━┘
```
---
### 4. 更新原应用后的分身同步 (`update`)
当 App Store 或官网更新了主应用版本时,一键更新分身,**保留所有聊天记录与登录状态(数据目录不丢失)**:
```bash
atbclone update 微信2
```
---
### 5. 删除分身 (`remove`)
#### 交互式删除(推荐)
在终端中直接执行删除时,系统会交互式询问是否同时清理数据目录:
```bash
atbclone remove 微信2
# 交互提示:是否同时删除数据目录 /Users/.../ATBClone/Data/微信2?[y/N]
```
#### 显式同时删除分身应用及数据目录 (`--with-data`)
```bash
atbclone remove 微信2 --with-data
```
#### 显式仅删除应用本体并保留数据 (`--keep-data`)
```bash
atbclone remove 微信2 --keep-data
```
*注:若分身应用或数据目录位于需要管理员权限的系统目录(如 `/Applications`),系统会自动通过一次提权安全清理。*
---
### 6. 分身规则管理与自定义扩展 (`recipe`)
#### 列出所有内置应用分身规则
```bash
atbclone recipe list
```
#### 查看特定应用的分身规则 YAML
```bash
atbclone recipe show com.tencent.xinWeChat
```
#### 自定义与覆盖分身规则
在 `~/ATBClone/recipes/.yaml` 放置 YAML 规则文件即可自动优先加载覆盖:
```yaml
# 示例:~/ATBClone/recipes/com.example.customapp.yaml
bundle_id: com.example.customapp
app_name: CustomApp
strategy: hard_clone
app_type: cocoa # 可选类型:cocoa, electron, chromium, firefox, generic
strip_sandbox: false # false (推荐): 依托 macOS 原生容器沙盒隔离;true: 强制剥离沙盒
environment_injection:
HOME: '{{ATB_DATA_DIR}}/Home'
TMPDIR: '{{ATB_DATA_DIR}}/Tmp'
proxy:
enabled: true
type: http
host: 127.0.0.1
port: 7890
```
---
### 7. 深度应用探测与分身规则生成 (`probe`)
对任意本地 `.app` 进行深度架构与代码签名权限探测,分析其运行内核(Chromium / Electron / Gecko / Native)、沙盒状态,并输出推荐的 ATBClone Recipe YAML:
#### 基础探测与终端展示
```bash
atbclone probe /Applications/ATBCmder.app
```
#### 探测并直接保存至本地规则库 (`~/ATBClone/recipes/.yaml`)
```bash
atbclone probe /Applications/ATBCmder.app --save
```
#### 导出分身规则到指定文件
```bash
atbclone probe /Applications/ATBCmder.app -o /path/to/recipe.yaml
```
#### 机器可读 JSON 输出
```bash
atbclone probe /Applications/ATBCmder.app --json
```
---
### 8. 查看版本与系统信息 (`version`)
```bash
# 查看详细系统与运行环境信息
atbclone version
# 仅输出版本号
atbclone version --short
# 或
atbclone --version
```
---
## 📋 内置分身规则 (Built-in Recipes)
| 类别 | 应用名称 | Bundle Identifier | 克隆策略 | 应用类型 (App Type) | 沙盒解除 (Strip Sandbox) |
| :--- | :--- | :--- | :--- | :--- | :---: |
| **即时通讯 & 协同办公** | 微信 (WeChat) | `com.tencent.xinWeChat` | Hard Clone | `cocoa` | ✔ |
| | QQ | `com.tencent.qq` | Hard Clone | `electron` | ✔ |
| | 飞书 (Lark) | `com.electron.lark` | Hard Clone | `electron` | ✔ |
| | Telegram (原生 Swift) | `ru.keepcoder.Telegram` | Hard Clone | `cocoa` | ✔ |
| | Telegram Desktop | `org.telegram.desktop` | Hard Clone | `generic` | ✔ |
| | LINE | `jp.naver.line.mac` | Hard Clone | `cocoa` | ✔ |
| | Slack | `com.tinyspeck.slackmacgap` | Hard Clone | `electron` | ✔ |
| | Discord | `com.hnc.Discord` | Hard Clone | `electron` | ✔ |
| | Skype | `com.skype.skype` | Hard Clone | `electron` | ✔ |
| **AI 客户端** | Claude | `com.anthropic.claudefordesktop` | Hard Clone | `electron` | ✔ |
| | ChatGPT (Codex) | `com.openai.codex` | Hard Clone | `cocoa` | ✔ |
| | ChatGPT (标准版) | `com.openai.chat` | Hard Clone | `cocoa` | ✔ |
| | Gemini | `com.google.GeminiMacOS` | Hard Clone | `cocoa` | ✔ |
| | Antigravity | `com.google.antigravity` | Hard Clone | `electron` | ✔ |
| | Antigravity IDE | `com.google.antigravity-ide` | Hard Clone | `electron` | ✔ |
| **浏览器** | Google Chrome | `com.google.Chrome` | Hard Clone | `chromium` | — |
| | Microsoft Edge | `com.microsoft.edgemac` | Hard Clone | `chromium` | — |
| | Brave Browser | `com.brave.Browser` | Soft Clone | `chromium` | — |
| | Firefox | `org.mozilla.firefox` | Soft Clone | `firefox` | — |
| | Tor Browser | `org.torproject.torbrowser` | Soft Clone | `firefox` | — |
| | Arc Browser | `company.thebrowser.Browser` | Hard Clone | `chromium` | — |
| **音视频与社交娱乐** | 哔哩哔哩 (Bilibili) | `com.bilibili.bilibiliPC` | Hard Clone | `electron` | ✔ |
| | 抖音 (Douyin) | `com.bytedance.douyin.desktop` | Hard Clone | `electron` | ✔ |
| | 网易云音乐 | `com.netease.163music` | Hard Clone | `chromium` | ✔ |
| | Steam | `com.valvesoftware.steam` | Hard Clone | `cocoa` | ✔ |
| **生产力与实用工具** | WPS Office | `com.kingsoft.wpsoffice.mac` | Hard Clone | `cocoa` | ✔ |
| | 剪映专业版 | `com.lemon.lvpro` | Hard Clone | `chromium` | ✔ |
| | CapCut | `com.lemon.lvoverseas` | Hard Clone | `chromium` | ✔ |
| **开发工具** | Cursor | `com.todesktop.230313mzl4w4u92` | Soft Clone | `electron` | — |
| | VS Code | `com.microsoft.VSCode` | Soft Clone | `electron` | — |
| | Android Studio | `com.google.android.studio` | Hard Clone | `generic` | ✔ |
| | Zed | `dev.zed.Zed` | Soft Clone | `generic` | — |
> [!WARNING]
> **关于企业微信 (WeCom / `com.tencent.WeWorkMac`)**:
> 由于企业微信客户端深度集成了定制版 CEF (Chromium Embedded Framework) 多进程架构与强绑定的 Seatbelt / Helper 子进程沙盒校验机制,目前在 macOS 上无法实现无损独立分身,ATBClone 暂不支持企业微信的多开分身。
---
## 🛠️ 开发与环境依赖 (Development Setup)
- **操作系统**:macOS 13.0+ (Apple Silicon arm64 / Intel x86_64)
- **Python**:Python 3.12+(`build_cli.sh` 编译时强制要求;推荐使用 Conda)
- **系统开发工具**:已安装 Xcode Command Line Tools(提供 `codesign`, `xcode-select`, `PlistBuddy`)
```bash
# 1. 安装 Xcode Command Line Tools (若尚未安装)
xcode-select --install
# 2. 切换到项目目录并激活 Conda 环境,以可编辑模式安装全部依赖 (含 GUI)
conda activate ATBClone
pip install -e ".[dev,gui]"
# 3. 运行环境自检
atbclone doctor
```
---
## 🏷️ 语义化版本管理 (Version Management)
项目采用标准的语义化版本号格式 `x.y.z`(当前版本:`0.9.7`),并提供了专用的版本管理脚本 `scripts/manage_version.py`:
```bash
# 1. 检查各配置文件版本是否一致
python scripts/manage_version.py --show
# 2. 语义化升级版本 (patch: 0.9.7 -> 0.9.8, minor: 0.9.7 -> 0.10.0, major: 0.9.7 -> 1.0.0)
python scripts/manage_version.py --bump patch
python scripts/manage_version.py --bump minor
python scripts/manage_version.py --bump major
# 3. 指定显式版本
python scripts/manage_version.py 0.9.7
# 4. 预览变更(不实际写入文件)
python scripts/manage_version.py --bump patch --dry-run
```
*脚本会自动同步更新 `pyproject.toml`、`src/atbclone/__init__.py` 等目标文件的版本定义。*
---
## 🏗️ 独立二进制构建与打包 (Build)
项目提供了自动化构建与打包脚本,支持独立 CLI 二进制及 GUI DMG 安装包构建:
```bash
# 1. 构建 CLI 独立二进制 (生成于 dist/ATBCloneCli)
bash scripts/build_cli.sh
# 2. 构建 GUI 原生安装包 (生成于 dist/ATBClone-0.9.7.dmg)
bash scripts/build_gui.sh
```
构建完成后将在 `dist/` 目录生成产物:
```bash
# 验证 CLI 独立二进制
./dist/ATBCloneCli --help
./dist/ATBCloneCli version
./dist/ATBCloneCli doctor
./dist/ATBCloneCli probe /Applications/ATBCmder.app
```
---
## 🧪 运行测试
本项目严格遵循 TDD 与自动化验证规范,包含完整的单元测试与集成测试:
```bash
PYTHONPATH=src conda run -n ATBClone python -m pytest tests/ -v
```
---
## 📂 目录与数据存储架构
```
~/ATBClone/
├── config.yaml # 用户配置与偏好设置 (语言、托盘等)
├── clones.yaml # 全局分身状态追踪记录
├── recipes/ # 用户自定义分身规则存放目录 (可选覆盖)
└── Data/ # 各分身独立的数据隔离目录
├── 微信2/
│ ├── Home/ # 隔离的独立用户主目录
│ └── Tmp/ # 隔离的临时目录
└── Chrome2/ # Chrome 独立 User Data 目录
```
```
src/atbclone/
├── cli/ # CLI 命令行层 (Click + Rich)
│ ├── cmd_clone.py # 克隆主命令 (支持未配置规则自动探测)
│ ├── cmd_doctor.py # 环境检测
│ ├── cmd_list.py # 分身列表
│ ├── cmd_probe.py # 应用深度架构探测与规则生成
│ ├── cmd_recipe.py # 分身规则管理
│ ├── cmd_remove.py # 分身删除
│ ├── cmd_update.py # 分身更新
│ ├── cmd_version.py # 版本与系统信息展示
│ └── cmd_wizard.py # 交互式向导
├── core/ # 核心领域模型与克隆引擎
│ ├── app_inspector.py # App 元数据检查与自动编号
│ ├── app_prober.py # 深度架构探测、沙盒检查与动态规则生成
│ ├── clone_task.py # 克隆任务实体
│ ├── engines.py # Soft & Hard 克隆执行引擎
│ ├── models.py # 基础模型
│ └── state.py # YAML 状态管理
├── gui/ # 原生 macOS GUI 桌面客户端层 (Toga / Briefcase)
│ ├── components/ # 可复用 UI 组件 (分身卡片、侧边栏、顶部栏)
│ ├── services/ # GUI 业务服务桥接 (clone, doctor, probe, recipe, tray)
│ └── views/ # GUI 视图 (仪表盘、规则库、探测器、自检、设置、日志)
├── executor/ # 底层执行器 (Direct Subprocess / AppleScript 提权)
│ └── runner.py
└── recipes/ # 规则模型、加载器与 33 个内置规则
├── builtin/ # 内置 YAML 规则
├── loader.py # 规则匹配与优先级加载
└── models.py # Pydantic 校验模型
```
## 📖 用户使用手册 (User Guide)
如需查阅小白入门图文教程、规则定制指南、底层原理解析与常见问题解答,请访问完整手册:
- 🇨🇳 **[简体中文用户使用手册](docs/guide/zh-cn/README.md)**
- [第一章:基础操作与分身管理](docs/guide/zh-cn/01-basic-operations.md)(7 步向导、无损更新、批量操作、安全删除)
- [第二章:冷门应用规则定制与基础参数详解](docs/guide/zh-cn/02-advanced-custom-recipes.md)(智能探针 Prober、规则编辑器、基础参数)
- [第三章:实现原理解析与高级参数全解](docs/guide/zh-cn/03-under-the-hood-and-internals.md)(软硬分身机制、壳劫持、高级参数与路径宏)
- [第四章:常见问题 (FAQ)、系统体检与反馈](docs/guide/zh-cn/04-faq-and-troubleshooting.md)(数据安全、防封号原理解析、Doctor 体检、GitHub 提报指引)
- 🇺🇸 **[English User Guide](docs/guide/en/README.md)**
- [Chapter 1: Basic Operations & Clone Management](docs/guide/en/01-basic-operations.md)
- [Chapter 2: Custom Recipes for Niche Apps](docs/guide/en/02-advanced-custom-recipes.md)
- [Chapter 3: Under the Hood & Advanced Parameters](docs/guide/en/03-under-the-hood-and-internals.md)
- [Chapter 4: FAQ & Diagnostic Troubleshooting](docs/guide/en/04-faq-and-troubleshooting.md)
---
## 📄 License 与 Release Notes
- **使用手册 (Guide)**: [简体中文手册](docs/guide/zh-cn/README.md) | [English Guide](docs/guide/en/README.md)
- **开源协议**: GPL-3.0 License.
- **更新日志 (Release Notes)**: [English](docs/release/ReleaseNote.md) | [简体中文](docs/release/ReleaseNote_zh.md) | [繁體中文](docs/release/ReleaseNote_zh_TW.md) | [日本語](docs/release/ReleaseNote_ja.md) | [한국어](docs/release/ReleaseNote_ko.md) | [Deutsch](docs/release/ReleaseNote_de.md) | [Français](docs/release/ReleaseNote_fr.md) | [Русский](docs/release/ReleaseNote_ru.md) | [Español](docs/release/ReleaseNote_es.md)