koishi-plugin-kkk 1.0.0

package/src/karin/module/utils/bot.ts

@@ -0,0 +1,115 @@
+import type { AdapterType, Message } from 'node-karin'
+import karin, { config, logger } from 'node-karin'
+
+import { Config } from '@/module/utils/Config'
+
+import { statBotId } from './Base'
+
+type FriendItem = { userId?: string }
+
+/**
+ * 获取候选机器人
+ * @returns
+ */
+const getCandidateBots = (): AdapterType[] => {
+  return karin
+    .getAllBotList()
+    .map((item) => item.bot as AdapterType)
+    .filter((bot) => bot.account.name !== 'console')
+}
+
+/**
+ * 获取非console主机器人ID列表
+ * @param masters - 主机器人ID列表
+ * @returns
+ */
+const getNonConsoleMasters = (masters: string[] = config.master()): string[] => {
+  return masters.filter((id) => id !== 'console')
+}
+
+/**
+ * 获取可访问的主机器人
+ * @param masters - 主机器人ID列表
+ * @returns
+ */
+export const getReachableMasterBots = async (masters: string[] = config.master()): Promise<Array<{ master: string; bot: AdapterType }>> => {
+  const owners = getNonConsoleMasters(masters)
+  if (owners.length === 0) return []
+
+  const bots = getCandidateBots()
+  if (bots.length === 0) return []
+
+  const friendsMap = new Map<string, FriendItem[]>()
+  await Promise.all(
+    bots.map(async (bot) => {
+      try {
+        const list = await bot.getFriendList()
+        friendsMap.set(bot.account.selfId, Array.isArray(list) ? (list as FriendItem[]) : [])
+      } catch {
+        friendsMap.set(bot.account.selfId, [])
+      }
+    })
+  )
+
+  const result: Array<{ master: string; bot: AdapterType }> = []
+  for (const master of owners) {
+    const matchedBot = bots.find((bot) => {
+      return (friendsMap.get(bot.account.selfId) || []).some((friend) => friend.userId === master)
+    })
+
+    if (matchedBot) {
+      result.push({ master, bot: matchedBot })
+    }
+  }
+
+  return result
+}
+
+/**
+ * 获取一个最少能用的机器人实例，优先级：1. selfId 参数指定的机器人 2. 可访问主人机器人中的第一个 3. pushlist 中活跃的机器人 4. 任意一个在线机器人
+ * @param selfId - 机器人ID
+ * @returns
+ */
+export const resolveUsableBot = async (selfId?: string): Promise<AdapterType | undefined> => {
+  if (selfId) {
+    const matchedBot = karin.getBot(selfId) as AdapterType | undefined
+    if (matchedBot) return matchedBot
+  }
+
+  const reachable = await getReachableMasterBots()
+  if (reachable.length > 0) return reachable[0].bot
+
+  const { douyin, bilibili } = statBotId(Config.pushlist)
+  const preferredBotId = douyin.botId || bilibili.botId
+  if (preferredBotId) {
+    const matchedBot = karin.getBot(preferredBotId) as AdapterType | undefined
+    if (matchedBot) return matchedBot
+  }
+
+  const fallbackBotId = karin.getAllBotID()[0]
+  if (!fallbackBotId) return undefined
+
+  return karin.getBot(fallbackBotId) as AdapterType | undefined
+}
+
+/**
+ * 取触发者头像 URL，用于嵌到登录二维码中心当 logo。
+ *
+ * 适配器（如 console）可能不实现 getAvatarUrl 或返回空串，模板侧 avatarUrl 缺省即退化为普通二维码，
+ * 所以这里任何失败都只记 debug 日志并返回 undefined，不影响登录流程。
+ *
+ * @param e - 触发登录的消息事件
+ * @returns 头像 URL，取不到时为 undefined
+ */
+export const resolveTriggerAvatarUrl = async (e: Message): Promise<string | undefined> => {
+  const userId = e.sender?.userId || e.userId
+  if (!userId) return undefined
+
+  try {
+    const url = await e.bot.getAvatarUrl(userId)
+    return url || undefined
+  } catch (error) {
+    logger.debug('[koishi-plugin-kkk] 获取触发者头像失败，二维码将不嵌入头像:', error)
+    return undefined
+  }
+}

package/src/karin/module/utils/build-metadata.ts

@@ -0,0 +1,60 @@
+import fs from 'node:fs'
+import { resolve } from 'node:path'
+
+import { logger } from 'node-karin'
+
+import { Root } from '../../root'
+
+export interface BuildMetadata {
+  version: string
+  buildTime: string
+  buildTimestamp: number
+  name: string
+  description: string
+  homepage: string
+  commitHash: string
+  shortCommitHash: string
+}
+
+let cachedMetadata: BuildMetadata | null = null
+
+/**
+ * 获取构建元数据
+ * @returns 构建元数据对象，如果读取失败则返回 null
+ */
+export const getBuildMetadata = (): BuildMetadata | null => {
+  if (cachedMetadata) {
+    return cachedMetadata
+  }
+
+  try {
+    // 使用插件路径 + lib/build-metadata.json
+    // Root.pluginPath 指向插件根目录，构建后的元数据在 lib 目录下
+    const metadataPath = resolve(Root.pluginPath, 'lib/build-metadata.json')
+    if (fs.existsSync(metadataPath)) {
+      const content = fs.readFileSync(metadataPath, 'utf-8')
+      cachedMetadata = JSON.parse(content)
+      return cachedMetadata
+    }
+  } catch (error) {
+    logger.error('无法读取构建元数据:', error)
+  }
+
+  return null
+}
+
+/**
+ * 格式化构建时间为可读格式
+ * @param isoString ISO 格式的时间字符串
+ * @returns 格式化后的时间字符串，格式：2025年11月02日 17:30
+ */
+export const formatBuildTime = (isoString: string): string => {
+  const date = new Date(isoString)
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  const hour = String(date.getHours()).padStart(2, '0')
+  const minute = String(date.getMinutes()).padStart(2, '0')
+
+  return `${year}年${month}月${day}日 ${hour}:${minute}`
+}

package/src/karin/module/utils/changelog.ts

@@ -0,0 +1,175 @@
+import fs from 'node:fs'
+
+import type { ChangelogData } from '@template/template/other/changelog/components/types'
+import { Message, parseChangelog, range } from 'node-karin'
+import axios from 'node-karin/axios'
+
+// Koishi 移植：同样是为了断开 utils → changelog → '@/module' → utils 的环（见 coverTheme.ts 的说明）
+import { Root } from '../../root'
+import { baseHeaders } from './Network/constants'
+import { Render } from './Render'
+
+import { formatBuildTime, getBuildMetadata } from './build-metadata'
+import { isSemverGreater } from './semver'
+
+/**
+ * 规范化为 x.x.x（剔除 v 前缀、预发布、构建标识）
+ * @param v 版本字符串
+ * @returns 核心版本字符串
+ */
+const versionCore = (v: string): string => {
+  v = v.trim()
+  if (v.startsWith('v') || v.startsWith('V')) v = v.slice(1)
+  const [preBuild] = v.split('+', 2)
+  const [core] = preBuild.split('-', 2)
+  return core
+}
+
+const getLagVersionCount = (changelog: string, localVersion: string, remoteVersion: string): number => {
+  const local = versionCore(localVersion)
+  const remote = versionCore(remoteVersion)
+
+  if (!local || !remote || !isSemverGreater(remote, local)) return 0
+
+  const versions = Object.keys(parseChangelog(changelog)).map(versionCore).filter(Boolean)
+
+  const uniqueVersions = [...new Set(versions)]
+  return uniqueVersions.filter((version) => {
+    const afterLocal = isSemverGreater(version, local)
+    const notAfterRemote = !isSemverGreater(version, remote)
+    return afterLocal && notAfterRemote
+  }).length
+}
+
+/**
+ * 获取远程构建元数据
+ * @param version 远程版本号
+ * @returns 构建元数据对象，如果获取失败则返回 null
+ */
+const getRemoteBuildMetadata = async (version: string) => {
+  const urls = [
+    // 国内镜像（优先）
+    `https://jsd.onmicrosoft.cn/npm/${Root.pluginName}@${version}/lib/build-metadata.json`,
+    `https://npm.onmicrosoft.cn/${Root.pluginName}@${version}/lib/build-metadata.json`,
+    // 海外源
+    `https://cdn.jsdelivr.net/npm/${Root.pluginName}@${version}/lib/build-metadata.json`,
+    `https://fastly.jsdelivr.net/npm/${Root.pluginName}@${version}/lib/build-metadata.json`,
+    `https://unpkg.com/${Root.pluginName}@${version}/lib/build-metadata.json`
+  ]
+
+  const requests = urls.map((url) =>
+    axios.get(url, { timeout: 10000, headers: baseHeaders }).then((res) => {
+      if (res.data && typeof res.data === 'object') {
+        return res.data
+      }
+      throw new Error('Invalid metadata')
+    })
+  )
+
+  try {
+    const metadata = await Promise.any(requests)
+    return metadata
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 获取变更日志图片
+ *
+ * @param ctx - 渲染上下文，可传入消息事件或 Bot 实例
+ * @param props - 获取变更日志图片选项
+ * @param props.isRemote - 是否强制获取远程变更日志
+ * @returns 变更日志图片元素数组（base64）
+ */
+export const getChangelogImage = async (ctx: Message, props: Omit<ChangelogData, 'markdown'> & { isRemote?: boolean }) => {
+  let changelog = ''
+  let buildTime: string | undefined
+  let lagVersionCount = 0
+  const event = 'bot' in (ctx as any) ? (ctx as Message) : ({ bot: ctx } as unknown as Message)
+
+  if (props.Tip || props.isRemote) {
+    const urls = [
+      // 国内代理
+      `https://jsd.onmicrosoft.cn/npm/${Root.pluginName}@${props.remoteVersion}/CHANGELOG.md`,
+      `https://npm.onmicrosoft.cn/${Root.pluginName}@${props.remoteVersion}/CHANGELOG.md`,
+      // 海外源
+      `https://cdn.jsdelivr.net/npm/${Root.pluginName}@${props.remoteVersion}/CHANGELOG.md`,
+      `https://fastly.jsdelivr.net/npm/${Root.pluginName}@${props.remoteVersion}/CHANGELOG.md`,
+      `https://unpkg.com/${Root.pluginName}@${props.remoteVersion}/CHANGELOG.md`,
+      // GitHub Raw 代理
+      `https://gh.llkk.cc/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://j.1lin.dpdns.org/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://tvv.tw/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://git.yylx.win/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://gitproxy.127731.xyz/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://ghm.078465.xyz/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://ghfile.geekertao.top/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://github.tbedu.top/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://j.1win.ggff.net/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://ghm.078465.xyz/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://ghm.078465.xyz/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`,
+      `https://jiashu.1win.eu.org/https://raw.githubusercontent.com/ikenxuan/koishi-plugin-kkk/v${props.remoteVersion}/packages/core/CHANGELOG.md`
+    ]
+
+    // 并发竞速获取 CHANGELOG
+    const requests = urls.map((url) =>
+      axios.get(url, { timeout: 10000, headers: baseHeaders }).then((res) => {
+        if (typeof res.data === 'string' && res.data.length > 0) {
+          return res.data as string
+        }
+        throw new Error('Invalid changelog content')
+      })
+    )
+    try {
+      changelog = await Promise.any(requests)
+    } catch {
+      return null
+    }
+    if (!changelog) return null
+    lagVersionCount = getLagVersionCount(changelog, props.localVersion, props.remoteVersion)
+
+    // 获取远程构建元数据
+    const remoteMeta = await getRemoteBuildMetadata(props.remoteVersion)
+    if (remoteMeta?.buildTime) {
+      buildTime = formatBuildTime(remoteMeta.buildTime)
+    }
+
+    changelog = range({
+      data: changelog,
+      startVersion: props.localVersion,
+      endVersion: versionCore(props.remoteVersion),
+      compare: 'semver'
+    })
+  } else {
+    try {
+      changelog = fs.readFileSync(Root.pluginPath + '/CHANGELOG.md', 'utf8')
+      lagVersionCount = getLagVersionCount(changelog, props.localVersion, props.remoteVersion)
+      changelog = range({
+        data: changelog,
+        startVersion: props.localVersion,
+        endVersion: versionCore(props.remoteVersion),
+        compare: 'semver'
+      })
+    } catch {
+      return null
+    }
+
+    // 获取本地构建元数据
+    const localMeta = getBuildMetadata()
+    if (localMeta?.buildTime) {
+      buildTime = formatBuildTime(localMeta.buildTime)
+    }
+  }
+
+  const img = await Render(event, 'other/changelog', {
+    markdown: changelog,
+    Tip: props.Tip,
+    localVersion: props.localVersion,
+    remoteVersion: props.remoteVersion,
+    lagVersionCount,
+    buildTime,
+    share_url: `https://koishi-plugin-kkk-docs.vercel.app/diff?old=${props.localVersion}&new=latest`
+  })
+  return img || null
+}

package/src/karin/module/utils/index.ts

@@ -0,0 +1,10 @@
+export * from '../../root'
+export * from './Base'
+export * from './build-metadata'
+export * from './Common'
+export * from './EmojiReaction'
+export * from './FFmpeg'
+export * from './ImageHelper'
+export * from './MotionPhoto'
+export * from './Networks'
+export * from './Render'

package/src/karin/module/utils/loginSession.ts

@@ -0,0 +1,291 @@
+/**
+ * 扫码登录会话（Koishi 迁移补充）。
+ *
+ * 上游 koishi-plugin-kkk 依赖 amagi **v7** 的登录会话 API：
+ *   \`client.bilibili.login.qrcode()\` / \`client.douyin.login.qrcode()\` → \`session.watch({ onQrcode, onScanned, onSuccess })\`
+ * 而已发布的 amagi 6.6.0 只提供 fetcher（requestLoginQrcode / checkQrcodeStatus / passport 系列），
+ * client 上没有 \`login\` 命名空间。这里按 v7 的会话契约在本地补一层：
+ * 取码 → 轮询 → 扫码/确认回调 → 领取凭证，使移植后的登录命令可以直接复用。
+ *
+ * 回调语义与 v7 保持一致（上游依赖这一点）：
+ *   - **调用方回调抛错 → watch reject**，由上层登录命令自己 catch 并提示；
+ *   - **中止 / 轮询失败 / 二维码过期 → watch resolve 失败态**，上层按 \`outcome.error\` 分流。
+ */
+import axios from 'node-karin/axios'
+import { logger } from 'node-karin'
+
+/** 登录凭证 */
+export interface LoginCredential {
+  /** 完整登录 cookie（name=value; ...） */
+  cookie: string
+  /** B站：refresh_token */
+  refreshToken?: string
+}
+
+/** 二维码信息 */
+export interface LoginQrcode {
+  /** 二维码承载的内容（拿去生成图片） */
+  content: string
+  /** 剩余有效秒数 */
+  expiresInSec?: number
+  /** 轮询令牌（抖音：token；B站：qrcode_key） */
+  key?: string
+}
+
+export interface LoginWatchOptions {
+  signal?: AbortSignal
+  /** 总超时，默认 180 秒 */
+  timeoutMs?: number
+  onQrcode?: (qrcode: LoginQrcode) => unknown | Promise<unknown>
+  onScanned?: () => unknown | Promise<unknown>
+  onSuccess?: (credential: LoginCredential) => unknown | Promise<unknown>
+  /** 抖音的短信二次验证（当前未实现，触发时按失败结束） */
+  onChallenge?: (challenge: unknown) => unknown | Promise<unknown>
+}
+
+export type LoginOutcome = { ok: true } | { ok: false; error: LoginSessionError }
+
+/** 与 AmagiError 结构兼容的登录错误（kind / code / message 会被上层读取） */
+export class LoginSessionError extends Error {
+  kind: string
+  code: string
+  constructor (kind: string, code: string, message: string) {
+    super(message)
+    this.name = 'LoginSessionError'
+    this.kind = kind
+    this.code = code
+  }
+}
+
+export interface WatchableSession {
+  watch: (options?: LoginWatchOptions) => Promise<LoginOutcome>
+}
+
+export interface LoginNamespace {
+  qrcode: () => WatchableSession
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+/** 把 set-cookie 数组归一化成 \`name=value; name2=value2\`（丢掉 Path/Domain/Expires 等属性） */
+export function mergeSetCookie (setCookie?: string[] | string): string {
+  if (!setCookie) return ''
+  const list = Array.isArray(setCookie) ? setCookie : [setCookie]
+  const pairs: string[] = []
+  for (const item of list) {
+    const [pair] = String(item).split(';')
+    if (pair && pair.includes('=')) pairs.push(pair.trim())
+  }
+  return pairs.join('; ')
+}
+
+/** 从跨域跳转 URL 的 query 里取登录 cookie（B站扫码成功后的标准做法） */
+export function cookieFromCrossDomainUrl (url: string): string {
+  if (!url) return ''
+  try {
+    const parsed = new URL(url)
+    const names = ['SESSDATA', 'bili_jct', 'DedeUserID', 'DedeUserID__ckMd5', 'sid']
+    const pairs = names
+      .map((name) => {
+        const value = parsed.searchParams.get(name)
+        return value ? name + '=' + decodeURIComponent(value) : ''
+      })
+      .filter(Boolean)
+    return pairs.join('; ')
+  } catch {
+    return ''
+  }
+}
+
+/** 解开 amagi 信封：\`{success,data:{...}}\` → 内层数据 */
+function unwrap (envelope: any): any {
+  if (!envelope || typeof envelope !== 'object') return envelope
+  if ('success' in envelope) return envelope.data
+  return envelope
+}
+
+/**
+ * B站扫码登录会话（v7 契约）。
+ * 状态码：86101 未扫码 / 86090 已扫码未确认 / 0 成功 / 86038 已过期。
+ */
+export function createBilibiliLoginSession (fetcher: any): LoginNamespace {
+  return {
+    qrcode () {
+      return {
+        async watch (options: LoginWatchOptions = {}): Promise<LoginOutcome> {
+          let qrcodeKey = ''
+          let qrcodeContent = ''
+
+          // 1) 取码：只把网络调用包在 try 里
+          try {
+            const body = unwrap(await fetcher.requestLoginQrcode({})) ?? {}
+            const payload = body?.data ?? body
+            qrcodeKey = payload?.qrcode_key ?? ''
+            qrcodeContent = payload?.url ?? ''
+          } catch (error: any) {
+            return { ok: false, error: new LoginSessionError('api', 'QRCODE_FAILED', String(error?.message ?? error)) }
+          }
+          if (!qrcodeContent) {
+            return { ok: false, error: new LoginSessionError('api', 'QRCODE_FAILED', 'B站未返回二维码地址') }
+          }
+
+          // 2) 回调：抛错直接向上传播（与 v7 一致）
+          await options.onQrcode?.({ content: qrcodeContent, expiresInSec: 180, key: qrcodeKey })
+
+          // 3) 轮询
+          const deadline = Date.now() + (options.timeoutMs ?? 180_000)
+          let scannedNotified = false
+          while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+              return { ok: false, error: new LoginSessionError('aborted', 'ABORTED', '登录已取消') }
+            }
+            await sleep(2000)
+            if (options.signal?.aborted) {
+              return { ok: false, error: new LoginSessionError('aborted', 'ABORTED', '登录已取消') }
+            }
+
+            let pollCode = -1
+            let inner: any = {}
+            let payload: any = {}
+            try {
+              const body = unwrap(await fetcher.checkQrcodeStatus({ qrcode_key: qrcodeKey })) ?? {}
+              inner = body?.data ?? {}
+              payload = inner?.data ?? {}
+              pollCode = Number(payload?.code ?? body?.code ?? -1)
+            } catch (error: any) {
+              return { ok: false, error: new LoginSessionError('api', 'POLL_FAILED', String(error?.message ?? error)) }
+            }
+
+            if (pollCode === 86101) continue
+            if (pollCode === 86090) {
+              if (!scannedNotified) {
+                scannedNotified = true
+                await options.onScanned?.()
+              }
+              continue
+            }
+            if (pollCode === 86038) {
+              return { ok: false, error: new LoginSessionError('api', 'COOKIE_EXPIRED', '二维码已失效') }
+            }
+            if (pollCode === 0) {
+              const cookie = mergeSetCookie(inner?.headers?.['set-cookie'] ?? inner?.headers?.['Set-Cookie'])
+                || cookieFromCrossDomainUrl(payload?.url ?? '')
+              if (!cookie) {
+                return { ok: false, error: new LoginSessionError('api', 'COOKIE_MISSING', '登录成功但未取到 cookie') }
+              }
+              await options.onSuccess?.({ cookie, refreshToken: payload?.refresh_token })
+              return { ok: true }
+            }
+          }
+          return { ok: false, error: new LoginSessionError('timeout', 'TIMEOUT', '登录超时，未完成扫码') }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * 抖音扫码登录会话（v7 契约的精简版）。
+ *
+ * amagi 6.6.0 的 passport 流程：\`requestPassportQrcode\` 拿码与 session cookie，
+ * \`checkPassportQrcode\` 轮询（new/scanned/confirmed/expired/verify/risk/busy），
+ * confirmed 时需要跟随 \`redirectUrl\` 才能领到最终凭证。
+ * 短信二次验证（verify）暂未实现，触发时以明确错误结束。
+ */
+export function createDouyinLoginSession (fetcher: any): LoginNamespace {
+  return {
+    qrcode () {
+      return {
+        async watch (options: LoginWatchOptions = {}): Promise<LoginOutcome> {
+          let sessionCookie = ''
+          let token = ''
+          let content = ''
+          let expiresInSec = 60
+
+          try {
+            const body = unwrap(await fetcher.requestPassportQrcode({})) ?? {}
+            const payload = body?.data ?? body
+            sessionCookie = payload?.cookie ?? ''
+            token = payload?.token ?? ''
+            content = payload?.content ?? payload?.qrcode ?? ''
+            expiresInSec = payload?.expires_in ?? 60
+          } catch (error: any) {
+            return { ok: false, error: new LoginSessionError('api', 'QRCODE_FAILED', String(error?.message ?? error)) }
+          }
+          if (!content) {
+            return { ok: false, error: new LoginSessionError('api', 'QRCODE_FAILED', '抖音未返回二维码内容') }
+          }
+
+          await options.onQrcode?.({ content, expiresInSec, key: token })
+
+          const deadline = Date.now() + (options.timeoutMs ?? 180_000)
+          let scannedNotified = false
+          while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+              return { ok: false, error: new LoginSessionError('aborted', 'ABORTED', '登录已取消') }
+            }
+            await sleep(2000)
+            if (options.signal?.aborted) {
+              return { ok: false, error: new LoginSessionError('aborted', 'ABORTED', '登录已取消') }
+            }
+
+            let payload: any = {}
+            try {
+              const body = unwrap(await fetcher.checkPassportQrcode({ cookie: sessionCookie, token })) ?? {}
+              payload = body?.data ?? body
+            } catch (error: any) {
+              return { ok: false, error: new LoginSessionError('api', 'POLL_FAILED', String(error?.message ?? error)) }
+            }
+            if (payload?.cookie) sessionCookie = payload.cookie
+
+            switch (payload?.status) {
+              case 'new':
+              case 'busy':
+                break
+              case 'scanned':
+                if (!scannedNotified) {
+                  scannedNotified = true
+                  await options.onScanned?.()
+                }
+                break
+              case 'verify':
+                return { ok: false, error: new LoginSessionError('unsupported', 'NEED_VERIFY', '抖音触发了短信二次验证，当前暂不支持') }
+              case 'risk':
+                return { ok: false, error: new LoginSessionError('risk', 'RISK', payload?.message ?? '登录请求被抖音风控拦截') }
+              case 'expired':
+                return { ok: false, error: new LoginSessionError('api', 'COOKIE_EXPIRED', '二维码已失效') }
+              case 'confirmed': {
+                const cookie = await followRedirect(payload?.redirectUrl, sessionCookie)
+                const finalCookie = cookie || payload?.cookie || sessionCookie
+                if (!finalCookie) {
+                  return { ok: false, error: new LoginSessionError('api', 'COOKIE_MISSING', '登录成功但未取到 cookie') }
+                }
+                await options.onSuccess?.({ cookie: finalCookie })
+                return { ok: true }
+              }
+              default:
+                logger.debug('[抖音登录] 未识别的轮询状态: ' + JSON.stringify(payload).slice(0, 200))
+            }
+          }
+          return { ok: false, error: new LoginSessionError('timeout', 'TIMEOUT', '登录超时，未完成扫码') }
+        }
+      }
+    }
+  }
+}
+
+/** 跟随 redirectUrl 领取抖音最终登录凭证 */
+async function followRedirect (redirectUrl: string | undefined, sessionCookie: string): Promise<string> {
+  if (!redirectUrl) return ''
+  try {
+    const response = await axios.get(redirectUrl, {
+      headers: { Cookie: sessionCookie },
+      maxRedirects: 0,
+      validateStatus: () => true
+    })
+    return mergeSetCookie(response.headers?.['set-cookie'])
+  } catch (error: any) {
+    logger.debug('[抖音登录] 跟随 redirect 失败: ' + String(error?.message ?? error))
+    return ''
+  }
+}