@waterwx/dsh-novel-forge 1.3.0 → 1.3.1-alpha

package/src/market-radar-scan.ts

@@ -0,0 +1,41 @@
+/**
+ * 热门题材雷达：真实榜单扫榜（聚合各平台榜单源，容错）。
+ */
+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[]
+}
+
+let lastScan: MarketScanResult | null = null
+
+export function getLastMarketScan(): MarketScanResult | null {
+  return lastScan
+}
+
+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: [] })
+    }
+  }))
+  lastScan = { scannedAt: new Date().toISOString(), groups }
+  return lastScan
+}

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 })
+}

package/src/novel-context.ts

@@ -0,0 +1,286 @@
+/**
+ * 统一上下文组装与相关设定检索
+ *
+ * 取代各阶段各自拼装 prompt，消除「生成看得到、审稿看不到」的断层。
+ * 所有阶段通过 buildChapterContext 获取同一来源的事实与设定。
+ */
+
+import type { ProjectState, ChapterPlan, StoryBible, RoleRecord, ChapterFact, Foreshadow, Plotline } from './protocol'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface ChapterContext {
+  /** 平台合规红线（永远全量） */
+  complianceRedLines: string[]
+  /** 本书写作红线（永远全量） */
+  bookRedLines: string[]
+  /** 当前章相关角色卡（全量信息） */
+  relevantRoles: Array<{ name: string; role: string; traits: string[]; goals?: string; knowledge?: string[] }>
+  /** 当前章相关道藏规则 */
+  relevantWorldRules: string[]
+  /** 活跃剧情线 */
+  activePlotlines: Plotline[]
+  /** 未回收伏笔 */
+  activeForeshadows: Foreshadow[]
+  /** 上一章结尾原文 */
+  prevChapterTail: string
+  /** 上一章摘要 */
+  prevChapterSummary?: string
+  /** 最近事实（近因记忆，top20） */
+  recentFacts: string[]
+  /** 相关旧事实（按本章 beats 检索，top15） */
+  relatedFacts: string[]
+  /** 当前卷大纲 */
+  currentVolumeOutline: string
+  /** 本章 beats */
+  beats: string
+  /** 本章标题 */
+  chapterTitle: string
+}
+
+export interface ContextBuildOptions {
+  /** 阶段：writing/review/revise/polish/plan */
+  stage?: 'writing' | 'review' | 'revise' | 'polish' | 'plan'
+  /** 是否注入完整角色卡（false 时只注入角色名+定位） */
+  fullRoleCards?: boolean
+  /** 相关事实检索上限 */
+  relatedFactsLimit?: number
+  /** 最近事实数量 */
+  recentFactsLimit?: number
+}
+
+/**
+ * 相关事实检索：trigram 重合度 + 角色名命中加权 + 近因加权
+ * 从 generateChapterStream 抽取，扩展为通用函数。
+ */
+export function retrieveRelatedFacts(
+  facts: ChapterFact[],
+  beatsText: string,
+  roleNames: string[],
+  limit = 15,
+): string[] {
+  if (facts.length === 0) return []
+
+  const trigrams = (s: string): Set<string> => {
+    const out = new Set<string>()
+    for (let i = 0; i + 3 <= s.length; i++) {
+      const tri = s.slice(i, i + 3)
+      if (tri.trim() !== '') out.add(tri)
+    }
+    return out
+  }
+
+  const beatsTri = trigrams(beatsText)
+  const beatRoles = roleNames.filter(n => beatsText.includes(n))
+
+  const recentTexts = new Set(facts.slice(-20).map(f => f.text))
+
+  return facts
+    .map((f, idx) => {
+      const head = f.text.slice(0, 80)
+      let score = 0
+      for (const tri of trigrams(head)) if (beatsTri.has(tri)) score += 1
+      if (beatRoles.length > 0) {
+        for (const n of beatRoles) if (head.includes(n)) score += 8
+      }
+      // 近因加权：越新越优先（封顶 40 章）
+      score += Math.min(idx, 40) / 10
+      return { f, score }
+    })
+    .filter(x => x.score >= 3)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(x => `[第${x.f.chapterNo}章] ${x.f.text}`)
+    .filter(t => !recentTexts.has(t.slice(t.indexOf(']') + 2)))
+}
+
+/**
+ * 相关角色检索：beats 中出现的角色 + 主角/主要反派永远全量
+ */
+export function retrieveRelevantRoles(
+  bible: StoryBible | undefined,
+  roles: RoleRecord[] | undefined,
+  beatsText: string,
+): ChapterContext['relevantRoles'] {
+  const result: ChapterContext['relevantRoles'] = []
+  const seen = new Set<string>()
+
+  // 主角/主要反派永远全量
+  const alwaysRoles = (bible?.characters ?? []).filter(c =>
+    c.role === 'protagonist' || c.role === 'antagonist'
+  )
+  for (const card of alwaysRoles) {
+    if (seen.has(card.name)) continue
+    seen.add(card.name)
+    result.push({
+      name: card.name,
+      role: card.role,
+      traits: card.traits,
+      goals: card.goals !== '' ? card.goals : undefined,
+      knowledge: Array.isArray(card.knowledge) && card.knowledge.length > 0 ? card.knowledge : undefined,
+    })
+  }
+
+  // beats 中出现的角色
+  const beatRoles = (bible?.characters ?? []).filter(c => beatsText.includes(c.name))
+  for (const card of beatRoles) {
+    if (seen.has(card.name)) continue
+    seen.add(card.name)
+    result.push({
+      name: card.name,
+      role: card.role,
+      traits: card.traits,
+      goals: card.goals !== '' ? card.goals : undefined,
+      knowledge: Array.isArray(card.knowledge) && card.knowledge.length > 0 ? card.knowledge : undefined,
+    })
+  }
+
+  // 角色库补充（不在道藏里的）
+  for (const r of roles ?? []) {
+    if (seen.has(r.name)) continue
+    if (!beatsText.includes(r.name) && r.roleLabel !== 'protagonist' && r.roleLabel !== 'antagonist') continue
+    seen.add(r.name)
+    result.push({
+      name: r.name,
+      role: r.roleLabel,
+      traits: Array.isArray(r.traits) ? r.traits : [],
+      goals: r.goals !== undefined && r.goals !== '' ? r.goals : undefined,
+    })
+  }
+
+  return result
+}
+
+/**
+ * 构建章节统一上下文
+ *
+ * 各阶段调用此函数获取同一来源的事实与设定，消除上下文断层。
+ * 检索结果不足时自动回退全量，保证不丢失关键信息。
+ */
+export function buildChapterContext(
+  project: ProjectState,
+  chapter: ChapterPlan,
+  outputDir: string,
+  options: ContextBuildOptions = {},
+): ChapterContext {
+  const {
+    fullRoleCards = true,
+    relatedFactsLimit = 15,
+    recentFactsLimit = 20,
+  } = options
+
+  const bible = project.bible
+  const allFacts = project.facts ?? []
+  const roleNames = (project.roles ?? []).map(r => r.name).filter((n): n is string => typeof n === 'string' && n !== '')
+
+  // 上一章结尾 + 摘要
+  let prevChapterTail = ''
+  let prevChapterSummary: string | undefined
+  const prev = project.chapters.find(c => c.no === chapter.no - 1)
+  if (prev?.file !== undefined) {
+    try {
+      const prevPath = join(outputDir, prev.file)
+      if (existsSync(prevPath)) {
+        const text = readFileSync(prevPath, 'utf8')
+        prevChapterTail = text.replace(/^#\s+.*$/m, '').trim().slice(-900)
+      }
+    } catch { /* 文件缺失时忽略 */ }
+  }
+  prevChapterSummary = prev?.summary
+
+  // 事实：最近 + 相关
+  const recentFacts = allFacts.slice(-recentFactsLimit).map(f => `[第${f.chapterNo}章] ${f.text}`)
+  const relatedFacts = retrieveRelatedFacts(allFacts, chapter.beats, roleNames, relatedFactsLimit)
+
+  // 角色：相关角色
+  const relevantRoles = retrieveRelevantRoles(bible, project.roles, chapter.beats)
+
+  // 道藏规则：全部（规则数量通常不多，全量注入更安全）
+  const relevantWorldRules = bible?.worldRules ?? []
+
+  // 活跃剧情线
+  const activePlotlines = (project.plotlines ?? []).filter(l =>
+    l.status === 'active' || l.status === 'paused'
+  )
+
+  // 未回收伏笔
+  const activeForeshadows = (project.foreshadows ?? []).filter(f =>
+    f.status === 'planted' || f.status === 'progressing'
+  )
+
+  // 当前卷大纲
+  const volumeNo = chapter.volume ?? 0
+  const volume = project.volumes?.find(v => v.no === volumeNo)
+  const currentVolumeOutline = volume !== undefined
+    ? `第${volume.no}卷《${volume.title}》：${volume.summary}`
+    : ''
+
+  return {
+    complianceRedLines: [], // 由调用方注入 COMPLIANCE_REDLINES
+    bookRedLines: bible?.redLines ?? [],
+    relevantRoles: fullRoleCards ? relevantRoles : relevantRoles.map(r => ({ name: r.name, role: r.role, traits: [] })),
+    relevantWorldRules,
+    activePlotlines,
+    activeForeshadows,
+    prevChapterTail,
+    prevChapterSummary,
+    recentFacts,
+    relatedFacts,
+    currentVolumeOutline,
+    beats: chapter.beats,
+    chapterTitle: chapter.title,
+  }
+}
+
+/**
+ * 将上下文渲染为 prompt 文本块
+ * 各阶段可按需选择注入哪些块。
+ */
+export function renderContextBlocks(ctx: ChapterContext): {
+  rolesBlock: string
+  worldRulesBlock: string
+  factsBlock: string
+  plotlinesBlock: string
+  foreshadowsBlock: string
+  continuityBlock: string
+  redLinesBlock: string
+} {
+  const roleName = { protagonist: '主角', supporting: '配角', antagonist: '反派', other: '其他', female_lead: '女主', female_support: '女配', support: '配角', extra: '路人' } as Record<string, string>
+
+  const rolesBlock = ctx.relevantRoles.length > 0
+    ? '==================== 相关角色卡 ====================\n' +
+      ctx.relevantRoles.map(r =>
+        `- ${r.name}（${roleName[r.role] ?? r.role}）：${r.traits.join('、')}${r.goals ? `；目标：${r.goals}` : ''}${r.knowledge ? `\n  已知信息：${r.knowledge.join('；')}（未列出的该角色不知道）` : ''}`
+      ).join('\n')
+    : ''
+
+  const worldRulesBlock = ctx.relevantWorldRules.length > 0
+    ? '==================== 世界规则 ====================\n' + ctx.relevantWorldRules.map(r => `- ${r}`).join('\n')
+    : ''
+
+  const factsBlock = (ctx.recentFacts.length > 0 || ctx.relatedFacts.length > 0)
+    ? '==================== 事实库（最近 + 相关） ====================\n' +
+      (ctx.recentFacts.length > 0 ? `【最近 ${ctx.recentFacts.length} 条】\n${ctx.recentFacts.join('\n')}` : '') +
+      (ctx.relatedFacts.length > 0 ? `\n【相关旧事实 ${ctx.relatedFacts.length} 条】\n${ctx.relatedFacts.join('\n')}` : '')
+    : ''
+
+  const plotlinesBlock = ctx.activePlotlines.length > 0
+    ? '==================== 活跃剧情线 ====================\n' +
+      ctx.activePlotlines.map(l => `- [${l.kind}${l.status === 'paused' ? '·暂停' : ''}] ${l.name}：${l.goal}${l.progress ? `（进度：${l.progress}）` : ''}`).join('\n')
+    : ''
+
+  const foreshadowsBlock = ctx.activeForeshadows.length > 0
+    ? '==================== 活跃伏笔 ====================\n' +
+      ctx.activeForeshadows.map(f => `- [${f.status === 'planted' ? '已埋设' : '推进中'}] ${f.description}${f.targetChapter ? `（预计第${f.targetChapter}章回收）` : ''}`).join('\n')
+    : ''
+
+  const continuityBlock = ctx.prevChapterTail !== ''
+    ? `==================== 上一章结尾（紧接此状态继续） ====================\n${ctx.prevChapterTail}`
+    : ''
+
+  const redLinesBlock = ctx.bookRedLines.length > 0
+    ? '==================== 本书红线 ====================\n' + ctx.bookRedLines.map(r => `- ${r}`).join('\n')
+    : ''
+
+  return { rolesBlock, worldRulesBlock, factsBlock, plotlinesBlock, foreshadowsBlock, continuityBlock, redLinesBlock }
+}