yuanflow-cli 0.1.5 → 0.1.7

package/src/work-tools.js

@@ -0,0 +1,344 @@
+import { callEndpoint } from './request.js';
+import { extractTargetId, normalizePlatform } from './comment-collector.js';
+
+import {
+  CONTENT_SEARCH_ENDPOINTS,
+  DETAIL_ENDPOINTS,
+  DOWNLOAD_ENDPOINTS,
+  USER_SEARCH_ENDPOINTS,
+} from './work-tool-definitions.js';
+
+export function listWorkCommands() {
+  return [
+    ...Object.keys(DETAIL_ENDPOINTS).map((platform) =>
+      workCommand(platform, 'detail', firstPrimary(DETAIL_ENDPOINTS[platform]), 'work-detail'),
+    ),
+    ...Object.keys(DOWNLOAD_ENDPOINTS).map((platform) =>
+      workCommand(platform, 'download', firstPrimary(DOWNLOAD_ENDPOINTS[platform]), 'work-download'),
+    ),
+  ];
+}
+
+export function listSearchCommands() {
+  return [
+    ...Object.keys(CONTENT_SEARCH_ENDPOINTS).map((platform) =>
+      searchCommand(platform, 'content', CONTENT_SEARCH_ENDPOINTS[platform], 'content-search'),
+    ),
+    ...Object.keys(USER_SEARCH_ENDPOINTS).map((platform) =>
+      searchCommand(platform, 'users', USER_SEARCH_ENDPOINTS[platform], 'user-search'),
+    ),
+  ];
+}
+
+export async function getWorkDetail({ platform, target, prefer = 'primary', kind, targetKind, options }) {
+  return callWorkEndpoint({
+    endpoints: DETAIL_ENDPOINTS,
+    action: 'detail',
+    platform,
+    target,
+    prefer,
+    kind,
+    targetKind,
+    options,
+  });
+}
+
+export async function getWorkDownload({ platform, target, prefer = 'primary', kind, targetKind, options }) {
+  return callWorkEndpoint({
+    endpoints: DOWNLOAD_ENDPOINTS,
+    action: 'download',
+    platform,
+    target,
+    prefer,
+    kind,
+    targetKind,
+    options,
+  });
+}
+
+export async function searchContent({ platform, keyword, options }) {
+  return callSearchEndpoint({
+    endpoints: CONTENT_SEARCH_ENDPOINTS,
+    action: 'content',
+    kind: 'content-search',
+    platform,
+    keyword,
+    options,
+  });
+}
+
+export async function searchUsers({ platform, keyword, options }) {
+  return callSearchEndpoint({
+    endpoints: USER_SEARCH_ENDPOINTS,
+    action: 'users',
+    kind: 'user-search',
+    platform,
+    keyword,
+    options,
+  });
+}
+
+async function callWorkEndpoint({ endpoints, action, platform, target, prefer, kind, targetKind, options }) {
+  const normalizedPlatform = normalizeWorkPlatform(platform);
+  const candidates = endpoints[normalizedPlatform] || [];
+  const endpoint = selectWorkEndpoint(candidates, { target, prefer, kind, targetKind });
+  if (!endpoint) {
+    throw new Error(`当前平台暂未接入作品${action === 'detail' ? '详情' : '下载'}工具：${normalizedPlatform}`);
+  }
+  validateRequiredOptions(endpoint, options);
+  const targetValue = resolveTargetValue(normalizedPlatform, endpoint, target);
+  if (!targetValue) {
+    throw new Error('请提供作品链接或作品 ID。');
+  }
+  const body = buildPayload(endpoint, endpoint.targetParam, targetValue, options);
+  const response = await callEndpoint(endpoint.path, {
+    ...options,
+    method: endpoint.method,
+    body,
+  });
+  return {
+    ok: true,
+    platform: normalizedPlatform,
+    action,
+    target: targetValue,
+    endpoint: endpointSummary(endpoint),
+    request: endpoint.bodyMode ? { body } : { params: body },
+    response,
+  };
+}
+
+async function callSearchEndpoint({ endpoints, action, kind, platform, keyword, options }) {
+  const normalizedPlatform = normalizeWorkPlatform(platform);
+  const endpoint = endpoints[normalizedPlatform];
+  if (!endpoint) {
+    throw new Error(`当前平台暂未接入${action === 'content' ? '综合搜索' : '用户搜索'}工具：${normalizedPlatform}`);
+  }
+  const cleanedKeyword = cleanOptional(keyword);
+  if (!cleanedKeyword) {
+    throw new Error('缺少 --keyword 或关键词位置参数。');
+  }
+  const body = buildPayload(endpoint, endpoint.keywordParam, cleanedKeyword, options);
+  const response = await callEndpoint(endpoint.path, {
+    ...options,
+    method: endpoint.method,
+    body,
+  });
+  return {
+    ok: true,
+    platform: normalizedPlatform,
+    action,
+    keyword: cleanedKeyword,
+    endpoint: endpointSummary(endpoint, kind),
+    request: endpoint.bodyMode ? { body } : { params: body },
+    response,
+  };
+}
+
+function workCommand(platform, action, endpoint, kind) {
+  return {
+    key: `works.${platform}.${action}`,
+    command: `works ${action} --platform ${platform}`,
+    kind,
+    description: endpoint.description,
+    method: endpoint.method,
+    socialPath: endpoint.path,
+    positionals: [],
+    options: buildWorkOptions(endpoint, action),
+    queryParams: endpoint.bodyMode ? [] : buildCommandParams(endpoint, 'target'),
+    requestBody: endpoint.bodyMode ? requestBodyExample(endpoint, 'target') : null,
+    returns:
+      action === 'download'
+        ? '返回作品可播放媒体信息、下载地址候选或视频流信息，字段以上游实际响应为准。'
+        : '返回作品详情、作者信息、正文/标题、互动统计和媒体信息，字段以上游实际响应为准。',
+  };
+}
+
+function searchCommand(platform, action, endpoint, kind) {
+  return {
+    key: `search.${platform}.${action}`,
+    command: `search ${action} --platform ${platform}`,
+    kind,
+    description: endpoint.description,
+    method: endpoint.method,
+    socialPath: endpoint.path,
+    positionals: [],
+    options: buildSearchOptions(endpoint, action),
+    queryParams: endpoint.bodyMode ? [] : buildCommandParams(endpoint, 'keyword'),
+    requestBody: endpoint.bodyMode ? requestBodyExample(endpoint, 'keyword') : null,
+    returns:
+      action === 'users'
+        ? '返回用户/频道搜索结果、分页字段和平台原始摘要字段，字段以上游实际响应为准。'
+        : '返回内容搜索结果、分页字段和平台原始摘要字段，字段以上游实际响应为准。',
+  };
+}
+
+function buildWorkOptions(endpoint, action) {
+  const options = [
+    { flag: '--platform', name: 'platform', required: true, label: '平台标识，例如 douyin、youtube、bilibili。' },
+    { flag: '--target', name: 'target', required: true, label: '作品链接、分享链接或作品 ID。' },
+    { flag: '--prefer', name: 'prefer', required: false, label: '接口偏好：primary、fallback；YouTube 下载可用 signed。' },
+    { flag: '--kind', name: 'kind', required: false, label: '内容类型，例如 video、post、article、question。' },
+    { flag: '--target-kind', name: 'targetKind', required: false, label: '目标 ID 类型，例如 Instagram 的 code 或 media_id。' },
+    { flag: '--extra', name: 'extra', required: false, label: 'JSON 字符串补充参数，会合并进请求参数。' },
+    { flag: '--format', name: 'format', required: false, label: 'Agent 调用时建议使用 agent-json。' },
+    { flag: '--dry-run', name: 'dryRun', required: false, label: '仅返回请求映射，不发起真实接口请求。' },
+  ];
+  for (const flag of Object.keys(endpoint.optionParams || {})) {
+    options.push({
+      flag: `--${flag}`,
+      name: flag,
+      required: (endpoint.requiredOptions || []).includes(flag),
+      label: `${action === 'download' ? '下载' : '详情'}接口补充参数：${endpoint.optionParams[flag]}。`,
+    });
+  }
+  return options;
+}
+
+function buildSearchOptions(endpoint) {
+  const options = [
+    { flag: '--platform', name: 'platform', required: true, label: '平台标识，例如 douyin、xiaohongshu、instagram。' },
+    { flag: '--keyword', name: 'keyword', required: true, label: '搜索关键词。' },
+    { flag: '--extra', name: 'extra', required: false, label: 'JSON 字符串补充参数，会合并进请求参数。' },
+    { flag: '--format', name: 'format', required: false, label: 'Agent 调用时建议使用 agent-json。' },
+    { flag: '--dry-run', name: 'dryRun', required: false, label: '仅返回请求映射，不发起真实接口请求。' },
+  ];
+  for (const flag of Object.keys(endpoint.optionParams || {})) {
+    options.push({
+      flag: `--${flag}`,
+      name: flag,
+      required: false,
+      label: `搜索接口补充参数：${endpoint.optionParams[flag]}。`,
+    });
+  }
+  return options;
+}
+
+function buildCommandParams(endpoint, mainName) {
+  const mainParam = endpoint.targetParam || endpoint.keywordParam;
+  const params = [{ name: mainParam, required: true, description: `由 --${mainName} 映射得到。` }];
+  for (const paramName of Object.values(endpoint.optionParams || {})) {
+    params.push({ name: paramName, required: (endpoint.requiredOptions || []).includes(paramName), description: '由同名 CLI 参数或 --extra 映射得到。' });
+  }
+  return params;
+}
+
+function requestBodyExample(endpoint, mainName) {
+  const mainParam = endpoint.targetParam || endpoint.keywordParam;
+  return {
+    ...(endpoint.defaults || {}),
+    [mainParam]: `<${mainName}>`,
+  };
+}
+
+function firstPrimary(endpoints) {
+  return endpoints.find((endpoint) => !endpoint.prefer) || endpoints[0];
+}
+
+function selectWorkEndpoint(candidates, { target, prefer, kind, targetKind }) {
+  const urlTarget = looksLikeUrl(target);
+  const preferred = candidates.filter((endpoint) => {
+    if (prefer && prefer !== 'primary') {
+      return endpoint.prefer === prefer;
+    }
+    return !endpoint.prefer;
+  });
+  const pool = preferred.length > 0 ? preferred : candidates;
+  return (
+    pool.find((endpoint) => kind && endpoint.kind === kind) ||
+    pool.find((endpoint) => targetKind && endpoint.targetKind === targetKind) ||
+    pool.find((endpoint) => urlTarget && ['raw-url', 'raw'].includes(endpoint.targetMode)) ||
+    pool.find((endpoint) => !urlTarget && endpoint.targetMode === 'id') ||
+    pool[0]
+  );
+}
+
+function resolveTargetValue(platform, endpoint, target) {
+  if (endpoint.targetMode === 'raw' || endpoint.targetMode === 'raw-url') {
+    return String(target || '').trim();
+  }
+  return extractTargetId(platform, target);
+}
+
+function buildPayload(endpoint, mainParam, mainValue, options) {
+  const payload = { ...(endpoint.defaults || {}), [mainParam]: mainValue };
+  for (const [flag, param] of Object.entries(endpoint.optionParams || {})) {
+    const value = cleanOptional(options.named?.[flag]);
+    if (value !== undefined) {
+      payload[param] = normalizeValue(value);
+    }
+  }
+  for (const [key, value] of Object.entries(parseExtra(options.named?.extra))) {
+    const cleaned = cleanOptional(value);
+    if (cleaned !== undefined) {
+      payload[key] = normalizeValue(cleaned);
+    }
+  }
+  return payload;
+}
+
+function validateRequiredOptions(endpoint, options) {
+  const missing = (endpoint.requiredOptions || []).filter((flag) => cleanOptional(options.named?.[flag]) === undefined);
+  if (missing.length > 0) {
+    throw new Error(`缺少必要参数：${missing.map((item) => `--${item}`).join(', ')}。`);
+  }
+}
+
+function endpointSummary(endpoint, kind = '') {
+  return {
+    method: endpoint.method,
+    path: endpoint.path,
+    description: endpoint.description,
+    ...(kind ? { kind } : {}),
+  };
+}
+
+function normalizeWorkPlatform(value) {
+  const normalized = normalizePlatform(value);
+  if (['wechat', 'channels', 'wechat_channels', '微信视频号', '视频号'].includes(normalized)) {
+    return 'wechat_channels';
+  }
+  if (['mp', 'wechat_mp', '微信公众号', '公众号'].includes(normalized)) {
+    return 'wechat_mp';
+  }
+  return normalized;
+}
+
+function looksLikeUrl(value) {
+  return /^https?:\/\//i.test(String(value || '').trim());
+}
+
+function cleanOptional(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  return value;
+}
+
+function normalizeValue(value) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  if (/^-?\d+$/.test(value)) {
+    return Number(value);
+  }
+  return value;
+}
+
+function parseExtra(value) {
+  if (!value) {
+    return {};
+  }
+  if (typeof value === 'object') {
+    return value;
+  }
+  try {
+    const parsed = JSON.parse(String(value));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}