nolo-cli 0.1.40 → 0.1.42

package/ai/tools/readXhsProfileTool.ts

@@ -0,0 +1,638 @@
+/**
+ * read_xhs_profile Tool
+ *
+ * Read-only tool for collecting XHS (Xiaohongshu) profile data:
+ * anonymous public profile info and public notes visible without login.
+ *
+ * Anonymous-only: does not use XHS login state, cookies, or persistent profile.
+ * No write actions (no like/comment/follow/collect/post/delete).
+ * Cookies and xsecToken are never exposed in output.
+ * Conservative by default: reads the initially loaded profile state only.
+ * Extra scrolling requires explicit user intent. Direct detail/comment API
+ * enrichment is disabled so reads stay close to visible desktop browsing.
+ * The tool clamps extended collection unless extendedCollectionConsent is true.
+ */
+
+import { createXhsFailure } from "../../integrations/xhs-reader/types";
+import type {
+  XhsReadResult,
+  XhsProfileCollection,
+  XhsCollectionStatus,
+  XhsParsedProfileUrl,
+} from "../../integrations/xhs-reader/types";
+import { redactXhsSensitiveValue } from "../../integrations/xhs-reader/redaction";
+import { parseXhsProfileUrl } from "../../integrations/xhs-reader/url";
+import { getRequestConfig, ToolApiError } from "./toolApiClient";
+
+export const readXhsProfileFunctionSchema = {
+  name: "read_xhs_profile",
+  description:
+    "以未登录匿名访客身份读取小红书用户主页的公开可见信息。默认只读取页面初始加载出的资料和笔记列表，不自动翻页，不抓评论或批量详情。只有当用户明确要求更多笔记/翻页时，才可显式请求一次可见页面滚动。不会使用账号、cookie 或持久浏览器 profile。",
+  parameters: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description:
+          "小红书用户主页 URL，例如 https://www.xiaohongshu.com/user/profile/5d2be8720000000010007556。用户从首页/feed 复制的 profile 链接可以带 xsec_token/xsec_source；token 只用于匿名桌面导航，输出会脱敏。",
+      },
+      maxScrollPages: {
+        type: "number",
+        description:
+          "最大滚动翻页数。默认 0，即只读取页面初始加载状态；只有用户明确要求更多笔记且 extendedCollectionConsent=true 时才设置为 1 或更高。",
+        default: 0,
+      },
+      includeComments: {
+        type: "boolean",
+        description:
+          "是否读取匿名公开笔记详情页首屏可见评论。只有 extendedCollectionConsent=true、collectionMode=\"assisted\"、assistedAction=\"read_visible_details\" 时才会生效；不会通过直接 API 收集评论。",
+        default: false,
+      },
+      maxCommentPagesPerNote: {
+        type: "number",
+        description:
+          "保留兼容字段，当前固定为 1 且不会触发评论采集。",
+        default: 1,
+      },
+      minLikesForDetail: {
+        type: "number",
+        description:
+          "已停用：不再通过直接 API 收集笔记详情。",
+      },
+      minCommentsForCollect: {
+        type: "number",
+        description:
+          "已停用：不再通过直接 API 收集评论。",
+      },
+      extendedCollectionConsent: {
+        type: "boolean",
+        description:
+          "扩展采集确认开关。只有用户在本轮明确要求更多笔记、翻页、公开笔记详情或首屏评论时才可设为 true；否则必须省略或为 false。匿名模式不会采集登录后内容。",
+        default: false,
+      },
+      collectionMode: {
+        type: "string",
+        enum: ["conservative", "assisted"],
+        description:
+          "采集模式。默认 conservative；assisted 需要 extendedCollectionConsent=true。",
+        default: "conservative",
+      },
+      assistedAction: {
+        type: "string",
+        enum: ["snapshot", "read_more_notes", "read_visible_details", "discover_indexed_notes"],
+        description:
+          "assisted 模式下的具体动作：snapshot 只读快照，read_more_notes 最多做一次可见页面滚动，read_visible_details 匿名打开最多 3 条公开笔记页读取页面可见详情和首屏评论，discover_indexed_notes 读取外部搜索索引发现的公开笔记 URL。",
+        default: "snapshot",
+      },
+      indexedNoteUrls: {
+        type: "array",
+        items: { type: "string" },
+        description:
+          "外部搜索索引发现的公开小红书笔记 URL（xiaohongshu.com/explore/...）。仅当 assistedAction=\"discover_indexed_notes\" 且 extendedCollectionConsent=true 时生效，最多读取 3 条；不要填搜索页 URL。",
+      },
+      maxAssistedSteps: {
+        type: "number",
+        description:
+          "assisted 模式最大步数。当前固定为 1，只允许一次可见页面滚动。",
+        default: 1,
+        minimum: 1,
+        maximum: 1,
+      },
+      headless: {
+        type: "boolean",
+        description:
+          "是否用 headless 模式启动匿名浏览器。默认 false，优先打开可见桌面浏览器。",
+        default: false,
+      },
+    },
+    required: ["url"],
+  },
+};
+
+type ReadXhsProfileToolContext = {
+  reader?: (
+    options: ReadXhsProfileArgs,
+  ) => Promise<XhsReadResult<XhsProfileCollection>>;
+};
+
+export interface ReadXhsProfileArgs {
+  url: string;
+  maxScrollPages?: number;
+  includeComments?: boolean;
+  maxCommentPagesPerNote?: number;
+  minLikesForDetail?: number;
+  minCommentsForCollect?: number;
+  extendedCollectionConsent?: boolean;
+  headless?: boolean;
+  collectionMode?: "conservative" | "assisted";
+  assistedAction?: "snapshot" | "read_more_notes" | "read_visible_details" | "discover_indexed_notes";
+  maxAssistedSteps?: number;
+  indexedNoteUrls?: string[];
+}
+
+export function normalizeXhsProfileReadArgs(
+  args: ReadXhsProfileArgs,
+): ReadXhsProfileArgs {
+  const consent = args.extendedCollectionConsent === true;
+
+  if (!consent) {
+    // No consent → force conservative behavior
+    return {
+      ...args,
+      maxScrollPages: 0,
+      includeComments: false,
+      maxCommentPagesPerNote: 1,
+      minLikesForDetail: undefined,
+      minCommentsForCollect: undefined,
+      extendedCollectionConsent: false,
+      collectionMode: "conservative",
+      assistedAction: "snapshot",
+      maxAssistedSteps: 1,
+    };
+  }
+
+  // Consent granted → determine mode
+  const mode = args.collectionMode === "assisted" ? "assisted" : "conservative";
+  const action = args.assistedAction ?? "snapshot";
+  const steps = 1;
+
+  if (mode === "conservative") {
+    // Consent alone is not enough for extended collection. The model must
+    // explicitly select assisted mode so status labels match actual behavior.
+    return {
+      ...args,
+      maxScrollPages: 0,
+      includeComments: false,
+      maxCommentPagesPerNote: 1,
+      minLikesForDetail: undefined,
+      minCommentsForCollect: undefined,
+      extendedCollectionConsent: true,
+      collectionMode: "conservative",
+      assistedAction: "snapshot",
+      maxAssistedSteps: steps,
+    };
+  }
+
+  // Assisted mode with consent: clamp based on action
+  let maxScrollPages = args.maxScrollPages;
+  let includeComments = args.includeComments;
+  let maxCommentPagesPerNote = args.maxCommentPagesPerNote;
+
+  if (action === "read_more_notes") {
+    maxScrollPages = clamp(maxScrollPages ?? steps, 1, steps);
+    includeComments = false;
+  } else if (action === "read_visible_details") {
+    maxScrollPages = 0;
+    includeComments = true;
+    maxCommentPagesPerNote = 3;
+  } else if (action === "discover_indexed_notes") {
+    maxScrollPages = 0;
+    includeComments = true;
+    maxCommentPagesPerNote = 3;
+  } else {
+    // snapshot: no scrolling, no comments
+    maxScrollPages = 0;
+    includeComments = false;
+    maxCommentPagesPerNote = 1;
+  }
+
+  return {
+    ...args,
+    maxScrollPages,
+    includeComments,
+    maxCommentPagesPerNote,
+    minLikesForDetail: undefined,
+    minCommentsForCollect: undefined,
+    extendedCollectionConsent: true,
+    collectionMode: mode,
+    assistedAction: action,
+    maxAssistedSteps: steps,
+    indexedNoteUrls: action === "discover_indexed_notes"
+      ? (args.indexedNoteUrls ?? []).slice(0, 3)
+      : undefined,
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function assertXhsProfileUrl(url: string): XhsParsedProfileUrl {
+  // Reuse parseXhsProfileUrl for validation
+  try {
+    return parseXhsProfileUrl(url);
+  } catch {
+    throw new Error(
+      "read_xhs_profile 需要一个有效的小红书用户主页 URL（xiaohongshu.com/user/profile/<24位hexID>）。",
+    );
+  }
+}
+
+async function callLocalReadXhsProfileApi(
+  thunkApi: any,
+  body: object,
+): Promise<XhsReadResult<XhsProfileCollection>> {
+  const { currentServer, token } = getRequestConfig(thunkApi);
+  const browserOrigin = (globalThis as any).window?.location?.origin;
+  const baseUrl =
+    typeof browserOrigin === "string" && browserOrigin
+      ? browserOrigin
+      : currentServer.replace(/\/+$/, "");
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const response = await fetch(`${baseUrl}/api/read-xhs-profile`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let data: any = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+  if (!response.ok) {
+    throw new ToolApiError(
+      data?.error?.message ??
+        `read_xhs_profile API 请求失败，状态码: ${response.status}`,
+      {
+        status: response.status,
+        code: data?.error?.code,
+        details: data,
+      },
+    );
+  }
+  return data as XhsReadResult<XhsProfileCollection>;
+}
+
+async function callDesktopReadXhsProfileApi(
+  thunkApi: any,
+  body: object,
+): Promise<XhsReadResult<XhsProfileCollection>> {
+  const { token } = getRequestConfig(thunkApi);
+  const port = Number(process.env.NOLO_DESKTOP_SERVER_PORT ?? 3233);
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const response = await fetch(
+    `http://127.0.0.1:${port}/api/read-xhs-profile`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    },
+  );
+  const text = await response.text();
+  let data: any = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+  if (!response.ok) {
+    throw new ToolApiError(
+      data?.error?.message ??
+        `desktop read_xhs_profile API 请求失败，状态码: ${response.status}`,
+      {
+        status: response.status,
+        code: data?.error?.code,
+        details: data,
+      },
+    );
+  }
+  return data as XhsReadResult<XhsProfileCollection>;
+}
+
+async function readWithDefaultBridge(
+  args: ReadXhsProfileArgs,
+  thunkApi?: any,
+): Promise<XhsReadResult<XhsProfileCollection>> {
+  if (process.env.PLATFORM === "web") {
+    if (thunkApi?.getState) {
+      return callLocalReadXhsProfileApi(thunkApi, args);
+    }
+
+    if (typeof window !== "undefined" && (window as any).__NOLO_DESKTOP__) {
+      try {
+        const res = await fetch("/api/read-xhs-profile", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(args),
+        });
+        const data = await res.json().catch(() => null);
+        if (res.ok && data) {
+          return data as XhsReadResult<XhsProfileCollection>;
+        }
+        return createXhsFailure({
+          code: "network_error",
+          message: `desktop read_xhs_profile endpoint failed: HTTP ${res.status}`,
+        });
+      } catch (error) {
+        return createXhsFailure({
+          code: "network_error",
+          message:
+            error instanceof Error
+              ? error.message
+              : "desktop read_xhs_profile endpoint request failed",
+        });
+      }
+    }
+
+    return createXhsFailure({
+      code: "network_error",
+      message:
+        "read_xhs_profile 需要通过服务器或桌面本地 bridge 执行，不能在普通浏览器 bundle 内直接启动 Playwright。",
+    });
+  }
+
+  if (process.env.NOLO_DESKTOP === "1" && thunkApi?.getState) {
+    return callDesktopReadXhsProfileApi(thunkApi, args);
+  }
+
+  // Server-side: use bridge directly
+  const importBridge = new Function("specifier", "return import(specifier)") as <
+    T = any,
+  >(
+    specifier: string,
+  ) => Promise<T>;
+  const { readXhsProfileWithBridge } = await importBridge<{
+    readXhsProfileWithBridge: (
+      options: ReadXhsProfileArgs,
+    ) => Promise<XhsReadResult<XhsProfileCollection>>;
+  }>("../../integrations/xhs-reader/bridge/readXhsProfileWithBridge.ts");
+  return readXhsProfileWithBridge(args);
+}
+
+function formatDisplay(result: XhsReadResult<XhsProfileCollection>) {
+  if (!result.ok) {
+    const hints: string[] = [];
+    if (result.code === "login_required") {
+      hints.push(
+        "匿名公开访问遇到登录墙：当前用户主页对未登录访客不可见，read_xhs_profile 不会请求登录或复用账号。",
+      );
+    } else if (result.code === "blocked") {
+      hints.push(
+        "匿名公开访问被安全检查拦截。请稍后重试，或接受匿名模式下无法读取该页面。",
+      );
+    } else if (result.code === "empty_profile_state") {
+      hints.push(
+        "页面加载但未获取到笔记数据。建议：确认该用户有公开笔记；如果页面需要登录，匿名模式会停止而不是切换账号。",
+      );
+    }
+    return [
+      `读取小红书用户主页失败：${result.message}`,
+      `失败代码：${result.code}`,
+      "",
+      "可能的解决步骤：",
+      "- 确认 URL 是有效的小红书用户主页链接",
+      "- 如果页面只对登录用户可见，接受匿名模式无法读取该内容",
+      "- 如果是临时网络或页面加载问题，可以稍后重试或增加 timeoutMs",
+      "- 检查 Playwright chromium 是否已安装",
+      ...hints,
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  const { profile, notes, noteDetails, analysis } = result.data;
+
+  const parts: string[] = [];
+
+  // Profile summary
+  parts.push(`小红书用户: ${profile.nickname || "未命名"}`);
+  if (profile.redId) parts.push(`小红书号: ${profile.redId}`);
+  if (profile.ipLocation) parts.push(`IP 属地: ${profile.ipLocation}`);
+  if (profile.desc) parts.push(`简介: ${profile.desc}`);
+
+  // Interaction counts
+  const ic = profile.interactionCounts;
+  if (ic) {
+    const counts: string[] = [];
+    if (ic.follows != null) counts.push(`关注 ${ic.follows}`);
+    if (ic.fans != null) counts.push(`粉丝 ${ic.fans}`);
+    if (ic.likesAndCollects != null)
+      counts.push(`获赞与收藏 ${ic.likesAndCollects}`);
+    if (counts.length > 0) parts.push(`互动: ${counts.join(" / ")}`);
+  }
+
+  parts.push("");
+
+  // Notes summary
+  parts.push(`笔记数量: ${analysis.totalNotes}`);
+  if (noteDetails.length > 0) {
+    parts.push(`已获取详情: ${noteDetails.length} 篇`);
+  }
+  if (result.data.indexedDiscovery) {
+    parts.push(
+      `外部索引公开笔记: ${result.data.indexedDiscovery.verifiedNoteUrls.length}/${result.data.indexedDiscovery.acceptedNoteUrls.length} 已校验（${result.data.indexedDiscovery.requestedNoteUrls.length} 个候选）`,
+    );
+  }
+
+  // Top notes
+  if (analysis.highestLikedNote) {
+    const n = analysis.highestLikedNote;
+    parts.push(
+      `最高点赞: ${n.title ?? n.noteId}（${n.count} 赞）`,
+    );
+  }
+  if (analysis.highestCommentedNote) {
+    const n = analysis.highestCommentedNote;
+    parts.push(
+      `最高评论: ${n.title ?? n.noteId}（${n.count} 评论）`,
+    );
+  }
+  if (analysis.highestCollectedNote) {
+    const n = analysis.highestCollectedNote;
+    parts.push(
+      `最高收藏: ${n.title ?? n.noteId}（${n.count} 收藏）`,
+    );
+  }
+  if (analysis.highestSharedNote) {
+    const n = analysis.highestSharedNote;
+    parts.push(
+      `最高分享: ${n.title ?? n.noteId}（${n.count} 分享）`,
+    );
+  }
+
+  // Comment buckets
+  if (analysis.commentBuckets.length > 0) {
+    parts.push("");
+    parts.push("评论主题分布:");
+    for (const bucket of analysis.commentBuckets) {
+      parts.push(`  - ${bucket.label}: ${bucket.count} 条`);
+    }
+  }
+
+  // Diagnostic info (when profile succeeded but notes collection had issues)
+  if (result.data.diagnostic) {
+    const diag = result.data.diagnostic;
+    parts.push("");
+    parts.push(`⚠ 采集诊断：${diag.code}`);
+    parts.push(`  ${diag.message}`);
+    if (diag.loginDetected) parts.push("  检测到登录提示");
+  }
+
+  // Collection status display
+  if (result.data.collectionStatus) {
+    const cs = result.data.collectionStatus;
+    parts.push("");
+    const modeLabel = cs.mode === "assisted" ? "辅助采集" : "保守模式";
+    const actionLabels: Record<string, string> = {
+      snapshot: "快照",
+      read_more_notes: "读取更多笔记",
+      read_visible_details: "读取公开详情与首屏评论",
+      discover_indexed_notes: "读取外部索引公开笔记",
+    };
+    parts.push(`采集模式: ${modeLabel}`);
+    parts.push(`采集动作: ${actionLabels[cs.action] ?? cs.action}`);
+    if (cs.mode === "assisted") {
+      parts.push(
+        `步数: ${cs.assistedStepCount}/${cs.limits.maxAssistedSteps}`,
+      );
+    }
+    if (cs.nextSuggestedAction) {
+      parts.push(
+        `建议: ${cs.nextSuggestedAction.label} - ${cs.nextSuggestedAction.reason}`,
+      );
+    }
+  }
+
+  return parts.join("\n");
+}
+
+export async function readXhsProfileFunc(
+  args: ReadXhsProfileArgs,
+  thunkApi: any,
+  context: ReadXhsProfileToolContext = {},
+): Promise<{
+  rawData: XhsReadResult<XhsProfileCollection>;
+  displayData: string;
+}> {
+  const url = String(args?.url ?? "").trim();
+  const parsedUrl = assertXhsProfileUrl(url);
+
+  const readerArgs: ReadXhsProfileArgs = normalizeXhsProfileReadArgs({
+    url: parsedUrl.navigationUrl,
+    maxScrollPages: args.maxScrollPages,
+    includeComments: args.includeComments,
+    maxCommentPagesPerNote: args.maxCommentPagesPerNote,
+    minLikesForDetail: args.minLikesForDetail,
+    minCommentsForCollect: args.minCommentsForCollect,
+    extendedCollectionConsent: args.extendedCollectionConsent,
+    headless: args.headless,
+    collectionMode: args.collectionMode,
+    assistedAction: args.assistedAction,
+    maxAssistedSteps: args.maxAssistedSteps,
+    indexedNoteUrls: args.indexedNoteUrls,
+  });
+
+  const rawDataUnredacted =
+    (await context.reader?.(readerArgs)) ??
+    (await readWithDefaultBridge(readerArgs, thunkApi));
+  const rawData = redactXhsSensitiveValue(rawDataUnredacted) as XhsReadResult<XhsProfileCollection>;
+
+  // Build and attach collectionStatus
+  if (rawData.ok) {
+    rawData.data.collectionStatus = buildCollectionStatus(
+      readerArgs,
+      rawData.data,
+    );
+  }
+
+  return {
+    rawData,
+    displayData: formatDisplay(rawData),
+  };
+}
+
+function buildCollectionStatus(
+  args: ReadXhsProfileArgs,
+  data: XhsProfileCollection,
+): XhsCollectionStatus {
+  const mode = args.collectionMode ?? "conservative";
+  const action = args.assistedAction ?? "snapshot";
+  const consent = args.extendedCollectionConsent === true;
+  const steps = args.maxAssistedSteps ?? 1;
+
+  const status: XhsCollectionStatus = {
+    mode,
+    action,
+    extendedCollectionConsent: consent,
+    assistedStepCount: consent && mode === "assisted" ? steps : 0,
+    limits: {
+      maxAssistedSteps: steps,
+      maxScrollPages: args.maxScrollPages ?? 0,
+      maxCommentPagesPerNote: args.maxCommentPagesPerNote ?? 1,
+      includeComments: args.includeComments ?? false,
+    },
+  };
+
+  // Determine next suggested action
+  status.nextSuggestedAction = computeNextSuggestedAction(args, data);
+
+  return status;
+}
+
+function computeNextSuggestedAction(
+  args: ReadXhsProfileArgs,
+  data: XhsProfileCollection,
+): XhsCollectionStatus["nextSuggestedAction"] {
+  const { diagnostic, notes, analysis } = data;
+  const action = args.assistedAction ?? "snapshot";
+
+  if (
+    (diagnostic?.loginDetected ||
+      diagnostic?.code === "login_required" ||
+      (diagnostic?.code === "empty_profile_state" && notes.length === 0)) &&
+    action !== "discover_indexed_notes"
+  ) {
+    return {
+      action: "discover_indexed_notes",
+      label: "外部索引找公开笔记",
+      reason: "站内匿名搜索不可用；可用 Google 等外部索引查找公开 note URL 后再读取可见页面",
+    };
+  }
+
+  // Login wall or empty state after indexed discovery → stop; anonymous mode must not request login.
+  if (diagnostic?.loginDetected || diagnostic?.code === "login_required") {
+    return {
+      action: "stop_anonymous_unavailable",
+      label: "匿名不可见",
+      reason: "检测到登录提示；匿名公开模式不会登录或复用账号",
+    };
+  }
+
+  // Few notes and was a snapshot → suggest reading more notes
+  if (notes.length < 5 && action === "snapshot") {
+    return {
+      action: "read_more_notes",
+      label: "读取更多笔记",
+      reason: `当前仅读取 ${notes.length} 篇笔记，可尝试翻页获取更多`,
+    };
+  }
+
+  if (notes.length > 0 && action === "snapshot") {
+    return {
+      action: "read_visible_details",
+      label: "读取公开详情与首屏评论",
+      reason: "当前已有公开笔记列表，可匿名打开公开笔记页读取页面可见详情",
+    };
+  }
+
+  // Analysis exists and has data → suggest saving to table
+  if (analysis.totalNotes > 0 && action === "read_more_notes") {
+    return {
+      action: "save_to_table",
+      label: "保存到表格",
+      reason: "已采集到数据，可保存到表格以便分析",
+    };
+  }
+
+  return undefined;
+}