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

package/manifest.json

@@ -1,10 +1,128 @@
 {
-  "revision": 6,
+  "revision": 9,
   "capability": "subscription",
   "command": "social-neuron-subscription",
   "default_action": null,
   "mcp_path": "/subscription/mcp",
   "tools": [
+    {
+      "action": "get-field-values",
+      "op": "get_field_values",
+      "name": "subscription/get_field_values",
+      "summary": "取字段值字典 [{code, value}];**仅在需要把导出的码值换成中文时按需取用**。",
+      "description": "取字段值字典 [{code, value}];**仅在需要把导出的码值换成中文时按需取用**。\n\n枚举字段与编码字段统一走这里(值从哪来是元数据内部的事,对外只有\"有没有字典\"之分)。\n\n换值**不是订阅的标准步骤**:导出文件默认按大库原值交付,只有调用方(或其用户)明确要求\n中文时才用这份字典自行替换 —— 系统不做出参自动回显,也不读产出的文件。\n\n**空列表原样返回**:不在出参里猜原因 —— \"该字段真是明文(本就无字典)\"与\"元数据侧没配值来源\"\n在出参上无法区分,猜错反而误导(说成\"直接当原值用\"会让调用方把一列 code 当中文发出去)。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "field": {
+            "description": "字段 name_en(取自 list_fields);仅 is_enum / is_code 为真的字段有值字典(按需取用:只有要把导出的码值换成中文时才需要)",
+            "title": "Field",
+            "type": "string"
+          },
+          "keyword": {
+            "anyOf": [
+              {
+                "maxLength": 64,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "按中文值 / code 模糊过滤(如品牌搜「兰」);不传=全量,编码类字段(品牌/品类标签)可上千条,建议带",
+            "title": "Keyword"
+          }
+        },
+        "required": [
+          "field"
+        ],
+        "title": "SubFieldValuesInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "$defs": {
+          "SubFieldValue": {
+            "additionalProperties": false,
+            "description": "值字典的一项。\n\n刻意**不复用** ``commons.metadata.schemas.values.FieldValue``:那是元数据面的内部契约,\n字段说明里带着上游系统的字段名(``tagCode`` / ``tagName`` 之类),对外没有意义也不该暴露。\n这里只说调用方需要知道的两件事:导出列里存的是什么、对应的中文是什么。",
+            "properties": {
+              "code": {
+                "description": "编码值 —— 导出列里实际存的那个值(如 1、V200500020023)",
+                "title": "Code",
+                "type": "string"
+              },
+              "value": {
+                "description": "该编码值对应的中文",
+                "title": "Value",
+                "type": "string"
+              }
+            },
+            "required": [
+              "code",
+              "value"
+            ],
+            "title": "SubFieldValue",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "field": {
+            "description": "字段 name_en(回显入参)",
+            "title": "Field",
+            "type": "string"
+          },
+          "items": {
+            "description": "值字典 [{code, value}]:code 是导出列里存的值,value 是对应中文;明文字段无字典,返回空列表",
+            "items": {
+              "$ref": "#/$defs/SubFieldValue"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "值总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "field",
+          "items",
+          "total"
+        ],
+        "title": "SubFieldValueList",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--field",
+          "field": "field",
+          "type": "string",
+          "required": true,
+          "desc": "字段 name_en(取自 list_fields);仅 is_enum / is_code 为真的字段有值字典(按需取用:只有要把导出的码值换成中文时才需要)"
+        },
+        {
+          "flag": "--keyword",
+          "field": "keyword",
+          "type": "string",
+          "required": false,
+          "desc": "按中文值 / code 模糊过滤(如品牌搜「兰」);不传=全量,编码类字段(品牌/品类标签)可上千条,建议带"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/subscription/get_field_values",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
     {
       "action": "job-create",
       "op": "job_create",
@@ -185,7 +303,7 @@
             "type": "array"
           },
           "published": {
-            "description": "**发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。",
             "pattern": "^(?:T-\\d+~T-\\d+|T-\\d+@(?:[01]\\d|2[0-3]):[0-5]\\d~T-\\d+@(?:[01]\\d|2[0-3]):[0-5]\\d)$",
             "title": "Published",
             "type": "string"
@@ -201,7 +319,7 @@
               }
             ],
             "default": null,
-            "description": "**入库时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**入库时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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个月),超限直接报错(不会静默回落)。",
             "title": "Idate"
           },
           "udate": {
@@ -215,7 +333,7 @@
               }
             ],
             "default": null,
-            "description": "**更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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个月),超限直接报错(不会静默回落)。",
             "title": "Udate"
           },
           "frequency": {
@@ -441,21 +559,21 @@
           "field": "published",
           "type": "string",
           "required": true,
-          "desc": "**发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--idate",
           "field": "idate",
           "type": "string",
           "required": false,
-          "desc": "**入库时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**入库时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--udate",
           "field": "udate",
           "type": "string",
           "required": false,
-          "desc": "**更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--frequency",
@@ -1383,7 +1501,7 @@
               }
             ],
             "default": null,
-            "description": "**发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。",
             "title": "Published"
           },
           "idate": {
@@ -1397,7 +1515,7 @@
               }
             ],
             "default": null,
-            "description": "**入库时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**入库时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。",
             "title": "Idate"
           },
           "udate": {
@@ -1411,7 +1529,7 @@
               }
             ],
             "default": null,
-            "description": "**更新时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。",
+            "description": "**更新时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。",
             "title": "Udate"
           },
           "fields": {
@@ -1680,21 +1798,21 @@
           "field": "published",
           "type": "string",
           "required": false,
-          "desc": "**发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--idate",
           "field": "idate",
           "type": "string",
           "required": false,
-          "desc": "**入库时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**入库时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--udate",
           "field": "udate",
           "type": "string",
           "required": false,
-          "desc": "**更新时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。"
+          "desc": "**更新时间**口径。不传=不改;传空串 \"\"=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。"
         },
         {
           "flag": "--fields",
@@ -1745,6 +1863,197 @@
         "internal"
       ]
     },
+    {
+      "action": "list-fields",
+      "op": "list_fields",
+      "name": "subscription/list_fields",
+      "summary": "列出所选站点下可导出的字段:name_en(填 fields 用)、中文名、类型、是否枚举 / code。",
+      "description": "列出所选站点下可导出的字段:name_en(填 fields 用)、中文名、类型、是否枚举 / code。\n\n``is_enum`` / ``is_code`` 为真的字段,导出文件里存的是枚举码 / 编码值;\n**若**调用方要把它们换成中文,再调 ``get_field_values`` 取字典自行替换(按需,非必经步骤)。",
+      "input_schema": {
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "description": "站点数组(中文站点名,取自 list_sites),至少 1 个;返回这些站点下字段的并集",
+            "items": {
+              "minLength": 1,
+              "type": "string"
+            },
+            "minItems": 1,
+            "title": "Source",
+            "type": "array"
+          },
+          "keyword": {
+            "anyOf": [
+              {
+                "maxLength": 64,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "按字段中文名 / name_en 模糊过滤(如「情感」「互动」);不传=该站点全部字段",
+            "title": "Keyword"
+          }
+        },
+        "required": [
+          "source"
+        ],
+        "title": "SubListFieldsInput",
+        "type": "object"
+      },
+      "output_schema": {
+        "$defs": {
+          "SubField": {
+            "additionalProperties": false,
+            "description": "一个可导出字段(**订阅口径**:只给填 ``fields`` 与翻译列值要用的信息)。",
+            "properties": {
+              "name_en": {
+                "description": "字段标识(ES 字段名),即 job_create / job_update 的 fields 该填的值",
+                "title": "Name En",
+                "type": "string"
+              },
+              "name": {
+                "description": "字段中文名 —— 把用户说法对齐到 name_en 用",
+                "title": "Name",
+                "type": "string"
+              },
+              "data_type": {
+                "description": "语义类型:keyword / text / long / double / date / boolean / object / nested",
+                "title": "Data Type",
+                "type": "string"
+              },
+              "description": {
+                "default": "",
+                "description": "字段描述;元数据未登记描述时为空串",
+                "title": "Description",
+                "type": "string"
+              },
+              "is_enum": {
+                "description": "值来自内置枚举(如数据类型、情感):导出列存的是枚举码;如需换成中文,再按需调 get_field_values 取字典自行替换",
+                "title": "Is Enum",
+                "type": "boolean"
+              },
+              "is_code": {
+                "description": "值是编码值(如品牌标签、品类标签):导出列存的是 code 而非中文;如需换成中文,再按需调 get_field_values 取字典自行替换",
+                "title": "Is Code",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name_en",
+              "name",
+              "data_type",
+              "is_enum",
+              "is_code"
+            ],
+            "title": "SubField",
+            "type": "object"
+          }
+        },
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "description": "字段列表(所选站点的并集,按 name_en 排序)",
+            "items": {
+              "$ref": "#/$defs/SubField"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "字段总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "items",
+          "total"
+        ],
+        "title": "SubFieldList",
+        "type": "object"
+      },
+      "flags": [
+        {
+          "flag": "--source",
+          "field": "source",
+          "type": "list[str](json)",
+          "required": true,
+          "desc": "站点数组(中文站点名,取自 list_sites),至少 1 个;返回这些站点下字段的并集"
+        },
+        {
+          "flag": "--keyword",
+          "field": "keyword",
+          "type": "string",
+          "required": false,
+          "desc": "按字段中文名 / name_en 模糊过滤(如「情感」「互动」);不传=该站点全部字段"
+        }
+      ],
+      "transport": {
+        "method": "POST",
+        "path": "/subscription/list_fields",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
+    {
+      "action": "list-sites",
+      "op": "list_sites",
+      "name": "subscription/list_sites",
+      "summary": "列出可订阅站点(中文站点名)—— job_create / job_update 的 source 只能取这里的值。",
+      "description": "列出可订阅站点(中文站点名)—— job_create / job_update 的 source 只能取这里的值。",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "additionalProperties": false,
+        "description": "可订阅站点名单(全量,无需翻页:站点由运维在表里配,量级有界)。",
+        "properties": {
+          "items": {
+            "description": "中文站点名列表,即 job_create / job_update 的 source 该填的值(按配置顺序)",
+            "items": {
+              "type": "string"
+            },
+            "title": "Items",
+            "type": "array"
+          },
+          "total": {
+            "description": "站点总数",
+            "title": "Total",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "items",
+          "total"
+        ],
+        "title": "SubSiteList",
+        "type": "object"
+      },
+      "flags": [],
+      "transport": {
+        "method": "POST",
+        "path": "/subscription/list_sites",
+        "send": "args"
+      },
+      "errors": [
+        "auth_error",
+        "validation",
+        "api_error",
+        "network",
+        "internal"
+      ]
+    },
     {
       "action": "task-list",
       "op": "task_list",
@@ -2023,13 +2332,16 @@
   ],
   "skill": {
     "slug": "social-neuron-subscription",
-    "description": "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task。概念: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 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息",
     "actions": [
+      "get-field-values",
       "job-create",
       "job-delete",
       "job-list",
       "job-trigger",
       "job-update",
+      "list-fields",
+      "list-sites",
       "task-list"
     ]
   }

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: social-neuron-subscription
-description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task。概念: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 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息"
 metadata:
   openclaw:
     requires: { bins: ['social-neuron-subscription'], skills: [] }
@@ -20,8 +20,16 @@ metadata:
 
 ### 一、写法约定
 
-数组和对象一律写成 **JSON 串**,和 MCP 入参同形:`--rule-ids '["r1","r2"]'`、`--target '{...}'`。
-数组不能用逗号分隔,**单个取值也要写成数组**。写错会直接报 `BAD_JSON` 并回显原值。
+**看 flag 的类型决定怎么写**,参数表里每个 flag 都标了类型:
+
+| flag 类型 | 怎么写 | 例子 |
+|---|---|---|
+| `list[...]` / 对象 | **JSON 串**(和 MCP 入参同形),**单个取值也要写成数组** | `--source '["小红书"]'`、`--rule-ids '["r1","r2"]'`、`--target '{...}'` |
+| `string` / `integer` | **直接写值**,不要加方括号 | `--field kw_docType`、`--keyword 品牌`、`--name 每日舆情`、`--size 1000` |
+
+数组不能用逗号分隔。JSON 写坏报 `BAD_JSON` 并回显原值;给标量 flag 套上方括号(如
+`--field '["kw_docType"]'`)不会报格式错 —— 它会被**原样当成字段名**去查,最后报"没有这个字段",
+所以这类错看起来会很迷惑,写的时候对一下参数表的类型列。
 
 ### 二、两个概念
 
@@ -33,15 +41,30 @@ metadata:
 ### 三、标准流程
 
 ```
-job-create   → 拿到 job_id
-job-trigger  → 立刻跑一次(不等 cron);返回 task_id
-task-list    → 轮询该 task,status 变终态后读 file_info 里的下载 url
+list-sites / list-fields  → 先对齐 --source 与 --fields 的合法取值(见四)
+job-create                → 拿到 job_id
+job-trigger               → 立刻跑一次(不等 cron);返回 task_id
+task-list                 → 轮询该 task,status 变终态后读 file_info 里的下载 url
 ```
 
+到这里订阅就做完了。**码值换中文不在这条流程里** —— 只有用户明确要求时才做,见六。
+
 改配置用 `job-update`(只传要改的字段);不想再跑就 `job-update --active false`,
 彻底不要才 `job-delete`。
 
-### 四、三个时间口径别搞混
+### 四、建 job 前先对齐取值(站点 / 字段)
+
+`--source` 和 `--fields` 不能凭感觉写,两个发现接口给的就是合法取值:
+
+| 命令 | 给什么 | 怎么用 |
+|---|---|---|
+| `list-sites` | 可订阅站点(**中文站点名**,如「抖音」「微博」) | 原样填 `--source` |
+| `list-fields --source '["抖音"]'` | 该站点下可导出的字段 | `name_en` 填 `--fields`;`name` 是中文名,用来把用户说法对齐到 `name_en` |
+
+`--source` 填的是**中文站点名**,不是域名 —— `douyin.com` 这类是大库内部的过滤值,填进去会被拒。
+字段近千,按需用 `list-fields --keyword 情感` 收窄。
+
+### 五、三个时间口径别搞混
 
 - `--published` **发布时间,必填**:它同时决定查哪个月的索引,所以不能缺省。
 - `--idate` 入库时间、`--udate` 更新时间:**选填**,是在发布时间窗**之内**再 AND 一层收窄;
@@ -49,12 +72,52 @@ task-list    → 轮询该 task,status 变终态后读 file_info 里的下载 ur
 - 相对时间支持按天 `T-M~T-N` 和按分钟 `T-M@HH:mm~T-N@HH:mm`,均包含首尾;
   如 `T-1@07:00~T-0@06:59` 表示昨天 07:00:00 至今天 06:59:59。
 
-### 五、容易踩的
+### 六、(可选)用户明确要求把码值换成中文时
+
+**默认不做翻译**:导出文件按大库原值交付,`get-field-values` **不是标准流程的一步**,
+不要为了"看起来完整"主动去翻。只有用户明确提出这个要求(如「品牌码换成品牌名」
+「文件里要中文」)时才做下面这件事 —— 而且这是**你拿到数据之后自己的加工**:
+订阅能力不自动回显,也不接受"把文件给我翻一遍"。
+
+`list-fields` 出参里 `is_enum` / `is_code` 为真的字段,导出列存的可能是码:
+
+| 标记 | 值来自 | 举例 |
+|---|---|---|
+| `is_enum: true` | 内置枚举 | `kw_docType`(数据类型):`1`=帖子、`2`=原创帖、`5`=评论 |
+| `is_code: true` | 编码字段(品牌、品类标签…) | `kw_tag_brand`(品牌标签):`V200500020023`=苏格兰百富 |
+| 两者都 false | 明文字段 | 原值,不用翻 |
+
+做法:对这些字段调 `get-field-values` 拿**全量字典** `[{code, value}]`,按 `code` 把导出列的值
+换成 `value`,字典拉一次就能换整列。
+
+**先看字典再决定要不要换**:有些枚举字段的 `code` 与 `value` 本就相同(如 `kw_commonSentimentV2`
+通用情感V2标签,字典是 `负面/负面`、`正面/正面`),导出的已是中文、无需转换;两者不同的才要换。
+
+```bash
+social-neuron-subscription get-field-values --field kw_docType
+# → items: [{"code":"1","value":"帖子"}, {"code":"2","value":"原创帖"}, {"code":"5","value":"评论"}, ...]
+#   导出文件里 kw_docType=1 的行 → 帖子
+```
+
+编码类字段取值上千(品牌标签约 7700 条),务必带 `--keyword` 收窄:
+
+```bash
+social-neuron-subscription get-field-values --field kw_tag_brand --keyword 兰
+# → 命中约百条,如 [{"code":"V200500020023","value":"苏格兰百富"}, ...]
+```
+
+**返回空列表**说明该字段没有值字典(明文字段,或元数据侧还没配值来源)—— 空不等于出错,
+别把 code 当中文直接发出去。
+
+> 以上示例值实查自元数据(2026-10-12);字典由元数据侧维护、会变 —— **以 `get-field-values`
+> 现查为准**,不要把这里的示例当权威映射。
+
+### 七、容易踩的
 
 - **拉不到数据就不会有文件**,`file_info` 里也就没有 url —— 这不是失败,是没命中。
 - 单次导出 `--size` 默认且最大 **50 万行**,超出会截断。
 - 每个 token 生效的 job 默认 **≤10 个**,满了要先 `job-delete` 或停用。
-- `--source` 只能填**已配置的站点**,不是随便写域名。
+- `--source` 只能填**已配置站点的中文名**(用 `list-sites` 查);写 `douyin.com` 这类域名会被拒。
 - 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
 
 ## 示例
@@ -62,16 +125,22 @@ task-list    → 轮询该 task,status 变终态后读 file_info 里的下载 ur
 ### 建一个每天跑的订阅,并立刻先跑一次看看
 
 ```bash
-# 1) 建 job(频率用自然语言,系统转 cron)
+# 1) 先看有哪些站点可订阅(--source 填的是中文站点名)
+social-neuron-subscription list-sites
+
+# 2) 再看该站点有哪些字段可导出(name_en 填 --fields)
+social-neuron-subscription list-fields --source '["抖音"]' --keyword 情感
+
+# 3) 建 job(频率用自然语言,系统转 cron)
 social-neuron-subscription job-create --name 每日舆情 \
-  --rule-ids '["12345"]' --source '["douyin.com"]' \
+  --rule-ids '["12345"]' --source '["抖音"]' \
   --published 'T-7~T-1' --frequency '每天早上8点' -y
 
-# 2) 不等 cron,手动触发一次
+# 4) 不等 cron,手动触发一次
 social-neuron-subscription job-trigger --job-id 1001 -y
 ```
 
-> 写操作要加 -y。job-trigger 返回 task_id,拿它去轮询。
+> 站点与字段先查后填,别凭感觉写。写操作要加 -y;job-trigger 返回 task_id,拿它去轮询。
 
 ### 轮询拿下载地址
 
@@ -81,6 +150,23 @@ social-neuron-subscription task-list --job-id 1001 --page 1 --page-size 10
 
 > status 到终态后读 file_info 里的 url;没命中数据时不会有文件,这不是失败。
 
+### (用户要求中文时)把导出文件里的码值换成中文
+
+```bash
+# 0) 前提:用户明确要求要中文。否则按原值交付,不做这一步
+# 1) 先看哪些字段的值是码(看 is_enum / is_code)
+social-neuron-subscription list-fields --source '["抖音"]' --keyword 品牌
+# → {"name_en":"kw_tag_brand","name":"品牌标签","data_type":"keyword","is_code":true}
+
+# 2) 取该字段的值字典(品牌标签约 7700 条,带 keyword 收窄)
+social-neuron-subscription get-field-values --field kw_tag_brand --keyword 兰
+# → items: [{"code":"V200500020023","value":"苏格兰百富"}, ...]
+
+# 3) 按 code 把导出文件里这一列换成 value(翻译在调用方做)
+```
+
+> 仅在用户要求时做,且由你在拿到数据后自己换 —— 系统不自动回显。is_enum / is_code 为真也不等于要换:先看字典,code 与 value 相同(如情感标签)就无需转换。
+
 ### 临时停用一个订阅(保留定义)
 
 ```bash
@@ -91,6 +177,45 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 ## 命令
 
+### social-neuron-subscription get-field-values
+取字段值字典 [{code, value}];**仅在需要把导出的码值换成中文时按需取用**。
+
+枚举字段与编码字段统一走这里(值从哪来是元数据内部的事,对外只有"有没有字典"之分)。
+
+换值**不是订阅的标准步骤**:导出文件默认按大库原值交付,只有调用方(或其用户)明确要求
+中文时才用这份字典自行替换 —— 系统不做出参自动回显,也不读产出的文件。
+
+**空列表原样返回**:不在出参里猜原因 —— "该字段真是明文(本就无字典)"与"元数据侧没配值来源"
+在出参上无法区分,猜错反而误导(说成"直接当原值用"会让调用方把一列 code 当中文发出去)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --field | field | string | 是 | - | 字段 name_en(取自 list_fields);仅 is_enum / is_code 为真的字段有值字典(按需取用:只有要把导出的码值换成中文时才需要) |
+| --keyword | keyword | string | 否 | maxLen=64 | 按中文值 / code 模糊过滤(如品牌搜「兰」);不传=全量,编码类字段(品牌/品类标签)可上千条,建议带 |
+
+**出参 `SubFieldValueList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| field | string | 是 | - | 字段 name_en(回显入参) |
+| items | list[SubFieldValue] | 是 | - | 值字典 [{code, value}]:code 是导出列里存的值,value 是对应中文;明文字段无字典,返回空列表 |
+| total | integer | 是 | - | 值总数 |
+
+**对象 `SubFieldValue`** —— 值字典的一项。
+
+刻意**不复用** ``commons.metadata.schemas.values.FieldValue``:那是元数据面的内部契约,
+字段说明里带着上游系统的字段名(``tagCode`` / ``tagName`` 之类),对外没有意义也不该暴露。
+这里只说调用方需要知道的两件事:导出列里存的是什么、对应的中文是什么。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| code | string | 是 | - | 编码值 —— 导出列里实际存的那个值(如 1、V200500020023) |
+| value | string | 是 | - | 该编码值对应的中文 |
+
+示例:social-neuron-subscription get-field-values --field <v>
+
 ### social-neuron-subscription job-create
 创建订阅 job:数据范围 + 频率 + 投递 target(默认 octo);系统生成 job_id/cron。
 
@@ -101,9 +226,9 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --name | name | string | 是 | minLen=1, maxLen=128 | job 名称,同一凭证(token)下唯一 |
 | --rule-ids | rule_ids | list[string] | 是 | minItems=1, minLen=1 | 魔方规则ID数组,至少 1 个 |
 | --source | source | list[string] | 是 | minItems=1, minLen=1 | 站点数组,至少 1 个;只能取已配置站点 |
-| --published | published | string | 是 | - | **发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
-| --idate | idate | 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
-| --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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
+| --published | published | string | 是 | - | **发布时间**口径(必填,主口径 —— 它同时决定查哪个月的索引、怎么拆分片,所以不能缺省)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。 |
+| --idate | idate | 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个月),超限直接报错(不会静默回落)。 |
+| --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 |
@@ -293,9 +418,9 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --name | name | string | 否 | minLen=1, maxLen=128 | 新名称(同一凭证下唯一) |
 | --rule-ids | rule_ids | list[string] | 否 | minItems=1, minLen=1 | 整组全量覆盖 |
 | --source | source | list[string] | 否 | minItems=1, minLen=1 | 整组全量覆盖 |
-| --published | published | string | 否 | - | **发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
-| --idate | idate | string | 否 | - | **入库时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
-| --udate | udate | string | 否 | - | **更新时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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。起点不得晚于终点;跨度最多 120 天、偏移最多 720 天,超限直接报错(不会静默回落)。 |
+| --published | published | string | 否 | - | **发布时间**口径(必填字段,只能改不能清)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。 |
+| --idate | idate | string | 否 | - | **入库时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。 |
+| --udate | udate | string | 否 | - | **更新时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。支持两种相对时间口径:**按天 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个月),超限直接报错(不会静默回落)。 |
 | --fields | fields | list[string] | 否 | minLen=1 | 整组全量覆盖 |
 | --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数;不传则不修改,最大 500000 |
 | --frequency | frequency | string | 否 | minLen=1, maxLen=64 | 传入则按新频率重算 cron(用法同创建;支持一天多次,如「每天9点和15点」);无法解析为 cron 会被拒绝 |
@@ -356,6 +481,56 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 示例:social-neuron-subscription job-update --job-id <v>
 
+### social-neuron-subscription list-fields
+列出所选站点下可导出的字段:name_en(填 fields 用)、中文名、类型、是否枚举 / code。
+
+``is_enum`` / ``is_code`` 为真的字段,导出文件里存的是枚举码 / 编码值;
+**若**调用方要把它们换成中文,再调 ``get_field_values`` 取字典自行替换(按需,非必经步骤)。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --source | source | list[string] | 是 | minItems=1, minLen=1 | 站点数组(中文站点名,取自 list_sites),至少 1 个;返回这些站点下字段的并集 |
+| --keyword | keyword | string | 否 | maxLen=64 | 按字段中文名 / name_en 模糊过滤(如「情感」「互动」);不传=该站点全部字段 |
+
+**出参 `SubFieldList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| items | list[SubField] | 是 | - | 字段列表(所选站点的并集,按 name_en 排序) |
+| total | integer | 是 | - | 字段总数 |
+
+**对象 `SubField`** —— 一个可导出字段(**订阅口径**:只给填 ``fields`` 与翻译列值要用的信息)。
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| name_en | string | 是 | - | 字段标识(ES 字段名),即 job_create / job_update 的 fields 该填的值 |
+| name | string | 是 | - | 字段中文名 —— 把用户说法对齐到 name_en 用 |
+| data_type | string | 是 | - | 语义类型:keyword / text / long / double / date / boolean / object / nested |
+| description | string | 否 | - | 字段描述;元数据未登记描述时为空串 |
+| is_enum | boolean | 是 | - | 值来自内置枚举(如数据类型、情感):导出列存的是枚举码;如需换成中文,再按需调 get_field_values 取字典自行替换 |
+| is_code | boolean | 是 | - | 值是编码值(如品牌标签、品类标签):导出列存的是 code 而非中文;如需换成中文,再按需调 get_field_values 取字典自行替换 |
+
+示例:social-neuron-subscription list-fields --source '["a","b"]'
+
+### social-neuron-subscription list-sites
+列出可订阅站点(中文站点名)—— job_create / job_update 的 source 只能取这里的值。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+
+**出参 `SubSiteList`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| items | list[string] | 是 | - | 中文站点名列表,即 job_create / job_update 的 source 该填的值(按配置顺序) |
+| total | integer | 是 | - | 站点总数 |
+
+示例:social-neuron-subscription list-sites
+
 ### social-neuron-subscription task-list
 列出某本人 job 的执行 task(翻页),可按 task_id 查单条、status/创建时间过滤,按创建时间排序。