@social-data/social-neuron-subscription 1.0.3 → 1.0.5

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]                       调用一条命令
@@ -65,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) } };
 }
@@ -113,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) {
@@ -134,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);
@@ -162,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;
   }

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

@@ -425,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 个;只能取已配置站点"
         },
@@ -467,7 +467,7 @@
         {
           "flag": "--fields",
           "field": "fields",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "拉取/导出字段;不填拉全量"
         },
@@ -776,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": {
@@ -1664,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": "整组全量覆盖"
         },
@@ -1699,7 +1699,7 @@
         {
           "flag": "--fields",
           "field": "fields",
-          "type": "list[str]",
+          "type": "list[str](json)",
           "required": false,
           "desc": "整组全量覆盖"
         },

package/package.json

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

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

@@ -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。
 
 ## 命令
 
@@ -84,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 恢复)。
@@ -146,7 +220,7 @@ metadata:
 ### 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`` 拉取。