@whyshu/argent-engine 0.6.0 → 0.6.1

package/engine/skills/ml-store-daily-report/SKILL.md

@@ -0,0 +1,224 @@
+---
+id: ml-store-daily-report
+name: ml-store-daily-report
+title: 美客多店铺日报
+version: 1.3.1
+category: 产品运营
+tags: [日报, 数据汇总, 定时推送, 多站点, 补货预警, 官方API]
+difficulty: ⭐⭐⭐⭐
+requires:
+  - node >= 18
+  - mercadolibre-app-oauth (官方 API 授权，ml-oauth-setup.mjs)
+  - feishu-config
+triggers:
+  - pattern: 日报|今日数据|运营报告|daily|今天情况|昨天销售|当日汇总|所有店铺|多店|补货|断货|畅销
+  - schedule: "0 * * * *"  # 每小时 cron；脚本内按站点本地时间门控（默认 08:00 推前一天）
+entry: scripts/README.md
+output:
+  format: markdown
+  push_to: [feishu]
+push:
+  enabled: true
+  type: card
+  template: daily_report
+metadata:
+  hermes:
+    requires_toolsets: [browser, terminal]
+    requires_tools: [terminal]
+description: "美客多店铺日报（Argent on DSH）——官方 API 数据源（OAuth）+ 浏览器兜底；畅销榜 + 补货预警 + 风险/利润/流量分区（可插拔）；支持飞书群 @ 按需问答与**只读口径对账**。v1.3.1。"
+---
+
+# 美客多店铺日报
+
+## 目标
+生成美客多多店铺日报：昨日销售概览 + 近7日畅销榜 + 补货预警（可售天数 < 供货周期+安全缓冲），按**站点本地时间**每天定时推送飞书。
+
+## 数据源（v1.2.0 起，二选一）
+
+| 模式 | 说明 | 使用场景 |
+|------|------|----------|
+| **API 模式（推荐）** | 卖家开发者应用 OAuth 授权，走美客多官方 API（`/orders/search`、`/users/{uid}/items/search`）；cron 全自动 | 常规日报推送（主路径） |
+| 浏览器模式（保留） | `scripts/extract.js` 经紫鸟窗口采集卖家后台页面 | 官方 API 未覆盖指标的兜底/人工触发 |
+
+**API 模式是唯一事实源**：实现位于 `argent-dsh/scripts/daily-report.mjs`（执行层，cron 与 agent 调用同一份），本技能 scripts/ 仅保留浏览器兜底逻辑。任何改动先改 `scripts/`，勿在 skill 内复制实现。
+
+---
+
+## 按需问答（客户在飞书群 @ 我时用；2026-09-27 新增）
+
+**原则**：客户问什么就给什么——**只算他问的那几组**，不要每次都跑全量日报（全量卡片很长，而且流量组要按商品逐个查访客）。
+实现基础：日报已拆成**分区（section）**，可用 `--sections` 精确选择、`--store` 限定店铺，两者都**不推送**（`--json` 只输出卡片 JSON）。
+
+### 一、先看有什么可查（不发任何美客多请求）
+
+```bash
+node ~/.argent-dsh/scripts/daily-report.mjs --list-sections   # 分区清单：id / 分组 / 依赖 / 成本 / 是否默认开
+node ~/.argent-dsh/scripts/daily-report.mjs --list-stores     # 已授权店铺：名称 / 站点 / 卖家 uid
+```
+
+### 二、客户问法 → 该跑哪些分区（映射表）
+
+| 客户大概会这么问 | `--sections` 用这些 | 卡片内容 |
+|---|---|---|
+| 「有没有超时要处理的」「今天有什么风险」「有没有要罚款的」 | `risk.reputation,risk.todo,risk.sla` | 纠纷率/延迟发货/取消率、待处理纠纷与未回复提问（含最久天数）、待发出订单与最久等待 |
+| 「昨天卖了多少」「今天怎么样」 | `sales.summary,sales.top` | 昨日订单/销售额/客单价/取消 + 近7日畅销榜 |
+| 「最近卖得好不好」「趋势」 | `sales.trend,sales.movers` | 近 7 日每日迷你趋势 + 环比上周涨/跌榜 |
+| 「Full 占多少」「自发货多少」 | `structure.logistics` | Full vs 自发货 GMV/件数占比（另注明已下架未知部分） |
+| 「是不是靠几个爆款」「集中度」 | `structure.concentration` | Top10 SKU 占 GMV 比例 + 风险语气 |
+| 「到手能有多少钱」「佣金多少」「扣了多少」 | `profit.fees,profit.net` | 佣金合计与占比、优惠券、净收入估算（**注明未含运费**） |
+| 「库存够不够」「要不要补货」 | `ops.restock` | 可售天数与建议补货量 |
+| 「流量怎么样」「转化率」「哪个没人看」 | `traffic.visits,traffic.zombies` | 近7日访客与转化率、访客Top5、7日0访客清单（**周更**，见下方注意） |
+| 「整个情况」「给我一份完整日报」 | 不传 `--sections`（=全部默认分区） | 完整卡片 |
+
+**店铺**：客户说「1店」就传 `--store 1店`（子串匹配，会自动命中「墨西哥-1店主账号」）；说「三家店」就别传 `--store`。
+**时间**：默认是**昨日 + 近 7 日**口径；客户明确要别的日期时用 `--date YYYY-MM-DD`。
+
+### 三、执行与回复（与全量日报同一套协议）
+
+```bash
+node ~/.argent-dsh/scripts/daily-report.mjs --sections risk.reputation,risk.todo,risk.sla --store 1店 --force --json --no-mark > /tmp/daily-card.json 2>/tmp/daily-card.err
+# 校验 JSON 可解析后：回复  CARDFILE:/tmp/daily-card.json
+```
+
+要点：
+- **必须带 `--force`**（跳过推送时段门控；问答不是定时推送）；
+- **必须带 `--no-mark`**（不写幂等标记，否则会污染当天定时推送）；
+- **必须用 `--json`**（只出卡片 JSON，不推送）——**绝不要**让脚本走默认推送模式（会与你的回复双推）；
+- 采集失败（429 限流/JSON 无效/文件为空）⇒ 只回复错误摘要（如「⚠️ 美客多接口限流，请稍后重试」），**不要** fallback 推送；
+- 客户没问的组不要顺手加进去（省请求、卡片也短）。
+
+### 四、流量组是**周更**（别每次都问）
+
+`traffic.*` 只在**周一**（`mlWeeklyDay`，可配）真算，其余日子卡片里显示的是**上周缓存**并标注数据日期。
+所以客户在非周一问「今天流量怎么样」时，要**顺带说明**"这一组是每周更新，上面是 X 月 X 日的数据"；
+若客户非要最新，可临时强制：`ML_WEEKLY_DAY=<今天星期> node ... --sections traffic.visits --force --json`（每次约 20–250 个请求，注意限流）。
+
+### 五、红线
+
+- **只读**：日报只从美客多官方 API 读数据、只往飞书发卡片；**不改**任何商品/价格/订单，也不写客户的飞书表（日报与 lip 表已解耦）；
+- 不要为了"数据更好看"而猜测：取不到的字段就如实说"未取到（原因）"；
+- 涉及**写**操作（改价、回消息、上架）一律不在此入口开放，需人工确认 + 单独权限。
+
+
+## 口径与对账（2026-10-12 新增；客户问「为什么和平台差几个数」时看这里）
+
+### 一、三个指标的定义（每个字都是判据）
+
+| 卡片上的字 | 定义 | 排除项 |
+|---|---|---|
+| **订单数** | 窗口内 `date_created` 命中、且**排除 `cancelled` 与 `payment_required`** 的**订单笔数** | 取消单、未付款单**不计**（取消**另列一行**） |
+| **已售件数** | 上述**有效订单**的 Σ `order_items[].quantity`（**件**，不是笔） | 取消/未付款单的件数不计 |
+| **销售额** | 上述**有效订单**的 Σ `total_amount` | 同上 |
+| 取消 / 客单价 | 窗口内 `cancelled` 笔数 / `销售额 ÷ 订单数`（四舍五入） | — |
+
+**窗口** = 报告日在**站点本地时区**的自然日 `[D 00:00, D+1 00:00)`（左闭右开；墨西哥 = `America/Mexico_City`）。
+数据源 = 官方 API `/orders/search`（`order.date_created.from/to`），**只读**。
+
+### 二、「抓取时刻」的语义（卡片上那行「数据截至」）
+
+- 卡片会印 **`**数据截至**：10-12 14:05（America/Mexico_City）`** —— 那是**抓取那一刻**（站点本地时刻），
+  同时快照 JSON 里落 `capturedAt`（ISO8601 带偏移）/ `capturedAtLocal` / `window`（from/to + 时区）；
+- 日报是**抓取时刻的快照**，不是"平台此刻的事实" ⇒ **跨时点比较必然可能差几个数**；
+- 老快照没有这三个字段 ⇒ 渲染**优雅降级**（不印那两行，⛔ 绝不猜一个时刻）。
+
+### 三、平台**会事后变更**历史订单状态（实测，这是第一层原因）
+
+2026-10-12 实测：同一窗口隔 ~4h 重拉 ⇒ 有效订单 **595→592**、件数 **643→640**、取消 **27→30**。
+即 **平台侧会事后把已创建的订单改成 `cancelled`**（我们抓的是当时的真实状态），而平台概览指标**也在滚动更新**
+⇒ 「我们 595」与「平台 602」既可以差在**时点**，也可以差在**口径标签**。**不是一个数错了。**
+
+### 四、只读对账工具：一条命令解释「为什么对不上」
+
+```bash
+# 用快照记录的时刻/窗口 + 与日报**同一条**取数聚合实现，逐候选重算同一窗口
+node ~/.argent-dsh/scripts/daily-report-reconcile.mjs --store 1店 --date 2026-10-11 \
+     --platform-kpi "订单数量=602"        # 也可 --platform-kpi '{"订单数量":602}' ；加 --json 给程序看
+```
+
+输出五段（可直接贴给客户）：① 我方口径；② **候选口径对照表**（仅付款已批准 / 含发货信息 / 含取消〔全部创建〕/
+未付款数 / 唯一买家数 / 件数 / 销售额 …每项都带口径说明）；③ **窗口平移敏感度**（±1h/±2h/±3h ⇒ 边界时刻能差多少）；
+④ **与快照的漂移**（【报告时 vs 现在】并排 —— 事后变更的直接证据）；⑤ **平台 KPI 命中判定**。
+
+判读：
+- **命中某项候选** ⇒ 差异是**口径标签**不同（客户看的那个标签对应另一个候选）；
+- **谁都不等于**（如现场的 602）⇒ **差异不是口径，而是时点或平台未知口径** ⇒ 请客户**同一时刻 + 同一标签**再比；
+- 退出码：`0` 有命中/漂移已解释 ｜ `2` **无候选命中**（可判红）｜ `1` 用法或取数失败 ｜ `3` 凭据不可用（未开刷新）。
+
+**只读红线**：⛔ 不写快照、⛔ 不写任何客户表、⛔ 不改 `ml-api-stores.json`（默认）。
+唯一例外 = `--allow-token-refresh`：token 已失效时**显式**允许刷新，并把轮换后的 `refresh_token`
+**原子写回**（tmp + rename）—— 不写回下次日报会因旧 token 撞 429（2026-09-04/05 断供根因）。
+默认（不给该开关）⇒ 只读失败退出并提示下一步。
+
+### 五、事故登记：2026-10-11 墨西哥1店「订单 595 vs 平台 602」
+
+- **现场**：卡片订单数 **595**，客户在平台概览看到销售量 **602**，问"为什么有出入"。
+- **第一层原因（实测，事后变更）**：同窗口隔 ~4h 重拉 ⇒ **595→592 / 643→640 / 27→30**；
+  两张卡上同时印着"昨日订单 595 · 已售件数 643"，客户大概率在比**不同标签**或**不同时刻**的数。
+- **第二层原因（口径不同，且 602 对不上任何候选）**：逐候选实测 —— 我方 **592**｜仅付款已批准 **577**｜
+  含发货 **592**｜含取消（全部创建）**622**｜件数 **640**｜唯一买家 **576**｜窗口平移 −1h/+2h = **559/583**
+  ⇒ **无一等于 602**。
+- **处置（本批交付）**：① 卡片追加「数据截至 + 一行口径」；② 快照落 `capturedAt`/`capturedAtLocal`/`window`/`apiBase`；
+  ③ 新增只读对账工具（`scripts/daily-report-reconcile.mjs`）；④ 取数/聚合抽到 `scripts/lib/daily-report-core.mjs`
+  供日报与对账**共用同一份口径**（⛔ 不许有第二份）。
+- **一句话**：差异 = **时点（平台事后改状态）× 标签（口径）**；以后先看卡片「数据截至」，再跑对账工具。
+
+
+## 输入格式（agent 触发）
+
+```json
+{ "mode": "api", "force": true, "stores": ["墨西哥站"] }
+```
+
+- `mode: api`：调用 `scripts/daily-report.mjs`（默认）；
+- `mode: browser`：走旧版 extract.js/generate.js 浏览器采集；
+- `force: true`：跳过时间门控立即执行（`--force`）；`dry: true` 只输出不推送（`--dry-run`）。
+
+## API 模式执行流程
+
+### 步骤 1：确认授权与配置
+```bash
+# 数据文件（~/.dsh/argent/，update 不覆盖）：
+#   daily-report.env      配置（ML_APP_ID/SECRET、FEISHU_WEBHOOK_URL、REPORT_TIME、补货参数）
+#   ml-api-stores.json    OAuth 授权（ml-oauth-setup.mjs 生成）
+node ~/.argent-dsh/scripts/ml-oauth-setup.mjs --list   # 查看已授权店铺
+```
+缺授权时：引导卖家运行 `node ~/.argent-dsh/scripts/ml-oauth-setup.mjs` 逐店授权（用该店紫鸟浏览器打开授权链接）。
+
+### 步骤 2：采集 + 计算（agent 直接调用执行层）
+```bash
+node ~/.argent-dsh/scripts/daily-report.mjs --dry-run          # 预览日报（推荐先跑）
+node ~/.argent-dsh/scripts/daily-report.mjs --force            # 立即推送
+node ~/.argent-dsh/scripts/daily-report.mjs --date YYYY-MM-DD  # 指定日期
+```
+脚本内部：逐店刷新 access token（refresh_token 轮换回写）→ 拉昨日+近7日订单（仅 `confirmed` 计销量，`cancelled` 单列）→ 拉在售商品库存/价格 → 聚合。
+
+### 步骤 3：报告结构与补货逻辑
+输出（Markdown）：
+- **昨日概览**：订单量 / 销售额 / 客单价 / 取消单数 + 环比昨日（读 `daily-report-cache/` 前日快照）
+- **🔥 畅销榜 Top N**（默认 5）：近7日按销量降序（并列按 GMV）
+- **⚠️ 补货提醒**：可售天数 `D = 库存 ÷ (近7日销量÷7)`，`D < 供货周期+安全缓冲`（默认 15+7=22）预警；库存=0 且近7日有销量 → 🔴 断货红警；建议补货量 `= ⌈阈值×日均销量 − 库存⌉`（不扣在途，参数可配）
+
+### 步骤 4：定时推送（cron，系统 crontab）
+- `init-ml.sh --daily-report` 注册：每小时 `0 * * * *` 执行 `daily-report.sh`；
+- 时间门控在脚本内：各店按**自己站点本地时间**判断是否到 `REPORT_TIME`（默认 08:00），推送**前一天**数据；
+- 幂等：`daily-report-cache/.pushed-<日期>-<店铺>` 标记防重复（`--force` 覆盖）；
+- 推送通道：**`ML_DAILY_CHAT_ID`（`ml-daily` 角色 lark-cli bot 身份，交互卡片）优先**；
+  未配置角色 Bot 时才回退 `FEISHU_WEBHOOK_URL`（群自定义机器人）——`config.json` 的 `mlDailyWebhook` 已弃用
+  （KB-057：设置页不再暴露该字段；代码见 `scripts/daily-report.mjs:530-548` 的 `chatId → webhook` 顺序）。
+
+### 浏览器模式（保留，兜底）
+旧流程不变：`ziniao-cli store list` 确认店铺 → `scripts/extract.js` 逐店采集（订单/在售/声誉/广告）→ `generate.js` 生成日报。API 模式失败时提示用户回退此模式。
+
+## 失败处理
+| 错误 | 处理 |
+|------|------|
+| 单店 token 刷新失败（refresh_token 过期） | 跳过该店，日报标注「数据缺失」，提示重跑 ml-oauth-setup.mjs 重新授权该店 |
+| 全部店铺失败 | 输出错误摘要，不推送 |
+| 非推送时段运行 | 提示使用 `--force` 立即执行 |
+| 浏览器模式页面加载失败 | 跳过该店铺，日报中标明「数据缺失」 |
+
+## 注意事项
+- 定时语义：**站点本地时间**（墨西哥 = UTC-6 无夏令时；巴西 = UTC-3）——推送时刻换算成北京约 22:00（墨西哥 08:00）
+- 环比依赖 `daily-report-cache/` 快照（保留 30 天滚动，脚本自动管理）
+- 切忌在日报中包含敏感信息（token/Secret 等），输出均为聚合运营指标
+- 多店铺串行采集，脚本内置限速；`ML_API_STORES_JSON`/`ARGENT_DATA_HOME` 可覆盖路径（测试用）

package/engine/skills/ml-store-daily-report/scripts/README.md

@@ -0,0 +1,25 @@
+# ml-store-daily-report / scripts
+
+## 数据源选择（v1.2.0）
+
+- **API 模式 = 主路径（唯一事实源）**：实现位于仓库 `scripts/daily-report.mjs`
+  （cron、agent 触发、人工测试均调用这一份），配合 `scripts/ml-oauth-setup.mjs`
+  （OAuth 授权向导）与 `scripts/daily-report.sh`（cron wrapper）。
+  改动/修复只改仓库 `scripts/` 下的实现，本目录**不要复制** API 实现。
+- **浏览器模式 = 兜底**：本目录 `extract.js`（经紫鸟窗口采集卖家后台页面）与
+  `generate.js`（旧日报模板），仅用于官方 API 未覆盖指标的人工触发场景。
+
+## 快速命令
+
+```bash
+# 授权（逐店，用该店紫鸟浏览器打开授权链接）
+node ~/.argent-dsh/scripts/ml-oauth-setup.mjs
+
+# 预览日报（不推送）
+node ~/.argent-dsh/scripts/daily-report.mjs --dry-run
+
+# 立即推送（跳过时间门控）
+node ~/.argent-dsh/scripts/daily-report.mjs --force
+```
+
+完整说明见 `docs/daily-report.md`。