两个月，四个AI智能体，878个测试，三个版本发布——这是开源Python框架Vestibule的诞生记。但真正让作者记住这段经历的，不是那些亮眼的数字，而是两个让他印象深刻的瞬间：AI发现了人类没发现的生产环境竞态条件，以及483个测试全部通过、框架却根本装不上的荒诞现实。

AI审AI：五轮设计迭代揪出真实竞态

打开网易新闻 查看精彩图片

Vestibule最棘手的组件是向量索引的按需创建——要保证多个worker并发时安全。这个设计被反复否决修改了五次，才进入编码阶段。第一轮评审时，负责审查的AI就发现了一个真实的生产环境竞态：当某个worker还在执行一次慢速索引创建（含重试约390秒）时，它的状态看起来已经过期（阈值默认300秒），于是等待中的worker会接管任务，最终导致两个worker创建同一个索引。

一个AI读另一个AI的设计，在代码还没写出来之前，就发现了默认配置下的生产环境竞态。这种"AI审AI"的协作方式，让作者第一次感受到流程本身的价值。

绿色测试的谎言：483个测试通过，pip install却失败

v0.2版本发布后，作者第一次以陌生人的视角运行快速上手脚本——结果翻车了。pip install直接失败，一个打包冲突让整个框架根本无法安装，而此时483个测试依然全绿。紧接着，一小时的实测又暴露了两个问题：一个从未在真实SDK上跑通的默认模型名，以及一个在缺少可选依赖时能拖垮整个包的import语句。

问题不在测试本身，而在于测试衡量了什么。这些测试证明的是代码与自身的一致性：同一工作目录、同样的模拟接缝。但没有任何测试去验证用户真实所处的世界：干净的机器、真实的安装、真实的SDK。测试通过和产品可用，原来是两个完全不同的命题。

修复不止于补丁：CI流程的持久改变

最终的修复不是那三个补丁，而是一个新的CI任务：每次PR都会构建一个干净的虚拟环境，执行真实安装，并运行快速上手脚本。三个bug全部被公开写进了发布说明——包括那个让框架完全无法安装的打包冲突。

这段经历留下的教训很直白：测试绿了不等于产品能跑。当代码只和自己对话，而从未和用户的世界对话时，再多的测试也只是自我安慰。

Vestibule到底解决什么问题

每个RAG教程都会讲解析、分块、嵌入。但没人讲第六个月会坏什么：重试导致分块重复、文档在管道中静默消失、一个团队的配置改动破坏另一个团队的索引、没人能回答"那篇文档到底进没进去"。

Vestibule就是这层缺失的中间件——四个契约，所有组件都插在这上面：

  • 统一的到达信封：每篇文档都通过同一个校验形状进入，ACL前置要求，而不是事后补丁。
  • 确定性身份：doc_id和chunk_id是其输入的纯函数。重试覆盖而非重复，重新摄入缩减后的文档不会留下孤儿分块。
  • 状态账本：每篇文档一行记录，一个合法的状态机，让"文档X在哪"成为可回答的问题。

这些设计背后，是作者用两个月时间换来的核心认知：AI能写出通过测试的代码，但只有人——或者一个足够好的流程——才能确保代码在真实世界里也能跑通。