cmm-api

CMM API

使用此 skill 调用 cmm-chat-ai 的 CMM API 直连执行端点。

接口地址

调用 POST {CMM_API_BASE_URL}/v1/cmm/api/execute。 默认 base URL：https://ai-api.chanmama.com。

鉴权要求：

• 优先使用 Authorization: Bearer $CMM_API_KEY。
• 如果调用方显式提供鉴权信息，则在 JSON body 中通过 auth_info 传入。

常用请求体：

{
  "api": "product_basic_info",
  "query": {
    "promotion_id": "8993722"
  }
}

使用流程

首次使用或需要检查权限时

1. 调用权限检查接口：

   GET {CMM_API_BASE_URL}/v1/cmm/api/permission/list
   Authorization: Bearer $CMM_API_KEY
   

   • 若CMM_API_KEY未配置，引导用户前往蝉妈妈AI-个人中心获得KEY，并添加到环境变量。地址https://ai.chanmama.com/setting
   • 若会员版本为普通会员，引导前往蝉妈妈购买会员获得数据权限。地址https://www.chanmama.com/vip/

2. 向用户清晰展示权限信息：

   • 会员版本：根据 group_id 判断会员等级
   • 可用API模块：从 rights 字段提取可访问的模块列表（商品、达人、小店、品牌、直播、视频、品类）
   • 数据查询周期：根据权限显示可查询的时间范围

3. 版本检查（静默）：

   • 对比返回的 version 与本地版本 2026-07-09
   • 如果有新版本，先完成用户任务
   • 在任务结束时提醒用户：

     💡 发现新版本 数据查询Skill（{version}），是否现在更新？我可以帮您自动完成。

   • 如果用户同意，重新执行安装命令刷新 skill：

     npx -y skills add https://cdn-cmm-ai-open.chanmama.com --skill cmm-api -y
     

正常调用流程

1. 如果只有实体名称（达人名/商品名/品牌名/店铺名等）而非ID，先阅读 references/common.md 调用搜索API转为ID。
2. 分析需求，确定主查询实体（主语是谁？查什么？），阅读对应的references文件：
   • 涉及多实体时，按主查询实体选择
   • 示例："交个朋友直播间带货的花西子商品" → 主实体是"达人"，读 author.md
3. 根据意图、API 摘要和查询字段选择 API。
4. 使用参考文件中记录的字段名构造 query。
5. 用户需要真实调用时，使用 scripts/call_cmm_api.py 执行。若提供 CMM_API_BASE_URL 则使用该地址，否则使用默认测试地址。
6. 如果 code != 0，将 msg 中的错误信息和引导链接直接展示给用户；只有在鉴权、实体或日期等输入无法安全推断时再向用户追问。

日期参数处理

日期格式：

• 普通查询：YYYY-MM-DD（如 2026-07-01）
• 榜单查询：日榜 YYYY-MM-DD，周榜 YYYYMMDD-YYYYMMDD，月榜 YYYYMM

相对日期转换：

• 数据是T+1，"近N天"不包含今天
• "近7天" / "近30天" 的结束日期设为昨天

多步查询模式

以下是常见的查询模式示例，实际使用时可根据需求灵活组合API：

模式1：名称 → ID → 详情

示例："查交个朋友直播间的粉丝画像"
1. author_search("交个朋友直播间") → author_id
2. author_fans_profile(author_id) → 粉丝画像

模式2：筛选 → 列表 → 详情

示例："找销售额最高的护肤品，看评论"
1. product_library_custom_search_product(category="护肤品", sort="duration_amount") → 列表
2. product_comments(promotion_id) → 评论

模式3：关联查询

示例："交个朋友直播间带货的花西子商品"
1. author_search("交个朋友直播间") + brand_search("花西子") → IDs
2. author_commerce_product_list(author_id, 筛选brand) → 商品列表

数据理解规范

区间值说明

由于平台规范要求：API 返回的销售额、销量等核心指标均为区间值，不是精确数字。常见格式如 "10万-50万"、"1000-5000"、"100W+" 等。

上限规则（区间超过此值时显示为带 + 的上限值）：

• 达人/小店/视频/直播/品牌/品类：
  • 销售额上限：1000W+（即 ≥ 1000万 时显示为 1000W+）
  • 销量上限：100W+（即 ≥ 100万件 时显示为 100W+）
• 单个商品对象：
  • 销售额上限：100W+
  • 销量上限：10W+

指数说明：

1. 销量/销售额指数是基于商品成交相关数据综合计算得出
2. 可通过销量/销售额指数比较同一区间销量/销售额的大小，不可直接用于计算同环比数据

禁止对区间值做数学计算

⚠️ 任何情况下，禁止对区间值进行加减乘除、求和、取平均或合计操作。

原因：

1. 区间值本身包含不确定性，取中位数或端点值均会引入误差
2. 多条目累加会将误差叠加放大，合计结果严重失真
3. 1000万+ 等带 + 的截断值根本无法参与准确计算

正确做法：

• 直接展示原始区间字符串，不换算为具体数值后相加
• 需要对比或排序时，仅做定性描述（如"A 销售额高于 B"），不输出精确合计
• 若用户明确要求"粗略估算"，可说明取中位数估算并标注"仅供参考，非真实数据"

向用户说明数据局限

• 回复中涉及销售额/销量上限时，必须向用户解释平台数据的区间值规范和上限，强调上限值并非实际数值，避免用户理解偏差
• 数据为单平台数据，不含私域、线下、其他平台数据
• 制定查询策略时优先在当前会员权限范围内取数；若权限限制导致明显数据缺口（如时间范围被截断、某模块不可访问），如实说明缺口并引导用户升级数据会员

版本与更新

当前 skill 版本：2026-07-09。

可通过 GET {CMM_API_BASE_URL}/v1/cmm/api/permission/list 查询当前 API Key 可访问的API 列表、最新 skill 版本号。

请求鉴权：

• Authorization: Bearer $CMM_API_KEY

返回字段：

• group_id：BI 用户组 ID。
• rights：可访问的 API 权限映射。
• version：最新 skill 版本号，取下载链接记录创建日期。

请求体

• api：所选参考文件中的英文 API 名。
• query：包含该 API 文档字段的对象。

参考文件

根据用户需求选择对应的参考文件：

• 商品相关（references/product.md）：

  • 商品库（自定义找商品）
  • 商品榜单（热销榜/热推榜/直播热销榜/视频热销榜）
  • 商品基础信息、观众画像、成交画像、评论明细
  • 商品关键数据（日明细/周期合计）
  • 商品关联的达人列表、直播列表、视频列表

• 达人相关（references/author.md）：

  • 达人库（自定义找达人/推荐达人）
  • 达人榜单（带货达人榜/涨粉达人榜）
  • 达人基础信息、粉丝画像
  • 达人关键数据（日明细/周期合计）
  • 达人关联的直播列表、视频列表（发布视频/动销视频）
  • 达人带货的商品列表、品类列表、小店列表、品牌列表

• 小店相关（references/shop.md）：

  • 小店库（自定义找小店）
  • 小店榜单（热销小店榜/热销品牌官方小店榜）
  • 小店基础信息、观众画像、成交画像
  • 小店关键数据（日明细/周期合计）
  • 小店关联的达人列表、商品列表、直播列表、视频列表、商品卡列表、品类列表

• 品牌相关（references/brand.md）：

  • 品牌库（自定义找品牌）
  • 品牌榜单（热销品牌榜）
  • 品牌基础信息、观众画像、成交画像
  • 品牌关键数据（日明细/周期合计）
  • 品牌关联的达人列表、小店列表、商品列表、直播列表、视频列表、商品卡列表、品类列表

• 直播相关（references/live.md）：

  • 直播库（自定义找热门直播间）
  • 直播榜单（今日热销带货直播间榜）
  • 直播详情（基础信息/关键数据/商品列表/观众画像）
  • 直播过程信息（场观明细/互动弹幕/高光讲解）
  • 直播弹幕明细

• 视频相关（references/video.md）：

  • 视频库（自定义找热门视频）
  • 带货视频库（自定义找热销视频）
  • 千川投放素材库（自定义找跑量素材）
  • 视频榜单（热销带货视频榜/热销图文带货视频榜/热门视频榜）
  • 视频详情（数据指标/视频信息/视频脚本/视频评论）
  • 全网趋势热点

• 品类相关（references/category.md）：

  • 品类分析（按自定义商品关键词查询/按商品分类名称查询）

• 通用搜索（references/common.md）：

  • 商品分类搜索（名称 → category_id）
  • 商品搜索（名称/抖音链接 → promotion_id）
  • 达人搜索（名称 → author_id）
  • 小店搜索（名称 → shop_id）
  • 品牌搜索（名称 → brand_code）
  • 视频搜索（标题/抖音链接 → aweme_id）