@whyshu/argent-engine 0.7.3 → 0.7.5

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/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

@@ -0,0 +1,44 @@
+# 放宽 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,6 +617,19 @@
+ 	}
+ 	tool(event, data) {
+ 		if (event.type === "tool/result" && event["surfaceOp"] !== "append") {
++			/* 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 实测 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;
+ 		}

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()')

package/engine/scripts/patches/verify-turn-outside-replace.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * verify-turn-outside-replace —— 补丁 `dsh-session-format-v3-to-v4--turn-outside-replace` 的自检。
+ *
+ * 这个补丁修的是**加载期**问题（不是写路径），它最危险的失效方式是"升级换了新树 ⇒ 补丁没跟着走 ⇒
+ * 某个旧会话突然打不开，而且没有运行期报错提示"（2026-10-17 本机就这么复现了一次）。故门禁要能
+ * 在**升级后立刻**判出"补丁在不在"。
+ *
+ * 判据两层：
+ *   ① 结构（始终跑）：目标模块里**确有**放宽逻辑（`Number.isSafeInteger(t)` + `t >= this.nextTurn` + 标记注释）；
+ *      且**没有**退回成裸 `this.requireTurn(event.type)`。
+ *   ② 行为（可选）：给了 `DSH_TURN_OUTSIDE_SESSION=<一个 v4 日志路径>` 时，用真实加载校验
+ *      （scripts/session-load-check.mjs，`validation:'current'`）证明它现在能过。
+ *      不给就**跳过并明说**（⛔ 不假装验过；本机已知样本：session-06732069 的 seq 30732）。
+ *
+ * 用法：node scripts/patches/verify-turn-outside-replace.mjs
+ *       DSH_TURN_OUTSIDE_SESSION=~/.dsh/sessions/…/session.v4.jsonl.zstd node …（会展开 ~）
+ * 退出码：0 通过（或"结构过 + 行为跳过"）/ 1 结构缺失 / 2 证据不足（scope 探不到）
+ */
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+
+let scope
+try { scope = requireDshScope({ what: '补丁自检（verify-turn-outside-replace）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(2) }
+
+const target = join(scope, 'dsh-session-format-v3-to-v4', 'lib', 'index.js')
+if (!existsSync(target)) {
+  console.error(`  ❌ 目标模块不存在：${target}（上游可能改名/改结构）`)
+  process.exit(1)
+}
+const src = readFileSync(target, 'utf8')
+
+let pass = 0
+let fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+ok(/Argent hotfix（0\.2\.0-rc\.2 移植版/.test(src), '放宽逻辑的标记注释在位（说明"这是本仓库的补丁，不是上游原生行为"）')
+ok(/if \(this\.turn === null\) \{\s*const t = data\["turn"\];\s*if \(!Number\.isSafeInteger\(t\) \|\| t >= this\.nextTurn\) throw new SessionFormatError/.test(src),
+  '放宽口径在位：turn 外只要求 data.turn 是已关闭的历史 turn（安全整数且 < nextTurn）')
+// 反向：不能退回成"一律要求打开 turn"（那样旧会话又会打不开）
+ok(!/if \(event\.type === "tool\/result" && event\["surfaceOp"\] !== "append"\) \{\s*this\.requireTurn\(event\.type\);\s*return;/.test(src),
+  '没有退回成裸 requireTurn（退回去 = 旧会话重新打不开）')
+
+// ② 行为（可选，不假装）
+const fixture = (process.env.DSH_TURN_OUTSIDE_SESSION || '').replace(/^~(?=$|\/)/, homedir())
+if (!fixture) {
+  console.log('  ⏭  行为校验跳过：未给 DSH_TURN_OUTSIDE_SESSION（结构判据已覆盖"补丁在不在"）')
+} else if (!existsSync(fixture)) {
+  console.log(`  ⏭  行为校验跳过：DSH_TURN_OUTSIDE_SESSION 指向的文件不存在（${fixture}）`)
+} else {
+  const r = spawnSync(process.execPath, ['--max-old-space-size=8192', join(import.meta.dirname, '..', 'session-load-check.mjs'), fixture], {
+    encoding: 'utf8', env: { ...process.env, DSH_SCOPE: scope },
+  })
+  const out = `${r.stdout || ''}${r.stderr || ''}`
+  ok(r.status === 0, `行为校验：该会话能过真实加载校验（${fixture}）${r.status === 0 ? '' : `\n     ${out.trim().split('\n').slice(-4).join('\n     ')}`}`)
+}
+
+console.log(`\n${fail === 0 ? '✅' : '❌'} verify-turn-outside-replace：通过 ${pass} / 失败 ${fail}`)
+process.exit(fail === 0 ? 0 : 1)

package/engine/scripts/poll-fulfillment.sh

@@ -102,7 +102,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/profile-doctor.mjs

@@ -518,7 +518,7 @@ function checkPackIntegrity() {
     const msg = '未找到 install.json（可能未按能力清单安装）'
     line('WARN', msg)
     record('warn', 'pkg-install-json-missing', msg,
-      `按能力安装：node install-argent.mjs --api-key <账号 API Key>（或核对 --dsh-home / ARGENT_INSTALL_JSON=${INSTALL_JSON}）`)
+      `按能力安装：由 @whyshu/argent 启动器安装（或核对 --dsh-home / ARGENT_INSTALL_JSON=${INSTALL_JSON}）`)
     return
   }
   const doc = readInstallJson(INSTALL_JSON)

package/engine/scripts/python-runtime.sh

@@ -23,9 +23,11 @@ case "$(uname -s 2>/dev/null || echo unknown)" in
 esac
 # P0-1（2026-10-08）：体检项 4 → 5（补 selenium）。理由：官方唯一推荐的驱动档位
 # （ZINIAO_MODE=selenium）此前在 venv 里**没装** ⇒ 选型开关静默撒谎、该档位从未运行过一次。
-# ⚠️ 本清单必须与 install-argent.mjs 的 pythonRuntimePlan().pkgs 和
+# ⚠️ 本清单必须与 scripts/lib/python-runtime.mjs 的 venvUsable(pkgs=…) 和
 #    scripts/lib/python-runtime.mjs 的 venvUsable(pkgs=…) 保持一致（缺一就会"体检红但 ensure 空转"）。
 PKGS=(openpyxl yaml PIL playwright selenium)
+# pip 安装名（import 名 ≠ 包名：yaml→pyyaml、PIL→pillow）
+PIP_PKGS=(openpyxl pyyaml pillow playwright selenium)
 # 交付纪律：本清单变更必须与"客户机 venv 补装 selenium（bash scripts/python-runtime.sh ensure）"
 # 同批落地，否则客户机体检会先变红（4/5）。
 
@@ -53,10 +55,20 @@ cmd_check() {
 }
 
 cmd_ensure() {
-  if [ ! -f "$REPO/install-argent.mjs" ]; then
-    echo "  ❌ 找不到 install-argent.mjs（本脚本需在 argent-dsh 仓库内运行）" >&2; return 2
+  # 旧安装器退役（2026-10-18）：直接创建持久 venv 并 pip 安装运行时依赖
+  local venv_dir; venv_dir="$(dirname "$VENV_BIN")"
+  local pybin="${PYTHON_BIN:-$(command -v python3 2>/dev/null || true)}"
+  if [ -z "$pybin" ] || [ ! -x "$pybin" ]; then
+    echo "  ❌ 找不到 python3；请先安装 Python 3.10+" >&2; return 2
   fi
-  node "$REPO/install-argent.mjs" --venv-only --dsh-home "${DSH_HOME:-$HOME/.dsh}" || return $?
+  if [ ! -x "$VENV_PY" ]; then
+    echo "  → 创建 venv：$venv_dir"
+    "$pybin" -m venv "$venv_dir" || return 1
+  fi
+  echo "  → 安装运行时依赖：${PIP_PKGS[*]}"
+  "$VENV_PY" -m pip install --upgrade pip >/dev/null 2>&1 || true
+  "$VENV_PY" -m pip install "${PIP_PKGS[@]}" || return $?
+  echo "  ✅ venv 就绪：$VENV_PY"
 }
 
 cmd_path() {

package/engine/scripts/release-argent.sh

@@ -69,7 +69,8 @@ REMOTE="${ARGENT_RELEASE_REMOTE:-$(git -C "$REPO_DIR" remote | head -1)}"
 # 2026-10-09：补 install.sh —— 官网 macOS/Linux 一行命令 `curl .../dl/install.sh | bash` 的入口
 # （旧的 `curl .../dl/install-argent.mjs | node` 因模块级相对 import 必然 ERR_MODULE_NOT_FOUND，
 #  已被 install.sh 取代）。`install-dsh.sh` 留在这里只为**存量老命令**仍能取到，是**遗留**件。
-CORE_FILES=("install-argent.mjs" "install.sh" "install-dsh.sh" "install.ps1" "argent-setup.md")
+# 旧一句话安装器已退役（2026-10-18）：只保留安装说明页；启动器由 @whyshu/argent 承担
+CORE_FILES=("argent-setup.md")
 # 目录级分发（--full 时启用；服务器对应目录有独立静态资源，非同名覆盖不删旧）
 DIR_FILES=("skills" "plugins")
 
@@ -184,7 +185,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 ⇒ 浏览器流程会失败（修：运行 @whyshu/argent 启动器自检子命令按提示补装；或手动 pip 安装）" >&2
     printf '%s' "$c"; return 0
   done
   return 1
@@ -343,7 +344,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 ⇒ 浏览器流程会失败（修：运行 @whyshu/argent 启动器自检子命令按提示补装；或手动 pip 安装）" >&2
     printf '%s' "$c"; return 0
   done
   return 1
@@ -537,7 +538,7 @@ if [[ $FULL -eq 1 ]]; then
 else
   echo "  3. （未指定 --full：skills/ plugins/ 目录不同步——服务器有独立静态资源）"
 fi
-echo "  4. 验证：本地/服务器 md5 + curl -sI ${DL_URL}/install-argent.mjs"
+echo "  4. 验证：本地/服务器 md5 + curl -sI ${DL_URL}/argent-setup.md"
 
 if [[ $DRY_RUN -eq 1 ]]; then
   echo
@@ -594,11 +595,11 @@ for f in "${CORE_FILES[@]}"; do
     VERIFY_OK=0
   fi
 done
-http_code="$(curl -sI -o /dev/null -w '%{http_code}' "${DL_URL}/install-argent.mjs")"
+http_code="$(curl -sI -o /dev/null -w '%{http_code}' "${DL_URL}/argent-setup.md")"
 if [[ "$http_code" == "200" ]]; then
-  echo "  ✓ ${DL_URL}/install-argent.mjs HTTP ${http_code}"
+  echo "  ✓ ${DL_URL}/argent-setup.md HTTP ${http_code}"
 else
-  echo "  ✗ ${DL_URL}/install-argent.mjs HTTP ${http_code}（期望 200）"
+  echo "  ✗ ${DL_URL}/argent-setup.md HTTP ${http_code}（期望 200）"
   VERIFY_OK=0
 fi