@waterwx/dsh-novel-forge 2.0.0-alpha.1 → 2.0.0

package/src/llm-live.ts

@@ -0,0 +1,245 @@
+/**
+ * LLM 实况 feed：以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）
+ * 推给订阅者，并提供环形缓冲供新连上的客户端重放。
+ *
+ * 同时承担三件与用量有关的事（进程内，不落盘）：
+ *   1) **用量账本**：每次调用结束后按用途累计 token / 耗时，供 /status 展示；
+ *   2) **Prompt 记录**：保存每次调用实际发送的 system + user（环形，按需查询）；
+ *   3) **首字耗时**：调用方在拿到第一个文本增量时打点，用于观察模型响应速度。
+ */
+
+import type { BlockAssembler, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type {
+  LlmLiveFrame,
+  LlmPromptRecord,
+  LlmTokenUsage,
+  LlmUsageBucket,
+  LlmUsageSummary,
+} from './protocol.ts'
+
+export type { LlmLiveFrame }
+
+/** 帧缓冲上限（新连接重放用）。 */
+const MAX_BUFFER = 400
+/** Prompt 记录上限（环形，避免长跑吃内存）。 */
+const MAX_PROMPTS = 40
+/** 单条 Prompt 记录的最大字符数（system + user 合计），超出截断并标记。 */
+const MAX_PROMPT_CHARS = 60_000
+
+let buffer: LlmLiveFrame[] = []
+type Listener = (frame: LlmLiveFrame) => void
+let listeners = new Set<Listener>()
+let seq = 0
+
+/** 进程内用量账本。 */
+const usageTotals = {
+  calls: 0,
+  failed: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  reasoningTokens: 0,
+  totalTokens: 0,
+  elapsedMs: 0,
+  callsWithoutUsage: 0,
+  byLabel: new Map<string, LlmUsageBucket>(),
+}
+
+/** Prompt 记录（按 sessionId，保留最近 MAX_PROMPTS 条）。 */
+const prompts = new Map<string, LlmPromptRecord>()
+
+export function nextSessionId(): string {
+  seq++
+  return `ll-${Date.now().toString(36)}-${seq}`
+}
+
+export function subscribeLiveFeed(listener: Listener): () => void {
+  // 先重放现有缓冲（新连接能立即看到最近调用），再进入实时。
+  for (const frame of buffer) listener(frame)
+  listeners.add(listener)
+  return () => { listeners.delete(listener) }
+}
+
+export function emitLive(frame: LlmLiveFrame): void {
+  if (frame.type === 'session_completed') recordUsage(frame)
+  buffer.push(frame)
+  if (buffer.length > MAX_BUFFER) buffer = buffer.slice(-MAX_BUFFER)
+  for (const l of listeners) l(frame)
+}
+
+// ------------------------------------------------------------------ 用量账本
+
+/** 把 dsh-llm 的 usage 转成线上形状。 */
+export function toLiveUsage(usage: TokenUsage | undefined): LlmTokenUsage | undefined {
+  if (usage === undefined) return undefined
+  return {
+    inputTokens: usage.inputTokens ?? 0,
+    outputTokens: usage.outputTokens ?? 0,
+    totalTokens: usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0),
+    reasoningTokens: usage.reasoningTokens ?? 0,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+  }
+}
+
+/** 记一次已完成的调用（由 emitLive 内部调用）。 */
+function recordUsage(frame: LlmLiveFrame): void {
+  const failed = frame.phase === 'failed' ? 1 : 0
+  const usage = frame.usage
+  usageTotals.calls += 1
+  usageTotals.failed += failed
+  usageTotals.elapsedMs += frame.elapsedMs ?? 0
+  if (usage === undefined) {
+    usageTotals.callsWithoutUsage += 1
+  } else {
+    usageTotals.inputTokens += usage.inputTokens
+    usageTotals.outputTokens += usage.outputTokens
+    usageTotals.reasoningTokens += usage.reasoningTokens ?? 0
+    usageTotals.totalTokens += usage.totalTokens ?? usage.inputTokens + usage.outputTokens
+  }
+  const label = frame.label ?? '未标注调用'
+  const bucket = usageTotals.byLabel.get(label) ?? { label, calls: 0, failed: 0, inputTokens: 0, outputTokens: 0, reasoningTokens: 0, elapsedMs: 0 }
+  bucket.calls += 1
+  bucket.failed += failed
+  bucket.elapsedMs += frame.elapsedMs ?? 0
+  if (usage !== undefined) {
+    bucket.inputTokens += usage.inputTokens
+    bucket.outputTokens += usage.outputTokens
+    bucket.reasoningTokens += usage.reasoningTokens ?? 0
+  }
+  usageTotals.byLabel.set(label, bucket)
+}
+
+/** 本次运行的用量汇总（按耗时降序排列用途，便于看谁最贵）。 */
+export function liveUsage(): LlmUsageSummary {
+  return {
+    calls: usageTotals.calls,
+    failed: usageTotals.failed,
+    inputTokens: usageTotals.inputTokens,
+    outputTokens: usageTotals.outputTokens,
+    reasoningTokens: usageTotals.reasoningTokens,
+    totalTokens: usageTotals.totalTokens,
+    elapsedMs: usageTotals.elapsedMs,
+    callsWithoutUsage: usageTotals.callsWithoutUsage,
+    byLabel: [...usageTotals.byLabel.values()].sort((a, b) =>
+      (b.inputTokens + b.outputTokens + b.reasoningTokens) - (a.inputTokens + a.outputTokens + a.reasoningTokens)),
+  }
+}
+
+/** 清零用量账本（面板「重新计数」用）。 */
+export function resetLiveUsage(): void {
+  usageTotals.calls = 0
+  usageTotals.failed = 0
+  usageTotals.inputTokens = 0
+  usageTotals.outputTokens = 0
+  usageTotals.reasoningTokens = 0
+  usageTotals.totalTokens = 0
+  usageTotals.elapsedMs = 0
+  usageTotals.callsWithoutUsage = 0
+  usageTotals.byLabel.clear()
+}
+
+// ------------------------------------------------------------- Prompt 记录
+
+/** 记一条 Prompt（超长截断并标记）。 */
+export function recordPrompt(input: { sessionId: string; label?: string; model?: string; system?: string; user?: string }): LlmPromptRecord {
+  const system = input.system ?? ''
+  const user = input.user ?? ''
+  const chars = system.length + user.length
+  let record: LlmPromptRecord = {
+    sessionId: input.sessionId,
+    label: input.label,
+    model: input.model,
+    at: new Date().toISOString(),
+    system,
+    user,
+    chars,
+  }
+  if (chars > MAX_PROMPT_CHARS) {
+    // 优先保留 user（真正随调用变化的输入），system 按剩余预算截断。
+    const userPart = user.slice(0, MAX_PROMPT_CHARS)
+    const rest = MAX_PROMPT_CHARS - userPart.length
+    record = { ...record, user: userPart, system: system.slice(0, Math.max(0, rest)), truncated: true }
+  }
+  prompts.set(record.sessionId, record)
+  while (prompts.size > MAX_PROMPTS) {
+    const oldest = prompts.keys().next().value
+    if (oldest === undefined) break
+    prompts.delete(oldest)
+  }
+  return record
+}
+
+/** 取一条 Prompt 记录（不存在返回 undefined）。 */
+export function livePrompt(sessionId: string): LlmPromptRecord | undefined {
+  return prompts.get(sessionId)
+}
+
+// --------------------------------------------------------------- 调用打点
+
+/** 一次调用的打点句柄。 */
+export interface LiveCallHandle {
+  sessionId: string
+  startedAt: number
+  /** 用途（用于 session_completed 的用量分组）。 */
+  label: string
+  /** 实际使用的模型。 */
+  model: string
+  /** 首字耗时（毫秒），由 markFirstToken 写入。 */
+  firstTokenMs?: number
+}
+
+/**
+ * 开始一次 LLM 调用：发 session_started、记 Prompt、起计时。
+ *
+ * @param input 用途/模型/实际发送的 system 与 user。
+ * @returns 打点句柄（结束时交给 endLiveCall）。
+ */
+export function beginLiveCall(input: { label: string; model: string; system?: string; user?: string }): LiveCallHandle {
+  const handle: LiveCallHandle = { sessionId: nextSessionId(), startedAt: Date.now(), label: input.label, model: input.model }
+  const record = recordPrompt({ sessionId: handle.sessionId, label: input.label, model: input.model, system: input.system, user: input.user })
+  emitLive({
+    type: 'session_started',
+    sessionId: handle.sessionId,
+    label: input.label,
+    model: input.model,
+    at: new Date().toISOString(),
+    context: { interactionId: handle.sessionId },
+    hasPrompt: true,
+    promptChars: record.chars,
+  })
+  emitLive({ type: 'phase_changed', sessionId: handle.sessionId, phase: 'streaming', phaseMessage: '模型正在返回内容', at: new Date().toISOString() })
+  return handle
+}
+
+/** 首字打点（调用方在收到第一个文本增量时调用，只记第一次）。 */
+export function markFirstToken(handle: LiveCallHandle): void {
+  if (handle.firstTokenMs === undefined) handle.firstTokenMs = Date.now() - handle.startedAt
+}
+
+/**
+ * 结束一次 LLM 调用：从 assembler 取用量，发 session_completed（含 token/耗时/首字）。
+ *
+ * @param handle beginLiveCall 的句柄。
+ * @param assembler 本次调用的 BlockAssembler。
+ * @param extra 字符数/预览/失败信息等。
+ */
+export function endLiveCall(
+  handle: LiveCallHandle,
+  assembler: BlockAssembler,
+  extra: { chars?: number; preview?: string; phase?: 'completed' | 'failed'; error?: string } = {},
+): void {
+  const usage = toLiveUsage(assembler.usage)
+  emitLive({
+    type: 'session_completed',
+    sessionId: handle.sessionId,
+    label: handle.label,
+    model: handle.model,
+    at: new Date().toISOString(),
+    totalChars: extra.chars,
+    preview: extra.preview,
+    phase: extra.phase ?? 'completed',
+    error: extra.error,
+    usage,
+    elapsedMs: Date.now() - handle.startedAt,
+    firstTokenMs: handle.firstTokenMs,
+  })
+}

package/src/llm-retry.ts

@@ -0,0 +1,77 @@
+/**
+ * 模型失败恢复规则（纯逻辑，可离线单测）。
+ *
+ * 解决的问题：批量连写时，主模型偶发限流/超时/额度耗尽会让**整批中断**，
+ * 而换一个模型重试一次往往就能过去。规则：
+ *   1) 只对「可重试」错误切换模型——用户主动取消、参数/契约类错误不重试；
+ *   2) 备用模型为空或与主模型相同则不切换；
+ *   3) 备用模型也失败时，抛**原始错误**（保留主因，不掩盖现场）；
+ *   4) 每次调用最多切换一次。
+ */
+
+/** 可重试错误特征（网络/超时/限流/服务端/额度类）。 */
+const RETRYABLE_PATTERNS: readonly RegExp[] = [
+  /失败/, /超时/, /timeout/i,
+  /network|fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EAI_AGAIN|socket hang up|terminated/i,
+  /频繁|限流|rate\s*limit|too many requests|\b429\b|\b5\d\d\b/i,
+  /overload|unavailable|capacity|服务不可用|繁忙/i,
+  /quota|balance|credit|insufficient|额度|余额/i,
+]
+
+/** 明确不可重试的特征（用户取消 / 契约类）。 */
+const NON_RETRYABLE_PATTERNS: readonly RegExp[] = [
+  /\baborted\b|已取消|用户取消/i,
+  /不在计划中|尚未生成|参数|非法|无效|需要/i,
+]
+
+/**
+ * 判断一次 LLM 失败是否值得换模型重试。
+ *
+ * @param error 捕获到的异常。
+ * @returns 可重试时为 true。
+ */
+export function isRetryableLlmError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  if (NON_RETRYABLE_PATTERNS.some(re => re.test(message))) return false
+  return RETRYABLE_PATTERNS.some(re => re.test(message))
+}
+
+/**
+ * 判断是否应当切换到备用模型。
+ *
+ * @param fallbackModel 配置的备用模型（空串 = 未配置）。
+ * @param primaryModel 本次实际使用的主模型。
+ * @param error 捕获到的异常。
+ * @returns 应当切换时为 true。
+ */
+export function shouldSwitchModel(fallbackModel: string | undefined, primaryModel: string, error: unknown): boolean {
+  const fallback = (fallbackModel ?? '').trim()
+  if (fallback === '' || fallback === primaryModel) return false
+  return isRetryableLlmError(error)
+}
+
+/**
+ * 用主模型执行；失败且满足切换条件时，用备用模型再执行一次。
+ *
+ * @param input 主模型 / 备用模型 / 实际执行函数（接收本次要用的模型 id）。
+ * @returns 执行结果（备用模型成功时返回其结果）。
+ * @throws 主模型失败且未切换时抛原错误；切换后仍失败时同样抛**主模型的原始错误**。
+ */
+export async function withModelFallback<T>(
+  input: { model: string; fallbackModel?: string; onSwitch?: (from: string, to: string, error: unknown) => void },
+  run: (model: string) => Promise<T>,
+): Promise<T> {
+  try {
+    return await run(input.model)
+  } catch (error) {
+    const fallback = (input.fallbackModel ?? '').trim()
+    if (fallback === '' || fallback === input.model || !isRetryableLlmError(error)) throw error
+    input.onSwitch?.(input.model, fallback, error)
+    try {
+      return await run(fallback)
+    } catch {
+      // 备用模型也失败：抛主模型的原始错误，避免掩盖第一现场。
+      throw error
+    }
+  }
+}

package/src/market-radar-scan.ts

@@ -0,0 +1,35 @@
+/**
+ * 热门题材雷达：真实榜单扫榜（聚合各平台榜单源，容错）。
+ */
+import { collectMarketSource, MARKET_RADAR_SOURCES, type CollectedRankingItem, type MarketRadarPlatform, type MarketRadarListSource } from './market-radar-sources.ts'
+
+export interface MarketRadarGroup {
+  platform: MarketRadarPlatform
+  platformLabel: string
+  listKey: string
+  listLabel: string
+  status: 'ok' | 'error'
+  error?: string
+  items: CollectedRankingItem[]
+}
+
+export interface MarketScanResult {
+  scannedAt: string
+  groups: MarketRadarGroup[]
+}
+
+export async function scanMarketRanking(platforms?: string[]): Promise<MarketScanResult> {
+  const wanted = new Set<string>(platforms?.length ? platforms : ['fanqie', 'qidian', 'jinjiang'])
+  const sources = MARKET_RADAR_SOURCES.filter(s => wanted.has(s.platform))
+  const groups: MarketRadarGroup[] = []
+  await Promise.all(sources.map(async (source: MarketRadarListSource) => {
+    try {
+      const items = await collectMarketSource(source)
+      groups.push({ platform: source.platform, platformLabel: source.platformLabel, listKey: source.listKey, listLabel: source.listLabel, status: 'ok', items })
+    } catch (error) {
+      groups.push({ platform: source.platform, platformLabel: source.platformLabel, listKey: source.listKey, listLabel: source.listLabel, status: 'error', error: (error as Error).message, items: [] })
+    }
+  }))
+  const result: MarketScanResult = { scannedAt: new Date().toISOString(), groups }
+  return result
+}

package/src/market-radar-sources.ts

@@ -0,0 +1,173 @@
+/**
+ * 「热门题材雷达」真实榜单抓取源（公开榜单页面的地址与选择器，属事实性配置）。
+ * 用全局 fetch 抓取公开榜单移动版页面，正则抽取元数据；无第三方依赖。
+ */
+export type MarketRadarPlatform = 'fanqie' | 'qidian' | 'jinjiang'
+
+export interface MarketRadarListSource {
+  platform: MarketRadarPlatform
+  platformLabel: string
+  listKey: string
+  listLabel: string
+  channel: string
+  sourceUrl: string
+}
+
+export interface CollectedRankingItem {
+  rank: number
+  title: string
+  author?: string
+  category?: string
+  tags: string[]
+  synopsis?: string
+  heatLabel?: string
+  serialStatus?: string
+  sourceUrl: string
+}
+
+export const MARKET_RADAR_SOURCES: MarketRadarListSource[] = [
+  { platform: 'fanqie', platformLabel: '番茄小说', listKey: 'reading', listLabel: '阅读榜', channel: 'general', sourceUrl: 'https://fanqienovel.com/rank' },
+  { platform: 'fanqie', platformLabel: '番茄小说', listKey: 'new_book', listLabel: '新书榜', channel: 'general', sourceUrl: 'https://fanqienovel.com/rank/1_1' },
+  { platform: 'qidian', platformLabel: '起点中文网', listKey: 'hotsales', listLabel: '畅销榜', channel: 'male', sourceUrl: 'https://m.qidian.com/rank/hotsales/' },
+  { platform: 'qidian', platformLabel: '起点中文网', listKey: 'monthly_ticket', listLabel: '月票榜', channel: 'male', sourceUrl: 'https://m.qidian.com/rank/yuepiao/' },
+  { platform: 'qidian', platformLabel: '起点中文网', listKey: 'new_book', listLabel: '新书榜', channel: 'male', sourceUrl: 'https://m.qidian.com/rank/' },
+  { platform: 'jinjiang', platformLabel: '晋江文学城', listKey: 'monthly', listLabel: '月度榜', channel: 'female', sourceUrl: 'https://m.jjwxc.net/rank/naturalmore/5' },
+  { platform: 'jinjiang', platformLabel: '晋江文学城', listKey: 'quarterly', listLabel: '季度榜', channel: 'female', sourceUrl: 'https://m.jjwxc.net/rank/naturalmore/6' },
+  { platform: 'jinjiang', platformLabel: '晋江文学城', listKey: 'new_author', listLabel: '新晋作者榜', channel: 'female', sourceUrl: 'https://m.jjwxc.net/rank/naturalmore/29' },
+]
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"',
+}
+
+function decodeEntities(value: string): string {
+  return value.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (_, key: string) => {
+    if (key.startsWith('#')) {
+      const hexadecimal = key[1]?.toLowerCase() === 'x'
+      const code = Number.parseInt(key.slice(hexadecimal ? 2 : 1), hexadecimal ? 16 : 10)
+      return Number.isFinite(code) ? String.fromCodePoint(code) : ''
+    }
+    return NAMED_ENTITIES[key.toLowerCase()] ?? ''
+  })
+}
+
+function plainText(value: string | undefined): string {
+  return decodeEntities((value ?? '').replace(/<[^>]*>/g, ' ')).replace(/\s+/g, ' ').trim()
+}
+
+function absoluteUrl(base: string, value: string): string {
+  return new URL(value.startsWith('//') ? `https:${value}` : value, base).toString()
+}
+
+function extractTags(synopsis: string): string[] {
+  const bracketed = synopsis.match(/^[【〖\[]([^】〗\]]+)[】〗\]]/g) ?? []
+  return bracketed.flatMap((part) => plainText(part).replace(/^[【〖\[]|[】〗\]]$/g, '').split(/[+＋、|]/))
+    .map((tag) => tag.trim()).filter(Boolean).slice(0, 12)
+}
+
+export function hasPrivateUseCharacters(value: string | null | undefined): boolean {
+  return /[\uE000-\uF8FF]/u.test(value ?? '')
+}
+
+export function parseFanqieRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[] {
+  const blocks = html.match(/<div class="rank-book-item">[\s\S]*?(?=<div class="rank-book-item">|<\/main>|<footer|<\/body>)/g) ?? []
+  return blocks.slice(0, 30).flatMap((block, index) => {
+    const titleMatch = block.match(/<div class="title">\s*<a href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/)
+    if (!titleMatch) return []
+    const synopsis = plainText(block.match(/<div class="desc abstract[^>]*>([\s\S]*?)<\/div>/)?.[1])
+    const footer = plainText(block.match(/<div class="book-item-footer">([\s\S]*?)<\/div>/)?.[1])
+    return [{
+      rank: Number(block.match(/book-item-index"><h1>(\d+)<\/h1>/)?.[1] ?? index + 1),
+      title: plainText(titleMatch[2]),
+      author: plainText(block.match(/<div class="author">[\s\S]*?<span[^>]*>([\s\S]*?)<\/span>/)?.[1]),
+      tags: extractTags(synopsis),
+      synopsis: synopsis.slice(0, 800),
+      heatLabel: footer.match(/在读[^\s，。]*/)?.[0],
+      serialStatus: footer.match(/连载中|已完结/)?.[0],
+      sourceUrl: absoluteUrl(source.sourceUrl, titleMatch[1]),
+    }]
+  })
+}
+
+export function parseFanqieDetail(html: string, item: CollectedRankingItem): CollectedRankingItem {
+  const title = plainText(html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/)?.[1])
+  const author = plainText(html.match(/author-name-text[^>]*>([\s\S]*?)<\/a>/)?.[1])
+  const synopsis = plainText(html.match(/<div class="page-abstract-content"[^>]*>\s*<p[^>]*>([\s\S]*?)<\/p>/)?.[1])
+  if (!title || hasPrivateUseCharacters(title)) throw new Error('作品详情页未提供可读书名')
+  return {
+    ...item,
+    title,
+    author: author && !hasPrivateUseCharacters(author) ? author : undefined,
+    synopsis: synopsis && !hasPrivateUseCharacters(synopsis) ? synopsis.slice(0, 800) : undefined,
+    tags: synopsis && !hasPrivateUseCharacters(synopsis) ? extractTags(synopsis) : [],
+  }
+}
+
+export function parseQidianRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[] {
+  const escapedLabel = source.listLabel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const itemPattern = new RegExp(`<a[^>]+href="([^"]*\\/book\\/[^"?]+)[^"]*"[^>]*>[\\s\\S]*?<h2[^>]+title="${escapedLabel}第(\\d+)位"[^>]*>([\\s\\S]*?)<\\/h2>[\\s\\S]*?<p[^>]*class="[^"]*subTitle[^"]*"[^>]*>([\\s\\S]*?)<\\/p>[\\s\\S]*?<\\/a>`, 'g')
+  return Array.from(html.matchAll(itemPattern)).slice(0, 30).map((match) => {
+    const subTitle = plainText(match[4])
+    const parts = subTitle.split('·').map((part) => part.trim()).filter(Boolean)
+    return {
+      rank: Number(match[2]),
+      title: plainText(match[3]),
+      author: parts[0],
+      category: parts[1],
+      tags: parts[1] ? [parts[1]] : [],
+      heatLabel: parts[2],
+      sourceUrl: absoluteUrl(source.sourceUrl, match[1]),
+    }
+  })
+}
+
+export function parseJinjiangRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[] {
+  const items = Array.from(html.matchAll(/<li[^>]*>\s*<a href="(\/book2\/\d+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<\/li>/g))
+  return items.slice(0, 30).map((match, index) => ({
+    rank: index + 1,
+    title: plainText(match[2]),
+    tags: [],
+    sourceUrl: absoluteUrl(source.sourceUrl, match[1]),
+  }))
+}
+
+async function fetchHtml(url: string): Promise<string> {
+  const response = await fetch(url, {
+    headers: { 'user-agent': 'Mozilla/5.0 (compatible; dsh-novel-forge-radar/1.0; public-ranking-metadata-only)' },
+    signal: AbortSignal.timeout(20_000),
+  })
+  if (!response.ok) throw new Error(`榜单页面返回 HTTP ${response.status}`)
+  const bytes = await response.arrayBuffer()
+  const headerCharset = response.headers.get('content-type')?.match(/charset=([^;]+)/i)?.[1]?.trim()
+  const metaProbe = new TextDecoder('latin1').decode(bytes.slice(0, 4096))
+  const metaCharset = metaProbe.match(/charset\s*=\s*["']?([\w-]+)/i)?.[1]
+  const charset = headerCharset || metaCharset || 'utf-8'
+  return new TextDecoder(charset).decode(bytes)
+}
+
+async function hydrateFanqieItems(items: CollectedRankingItem[]): Promise<CollectedRankingItem[]> {
+  const hydrated: CollectedRankingItem[] = []
+  for (let offset = 0; offset < items.length; offset += 4) {
+    const batch = await Promise.all(items.slice(offset, offset + 4).map(async (item) => {
+      const containsObfuscatedText = [item.title, item.author, item.synopsis].some(hasPrivateUseCharacters)
+      if (!containsObfuscatedText) return item
+      try { return parseFanqieDetail(await fetchHtml(item.sourceUrl), item) }
+      catch { return null }
+    }))
+    hydrated.push(...batch.filter((item): item is CollectedRankingItem => item !== null))
+  }
+  return hydrated
+}
+
+export async function collectMarketSource(source: MarketRadarListSource): Promise<CollectedRankingItem[]> {
+  const html = await fetchHtml(source.sourceUrl)
+  const parsers: Record<MarketRadarPlatform, (value: string, item: MarketRadarListSource) => CollectedRankingItem[]> = {
+    fanqie: parseFanqieRanking,
+    qidian: parseQidianRanking,
+    jinjiang: parseJinjiangRanking,
+  }
+  const parsed = parsers[source.platform](html, source)
+  const items = source.platform === 'fanqie' ? await hydrateFanqieItems(parsed) : parsed
+  if (items.length === 0) throw new Error('榜单页面结构可能已变化，未识别到公开作品元数据')
+  return items
+}

package/src/migrate-output.ts

@@ -0,0 +1,76 @@
+/**
+ * 输出目录迁移（Migrate Output Dir）— 把一本书/默认输出目录的内容搬到新位置。
+ *
+ * 安全纪律（数据零丢失排序）：
+ *  1. copy 全部内容到新目录（源目录始终原样保留）；
+ *  2. 调用方完成配置写入 / 书架重指向后，最后一步才删源目录；
+ *  3. 中途任何失败，最坏情况只是新目录多一份副本，源数据零丢失。
+ */
+
+import { existsSync, mkdirSync, readdirSync, cpSync, rmSync, statSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+/** 目录内容清单（相对路径 + 总字节）。 */
+export interface DirContents {
+  files: string[]
+  bytes: number
+}
+
+/** 规范化路径用于比较（统一分隔符，Windows 忽略大小写）。 */
+export function normalizeDir(dir: string): string {
+  const r = resolve(dir.trim())
+  return process.platform === 'win32' ? r.toLowerCase() : r
+}
+
+/** 列出目录全部内容（递归；子目录以 `name/` 形式占位列出）。 */
+export function listDirContents(dir: string): DirContents {
+  const files: string[] = []
+  let bytes = 0
+  const walk = (rel: string): void => {
+    const abs = rel === '' ? dir : join(dir, rel)
+    for (const name of readdirSync(abs, { withFileTypes: true })) {
+      const childRel = rel === '' ? name.name : `${rel}/${name.name}`
+      if (name.isDirectory()) {
+        files.push(`${childRel}/`)
+        walk(childRel)
+      } else {
+        files.push(childRel)
+        try { bytes += statSync(join(dir, childRel)).size } catch { /* 竞态删除则跳过 */ }
+      }
+    }
+  }
+  if (existsSync(dir)) walk('')
+  return { files, bytes }
+}
+
+/**
+ * 把 from 全部内容复制到 to（源目录保留，删除由调用方在收尾执行）。
+ * 目标必须不存在或为空目录（防覆盖无关数据）；禁止互相嵌套的目录对。
+ * @returns 复制的顶层条目数。
+ */
+export function copyDirContents(from: string, to: string): number {
+  if (!existsSync(from)) throw new Error(`源目录不存在：${from}`)
+  const nf = normalizeDir(from)
+  const nt = normalizeDir(to)
+  if (nf === nt) throw new Error('新目录与当前目录相同')
+  // 嵌套防护：copy 进入自身会无限递归 / 自我复制。
+  if (nt.startsWith(nf + sep.toLowerCase()) || nf.startsWith(nt + sep.toLowerCase()) ||
+      nt.startsWith(nf + '/') || nf.startsWith(nt + '/')) {
+    throw new Error('新目录不能是当前目录的子目录（或反之）')
+  }
+  if (existsSync(to)) {
+    const entries = readdirSync(to)
+    if (entries.length > 0) throw new Error(`目标目录非空（${entries.length} 个条目），为防覆盖已中止：${to}`)
+  } else {
+    mkdirSync(to, { recursive: true })
+  }
+  const entries = readdirSync(from)
+  if (entries.length === 0) return 0
+  cpSync(from, to, { recursive: true, errorOnExist: true, force: false })
+  return entries.length
+}
+
+/** 删除源目录（仅复制 + 配置/书架重指向全部成功后调用）。 */
+export function removeDir(dir: string): void {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+}