@tq1086/urpf-cli 2.0.0 → 2.1.1

package/readme.md

@@ -1,424 +1,665 @@
-# URPF CLI 工具
-
-基于 URPF (Universal Resource Package Format) v1.0 规范的命令行打包工具。
-
-## 项目链接
-
-- **首页**: https://gitcode.com/tq1086/urpf-cli
-- **仓库**: git@gitcode.com:tq1086/urpf-cli.git
-- **问题反馈**: https://gitcode.com/tq1086/urpf-cli/issues
-
-## 功能特性
-
-- ✅ 将文件或目录打包成 URPF 格式
-- ✅ 从 URPF 文件中解包资源到文件系统
-- ✅ 向已有 URPF 包添加文件或目录
-- ✅ 从 URPF 包中移除文件（支持变量替换和通配符）
-- ✅ 支持 `.gitignore` 风格的忽略规则
-- ✅ 自动检测文件编码和换行符类型
-- ✅ 保留文件权限和元数据
-- ✅ 跨平台支持（Windows、Linux、macOS）
-- ✅ 按字节偏移量切片文件（从0开始）
-- ✅ 按行号切片文件（从1开始）
-- ✅ 输出 URPF 内容到屏幕
-- ✅ 复制 URPF 内容到剪贴板
-- ✅ 打包环境变量到 URPF 属性
-- ✅ 变量管理和环境变量管理
-
-## 安装
-
-```bash
-# 全局安装
-npm install -g @tq1086/urpf-cli
-
-# 本地安装
-npm install @tq1086/urpf-cli
-```
-
-## 使用方法
-
-### 基本用法
-
-#### 打包命令 (pack)
-
-URPF CLI 提供了子命令结构，支持灵活的包管理操作。
-
-**创建新的 URPF 包**：
-
-```bash
-# 创建新的 URPF 包
-urpf-cli pack create package.json
-
-# 打包目录
-urpf-cli pack create src/
-
-# 指定输出路径
-urpf-cli pack create src/ -o output.urpf.txt
-
-# 显示详细日志
-urpf-cli pack create src/ -v
-
-# 按字节偏移量切片（从0开始）
-urpf-cli pack create file.txt --byte 100:200
-
-# 按行号切片（从1开始）
-urpf-cli pack create file.txt --line 10:20
-
-# 输出到屏幕
-urpf-cli pack create file.txt --stdout
-
-# 复制到剪贴板
-urpf-cli pack create file.txt --clipboard
-
-# 打包环境变量
-urpf-cli pack create src/ --env API_KEY
-urpf-cli pack create src/ --env "*"
-```
-
-**向已有 URPF 包添加文件**：
-
-```bash
-# 添加单个文件
-urpf-cli pack add package.urpf.txt newfile.txt
-
-# 添加多个文件
-urpf-cli pack add package.urpf.txt file1.txt file2.txt
-
-# 添加目录
-urpf-cli pack add package.urpf.txt newdir/
-
-# 混合添加文件和目录
-urpf-cli pack add package.urpf.txt file1.txt dir1/ file2.txt
-```
-
-**从 URPF 包移除文件**：
-
-```bash
-# 移除单个文件
-urpf-cli pack remove package.urpf.txt oldfile.txt
-
-# 移除多个文件
-urpf-cli pack remove package.urpf.txt file1.txt file2.txt
-
-# 使用通配符
-urpf-cli pack remove package.urpf.txt "*.log"
-
-# 使用变量替换
-urpf-cli pack remove package.urpf.txt "${root}/config.json"
-```
-
-#### 解包命令 (unpack)
-
-```bash
-# 解包到当前目录
-urpf-cli unpack package.urpf.txt
-
-# 解包到指定目录
-urpf-cli unpack package.urpf.txt -o ./output
-
-# 只解压指定的文件
-urpf-cli unpack package.urpf.txt config.json
-
-# 只解压目录
-urpf-cli unpack package.urpf.txt src/
-
-# 解压多个文件
-urpf-cli unpack package.urpf.txt config.json src/index.js
-
-# 使用通配符
-urpf-cli unpack package.urpf.txt "*.js"
-
-# 强制覆盖已存在的文件
-urpf-cli unpack package.urpf.txt --force
-
-# 仅当源文件更新时才覆盖
-urpf-cli unpack package.urpf.txt --force-when-newer
-
-# 自动确认环境变量设置（无需用户交互）
-urpf-cli unpack package.urpf.txt --unpack-env
-
-# 应用变量替换到文件内容
-urpf-cli unpack package.urpf.txt --apply-variables
-```
-
-#### 列出命令 (list)
-
-```bash
-# 列出 URPF 包中的所有文件
-urpf-cli list package.urpf.txt
-
-# 按模式过滤文件
-urpf-cli list package.urpf.txt --pattern "*.js"
-
-# 以 JSON 格式输出
-urpf-cli list package.urpf.txt --json
-
-# 显示详细信息
-urpf-cli list package.urpf.txt -v
-```
-
-#### 信息命令 (info)
-
-```bash
-# 显示 URPF 包的摘要信息
-urpf-cli info package.urpf.txt
-
-# 以 JSON 格式输出
-urpf-cli info package.urpf.txt --json
-
-# 显示详细信息
-urpf-cli info package.urpf.txt -v
-```
-
-#### 验证命令 (verify)
-
-```bash
-# 验证 URPF 包的文件完整性
-urpf-cli verify package.urpf.txt
-
-# 尝试修复常见问题
-urpf-cli verify package.urpf.txt --fix
-
-# 显示详细日志
-urpf-cli verify package.urpf.txt -v
-```
-
-#### 比较命令 (diff)
-
-```bash
-# 比较两个 URPF 包
-urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt
-
-# 以 JSON 格式输出
-urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json
-```
-
-#### 合并命令 (merge)
-
-```bash
-# 合并多个 URPF 包
-urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt
-
-# 使用覆盖策略
-urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite
-
-# 使用重命名策略
-urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy rename
-```
-
-#### 变量管理命令 (var)
-
-```bash
-# 添加变量
-urpf-cli var add package.urpf.txt VERSION "1.0.0"
-
-# 列出所有变量
-urpf-cli var list package.urpf.txt
-
-# 删除变量
-urpf-cli var remove package.urpf.txt VERSION
-
-# 清除所有变量
-urpf-cli var clear package.urpf.txt
-```
-
-#### 环境变量管理命令 (env)
-
-```bash
-# 添加环境变量（使用系统值）
-urpf-cli env add package.urpf.txt API_KEY
-
-# 添加环境变量（指定值）
-urpf-cli env add package.urpf.txt API_KEY "my-secret-key"
-
-# 列出所有环境变量
-urpf-cli env list package.urpf.txt
-
-# 删除环境变量
-urpf-cli env remove package.urpf.txt API_KEY
-
-# 清除所有环境变量
-urpf-cli env clear package.urpf.txt
-```
-
-### 文件后缀
-
-URPF 文件使用 `.urpf.txt` 后缀，这是一种文本格式的资源包文件。
-
-### 环境变量支持
-
-**打包环境变量**：
-- 使用 `--env <name>` 打包单个环境变量
-- 使用 `--env "*"` 打包全部环境变量（排除含 "key" 的变量）
-- 使用 `--env <name> <value>` 指定环境变量的值
-
-**解包环境变量**：
-- 如果 URPF 包包含环境变量，解包时会提示用户是否设置
-- 使用 `--unpack-env` 选项可自动确认环境变量设置（无需用户交互）
-- 使用 `--apply-variables` 选项可应用变量替换到文件内容
-
-### 变量替换
-
-URPF 包支持变量替换功能，可以在打包和解包时使用变量。
-
-**定义变量**：
-```bash
-urpf-cli var add package.urpf.txt ROOT "/path/to/root"
-urpf-cli var add package.urpf.txt VERSION "1.0.0"
-```
-
-**使用变量**：
-```bash
-# 在 pack remove 中使用变量
-urpf-cli pack remove package.urpf.txt "${ROOT}/config.json"
-urpf-cli pack remove package.urpf.txt "${VERSION}.txt"
-
-# 在文件内容中使用变量（解包时）
-urpf-cli unpack package.urpf.txt --apply-variables
-```
-
-### 忽略规则
-
-URPF CLI 支持 `.gitignore` 风格的忽略规则。
-
-**默认忽略规则文件**：
-- `.gitignore`
-- `.urpfignore`
-
-**白名单和黑名单**：
-- `.urpfallow` - 白名单文件（格式与 .gitignore 一致）
-- `.urpfforbid` - 黑名单文件（格式与 .gitignore 一致）
-
-**文件打包规则**：
-- 不在黑名单内
-- 不在 ignore 内
-- 在白名单内（或无白名单）
-- 不以点开头
-
-**指定忽略规则文件**：
-```bash
-urpf-cli pack create src/ -i .customignore
-```
-
-## 高级用法
-
-### 字节切片
-
-按字节偏移量切片文件，从 0 开始。
-
-```bash
-# 切片从字节 100 到 200
-urpf-cli pack create file.txt --byte 100:200
-
-# 切片从字节 100 到文件末尾
-urpf-cli pack create file.txt --byte 100
-
-# 切片从文件开头到字节 200
-urpf-cli pack create file.txt --byte :200
-```
-
-### 行切片
-
-按行号切片文件，从 1 开始。
-
-```bash
-# 切片第 10 到 20 行
-urpf-cli pack create file.txt --line 10:20
-
-# 切片第 10 行到文件末尾
-urpf-cli pack create file.txt --line 10
-
-# 切片从文件开头到第 20 行
-urpf-cli pack create file.txt --line :20
-```
-
-### 跨平台路径处理
-
-URPF CLI 自动处理不同操作系统的路径分隔符。
-
-```bash
-# Windows
-urpf-cli pack create C:\project\src\
-
-# Linux/macOS
-urpf-cli pack create /home/user/project/src/
-
-# 相对路径
-urpf-cli pack create ./src/
-```
-
-## 项目结构
-
-```
-urpf-cli/
-├── 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
-│   │   └── types.ts
-│   ├── core/
-│   │   ├── parser/      # URPF 解析器
-│   │   ├── scanner/     # 文件扫描器
-│   │   ├── generator/   # URPF 生成器
-│   │   └── engine/      # UDRS 集成层
-│   ├── utils/          # 工具函数
-│   └── index.ts        # CLI 入口
-├── tests/              # 测试文件
-├── examples/           # 示例文件
-├── package.json
-├── tsconfig.json
-└── readme.md
-```
-
-## 开发
-
-### 安装依赖
-
-```bash
-npm install
-```
-
-### 构建项目
-
-```bash
-npm run build
-```
-
-### 运行测试
-
-```bash
-npm test
-```
-
-### 代码检查
-
-```bash
-npm run lint
-```
-
-### 代码格式化
-
-```bash
-npm run format
-```
-
-## 许可证
-
-MIT License
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 更新日志
-
+# URPF CLI 工具
+
+基于 URPF (Universal Resource Package Format) v1.0 规范的命令行打包工具。
+
+## 项目链接
+
+- **首页**: https://gitcode.com/tq1086/urpf-cli
+- **仓库**: git@gitcode.com:tq1086/urpf-cli.git
+- **问题反馈**: https://gitcode.com/tq1086/urpf-cli/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 类型
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @tq1086/urpf-cli
+
+# 本地安装
+npm install @tq1086/urpf-cli
+```
+
+## 使用方法
+
+### 基本用法
+
+#### 打包命令 (pack)
+
+URPF CLI 提供了子命令结构，支持灵活的包管理操作。
+
+**创建新的 URPF 包**：
+
+```bash
+# 创建新的 URPF 包
+urpf-cli pack create package.json
+
+# 打包目录
+urpf-cli pack create src/
+
+# 指定输出路径
+urpf-cli pack create src/ -o output.urpf.txt
+
+# 显示详细日志
+urpf-cli pack create src/ -v
+
+# 按字节偏移量切片（从0开始）
+urpf-cli pack create file.txt --byte 100:200
+
+# 按行号切片（从1开始）
+urpf-cli pack create file.txt --line 10:20
+
+# 输出到屏幕
+urpf-cli pack create file.txt --stdout
+
+# 复制到剪贴板
+urpf-cli pack create file.txt --clipboard
+
+# 打包环境变量
+urpf-cli pack create src/ --env API_KEY
+urpf-cli pack create src/ --env "*"
+```
+
+**向已有 URPF 包添加文件**：
+
+```bash
+# 添加单个文件
+urpf-cli pack add package.urpf.txt newfile.txt
+
+# 添加多个文件
+urpf-cli pack add package.urpf.txt file1.txt file2.txt
+
+# 添加目录
+urpf-cli pack add package.urpf.txt newdir/
+
+# 混合添加文件和目录
+urpf-cli pack add package.urpf.txt file1.txt dir1/ file2.txt
+```
+
+**从 URPF 包移除文件**：
+
+```bash
+# 移除单个文件
+urpf-cli pack remove package.urpf.txt oldfile.txt
+
+# 移除多个文件
+urpf-cli pack remove package.urpf.txt file1.txt file2.txt
+
+# 使用通配符
+urpf-cli pack remove package.urpf.txt "*.log"
+
+# 使用变量替换
+urpf-cli pack remove package.urpf.txt "${root}/config.json"
+```
+
+#### 解包命令 (unpack)
+
+```bash
+# 解包到当前目录
+urpf-cli unpack package.urpf.txt
+
+# 解包到指定目录
+urpf-cli unpack package.urpf.txt -o ./output
+
+# 只解压指定的文件
+urpf-cli unpack package.urpf.txt config.json
+
+# 只解压目录
+urpf-cli unpack package.urpf.txt src/
+
+# 解压多个文件
+urpf-cli unpack package.urpf.txt config.json src/index.js
+
+# 使用通配符
+urpf-cli unpack package.urpf.txt "*.js"
+
+# 强制覆盖已存在的文件
+urpf-cli unpack package.urpf.txt --force
+
+# 仅当源文件更新时才覆盖
+urpf-cli unpack package.urpf.txt --force-when-newer
+
+# 自动确认环境变量设置（无需用户交互）
+urpf-cli unpack package.urpf.txt --unpack-env
+
+# 应用变量替换到文件内容
+urpf-cli unpack package.urpf.txt --apply-variables
+```
+
+#### 列出命令 (list)
+
+```bash
+# 列出 URPF 包中的所有文件
+urpf-cli list package.urpf.txt
+
+# 按模式过滤文件
+urpf-cli list package.urpf.txt --pattern "*.js"
+
+# 以 JSON 格式输出
+urpf-cli list package.urpf.txt --json
+
+# 显示详细信息
+urpf-cli list package.urpf.txt -v
+```
+
+#### 信息命令 (info)
+
+```bash
+# 显示 URPF 包的摘要信息
+urpf-cli info package.urpf.txt
+
+# 以 JSON 格式输出
+urpf-cli info package.urpf.txt --json
+
+# 显示详细信息
+urpf-cli info package.urpf.txt -v
+```
+
+#### 验证命令 (verify)
+
+```bash
+# 验证 URPF 包的文件完整性
+urpf-cli verify package.urpf.txt
+
+# 尝试修复常见问题
+urpf-cli verify package.urpf.txt --fix
+
+# 显示详细日志
+urpf-cli verify package.urpf.txt -v
+```
+
+#### 比较命令 (diff)
+
+```bash
+# 比较两个 URPF 包
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt
+
+# 以 JSON 格式输出
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json
+```
+
+#### 合并命令 (merge)
+
+```bash
+# 合并多个 URPF 包
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt
+
+# 使用覆盖策略
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite
+
+# 使用重命名策略
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy rename
+```
+
+#### 变量管理命令 (var)
+
+```bash
+# 添加变量
+urpf-cli var add package.urpf.txt VERSION "1.0.0"
+
+# 列出所有变量
+urpf-cli var list package.urpf.txt
+
+# 删除变量
+urpf-cli var remove package.urpf.txt VERSION
+
+# 清除所有变量
+urpf-cli var clear package.urpf.txt
+```
+
+#### 环境变量管理命令 (env)
+
+```bash
+# 添加环境变量（使用系统值）
+urpf-cli env add package.urpf.txt API_KEY
+
+# 添加环境变量（指定值）
+urpf-cli env add package.urpf.txt API_KEY "my-secret-key"
+
+# 列出所有环境变量
+urpf-cli env list package.urpf.txt
+
+# 删除环境变量
+urpf-cli env remove package.urpf.txt API_KEY
+
+# 清除所有环境变量
+urpf-cli env clear package.urpf.txt
+```
+
+### 文件后缀
+
+URPF 文件使用 `.urpf.txt` 后缀，这是一种文本格式的资源包文件。
+
+### Key 提取功能
+
+URPF CLI 支持从多种配置文件格式中提取指定键值的功能。
+
+**支持的文件格式**：
+- JSON (.json)
+- YAML (.yaml, .yml)
+- TOML (.toml)
+- XML (.xml)
+- Properties (.properties)
+- INI (.ini)
+
+**打包时提取 key 值**：
+
+```bash
+# 从 JSON 文件提取 key 值
+urpf-cli pack create config.json --key "server.port"
+
+# 从 YAML 文件提取嵌套值
+urpf-cli pack create config.yaml --key "database.host"
+
+# 从 TOML 文件提取值
+urpf-cli pack create config.toml --key "app.version"
+
+# 从 XML 文件提取值
+urpf-cli pack create config.xml --key "root.server.port"
+
+# 从 Properties 文件提取值
+urpf-cli pack create config.properties --key "server.port"
+
+# 从 INI 文件提取值（支持 section）
+urpf-cli pack create config.ini --key "database.host"
+
+# 支持数组索引访问
+urpf-cli pack create config.json --key "items[0].name"
+urpf-cli pack create config.json --key "items.0.name"  # 等价写法
+```
+
+**解包时提取 key 值**：
+
+```bash
+# 从 URPF 包中的配置文件提取 key 值
+urpf-cli unpack package.urpf.txt --key "config.json:server.port"
+
+# 提取多个 key 值
+urpf-cli unpack package.urpf.txt --key "config.json:server.port" --key "config.json:server.host"
+
+# 结合其他选项使用
+urpf-cli unpack package.urpf.txt --key "config.json:server.port" --stdout
+```
+
+**Key 语法说明**：
+
+- **点分隔符**：使用 `.` 访问嵌套属性（如 `config.server.port`）
+- **数组索引**：使用 `[n]` 或 `.n` 访问数组元素（如 `items[0]` 或 `items.0`）
+- **组合路径**：支持组合使用（如 `items[0].name`）
+
+**示例**：
+
+```json
+// config.json
+{
+  "server": {
+    "port": 3000,
+    "host": "localhost"
+  },
+  "items": [
+    { "name": "item1", "value": 100 },
+    { "name": "item2", "value": 200 }
+  ]
+}
+```
+
+```bash
+# 提取 server.port
+urpf-cli pack create config.json --key "server.port"
+# 输出: 3000
+
+# 提取 items[0].name
+urpf-cli pack create config.json --key "items[0].name"
+# 输出: item1
+
+# 提取 items.1.value（等价于 items[1].value）
+urpf-cli pack create config.json --key "items.1.value"
+# 输出: 200
+```
+
+**注意事项**：
+- `--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-cli var add package.urpf.txt ROOT "/path/to/root"
+urpf-cli var add package.urpf.txt VERSION "1.0.0"
+```
+
+**使用变量**：
+```bash
+# 在 pack remove 中使用变量
+urpf-cli pack remove package.urpf.txt "${ROOT}/config.json"
+urpf-cli pack remove package.urpf.txt "${VERSION}.txt"
+
+# 在文件内容中使用变量（解包时）
+urpf-cli unpack package.urpf.txt --apply-variables
+```
+
+### 忽略规则
+
+URPF CLI 支持 `.gitignore` 风格的忽略规则。
+
+**默认忽略规则文件**：
+- `.gitignore`
+- `.urpfignore`
+
+**白名单和黑名单**：
+- `.urpfallow` - 白名单文件（格式与 .gitignore 一致）
+- `.urpfforbid` - 黑名单文件（格式与 .gitignore 一致）
+
+**文件打包规则**：
+- 不在黑名单内
+- 不在 ignore 内
+- 在白名单内（或无白名单）
+- 不以点开头
+
+**指定忽略规则文件**：
+```bash
+urpf-cli pack create src/ -i .customignore
+```
+
+### 配置文件合并
+
+URPF CLI 支持合并多个 URPF 包或配置文件，处理文件冲突。
+
+**基本用法**：
+```bash
+# 合并多个 URPF 包
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt
+
+# 使用覆盖策略（默认）
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite
+
+# 使用跳过策略
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy skip
+
+# 使用重命名策略
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy rename
+```
+
+**冲突处理策略**：
+- `overwrite` - 后文件覆盖前文件（默认）
+- `skip` - 跳过冲突的文件
+- `rename` - 重命名冲突的文件（如 `config.json` → `config_2.json`）
+
+**示例**：
+```bash
+# 合并两个包含相同文件的包
+urpf-cli merge merged.urpf.txt base.urpf.txt override.urpf.txt --strategy overwrite
+
+# 合并多个包并跳过冲突
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt --strategy skip
+```
+
+### Key 提取历史记录
+
+URPF CLI 自动记录 Key 提取操作，支持查看历史记录和快速重用。
+
+**历史记录功能**：
+```bash
+# 查看所有历史记录
+urpf-cli pack create config.json --key "server.port" --history
+
+# 查看最近 10 条历史记录
+urpf-cli pack create config.json --key "database.host" --history --limit 10
+
+# 搜索历史记录
+urpf-cli pack create config.json --key "server.port" --history --search "server"
+
+# 清除历史记录
+urpf-cli pack create config.json --key "server.port" --history --clear
+```
+
+**历史记录位置**：
+- 存储在用户主目录的 `.urpf/history.json`
+- 默认保留最近 100 条记录
+- 按时间倒序排列
+
+**示例**：
+```bash
+# 提取 key 并记录到历史
+urpf-cli pack create config.json --key "server.port"
+
+# 查看历史记录
+urpf-cli history
+
+# 重用历史记录（按索引）
+urpf-cli pack create config.json --history --reuse 0
+```
+
+### 远程配置文件支持
+
+URPF CLI 支持从远程 URL 直接提取 key 或打包配置文件。
+
+**基本用法**：
+```bash
+# 从远程 URL 提取 key
+urpf-cli pack create https://example.com/config.json --key "server.port"
+
+# 使用 Basic Auth
+urpf-cli pack create https://user:password@example.com/config.json --key "database.host"
+
+# 使用 Bearer Token
+urpf-cli pack create https://api.example.com/config.json --key "api.key" --token "your-token-here"
+
+# 设置超时时间（毫秒）
+urpf-cli pack create https://example.com/config.json --key "server.port" --timeout 30000
+```
+
+**支持的认证方式**：
+- `none` - 无认证（默认）
+- `basic` - Basic Auth（用户名:密码）
+- `bearer` - Bearer Token
+- `custom` - 自定义请求头
+
+**示例**：
+```bash
+# 从公共配置文件提取 key
+urpf-cli pack create https://raw.githubusercontent.com/user/repo/main/config.json --key "app.version"
+
+# 从需要认证的 API 获取配置
+urpf-cli pack create https://api.example.com/config --token "your-bearer-token" --key "api.endpoint"
+```
+
+### 配置差异对比
+
+URPF CLI 支持对比两个配置文件或 URPF 包的差异，生成详细的差异报告。
+
+**基本用法**：
+```bash
+# 对比两个 URPF 包
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt
+
+# 对比配置文件
+urpf-cli diff config-dev.json config-prod.json
+
+# 以 JSON 格式输出
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json
+
+# 显示相同的 key
+urpf-cli diff config1.yaml config2.yaml --show-same
+```
+
+**差异类型**：
+- `SAME` - 值相同
+- `CHANGED` - 值不同
+- `ADDED` - 仅在第二个文件中存在
+- `REMOVED` - 仅在第一个文件中存在
+
+**示例**：
+```bash
+# 对比两个环境配置
+urpf-cli diff config.dev.json config.prod.json
+
+# 输出 JSON 格式的差异报告
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json > diff-report.json
+
+# 显示所有差异（包括相同的 key）
+urpf-cli diff config1.yaml config2.yaml --show-same
+```
+
+## 高级用法
+
+### 字节切片
+
+按字节偏移量切片文件，从 0 开始。
+
+```bash
+# 切片从字节 100 到 200
+urpf-cli pack create file.txt --byte 100:200
+
+# 切片从字节 100 到文件末尾
+urpf-cli pack create file.txt --byte 100
+
+# 切片从文件开头到字节 200
+urpf-cli pack create file.txt --byte :200
+```
+
+### 行切片
+
+按行号切片文件，从 1 开始。
+
+```bash
+# 切片第 10 到 20 行
+urpf-cli pack create file.txt --line 10:20
+
+# 切片第 10 行到文件末尾
+urpf-cli pack create file.txt --line 10
+
+# 切片从文件开头到第 20 行
+urpf-cli pack create file.txt --line :20
+```
+
+### 跨平台路径处理
+
+URPF CLI 自动处理不同操作系统的路径分隔符。
+
+```bash
+# Windows
+urpf-cli pack create C:\project\src\
+
+# Linux/macOS
+urpf-cli pack create /home/user/project/src/
+
+# 相对路径
+urpf-cli pack create ./src/
+```
+
+## 项目结构
+
+```
+urpf-cli/
+├── 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
+│   │   └── types.ts
+│   ├── core/
+│   │   ├── parser/      # URPF 解析器
+│   │   ├── scanner/     # 文件扫描器
+│   │   ├── generator/   # URPF 生成器
+│   │   ├── engine/      # UDRS 集成层
+│   │   ├── merger/      # 配置合并器（新增）
+│   │   ├── history/     # Key 历史记录（新增）
+│   │   ├── remote/      # 远程文件获取（新增）
+│   │   └── diff/        # 配置差异对比（新增）
+│   ├── utils/          # 工具函数
+│   └── index.ts        # CLI 入口
+├── tests/              # 测试文件
+├── examples/           # 示例文件
+├── package.json
+├── tsconfig.json
+└── readme.md
+```
+
+## 开发
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 构建项目
+
+```bash
+npm run build
+```
+
+### 运行测试
+
+```bash
+npm test
+```
+
+### 代码检查
+
+```bash
+npm run lint
+```
+
+### 代码格式化
+
+```bash
+npm run format
+```
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。