SecondMe Next.js 项目生成
基于 /secondme-init 的配置和 /secondme-prd 的需求定义，生成完整的 Next.js 项目。
前置条件检查
1. 检查 state.json
首先检查 .secondme/state.json 是否存在：
- 不存在 → 提示：
请先运行 /secondme-init 初始化项目配置 - 存在 → 继续
2. 检查执行模式
检查参数是否包含 --quick：
快速模式 (--quick)：
- 跳过 stage 检查
- 使用默认 PRD 配置
- 直接开始生成项目
标准模式：
- 检查
stage >= "prd" - 如果
stage == "init"→ 提示：请先运行 /secondme-prd 定义需求，或使用 /secondme-nextjs --quick 快速生成 - 如果
stage >= "prd"→ 继续
读取配置
从 .secondme/state.json 读取：
const state = {
app_name: "secondme-tinder", // 应用名称
modules: ["auth", "chat", "profile"], // 已选模块
config: {
client_id: "71658da7-659c-414a-abdf-cb6472037fc2",
client_secret: "xxx",
redirect_uri: "http://localhost:3000/api/auth/callback",
redirect_uris: [...],
database_url: "postgresql://...",
allowed_scopes: [...]
},
api: {
base_url: "https://api.mindverse.com/gate/lab",
oauth_url: "https://go.second.me/oauth/",
token_endpoint: "https://api.mindverse.com/gate/lab/api/oauth/token/code",
refresh_endpoint: "https://api.mindverse.com/gate/lab/api/oauth/token/refresh",
access_token_ttl: 7200,
refresh_token_ttl: 2592000
},
docs: {
quickstart: "https://develop-docs.second.me/zh/docs",
oauth2: "...",
api_reference: "...",
errors: "..."
},
prd: {
summary: "应用概要",
features: ["功能1", "功能2"],
design_preference: "简约现代"
}
}重要： 所有 API 端点、文档链接均从 state.api 和 state.docs 读取，不要硬编码。
前端设计要求
重要： 在构建前端界面时，必须使用 frontend-design:frontend-design skill 来生成高质量的 UI 组件。
设计原则：
- 亮色主题：仅使用亮色/浅色主题，不使用暗色/深色主题
- 简约优雅：遵循极简设计理念，减少视觉噪音
- 产品特性驱动：UI 设计应紧密结合要实现的功能特性
- 现代感：采用当下流行的设计趋势，避免过时的 UI 模式
- 一致性：保持整体视觉风格统一
- 响应式：适配各种屏幕尺寸
- 中文界面：所有用户可见的文字（按钮、提示、标签、说明等）必须使用中文
- 稳定优先：避免复杂动画效果，仅使用简单的过渡动画（如 hover、fade），确保界面稳定流畅
项目生成流程
1. 初始化 Next.js 项目
在当前目录直接初始化 Next.js 项目：
npx create-next-app@latest . --typescript --tailwind --app --src-dir --import-alias "@/*" --yes2. 安装依赖
npm install prisma @prisma/client
npx prisma init3. 生成.env.local
从 state.config 和 state.api 生成环境变量：
# SecondMe OAuth2 配置
SECONDME_CLIENT_ID=[config.client_id]
SECONDME_CLIENT_SECRET=[config.client_secret]
SECONDME_REDIRECT_URI=[config.redirect_uri]
# 数据库
DATABASE_URL=[config.database_url]
# SecondMe API（从 state.api 读取）
SECONDME_API_BASE_URL=[api.base_url]
SECONDME_OAUTH_URL=[api.oauth_url]
SECONDME_TOKEN_ENDPOINT=[api.token_endpoint]
SECONDME_REFRESH_ENDPOINT=[api.refresh_endpoint]4. 生成 Prisma Schema
根据已选模块动态生成 prisma/schema.prisma。
auth 模块（必有）- User 表必须包含的字段
User 表必须包含 Token 相关字段用于存储和刷新用户凭证：
model User {
id String @id @default(cuid())
secondmeUserId String @unique @map("secondme_user_id")
accessToken String @map("access_token")
refreshToken String @map("refresh_token")
tokenExpiresAt DateTime @map("token_expires_at")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
// 其他字段根据模块需求自行添加
@@map("users")
}其他模块
根据已选模块（profile、chat、note）的实际需求，自行设计相应的数据库表结构和关联关系。
5. 生成代码
根据已选模块生成对应代码：
auth 模块
| 文件 | 说明 |
|---|---|
src/app/api/auth/login/route.ts | OAuth 登录跳转 |
src/app/api/auth/callback/route.ts | OAuth 回调处理 |
src/app/api/auth/logout/route.ts | 登出处理 |
src/lib/auth.ts | 认证工具函数 |
src/components/LoginButton.tsx | 登录按钮组件 |
profile 模块
| 文件 | 说明 |
|---|---|
src/app/api/user/info/route.ts | 获取用户信息 |
src/app/api/user/shades/route.ts | 获取兴趣标签 |
src/components/UserProfile.tsx | 用户资料组件 |
chat 模块
| 文件 | 说明 |
|---|---|
src/app/api/chat/route.ts | 流式聊天 API |
src/app/api/sessions/route.ts | 会话列表 API |
src/components/ChatWindow.tsx | 聊天界面组件 |
act 模块
| 文件 | 说明 |
|---|---|
src/app/api/act/route.ts | 流式动作判断 API（结构化 JSON 输出） |
src/lib/act.ts | Act API 工具函数（发送 actionControl、解析 SSE JSON 结果） |
note 模块
| 文件 | 说明 |
|---|---|
src/app/api/note/route.ts | 添加笔记 API |
6. 更新 state.json
{
"stage": "ready",
...
}技术栈
- 框架： Next.js 14+ (App Router)
- 语言： TypeScript
- 样式： Tailwind CSS
- 数据库 ORM： Prisma
- 前端设计： 使用
frontend-design:frontend-designskill 生成 - API 调用： fetch
- 状态管理： React hooks
- 运行端口： 必须使用 3000 端口
常见问题与注意事项
CSS @import 顺序问题
问题： 在 globals.css 中使用 @import url(...) 引入 Google Fonts 会导致构建失败。
错误信息：
@import rules must precede all rules aside from @charset and @layer statements原因： Tailwind CSS 的 @import "tailwindcss" 展开后生成大量规则，导致后续的 @import url(...) 不再是第一个。
正确做法：
- 使用
<link>标签（推荐）： 在layout.tsx中引入<head> <link rel="preconnect" href="https://fonts.googleapis.com" /> <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet" /> </head> - 使用
next/font（最佳实践）：import {Noto_Sans_SC} from 'next/font/google' const notoSans = Noto_Sans_SC({subsets: ['latin'], weight: ['400', '500']})
构建验证
重要： 每次完成代码修改后，必须运行以下命令验证构建：
npm run build特别关注：
- CSS 解析错误
- TypeScript 类型错误
- 导入路径错误
WebView OAuth 认证问题
问题： 在 WebView 环境中（如移动端 App 内嵌页面、微信小程序等），OAuth state 验证可能失败，因为 WebView 与系统浏览器之间的存储不共享。
解决方案： 使用宽松的 state 验证，验证失败时记录警告但继续处理登录流程。
// 之前：验证失败直接拒绝
if (!isValidState) {
return NextResponse.redirect('/?error=invalid_state');
}
// 之后：验证失败记录警告，继续处理
if (!isValidState) {
console.warn('OAuth state 验证失败，可能是跨 WebView 场景');
// 继续处理，不阻止登录
}注意： 这种方式降低了 CSRF 防护，仅建议在可信的 WebView 环境中使用
输出结果
✅ Next.js 项目已生成！
已生成模块: auth, chat, profile
数据库: PostgreSQL
启动步骤:
1. npm install
2. npx prisma db push
3. npm run dev
项目将在 http://localhost:3000 启动API 响应格式
重要：所有 SecondMe API 响应都遵循统一格式：
{
"code": 0,
"data": { ... }
}本地路由与上游 API 的关系： Next.js 本地路由（如/api/secondme/user/shades）作为代理层， 将请求转发到上游 SecondMe API（{state.api.base_url}/api/secondme/...），并透传上游的响应格式。 前端代码调用本地路由即可，无需直接访问上游 API。
前端代码必须正确提取数据：
// ✅ 正确写法（调用 Next.js 本地路由，响应格式与上游一致）
const response = await fetch('/api/secondme/user/shades');
const result = await response.json();
if (result.code === 0) {
const shades = result.data.shades;
shades.map(item => ...)
}官方文档
从 state.docs 读取文档链接：
| 文档 | 配置键 |
|---|---|
| 快速入门 | docs.quickstart |
| OAuth2 指南 | docs.oauth2 |
| API 参考 | docs.api_reference |
| 错误码 | docs.errors |