Y Yuan Tools
2026/7/3

为什么我选择“总索引仓库 + 独立工具仓库”

我一开始想把所有工具像目录一样放在 yuan-tools 下面，后来确认更适合的结构是一个总索引仓库加多个独立工具仓库。

为什么我选择“总索引仓库 + 独立工具仓库”

06 repository strategy

在发布第一个小工具时，我遇到过一个很自然的问题：既然本地所有工具都放在 D:\dev\yuan-tools 下，GitHub 上能不能也做成类似目录的结构？

我最开始想象的是：

github.com/yuan0727/yuan-tools/yuan-image-redactor

也就是说，yuan-tools 像一个总目录，下面再放每个工具。

后来梳理之后，我理解了 GitHub 的基本结构：仓库地址通常是两级。

github.com/用户名/仓库名

所以真正的独立仓库应该是：

github.com/yuan0727/yuan-tools
github.com/yuan0727/yuan-image-redactor

这件事看起来只是路径问题，但它会影响后续所有工具的发布和维护方式。

几种可选方案

我当时大概有四种选择。

第一种是单仓库目录结构。所有工具都放在 yuan-tools 仓库下面，每个工具是一个普通文件夹。这样最像本地目录，但问题是所有工具会共用同一个仓库、同一套 tag 和 Release。工具变多之后，版本会很混乱。

第二种是 Git submodule。总仓库里可以出现一个工具入口，但它实际指向另一个独立仓库。这个方案能保留独立仓库，也能在总仓库里看到目录入口，但对普通用户来说，clone 和维护都多了一层理解成本。

第三种是 Git subtree。它可以把独立仓库内容同步进总仓库的某个目录。用户 clone 总仓库时能直接拿到代码，但代码会被复制进总仓库，后续同步和维护更麻烦。

第四种就是我最终选择的方案：总索引仓库 + 每个工具独立仓库。

最终结构

最终我把 yuan-tools 定位成总索引仓库。

它不存放所有工具源码，只维护公开工具列表和入口链接。

flowchart TD
  A["yuan0727/yuan-tools<br/>总索引仓库"] --> B["yuan-image-redactor<br/>图片打码工具"]
  A --> C["未来工具 A"]
  A --> D["未来工具 B"]
  B --> E["v0.1.0 GitHub Release"]

现在已经存在的两个仓库是：

https://github.com/yuan0727/yuan-tools
https://github.com/yuan0727/yuan-image-redactor

yuan-tools 的公开内容保持很干净，目前只发布 README.md。里面的工具列表只包含已经公开发布的工具。

yuan-image-redactor 则是图片打码工具自己的源码仓库，有自己的 README、工具使用说明、tag 和 Release。

为什么这样更适合长期做很多工具

如果以后我做几十个小工具，每个工具都会有自己的生命周期。

有的工具可能只是修一个小 bug，从 v0.1.0 到 v0.1.1。有的工具可能增加明显功能，从 v0.1.0 到 v0.2.0。也有的工具可能很久不更新，但仍然可以下载旧版本。

如果所有工具都混在一个仓库里，版本管理会越来越难解释。到底 v0.2.0 是哪个工具的版本？Release 里应该放哪些 EXE？README 该怎么组织？这些问题都会堆在一起。

独立仓库就清楚得多：

  • 每个工具有自己的源码。
  • 每个工具有自己的 issue 和后续计划。
  • 每个工具有自己的 tag。
  • 每个工具有自己的 GitHub Release。
  • 总索引只负责把它们串起来。

这和我想做的“很多很多小工具”更匹配。

总索引仓库的角色

yuan-tools 更像一个作品集入口，而不是代码仓库合集。

它的 README 只需要维护三类信息：

项目名称中文名称工具使用说明
yuan-image-redactor图片打码工具指向工具仓库里的说明文档

这样对外很清楚。用户想看工具列表，就进 yuan-tools；想看某个工具的源码和下载文件，就点进对应工具仓库。

这个结构也更适合个人品牌展示。总索引是“我做过哪些工具”，独立仓库是“这个工具具体怎么实现和发布”。

小结

这次我没有选择把所有源码塞进一个大仓库，也没有使用 submodule 或 subtree。

最终方案虽然看起来更“分散”，但长期更干净：

yuan-tools              负责索引
yuan-image-redactor     负责图片打码工具
未来的 yuan-* 仓库       各自负责自己的工具

对一个长期小工具计划来说，干净的结构比一开始看起来像目录更重要。

第一个工具发布后，我对这个选择更有信心。它让开发、发布、写文章和后续维护都变得更清楚。