diff --git a/AGENTS.md b/AGENTS.md index 2107241..fd6e892 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -136,7 +136,72 @@ AdminPage.tsx / schema.prisma 里出现的 `100.111.84.16:3002/mcp` 是 MCP serv ## 数据库模型 -User, Lead(含 AI 评分/状态流转/跟进日志), Rule/RuleVersion, Report, AuditLog, CrawlerConfig(含 keywords/categories + cron schedule), Inquiry, Product(含 supplier/imageUrl), GeneratedImage +User, Lead(含 AI 评分/状态流转/跟进日志), Rule/RuleVersion, Report, AuditLog, CrawlerConfig(含 keywords/categories + cron schedule), Inquiry, Product(含 supplier/imageUrl), GeneratedImage, **ProductCategory**(品类字典,AI 关键词反哺用) + +## 品类方案 C(关键词优先 + AI 反哺,2026-07-01) + +### 数据模型 + +`ProductCategory` 表: +- `name`:品类名(2-6 中文字,唯一) +- `keywords`:JSON 数组,关键字列表 +- `isAIGenerated`:AI 自动创建标记(人工 review 后可改 false) + +### 分类逻辑 + +``` +1. 采集器入库 / 手动回填时,对每条线索标题做: + 关键词匹配(ProductCategory.keywords contains 标题)→ 命中直接写 + ↓ 未命中 + MiniMax API 分类 → 写品类 + 反写关键词到 ProductCategory +2. 同类标题下次直接走关键词,不再调 AI +``` + +### 关键代码路径 + +| 文件 | 说明 | +|------|------| +| `apps/api/prisma/schema.prisma` | `ProductCategory` model | +| `apps/api/src/product-category/` | CRUD + 关键词匹配 service | +| `apps/api/src/product-category/category-inference.service.ts` | AI 推断 + 反写关键词 | +| `apps/api/src/crawler/crawler.service.ts` | 采集入库用 `batchInfer()` | +| `apps/api/src/crawler/notes-extractor.service.ts` | PDF/HTML 提取要点也走 AI | +| `apps/web/src/components/InquiryPage.tsx` | 品类筛选项动态从 `/api/categories` 加载 | + +### LLM 配置(DeepSeek → MiniMax 迁移) + +- endpoint:`https://api.minimaxi.com/v1/chat/completions` +- model:`MiniMax-M2.7`(env `MINIMAX_MODEL` 可覆盖) +- env:`MINIMAX_API_KEY` 写入 `apps/api/.env`(生产已配) +- **注意**:M2.7 是推理模型,max_tokens 要 ≥500 才够(否则全被 吃掉) +- 生产 `.env` 同时保留 `MINIMAX_API_KEY` 和 `MINIMAX_MODEL` 两个变量 + +### 历史回填策略(重要:AI 不可全信) + +2026-07-01 用 MiniMax 回填了 507 条历史空品类线索,结果: +- ✅ 命中:693/761(91%)已分配品类 +- ⚠️ AI 自动新建 ~25 个细分类,需要人工 review 合并/删除 +- ❌ 68 条空品类线索(重要数据手动指定,非重要忽略) + +**决策(用户)**:停止继续调 AI 回填剩余数据。原因: +- 单条 API 推理模型耗时大(500 tokens 给思考留空间) +- AI 输出容易混入 ``、`让我分析`、`**加粗**` 等解释文字 +- 关键词匹配已能覆盖新采集数据,老数据人工 review 更可靠 + +### 后续流程 + +- **新采集数据**:自动走关键词匹配(15 个初始品类 + 已入库的 ~25 个细分类) +- **AdminPage → 品类管理**:用户手动 review AI 新建的细分类(合并到已有大类、删除不合理的) +- **空品类历史线索**:用户从详情面板手动指定,或忽略(过期数据) +- **新增采集场景需要新关键词**:编辑 `ProductCategory.keywords` 字段(AdminPage 或直接 SQL) + +### 数据维护脚本 + +| 脚本 | 用途 | +|------|------| +| `scripts/backfill_category.js` | 批量回填空品类(已停止使用,仅供参考) | +| `scripts/clean_category.js` | 清理 AI 输出脏值(``、`**加粗**`、` - 描述`、解释行) | +| `scripts/deploy.sh` | 部署时自动同步上述脚本到生产 | ## 采集器关键事实