企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG

本文以 Nexent 仓库内置的 Agent 技能文档 SKILL.md 为主体，完整梳理frontend/目录下的前端开发规范：路由与国际化、组件与 UI、Hooks 与状态管理、API 服务层、类型与运行时常量的职责划分，以及配套的校验命令。读完后，你能够按照 Nexent 既有的分层约定独立实现、调试和评审前端代码，并知道用哪些命令做行为验证。

一、这份 Skill 文档的定位与适用边界

nexent-frontend 是一份面向 AI Agent（同样适用于人类开发者）的前端工作流指南，位于仓库根目录的.agents/skills/下。其 YAML frontmatter 明确定义了触发条件与排除范围：

--- name: nexent-frontend description: Use when implementing, debugging, or reviewing Nexent frontend pages, React components, hooks, API services, TypeScript types, styling, or localization under frontend/. Includes UI requests without file paths. Skip backend-only work, Python tests, and documentation-only changes with no frontend behavior. ---

含义可以归纳为三点：

• 覆盖范围：frontend/下的页面、React 组件、Hooks、API 服务、TypeScript 类型、样式与国际化改动，甚至是不带文件路径的 UI 类需求；
• 明确排除：纯后端工作、Python 测试、以及不产生前端行为变化的纯文档改动；
• 协作原则（文档第 5 条）：报告引用了哪些参考资料、跑了哪些检查、哪些检查被阻塞；不要为了强制统一规范去改动无关的遗留代码。

文档要求所有路径以仓库根目录为相对基准，参考链接从该 Skill 自身解析，这保证了指南中链接的可追溯性。

二、五步工作流与"按需加载"的参考资料体系

SKILL.md 正文给出了一条极简但完整的工作流：

1. 先读架构与现状，再选 API 和依赖：阅读 architecture、受影响的 feature，以及frontend/package.json；
2. 只加载相关的详细规则：按工作类型查表，取对应 reference，而不是通读全部；
3. 保持路由入口轻薄，复用现有共享 UI，在复用或复杂度确实需要时再提取抽象；
4. 验证受影响的行为（含 loading/error 状态和国际化），从frontend/package.json中选择合适的检查命令，必要时用npm run check-all做宽范围验证；不要因为过时示例里提到过某个依赖就去安装它；
5. 报告所查资料、已跑与阻塞的检查。

第 2 步的"工作 → 参考资料"映射表如下（均为仓库内真实文件）：

这种"总入口 + 按任务取规则"的组织方式，本质上是一份渐进式加载的规则路由表，既控制了上下文成本，也让每条规范都落在具体任务上。

三、目录架构：谁负责什么

references/architecture.md 是整份规范的骨架，定义了frontend/的分层职责。对照仓库现状，这些约定与实际目录一一对应：

• 路由层：app/[locale]/{feature}/page.tsx只是薄入口，负责路由、鉴权/配置与 feature 组合；实质性逻辑跟随各 feature 既有的内部结构。仓库中frontend/app/[locale]/下确实按 feature 平铺了agent-space/、workbench/、evaluation/、knowledges/、market/等二十余个路由段；
• UI 归属：仅某 feature 使用的 UI 放app/[locale]/{feature}/components/；跨 feature 的 UI 放顶层components/；鉴权 UI 用components/auth/，Provider 用components/providers/。仓库顶层frontend/components/下相应存在agent/、auth/、chat/、navigation/、providers/、skill/、ui/等目录；
• 禁止私有代码跨 feature 导入：feature 代码不得 import 另一个 feature 的私有代码，真正的复用应提升为共享模块；
• 状态/请求/工具分层：hooks/{domain}/拥有可复用的状态与副作用；services/拥有 API 调用；lib/拥有工具函数。依赖方向是硬约束：services/、lib/、types/不得依赖app/或components/；
• 类型与常量分离：types/只放导出的接口/类型别名；运行时常量、枚举、配置和状态值放const/；可执行的守卫函数放lib/或合适的运行时模块。仓库中frontend/const/下可看到errorCode.ts、errorMessage.ts、memoryConfig.ts等，frontend/types/下则是agentConfig.ts、conversation.ts等纯类型文件；
• 样式分层：styles/放全局主题/reset/AntD 覆写，组件 CSS 就近共置；组件库以Ant Design 为主，Tailwind 仅做适度的布局/间距辅助；
• 日志：新代码或改动代码一律使用frontend/lib/logger.ts，禁止直接console.log；
• 路径别名：frontend/tsconfig.json将@/*映射到frontend/*、@/app/*映射到frontend/app/[locale]/*，使用后者时可以省略[locale]段。这一点可以在 tsconfig.json 中直接验证：

"paths": { "@/*": ["./*"], "@/app/*": ["./app/[locale]/*"] }

• 数据获取约定：共享客户端 API 数据统一走 TanStack React Query；派生过滤/排序用useMemo；mutation 用useMutation并做相关 query 失效；
• 抽象比例原则：抽象只服务于具体的复用、复杂度或可测试性需求，不为抽象而抽象。

从源码结构看，这套分层在整个仓库中被稳定执行：例如 frontend/services/api.ts 只依赖@/const/*、@/lib/*和@/types/*，完全没有反向依赖 UI 层。

四、页面与国际化（Pages）

references/pages.md 规定了路由页面与本地化的具体做法：

• [locale]动态路由：所有用户可见页面都参与[locale]路由，page.tsx、layout.tsx、loading.tsx各司 App Router 其职；新路由段使用 kebab-case（仓库内如agent-repository/、owner-manage/、resource-manage/均为 kebab-case）；
• 入口保持轻薄：实质性 UI/逻辑下放给 feature 组件或内部模块；跨层布局状态优先用嵌套 layout 解决，而不是逐层透传 props；
• 国际化集成：项目使用既有的react-i18next/i18next集成。具体入口是 frontend/app/[locale]/i18n.tsx——该文件定义loadLocaleMessages(locale)，在运行时从/locales/{en|zh}/common.json与custom.json拉取文案资源并注入 i18next；custom.json中的键值对还会被转换为replacemenKeyArr（pattern/str 替换表）供后续文案解析使用。文档同时特别警告：项目没有声明next-intl，不要照搬旧 Cursor 示例中的 import 写法（frontend/package.json的依赖中是i18next、react-i18next与next-i18next，无next-intl）；
• 客户端/服务端组件的边界：客户端组件用useTranslation加描述性的 feature/namespace key；Server Components 必须走当前服务端兼容的 locale 加载路径，不能直接用客户端 hooks；
• 数据获取偏好：在路由兼容的前提下优先用 Server Components 做首屏取数，并有意地设置服务端缓存策略；客户端取数则放入遵循 shared-query 约定的 hooks；
• 页面职责：提供 loading/error 状态、页面私有状态保持局部化、共享状态走 Context/自定义 hooks；需要时用 Next.js metadata API；布局保持响应式；日志同样走 logger.ts。

[locale]根布局可参考 layout.tsx 与 layout.client.tsx 的服务端/客户端拆分方式。

五、组件与 UI 约定（Components and UI）

references/components-ui.md 从结构、视觉、文案三条线约束组件写法：

结构与接口

• TypeScript 函数式组件 + 带类型的 props 接口；优先受控组件，可选 props 给合理默认值；
• 局部状态保持局部；跨切面状态用 Context，嵌套内容/回调走组合（composition），共享逻辑走 hooks。"props 到 7～10 个或出现重复透传层"是复审接口的信号，而不是自动重写的要求；
• 组件文件控制在约1,000 行以内，复杂度增长时提取内聚的共置子组件/hooks；props 只有在构成一致关注点时才做分组。

视觉约定

• 表单、数据展示、按钮、模态框、复杂交互首选 Ant Design，避免给基础控件套无意义的 wrapper；优先使用 AntD Layout（Header/Sider/Content/Footer）、响应式 Grid 与 Flex；Tailwind 只做适度的间距/布局/样式补充；确有必要时可用内联样式与局部 AntD 全局覆写；
• 使用主题 token/CSS 变量、响应式布局、可访问的 focus 状态与必要的 error boundary；组件 CSS 就近共置；
• 图标首选lucide-react，Lucide 没有等价图标时再用@ant-design/icons（两者版本可在 package.json 中确认：lucide-react^0.454.0、@ant-design/icons6.2.5）；
• 自定义内容用居中的 AntDModal；简单确认统一用 frontend/hooks/useConfirmModal.ts，文案 key 用common.cancel/common.confirm；破坏性确认使用 primary danger 按钮与既定的警告图标/标题布局，普通操作不得从旧删除示例中继承破坏性样式。

文案与行为

• 用户可见文本一律经useTranslation本地化，key 按 feature/namespace 分组并带描述性命名，遵循项目的 fallback 行为；结构化/富文本翻译用Trans组件；
• 提供有意义的异步 loading/error 状态；日志走frontend/lib/logger.ts；
• 改动后检查交互、窄屏布局、焦点与本地化文案；提取组件时保持 handler/label 一致。

frontend/lib/logger.ts本身实现也很直白：开发环境输出带[DEBUG]/[INFO]/[WARN]/[ERROR]前缀的 console 记录，生产环境全部静默为 noop——这正是"新代码禁止裸console.log"的落地基础。

六、Hooks 与状态管理

references/hooks.md 给出了状态与副作用的完整决策规则：

• 命名与放置：TypeScript，useXxx命名，放在既有 domain 文件夹下（仓库中即frontend/hooks/agent/、frontend/hooks/mcpTools/、frontend/hooks/tenant/等）；返回值用对象并带描述性命名，包含 loading/error/success 状态；
• 取数三件套：共享服务端数据用 TanStack React QueryuseQuery；派生过滤/排序用useMemo；mutation 用useMutation并失效受影响的 query。仓库依赖@tanstack/react-query^5.90.12，可与之对照；
• 反模式：不要为重复 shared-query 的取数再写useEffect+ state。effect 留给订阅、定时器与局部副作用，且必须清理、声明正确依赖；
• 本地状态用useState，耦合的复合状态机用useReducer，真正共享的状态才上 Context；保持不可变更新与正确的异步状态流转；
• useCallback/useMemo/useRef仅在身份、计算或可变引用确实需要时使用，不机械地包裹每个函数；
• 暴露有用的异步错误；瞬时失败通过既有的 query/请求策略重试，避免无界或重复重试；
• 用frontend/lib/logger.ts记录日志；验证清理、状态流转、错误与 query 失效路径。

七、API 服务层

references/api-services.md 对请求层的规定非常具体：

• 端点集中定义：端点定义与基础请求行为放在 frontend/services/api.ts；领域操作放入对应的*Service.ts（仓库中已有agentRepositoryService.ts、conversationService.ts、knowledgeBaseService.ts等三十余个服务文件）；
• 只用API_ENDPOINTS：禁止在领域服务中硬编码 URL 或拼接端点字符串；需要时集中添加参数化 builder。api.ts 的真实写法可以佐证这一约定——基础路径统一为withBasePath("/api")，随后按领域分组、静态端点用模板字符串、动态端点用函数 builder：

export const API_BASE_URL = withBasePath("/api"); export const API_ENDPOINTS = { user: { signup: `${API_BASE_URL}/user/signup`, signin: `${API_BASE_URL}/user/signin`, deleteToken: (tokenId: number) => `${API_BASE_URL}/user/tokens/${tokenId}`, // ... }, conversation: { list: `${API_BASE_URL}/conversation/list`, detail: (id: number) => `${API_BASE_URL}/conversation/${id}`, // ... }, share: { assetPreview: (shareId: string, assetId: string, filename?: string) => { const queryParams = new URLSearchParams(); if (filename) queryParams.append("filename", filename); const suffix = queryParams.toString() ? `?${queryParams.toString()}` : ""; return `${API_BASE_URL}/share/${shareId}/assets/${assetId}/preview${suffix}`; }, }, // ... };

• fetchWithErrorHandling：解析前先看它的当前返回类型与错误行为；保留既有流式/响应契约；
• 会话过期处理：复用共享的ApiError与既有的401/499 session-expiration处理（api.ts 顶部即导入handleSessionExpired与STATUS_CODES），不要重复实现或绕过；
• 请求/响应类型分离：共享契约放frontend/types/，需要兼容时可再导出；确需复用时用泛型；
• 做好数据转换与有用错误信息的处理；日志走frontend/lib/logger.ts；
• 服务层不得依赖app/或components/；改动后验证端点选择、解析与错误路径。

八、类型与运行时值

references/types.md 补充了最容易被忽视的"类型/常量"边界：

• 共享类型一律导出，文件按既有 domain 惯例组织；
• 对象形状、props、API 契约用interface；联合类型、原始类型、计算类型用 type alias；
• 请求/响应类型分开定义，可选字段显式标注，状态用 union 表达；泛型/工具/映射/条件类型只在有具体需要时用；
• 复杂类型用简短的英文 JSDoc 说明；
• frontend/types/不含任何运行时值：运行时枚举、字面量、配置与状态常量进frontend/const/（如 const/errorCode.ts）；可执行守卫放frontend/lib/或合适的运行时模块；
• 类型定义模块里不写日志；运行时消费者用frontend/lib/logger.ts；
• 契约变更后，用项目的 TypeScript 检查（npm run type-check）验证所有消费方。

九、验证命令：从 package.json 中选择检查

SKILL.md 第 4 条要求"从frontend/package.json中选择检查"。frontend/package.json 当前提供的命令如下：

"scripts": { "dev": "node server.js", "build": "next build", "start": "NODE_ENV=production node server.js", "lint": "eslint .", "lint:fix": "eslint . --fix", "format": "prettier --write .", "format:check": "prettier --check .", "type-check": "tsc --noEmit", "test:components": "vitest run", "test:workbench": "vitest run --config vitest.workbench.config.ts", "test:e2e:external-memory": "playwright test e2e/external-memory-provider.spec.ts", "check-all": "npm run type-check && npm run lint && npm run format:check && npm run build" }

选型建议（对应文档"宽范围验证时用npm run check-all"）：

• 契约/类型改动 →npm run type-check（tsc --noEmit）；
• 代码风格问题 →npm run lint（修复用lint:fix）；
• 组件逻辑改动 →npm run test:components（Vitest + Testing Library，用例在frontend/tests/下，如humanClarification.test.ts、workbenchTransitions.test.ts）；
• Workbench 特性改动 →npm run test:workbench（独立配置 vitest.workbench.config.ts）；
• 端到端行为 →npm run test:e2e:external-memory（Playwright，用例frontend/e2e/）；
• 大范围改动或不确定影响面 →npm run check-all，即类型检查 + ESLint + Prettier 校验 +next build全链路。

技术栈版本基线（来自同一 package.json，供环境对齐参考）：next16.3.5、react19.2.3、antd^6.3.0、@tanstack/react-query^5.90.12、i18next^25.2.1 /react-i18next^15.5.3、lucide-react^0.454.0、zustand^5.0.9、typescript5.8.3。文档同时提醒：不要仅仅因为过时示例提到某个依赖就安装它——以 package.json 的实际声明为准。

十、落地小结

把 SKILL.md 与五份 reference 串起来，Nexent 前端规范可以浓缩为五条可执行原则：

1. 先读再写：动任何前端代码前，先读 architecture、受影响 feature 和package.json，按需加载对应 reference；
2. 分层不越界：app/[locale]薄入口、feature 私有组件不外泄、services/lib/types不反向依赖 UI、types与const严格分离；
3. AntD 优先、Tailwind 辅助，lucide-react优先、useConfirmModal统一简单确认、所有用户文案走useTranslation；
4. 数据流统一：API_ENDPOINTS集中端点 +fetchWithErrorHandling+ 共享 401/499 会话过期处理，TanStack Query 承载共享服务端状态；
5. 改动必验证：按改动面选择 type-check / lint / vitest / playwright 检查，宽范围改动跑check-all，并如实报告已查资料、已跑与阻塞的检查。

这套规范的价值在于：它既是给 AI Agent 的规则路由表，也是给人类贡献者的架构契约——规则、目录结构、tsconfig别名与package.json命令在仓库中互相印证，任何一条约定都能追溯到具体文件，从而在多人（含多 Agent）协作下保持frontend/的可读性与可维护性。

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG