明日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（凭证检查）
• 如果未安装 → 向用户展示以下提示并等待回复

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

text

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

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

是否自动下载并安装？

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

请回复：是/否

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

• 用户回复"是"：

  • 使用 terminal 工具执行： openclaw skills install mingdata-dmp-auth

  • 等待命令执行完成

  • 安装成功：提示 ✅ 鉴权技能安装成功 → 继续步骤2.2

  • 安装失败：展示以下内容后 终止流程： text

    ❌ 鉴权技能自动安装失败
    
    请前往 ClawHub 手动安装：
    👉 https://clawhub.ai/mingri26/mingdata-dmp-auth
    
    手动安装步骤：
    

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

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

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

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

- **凭证文件路径**： `~/.mingdata_dmp_credentials`
- **如果凭证不存在** → 展示凭证获取指引（见下方）
- **如果凭证存在但无效** → 引导重新配置
- **如果凭证有效** → 继续执行第三步（参数收集）

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

text

🔑 明日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**广告账户品牌**品牌名称（小红书必填）

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

text

请确认以上参数是否正确？

• 回复"确认"或"是"：开始创建同步任务
• 回复"修改"：重新设置参数
• 回复"取消"：取消本次操作

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

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

python

```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（自动记录任务）
• 如果未安装 → 向用户展示以下提示并等待回复

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

text

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

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

是否自动下载并安装？

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

请回复：是/否

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

• 用户回复"是"：

  • 使用 terminal 工具执行： openclaw skills install skill-logger

  • 等待命令执行完成

  • 安装成功：提示 ✅ 任务记录技能安装成功 → 继续步骤8.2（记录任务）

  • 安装失败：展示以下内容，等待用户选择： text

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

    • 用户回复 A：等待用户确认安装完成 → 继续步骤8.2（记录任务）→ 进入第九步
    • 用户回复 B：提示 已跳过任务记录 → 直接进入第九步
• 用户回复"否"：
  • 提示： 已跳过任务记录，不影响主流程。
  • 直接进入第九步

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

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

• 记录内容：任务ID、任务名称、创建时间、参数配置

• 必须向用户展示记录结果： text

  ✅ 任务记录技能已安装
  ✅ 任务已自动记录到历史
   - 任务ID：人群同步_20260610102000
   - 存储路径：/home/sandbox/.skill-logger/task_history.json
  

- **禁止静默执行**：即使技能已安装，也必须告知用户"已自动记录"

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

**⚠️ 前置条件检查**：
在执行第九步之前，必须确认：

- 第八步（任务记录检查）是否已执行？
- 是否已检查skill-logger安装状态？
- 是否已询问用户是否需要安装（如果未安装）？

**成功时：**

展示任务创建成功信息：

- 任务ID
- 预计完成时间（通常几分钟到几小时）
- 后续操作建议

**后续操作建议：**

text

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

任务信息：

• 任务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

```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调用流程：

text

业务脚本 → 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.pyscripts/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

平台编码映射#

平台名称平台编码说明oceanengine1字节DMPtencent2腾讯DMPalipay3支付宝DMPbilibili4B站DMPxiaohongshu5小红书灵犀

依赖关系#

text

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等条件查询历史任务。如果安装了任务记录技能，还可以查看完整的任务历史记录。

---