明日Dmp人群洞察

SKILL.md

---
name: 明日dmp人群洞察
description: 基于明日DMP开放平台API，提供人群洞察分析功能，支持明略洞察（人口属性/兴趣爱好/媒体分析）和合作伙伴洞察（基础标签/地域分布/兴趣偏好/应用偏好/手机偏好/场景偏好/品类偏好），帮助深度理解目标人群特征，优化营销策略。
---

# 明日DMP人群洞察

## 概述

本技能基于明日DMP开放平台API，提供人群洞察分析功能，帮助您深度理解目标人群的特征和行为模式。

⚠️ **重要声明**：
1. **凭证安全责任**：您的 Access Key（AK）和 Secret Key（SK）是访问明日 DMP API 的唯一凭证，属于您的敏感私密信息。您对凭证的妥善保管（包括但不限于防止泄露、撤销权限）负全部责任。因凭证泄露、遗失或不当使用导致的一切损失及法律责任，均由您自行承担。
2. **数据合法性责任**：使用本技能进行人群圈选、洞察、同步、投放等操作时，您须保证所使用的数据来源合法合规，并已取得必要的用户授权。因数据来源违法、侵权或违反相关法律法规所引发的一切法律责任与纠纷，均由您自行承担，本技能开发者不承担任何连带责任。
3. **操作结果责任**：本技能的所有 API 调用结果（包括人群创建、任务状态、数据结果等）均由明日DMP平台提供，本技能开发者对 API 返回内容的准确性、完整性不作任何保证，对因此产生的业务损失不承担责任。
4. **使用即视为同意**：继续使用本技能，即表示您已阅读并同意上述免责声明。


## 工作流程

### 请求类型自动识别

当您发起请求时，系统会自动识别请求类型并进入相应流程：

**1. 技能咨询请求**（"有哪些功能"、"能做什么"）
- 展示2种洞察类型的详细说明
- 直接结束，等待您的下一步需求

**2. 查询任务请求**（"查询洞察任务123456"）
- 直接调用查询脚本
- 展示任务状态（计算中/成功/失败）
- **任务成功时，提供后续操作建议**：
  1. 下载人群圈选技能 - 根据画像特征进一步精准圈选人群
  2. 下载人群投放技能 - 创建广告投放任务
- 直接结束

**3. 获取结果请求**（"获取洞察任务123456的结果"）
- 直接调用获取结果脚本
- **自动生成两种格式的数据文件**：
  - JSON格式：洞察任务{任务ID}_API原始数据.json（保留完整树形结构）
  - Excel格式：洞察任务{任务ID}_完整数据表格.xlsx（包含3个工作表）
- 展示洞察数据和文件下载链接
- 直接结束

**4. 创建洞察请求**（包含人群ID、洞察类型等）
- 进入完整的创建流程（见下方）

### 创建洞察完整流程

**流程执行规则:**
- ✅ 必须执行：第一步~第十步（所有步骤都必须执行）
- ⚠️ **严格禁止跳过任何步骤**，特别是第六步（参数确认）、第八步（检查任务记录技能）和第九步（记录任务历史）
- 📌 **第八步虽然用户可以选择不安装，但必须执行检查和询问流程**

**第一步：请求类型识别** [必须执行]

当用户发起请求时，系统首先识别请求类型：

- **技能咨询请求**（"有哪些功能"、"能做什么"）→ 展示功能说明后结束
- **查询任务请求**（"查询洞察任务123456"）→ 调用查询脚本后结束
- **获取结果请求**（"获取洞察任务123456的结果"）→ 调用获取结果脚本后结束
- **创建洞察请求**（包含"洞察"、"分析"、"画像"等关键词）→ 进入完整的创建流程（第二步~第十步）

**第二步：鉴权技能检查与凭证配置** [必须执行]

确认洞察方式后，系统会立即检查鉴权技能是否已安装，并配置API凭证：

**完整检查流程：**

**步骤2.1：检查鉴权技能是否已安装**

系统会自动检查鉴权技能（mingdata-dmp-auth）的安装状态：

- **检查路径**：`~/.skills/mingdata-dmp-auth/`
- **如果已安装** → 跳转到步骤2.2（凭证检查）
- **如果未安装** → 向用户展示以下提示并等待回复

**鉴权技能未安装时的提示内容：**

```
⚠️ 检测到您尚未安装【明日DMP鉴权技能】

该技能负责管理 API 凭证（AK/SK）、生成签名，是使用本功能的必要前提。

是否自动下载并安装？

是 - 立即安装
否 - 取消本次操作

请回复：是/否
```

**等待用户回复，按以下逻辑执行：**

- **用户回复"是"**：
  - 使用 terminal 工具执行：`openclaw skills install mingdata-dmp-auth`
  - 等待命令执行完成
  - **安装成功**：提示 `✅ 鉴权技能安装成功` → 继续步骤2.2
  - **安装失败**：展示以下内容后**终止流程**：
    ```
    ❌ 鉴权技能自动安装失败

    请前往 ClawHub 手动安装：
    👉 https://clawhub.ai/mingri26/mingdata-dmp-auth

    手动安装步骤：
    1. 打开上方链接
    2. 点击「Download」按钮
    3. 安装完成后重新发起本次请求
    ```

- **用户回复"否"**：
  - 提示：`已取消操作。如需继续，请先安装鉴权技能。`
  - 终止流程

**步骤2.2：检查凭证是否存在**

鉴权技能安装完成后，检查API凭证配置状态：

- **凭证文件路径**：`~/.mingdata_dmp_credentials`
- **如果凭证不存在** → 展示凭证获取指引（见下方）
- **如果凭证存在但无效** → 引导重新配置
- **如果凭证有效** → 继续执行第三步（洞察类型识别与确认）

**凭证不存在时的引导内容：**

```
🔑 明日DMP API凭证获取指南

您需要先获取明日DMP的API访问凭证（Access Key 和 Secret Key），才能使用人群洞察功能。

📧 申请方式（二选一）：

方式一：邮件申请
- 发送开通申请至：product@mingdata.com
- 邮件主题：【明日DMP API开通申请】
- 邮件内容：请注明公司名称、联系人、联系方式及使用场景

方式二：在线表单申请
- 填写在线申请表单：https://doc.weixin.qq.com/forms/ANEAJwfLAAoADMAHwbhAPICNUE0vDRd8f#/fill
- 提交后等待审核通过（通常1-3个工作日）

🔒 安全提示：
- Access Key ：xxxxxxxxxxxxxxxxxxxx
- Secret Key ：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 请妥善保管凭证，不要泄露给他人

获取凭证后，请按以下格式提供给我：
Access Key: xxxxxxxxxxxxxxxxxxxx
Secret Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**凭证配置后：**
- 系统会自动保存凭证到本地配置文件（`~/.mingdata_dmp_credentials`）
- 凭证由鉴权技能（mingdata-dmp-auth）统一管理
- 后续操作将自动使用已保存的凭证
- 凭证过期时会自动提示重新配置

**第三步：洞察类型识别与确认** [必须执行]

系统会根据您的需求关键词，识别出洞察类型，然后**向您确认并展示完整维度列表**。

### 意图识别规则表

| 洞察类型 | 核心关键词 | 典型口语变体 | 否定/排除词 |
|---------|-----------|------------|-----------|
| **明略洞察** | 明略、人口属性、兴趣爱好、媒体分析、demographic、interest、media | "分析人群的年龄性别"、"看看兴趣偏好"、"媒体使用习惯" | 排除"合作伙伴"、"个推" |
| **合作伙伴洞察** | 合作伙伴、个推、基础标签、地域分布、应用偏好、手机偏好、场景偏好、品类偏好 | "个推洞察"、"看看地域分布"、"APP使用情况" | 排除"明略" |

### 意图识别流程

**步骤1.1：关键词匹配**

从用户需求中提取关键词，匹配洞察类型。

**步骤1.2：向用户确认并展示完整维度列表**

识别出洞察类型后，**必须向用户确认并展示该类型的所有可选维度**：

```
示例1：
您："帮我分析人群123456的特征"
    ↓
系统："识别到您想创建人群洞察。请问您想使用哪种洞察类型？
      
      【明略洞察】
      可选择的维度大类（选择大类即包含该大类下所有细分维度）：
      
      1. demographic（人口属性）- 8个细分维度
         
         | 细分维度 | 细分维度 | 细分维度 | 细分维度 |
         |---------|---------|---------|---------|
         | 性别 | 年龄 | 教育程度 | 个人月收入 |
         | 家庭月收入 | 婚恋育儿 | 职业 | 消费状态 |
      
      2. interest（兴趣爱好）- 23个细分维度
         
         | 细分维度 | 细分维度 | 细分维度 | 细分维度 |
         |---------|---------|---------|---------|
         | 汽车 | 美妆个护 | 游戏 | 旅游运动 |
         | 食品饮料 | IT | 母婴 | 房地产 |
         | 家电 | 服装配饰 | 家装家居 | 家庭清洁 |
         | 金融理财 | 教育 | 医药保健 | 体育赛事直播 |
         | 影视剧 | 文学阅读 | 动漫二次元 | 博物纪实 |
         | 流行音乐 | 自拍人群 | 有车养车 | |
      
      3. media（媒体分析）- 19个细分维度
         
         | 细分维度 | 细分维度 | 细分维度 | 细分维度 |
         |---------|---------|---------|---------|
         | 电子商务 | 电子阅读 | 互动社交 | 家电数码垂媒 |
         | 健康医疗 | 教育文化 | 金融理财 | 旅游出行 |
         | 母婴垂媒 | 拍摄美化 | 汽车垂媒 | 生活服务 |
         | 时尚垂媒 | 视频服务 | 数字电视 | 音乐综合 |
         | 应用工具 | 游戏服务 | 综合资讯 | |
      
      【合作伙伴洞察】
      可选择的维度：
      
      1. basic（基础标签）
      2. region（地域分布）
      3. interest（兴趣偏好）
      4. app（应用偏好）
      5. mobile（手机偏好）
      6. scene（场景偏好）
      7. category（品类偏好）
      
      请选择洞察类型：明略洞察 或 合作伙伴洞察？"
    ↓
您："明略洞察" / "合作伙伴洞察"
```

**步骤1.3：询问维度选择**

用户确认洞察类型后，询问具体维度：

```
系统："您想分析哪些维度？
      
      选项1：全部维度（推荐，获得完整画像）
      选项2：指定维度（请告诉我具体维度名称，如：demographic, interest）
      
      请选择："
    ↓
您："全部维度" / "demographic和interest"
```

**第四步：参数补充** [必须执行]

凭证检查通过后，系统会检查必填参数是否齐全，缺失时**主动询问**。

### 参数引导

**参数1：洞察任务名称（name）**
```
请提供洞察任务名称（≤50字符）：
示例：
- "高端用户画像分析"
- "母婴人群兴趣洞察"
- "北京地区用户特征"
```

**参数2：人群ID（audienceId）**
```
请提供要分析的人群ID：
- 格式：纯数字
- 来源：人群圈选任务创建成功后返回的人群ID
```

**第五步：参数格式校验** [必须执行]

系统会检查参数格式是否正确：
- 任务名称：≤50字符
- 人群ID：纯数字
- 洞察类型：0或1
- 维度：符合对应洞察类型的维度列表

格式错误时会提示正确格式示例。

### ⚠️ 参数获取失败处理规则 (强制执行)

**当通过API查询参数(如人群ID验证、维度列表等)失败时，必须执行以下流程：**

**1. 立即向用户同步失败情况**
   - 说明哪个参数查询失败
   - 说明失败原因(如API权限不足、网络错误等)
   - 说明对任务的影响

**2. 提供备选方案并等待用户决策**
   - 方案A: 降级处理(去掉该参数，用其他参数创建)
   - 方案B: 用户手动提供参数值
   - 方案C: 取消本次操作
   - **⚠️ 禁止自行决定方案，必须等待用户选择**

**3. 用户选择后重新确认参数**
   - 如用户选择降级处理，必须重新展示修改后的参数表格
   - 必须再次等待用户确认
   - 确认后才能执行创建

**错误示例(禁止)：**
```
查询人群ID失败 → 直接跳过验证 → 继续创建 ❌
```

**正确示例：**
```
查询人群ID失败 → 向用户说明情况 → 提供备选方案 → 用户选择方案B(手动提供) → 重新展示参数表格 → 用户确认 → 执行创建 ✅
```

**示例对话：**
```
系统: "⚠️ 人群ID验证失败
      
      失败原因: API权限不足，无法查询人群ID 123456的详细信息
      影响: 无法验证人群是否存在和状态是否正常
      
      您可以选择以下方案:
      A. 跳过验证 - 直接使用该人群ID创建洞察任务（可能失败）
      B. 更换人群ID - 提供其他人群ID
      C. 取消操作 - 取消本次洞察任务创建
      
      请选择方案(回复A/B/C):"

用户: "A"

系统: "好的，已跳过人群ID验证。
      
      修改后的参数如下:
      | 参数项 | 参数值 |
      |--------|--------|
      | 洞察任务名称 | 测试洞察 |
      | 人群ID | 123456（未验证） |
      | 洞察类型 | 明略洞察 |
      | 洞察维度 | demographic, interest |
      
      请确认以上参数是否正确?(回复'确认'开始创建)"
```

**第六步：参数确认** [必须执行]

⚠️ **这是强制性步骤，绝对不能跳过！**

**必须执行的完整确认流程：**

1. **生成参数确认表格**
   - 以表格形式展示所有参数
   - 包含所有关键信息
   - 使用清晰的格式，便于用户检查

**参数确认表格必须包含以下信息：**

| 参数项 | 参数值 |
|--------|--------|
| **洞察任务名称** | 用户指定的任务名称 |
| **人群ID** | 要分析的人群ID |
| **洞察类型** | 明略洞察/合作伙伴洞察 |
| **洞察维度** | 选择的维度列表（如：demographic, interest, media） |

2. **等待用户明确确认**
   - 必须等待用户回复"确认"、"是"、"可以"等明确的确认词
   - 不允许在用户未确认前直接调用API
   - 用户可以选择"修改"、"取消"或"确认"

**示例确认对话：**

```
系统展示参数表格后：

请确认以上参数是否正确？
- 回复"确认"或"是"：开始创建洞察任务
- 回复"修改"：重新设置参数
- 回复"取消"：取消本次操作
```

3. **处理用户响应**
   - 用户确认 → 进入第七步（调用业务脚本）
   - 用户要求修改 → 返回第四步（参数补充）
   - 用户取消 → 终止流程，提示"已取消本次操作"

### ⚠️ 参数变更时的重新确认规则 (强制执行)

**如果在执行过程中发生以下情况，必须重新执行第六步参数确认：**

**1. 参数查询失败导致参数变更**
   - 示例：人群ID查询失败，用户选择使用其他人群ID
   - 必须重新展示修改后的参数表格
   - 必须再次等待用户确认

**2. 用户主动修改参数**
   - 用户在确认表格后要求修改某个参数
   - 必须重新展示完整参数表格
   - 必须再次等待用户确认

**3. 系统自动调整参数**
   - 示例：维度选择超过限制，系统自动调整
   - 必须向用户说明调整原因和调整后的值
   - 必须重新展示参数表格并等待确认

**禁止行为：**
- ❌ 参数变更后直接执行，不重新确认
- ❌ 假设用户已经知道参数变更
- ❌ 只口头说明变更，不展示完整表格

**第七步：调用业务脚本** [必须执行]

⚠️ **前置条件：必须在用户明确确认后才能执行**

🔧 **架构优化：业务脚本通过鉴权技能统一API模块完成调用**

**执行流程**：
1. 调用创建洞察任务脚本（scripts/create_insight_task.py）
2. 业务脚本通过subprocess调用鉴权技能的minri_dmp_api.py
3. 鉴权技能负责：
   - 从~/.mingdata_dmp_credentials加载凭证
   - 生成签名（timestamp + randStr + MD5）
   - 封装HTTP请求并发送到明日DMP API
4. 返回API响应结果给业务脚本
5. 业务脚本解析并返回结果

**处理API返回结果**：
   - 成功 → 获取任务ID → **⚠️ 立即执行第八步（检查任务记录技能）**
   - 失败 → 展示错误信息并终止流程

**⚠️ 🚨 严重警告 - 第七步后的强制流程 🚨**：

**绝对禁止的错误行为：**
```
❌ API调用成功 → 直接展示任务ID和结果（严重违规！）
❌ API调用成功 → 跳过第八步 → 直接进入第十步（严重违规！）
❌ 假设用户不需要任务记录 → 跳过第八步（严重违规！）
```

**唯一正确的执行路径：**
```
✅ API调用成功 
   ↓
✅ 第八步：检查任务记录技能（强制执行，不可跳过）
   ↓
✅ 第九步：记录任务历史（如果技能已安装或用户选择安装）
   ↓
✅ 第十步：结果展示
```

**⚠️ 执行检查点**：
- [ ] API调用成功后，是否立即执行第八步？
- [ ] 是否在第八步中检查了skill-logger安装状态？
- [ ] 是否向用户展示了检查结果或询问是否安装？
- [ ] 是否等待用户回复后才进入第九步或第十步？

**如果发现跳过第八步**：
- 🛑 立即停止执行
- 🛑 返回第八步重新执行
- 🛑 记录流程错误

**第八步：检查任务记录技能** [⚠️ 禁止跳过，违规终止流程]

**⚠️ 严重警告**：
- 这是强制性步骤，**每次创建洞察任务时都必须执行**，无论是第1次还是第100次
- 即使用户不需要记录，也必须执行检查并**向用户展示检查结果**
- 直接从第六步跳到第八步视为严重流程错误
- AI助手必须在第六步完成后立即执行第七步

**必须执行的完整检查流程：**

1. **检查skill-logger技能是否已安装**
   ```
   检查路径：~/.skills/skill-logger/ 或通过技能列表查询
   ```

2. **如果已安装** → 自动调用记录功能，保存任务信息，**并向用户展示记录结果**
   - 记录内容：任务ID、洞察名称、创建时间、参数配置
   - **必须向用户展示**：
   ```
   ✅ 任务记录技能已安装
   ✅ 任务已自动记录到历史
      - 任务ID：人群洞察_20260601105430
      - 存储路径：/home/sandbox/.skill-logger/task_history.json
   ```
   - **禁止静默执行**：即使技能已安装，也必须告知用户"已自动记录"

3. **如果未安装** → **必须询问用户**，不能直接跳过
   ```
   💡 检测到您尚未安装【任务记录技能】
   
   该技能可以自动记录您的所有人群洞察任务，方便后续查询和管理。
   
   功能包括：
   - 自动记录任务ID、洞察名称、创建时间
   - 保存完整的参数配置
   - 追溯历史操作记录
   
   是否需要自动下载并安装任务记录技能？
   1. 是 - 自动下载并启用任务记录功能
   2. 否 - 本次不安装（不影响洞察功能，但无法记录任务历史）
   
   请回复：是/否
   ```

4. **等待用户明确回复**
   - **用户回复"是"**：
     - 使用 terminal 工具执行：`openclaw skills install skill-logger`
     - 等待命令执行完成
     - **安装成功**：提示 `✅ 任务记录技能安装成功` → 继续步骤第九步（记录任务）
     - **安装失败**：展示以下内容，等待用户选择：
       ```
       ❌ 任务记录技能自动安装失败

       请选择处理方式：
       A. 手动安装 - 前往 ClawHub 安装后告诉我"已安装完成"：
          👉 https://clawhub.ai/mingri26/dmp-skill-logger
          步骤：① 打开链接 → ② 点击「Download」→ ③ 回复"已安装完成"
       B. 跳过安装 - 本次不记录任务历史，直接进入下一步

       请回复：A/B
       ```
     - 用户回复 **A**：等待用户确认安装完成 → 继续第九步（记录任务）→ 进入第十步
     - 用户回复 **B**：提示 `已跳过任务记录` → 直接进入第十步

   - **用户回复"否"**：
     - 提示：`已跳过任务记录，不影响主流程。`
     - 直接进入第十步

**⚠️ 重要提醒：**
- 这一步虽然用户可以选择"否"，但**检查和向用户展示结果的流程是强制性的**
- 即使用户选择不安装，也必须完成询问并记录用户的选择
- **即使技能已安装，也必须向用户展示"已自动记录"的提示**
- **绝对禁止**在未执行检查和展示的情况下直接跳到第九步或第十步
- **每次创建洞察任务都必须执行此步骤**，不能因为之前执行过就跳过

**第九步：记录任务历史** [必须执行]

**执行条件：**
- 第八步检查发现skill-logger技能已安装，或用户选择安装

**执行流程：**
1. 调用skill-logger技能记录任务信息
2. 记录内容包括：
   - 任务ID：人群洞察_[时间戳]
   - 洞察名称：用户指定的任务名称
   - 洞察类型：明略洞察/合作伙伴洞察
   - 洞察维度：选择的维度列表
   - 创建时间：任务创建时间
   - 完整参数配置：所有参数的JSON格式记录
3. 保存到任务历史文件：/home/sandbox/.skill-logger/task_history.json

**向用户展示记录结果：**
```
✅ 任务已自动记录到历史
   - 任务ID：人群洞察_20260601105430
   - 存储路径：/home/sandbox/.skill-logger/task_history.json
```

**第十步：结果展示** [必须执行]

**⚠️ 🚨 前置条件强制检查 - 执行第十步前必读 🚨**：

**在执行第十步之前，AI助手必须逐项确认以下检查点：**

✅ **检查点1：第八步是否已执行？**
   - 是否检查了skill-logger技能的安装状态？
   - 是否向用户展示了检查结果？
   - 如果未安装，是否询问了用户是否需要安装？
   - 是否等待了用户的明确回复（是/否）？

✅ **检查点2：第九步是否已执行（如适用）？**
   - 如果skill-logger已安装，是否调用了记录功能？
   - 如果用户选择安装，是否完成了安装和记录？
   - 是否向用户展示了记录结果？

✅ **检查点3：用户选择跳过记录功能的情况**
   - 如果用户选择"否"（不安装），是否明确告知用户"已跳过任务记录功能"？
   - 是否记录了用户的选择？

**🚨 如果任何一个检查点未通过**：
```
❌ 立即停止执行第十步
❌ 返回第八步重新执行
❌ 向用户说明："检测到流程错误，正在重新执行任务记录检查..."
❌ 记录流程错误日志
```

**✅ 所有检查点通过后，才能继续执行第十步**

**成功时：**

展示任务创建成功信息：
- 任务ID（taskId）
- 洞察任务名称
- 预计完成时间（通常5-30分钟）

**后续操作建议：**

人群洞察任务执行成功后，您可以进行以下操作：

1. **下载人群圈选技能** - 根据画像特征进一步精准圈选人群
   - 功能：基于洞察结果中的画像特征，创建更精准的人群圈选规则
   - 适用场景：发现了目标人群的关键特征，需要扩大或优化人群范围
   - 操作方式：告诉我"下载人群圈选技能"或"创建人群圈选任务"

2. **下载人群投放技能** - 创建人群投放任务
   - 功能：将洞察的人群包投放到广告平台
   - 适用场景：洞察的人群包符合目标人群预期，需要进行广告投放
   - 操作方式：告诉我"下载人群投放技能"或"创建投放任务"

**失败时：**

展示错误详情、可能原因、解决方案

---

## 流程执行规则（AI助手必读）

### 强制性说明

本技能的工作流程包含10个步骤，每个步骤都有明确的执行要求：

**[必须执行]** - 该步骤在任何情况下都必须执行，不可跳过
**[必须检查]** - 该步骤必须执行检查逻辑，即使用户不需要该功能

### 执行检查清单

在执行人群洞察任务时，AI助手必须按照以下清单逐步检查：

- [ ] **第一步：请求类型识别** [必须执行]
  - 检查点：是否正确识别了请求类型（咨询/查询任务/获取结果/创建洞察）？
  - 检查点：如果是咨询/查询/获取结果请求，是否直接处理后结束？
  - 检查点：如果是创建洞察请求，是否进入完整的创建流程（第二步~第十步）？
  - 失败处理：如无法识别，询问用户具体需求

- [ ] **第二步：凭证检查** [必须执行]
  - 检查点：是否检查了凭证文件是否存在？
  - 检查点：凭证不存在时，是否展示凭证获取指引？
  - 失败处理：凭证配置失败时，终止流程并提示用户

- [ ] **第三步：洞察类型识别与确认** [必须执行]
  - 检查点：是否正确识别了洞察类型（明略洞察/合作伙伴洞察）？
  - 检查点：是否向用户展示了完整维度列表？
  - 检查点：是否等待用户确认后才继续？
  - 失败处理：如无法识别，展示所有洞察类型供用户选择

- [ ] **第四步：参数补充** [必须执行]
  - 检查点：是否收集了所有必填参数（任务名称、人群ID、洞察维度）？
  - 失败处理：参数不完整时，重新询问用户

- [ ] **第五步：参数格式校验** [必须执行]
  - 检查点：是否验证了所有参数的格式？
  - 失败处理：格式错误时，提示正确格式并重新收集

- [ ] **第六步：参数确认** [必须执行]
  - ⚠️ 关键：这是强制性步骤，任何洞察类型都必须先展示参数表等待用户确认
  - 检查点：是否以表格形式展示了所有参数？
  - 检查点：是否等待用户明确回复"确认"、"是"、"可以"等确认词？
  - 检查点：是否在用户确认前禁止调用API？
  - 失败处理：用户要求修改时，返回第四步重新收集参数；用户取消时，终止流程

- [ ] **第七步：调用业务脚本** [必须执行]
  - 检查点：是否调用了正确的创建脚本（scripts/create_insight_task.py）？
  - 检查点：是否通过鉴权技能的统一API模块完成API调用？
  - 检查点：是否处理了API返回的错误？
  - 失败处理：API调用失败时，展示错误信息并终止流程
  - **🚨 关键检查：API调用成功后，是否立即执行第八步？（禁止直接跳到第十步）**

- [ ] **第八步：检查任务记录技能** [⚠️ 强制执行，禁止跳过]
  - **🚨 严重警告：这是强制性步骤，每次创建洞察任务都必须执行**
  - **🚨 即使用户不需要记录，也必须执行检查并向用户展示结果**
  - 检查点：是否检查了skill-logger技能是否安装？
  - 检查点：未安装时，是否向用户展示完整的询问提示（包括功能说明）？
  - 检查点：已安装时，是否向用户展示"已自动记录"的提示？
  - 检查点：是否等待用户明确回复（是/否）？
  - 检查点：是否记录了用户的选择（安装/跳过）？
  - 失败处理：用户选择跳过时，明确告知"已跳过任务记录功能"并继续第十步
  - **🚨 禁止行为：直接跳过第八步，假设用户不需要记录功能**

- [ ] **第九步：记录任务历史** [必须执行]
  - 执行条件：第八步检查发现skill-logger技能已安装，或用户选择安装
  - 检查点：是否调用skill-logger技能记录任务信息？
  - 检查点：是否向用户展示记录结果？
  - 失败处理：记录失败时，提示用户但不影响任务创建

- [ ] **第十步：结果展示** [必须执行]
  - 检查点：是否展示了任务ID和预计完成时间？
  - 检查点：是否提供了后续操作建议（人群圈选/人群投放）？
  - 失败处理：无

### AI助手执行指引

**执行原则：**
1. 严格按照步骤顺序执行，不可跳过任何[必须执行]或[必须检查]的步骤
2. 每个步骤完成后，在内部记录执行状态（已完成/已跳过/失败）
3. 遇到[必须检查]步骤时，即使预判用户不需要，也必须执行检查逻辑
4. **🚨 第八步是最容易被跳过的步骤，必须特别注意**
5. **🚨 API调用成功后，禁止直接展示结果，必须先执行第八步**

**第六步执行示例（参数确认）：**

```
# 正确执行方式
1. 收集完所有必填参数后，立即生成参数确认表格
2. 以表格形式展示所有参数
3. 向用户展示确认提示：
   "请确认以上参数是否正确？
   - 回复'确认'或'是'：开始创建洞察任务
   - 回复'修改'：重新设置参数
   - 回复'取消'：取消本次操作"
4. 等待用户明确回复
5. 用户确认后才进入第七步（调用业务脚本）

# 错误执行方式（禁止）
1. 收集完参数后直接调用API，不展示确认表格
2. 展示表格后不等待用户确认就执行
3. 假设用户已经确认，直接创建任务
```

**第八步执行示例（任务记录检查）：**

```
# ✅ 正确执行方式
1. API调用成功后，立即执行第八步（不要直接展示结果）
2. 检查skill-logger是否安装
3. 如已安装，自动记录并向用户展示：
   "✅ 任务记录技能已安装
   ✅ 任务已自动记录到历史
      - 任务ID：人群洞察_20260601105430
      - 存储路径：/home/sandbox/.skill-logger/task_history.json"
4. 如未安装，向用户展示完整询问提示：
   "💡 检测到您尚未安装【任务记录技能】
   
   该技能可以自动记录您的所有人群洞察任务，方便后续查询和管理。
   
   功能包括：
   - 自动记录任务ID、洞察名称、创建时间
   - 保存完整的参数配置
   - 追溯历史操作记录
   
   是否需要自动下载并安装任务记录技能？
   1. 是 - 自动下载并启用任务记录功能
   2. 否 - 本次不安装（不影响洞察功能，但无法记录任务历史）
   
   请回复：是/否"
5. 等待用户明确回复
6. 记录用户选择
7. 根据用户选择进入第九步或第十步

# ❌ 错误执行方式（严重违规）
1. API调用成功 → 直接跳到第十步展示结果（跳过第八步）
2. 不检查skill-logger安装状态
3. 不询问用户直接进入第十步
4. 假设用户不需要记录功能
5. 已安装时静默执行，不告知用户"已自动记录"
```

**流程完整性验证：**

在展示最终结果前，AI助手应在内部验证：
- 是否所有[必须执行]步骤都已完成？
- 是否所有[必须检查]步骤都已执行检查逻辑？
- 是否记录了用户在可选步骤的选择？
- **⚠️ 特别检查：第五步参数确认是否已展示表格并等待用户明确确认？**
- **⚠️ 特别检查：是否在用户确认前就调用了API（严重错误）？**
- **⚠️ 特别检查：第七步任务记录检查是否已执行并展示结果？**

如发现遗漏，应立即补充执行遗漏的步骤。

**调试建议：**

如用户反馈某个步骤被跳过，AI助手应：
1. 回顾执行日志，确认该步骤是否真的被执行
2. 检查该步骤的检查点是否都已满足
3. 向用户说明该步骤的执行情况和结果
4. 如确实遗漏，立即补充执行并道歉

---

## API凭证说明

本技能的API凭证由独立的鉴权技能（mingdata-dmp-auth）管理。首次使用时，系统会自动引导您申请和配置凭证。

**凭证申请方式（二选一）：**

**方式一：邮件申请**
- 发送开通申请至：product@mingdata.com
- 邮件主题：【明日DMP API开通申请】
- 邮件内容：请注明公司名称、联系人、联系方式及使用场景

**方式二：在线表单申请**
- 填写在线申请表单：https://doc.weixin.qq.com/forms/ANEAJwfLAAoADMAHwbhAPICNUE0vDRd8f#/fill
- 提交后等待审核通过（通常1-3个工作日）

**凭证格式：**
- Access Key：`xxxxxxxxxxxxxxxx`
- Secret Key：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

## 支持的洞察类型

### 1. 明略洞察（insightType=0）

**功能说明：** 基于明略科技的数据能力，提供人口属性、兴趣爱好、媒体分析三大维度的深度洞察

**可选维度大类：**

**1. demographic（人口属性）- 8个细分维度**

| 细分维度 | 细分维度 | 细分维度 | 细分维度 |
|---------|---------|---------|---------|
| 性别 | 年龄 | 教育程度 | 个人月收入 |
| 家庭月收入 | 婚恋育儿 | 职业 | 消费状态 |

**2. interest（兴趣爱好）- 23个细分维度**

| 细分维度 | 细分维度 | 细分维度 | 细分维度 |
|---------|---------|---------|---------|
| 汽车 | 美妆个护 | 游戏 | 旅游运动 |
| 食品饮料 | IT | 母婴 | 房地产 |
| 家电 | 服装配饰 | 家装家居 | 家庭清洁 |
| 金融理财 | 教育 | 医药保健 | 体育赛事直播 |
| 影视剧 | 文学阅读 | 动漫二次元 | 博物纪实 |
| 流行音乐 | 自拍人群 | 有车养车 | |

**3. media（媒体分析）- 19个细分维度**

| 细分维度 | 细分维度 | 细分维度 | 细分维度 |
|---------|---------|---------|---------|
| 电子商务 | 电子阅读 | 互动社交 | 家电数码垂媒 |
| 健康医疗 | 教育文化 | 金融理财 | 旅游出行 |
| 母婴垂媒 | 拍摄美化 | 汽车垂媒 | 生活服务 |
| 时尚垂媒 | 视频服务 | 数字电视 | 音乐综合 |
| 应用工具 | 游戏服务 | 综合资讯 | |

**总计：** 3个维度大类，50个细分维度

**示例：** "分析人群123456的人口属性和兴趣爱好"

### 2. 合作伙伴洞察（insightType=1）

**功能说明：** 基于个推等合作伙伴的数据能力，提供7个维度的用户行为和偏好洞察

**可选维度：**

| 维度代码 | 维度名称 | 维度代码 | 维度名称 |
|---------|---------|---------|---------|
| basic | 基础标签 | region | 地域分布 |
| interest | 兴趣偏好 | app | 应用偏好 |
| mobile | 手机偏好 | scene | 场景偏好 |
| category | 品类偏好 | | |

**总计：** 7个维度大类

**示例：** "分析人群123456的地域分布和应用偏好"

## 任务状态码说明

### 状态码定义表

为了避免状态误判，以下是明日DMP洞察任务的完整状态码定义（根据官方文档）：

| 状态码 | 状态名称 | 状态显示 | 说明 | 可获取结果 | 预计等待时间 |
|--------|---------|---------|------|-----------|------------|
| 0 | 失败 | ❌ 失败 | 任务计算失败 | ❌ 否 | - |
| 1 | 成功 | ✅ 已完成 | 任务计算成功完成 | ✅ 是 | - |
| 2 | 等待中 | 🟡 等待中 | 任务等待处理 | ❌ 否 | < 1分钟 |
| 3 | 计算中 | 🔵 计算中 | 任务正在计算处理 | ❌ 否 | 5-30分钟 |

### 状态判断规则

**✅ 可以获取结果的状态**
- status = 1（成功）

**⏳ 需要继续等待的状态**
- status = 2（等待中）- 通常 < 1分钟
- status = 3（计算中）- 通常 5-30分钟

**❌ 需要重新创建的状态**
- status = 0（失败）

### 重要提示

⚠️ **避免状态误判**：
- 只有 status = 1 时才表示任务已完成
- status = 2, 3 都表示任务还在处理中，需要继续等待
- 不要仅凭 API 返回的 code = "0" 就判断任务完成
- 必须检查 status 字段的具体值来判断任务状态

## 查询任务状态

创建洞察任务后，您可以查询任务状态：

**用法：** "查询洞察任务 123456 的状态"

**返回信息：**
```json
{
  "任务ID": 123456,
  "任务名称": "明略洞察-全维度分析",
  "人群ID": 125456,
  "洞察类型": "明略洞察",
  "创建时间": "2026-06-02 11:35:37",
  "状态码": 1,
  "状态名称": "成功",
  "状态显示": "✅ 已完成",
  "状态说明": "任务计算成功完成",
  "可获取结果": "是",
  "下一步操作": "✅ 可以获取洞察结果了！"
}
```

**任务成功时的后续操作建议：**

人群洞察任务执行成功后，您可以进行以下操作：

1. **下载人群圈选技能** - 根据画像特征进一步精准圈选人群
   - 功能：基于洞察结果中的画像特征，创建更精准的人群圈选规则
   - 适用场景：发现了目标人群的关键特征，需要扩大或优化人群范围
   - 操作方式：告诉我"下载人群圈选技能"或"创建人群圈选任务"

2. **下载人群投放技能** - 创建人群投放任务
   - 功能：将洞察的人群包投放到广告平台
   - 适用场景：洞察的人群包符合目标人群预期，需要进行广告投放
   - 操作方式：告诉我"下载人群投放技能"或"创建投放任务"

## 获取洞察结果

任务计算成功后，您可以获取详细的洞察数据：

**用法：** "获取洞察任务 123456 的结果"

**自动生成文件：**

系统会自动生成两种格式的数据文件供您下载：

### 📄 文件1：JSON格式（原始数据）
- **文件名**：洞察任务{任务ID}_API原始数据.json
- **内容**：保留完整的树形结构数据
- **用途**：适合程序化处理和二次开发

### 📊 文件2：Excel格式（数据表格）
- **文件名**：洞察任务{任务ID}_完整数据表格.xlsx
- **包含3个工作表**：

**工作表1：完整洞察数据**
- 包含所有维度的详细数据（通常300+条记录）
- 字段：一级分类、二级分类、三级分类、四级分类、维度名称、覆盖率、TGI指数、维度类型等

**工作表2：高TGI特征(>200)**
- 筛选出TGI指数大于200的高价值特征
- 按TGI指数降序排列
- 用途：快速定位目标人群的核心特征

**工作表3：一级分类汇总**
- 按一级分类（兴趣爱好、人口属性、媒体分析）统计
- 字段：一级分类、最大覆盖率、最大TGI指数、维度数量

**返回信息：**
- 各维度的详细数据分布
- TGI指数（Target Group Index，目标人群指数）
- 覆盖率、渗透率等关键指标
- 文件下载链接

## 常见问题

### Q: 凭证过期了怎么办？
A: 系统会自动调用鉴权技能引导您重新配置凭证。

### Q: 创建洞察任务后多久能完成？
A: 洞察任务通常需要5-30分钟完成计算，您可以通过查询任务状态功能查看进度。

### Q: 明略洞察和合作伙伴洞察有什么区别？
A: 明略洞察侧重人口属性、兴趣爱好、媒体分析；合作伙伴洞察侧重地域、应用、设备等行为数据。建议根据分析目标选择。

### Q: 可以同时选择多个维度吗？
A: 可以。您可以选择全部维度获得完整画像，也可以指定部分维度进行针对性分析。

### Q: 选择维度大类是什么意思？
A: 对于明略洞察，选择一个维度大类（如demographic）即包含该大类下的所有细分标签（性别、年龄、教育程度等）。

## 技能依赖

### 1. 鉴权技能（mingdata-dmp-auth）

**作用：** 管理明日DMP API的访问凭证（Access Key和Secret Key）

**调用时机：** 
- 首次使用本技能时
- 凭证过期或失效时
- 任何需要调用明日DMP API的操作前

**定位方式：**
- 通过scripts/find_auth_skill.py脚本自动定位鉴权技能路径
- 所有API调用通过鉴权技能的minri_dmp_api.py统一处理

**API调用方式：**
```bash
# 通过鉴权技能调用API
python <鉴权技能路径>/scripts/minri_dmp_api.py POST /api/open-api/audience/insight/add \
  --data '{"name":"洞察任务","audienceId":123456,"insightType":0,"insightCondition":["demographic"]}'
```

**是否必需：** ✅ 必需（不安装无法使用洞察功能）

### 2. 任务记录技能（skill-logger）

**作用：** 自动记录所有洞察任务的创建参数、执行时间和操作步骤

**调用时机：**
- 每次成功创建洞察任务后
- 用于后续查询历史任务、追溯操作记录

**是否必需：** ⭕ 可选（不安装不影响洞察功能，但无法记录任务历史）

## 技术说明

🔧 **架构优化：业务脚本通过鉴权技能的统一API模块完成所有API调用**

本技能通过Python脚本调用明日DMP开放平台API，所有脚本位于 `scripts/` 目录：

**业务脚本：**
- scripts/create_insight_task.py - 创建洞察任务
- scripts/query_insight_task.py - 查询任务状态
- scripts/get_insight_result.py - 获取洞察结果

**API调用方式：**
- 业务脚本不再包含API调用逻辑
- 通过subprocess调用鉴权技能的统一API模块（minri_dmp_api.py）
- 鉴权技能负责：凭证加载、签名生成（timestamp + randStr + MD5）、HTTP请求封装