链接卡片私信 — 本地联调指南

普通私信 Web IM 链接卡片（message_type=70），任意账号均可收发；与企业号 OpenAPI 模板卡无关。

一、环境准备

  1. 启动后端与前端，确保能登录管理后台。
  2. 设置公网基础 URL（卡片落地页与封面必须外网可访问）： 
    KEFU_PUBLIC_BASE_URL=https://你的域名
    本地调试可用内网穿透（ngrok / frp 等），不要用 localhost 作为卡片跳转地址。
  3. 抖音账号完成 IM 凭证采集（Cookie + web_protect + keys），状态为「可 IM 直连」。

二、创建示例规则（约 3 分钟）

  1. 进入 自动回复规则 → 新建规则。
  2. 匹配方式：包含；关键字：深度研究（或任意测试词）。
  3. 回复类型选 卡片 → 点击 填入示例。
  4. 上传封面图（JPG/PNG，系统会转为 256×256）。
  5. 将「跳转链接」改为你的真实业务 URL。
  6. 保存规则（会自动调用 /api/link-cards 生成落地页）。
  7. 确认表单中出现 落地页链接（形如 https://域名/p/xxxx）。
保存成功后，规则内 reply_content 类似： 
{"type":"card","title":"深度研究入口","desc":"…","url":"https://域名/p/xxx","target_url":"https://业务页","cover_url":"…","image_path":"/api/media/link-cards/…"}

三、联调发送

  1. 在 账号管理 对该抖音号点击 启动托管。
  2. 用另一个抖音号给该账号发私信：深度研究（或你设的关键字）。
  3. 预期：对方收到一条带封面、标题、描述的链接卡片（不是纯文本+链接）。
  4. 点击卡片 → 打开落地页 → 自动跳转到 target_url。

四、日志排查

位置看什么
消息日志reply 列应含 [链接卡片] 标题；status 为 sent
系统诊断日志搜索「卡片」「8004」「封面上传」
后端控制台Sending to target: 与 Link card send

五、常见错误

现象处理
卡片封面上传失败重新登录采集 IM 凭证；确认 session 有效
缺少卡片跳转链接配置 KEFU_PUBLIC_BASE_URL 后重新保存规则
status_code 8004 / raw_check_code 1封面 CDN 未就绪；等待 2～5 秒后重试（系统会自动重试一次）
收到的是文本不是卡片检查 reply_content 中 "type":"card" 是否存在
落地页 404确认后端 /p/{slug} 路由可访问且 slug 已入库
注意：两个均为本系统托管的账号互发消息时，会自动跳过回复以防风控循环。联调请使用外部测试号。

六、手动验证 API（可选）

登录后台后，在浏览器开发者工具 Network 中确认：