yuanflow-cli 0.1.3 → 0.1.5

package/src/comment-collector.js

@@ -0,0 +1,823 @@
+import { callEndpoint } from './request.js';
+
+const PRIMARY_ENDPOINTS = {
+  'douyin:comments': {
+    platform: 'douyin',
+    action: 'comments',
+    method: 'GET',
+    path: '/douyin/web/fetch_video_comments',
+    targetParam: 'aweme_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: '抖音作品一级评论',
+  },
+  'douyin:replies': {
+    platform: 'douyin',
+    action: 'replies',
+    method: 'GET',
+    path: '/douyin/web/fetch_video_comment_replies',
+    targetParam: 'item_id',
+    commentParam: 'comment_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: '抖音指定评论回复',
+  },
+  'xiaohongshu:comments': {
+    platform: 'xiaohongshu',
+    action: 'comments',
+    method: 'GET',
+    path: '/xiaohongshu/web_v3/fetch_note_comments',
+    targetParam: 'note_id',
+    cursorParam: 'cursor',
+    description: '小红书笔记一级评论',
+  },
+  'xiaohongshu:replies': {
+    platform: 'xiaohongshu',
+    action: 'replies',
+    method: 'GET',
+    path: '/xiaohongshu/web_v3/fetch_sub_comments',
+    targetParam: 'note_id',
+    commentParam: 'root_comment_id',
+    cursorParam: 'cursor',
+    countParam: 'num',
+    description: '小红书笔记二级评论',
+  },
+  'bilibili:comments': {
+    platform: 'bilibili',
+    action: 'comments',
+    method: 'GET',
+    path: '/bilibili/web/fetch_video_comments',
+    targetParam: 'bv_id',
+    pageParam: 'pn',
+    description: 'B站视频一级评论',
+  },
+  'bilibili:replies': {
+    platform: 'bilibili',
+    action: 'replies',
+    method: 'GET',
+    path: '/bilibili/web/fetch_comment_reply',
+    targetParam: 'bv_id',
+    commentParam: 'rpid',
+    pageParam: 'pn',
+    description: 'B站指定评论回复',
+  },
+  'wechat_mp:comments': {
+    platform: 'wechat_mp',
+    action: 'comments',
+    method: 'GET',
+    path: '/wechat_mp/web/fetch_mp_article_comment_list',
+    targetParam: 'url',
+    commentParam: 'comment_id',
+    cursorParam: 'buffer',
+    description: '微信公众号文章一级评论',
+  },
+  'wechat_mp:replies': {
+    platform: 'wechat_mp',
+    action: 'replies',
+    method: 'GET',
+    path: '/wechat_mp/web/fetch_mp_article_comment_reply_list',
+    targetParam: 'url',
+    commentParam: 'comment_id',
+    cursorParam: 'offset',
+    requiredExtra: ['content_id'],
+    description: '微信公众号文章评论回复',
+  },
+  'wechat_channels:comments': {
+    platform: 'wechat_channels',
+    action: 'comments',
+    method: 'POST',
+    path: '/wechat_channels/fetch_comments',
+    targetParam: 'id',
+    cursorParam: 'lastBuffer',
+    bodyMode: true,
+    description: '微信视频号一级评论',
+  },
+  'wechat_channels:replies': {
+    platform: 'wechat_channels',
+    action: 'replies',
+    method: 'POST',
+    path: '/wechat_channels/fetch_comments',
+    targetParam: 'id',
+    commentParam: 'comment_id',
+    cursorParam: 'lastBuffer',
+    bodyMode: true,
+    description: '微信视频号指定评论回复',
+  },
+  'tiktok:comments': {
+    platform: 'tiktok',
+    action: 'comments',
+    method: 'GET',
+    path: '/tiktok/web/fetch_post_comment',
+    targetParam: 'aweme_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: 'TikTok 作品一级评论',
+  },
+  'tiktok:replies': {
+    platform: 'tiktok',
+    action: 'replies',
+    method: 'GET',
+    path: '/tiktok/web/fetch_post_comment_reply',
+    targetParam: 'item_id',
+    commentParam: 'comment_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: 'TikTok 作品评论回复',
+  },
+  'instagram:comments': {
+    platform: 'instagram',
+    action: 'comments',
+    method: 'GET',
+    path: '/instagram/v2/fetch_post_comments',
+    targetParam: 'code_or_url',
+    cursorParam: 'pagination_token',
+    description: 'Instagram 帖子一级评论',
+  },
+  'instagram:replies': {
+    platform: 'instagram',
+    action: 'replies',
+    method: 'GET',
+    path: '/instagram/v2/fetch_comment_replies',
+    targetParam: 'code_or_url',
+    commentParam: 'comment_id',
+    cursorParam: 'pagination_token',
+    description: 'Instagram 帖子评论回复',
+  },
+  'kuaishou:comments': {
+    platform: 'kuaishou',
+    action: 'comments',
+    method: 'GET',
+    path: '/kuaishou/web/fetch_one_video_comment',
+    targetParam: 'photo_id',
+    cursorParam: 'pcursor',
+    description: '快手作品一级评论',
+  },
+  'kuaishou:replies': {
+    platform: 'kuaishou',
+    action: 'replies',
+    method: 'GET',
+    path: '/kuaishou/web/fetch_one_video_sub_comment',
+    targetParam: 'photo_id',
+    commentParam: 'root_comment_id',
+    cursorParam: 'pcursor',
+    description: '快手作品二级评论',
+  },
+  'reddit:comments': {
+    platform: 'reddit',
+    action: 'comments',
+    method: 'GET',
+    path: '/reddit/app/fetch_post_comments',
+    targetParam: 'post_id',
+    cursorParam: 'after',
+    description: 'Reddit 帖子一级评论',
+  },
+  'reddit:replies': {
+    platform: 'reddit',
+    action: 'replies',
+    method: 'GET',
+    path: '/reddit/app/fetch_comment_replies',
+    targetParam: 'post_id',
+    cursorParam: 'cursor',
+    requiredCursor: true,
+    description: 'Reddit 评论回复',
+  },
+  'twitter:comments': {
+    platform: 'twitter',
+    action: 'comments',
+    method: 'GET',
+    path: '/twitter/web/fetch_post_comments',
+    targetParam: 'tweet_id',
+    cursorParam: 'cursor',
+    description: 'Twitter/X 推文评论',
+  },
+  'weibo:comments': {
+    platform: 'weibo',
+    action: 'comments',
+    method: 'GET',
+    path: '/weibo/web_v2/fetch_post_comments',
+    targetParam: 'id',
+    cursorParam: 'max_id',
+    countParam: 'count',
+    description: '微博一级评论',
+  },
+  'weibo:replies': {
+    platform: 'weibo',
+    action: 'replies',
+    method: 'GET',
+    path: '/weibo/web_v2/fetch_post_sub_comments',
+    targetParam: 'id',
+    cursorParam: 'max_id',
+    countParam: 'count',
+    description: '微博子评论',
+  },
+  'youtube:comments': {
+    platform: 'youtube',
+    action: 'comments',
+    method: 'GET',
+    path: '/youtube/web/get_video_comments',
+    targetParam: 'video_id',
+    cursorParam: 'continuation_token',
+    description: 'YouTube 视频一级评论',
+  },
+  'youtube:replies': {
+    platform: 'youtube',
+    action: 'replies',
+    method: 'GET',
+    path: '/youtube/web/get_video_comment_replies',
+    targetParam: 'continuation_token',
+    description: 'YouTube 视频二级评论',
+  },
+  'youtube:post_comments': {
+    platform: 'youtube',
+    action: 'post_comments',
+    method: 'GET',
+    path: '/youtube/web_v2/get_post_comments',
+    targetParam: 'post_id',
+    cursorParam: 'continuation_token',
+    description: 'YouTube 帖子一级评论',
+  },
+  'youtube:post_replies': {
+    platform: 'youtube',
+    action: 'post_replies',
+    method: 'GET',
+    path: '/youtube/web_v2/get_post_comment_replies',
+    targetParam: 'continuation_token',
+    description: 'YouTube 帖子评论回复',
+  },
+  'zhihu:comments': {
+    platform: 'zhihu',
+    action: 'comments',
+    method: 'GET',
+    path: '/zhihu/web/fetch_comment_v5',
+    targetParam: 'answer_id',
+    cursorParam: 'offset',
+    countParam: 'limit',
+    description: '知乎回答评论区',
+  },
+  'zhihu:replies': {
+    platform: 'zhihu',
+    action: 'replies',
+    method: 'GET',
+    path: '/zhihu/web/fetch_sub_comment_v5',
+    targetParam: 'comment_id',
+    cursorParam: 'offset',
+    countParam: 'limit',
+    description: '知乎子评论区',
+  },
+};
+
+const FALLBACK_ENDPOINTS = {
+  'douyin:comments': {
+    platform: 'douyin',
+    action: 'comments',
+    method: 'GET',
+    path: '/douyin/app/v3/fetch_video_comments',
+    targetParam: 'aweme_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: '抖音作品一级评论备用 app v3 接口',
+  },
+  'douyin:replies': {
+    platform: 'douyin',
+    action: 'replies',
+    method: 'GET',
+    path: '/douyin/app/v3/fetch_video_comment_replies',
+    targetParam: 'item_id',
+    commentParam: 'comment_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: '抖音评论回复备用 app v3 接口',
+  },
+  'xiaohongshu:comments': {
+    platform: 'xiaohongshu',
+    action: 'comments',
+    method: 'GET',
+    path: '/xiaohongshu/web_v2/fetch_note_comments',
+    targetParam: 'note_id',
+    cursorParam: 'cursor',
+    description: '小红书笔记一级评论备用 web_v2 接口',
+  },
+  'xiaohongshu:replies': {
+    platform: 'xiaohongshu',
+    action: 'replies',
+    method: 'GET',
+    path: '/xiaohongshu/web_v2/fetch_sub_comments',
+    targetParam: 'note_id',
+    commentParam: 'comment_id',
+    cursorParam: 'cursor',
+    description: '小红书笔记二级评论备用 web_v2 接口',
+  },
+  'bilibili:comments': {
+    platform: 'bilibili',
+    action: 'comments',
+    method: 'GET',
+    path: '/bilibili/app/fetch_video_comments',
+    targetParam: 'bv_id',
+    cursorParam: 'next_offset',
+    description: 'B站视频一级评论备用 app 接口',
+  },
+  'tiktok:comments': {
+    platform: 'tiktok',
+    action: 'comments',
+    method: 'GET',
+    path: '/tiktok/app/v3/fetch_video_comments',
+    targetParam: 'aweme_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: 'TikTok 作品一级评论备用 app v3 接口',
+  },
+  'tiktok:replies': {
+    platform: 'tiktok',
+    action: 'replies',
+    method: 'GET',
+    path: '/tiktok/app/v3/fetch_video_comment_replies',
+    targetParam: 'item_id',
+    commentParam: 'comment_id',
+    cursorParam: 'cursor',
+    countParam: 'count',
+    description: 'TikTok 评论回复备用 app v3 接口',
+  },
+  'instagram:comments': {
+    platform: 'instagram',
+    action: 'comments',
+    method: 'GET',
+    path: '/instagram/v1/fetch_post_comments_v2',
+    targetParam: 'media_id',
+    cursorParam: 'min_id',
+    description: 'Instagram 帖子一级评论备用 v1 接口',
+  },
+  'instagram:replies': {
+    platform: 'instagram',
+    action: 'replies',
+    method: 'GET',
+    path: '/instagram/v1/fetch_comment_replies',
+    targetParam: 'media_id',
+    commentParam: 'comment_id',
+    cursorParam: 'min_id',
+    description: 'Instagram 评论回复备用 v1 接口',
+  },
+  'kuaishou:comments': {
+    platform: 'kuaishou',
+    action: 'comments',
+    method: 'GET',
+    path: '/kuaishou/app/fetch_one_video_comment',
+    targetParam: 'photo_id',
+    cursorParam: 'pcursor',
+    description: '快手作品一级评论备用 app 接口',
+  },
+  'twitter:comments': {
+    platform: 'twitter',
+    action: 'comments',
+    method: 'GET',
+    path: '/twitter/web/fetch_latest_post_comments',
+    targetParam: 'tweet_id',
+    cursorParam: 'cursor',
+    description: 'Twitter/X 最新推文评论备用接口',
+  },
+  'weibo:comments': {
+    platform: 'weibo',
+    action: 'comments',
+    method: 'GET',
+    path: '/weibo/app/fetch_status_comments',
+    targetParam: 'status_id',
+    cursorParam: 'max_id',
+    description: '微博一级评论备用 app 接口',
+  },
+  'youtube:comments': {
+    platform: 'youtube',
+    action: 'comments',
+    method: 'GET',
+    path: '/youtube/web_v2/get_video_comments',
+    targetParam: 'video_id',
+    cursorParam: 'continuation_token',
+    description: 'YouTube 视频一级评论备用 web_v2 接口',
+  },
+  'youtube:replies': {
+    platform: 'youtube',
+    action: 'replies',
+    method: 'GET',
+    path: '/youtube/web_v2/get_video_comment_replies',
+    targetParam: 'continuation_token',
+    description: 'YouTube 视频二级评论备用 web_v2 接口',
+  },
+};
+
+const PLATFORM_ALIASES = {
+  抖音: 'douyin',
+  douyin: 'douyin',
+  小红书: 'xiaohongshu',
+  xiaohongshu: 'xiaohongshu',
+  xhs: 'xiaohongshu',
+  B站: 'bilibili',
+  b站: 'bilibili',
+  哔哩哔哩: 'bilibili',
+  bilibili: 'bilibili',
+  微信公众号: 'wechat_mp',
+  公众号: 'wechat_mp',
+  wechat_mp: 'wechat_mp',
+  微信视频号: 'wechat_channels',
+  视频号: 'wechat_channels',
+  wechat_channels: 'wechat_channels',
+  TikTok: 'tiktok',
+  tiktok: 'tiktok',
+  Instagram: 'instagram',
+  instagram: 'instagram',
+  ins: 'instagram',
+  快手: 'kuaishou',
+  kuaishou: 'kuaishou',
+  Reddit: 'reddit',
+  reddit: 'reddit',
+  Twitter: 'twitter',
+  'Twitter/X': 'twitter',
+  'twitter/x': 'twitter',
+  twitter: 'twitter',
+  X: 'twitter',
+  x: 'twitter',
+  微博: 'weibo',
+  weibo: 'weibo',
+  YouTube: 'youtube',
+  youtube: 'youtube',
+  油管: 'youtube',
+  知乎: 'zhihu',
+  zhihu: 'zhihu',
+};
+
+export function listCommentCommands() {
+  return Object.values(PRIMARY_ENDPOINTS).map((endpoint) => ({
+    key: `comments.${endpoint.platform}.${endpoint.action}`,
+    command: `comments collect --platform ${endpoint.platform} --action ${endpoint.action}`,
+    kind: 'comment-collector',
+    description: endpoint.description,
+    method: endpoint.method,
+    socialPath: endpoint.path,
+    positionals: [],
+    options: buildCommentCommandOptions(endpoint),
+    queryParams: buildCommentCommandQueryParams(endpoint),
+    requestBody: endpoint.bodyMode ? buildCommentCommandRequestBody(endpoint) : null,
+    returns: '返回评论列表、翻页游标和平台原始响应字段，字段以上游接口实际响应为准。',
+  }));
+}
+
+function buildCommentCommandOptions(endpoint) {
+  const options = [
+    {
+      flag: '--platform',
+      name: 'platform',
+      required: true,
+      label: '平台标识，例如 douyin、xiaohongshu、bilibili。',
+    },
+    {
+      flag: '--action',
+      name: 'action',
+      required: false,
+      label: '评论类型：comments、replies、post_comments 或 post_replies。',
+    },
+    {
+      flag: '--target',
+      name: 'target',
+      required: true,
+      label: '作品、文章、帖子或回答 ID，也可以传支持的平台链接。',
+    },
+    {
+      flag: '--prefer',
+      name: 'prefer',
+      required: false,
+      label: 'primary 使用首选接口，fallback 使用备用接口。',
+    },
+    {
+      flag: '--format',
+      name: 'format',
+      required: false,
+      label: 'Agent 调用时建议使用 agent-json。',
+    },
+    {
+      flag: '--dry-run',
+      name: 'dryRun',
+      required: false,
+      label: '仅返回请求映射，不发起真实接口请求。',
+    },
+  ];
+  if (endpoint.commentParam) {
+    options.push({
+      flag: '--comment-id',
+      name: 'commentId',
+      required: true,
+      label: '父评论 ID，采集评论回复时必填。',
+    });
+  }
+  if (endpoint.cursorParam) {
+    options.push({
+      flag: '--cursor',
+      name: 'cursor',
+      required: Boolean(endpoint.requiredCursor),
+      label: '翻页游标，按上一次响应返回字段继续传。',
+    });
+  }
+  if (endpoint.countParam) {
+    options.push({
+      flag: '--count',
+      name: 'count',
+      required: false,
+      label: '返回数量，仅对支持 count/num 的接口生效。',
+    });
+  }
+  if (endpoint.pageParam) {
+    options.push({
+      flag: '--page',
+      name: 'page',
+      required: false,
+      label: '页码，仅对分页页码型接口生效。',
+    });
+  }
+  if (endpoint.requiredExtra?.length) {
+    options.push({
+      flag: '--extra',
+      name: 'extra',
+      required: true,
+      label: `JSON 字符串补充参数，必须包含：${endpoint.requiredExtra.join(', ')}。`,
+    });
+  } else {
+    options.push({
+      flag: '--extra',
+      name: 'extra',
+      required: false,
+      label: 'JSON 字符串补充参数，用于平台特殊字段。',
+    });
+  }
+  return options;
+}
+
+function buildCommentCommandQueryParams(endpoint) {
+  const params = [
+    {
+      name: endpoint.targetParam,
+      required: true,
+      description: '由 --target 映射得到。',
+    },
+  ];
+  if (endpoint.commentParam) {
+    params.push({
+      name: endpoint.commentParam,
+      required: true,
+      description: '由 --comment-id 映射得到。',
+    });
+  }
+  if (endpoint.cursorParam) {
+    params.push({
+      name: endpoint.cursorParam,
+      required: Boolean(endpoint.requiredCursor),
+      description: '由 --cursor 或 --extra 映射得到。',
+    });
+  }
+  if (endpoint.countParam) {
+    params.push({
+      name: endpoint.countParam,
+      required: false,
+      description: '由 --count 映射得到。',
+    });
+  }
+  if (endpoint.pageParam) {
+    params.push({
+      name: endpoint.pageParam,
+      required: false,
+      description: '由 --page 映射得到。',
+    });
+  }
+  return params;
+}
+
+function buildCommentCommandRequestBody(endpoint) {
+  const body = {};
+  for (const item of buildCommentCommandQueryParams(endpoint)) {
+    body[item.name] = item.required ? `<${item.name}>` : '';
+  }
+  return body;
+}
+
+export function normalizePlatform(value) {
+  const raw = String(value || '').trim();
+  return PLATFORM_ALIASES[raw] || raw.toLowerCase();
+}
+
+export function normalizeAction(value, platform = '') {
+  const raw = String(value || 'comments').trim().toLowerCase();
+  if (
+    [
+      'post_comments',
+      'post-comments',
+      'youtube_post_comments',
+      'youtube-post-comments',
+      '社区帖子评论',
+    ].includes(raw)
+  ) {
+    return 'post_comments';
+  }
+  if (
+    [
+      'post_replies',
+      'post-replies',
+      'youtube_post_replies',
+      'youtube-post-replies',
+      '帖子评论回复',
+      '帖子回复',
+    ].includes(raw)
+  ) {
+    return 'post_replies';
+  }
+  if (raw === '帖子评论') {
+    return platform === 'youtube' ? 'post_comments' : 'comments';
+  }
+  if (
+    [
+      'reply',
+      'replies',
+      'sub_comments',
+      'sub-comments',
+      '二级评论',
+      '子评论',
+      '评论回复',
+      '回复',
+    ].includes(raw)
+  ) {
+    return 'replies';
+  }
+  return 'comments';
+}
+
+export function extractTargetId(platform, target) {
+  const raw = String(target || '').trim();
+  if (!raw) {
+    return '';
+  }
+  if (platform === 'wechat_mp') {
+    return raw;
+  }
+  if (platform === 'instagram' && raw.startsWith('http')) {
+    return raw;
+  }
+  if (platform === 'bilibili') {
+    const match = raw.match(/BV[0-9A-Za-z]+/);
+    if (match) {
+      return match[0];
+    }
+  }
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return raw;
+  }
+  for (const key of [
+    'v',
+    'aweme_id',
+    'note_id',
+    'bv_id',
+    'bvid',
+    'id',
+    'video_id',
+    'item_id',
+    'tweet_id',
+    'post_id',
+    'photo_id',
+    'media_id',
+    'code',
+    'answer_id',
+  ]) {
+    const value = parsed.searchParams.get(key);
+    if (value) {
+      return value.trim();
+    }
+  }
+  const pathParts = parsed.pathname.split('/').filter(Boolean);
+  if (platform === 'reddit' && pathParts.includes('comments')) {
+    const index = pathParts.indexOf('comments');
+    if (pathParts[index + 1]) {
+      const postId = pathParts[index + 1];
+      return postId.startsWith('t3_') ? postId : `t3_${postId}`;
+    }
+  }
+  for (const part of pathParts.reverse()) {
+    if (part && !['video', 'note', 'discovery', 'explore'].includes(part)) {
+      return part;
+    }
+  }
+  return raw;
+}
+
+export function resolveCommentEndpoint(platform, action, prefer = 'primary') {
+  const key = `${platform}:${action}`;
+  if (prefer === 'fallback' && FALLBACK_ENDPOINTS[key]) {
+    return { endpoint: FALLBACK_ENDPOINTS[key], usedFallback: true };
+  }
+  return { endpoint: PRIMARY_ENDPOINTS[key] || null, usedFallback: false };
+}
+
+export function buildCommentRequest(endpoint, { target, options }) {
+  const payload = { [endpoint.targetParam]: target };
+  const commentId = cleanOptional(options.named?.['comment-id']);
+  if (endpoint.commentParam && commentId !== undefined) {
+    payload[endpoint.commentParam] = commentId;
+  }
+  let cursor = cleanOptional(options.named?.cursor);
+  const extra = parseExtra(options.named?.extra);
+  if (cursor === undefined && endpoint.cursorParam) {
+    cursor = cleanOptional(extra[endpoint.cursorParam]);
+  }
+  if (endpoint.cursorParam && cursor !== undefined) {
+    payload[endpoint.cursorParam] = cursor;
+  }
+  const count = cleanOptional(options.named?.count);
+  if (endpoint.countParam && count !== undefined) {
+    payload[endpoint.countParam] = Number(count);
+  }
+  const page = cleanOptional(options.named?.page);
+  if (endpoint.pageParam && page !== undefined) {
+    payload[endpoint.pageParam] = Number(page);
+  }
+  for (const key of endpoint.requiredExtra || []) {
+    const value = cleanOptional(extra[key]);
+    if (value !== undefined) {
+      payload[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(extra)) {
+    const cleaned = cleanOptional(value);
+    if (!(key in payload) && cleaned !== undefined) {
+      payload[key] = cleaned;
+    }
+  }
+  return payload;
+}
+
+export async function collectComments({ platform, action, target, prefer, options }) {
+  const normalizedPlatform = normalizePlatform(platform);
+  const normalizedAction = normalizeAction(action, normalizedPlatform);
+  const { endpoint, usedFallback } = resolveCommentEndpoint(normalizedPlatform, normalizedAction, prefer);
+  if (!endpoint) {
+    throw new Error(`当前平台或评论类型暂未接入：${normalizedPlatform} ${normalizedAction}`);
+  }
+  const targetId = extractTargetId(normalizedPlatform, target);
+  if (!targetId) {
+    throw new Error('请提供作品、文章或视频号目标 ID/链接。');
+  }
+  if (endpoint.commentParam && cleanOptional(options.named?.['comment-id']) === undefined) {
+    throw new Error('采集二级评论时必须提供 --comment-id。');
+  }
+  if (endpoint.requiredCursor && cleanOptional(options.named?.cursor) === undefined) {
+    throw new Error('该平台采集二级评论时必须提供 --cursor。');
+  }
+  const extra = parseExtra(options.named?.extra);
+  const missingExtra = (endpoint.requiredExtra || []).filter((key) => cleanOptional(extra[key]) === undefined);
+  if (missingExtra.length > 0) {
+    throw new Error(`缺少必要补充参数：${missingExtra.join(', ')}。`);
+  }
+  const body = buildCommentRequest(endpoint, { target: targetId, options });
+  const response = await callEndpoint(endpoint.path, {
+    ...options,
+    method: endpoint.method,
+    body,
+  });
+  return {
+    ok: true,
+    platform: normalizedPlatform,
+    action: normalizedAction,
+    target: targetId,
+    endpoint: {
+      method: endpoint.method,
+      path: endpoint.path,
+      description: endpoint.description,
+    },
+    usedFallback,
+    request: {
+      params: endpoint.bodyMode ? undefined : body,
+      body: endpoint.bodyMode ? body : undefined,
+    },
+    response,
+  };
+}
+
+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 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 {};
+  }
+}