# CLAUDE.md

## 项目概述

这是一个基于LLM的智能搜索系统，用于小红书内容搜索场景。系统通过多阶段处理流程（7个步骤），从原始特征出发，自动生成、评估和执行搜索任务。核心功能包括特征匹配、关联分析、智能搜索词生成、并发搜索执行、LLM评估、深度解构和相似度分析。

## 概念定义

### 核心术语
- **选题点**：帖子中灵感点列表下的名称、目的点列表下的名称、关键点列表下的名称
- **人设特征/分类**：作者多个帖子的聚合结果，在输入文件"匹配人设结果"结构下，命名是"人设特征名称"，相似度得分是指这些选题点和人设各个特征点的匹配度
- **候选词**：相似度 ≥ 0.8 的��设特征名称，或符合条件的帖子点名称
- **Base Word**：中心词，用于组织和生成搜索词的基础词汇
- **完全匹配**：LLM评估得分 ≥ 0.8 的搜索结果

### 维度分类
- **灵感点**：全新内容、共性差异、共性内容（实质/形式/意图）
- **目的点**：用户目的和意图
- **关键点**：关键特征和要素

## 数据流程与结构

### 流程概览
```
输入: how.json
  ↓
步骤1: 特征筛选 → filtered_features.json
  ↓
步骤2: 候选词提取 → candidate_words.json
  ↓
步骤3: 搜索词生成(LLM) → search_queries_evaluated.json
  ↓
步骤4: 执行搜索(小红书API) → search_results.json
  ↓
步骤5: 结果评估(LLM两层过滤) → evaluated_results.json
  ↓
步骤6: 深度解构(可选) → deep_analysis_results.json
  ↓
步骤7: 相似度分析(可选) → similarity_analysis_results.json
  ↓
可视化: HTML交互式界面
```

### 输入数据结构: how.json

**位置**: `input/posts/{post_id}_how.json`

**核心字段**:
```json
{
  "帖子id": "690d977d0000000007036331",
  "帖子详情": {
    "link": "https://www.xiaohongshu.com/explore/...",
    "title": "帖子标题",
    "body_text": "帖子正文",
    "images": ["图片URL1", "图片URL2"],
    "like_count": 7428,
    "collect_count": 368,
    "channel_account_name": "作者名称"
  },
  "解构结果": {
    "灵感点列表": [
      {
        "ID": "inspiration_1",
        "名称": "猫咪考试祝福",
        "类型": "实质",
        "描述": "详细描述...",
        "置信度": 0.95,
        "匹配人设结果": [
          {
            "人设特征名称": "鼓励式猫咪表情包",
            "人设特征层级": "灵感点",
            "特征类型": "标签",           // 或 "分类"
            "特征分类": ["表情包素材", "日常生活演绎", "实质"],
            "相似度": 0.5339,
            "说明": "相似度计算说明..."
          }
        ]
      }
    ],
    "目的点列表": [...],
    "关键点列表": [...]
  }
}
```

### 步骤1输出: filtered_features.json

**筛选条件**: 0.5 ≤ 最高相似度 < 0.8

```json
[
  {
    "原始特征名称": "猫咪考试祝福",
    "来源层级": "灵感点列表",
    "权重": 1.0,
    "所属点名称": "猫咪考试祝福",
    "最高匹配信息": {
      "人设特征名称": "鼓励式猫咪表情包",
      "人设特征层级": "灵感点",
      "特征类型": "标签",
      "相似度": 0.5339,
      "是分类": false,
      "所属分类路径": "表情包素材/日常生活演绎/实质"
    },
    "top3匹配信息": [...]
  }
]
```

### 步骤2输出: candidate_words.json

**候选词来源**:
1. 人设候选词: 相似度 ≥ 0.8 的人设特征
2. 帖子候选词: 点名称（该点最高相似度 ≥ 0.8）

```json
[
  {
    "原始特征名称": "猫咪考试祝福",
    "来源层级": "灵感点列表",
    "高相似度候选_按base_word": {
      "鼓励式猫咪表情包": [
        {
          "候选词": "鼓励式猫咪表情包",
          "候选词类型": "persona",    // 或 "post"
          "相似度": 0.85,
          "特征类型": "标签",
          "人设特征层级": "灵感点",
          "来源层级": "persona",
          "来源路径": "表情包素材/日常生活演绎/实质",
          "来源原始特征": "猫咪考试祝福"
        }
      ]
    }
  }
]
```

### 步骤3输出: search_queries_evaluated.json

**生成方式**: LLM基于中心词(base_word)和候选词生成搜索词

```json
[
  {
    "原始特征名称": "猫咪考试祝福",
    "组合评估结果_分组": [
      {
        "base_word": "鼓励式猫咪表情包",
        "base_word_similarity": 0.5339,
        "base_word_info": {...},
        "top10_searches": [
          {
            "search_word": "鼓励式猫咪表情包 考试祝福",
            "score": 0.92,
            "reasoning": "组合词很好地结合了中心词和候选词...",
            "source_word": "鼓励式猫咪表情包",
            "original_feature": "猫咪考试祝福"
          }
        ],
        "available_words": ["鼓励式猫咪表情包", "考试祝福", ...]
      }
    ]
  }
]
```

### 步骤4输出: search_results.json

**数据来源**: 小红书搜索API

```json
[
  {
    "原始特征名称": "猫咪考试祝福",
    "组合评估结果_分组": [
      {
        "base_word": "鼓励式猫咪表情包",
        "top10_searches": [
          {
            "search_word": "鼓励式猫咪表情包 考试祝福",
            "search_result": {
              "data": {
                "data": [
                  {
                    "id": "note_id_123",
                    "note_card": {
                      "display_title": "考试祝福表情包",
                      "type": "normal",         // 或 "video"
                      "image_list": ["http://..."],
                      "user": {
                        "nickname": "用户昵称",
                        "user_id": "..."
                      },
                      "interact_info": {
                        "liked_count": "1234",
                        "collected_count": "56"
                      }
                    }
                  }
                ]
              }
            },
            "search_metadata": {
              "searched_at": "2025-01-01T12:00:00",
              "status": "success",
              "note_count": 20
            }
          }
        ]
      }
    ]
  }
]
```

### 步骤5输出: evaluated_results.json

**评估机制**: LLM两层过滤
1. 第一层: 过滤与Query无关的结果
2. 第二层: 评估与目标特征的匹配度

```json
[
  {
    "原始特征名称": "猫咪考试祝福",
    "组合评估结果_分组": [
      {
        "base_word": "鼓励式猫咪表情包",
        "top10_searches": [
          {
            "search_word": "鼓励式猫咪表情包 考试祝福",
            "search_result": {...},
            "evaluation_with_filter": {
              "total_notes": 20,
              "filtered_count": 5,         // 第一层过滤: 与Query无关
              "evaluated_count": 15,       // 第二层评估数量
              "statistics": {
                "完全匹配(0.8-1.0)": 8,
                "相似匹配(0.6-0.79)": 4,
                "弱相似(0.5-0.59)": 2,
                "无匹配(≤0.4)": 1
              },
              "notes_evaluation": [
                {
                  "note_index": 0,
                  "note_id": "note_id_123",
                  "Query相关性": "相关",     // 或 "不相关"
                  "Query相关性说明": "...",
                  "综合得分": 0.85,
                  "评分说明": "...",
                  "关键匹配点": ["考试祝福", "猫咪表情包"]
                }
              ]
            }
          }
        ]
      }
    ]
  }
]
```

### 步骤6输出: deep_analysis_results.json (可选)

**触发条件**: 评估得分 ≥ min_score (默认0.8) 且评估类型为"完全匹配"

```json
{
  "metadata": {
    "stage": "deconstruction",
    "post_id": "690d977d0000000007036331",
    "total_matched_notes": 50,
    "processed_notes": 45,
    "success_count": 40,
    "min_score_threshold": 0.8,
    "created_at": "2025-01-01T12:00:00"
  },
  "results": [
    {
      "note_id": "note_id_123",
      "search_word": "鼓励式猫咪表情包 考试祝福",
      "original_feature": "猫咪考试祝福",
      "evaluation_score": 0.85,
      "evaluation_type": "完全匹配",
      "key_matching_points": ["考试祝福", "猫咪表情包"],
      "inspiration_features": [
        {
          "feature_name": "考试祝福主题",
          "dimension": "灵感点-全新内容",
          "dimension_detail": "实质",
          "weight": 0.8,
          "source_index": 0,
          "source_candidate_number": 1
        }
      ],
      "purpose_features": [...],
      "key_point_features": [...],
      "api_response": {
        "result": {
          "data": {
            "三点解构": {
              "灵感点": {
                "全新内容": [...],
                "共性差异": [...],
                "共性内容": [...]
              },
              "目的点": {...},
              "关键点": {...}
            }
          }
        }
      }
    }
  ]
}
```

### 步骤7输出: similarity_analysis_results.json (可选)

**计算公式**:
- 混合相似度 = weight_embedding × embedding_score + weight_semantic × semantic_score
- 综合得分P = Σ(评估分 × 最高相似度) / 总帖子数

```json
{
  "metadata": {
    "stage": "similarity_analysis",
    "weight_embedding": 0.5,
    "weight_semantic": 0.5,
    "min_similarity": 0.0,
    "created_at": "2025-01-01T12:00:00"
  },
  "results": [
    {
      "note_id": "note_id_123",
      "original_feature": "猫咪考试祝福",
      "features_similarity": [
        {
          "feature_name": "考试祝福主题",
          "dimension": "灵感点-全新内容",
          "dimension_detail": "实质",
          "weight": 0.8,
          "similarity_score": 0.75,
          "similarity_breakdown": {
            "embedding_score": 0.80,   // 向量模型
            "semantic_score": 0.70,    // LLM模型
            "weighted_score": 0.75     // 加权平均
          },
          "original_feature": "猫咪考试祝福"
        }
      ],
      "statistics": {
        "total_features": 5,
        "avg_similarity": 0.72,
        "max_similarity": 0.85,
        "min_similarity": 0.60
      }
    }
  ],
  "综合得分P": 0.78  // 可选，需要启用 calculate_comprehensive_score
}
```

## 项目架构

### 目录结构
```
optimization/
├── lib/                    # 核心功能库
│   ├── client.py          # API客户端
│   ├── data_loader.py     # 数据加载
│   ├── match_analyzer.py  # 匹配分析
│   ├── relation_analyzer.py # 关联分析
│   ├── semantic_similarity.py # 语义相似度
│   ├── hybrid_similarity.py # 混合相似度(向量+LLM)
│   └── utils.py           # 工具函数
├── src/                    # 主要源代码
│   ├── pipeline/          # 流程控制
│   ├── analyzers/         # 分析器(解构/相似度)
│   ├── evaluators/        # 评估器(LLM)
│   ├── clients/           # API客户端
│   └── visualizers/       # 可视化生成器
├── input/posts/           # 输入数据 (*_how.json)
├── output_v2/             # 输出结果
├── visualization/         # 可视化HTML文件
├── cache/search/          # 搜索缓存
└── logs/                  # 日志文件
```

### 核心模块职责

**数据处理流程**:
1. `EnhancedSearchV2` (src/pipeline/feature_search_pipeline.py) - 主流程控制器
2. `LLMEvaluator` (src/evaluators/llm_evaluator.py) - 搜索词生成和结果评估
3. `PostDeconstructionAnalyzer` (src/analyzers/) - 深度解构分析
4. `SimilarityAnalyzer` (src/analyzers/) - 相似度分析
5. `XiaohongshuSearch` (src/clients/) - 小红书搜索API客户端
6. `OpenRouterClient` (src/clients/) - LLM API客户端

**可视化模块**:
1. `deconstruction_visualizer.py` - 整合可视化（搜索+评估+解构+相似度）

## 运行模式

### 基础模式 (步骤1-4)
```bash
python3 main.py --mode basic
```

### 标准模式 (步骤1-5，默认)
```bash
python3 main.py --mode standard
```

### 完整模式 (步骤1-7)
```bash
python3 main.py --mode full
```

### 自定义控制
```bash
python3 main.py \
  --enable-evaluation \
  --enable-deep-analysis \
  --deep-analysis-min-score 0.9 \
  --enable-similarity \
  --similarity-weight-embedding 0.6
```

## 关键配置参数

### 搜索相关
- `top_n`: 每个特征取评分最高的N个搜索词 (默认10)
- `max_total_searches`: 全局最大搜索次数
- `max_searches_per_feature`: 每个特征的最大搜索次数
- `search_max_workers`: 搜索并发数 (默认3)

### 评估相关
- `enable_evaluation`: 是否启用结果评估
- `evaluation_max_workers`: 评估并发数 (默认10)
- `evaluation_max_notes_per_query`: 每个搜索最多评估的帖子数 (默认20)

### 解构相关
- `enable_deep_analysis`: 是否启用深度解构
- `deep_analysis_min_score`: 最低分数阈值 (默认0.8)
- `deep_analysis_max_workers`: 解构并发数 (默认5)
- `deep_analysis_api_url`: 解构API地址

### 相似度相关
- `enable_similarity`: 是否启用相似度分析
- `similarity_weight_embedding`: 向量模型权重 (默认0.5)
- `similarity_weight_semantic`: LLM模型权重 (默认0.5)
- `similarity_min_similarity`: 最小相似度阈值 (默认0.0)
- `calculate_comprehensive_score`: 是否计算综合得分P

## 严格约束

### 代码修改规范
1. **Prompt保护**: 重构或修改功能代码过程中不要修改任何的原始prompt，如需修改，必须确认授权
2. **可视化更新**: 如果涉及可视化的修改，修改完后直接open打开验证效果
3. **数据结构保持**: 修改代码时必须保持各环节的数据结构兼容性，避免破坏数据流转
4. **并发控制**: 注意并发数限制，避免API限流

### 调试指南
- 应用日志: `logs/app.log`
- 中间结果: `output_v2/*.json` (各步骤的输出文件)
- 缓存位置: `cache/search/*.json` (搜索结果缓存)
- 可视化输出: `visualization/*.html`

### 常见问题
1. **API超时**: 检查网络和API配置，调整重试策略
2. **相似度计算异常**: 检查embedding模型可用性
3. **LLM评估失败**: 检查OpenRouter API密钥和模型可用性
4. **搜索结果为空**: 检查搜索词是否合理，API是否正常
5. **解构失败**: 检查解构API地址和帖子ID有效性

## 数据访问模式

### 可视化数据访问路径

**搜索结果可视化**:
- 统计数据: 遍历所有 `组合评估结果_分组` → `top10_searches` → `evaluation_with_filter`
- 左侧导航: `data[featureIdx]['组合评估结果_分组'][groupIdx]['top10_searches']`
- 右侧结果: `search_result.data.data[noteIdx]`
- 评估详情: `noteEvaluations["featureIdx-groupIdx-swIdx-noteIdx"]`

**解构结果可视化**:
- 评估数据: `evaluated_data[featureIdx]['组合评估结果_分组'][groupIdx]['top10_searches'][swIdx]`
- 解构数据: `deconstruction_mapping[note_id]` (通过note_id关联)
- 相似度数据: `similarity_mapping[note_id]` (通过note_id关联)
- 特征信息: `all_features[feature_name]` (从how.json提取)

### 数据关联关系
- 主键标识符: `note_id` (帖子唯一ID)
- 评估结果 → 解构结果: 通过 `note_id` 匹配
- 评估结果 → 相似度结果: 通过 `note_id` 匹配
- How文件 → 评估结果: 通过 `原始特征名称` 匹配