Label Studio Web 前端项目结构分析

项目概述

这是 Label Studio 的纯前端 Web 项目，基于 NX Monorepo 架构，使用 React + TypeScript 技术栈。项目已移除后端、Docker 等配置，专注于前端开发。

技术栈

构建工具: NX (Monorepo 管理)
前端框架: React 18.3.1
语言: TypeScript 5.8.3
状态管理:
- MobX + mobx-state-tree (编辑器核心)
- Jotai (应用层状态管理)
UI 组件库:
- Ant Design 4.x
- Radix UI (现代化组件)
- Shadcn/ui (基于 Radix UI)
样式方案:
- Tailwind CSS 3.4.3
- SCSS Modules
打包工具: Webpack 5
测试框架:
- Jest (单元测试)
- Cypress (E2E 测试)
代码质量:
- Biome (代码检查和格式化)
- Stylelint (样式检查)

项目结构

web/
├── apps/                    # 应用层
│   ├── labelstudio/        # 主应用
│   ├── labelstudio-e2e/    # E2E 测试
│   └── playground/         # 独立演示应用
├── libs/                    # 共享库
│   ├── editor/             # 标注编辑器核心
│   ├── datamanager/        # 数据管理器
│   ├── ui/                 # UI 组件库
│   ├── core/               # 核心工具库
│   ├── app-common/         # 应用通用模块
│   ├── frontend-test/      # 测试工具库
│   └── storybook/          # Storybook 配置
├── tools/                   # 构建工具
├── dist/                    # 构建输出
└── 配置文件

核心应用 (Apps)

1. `apps/labelstudio` - 主应用

用途: Label Studio 的完整前端应用

特点:

集成所有功能库和组件
包含完整的用户界面、路由、页面管理
需要配合后端 API 使用（通过环境变量配置）
构建输出: dist/apps/labelstudio/

启动命令:

yarn ls:dev          # 开发模式（支持 HMR）
yarn ls:watch        # 监听模式
yarn ls:build        # 生产构建

2. `apps/playground` - 独立演示应用

用途: 标注编辑器的独立测试和演示环境

特点:

完全独立运行（standalone 模式）
无需后端支持
主要用于测试和演示标注编辑器功能
可通过 URL 参数加载配置

启动命令:

yarn playground:serve    # 开发服务器
yarn playground:build    # 生产构建

3. `apps/labelstudio-e2e` - E2E 测试

用途: 端到端测试套件

特点:

基于 Cypress
测试主应用的完整工作流

运行命令:

yarn ls:e2e    # 运行 E2E 测试

共享库 (Libs)

1. `libs/editor` - 标注编辑器核心 ⭐

功能: 数据标注的核心功能库

技术栈:

React + mobx-state-tree
Konva (画布渲染)
Ant Design (UI 组件)

特点:

可独立使用和嵌入到其他应用
支持多种数据类型标注：
- 图像（矩形、多边形、关键点、分割等）
- 音频（区域标注、分类）
- 文本（NER、分类、关系抽取）
- 视频（时间轴标注）
- 时间序列数据
包含标注工具、画布、控件等完整功能
可通过 XML 配置定义标注界面

开发命令:

yarn lsf:watch          # 监听构建
yarn lsf:serve          # 独立运行
yarn lsf:unit           # 单元测试
yarn lsf:integration    # 集成测试
yarn lsf:e2e            # E2E 测试

2. `libs/datamanager` - 数据管理器

功能: 数据探索和管理工具

特点:

数据列表展示（虚拟滚动优化）
高级过滤和排序
批量操作支持
数据可视化
与编辑器深度集成

技术栈:

React + MobX
react-window (虚拟滚动)
@tanstack/react-table (表格)

开发命令:

yarn dm:watch    # 监听构建
yarn dm:unit     # 单元测试

3. `libs/ui` - UI 组件库 ⭐

功能: 共享的 UI 组件库

特点:

基于 Radix UI 和 Tailwind CSS
包含 Shadcn/ui 组件
设计令牌系统（从 Figma 自动生成）
完整的 Storybook 文档
支持深色模式

组件类型:

基础组件（Button, Input, Select 等）
布局组件（Dialog, Popover, Tabs 等）
数据展示组件（Table, Toast 等）

开发命令:

yarn ui:serve              # 启动 Storybook
yarn design-tokens         # 重新生成设计令牌

4. `libs/core` - 核心工具库

功能: 跨应用的通用工具和类型定义

特点:

工具函数集合
TypeScript 类型定义
常量和配置
无 UI 依赖

5. `libs/app-common` - 应用通用模块

功能: 应用级别的共享代码

特点:

跨应用的页面级组件
共享的业务逻辑
可以依赖其他 libs，但不能被其他 libs 依赖

6. `libs/frontend-test` - 测试工具库

功能: 测试辅助工具和 Helpers

特点:

Cypress 测试 Helpers
测试工具函数
Mock 数据生成

7. `libs/storybook` - Storybook 配置

功能: Storybook 的全局配置和插件

特点:

统一的 Storybook 配置
自定义插件和装饰器
主题配置

依赖关系图

apps/labelstudio
├── libs/editor          (标注编辑器)
├── libs/datamanager     (数据管理)
├── libs/ui              (UI 组件)
├── libs/core            (核心工具)
└── libs/app-common      (应用通用)

apps/playground
├── libs/editor          (标注编辑器)
├── libs/ui              (UI 组件)
└── libs/core            (核心工具)

libs/app-common
├── libs/ui
├── libs/core
└── libs/editor

libs/datamanager
├── libs/ui
└── libs/core

libs/editor
├── libs/ui
└── libs/core

libs/ui
└── libs/core

依赖规则:

apps/ 可以导入任何 libs/
libs/ 不能导入 apps/
libs/app-common 可以导入其他 libs/
其他 libs/ 不能导入 libs/app-common
避免循环依赖

开发工作流

启动开发环境

# 1. 安装依赖
yarn install --frozen-lockfile

# 2. 启动主应用（开发模式）
yarn dev
# 或
yarn ls:dev

# 3. 启动 Storybook（UI 组件开发）
yarn ui:serve

# 4. 启动 Playground（编辑器测试）
yarn playground:serve

构建生产版本

# 构建主应用
yarn build
# 或
yarn ls:build

# 构建 Playground
yarn playground:build

# 构建 Storybook
yarn storybook:build

测试

# 运行所有单元测试
yarn test:unit

# 运行特定模块测试
yarn ls:unit          # 主应用
yarn lsf:unit         # 编辑器
yarn dm:unit          # 数据管理器

# 运行集成测试
yarn lsf:integration

# 运行 E2E 测试
yarn test:e2e
yarn ls:e2e           # 主应用 E2E
yarn lsf:e2e          # 编辑器 E2E

# 测试覆盖率
yarn test:unit:coverage

代码质量检查

# 代码检查和自动修复
yarn lint

# SCSS 检查和自动修复
yarn lint-scss

# 生成文档
yarn docs

配置文件说明

核心配置

nx.json: NX 工作区配置
package.json: 项目依赖和脚本
tsconfig.base.json: TypeScript 基础配置
webpack.config.js: Webpack 构建配置
tailwind.config.js: Tailwind CSS 配置
biome.json: Biome 代码检查配置
.stylelintrc.json: Stylelint 样式检查配置

设计令牌

design-tokens.json: 从 Figma 导出的设计令牌
components.json: Shadcn/ui 组件配置

测试配置

jest.config.ts: Jest 测试配置
jest.preset.js: Jest 预设配置
cypress.config.ts: Cypress E2E 测试配置

独立性分析

✅ 可以独立运行的部分

Playground 应用 (完全独立)
- 无需后端支持
- 可通过 URL 参数加载配置
- 适合演示和测试标注功能
Editor 库 (可嵌入)
- 可作为独立库嵌入到其他项目
- 支持 standalone 模式
- 可通过 npm 包方式使用
UI 组件库 (完全独立)
- 通过 Storybook 独立开发和预览
- 可作为独立组件库使用

扩展和定制

创建新应用

# 使用 NX 生成器创建新应用
nx generate @nx/react:application my-app --style=scss --bundler=webpack

创建新库

# 创建新的共享库
nx generate @nx/react:library my-lib --style=scss --unitTestRunner=jest

添加新组件

# 在 UI 库中添加新组件
nx generate @nx/react:component my-component --project=ui --style=scss

环境变量配置

开发环境 HMR 配置

创建 .env 文件（可选）:

# 启用热模块替换
FRONTEND_HMR=true

# HMR 服务器地址（默认: http://localhost:8010）
FRONTEND_HOSTNAME=http://localhost:8010

# Django 后端地址（默认: http://localhost:8080）
DJANGO_HOSTNAME=http://localhost:8080

DataManager 自定义配置

参考 libs/datamanager/.env.example:

# API 网关地址
NX_API_GATEWAY=http://localhost:8080/api/dm

# Label Studio 访问令牌
LS_ACCESS_TOKEN=your_access_token

性能优化

构建优化

使用 NX 缓存加速构建
Webpack 代码分割
Tree-shaking 移除未使用代码
CSS 压缩和优化

运行时优化

React.memo 减少重渲染
虚拟滚动处理大数据集
懒加载路由和组件
图片和资源优化

常见问题

1. 如何连接后端 API？

主应用需要配置后端 API 地址，通常通过环境变量或构建时配置。

2. 如何独立使用编辑器？

使用 Playground 应用或将 @humansignal/editor 作为 npm 包引入你的项目。

3. 如何添加新的标注类型？

在 libs/editor 中扩展标注工具和控件，参考现有实现。

4. 如何自定义 UI 主题？

修改 design-tokens.json 和 Tailwind 配置，重新生成设计令牌。

5. 如何运行测试？

yarn test:unit           # 所有单元测试
yarn test:integration    # 集成测试
yarn test:e2e            # E2E 测试

总结

这是一个现代化的前端 Monorepo 项目，具有以下特点：

✅ 模块化架构: 清晰的应用和库分离
✅ 可复用性: 核心功能可独立使用
✅ 类型安全: 完整的 TypeScript 支持
✅ 现代工具链: NX + Webpack + Biome
✅ 完善的测试: 单元测试 + 集成测试 + E2E 测试
✅ 组件文档: Storybook 支持
✅ 设计系统: 基于 Figma 的设计令牌

项目专注于前端开发，可以独立开发和测试，也可以与后端 API 集成使用。

项目结构分析.md 10 KB Histórico Em bruto

Label Studio Web 前端项目结构分析

项目概述

技术栈

项目结构

核心应用 (Apps)

1. apps/labelstudio - 主应用

2. apps/playground - 独立演示应用

3. apps/labelstudio-e2e - E2E 测试

共享库 (Libs)

1. libs/editor - 标注编辑器核心 ⭐

2. libs/datamanager - 数据管理器

3. libs/ui - UI 组件库 ⭐

4. libs/core - 核心工具库

5. libs/app-common - 应用通用模块

6. libs/frontend-test - 测试工具库

7. libs/storybook - Storybook 配置

依赖关系图

开发工作流

启动开发环境

构建生产版本

测试

代码质量检查

配置文件说明

核心配置

设计令牌

测试配置

独立性分析

✅ 可以独立运行的部分

扩展和定制

创建新应用

创建新库

添加新组件

环境变量配置

开发环境 HMR 配置

DataManager 自定义配置

性能优化

构建优化

运行时优化

常见问题

1. 如何连接后端 API？

2. 如何独立使用编辑器？

3. 如何添加新的标注类型？

4. 如何自定义 UI 主题？

5. 如何运行测试？

总结

项目结构分析.md 10 KB

Histórico Em bruto

1. `apps/labelstudio` - 主应用

2. `apps/playground` - 独立演示应用

3. `apps/labelstudio-e2e` - E2E 测试

1. `libs/editor` - 标注编辑器核心 ⭐

2. `libs/datamanager` - 数据管理器

3. `libs/ui` - UI 组件库 ⭐

4. `libs/core` - 核心工具库

5. `libs/app-common` - 应用通用模块

6. `libs/frontend-test` - 测试工具库

7. `libs/storybook` - Storybook 配置