@whyshu/argent-engine 0.7.3 → 0.7.4

package/engine/scripts/flow-trigger.sh

@@ -37,7 +37,7 @@ pick_py() {
     [ -x "$c" ] || continue
     "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue   # 硬要求：配置/发票生成必需
     "$c" -c 'import PIL, playwright' 2>/dev/null || \
-      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：bash scripts/python-runtime.sh ensure）" >&2
     printf '%s' "$c"; return 0
   done
   return 1

package/engine/scripts/gen-preset-rows.mjs

@@ -106,8 +106,28 @@ export function indentComposition(text) {
   return text.replace(/\n+$/, '\n').split('\n').map((l) => (l.trim() === '' ? '' : INDENT + l)).join('\n')
 }
 
+/**
+ * 0.2.x 只注册 `provider`/`model` 两个提示词变量；`cwd` 已移除（工作目录改由
+ * `dsh-working-directory` 作为**原生上下文**注入）。预设里若再写 `{{cwd}}`，
+ * 会话首轮就会 `unknown prompt variable` 直接失败 ⇒ 生成期就拦下（2026-10-18 P2 试点实测）。
+ */
+export const ALLOWED_PROMPT_VARS = ['provider', 'model']
+
+function assertPromptVars(id, text) {
+  const refs = [...text.matchAll(/\{\{([^{}]*)\}\}/g)].map((m) => m[1].trim())
+  const bad = [...new Set(refs.filter((v) => !ALLOWED_PROMPT_VARS.includes(v)))]
+  if (bad.length > 0) {
+    throw new Error(
+      `preset ${id} 引用了宿主未注册的提示词变量 ${bad.map((v) => `{{${v}}}`).join(', ')}；`
+      + `0.2.x 允许的变量：${ALLOWED_PROMPT_VARS.map((v) => `{{${v}}}`).join(', ')}`
+      + '（工作目录由 dsh-working-directory 上下文原生提供，不要写 {{cwd}}）',
+    )
+  }
+}
+
 /** 生成单个角色的 patch 文件内容（含跨版本行改写；改写记录写进文件头便于审计）。 */
 export function renderPatch({ id, meta, composition, order }) {
+  assertPromptVars(id, composition)
   const compat = applyRowCompat(composition)
   const name = (meta.name || id).replace(/'/g, "''")
   const desc = (meta.description || '').replace(/'/g, "''")

package/engine/scripts/invoice_stageb.py

@@ -18,6 +18,7 @@ from argent_datadir import resolve_data_dir  # noqa: E402  —— 勿在此复
 DATA = Path(resolve_data_dir()['dir'])
 CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
 PROFILE = str(DATA / "chrome-profile-xinhang")
+XZH_CDP_URL = os.environ.get("XZH_CDP_URL", "http://127.0.0.1:9223")
 TIMEOUT = 15000
 
 
@@ -27,9 +28,24 @@ def load_ctx():
     return m, c
 
 
+def _try_shared(p):
+    """优先连接常驻鑫中航 Chrome（CDP）；连不上返回 None，回退旧的一次性浏览器。"""
+    try:
+        browser = p.chromium.connect_over_cdp(XZH_CDP_URL, timeout=3000)
+        contexts = browser.contexts
+        if not contexts:
+            return None
+        return browser, contexts[0]
+    except Exception:
+        return None
+
+
 def browser():
     from playwright.sync_api import sync_playwright
     p = sync_playwright().start()
+    shared = _try_shared(p)
+    if shared:
+        return p, shared[1]
     ctx = p.chromium.launch_persistent_context(
         user_data_dir=PROFILE,
         executable_path=CHROME,
@@ -159,9 +175,12 @@ LABELS_DIR.mkdir(parents=True, exist_ok=True)
 
 
 def browser_ac():
-    """带 accept_downloads 的持久化 context（登录态复用；下载标签必需）。"""
+    """带 accept_downloads 的 context；优先常驻 Chrome，否则一次性 profile。"""
     from playwright.sync_api import sync_playwright
     p = sync_playwright().start()
+    shared = _try_shared(p)
+    if shared:
+        return p, shared[1]
     ctx = p.chromium.launch_persistent_context(
         user_data_dir=PROFILE,
         executable_path=CHROME,

package/engine/scripts/lib/agent-install.mjs

@@ -457,7 +457,16 @@ export async function runAgentInstall({
   }
   // ③ 快照**本次落盘面**（跨进程事务；失败即逐字节回滚 —— "⛔ 不写半截依赖图"）
   const surface = snapshotAgentSurface({ repo, dshHome, profile, id })
-  // ④ 调用**安装器本体**（唯一安装链）
+  // ④ **旧安装器已退役（2026-10-18）**：不再 spawn `install-argent.mjs`。
+  //    新链路 = @whyshu/argent 启动器（待发布）；此处 fail-fast，避免"进程启动失败"式的模糊报错。
+  if (!existsSync(join(repo, 'install-argent.mjs'))) {
+    return {
+      ok: false, step: 'installer-retired', argv: [], exitCode: null, stdout: '', stderr: '', out: '',
+      fix: '旧一句话安装器已退役（2026-10-18）。智能体安装/升级改由 @whyshu/argent 启动器承担（待发布）；本次没有写任何东西。',
+      logs: ['install-argent.mjs 已退役 ⇒ 本次不装 agent bundle（⛔ 不写半截依赖图）'], wrote: false,
+    }
+  }
+  // ⑤ 调用安装器本体（历史路径；仅当仓库里仍有安装器时）
   const argv = agentInstallArgv({ repo, dshHome, id })
   const child = spawn(process.execPath, argv, { env, cwd: cwd || repo, stdio: ['ignore', 'pipe', 'pipe'] })
   const logs = []

package/engine/scripts/lib/daily-report-core.mjs

@@ -426,26 +426,134 @@ export async function apiGet(path, token, opts = {}) {
   }
 }
 
-/** 拉窗口内订单（分页 + 节流）。只读。 */
-export async function fetchOrders(token, sellerId, fromISO, toISO, opts = {}) {
-  const all = []
+// ── 订单窗口取全量（P0，2026-10-18）：超限不再硬停，按整点二分 ──
+//
+// 事故：旧实现有 `all.length >= 5000` 的静默硬停；订单接口按 date_created 升序 ⇒
+// 截断丢的是**窗口尾部（最新）**，导致 2 店「昨日」被砍 40~58%（见 docs/日报数据出入-5000截断…）。
+// 现口径：
+//   ① 窗口先取一页（limit=50）读 paging.total；
+//   ② total ≤ 阈值(默认 4000) 或窗口 ≤ 2h ⇒ 直接分页拉全；
+//   ③ 否则在**整点边界**二分递归；合并后按 `order.id` 去重（防 `to` 整点扩展造成的边界重叠）；
+//   ④ 合并条数必须 == 根窗口 total；不等 ⇒ `complete=false`（**不假装成功**，由调用方告警）；
+//   ⑤ 总上限保护（默认 20000）⇒ `complete=false` + 告警，不硬撑。
+// 兼容：`fetchOrders()` 仍返回数组（内部走 WithMeta）；日报/对账不用大改。
+const ORDER_PAGE_LIMIT = 50
+const HOUR_MS = 3600 * 1000
+export const DEFAULT_ORDERS_SPLIT_THRESHOLD = 4000
+export const DEFAULT_ORDERS_MAX_TOTAL = 20000
+
+const envPositiveInt = (name, fallback) => {
+  const n = Number(process.env[name])
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}
+
+function orderSearchPath(sellerId, fromISO, toISO, offset) {
+  const p = new URLSearchParams({
+    seller: String(sellerId),
+    'order.date_created.from': fromISO,
+    'order.date_created.to': toISO,
+    limit: String(ORDER_PAGE_LIMIT),
+    offset: String(offset),
+  })
+  return `/orders/search?${p}`
+}
+
+/** 一个窗口内分页拉全（不再有 5000 硬停；`preloaded` = 已取到的第一页，避免重复请求）。 */
+async function fetchOrderWindow(token, sellerId, fromISO, toISO, opts = {}, preloaded = null) {
+  const orders = []
   let offset = 0
+  let total = null
+  let page = preloaded
   for (;;) {
-    const p = new URLSearchParams({
-      seller: String(sellerId),
-      'order.date_created.from': fromISO,
-      'order.date_created.to': toISO,
-      limit: '50',
-      offset: String(offset),
-    })
-    const d = await apiGet(`/orders/search?${p}`, token, { base: opts.base })
-    all.push(...(d.results || []))
-    const total = (d.paging && d.paging.total) || all.length
-    if (all.length >= total || all.length >= 5000 || !(d.results || []).length) break
-    offset += 50
+    const d = page || await apiGet(orderSearchPath(sellerId, fromISO, toISO, offset), token, { base: opts.base })
+    page = null
+    orders.push(...(d.results || []))
+    if (total === null) {
+      const n = Number(d.paging && d.paging.total)
+      total = Number.isFinite(n) ? n : orders.length
+    }
+    if (orders.length >= total || !(d.results || []).length) break
+    offset += ORDER_PAGE_LIMIT
     await sleep(Number(process.env.ML_PAGE_GAP_MS || 60))   // 翻页节流：降低被限流概率
   }
-  return all
+  return { orders, total, got: orders.length }
+}
+
+/**
+ * 拉窗口内订单并返回完整度元信息。只读。
+ * @returns {{orders:object[], total:number, got:number, complete:boolean, windows:object[], reason:string}}
+ */
+export async function fetchOrdersWithMeta(token, sellerId, fromISO, toISO, opts = {}) {
+  const threshold = Number(opts.splitThreshold) > 0
+    ? Number(opts.splitThreshold)
+    : envPositiveInt('ML_ORDERS_SPLIT_THRESHOLD', DEFAULT_ORDERS_SPLIT_THRESHOLD)
+  const maxTotal = Number(opts.maxTotal) > 0
+    ? Number(opts.maxTotal)
+    : envPositiveInt('ML_ORDERS_MAX_TOTAL', DEFAULT_ORDERS_MAX_TOTAL)
+
+  const rootFirst = await apiGet(orderSearchPath(sellerId, fromISO, toISO, 0), token, { base: opts.base })
+  const rootTotalRaw = Number(rootFirst && rootFirst.paging && rootFirst.paging.total)
+  const rootTotal = Number.isFinite(rootTotalRaw) ? rootTotalRaw : (rootFirst.results || []).length
+
+  if (rootTotal > maxTotal) {
+    return { orders: [], total: rootTotal, got: 0, complete: false, windows: [],
+      reason: `max-total(>${maxTotal})` }
+  }
+
+  const windows = []
+  let failed = false
+
+  async function collect(from, to, preloaded) {
+    const fromMs = Date.parse(from)
+    const toMs = Date.parse(to)
+    const first = preloaded || await apiGet(orderSearchPath(sellerId, from, to, 0), token, { base: opts.base })
+    const t = Number(first && first.paging && first.paging.total)
+    const total = Number.isFinite(t) ? t : (first.results || []).length
+    // 小窗口/极窄窗口：单窗口分页拉全
+    if (total <= threshold || !(toMs - fromMs > 2 * HOUR_MS)) {
+      const w = await fetchOrderWindow(token, sellerId, from, to, opts, first)
+      windows.push({ from, to, total: w.total, got: w.got })
+      return w.orders
+    }
+    // 整点边界二分；取不到合法中点（窗口过窄）⇒ 退化为单窗口拉全
+    const midMs = Math.floor(((fromMs + toMs) / 2) / HOUR_MS) * HOUR_MS
+    if (!(midMs > fromMs && midMs < toMs)) {
+      const w = await fetchOrderWindow(token, sellerId, from, to, opts, first)
+      windows.push({ from, to, total: w.total, got: w.got })
+      return w.orders
+    }
+    const mid = new Date(midMs).toISOString()
+    const left = await collect(from, mid, null)
+    const right = await collect(mid, to, null)
+    return [...left, ...right]
+  }
+
+  async function safeCollect(from, to, preloaded) {
+    try { return await collect(from, to, preloaded) } catch (error) {
+      failed = true
+      windows.push({ from, to, error: String((error && error.message) || error).slice(0, 200) })
+      return []
+    }
+  }
+
+  const all = await safeCollect(fromISO, toISO, rootFirst)
+  const seen = new Map()
+  for (const o of all) {
+    if (o && o.id != null) seen.set(String(o.id), o)
+    else if (o) seen.set(`__anon_${seen.size}`, o)
+  }
+  const orders = [...seen.values()]
+  const complete = !failed && orders.length === rootTotal
+  return {
+    orders, total: rootTotal, got: orders.length, complete, windows,
+    reason: complete ? 'ok' : failed ? 'window-error' : `short(${orders.length}/${rootTotal})`,
+  }
+}
+
+/** 兼容入口：返回订单数组（日报/对账既有调用方签名不变）。 */
+export async function fetchOrders(token, sellerId, fromISO, toISO, opts = {}) {
+  const meta = await fetchOrdersWithMeta(token, sellerId, fromISO, toISO, opts)
+  return meta.orders
 }
 
 // ── OAuth token（刷新 + 轮换回写交给调用方）──────────────────

package/engine/scripts/lib/dsh-versions.mjs

@@ -21,7 +21,23 @@
  * ⇒ 客户看到一条毫无意义的告警）。防漂移门禁 = `verifiedListGaps()`（回归
  * `scripts/tests/dsh-verified-list.test.mjs` 钉住"缺项即红"）。
  */
-export const DSH_VERIFIED_FALLBACK = ['0.1.0-rc.6', '0.1.0-rc.7', '0.1.1-rc.1', '0.1.5-rc.1', '0.1.7-rc.2']
+export const DSH_VERIFIED_FALLBACK = ['0.1.0-rc.6', '0.1.0-rc.7', '0.1.1-rc.1', '0.1.5-rc.1', '0.1.7-rc.2', '0.2.0-rc.2', '0.2.1-rc.2']
+
+/**
+ * **最小支持宿主版本**（唯一真源，2026-10-18 用户决定：「以后机器都要求升级到与本机一致才能用」）。
+ *
+ * 为什么是硬下限而不是"窗口内任选"：0.2.x 改动会让旧宿主上的 argent 预设/插件直接失败
+ * （典型：0.2.x 移除 `{{cwd}}` 提示词变量 ⇒ 所有旧预设首轮 `unknown prompt variable` 失败；
+ * 另有 patch 面/peer 门禁变化）。旧宿主上"装得上"≠"能跑"，所以窗口统一收敛到 ≥ 0.2.1-rc.2。
+ * 逃生阀仍是 `--allow-unsupported-host`（内部/验证用，带告警+审计）。
+ */
+export const DSH_MIN_SUPPORTED = '0.2.1-rc.2'
+
+/** 判断某个 dsh 版本是否满足最小支持版本（纯函数；`rc` 版本按 cmpVer 比较）。 */
+export function isSupportedHostVersion(version, min = DSH_MIN_SUPPORTED) {
+  if (!version) return false
+  return cmpVer(String(version).trim(), min) >= 0
+}
 
 /**
  * **防漂移门禁**：`verified`（安装器实际会用的清单）是否覆盖 `lockDir` 里**已晋级**的每个版本。

package/engine/scripts/lib/ml-ads-core.mjs

@@ -0,0 +1,204 @@
+/**
+ * ml-ads-core.mjs —— Mercado Ads（Product Ads）只读取数 + 聚合 + 告警（L1 执行内核，纯逻辑）。
+ *
+ * ## 为什么单独一份
+ * 「广告」这块要同时服务两个消费方：
+ *   · `scripts/ml-ads.mjs`（只读 CLI：人工/角色对话按需查广告效果）；
+ *   · `scripts/daily-report.mjs`（日报卡片里的「广告」分区）。
+ * 两边**必须同一份口径**（花费、ROAS、ACoS、单量），所以取数/聚合/告警全放这里，
+ * ⛔ 不在两个入口各写一份（口径一漂两边各自"正确"，历史已踩过：日报 vs 平台对账）。
+ *
+ * ## 纪律（与 daily-report-core.mjs 一致）
+ *   · **纯 L1**：只 import `node:` 内建；⛔ 不 import 宿主模块（`scripts/tests/kernel-purity.test.mjs` 扫）；
+ *   · **零平台域名**：HTTP 入口由调用方注入（`apiGet`），本文件不认任何域名；
+ *   · **零写盘**：本文件不出现在任何写路径上（token 轮换写回由调用方负责）。
+ *
+ * ## 口径（2026-10 实测，MELI 现行 API）
+ *   · 广告主：`GET /advertising/advertisers?product_id=PADS` → `{advertisers:[{advertiser_id, site_id, ...}]}`
+ *   · 活动：`GET /advertising/{site}/advertisers/{id}/product_ads/campaigns/search`
+ *     （`date_from`/`date_to` + `metrics`；**必须逐页累加**——`metrics_summary=true` 只汇总返回的那一条，
+ *     ⛔ 不能当账户总额用，2026-10-17 实测踩过）
+ *   · 旧 `product_ads/ads/*` 已于 2026-05/06 下线 ⇒ 统一走 campaign 维度（单品下钻用 ad_groups）。
+ *   · 指标可回溯 90 天；数据每天 10:00 (GMT-3) 更新。
+ */
+
+/** 请求的活动指标（逗号串直接拼进 query）。 */
+export const ADS_METRICS = [
+  'clicks', 'prints', 'ctr', 'cost', 'cpc', 'acos', 'roas',
+  'units_quantity', 'total_amount', 'direct_amount', 'indirect_amount',
+  'advertising_items_quantity',
+].join(',')
+
+/** 默认告警阈值（可按店铺/全局覆盖）。 */
+export const ADS_ALERT_DEFAULTS = {
+  acosWarn: 25,     // %：ACoS 超过 ⇒ 🟡
+  acosBad: 35,      // %：ACoS 超过 ⇒ 🔴
+  minSpend: 100,    // 本币：花费低于此值不告警（避免小样本噪声）
+  minRoas: 2,       // ROAS 低于此值且花费达标 ⇒ 🔴
+}
+
+const num = (x) => Number(x || 0)
+
+/**
+ * 纯函数：把一批 campaign（含 `metrics`）聚合成总额 + 派生指标。
+ * @param {Array<{id?:any,name?:string,status?:string,metrics?:object}>} campaigns
+ */
+export function deriveAdsTotals(campaigns = []) {
+  const t = { clicks: 0, prints: 0, cost: 0, units: 0, amount: 0, directAmount: 0, indirectAmount: 0, campaigns: campaigns.length, activeCampaigns: 0 }
+  for (const c of campaigns) {
+    const m = (c && c.metrics) || {}
+    t.clicks += num(m.clicks)
+    t.prints += num(m.prints)
+    t.cost += num(m.cost)
+    t.units += num(m.units_quantity)
+    t.amount += num(m.total_amount)
+    t.directAmount += num(m.direct_amount)
+    t.indirectAmount += num(m.indirect_amount)
+    if (String(c && c.status || '').toLowerCase() === 'active') t.activeCampaigns++
+  }
+  t.cost = round2(t.cost)
+  t.amount = round2(t.amount)
+  t.directAmount = round2(t.directAmount)
+  t.indirectAmount = round2(t.indirectAmount)
+  t.roas = t.cost > 0 ? round2(t.amount / t.cost) : 0
+  t.acos = t.amount > 0 ? round2((t.cost / t.amount) * 100) : 0
+  t.cpc = t.clicks > 0 ? round2(t.cost / t.clicks) : 0
+  t.ctr = t.prints > 0 ? round2((t.clicks / t.prints) * 100) : 0
+  t.cvr = t.clicks > 0 ? round2((t.units / t.clicks) * 100) : 0
+  return t
+}
+
+/** 纯函数：告警分级（返回 `[{level:'red'|'yellow', code, text}]`，text 为中文可读句）。 */
+export function classifyAdsAlerts(totals, opts = {}) {
+  const o = { ...ADS_ALERT_DEFAULTS, ...opts }
+  const alerts = []
+  const t = totals || {}
+  const spend = num(t.cost)
+  if (spend <= 0) return alerts
+  const amount = num(t.amount)
+  const big = spend >= num(o.minSpend)
+  if (amount <= 0) {
+    // 花钱但零广告销售额：**不管花多少都要报**（小钱也是白烧）
+    alerts.push({ level: 'red', code: 'zero_conversion', text: `花费 ${fmtMoney(spend)} 但广告销售额 0（烧钱零转化）` })
+    return alerts
+  }
+  // 容错：调用方可能只给 cost/amount（没预算 acos/roas）⇒ 这里自己算，避免"没告警=真健康"的假绿
+  const acos = t.acos != null ? num(t.acos) : round2((spend / amount) * 100)
+  const roas = t.roas != null ? num(t.roas) : (spend > 0 ? round2(amount / spend) : 0)
+  // ACoS / ROAS 告警只在「花费达到 minSpend」时给：小钱的比例噪声大，报了会训练人忽略告警
+  if (big) {
+    if (acos > num(o.acosBad)) alerts.push({ level: 'red', code: 'acos_bad', text: `ACoS ${acos}%（阈值 ${o.acosBad}%）偏高` })
+    else if (acos > num(o.acosWarn)) alerts.push({ level: 'yellow', code: 'acos_warn', text: `ACoS ${acos}%（阈值 ${o.acosWarn}%）偏高` })
+    if (roas > 0 && roas < num(o.minRoas)) {
+      alerts.push({ level: 'red', code: 'roas_low', text: `ROAS ${roas} 低于 ${o.minRoas}` })
+    }
+  }
+  return alerts
+}
+
+/**
+ * 只读取数：一个店铺 → 广告主列表 + 每个广告主的活动聚合 + 总计。
+ * @param {{apiGet:Function, token:string, site:string, dateFrom:string, dateTo:string, pageSize?:number, maxPages?:number, metrics?:string}} p
+ */
+export async function fetchAdsReport({ apiGet, token, site, dateFrom, dateTo, pageSize = 50, maxPages = 40, metrics = ADS_METRICS }) {
+  if (typeof apiGet !== 'function') throw new Error('fetchAdsReport 需要注入 apiGet')
+  const advRes = await apiGet('/advertising/advertisers?product_id=PADS', token)
+  const advertisers = (advRes && advRes.advertisers) || []
+  const perAdvertiser = []
+  for (const a of advertisers) {
+    const advSite = a.site_id || site
+    let offset = 0, total = null
+    const campaigns = []
+    for (let page = 0; page < maxPages; page++) {
+      const q = new URLSearchParams({
+        limit: String(pageSize), offset: String(offset),
+        date_from: dateFrom, date_to: dateTo, metrics,
+      })
+      const r = await apiGet(`/advertising/${advSite}/advertisers/${a.advertiser_id}/product_ads/campaigns/search?${q}`, token)
+      const rows = (r && r.results) || []
+      campaigns.push(...rows)
+      total = (r && r.paging && r.paging.total) ?? campaigns.length
+      offset += pageSize
+      if (!rows.length || campaigns.length >= total || offset >= 10000) break
+    }
+    const totals = deriveAdsTotals(campaigns)
+    perAdvertiser.push({
+      advertiserId: a.advertiser_id, site: advSite, name: a.advertiser_name || '', account: a.account_name || '',
+      campaignTotal: total ?? campaigns.length, totals,
+      topCampaigns: pickCampaigns(campaigns),
+    })
+  }
+  const combined = combineTotals(perAdvertiser.map((x) => x.totals))
+  return { site, dateFrom, dateTo, advertisers: perAdvertiser, totals: combined }
+}
+
+/** 纯函数：多广告主合计（同一店铺可能多个 advertiser）。 */
+export function combineTotals(list = []) {
+  const sum = list.reduce((a, t) => {
+    a.clicks += num(t.clicks); a.prints += num(t.prints); a.cost += num(t.cost)
+    a.units += num(t.units); a.amount += num(t.amount); a.campaigns += num(t.campaigns)
+    return a
+  }, { clicks: 0, prints: 0, cost: 0, units: 0, amount: 0, campaigns: 0 })
+  sum.cost = round2(sum.cost); sum.amount = round2(sum.amount)
+  sum.roas = sum.cost > 0 ? round2(sum.amount / sum.cost) : 0
+  sum.acos = sum.amount > 0 ? round2((sum.cost / sum.amount) * 100) : 0
+  sum.cpc = sum.clicks > 0 ? round2(sum.cost / sum.clicks) : 0
+  sum.ctr = sum.prints > 0 ? round2((sum.clicks / sum.prints) * 100) : 0
+  sum.cvr = sum.clicks > 0 ? round2((sum.units / sum.clicks) * 100) : 0
+  return sum
+}
+
+/** 纯函数：挑出「花钱最多 / ACoS 超标」的活动（用于下钻展示）。 */
+export function pickCampaigns(campaigns = [], { topSpend = 3, badAcos = ADS_ALERT_DEFAULTS.acosBad, minSpend = 50 } = {}) {
+  const rows = campaigns.map((c) => ({
+    id: c.id, name: c.name || String(c.id || ''), status: String(c.status || ''),
+    cost: round2(num(c.metrics && c.metrics.cost)),
+    amount: round2(num(c.metrics && c.metrics.total_amount)),
+    clicks: num(c.metrics && c.metrics.clicks),
+    units: num(c.metrics && c.metrics.units_quantity),
+    roas: round2(num(c.metrics && c.metrics.roas)),
+    acos: round2(num(c.metrics && c.metrics.acos)),
+  })).filter((x) => x.cost > 0)
+  const top = [...rows].sort((a, b) => b.cost - a.cost).slice(0, topSpend)
+  const bad = rows.filter((x) => x.cost >= minSpend && (x.acos > badAcos || x.amount <= 0))
+    .sort((a, b) => b.cost - a.cost).slice(0, 3)
+  return { top, bad }
+}
+
+/** 纯函数：单行金额（只做千分位，不带币种——币种由调用方按店铺站点加）。 */
+export function fmtMoney(n) {
+  const v = num(n)
+  return v.toLocaleString('en-US', { maximumFractionDigits: 2 })
+}
+
+/**
+ * 纯函数：把结果渲染成中文卡片行（日报分区 / CLI 共用）。
+ * @param {object} report fetchAdsReport 的返回
+ * @param {{currency?:string, alertOpts?:object, title?:string}} opts
+ */
+export function adsCardLines(report, opts = {}) {
+  const cur = opts.currency || ''
+  const m = (n) => `${cur ? cur + ' ' : ''}${fmtMoney(n)}`
+  const out = []
+  if (!report || !report.advertisers || !report.advertisers.length) {
+    out.push('**📣 广告**：未找到广告主（该店未开通 Mercado Ads 或没有广告账户）')
+    return out
+  }
+  const t = report.totals || {}
+  out.push(`**📣 广告**（${report.dateFrom} ~ ${report.dateTo}，Product Ads）`)
+  out.push(`花费 ${m(t.cost)} · 广告销售额 ${m(t.amount)} · **ROAS ${t.roas}** · ACoS ${t.acos}% · 点击 ${t.clicks} · 广告单量 ${t.units} · ${t.campaigns} 个活动`)
+  for (const a of report.advertisers) {
+    const at = a.totals || {}
+    const alerts = classifyAdsAlerts(at, opts.alertOpts)
+    const flag = alerts.some((x) => x.level === 'red') ? '🔴' : alerts.length ? '🟡' : '✅'
+    out.push(`${flag} 广告主 ${a.advertiserId}：花费 ${m(at.cost)} / ROAS ${at.roas} / ACoS ${at.acos}% / 单量 ${at.units}（${a.campaignTotal} 个活动）`)
+    for (const al of alerts) out.push(`　└ ${al.level === 'red' ? '🔴' : '🟡'} ${al.text}`)
+    const bad = (a.topCampaigns && a.topCampaigns.bad) || []
+    for (const c of bad.slice(0, 3)) {
+      out.push(`　└ ${c.amount <= 0 ? '🔴 零转化' : '🟡 ACoS 高'}「${c.name}」花费 ${m(c.cost)} / ROAS ${c.roas} / ACoS ${c.acos}%`)
+    }
+  }
+  return out
+}
+
+const round2 = (x) => Math.round(Number(x || 0) * 100) / 100

package/engine/scripts/lib/plugin-packages.mjs

@@ -44,6 +44,7 @@ export const NPM_SCOPE = '@whyshu'
  * `npm`  = npm 包名（`package.json#name`、`dependencies` 键、组合行 `name:`）。
  */
 export const PLUGIN_PACKAGES = [
+  { id: 'argent-dsh', npm: `${NPM_SCOPE}/argent-dsh` },
   { id: 'argent-core', npm: `${NPM_SCOPE}/argent-core` },
   { id: 'argent-skin', npm: `${NPM_SCOPE}/argent-skin` },
   { id: 'argent-presets', npm: `${NPM_SCOPE}/argent-presets` },