zhuiguang-ai/.trae/specs/modules/tools.md

工具功能增强模块

概述

工具功能增强模块包含工具对比（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 🆕

export function sourceTypeLabel(type: string): string
export function sourceTypeColor(type: string): string

• 支持: github / gitlab / gitee / huggingface / 官网
• 统一管理标签中文名和 Tailwind 配色

src/lib/constants.ts 🆕

• tagColors — 工具/技能标签配色映射
• 统一管理所有标签的颜色方案