beyond-local-file v0.3.0 发布：配置自由，反向链接，一键升级

大家好！beyond-local-file v0.3.0 来了！这次更新可以说是一次”体验升级”——解决了几个一直以来让我（相信也让你）觉得不太顺手的痛点。话不多说，直接上干货！

背景：配置的困境

用过 blf 的朋友可能都遇到过这个问题：每次运行命令都得在项目目录下，或者手动指定 --config 参数。想同时管理个人和公司项目？抱歉，要么来回切换目录，要么每次都得敲一大串路径。

这种体验，怎么说呢，就像是你出门旅游，每次都得带个巨大的行李箱，里面装着所有可能用到的东西——不是不行，但真的很累。

好了，言归正传。v0.3.0 解决了这个问题，而且不止这一个问题。

核心基石：.blfrc 配置支持

动机

之前 blf 只能从当前目录的 config.yml 加载配置，或者每次都要手动指定 --config 参数。这限制了灵活性——用户想同时管理个人和公司项目，或者不想被目录结构束缚。

价值

现在可以在 ~/.blfrc 中指定一个或多个配置文件，支持绝对路径、波浪号路径和相对路径。多配置文件会自动合并，并进行冲突检测（基于管理项目的绝对路径，而非项目名称）。

简单来说，blf 可以从任何目录运行，不用再手动指定配置文件。

用法示例

在你的 home 目录下创建 .blfrc 文件：

1
2
3
4

# ~/.blfrc
config_file:
  - ~/personal/config.yml
  - ~/company/config.yml

配置文件合并时，相同绝对路径的项目会被视为冲突，工具会给出明确的提示。这样可以避免不小心覆盖了重要的配置。

核心功能：revlink 反向链接命令

场景引入

有了 .blfrc 的自由，revlink 才有了存在的意义。因为 revlink 需要从目标项目目录运行，把当前工作目录的文件转换为管理链接。如果没有 .blfrc，你只能在管理文件目录下操作，revlink 根本无法使用。

话外音：这也是为什么 .blfrc 是这个版本的核心基石——它解锁了后续一系列新功能的可能性。

假设你已经有一个项目，里面有一些文件想开始用 blf 管理。之前的流程是：

1. 手动复制文件到管理位置
2. 删除原文件
3. 运行同步命令创建符号链接

这个过程不仅繁琐，而且容易出错——复制错了、删错了，都是泪。

revlink create：一键转换

blf revlink create <path> 命令可以一键将现有文件/目录转换为管理符号链接。

采用”复制-校验-替换”的方式：

1. 先计算 MD5 校验和
2. 复制到管理位置
3. 验证完整性后再替换为符号链接
4. 自动添加到 .git/info/exclude 和配置的 subpath 列表中

1
2
3
4
5
6
7
8
9
10
11

# 将 .kiro/hooks 转换为管理链接
blf revlink create .kiro/hooks

# 转换单个文件
blf revlink create .kiro/settings/mcp.json

# 预览操作，不实际执行
blf revlink create .kiro/hooks --dry-run

# 强制覆盖已存在的管理副本（慎用）
blf revlink create .kiro/hooks --force

整个过程是原子性的——如果中间任何一步失败，都会回滚，保证数据安全。--dry-run 是个很实用的选项，可以先看看要做什么，确认无误后再执行。

revlink restore：精确逆操作

有了创建，必然需要恢复。blf revlink restore <path> 是 create 的精确逆操作：

1. 验证符号链接指向有效目标
2. 将管理文件复制回原位置
3. MD5 校验确保完整性
4. 删除管理副本
5. 清理 .git/info/exclude 和配置条目

1
2
3
4
5

# 恢复 .kiro/hooks 为真实文件
blf revlink restore .kiro/hooks

# 预览操作，不实际执行
blf revlink restore .kiro/hooks --dry-run

restore 同样支持 --dry-run 选项，让你在执行前确认操作。如果 MD5 不匹配（比如目标文件被修改过），工具会自动清理并中止，不会覆盖你的修改。

一键升级：upgrade 子命令

动机

用户常常不记得自己是通过 uv tool 还是 pipx 安装的工具，升级时需要查文档确认命令。我自己就经常遇到这个问题——装完之后隔了几个月想升级，完全忘了当初用的什么命令。

价值

blf upgrade 自动检测安装方式（从 sys.executable 的路径特征判断），然后运行正确的升级命令。支持 --dry-run 预览操作。

1
2
3
4
5

# 自动检测并升级
blf upgrade

# 预览要执行的命令，不实际运行
blf upgrade --dry-run

话外音：这个功能实现起来其实挺有意思的，通过解析 Python 可执行文件的路径来判断安装方式。比如 /Users/xxx/.local/share/uv/... 就是 uv，/Users/xxx/.local/pipx/... 就是 pipx。

可用性改进：CLI 补全支持

管理多个项目时，手动输入项目名称容易出错且效率低。现在 Shell 自动补全支持项目名称了！

在 blf link check 和 blf link sync 命令中按 Tab 键就能看到可用项目列表，支持 bash、zsh 和 fish。

1
2
3

# 按 Tab 键会自动列出所有项目
blf link sync pro<Tab>
# 可能补全为 project-a、project-b 等

代码质量：润物细无声

这次还做了一些内部重构：

1. 枚举迁移：将 SyncStatus 枚举从 options.py 移到 sync_state.py，让 options.py 只包含用户可见的 CLI 选项枚举
2. 命名结果类：将 load_config_projects 的返回类型从匿名 tuple[dict, Path] 改为命名的 ConfigLoadResult 数据类，消除了三处调用点中脆弱的文件名重建逻辑

这些改动用户看不到，但代码更清晰了，以后维护起来也更方便。

言而总之

v0.3.0 版本的核心价值在于：

希望这能够给你带来一些不同的体验！

GitHub Repo:
https://github.com/xingyuli/beyond-local-file

Full Release Notes of v0.3.0:
https://github.com/xingyuli/beyond-local-file/releases/tag/v0.3.0

预告

关于 mcp server 的一点点偏门经验，应该不会等待太久。So, let’s see!