DataMax Ad Measurement MCP

凭证是 Access Key，能做什么由两道正交约束共同决定：Key 类型与授权工作空间。 类型只有两种，控制台里就叫这两个名字，转述给用户时别自创说法：

| whoami 返回的 scope | 类型 | 能做什么 | |------|------|------| | read | 只读 Key | 只能查 | | standard | 管理 Key | 只读的全部能力 + 建监测、建品牌、撤链接、改工作空间名 |

standard 是历史存储值，不是「标准 Key」——对用户一律说「管理 Key」。 工具清单按类型裁剪——只读 Key 的 tools/list 里根本不会出现写工具。

共享演示空间：控制台允许给一把只读 Key 单独授权「共享演示空间」——一份所有账户共用的 只读演示数据，用来在没有真实投放前先跑通链路。它在 list_workspaces 里就叫「共享演示空间」， 其下的品牌、监测链接与测量数据都能正常查——但只有测量那半边，人群激活的工具在演示空间下 一律被拒（见「人群激活」末尾）。两条约束是控制台强制的：只能配只读 Key，且只能单独授权 （不能和用户自己的空间共用一把 Key）。所以如果用户说「演示空间和我的空间要用同一把 Key」， 答案是不行，得分开建两把。

tools/list 是唯一权威。本文档描述的是当前版本；实际连上后以 tools/list 为准， 不要因为文档提到某个工具就假定它一定在。

接入

| 环境 | 地址 | |------|------| | 生产 | https://dm.addnewer.com/mcp | | 测试 | https://dmtest.addnewer.com/mcp |

{
  "mcpServers": {
    "datamax-measurement": {
      "type": "http",
      "url": "https://dm.addnewer.com/mcp",
      "headers": { "X-API-Key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Authorization: Bearer <key> 等效。Key 在控制台「Agent 接入」页创建，必须勾选至少 一个授权工作空间，且只在创建时可见完整值——用户没记下就只能重建，别让他们去列表页找。

创建时还要选类型（管理 / 只读）与有效期，两者创建后都不可改：要建监测就得选管理 Key， 拿只读 Key 去建只能重建一把新的。

整个端点都要鉴权（含 initialize 与 tools/list），所以「连不上」和「调用被拒」往往是同一个 原因：Key 没配对。

工具总览

完整入参与返回见 TOOLS.md。

| 分组 | 只读 Key 可用 | 需管理 Key | |------|------|-----------| | 身份 | whoami list_workspaces | rename_workspace | | 资源 | list_brands get_quota | create_brand | | 监测 | list_monitor_links get_monitor_link | create_monitor revoke_monitor_link | | 数据 | measure_summary measure_trend measure_geo measure_platform measure_top measure_group measure_frequency measure_quality measure_monitor_detail measure_monitor_uv measure_monitor_metrics measure_dimensions | — | | 授权 | list_platform_auths start_platform_auth | — | | 人群 | list_audience_dimensions list_audience_areas estimate_audience list_audience_packages get_audience_package | create_audience_package | | 推送 | list_audience_pushes get_audience_push get_audience_portrait_url | create_audience_push start_audience_push retry_audience_push retry_audience_push_part generate_audience_portrait |

前四组是测量（建监测、看数据），后三组是人群激活（把测量数据攒出的人推给媒体投放）。 两条线共用工作空间与品牌/活动编码，但平台枚举是两套，见下节最后一条。

五条会导致结论错误的口径

这些不是细节，答错一条整个分析就是错的。引用数据时要把口径一并转述给用户。

1. pv 是次数，uv 是人数。一个人看 3 次：pv 记 3，uv 记 1。
2. uv 是累积快照，不是区间量。口径为「截至区间末的近 100 天累积去重人数」， 不能跨天相加，也不能跨行相加（同一个人可能出现在多条监测里）。 要「这段时间内真实发生了多少」一律用 pv。因此没有 uv 的按小时口径。
3. 地域只有 PV，且有隐私阈值。数据源里没有「地域 × 去重人数」，问不出「某地有多少人看过」； 有效曝光量过低的地域不会被整行剔除，而是保留地域名照常返回一行，只把 imp_pv / click_pv / ctr 归零并置 suppressed=true。那三个 0 不是真实值——看到 suppressed=true 只能说「量太少不予展示」，绝不能读成「那里真的零曝光」或「那里没投放」 （区县级下钻尤其常见），各地域之和也不等于总量。
4. link_id 与 id 是两个东西。link_id 是监测 ID（字符串），用于数据工具的筛选与下钻； id 是内部主键（数字），只有 get_monitor_link / revoke_monitor_link 用它。 两者都在 list_monitor_links 的返回里，别拿错。
5. 所有编码一律原样传，不要自己拼。库里新旧两代格式并存 （campaign_code 有 C000600001 也有 M01205593196967755776），没有可依赖的规律。 brand_code 则是品牌 id 的十进制串（如 "6"）。

另有一条基础事实：测量侧的平台编码只有一套——xhs 小红书 / dy 抖音 / tx 腾讯广告 / ty 通用。list_monitor_links 返回的 platform 可以直接当数据工具的 platform_code 用。 但人群激活侧是另一套：oceanengine 巨量引擎 / tencentads 腾讯广告广点通 / jdshufang 京东数坊 / databank 品牌数据引擎 / yuntu 巨量云图 / ruyi 腾讯如翼。 两套刻意分开、不通用——tx 不是 tencentads，别互相代入。

这六个平台里 ruyi 只授权、不推送：它不在 create_audience_push 的平台枚举里， 授权它是为了给广点通分包算画像。其余五个才是推送目标。 能力也不齐：人群画像有四个平台——yuntu 用云图自己的画像；tencentads 借腾讯如翼的洞察 能力生成（需先完成如翼授权）；jdshufang 读京东数坊「透视」算好的结果（要用户先在数坊站内 点过「透视」，DataMax 代劳不了）；databank 走品牌数据引擎的「标签透视」。 只有 oceanengine 没有这个能力（见「人群激活」第四段）。

监测组

活动与链接之间还有一层监测组：一个组绑定一个平台，imp（曝光）与 click（点击） 是两个开关，勾上即各出 1 条链接——没有数量参数，组内至多一条曝光 + 一条点击。 同一平台要 5 条曝光就得建 5 个组。组的对外编码是 MG 开头的 monitor_group_code， 也就是链接 URL 上的 mg 参数。

配成一组是为了让点击率有意义：只有组内曝光与点击都在（pairing_state=paired）， 这个组的点击率才算得准。只建了一侧、或事后撤掉一条，该组就产不出可信的点击率。

问「某一批链接的点击率」一律用 measure_group，那是唯一按组算 ctr 的工具：一条链接只采一种 事件，所以点击率的最小可算单位是组而不是链接，measure_monitor_detail 逐行的 ctr 基本恒为 0 就是这个缘故。其余 measure_* 返回的 ctr 是筛选范围内 click_pv / imp_pv 的原始比值， 不会自动剔除没配对的组——组配得不全时要把这一点告诉用户。

监测组模型上线前建的老链接不属于任何组，monitor_group_id / monitor_group_code 都为空。这是历史遗留，不是数据缺失。

人群激活

把测量攒下的人推给媒体投放。三段链路各有一个必须提前转达给用户的前提，漏掉哪个都会卡住； 推到巨量云图、腾讯广告广点通、京东数坊或品牌数据引擎的人群还能再走第四段——生成人群画像 （oceanengine 是唯一没有画像能力的推送目标）。

一、平台授权（oceanengine 巨量引擎 / tencentads 腾讯广告广点通 / jdshufang 京东数坊 / databank 品牌数据引擎 / yuntu 巨量云图 / ruyi 腾讯如翼）。

授权只能由用户在 DataMax 网页端完成，你代劳不了任何一步，也没有任何 Key 能代劳。 start_platform_auth 给的是 DataMax 授权页的地址（console_url）与这个平台的操作步骤（steps）—— 原样转达，别改写顺序也别自己概括。六个平台分两种方式：巨量引擎与腾讯广告在页面上点一下会新开 标签跳媒体官方授权页；京东数坊、品牌数据引擎、巨量云图、腾讯如翼没有开放平台授权，要先装「DataMax 平台连接器」浏览器扩展，全程在 DataMax 页面上做完。各平台最后一步差别很大（数坊勾服务账号、 品牌数据引擎登录后还得点「进入数据银行」并选品牌、云图勾品牌、如翼没得勾但要核对识别出的账号）， 这些 steps 里都写好了。

走 OAuth 的那两家（巨量引擎、腾讯广告）在媒体授权页上勾选时，要勾具体的投放账户：只勾 代理商 / 纵横组织的话，list_platform_auths 里照样显示「授权完成」，直到 create_audience_push 才被拒。这句在 steps 里，但值得你在用户动手之前再单独强调一遍——事后返工要解除重来。

如翼授权是为画像服务的：用户想要广点通人群的画像却还没授权如翼时，就用 start_platform_auth(platform="ruyi") 给他指引。它走扩展链路，用户在 ruyi.qq.com 登录自己的 腾讯广告账号后扩展把会话送回 DataMax；授权对应的是他当时登录的那个账号，换账号要先在如翼 切换登录再回来点「重新识别账号」。

要提前说清的前提：用户得用本 Key 所属的那个 DataMax 账号登录，并在授权页上把「授权空间」 选成说好的那个工作空间——授权归属建好之后不能迁移，选错只能解除重来。

确认授权成没成只有一个办法：用户说做完之后，调 list_platform_auths（带 platform 与 status=completed）看账户在不在。这条链路没有可查询的进度，不存在「正在授权中」可以轮询—— 没做完就是列表里没有。

授权账户里只有 status=completed 的能推，还要看 account_category：巨量引擎的授权会把云图、 星图、工作台、代理商等各业务线的账号一并带回来且全都是 completed，只有 engine（投放账户） 推得动，挑错了要到 create_audience_push 才被拒。这个字段只有巨量引擎有值。 授权失效看 fail_code（refresh_failed / verify_failed / revoked_by_user）而不是 fail_reason； 走扩展的那三家失效多半是浏览器会话过期，要用户重新登录那个平台，不是重走一遍授权。 解除授权与更换任务的授权账户不在工具集内，只能去页面上操作。

二、圈选人群包。list_audience_dimensions 是入口，有三级级联：只传 workspace_id 拿品牌 → 带上 brand_codes 才下发活动 → 再带上 campaign_codes 才下发监测组。不传上一级，下一级 恒为空数组——那是级联没走到，不是「没有数据」。 规则里一律填 code 不填中文名：传品牌名、活动名不会报错，只会圈出 0 人，看起来像「这批人 真的不存在」。同理，id_types / platform_codes 选了该空间没有的取值也是静悄悄 0 人。 规则是两级结构：pools（运算池，1..4 个）× groups（条件组，每池 1..10 个）——条件组内部各维度 恒为「且」，池内用 op、池间用 pool_op 定交并，最常见的就是 1 池 1 组。 两级共用同一套取值，而且刻意只有 and / or——没有差集。所以「圈看过 A 但排除已转化的人」 「排除 B 活动那批人」这类圈法根本表达不出来，服务端的白名单里就没有这个运算符。用户提这种 需求时当场说清做不到，别先答应再去凑一个必然被拒的组合。 先 estimate_audience 试算、把 rule_expr 念给用户核对，再 create_audience_package。

create_audience_package 是异步的：返回的 status 恒为 pending / running，拿到返回不等于 算好了，别当成「已生成」转告用户。轮询 get_audience_package 的 versions[0].status 到 success 或 failed，大规模人群通常要几十秒到几分钟——这只是经验值，服务端没有对应的硬超时 阈值，别掐着某个分钟数就向用户报「卡住了/坏了」，多等一轮再看；真失败会进 failed 并带 error_msg。 两种情况直接被拒：规则算出 0 人（所以先 estimate），以及这个包上一版还在算。 同名不报错也不新建包——本次计算会成为那个包的新版本（version+1），历史版本原样保留； 想要一个独立的新人群包就换个名字。

三、推送。create_audience_push 建完就推：落库、按平台规则拆包，并立刻开始推送，返回时 任务通常已是 pushing——没有「先建着回头再决定」这个中间态，也撤不回来（媒体侧没有撤回入口，DataMax 也 没有）。所以拆包结果、skipped_id_types、推给哪个账户，全都要在调用之前跟用户确认完； start_audience_push 不是必经的第二步，它只是自动开始失败之后（推送链路没启用、授权刚失效， 任务停在 pending 且 pushed_at 为空）的重试入口。 skipped_id_types 仅创建那一次可能非空，必须逐类转达，别静默丢——它正是 identifiable_count （可识别设备数，含平台不收的类型）与 submitted_count（实际提交数）的差额来源，而且不同原因 要改的地方完全不同：有的是后台白名单没勾（改配置就能带上），有的是平台压根不收（改配置也没用）。 matched_count 是平台回的匹配人数，为 0 通常是平台还没回，不等于「匹配到 0 人」；它还可能 大于 identifiable_count（一个设备号可关联多个平台账号），所以不要拿它算损耗率、不要按 100% 封顶。 推送同样异步，用 get_audience_push 轮询，但不要按固定间隔催——各阶段耗时差一个数量级 （光巨量侧解析常规就要 20~60 分钟，整条链路预期在 30~90 分钟量级）。节奏看 platform_stage： 平台侧此刻走到哪一步的中文说明（「平台排队中」/「平台解析中」/「平台计算中」/「待发布」/ 「可投放」…）。它是自由文本不是枚举，取值会随平台链路增减，所以原样转达给用户，不要自行 归类、也不要拿它做判断（判断一律看 status）。任务级的 platform_stage 只在 status=pushing 时有意义，其余状态下为空或是上一次的残留，且显示的是最落后的那一个阶段；要答「到底哪一包卡住了」 得看分包级的 parts[].platform_stage。少了它，一个停在 pushing 两小时的任务，「正常等平台解析」 与「发布卡死」在你眼里长得一模一样。

失败之后有两条恢复路径，别只会用任务级那条。retry_audience_push(id) 把这个任务里全部 失败分包一起退回待提交；retry_audience_push_part(part_id) 只重推一个包，同任务的其它失败 分包一律不动。判据是失败原因：一次推送里几个包的失败原因往往不是一回事——一包是人群名在平台上 撞了（得先去媒体后台改名，改完这一包才有意义），另一包只是网络抖了一下（立刻重来就行）。 任务级那个会把它们一起退回，于是没修好的那包必然再失败一次，白烧一次平台配额。 所以先逐包读 parts[].fail_reason：原因各不相同就一个个单包重试，确认都属于「重来就行」才用 任务级一把全退。part_id 取自 parts[].id，既不是任务 id，也不是 part_no（那是任务内从 1 起的序号）。两个工具返回的都是整个任务的详情而不是那一包——重试会把任务从 failed 拖回 pushing。

两个重试都会把相关分包的 retry_count 清零。这个字段是自动重试次数（达到平台上限即判该包 失败），所以它读作「上次人工重试之后又自动重试了几次」，不是历史累计。清零意味着每调一次就 重新赠送一轮自动重试额度——「多调几次试试」不是无害的，病因没除掉时只是把同一个失败多烧几遍。

单包重试有两类正常拒绝，都不是故障，别当报错往上报：① 退避中的包——状态是 pending 却带着上次的 fail_reason，服务端下一轮本来就会自动重来，不必插手；② 数据已经提交到平台的包 ——云图那边已经建出数据源了，再推会在媒体侧多建一个同名人群，正确动作是等平台解析完。 任务级那个也有一条：没有失败分包时会被拒并回「无需重试」，对同一任务连着调第二次通常就是撞上 这个，说明上一次已经把它们退回待提交了。

几条硬前提，不满足会在 create_audience_push 当场被拒：人群包计算成功、未过期且人数 > 0 （有效期 90 天，判定看 usable 而不是 build_status——这三条它都算进去了；过期只挡新建推送， 不影响已建的任务）、 授权账户与人群包在同一个工作空间、平台枚举用人群激活那套推送编码（五个，ruyi 不在其中）而不是测量侧那套。 最后一条：共享演示空间用不了人群功能——连只读的维度与预估也一并拒绝（免得出现「能预估、 一点生成就被拒」的割裂），要跑这条链路得用用户自己的工作空间。

四、生成人群画像（巨量云图 / 腾讯广告广点通 / 京东数坊 / 品牌数据引擎）。四家各算各的： 云图分包由云图按它自己的标签体系算；广点通分包借腾讯如翼（ruyi）的洞察能力算——推到广点通的 人群包会同名出现在如翼，前提是用户已完成腾讯如翼平台授权（未授权时发起会被拒并说明原因，那时用 start_platform_auth(platform="ruyi") 给他授权指引）；京东数坊读的是数坊「透视」算好的结果 （见下面那条⚠️）；品牌数据引擎走它的「标签透视」，同步当场算，维度目前 6 个、没有 TGI。 oceanengine 没有这个能力。

⚠️ 京东数坊有一条其它三家都没有的前置：透视必须由用户先在数坊站内触发。 数坊的画像只能由 用户在数坊「人群管理 - 人群列表」找到目标人群（名字就是分包的 part_name）点「透视」来触发， DataMax 只能读取算好的结果、无法代为触发，没有任何工具能代劳。用户没点过时发起会明确失败， 错误文案本身就是操作指引（「京东数坊侧该人群尚未生成画像, 请先在数坊「人群管理-人群列表」找到 该人群点击「透视」生成后再试」）——原样转达给用户，不要重试：那不是系统故障，重试多少次都 一样，唯一的出路是让他去数坊点一下。四个平台里只有数坊需要用户先去平台侧做这一步。

数坊的画像维度目前是 10 个、带 TGI（这是 convert-platform 网关的封装范围，不是数坊只有这些； 洞察页里「用户偏好」那一栏在真实数据下是空的，同样是封装范围所致）。

链路：get_audience_push 取分包明细 → 挑一个满足条件的分包 → generate_audience_portrait 传它的 parts[].id → 回 get_audience_push 看 parts[].portrait_status → 转 ready 后 get_audience_portrait_url 取下载地址交给用户。用户想「看看画像」而不是要文件时，别走完这条 链路——直接把画像页地址给他（见本节末尾的 console_url）。

画像挂在分包上，不是任务上：平台那边一个分包就是一个独立人群，画像是按人群算的——一个任务 拆了几包就要分别发起几次，没有「整个任务一把画像」这回事。入参只有 part_id，取自 parts[].id， 不是任务 id，也不是 part_no。

发起前先读那一包的 portrait_disabled_reason——非空就是现在发起不了，值就是原因原文 （如「人群规模过小，暂不支持画像分析」）。它由服务端现算，与页面上画像列的 hover 文案同源， 比你自己逐条推断可靠。下面几条是它背后的判断，缺一即当场被拒：任务平台是 yuntu / tencentads / jdshufang / databank 四者之一；分包 status=success；分包有 platform_audience_id（云图要 异步解析 20~60 分钟才生成，在那之前为空不是异常）；分包 matched_count > 0，且不低于服务端的 小样本阈值（可配，当前默认 1000）——所以 matched_count 落在 1~999 时同样发起不了， 「大于 0」这一条单独看是不够的。

「数坊侧还没点透视」不在这几条里：portrait_disabled_reason 是空的，发起才失败——和 「广点通未授权如翼」是同一类，都是发起时才判、不进这个字段。

注意 portrait_disabled_reason 只对从未生成过画像的分包给原因；已经有 portrait_status 的行它恒为空，那时按状态判断。

画像状态没有独立查询接口，get_audience_push 的分包明细是唯一读法：portrait_status （空 = 未生成 / generating / ready / failed）、portrait_fail_reason（仅 failed 有值）、 portrait_ready_at（就绪时刻）、portrait_last_error（仅 generating 时可能非空：服务端 还在重试，这是最近一次暂时性失败的原因）、portrait_disabled_reason（见上）。 这几列仅有画像能力的四个平台（云图 / 腾讯广告 / 京东数坊 / 品牌数据引擎）非空， oceanengine 恒为空。它们与推送的 status / fail_reason 是两套——画像失败时该分包的推送状态仍然是 success，别互相解释。

通常几分钟，但要引导用户等：服务端兜底超时 6 小时，状态轮询退避上限 10 分钟，所以画像真算好后 portrait_status 最多还会晚 10 分钟才翻。generating 迟迟不动时看 portrait_last_error—— 非空说明服务端正在重试，它能解释卡在哪，比干等着强。而且不幂等：generating / ready 期间重复调用会被拒（就绪态不提供重新生成），failed 之后再调会真的再算一次——但距上次发起 不足 5 分钟会被频控挡下（「操作过于频繁，请 5 分钟后再试」）。用户说「再试一次」时先看时间， 别立刻重发，更别拿它当「刷新状态」的手段。

ready 之后用 get_audience_portrait_url 取下载地址（入参同样是 part_id）。它回的是一条 30 分钟就过期的地址（expires_in 是秒数），不是文件内容——那是几千行的标签占比明细 （云图、京东数坊、品牌数据引擎是 .csv，腾讯广告经如翼出的是 .xlsx，filename 里已带对扩展名； 数坊那份带 TGI，品牌数据引擎那份只有维度 / 标签 / 占比三列）， 把地址原样交给用户去下载即可，别代为解读，那份文件的读者是 Excel。给地址时把有效期一并说清， 别把它写进待办、笔记或对话摘要长期复用：过期后打开是一段 AccessDenied 报错，看起来像服务 坏了。用户过一会儿再要就重新调一次换一条，没有任何副作用；画像本身不会因为地址过期而失效， 那一包仍然是 ready。这一条是只读能力，两种 Key 都能调。

想在浏览器里看画像，就给页面地址，别给文件。 画像三个工具都回一条 DataMax 上的 画像洞察页地址：get_audience_push 的 parts[].portrait_console_url， generate_audience_portrait 与 get_audience_portrait_url 的 console_url （形如 https://dm.addnewer.com/dashboard/activation/portrait/{part_id}）。它与 get_audience_portrait_url 的 url 是两样东西：url 是文件（给 Excel 的、30 分钟过期）， console_url 是页面（给眼睛的、不过期），可以放心写进对话摘要或转发。用户没明说要文件时 优先给页面。页面要用本 Access Key 所属的那个 DataMax 账号登录，别的账号打开是 「无权限访问该画像」，转达时值得带一句。

这条地址不必等 ready 才给：还没生成时页面上有「生成画像」按钮（用户自己就能发起）， generating 时页面转圈并每 5 秒自动刷新、算好自动显示——所以刚发起完画像，与其让用户每隔几 分钟回来问一次「好了没」，不如把 console_url 给他让他自己盯着。只有一种情况拿不到这条地址： 那一包 portrait_disabled_reason 非空（现在没有画像可看），此时字段为空，别自己拼一条给用户。

错误码：40002（绝大多数情况，msg 是中文原文，可直接展示给用户）、36019（云图会话失效， 要用户重新登录云图并重新授权），取下载地址时另有 36021（画像文件暂时存取不了，服务端侧的问题， 提示稍后重试即可）；腾讯如翼未授权或会话失效另有专码。数坊与品牌数据引擎的失败原因也一律是中文原文， 照原样转达：数坊常见「尚未生成画像（去点透视）」「已找不到该人群」「登录态已失效, 请重新授权」， 品牌数据引擎常见「找不到人群」「暂不支持标签透视, 请稍后确认人群状态后重试」「会话已失效」。 走浏览器扩展的这几家（云图 / 数坊 / 品牌数据引擎）会话失效都要用户重新登录那个平台再授权，重试无用。

典型工作流

做数据分析：list_workspaces 取 id → 需要按活动/品牌收窄就先 measure_dimensions 拿准确编码（它列的是「建过什么」，不保证有数据）→ measure_summary 看总量 → 按问题展开（趋势 measure_trend、 地域 measure_geo、平台 measure_platform、排名 measure_top、 逐条监测 measure_monitor_detail）。逐条监测类工具最多回 1000 行，量大时先用筛选收窄。

建监测：list_workspaces → list_brands 决定复用 brand_id 还是新建 brand_name → 把用户的需求翻译成 groups[]（每组一个平台 + 勾 imp/click）→ get_quota 确认额度够 （消耗 = 本次新增的链接条数，append 补缺时比「平台数 × 类型数」少）→ 与用户确认参数 → create_monitor，实扣多少以返回的 consumed 为准。 往已有活动补链接用 mode=append + campaign_id，品牌与周期继承该活动；要给已有组补上 缺的那一侧，再带上 groups[].group_code（取自 list_monitor_links 的 monitor_group_code）。

排查某条链接没数据：list_monitor_links 找到 link_id → measure_monitor_metrics 看全周期累计与最后收数时刻（没回来就是一条都没收到）→ 再看 get_monitor_link 的 生效周期与状态是否已过期/被撤销。

圈人并推给媒体：list_platform_auths（带 platform + status=completed）确认有可用授权， 没有就 start_platform_auth 拿授权页地址与步骤交给用户 → 用户在 DataMax 网页端做完 → 再 list_platform_auths 确认账户在了（account_category=engine 才推得动） → list_audience_dimensions 三级拿编码（要按地域筛再加 list_audience_areas） → estimate_audience 试算，把人数与 rule_expr 交给用户确认 → create_audience_package → 轮询 get_audience_package 到 success → 推之前把人群包、目标账户、预计拆包情况跟用户确认清楚（create_audience_push 建完就推、 撤不回，之后没有第二道闸门）→ create_audience_push → get_audience_push 轮询到 success （进度看 platform_stage，别按固定间隔催）；若 failed，先逐包看 parts 里的 fail_reason 判断值不值得重试：几个包的原因各不相同就一个个 retry_audience_push_part(part_id)， 确认都属于「重来就行」才用 retry_audience_push(id) 一把全退——两者都会把 retry_count 清零。 想直接挑一个能推的包，用 list_audience_packages 的 pushable_only=true——「未过期」这条 你自己判不出来，别拿管理列表按 build_status 筛。 推的是巨量云图 / 腾讯广告广点通 / 京东数坊 / 品牌数据引擎时还能再走一步：任务 success 之后从 get_audience_push 里挑一个 platform_audience_id 已生成、matched_count > 0 的分包 → generate_audience_portrait 传它的 parts[].id → 再用 get_audience_push 看 parts[].portrait_status 转 ready → get_audience_portrait_url 取下载地址 （30 分钟过期，连有效期一起告诉用户）。用户要的只是「看一眼画像」时，generate 回来就把 console_url 给他（页面自己会刷新到画像），后面两步都不必走。 两条平台侧的额外前提要提前说：广点通分包的画像借腾讯如翼生成，要求用户已完成如翼授权——没授权 就先给他 start_platform_auth(platform="ruyi") 的指引；京东数坊要用户先在数坊站内对那个人群 点过「透视」，DataMax 触发不了，没点过就发起只会拿到一句指引式的报错，照转即可、别重试。

链接列表导出为 Excel

list_monitor_links 回来多于一条时，不要在正文里铺 Markdown 表格——url 很长， 表格会被撑散，用户也没法直接拿去登记。生成 .xlsx 文件并把路径交给用户， 正文只留一句结论（共几条、状态分布）。只有一条时照常口述，不必导出。

导出前先把分页翻完：has_more 为 true 就用 offset + 本页条数 继续取， 否则用户拿到的是一张残缺的表。

表头固定这十列，顺序不要改：

| 列 | 取自 | 注意 | |------|------|------| | 监测 ID | link_id | 不是 id（内部主键），别拿错 | | 活动名称 | activity | | | 品牌 | brand_name | | | 监测组 | monitor_group_code | MG 开头的对外编码，不是 monitor_group_id（内部主键）。一个组配一条曝光 + 一条点击，写进表里用户才看得出配对关系；监测组模型上线前建的老链接没有组，留空即可，不要编造 | | 平台 | platform_text | 已是中文，不要写 platform 的 xhs/dy/tx/ty | | 数据类型 | event_type | imp 写「曝光」、click 写「点击」，此字段没有 _text 版本 | | 状态 | status_text | 已是中文，不要写 status 的数字 | | 生效周期 | starts_at / expires_at | 合成一列，写成 起 ~ 止 | | 创建时间 | created_at | | | 链接 | url | 原样整串，不要截断、不要转成超链接文字 |

怎么把这张表落成文件由你按所处环境自行决定，本文不作规定；文件名带上工作空间与日期 便于区分，如 监测链接_<工作空间>_<日期>.xlsx。最终交付的若不是 xlsx，要明确告诉用户 拿到的是什么格式。

不可逆操作

这四个动作调用前一律先把参数复述给用户确认。

• create_monitor 扣账户额度（= 本次新增的链接条数），且链接生成后周期与平台无法修改。 创建是原子的：重名、额度不足或上线失败都不会留下半批链接，也不会扣额度——失败后可以 放心重试，不必担心产生脏数据。
• revoke_monitor_link 撤销本身不可逆，但只撤得动一条数据都没收到过的链接：收过数的会被拒 （「该监测链接已收到数据, 不能撤销」），因为那批数据已经入库、不该失去归属。判定同时查时报库 与实时计数，所以「刚投出去几分钟」也算收过数。也正因为撤掉的是没用过的链接， 撤销成功会退还 1 条额度。一次一条。 撤掉配对完整的组里的一条，这个组就只剩一侧、点击率从此配不出来——撤销前把这点说清楚。
• create_audience_push 建完就推：人群在这一步就发给了媒体，媒体侧与 DataMax 都没有撤回入口。 要确认的事必须在调用之前做完——之后没有第二道闸门。
• start_audience_push / retry_audience_push / retry_audience_push_part 同样把设备标识发给媒体， 同样撤不回：第一个是自动开始失败后的重试入口，第二个把该任务全部失败分包再发一次， 第三个只发指定的那一个包（part_id 取自 parts[].id）。后两个还会把相关分包的 retry_count 清零，等于重新赠送一轮自动重试额度——所以「多调几次试试」有实际代价， 调之前先逐包读 fail_reason 确认这次重试有意义。

其余写工具不触达外部：create_brand、create_audience_package 建错了重来即可。 但人群包不能删除也不能修改，算错只能再算一版。 generate_audience_portrait 同样不外发数据（只是让云图 / 腾讯如翼 / 京东数坊 / 品牌数据引擎对一个 已经推过去的人群算标签分布，或读它算好的结果），但它不幂等：generating / ready 期间重复调会被拒，failed 之后再调会真的再算一次。

错误处理

除鉴权与限流外，所有失败都是工具级错误（isError: true + 中文说明），能读懂再决定重试。

| 现象 | 该怎么办 | |------|---------| | HTTP 401 | 不要重试。凭证问题，请用户检查请求头与 Key 是否有效 | | HTTP 429 | 按 Retry-After（秒）退避。两个来源：按 Key 的限流 60 次/分钟（计的是 HTTP 请求数不是工具调用数），以及鉴权失败过多后按 IP 的锁定——后者跟在 401 后面出现，等多久都没用，得先换对 Key | | isError 工作空间不可用 | 调 list_workspaces 取合法 id 后重试 | | isError Key 类型不足 | 重试不会成功，请用户换用管理 Key | | isError 入参不合法 | 文案里已点名字段与可选值，照着改 |

越权与「不存在」的文案完全一致，这是刻意为之（避免成为探测他人资源的预言机）。所以看到 「工作空间不可用」或「链接不存在」时，不要向用户断言「它存在但你没权限」——回包里区分不出来。

拿着无效 Key 反复重连会触发按 IP 的锁定（鉴权失败 10 次/5 分钟），锁定期回的是 429 而不是 401， 所以 401 之后就停下来问用户，别自动重连把自己锁进去。正常放行的响应带 RateLimit-Remaining， 批量翻页前可以看一眼，别等撞上 429 再退避。

排查顺序

1. whoami → 401：地址/请求头/Key 的问题，先修凭证。
2. whoami 通了但 workspace_count 为 0：建 Key 时没勾工作空间，回控制台补授权。
3. list_workspaces 里没有用户要的空间：这把 Key 没被授权到它，换 Key 或补授权。
4. 想做的事在 tools/list 里没有对应工具：如实回复「DataMax MCP 目前没有这个工具」， 不要拼 URL 直接打 REST 绕过去。

常见问题

这些问题工具本身答不了，但用户一定会问。答错的代价是让人干等——比如以为换个工作空间就能绕开额度。

额度不够了，怎么充值？找谁？

没有自助充值，也没有对应工具——额度只能由运营为账户扩容。唯一的联系入口是企业微信二维码： 在控制台打开额度卡片扫码，或在官网页脚扫同一张码（二维码只在页面上，你替不了用户扫）。 邮箱入口已下线，别再让用户发邮件。

额度归账户所有、全部工作空间共享，所以换一个工作空间不会多出额度，别在这上面绕。 手机号验证后发放 30 条初始额度，每成功生成一条链接扣 1 条。

等扩容期间还有一条立刻可行的路：create_monitor 因额度不足失败时不生成任何链接、也不扣额度， 减少平台或链接类型再试即可（先 get_quota 看 remaining）。

预估口径要限定住：「平台数 × 数据类型数」只在 mode=create（新建监测组）时成立。 往已有组里追加（mode=append 且带 groups[].group_code）时只补缺失的那几条，拿平台数乘类型数 去预估必然偏大。扣的一律是本次实际新增的链接条数，实扣多少以 create_monitor 返回的 consumed 为准（服务端重算）——向用户汇报消耗时念 consumed，别念自己算的那个数。

链接到期了，能续期吗？

不能。生效周期在创建时定死，没有任何工具能改，也没有续期入口——只能按新周期重新创建， 这会再扣一次额度，创建前照例先跟用户确认。

对已到期的链接调 revoke_monitor_link 会被拒（「监测链接已到期, 无需撤销」），这不是故障： 周期两端就是收数窗口，到期即停止收数，不撤也不会再产生数据。

Access Key 到期或丢了怎么办？

都只能去控制台重建，没有找回入口——完整 Key 只在创建那一次可见，服务端只留哈希。 Key 自带有效期，到期后调用一律 401，与「Key 填错」的表现完全一样，所以 401 时提醒用户 顺带确认一下是不是过期了，别只盯着有没有粘错。

刚建好的监测查不到数据，是坏了吗？

先别下结论，用 measure_monitor_metrics 看这条链接的 last_data_at： 链接没出现在返回里 = 一条都没收到过；有 last_data_at 就是收过，只是你查的窗口里没有。

确实一条都没收到时，按这个顺序看：链接是否真的投出去了、get_monitor_link 的周期是否已经开始 （周期外的请求一律不计）、状态是否已撤销或到期。

另外各口径的可见时间不一样：按天 PV 由后端按小时汇总，当天的量走实时补数；UV 与部分日报口径 来自上游管道，会更晚一些。所以「刚投出去的量还查不到」不等于没收到——以 last_data_at 为准， 别据此断言链接有问题。