# DevPack 用户手册

> 版本：v0.1.0  
> 更新日期：2026-03-03

---

## 目录

1. [简介](#1-简介)
2. [安装](#2-安装)
3. [快速入门](#3-快速入门)
4. [核心概念](#4-核心概念)
5. [命令详解](#5-命令详解)
6. [使用场景](#6-使用场景)
7. [配置文件](#7-配置文件)
8. [常见问题](#8-常见问题)
9. [故障排除](#9-故障排除)

---

## 1. 简介

DevPack 是一个开发环境打包迁移工具。它可以：

- 🔍 **扫描** 你当前电脑上安装的开发工具、配置、环境变量等
- 📦 **打包** 成一个可移植的 `.devpack` 文件
- 🚀 **还原** 在另一台电脑上一键恢复完整开发环境

### 支持的内容

| 类别 | 支持的项目 |
|------|-----------|
| 编程语言 | Go, Node.js, Python, Java, Rust, .NET, Ruby, PHP |
| 包管理器 | Scoop, Chocolatey, Winget, Homebrew, APT |
| 编辑器 | VS Code (扩展+设置), JetBrains IDEs, Vim/Neovim |
| Shell | PowerShell, Bash, Zsh, Fish, Windows Terminal |
| 其他 | Git 配置, 环境变量, SSH 密钥, 字体 |

---

## 2. 安装

### 2.1 通过 Go 安装

```bash
go install github.com/user/devpack@latest
```

### 2.2 通过包管理器安装

**Windows (Scoop):**
```powershell
scoop bucket add devpack https://github.com/user/devpack-bucket
scoop install devpack
```

**Windows (Chocolatey):**
```powershell
choco install devpack
```

**macOS (Homebrew):**
```bash
brew tap user/devpack
brew install devpack
```

### 2.3 下载二进制文件

1. 前往 [GitHub Releases](https://github.com/user/devpack/releases)
2. 下载对应你系统的压缩包
3. 解压到一个目录（如 `C:\Tools\devpack\`）
4. 将该目录添加到系统 PATH

### 2.4 验证安装

```bash
devpack version
```

输出示例：
```
DevPack v0.1.0 (commit: abc1234, built: 2026-03-03)
OS: windows/amd64
```

---

## 3. 快速入门

### 3.1 五分钟上手

```bash
# 第一步：初始化
devpack init

# 第二步：扫描你的环境
devpack scan

# 第三步：打包
devpack capture --name "my-env"

# 第四步：导出为文件（可以拷贝到 U 盘）
devpack export my-env -o my-env.devpack
```

拿到 `.devpack` 文件后，在新电脑上：

```bash
# 第五步：安装 DevPack 后，导入文件
devpack import my-env.devpack

# 第六步：预览将要做的更改
devpack restore my-env --dry-run

# 第七步：正式还原
devpack restore my-env
```

### 3.2 推荐工作流

```
旧电脑                          新电脑
──────                          ──────
devpack init                    (安装 DevPack)
     │                               │
devpack scan                         │
     │                               │
devpack capture --name env           │
     │                               │
devpack export env                   │
     │                               │
     └── my-env.devpack ──(U盘)──▶   │
                                     │
                              devpack import my-env.devpack
                                     │
                              devpack restore env --dry-run
                                     │
                              devpack restore env
                                     │
                              ✅ 环境就绪！
```

---

## 4. 核心概念

### 4.1 Pack（环境包）

Pack 是 DevPack 生成的打包文件（`.devpack` 格式）。它包含：
- **Manifest** — 描述包内容的清单
- **采集器数据** — 各个采集器收集的环境数据
- **校验信息** — 确保文件完整性

一个 Pack 代表某一时刻你的开发环境的"快照"。

### 4.2 Profile（配置方案）

Profile 定义了"打包什么"和"怎么打包"。通过 Profile，你可以：
- 只打包特定的工具链（如只打包 Go + VS Code）
- 排除不需要的内容
- 为不同场景准备不同的配置方案

内置 Profile 模板：
| 模板 | 包含内容 |
|------|---------|
| `minimal` | 只有编辑器设置和 Shell 配置 |
| `standard` | 运行时 + 编辑器 + Shell + Git + 环境变量 |
| `full` | 所有可用的采集器 |

### 4.3 Collector（采集器）

采集器是负责扫描和收集特定类型环境信息的模块。每个采集器独立工作：

| 采集器 | 扫描内容 | 还原方式 |
|--------|---------|---------|
| `go` | Go 版本、go env、GOPATH/bin 工具 | 下载安装器 |
| `node` | Node 版本、npm 全局包 | nvm/直接安装 |
| `python` | Python 版本、pip 全局包 | 安装器/pyenv |
| `vscode` | 扩展列表、settings.json | code --install-extension |
| `powershell` | Profile、已安装模块 | 复制 Profile + Install-Module |
| `scoop` | bucket 列表、已安装包 | scoop install |
| `git` | .gitconfig、aliases | 复制配置 |
| `env` | 用户环境变量 | setx/export |

### 4.4 还原策略

当还原时遇到已存在的配置，DevPack 提供多种处理策略：

| 策略 | 行为 |
|------|------|
| `skip` | 跳过，保留现有配置 |
| `overwrite` | 覆盖，使用 Pack 中的配置 |
| `merge` | 合并两者（适用于配置文件） |
| `prompt` | 逐项询问用户（默认） |
| `newest` | 使用较新的版本 |

---

## 5. 命令详解

### 5.1 devpack init

初始化 DevPack 配置。

```bash
# 默认初始化
devpack init

# 使用 standard 模板
devpack init --template standard

# 指定 Profile 名称
devpack init --profile my-profile
```

这会在 `~/.devpack/` 下创建配置目录和默认配置文件。

### 5.2 devpack scan

扫描当前环境，展示检测到的开发工具和配置。

```bash
# 扫描所有
devpack scan

# 详细模式
devpack scan --detailed

# 只扫描运行时
devpack scan --category runtime

# 只扫描特定采集器
devpack scan -c go,node,vscode

# 输出为 JSON
devpack scan -o json

# 保存扫描结果
devpack scan --save my-scan.json
```

### 5.3 devpack capture

捕获环境数据并创建 Pack。

```bash
# 基本用法
devpack capture --name "my-env"

# 使用 Profile
devpack capture --name "go-env" --profile golang-dev

# 捕获所有
devpack capture --name "full-env" --all

# 只捕获特定采集器
devpack capture --name "editor-env" -c vscode,git

# 带描述和标签
devpack capture --name "v1" \
  --description "生产环境工具链" \
  --tag golang,production
```

### 5.4 devpack restore

从 Pack 还原环境。

```bash
# 先预览
devpack restore my-env --dry-run

# 执行还原
devpack restore my-env

# 跳过冲突项
devpack restore my-env --conflict skip

# 覆盖所有冲突
devpack restore my-env --conflict overwrite

# 只还原特定采集器
devpack restore my-env -c vscode,git

# 跳过确认
devpack restore my-env -y
```

### 5.5 devpack export / import

```bash
# 导出为文件
devpack export my-env -o ~/Desktop/my-env.devpack

# 导入文件
devpack import ~/Desktop/my-env.devpack

# 导入并指定名称
devpack import ~/Desktop/my-env.devpack --name imported-env

# 导入前验证
devpack import ~/Desktop/my-env.devpack --verify
```

### 5.6 devpack diff

对比环境差异。

```bash
# 与当前环境对比
devpack diff my-env --current

# 两个 Pack 对比
devpack diff old-env --with new-env

# 只对比特定采集器
devpack diff my-env --current -c runtime
```

### 5.7 devpack list

```bash
# 列出所有 Pack
devpack list packs

# 列出所有 Profile
devpack list profiles

# 列出所有可用采集器
devpack list collectors

# 详细信息
devpack list packs --detailed
```

### 5.8 devpack profile

```bash
# 创建 Profile
devpack profile create my-profile

# 查看 Profile
devpack profile show my-profile

# 编辑 Profile（使用默认编辑器打开）
devpack profile edit my-profile

# 设置默认 Profile
devpack profile use my-profile

# 删除 Profile
devpack profile delete my-profile

# 列出所有 Profile
devpack profile list
```

---

## 6. 使用场景

### 6.1 个人换电脑

**场景：** 你买了一台新笔记本电脑，需要迁移开发环境。

**步骤：**

在旧电脑上：
```bash
devpack init
devpack scan --detailed            # 确认要迁移的内容
devpack capture --name "laptop-2026" --all
devpack export laptop-2026 -o laptop-2026.devpack
```

将 `laptop-2026.devpack` 拷贝到 U 盘或通过网络传到新电脑。

在新电脑上：
```bash
# 先安装 DevPack
devpack import laptop-2026.devpack
devpack restore laptop-2026 --dry-run    # 预览
devpack restore laptop-2026              # 开始还原
```

### 6.2 团队环境统一

**场景：** 你是 Tech Lead，需要为团队准备统一的开发环境。

**步骤：**

1. 创建团队 Profile：
```bash
devpack profile create team-standard
devpack profile edit team-standard
```

2. 在 Profile 中定义标准配置（编辑 YAML 文件）

3. 使用 Profile 打包：
```bash
devpack capture --name "team-env-v1" --profile team-standard
devpack export team-env-v1 -o team-env-v1.devpack
```

4. 分发给团队成员

5. 成员还原：
```bash
devpack import team-env-v1.devpack
devpack restore team-env-v1
```

### 6.3 项目环境隔离

**场景：** 你同时参与 Go 和 Python 项目，需要不同的环境配置。

**步骤：**

1. 为每个项目创建 Profile：
```bash
devpack profile create golang-project
devpack profile create python-ml
```

2. 分别配置各 Profile 只包含对应工具链

3. 按项目打包：
```bash
devpack capture --name "go-env" --profile golang-project
devpack capture --name "ml-env" --profile python-ml
```

### 6.4 环境排障

**场景：** 同事说"在我电脑上能跑"，你需要对比环境差异。

```bash
# 让同事导出环境
# (同事) devpack capture --name "alice-env" && devpack export alice-env

# 你导入并对比
devpack import alice-env.devpack
devpack diff alice-env --current
```

差异输出会清晰展示两个环境的不同之处。

---

## 7. 配置文件

### 7.1 配置文件位置

| 文件 | 路径 | 说明 |
|------|------|------|
| 全局配置 | `~/.devpack/config.yaml` | DevPack 全局设置 |
| Profile | `~/.devpack/profiles/<name>.yaml` | 命名配置方案 |
| 日志 | `~/.devpack/logs/devpack.log` | 运行日志 |
| Pack 存储 | `~/.devpack/packs/` | 本地 Pack 存储 |

### 7.2 自定义配置示例

```yaml
# ~/.devpack/config.yaml

defaults:
  profile: "standard"
  compression: "gzip"
  conflict_strategy: "prompt"

logging:
  level: "info"

ui:
  color: true
  progress_bar: true

security:
  scan_for_secrets: true
  exclude_patterns:
    - "*_KEY"
    - "*_SECRET"
    - "*_TOKEN"
```

---

## 8. 常见问题

### Q: DevPack 和 Docker 有什么区别？

Docker 用于打包**应用运行环境**，应用运行在容器中；DevPack 用于打包**开发者的本地开发环境**，直接还原到宿主机。两者是互补关系。

### Q: 支持跨操作系统迁移吗？

不支持。DevPack 只支持同一操作系统之间的迁移（Windows → Windows, macOS → macOS）。不同操作系统的工具链和配置差异太大，无法可靠地自动转换。

### Q: 还原会覆盖我现有的配置吗？

默认不会。DevPack 使用 `prompt` 策略，遇到冲突会询问你如何处理。你也可以先使用 `--dry-run` 预览所有更改。

### Q: Pack 文件大小一般多大？

典型的开发环境 Pack 大小在 5-50 MB 之间。Pack 文件只包含配置信息和元数据，不包含实际的安装程序二进制文件（还原时会从网络下载）。

### Q: 密码和密钥安全吗？

DevPack 默认不采集 SSH 密钥和密码。如果你选择采集 SSH 密钥，它们会使用 AES-256-GCM 加密存储。DevPack 不会采集浏览器密码、系统凭证等隐私数据。

### Q: 还原需要网络连接吗？

是的。还原过程需要从网络下载对应版本的安装程序。Pack 文件只包含"安装什么"的信息，不包含安装程序本身。

### Q: 还原失败了怎么办？

如果开启了还原点功能（默认开启），可以使用 `devpack rollback` 撤销所有更改，回到还原前的状态。

---

## 9. 故障排除

### 9.1 查看详细日志

```bash
# 开启详细输出
devpack scan --verbose

# 开启 debug 日志
devpack scan --log-level debug

# 查看日志文件
# Windows
notepad %USERPROFILE%\.devpack\logs\devpack.log
# macOS/Linux
cat ~/.devpack/logs/devpack.log
```

### 9.2 常见错误

| 错误 | 原因 | 解决方案 |
|------|------|---------|
| `collector not available` | 对应的工具未安装 | 安装对应工具或排除该采集器 |
| `pack file corrupted` | Pack 文件损坏 | 使用 `devpack verify` 检查，重新导出 |
| `platform mismatch` | Pack 的系统与当前不一致 | 只能在相同 OS 之间还原 |
| `permission denied` | 权限不足 | 以管理员身份运行 |
| `network timeout` | 下载超时 | 检查网络，或设置代理 |

### 9.3 报告问题

如果遇到无法解决的问题：

1. 运行 `devpack scan --log-level debug --save debug-info.json`
2. 查看 `~/.devpack/logs/devpack.log`
3. 在 [GitHub Issues](https://github.com/user/devpack/issues) 创建 Issue
4. 附上 debug 日志（注意删除敏感信息）