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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@social-data/social-neuron-subscription",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "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;另有三个只读发现接口: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信息"
+description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;普通批量创建/取数配置修改有数据量预检，可选 precheck 只读预览；超量先提示调整参数或征求用户确认，明确同意系统超限规则后才以 confirmed=true 重提，导出仍按上限截断；另有三个只读发现接口: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: [] }
@@ -13,6 +13,9 @@ metadata:
 > 命令为一能力一命令:`social-neuron-subscription <action> --flags`(无子命令层)。
 > **取值写法**:标量直接写(`--size 20`);**数组和对象一律写成一个 JSON 串**,与 MCP/HTTP 入参完全同形:`--platforms '["video"]'`、`--where '{...}'`。数组**不能**用逗号分隔,单个取值也要写成数组(`'["video"]'` 而不是 `video`)。
 
+系统字段 `_id`（唯一ID）始终自动输出；`fields` 仅填写 selectable=true 的业务字段，
+禁止填写 `_id`，也不能用 `_id` 作 top 排序。
+
 ## 怎么用(操作手册)
 
 这是**异步导出**:创建 job → 系统按 cron 或你手动触发 → 产出 task → **轮询 task 拿文件 url**。
@@ -26,6 +29,7 @@ metadata:
 |---|---|---|
 | `list[...]` / 对象 | **JSON 串**(和 MCP 入参同形),**单个取值也要写成数组** | `--source '["小红书"]'`、`--rule-ids '["r1","r2"]'`、`--target '{...}'` |
 | `string` / `integer` | **直接写值**,不要加方括号 | `--field kw_docType`、`--keyword 品牌`、`--name 每日舆情`、`--size 1000` |
+| `boolean` | 明确写 `true` 或 `false` | `--confirmed true`；不能只写 `--confirmed` |
 
 数组不能用逗号分隔。JSON 写坏报 `BAD_JSON` 并回显原值;给标量 flag 套上方括号(如
 `--field '["kw_docType"]'`)不会报格式错 —— 它会被**原样当成字段名**去查,最后报"没有这个字段",
@@ -40,21 +44,82 @@ metadata:
 
 ### 三、标准流程
 
-```
-list-sites / list-fields  → 先对齐 --source 与 --fields 的合法取值(见四)
-job-create                → 拿到 job_id
-job-trigger               → 立刻跑一次(不等 cron);返回 task_id
-task-list                 → 轮询该 task,status 变终态后读 file_info 里的下载 url
-```
+先区分取数模式，再选择对应流程：
+
+| 模式 | 创建/修改流程 | 数量限制 |
+|---|---|---|
+| 普通批量（不传 top） | 可先独立预检，也可直接提交；命中数据超量时询问是否继续 | 默认最多 50 万行；确认后仍按上限截断 |
+| TopN（传 top） | 沿用原有创建/修改流程，不新增命中量预检或超量确认 | size 默认 1000、最大 10000；超过最大量直接拒绝，confirmed 不能放行 |
+
+**下面的可选预检与确认流程针对普通批量。创建或修改取数配置前，先说明可以选择预检，
+以及做与不做的区别。独立预检不是必选步骤，用户已有选择时直接按其选择执行。**
+
+| 选择 | 调用方式 | 用户何时知道是否超量 |
+|---|---|---|
+| 先预检 | 调用只读 `precheck`，查看命中量、范围与导出上限，再创建或修改 | 保存前就能知道是否超量；超量时先提示调整参数或询问是否继续 |
+| 不单独预检 | 直接调用 `job-create` / `job-update`，默认 confirmed=false | 正式提交时由服务端内部检查；超量则拒绝保存，再提示调整参数或询问是否继续 |
 
-建 job 时先想清楚:同样的筛选条件,要**全部命中的数据**,还是**只要排在前面的若干条**。
-默认是全部;用户明确限定了条数(「只要 1000 条」「按点赞取前 500」「挑互动最多的那批」)
-才加 `--top`(见七,两种模式的 size 上限与多规则语义都不同)。
+两条路径的保存条件和导出上限相同。跳过独立预检不会跳过服务端内部检查，也不表示同意超限处理。
 
-到这里订阅就做完了。**码值换中文不在这条流程里** —— 只有用户明确要求时才做,见六。
+```
+准备普通批量创建参数 / 局部修改参数，必要时用 list-sites / list-fields 对齐合法取值
+  ↓
+创建或修改前说明可选预检及上述区别，按用户选择走：
+  ├─ 先预检 → precheck(create/update)
+  │            ├─ 未超量 → 提交 job-create / job-update，confirmed=false
+  │            └─ 超量 → 展示数量与上限，提示调整参数或询问是否继续
+  │                       ├─ 调整参数 → 按新参数重新预检或直接提交，confirmed=false
+  │                       └─ 明确确认接受超限规则 → 提交同一份业务参数，confirmed=true
+  └─ 不单独预检 → 直接提交 job-create / job-update，confirmed=false
+                   ├─ 未超量 → 保存成功
+                   └─ 超量拒绝 → 提示调整参数或询问是否继续，确认后以 true 重提
+  ↓
+job-create / job-update 成功 → 拿到 job_id / 更新后的 job
+  ↓
+需要立刻跑一次时 job-trigger → 返回 task_id
+  ↓
+task-list → 轮询到终态后，读取 file_info 中的下载 url
+```
 
-改配置用 `job-update`(只传要改的字段);不想再跑就 `job-update --active false`,
-彻底不要才 `job-delete`。
+先预检且用户已确认超量时，可以直接带 confirmed=true 正式提交，不需要先提交一次 false 再问一遍。
+服务端正式保存仍重新检查；预检结果不是保存成功，也不保证未来执行量。
+
+预检命令：
+- 创建前：`precheck --operation create --create '{完整创建参数}'`。
+- 修改前：`precheck --operation update --update '{"job_id":1001,"rule_ids":["12345"]}'`。
+
+创建时先明确要批量命中数据还是按排序取前 N 条；只有用户明确要求后者才加 `--top`（见七）。
+TopN 维持原样，不进入本次数据量预检确认流程。
+修改用 `job-update`，只传要改的字段；仅改名称、频率、投递或启停无需数据量预检。
+不想再跑用 `job-update --active false`，彻底不要用 `job-delete`。
+码值换中文仅在用户明确要求时处理，见六。
+
+### 超量预检与确认
+
+普通批量创建，以及修改规则、站点、时间范围、导出数量或切回批量时，服务端检查当前窗口的命中量。
+默认 `confirmed=false`：超量则本次不创建、不保存修改。告诉用户命中量和导出上限，建议调整参数缩小范围；
+只有用户明确确认继续、接受系统超限处理规则后，才使用同一份业务参数加 `--confirmed true` 提交或重提。
+`-y` 是 CLI 写操作确认，不代替用户对本次数据超量的确认，不能据此自动设置 confirmed。
+确认后仍重新检查，实际导出按保存的 size 截断；参数、权限、统计失败不能放行。
+拿到成功响应前，不宣称已经创建/修改成功，不继续触发该次新建 job。
+
+按业务码处理：
+- `42223`（数据量超量待确认）：读取 CLI 的 `error.data.precheck`，展示命中数量、有效导出上限与
+  `windows` 的三个时间维度；REST 对应 `data.precheck`，MCP 错误附加文本块为 `{code,data}` JSON。
+  询问用户是调整参数，还是确认继续并接受系统超限规则。等待明确选择，不自动加 confirmed 重试。
+- `42224`（size 超过系统上限）：依据 `system_limit` 请用户调整 size；confirmed=true 无法放行。
+- `50332`（统计失败）：说明本次未保存，按错误处理；不作为超量确认处理。
+- 成功响应的 `warnings` 非空时，把截断提醒告知用户；不要声称已导出全部命中数据。
+
+用户提示示例：“当前至少命中 500001 条，单次最多导出 500000 条。可以调整规则、站点或时间范围
+缩小数据量，也可以确认继续，接受系统按上限截断处理。你希望调整参数还是继续？”
+不要把一次确认视为后续所有订阅、所有修改或参数变化后的确认。
+修改仍只传要改的字段；参数改变后重新以 confirmed=false 提交。
+只改名称、频率、投递、启停不新增统计；TopN、手动触发及自动执行维持原样。
+
+独立预检不会创建 job/task、占配额或触发执行；超量时只返回预览结果，不保存、不执行。
+`count_relation=gte` 表示“至少”命中，不是精确总量。三个时间维度见 windows。
+预检只反映当前窗口，不代表未来每次执行量。
 
 ### 四、建 job 前先对齐取值(站点 / 字段)
 
@@ -127,7 +192,7 @@ social-neuron-subscription get-field-values --field kw_tag_brand --keyword 兰
 | | 默认(不传 `--top`) | 传 `--top` |
 |---|---|---|
 | 给什么 | 命中条件的**全部**数据 | 同一批命中里,排序后的**前 N 条** |
-| `--size` | 默认/最大 **50 万**,到顶截断 | 默认 **1000**、最大 **10000** |
+| `--size` | 默认/最大 **50 万**，到顶截断 | 默认 **1000**、最大 **10000** |
 | 多条规则 | **各规则分别拉、结果拼接** | **OR 合并:命中任一规则即可** |
 | 同时命中多条规则的数据 | **出现多次**(每条规则各一份) | **只出现一次** |
 | 导出的 `kw_ruleId` | `["r1"]`(该份属哪条规则) | `["r1","r2"]`(命中的全部规则) |
@@ -187,7 +252,7 @@ json 格式下就是 JSON 数组;csv / excel 下这一列落成紧凑 JSON 字
 ### 九、容易踩的
 
 - **拉不到数据就不会有文件**,`file_info` 里也就没有 url —— 这不是失败,是没命中。
-- 单次导出 `--size`:默认模式下默认且最大 **50 万行**;传了 `--top` 则默认 **1000**、最大 **10000**,超出报错。
+- 普通批量 `--size` 默认/最大 **50 万行**，超限按服务端提示处理；传了 `--top` 则默认 **1000**、最大 **10000**,超出报错。
 - 每个 token 生效的 job 默认 **≤10 个**,满了要先 `job-delete` 或停用。
 - `--source` 只能填**已配置站点的中文名**(用 `list-sites` 查);写 `douyin.com` 这类域名会被拒。
 - 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
@@ -197,7 +262,7 @@ json 格式下就是 JSON 数组;csv / excel 下这一列落成紧凑 JSON 字
 
 ## 示例
 
-### 建一个每天跑的订阅,并立刻先跑一次看看
+### 选择不单独预检：直接创建，成功后手动跑一次
 
 ```bash
 # 1) 先看有哪些站点可订阅(--source 填的是中文站点名)
@@ -215,7 +280,50 @@ social-neuron-subscription job-create --name 每日舆情 \
 social-neuron-subscription job-trigger --job-id 1001 -y
 ```
 
-> 站点与字段先查后填,别凭感觉写。写操作要加 -y;job-trigger 返回 task_id,拿它去轮询。
+> 站点与字段先查后填。job-create 成功才继续触发；若返回 42223，先取得用户超量确认再重提。-y 不代表超量确认；job-trigger 返回 task_id，拿它轮询。
+
+### 选择先预检：保存前了解数据量，超量先征求确认
+
+```bash
+# 用户选择先预检：此时只预览，不创建订阅
+social-neuron-subscription precheck --operation create --create '{"name":"每日舆情","rule_ids":["12345"],"source":["微博"],"published":"T-7~T-1","frequency":"每天9点"}'
+
+# 若 would_truncate=true，展示数量和上限，询问是否继续；仅在用户明确确认接受超限规则后执行
+social-neuron-subscription job-create --name 每日舆情 --rule-ids '["12345"]' --source '["微博"]' --published 'T-7~T-1' --frequency '每天9点' --confirmed true -y
+
+# 修改也可先预检；后续仍只提交相同的局部修改参数
+social-neuron-subscription precheck --operation update --update '{"job_id":1001,"rule_ids":["67890"]}'
+```
+
+> 预检未超量时直接以 confirmed=false（或省略）保存；不选择独立预检时直接正式提交，服务端仍会检查。超量已明确确认后可直接 true 保存，不必先 false 再重复确认。
+
+### 普通批量创建超量：用户明确确认后重提
+
+```bash
+# 首次提交默认 confirmed=false；若返回 42223，本次没有创建 job
+social-neuron-subscription job-create --name 每日舆情 \
+  --rule-ids '["12345"]' --source '["微博"]' \
+  --published 'T-7~T-1' --frequency '每天9点' -y
+
+# 展示 error.data.precheck 的数量、窗口和上限，等用户明确确认继续并接受截断规则后，才执行：
+social-neuron-subscription job-create --name 每日舆情 \
+  --rule-ids '["12345"]' --source '["微博"]' \
+  --published 'T-7~T-1' --frequency '每天9点' --confirmed true -y
+```
+
+> 两次业务参数相同，只增加 confirmed=true；用户选择调整参数时重新以 false 提交。确认允许保存，不提高导出上限；只有成功返回后才能宣称创建完成。
+
+### 修改规则超量：保留局部修改参数确认重提
+
+```bash
+# 修改后的完整配置由服务端合并检查；超量拒绝时原 job 不变
+social-neuron-subscription job-update --job-id 1001 --rule-ids '["67890"]' -y
+
+# 仅在用户明确确认接受系统超限规则后重提，无需补全整个 job
+social-neuron-subscription job-update --job-id 1001 --rule-ids '["67890"]' --confirmed true -y
+```
+
+> 只改名称、频率、投递或启停不新增统计；TopN 保持原样。显式 size 或继承 size 超过当前系统上限时，必须调整 size，不能靠 confirmed 放行。
 
 ### 轮询拿下载地址
 
@@ -310,6 +418,7 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 | flag | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
+| --confirmed | confirmed | boolean | 否 | - | 是否已确认继续并同意系统超限处理规则；超量时默认拒绝，true 允许保存但仍按上限截断；不跳过其他校验，不保存到 job，TopN 不适用 |
 | --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 个;只能取已配置站点 |
@@ -317,8 +426,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --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 | 每次执行最多导出的记录行数。省略则按模式取默认:取全部命中 500,000(同时是上限);传了 top(只取前 N 条)则默认 1,000、上限 10,000 |
+| --fields | fields | list[string] | 否 | minLen=1 | _id 自动输出，禁止在 fields 中填写；拉取/导出字段;不填拉全量 |
+| --size | size | integer | 否 | min=1, max=2147483647 | 每次执行最多导出的记录行数。省略则按模式取默认:普通批量默认最多 500000 条，实际以服务端当前约束为准;传了 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、无法区分来源规则 |
 
@@ -345,10 +454,10 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
 | type | string | 是 | - | 固定 sftp |
-| host | string | 是 | - | SFTP 主机 |
-| port | integer | 否 | - | 端口,默认 22 |
-| username | string | 是 | - | 登录用户名 |
-| password | string | 是 | - | 登录密码 |
+| host | string | 是 | minLen=1 | SFTP 主机,不能为空白 |
+| port | integer | 否 | min=1, max=65535 | 端口,1–65535,默认 22 |
+| username | string | 是 | minLen=1 | 登录用户名,不能为空白 |
+| password | string | 是 | minLen=1 | 登录密码,不能为空白,保留首尾空格 |
 | 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) |
@@ -364,6 +473,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
+| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
+| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
 | job_id | integer | 是 | - | job ID |
 | name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
@@ -371,8 +482,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
-| fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
 | top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
@@ -382,6 +493,20 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | created_at | string | 是 | - | 创建时间(ISO8601,UTC+8) |
 | updated_at | string | 是 | - | 更新时间(ISO8601,UTC+8) |
 
+**对象 `PrecheckResult`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| checked_at | string | 是 | - | 检查时间，东八区 ISO 时间 |
+| windows | object | 是 | - | 发布时间、入库时间、更新时间三个维度的绝对闭区间；空表示不过滤 |
+| matched_rows | integer | 是 | - | 命中行数；count_relation=gte 时为下界，非精确总量 |
+| count_relation | enum(eq、gte) | 是 | - | eq=精确计数；gte=至少命中该数量 |
+| system_limit | integer | 是 | - | 普通批量的系统导出上限；TopN 未执行预检时为空 |
+| effective_limit | integer | 是 | - | 本次生效的单次最大导出行数 |
+| would_truncate | boolean | 是 | - | 当前统计是否超出有效导出数量；TopN 不新增预检 |
+| checked | boolean | 否 | - | 是否执行数据量统计；TopN 为 false |
+| message | string | 是 | - | 数量提示及调整参数或确认继续的说明 |
+
 示例:social-neuron-subscription job-create --name <v> --rule-ids '["a","b"]' --source '["a","b"]' --published <v> --frequency <v>
 
 ### social-neuron-subscription job-delete
@@ -422,6 +547,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
+| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
+| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
 | job_id | integer | 是 | - | job ID |
 | name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
@@ -429,8 +556,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
-| fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
 | top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
@@ -462,7 +589,7 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --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 |
+| --size | size | integer | 否 | min=1, max=2147483647 | 覆盖本次导出行数；不传继承 job.size 并按系统当前上限收紧，显式超限拒绝 |
 
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
 
@@ -487,10 +614,10 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
 | type | string | 是 | - | 固定 sftp |
-| host | string | 是 | - | SFTP 主机 |
-| port | integer | 否 | - | 端口,默认 22 |
-| username | string | 是 | - | 登录用户名 |
-| password | string | 是 | - | 登录密码 |
+| host | string | 是 | minLen=1 | SFTP 主机,不能为空白 |
+| port | integer | 否 | min=1, max=65535 | 端口,1–65535,默认 22 |
+| username | string | 是 | minLen=1 | 登录用户名,不能为空白 |
+| password | string | 是 | minLen=1 | 登录密码,不能为空白,保留首尾空格 |
 | 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) |
@@ -511,6 +638,7 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 | flag | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
+| --confirmed | confirmed | boolean | 否 | - | 是否已确认继续并同意系统超限处理规则；修改取数配置超量时默认拒绝，true 允许保存但仍按上限截断；仅本次有效，TopN 不适用 |
 | --job-id | job_id | integer | 是 | - | 目标 job |
 | --name | name | string | 否 | minLen=1, maxLen=128 | 新名称(同一凭证下唯一) |
 | --rule-ids | rule_ids | list[string] | 否 | minItems=1, minLen=1 | 整组全量覆盖 |
@@ -518,8 +646,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | --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 |
+| --fields | fields | list[string] | 否 | minLen=1 | 业务字段整组全量覆盖；_id 自动输出，禁止在 fields 中填写 |
+| --size | size | integer | 否 | min=1, max=2147483647 | 每次执行最多导出的记录行数；不传则不修改，普通批量默认上限 500000，TopN 默认上限 10000，实际以上游返回约束为准 |
 | --frequency | frequency | string | 否 | minLen=1, maxLen=64 | 传入则按新频率重算 cron(用法同创建;支持一天多次,如「每天9点和15点」);无法解析为 cron 会被拒绝 |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 整体替换投递目标 |
 | --top | top | list[TopSpec] | 否 | - | 只取前 N 条的排序规格:传入则整组替换,不传则不修改。切到该模式后 size 最大 10,000;传空数组 [] 表示改回「给全部命中数据」 |
@@ -548,10 +676,10 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
 | type | string | 是 | - | 固定 sftp |
-| host | string | 是 | - | SFTP 主机 |
-| port | integer | 否 | - | 端口,默认 22 |
-| username | string | 是 | - | 登录用户名 |
-| password | string | 是 | - | 登录密码 |
+| host | string | 是 | minLen=1 | SFTP 主机,不能为空白 |
+| port | integer | 否 | min=1, max=65535 | 端口,1–65535,默认 22 |
+| username | string | 是 | minLen=1 | 登录用户名,不能为空白 |
+| password | string | 是 | minLen=1 | 登录密码,不能为空白,保留首尾空格 |
 | 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) |
@@ -567,6 +695,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 | 字段 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
+| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
+| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
 | job_id | integer | 是 | - | job ID |
 | name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
 | rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
@@ -574,8 +704,8 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
 | idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
-| fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
-| size | integer | 是 | - | 每次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
 | top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
@@ -585,6 +715,20 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | created_at | string | 是 | - | 创建时间(ISO8601,UTC+8) |
 | updated_at | string | 是 | - | 更新时间(ISO8601,UTC+8) |
 
+**对象 `PrecheckResult`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| checked_at | string | 是 | - | 检查时间，东八区 ISO 时间 |
+| windows | object | 是 | - | 发布时间、入库时间、更新时间三个维度的绝对闭区间；空表示不过滤 |
+| matched_rows | integer | 是 | - | 命中行数；count_relation=gte 时为下界，非精确总量 |
+| count_relation | enum(eq、gte) | 是 | - | eq=精确计数；gte=至少命中该数量 |
+| system_limit | integer | 是 | - | 普通批量的系统导出上限；TopN 未执行预检时为空 |
+| effective_limit | integer | 是 | - | 本次生效的单次最大导出行数 |
+| would_truncate | boolean | 是 | - | 当前统计是否超出有效导出数量；TopN 不新增预检 |
+| checked | boolean | 否 | - | 是否执行数据量统计；TopN 为 false |
+| message | string | 是 | - | 数量提示及调整参数或确认继续的说明 |
+
 示例:social-neuron-subscription job-update --job-id <v>
 
 ### social-neuron-subscription list-fields
@@ -607,11 +751,13 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 | items | list[SubField] | 是 | - | 字段列表(所选站点的并集,按 name_en 排序) |
 | total | integer | 是 | - | 字段总数 |
 
-**对象 `SubField`** —— 一个可导出字段(**订阅口径**:只给填 ``fields`` 与翻译列值要用的信息)。
+**对象 `SubField`** —— 一个字段的订阅口径描述；selectable 区分可选业务字段与自动输出的系统字段。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| name_en | string | 是 | - | 字段标识(ES 字段名),即 job_create / job_update 的 fields 该填的值 |
+| name_en | string | 是 | - | 字段标识(ES 字段名),仅 selectable=true 时可填入 job_create / job_update 的 fields |
+| field_origin | string | 否 | - | 字段来源：source 为业务字段，system 为系统字段 |
+| selectable | boolean | 否 | - | 是否允许填入 fields；_id 自动输出，不可填写 |
 | name | string | 是 | - | 字段中文名 —— 把用户说法对齐到 name_en 用 |
 | data_type | string | 是 | - | 语义类型:keyword / text / long / double / date / boolean / object / nested |
 | description | string | 否 | - | 字段描述;元数据未登记描述时为空串 |
@@ -637,6 +783,69 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 
 示例:social-neuron-subscription list-sites
 
+### social-neuron-subscription precheck
+可选预览订阅创建/修改的数据量；正式保存会重新检查，TopN 保持原样。
+
+**入参**
+
+| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| --operation | operation | enum(create、update) | 是 | - | 预览操作：create 创建或 update 修改 |
+| --create | create | SubJobCreateInput | 否 | - | 创建业务参数；仅 operation=create 时传入，confirmed 不影响预览 |
+| --update | update | SubJobUpdateInput | 否 | - | 本人 job_id 和局部修改参数；仅 operation=update 时传入，confirmed 不影响预览 |
+
+**对象 `SubJobCreateInput`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| confirmed | boolean | 否 | - | 是否已确认继续并同意系统超限处理规则；超量时默认拒绝，true 允许保存但仍按上限截断；不跳过其他校验，不保存到 job，TopN 不适用 |
+| name | string | 是 | minLen=1, maxLen=128 | job 名称,同一凭证(token)下唯一 |
+| rule_ids | list[string] | 是 | minItems=1, minLen=1 | 魔方规则ID数组,至少 1 个 |
+| source | list[string] | 是 | minItems=1, minLen=1 | 站点数组,至少 1 个;只能取已配置站点 |
+| 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 | 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 | 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 | string | 是 | minLen=1, maxLen=64 | 自然语言同步频率,系统转 cron(东八区)。可指定具体时间、并**支持一天多次**:如「每天9点」「每天9点和15点」(一天跑两次)「每周一9点」「每小时」「每30分钟」。无法解析为 cron 会被拒绝。 |
+| fields | list[string] | 否 | minLen=1 | _id 自动输出，禁止在 fields 中填写；拉取/导出字段;不填拉全量 |
+| size | integer | 否 | min=1, max=2147483647 | 每次执行最多导出的记录行数。省略则按模式取默认:普通批量默认最多 500000 条，实际以服务端当前约束为准;传了 top(只取前 N 条)则默认 1,000、上限 10,000 |
+| target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。 |
+| top | list[TopSpec] | 否 | - | 只取前 N 条(可选)。**不改变筛选条件** —— 省略时给命中条件的全部数据,传了则在同一批命中结果里按指定字段排序、只取前 size 条。排序跨发布窗内所有日期 / 站点 / 规则**全局生效**(不是每天各取 N)。多字段按顺序作排序优先级(前者相同时比后者)。字段必须是可排序类型(keyword / long / double / date)。该模式下 size 默认 1,000、最大 10,000;且多条规则改为 OR 合并并去重,导出的 kw_ruleId 恒为 topN、无法区分来源规则 |
+
+**对象 `SubJobUpdateInput`**
+
+| 键 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| confirmed | boolean | 否 | - | 是否已确认继续并同意系统超限处理规则；修改取数配置超量时默认拒绝，true 允许保存但仍按上限截断；仅本次有效，TopN 不适用 |
+| job_id | integer | 是 | - | 目标 job |
+| name | string | 否 | minLen=1, maxLen=128 | 新名称(同一凭证下唯一) |
+| rule_ids | list[string] | 否 | minItems=1, minLen=1 | 整组全量覆盖 |
+| source | list[string] | 否 | minItems=1, minLen=1 | 整组全量覆盖 |
+| 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 | 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 | 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 | list[string] | 否 | minLen=1 | 业务字段整组全量覆盖；_id 自动输出，禁止在 fields 中填写 |
+| size | integer | 否 | min=1, max=2147483647 | 每次执行最多导出的记录行数；不传则不修改，普通批量默认上限 500000，TopN 默认上限 10000，实际以上游返回约束为准 |
+| frequency | string | 否 | minLen=1, maxLen=64 | 传入则按新频率重算 cron(用法同创建;支持一天多次,如「每天9点和15点」);无法解析为 cron 会被拒绝 |
+| target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 整体替换投递目标 |
+| top | list[TopSpec] | 否 | - | 只取前 N 条的排序规格:传入则整组替换,不传则不修改。切到该模式后 size 最大 10,000;传空数组 [] 表示改回「给全部命中数据」 |
+| active | enum(0、1) | 否 | - | 启停:1 / 0 |
+
+**出参 `PrecheckResult`**
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|
+| checked_at | string | 是 | - | 检查时间，东八区 ISO 时间 |
+| windows | object | 是 | - | 发布时间、入库时间、更新时间三个维度的绝对闭区间；空表示不过滤 |
+| matched_rows | integer | 是 | - | 命中行数；count_relation=gte 时为下界，非精确总量 |
+| count_relation | enum(eq、gte) | 是 | - | eq=精确计数；gte=至少命中该数量 |
+| system_limit | integer | 是 | - | 普通批量的系统导出上限；TopN 未执行预检时为空 |
+| effective_limit | integer | 是 | - | 本次生效的单次最大导出行数 |
+| would_truncate | boolean | 是 | - | 当前统计是否超出有效导出数量；TopN 不新增预检 |
+| checked | boolean | 否 | - | 是否执行数据量统计；TopN 为 false |
+| message | string | 是 | - | 数量提示及调整参数或确认继续的说明 |
+
+示例:social-neuron-subscription precheck --operation create
+
 ### social-neuron-subscription task-list
 列出某本人 job 的执行 task(翻页),可按 task_id 查单条、status/创建时间过滤,按创建时间排序。
 
@@ -666,11 +875,11 @@ social-neuron-subscription job-update --job-id 1001 --active false -y
 |---|---|---|---|---|
 | task_id | integer | 是 | - | task ID |
 | job_id | integer | 是 | - | 所属 job |
-| size | integer | 是 | - | 本次执行最多导出的记录行数;取全部命中时上限 500000,只取前 N 条时上限 10000 |
+| size | integer | 是 | - | 本次任务记录的导出数量；实际执行受系统当前总量上限约束，TopN 默认上限 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 时给出;成功/进行中为空) |
+| error_msg | string | 否 | - | 对外可操作的失败提示;系统异常仅给通用提示,内部细节不返回 |
 | created_at | string | 是 | - | 创建时间 |
 | updated_at | string | 是 | - | 更新时间 |