@social-data/social-neuron-subscription 1.0.2 → 1.0.4

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 
-// ⚠️ 本文件由 backend/app/cli_spec/gen.py 生成,请勿手改;要改改 gen.py 的 _CLI_JS 后重跑 gen。
+// ⚠️ 本文件由 core/cli/gen.py 生成,请勿手改;要改改 gen.py 的 _CLI_JS 后重跑 gen。
 //
 // 能力 CLI —— 通用薄运行时(纯 JS,零依赖):一能力一命令、一包、一配置文件,互不影响。
 //   <cmd> <action> [--flags]                       调用一条命令
@@ -40,7 +40,11 @@ function resolveConfig() {
 
 function emit(env) {
   process.stdout.write(JSON.stringify(env) + "\n");
-  process.exit(env.ok ? 0 : (EXIT[env.error && env.error.type] ?? 1));
+  const dataExit = env.ok && env.data && env.data.meta && env.data.meta.exit_code;
+  const status = env.ok
+    ? ([0, 1, 2].includes(dataExit) ? dataExit : 0)
+    : (EXIT[env.error && env.error.type] ?? 1);
+  process.exit(status);
 }
 function fail(type, code, message, extra) {
   emit({ ok: false, error: { type, code, message, ...(extra || {}) } });
@@ -61,7 +65,9 @@ function normalize(body) {
     const type = forgeType(body.code);
     let message = body.msg || "";
     if (type === "outdated") message += "(升级后请重新加载 SKILL.md 与 manifest 再调用)";
-    return { ok: false, error: { type, code: body.code, message } };
+    // 网关在 data 里带审计 trace_id 的业务错误(如查询失败):透出供 get-query 回查。
+    const extra = body.data && body.data.trace_id ? { trace_id: body.data.trace_id } : {};
+    return { ok: false, error: { type, code: body.code, message, ...extra } };
   }
   return { ok: false, error: { type: "api_error", code: "UNKNOWN", message: JSON.stringify(body).slice(0, 200) } };
 }
@@ -109,15 +115,63 @@ function printWelcome() {
   w("──────────────────────────────────────────────");
 }
 
+// ── 嵌套对象形状:object(json) / list[object](json) 这类 flag 光看类型名没法拼 JSON,
+//    这里把 input_schema.$defs 里**被引用到的**对象摊开印出来(与 SKILL.md 同源同内容)。
+//    没有这段时,调用方只能靠 422 报错反推字段名。
+function typeStr(node) {
+  if (!node || typeof node !== "object") return "any";
+  if (typeof node.$ref === "string") return node.$ref.split("/").pop();
+  const union = node.anyOf || node.oneOf;
+  if (union) {
+    const parts = union.filter((n) => n && n.type !== "null").map(typeStr);
+    return parts.length ? parts.join("|") : "any";
+  }
+  if (Array.isArray(node.enum)) return "enum(" + node.enum.join("|") + ")";
+  if (node.type === "array") return "list[" + typeStr(node.items) + "]";
+  return node.type || "any";
+}
+function refsOf(node, acc) {
+  if (!node || typeof node !== "object") return acc;
+  if (Array.isArray(node)) { for (const n of node) refsOf(n, acc); return acc; }
+  if (typeof node.$ref === "string") acc.add(node.$ref.split("/").pop());
+  for (const k of Object.keys(node)) if (k !== "$defs") refsOf(node[k], acc);
+  return acc;
+}
+function objectBlocks(schema) {
+  const defs = (schema && schema.$defs) || {};
+  const queue = [...refsOf((schema && schema.properties) || {}, new Set())], seen = new Set();
+  while (queue.length) {                       // 递归:GroupLevel 会引用自己、Leaf 会被 AndNode 引用
+    const name = queue.shift();
+    if (seen.has(name) || !defs[name]) continue;
+    seen.add(name);
+    for (const r of refsOf(defs[name], new Set())) queue.push(r);
+  }
+  const out = [];
+  for (const name of [...seen].sort()) {
+    const d = defs[name], props = d.properties;
+    if (!props) continue;
+    const required = new Set(d.required || []);
+    const rows = Object.keys(props).map((k) => [k, typeStr(props[k]), required.has(k) ? "required" : "optional",
+                                                props[k].description || ""]);
+    const w0 = Math.max(...rows.map((r) => r[0].length)), w1 = Math.max(...rows.map((r) => r[1].length));
+    out.push("对象 " + name + ":" + (d.description ? "  " + d.description.split("\n")[0] : ""));
+    for (const r of rows) out.push("  " + r[0].padEnd(w0) + "  " + r[1].padEnd(w1) + "  " + r[2].padEnd(8) + "  " + r[3]);
+  }
+  return out;
+}
+
 function usageOf(cmd) {
   const line = (f) => "  " + f.flag + "  " + f.type + (f.required ? "  required" : "  optional") + "  " + (f.desc || "");
   const req = cmd.flags.filter((f) => f.required), opt = cmd.flags.filter((f) => !f.required);
+  const blocks = objectBlocks(cmd.input_schema);
   return {
     command: COMMAND + " " + cmd.action,
     required: req.map((f) => ({ flag: f.flag, type: f.type, desc: f.desc })),
     optional: opt.map((f) => ({ flag: f.flag, type: f.type, desc: f.desc })),
+    objects: blocks,                            // 同样带进 INVALID_ARGS 报错里,拼错时直接能看到形状
     example: (COMMAND + " " + cmd.action + " " + req.map((f) => f.flag + " <v>").join(" ")).trim(),
-    _text: [COMMAND + " " + cmd.action + " — " + cmd.summary, "Inputs:", ...cmd.flags.map(line)].join("\n"),
+    _text: [COMMAND + " " + cmd.action + " — " + cmd.summary, "Inputs:", ...cmd.flags.map(line),
+            ...(blocks.length ? ["", ...blocks] : [])].join("\n"),
   };
 }
 function printHelp(action) {
@@ -130,7 +184,7 @@ function printHelp(action) {
   w(COMMAND + " v" + VERSION + " — Social Neuron 能力 CLI(能力:" + CAPABILITY + ";供 AI agent 调用)");
   w("");
   w("用法:" + COMMAND + " <action> [--flags]");
-  w("  标量 --flag v;数组 --flag a,b;对象 --flag '<json>';写/删/触发加 -y");
+  w("  标量 --flag v;数组/对象一律 JSON:--flag '[\"a\",\"b\"]' / --flag '{\"k\":\"v\"}';写/删/触发加 -y");
   w("");
   w("命令:");
   for (const c of MANIFEST.tools) w("  " + COMMAND + " " + c.action + "  —  " + c.summary);
@@ -158,8 +212,17 @@ function parseArgs(cmd, argv) {
     const raw = argv[++i];
     if (raw === undefined) return { err: fail("validation", "MISSING_VALUE", a + " 缺少取值") };
     let val = raw;
-    if (f.type.startsWith("list")) val = raw.split(",").map((s) => s.trim()).filter(Boolean);
-    else if (f.type.startsWith("object")) { try { val = JSON.parse(raw); } catch { return { err: fail("validation", "BAD_JSON", a + " 需为合法 JSON") }; } }
+    if (f.type.indexOf("(json)") >= 0) {
+      // 数组/对象一律按 JSON 解析(与 MCP 入参同形)。不做「逗号分隔」这类特例:
+      // 同一份文档要能同时用于两个出口,取值写法就只能有一种。
+      try { val = JSON.parse(raw); } catch {
+        const hint = f.type.startsWith("list") ? "JSON 数组,如 '[\"a\",\"b\"]'" : "JSON 对象,如 '{\"k\":\"v\"}'";
+        return { err: fail("validation", "BAD_JSON", a + " 需为 " + hint + "(当前取值:" + raw + ")") };
+      }
+      if (f.type.startsWith("list") && !Array.isArray(val)) {
+        return { err: fail("validation", "BAD_JSON", a + " 需为 JSON 数组,如 '[\"a\",\"b\"]';单个取值也要写成数组") };
+      }
+    }
     else if (f.type === "integer") val = Number(raw);
     args[f.field] = val;
   }
@@ -167,7 +230,8 @@ function parseArgs(cmd, argv) {
 }
 
 async function main() {
-  const argv = process.argv.slice(2);
+  let argv = process.argv.slice(2);
+  if (argv.length === 0 && MANIFEST.default_action) argv = [MANIFEST.default_action];
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") return printHelp();
   if (argv[0] === "--version" || argv[0] === "-V") { process.stdout.write(VERSION + "\n"); return; }
   if (argv[0] === "bind") return doBind(argv.slice(1));

package/bin/install-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 
-// ⚠️ 本文件由 backend/app/cli_spec/gen.py 生成,请勿手改。
+// ⚠️ 本文件由 core/cli/gen.py 生成,请勿手改。
 // postinstall:把包内 SKILL.md 覆盖写到 OpenClaw 技能目录(OPENCLAW_SKILLS_DIR 或 ~/.openclaw/skills)。
 
 const fs = require("fs");

package/manifest.json

@@ -2,6 +2,7 @@
   "revision": 6,
   "capability": "subscription",
   "command": "social-neuron-subscription",
+  "default_action": null,
   "mcp_path": "/subscription/mcp",
   "tools": [
     {
@@ -84,7 +85,7 @@
           },
           "SftpTarget": {
             "additionalProperties": false,
-            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。",
+            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task\n重跑多少次,远端路径与文件名都不变。",
             "properties": {
               "type": {
                 "const": "sftp",
@@ -233,6 +234,14 @@
             "title": "Fields",
             "type": "array"
           },
+          "size": {
+            "default": 500000,
+            "description": "每次执行最多导出的记录行数,默认且最大为 500000",
+            "maximum": 500000,
+            "minimum": 1,
+            "title": "Size",
+            "type": "integer"
+          },
           "target": {
             "anyOf": [
               {
@@ -342,6 +351,11 @@
             "title": "Fields",
             "type": "array"
           },
+          "size": {
+            "description": "每次执行最多导出的记录行数,范围 1–500000",
+            "title": "Size",
+            "type": "integer"
+          },
           "frequency": {
             "description": "自然语言频率",
             "title": "Frequency",
@@ -388,6 +402,7 @@
           "idate",
           "udate",
           "fields",
+          "size",
           "frequency",
           "cron",
           "target_type",
@@ -410,14 +425,14 @@
         {
           "flag": "--rule-ids",
           "field": "rule_ids",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": true,
           "desc": "魔方规则ID数组,至少 1 个"
         },
         {
           "flag": "--source",
           "field": "source",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": true,
           "desc": "站点数组,至少 1 个;只能取已配置站点"
         },
@@ -452,10 +467,17 @@
         {
           "flag": "--fields",
           "field": "fields",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "拉取/导出字段;不填拉全量"
         },
+        {
+          "flag": "--size",
+          "field": "size",
+          "type": "integer",
+          "required": false,
+          "desc": "每次执行最多导出的记录行数,默认且最大为 500000"
+        },
         {
           "flag": "--target",
           "field": "target",
@@ -640,6 +662,11 @@
                 "title": "Fields",
                 "type": "array"
               },
+              "size": {
+                "description": "每次执行最多导出的记录行数,范围 1–500000",
+                "title": "Size",
+                "type": "integer"
+              },
               "frequency": {
                 "description": "自然语言频率",
                 "title": "Frequency",
@@ -686,6 +713,7 @@
               "idate",
               "udate",
               "fields",
+              "size",
               "frequency",
               "cron",
               "target_type",
@@ -748,7 +776,7 @@
       "op": "job_trigger",
       "name": "subscription/job_trigger",
       "summary": "临时触发一次本人 job,落一条 ik_subscription_task(manual);默认用 job 存的 target,可覆盖。",
-      "description": "临时触发一次本人 job,落一条 ik_subscription_task(manual);默认用 job 存的 target,可覆盖。\n\n落 pending task 后触发 Airflow DAG(``social_neuron_subscription``)跑取数→组装→投递(上传取 url);\n未配 airflow_base_url 时(本地/测试)触发被跳过,仅留 pending task。**无通知**:结果落\n``file_info.url``,调用方轮询 ``task-list`` 拉取。",
+      "description": "临时触发一次本人 job,落一条 ik_subscription_task(manual);默认用 job 存的 target,可覆盖。\n\n落 pending task 后触发 Airflow DAG(``social_capability_subscription``)跑取数→组装→投递(上传取 url);\n未配 airflow_base_url 时(本地/测试)触发被跳过,仅留 pending task。**无通知**:结果落\n``file_info.url``,调用方轮询 ``task-list`` 拉取。",
       "input_schema": {
         "$defs": {
           "KafkaTarget": {
@@ -823,7 +851,7 @@
           },
           "SftpTarget": {
             "additionalProperties": false,
-            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。",
+            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task\n重跑多少次,远端路径与文件名都不变。",
             "properties": {
               "type": {
                 "const": "sftp",
@@ -1014,6 +1042,21 @@
             "default": null,
             "description": "覆盖本次投递目标",
             "title": "Target"
+          },
+          "size": {
+            "anyOf": [
+              {
+                "maximum": 500000,
+                "minimum": 1,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "覆盖本次导出行数;不传则继承 job 的 size,最大 500000",
+            "title": "Size"
           }
         },
         "required": [
@@ -1099,6 +1142,13 @@
           "type": "object(json)",
           "required": false,
           "desc": "覆盖本次投递目标"
+        },
+        {
+          "flag": "--size",
+          "field": "size",
+          "type": "integer",
+          "required": false,
+          "desc": "覆盖本次导出行数;不传则继承 job 的 size,最大 500000"
         }
       ],
       "transport": {
@@ -1194,7 +1244,7 @@
           },
           "SftpTarget": {
             "additionalProperties": false,
-            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。",
+            "description": "sftp(本期):把导出文件上传到 SFTP 远端目录。\n目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task\n重跑多少次,远端路径与文件名都不变。",
             "properties": {
               "type": {
                 "const": "sftp",
@@ -1381,6 +1431,21 @@
             "description": "整组全量覆盖",
             "title": "Fields"
           },
+          "size": {
+            "anyOf": [
+              {
+                "maximum": 500000,
+                "minimum": 1,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "每次执行最多导出的记录行数;不传则不修改,最大 500000",
+            "title": "Size"
+          },
           "frequency": {
             "anyOf": [
               {
@@ -1518,6 +1583,11 @@
             "title": "Fields",
             "type": "array"
           },
+          "size": {
+            "description": "每次执行最多导出的记录行数,范围 1–500000",
+            "title": "Size",
+            "type": "integer"
+          },
           "frequency": {
             "description": "自然语言频率",
             "title": "Frequency",
@@ -1564,6 +1634,7 @@
           "idate",
           "udate",
           "fields",
+          "size",
           "frequency",
           "cron",
           "target_type",
@@ -1593,14 +1664,14 @@
         {
           "flag": "--rule-ids",
           "field": "rule_ids",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "整组全量覆盖"
         },
         {
           "flag": "--source",
           "field": "source",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "整组全量覆盖"
         },
@@ -1628,10 +1699,17 @@
         {
           "flag": "--fields",
           "field": "fields",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "整组全量覆盖"
         },
+        {
+          "flag": "--size",
+          "field": "size",
+          "type": "integer",
+          "required": false,
+          "desc": "每次执行最多导出的记录行数;不传则不修改,最大 500000"
+        },
         {
           "flag": "--frequency",
           "field": "frequency",
@@ -1788,6 +1866,11 @@
                 "title": "Job Id",
                 "type": "integer"
               },
+              "size": {
+                "description": "本次执行最多导出的记录行数",
+                "title": "Size",
+                "type": "integer"
+              },
               "status": {
                 "description": "pending/running/success/failed/terminated",
                 "title": "Status",
@@ -1834,6 +1917,7 @@
             "required": [
               "task_id",
               "job_id",
+              "size",
               "status",
               "created_at",
               "updated_at"
@@ -1939,7 +2023,7 @@
   ],
   "skill": {
     "slug": "social-neuron-subscription",
-    "description": "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②单次拉数≤10 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息",
+    "description": "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task。概念:job=订阅定义(数据范围+频率+投递方式,系统按频率生成 cron);task=job 的一次执行,产物与下载地址落在 file_info。边界:①每 token 生效 job 默认≤10;②单次拉数可指定 size,默认且最大 50 万行,超出截断;③投递仅 octo/sftp(kafka 规划中,暂不支持),无主动通知、须轮询 task 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息",
     "actions": [
       "job-create",
       "job-delete",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@social-data/social-neuron-subscription",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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 取结果。④如果拉取不到数据则不会产生文件上传，也就没有文件url信息"
+description: "使用场景:定时导出/订阅推送/定期拉数/大批量出文件——需异步产出文件并下载时用能力:按魔方规则、定时 cron 或手动触发,把大库数据异步导出为文件,上传 octo/sftp,产出下载 url 供调用方轮询拉取;可创建/修改/列出/删除/触发订阅 job、翻页查询 task。概念: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,7 +10,81 @@ 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**。
+没有主动通知,不轮询就拿不到结果。
+
+### 一、写法约定
+
+数组和对象一律写成 **JSON 串**,和 MCP 入参同形:`--rule-ids '["r1","r2"]'`、`--target '{...}'`。
+数组不能用逗号分隔,**单个取值也要写成数组**。写错会直接报 `BAD_JSON` 并回显原值。
+
+### 二、两个概念
+
+| | 是什么 | 谁创建 |
+|---|---|---|
+| **job** | 订阅定义:数据范围 + 频率 + 投递方式 | 你 `job-create` |
+| **task** | job 的**一次执行**,产物和下载地址落在 `file_info` | 系统按 cron,或你 `job-trigger` |
+
+### 三、标准流程
+
+```
+job-create   → 拿到 job_id
+job-trigger  → 立刻跑一次(不等 cron);返回 task_id
+task-list    → 轮询该 task,status 变终态后读 file_info 里的下载 url
+```
+
+改配置用 `job-update`(只传要改的字段);不想再跑就 `job-update --active false`,彻底不要才 `job-delete`。
+
+### 四、三个时间口径别搞混
+
+- `--published` **发布时间,必填**:它同时决定查哪个月的索引,所以不能缺省。
+- `--idate` 入库时间、`--udate` 更新时间:**选填**,是在发布时间窗**之内**再 AND 一层收窄;
+  不传 = 该维度不过滤。
+
+### 五、容易踩的
+
+- **拉不到数据就不会有文件**,`file_info` 里也就没有 url —— 这不是失败,是没命中。
+- 单次导出 `--size` 默认且最大 **50 万行**,超出会截断。
+- 每个 token 生效的 job 默认 **≤10 个**,满了要先 `job-delete` 或停用。
+- `--source` 只能填**已配置的站点**,不是随便写域名。
+- 投递目标本期只支持 **octo / sftp**(kafka 规划中);省略 `--target` 默认 octo。
+
+## 示例
+
+### 建一个每天跑的订阅,并立刻先跑一次看看
+
+```bash
+# 1) 建 job(频率用自然语言,系统转 cron)
+social-neuron-subscription job-create --name 每日舆情 \
+  --rule-ids '["12345"]' --source '["douyin.com"]' \
+  --published '近7天' --frequency '每天早上8点' -y
+
+# 2) 不等 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
+social-neuron-subscription job-update --job-id 1001 --active false -y
+```
+
+> 只传要改的字段即可;彻底不要才用 job-delete。
 
 ## 命令
 
@@ -29,6 +103,7 @@ metadata:
 | --udate | udate | string | 否 | - | **更新时间**口径(选填,不传=该维度不过滤)。在发布时间窗**之内**再 AND 一层:更新时间落在本区间的数据。记法 **T-M~T-N**:从 M 天前到 N 天前的闭区间(要求 M>=N),端点按天计,基准日是本次触发的 task_time(东八区;定时=cron 槽位日,手动=触发当日)。**两个端点都必须写全,不接受单值简写** —— 「昨天」写 T-1~T-1,写 T-1 会被拒绝。举例:T-0~T-0=今天;T-1~T-1=昨天;T-2~T-2=前天;T-1~T-0=昨天到今天(2天);T-2~T-1=前天到昨天(2天,口语的「前两天」);T-3~T-1=前三天(3天);T-7~T-3=7天前到3天前(5天);T-7~T-1=近7天到昨天(7天)。跨度最多 120 天、偏移最多 720 天(近两年),M<N 或超限直接报错(不会静默回落)。 |
 | --frequency | frequency | string | 是 | minLen=1, maxLen=64 | 自然语言同步频率,系统转 cron(东八区)。可指定具体时间、并**支持一天多次**:如「每天9点」「每天9点和15点」(一天跑两次)「每周一9点」「每小时」「每30分钟」。无法解析为 cron 会被拒绝。 |
 | --fields | fields | list[string] | 否 | minLen=1 | 拉取/导出字段;不填拉全量 |
+| --size | size | integer | 否 | min=1, max=500000 | 每次执行最多导出的记录行数,默认且最大为 500000 |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 投递目标;省略默认 octo(json)。本期支持 octo(上传存储→CDN url)与 sftp(账密上传远端,路径/文件名可用日期变量);kafka: 暂未实现。 |
 
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
@@ -48,7 +123,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
-目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -73,6 +149,7 @@ metadata:
 | idate | string | 是 | - | 入库时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -81,7 +158,7 @@ metadata:
 | 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 恢复)。
@@ -129,6 +206,7 @@ metadata:
 | idate | string | 是 | - | 入库时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -137,12 +215,12 @@ metadata:
 | 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,落一条 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`` 拉取。
 
@@ -158,6 +236,7 @@ metadata:
 | --udate-start | udate_start | string | 否 | - | **更新时间**下界(绝对日期 yyyy-MM-dd,东八区);与 udate_end 同传同不传;不传则按 job 上的 udate 相对口径折算,job 也没配=该维度不过滤 |
 | --udate-end | udate_end | string | 否 | - | **更新时间**上界(绝对日期 yyyy-MM-dd,东八区,该日整天含在窗内) |
 | --target | target | OctoTarget、SftpTarget、KafkaTarget | 否 | - | 覆盖本次投递目标 |
+| --size | size | integer | 否 | min=1, max=500000 | 覆盖本次导出行数;不传则继承 job 的 size,最大 500000 |
 
 **对象 `KafkaTarget`** —— kafka(规划):把记录流投送到 topic(无文件)。
 
@@ -176,7 +255,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
-目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -213,6 +293,7 @@ metadata:
 | --idate | idate | string | 否 | - | **入库时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。记法 **T-M~T-N**:从 M 天前到 N 天前的闭区间(要求 M>=N),端点按天计,基准日是本次触发的 task_time(东八区;定时=cron 槽位日,手动=触发当日)。**两个端点都必须写全,不接受单值简写** —— 「昨天」写 T-1~T-1,写 T-1 会被拒绝。举例:T-0~T-0=今天;T-1~T-1=昨天;T-2~T-2=前天;T-1~T-0=昨天到今天(2天);T-2~T-1=前天到昨天(2天,口语的「前两天」);T-3~T-1=前三天(3天);T-7~T-3=7天前到3天前(5天);T-7~T-1=近7天到昨天(7天)。跨度最多 120 天、偏移最多 720 天(近两年),M<N 或超限直接报错(不会静默回落)。 |
 | --udate | udate | string | 否 | - | **更新时间**口径。不传=不改;传空串 ""=**清除**该维度(恢复成不过滤)。记法 **T-M~T-N**:从 M 天前到 N 天前的闭区间(要求 M>=N),端点按天计,基准日是本次触发的 task_time(东八区;定时=cron 槽位日,手动=触发当日)。**两个端点都必须写全,不接受单值简写** —— 「昨天」写 T-1~T-1,写 T-1 会被拒绝。举例:T-0~T-0=今天;T-1~T-1=昨天;T-2~T-2=前天;T-1~T-0=昨天到今天(2天);T-2~T-1=前天到昨天(2天,口语的「前两天」);T-3~T-1=前三天(3天);T-7~T-3=7天前到3天前(5天);T-7~T-1=近7天到昨天(7天)。跨度最多 120 天、偏移最多 720 天(近两年),M<N 或超限直接报错(不会静默回落)。 |
 | --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 |
@@ -234,7 +315,8 @@ metadata:
 | format | enum(csv、excel、json) | 否 | - | 文件格式:csv/excel/json(默认 json) |
 
 **对象 `SftpTarget`** —— sftp(本期):把导出文件上传到 SFTP 远端目录。
-目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task 重跑多少次,远端路径与文件名都不变。
+目录与文件名都支持日期变量 ``yyyyMMdd`` / ``yyyyMM`` / ``yyyy``,同一个 task
+重跑多少次,远端路径与文件名都不变。
 
 | 键 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
@@ -259,6 +341,7 @@ metadata:
 | idate | string | 是 | - | 入库时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | udate | string | 是 | - | 更新时间口径(相对,T-M~T-N);null=该维度不过滤 |
 | fields | list[string] | 是 | - | 拉取/导出字段(空=全量) |
+| size | integer | 是 | - | 每次执行最多导出的记录行数,范围 1–500000 |
 | frequency | string | 是 | - | 自然语言频率 |
 | cron | string | 是 | - | 系统由 frequency 转换的 cron |
 | target_type | string | 是 | - | 投递类型:octo、sftp、kafka(暂不支持) |
@@ -298,6 +381,7 @@ metadata:
 |---|---|---|---|---|
 | 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 时给出;成功/进行中为空) |