page-agent 官网开发指南：React + Vite + Tailwind + shadcn/ui 文档站架构、路由与发布实践

page-agent 官网开发指南React Vite Tailwind shadcn/ui 文档站架构、路由与发布实践【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent本文以 page-agent 仓库中 packages/website/AGENTS.md 为骨架系统讲解该开源项目官方网站page-agent/website的前端技术栈、组件规范、wouter 路由设计、GitHub Pages SPA 部署方案以及新增一篇文档页的完整操作流程。读完本文你将掌握如何基于 React 19 Tailwind CSS 4 shadcn/ui Magic UI 维护一个多语言文档站点并能为 page-agent 官网添加新页面而不破坏既有路由与部署约束。一、网站包定位与整体技术栈packages/website是 page-agent 的官方网站包承载首页Home与全部文档Docs的展示。它的包名为page-agent/website见 packages/website/package.json作为 npm workspace 的一员挂载在仓库根 package.json 的workspaces列表中。其技术栈在 AGENTS.md 中明确列出与 packages/website/package.json 的依赖声明完全对应技术用途当前仓库实际依赖版本React TypeScript视图框架与类型系统react/react-dom^19.2.xtypescript^6.0.3仓库根 overrideVite开发服务器与构建vite^8.2.2Tailwind CSS原子化样式tailwindcss^4.3.2shadcn/uinew-york 风格基础 UI 组件库基于class-variance-authority、clsx、tailwind-merge等Magic UI动效与展示组件基于motion^12.42.2、tw-animate-csswouter轻量路由base: /page-agentwouter^3.10.0lucide-react图标库^1.40.0此外还依赖next-themes主题切换、sonnerToast、rough-notation手绘标注效果用于highlighter组件、simple-icons社交图标等。值得注意的两个工程约束Node/npm 版本仓库根 package.json 的engines声明要求node ^22.22.1 || 24、npm ^11.6.3本地开发与 CI 构建都应满足该版本前提。构建产物规模官网首页与文档页组件较多vite.config.js 将chunkSizeWarningLimit提升到 2000 KB并将react、react-dom、wouter手动拆分为独立的vendorchunkmanualChunks避免三方库与业务代码混在一个包里。二、项目目录结构与职责划分AGENTS.md 给出了src/下的核心结构结合仓库实际文件packages/website/src可进一步细化src/ ├── pages/ │ ├── home/ # 首页 │ │ ├── index.tsx # 首页入口 │ │ └── HeroSection.tsx / FeaturesSection.tsx / ScenariosSection.tsx / OneMoreThingSection.tsx │ └── docs/ │ ├── index.tsx # 文档路由表DocsRouter │ ├── Layout.tsx # 文档页侧边栏导航布局 │ └── introduction|features|advanced/topic/page.tsx # 每个文档主题一个目录 ├── components/ │ ├── ui/ # shadcn/ui Magic UI 组件禁止手工修改 │ ├── Heading.tsx # 文档页锚点标题组件 │ ├── Header.tsx # 站点页头 │ └── Footer.tsx # 站点页脚 ├── i18n/ # 国际化LanguageProvider / useLanguage ├── lib/ # 工具函数useDocumentTitle 等 ├── router.tsx # 根布局 路由切换 └── main.tsx # 应用入口关键约定components/ui/下的组件来自 shadcn/ui 与 Magic UI是生成品而非手写品。AGENTS.md 明确要求do NOT hand-editsrc/components/ui/files所有底层组件都应通过 CLI 添加避免与官方 registry 的后续升级产生冲突。文档页统一放在src/pages/docs/section/topic/page.tsxsection 目前为三个分类introduction介绍、features功能特性、advanced高级。每个page.tsx默认导出一个 React 组件由路由表挂载。站点级组件Header/Footer与文档页的Layout分离前者在根路由上下文中渲染后者是 docs 嵌套路由的专属外壳。三、组件开发规范shadcn/ui 优先3.1 组件选择优先级AGENTS.md 强调一条铁律ALWAYS prefer shadcn/ui components over custom implementations。在自研任何 UI 组件之前先检查 shadcn 是否已提供对应能力。只有当 shadcn 与 Magic UI 都没有合适的组件时才在src/components/下自行实现并单独归入 custom 分类。3.2 添加组件的命令新增 shadcn/ui 或 Magic UI 组件必须在packages/website/目录内执行而不是仓库根这与components.json中配置的magicuiregistry 指向一致# 重要必须在 packages/website/ 目录下执行而不是仓库根目录 cd packages/website # 添加一个新的 shadcn 组件 npx shadcnlatest add component-name # 添加一个 Magic UI 组件 npx shadcnlatest add magicui/component-name关于 Magic UI 的 registry 配置可在 components.json 中看到{ $schema: https://ui.shadcn.com/schema.json, style: new-york, rsc: false, tsx: true, iconLibrary: lucide, aliases: { components: /components, utils: /lib/utils, ui: /components/ui, lib: /lib, hooks: /hooks }, registries: { magicui: https://magicui.design/r/{name}.json } }这里有几个要点style: new-york决定了 shadcn/ui 生成组件的代码风格iconLibrary: lucide让生成的组件默认使用 lucide-react 图标路径别名统一为/对应src/由 tsconfig.json 的paths: { /*: [./src/*] }与 vite.config.js 的resolve.alias双重声明。3.3 当前已启用的组件清单AGENTS.md 记录了三个来源的组件均可在 packages/website/src/components/ui 下找到对应文件来自 shadcn/uialert、badge、button、separator、sonner、switch、tooltip来自 Magic UIanimated-gradient-text、animated-shiny-text、aurora-texthyper-text、magic-card、neon-gradient-card、particlessparkles-text、text-animate、typing-animation自定义实现highlighter基于 rough-notation 的手绘高亮、kbd键盘键位、spinner加载动画这些动效组件对应的关键帧动画如aurora、shiny-text、marquee、blink-cursor等在 src/index.css 的theme inline块中统一定义通过--animate-*变量暴露给 Tailwind 使用。3.4 样式编写规则AGENTS.md 的 Styling Rules 只有三条但直接决定代码风格优先 Tailwind 类而非自定义 CSS页面级样式尽量用原子类内联表达通过dark:前缀支持暗色模式网站采用 class-based dark modesrc/index.css 中通过custom-variant dark (:is(.dark *))启用由next-themes负责在html上切换.dark类主题色统一走 CSS 变量例如--background、--foreground、--primary、--muted等在 src/index.css 的:root与.dark两套定义中给出浅色为 oklch 中性色系深色为#0a0a0a/#ededed并在theme/theme inline中映射为--color-*最终经由layer base应用到body。此外 tailwind.config.js 中设置了important: #root确保网站样式优先级高于被引入页面例如 demo 页面自身的样式避免样式互相污染。而 src/index.css 顶部config ../tailwind.config.js将 Tailwind v4 与配置文件显式关联。四、路由设计wouter 嵌套上下文4.1 根路由base 路径与 hash 兼容应用入口 src/main.tsx 用 wouter 的Router base/page-agent包裹整个应用并额外处理了旧版 hash 路由的兼容重定向// main.tsx节选 const { hash } window.location if (hash.length 1 hash.includes(/)) { const path hash.replace(/^#\/?/, /) history.replaceState(null, , /page-agent path) } createRoot(document.getElementById(root)!).render( LanguageProvider Router base/page-agent PagesRouter / /Router /LanguageProvider )也就是说形如/#/docs/foo的旧链接会被重写为/page-agent/docs/foo后进入 wouter 的匹配流程。4.2 根布局与路由表src/router.tsx 是根布局与路由切换的枢纽结构如下Header / // 在 Switch 之外常驻 ScrollToTop / // 路由变化时 window.scrollTo(0,0) Switch Route path/…HomePage //Route // 首页 Route path/docs nest…DocsPages //Route // 文档区嵌套子路由 Route…404…/Route // 兜底 /Switch Footer / // 在 Switch 之外常驻AGENTS.md 强调的关键点与源码完全对应Header 和 Footer 位于Switch之外因此它们始终处于根路由上下文base/page-agent链接不会被嵌套路由的上下文吃掉文档区通过Route path/docs nest创建子路由上下文子上下文的 base 变为/page-agent/docs文档路由使用lazy(docsImport)动态加载并在挂载后通过requestIdleCallback或 setTimeout 兜底空闲预取兼顾首屏速度与后续跳转体验ScrollToTop组件借助useLocation()监听 pathname每次路由切换滚回顶部保证多页面文档的阅读连贯性。4.3 文档路由表与默认页src/pages/docs/index.tsx 导出DocsRouter在 docs 子上下文中继续用Switch匹配 15 个文档路由例如Route path/introduction/overview DocsPageOverview //DocsPage /Route Route path/features/models DocsPageModels //DocsPage /Route Route path/advanced/page-controller DocsPagePageControllerDocs //DocsPage /Route … Route path/docs DocsPageOverview //DocsPage // 访问 /docs 时默认展示 Overview /RouteDocsPage是统一的包装组件外层套DocsLayout侧边栏导航内层用Suspense包裹内容。注意最后一个Route path/docs是 wouter 的占位匹配由于子上下文 base 是/page-agent/docs当用户访问/page-agent/docs时会命中该路由并渲染 Overview。4.4 嵌套上下文下的链接规则这是最容易踩坑的地方AGENTS.md 用三条规则划清了边界docs 嵌套内Link 的 href 相对于/docs写例如侧边栏里写href/features/models而不是href/docs/features/models后者在 wouter 中会被解析为/page-agent/docs/docs/features/models而 404绝不要使用~前缀href~/xxx会绕过 base 路径直接按绝对路径解析导致部署到子路径后全部失效文档页标题用Heading idslug level{2}生成锚点组件实现见 src/components/Heading.tsx它按level映射 h2/h3/h4 的样式text-3xl/1.375rem/1.0625rem左侧悬浮#锚点链接并在window.location.hash命中时平滑滚动定位。在 src/pages/docs/Layout.tsx 中可以看到侧边栏导航的实际实现navigationSections定义了 Introduction / Features / Advanced 三组导航项当前路径通过useLocation()取到并与item.path比对高亮激活项useDocumentTitle(activeTitle)同步浏览器标题。侧边栏还针对 Chrome 扩展文档做了特殊渲染simple-icons的 Chrome 图标 SparklesText闪烁文本。布局整体为max-w-7xl容器 左侧w-64吸顶侧栏 右侧prose dark:prose-invert正文。4.5 国际化上下文src/i18n/context.tsx 提供LanguageProvider与useLanguage语言偏好持久化在localStorage首次访问按navigator.language是否以zh开头决定zh-CN或en-US。文档页与导航文案均通过isZh条件切换中英文见 src/pages/docs/Layout.tsx 与 Overview 页面。这解释了为什么文档page.tsx中会出现大量{isZh ? 中文 : English}三元表达式。五、GitHub Pages 上的 SPA路由兜底与 sitemap网站部署目标是 GitHub Pages 静态托管base: /page-agent/见 vite.config.js。静态服务器不执行 SPA 路由直接访问/page-agent/docs/features/models会 404因此项目没有采用 404.html 重定向方案而是用一个自定义 Vite 插件spaRoutes在构建收尾时把index.html复制进每个路由目录// vite.config.js节选 const SPA_ROUTES [ docs, docs/introduction/overview, docs/introduction/quick-start, docs/introduction/limitations, docs/introduction/troubleshooting, docs/features/custom-tools, docs/features/data-masking, docs/features/custom-instructions, docs/features/models, docs/features/local-llms, docs/features/chrome-extension, docs/features/mcp-server, docs/features/third-party-agent, docs/advanced/page-agent, docs/advanced/page-agent-core, docs/advanced/page-controller, docs/advanced/custom-ui, docs/advanced/security-permissions, ] function spaRoutes() { return { name: spa-routes, closeBundle() { // 1. 为每个 SPA_ROUTES 目录复制一份 index.html // 2. 同时生成 sitemap.xml含每个路由的 loc 与今天的 lastmod }, } }closeBundle钩子中完成两件事遍历SPA_ROUTESmkdirSync(dir, { recursive: true })后copyFileSync(dist/index.html, dir/index.html)基于SITE_URLhttps://alibaba.github.io/page-agent与路由列表生成sitemap.xml方便搜索引擎收录所有文档页面。因此每新增一个文档路由都必须把它的路径追加进SPA_ROUTES否则该页面只能从首页导航点击进入前端路由可用无法被直接访问或收录。构建时还会读取仓库根的.envdotenvConfig并把LLM_MODEL_NAME、LLM_API_KEY、LLM_BASE_URL注入import.meta.env仅 development 模式同时把packages/page-agent/package.json的version作为import.meta.env.VERSION注入用于在站点上展示版本信息。六、新增文档页的五步流程AGENTS.md 用 5 个步骤给出了新增文档页的标准操作这是本指南最具实操价值的部分创建页面文件在src/pages/docs/section/slug/page.tsx创建组件默认导出注册路由在 src/pages/docs/index.tsx 中import该组件并新增Route path/section/slug加入侧边栏导航在 src/pages/docs/Layout.tsx 的navigationSections对应分组中新增{ title, path }条目追加 SPA 路由在 vite.config.js 的SPA_ROUTES数组中添加docs/section/slug保持 slug 全局一致文件夹名、import 路径、路由 path、侧边栏链接、以及文档间的交叉链接必须使用同一个 slug如果公开路由变更必须同步重命名文件夹。值得补充的细节步骤 1 中的section必须是introduction、features、advanced之一与docs/index.tsx的既有匹配一致页面内容建议使用article包裹标题使用Heading id... level{2}生成锚点若页面包含中英文内容应接入useLanguage()的isZh分支保持与 Overview 等现有页面一致的 i18n 风格。七、配置文件速查AGENTS.md 汇总了三个核心配置文件结合源码补充说明如下文件用途关键内容components.jsonshadcn/ui 配置new-york 风格、/别名、magicuiregistry、lucide 图标库vite.config.jsVite 构建 SPA 路由base: /page-agent/、spaRoutes插件、SPA_ROUTES、sitemap 生成、vendor 分包、.env注入tsconfig.jsonTypeScript 配置继承根 tsconfig.base.json声明/*路径别名include限定src/**八、常用命令AGENTS.md 给出的命令全部从仓库根目录执行通过 npm workspace 转发到 website 包npm start # 启动官网开发服务器等价于 npm run dev --workspacepage-agent/website npm run build:website # 构建官网产物等价于 npm run build:website --workspacepage-agent/website与 packages/website/package.json 的脚本对照npm start实际执行vite --host 0.0.0.0监听所有网卡便于局域网预览build:website执行vite build构建结束后由spaRoutes插件完成 SPA 路由复制与 sitemap 生成。此外npm run previewvite preview可在本地预览构建产物npm run typecheck仓库根会连同 website 一起做 TypeScript 全量检查。九、给维护者的补充提醒结合 AGENTS.md 与源码最后整理几条容易被忽视的维护要点严禁手工编辑src/components/ui/该目录是 shadcn/ui 与 Magic UI 的生成区升级组件应通过npx shadcnlatest重新添加或官方迁移指引完成任何路由改动都要三处同步docs/index.tsx的路由表、Layout.tsx的导航项、vite.config.js的SPA_ROUTES三者任一遗漏都会造成能进导航但直接访问 404或反之的问题链接书写遵循上下文docs 嵌套内 href 相对/docs全局避免~前缀暗色模式是硬性要求新页面样式必须提供dark:变体并复用 src/index.css 中的 CSS 变量而不是硬编码色值仓库根目录的.env承载 LLM 演示配置LLM_MODEL_NAME/LLM_API_KEY/LLM_BASE_URL仅在开发模式注入构建产物不会携带密钥。以上内容可作为 page-agent 官网二次开发与维护的完整参考。若要继续深入某个文档主题的页面实现可直接阅读 packages/website/src/pages/docs 下对应目录的page.tsx例如 Overview 文档页 展示了页面结构、中英文切换与卡片布局的标准写法。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考