基于 AI 大模型的多智能体协作推荐框架，通过智能体协作实现可解释、透明、开放的个性化推荐。
技术栈：纯 TypeScript（Next.js 16 + React 19 + LangGraph JS + Supabase）
状态：✅ 已完成，生产就绪
访问地址：https://your-domain.com（开源前替换为实际域名）
Open（开放）+ eXplainable（可解释）+ Recommendation（推荐）
OpenXRec = 开放的推荐算法（透明可见）
+ 可解释的推荐结果（推理路径清晰）
+ 用户可参与配置（个性化调优）
| 维度 | 传统推荐系统 | OpenXRec |
|---|---|---|
| 透明度 | 黑盒算法，用户不知道为何推荐 | 每个推荐都有清晰的解释和推理路径 |
| 可控性 | 用户无法调整推荐策略 | 用户可参与配置，调整偏好权重 |
| 信任度 | 算法歧视、信息茧房问题 | 推荐过程完全透明，可审计可追溯 |
| 适应性 | 静态算法，难以个性化 | 多策略灵活组合，动态权重调整 |
- 电商推荐 → "因为你在该品类有多次购买记录，推荐相似高评分商品"
- 内容推荐 → "因为你关注的技术主题，推荐相关深度文章"
- 服务推荐 → "基于你的使用偏好，推荐匹配的服务方案"
- 投资推荐 → "基于风险评估和因果分析，推荐投资组合"
OpenXRec 继承五层智能体架构，针对推荐场景进行了特化：
┌─────────────────────────────────────────────────────────────┐
│ 感知层（画像构建） │
│ 用户画像智能体：提取用户兴趣、偏好、行为模式 │
│ 物品画像智能体：提取物品特征、构建物品表示 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 认知层（特征分析） │
│ 特征提取智能体：从用户和物品中提取特征 │
│ 相似度计算智能体：计算用户-物品、物品-物品相似度 │
│ 因果推理智能体：基于因果推断分析推荐影响 │
│ 知识图谱推理智能体：利用知识图谱发现隐式关联 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 决策层（排序决策） │
│ 排序智能体：多因素排序，考虑多样性、新颖性 │
│ 解释生成智能体：生成推荐结果的自然语言解释 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 优化层（结果优化） │
│ 多样性优化智能体：优化推荐结果的多样性 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 进化层（持续学习） │
│ 反馈收集智能体：收集用户反馈，分析偏好变化 │
│ 配置优化智能体：基于反馈动态调整推荐配置 │
└─────────────────────────────────────────────────────────────┘
用户请求 → 用户画像分析 → 候选召回 → 特征提取 → 多策略评分
↓ ↓ ↓ ↓ ↓
上下文 兴趣偏好 相关物品 相似度计算 内容/协同/知识图谱/因果
↓
排序 + 多样性优化
↓
解释生成 → 返回结果
支持多种推荐策略的灵活组合：
| 策略 | 说明 | 适用场景 |
|---|---|---|
| 基于内容 | 基于物品特征的相似度匹配 | 新用户冷启动、特征丰富的物品 |
| 协同过滤 | 基于用户行为的协同推荐 | 有行为数据的老用户 |
| 知识图谱驱动 | 利用知识图谱发现隐式关联 | 需要深度关联发现的场景 |
| 智能体驱动 | 多智能体协作决策推荐 | 复杂推荐场景 |
| 因果推断驱动 | 基于因果推断的推荐分析 | 需要解释因果关系的场景 |
每个推荐结果都附带自然语言解释：
{
"item": { "id": "item-001", "title": "商品A" },
"score": 0.92,
"explanations": [
{
"type": "feature_similarity",
"reason": "该商品与你浏览过的商品在价格区间、品牌定位上高度相似",
"factors": [
{ "name": "价格区间", "value": "200-300元", "importance": 0.8 },
{ "name": "品牌定位", "value": "中高端", "importance": 0.6 }
]
},
{
"type": "collaborative",
"reason": "与你兴趣相似的用户中，85%对该商品给了好评",
"weight": 0.3
}
]
}系统持续从用户反馈中学习：
用户行为 → 反馈收集 → 效果分析 → 配置优化 → 推荐调整
↓ ↓ ↓ ↓ ↓
click 缓冲聚合 LLM分析 权重更新 实时生效
like 批量触发 统计计算 阈值调整
purchase 持续积累 趋势识别 策略切换
完整的推荐质量评估框架：
| 指标 | 说明 |
|---|---|
| Precision@K | 前K个推荐的精确率 |
| Recall@K | 前K个推荐的召回率 |
| NDCG@K | 考虑排序位置的归一化指标 |
| MAP | 平均精确率均值 |
| Diversity | 推荐结果多样性 |
| Novelty | 推荐结果新颖性 |
| Serendipity | 推荐结果惊喜性 |
- Node.js 18+
- pnpm（包管理器）
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 构建
pnpm build
# 生产运行
pnpm start推荐与知识向量等能力依赖 Postgres（含 pgvector）。匿名 API 密钥不能执行 DDL，需要在 .env.local 中配置数据库直连（任选其一）：
SUPABASE_DB_URL=postgresql://postgres:数据库密码@db.xxx.supabase.co:5432/postgres- 或
DATABASE_URL=…（同上含义）
连接串在 Supabase Dashboard → Project Settings → Database → Connection string（URI）中复制，将 [YOUR-PASSWORD] 换成项目的数据库密码。
在项目根目录执行：
pnpm db:migrate脚本会按顺序执行 supabase/migrations/000_pre_vector_cleanup.sql、supabase/init.sql 及 002–006 迁移（定义见 scripts/supabase-sql-sources.ts）。策略与触发器在重复执行前会先 DROP … IF EXISTS，便于在同一库上多次跑迁移。
若本机无法稳定直连数据库（超时、被断开），可生成合并 SQL 后在控制台执行：
pnpm db:sql-bundle
# 将生成的 supabase/migrate-all-for-sql-editor.sql 粘贴到 Dashboard → SQL Editor → Run向量维度：表结构与嵌入维度需一致；若更换嵌入模型维度，请同步调整迁移中的 vector(n) / 相关索引，并在 .env.example 中查阅 OPENXREC_PGVECTOR_DIMENSION 的说明后配置到 .env.local。
# 生成推荐
curl -X POST http://localhost:5000/api/recommendation \
-H "Content-Type: application/json" \
-d '{
"userId": "user-001",
"scenario": "product_recommendation",
"limit": 10,
"options": {
"enableExplanation": true,
"enableDiversity": true
}
}'
# 序列推荐
curl -X POST http://localhost:5000/api/recommendation/sequential \
-H "Content-Type: application/json" \
-d '{
"userId": "user-001",
"behaviors": ["view", "click", "purchase"]
}'- 在首页输入需求（可上传文本文档作为上下文）。
- 系统先做信息充足度判断，不足时返回追问问题。
- 推荐生成后可查看：
- 证据链（KG 关联/因果线索/因果证据/用户匹配点）
- 多推荐对比说明
- 点击“有帮助 / 不相关”提交显式反馈。
- 短时间重复问题会优先命中短 TTL 缓存（默认 5 分钟）。
- 若缓存未命中，会尝试向量相似案例复用（带相似度标识）。
- 命中复用后，可点击“完整重算”强制走全量推荐流程（
forceRefresh=true）。
- 反馈接口支持意见文本意图识别：修正 / 认可 / 反对 / 要求说明。
- 修正意见不会直接改知识事实，而是进入候选审查池（管理员审核后应用）。
- 认可/反对会进入推荐反馈记忆，并可作为 PPO 优化反馈信号（用于策略闭环学习）。
文档上传后进入知识层前，遵循以下流程：
- 抽取：LLM 抽取候选知识条目（先不直接入知识层）。
- 归一化：标题/内容/标签/来源标准化。
- 置信度：按阈值过滤低可信条目。
- 冲突检测：高相似但语义冲突条目进入冲突候选。
- 可追溯来源：记录 trace/doc 标记，门禁通过后才写入知识层。
src/
├── app/ # 页面路由
│ ├── api/ # API 路由
│ │ ├── admin/review/ # 管理员审核
│ │ ├── analyze*/ # 分析相关
│ │ ├── auth/ # 认证
│ │ ├── cases/ # 案例
│ │ ├── causal/ # 因果推理
│ │ ├── chat/ # 聊天
│ │ ├── knowledge-graph/ # 知识图谱
│ │ ├── knowledge/ # 知识管理
│ │ ├── memory/ # 记忆
│ │ ├── quality/ # 质量评估
│ │ ├── recommendation/ # 推荐
│ │ └── ...
│ ├── admin/ # 管理页面
│ ├── dashboard/ # 仪表盘
│ ├── knowledge/ # 知识页面
│ └── recommendation/ # 推荐页面
├── components/ # 共享组件
│ ├── ui/ # UI 组件（shadcn/ui）
│ ├── auth/ # 认证组件
│ ├── knowledge/ # 知识组件
│ ├── quality/ # 质量评估组件
│ ├── recommendation-cards/ # 推荐卡片组件
│ ├── memory/ # 记忆组件
│ ├── user/ # 用户组件
│ ├── chat/ # 聊天组件
│ ├── analyze/ # 分析组件
│ ├── evolution/ # 演化组件
│ ├── graph/ # 图谱组件
│ ├── simulation/ # 模拟组件
│ ├── research/ # 研究组件
│ ├── cases/ # 案例组件
│ ├── docs/ # 文档组件
│ └── *.tsx # 根级组件（OpenXRecHome, ClientTabs 等）
├── hooks/ # 自定义 Hooks
├── lib/ # 工具库
│ ├── agents/ # 智能体
│ ├── knowledge-graph/ # 知识图谱
│ ├── recommendation/ # 推荐引擎
│ │ ├── ppo/ # PPO 优化
│ │ └── reflection/ # 反思机制
│ ├── tools/ # 工具系统
│ └── ...
├── contexts/ # React Context
├── storage/database/ # 数据库配置
└── types/ # 类型定义
- 架构要点：五层智能体（感知->认知->决策->优化->进化），推荐主链支持 KG 与因果协同。
- 交互要点：推荐结果统一展示在“推荐结果”区域，支持证据链分段与一键完整重算。
- 推荐引擎：支持多策略融合、复杂度编排、解释生成与多样性优化。
- 调度策略：简单请求走轻链路，复杂请求启用 KG/因果/多样性等完整链路。
- 知识图谱：动态类型注册表、自动配色、可确认固化、同名合并与本地交互修复。
为提升知识图谱可解释性与交互体验，近期已完成以下改动：
- 动态类型优先：图例与节点/关系标签优先展示抽取得到的动态类型标签。
- 类型注册表：新增
config/knowledge-graph/type-registry.json，持续积累动态发现类型（非 TS 硬编码）。 - 自动配色：实体/关系按动态标签稳定哈希配色，不同类型自动区分颜色。
- 交互恢复：修复节点拖拽回弹问题，恢复点击后“编辑/确认”快捷操作。
- 非阻断提示：知识图谱确认/编辑结果不再使用浏览器
alert，避免打断操作流程。 - 增量合并修复：抽取增量合并时按名称重映射关系端点到稳定实体 ID，减少“节点/关系丢失”现象。
欢迎贡献代码、报告问题或提出建议。最小流程如下：
- 提交前确认
pnpm dev可运行、关键路径无报错。 - 功能改动请附简短说明：改动目的、影响范围、验证方式。
- 若涉及数据结构或 API 变更，请在本 README 同步更新最小使用说明。
MIT License
OpenXRec 基于多智能体协作架构开发，继承了 LangGraph 智能体编排能力，感谢相关开源项目的贡献。