@whyshu/argent-engine 0.7.2 → 0.7.4

package/engine/scripts/ml-ads.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * ml-ads.mjs —— Mercado Ads（Product Ads）**只读**效果报告 CLI。
+ *
+ * ## 干什么
+ * 用与日报同一条授权链（`~/.dsh/argent/ml-api-stores.json`）逐店拉广告数据，输出：
+ *   花费 / 广告销售额 / ROAS / ACoS / 点击 / CTR / CPC / 广告单量，
+ *   外加**告警**（ACoS 超标、烧钱零转化、ROAS 过低）和活动级下钻。
+ *
+ * ## 用法
+ *   node scripts/ml-ads.mjs                          # 全部已授权店铺 · 近 7 个完整自然日
+ *   node scripts/ml-ads.mjs --store 1店               # 店铺子串过滤
+ *   node scripts/ml-ads.mjs --days 30                 # 回溯天数（MELI 上限 90）
+ *   node scripts/ml-ads.mjs --to 2026-10-16           # 指定结束日（站点本地）
+ *   node scripts/ml-ads.mjs --detail                  # 附「花钱最多 / ACoS 超标」活动
+ *   node scripts/ml-ads.mjs --json                    # 结构化输出（stdout 纯 JSON）
+ *   node scripts/ml-ads.mjs --lines                   # 只输出中文卡片行（给日报/角色回复用）
+ *   node scripts/ml-ads.mjs --list                    # 只列每店广告主，不拉活动
+ *   node scripts/ml-ads.mjs --acos-bad 30 --min-spend 200   # 告警阈值
+ *
+ * ## 只读纪律
+ *   · 只发 GET（`/advertising/...`）；⛔ 不改预算/暂停/调价，也不写任何客户数据；
+ *   · 唯一写盘 = token 轮换回写（MELI refresh_token 是轮换制，不写回下次必 429）：
+ *     原子写（tmp + rename）、保持 600；
+ *   · API 基址：`ML_API_BASE` → 默认平台地址（引擎 lib 里⛔不含域名，只在本 CLI 注入）。
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, chmodSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import {
+  loadEnvFile, refreshStoreToken, apiGet as coreApiGet,
+  SITE_TZ, SITE_CURRENCY, fallbackSite, startOfLocalDayUTC, localDateStr, matchStores,
+} from './lib/daily-report-core.mjs'
+import {
+  fetchAdsReport, classifyAdsAlerts, adsCardLines, fmtMoney, ADS_ALERT_DEFAULTS,
+} from './lib/ml-ads-core.mjs'
+
+const API_BASE = () => process.env.ML_API_BASE || 'https://api.mercadolibre.com'
+
+const args = process.argv.slice(2)
+const argVal = (n) => { const i = args.indexOf(n); return i >= 0 && args[i + 1] ? args[i + 1] : null }
+const has = (n) => args.includes(n)
+
+if (has('-h') || has('--help')) {
+  console.log(`Mercado Ads 只读报告
+
+用法: node scripts/ml-ads.mjs [选项]
+  --store <名或uid>   店铺过滤（名称子串 / uid 全等，与日报同一判据）
+  --days <n>          回溯天数，默认 7（MELI 上限 90）
+  --to <YYYY-MM-DD>   结束日（站点本地），默认「昨天」
+  --detail            附活动级下钻（花钱最多 + ACoS 超标）
+  --list              只列出每店广告主（1 请求/店）
+  --json              结构化 JSON（stdout）
+  --lines             中文卡片行（给日报分区/角色回复复用）
+  --acos-warn <n>     ACoS 黄色阈值，默认 ${ADS_ALERT_DEFAULTS.acosWarn}
+  --acos-bad <n>      ACoS 红色阈值，默认 ${ADS_ALERT_DEFAULTS.acosBad}
+  --min-spend <n>     告警最小花费（本币），默认 ${ADS_ALERT_DEFAULTS.minSpend}
+  --env <path>        daily-report.env 路径
+退出码: 0 正常 ｜ 1 用法/取数失败 ｜ 2 全部店铺失败`)
+  process.exit(0)
+}
+
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const ENV_PATH = argVal('--env') || join(DATA_DIR, 'daily-report.env')
+const STORES_PATH = process.env.ML_API_STORES_JSON || join(DATA_DIR, 'ml-api-stores.json')
+const env = loadEnvFile(ENV_PATH)
+const doc = existsSync(STORES_PATH) ? JSON.parse(readFileSync(STORES_PATH, 'utf8')) : { stores: [] }
+const stores = doc.stores || []
+
+const persistStores = () => {
+  try {
+    mkdirSync(dirname(STORES_PATH), { recursive: true })
+    const tmp = `${STORES_PATH}.tmp`
+    writeFileSync(tmp, JSON.stringify({ stores }, null, 2) + '\n', { mode: 0o600 })
+    renameSync(tmp, STORES_PATH)
+    chmodSync(STORES_PATH, 0o600)
+  } catch (e) { console.error(`✗ token 写回失败：${e.message}`) }
+}
+const apiGet = (path, token) => coreApiGet(path, token, { base: API_BASE() })
+
+const alertOpts = {
+  acosWarn: Number(argVal('--acos-warn') || ADS_ALERT_DEFAULTS.acosWarn),
+  acosBad: Number(argVal('--acos-bad') || ADS_ALERT_DEFAULTS.acosBad),
+  minSpend: Number(argVal('--min-spend') || ADS_ALERT_DEFAULTS.minSpend),
+  minRoas: ADS_ALERT_DEFAULTS.minRoas,
+}
+
+const FLAG_JSON = has('--json')
+const FLAG_LINES = has('--lines')
+const FLAG_DETAIL = has('--detail')
+const FLAG_LIST = has('--list')
+const days = Math.max(1, Math.min(90, Number(argVal('--days') || 7)))
+const toArg = argVal('--to')
+
+const now = new Date()
+const picked = matchStores(stores, (argVal('--store') || '').split(',').map((x) => x.trim()).filter(Boolean))
+if (!picked.length) {
+  console.error(`✗ 没有匹配到店铺（已授权 ${stores.length} 家）`)
+  process.exit(1)
+}
+
+const results = []
+for (const store of picked) {
+  const site = fallbackSite(store.site)
+  const tz = SITE_TZ[site]
+  const todayStart = startOfLocalDayUTC(tz, now)
+  const toMs = toArg ? startOfLocalDayUTC(tz, new Date(`${toArg}T12:00:00Z`)) : todayStart - 86400000
+  const fromMs = toMs - (days - 1) * 86400000
+  const dateFrom = localDateStr(tz, new Date(fromMs))
+  const dateTo = localDateStr(tz, new Date(toMs))
+  const row = { store: store.name, site, uid: store.user_id, currency: SITE_CURRENCY[site] || '', dateFrom, dateTo }
+  try {
+    const token = await refreshStoreToken(env, store, { onRotate: persistStores })
+    if (FLAG_LIST) {
+      const adv = await apiGet('/advertising/advertisers?product_id=PADS', token)
+      row.advertisers = (adv.advertisers || []).map((a) => ({ advertiser_id: a.advertiser_id, site: a.site_id, name: a.advertiser_name }))
+      results.push(row)
+      continue
+    }
+    const report = await fetchAdsReport({ apiGet, token, site, dateFrom, dateTo })
+    row.report = report
+    row.alerts = classifyAdsAlerts(report.totals, alertOpts)
+    results.push(row)
+  } catch (e) {
+    row.error = String(e.message || e)
+    results.push(row)
+  }
+}
+
+// ── 输出 ───────────────────────────────────────────────────
+const ok = results.filter((r) => !r.error)
+if (!ok.length) {
+  if (FLAG_JSON) console.log(JSON.stringify({ results }, null, 2))
+  else for (const r of results) console.error(`✗ ${r.store}：${r.error}`)
+  process.exit(2)
+}
+if (FLAG_JSON) { console.log(JSON.stringify({ generatedAt: now.toISOString(), days, results }, null, 2)); process.exit(0) }
+
+if (FLAG_LINES) {
+  for (const r of ok) {
+    const lines = adsCardLines(r.report, { currency: r.currency, alertOpts })
+    console.log(`### ${r.store}`)
+    console.log(lines.join('\n'))
+  }
+  process.exit(0)
+}
+
+if (FLAG_LIST) {
+  for (const r of results) {
+    if (r.error) { console.log(`${r.store}: ✗ ${r.error}`); continue }
+    console.log(`${r.store}（${r.site}）：` + (r.advertisers.length ? r.advertisers.map((a) => `${a.advertiser_id}(${a.site})`).join(', ') : '无广告主'))
+  }
+  process.exit(0)
+}
+
+const hdr = ['店铺', '站点', '花费', '销售额', 'ROAS', 'ACoS', '点击', 'CTR', '广告单量', '活动']
+let text = `## 📣 Mercado Ads · ${ok[0].dateFrom} ~ ${ok[0].dateTo}（近 ${days} 天）\n\n`
+text += '| ' + hdr.join(' | ') + ' |\n|' + hdr.map(() => '---').join('|') + '|\n'
+const allAlerts = []
+for (const r of results) {
+  if (r.error) { text += `| ${r.store} | ${r.site} | — | — | — | — | — | — | — | ✗ ${r.error.slice(0, 40)} |\n`; continue }
+  const t = r.report.totals
+  const c = r.currency ? r.currency + ' ' : ''
+  text += `| ${r.store} | ${r.site} | ${c}${fmtMoney(t.cost)} | ${c}${fmtMoney(t.amount)} | ${t.roas} | ${t.acos}% | ${t.clicks} | ${t.ctr}% | ${t.units} | ${t.campaigns} |\n`
+  for (const a of r.alerts) allAlerts.push({ store: r.store, ...a })
+  if (FLAG_DETAIL) {
+    for (const a of r.report.advertisers) {
+      const top = [...(a.topCampaigns.top || [])]
+      for (const cp of top) text += `| ↳ ${r.store}·${cp.name.slice(0, 24)} | ${a.advertiserId} | ${c}${fmtMoney(cp.cost)} | ${c}${fmtMoney(cp.amount)} | ${cp.roas} | ${cp.acos}% | ${cp.clicks} | — | ${cp.units} | — |\n`
+    }
+  }
+}
+text += '\n'
+if (allAlerts.length) {
+  text += '### ⚠️ 告警\n'
+  for (const a of allAlerts) text += `- ${a.level === 'red' ? '🔴' : '🟡'} **${a.store}**：${a.text}\n`
+} else {
+  text += '✅ 无告警（ACoS 与 ROAS 均在阈值内）\n'
+}
+console.log(text)

package/engine/scripts/ml-oauth-setup.mjs

@@ -49,7 +49,7 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
 // 其他站点域名实测被拦（403），后续逐个站点验证后更新此表。
 const AUTH_HOSTS = {
   MLM: 'auth.mercadolibre.com.mx',
-  MLB: 'auth.mercadolibre.com.br',
+  MLB: 'auth.mercadolivre.com.br',   // 2026-10-17 实测修正：巴西站点域名是 mercadolivre（auth.mercadolibre.com.br 无 DNS）
   MLA: 'auth.mercadolibre.com.ar',
   MLC: 'auth.mercadolibre.cl',
   MCO: 'auth.mercadolibre.com.co',

package/engine/scripts/orchestrator.py

@@ -7349,6 +7349,16 @@ class Orchestrator:
             i = j + 1
         return ",".join(out)
 
+    def _write_status_done(self, record_id: str) -> None:
+        """**唯一入口**：把 `FULL状态` 置为「已完成」。
+
+        2026-10-16：原先只有 `_finalize_ticket_complete`（引擎自己跑完）能置位；现在
+        「运营手动完成（hub-v2 实测）」也要置位（用户口径「都要」）⇒ 抽出本入口，两条路径
+        **都走这里**，保持"表状态只有一个写点"的不变量（回归见 ticket-completion-criteria /
+        step-progress-realtime 的 AST 断言）。
+        """
+        self.feishu.update_status(record_id, "done")
+
     def _finalize_ticket_complete(self, *, label: str = "全部完成",
                                   notify: bool = True) -> bool:
         """**唯一**的「整票完成态」写入入口（`FULL状态=已完成` + `当前步骤` + 完成卡）。
@@ -7372,7 +7382,7 @@ class Orchestrator:
                          "field": "ticket-complete", "value": label[:120],
                          "why": "premature-completion-ticket", "missing_steps": missing})
             return False
-        self.feishu.update_status(self.state.record_id, "done")
+        self._write_status_done(self.state.record_id)
         self.feishu.update_step_progress(self.state.record_id, label, force=True, done=True,
                                         ticket_attestation=self._ticket_attestation())
         self.feishu.set_confirm(self.state.record_id, False)
@@ -7761,11 +7771,11 @@ class Orchestrator:
         ## 写什么 / ⛔ 不写什么（用户口径）
         - **写**：`FULL备注` ← 「识别为运营手动完成（依据 hub-v2 实测）：<逐项>」（同源同文，
           与 `--mode hub-status` 打印、与 `failures.jsonl#hub_status` 完全一致）；
-          `当前步骤` ← 「已识别为运营手动完成（hub-v2 实测）」；`就绪=false`（消费掉拾取位）。
-        - **⛔ 不写**：`FULL状态` —— 「不得据此自动改写 FULL状态（那一步留给人/用户）」。所以
-          这里**故意不调** `update_status`：表的最终状态由运营确认后自己置位。
-          ⚠️ 因此 `当前步骤` 也**不写「全部完成」**（那句只属于"引擎自己跑完"的路径，
-          写了就会造成「表=完成、台账=blocked」的错位——今天已出现 2 次）。
+          `当前步骤` ← **「全部完成」**（2026-10-16 用户口径：表口径与"引擎自己跑完"一致）；`就绪=false`（消费掉拾取位）。
+          **`FULL状态` ← 已完成**（2026-10-16 用户口径「都要」：认定即置位，否则票一直挂在"失败"里，
+          运营每轮巡检都要人工排除；判据仍是 hub-v2 三项全 True，比表里的旧状态权威）。
+        - **仍不写**：不发「FULL 货件完成」卡、不写 `ticket_attestation`（卡与存证只属于引擎自己
+          跑完的路径）；"谁完成的"这件事仍由 `FULL备注` 那句话交代。
 
         返回 `{"status": "already_completed", "identified_as": "manual-completion-by-hub", …}`
         ⇒ `_execute_steps` 见 `already_completed` 即停止后续步骤。
@@ -7773,13 +7783,15 @@ class Orchestrator:
         rid = self.state.record_id
         note = f"{self.HUB_MANUAL_NOTE}：" + "；".join(verdict.get("items") or [])
         self._log(f"  🧾 {self.HUB_MANUAL_NOTE}：{verdict.get('reason') or ''}"
-                  f"（货件 #{self.state.shipment_id}）—— 按用户口径**不改写 FULL状态**")
+                  f"（货件 #{self.state.shipment_id}）—— 并置 FULL状态=已完成（2026-10-16 用户口径）")
         if rid and not getattr(self.feishu, "dry_run", False):
             try:
                 self.feishu.set_note(rid, note[:900])
-                self.feishu.update_step_progress(rid, "已识别为运营手动完成（hub-v2 实测）",
+                self.feishu.update_step_progress(rid, "全部完成",
                                                  force=True)
                 self.feishu.set_confirm(rid, False)
+                # 2026-10-16 用户口径（「都要」）：认定运营手动完成 ⇒ 一并置 FULL状态=已完成
+                self._write_status_done(rid)
             except Exception as exc:                          # noqa: BLE001
                 self._log(f"  ⚠️ 写「运营手动完成」备注失败（不影响判定）: {exc}")
         return {
@@ -7788,10 +7800,29 @@ class Orchestrator:
             "identified_as": "manual-completion-by-hub",
             "hub_note": note[:900],
             "hub_status": verdict,
-            "status_unchanged": True,     # 显式标注：没有改写 FULL状态（下游据此别误判"已完成"）
+            "status_unchanged": False,    # 已改写 FULL状态（2026-10-16 起）
+            "status_written": "已完成",     # 与 hub 判据同源；下游可据此确认表已置位
         }
 
     # ---- 本地失败诊断（failures.jsonl 索引）----
+    async def _hub_manual_step7_fallback(self) -> bool:
+        """步骤7 收口前先问 hub 真相：门户全完成 ⇒ 认定「运营手动完成」并返回 True。
+    
+        KB-137（2026-10-16 现场 79301358）：单步/异常路径会绕过前置「先问 hub 真相」判定，
+        于是"门户其实早已全完成（运营手工做完）"的票被判失败留在表里。补同一判据
+        （唯一入口 `_hub_truth` + `_hub_verdict_of`），与前置检查同源同文；探针不可用 ⇒ False。
+        """
+        try:
+            hub = await self._hub_truth()
+            verdict = self._hub_verdict_of(hub)
+        except Exception as exc:                     # noqa: BLE001（探针失败 ⇒ 沿用原判定）
+            self._log(f"  ⚠️ 步骤7 收口前的 hub 探针不可用（沿用原判定）: {exc}")
+            return False
+        if verdict.get("operationally_complete"):
+            self._hub_manual_complete(verdict)
+            return True
+        return False
+
     def _current_log_file(self) -> str:
         """本次运行日志路径：优先 poll 脚本注入的 FULFILLMENT_LOG_FILE，兜底按店铺名推导。"""
         env_path = os.environ.get("FULFILLMENT_LOG_FILE", "").strip()
@@ -11019,6 +11050,20 @@ class Orchestrator:
         except Exception:
             return False
 
+    async def _declara_progress(self) -> tuple[int, int]:
+        """返回 (已勾选 checkbox, 总数) —— 区分「残留文案」与「声明确实没做完」。
+
+        KB-136（2026-10-16 现场 79301358）：4 个箱子只声明了 2 个 ⇒ 「Descarga todas」永远不会
+        出现，而旧逻辑把点击前就存在的「Declara al menos」一律当**残留** ⇒ 干等 30s 后以
+        "平台侧异常"收口（冤枉平台、运营也拿不到可执行信息）。读不到 ⇒ (-1,-1)，不改变原判定。
+        """
+        try:
+            raw = await self._generar_diag()
+            d = json.loads(raw) if raw else {}
+            return int(d.get("checkbox_checked") or 0), int(d.get("checkbox_total") or 0)
+        except Exception:                       # noqa: BLE001（读不到 ⇒ 沿用原判定）
+            return -1, -1
+
     async def _generar_diag(self) -> str:
         """KB-128：采集 Generar/Descarga 按钮态 + checkbox 勾选态 + Declara 提示 + URL。
 
@@ -11233,6 +11278,33 @@ class Orchestrator:
                 # ② 提示在**点击 Generar 之前就已存在** = 残留（页面流转留下的旧校验文案），
                 #    不能当作"checkbox 未生效"的证据 ⇒ 不作为失败信号，继续等。
                 if self._declara_hint_at_click:
+                    # KB-136：先看勾选进度 —— 不是残留而是**声明确实没做完**时，干等必然超时。
+                    _declared, _total = await self._declara_progress()
+                    _andes_ok = await self._andes_checked()
+                    # ⚠️ checkbox_total 含我们**故意跳过**的 #1（bultos）⇒ "勾选数 < 总数"本身不是声明
+                    # 未完成的证据（正常态就是 2/4）。必须再看 Andes 勾选态（#2/#3 是否到位）。
+                    if _total > 0 and _declared < _total and not _andes_ok:
+                        if retried >= 1:
+                            raise StepError(
+                                7, "business",
+                                f"[declaration_incomplete] 箱型/箱数声明只完成 {_declared}/{_total}"
+                                f"（「Declara al menos」仍在）⇒ 下载按钮不会出现；需在该页面把剩下的箱子也声明完后重跑。"
+                                f"现场: {await self._generar_diag()}",
+                                recovery_attempted=["declara_progress_probe", "andes_checkbox_recheck"])
+                        retried += 1
+                        self._log(f"  ⚠️ 「Declara al menos」为**真实未完成**（已声明 {_declared}/{_total}）"
+                                  f"⇒ 重勾 Andes checkbox 并重新触发 Generar（第 {retried}/2 次）")
+                        try:
+                            shot = await self._screenshot_on_error(7)
+                            if shot:
+                                self._log(f"  📸 重试现场截图（供识图判读）: {shot}")
+                        except Exception:
+                            pass
+                        await self._check_andes_checkboxes()
+                        self._declara_hint_at_click = await self._has_declara_hint()
+                        await self.browser.click_with_fallback(7, "generate_btn", "Generar etiquetas", wait_after=5.0)
+                        waited = 0.0
+                        continue
                     if not stale_logged:
                         self._log("  ℹ️ 「Declara al menos」在点击 Generar **之前**就已存在"
                                   "（残留文案）⇒ 不作为失败信号，继续等待生成结果")
@@ -12277,7 +12349,16 @@ class Orchestrator:
                 elif step == 6:
                     await self.step6_labels(dry_run=dry_run)
                 elif step == 7:
-                    await self.step7_box_labels()
+                    try:
+                        await self.step7_box_labels()
+                    except StepError:
+                        # KB-137：收口前先问 hub 真相（门户可能早已完成，只是页面态残留）
+                        if await self._hub_manual_step7_fallback():
+                            return self._result("already_completed", None,
+                                                {"step": 7, "type": "hub_manual_complete",
+                                                 "message": self.HUB_MANUAL_NOTE},
+                                                step_summaries, dry_run)
+                        raise
                 elif step == 8:
                     await self.step8_cancel_appointment()
                 # ── 需求 2：步骤**结束**（成功）再写一次（节流；文案与开跑不同 ⇒ 必写） ──

package/engine/scripts/p2-report-run.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * P2 执行面回写器（本机 → 服务端）—— 用 runner token 把一次执行结果写回数据中心。
+ *
+ * 只做三件事（都不含业务判定）：
+ *   1) --create-card <title>   建服务端业务卡（可带 --preset）
+ *   2) --report                 写 run（POST /runs）+ 结算卡状态（PATCH /cards/:id）
+ *   3) --verify                 读回卡与 run，供自动核对
+ *
+ * 用法：
+ *   node scripts/p2-report-run.mjs --state /tmp/argent-dev-local.json --create-card "美客多日报（试点）" --preset argent-ml-daily
+ *   node scripts/p2-report-run.mjs --state ... --report --card-id <id> --preset argent-ml-daily --outcome succeeded --tokens 120 --summary "链路验证通过"
+ *   node scripts/p2-report-run.mjs --state ... --verify --card-id <id>
+ *
+ * 状态文件（600）由 `whyshu-svr/scripts/dev-local.mjs` 生成：{ serverUrl, runnerToken, adminToken, appId }
+ * ⛔ 不打印 token；⛔ 不写生产（state 文件只由本地 dev-local 生成）。
+ */
+import { readFileSync } from 'node:fs';
+
+const argv = process.argv.slice(2);
+const val = (flag, dflt = '') => {
+  const i = argv.indexOf(flag);
+  return i > -1 ? (argv[i + 1] ?? dflt) : dflt;
+};
+const has = (flag) => argv.includes(flag);
+
+const statePath = val('--state', '/tmp/argent-dev-local.json');
+let state;
+try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch (e) {
+  console.error(`❌ 读不到状态文件 ${statePath}：${e.message}\n   先在 whyshu-svr 起本地服务：node scripts/dev-local.mjs`);
+  process.exit(2);
+}
+const { serverUrl, runnerToken, appId } = state;
+if (!serverUrl || !runnerToken || !appId) { console.error('❌ 状态文件缺 serverUrl/runnerToken/appId'); process.exit(2); }
+
+const api = async (path, { method = 'GET', body } = {}) => {
+  const res = await fetch(`${serverUrl}/api/argent/v1${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${runnerToken}`,
+      'content-type': 'application/json',
+      ...(has('--idem-key') ? { 'idempotency-key': val('--idem-key') } : {}),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = JSON.parse(text); } catch { data = text; }
+  if (!res.ok) {
+    throw new Error(`${method} ${path} → ${res.status} ${data?.error?.code || ''} ${data?.error?.message || ''}`.trim());
+  }
+  return data;
+};
+
+const main = async () => {
+  const tenantPath = `/tenants/${appId}`;
+
+  if (has('--create-card')) {
+    const title = val('--create-card');
+    const preset = val('--preset');
+    const d = await api(`${tenantPath}/cards`, { method: 'POST', body: { title, description: val('--description'), assigneePreset: preset } });
+    console.log(JSON.stringify({ ok: true, cardId: d.data.card._id, title, appId }));
+    return;
+  }
+
+  if (has('--report')) {
+    const cardId = val('--card-id');
+    const preset = val('--preset', 'argent-ml-daily');
+    const outcome = val('--outcome', 'succeeded');
+    const tokens = Number(val('--tokens', '0')) || 0;
+    const summary = val('--summary', '');
+    const run = await api(`${tenantPath}/runs`, { method: 'POST', body: { cardId: cardId || null, preset } });
+    const runId = run.data.run._id;
+    const settled = await api(`${tenantPath}/runs/${runId}/settle`, {
+      method: 'PATCH',
+      body: { outcome, tokens, cost: Number(val('--cost', '0')) || 0, summary },
+    });
+    console.log(JSON.stringify({
+      ok: true,
+      runId,
+      outcome: settled.data.run.outcome,
+      cardStatus: settled.data.card?.status ?? null,
+      cardSkipped: settled.data.cardSkipped ?? false,
+    }));
+    return;
+  }
+
+  if (has('--verify')) {
+    const cardId = val('--card-id');
+    const cards = await api(`${tenantPath}/cards?limit=50`);
+    const runs = await api(`${tenantPath}/runs?limit=50`);
+    const card = cardId ? cards.data.items.find((c) => String(c._id) === String(cardId)) : null;
+    const relatedRuns = cardId ? runs.data.items.filter((r) => String(r.cardId) === String(cardId)) : [];
+    console.log(JSON.stringify({ ok: true, card, runs: relatedRuns }, null, 2));
+    return;
+  }
+
+  console.error('用法：--create-card <title> | --report ... | --verify ...（详见脚本头注释）');
+  process.exit(2);
+};
+
+main().catch((e) => { console.error(`❌ ${e.message}`); process.exit(1); });

package/engine/scripts/patches/dsh-session--append-message-shape.patch

@@ -1,15 +1,40 @@
+# 加固（B 类 · 防毒化）：Session.append 边界补 message 形状校验 —— **dsh 0.2.1-rc.2 移植版**
+#
+# 背景（2026-09-18 会话毒化事故）：append() 原本只做 validateSessionEventData + surface 校验，
+#   **漏了** assertMessageEventShape ⇒ 一个非法 message 事件（如某个 tool 的 render 返回裸字符串）
+#   能写进日志，直到**下次从磁盘加载**才炸（"message must contain one tool-result block"），
+#   此时会话根本打不开，surface replace 也救不回来（校验针对事件本身，不是 surface 视图）。
+#
+# 版本沿革 / 为什么这次要改：
+#   · 2026-09-18 首版：面向 0.1.7/0.2.0 —— 插入点是 `validateSessionEventData(...)` 与
+#     `this.surfaceManager.validateNext(event)` 之间（当时 append() 内联了这个调用）。
+#   · 2026-10-18 移植到 **0.2.1-rc.2**：上游把 `surfaceManager.validateNext(event)` 移进了
+#     `commit()`，append() 变成 `validateSessionEventData(...) → this.commit(event, entry)`；
+#     旧 hunk 的上下文消失 ⇒ 补丁应用失败、加固门禁变红（实测）。故插入点改为
+#     **`validateSessionEventData(...)` 之后、`this.commit(event, entry)` 之前**。
+#   · ⚠️ 上游 0.2.1 **并未**原生补上该校验：`assertMessageEventShape` 只在 `adoptSessionEvent()`
+#     里调用（那是另一条"接收获批事件"的路径），append/commit 仍未调用 ⇒ 加固仍然必要。
+#   · 0.1.7/0.2.0 树的旧版补丁见 git 历史（本文件在提交 987de39 之前的版本）；回滚到旧树时
+#     物理备份树里**已含**该补丁的修改，无需重打；`--patches-only` 在旧树上会对此文件报 warn，
+#     属预期（按 `dsh-upgrade.mjs --rollback` 流程走，别拿"先别重启"卡自己）。
+#
+# 退役条件：上游把 assertMessageEventShape 接进 append/commit 路径后，patch --forward 会因上下文不符
+#   而 warn ⇒ 届时删除本文件并同步删掉 scripts/patches/verify-hardening.mjs 的补丁 B 部分。
 --- /opt/homebrew/lib/node_modules/@deepseek-ai/dsh-session/lib/index.js.orig
 +++ /opt/homebrew/lib/node_modules/@deepseek-ai/dsh-session/lib/index.js
-@@ -1187,6 +1187,12 @@
+@@ -1533,6 +1533,15 @@
  			...surfaceMetadataSnapshot
  		});
  		validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
-+		/* Hardening (2026-09-18, argent-dsh hotfix): the append boundary must reject a
-+		   message event that could never be replayed. Otherwise a malformed tool/result
-+		   (e.g. a render that returned a bare string) lands in the log and only fails
-+		   when the session is next LOADED from disk — by then the session cannot even be
-+		   opened, and a surface replace cannot repair it. Fail at the writer instead. */
++		/* Hardening (2026-09-18, argent-dsh hotfix；2026-10-18 移植到 dsh 0.2.1):
++		   the append boundary must reject a message event that could never be replayed.
++		   Otherwise a malformed tool/result (e.g. a render that returned a bare string)
++		   lands in the log and only fails when the session is next LOADED from disk — by
++		   then the session cannot even be opened, and a surface replace cannot repair it.
++		   Fail at the writer instead.
++		   0.2.1 结构变化：append() 不再直接调 surfaceManager.validateNext（移进 commit()），
++		   故插入点改为 validateSessionEventData 之后、commit 之前；校验函数/语义未变。 */
 +		assertMessageEventShape(event, `session event "${type}" at seq ${event.seq}`);
- 		this.surfaceManager.validateNext(event);
- 		if (entry !== void 0) entry.appending = true;
- 		try {
+ 		this.commit(event, entry);
+ 		return event;
+ 	}

package/engine/scripts/patches/dsh-session-format-v3-to-v4--turn-outside-replace.patch

@@ -1,20 +1,44 @@
-# requires-dsh: >=0.1.7   （v3→v4 迁移器 0.1.7 新增；修复"turn 外替换型 tool/result"过严拒绝）
+# 放宽 v4 加载校验：允许"turn 结束后的**替换型** tool/result"（合法历史，不是损坏）
+#
+# 背景（2026-10-17，本机 0.1.7-rc.2 → 0.2.0-rc.2 重启后）：
+#   用户主会话 06732069（v4、95032 事件）在 0.2.0 上打不开：
+#     Failed to load history: stored session "…06732069…" is corrupt:
+#     SessionFormatError: tool/result is outside an open turn
+#   真因：v4 校验器（本包 `tool()`）对 `surfaceOp !== "append"` 的 tool/result 一律 `requireTurn`；
+#   而 v3 时代就允许"turn 结束后重写早先 turn 的工具结果"（编辑/重放/surface 自替换）。
+#   本机实测只有 **1 处**：seq 30732，surfaceOp.replace(startSeq=30702,endSeq=30702)，
+#   data.turn=541 而当时 nextTurn=545 ⇒ 指向**已关闭的历史 turn**，属合法历史。
+#
+# 口径：turn 外时只要求 data.turn 是**已关闭的历史 turn**（安全整数且 < nextTurn）；
+#       其余情况仍抛原错 ⇒ 防真损坏，放行合法历史。
+#
+# 来源：等价于已退役 A 类补丁 `dsh-session-format-v3-to-v4--turn-outside-replace.patch`
+#   （2026-09-29 为 0.1.7 修同一坑；A 类于 2026-10-16 退役）。0.2.0 是**新旁路树**，
+#   退役补丁不会随树迁移 ⇒ 该缺陷在新树上复现；本文件是 0.2.0 树的移植版，`--patches-only` 会自动重打。
+#
+# 为什么不写 `# requires-dsh:` 版本门：① 本补丁的上下文在 0.1.7 与 0.2.0 上一致，两版都适用；
+#   ② `applyHotfixPatches()` 里的版本门目前**静默失效**（正则被行尾注释打断）且依赖未定义的
+#   `cmpVerText` —— 写一行能被识别的门反而会 ReferenceError 崩掉升级脚本（待单独修）。
+# 退役条件：上游把这条规则放宽（或提供配置）后，本补丁 `patch --forward` 会因上下文不符而 warn ⇒ 再删。
 --- /opt/homebrew/lib/node_modules/@deepseek-ai/dsh-session-format-v3-to-v4/lib/index.js.orig
 +++ /opt/homebrew/lib/node_modules/@deepseek-ai/dsh-session-format-v3-to-v4/lib/index.js
-@@ -617,7 +617,15 @@
+@@ -617,6 +617,19 @@
  	}
  	tool(event, data) {
  		if (event.type === "tool/result" && event["surfaceOp"] !== "append") {
--			this.requireTurn(event.type);
-+			/* Hardening (2026-09-29, argent-dsh hotfix for 0.1.7): v3 允许"turn 结束后的替换型
++			/* Argent hotfix（0.2.0-rc.2 移植版，2026-10-17）：v3/v4 允许"turn 结束后的替换型
 +			   tool/result"（编辑/重放场景：重写早先 turn 的工具结果，如 surface 自替换）。
-+			   原 requireTurn 过严 → 整个 session 迁移失败（'tool/result is outside an
-+			   open turn'，实测 06732069/34c3e088 等）。现在：turn 外时校验 data.turn 指向
-+			   已关闭的历史 turn（防真损坏，放行合法历史）。 */
++			   原 `requireTurn` 过严 ⇒ 整个 session **加载**失败（'tool/result is outside an
++			   open turn'；本机 06732069 实测 1 处：seq 30732，surfaceOp.replace 指向 seq 30702，
++			   data.turn=541 而当时 nextTurn=545）。放宽口径：turn 外时 data.turn 必须是
++			   **已关闭的历史 turn**（安全整数且 < nextTurn）—— 防真损坏，放行合法历史。
++			   等价于已退役 A 类补丁 dsh-session-format-v3-to-v4--turn-outside-replace
++			   （0.1.7 上曾修同一坑）；本次因 0.2.0 树是**新树**（补丁未随树迁移）而复现。 */
 +			if (this.turn === null) {
 +				const t = data["turn"];
 +				if (!Number.isSafeInteger(t) || t >= this.nextTurn) throw new SessionFormatError(`${event.type} is outside an open turn`);
++				return;
 +			}
+ 			this.requireTurn(event.type);
  			return;
  		}
- 		this.requireStep(event, data);

package/engine/scripts/patches/retire-check.sh

@@ -10,10 +10,6 @@ declare -A PKG=(
   [dsh-session--append-message-shape]="@deepseek-ai/dsh-session"
   [dsh-session--tool-result-block-017]="@deepseek-ai/dsh-session"
   [dsh-tools--render-return-shape]="@deepseek-ai/dsh-tools"
-  [dsh-session-format-v0-to-v1--permission-preset-origin]="@deepseek-ai/dsh-session-format-v0-to-v1"
-  [dsh-session-format-v3-to-v4--turn-outside-replace]="@deepseek-ai/dsh-session-format-v3-to-v4"
-  [dsh-session-persistence-jsonl--worker-bundled-migrators]="@deepseek-ai/dsh-session-persistence-jsonl"
-  [dsh-llm-deepseek--transport-diagnostics]="@deepseek-ai/dsh-llm-deepseek"
 )
 echo "上游版本 $VER ｜ 临时目录 $TMP"
 cd "$TMP"

package/engine/scripts/patches/verify-hardening.mjs

@@ -80,7 +80,10 @@ console.log('\n【补丁 B】dsh-session：append 边界补上 message 形状校
 if (!existsSync(SESSION)) { ok(false, `dsh-session 存在（${SESSION}）`) }
 else {
   const src = readFileSync(SESSION, 'utf8')
-  ok(/Hardening \(2026-09-18, argent-dsh hotfix\)/.test(src), '打补丁标记存在')
+  // 2026-10-18：标记判据放宽为"前缀匹配"——补丁按宿主版本移植时注释尾部会变
+  // （0.2.1 版 = `Hardening (2026-09-18, argent-dsh hotfix；2026-10-18 移植到 dsh 0.2.1)`），
+  // 但"这是本仓库的补丁、不是上游原生行为"这件事不变。⛔ 不要退回成要求精确闭合括号。
+  ok(/Hardening \(2026-09-18, argent-dsh hotfix/.test(src), '打补丁标记存在')
   const appendBody = src.slice(src.indexOf('\tappend(type, data, ...opts) {'), src.indexOf('headerFold;', src.indexOf('\tappend(type, data, ...opts) {')))
   ok(/validateSessionEventData\(event, `session event "\$\{type\}" at seq \$\{event\.seq\}`\);\s*\n\s*\/\* Hardening[\s\S]*?\*\/\s*\n\s*assertMessageEventShape\(event, `session event "\$\{type\}" at seq \$\{event\.seq\}`\);/.test(appendBody),
     'append() 在落盘前调用 assertMessageEventShape()')