sycm-cli

# sycm-cli — 生意参谋数据与店铺分析 Skill **适用人群**：淘宝/天猫店铺商家自己拉取自己店铺的客服聊天、评价、销售、商品等经营数据，用于内部分析。 **前置条件**： - macOS Chrome 已登录 sycm.taobao.com；Windows 首次运行会自动打开专用 Chrome/Edge，登录一次即可 - 已装 `uv`（或 `pip` + Python 3.8+） ## 一句话用法 ```bash scripts/sycm.sh fetch-recent --date YYYY-MM-DD --limit 10 --out chats.json ``` 输出 `chats.json` 包含某日前 N 个会话的元数据 + 全部消息内容，可直接喂给 LLM 做客服分析。 ## 工作机制 参考 [twitter-cli](https://github.com/jackwener/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](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` | 服务/慢响应 | 日期、开始/结束时间、买家、客服 | 示例： ```bash 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 日调用虽成功，但曾返回完全相同结果，未确认前不要宣传为两个独立窗口。 示例： ```bash # 看昨天销售前 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`。 ```bash # 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` 不报错、静默返回空——猜错会得到一个永远空着还看不出毛病的命令。同类硬编码值还有