# AGENTS.md — AI 编码助手项目指南

> 本文件面向 AI 编码助手。阅读者应假设对该项目一无所知。以下所有信息均基于项目实际内容，不做假设性推断。

---

## 项目概述

本项目是一个**语义分割系统**（Semantic Segmentation System）的 Web 前端应用，用于 AI 驱动的图像/视频分割与标注。它提供了一个深色主题（Dark Mode）的单页应用（SPA），包含项目管理、分割工作区、AI 智能分割引擎和模板库四大核心模块。

- **项目名称**: `react-example`（package.json 中的 name）
- **部署目标**: Google AI Studio（Cloud Run）
- **AI Studio 应用链接**: https://ai.studio/apps/2707f0e1-d453-4594-a618-fba53cb937c4
- **业务文档**: `语义分割系统构建方案.docx`（项目根目录，未解析内容）

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | React 19 + TypeScript 5.8 |
| 构建工具 | Vite 6 |
| 样式方案 | TailwindCSS 4 + 自定义深色主题 |
| 状态管理 | React `useState`（无外部状态库） |
| 路由 | 无路由库，基于 React 状态切换模块 |
| Canvas 渲染 | Konva + react-konva |
| 图标库 | lucide-react |
| 动画 | motion |
| AI SDK | @google/genai（Gemini API） |
| 后端/服务器 | Express 4（单文件 `server.ts`） |
| 运行时 | Node.js，ES Modules（`"type": "module"`） |

---

## 项目结构

```
Seg_Server/
├── server.ts              # Express 服务端入口（开发服务器 + 生产静态文件服务）
├── index.html             # SPA HTML 入口
├── vite.config.ts         # Vite 构建配置
├── tsconfig.json          # TypeScript 配置
├── package.json           # 依赖与脚本
├── .env.example           # 环境变量模板
├── metadata.json          # AI Studio 元数据（目前为空）
├── src/
│   ├── main.tsx           # React 应用挂载点（StrictMode）
│   ├── App.tsx            # 根组件：模块路由 + 登录鉴权
│   ├── index.css          # TailwindCSS 导入 + 自定义工具类
│   ├── lib/
│   │   └── utils.ts       # `cn()` 工具函数（clsx + tailwind-merge）
│   └── components/
│       ├── auth/
│       │   └── Login.tsx              # 登录页
│       ├── layout/
│       │   └── Sidebar.tsx            # 左侧导航栏（w-16）
│       ├── dashboard/
│       │   └── Dashboard.tsx          # 总体概况仪表盘
│       ├── projects/
│       │   └── ProjectLibrary.tsx     # 项目库列表
│       ├── workspace/
│       │   ├── VideoWorkspace.tsx     # 核心分割工作区布局
│       │   ├── CanvasArea.tsx         # Konva 画布（缩放/平移/选点）
│       │   ├── ToolsPalette.tsx       # 左侧工具栏
│       │   ├── OntologyInspector.tsx  # 右侧本体/属性检查面板
│       │   └── FrameTimeline.tsx      # 底部时间轴
│       ├── ai/
│       │   └── AISegmentation.tsx     # AI 智能分割引擎界面
│       └── templates/
│           └── TemplateRegistry.tsx   # 模板库管理
```

---

## 构建与运行命令

```bash
# 安装依赖
npm install

# 开发模式（启动 Express + Vite 中间件，端口 3000）
npm run dev

# 生产构建（输出到 dist/）
npm run build

# 预览生产构建
npm run preview

# 生产模式启动（Node 直接运行 server.ts，需先 build）
npm start

# 类型检查（不输出文件）
npm run lint

# 清理构建产物
npm run clean
```

**开发服务器地址**: `http://localhost:3000`

**环境变量**（复制 `.env.example` 为 `.env.local`）：
- `GEMINI_API_KEY` — Gemini AI API 密钥（AI Studio 会自动注入）
- `APP_URL` — 应用托管 URL（AI Studio 自动注入 Cloud Run 地址）

---

## 运行时架构

### 前端
- 单页应用，React 19 `StrictMode` 挂载。
- 模块切换通过 `App.tsx` 中的 `activeModule` 状态控制，可选值：
  `'dashboard' | 'projects' | 'ai' | 'workspace' | 'templates'`
- 默认进入 `workspace`（分割工作区）。
- 未登录时全局拦截，显示 `Login` 组件。

### 后端 (`server.ts`)
- Express 服务器，端口 `3000`。
- **开发模式**: 集成 Vite 中间件（`middlewareMode: true`）。
- **生产模式**: 静态文件服务 `dist/`，所有路由回退到 `index.html`。
- **API 端点**（内存数据存储，无数据库）：
  - `POST /api/login` — 认证（固定用户名 `admin`，密码 `123456`）
  - `GET /api/projects` — 返回项目列表
  - `GET /api/templates` — 返回模板列表

### 部署
- 面向 **Google AI Studio** / **Cloud Run** 部署。
- `metadata.json` 用于 AI Studio 元数据配置（当前为空）。
- `vite.config.ts` 中 HMR 可通过环境变量 `DISABLE_HMR=true` 关闭（AI Studio 环境下文件监听被禁用以防止 agent 编辑时闪烁）。

---

## 代码风格与约定

### 样式规范
- **深色主题**: 全局背景色以 `#0a0a0a`、`#111`、`#0d0d0d`、`#151515`、`#1e1e1e` 为主。
- **强调色**: 青色（`cyan-400`/`cyan-500`）用于激活状态、按钮和关键指示器。
- **工具类优先**: 全面使用 TailwindCSS 工具类，通过 `cn()` 合并条件类名。
- **自定义工具类**: `index.css` 中定义 `.no-scrollbar` 用于隐藏滚动条。

### 组件规范
- 所有组件使用 **函数组件 + Hooks**，无类组件。
- 组件按功能模块分目录存放在 `src/components/{module}/` 下。
- Props 类型使用 TypeScript `interface` 定义。
- 导入排序：React → 第三方库 → 内部模块 → 类型。

### 命名规范
- 组件文件使用 **PascalCase**（如 `AISegmentation.tsx`）。
- 工具文件使用 **camelCase**（如 `utils.ts`）。
- 类型/接口使用 **PascalCase**。

### 语言约定
- **界面文本**: 全部使用 **中文**（如 "核心分割工作区"、"AI智能分割引擎"、"导出 JSON 标注集"）。
- **代码与注释**: 使用英文。
- 添加新 UI 文本时，**必须保持中文**。

---

## 测试策略

**当前状态：无测试文件。**

- 项目中不存在 `.test.` 或 `.spec.` 文件。
- 无测试框架配置（如 Jest、Vitest、Playwright）。
- 若需添加测试，建议在前端引入 Vitest（与 Vite 同生态）进行单元测试，或使用 Playwright 进行 E2E 测试。

---

## 安全注意事项

- **硬编码凭证**: `server.ts` 中登录验证使用硬编码凭据（`admin` / `123456`），生产环境必须替换为真实的身份验证机制。
- **Mock JWT**: 登录成功返回固定的 `fake-jwt-token-for-admin`，无实际的 JWT 签名验证。
- **内存数据存储**: 所有项目/模板数据存储在内存中，服务重启后数据丢失。无持久化层。
- **环境变量**: `GEMINI_API_KEY` 通过 `.env.local` 管理，已加入 `.gitignore`，不会误提交。
- **CORS / 安全头**: Express 服务器目前未配置 CORS 策略或安全响应头（如 Helmet）。

---

## 关键依赖与注意事项

- **React 19**: 使用 `createRoot` API，注意与 React 18 的部分差异。
- **TailwindCSS 4**: 使用 `@import "tailwindcss"` 语法（非 v3 的 `@tailwind` 指令）。
- **react-konva**: Canvas 交互核心，所有画布相关操作（缩放、选点、遮罩）均依赖此库。
- **use-image**: 用于异步加载图片到 Konva 画布。
- **路径别名**: `@/*` 映射到项目根目录（由 `vite.config.ts` 和 `tsconfig.json` 共同配置）。
- **缺失资源**: `Sidebar.tsx` 引用了 `/Logo.png`，但项目根目录无此文件，运行时会 404。

---

## AI Studio 特定配置

- `vite.config.ts` 中通过 `loadEnv` 加载环境变量，并将 `GEMINI_API_KEY` 注入到 `process.env.GEMINI_API_KEY`。
- AI Studio 会在部署时自动注入 `GEMINI_API_KEY` 和 `APP_URL`。
- `DISABLE_HMR` 环境变量用于在 AI Studio agent 编辑模式下关闭 HMR，避免界面闪烁。**请勿修改此逻辑。**