iii 开源仓库 · 技术科普 · 2026-09

用 AI 做版本管理与功能迭代

一个真实存在的开源项目（iii，一个用 Rust 写的服务器引擎），把「让 AI 帮忙写代码、管版本、发新功能」这件事 做成了一条不出乱子的流水线。这篇文档用大白话讲清楚三件事：AI 为什么不会乱来、版本号到底是谁定的、 老功能和新功能分别怎么处理。所有故事都来自仓库里真实发生过的记录，每句话的出处可以在附录查到。

先建立一张对照表，后面所有内容都能在这张表里找到位置：

这家店最重要的家规是：真正需要动手写的东西只有三处，其余全部由机器自动生成、 自动检查、自动归档。用图表示：

让 AI 干活，最大的问题不是它不会，而是它不了解你家的规矩。 iii 的做法像给新员工发一套入职资料——而且「到了哪个岗位才发哪本」，不是把整个文件柜一次性倒给你。 （喂给 AI 的这些材料，行话叫「上下文」。）

员工守则的精髓：「必须 / 先问 / 绝不」三栏

AGENTS.md 把规矩分成三栏写。最值钱的是中间那栏「先问」—— 它把 AI 的自作主张变成提问：

# AGENTS.md（节选，实文 170 行）
### Always   （必须）用 pnpm 工具；提交前先跑格式化；接口路径写 /orders 这样的斜杠开头；
           定时任务的配置字段叫 expression；功能起名用 冒号冒号 分隔，如 orders::validate
### Ask First （先问）改对外发布的 SDK 接口；改服务器通信协议；改 CI 自动化；加新的引擎模块
### Never    （绝不）提交密钥；直接推送到主分支；改软件许可证

师傅的带教节奏：每一步都停下来给你看

第 1 步 · 计划     列出文件结构和章节 → 停下，等人点头
第 2 步 · 动手     一块一块写（一个完整章节算一块）
第 3 步 · 检查     每块写完停下："Review this section. Shall I proceed?"
第 4 步 · 提交     建议一条提交说明，格式 scope: 简短描述

很多人觉得「发版本」是件大事：要改版本号、要同步一堆配置文件、要把旧文档归档…… 漏一步就是事故。在 iii 这里，这些事全部由程序完成，人做的动作相当于打开 App、选好规格、下单。

3.1 什么是「版本列车」？

下面是 0.21 这趟车的真实发车记录（日期来自代码仓库的标签历史）：

3.2 版本号是谁定的？——收银机，不是店长

版本号不是人开会拍出来的，是一个小程序按死规矩算出来的。 程序开头注释写着「纯函数放在文件顶部，方便单元测试」——意思是这套规则像收银机算账一样死板， 而且给收银机本身配了体检（专门的测试代码）。

规矩一：说「接着编号」→ 当前班车继续 next.1 → next.2 → next.3，目的地不变
规矩二：说「转正」→ 试运行的号码直接变成正式版（next 班变 v0.21.4）
规矩三：alpha / beta / rc 是不同级别的试运行，发布到各平台时格式自动换算

3.3 发版按钮长什么样？

就像点外卖选规格，填四个选项，剩下的全自动：

按下按钮后的流程一句话：先检查新文档备齐没有（没备齐就发警报停止）→ 整理归档 → 打上版本标签 → 各平台自动上架。

3.4 换价签：一次换完所有门店

3.5 杂志社的归档制度

开新功能像研发新菜：看菜单（要做什么）、翻手册（基本功是什么）。 修老功能像照着老菜谱回锅：得先找到当年的菜谱（代码历史）、翻翻那期的杂志（当版文档）、 看看当时的卷首语（更新日志）。两类活要拿的资料完全不同，但写东西永远只写在一个地方——草稿区。

拿资料的方向，一句话记住

0.21 版本的主打功能——「让任何程序都能动态注册触发器」（可以理解为：给餐厅加了一个 「临时加菜窗口」，不用重启厨房）——从想法到用户手里，全过程都有记录。这个故事的价值在于： 它是整套机制的一次完整走位。

5.1 换到 AI 的视角：它的一天是怎么过的

下面的「剧本」是从 AI 的角度重演这一天。人输入的话在左边， 注释标出 AI 拿到了什么资料、产出了什么。读的时候数一数人一共说了几次「好，继续」—— 那几次就是人在拍板，也是整套机制里人不可替代的部分：

【第 1 轮 · 接活】
人：读一下需求文档 engine-register-trigger-metadata.md，
    把它做成引擎内置功能，四种语言的接口都要支持。
# AI 拿到：员工守则(自动) + 点菜单(需求) + 员工手册(基本功)
AI：给出实现计划——列出要动的文件，并主动标注：
    "这次要改通信协议，守则里写的是「先问」，需要你确认"
人：协议改动我评审过了，继续。                      ← 拍板 1

【第 2 轮 · 出图纸，等点头】
AI：文件结构清单 + 分块施工计划，停住
人：按这个做。                                    ← 拍板 2

【第 3 轮 · 一块一块做，每块停一次】
块 1  通信协议文件         新增消息类型 (+44 行)
块 2  核心功能文件         注册/注销/元数据透传 (+383 行)
块 3  四语言接口           Rust/Node/Python/Go 各自符合语言习惯的写法
                          （比如 Python 只在用户声明了参数时才多传一个参数）
每块做完 AI 都问一句 "这段可以吗？我继续下一块？"
人：（抽查关键块）可以。                           ← 拍板 3..N

【第 4 轮 · 写说明 + 重印小票】
AI：手写草稿区文档 → 跑工具重印 API 参考 → 刷新 AI 简版手册
护栏：本地提交检查先拦一遍格式问题

【第 5 轮 · 建议提交说明】
AI：建议写成 "feat: engine::register_trigger + first-class
    invocation metadata (#1928)"
    （格式约定 + 编号；提交、推送、开审核单都是人来按）
人：提交 → 审核单描述「改了什么/为什么」→ 门禁全绿 → 合入

【第 6 轮 · 发版（AI 完全不参与）】
人：打开发版按钮，选「小版本 + 转正 + 先演习一遍」
机器：检查文档备齐 → 归档轮转 → 换价签 → 贴版本标签

5.2 对照：修一个老功能，AI 拿的资料完全不同

人：0.20 版本里 RabbitMQ 消息队列的优先级功能，高并发时会丢优先级，修一下。
# AI 拿到：员工守则 + 代码历史(搜 "max_priority" 定位当年谁改的、怎么改的)
#          + 过刊库里 0.20 那期的杂志(当年对用户的承诺) + 那期卷首语
AI：只动队列相关代码和测试；
    修复说明写进草稿区（出现在下一期杂志上），过刊库一个字不碰；
    提交建议写成 "fix(queue): ..."

这套打法可以搬回你自己的项目，哪怕只是个人小项目。按下面的顺序做，每一步都很小。 时间紧就先做第 1、3、6 步——那是「最小可用组合」。

# AGENTS.md
## 常用命令        怎么构建、测试、格式化（写确切命令）
## 项目地图        哪个目录是干什么的（一张表）
## 规矩
### 必须    工具用哪个、命名怎么起（附范例）
### 先问    动对外接口 / 协议 / 自动化流程之前，必须先问我
### 绝不    提交密钥、直推主分支

直接可抄的提示词模板

模板里的 iii 词汇换成你项目的对应物（点菜单 → 你的需求文档；草稿区 → 你的文档目录）即可：

开发新功能时：
先读：员工守则（AGENTS.md）+ 这次的需求文档 + 相关的知识库页面
任务：按需求实现 <功能名>，含测试。
节奏：先给计划，停下等我确认 → 一块一块做，每块停下
      → 同步更新文档 → 最后建议一条提交说明。
红线：不动自动化流程、不动对外接口（要动先问我）；
      文档只写草稿区，不碰旧版归档。

修老功能时：
先查：代码历史（搜 "<关键词>"，找到当年谁改的、怎么改的）
      + 旧版本文档 + 对应的更新日志
任务：修复 <问题>。修复说明写进草稿区，旧归档只读。

发版前自检：
跑一遍和发版程序相同的检查命令        # 别靠感觉
重新生成自动文档，确认没有遗漏的改动   # 对不上=会亮红

这篇科普里的每个故事都能查证。以下是最初级版教程（进阶版）里的查证方法摘录：