@social-data/social-neuron-subscription 1.0.0-beta.2 → 1.0.0-beta.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@social-data/social-neuron-subscription",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.20",
   "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;②单次拉数≤10 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。"
+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: [] }
@@ -10,10 +10,212 @@ metadata:
 
 > ⚠️ 本技能随该能力 CLI 版本更新。若刚升级过 CLI、重装过 skill,或调用返回 426(版本过旧需升级),请**重新加载本 SKILL.md 与 manifest** 再用——以最新文件为准。
 
-> 命令为一能力一命令:`social-neuron-subscription <action> --flags`(无子命令层)。对象类型(如 notify/target)用一个 JSON 串:`--notify '{...}'`。
+> 命令为一能力一命令:`social-neuron-subscription <action> --flags`(无子命令层)。
+> **取值写法**:标量直接写(`--size 20`);**数组和对象一律写成一个 JSON 串**,与 MCP/HTTP 入参完全同形:`--platforms '["video"]'`、`--where '{...}'`。数组**不能**用逗号分隔,单个取值也要写成数组(`'["video"]'` 而不是 `video`)。
+
+## 怎么用(操作手册)
+
+这是**异步导出**:创建 job → 系统按 cron 或你手动触发 → 产出 task → **轮询 task 拿文件 url**。
+没有主动通知,不轮询就拿不到结果。
+
+### 一、写法约定
+
+**看 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"]'`)不会报格式错 —— 它会被**原样当成字段名**去查,最后报"没有这个字段",
+所以这类错看起来会很迷惑,写的时候对一下参数表的类型列。
+
+### 二、两个概念
+
+| | 是什么 | 谁创建 |
+|---|---|---|
+| **job** | 订阅定义:数据范围 + 频率 + 投递方式 | 你 `job-create` |
+| **task** | job 的**一次执行**,产物和下载地址落在 `file_info` | 系统按 cron,或你 `job-trigger` |
+
+### 三、标准流程
+
+```
+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 一层收窄;
+  不传 = 该维度不过滤。
+- 相对时间支持按天 `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` 只能填**已配置站点的中文名**(用 `list-sites` 查);写 `douyin.com` 这类域名会被拒。
+- 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
+
+## 示例
+
+### 建一个每天跑的订阅,并立刻先跑一次看看
+
+```bash
+# 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 '["抖音"]' \
+  --published 'T-7~T-1' --frequency '每天早上8点' -y
+
+# 4) 不等 cron,手动触发一次
+social-neuron-subscription job-trigger --job-id 1001 -y
+```
+
+> 站点与字段先查后填,别凭感觉写。写操作要加 -y;job-trigger 返回 task_id,拿它去轮询。
+
+### 轮询拿下载地址
+
+```bash
+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
+social-neuron-subscription job-update --job-id 1001 --active false -y
+```
+
+> 只传要改的字段即可;彻底不要才用 job-delete。
 
 ## 命令
 
+### 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。
 
@@ -21,13 +223,16 @@ metadata:
 
 | flag | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
-| --name | name | string | 是 | minLen=1, maxLen=128 | job 名称,全局唯一 |
+| --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 | enum(T-0、T-1、T-7) | 是 | - | 发布时间口径:T-0(当天)/ T-1(昨天)/ T-7(近7天到昨天) |
+| --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 | 拉取/导出字段;不填拉全量 |
-| --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 投递目标;省略默认 octo(excel)。本期仅接受 octo |
+| --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数,默认且最大为 500000 |
+| --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。 |
 
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
 
@@ -46,6 +251,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -54,28 +261,32 @@ metadata:
 | port | integer | 否 | - | 端口,默认 22 |
 | username | string | 是 | - | 登录用户名 |
 | password | string | 是 | - | 登录密码 |
-| remote_path | string | 是 | - | 远端目录/路径 |
+| remote_path | string | 是 | - | 远端目录/路径。可在**任意一层**用日期变量,但变量必须**独占一层**:`/data/sub/yyyyMM/yyyyMMdd` 合法,`/data/sub_yyyyMMdd` 非法。只认 yyyyMMdd / yyyyMM / yyyy 三种;不允许 '..'、空目录层。 |
+| 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) |
 
 **出参 `SubJob`**
 
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| job_id | integer | 是 | - | job ID(sub_job.id) |
-| name | string | 是 | - | job 名称,全局唯一 |
+| job_id | integer | 是 | - | job ID |
+| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
 | source | list[string] | 是 | - | 站点数组 |
-| published | string | 是 | - | 发布时间口径:T-0(当天)/ T-1(昨天)/ T-7(近7天) |
+| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
+| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
+| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
-| target_type | string | 是 | - | 投递类型:octo(本期)/sftp/kafka |
+| target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
 | target_info | object | 是 | - | 投递配置 |
 | active | integer | 是 | - | 1 生效 / 0 停用 |
 | created_at | string | 是 | - | 创建时间(ISO8601,UTC+8) |
 | updated_at | string | 是 | - | 更新时间(ISO8601,UTC+8) |
 
-示例:social-neuron-subscription job-create --name <v> --rule-ids <v> --source <v> --published <v> --frequency <v>
+示例:social-neuron-subscription job-create --name <v> --rule-ids '["a","b"]' --source '["a","b"]' --published <v> --frequency <v>
 
 ### social-neuron-subscription job-delete
 软删除本人 job:置 active=0(记录保留,可 job_update 恢复)。
@@ -111,30 +322,34 @@ metadata:
 | items | list[SubJob] | 是 | - | 本人 job 列表,按创建时间倒序(全量) |
 | total | integer | 是 | - | 命中总数 |
 
-**对象 `SubJob`** —— 订阅 job 出参对象(= sub_job 全字段,id 暴露为 job_id)。
+**对象 `SubJob`** —— 订阅 job 出参对象。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| job_id | integer | 是 | - | job ID(sub_job.id) |
-| name | string | 是 | - | job 名称,全局唯一 |
+| job_id | integer | 是 | - | job ID |
+| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
 | source | list[string] | 是 | - | 站点数组 |
-| published | string | 是 | - | 发布时间口径:T-0(当天)/ T-1(昨天)/ T-7(近7天) |
+| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
+| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
+| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
-| target_type | string | 是 | - | 投递类型:octo(本期)/sftp/kafka |
+| target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
 | target_info | object | 是 | - | 投递配置 |
 | active | integer | 是 | - | 1 生效 / 0 停用 |
 | created_at | string | 是 | - | 创建时间(ISO8601,UTC+8) |
 | updated_at | string | 是 | - | 更新时间(ISO8601,UTC+8) |
 
-示例:social-neuron-subscription job-list 
+示例:social-neuron-subscription job-list
 
 ### social-neuron-subscription job-trigger
-临时触发一次本人 job,落一条 sub_task(manual);默认用 job 存的 target,可覆盖。
+临时触发一次本人 job,落一条 ik_subscription_task(manual);默认用 job 存的 target,可覆盖。
 
-落 pending task 后触发 Airflow DAG(``social_neuron_subscription``)跑取数→组装→投递(上传取 url);
+落 pending task 后触发 Airflow DAG(``social_capability_subscription``)
+跑取数→组装→投递(上传取 url);
 未配 airflow_base_url 时(本地/测试)触发被跳过,仅留 pending task。**无通知**:结果落
 ``file_info.url``,调用方轮询 ``task-list`` 拉取。
 
@@ -143,9 +358,14 @@ metadata:
 | flag | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | --job-id | job_id | integer | 是 | - | 目标 job |
-| --start-time | start_time | string | 否 | - | 回溯起始;与 end_time 同传同不传 |
-| --end-time | end_time | string | 否 | - | 回溯结束 |
+| --start-time | start_time | string | 否 | - | **发布时间**闭区间下界(东八区)。支持 yyyy-MM-dd(整日)、yyyy-MM-ddTHH:mm(整分钟);与 end_time 同传同不传;不传则按 job 上的 published 相对口径折算 |
+| --end-time | end_time | string | 否 | - | **发布时间**闭区间上界(东八区,精度须与下界一致);日期包含整日,分钟包含整分钟 |
+| --idate-start | idate_start | string | 否 | - | **入库时间**闭区间下界(东八区,支持日期/分钟);与 idate_end 同传同不传;不传则按 job 上的 idate 相对口径折算,job 也没配=该维度不过滤 |
+| --idate-end | idate_end | string | 否 | - | 本次**入库时间**闭区间上界(东八区,精度须与下界一致) |
+| --udate-start | udate_start | string | 否 | - | **更新时间**闭区间下界(东八区,支持日期/分钟);与 udate_end 同传同不传;不传则按 job 上的 udate 相对口径折算,job 也没配=该维度不过滤 |
+| --udate-end | udate_end | string | 否 | - | **更新时间**闭区间上界(东八区,精度须与下界一致) |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 覆盖本次投递目标 |
+| --size | size | integer | 否 | min=1, max=500000 | 覆盖本次导出行数;不传则继承 job 的 size,最大 500000 |
 
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
 
@@ -164,6 +384,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -172,7 +394,8 @@ metadata:
 | port | integer | 否 | - | 端口,默认 22 |
 | username | string | 是 | - | 登录用户名 |
 | password | string | 是 | - | 登录密码 |
-| remote_path | string | 是 | - | 远端目录/路径 |
+| remote_path | string | 是 | - | 远端目录/路径。可在**任意一层**用日期变量,但变量必须**独占一层**:`/data/sub/yyyyMM/yyyyMMdd` 合法,`/data/sub_yyyyMMdd` 非法。只认 yyyyMMdd / yyyyMM / yyyy 三种;不允许 '..'、空目录层。 |
+| 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) |
 
 **出参 `SubJobTriggerResult`**
@@ -192,11 +415,14 @@ metadata:
 | flag | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | --job-id | job_id | integer | 是 | - | 目标 job |
-| --name | name | string | 否 | minLen=1, maxLen=128 | 新名称(全局唯一) |
+| --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 | enum(T-0、T-1、T-7) | 否 | - | 发布时间口径:T-0 / T-1 / T-7 |
+| --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 会被拒绝 |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 整体替换投递目标 |
 | --active | active | enum(0、1) | 否 | - | 启停:1 / 0 |
@@ -218,6 +444,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -226,22 +454,26 @@ metadata:
 | port | integer | 否 | - | 端口,默认 22 |
 | username | string | 是 | - | 登录用户名 |
 | password | string | 是 | - | 登录密码 |
-| remote_path | string | 是 | - | 远端目录/路径 |
+| remote_path | string | 是 | - | 远端目录/路径。可在**任意一层**用日期变量,但变量必须**独占一层**:`/data/sub/yyyyMM/yyyyMMdd` 合法,`/data/sub_yyyyMMdd` 非法。只认 yyyyMMdd / yyyyMM / yyyy 三种;不允许 '..'、空目录层。 |
+| 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) |
 
 **出参 `SubJob`**
 
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| job_id | integer | 是 | - | job ID(sub_job.id) |
-| name | string | 是 | - | job 名称,全局唯一 |
+| job_id | integer | 是 | - | job ID |
+| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
 | source | list[string] | 是 | - | 站点数组 |
-| published | string | 是 | - | 发布时间口径:T-0(当天)/ T-1(昨天)/ T-7(近7天) |
+| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
+| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
+| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
-| target_type | string | 是 | - | 投递类型:octo(本期)/sftp/kafka |
+| target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
 | target_info | object | 是 | - | 投递配置 |
 | active | integer | 是 | - | 1 生效 / 0 停用 |
 | created_at | string | 是 | - | 创建时间(ISO8601,UTC+8) |
@@ -249,6 +481,56 @@ metadata:
 
 示例: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/创建时间过滤,按创建时间排序。
 
@@ -272,12 +554,13 @@ metadata:
 | items | list[SubTask] | 是 | - | task 列表,按 created_at 排序(方向由 sort 定,默认倒序) |
 | total | integer | 是 | - | 命中总数 |
 
-**对象 `SubTask`** —— 订阅 task 出参对象(**对外精简**:只给调用方轮询/下载所需;其余字段仅存 sub_task 表供排查)。
+**对象 `SubTask`** —— 订阅 task 出参对象(**对外精简**:只给调用方轮询/下载所需)。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| task_id | integer | 是 | - | task ID(sub_task.id) |
+| task_id | integer | 是 | - | task ID |
 | job_id | integer | 是 | - | 所属 job |
+| size | integer | 是 | - | 本次执行最多导出的记录行数 |
 | 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 时给出;成功/进行中为空) |