20 万行代码：我们如何构建和维护大规模 AI 原型系统

项目简介

在三个月的时间里，我们从零开始搭建了一个包含 20 万行代码的 AI 原型系统。这是一个非常庞大的项目，就像建造一座大楼一样，需要科学的规划和管理。为了让这个系统易于维护和扩展，我们采用了一种叫做 monorepo（单一代码仓库）的项目管理方式，并特别注重可复用工具包的设计。这篇文档将用通俗易懂的语言，为大家介绍这个项目是如何组织和管理的。

什么是 monorepo？

monorepo 就像是一个巨大的收纳箱，我们把项目中所有的代码都整整齐齐地放在这个箱子里。想象一下你有很多玩具，如果把它们随意放在房间的各个角落，找起来会很麻烦。但如果你有一个大收纳箱，给每个玩具都安排一个固定的位置，那么无论是找玩具还是收拾玩具都会变得很容易。

monorepo 的好处有：

1. 代码共享更方便：就像全家人共用一个工具箱，需要用工具的时候直接去工具箱里拿就行了
2. 版本管理更统一：就像统一采购文具，避免每个人买的东西不一样导致混乱
3. 团队协作更顺畅：就像在同一个工作室工作，大家可以随时交流和互相帮助

项目是如何组织的？

我们的项目就像一个精心设计的大楼，每一层都有它特定的功能：

one-prototype/
├── apps/                 # 各个独立应用的代码
│   ├── base/            # 独立的产品，包含服务部署、云实例等
│   ├── course/          # 高校场景相关的独立产品
│   ├── docs/            # UI 组件的文档
│   ├── idcloud/         # IDC 相关的独立产品
│   └── web/             # 独立的测试网页应用
├── packages/            # 可以共享的代码包
│   ├── eslint-config/   # 代码规范配置
│   ├── hooks/           # React 钩子函数
│   ├── request/         # 网络请求工具
│   ├── track/           # 用户行为跟踪工具
│   ├── typescript-config/# TypeScript 配置
│   ├── ui/              # 通用界面组件
│   └── zod/             # 数据验证工具

共享工具包详解

在 packages 目录下，我们精心打造了一系列可复用的工具包，它们就像是一个个专业的工具箱，每个工具箱都有其特定的用途。让我们深入了解这些工具包的特点和作用。

UI 组件库：标准化装修工具包

就像建筑工地的标准化部件，我们的 UI 组件库提供了一套完整的界面解决方案。它基于 Tailwind CSS 实现灵活的样式定制，采用 TypeScript 确保类型安全，并遵循 Radix UI 的无障碍设计原则。组件的高度可配置性使其能够支持多种场景的复用。

在开发效率方面，UI 组件库通过统一的设计语言和交互模式，为开发者提供了完善的组件文档和使用示例。快速的开发调试和主题预览功能，加上跨产品的复用能力，大大减少了重复开发的工作量。标准化的组件接口设计也让集成变得异常简单。

我们的文档系统基于 Storybook 构建，提供了交互式的组件展示和调试环境。开发者可以实时预览组件的外观和行为，动态修改组件属性，并在多种设备和主题下进行预览。规范的文档编写流程确保了组件用法、API 说明和最佳实践的完整记录。这种高效的开发工作流让组件的独立开发和测试变得轻松自如。

Zod 数据验证工具包：数据检验员

作为项目中的数据质检员，Zod 数据验证工具包严格把控着数据的格式和类型。它不仅能确保数据的正确性和安全性，还提供了强大的类型推导功能。特别是在与 React Hook Form 配合使用时，它能提供类型安全的表单验证，自动推导表单字段类型，在运行时确保数据安全，并提供友好的错误提示。

用户行为跟踪工具包：数据记录员

track 工具包就像是一个细心的记录员，它统一封装了多个主流的数据统计服务，包括 Umami、百度统计和 Microsoft Clarity 等。通过标准化的事件跟踪方法和自动的页面访问统计，它为产品提供了全面的数据分析能力。

这个工具包的一大特色是其多平台数据统计集成能力。它不仅支持开源的 Umami 统计，还能无缝对接百度统计服务和 Microsoft Clarity。开发者可以根据具体场景灵活切换不同的统计服务。在使用体验上，完善的 TypeScript 类型支持、自动的错误处理机制和丰富的调试信息，都让数据追踪变得轻松而可靠。

代码质量保障工具包：ESLint 和 TypeScript 的完美配合

就像建筑工地需要全方位的质量保障体系，我们的代码质量保障工具包通过 ESLint 和 TypeScript 的完美配合，为项目提供了全面的代码质量和类型安全保障。ESLint 负责统一团队代码风格，自动发现并修复代码中的潜在问题，同时实施最佳实践确保代码质量始终保持高水平。它与编辑器的紧密集成让开发者能实时获得代码改进建议。

TypeScript 则通过其强大的类型系统，在编译时就能捕获潜在错误。智能的代码提示和优秀的重构支持大大提升了开发效率，自动生成的类型声明确保了 API 使用的准确性。这两个工具的协同工作创造了一个完整的开发工具链，让团队协作更加顺畅，代码质量更有保障。

网络请求工具包：通信专家

request 工具包就像是一个专业的快递公司：

• 处理所有与服务器的数据交互
• 统一管理 API 请求
• 提供错误处理和重试机制

工具包的协同工作

这些工具包并不是独立运作的，它们之间相互配合，形成了一个完整的开发生态系统。UI 组件库借助 TypeScript 配置确保类型安全，网络请求工具与数据验证工具密切配合确保数据正确性，而用户行为跟踪则与 React Hooks 结合提供更好的用户体验。这种协同工作方式让整个系统更加稳定可靠。

项目管理工具

为了更好地管理这个大型项目，我们使用了两个主要工具：

• pnpm：一个高效的包管理工具，它帮我们管理项目中用到的各种工具和库
• Turborepo：专门用来管理大型项目的工具，让整个项目运行得更流畅

通过这样科学的项目组织和管理方式，我们成功地在三个月内构建了这个包含 20 万行代码的 AI 原型系统。这种管理方式不仅让开发过程更加高效，也让后期的维护和升级变得更加容易。特别是通过精心设计的工具包体系，我们大大提高了代码的复用率，减少了重复开发的工作量。对于想要了解大型项目管理的朋友来说，这个项目的组织方式提供了一个很好的参考。