Pre_Seg_Server/AGENTS.md

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   # 模板库管理

---

构建与运行命令

# 安装依赖
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，避免界面闪烁。请勿修改此逻辑。