包文档索引

01MVP Monorepo 中所有共享包的完整文档索引

概述

01MVP Monorepo 包含 13 个经过精心设计的共享包，涵盖认证、基础设施、AI 集成和云服务等核心功能。所有包都遵循统一的架构模式，提供完整的 TypeScript 类型支持和测试覆盖。

包分类

认证与配置

核心基础设施包，为整个应用提供认证和配置管理能力。

包名	描述	文档链接
@mono/auth	基于 Better Auth 的认证与授权解决方案，支持微信 OAuth、权限管理、邀请系统	查看文档
@mono/config	统一的配置管理，支持环境变量验证、类型安全的配置访问	查看文档

UI 与工具

前端开发的核心工具包，提供组件库、国际化和通用工具函数。

包名	描述	文档链接
@mono/ui	基于 shadcn/ui 的组件库，包含 80+ 个可复用组件	查看文档
@mono/i18n	基于 next-intl 的国际化解决方案，支持中英文切换	查看文档
@mono/utils	通用工具函数库，包含手机号处理、用户名验证、资料验证等	查看文档

基础设施服务

后端基础设施包，提供缓存、存储和 API 客户端能力。

包名	描述	文档链接
@mono/cache	多层缓存解决方案，支持内存缓存、Next.js 缓存集成、缓存监控	查看文档
@mono/storage	文件存储抽象层，支持 S3 和腾讯云 COS，提供签名 URL、水印等功能	查看文档
@mono/api-client	统一的 API 客户端，支持请求重试、缓存、错误处理、性能监控	查看文档
@mono/logs	结构化日志系统，支持多级别日志、模块化 logger、环境感知	查看文档

AI 与语音

AI 和语音识别集成包，支持多提供商切换。

包名	描述	文档链接
@mono/ai	统一的 AI/LLM 集成层，基于 Vercel AI SDK，支持多提供商切换	查看文档
@mono/asr	语音识别集成，支持 DashScope 和火山引擎，提供流式识别能力	查看文档

云服务

腾讯云服务集成包，提供内容审核能力。

包名	描述	文档链接
@mono/tencent-cloud	腾讯云 SDK 封装，提供文本审核、图片审核客户端	查看文档
@mono/content-moderation	内容审核抽象层，支持多提供商、批量审核、缓存策略	查看文档

包依赖关系

应用层 (apps/mono-web)
    ↓
┌─────────────────────────────────────────────────────────┐
│                     UI & 工具层                          │
│  @mono/ui  @mono/i18n  @mono/utils                      │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│                   业务逻辑层                             │
│  @mono/auth  @mono/api-client  @mono/content-moderation │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│                  基础设施层                              │
│  @mono/cache  @mono/storage  @mono/logs                 │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│                  外部服务层                              │
│  @mono/ai  @mono/asr  @mono/tencent-cloud               │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│                    配置层                                │
│  @mono/config                                           │
└─────────────────────────────────────────────────────────┘

快速开始

安装依赖

所有包都使用 workspace:* 协议在 monorepo 内部引用：

{
  "dependencies": {
    "@mono/auth": "workspace:*",
    "@mono/ui": "workspace:*"
  }
}

开发工作流

# 安装所有依赖
pnpm install

# 启动开发服务器（自动生成 Prisma 类型）
pnpm dev

# 类型检查所有包
pnpm type-check:packages

# 测试所有包
pnpm test:packages

# 验证所有包（类型检查 + 测试）
pnpm verify:packages

添加新包

使用标准包结构：

packages/your-package/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

在 package.json 中配置导出：

{
  "name": "@mono/your-package",
  "exports": {
    ".": "./src/index.ts"
  }
}

包开发规范

目录结构

所有包遵循统一的目录结构：

packages/package-name/
├── src/
│   ├── index.ts          # 主导出文件
│   ├── types.ts          # 类型定义
│   └── ...               # 其他源文件
├── test/                 # 测试文件（或 __tests__/）
├── package.json          # 包配置
├── tsconfig.json         # TypeScript 配置
├── vitest.config.ts      # 测试配置（如有测试）
└── README.md             # 包文档

导出规范

简单包（单一导出点）：

{
  "exports": {
    ".": "./src/index.ts"
  }
}

复杂包（多个子路径）：

{
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*"
  }
}

测试要求

所有包都应包含测试套件：

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "type-check": "tsc --noEmit"
  }
}

测试覆盖率目标：

核心包（auth, api-client, cache）：80%+
工具包（utils, config）：70%+
集成包（ai, asr, storage）：60%+

包质量指标

包名	代码行数	测试用例	测试覆盖率	文档完整度
@mono/auth	~800	76	85%+	✅ 完整
@mono/config	~200	31	90%+	✅ 完整
@mono/ui	~11,500	101	60%+	✅ 完整
@mono/i18n	~300	37	80%+	✅ 完整
@mono/utils	~600	123	85%+	✅ 完整
@mono/cache	~400	80	90%+	✅ 完整
@mono/storage	~800	41	70%+	✅ 完整
@mono/api-client	~2,300	81	75%+	✅ 完整
@mono/logs	~200	59	85%+	✅ 完整
@mono/ai	~1,000	143	97%+	✅ 完整
@mono/asr	~600	78	80%+	✅ 完整
@mono/tencent-cloud	~500	62	85%+	✅ 完整
@mono/content-moderation	~300	85	90%+	✅ 完整

总计：13 个包，~19,500 行代码，1,097 个测试用例，平均覆盖率 80%+

常见问题

如何在应用中使用包？

直接导入即可，TypeScript 会自动解析类型：

import { auth } from "@mono/auth";
import { Button } from "@mono/ui";
import { generateText } from "@mono/ai";

包之间如何相互依赖？

在 package.json 中使用 workspace:* 协议：

{
  "dependencies": {
    "@mono/config": "workspace:*",
    "@mono/utils": "workspace:*"
  }
}

修改包后需要重新构建吗？

不需要。所有包导出 TypeScript 源文件（.ts），Next.js 的 Turbopack 会自动处理编译和热更新。

如何调试包代码？

直接在包的源文件中添加断点
使用 console.log 或 @mono/logs 记录日志
运行 pnpm dev 时会自动监听包的变化

包的类型检查失败怎么办？

# 检查单个包
pnpm --filter @mono/package-name type-check

# 检查所有包
pnpm type-check:packages

# 如果是 Prisma 类型问题，重新生成
pnpm db:generate

贡献指南

添加新功能

在对应包的 src/ 目录添加代码
导出新功能到 src/index.ts
添加测试到 test/ 或 __tests__/
更新包的 README.md
更新 Fumadocs 文档（如需要）

提交规范

遵循 Conventional Commits：

# 新功能
git commit -m "feat(auth): add WeChat OAuth support"

# 修复
git commit -m "fix(cache): resolve memory leak in CacheMonitor"

# 文档
git commit -m "docs(ai): add streaming examples"

# 测试
git commit -m "test(utils): add phone number validation tests"

发布流程

包不单独发布，随应用一起部署。如需独立发布：

更新包版本号
运行 pnpm build
运行 pnpm test:packages
提交并打标签
推送到 npm（如需要）

最后更新：2026-03-09 维护者：01MVP Team