URPF CLI 工具

基于 URPF (Universal Resource Package Format) v1.0 规范的命令行打包工具

项目链接

• 首页: https://gitcode.com/tq1086/urpf
• 仓库: [email protected]:tq1086/urpf.git
• 问题反馈: https://gitcode.com/tq1086/urpf/issues

功能特性

• 将文件或目录打包为 URPF 格式
• 从 URPF 文件中解包资源到文件系统
• 向已有 URPF 包添加文件或目录
• 从 URPF 包中移除文件（支持变量替换和通配符）
• 支持 .gitignore 风格的忽略规则
• 自动检测文件编码和换行符类型
• 保留文件权限和元数据
• 跨平台支持（Windows、Linux、macOS）
• 按字节偏移量切片文件（从0开始）
• 按行号切片文件（从1开始）
• 输出 URPF 内容到屏幕
• 复制 URPF 内容到剪贴板
• 打包环境变量到 URPF 属性
• 变量管理和环境变量管理
• 配置文件合并 - 支持多个配置文件合并，支持 overwrite/skip/rename 三种冲突处理策略
• Key 提取历史记录 - 记录、查看、重用历史 key 提取操作
• 远程配置文件支持 - 支持 HTTP/HTTPS，支持 Basic Auth/Bearer Token 认证
• 配置差异对比 - 对比配置文件差异，识别 SAME/CHANGED/ADDED/REMOVED 类型
• 冲突检测与管理 - 检测、封装和解决 URPF 包之间的冲突，支持交互式和策略式解决
• Pentagon 工作流支持 - 下载并解压 Pentagon URPF 包

安装

# 全局安装
npm install -g @tq1086/urpf

# 本地安装
npm install @tq1086/urpf

使用方法

基本用法

Pentagon 工作流命令 (ptg)

ptg download 子命令 - 下载并解压 Pentagon URPF 包：

# 基本用法：下载并解压到当前目录
ptg download

# 指定输出目录
ptg download -o ./pentagon

# 启用验证和详细日�?ptg download --verify -v

# 查看帮助
ptg download --help

ptg download 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | -o, --output | -o | string | 当前目录 | 输出目录路径 | | --verify | - | boolean | false | 验证下载文件的完整�?| | -v, --verbose | -v | boolean | false | 显示详细日志 |

*ptg inspect 子命�? - 检�?Pentagon 工作流状态：

# 基本用法：打包核心文件到剪贴�?ptg inspect

# 同时输出到文�?ptg inspect -o pentagon-state.urpf.txt

# 显示详细日志
ptg inspect -v

ptg inspect 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | -v, --verbose | -v | boolean | false | 显示详细日志 | | -o, --output | -o | string | undefined | 同时输出到文件（可选） |

打包命令 (pack)

URPF CLI 提供了子命令结构，支持灵活的包管理操作�? **创建新的 URPF �?(pack create)**�?

# 基本用法
urpf pack create package.json                          # 打包单个文件
urpf pack create src/                                  # 打包整个目录
urpf pack create file1.txt file2.txt file3.txt         # 打包多个文件

# 输出控制
urpf pack create config.json -o output.urpf.txt        # 指定输出路径
urpf pack create config.json --stdout                  # 输出到屏幕（不写入文件）
urpf pack create config.json --clipboard               # 复制到剪贴板（不写入文件�?urpf pack create config.json --stdout --clipboard      # 同时输出到屏幕和剪贴�?
# 文件切片
urpf pack create file.txt --byte 100:200               # 按字节切片（�?开始）
urpf pack create file.txt --byte 100                   # 从字�?00到文件末�?urpf pack create file.txt --byte :200                  # 从文件开头到字节200
urpf pack create file.txt --line 10:20                 # 按行号切片（�?开始）
urpf pack create file.txt --line 10                    # 从第10行到文件末尾
urpf pack create file.txt --line :20                   # 从文件开头到�?0�?
# Key 提取
urpf pack create config.json --key "server.port"       # 提取配置文件中的指定键�?urpf pack create config.json --key "items[0].name"     # 支持数组索引
urpf pack create config.json --key "db.host,db.port"   # 批量提取多个键值（逗号分隔�?
# 环境变量
urpf pack create src/ --env API_KEY                    # 打包单个环境变量
urpf pack create src/ --env "*"                        # 打包全部环境变量
urpf pack create src/ --env API_KEY "my-secret"        # 指定环境变量�?
# 扫描控制
urpf pack create src/ -i .gitignore                    # 指定忽略规则文件
urpf pack create src/ --no-recurse                     # 不递归扫描子目�?urpf pack create src/ -d 3                             # 最大扫描深度为3�?urpf pack create src/ --follow-symlinks                # 跟随符号链接

# 多文件打包（处理冲突�?urpf pack create dir1/ dir2/ --force-first             # 冲突时保留第一个文件的�?urpf pack create dir1/ dir2/ --force-last              # 冲突时保留最后一个文件的�?urpf pack create dir1/ dir2/ --allow-conflict --force-first  # 允许冲突并使用策略处�?
# 其他选项
urpf pack create src/ --force                          # 强制覆盖已存在的输出文件
urpf pack create src/ -v                               # 显示详细日志
urpf pack create config.json --key "server.port" --validate  # 验证模式（仅验证key是否存在�?```

**pack create 参数说明**�?
| 参数 | 简�?| 类型 | 默认�?| 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `<files...>` | - | 必填 | - | 要打包的文件或目录路径（支持多个�?|
| `-o, --output` | -o | string | 第一个输入路�?urpf | 输出文件路径 |
| `-v, --verbose` | -v | boolean | false | 显示详细日志 |
| `-i, --ignore` | -i | string | .gitignore/.urpfignore | 指定忽略规则文件路径 |
| `-f, --follow-symlinks` | -f | boolean | false | 跟随符号链接 |
| `-d, --max-depth` | -d | number | undefined | 最大扫描深度（0表示无限制） |
| `--no-recurse` | - | boolean | false | 不递归扫描子目�?|
| `--force` | - | boolean | false | 强制覆盖已存在的输出文件 |
| `--byte` | - | string | undefined | 按字节切片，格式：start[:end]（从0开始） |
| `--line` | - | string | undefined | 按行号切片，格式：start[:end]（从1开始） |
| `-s, --stdout` | -s | boolean | false | 输出URPF内容到屏幕（不写入文件） |
| `-c, --clipboard` | -c | boolean | false | 复制URPF内容到剪贴板（不写入文件�?|
| `-e, --env` | -e | string | undefined | 打包环境变量（可多次使用�?|
| `--key` | - | string | undefined | 从配置文件提取键值（支持嵌套和数组） |
| `--format` | - | string | json | 输出格式（json/yaml/toml/xml/properties/ini/raw�?|
| `--validate` | - | boolean | false | 验证模式（仅验证key是否存在�?|
| `--force-first` | - | boolean | false | 多文件打包时，冲突保留第一个文件的�?|
| `--force-last` | - | boolean | false | 多文件打包时，冲突保留最后一个文件的�?|
| `--allow-conflict` | - | boolean | false | 允许冲突并使用默认策略处理（需要配�?--force-first �?--force-last�?|

#### Pack 命令输出选项

`pack create` 命令支持多种输出选项，可以灵活控制输出行为：

**输出选项说明**�?
- **`-o, --output <path>`** - 强制输出到指定文件（优先级最高）
- **`-s, --stdout`** - 输出 URPF 内容到屏幕（不写入文件）
- **`-c, --clipboard`** - 复制 URPF 内容到剪贴板（不写入文件�?
**输出选项优先级规�?*�?
1. **使用 `--output` 选项**：强制输出到指定文件，可与其他选项组合使用
2. **使用 `--stdout` 选项**：仅输出到标准输出，不写入文�?3. **使用 `--clipboard` 选项**：仅复制到剪贴板，不写入文件
4. **组合使用 `--stdout` �?`--clipboard`**：同时执行两个操作，不写入文�?5. **无任何输出选项**：默认输出到文件（基于输入路径生成）

**使用示例**�?
```bash
# 示例 1: 输出到标准输出（不写入文件）
urpf pack create config.json --stdout

# 示例 2: 复制到剪贴板（不写入文件�?urpf pack create config.json --clipboard

# 示例 3: 同时输出到屏幕和剪贴板（不写入文件）
urpf pack create config.json --stdout --clipboard

# 示例 4: 强制输出到指定文�?urpf pack create config.json --output custom.urpf.txt

# 示例 5: 输出到文件同时复制到剪贴�?urpf pack create config.json --output my.urpf.txt --clipboard

# 示例 6: 默认输出（无选项�?urpf pack create config.json
# 输出文件: config.urpf.txt

注意事项�?

• --output 选项优先级最高，会始终写入到指定文件
• --stdout �?--clipboard 选项会抑制默认的文件输出
• 同时使用 --stdout �?--clipboard 时，两个操作都会执行
• 无任何输出选项时，默认行为保持不变（输出到基于输入路径生成的文件）

**向已�?URPF 包添加文�?(pack add)**�?

# 基本用法
urpf pack add package.urpf.txt newfile.txt              # 添加单个文件
urpf pack add package.urpf.txt file1.txt file2.txt     # 添加多个文件
urpf pack add package.urpf.txt newdir/                 # 添加整个目录
urpf pack add package.urpf.txt file1.txt dir1/ file2.txt  # 混合添加

# 扫描控制
urpf pack add package.urpf.txt src/ -i .gitignore      # 指定忽略规则文件
urpf pack add package.urpf.txt src/ --no-recurse       # 不递归扫描子目�?urpf pack add package.urpf.txt src/ -d 2               # 最大扫描深度为2�?urpf pack add package.urpf.txt src/ --follow-symlinks  # 跟随符号链接

# 其他选项
urpf pack add package.urpf.txt src/ -v                 # 显示详细日志

pack add 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | <file|dir...> | - | 必填 | - | 要添加的文件或目录路径（支持多个�?| | -v, --verbose | -v | boolean | false | 显示详细日志 | | -i, --ignore | -i | string | .gitignore/.urpfignore | 指定忽略规则文件路径 | | -f, --follow-symlinks | -f | boolean | false | 跟随符号链接 | | -d, --max-depth | -d | number | undefined | 最大扫描深度（0表示无限制） | | --no-recurse | - | boolean | false | 不递归扫描子目�?|

**�?URPF 包移除文�?(pack remove)**�?

# 基本用法
urpf pack remove package.urpf.txt oldfile.txt           # 移除单个文件
urpf pack remove package.urpf.txt file1.txt file2.txt  # 移除多个文件

# 通配符和变量
urpf pack remove package.urpf.txt "*.log"              # 使用通配�?urpf pack remove package.urpf.txt "temp/*"             # 移除temp目录下所有文�?urpf pack remove package.urpf.txt "${ROOT}/config.json" # 使用变量替换

# 其他选项
urpf pack remove package.urpf.txt "*.tmp" -v           # 显示详细日志
urpf pack remove package.urpf.txt "*.log" --no-apply-variables  # 不应用变量替�?```

**pack remove 参数说明**�?
| 参数 | 简�?| 类型 | 默认�?| 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `<file.urpf>` | - | 必填 | - | URPF文件路径 |
| `<filename...>` | - | 必填 | - | 要移除的文件名或模式（支持多个） |
| `-v, --verbose` | -v | boolean | false | 显示详细日志 |
| `--no-apply-variables` | - | boolean | false | 不应用变量替�?|

#### 解包命令 (unpack)

```bash
# 基本用法
urpf unpack package.urpf.txt                           # 解包到当前目�?urpf unpack package.urpf.txt -o ./output               # 解包到指定目�?
# 选择性解�?urpf unpack package.urpf.txt config.json               # 只解压指定文�?urpf unpack package.urpf.txt src/                      # 只解压指定目�?urpf unpack package.urpf.txt config.json src/index.js  # 解压多个文件
urpf unpack package.urpf.txt "*.js"                    # 使用通配�?urpf unpack package.urpf.txt --packed-path "src/*"     # 使用 --packed-path 选项

# 覆盖控制
urpf unpack package.urpf.txt --force                   # 强制覆盖已存在的文件
urpf unpack package.urpf.txt --force-when-newer        # 仅当源文件更新时才覆�?urpf unpack package.urpf.txt --preserve-mtime          # 保留原始修改时间

# 环境变量和变量替�?urpf unpack package.urpf.txt --unpack-env              # 自动确认环境变量设置
urpf unpack package.urpf.txt --apply-variables         # 应用变量替换到文件内�?
# Key 提取
urpf unpack package.urpf.txt --key "config.json:server.port"  # 从配置文件提取键�?urpf unpack package.urpf.txt --key "config.json:db.host,db.port"  # 批量提取
urpf unpack package.urpf.txt --key "data.json:items[0].name"     # 支持数组索引
urpf unpack package.urpf.txt --key "*.json:version"    # 使用通配符提�?
# 其他选项
urpf unpack package.urpf.txt -v                        # 显示详细日志
urpf unpack package.urpf.txt --validate                # 验证模式（仅验证key是否存在�?```

**unpack 参数说明**�?
| 参数 | 简�?| 类型 | 默认�?| 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `<file.urpf>` | - | 必填 | - | 要解包的URPF文件路径 |
| `-o, --output` | -o | string | 当前目录 | 输出目录路径 |
| `-v, --verbose` | -v | boolean | false | 显示详细日志 |
| `--force` | - | boolean | false | 强制覆盖已存在的文件 |
| `--force-when-newer` | - | boolean | false | 仅当源文件更新时才覆�?|
| `--preserve-mtime` | - | boolean | false | 保留原始修改时间 |
| `--unpack-env` | - | boolean | false | 自动确认环境变量设置 |
| `--apply-variables` | - | boolean | false | 应用变量替换到文件内�?|
| `--packed-path` | - | string | undefined | 只解压指定的文件或目录（支持通配符，可多次使用） |
| `--key` | - | string | undefined | 从配置文件提取键值（支持嵌套和数组，可多次使用） |
| `--format` | - | string | json | 输出格式（json/yaml/toml/xml/properties/ini/raw�?|
| `--validate` | - | boolean | false | 验证模式（仅验证key是否存在�?|

#### 列出命令 (list)

```bash
# 基本用法
urpf list package.urpf.txt                            # 列出所有文�?urpf list package.urpf.txt --pattern "*.js"           # 按模式过滤文�?urpf list package.urpf.txt --pattern "src/*"          # 过滤src目录下的文件

# 输出格式
urpf list package.urpf.txt --json                     # 以JSON格式输出
urpf list package.urpf.txt -v                         # 显示详细信息

list 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 | | -p, --pattern | -p | string | undefined | 按模式过滤文件（支持通配�?�?�?| | -j, --json | -j | boolean | false | 以JSON格式输出 |

信息命令 (info)

# 基本用法
urpf info package.urpf.txt                            # 显示摘要信息
urpf info package.urpf.txt --json                     # 以JSON格式输出
urpf info package.urpf.txt -v                         # 显示详细信息（包括属性和文件统计�?```

**info 参数说明**�?
| 参数 | 简�?| 类型 | 默认�?| 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `<file.urpf>` | - | 必填 | - | URPF文件路径 |
| `-v, --verbose` | -v | boolean | false | 显示详细信息 |
| `-j, --json` | -j | boolean | false | 以JSON格式输出 |

---

#### 验证命令 (verify)

```bash
# 基本用法
urpf verify package.urpf.txt                          # 验证URPF包的文件完整�?urpf verify package.urpf.txt --fix                    # 尝试修复常见问题
urpf verify package.urpf.txt -v                       # 显示详细日志
urpf verify package.urpf.txt --json                   # 以JSON格式输出

verify 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -f, --fix | -f | boolean | false | 尝试修复常见问题 | | -v, --verbose | -v | boolean | false | 显示详细日志 | | -j, --json | -j | boolean | false | 以JSON格式输出 |

比较命令 (diff)

# 基本用法
urpf diff package-v1.urpf.txt package-v2.urpf.txt     # 比较两个URPF�?urpf diff config-dev.json config-prod.json            # 比较配置文件
urpf diff package-v1.urpf.txt package-v2.urpf.txt --json  # 以JSON格式输出

diff 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file1.urpf> | - | 必填 | - | 第一个URPF文件路径 | | <file2.urpf> | - | 必填 | - | 第二个URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 | | -j, --json | -j | boolean | false | 以JSON格式输出 |

合并命令 (merge)

# 基本用法
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt                 # 合并多个URPF�?urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt   # 合并3个以上包

# 冲突处理策略
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy skip       # 跳过重复（默认）
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite  # 覆盖
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy rename     # 重命�?
# 其他选项
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt -v              # 显示详细日志

merge 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <output.urpf> | - | 必填 | - | 输出URPF文件路径 | | <input.urpf...> | - | 必填 | - | 输入URPF文件路径（至�?个） | | -s, --strategy | -s | string | skip | 合并策略：skip（跳过）/overwrite（覆盖）/rename（重命名�?| | -v, --verbose | -v | boolean | false | 显示详细日志 |

冲突检测与管理命令 (conflict)

conflict 命令用于检测、封装和解决 URPF 包之间的冲突，支持文件内容冲突、变量冲突和环境变量冲突�? *conflict find 子命�? - 检测冲突：

# 基本用法
urpf conflict find file1.urpf.txt file2.urpf.txt                # 检测两个包之间的冲�?urpf conflict find pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt    # 检测多个包之间的冲�?
# 忽略特定类型的冲�?urpf conflict find file1.urpf.txt file2.urpf.txt --ignore-var   # 忽略变量冲突
urpf conflict find file1.urpf.txt file2.urpf.txt --ignore-env   # 忽略环境变量冲突
urpf conflict find file1.urpf.txt file2.urpf.txt --ignore-var --ignore-env  # 忽略所有属性冲�?
# 输出格式
urpf conflict find file1.urpf.txt file2.urpf.txt --json        # �?JSON 格式输出
urpf conflict find file1.urpf.txt file2.urpf.txt -v            # 显示详细日志

conflict find 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf...> | - | 必填 | - | 要检测的URPF文件路径（至�?个） | | --ignore-var | - | boolean | false | 忽略变量冲突 | | --ignore-env | - | boolean | false | 忽略环境变量冲突 | | -j, --json | -j | boolean | false | 以JSON格式输出 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

conflict find 输出示例�?

🔍 检测到 2 个冲�?

  📄 文件内容冲突 (1 �?:
    路径              大小差异    来源文件
    ───────────────────────────────────────────────────
    config/app.conf   +123 B      file1.urpf.txt -> file2.urpf.txt

  ⚙️  变量冲突 (1 �?:
    变量�?           �?1                        �?2
    ────────────────────────────────────────────────────────────────
    API_VERSION       1.0.0                      2.0.0

退出码�?- 0 - 无冲�?- 1 - 检测到冲突

• 2 - 错误（文件不存在、格式错误等�?

*conflict pack 子命�? - 封装冲突�?

# 基本用法
urpf conflict pack file1.urpf.txt file2.urpf.txt -o conflicts.urpf.txt  # 封装冲突为URPF文件
urpf conflict pack pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt -o all-conflicts.urpf.txt  # 封装多个包的冲突

# 其他选项
urpf conflict pack file1.urpf.txt file2.urpf.txt -o conflicts.urpf.txt -v  # 显示详细日志

conflict pack 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf...> | - | 必填 | - | 要检测冲突的URPF文件路径（至�?个） | | -o, --output | -o | string | 必填 | 输出冲突文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

冲突文件命名规范�?- 冲突文件名使用随机化后缀，格式：<文件�?.conflict.{8位十六进制}

• 示例：conflicts.urpf.conflict.a1b2c3d4

输出示例�?

�?已将 2 个冲突封装到 conflicts.urpf.conflict.a1b2c3d4
  - 文件内容冲突: 1 �?  - 变量冲突: 1 �?  - 环境变量冲突: 0 �?  ⏱️  执行耗时: 45ms

*conflict resolve 子命�? - 解决冲突�?

# 交互式解决（逐个询问选择版本�?urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt

# 策略式解决（自动选择版本�?urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt --select v1   # 保留所�?v1 版本
urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt --select v2   # 保留所�?v2 版本

# 其他选项
urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt -v            # 显示详细日志

conflict resolve 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <conflicts.urpf> | - | 必填 | - | 冲突文件路径（由 conflict pack 生成�?| | -o, --output | -o | string | 必填 | 输出合并后的URPF文件路径 | | --select | - | string | undefined | 选择版本策略：v1 �?v2 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

交互式选择示例�?

检测到冲突: config/app.conf
  版本 1 (来源: file1.urpf.txt):
    server.port=8080
    server.host=localhost
  版本 2 (来源: file2.urpf.txt):
    server.port=3000
    server.host=0.0.0.0
  请选择保留的版�?(1/2): 1

输出示例�?

�?已解�?2 个冲突，生成 merged.urpf.txt
  - 文件内容冲突: 1 �?  - 变量冲突: 1 �?  - 环境变量冲突: 0 �?  ⏱️  执行耗时: 123ms

冲突文件结构�? 冲突文件符合 URPF v1.0 规范，包含以下内容：

**属性部分（Metadata�?*�?- conflict-type - 冲突类型（file-content、variable、environment�?- source-file-1 - 来源文件 1 的路�?- source-file-2 - 来源文件 2 的路�?- timestamp - 冲突检测时间戳

**资源部分（Resources�?*�?- 冲突版本的完整内容，使用 .v1 �?.v2 后缀区分

• 保留原始文件的权限、编码和换行符类�? 典型使用场景�?

1. **版本冲突检�?*�? ```bash

   检测开发环境和生产环境的配置差�? urpf conflict find config-dev.urpf.txt config-prod.urpf.txt

2. **协作开发冲突处�?*�? ```bash

   多个开发者生成的 URPF 包合并前检测冲�? urpf conflict find alice.urpf.txt bob.urpf.txt charlie.urpf.txt

3. 批量配置迁移�? ```bash

   封装冲突后分批解�? urpf conflict pack old.urpf.txt new.urpf.txt -o conflicts.urpf.txt

   urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt --select v2

4. CI/CD 集成�? ```bash

   �?CI 流程中检测冲突并自动拒绝部署

   urpf conflict find staging.urpf.txt production.urpf.txt if [ $? -eq 1 ]; then echo "发现配置冲突，部署被中止" exit 1 fi

变量管理命令 (var)

# 添加变量
urpf var add package.urpf.txt VERSION "1.0.0"         # 添加变量
urpf var add package.urpf.txt VERSION "1.0.0" -v      # 显示详细日志
urpf var add package.urpf.txt VERSION "2.0.0" --force # 强制覆盖已存在的变量

# 列出变量
urpf var list package.urpf.txt                        # 列出所有变�?urpf var list package.urpf.txt -v                     # 显示详细日志

# 删除变量
urpf var remove package.urpf.txt VERSION              # 删除指定变量
urpf var remove package.urpf.txt VERSION -v           # 显示详细日志

# 清除变量
urpf var clear package.urpf.txt                       # 清除所有变�?urpf var clear package.urpf.txt -v                    # 显示详细日志

var add 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | <name> | - | 必填 | - | 变量�?| | <value> | - | 必填 | - | 变量�?| | -v, --verbose | -v | boolean | false | 显示详细日志 | | --force | - | boolean | false | 强制覆盖已存在的变量 |

var list 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

var remove 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | <name> | - | 必填 | - | 变量�?| | -v, --verbose | -v | boolean | false | 显示详细日志 |

var clear 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

环境变量管理命令 (env)

# 添加环境变量
urpf env add package.urpf.txt API_KEY                  # 使用系统环境变量�?urpf env add package.urpf.txt API_KEY "my-secret-key" # 指定环境变量�?urpf env add package.urpf.txt API_KEY "value" -v      # 显示详细日志
urpf env add package.urpf.txt API_KEY "value" --force # 强制覆盖已存在的变量

# 列出环境变量
urpf env list package.urpf.txt                        # 列出所有环境变�?urpf env list package.urpf.txt -v                     # 显示详细日志

# 删除环境变量
urpf env remove package.urpf.txt API_KEY              # 删除指定环境变量
urpf env remove package.urpf.txt API_KEY -v           # 显示详细日志

# 清除环境变量
urpf env clear package.urpf.txt                       # 清除所有环境变�?urpf env clear package.urpf.txt -v                    # 显示详细日志

env add 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | <name> | - | 必填 | - | 环境变量�?| | [value] | - | 可�?| 从系统环境变量读�?| 环境变量值（可选） | | -v, --verbose | -v | boolean | false | 显示详细日志 | | --force | - | boolean | false | 强制覆盖已存在的环境变量 |

env list 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

env remove 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | <name> | - | 必填 | - | 环境变量�?| | -v, --verbose | -v | boolean | false | 显示详细日志 |

env clear 参数说明�? | 参数 | 简�?| 类型 | 默认�?| 说明 | | :--- | :--- | :--- | :--- | :--- | | <file.urpf> | - | 必填 | - | URPF文件路径 | | -v, --verbose | -v | boolean | false | 显示详细日志 |

Shell 自动补全命令 (completion)

生成 Shell 自动补全脚本，提升命令行使用体验。

# Bash
urpf completion bash >> ~/.bashrc
# 或
urpf completion bash >> ~/.bash_profile

# Zsh
urpf completion zsh >> ~/.zshrc

# Fish
urpf completion fish > ~/.config/fish/completions/urpf.fish

# PowerShell
urpf completion powershell >> $PROFILE

安装后，重新打开终端或运行 source ~/.bashrc（Bash）或 source ~/.zshrc（Zsh）即可使用自动补全功能。

支持的 Shell：

• bash - Bash shell
• zsh - Zsh shell
• fish - Fish shell
• powershell - PowerShell

文件后缀

URPF 文件使用 .urpf.txt 后缀，这是一种文本格式的资源包文件�?

Key 提取功能

URPF CLI 支持从多种配置文件格式中提取指定键值的功能�? **支持的文件格�?*�?- JSON (.json)

• YAML (.yaml, .yml)
• TOML (.toml)
• XML (.xml)
• Properties (.properties)
• INI (.ini)

**打包时提�?key �?*�?

# 基本用法
urpf pack create config.json --key "server.port"              # 提取单个键�?urpf pack create config.json --key "server.port" --stdout     # 输出到屏�?
# 嵌套属性访�?urpf pack create config.yaml --key "database.host"             # YAML 嵌套
urpf pack create config.toml --key "app.version"               # TOML 嵌套
urpf pack create config.xml --key "root.server.port"           # XML 从根元素开�?
# 数组索引访问
urpf pack create config.json --key "items[0].name"             # 使用方括�?urpf pack create config.json --key "items.0.name"              # 使用点号（等价）

# 批量提取（逗号分隔�?urpf pack create config.json --key "server.port,server.host"   # 提取多个键�?urpf pack create config.json --key "items[0].name,items[1].name"

# 支持通配�?urpf pack create config.json --key "items[*].name"             # 提取所有数组元素的name
urpf pack create config.json --key "server.*"                  # 提取server下的所有属�?
# 多次指定 --key 选项
urpf pack create config.json --key "server.port" --key "server.host"

# 格式化输�?urpf pack create config.json --key "server.port" --format json  # JSON格式（默认）
urpf pack create config.json --key "server.port" --format yaml  # YAML格式
urpf pack create config.json --key "server.port" --format raw   # 原始格式

# 验证模式（仅验证key是否存在�?urpf pack create config.json --key "server.port" --validate

**解包时提�?key �?*�?

# 基本用法
urpf unpack package.urpf.txt --key "config.json:server.port"    # 从URPF包中提取

# 多个key值提�?urpf unpack package.urpf.txt --key "config.json:server.port" --key "config.json:server.host"

# 结合其他选项
urpf unpack package.urpf.txt --key "config.json:server.port" --stdout
urpf unpack package.urpf.txt --key "config.json:server.port" --clipboard
urpf unpack package.urpf.txt --key "config.json:server.port" --format yaml

# 使用通配�?urpf unpack package.urpf.txt --key "*.json:version"             # 从所有json文件提取version

Key 语法说明�?

• 点分隔符：使�?. 访问嵌套属性（�?config.server.port�?- 数组索引：使�?[n] �?.n 访问数组元素（如 items[0] �?items.0�?- 组合路径：支持组合使用（�?items[0].name�?- **通配�?*：支�?* 匹配任意键名，** 匹配多层路径
• 解包语法：使�?文件�?key路径 格式（如 config.json:server.port�? 示例�?

// config.json
{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "items": [
    { "name": "item1", "value": 100 },
    { "name": "item2", "value": 200 }
  ]
}

# 提取 server.port
urpf pack create config.json --key "server.port"
# 输出: 3000

# 提取 items[0].name
urpf pack create config.json --key "items[0].name"
# 输出: item1

# 提取 items.1.value（等价于 items[1].value�?urpf pack create config.json --key "items.1.value"
# 输出: 200

# 批量提取
urpf pack create config.json --key "server.port,server.host"
# 输出:
# {
#   "server.port": 3000,
#   "server.host": "localhost"
# }

注意事项�?- --key 选项�?--byte、--line 选项互斥，不能同时使�?- 如果指定�?key 路径不存在，将抛出错�?- 对于 XML 文件，key 路径从根元素开始（�?root.server.port�?- 对于 Properties �?INI 文件，支�?section 语法（如 database.host�?- 使用通配符时，返回的结果可能是数组或对象

环境变量支持

打包环境变量�?- 使用 --env <name> 打包单个环境变量

• 使用 --env "*" 打包全部环境变量（排除含 "key" 的变量）
• 使用 --env <name> <value> 指定环境变量的�? 解包环境变量�?- 如果 URPF 包包含环境变量，解包时会提示用户是否设置
• 使用 --unpack-env 选项可自动确认环境变量设置（无需用户交互�?- 使用 --apply-variables 选项可应用变量替换到文件内容

变量替换

URPF 包支持变量替换功能，可以在打包和解包时使用变量�? 定义变量�?```bash urpf var add package.urpf.txt ROOT "/path/to/root" urpf var add package.urpf.txt VERSION "1.0.0"

**使用变量**�?```bash
# �?pack remove 中使用变�?urpf pack remove package.urpf.txt "${ROOT}/config.json"
urpf pack remove package.urpf.txt "${VERSION}.txt"

# 在文件内容中使用变量（解包时�?urpf unpack package.urpf.txt --apply-variables

忽略规则

URPF CLI 支持 .gitignore 风格的忽略规则�? 默认忽略规则文件�?- .gitignore

• .urpfignore

**白名单和黑名�?*�?- .urpfallow - 白名单文件（格式�?.gitignore 一致）

• .urpfforbid - 黑名单文件（格式�?.gitignore 一致）

文件打包规则�?- 不在黑名单内

• 不在 ignore �?- 在白名单内（或无白名单）
• 不以点开�? 指定忽略规则文件�?```bash urpf pack create src/ -i .customignore

### 配置文件合并

URPF CLI 支持合并多个 URPF 包或配置文件，处理文件冲突�?
**基本用法**�?```bash
# 合并多个 URPF �?urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt

# 使用覆盖策略（默认）
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite

# 使用跳过策略
urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy skip

# 使用重命名策�?urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy rename

冲突处理策略�?- overwrite - 后文件覆盖前文件（默认）

• skip - 跳过冲突的文�?- rename - 重命名冲突的文件（如 config.json �?config_2.json�? 示例�?```bash

合并两个包含相同文件的包

urpf merge merged.urpf.txt base.urpf.txt override.urpf.txt --strategy overwrite

合并多个包并跳过冲突

urpf merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt --strategy skip

### Key 提取历史记录

URPF CLI 自动记录 Key 提取操作，支持查看历史记录和快速重用�?
**历史记录功能**�?```bash
# 查看所有历史记�?urpf pack create config.json --key "server.port" --history

# 查看最�?10 条历史记�?urpf pack create config.json --key "database.host" --history --limit 10

# 搜索历史记录
urpf pack create config.json --key "server.port" --history --search "server"

# 清除历史记录
urpf pack create config.json --key "server.port" --history --clear

历史记录位置�?- 存储在用户主目录�?.urpf/history.json

• 默认保留最�?100 条记�?- 按时间倒序排列

示例�?```bash

提取 key 并记录到历史

urpf pack create config.json --key "server.port"

查看历史记录

urpf history

重用历史记录（按索引�?urpf pack create config.json --history --reuse 0

### 远程配置文件支持

URPF CLI 支持从远�?URL 直接提取 key 或打包配置文件�?
**安全说明**�?- 默认情况下，远程文件访问�?*禁用**的，出于安全考虑
- 需要使�?`--allow-remote-file` 选项启用远程文件支持
- 远程文件请求无认证机制，请确保访问的 URL 是可信的
- 请求超时时间�?30 �?
**基本用法**�?```bash
# 从远�?URL 提取 key（需要启用远程文件支持）
urpf pack create --allow-remote-file https://example.com/config.json --key "server.port"

# 使用 Basic Auth
urpf pack create --allow-remote-file https://user:[email protected]/config.json --key "database.host"

# 使用 Bearer Token
urpf pack create --allow-remote-file https://api.example.com/config.json --key "api.key" --token "your-token-here"

# 设置超时时间（毫秒）
urpf pack create --allow-remote-file https://example.com/config.json --key "server.port" --timeout 30000

**支持的认证方�?*�?- none - 无认证（默认�?- basic - Basic Auth（用户名:密码�?- bearer - Bearer Token

• custom - 自定义请求头

注意事项�?- 远程文件访问需要网络连�?- 请求可能会因为网络问题或超时而失�?- 请确保访问的 URL 是可信的，避免访问不可信的远程资�?- 远程文件内容会被缓存到临时目录，使用后自动清�? 示例�?```bash

从公共配置文件提�?key

urpf pack create --allow-remote-file https://raw.githubusercontent.com/user/repo/main/config.json --key "app.version"

从需要认证的 API 获取配置

urpf pack create --allow-remote-file https://api.example.com/config --token "your-bearer-token" --key "api.endpoint"

### 配置差异对比

URPF CLI 支持对比两个配置文件�?URPF 包的差异，生成详细的差异报告�?
**基本用法**�?```bash
# 对比两个 URPF �?urpf diff package-v1.urpf.txt package-v2.urpf.txt

# 对比配置文件
urpf diff config-dev.json config-prod.json

# �?JSON 格式输出
urpf diff package-v1.urpf.txt package-v2.urpf.txt --json

# 显示相同�?key
urpf diff config1.yaml config2.yaml --show-same

差异类型�?- SAME - 值相�?- CHANGED - 值不�?- ADDED - 仅在第二个文件中存在

• REMOVED - 仅在第一个文件中存在

示例�?```bash

对比两个环境配置

urpf diff config.dev.json config.prod.json

输出 JSON 格式的差异报�?urpf diff package-v1.urpf.txt package-v2.urpf.txt --json > diff-report.json

显示所有差异（包括相同�?key�?urpf diff config1.yaml config2.yaml --show-same

### 冲突检测与管理

URPF CLI 提供了完整的冲突检测、封装和解决方案，支持文件内容冲突、变量冲突和环境变量冲突�?
**完整工作流程**�?
```bash
# 步骤 1: 检测冲�?urpf conflict find pkg1.urpf.txt pkg2.urpf.txt

# 步骤 2: 封装冲突（可选，用于保存冲突信息�?urpf conflict pack pkg1.urpf.txt pkg2.urpf.txt -o conflicts.urpf.txt

# 步骤 3: 解决冲突
urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt

使用场景�?

1. 团队协作配置合并�? ```bash

   检测不同开发者提交的配置冲突

   urpf conflict find dev-a.urpf.txt dev-b.urpf.txt

   使用交互式方式逐个解决

   urpf conflict resolve conflicts.urpf.txt -o merged.urpf.txt

2. 环境配置迁移�? ```bash

   从测试环境迁移到生产环境时检测差�? urpf conflict find staging.urpf.txt production.urpf.txt

   自动选择生产环境的版�? urpf conflict resolve conflicts.urpf.txt -o final.urpf.txt --select v2

3. **版本回滚与合�?*�? ```bash

   对比当前版本和历史版�? urpf conflict find current.urpf.txt backup.urpf.txt

pack 命令中的冲突处理�? 当使�?pack 命令打包多个来源时，可以使用以下选项处理冲突�?

# 默认行为：遇到冲突时报错
urpf pack create dir1/ dir2/

# 保留第一个文件的�?urpf pack create dir1/ dir2/ --force-first

# 保留最后一个文件的�?urpf pack create dir1/ dir2/ --force-last

# 允许冲突并使用策略处�?urpf pack create dir1/ dir2/ --allow-conflict --force-first

高级用法

字节切片

按字节偏移量切片文件，从 0 开始�?

# 切片从字�?100 �?200
urpf pack create file.txt --byte 100:200

# 切片从字�?100 到文件末�?urpf pack create file.txt --byte 100

# 切片从文件开头到字节 200
urpf pack create file.txt --byte :200

行切�?

按行号切片文件，�?1 开始�?

# 切片�?10 �?20 �?urpf pack create file.txt --line 10:20

# 切片�?10 行到文件末尾
urpf pack create file.txt --line 10

# 切片从文件开头到�?20 �?urpf pack create file.txt --line :20

跨平台路径处�?

URPF CLI 自动处理不同操作系统的路径分隔符�?

# Windows
urpf pack create C:\project\src\

# Linux/macOS
urpf pack create /home/user/project/src/

# 相对路径
urpf pack create ./src/

项目结构

urpf/
├── src/
�?  ├── commands/       # 命令实现
�?  �?  ├── pack.ts
�?  �?  ├── unpack.ts
�?  �?  ├── pack-add.ts
�?  �?  ├── pack-remove.ts
�?  �?  ├── list.ts
�?  �?  ├── info.ts
�?  �?  ├── verify.ts
�?  �?  ├── diff.ts
�?  �?  ├── merge.ts
�?  �?  ├── var.ts
�?  �?  ├── env.ts
�?  �?  ├── conflict.ts
�?  �?  ├── download.ts
�?  �?  └── types.ts
�?  ├── core/
�?  �?  ├── parser/      # URPF 解析�?�?  �?  ├── scanner/     # 文件扫描�?�?  �?  ├── generator/   # URPF 生成�?�?  �?  ├── engine/      # UDRS 集成�?�?  �?  ├── merger/      # 配置合并器（新增�?�?  �?  ├── history/     # Key 历史记录（新增）
�?  �?  ├── remote/      # 远程文件获取（新增）
�?  �?  ├── diff/        # 配置差异对比（新增）
�?  �?  └── conflict/    # 冲突检测与管理（新增）
�?  ├── utils/          # 工具函数
�?  └── index.ts        # CLI 入口
├── tests/              # 测试文件
├── examples/           # 示例文件
├── package.json
├── tsconfig.json
└── readme.md

开�?

安装依赖

npm install

构建项目

npm run build

运行测试

npm test

代码检�?

npm run lint

代码格式�?

npm run format

许可�?

MIT License

贡献

欢迎提交 Issue �?Pull Request�?

更新日志

查看 CHANGELOG.md 了解版本更新历史�?