# 追光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 唯一约束冲突竞态