明日Dmp人群同步

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

概述

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

⚠️ 重要声明：

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

🔑 前置准备

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

📧 申请方式（二选一）：

方式一：邮件申请

• 发送至：[e-mail]
• 邮件主题：【明日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），才能使用人群同步功能。

📧 申请方式（二选一）：

方式一：邮件申请
- 发送开通申请至：[e-mail]
- 邮件主题：【明日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 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
• 查看当前可用的广告账户

触发方式：

• "查询小红书广告账户"
• "获取腾讯广告账户列表"
• "我有哪些快手广告账户"

脚本调用：

python scripts/get_ad_accounts.py xiaohongshu

支持的平台：

• oceanengine（字节DMP）
• tencent（腾讯DMP）
• alipay（支付宝DMP）
• bilibili（B站DMP）
• xiaohongshu（小红书灵犀）

2. 创建人群同步任务

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

使用场景：

• 将圈选的目标人群同步到广告平台进行投放
• 实现跨平台的精准营销

触发方式：

• "将人群123456同步到小红书"
• "创建人群同步任务"
• "同步人群到腾讯广告"

脚本调用：

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进度如何"

脚本调用：

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

---