项目代号aa---(13)：第13版重构实录与减法工程思想

接到不少新项目时，我的习惯是先看代号，再看文档。说实话，很多项目正文写得稀里糊涂，真正有价值的信息往往藏在命名和版本号里。就拿最近在整理的aa---(13)来说，乍一看像乱码，仔细拆开却是一套完整的工作流痕迹：项目代号是aa，三个横线表示这是跨版本大改后的稳定分支，括号里的13则是第十三轮实质迭代。这比任何项目简介都诚实。

这篇内容从一个真实存在的个人实战项目出发，讲清楚代号背后的设计思路、第13版到底改了些什么、以及我在这次迭代里踩过和填平的坑。如果你也在维护一个长期项目，正被“要不要推倒重构”“依赖该留多少”“版本号怎么编”这些问题卡住，这篇应该能给你一些可以直接抄作业的参考答案。

1. 先从代号说起：aa---(13)到底是什么意思

1.1 命名不是随手打的，是一套排序规则

很多个人项目写着写着，目录里就会出现final_v2、真·最终版、改动3这类命名，三个月后再看根本分不清哪个是最新版。我早期也吃过这种亏，后来定了一套规则：短前缀 + 分隔符 + 大版本号。

• aa取的是项目主题的首字母缩写，方便在文件管理器里按字母排序，一屏之内就能定位到所有相关文件；
• ---不是随手敲的横线，它代表“合并了多个小版本之后的跨版本快照”，相当于告诉未来的自己：这个目录状态是经过整合的，不是临时改的；
• (13)是真正的大版本计数，每完成一轮有交付物的迭代就加一。

这套规则看起来没什么技术含量，但实际用起来非常省心。比如我给某高校实验室维护内容归档工具时，文件名一律用这种短前缀加版本号的方式，半年下来几十个文件，排序、检索、回滚都是秒级完成，不用打开文档看内容就能知道哪个是最新版。

1.2 为什么是 13：版本迭代里的“压力拐点”

数字 13 在版本记录里其实挺特殊。前 10 版往往是功能堆积期，什么功能都想往里塞；到第 11、12 版开始意识到问题；第 13 版通常是一个转折点——要么是重构，要么是砍功能，要么是彻底换思路。

我之前在做一个跨平台的小工具时，维护过一个长期迭代的开源镜像站，跑到 13 版的时候，东西还能跑，但构建时间从 40 秒涨到了 5 分多钟，依赖数量翻了将近三倍，我已经开始记不清某个功能到底是为谁加的。这种时候，继续往上堆版本已经没有意义，必须停下来做一次彻底的减法。

aa---(13)这个项目，就是在类似的压力拐点上诞生的：不是要加新功能，而是要把整个项目拉回“可维护、可解释、可交付”的状态。

2. 项目整体设计与思路拆解：减法优先，克制比堆料难

2.1 核心定位：一个内容发布实验台

这个代号为aa的项目，本质是一条个人用的轻量级内容发布工作流：从本地的 Markdown 草稿出发，经过模板渲染、脚本构建，最终产出一个静态页面，方便随时归档和分享。它不追求复杂，不追求功能丰富，核心目标只有一个——在任何一台电脑上，三条命令内完成从草稿到发布的全过程。

这也是为什么我把重构作为第 13 版的核心策略。旧版为了满足各种场景，引入了完整的构建框架，甚至接了一个前端渲染流程，听上去很专业，实际体验却非常糟糕：每次发布要手动装依赖、调配置、处理路径差异，光准备环境就要花超过 10 分钟。轻量级内容发布工具本来应该像“开灯”一样简单，硬是被做成了“启动一台发电机”。

2.2 方案选型：为什么要大幅削减依赖

第 13 版里，我做了一个相对激进的决定：把所有运行时依赖压缩到只剩一个最新的稳定脚本环境，其余能力全部用标准工具链代替。也就是说，模板渲染、文件监听、打包压缩这些环节，全部从“引入外部库”改成“自己写几十行脚本”。

选择这条路的主要原因是：外部依赖的维护成本在长期迭代中会吞噬掉它带来的便利。一个能力库如果三个月不更新，就可能和新的运行环境产生摩擦；如果两年不更新，基本就变成项目里的一颗定时炸弹。个人项目不像团队项目有专人维护依赖，能用标准能力解决的，绝对不引第三方库，这是我用几年踩坑换来的原则。

你可以把这时候的aa---(13)理解为一次“内容工厂”的流水线改造：不再采购各种昂贵且不好用的机器，而是把现有工具重新排列，只保留最小必要环节，让每篇文章都能走同一条稳定路径完成生产。这个逻辑放在很多长期项目上其实是通用的——完成比完善重要，稳定交付比什么都能做重要。

2.3 旧版遗留了什么，新版又丢掉了什么

在动工之前，我先花了一整个下午盘点旧版的功能清单。最终保留的能力只有四个：草稿写入、格式转换、页面生成、本地预览。至于多用户权限、云端同步、实时协作这些听起来很厉害、实际一年都用不了一两次的能力，全部在重构中被移除。

具体过程里最难的不是删代码，而是确认“这些功能真的不会被需要”。我的判断标准是：如果这个功能在过去三个版本里都没有被主动打开过三次以上，就说明它在现实中并没有被依赖。与其放着让项目显得臃肿，不如大方地去掉，谁需要的时候再通过版本管理找回旧代码就好，这就是留好版本号的意义。

3. 实操过程与核心环节实现：从零重构一条内容流水线

3.1 盘点现状：先搞清旧版到底慢在哪里

如果要给重构项目一个最值得强调的建议，那就是“先不要动手改代码，先把旧行为摸清楚”。我在旧版项目里记录了整个发布流程的耗时分布，数据整理成了一张表：

这张表一出来，优化方向可以说一目了然，95% 以上的等待时间都花在环境准备上，而不是真正的处理环节。与其在渲染引擎上调优，不如直接换一条更简单的路径。

3.2 重写发布主流程：三条命令走完

重构后，整个发布流程被我压缩成三个阶段，对应三条命令：init、build、preview。

# 第一步：初始化环境，建立草稿目录与输出目录 aa init --project my-notes # 第二步：构建静态页面，将草稿渲染为最终产物 aa build --input ./drafts --output ./public # 第三步：本地预览已生成页面，确认无误后发布 aa preview --port 8080

三个命令背后的脚本逻辑非常简单，加起来大约 150 行。init只做两件事：创建目录结构，写一份初始配置；build读取配置，遍历草稿目录，把 Markdown 内容按约定模板包裹后输出到公开目录；preview则启动一个本地静态服务，让人能直接在浏览器里验收成果。

这种做法在一次完整发布流程上，从旧版的十几分钟直接压缩到不到 10 秒。可能有人会说这没什么技术含量，但作为干活的人，这种“技术含量低但节省了大量时间”的方案才最有实际价值。

3.3 让输出结果可追溯：构建时的关键参数记录

重构完成后，我在构建脚本里加了一个平时容易忽略的能力：生成构建报告。每次执行build，脚本会把时间、输入文件数量、输出文件大小、耗时、脚本版本号这五个关键参数写进一个report.txt，随页面一起放在输出目录下。

时间 : 2025-05-15 14:32:07 输入文件 : 12 个草稿 输出文件 : 12 个页面 + 1 个索引 总耗时 : 1.42 秒 脚本版本 : aa---(13)

熟悉发布流程的朋友肯定一眼就能看出这个设计的好处：当输出内容出现异常时，不需要猜是内容问题、脚本问题还是环境问题，直接看report.txt就知道这次构建的运行环境是什么、用了哪个版本的脚本、做到什么程度。这也是我在前几次版本里踩过的坑——内容输出错了，却因为不知道当时的构建环境，排查了两个小时。

3.4 模板设计的取舍：最笨的办法往往最省心

第 13 版的模板系统，我也做了大幅简化。旧版支持主题嵌套、多级继承、动态布局，听起来很强大，实际用起来每次调整样式都要翻三层目录。新版直接改成“一个 HTML 模板 + 一段替换逻辑”，模板里只有三个占位符：标题、正文、日期。

<!DOCTYPE html> <html> <head><title>{{title}}</title></head> <body> <h1>{{title}}</h1> <div>{{content}}</div> <span>{{date}}</span> </body> </html>

替换逻辑就更直接了，读文件、字符串替换、写文件，用最标准的脚本能力就能完成，不需要任何外部模板引擎。很多刚接触轻量级项目的人可能会觉得这种写法太简单、不够“工程化”，但从维护角度看，一个能看懂全部逻辑、五分钟内能改完样式的模板系统，远比一个功能强大但半年后自己都未必看得懂的模板框架更实用。

4. 常见问题与排查技巧实录：重构中踩过的坑

4.1 过度精简带来的功能缺失

第 13 版刚做完时，我一度非常得意，整个代码仓库干净得发亮，文件数量少了一半还多。结果用到第二周就发现问题了：旧版里有个不起眼的细节，会自动把草稿中的图片复制到输出目录并改写路径，而新版因为追求“只做最核心的三件事”，把这个环节漏掉了。发布出来的页面文字正常，图片却全是裂图。

这是所有重构项目都会有的通病：砍功能的时候看什么都觉得没用，切到真实使用场景才发现每个功能背后都有人需要。这次之后我养成了一个习惯：重构前把旧版输出结果完整留档，重构后拿同一份输入数据跑一遍新流程，逐项对比产物差异，而不是只盯着“构建成功”就以为大功告成。

4.2 脚本环境漂移问题

第 13 版把依赖压缩到只剩最新的标准运行环境，理论上只要是用近两年内的环境，都能正常运行。但实际换了一台旧设备后还是出问题了：脚本里用到了一个较新的字符串处理能力，在老版本环境上不支持，结果直接报错退出。

这里要说一个经验：精简依赖不等于彻底和版本绝缘。如果项目面向多环境运行，建议在脚本开头加一段能力检测，不满足条件时直接给出清晰的中文提示是哪一步不对，而不是让使用者直面一次看不懂的报错。这个做法花不了几行代码，却能把“使用者手足无措”变成“照着提示就能解决”。

4.3 版本管理规范：为什么必须留好旧版本

重构顺利完成后，最容易掉进的坑是“立刻删掉旧版代码”。我个人的底线是：旧版可以不在主分支，但不能彻底消失。

当时的做法是给旧版打了一个完整的版本标签，存着旧版所有源码和一份简短的说明，写清楚“这是上一版实现，核心差异在哪，如果要找回 xxx 功能，参考这里”。后来真的有需要恢复一个旧行为场景时，只花了几分钟就在标签里找到了答案。版本号这种事，平时感觉不到它的意义，一旦要回溯历史的时候才知道它有多值钱。

4.4 常见问题速查表

整理了一下这次重构过程中最容易被其他人问到的几个问题和排查路径，可以直接作为参考：

4.5 独立维护项目时的复盘节奏

这次aa---(13)能顺利落地，除了技术上做对了一些决定之外，还有一个容易被忽略的细节：过程节奏控制得很稳。我没有想着一口气全部推翻重写，而是分了三步走——先盘点旧版功能，再写新的核心流程，最后跑通新旧对比验证。每一步都保证了项目处于可用状态，随时可以停下来也不会造成损失。

个人维护长期项目时，最容易犯的错误就是“毕其功于一役”，总想找一个完整的时间段把活全干完。实际上小型项目不像团队项目有那么完整的排期和测试条件，留给个人项目的时间往往是碎片化的。把重构拆成多个可独立交付的小阶段，每个阶段都有明确产出，反而是最稳妥的节奏。

5. 重构之后：这套方案的适用范围与实际收益

做这个项目的过程中，我反复被问到一个问题：把项目重写这么简单，是不是意味着旧版选型一开始就错了？倒也不是。技术选型没有绝对的对错，只有适合的阶段。旧版的复杂设计可能在某个特定阶段确实提供了便利，只是当项目目标和场景发生变化后，旧设计带来的维护成本超过了它的收益，这时候就需要果断做减法。

这套“代号管理 + 减法重构 + 构建留痕”的思路，后来被我迁移到了好几个地方，包括给团队做的内部自动化脚本、个人的备份工具、甚至一些非技术类的归档项目。底层逻辑都一样：一个长期维护的项目，最重要的不是功能多，而是状态清晰、每一步都解释得了、出问题时能快速定位。

另外关于脚本本身，我在第 13 版中实践下来的体会是：对于个人使用或小团队使用的工具，技术方案的“可解释性”远比“复杂度”重要。如果一份脚本今天能跑，但三个月后没人能说清它为什么要这样写，那它就已经开始制造债务了。

最后再分享一个细节技巧：脚本和文档尽量放在同一个目录下，命名保持和版本号一致。这次aa---(13)的脚本目录里就同时放着源代码、构建报告模板、以及一页纸的操作说明。任何人打开目录，即使完全不熟悉这个项目，也能在五分钟内搞清楚它是干什么的、怎么启动、出错了看哪里。把项目当成给未来自己看的产品来做，维护体验会完全不一样。