aiconductor-cli 1.6.0 → 1.7.0

package/src/lib/cli-utils.js

@@ -1,172 +1,172 @@
-const { resolveApiKey } = require("../api");
-
-/**
- * 统一成功输出
- * @param {object} data - API 返回数据
- * @param {"json"|"text"} format
- * @param {function} [textFormatter] - text 模式的自定义格式化函数，接收 data 返回字符串
- */
-function outputResult(data, format, textFormatter) {
-  if (format === "json") {
-    process.stdout.write(JSON.stringify({ success: true, data }, null, 2) + "\n");
-  } else {
-    const text = textFormatter ? textFormatter(data) : JSON.stringify(data, null, 2);
-    process.stdout.write(text + "\n");
-  }
-}
-
-/**
- * 统一错误输出
- * @param {object} err - 错误对象（需有 message 属性）
- * @param {"json"|"text"} format
- */
-function outputError(err, format) {
-  const msg = err.message || String(err);
-  if (format === "json") {
-    process.stderr.write(JSON.stringify({ success: false, error: msg }, null, 2) + "\n");
-  } else {
-    process.stderr.write(`✗ 错误: ${msg}\n`);
-  }
-}
-
-/**
- * 解析 API Key，失败时输出错误并退出进程
- * @param {string} [optionKey] - 命令行传入的 key
- * @param {"json"|"text"} format
- * @returns {string} 解析到的 API Key
- */
-function resolveKeyOrExit(optionKey, format) {
-  const key = resolveApiKey(optionKey);
-  if (!key) {
-    outputError(
-      { message: "缺少 API Key。请通过 -k 参数、AICONDUCTOR_API_KEY 环境变量或 .env 文件提供。" },
-      format
-    );
-    process.exit(1);
-  }
-  return key;
-}
-
-/**
- * 统一 API 错误处理（不退出，由调用方决定退出码）
- * @param {object} err - 错误对象
- * @param {"json"|"text"} format
- */
-function handleApiError(err, format) {
-  if (err.type === "http_error") {
-    outputError(
-      { message: `API 返回错误 (HTTP ${err.statusCode}): ${err.body?.message || JSON.stringify(err.body)}` },
-      format
-    );
-  } else if (err.type === "network_error") {
-    outputError({ message: `网络错误: ${err.message}` }, format);
-  } else if (err.type === "validation_error") {
-    outputError({ message: `参数错误: ${err.message}` }, format);
-  } else if (err.type === "api_error") {
-    outputError({ message: err.message }, format);
-  } else {
-    outputError({ message: `未知错误: ${err.message || err}` }, format);
-  }
-}
-
-/**
- * 安全解析整数，无效时返回 defaultValue
- * @param {*} value
- * @param {number} defaultValue
- * @returns {number}
- */
-function safeParseInt(value, defaultValue) {
-  if (value === undefined || value === null) return defaultValue;
-  const n = parseInt(value, 10);
-  return Number.isNaN(n) ? defaultValue : n;
-}
-
-/**
- * 从文本（分享口令/带链接的句子）中抽出第一个 http(s) 链接。
- *
- * 小红书用户复制的内容形如「标题 https://xhslink.cn/o/xxx 复制内容，然后进入【小红书】查看相关笔记。」
- * 平台侧的 share_text 是**原样透传上游**的，带中文口令必失败（2026-11-05 实测），所以链接必须本地抽。
- * @param {string} text
- * @returns {string|null}
- */
-function extractUrlFromText(text) {
-  if (typeof text !== "string") return null;
-  const match = text.match(/https?:\/\/[^\s\u4e00-\u9fa5，。、；：！？（）【】《》“”‘’]+/i);
-  if (!match) return null;
-  // 去掉 URL 尾部的英文标点（中文标点已在字符集里排除）
-  return match[0].replace(/[),.;:!?'"\]}>]+$/, "");
-}
-
-const XHS_ID_RE = /^[0-9a-f]{24}$/i;
-
-/**
- * 从用户输入里识别小红书笔记 ID（裸 ID / 长链 / 带链接的分享文案）。
- * 短链（xhslink.cn）需先由 resolveXhsShortLink 换成长链。
- * @param {string} text
- * @returns {string|null}
- */
-function parseXhsNoteId(text) {
-  if (typeof text !== "string") return null;
-  const raw = text.trim();
-  if (XHS_ID_RE.test(raw)) return raw;
-  const url = extractUrlFromText(raw);
-  if (!url) return null;
-  const match = url.match(/(?:explore|discovery\/item|note)\/([0-9a-f]{24})/i);
-  return match ? match[1] : null;
-}
-
-/**
- * 从用户输入里识别小红书用户 ID（裸 ID / 主页链接）。
- * @param {string} text
- * @returns {string|null}
- */
-function parseXhsUserId(text) {
-  if (typeof text !== "string") return null;
-  const raw = text.trim();
-  if (XHS_ID_RE.test(raw)) return raw;
-  const url = extractUrlFromText(raw);
-  if (!url) return null;
-  const match = url.match(/user\/profile\/([0-9a-f]{24})/i);
-  return match ? match[1] : null;
-}
-
-/**
- * 小红书时间戳格式化：上游给的是**真 UTC epoch**（详情秒、笔记列表毫秒），展示需 +8 小时。
- * 与抖音相反（抖音是「北京时间编码」，不要再加 8）。
- * @param {number|string} value epoch 秒或毫秒
- * @returns {string} `YYYY-MM-DD HH:mm:ss`，无效值返回空串
- */
-function formatXhsTime(value) {
-  const n = Number(value);
-  if (!n || Number.isNaN(n)) return "";
-  const ms = n > 1e12 ? n : n * 1000;
-  return new Date(ms + 8 * 3600 * 1000).toISOString().replace("T", " ").slice(0, 19);
-}
-
-/**
- * 归一化为整数计数：上游同一平台里数字有 int、字符串、以及「1.2万」这类糊糊写法。
- * @param {*} value
- * @returns {number}
- */
-function toCount(value) {
-  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
-  if (value === null || value === undefined) return 0;
-  const text = String(value).replace(/[,\s]/g, "");
-  const match = text.match(/^(\d+(?:\.\d+)?)(万|w)?\+?$/i);
-  if (!match) return 0;
-  const base = Number(match[1]);
-  return Math.round(match[2] ? base * 10000 : base);
-}
-
-module.exports = {
-  outputResult,
-  outputError,
-  resolveKeyOrExit,
-  handleApiError,
-  safeParseInt,
-  extractUrlFromText,
-  parseXhsNoteId,
-  parseXhsUserId,
-  formatXhsTime,
-  toCount,
-};
+const { resolveApiKey } = require("../api");
+
+/**
+ * 统一成功输出
+ * @param {object} data - API 返回数据
+ * @param {"json"|"text"} format
+ * @param {function} [textFormatter] - text 模式的自定义格式化函数，接收 data 返回字符串
+ */
+function outputResult(data, format, textFormatter) {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ success: true, data }, null, 2) + "\n");
+  } else {
+    const text = textFormatter ? textFormatter(data) : JSON.stringify(data, null, 2);
+    process.stdout.write(text + "\n");
+  }
+}
+
+/**
+ * 统一错误输出
+ * @param {object} err - 错误对象（需有 message 属性）
+ * @param {"json"|"text"} format
+ */
+function outputError(err, format) {
+  const msg = err.message || String(err);
+  if (format === "json") {
+    process.stderr.write(JSON.stringify({ success: false, error: msg }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`✗ 错误: ${msg}\n`);
+  }
+}
+
+/**
+ * 解析 API Key，失败时输出错误并退出进程
+ * @param {string} [optionKey] - 命令行传入的 key
+ * @param {"json"|"text"} format
+ * @returns {string} 解析到的 API Key
+ */
+function resolveKeyOrExit(optionKey, format) {
+  const key = resolveApiKey(optionKey);
+  if (!key) {
+    outputError(
+      { message: "缺少 API Key。请通过 -k 参数、AICONDUCTOR_API_KEY 环境变量或 .env 文件提供。" },
+      format
+    );
+    process.exit(1);
+  }
+  return key;
+}
+
+/**
+ * 统一 API 错误处理（不退出，由调用方决定退出码）
+ * @param {object} err - 错误对象
+ * @param {"json"|"text"} format
+ */
+function handleApiError(err, format) {
+  if (err.type === "http_error") {
+    outputError(
+      { message: `API 返回错误 (HTTP ${err.statusCode}): ${err.body?.message || JSON.stringify(err.body)}` },
+      format
+    );
+  } else if (err.type === "network_error") {
+    outputError({ message: `网络错误: ${err.message}` }, format);
+  } else if (err.type === "validation_error") {
+    outputError({ message: `参数错误: ${err.message}` }, format);
+  } else if (err.type === "api_error") {
+    outputError({ message: err.message }, format);
+  } else {
+    outputError({ message: `未知错误: ${err.message || err}` }, format);
+  }
+}
+
+/**
+ * 安全解析整数，无效时返回 defaultValue
+ * @param {*} value
+ * @param {number} defaultValue
+ * @returns {number}
+ */
+function safeParseInt(value, defaultValue) {
+  if (value === undefined || value === null) return defaultValue;
+  const n = parseInt(value, 10);
+  return Number.isNaN(n) ? defaultValue : n;
+}
+
+/**
+ * 从文本（分享口令/带链接的句子）中抽出第一个 http(s) 链接。
+ *
+ * 小红书用户复制的内容形如「标题 https://xhslink.cn/o/xxx 复制内容，然后进入【小红书】查看相关笔记。」
+ * 平台侧的 share_text 是**原样透传上游**的，带中文口令必失败（2026-11-05 实测），所以链接必须本地抽。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractUrlFromText(text) {
+  if (typeof text !== "string") return null;
+  const match = text.match(/https?:\/\/[^\s\u4e00-\u9fa5，。、；：！？（）【】《》“”‘’]+/i);
+  if (!match) return null;
+  // 去掉 URL 尾部的英文标点（中文标点已在字符集里排除）
+  return match[0].replace(/[),.;:!?'"\]}>]+$/, "");
+}
+
+const XHS_ID_RE = /^[0-9a-f]{24}$/i;
+
+/**
+ * 从用户输入里识别小红书笔记 ID（裸 ID / 长链 / 带链接的分享文案）。
+ * 短链（xhslink.cn）需先由 resolveXhsShortLink 换成长链。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function parseXhsNoteId(text) {
+  if (typeof text !== "string") return null;
+  const raw = text.trim();
+  if (XHS_ID_RE.test(raw)) return raw;
+  const url = extractUrlFromText(raw);
+  if (!url) return null;
+  const match = url.match(/(?:explore|discovery\/item|note)\/([0-9a-f]{24})/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * 从用户输入里识别小红书用户 ID（裸 ID / 主页链接）。
+ * @param {string} text
+ * @returns {string|null}
+ */
+function parseXhsUserId(text) {
+  if (typeof text !== "string") return null;
+  const raw = text.trim();
+  if (XHS_ID_RE.test(raw)) return raw;
+  const url = extractUrlFromText(raw);
+  if (!url) return null;
+  const match = url.match(/user\/profile\/([0-9a-f]{24})/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * 小红书时间戳格式化：上游给的是**真 UTC epoch**（详情秒、笔记列表毫秒），展示需 +8 小时。
+ * 与抖音相反（抖音是「北京时间编码」，不要再加 8）。
+ * @param {number|string} value epoch 秒或毫秒
+ * @returns {string} `YYYY-MM-DD HH:mm:ss`，无效值返回空串
+ */
+function formatXhsTime(value) {
+  const n = Number(value);
+  if (!n || Number.isNaN(n)) return "";
+  const ms = n > 1e12 ? n : n * 1000;
+  return new Date(ms + 8 * 3600 * 1000).toISOString().replace("T", " ").slice(0, 19);
+}
+
+/**
+ * 归一化为整数计数：上游同一平台里数字有 int、字符串、以及「1.2万」这类糊糊写法。
+ * @param {*} value
+ * @returns {number}
+ */
+function toCount(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+  if (value === null || value === undefined) return 0;
+  const text = String(value).replace(/[,\s]/g, "");
+  const match = text.match(/^(\d+(?:\.\d+)?)(万|w)?\+?$/i);
+  if (!match) return 0;
+  const base = Number(match[1]);
+  return Math.round(match[2] ? base * 10000 : base);
+}
+
+module.exports = {
+  outputResult,
+  outputError,
+  resolveKeyOrExit,
+  handleApiError,
+  safeParseInt,
+  extractUrlFromText,
+  parseXhsNoteId,
+  parseXhsUserId,
+  formatXhsTime,
+  toCount,
+};

package/src/lib/daren-score.js

@@ -0,0 +1,91 @@
+/**
+ * 小红书达人打分（纯函数，不联网）。
+ *
+ * 公式与 `backend/api_docs/xhs_pgy_blogger.md` 的「注意事项 2」保持一致，
+ * HTTP 用户可依同一份公式自行计算。
+ *
+ * 三个维度满分 100：粉丝 40 / 互动率 30 / 百赞率 30。
+ * 某一段取数失败时，按「已拿到维度的满分之和」归一，并在结果里标 partial。
+ */
+
+const FAN_TIERS = [
+  [100000, 40],
+  [50000, 34],
+  [10000, 26],
+  [5000, 18],
+  [1000, 10],
+];
+const INTERACTION_TIERS = [
+  [20, 30],
+  [10, 24],
+  [5, 16],
+  [2, 8],
+];
+const HUNDRED_LIKE_TIERS = [
+  [50, 30],
+  [20, 24],
+  [10, 16],
+  [5, 8],
+];
+
+/**
+ * 按阶梯取分：命中第一个 `value >= 门槛` 的档位，否则取兜底分。
+ * @param {number} value
+ * @param {Array<[number, number]>} tiers
+ * @param {number} fallback
+ * @returns {number}
+ */
+function pickTier(value, tiers, fallback) {
+  for (const [threshold, score] of tiers) {
+    if (value >= threshold) return score;
+  }
+  return fallback;
+}
+
+function toFinite(value) {
+  // null / undefined / 空串表示「没拿到」，不能当成 0 参与打分
+  if (value === null || value === undefined || value === "") return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * 计算达人评分。
+ * @param {{fansCount?: number, interactionRate?: number, hundredLikePercent?: number}} metrics
+ * @returns {{value: number, tier: string, basis: Array<{item: string, got: number, max: number}>, partial: boolean}}
+ */
+function scoreDaren(metrics = {}) {
+  const fansCount = toFinite(metrics.fansCount);
+  const interactionRate = toFinite(metrics.interactionRate);
+  const hundredLikePercent = toFinite(metrics.hundredLikePercent);
+
+  const dims = [];
+  if (fansCount !== undefined) {
+    dims.push({ item: "粉丝数", got: pickTier(fansCount, FAN_TIERS, 4), max: 40 });
+  }
+  if (interactionRate !== undefined) {
+    dims.push({ item: "互动率", got: pickTier(interactionRate, INTERACTION_TIERS, 0), max: 30 });
+  }
+  if (hundredLikePercent !== undefined) {
+    dims.push({ item: "百赞率", got: pickTier(hundredLikePercent, HUNDRED_LIKE_TIERS, 0), max: 30 });
+  }
+
+  if (!dims.length) {
+    return { value: 0, tier: "数据不足", basis: [], partial: true };
+  }
+
+  const got = dims.reduce((sum, d) => sum + d.got, 0);
+  const max = dims.reduce((sum, d) => sum + d.max, 0);
+  const value = Math.round((got / max) * 100);
+  const tier = value >= 80 ? "头部" : value >= 55 ? "腰部" : "尾部";
+
+  return { value, tier, basis: dims, partial: dims.length < 3 };
+}
+
+module.exports = {
+  scoreDaren,
+  pickTier,
+  FAN_TIERS,
+  INTERACTION_TIERS,
+  HUNDRED_LIKE_TIERS,
+};

package/src/lib/daren-score.test.js

@@ -0,0 +1,57 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { scoreDaren, pickTier } = require("./daren-score");
+
+test("scoreDaren scores each tier boundary", () => {
+  // 头部：粉丝 10 万 + 互动率 20 + 百赞率 50 = 40+30+30
+  assert.equal(scoreDaren({ fansCount: 100000, interactionRate: 20, hundredLikePercent: 50 }).value, 100);
+  // 腰部：粉丝 1 万 + 互动率 10 + 百赞率 20 = 26+24+24 = 74
+  const waist = scoreDaren({ fansCount: 10000, interactionRate: 10, hundredLikePercent: 20 });
+  assert.equal(waist.value, 74);
+  assert.equal(waist.tier, "腰部");
+  // 尾部：粉丝 100 + 互动率 0 + 百赞率 0 = 4+0+0
+  const tail = scoreDaren({ fansCount: 100, interactionRate: 0, hundredLikePercent: 0 });
+  assert.equal(tail.value, 4);
+  assert.equal(tail.tier, "尾部");
+});
+
+test("scoreDaren falls back to the lowest band just below a threshold", () => {
+  assert.equal(pickTier(99999, [[100000, 40], [50000, 34]], 4), 34);
+  assert.equal(pickTier(999, [[1000, 10]], 4), 4);
+  assert.equal(pickTier(1.9, [[2, 8]], 0), 0);
+});
+
+test("scoreDaren normalises when a segment is missing", () => {
+  // 只有粉丝 + 互动率：40 + 30 = 70 / 70 → 100
+  const partial = scoreDaren({ fansCount: 200000, interactionRate: 25 });
+  assert.equal(partial.value, 100);
+  assert.equal(partial.partial, true);
+  // 只有粉丝 1 万：26/40 = 65 → 腰部
+  const onlyFans = scoreDaren({ fansCount: 10000 });
+  assert.equal(onlyFans.value, 65);
+  assert.equal(onlyFans.tier, "腰部");
+  assert.equal(onlyFans.basis.length, 1);
+});
+
+test("scoreDaren reports 数据不足 when nothing usable is passed", () => {
+  const empty = scoreDaren({});
+  assert.equal(empty.value, 0);
+  assert.equal(empty.tier, "数据不足");
+  assert.equal(empty.partial, true);
+  assert.deepEqual(empty.basis, []);
+
+  // 非数字（如上游给 null/undefined/空串）同样视为缺失
+  assert.equal(scoreDaren({ fansCount: null, interactionRate: "abc" }).tier, "数据不足");
+});
+
+test("scoreDaren basis keeps got/max per dimension for explainability", () => {
+  const result = scoreDaren({ fansCount: 5000, interactionRate: 5, hundredLikePercent: 10 });
+  assert.deepEqual(result.basis, [
+    { item: "粉丝数", got: 18, max: 40 },
+    { item: "互动率", got: 16, max: 30 },
+    { item: "百赞率", got: 16, max: 30 },
+  ]);
+  assert.equal(result.value, 50);
+  assert.equal(result.tier, "尾部");
+});