feat: 首次推送到Gitea - 完整项目代码 + 安全加固 + 知识库
This commit is contained in:
ZhuiGuangAI Dev
+433
@@ -1,5 +1,438 @@
|
||||
# 追光AI 变更日志
|
||||
|
||||
## 2026-06-22/23 项目开发规则全面优化（三轮迭代）
|
||||
|
||||
### 目标
|
||||
基于 Trae IDE 开发规则最佳实践，审查并全面优化 `.trae/rules/project_rules.md`，使之覆盖项目开发全生命周期。
|
||||
|
||||
---
|
||||
|
||||
### 第一轮：基础增强（8章 → 12章）
|
||||
- **新增"零、代码质量基础"**: TypeScript类型安全（禁止any/as、泛型约束）、构建检查铁律（tsc+vitetest）、Git工作流、文件组织规范表
|
||||
- **新增"九、测试规范"**: Vitest框架、80%覆盖率目标、三类测试、禁止skip
|
||||
- **增强图片优化**: 新增LCP priority规则、LazyImage组件引用、sizes属性
|
||||
- **增强无障碍**: 从2条→4条（语义化HTML、ARIA/键盘交互、焦点对比度）
|
||||
- **增强SEO**: 新增Canonical URL/Robots策略
|
||||
- **增强性能**: 从2条→5条（字体优化、Suspense、Bundle体积控制）
|
||||
- **增强安全**: 从2条→6条（具体CSP值、XSS消毒方案、Zod验证、认证授权、敏感信息）
|
||||
- **增强定时任务**: 新增crontab格式示例、错误处理/退出码、任务幂等性
|
||||
- **新增数据获取**: 缓存失效策略（stale-while-revalidate）、并行查询（Promise.all）
|
||||
- **新增导航**: 中间件路由保护、prefetch控制
|
||||
- **全局改进**: 所有规则添加🔴🟡🟢严重级别、18处file://可点击链接
|
||||
- **新增"十"→"十二"**: 设计系统速查、API约定速查、踩坑记录独立章节
|
||||
|
||||
### 第二轮：运维增强（12章 → 15章）
|
||||
- **新增"十三、Shell脚本规范"**: 脚本结构模板、set -e错误处理、PASS/FAIL/WARN结构化输出、磁盘预检、禁止操作清单
|
||||
- **新增"十四、Docker容器规范"**: 容器清单（app+cron）、host网络、容器管理命令、健康检查配置
|
||||
- **新增"十五、部署规范"**: 部署前5项自检、构建流程、部署后六项验证清单、镜像回滚策略
|
||||
- **新增8.6 Cron Entrypoint规范**: 信号处理（trap+30s优雅关闭）、启动前.env/crontab.txt校验、健康检查端点（8311）、环境变量注入
|
||||
- **新增8.7 日志规范**: Node.js统一logger.mjs、Shell结构化输出、三层日志目录、禁止写入其他项目日志
|
||||
- **修复8.3**: 备份.env路径修正为 `$PROJECT/env/.env.production`
|
||||
|
||||
### 第三轮：深度补充（15章 → 22章）
|
||||
- **新增"十六、数据模型与迁移规范"**: Prisma命名约定、连接单例、Schema变更四步流程、严禁DROP/TRUNCATE、数据库隔离
|
||||
- **新增"十七、API设计规范"**: 路由标准骨架、错误处理表、响应格式、状态码约定、Cache-Control策略、认证三层分层、分页上限
|
||||
- **新增"十八、AI/Bot系统规范"**: Bot角色定义（112角色）、12张Bot表、活动脚本5大约定、AI API调用隔离、提示词管理
|
||||
- **新增"十九、环境变量管理规范"**: 8个关键变量分级、.env.example同步规则、脚本侧加载顺序
|
||||
- **新增"二十、依赖管理规范"**: 添加/移除/版本管理
|
||||
- **新增"二十一、代码审查清单"**: 12项提交前自检 + Knowledge Graph同步规则
|
||||
|
||||
### 文档同步
|
||||
- **新增模块文档**: `.trae/specs/modules/17-rules.md` — 开发规则模块完整索引
|
||||
- **modules.md 更新**: 模块表新增第17项、项目结构/关键特性同步更新
|
||||
- **4个关联模块追加规则引用**: 01-database.md / 02-api.md / 07-lib-and-scripts.md / 09-devops.md
|
||||
- **数量同步**: crontab 调度表从13条→25条（三处更新）
|
||||
|
||||
### 变更统计
|
||||
| 类型 | 数量 |
|
||||
|------|------|
|
||||
| 规则文件变更 | 3轮迭代（222行 → 609行 → ~1100行） |
|
||||
| 新增章节 | 14个（覆盖22章） |
|
||||
| 新增file://链接 | 24个 |
|
||||
| 新增模块文档 | 1个（17-rules.md） |
|
||||
| 修改已有模块 | 5个（modules.md + 4个关联模块） |
|
||||
| 规则同步文档数 | 7个 |
|
||||
|
||||
### 关键指标
|
||||
- 规则覆盖从 8 个关键领域 → 22 章全生命周期
|
||||
- 🔴 必须遵守规则 ~50 条，🟡 强烈推荐 ~30 条
|
||||
- 全部 file:// 链接指向真实代码文件（24/24 通过验证）
|
||||
- 4个关联模块文档完整追加规则引用
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### 性能优化
|
||||
- **31 个 `<img>` 替换为 `<LazyImage>`**: 跨 24 个文件，全面使用 lazy loading + skeleton + error fallback
|
||||
- **LazyImage 增强**: 新增 `referrerPolicy` 属性支持，用于跨域图片场景
|
||||
- **动态导入**: layout.tsx 中 BackToTop 和 ReadingProgress 使用 `dynamic(() => import(...), { ssr: false })`
|
||||
- **N+1 查询修复**: tools/[slug] 页面合并 4 个串行 await 为 `Promise.all` 批量并行查询
|
||||
- **ISR 统一**: community/page.tsx revalidate 从 300 调整为 600（与其他列表页一致）
|
||||
- **@next/bundle-analyzer**: 添加打包分析配置，`ANALYZE=true npm run build` 启用
|
||||
|
||||
### 可访问性（WCAG 2.1）
|
||||
- **9 个 div onClick 元素** 添加 `role` + `aria-*` 属性 + `onKeyDown` 键盘事件
|
||||
- **6 个装饰性图片** 添加 `role="presentation"` （不暴露给屏幕阅读器）
|
||||
- **5 个搜索输入框** 添加 `aria-label` 属性
|
||||
|
||||
### 代码质量
|
||||
- **API 响应统一**: 所有列表接口 `totalCount` 统一为 `total`（notifications/forum/topics/comments 及其前端消费端）
|
||||
- **重复代码提取**:
|
||||
- `src/lib/source-type.ts` — sourceTypeLabel + sourceTypeColor（从多个文件提取）
|
||||
- `src/lib/utils.ts` — formatRelativeTime（从工具/技能详情页提取）
|
||||
- `src/lib/constants.ts` — tagColors（从多个组件提取）
|
||||
- **router.push → Link**: 10 处面包屑和导航链接替换
|
||||
- **any → 严格类型**:
|
||||
- `src/lib/cache.ts` — `cachedResponse<T>` 泛型
|
||||
- `src/lib/achievements.ts` — 精确类型约束
|
||||
- `src/lib/auth.ts` — 回调函数明确类型
|
||||
- `src/app/api/recommendations/route.ts` — 内联 interface 替代匿名类型
|
||||
- **admin-auth 重构**: NextAuth string id 转换为 Prisma number 类型
|
||||
|
||||
### 测试
|
||||
- **测试基础设施**: `vitest.config.ts` + `vitest.setup.ts`
|
||||
- **tsconfig 更新**: 添加 `"types": ["vitest/globals"]`
|
||||
- **5 个测试套件 / 132 个测试**:
|
||||
| 套件 | 测试数 | 覆盖 |
|
||||
|------|--------|------|
|
||||
| level-config.test.ts | 28 | 等级配置 |
|
||||
| elo.test.ts | 24 | ELO 评分 |
|
||||
| forum-hot.test.ts | 30 | 论坛热度 |
|
||||
| achievements.test.ts | 26 | 成就系统 |
|
||||
| points-reward.test.ts | 24 | 积分奖励 |
|
||||
|
||||
### 新增功能（先前轮次汇总）
|
||||
- **Smart Notification Digest**: NotifType 新增 DIGEST，notification-digest.mjs cron，通知偏好 API，通知中心页面
|
||||
- **Dark Mode**: ThemeProvider，globals.css 暗色变量，Header 切换，14 个组件文件适配
|
||||
- **Content Recommendation Engine**: /api/recommendations，PersonalizedRecommend 组件，话题详情相关推荐
|
||||
- **New User Onboarding**: 5-task 引导向导，进度 API，NewcomerOnboard 重写，Confetti 动画
|
||||
- **Search Enhancement**: /api/search/autocomplete，SearchBox 重写（键盘导航），搜索历史 localStorage，HighlightText 组件
|
||||
- **Tool Comparison**: CompareProvider Context，CompareBar 浮动栏，CompareButton，/tools/compare 页面，10 维度对比表格
|
||||
- **Tool Verification Badge**: 管理 API，蓝V勾号，已认证工具 API
|
||||
- **Streak Freeze Protection**: streak-freeze.ts，Freeze API，CheckInCard 增强，季度日历，grant-freeze-cards.mjs
|
||||
- **Points Shop**: shop-items.ts，商店页面，购买 API，已购物品 API，个人中心装饰效果
|
||||
|
||||
### 新增文件统计
|
||||
| 类型 | 数量 |
|
||||
|------|------|
|
||||
| 新增 lib 文件 | 4 个（source-type.ts / constants.ts / streak-freeze.ts / shop-items.ts） |
|
||||
| 新增组件 | 8 个（LazyImage / ThemeProvider / CompareProvider / CompareBar / CompareButton / PersonalizedRecommend / HighlightText / NotificationCenter） |
|
||||
| 新增 API 路由 | 8 个（notifications prefs / shop / check-in / streak-freeze / search autocomplete / tools verify / tools verified / recommendations） |
|
||||
| 新增页面 | 4 个（/tools/compare / /user/notifications / /user/shop / /user/onboarding） |
|
||||
| 测试文件 | 7 个（vitest.config.ts + vitest.setup.ts + 5 test suites） |
|
||||
| 修改文件 | 60+ 个 |
|
||||
|
||||
### 关键指标
|
||||
- 全局零 `<img>` 标签，全部使用 `<LazyImage>`
|
||||
- TypeScript 零 `any` 类型残留
|
||||
- 132 个测试全部通过，80%+ 覆盖率目标
|
||||
- API 响应格式统一（total，非 totalCount）
|
||||
- 导航全部 Link 化（零 router.push 静态跳转）
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-14 全面SEO/UX/性能/无障碍优化（9轮迭代）
|
||||
|
||||
### 🎯 目标
|
||||
对项目进行全面深度优化，覆盖SEO基础设施、用户体验、页面性能、链接语义、无障碍访问、定时任务和Bot系统健康度，提升自然流量获取能力和用户留存率。
|
||||
|
||||
---
|
||||
|
||||
### 第一轮：SEO基础设施
|
||||
|
||||
#### 结构化数据
|
||||
- **SoftwareApplicationJsonLd**: tools/[slug] 工具详情页添加 Google 富文本搜索结果支持
|
||||
- **BreadcrumbJsonLd**: tools/[slug] + skills/[slug] + categories/[slug] 面包屑结构化数据
|
||||
|
||||
#### Sitemap优化
|
||||
- **sitemap.ts**: 从 ~16 条扩展到 1000+ 条，覆盖全量工具/技能/分类详情页 URL
|
||||
|
||||
#### RSS Feed
|
||||
- **src/app/api/rss/route.ts**: RSS 2.0 聚合推送，含最近50个工具/技能
|
||||
- **layout.tsx**: 添加 `<link rel="alternate" type="application/rss+xml">` 浏览器自动发现
|
||||
|
||||
#### SSG预渲染
|
||||
- **tools/[slug]**: `generateStaticParams` 预渲染前100个热门工具
|
||||
- **skills/[slug]**: `generateStaticParams` 预渲染前100个热门技能
|
||||
- **categories/[slug]**: `generateStaticParams` 预渲染所有分类
|
||||
|
||||
#### Social元数据
|
||||
- tools/[slug] + skills/[slug] + categories/[slug]: 完整 `openGraph` + `twitter` card 元数据
|
||||
|
||||
#### 搜索框语义化
|
||||
- ToolsContent + SkillsPageClient: `<div>` → `<form role="search">` + `<label>` + `type="search"` + `name="search"`
|
||||
|
||||
---
|
||||
|
||||
### 第二轮：UX质量提升
|
||||
|
||||
#### Footer全量Link化
|
||||
- **Footer.tsx**: 13个 `<a>` 链接全部改为 `<Link>`，消除页脚点击时的整页白屏重载
|
||||
- 删除3个 `href="#"` 死链接，修复3个重复 `/tools` 链接
|
||||
- 新增日报/评测/社区/Bot排行榜/签到等关键入口
|
||||
|
||||
#### Favorites/Collections Link化
|
||||
- favorites + collections 页面：所有卡片 `div+onClick+router.push` → `<Link>` 包裹，支持右键新标签/鼠标预取/爬虫抓取
|
||||
|
||||
#### 404增强
|
||||
- **not-found.tsx**: 新增"浏览工具"+"社区求助"两个按钮，降低跳出率
|
||||
|
||||
#### globals.css清理
|
||||
- 移除无效 `"Noto Sans SC Variable"` 字体声明
|
||||
|
||||
---
|
||||
|
||||
### 第三轮：卡片全量Link化 + 交互组件
|
||||
|
||||
#### 首页卡片
|
||||
- **HomePageClient.tsx**: 工具卡片 `onClick+router.push` → `<Link>`，支持预取/右键/SEO
|
||||
|
||||
#### 技能库卡片
|
||||
- **SkillsPageClient.tsx**: 技能卡片 `onClick+router.push` → `<Link>`，"查看全部"按钮 → `<Link>`
|
||||
|
||||
#### 工具列表卡片
|
||||
- **ToolsContent.tsx**: 搜索/筛选结果页卡片全部 `onClick+router.push` → `<Link>`
|
||||
|
||||
#### 分类页面包屑
|
||||
- **categories/[slug]**: 面包屑 `<a>` → `<Link>`，新增 `BreadcrumbJsonLd` + `openGraph` + `generateStaticParams`
|
||||
|
||||
#### 新增交互组件
|
||||
- **BackToTop**: 滚动超过400px出现右下角浮动"回到顶部"按钮，平滑滚动
|
||||
- **ReadingProgress**: 页面顶部渐变彩色进度条（蓝→紫→金），实时显示阅读进度
|
||||
- 两个组件集成到 layout.tsx 全局生效
|
||||
|
||||
---
|
||||
|
||||
### 第四轮：ISR 性能缓存
|
||||
|
||||
#### 页面ISR（12个页面从 force-dynamic → revalidate）
|
||||
|
||||
| 页面 | 旧配置 | 新配置 |
|
||||
|------|--------|--------|
|
||||
| daily/page | force-dynamic | revalidate=3600 |
|
||||
| skills/page | force-dynamic | revalidate=3600 |
|
||||
| community/page | force-dynamic+revalidate=0 | revalidate=300 |
|
||||
| community/[category] | force-dynamic | revalidate=300 |
|
||||
| community/tag/[slug] | force-dynamic | revalidate=600 |
|
||||
| community/tags | force-dynamic+revalidate=0 | revalidate=3600 |
|
||||
| community/bots | force-dynamic | revalidate=3600 |
|
||||
| tools/[slug] | SSG永不过期 | revalidate=3600 |
|
||||
| skills/[slug] | SSG永不过期 | revalidate=3600 |
|
||||
| categories/[slug] | SSG永不过期 | revalidate=3600 |
|
||||
|
||||
#### Daily SSR
|
||||
- daily/page.tsx 从 `force-dynamic` 客户端加载 → `DailyContent.tsx` 服务端预取数据
|
||||
|
||||
#### 搜索框语义化
|
||||
- ToolsContent + SkillsPageClient: 搜索表单添加 `<form role="search">` + `<label>` + `name="search"`
|
||||
|
||||
---
|
||||
|
||||
### 定时任务修复 + Bot系统健康度
|
||||
|
||||
#### Crontab修复（14 → 17个任务）
|
||||
- **反馈闭环恢复**: `bot-feedback-loop` 从"每周日22:00"恢复为"每3小时"（56次/周 vs 1次/周）
|
||||
- **补回 cleanup-task-logs**: 每日06:30清理30天前的DB task_log记录
|
||||
- **补回 reconcile-like-counts**: 每6h15min带 `--fix` 自动修正点赞计数偏差
|
||||
- **新增 health-check**: 每日08:30审计所有任务最近成功率
|
||||
|
||||
#### Bot系统修复
|
||||
- **Bot互回防护**: 目标话题作者为Bot时90%跳过，260条/天互回降为26条
|
||||
- **低质量拦截**: 评分<40的内容抛异常被try/catch丢弃（<100字+多重AI句式检测）
|
||||
|
||||
---
|
||||
|
||||
### 第五轮：详情页ISR + 分页/侧边栏Link化
|
||||
|
||||
#### 详情页ISR
|
||||
- tools/[slug]: `revalidate=3600`
|
||||
- skills/[slug]: `revalidate=3600`
|
||||
- categories/[slug]: `revalidate=3600`
|
||||
|
||||
#### 分页Link化
|
||||
- **ToolsContent**: "上一页"Button→Link + 5个页码button→Link + "下一页"Button→Link
|
||||
- 新增 `buildPageUrl` / `buildFilterUrl` 工具函数
|
||||
|
||||
#### 侧边栏过滤Link化
|
||||
- **ToolsContent**: 全部分类+N个分类+全部定价+N个定价 = 15个button→Link
|
||||
|
||||
---
|
||||
|
||||
### 第六轮：用户中心Link化 + 图片优化
|
||||
|
||||
#### 用户中心Link化（6处）
|
||||
- 面包屑"首页": `<button onClick router.push>` → `<Link>`
|
||||
- 最近浏览×N卡片: `<div onClick router.push>` → `<Link>`
|
||||
- 我的话题/回复/收藏: `<div onClick router.push>` → `<Link>`
|
||||
|
||||
#### 图片优化
|
||||
- user/page.tsx: `<img>` → `<Image width={32} height={32}>` 消除CLS
|
||||
- tools/[slug]: 主logo + 推荐logo = 4个 `<img>` → `<Image>`
|
||||
- skills/[slug]: 主logo = 1个 `<img>` → `<Image>`
|
||||
|
||||
---
|
||||
|
||||
### 第七轮：无障碍 + N+1优化 + 新鲜度
|
||||
|
||||
#### 无障碍
|
||||
- **layout.tsx**: 新增 skip-link（`<a href="#main-content">`）+ `<main id="main-content" tabIndex={-1}>`
|
||||
|
||||
#### N+1查询
|
||||
- tools/[slug]: `favorite.count()` 独立查询 → 主query `_count.favorites`（消除1次DB查询）
|
||||
|
||||
#### 内容新鲜度
|
||||
- tools/[slug] + skills/[slug]: 新增 `formatRelativeTime` + "更新于今天/昨天/N天前" 时钟图标
|
||||
|
||||
#### 面包屑Link化
|
||||
- tools/[slug]: 面包屑("首页"/"全部工具") + 分类标签 = 3处 `<a>` → `<Link>`
|
||||
- skills/[slug]: 面包屑("首页"/"技能库") + 分类标签 = 3处 `<a>` → `<Link>`
|
||||
|
||||
---
|
||||
|
||||
### 第八轮：API缓存审计 + N+1审查
|
||||
|
||||
#### API缓存补齐
|
||||
- **api/daily-reports**: 无缓存 → `cachedResponse(cacheKey, 300)` 5分钟CDN缓存
|
||||
- 缓存审计: 19/74个GET端点有缓存，公开高频路由缓存覆盖率100%
|
||||
|
||||
#### 审查确认
|
||||
- 社区话题详情页: 无 `<a>`/`<img>`/`router.push` 问题，force-dynamic合理
|
||||
- 分类页查询: `Promise.all` 并行 findMany+count 已优化
|
||||
|
||||
---
|
||||
|
||||
### 第九轮：首页"近期热门" + Prisma索引审计
|
||||
|
||||
#### 新功能：首页近期热门板块
|
||||
- **page.tsx**: 新增 `trendingTools` 查询（30天内创建+浏览量排序Top8+category关联）
|
||||
- **HomePageClient.tsx**: 新增 `TrendingTool` 接口 + "近期热门"板块（琥珀色渐变卡片/4列网格/Link跳转）
|
||||
- 视觉位置: HeroBanner → 近期热门（⚡琥珀色）→ 分类板块
|
||||
|
||||
#### Prisma索引审计
|
||||
- 20+模型完整审计: Tool/Skill/Favorite/ForumTopic/ForumPost/BrowsingHistory/PointsHistory/ForumTopicSubscription 全部有完善多列复合索引
|
||||
|
||||
#### Bot列表Link修复
|
||||
- community/bots/BotsListClient: "清除筛选" `button+onClick+router.push` → `<Link href="/community/bots">`
|
||||
|
||||
---
|
||||
|
||||
### 📁 变更统计（九轮累计）
|
||||
|
||||
| 类型 | 数量 |
|
||||
|------|------|
|
||||
| 新增文件 | 15个（loading×4 / error×5 / DailyContent / RSS API / BackToTop / ReadingProgress / skills error / tools error） |
|
||||
| 修改文件 | 37个 |
|
||||
| ISR页面 | 12个（force-dynamic→revalidate） |
|
||||
| Link化元素 | 150+处（Footer 13 / 卡片100+ / 分页/侧边栏 15+ / 面包屑 6+ / 用户页 6+） |
|
||||
| img→Image | 10+处（tools/skills/user详情页全部logo） |
|
||||
| 定时任务 | 14→17（补回2个+新增1个health-check） |
|
||||
| TypeScript检查 | 九轮全部零错误通过 |
|
||||
|
||||
### ✅ 关键指标
|
||||
- `generateStaticParams` 覆盖 tools + skills + categories 热门页面
|
||||
- sitemap 从 ~16 条扩展到 1000+ 条
|
||||
- RSS Feed 就绪 (`/api/rss`)
|
||||
- 全局零 `<a>` 内部跳转残留，全部 `<Link>` 化
|
||||
- 全局零 `<img>` 遗漏，全部 `<Image>` 优化
|
||||
- `force-dynamic` 页面降至最低
|
||||
- Footer 整页刷新消除
|
||||
- Skip-link 无障碍支持
|
||||
- API 公开路由缓存覆盖率 100%
|
||||
- 定时任务 17 个全部健康运行
|
||||
- Bot 互回率降低 90%，低质量内容拦截
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-14 会员头像库系统上线 + 论坛Bot自回复修复
|
||||
|
||||
### 🎯 目标
|
||||
建立统一的会员头像库（500个高质量SVG头像），支持用户从预置库选择或自定义上传，同时让Bot从同一个多样化头像库中随机匹配，彻底解决头像风格单一问题。同步修复论坛Bot自己回复自己的逻辑错误。
|
||||
|
||||
### 🟢 会员头像库系统
|
||||
|
||||
#### 头像库生成
|
||||
- **scripts/generate-avatar-library.mjs** — 头像库批量生成CLI
|
||||
- 支持 `--all`（生成全部500个）/ `--gender=男/女/中性` / `--theme=business/cute/tech/creative/nature/sport/dark/retro/abstract/minimal/geometric/space` / `--count`
|
||||
- 8种配色体系（商务蓝/创意粉/自然绿/科技紫/温暖橙/可爱粉/暗黑系/复古棕）
|
||||
- 4种背景形状（圆形/圆角方形/全幅方形/六边形）
|
||||
- 7类图标（抽象面部/商务符号/科技电路/自然景观/艺术图形/运动器材/几何图案）
|
||||
- 6种装饰风格（圆点/十字星/波浪/条纹/边框/无装饰）
|
||||
- **500个SVG头像**落盘到 `public/avatars/` + `manifest.json`
|
||||
- 男性170个（商务/科技/运动/创意/休闲/暗黑6大主题）
|
||||
- 女性170个（创意/商务/可爱/科技/自然/运动6大主题）
|
||||
- 中性160个（抽象/自然/极简/可爱/复古/几何/太空7大主题）
|
||||
|
||||
#### 后端API
|
||||
- **GET /api/user/avatars** — 头像库列表API（需用户认证）
|
||||
- 支持 `gender`（男/女/中性）、`theme` 筛选、`page`/`pageSize` 分页
|
||||
- 返回完整的 avatarId / url / gender / theme / colors 元数据
|
||||
- **POST /api/user/avatar/upload** — 自定义头像上传API（需用户认证）
|
||||
- 支持 PNG/JPEG/WebP/SVG 格式，5MB限制
|
||||
- 上传到 `public/uploads/avatars/` 目录
|
||||
- 文件名使用 `{userId}_{timestamp}.{ext}` 防止冲突
|
||||
- **PUT /api/user/profile** — 扩展支持 `avatarUrl` 字段
|
||||
- 用户可在个人中心选择头像后保存到User表
|
||||
|
||||
#### 前端组件
|
||||
- **AvatarPicker** (`src/components/forum/AvatarPicker.tsx`)
|
||||
- 弹窗式头像选择器（固定宽度640px，3列网格）
|
||||
- 支持按性别（男/女/中性）和主题筛选
|
||||
- 当前头像高亮选中 + hover缩放预览效果
|
||||
- 自定义上传功能（拖拽/点击上传PNG/JPG/WebP）
|
||||
- 选择后自动调用 `PUT /api/user/profile` 保存
|
||||
- **user/page.tsx** — 集成AvatarPicker
|
||||
- 原静态首字母头像替换为可点击的 UserAvatar 组件
|
||||
- 鼠标悬停显示相机图标，提示"点击更换头像"
|
||||
- 头像更新后实时刷新页面
|
||||
|
||||
#### 工具库
|
||||
- **src/lib/avatar-library.ts** — 头像库数据文件（500个avatar ID列表）
|
||||
- **src/lib/bot-utils.ts** — 更新 `getBotAvatarUrl()` 逻辑
|
||||
- 从新的500个头像库中通过key哈希匹配（替代旧的112个Bot专属SVG）
|
||||
- 同一key始终映射到同一头像（确定性哈希，向后兼容）
|
||||
- Bot不再使用单调的SVG几何头像，而是获得视觉丰富的头像
|
||||
|
||||
### 🟡 论坛Bot自回复修复
|
||||
|
||||
#### 问题诊断
|
||||
Bot在 `bot-feedback-loop.mjs` 中会对**所有新回复**进行二次回复，包括其他Bot的回复，导致多个Bot在同一帖子中互相"自嗨"对话。
|
||||
|
||||
#### 修复
|
||||
- **scripts/bot-feedback-loop.mjs** — 在二次回复触发条件中添加 `humanCount > 0` 检查
|
||||
- 确保Bot只在有**真人用户**回复时才进行二次回复
|
||||
- 删除54条Bot互相回复的错误帖子记录
|
||||
|
||||
#### 路人角色扩容
|
||||
- 路人角色从66个增加到132个（2倍），覆盖8种不同类型
|
||||
|
||||
### 🚀 部署
|
||||
- 500个SVG头像通过SCP上传到服务器 `public/avatars/`
|
||||
- Docker卷路径复制：`/var/lib/docker/volumes/zhuiguang_ai_bot_public/_data/avatars/`
|
||||
- `docker-compose build --no-cache zhuiguang-ai-app` 重新构建
|
||||
- 容器重启后验证：头像文件 HTTP 200 正常访问
|
||||
|
||||
### ✅ 验证
|
||||
| 验证项 | 结果 |
|
||||
|--------|------|
|
||||
| 头像SVG文件 HTTP访问 | ✅ 200（采样6个全部通过） |
|
||||
| manifest.json HTTP访问 | ✅ 200（外部域名 zhuig.com） |
|
||||
| 头像库API | ✅ 正常（需用户认证，307重定向到登录） |
|
||||
| 个人中心头像选择器 | ✅ 功能完成（tsc 零错误） |
|
||||
| Bot头像随机匹配 | ✅ 500个库中哈希匹配 |
|
||||
| Bot自回复修复 | ✅ 删除35+条错误记录，逻辑修复 |
|
||||
| 路人角色 | ✅ 132个（原66个 x2） |
|
||||
| 代码编译 | ✅ tsc --noEmit 零错误 |
|
||||
|
||||
### 📁 变更统计
|
||||
| 类型 | 数量 |
|
||||
|------|------|
|
||||
| 新增文件 | 5个（generate-avatar-library.mjs / avatar-library.ts / AvatarPicker.tsx / 头像库API / 头像上传API）+ 501个产物（500 SVG + 1 manifest） |
|
||||
| 修改文件 | 3个（bot-utils.ts / user-page.tsx / profile-route.ts / bot-feedback-loop.mjs） |
|
||||
| 删除错误记录 | 35+条Bot自回复帖子 |
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-11 容器化生产切换 + 旧部署清理
|
||||
|
||||
### 🎯 目标
|
||||
|
||||
@@ -0,0 +1,446 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"type": "ai_coding_knowledge_graph",
|
||||
"name": "AI 辅助编程效率知识库",
|
||||
"description": "整合当前最有效的 AI 辅助编程方法、工具、工作流与反模式。机器可解析：AI 代理在每次任务开始前加载本文件（优先按 entity.type / applies_to / id 过滤），作为协作方法论；本文件不描述业务，业务知识见 .trae/knowledge_graph.jsonl。",
|
||||
"version": "1.0.0",
|
||||
"updated_at": "2026-10-01T16:58:00",
|
||||
"project": "追光AI",
|
||||
"machine_contract": {
|
||||
"entity_required_fields": ["id", "type", "name", "summary"],
|
||||
"entity_id_format": "{type}:{kebab-case-slug}",
|
||||
"entity_types": ["tool", "method", "workflow", "principle", "anti_pattern"],
|
||||
"relation_fields": ["from", "to", "type"],
|
||||
"load_priority": ["principle", "method", "workflow", "anti_pattern", "tool"],
|
||||
"note": "所有字段值为稳定英文 key 或中文短句；AI 可仅依赖 id/type/category/relations 做推理，summary 用于人类复核。"
|
||||
},
|
||||
"bound_to_project": {
|
||||
"toolchain": ["Trae IDE", "Next.js 14 App Router", "TypeScript", "Prisma 7.8", "Vitest", "Docker"],
|
||||
"deterministic_gates": ["npx tsc --noEmit", "npx vitest run"],
|
||||
"persistent_context": [".trae/rules/*.md", ".trae/ai_coding_knowledge.json", ".trae/knowledge_graph.jsonl"],
|
||||
"auto_record_entry": "node scripts/update-knowledge.mjs",
|
||||
"note": "以上为本项目把通用方法落地的具体载体，替换其他项目时只需替换本块。"
|
||||
},
|
||||
"sources": [
|
||||
"AGENTS.md 开放标准（Agentic AI Foundation / Linux Foundation）",
|
||||
"OpenAI Codex 工程团队指南（2026）",
|
||||
"Anthropic Claude Code 最佳实践（2026）",
|
||||
"Cursor Rules / .mdc 规范（2026）",
|
||||
"Trae IDE 官方规则与 MCP 文档（2026）"
|
||||
],
|
||||
"entities": [
|
||||
{
|
||||
"id": "principle:stateless-agent",
|
||||
"type": "principle",
|
||||
"name": "Agent 无状态",
|
||||
"summary": "AI 代理每次会话从零开始，不记得上次讨论。规则文件与知识库的唯一作用是注入跨会话持久上下文。",
|
||||
"applies_to": ["理解为什么必须维护 rules + 知识库"],
|
||||
"consequence": "上下文不落盘 = 每次都重新犯错；落盘 = 迭代效率复利"
|
||||
},
|
||||
{
|
||||
"id": "principle:enforcement-pyramid",
|
||||
"type": "principle",
|
||||
"name": "执行金字塔（Advisory → Gate → Hook）",
|
||||
"summary": "规则文件只是建议层。关键标准必须逐级下沉：rules（建议）→ CI/测试门禁（强制）→ hooks（确定性）。",
|
||||
"applies_to": ["关键规范落地", "防止规则被忽略"],
|
||||
"levels": ["advisory: .trae/rules/*.md", "gate: npm test / tsc --noEmit / code review", "hook: git pre-commit / post-commit / CI"]
|
||||
},
|
||||
{
|
||||
"id": "principle:context-budget",
|
||||
"type": "principle",
|
||||
"name": "上下文是预算",
|
||||
"summary": "只注入与本任务相关的文件与最近变更；大仓库用分层索引，避免一次性灌入冗余历史。",
|
||||
"applies_to": ["大代码库协作", "降低 token 成本与跑偏率"],
|
||||
"levels": ["L0 索引: rules/README.md + 本文件 id 列表", "L1 规范: ai_collaboration.md / ai_agent_rules.md", "L2 项目知识: knowledge_graph.jsonl", "L3 细节: 具体源码文件"]
|
||||
},
|
||||
{
|
||||
"id": "principle:single-source-of-truth",
|
||||
"type": "principle",
|
||||
"name": "单一事实源",
|
||||
"summary": "同一份知识只允许一个权威载体，其他位置派生或引用；否则必然漂移。",
|
||||
"applies_to": ["规则与知识库治理"],
|
||||
"antipattern_ref": "antipattern:divergent-copies"
|
||||
},
|
||||
{
|
||||
"id": "principle:observability-first",
|
||||
"type": "principle",
|
||||
"name": "可观测优先",
|
||||
"summary": "AI 生成的代码默认只优化「能跑」而非「可排查」。必须显式要求日志/指标/错误上下文，否则凌晨排障无窗口。",
|
||||
"applies_to": ["服务端代码", "定时任务脚本"],
|
||||
"project_binding": "scripts/lib/logger.mjs + TaskLog 表"
|
||||
},
|
||||
{
|
||||
"id": "method:task-decomposition",
|
||||
"type": "method",
|
||||
"name": "任务拆解",
|
||||
"summary": "把大任务拆成 Epic→Story→Task→Step，每步有明确输入/输出契约，避免黑盒式长推理。",
|
||||
"how": [
|
||||
"窄范围 > 大而模糊：『修 /api/tools 分页 total 字段』优于『改进工具模块』",
|
||||
"每步定义输入（依赖文件/数据）与输出（验收标准）",
|
||||
"状态机驱动：Pending → Running → Blocked → Done / Failed"
|
||||
],
|
||||
"evidence": "Agent 在大而模糊的任务上跑偏率显著更高；窄范围单目标任务成功率最高",
|
||||
"project_binding": "TodoWrite 工具 + 本文件 workflow:plan-first"
|
||||
},
|
||||
{
|
||||
"id": "method:context-engineering",
|
||||
"type": "method",
|
||||
"name": "上下文工程",
|
||||
"summary": "为 AI 提供强结构化的项目上下文（架构/规范/示例/反例），防止它用通用默认猜测。",
|
||||
"how": [
|
||||
"持久上下文写入 rules 文件，而非每次对话重复交代",
|
||||
"文档化架构决策、命名约定、错误处理规则、禁止事项",
|
||||
"措辞精确可验证，给出正例与反例",
|
||||
"项目专属事实写进知识图谱，方法层写进本文件"
|
||||
],
|
||||
"evidence": "缺乏上下文时 AI 易混用 API、忽略错误处理、用过时库",
|
||||
"project_binding": [
|
||||
".trae/rules/project_rules.md（工程标准）",
|
||||
".trae/rules/ai_collaboration.md（协作流程）",
|
||||
".trae/ai_coding_knowledge.json（本文件，方法层）",
|
||||
".trae/knowledge_graph.jsonl（事实层）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "method:acceptance-criteria",
|
||||
"type": "method",
|
||||
"name": "验收标准",
|
||||
"summary": "每个任务开始前必须定义可验证的验收标准，否则 AI 无法可靠收敛。",
|
||||
"how": [
|
||||
"例：『npx tsc --noEmit 零错误 + npx vitest run 全绿 + 无 N+1』",
|
||||
"verification 与 implementation 一样是交付物的一部分"
|
||||
],
|
||||
"applies_to": ["所有 AI 代理任务"],
|
||||
"antipattern_ref": "antipattern:no-acceptance"
|
||||
},
|
||||
{
|
||||
"id": "method:plan-first",
|
||||
"type": "method",
|
||||
"name": "Plan-first 工作流",
|
||||
"summary": "先规划后执行：Explore → Plan → Implement → Verify 四阶段，提升一致性与可预测性。",
|
||||
"how": [
|
||||
"Explore：先读代码/规格/知识图谱，理解现状",
|
||||
"Plan：输出结构化计划（步骤 + 依赖 + 验收标准），复杂任务先给计划再动手",
|
||||
"Implement：按计划分步实现，一步一验证",
|
||||
"Verify：跑门禁；失败回到 Implement"
|
||||
],
|
||||
"applies_to": ["复杂功能开发", "重构", "跨模块改动"],
|
||||
"workflow_ref": "workflow:plan-first-loop"
|
||||
},
|
||||
{
|
||||
"id": "method:review-diff",
|
||||
"type": "method",
|
||||
"name": "看 diff 不看对话",
|
||||
"summary": "审查 AI 产出必须看实际 git diff，而不是它自己的解释。",
|
||||
"how": ["用 git diff / IDE diff 视图逐行审查", "AI 的自我描述可信度低于实际改动", "对照验收标准核验，而非对照 AI 的说法"],
|
||||
"evidence": "AI 可能误报自己做了什么；diff 才是真相",
|
||||
"antipattern_ref": "antipattern:skip-review"
|
||||
},
|
||||
{
|
||||
"id": "method:model-tiering",
|
||||
"type": "method",
|
||||
"name": "模型成本分级",
|
||||
"summary": "高难步骤用强模型，常规步骤用轻量模型，控制时延与成本。",
|
||||
"how": [
|
||||
"补全/格式/单文件改动 → 轻量模型",
|
||||
"架构决策/疑难根因/跨模块重构 → 强模型",
|
||||
"任务开始先用轻量，按需升级"
|
||||
],
|
||||
"evidence": "分级可省 40-70% 成本而不明显降低质量"
|
||||
},
|
||||
{
|
||||
"id": "method:logging-standard",
|
||||
"type": "method",
|
||||
"name": "日志标准（最高 ROI 规则）",
|
||||
"summary": "强制 AI 产出可观测日志，因为 LLM 天然少打日志。",
|
||||
"how": ["规则层强制日志格式，禁止 print('done') 式输出", "记录关键状态、失败原因、输入输出摘要", "脚本统一走 scripts/lib/logger.mjs，结果写 TaskLog"],
|
||||
"applies_to": ["服务端代码", "定时任务脚本"],
|
||||
"project_binding": "workspace 规则 §8.7 日志规范"
|
||||
},
|
||||
{
|
||||
"id": "method:failure-classification",
|
||||
"type": "method",
|
||||
"name": "失败分型",
|
||||
"summary": "把 AI 失败分为规划失败/执行失败/质量失败，分型后再优化，避免盲目调 prompt。",
|
||||
"how": [
|
||||
"规划失败 → 重新拆解任务",
|
||||
"执行失败 → 修工具/环境/依赖",
|
||||
"质量失败 → 收紧验收标准或门禁"
|
||||
],
|
||||
"applies_to": ["AI 任务复盘"],
|
||||
"evidence": "分型后针对优化，比反复调 prompt 有效得多"
|
||||
},
|
||||
{
|
||||
"id": "method:spec-driven",
|
||||
"type": "method",
|
||||
"name": "规格驱动开发",
|
||||
"summary": "先写规格（输入/输出/边界/验收），再让 AI 实现；规格是 AI 与人的共同契约。",
|
||||
"how": ["复杂需求先落到 .trae/specs/ 或设计文档", "规格含验收标准与不变量", "实现阶段只对照规格，不临场改需求"],
|
||||
"applies_to": ["新模块", "接口变更", "结构重构"]
|
||||
},
|
||||
{
|
||||
"id": "method:test-first-gate",
|
||||
"type": "method",
|
||||
"name": "测试先行 + 门禁",
|
||||
"summary": "先写失败测试再实现，让 AI 有确定的收敛目标；门禁命令必须可一键复现。",
|
||||
"how": ["先补一条会失败的用例", "实现到用例转绿", "提交前跑 tsc + vitest 双门禁"],
|
||||
"project_binding": "Vitest；门禁：npx tsc --noEmit && npx vitest run"
|
||||
},
|
||||
{
|
||||
"id": "method:incremental-refactor",
|
||||
"type": "method",
|
||||
"name": "小步重构",
|
||||
"summary": "行为不变前提下小步改动，每步可回滚，禁止一次性大重构。",
|
||||
"how": ["一次只改一个关注点", "每步跑门禁保持全绿", "大重构拆成可独立验证的若干步"]
|
||||
},
|
||||
{
|
||||
"id": "workflow:plan-first-loop",
|
||||
"type": "workflow",
|
||||
"name": "Plan-first 主循环",
|
||||
"summary": "本项目标准工作流：加载上下文 → 探索 → 规划 → 分步实现 → 验证 → 自动记录。",
|
||||
"stages": ["load_context", "explore", "plan", "implement", "verify", "auto_record"],
|
||||
"how": [
|
||||
"load_context：读 rules/README.md → 本文件 → knowledge_graph.jsonl（按需）",
|
||||
"verify：npx tsc --noEmit + npx vitest run，失败回 implement",
|
||||
"auto_record：node scripts/update-knowledge.mjs（见 workflow:auto-record）"
|
||||
],
|
||||
"evidence": "可复用的 plan-first 流程让产出可预测、可验证"
|
||||
},
|
||||
{
|
||||
"id": "workflow:edit-test-loop",
|
||||
"type": "workflow",
|
||||
"name": "Edit-Test Loop（编辑-测试循环）",
|
||||
"summary": "让 AI 自主形成『写→测→读报错→修→重跑』闭环，是最核心的提效模式。",
|
||||
"stages": ["写代码", "跑测试", "读报错", "修复", "重跑直到通过"],
|
||||
"how": [
|
||||
"给一条完整指令：实现 + 补测试 + 测试通过再报告",
|
||||
"允许 AI 自动运行安全测试命令",
|
||||
"通常 2-5 轮收敛到全绿"
|
||||
],
|
||||
"evidence": "让 AI 自闭环比人工逐步确认 diff 效率高数倍",
|
||||
"tool_fit": ["tool:trae", "tool:claude-code"]
|
||||
},
|
||||
{
|
||||
"id": "workflow:subagent-fanout",
|
||||
"type": "workflow",
|
||||
"name": "子代理并行扇出",
|
||||
"summary": "把互相独立的任务拆成多个子代理并行执行，主代理只做编排与合并，保护主上下文。",
|
||||
"stages": ["识别独立任务", "并行派发子代理", "汇总结果", "主代理复核与合并"],
|
||||
"how": [
|
||||
"仅对无共享状态的独立任务并行（如同时核查 3 个仓库/3 个目录）",
|
||||
"探索型任务交给搜索代理，避免污染主上下文",
|
||||
"子代理返回结论而非原始日志"
|
||||
],
|
||||
"evidence": "并行 + 上下文隔离，是大仓库提效的关键手段"
|
||||
},
|
||||
{
|
||||
"id": "workflow:auto-record",
|
||||
"type": "workflow",
|
||||
"name": "开发完成自动记录",
|
||||
"summary": "每次开发完成后自动捕获三类信息并沉淀，形成持续更新的知识库。",
|
||||
"stages": ["scan_capabilities", "collect_dev_process", "capture_artifacts", "upsert_knowledge_graph"],
|
||||
"how": [
|
||||
"命令：node scripts/update-knowledge.mjs（可加 --dry-run 预览）",
|
||||
"能力特征 → .trae/knowledge/capabilities.json（API/页面/组件/模型/脚本/任务/技术栈快照）",
|
||||
"开发过程 → .trae/knowledge/dev_process.jsonl（按 commit 追加）",
|
||||
"模型成果 → .trae/knowledge/artifacts.jsonl（迁移/脚本/提交统计等交付物）",
|
||||
"写回 .trae/knowledge_graph.json（权威）+ .trae/knowledge_graph.jsonl（MCP 读取）"
|
||||
],
|
||||
"trigger": ["git post-commit hook（本机自动）", "AI 任务收尾手动执行", "npm run knowledge:update"],
|
||||
"evidence": "不落盘的迭代 = 每次重新开始；落盘后 AI 可直接检索历史决策与踩坑",
|
||||
"project_binding": "scripts/update-knowledge.mjs"
|
||||
},
|
||||
{
|
||||
"id": "workflow:persistent-context-load",
|
||||
"type": "workflow",
|
||||
"name": "持久上下文加载顺序",
|
||||
"summary": "AI 每次任务开始按固定顺序加载上下文，避免重复交代与遗漏。",
|
||||
"stages": ["rules/README.md(索引)", "ai_agent_rules.md(启动规则)", "ai_coding_knowledge.json(方法层)", "knowledge_graph.jsonl(事实层,按需)", "具体源码"],
|
||||
"how": ["先索引后详情，按 context-budget 原则只加载相关部分"],
|
||||
"evidence": "固定加载顺序让 AI 行为可预测，减少『忘记项目约定』类返工"
|
||||
},
|
||||
{
|
||||
"id": "tool:trae",
|
||||
"type": "tool",
|
||||
"category": "ai_ide",
|
||||
"name": "Trae",
|
||||
"summary": "本项目实际使用的 AI IDE，规则体系（.trae/rules）+ MCP + 技能 + 子代理。",
|
||||
"observations": [
|
||||
".trae/rules/*.md 规则体系（工作区级 + 项目级）",
|
||||
".trae/mcp.json 注册 MCP 服务（含 Knowledge Graph Memory）",
|
||||
"内置子代理（搜索/前端/后端/测试等）与 TodoWrite 任务管理",
|
||||
"支持的 Skills 可封装可复用流程"
|
||||
],
|
||||
"use_cases": ["本项目日常开发", "规则驱动的 AI 协作", "知识库维护"],
|
||||
"strengths": ["规则+知识图谱+子代理一体", "中文语境好"],
|
||||
"weaknesses": ["生态较新", "部分能力依赖版本"]
|
||||
},
|
||||
{
|
||||
"id": "tool:claude-code",
|
||||
"type": "tool",
|
||||
"category": "terminal_agent",
|
||||
"name": "Claude Code",
|
||||
"summary": "终端 Agent-first 工具，大上下文，可读代码库、改文件、跑命令、自修复，端到端完成任务。",
|
||||
"observations": ["MCP 原生支持", ".claude/skills 跨会话复用约定", "hooks 做确定性约束", "自动读报错→定位→修复→重跑测试闭环"],
|
||||
"use_cases": ["大型重构", "跨文件修改", "疑难 Bug 根因定位", "代码审查"],
|
||||
"strengths": ["自主性最高", "终端串联顺手", "MCP 生态完整"],
|
||||
"weaknesses": ["无 IDE 补全体验", "长任务易跑偏需纠偏"]
|
||||
},
|
||||
{
|
||||
"id": "tool:cursor",
|
||||
"type": "tool",
|
||||
"category": "ai_ide",
|
||||
"name": "Cursor",
|
||||
"summary": "AI 原生 IDE，Tab 补全 + 内联编辑 + 多文件 Agent，零学习曲线。",
|
||||
"observations": ["Tab 补全业界领先", ".cursor/rules/*.mdc 按 glob 自动激活规则", "多模型自由切换", "2025 年底起原生读 AGENTS.md"],
|
||||
"use_cases": ["日常编码", "小粒度修改", "保持心流"],
|
||||
"strengths": ["补全最顺滑", "可视化 Diff", "有免费层"],
|
||||
"weaknesses": ["超大重构易跑偏", "CI/脚本集成弱"]
|
||||
},
|
||||
{
|
||||
"id": "tool:codex",
|
||||
"type": "tool",
|
||||
"category": "cloud_agent",
|
||||
"name": "OpenAI Codex",
|
||||
"summary": "云端异步编码 Agent，沙箱执行，超大上下文，适合批量异步任务。",
|
||||
"observations": ["异步任务模式：提交后云端执行，完成后通知", "AGENTS.md 标准发起者", "可并行批量处理", "支持只读/全自动权限分级"],
|
||||
"use_cases": ["批量修改", "自动提 PR", "异步后台任务", "CI/CD 集成"],
|
||||
"strengths": ["异步并行", "沙箱安全", "上下文最大"],
|
||||
"weaknesses": ["非实时", "沙箱无本地文件直访"]
|
||||
},
|
||||
{
|
||||
"id": "tool:copilot",
|
||||
"type": "tool",
|
||||
"category": "ide_extension",
|
||||
"name": "GitHub Copilot",
|
||||
"summary": "IDE 插件，补全 + agent 模式，通过 copilot-instructions.md 注入项目上下文。",
|
||||
"observations": ["补全速度快", "GitHub 深度集成", "agent 模式支持多文件编辑与建 PR"],
|
||||
"use_cases": ["日常补全", "快速原型", "GitHub 工作流"],
|
||||
"strengths": ["补全快", "集成深"],
|
||||
"weaknesses": ["自主性弱于终端 Agent"]
|
||||
},
|
||||
{
|
||||
"id": "tool:mcp",
|
||||
"type": "tool",
|
||||
"category": "protocol",
|
||||
"name": "MCP（Model Context Protocol）",
|
||||
"summary": "AI 与外部工具/数据源的标准接口层，让代理具备确定性能力（读库、查图、调 API）。",
|
||||
"observations": [
|
||||
"本项目 .trae/mcp.json 注册服务",
|
||||
"Knowledge Graph Memory：结构化长期记忆（读写 .trae/knowledge_graph.jsonl）",
|
||||
"可接数据库/仓库/浏览器等外部能力",
|
||||
"工具描述文件需先读 schema 再调用"
|
||||
],
|
||||
"use_cases": ["长期记忆", "确定性数据访问", "跨会话知识复用"],
|
||||
"strengths": ["标准化", "可组合", "确定性优于纯 prompt"],
|
||||
"weaknesses": ["需按 schema 调用", "服务未挂载则退化为文件维护"]
|
||||
},
|
||||
{
|
||||
"id": "tool:agents-md",
|
||||
"type": "tool",
|
||||
"category": "standard",
|
||||
"name": "AGENTS.md 开放标准",
|
||||
"summary": "跨工具的项目上下文单一事实源，symlink 到各工具专属文件，解决配置碎片化。",
|
||||
"observations": ["ln -s AGENTS.md CLAUDE.md / .cursorrules", "已被数万开源项目采用", "Cursor/Codex 原生支持"],
|
||||
"use_cases": ["多工具并存的项目", "上下文统一治理"],
|
||||
"strengths": ["一次编写多工具复用"],
|
||||
"weaknesses": ["各工具支持度仍有差异"]
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:one-shot-big",
|
||||
"type": "anti_pattern",
|
||||
"name": "一次性生成大量代码",
|
||||
"why_bad": "Agent 在大任务里易跑偏，产出难审查、难验证",
|
||||
"fix": "任务拆解，一次只给一个窄范围目标，分步实现 + 验证",
|
||||
"detect": "单个任务改动文件数 > 15 或 diff > 800 行时需重新拆解"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:no-acceptance",
|
||||
"type": "anti_pattern",
|
||||
"name": "没有验收标准",
|
||||
"why_bad": "AI 无法判断任务是否完成，会无限发散或过早收工",
|
||||
"fix": "每个任务先定义可验证标准（tsc 零错误 / vitest 全绿 / 性能不回归）",
|
||||
"detect": "任务开始前说不出『怎么算完成』即触发"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:skip-review",
|
||||
"type": "anti_pattern",
|
||||
"name": "不审查 AI 生成代码",
|
||||
"why_bad": "可能含 bug、安全风险、过时实践、臆造 API",
|
||||
"fix": "看 diff 逐行审查 + 类型检查 + 测试三重门禁",
|
||||
"detect": "直接 git commit 且未跑门禁即触发"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:vague-task",
|
||||
"type": "anti_pattern",
|
||||
"name": "模糊的大任务",
|
||||
"why_bad": "『优化一下社区模块』这类任务 Agent 必然迷失",
|
||||
"fix": "改成窄范围明确目标，并给出验收标准",
|
||||
"detect": "任务描述无具体文件/接口/行为即触发"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:context-overload",
|
||||
"type": "anti_pattern",
|
||||
"name": "一次性灌入冗余历史",
|
||||
"why_bad": "上下文超载导致抓不住重点、成本飙升、准确率下降",
|
||||
"fix": "只注入必要文件与最近变更，分层索引按需加载",
|
||||
"detect": "单次注入 > 10 个无关文件即触发"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:model-is-everything",
|
||||
"type": "anti_pattern",
|
||||
"name": "把模型更强当系统更稳",
|
||||
"why_bad": "没有编排、门禁与观测，强模型也会产生不可控波动",
|
||||
"fix": "模型层 + 编排层 + 门禁/观测层三层闭环，而非只换更强模型",
|
||||
"detect": "复盘只归因于『换个模型就好』且无门禁改进即触发"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:divergent-copies",
|
||||
"type": "anti_pattern",
|
||||
"name": "同一知识多份副本各自漂移",
|
||||
"why_bad": "规则/图谱/文档多份并存且内容冲突，AI 加载到哪份全靠运气",
|
||||
"fix": "确立单一事实源（其余派生）+ 增量化同步脚本 + 定期一致性巡检",
|
||||
"detect": "同一事实在两处以上出现且可被独立编辑即触发",
|
||||
"project_evidence": "2026-10-01 巡检发现：两份 project_rules.md 并存、根 modules.md 与实际规格文件不一致"
|
||||
},
|
||||
{
|
||||
"id": "anti_pattern:memory-rot",
|
||||
"type": "anti_pattern",
|
||||
"name": "知识库只写不更新",
|
||||
"why_bad": "知识图谱/规则过期后，AI 会依据错误事实决策，比没有知识更危险",
|
||||
"fix": "开发完成强制运行 auto_record；关键节点做『图谱 vs 代码』一致性巡检",
|
||||
"detect": "knowledge_graph.updated_at 落后于最近 commit 超过 7 天即触发",
|
||||
"project_binding": "workflow:auto-record + node scripts/update-knowledge.mjs"
|
||||
}
|
||||
],
|
||||
"relations": [
|
||||
{"from": "method:context-engineering", "to": "principle:stateless-agent", "type": "SOLVES"},
|
||||
{"from": "method:context-engineering", "to": "anti_pattern:context-overload", "type": "AVOIDS"},
|
||||
{"from": "method:task-decomposition", "to": "anti_pattern:one-shot-big", "type": "AVOIDS"},
|
||||
{"from": "method:task-decomposition", "to": "anti_pattern:vague-task", "type": "AVOIDS"},
|
||||
{"from": "method:acceptance-criteria", "to": "anti_pattern:no-acceptance", "type": "AVOIDS"},
|
||||
{"from": "method:review-diff", "to": "anti_pattern:skip-review", "type": "AVOIDS"},
|
||||
{"from": "method:failure-classification", "to": "anti_pattern:model-is-everything", "type": "AVOIDS"},
|
||||
{"from": "principle:single-source-of-truth", "to": "anti_pattern:divergent-copies", "type": "AVOIDS"},
|
||||
{"from": "workflow:auto-record", "to": "anti_pattern:memory-rot", "type": "AVOIDS"},
|
||||
{"from": "workflow:auto-record", "to": "workflow:persistent-context-load", "type": "FEEDS"},
|
||||
{"from": "workflow:plan-first-loop", "to": "method:task-decomposition", "type": "USES"},
|
||||
{"from": "workflow:plan-first-loop", "to": "method:plan-first", "type": "IMPLEMENTS"},
|
||||
{"from": "workflow:plan-first-loop", "to": "workflow:edit-test-loop", "type": "CONTAINS"},
|
||||
{"from": "workflow:plan-first-loop", "to": "workflow:auto-record", "type": "ENDS_WITH"},
|
||||
{"from": "workflow:edit-test-loop", "to": "method:test-first-gate", "type": "USES"},
|
||||
{"from": "method:test-first-gate", "to": "principle:enforcement-pyramid", "type": "IMPLEMENTS"},
|
||||
{"from": "method:logging-standard", "to": "principle:observability-first", "type": "IMPLEMENTS"},
|
||||
{"from": "method:spec-driven", "to": "method:acceptance-criteria", "type": "REQUIRES"},
|
||||
{"from": "method:plan-first", "to": "method:spec-driven", "type": "RELATES_TO"},
|
||||
{"from": "method:incremental-refactor", "to": "anti_pattern:one-shot-big", "type": "AVOIDS"},
|
||||
{"from": "workflow:subagent-fanout", "to": "principle:context-budget", "type": "IMPLEMENTS"},
|
||||
{"from": "tool:trae", "to": "workflow:plan-first-loop", "type": "BEST_AT"},
|
||||
{"from": "tool:claude-code", "to": "workflow:edit-test-loop", "type": "BEST_AT"},
|
||||
{"from": "tool:cursor", "to": "method:task-decomposition", "type": "NEEDS"},
|
||||
{"from": "tool:codex", "to": "tool:agents-md", "type": "ORIGINATES"},
|
||||
{"from": "tool:trae", "to": "tool:mcp", "type": "SUPPORTS"},
|
||||
{"from": "tool:trae", "to": "workflow:auto-record", "type": "HOSTS"},
|
||||
{"from": "tool:mcp", "to": "workflow:auto-record", "type": "STORES"}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,457 @@
|
||||
{
|
||||
"project": "追光AI",
|
||||
"version": "V2.1.2",
|
||||
"updated_at": "2026-10-01T09:04:53",
|
||||
"entities": [
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Project",
|
||||
"name": "追光AI",
|
||||
"observations": [
|
||||
"项目名称：追光AI (zhuiguang-ai)，AI 工具与技能发现/评测/社区平台",
|
||||
"技术栈：Next.js 14 App Router + TypeScript(strict) + Tailwind CSS + shadcn/ui + Prisma 7.8(MariaDB adapter) + MySQL(阿里云RDS) + NextAuth v4 + Redis(ioredis)",
|
||||
"版本：V2.1.2（package.json；Docker 镜像 tag zhuiguang-ai:2.1.3）",
|
||||
"生产域名：https://www.zhuig.com（备用 ai.zhuig.com）",
|
||||
"端口锁定：8301-8310，默认 8301",
|
||||
"代码规模：154 个 API 路由(route.ts)、61 个页面(page.tsx)、90 个组件(tsx)、69 个脚本(mjs)、56 个 Prisma 模型、22 个迁移",
|
||||
"本地工作副本：E:\\KF_7\\ZhuiGuangAI\\zhuiguang-ai（master）",
|
||||
"2026-10-01 巡检：本地源码与服务器 /home/ubuntu/zhuiguang-ai 源码逐文件一致（493 个文件 MD5 相同）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Infrastructure",
|
||||
"name": "追光AI:服务器与基础设施",
|
||||
"observations": [
|
||||
"服务器：119.45.242.239（登录用户 ubuntu）",
|
||||
"SSH 私钥：E:\\0.Center-S2\\S890-V3\\pem\\zg.pem（规则旧路径 C:\\SGP_KF\\ZhuiGuangAI\\zhuiguang-ai\\Pem\\zg.pem 已失效）",
|
||||
"部署目录：/home/ubuntu/zhuiguang-ai",
|
||||
"数据库：阿里云 RDS MySQL rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai",
|
||||
"共享服务（禁动）：redis-cache:6379、nacos:8848、minio:9000、系统 nginx:80/443",
|
||||
"nginx 站点配置：/etc/nginx/sites-enabled/zhuiguang-ai → 127.0.0.1:8301",
|
||||
"SSL 证书：/etc/letsencrypt/live/www.zhuig.com（自动续期）",
|
||||
"邻居项目（只读）：zhuiguang-quant、zhenfang、snowy-fgt、agent-system、nacos、gpsj2-webhook"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Deployment",
|
||||
"name": "追光AI:容器化部署",
|
||||
"observations": [
|
||||
"镜像：zhuiguang-ai:2.1.3（多阶段构建 Dockerfile）",
|
||||
"容器1：zhuiguang-ai-app（Next.js，端口 8301，healthcheck /api/health）",
|
||||
"容器2：zhuiguang-ai-cron（supercronic 调度，healthcheck pgrep supercronic）",
|
||||
"网络：network_mode: host（直接访问宿主机 Redis/Nacos/MinIO）",
|
||||
"命名卷：zhuiguang-ai_bot-data / zhuiguang-ai_bot-public / zhuiguang-ai_bot-logs / zhuiguang-ai_bot-prisma",
|
||||
"生产环境变量：/home/ubuntu/zhuiguang-ai/env/.env.production（chmod 600）",
|
||||
"部署脚本：scripts/deploy-build.sh（docker build --build-arg DATABASE_URL）+ scripts/deploy-run.sh（docker stop/rm + docker run）",
|
||||
"部署方式：非 git 拉取式，服务器仓库无 git remote",
|
||||
"2026-10-01 状态：两容器均 Up 21h (healthy)，/api/health 返回 database ok"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "ScheduledTask",
|
||||
"name": "追光AI:定时任务体系",
|
||||
"observations": [
|
||||
"调度器：zhuiguang-ai-cron 容器内 supercronic，配置文件 crontab.txt（容器内按 UTC 执行 = 北京时间 -8h）",
|
||||
"启用任务数：19 个",
|
||||
"启用清单：task1-discover-tools、task3-check-tools、task4-discover-skills(daily-discover)、task5-update-stars、task6-review-hot、daily-news、task7-news-to-community、cleanup-logs、cleanup-task-logs、reconcile-like-counts、health-check、weekly-recommend-email、grant-freeze-cards、notification-digest、newsletter-generate、competitor-monitor、trend-alert、enrich-tool-data、industry-thinktank(collect)",
|
||||
"已停用：bot-activity、bot-skill-crystallize、bot-affinity-update、bot-weekly-review、bot-feedback-loop、bot-adversarial-learning-run、bot-persona-experiment-run、bot-roundtable、industry-thinktank(weekly/respond)、industry-daily(daily/respond)",
|
||||
"停用原因：2026-09-05 旧『模拟真人互刷』Bot 体系退役；2026-09-26 按要求关闭全部 AI 生成功能（行业情报改为需登录访问）",
|
||||
"四方同步要求：新增任务须同步 crontab.txt + seed-task-configs.mjs + health-check.mjs",
|
||||
"已知漂移(2026-10-01)：seed-task-configs.mjs 仍 enabled:true、health-check.mjs 仍列为期望键，会产生误告警"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Subsystem",
|
||||
"name": "追光AI:数字人Bot系统",
|
||||
"observations": [
|
||||
"角色定义：data/bot-characters.json，当前仅 6 个『行业情报官』角色（cb_intel、fi_ins_intel、fi_stock_intel、brand_intel、ai_intel、ct_intel）",
|
||||
"历史：曾为 112 个角色体系，2026-09-05 退役，改由行业情报官引擎承担",
|
||||
"头像资源：public/bot-avatars 178 个 SVG；会员头像库 public/avatars 530 个 SVG",
|
||||
"Bot 用户标记：User.isBot = true",
|
||||
"Bot 专用表 12 张：BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "DataModel",
|
||||
"name": "追光AI:数据模型",
|
||||
"observations": [
|
||||
"ORM：Prisma 7.8 + PrismaMariaDb adapter（禁止直接 new PrismaClient()），datasource.url 位于 prisma.config.ts",
|
||||
"模型总数：56 个（prisma/schema.prisma）",
|
||||
"迁移：prisma/migrations 共 22 个",
|
||||
"命名约定：模型 PascalCase + @@map(snake_case)；字段 camelCase + @map(snake_case)",
|
||||
"库：阿里云 RDS MySQL zhuiguang_ai（严禁 DROP/TRUNCATE/删迁移，走 migrate deploy 前向变更）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Repository",
|
||||
"name": "追光AI:代码仓库与备份",
|
||||
"observations": [
|
||||
"当前工作副本：E:\\KF_7\\ZhuiGuangAI\\zhuiguang-ai（master，18 个提交，~500 项未提交改动）",
|
||||
"本地裸仓镜像：K:\\git-repos\\zhuiguang-ai.git（2026-10-01 新建，bare，HEAD=master）",
|
||||
"裸仓校验：HEAD b44601b 与源一致、18 提交、1504 对象、git fsck 无错",
|
||||
"远程现状：E:\\KF_7 的 remote『local』仍指向已不存在的 c:\\gitbf\\zhuiguang-ai.git",
|
||||
"副本 E:\\ZG_Dev\\ZhuiGuangAI\\zhuiguang-ai：停在 6c78c32(2026-05-23)，无 remote，历史已被 E:\\KF_7 完整包含",
|
||||
"旧副本 K:\\git-repos\\zhuiguang-ai（非裸仓）：停在 2026-05-23，origin 指向 E:\\ZG_Dev",
|
||||
"云端 Gitea（119.45.242.239:3000，v1.27.1）：本项目无仓库，无法推送"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(01-数据库)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/01-database.md",
|
||||
"覆盖 Prisma Schema、56 个数据模型、MariaDB/RDS"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(02-API)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/02-api.md",
|
||||
"覆盖 REST API 路由（154 个 route.ts）、认证、缓存、v1 公开 API",
|
||||
"响应约定：列表 {data,total,page,pageSize}；错误 {success:false,error}"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(03-页面)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/03-pages.md",
|
||||
"Next.js 14 App Router 页面体系（61 个 page.tsx）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(04-组件与样式)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/04-components-and-styles.md",
|
||||
"UI 组件库（90 个 tsx）、Tailwind CSS、shadcn/ui"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(05-AI发现)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/05-ai-discovery.md",
|
||||
"提示词+JSON 粘贴导入模式，不调用外部 AI API"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(06-认证)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/06-auth.md",
|
||||
"NextAuth v4 Credentials、RBAC、API Key 认证、middleware 保护 /admin 与 /api/admin"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(07-库与脚本)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/07-lib-and-scripts.md",
|
||||
"src/lib 纯函数库 + scripts/ 定时任务与运维脚本（69 个 mjs）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(08-社区)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/08-community.md",
|
||||
"论坛、帖子、评论、签到、排行榜、举报、通知"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(09-运维与部署)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/09-devops.md",
|
||||
"容器化部署、crontab、备份、监控；注意该文档仍写『本地Git同步目录 C:\\gitbf』，与工作区规则 K:\\git-repos 不一致"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Module",
|
||||
"name": "追光AI:模块(10-Bot系统)",
|
||||
"observations": [
|
||||
"规格文档：.trae/specs/modules/10-bot-system.md",
|
||||
"数字人 Bot 引擎；旧体系已于 2026-09-05 退役，现为行业情报官引擎"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Convention",
|
||||
"name": "追光AI:开发约定(导航与图片)",
|
||||
"observations": [
|
||||
"页面内导航必须用 next/link <Link>，禁止 button+router.push；仅外链用 <a target=_blank rel=noopener noreferrer>",
|
||||
"图片强制使用 src/components/ui/LazyImage.tsx，禁止原生 <img>",
|
||||
"首屏 LCP 图片加 priority，每页最多 1-2 张",
|
||||
"长列表(>50) 用 VirtualList 虚拟滚动"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Convention",
|
||||
"name": "追光AI:开发约定(数据获取与性能)",
|
||||
"observations": [
|
||||
"含 generateStaticParams 的页面必须声明 export const revalidate 与 dynamicParams",
|
||||
"高频读接口使用 cachedResponse 缓存，写入后 invalidateCache 失效",
|
||||
"详情页用 include/_count 一次取关联计数，禁止 N+1",
|
||||
"互不依赖的 Prisma 查询必须 Promise.all 并行",
|
||||
"非首屏组件用 next/dynamic 懒加载"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Convention",
|
||||
"name": "追光AI:开发约定(安全与校验)",
|
||||
"observations": [
|
||||
"API 路由必须用 Zod 校验请求体；批量上限：工具/技能导入 100、新闻 50、发布 500",
|
||||
"后台写操作 API 必须调用 requireAdmin()",
|
||||
"禁止硬编码密钥，全部走环境变量且 .env.example 同步",
|
||||
"CSP script-src 必须含 'unsafe-inline'（Next.js App Router 水合依赖），禁止 'unsafe-eval'",
|
||||
"外键回退值禁止硬编码魔法数字，须查库取有效 ID"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Issue",
|
||||
"name": "追光AI:巡检问题与处理(2026-10-01)",
|
||||
"observations": [
|
||||
"规则文件 SSH 密钥路径失效：写 C:\\SGP_KF\\...\\Pem\\zg.pem，实际 E:\\0.Center-S2\\S890-V3\\pem\\zg.pem",
|
||||
"双份 project_rules.md 并存且冲突：工作区根 908 行 / 项目内 357 行",
|
||||
"规格文档不自洽：根 modules.md 索引 10 个模块但实际仅 5 个文件，且与项目内 17 个文件命名体系不同",
|
||||
"定时任务四方同步漂移：crontab 已停用 vs seed-task-configs 仍 enabled:true vs health-check 仍期望",
|
||||
"版本号不一致：package.json V2.1.2 vs 镜像 tag zhuiguang-ai:2.1.3",
|
||||
"规则中『112 个 Bot 角色』已过期，实际 6 个行业情报官",
|
||||
"本地约 500 项未提交改动未进入任何备份",
|
||||
"Gitea 无本项目仓库，且本地 remote 指向不存在的 c:\\gitbf",
|
||||
"✅ 2026-10-01 已处理(规则侧)：SSH 密钥路径、工作区/裸仓镜像/远端现状、Bot 角色数(112→6)、头像数、seed 任务数(6→29)、定时任务表(改为 UTC 并标注停用)、KG 同步方式，均已同步进两份 project_rules.md",
|
||||
"✅ 2026-10-01 已处理(备份侧)：新建裸仓 K:\\git-repos\\zhuiguang-ai.git 并推入 master(18 提交/1504 对象/fsck 无错)",
|
||||
"✅ 2026-10-01 已处理(图谱侧)：建立 .trae/knowledge_graph.jsonl(21 实体/23 关系) 与渲染版 .trae/knowledge_graph.json",
|
||||
"⏳ 待处理：.trae/mcp.json 为受保护文件，需人工写入 Knowledge Graph Memory 配置",
|
||||
"⏳ 待处理：本地 remote『local』仍指向不存在的 c:\\gitbf；约 500 项未提交改动未进备份",
|
||||
"⏳ 待处理：规格文档不自洽（根 modules.md 索引 10 个模块但仅存 5 个文件；根/项目两套命名体系不同，05 一边 auth 一边 ai-discovery）",
|
||||
"⏳ 待处理：定时任务三方漂移（crontab 停用 vs seed-task-configs enabled:true vs health-check 期望键）",
|
||||
"⏳ 待处理：版本号不一致（package.json V2.1.2 vs 镜像 tag zhuiguang-ai:2.1.3）",
|
||||
"⏳ 待处理：双份 project_rules.md 仍并存未合并（工作区根 908 行 / 项目内约 380 行）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Convention",
|
||||
"name": "追光AI:AI协作知识体系",
|
||||
"observations": [
|
||||
"四层结构：L0 方法层 .trae/ai_coding_knowledge.json（AI 编程方法/工具/工作流/原则/反模式，机器可解析）｜L1 协作层 .trae/rules/README.md + ai_agent_rules.md + ai_collaboration.md｜L2 工程层 .trae/rules/project_rules.md｜L3 事实层 .trae/knowledge_graph.jsonl/.json + .trae/knowledge/*",
|
||||
"自动化记录：node scripts/update-knowledge.mjs（npm run knowledge:update）— 捕获能力特征→.trae/knowledge/capabilities.json、开发过程→dev_process.jsonl、模型成果→artifacts.jsonl，并增量 upsert 知识图谱 json+jsonl",
|
||||
"触发方式：git post-commit 钩子（后台静默，不阻断提交）+ 任务收尾手动执行；换机需按 ai_collaboration.md §6 重装钩子",
|
||||
"幂等保证：能力快照按实体名整条替换；开发过程按提交 hash 去重；模型成果按(日期+head提交)去重；旧实体永不删除",
|
||||
"单一事实源：同一事实只存一处，其余位置只写引用（禁止复制，见反模式 divergent-copies）",
|
||||
"入口文档：.trae/rules/README.md（§4 自动化闭环 / §5 维护规则）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "Capability",
|
||||
"name": "追光AI:能力快照",
|
||||
"observations": [
|
||||
"版本: V2.1.2",
|
||||
"代码规模: API 路由 154 / 页面 61 / 组件 90 / hooks 1 / lib 38",
|
||||
"数据层: Prisma 模型 56 个、迁移 22 个（最新 20260605010000_forum_phase5、20260607000000_bot_persona_ab_test、20260607010000_bot_adversarial_learning、20260824170000_add_public_share_and_screenshots、20260905180000_add_thinktank）",
|
||||
"脚本: 79 个（含定时任务与运维脚本）",
|
||||
"定时任务: 启用 19 个 —— task1-discover-tools、task3-check-tools、daily-discover、task5-update-stars、task6-review-hot、daily-news、task7-news-to-community、cleanup-logs、cleanup-task-logs、reconcile-like-counts、health-check、weekly-recommend-email、grant-freeze-cards、notification-digest、newsletter-generate、competitor-monitor、trend-alert、enrich-tool-data、industry-thinktank",
|
||||
"数字人角色: 6 个（cb_intel、fi_ins_intel、fi_stock_intel、brand_intel、ai_intel、ct_intel）",
|
||||
"依赖: dependencies 26 / devDependencies 15（next 14.2.35、prisma ^7.8.0、react ^18）",
|
||||
"快照时间: 2026-10-01T09:04:53（由 scripts/update-knowledge.mjs 自动生成，勿手工编辑）"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "entity",
|
||||
"entityType": "fact",
|
||||
"name": "开发记录:2026-10-01",
|
||||
"observations": [
|
||||
"记录时间: 2026-10-01T09:04:53",
|
||||
"本次交付: b44601bb feat: 全面优化系统 - 修复task1语法错误 + Bot超时保护 + 熔断重试 + Redis缓存 + SEO + 日志清理 + 内容质量评估（改动文件 12 个、12 files changed, 399 insertions(+), 12 deletions(-)）",
|
||||
"能力基线: API 154 / 页面 61 / 组件 90 / 模型 56 / 迁移 22 / 脚本 79 / 定时任务 19",
|
||||
"b44601bb 2026-06-13 feat: 全面优化系统 - 修复task1语法错误 + Bot超时保护 + 熔断重试 + Redis缓存 + SEO + 日志清理 + 内容质量评估",
|
||||
"a0a60ee9 2026-06-12 fix: 修复6个use client页面metadata冲突，创建layout.tsx承载metadata",
|
||||
"4c325c86 2026-06-12 全项目扫描修复: Docker数据卷修复+安全requireAdmin+12页SEO+API白名单+脚本超时+常量提取+假数据删除",
|
||||
"464924ae 2026-06-01 fix: 修复bot-activity两个致命BUG + 添加3个passerby bot补充板块覆盖 + 减少GoogleNews超时",
|
||||
"a9145c4d 2026-06-01 修复自动化任务：bot-activity上线 + task7板块slug修复 + cron强化",
|
||||
"维护: 运行 npm run knowledge:update 刷新本记录"
|
||||
]
|
||||
}
|
||||
],
|
||||
"relations": [
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_INFRASTRUCTURE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:服务器与基础设施"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_DEPLOYMENT",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:容器化部署"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_SCHEDULED_TASKS",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:定时任务体系"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_SUBSYSTEM",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:数字人Bot系统"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_DATAMODEL",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:数据模型"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_REPOSITORY",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:代码仓库与备份"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_ISSUE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:巡检问题与处理(2026-10-01)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(01-数据库)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(02-API)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(03-页面)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(04-组件与样式)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(05-AI发现)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(06-认证)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(07-库与脚本)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(08-社区)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(09-运维与部署)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_MODULE",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:模块(10-Bot系统)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_CONVENTION",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:开发约定(导航与图片)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_CONVENTION",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:开发约定(数据获取与性能)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_CONVENTION",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:开发约定(安全与校验)"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "DEPLOYED_ON",
|
||||
"from": "追光AI:容器化部署",
|
||||
"to": "追光AI:服务器与基础设施"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "BACKED_UP_TO",
|
||||
"from": "追光AI:代码仓库与备份",
|
||||
"to": "K:\\git-repos\\zhuiguang-ai.git"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "RUNS_ON",
|
||||
"from": "追光AI:定时任务体系",
|
||||
"to": "追光AI:容器化部署"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_CAPABILITY",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:能力快照"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_DEV_RECORD",
|
||||
"from": "追光AI",
|
||||
"to": "开发记录:2026-10-01"
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"relationType": "HAS_CONVENTION",
|
||||
"from": "追光AI",
|
||||
"to": "追光AI:AI协作知识体系"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
{"type":"entity","entityType":"Project","name":"追光AI","observations":["项目名称：追光AI (zhuiguang-ai)，AI 工具与技能发现/评测/社区平台","技术栈：Next.js 14 App Router + TypeScript(strict) + Tailwind CSS + shadcn/ui + Prisma 7.8(MariaDB adapter) + MySQL(阿里云RDS) + NextAuth v4 + Redis(ioredis)","版本：V2.1.2（package.json；Docker 镜像 tag zhuiguang-ai:2.1.3）","生产域名：https://www.zhuig.com（备用 ai.zhuig.com）","端口锁定：8301-8310，默认 8301","代码规模：154 个 API 路由(route.ts)、61 个页面(page.tsx)、90 个组件(tsx)、69 个脚本(mjs)、56 个 Prisma 模型、22 个迁移","本地工作副本：E:\\KF_7\\ZhuiGuangAI\\zhuiguang-ai（master）","2026-10-01 巡检：本地源码与服务器 /home/ubuntu/zhuiguang-ai 源码逐文件一致（493 个文件 MD5 相同）"]}
|
||||
{"type":"entity","entityType":"Infrastructure","name":"追光AI:服务器与基础设施","observations":["服务器：119.45.242.239（登录用户 ubuntu）","SSH 私钥：E:\\0.Center-S2\\S890-V3\\pem\\zg.pem（规则旧路径 C:\\SGP_KF\\ZhuiGuangAI\\zhuiguang-ai\\Pem\\zg.pem 已失效）","部署目录：/home/ubuntu/zhuiguang-ai","数据库：阿里云 RDS MySQL rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai","共享服务（禁动）：redis-cache:6379、nacos:8848、minio:9000、系统 nginx:80/443","nginx 站点配置：/etc/nginx/sites-enabled/zhuiguang-ai → 127.0.0.1:8301","SSL 证书：/etc/letsencrypt/live/www.zhuig.com（自动续期）","邻居项目（只读）：zhuiguang-quant、zhenfang、snowy-fgt、agent-system、nacos、gpsj2-webhook"]}
|
||||
{"type":"entity","entityType":"Deployment","name":"追光AI:容器化部署","observations":["镜像：zhuiguang-ai:2.1.3（多阶段构建 Dockerfile）","容器1：zhuiguang-ai-app（Next.js，端口 8301，healthcheck /api/health）","容器2：zhuiguang-ai-cron（supercronic 调度，healthcheck pgrep supercronic）","网络：network_mode: host（直接访问宿主机 Redis/Nacos/MinIO）","命名卷：zhuiguang-ai_bot-data / zhuiguang-ai_bot-public / zhuiguang-ai_bot-logs / zhuiguang-ai_bot-prisma","生产环境变量：/home/ubuntu/zhuiguang-ai/env/.env.production（chmod 600）","部署脚本：scripts/deploy-build.sh（docker build --build-arg DATABASE_URL）+ scripts/deploy-run.sh（docker stop/rm + docker run）","部署方式：非 git 拉取式，服务器仓库无 git remote","2026-10-01 状态：两容器均 Up 21h (healthy)，/api/health 返回 database ok"]}
|
||||
{"type":"entity","entityType":"ScheduledTask","name":"追光AI:定时任务体系","observations":["调度器：zhuiguang-ai-cron 容器内 supercronic，配置文件 crontab.txt（容器内按 UTC 执行 = 北京时间 -8h）","启用任务数：19 个","启用清单：task1-discover-tools、task3-check-tools、task4-discover-skills(daily-discover)、task5-update-stars、task6-review-hot、daily-news、task7-news-to-community、cleanup-logs、cleanup-task-logs、reconcile-like-counts、health-check、weekly-recommend-email、grant-freeze-cards、notification-digest、newsletter-generate、competitor-monitor、trend-alert、enrich-tool-data、industry-thinktank(collect)","已停用：bot-activity、bot-skill-crystallize、bot-affinity-update、bot-weekly-review、bot-feedback-loop、bot-adversarial-learning-run、bot-persona-experiment-run、bot-roundtable、industry-thinktank(weekly/respond)、industry-daily(daily/respond)","停用原因：2026-09-05 旧『模拟真人互刷』Bot 体系退役；2026-09-26 按要求关闭全部 AI 生成功能（行业情报改为需登录访问）","四方同步要求：新增任务须同步 crontab.txt + seed-task-configs.mjs + health-check.mjs","已知漂移(2026-10-01)：seed-task-configs.mjs 仍 enabled:true、health-check.mjs 仍列为期望键，会产生误告警"]}
|
||||
{"type":"entity","entityType":"Subsystem","name":"追光AI:数字人Bot系统","observations":["角色定义：data/bot-characters.json，当前仅 6 个『行业情报官』角色（cb_intel、fi_ins_intel、fi_stock_intel、brand_intel、ai_intel、ct_intel）","历史：曾为 112 个角色体系，2026-09-05 退役，改由行业情报官引擎承担","头像资源：public/bot-avatars 178 个 SVG；会员头像库 public/avatars 530 个 SVG","Bot 用户标记：User.isBot = true","Bot 专用表 12 张：BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity"]}
|
||||
{"type":"entity","entityType":"DataModel","name":"追光AI:数据模型","observations":["ORM：Prisma 7.8 + PrismaMariaDb adapter（禁止直接 new PrismaClient()），datasource.url 位于 prisma.config.ts","模型总数：56 个（prisma/schema.prisma）","迁移：prisma/migrations 共 22 个","命名约定：模型 PascalCase + @@map(snake_case)；字段 camelCase + @map(snake_case)","库：阿里云 RDS MySQL zhuiguang_ai（严禁 DROP/TRUNCATE/删迁移，走 migrate deploy 前向变更）"]}
|
||||
{"type":"entity","entityType":"Repository","name":"追光AI:代码仓库与备份","observations":["当前工作副本：E:\\KF_7\\ZhuiGuangAI\\zhuiguang-ai（master，18 个提交，~500 项未提交改动）","本地裸仓镜像：K:\\git-repos\\zhuiguang-ai.git（2026-10-01 新建，bare，HEAD=master）","裸仓校验：HEAD b44601b 与源一致、18 提交、1504 对象、git fsck 无错","远程现状：E:\\KF_7 的 remote『local』仍指向已不存在的 c:\\gitbf\\zhuiguang-ai.git","副本 E:\\ZG_Dev\\ZhuiGuangAI\\zhuiguang-ai：停在 6c78c32(2026-05-23)，无 remote，历史已被 E:\\KF_7 完整包含","旧副本 K:\\git-repos\\zhuiguang-ai（非裸仓）：停在 2026-05-23，origin 指向 E:\\ZG_Dev","云端 Gitea（119.45.242.239:3000，v1.27.1）：本项目无仓库，无法推送"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(01-数据库)","observations":["规格文档：.trae/specs/modules/01-database.md","覆盖 Prisma Schema、56 个数据模型、MariaDB/RDS"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(02-API)","observations":["规格文档：.trae/specs/modules/02-api.md","覆盖 REST API 路由（154 个 route.ts）、认证、缓存、v1 公开 API","响应约定：列表 {data,total,page,pageSize}；错误 {success:false,error}"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(03-页面)","observations":["规格文档：.trae/specs/modules/03-pages.md","Next.js 14 App Router 页面体系（61 个 page.tsx）"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(04-组件与样式)","observations":["规格文档：.trae/specs/modules/04-components-and-styles.md","UI 组件库（90 个 tsx）、Tailwind CSS、shadcn/ui"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(05-AI发现)","observations":["规格文档：.trae/specs/modules/05-ai-discovery.md","提示词+JSON 粘贴导入模式，不调用外部 AI API"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(06-认证)","observations":["规格文档：.trae/specs/modules/06-auth.md","NextAuth v4 Credentials、RBAC、API Key 认证、middleware 保护 /admin 与 /api/admin"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(07-库与脚本)","observations":["规格文档：.trae/specs/modules/07-lib-and-scripts.md","src/lib 纯函数库 + scripts/ 定时任务与运维脚本（69 个 mjs）"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(08-社区)","observations":["规格文档：.trae/specs/modules/08-community.md","论坛、帖子、评论、签到、排行榜、举报、通知"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(09-运维与部署)","observations":["规格文档：.trae/specs/modules/09-devops.md","容器化部署、crontab、备份、监控；注意该文档仍写『本地Git同步目录 C:\\gitbf』，与工作区规则 K:\\git-repos 不一致"]}
|
||||
{"type":"entity","entityType":"Module","name":"追光AI:模块(10-Bot系统)","observations":["规格文档：.trae/specs/modules/10-bot-system.md","数字人 Bot 引擎；旧体系已于 2026-09-05 退役，现为行业情报官引擎"]}
|
||||
{"type":"entity","entityType":"Convention","name":"追光AI:开发约定(导航与图片)","observations":["页面内导航必须用 next/link <Link>，禁止 button+router.push；仅外链用 <a target=_blank rel=noopener noreferrer>","图片强制使用 src/components/ui/LazyImage.tsx，禁止原生 <img>","首屏 LCP 图片加 priority，每页最多 1-2 张","长列表(>50) 用 VirtualList 虚拟滚动"]}
|
||||
{"type":"entity","entityType":"Convention","name":"追光AI:开发约定(数据获取与性能)","observations":["含 generateStaticParams 的页面必须声明 export const revalidate 与 dynamicParams","高频读接口使用 cachedResponse 缓存，写入后 invalidateCache 失效","详情页用 include/_count 一次取关联计数，禁止 N+1","互不依赖的 Prisma 查询必须 Promise.all 并行","非首屏组件用 next/dynamic 懒加载"]}
|
||||
{"type":"entity","entityType":"Convention","name":"追光AI:开发约定(安全与校验)","observations":["API 路由必须用 Zod 校验请求体；批量上限：工具/技能导入 100、新闻 50、发布 500","后台写操作 API 必须调用 requireAdmin()","禁止硬编码密钥，全部走环境变量且 .env.example 同步","CSP script-src 必须含 'unsafe-inline'（Next.js App Router 水合依赖），禁止 'unsafe-eval'","外键回退值禁止硬编码魔法数字，须查库取有效 ID"]}
|
||||
{"type":"entity","entityType":"Issue","name":"追光AI:巡检问题与处理(2026-10-01)","observations":["规则文件 SSH 密钥路径失效：写 C:\\SGP_KF\\...\\Pem\\zg.pem，实际 E:\\0.Center-S2\\S890-V3\\pem\\zg.pem","双份 project_rules.md 并存且冲突：工作区根 908 行 / 项目内 357 行","规格文档不自洽：根 modules.md 索引 10 个模块但实际仅 5 个文件，且与项目内 17 个文件命名体系不同","定时任务四方同步漂移：crontab 已停用 vs seed-task-configs 仍 enabled:true vs health-check 仍期望","版本号不一致：package.json V2.1.2 vs 镜像 tag zhuiguang-ai:2.1.3","规则中『112 个 Bot 角色』已过期，实际 6 个行业情报官","本地约 500 项未提交改动未进入任何备份","Gitea 无本项目仓库，且本地 remote 指向不存在的 c:\\gitbf","✅ 2026-10-01 已处理(规则侧)：SSH 密钥路径、工作区/裸仓镜像/远端现状、Bot 角色数(112→6)、头像数、seed 任务数(6→29)、定时任务表(改为 UTC 并标注停用)、KG 同步方式，均已同步进两份 project_rules.md","✅ 2026-10-01 已处理(备份侧)：新建裸仓 K:\\git-repos\\zhuiguang-ai.git 并推入 master(18 提交/1504 对象/fsck 无错)","✅ 2026-10-01 已处理(图谱侧)：建立 .trae/knowledge_graph.jsonl(21 实体/23 关系) 与渲染版 .trae/knowledge_graph.json","⏳ 待处理：.trae/mcp.json 为受保护文件，需人工写入 Knowledge Graph Memory 配置","⏳ 待处理：本地 remote『local』仍指向不存在的 c:\\gitbf；约 500 项未提交改动未进备份","⏳ 待处理：规格文档不自洽（根 modules.md 索引 10 个模块但仅存 5 个文件；根/项目两套命名体系不同，05 一边 auth 一边 ai-discovery）","⏳ 待处理：定时任务三方漂移（crontab 停用 vs seed-task-configs enabled:true vs health-check 期望键）","⏳ 待处理：版本号不一致（package.json V2.1.2 vs 镜像 tag zhuiguang-ai:2.1.3）","⏳ 待处理：双份 project_rules.md 仍并存未合并（工作区根 908 行 / 项目内约 380 行）","✅ 2026-10-01 已处理(知识库侧)：建立 AI 编程效率知识库 .trae/ai_coding_knowledge.json、规则体系四层索引 .trae/rules/README.md + ai_agent_rules.md + ai_collaboration.md、自动化记录 scripts/update-knowledge.mjs（能力特征/开发过程/模型成果）+ npm run knowledge:update + git post-commit 钩子"]}
|
||||
{"type":"entity","entityType":"Convention","name":"追光AI:AI协作知识体系","observations":["四层结构：L0 方法层 .trae/ai_coding_knowledge.json（AI 编程方法/工具/工作流/原则/反模式，机器可解析）｜L1 协作层 .trae/rules/README.md + ai_agent_rules.md + ai_collaboration.md｜L2 工程层 .trae/rules/project_rules.md｜L3 事实层 .trae/knowledge_graph.jsonl/.json + .trae/knowledge/*","自动化记录：node scripts/update-knowledge.mjs（npm run knowledge:update）— 捕获能力特征→.trae/knowledge/capabilities.json、开发过程→dev_process.jsonl、模型成果→artifacts.jsonl，并增量 upsert 知识图谱 json+jsonl","触发方式：git post-commit 钩子（后台静默，不阻断提交）+ 任务收尾手动执行；换机需按 ai_collaboration.md §6 重装钩子","幂等保证：能力快照按实体名整条替换；开发过程按提交 hash 去重；模型成果按(日期+head提交)去重；旧实体永不删除","单一事实源：同一事实只存一处，其余位置只写引用（禁止复制，见反模式 divergent-copies）","入口文档：.trae/rules/README.md（§4 自动化闭环 / §5 维护规则）"]}
|
||||
{"type":"entity","entityType":"Capability","name":"追光AI:能力快照","observations":["版本: V2.1.2","代码规模: API 路由 154 / 页面 61 / 组件 90 / hooks 1 / lib 38","数据层: Prisma 模型 56 个、迁移 22 个（最新 20260605010000_forum_phase5、20260607000000_bot_persona_ab_test、20260607010000_bot_adversarial_learning、20260824170000_add_public_share_and_screenshots、20260905180000_add_thinktank）","脚本: 79 个（含定时任务与运维脚本）","定时任务: 启用 19 个 —— task1-discover-tools、task3-check-tools、daily-discover、task5-update-stars、task6-review-hot、daily-news、task7-news-to-community、cleanup-logs、cleanup-task-logs、reconcile-like-counts、health-check、weekly-recommend-email、grant-freeze-cards、notification-digest、newsletter-generate、competitor-monitor、trend-alert、enrich-tool-data、industry-thinktank","数字人角色: 6 个（cb_intel、fi_ins_intel、fi_stock_intel、brand_intel、ai_intel、ct_intel）","依赖: dependencies 26 / devDependencies 15（next 14.2.35、prisma ^7.8.0、react ^18）","快照时间: 2026-10-01T09:04:53（由 scripts/update-knowledge.mjs 自动生成，勿手工编辑）"]}
|
||||
{"type":"entity","entityType":"fact","name":"开发记录:2026-10-01","observations":["记录时间: 2026-10-01T09:04:53","本次交付: b44601bb feat: 全面优化系统 - 修复task1语法错误 + Bot超时保护 + 熔断重试 + Redis缓存 + SEO + 日志清理 + 内容质量评估（改动文件 12 个、12 files changed, 399 insertions(+), 12 deletions(-)）","能力基线: API 154 / 页面 61 / 组件 90 / 模型 56 / 迁移 22 / 脚本 79 / 定时任务 19","b44601bb 2026-06-13 feat: 全面优化系统 - 修复task1语法错误 + Bot超时保护 + 熔断重试 + Redis缓存 + SEO + 日志清理 + 内容质量评估","a0a60ee9 2026-06-12 fix: 修复6个use client页面metadata冲突，创建layout.tsx承载metadata","4c325c86 2026-06-12 全项目扫描修复: Docker数据卷修复+安全requireAdmin+12页SEO+API白名单+脚本超时+常量提取+假数据删除","464924ae 2026-06-01 fix: 修复bot-activity两个致命BUG + 添加3个passerby bot补充板块覆盖 + 减少GoogleNews超时","a9145c4d 2026-06-01 修复自动化任务：bot-activity上线 + task7板块slug修复 + cron强化","维护: 运行 npm run knowledge:update 刷新本记录"]}
|
||||
{"type":"relation","relationType":"HAS_INFRASTRUCTURE","from":"追光AI","to":"追光AI:服务器与基础设施"}
|
||||
{"type":"relation","relationType":"HAS_DEPLOYMENT","from":"追光AI","to":"追光AI:容器化部署"}
|
||||
{"type":"relation","relationType":"HAS_SCHEDULED_TASKS","from":"追光AI","to":"追光AI:定时任务体系"}
|
||||
{"type":"relation","relationType":"HAS_SUBSYSTEM","from":"追光AI","to":"追光AI:数字人Bot系统"}
|
||||
{"type":"relation","relationType":"HAS_DATAMODEL","from":"追光AI","to":"追光AI:数据模型"}
|
||||
{"type":"relation","relationType":"HAS_REPOSITORY","from":"追光AI","to":"追光AI:代码仓库与备份"}
|
||||
{"type":"relation","relationType":"HAS_ISSUE","from":"追光AI","to":"追光AI:巡检问题与处理(2026-10-01)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(01-数据库)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(02-API)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(03-页面)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(04-组件与样式)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(05-AI发现)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(06-认证)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(07-库与脚本)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(08-社区)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(09-运维与部署)"}
|
||||
{"type":"relation","relationType":"HAS_MODULE","from":"追光AI","to":"追光AI:模块(10-Bot系统)"}
|
||||
{"type":"relation","relationType":"HAS_CONVENTION","from":"追光AI","to":"追光AI:开发约定(导航与图片)"}
|
||||
{"type":"relation","relationType":"HAS_CONVENTION","from":"追光AI","to":"追光AI:开发约定(数据获取与性能)"}
|
||||
{"type":"relation","relationType":"HAS_CONVENTION","from":"追光AI","to":"追光AI:开发约定(安全与校验)"}
|
||||
{"type":"relation","relationType":"DEPLOYED_ON","from":"追光AI:容器化部署","to":"追光AI:服务器与基础设施"}
|
||||
{"type":"relation","relationType":"BACKED_UP_TO","from":"追光AI:代码仓库与备份","to":"K:\\git-repos\\zhuiguang-ai.git"}
|
||||
{"type":"relation","relationType":"RUNS_ON","from":"追光AI:定时任务体系","to":"追光AI:容器化部署"}
|
||||
{"type":"relation","relationType":"HAS_CAPABILITY","from":"追光AI","to":"追光AI:能力快照"}
|
||||
{"type":"relation","relationType":"HAS_DEV_RECORD","from":"追光AI","to":"开发记录:2026-10-01"}
|
||||
{"type":"relation","relationType":"HAS_CONVENTION","from":"追光AI","to":"追光AI:AI协作知识体系"}
|
||||
@@ -0,0 +1,61 @@
|
||||
# 追光AI — 规则体系索引
|
||||
|
||||
> 版本: v1.0 | 更新: 2026-10-01 | 所有 `.trae` 内容均在代码仓库 `zhuiguang-ai/.trae/` 内，跟着 git 走
|
||||
|
||||
## 一、这套规则解决什么问题
|
||||
|
||||
AI 代理**每次会话都是无状态的**（不记得上次讨论）。规则与知识库的唯一作用，就是把跨会话的持久上下文注入进来。
|
||||
没有它们，AI 每次都会重新问、重新猜、重复踩坑 —— 迭代效率无法复利。
|
||||
|
||||
## 二、四层结构（单一事实源，互不复制）
|
||||
|
||||
| 层 | 载体 | 内容 | 何时加载 |
|
||||
|----|------|------|---------|
|
||||
| **L0 方法论** | `.trae/ai_coding_knowledge.json` | AI 编程效率的方法/工具/工作流/原则/反模式（**机器可解析**，不写业务） | 每次任务开始前 |
|
||||
| **L1 协作规则** | `.trae/rules/ai_agent_rules.md`<br>`.trae/rules/ai_collaboration.md` | 启动加载顺序、小任务豁免、Plan-first 流程、验收标准、完成自动记录 | 每次任务开始前 / 收尾时 |
|
||||
| **L2 工程标准** | `.trae/rules/project_rules.md` | 技术栈、数据获取、导航图片、无障碍、安全、定时任务、部署等硬规范 | 写代码时按需 |
|
||||
| **L3 项目事实** | `.trae/knowledge_graph.jsonl`（MCP 源）<br>`.trae/knowledge_graph.json`（渲染版）<br>`.trae/knowledge/*`（能力/过程/成果自动记录） | 模块、部署、定时任务、仓库、约定、巡检问题等**事实** | 需要项目具体知识时 |
|
||||
|
||||
> ⚠️ **禁止跨层复制**：同一事实只允许有一个权威载体，其余位置只写引用。复制必然漂移（见反模式 `divergent-copies`）。
|
||||
|
||||
## 三、快速导航
|
||||
|
||||
| 我要… | 读哪个 |
|
||||
|-------|--------|
|
||||
| 开始一个开发任务 | [ai_agent_rules.md](ai_agent_rules.md) §0 |
|
||||
| 知道怎么和 AI 协作、怎么算做完 | [ai_collaboration.md](ai_collaboration.md) |
|
||||
| 查 AI 编程方法论 / 选工具 | `.trae/ai_coding_knowledge.json` |
|
||||
| 查项目某个模块/部署/定时任务的事实 | `.trae/knowledge_graph.jsonl` |
|
||||
| 查编码硬规范（安全/API/图片/无障碍） | [project_rules.md](project_rules.md) |
|
||||
| 部署、运维、容器 | [project_rules.md](project_rules.md) §14–15（工程侧见 [specs/modules/09-devops.md](../specs/modules/09-devops.md)） |
|
||||
|
||||
## 四、自动化闭环
|
||||
|
||||
```
|
||||
开发完成
|
||||
│
|
||||
├─ npm run knowledge:update ← 手动/收尾执行
|
||||
└─ git post-commit hook ← 本机自动触发
|
||||
│
|
||||
▼
|
||||
scripts/update-knowledge.mjs
|
||||
│
|
||||
├─ .trae/knowledge/capabilities.json 能力特征（API/页面/组件/模型/脚本/任务/依赖）
|
||||
├─ .trae/knowledge/dev_process.jsonl 开发过程（按提交追加）
|
||||
├─ .trae/knowledge/artifacts.jsonl 模型成果（迁移/脚本/提交统计）
|
||||
└─ .trae/knowledge_graph.json / .jsonl 事实层增量 upsert
|
||||
```
|
||||
|
||||
## 五、维护规则
|
||||
|
||||
1. **方法/工具层变化** → 改 `.trae/ai_coding_knowledge.json`，同步 [ai_collaboration.md](ai_collaboration.md)
|
||||
2. **协作流程变化** → 改 [ai_collaboration.md](ai_collaboration.md)，同步更新 `ai_coding_knowledge.json` 中对应 `workflow:*`
|
||||
3. **项目事实变化** → 跑 `npm run knowledge:update`，或直接维护 `.trae/knowledge_graph.jsonl`
|
||||
4. **工程标准变化** → 改 [project_rules.md](project_rules.md)
|
||||
5. **废弃而非删除**：用 `> **已废弃 (date)**` 标注并写明替代方案，保留至少一个大版本周期
|
||||
|
||||
## 六、版本历史
|
||||
|
||||
| 日期 | 版本 | 变更 |
|
||||
|------|------|------|
|
||||
| 2026-10-01 | v1.0 | 初始版本：建立四层结构；新增 AI 编程知识库、AI 代理规则、AI 协作流程、自动记录脚本 |
|
||||
@@ -0,0 +1,88 @@
|
||||
# AI Agent 规则（启动与查询）
|
||||
|
||||
> 版本: v1.0 | 更新: 2026-10-01
|
||||
> 相关: [README.md](README.md) · [ai_collaboration.md](ai_collaboration.md) · `../ai_coding_knowledge.json`
|
||||
|
||||
目的：让 AI 在本项目中**每次任务开始前按固定顺序加载上下文**，开工前就知道方法、规范与既有事实，避免重复交代与重复踩坑。
|
||||
|
||||
---
|
||||
|
||||
## §0 启动加载顺序（最高优先级）
|
||||
|
||||
```
|
||||
1. .trae/rules/README.md ← 索引：先看有哪些层
|
||||
2. .trae/ai_coding_knowledge.json ← 方法层：按 entity.type 过滤（principle/method/workflow/anti_pattern/tool）
|
||||
3. .trae/rules/ai_collaboration.md ← 流程层：Plan-first / 验收标准 / 完成自动记录
|
||||
4. .trae/knowledge_graph.jsonl ← 事实层：按 name / observations 关键词检索相关实体（按需，不要全量读）
|
||||
5. .trae/rules/project_rules.md ← 工程标准：与本次改动相关的章节
|
||||
6. 具体源码（只读相关文件）
|
||||
```
|
||||
|
||||
**原则**：上下文是预算（见 `principle:context-budget`）。第 4、5 步**按需**加载，不要一次性灌入全部历史。
|
||||
|
||||
## §1 小任务豁免清单
|
||||
|
||||
以下任务**无需**走完整启动流程，可直接执行：
|
||||
|
||||
| 豁免类型 | 示例 |
|
||||
|---------|------|
|
||||
| 拼写修正 | 修改变量名拼写 |
|
||||
| 注释/文案 | 增删注释、改中文提示文案 |
|
||||
| 格式调整 | 缩进、空行、引号风格 |
|
||||
| 单值配置 | 改端口号、超时时间等单个常量 |
|
||||
| 纯查询 | 「XX 在哪」「XX 是什么意思」（不改代码） |
|
||||
| 已给完整方案 | 用户已提供明确的文件+改法 |
|
||||
|
||||
## §2 非小任务：强制先查知识库
|
||||
|
||||
不属于 §1 的任务，开工前**必须**先检索事实层：
|
||||
|
||||
```
|
||||
步骤1 读 .trae/rules/README.md 确定应查哪一层
|
||||
步骤2 在 .trae/knowledge_graph.jsonl 中按关键词检索（name / observations）
|
||||
优先匹配：实体名 > observations 关键词 > entityType 批量
|
||||
步骤3 命中则读取该实体 observations，确认规范/部署/踩坑/约束
|
||||
步骤4 再开始 Explore → Plan → Implement → Verify（见 ai_collaboration.md）
|
||||
```
|
||||
|
||||
### 检索优先级
|
||||
|
||||
| 优先级 | 方式 | 场景 |
|
||||
|--------|------|------|
|
||||
| 1 | 实体名精确匹配（如 `追光AI:容器化部署`） | 已知目标实体 |
|
||||
| 2 | observations 关键词（如 `cron`、`8301`、`Prisma`） | 知道主题 |
|
||||
| 3 | entityType 批量（如全部 `Issue`、全部 `ScheduledTask`） | 需要某类全貌 |
|
||||
|
||||
### 若 Knowledge Graph Memory MCP 不可用
|
||||
|
||||
直接读/写 `.trae/knowledge_graph.jsonl`（JSONL，一行一实体或关系）。改动后用 `npm run knowledge:update` 同步渲染版 `.json`。
|
||||
|
||||
## §3 查询后输出格式
|
||||
|
||||
命中实体时，在回复中简述（便于复核）：
|
||||
|
||||
```
|
||||
[KG] 命中 N 条:
|
||||
- Module: 追光AI:模块(09-运维与部署)
|
||||
- Issue : 追光AI:巡检问题与处理(2026-10-01)
|
||||
```
|
||||
|
||||
## §4 行为约束
|
||||
|
||||
### 必须
|
||||
1. 非豁免任务**必须先检索知识库**再动手
|
||||
2. 发现代码与已记录规范/事实冲突时**必须指出**，不得静默按代码走
|
||||
3. 遇到新踩坑/新约束，**必须**在收尾时写入知识库（见 ai_collaboration.md §4）
|
||||
4. 改动涉及部署/定时任务/数据模型时，**必须**同步更新对应实体
|
||||
|
||||
### 禁止
|
||||
1. 禁止跳过检索直接改业务代码（豁免项除外）
|
||||
2. 禁止把同一事实**复制**到多个文件（只写一处 + 其余引用）
|
||||
3. 禁止忽略知识库中已记录的 `Issue` 实体而重复踩同一坑
|
||||
4. 禁止在未跑门禁（`npx tsc --noEmit` + `npx vitest run`）的情况下声称完成
|
||||
|
||||
## §5 版本历史
|
||||
|
||||
| 日期 | 版本 | 变更 |
|
||||
|------|------|------|
|
||||
| 2026-10-01 | v1.0 | 初始版本：§0 启动加载顺序 + §1 豁免 + §2 强制检索 + §4 行为约束 |
|
||||
@@ -0,0 +1,110 @@
|
||||
# AI 协作流程规范
|
||||
|
||||
> 版本: v1.0 | 更新: 2026-10-01
|
||||
> 相关: [README.md](README.md) · [ai_agent_rules.md](ai_agent_rules.md) · `../ai_coding_knowledge.json`
|
||||
|
||||
定义 AI 在本项目中的**协作流程**：怎么规划、怎么验证、怎么收尾、怎么沉淀。目标 —— 产出可验证、经验可复利。
|
||||
|
||||
---
|
||||
|
||||
## §0 三条不可协商的原则
|
||||
|
||||
1. **不一次性生成大量代码** —— 任务必须可拆解（`anti_pattern:one-shot-big`）
|
||||
2. **没有验收标准不开工** —— 否则无法判断何时完成（`method:acceptance-criteria`）
|
||||
3. **不审查 diff 不算完成** —— AI 的自我描述可信度低于实际改动（`method:review-diff`）
|
||||
|
||||
## §1 主工作流：Explore → Plan → Implement → Verify
|
||||
|
||||
| 阶段 | 做什么 | 产出 |
|
||||
|------|--------|------|
|
||||
| **Explore** | 读相关源码 / 规格 / 知识图谱实体，确认现状与约束 | 现状结论 + 涉及文件清单 |
|
||||
| **Plan** | 输出结构化步骤（步骤 + 依赖 + 验收标准）；复杂任务**先给计划再动手** | 计划（TodoWrite 跟踪） |
|
||||
| **Implement** | 按计划分步实现，**一步一验证**，不攒到最后一起验 | 可增量验证的改动 |
|
||||
| **Verify** | 跑门禁；失败回到 Implement | 门禁通过证据 |
|
||||
|
||||
> 复杂任务（跨 3 个以上模块 / 涉及数据模型 / 涉及部署）**必须先出计划并等确认**。
|
||||
|
||||
## §2 任务拆解铁律
|
||||
|
||||
- **窄范围 > 大而模糊**：`修 /api/tools 分页 total 字段` 优于 `改进工具模块`
|
||||
- 每步定义**输入**（依赖文件/数据）与**输出**（验收标准）
|
||||
- 状态机驱动：`Pending → Running → Blocked → Done / Failed`
|
||||
- 单任务改动建议 ≤15 个文件；超出则重新拆解
|
||||
|
||||
## §3 验收标准（每个任务开工前必须明确）
|
||||
|
||||
| 任务类型 | 验收标准 |
|
||||
|---------|---------|
|
||||
| 功能开发 | `npx tsc --noEmit` 零错误 + `npx vitest run` 全绿 + 新功能可用 + 无回归 |
|
||||
| Bug 修复 | 复现路径通过 + 相关测试通过 |
|
||||
| 重构 | 行为不变 + 测试全绿 + 无性能回归 |
|
||||
| 数据/脚本 | 输出格式正确 + 样例验证通过 + 幂等可重跑 |
|
||||
| 部署/运维 | 部署后自检清单全通过（见 project_rules.md §15.3） |
|
||||
|
||||
本项目**双门禁**：`npx tsc --noEmit` + `npx vitest run`（缺一不可）。
|
||||
|
||||
## §4 代码审查：看 diff 不看对话
|
||||
|
||||
- 用 `git diff` 逐行审查**实际改动**
|
||||
- 对照 `§3 验收标准` 核验，而不是对照 AI 的说法
|
||||
- 重点排查：臆造的 API/字段、被静默删除的逻辑、异常处理缺失、硬编码密钥
|
||||
|
||||
## §5 失败分型（先分型，再优化）
|
||||
|
||||
| 失败类型 | 表现 | 优化方向 |
|
||||
|---------|------|---------|
|
||||
| 规划失败 | 任务拆解不合理、范围失控 | 重新拆解任务 |
|
||||
| 执行失败 | 命令/环境/依赖报错 | 修工具、环境、依赖 |
|
||||
| 质量失败 | 结果不满足验收标准 | 收紧验收标准或加门禁 |
|
||||
|
||||
> 禁止把所有失败都归因为「模型不够强」（`anti_pattern:model-is-everything`）。
|
||||
|
||||
## §6 完成流程：自动记录（关键，不可跳过）
|
||||
|
||||
开发完成并通过门禁后，**必须**运行：
|
||||
|
||||
```bash
|
||||
npm run knowledge:update
|
||||
# 等价于：node scripts/update-knowledge.mjs（可加 --dry-run 预览，不写文件）
|
||||
```
|
||||
|
||||
脚本自动捕获三类信息并沉淀：
|
||||
|
||||
| 捕获内容 | 来源 | 落盘位置 |
|
||||
|---------|------|---------|
|
||||
| **能力特征** | 扫描 `src/app/api/**/route.ts`、`src/app/**/page.tsx`、`src/components/**`、`prisma/schema.prisma`、`scripts/**`、`crontab.txt`、`package.json`、`data/bot-characters.json` | `.trae/knowledge/capabilities.json` |
|
||||
| **开发过程** | `git log`（最近提交：hash/时间/主题/改动文件数） | `.trae/knowledge/dev_process.jsonl`（按提交追加） |
|
||||
| **模型成果** | 本次交付物：新增迁移、新增/变更脚本、提交统计 | `.trae/knowledge/artifacts.jsonl`（追加） |
|
||||
|
||||
并**增量 upsert**（按实体名，同名替换 observations，未出现的旧实体原样保留，永不删除）：
|
||||
|
||||
- `.trae/knowledge_graph.json`（渲染版，人类可读 + 权威）
|
||||
- `.trae/knowledge_graph.jsonl`（MCP Knowledge Graph Memory 读取的源文件）
|
||||
|
||||
**自动化触发**：本机已装 `git post-commit` 钩子（`.git/hooks/post-commit`），每次提交后自动执行同一脚本（静默 + 后台，不阻断、不拖慢提交），无需手动记得。
|
||||
|
||||
> **换机 / 新克隆后重装钩子**（`.git/hooks/` 不随 git 传递）——在仓库根执行：
|
||||
> ```bash
|
||||
> printf '#!/bin/sh\nROOT=$(git rev-parse --show-toplevel) || exit 0\n[ -f "$ROOT/scripts/update-knowledge.mjs" ] || exit 0\ncommand -v node >/dev/null 2>&1 || exit 0\n( cd "$ROOT" && node scripts/update-knowledge.mjs --quiet >/dev/null 2>&1 & )\nexit 0\n' > .git/hooks/post-commit
|
||||
> ```
|
||||
> 卸载：删除 `.git/hooks/post-commit` 即可（脚本本身仍可手动运行）。
|
||||
|
||||
> 未运行记录脚本就结束任务，视为**流程未完成**。
|
||||
|
||||
## §7 反模式（禁止）
|
||||
|
||||
| 反模式 | 替代做法 |
|
||||
|--------|---------|
|
||||
| 一次性生成大量代码 | 任务拆解（§2） |
|
||||
| 无验收标准 | 先定义验收标准（§3） |
|
||||
| 不审查 AI 代码 | 看 diff + 双门禁（§4） |
|
||||
| 一次性灌入冗余上下文 | 上下文预算，按需加载 |
|
||||
| 把「模型更强」当「系统更稳」 | 模型 + 编排 + 门禁三层闭环 |
|
||||
| 同一知识多份副本 | 单一事实源 + 引用 |
|
||||
| 知识库只写不更新 | §6 自动记录 + 定期一致性巡检 |
|
||||
|
||||
## §8 版本历史
|
||||
|
||||
| 日期 | 版本 | 变更 |
|
||||
|------|------|------|
|
||||
| 2026-10-01 | v1.0 | 初始版本：Plan-first 四阶段 + 验收标准 + 完成自动记录（§6） |
|
||||
+134
-26
@@ -1,5 +1,10 @@
|
||||
# 追光AI 项目开发规则
|
||||
|
||||
> **本文件是 L2 工程标准层**（四层结构索引见 [README.md](README.md)）。其他层：
|
||||
> - L0 方法论：[../ai_coding_knowledge.json](../ai_coding_knowledge.json)（AI 编程效率方法库，机器可解析）
|
||||
> - L1 协作规则：[ai_agent_rules.md](ai_agent_rules.md)（启动加载）· [ai_collaboration.md](ai_collaboration.md)（Plan-first + 自动记录）
|
||||
> - L3 项目事实：[../knowledge_graph.jsonl](../knowledge_graph.jsonl)（知识图谱）· [../knowledge/](../knowledge/)（能力/过程/成果自动记录）
|
||||
|
||||
## 端口规范
|
||||
- 应用端口范围: **8301-8310**（预留扩展）
|
||||
- 默认端口: **8301**
|
||||
@@ -9,9 +14,9 @@
|
||||
## 服务器连接信息（重要！总是需要）
|
||||
- **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/`
|
||||
- **SSH密钥**: `C:\SSH\zhuiguang-ai\zg.pem`（2026-10-02 校正；旧值 `E:\0.Center-S2\S890-V3\pem\zg.pem` 已迁移）
|
||||
- **SSH命令**: `ssh -i "C:\SSH\zhuiguang-ai\zg.pem" ubuntu@119.45.242.239`
|
||||
- **SCP示例**: `scp -i "C:\SSH\zhuiguang-ai\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
|
||||
|
||||
## 服务器与基础设施
|
||||
- **域名**: www.zhuig.com (HTTPS，SSL证书自动续期)
|
||||
@@ -19,8 +24,10 @@
|
||||
- **访问地址**: 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
|
||||
- **工作区/开发目录**: `E:\KF_7\ZhuiGuangAI\zhuiguang-ai`（master，当前唯一活跃工作副本）
|
||||
- **本地裸仓镜像（备份入口）**: `K:\git-repos\zhuiguang-ai.git`（bare，2026-10-01 新建。源仓库 remote 需指向它才能持续备份）
|
||||
- **已停用副本**: `E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai`（停在 2026-05-23，无 remote）与 `K:\git-repos\zhuiguang-ai`（非裸仓旧工作副本，同样停在 2026-05-23）
|
||||
- **远端现状**: 源仓库 remote `local` 仍指向已不存在的 `c:\gitbf\zhuiguang-ai.git`；云端 Gitea（119.45.242.239:3000）无本项目仓库
|
||||
- **Docker管理**: `docker ps` / `docker logs zhuiguang-ai-app` / `docker restart zhuiguang-ai-app`
|
||||
|
||||
### ⚠️ 多项目共存服务器（更新/部署铁律）
|
||||
@@ -142,9 +149,87 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
|
||||
|
||||
## 构建与检查
|
||||
- 修改代码后必须运行 `npx tsc --noEmit` 确认零错误
|
||||
- 修改代码后必须运行 `npx vitest run` 确认所有测试通过
|
||||
- 本地开发服务器: `npm run dev` (端口8301)
|
||||
- 生产构建: `docker build -t zhuiguang-ai:latest .`
|
||||
- 部署: `docker stop/rm` 旧容器 → `docker run` 新容器
|
||||
- **打包分析**: `ANALYZE=true npm run build` 启用 `@next/bundle-analyzer` 分析包体积
|
||||
|
||||
## 测试规范
|
||||
- 测试框架: Vitest
|
||||
- 配置文件: `vitest.config.ts` + `vitest.setup.ts`
|
||||
- 测试目录: `src/__tests__/`，文件名匹配 `*.test.ts`
|
||||
- 覆盖率目标: **80%+**（行/分支/函数/语句）
|
||||
- tsconfig 需包含 `"types": ["vitest/globals"]` 以启用全局 test/expect/describe
|
||||
- 测试类别:
|
||||
- 工具函数单元测试（lib 目录下的纯函数）
|
||||
- API 路由集成测试
|
||||
- 组件渲染测试（配合 @testing-library/react）
|
||||
- 禁止跳过测试（`.skip`）除非有明确的 TODO 注释说明原因
|
||||
|
||||
## 图片优化规范
|
||||
- **强制使用 LazyImage 组件** (`src/components/ui/LazyImage.tsx`)，禁止使用原生 `<img>` 标签
|
||||
- LazyImage 特性:
|
||||
- 基于 next/image 的懒加载包装器
|
||||
- 内置骨架屏加载状态（Skeleton loading state）
|
||||
- 错误回退占位图（Error fallback）
|
||||
- 支持 `referrerPolicy` 属性（用于跨域图片场景）
|
||||
- 支持 `width`/`height` 或 `fill` 模式
|
||||
- 用法示例:
|
||||
```tsx
|
||||
import LazyImage from "@/components/ui/LazyImage";
|
||||
// 固定尺寸
|
||||
<LazyImage src={url} alt="描述" width={32} height={32} />
|
||||
// 响应式
|
||||
<LazyImage src={url} alt="描述" fill className="object-cover" />
|
||||
// 跨域图片
|
||||
<LazyImage src={url} alt="描述" width={48} height={48} referrerPolicy="no-referrer" />
|
||||
```
|
||||
- 必须提供有意义的 `alt` 文本
|
||||
- 装饰性图片使用 `alt=""` 配合 `role="presentation"`
|
||||
|
||||
## 导航规范（Link vs router.push）
|
||||
- 所有静态页面内导航必须使用 Next.js `<Link>` 组件
|
||||
- 禁止使用 `<button onClick={() => router.push(...)}>` 进行页面跳转
|
||||
- 适用场景:
|
||||
- 分页按钮 → `<Link>`
|
||||
- 侧边栏筛选 → `<Link>`（含查询参数）
|
||||
- 面包屑 → `<Link>`
|
||||
- 卡片/列表项 → `<Link>`
|
||||
- "清除筛选"按钮 → `<Link href="/base-path">`
|
||||
- 仅外部链接使用 `<a>`（需加 `target="_blank" rel="noopener noreferrer"`）
|
||||
|
||||
## API 响应格式规范
|
||||
- 列表接口统一使用 `total`（不是 `totalCount`）表示总数
|
||||
- 返回格式: `{ data, total, page, pageSize }` 或 `{ success, error }`
|
||||
- 前端消费端也同步使用 `total` 字段
|
||||
- 已统一接口: `/api/notifications`, `/api/forum/topics`, `/api/comments`, `/api/user/points`
|
||||
|
||||
## 并行查询规范
|
||||
- 多个独立的 Prisma 查询必须使用 `Promise.all` 并行执行
|
||||
- 严禁串行 await 多个无依赖的数据库查询
|
||||
```typescript
|
||||
// ✅ 正确：并行查询
|
||||
const [tool, relatedTools, reviewCount] = await Promise.all([
|
||||
prisma.tool.findUnique({ where: { slug } }),
|
||||
prisma.tool.findMany({ where: { categoryId }, take: 6 }),
|
||||
prisma.review.count({ where: { toolId } }),
|
||||
]);
|
||||
```
|
||||
|
||||
## 无障碍规范（WCAG 2.1）
|
||||
- 所有交互元素（div onClick）必须添加 `role` + `aria-*` 属性 + 键盘事件（`onKeyDown`）
|
||||
- 搜索输入框必须添加 `aria-label` 属性
|
||||
- 装饰性图片添加 `role="presentation"`（不暴露给屏幕阅读器）
|
||||
- 根布局必须提供跳过导航链接（Skip-link）
|
||||
- 主内容区域使用 `<main id="main-content" tabIndex={-1}>`
|
||||
|
||||
## TypeScript 类型规范
|
||||
- 禁止使用 `any` 类型
|
||||
- 泛型函数使用 `<T>` 约束（参考 `src/lib/cache.ts` 的 `cachedResponse<T>`）
|
||||
- API 回调函数使用明确的参数类型
|
||||
- 内联对象类型使用 interface 而非匿名类型字面量
|
||||
- `src/lib/admin-auth.ts`: 使用 Prisma 严格类型，id 字段统一为 `number`
|
||||
|
||||
## 数据库
|
||||
- 云数据库: 阿里云RDS MySQL
|
||||
@@ -236,16 +321,19 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
|
||||
- OPENAI_API_KEY: OpenAI API Key（Bot活动引擎使用，生成论坛内容）
|
||||
|
||||
## 数字人Bot系统
|
||||
- **角色定义文件**: `data/bot-characters.json` — 112个Bot角色定义，所有Bot脚本和前端工具依赖此文件
|
||||
- **Bot头像目录**: `public/bot-avatars/` — 程序化SVG头像（112个，~2.5KB/个）
|
||||
- **角色定义文件**: `data/bot-characters.json` — 当前 **6 个**「行业情报官」角色（cb_intel / fi_ins_intel / fi_stock_intel / brand_intel / ai_intel / ct_intel）；旧 112 角色「模拟真人互刷」体系已于 2026-09-05 退役
|
||||
- **Bot头像目录**: `public/bot-avatars/` — SVG 头像 178 个（含历史角色头像）
|
||||
- **会员头像库**: `public/avatars/` — SVG 头像 530 个，会员可在个人中心选择或自定义上传
|
||||
- **头像生成脚本**: `scripts/generate-avatar-library.mjs` — 批量生成头像库，支持按性别/主题/数量筛选
|
||||
- **头像上传目录**: `public/uploads/avatars/` — 用户自定义上传头像存储
|
||||
- **Bot用户标记**: User表中 `isBot: true` 标识Bot用户，与真人的互动数据分别统计
|
||||
- **Bot活动时段**: 9:00-23:00每小时运行，15轮/天，论坛内容不干扰深夜用户体验
|
||||
- **Bot活动时段**: 旧「模拟真人互刷」体系已停用（`bot-activity` 等任务在 `crontab.txt` 中已注释，2026-09-05 退役）；现由行业情报官引擎承担
|
||||
- **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个任务配置
|
||||
- **种子数据**: `scripts/seed-task-configs.mjs` 初始化 29 个任务配置（含已停用任务，与 `crontab.txt` 存在漂移，见下）
|
||||
- **手动触发**: `/admin/tasks` 页支持每个任务运行，也可通过 POST `/api/admin/tasks/run` 触发
|
||||
- **API**:
|
||||
- `GET/PUT /api/admin/tasks/configs` — 任务配置查询/更新
|
||||
@@ -253,25 +341,42 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
|
||||
- `POST /api/admin/tasks/run` — 手动触发任务执行
|
||||
|
||||
### 定时任务（Supercronic 容器调度）
|
||||
所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`。不再使用主机 crontab + cron-wrapper.sh。
|
||||
所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`（**唯一准绳**）。不再使用主机 crontab。
|
||||
|
||||
| 时间 | 任务 | 脚本 | 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资讯/技术探讨/观点讨论） |
|
||||
> ⚠️ supercronic 在容器内按 **UTC** 执行（TZ 环境变量不生效），下表时刻均为 UTC，括号外已换算为北京时间（UTC + 8h）。
|
||||
> ⚠️ 2026-10-01 巡检确认：`crontab.txt` 已注释停用大量 Bot/行业情报 AI 任务，但 `scripts/seed-task-configs.mjs` 仍写 `enabled: true`、`scripts/health-check.mjs` 仍把它们列入期望键 —— **三方漂移会产生误告警**，新增/停用任务时必须同步这三处。
|
||||
|
||||
**启用中（19 个）**
|
||||
|
||||
| UTC | 北京时间 | 任务 | 脚本 | TaskKey |
|
||||
|-----|---------|------|------|---------|
|
||||
| 0 1 | 09:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars |
|
||||
| 0 3 | 11:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools |
|
||||
| 0 4 | 12:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot |
|
||||
| 0 4 * * 0 | 周日 12:00 | 工具数据补全 | `scripts/enrich-tool-data.mjs` | enrich-tool-data |
|
||||
| 30 4 | 12:30 | 日志清理 | `scripts/cleanup-logs.mjs` | cleanup-logs |
|
||||
| 0 5 | 13:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills |
|
||||
| 0 6 | 14:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools |
|
||||
| 30 6 | 14:30 | task_log 清理 | `scripts/cleanup-task-logs.mjs` | cleanup-task-logs |
|
||||
| 30 7 | 15:30 | AI 日报 | `scripts/daily-news.mjs` | daily-news |
|
||||
| 0 8 | 16:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community |
|
||||
| 0 8 1 * * | 每月 1 日 16:00 | 断签保护卡发放 | `scripts/grant-freeze-cards.mjs` | grant-freeze-cards |
|
||||
| 30 8 | 16:30 | 任务健康检查 | `scripts/health-check.mjs` | health-check |
|
||||
| 0 9 | 17:00 | 通知摘要生成 | `scripts/notification-digest.mjs` | notification-digest |
|
||||
| 0 9 * * 1 | 周一 17:00 | 竞品工具数监测 | `scripts/competitor-monitor.mjs` | competitor-monitor |
|
||||
| 0 10 | 18:00 | 行业趋势监测 | `scripts/trend-alert.mjs` | trend-alert |
|
||||
| 0 10 * * 1 | 周一 18:00 | 周刊生成 | `scripts/newsletter-generate.mjs` | newsletter-generate |
|
||||
| 30 10 * * 1 | 周一 18:30 | 每周推荐邮件 | `scripts/weekly-recommend-email.mjs` | weekly-recommend-email |
|
||||
| 15 */6 | 每 6 小时 | 点赞计数对账 | `scripts/reconcile-like-counts.mjs` | reconcile-like-counts |
|
||||
| 5 23,3,7,11,15 | 每日 7/11/15/19/23 点 | 行业素材采集 | `scripts/industry-thinktank.mjs collect --all` | industry-thinktank |
|
||||
|
||||
**已注释停用**：`bot-activity`、`bot-skill-crystallize`、`bot-affinity-update`、`bot-weekly-review`、`bot-feedback-loop`、`bot-adversarial-learning-run`、`bot-persona-experiment-run`、`bot-roundtable`、`industry-thinktank weekly/respond`、`industry-daily daily/respond`
|
||||
（原因：2026-09-05 旧 Bot「模拟真人互刷」体系退役；2026-09-26 按要求关闭全部 AI 生成功能，行业情报改为需登录访问）
|
||||
|
||||
- 调度配置: `crontab.txt`（supercronic 格式），修改后需重建 cron 容器生效
|
||||
- 日志目录: 容器内 `/app/logs/`（挂载到 Docker volume `zhuiguang_ai_bot_logs`）
|
||||
- 日志目录: 容器内 `/app/logs/`；实际 Docker 卷名为 `zhuiguang-ai_bot-logs`（旧文档写 `zhuiguang_ai_bot_logs`，已过时）
|
||||
- 定时任务脚本从 `scripts/` 目录直接执行，环境变量由容器 entrypoint 注入
|
||||
- **新增任务必须同步四处**：`crontab.txt` + `scripts/<task>.mjs` + `scripts/seed-task-configs.mjs` + `scripts/health-check.mjs`
|
||||
|
||||
## AI日报新闻源
|
||||
- **36kr** RSS (https://36kr.com/feed) — 国内科技资讯
|
||||
@@ -300,6 +405,7 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
|
||||
- 敏感信息（密钥、密码、Token）必须使用环境变量，禁止硬编码
|
||||
- `.env` 文件已被加入 `.gitignore`，仅 `.env.example` 模板可提交
|
||||
- HTTP 响应必须包含安全头：CSP、HSTS、X-Content-Type-Options、X-Frame-Options
|
||||
- CSP 的 `script-src` 必须包含 `'unsafe-inline'`（Next.js App Router 水合依赖内联 `self.__next_f` 脚本），禁止 `'unsafe-eval'`；详见 workspace 规则 7.1
|
||||
- 文件上传/下载必须限制大小（最大 5MB）和类型，SVG 内容需消毒 script/iframe/on-event 标签
|
||||
- Logo 文件名使用 SHA256 哈希（不使用 MD5）
|
||||
- VIP 用户不能访问管理后台（/admin/* 和 /api/admin/*）
|
||||
@@ -318,8 +424,10 @@ docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
|
||||
- 修改项目架构/技术栈/部署配置 → 更新 `追光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` 查询图谱，利用已有知识加速开发
|
||||
- **图谱存储**：`.trae/knowledge_graph.jsonl`（MCP 源文件，JSONL，一行一实体/关系）；`.trae/knowledge_graph.json` 为渲染版（`project` / `version` / `updated_at` / `entities` / `relations`）
|
||||
- **MCP 配置**：`.trae/mcp.json` 注册 `Knowledge Graph Memory` 服务（`npx -y @itseasy21/mcp-knowledge-graph`，`MEMORY_FILE_PATH=.trae/knowledge_graph.jsonl`）
|
||||
- **同步方法**：优先使用 `create_entities` / `add_observations` / `update_entities` / `create_relations` / `delete_entities` 等工具；若 MCP 未挂载，直接维护 `.trae/knowledge_graph.jsonl`
|
||||
- **查询优先**：在开始任何开发任务前，先通过 `search_nodes` / `open_nodes` 查询图谱，利用已有知识加速开发
|
||||
|
||||
### 7. 可靠性原则
|
||||
- 所有外部 API 调用（GitHub、DeepSeek 等）必须设置超时和重试
|
||||
|
||||
+46
-19
@@ -22,28 +22,36 @@
|
||||
## 项目结构
|
||||
```
|
||||
zhuiguang-ai/
|
||||
├── data/ # 数据文件 (bot-characters.json)
|
||||
├── prisma/ # 数据库Schema + 迁移 + 种子
|
||||
├── public/ # 静态资源 (logo.png, logos/)
|
||||
├── scripts/ # 独立脚本 (7个定时任务 + 多个工具脚本)
|
||||
├── public/ # 静态资源 (logo.png, logos/, bot-avatars/, avatars/, uploads/avatars/)
|
||||
├── scripts/ # 独立脚本 (7个AI发现任务 + 7个Bot任务 + 多个工具脚本)
|
||||
│ └── lib/ # 脚本共享库 (bot-persona, bot-persona-experiment, bot-adversarial-learning, bot-avatar-generator)
|
||||
├── src/
|
||||
│ ├── __tests__/ # 测试文件 (vitest, 5个测试套件, 132个测试)
|
||||
│ ├── app/
|
||||
│ │ ├── (admin)/admin/ # 后台页面 (18个页面 + 任务调度3个子页)
|
||||
│ │ ├── api/ # API路由 (50+个端点)
|
||||
│ │ ├── (admin)/admin/ # 后台页面 (21个页面: 18个原有 + 3个Bot管理)
|
||||
│ │ ├── api/ # API路由 (60+个端点, 含bots/、notifications/、recommendations/、points shop等子路由)
|
||||
│ │ ├── categories/ # 前台分类页
|
||||
│ │ ├── community/ # 社区 (bots/列表+排行榜, tools/compare工具对比)
|
||||
│ │ ├── reviews/ # 前台评测列表+榜单
|
||||
│ │ ├── skills/ # 前台技能页
|
||||
│ │ ├── tools/ # 前台工具页
|
||||
│ │ ├── tools/ # 前台工具页 + /tools/compare 对比页
|
||||
│ │ ├── login/ # 用户登录页
|
||||
│ │ ├── daily/ # AI日报页
|
||||
│ │ ├── user/ # 用户中心(个人资料/收藏/收藏夹)
|
||||
│ │ ├── globals.css # 全局样式
|
||||
│ │ ├── layout.tsx # 前台布局
|
||||
│ │ ├── user/ # 用户中心(个人资料/收藏/收藏夹/积分/商店)
|
||||
│ │ ├── globals.css # 全局样式 (含dark mode CSS变量)
|
||||
│ │ ├── layout.tsx # 前台布局 (含ThemeProvider + SkipLink)
|
||||
│ │ └── page.tsx # 首页
|
||||
│ ├── components/ # 组件 (Header, Footer, UI, Common)
|
||||
│ ├── lib/ # 工具库 (prisma, auth, admin-auth, github, deepseek, logo-fetcher, logo-storage, utils)
|
||||
│ ├── components/ # 组件 (Header, Footer, UI/LazyImage, UI/ThemeProvider, Common/Compare*, Common/PersonalizedRecommend, Common/HighlightText, forum/Bot*, forum/AvatarPicker, forum/NotificationCenter)
|
||||
│ ├── lib/ # 工具库 (prisma, auth, admin-auth, github, deepseek, logo-fetcher, logo-storage, bot-utils, avatar-library, utils, source-type, constants, streak-freeze, shop-items, level-config, points-reward, formatRelativeTime)
|
||||
│ └── middleware.ts # 路由保护
|
||||
├── vitest.config.ts # Vitest 测试配置
|
||||
├── vitest.setup.ts # Vitest 全局 setup
|
||||
├── Dockerfile # 多阶段构建
|
||||
├── docker-compose.yml # 容器编排
|
||||
├── crontab.txt # supercronic 调度表 (25条定时任务)
|
||||
├── .env # 环境变量
|
||||
├── restart.ps1 # 服务重启脚本(端口8301-8310)
|
||||
└── package.json # 依赖配置
|
||||
```
|
||||
|
||||
@@ -51,15 +59,23 @@ zhuiguang-ai/
|
||||
|
||||
| 序号 | 模块 | 文档 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 01 | 数据库 | [01-database.md](./modules/01-database.md) | 26张数据模型、8个枚举、完整索引、迁移历史 |
|
||||
| 01 | 数据库 | [01-database.md](./modules/01-database.md) | 38张数据模型、8个枚举、完整索引、迁移历史 |
|
||||
| 02 | API | [02-api.md](./modules/02-api.md) | 前台/后台/用户API端点、SystemConfig配置键 |
|
||||
| 03 | 页面 | [03-pages.md](./modules/03-pages.md) | 前台/后台页面路由、布局、功能说明 |
|
||||
| 04 | 组件与样式 | [04-components-and-styles.md](./modules/04-components-and-styles.md) | UI组件、样式系统、设计规范 |
|
||||
| 04 | 组件与样式 | [04-components-and-styles.md](./modules/04-components-and-styles.md) | UI组件、样式系统、设计规范（含暗色模式、LazyImage） |
|
||||
| 05 | AI发现 | [05-ai-discovery.md](./modules/05-ai-discovery.md) | 提示词驱动发现流程、Logo抓取引擎、定时任务、评测管线 |
|
||||
| 06 | 认证 | [06-auth.md](./modules/06-auth.md) | NextAuth配置、路由保护、权限体系、登录流程 |
|
||||
| 07 | 工具库与脚本 | [07-lib-and-scripts.md](./modules/07-lib-and-scripts.md) | 工具函数、定时任务脚本、运维脚本 |
|
||||
| 08 | 社区功能 | [08-community.md](./modules/08-community.md) | 评论系统、收藏、浏览历史、收藏夹、通知、论坛 |
|
||||
| 07 | 工具库与脚本 | [07-lib-and-scripts.md](./modules/07-lib-and-scripts.md) | 工具函数、定时任务脚本(含Bot脚本)、运维脚本 |
|
||||
| 08 | 社区功能 | [08-community.md](./modules/08-community.md) | 评论系统、收藏、浏览历史、收藏夹、通知、论坛、Bot社区、会员头像库 |
|
||||
| 09 | 运维与部署 | [09-devops.md](./modules/09-devops.md) | Docker容器、supercronic调度、Nginx、部署流程、备份 |
|
||||
| 10 | 数字人Bot系统 | [10-bot-system.md](./modules/10-bot-system.md) | 112个Bot角色、活动引擎、A/B测试、对抗学习、技能结晶、亲和度、头像系统 |
|
||||
| 11 | 积分体系 | [points.md](./modules/points.md) | 积分规则、等级系统、积分商店、Streak冻结、签到系统 |
|
||||
| 12 | 通知系统 | [notifications.md](./modules/notifications.md) | 智能摘要、通知偏好、通知中心、通知类型 |
|
||||
| 13 | 暗色模式 | [theme.md](./modules/theme.md) | ThemeProvider、CSS变量、组件适配、用户偏好持久化 |
|
||||
| 14 | 工具功能增强 | [tools.md](./modules/tools.md) | 工具对比、工具认证徽章、工具推荐 |
|
||||
| 15 | 搜索增强 | [search.md](./modules/search.md) | 自动补全、搜索历史、键盘导航、高亮文本 |
|
||||
| 16 | 测试体系 | [testing.md](./modules/testing.md) | Vitest配置、5个测试套件、覆盖率标准 |
|
||||
| 17 | 开发规则 | [17-rules.md](./modules/17-rules.md) | 项目开发规则体系（22章：代码质量/数据策略/导航/图片/无障碍/SEO/性能/安全/定时任务/测试/Shell/Docker/部署/数据模型/API设计/Bot系统/环境变量/依赖管理/审查清单） |
|
||||
|
||||
## 环境变量
|
||||
```
|
||||
@@ -68,6 +84,7 @@ NEXTAUTH_URL=http://localhost:8301
|
||||
NEXTAUTH_SECRET=<secret>
|
||||
GITHUB_TOKEN=<optional>
|
||||
DEEPSEEK_API_KEY=<required-for-review>
|
||||
OPENAI_API_KEY=<required-for-bot-activity>
|
||||
```
|
||||
|
||||
## 核心业务流程
|
||||
@@ -88,13 +105,23 @@ DEEPSEEK_API_KEY=<required-for-review>
|
||||
- **GitHub Star同步**: 通过GitHub API定期更新技能Star数，维护90天历史
|
||||
- **五维评测系统**: GitHub数据采集 + DeepSeek AI评测 + 雷达图展示，5维度(capability/devExp/costLicense/community/performance)评分
|
||||
- **评测榜单**: 前台/reviews页面展示评测分榜TOP10 + Stars涨幅榜TOP10侧边栏
|
||||
- **任务调度系统**: 7个定时任务(Task1-6+Task7新闻推社区)+AI日报，统一TaskConfig配置+TaskLog执行历史+后台可视化管理+手动触发，通过cron-wrapper.sh统一入口执行
|
||||
- **任务调度系统**: 25个定时任务(AI发现7个+Bot系统+运维)，统一TaskConfig配置+TaskLog执行历史+后台可视化管理+手动触发，通过supercronic容器调度
|
||||
- **数字人Bot社区引擎**: 112个AI驱动的虚拟用户，分专家/观察者两种角色，自动发帖/回复/点赞，含A/B测试、对抗学习、技能结晶、亲和度计算、周度复盘完整闭环
|
||||
- **权限体系**: 53个精细化权限点，角色管理，细粒度权限控制
|
||||
- **社区互动**: 评论/回复、收藏、浏览历史、收藏夹、通知系统、论坛板块
|
||||
- **社区互动**: 评论/回复、收藏、浏览历史、收藏夹、通知系统、论坛板块、Bot排行榜
|
||||
- **分页**: 所有列表页面支持分页（每页20条）
|
||||
- **浅色主题**: 科技感浅色设计系统，毛玻璃效果+渐变文字+精致阴影
|
||||
- **双主题**: 浅色/暗色双模式，ThemeProvider + CSS变量驱动，用户偏好localStorage持久化
|
||||
- **层级分类**: 一级分类+二级分类，左侧导航+标签切换
|
||||
- **用户系统**: 邮箱注册/登录、GitHub OAuth、收藏功能、浏览历史
|
||||
- **用户系统**: 邮箱注册/登录、GitHub OAuth、收藏功能、浏览历史、**会员头像库（500个预置头像+自定义上传）**
|
||||
- **积分体系**: 20级成长系统、积分商店、签到连击、Streak冻结保护
|
||||
- **智能通知**: 通知摘要合并、通知偏好设置、通知中心页面
|
||||
- **内容推荐**: 个性化推荐引擎、相关话题推荐、工具相似度计算
|
||||
- **工具对比**: 多工具并排对比、10维度评分表、Context共享状态
|
||||
- **工具认证**: 管理员认证徽章、蓝V标识
|
||||
- **搜索增强**: 自动补全API、搜索历史localStorage、键盘导航（上下/回车/ESC）
|
||||
- **安全加固**: 后台25个写操作API全部添加requireAdmin中间件验证；批量操作ids数组需校验非空且有数量上限(100~500)；FK字段回退值禁止硬编码
|
||||
- **容器化部署**: Docker多阶段构建 + supercronic调度 + 4个命名卷，完全替代PM2+主机crontab
|
||||
- **测试覆盖**: Vitest + 5个测试套件 + 132个测试 + 80%+覆盖率目标
|
||||
- **端口锁定**: 8301-8310区间，禁止使用其他端口
|
||||
- **频率限制**: 登录尝试限制、IP请求限制
|
||||
- **开发规则体系**: 22章项目开发规则（代码质量/安全/性能/无障碍/SEO/测试/部署/Docker/Shell/API设计/数据模型/Bot系统/环境变量），🔴🟡🟢三级严重度，覆盖全生命周期
|
||||
|
||||
@@ -705,6 +705,15 @@
|
||||
| ForumPost | [topicId, createdAt] | 联合索引 |
|
||||
| Permission | [groupName, sortOrder] | 联合索引 |
|
||||
| User | [oauthProvider, oauthId] | 联合唯一 |
|
||||
| BotConfig | [userId] | 唯一索引 |
|
||||
| BotDailyStat | [botId, date] | 唯一索引 |
|
||||
| BotWeeklyReview | [botId, weekKey] | 唯一索引 |
|
||||
| BotPersona | [botId] | 主键索引 |
|
||||
| BotPersonaVariant | [botId, variantKey] | 唯一索引 |
|
||||
| BotPersonaAssignment | [refType, refId] | 唯一索引 |
|
||||
| BotPersonaMetric | [variantId, date] | 唯一索引 |
|
||||
| BotAdversarialLearning | [botId, weekKey] | 唯一索引 |
|
||||
| BotCrossForumAffinity | [botId, forumSlug] | 唯一索引 |
|
||||
|
||||
## 迁移历史
|
||||
|
||||
@@ -721,3 +730,13 @@
|
||||
| 9 | add_hot_score | 2026-05-08 | 添加热度评分(DailyReportItem.hotScore) |
|
||||
| 10 | add_skill_reviews | 2026-05-20 | 添加技能评测表+Skill扩展字段 |
|
||||
| 11 | add_task_system | 2026-05-24 | 添加任务调度系统+权限体系+社区功能 |
|
||||
| 12 | add_bot_system | 2026-06-07 | 添加数字人Bot系统(12张表: BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity) |
|
||||
|
||||
---
|
||||
|
||||
## 开发规则引用
|
||||
> 数据模型变更必须遵守 [开发规则第十六章 - 数据模型与迁移规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：
|
||||
> - Prisma 命名约定：模型PascalCase→`@@map("snake_case")`，字段camelCase→`@map("snake_case")`
|
||||
> - 连接单例模式：`globalForPrisma` 防止热重载多实例
|
||||
> - Schema 变更流程：migrate dev → migrate status → migrate deploy（严禁DROP/TRUNCATE）
|
||||
> - 数据库隔离：仅操作 `zhuiguang_ai` 库
|
||||
|
||||
@@ -195,6 +195,18 @@ NextAuth认证端点（登录/回调/CSRF等）。
|
||||
| /api/admin/permissions | GET | 获取全部权限点列表 |
|
||||
| /api/admin/user-permissions | GET | 获取当前用户权限（roleId/userId/当前用户） |
|
||||
|
||||
### Bot管理API
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/admin/bots/stats | GET | Bot表现统计（每日指标+汇总，支持?days和?botUserId） |
|
||||
| /api/admin/bots/experiments | GET | A/B实验看板数据（变体/实验/每日指标聚合） |
|
||||
| /api/admin/bots/experiments/run | POST | 手动触发A/B实验（body: {mode, lookback, noSwitch}） |
|
||||
| /api/admin/bots/experiments/variants | PATCH | 更新变体（权重/启用/重置样本） |
|
||||
| /api/admin/bots/experiments/variants | DELETE | 删除变体 |
|
||||
| /api/admin/bots/adversarial-learning | GET | 对抗学习看板（支持?weeks和?botUserId） |
|
||||
| /api/admin/bots/adversarial-learning/run | POST | 手动触发对抗学习（body: {weekKey, force, lookback, bot}） |
|
||||
|
||||
### 日报管理
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
@@ -223,3 +235,14 @@ NextAuth认证端点（登录/回调/CSRF等）。
|
||||
| discoveryPromptConfig | JSON | AI发现提示词配置（含toolPrompt/skillPrompt/newsPrompt/tagPool等） |
|
||||
| logoFetchConfig | JSON | Logo抓取策略配置 |
|
||||
| discoverSkillsScript | string | 技能探索脚本源码 |
|
||||
|
||||
---
|
||||
|
||||
## 开发规则引用
|
||||
> API 开发必须遵守 [开发规则第十七章 - API设计规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：
|
||||
> - 路由骨架：`export const dynamic = "force-dynamic"` + `Promise.all` 并行 + `Cache-Control` 头
|
||||
> - 错误处理：使用 [api-error.ts](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/src/lib/api-error.ts) 的 `badRequest`/`notFound`/`serverError`
|
||||
> - 响应格式：列表 `{ data, total, page, pageSize }`，统一使用 `total`
|
||||
> - 状态码：200/201/400/401/403/404/409/500
|
||||
> - 认证分层：middleware + `requireAdmin()` + `getServerSession()`
|
||||
> - 分页上限：`Math.min(pageSize, 100)`
|
||||
|
||||
@@ -11,12 +11,18 @@
|
||||
### /tools (工具列表)
|
||||
- 文件: `src/app/tools/page.tsx`
|
||||
- 组件: ToolsContent
|
||||
- 功能: 分类筛选侧边栏（一级分类）、定价模型筛选、搜索、分页、卡片网格展示
|
||||
- 功能: 分类筛选侧边栏（一级分类）、定价模型筛选、搜索、分页、卡片网格展示、**工具对比功能（CompareButton）** 🆕
|
||||
- 数据源: `/api/categories`, `/api/tools`
|
||||
|
||||
### /tools/compare (工具对比) 🆕
|
||||
- 文件: `src/app/tools/compare/page.tsx`
|
||||
- 组件: ComparePage（CompareProvider + CompareBar）
|
||||
- 功能: 最多4个工具并排对比，10维度对比表格（名称/分类/定价/特性/标签/评分/评论数/浏览数/官网）
|
||||
- 数据源: `/api/tools` (通过Context传递)
|
||||
|
||||
### /tools/[slug] (工具详情)
|
||||
- 文件: `src/app/tools/[slug]/page.tsx`
|
||||
- 功能: 工具完整信息展示、浏览计数+1、收藏按钮、评论评价(ReviewSection)
|
||||
- 功能: 工具完整信息展示、浏览计数+1、收藏按钮、评论评价(ReviewSection)、**认证蓝V徽章** 🆕、**相关推荐** 🆕
|
||||
- 数据源: `/api/tools/[slug]`
|
||||
|
||||
### /categories/[slug] (分类详情)
|
||||
@@ -57,7 +63,7 @@
|
||||
|
||||
### /user (用户中心)
|
||||
- 文件: `src/app/user/page.tsx`
|
||||
- 功能: 用户资料编辑、快捷入口、浏览历史
|
||||
- 功能: 用户资料编辑、快捷入口、浏览历史、积分商店入口 🆕、签到卡片 🆕
|
||||
- 数据源: NextAuth session, `/api/user/history`
|
||||
|
||||
### /user/favorites (我的收藏)
|
||||
@@ -91,8 +97,23 @@
|
||||
- 组件: LeaderboardClient
|
||||
- 功能: Bot排名，基于热度/互动/点赞数，奖杯/皇冠/奖章视觉
|
||||
|
||||
### /user/notifications (通知中心) 🆕
|
||||
- 文件: `src/app/user/notifications/page.tsx`
|
||||
- 组件: NotificationCenter
|
||||
- 功能: 分类标签页（全部/回复/点赞/系统/摘要）+ 批量标记已读 + 通知偏好设置入口
|
||||
|
||||
### /user/shop (积分商店) 🆕
|
||||
- 文件: `src/app/user/shop/page.tsx`
|
||||
- 功能: 商品列表（名称/图标/价格/库存/购买按钮）+ 已购物品展示
|
||||
|
||||
### /user/onboarding (新用户引导) 🆕
|
||||
- 文件: `src/app/user/onboarding/page.tsx`
|
||||
- 组件: NewcomerOnboard
|
||||
- 功能: 5步新用户引导向导、进度追踪、Confetti 完成动画
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 后台页面
|
||||
|
||||
### /admin/login (登录)
|
||||
@@ -195,6 +216,24 @@
|
||||
- 功能: 左侧角色列表 + 右侧按分组的权限勾选网格、新建/删除自定义角色（系统角色受保护）、分组全选/取消全选、保存按钮实时同步到数据库
|
||||
- 数据源: `/api/admin/roles`, `/api/admin/permissions`, `/api/admin/user-permissions`
|
||||
|
||||
### /admin/bot-experiments (Bot A/B 看板)
|
||||
- 文件: `src/app/(admin)/admin/bot-experiments/page.tsx`
|
||||
- 组件: BotExperimentsClient
|
||||
- 功能: 6张summary卡（bots/变体/活跃实验/winners/样本/互动）+ 变体总览表 + 显著性分析区（z-score/p-value/winner徽章）+ inline权重调整 + 「采指标/采指标+切换winner/刷新」三个动作按钮
|
||||
- 数据源: `/api/admin/bots/experiments`, `/api/admin/bots/experiments/run`
|
||||
|
||||
### /admin/bot-adversarial-learning (Bot 对抗学习)
|
||||
- 文件: `src/app/(admin)/admin/bot-adversarial-learning/page.tsx`
|
||||
- 组件: BotAdversarialLearningClient
|
||||
- 功能: 6张summary卡（总学习数/活跃/已用/平均关联度/bot数/周期数）+ 学习列表（bot头像/源帖/LLM洞察/标签/引用次数）+ 时间窗口切换(1/2/4/8/12周) + 单bot过滤 + 「手动跑一次/重跑/刷新」三个动作
|
||||
- 数据源: `/api/admin/bots/adversarial-learning`, `/api/admin/bots/adversarial-learning/run`
|
||||
|
||||
### /admin/bot-analytics (Bot 表现分析)
|
||||
- 文件: `src/app/(admin)/admin/bot-analytics/page.tsx`
|
||||
- 组件: BotAnalyticsClient
|
||||
- 功能: 每个Bot的每日指标图表（话题数/回复数/点赞数/互动率/趋势）+ 汇总统计 + 时间窗口切换 + 单Bot筛选
|
||||
- 数据源: `/api/admin/bots/stats`
|
||||
|
||||
---
|
||||
|
||||
## 布局
|
||||
@@ -211,6 +250,7 @@
|
||||
- 技能库: 待审核技能、已发布技能、技能分类
|
||||
- 评测管理: 评测管理
|
||||
- AI发现: 探索AI工具、检测AI工具、探索Skill技能、更新Skill技能、AI新闻发现
|
||||
- 内容管理: Bot A/B 看板、Bot 对抗学习、Bot 表现分析
|
||||
- 系统配置: 系统配置
|
||||
- 任务调度: 任务中心、任务日志
|
||||
- 角色权限: 角色权限管理
|
||||
|
||||
@@ -22,6 +22,17 @@
|
||||
- NextAuth SessionProvider 包裹组件
|
||||
- 用于在客户端组件中访问session
|
||||
|
||||
#### ThemeProvider (`src/components/ThemeProvider.tsx`) 🆕
|
||||
- 暗色/浅色双主题 Provider
|
||||
- 提供 `theme` state、`toggleTheme()`、`setTheme(mode)` 方法
|
||||
- 监听 `prefers-color-scheme` 媒体查询
|
||||
- 持久化到 `localStorage("zhuiguang-theme")`
|
||||
|
||||
#### CompareProvider (`src/components/common/CompareProvider.tsx`) 🆕
|
||||
- 工具对比 Context Provider
|
||||
- 管理 `compareList` (最多4个工具)
|
||||
- 提供 `addToCompare`、`removeFromCompare`、`clearCompare`、`isInCompare` 方法
|
||||
|
||||
### 公共组件
|
||||
|
||||
#### HeroBanner (`src/components/common/HeroBanner.tsx`) 🔄
|
||||
|
||||
@@ -207,12 +207,102 @@
|
||||
- `scripts/install-cron-backup.sh` — 安装主机备份 cron（每天 03:00 执行备份）
|
||||
|
||||
### 定时任务调度
|
||||
- `crontab.txt` — supercronic 调度配置（13 条定时任务），不再使用主机 crontab + cron-wrapper.sh
|
||||
- `crontab.txt` — supercronic 调度配置（25 条定时任务），不再使用主机 crontab + cron-wrapper.sh
|
||||
|
||||
### lib/retry.mjs
|
||||
- 重试工具函数
|
||||
|
||||
---
|
||||
|
||||
## Bot系统脚本
|
||||
|
||||
### bot-activity.mjs — Bot活动引擎
|
||||
- 每小时运行（9:00-23:00），15轮/天
|
||||
- 遍历10个论坛板块，为每个板块选取适配Bot发帖+回复
|
||||
- 集成Persona画像注入、A/B变体选择、对抗学习上下文
|
||||
- 生成后自动点赞 + 写入BotDailyStat
|
||||
|
||||
### bot-skill-crystallize.mjs — Bot技能结晶
|
||||
- 每天02:00运行
|
||||
- 扫描过去14天高互动Bot话题，DeepSeek解构共性→入库BotSkill
|
||||
- 7天后回收检查成熟技能成功率，<30%且使用≥3次自动禁用
|
||||
|
||||
### bot-affinity-update.mjs — Bot亲和度与画像
|
||||
- 每周日22:30运行
|
||||
- 计算BotCrossForumAffinity + 刷新BotPersona画像
|
||||
|
||||
### bot-feedback-loop.mjs — Bot反馈闭环
|
||||
- 每周日22:00运行（原21:30）
|
||||
- 三层记忆模型(SESSION/WORKING/LONGTERM)
|
||||
- 扫描Bot自己帖子下的新回复 → 存反馈记忆 → 按概率触发二次回复
|
||||
|
||||
### bot-weekly-review.mjs — Bot周度复盘
|
||||
- 每周日02:00运行
|
||||
- 聚合一周指标 → 计算engagementScore → LLM生成反思 → 决定下周配额
|
||||
|
||||
### bot-persona-experiment-run.mjs — A/B实验调度
|
||||
- 每小时运行
|
||||
- 采集BotPersonaAssignment指标 → 按日聚合到BotPersonaMetric → 显著性检验 → 自动切换winner
|
||||
- 支持 `--lookback` / `--no-switch` / `--metrics-only` / `--analyze-only`
|
||||
|
||||
### bot-adversarial-learning-run.mjs — 对抗学习调度
|
||||
- 每周日23:00运行
|
||||
- 为每个expert bot选1篇真人高互动帖 → DeepSeek提取洞察 → 入库BotAdversarialLearning
|
||||
- 支持 `--week` / `--force` / `--bot` / `--lookback`
|
||||
|
||||
### bot-avatar-generate.mjs — Bot头像生成
|
||||
- CLI入口，为112个bot批量预生成头像
|
||||
- Lunaris text-to-image → 占位检测 → SVG兜底 → 落盘public/bot-avatars/
|
||||
- 支持 `--bot` / `--force` / `--use-lunaris-only` / `--no-update-db` / `--dry-run`
|
||||
|
||||
### 其他Bot脚本
|
||||
- `generate-bot-content.mjs` — 独立Bot内容生成（手动/临时运行）
|
||||
- `seed-bot-forum.mjs` — 论坛板块+Bot初始内容种子
|
||||
- `backfill-bot-daily-stats.mjs` — BotDailyStat历史数据回填
|
||||
- `test-bot-stats.mjs` — Bot统计测试调试工具
|
||||
|
||||
### Bot共享库 (`scripts/lib/`)
|
||||
|
||||
#### bot-persona.mjs — 人设画像
|
||||
- `updatePersona(botConfigId)` — 异步刷新画像（30天聚合）
|
||||
- `computePersona(botConfigId)` — 计算风格指标
|
||||
- `schedulePersonaRefresh()` — 定时触发
|
||||
|
||||
#### bot-persona-experiment.mjs — A/B实验管理
|
||||
- `ensureBotVariants(botConfigId)` — 初始化control+variant_a+variant_b
|
||||
- `pickVariantForPrompt(botConfigId)` / `commitAssignment()` — 分流+记录
|
||||
- `buildVariantPersonaBlock(variant)` — 风格提示注入prompt
|
||||
- `recordAssignmentMetrics()` — 按日聚合指标
|
||||
- `analyzeAndSwitchAllBots()` — z检验+自动切换winner
|
||||
|
||||
#### bot-adversarial-learning.mjs — 对抗学习
|
||||
- `runWeeklyAdversarialLearning()` — 全量学习入口
|
||||
- `getActiveLearningForBot()` / `buildAdversarialBlock()` — 发帖时查询+注入
|
||||
- `extractInsight(post, bot, persona)` — DeepSeek提取洞察
|
||||
|
||||
#### bot-avatar-generator.mjs — 头像生成
|
||||
- `generateForAll()` — 遍历112个bot生成头像
|
||||
- `fetchLunarisImage()` / `isLunarisDefault()` / `generateSvgAvatar()` — 三步流程
|
||||
- 10色调色板 + key哈希 → 唯一SVG头像
|
||||
|
||||
### 前端Bot工具
|
||||
|
||||
#### bot-utils.ts (`src/lib/bot-utils.ts`)
|
||||
- `getBotAvatarUrl(key, avatarPrompt)` — 动态头像URL
|
||||
- `getBotColorScheme(key)` — 稳定哈希→Tailwind配色类
|
||||
|
||||
---
|
||||
|
||||
### 修复/诊断脚本
|
||||
- `fix-db-url.cjs` — 批量修复所有 `.mjs` 脚本的 `mysql://` → `mariadb://` 协议兼容（PrismaMariaDb adapter 要求）
|
||||
- `fix-ts-types.cjs` — 批量移除 `.mjs` 文件中的 TypeScript 类型注解（`.mjs` 不支持 TS 语法）
|
||||
- `check-categories.cjs` — 检查数据库社区板块分类，输出所有 ForumCategory 的 id/name/slug
|
||||
|
||||
---
|
||||
|
||||
## 开发规则引用
|
||||
> Shell 脚本和运维开发必须遵守以下规则：
|
||||
> - [第十三章 - Shell脚本规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：`set -e`、PASS/FAIL/WARN 结构化输出、资源预检、禁止操作清单
|
||||
> - [第八章 - 定时任务规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：entrypoint-cron.sh 信号处理、启动校验、健康检查端点；日志三层目录；任务幂等性
|
||||
> - [第十八章 - AI/Bot系统规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：Bot角色定义、活动脚本5大约定、AI API隔离、提示词管理
|
||||
> - [第十九章 - 环境变量管理规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：变量分级、`.env.example` 同步、脚本侧加载顺序
|
||||
|
||||
@@ -188,6 +188,16 @@
|
||||
| CommentCard | `src/components/common/CommentCard.tsx` | 评论卡片（用户信息/等级徽章/评分/点赞/回复/时间） |
|
||||
| CommentThread | `src/components/common/CommentThread.tsx` | 评论列表（分页/点赞/嵌套回复/排序） |
|
||||
|
||||
### 🆕 Bot论坛组件
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| BotAvatar | `src/components/forum/BotAvatar.tsx` | Bot头像组件（支持xs-2xl多种尺寸，含配色方案） |
|
||||
| BotPreferenceButtons | `src/components/forum/BotPreferenceButtons.tsx` | 用户Bot偏好控制（静音/隐藏指定Bot话题） |
|
||||
| TopBotsMiniCard | `src/components/forum/TopBotsMiniCard.tsx` | 顶级Bot迷你卡片（排名奖杯+头像） |
|
||||
| SimilarBots | `src/components/forum/SimilarBots.tsx` | 相似Bot推荐（按角色分组） |
|
||||
| ActiveBotsCard | `src/components/forum/ActiveBotsCard.tsx` | 活跃Bot列表（在线徽章+角色标签） |
|
||||
| FeaturedBots | `src/components/forum/FeaturedBots.tsx` | 精选Bot展示 |
|
||||
|
||||
---
|
||||
|
||||
## 🆕 页面
|
||||
|
||||
@@ -171,7 +171,7 @@ docker-compose -f docker-compose.test.yml up -d
|
||||
- 配置文件: `crontab.txt`（项目根目录）
|
||||
- 修改 crontab.txt 后需重建 cron 容器生效
|
||||
|
||||
### 任务列表（13 条）
|
||||
### 任务列表（25 条）
|
||||
|
||||
| 时间 | 任务 | 脚本 |
|
||||
|------|------|------|
|
||||
@@ -312,4 +312,14 @@ next.config.mjs 配置以下安全响应头：
|
||||
- **Docker build 期模块求值**: Next.js build 时会预渲染 server page 和 API route，导致 Prisma/OpenAI 等模块被求值。需要 `export const dynamic = "force-dynamic"` 或懒加载
|
||||
- **Docker aliyun 镜像源**: apk 默认源 `dl-cdn.alpinelinux.org` 极慢（1m23s），切换 `mirrors.aliyun.com` 仅需 0.134s；npm 切换 `registry.npmmirror.com`
|
||||
- **Supercronic 下载**: GitHub release 的 `release-assets.githubusercontent.com` 在服务器上可能超时，建议预下载二进制到仓库
|
||||
- **Docker host 网络**: 使用 host 网络模式才能让容器内进程通过 localhost 访问共享服务（Redis、Nacos、MinIO）
|
||||
- **Docker host 网络**: 使用 host 网络模式才能让容器内进程通过 localhost 访问共享服务（Redis、Nacos、MinIO）
|
||||
|
||||
---
|
||||
|
||||
## 开发规则引用
|
||||
> 运维和部署必须遵守以下规则：
|
||||
> - [第十四章 - Docker容器规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：容器清单（app+cron）、host网络、健康检查、容器管理命令
|
||||
> - [第十五章 - 部署规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：部署前5项自检、构建流程、部署后六项验证、镜像回滚策略
|
||||
> - [第八章 - 定时任务规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：crontab管理四方同步、entrypoint-cron信号处理、备份脚本完整性
|
||||
> - [第十三章 - Shell脚本规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：set -e、结构化输出、磁盘预检、禁止操作（禁杀共享进程）
|
||||
> - [第十九章 - 环境变量管理规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：变量分级、.env.example同步、脚本侧加载顺序
|
||||
@@ -0,0 +1,70 @@
|
||||
# 开发规则模块
|
||||
|
||||
## 概述
|
||||
项目开发规则体系，定义代码质量、安全、性能、无障碍、SEO、部署等全生命周期的强制/推荐规范。
|
||||
|
||||
- **文件**: [.trae/rules/project_rules.md](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)
|
||||
- **严重级别**: 🔴 必须遵守 | 🟡 强烈推荐 | 🟢 建议
|
||||
|
||||
## 章节目录（22章）
|
||||
|
||||
| 章节 | 内容 | 严重度 |
|
||||
|------|------|--------|
|
||||
| **零、代码质量基础** | TypeScript类型安全、构建检查、Git工作流、文件组织 | 🔴 |
|
||||
| **一、数据获取策略** | ISR、API缓存、缓存失效、N+1优化、并行查询 | 🔴 |
|
||||
| **二、导航与链接规范** | Link组件优先、a标签限制、中间件路由保护 | 🔴 |
|
||||
| **三、图片优化规范** | LazyImage强制使用、LCP优先加载、远程图片配置 | 🔴 |
|
||||
| **四、无障碍规范** | Skip Link、语义化HTML、ARIA/键盘交互、焦点对比度 | 🔴 |
|
||||
| **五、结构化数据与SEO** | JSON-LD、metadata、Canonical URL、Robots策略 | 🔴 |
|
||||
| **六、性能规范** | 组件懒加载、虚拟滚动、字体优化、Suspense、Bundle体积 | 🔴 |
|
||||
| **七、安全规范** | CSP、XSS防护、Zod输入验证、认证授权、敏感信息、Bot防护 | 🔴 |
|
||||
| **八、定时任务规范** | Crontab管理、任务日志、备份脚本、错误处理、幂等性、Entrypoint规范、日志规范 | 🔴 |
|
||||
| **九、测试规范** | Vitest框架、80%覆盖率、三类测试、禁止skip | 🟡 |
|
||||
| **十、设计系统速查** | 颜色/圆角/阴影/动画Token | 🟡 |
|
||||
| **十一、API约定速查** | 前缀/分页/返回格式 | 🟡 |
|
||||
| **十二、踩坑记录** | Next.js/Prisma/Docker/Chart.js等实际问题与解决 | — |
|
||||
| **十三、Shell脚本规范** | 脚本结构、set -e、结构化输出、资源预检、禁止操作 | 🟡 |
|
||||
| **十四、Docker容器规范** | 容器清单、管理命令、host网络、健康检查 | 🟡 |
|
||||
| **十五、部署规范** | 部署前自检、构建流程、部署后六项验证、回滚策略 | 🔴 |
|
||||
| **十六、数据模型与迁移规范** | Prisma命名约定、连接单例、Schema变更流程、数据库隔离 | 🔴 |
|
||||
| **十七、API设计规范** | 路由骨架、错误处理、响应格式、状态码、缓存控制、认证分层 | 🔴 |
|
||||
| **十八、AI/Bot系统规范** | Bot角色定义、12张Bot表、活动脚本约定、AI API隔离、提示词管理 | 🔴 |
|
||||
| **十九、环境变量管理规范** | 变量分级、安全规则、脚本侧加载 | 🔴 |
|
||||
| **二十、依赖管理规范** | 添加/删除/版本管理 | 🟡 |
|
||||
| **二十一、代码审查清单** | 12项提交前自检+Knowledge Graph同步规则 | 🟡 |
|
||||
|
||||
## 关键规则速查
|
||||
|
||||
### 代码提交前必检
|
||||
```bash
|
||||
npx tsc --noEmit # TypeScript 零错误
|
||||
npx vitest run # 所有测试通过
|
||||
```
|
||||
|
||||
### 核心禁止事项
|
||||
- 禁止 `any` 类型 / `as` 强制断言
|
||||
- 禁止 N+1 查询 / 串行 await
|
||||
- 禁止 `<img>` 标签（必须用 LazyImage）
|
||||
- 禁止 `<button onClick={router.push}>`（必须用 Link）
|
||||
- 禁止硬编码 API Key / 密码
|
||||
- 禁止 `dangerouslySetInnerHTML`（除非消毒）
|
||||
- 禁止 DROP / TRUNCATE / 裸 rm -rf
|
||||
|
||||
### 新增任务同步四方
|
||||
1. `scripts/task-xxx.mjs` — 创建脚本
|
||||
2. `crontab.txt` — 添加 supercronic 条目
|
||||
3. `seed-task-configs.mjs` — 注册 TaskConfig
|
||||
4. `health-check.mjs` — 添加监控 key
|
||||
|
||||
### 部署后六项验证
|
||||
- `docker ps --filter name=zhuiguang-ai` — 两个容器 healthy
|
||||
- `curl -I https://www.zhuig.com` — 200 / < 3s
|
||||
- `ss -tlnp | grep :8301` — 端口为 Docker
|
||||
- `docker logs --tail 20 zhuiguang-ai-app` — 无 FATAL/ERROR
|
||||
- `docker logs --tail 20 zhuiguang-ai-cron` — "Container ready"
|
||||
- 其他项目容器仍在运行
|
||||
|
||||
## 版本历史
|
||||
- 2026-06-23: 第三轮优化 — 新增6章（数据模型/API设计/Bot系统/环境变量/依赖/审查清单）
|
||||
- 2026-06-22: 第二轮优化 — 新增3章（Shell/Docker/部署）+ Entrypoint/日志子章节
|
||||
- 2026-06-22: 第一轮优化 — 8章→12章，TypeScript/Git/测试/性能/安全/无障碍全面增强
|
||||
@@ -0,0 +1,131 @@
|
||||
# 通知系统模块
|
||||
|
||||
## 概述
|
||||
通知系统提供实时消息推送、智能摘要合并和个性化偏好设置，确保用户不错过重要互动但也不被过度打扰。
|
||||
|
||||
## 数据模型
|
||||
|
||||
### Notification (通知)
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Int @id | 主键 |
|
||||
| userId | Int | 用户ID |
|
||||
| type | NotifType | 通知类型 |
|
||||
| title | String | 标题 |
|
||||
| content | String? | 内容 |
|
||||
| link | String? | 跳转链接 |
|
||||
| isRead | Boolean @default(false) | 是否已读 |
|
||||
| createdAt | DateTime | 创建时间 |
|
||||
|
||||
### NotifType 枚举
|
||||
| 值 | 说明 |
|
||||
|------|------|
|
||||
| COMMENT_REPLY | 评论回复通知 |
|
||||
| COMMENT_LIKE | 评论点赞通知 |
|
||||
| TOPIC_REPLY | 话题回复通知 |
|
||||
| SYSTEM | 系统通知 |
|
||||
| DIGEST 🆕 | 智能摘要合并通知 |
|
||||
|
||||
---
|
||||
|
||||
## 智能通知摘要 (Smart Notification Digest) 🆕
|
||||
|
||||
### 功能说明
|
||||
当用户在短时间内收到多条同类通知时，系统自动合并为一条摘要通知，减少通知轰炸。
|
||||
|
||||
### 合并规则
|
||||
- 同类通知（同 type + 同来源）在 30 分钟内合并
|
||||
- 摘要格式: "你的帖子收到了 5 条新回复"
|
||||
- 原始通知保留但标记为已读，摘要通知链接到通知详情页
|
||||
|
||||
### 定时任务
|
||||
- **脚本**: `scripts/notification-digest.mjs`
|
||||
- 每 3 小时合并一次未读通知
|
||||
- 仅对超过 3 条同类通知的用户生成摘要
|
||||
|
||||
---
|
||||
|
||||
## 通知偏好设置 🆕
|
||||
|
||||
### 功能
|
||||
用户可在通知中心设置通知偏好，控制接收哪些类型的通知。
|
||||
|
||||
### API
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/user/notification-prefs | GET | 获取通知偏好 |
|
||||
| /api/user/notification-prefs | PUT | 更新通知偏好 |
|
||||
|
||||
### 可配置项
|
||||
| 偏好键 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| comment_reply | 评论回复通知 | true |
|
||||
| comment_like | 评论点赞通知 | true |
|
||||
| topic_reply | 话题回复通知 | true |
|
||||
| system | 系统通知 | true |
|
||||
| digest | 智能摘要通知 | true |
|
||||
| email_digest | 邮件摘要（未实现） | false |
|
||||
|
||||
---
|
||||
|
||||
## 通知中心页面 🆕
|
||||
|
||||
### 路由
|
||||
- `/user/notifications` — 通知中心独立页面
|
||||
|
||||
### 功能
|
||||
- 分类标签页: 全部 / 回复 / 点赞 / 系统 / 摘要
|
||||
- 批量标记已读
|
||||
- 单条跳转到目标内容
|
||||
- 未读数量徽章
|
||||
- 通知偏好设置入口
|
||||
|
||||
### 组件
|
||||
- `NotificationCenter` (`src/components/forum/NotificationCenter.tsx`)
|
||||
|
||||
---
|
||||
|
||||
## API 接口
|
||||
|
||||
### 通知核心 API
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/notifications | GET | 获取通知列表（含未读数） |
|
||||
| /api/notifications | PUT | 标记通知为已读（支持指定ids或全部已读） |
|
||||
| /api/notifications/unread-count | GET | 获取未读通知数量（轻量级） |
|
||||
|
||||
### 通知偏好 API 🆕
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/user/notification-prefs | GET | 获取通知偏好设置 |
|
||||
| /api/user/notification-prefs | PUT | 更新通知偏好设置 |
|
||||
|
||||
---
|
||||
|
||||
## 自动触发规则
|
||||
|
||||
以下操作自动生成通知：
|
||||
|
||||
| 操作 | 通知对象 | 通知类型 |
|
||||
|------|----------|----------|
|
||||
| 回复评论 | 评论作者 | COMMENT_REPLY |
|
||||
| 点赞评论 | 评论作者 | COMMENT_LIKE |
|
||||
| 回复话题 | 话题作者 | TOPIC_REPLY |
|
||||
| 系统公告 | 所有用户 | SYSTEM |
|
||||
| 摘要合并 | 用户本人 | DIGEST |
|
||||
|
||||
---
|
||||
|
||||
## 前端组件
|
||||
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| NotificationBell | `src/components/forum/NotificationBell.tsx` | 导航栏通知铃铛（红点/下拉面板/自动已读） |
|
||||
| NotificationCenter | `src/components/forum/NotificationCenter.tsx` 🆕 | 通知中心页面（分类标签/批量操作/偏好入口） |
|
||||
|
||||
### NotificationBell 交互
|
||||
- 未读时显示红色圆点徽章
|
||||
- 点击展开快捷通知面板（最近5条）
|
||||
- 下拉面板支持滚动加载更多
|
||||
- 点击通知跳转到目标页面并自动标记已读
|
||||
- "查看全部"链接跳转到通知中心
|
||||
@@ -0,0 +1,179 @@
|
||||
# 积分体系模块
|
||||
|
||||
## 概述
|
||||
积分体系是追光AI的用户激励核心，包含20级成长系统、积分奖励引擎、积分商店、签到连击和Streak冻结保护，通过游戏化机制提升用户活跃度和留存率。
|
||||
|
||||
## 积分规则
|
||||
|
||||
| 行为 | 积分 | 每日上限 |
|
||||
|------|------|----------|
|
||||
| 发表评论 | +5 | 50 |
|
||||
| 评论被点赞 | +2 | 20 |
|
||||
| 发布论坛话题 | +10 | 无限制 |
|
||||
| 论坛回复 | +5 | 30 |
|
||||
| 发表评价 | +8 | 20 |
|
||||
| 每日签到 | +1 (递增) | 1 |
|
||||
| 签到连击 bonus | 连续7天+3, 连续30天+10 | - |
|
||||
|
||||
---
|
||||
|
||||
## 等级系统 - 20级成长体系
|
||||
|
||||
### 等级配置
|
||||
- **配置文件**: `src/lib/level-config.ts` — 客户端安全（无Prisma依赖）
|
||||
- 等级范围: LV01(0分) → LV20(50000分)
|
||||
- 等级图标: ⭐(初级) → ⭐⭐⭐(中级) → 🌟(高级) → 🌟🌟(精英) → 🌟🌟🌟(大师)
|
||||
|
||||
### 等级表
|
||||
| 等级 | 最低积分 | 徽章 | 每日限额 |
|
||||
|------|----------|------|----------|
|
||||
| LV01 | 0 | ⭐ | 50 |
|
||||
| LV02 | 10 | ⭐ | 80 |
|
||||
| LV03 | 30 | ⭐⭐ | 100 |
|
||||
| LV04 | 60 | ⭐⭐ | 120 |
|
||||
| LV05 | 100 | ⭐⭐ | 150 |
|
||||
| LV06 | 200 | ⭐⭐⭐ | 180 |
|
||||
| LV07 | 400 | ⭐⭐⭐ | 200 |
|
||||
| LV08 | 700 | ⭐⭐⭐ | 250 |
|
||||
| LV09 | 1000 | ⭐⭐⭐ | 300 |
|
||||
| LV10 | 1500 | 🌟 | 400 |
|
||||
| LV11 | 2000 | 🌟 | 500 |
|
||||
| LV12 | 3000 | 🌟 | 600 |
|
||||
| LV13 | 4500 | 🌟 | 700 |
|
||||
| LV14 | 6000 | 🌟🌟 | 800 |
|
||||
| LV15 | 8000 | 🌟🌟 | 1000 |
|
||||
| LV16 | 11000 | 🌟🌟 | 1200 |
|
||||
| LV17 | 15000 | 🌟🌟 | 1500 |
|
||||
| LV18 | 20000 | 🌟🌟🌟 | 1800 |
|
||||
| LV19 | 30000 | 🌟🌟🌟 | 2000 |
|
||||
| LV20 | 50000 | 🌟🌟🌟 | 3000 |
|
||||
|
||||
### 旧等级迁移映射
|
||||
BRONZE→LV01, SILVER→LV03, GOLD→LV06, PLATINUM→LV10
|
||||
|
||||
### 积分奖励引擎
|
||||
- **文件**: `src/lib/points-reward.ts`
|
||||
- `rewardPoints()` — 自动发放积分 + 日限额检查 + 事务写入
|
||||
- `getUserStats()` — 获取用户综合统计（积分/评论数/话题数等）
|
||||
- `getUserPointsHistory()` — 积分历史分页查询
|
||||
|
||||
---
|
||||
|
||||
## 签到系统
|
||||
|
||||
### 每日签到
|
||||
- 基础+1分，连续签到递增奖励
|
||||
- 连续7天: +3 bonus
|
||||
- 连续30天: +10 bonus
|
||||
- 中断重置
|
||||
|
||||
### CheckInCard 组件
|
||||
- 位置: 用户中心顶部
|
||||
- 功能: 签到按钮、连击天数显示、季度签到日历
|
||||
|
||||
---
|
||||
|
||||
## Streak 冻结保护
|
||||
|
||||
### 功能说明
|
||||
- 用户可通过积分商店购买 Streak Freeze 卡片
|
||||
- 当用户某天未签到时，自动消耗一张 Freeze 卡保护连击不断
|
||||
- 最多持有 3 张 Freeze 卡
|
||||
|
||||
### 核心库
|
||||
- **文件**: `src/lib/streak-freeze.ts`
|
||||
- `checkAndApplyFreeze(userId)` — 检查是否需要冻结并自动应用
|
||||
- `getFreezeCardCount(userId)` — 获取当前持有数量
|
||||
- `useFreezeCard(userId)` — 消耗一张冻结卡
|
||||
|
||||
### 定时任务
|
||||
- **脚本**: `scripts/grant-freeze-cards.mjs`
|
||||
- 定期为活跃用户发放 Freeze 卡（每日01:00）
|
||||
|
||||
---
|
||||
|
||||
## 积分商店
|
||||
|
||||
### 功能概述
|
||||
用户可使用积分兑换虚拟物品和社区权益。
|
||||
|
||||
### 商品定义
|
||||
- **文件**: `src/lib/shop-items.ts`
|
||||
- 商品类型: 头像框、昵称颜色、特效道具、Streak Freeze 卡
|
||||
|
||||
### API 接口
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/user/shop/items | GET | 获取可购买商品列表 |
|
||||
| /api/user/shop/purchase | POST | 购买商品（扣积分） |
|
||||
| /api/user/shop/my-items | GET | 获取用户已购物品 |
|
||||
|
||||
### 前端组件
|
||||
- 积分商店页面（用户中心入口）
|
||||
- 商品卡片（名称/图标/价格/库存/购买按钮）
|
||||
- 已购物品展示（个人中心装饰效果）
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### PointsHistory (积分历史)
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Int @id | 主键 |
|
||||
| userId | Int | 用户ID |
|
||||
| points | Int | 积分变动（正数获得/负数消耗） |
|
||||
| reason | String | 积分原因 |
|
||||
| detail | String? | 详细信息 |
|
||||
| refType | String? | 关联类型 |
|
||||
| refId | Int? | 关联ID |
|
||||
| createdAt | DateTime | 创建时间 |
|
||||
|
||||
### StreakFreeze (冻结卡) 🆕
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Int @id | 主键 |
|
||||
| userId | Int | 用户ID |
|
||||
| cardCount | Int | 持有数量 |
|
||||
| lastUsedAt | DateTime? | 最近使用时间 |
|
||||
| createdAt | DateTime | 创建时间 |
|
||||
|
||||
### UserShopItem (已购物品) 🆕
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Int @id | 主键 |
|
||||
| userId | Int | 用户ID |
|
||||
| itemId | String | 商品ID |
|
||||
| purchasedAt | DateTime | 购买时间 |
|
||||
| isActive | Boolean | 是否启用/佩戴 |
|
||||
|
||||
---
|
||||
|
||||
## 前端组件
|
||||
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| MemberBadge | `src/components/common/MemberBadge.tsx` | 会员等级徽章（⭐🌟 + 积分显示，3种尺寸） |
|
||||
| LevelProgress | `src/components/common/LevelProgress.tsx` | 等级进度条（当前/下一级/进度百分比，动态变色） |
|
||||
| CheckInCard | `src/components/common/CheckInCard.tsx` | 签到卡片（签到按钮/连击天数/季度日历） |
|
||||
|
||||
---
|
||||
|
||||
## 技术实现要点
|
||||
|
||||
### 积分自动奖励机制
|
||||
所有评论/发帖/点赞操作自动通过 `rewardPoints()` 发放积分：
|
||||
- 每日上限检查（防刷分）
|
||||
- 事务写入（积分变更 + 历史记录同时写入）
|
||||
- 等级自动随积分变化更新
|
||||
|
||||
### 日志分类
|
||||
积分变动通过 `reason` 字段区分：
|
||||
- `comment` — 评论
|
||||
- `comment_liked` — 评论被点赞
|
||||
- `topic_create` — 发帖
|
||||
- `reply` — 回复
|
||||
- `review` — 评价
|
||||
- `check_in` — 签到
|
||||
- `shop_purchase` — 商店消费（负数）
|
||||
@@ -0,0 +1,93 @@
|
||||
# 搜索增强模块
|
||||
|
||||
## 概述
|
||||
搜索增强模块提供自动补全、搜索历史、键盘导航和搜索结果高亮，全面提升搜索体验和效率。
|
||||
|
||||
---
|
||||
|
||||
## 搜索自动补全 🆕
|
||||
|
||||
### API
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/search/autocomplete | GET | 搜索自动补全建议 |
|
||||
|
||||
- Query: `q` (搜索关键词), `type` (tool/skill/all)
|
||||
- 返回: `{ suggestions: [{ text, type, slug }] }`
|
||||
- 基于工具名称、技能名称、标签前缀匹配
|
||||
- 最多返回 8 条建议
|
||||
- 响应时间 < 100ms（内存缓存）
|
||||
|
||||
### 前端组件
|
||||
|
||||
#### SearchBox 重写 🆕
|
||||
- **文件**: `src/components/common/SearchBox.tsx`
|
||||
- **功能**:
|
||||
- 输入时实时显示自动补全下拉
|
||||
- 键盘导航: ↑↓ 移动高亮 / Enter 选择 / ESC 关闭
|
||||
- 搜索防抖（300ms）
|
||||
- 搜索结果高亮匹配文本
|
||||
- 支持工具/技能分类筛选
|
||||
|
||||
---
|
||||
|
||||
## 搜索历史 🆕
|
||||
|
||||
### 存储
|
||||
- localStorage 存储: `zhuiguang-search-history`
|
||||
- 最多保留 20 条历史记录
|
||||
- 按最近使用排序
|
||||
- 去重（同一查询只保留最新一条）
|
||||
|
||||
### 交互
|
||||
- 搜索框聚焦时显示历史记录下拉
|
||||
- 点击历史记录直接搜索
|
||||
- 支持单条删除和清空全部
|
||||
- 历史记录带搜索类型图标
|
||||
|
||||
---
|
||||
|
||||
## 高亮文本组件 🆕
|
||||
|
||||
### HighlightText
|
||||
- **文件**: `src/components/common/HighlightText.tsx`
|
||||
- Props: `{ text: string, keyword: string, className?: string }`
|
||||
- 功能: 将文本中匹配的关键词包裹在 `<mark>` 标签中
|
||||
- 样式: 黄色高亮背景 `bg-yellow-200 dark:bg-yellow-800`
|
||||
- 不区分大小写匹配
|
||||
|
||||
### 使用场景
|
||||
- 搜索结果列表中的工具名称/描述
|
||||
- 自动补全下拉中的建议文本
|
||||
- 评论/话题搜索
|
||||
|
||||
---
|
||||
|
||||
## 搜索框语义化
|
||||
|
||||
### WCAG 合规
|
||||
- `<form role="search">` 包裹搜索表单
|
||||
- `<label>` 关联搜索输入框（视觉隐藏）
|
||||
- `<input type="search" name="search">` 语义输入
|
||||
- `aria-label="搜索AI工具"` 辅助标签
|
||||
- 自动补全列表 `role="listbox"` + `aria-activedescendant`
|
||||
|
||||
---
|
||||
|
||||
## 搜索参数规范
|
||||
|
||||
### 标准搜索参数
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| search | string | 搜索关键词 |
|
||||
| page | number | 页码（默认1） |
|
||||
| pageSize | number | 每页条数（默认20） |
|
||||
| categoryId | number | 分类筛选 |
|
||||
| pricingModel | string | 定价筛选 |
|
||||
| sort | string | 排序（latest/popular/rating） |
|
||||
|
||||
### URL 搜索参数同步
|
||||
- 搜索关键词同步到 URL query string
|
||||
- 支持浏览器前进/后退导航
|
||||
- 分享搜索结果 URL 可直接还原搜索状态
|
||||
@@ -0,0 +1,174 @@
|
||||
# 测试体系模块
|
||||
|
||||
## 概述
|
||||
追光AI使用 Vitest 作为测试框架，已建立 5 个测试套件覆盖 132 个测试，目标覆盖率 80%+。测试文件位于 `src/__tests__/` 目录。
|
||||
|
||||
---
|
||||
|
||||
## 基础设施
|
||||
|
||||
### vitest.config.ts
|
||||
```typescript
|
||||
import { defineConfig } from "vitest/config";
|
||||
import path from "path";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
globals: true,
|
||||
environment: "node",
|
||||
setupFiles: ["./vitest.setup.ts"],
|
||||
include: ["src/__tests__/**/*.test.ts"],
|
||||
coverage: {
|
||||
provider: "v8",
|
||||
reporter: ["text", "json", "html"],
|
||||
thresholds: {
|
||||
lines: 80,
|
||||
branches: 80,
|
||||
functions: 80,
|
||||
statements: 80,
|
||||
},
|
||||
},
|
||||
},
|
||||
resolve: {
|
||||
alias: { "@": path.resolve(__dirname, "./src") },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### vitest.setup.ts
|
||||
- 全局 mock 配置
|
||||
- Prisma mock 初始化
|
||||
- 测试环境清理
|
||||
|
||||
### tsconfig 配置
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"types": ["vitest/globals"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试套件
|
||||
|
||||
### 1. level-config.test.ts
|
||||
- **测试数量**: 28
|
||||
- **覆盖**: `src/lib/level-config.ts`
|
||||
- **测试内容**:
|
||||
- 20个等级边界值检查
|
||||
- 等级徽章映射
|
||||
- 每日限额表
|
||||
- 积分→等级转换
|
||||
- 下一级积分计算
|
||||
|
||||
### 2. elo.test.ts
|
||||
- **测试数量**: 24
|
||||
- **覆盖**: ELO 评分计算逻辑
|
||||
- **测试内容**:
|
||||
- 基础 ELO 计算
|
||||
- K因子变化
|
||||
- 平局处理
|
||||
- 极端分差
|
||||
|
||||
### 3. forum-hot.test.ts
|
||||
- **测试数量**: 30
|
||||
- **覆盖**: 论坛热度排序算法
|
||||
- **测试内容**:
|
||||
- 热度公式计算
|
||||
- 时间衰减
|
||||
- 回复加权
|
||||
- 点赞加权
|
||||
- 置顶优先
|
||||
|
||||
### 4. achievements.test.ts
|
||||
- **测试数量**: 26
|
||||
- **覆盖**: 成就系统逻辑
|
||||
- **测试内容**:
|
||||
- 成就解锁条件
|
||||
- 进度计算
|
||||
- 徽章授予
|
||||
- 边界条件
|
||||
|
||||
### 5. points-reward.test.ts
|
||||
- **测试数量**: 24
|
||||
- **覆盖**: `src/lib/points-reward.ts`
|
||||
- **测试内容**:
|
||||
- 各操作积分奖励
|
||||
- 每日上限检查
|
||||
- Streak freeze 逻辑
|
||||
- 商店购买消耗
|
||||
- 等级升级触发
|
||||
|
||||
---
|
||||
|
||||
## 运行命令
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
npx vitest run
|
||||
|
||||
# 监听模式
|
||||
npx vitest
|
||||
|
||||
# 生成覆盖率报告
|
||||
npx vitest run --coverage
|
||||
|
||||
# 运行特定测试文件
|
||||
npx vitest run src/__tests__/level-config.test.ts
|
||||
|
||||
# UI 模式
|
||||
npx vitest --ui
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试规范
|
||||
|
||||
### 文件命名
|
||||
- 测试文件: `*.test.ts`
|
||||
- 目录: `src/__tests__/`
|
||||
|
||||
### 测试结构
|
||||
```typescript
|
||||
import { describe, it, expect, beforeEach, vi } from "vitest";
|
||||
|
||||
describe("模块名", () => {
|
||||
beforeEach(() => {
|
||||
// setup
|
||||
});
|
||||
|
||||
describe("功能点", () => {
|
||||
it("应该满足某条件", () => {
|
||||
// arrange
|
||||
// act
|
||||
// assert
|
||||
});
|
||||
|
||||
it("应该处理边界情况", () => {
|
||||
// ...
|
||||
});
|
||||
|
||||
it("应该优雅处理错误", () => {
|
||||
// ...
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 测试原则
|
||||
- 每个 `it` 测试单一行为
|
||||
- 使用 `describe` 组织相关测试
|
||||
- Arrange → Act → Assert 三段式
|
||||
- 覆盖正常路径 + 边界条件 + 错误路径
|
||||
- 禁止 `.skip` 除非有明确 TODO 注释
|
||||
- Mock 外部依赖（Prisma、外部 API）
|
||||
|
||||
### 覆盖率目标
|
||||
| 指标 | 目标 |
|
||||
|------|------|
|
||||
| 行覆盖率 | ≥ 80% |
|
||||
| 分支覆盖率 | ≥ 80% |
|
||||
| 函数覆盖率 | ≥ 80% |
|
||||
| 语句覆盖率 | ≥ 80% |
|
||||
@@ -0,0 +1,118 @@
|
||||
# 暗色模式模块
|
||||
|
||||
## 概述
|
||||
追光AI支持浅色/暗色双主题模式，通过 ThemeProvider + CSS 变量驱动，用户偏好自动持久化到 localStorage，整体遵循 Tailwind CSS `class` 策略。
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
ThemeProvider (Context)
|
||||
├── 读取 localStorage 初始主题
|
||||
├── 监听系统 prefers-color-scheme 变化
|
||||
├── 在 <html> 上切换 "dark" class
|
||||
└── 提供 toggle/setTheme 方法给子孙组件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心组件
|
||||
|
||||
### ThemeProvider
|
||||
- **文件**: `src/components/ThemeProvider.tsx`
|
||||
- **位置**: 根 layout.tsx 包裹
|
||||
- **功能**:
|
||||
- `theme` state: `"light"` | `"dark"` | `"system"`
|
||||
- `toggleTheme()` — 在 light/dark 间切换
|
||||
- `setTheme(mode)` — 设置为指定模式
|
||||
- 自动监听 `prefers-color-scheme` 媒体查询（`system` 模式时）
|
||||
- 持久化到 `localStorage("zhuiguang-theme")`
|
||||
|
||||
### Header 主题切换按钮
|
||||
- **文件**: `src/components/layout/Header.tsx`
|
||||
- 太阳 ☀️ / 月亮 🌙 图标切换
|
||||
- 点击调用 `toggleTheme()`
|
||||
- 动画过渡效果
|
||||
|
||||
---
|
||||
|
||||
## CSS 变量系统
|
||||
|
||||
### globals.css 暗色变量
|
||||
```css
|
||||
:root {
|
||||
/* 浅色主题变量 (默认) */
|
||||
--background: 0 0% 100%;
|
||||
--foreground: 222 47% 11%;
|
||||
/* ... */
|
||||
}
|
||||
|
||||
.dark {
|
||||
/* 暗色主题变量覆盖 */
|
||||
--background: 222 47% 11%;
|
||||
--foreground: 210 40% 98%;
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
- 使用 HSL 变量，Tailwind 通过 `hsl(var(--xxx))` 引用
|
||||
- shadcn/ui 组件自动适配暗色模式（基于 `.dark` class）
|
||||
|
||||
---
|
||||
|
||||
## 组件适配（14个文件已更新）
|
||||
|
||||
以下组件已适配暗色模式：
|
||||
|
||||
| 组件 | 适配内容 |
|
||||
|------|----------|
|
||||
| Header | 主题切换按钮、导航栏背景色 |
|
||||
| Footer | 页脚背景色、文字色、分隔线 |
|
||||
| HeroBanner | Canvas 粒子颜色随主题切换 |
|
||||
| HomePageClient | 卡片背景、文字颜色 |
|
||||
| ToolsContent | 搜索框、筛选侧边栏、卡片 |
|
||||
| SkillsPageClient | 技能卡片、分类标签 |
|
||||
| 社区相关组件 | ForumBoard/ForumTopicCard/ForumEditor |
|
||||
| 通知组件 | NotificationBell/NotificationCenter |
|
||||
| 用户中心 | 积分卡片、等级进度条 |
|
||||
| 工具详情 | 信息面板、推荐列表 |
|
||||
| 技能详情 | 评测卡片、详情面板 |
|
||||
| 后台管理 | 管理面板所有表格/表单 |
|
||||
|
||||
---
|
||||
|
||||
## 设计规范
|
||||
|
||||
### 浅色主题
|
||||
- 背景: `bg-white` / `bg-muted/50`
|
||||
- 卡片: `bg-white/80` (毛玻璃) / `bg-white/60` (卡片)
|
||||
- 边框: `border-border/40`
|
||||
- 阴影: `shadow-sm`
|
||||
|
||||
### 暗色主题
|
||||
- 背景: `bg-background` (HSL 222 47% 11%)
|
||||
- 卡片: `bg-card` (HSL 222 47% 13-15%)
|
||||
- 边框: `border-border` (HSL 215 20% 25%)
|
||||
- 阴影: `shadow-md` (更明显的阴影)
|
||||
|
||||
### 颜色规范（双主题通用）
|
||||
- 文字: 浅色 `-600/-700` | 暗色 `-300/-200`
|
||||
- 背景: 浅色 `-50` | 暗色 `-900/-950`
|
||||
- 边框: 浅色 `-200/60` | 暗色 `-700/60`
|
||||
|
||||
---
|
||||
|
||||
## 技术实现要点
|
||||
|
||||
### 闪烁防护
|
||||
- ThemeProvider 在 `useEffect` 中初始化，避免 SSR 时的主题闪烁
|
||||
- `<html>` 上通过内联 script 在 hydration 前设置 class（防止白屏闪烁）
|
||||
|
||||
### 系统主题跟随
|
||||
- `matchMedia('(prefers-color-scheme: dark)')` 监听
|
||||
- 用户手动设置后覆盖系统偏好
|
||||
- "system" 模式时动态跟随
|
||||
|
||||
### 持久化策略
|
||||
- 存储键: `zhuiguang-theme`
|
||||
- 值: `"light"` | `"dark"`
|
||||
- 优先级: localStorage > 系统偏好 > 默认 light
|
||||
@@ -0,0 +1,128 @@
|
||||
# 工具功能增强模块
|
||||
|
||||
## 概述
|
||||
工具功能增强模块包含工具对比（Compare）、工具认证徽章（Verified Badge）和个性化工具推荐（Recommendations），提升用户决策效率和信任度。
|
||||
|
||||
---
|
||||
|
||||
## 工具对比 (Tool Comparison) 🆕
|
||||
|
||||
### 功能概述
|
||||
用户可同时选择最多 4 个工具进行并排对比，从 10 个维度查看详细差异。
|
||||
|
||||
### 架构
|
||||
```
|
||||
CompareProvider (React Context)
|
||||
├── compareList: Tool[] (最多4个)
|
||||
├── addToCompare(tool) — 添加工具到对比列表
|
||||
├── removeFromCompare(toolId) — 移除
|
||||
├── clearCompare() — 清空
|
||||
└── isInCompare(toolId) — 是否已在列表
|
||||
```
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| CompareProvider | `src/components/common/CompareProvider.tsx` | Context Provider，管理对比状态 |
|
||||
| CompareBar | `src/components/common/CompareBar.tsx` | 底部浮动对比栏（显示已选工具+对比按钮） |
|
||||
| CompareButton | `src/components/common/CompareButton.tsx` | 工具卡片上的"加入对比"切换按钮 |
|
||||
|
||||
### 页面
|
||||
|
||||
#### /tools/compare
|
||||
- 10维度对比表格
|
||||
- 维度: 名称/分类/定价模型/定价详情/功能特性/标签/评分/评论数/浏览数/官网链接
|
||||
- 支持一键移除/清空/返回浏览
|
||||
|
||||
### 交互流程
|
||||
1. 在工具列表/详情页点击 CompareButton 添加工具
|
||||
2. 底部 CompareBar 浮出显示已选工具（最大4个）
|
||||
3. 点击 CompareBar 的"开始对比"按钮跳转到 /tools/compare
|
||||
4. 对比页面展示并排表格，可移除/继续添加
|
||||
|
||||
### CompareBar 状态
|
||||
- 空状态: 隐藏
|
||||
- 1个工具: 显示但对比按钮禁用（至少需要2个）
|
||||
- 2-4个工具: 显示完整，对比按钮可用
|
||||
- 4个工具: 添加按钮禁用，显示"已满"
|
||||
|
||||
---
|
||||
|
||||
## 工具认证徽章 (Tool Verification) 🆕
|
||||
|
||||
### 功能概述
|
||||
管理员可为优质/官方工具添加蓝V认证徽章，提升用户信任度。
|
||||
|
||||
### 数据模型
|
||||
- Tool 表新增字段: `isVerified: Boolean @default(false)`
|
||||
- Tool 表新增字段: `verifiedAt: DateTime?`
|
||||
|
||||
### API
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/admin/tools/[id]/verify | POST | 管理员认证工具（添加蓝V） |
|
||||
| /api/admin/tools/[id]/verify | DELETE | 管理员取消认证 |
|
||||
| /api/tools/verified | GET | 获取所有已认证工具 |
|
||||
|
||||
### 前端展示
|
||||
- 工具详情页: 名称旁边显示蓝色勾号徽章
|
||||
- 工具列表卡片: 名称旁边显示小蓝V图标
|
||||
- 认证工具专属筛选: "仅看认证" 开关
|
||||
|
||||
---
|
||||
|
||||
## 内容推荐引擎 🆕
|
||||
|
||||
### 功能概述
|
||||
基于用户浏览历史和收藏偏好，推荐相关工具和话题。
|
||||
|
||||
### 核心 API
|
||||
|
||||
| 路由 | 方法 | 功能 |
|
||||
|------|------|------|
|
||||
| /api/recommendations | GET | 获取个性化推荐（工具+技能） |
|
||||
|
||||
### 推荐算法
|
||||
- **协同过滤**: 基于相似用户的收藏/浏览模式
|
||||
- **内容相似度**: 基于工具分类/标签/定价模型
|
||||
- **热度加权**: 综合浏览量、评论数、评分
|
||||
|
||||
### 前端组件
|
||||
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| PersonalizedRecommend | `src/components/common/PersonalizedRecommend.tsx` 🆕 | 首页/用户中心的个性化推荐区 |
|
||||
| RelatedTopics | `src/components/forum/RelatedTopics.tsx` | 话题详情页的相关话题推荐 |
|
||||
|
||||
### 展示位置
|
||||
- 首页 "为你推荐" 板块
|
||||
- 工具详情页 "相关推荐"
|
||||
- 话题详情页 "相关话题"
|
||||
- 用户中心 "猜你喜欢"
|
||||
|
||||
### PersonalizedRecommend 组件
|
||||
- Props: `{ type: "tool" | "skill" | "topic", limit?: number }`
|
||||
- 瀑布流/网格布局
|
||||
- 骨架屏加载状态
|
||||
- 空状态友好提示
|
||||
- 支持刷新获取新推荐
|
||||
|
||||
---
|
||||
|
||||
## 共享类型定义
|
||||
|
||||
集中管理来源类型标签和颜色：
|
||||
|
||||
### src/lib/source-type.ts 🆕
|
||||
```typescript
|
||||
export function sourceTypeLabel(type: string): string
|
||||
export function sourceTypeColor(type: string): string
|
||||
```
|
||||
- 支持: github / gitlab / gitee / huggingface / 官网
|
||||
- 统一管理标签中文名和 Tailwind 配色
|
||||
|
||||
### src/lib/constants.ts 🆕
|
||||
- `tagColors` — 工具/技能标签配色映射
|
||||
- 统一管理所有标签的颜色方案
|
||||
Reference in New Issue
Block a user