Ohbin：解决 Python 生态中 GitHub 二进制工具管理的痛点

背景

在现代软件开发中，许多高效且轻量级的命令行工具（如 ripgrep、oasdiff 或各种 Rust 编写的 linter）往往只以 GitHub Release 的形式发布，而不提供传统的包管理器安装支持（如 PyPI、npm 或 Cargo）。

对于 Python 项目而言，这带来了一个长期存在的痛点：Python 无法直接安装这些非 Python 的二进制文件。 开发者通常面临两种尴尬的选择：

1. 手动分发：告诉每个团队成员“自己去安装它”，但这导致版本漂移、环境不一致，最终引发 CI（持续集成）构建失败。
2. 手写包装器：为每个工具编写一个包含下载、校验、缓存逻辑的 Python 包，并将其复制到每个仓库中。

这种做法不仅重复劳动巨大，而且维护成本极高。每一个新工具都需要一个新的包装包，包含平台特定的资产映射、SHA256 校验和复杂的下载逻辑。

Ohbin 的出现旨在消除这种繁琐。它作为一个基于 uv 的包装器，允许开发者在 pyproject.toml 中声明工具，实现“首次使用时自动获取、SHA256 校验、主机级缓存并执行”。只需一个开发依赖，即可管理任意数量的外部二进制工具。

核心内容

1. 传统方案 vs. Ohbin 方案

❌ 传统的手写包装器方案 为了安装一个工具（例如 ripgrep），开发者需要维护一个完整的 Python 包，代码量庞大且重复：

• 平台资产映射：需要手动为 Linux (x86_64/arm64) 和 macOS (x86_64/arm64) 编写资产 URL 和 SHA256 哈希值。
• 复杂逻辑：需要处理 urllib 下载、重定向、重试、并发锁 (flock)、校验和验证 (hashlib)、解压 (tarfile) 以及原子重命名。
• 配置冗余：每个工具都需要一个 wheel shim、[project.scripts] 入口以及 [tool.uv.sources] 条目，并在每个仓库中复制。

✅ Ohbin 方案 Ohbin 将复杂的工程逻辑抽象为一个通用的引擎，开发者只需在配置表中声明工具：

• 声明式配置：在 pyproject.toml 中通过 [tool.ohbin.tools.*] 定义工具来源、版本和二进制名称。
• 自动化管理：通过 uv run ohbin add 命令，自动解析 GitHub Release，匹配对应平台的资产，获取 SHA256 哈希，并写入配置。
• 极简依赖：只需添加一个 ohbin 作为 dev-dependency。

2. 为什么 uv 不能直接解决？

uv 本身无法直接安装任意 GitHub Release 的二进制文件，这并非设计疏忽，而是架构限制：

• uv run <name> 解析的是 Python 控制台脚本入口点（console-script entry point），这是静态轮子（wheel）元数据在构建时确定的。
• 没有钩子（hook）能读取配置表并动态生成命令。
• 因此，需要一个桥梁将“Release 页面上的二进制文件”连接到“venv 中的命令”。

Ohbin 选择了方案 (b)：一个通用的引擎读取清单（Manifest）。工具的具体细节（仓库、版本、平台资产、校验和）保留在配置表中，而由一个主要基于标准库的引擎统一处理下载、验证、缓存和执行。

3. 核心功能与工作流

添加公共工具

使用 uv run ohbin add 命令，指定 GitHub 仓库、版本、命令别名和二进制文件名：

uv run ohbin add BurntSushi/ripgrep --version 14.1.1 --name rg --binary rg

• 解析过程：Ohbin 会解析 BurntSushi/[email protected]，为每个平台（Linux x86_64, Linux aarch64, macOS x86_64, macOS arm64）下载资产并计算哈希（或通过 GitHub API 获取 digest）。
• 配置写入：将结果写入 pyproject.toml 中的 [tool.ohbin.tools.rg] 部分，保留注释和格式。
• 参数说明：
  • --name：设置命令名称（若与仓库名不同，如 ripgrep -> rg）。
  • --binary：设置压缩包内的可执行文件名。
  • 认证：优先使用 gh CLI（复用认证，避免速率限制），否则使用公共 REST API（支持 GH_TOKEN 或 GITHUB_TOKEN）。

运行与缓存

• 首次运行：uv run ohbin run rg -- --files 会触发下载 -> 验证 -> 缓存 -> 执行。
• 后续运行：直接从缓存执行，速度极快。
• 其他命令：
  • uv run ohbin which fd：打印缓存路径（如需则先下载）。
  • uv run ohbin list：列出已声明的工具及解析的平台。

配置发现

• 所有命令支持 --pyproject-file PATH 指定特定清单。
• 默认情况下，向上查找包含 [tool.ohbin] 的最近 pyproject.toml，或通过环境变量 $OHBIN_PYPROJECT 指定。
• add 和 add-gist 仅写入当前工作目录的 pyproject.toml。
• 每次运行都会打印解析到的 pyproject 真实路径，避免目标猜测错误。

进程替换与 CI 集成

ohbin run 使用 execv 替换当前进程，使工具完全拥有 stdin/stdout、信号处理和退出码。这使得它可以无缝替代 CI 和 Makefile 中的命令：

RG := uv run ohbin run rg --
search:; $(RG) TODO src/

4. 私有工具与加密 Gist

对于内部构建的工具、闭源 linter 或 vendored 二进制文件，Ohbin 提供了基于 GitHub Gist 的安全分发机制：

• 加密存储：将二进制文件通过 openssl AES-256-CBC 加密（PBKDF2 / 200k 迭代），Base64 编码后上传到 Gist。
• 链接门禁：Gist 设置为未列出（unlisted），不公开搜索。密码仅存储在私有仓库中。
• 安全性：泄露的链接本身无用，因为没有密码，字节数据是 AES 乱码。撤销访问只需删除 Gist 或轮换密码，无需密钥服务器。

操作流程：

1. 发布：

   uv run ohbin publish-gist ./dist/mytool --password "$PW"
   

   • 可针对特定平台发布（--platform linux-x86_64），并通过 --gist <id> 将多个平台添加到同一个 Gist。
2. 添加：

   uv run ohbin add-gist https://gist.github.com/you/ab12... --name mytool
   

   • 读取索引，锁定每个 blob 的不可变 raw_url 和密文 SHA256，写入 pyproject.toml 并标记 encrypted = true。
3. 运行：

   uv run ohbin run --password "$PW" mytool -- --help
   

   • 密码通过 --password 参数传入（在工具名之前），或通过清单中的 password 字段。
   • 安全注意：密码绝不接触 argv，而是通过文件描述符管道传递给 openssl。

5. 底层引擎特性

• 缓存机制：