beyond-local-file v0.2.0 新功能速递

四月 06, 2026

大家好！最近给 beyond-local-file 工具做了一些小更新，解决了使用过程中遇到的几个实际问题。今天就来跟大家聊聊 v0.2.0 版本带来的两个实用新功能。

背景：那些 symlink 解决不了的问题

在使用 beyond-local-file 的过程中，我发现了两个场景，原有的功能无法支持：

目录结构不匹配：当 managed project 中的文件需要链接到 target project 的子目录时，直接链接整个目录会覆盖 target project 中已有的内容
工具不识别 symlink：有些工具（比如 Kiro）不识别 symlink 文件，导致功能失效

针对这两个问题，v0.2.0 版本带来了两个新功能，Let’s see！

功能一：Subpath Mapping

解决了什么问题？

想象一下这个场景：你的 managed project 中有一个 .kiro/hooks 目录，你想把它链接到 target project 的 .kiro/hooks 目录。但是 target project 已经有了 .kiro/steering/guide.md 文件，并且这个文件已经提交到了 Git 仓库。

如果直接链接整个 .kiro 目录，就会覆盖掉 target project 中已有的 steering 目录，这显然不是我想要的结果。

如何使用？

现在，你可以在配置文件中使用 subpath 来指定具体的子路径：

project-a:
  target: /Users/username/workspace/project-a
  subpath:
    - .kiro/hooks
    - .kiro/settings/mcp.json

这样，工具会创建：

symlink：project-a/.kiro/hooks → managed/project-a/.kiro/hooks
symlink：project-a/.kiro/settings/mcp.json → managed/project-a/.kiro/settings/mcp.json

而不会影响 target project 中已有的其他内容，是不是很灵活？

功能二：Single File Copy

解决了什么问题？

有些工具就是不买 symlink 的账，比如 Kiro 就要求 steering 文件必须是物理文件，而不是 symlink。当这些文件以 symlink 存在时，Kiro 会默默地忽略它们，导致工作流中断。

如何使用？

为了解决这个问题，我新增了 Single File Copy 功能。你可以在配置中指定某些文件作为 copy，而不是 symlink：

project-a:
  target: /Users/username/workspace/project-a
  subpath:
    - .kiro/hooks
    - path: .kiro/steering/guide.md
      copy: true

这样，.kiro/steering/guide.md 会被 copy 到 target project 中，而不是创建 symlink，确保 Kiro 等工具能够正常识别它。

写在最后

这两个新功能让 beyond-local-file 变得更加灵活和强大，能够适应更多实际场景。无论是需要精细控制链接路径，还是应对不支持 symlink 的工具，现在都有了更好的解决方案。

如果你对这个工具有兴趣，欢迎尝试使用。

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

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

查看评论