# Python 调用 Dify chat-messages（后端示例）

本文档用于指导在后端实现真正的 Dify `POST /v1/chat-messages` 调用。

## 脚本入口

- 脚本路径：`scripts/MCN_CYLG_API.py`

## 1) 环境变量配置（必填）

- `DIFY_MCN_CYLG_KEY`: 创意灵感技能专用 KEY（必须，通过系统环境变量设置）
- `DIFY_MCN_MODEL`: 模型名称（可选，默认为 `gemini`）
- `DIFY_URL`: Dify 接口基础地址（可选，默认为 `https://mydify.youmanvideo.com/v1`）

> 密钥通过系统环境变量注入，不要在 Skill 目录或代码仓库中存放 `.env.local` 文件。

> ⚠️ 注意：该接口无需 `app_id`，请求体中不要传该字段，否则 CDN 会 400 拦截。另外 curl 发中文 query 也会被 CDN 拦截，推荐用 Python 调用。

---

## 2) 两种调用模式

脚本支持两种子命令模式，分别对应不同的信息获取方式：

| 模式 | 子命令 | `is_online` | 提示词前缀 | 输入参数 | 适用场景 |
|:---:|:---:|:---:|------|------|------|
| **联网搜索** | `search` | `1` | `联网搜索` | 创作意图 + 搜索内容 | 查热词释义、最新热点、时事话题、竞品趋势 |
| **查询事件库** | `recall` | `0` | `查询事件库` | 创作意图 + 搜索标签 + 搜索内容 | 查询事件库中的创作知识、爆款案例、框架模板 |

### 模式一：联网搜索（search）

**输入参数：**
- `--intent`：创作意图（账号定位、视频目标、赛道方向等）
- `--content`：需要搜索的内容（热词释义、热点趋势、竞品分析等）

**query 构造格式：**
```
联网搜索
创作意图：{intent}
搜索内容：{content}
```

**调用示例：**
```bash
$env:DIFY_MCN_CYLG_KEY="app-xxxx"
python scripts/MCN_CYLG_API.py search `
  --intent "为萌宠账号写一个猫咪应激的搞笑短视频" `
  --content "抖音上'耄耋猫'是什么梗，有哪些爆款视频" `
  --timeout 300
```

### 模式二：查询事件库（recall）

**输入参数：**
- `--intent`：创作意图（账号定位、视频目标、赛道方向等）
- `--tags`：搜索标签（逗号分隔的关键词，用于事件库检索匹配，如 `萌宠,搞笑,应激,反差萌`）
- `--content`：搜索内容（需要查询的具体事件/知识描述）

**query 构造格式：**
```
查询事件库
创作意图：{intent}
搜索标签：{tags}
搜索内容：{content}
```

**调用示例：**
```bash
$env:DIFY_MCN_CYLG_KEY="app-xxxx"
python scripts/MCN_CYLG_API.py recall `
  --intent "为萌宠账号写一个猫咪应激的搞笑短视频" `
  --tags "萌宠,搞笑,应激,反差萌" `
  --content "猫咪应激反应的表现和常见搞笑场景" `
  --timeout 300
```

---

## 3) 接口信息（Dify chat-messages）

- URL: `https://mydify.youmanvideo.com/v1/chat-messages`
- Method: `POST`
- Headers：
  - `Authorization: Bearer <MCN_KEY>`
  - `Content-Type: application/json`

### 请求体结构

```json
{
  "inputs": {
    "is_think": "0",
    "is_online": "1",
    "model": "gemini"
  },
  "query": "联网搜索\n创作意图：...\n搜索内容：...",
  "response_mode": "blocking",
  "user": "用户唯一标识"
}
```

### 参数含义

| 参数 | 位置 | 含义 | search 模式 | recall 模式 |
|------|:---:|------|:---:|:---:|
| `is_online` | `inputs` | 是否联网搜索 | 固定 `"1"` | 固定 `"0"` |
| `is_think` | `inputs` | 是否深度思考（复杂剧情/多反转用 `"1"`） | 可选 | 可选 |
| `model` | `inputs` | 模型名称（默认 `gemini`） | 可选 | 可选 |
| `query` | body | 组装后的完整提示词 | 脚本自动构造 | 脚本自动构造 |
| `response_mode` | body | `blocking`（同步）或 `streaming`（流式） | 默认 `blocking` | 默认 `blocking` |
| `user` | body | 用户唯一标识 | 可选 | 可选 |

---

## 4) 命令行参数对照

### 公共参数（两种模式通用）

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--is-think` | 是否深度思考 (0/1) | `0` |
| `--model` | 模型名称 | `gemini` |
| `--response-mode` | 响应模式 (blocking/streaming) | `blocking` |
| `--user` | 用户唯一标识 | `wb-skill-001` |
| `--timeout` | HTTP 超时（秒） | `1200` |

### search 模式专属参数

| 参数 | 说明 | 必填 |
|------|------|:---:|
| `--intent` | 创作意图（账号定位、视频目标等） | ✅ |
| `--content` | 需要搜索的内容（热词释义、热点趋势等） | ✅ |

### recall 模式专属参数

| 参数 | 说明 | 必填 |
|------|------|:---:|
| `--intent` | 创作意图（账号定位、视频目标等） | ✅ |
| `--tags` | 搜索标签（逗号分隔关键词） | ✅ |
| `--content` | 需要查询的事件/知识描述 | ✅ |

---

## 5) 返回值说明

脚本输出 API 原始 JSON 响应，关键字段：

| 字段 | 含义 |
|------|------|
| `answer` | LLM 生成的回答正文（创作流程中实际使用的内容） |
| `conversation_id` | 会话 ID，传回可续接多轮对话 |
| `metadata.usage` | token 消耗与费用 |
| `metadata.retriever_resources` | RAG 检索引用资源（recall 模式下可能有值） |

---

## 6) 调试示例（终端测试，可选）

```bash
# 联网搜索（search）
curl -X POST 'https://mydify.youmanvideo.com/v1/chat-messages' \
  --header "Authorization: Bearer $DIFY_MCN_CYLG_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": { "is_think": "0", "is_online": "1", "model": "gemini" },
    "query": "联网搜索\n创作意图：为萌宠账号写猫咪应激搞笑短视频\n搜索内容：抖音耄耋猫是什么梗",
    "response_mode": "blocking",
    "user": "demo-user-001"
  }'

# 查询事件库（recall）
curl -X POST 'https://mydify.youmanvideo.com/v1/chat-messages' \
  --header "Authorization: Bearer $DIFY_MCN_CYLG_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": { "is_think": "0", "is_online": "0", "model": "gemini" },
    "query": "查询事件库\n创作意图：为萌宠账号写猫咪应激搞笑短视频\n搜索标签：萌宠,搞笑,应激,反差萌\n搜索内容：猫咪应激反应的表现和搞笑场景",
    "response_mode": "blocking",
    "user": "demo-user-001"
  }'
```

---
## 7) 选题搜索的内容设计原则（三层递进）

> ⚠️ **搜索输入决定选题边界。** `content` 和 `tags` 中的行为词会锁定 Dify 的输出方向。

### content 字段设计规则

| 规则 | 说明 |
|------|------|
| ❌ 禁止 | `content` 中出现账号核心行为词超过 1 次（如账号核心行为是做饭，则"做饭""美食""下厨"不应同时出现） |
| ✅ 第1层 | 可含 1 次核心行为词，确认框架内可能性 |
| ✅ 第2层起 | 去掉所有行为词，改用**场景词 + 互动类型词**（如"露营 亲子互动 户外挑战"） |
| 🔄 第3层 | 更换视角关键词（如"露营教育""露营角色反转""露营环保"） |

### 反例 vs 正例（以亲子美食账号搜"露营"为例）

```bash
# ❌ 第1层就把"做饭""美食"写死，Dify 永远在做饭框架里打转
--content "露营美食爆款选题 亲子露营做饭 小学生野外做饭"

# ✅ 第1层：框架内探索（可含1次做饭）
--content "亲子露营爆款选题 露营美食创意 小学生露营内容"

# ✅ 第2层：跳出框架（去掉做饭，场景驱动）
--content "亲子露营互动创意 露营意外搞笑 户外亲子挑战 露营趣味内容"

# ✅ 第3层：近一步跳出框架（换视角）
--content "露营教育亲子对话 露营角色反转 无电子设备露营 露营环保正能量"
```

### tags 字段同理（recall 模式）

```bash
# ❌ 标签自带锁定
--tags "露营,美食,亲子,反差萌,户外做饭"

# ✅ 场景驱动标签
--tags "露营,亲子,互动,挑战,搞笑,教育,情感,户外"
```

> 该原则同步写入 `创作流程/5_生成短视频选题.md` 处理规则「联网搜索策略 — 三层递进」。