明日Dmp人群同步

SKILL.md

---
name: 明日dmp人群同步
description: 基于明日DMP开放平台API，提供人群同步管理功能。支持获取广告账户、创建同步任务、查询同步状态。采用10步标准化工作流程，包含请求类型识别、凭证检查、参数引导、格式校验、参数确认、任务记录等完整流程。适用于将DMP人群包同步到各大广告平台（小红书/腾讯/字节等）进行精准投放。
---

# 明日DMP人群同步

## 概述

本技能基于明日DMP开放平台API，提供人群同步管理功能，帮助您将圈选的人群包同步到各大广告平台进行精准投放。

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

## 🔑 前置准备

使用本技能前，您需要先获取明日DMP API凭证：

**📧 申请方式（二选一）：**

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

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

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

**💡 温馨提示**：首次使用时，我会自动引导您完成凭证配置，无需担心！

## 工作流程（10步标准化流程）

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

系统会自动识别您的请求类型：

**1. 获取广告账户请求**
- 触发词："查询小红书广告账户"、"获取腾讯广告账户列表"
- 直接调用获取广告账户脚本
- 展示账户列表后结束

**2. 查询同步任务请求**
- 触发词："查询同步任务123456"、"同步任务状态"
- 直接调用查询脚本
- 展示任务状态后结束

**3. 创建同步任务请求**
- 触发词："将人群123456同步到小红书"、"创建人群同步任务"
- 进入完整的创建流程（第二步~第十步）

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

**步骤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
```

### 第三步：参数收集 [必须执行]

系统会引导您提供必要的参数：

**必填参数：**
1. **平台类型（platform）**
   - oceanengine（字节DMP）
   - tencent（腾讯DMP）
   - alipay（支付宝DMP）
   - bilibili（B站DMP）
   - xiaohongshu（小红书灵犀）

2. **人群ID（crowdId）**
   - 要同步的DMP人群包ID

3. **广告账户ID（adAccountId）**
   - 目标广告平台的账户ID
   - 可通过"获取广告账户"功能查询

**条件必填参数：**

**字节DMP（platform=oceanengine）时必填：**
- `isToBytedanceBrand`：是否推送云图（true/false）
- `bytedanceBrandVirtualAdvId`：云图账户虚拟ID
- `bytedanceBrandName`：云图账户名称

**小红书（platform=xiaohongshu）时必填：**
- `advertiserBrand`：广告账户品牌

### 第四步：参数格式校验 [必须执行]

系统会检查参数格式是否正确：
- 平台类型：必须是支持的平台之一
- 人群ID：必须是有效的数字
- 广告账户ID：必须是有效的字符串
- 条件参数：根据平台类型检查必填参数是否齐全

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

### 第五步：参数确认 [必须执行]

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

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

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

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

3. **处理用户响应**
   - 用户确认 → 进入第六步（执行创建）
   - 用户要求修改 → 返回第三步（参数收集）
   - 用户取消 → 终止流程，提示"已取消本次操作"

**参数确认表格格式：**

| 参数项 | 参数值 |
|--------|--------|
| **平台类型** | 小红书灵犀 |
| **人群ID** | 123456 |
| **广告账户ID** | ad_account_123456 |
| **广告账户品牌** | 品牌名称（小红书必填） |

**确认提示语示例：**

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

### 第六步：查询广告账户（可选）[按需执行]

如果用户未提供广告账户ID，系统会先调用获取广告账户接口：

```python
python scripts/get_ad_accounts.py <platform>
```

展示账户列表，等待用户选择账户ID后继续。

### 第七步：执行创建 [必须执行]

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

**执行流程**：
1. 调用创建同步任务脚本
2. 脚本通过鉴权技能调用明日DMP API
3. 处理API返回结果
   - 成功 → 获取任务ID → **🔴 立即执行第八步（任务记录检查）**
   - 失败 → 展示错误信息并终止流程

**🔴 严重警告 - 禁止跳过第八步**：
- API调用成功后，**绝对禁止直接展示结果**
- **必须先执行第八步（任务记录检查）**
- 只有完成第八步后，才能进入第九步（结果展示）
- **创建脚本会自动输出第八步提示，AI助手必须响应该提示**

### 第八步：任务记录技能检查 [⚠️ 禁止跳过]

**⚠️ 严重警告**：
- 这是强制性步骤，**每次创建同步任务时都必须执行**
- 即使用户不需要记录，也必须执行检查并**向用户展示检查结果**
- 直接从第七步跳到第九步视为严重流程错误

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

**步骤8.1：检查任务记录技能是否已安装**

系统会自动检查任务记录技能（skill-logger）的安装状态：

- **检查路径**：`~/.skills/skill-logger/` 或 `~/.skills/skill-logger-v2-global/`
- **如果已安装** → 跳转到步骤8.2（自动记录任务）
- **如果未安装** → 向用户展示以下提示并等待回复

**任务记录技能未安装时的提示内容：**

```
💡 检测到您尚未安装【任务记录技能】

该技能可自动记录每次任务的 ID、名称、时间和参数，方便后续查询和追溯。

是否自动下载并安装？

是 - 立即安装并启用记录功能
否 - 本次跳过（不影响主流程）

请回复：是/否
```

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

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

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

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

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

**步骤8.2：自动记录任务信息**

任务记录技能安装完成后，自动调用记录功能保存任务信息：

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

### 第九步：结果展示 [必须执行]

**⚠️ 前置条件检查**：
在执行第九步之前，必须确认：
- [ ] 第八步（任务记录检查）是否已执行？
- [ ] 是否已检查skill-logger安装状态？
- [ ] 是否已询问用户是否需要安装（如果未安装）？

**成功时：**

展示任务创建成功信息：
- 任务ID
- 预计完成时间（通常几分钟到几小时）
- 后续操作建议

**后续操作建议：**

```
✅ 人群同步任务创建成功！

任务信息：
- 任务ID：20000456
- 平台：小红书灵犀
- 人群ID：123456
- 预计完成时间：几分钟到几小时（取决于人群规模）

后续操作：
1. 查询任务状态：告诉我"查询同步任务20000456"
2. 查看所有同步任务：告诉我"查询所有同步任务"
```

**失败时：**

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

### 第十步：流程结束 [必须执行]

确认所有步骤已完成，流程正常结束。

## 技能依赖说明

本技能依赖以下技能：

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

**作用：** 管理明日DMP API的访问凭证并提供统一的API调用接口

**调用方式：** 
- 所有业务脚本通过调用鉴权技能的 `minri_dmp_api.py` 来完成API请求
- 自动处理凭证读取、签名生成、请求发送等流程

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

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

**作用：** 自动记录所有人群同步任务的创建记录、参数配置和执行结果

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

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

## 支持的功能

### 1. 获取广告账户列表

**功能说明：** 查询指定广告平台的可用广告账户

**使用场景：**
- 创建同步任务前，需要先获取广告账户ID
- 查看当前可用的广告账户

**触发方式：**
- "查询小红书广告账户"
- "获取腾讯广告账户列表"
- "我有哪些快手广告账户"

**脚本调用：**
```bash
python scripts/get_ad_accounts.py xiaohongshu
```

**支持的平台：**
- oceanengine（字节DMP）
- tencent（腾讯DMP）
- alipay（支付宝DMP）
- bilibili（B站DMP）
- xiaohongshu（小红书灵犀）

### 2. 创建人群同步任务

**功能说明：** 将DMP人群包同步到指定广告平台的广告账户

**使用场景：**
- 将圈选的目标人群同步到广告平台进行投放
- 实现跨平台的精准营销

**触发方式：**
- "将人群123456同步到小红书"
- "创建人群同步任务"
- "同步人群到腾讯广告"

**脚本调用：**
```bash
python scripts/create_sync_task.py '{"platform":"xiaohongshu","crowdId":"123456","adAccountId":"ad_account_123456","advertiserBrand":"品牌名称"}'
```

**参数说明：**
- `platform`：平台类型（oceanengine/tencent/alipay/bilibili/xiaohongshu）
- `crowdId`：人群ID
- `adAccountId`：广告账户ID
- `advertiserBrand`：广告账户品牌（小红书必填）
- `isToBytedanceBrand`：是否推送云图（字节DMP必填）
- `bytedanceBrandVirtualAdvId`：云图账户虚拟ID（字节DMP必填）
- `bytedanceBrandName`：云图账户名称（字节DMP必填）

### 3. 查询同步任务状态

**功能说明：** 查询人群同步任务的执行状态和详细信息

**使用场景：**
- 查看同步任务是否完成
- 了解同步进度和结果

**触发方式：**
- "查询同步任务20000456"
- "同步任务状态"
- "任务20000456进度如何"

**脚本调用：**
```bash
# 查询单个任务
python scripts/query_sync_task.py 20000456

# 查询多个任务
python scripts/query_sync_task.py 20000456,20000457,20000458

# 按状态查询
python scripts/query_sync_task.py --status 1

# 按时间范围查询
python scripts/query_sync_task.py --start-date 2025-01-01 --end-date 2025-12-31

# 分页查询
python scripts/query_sync_task.py --current 2 --page-size 10
```

**状态说明：**
- 0：失败
- 1：成功
- 2：等待中
- 3：计算中

## 技术说明

### 核心架构

本技能采用**依赖鉴权技能**的架构设计：

**API调用流程：**
```
业务脚本 → find_auth_skill_path() → 鉴权技能 → 明日DMP API
```

**优势：**
1. **统一鉴权**：所有API调用使用相同的鉴权逻辑，确保一致性
2. **安全可靠**：凭证管理和签名生成由专业鉴权技能处理
3. **易于维护**：鉴权逻辑集中管理，升级时只需更新鉴权技能
4. **自动发现**：脚本自动查找鉴权技能路径，无需手动配置

### 业务脚本列表

| 脚本文件 | 功能 | 调用方式 |
|---------|------|---------|
| scripts/get_ad_accounts.py | 获取广告账户列表 | `python scripts/get_ad_accounts.py <平台>` |
| scripts/create_sync_task.py | 创建人群同步任务 | `python scripts/create_sync_task.py <params_JSON>` |
| scripts/query_sync_task.py | 查询同步任务状态 | `python scripts/query_sync_task.py <查询参数>` |
| scripts/check_credentials.py | 检查凭证配置状态 | `python scripts/check_credentials.py` |
| scripts/check_task_logger.py | 检查任务记录技能 | `python scripts/check_task_logger.py <任务ID>` |

**注意：** 所有脚本都通过鉴权技能调用API，无需单独配置环境或域名。

### API端点映射

| 功能 | API端点 |
|------|---------|
| 获取广告账户 | /api/open-api/audience/sync/task/advertiser/list |
| 创建同步任务 | /api/open-api/audience/sync/task/create |
| 查询同步任务 | /api/open-api/audience/sync/task/list |

### 平台编码映射

| 平台名称 | 平台编码 | 说明 |
|---------|---------|------|
| oceanengine | 1 | 字节DMP |
| tencent | 2 | 腾讯DMP |
| alipay | 3 | 支付宝DMP |
| bilibili | 4 | B站DMP |
| xiaohongshu | 5 | 小红书灵犀 |

### 依赖关系

```
mingdata-dmp-sync（本技能）
├── mingdata-dmp-auth（必需）- 提供API鉴权和调用能力
└── skill-logger（可选）- 提供任务记录能力
```

## 常见问题

### Q: 为什么需要安装鉴权技能？
A: 鉴权技能提供统一的API调用接口，处理凭证管理、签名生成等复杂逻辑，确保API调用的安全性和稳定性。

### Q: 如果鉴权技能未安装会怎样？
A: 业务脚本会提示"未找到鉴权技能，请先安装mingdata-dmp-auth技能"，并终止执行。

### Q: 支持哪些广告平台？
A: 目前支持字节DMP、腾讯DMP、支付宝DMP、B站DMP、小红书灵犀共5个主流广告平台。

### Q: 同步任务需要多久完成？
A: 同步时间取决于人群包大小和平台处理速度，通常在几分钟到几小时不等。您可以通过"查询同步任务"功能实时查看进度。

### Q: 字节DMP和小红书的条件参数是什么？
A: 字节DMP需要提供云图相关参数（isToBytedanceBrand、bytedanceBrandVirtualAdvId、bytedanceBrandName），小红书需要提供广告账户品牌（advertiserBrand）。

### Q: 如何查询历史同步任务？
A: 可以使用查询功能按状态、时间范围、任务ID等条件查询历史任务。如果安装了任务记录技能，还可以查看完整的任务历史记录。

---