koishi-plugin-kkk 1.0.0

package/src/karin/platform/kuaishou/comments.ts

@@ -0,0 +1,114 @@
+import type { KuaishouCommentsResponse } from '@ikenxuan/amagi'
+import {
+  createEmojiNode,
+  createLineBreakNode,
+  createMentionNode,
+  createRichTextDocument,
+  createTextNode,
+  type RichTextDocument,
+  type RichTextEmojiDefinition,
+  type RichTextNode
+} from '@kkk/richtext'
+import type { KuaishouCommentData } from '@template/template/kuaishou/comment/components/types'
+
+import { Config } from '@/module/utils/Config'
+
+/**
+ * 处理快手评论数据。
+ *
+ * 这里不再拼 HTML，而是输出共享富文本 JSON，交给 template 侧渲染 React 节点。
+ *
+ * amagi 把评论换到 H5 `photo/comment/list` 之后形状变了三处，且按「不归一化」原样透出：
+ * 条目从 `data.visionCommentList.rootComments` 提到顶层 `rootComments`、字段名从
+ * camelCase 变成 snake_case、子评论从内嵌的 `subComments` 挪到了 `subCommentsMap`。
+ * 本函数只用到根评论和 `subCommentCount` 这个计数，所以 `subCommentsMap` 暂不读。
+ */
+export const kuaishouComments = async (
+  data: KuaishouCommentsResponse,
+  emojiData: RichTextEmojiDefinition[]
+): Promise<KuaishouCommentData['CommentsData']> => {
+  const rootComments = data?.rootComments
+  if (!Array.isArray(rootComments) || rootComments.length === 0) {
+    return []
+  }
+
+  const comments = rootComments.map((comment) => ({
+    // 生成类型里 `comment_id` 是数字（H5 这条的 id 就是数字），模板侧要字符串
+    cid: String(comment.comment_id ?? ''),
+    aweme_id: String(comment.comment_id ?? ''),
+    nickname: comment.author_name ?? '',
+    userimageurl: comment.headurl ?? '',
+    text: buildKuaishouRichText(comment.content ?? '', emojiData),
+    // H5 这条**没有** `realLikedCount`（那是 PC GraphQL 独有的真实点赞数），只剩展示用的
+    // `likedCount`，还可能是「1.2万」这种字符串 —— 解不出数字就沿用原有的兜底值 0
+    digg_count: Number(comment.likedCount) || 0,
+    create_time: comment.timestamp ?? 0,
+    reply_comment_total: comment.subCommentCount ?? 0
+  }))
+
+  return comments.sort((a, b) => b.digg_count - a.digg_count).slice(0, Math.min(comments.length, Config.kuaishou.numcomment))
+}
+
+/**
+ * 把快手评论正文解析成共享富文本 JSON。
+ *
+ * 当前主要兼容：
+ * - `[表情]` 形式的平台表情；
+ * - `@昵称(uid)` 形式的提及；
+ * - 评论里的换行与空格。
+ */
+const buildKuaishouRichText = (text: string, emojiData: RichTextEmojiDefinition[]): RichTextDocument => {
+  const normalizedText = typeof text === 'string' ? text : String(text || '')
+  const emojiTokens = [...emojiData].sort((a, b) => b.name.length - a.name.length)
+  const nodes: RichTextNode[] = []
+  let buffer = ''
+  let index = 0
+
+  const pushBuffer = () => {
+    if (buffer.length > 0) {
+      nodes.push(createTextNode(buffer))
+      buffer = ''
+    }
+  }
+
+  while (index < normalizedText.length) {
+    if (normalizedText[index] === '\r') {
+      pushBuffer()
+      index += normalizedText[index + 1] === '\n' ? 2 : 1
+      nodes.push(createLineBreakNode())
+      continue
+    }
+
+    if (normalizedText[index] === '\n') {
+      pushBuffer()
+      nodes.push(createLineBreakNode())
+      index += 1
+      continue
+    }
+
+    const mentionMatch = normalizedText.slice(index).match(/^@([^()]+?)\(([^)]+)\)/)
+    if (mentionMatch) {
+      pushBuffer()
+      const mentionText = `@${mentionMatch[1].trim()}`
+      const mentionId = mentionMatch[2].trim() || undefined
+      nodes.push(createMentionNode(mentionText, mentionId))
+      index += mentionMatch[0].length
+      continue
+    }
+
+    const matchedEmoji = emojiTokens.find((item) => normalizedText.startsWith(item.name, index))
+    if (matchedEmoji) {
+      pushBuffer()
+      nodes.push(createEmojiNode(matchedEmoji.name, matchedEmoji.url))
+      index += matchedEmoji.name.length
+      continue
+    }
+
+    buffer += normalizedText[index]
+    index += 1
+  }
+
+  pushBuffer()
+
+  return createRichTextDocument(nodes, { platform: 'kuaishou' })
+}

package/src/karin/platform/kuaishou/getID.ts

@@ -0,0 +1,48 @@
+import { logger } from 'node-karin'
+
+import { Networks } from '@/module'
+import type { KuaishouDataTypes } from '@/types'
+
+export interface ExtendedKuaishouOptionsType {
+  type: KuaishouDataTypes[keyof KuaishouDataTypes]
+  [x: string]: any
+}
+
+/**
+ *
+ * @param url 分享链接
+ * @param log 输出日志，默认true
+ * @returns
+ */
+export const getKuaishouID = async (url: string, log = true) => {
+  const longLink = await new Networks({ url }).getLongLink()
+  let result = {} as ExtendedKuaishouOptionsType
+  switch (true) {
+    case /photoId=(.*)/.test(longLink): {
+      const workid = /photoId=([^&]+)/.exec(longLink)
+      result = {
+        type: 'one_work',
+        photoId: workid ? workid[1] : undefined
+      }
+      break
+    }
+    // 匹配 kuaishou.com/short-video/{id} 格式的链接
+    case /kuaishou\.com\/short-video\/([^?]+)/.test(longLink): {
+      const workid = /short-video\/([^?]+)/.exec(longLink)
+      result = {
+        type: 'one_work',
+        photoId: workid ? workid[1] : undefined
+      }
+      break
+    }
+    default: {
+      logger.warn('无法获取作品ID')
+      break
+    }
+  }
+
+  if (log) {
+    console.log(result)
+  }
+  return result
+}

package/src/karin/platform/kuaishou/getdata.ts

@@ -0,0 +1,78 @@
+import type {
+  KuaishouCommentsResponse,
+  KuaishouDataOptionsMap,
+  KuaishouEmojiListResponse,
+  KuaishouVideoWorkResponse
+} from '@ikenxuan/amagi'
+
+import { kuaishouFetcher } from '@/module/utils/amagiClient'
+import { KuaishouDataTypes, type ExtendedKuaishouOptionsType } from '@/types'
+
+/**
+ * `one_work` 分支打包返回的三个响应体。
+ *
+ * 抽成命名类型是给 `KuaishouHandler` 用的：它的入参一直是 `any`，快手换成 H5 REST
+ * 之后响应形状整个变了（少了 `data.visionVideoDetail` 两层），靠 `any` 读错字段
+ * tsc 一声不响 —— 有了这个类型，处理函数里那几处取值才有编译期兜底。
+ * 存的是响应体本身（fetcher 失败即抛，信封没人读）。
+ */
+export type KuaishouOneWorkPayload = {
+  /** 作品详情（H5 `photo/info`，字段都在顶层） */
+  VideoData: KuaishouVideoWorkResponse
+  /** 作品评论（H5 `photo/comment/list`，字段名是 snake_case） */
+  CommentsData: KuaishouCommentsResponse
+  /** 表情映射表（仍走 graphql，形状没变） */
+  EmojiData: KuaishouEmojiListResponse
+}
+
+/** `fetchKuaishouData` 的返回：按 `type` 分支的响应体（`undefined` 表示该类型不需要数据） */
+export type KuaishouDataResult = KuaishouOneWorkPayload | KuaishouCommentsResponse | KuaishouEmojiListResponse | undefined
+
+/**
+ * 各分支要吃的参数。
+ *
+ * 除了 amagi 各端点的入参形状，还并上 `ExtendedKuaishouOptionsType`（链接解析结果）：
+ * 那个类型带 `[x: string]: any` 索引签名，结构上既不满足、也不被满足于具体入参类型，
+ * 并进联合里，分支内按具体形状断言就不必再走 `unknown` 中转。
+ */
+type KuaishouFetchOptions = KuaishouDataOptionsMap[keyof KuaishouDataOptionsMap]['opt'] | ExtendedKuaishouOptionsType
+
+/**
+ * 按数据类型取快手数据。
+ *
+ * 返回类型必须显式写出来：不写的话 TS 推出的是生成树的底层名（`Comments_V0` 这类），
+ * 而那些名字不出现在包外 —— 声明产物于是报 TS2883「inferred type cannot be named」。
+ * @param type - 数据类型
+ * @param opt - 该类型对应的参数（调用方是链接解析结果，字段随链接类型变化）
+ * @returns 按 type 分支的响应体
+ */
+export const fetchKuaishouData = async <T extends keyof KuaishouDataTypes>(
+  type: T,
+  opt?: KuaishouFetchOptions
+): Promise<KuaishouDataResult> => {
+  switch (type) {
+    case 'one_work': {
+      const VideoData = await kuaishouFetcher.fetchVideoWork({
+        photoId: (opt as KuaishouDataOptionsMap['videoWork']['opt']).photoId
+      })
+      const CommentsData = await kuaishouFetcher.fetchWorkComments({
+        photoId: (opt as KuaishouDataOptionsMap['comments']['opt']).photoId
+      })
+      const EmojiData = await kuaishouFetcher.fetchEmojiList()
+      return { VideoData: VideoData.data, CommentsData: CommentsData.data, EmojiData: EmojiData.data }
+    }
+    case 'work_comments': {
+      const CommentsData = await kuaishouFetcher.fetchWorkComments({
+        photoId: (opt as KuaishouDataOptionsMap['comments']['opt']).photoId
+      })
+      return CommentsData.data
+    }
+    case 'emoji_list': {
+      const EmojiData = await kuaishouFetcher.fetchEmojiList()
+      return EmojiData.data
+    }
+    default: {
+      break
+    }
+  }
+}

package/src/karin/platform/kuaishou/index.ts

@@ -0,0 +1,4 @@
+export * from './comments'
+export * from './getdata'
+export * from './getID'
+export * from './kuaishou'

package/src/karin/platform/kuaishou/kuaishou.ts

@@ -0,0 +1,130 @@
+import type { KuaishouVideoWorkResponse } from '@ikenxuan/amagi'
+import { logger, type Message } from 'node-karin'
+
+import { Base, downloadVideo, extractTotalBytesFromHeaders, Networks, Render } from '@/module'
+// sendParseTip 单独导入：它在一个无依赖的叶子模块里，避免和平台模块形成循环 import
+import { sendParseTip } from '@/module/utils/parseTip'
+import type { ParseWorkType } from '@/module/db'
+import { Config } from '@/module/utils/Config'
+import { kuaishouComments, type KuaishouDataResult, type KuaishouOneWorkPayload } from '@/platform/kuaishou'
+import type { ExtendedKuaishouOptionsType, KuaishouDataTypes } from '@/types'
+
+/**
+ * 从作品详情里挑一条视频直链。
+ *
+ * PC GraphQL 那条有现成的 `photo.photoUrl`，H5 `photo/info` **没有这个字段**，
+ * 只能按 amagi 类型里写明的分发规则自己挑：优先 `manifest.adaptationSet` 的档位
+ * （`defaultSelect` 是平台自己标的默认清晰度），没有 `manifest` 再回落到单档的
+ * `mainMvUrls`。
+ *
+ * 图集 / 单图作品这两处都是空的（原图在 `atlas` / `single`，本插件目前只解析视频），
+ * 所以取不到时返回空串，交给调用方走原有的「不支持解析」分支，而不是拿空串去发请求。
+ * @param work - `fetchVideoWork` 的响应体
+ * @returns 视频直链；取不到时为空串
+ */
+const pickVideoUrl = (work: KuaishouVideoWorkResponse): string => {
+  const representations = work.photo?.manifest?.adaptationSet?.flatMap((set) => set.representation ?? []) ?? []
+  const preferred = representations.find((item) => item.defaultSelect) ?? representations[0]
+  return preferred?.url ?? work.photo?.mainMvUrls?.[0]?.url ?? ''
+}
+
+export class Kuaishou extends Base {
+  e: Message
+  type: KuaishouDataTypes[keyof KuaishouDataTypes]
+  /**
+   * 本次解析的内容形态，供统计埋点读取。
+   * 本插件只解析视频，图集/单图会在下面提前返回，那时保持 undefined。
+   */
+  workType?: ParseWorkType
+  constructor(e: Message, iddata: ExtendedKuaishouOptionsType) {
+    super(e)
+    this.e = e
+    this.type = iddata?.type
+  }
+
+  async KuaishouHandler(data: KuaishouDataResult) {
+    // 入参是 fetchKuaishouData 的联合返回，本插件只解析视频，先收窄到 one_work 那一支：
+    // H5 换形状后所有取值都得靠 tsc 检查，不能再裸读 any
+    const payload = data as KuaishouOneWorkPayload
+    /**
+     * 快手 H5 的响应多包了一层 `data`：`{ data: { result, photo, … } }`。
+     * 直接读 `work.result` / `work.photo` 会全是 undefined，于是每个链接都被判成「不支持解析的视频」
+     * （诊断日志：顶层键=["data"]、photo键=[] ✓）。这里统一拆一层，两种形状都兼容。
+     */
+    const rawWork: any = payload.VideoData
+    const work: any =
+      rawWork?.data?.visionVideoDetail ??
+      rawWork?.visionVideoDetail ??
+      (rawWork?.data && typeof rawWork.data === 'object' && !rawWork.photo ? rawWork.data : rawWork)
+
+    // H5 这条响应没有 `data.visionVideoDetail.status`（那是 PC GraphQL 的字段），
+    // 顶层 `result` 才是接口状态位（1 = 成功）；再加一道「拿不到视频直链」，
+    // 图集 / 单图落到这里也能给出原来那句提示而不是报错
+    const video_url = pickVideoUrl(work)
+    /**
+     * 成功与否**以能否取到视频直链为准**：
+     * H5 那版响应里状态字段叫 `status`，没有 `result`（PC GraphQL 才有）；
+     * 死抠 `work.result !== 1` 会把所有能解析的作品都判成「不支持解析的视频」。
+     * 只有状态位明确是失败（非 1）时才提前返回。
+     */
+    const statusOk = work?.result === undefined && work?.status === undefined
+      ? true
+      : (work?.result === 1 || work?.status === 1 || work?.status === true || work?.status === 'ok')
+    if (!video_url && !statusOk) {
+      await this.e.reply('接口没有返回视频直链，稍后再试试')
+      return true
+    }
+    /**
+     * **风控/验证码要单独说清楚**：快手有时直接返回带 `captcha` 的响应而不是作品数据
+     * （本次诊断日志里就能看到 顶层键=["visionVideoDetail","captcha"]）。
+     * 这种情况拿去当「不支持解析的视频」会让人以为链接有问题，其实等一会儿/换网络就好。
+     */
+    if (work?.captcha !== undefined || rawWork?.captcha !== undefined) {
+      logger.warn('[快手] 接口返回了验证码（风控），本次无法解析')
+      await this.e.reply('快手这次返回了验证码（风控拦截），过一会儿或换个网络再试试 ~')
+      return true
+    }
+    if (!video_url) {
+      // 诊断：把真实响应形状打出来，便于判断是「接口没给直链」还是「状态位字段变了」
+      const reps = work?.photo?.manifest?.adaptationSet?.flatMap((set: any) => set.representation ?? []) ?? []
+      logger.mark(
+        '[快手] 判为不支持解析 → result=' + String(work?.result) +
+        ' 顶层键=' + JSON.stringify(Object.keys(work ?? {}).slice(0, 12)) +
+        ' photo键=' + JSON.stringify(Object.keys(work?.photo ?? {}).slice(0, 14)) +
+        ' 码流数=' + reps.length +
+        ' mainMvUrls=' + (work?.photo?.mainMvUrls?.length ?? 0)
+      )
+      await this.e.reply('不支持解析的视频')
+      return true
+    }
+    this.workType = 'video'
+    await sendParseTip(this.e, '快手')
+    // 表情接口没换，还是 graphql 那条，`data.visionBaseEmoticons` 两层照旧
+    const transformedData = Object.entries(payload.EmojiData.data.visionBaseEmoticons.iconUrls).map(([name, path]) => {
+      return { name, url: `https:${path}` }
+    })
+    const CommentsData = await kuaishouComments(payload.CommentsData, transformedData)
+    const fileHeaders = await new Networks({ url: video_url, headers: this.headers }).getHeaders()
+    const fileSizeContent = extractTotalBytesFromHeaders(fileHeaders)
+    const fileSizeInMB = (fileSizeContent / (1024 * 1024)).toFixed(2)
+    const img = await Render(this.e, 'kuaishou/comment', {
+      Type: '视频',
+      // 这两个计数在 GraphQL 那条是字符串，H5 直接给数字，正好对上模板声明的 number
+      viewCount: work.photo.viewCount,
+      CommentsData,
+      CommentLength: CommentsData?.length ?? 0,
+      share_url: video_url,
+      VideoSize: fileSizeInMB,
+      likeCount: work.photo.likeCount
+    })
+    await this.e.reply(img)
+    await downloadVideo(this.e, {
+      video_url,
+      title: {
+        timestampTitle: `tmp_${Date.now()}.mp4`,
+        originTitle: `${work.photo.caption}.mp4`
+      }
+    })
+    return true
+  }
+}

package/src/karin/platform/xiaohongshu/comments.ts

@@ -0,0 +1,227 @@
+import type { NoteComments } from '@ikenxuan/amagi'
+import {
+  createEmojiNode,
+  createLineBreakNode,
+  createMentionNode,
+  createRichTextDocument,
+  createTextNode,
+  type RichTextDocument,
+  type RichTextEmojiDefinition,
+  type RichTextNode
+} from '@kkk/richtext'
+import type { XiaohongshuCommentData } from '@template/template/xiaohongshu/comment/components/types'
+
+import { Config } from '@/module/utils/Config'
+
+/** 评论项类型：从模板路由主数据接口逐步索引派生，types.ts 不再单独导出子类型 */
+type XiaohongshuCommentItem = XiaohongshuCommentData['CommentsData'][number]
+/** 子评论类型：同上，由评论项的 sub_comments 字段索引得到 */
+type XiaohongshuSubComment = XiaohongshuCommentItem['sub_comments'][number]
+
+/**
+ * 评论里被 @ 的人。
+ *
+ * 快照类型写的是 `string[]`，但线上两种形态都见过：web 接口给 `"@昵称"` 字符串，
+ * app 接口给对象（昵称在 `nickname` 或 `user_info.nickname`）—— 按实际读到的两格并集声明，
+ * `string[]` 天然是它的子集，调用处不用断言。
+ */
+type NoteAtUser = string | { nickname?: string; user_id?: string; user_info?: { nickname?: string; user_id?: string } }
+
+/** 评论标签：字符串，或带 `name` / `tag` 的对象（同样是快照类型没覆盖到的形态） */
+type NoteTag = string | { name?: string; tag?: string }
+
+/**
+ * 处理小红书评论数据。
+ *
+ * 这里直接输出结构化评论 JSON，正文部分使用 richtext 文档，避免后端拼接 HTML。
+ */
+export const xiaohongshuComments = (data: NoteComments, emojiData: RichTextEmojiDefinition[]): XiaohongshuCommentItem[] => {
+  const rawComments = data?.data?.comments
+  if (!Array.isArray(rawComments) || rawComments.length === 0) {
+    return []
+  }
+
+  const comments = rawComments.map((comment) => {
+    const showTags = normalizeTagNames(comment.show_tags)
+
+    return {
+      id: comment.id,
+      note_id: comment.note_id,
+      content: buildXiaohongshuRichText(comment.content, emojiData, comment.at_users),
+      user_info: comment.user_info,
+      create_time: comment.create_time,
+      ip_location: comment.ip_location || '未知',
+      like_count: comment.like_count,
+      liked: comment.liked,
+      pictures: Array.isArray(comment.pictures) ? comment.pictures : [],
+      sub_comment_count: comment.sub_comment_count,
+      sub_comments: buildXiaohongshuSubComments(comment.sub_comments, emojiData),
+      show_tags: showTags,
+      at_users: normalizeAtUsers(comment.at_users).map((item) => item.text),
+      status: comment.status
+    }
+  })
+
+  return comments
+    .sort((a, b) => Number(b.show_tags.includes('user_top')) - Number(a.show_tags.includes('user_top')))
+    .slice(0, Config.xiaohongshu.numcomment)
+}
+
+const buildXiaohongshuSubComments = (
+  subComments: NoteComments['data']['comments'][number]['sub_comments'],
+  emojiData: RichTextEmojiDefinition[]
+): XiaohongshuSubComment[] => {
+  if (!Array.isArray(subComments)) {
+    return []
+  }
+
+  return subComments.map((subComment) => ({
+    id: subComment.id,
+    note_id: subComment.note_id,
+    content: buildXiaohongshuRichText(subComment.content, emojiData, subComment.at_users),
+    user_info: subComment.user_info,
+    create_time: subComment.create_time,
+    ip_location: subComment.ip_location || '未知',
+    like_count: subComment.like_count,
+    liked: subComment.liked,
+    pictures: Array.isArray(subComment.pictures) ? subComment.pictures : [],
+    show_tags: normalizeTagNames(subComment.show_tags),
+    at_users: normalizeAtUsers(subComment.at_users).map((item) => item.text),
+    status: subComment.status,
+    target_comment: subComment.target_comment
+  }))
+}
+
+/**
+ * 把小红书评论正文解析成共享富文本 JSON。
+ *
+ * 当前主要兼容：
+ * - `[表情]` 形式的平台表情；
+ * - `@用户` 提及；
+ * - 评论里的换行与连续空格。
+ */
+export const buildXiaohongshuRichText = (
+  text: string,
+  emojiData: RichTextEmojiDefinition[],
+  atUsers: NoteAtUser[] = [],
+  options: {
+    stripTopicMarker?: boolean
+  } = {}
+): RichTextDocument => {
+  const normalizedText = normalizeXiaohongshuText(text, options)
+  const emojiTokens = [...emojiData].sort((a, b) => b.name.length - a.name.length)
+  const mentionTokens = normalizeAtUsers(atUsers).sort((a, b) => b.text.length - a.text.length)
+  const nodes: RichTextNode[] = []
+  let buffer = ''
+  let index = 0
+
+  const pushBuffer = () => {
+    if (buffer.length > 0) {
+      nodes.push(createTextNode(buffer))
+      buffer = ''
+    }
+  }
+
+  while (index < normalizedText.length) {
+    if (normalizedText[index] === '\r') {
+      pushBuffer()
+      index += normalizedText[index + 1] === '\n' ? 2 : 1
+      nodes.push(createLineBreakNode())
+      continue
+    }
+
+    if (normalizedText[index] === '\n') {
+      pushBuffer()
+      nodes.push(createLineBreakNode())
+      index += 1
+      continue
+    }
+
+    const matchedMention = mentionTokens.find((item) => normalizedText.startsWith(item.text, index))
+    if (matchedMention) {
+      pushBuffer()
+      nodes.push(createMentionNode(matchedMention.text, matchedMention.userId))
+      index += matchedMention.text.length
+      continue
+    }
+
+    const matchedEmoji = emojiTokens.find((item) => normalizedText.startsWith(item.name, index))
+    if (matchedEmoji) {
+      pushBuffer()
+      nodes.push(createEmojiNode(matchedEmoji.name, matchedEmoji.url))
+      index += matchedEmoji.name.length
+      continue
+    }
+
+    buffer += normalizedText[index]
+    index += 1
+  }
+
+  pushBuffer()
+
+  return createRichTextDocument(nodes, { platform: 'xiaohongshu' })
+}
+
+const normalizeXiaohongshuText = (
+  text: string,
+  options: {
+    stripTopicMarker?: boolean
+  }
+): string => {
+  const normalized = typeof text === 'string' ? text : String(text || '')
+  if (options.stripTopicMarker) {
+    return normalized.replace(/\[话题\]/g, '')
+  }
+
+  return normalized
+}
+
+const normalizeTagNames = (tags: NoteTag[] | undefined): string[] => {
+  if (!Array.isArray(tags)) {
+    return []
+  }
+
+  return tags
+    .map((tag) => {
+      if (typeof tag === 'string') {
+        return tag
+      }
+
+      if (tag && typeof tag === 'object') {
+        const candidate = tag.name ?? tag.tag
+        return typeof candidate === 'string' ? candidate : ''
+      }
+
+      return ''
+    })
+    .filter(Boolean)
+}
+
+const normalizeAtUsers = (atUsers: NoteAtUser[] | undefined): Array<{ text: string; userId?: string }> => {
+  if (!Array.isArray(atUsers)) {
+    return []
+  }
+
+  return atUsers
+    .map((item) => {
+      if (typeof item === 'string' && item.trim()) {
+        const nickname = item.trim().replace(/^@/, '')
+        return { text: `@${nickname}` }
+      }
+
+      if (item && typeof item === 'object') {
+        const nickname = item.nickname ?? item.user_info?.nickname
+        const userId = item.user_id ?? item.user_info?.user_id
+
+        if (typeof nickname === 'string' && nickname.trim()) {
+          return {
+            text: `@${nickname.trim().replace(/^@/, '')}`,
+            userId
+          }
+        }
+      }
+
+      return null
+    })
+    .filter((item): item is { text: string; userId?: string } => Boolean(item))
+}