npm - @social-data/social-neuron-subscription - Versions diffs - 1.0.10 → 1.0.11 - Mend

@social-data/social-neuron-subscription 1.0.10 → 1.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/manifest.json +185 -12
package/package.json +1 -1
package/skills/social-neuron-subscription/SKILL.md +115 -8

package/manifest.json CHANGED Viewed

@@ -271,6 +271,32 @@
             ],
             "title": "SftpTarget",
             "type": "object"
+          },
+          "TopSpec": {
+            "additionalProperties": false,
+            "description": "全局TopN排序规格(subscription专用)。",
+            "properties": {
+              "field": {
+                "description": "排序字段(name_en);仅支持可排序类型(keyword/long/double/date)",
+                "title": "Field",
+                "type": "string"
+              },
+              "order": {
+                "default": "desc",
+                "description": "排序方向:desc降序(取最大的N个)/asc升序(取最小的N个)",
+                "enum": [
+                  "asc",
+                  "desc"
+                ],
+                "title": "Order",
+                "type": "string"
+              }
+            },
+            "required": [
+              "field"
+            ],
+            "title": "TopSpec",
+            "type": "object"
           }
         },
         "additionalProperties": false,
@@ -353,12 +379,19 @@
             "type": "array"
           },
           "size": {
-            "default": 500000,
-            "description": "每次执行最多导出的记录行数,默认且最大为 500000",
-            "maximum": 500000,
-            "minimum": 1,
-            "title": "Size",
-            "type": "integer"
+            "anyOf": [
+              {
+                "maximum": 500000,
+                "minimum": 1,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "每次执行最多导出的记录行数。省略则按模式取默认:取全部命中 500,000(同时是上限);传了 top(只取前 N 条)则默认 1,000、上限 10,000",
+            "title": "Size"
           },
           "target": {
             "anyOf": [
@@ -390,6 +423,22 @@
             "default": null,
             "description": "投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。",
             "title": "Target"
+          },
+          "top": {
+            "anyOf": [
+              {
+                "items": {
+                  "$ref": "#/$defs/TopSpec"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "只取前 N 条(可选)。**不改变筛选条件** —— 省略时给命中条件的全部数据,传了则在同一批命中结果里按指定字段排序、只取前 size 条。排序跨发布窗内所有日期 / 站点 / 规则**全局生效**(不是每天各取 N)。多字段按顺序作排序优先级(前者相同时比后者)。字段必须是可排序类型(keyword / long / double / date)。该模式下 size 默认 1,000、最大 10,000;且多条规则改为 OR 合并并去重,导出的 kw_ruleId 恒为 topN、无法区分来源规则",
+            "title": "Top"
           }
         },
         "required": [
@@ -470,10 +519,27 @@
             "type": "array"
           },
           "size": {
-            "description": "每次执行最多导出的记录行数,范围 1–500000",
+            "description": "每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000",
             "title": "Size",
             "type": "integer"
           },
+          "top": {
+            "anyOf": [
+              {
+                "items": {
+                  "additionalProperties": true,
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据",
+            "title": "Top"
+          },
           "frequency": {
             "description": "自然语言频率",
             "title": "Frequency",
@@ -594,7 +660,7 @@
           "field": "size",
           "type": "integer",
           "required": false,
-          "desc": "每次执行最多导出的记录行数,默认且最大为 500000"
+          "desc": "每次执行最多导出的记录行数。省略则按模式取默认:取全部命中 500,000(同时是上限);传了 top(只取前 N 条)则默认 1,000、上限 10,000"
         },
         {
           "flag": "--target",
@@ -602,6 +668,13 @@
           "type": "object(json)",
           "required": false,
           "desc": "投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。"
+        },
+        {
+          "flag": "--top",
+          "field": "top",
+          "type": "list[object](json)",
+          "required": false,
+          "desc": "只取前 N 条(可选)。**不改变筛选条件** —— 省略时给命中条件的全部数据,传了则在同一批命中结果里按指定字段排序、只取前 size 条。排序跨发布窗内所有日期 / 站点 / 规则**全局生效**(不是每天各取 N)。多字段按顺序作排序优先级(前者相同时比后者)。字段必须是可排序类型(keyword / long / double / date)。该模式下 size 默认 1,000、最大 10,000;且多条规则改为 OR 合并并去重,导出的 kw_ruleId 恒为 topN、无法区分来源规则"
         }
       ],
       "transport": {
@@ -781,10 +854,27 @@
                 "type": "array"
               },
               "size": {
-                "description": "每次执行最多导出的记录行数,范围 1–500000",
+                "description": "每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000",
                 "title": "Size",
                 "type": "integer"
               },
+              "top": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "additionalProperties": true,
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据",
+                "title": "Top"
+              },
               "frequency": {
                 "description": "自然语言频率",
                 "title": "Frequency",
@@ -1430,6 +1520,32 @@
             ],
             "title": "SftpTarget",
             "type": "object"
+          },
+          "TopSpec": {
+            "additionalProperties": false,
+            "description": "全局TopN排序规格(subscription专用)。",
+            "properties": {
+              "field": {
+                "description": "排序字段(name_en);仅支持可排序类型(keyword/long/double/date)",
+                "title": "Field",
+                "type": "string"
+              },
+              "order": {
+                "default": "desc",
+                "description": "排序方向:desc降序(取最大的N个)/asc升序(取最小的N个)",
+                "enum": [
+                  "asc",
+                  "desc"
+                ],
+                "title": "Order",
+                "type": "string"
+              }
+            },
+            "required": [
+              "field"
+            ],
+            "title": "TopSpec",
+            "type": "object"
           }
         },
         "additionalProperties": false,
@@ -1610,6 +1726,22 @@
             "description": "整体替换投递目标",
             "title": "Target"
           },
+          "top": {
+            "anyOf": [
+              {
+                "items": {
+                  "$ref": "#/$defs/TopSpec"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "只取前 N 条的排序规格:传入则整组替换,不传则不修改。切到该模式后 size 最大 10,000;传空数组 [] 表示改回「给全部命中数据」",
+            "title": "Top"
+          },
           "active": {
             "anyOf": [
               {
@@ -1702,10 +1834,27 @@
             "type": "array"
           },
           "size": {
-            "description": "每次执行最多导出的记录行数,范围 1–500000",
+            "description": "每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000",
             "title": "Size",
             "type": "integer"
           },
+          "top": {
+            "anyOf": [
+              {
+                "items": {
+                  "additionalProperties": true,
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据",
+            "title": "Top"
+          },
           "frequency": {
             "description": "自然语言频率",
             "title": "Frequency",
@@ -1842,6 +1991,13 @@
           "required": false,
           "desc": "整体替换投递目标"
         },
+        {
+          "flag": "--top",
+          "field": "top",
+          "type": "list[object](json)",
+          "required": false,
+          "desc": "只取前 N 条的排序规格:传入则整组替换,不传则不修改。切到该模式后 size 最大 10,000;传空数组 [] 表示改回「给全部命中数据」"
+        },
         {
           "flag": "--active",
           "field": "active",
@@ -2176,10 +2332,27 @@
                 "type": "integer"
               },
               "size": {
-                "description": "本次执行最多导出的记录行数",
+                "description": "本次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000",
                 "title": "Size",
                 "type": "integer"
               },
+              "top": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "additionalProperties": true,
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "本次生效的排序快照 [{field, order}];null = 取了命中条件的全部数据。非 null 时本次只取按该排序排在前 size 条的数据",
+                "title": "Top"
+              },
               "status": {
                 "description": "pending/running/success/failed/terminated",
                 "title": "Status",
@@ -2332,7 +2505,7 @@
   ],
   "skill": {
     "slug": "social-neuron-subscription",
-    "description": "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;另有三个只读发现接口:list_sites / list_fields 用于建 job 前对齐站点与字段取值;get_field_values 给出枚举值 / 编码值的中文字典,仅在用户明确要求把导出的码值换成中文时按需取用(换值由调用方拿到数据后自行完成,系统不自动回显)。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②单次拉数可指定 size,默认且最大 50 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息",
+    "description": "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;另有三个只读发现接口:list_sites / list_fields 用于建 job 前对齐站点与字段取值;get_field_values 给出枚举值 / 编码值的中文字典,仅在用户明确要求把导出的码值换成中文时按需取用(换值由调用方拿到数据后自行完成,系统不自动回显)。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②两种取数模式二选一:**默认**给命中条件的全部数据、size 默认且最大 50 万、多规则各自拉(同时命中多条规则的数据会重复出现);传 **top** 则不改筛选条件、只在同一批命中里按指定字段跨全部日期/站点/规则排序后取前 N 条、size 默认 1000 最大 10000、多规则 OR 合并(同时命中多条的只出一份),排序字段只能是 keyword/long/double/date 类型;这与平台自身的热搜/热门榜单无关;③导出数据的 kw_ruleId 字段**恒为数组**(列出本行命中的 rule_id;此前是字符串,按老格式解析的下游需改);④投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。⑤如果拉取不到数据则不会产生文件上传，也就没有文件url信息",
     "actions": [
       "get-field-values",
       "job-create",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@social-data/social-neuron-subscription",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Social Neuron subscription 能力 CLI —— 一能力一命令(social-neuron-subscription),薄客户端直达 /subscription/{op}。",
   "bin": {
     "social-neuron-subscription": "bin/cli.js"

package/skills/social-neuron-subscription/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: social-neuron-subscription
-description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;另有三个只读发现接口:list_sites / list_fields 用于建 job 前对齐站点与字段取值;get_field_values 给出枚举值 / 编码值的中文字典,仅在用户明确要求把导出的码值换成中文时按需取用(换值由调用方拿到数据后自行完成,系统不自动回显)。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②单次拉数可指定 size,默认且最大 50 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息"
+description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;另有三个只读发现接口:list_sites / list_fields 用于建 job 前对齐站点与字段取值;get_field_values 给出枚举值 / 编码值的中文字典,仅在用户明确要求把导出的码值换成中文时按需取用(换值由调用方拿到数据后自行完成,系统不自动回显)。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②两种取数模式二选一:**默认**给命中条件的全部数据、size 默认且最大 50 万、多规则各自拉(同时命中多条规则的数据会重复出现);传 **top** 则不改筛选条件、只在同一批命中里按指定字段跨全部日期/站点/规则排序后取前 N 条、size 默认 1000 最大 10000、多规则 OR 合并(同时命中多条的只出一份),排序字段只能是 keyword/long/double/date 类型;这与平台自身的热搜/热门榜单无关;③导出数据的 kw_ruleId 字段**恒为数组**(列出本行命中的 rule_id;此前是字符串,按老格式解析的下游需改);④投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。⑤如果拉取不到数据则不会产生文件上传，也就没有文件url信息"
 metadata:
   openclaw:
     requires: { bins: ['social-neuron-subscription'], skills: [] }
@@ -47,6 +47,10 @@ job-trigger               → 立刻跑一次(不等 cron);返回 task_id
 task-list                 → 轮询该 task,status 变终态后读 file_info 里的下载 url
 ```
+建 job 时先想清楚:同样的筛选条件,要**全部命中的数据**,还是**只要排在前面的若干条**。
+默认是全部;用户明确限定了条数(「只要 1000 条」「按点赞取前 500」「挑互动最多的那批」)
+才加 `--top`(见七,两种模式的 size 上限与多规则语义都不同)。
 到这里订阅就做完了。**码值换中文不在这条流程里** —— 只有用户明确要求时才做,见六。
 改配置用 `job-update`(只传要改的字段);不想再跑就 `job-update --active false`,
@@ -112,13 +116,84 @@ social-neuron-subscription get-field-values --field kw_tag_brand --keyword 兰
 > 以上示例值实查自元数据(2026-10-12);字典由元数据侧维护、会变 —— **以 `get-field-values`
 > 现查为准**,不要把这里的示例当权威映射。
-### 七、容易踩的
+### 七、两种取数模式:全部命中 vs 取前 N 条
+**默认取全部命中的数据**(不传 `--top`)。`--top` **不改变筛选条件**,只是在同一批命中结果里
+按某字段排序、只取前 N 条 —— 用户明确限定了条数时才用。
+> 这不是"榜单数据" —— 跟平台自己的热搜榜/热门榜没有关系,数据源与筛选条件完全不变,
+> 变的只是"给你全部"还是"给你排在前面的那几条"。
+| | 默认(不传 `--top`) | 传 `--top` |
+|---|---|---|
+| 给什么 | 命中条件的**全部**数据 | 同一批命中里,排序后的**前 N 条** |
+| `--size` | 默认/最大 **50 万**,到顶截断 | 默认 **1000**、最大 **10000** |
+| 多条规则 | **各规则分别拉、结果拼接** | **OR 合并:命中任一规则即可** |
+| 同时命中多条规则的数据 | **出现多次**(每条规则各一份) | **只出现一次** |
+| 导出的 `kw_ruleId` | `["r1"]`(该份属哪条规则) | `["r1","r2"]`(命中的全部规则) |
+| 取不满 size | 正常,有多少给多少 | 正常,说明命中数本来就少 |
+排序**全局有效**:跨发布窗内所有日期、所有站点、所有规则排完再取前 N —— 不是每天各取 N,
+也不是每个站点各取 N。
+```bash
+# 近 7 天抖音命中该规则的数据里,按点赞数取最高的 1000 条
+social-neuron-subscription job-create --name 抖音高互动采样   --rule-ids '["12345"]' --source '["抖音"]' --published 'T-7~T-1'   --top '[{"field":"long_likeCount","order":"desc"}]' --size 1000   --frequency '每天早上8点' -y
+```
+`--top` 是 JSON 数组,多个字段按顺序作排序优先级(前者相同时比后者):
+```bash
+--top '[{"field":"long_likeCount","order":"desc"},{"field":"date_publishedAt","order":"desc"}]'
+# 先按点赞降序;点赞一样多的,新的排前面
+```
+**排序字段有类型限制** —— 只能用 `list-fields` 里 `data_type` 为
+`keyword` / `long` / `double` / `date` 的字段。`text`(正文这类分词字段)、`boolean`、
+`object`、`nested` 建 job 时直接拒。`order` 省略默认 `desc`。
+**字段名必须现查**(`list-fields --source '[...]' --keyword 赞`)—— 各站点字段不同,
+上面示例里的 `long_likeCount` 是小红书实查到的点赞数字段,别凭印象写 `kw_likeCount`
+这类名字,那会在建 job 时报"字段不存在"。
+**导出文件按排序顺序输出**:第一行即第 1 名。
+想改回取全部:`job-update --top '[]'`。
+**为什么取前 N 条的 size 反而小这么多**:它要让搜索引擎在全部索引上做一次全局排序,
+深度排序的开销随 N 线性涨,默认那个 50 万放上去会拖垮集群。真要大批量高互动数据,
+用默认模式 + 在魔方规则里加互动量阈值过滤,比用 `--top` 取 50 万健康得多。
+### 八、导出文件里的 `kw_ruleId`(⚠️ 契约已变更)
+导出的每条数据除了业务字段,还带一个 `kw_ruleId`,标明这条数据是被**哪条魔方规则**命中的。
+> ⚠️ **它现在恒为数组**。此前是字符串(`"12345"`),现已统一成数组(`["12345"]`) ——
+> 两种取数模式同形。按老格式解析的下游(直接当字符串比较 / 拼接 / 分组)**必须改**,
+> 否则会拿到 `['12345']` 这样的字面量或整串 JSON。
+```jsonc
+// 默认模式:一片一规则,所以恒为单元素
+{"_id": "abc", "kw_ruleId": ["12345"], "_source": {...}}
+// 传了 --top:OR 合并,同时命中多条规则的数据只出一份,但把命中的都记下
+{"_id": "abc", "kw_ruleId": ["12345", "67890"], "_source": {...}}
+{"_id": "def", "kw_ruleId": ["67890"],          "_source": {...}}
+```
+json 格式下就是 JSON 数组;csv / excel 下这一列落成紧凑 JSON 字符串(如 `["12345"]`),
+按需自行解析。
+### 九、容易踩的
 - **拉不到数据就不会有文件**,`file_info` 里也就没有 url —— 这不是失败,是没命中。
-- 单次导出 `--size` 默认且最大 **50 万行**,超出会截断。
+- 单次导出 `--size`:默认模式下默认且最大 **50 万行**;传了 `--top` 则默认 **1000**、最大 **10000**,超出报错。
 - 每个 token 生效的 job 默认 **≤10 个**,满了要先 `job-delete` 或停用。
 - `--source` 只能填**已配置站点的中文名**(用 `list-sites` 查);写 `douyin.com` 这类域名会被拒。
 - 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
+- 传了 `--top` 时同时命中多条规则的数据只出现一份(`kw_ruleId` 里列出全部命中的规则);
+  不传时每条规则各出一份。按规则分组统计前先想清楚要哪种。
+- `kw_ruleId` **恒为数组**(契约已变更,见八),别再当字符串用。
 ## 示例
@@ -167,6 +242,18 @@ social-neuron-subscription get-field-values --field kw_tag_brand --keyword 兰
 > 仅在用户要求时做,且由你在拿到数据后自己换 —— 系统不自动回显。is_enum / is_code 为真也不等于要换:先看字典,code 与 value 相同(如情感标签)就无需转换。
+### 只要符合条件的前 N 条(按指定字段排序)
+```bash
+# 传了 --top 就从「给全部命中数据」改成「只给排序后的前 N 条」,筛选条件不变
+social-neuron-subscription job-create --name 抖音高互动采样 \
+  --rule-ids '["12345"]' --source '["抖音"]' --published 'T-7~T-1' \
+  --top '[{"field":"long_likeCount","order":"desc"}]' --size 1000 \
+  --frequency '每天早上8点' -y
+```
+> 排序跨发布窗内所有日期/站点/规则全局生效,不是每天各取 1000。排序字段只能是 keyword/long/double/date(用 list-fields 看 data_type);size 最大 10000。多规则在这个模式下是 OR 合并:同时命中多条的数据只出一份,kw_ruleId 里列出命中的全部规则。与平台自己的热搜/热门榜无关,数据源和筛选条件都没变。
 ### 临时停用一个订阅(保留定义)
 ```bash
@@ -231,8 +318,9 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --udate | udate | string | 否 | - | **更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 AND 一层:更新时间落在本区间的数据。支持两种相对时间口径:**按天 T-M~T-N** 与**按分钟 T-M@HH:mm~T-N@HH:mm**。M/N 是相对基准日的天数偏移,HH:mm 使用 24 小时制(00:00–23:59);基准时间取本次触发的 cron 槽位时间(东八区),手动触发取触发时间。**两个端点都必须写全且精度必须一致**:不接受 T-1 单值简写,也不允许T-1@07:00~T-0 这类按天、按分钟混用。所有口径均为左闭右闭区间 [start,end],即起止端点都包含。按天格式包含首尾自然日,查询时起始日补 00:00:00、结束日补 23:59:59。例如:T-0~T-0=今天;T-1~T-1=昨天;T-2~T-1=前天到昨天;T-7~T-1=近7天到昨天。按分钟格式包含首尾分钟,查询时起始分钟补 :00、结束分钟补 :59。例如:T-1@07:00~T-0@06:59=昨天07:00:00至今天06:59:59,完整覆盖昨天7点到今天6点时段;T-0@09:30~T-0@10:45=今天09:30:00至10:45:59。起点不得晚于终点;跨度最多 731 天(两年)、偏移最多 915 天(30个月),超限直接报错(不会静默回落)。 |
 | --frequency | frequency | string | 是 | minLen=1, maxLen=64 | 自然语言同步频率,系统转 cron(东八区)。可指定具体时间、并**支持一天多次**:如「每天9点」「每天9点和15点」(一天跑两次)「每周一9点」「每小时」「每30分钟」。无法解析为 cron 会被拒绝。 |
 | --fields | fields | list[string] | 否 | minLen=1 | 拉取/导出字段;不填拉全量 |
-| --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数,默认且最大为 500000 |
+| --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数。省略则按模式取默认:取全部命中 500,000(同时是上限);传了 top(只取前 N 条)则默认 1,000、上限 10,000 |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。 |
+| --top | top | list[TopSpec] | 否 | - | 只取前 N 条(可选)。**不改变筛选条件** —— 省略时给命中条件的全部数据,传了则在同一批命中结果里按指定字段排序、只取前 size 条。排序跨发布窗内所有日期 / 站点 / 规则**全局生效**(不是每天各取 N)。多字段按顺序作排序优先级(前者相同时比后者)。字段必须是可排序类型(keyword / long / double / date)。该模式下 size 默认 1,000、最大 10,000;且多条规则改为 OR 合并并去重,导出的 kw_ruleId 恒为 topN、无法区分来源规则 |
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
@@ -265,6 +353,13 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | filename_template | string | 否 | - | 自定义文件名模板(不含扩展名)。只允许字母、数字、'_'、'-' 与日期变量,且变量前后必须是 '_' 或首尾:`daily_yyyyMMdd_export`、`yyyyMM_summary` 合法,`dailyyyyyMMdd`、`report-yyyyMMdd-x` 非法。系统统一追加 `_<task_id>` 与扩展名。不传=沿用默认 `<job_id>_<task_id>.<ext>`。 |
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
+**对象 `TopSpec`** —— 全局TopN排序规格(subscription专用)。
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | - | 排序字段(name_en);仅支持可排序类型(keyword/long/double/date) |
+| order | enum(asc、desc) | 否 | - | 排序方向:desc降序(取最大的N个)/asc升序(取最小的N个) |
 **出参 `SubJob`**
 | 字段 | 类型 | 必填 | 约束 | 说明 |
@@ -277,7 +372,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
+| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -334,7 +430,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
+| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -425,6 +522,7 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数;不传则不修改,最大 500000 |
 | --frequency | frequency | string | 否 | minLen=1, maxLen=64 | 传入则按新频率重算 cron(用法同创建;支持一天多次,如「每天9点和15点」);无法解析为 cron 会被拒绝 |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 整体替换投递目标 |
+| --top | top | list[TopSpec] | 否 | - | 只取前 N 条的排序规格:传入则整组替换,不传则不修改。切到该模式后 size 最大 10,000;传空数组 [] 表示改回「给全部命中数据」 |
 | --active | active | enum(0、1) | 否 | - | 启停:1 / 0 |
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
@@ -458,6 +556,13 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | filename_template | string | 否 | - | 自定义文件名模板(不含扩展名)。只允许字母、数字、'_'、'-' 与日期变量,且变量前后必须是 '_' 或首尾:`daily_yyyyMMdd_export`、`yyyyMM_summary` 合法,`dailyyyyyMMdd`、`report-yyyyMMdd-x` 非法。系统统一追加 `_<task_id>` 与扩展名。不传=沿用默认 `<job_id>_<task_id>.<ext>`。 |
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
+**对象 `TopSpec`** —— 全局TopN排序规格(subscription专用)。
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | - | 排序字段(name_en);仅支持可排序类型(keyword/long/double/date) |
+| order | enum(asc、desc) | 否 | - | 排序方向:desc降序(取最大的N个)/asc升序(取最小的N个) |
 **出参 `SubJob`**
 | 字段 | 类型 | 必填 | 约束 | 说明 |
@@ -470,7 +575,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
+| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -560,7 +666,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 |---|---|---|---|---|
 | task_id | integer | 是 | - | task ID |
 | job_id | integer | 是 | - | 所属 job |
-| size | integer | 是 | - | 本次执行最多导出的记录行数 |
+| size | integer | 是 | - | 本次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| top | list[object] | 否 | - | 本次生效的排序快照 [{field, order}];null = 取了命中条件的全部数据。非 null 时本次只取按该排序排在前 size 条的数据 |
 | status | string | 是 | - | pending/running/success/failed/terminated |
 | file_info | object | 否 | - | 产物 + 下载入口,含 type 标识:octo→{type,name,format,rows,url};sftp→{...,url,path};kafka→{type,brokers,topic} |
 | error_msg | string | 否 | - | 失败原因(status=failed 时给出;成功/进行中为空) |