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

330 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 追光AI 项目开发规则
## 端口规范
- 应用端口范围: **8301-8310**（预留扩展）
- 默认端口: **8301**
- 重启脚本仅扫描8301-8310范围
- **强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品**
## 服务器连接信息（重要！总是需要）
- **IP地址**: 119.45.242.239
- **登录用户**: ubuntu
- **SSH密钥**: `C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem`
- **SSH命令**: `ssh -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" ubuntu@119.45.242.239`
- **SCP示例**: `scp -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
## 服务器与基础设施
- **域名**: www.zhuig.com (HTTPS，SSL证书自动续期)
- **部署目录**: /home/ubuntu/zhuiguang-ai
- **访问地址**: https://www.zhuig.com (HTTP自动跳转HTTPS)
- **数据库**: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
- **Redis**: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
- **本地Git同步目录**: K:\git-repos
- **开发机**: E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai
- **Docker管理**: `docker ps` / `docker logs zhuiguang-ai-app` / `docker restart zhuiguang-ai-app`
### ⚠️ 多项目共存服务器（更新/部署铁律）
服务器 119.45.242.239 上**同时运行多个项目**和**多个共享服务**，任何代码更新、部署、运维操作必须严格隔离，绝不能影响其他项目。
#### 当前服务器实际部署清单（2026-06-10 巡检）
| 项目 | 路径 | 占用端口 | 进程 |
|------|------|----------|------|
| **zhuiguang-ai（我们）** | /home/ubuntu/zhuiguang-ai | 8301 (next-server) | Docker: zhuiguang-ai-app + zhuiguang-ai-cron |
| zhuiguang-ai-backup | /home/ubuntu/zhuiguang-ai-backup | — | 静态备份 |
| zhuiguang-quant | /home/ubuntu/zhuiguang-quant | 8701 / 8802 (java) | 独立 java 进程 |
| zhenfang | /home/ubuntu/zhenfang | — | — |
| snowy-fgt | /home/ubuntu/snowy-fgt | 7001 (gunicorn) | 独立 gunicorn |
| agent-system | /home/ubuntu/agent-system | — | — |
| nacos | /home/ubuntu/nacos | 8601 / 8602 (java) | 独立 java 进程 |
#### 共享服务（绝对不能动）
| 服务 | 端口 | 容器名 | 共享给 |
|------|------|--------|--------|
| Redis | 6379 | redis-cache (Docker) | 所有项目 |
| Nacos | 8848 / 9848 | nacos (Docker) | 注册中心 |
| MinIO | 9000 / 9001 | minio (Docker) | 文件存储 |
| nginx | 80 / 443 / 8720 / 8801 | 系统 nginx | 反向代理多域名 |
#### 铁律（更新/部署前必读）
1. **端口锁定 8301-8310**：本项目所有 HTTP/WS 服务只能使用 8301-8310 区间。禁止占用 80/443/8601-8802/8848/9000-9001/6379/7001 等任何其他端口。Docker 容器启动时若发现目标端口被占，**先排查是哪个项目在用**，绝不能 kill 别人的进程。
2. **进程隔离**：禁止 `pkill -f node` / `pkill -f java` / `pkill -f nginx` / `pkill -f docker` 等全局杀进程。重启本项目**只能重启 Docker 容器**（`docker restart zhuiguang-ai-app`）或 8301-8310 端口上的进程。
3. **禁止修改其他项目目录**：`/home/ubuntu/{zhuiguang-quant,zhenfang,snowy-fgt,agent-system,nacos}` 及其子目录**只读**，不要 `cd` 进去 `git pull` / `npm install` / 改文件。
4. **禁止修改共享服务配置**：
- 不动 Redis（6379）—— 别人可能正在用我们的 key 以外的数据
- 不动 Nacos（8848）—— 注册中心是全局的
- 不动 MinIO（9000）—— 文件存储多项目共用
- 不动 nginx 主配置 / sites-enabled 下的其他站点 —— 我们的反代规则放在独立文件，文件名带 `zhuiguang` 前缀
- 不 `docker restart` / `docker stop` / `docker rm` 任何邻居容器（本项目容器名以 `zhuiguang-ai` 开头）
5. **数据库隔离**：阿里云 RDS 上的数据库是本项目专用（`zhuiguang_ai`），但**严禁 `DROP DATABASE` / `TRUNCATE` 全表 / 删 migration 文件**。改 schema 必须 `prisma migrate dev` 生成新 migration 走前向变更。绝不执行任何会清空数据的脚本。
6. **Crontab 隔离**：本项目定时任务已全部迁移到容器内 supercronic 调度（`zhuiguang-ai-cron` 容器），主机 crontab 已清空。**禁止在主机 crontab 中添加本项目定时任务**，所有定时任务通过更新 `crontab.txt` 并重建 cron 容器完成。也禁止 `crontab -r` 清空（可能影响邻居项目）。
7. **磁盘隔离**：`/home/ubuntu/zhuiguang-ai/logs/` 是本项目日志目录；`/home/ubuntu/logs/` 是其他项目的，**不要混淆**。本项目备份只放 `/home/ubuntu/zhuiguang-ai-backup/`。
8. **环境变量隔离**：只读 `/home/ubuntu/zhuiguang-ai/.env`。**不要改 `~/.bashrc` / `/etc/environment` / `/etc/profile`** 等全局环境文件，全局变量可能影响其他项目。
9. **部署前自检清单**（强制）：
- [ ] `docker ps --filter name=zhuiguang-ai` —— 确认当前运行的容器
- [ ] `ss -tlnp | grep :8301` —— 确认 8301 是容器进程
- [ ] `git status` —— 确认本地代码只动本项目文件
- [ ] `npx tsc --noEmit` —— 零错误
- [ ] **不动** `/home/ubuntu/` 下其他项目目录
- **不动** Redis/Nacos/MinIO 容器
- **不动** nginx/sites-enabled 下非 zhuiguang 开头的文件
- **不动** 全局 crontab（本项目已用 supercronic 容器）
10. **部署后自检清单**（强制）：
- [ ] `docker ps` —— zhuiguang-ai-app 和 zhuiguang-ai-cron 状态 healthy
- [ ] `curl -I https://www.zhuig.com` —— 200，且响应时间 < 3s
- [ ] `ss -tlnp | grep :8301` —— 进程为 Docker 容器内 next-server
- [ ] `docker logs --tail 20 zhuiguang-ai-app` —— 无 ERROR
- [ ] 其他项目（zhuiguang-quant/zhenfang/snowy-fgt/nacos 等）的进程仍在、状态正常
#### 反例（禁止操作）
```bash
# ❌ 禁止 —— 全局杀进程
pkill -f node
pkill -f java
kill -9 $(pgrep node)
systemctl restart nginx
# ❌ 禁止 —— 改其他项目
cd /home/ubuntu/zhuiguang-quant && git pull
rm -rf /home/ubuntu/zhenfang
docker restart redis-cache
docker stop nacos
vi /etc/nginx/nginx.conf
crontab -r
# ❌ 禁止 —— 改共享服务
redis-cli FLUSHALL
mysql -e "DROP DATABASE ..."
```
#### 正例（本项目更新/部署的标准做法）
```bash
# ✅ 只动本项目
cd /home/ubuntu/zhuiguang-ai
git pull
docker build -t zhuiguang-ai:latest .
docker stop zhuiguang-ai-app zhuiguang-ai-cron
docker rm zhuiguang-ai-app zhuiguang-ai-cron
# 然后重新 docker run（参考 docker-compose.yml 或 CONTAINERIZATION.md）
# ✅ 查看状态时不漏看其他项目
docker ps --filter name=zhuiguang-ai # 看本项目容器状态
ss -tlnp | grep -E ':(8301|8601|8701|8802)' # 看我们的端口 + 邻居项目的端口
# ✅ 日志查看
docker logs --tail 50 zhuiguang-ai-app # APP 容器日志
docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
```
## 技术栈
- 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` 确认零错误
- 本地开发服务器: `npm run dev` (端口8301)
- 生产构建: `docker build -t zhuiguang-ai:latest .`
- 部署: `docker stop/rm` 旧容器 → `docker run` 新容器
## 数据库
- 云数据库: 阿里云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]`, `/community/bots`, `/community/bots/leaderboard`
- 后台: `/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`, `/admin/roles`, `/admin/bot-experiments`, `/admin/bot-adversarial-learning`, `/admin/bot-analytics`
## 五大操作指令
用户使用以下五个命令时，必须跳转到对应页面理解流程并按流程执行。
所有页面均为"提示词+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日报整理）
- OPENAI_API_KEY: OpenAI API Key（Bot活动引擎使用，生成论坛内容）
## 数字人Bot系统
- **角色定义文件**: `data/bot-characters.json` — 112个Bot角色定义，所有Bot脚本和前端工具依赖此文件
- **Bot头像目录**: `public/bot-avatars/` — 程序化SVG头像（112个，~2.5KB/个）
- **Bot用户标记**: User表中 `isBot: true` 标识Bot用户，与真人的互动数据分别统计
- **Bot活动时段**: 9:00-23:00每小时运行，15轮/天，论坛内容不干扰深夜用户体验
- **Bot数据库**: 12张Bot专用表（BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity）
## 定时任务调度系统
- **后台管理**: `/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` — 手动触发任务执行
### 定时任务（Supercronic 容器调度）
所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`。不再使用主机 crontab + cron-wrapper.sh。
| 时间 | 任务 | 脚本 | 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 | 检查网站/Logo可访问性+自动发布合格待审核工具 |
| 04:00 | Bot技能结晶 | `scripts/bot-skill-crystallize.mjs` | bot-skill-crystallize | 扫过去14天高互动Bot话题→DeepSeek解构共性→入库BotSkill（usageCount驱动调用）；末尾回收7天前成熟技能更新successRate（<30%且使用≥3次自动isActive=false） |
| 05:00 | Bot亲和度与画像 | `scripts/bot-affinity-update.mjs` | bot-affinity-update | 刷BotCrossForumAffinity（affinity=min(1, samples/total/4)）和BotPersona（avgReplyLength/questionRatio/stanceKeywords/topHumanUsers/topTopicTypes/lastTopicTitles，bot-activity发帖时注入prompt） |
| 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整理格式→发布日报 |
| 21:30 | Bot反馈闭环 | `scripts/bot-feedback-loop.mjs` | bot-feedback-loop | 扫描Bot自己帖子下的新回复→存反馈记忆→按概率触发二次回复（仅expert bots，配额high=6/medium=3/low=1） |
| 周日02:00 | Bot周度复盘 | `scripts/bot-weekly-review.mjs` | bot-weekly-review | 算engagementScore→生成REFLECTION记忆→决定下周配额tier（写入BotWeeklyReview.nextWeekQuota，bot-activity下次跑时动态覆盖） |
| 08:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community | 将当日日报新闻分发到社区4个板块（AI工具推荐/AI资讯/技术探讨/观点讨论） |
- 调度配置: `crontab.txt`（supercronic 格式），修改后需重建 cron 容器生效
- 日志目录: 容器内 `/app/logs/`（挂载到 Docker volume `zhuiguang_ai_bot_logs`）
- 定时任务脚本从 `scripts/` 目录直接执行，环境变量由容器 entrypoint 注入
## 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 隔离**: 本项目已迁移到容器内 supercronic 调度，不再依赖主机 crontab
- **Supercronic 环境变量**: entrypoint-cron.sh 中 `set -a; . /app/.env; set +a` 注入环境变量到 supercronic 子进程
- **Prisma 7 datasource.url**: 必须放在 `prisma.config.ts` 中，不能在 `schema.prisma` 的 datasource 块里写 `url`
- **Docker build 期 Next.js 模块求值**: server page 和 API route 在 build 时会被求值，如果依赖 env 变量（如 DATABASE_URL、API_KEY），需加 `export const dynamic = "force-dynamic"` 或懒加载
- **Docker 多阶段构建**: deps → builder → runner，利用 layer cache 加速重复构建
### 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)
### 8. Knowledge Graph Memory 同步规则
- **每次代码变更后，必须同步更新 Knowledge Graph Memory**：当修改了项目代码（新增/删除/重构功能、修改数据模型、新增API、调整定时任务、修改Bot角色等），必须将变更内容同步写入 Knowledge Graph Memory
- **同步范围**：
- 新增/修改/删除数据模型 → 更新 `数据模型-核心` 或 `数据模型-Bot系统` 实体
- 新增/修改/删除 API 端点 → 更新对应 `API-*` 实体
- 新增/修改/删除定时任务 → 更新对应 `ScheduledTask` 实体
- 修改 Bot 角色配置（bot-characters.json） → 更新对应 `BotCharacter` 实体
- 新增/修改/删除论坛板块 → 更新对应 `ForumCategory` 实体
- 修改项目架构/技术栈/部署配置 → 更新 `追光AI` 或对应 `Module` 实体
- 新增/修改实体间关系 → 更新 Knowledge Graph 关系
- **同步时机**：在代码修改完成并通过检查后、提交代码前执行同步
- **同步方法**：使用 `mcp_Knowledge_Graph_Memory_create_entities`（新增实体）、`mcp_Knowledge_Graph_Memory_add_observations`（追加观察）、`mcp_Knowledge_Graph_Memory_update_entities`（更新实体）、`mcp_Knowledge_Graph_Memory_create_relations`（新增关系）、`mcp_Knowledge_Graph_Memory_delete_entities`/`delete_relations`/`delete_observations`（删除）
- **查询优先**：在开始任何开发任务前，先通过 `mcp_Knowledge_Graph_Memory_search_nodes` 或 `mcp_Knowledge_Graph_Memory_open_nodes` 查询图谱，利用已有知识加速开发
### 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