sycm-cli

name	sycm-cli
description	使用 sycm.taobao.com 的已登录本地浏览器读取淘宝/天猫自营店铺数据，生成标准报表并执行经营分析。覆盖首页大盘、销售、商品、新品、退款、接待、评价、客服对话、Excel 导出和多店铺登录态。当用户提到生意参谋、sycm、店铺数据、标准报表、店铺体检、日检、周复盘、测款、退货归因、客服质检、商品 360、新品追踪、下载店铺 Excel 或让 AI 分析店铺时使用。

sycm-cli — 生意参谋数据与店铺分析 Skill

适用人群：淘宝/天猫店铺商家自己拉取自己店铺的客服聊天、评价、销售、商品等经营数据，用于内部分析。

前置条件：

• macOS Chrome 已登录 sycm.taobao.com；Windows 首次运行会自动打开专用 Chrome/Edge，登录一次即可
• 已装 uv（或 pip + Python 3.8+）

一句话用法

scripts/sycm.sh fetch-recent --date YYYY-MM-DD --limit 10 --out chats.json

输出 chats.json 包含某日前 N 个会话的元数据 + 全部消息内容，可直接喂给 LLM 做客服分析。

工作机制

参考 twitter-cli 的纯本地认证模型：

1. macOS 用 browser_cookie3.chrome(domain_name='taobao.com') 从 Chrome 直读 cookie；Windows 自动启动独立 Profile 的 Chrome/Edge，通过本机 CDP 读取浏览器已解密 cookie
2. curl_cffi 伪 TLS 指纹（impersonate='chrome120'）直调 sycm API
3. Windows 不读取默认 Profile、不导出 cookie，也不关闭 Chrome App-Bound Encryption 安全保护

请求形态尽量贴近正常人工浏览，但仍然必须控制频率并遵守下面的安全护栏。

AI 执行原则

• 先确认店铺 profile、日期范围和用户要的报表/分析，再调用只读命令。
• 优先使用已验证的子命令；除非用户明确要求侦查新接口，不使用 api 猜路径或参数。
• 将真实数据写到本地临时文件，不写入 Skill、Git 或可分发文档。
• 默认对买家昵称、客服昵称、订单 ID、商品 ID 和聊天正文脱敏。只有用户明确要求对话分析时才读取必要正文。
• 每个结论附上数据来源、日期和字段名；数据不足时标记“不能判断”，不用经验补数。
• 不将“当日完结的历史订单退款”除以“当日成交”生成商品退款率。无法建立同一订单队列时，只报告官方字段口径或“当日完结退款金额/笔数”。
• 追溯某日完结退款时，优先执行 refund-origin-analysis --date <D>；它按 ordPayTime 找到原付款日并区分退款场景，但本身仍不是退货率。

模块 1：标准全景报表

当用户说“把现在能拿到的数据全部展开”、“做一份给其他 AI 分析的报表”或“给每张表一个真实范例”时，执行本模块。

范围

按五个数据域组织，不将一张多行表压缩成一个指标：

数据域	必查命令
总览大盘	home-overview, home-table, home-trend, grow-factor
商品与新品	item-list, cate-list, new-product-overview, new-product-list, new-product-trend, order-overview, order-trend, order-distribution, order-recommend
销售与售后	sale-shop-list, sale-item-list, refund-item-list
客户与客服	reception-list, evaluation-list, sale-cs-list, inquiry-loss-list, slow-rsps-list
内容与直播	preheating-metrics, live-guide-overview, live-guide-trend

fetch-recent 的聊天正文不默认进入全景报表；只报告可用会话数和字段结构，避免不必要暴露买家信息。

执行

1. 运行 scripts/sycm.sh doctor；失败则停止，告知用户登录态问题。
2. 运行 scripts/sycm.sh --help 保存当前命令面，防止报表清单落后于代码。
3. 对上表每个命令只取一个最小真实样本；列表类使用 --limit 1，趋势类使用最小有效日期范围。
4. 保存完整输出到本地临时目录，在对话中只展示脱敏范例。
5. 命令返回空表时仍保留该行，标记“0 条/当日无数据”；不把空表说成接口不可用。
6. 命令失败时记录错误类型（登录、权限、风控、参数、网络），不猜造样例。

输出合同

首先输出覆盖摘要：检查日期、店铺 profile、已成功/空表/失败命令数。然后每个数据域输出一张表：

报表	命令	日期口径	记录数	关键字段	脱敏真实样例	口径/限制	状态

硬性要求：

• “真实样例”只取一行或一个汇总对象，但必须来自本次真实请求。
• “关键字段”写中文名和原始 field code，便于其他 AI 继续分析。
• 不少列已验证命令；不用“等”省略剩余报表。
• 本模块只呈现数据，不做经营归因。需要分析时，再进入对应的日检、周复盘或专项模块。

分析模块

当用户要求日体检、周复盘、测款、退货归因、广告 ROI 或客服质检时，读取 references/analysis-workflows.md 中对应模块的全部指令，严格按其口径、输出合同和停止条件执行。

子命令

旺旺咨询接待（含完整对话）

子命令	用途
doctor	检查 cookie 能否读到 / 登录态是否有效
list --date YYYY-MM-DD [--page N --size N]	拉某日的咨询会话列表（不含消息内容）
detail <dataId>	拉单个会话的全部消息（自动翻页）
fetch-recent --date YYYY-MM-DD --limit N [--out file]	主力：列表 + 全部详情，给 AI 一行命令即可拿全数据

高频日维度列表页面（v0.2+）

每个子命令都接受 --date YYYY-MM-DD --limit N --raw --out file：

子命令	对应 sycm 页面	字段
reception-list	服务/接待明细	开始/结束时间、买家、客服、是否回复
evaluation-list	服务/售后评价 (邀评明细)	接待时间、邀评时间、买家、客服、来源
sale-shop-list	商品/销售分析	商品 ID/标题、店铺销售额、客服销售额、静默销售额
sale-item-list	交易/订单明细	订单时间、订单金额、买家、客服、是否静默
sale-cs-list	客服销售明细（旺旺销售）	订单时间、买家、客服
inquiry-loss-list	服务/询单流失	开始/结束时间、买家、客服
slow-rsps-list	服务/慢响应	日期、开始/结束时间、买家、客服

示例：

sycm-cli sale-shop-list --date YYYY-MM-DD --limit 10
sycm-cli evaluation-list --date YYYY-MM-DD --limit 20 --out eval.json
sycm-cli reception-list --date YYYY-MM-DD --raw   # 输出原始 JSON

商品大类 (v0.4+) —— 商品排行 / 商品 360 / 品类 360 / 新品追踪

走的是 sycm 商品板块的新接口（cc/* 系列，cc-v2 风格），与上面的旧 csp 接口参数完全不同：

• 日期参数：dateRange="YYYY-MM-DD|YYYY-MM-DD" + dateType=day|recent7|recent15|recent30
• response 里字段值常是 {value, cycleCrc, syncCrc} 嵌套对象（CLI 已自动提取 .value 展示）

子命令	对应 sycm 页面	关键字段	备注
item-list	商品/商品排行 (/cc/item_rank) 或 商品 360 (/cc/item_archives)	商品标题、支付金额/买家数/件数/转化率/客单价、访客数、加购件数、收藏人数、平均停留时长、详情页跳出率、搜索引导访客数、成功退款金额（12 项，其余 29 个字段用 --raw 看）	走 /cc/item/view/top.json（历史档接口）；旧接口 /cc/item/portal/itemList.json 只在网页「实时」档才用，且不认 indexCode(实测传多少个都只回 3 个指标)，已弃用
cate-list	商品/品类 360 (/cc/new_cate_archives)	cateName、payAmt、itmUv、payRate	返回的是当日全行业品类数据（含 children 树）
new-product-list	商品/新品追踪 → 列表 (/cc/new_item_analysis)	商品、publishNewTime、payAmtNew、shopUvNew	接 --cate-id 限定类目
new-product-overview	商品/新品追踪 → 顶部汇总卡	newItmCnt、shopUvNew、payAmtNew、addCartCntNew	不是 list，返回汇总对象
new-product-trend	商品/新品追踪 → 趋势图	self/industry 两组时序数据	建议加 --raw 拿全

日期能力以实测为准：overview 只确认单日；trend 的单日调用返回截至该日的固定 30 日序列；overview/trend 显式 7/30 日区间会报 1003。list 的 7/30 日调用虽成功，但曾返回完全相同结果，未确认前不要宣传为两个独立窗口。

示例：

# 看昨天销售前 10 商品 (商品排行)
sycm-cli item-list --date YYYY-MM-DD --limit 10

# 看品类 360（全行业品类销售）
sycm-cli cate-list --date YYYY-MM-DD --limit 5

# 新品追踪 (3 个子接口)
sycm-cli new-product-overview --date YYYY-MM-DD           # 总览
sycm-cli new-product-list --date YYYY-MM-DD --limit 10    # 列表
sycm-cli new-product-trend --date YYYY-MM-DD --raw        # 趋势

字段值是嵌套对象，加 --raw 才能拿到对比指标（cycleCrc=环比、syncCrc=同比）。摘要模式只显示 .value。

单品五件套 (v0.8+) —— 这个款为什么不行

回答「这个款为什么不行、哪个尺码在退、流量从哪来」。全部只读，都走 cc-v2 风格接口。

先用 item-search 拿到 itemId，其余四个命令都接 --item-id <商品ID>；也可以直接用 --search <货号/标题关键词> 代替，命中唯一才继续，命中多个会列出候选并以退出码 1 停下（不猜）。

子命令	对应 sycm 页面	产出	日期口径
item-search <关键词>	商品 360 搜索框	商品ID、货号、价格、库存、标题	目录搜索，无日期参数
item-360	商品 360 顶部	核心指标（本店值+环比+cmpt对比值）+ 销售总览	都吃 --date
item-sku-list	商品 360 / 销售分析 / SKU销售明细	各 SKU 组合的加购件数、支付金额/件数/买家数；--by <属性名> 时改出按属性聚合表；--live 时改出现有库存/售罄率/库存可售天数（与 --by 互斥）	默认吃 --date；--live 是当前快照，忽略 --date
item-flow-source	商品 360 / 流量来源	来源树（多级）：uv、pv、收藏、加购、支付买家/金额、转化率	吃 --date
item-refund	商品 360 / 退款	一条命令三张表：退款原因分布、各 SKU 退款、各属性退款（含属性值）	吃 --date，按原订单付款时间
item-profile	商品 360 / 客群洞察 / 客群画像	买这个款的人是谁：人群标签/年龄/性别/新老客/省/市/品牌偏好/类目偏好/预测消费层级/淘气值 共 10 个维度	只认单日，多日区间会被拒
item-loss-risk	商品 360 / 客群洞察 / 客群细分	潜在流失风险：你这个款的客户预测会流向哪些商品（含友商），带按店铺汇总	人气值只有单日有，多日会静默丢掉该列
item-detail	商品 360 / 详情分析	核心概况 11 个指标，每个都带同行均值/同行优秀 + 详情页逐屏（11 个楼层，两级树）看买家看到哪屏走的	吃 --date
item-price	商品 360 / 价格分析	本款价格定位（挂牌价 / 实际件单价 / 所属价格带）+ 类目各价格带大盘，标出本款所在档	吃 --date
item-title	商品 360 / 标题优化	标题每个词带来多少搜索访客，直接点名零引导的死词 + 推荐词（类目/属性/品牌/长尾）	吃 --date
item-bundle	商品 360 / 关联搭配	买了这个款的人还买了什么：系统推荐 + 卖家自选（未配置时会说明是没配，不是取不到）	吃 --date
item-content	商品 360 / 内容分析	关联视频/内容带来多少种草点击、粉丝点击、收藏、加购、支付（汇总 + 逐条内容）	默认近 30 天，内容效果看单日没意义
item-service	商品 360 / 服务体验	售前咨询/售后首次解决率/有效回复/主动评价/问大家声量/成功退款，每项带对比值与环比	吃 --date

公共参数：--item-id / --search / --date / --end-date / --limit / --page / --raw / --out。

# 1. 先拿商品 ID（支持标题关键词、商品ID、商品URL、货号）
sycm-cli item-search 连衣裙 --limit 3

# 2. 单品总体面貌（核心指标 + 销售总览，都按 --date）
sycm-cli item-360 --item-id 123456789 --date YYYY-MM-DD

# 3. 哪个 SKU 组合卖得动（近 30 天，--date 与 --end-date 相隔 30 天）
sycm-cli item-sku-list --item-id 123456789 --date 起始 --end-date 结束 --limit 10

# 3b. 换个视角：哪个尺码/颜色卖得动（网页「属性分析」表，同一份数据按属性聚合）
sycm-cli item-sku-list --item-id 123456789 --date 起始 --end-date 结束 --by 尺码

# 3c. 现在该补哪个 SKU 的货（现有库存/售罄率/库存可售天数，当前快照，--date 不生效）
sycm-cli item-sku-list --item-id 123456789 --live --limit 10

# 4. 访客从哪来、哪个渠道转化差
sycm-cli item-flow-source --item-id 123456789 --date YYYY-MM-DD --limit 10

# 5. 为什么退、哪个 SKU / 哪个尺码退得多（近 30 天）
sycm-cli item-refund --item-id 123456789 --date 起始 --end-date 结束 --limit 10

# 12. 这个款的服务/售后有没有拖后腿
sycm-cli item-service --item-id 123456789 --date 起始 --end-date 结束

# 11. 哪条视频真的带货
sycm-cli item-content --item-id 123456789 --date 起始 --end-date 结束

# 10. 买了这个款的人还买了什么（配套餐用）
sycm-cli item-bundle --item-id 123456789 --date YYYY-MM-DD

# 9. 标题哪几个字是白占的
sycm-cli item-title --item-id 123456789 --date YYYY-MM-DD

# 8. 这个价位段值不值得待 —— 本款所在档的盘子多大、涨得多快
sycm-cli item-price --item-id 123456789 --date YYYY-MM-DD

# 7. 详情页哪一屏在掉人 + 跟同行比差在哪
sycm-cli item-detail --item-id 123456789 --date YYYY-MM-DD --limit 20

# 6b. 客户要跑去哪（含友商；人气值只有单日有）
sycm-cli item-loss-risk --item-id 123456789 --date YYYY-MM-DD --limit 20

# 6. 买这个款的是谁（默认人群标签；--all 一次跑完 10 个维度）
sycm-cli item-profile --item-id 123456789 --date YYYY-MM-DD
sycm-cli item-profile --item-id 123456789 --date YYYY-MM-DD --by province
sycm-cli item-profile --item-id 123456789 --date YYYY-MM-DD --all --limit 5

# 也可以不带 ID，直接按货号搜（命中唯一才继续）
sycm-cli item-sku-list --search A1001 --by 颜色分类

--by <属性名> 不传就出 SKU 组合明细（skuName 是"颜色分类:xx;尺码:xx"这种组合值）；传了就改走 按属性聚合的接口，出该属性维度下每个取值的汇总（attrValue 列）。属性名取值来自商品自身定义的 属性（常见的是"尺码"“颜色分类”），不写死枚举——服务端不认的属性名会自己报错，不会静默返回空表。

口径警告（分析前必看）

• 日期窗口只支持 1 / 7 / 15 / 30 天。--date 与 --end-date 的间隔必须恰好是这几个宽度之一， 其余宽度服务端一律 code=1003 拒绝（2026-08-05 实测，cc/flow/csp 三族一致），CLI 会先在本地报错。 recentN 是相对 dateRange 的，不是相对今天（同日实测：7 天窗返回值等于窗口内七个单日之和）。
• 生意参谋商品板块反复出现同一类接口分裂：日/7天/30天档和「实时」档走的是两个完全不同的 接口，只在某一档录到的接口签名不能代表另一档。已踩过三次：item-sku-list、item-360 的 销售总览最初侦查时页面停在「实时」档，录成 /cc/live/... 系列（写死当天，忽略传入日期）， 已改正为不带 live/ 的日期口径接口（2026-08-05 用 recent7/recent30 两次真实调用对照过，数值 不同）；item-list 也一样，最初录到的 /cc/item/portal/itemList.json 不认 indexCode（传多 少个都只回 3 个指标），页面日期档实际走的是 /cc/item/view/top.json，换过去后单次调用能拿到 41 个字段。item-sku-list 的实时档没有丢，用 --live 显式切换——现有库存 currentStockCnt / 售罄率 sellRate / 库存可售天数 stockDays 只有实时接口才有，认日期的接口拿不到这三个字段 （加了 indexCode 也会被静默丢弃），--live 和 --by 互斥。
• item-refund 是退款事件归属，不是退货率。 三张表都按原订单付款时间（refundDateType=pay）。 真实退货率要用同一付款批次的支付订单数作分母，CLI 不替你算，也不要自己拿这些数去算。
• item-refund 的「退款原因」表已修好（2026-08-06）。 它曾长期返回 0 行，真凶是 rfdIntervalLevel 传了猜的 "ALL" —— 服务端照收、不报错、静默返空；页面实际传的是 99。 现在能正常拿到 8 类原因，且带 rfdReasonTypeCn（内部原因 / 消费者原因）——先看这一列， 内部原因才是自己能改的。金额字段是 itemRfdAmt，itemSucRfdAmt 这个名字在响应里不存在。
• 退款率字段近 7 天还没长完。 各 SKU 表里的 payAmtRfdRate / ordRfdRate 是平台自算的支付时间 口径退款率，实测 T-6 仍在爬升。--date 默认昨天正落在禁区里，别用近 7 天的退款率下结论。
• item-360 的 *Cmpt 不是同行绝对值。 实测本店 payAmt / uv 都是三四位数时，对应的 *Cmpt 全落在 0~1 区间，量级完全对不上。具体口径未核实，别当同行对比读。
• item-profile 只认单日（2026-08-06 实测）。传 recent7 / recent30 服务端照样回 code=0，但 data 恒为空数组——又一次「参数照收、结果静默变空」。CLI 在发请求前就拦掉多日区间。
• item-profile 的三个人群口径里通常只有 itmUv（访问人群）有数据 —— 原因是样本量门槛。 页面原文：「本店商品人群样本量小于 300 人，不统计客群画像」（2026-08-06 核对）。 payByrCnt（成交人群）与 appSearchUv（搜索人群）的人数一般远达不到 300，所以恒空。 致命的是本接口只认单日，没法靠拉长窗口把人数攒过门槛——这两个画像实际上只有 单日就能跑到 300+ 的大流量爆款才出得来。不是缺参数，也不等于该商品没有成交人群。
• brand_prefer 维度有标签没数值：回得出品牌名，但访客数全 0、占比全空。命令会点明这是 取不到数，不是「没人偏好这些品牌」。
• new_old 的 Y=新客户、N=老客户（2026-08-06 用页面「新老占比」环形图核对）。CLI 显示成 「新客户(Y)」，中文与原码并存。
• item-loss-risk 的「预测流失人气」只有单日有。 多日区间时行还在、customerCnt 列被服务端 静默拿掉——是本项目第六次遇到「参数照收、结果悄悄缩水」。命令会显式提示，别把没有数字的表当 成正常结果读。
• item-loss-risk 的 crowdType 目前只核实了 ptl-loss。 页面「流失客户」「潜在客户」那些 框应该还有别的值，但服务端不吐白名单、前端 39 个 JS bundle 里也搜不到，没拿到就没写进来。
• item-detail 的 rivalAvg/rivalGood 是真的同行对比（同行均值 / 同行优秀），量级与本店值 同数量级、可直接比较。这与 item-360 那个量级对不上、口径不明的 *Cmpt 不是一回事，别混用。
• item-detail 的 byrType=all 是从页面录来的，不能猜。 服务端对瞎编的 byrType / detailType 不报错、静默返回空——猜错会得到一个永远空着还看不出毛病的命令。同类硬编码值还有