@tuskira/gateway-web

Tuskira AI Agent Gateway 的管理控制台。React 19 + Vite + TypeScript（严格模式）+ Tailwind CSS 4 + shadcn/ui。

开发

需要 Node 26+ 和 npm 11+（不支持 pnpm）。

npm install
npm run dev

开发服务器将 /api 代理到 http://localhost:8081（参见 vite.config.ts），因此 请在 :8081 上运行网关，与 UI 并行。使用网关签发的 API 密钥（gk_…）在 /login 登录。

从仓库根目录，你也可以改为运行：

make ui-install
make ui-dev

构建

npm run build

将生产包输出到 dist/。在生产环境中，网关自身在 :8081 的 / 上提供此包， 因此应用与 API 同源通信——无需代理。

make ui-build   # 从仓库根目录

质量检查

npm run lint        # eslint
npm run typecheck    # tsc --noEmit (project references)
npm run test         # vitest
npm run format:check # prettier --check

添加 shadcn/ui 组件

npx shadcn@latest add <component>

本项目的 components.json 面向 Vite 模板、radix 基础、neutral 基础色， 以及用于主题化的 CSS 变量，其中 @/* 导入别名解析为 src/*。新组件写入 src/components/ui/。

设计令牌

tokens.json（仓库根目录）是设计系统的唯一事实来源——颜色、间距、圆角、阴影、 字体。编辑后运行 npm run gen:tokens 以重新生成：

• src/styles/tokens.css — 作为 CSS 自定义属性的原始令牌（:root 用于浅色值， .dark 用于深色覆盖），保留设计师自己的令牌名称（--indigo-9、--sev-high、 --r-4、--shadow-1 等）。
• src/styles/tokens.ts — 相同的分类色阶（colors.indigo、colors.slate、 colors.sev、colors.status、colors.brand）以及 fonts、radii、shadows， 供非 CSS 消费者使用（例如 recharts 系列颜色）。

src/index.css 将 shadcn 的语义变量（--background、--primary、--sidebar 等） 映射到这些令牌，并注册 Tailwind v4 @theme 条目，以便 bg-indigo-9、 text-text-muted、border-border-strong、shadow-1、rounded-r-4 和 font-mono 等工具类可在应用中的任何位置使用。请勿手动编辑 src/styles/tokens.css / src/styles/tokens.ts——它们会被生成器覆盖。src/test/tokens.test.ts 断言每个 tokens.ts 条目在 tokens.css 中都有匹配的声明。

文件夹布局

web/
├── index.html
├── vite.config.ts        # React + Tailwind plugins, /api dev proxy, vitest config
├── components.json        # shadcn/ui config
├── tokens.json             # design-token source of truth (see Design tokens)
├── scripts/
│   └── gen-tokens.mjs        # tokens.json -> src/styles/tokens.{css,ts}
├── src/
│   ├── main.tsx            # ReactDOM root
│   ├── App.tsx              # QueryClientProvider, AuthProvider, RouterProvider
│   ├── index.css            # Tailwind entrypoint + semantic token mapping
│   ├── styles/
│   │   ├── tokens.css         # generated — raw design tokens as CSS vars
│   │   └── tokens.ts           # generated — same tokens for non-CSS use
│   ├── auth/
│   │   ├── AuthContext.tsx    # AuthProvider / useAuth — principal, signIn, signOut
│   │   └── RequireAuth.tsx    # route guard for the authenticated shell
│   ├── components/
│   │   ├── ui/                 # shadcn/ui primitives (generated, don't hand-edit)
│   │   ├── layout/              # AppShell, Sidebar, TopBar
│   │   └── app/                  # ComingSoon, StatCard
│   ├── hooks/
│   │   └── use-theme.ts          # light/dark toggle, class strategy, localStorage
│   ├── lib/
│   │   ├── api.ts                 # fetch wrapper: bearer auth, 401 handling, ApiError
│   │   ├── nav.ts                  # single source of truth for sidebar nav + routes
│   │   ├── queries.ts                # react-query hooks (useHealth)
│   │   ├── query-client.ts            # QueryClient instance
│   │   ├── types.ts                    # Principal, HealthResponse, ApiErrorBody
│   │   └── utils.ts                     # cn() (shadcn)
│   ├── routes/
│   │   ├── router.tsx                    # createBrowserRouter (data router)
│   │   ├── LoginPage.tsx
│   │   ├── OverviewPage.tsx
│   │   └── DocsPage.tsx
│   └── test/
│       ├── setup.ts
│       ├── LoginPage.test.tsx
│       ├── Sidebar.test.tsx
│       ├── SignOut.test.tsx
│       └── tokens.test.ts