196 lines
7.9 KiB
Markdown
196 lines
7.9 KiB
Markdown
# 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，避免界面闪烁。**请勿修改此逻辑。**
|