# DevPack API 设计文档

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

---

## 1. CLI 命令参考

### 1.1 命令总览

```
devpack [command] [subcommand] [flags]

Available Commands:
  init        初始化 DevPack 配置
  scan        扫描当前开发环境
  capture     捕获环境并生成 Pack
  restore     从 Pack 还原开发环境
  diff        对比两个环境的差异
  export      导出 Pack 为文件
  import      导入 Pack 文件
  list        列出 Pack 和 Profile
  profile     管理配置文件
  verify      验证 Pack 文件完整性
  version     显示版本信息
  help        帮助信息

Global Flags:
  -v, --verbose         详细输出
  -q, --quiet           静默模式
      --log-level       日志级别 (trace|debug|info|warn|error)
      --log-file        日志文件路径
      --no-color        禁用彩色输出
      --config          配置文件路径（默认 ~/.devpack/config.yaml）
  -h, --help            帮助信息
```

---

### 1.2 devpack init

初始化 DevPack，创建配置目录和默认配置文件。

```
devpack init [flags]

Flags:
      --profile <name>    创建并使用指定名称的 Profile
      --template <tpl>    使用预设模板 (minimal|standard|full)
      --force             覆盖已有配置
```

**示例：**
```bash
# 默认初始化
devpack init

# 使用模板初始化
devpack init --template standard

# 创建指定 Profile
devpack init --profile golang-dev
```

**行为：**
1. 创建 `~/.devpack/` 目录
2. 生成 `~/.devpack/config.yaml` 默认配置
3. 创建 `~/.devpack/profiles/` 目录
4. 创建 `~/.devpack/packs/` 目录
5. 创建 `~/.devpack/logs/` 目录

**输出示例：**
```
✓ Created ~/.devpack/config.yaml
✓ Created ~/.devpack/profiles/default.yaml
✓ DevPack initialized successfully!

Run 'devpack scan' to scan your current environment.
```

---

### 1.3 devpack scan

扫描当前系统的开发环境。

```
devpack scan [flags]

Flags:
  -c, --collectors <list>   指定采集器（逗号分隔）
      --category <cat>      按分类扫描 (runtime|package|editor|shell|git|env)
      --profile <name>      使用指定 Profile 的扫描配置
  -o, --output <format>     输出格式 (table|json|yaml) [默认: table]
      --save <path>         保存扫描结果到文件
      --detailed            显示详细信息
```

**示例：**
```bash
# 扫描所有
devpack scan

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

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

# JSON 格式输出
devpack scan -o json

# 保存结果
devpack scan --save scan-result.json
```

**输出示例：**
```
🔍 Scanning development environment...

╔══════════════╤════════════════════╤═══════════╤═══════════════════╗
║ Category     │ Name               │ Version   │ Details           ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Runtime      │ Go                 │ 1.22.1    │ GOPATH: ~/go      ║
║ Runtime      │ Node.js            │ 20.11.0   │ npm: 10.2.4       ║
║ Runtime      │ Python             │ 3.12.2    │ pip: 24.0         ║
║ Runtime      │ Rust               │ 1.76.0    │ rustup: 1.27.0    ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Package Mgr  │ Scoop              │ -         │ 42 packages       ║
║ Package Mgr  │ Winget             │ -         │ 15 packages       ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Editor       │ VS Code            │ 1.87.0    │ 35 extensions     ║
║ Editor       │ Neovim             │ 0.9.5     │ 18 plugins        ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Shell        │ PowerShell         │ 7.4.1     │ 5 modules         ║
║ Shell        │ Windows Terminal   │ 1.19      │ 3 profiles        ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Git          │ Git                │ 2.43.0    │ 12 aliases        ║
╠══════════════╪════════════════════╪═══════════╪═══════════════════╣
║ Environment  │ Environment Vars   │ -         │ 8 dev-related     ║
╚══════════════╧════════════════════╧═══════════╧═══════════════════╝

Found 12 items across 6 categories.
Estimated pack size: ~12 MB
```

---

### 1.4 devpack capture

捕获当前环境并创建 Pack。

```
devpack capture [flags]

Flags:
  -n, --name <name>         Pack 名称（必需）
  -d, --description <desc>  Pack 描述
  -p, --profile <name>      使用指定 Profile
  -c, --collectors <list>   指定采集器（逗号分隔）
      --filter <expr>       过滤表达式
      --all                 捕获所有可用采集器
      --encrypt             加密敏感数据
      --password <pwd>      加密密码（不建议命令行传入）
      --exclude <patterns>  排除模式（逗号分隔）
      --tag <tags>          标签（逗号分隔）
  -y, --yes                 跳过确认提示
```

**示例：**
```bash
# 使用默认 Profile 捕获
devpack capture --name "my-env-2026"

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

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

# 选择性捕获
devpack capture --name "vscode-only" -c vscode

# 加密捕获
devpack capture --name "secure-env" --all --encrypt

# 带过滤器
devpack capture --name "web-dev" \
  -c go,node,vscode \
  --filter "runtime:go,runtime:node,editor:vscode"
```

**输出示例：**
```
📦 Capturing environment "my-env-2026"...

Collecting:
  ✓ Go Runtime           (1.22.1, 3 tools)           [2.1 MB]
  ✓ Node.js Runtime      (20.11.0, 12 global pkgs)   [1.5 MB]
  ✓ VS Code              (35 extensions, settings)    [4.2 MB]
  ✓ PowerShell           (profile, 5 modules)         [0.3 MB]
  ✓ Scoop                (42 packages)                [0.1 MB]
  ✓ Git                  (config, 12 aliases)         [0.01 MB]
  ✓ Environment Variables (8 variables)               [0.001 MB]
  ⚠ SSH Keys             skipped (use --encrypt)

Pack created: my-env-2026
  Items:  7 collectors, 115 items
  Size:   8.2 MB (compressed)
  Pack ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Run 'devpack export my-env-2026 -o my-env-2026.devpack' to export.
```

---

### 1.5 devpack restore

从 Pack 还原开发环境。

```
devpack restore <pack-name> [flags]

Flags:
      --dry-run             预览更改（不实际执行）
      --conflict <strategy> 冲突处理策略 (skip|overwrite|merge|prompt|newest)
      --no-rollback         不创建还原点
  -c, --collectors <list>   只还原指定采集器
      --exclude <list>      排除指定采集器
      --password <pwd>      解密密码
      --parallel <n>        并行还原数（默认: 4）
  -y, --yes                 跳过确认提示
      --force               强制还原（忽略平台不匹配）
```

**示例：**
```bash
# 干运行预览
devpack restore my-env-2026 --dry-run

# 正常还原
devpack restore my-env-2026

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

# 只还原编辑器配置
devpack restore my-env-2026 -c vscode

# 还原加密 Pack
devpack restore secure-env --password
```

**干运行输出示例：**
```
🔍 Dry Run — Restore Plan for "my-env-2026"

Source: DESKTOP-ABC123 (Windows 11, amd64)
Target: LAPTOP-XYZ789  (Windows 11, amd64) ✓ Compatible

Plan:
  ┌────────────────────┬────────────┬──────────────────────────────┐
  │ Item               │ Action     │ Details                      │
  ├────────────────────┼────────────┼──────────────────────────────┤
  │ Go 1.22.1          │ INSTALL    │ Download from golang.org     │
  │ Node.js 20.11.0    │ SKIP       │ Already installed (20.11.0)  │
  │ Python 3.12.2      │ UPGRADE    │ Current: 3.11.7 → 3.12.2    │
  │ VS Code Extensions │ INSTALL 12 │ 23 already present           │
  │ VS Code Settings   │ MERGE      │ Conflict in 3 settings       │
  │ PowerShell Profile │ OVERWRITE  │ Backup: profile.bak          │
  │ Scoop Packages     │ INSTALL 8  │ 34 already present           │
  │ Git Config         │ MERGE      │ Add 5 aliases                │
  │ Env Variables      │ SET 3      │ GOPATH, GOROOT, NODE_HOME    │
  └────────────────────┴────────────┴──────────────────────────────┘

  Install: 3 items | Upgrade: 1 | Merge: 2 | Skip: 1 | Overwrite: 1

⚠ This is a dry run. No changes were made.
Run without --dry-run to apply these changes.
```

---

### 1.6 devpack diff

对比两个环境的差异。

```
devpack diff <pack-name> [flags]

Flags:
      --current            与当前环境对比
      --with <pack-name>   与另一个 Pack 对比
  -c, --collectors <list>  只对比指定采集器
  -o, --output <format>    输出格式 (table|json|yaml)
```

**示例：**
```bash
# 与当前环境对比
devpack diff my-env-2026 --current

# 两个 Pack 对比
devpack diff env-v1 --with env-v2
```

---

### 1.7 devpack export / import

导出和导入 Pack 文件。

```
# 导出
devpack export <pack-name> [flags]

Flags:
  -o, --output <path>   输出文件路径（默认: <pack-name>.devpack）

# 导入
devpack import <file-path> [flags]

Flags:
  -n, --name <name>     导入后的名称（默认使用 Pack 原名）
      --verify          导入前验证文件完整性
```

---

### 1.8 devpack list

列出本地的 Pack 和 Profile。

```
devpack list [subcommand] [flags]

Subcommands:
  packs       列出所有 Pack
  profiles    列出所有 Profile
  collectors  列出所有可用采集器

Flags:
  -o, --output <format>   输出格式 (table|json|yaml)
      --detailed          显示详细信息
```

---

### 1.9 devpack profile

管理 Profile 配置文件。

```
devpack profile [subcommand] [flags]

Subcommands:
  create <name>     创建新 Profile
  edit <name>       编辑 Profile
  delete <name>     删除 Profile
  show <name>       显示 Profile 内容
  list              列出所有 Profile
  use <name>        设置默认 Profile
```

---

### 1.10 devpack verify

验证 Pack 文件的完整性。

```
devpack verify <pack-name-or-file> [flags]

Flags:
      --checksum    验证校验和
      --structure   验证目录结构
      --deep        深度验证（检查所有采集器数据）
```

---

## 2. 内部 API

### 2.1 Collector 接口

```go
package collector

import (
    "context"
    "time"
)

// Collector 所有采集器的统一接口
type Collector interface {
    // 基本信息
    Name() string
    DisplayName() string
    Description() string
    Category() Category

    // 可用性检查
    IsAvailable(ctx context.Context) bool

    // 核心操作
    Scan(ctx context.Context, opts ScanOptions) (*ScanResult, error)
    Capture(ctx context.Context, targetDir string, opts CaptureOptions) error
    Restore(ctx context.Context, sourceDir string, opts RestoreOptions) error
    Verify(ctx context.Context) (*VerifyResult, error)
}

// ScanOptions 扫描选项
type ScanOptions struct {
    Detailed bool              // 是否返回详细信息
    Filters  map[string]string // 过滤条件
    Timeout  time.Duration     // 超时时间
}

// CaptureOptions 捕获选项
type CaptureOptions struct {
    IncludePatterns []string // 包含模式
    ExcludePatterns []string // 排除模式
    Encrypt         bool     // 是否加密
}

// RestoreOptions 还原选项
type RestoreOptions struct {
    ConflictStrategy ConflictStrategy // 冲突策略
    DryRun           bool             // 干运行
    Force            bool             // 强制
}

// 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"`
    Errors    []string     `json:"errors,omitempty"`
}

// ScanItem 扫描项
type ScanItem struct {
    Name       string            `json:"name"`
    Version    string            `json:"version,omitempty"`
    Path       string            `json:"path,omitempty"`
    Type       string            `json:"type,omitempty"`     // binary, config, package
    Properties map[string]string `json:"properties,omitempty"`
    Size       int64             `json:"size,omitempty"`
    Sensitive  bool              `json:"sensitive,omitempty"` // 是否包含敏感数据
    Children   []ScanItem        `json:"children,omitempty"`
}

// VerifyResult 验证结果
type VerifyResult struct {
    Success bool           `json:"success"`
    Items   []VerifyItem   `json:"items"`
}

type VerifyItem struct {
    Name    string `json:"name"`
    Status  string `json:"status"` // ok, missing, version_mismatch, error
    Message string `json:"message,omitempty"`
}
```

### 2.2 Pack Engine API

```go
package pack

import (
    "context"
    "io"

    "github.com/user/devpack/pkg/manifest"
)

// Packer 打包器
type Packer struct {
    // ...
}

// NewPacker 创建打包器
func NewPacker(opts PackerOptions) *Packer

// PackerOptions 打包器选项
type PackerOptions struct {
    Name        string
    Description string
    Author      string
    Compression CompressionType // gzip, zstd, none
    Encryption  bool
    Password    string
}

// Pack 执行打包
func (p *Packer) Pack(ctx context.Context, sourceDir string, output io.Writer) (*manifest.Manifest, error)

// Unpacker 解包器
type Unpacker struct {
    // ...
}

// NewUnpacker 创建解包器
func NewUnpacker() *Unpacker

// Unpack 执行解包
func (u *Unpacker) Unpack(ctx context.Context, input io.Reader, targetDir string) (*manifest.Manifest, error)

// Verify 验证 Pack 文件
func (u *Unpacker) Verify(ctx context.Context, input io.Reader) (*VerifyResult, error)
```

### 2.3 Restore Engine API

```go
package restore

import (
    "context"

    "github.com/user/devpack/internal/collector"
    "github.com/user/devpack/pkg/manifest"
)

// Engine 还原引擎
type Engine struct {
    registry *collector.Registry
    platform platform.Platform
    // ...
}

// NewEngine 创建还原引擎
func NewEngine(registry *collector.Registry, platform platform.Platform) *Engine

// Plan 生成还原计划
func (e *Engine) Plan(ctx context.Context, m *manifest.Manifest, opts PlanOptions) (*RestorePlan, error)

// Execute 执行还原计划
func (e *Engine) Execute(ctx context.Context, plan *RestorePlan) (*RestoreReport, error)

// Rollback 回滚还原
func (e *Engine) Rollback(ctx context.Context, restorePointID string) error

// RestorePlan 还原计划
type RestorePlan struct {
    PackName   string           `json:"pack_name"`
    Items      []RestorePlanItem `json:"items"`
    Conflicts  []ConflictItem   `json:"conflicts"`
    TotalSteps int              `json:"total_steps"`
}

// RestorePlanItem 还原计划项
type RestorePlanItem struct {
    Collector  string       `json:"collector"`
    ItemName   string       `json:"item_name"`
    Action     RestoreAction `json:"action"` // install, upgrade, merge, skip, overwrite
    Current    string       `json:"current,omitempty"`
    Target     string       `json:"target"`
    Details    string       `json:"details,omitempty"`
    Order      int          `json:"order"` // 执行顺序
}

// RestoreAction 还原动作
type RestoreAction string

const (
    ActionInstall   RestoreAction = "install"
    ActionUpgrade   RestoreAction = "upgrade"
    ActionMerge     RestoreAction = "merge"
    ActionSkip      RestoreAction = "skip"
    ActionOverwrite RestoreAction = "overwrite"
)

// RestoreReport 还原报告
type RestoreReport struct {
    Success    int            `json:"success"`
    Failed     int            `json:"failed"`
    Skipped    int            `json:"skipped"`
    Items      []ReportItem   `json:"items"`
    Duration   time.Duration  `json:"duration"`
    RestorePointID string     `json:"restore_point_id,omitempty"`
}
```

---

## 3. Pack 文件格式规范

### 3.1 文件结构

```
<name>.devpack                      # tar.gz 归档
│
├── manifest.json                   # Pack 清单（必需）
├── checksum.sha256                 # 校验和文件（必需）
│
├── collectors/                     # 采集器数据目录
│   ├── <category>/                 # 分类目录
│   │   └── <collector-name>/       # 采集器目录
│   │       ├── metadata.json       # 采集器元数据
│   │       └── data/               # 采集器数据
│   │           └── ...             # 具体数据文件
│   └── ...
│
└── encrypted/                      # 加密数据目录（可选）
    └── <collector-name>/
        └── data.enc                # 加密数据
```

### 3.2 manifest.json 完整规范

```json
{
  "version": "0.1.0",
  "format_ver": "1",
  "pack_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-dev-env",
  "description": "My full development environment",
  "author": "developer@example.com",
  "created_at": "2026-03-03T10:30:00Z",
  "tags": ["golang", "fullstack"],

  "source": {
    "hostname": "DESKTOP-ABC123",
    "os": "windows",
    "os_version": "10.0.22631",
    "arch": "amd64",
    "username": "developer",
    "devpack_version": "0.1.0"
  },

  "collectors": [
    {
      "name": "go",
      "category": "runtime",
      "display_name": "Go Runtime",
      "item_count": 4,
      "data_path": "collectors/runtime/go",
      "data_size": 2148576,
      "checksum": "sha256:abc123..."
    },
    {
      "name": "vscode",
      "category": "editor",
      "display_name": "Visual Studio Code",
      "item_count": 36,
      "data_path": "collectors/editor/vscode",
      "data_size": 4412928,
      "checksum": "sha256:def456..."
    }
  ],

  "encryption": {
    "algorithm": "AES-256-GCM",
    "kdf": "argon2id",
    "kdf_params": {
      "time": 1,
      "memory": 65536,
      "threads": 4
    },
    "encrypted_collectors": ["ssh"]
  },

  "checksum": "sha256:789abc..."
}
```

### 3.3 metadata.json 规范

每个采集器目录下的元数据文件：

```json
{
  "collector": "go",
  "category": "runtime",
  "captured_at": "2026-03-03T10:30:00Z",
  "platform": {
    "os": "windows",
    "arch": "amd64"
  },
  "items": [
    {
      "name": "go",
      "version": "1.22.1",
      "type": "binary",
      "install_method": "direct",
      "install_url": "https://go.dev/dl/go1.22.1.windows-amd64.msi",
      "properties": {
        "GOPATH": "C:\\Users\\dev\\go",
        "GOROOT": "C:\\Program Files\\Go",
        "GOPROXY": "https://goproxy.cn,direct"
      }
    },
    {
      "name": "gopls",
      "version": "0.15.1",
      "type": "tool",
      "install_method": "go_install",
      "install_command": "go install golang.org/x/tools/gopls@v0.15.1"
    },
    {
      "name": "golangci-lint",
      "version": "1.56.2",
      "type": "tool",
      "install_method": "go_install",
      "install_command": "go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.56.2"
    }
  ],
  "files": [
    {
      "source": "data/go-env.json",
      "description": "Go environment variables"
    }
  ]
}
```

---

## 4. 配置文件规范

### 4.1 全局配置 (~/.devpack/config.yaml)

```yaml
# DevPack 全局配置
version: "1"

# 存储设置
storage:
  packs_dir: "~/.devpack/packs"       # Pack 存储目录
  profiles_dir: "~/.devpack/profiles" # Profile 目录
  logs_dir: "~/.devpack/logs"         # 日志目录
  temp_dir: ""                        # 临时目录（空则使用系统默认）

# 默认行为
defaults:
  profile: "default"                   # 默认 Profile
  compression: "gzip"                  # 压缩方式 (gzip|zstd|none)
  conflict_strategy: "prompt"          # 冲突策略
  create_restore_point: true           # 还原前创建还原点
  parallel_restore: 4                  # 并行还原数

# 日志设置
logging:
  level: "info"                        # 日志级别
  format: "text"                       # 日志格式 (text|json)
  file: "~/.devpack/logs/devpack.log"  # 日志文件

# 网络设置（用于下载安装器）
network:
  timeout: 300                         # 下载超时（秒）
  proxy: ""                            # HTTP 代理
  retries: 3                           # 重试次数

# UI 设置
ui:
  color: true                          # 彩色输出
  progress_bar: true                   # 进度条
  interactive: true                    # 交互式提示

# 安全设置
security:
  default_encrypt: false               # 默认是否加密
  scan_for_secrets: true               # 扫描敏感数据并警告
  exclude_patterns:                    # 全局排除模式
    - "*_KEY"
    - "*_SECRET"
    - "*_TOKEN"
    - "*_PASSWORD"
```

### 4.2 Profile 配置文件规范

```yaml
# Profile 配置文件
name: "default"
description: "Default development environment profile"
version: "1"

collectors:
  # 运行时采集器配置
  runtime:
    enabled: true
    include: []          # 空列表 = 全部，非空 = 只包含列出的
    exclude: []          # 排除列表
    options: {}          # 采集器特定选项

  # 包管理器采集器配置
  package:
    enabled: true
    include: []
    exclude: []
    options:
      scoop:
        include_buckets: true
        exclude_packages: []
      chocolatey:
        exclude_packages: []

  # 编辑器采集器配置
  editor:
    enabled: true
    include: ["vscode"]
    options:
      vscode:
        capture_extensions: true
        capture_settings: true
        capture_keybindings: true
        capture_snippets: true
        exclude_extensions: []

  # Shell 采集器配置
  shell:
    enabled: true
    include: []
    options: {}

  # Git 采集器配置
  git:
    enabled: true
    options:
      capture_config: true
      capture_aliases: true
      capture_hooks: false

  # 环境变量采集器配置
  env:
    enabled: true
    options:
      include_patterns: []
      exclude_patterns:
        - "*_KEY"
        - "*_SECRET"

  # SSH/GPG 采集器配置
  ssh:
    enabled: false        # 默认禁用
    options:
      encrypt: true       # 必须加密

  # 字体采集器配置
  font:
    enabled: false
    options:
      include_fonts: []   # 空 = 自动检测开发字体

# 还原选项
restore:
  conflict_strategy: "prompt"
  create_restore_point: true
  dry_run_first: false
  
# 自定义钩子（高级）
hooks:
  pre_capture: ""         # 捕获前执行的命令
  post_capture: ""        # 捕获后执行的命令
  pre_restore: ""         # 还原前执行的命令
  post_restore: ""        # 还原后执行的命令
```

---

## 5. 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 一般性错误 |
| 2 | 命令行参数错误 |
| 3 | 配置错误 |
| 10 | Pack 文件损坏或无效 |
| 11 | 平台不兼容 |
| 12 | 版本不兼容 |
| 20 | 还原失败 |
| 21 | 还原部分成功 |
| 22 | 冲突（需要用户介入） |
| 30 | 权限不足 |
| 40 | 网络错误 |
| 50 | 加密/解密错误 |

---

## 6. 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DEVPACK_HOME` | DevPack 主目录 | `~/.devpack` |
| `DEVPACK_LOG_LEVEL` | 日志级别 | `info` |
| `DEVPACK_LOG_FILE` | 日志文件路径 | `~/.devpack/logs/devpack.log` |
| `DEVPACK_CONFIG` | 配置文件路径 | `~/.devpack/config.yaml` |
| `DEVPACK_NO_COLOR` | 禁用彩色输出 | `false` |
| `DEVPACK_PROFILE` | 默认 Profile | `default` |
| `DEVPACK_HTTP_PROXY` | HTTP 代理 | - |