AgentEval 前端应用，基于 React + Vite + TypeScript 构建。提供 AI Agent 评估平台的管理界面，包含测试套件管理、评估运行分析、采样配置和文档浏览等功能。

---

eval-web/
├── main.tsx                  # 入口：挂载 React，配置 QueryClient、BrowserRouter、ThemeProvider
├── App.tsx                   # 路由定义，顶层路由分发（/docs 独立布局，其余走 AppLayout）
├── index.html                # Vite HTML 模板
├── vite.config.ts            # Vite 配置：代理 /api/v1 → eval-server，端口 5173
├── tsconfig.json             # TypeScript 配置
├── package.json              # 依赖与脚本
│
├── api/                      # REST API 客户端层
│   ├── client.ts             # 底层 fetch 封装：request/get/post/put/del，含 X-Project-ID 等请求头
│   ├── config.ts             # 环境变量读取与 API 配置
│   ├── queryKeys.ts          # TanStack Query 键管理
│   ├── invalidation.ts       # 查询缓存失效策略
│   └── *.ts                  # 各业务模块 API（evaluations、executions、suites、sampling 等）
│
├── hooks/                    # 自定义 React Hooks（TanStack Query 数据获取封装）
│   ├── dashboard.ts          # 仪表盘数据 hooks
│   ├── evaluations.ts        # 评估运行 hooks
│   ├── suites.ts             # 测试套件 hooks
│   ├── useSampling.ts        # 采样配置 hooks
│   ├── useDoc.ts             # 文档内容加载 hook
│   └── *.ts                  # 其他业务 hooks
│
├── components/               # UI 组件，按 feature 域组织
│   ├── layout/               # AppLayout：导航栏、侧边栏、页面骨架
│   ├── dashboard/            # Overview 仪表盘：KPI、趋势图、测试用例详情
│   ├── test-suites/          # 测试套件管理：套件列表、执行、评估、手动评分
│   ├── evaluation-definitions/ # 评估定义 CRUD：评估器配置、输入构造器
│   ├── results/              # 评估结果详情：span 视图、序列评估视图
│   ├── sampling/             # 采样配置与运行记录
│   ├── government/           # 裁判治理（Judge Governance）
│   ├── settings/             # 集成设置（Langfuse 等）
│   ├── docs/                 # 内嵌文档浏览器：Markdown 渲染、目录导航、搜索
│   ├── shared/               # 跨业务复用组件：StatusBadge、GlobalSearch、AsyncState 等
│   └── ui/                   # shadcn/ui 基础组件（Radix UI 封装）
│
├── contexts/
│   └── requestContext.tsx    # React Context：注入租户请求头（project_id、env、actor_id）
│
├── types/
│   ├── idl.ts                # 接口数据结构（与后端 IDL 对齐）
│   └── sampling.ts           # 采样相关类型
│
├── lib/
│   ├── utils.ts              # cn() 工具函数（Tailwind class 合并）
│   └── apiErrors.ts          # API 错误分类处理
│
├── data/
│   └── mockData.ts           # 本地 mock 数据（开发/测试用）
│
├── styles/
│   └── globals.css           # 全局样式：Tailwind 基础 + CSS 变量主题（light/dark）
│
├── docs/                     # 内嵌文档内容（Markdown 文件 + 静态资源）
├── openspec/                 # 变更提案与规格文档（OpenSpec 规范）
└── tests/                    # 测试文件
    ├── integration/          # Playwright E2E 集成测试
    ├── setup.ts              # Vitest 全局测试配置
    └── test-utils.tsx        # 测试辅助工具

main.tsx → App.tsx（BrowserRouter）：

路径	组件	说明
/docs/*	DocsLayout	独立文档布局
/overview	Dashboard	默认落地页
/test-suites/:suiteId?	TestSuitesPage	测试套件管理
/executions/:execRunId?	ExecutionsPage	执行记录
/evaluations/:evalRunId?	EvaluationsPage	评估运行
/evaluation-definitions	EvaluationDefinitionsPage	评估定义管理
/manual-score	ManualScorePage	手动评分
/government	GovernmentPage	裁判治理
/settings/sampling	SamplingConfigPage	采样配置
/settings/integrations	IntegrationsSettingsPage	集成设置
/sampling-runs	SamplingRunsPage	采样运行记录

---

严禁直接修改对象/数组，必须返回新对象：

// 错误
function updateUser(user, name) {
  user.name = name   // 直接修改！
  return user
}

// 正确
function updateUser(user, name) {
  return { ...user, name }
}

• 典型文件：200–400 行；上限 800 行
• 超限时提取工具函数或拆分子组件
• 按 feature 域组织，而非按类型（不要把所有 hooks 混在一个大文件里）

try {
  const result = await riskyOperation()
  return result
} catch (error) {
  console.error('Operation failed:', error)
  throw new Error('详细的用户友好错误信息')
}

• API 层通过 ApiClientError（lib/apiErrors.ts）统一抛出结构化错误
• 禁止裸 throw error，必须附带上下文信息
• 不要将原始错误信息直接暴露给用户界面

对所有用户输入使用 zod 或等效方案校验：

import { z } from 'zod'

const schema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0).max(150)
})

const validated = schema.parse(input)

• 函数体 < 50 行；超长时提取命名辅助函数
• 嵌套深度 < 4 层；提前 return 减少嵌套
• 变量/函数命名清晰，见名知意，避免缩写

• 提交前必须清除所有 console.log
• 项目 PostToolUse hook 会在编辑 TS/TSX 文件后自动告警
• Stop hook 会在会话结束前全量审计

// 错误
const apiKey = "sk-proj-xxxxx"

// 正确
const apiKey = import.meta.env.VITE_AUTH_TOKEN
if (!apiKey) throw new Error('VITE_AUTH_TOKEN not configured')

所有可配置值从 import.meta.env 读取，对应 .env.local 文件。

• tsconfig.json 当前 strict: false，但新代码应尽量提供类型注解
• 类型定义统一放 types/ 目录，与后端 IDL 对齐

项目暂无 ESLint 配置文件。可用脚本：

npm run test      # Vitest 单元测试
npm run build     # TypeScript 类型检查 + Vite 构建

提示：vite build 会通过 tsc --noEmit（由 isolatedModules 保证）触发类型检查。

---

依赖	版本要求
Node.js	建议 v20+（开发环境实测 v24.12.0）
包管理器	npm（仓库使用 package-lock.json）

项目未配置 .nvmrc，建议使用 Node v20 LTS 或更高版本。

cd eval-web    # 进入本仓库根目录
npm install

复制示例文件并按需修改：

cp .env.example .env.local

.env.example 中的变量说明：

变量	说明	示例值
VITE_API_BASE_URL	后端 API 根地址（客户端直连用）	http://127.0.0.1:8080
VITE_PROXY_TARGET	Vite 开发服务器代理目标	http://127.0.0.1:8080
VITE_PROJECT_ID	租户项目 ID	demo
VITE_ENV	环境标识（DEV/STAGING/PROD）	DEV
VITE_ACTOR_ID	请求发起方标识	ui

npm run dev

默认监听 http://localhost:5173（所有网卡：0.0.0.0:5173）。

eval-web 依赖 eval-server 提供 REST API，路径前缀为 /api/v1。

Vite 开发服务器通过内置代理将所有 /api/v1/* 请求转发到 VITE_PROXY_TARGET（默认 http://127.0.0.1:64887），无需在前端代码中处理跨域。

浏览器 → localhost:5173/api/v1/* → (Vite proxy) → eval-server:8080/api/v1/*

请先确保 eval-server 在本地运行。参考 deploy.md 了解完整的多服务本地部署步骤。

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

# 预览构建产物（本地静态服务器）
npm run preview

# Vitest 单元测试（含组件测试）
npm run test

# Playwright E2E 测试（需先启动开发服务器）
npx playwright test

Q: 页面空白或 API 请求 404 确认 VITE_PROXY_TARGET 指向正确的 eval-server 地址，并且 eval-server 已启动。

Q: 端口冲突 修改 vite.config.ts 中的 server.port，或在启动时指定：npm run dev -- --port 3000

Q: .claude/settings.local.json 应不应该提交 该文件已被 .gitignore 忽略，本地修改不会进入提交。