代码历史与版本事实

TurboTune 的演进不是一次普通功能迭代，而是从算法原型到 API V2、WebUI、TaskManager、训练推理、发版链路、测试体系和 AI 约束体系的连续重构。 v0.1 不是最原始起点，而是接手时已经经历过一部分 V1 UI 与功能收敛后的 baseline；后续 tag 是围绕真实交付持续推进的架构和功能演进。

阶段角色速览

版本 Tag 时间线

项目功能引入：Tutorial 展示的 TurboTune 是什么

在进入 AI 开发复盘之前，需要先明确 TurboTune 到底是什么。它不是一个普通 WebUI，也不是一个单点训练脚本。 从 Tutorial 的产品定义看，TurboTune 是一个专业的 AI 交互标注训练平台：它把原始帧、交互式标注、快速反馈训练、Validation、部署和发版记录串成一个连续闭环。

Tutorial 中呈现的标准使用链路

四个产品工作区

为什么 Tutorial 对这次复盘重要

Tutorial 的意义不是“再做一个演示页面”，而是用可视化方式向别人解释 TurboTune 是什么、怎么用，以及完整产品链路为什么成立。 它要展示的是一条真实流程：创建项目、添加数据集、预览、推理、标注、训练、Validation、Deploy 和发版记录。

但 Tutorial 同时施加了几个非常强的工程约束：不能为了演示侵入正式 UI，不能把 tutorial 专属语义塞进正式后端，也不能维护一套与真实产品不一致的假界面。 正确做法是用独立 demo server 提供 mock backend，在独立运行态里模拟完整流程；前端继续驱动真实业务组件、真实 store、真实 client 和真实 `/api/v2` 契约。

这也解释了为什么 Tutorial 反过来证明了 API V2 的价值。只要 API、状态分层、数据模型和任务系统足够稳定， Tutorial 就可以用 mock backend 完整展现真实产品流程，而不需要改正式 UI 和正式后端；反过来，如果 API 不稳定，Tutorial 会被迫复刻第二套状态，最终变成另一个屎山入口。

UI 产品化演进：从研发工具到产品工作台

从代码可以看到，TurboTune 的 UI 变化不是单纯换皮，而是在不断回答一个产品问题： 我们到底是在做一个临时研发工具，还是一个能承载完整 AI 交互式训练闭环的产品工作台？ 从最终 UI 回看 v0.1，再看当前 UI，变化最明显的不是组件数量，而是产品链路、API 边界、后端职责和状态模型一起被重新组织了。

v0.1 的 UI：已经有产品雏形，但仍是研发式组织

v0.1 的前端结构集中在 MainApp.vue、project.vue、hammer.vue、magic.vue、model-zoo.vue、viewer.vue。 它已经具备 Project、Hammer、Magic、Model Zoo、Viewer 等产品入口，也有侧边栏、可拖拽宽度、SSE 连接、项目状态显示等能力。 这说明当时不是没有产品意识，而是产品形态还主要围绕“把功能放进页面”组织。

当前 UI：产品链路变成了布局和状态架构

当前 UI 已经演进为 MainLayout.vue 统一承载工作区，并拆分出 HeaderBar、ActivityBar、DynamicSidebar、ViewerContent、RightPanel、StatusBar 等稳定布局模块。 这不是简单组件拆分，而是产品逻辑被明确分区：

UI 变化背后的四条架构调整

从研发到产品：变化不是“更好看”，而是“更可交付”

最终 UI 展示出的产品链路，是 TurboTune 研发过程的结果：早期验证算法闭环，V1 把功能放到用户能点的地方，后续重构再把 UI、API、后端和状态统一到一个长期可交付的产品结构里。 这也是为什么这次复盘不能只讲“AI 写代码快不快”，而要讲 AI 在产品化工程里如何被约束。

角色与提交脉络

这次分享的重点不是给个人贴标签，而是把代码历史背后的工程演进讲清楚：谁在什么阶段解决了什么问题，为什么后面会从功能迭代转向架构治理。 从提交历史看，TurboTune 不是一开始就进入 V2 重构，而是先经历了算法闭环验证、V1 UI 与功能收敛、AI 快速堆功能、再到系统性重构。

Root 到 v0.1：原型验证与 V1 产品雏形

v0.1 之后：从功能增长转向架构治理

v0.1..HEAD 的差异达到 807 个文件、187319 行新增、30453 行删除。 这种规模说明后续不是修修补补，而是围绕 API、schema、task、runtime、SSE、前端 store、测试、文档和发版链路的系统性重构。

v0.5-beta.2 之后：从亲自重构到可复制交付

在架构完全稳定之前，我一开始预期承担的是工程化项目角色：把项目从原型和功能堆叠状态，推进到可维护、可测试、可协作的工程系统。 但随着 API V2、TaskManager、runtime、SSE、schema、docs 和测试体系逐步收口，角色也开始发生变化。

中后期，我逐渐从“主要亲自改核心架构的人”，转向“架构 reviewer 和产品经理”：一方面审核后续功能是否符合 API V2 设计、状态分层和 owner 边界；另一方面从产品经理视角判断哪些能力应该进入产品闭环，哪些只是局部研发便利。

这个变化从代码量和提交角色上也能看出来。v0.5-beta.2 -> HEAD 期间，我作为 author 的直接提交只有 6 次，但作为 committer 的提交有 28 次； 多条由陈栓、陈亚南、刘迎召完成的功能或修复，最终由我合入。Git 记录不能完整代表所有 review 讨论，但 author / committer 的差异已经能说明角色正在从“主要实现者”转向“reviewer、合入者和架构把关者”。

这个阶段开始验证“架构是否真的稳定到可以让非核心开发者介入”。刘迎召并不是作为“工程组代表”出现，而是我负责的工程组中第一批开始介入 TurboTune 开发的同学； 他参与 Model Zoo、画框模式、发版登录校验、数据集 meta 自动解析、缓存读取窗口滑动、前端卡死修复等功能，意义不只是补功能，而是验证 API V2、状态分层、docs 和 Skill 是否已经稳定到不依赖核心开发者本人也能交付。

这个判断成立后，后续才适合继续引入其他工程组同学，以及 AI 训练组的开发同学。此时项目治理的目标，不再只是“我能把架构改好”，而是“架构、文档、测试和 Skill 能让更多人和 AI 都在同一套边界里安全开发”。

四类贡献不是互相替代，而是阶段接力

Docs 架构演进

TurboTune 的文档演进，是这次 AI 开发实践里最重要的工程信号之一。 早期文档更多是给人看的说明，后期文档逐渐变成给 AI 和团队共同执行的架构约束。

v0.1 时：文档与代码边界仍然分散

在 v0.1，仓库里主要是 README.md、api/schemas/Readme.md、tests/README.md 和旧 doc/ 下的 project 说明。 API 入口仍是 api/server/endpoints/*，前端主要是 JS store，例如 src/stores/dataset.js、src/stores/project.js、src/lib/globalState.js。 这说明当时还没有一个统一的架构设计源来告诉 AI：哪些状态属于事实，哪些只是 UI 页面态，哪些路径不能继续扩张。

V2 重构后：docs 成为架构控制面

api_v2_design.md 的演进方向

从提交历史看，docs/api_v2_design.md 不是一次写完的文档，而是随着架构问题被发现、修复、收口而持续演进： 4 月初围绕 API V2、Pydantic、TaskManager、SSE 起步；4 月 13 日删除 API v1；4 月中下旬围绕 runtime、task architecture、main-process ownership、ProjectBundle、path resolution 等问题持续更新； 5 月到 6 月，功能开发中的 project_id/name、deploy meta、train status、simpleai、模型溯源等问题继续反哺设计文档。

唯一主设计文档为什么重要

AI 最怕的不是复杂，而是多个互相冲突的事实源。一个需求如果同时参考旧 doc/、旧 API endpoints、旧前端 store、临时 task 文档和口头共识， AI 会倾向于把所有东西都兼容下来，最终制造更多第二事实源。

因此最终必须明确：docs/api_v2_design.md 是核心唯一主设计文档。WebUI 设计文档可以指导布局和交互，TaskManager 文档可以指导通用调度， testing 文档可以指导验证，但涉及 API V2 契约、状态语义、恢复、前后端边界和当前偏差时，以 api_v2_design.md 为准。

三阶段演进

每个阶段沉淀出的 AI 工程方法

Git Log 与架构清创证据

这次复盘不能只靠主观感受，必须回到 git log。提交历史显示，TurboTune 的后续演进不是“继续堆功能”，而是先经历了一段高密度架构清创，再在稳定架构上重新恢复产品功能迭代。 前文已经建立 tag 节奏，这里只看提交主题、改动范围和 author / committer 变化如何证明架构治理发生过。

功能与架构演进鱼骨图

从 git log 看架构清创路径

关键清创提交：跨层旧事实源的一次性收口

Git log 里能看到多次 80+、100+ 文件级提交。这些不是普通功能迭代，而是对应跨层旧事实源的一次性手术式收口—— 每一次都同时触及 schema、API router、store、SSE、runtime、task system 和测试，把散落在各处的临时实现统一回正式契约。

第二阶段失控复盘

第二阶段的问题不能简单归因于开发者能力。真正的问题是 AI 使用方式和工程治理缺位。 AI 可以安全地翻译清晰想法，但当它被用来填补人的架构盲区时，会快速制造全局混乱。

野分支与分叉开发：问题不是有分支，而是没有小步快跑

每个开发者都会有自己的分支，这本身不是问题。真正的问题是：当团队不使用 git 小步快跑的理念时，分支会变成个人思路的无限延伸。 一个人本来在做 A 功能，过程中发现 B 有问题，于是顺手修 B；修 B 时又发现 C 不对，于是继续改 C。最后一个分支里混着 A、B、C 三类问题，提交历史无法解释，代码边界无法判断，也没有人能有效 review。

AI 会放大这个问题。因为 AI 很擅长在当前上下文里继续写下去，它会把“顺手修一下”变成跨 UI、store、API、后端、测试的连锁修改。 每一步看起来都有道理，但整体已经偏离原始目标。人最后面对的不是一个可审查的功能分支，而是一团夹杂需求、修复、重构、兼容和临时判断的混合差异。

关键决策复盘：从有限介入到全面重构

这一段是整个分享中最重要的决策复盘。它不是“我一开始判断错了”的故事，而是一个长期工程里很典型的过程： 基于业务逻辑做出合理的局部优化判断，随后被现实揭示出更深层的架构问题，最终必须从渐进优化转向清创式重构。

5.1 最初判断：基于业务逻辑的合理决策

我进入项目时，首先看到的是前端 UI 的混乱。最初的想法很简单：把 UI 重构好就够了，不打算主导一个完整的系统性重构。 这个判断并非轻率，而是基于对项目核心业务逻辑的理解。

TurboTune 的核心价值，是将传统离线训练转变为可持续正向反馈的训练体系。其中最关键的一环，就是通过画布和标注体系，实现“训练 -> 标注 -> 再训练 -> 再标注”的反馈闭环。 因此 UI 不是表层皮肤，而是这个闭环的人机交互核心。

5.2 现实揭露：短板不是 UI，而是地基

实际推进很快超出了我的预料。问题不在于 UI 写得不好，而在于底层架构混乱，让 AI 根本无法写出能支撑核心闭环的 UI。 API 从页面出发组织，而不是从数据边界和资源契约出发；数据结构不分离，状态 owner 不清晰，前端 store、后端 runtime、SSE 和 cache 互相制造第二事实源。

大模型看不懂这种混乱。基于混乱 API 生成的 UI，只会把页面问题、状态问题和接口问题继续叠加。UI 的混乱只是冰山露出水面的部分，水下是已经歪到无法支撑长期迭代的地基。

5.3 被迫转向：当渐进优化不可行时，只能做清创手术

这就是我从“有限介入”转向“全面重构”的临界点。继续做 UI 优化，看起来是最省力的路，但它无法解决结构性问题，只会让 AI 在错误地基上继续生成更多局部合理、全局冲突的代码。

因此，我被迫从一个本打算“有限介入”的修复者，变成必须主导系统性重构的人。这不是轻率地推倒重来，而是在渐进路径被证明不可行之后，被迫做出的理性选择。

5.4 教训：重构必须自底向上

当底层架构无法支撑上层业务闭环时，即使上层承载着最核心的用户交互，继续从表现层渐进优化也是徒劳的。 真正负责任的做法，是先把数据模型、API 契约、状态 owner 和任务系统边界重新立住，然后再让 AI 回到高效实现的位置。

第三阶段治理体系

1. 最终决策权

AI 可以给方案，团队可以讨论，但必须有人拥有最终决策权。长期工程不能靠谁的 AI 生成得快来决定方向。 人必须决定哪个文档是唯一设计源、哪个 API 是正式契约、哪个状态是 canonical source、哪些兼容逻辑要删除。

2. 核心设计文档唯一化

docs/api_v2_design.md 最终成为 TurboTune API V2 的唯一正式设计文档。 它统一定义资源边界、公开契约、主键生命周期、状态分层、ServiceContext、TaskManager、Reporter、缓存、恢复与 reconcile 的 owner。

3. 为 AI 写设计文档

AI 不怕文档长，怕文档不明确。文档必须明确回答：什么是事实源，谁是 owner，哪些路径禁止走，当前偏差在哪里，后续怎么收口。 这样的文档不是“给人看的说明”，而是“给 AI 执行的约束”。

4. Skill 固化

项目进一步把规则固化为 turbotune-v2-design-guardrails。它让 AI 每次进入 V2 链路时都先遵守同一套边界： 不把 trace_id 当业务主键，不让 SSE 成为 canonical state，不把 runtime 写回 projectStore，不手改生成的 TS schema，不把业务语义塞进 TaskManager。

5. 六层状态模型

6. Pydantic V2 + OpenAPI + TS 生成

后端 Pydantic schema 是源定义，前端 TypeScript 类型从这里生成，不手写维护。 define.py 管领域类型，api.py 管 request / response，runtime.py 管 runtime read model。 这让人、AI、前端、后端和 OpenAPI 都围绕同一份契约协作。

7. TaskManager 保持 generic

TaskManager 的正式目标是 generic scheduler / executor / store。它负责排队、调度、执行、取消和 GPU slot 分配，不承载项目、数据集、训练、推理这些业务语义。 业务语义放在 API V2 的 preparation、runner 和 completion 边界中。

AI 开发实践方法论

这次分享的目标不只是复盘 TurboTune，而是回答一个更通用的问题：在 AI 时代，如何用 AI 构建一个长期可持续迭代的大型复杂工程。 TurboTune 的结论是，AI 开发不是“把需求丢给 AI”，而是建立一套让 AI 只能在正确边界内高效工作的工程系统。

第一原则：AI 适合翻译清晰意图，不适合替人决定架构

第二原则：分层决定 AI 的自由度

第三原则：AI 开发闭环必须先于代码生成

第四原则：大型长期工程要把“个人能力”转成“系统能力”

前期可以依赖核心开发者强行把系统拉回正轨，但长期不能靠某个人永远盯住所有代码。 真正的工程化，是让新加入的人和 AI 都能通过同一套文档、契约、测试、MR 和 review 机制做出正确修改。 刘迎召开始介入功能开发的意义就在这里：当非核心开发者也能在既有架构和 Skill 约束下交付，说明架构治理开始具备可复制性。

代码 Review 新范式：看不过来时，看什么

AI 时代，传统逐行 review 会失效。一个 MR 可能修改几十个文件、几千行代码，如果人仍然试图逐行校对，就会变成“AI 的校对员”，而不是系统质量的负责人。 因此 review 的第一目标必须从“看代码写得怎么样”，转为“判断 AI 实现的是不是我们想要的系统意图”。

Review 的四个锚点

质量保障：AI 时代的战略核心

AI 时代，测试不是收尾动作，而是战略核心。AI 可以写大量代码，也可以写大量测试，但人必须定义哪些测试代表业务意义。

7.1 困境：数量失控、偏差和回归

7.2 策略一：分层测试 + 手写完整 Pipeline

核心 Pipeline 必须由人手写

TurboTune 的核心测试不是某个按钮返回 200，而是完整业务闭环： 创建项目，添加 dataset，baseline 推理，保存 annotation，labeled 结果失效并重新生成，启动训练，发布 epoch，trained validation 可查询，部署产物可追溯，服务重启后 runtime 能恢复。

7.3 策略二：FastAPI + OpenAPI 3.0 强一致

后端使用 FastAPI 和 Pydantic V2 后，OpenAPI 3.0 不只是文档，而是正式契约。它必须和代码保持强一致： 后端 schema 是源定义，前端 TS 类型从 schema 生成，接口测试基于同一份契约展开，review 也以 OpenAPI 变化作为锚点。

治理体系总览

核心经验

前瞻机制：Record、Insight 与 Skill 闭环

AI 工程不能只依赖当次对话。真正的长期价值，是把一次次开发中的事实、决策、坑、盲点和改进建议沉淀下来。 这里的 Record.md 和 Insight.md 不是拘泥于某个具体工具名，而是一套思路：前者建立项目长期记忆，后者帮助我发现自己都没有意识到的协作模式和问题。

Record 与 Insight 的核心区别

失效内容必须清理

长期记忆不是越多越好。AI 最怕多个互相冲突的事实源，因此 Record 和 Insight 机制必须包含清理动作： 已经废弃的 API、旧状态模型、临时 workaround、过期 prompt、被验证无效的测试策略，都要明确标记为失效或从主路径移除。

洞察 -> 行动 -> 沉淀 -> Skill

最终结论

TurboTune 的经验可以压缩成一句话：AI 可以极大提升代码产出速度，但长期工程的核心竞争力不是写得快，而是人能不能持续定义正确的边界、契约、测试和决策机制。

在 AI 时代，用 AI 构建长期工程，识别核心业务闭环当然重要。但更关键的是判断底层架构地基能否支撑这个闭环。 如果短板只是 UI，就聚焦 UI；如果短板是架构，就必须做清创式重构。

本文件为单 HTML 分享稿，可直接在浏览器打开。建议配合仓库中的 docs/api_v2_design.md、docs/testing.md、docs/system_architecture_overview.md 一起讲解。