feat: add MCP creator screenshot metrics recognition

lib/collection-service.ts

@@ -21,6 +21,33 @@ type ScheduledTask = {
 
 type CollectionSource = "automatic" | "catchup" | "manual";
 
+function userFacingCollectionError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  const normalized = message.toLowerCase();
+  if (
+    /cookie|登录|登陆|授权|access.?token|未登录|未授权|401|403/.test(
+      normalized,
+    )
+  ) {
+    return "采集 Cookie 已过期或无权限";
+  }
+  if (
+    /链接|link|url|404|not found|不存在|删除|失效|无法识别.*笔记/.test(
+      normalized,
+    )
+  ) {
+    return "笔记链接失效或不可访问";
+  }
+  if (
+    /超时|timeout|fetch failed|network|502|503|暂时不可用|响应空/.test(
+      normalized,
+    )
+  ) {
+    return "采集服务暂时不可用";
+  }
+  return "笔记链接失效或采集 Cookie 过期";
+}
+
 function utcDay(value: string) {
   const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
   if (!match) return null;
@@ -311,8 +338,9 @@ export async function collectDistributionMetrics(
     ]);
     return { skipped: false, likes, comments, collects, shares };
   } catch (error) {
-    const message =
-      error instanceof Error ? error.message : "公开数据采集失败";
+    const detail = error instanceof Error ? error.message : String(error);
+    const message = userFacingCollectionError(error);
+    console.error("[KOC LOOP] collection failed", { detail, distributionId });
     await db.batch([
       db
         .prepare(

lib/creator-screenshot-access.ts

@@ -0,0 +1,60 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { getRuntimeEnv } from "./runtime-env";
+
+function accessSecret() {
+  const env = getRuntimeEnv();
+  return (
+    env.KOC_MCP_API_KEY ||
+    env.KOC_LOOP_MCP_API_KEY ||
+    env.ADMIN_INTERNAL_TOKEN ||
+    env.AI_TOOL_CENTER_MCP_KEY ||
+    ""
+  ).trim();
+}
+
+function signature(distributionId: string, screenshotKey: string, expiresAt: number) {
+  return createHmac("sha256", accessSecret())
+    .update(`${distributionId}:${screenshotKey}:${expiresAt}`)
+    .digest("hex");
+}
+
+export function creatorScreenshotAccessToken(
+  distributionId: string,
+  screenshotKey: string,
+  expiresAt = Math.floor(Date.now() / 1000) + 300,
+) {
+  const secret = accessSecret();
+  if (!secret) throw new Error("图片识别访问密钥未配置");
+  return `${expiresAt}.${signature(distributionId, screenshotKey, expiresAt)}`;
+}
+
+export function verifyCreatorScreenshotAccessToken(
+  distributionId: string,
+  screenshotKey: string,
+  token: string,
+) {
+  const [expiresText, received] = token.split(".");
+  const expiresAt = Number(expiresText);
+  if (!Number.isInteger(expiresAt) || expiresAt < Math.floor(Date.now() / 1000)) {
+    return false;
+  }
+  const expected = signature(distributionId, screenshotKey, expiresAt);
+  if (!received || received.length !== expected.length) return false;
+  return timingSafeEqual(Buffer.from(received), Buffer.from(expected));
+}
+
+export function creatorScreenshotMcpUrl(
+  request: Request,
+  distributionId: string,
+  screenshotKey: string,
+) {
+  const env = getRuntimeEnv();
+  const origin = (env.APP_ORIGIN || new URL(request.url).origin).replace(/\/$/, "");
+  const url = new URL(`${origin}/api/creator-screenshot`);
+  url.searchParams.set("distribution", distributionId);
+  url.searchParams.set(
+    "mcp_token",
+    creatorScreenshotAccessToken(distributionId, screenshotKey),
+  );
+  return url.toString();
+}

lib/mcp-collection-client.ts

@@ -254,6 +254,7 @@ async function invokeMcpTool(
   timeoutMs: number,
   name: string,
   args: Record<string, unknown>,
+  allowText = false,
 ): Promise<ToolResult> {
   const result = await postMcp(
     fetchImpl,
@@ -277,6 +278,12 @@ async function invokeMcpTool(
   try {
     payload = JSON.parse(text);
   } catch {
+    if (allowText) {
+      return {
+        isError: result.envelope?.result?.isError === true,
+        payload: { text },
+      };
+    }
     if (result.envelope?.result?.isError === true) {
       return {
         isError: true,
@@ -305,6 +312,7 @@ async function callMcpTool(
   timeoutMs: number,
   name: string,
   args: Record<string, unknown>,
+  allowText = false,
 ): Promise<ToolResult> {
   const nested = await invokeMcpTool(
     fetchImpl,
@@ -313,6 +321,7 @@ async function callMcpTool(
     timeoutMs,
     name,
     { request: args },
+    allowText,
   );
   if (!isToolArgumentShapeError(nested)) return nested;
   return invokeMcpTool(
@@ -322,10 +331,86 @@ async function callMcpTool(
     timeoutMs,
     name,
     args,
+    allowText,
   );
 }
 
-function metricsFromToolResult(result: ToolResult): XhsPublicMetrics {
+function imageToolText(value: unknown) {
+  if (typeof value === "string") return value;
+  const root = asRecord(value);
+  if (!root) return "";
+  return [root.text, root.description, root.content, root.message, root.error]
+    .flatMap((item) => (Array.isArray(item) ? item : [item]))
+    .map((item) => {
+      if (typeof item === "string") return item;
+      const record = asRecord(item);
+      return String(record?.text ?? record?.description ?? "");
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function metricFromImageText(text: string, labels: string[], label: string) {
+  const pattern = labels.join("|");
+  const match = text.match(
+    new RegExp(`(?:${pattern})\\s*[：:]?\\s*([\\d,.]+(?:万|w|千|k)?)`, "i"),
+  );
+  if (!match) return null;
+  try {
+    return metricValue(match[1], label);
+  } catch {
+    return null;
+  }
+}
+
+function creatorMetricsFromImageResult(result: ToolResult) {
+  if (result.isError) {
+    const detail = imageToolText(result.payload);
+    throw new Error(
+      `图片识别 MCP 调用失败${detail ? `：${safeMessage(detail, "")}` : ""}`,
+    );
+  }
+  const text = imageToolText(result.payload);
+  const exposure = metricFromImageText(
+    text,
+    ["曝光量", "曝光", "impressions", "exposure"],
+    "曝光量",
+  );
+  const views = metricFromImageText(
+    text,
+    ["阅读量", "阅读", "views", "view_count", "view count"],
+    "阅读量",
+  );
+  if (exposure === null || views === null) {
+    throw new Error("图片识别未找到曝光量和阅读量");
+  }
+  return { exposure, views };
+}
+
+export async function extractCreatorMetricsFromMcp(
+  imageUrl: string,
+  config: CollectionMcpConfig,
+  fetchImpl: typeof fetch = fetch,
+) {
+  const endpoint = buildMcpUrl(config);
+  const timeoutMs = Math.max(5_000, config.timeoutMs ?? 30_000);
+  const sessionId = await createMcpSession(fetchImpl, endpoint, timeoutMs);
+  const result = await callMcpTool(
+    fetchImpl,
+    endpoint,
+    sessionId,
+    timeoutMs,
+    "analyze_image",
+    { image_url: imageUrl },
+    true,
+  );
+  return creatorMetricsFromImageResult(result);
+}
+
+function metricsFromToolResult(
+  result: ToolResult,
+  toolName = "fetch_content_detail",
+): XhsPublicMetrics {
   const root = asRecord(result.payload);
   const response = asRecord(root?.response) ?? root;
   const data = asRecord(response?.data) ?? asRecord(root?.data);
@@ -337,14 +422,18 @@ function metricsFromToolResult(result: ToolResult): XhsPublicMetrics {
     success === false ||
     (Number.isFinite(code) && code >= 400)
   ) {
+    const providerCode = Number(response?.code);
+    const codeLabel = Number.isFinite(providerCode)
+      ? `（code ${providerCode}）`
+      : "";
     throw new Error(
-      safeMessage(
+      `MCP工具 ${toolName} 返回失败${codeLabel}：${safeMessage(
         response?.msg ?? response?.message ?? root?.message,
         "公开数据采集失败",
-      ),
+      )}`,
     );
   }
-  if (!data) throw new Error("采集结果缺少互动数据");
+  if (!data) throw new Error(`MCP工具 ${toolName} 未返回互动数据`);
 
   const count = (value: unknown, label: string) =>
     value === null || value === undefined || value === ""
@@ -1156,7 +1245,7 @@ async function collectInSession(
       auto_cookie: true,
     },
   );
-  return metricsFromToolResult(primary);
+  return metricsFromToolResult(primary, "fetch_content_detail");
 }
 
 export function resolveCollectionMcpConfig(