Metadata

name: 明日dmp批量打通圈包
description: 基于明日DMP OPEN API 的“人群打通服务”，批量创建打通人群任务（/api/open-api/audience/idlink/create）。支持项目化分批创建（每批最多5个、同批串行、批间等待本批计算完成）、状态追踪，并在执行结束输出人群名称与人群ID汇总。支持两种参数输入方式：1）上传Excel/CSV批量导入；2）对话框一次性输入完整参数（单条或多条）。

明日dmp批量打通圈包

能做什么

批量创建 打通人群任务（人群类型 audienceType=5），创建接口对应 OPEN API：/api/open-api/audience/idlink/create。
项目化批量创建 + 状态追踪：支持分批策略（每批最多5个任务、同批串行创建、批间等待本批全部计算完成后再进入下一批），并在结束时输出完整汇总（人群名称 + 人群ID）。
支持两种输入方式：
1. 表格导入（推荐）：上传 Excel/CSV，一行一条打通任务（可填人群ID或人群名称，系统自动匹配）。
2. 对话输入：用户在对话框中一次性输入完整参数（单条或多条 JSON，均为中文字段）。人群可通过ID或名称指定。如参数不完整会提示补全。

说明：被打通的人群名称无需用户提供，将通过"人群列表查询接口"按人群ID自动查询，用于自动生成默认新名称。但用户必须在参数确认环节明确确认新名称（可采纳默认命名或自定义）。

🔴 人群状态定义（audienceStatus）

关键：只有 audienceStatus=1 才表示创建成功，其他状态均不可视为成功。

audienceStatus	含义	说明
0	❌ 失败	人群创建/计算失败，不可使用
1	✅ 成功	人群创建并计算完成，可正常使用
2	⏳ 等待中	已提交，排队等待计算
3	🔄 计算中	正在计算，尚未完成

⚠️ 判定规则：

在轮询监控和结果汇总时，仅当 audienceStatus=1 时才判定为成功
audienceStatus=2 或 3 时需继续等待，不可跳过或判定为成功
audienceStatus=0 时判定为失败，按失败处理策略执行
禁止将 2、3 状态误判为成功

重要声明

使用前请阅读：references/免责声明与安全提示.md

前置准备

明日DMP OPEN API 凭证（Access Key / Secret Key）。
本地可用的鉴权能力（用于签名与API调用）。

如检测到鉴权能力或凭证缺失，本技能会在对应步骤提示你阅读并执行：

references/技能安装与环境检查.md
references/凭证获取指南.md

工作流程（独立技能流程）

本技能按“项目”管理一次批量打通：收集参数 → 校验 → 生成执行计划 → 用户确认 → 分批创建 → 监控/轮询 → 汇总输出。

第一步：场景识别

识别为【批量打通人群项目】。

第二步：鉴权检查与凭证配置（脚本化）

运行前置校验（强制）：

python3 scripts/preflight_check.py --action create_first --project <project_id可留空>

若返回阻塞项包含“鉴权技能未安装”或“凭证缺失/不完整”，请按以下顺序处理：

读取：references/技能安装与环境检查.md
凭证申请：references/凭证获取指南.md
凭证写入：python3 scripts/setup_credentials.py <AK> <SK>

说明：本技能不会通过逐条追问来收集AK/SK；缺失时会提示你按上述文档与脚本一次性补齐。

第三步：参数收集（两种方式二选一，一次性收齐，禁止逐条追问）

AI必须在第一次交互时就列出所有参数（含必填/可选、默认值、取值说明），禁止分步追问。如果用户参数不完整，一次性指出所有缺失项。

参数一览（全量必填）

⚠️ 所有字段均为必填，无一项可选。AI 必须在第一次交互时列出全部字段，禁止遗漏。用户必须逐项确认后才能进入下一步。

字段	必填	说明	取值/默认值
被打通的人群（ID或名称二选一）	✅	指定要打通的人群包	可传人群ID（数字）或人群名称（字符串，支持关键词模糊搜索）；如名称匹配到多个结果，会列出候选项供你选择
打通方向	✅	从哪端打通到哪端	`移动端→OTT端` 或 `OTT端→移动端`
输入终端ID类型	✅	原始人群包的设备ID类型	移动端：`MD5_IDFA,MD5_IMEI,MD5_OAID` 等；OTT：`MD5_MAC`；逗号分隔可多选
输出终端ID类型	✅	要打通到的目标设备ID类型	移动端：`MD5_IDFA,MD5_IMEI,MD5_OAID`；OTT：`MD5_MAC`；逗号分隔可多选
新名称	✅	打通后的人群包名称	默认命名：`原人群名_ott`（打通到OTT）或 `原人群名_mobile`（打通到移动端）。用户须确认是否采纳默认名或提供自定义名称，未确认不得继续
打通类型	✅	打通类型名称	默认 `TV-移动端跨屏打通`，用户须确认或自定义
所属品牌	✅	指定品牌创建任务	v1.4新增。先调用 `python3 scripts/query_brand_list.py --format table` 查询品牌列表，展示给用户选择；用户选具体品牌→brands=["xxx"]；用户选"全部"/未选→brandId=[]（默认全部品牌）
MAC格式过滤	✅（仅跨屏打通）	是否输出标准MAC格式	v1.4新增（ieeeFlag）。仅TV-Mobile跨屏打通时询问：`1`=仅保留IEEE标准格式MAC（如00:1A:2B:3C:4D:5E），`0`/不传=保留所有格式。需向用户说明并确认

⚠️ 输入/输出终端ID类型没有默认值，必须由用户明确选择。打通方向与ID类型必须匹配（见下方匹配关系），系统会做校验但不会替用户填充。 ⚠️ 新名称和打通类型虽提供默认值，但属于必填项——AI 须向用户展示默认命名方式，用户必须明确确认（采纳默认或自定义）后才可继续。

打通方向与ID类型匹配关系（校验规则）：

打通方向	inputTrackType	输入ID类型可选值	outputTrackType	输出ID类型可选值
移动端→OTT端	MOBILE	MD5_IDFA / MD5_IMEI / MD5_OAID / IDFA / OAID / CAID / MD5_CAID（可多选，逗号分隔）	OTT	MD5_MAC
OTT端→移动端	OTT	MD5_MAC	MOBILE	MD5_IDFA / MD5_IMEI / MD5_OAID / IDFA / OAID / CAID / MD5_CAID（可多选，逗号分隔）

AI首次提示模板（必须使用）

收集参数时，AI必须一次性列出所有必填字段，禁止省略、禁止替用户填默认值：

请提供打通任务参数（支持上传Excel/CSV，或对话框直接发JSON）。

必填字段（全部必填，每一项都必须由用户确认）：
1. 被打通的人群（ID或名称二选一）：
   · 输入人群ID：直接填数字，如 123456
   · 输入人群名称：填名称关键词，如"测试白领"，系统会搜索匹配，如匹配到多个会列出候选项供你选择
2. 打通方向：移动端→OTT端 或 OTT端→移动端
3. 输入终端ID类型（逗号分隔，多选）：
   · 移动端人群常用：MD5_IDFA,MD5_IMEI,MD5_OAID
   · OTT人群：MD5_MAC
4. 输出终端ID类型（逗号分隔，多选）：
   · 打通到OTT：MD5_MAC
   · 打通到移动端：MD5_IDFA,MD5_IMEI,MD5_OAID
5. 新名称：打通后的人群包名称
   · 默认命名方式：原人群名_ott（打通到OTT）或 原人群名_mobile（打通到移动端）
   · 你可以采纳默认名称，也可以自定义，但必须明确告知
   · ⚠️ 如未确认新名称，将不会继续执行
6. 打通类型：默认为 "TV-移动端跨屏打通"，你确认使用默认或提供自定义值
7. 所属品牌：先查询品牌列表供您选择
   · 调用接口查询当前租户下的所有品牌
   · 展示品牌列表供您选择（回复序号/brandId，或回复"全部"使用全部品牌）
   · 示例：1. Olay(olay) 2. SK-II(skii) 3. 全部品牌
8. MAC格式过滤（仅跨屏打通时询问）：
   · 是否只输出IEEE标准格式MAC地址？
   · ieeeFlag=1：仅保留标准格式（如00:1A:2B:3C:4D:5E），过滤掉非标准格式（如001A-2B3C-4D5E、a1b2c3d4e5f）
   · ieeeFlag=0/不传：保留所有MAC格式
   · 示例：回复"1"仅保留标准格式，回复"0"保留全部

JSON示例（用人群ID）：
[{"被打通的人群ID": 123456, "打通方向": "移动端→OTT端", "输入终端ID类型": "MD5_IDFA,MD5_IMEI,MD5_OAID", "输出终端ID类型": "MD5_MAC", "新名称": "原人群名_ott", "打通类型": "TV-移动端跨屏打通", "品牌": ["olay"], "MAC格式过滤": 1}]

JSON示例（用人群名称）：
[{"被打通的人群名称": "测试白领", "打通方向": "移动端→OTT端", "输入终端ID类型": "MD5_IDFA,MD5_IMEI,MD5_OAID", "输出终端ID类型": "MD5_MAC", "新名称": "测试白领_ott", "打通类型": "TV-移动端跨屏打通", "品牌": [], "MAC格式过滤": 0}]

方式1：上传表格（Excel/CSV）

推荐表头（面向业务人员，仅中文字段，全部必填）：

被打通的人群ID 或被打通的人群名称（二选一必填；填名称时系统自动搜索匹配，匹配到多个会让用户确认）
打通方向（必填：移动端→OTT端 / OTT端→移动端）
输入终端ID类型（必填；逗号分隔，如：MD5_IMEI,MD5_IDFA,MD5_OAID 或 MD5_MAC）
输出终端ID类型（必填；逗号分隔，无默认值，必须由用户选择）
新名称（必填；默认命名：原名_ott 或原名_mobile，用户须确认或自定义）
打通类型（必填；默认TV-移动端跨屏打通，用户须确认或自定义）
品牌（可选；填品牌ID，逗号分隔；不填/空=全部品牌。v1.4新增）
MAC格式过滤（可选；1=仅标准格式MAC，0/空=全部格式。仅跨屏打通有效。v1.4新增）

方式2：对话框输入（一次性JSON）

用户在对话框中一次性提供完整参数：

单条任务：一个 JSON 对象
多条任务：一个 JSON 数组

如参数不完整，系统会一次性列出所有缺失/错误字段并终止本次执行（禁止逐条追问模式）。

⚠️ 名称匹配规则：若用户输入人群名称，系统会通过关键词搜索人群列表：

精确匹配到1个 → 自动选用，进入下一步

模糊匹配到多个 → 列出候选项（含ID、名称、量级、状态），由用户选择

未匹配到 → 提示用户核对名称或改用人群ID

第四步：参数校验

校验必填字段完整性（所有6个字段均为必填，缺一不可）
校验新名称是否已由用户明确确认（采纳默认或自定义）；未确认则终止，要求用户补充
校验打通类型是否已由用户明确确认；未确认则终止，要求用户补充
校验 trackType 与 idTypes 的匹配关系（MOBILE/OTT）
校验 outputTrackType 与 inputTrackType 的互斥关系

第五步：生成执行计划

计算总任务数 N
生成批次：每批最多 5 个任务

第六步：参数确认（强制）

展示执行计划并等待用户明确确认后才创建。

第六步B：流程完整性验证（强制）

第六步C：失败处理策略确认（强制）

在批量执行过程中，可能出现两类失败：

创建失败：调用创建接口失败（未拿到 audienceId）
计算失败：创建成功但计算状态为失败（audienceStatus=0）

🔴 再次强调：audienceStatus 仅在值为 1 时才算成功。0=失败、2=等待中、3=计算中，均不可视为成功。

请提前确认处理策略（与批量圈包保持一致）：

【创建失败时】
- a) 暂停等待（pause）：停止后续任务，等待“重试/跳过/取消”指令
- b) 自动跳过（skip）：记录失败并继续创建下一条
【计算失败时】
- a) 暂停等待（pause）：停止进入下一批，等待“重试/跳过/取消”指令
- b) 自动跳过（skip）：记录失败并继续后续批次

请选择策略组合：

输入 1a+2a：创建失败暂停 + 计算失败暂停（默认推荐）
输入 1a+2b：创建失败暂停 + 计算失败跳过
输入 1b+2a：创建失败跳过 + 计算失败暂停
输入 1b+2b：创建失败跳过 + 计算失败跳过

执行脚本会按策略运行（对应参数：--on-create-fail pause|skip、--on-exec-fail pause|skip）。

第六步D：监控方案（强制使用cron，禁止后台exec轮询）

🔴 三种方式的强制约束：

方式	是否允许	原因
✅ `cron(action="add", job={...})` 工具	必须使用	绑定当前session，每60秒自动触发agent turn，完成后可自动通知用户和推进下一批
❌ `openclaw cron add` 命令行	严格禁止	无法设置sessionTarget=current，会绑定到isolated session导致监控无法触发
❌ `exec(background=true)` + `sleep` + 手动轮询	严格禁止	后台进程在session休眠/断连后不会唤醒AI，导致任务完成后无法通知用户（已发生过此故障）

监控规则与禁用项： 阅读 references/监控规则与禁用项.md

cron监控任务创建规范（必须在第一批任务创建成功后立即执行）：

cron(action="add", job={
    "name": f"DMP打通监控-{project_id}",
    "schedule": {"kind": "every", "everyMs": 60000},
    "payload": {
        "kind": "agentTurn",
        "message": f"检查DMP批量打通项目{project_id}状态：运行 python3 scripts/run_idlink_project.py --mode monitor --project-id {project_id} 推进批次；若本批完成则创建下一批；全部完成则汇报结果并删除此cron任务。"
    },
    "sessionTarget": "current",
    "delivery": {"mode": "none"}
})

cron任务触发时的执行流程：

运行 python3 scripts/run_idlink_project.py --mode monitor --project-id <id> 检查当前批状态
若本批全部计算完成 → 自动创建下一批任务
若所有批次完成 → 输出汇总结果，主动通知用户，并调用 cron(action="remove", ...) 删除监控任务
若有失败 → 按第六步C确认的失败策略处理（pause则通知用户等待指令，skip则记录后继续）

🔴 自我检查清单（每次创建第一批任务后必须逐项确认）：

我是否使用了 cron 工具（不是exec background，不是命令行）？
sessionTarget 是否设置为 "current"？
delivery 是否设置为 {"mode": "none"}？
payload.message 是否包含了项目ID、monitor命令、完成后删除cron的指令？
创建cron后是否向用户确认了监控已启动？

第七步：执行创建（仅接口变化）

创建接口（OPEN API）：/api/open-api/audience/idlink/create
通过鉴权能力调用时的 endpoint 路径：/audience/idlink/create
分批规则：
- 任务数 ≤ 5：逐个串行创建
- 任务数 > 1：按每批 1 个分批创建；同批只等创建接口返回成功，不等计算完成；批间必须等本批全部计算完成再创建下一批

统一执行入口：

表格方式：python3 scripts/run_idlink_project.py --file <excel_or_csv>
对话JSON：python3 scripts/run_idlink_project.py --json '<json_object_or_array>'

第八步：任务记录技能检查（必须执行）

目的：把本次项目的 projectId、执行时间、创建成功的人群ID清单写入历史，便于后续追溯。

执行检查脚本（强制）：

python3 scripts/check_task_logger.py <project_id> <audience_name可选> <task_count可选>

分支处理（与批量圈包一致）：

若提示已安装：按提示完成“记录到历史”的动作，并在第九步展示记录结果（项目ID、存储路径）。
若提示未安装：阅读 references/技能安装与环境检查.md，询问用户是否安装：
- 选择“是”：执行安装（以当前环境可用方式为准），安装后再次执行检查脚本
- 选择“否”：本次跳过记录，不影响主流程，但第九步仍需展示“已跳过记录”的说明

第九步：结果展示与用户通知（强制）

🔴 当所有批次全部计算完成（或全部失败/跳过后），必须主动向用户返回完整的创建人群信息汇总，不得省略。

通知时机

所有批次均已完成（成功/失败/跳过）后，立即主动通知用户
通知方式：通过当前 session 直接发送消息（无需用户询问）

必须返回的信息（完整汇总表）

序号	人群名称	人群ID	打通方向	人群量级	audienceStatus	状态说明
1	xxx_ott	123456	移动端→OTT端	1,234,567	1	✅ 成功
2	xxx_mobile	123457	OTT端→移动端	890,123	0	❌ 失败：xxx原因
...	...	...	...	...	...	...

汇总内容要求（每条人群都必须包含）

人群名称：打通后的新名称
人群ID：创建返回的 audienceId
人群量级：打通后人群包的设备数量（从查询接口获取）
打通方向：移动端→OTT端 / OTT端→移动端
audienceStatus 值 + 状态说明：1=成功、0=失败、2=等待中、3=计算中
失败原因（如有）：创建失败或计算失败的具体原因

统计摘要（必须包含）

📊 批量打通项目汇总
项目ID：xxx
总任务数：N
✅ 成功：X 个（audienceStatus=1）
❌ 失败：Y 个（audienceStatus=0）
⏳ 未完成：Z 个（audienceStatus=2或3）
执行时间：YYYY-MM-DD HH:MM ~ HH:MM

同时落盘

汇总结果写入项目 result.json（脚本自动完成）
任务记录写入历史（见第八步）

⚠️ 即使用户没有主动询问，也必须在全部完成后主动发送汇总。不得以"任务完成"一句话带过，必须包含完整表格和统计。

Scripts

scripts/run_idlink_project.py：批量打通项目统一执行入口（读取输入→校验→分批创建→批间轮询→汇总落盘）
scripts/preflight_check.py：前置校验（鉴权能力/凭证/上一步任务状态等硬拦截）
scripts/cron_helper.py：🔴 cron监控硬约束工具（代码级拦截）
- check：monitor模式/推进下一批前检查锁文件，未设置cron则拒绝执行（exit 1/2）
- mark-cron-set --cron-name <名字>：AI创建cron任务后必须调用此命令写入锁文件
- cleanup：全部完成后清理锁文件，提示AI删除cron任务
- gen-cron-params：生成标准cron任务参数
scripts/check_task_logger.py：任务记录能力检查提示
其他辅助脚本：鉴权查找、任务状态轮询等

🔴 cron硬拦截工作机制（代码级保证）

init创建第一批成功
      ↓
脚本输出cron_params + mark-cron-set指令 + exit 0
      ↓
🔴 AI必须执行：
  1. cron(action="add", job=cron_params)  ← 创建cron
  2. python3 scripts/cron_helper.py mark-cron-set  ← 写入锁文件
      ↓
cron每分钟触发 → monitor模式
      ↓
monitor入口 check_cron_setup()
  ├─ 锁文件存在 → 正常推进
  └─ 锁文件不存在 → exit 2，输出拦截提示
      ↓
全部批次完成
      ↓
cron_helper cleanup → 提示AI删除cron任务

这意味着：即使AI忽略提示词、忘记创建cron、或session断连，monitor模式也会拒绝执行，从而强制AI必须先创建cron才能推进。

执行结束的汇总输出（强制）

无论创建是否全部成功，批量任务执行结束后都会输出汇总表（并同时写入项目 result.json）。

🔴 成功判定标准：仅 audienceStatus=1 判定为成功。audienceStatus=0（失败）、2（等待中）、3（计算中）均不计入成功。

成功（audienceStatus=1）：人群名称 + 人群ID
失败（audienceStatus=0）：人群名称 + 失败原因
未完成（audienceStatus=2或3）：人群名称 + 当前状态（等待中/计算中）+ 说明

明日dmp批量打通圈包

安装技能

明日dmp批量打通圈包

能做什么

🔴 人群状态定义（audienceStatus）

重要声明

前置准备

工作流程（独立技能流程）

第一步：场景识别

第二步：鉴权检查与凭证配置（脚本化）

第三步：参数收集（两种方式二选一，一次性收齐，禁止逐条追问）

参数一览（全量必填）

AI首次提示模板（必须使用）

方式1：上传表格（Excel/CSV）

方式2：对话框输入（一次性JSON）

第四步：参数校验

第五步：生成执行计划

第六步：参数确认（强制）

第六步B：流程完整性验证（强制）

第六步C：失败处理策略确认（强制）

第六步D：监控方案（强制使用cron，禁止后台exec轮询）

第七步：执行创建（仅接口变化）

第八步：任务记录技能检查（必须执行）

第九步：结果展示与用户通知（强制）

通知时机

必须返回的信息（完整汇总表）

汇总内容要求（每条人群都必须包含）

统计摘要（必须包含）

同时落盘

Scripts

🔴 cron硬拦截工作机制（代码级保证）

执行结束的汇总输出（强制）

360 行为纵深安全审计引擎