@yaoxiu/marketing-dsl 1.4.1 → 1.5.1

package/README.md

@@ -68,7 +68,7 @@ import { createRuntime } from '@yaoxiu/marketing-dsl';
 const runtime = createRuntime(dsl, {
   user: { shopName: '麦爆了旗舰店', version: '专业版' },
   sources: { listRenewTiers: params => api.getTiers(params) },
-  handlers: { setNeverRemind: () => localStorage.setItem('never', '1') },
+  handlers: { openRecharge: () => showRechargeModal() },
   emit: (event, payload) => console.log(event, payload),
 });
 
@@ -135,6 +135,34 @@ unsubscribe();
 | 不能打任意接口         | 数据源用注册名引用，配置里写不了 URL                                 |
 | 不能调任意方法         | `call` 只能调宿主注册在 `handlers` 里的方法                          |
 
+## `call` 的适用边界
+
+`call` 是「**让宿主去做一件事**」，不是「记一笔账」。
+
+| ✅ 该用 `call`                                             | ❌ 不该用 `call`                              |
+| ---------------------------------------------------------- | --------------------------------------------- |
+| 唤起充值弹窗、打开客服会话、复制到剪贴板、跳转应用内特定页 | 记录用户意图、写本地存储（`localStorage` 等） |
+
+判断标准只有一条：**这件事后端需不需要知道**。
+
+- 需要 → 走**上报**：`close` 的 `reason`，或 `track` 动作。
+- 纯粹是宿主的本地动作、后端不关心 → 才用 `call`。
+
+典型反例是「不再提醒」。曾经的写法是 `close` 之外再配一条 `call` 让宿主写 `localStorage`，这是错的：
+
+1. **频控职责分裂**。「这条还要不要出」由后端算，前端存一份频控依据后端看不见，两边依据不一致，规则就是假的。
+2. **换设备、清缓存就失效**。这是用户的长期意图，该跟着账号走，不该跟着浏览器走。
+3. **每个宿主各写一份**。`handlers` 由宿主注册，前台一份、调试台一份、将来 Vue3 宿主再一份，行为迟早分叉。
+
+正确写法不需要任何新增代码，`close` 带上 `reason` 即可：
+
+```jsonc
+{ "type": "close", "reason": "user-dismiss" }
+```
+
+上报出去就是 `{ "id": "...", "event": "close", "reason": "user-dismiss" }`，后端看到这个 `reason`
+就永久压制这条物料。注意这个信息走 **`close` 的 `reason`**，不走 `extra`——`extra` 只属于 `click`。
+
 ## 完整 DSL 语法
 
 见调试台的「开发文档」页，或从那里导出 markdown / AI 提示词。
@@ -158,3 +186,45 @@ buildAiPrompt(); // 生成喂给 AI 的提示词
 章节正文是**数据**（`DocBlock` 数组）不是字符串：调试台按块渲染成页面，`toMarkdown` 导出成 markdown，
 同一份内容两边永远一致。节点类型 / 动作 / 样式白名单 / 埋点事件名正则等清单一律从解释器常量取，
 并经 `reconcileRows` 对账——解释器加了东西而文档没跟上，会在文档页面上直接标出来。
+
+---
+
+## 上报契约（`/report` 子路径）
+
+物料的曝光 / 点击 / 关闭要如实上报给后端。**「运行时事件 → 上报载荷」这一步的映射是纯函数，
+放在这个包的 `/report` 子路径里**，前台（`move-front`）与后台调试台（`moveback-front`）共用同一份：
+
+```ts
+import {
+  mapRuntimeEventToReport,
+  buildExposureReport,
+} from '@yaoxiu/marketing-dsl/report';
+import type { MarketingReportParams } from '@yaoxiu/marketing-dsl/report';
+
+// 宿主把物料画到页面上时主动发（曝光不由运行时事件触发，解释器不知道自己被画出来了）
+buildExposureReport(materialId); // → { id, event: 'exposure' }
+
+// runtime 的 emit 事件直接喂进来，返回 null 表示这个事件不产生上报
+mapRuntimeEventToReport(materialId, 'track', {
+  event: 'banner_renew_click',
+  params: { pos: 1 },
+});
+// → { id, event: 'click', extra: { trigger: 'track', name: 'banner_renew_click', params: { pos: 1 } } }
+mapRuntimeEventToReport(materialId, 'navigate', { url: 'https://a.com' });
+// → { id, event: 'click', extra: { trigger: 'navigate', url: 'https://a.com' } }
+mapRuntimeEventToReport(materialId, 'close', { reason: 'mask' });
+// → { id, event: 'close', reason: 'mask' }
+mapRuntimeEventToReport(materialId, 'call', payload); // → null（call / error / state-change / view-change / ready / open 都不上报）
+```
+
+上报载荷 `MarketingReportParams` 是**可辨识联合**：`reason` 只属于 `close`、`extra` 只属于 `click`，
+写错编译不过；不该出现的字段声明成 `?: never` 而非省略，消费方仍可直接读，不必先窄化。
+
+**给谁用**：接了后端上报的宿主（前台坑位组件），以及调试台的「上报预览」——
+预览要展示的就是真实会发给后端的 JSON，映射再写第二份，前台改了口径而调试台没跟上，预览就会骗人。
+
+**为什么不在主入口**：主入口的身份是「DSL 解释器」，上报是**可选的附加约定**，
+只有接了上报的宿主才需要。主入口不 re-export，边界才清楚，只用解释器的消费方也不背这份代码。
+包根同样有一个物理 `report/` 转发垫片，理由与 `docs/` 一致（webpack 4 不认 `exports`）。
+
+契约字段的完整说明（后端视角）见 `move-front` 仓库的 `docs/marketing/README.md`。

package/dist/docs/index.cjs

@@ -144,7 +144,11 @@ var actionRows = [
   ["closeAll", "\u2014", "\u4E0D\u7BA1\u51E0\u5C42\uFF0C\u5168\u90E8\u5173\u6389"],
   ["setState", "`key`\u3001`value`", "\u6539\u5C40\u90E8\u72B6\u6001\uFF0C\u7528\u6765\u505A\u9009\u4E2D\u5207\u6362"],
   ["track", "`event`\u3001`params`", "\u57CB\u70B9\u4E0A\u62A5\u3002`event` \u6709\u547D\u540D\u89C4\u8303\uFF0C\u89C1\u4E0B"],
-  ["call", "`name`\u3001`params`", "\u8C03\u7528\u5BBF\u4E3B\u6CE8\u518C\u7684\u65B9\u6CD5\uFF08\u5982\u9886\u5238\uFF09\uFF0C`name` \u662F\u767D\u540D\u5355"],
+  [
+    "call",
+    "`name`\u3001`params`",
+    "\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B\uFF08\u5982\u5524\u8D77\u5145\u503C\uFF09\uFF0C`name` \u662F\u767D\u540D\u5355\uFF0C\u8FB9\u754C\u89C1\u4E0B"
+  ],
   ["sequence", "`actions`", "\u4F9D\u6B21\u6267\u884C\u591A\u4E2A\u52A8\u4F5C"]
 ];
 var sections = [
@@ -257,12 +261,45 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
       {
         t: "note",
         tone: "info",
-        text: '`close` \u7684 `reason` \u4F1A\u4E00\u8D77\u4F20\u7ED9\u5BBF\u4E3B\uFF0C\u5BBF\u4E3B\u636E\u6B64\u51B3\u5B9A\u540E\u7EED\u884C\u4E3A\u2014\u2014\u6BD4\u5982 `reason: "user-dismiss"` \u65F6\u8BB0\u4F4F\u300C\u4ECA\u5929\u4E0D\u518D\u663E\u793A\u300D\u3002\u4E0D\u5199 `reason` \u9ED8\u8BA4\u662F `action`\u3002'
+        text: "`close` \u7684 `reason` \u4F1A\u4E00\u8D77\u4F20\u7ED9\u5BBF\u4E3B\uFF0C\u5BBF\u4E3B\u636E\u6B64\u51B3\u5B9A\u540E\u7EED\u884C\u4E3A\uFF0C\u5E76\u539F\u6837\u4E0A\u62A5\u7ED9\u540E\u7AEF\u3002\u4E0D\u5199 `reason` \u9ED8\u8BA4\u662F `action`\u3002"
+      },
+      { t: "h3", text: "\u300C\u4E0D\u518D\u63D0\u9192\u300D\u5C31\u5199 close \u7684 reason\uFF0C\u4E0D\u8981\u914D call" },
+      {
+        t: "p",
+        text: "\u60F3\u8BA9\u7269\u6599\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u4E00\u6761 `close` \u5C31\u591F\u4E86\uFF0C\u628A\u7528\u6237\u7684\u610F\u56FE\u5199\u8FDB `reason`\uFF1A"
+      },
+      {
+        t: "code",
+        code: `{ "type": "close", "reason": "user-dismiss" }`
+      },
+      {
+        t: "p",
+        text: '\u4E0A\u62A5\u51FA\u53BB\u5C31\u662F `{ "id": "...", "event": "close", "reason": "user-dismiss" }`\uFF0C\u540E\u7AEF\u770B\u5230\u8FD9\u4E2A `reason` \u5C31\u6C38\u4E45\u538B\u5236\u8FD9\u6761\u7269\u6599\u3002\u8FD9\u4E2A\u4FE1\u606F\u8D70 `close` \u7684 `reason`\uFF0C\u4E0D\u8D70 `extra`\u2014\u2014`extra` \u53EA\u5C5E\u4E8E `click`\u3002'
       },
       {
         t: "note",
         tone: "warn",
-        text: "\u60F3\u8BA9\u5F39\u7A97\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5149\u9760 `close` \u4E0D\u591F\u2014\u2014\u5B83\u53EA\u7BA1\u8FD9\u4E00\u6B21\u3002\u8981\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765\uFF08\u89C1\u793A\u4F8B \u2461 \u548C \u2464 \u7684\u300C\u4E0D\u518D\u63D0\u9192\u300D\uFF09\u3002"
+        text: "**\u4E0D\u8981**\u518D\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u5199 `localStorage` \u8BB0\u4F4F\u3002\u9891\u63A7\u7531\u540E\u7AEF\u7B97\uFF0C\u524D\u7AEF\u5B58\u4E00\u4EFD\u540E\u7AEF\u770B\u4E0D\u89C1\u7684\u4F9D\u636E\uFF0C\u4E24\u8FB9\u5C31\u5BF9\u4E0D\u4E0A\uFF1B\u800C\u4E14\u6362\u8BBE\u5907\u3001\u6E05\u7F13\u5B58\u5C31\u5931\u6548\u2014\u2014\u7528\u6237\u7684\u957F\u671F\u610F\u56FE\u8BE5\u8DDF\u7740\u8D26\u53F7\u8D70\uFF0C\u4E0D\u8BE5\u8DDF\u7740\u6D4F\u89C8\u5668\u8D70\uFF1B`call` \u7684\u65B9\u6CD5\u8FD8\u662F\u5404\u4E2A\u5BBF\u4E3B\u5404\u6CE8\u518C\u4E00\u4EFD\u7684\uFF0C\u884C\u4E3A\u8FDF\u65E9\u5206\u53C9\u3002"
+      },
+      { t: "h3", text: "call \u7684\u9002\u7528\u8FB9\u754C" },
+      {
+        t: "p",
+        text: "`call` \u662F\u300C**\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B**\u300D\uFF0C\u4E0D\u662F\u300C\u8BB0\u4E00\u7B14\u8D26\u300D\u3002"
+      },
+      {
+        t: "table",
+        head: ["\u2705 \u8BE5\u7528 call", "\u274C \u4E0D\u8BE5\u7528 call"],
+        rows: [
+          [
+            "\u5524\u8D77\u5145\u503C\u5F39\u7A97\u3001\u6253\u5F00\u5BA2\u670D\u4F1A\u8BDD\u3001\u590D\u5236\u5230\u526A\u8D34\u677F\u3001\u8DF3\u8F6C\u5E94\u7528\u5185\u7279\u5B9A\u9875\u9762",
+            "\u8BB0\u5F55\u7528\u6237\u610F\u56FE\u3001\u5199\u672C\u5730\u5B58\u50A8"
+          ]
+        ]
+      },
+      {
+        t: "note",
+        tone: "info",
+        text: "\u5224\u65AD\u6807\u51C6\u53EA\u6709\u4E00\u6761\uFF1A**\u8FD9\u4EF6\u4E8B\u540E\u7AEF\u9700\u4E0D\u9700\u8981\u77E5\u9053**\u3002\u9700\u8981 \u2192 \u8D70\u4E0A\u62A5\uFF08`close` \u7684 `reason`\uFF0C\u6216 `track`\uFF09\uFF1B\u7EAF\u7CB9\u662F\u5BBF\u4E3B\u7684\u672C\u5730\u52A8\u4F5C\u3001\u540E\u7AEF\u4E0D\u5173\u5FC3 \u2192 \u624D\u7528 `call`\u3002"
       },
       { t: "h3", text: "\u66DD\u5149\u548C\u5173\u95ED\u4E5F\u8981\u57CB\u70B9\uFF1Astage.onShow / stage.onClose" },
       {
@@ -289,7 +326,7 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
           ["`close-button`", "\u70B9\u4E86\u5173\u95ED\u6309\u94AE"],
           ["`mask`", "\u70B9\u4E86\u906E\u7F69\uFF08\u9700\u8981 `maskClosable: true`\uFF09"],
           ["`replace`", "\u88AB `open` \u7684 `replace` \u6A21\u5F0F\u9876\u6389"],
-          ["\u81EA\u5B9A\u4E49\u503C", '`close` \u52A8\u4F5C\u91CC\u81EA\u5DF1\u5199\u7684 `reason`\uFF0C\u5982 `"never-remind"`'],
+          ["\u81EA\u5B9A\u4E49\u503C", '`close` \u52A8\u4F5C\u91CC\u81EA\u5DF1\u5199\u7684 `reason`\uFF0C\u5982 `"user-dismiss"`'],
           ["`action`", "`close` \u52A8\u4F5C\u6CA1\u5199 `reason` \u65F6\u7684\u9ED8\u8BA4\u503C"]
         ]
       },
@@ -310,14 +347,13 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
              "textAlign": "center", "lineHeight": 22, "cursor": "pointer" },
   "action": { "type": "sequence", "actions": [
     { "type": "track", "event": "notice_close" },
-    { "type": "call",  "name": "setNeverRemind" },   // \u8BB0\u4F4F\u522B\u518D\u51FA
-    { "type": "close", "reason": "user-dismiss" }
+    { "type": "close", "reason": "user-dismiss" }   // reason \u4E0A\u62A5\u7ED9\u540E\u7AEF\uFF0C\u636E\u6B64\u4E0D\u518D\u4E0B\u53D1
   ] } }`
       },
       {
         t: "note",
         tone: "info",
-        text: "`close` \u53EA\u662F\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C**\u5173\u6389\u4E4B\u540E\u8981\u4E0D\u8981\u518D\u51FA\u3001\u9694\u591A\u4E45\u518D\u51FA\u7531\u5BBF\u4E3B\u51B3\u5B9A**\u3002\u60F3\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\uFF0C\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765\u3002"
+        text: '`close` \u53EA\u662F\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C**\u8FD9\u4E00\u6B21\u5173\u4E0D\u5173\u7531\u5BBF\u4E3B\u51B3\u5B9A**\uFF1B\u800C\u300C\u4EE5\u540E\u8FD8\u51FA\u4E0D\u51FA\u300D\u7531\u540E\u7AEF\u6839\u636E\u4E0A\u62A5\u7684 `reason` \u51B3\u5B9A\uFF0C\u6240\u4EE5\u60F3\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\uFF0C\u5199 `reason: "user-dismiss"` \u5373\u53EF\uFF0C\u4E0D\u9700\u8981\u518D\u914D `call`\u3002'
       },
       {
         t: "note",
@@ -2301,13 +2337,7 @@ var noticeToPopup = {
                 fontSize: 13,
                 cursor: "pointer"
               },
-              action: {
-                type: "sequence",
-                actions: [
-                  { type: "call", name: "setNeverRemind" },
-                  { type: "close", reason: "user-dismiss" }
-                ]
-              }
+              action: { type: "close", reason: "user-dismiss" }
             }
           ]
         }
@@ -2673,13 +2703,13 @@ var confirmAndSwitch = {
                     background: ORANGE3,
                     cursor: "pointer"
                   },
-                  // 确认后整个关掉，两层一起消失
+                  // 确认后整个关掉，两层一起消失。
+                  // 「不再提醒」的意图靠 reason 上报给后端，不配 call 写本地存储
                   action: {
                     type: "sequence",
                     actions: [
                       { type: "track", event: "popup_never_remind_confirm" },
-                      { type: "call", name: "setNeverRemind" },
-                      { type: "closeAll" }
+                      { type: "closeAll", reason: "user-dismiss" }
                     ]
                   },
                   children: [
@@ -2993,13 +3023,8 @@ var imageBanner = {
             fontSize: 13,
             cursor: "pointer"
           },
-          action: {
-            type: "sequence",
-            actions: [
-              { type: "call", name: "setNeverRemind" },
-              { type: "close", reason: "user-dismiss" }
-            ]
-          }
+          // 「不再提醒」写在 close 的 reason 上，上报给后端即可，不配 call 写本地存储
+          action: { type: "close", reason: "user-dismiss" }
         }
       ]
     }
@@ -3130,16 +3155,11 @@ var imageHotspot = {
     {
       id: "hotspot-never",
       type: "box",
-      // 最底部「不再提醒」，动作是关弹窗而不是跳转
+      // 最底部「不再提醒」，动作是关弹窗而不是跳转。
+      // reason 上报给后端，后端据此不再下发这条物料——不需要写本地存储
       rect: ["30%", 478, "40%", 26],
       style: { radius: 13, background: HOTSPOT_BG, cursor: "pointer" },
-      action: {
-        type: "sequence",
-        actions: [
-          { type: "call", name: "setNeverRemind" },
-          { type: "close", reason: "never-remind" }
-        ]
-      }
+      action: { type: "close", reason: "user-dismiss" }
     }
   ]
 };
@@ -3217,7 +3237,6 @@ var noticeBar = {
             type: "sequence",
             actions: [
               { type: "track", event: "notice_close", params: { notice: "guide" } },
-              { type: "call", name: "setNeverRemind" },
               { type: "close", reason: "user-dismiss" }
             ]
           }
@@ -3417,6 +3436,7 @@ function checklistSection() {
       \u6709\u4E00\u4E2A\u4E0D\u5408\u89C4\uFF0C\u6574\u4EFD\u914D\u7F6E\u5C31\u5B58\u4E0D\u4E0A
 - [ ] \u6BCF\u4E2A\u89C6\u56FE\u7684 \`stage\` \u90FD\u6709 \`onShow\` \u66DD\u5149\u57CB\u70B9\u548C \`onClose\` \u5173\u95ED\u57CB\u70B9\uFF0C\`onClose\` \u7684 params \u91CC\u5E26\u4E0A \`"reason": "{{ closeReason }}"\`
 - [ ] \u5173\u95ED\u6309\u94AE\u6CA1\u6709\u591A\u4F59\u7684 \`icon\`\uFF08\u9ED8\u8BA4\u7684\u5185\u7F6E\u77E2\u91CF\u56FE\u6807\u5C31\u662F\u5BF9\u7684\uFF09
+- [ ] \u6CA1\u6709\u7528 \`call\` \u53BB\u8BB0\u5F55\u7528\u6237\u610F\u56FE\u6216\u5199\u672C\u5730\u5B58\u50A8\uFF08\`call\` \u53EA\u7528\u6765\u8BA9\u5BBF\u4E3B\u505A\u4E00\u4EF6\u4E8B\uFF0C\u5982\u5524\u8D77\u5145\u503C / \u6253\u5F00\u5BA2\u670D / \u590D\u5236\u5230\u526A\u8D34\u677F\uFF09\u3002\u300C\u4E0D\u518D\u63D0\u9192\u300D\u5199\u6210 \`{ "type": "close", "reason": "user-dismiss" }\`\uFF0C\u4E0D\u914D \`call\`
 - [ ] \u8F93\u51FA\u7684\u662F\u5408\u6CD5 JSON\uFF08\u6CA1\u6709\u591A\u4F59\u9017\u53F7\u3001\u6CA1\u6709\u6CE8\u91CA\uFF09`;
 }
 function requirementSection() {
@@ -3454,7 +3474,8 @@ function actionSection() {
 - \`setState\`\uFF1A\`{ "type": "setState", "key": "period", "value": "{{ index }}" }\` \u505A\u9009\u4E2D\u5207\u6362
 - \`close\`\uFF1A\u5173\u6389\u5F53\u524D\u8FD9\u4E00\u5C42\uFF08\u53EA\u6709\u4E00\u5C42\u65F6\u5C31\u662F\u6574\u4F53\u5173\u95ED\uFF09\u3002\u6CE8\u610F\u5B83\u53EA\u662F**\u901A\u77E5\u5BBF\u4E3B\u9875\u9762**\u300C\u7528\u6237\u60F3\u5173\u4E86\u300D\uFF0C\u7531\u5BBF\u4E3B\u51B3\u5B9A\u5173\u4E0D\u5173\uFF1B\u591A\u89C6\u56FE\u65F6\u5173\u5185\u5C42\u4E0D\u4F1A\u901A\u77E5\u5BBF\u4E3B\uFF0C\u53EA\u662F\u56DE\u5230\u4E0B\u9762\u90A3\u5C42
 - \`closeAll\`\uFF1A\u51E0\u5C42\u90FD\u5173\u6389\uFF0C\u4E00\u5B9A\u4F1A\u901A\u77E5\u5BBF\u4E3B
-- \u60F3\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5149 \`close\` \u4E0D\u591F\uFF0C\u8981\u518D\u914D\u4E00\u6761 \`{ "type": "call", "name": "setNeverRemind" }\` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765
+- \u60F3\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5C31\u5199 \`{ "type": "close", "reason": "user-dismiss" }\`\u3002\u4E0A\u62A5\u51FA\u53BB\u662F \`{ "event": "close", "reason": "user-dismiss" }\`\uFF0C\u540E\u7AEF\u636E\u6B64\u6C38\u4E45\u538B\u5236\u8FD9\u6761\u7269\u6599\u3002**\u4E0D\u8981**\u518D\u914D \`call\` \u8BA9\u5BBF\u4E3B\u5199\u672C\u5730\u5B58\u50A8\u2014\u2014\u9891\u63A7\u7531\u540E\u7AEF\u7B97\uFF0C\u524D\u7AEF\u5B58\u7684\u4F9D\u636E\u540E\u7AEF\u770B\u4E0D\u89C1\uFF0C\u800C\u4E14\u6362\u8BBE\u5907\u3001\u6E05\u7F13\u5B58\u5C31\u6CA1\u4E86
+- \`call\`\uFF1A**\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B**\uFF08\u5524\u8D77\u5145\u503C\u5F39\u7A97\u3001\u6253\u5F00\u5BA2\u670D\u4F1A\u8BDD\u3001\u590D\u5236\u5230\u526A\u8D34\u677F\u3001\u8DF3\u8F6C\u5E94\u7528\u5185\u7279\u5B9A\u9875\u9762\uFF09\u3002\u5224\u65AD\u6807\u51C6\uFF1A**\u8FD9\u4EF6\u4E8B\u540E\u7AEF\u9700\u4E0D\u9700\u8981\u77E5\u9053**\u2014\u2014\u9700\u8981\u5C31\u8D70\u4E0A\u62A5\uFF08\`close\` \u7684 \`reason\` \u6216 \`track\`\uFF09\uFF0C\u7EAF\u672C\u5730\u52A8\u4F5C\u624D\u7528 \`call\`\u3002\u7EDD\u4E0D\u7528 \`call\` \u8BB0\u5F55\u7528\u6237\u610F\u56FE\u6216\u5199\u672C\u5730\u5B58\u50A8
 - \`open\`\uFF1A\u6253\u5F00\u53E6\u4E00\u4E2A\u89C6\u56FE\uFF0C\u89C1\u4E0B\u4E00\u8282
 - \u4EFB\u4F55\u8282\u70B9\u52A0 \`action\` \u90FD\u80FD\u70B9\u51FB
 - **\u6BCF\u4E2A\u53EF\u70B9\u51FB\u5143\u7D20\u90FD\u5E94\u8BE5\u914D \`track\`**\uFF0C\u5426\u5219\u6CA1\u6709\u6570\u636E\u53EF\u770B
@@ -3504,7 +3525,7 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6
 
 - \`onShow\` \u5728\u6570\u636E\u5C31\u7EEA\u3001\u5F39\u7A97\u771F\u6B63\u6E32\u67D3\u51FA\u6765\u65F6\u89E6\u53D1\u4E00\u6B21
 - \`onClose\` \u5728\u70B9 X\u3001\u70B9\u906E\u7F69\u3001\u8D70 \`close\` \u52A8\u4F5C\u3001\u88AB \`replace\` \u9876\u6389\u65F6\u90FD\u4F1A\u89E6\u53D1
-- \`{{ closeReason }}\` \u53D6\u503C\uFF1A\`close-button\` / \`mask\` / \`replace\` / \`close\` \u52A8\u4F5C\u81EA\u5E26\u7684 \`reason\`\uFF08\u5982 \`"never-remind"\`\uFF09/ \u9ED8\u8BA4 \`action\`
+- \`{{ closeReason }}\` \u53D6\u503C\uFF1A\`close-button\` / \`mask\` / \`replace\` / \`close\` \u52A8\u4F5C\u81EA\u5E26\u7684 \`reason\`\uFF08\u5982 \`"user-dismiss"\`\uFF09/ \u9ED8\u8BA4 \`action\`
 - \u591A\u89C6\u56FE\u65F6\u6BCF\u5C42\u5404\u5199\u5404\u7684\uFF0C\u624D\u80FD\u5206\u5F00\u7EDF\u8BA1
 
 ## \u516C\u544A\u6761 / Banner \u7684\u5173\u95ED
@@ -3517,12 +3538,11 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6
              "textAlign": "center", "lineHeight": 22, "cursor": "pointer" },
   "action": { "type": "sequence", "actions": [
     { "type": "track", "event": "notice_guide_close" },
-    { "type": "call",  "name": "setNeverRemind" },
     { "type": "close", "reason": "user-dismiss" }
   ] } }
 \`\`\`
 
-\`close\` \u53EA\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C\u8981\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\u5F97\u914D\u4E00\u6761 \`call\`\u3002
+\`close\` \u53EA\u901A\u77E5\u5BBF\u4E3B\u300C\u8FD9\u4E00\u6B21\u5173\u4E0D\u5173\u300D\uFF1B\u300C\u4EE5\u540E\u8FD8\u51FA\u4E0D\u51FA\u300D\u7531\u540E\u7AEF\u6309\u4E0A\u62A5\u7684 \`reason\` \u51B3\u5B9A\uFF0C\u6240\u4EE5 \`reason: "user-dismiss"\` \u5C31\u591F\u4E86\uFF0C\u4E0D\u8981\u518D\u914D \`call\`\u3002
 \u6574\u6761\u53EF\u70B9 + \u884C\u672B \xD7 \u4E0D\u4F1A\u51B2\u7A81\uFF1A\u5185\u5C42\u6709\u81EA\u5DF1\u7684 \`action\` \u5C31\u4E0D\u518D\u5192\u6CE1\u7ED9\u5916\u5C42\u3002`;
 }
 function viewsSection() {

package/dist/docs/index.js

@@ -47,7 +47,11 @@ var actionRows = [
   ["closeAll", "\u2014", "\u4E0D\u7BA1\u51E0\u5C42\uFF0C\u5168\u90E8\u5173\u6389"],
   ["setState", "`key`\u3001`value`", "\u6539\u5C40\u90E8\u72B6\u6001\uFF0C\u7528\u6765\u505A\u9009\u4E2D\u5207\u6362"],
   ["track", "`event`\u3001`params`", "\u57CB\u70B9\u4E0A\u62A5\u3002`event` \u6709\u547D\u540D\u89C4\u8303\uFF0C\u89C1\u4E0B"],
-  ["call", "`name`\u3001`params`", "\u8C03\u7528\u5BBF\u4E3B\u6CE8\u518C\u7684\u65B9\u6CD5\uFF08\u5982\u9886\u5238\uFF09\uFF0C`name` \u662F\u767D\u540D\u5355"],
+  [
+    "call",
+    "`name`\u3001`params`",
+    "\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B\uFF08\u5982\u5524\u8D77\u5145\u503C\uFF09\uFF0C`name` \u662F\u767D\u540D\u5355\uFF0C\u8FB9\u754C\u89C1\u4E0B"
+  ],
   ["sequence", "`actions`", "\u4F9D\u6B21\u6267\u884C\u591A\u4E2A\u52A8\u4F5C"]
 ];
 var sections = [
@@ -160,12 +164,45 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
       {
         t: "note",
         tone: "info",
-        text: '`close` \u7684 `reason` \u4F1A\u4E00\u8D77\u4F20\u7ED9\u5BBF\u4E3B\uFF0C\u5BBF\u4E3B\u636E\u6B64\u51B3\u5B9A\u540E\u7EED\u884C\u4E3A\u2014\u2014\u6BD4\u5982 `reason: "user-dismiss"` \u65F6\u8BB0\u4F4F\u300C\u4ECA\u5929\u4E0D\u518D\u663E\u793A\u300D\u3002\u4E0D\u5199 `reason` \u9ED8\u8BA4\u662F `action`\u3002'
+        text: "`close` \u7684 `reason` \u4F1A\u4E00\u8D77\u4F20\u7ED9\u5BBF\u4E3B\uFF0C\u5BBF\u4E3B\u636E\u6B64\u51B3\u5B9A\u540E\u7EED\u884C\u4E3A\uFF0C\u5E76\u539F\u6837\u4E0A\u62A5\u7ED9\u540E\u7AEF\u3002\u4E0D\u5199 `reason` \u9ED8\u8BA4\u662F `action`\u3002"
+      },
+      { t: "h3", text: "\u300C\u4E0D\u518D\u63D0\u9192\u300D\u5C31\u5199 close \u7684 reason\uFF0C\u4E0D\u8981\u914D call" },
+      {
+        t: "p",
+        text: "\u60F3\u8BA9\u7269\u6599\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u4E00\u6761 `close` \u5C31\u591F\u4E86\uFF0C\u628A\u7528\u6237\u7684\u610F\u56FE\u5199\u8FDB `reason`\uFF1A"
+      },
+      {
+        t: "code",
+        code: `{ "type": "close", "reason": "user-dismiss" }`
+      },
+      {
+        t: "p",
+        text: '\u4E0A\u62A5\u51FA\u53BB\u5C31\u662F `{ "id": "...", "event": "close", "reason": "user-dismiss" }`\uFF0C\u540E\u7AEF\u770B\u5230\u8FD9\u4E2A `reason` \u5C31\u6C38\u4E45\u538B\u5236\u8FD9\u6761\u7269\u6599\u3002\u8FD9\u4E2A\u4FE1\u606F\u8D70 `close` \u7684 `reason`\uFF0C\u4E0D\u8D70 `extra`\u2014\u2014`extra` \u53EA\u5C5E\u4E8E `click`\u3002'
       },
       {
         t: "note",
         tone: "warn",
-        text: "\u60F3\u8BA9\u5F39\u7A97\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5149\u9760 `close` \u4E0D\u591F\u2014\u2014\u5B83\u53EA\u7BA1\u8FD9\u4E00\u6B21\u3002\u8981\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765\uFF08\u89C1\u793A\u4F8B \u2461 \u548C \u2464 \u7684\u300C\u4E0D\u518D\u63D0\u9192\u300D\uFF09\u3002"
+        text: "**\u4E0D\u8981**\u518D\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u5199 `localStorage` \u8BB0\u4F4F\u3002\u9891\u63A7\u7531\u540E\u7AEF\u7B97\uFF0C\u524D\u7AEF\u5B58\u4E00\u4EFD\u540E\u7AEF\u770B\u4E0D\u89C1\u7684\u4F9D\u636E\uFF0C\u4E24\u8FB9\u5C31\u5BF9\u4E0D\u4E0A\uFF1B\u800C\u4E14\u6362\u8BBE\u5907\u3001\u6E05\u7F13\u5B58\u5C31\u5931\u6548\u2014\u2014\u7528\u6237\u7684\u957F\u671F\u610F\u56FE\u8BE5\u8DDF\u7740\u8D26\u53F7\u8D70\uFF0C\u4E0D\u8BE5\u8DDF\u7740\u6D4F\u89C8\u5668\u8D70\uFF1B`call` \u7684\u65B9\u6CD5\u8FD8\u662F\u5404\u4E2A\u5BBF\u4E3B\u5404\u6CE8\u518C\u4E00\u4EFD\u7684\uFF0C\u884C\u4E3A\u8FDF\u65E9\u5206\u53C9\u3002"
+      },
+      { t: "h3", text: "call \u7684\u9002\u7528\u8FB9\u754C" },
+      {
+        t: "p",
+        text: "`call` \u662F\u300C**\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B**\u300D\uFF0C\u4E0D\u662F\u300C\u8BB0\u4E00\u7B14\u8D26\u300D\u3002"
+      },
+      {
+        t: "table",
+        head: ["\u2705 \u8BE5\u7528 call", "\u274C \u4E0D\u8BE5\u7528 call"],
+        rows: [
+          [
+            "\u5524\u8D77\u5145\u503C\u5F39\u7A97\u3001\u6253\u5F00\u5BA2\u670D\u4F1A\u8BDD\u3001\u590D\u5236\u5230\u526A\u8D34\u677F\u3001\u8DF3\u8F6C\u5E94\u7528\u5185\u7279\u5B9A\u9875\u9762",
+            "\u8BB0\u5F55\u7528\u6237\u610F\u56FE\u3001\u5199\u672C\u5730\u5B58\u50A8"
+          ]
+        ]
+      },
+      {
+        t: "note",
+        tone: "info",
+        text: "\u5224\u65AD\u6807\u51C6\u53EA\u6709\u4E00\u6761\uFF1A**\u8FD9\u4EF6\u4E8B\u540E\u7AEF\u9700\u4E0D\u9700\u8981\u77E5\u9053**\u3002\u9700\u8981 \u2192 \u8D70\u4E0A\u62A5\uFF08`close` \u7684 `reason`\uFF0C\u6216 `track`\uFF09\uFF1B\u7EAF\u7CB9\u662F\u5BBF\u4E3B\u7684\u672C\u5730\u52A8\u4F5C\u3001\u540E\u7AEF\u4E0D\u5173\u5FC3 \u2192 \u624D\u7528 `call`\u3002"
       },
       { t: "h3", text: "\u66DD\u5149\u548C\u5173\u95ED\u4E5F\u8981\u57CB\u70B9\uFF1Astage.onShow / stage.onClose" },
       {
@@ -192,7 +229,7 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
           ["`close-button`", "\u70B9\u4E86\u5173\u95ED\u6309\u94AE"],
           ["`mask`", "\u70B9\u4E86\u906E\u7F69\uFF08\u9700\u8981 `maskClosable: true`\uFF09"],
           ["`replace`", "\u88AB `open` \u7684 `replace` \u6A21\u5F0F\u9876\u6389"],
-          ["\u81EA\u5B9A\u4E49\u503C", '`close` \u52A8\u4F5C\u91CC\u81EA\u5DF1\u5199\u7684 `reason`\uFF0C\u5982 `"never-remind"`'],
+          ["\u81EA\u5B9A\u4E49\u503C", '`close` \u52A8\u4F5C\u91CC\u81EA\u5DF1\u5199\u7684 `reason`\uFF0C\u5982 `"user-dismiss"`'],
           ["`action`", "`close` \u52A8\u4F5C\u6CA1\u5199 `reason` \u65F6\u7684\u9ED8\u8BA4\u503C"]
         ]
       },
@@ -213,14 +250,13 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6`
              "textAlign": "center", "lineHeight": 22, "cursor": "pointer" },
   "action": { "type": "sequence", "actions": [
     { "type": "track", "event": "notice_close" },
-    { "type": "call",  "name": "setNeverRemind" },   // \u8BB0\u4F4F\u522B\u518D\u51FA
-    { "type": "close", "reason": "user-dismiss" }
+    { "type": "close", "reason": "user-dismiss" }   // reason \u4E0A\u62A5\u7ED9\u540E\u7AEF\uFF0C\u636E\u6B64\u4E0D\u518D\u4E0B\u53D1
   ] } }`
       },
       {
         t: "note",
         tone: "info",
-        text: "`close` \u53EA\u662F\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C**\u5173\u6389\u4E4B\u540E\u8981\u4E0D\u8981\u518D\u51FA\u3001\u9694\u591A\u4E45\u518D\u51FA\u7531\u5BBF\u4E3B\u51B3\u5B9A**\u3002\u60F3\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\uFF0C\u914D\u4E00\u6761 `call` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765\u3002"
+        text: '`close` \u53EA\u662F\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C**\u8FD9\u4E00\u6B21\u5173\u4E0D\u5173\u7531\u5BBF\u4E3B\u51B3\u5B9A**\uFF1B\u800C\u300C\u4EE5\u540E\u8FD8\u51FA\u4E0D\u51FA\u300D\u7531\u540E\u7AEF\u6839\u636E\u4E0A\u62A5\u7684 `reason` \u51B3\u5B9A\uFF0C\u6240\u4EE5\u60F3\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\uFF0C\u5199 `reason: "user-dismiss"` \u5373\u53EF\uFF0C\u4E0D\u9700\u8981\u518D\u914D `call`\u3002'
       },
       {
         t: "note",
@@ -2204,13 +2240,7 @@ var noticeToPopup = {
                 fontSize: 13,
                 cursor: "pointer"
               },
-              action: {
-                type: "sequence",
-                actions: [
-                  { type: "call", name: "setNeverRemind" },
-                  { type: "close", reason: "user-dismiss" }
-                ]
-              }
+              action: { type: "close", reason: "user-dismiss" }
             }
           ]
         }
@@ -2576,13 +2606,13 @@ var confirmAndSwitch = {
                     background: ORANGE3,
                     cursor: "pointer"
                   },
-                  // 确认后整个关掉，两层一起消失
+                  // 确认后整个关掉，两层一起消失。
+                  // 「不再提醒」的意图靠 reason 上报给后端，不配 call 写本地存储
                   action: {
                     type: "sequence",
                     actions: [
                       { type: "track", event: "popup_never_remind_confirm" },
-                      { type: "call", name: "setNeverRemind" },
-                      { type: "closeAll" }
+                      { type: "closeAll", reason: "user-dismiss" }
                     ]
                   },
                   children: [
@@ -2896,13 +2926,8 @@ var imageBanner = {
             fontSize: 13,
             cursor: "pointer"
           },
-          action: {
-            type: "sequence",
-            actions: [
-              { type: "call", name: "setNeverRemind" },
-              { type: "close", reason: "user-dismiss" }
-            ]
-          }
+          // 「不再提醒」写在 close 的 reason 上，上报给后端即可，不配 call 写本地存储
+          action: { type: "close", reason: "user-dismiss" }
         }
       ]
     }
@@ -3033,16 +3058,11 @@ var imageHotspot = {
     {
       id: "hotspot-never",
       type: "box",
-      // 最底部「不再提醒」，动作是关弹窗而不是跳转
+      // 最底部「不再提醒」，动作是关弹窗而不是跳转。
+      // reason 上报给后端，后端据此不再下发这条物料——不需要写本地存储
       rect: ["30%", 478, "40%", 26],
       style: { radius: 13, background: HOTSPOT_BG, cursor: "pointer" },
-      action: {
-        type: "sequence",
-        actions: [
-          { type: "call", name: "setNeverRemind" },
-          { type: "close", reason: "never-remind" }
-        ]
-      }
+      action: { type: "close", reason: "user-dismiss" }
     }
   ]
 };
@@ -3120,7 +3140,6 @@ var noticeBar = {
             type: "sequence",
             actions: [
               { type: "track", event: "notice_close", params: { notice: "guide" } },
-              { type: "call", name: "setNeverRemind" },
               { type: "close", reason: "user-dismiss" }
             ]
           }
@@ -3320,6 +3339,7 @@ function checklistSection() {
       \u6709\u4E00\u4E2A\u4E0D\u5408\u89C4\uFF0C\u6574\u4EFD\u914D\u7F6E\u5C31\u5B58\u4E0D\u4E0A
 - [ ] \u6BCF\u4E2A\u89C6\u56FE\u7684 \`stage\` \u90FD\u6709 \`onShow\` \u66DD\u5149\u57CB\u70B9\u548C \`onClose\` \u5173\u95ED\u57CB\u70B9\uFF0C\`onClose\` \u7684 params \u91CC\u5E26\u4E0A \`"reason": "{{ closeReason }}"\`
 - [ ] \u5173\u95ED\u6309\u94AE\u6CA1\u6709\u591A\u4F59\u7684 \`icon\`\uFF08\u9ED8\u8BA4\u7684\u5185\u7F6E\u77E2\u91CF\u56FE\u6807\u5C31\u662F\u5BF9\u7684\uFF09
+- [ ] \u6CA1\u6709\u7528 \`call\` \u53BB\u8BB0\u5F55\u7528\u6237\u610F\u56FE\u6216\u5199\u672C\u5730\u5B58\u50A8\uFF08\`call\` \u53EA\u7528\u6765\u8BA9\u5BBF\u4E3B\u505A\u4E00\u4EF6\u4E8B\uFF0C\u5982\u5524\u8D77\u5145\u503C / \u6253\u5F00\u5BA2\u670D / \u590D\u5236\u5230\u526A\u8D34\u677F\uFF09\u3002\u300C\u4E0D\u518D\u63D0\u9192\u300D\u5199\u6210 \`{ "type": "close", "reason": "user-dismiss" }\`\uFF0C\u4E0D\u914D \`call\`
 - [ ] \u8F93\u51FA\u7684\u662F\u5408\u6CD5 JSON\uFF08\u6CA1\u6709\u591A\u4F59\u9017\u53F7\u3001\u6CA1\u6709\u6CE8\u91CA\uFF09`;
 }
 function requirementSection() {
@@ -3357,7 +3377,8 @@ function actionSection() {
 - \`setState\`\uFF1A\`{ "type": "setState", "key": "period", "value": "{{ index }}" }\` \u505A\u9009\u4E2D\u5207\u6362
 - \`close\`\uFF1A\u5173\u6389\u5F53\u524D\u8FD9\u4E00\u5C42\uFF08\u53EA\u6709\u4E00\u5C42\u65F6\u5C31\u662F\u6574\u4F53\u5173\u95ED\uFF09\u3002\u6CE8\u610F\u5B83\u53EA\u662F**\u901A\u77E5\u5BBF\u4E3B\u9875\u9762**\u300C\u7528\u6237\u60F3\u5173\u4E86\u300D\uFF0C\u7531\u5BBF\u4E3B\u51B3\u5B9A\u5173\u4E0D\u5173\uFF1B\u591A\u89C6\u56FE\u65F6\u5173\u5185\u5C42\u4E0D\u4F1A\u901A\u77E5\u5BBF\u4E3B\uFF0C\u53EA\u662F\u56DE\u5230\u4E0B\u9762\u90A3\u5C42
 - \`closeAll\`\uFF1A\u51E0\u5C42\u90FD\u5173\u6389\uFF0C\u4E00\u5B9A\u4F1A\u901A\u77E5\u5BBF\u4E3B
-- \u60F3\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5149 \`close\` \u4E0D\u591F\uFF0C\u8981\u518D\u914D\u4E00\u6761 \`{ "type": "call", "name": "setNeverRemind" }\` \u8BA9\u5BBF\u4E3B\u8BB0\u4E0B\u6765
+- \u60F3\u300C\u5173\u4E86\u5C31\u522B\u518D\u51FA\u73B0\u300D\uFF0C\u5C31\u5199 \`{ "type": "close", "reason": "user-dismiss" }\`\u3002\u4E0A\u62A5\u51FA\u53BB\u662F \`{ "event": "close", "reason": "user-dismiss" }\`\uFF0C\u540E\u7AEF\u636E\u6B64\u6C38\u4E45\u538B\u5236\u8FD9\u6761\u7269\u6599\u3002**\u4E0D\u8981**\u518D\u914D \`call\` \u8BA9\u5BBF\u4E3B\u5199\u672C\u5730\u5B58\u50A8\u2014\u2014\u9891\u63A7\u7531\u540E\u7AEF\u7B97\uFF0C\u524D\u7AEF\u5B58\u7684\u4F9D\u636E\u540E\u7AEF\u770B\u4E0D\u89C1\uFF0C\u800C\u4E14\u6362\u8BBE\u5907\u3001\u6E05\u7F13\u5B58\u5C31\u6CA1\u4E86
+- \`call\`\uFF1A**\u8BA9\u5BBF\u4E3B\u53BB\u505A\u4E00\u4EF6\u4E8B**\uFF08\u5524\u8D77\u5145\u503C\u5F39\u7A97\u3001\u6253\u5F00\u5BA2\u670D\u4F1A\u8BDD\u3001\u590D\u5236\u5230\u526A\u8D34\u677F\u3001\u8DF3\u8F6C\u5E94\u7528\u5185\u7279\u5B9A\u9875\u9762\uFF09\u3002\u5224\u65AD\u6807\u51C6\uFF1A**\u8FD9\u4EF6\u4E8B\u540E\u7AEF\u9700\u4E0D\u9700\u8981\u77E5\u9053**\u2014\u2014\u9700\u8981\u5C31\u8D70\u4E0A\u62A5\uFF08\`close\` \u7684 \`reason\` \u6216 \`track\`\uFF09\uFF0C\u7EAF\u672C\u5730\u52A8\u4F5C\u624D\u7528 \`call\`\u3002\u7EDD\u4E0D\u7528 \`call\` \u8BB0\u5F55\u7528\u6237\u610F\u56FE\u6216\u5199\u672C\u5730\u5B58\u50A8
 - \`open\`\uFF1A\u6253\u5F00\u53E6\u4E00\u4E2A\u89C6\u56FE\uFF0C\u89C1\u4E0B\u4E00\u8282
 - \u4EFB\u4F55\u8282\u70B9\u52A0 \`action\` \u90FD\u80FD\u70B9\u51FB
 - **\u6BCF\u4E2A\u53EF\u70B9\u51FB\u5143\u7D20\u90FD\u5E94\u8BE5\u914D \`track\`**\uFF0C\u5426\u5219\u6CA1\u6709\u6570\u636E\u53EF\u770B
@@ -3407,7 +3428,7 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6
 
 - \`onShow\` \u5728\u6570\u636E\u5C31\u7EEA\u3001\u5F39\u7A97\u771F\u6B63\u6E32\u67D3\u51FA\u6765\u65F6\u89E6\u53D1\u4E00\u6B21
 - \`onClose\` \u5728\u70B9 X\u3001\u70B9\u906E\u7F69\u3001\u8D70 \`close\` \u52A8\u4F5C\u3001\u88AB \`replace\` \u9876\u6389\u65F6\u90FD\u4F1A\u89E6\u53D1
-- \`{{ closeReason }}\` \u53D6\u503C\uFF1A\`close-button\` / \`mask\` / \`replace\` / \`close\` \u52A8\u4F5C\u81EA\u5E26\u7684 \`reason\`\uFF08\u5982 \`"never-remind"\`\uFF09/ \u9ED8\u8BA4 \`action\`
+- \`{{ closeReason }}\` \u53D6\u503C\uFF1A\`close-button\` / \`mask\` / \`replace\` / \`close\` \u52A8\u4F5C\u81EA\u5E26\u7684 \`reason\`\uFF08\u5982 \`"user-dismiss"\`\uFF09/ \u9ED8\u8BA4 \`action\`
 - \u591A\u89C6\u56FE\u65F6\u6BCF\u5C42\u5404\u5199\u5404\u7684\uFF0C\u624D\u80FD\u5206\u5F00\u7EDF\u8BA1
 
 ## \u516C\u544A\u6761 / Banner \u7684\u5173\u95ED
@@ -3420,12 +3441,11 @@ countdown_end          // \u5012\u8BA1\u65F6\u5F52\u96F6
              "textAlign": "center", "lineHeight": 22, "cursor": "pointer" },
   "action": { "type": "sequence", "actions": [
     { "type": "track", "event": "notice_guide_close" },
-    { "type": "call",  "name": "setNeverRemind" },
     { "type": "close", "reason": "user-dismiss" }
   ] } }
 \`\`\`
 
-\`close\` \u53EA\u901A\u77E5\u5BBF\u4E3B\u300C\u7528\u6237\u5173\u6389\u4E86\u300D\uFF0C\u8981\u8BA9\u5B83\u522B\u518D\u51FA\u73B0\u5F97\u914D\u4E00\u6761 \`call\`\u3002
+\`close\` \u53EA\u901A\u77E5\u5BBF\u4E3B\u300C\u8FD9\u4E00\u6B21\u5173\u4E0D\u5173\u300D\uFF1B\u300C\u4EE5\u540E\u8FD8\u51FA\u4E0D\u51FA\u300D\u7531\u540E\u7AEF\u6309\u4E0A\u62A5\u7684 \`reason\` \u51B3\u5B9A\uFF0C\u6240\u4EE5 \`reason: "user-dismiss"\` \u5C31\u591F\u4E86\uFF0C\u4E0D\u8981\u518D\u914D \`call\`\u3002
 \u6574\u6761\u53EF\u70B9 + \u884C\u672B \xD7 \u4E0D\u4F1A\u51B2\u7A81\uFF1A\u5185\u5C42\u6709\u81EA\u5DF1\u7684 \`action\` \u5C31\u4E0D\u518D\u5192\u6CE1\u7ED9\u5916\u5C42\u3002`;
 }
 function viewsSection() {

package/dist/index.cjs

@@ -1173,7 +1173,7 @@ function createRuntime(dsl, options = {}) {
     setState,
     emit,
     openView,
-    // 配置里 close 可以自带 reason（如 'never-remind'），要透传给埋点，不能吞掉
+    // 配置里 close 可以自带 reason（如 'user-dismiss'），要透传给埋点，不能吞掉
     closeTop: (reason) => closeTop(reason),
     closeAll: (reason) => closeAll(reason),
     get handlers() {

package/dist/index.js

@@ -645,7 +645,7 @@ function createRuntime(dsl, options = {}) {
     setState,
     emit,
     openView,
-    // 配置里 close 可以自带 reason（如 'never-remind'），要透传给埋点，不能吞掉
+    // 配置里 close 可以自带 reason（如 'user-dismiss'），要透传给埋点，不能吞掉
     closeTop: (reason) => closeTop(reason),
     closeAll: (reason) => closeAll(reason),
     get handlers() {

package/dist/report/index.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+// src/report/map.ts
+function buildExposureReport(id) {
+  if (!id) return null;
+  return { id, event: "exposure" };
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  switch (event) {
+    case "track": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "track", name: data.event, params: data.params }
+      };
+    }
+    case "navigate": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "navigate", url: data.url }
+      };
+    }
+    case "close": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "close",
+        reason: data.reason
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+exports.buildExposureReport = buildExposureReport;
+exports.mapRuntimeEventToReport = mapRuntimeEventToReport;

package/dist/report/index.d.cts

@@ -0,0 +1,150 @@
+import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
+
+/**
+ * 营销物料上报载荷类型（上报契约的唯一数据源）。
+ *
+ * 契约正文见仓库 `docs/marketing/README.md` 的「接口契约 · 上报事件」一节，
+ * 本文件是它的类型化表达，前台（platform-adapters / ui-vue2）与后台调试台共用同一份。
+ *
+ * 【为什么在 core 包里】调试台不装 platform-adapters，两边唯一的共同载体就是这个已发布的 npm 包。
+ * 但它是**可选的附加约定**，走子路径 `@yaoxiu/marketing-dsl/report` 独立入口，
+ * 主入口不 re-export —— 主入口的身份仍然只是「DSL 解释器」，不该知道上报契约的存在。
+ */
+/**
+ * 上报事件类型：曝光 / 点击 / 关闭
+ *
+ * 这是**物料生命周期**的固定三值枚举，由前端写死，不受运营配置影响：
+ * - `exposure` 曝光：物料渲染到页面时，每条一次
+ * - `click` 点击：用户点了物料里任何带动作的元素
+ * - `close` 关闭：用户关掉了这条物料
+ */
+type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 点击上报的附加信息（**只在 `event='click'` 时有值**）
+ *
+ * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
+ * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ */
+interface MarketingClickExtra {
+    /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
+    trigger: 'track' | 'navigate';
+    /** `trigger='track'` 时：运营在配置里写的埋点名 */
+    name?: string;
+    /** `trigger='navigate'` 时：跳转目标地址 */
+    url?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
+/** 曝光上报入参：只有 id */
+interface MarketingExposureReportParams {
+    /** 物料 id，取自 `MarketingMaterial.id` */
+    id: string;
+    /** 事件类型 */
+    event: 'exposure';
+    /** 曝光事件无关闭原因 */
+    reason?: never;
+    /** 曝光事件无点击附加信息 */
+    extra?: never;
+}
+/** 关闭上报入参：可带关闭原因 */
+interface MarketingCloseReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'close';
+    /**
+     * 关闭原因，取自解释器抛出的 close reason：
+     * `close-button`（点 ×）/ `mask`（点遮罩）/ `countdown-end`（倒计时归零自动关）/
+     * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
+     */
+    reason?: string;
+    /** 关闭事件无点击附加信息 */
+    extra?: never;
+}
+/** 点击上报入参：必须带 extra 说明点了什么 */
+interface MarketingClickReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'click';
+    /** 点击事件不写关闭原因 */
+    reason?: never;
+    /** 点击详情，见 {@link MarketingClickExtra} */
+    extra: MarketingClickExtra;
+}
+/**
+ * 上报物料事件的入参（可辨识联合，按 `event` 区分）
+ *
+ * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
+ * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
+ * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
+ */
+type MarketingReportParams = MarketingExposureReportParams | MarketingCloseReportParams | MarketingClickReportParams;
+
+/**
+ * 「DSL 运行时事件 → 上报载荷」的映射（纯函数，无副作用、无框架依赖）。
+ *
+ * 前台坑位组件与后台调试台的「上报预览」共用这一份：
+ * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
+ * 前台改了口径而调试台忘了改，调试台就会骗人。
+ */
+
+/**
+ * 会产生上报的运行时事件及其载荷。
+ *
+ * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 缺字段是允许的，不该在映射这一步炸掉。
+ */
+interface MarketingReportableEventPayloads {
+    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
+    track: {
+        event?: string;
+        params?: Record<string, unknown>;
+    };
+    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
+    navigate: {
+        url?: string;
+        target?: string;
+    };
+    /** 关闭：`reason` 是关闭原因 */
+    close: {
+        reason?: string;
+    };
+}
+/** 会产生上报的运行时事件名 */
+type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
+/**
+ * 事件名 → 载荷类型。
+ *
+ * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
+ * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ */
+type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 曝光上报载荷。
+ *
+ * 单独一个函数是因为曝光**不由运行时事件触发** —— 它是宿主把物料渲染到页面上时主动发的，
+ * 解释器根本不知道自己被画出来了。
+ *
+ * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+/**
+ * 把一个 DSL 运行时事件映射成上报载荷。
+ *
+ * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
+ * - `track` → `click`，`extra = { trigger: 'track', name, params }`
+ * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
+ * - `close` → `close`，带 `reason`
+ * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ *
+ * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
+ * @param event 运行时事件名
+ * @param payload 事件载荷，可缺省
+ * @returns 上报载荷，或 `null`（该事件不产生上报）
+ */
+declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
+
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };

package/dist/report/index.d.ts

@@ -0,0 +1,150 @@
+import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
+
+/**
+ * 营销物料上报载荷类型（上报契约的唯一数据源）。
+ *
+ * 契约正文见仓库 `docs/marketing/README.md` 的「接口契约 · 上报事件」一节，
+ * 本文件是它的类型化表达，前台（platform-adapters / ui-vue2）与后台调试台共用同一份。
+ *
+ * 【为什么在 core 包里】调试台不装 platform-adapters，两边唯一的共同载体就是这个已发布的 npm 包。
+ * 但它是**可选的附加约定**，走子路径 `@yaoxiu/marketing-dsl/report` 独立入口，
+ * 主入口不 re-export —— 主入口的身份仍然只是「DSL 解释器」，不该知道上报契约的存在。
+ */
+/**
+ * 上报事件类型：曝光 / 点击 / 关闭
+ *
+ * 这是**物料生命周期**的固定三值枚举，由前端写死，不受运营配置影响：
+ * - `exposure` 曝光：物料渲染到页面时，每条一次
+ * - `click` 点击：用户点了物料里任何带动作的元素
+ * - `close` 关闭：用户关掉了这条物料
+ */
+type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 点击上报的附加信息（**只在 `event='click'` 时有值**）
+ *
+ * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
+ * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ */
+interface MarketingClickExtra {
+    /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
+    trigger: 'track' | 'navigate';
+    /** `trigger='track'` 时：运营在配置里写的埋点名 */
+    name?: string;
+    /** `trigger='navigate'` 时：跳转目标地址 */
+    url?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
+/** 曝光上报入参：只有 id */
+interface MarketingExposureReportParams {
+    /** 物料 id，取自 `MarketingMaterial.id` */
+    id: string;
+    /** 事件类型 */
+    event: 'exposure';
+    /** 曝光事件无关闭原因 */
+    reason?: never;
+    /** 曝光事件无点击附加信息 */
+    extra?: never;
+}
+/** 关闭上报入参：可带关闭原因 */
+interface MarketingCloseReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'close';
+    /**
+     * 关闭原因，取自解释器抛出的 close reason：
+     * `close-button`（点 ×）/ `mask`（点遮罩）/ `countdown-end`（倒计时归零自动关）/
+     * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
+     */
+    reason?: string;
+    /** 关闭事件无点击附加信息 */
+    extra?: never;
+}
+/** 点击上报入参：必须带 extra 说明点了什么 */
+interface MarketingClickReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'click';
+    /** 点击事件不写关闭原因 */
+    reason?: never;
+    /** 点击详情，见 {@link MarketingClickExtra} */
+    extra: MarketingClickExtra;
+}
+/**
+ * 上报物料事件的入参（可辨识联合，按 `event` 区分）
+ *
+ * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
+ * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
+ * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
+ */
+type MarketingReportParams = MarketingExposureReportParams | MarketingCloseReportParams | MarketingClickReportParams;
+
+/**
+ * 「DSL 运行时事件 → 上报载荷」的映射（纯函数，无副作用、无框架依赖）。
+ *
+ * 前台坑位组件与后台调试台的「上报预览」共用这一份：
+ * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
+ * 前台改了口径而调试台忘了改，调试台就会骗人。
+ */
+
+/**
+ * 会产生上报的运行时事件及其载荷。
+ *
+ * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 缺字段是允许的，不该在映射这一步炸掉。
+ */
+interface MarketingReportableEventPayloads {
+    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
+    track: {
+        event?: string;
+        params?: Record<string, unknown>;
+    };
+    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
+    navigate: {
+        url?: string;
+        target?: string;
+    };
+    /** 关闭：`reason` 是关闭原因 */
+    close: {
+        reason?: string;
+    };
+}
+/** 会产生上报的运行时事件名 */
+type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
+/**
+ * 事件名 → 载荷类型。
+ *
+ * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
+ * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ */
+type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 曝光上报载荷。
+ *
+ * 单独一个函数是因为曝光**不由运行时事件触发** —— 它是宿主把物料渲染到页面上时主动发的，
+ * 解释器根本不知道自己被画出来了。
+ *
+ * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+/**
+ * 把一个 DSL 运行时事件映射成上报载荷。
+ *
+ * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
+ * - `track` → `click`，`extra = { trigger: 'track', name, params }`
+ * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
+ * - `close` → `close`，带 `reason`
+ * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ *
+ * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
+ * @param event 运行时事件名
+ * @param payload 事件载荷，可缺省
+ * @returns 上报载荷，或 `null`（该事件不产生上报）
+ */
+declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
+
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };

package/dist/report/index.js

@@ -0,0 +1,38 @@
+// src/report/map.ts
+function buildExposureReport(id) {
+  if (!id) return null;
+  return { id, event: "exposure" };
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  switch (event) {
+    case "track": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "track", name: data.event, params: data.params }
+      };
+    }
+    case "navigate": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "navigate", url: data.url }
+      };
+    }
+    case "close": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "close",
+        reason: data.reason
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+export { buildExposureReport, mapRuntimeEventToReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaoxiu/marketing-dsl",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "type": "module",
   "description": "营销弹窗 DSL 解释器核心，纯逻辑无框架依赖",
   "license": "MIT",
@@ -21,11 +21,17 @@
       "types": "./dist/docs/index.d.ts",
       "import": "./dist/docs/index.js",
       "require": "./dist/docs/index.cjs"
+    },
+    "./report": {
+      "types": "./dist/report/index.d.ts",
+      "import": "./dist/report/index.js",
+      "require": "./dist/report/index.cjs"
     }
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "report"
   ],
   "dependencies": {},
   "devDependencies": {},

package/report/package.json

@@ -0,0 +1,7 @@
+{
+  "//": "webpack 4 兼容垫片。它用的 enhanced-resolve 4 不认 package.json 的 exports 字段，会把 `@yaoxiu/marketing-dsl/report` 当成物理路径去找。这个目录就是那个物理路径，靠 main/module/types 把它转发到真正的产物上。消费方（后台 moveback-front 的调试台「上报预览」）因此可以照常写 `@yaoxiu/marketing-dsl/report`，不必伸进 dist 里做深路径引入。webpack 5 / Vite / Node 走的仍是根 package.json 的 exports，不经过这里。删掉它之前先确认没有 webpack 4 的消费方。",
+  "main": "../dist/report/index.cjs",
+  "module": "../dist/report/index.js",
+  "types": "../dist/report/index.d.ts",
+  "sideEffects": false
+}