---
name: social-neuron-subscription
description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task;普通批量创建/取数配置修改有数据量预检，可选 precheck 只读预览；超量先提示调整参数或征求用户确认，明确同意系统超限规则后才以 confirmed=true 重提，导出仍按上限截断；订阅范围二选一：热门站点用 source（list_source 返回的中文名，按已有配置确定范围）；指定平台站点用 platform_site（platform 取 list_platforms.name_en，sites 取 list_sites.value），适用于指定平台下站点、不同平台各自站点或整个平台，sites=["*"] 表示该平台全部站点；范围选择与是否 TopN 独立，两种范围均支持普通批量或 TopN。发现接口:list_source / list_platforms / list_sites 对齐范围，list_fields 对齐字段；原 list_sites 的热门站点列表已改名 list_source，新 list_sites 返回元数据站点对象；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: [] }
---
# social-neuron-subscription


> ⚠️ 本技能随该能力 CLI 版本更新。若刚升级过 CLI、重装过 skill,或调用返回 426(版本过旧需升级),请**重新加载本 SKILL.md 与 manifest** 再用——以最新文件为准。

> 命令为一能力一命令:`social-neuron-subscription <action> --flags`(无子命令层)。
> **取值写法**:标量直接写(`--size 20`);**数组和对象一律写成一个 JSON 串**,与 MCP/HTTP 入参完全同形:`--platforms '["video"]'`、`--where '{...}'`。数组**不能**用逗号分隔,单个取值也要写成数组(`'["video"]'` 而不是 `video`)。

参与索引定位的 platform 禁止包含 `*`（包括前后缀通配），必须使用 list-platforms 返回的具体 name_en。全平台订阅须显式列出全部平台的 platform_site 组合；每个平台的 sites=["*"] 仍表示该平台全部站点。

系统字段 `_id`（唯一ID）始终自动输出；`fields` 仅填写 selectable=true 的业务字段，
禁止填写 `_id`，也不能用 `_id` 作 top 排序。

## 怎么用(操作手册)

这是**异步导出**:创建 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` |
| `boolean` | 明确写 `true` 或 `false` | `--confirmed true`；不能只写 `--confirmed` |

数组不能用逗号分隔。JSON 写坏报 `BAD_JSON` 并回显原值;给标量 flag 套上方括号(如
`--field '["kw_docType"]'`)不会报格式错 —— 它会被**原样当成字段名**去查,最后报"没有这个字段",
所以这类错看起来会很迷惑,写的时候对一下参数表的类型列。

### 二、两个概念

| | 是什么 | 谁创建 |
|---|---|---|
| **job** | 订阅定义:数据范围 + 频率 + 投递方式 | 你 `job-create` |
| **task** | job 的**一次执行**,产物和下载地址落在 `file_info` | 系统按 cron,或你 `job-trigger` |

### 三、标准流程

先区分取数模式，再选择对应流程：

| 模式 | 创建/修改流程 | 数量限制 |
|---|---|---|
| 普通批量（不传 top） | 可先独立预检，也可直接提交；命中数据超量时询问是否继续 | 默认最多 50 万行；确认后仍按上限截断 |
| TopN（传 top） | 沿用原有创建/修改流程，不新增命中量预检或超量确认 | size 默认 1000、最大 10000；超过最大量直接拒绝，confirmed 不能放行 |

**下面的可选预检与确认流程针对普通批量。创建或修改取数配置前，先说明可以选择预检，
以及做与不做的区别。独立预检不是必选步骤，用户已有选择时直接按其选择执行。**

| 选择 | 调用方式 | 用户何时知道是否超量 |
|---|---|---|
| 先预检 | 调用只读 `precheck`，查看命中量、范围与导出上限，再创建或修改 | 保存前就能知道是否超量；超量时先提示调整参数或询问是否继续 |
| 不单独预检 | 直接调用 `job-create` / `job-update`，默认 confirmed=false | 正式提交时由服务端内部检查；超量则拒绝保存，再提示调整参数或询问是否继续 |

两条路径的保存条件和导出上限相同。跳过独立预检不会跳过服务端内部检查，也不表示同意超限处理。

```
准备普通批量创建参数 / 局部修改参数，必要时用 list-source / 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
```

先预检且用户已确认超量时，可以直接带 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 无法放行。
- `42225`（预检 ES 查询超时）：本次未保存；可能是当前 ES 负载较高，建议稍后重试；若持续超时，再减少规则数量、缩小时间窗口、减少站点数量或简化规则后重试，不能用 confirmed 绕过。
- `50332`（统计失败）：说明本次未保存，按错误处理；不作为超量确认处理。
- 成功响应的 `warnings` 非空时，把截断提醒告知用户；不要声称已导出全部命中数据。

用户提示示例：“当前至少命中 500001 条，单次最多导出 500000 条。可以调整规则、站点或时间范围
缩小数据量，也可以确认继续，接受系统按上限截断处理。你希望调整参数还是继续？”
不要把一次确认视为后续所有订阅、所有修改或参数变化后的确认。
修改仍只传要改的字段；参数改变后重新以 confirmed=false 提交。
只改名称、频率、投递、启停不新增统计；TopN、手动触发及自动执行维持原样。

独立预检不会创建 job/task、占配额或触发执行；超量时只返回预览结果，不保存、不执行。
`count_relation=gte` 表示“至少”命中，不是精确总量。三个时间维度见 windows。
预检只反映当前窗口，不代表未来每次执行量。

### 四、选择订阅范围：热门站点 / 指定平台站点

先按用户需要的订阅范围选择参数，再查询对应的合法取值：

| 使用场景 | 选择参数 | 行为 |
|---|---|---|
| 热门站点：用户要订阅已配置的常用站点，如抖音、微博，不需要指定平台归属 | `source` | 按中文热门站点名选择，平台与实际站点范围由已有配置确定 |
| 指定平台站点：用户明确指定某个平台下的站点、不同平台各自的站点，或整个平台；需要选择热门站点列表以外的站点 | `platform_site` | 每组明确绑定平台编码与站点编码，可分别指定多个平台的站点范围 |

例如“订阅抖音和微博”可先查 list-source，使用 source；“订阅新闻平台中的腾讯站点”使用
platform_site；“订阅新闻整个平台”也使用 platform_site，并显式填写 sites=["*"]。
热门站点模式仅限 list-source 中已有配置的站点；指定平台站点模式从元数据查询平台和站点。
不要仅凭中文站点名猜测平台编码，也不要把不同平台的站点合并成没有对应关系的平铺数组。

**范围选择与 TopN 是两个独立选择**：source / platform_site 决定从哪里取；top 决定命中后
是否只取排序前 N 条。两种范围均可用于普通批量或 TopN。“热门站点”指已配置的常用站点，
不表示热门内容、热搜榜或按互动量排序；用户未要求排序前 N 条时，不自动添加 top。

创建时 `source` 与 `platform_site` 必须且只能提供一种。旧调用和历史 job 的 source 含义不变。

| 模式 | 发现命令 | 参数取值 |
|---|---|---|
| 热门站点 | `list-source` | 中文站点名原样填顶层 `--source` |
| 指定平台站点 | `list-platforms`，`list-sites --keyword 腾讯` | 平台 name_en 填 platform_site[].platform；站点 value 填 platform_site[].sites |
| 导出字段 | `list-fields`，传与 job 相同的 source 或 platform_site | name_en 填 fields；仅 selectable=true 的业务字段可选 |

**历史接口变化**：原 `list-sites`（返回中文热门站点数组）已改名 `list-source`；
新的 `list-sites` 返回元数据站点对象 name/value/is_key_site，value 是站点编码，不是中文名。
旧调用方获取热门站点时必须改调 list-source；已有 source 创建请求不需要改动。

平台站点示例：`--platform-site '[{"platform":"news","sites":["toutiao.com","qq.com"]}]'`。
每组平台与站点绑定，多组 OR 合并；平台和站点的实际归属由服务端校验。
整个平台显式传 `"sites":["*"]`，不能混入具体站点；不接受空数组或省略 sites。
list-sites 是全局站点目录，不带平台归属，不能把站点搜索命中当成属于任意平台的证明。
站点目录可能有数万条，优先传 keyword 搜索，不拉全量作为输入枚举。

顶层 source 只接受 list-source 的中文热门站点名，不能填写 list-sites.value。
更新不传范围则保持原模式；传 source 或 platform_site 即整体替换范围并切换模式，不能同时传。
字段近千，按需用 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。

### 附加过滤条件

每条订阅可用 `--where` 配置条件树。`and` 和 `or` 接收子条件数组，`not` 接收一个子条件，支持嵌套。
叶子使用 `field`、`op` 和 `value`，字段和值可通过 `list-fields` 与 `get-field-values` 查询。
附加条件与魔方规则、站点、时间同时生效。以下示例筛选帖子，情感为正面或中性。

```bash
social-neuron-subscription job-update --job-id <job_id> \
  --where '{"and":[{"field":"kw_docType","op":"eq","value":"1"},{"or":[{"field":"kw_commonSentimentV2","op":"eq","value":"正面"},{"field":"kw_commonSentimentV2","op":"eq","value":"中性"}]}]}' -y
```

更新时省略 `--where` 会保留已有条件，传 `--where null` 可清除。预检时在 `--create` 或 `--update` 的 JSON 对象里填 `where`。

### 六、(可选)用户明确要求把码值换成中文时

**默认不做翻译**:导出文件按大库原值交付,`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`
> 现查为准**,不要把这里的示例当权威映射。

### 七、两种取数模式:全部命中 vs 取前 N 条

**默认取全部命中的数据**(不传 `--top`)。`--top` **不改变筛选条件**,只是在同一批命中结果里
按某字段排序、只取前 N 条 —— 用户明确限定了条数时才用。

> 这不是"榜单数据" —— 跟平台自己的热搜榜/热门榜没有关系,数据源与筛选条件完全不变,
> 变的只是"给你全部"还是"给你排在前面的那几条"。

| | 默认(不传 `--top`) | 传 `--top` |
|---|---|---|
| 给什么 | 命中条件的**全部**数据 | 同一批命中里,排序后的**前 N 条** |
| `--size` | 默认/最大 **50 万**，到顶截断 | 默认 **1000**、最大 **10000** |
| 多条规则 | **各规则分别拉、结果拼接** | **OR 合并:命中任一规则即可** |
| 同时命中多条规则的数据 | **出现多次**(每条规则各一份) | **只出现一次** |
| 导出的 `kw_ruleId` | `["r1"]`(该份属哪条规则) | `["r1","r2"]`(命中的全部规则) |
| 取不满 size | 正常,有多少给多少 | 正常,说明命中数本来就少 |

排序**全局有效**:跨发布窗内所有日期、所有站点、所有规则排完再取前 N —— 不是每天各取 N,
也不是每个站点各取 N。

```bash
# 近 7 天抖音命中该规则的数据里,按点赞数取最高的 1000 条
social-neuron-subscription job-create --name 抖音高互动采样   --rule-ids '["12345"]' --source '["抖音"]' --published 'T-7~T-1'   --top '[{"field":"long_likeCount","order":"desc"}]' --size 1000   --frequency '每天早上8点' -y
```

`--top` 是 JSON 数组,多个字段按顺序作排序优先级(前者相同时比后者):

```bash
--top '[{"field":"long_likeCount","order":"desc"},{"field":"date_publishedAt","order":"desc"}]'
# 先按点赞降序;点赞一样多的,新的排前面
```

**排序字段有类型限制** —— 只能用 `list-fields` 里 `data_type` 为
`keyword` / `long` / `double` / `date` 的字段。`text`(正文这类分词字段)、`boolean`、
`object`、`nested` 建 job 时直接拒。`order` 省略默认 `desc`。

**字段名必须现查**(`list-fields --source '[...]' --keyword 赞`)—— 各站点字段不同,
上面示例里的 `long_likeCount` 是小红书实查到的点赞数字段,别凭印象写 `kw_likeCount`
这类名字,那会在建 job 时报"字段不存在"。

**导出文件按排序顺序输出**:第一行即第 1 名。

想改回取全部:`job-update --top '[]'`。

**为什么取前 N 条的 size 反而小这么多**:它要让搜索引擎在全部索引上做一次全局排序,
深度排序的开销随 N 线性涨,默认那个 50 万放上去会拖垮集群。真要大批量高互动数据,
用默认模式 + 在魔方规则里加互动量阈值过滤,比用 `--top` 取 50 万健康得多。

### 八、导出文件里的 `kw_ruleId`(⚠️ 契约已变更)

导出的每条数据除了业务字段,还带一个 `kw_ruleId`,标明这条数据是被**哪条魔方规则**命中的。

> ⚠️ **它现在恒为数组**。此前是字符串(`"12345"`),现已统一成数组(`["12345"]`) ——
> 两种取数模式同形。按老格式解析的下游(直接当字符串比较 / 拼接 / 分组)**必须改**,
> 否则会拿到 `['12345']` 这样的字面量或整串 JSON。

```jsonc
// 默认模式:一片一规则,所以恒为单元素
{"_id": "abc", "kw_ruleId": ["12345"], "_source": {...}}

// 传了 --top:OR 合并,同时命中多条规则的数据只出一份,但把命中的都记下
{"_id": "abc", "kw_ruleId": ["12345", "67890"], "_source": {...}}
{"_id": "def", "kw_ruleId": ["67890"],          "_source": {...}}
```

json 格式下就是 JSON 数组;csv / excel 下这一列落成紧凑 JSON 字符串(如 `["12345"]`),
按需自行解析。

### 九、容易踩的

- **拉不到数据就不会有文件**,`file_info` 里也就没有 url —— 这不是失败,是没命中。
- 普通批量 `--size` 默认/最大 **50 万行**，超限按服务端提示处理；传了 `--top` 则默认 **1000**、最大 **10000**,超出报错。
- 每个 token 生效的 job 默认 **≤10 个**,满了要先 `job-delete` 或停用。
- `--source` 只能填**已配置站点的中文名**(用 `list-source` 查);写 `douyin.com` 这类域名会被拒。
- 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
- 传了 `--top` 时同时命中多条规则的数据只出现一份(`kw_ruleId` 里列出全部命中的规则);
  不传时每条规则各出一份。按规则分组统计前先想清楚要哪种。
- `kw_ruleId` **恒为数组**(契约已变更,见八),别再当字符串用。

## 示例

### 热门站点：订阅已配置的抖音和微博

```bash
# 查询中文热门站点名，确认用户选择的站点在返回列表中
social-neuron-subscription list-source
social-neuron-subscription job-create --name 热门站点每日订阅 --rule-ids '["12345"]' --source '["抖音","微博"]' --published 'T-1~T-1' --frequency '每天9点' -y
```

> 使用 source，由已有站点配置确定平台及站点范围；不同时传 platform_site。这是普通批量订阅，不表示只取热门内容；超量按预检与用户确认流程处理。

### 指定平台站点：订阅新闻平台中的腾讯站点

```bash
# 平台 name_en 填 platform，站点 value 填 sites；实际归属由服务端校验
social-neuron-subscription list-platforms
social-neuron-subscription list-sites --keyword 腾讯
social-neuron-subscription list-fields --platform-site '[{"platform":"news","sites":["qq.com"]}]' --keyword 标题
social-neuron-subscription job-create --name 指定平台站点每日订阅 --rule-ids '["12345"]' --platform-site '[{"platform":"news","sites":["qq.com"]}]' --published 'T-1~T-1' --frequency '每天9点' -y
```

> 使用 platform_site，不同时传 source；整个平台改为 sites=["*"]。多个平台分别写一组，保留各自的站点对应关系。同样支持普通批量或 TopN；只有用户要求排序前 N 条时才加 top，普通批量超量按确认流程处理。

### 选择不单独预检：直接创建，成功后手动跑一次

```bash
# 1) 先看有哪些站点可订阅(--source 填的是中文站点名)
social-neuron-subscription list-source

# 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
```

> 站点与字段先查后填。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 放行。

### 轮询拿下载地址

```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 相同(如情感标签)就无需转换。

### 只要符合条件的前 N 条(按指定字段排序)

```bash
# 传了 --top 就从「给全部命中数据」改成「只给排序后的前 N 条」,筛选条件不变
social-neuron-subscription job-create --name 抖音高互动采样 \
  --rule-ids '["12345"]' --source '["抖音"]' --published 'T-7~T-1' \
  --top '[{"field":"long_likeCount","order":"desc"}]' --size 1000 \
  --frequency '每天早上8点' -y
```

> 排序跨发布窗内所有日期/站点/规则全局生效,不是每天各取 1000。排序字段只能是 keyword/long/double/date(用 list-fields 看 data_type);size 最大 10000。多规则在这个模式下是 OR 合并:同时命中多条的数据只出一份,kw_ruleId 里列出命中的全部规则。与平台自己的热搜/热门榜无关,数据源和筛选条件都没变。

### 临时停用一个订阅(保留定义)

```bash
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。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --source | source | list[string] | 否 | minItems=1, minLen=1 | 历史热门站点中文名数组，取 list_source；与 platform_site 必须二选一 |
| --platform-site | platform_site | list[PlatformSite] | 否 | minItems=1 | 元数据平台站点组合；platform 取 list_platforms.name_en，sites 取 list_sites.value；与 source 二选一 |
| --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 个 |
| --where | where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，支持 and、or、not，与规则、站点和时间同时生效 |
| --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 | _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、无法区分来源规则 |

**对象 `AndNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 全部满足(编译为 bool.filter);至少 1 个条件 |

**对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 kafka |
| brokers | string | 是 | - | broker 列表(逗号分隔) |
| topic | string | 是 | - | 目标 topic |
| key_field | string | 否 | - | 作为消息 key 的字段名 |

**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;query_string 的 value 为表达式，其它操作传 ES 真实值。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
| op | enum(eq、in、query_string、gt、gte、lt、lte、exists) | 是 | - | _id 仅支持 eq/in；其他字段操作符;须在字段 data_type 允许集合内(§1.5) |
| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | query_string 必须传非空字符串(最多4096字符)：每个关键词用双引号包围，如 ("防晒" OR "隔离") AND "敏感肌"；短语后可写 ~N，如 "散热测试"~3。支持 AND/OR/NOT 和括号；禁止裸词、字段限定、通配符、正则。服务端原样传递表达式，固定 ik_smart；其它 op 传 ES 真实值，in 传数组，exists 无需 value。 |

**对象 `NotNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |

**对象 `OctoTarget`** —— octo(本期,默认):导出文件上传 octo 存储,产出 CDN 下载 url(写入 file_info.url)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 octo |
| format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |

**对象 `OrNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件 |

**对象 `PlatformSite`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| platform | string | 是 | minLen=1 | 具体平台编码，禁止包含 *，取 list_platforms 的 name_en；全平台须逐一列出平台组合 |
| sites | list[string] | 是 | minItems=1, minLen=1 | 站点编码数组，取 list_sites 的 value；["*"] 表示该平台全部站点，不可混用 |

**对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
重跑多少次,远端路径与文件名都不变。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 sftp |
| 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) |

**对象 `TopSpec`** —— 全局TopN排序规格(subscription专用)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | - | 排序字段(name_en);仅支持可排序类型(keyword/long/double/date) |
| order | enum(asc、desc) | 否 | - | 排序方向:desc降序(取最大的N个)/asc升序(取最小的N个) |

**出参 `SubJob`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
| job_id | integer | 是 | - | job ID |
| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
| rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
| where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，null 表示无附加条件 |
| source | list[string] | 是 | - | 历史热门站点中文名数组；元数据模式为空数组 |
| platform_site | list[PlatformSite] | 否 | - | 元数据平台站点组合；历史热门站点模式为 null |
| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
| frequency | string | 是 | - | 自然语言频率 |
| cron | string | 是 | - | 系统由 frequency 转换的 cron |
| 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) |

**对象 `AndNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 全部满足(编译为 bool.filter);至少 1 个条件 |

**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;query_string 的 value 为表达式，其它操作传 ES 真实值。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
| op | enum(eq、in、query_string、gt、gte、lt、lte、exists) | 是 | - | _id 仅支持 eq/in；其他字段操作符;须在字段 data_type 允许集合内(§1.5) |
| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | query_string 必须传非空字符串(最多4096字符)：每个关键词用双引号包围，如 ("防晒" OR "隔离") AND "敏感肌"；短语后可写 ~N，如 "散热测试"~3。支持 AND/OR/NOT 和括号；禁止裸词、字段限定、通配符、正则。服务端原样传递表达式，固定 ik_smart；其它 op 传 ES 真实值，in 传数组，exists 无需 value。 |

**对象 `NotNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |

**对象 `OrNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件 |

**对象 `PlatformSite`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| platform | string | 是 | minLen=1 | 具体平台编码，禁止包含 *，取 list_platforms 的 name_en；全平台须逐一列出平台组合 |
| sites | list[string] | 是 | minItems=1, minLen=1 | 站点编码数组，取 list_sites 的 value；["*"] 表示该平台全部站点，不可混用 |

**对象 `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"]' --published <v> --frequency <v>

### social-neuron-subscription job-delete
软删除本人 job:置 active=0(记录保留,可 job_update 恢复)。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --job-id | job_id | integer | 是 | - | 要停用的 job(须本人) |

**出参 `DeletedSubJob`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| job_id | integer | 是 | - | 被停用的 job |
| active | integer | 是 | - | 停用后固定为 0 |

示例:social-neuron-subscription job-delete --job-id <v>

### social-neuron-subscription job-list
列出本人全部订阅 job(不翻页),可按 active 过滤。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --active | active | enum(0、1) | 否 | - | 按启停过滤;不传返回全部 |

**出参 `SubJobList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[SubJob] | 是 | - | 本人 job 列表,按创建时间倒序(全量) |
| total | integer | 是 | - | 命中总数 |

**对象 `SubJob`** —— 订阅 job 出参对象。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
| job_id | integer | 是 | - | job ID |
| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
| rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
| where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，null 表示无附加条件 |
| source | list[string] | 是 | - | 历史热门站点中文名数组；元数据模式为空数组 |
| platform_site | list[PlatformSite] | 否 | - | 元数据平台站点组合；历史热门站点模式为 null |
| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
| frequency | string | 是 | - | 自然语言频率 |
| cron | string | 是 | - | 系统由 frequency 转换的 cron |
| 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-trigger
临时触发一次本人 job,落一条 ik_subscription_task(manual);默认用 job 存的 target,可覆盖。

落 pending task 后触发 Airflow DAG(``social_capability_subscription``)
跑取数→组装→投递(上传取 url);
未配 airflow_base_url 时(本地/测试)触发被跳过,仅留 pending task。**无通知**:结果落
``file_info.url``,调用方轮询 ``task-list`` 拉取。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --job-id | job_id | integer | 是 | - | 目标 job |
| --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=2147483647 | 覆盖本次导出行数；不传继承 job.size 并按系统当前上限收紧，显式超限拒绝 |

**对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 kafka |
| brokers | string | 是 | - | broker 列表(逗号分隔) |
| topic | string | 是 | - | 目标 topic |
| key_field | string | 否 | - | 作为消息 key 的字段名 |

**对象 `OctoTarget`** —— octo(本期,默认):导出文件上传 octo 存储,产出 CDN 下载 url(写入 file_info.url)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 octo |
| format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |

**对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
重跑多少次,远端路径与文件名都不变。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 sftp |
| 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) |

**出参 `SubJobTriggerResult`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| task_id | integer | 是 | - | task ID(异步) |
| status | string | 是 | - | 初始状态:pending |

示例:social-neuron-subscription job-trigger --job-id <v>

### social-neuron-subscription job-update
以 job_id 定位改本人 job:数组整组覆盖,target 整体替换,改 frequency 重算 cron。

**入参**

| 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 | 整组全量覆盖 |
| --where | where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，支持 and、or、not。省略保留，传 null 清除，传条件树整体替换 |
| --source | source | list[string] | 否 | minItems=1, minLen=1 | 历史热门站点中文名数组，取 list_source；整体替换范围，与 platform_site 互斥 |
| --platform-site | platform_site | list[PlatformSite] | 否 | minItems=1 | 元数据平台站点组合；整体替换范围，与 source 互斥；不传保持原范围 |
| --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 | 业务字段整组全量覆盖；_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;传空数组 [] 表示改回「给全部命中数据」 |
| --active | active | enum(0、1) | 否 | - | 启停:1 / 0 |

**对象 `AndNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 全部满足(编译为 bool.filter);至少 1 个条件 |

**对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 kafka |
| brokers | string | 是 | - | broker 列表(逗号分隔) |
| topic | string | 是 | - | 目标 topic |
| key_field | string | 否 | - | 作为消息 key 的字段名 |

**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;query_string 的 value 为表达式，其它操作传 ES 真实值。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
| op | enum(eq、in、query_string、gt、gte、lt、lte、exists) | 是 | - | _id 仅支持 eq/in；其他字段操作符;须在字段 data_type 允许集合内(§1.5) |
| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | query_string 必须传非空字符串(最多4096字符)：每个关键词用双引号包围，如 ("防晒" OR "隔离") AND "敏感肌"；短语后可写 ~N，如 "散热测试"~3。支持 AND/OR/NOT 和括号；禁止裸词、字段限定、通配符、正则。服务端原样传递表达式，固定 ik_smart；其它 op 传 ES 真实值，in 传数组，exists 无需 value。 |

**对象 `NotNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |

**对象 `OctoTarget`** —— octo(本期,默认):导出文件上传 octo 存储,产出 CDN 下载 url(写入 file_info.url)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 octo |
| format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |

**对象 `OrNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件 |

**对象 `PlatformSite`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| platform | string | 是 | minLen=1 | 具体平台编码，禁止包含 *，取 list_platforms 的 name_en；全平台须逐一列出平台组合 |
| sites | list[string] | 是 | minItems=1, minLen=1 | 站点编码数组，取 list_sites 的 value；["*"] 表示该平台全部站点，不可混用 |

**对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
重跑多少次,远端路径与文件名都不变。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| type | string | 是 | - | 固定 sftp |
| 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) |

**对象 `TopSpec`** —— 全局TopN排序规格(subscription专用)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | - | 排序字段(name_en);仅支持可排序类型(keyword/long/double/date) |
| order | enum(asc、desc) | 否 | - | 排序方向:desc降序(取最大的N个)/asc升序(取最小的N个) |

**出参 `SubJob`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| precheck | PrecheckResult | 否 | - | 本次保存的数据量预检摘要；非预检场景为空，不保存到 job |
| warnings | list[string] | 否 | - | 本次保存的超量截断提醒；未超量为空，不保存到 job |
| job_id | integer | 是 | - | job ID |
| name | string | 是 | - | job 名称,同一凭证(token)下唯一 |
| rule_ids | list[string] | 是 | - | 魔方规则ID数组 |
| where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，null 表示无附加条件 |
| source | list[string] | 是 | - | 历史热门站点中文名数组；元数据模式为空数组 |
| platform_site | list[PlatformSite] | 否 | - | 元数据平台站点组合；历史热门站点模式为 null |
| published | string | 是 | - | 发布时间口径(相对,支持按天或按分钟);触发时按 task_time 折算成绝对时间区间 |
| idate | string | 是 | - | 入库时间口径(相对,按天或按分钟);null=该维度不过滤 |
| udate | string | 是 | - | 更新时间口径(相对,按天或按分钟);null=该维度不过滤 |
| fields | list[string] | 是 | - | _id 自动输出，禁止在 fields 中填写；拉取/导出字段(空=全量) |
| size | integer | 是 | - | 每次执行最多导出的记录行数；普通批量保存时按系统配置校验，只取前 N 条时上限 10000 |
| top | list[object] | 否 | - | 只取前 N 条的排序定义 [{field, order}];null = 给命中条件的全部数据。非 null 时每次执行只取按该排序排在前 size 条的数据 |
| frequency | string | 是 | - | 自然语言频率 |
| cron | string | 是 | - | 系统由 frequency 转换的 cron |
| 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) |

**对象 `AndNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| and | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 全部满足(编译为 bool.filter);至少 1 个条件 |

**对象 `Leaf`** —— 叶子条件 ``{field, op, value}``;query_string 的 value 为表达式，其它操作传 ES 真实值。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| field | string | 是 | minLen=1, maxLen=128 | 字段 name_en |
| op | enum(eq、in、query_string、gt、gte、lt、lte、exists) | 是 | - | _id 仅支持 eq/in；其他字段操作符;须在字段 data_type 允许集合内(§1.5) |
| value | string、integer、number、boolean、list[string、integer、number、boolean] | 否 | - | query_string 必须传非空字符串(最多4096字符)：每个关键词用双引号包围，如 ("防晒" OR "隔离") AND "敏感肌"；短语后可写 ~N，如 "散热测试"~3。支持 AND/OR/NOT 和括号；禁止裸词、字段限定、通配符、正则。服务端原样传递表达式，固定 ik_smart；其它 op 传 ES 真实值，in 传数组，exists 无需 value。 |

**对象 `NotNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| not | AndNode、OrNode、NotNode、Leaf | 是 | - | 取反(编译为 bool.must_not) |

**对象 `OrNode`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| or | list[AndNode、OrNode、NotNode、Leaf] | 是 | minItems=1 | 任一满足(编译为 bool.should + minimum_should_match:1);至少 1 个条件 |

**对象 `PlatformSite`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| platform | string | 是 | minLen=1 | 具体平台编码，禁止包含 *，取 list_platforms 的 name_en；全平台须逐一列出平台组合 |
| sites | list[string] | 是 | minItems=1, minLen=1 | 站点编码数组，取 list_sites 的 value；["*"] 表示该平台全部站点，不可混用 |

**对象 `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
列出所选站点下可导出的字段:name_en(填 fields 用)、中文名、类型、是否枚举 / code。

``is_enum`` / ``is_code`` 为真的字段,导出文件里存的是枚举码 / 编码值;
**若**调用方要把它们换成中文,再调 ``get_field_values`` 取字典自行替换(按需,非必经步骤)。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --source | source | list[string] | 否 | minItems=1, minLen=1 | 历史热门站点中文名数组，取 list_source；与 platform_site 必须二选一 |
| --platform-site | platform_site | list[PlatformSite] | 否 | minItems=1 | 元数据平台站点组合；platform 取 list_platforms.name_en，sites 取 list_sites.value；与 source 二选一 |
| --keyword | keyword | string | 否 | maxLen=64 | 按字段中文名 / name_en 模糊过滤(如「情感」「互动」);不传=该站点全部字段 |

**对象 `PlatformSite`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| platform | string | 是 | minLen=1 | 具体平台编码，禁止包含 *，取 list_platforms 的 name_en；全平台须逐一列出平台组合 |
| sites | list[string] | 是 | minItems=1, minLen=1 | 站点编码数组，取 list_sites 的 value；["*"] 表示该平台全部站点，不可混用 |

**出参 `SubFieldList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[SubField] | 是 | - | 字段列表(所选站点的并集,按 name_en 排序) |
| total | integer | 是 | - | 字段总数 |

**对象 `SubField`** —— 一个字段的订阅口径描述；selectable 区分可选业务字段与自动输出的系统字段。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| 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 | 否 | - | 字段描述;元数据未登记描述时为空串 |
| is_enum | boolean | 是 | - | 值来自内置枚举(如数据类型、情感):导出列存的是枚举码;如需换成中文,再按需调 get_field_values 取字典自行替换 |
| is_code | boolean | 是 | - | 值是编码值(如品牌标签、品类标签):导出列存的是 code 而非中文;如需换成中文,再按需调 get_field_values 取字典自行替换 |

示例:social-neuron-subscription list-fields

### social-neuron-subscription list-platforms
列出舆情元数据平台，name_en 填入 platform_site[].platform。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|

**出参 `SubPlatformList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[Platform] | 是 | - | 元数据平台列表，name_en 填 platform_site.platform |
| total | integer | 是 | - | 平台总数 |

**对象 `Platform`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| name_en | string | 是 | - | 平台标识(= kw_platform 值) |
| name | string | 是 | - | 平台中文名 |
| description | string | 否 | - | 平台描述 |
| index_prefix | string | 否 | - | 索引前缀(索引名解析用) |
| time_pattern | string | 否 | - | 索引时间分片模式(如 yyyyMM) |

示例:social-neuron-subscription list-platforms

### social-neuron-subscription list-sites
搜索元数据站点，value 填 platform_site[].sites；原热门站点列表已改名 list_source。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --keyword | keyword | string | 否 | maxLen=64 | 按站点中文名或编码搜索，建议传关键词收窄结果 |

**出参 `SubSiteList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[Site] | 是 | - | 元数据全局站点列表，value 填 platform_site.sites；不包含平台归属，保存时校验对应关系 |
| total | integer | 是 | - | 命中站点总数 |

**对象 `Site`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| name | string | 是 | - | 站点中文名 |
| value | string | 是 | - | ES 来源字段值(如 douyin.com);站点目录即字典,value_source=none |
| is_key_site | boolean | 否 | - | 是否重点站点 |

示例:social-neuron-subscription list-sites

### social-neuron-subscription list-source
列出可订阅站点(中文站点名)—— job_create / job_update 的 source 只能取这里的值。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|

**出参 `SubSourceList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[string] | 是 | - | 中文站点名列表,即 job_create / job_update 的 source 该填的值(按配置顺序) |
| total | integer | 是 | - | 站点总数 |

示例:social-neuron-subscription list-source

### 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`**

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| source | list[string] | 否 | minItems=1, minLen=1 | 历史热门站点中文名数组，取 list_source；与 platform_site 必须二选一 |
| platform_site | list[PlatformSite] | 否 | minItems=1 | 元数据平台站点组合；platform 取 list_platforms.name_en，sites 取 list_sites.value；与 source 二选一 |
| confirmed | boolean | 否 | - | 是否已确认继续并同意系统超限处理规则；超量时默认拒绝，true 允许保存但仍按上限截断；不跳过其他校验，不保存到 job，TopN 不适用 |
| name | string | 是 | minLen=1, maxLen=128 | job 名称,同一凭证(token)下唯一 |
| rule_ids | list[string] | 是 | minItems=1, minLen=1 | 魔方规则ID数组,至少 1 个 |
| where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，支持 and、or、not，与规则、站点和时间同时生效 |
| 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 | 整组全量覆盖 |
| where | AndNode、OrNode、NotNode、Leaf | 否 | - | 附加过滤条件树，支持 and、or、not。省略保留，传 null 清除，传条件树整体替换 |
| source | list[string] | 否 | minItems=1, minLen=1 | 历史热门站点中文名数组，取 list_source；整体替换范围，与 platform_site 互斥 |
| platform_site | list[PlatformSite] | 否 | minItems=1 | 元数据平台站点组合；整体替换范围，与 source 互斥；不传保持原范围 |
| 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/创建时间过滤,按创建时间排序。

**入参**

| flag | 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| --job-id | job_id | integer | 是 | - | 所属 job |
| --task-id | task_id | integer | 否 | - | 传则查单条详情 |
| --status | status | enum(pending、running、success、failed、terminated) | 否 | - | 按状态过滤 |
| --start | start | string | 否 | - | 按创建时间过滤下界(created_at ≥ start,ISO8601 UTC+8) |
| --end | end | string | 否 | - | 按创建时间过滤上界(created_at ≤ end,ISO8601 UTC+8) |
| --sort | sort | enum(asc、desc) | 否 | - | 按 created_at 排序:asc 正序 / desc 倒序(默认 desc) |
| --page | page | integer | 否 | min=1 | 页码,默认 1 |
| --page-size | page_size | integer | 否 | min=1, max=100 | 每页条数,默认 10,范围 1–100 |

**出参 `SubTaskList`**

| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| items | list[SubTask] | 是 | - | task 列表,按 created_at 排序(方向由 sort 定,默认倒序) |
| total | integer | 是 | - | 命中总数 |

**对象 `SubTask`** —— 订阅 task 出参对象(**对外精简**:只给调用方轮询/下载所需)。

| 键 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| task_id | integer | 是 | - | task ID |
| job_id | integer | 是 | - | 所属 job |
| 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 | 否 | - | 对外可操作的失败提示;系统异常仅给通用提示,内部细节不返回 |
| created_at | string | 是 | - | 创建时间 |
| updated_at | string | 是 | - | 更新时间 |

示例:social-neuron-subscription task-list --job-id <v>
