# Step3 灵感点生成脚本说明

## 概述

Step3 用于从锚点分类推导出具体的灵感点。有两种运行方式：

1. **run_step3_from_folder.py** (推荐) - 直接从灵感点文件夹读取
2. **run_step3_from_analysis.py** - 从分析文件读取

---

## 方式1: run_step3_from_folder.py (推荐)

### 输入
- **直接扫描**：`data/.../how/灵感点/` 文件夹
- **自动读取**：每个灵感的 `*_step1_*_gemini-2.5-pro.json` 文件

### 工作流程
1. 扫描灵感点文件夹，收集所有 step1 结果
2. 提取每个灵感的 top1 匹配的 score
3. 按 score 降序排序
4. 筛选出 score 在指定范围内的灵感
5. 对每个灵感执行 step3 生成新灵感点

### 使用方法

```bash
# 测试：处理前3个符合条件的灵感
python run_step3_from_folder.py --count 3

# 处理所有符合条件的灵感（score 0.5-0.8）
python run_step3_from_folder.py --force

# 自定义 score 范围
python run_step3_from_folder.py --min-score 0.6 --max-score 0.9 --force

# 查看会处理哪些灵感（不加 --force 就是预览）
python run_step3_from_folder.py --count 10
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--dir` | 人设目录路径 | `data/阿里多多酱/out/人设_1110` |
| `--min-score` | step1 score 最小值（含） | `0.5` |
| `--max-score` | step1 score 最大值（含） | `0.8` |
| `--count` | 处理数量限制 | 无限制 |
| `--force` | 强制重新执行 | False |

### 输出示例

```
找到 32 个灵感（有 step1 结果）
找到 3 个符合条件的灵感（已应用数量限制）:

  1. 品牌产品植入需求 (score: 0.75)
  2. 女性生理期关怀需求 (score: 0.68)
  3. 打工人emo情绪 (score: 0.67)

统计:
  总数: 3
  成功: 2
  跳过: 1
  失败: 0
```

---

## 方式2: run_step3_from_analysis.py

### 输入
- **分析文件**：`data/.../how/灵感匹配分析.json`
- **需要先运行**：`analyze_inspiration_results.py`

### 工作流程
1. 读取灵感匹配分析文件
2. 从 `排序结果` 中筛选 step1 score 符合条件的灵感
3. 对每个灵感执行 step3

### 使用方法

```bash
# 使用默认参数
python run_step3_from_analysis.py --count 1

# 自定义参数
python run_step3_from_analysis.py --min-score 0.6 --max-score 0.9 --force
```

---

## 生成的输出

### 输出文件位置
```
data/.../how/灵感点/{灵感名称}/all_step3_top1_生成灵感_gemini-2.5-pro.json
```

### 输出文件结构
```json
{
  "元数据": {
    "current_time": "...",
    "log_url": "...",
    "model": "google/gemini-2.5-pro",
    "步骤": "Step3: 从锚点分类推导灵感点",
    "step1_匹配索引": 1
  },
  "锚点信息": {
    "锚点分类": "商业合作的要求",
    "分类定义": "...",
    "分类上下文": "..."
  },
  "step1_结果": { ... },
  "灵感点列表": [
    {
      "推理路径": "[锚点分类] → [思维方向] → [联想节点] → [灵感点]",
      "灵感点": "具体的刺激源描述（≤15字）",
      "描述": "对刺激源本身的客观说明"
    }
  ]
}
```

---

## 核心概念

### 锚点分类（维度）
创作者接收外界信息刺激的角度或通道，来自人设体系中的分类节点。

### 灵感点
创作前遇到的、触发创作冲动的客观刺激源：
- **本质**：被动接收的信息（看到的、听说的、发现的、观察到的）
- **格式**：不超过15字，口语化表达
- **要求**：避免学术化、抽象化词汇堆砌

### 推理路径
展示从锚点分类到灵感点的推导过程：
```
[锚点分类] → [思维方向] → [联想节点] → [灵感点]
```

### 描述
对刺激源本身的详细说明：
- 描述刺激源的具体特征、形态、场景、内容
- 注意区分：刺激源内容本身 vs 呈现方式/表现形式

---

## 质量检查

生成后会自动输出统计信息：
- 生成灵感点数量
- 字段完整性检查
- 灵感点字数统计（平均、最长、超标数量）
- ⚠️ 警告超过15字的灵感点

---

## 常见问题

### Q: 为什么选择 score 0.5-0.8？
A:
- score 太高（>0.8）：灵感与人设要素几乎完全匹配，不需要再扩展
- score 太低（<0.5）：灵感与人设要素差异太大，生成质量可能不好
- score 中等（0.5-0.8）：有一定相关性但不完全重合，适合扩展生成

### Q: 两种方式有什么区别？
A:
- **run_step3_from_folder.py**: 直接读取文件夹，无需依赖分析文件，更灵活
- **run_step3_from_analysis.py**: 需要先运行分析脚本，适合已有分析结果的情况

### Q: 如何批量处理所有符合条件的灵感？
A:
```bash
python run_step3_from_folder.py --force
```

### Q: 生成的灵感点不符合要求怎么办？
A: 检查以下几点：
1. 灵感点是否 ≤15字
2. 灵感点是否口语化
3. 描述是否客观（没有涉及如何创作/运用）
4. 推理路径是否清晰

如有问题，可以调整 prompt 或重新生成。