# DevPack 架构设计文档

> 版本：v1.0.0-draft  
> 更新日期：2026-03-03  
> 作者：DevPack Team

---

## 1. 架构概览

### 1.1 设计原则

| 原则 | 说明 |
|------|------|
| **单一二进制** | 编译为无依赖的单一可执行文件 |
| **插件化** | 采集器通过接口抽象，支持扩展 |
| **安全优先** | 敏感数据加密，操作可回滚 |
| **平台适配** | 通过平台适配层处理 OS 差异 |
| **幂等性** | 同一 Pack 多次还原结果一致 |
| **最小侵入** | 只修改用户级配置，不修改系统级设置（除非明确授权） |

### 1.2 高层架构图

```
┌──────────────────────────────────────────────────────────────────┐
│                          CLI Layer (Cobra)                       │
│  ┌──────┐ ┌───────┐ ┌─────────┐ ┌────────┐ ┌──────┐ ┌────────┐ │
│  │ init │ │ scan  │ │ capture │ │restore │ │ diff │ │export/ │ │
│  │      │ │       │ │         │ │        │ │      │ │import  │ │
│  └──┬───┘ └───┬───┘ └────┬────┘ └───┬────┘ └──┬───┘ └───┬────┘ │
└─────┼─────────┼──────────┼──────────┼─────────┼─────────┼──────┘
      │         │          │          │         │         │
┌─────┴─────────┴──────────┴──────────┴─────────┴─────────┴──────┐
│                       Core Engine Layer                         │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│  │   Collector   │ │  Pack Engine │ │    Restore Engine        │ │
│  │   Registry    │ │              │ │                          │ │
│  └──────┬───────┘ └──────┬───────┘ └────────────┬─────────────┘ │
│         │                │                      │               │
│  ┌──────┴───────┐ ┌──────┴───────┐ ┌────────────┴─────────────┐ │
│  │   Profile     │ │   Crypto     │ │   Dependency Resolver    │ │
│  │   Manager     │ │   Module     │ │                          │ │
│  └──────────────┘ └──────────────┘ └──────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────────┐
│                    Platform Abstraction Layer                    │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐             │
│  │  Windows   │    │   macOS    │    │   Linux    │             │
│  │  Adapter   │    │  Adapter   │    │  Adapter   │             │
│  └────────────┘    └────────────┘    └────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────────┐
│                      Collector Plugins                          │
│  ┌─────────┐ ┌─────────┐ ┌────────┐ ┌───────┐ ┌─────┐ ┌─────┐ │
│  │ Runtime │ │ Package │ │ Editor │ │ Shell │ │ Git │ │ Env │ │
│  └─────────┘ └─────────┘ └────────┘ └───────┘ └─────┘ └─────┘ │
│  ┌─────────┐ ┌─────────┐                                       │
│  │  Font   │ │ SSH/GPG │                                       │
│  └─────────┘ └─────────┘                                       │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. 核心模块设计

### 2.1 采集器系统 (Collector System)

采集器是 DevPack 的核心，负责扫描和收集环境信息。所有采集器实现统一的接口。

#### 2.1.1 Collector 接口

```go
// Collector 定义了所有采集器必须实现的接口
type Collector interface {
    // Name 返回采集器名称（唯一标识）
    Name() string

    // DisplayName 返回采集器的显示名称
    DisplayName() string

    // Description 返回采集器的描述信息
    Description() string

    // Category 返回采集器所属分类
    Category() Category

    // IsAvailable 检测当前系统是否支持此采集器
    IsAvailable(ctx context.Context) bool

    // Scan 扫描当前环境，返回扫描结果
    Scan(ctx context.Context, opts ScanOptions) (*ScanResult, error)

    // Capture 捕获环境数据，写入到指定目录
    Capture(ctx context.Context, targetDir string, opts CaptureOptions) error

    // Restore 从指定目录还原环境
    Restore(ctx context.Context, sourceDir string, opts RestoreOptions) error

    // Verify 验证还原后的环境是否正确
    Verify(ctx context.Context) (*VerifyResult, error)
}

// Category 采集器分类
type Category string

const (
    CategoryRuntime Category = "runtime"    // 编程语言运行时
    CategoryPackage Category = "package"    // 包管理器
    CategoryEditor  Category = "editor"     // 编辑器/IDE
    CategoryShell   Category = "shell"      // Shell 配置
    CategoryGit     Category = "git"        // Git 配置
    CategoryEnv     Category = "env"        // 环境变量
    CategoryFont    Category = "font"       // 字体
    CategorySSH     Category = "ssh"        // SSH/GPG 密钥
    CategoryCustom  Category = "custom"     // 自定义
)

// ScanResult 扫描结果
type ScanResult struct {
    Collector   string        `json:"collector"`
    Category    Category      `json:"category"`
    Items       []ScanItem    `json:"items"`
    Timestamp   time.Time     `json:"timestamp"`
    Platform    PlatformInfo  `json:"platform"`
}

// ScanItem 单个扫描项
type ScanItem struct {
    Name        string            `json:"name"`
    Version     string            `json:"version,omitempty"`
    Path        string            `json:"path,omitempty"`
    Properties  map[string]string `json:"properties,omitempty"`
    Size        int64             `json:"size,omitempty"`
    Children    []ScanItem        `json:"children,omitempty"`
}
```

#### 2.1.2 采集器注册中心

```go
// Registry 采集器注册中心
type Registry struct {
    collectors map[string]Collector
    mu         sync.RWMutex
}

// Register 注册一个采集器
func (r *Registry) Register(c Collector) error

// Get 获取指定名称的采集器
func (r *Registry) Get(name string) (Collector, bool)

// List 列出所有已注册的采集器
func (r *Registry) List() []Collector

// ListByCategory 按分类列出采集器
func (r *Registry) ListByCategory(cat Category) []Collector

// ScanAll 使用所有可用的采集器扫描
func (r *Registry) ScanAll(ctx context.Context, opts ScanOptions) ([]*ScanResult, error)
```

#### 2.1.3 内置采集器实现示例

以 Go 运行时采集器为例：

```go
type GoCollector struct{}

func (c *GoCollector) Name() string        { return "go" }
func (c *GoCollector) DisplayName() string { return "Go Runtime" }
func (c *GoCollector) Category() Category  { return CategoryRuntime }

func (c *GoCollector) Scan(ctx context.Context, opts ScanOptions) (*ScanResult, error) {
    result := &ScanResult{
        Collector: c.Name(),
        Category:  c.Category(),
    }

    // 检测 Go 版本
    version, err := exec.CommandContext(ctx, "go", "version").Output()
    // ... 解析版本信息

    // 获取 go env 信息
    envJSON, err := exec.CommandContext(ctx, "go", "env", "-json").Output()
    // ... 解析环境变量

    // 获取全局安装的工具
    // ... 扫描 GOPATH/bin

    return result, nil
}
```

### 2.2 打包引擎 (Pack Engine)

#### 2.2.1 Pack 文件格式

`.devpack` 文件本质上是一个经过组织的 tar.gz 归档文件：

```
my-env.devpack (tar.gz)
├── manifest.json           # Pack 清单（元数据）
├── checksum.sha256         # 文件校验和
├── collectors/             # 各采集器数据
│   ├── runtime/
│   │   ├── go/
│   │   │   ├── metadata.json    # Go 环境元数据
│   │   │   └── data/            # Go 相关数据文件
│   │   ├── node/
│   │   │   ├── metadata.json
│   │   │   └── data/
│   │   └── python/
│   │       ├── metadata.json
│   │       └── data/
│   ├── editor/
│   │   └── vscode/
│   │       ├── metadata.json
│   │       ├── extensions.json  # 扩展列表
│   │       └── data/            # 设置文件
│   │           ├── settings.json
│   │           ├── keybindings.json
│   │           └── snippets/
│   ├── shell/
│   │   ├── powershell/
│   │   │   ├── metadata.json
│   │   │   └── data/
│   │   └── bash/
│   │       ├── metadata.json
│   │       └── data/
│   ├── package/
│   │   └── scoop/
│   │       ├── metadata.json
│   │       └── data/
│   ├── git/
│   │   ├── metadata.json
│   │   └── data/
│   └── env/
│       ├── metadata.json
│       └── data/
└── encrypted/              # 加密数据（可选）
    └── ssh/
        └── data.enc        # 加密的 SSH 密钥
```

#### 2.2.2 Manifest 结构

```go
// Manifest Pack 清单
type Manifest struct {
    // 元信息
    Version     string    `json:"version"`      // DevPack 版本
    FormatVer   string    `json:"format_ver"`   // Pack 格式版本
    Name        string    `json:"name"`         // Pack 名称
    Description string    `json:"description"`  // 描述
    Author      string    `json:"author"`       // 作者
    CreatedAt   time.Time `json:"created_at"`   // 创建时间
    PackID      string    `json:"pack_id"`      // 唯一 ID (UUID)

    // 源环境信息
    Source      SourceInfo `json:"source"`

    // 采集器数据索引
    Collectors  []CollectorEntry `json:"collectors"`

    // 加密信息
    Encryption  *EncryptionInfo  `json:"encryption,omitempty"`

    // 校验信息
    Checksum    string    `json:"checksum"`     // 整包校验和
}

// SourceInfo 源环境信息
type SourceInfo struct {
    Hostname    string `json:"hostname"`
    OS          string `json:"os"`          // windows, darwin, linux
    OSVersion   string `json:"os_version"`
    Arch        string `json:"arch"`        // amd64, arm64
    Username    string `json:"username"`
}

// CollectorEntry 采集器条目
type CollectorEntry struct {
    Name        string   `json:"name"`
    Category    Category `json:"category"`
    ItemCount   int      `json:"item_count"`
    DataPath    string   `json:"data_path"`
    DataSize    int64    `json:"data_size"`
    Checksum    string   `json:"checksum"`
}
```

#### 2.2.3 打包流程

```
用户执行 capture 命令
        │
        ▼
┌─────────────────┐
│  加载 Profile    │ ─── 确定需要运行哪些采集器
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  运行采集器      │ ─── 并行扫描 → 收集数据 → 写入临时目录
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成 Manifest   │ ─── 创建清单文件、计算校验和
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  加密敏感数据    │ ─── 对标记为敏感的数据进行加密（可选）
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  压缩归档       │ ─── tar.gz 打包
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  输出 .devpack   │ ─── 写入最终文件
└─────────────────┘
```

### 2.3 还原引擎 (Restore Engine)

#### 2.3.1 还原流程

```
用户执行 restore 命令
        │
        ▼
┌─────────────────┐
│  校验 Pack 文件  │ ─── 检查完整性、版本兼容性
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  解析 Manifest   │ ─── 读取清单，确定还原内容
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  平台兼容检查    │ ─── 确认目标平台与源平台匹配
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  冲突检测       │ ─── 检测与现有环境的冲突
└────────┬────────┘
         │
         ▼
┌─────────────────────┐
│  创建还原点（可选）  │ ─── 备份当前环境用于回滚
└────────┬────────────┘
         │
         ▼
┌─────────────────┐
│  依赖排序       │ ─── 按依赖关系排序安装顺序
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────┐
│  执行还原       │ ──▶ │ 逐项安装/配置 │
└────────┬────────┘     └──────────────┘
         │
         ▼
┌─────────────────┐
│  验证还原结果    │ ─── 运行各采集器的验证逻辑
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  生成还原报告    │ ─── 成功/失败/跳过的项目清单
└─────────────────┘
```

#### 2.3.2 冲突处理策略

```go
// ConflictStrategy 冲突处理策略
type ConflictStrategy int

const (
    ConflictSkip      ConflictStrategy = iota // 跳过（保留现有）
    ConflictOverwrite                          // 覆盖（使用 Pack 中的）
    ConflictMerge                              // 合并
    ConflictPrompt                             // 询问用户
    ConflictNewest                             // 使用较新版本
)

// ConflictItem 冲突项
type ConflictItem struct {
    Collector    string
    ItemName     string
    CurrentVer   string
    PackVer      string
    Type         ConflictType // VersionMismatch, AlreadyExists, DependencyConflict
}
```

### 2.4 配置文件管理 (Profile Manager)

#### 2.4.1 Profile 格式

使用 YAML 格式定义 Profile：

```yaml
# ~/.devpack/profiles/golang-dev.yaml
name: golang-dev
description: "Go 全栈开发环境"
version: "1.0"

# 采集器配置
collectors:
  runtime:
    enabled: true
    include:
      - go
      - node
    exclude: []
    options:
      go:
        capture_gopath_bin: true    # 捕获 GOPATH/bin 下的工具
        capture_go_env: true        # 捕获 go env 配置

  editor:
    enabled: true
    include:
      - vscode
    options:
      vscode:
        capture_extensions: true
        capture_settings: true
        capture_keybindings: true
        capture_snippets: true
        # 排除的扩展
        exclude_extensions:
          - "ms-vsliveshare.vsliveshare"

  shell:
    enabled: true
    include:
      - powershell
      - bash

  package:
    enabled: true
    include:
      - scoop

  git:
    enabled: true
    options:
      capture_aliases: true
      capture_hooks: false

  env:
    enabled: true
    options:
      # 只捕获匹配的环境变量
      include_patterns:
        - "GOPATH"
        - "GOROOT"
        - "PATH"
        - "NODE_*"
      exclude_patterns:
        - "*_KEY"
        - "*_SECRET"
        - "*_TOKEN"

  ssh:
    enabled: false

# 还原选项
restore:
  conflict_strategy: prompt    # skip, overwrite, merge, prompt, newest
  create_restore_point: true
  dry_run_first: false
```

### 2.5 平台适配层 (Platform Abstraction Layer)

```go
// Platform 平台适配接口
type Platform interface {
    // OS 返回操作系统标识
    OS() string

    // Arch 返回架构标识
    Arch() string

    // HomeDir 返回用户主目录
    HomeDir() string

    // ConfigDir 返回配置文件目录
    ConfigDir() string

    // DataDir 返回数据目录
    DataDir() string

    // GetEnvVar 获取环境变量
    GetEnvVar(key string) string

    // SetEnvVar 设置用户级环境变量
    SetEnvVar(key, value string) error

    // AddToPath 添加目录到 PATH
    AddToPath(dir string) error

    // IsAdmin 是否以管理员身份运行
    IsAdmin() bool

    // PackageManagers 返回可用的包管理器
    PackageManagers() []string

    // DefaultShell 返回默认 Shell
    DefaultShell() string

    // InstallFont 安装字体文件
    InstallFont(fontPath string) error

    // RunAsAdmin 以管理员权限运行命令
    RunAsAdmin(cmd string, args ...string) error
}
```

各平台实现：

```go
// Windows 平台实现
type WindowsPlatform struct{}

func (p *WindowsPlatform) OS() string        { return "windows" }
func (p *WindowsPlatform) HomeDir() string   { return os.Getenv("USERPROFILE") }
func (p *WindowsPlatform) ConfigDir() string { return os.Getenv("APPDATA") }
func (p *WindowsPlatform) DefaultShell() string { return "powershell" }
func (p *WindowsPlatform) PackageManagers() []string {
    var pms []string
    if _, err := exec.LookPath("scoop"); err == nil { pms = append(pms, "scoop") }
    if _, err := exec.LookPath("choco"); err == nil { pms = append(pms, "chocolatey") }
    if _, err := exec.LookPath("winget"); err == nil { pms = append(pms, "winget") }
    return pms
}

// macOS 平台实现
type DarwinPlatform struct{}

// Linux 平台实现
type LinuxPlatform struct{}
```

### 2.6 加密模块 (Crypto Module)

```go
// Encryptor 加密器接口
type Encryptor interface {
    // Encrypt 使用密码加密数据
    Encrypt(data []byte, password string) ([]byte, error)

    // Decrypt 使用密码解密数据
    Decrypt(encrypted []byte, password string) ([]byte, error)
}

// AESGCMEncryptor AES-256-GCM 加密实现
type AESGCMEncryptor struct{}

// 密钥派生使用 Argon2id
func deriveKey(password string, salt []byte) []byte {
    return argon2.IDKey([]byte(password), salt, 1, 64*1024, 4, 32)
}
```

---

## 3. 数据流

### 3.1 扫描 → 打包数据流

```
┌────────────┐     ┌────────────┐     ┌────────────┐     ┌──────────┐
│  用户系统   │ ──▶ │  Collectors │ ──▶ │  ScanResult │ ──▶ │ 临时目录  │
│  (实际环境) │     │  (扫描采集) │     │  (结构化数据)│     │ (文件数据)│
└────────────┘     └────────────┘     └────────────┘     └────┬─────┘
                                                              │
                   ┌────────────┐     ┌────────────┐          │
                   │  .devpack  │ ◀── │  Pack 引擎  │ ◀────────┘
                   │  (归档文件) │     │  (压缩打包) │
                   └────────────┘     └────────────┘
```

### 3.2 导入 → 还原数据流

```
┌────────────┐     ┌────────────┐     ┌────────────┐     ┌──────────┐
│  .devpack  │ ──▶ │  解压校验   │ ──▶ │  Manifest   │ ──▶ │ 还原计划  │
│  (归档文件) │     │            │     │  解析       │     │ 生成     │
└────────────┘     └────────────┘     └────────────┘     └────┬─────┘
                                                              │
                   ┌────────────┐     ┌────────────┐          │
                   │  目标系统   │ ◀── │  Restore   │ ◀────────┘
                   │  (已还原)   │     │  Engine    │
                   └────────────┘     └────────────┘
```

---

## 4. 技术选型

### 4.1 核心依赖

| 依赖 | 用途 | 选型理由 |
|------|------|---------|
| [cobra](https://github.com/spf13/cobra) | CLI 框架 | Go 生态最流行的 CLI 框架 |
| [viper](https://github.com/spf13/viper) | 配置管理 | 支持多种配置格式 |
| [zerolog](https://github.com/rs/zerolog) | 日志 | 高性能结构化日志 |
| [color](https://github.com/fatih/color) | 终端着色 | 美化 CLI 输出 |
| [progressbar](https://github.com/schollz/progressbar) | 进度条 | 长时操作反馈 |
| [survey](https://github.com/AlecAivazis/survey) | 交互式提示 | 用户交互 |
| [archiver](https://github.com/mholt/archiver) | 压缩归档 | 支持多种归档格式 |
| [go-yaml](https://github.com/go-yaml/yaml) | YAML 解析 | Profile 文件解析 |
| [uuid](https://github.com/google/uuid) | UUID 生成 | Pack ID 生成 |
| [golang.org/x/crypto](https://golang.org/x/crypto) | 加密库 | Argon2, AES |

### 4.2 构建工具

| 工具 | 用途 |
|------|------|
| Go 1.22+ | 编程语言 |
| Make / Task | 构建脚本 |
| GoReleaser | 多平台发布 |
| golangci-lint | 代码检查 |
| GitHub Actions | CI/CD |

---

## 5. 错误处理策略

### 5.1 错误分级

```go
// ErrorLevel 错误级别
type ErrorLevel int

const (
    ErrorFatal    ErrorLevel = iota  // 致命错误，必须终止
    ErrorCritical                     // 严重错误，当前采集器失败
    ErrorWarning                      // 警告，可继续但需告知用户
    ErrorInfo                         // 信息，记录但不影响流程
)

// CollectorError 采集器错误
type CollectorError struct {
    Collector string
    Level     ErrorLevel
    Message   string
    Cause     error
    Hint      string   // 给用户的建议
}
```

### 5.2 错误处理原则

1. **采集阶段** — 单个采集器失败不影响其他采集器
2. **打包阶段** — 失败的采集器数据不包含在 Pack 中，但 Pack 仍然生成
3. **还原阶段** — 根据策略决定是继续还是终止
4. **所有操作** — 详细日志记录，用户友好的错误信息

---

## 6. 安全设计

### 6.1 敏感数据识别

| 数据类型 | 敏感级别 | 处理方式 |
|---------|---------|---------|
| SSH 私钥 | 高 | AES-256 加密 |
| GPG 私钥 | 高 | AES-256 加密 |
| API Token | 高 | AES-256 加密或排除 |
| 环境变量中的密码 | 高 | 默认排除 |
| Git 凭证 | 高 | 默认排除 |
| IDE 设置 | 低 | 明文存储 |
| Shell 配置 | 中 | 扫描并警告内嵌 Token |

### 6.2 加密流程

```
用户密码 ──▶ Argon2id ──▶ 派生密钥 (256-bit)
                              │
                              ▼
敏感数据 ──▶ AES-256-GCM 加密 ──▶ 加密数据 + Nonce + Salt
                                         │
                                         ▼
                                  存入 encrypted/ 目录
```

---

## 7. 可扩展性设计

### 7.1 插件系统（远期规划）

未来计划支持外部插件：

```go
// Plugin 外部插件接口
type Plugin interface {
    Collector

    // PluginInfo 返回插件元信息
    PluginInfo() PluginMeta
}

type PluginMeta struct {
    Name        string `json:"name"`
    Version     string `json:"version"`
    Author      string `json:"author"`
    MinDevPack  string `json:"min_devpack_version"`
}
```

插件发现机制：
1. `~/.devpack/plugins/` 目录下的可执行文件
2. 通过 Go Plugin 机制加载 `.so` / `.dll`
3. 通过 gRPC/JSON-RPC 与外部进程通信（推荐，跨语言）

---

## 8. 测试策略

### 8.1 测试层级

| 层级 | 范围 | 工具 |
|------|------|------|
| 单元测试 | 各模块独立逻辑 | Go testing + testify |
| 集成测试 | 模块间协作 | Go testing |
| 端到端测试 | 完整的 capture → restore 流程 | 脚本 + Docker/VM |
| 平台测试 | 各操作系统适配 | GitHub Actions Matrix |

### 8.2 测试环境

- CI 环境使用 GitHub Actions 矩阵构建（Windows/macOS/Linux）
- 端到端测试使用虚拟机或容器模拟真实环境
- Mock 框架用于隔离外部依赖（如包管理器）