@tq1086/urpf-cli 1.0.0 → 2.1.0

package/readme.md

@@ -9,14 +9,25 @@
 - **问题反馈**: https://gitcode.com/tq1086/urpf-cli/issues
 
 ## 功能特性
+
 - ✅ 将文件或目录打包成 URPF 格式
 - ✅ 从 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 类型
 
 ## 安装
 
@@ -34,598 +45,621 @@ npm install @tq1086/urpf-cli
 
 #### 打包命令 (pack)
 
+URPF CLI 提供了子命令结构，支持灵活的包管理操作。
+
+**创建新的 URPF 包**：
+
 ```bash
-# 打包单个文件
-urpf-cli pack package.json
+# 创建新的 URPF 包
+urpf-cli pack create package.json
 
 # 打包目录
-urpf-cli pack src/
+urpf-cli pack create src/
 
 # 指定输出路径
-urpf-cli pack src/ -o output.urpf
+urpf-cli pack create src/ -o output.urpf.txt
 
 # 显示详细日志
-urpf-cli pack src/ -v
-```
+urpf-cli pack create src/ -v
 
-#### 解包命令 (unpack)
+# 按字节偏移量切片（从0开始）
+urpf-cli pack create file.txt --byte 100:200
 
-```bash
-# 解包到当前目录
-urpf-cli unpack package.urpf
+# 按行号切片（从1开始）
+urpf-cli pack create file.txt --line 10:20
 
-# 解包到指定目录
-urpf-cli unpack package.urpf -o ./output
+# 输出到屏幕
+urpf-cli pack create file.txt --stdout
 
-# 显示详细日志
-urpf-cli unpack package.urpf -v
+# 复制到剪贴板
+urpf-cli pack create file.txt --clipboard
 
-# 强制覆盖已存在的文件
-urpf-cli unpack package.urpf --force
-
-# 仅当源文件更新时才覆盖
-urpf-cli unpack package.urpf --force-when-newer
+# 打包环境变量
+urpf-cli pack create src/ --env API_KEY
+urpf-cli pack create src/ --env "*"
 ```
 
-#### 添加文件命令 (pack-add)
+**向已有 URPF 包添加文件**：
 
 ```bash
-# 向已有 URPF 包添加单个文件
-urpf-cli pack-add package.urpf newfile.txt
-
-# 向已有 URPF 包添加目录
-urpf-cli pack-add package.urpf newdir/
+# 添加单个文件
+urpf-cli pack add package.urpf.txt newfile.txt
 
-# 不递归扫描子目录
-urpf-cli pack-add package.urpf newdir/ --no-recurse
+# 添加多个文件
+urpf-cli pack add package.urpf.txt file1.txt file2.txt
 
-# 显示详细日志
-urpf-cli pack-add package.urpf newfile.txt -v
+# 添加目录
+urpf-cli pack add package.urpf.txt newdir/
 
-# 使用自定义忽略规则
-urpf-cli pack-add package.urpf newdir/ -i .myignore
+# 混合添加文件和目录
+urpf-cli pack add package.urpf.txt file1.txt dir1/ file2.txt
 ```
 
-#### 移除文件命令 (pack-remove)
+**从 URPF 包移除文件**：
 
 ```bash
-# 从 URPF 包中移除单个文件
-urpf-cli pack-remove package.urpf oldfile.txt
+# 移除单个文件
+urpf-cli pack remove package.urpf.txt oldfile.txt
 
-# 支持通配符匹配
-urpf-cli pack-remove package.urpf "old*.txt"
+# 移除多个文件
+urpf-cli pack remove package.urpf.txt file1.txt file2.txt
 
-# 支持问号通配符
-urpf-cli pack-remove package.urpf "file?.txt"
+# 使用通配符
+urpf-cli pack remove package.urpf.txt "*.log"
 
 # 使用变量替换
-urpf-cli pack-remove package.urpf "${root}/config.json"
-
-# 不应用变量替换
-urpf-cli pack-remove package.urpf "${root}/config.json" --no-apply-variables
-
-# 显示详细日志
-urpf-cli pack-remove package.urpf oldfile.txt -v
+urpf-cli pack remove package.urpf.txt "${root}/config.json"
 ```
 
-### 命令选项
+#### 解包命令 (unpack)
 
-#### pack 命令选项
+```bash
+# 解包到当前目录
+urpf-cli unpack package.urpf.txt
 
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-o, --output <path>` | 输出文件路径 | 输入路径.urpf |
-| `-v, --verbose` | 显示详细日志 | false |
-| `-i, --ignore <path>` | 指定忽略规则文件 | 自动检测 .gitignore/.iflowignore |
-| `-f, --follow-symlinks` | 跟随符号链接 | false |
-| `-d, --max-depth <number>` | 最大扫描深度（0 表示无限制） | 0 |
-| `--no-recurse` | 不递归扫描子目录 | false |
-| `--force` | 强制覆盖已存在的输出文件 | false |
+# 解包到指定目录
+urpf-cli unpack package.urpf.txt -o ./output
 
-#### unpack 命令选项
+# 只解压指定的文件
+urpf-cli unpack package.urpf.txt config.json
 
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-o, --output <path>` | 输出目录路径 | 当前目录 |
-| `-v, --verbose` | 显示详细日志 | false |
-| `--force` | 强制覆盖已存在的文件 | false |
-| `--force-when-newer` | 仅当源文件比目标文件更新时才覆盖 | false |
-| `--preserve-mtime` | 保留原始修改时间 | false |
+# 只解压目录
+urpf-cli unpack package.urpf.txt src/
 
-#### pack-add 命令选项
+# 解压多个文件
+urpf-cli unpack package.urpf.txt config.json src/index.js
 
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-v, --verbose` | 显示详细日志 | false |
-| `-i, --ignore <path>` | 指定忽略规则文件 | 自动检测 .gitignore/.iflowignore |
-| `-f, --follow-symlinks` | 跟随符号链接 | false |
-| `-d, --max-depth <number>` | 最大扫描深度（0 表示无限制） | 0 |
-| `--no-recurse` | 不递归扫描子目录 | false |
+# 使用通配符
+urpf-cli unpack package.urpf.txt "*.js"
 
-#### pack-remove 命令选项
+# 强制覆盖已存在的文件
+urpf-cli unpack package.urpf.txt --force
 
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-v, --verbose` | 显示详细日志 | false |
-| `--no-apply-variables` | 不应用变量替换 | true |
+# 仅当源文件更新时才覆盖
+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
+```
 
-#### 示例 1：打包项目目录
+#### 列出命令 (list)
 
 ```bash
-urpf-cli pack ./my-project -o my-project.urpf -v
-```
+# 列出 URPF 包中的所有文件
+urpf-cli list package.urpf.txt
 
-输出：
-```
-✅ URPF 文件已生成: my-project.urpf
-  文件数量: 42
-  目录数量: 8
-  跳过文件: 5
-  URPF 大小: 123456 字节
-  执行耗时: 234ms
-```
+# 按模式过滤文件
+urpf-cli list package.urpf.txt --pattern "*.js"
 
-#### 示例 2：使用自定义忽略规则
+# 以 JSON 格式输出
+urpf-cli list package.urpf.txt --json
 
-```bash
-urpf-cli pack ./src -o src.urpf -i .myignore -v
+# 显示详细信息
+urpf-cli list package.urpf.txt -v
 ```
 
-#### 示例 3：打包单个文件
+#### 信息命令 (info)
 
 ```bash
-urpf-cli pack config.json -o config.urpf
-```
+# 显示 URPF 包的摘要信息
+urpf-cli info package.urpf.txt
 
-#### 示例 4：不递归扫描子目录
+# 以 JSON 格式输出
+urpf-cli info package.urpf.txt --json
 
-```bash
-urpf-cli pack ./src --no-recurse -o src-top-level.urpf
+# 显示详细信息
+urpf-cli info package.urpf.txt -v
 ```
 
-此命令只打包 `src` 目录的顶层文件，不包含子目录。
-
-#### 示例 5：强制覆盖已存在的文件
+#### 验证命令 (verify)
 
 ```bash
-urpf-cli pack ./my-project -o my-project.urpf --force
-```
+# 验证 URPF 包的文件完整性
+urpf-cli verify package.urpf.txt
 
-如果 `my-project.urpf` 已存在，使用 `--force` 选项会强制覆盖它。
+# 尝试修复常见问题
+urpf-cli verify package.urpf.txt --fix
 
-### 解包示例
+# 显示详细日志
+urpf-cli verify package.urpf.txt -v
+```
 
-#### 示例 1：基本解包
+#### 比较命令 (diff)
 
 ```bash
-urpf-cli unpack my-project.urpf
-```
+# 比较两个 URPF 包
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt
 
-输出：
-```bash
-✅ URPF 文件已解包到: /current/directory
-  创建: 42
-  覆盖: 0
-  跳过: 0
-  总字节: 123456
-  执行耗时: 234ms
+# 以 JSON 格式输出
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json
 ```
 
-#### 示例 2：解包到指定目录
+#### 合并命令 (merge)
 
 ```bash
-urpf-cli unpack my-project.urpf -o ./extracted
+# 合并多个 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
 ```
 
-#### 示例 3：强制覆盖已存在的文件
+#### 变量管理命令 (var)
 
 ```bash
-# 第一次解包
-urpf-cli unpack my-project.urpf -o ./output
+# 添加变量
+urpf-cli var add package.urpf.txt VERSION "1.0.0"
 
-# 修改一些文件
-echo "modified" > ./output/somefile.txt
+# 列出所有变量
+urpf-cli var list package.urpf.txt
 
-# 第二次解包（不使用 --force 会失败）
-urpf-cli unpack my-project.urpf -o ./output
-# 错误: 文件已存在: somefile.txt。请使用 --force 选项强制覆盖，或使用 --force-when-newer 选项仅覆盖更新的文件。
+# 删除变量
+urpf-cli var remove package.urpf.txt VERSION
 
-# 使用 --force 强制覆盖
-urpf-cli unpack my-project.urpf -o ./output --force
+# 清除所有变量
+urpf-cli var clear package.urpf.txt
 ```
 
-#### 示例 4：仅覆盖更新的文件
+#### 环境变量管理命令 (env)
 
 ```bash
-urpf-cli unpack my-project.urpf -o ./output --force-when-newer -v
-```
+# 添加环境变量（使用系统值）
+urpf-cli env add package.urpf.txt API_KEY
 
-输出：
-```bash
-已创建: ./output/newfile.txt
-跳过（目标文件更新）: ./output/oldfile.txt
-跳过（目标文件更新）: ./output/anotherfile.txt
-✅ URPF 文件已解包到: ./output
-  创建: 1
-  覆盖: 0
-  跳过: 2
-  总字节: 1024
-  执行耗时: 123ms
-```
+# 添加环境变量（指定值）
+urpf-cli env add package.urpf.txt API_KEY "my-secret-key"
 
-#### 示例 5：保留原始修改时间
+# 列出所有环境变量
+urpf-cli env list package.urpf.txt
 
-```bash
-urpf-cli unpack my-project.urpf -o ./output --preserve-mtime
+# 删除环境变量
+urpf-cli env remove package.urpf.txt API_KEY
+
+# 清除所有环境变量
+urpf-cli env clear package.urpf.txt
 ```
 
-### 添加文件示例
+### 文件后缀
 
-#### 示例 1：添加单个文件到 URPF 包
+URPF 文件使用 `.urpf.txt` 后缀，这是一种文本格式的资源包文件。
 
-```bash
-# 创建初始 URPF 包
-urpf-cli pack ./my-project -o my-project.urpf
+### Key 提取功能
 
-# 添加新文件
-urpf-cli pack-add my-project.urpf newfile.txt
-```
+URPF CLI 支持从多种配置文件格式中提取指定键值的功能。
 
-输出：
-```bash
-✅ 已成功添加文件到 URPF 包: my-project.urpf
-  添加文件: 1
-  跳过文件: 0
-  总字节: 1024
-  执行耗时: 123ms
-```
+**支持的文件格式**：
+- JSON (.json)
+- YAML (.yaml, .yml)
+- TOML (.toml)
+- XML (.xml)
+- Properties (.properties)
+- INI (.ini)
 
-#### 示例 2：添加目录到 URPF 包
+**打包时提取 key 值**：
 
 ```bash
-urpf-cli pack-add my-project.urpf ./new-module/
-```
+# 从 JSON 文件提取 key 值
+urpf-cli pack create config.json --key "server.port"
 
-#### 示例 3：不递归添加目录
+# 从 YAML 文件提取嵌套值
+urpf-cli pack create config.yaml --key "database.host"
 
-```bash
-urpf-cli pack-add my-project.urpf ./new-module/ --no-recurse
-```
+# 从 TOML 文件提取值
+urpf-cli pack create config.toml --key "app.version"
 
-此命令只添加 `new-module` 目录的顶层文件，不包含子目录。
+# 从 XML 文件提取值
+urpf-cli pack create config.xml --key "root.server.port"
 
-#### 示例 4：使用自定义忽略规则
+# 从 Properties 文件提取值
+urpf-cli pack create config.properties --key "server.port"
 
-```bash
-urpf-cli pack-add my-project.urpf ./new-module/ -i .myignore -v
-```
+# 从 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"  # 等价写法
+```
 
-#### 示例 1：移除单个文件
+**解包时提取 key 值**：
 
 ```bash
-urpf-cli pack-remove my-project.urpf oldfile.txt
-```
+# 从 URPF 包中的配置文件提取 key 值
+urpf-cli unpack package.urpf.txt --key "config.json:server.port"
 
-输出：
-```bash
-✅ 已成功从 URPF 包移除文件: my-project.urpf
-  移除文件: 1
-  未找到: 0
-  执行耗时: 89ms
-```
+# 提取多个 key 值
+urpf-cli unpack package.urpf.txt --key "config.json:server.port" --key "config.json:server.host"
 
-#### 示例 2：使用通配符移除多个文件
+# 结合其他选项使用
+urpf-cli unpack package.urpf.txt --key "config.json:server.port" --stdout
+```
 
-```bash
-# 移除所有 .log 文件
-urpf-cli pack-remove my-project.urpf "*.log"
+**Key 语法说明**：
 
-# 移除所有以 old 开头的文件
-urpf-cli pack-remove my-project.urpf "old*"
-```
+- **点分隔符**：使用 `.` 访问嵌套属性（如 `config.server.port`）
+- **数组索引**：使用 `[n]` 或 `.n` 访问数组元素（如 `items[0]` 或 `items.0`）
+- **组合路径**：支持组合使用（如 `items[0].name`）
 
-#### 示例 3：移除子目录中的文件
+**示例**：
 
-```bash
-urpf-cli pack-remove my-project.urpf "subdir/oldfile.txt"
+```json
+// config.json
+{
+  "server": {
+    "port": 3000,
+    "host": "localhost"
+  },
+  "items": [
+    { "name": "item1", "value": 100 },
+    { "name": "item2", "value": 200 }
+  ]
+}
 ```
 
-#### 示例 4：使用变量替换
+```bash
+# 提取 server.port
+urpf-cli pack create config.json --key "server.port"
+# 输出: 3000
 
-首先，创建一个包含变量定义的 URPF 文件：
+# 提取 items[0].name
+urpf-cli pack create config.json --key "items[0].name"
+# 输出: item1
 
-```bash
-# 创建 URPF 文件（假设包含属性部分）
-urpf-cli pack ./my-project -o my-project.urpf
+# 提取 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`）
 
-```bash
-# 移除 ${root}/config.json
-urpf-cli pack-remove my-project.urpf "${root}/config.json" -v
-```
+### 环境变量支持
 
-输出：
-```bash
-Variable replacement: ${root}/config.json -> subdir/config.json
-Successfully removed 1 files: my-project.urpf
-  Removed files:
-    - file://subdir/config.json
-  Not found count: 0
-  Duration: 123ms
-```
+**打包环境变量**：
+- 使用 `--env <name>` 打包单个环境变量
+- 使用 `--env "*"` 打包全部环境变量（排除含 "key" 的变量）
+- 使用 `--env <name> <value>` 指定环境变量的值
+
+**解包环境变量**：
+- 如果 URPF 包包含环境变量，解包时会提示用户是否设置
+- 使用 `--unpack-env` 选项可自动确认环境变量设置（无需用户交互）
+- 使用 `--apply-variables` 选项可应用变量替换到文件内容
+
+### 变量替换
 
-#### 示例 5：处理不存在的文件
+URPF 包支持变量替换功能，可以在打包和解包时使用变量。
 
+**定义变量**：
 ```bash
-urpf-cli pack-remove my-project.urpf nonexistent.txt
+urpf-cli var add package.urpf.txt ROOT "/path/to/root"
+urpf-cli var add package.urpf.txt VERSION "1.0.0"
 ```
 
-输出：
+**使用变量**：
 ```bash
-✅ 已成功从 URPF 包移除文件: my-project.urpf
-  移除文件: 0
-  未找到: 1
-  执行耗时: 45ms
-```
+# 在 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`
-- `.iflowignore`
-- `.npmignore`
-
-也可以通过 `-i` 选项指定自定义的忽略规则文件。
-
-**忽略规则示例**：
-```gitignore
-# 忽略 node_modules 目录
-node_modules/
-
-# 忽略所有 .log 文件
-*.log
+URPF CLI 支持 `.gitignore` 风格的忽略规则。
 
-# 忽略 build 目录
-build/
-
-# 忽略 .env 文件
-.env
-```
+**默认忽略规则文件**：
+- `.gitignore`
+- `.urpfignore`
 
-### 递归控制
+**白名单和黑名单**：
+- `.urpfallow` - 白名单文件（格式与 .gitignore 一致）
+- `.urpfforbid` - 黑名单文件（格式与 .gitignore 一致）
 
-默认情况下，`pack` 命令会递归扫描所有子目录。使用 `--no-recurse` 选项可以只打包当前目录的文件：
+**文件打包规则**：
+- 不在黑名单内
+- 不在 ignore 内
+- 在白名单内（或无白名单）
+- 不以点开头
 
+**指定忽略规则文件**：
 ```bash
-# 递归打包（默认）
-urpf-cli pack ./src
-
-# 只打包顶层文件
-urpf-cli pack ./src --no-recurse
+urpf-cli pack create src/ -i .customignore
 ```
 
-### 输出文件控制
+### 配置文件合并
 
-使用 `-o` 或 `--output` 选项指定输出文件路径：
+URPF CLI 支持合并多个 URPF 包或配置文件，处理文件冲突。
 
+**基本用法**：
 ```bash
-# 相对路径
-urpf-cli pack ./src -o ./output/src.urpf
+# 合并多个 URPF 包
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt
 
-# 绝对路径
-urpf-cli pack ./src -o /tmp/src.urpf
+# 使用覆盖策略（默认）
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt --strategy overwrite
 
-# 自定义文件名
-urpf-cli pack ./src -o my-package.urpf
-```
+# 使用跳过策略
+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
+```
 
-如果输出文件已存在，`pack` 命令会报错并提示用户。使用 `--force` 选项可以强制覆盖：
+**冲突处理策略**：
+- `overwrite` - 后文件覆盖前文件（默认）
+- `skip` - 跳过冲突的文件
+- `rename` - 重命名冲突的文件（如 `config.json` → `config_2.json`）
 
+**示例**：
 ```bash
-# 第一次打包
-urpf-cli pack ./my-project -o my-project.urpf
-
-# 第二次打包（不使用 --force 会失败）
-urpf-cli pack ./my-project -o my-project.urpf
-# 错误: 输出文件已存在: my-project.urpf。请使用 --force 选项强制覆盖，或指定不同的输出路径。
+# 合并两个包含相同文件的包
+urpf-cli merge merged.urpf.txt base.urpf.txt override.urpf.txt --strategy overwrite
 
-# 使用 --force 强制覆盖
-urpf-cli pack ./my-project -o my-project.urpf --force
+# 合并多个包并跳过冲突
+urpf-cli merge merged.urpf.txt pkg1.urpf.txt pkg2.urpf.txt pkg3.urpf.txt --strategy skip
 ```
 
-## 变量替换
+### Key 提取历史记录
 
-`pack-remove` 命令支持变量替换功能，可以从 URPF 文件的属性部分读取变量定义，并在移除文件时应用这些变量。
+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 文件的属性部分定义变量：
+# 搜索历史记录
+urpf-cli pack create config.json --key "server.port" --history --search "server"
 
+# 清除历史记录
+urpf-cli pack create config.json --key "server.port" --history --clear
 ```
---URPF-BOUNDARY-a1b2c3d4--
 
-$root=subdir
-$version=1.0.0
+**历史记录位置**：
+- 存储在用户主目录的 `.urpf/history.json`
+- 默认保留最近 100 条记录
+- 按时间倒序排列
 
---URPF-BOUNDARY-a1b2c3d4--
+**示例**：
+```bash
+# 提取 key 并记录到历史
+urpf-cli pack create config.json --key "server.port"
 
-@file://${root}/config.json utf-8 644 lf
-{"name": "my-app", "version": "${version}"}
+# 查看历史记录
+urpf-cli history
 
---URPF-BOUNDARY-a1b2c3d4--
+# 重用历史记录（按索引）
+urpf-cli pack create config.json --history --reuse 0
 ```
 
-### 使用变量
+### 远程配置文件支持
 
-在 `pack-remove` 命令中使用变量：
+URPF CLI 支持从远程 URL 直接提取 key 或打包配置文件。
 
+**基本用法**：
 ```bash
-# 移除 ${root}/config.json（实际移除 subdir/config.json）
-urpf-cli pack-remove package.urpf "${root}/config.json"
+# 从远程 URL 提取 key
+urpf-cli pack create https://example.com/config.json --key "server.port"
 
-# 移除 ${version}.txt（实际移除 1.0.0.txt）
-urpf-cli pack-remove package.urpf "${version}.txt"
-```
+# 使用 Basic Auth
+urpf-cli pack create https://user:password@example.com/config.json --key "database.host"
 
-## URPF 文件格式
+# 使用 Bearer Token
+urpf-cli pack create https://api.example.com/config.json --key "api.key" --token "your-token-here"
 
-URPF 是一种用于打包、分发和精确描述多个关联资源的通用文本格式。它通过边界分隔符组织多个独立部分，每个部分可包含属性定义或资源内容。
+# 设置超时时间（毫秒）
+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-BOUNDARY-a1b2c3d4--
 
-$project=/home/user/project
-$version=1.0.0
+### 配置差异对比
 
---URPF-BOUNDARY-a1b2c3d4--
+URPF CLI 支持对比两个配置文件或 URPF 包的差异，生成详细的差异报告。
 
-@file://${project}/config.json utf-8 644 lf
-{
-  "name": "my-project",
-  "version": "1.0.0"
-}
+**基本用法**：
+```bash
+# 对比两个 URPF 包
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt
 
---URPF-BOUNDARY-a1b2c3d4--
+# 对比配置文件
+urpf-cli diff config-dev.json config-prod.json
 
-@file://${project}/src/index.js utf-8 644 lf
-console.log("Hello, World!");
+# 以 JSON 格式输出
+urpf-cli diff package-v1.urpf.txt package-v2.urpf.txt --json
 
---URPF-BOUNDARY-a1b2c3d4--
+# 显示相同的 key
+urpf-cli diff config1.yaml config2.yaml --show-same
 ```
 
-### 规范说明
-
-- **边界令牌**：8位十六进制数字，用于分隔不同的部分
-- **属性部分**：以 `$` 开头的变量定义
-- **资源部分**：以 `@` 开头的资源引用，包含 UDRS 引用、编码、权限和换行符类型
-- **资源引用**：遵循 UDRS v1.1 规范，支持文件协议和非文件协议
+**差异类型**：
+- `SAME` - 值相同
+- `CHANGED` - 值不同
+- `ADDED` - 仅在第二个文件中存在
+- `REMOVED` - 仅在第一个文件中存在
 
-详细规范请参考 [URPF v1.0 规范文档](./goal.md)。
+**示例**：
+```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
 
-工具支持 `.gitignore` 风格的忽略规则，可以自动检测以下文件：
-- `.gitignore`
-- `.iflowignore`
-- `.npmignore`
+# 显示所有差异（包括相同的 key）
+urpf-cli diff config1.yaml config2.yaml --show-same
+```
 
-### 忽略规则示例
+## 高级用法
 
-```
-# 忽略 node_modules 目录
-node_modules/
+### 字节切片
 
-# 忽略所有日志文件
-*.log
+按字节偏移量切片文件，从 0 开始。
 
-# 忽略临时文件
-*.tmp
-temp/
+```bash
+# 切片从字节 100 到 200
+urpf-cli pack create file.txt --byte 100:200
 
-# 忽略特定目录
-dist/
-build/
+# 切片从字节 100 到文件末尾
+urpf-cli pack create file.txt --byte 100
 
-# 但不忽略 dist/config.json
-!dist/config.json
+# 切片从文件开头到字节 200
+urpf-cli pack create file.txt --byte :200
 ```
 
-## 开发
+### 行切片
 
-### 构建
+按行号切片文件，从 1 开始。
 
 ```bash
-npm run build
-```
-
-### 测试
+# 切片第 10 到 20 行
+urpf-cli pack create file.txt --line 10:20
 
-```bash
-# 运行所有测试
-npm test
+# 切片第 10 行到文件末尾
+urpf-cli pack create file.txt --line 10
 
-# 运行测试并显示覆盖率
-npm run test:coverage
+# 切片从文件开头到第 20 行
+urpf-cli pack create file.txt --line :20
 ```
 
-### 代码检查
+### 跨平台路径处理
+
+URPF CLI 自动处理不同操作系统的路径分隔符。
 
 ```bash
-# ESLint 检查
-npm run lint
+# Windows
+urpf-cli pack create C:\project\src\
 
-# 代码格式化
-npm run format
+# Linux/macOS
+urpf-cli pack create /home/user/project/src/
+
+# 相对路径
+urpf-cli pack create ./src/
 ```
 
 ## 项目结构
 
 ```
-urpfcli/
+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 集成层
+│   │   ├── engine/      # UDRS 集成层
+│   │   ├── merger/      # 配置合并器（新增）
+│   │   ├── history/     # Key 历史记录（新增）
+│   │   ├── remote/      # 远程文件获取（新增）
+│   │   └── diff/        # 配置差异对比（新增）
 │   ├── utils/          # 工具函数
 │   └── index.ts        # CLI 入口
 ├── tests/              # 测试文件
-│   ├── integration/    # 集成测试
-│   └── fixtures/       # 测试数据
-├── dist/               # 编译输出
-└── package.json
+├── examples/           # 示例文件
+├── package.json
+├── tsconfig.json
+└── readme.md
+```
+
+## 开发
+
+### 安装依赖
+
+```bash
+npm install
 ```
 
-## 技术栈
+### 构建项目
 
-- **语言**: TypeScript
-- **模块系统**: ESM (ECMAScript Modules)
-- **运行时**: Node.js
-- **核心依赖**:
-  - `@tq1086/urpf-sdk`: URPF 规范解析 SDK
-  - `commander`: 命令行参数解析
-- **开发工具**:
-  - `tsup`: 构建工具
-  - `vitest`: 测试框架
-  - `eslint`: 代码检查
-  - `prettier`: 代码格式化
+```bash
+npm run build
+```
 
-## 已知限制
+### 运行测试
 
-1. **大文件处理**：当前版本将整个文件内容加载到内存，对于超大文件可能会有性能问题
-2. **编码检测**：编码检测功能基于简单的启发式算法，可能不够准确
-3. **符号链接**：默认不跟随符号链接，需要使用 `-f` 选项启用
+```bash
+npm test
+```
 
-## 未来计划
+### 代码检查
 
-- [x] 实现 `unpack` 子命令
-- [x] 支持 `pack-add` 和 `pack-remove` 子命令
-- [ ] 添加 `validate` 子命令（验证 URPF 文件格式）
-- [ ] 添加 `list` 子命令（列出 URPF 文件内容）
-- [ ] 支持流式处理大文件
-- [ ] 添加压缩支持
+```bash
+npm run lint
+```
+
+### 代码格式化
+
+```bash
+npm run format
+```
 
 ## 许可证
 
-ISC
+MIT License
 
 ## 贡献
 
 欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
+查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。