@whyshu/argent-engine 0.7.2 → 0.7.4

package/engine/scripts/flow-requirements.json

@@ -148,7 +148,7 @@
       },
       "minPlan": "enterprise",
       "pack": {
-        "version": "1.2.172",
+        "version": "1.2.176",
         "scripts": [
           "scripts/wenyao-invoice-writeback.mjs",
           "scripts/invoice_lip_runner.py",
@@ -251,7 +251,7 @@
       ],
       "minPlan": "enterprise",
       "pack": {
-        "version": "1.3.177",
+        "version": "1.3.181",
         "scripts": [
           "scripts/poll-fulfillment.sh",
           "scripts/orchestrator.py",
@@ -331,7 +331,7 @@
       "minPlan": "pro",
       "_minPlanNote": "**2026-10-09（变现分层落地）**：`enterprise` → **`pro`**。判据 = 用户已确认的产品模型「分界线 = **价值更高 / 风险更高 ⇒ 企业版**」：日报是**只读**能力（官方 API 只读查询 + 生成推送，⛔ 不写客户任何系统、⛔ 不动浏览器），与 `full`（箱唛/写操作）、`invoice`（发票/门户写操作）不同档 ⇒ 归 **Pro**。⛔ 只改**档位下限**，⛔ 不改流程行为、⛔ 不改价格口径；`daily-report` 的能力包版本随引擎前进（见 pack.version）。已装机器**不因本改动被卸载/停用**（缩权只影响后续下发，见 entitlements.plans._why 与 docs 策划案 §4.4）。",
       "pack": {
-        "version": "1.1.170",
+        "version": "1.1.174",
         "scripts": [
           "scripts/daily-report.mjs",
           "scripts/daily-report.sh",
@@ -433,7 +433,7 @@
             }
           ]
         },
-        "version": "0.1.78",
+        "version": "0.1.82",
         "_note": [
           "能力包版本（语义化）：改了该能力的流程/提示词/脚本/技能 ⇒ 必须提版本并重新打包 ｜**0.1.40（2026-10-04，角色退役·墓碑）**：包内容变更（`presets/argent-hr-office/agent.cordis.yml` 的 persona 改成退役告知、`preset.yml` 的 name/description 标注「已退役」）—— 角色 `hr-office` 已于 2026-10-04 退役（方案 §3.3.1：gateway.json 条目与 install-dsh.sh 安装期入口已撤），**本能力包保留**（装机内容不变、仍可安装；入口 preset 作为 web 老会话的墓碑保留）⇒ 版本随内容前进。｜**0.1.41（2026-10-09，版本随内容前进）**：`0.1.40` **发布之后其字节被原地覆盖过一次**（服务端清单 `sha256` `15cf4f43…` → `058ccead…` 而 `version` 原地不动，见 whyshu-svr `docs/ops/deploy-fe02231-packs-align.md`）⇒ 同一个 URL 下的内容变过 ⇒ \"内容变 ⇒ 版本变\"这条不变式被破坏，客户机无法靠版本号判断自己拿到的是哪一份。本次**只提版本、包内容一字未改**（重盖章后内容摘要与 0.1.40 时逐字相同）⇒ `hr-0.1.41.tgz` 是该内容**首次以某个版本号**对外发布。⛔ 未改共用引擎、未新增运行期文件，故 `pack.engine` 清单不变。｜**0.1.42（2026-10-09，配置地基：配置目录 + 通用读取器 —— hr 包内容随之改变）**：本能力**无 flow**，按 `pack.engine` 的分发规矩**不背共用引擎**（`files` 仍只有 `presets/argent-hr-office/**` 三件，`integrity` 逐字节未变）。但**每个包的 tgz 里都带一份注册表投影**（`scripts/flow-requirements.json` 的引擎级段），而本批改了它的 `pack.engine`（新增 `core/lib/config-catalog.mjs` 与 5 个 `configs/*.json`）⇒ **hr 的包字节变了** ⇒ 按「内容变 ⇒ 版本必变（含无 flow 的包）」这条不变式**必须一起提版本**，否则会出现\"同一个版本号 0.1.41 对应两份不同字节\"（这正是 `release-argent.sh --check-dl` 的能力包档当场抓到的形态：`✗ hr: 版本相同（0.1.41）但内容摘要不同 —— 仓库 ad3599c5 vs 线上 09e1fef9`；提版后该条转为 ⚠「发布在途」，不再判红）。⛔ 本轮 hr 的**能力内容一字未改**。｜**0.1.44（2026-10-09，预约失败判定链 + 口径统一）**：共用引擎 `scripts/flow_failure.py` 变更（新增 `canonical_reason()` 与 `--case` —— 打印某 case 的**规范失败原因**：优先读台账 `failed.reason`，老台账回落到 `error` 去身份前缀；给角色/运维一个**逐字照抄**的取数口，杜绝\"表备注写 A、账本写 B\"）⇒ 所有能力包的注册表投影同批变化。本能力自身：⛔ 本能力内容一字未改；但 `flow_failure.py` 在 `pack.engine` 内，且包内 `scripts/flow-requirements.json` 投影**含 `failureClasses`**（本次新增的两条 needsHuman 判据就在其中）⇒ **包字节变了**，按「内容变 ⇒ 版本必变（含无 flow 的包）」这条不变式必须一起提版本。（⚠️ **盖章说明**：本版内容在同一工作树里经过**多轮收口**（先落实现，再按 vertical-lint 的引擎业务词约束改注册表文案、再收口文案）⇒ 以**最终内容**盖章；版本号从未发布过，不存在\"内容变了版本没动\"的对外窗口。）｜**0.1.45（2026-10-09，三处生产实测收口：票不许静默消失 · 失败必写原因+动作 · 发票流程 Rule R）**：共用引擎变更 ⇒ 四个能力包一起提版本并重盖章。① `scripts/flow_triage.py`：判定改为**有效末条事件**（`INFO_EVENTS = phase/wake/policy_apply/policy_new` 回退到最近一条状态性事件；`failed_ack` = 有意不动且**不参与回退**）、`blocked` 从「静默 pass」改为可见的 `needs_human`，并加**循环后对账兜底**（任何未归桶的 case ⇒ `needs_human`，kind=unclassified）——修的是客户机生产实测 P0（某发票票）：其尾部是 `blocked → phase` ⇒ 分诊摘要全 0、运营勾了放行也不派发、且**不在「需人工」里**（静默卡死）。② `scripts/flow_failure.py`：新增运营文案**唯一来源** `ops_message()`（`结论：<业务类|系统类|我方缺陷类>｜<原因>｜动作：…`，≤300 字）与 `release_hint()`（放行位/提示的**唯一实现**：变体与**顶层** pick 都认；`orchestrator._ops_action_hint` 改为委托它）；③ **新增** `scripts/invoice_fail_closeout.py`（属**发票能力专属脚本** `capabilities.invoice.pack.scripts`，⛔ 不进共用引擎 —— 它只写发票那一列）：失败/成功收口 —— 把**同一串**写进表「发票错误信息」与台账（`detail` 逐字相同、`error` 放规范原因），取不到原因 ⇒ **exit 2 拒绝执行**，代码级异常归「我方缺陷类」且**不回原文**，成功 ⇒ `--clear-error` 清空；④ `scripts/flow_return_to_ops.py`：缺口回填文案改用同一来源（表字段 == 台账 `detail`）；④b `scripts/flow_config.py`：归一化的 `guards` 增**标量透传**（`writer`=写手路径、`errorField`=失败原因列 —— 不透出就只能各自把路径/列名写死，那正是「判据第二份」与业务词泄漏进引擎的来源）；⑤ 业务线声明（`verticals/<id>/flows.json`）：两个发票流程新增 `pick.release` / `pick.releaseReDispatch`（放行位 = **各自的门控列**「发票就绪」；上限 3 / 冷却 30）与 `guards.errorField`。本能力自身：⛔ 内容一字未改（无 flow ⇒ 不背共用引擎）；但包内注册表投影含 `failureClasses`/`pack.engine` ⇒ 包字节变了，按「内容变 ⇒ 版本必变（含无 flow 的包）」一起提版本。｜**0.1.46（2026-10-09，配置「生效来源」可见化 + 冲突告警，批 1）**：本能力无 flow ⇒ **不背共用引擎**（`files` 仍只有 3 件 preset，逐字节未变）；但包内注册表投影含 `pack.engine` ⇒ 包字节变了，按「内容变 ⇒ 版本必变（含无 flow 的包）」一起提版本（同 `0.1.42` 先例）。本能力内容一字未改。共用引擎 `core/lib/config-catalog.mjs` 新增**纯函数** `resolveEffective()`（按规范链算「谁赢了 / 谁被压住」）、密钥脱敏 `redactSecret()` 与读取器 `effectiveOf()/levelsOf()`，并新增只读 CLI `scripts/config-explain.mjs`（`--key/--all/--list/--json`）⇒ 能力包内容变化，按纪律提版本并重盖章。⛔ **零行为变化**：读取器的取值路径（`resolveOne`）与任何 `todayChain` 一个字节都没改，只是「如实展示」；同批回归 `scripts/tests/config-effective.test.mjs`（63 断言）+ 端点 / 页面两条既有回归扩测。｜**0.1.47（2026-10-09，同批收口：脱敏闸幂等）**：只读 CLI `scripts/config-explain.mjs` 的\"再脱敏\"兜底闸原先**无条件**执行 ⇒ `❰已设置(长度N)❱` 里的 N 变成**占位串自己的长度**（恒 11，实测），而用户正是拿它比对\"密钥换没换\" ⇒ 已改为**幂等**（含被压住的那级）并补回归；引擎面同一份 CLI 变了 ⇒ 包内容变化，按纪律再提版本并重盖章。本能力自身内容一字未改。｜**0.1.49（2026-10-10，A 批：按智能体安装清单 —— 客户从「智能体库」选一个装，只装它的东西）**：① **`pack.engine` 新增两项**：`agents/catalog.json`（L0 货架声明：agent → capability + flows 子集 + 角色 + 插件/技能/集成/凭据槽）与 `scripts/argent-agents.mjs`（声明解析/校验/清单构造；安装器与门禁**共用一份**判据）⇒ 引擎清单与每包内的注册表投影都变了（**无 flow 的 hr 也变**，按「内容变 ⇒ 版本必变（含无 flow 的包）」这条不变式一起提版本）；② **共用引擎行为变更**（`install-argent.mjs` / `scripts/lib/preset-install.mjs` / `scripts/argent-upgrade.mjs`）：新增 `--agent <id>[,<id>…]` / `--list-agents` / `--internal-roles` / `--capability remove <id>`（写前备份 + 审计）；preset **行落盘集合**改为「按清单收窄」（`--agent` ⇒ 恒装 + 本智能体角色 + 已装集；默认 ⇒ 客户可见集 + 已装集；**内部角色默认不落**）；升级器按 `<dshHome>/argent/agents.json` **重新施加**同一集合（否则一次升级就把收窄还原）；**未给 `--agent` 时 CLI 契约与计划清单输出与改动前逐字一致**（差分回归钉住）；③ 本能力自身：**新增活的 HR 角色** `presets/argent-hr/`（招聘支持 / 员工关系 / PPT 与文档产出 / 员工隐私严格保密）+ `pack.presets` 收它 ⇒ 本能力从「只有墓碑」变成「有入口」；设置页入口字段由 `hrOfficeRole`(hr-office) 改为 `hrRole`(argent-hr)，旧角色改用 `hrOfficeTombstone` 字段如实报告（⛔ 墓碑不复活、⛔ 不当入口，仍随包落位供老会话 agentPreset 外键解析）。回归：`scripts/tests/agent-catalog.test.mjs`（110 断言，七条判据：只落本智能体 / 子集过滤 / 向后兼容差分 / 未知输入零写入 / remove 备份+审计 / 目录 schema / 内部角色默认不落）。｜**0.1.50（2026-10-10，同批二次收口：宿主资产声明 + 门禁）**：同一工作树里第二次收口（先落 `--agent` 实现并盖章，再补 `capabilities.<c>.pack.hostAssets`（**宿主侧资产声明位**：定时器/登录自启/桌面项）与它的门禁 C12，并把 `scripts/argent-agents.mjs` 的清单/回执接上宿主资产）⇒ 引擎面文件内容变了，按「内容变 ⇒ 版本必变」纪律**再提一版**（先例同 1.3.104→1.3.105、`docs/Argent-智能体平台-设计.md` §8.3 第 3 条）。版本号 0.1.49 从未发布过，不存在「内容变了版本没动」的对外窗口。⛔ 本能力的流程/提示词/脚本内容未再改动。｜**0.1.51（2026-10-10，同批三次收口：安装器用法文案 · 门禁登记 · 引擎面去业务词）**：同一工作树里第三次收口 —— ① `install-argent.mjs` 的**用法头注释**补上 `--agent` / `--list-agents` / `--internal-roles` / `--capability remove` 四个入口（内容变 ⇒ 引擎 sha 变）；② `scripts/tests/is-direct-run.test.mjs` 的**唯一登记处**加入 `scripts/check-agent-catalog.mjs`（新增 CLI 必须登记，否则端到端判据覆盖不到它；测试文件不在包内，本条只为留痕）；③ 本文件里本批新加的 `_note` 文案去掉业务词（`vertical-lint` 的 engine-words 档按**基线**只拦新增，⛔ 不抬基线 ⇒ 改写文案而不是改基线）⇒ 引擎面内容再变，按纪律**再提一版**。版本号 0.1.50 从未发布过，不存在「内容变了版本没动」的对外窗口。⛔ 本能力的流程/提示词/脚本内容未再改动。｜**0.1.52（2026-10-10，仓容前置探测批 —— 注册表投影变化，hr 必须跟随提版）**：本批改了共用引擎面 `scripts/flow-requirements.json`（新增 `failureClasses.capacityFull`）、`scripts/flow_capacity*`/`ml_capacity_probe.py`、`flow_failure.py` 分类顺序、`configs/advanced.json`（`advanced.appointment.max_day` 默认 5）与编排器接入点 ⇒ **每个包的 tgz 里都带一份注册表投影**（含 `failureClasses`/`pack.engine`）⇒ hr 的包字节随之改变。本能力自身内容一字未改（`files` 仍只有两个 preset 目录）。⚠️ **教训**：本批曾按 `--describe hr`（只列 6 个 preset 文件）判定\"hr 不含 pack.engine ⇒ 内容没变\"，漏掉了\"注册表投影在包内\"这一层 ⇒ 被 `release-argent.sh --check-dl` 当场抓成 `✗ hr: 版本相同（0.1.51）但内容摘要不同 ⇒ 同版本覆盖发布的形态`；按不变式提版后该条转为 ⚠「发布在途」。先例：0.1.42 / 0.1.44 / 0.1.46（均为\"改了引擎基表 ⇒ 无 flow 的包也提版本\"）。｜**0.1.55（2026-10-11，同批：引擎面新增 `scripts/lib/cdp_ports.py`）**：本能力**无 flow ⇒ 不背共用引擎**（`files` 仍只有两个 preset 目录，逐字节未变）；但包内注册表投影含 `pack.engine` ⇒ 包字节变了，按「内容变 ⇒ 版本必变（含无 flow 的包）」提版本并重盖章（同 `0.1.42` / `0.1.52` 先例）。本能力内容一字未改。｜**0.1.56（2026-10-12，Windows 安装路径三缺陷修复批）**：共用引擎变更（引擎面文件 ⇒ 每个包的注册表投影都变）——① `scripts/lib/preset-install.mjs`：**「已装集」判据改为选择痕迹** `presets.selection.json#kept`（⛔ 不再读 `package.json#dsh.bundle.patch` —— pnpm 对 `file:` 依赖建的是指向货架的链，读到的永远是货架自带的 14 条 ⇒ 收窄被自己的安装步骤抹掉），新增 `installedSelectionIds()` / `materializeBundleDir()`（软链**实体化**后再改写，⛔ 不走链写进仓库）/ `checkPresetSelectionConsistency()`（patch 实体 == presets.json 行 == dsh.bundle.patch == 痕迹）；② `install-argent.mjs`：新增**第 7c2 步收尾重施**（第 7 步 `pnpm add file:…` 会把 profile 副本换回货架 14 个 ⇒ 旧实现在 winpc 真机\"声称只落 7/14、装完却是 14\"，7 个内部角色永久留下）、版本体检改**两个候选落点**（克隆目录 + 安装器自己那棵树 —— Windows 的 boot 克隆场景，此前永远退回内置列表 ⇒ 现役 `0.1.7-rc.2` 被报\"未验证\"）、`profile-doctor` 与升级器子进程**显式传 `DSH_HOME`**（否则 `--dsh-home <临时>` 时改的是真实 `~/.dsh`）、完成提示**按平台**给启动/重启指引（Windows 不再打 bash 的 `DSH_HOME=… dsh web …`）；③ `scripts/lib/dsh-versions.mjs`：内置基线补 `0.1.7-rc.2` + 新增 `verifiedListGaps()` **防漂移门禁**；④ `scripts/argent-upgrade.mjs`：同一判据 + 收尾重施。⇒ 按「内容变 ⇒ 版本必变（含无 flow 的包）」四个包一起提版本并重盖章。本能力内容**一字未改**（无 flow ⇒ 不背共用引擎，仍因包内注册表投影而变）。回归：`scripts/tests/preset-landing-selection.test.mjs`（48 断言：全新机器恰 7 个客户可见角色 / 客户机的 7 再跑安装**仍 7**（垫片 pnpm 中途真把它放大过）/ 14 坏态收窄到 7 / 三处集合+痕迹不变量 / 软链不走链改写仓库 / 真 pnpm 的机制证据）、`scripts/tests/dsh-verified-list.test.mjs`（21 断言：lock 里已晋级版本必须全在列表内（构造缺项 ⇒ 红）、`candidate/` 不参与、列表唯一真源、boot 克隆场景真跑一次）。⛔ 本批**未发布**（发布留给交付方）。｜**0.1.57（2026-10-12，升级路径角色落盘追修批：已装集唯一来源 + 内部角色不变式）**：本能力**无 flow ⇒ 不背共用引擎**（`files` 仍只有 preset 目录，逐字节未变）；但包内注册表投影含 `pack.engine` ⇒ 包字节变了，按「内容变 ⇒ 版本必变（含无 flow 的包）」一起提版本并重盖章（同 `0.1.42` / `0.1.52` 先例）。本能力内容**一字未改**。① `scripts/lib/preset-install.mjs`：「已装集」的**唯一来源**收口到 `resolveInstalledSelection()`（**可信痕迹** `presets.selection.json#kept` → 退回 `agents.json` 里各 agent 的 `roles` 并集 → 两级都没有 ⇒ **空集**=首次安装语义；⛔ **绝不**把 profile 里的 patch 实体 / `presets.json` 行 / `dsh.bundle.patch` 条目当已装集 —— 那三份铺完恒是 14，「客户可见 ∪ 已装 ∪ 本智能体」于是恒等于 14，收窄被自己的安装步骤抹掉），并给「可信」加了**判据**：痕迹含 `visibility: internal` 的角色而本机 `internalRoles ≠ true`（且未给 `--internal-roles`）⇒ 判不可信、**响亮报告**后按「痕迹缺失」处理（现场那份 `kept:14/excluded:[]` 的痕迹正是放大缺陷写出来的）；新增**不变式** `checkNoInternalLanding()` —— 落盘集合不得含内部角色（除非 `--internal-roles` 或 `agents.json#internalRoles === true`），违反 ⇒ `applyPresetSelection()` **判红并拒绝写出**（⛔ 不静默剔除、不静默修）；新增 `reseedBundleDir()` 与 `applyPresetSelection({reseedFromShelf})`（收尾重施必须**按货架重播再收窄**：副本已被削到 7 时就地再过滤永远只能得 7，`--internal-roles` 装不回来、自检还会拿「期望 14 ≠ 落盘 7」判**假红**）；② `scripts/argent-upgrade.mjs`：**升级档与安装档同一条公式**（客户可见集 ∪ 可信已装集 ∪ 本智能体角色），⛔ 不再用 `agentScoped: agents.length>0`（它把客户可见集整个排除掉 ⇒ 现场那台只落 2 个角色）；第 7.6 步收尾重施带 `allowInternal` + `reseedFromShelf`，判红即该步 `ok:false`；③ `install-argent.mjs`：第 4 步默认档 / `--agent` 子集 / 第 7c2 步收尾重施 / `--capability remove` 四处统一走可信已装集与授权口径（`--capability remove` 只为「本机已合法装了内部角色」时不误判红）；④ **新增只读 CLI** `scripts/check-preset-landing.mjs`（四件套 + 已装集来源 + 两条不变式，任何一台机器可照抄自查，⛔ 不写任何文件）⇒ `pack.engine` 登记项 +1。**现场（winpc 真机，2026-10-12）**：profile 14 个 patch 实体 + 痕迹 `kept:14/excluded:[]` + `agents.json=[hr]` + `internalRoles=false`，重跑官网一条命令（升级路径）修前打的是 `preset 同步（行式）: **14** 个角色` + `角色落盘集合收尾：14 个；三处集合 + 痕迹一致`（7 个内部角色一个没摘），修后同一台机器 ⇒ **7**（`excluded` 列出 7 个内部角色）并打印 `选择痕迹不可信 ⇒ 已装集退回 agents.json 角色`。回归：`scripts/tests/preset-landing-upgrade-path.test.mjs`（43 断言：现场复刻升级路径 ⇒ 7 且 **pre-fix 判据重建得 14**（鉴别力）/ `agents.json` 缺失 ⇒ 7 / 可信痕迹 7 不许放大 / `internalRoles:true` ⇒ 14 放行 / **不变式负样本判红且零写入** / 「铺货架 ≠ 选择」/ 现场真形态 `kept:14` ⇒ 7 且响亮报告 / 真 home 零增量）。⛔ 本批**未发布**（发布留给交付方）。｜**0.1.59（2026-10-12，P1-A 宿主排程批：四道闸防线 + 日报试点声明）**：本能力的流程/提示词/脚本**一字未改**；共用引擎面变更（`scripts/flow_config.py` 新增 trigger.schedule 解析、`scripts/vertical-lint.mjs` 新增排程声明门禁、`scripts/lib/registry.mjs` 新增只读 flowSchedule()）与**包内注册表投影**变化（业务线声明只动了日报；新增的 L1 `scripts/lib/schedule-probe.mjs` 与 L2 `scripts/argent-schedule.mjs` **刻意不进 pack.engine**，理由见 daily-report 的 `_note`）⇒ 按「内容变 ⇒ 版本必变（含无 flow 的包）」一起提版本并重盖章。新增回归 `scripts/tests/schedule-probe.test.mjs` / `scripts/tests/schedule-declaration.test.mjs`。｜**0.1.62（2026-10-12，宿主门禁追修批：⛔ 不代装宿主 + npx 形态纳入宿主解析）**：共用引擎变更（引擎面文件 ⇒ 每个包的注册表投影都变，**含无 flow 的 hr**）——① `install-argent.mjs`：**删除** `--install-host` 代装入口（连同旧自动代装函数与宿主离线包的下载/解包/bin 链接逻辑；开关若仍被传入 ⇒ 报「该开关已废弃」+ **非零退出**（1 = 用法错误），⛔ 不静默忽略），被拒文案改为按 dsh **官方**运行方式给指引（首选 `npx @deepseek-ai/dsh@<窗口内版本> web`；备选官方「从源码运行」；四要素：① 你的版本不在支持窗口（列窗口）② 官方方式换成窗口内版本的一行命令 ③ 我们正在适配你的版本（⛔ 不给对外 ETA）④ 未改动你的 dsh）；② **新增** `scripts/lib/dsh-host-resolve.mjs`（**进 `pack.engine`**）：宿主解析链 = **PATH 上的 `dsh` → `DSH_BIN` → npx 缓存形态**（读 `<npm cache>/_npx/<hash>/node_modules/@deepseek-ai/dsh/package.json` 的 version，纯只读零网络；多候选按「最近使用优先（mtime 最新）+ 同刻路径升序」确定并**打印选了哪个**）⇒ **npx 形态算宿主**（旧口径「npx 不等于已安装宿主」作废），且 npx 形态下插件装配走**同一条 launcher**（`npx --yes @deepseek-ai/dsh@<版本> plugin --profile web add file:…`），⛔ 不许「检测到 npx 却去用 PATH 上的另一个 dsh」；③ `install.sh` / `install.ps1` 口径同步（ps1 仍声明并透传 `-InstallHost`，只为让旧命令行得到**可读**的「已废弃」原因而不是参数绑定错误）。本能力自身流程 / 提示词 / 脚本**一字未改**。回归 `scripts/tests/install-host-gate.test.mjs`（**219 断言**，纯夹具：垫片 dsh/npx + 本地裸库 + 临时 home，⛔ 零外网、⛔ 不碰真 `~/.dsh`；⚠️ `dsh plugin` 会绕过 `DSH_HOME`/`HOME` ⇒ 夹具只断言命令行、绝不真跑）。⛔ 本批**未发布**（发布留给交付方）。",
           "2026-10-12：仓容前置探测**误报**修复（判据收紧为「严格阻断形态」+ 手动/CLI 跑完落终态台账）；注册表投影在每个包内 ⇒ 四包一起提版重盖。",
@@ -644,9 +644,7 @@
       "scripts/invoice_ready_audit.py",
       "scripts/invoice_carrier_notice.py",
       "scripts/ziniao-auth-probe.sh",
-      "install-argent.mjs",
       "scripts/install-license.mjs",
-      "scripts/install-one-shot.mjs",
       "scripts/migrate-providers.mjs",
       "agents/catalog.json",
       "scripts/argent-capabilities.mjs",
@@ -748,4 +746,4 @@
     "_note": "**「定时怎么来」的唯一声明点**（0.6.0 W8，2026-10-14）。取值 `auto | native | activation-shim | none`：`auto` = 按宿主证据决定（探到 `@deepseek-ai/dsh-schedule` ⇒ native，否则按垫片证据）。⭐ 判据**不在这里**：唯一实现是 `scripts/lib/schedule-mechanism.mjs#resolveScheduleMechanism()`；本段只是**声明**（谁在什么条件下被允许），运行期只有两个读取点 —— Node 侧读本段经 `scripts/lib/registry.mjs`（合并唯一真源），Python 侧 `scripts/flow_config.py --schedule-declaration`。`jobs` = **激活垫片**（0.1.7 线）的安装入口清单：`labelPrefix`（LaunchAgent label 前缀）、`installCommand`（模板，占位 `{repo}`/`{flow}`）、`source`（垫片实现文件）。⛔ 两条线**不许同时**调度同一条流程（单一调度者纪律）：native 与 shim 同时在 ⇒ 响亮报冲突（`schedule-mechanism.mjs#schedulerConflict()`，`onConflict: refuse` = ⛔ 不静默择一）。⛔ 探测不到时一律 `unknown`（**不假装可用、不静默装 cron**）——F1（`resolveDshScope()` 可能返回不存在的路径且不感知 npx）未修，所以 native 探测必须分三态：available / absent / unknown。"
   },
   "_engineNoteReleaseBudget20261013": "2026-10-13（**放行额度随上游数据变化重置 + 外部时序独立通道**，修「上限用尽后再也不会被拾取」）。① 引擎面内容变更：`scripts/flow_triage.py`（新增上游逐字段稳定哈希判据 —— 变了才把该票的放行计数归零，并写一条**信息性** `policy_apply{policy=release_budget_reset}`；新增**独立通道**分类与长冷却/独立上限，⛔ 不占既有的每票放行上限）、`scripts/flow_claim.py`（`planned` 增记逐字段哈希快照与独立通道标记，⛔ 只加字段）、`scripts/flow_ledger.py`（`policy_apply` 增一个机器可判的政策名，⛔ 不改事件类型）、`scripts/flow_sources/common.py` 与 `scripts/flow_sources/feishu_base.py`（新增**观察列**进投影的判据 —— 不在投影里的列永远观察不到变化）、`core/contracts/argent.contracts.json`（三处 anchor 行号随上述文件重排）。② 每个包的 tgz 里都带一份注册表投影（含 `pack.engine`）⇒ 引擎面一变、**四个包一起提版本并重盖章**（含**无 flow** 的 `hr`；同 0.1.42 / 0.1.52 先例）。⚠️ 本批在同一工作树里经过**多轮收口**（先落实现，再按 vertical-lint 的引擎业务词约束去掉引擎面文案里的业务词，再收口技能/运维文案与契约 anchor）⇒ 以**最终内容**盖章；版本号**未发布**，不存在「内容变而版本没动」的对外窗口。"
-}
+}

package/engine/scripts/flow-timers.sh

@@ -41,7 +41,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/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/handover-sheet.mjs

@@ -31,9 +31,17 @@ const L = [
   '## 2. 能力包（服务端清单为准）', '',
   '| 能力 | 版本 | sha256（前 16） | 下载 |', '|---|---|---|---|',
   ...Object.entries(manifest).map(([k, v]) => `| ${k} | ${v.version} | \`${String(v.sha256).slice(0, 16)}…\` | ${v.url} |`), '',
+  '## 2.5 首次登录（零手输，推荐）', '',
+  '```bash',
+  'argent auth login --device-code          # 打印授权码并自动打开 https://whyshu.com/argent/device?code=XXXX-XXXX',
+  '```',
+  '在打开的页面上**确认授权**即可（无需复制任何令牌）；命令会自己轮询并在成功后写入权限 600 的凭据，',
+  '并打印套餐与已解锁能力。容器/无浏览器环境加 `--no-open`，把命令打印的链接交给用户自己打开。',
+  '· 终态失败：`expired_token`（10 分钟一次性，重跑）/ `access_denied`（用户点了拒绝）/ `unreachable`（网络不通，exit 2）',
+  '· 备选（用户已有令牌）：`argent auth login --whyshu-token <令牌>`（⛔ 令牌不要进对话）', '',
   '## 3. 一条命令验收（普通用户视角）', '',
   '```bash',
-  'bash scripts/drill-clean-room.sh                 # 13 步；已发布版本 + 临时数据目录；要求 13/0',
+  'bash scripts/drill-clean-room.sh                 # 22 步；已发布版本 + 临时数据目录；要求 22/0',
   'node scripts/audit-all.mjs --with-net            # 终检 + 文档一致 + 证据可复算 + 发布落地；要求 4/4',
   '```', '',
   '## 4. 控制面（服务端，已上线）', '',

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` },