Alfred/docs/development/frontend.md

前端开发

本文档说明 alfred 前端的运行时代码结构、组件索引和页面组成。开发规范（组件规范、Ant Design 用法、样式规则、表单交互、TanStack Query、测试约定等）见 开发规范文档。

适用场景：修改 src/web/、了解现有组件和页面结构、查找 hooks 和工具函数。

运行时外壳

前端提供两个入口外壳，共享通用 Console Shell 组件：

• Admin（管理台）：src/web/consoles/admin/AdminConsoleLayout.tsx，菜单配置在 src/web/consoles/admin/menu.tsx，路由 /（总览）、/projects（项目管理）、/models（模型管理）。
• Workbench（工作台）：src/web/consoles/workbench/WorkbenchProjectGate.tsx → WorkbenchConsoleLayout.tsx，菜单配置和路由构造在 src/web/consoles/workbench/routes.ts，路由 /workbench/:projectId 和 /workbench/:projectId/chat。默认菜单为"聊天室"。

通用 Console Shell（src/web/components/ConsoleShell/ConsoleShell.tsx）包含 ConfigProvider（zhCN locale）、AntApp、Layout、Header、Sider、Content、主题切换（明亮/黑暗/系统）和侧边栏折叠状态，由 Admin 和 Workbench 复用。Header 显示品牌名、版本号和控制台标题（Admin 显示"管理台"，Workbench 显示"工作台 · 项目名"）。

Menu 类型定义在 src/web/menu.tsx 中的 MenuItemConfig 接口（icon、label、path、value）。

Sidebar（src/web/components/Sidebar/index.tsx）是纯展示/导航组件，通过 menuItems props 接收菜单配置，由调用方决定菜单内容和路径。Admin 传入静态路径 /、/projects、/models；Workbench 通过 route builder（buildWorkbenchPath）将相对菜单路径拼成 /workbench/:projectId 的子路径。

Workbench 项目上下文通过 ProjectContext（src/web/consoles/workbench/ProjectContext.tsx 和 ProjectContextValue.ts）提供，在 WorkbenchProjectGate 中从 URL path param 读取 projectId，通过 useProject(projectId) 加载项目，仅 active 项目渲染工作台布局，不存在或 archived 项目显示"项目不存在或不可访问"。

页面概览

页面	路径	入口文件
总览	/	src/web/pages/dashboard/index.tsx
项目管理	/projects	src/web/pages/projects/index.tsx
模型管理	/models	src/web/pages/models/index.tsx
聊天室	/workbench/:id	src/web/consoles/workbench/pages/ChatPage.tsx
404	*	src/web/pages/404/index.tsx

项目管理页面

项目管理页面（src/web/pages/projects/index.tsx）使用 ProjectToolbar（Tab 切换 active/archived + 搜索 + 新建按钮）、ProjectTable（列表展示、内联操作）和 ProjectFormModal 拆分职责。支持创建、编辑、归档、恢复和永久删除项目，仅 active 项目可点击跳转工作台。

模型管理页面

模型管理页面（src/web/pages/models/index.tsx）通过 antd Tabs 在同页组织供应商和模型两个视图。页面使用 ModelsToolbar、ProviderTable、ProviderFormModal、ModelTable、ModelFormModal 拆分职责；模型表单和模型表格必须使用 GET /api/providers/options 获取最小供应商选项。供应商表单支持未保存配置的连通性测试（POST /api/providers/test），新建供应商时 type 默认 openai-compatible，baseURL 不设默认值。连通性测试返回 ok: false 时展示失败反馈；/models 不支持属于可忽略提醒，不阻止保存。

聊天页面

Workbench 聊天页面位于 src/web/consoles/workbench/pages/ChatPage.tsx，组合 ChatSidebar 和 ChatPanel 两个子组件。

• ChatSidebar（src/web/consoles/workbench/components/chat/ChatSidebar.tsx）：使用 TanStack Query 管理会话列表，提供创建和删除会话操作。
• ChatPanel（src/web/consoles/workbench/components/chat/ChatPanel.tsx）：使用 Vercel AI SDK useChat hook（来自 @ai-sdk/react）管理聊天状态，通过 DefaultChatTransport（来自 ai 包）与后端 SSE 端点通信。采用论坛式单列垂直布局，使用 antd Card 组件承载每条消息，通过按 part.type 分派渲染（文本/推理/工具调用）。AI 文本使用 streamdown 流式 Markdown 渲染。支持编辑上一条用户消息后重新发送、重新生成最后一条 AI 回复、复制消息内容。
• ChatInputArea（src/web/consoles/workbench/components/chat/ChatInputArea.tsx）：使用 antd Input.TextArea + Button + Select 组合，支持模型切换和发送/停止操作。
• Part renderers（src/web/consoles/workbench/components/chat/parts/）：TextPart.tsx（Markdown 文本渲染）、ReasoningPart.tsx（推理过程）、ToolPart.tsx（工具调用展示，支持 input-streaming/input-available/output-available/output-error 四态）。

use-conversations hook 位于 src/web/hooks/use-conversations.ts，封装会话 CRUD 和消息获取的 fetch 调用。

Hooks 索引

Hook 文件	说明
use-meta.ts	获取 /api/meta（30s 轮询，5s staleTime）
use-projects.ts	项目 CRUD + archive/restore API
use-providers.ts	供应商 CRUD + test connection API
use-models.ts	模型 CRUD + test connection API
use-conversations.ts	会话和消息 fetch 函数（不含 Query hooks）
use-theme-preference.ts	主题偏好（明亮/黑暗/跟随系统）localStorage 持久化
use-sidebar-collapsed.ts	侧边栏折叠状态 localStorage 持久化

工具函数索引

文件	说明
utils/api.ts	handleResponse()、handleVoidResponse() — 通用 fetch 响应处理
utils/time.ts	formatCountdown、formatDurationUnit、formatRelativeTime、isOlderThan、subtractHours

更新触发条件

修改前端运行时代码结构、页面组成、组件索引或 hooks/工具清单时，必须更新本文档。