Frontend AI Template

前端+AI工程模板

一个生产就绪的Next.js 15模板，具有多提供商AI集成、Jotai状态管理和MCP工具架构。

特性

• Next.js 15 使用App Router和Turbopack
• 多提供商AI -Google Gemini和OpenAI支持回退
• 佐敦州管理 -原子性、可扩展的状态，无需样板
• MCP工具 -AI工具编排的模型上下文协议
• TypeScript -具有全面类型定义的严格模式
• Tailwind CSS -实用性优先，响应式设计
• 测试 -Vitest用于单元测试，剧作家用于E2E
• 代码质量 -ESLint、Lefthok、Commitline

快速开始

# Clone the template
npx degit cheshirecode/frontend-ai-template my-ai-app
cd my-ai-app

# Install dependencies
npm install

# Set up environment
cp .env.example .env.local
# Add your API keys to .env.local

# Start development server
npm run dev

打开 http://localhost:3000 查看您的应用程序。

环境设置

至少需要一个AI提供商API密钥：

拿到你的钥匙：

• 双子座: 谷歌AI工作室 （免费版可用）
• 开放人工智能: OpenAI平台

项目结构

├── app/
│   ├── api/
│   │   ├── ai/          # AI chat endpoint
│   │   └── mcp/         # MCP tools endpoint
│   │       └── tools/   # Tool definitions
│   ├── components/
│   │   ├── chat/        # Chat UI components
│   │   ├── common/      # Shared components
│   │   ├── layout/      # Layout components
│   │   └── providers/   # React providers
│   ├── hooks/
│   │   ├── chat/        # Chat hooks
│   │   ├── composed/    # High-level hooks
│   │   └── core/        # Core state hooks
│   ├── lib/
│   │   ├── ai-service.ts    # AI provider abstraction
│   │   ├── error-handler.ts # Error utilities
│   │   └── logger.ts        # Structured logging
│   └── store/           # Jotai atoms
├── types/               # TypeScript definitions
├── e2e/                 # Playwright tests
└── docs/                # Documentation

可用脚本

npm run dev          # Start dev server with Turbopack
npm run build        # Production build
npm run start        # Start production server
npm test             # Run unit tests
npm run test:e2e     # Run E2E tests
npm run lint         # Lint code
npm run type-check   # TypeScript check

定制

添加AI工具

在中创建新工具 app/api/mcp/tools/:

// app/api/mcp/tools/my-tool.ts
import { MCPTool, MCPToolResult, ToolHandler } from './types'

export const myTool: MCPTool = {
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input parameter' }
    },
    required: ['input']
  }
}

export const handleMyTool: ToolHandler = async (params) => {
  // Implementation
  return { success: true, data: result }
}

注册于 app/api/mcp/tools/index.ts.

添加组件

组件遵循分解模式：

// app/components/feature/MyComponent.tsx
'use client'

import { useMyHook } from '@/hooks/feature/useMyHook'

interface MyComponentProps {
  title: string
}

export function MyComponent({ title }: MyComponentProps) {
  const { data, isLoading } = useMyHook()
  // ...
}

添加州

使用Jotai原子 app/store/:

import { atom } from 'jotai'

export const myAtom = atom('')
export const derivedAtom = atom((get) => get(myAtom).toUpperCase())

建筑

看 docs/ARCHITECTURE.md 获取详细的架构文档。

部署

Vercel（推荐）

npm run deploy:vercel

其他平台

构建并运行生产服务器：

npm run build
npm run start

贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 运行测试： npm test && npm run test:e2e
5. 提交拉取请求

许可证

麻省理工学院