172 lines
10 KiB
Markdown
172 lines
10 KiB
Markdown
# 追光AI 项目开发规则
|
||
|
||
## 端口规范
|
||
- 应用端口范围: **8301-8310**（预留扩展）
|
||
- 默认端口: **8301**
|
||
- 重启脚本仅扫描8301-8310范围
|
||
- **强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品**
|
||
|
||
## 服务器与基础设施
|
||
- **域名**: www.zhuig.com (HTTPS，SSL证书自动续期)
|
||
- **云服务器**: 119.45.242.239 (登录名: ubuntu, 密钥: E:\ZG_Dev\pem\zg.pem)
|
||
- **数据库**: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
|
||
- **Redis**: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
|
||
- **本地Git同步目录**: K:\git-repos
|
||
- **开发机**: E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai
|
||
- **部署目录**: /home/ubuntu/zhuiguang-ai
|
||
- **访问地址**: https://www.zhuig.com (HTTP自动跳转HTTPS)
|
||
- **注意事项**: 服务器有其他应用运行，部署时不可占用非8301-8310端口，不可影响其他服务
|
||
|
||
## 技术栈
|
||
- Next.js 14 (App Router) + TypeScript
|
||
- Tailwind CSS + shadcn/ui
|
||
- Prisma 7.8 + MySQL (阿里云RDS)
|
||
- NextAuth.js v4 (Credentials Provider)
|
||
- DeepSeek API (deepseek-v4-pro) — 用于技能五维评测生成（服务端脚本调用）
|
||
|
||
## 代码风格
|
||
- 不添加注释（除非明确要求）
|
||
- 使用中文作为UI文案和提示词语言
|
||
- TypeScript严格模式，零编译错误
|
||
- 组件使用 `"use client"` 标记客户端组件
|
||
- 路径别名: `@/*` → `./src/*`
|
||
- **禁止在代码中硬编码任何AI API Key**
|
||
- **禁止在代码中调用任何外部AI API（DeepSeek、OpenAI等）** — 前台/后台页面代码中禁止调用；服务端脚本(scripts/)中允许通过环境变量调用DeepSeek API和GitHub API
|
||
- 所有发现/导入功能通过页面提示词+JSON粘贴方式完成，不调用外部接口
|
||
|
||
## 构建与检查
|
||
- 修改代码后必须运行 `npx tsc --noEmit` 确认零错误
|
||
- 重启服务使用 `pwsh -ExecutionPolicy Bypass -File restart.ps1`
|
||
- 开发服务器: `npm run dev` (端口8301)
|
||
|
||
## 数据库
|
||
- 云数据库: 阿里云RDS MySQL
|
||
- 连接: `mysql://mohe001:***@rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai`
|
||
- Prisma单例模式防止热重载多实例
|
||
- 修改Schema后: `npx prisma migrate dev --name <描述>`
|
||
|
||
## 认证
|
||
- 管理员: admin@zhuiguang.ai / admin123
|
||
- JWT Session策略
|
||
- middleware.ts保护/admin路由（跳过/admin/login）
|
||
- 后台API需requireAdmin中间件验证（src/lib/admin-auth.ts）
|
||
- 用户注册/登录: NextAuth Credentials Provider，支持邮箱+密码
|
||
|
||
## API约定
|
||
- 前台API: `/api/` 前缀，无需认证
|
||
- 后台API: `/api/admin/` 前缀，需NextAuth认证
|
||
- 分页参数: `page`(默认1), `pageSize`(默认20)
|
||
- 返回格式: `{ data, total, page, pageSize }` 或 `{ success, error }`
|
||
- 批量操作: body中传 `ids` 数组
|
||
|
||
## 页面路由
|
||
- 前台: `/`, `/tools`, `/tools/[slug]`, `/categories/[slug]`, `/skills`, `/skills/[slug]`, `/login`, `/user`, `/user/favorites`
|
||
- 后台: `/admin/login`, `/admin/pending`, `/admin/pending-skills`, `/admin/tools`, `/admin/skills`, `/admin/categories`, `/admin/skill-categories`, `/admin/discover-tools`, `/admin/check-tools`, `/admin/discover-skills`, `/admin/update-skills`, `/admin/discover-news`, `/admin/system-config`
|
||
|
||
## 五大操作指令
|
||
|
||
用户使用以下五个命令时，必须跳转到对应页面理解流程并按流程执行。
|
||
所有页面均为"提示词+JSON粘贴导入"模式，不调用任何外部AI API。
|
||
|
||
### 探索AI工具
|
||
- 页面: `/admin/discover-tools`
|
||
- 流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表 → 抓取Logo
|
||
- 导入API: POST `/api/admin/discover-tools` body: `{ tools: [...], categoryId }`
|
||
- API接收前端提交的工具JSON数组，自动去重导入待审核列表
|
||
- Logo抓取API: POST `/api/admin/pending/fetch-logos`
|
||
- 工具分类(20个): 文本生成(165), 图像生成(174), 视频生成(183), 音频与语音(191), 代码开发(199), AI Agent(208), 办公效率(216), 设计与创意(224), 营销与SEO(231), 数据分析(238), 教育与学习(245), 搜索与信息(252), 安全与合规(258), 医疗健康(264), 金融与法律(270), 电商与零售(276), 3D与游戏(282), 科学研究(288), 模型与框架(294), 聊天机器人(302)
|
||
|
||
### 检测AI工具
|
||
- 页面: `/admin/check-tools`
|
||
- 流程: 选择范围(已发布/待审核) → 一键检测+抓取Logo → 处理失效工具
|
||
- 检测API: POST `/api/admin/check-tools` body: `{ type: "published" | "pending" }`
|
||
- 系统自动逐一GET请求检测网站可访问性，同时自动抓取缺失Logo并记录成功方法名
|
||
- 删除API: DELETE `/api/admin/tools/{id}` / `/api/admin/pending/{id}`
|
||
|
||
### 探索AI技能
|
||
- 页面: `/admin/discover-skills`
|
||
- 流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表
|
||
- 导入API: POST `/api/admin/discover-skills` body: `{ skills: [...], categoryId }`
|
||
- API接收前端提交的技能JSON数组，自动去重导入待审核列表
|
||
- 技能分类(20个父分类): 代码生成(1), 测试(10), 代码质量与分析(20), 安全(29), 文档(36), 架构与设计(43), 需求工程(49), DevOps与部署(56), 调试与错误处理(62), 形式化验证(69), 维护与重构(76), 版本控制与协作(82), 开发工具(86), UI/UX设计(91), 科学研究(95), 金融(103), 云服务(109), 移动开发(115), AI/ML工程(120), 营销与增长(127)
|
||
|
||
### 更新Skill技能
|
||
- 页面: `/admin/update-skills`
|
||
- 流程: 选择范围(已发布/待审核) → 一键更新 → 自动同步星级
|
||
- 更新API: POST `/api/admin/update-stars` body: `{ type: "published" | "pending" }`
|
||
- 系统自动从GitHub/Gitee/GitCode API获取最新星级评分并写入数据库
|
||
|
||
### AI新闻发现
|
||
- 页面: `/admin/discover-news`
|
||
- 流程: 复制提示词发给AI → 粘贴JSON → 导入今日新闻
|
||
- 导入API: POST `/api/admin/discover-news` body: `{ items: [...] }`
|
||
- API接收前端提交的新闻JSON数组，自动生成今日AI日报
|
||
- 新闻分类: 产品发布/融资投资/技术突破/政策法规/开源项目/行业事件
|
||
|
||
### 通用执行规则
|
||
1. **禁止调用任何外部AI API**，所有发现/导入功能通过页面提示词+JSON粘贴方式完成
|
||
2. 页面提供提示词模板（含排除列表），用户复制发给AI助手获取JSON，粘贴到页面导入
|
||
3. 导入API接收JSON数组，自动去重（名称+网址），导入待审核列表
|
||
4. 导入工具后建议执行Logo抓取，确保所有工具有图标
|
||
5. 所有提示词要求: 优先推荐国产AI工具/技能，国内可直连，中文友好
|
||
6. 检测工具时：系统自动GET请求检测网站可访问性，同时抓取缺失Logo
|
||
7. 更新技能时：系统自动从GitHub/Gitee/GitCode API获取最新星级
|
||
|
||
## 设计系统
|
||
- 浅色主题，HSL CSS变量
|
||
- 圆角: rounded-xl / rounded-2xl
|
||
- 边框: border-border/40 (40%透明度)
|
||
- 背景: bg-white/80 (毛玻璃) / bg-white/60 (卡片) / bg-muted/50 (输入框)
|
||
- 阴影: shadow-sm (卡片) / shadow-md (悬浮)
|
||
- 动画: transition-all duration-200
|
||
- 自定义工具类: .glow-sm, .gradient-text, .glass, .card-shine, .dot-grid, .animate-fade-in
|
||
- 颜色规范: 文字用 -600/-700 (非-400)，背景用 -50 (非-500/10)，边框用 -200/60 (非-500/20)
|
||
- 输入框: bg-muted/50 focus:bg-white focus:ring-2 focus:ring-primary/10
|
||
|
||
## 环境变量
|
||
- GITHUB_TOKEN: GitHub Personal Access Token（可选，提升API限流从60→5000次/小时）
|
||
- DEEPSEEK_API_KEY: DeepSeek API Key（用于技能评测生成脚本、AI日报整理）
|
||
|
||
## 定时任务调度系统
|
||
- **后台管理**: `/admin/tasks`（任务中心）、`/admin/tasks/logs`（执行日志）、`/admin/tasks/[taskKey]`（单任务详情+统计）
|
||
- **数据模型**: TaskConfig（任务配置，含enabled/cronExpr/config）、TaskLog（执行历史，含status/duration/result/error）
|
||
- **种子数据**: `scripts/seed-task-configs.mjs` 初始化6个任务配置
|
||
- **手动触发**: `/admin/tasks` 页支持每个任务运行，也可通过 POST `/api/admin/tasks/run` 触发
|
||
- **API**:
|
||
- `GET/PUT /api/admin/tasks/configs` — 任务配置查询/更新
|
||
- `GET /api/admin/tasks/logs` — 任务执行日志（分页+按taskKey筛选）
|
||
- `POST /api/admin/tasks/run` — 手动触发任务执行
|
||
|
||
### 定时任务（Crontab）
|
||
所有6个定时任务全部经过TaskLog记录：
|
||
|
||
| 时间 | 任务 | 脚本 | TaskKey | 说明 |
|
||
|------|------|------|---------|------|
|
||
| 01:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars | 更新所有GitHub技能Stars数+日/周/月变化 |
|
||
| 03:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools | 检查网站/Lo4go可访问性+自动发布合格待审核工具 |
|
||
| 04:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot | 评测2个最热未评测GitHub技能(五维评测) |
|
||
| 05:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills | GitHub搜索≥1000 stars项目→DeepSeek预评测→入库PendingSkill |
|
||
| 06:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools | 36kr/IT之家/开源中国RSS→DeepSeek提取工具→入库PendingTool |
|
||
| 07:30 | AI日报 | `scripts/daily-news.mjs` | daily-news | 多源搜索真实新闻+DeepSeek整理格式→发布日报 |
|
||
|
||
- Crontab 位于服务器: `crontab -l`（ubuntu用户）
|
||
- 日志目录: `/home/ubuntu/zhuiguang-ai/logs/`（task1.log ~ task6.log）
|
||
|
||
## AI日报新闻源
|
||
- **36kr** RSS (https://36kr.com/feed) — 国内科技资讯
|
||
- **IT之家** RSS (https://www.ithome.com/rss/) — 国内科技资讯
|
||
- **开源中国** RSS (https://www.oschina.net/news/rss) — 开源动态
|
||
- **HackerNews** API — 海外AI/技术热点
|
||
- **Google News** RSS — 海外新闻（国内服务器可能无法访问）
|
||
- 流程: 搜索真实新闻 → AI关键词过滤 → 近2天筛选 → DeepSeek整理格式 → 入库发布
|
||
- **严禁让DeepSeek直接生成新闻内容**（会编造假新闻），必须基于真实新闻素材整理
|
||
|
||
## 踩坑记录
|
||
- Next.js 14不支持useActionState，登录页用原生表单POST
|
||
- Prisma MariaDB adapter需要连接字符串方式初始化
|
||
- 图片域名需在next.config.mjs中配置remotePatterns
|
||
- 热重载后需清除.next缓存: 删除.next目录后重启
|
||
- Chart.js组件需用dynamic import + ssr: false，不支持服务端渲染
|
||
- Prisma 7.8需通过PrismaMariaDb适配器初始化，不能直接new PrismaClient()
|
||
- 服务器环境SSL证书问题: 运行脚本需设置$env:NODE_TLS_REJECT_UNAUTHORIZED="0"
|