zhuiguangaikf/zhuiguang-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
722594858cfa36bc2c3f34ca198ee0a55fbe3412
zhuiguang-ai/.trae/rules/project_rules.md
T

13 KiB
Raw Blame History

追光AI 项目开发规则

端口规范

  • 应用端口范围: 8301-8310（预留扩展）
  • 默认端口: 8301
  • 重启脚本仅扫描8301-8310范围
  • 强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品

服务器与基础设施

  • 域名: www.zhuig.com (HTTPS，SSL证书自动续期)
  • 云服务器: 119.45.242.239 (登录名: ubuntu, 密钥: C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\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端口，不可影响其他服务
  • SSH连接示例: ssh -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" ubuntu@119.45.242.239
  • PM2管理: pm2 list / pm2 restart zhuiguang-ai / pm2 save
  • 其他应用: agent-system, nacos, zhuiguang-quant (部署时请勿影响)

技术栈

  • 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, /user/[id](会员空间), /user/collections, /daily, /reviews, /community, /community/[category], /community/topic/[id]
  • 后台: /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, /admin/tasks, /admin/tasks/logs, /admin/tasks/[taskKey], /admin/reviews

五大操作指令

用户使用以下五个命令时，必须跳转到对应页面理解流程并按流程执行。 所有页面均为"提示词+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）

所有7个定时任务全部经过TaskLog记录，由 scripts/cron-wrapper.sh 统一入口执行（自动加载 .env 环境变量、创建日志目录）：

时间 任务 脚本 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整理格式→发布日报
08:00 Task7 新闻推社区 scripts/task7-news-to-community.mjs task7-news-to-community 将当日日报新闻分发到社区4个板块（AI工具推荐/AI资讯/技术探讨/观点讨论）
  • Crontab 位于服务器: crontab -l（ubuntu用户），安装脚本: bash scripts/install-cron.sh
  • 统一入口: scripts/cron-wrapper.sh <TASK_NAME> <SCRIPT_PATH> — 自动加载 .env、创建日志目录、记录执行结果
  • 日志目录: /home/ubuntu/zhuiguang-ai/logs/（task1.log ~ task7.log, daily-news.log）
  • 关键: crontab 环境不加载 .env，所有定时任务必须通过 wrapper 执行；.env 值不能加引号

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"
  • crontab env隔离: crontab 不加载 .env，必须用 wrapper 脚本 source .env + set -a/set +a
  • .env 引号陷阱: .env 值禁止加引号，xargs 导出会保留引号导致 SQL 语法错误
  • PrismaMariaDb 协议: adapter 只接受 mariadb://，.env 中的 mysql:// 需在脚本中 .replace('mysql://', 'mariadb://')
  • .mjs 不支持 TS: .mjs 文件不能有 TypeScript 类型注解（const x: Type =），需用纯 JS 语法

6. 安全原则

  • 敏感信息（密钥、密码、Token）必须使用环境变量，禁止硬编码
  • .env 文件已被加入 .gitignore，仅 .env.example 模板可提交
  • HTTP 响应必须包含安全头：CSP、HSTS、X-Content-Type-Options、X-Frame-Options
  • 文件上传/下载必须限制大小（最大 5MB）和类型，SVG 内容需消毒 script/iframe/on-event 标签
  • Logo 文件名使用 SHA256 哈希（不使用 MD5）
  • VIP 用户不能访问管理后台（/admin/* 和 /api/admin/*）
  • 后台写操作 API 必须使用 requireAdmin 中间件（全部 25 个 POST 接口已验证）
  • 数据库外键回退值禁止硬编码：凡涉及 FK 字段（如 categoryId）必须先查库取有效 ID，再做回退（参考 category.findFirst() 模式），禁止用 || 1 等魔法数字
  • 批量写操作必须限制数量上限：工具/技能导入 max(100)，新闻导入 max(50)，批量发布 max(500)

7. 可靠性原则

  • 所有外部 API 调用（GitHub、DeepSeek 等）必须设置超时和重试
  • OpenAI/DeepSeek 客户端配置：timeout: 120000, maxRetries: 2
  • Octokit 配置：request.timeout: 30000，配合 withRetry 指数退避重试
  • 定时脚本启动时必须验证必需环境变量（DEEPSEEK_API_KEY、DATABASE_URL）
  • DeepSeek 模型名使用环境变量 DEEPSEEK_MODEL（默认 deepseek-v4-pro）
  • OAuth 用户创建需处理 P2002 唯一约束冲突竞态
Reference in New Issue View Git Blame Copy Permalink