ai-learning-platform/AGENTS.md

AGENTS.md — 项目知识库（AI 专用）

每次任务前先读此文件。维护项目关键上下文，避免重复探索。

项目概览

宇之然 AI 学习与实践平台。前端 Next.js + shadcn/ui，后端 NestJS + PostgreSQL。

项目	值
品牌	宇之然（北京宇之然科技中心）
域名	yuzhiran.com
前端	frontend/, port 3000, Next.js App Router
后端	backend/, port 4000, NestJS
CSS	Tailwind CSS + shadcn/ui 暗黑模式

技术栈约定

前端

• 框架: Next.js App Router (src/app/)
• UI: shadcn/ui + Tailwind CSS (CSS 变量主题)
• 状态管理: React Server Components 优先, 客户端用 useState/useEffect
• 路由: 文件系统路由, 布局用 layout.tsx, 加载用 loading.tsx, 错误用 error.tsx
• 暗黑模式: next-themes + Tailwind 暗类策略 (darkMode: 'class')

后端

• 框架: NestJS 模块化架构
• ORM: TypeORM + PostgreSQL（schema 在 database/migrations/）
• 认证: JWT + Passport
• API 前缀: /api/v1
• CORS: origin: true, maxAge: 0（避免浏览器预检缓存）

UI/UX 统一规则

• 容器: 内容页 max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12；法律/文本页用 max-w-3xl
• 标题: text-3xl font-bold text-foreground
• 副标题: <p className="mt-2 text-muted-foreground">...</p>
• 颜色: 全站禁用 text-gray-* / bg-gray-* / border-gray-* 硬编码 —— 使用 CSS 变量：
  • 前景色 → text-foreground / text-muted-foreground
  • 背景 → bg-card / bg-muted/50 / bg-accent
  • 边框 → border-border
  • hover → hover:text-foreground / hover:bg-accent
• 国际化: 所有用户可见文本使用 useT() hook，翻译 key 位于 src/i18n/locales/。新增页面先加翻译 key 再写 UI。中文默认，英文同步维护。

关键架构决策

决策	方案	原因
CORS	origin: true + maxAge: 0	避免预检缓存, 开发灵活
Favicon	public/favicon.png + app/icon.svg	.ico 与 output: 'export' 不兼容
静态导出	output: 'export'	部署到静态托管
Sandbox 布局	h-[calc(100vh-4rem)] flex flex-col	固定头尾, 消息区滚动
流式聊天	ReadableStream fetch API	实时 AI 响应
法律页面	max-w-3xl 窄容器	长文本可读性
模型列表	frontend/src/lib/models.ts	全站唯一数据源，3 个页面统一导入
颜色约定	全站禁用 text-gray-* / bg-gray-* / border-gray-*	必须使用 CSS 变量
学情分析	GET /api/v1/learning/analytics + GET /api/v1/learning/path	基于对话知识度分析

后端关键 API

端点	说明
POST /api/v1/auth/register	注册
POST /api/v1/auth/login	登录
GET /api/v1/search?q=xxx	搜索（返回 { results: [...] }，不是 items）
GET /api/v1/users/:id	用户信息
POST /api/v1/chat/completions	AI 流式对话
GET /api/v1/enterprise/...	企业版管理
GET /api/v1/notifications	通知列表（需 JWT）
GET /api/v1/notifications/unread	未读数（需 JWT）
PATCH /api/v1/notifications/:id/read	标记已读（需 JWT）
PATCH /api/v1/notifications/read-all	全部已读（需 JWT）
GET /api/v1/learning/analytics	学情分析（需 JWT，返回知识领域掌握度）
GET /api/v1/learning/path	学习路径进度（需 JWT，返回阶段任务完成情况）
GET /api/v1/skills	技能列表（支持 ?category= / ?difficulty= / ?search= 过滤）
GET /api/v1/skills/:id	技能详情（含 system prompt、练习任务、starter 问题）
GET /api/v1/skills/categories	技能分类列表
GET /api/v1/skills/difficulties	难度等级列表

关键上下文（Critical Context）

• search.service.ts 返回 results 而非 items —— 写测试时注意
• users.service.ts 的 if (status) 曾误写为 if (params.status)（已修复）
• 静态构建 (next build) 已修复 —— 所有动态路由都通过 server wrapper 模式导出 generateStaticParams()（60 页面全部生成）
• public/favicon.ico 和 app/favicon.ico 不能共存，会触发 500
• 数据库 schema 通过 TypeORM migration 管理, 位于 backend/src/database/migrations/

项目管理流程

每次任务遵循以下流程：

1. 任务开始前 — 读 AGENTS.md + docs/progress.md，了解当前进度和上下文
2. 规划阶段 — 分析需求，拆解为 TODO 列表，按优先级排序
3. 执行阶段 — 按 TODO 依次实施，每次完成后验证（lint/test/build）
4. 任务完成后 — 更新 docs/progress.md（更新阶段状态、补充完成项）
5. 归档 — 旧版 progress.md 移到 docs/archive/progress-YYYY-MM-DD.md
6. 提交 — 只有在用户明确要求时才创建 git commit

常用命令

# 前端开发
cd frontend && npm run dev

# 后端开发
cd backend && npm run start:dev

# 前端构建
cd frontend && npm run build

# 后端测试
cd backend && npm test
npm run test:e2e

---

此文件仅在架构/约定变更时更新。进度追踪见 docs/progress.md。

---

此文件仅在架构/约定变更时更新。进度追踪见 docs/progress.md。