AG Kit Web 门户开发指南基于 Next.js 16 与 React 19 的文档站与交互仪表盘【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kitAG Kit 是一个面向 AI Agent 的工程套件除了提供 CLI 向项目注入.agents/工作区含 Skills、Agents、Workflows还维护了一个基于Next.js 16 (App Router)与React 19构建的官方在线文档站与交互式仪表盘门户位于仓库的 web/ 目录。本文以 web/README.md 为骨架结合仓库源码讲解该门户的技术栈、本地开发流程、构建配置、文档导航与多语言机制帮助你快速上手这套文档系统的二次开发与本地部署。一、web 目录在 AG Kit 中的定位AG Kit 仓库采用“CLI 工具包 Web 文档门户”的双目录结构cli/负责npx vudovn/ag-kit init的安装、更新与回滚逻辑核心实现见 cli/lib/managed-tree.jsweb/官方在线文档与仪表盘门户是 AG Kit 面向开发者的“门面”。根据 web/README.mdweb 目录承载两类内容官方在线文档涵盖 Introduction、Installation、Agents、Skills、Workflows、Managed Updates、Antigravity Runtime、CLI Reference 及 10 个 Guide 实战示例交互式仪表盘以首页 Landing 页 文档区为主体数据由web/src/services/下的 JSON 文件驱动。门户的生产部署地址、SEO 元数据与站点地图在 web/src/app/layout.tsx、web/src/app/robots.ts 与 web/src/app/sitemap.ts 中统一定义站点基础 URL 为https://ag-kit.unikorn.vn/。二、架构与核心技术栈web/README.md 明确列出了门户的技术栈与 web/package.json 中的实际依赖一一对应层次技术选型实际版本见 web/package.json框架Next.js 16App Routernext^16.2.11UI 库React 19react19.2.3/react-dom19.2.3样式Tailwind CSS v4tailwindcss^4tailwindcss/postcss^4MDXnext/mdxnext/mdx16.2.10mdx-js/loader^3.1.1组件base-ui/react Lucide React 图标base-ui/react^1.1.0、lucide-react^0.562.0其他next-themes暗色/亮色切换、class-variance-authority、tailwind-merge、tw-animate-css见 devDependencies此外 devDependencies 中还引入了babel-plugin-react-compiler1.0.0、gray-matter、shiki与rehype-pretty-code前者配合 web/next.config.ts 中的reactCompiler: true启用 React Compiler 自动记忆化后者为 MDX 代码块提供基于 Shiki 的高亮渲染。三、快速开始本地开发三步走web/README.md 给出的本地开发流程非常简洁在仓库根目录下进入web/目录执行npm install # 1. 安装依赖 npm run dev # 2. 启动本地开发服务器然后打开浏览器访问http://localhost:3000即可预览文档门户。对应的脚本定义在 web/package.json 的scripts字段{ dev: next dev, build: next build --webpack, start: next start, lint: eslint . --max-warnings0, typecheck: tsc --noEmit }其中build显式指定--webpack构建器区别于默认的 Turbopack 构建lint采用--max-warnings0的零警告策略配合 web/eslint.config.mjs 保证代码质量门禁。环境要求从 web/package.json 的engines相关依赖与根目录 README.md 的 Requirements 一节可以推断构建该门户需要Node.js 22 或更新版本仓库级 Antigravity 工具链要求 Node.js 22发布版 CLI 本身支持 Node.js 18。四、构建配置深度解析next.config.tsweb/next.config.ts 是整个门户构建行为的“总开关”值得逐项拆解1. MDX 插件管线通过createMDX()配置完整的 markdown 处理链const withMDX createMDX({ options: { remarkPlugins: [[remark-gfm]], // 支持表格、删除线等 GFM 语法 rehypePlugins: [ [rehype-slug], // 为标题生成锚点 id [rehype-pretty-code, { theme: github-dark-default, keepBackground: false }], [rehype-autolink-headings, { behavior: wrap, properties: { className: [heading-anchor] } }], ], }, });pageExtensions同时注册了md/mdx扩展名配合mdx-js/loader让文档内容可以直接以 MDX 文件形式挂在路由下见下文多语言文档一节。2. 全站安全响应头对/(.*)全局路由注入 7 组安全头包括 CSPbase-uri self、frame-ancestors none、object-src none、Referrer-Policy: strict-origin-when-cross-origin、X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Permissions-Policy禁用摄像头/麦克风/地理位置以及Cross-Origin-Opener-Policy: same-origin与 HSTS。这是文档站生产环境安全基线的一部分。3. 部署形态与图片域名白名单output: standalone构建产物为可独立运行的 Node 服务便于容器化部署仓库根目录的 Dockerfile 即按此形态打包images.remotePatterns仅放行img.vietqr.io的越南 MBBank 二维码图片用于捐赠展示其余外部图片一律拒绝。五、根布局SEO、JSON-LD 与全局 Providerweb/src/app/layout.tsx 定义了门户的全局元数据与结构metadata默认标题模板%s | AG Kitdescription 明确写有“47 skills, 20 specialist agents”并配置了manifest.webmanifest、favicon、Apple touch icon/images/logo.png、Open Graph 与 Twitter Card 图片/images/og-image.pngJSON-LD 结构化数据内联注入WebSite与SoftwareApplication两种 Schema.org 实体方便搜索引擎理解站点与软件本体applicationCategory: DeveloperApplication、offers.price: 0等全局 Provider 嵌套ThemeProvider默认暗色、跟随系统、禁用切换过渡动画I18nProvider包裹全部子路由。首页 web/src/app/page.tsx 则由 web/src/components/landing/ 下的 Hero、Sponsors、Benefits、Features、Workflows、Testimonials、Sponsored、Contribute、FAQ 等 10 个 Landing 组件按序拼装构成仪表盘的落地页。六、文档区布局侧边栏、目录与分页导航文档区采用经典的“三栏式”布局见 web/src/app/docs/layout.tsx左侧 SidebarDocsSidebar桌面端lg断点以上显示宽度 256px吸顶滚动中间主内容区最大宽度max-w-4xl底部挂载DocsPager提供上一篇/下一篇翻页右侧 TOCTocxl断点以上显示根据当前页面标题生成目录。导航的单一事实来源所有文档链接集中维护在 web/src/lib/docs-nav.ts该文件注释明确写着“Single source of truth for docs navigation. Consumed by the sidebar, mobile menu, search dialog, and prev/next pager.”侧边栏、移动端菜单、搜索对话框、上下页分页器共用的唯一数据源。导航共分四组Getting Started/docsIntroduction、/docs/installationCore ConceptsAgents、Skills、Workflows、Managed Updates Rollback、Antigravity RuntimeGuide10 个实战示例brainstorm、plan、create、new-feature、debugging、test、preview、status、orchestration、deployment每个示例都有content.en.mdx与多语言版本CLI ReferenceCommands Options、Changelog。每个导航项还带有keywords字段供 web/src/components/layout/header/components/search-dialog.tsx 实现站内搜索文档首页提示可按下CtrlK唤起。七、多语言文档机制LocalizedDoc 与 MDX 内容分离Guide 示例采用“页面组件 多语言内容”的分离模式。以 web/src/app/docs/guide/examples/brainstorm/ 为例content.en.mdx # 英文正文 content.ja.mdx # 日文正文 content.vi.mdx # 越南文正文 content.zh.mdx # 中文正文 page.tsx # 页面壳web/src/components/docs/localized-doc.tsx 负责按当前激活的 locale 选择渲染哪份内容export default function LocalizedDoc({ en, vi, zh, ja }: LocalizedDocProps) { const { locale } useI18n(); const byLocale { en, vi, zh, ja }; return {byLocale[locale] ?? en}/; // 缺少翻译时回退英文 }其注释特别说明每个语言分支都在服务端渲染组件只负责“选择展示哪一个”因此切换语言无需重新加载页面。i18n 字典定义在 web/src/i18n/ 下dictionaries.ts、landing-dictionaries.ts、locale-store.ts、provider.tsx配合 web/src/app/docs/installation/content.tsx 这类“以字典驱动页面文案”的交互式页面使用该页文案全部来自t.installPage.*含面包屑、标题、Callout 提示等。八、数据驱动的仪表盘内容首页与文档页的“20 个 Agent、47 个 Skill、13 个 Workflow”数字并非硬编码而是从 web/src/services/ 的 JSON 读取数据文件条目数用途web/src/services/agents.json20领域专家 Agent 定义Frontend、Backend、Security、PM、QA 等web/src/services/skills.json47领域知识模块与条件加载规则web/src/services/workflows.json13预配置的交互式斜杠命令web/src/app/docs/page.tsx 中直接import agents from /services/agents.json并用agents.length渲染统计卡片。需要注意web/README.md 中表格写的是 Skills45个而当前仓库中 web/src/services/skills.json 实际为47个根目录 README.md 与 layout.tsx 的 metadata 也均为 47。撰写文档引用数量时请以仓库实际数据为准。CLI 安装产物对照web/README.md 还说明了下游开发者执行npx vudovn/ag-kit init后项目根目录得到的.agents/结构目录数量说明agent/20专业 AI Agent 配置前端、后端、安全、PM、QA 等skills/45/47领域上下文模块带条件加载规则当前仓库数据为 47workflows/13预配置的交互式斜杠命令这与根目录 README.md 的 Included components 表格Agents 20、Skills 47、Workflows 13、Rules 6、Memory topics 4index相互印证完整的目录结构与描述还可见安装页 web/src/app/docs/installation/content.tsx 中的.agents/树形示例agent/、skills/、workflows/、rules/、ARCHITECTURE.md。九、SEO 与站点地图门户对搜索引擎做了完整配置web/src/app/robots.tsuserAgent: *全量放行并声明sitemap: https://ag-kit.unikorn.vn/sitemap.xmlweb/src/app/sitemap.ts列出首页、/docs系列与 10 个 Guide 示例共 20 条路由/docs/changelog为weekly更新频率首页 priority 为 1web/src/app/manifest.ts提供 PWA Web App Manifest。十、本地部署与发布流程小结将门户用于本地或自托管场景只需遵循官方文档的流程# 在 web/ 目录下 npm install npm run dev # 开发http://localhost:3000 npm run lint # 零警告 ESLint 检查 npm run typecheck # TypeScript 类型检查 npm run build # 生产构建--webpackstandalone 输出 npm start # 启动生产服务构建前建议先通过lint与typecheck两道关卡这与根目录 README.md 中“Web lint, typecheck, build, and audit”的发布门禁一致。结语AG Kit 的 Web 门户是一个典型的“Next.js 16 React 19 Tailwind v4 MDX base-ui/react”现代文档站工程web/README.md 提供了简洁的启动入口而源码层则展示了 MDX 插件管线、安全响应头、standalone 部署、JSON-LD 结构化数据、多语言文档切换、数据驱动仪表盘与单一来源导航等一整套可复用的工程实践。无论你是要本地预览文档、为门户新增 Guide 页面还是将这套架构模式移植到自己的项目都可以从 web/src/app/、web/src/components/ 与 web/src/lib/docs-nav.ts 出发按本文梳理的脉络逐层深入。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考