899 lines
25 KiB
Markdown
899 lines
25 KiB
Markdown
# 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 代理 | - |
|