@tq1086/urpf-cli 1.0.0 → 2.0.0

package/readme.md

@@ -1,631 +1,424 @@
-# 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）
-
-## 安装
-
-```bash
-# 全局安装
-npm install -g @tq1086/urpf-cli
-
-# 本地安装
-npm install @tq1086/urpf-cli
-```
-
-## 使用方法
-
-### 基本用法
-
-#### 打包命令 (pack)
-
-```bash
-# 打包单个文件
-urpf-cli pack package.json
-
-# 打包目录
-urpf-cli pack src/
-
-# 指定输出路径
-urpf-cli pack src/ -o output.urpf
-
-# 显示详细日志
-urpf-cli pack src/ -v
-```
-
-#### 解包命令 (unpack)
-
-```bash
-# 解包到当前目录
-urpf-cli unpack package.urpf
-
-# 解包到指定目录
-urpf-cli unpack package.urpf -o ./output
-
-# 显示详细日志
-urpf-cli unpack package.urpf -v
-
-# 强制覆盖已存在的文件
-urpf-cli unpack package.urpf --force
-
-# 仅当源文件更新时才覆盖
-urpf-cli unpack package.urpf --force-when-newer
-```
-
-#### 添加文件命令 (pack-add)
-
-```bash
-# 向已有 URPF 包添加单个文件
-urpf-cli pack-add package.urpf newfile.txt
-
-# 向已有 URPF 包添加目录
-urpf-cli pack-add package.urpf newdir/
-
-# 不递归扫描子目录
-urpf-cli pack-add package.urpf newdir/ --no-recurse
-
-# 显示详细日志
-urpf-cli pack-add package.urpf newfile.txt -v
-
-# 使用自定义忽略规则
-urpf-cli pack-add package.urpf newdir/ -i .myignore
-```
-
-#### 移除文件命令 (pack-remove)
-
-```bash
-# 从 URPF 包中移除单个文件
-urpf-cli pack-remove package.urpf oldfile.txt
-
-# 支持通配符匹配
-urpf-cli pack-remove package.urpf "old*.txt"
-
-# 支持问号通配符
-urpf-cli pack-remove package.urpf "file?.txt"
-
-# 使用变量替换
-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
-```
-
-### 命令选项
-
-#### pack 命令选项
-
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-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 |
-
-#### unpack 命令选项
-
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-o, --output <path>` | 输出目录路径 | 当前目录 |
-| `-v, --verbose` | 显示详细日志 | false |
-| `--force` | 强制覆盖已存在的文件 | false |
-| `--force-when-newer` | 仅当源文件比目标文件更新时才覆盖 | false |
-| `--preserve-mtime` | 保留原始修改时间 | false |
-
-#### pack-add 命令选项
-
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-v, --verbose` | 显示详细日志 | false |
-| `-i, --ignore <path>` | 指定忽略规则文件 | 自动检测 .gitignore/.iflowignore |
-| `-f, --follow-symlinks` | 跟随符号链接 | false |
-| `-d, --max-depth <number>` | 最大扫描深度（0 表示无限制） | 0 |
-| `--no-recurse` | 不递归扫描子目录 | false |
-
-#### pack-remove 命令选项
-
-| 选项 | 描述 | 默认值 |
-| :--- | :--- | :--- |
-| `-v, --verbose` | 显示详细日志 | false |
-| `--no-apply-variables` | 不应用变量替换 | true |
-
-### 使用示例
-
-#### 示例 1：打包项目目录
-
-```bash
-urpf-cli pack ./my-project -o my-project.urpf -v
-```
-
-输出：
-```
-✅ URPF 文件已生成: my-project.urpf
-  文件数量: 42
-  目录数量: 8
-  跳过文件: 5
-  URPF 大小: 123456 字节
-  执行耗时: 234ms
-```
-
-#### 示例 2：使用自定义忽略规则
-
-```bash
-urpf-cli pack ./src -o src.urpf -i .myignore -v
-```
-
-#### 示例 3：打包单个文件
-
-```bash
-urpf-cli pack config.json -o config.urpf
-```
-
-#### 示例 4：不递归扫描子目录
-
-```bash
-urpf-cli pack ./src --no-recurse -o src-top-level.urpf
-```
-
-此命令只打包 `src` 目录的顶层文件，不包含子目录。
-
-#### 示例 5：强制覆盖已存在的文件
-
-```bash
-urpf-cli pack ./my-project -o my-project.urpf --force
-```
-
-如果 `my-project.urpf` 已存在，使用 `--force` 选项会强制覆盖它。
-
-### 解包示例
-
-#### 示例 1：基本解包
-
-```bash
-urpf-cli unpack my-project.urpf
-```
-
-输出：
-```bash
-✅ URPF 文件已解包到: /current/directory
-  创建: 42
-  覆盖: 0
-  跳过: 0
-  总字节: 123456
-  执行耗时: 234ms
-```
-
-#### 示例 2：解包到指定目录
-
-```bash
-urpf-cli unpack my-project.urpf -o ./extracted
-```
-
-#### 示例 3：强制覆盖已存在的文件
-
-```bash
-# 第一次解包
-urpf-cli unpack my-project.urpf -o ./output
-
-# 修改一些文件
-echo "modified" > ./output/somefile.txt
-
-# 第二次解包（不使用 --force 会失败）
-urpf-cli unpack my-project.urpf -o ./output
-# 错误: 文件已存在: somefile.txt。请使用 --force 选项强制覆盖，或使用 --force-when-newer 选项仅覆盖更新的文件。
-
-# 使用 --force 强制覆盖
-urpf-cli unpack my-project.urpf -o ./output --force
-```
-
-#### 示例 4：仅覆盖更新的文件
-
-```bash
-urpf-cli unpack my-project.urpf -o ./output --force-when-newer -v
-```
-
-输出：
-```bash
-已创建: ./output/newfile.txt
-跳过（目标文件更新）: ./output/oldfile.txt
-跳过（目标文件更新）: ./output/anotherfile.txt
-✅ URPF 文件已解包到: ./output
-  创建: 1
-  覆盖: 0
-  跳过: 2
-  总字节: 1024
-  执行耗时: 123ms
-```
-
-#### 示例 5：保留原始修改时间
-
-```bash
-urpf-cli unpack my-project.urpf -o ./output --preserve-mtime
-```
-
-### 添加文件示例
-
-#### 示例 1：添加单个文件到 URPF 包
-
-```bash
-# 创建初始 URPF 包
-urpf-cli pack ./my-project -o my-project.urpf
-
-# 添加新文件
-urpf-cli pack-add my-project.urpf newfile.txt
-```
-
-输出：
-```bash
-✅ 已成功添加文件到 URPF 包: my-project.urpf
-  添加文件: 1
-  跳过文件: 0
-  总字节: 1024
-  执行耗时: 123ms
-```
-
-#### 示例 2：添加目录到 URPF 包
-
-```bash
-urpf-cli pack-add my-project.urpf ./new-module/
-```
-
-#### 示例 3：不递归添加目录
-
-```bash
-urpf-cli pack-add my-project.urpf ./new-module/ --no-recurse
-```
-
-此命令只添加 `new-module` 目录的顶层文件，不包含子目录。
-
-#### 示例 4：使用自定义忽略规则
-
-```bash
-urpf-cli pack-add my-project.urpf ./new-module/ -i .myignore -v
-```
-
-### 移除文件示例
-
-#### 示例 1：移除单个文件
-
-```bash
-urpf-cli pack-remove my-project.urpf oldfile.txt
-```
-
-输出：
-```bash
-✅ 已成功从 URPF 包移除文件: my-project.urpf
-  移除文件: 1
-  未找到: 0
-  执行耗时: 89ms
-```
-
-#### 示例 2：使用通配符移除多个文件
-
-```bash
-# 移除所有 .log 文件
-urpf-cli pack-remove my-project.urpf "*.log"
-
-# 移除所有以 old 开头的文件
-urpf-cli pack-remove my-project.urpf "old*"
-```
-
-#### 示例 3：移除子目录中的文件
-
-```bash
-urpf-cli pack-remove my-project.urpf "subdir/oldfile.txt"
-```
-
-#### 示例 4：使用变量替换
-
-首先，创建一个包含变量定义的 URPF 文件：
-
-```bash
-# 创建 URPF 文件（假设包含属性部分）
-urpf-cli pack ./my-project -o my-project.urpf
-```
-
-然后，使用变量替换移除文件：
-
-```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
-```
-
-#### 示例 5：处理不存在的文件
-
-```bash
-urpf-cli pack-remove my-project.urpf nonexistent.txt
-```
-
-输出：
-```bash
-✅ 已成功从 URPF 包移除文件: my-project.urpf
-  移除文件: 0
-  未找到: 1
-  执行耗时: 45ms
-```
-
-## 高级功能
-
-### 忽略规则
-
-URPF CLI 支持 `.gitignore` 风格的忽略规则，可以自动检测并应用以下文件：
-- `.gitignore`
-- `.iflowignore`
-- `.npmignore`
-
-也可以通过 `-i` 选项指定自定义的忽略规则文件。
-
-**忽略规则示例**：
-```gitignore
-# 忽略 node_modules 目录
-node_modules/
-
-# 忽略所有 .log 文件
-*.log
-
-# 忽略 build 目录
-build/
-
-# 忽略 .env 文件
-.env
-```
-
-### 递归控制
-
-默认情况下，`pack` 命令会递归扫描所有子目录。使用 `--no-recurse` 选项可以只打包当前目录的文件：
-
-```bash
-# 递归打包（默认）
-urpf-cli pack ./src
-
-# 只打包顶层文件
-urpf-cli pack ./src --no-recurse
-```
-
-### 输出文件控制
-
-使用 `-o` 或 `--output` 选项指定输出文件路径：
-
-```bash
-# 相对路径
-urpf-cli pack ./src -o ./output/src.urpf
-
-# 绝对路径
-urpf-cli pack ./src -o /tmp/src.urpf
-
-# 自定义文件名
-urpf-cli pack ./src -o my-package.urpf
-```
-
-### 覆盖已存在的文件
-
-如果输出文件已存在，`pack` 命令会报错并提示用户。使用 `--force` 选项可以强制覆盖：
-
-```bash
-# 第一次打包
-urpf-cli pack ./my-project -o my-project.urpf
-
-# 第二次打包（不使用 --force 会失败）
-urpf-cli pack ./my-project -o my-project.urpf
-# 错误: 输出文件已存在: my-project.urpf。请使用 --force 选项强制覆盖，或指定不同的输出路径。
-
-# 使用 --force 强制覆盖
-urpf-cli pack ./my-project -o my-project.urpf --force
-```
-
-## 变量替换
-
-`pack-remove` 命令支持变量替换功能，可以从 URPF 文件的属性部分读取变量定义，并在移除文件时应用这些变量。
-
-### 变量定义
-
-在 URPF 文件的属性部分定义变量：
-
-```
---URPF-BOUNDARY-a1b2c3d4--
-
-$root=subdir
-$version=1.0.0
-
---URPF-BOUNDARY-a1b2c3d4--
-
-@file://${root}/config.json utf-8 644 lf
-{"name": "my-app", "version": "${version}"}
-
---URPF-BOUNDARY-a1b2c3d4--
-```
-
-### 使用变量
-
-在 `pack-remove` 命令中使用变量：
-
-```bash
-# 移除 ${root}/config.json（实际移除 subdir/config.json）
-urpf-cli pack-remove package.urpf "${root}/config.json"
-
-# 移除 ${version}.txt（实际移除 1.0.0.txt）
-urpf-cli pack-remove package.urpf "${version}.txt"
-```
-
-## URPF 文件格式
-
-URPF 是一种用于打包、分发和精确描述多个关联资源的通用文本格式。它通过边界分隔符组织多个独立部分，每个部分可包含属性定义或资源内容。
-
-### 格式示例
-
-```
---URPF-BOUNDARY-a1b2c3d4--
-
-$project=/home/user/project
-$version=1.0.0
-
---URPF-BOUNDARY-a1b2c3d4--
-
-@file://${project}/config.json utf-8 644 lf
-{
-  "name": "my-project",
-  "version": "1.0.0"
-}
-
---URPF-BOUNDARY-a1b2c3d4--
-
-@file://${project}/src/index.js utf-8 644 lf
-console.log("Hello, World!");
-
---URPF-BOUNDARY-a1b2c3d4--
-```
-
-### 规范说明
-
-- **边界令牌**：8位十六进制数字，用于分隔不同的部分
-- **属性部分**：以 `$` 开头的变量定义
-- **资源部分**：以 `@` 开头的资源引用，包含 UDRS 引用、编码、权限和换行符类型
-- **资源引用**：遵循 UDRS v1.1 规范，支持文件协议和非文件协议
-
-详细规范请参考 [URPF v1.0 规范文档](./goal.md)。
-
-## 忽略规则
-
-工具支持 `.gitignore` 风格的忽略规则，可以自动检测以下文件：
-- `.gitignore`
-- `.iflowignore`
-- `.npmignore`
-
-### 忽略规则示例
-
-```
-# 忽略 node_modules 目录
-node_modules/
-
-# 忽略所有日志文件
-*.log
-
-# 忽略临时文件
-*.tmp
-temp/
-
-# 忽略特定目录
-dist/
-build/
-
-# 但不忽略 dist/config.json
-!dist/config.json
-```
-
-## 开发
-
-### 构建
-
-```bash
-npm run build
-```
-
-### 测试
-
-```bash
-# 运行所有测试
-npm test
-
-# 运行测试并显示覆盖率
-npm run test:coverage
-```
-
-### 代码检查
-
-```bash
-# ESLint 检查
-npm run lint
-
-# 代码格式化
-npm run format
-```
-
-## 项目结构
-
-```
-urpfcli/
-├── src/
-│   ├── commands/       # 命令实现
-│   │   ├── pack.ts
-│   │   ├── unpack.ts
-│   │   └── types.ts
-│   ├── core/
-│   │   ├── parser/      # URPF 解析器
-│   │   ├── scanner/     # 文件扫描器
-│   │   ├── generator/   # URPF 生成器
-│   │   └── engine/      # UDRS 集成层
-│   ├── utils/          # 工具函数
-│   └── index.ts        # CLI 入口
-├── tests/              # 测试文件
-│   ├── integration/    # 集成测试
-│   └── fixtures/       # 测试数据
-├── dist/               # 编译输出
-└── package.json
-```
-
-## 技术栈
-
-- **语言**: TypeScript
-- **模块系统**: ESM (ECMAScript Modules)
-- **运行时**: Node.js
-- **核心依赖**:
-  - `@tq1086/urpf-sdk`: URPF 规范解析 SDK
-  - `commander`: 命令行参数解析
-- **开发工具**:
-  - `tsup`: 构建工具
-  - `vitest`: 测试框架
-  - `eslint`: 代码检查
-  - `prettier`: 代码格式化
-
-## 已知限制
-
-1. **大文件处理**：当前版本将整个文件内容加载到内存，对于超大文件可能会有性能问题
-2. **编码检测**：编码检测功能基于简单的启发式算法，可能不够准确
-3. **符号链接**：默认不跟随符号链接，需要使用 `-f` 选项启用
-
-## 未来计划
-
-- [x] 实现 `unpack` 子命令
-- [x] 支持 `pack-add` 和 `pack-remove` 子命令
-- [ ] 添加 `validate` 子命令（验证 URPF 文件格式）
-- [ ] 添加 `list` 子命令（列出 URPF 文件内容）
-- [ ] 支持流式处理大文件
-- [ ] 添加压缩支持
-
-## 许可证
-
-ISC
-
-## 贡献
-
-欢迎提交 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 属性
+- ✅ 变量管理和环境变量管理
+
+## 安装
+
+```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！
+
+## 更新日志
+
+查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。