bt-patch

bt-patch 是一个 Rust 命令行工具，用于修补部分下载完成但存在空洞的文件。它支持两种工作方式：

• 手动按偏移复制指定区间
• 基于锚点自动定位并修补零字节空洞

这个工具面向“目标文件不完整，但你手上还有完整文件或可用于补丁的数据源”的场景，重点是尽量安全地修补，而不是猜测性写入。

特性

• 支持 manual、auto-once、auto-all 三个子命令
• 自动模式按连续零字节区间扫描候选空洞
• 自动定位时优先使用前锚点，并在可用时叠加后锚点确认
• 文件开头缺失时，后锚点也可以作为主要定位依据
• 默认流式处理，适合大文件
• 支持 dry-run、备份输出、写入新文件
• 手动模式支持 sha256:<hex> 校验
• 运行时进度显示到 stderr
• 帮助信息、错误信息、报告信息可根据系统语言显示中文或英文
• 输出中的偏移和长度会同时显示十进制和十六进制

适用场景

• BT 或其他分块下载产生了连续零字节空洞
• 你已经拿到一份完整文件，或至少拿到包含正确内容的补丁源文件
• 你知道准确偏移，想做一次精确覆盖
• 你不知道偏移，但空洞附近内容仍可作为锚点定位

不适用场景

• 非零字节但内容错误的损坏区域
• 需要自动处理多文件 torrent 路径映射
• 需要联网下载缺失分块
• 需要依赖 .torrent piece hash 做完整校验

安装与构建

要求：

• Rust 工具链
• Cargo

构建：

cargo build --release

Windows 下生成的可执行文件通常位于：

target\release\bt-patch.exe

开发调试时可直接运行：

cargo run -- <COMMAND> [OPTIONS]

命令概览

bt-patch <COMMAND> [OPTIONS]

子命令：

• manual：按明确偏移修补目标区间
• auto-once：扫描零字节空洞，只修补第一个唯一匹配的空洞
• auto-all：扫描零字节空洞，修补全部唯一匹配的空洞

手动模式

用途：你已经知道目标文件偏移、补丁源偏移和长度，希望做精确写入。

bt-patch manual [OPTIONS]

参数：

• -t, --target <FILE>：目标文件
• -p, --patch <FILE>：补丁源文件
• -T, --target-offset <U64>：目标文件写入起始偏移
• -P, --patch-offset <U64>：补丁源读取起始偏移
• -l, --length <U64>：复制字节数
• -d, --dry-run：仅输出计划，不修改文件
• -b, --backup：写入前创建 <target>.bak
• -o, --output <FILE>：输出到新文件，不直接修改目标文件
• -v, --verify <SPEC>：写入后校验目标区间，目前支持 sha256:<hex>

示例：

bt-patch manual ^
  -t partial.bin ^
  -p full.bin ^
  -T 0 ^
  -P 0 ^
  -l 1048576

写入到新文件：

bt-patch manual ^
  -t partial.bin ^
  -p full.bin ^
  -T 1048576 ^
  -P 1048576 ^
  -l 524288 ^
  -o repaired.bin

带校验：

bt-patch manual ^
  -t partial.bin ^
  -p full.bin ^
  -T 0 ^
  -P 0 ^
  -l 4096 ^
  -v sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

自动模式

自动模式会从目标文件中扫描“连续零字节区间”，将其视为候选空洞，然后尝试在补丁源文件中定位对应内容。

核心规则：

• 先找连续零字节区间
• 优先提取空洞前方锚点
• 如果有后锚点，则叠加确认
• 如果前锚点不可用，后锚点也可以单独承担主定位
• 只有唯一匹配才允许写入
• 出现歧义时宁可跳过，不做猜测性修补

auto-once

bt-patch auto-once [OPTIONS]

用途：只修补第一个满足安全条件且唯一匹配的空洞。

auto-all

bt-patch auto-all [OPTIONS]

用途：依次扫描所有候选空洞，修补全部唯一匹配的空洞；无法安全修补的空洞会跳过并记录结果。

自动模式参数

• -t, --target <FILE>：目标文件
• -p, --patch <FILE>：补丁源文件
• -s, --search-start <U64>：扫描起始偏移，支持字节偏移或小数比例，例如 0.7 表示文件长度的 70%，默认 0
• -z, --zero-threshold <U64>：最小零字节连续长度，默认 1048576
• -a, --anchor-size <U64>：前后锚点大小，默认 4096
• -m, --max-match-candidates <U32>：最大候选数，超过即视为歧义，默认 32
• -d, --dry-run：仅输出计划，不修改文件
• -b, --backup：写入前创建 <target>.bak
• -o, --output <FILE>：输出到新文件，不直接修改目标文件

示例：

bt-patch auto-once ^
  -t partial.bin ^
  -p full.bin

从指定偏移开始扫描，并降低空洞阈值：

bt-patch auto-once ^
  -t partial.bin ^
  -p full.bin ^
  -s 1048576 ^
  -z 65536 ^
  -a 4096

批量修补全部唯一匹配空洞：

bt-patch auto-all ^
  -t partial.bin ^
  -p full.bin ^
  -b

仅预览修补计划：

bt-patch auto-all ^
  -t partial.bin ^
  -p full.bin ^
  -d

输出说明

标准输出会给出本次执行的结果报告，例如：

• 模式
• 目标文件与补丁源文件
• 扫描起始偏移
• 锚点大小
• 发现的空洞数量
• 每个空洞的偏移、长度、匹配状态、修补状态
• 最终汇总

其中偏移和长度会同时显示十进制和十六进制，例如：

目标偏移：1048576 (0x100000)
长度：4096 (0x1000) 字节

耗时步骤的进度信息会输出到 stderr，包括：

• 扫描空洞
• 扫描补丁锚点
• 复制字节
• 校验字节

这样既能看到进度，也不会污染主结果报告。

退出码

• 0：执行成功，且至少完成一次修补；或 dry-run 成功生成计划
• 1：执行完成，但没有可安全修补的空洞，或部分空洞失败导致结果为软失败
• 2：参数错误或致命 I/O 错误

安全策略

bt-patch 的默认策略是“宁可不修，也不误修”。

• 自动模式下，只有唯一匹配才允许写入
• 匹配歧义时直接跳过
• 不允许目标区间越界
• 不允许补丁源区间越界
• dry-run 不修改任何文件
• --output 可避免直接污染原文件
• --backup 可在原地写入前保留备份

建议流程：

1. 先使用 -d, --dry-run 预览计划
2. 如需保留原文件，使用 -b 或 -o
3. 对明确偏移的修补优先使用 manual
4. 对自动定位结果有疑问时，先缩小 --search-start 或调整 --anchor-size

参数调优建议

• 空洞很小：降低 --zero-threshold
• 目标文件前部缺失：保持后锚点可用，自动模式会尝试后锚点主定位
• 锚点太短导致误匹配：增大 --anchor-size
• 候选过多经常歧义：适当增大 --anchor-size，必要时缩小扫描范围
• 文件很大：优先设置合理的 --search-start，减少扫描时间

本地化

帮助信息、错误信息和结果报告会根据系统语言自动选择中文或英文。目前已提供：

• 中文
• 英文

你也可以直接查看命令帮助：

bt-patch --help
bt-patch manual --help
bt-patch auto-once --help
bt-patch auto-all --help

当前限制

• 只处理单文件修补
• 自动模式只把“连续零字节区间”视为候选空洞
• 不处理“内容错误但不是零”的损坏区间
• 不直接读取 .torrent 元数据做 piece 校验
• 自动模式当前不提供 --verify

开发与测试

格式化：

cargo fmt

测试：

cargo test --offline

发布构建：

cargo build --release --offline

许可证

MIT