@waterwx/dsh-novel-forge 0.1.0 → 1.0.0-alpha

package/src/routes.ts

@@ -1,955 +1,3277 @@
-/**
- * The /api/dsh-novel-forge route family: status, docx outline loading, LLM
- * story-bible extraction, volume planning, chapter planning, streaming
- * generation / rewrite / polish (NDJSON frames), review, summaries,
- * foreshadows, export, chapter reading, config patching, and opening the
- * output folder. Every route carries the same loopback-only trust fence as
- * the family plugins — these endpoints invoke the LLM and write files on the
- * host machine.
- */
-
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import { exec } from 'node:child_process'
-import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
-import type { Context } from '@deepseek-ai/cordis'
-import {
-  NOVEL_API,
-  type AssetsPatch,
-  type AssetsResponse,
-  type AssistantFrame,
-  type AssistantHistoryResponse,
-  type AssistantRequest,
-  type BibleRequest,
-  type BibleResponse,
-  type BookActivateRequest,
-  type BookCreateRequest,
-  type BookRemoveRequest,
-  type BookshelfSnapshot,
-  type ChapterResponse,
-  type ChapterPlan,
-  type ConfigPatch,
-  type ExportRequest,
-  type ExportResponse,
-  type ForeshadowRequest,
-  type ForeshadowResponse,
-  type JobFrame,
-  type LoadOutlineRequest,
-  type LoadOutlineResponse,
-  type NovelConfig,
-  type PlanRequest,
-  type PlanResponse,
-  type PolishRequest,
-  type ReviewRequest,
-  type RewriteRequest,
-  type StatusResponse,
-  type StyleEngineRequest,
-  type SummaryRequest,
-  type VolumesRequest,
-  type VolumesResponse,
-} from './protocol.ts'
-import { readOutlineFromDocx } from './docx.ts'
-import { loadAssistantHistory, runAssistantTurn } from './assistant.ts'
-import { activateBook, bookshelfSnapshot, createBook, defaultOutputDirFor, loadBookshelf, removeBook, seedBookshelfFromOutputDir } from './bookshelf.ts'
-import { BUILTIN_ANTI_AI_RULES, BUILTIN_GENRE_LIBRARY, BUILTIN_PROGRESSION_MODES, BUILTIN_STYLE_TEMPLATES, emptyProjectAssets } from './assets.ts'
-import {
-  chapterFileName,
-  createProject,
-  exportBook,
-  extractBible,
-  extractStyleAsset,
-  generateChapterStream,
-  listChapterFiles,
-  loadProject,
-  planChapters,
-  planVolumes,
-  polishChapterStream,
-  readChapterFile,
-  reviewChapter,
-  rewriteChapterStream,
-  saveProject,
-  suggestForeshadows,
-  summarizeChapter,
-  syncProjectWithDisk,
-} from './engine.ts'
-
-/** Cap on JSON request bodies. */
-const MAX_JSON_BODY_BYTES = 4 * 1024 * 1024
-
-/** Loopback-only fence (mirrors the family plugins' pairing routes). */
-function isLoopbackRequest(request: IncomingMessage): boolean {
-  const address = request.socket.remoteAddress
-  if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1') return false
-  const host = request.headers.host
-  if (typeof host !== 'string') return false
-  let hostUrl: URL
-  try {
-    hostUrl = new URL(`http://${host}`)
-  } catch {
-    return false
-  }
-  if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]') return false
-  if (request.headers['sec-fetch-site'] === 'cross-site') return false
-  const origin = request.headers.origin
-  if (origin === undefined) return true
-  try {
-    return new URL(origin).host === hostUrl.host
-  } catch {
-    return false
-  }
-}
-
-/** One JSON response. */
-function writeJson(res: ServerResponse, status: number, body: unknown): void {
-  const payload = JSON.stringify(body)
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
-  res.end(payload)
-}
-
-/** Read a JSON request body. */
-async function readJsonBody<T>(req: IncomingMessage): Promise<T | undefined> {
-  const chunks: Buffer[] = []
-  let size = 0
-  for await (const chunk of req) {
-    const buffer = chunk as Buffer
-    size += buffer.length
-    if (size > MAX_JSON_BODY_BYTES) return undefined
-    chunks.push(buffer)
-  }
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString('utf8')) as T
-  } catch {
-    return undefined
-  }
-}
-
-/** Route deps. */
-export interface NovelRoutesDeps {
-  ctx: Context
-  /** Resolve the live plugin config (settings-aware). */
-  getConfig: () => NovelConfig
-  /** Persist a config patch through the settings seam. */
-  patchConfig: (patch: ConfigPatch) => Promise<NovelConfig>
-}
-
-/** Default chapter count for planning when the request omits it. */
-const DEFAULT_PLAN_COUNT = 30
-
-/**
- * Build every /api/dsh-novel-forge route.
- * @param deps - context, config resolver, config patcher.
- * @returns the route list.
- */
-export function makeRoutes(deps: NovelRoutesDeps): WebRoute[] {
-  const { ctx, getConfig, patchConfig } = deps
-
-  /** Guard helper: fence + method check. */
-  const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
-    if (!isLoopbackRequest(req)) {
-      writeJson(res, 403, { error: 'forbidden: loopback-only' })
-      return false
-    }
-    if (req.method !== method) {
-      writeJson(res, 405, { error: `method not allowed (expected ${method})` })
-      return false
-    }
-    return true
-  }
-
-  /** Load (and sync) the project, or respond 400. */
-  const requireProject = (res: ServerResponse): ReturnType<typeof loadProject> => {
-    const config = getConfig()
-    const project = loadProject(config.outputDir)
-    if (project === undefined) {
-      writeJson(res, 400, { error: '输出目录中没有项目，请先加载大纲' })
-      return undefined
-    }
-    syncProjectWithDisk(project, config.outputDir)
-    saveProject(config.outputDir, project)
-    return project
-  }
-
-  // -------------------------------------------------------------- status
-  const statusRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.status,
-    handler: (req, res) => {
-      if (!guard(req, res, 'GET')) return
-      const config = getConfig()
-      // 书架为空时播种 settings 默认输出目录里的已有项目。
-      seedBookshelfFromOutputDir(config.outputDir)
-      const project = loadProject(config.outputDir)
-      if (project !== undefined) {
-        syncProjectWithDisk(project, config.outputDir)
-        saveProject(config.outputDir, project)
-      }
-      const response: StatusResponse = {
-        config,
-        project: project ?? undefined,
-        generatedFiles: listChapterFiles(config.outputDir),
-      }
-      writeJson(res, 200, response)
-    },
-  }
-
-  // -------------------------------------------------------- load-outline
-  const loadOutlineRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.loadOutline,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<LoadOutlineRequest>(req)
-      const config = getConfig()
-      try {
-        let outline: string
-        let path: string | undefined
-        if (body?.text !== undefined && body.text.trim() !== '') {
-          outline = body.text.trim()
-        } else {
-          const target = body?.path?.trim() !== '' && body?.path !== undefined ? body.path : config.outlinePath
-          outline = readOutlineFromDocx(target)
-          path = target
-        }
-        if (outline.length < 50) {
-          writeJson(res, 400, { error: '大纲内容过短（<50 字符），请检查文件或直接粘贴大纲文本' })
-          return
-        }
-        const response: LoadOutlineResponse = {
-          outline,
-          bookName: createProject(outline).bookName,
-          chars: outline.length,
-          path,
-        }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 400, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // -------------------------------------------------------- save-outline
-  const saveOutlineRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.saveOutline,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<LoadOutlineRequest>(req)
-      const config = getConfig()
-      const outline = body?.text ?? ''
-      if (outline.trim().length < 50) {
-        writeJson(res, 400, { error: '大纲内容过短（<50 字符）' })
-        return
-      }
-      let project = loadProject(config.outputDir)
-      const now = new Date().toISOString()
-      if (project === undefined) {
-        project = createProject(outline)
-      } else {
-        project.outline = outline
-        project.bookName = createProject(outline).bookName
-        project.updatedAt = now
-      }
-      saveProject(config.outputDir, project)
-      writeJson(res, 200, { ok: true, bookName: project.bookName })
-    },
-  }
-
-  // --------------------------------------------------------------- bible
-  const bibleRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.bible,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<BibleRequest>(req)
-      const config = getConfig()
-      const project = loadProject(config.outputDir)
-      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
-        ? body.outline
-        : project?.outline
-      if (outline === undefined || outline.length < 50) {
-        writeJson(res, 400, { error: '请先加载大纲' })
-        return
-      }
-      try {
-        const bible = await extractBible(ctx, config, outline)
-        const now = new Date().toISOString()
-        const next = project ?? createProject(outline)
-        next.bible = bible
-        next.updatedAt = now
-        saveProject(config.outputDir, next)
-        const response: BibleResponse = { bible }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ------------------------------------------------------------- volumes
-  const volumesRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.volumes,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<VolumesRequest>(req)
-      const config = getConfig()
-      const project = loadProject(config.outputDir)
-      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
-        ? body.outline
-        : project?.outline
-      if (outline === undefined || outline.length < 50) {
-        writeJson(res, 400, { error: '请先加载大纲' })
-        return
-      }
-      try {
-        const volumes = await planVolumes(ctx, config, outline)
-        const now = new Date().toISOString()
-        const next = project ?? createProject(outline)
-        next.volumes = volumes
-        next.updatedAt = now
-        saveProject(config.outputDir, next)
-        const response: VolumesResponse = { volumes }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ----------------------------------------------------------------- plan
-  const planRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.plan,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<PlanRequest>(req)
-      const config = getConfig()
-      const project = loadProject(config.outputDir)
-      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
-        ? body.outline
-        : project?.outline
-      if (outline === undefined || outline.length < 50) {
-        writeJson(res, 400, { error: '请先加载大纲（或粘贴大纲文本）' })
-        return
-      }
-      const count = body?.chapterCount ?? DEFAULT_PLAN_COUNT
-      if (!Number.isInteger(count) || count < 1 || count > 200) {
-        writeJson(res, 400, { error: 'chapterCount 须为 1-200 的整数' })
-        return
-      }
-      try {
-        const next = project ?? createProject(outline)
-        const chapters: ChapterPlan[] = await planChapters(ctx, config, next, count, body?.volume)
-        next.chapters.push(...chapters)
-        next.updatedAt = new Date().toISOString()
-        saveProject(config.outputDir, next)
-        const response: PlanResponse = { chapters, volumes: next.volumes }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ------------------------------------------------------------- generate
-  const generateRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.generate,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<{ chapterNo?: number; skipReview?: boolean }>(req)
-      const rawNo = body?.chapterNo
-      if (!Number.isInteger(rawNo) || rawNo === undefined || rawNo < 1) {
-        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
-        return
-      }
-      const no: number = rawNo
-      const chapter = project.chapters.find(c => c.no === no)
-      if (chapter === undefined) {
-        writeJson(res, 404, { error: `章节 ${no} 不在计划中` })
-        return
-      }
-      if (chapter.status === 'generating') {
-        writeJson(res, 409, { error: `章节 ${no} 正在生成中` })
-        return
-      }
-
-      // NDJSON stream.
-      res.writeHead(200, {
-        'content-type': 'application/x-ndjson; charset=utf-8',
-        'cache-control': 'no-cache',
-        'x-accel-buffering': 'no',
-        'referrer-policy': 'no-referrer',
-      })
-      chapter.status = 'generating'
-      chapter.error = undefined
-      saveProject(config.outputDir, project)
-
-      const send = (frame: JobFrame): void => {
-        res.write(JSON.stringify(frame) + '\n')
-      }
-
-      try {
-        send({ type: 'start', no, title: chapter.title })
-        for await (const step of generateChapterStream(ctx, config, project, config.outputDir, no)) {
-          if (step.frame === 'delta') {
-            send({ type: 'delta', text: step.text })
-          } else if (step.frame === 'done') {
-            send({ type: 'done', no, file: step.file, chars: step.chars, title: chapter.title })
-          }
-        }
-        // Auto pipeline: summary -> review (unless skipped).
-        try {
-          await summarizeChapter(ctx, config, project, config.outputDir, no)
-        } catch (error) {
-          console.warn('[dsh-novel-forge] summary failed:', (error as Error).message)
-        }
-        if (!(body?.skipReview === true) && (config.autoReview ?? true)) {
-          const report = await reviewChapter(ctx, config, project, config.outputDir, no)
-          send({ type: 'review', no, report })
-        } else {
-          chapter.status = 'approved'
-          saveProject(config.outputDir, project)
-        }
-        res.end()
-      } catch (error) {
-        chapter.status = 'error'
-        chapter.error = (error as Error).message
-        saveProject(config.outputDir, project)
-        if (!res.writableEnded) {
-          send({ type: 'error', no, message: (error as Error).message })
-          res.end()
-        }
-      }
-    },
-  }
-
-  // --------------------------------------------------------------- review
-  const reviewRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.review,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<ReviewRequest>(req)
-      if (!Number.isInteger(body?.chapterNo)) {
-        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
-        return
-      }
-      const no = body!.chapterNo!
-      try {
-        const report = await reviewChapter(ctx, config, project, config.outputDir, no)
-        writeJson(res, 200, { report })
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // -------------------------------------------------------------- rewrite
-  const rewriteRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.rewrite,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<RewriteRequest>(req)
-      if (!Number.isInteger(body?.chapterNo)) {
-        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
-        return
-      }
-      const no = body!.chapterNo!
-      res.writeHead(200, {
-        'content-type': 'application/x-ndjson; charset=utf-8',
-        'cache-control': 'no-cache',
-        'x-accel-buffering': 'no',
-        'referrer-policy': 'no-referrer',
-      })
-      const send = (frame: JobFrame): void => { res.write(JSON.stringify(frame) + '\n') }
-      try {
-        for await (const step of rewriteChapterStream(ctx, config, project, config.outputDir, no, body?.instructions ?? '', body?.target)) {
-          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
-          else if (step.frame === 'done') send({ type: 'rewritten', no, file: step.file, chars: step.chars })
-        }
-        // Re-review after rewrite.
-        const report = await reviewChapter(ctx, config, project, config.outputDir, no)
-        send({ type: 'review', no, report })
-        res.end()
-      } catch (error) {
-        if (!res.writableEnded) {
-          send({ type: 'error', no, message: (error as Error).message })
-          res.end()
-        }
-      }
-    },
-  }
-
-  // --------------------------------------------------------------- polish
-  const polishRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.polish,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<PolishRequest>(req)
-      if (!Number.isInteger(body?.chapterNo)) {
-        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
-        return
-      }
-      const no = body!.chapterNo!
-      res.writeHead(200, {
-        'content-type': 'application/x-ndjson; charset=utf-8',
-        'cache-control': 'no-cache',
-        'x-accel-buffering': 'no',
-        'referrer-policy': 'no-referrer',
-      })
-      const send = (frame: JobFrame): void => { res.write(JSON.stringify(frame) + '\n') }
-      try {
-        for await (const step of polishChapterStream(ctx, config, project, config.outputDir, no)) {
-          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
-          else if (step.frame === 'done') send({ type: 'rewritten', no, file: step.file, chars: step.chars })
-        }
-        res.end()
-      } catch (error) {
-        if (!res.writableEnded) {
-          send({ type: 'error', no, message: (error as Error).message })
-          res.end()
-        }
-      }
-    },
-  }
-
-  // -------------------------------------------------------------- summary
-  const summaryRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.summary,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<SummaryRequest>(req)
-      if (!Number.isInteger(body?.chapterNo)) {
-        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
-        return
-      }
-      try {
-        const summary = await summarizeChapter(ctx, config, project, config.outputDir, body!.chapterNo!)
-        writeJson(res, 200, { summary })
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ---------------------------------------------------------- foreshadow
-  const foreshadowRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.foreshadow,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<ForeshadowRequest>(req)
-      try {
-        if (body?.suggest === true) {
-          // AI suggestion pass: create several foreshadows from the outline.
-          const created = await suggestForeshadows(ctx, config, project)
-          project.updatedAt = new Date().toISOString()
-          saveProject(config.outputDir, project)
-          const response: ForeshadowResponse = { foreshadows: created }
-          writeJson(res, 200, response)
-          return
-        }
-        if (body?.id !== undefined) {
-          // Update an existing foreshadow.
-          const target = project.foreshadows.find(f => f.id === body.id)
-          if (target === undefined) {
-            writeJson(res, 404, { error: `伏笔 ${body.id} 不存在` })
-            return
-          }
-          if (body.description !== undefined) target.description = body.description
-          if (body.plantedChapter !== undefined) target.plantedChapter = body.plantedChapter
-          if (body.targetChapter !== undefined) target.targetChapter = body.targetChapter
-          if (body.status !== undefined) target.status = body.status
-          if (body.resolvedNote !== undefined) target.resolvedNote = body.resolvedNote
-        } else {
-          // Create one manually.
-          const description = body?.description?.trim()
-          if (description === undefined || description === '') {
-            writeJson(res, 400, { error: 'description 必填' })
-            return
-          }
-          project.foreshadows.push({
-            id: `fs-${Date.now().toString(36)}`,
-            description,
-            plantedChapter: body?.plantedChapter,
-            targetChapter: body?.targetChapter,
-            status: body?.status ?? 'planned',
-          })
-        }
-        project.updatedAt = new Date().toISOString()
-        saveProject(config.outputDir, project)
-        const response: ForeshadowResponse = { foreshadows: project.foreshadows }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // -------------------------------------------------------------- export
-  const exportRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.exportBook,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<ExportRequest>(req)
-      const format = body?.format === 'md' ? 'md' : 'txt'
-      try {
-        const result = exportBook(config.outputDir, project, format)
-        const response: ExportResponse = { ...result }
-        writeJson(res, 200, response)
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // -------------------------------------------------------------- chapter
-  const chapterRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.chapter,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'GET')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const url = new URL(req.url ?? '/', 'http://localhost')
-      const rawNo = Number(url.searchParams.get('no') ?? '0')
-      if (!Number.isInteger(rawNo) || rawNo < 1) {
-        writeJson(res, 400, { error: 'no 须为正整数' })
-        return
-      }
-      const chapter = project.chapters.find(c => c.no === rawNo)
-      if (chapter === undefined) {
-        writeJson(res, 404, { error: `章节 ${rawNo} 不在计划中` })
-        return
-      }
-      const markdown = readChapterFile(config.outputDir, chapter)
-      if (markdown === undefined) {
-        writeJson(res, 404, { error: `章节 ${rawNo} 尚未生成` })
-        return
-      }
-      const response: ChapterResponse = { no: chapter.no, title: chapter.title, markdown }
-      writeJson(res, 200, response)
-    },
-  }
-
-  // ----------------------------------------------------------- assistant
-  const assistantRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.assistant,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = requireProject(res)
-      if (project === undefined) return
-      const body = await readJsonBody<AssistantRequest>(req)
-      const message = body?.message?.trim()
-      if (message === undefined || message === '') {
-        writeJson(res, 400, { error: '消息不能为空' })
-        return
-      }
-      res.writeHead(200, {
-        'content-type': 'application/x-ndjson; charset=utf-8',
-        'cache-control': 'no-cache',
-        'x-accel-buffering': 'no',
-        'referrer-policy': 'no-referrer',
-      })
-      const send = (frame: AssistantFrame): void => { res.write(JSON.stringify(frame) + '\n') }
-      try {
-        for await (const step of runAssistantTurn(ctx, config, project, config.outputDir, message)) {
-          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
-          else if (step.frame === 'tool') send({ type: 'tool', name: step.name, status: step.status, detail: step.detail })
-          else if (step.frame === 'toolDelta') send({ type: 'toolDelta', name: step.name, text: step.text })
-        }
-        send({ type: 'done' })
-        res.end()
-      } catch (error) {
-        if (!res.writableEnded) {
-          send({ type: 'error', message: (error as Error).message })
-          res.end()
-        }
-      }
-    },
-  }
-
-  // -------------------------------------------------- assistant-history
-  const assistantHistoryRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.assistantHistory,
-    handler: (req, res) => {
-      if (!guard(req, res, 'GET')) return
-      const config = getConfig()
-      const response: AssistantHistoryResponse = { messages: loadAssistantHistory(config.outputDir) }
-      writeJson(res, 200, response)
-    },
-  }
-
-  // --------------------------------------------------------------- assets
-  const assetsRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.assets,
-    handler: async (req, res) => {
-      // GET (read) and POST (patch) are both allowed — check methods first,
-      // then the loopback fence (guard() would 405 on POST, which is wrong).
-      if (req.method !== 'GET' && req.method !== 'POST') {
-        writeJson(res, 405, { error: 'method not allowed (expected GET or POST)' })
-        return
-      }
-      if (!isLoopbackRequest(req)) {
-        writeJson(res, 403, { error: 'forbidden: loopback-only' })
-        return
-      }
-      const config = getConfig()
-      const project = loadProject(config.outputDir)
-      const projectAssets = project?.assets ?? emptyProjectAssets()
-      if (req.method === 'POST') {
-        const body = await readJsonBody<AssetsPatch>(req)
-        if (body === undefined) {
-          writeJson(res, 400, { error: '无效的 JSON' })
-          return
-        }
-        if (project === undefined) {
-          writeJson(res, 400, { error: '请先加载大纲创建项目' })
-          return
-        }
-        if (body.genre !== undefined) projectAssets.genre = body.genre
-        if (body.primaryProgression !== undefined) projectAssets.primaryProgression = body.primaryProgression
-        if (body.auxiliaryProgressions !== undefined) projectAssets.auxiliaryProgressions = body.auxiliaryProgressions
-        if (body.antiAiRules !== undefined) projectAssets.antiAiRules = body.antiAiRules
-        if (body.styleAssets !== undefined) projectAssets.styleAssets = body.styleAssets
-        projectAssets.updatedAt = new Date().toISOString()
-        project.assets = projectAssets
-        project.updatedAt = new Date().toISOString()
-        saveProject(config.outputDir, project)
-      }
-      const response: AssetsResponse = {
-        projectAssets,
-        genreLibrary: BUILTIN_GENRE_LIBRARY,
-        antiAiLibrary: BUILTIN_ANTI_AI_RULES,
-        styleTemplates: BUILTIN_STYLE_TEMPLATES,
-        progressionLibrary: BUILTIN_PROGRESSION_MODES,
-      }
-      writeJson(res, 200, response)
-    },
-  }
-
-  // ----------------------------------------------------------- style-engine
-  const styleEngineRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.styleEngine,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const project = loadProject(config.outputDir)
-      const body = await readJsonBody<StyleEngineRequest>(req)
-      const sample = body?.sampleText?.trim()
-      if (sample === undefined || sample.length < 50) {
-        writeJson(res, 400, { error: '样本文本过短（<50 字符），请粘贴一段能代表目标风格的文字' })
-        return
-      }
-      try {
-        const rules = await extractStyleAsset(ctx, config, sample)
-        const name = body?.name?.trim() !== '' && body?.name !== undefined ? body.name : `风格资产 ${Date.now().toString(36)}`
-        const styleAsset = {
-          name: name.slice(0, 40),
-          ...rules,
-          sourceText: sample.slice(0, 3000),
-          createdAt: new Date().toISOString(),
-        }
-        if (project !== undefined) {
-          project.assets ??= emptyProjectAssets()
-          project.assets.styleAssets ??= []
-          project.assets.styleAssets.push(styleAsset)
-          project.assets.updatedAt = new Date().toISOString()
-          project.updatedAt = new Date().toISOString()
-          saveProject(config.outputDir, project)
-        }
-        writeJson(res, 200, { styleAsset })
-      } catch (error) {
-        writeJson(res, 500, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ------------------------------------------------------------- bookshelf
-  const bookshelfRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.bookshelf,
-    handler: async (req, res) => {
-      // GET = snapshot; POST = create book.
-      if (req.method === 'GET') {
-        if (!isLoopbackRequest(req)) {
-          writeJson(res, 403, { error: 'forbidden: loopback-only' })
-          return
-        }
-        // 书架为空时，把 settings 默认输出目录里已有的项目播种为第一本书。
-        seedBookshelfFromOutputDir(getConfig().outputDir)
-        const snapshot: BookshelfSnapshot = bookshelfSnapshot(loadBookshelf())
-        writeJson(res, 200, snapshot)
-        return
-      }
-      if (req.method === 'POST') {
-        if (!isLoopbackRequest(req)) {
-          writeJson(res, 403, { error: 'forbidden: loopback-only' })
-          return
-        }
-        const body = await readJsonBody<BookCreateRequest>(req)
-        const bookName = body?.bookName?.trim()
-        if (bookName === undefined || bookName === '') {
-          writeJson(res, 400, { error: 'bookName 不能为空' })
-          return
-        }
-        const outputDir = body?.outputDir?.trim() !== '' && body?.outputDir !== undefined
-          ? body.outputDir
-          : defaultOutputDirFor(bookName)
-        const book = createBook(bookName, outputDir)
-        writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
-        void book
-        return
-      }
-      writeJson(res, 405, { error: 'method not allowed (expected GET or POST)' })
-    },
-  }
-
-  // --------------------------------------------------- bookshelf activate
-  const bookshelfActivateRoute: WebRoute = {
-    kind: 'exact',
-    path: '/api/dsh-novel-forge/bookshelf/activate',
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<BookActivateRequest>(req)
-      if (body?.id === undefined || body.id === '') {
-        writeJson(res, 400, { error: 'id 不能为空' })
-        return
-      }
-      const book = activateBook(body.id)
-      if (book === undefined) {
-        writeJson(res, 404, { error: `书 ${body.id} 不存在` })
-        return
-      }
-      writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
-    },
-  }
-
-  // ---------------------------------------------------- bookshelf remove
-  const bookshelfRemoveRoute: WebRoute = {
-    kind: 'exact',
-    path: '/api/dsh-novel-forge/bookshelf/remove',
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<BookRemoveRequest>(req)
-      if (body?.id === undefined || body.id === '') {
-        writeJson(res, 400, { error: 'id 不能为空' })
-        return
-      }
-      const removed = removeBook(body.id)
-      if (!removed) {
-        writeJson(res, 404, { error: `书 ${body.id} 不存在` })
-        return
-      }
-      writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
-    },
-  }
-
-  // --------------------------------------------------------------- config
-  const configRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.config,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const body = await readJsonBody<ConfigPatch>(req)
-      if (body === undefined) {
-        writeJson(res, 400, { error: '无效的配置 JSON' })
-        return
-      }
-      try {
-        const next = await patchConfig(body)
-        writeJson(res, 200, { config: next })
-      } catch (error) {
-        writeJson(res, 400, { error: (error as Error).message })
-      }
-    },
-  }
-
-  // ---------------------------------------------------------- open-folder
-  const openFolderRoute: WebRoute = {
-    kind: 'exact',
-    path: NOVEL_API.openFolder,
-    handler: async (req, res) => {
-      if (!guard(req, res, 'POST')) return
-      const config = getConfig()
-      const dir = config.outputDir
-      exec(`explorer "${dir.replace(/"/g, '')}"`, (error) => {
-        if (error) {
-          writeJson(res, 500, { ok: false, error: error.message })
-        } else {
-          writeJson(res, 200, { ok: true })
-        }
-      })
-    },
-  }
-
-  return [
-    statusRoute,
-    loadOutlineRoute,
-    saveOutlineRoute,
-    bibleRoute,
-    volumesRoute,
-    planRoute,
-    generateRoute,
-    reviewRoute,
-    rewriteRoute,
-    polishRoute,
-    summaryRoute,
-    foreshadowRoute,
-    exportRoute,
-    chapterRoute,
-    assetsRoute,
-    styleEngineRoute,
-    assistantRoute,
-    assistantHistoryRoute,
-    bookshelfRoute,
-    bookshelfActivateRoute,
-    bookshelfRemoveRoute,
-    configRoute,
-    openFolderRoute,
-  ]
-}
-
-// Re-export for tests / type consumers.
-export type {
-  ConfigPatch,
-  NovelConfig,
-  StatusResponse,
-  PlanResponse,
-  LoadOutlineResponse,
-  BibleResponse,
-  VolumesResponse,
-  ExportResponse,
-}
-export { chapterFileName }
+/**
+ * The /api/dsh-novel-forge route family: status, docx outline loading, LLM
+ * story-bible extraction, volume planning, chapter planning, streaming
+ * generation / rewrite / polish (NDJSON frames), review, summaries,
+ * foreshadows, export, chapter reading, config patching, and opening the
+ * output folder. Every route carries the same loopback-only trust fence as
+ * the family plugins — these endpoints invoke the LLM and write files on the
+ * host machine.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { spawn } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join, basename, extname } from 'node:path'
+import { homedir } from 'node:os'
+import { randomBytes } from 'node:crypto'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { Context } from '@deepseek-ai/cordis'
+import { ProductionRunner } from './run.ts'
+import {
+  NOVEL_API,
+  type AssetsPatch,
+  type AssetsResponse,
+  type AddModelRequest,
+  type AddModelResponse,
+  type LlmModelsResponse,
+  type LlmProvidersResponse,
+  type LlmVendorsResponse,
+  type RemoveProviderRequest,
+  type RemoveProviderResponse,
+  type AssistantFrame,
+  type AssistantHistoryResponse,
+  type AssistantRequest,
+  type AuditResponse,
+  type AuditStatus,
+  type AuthorReview,
+  type BiblePatchRequest,
+  type BibleRequest,
+  type BlurbRequest,
+  type CoverRequest,
+  type CoverResponse,
+  type RenameRequest,
+  type WorldRequest,
+  type BibleResponse,
+  type BookActivateRequest,
+  type BookCreateRequest,
+  type BookImportDirRequest,
+  type BookImportDirResponse,
+  type BookImportTextRequest,
+  type BookImportTextResponse,
+  type BookImportTextPreviewRequest,
+  type BookImportTextPreviewResponse,
+  type BookRemoveRequest,
+  type BookshelfSnapshot,
+  type ChapterResponse,
+  type ChapterPlan,
+  type ChapterSaveResponse,
+  type ChapterTextRequest,
+  type ConfigPatch,
+  type DraftDecisionRequest,
+  type ExportRequest,
+  type ExportResponse,
+  type ForeshadowRequest,
+  type ForeshadowResponse,
+  type JobFrame,
+  type LoadOutlineRequest,
+  type LoadOutlineResponse,
+  type NovelConfig,
+  type PlotlinesRequest,
+  type PlotlinesResponse,
+  type PlanRequest,
+  type PlanResponse,
+  type PolishRequest,
+  type ResetRequest,
+  type ReviewReport,
+  type ReviewRequest,
+  type RunControlRequest,
+  type RunStartRequest,
+  type RunState,
+  type RewriteRequest,
+  type RolesRequest,
+  type RolesResponse,
+  type OutlineSuggestRequest,
+  type OutlineSuggestResponse,
+  type BreakdownRequest,
+  type BreakdownResponse,
+  type SensitiveCheckRequest,
+  type SensitiveCheckResponse,
+  type SensitiveHit,
+  type ProjectState,
+  type StatusResponse,
+  type StoryBible,
+  type LlmTestRequest,
+  type LlmTestResponse,
+  type StyleEngineRequest,
+  type SummaryRequest,
+  type VolumesRequest,
+  type VolumesResponse,
+  type AuthorAssetsResponse,
+  type AuthorAssetUpsertRequest,
+  type AuthorAssetRemoveRequest,
+  type AdaptAnalyzeRequest,
+  type AdaptAnalyzeResponse,
+  type AdaptProposeRequest,
+  type AdaptProposeResponse,
+  type AdaptExecuteRequest,
+  type AdaptExecuteResponse,
+  type AdaptSaveRequest,
+  type AdaptSaveResponse,
+  type AdaptMaterializeRequest,
+  type AdaptMaterializeResponse,
+  type AdaptMaterializeSaveRequest,
+  type AdaptMaterializeSaveResponse,
+  type AdaptRewriteFrame,
+  type PluginUpdateResponse,
+  type MarketRadarRequest,
+  type MarketRadarBriefRequest,
+  type ProductionFoundation,
+  type ProgressionMode,
+  type GenreNode,
+  type KnowledgeDoc,
+  type KnowledgeRequest,
+  type BookAnalysisRequest,
+  type IdeaInspirationRequest,
+  type DirectorRequest,
+  type DirectorTodo,
+} from './protocol.ts'
+import { readOutlineFromDocx } from './docx.ts'
+import { clearAssistantHistory, loadAssistantHistory, runAssistantTurn } from './assistant.ts'
+import { activateBook, bookshelfSnapshot, createBook, defaultOutputDirFor, importDir, loadBookshelf, removeBook, renameBook, seedBookshelfFromOutputDir } from './bookshelf.ts'
+import { loadAuthorAssets, upsertAuthorAsset, removeAuthorAsset, importDefaultAuthorAssets } from './author-assets.ts'
+import { BUILTIN_ANTI_AI_RULES, BUILTIN_GENRE_LIBRARY, BUILTIN_PLOT_BEATS, BUILTIN_PROGRESSION_MODES, BUILTIN_STARTER_STYLE_PROFILES, BUILTIN_STYLE_TEMPLATES, emptyProjectAssets, ensureBuiltinAssets } from './assets.ts'
+import { scanAiFlavor } from './ai-scan.ts'
+import { emitLive, nextSessionId, subscribeLiveFeed } from './llm-live.ts'
+import { scanMarketRanking } from './market-radar-scan.ts'
+import { addGlobalGenre, addGlobalMode, globalGenreLibrary, globalProgressionLibrary } from './global-assets.ts'
+import {
+  chapterFileName,
+  auditBook,
+  authorReviewChapter,
+  autoLinkPlotlines,
+  backfillFacts,
+  createProject,
+  exportBook,
+  importBookText,
+  importBookTextFromText,
+  previewBookText,
+  extractBible,
+  extractStyleAsset,
+  extractStyleFormula,
+  runMarketRadar,
+  runMarketCreativeBrief,
+  runBookAnalysis,
+  runIdeaInspiration,
+  runMarketIdeaInspiration,
+  runDirectorAdvice,
+  extractWorld,
+  generateBlurb,
+  generateChapterStream,
+  listChapterFiles,
+  loadProject,
+  markForeshadowPlanted,
+  mergeVolatileFromDisk,
+  planChapters,
+  planVolumes,
+  polishChapterStream,
+  readChapterFile,
+  refreshCharacters,
+  refreshPlotlineProgress,
+  reviewChapter,
+  reviewChapterText,
+  rewriteChapterStream,
+  saveProject,
+  analyzePlotlineHealth,
+  designPlotlinePlan,
+  extractRoles,
+  suggestOutlines,
+  reverseOutlineFromChapters,
+  breakdownBook,
+  analyzeAdaptation,
+  proposeAdaptation,
+  applyAdaptationReplacements,
+  rewriteAdaptationBook,
+  materializeAdaptedBook,
+  saveMaterializedBook,
+  testLlmModel,
+  registerLlmModel,
+  listLlmVendors,
+  listLlmModels,
+  listLlmProviders,
+  removeLlmProvider,
+  checkSensitiveText,
+  suggestForeshadows,
+  suggestPlotlines,
+  summarizeAndExtractFacts,
+  summarizeChapter,
+  syncProjectWithDisk,
+} from './engine.ts'
+
+/** Cap on JSON request bodies (generous: cover images travel as base64). */
+const MAX_JSON_BODY_BYTES = 64 * 1024 * 1024
+
+/** 包内置风格效果图目录（assets/styles，随 npm 包分发）。 */
+
+/** 解析请求级目标书目录：优先按请求携带的 bookId 查书架，否则回退全局 active 书目录。 */
+function resolveOutputDir(config: NovelConfig, bookId?: string): string {
+  if (bookId !== undefined && bookId !== '') {
+    const book = loadBookshelf().books.find(b => b.id === bookId)
+    if (book !== undefined && book.outputDir !== '') return book.outputDir
+  }
+  return config.outputDir
+}
+
+/** Loopback-only fence (mirrors the family plugins' pairing routes). */
+function isLoopbackRequest(request: IncomingMessage): boolean {
+  const address = request.socket.remoteAddress
+  if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1') return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]') return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+/** One JSON response. */
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
+  res.end(payload)
+}
+
+/** Read a JSON request body. */
+async function readJsonBody<T>(req: IncomingMessage): Promise<T | undefined> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > MAX_JSON_BODY_BYTES) return undefined
+    chunks.push(buffer)
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8')) as T
+  } catch {
+    return undefined
+  }
+}
+
+/** Route deps. */
+export interface NovelRoutesDeps {
+  ctx: Context
+  /** Resolve the live plugin config (settings-aware). */
+  getConfig: () => NovelConfig
+  /** Persist a config patch through the settings seam. */
+  patchConfig: (patch: ConfigPatch) => Promise<NovelConfig>
+}
+
+/** Default chapter count for planning when the request omits it. */
+const DEFAULT_PLAN_COUNT = 30
+
+/**
+ * Build every /api/dsh-novel-forge route.
+ * @param deps - context, config resolver, config patcher.
+ * @returns the route list.
+ */
+export function makeRoutes(deps: NovelRoutesDeps): WebRoute[] {
+  const { ctx, getConfig, patchConfig } = deps
+
+  /** 全书质检实时状态（内存态，重启后回到 idle；用于 /status 暴露进度）。 */
+  let auditState: AuditStatus = { status: 'idle', totalBatches: 0, completedBatches: 0 }
+
+  /** Guard helper: fence + method check. */
+  const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
+    if (!isLoopbackRequest(req)) {
+      writeJson(res, 403, { error: 'forbidden: loopback-only' })
+      return false
+    }
+    if (req.method !== method) {
+      writeJson(res, 405, { error: `method not allowed (expected ${method})` })
+      return false
+    }
+    return true
+  }
+
+  /** Load (and sync) the project, or respond 400. */
+  const requireProject = (res: ServerResponse): ReturnType<typeof loadProject> => {
+    const config = getConfig()
+    const project = loadProject(config.outputDir)
+    if (project === undefined) {
+      writeJson(res, 400, { error: '输出目录中没有项目，请先加载大纲' })
+      return undefined
+    }
+    syncProjectWithDisk(project, config.outputDir)
+    saveProject(config.outputDir, project)
+    return project
+  }
+
+  // -------------------------------------------------------------- status
+  const statusRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.status,
+    handler: (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      const config = getConfig()
+      const qurl = new URL(req.url ?? '/', 'http://localhost')
+      const outputDir = resolveOutputDir(config, qurl.searchParams.get('bookId') ?? undefined)
+      // 书架为空时播种 settings 默认输出目录里的已有项目。
+      seedBookshelfFromOutputDir(outputDir)
+      const project = loadProject(outputDir)
+      if (project !== undefined) {
+        // 自动兜底：generating 超过 10 分钟（正常一章 2-5 分钟）视为卡死/中断，
+        // 复位为 pending，避免"生成中"状态卡死无法重新生成。
+        const staleMs = 10 * 60 * 1000
+        for (const c of project.chapters) {
+          if (c.status === 'generating' && c.generatingAt !== undefined) {
+            const started = new Date(c.generatingAt).getTime()
+            if (Number.isFinite(started) && Date.now() - started > staleMs) {
+              c.status = 'pending'
+              c.error = undefined
+              c.generatingAt = undefined
+            }
+          }
+        }
+        syncProjectWithDisk(project, outputDir)
+        saveProject(outputDir, project)
+      }
+      const slim = new URL(req.url ?? '/', 'http://localhost').searchParams.get('slim') === '1'
+      let projectPayload: StatusResponse['project']
+      if (project === undefined) {
+        projectPayload = undefined
+      } else if (slim) {
+        // slim 瘦身：轮询/角标只需章节状态与分数 + 轻量元数据，
+        // 去掉正文、beats、图集（base64）、道藏/大世界/资产等重字段，避免长书轮询反复传输大体积。
+        projectPayload = {
+          bookName: project.bookName,
+          outline: project.outline.slice(0, 200),
+          chapters: project.chapters.map(c => ({
+            no: c.no,
+            volume: c.volume,
+            title: c.title,
+            status: c.status,
+            chars: c.chars,
+            error: c.error,
+            review: c.review !== undefined ? { score: c.review.score, passed: c.review.passed } : undefined,
+          })) as unknown as ProjectState['chapters'],
+          createdAt: project.createdAt,
+          updatedAt: project.updatedAt,
+        } as unknown as ProjectState
+      } else {
+        // 瘦身：facts 只回最近 80 条（客户端最多展示 60），避免长篇后
+        // status 响应体随编年录无限膨胀。
+        projectPayload = { ...project, facts: (project.facts ?? []).slice(-80) }
+      }
+      const response: StatusResponse = {
+        config,
+        project: projectPayload,
+        generatedFiles: listChapterFiles(config.outputDir),
+        audit: auditState,
+      }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // -------------------------------------------------------- load-outline
+  const loadOutlineRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.loadOutline,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<LoadOutlineRequest>(req)
+      const config = getConfig()
+      try {
+        let outline: string
+        let path: string | undefined
+        if (body?.text !== undefined && body.text.trim() !== '') {
+          outline = body.text.trim()
+        } else {
+          const target = body?.path?.trim() !== '' && body?.path !== undefined ? body.path : config.outlinePath
+          outline = readOutlineFromDocx(target)
+          path = target
+        }
+        if (outline.length < 50) {
+          writeJson(res, 400, { error: '大纲内容过短（<50 字符），请检查文件或直接粘贴大纲文本' })
+          return
+        }
+        const response: LoadOutlineResponse = {
+          outline,
+          bookName: createProject(outline).bookName,
+          chars: outline.length,
+          path,
+        }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 400, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // -------------------------------------------------------- save-outline
+  const saveOutlineRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.saveOutline,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<LoadOutlineRequest>(req)
+      const config = getConfig()
+      const outline = body?.text ?? ''
+      if (outline.trim().length < 50) {
+        writeJson(res, 400, { error: '大纲内容过短（<50 字符）' })
+        return
+      }
+      let project = loadProject(config.outputDir)
+      const now = new Date().toISOString()
+      if (project === undefined) {
+        project = createProject(outline)
+      } else {
+        project.outline = outline
+        project.bookName = createProject(outline).bookName
+        project.updatedAt = now
+      }
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { ok: true, bookName: project.bookName })
+    },
+  }
+
+  // --------------------------------------------------------------- bible
+  const bibleRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bible,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BibleRequest>(req)
+      const config = getConfig()
+      const project = loadProject(config.outputDir)
+      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
+        ? body.outline
+        : project?.outline
+      if (outline === undefined || outline.length < 50) {
+        writeJson(res, 400, { error: '请先加载大纲' })
+        return
+      }
+      try {
+        const bible = await extractBible(ctx, config, outline, project)
+        const now = new Date().toISOString()
+        const next = project ?? createProject(outline)
+        next.bible = bible
+        next.updatedAt = now
+        saveProject(config.outputDir, next)
+        const response: BibleResponse = { bible }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- volumes
+  const volumesRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.volumes,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<VolumesRequest & { bookId?: string }>(req)
+      const config0 = getConfig()
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
+        ? body.outline
+        : project?.outline
+      if (outline === undefined || outline.length < 50) {
+        writeJson(res, 400, { error: '请先加载大纲' })
+        return
+      }
+      try {
+        const volumes = await planVolumes(ctx, config, outline)
+        const now = new Date().toISOString()
+        const next = project ?? createProject(outline)
+        next.volumes = volumes
+        next.updatedAt = now
+        saveProject(outputDir, next)
+        const response: VolumesResponse = { volumes }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ----------------------------------------------------------------- plan
+  const planRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.plan,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<PlanRequest & { bookId?: string }>(req)
+      const config0 = getConfig()
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      const outline = body?.outline?.trim() !== '' && body?.outline !== undefined
+        ? body.outline
+        : project?.outline
+      if (outline === undefined || outline.length < 50) {
+        writeJson(res, 400, { error: '请先加载大纲（或粘贴大纲文本）' })
+        return
+      }
+      const count = body?.chapterCount ?? DEFAULT_PLAN_COUNT
+      if (!Number.isInteger(count) || count < 1 || count > 200) {
+        writeJson(res, 400, { error: 'chapterCount 须为 1-200 的整数' })
+        return
+      }
+      try {
+        const next = project ?? createProject(outline)
+        const chapters: ChapterPlan[] = await planChapters(ctx, config, next, count, body?.volume, config.outputDir)
+        // 并发保护：长 LLM 调用期间磁盘可能已被其他请求更新（角色库/剧情线等），
+        // 保存前合并磁盘最新易变字段，避免旧快照覆盖新修改。
+        mergeVolatileFromDisk(config.outputDir, next)
+        next.chapters.push(...chapters)
+        next.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, next)
+        const response: PlanResponse = { chapters, volumes: next.volumes }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- generate
+  const generateRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.generate,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<{ chapterNo?: number; skipReview?: boolean; bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const rawNo = body?.chapterNo
+      if (!Number.isInteger(rawNo) || rawNo === undefined || rawNo < 1) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const no: number = rawNo
+      const chapter = project.chapters.find(c => c.no === no)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${no} 不在计划中` })
+        return
+      }
+      if (chapter.status === 'generating') {
+        writeJson(res, 409, { error: `章节 ${no} 正在生成中` })
+        return
+      }
+
+      // NDJSON stream.
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      chapter.status = 'generating'
+      chapter.error = undefined
+      chapter.generatingAt = new Date().toISOString()
+      // 并发保护：合并磁盘最新易变字段后保存，避免本请求覆盖并发修改（角色库/剧情线等）。
+      mergeVolatileFromDisk(config.outputDir, project)
+      saveProject(config.outputDir, project)
+
+      const send = (frame: JobFrame): void => {
+        res.write(JSON.stringify(frame) + '\n')
+      }
+
+      const liveSession = nextSessionId()
+      emitLive({ type: 'session_started', sessionId: liveSession, label: '正文生成', model: config.generateModel || config.model, at: new Date().toISOString(), context: { interactionId: liveSession, taskId: `ch-${no}` } })
+      emitLive({ type: 'phase_changed', sessionId: liveSession, phase: 'streaming', phaseMessage: '模型正在返回正文', at: new Date().toISOString() })
+
+      try {
+        send({ type: 'start', no, title: chapter.title })
+        let genChars = 0
+        for await (const step of generateChapterStream(ctx, config, project, config.outputDir, no)) {
+          if (step.frame === 'delta') {
+            send({ type: 'delta', text: step.text })
+            genChars += step.text.length
+            emitLive({ type: 'output_delta', sessionId: liveSession, content: step.text, totalChars: genChars, at: new Date().toISOString() })
+          } else if (step.frame === 'done') {
+            send({ type: 'done', no, file: step.file, chars: step.chars, title: chapter.title, warn: step.warn })
+          }
+        }
+        emitLive({ type: 'session_completed', sessionId: liveSession, totalChars: genChars, preview: '', at: new Date().toISOString(), phase: 'completed' })
+        // Auto pipeline: summary + facts（一次调用）-> review（unless skipped）。
+        try {
+          await summarizeAndExtractFacts(ctx, config, project, config.outputDir, no)
+        } catch (error) {
+          console.warn('[dsh-novel-forge] summary/facts failed:', (error as Error).message)
+        }
+        // 伏笔落地标记：正文中命中 planned 伏笔关键词 → 自动标为 planted（暗线管理页与正文同步）。
+        try {
+          const marked = markForeshadowPlanted(project, config.outputDir, no)
+          if (marked > 0) {
+            console.log(`[dsh-novel-forge] 第${no}章已埋伏笔 ${marked} 条`)
+          }
+        } catch (error) {
+          console.warn('[dsh-novel-forge] markForeshadowPlanted failed:', (error as Error).message)
+        }
+        if (!(body?.skipReview === true) && (config.autoReview ?? true)) {
+          const report = await reviewChapter(ctx, config, project, config.outputDir, no)
+          send({ type: 'review', no, report })
+        } else {
+          chapter.status = 'approved'
+          mergeVolatileFromDisk(config.outputDir, project)
+          saveProject(config.outputDir, project)
+        }
+        // 作者复盘：叙事结构检查（钩子兑现/结尾钩子/推进/连续性/趋势；不改变章节状态）。
+        if (config.autoAuthorReview ?? true) {
+          try {
+            const currentBody = readChapterFile(config.outputDir, chapter)
+            let prevTail = ''
+            if (no > 1) {
+              const prev = project.chapters.find(c => c.no === no - 1)
+              if (prev !== undefined) {
+                prevTail = (readChapterFile(config.outputDir, prev) ?? '').replace(/^#.*$/m, '').trim().slice(-600)
+              }
+            }
+            if (currentBody !== undefined) {
+              const review = await authorReviewChapter(ctx, config, project, no, currentBody, prevTail)
+              chapter.authorReview = review
+              // 复盘标记推进的剧情线 → 自动关联本章。
+              if (review.advancedLines !== undefined) {
+                autoLinkPlotlines(project, no, review.advancedLines)
+              }
+              mergeVolatileFromDisk(config.outputDir, project)
+              saveProject(config.outputDir, project)
+              send({ type: 'author-review', no, review })
+            }
+          } catch (error) {
+            console.warn('[dsh-novel-forge] author review failed:', (error as Error).message)
+          }
+        }
+        res.end()
+      } catch (error) {
+        chapter.status = 'error'
+        chapter.error = (error as Error).message
+        mergeVolatileFromDisk(config.outputDir, project)
+        saveProject(config.outputDir, project)
+        if (!res.writableEnded) {
+          send({ type: 'error', no, message: (error as Error).message })
+          res.end()
+        }
+      }
+    },
+  }
+
+  // --------------------------------------------------------------- review
+  const reviewRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.review,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<ReviewRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const no = body!.chapterNo!
+      try {
+        const report = await reviewChapter(ctx, config, project, outputDir, no)
+        writeJson(res, 200, { report })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // -------------------------------------------------------------- rewrite
+  const rewriteRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.rewrite,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<RewriteRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const no = body!.chapterNo!
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: JobFrame): void => { res.write(JSON.stringify(frame) + '\n') }
+      try {
+        for await (const step of rewriteChapterStream(ctx, config, project, config.outputDir, no, body?.instructions ?? '', body?.target)) {
+          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
+          else if (step.frame === 'drafted') send({ type: 'drafted', no, chars: step.chars, draft: step.draft })
+        }
+        // Draft mode: no auto re-review — the user reviews the diff and
+        // decides; re-run review after applying if wanted.
+        res.end()
+      } catch (error) {
+        if (!res.writableEnded) {
+          send({ type: 'error', no, message: (error as Error).message })
+          res.end()
+        }
+      }
+    },
+  }
+
+  // --------------------------------------------------------------- polish
+  const polishRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.polish,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<PolishRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const no = body!.chapterNo!
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: JobFrame): void => { res.write(JSON.stringify(frame) + '\n') }
+      try {
+        for await (const step of polishChapterStream(ctx, config, project, config.outputDir, no)) {
+          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
+          else if (step.frame === 'drafted') send({ type: 'drafted', no, chars: step.chars, draft: step.draft })
+        }
+        res.end()
+      } catch (error) {
+        if (!res.writableEnded) {
+          send({ type: 'error', no, message: (error as Error).message })
+          res.end()
+        }
+      }
+    },
+  }
+
+  // ---------------------------------------------------- draft apply/discard
+  /** 采纳待确认草稿：覆盖正文文件 + 状态回 written + 清空草稿。 */
+  const draftApplyRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.draftApply,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<DraftDecisionRequest>(req)
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === body!.chapterNo!)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${body!.chapterNo} 不在计划中` })
+        return
+      }
+      if (chapter.pendingDraft === undefined || chapter.pendingDraft === '') {
+        writeJson(res, 400, { error: `章节 ${chapter.no} 没有待确认的草稿` })
+        return
+      }
+      const draft = chapter.pendingDraft
+      const fileName = chapterFileName(chapter)
+      mkdirSync(config.outputDir, { recursive: true })
+      const targetPath = join(config.outputDir, fileName)
+      // 采纳前自动备份当前原稿为 .bak.md（每次应用都刷新为最新原稿），可随时回退。
+      if (existsSync(targetPath)) {
+        copyFileSync(targetPath, join(config.outputDir, `${fileName.replace(/\.md$/, '')}.bak.md`))
+      }
+      writeFileSync(targetPath, `# 第${chapter.no}章 ${chapter.title}\n\n${draft}\n`, 'utf8')
+      chapter.pendingDraft = undefined
+      chapter.chars = draft.length
+      chapter.file = fileName
+      // 携带审查报告则沿用结论定状态（修订后审查通过 → approved）；否则置 written 待审。
+      const carried = body?.report
+      if (carried !== undefined && typeof carried.score === 'number') {
+        chapter.review = carried
+        chapter.status = carried.passed ? 'approved' : 'rejected'
+      } else {
+        chapter.status = 'written'
+        chapter.review = undefined
+      }
+      chapter.error = undefined
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { ok: true, chars: draft.length, file: fileName, markdown: draft })
+    },
+  }
+
+  /** 放弃待确认草稿：保留原稿，仅清空草稿字段。 */
+  const draftDiscardRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.draftDiscard,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<DraftDecisionRequest>(req)
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === body!.chapterNo!)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${body!.chapterNo} 不在计划中` })
+        return
+      }
+      if (chapter.pendingDraft !== undefined) {
+        chapter.pendingDraft = undefined
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+      }
+      writeJson(res, 200, { ok: true })
+    },
+  }
+
+  // -------------------------------------------------------------- summary
+  const summaryRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.summary,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<SummaryRequest>(req)
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      try {
+        const summary = await summarizeChapter(ctx, config, project, config.outputDir, body!.chapterNo!)
+        writeJson(res, 200, { summary })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- foreshadow
+  const foreshadowRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.foreshadow,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<ForeshadowRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      try {
+        if (body?.suggest === true) {
+          // AI suggestion pass: create several foreshadows from the outline.
+          const created = await suggestForeshadows(ctx, config, project)
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          const response: ForeshadowResponse = { foreshadows: created }
+          writeJson(res, 200, response)
+          return
+        }
+        if (body?.id !== undefined) {
+          // Update an existing foreshadow.
+          const target = project.foreshadows.find(f => f.id === body.id)
+          if (target === undefined) {
+            writeJson(res, 404, { error: `伏笔 ${body.id} 不存在` })
+            return
+          }
+          if (body.description !== undefined) target.description = body.description
+          if (body.plantedChapter !== undefined) target.plantedChapter = body.plantedChapter
+          if (body.targetChapter !== undefined) target.targetChapter = body.targetChapter
+          if (body.status !== undefined) target.status = body.status
+          if (body.resolvedNote !== undefined) target.resolvedNote = body.resolvedNote
+        } else {
+          // Create one manually.
+          const description = body?.description?.trim()
+          if (description === undefined || description === '') {
+            writeJson(res, 400, { error: 'description 必填' })
+            return
+          }
+          project.foreshadows.push({
+            id: `fs-${Date.now().toString(36)}`,
+            description,
+            plantedChapter: body?.plantedChapter,
+            targetChapter: body?.targetChapter,
+            status: body?.status ?? 'planned',
+          })
+        }
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        const response: ForeshadowResponse = { foreshadows: project.foreshadows }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // -------------------------------------------------------------- export
+  const exportRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.exportBook,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config0 = getConfig()
+      const body = await readJsonBody<ExportRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const format = body?.format === 'md' ? 'md' : 'txt'
+      try {
+        const result = exportBook(config.outputDir, project, format)
+        const response: ExportResponse = { ...result }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // -------------------------------------------------------------- chapter
+  const chapterRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.chapter,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      const config = getConfig()
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const outputDir = resolveOutputDir(config, url.searchParams.get('bookId') ?? undefined)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const rawNo = Number(url.searchParams.get('no') ?? '0')
+      if (!Number.isInteger(rawNo) || rawNo < 1) {
+        writeJson(res, 400, { error: 'no 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === rawNo)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${rawNo} 不在计划中` })
+        return
+      }
+      const markdown = readChapterFile(outputDir, chapter)
+      if (markdown === undefined) {
+        writeJson(res, 404, { error: `章节 ${rawNo} 尚未生成` })
+        return
+      }
+      const response: ChapterResponse = { no: chapter.no, title: chapter.title, markdown }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ------------------------------------------------------ chapter check/save
+  /** 审查手动编辑的正文（不落盘，返回审稿报告）。 */
+  const chapterCheckRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.chapterCheck,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<ChapterTextRequest>(req)
+      const text = body?.text?.trim() ?? ''
+      if (text.length < 50) {
+        writeJson(res, 400, { error: '正文过短（<50 字），请先编辑内容' })
+        return
+      }
+      try {
+        // 携带上一轮报告 → 验证模式（逐条核对原意见解决情况 + 只挑新增 high）。
+        const report = await reviewChapterText(ctx, config, project, text, body?.previousReport)
+        writeJson(res, 200, { report })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  /** 保存手动编辑的正文（自动备份 .bak，状态回 written）。 */
+  const chapterSaveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.chapterSave,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<ChapterTextRequest>(req)
+      if (!Number.isInteger(body?.chapterNo)) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === body!.chapterNo!)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${body!.chapterNo} 不在计划中` })
+        return
+      }
+      const text = body?.text?.trim() ?? ''
+      if (text.length < 50) {
+        writeJson(res, 400, { error: '正文过短（<50 字），未保存' })
+        return
+      }
+      const fileName = chapterFileName(chapter)
+      mkdirSync(config.outputDir, { recursive: true })
+      const targetPath = join(config.outputDir, fileName)
+      if (existsSync(targetPath)) {
+        copyFileSync(targetPath, join(config.outputDir, `${fileName.replace(/\.md$/, '')}.bak.md`))
+      }
+      writeFileSync(targetPath, `# 第${chapter.no}章 ${chapter.title}\n\n${text}\n`, 'utf8')
+      chapter.status = 'written'
+      chapter.chars = text.length
+      chapter.file = fileName
+      chapter.pendingDraft = undefined
+      // 保存即审稿：携带工作区审查报告则沿用（不重复审）；否则自动正式审稿一次。
+      let report: ReviewReport | undefined
+      const carried = body?.report
+      if (carried !== undefined && typeof carried.score === 'number') {
+        report = carried
+        chapter.review = report
+        chapter.status = report.passed ? 'approved' : 'rejected'
+      } else {
+        report = await reviewChapter(ctx, config, project, config.outputDir, chapter.no)
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      const response: ChapterSaveResponse = { ok: true, chars: text.length, file: fileName, report }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ----------------------------------------------------------- assistant
+  const assistantRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.assistant,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<AssistantRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const message = body?.message?.trim()
+      if (message === undefined || message === '') {
+        writeJson(res, 400, { error: '消息不能为空' })
+        return
+      }
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: AssistantFrame): void => { res.write(JSON.stringify(frame) + '\n') }
+      try {
+        for await (const step of runAssistantTurn(ctx, config, project, outputDir, message)) {
+          if (step.frame === 'delta') send({ type: 'delta', text: step.text })
+          else if (step.frame === 'tool') send({ type: 'tool', name: step.name, status: step.status, detail: step.detail })
+          else if (step.frame === 'toolDelta') send({ type: 'toolDelta', name: step.name, text: step.text })
+          else if (step.frame === 'toolResult') send({ type: 'toolResult', name: step.name, text: step.text })
+        }
+        send({ type: 'done' })
+        res.end()
+      } catch (error) {
+        if (!res.writableEnded) {
+          send({ type: 'error', message: (error as Error).message })
+          res.end()
+        }
+      }
+    },
+  }
+
+  // -------------------------------------------------- assistant-history
+  const assistantHistoryRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.assistantHistory,
+    handler: (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      const config = getConfig()
+      const qurl = new URL(req.url ?? '/', 'http://localhost')
+      const outputDir = resolveOutputDir(config, qurl.searchParams.get('bookId') ?? undefined)
+      const response: AssistantHistoryResponse = { messages: loadAssistantHistory(outputDir) }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // --------------------------------------------------- assistant-clear
+  /** 清空助手对话记录。 */
+  const assistantClearRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.assistantClear,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<{ bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      clearAssistantHistory(outputDir)
+      writeJson(res, 200, { ok: true })
+    },
+  }
+
+  // --------------------------------------------------------------- assets
+  const assetsRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.assets,
+    handler: async (req, res) => {
+      // GET (read) and POST (patch) are both allowed — check methods first,
+      // then the loopback fence (guard() would 405 on POST, which is wrong).
+      if (req.method !== 'GET' && req.method !== 'POST') {
+        writeJson(res, 405, { error: 'method not allowed (expected GET or POST)' })
+        return
+      }
+      if (!isLoopbackRequest(req)) {
+        writeJson(res, 403, { error: 'forbidden: loopback-only' })
+        return
+      }
+      const config = getConfig()
+      let postBody: (AssetsPatch & { bookId?: string }) | undefined
+      if (req.method === 'POST') {
+        postBody = await readJsonBody<AssetsPatch & { bookId?: string }>(req)
+        if (postBody === undefined) {
+          writeJson(res, 400, { error: '无效的 JSON' })
+          return
+        }
+      }
+      const qurl = new URL(req.url ?? '/', 'http://localhost')
+      const queryBookId = qurl.searchParams.get('bookId') ?? undefined
+      const outputDir = resolveOutputDir(config, postBody?.bookId ?? queryBookId)
+      const project = loadProject(outputDir)
+      const projectAssets = ensureBuiltinAssets(project?.assets ?? emptyProjectAssets())
+      if (req.method === 'POST') {
+        const body = postBody
+        if (body === undefined) {
+          writeJson(res, 400, { error: '无效的 JSON' })
+          return
+        }
+        if (project === undefined) {
+          writeJson(res, 400, { error: '请先加载大纲创建项目' })
+          return
+        }
+        if (body.genre !== undefined) projectAssets.genre = body.genre
+        if (body.primaryProgression !== undefined) projectAssets.primaryProgression = body.primaryProgression
+        if (body.auxiliaryProgressions !== undefined) projectAssets.auxiliaryProgressions = body.auxiliaryProgressions
+        if (body.antiAiRules !== undefined) projectAssets.antiAiRules = body.antiAiRules
+        if (body.styleAssets !== undefined) projectAssets.styleAssets = body.styleAssets
+        projectAssets.updatedAt = new Date().toISOString()
+        project.assets = projectAssets
+        project.updatedAt = new Date().toISOString()
+        saveProject(outputDir, project)
+      }
+      const response: AssetsResponse = {
+        projectAssets,
+        genreLibrary: [...BUILTIN_GENRE_LIBRARY, ...globalGenreLibrary()],
+        antiAiLibrary: BUILTIN_ANTI_AI_RULES,
+        styleTemplates: BUILTIN_STYLE_TEMPLATES,
+        progressionLibrary: [...BUILTIN_PROGRESSION_MODES, ...globalProgressionLibrary()],
+        starterStyleProfiles: BUILTIN_STARTER_STYLE_PROFILES,
+        plotBeatLibrary: BUILTIN_PLOT_BEATS,
+      }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ----------------------------------------------------------- style-engine
+  const styleEngineRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.styleEngine,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = loadProject(config.outputDir)
+      const body = await readJsonBody<StyleEngineRequest>(req)
+      const sample = body?.sampleText?.trim()
+      if (sample === undefined || sample.length < 50) {
+        writeJson(res, 400, { error: '样本文本过短（<50 字符），请粘贴一段能代表目标风格的文字' })
+        return
+      }
+      try {
+        const rules = await extractStyleAsset(ctx, config, sample)
+        const name = body?.name?.trim() !== '' && body?.name !== undefined ? body.name : `风格资产 ${Date.now().toString(36)}`
+        const styleAsset = {
+          name: name.slice(0, 40),
+          ...rules,
+          sourceText: sample.slice(0, 3000),
+          createdAt: new Date().toISOString(),
+        }
+        if (project !== undefined) {
+          project.assets ??= emptyProjectAssets()
+          project.assets.styleAssets ??= []
+          project.assets.styleAssets.push(styleAsset)
+          project.assets.updatedAt = new Date().toISOString()
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+        }
+        writeJson(res, 200, { styleAsset })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ----------------------------------------------------------- style-formula
+  const styleFormulaRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.styleFormula,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = loadProject(config.outputDir)
+      const body = await readJsonBody<StyleEngineRequest & { depth?: string }>(req)
+      const sample = body?.sampleText?.trim()
+      if (sample === undefined || sample.length < 50) {
+        writeJson(res, 400, { error: '样本文本过短（<50 字符），请粘贴一段能代表目标风格的文字' })
+        return
+      }
+      const depth = (['basic', 'standard', 'deep'] as const).includes(body?.depth as never)
+        ? body!.depth! as 'basic' | 'standard' | 'deep'
+        : 'standard'
+      try {
+        const formula = await extractStyleFormula(ctx, config, sample, depth)
+        const key = `sf-${Date.now().toString(36)}`
+        const styleFormula = { key, ...formula, depth, createdAt: new Date().toISOString() }
+        if (project !== undefined) {
+          project.assets ??= emptyProjectAssets()
+          project.assets.styleFormulas ??= []
+          project.assets.styleFormulas.push(styleFormula)
+          project.assets.updatedAt = new Date().toISOString()
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+        }
+        writeJson(res, 200, { styleFormula })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ----------------------------------------------------------- style-detect
+  /** 正文实时 AI 味检测（本地确定性扫描，免 LLM）。 */
+  const styleDetectRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.styleDetect,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ text?: string }>(req)
+      const text = body?.text?.trim() ?? ''
+      if (text.length < 20) {
+        writeJson(res, 400, { error: '文本过短（<20 字符）' })
+        return
+      }
+      const scan = scanAiFlavor(text.slice(0, 20000))
+      writeJson(res, 200, { scan })
+    },
+  }
+
+  // --------------------------------------------------------- market-radar
+  /** 热门题材雷达：输入平台/题材/榜单文本 → 信号 + 生产底座 + 开书创意。 */
+  const marketRadarRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.marketRadar,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<MarketRadarRequest>(req)
+      try {
+        const result = await runMarketRadar(ctx, config, body ?? {})
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------- market-radar scan
+  /** 真实榜单扫榜：抓取公开榜单（容错），返回分组候选。 */
+  const marketRadarScanRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.marketRadarScan,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ platforms?: string[] }>(req)
+      try {
+        const result = await scanMarketRanking(body?.platforms)
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------- market-radar apply
+  /** 把雷达生产底座一键应用到某本书（写入项目资产/开书定盘，供后续规划与生成遵守）。 */
+  const marketRadarApplyRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.marketRadarApply,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ bookId?: string; foundation?: ProductionFoundation }>(req)
+      const pf = body?.foundation
+      if (pf === undefined) {
+        writeJson(res, 400, { error: '缺少 foundation' })
+        return
+      }
+      const config = getConfig()
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const genreBuiltin = BUILTIN_GENRE_LIBRARY.find(g => g.name === (pf.genre.existingId || pf.genre.name))
+      const genreNode: GenreNode = genreBuiltin !== undefined
+        ? { ...genreBuiltin }
+        : { name: pf.genre.name.slice(0, 40), description: pf.genre.description, template: pf.genre.template, children: [] }
+      const findMode = (m: { existingId?: string; name: string }): ProgressionMode | undefined => BUILTIN_PROGRESSION_MODES.find(x => x.name === (m.existingId || m.name))
+      const primary = findMode(pf.primaryStoryMode) ?? {
+        name: pf.primaryStoryMode.name.slice(0, 40),
+        driver: pf.primaryStoryMode.driver,
+        readerExpectation: pf.primaryStoryMode.readerExpectation,
+        payoffs: [],
+        risks: [],
+        primary: true,
+      }
+      const aux: ProgressionMode[] = []
+      if (pf.secondaryStoryMode !== undefined) {
+        const sec = findMode(pf.secondaryStoryMode) ?? {
+          name: pf.secondaryStoryMode.name.slice(0, 40),
+          driver: pf.secondaryStoryMode.driver,
+          readerExpectation: pf.secondaryStoryMode.readerExpectation,
+          payoffs: [],
+          risks: [],
+          primary: false,
+        }
+        aux.push(sec)
+      }
+      project.assets ??= emptyProjectAssets()
+      project.assets.genre = genreNode
+      project.assets.primaryProgression = primary
+      project.assets.auxiliaryProgressions = aux
+      project.bookContract = {
+        promise: pf.genre.description.slice(0, 120),
+        primaryModeName: pf.primaryStoryMode.name,
+        secondaryModeNames: pf.secondaryStoryMode !== undefined ? [pf.secondaryStoryMode.name] : [],
+        tone: pf.genre.template,
+        targetPlatform: undefined,
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(outputDir, project)
+      writeJson(res, 200, { ok: true, bookName: project.bookName })
+    },
+  }
+
+  // ------------------------------------------------- market-radar sync
+  /** 把雷达生产底座里的「新资产」同步进全局资源库（跨书复用；已有名字跳过）。 */
+  const marketRadarSyncRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.marketRadarSync,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ foundation?: ProductionFoundation }>(req)
+      const pf = body?.foundation
+      if (pf === undefined) {
+        writeJson(res, 400, { error: '缺少 foundation' })
+        return
+      }
+      const synced = { genre: false, primaryMode: false, secondaryMode: false }
+      if (pf.genre.existingId === undefined && pf.genre.name !== '') {
+        synced.genre = addGlobalGenre({ name: pf.genre.name.slice(0, 40), description: pf.genre.description, template: pf.genre.template, children: [] })
+      }
+      if (pf.primaryStoryMode.existingId === undefined && pf.primaryStoryMode.name !== '') {
+        synced.primaryMode = addGlobalMode({ name: pf.primaryStoryMode.name.slice(0, 40), driver: pf.primaryStoryMode.driver, readerExpectation: pf.primaryStoryMode.readerExpectation, payoffs: [], risks: [], primary: true })
+      }
+      if (pf.secondaryStoryMode !== undefined && pf.secondaryStoryMode !== null && pf.secondaryStoryMode.existingId === undefined && pf.secondaryStoryMode.name !== '') {
+        synced.secondaryMode = addGlobalMode({ name: pf.secondaryStoryMode.name.slice(0, 40), driver: pf.secondaryStoryMode.driver, readerExpectation: pf.secondaryStoryMode.readerExpectation, payoffs: [], risks: [], primary: false })
+      }
+      writeJson(res, 200, { ok: true, synced })
+    },
+  }
+
+  // ------------------------------------------------- market-radar brief
+  /** 开书创意简报：用选中的市场信号 + 影响模式生成。 */
+  const marketRadarBriefRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.marketRadarBrief,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<MarketRadarBriefRequest>(req)
+      if (body === undefined || body.influenceMode === undefined) {
+        writeJson(res, 400, { error: '缺少 influenceMode' })
+        return
+      }
+      try {
+        const creativeBrief = await runMarketCreativeBrief(ctx, config, body)
+        writeJson(res, 200, { creativeBrief })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- knowledge
+  /** 书内知识库：GET 读取 / POST 增删改（按书路由）。 */
+  const knowledgeRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.knowledge,
+    handler: async (req, res) => {
+      if (req.method === 'POST') {
+        if (!guard(req, res, 'POST')) return
+      } else {
+        if (!guard(req, res, 'GET')) return
+      }
+      const config = getConfig()
+      const qurl = new URL(req.url ?? '/', 'http://localhost')
+      const body = req.method === 'POST' ? await readJsonBody<KnowledgeRequest & { bookId?: string }>(req) : undefined
+      const outputDir = resolveOutputDir(config, body?.bookId ?? qurl.searchParams.get('bookId') ?? undefined)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      project.knowledgeDocs ??= []
+      if (req.method === 'POST' && body !== undefined) {
+        if (body.action === 'add' && body.doc !== undefined) {
+          project.knowledgeDocs.push({ id: body.doc.id ?? `kd-${Date.now().toString(36)}`, title: body.doc.title, content: body.doc.content, updatedAt: new Date().toISOString() })
+        } else if (body.action === 'remove' && body.id !== undefined) {
+          project.knowledgeDocs = project.knowledgeDocs.filter(d => d.id !== body.id)
+        } else if (body.action === 'replace' && body.doc !== undefined) {
+          project.knowledgeDocs = project.knowledgeDocs.map(d => d.id === body.doc!.id ? { ...d, title: body.doc!.title, content: body.doc!.content, updatedAt: new Date().toISOString() } : d)
+        }
+        project.updatedAt = new Date().toISOString()
+        saveProject(outputDir, project)
+      }
+      writeJson(res, 200, { docs: project.knowledgeDocs })
+    },
+  }
+
+  // ---------------------------------------------------------- book-analysis
+  /** 书分析/拆书：输入文本 → 卖点/结构/可借鉴点/风险。 */
+  const bookAnalysisRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bookAnalysis,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<BookAnalysisRequest>(req)
+      if (body === undefined || (body.text ?? '').trim().length < 50) {
+        writeJson(res, 400, { error: '文本过短（<50 字符）' })
+        return
+      }
+      try {
+        const result = await runBookAnalysis(ctx, config, body)
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- idea-inspiration
+  /** 创意灵感：一句话/题材 → 多方向开书灵感。 */
+  const ideaInspirationRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.ideaInspiration,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<IdeaInspirationRequest>(req)
+      if (body === undefined || (body.idea ?? '').trim().length < 2) {
+        writeJson(res, 400, { error: '请填写你的方向/一句话想法' })
+        return
+      }
+      try {
+        const result = await runIdeaInspiration(ctx, config, body)
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------- idea-inspiration/market
+  /** 雷达→灵感：基于市场信号/生产底座/创意简报生成开书灵感。 */
+  const marketIdeaInspirationRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.ideaInspirationMarket,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<{ signals?: import('./protocol.ts').MarketRadarSignal[]; foundation?: import('./protocol.ts').ProductionFoundation; brief?: import('./protocol.ts').MarketCreativeBrief; count?: number }>(req)
+      if (body === undefined) {
+        writeJson(res, 400, { error: '缺少市场分析参数' })
+        return
+      }
+      try {
+        const result = await runMarketIdeaInspiration(ctx, config, body)
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- director
+  /** 自动导演编排建议：基于全书上下文。 */
+  const directorRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.director,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<DirectorRequest & { bookId?: string }>(req)
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      try {
+        const result = await runDirectorAdvice(ctx, config, project, body ?? {})
+        writeJson(res, 200, { result })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- director/todos
+  /** 自动导演「采纳」出的书内待办：GET 读取 / POST 增删勾选（按书路由）。 */
+  const directorTodosRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.directorTodos,
+    handler: async (req, res) => {
+      type DirectorTodosReq = { op?: 'add' | 'toggle' | 'remove'; text?: string; source?: DirectorTodo['source']; id?: string; bookId?: string }
+      let body: DirectorTodosReq | undefined
+      if (req.method === 'POST') {
+        if (!guard(req, res, 'POST')) return
+        body = await readJsonBody<DirectorTodosReq>(req)
+      } else {
+        if (!guard(req, res, 'GET')) return
+      }
+      const config = getConfig()
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      project.todos ??= []
+      if (req.method === 'POST' && body !== undefined) {
+        if (body.op === 'add' && (body.text ?? '').trim() !== '') {
+          project.todos.unshift({ id: `td-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`, text: body.text!.trim(), source: body.source ?? 'fix', done: false, createdAt: new Date().toISOString() })
+        } else if (body.op === 'toggle' && body.id !== undefined) {
+          project.todos = project.todos.map(t => t.id === body.id ? { ...t, done: !t.done } : t)
+        } else if (body.op === 'remove' && body.id !== undefined) {
+          project.todos = project.todos.filter(t => t.id !== body.id)
+        }
+        project.updatedAt = new Date().toISOString()
+        saveProject(outputDir, project)
+      }
+      writeJson(res, 200, { todos: project.todos })
+    },
+  }
+
+  // ------------------------------------------------------------- llm-live
+  /** AI 创作实况：订阅 LLM 实时事件流（NDJSON；订阅时先重放最近缓冲）。 */
+  const llmLiveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmLive,
+    handler: async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { error: 'GET only' })
+        return
+      }
+      if (!isLoopbackRequest(req)) {
+        writeJson(res, 403, { error: 'forbidden: loopback-only' })
+        return
+      }
+      res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const unsubscribe = subscribeLiveFeed((frame) => {
+        try { res.write('data: ' + JSON.stringify(frame) + '\n\n') } catch { /* client closed */ }
+      })
+      const hb = setInterval(() => { try { res.write(': ping\n\n') } catch { /* closed */ } }, 25000)
+      // 关键：让 handler 一直挂起，直到客户端关闭，避免 WebRoute 框架在 handler 返回后关闭响应。
+      await new Promise<void>((resolve) => {
+        res.on('close', () => {
+          clearInterval(hb)
+          unsubscribe()
+          resolve()
+        })
+      })
+    },
+  }
+
+  // ------------------------------------------------------------- bookshelf
+  const bookshelfRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bookshelf,
+    handler: async (req, res) => {
+      // GET = snapshot; POST = create book.
+      if (req.method === 'GET') {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        // 书架为空时，把 settings 默认输出目录里已有的项目播种为第一本书。
+        seedBookshelfFromOutputDir(getConfig().outputDir)
+        const snapshot: BookshelfSnapshot = bookshelfSnapshot(loadBookshelf())
+        writeJson(res, 200, snapshot)
+        return
+      }
+      if (req.method === 'POST') {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        const body = await readJsonBody<BookCreateRequest>(req)
+        const bookName = body?.bookName?.trim()
+        if (bookName === undefined || bookName === '') {
+          writeJson(res, 400, { error: 'bookName 不能为空' })
+          return
+        }
+        const outputDir = body?.outputDir?.trim() !== '' && body?.outputDir !== undefined
+          ? body.outputDir
+          : defaultOutputDirFor(bookName)
+        const book = createBook(bookName, outputDir)
+        // 开书向导：创建时带大纲 → 立即建立项目（书名以大纲首行为准）。
+        const outline = body?.outline?.trim()
+        if (outline !== undefined && outline.length >= 50) {
+          const project = createProject(outline)
+          saveProject(outputDir, project)
+          renameBook(book.id, project.bookName)
+        }
+        writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
+        return
+      }
+      writeJson(res, 405, { error: 'method not allowed (expected GET or POST)' })
+    },
+  }
+
+  // --------------------------------------------------------------- reset
+  /** 重置项目：清空设定/卷/章节计划/正文/伏笔/资产/事实库（可携带新大纲）。 */
+  const resetRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.reset,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = loadProject(config.outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目，无需重置' })
+        return
+      }
+      const body = await readJsonBody<ResetRequest>(req)
+      const outline = body?.outline?.trim()
+      if (outline !== undefined && outline.length >= 50) {
+        project.outline = outline
+        project.bookName = createProject(outline).bookName
+      }
+      project.bible = undefined
+      project.volumes = undefined
+      project.chapters = []
+      project.foreshadows = []
+      project.assets = emptyProjectAssets()
+      project.facts = []
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { ok: true, bookName: project.bookName })
+    },
+  }
+
+  // --------------------------------------------------- bookshelf activate
+  const bookshelfActivateRoute: WebRoute = {
+    kind: 'exact',
+    path: '/api/dsh-novel-forge/bookshelf/activate',
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BookActivateRequest>(req)
+      if (body?.id === undefined || body.id === '') {
+        writeJson(res, 400, { error: 'id 不能为空' })
+        return
+      }
+      const book = activateBook(body.id)
+      if (book === undefined) {
+        writeJson(res, 404, { error: `书 ${body.id} 不存在` })
+        return
+      }
+      writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
+    },
+  }
+
+  // ---------------------------------------------------- bookshelf remove
+  const bookshelfRemoveRoute: WebRoute = {
+    kind: 'exact',
+    path: '/api/dsh-novel-forge/bookshelf/remove',
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BookRemoveRequest>(req)
+      if (body?.id === undefined || body.id === '') {
+        writeJson(res, 400, { error: 'id 不能为空' })
+        return
+      }
+      const removed = removeBook(body.id)
+      if (!removed) {
+        writeJson(res, 404, { error: `书 ${body.id} 不存在` })
+        return
+      }
+      writeJson(res, 200, bookshelfSnapshot(loadBookshelf()))
+    },
+  }
+
+  // ------------------------------------------- bookshelf import-dir
+  /** 导入已有项目目录（Mode A）：校验 novel-project.json，登记/激活书架。 */
+  const bookshelfImportDirRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bookshelfImportDir,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BookImportDirRequest>(req)
+      const outputDir = body?.outputDir?.trim()
+      if (outputDir === undefined || outputDir === '') {
+        writeJson(res, 400, { error: 'outputDir 不能为空' })
+        return
+      }
+      try {
+        const { book, existed } = importDir(outputDir)
+        writeJson(res, 200, { book, existed })
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  // ------------------------------------------- bookshelf import-text
+  /** 导入 txt/md 全本（Mode B）：拆章落盘建项目，登记书架。支持浏览器上传（text+fileName）与服务器本地文件（filePath）两种模式。 */
+  const bookshelfImportTextRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bookshelfImportText,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BookImportTextRequest>(req)
+      try {
+        // 模式二：浏览器上传全文内容
+        if (body?.text !== undefined && body.text.length > 0) {
+          const bookName = (body.fileName ?? '').replace(/\.[^.]+$/, '').trim().slice(0, 40) || '导入小说'
+          const outDir = body?.outputDir?.trim() !== undefined && body.outputDir.trim() !== ''
+            ? body.outputDir.trim()
+            : defaultOutputDirFor(bookName)
+          const result = importBookTextFromText(body.text, outDir, bookName)
+          const { book } = importDir(outDir)
+          writeJson(res, 200, { ...result, book })
+          return
+        }
+        // 模式一：服务器本地文件
+        const filePath = body?.filePath?.trim()
+        if (filePath === undefined || filePath === '') {
+          writeJson(res, 400, { error: 'filePath 不能为空（或请上传文件内容）' })
+          return
+        }
+        if (!existsSync(filePath)) {
+          writeJson(res, 400, { error: `文件不存在：${filePath}` })
+          return
+        }
+        const bookName = basename(filePath, extname(filePath)).slice(0, 40) || '导入小说'
+        const outDir = body?.outputDir?.trim() !== undefined && body.outputDir.trim() !== ''
+          ? body.outputDir.trim()
+          : defaultOutputDirFor(bookName)
+        const result = importBookText(filePath, outDir)
+        const { book } = importDir(outDir)
+        writeJson(res, 200, { ...result, book })
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  // --------------------------------------- bookshelf import-text preview
+  /** 上传全文做拆章预览（不落盘、不登记书架）。 */
+  const bookshelfImportTextPreviewRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.bookshelfImportTextPreview,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<BookImportTextPreviewRequest>(req)
+      if (body?.text === undefined || body.text.length === 0) {
+        writeJson(res, 400, { error: 'text 不能为空' })
+        return
+      }
+      try {
+        const bookName = (body.fileName ?? '').replace(/\.[^.]+$/, '').trim().slice(0, 40) || '导入小说'
+        const preview = previewBookText(body.text)
+        writeJson(res, 200, { bookName, ...preview })
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------------- audit
+  /** 全书一致性质检。 */
+  const auditRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.audit,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ bookId?: string }>(req)
+      const config0 = getConfig()
+      const outputDir = resolveOutputDir(config0, body?.bookId)
+      const config = { ...config0, outputDir }
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const startedAt = new Date().toISOString()
+      auditState = { status: 'running', startedAt, totalBatches: 0, completedBatches: 0 }
+      try {
+        const issues = await auditBook(ctx, config, project, config.outputDir, (completed, total) => {
+          auditState.totalBatches = total
+          auditState.completedBatches = completed
+        })
+        const auditedChapters = project.chapters.filter(c => c.status !== 'pending' && c.status !== 'generating').length
+        auditState = {
+          status: 'done',
+          startedAt,
+          finishedAt: new Date().toISOString(),
+          totalBatches: auditState.totalBatches,
+          completedBatches: auditState.totalBatches,
+          auditedChapters,
+          issuesCount: issues.length,
+          issues,
+        }
+        const response: AuditResponse = {
+          issues,
+          auditedChapters,
+          auditedAt: auditState.finishedAt!,
+          model: config.auditModel || config.model,
+        }
+        writeJson(res, 200, response)
+      } catch (error) {
+        auditState = {
+          ...auditState,
+          status: 'error',
+          finishedAt: new Date().toISOString(),
+          error: (error as Error).message,
+        }
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ----------------------------------------------------- characters refresh
+  /** 角色卡刷新（出场统计精确化 + LLM 聚合状态）。 */
+  const charactersRefreshRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.charactersRefresh,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      try {
+        const cards = await refreshCharacters(ctx, config, project, config.outputDir)
+        // 存档：人物志聚合结果落盘，下次打开直接显示，无需重新计算。
+        project.roleStatus = cards
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ------------------------------------------------------- facts backfill
+  /** 事实库回填：对历史已生成章节批量抽取事实。 */
+  const factsBackfillRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.factsBackfill,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      try {
+        const filled = await backfillFacts(ctx, config, project, config.outputDir)
+        writeJson(res, 200, { ok: true, filled })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- bible patch
+  /** 道藏局部修补（世界观规则/红线/风格）。 */
+  const biblePatchRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.biblePatch,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      if (project.bible === undefined) {
+        writeJson(res, 400, { error: '尚未生成道藏，请先生成' })
+        return
+      }
+      const body = await readJsonBody<BiblePatchRequest>(req)
+      if (Array.isArray(body?.worldRules)) project.bible.worldRules = body.worldRules.filter(r => r.trim() !== '')
+      if (Array.isArray(body?.redLines)) project.bible.redLines = body.redLines.filter(r => r.trim() !== '')
+      if (Array.isArray(body?.style)) project.bible.style = body.style.filter(r => r.trim() !== '')
+      if (Array.isArray(body?.characters)) {
+        project.bible.characters = body.characters
+          .filter(c => c !== undefined && c !== null && typeof c.name === 'string' && c.name.trim() !== '')
+          .map(c => ({
+            name: c.name.trim(),
+            role: (['protagonist', 'supporting', 'antagonist', 'other'] as const).includes(c.role as never)
+              ? c.role as StoryBible['characters'][number]['role']
+              : 'other',
+            traits: Array.isArray(c.traits) ? c.traits.filter((t): t is string => typeof t === 'string' && t.trim() !== '') : [],
+            goals: typeof c.goals === 'string' ? c.goals : '',
+            relations: typeof c.relations === 'string' ? c.relations : '',
+            knowledge: Array.isArray(c.knowledge)
+              ? c.knowledge.filter((k): k is string => typeof k === 'string' && k.trim() !== '')
+              : undefined,
+          }))
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { bible: project.bible })
+    },
+  }
+
+  // ---------------------------------------------------------------- blurb
+  /** 小说简介：AI 生成/补全，或手动保存。 */
+  const blurbRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.blurb,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<BlurbRequest>(req)
+      try {
+        if (body?.action === 'save') {
+          const text = body.text?.trim() ?? ''
+          project.blurb = text
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { blurb: text })
+          return
+        }
+        const partial = body?.partial?.trim() ?? ''
+        const blurb = await generateBlurb(ctx, config, project, partial)
+        project.blurb = blurb
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { blurb })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------------- cover
+  /** 封面：GET 读取（dataUrl）；POST 上传（base64）或移除。 */
+  const coverRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.cover,
+    handler: async (req, res) => {
+      const config = getConfig()
+      if (req.method === 'GET') {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        // 书架页按书读取：?dir=<输出目录>；省略时用当前激活书目录。
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const dirParam = url.searchParams.get('dir')
+        const targetDir = dirParam !== null && dirParam !== '' ? dirParam : config.outputDir
+        const project = loadProject(targetDir)
+        const coverPath = project?.coverPath
+        if (coverPath === undefined || coverPath === '') {
+          writeJson(res, 200, { dataUrl: null } satisfies CoverResponse)
+          return
+        }
+        const file = join(targetDir, coverPath)
+        if (!existsSync(file)) {
+          writeJson(res, 200, { dataUrl: null } satisfies CoverResponse)
+          return
+        }
+        const mime = coverPath.toLowerCase().endsWith('.png') ? 'image/png'
+          : coverPath.toLowerCase().endsWith('.jpg') || coverPath.toLowerCase().endsWith('.jpeg') ? 'image/jpeg'
+            : coverPath.toLowerCase().endsWith('.webp') ? 'image/webp'
+              : 'image/png'
+        const dataUrl = `data:${mime};base64,${readFileSync(file).toString('base64')}`
+        writeJson(res, 200, { dataUrl } satisfies CoverResponse)
+        return
+      }
+      if (req.method === 'POST') {
+        if (!guard(req, res, 'POST')) return
+        const project = requireProject(res)
+        if (project === undefined) return
+        const body = await readJsonBody<CoverRequest>(req)
+        try {
+          if (body?.action === 'remove') {
+            if (project.coverPath !== undefined && project.coverPath !== '') {
+              const oldFile = join(config.outputDir, project.coverPath)
+              if (existsSync(oldFile)) rmSync(oldFile, { force: true })
+            }
+            project.coverPath = undefined
+            project.updatedAt = new Date().toISOString()
+            saveProject(config.outputDir, project)
+            writeJson(res, 200, { ok: true, coverPath: null })
+            return
+          }
+          const dataUrl = body?.dataUrl ?? ''
+          const match = /^data:(image\/(?:png|jpeg|jpg|webp));base64,(.+)$/s.exec(dataUrl)
+          if (match === null) {
+            writeJson(res, 400, { error: '封面须为 PNG/JPEG/WebP 的 base64 data URL' })
+            return
+          }
+          const mime = match[1]!
+          const ext = mime === 'image/png' ? 'png' : mime === 'image/webp' ? 'webp' : 'jpg'
+          const fileName = `cover.${ext}`
+          const targetPath = join(config.outputDir, fileName)
+          const oldPath = project.coverPath
+          mkdirSync(config.outputDir, { recursive: true })
+          writeFileSync(targetPath, Buffer.from(match[2]!, 'base64'))
+          if (oldPath !== undefined && oldPath !== '' && oldPath !== fileName) {
+            const oldFile = join(config.outputDir, oldPath)
+            if (existsSync(oldFile)) rmSync(oldFile, { force: true })
+          }
+          project.coverPath = fileName
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { ok: true, coverPath: fileName })
+        } catch (error) {
+          writeJson(res, 500, { error: (error as Error).message })
+        }
+        return
+      }
+      writeJson(res, 405, { error: 'method not allowed (expected GET or POST)' })
+    },
+  }
+
+  // ---------------------------------------------------------------- world
+  /** 大世界：AI 提炼或手动保存（境界体系/区域/势力）。 */
+  const worldRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.world,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<WorldRequest>(req)
+      try {
+        if (body?.action === 'save' && body.world !== undefined) {
+          project.world = {
+            realms: Array.isArray(body.world.realms) ? body.world.realms : [],
+            regions: Array.isArray(body.world.regions) ? body.world.regions : [],
+            factions: Array.isArray(body.world.factions) ? body.world.factions : [],
+          }
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { world: project.world })
+          return
+        }
+        const world = await extractWorld(ctx, config, project)
+        project.world = world
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { world })
+      } catch (error) {
+        writeJson(res, 500, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // --------------------------------------------------------------- rename
+  /** 重命名当前书：同步项目 bookName 与书架条目。 */
+  const renameRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.rename,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<RenameRequest>(req)
+      const bookName = body?.bookName?.trim()
+      if (bookName === undefined || bookName === '') {
+        writeJson(res, 400, { error: '书名不能为空' })
+        return
+      }
+      project.bookName = bookName.slice(0, 60)
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      const store = loadBookshelf()
+      if (store.activeBookId !== null) renameBook(store.activeBookId, project.bookName)
+      writeJson(res, 200, { bookName: project.bookName })
+    },
+  }
+
+  // ------------------------------------------------------------- plotlines
+  /** 剧情线管理：增删改 + 关联章节（主线/支线/人物线/悬念线）。 */
+  const plotlinesRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.plotlines,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<PlotlinesRequest>(req)
+      if (project.plotlines === undefined) project.plotlines = []
+      const op = body?.op
+      if (op === 'add' && body?.line !== undefined) {
+        const line = body.line
+        project.plotlines.push({
+          id: line.id !== '' ? line.id : `pl-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+          name: line.name.slice(0, 40),
+          kind: line.kind,
+          goal: line.goal.slice(0, 300),
+          progress: line.progress.slice(0, 300),
+          status: line.status,
+          chapters: Array.isArray(line.chapters) ? line.chapters.filter((n): n is number => typeof n === 'number') : [],
+          createdAt: line.createdAt !== '' ? line.createdAt : new Date().toISOString(),
+        })
+      } else if (op === 'update' && body?.line !== undefined && body.line.id !== '') {
+        const idx = project.plotlines.findIndex(l => l.id === body.line!.id)
+        if (idx !== -1) {
+          const line = body.line
+          project.plotlines[idx] = {
+            ...project.plotlines[idx]!,
+            name: line.name.slice(0, 40),
+            kind: line.kind,
+            goal: line.goal.slice(0, 300),
+            progress: line.progress.slice(0, 300),
+            status: line.status,
+          }
+        }
+      } else if (op === 'remove' && body?.id !== undefined) {
+        project.plotlines = project.plotlines.filter(l => l.id !== body.id)
+      } else if (op === 'link' && body?.id !== undefined && typeof body.chapterNo === 'number' && body.chapterNo > 0) {
+        const line = project.plotlines.find(l => l.id === body.id)
+        if (line !== undefined && !line.chapters.includes(body.chapterNo)) {
+          line.chapters.push(body.chapterNo)
+          if (line.status === 'active' && line.progress === '') {
+            line.progress = `推进至第 ${body.chapterNo} 章`
+          }
+        }
+      } else if (op === 'suggest') {
+        try {
+          const suggestions = await suggestPlotlines(ctx, config, project)
+          writeJson(res, 200, { plotlines: project.plotlines, suggestions } satisfies PlotlinesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `AI 建议失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'refresh' && body?.id !== undefined) {
+        const line = project.plotlines.find(l => l.id === body.id)
+        if (line === undefined) {
+          writeJson(res, 404, { error: '剧情线不存在' })
+          return
+        }
+        try {
+          const progress = await refreshPlotlineProgress(ctx, config, project, line)
+          line.progress = progress
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { plotlines: project.plotlines } satisfies PlotlinesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `刷新进度失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'health') {
+        try {
+          const health = await analyzePlotlineHealth(ctx, config, project)
+          writeJson(res, 200, { plotlines: project.plotlines, health } satisfies PlotlinesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `健康检查失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'plan') {
+        try {
+          const health = await analyzePlotlineHealth(ctx, config, project)
+          const plan = await designPlotlinePlan(ctx, config, project, health)
+          writeJson(res, 200, { plotlines: project.plotlines, health, plan } satisfies PlotlinesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `剧情方案生成失败：${(error as Error).message}` })
+          return
+        }
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      const response: PlotlinesResponse = { plotlines: project.plotlines }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // --------------------------------------------------------- sensitive
+  /** 敏感词检查：指定章节 / 任意文本 / 全书已写章节。 */
+  const sensitiveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.sensitiveCheck,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<SensitiveCheckRequest>(req)
+      const hits: SensitiveHit[] = []
+      let scanned = 0
+      if (body?.text !== undefined) {
+        for (const hit of checkSensitiveText(body.text)) {
+          hits.push({ chapterNo: 0, word: hit.word, category: hit.category, count: hit.count })
+        }
+      } else if (typeof body?.chapterNo === 'number') {
+        const chapter = project.chapters.find(c => c.no === body.chapterNo)
+        if (chapter !== undefined) {
+          const text = readChapterFile(config.outputDir, chapter)
+          if (text !== undefined) {
+            scanned = 1
+            for (const hit of checkSensitiveText(text)) {
+              hits.push({ chapterNo: chapter.no, word: hit.word, category: hit.category, count: hit.count })
+            }
+          }
+        }
+      } else if (body?.all === true) {
+        for (const chapter of project.chapters) {
+          if (chapter.status === 'pending' || chapter.status === 'generating') continue
+          const text = readChapterFile(config.outputDir, chapter)
+          if (text === undefined) continue
+          scanned++
+          for (const hit of checkSensitiveText(text)) {
+            hits.push({ chapterNo: chapter.no, word: hit.word, category: hit.category, count: hit.count })
+          }
+        }
+      } else {
+        writeJson(res, 400, { error: '请提供 chapterNo / text / all 之一' })
+        return
+      }
+      const response: SensitiveCheckResponse = { hits, scannedChapters: scanned }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ---------------------------------------------------------------- roles
+  /** 角色库：AI 提炼 / 采纳 / 更新 / 删除。 */
+  const rolesRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.roles,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<RolesRequest>(req)
+      if (project.roles === undefined) project.roles = []
+      const op = body?.op
+      if (op === 'extract') {
+        try {
+          const candidates = await extractRoles(ctx, config, project)
+          writeJson(res, 200, { roles: project.roles, candidates } satisfies RolesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `角色提炼失败：${(error as Error).message}` })
+          return
+        }
+      } else if ((op === 'adopt' || op === 'update') && body?.role !== undefined) {
+        const r = body.role
+        const idx = project.roles.findIndex(x => x.name === r.name)
+        if (idx === -1) project.roles.push(r)
+        else project.roles[idx] = r
+      } else if (op === 'remove' && body?.name !== undefined) {
+        project.roles = project.roles.filter(x => x.name !== body.name)
+      } else {
+        writeJson(res, 400, { error: '未知的 roles op' })
+        return
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      const response: RolesResponse = { roles: project.roles }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ------------------------------------------------------- chapter reset
+  /** 章节复位：generating 卡死 → pending（可重新生成）。 */
+  const chapterResetRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.chapterReset,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<{ chapterNo?: number }>(req)
+      const no = body?.chapterNo
+      if (!Number.isInteger(no) || no === undefined || no < 1) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === no)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${no} 不在计划中` })
+        return
+      }
+      chapter.status = 'pending'
+      chapter.error = undefined
+      chapter.generatingAt = undefined
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { ok: true, no })
+    },
+  }
+
+  // ------------------------------------------------------ chapter approve
+  /** 章节直接通过：作者行使最终决定权（不重审，保留审稿记录）。 */
+  const chapterApproveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.chapterApprove,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<{ chapterNo?: number }>(req)
+      const no = body?.chapterNo
+      if (!Number.isInteger(no) || no === undefined || no < 1) {
+        writeJson(res, 400, { error: 'chapterNo 须为正整数' })
+        return
+      }
+      const chapter = project.chapters.find(c => c.no === no)
+      if (chapter === undefined) {
+        writeJson(res, 404, { error: `章节 ${no} 不在计划中` })
+        return
+      }
+      chapter.status = 'approved'
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      writeJson(res, 200, { ok: true, no })
+    },
+  }
+
+  // ------------------------------------------------------ author review backfill
+  /** 作者复盘补跑：对已写章节补齐 authorReview（body.chapterNo=单章 JSON，缺省=全书 NDJSON 流）。 */
+  const reviewBackfillRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.reviewBackfill,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<{ chapterNo?: number }>(req)
+
+      /** 对一章执行作者复盘（读取已落盘正文，不改变章节状态/正文）。 */
+      const runOne = async (chapter: ChapterPlan): Promise<AuthorReview> => {
+        const currentBody = readChapterFile(config.outputDir, chapter)
+        if (currentBody === undefined) throw new Error(`章节 ${chapter.no} 的正文文件不存在`)
+        let prevTail = ''
+        if (chapter.no > 1) {
+          const prev = project.chapters.find(c => c.no === chapter.no - 1)
+          if (prev !== undefined) {
+            prevTail = (readChapterFile(config.outputDir, prev) ?? '').replace(/^#.*$/m, '').trim().slice(-600)
+          }
+        }
+        return authorReviewChapter(ctx, config, project, chapter.no, currentBody, prevTail)
+      }
+
+      // 单章：JSON 响应。
+      if (typeof body?.chapterNo === 'number' && body.chapterNo > 0) {
+        const chapter = project.chapters.find(c => c.no === body.chapterNo)
+        if (chapter === undefined) {
+          writeJson(res, 404, { error: `章节 ${body.chapterNo} 不在计划中` })
+          return
+        }
+        if (chapter.status === 'pending') {
+          writeJson(res, 400, { error: '该章尚未生成正文，无法复盘' })
+          return
+        }
+        try {
+          const review = await runOne(chapter)
+          chapter.authorReview = review
+          if (review.advancedLines !== undefined) {
+            autoLinkPlotlines(project, chapter.no, review.advancedLines)
+          }
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { no: chapter.no, review } satisfies { no: number; review: AuthorReview })
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: (error as Error).message })
+          return
+        }
+      }
+
+      // 全书：NDJSON 流式补跑缺失复盘的已写章节。
+      const missing = project.chapters.filter(c => c.status !== 'pending' && c.status !== 'generating' && c.status !== 'error' && c.authorReview === undefined)
+      if (missing.length === 0) {
+        writeJson(res, 200, { count: 0 })
+        return
+      }
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: JobFrame): void => {
+        res.write(JSON.stringify(frame) + '\n')
+      }
+      let done = 0
+      for (const chapter of missing) {
+        try {
+          const review = await runOne(chapter)
+          chapter.authorReview = review
+          if (review.advancedLines !== undefined) {
+            autoLinkPlotlines(project, chapter.no, review.advancedLines)
+          }
+          done++
+          saveProject(config.outputDir, project)
+          send({ type: 'author-review', no: chapter.no, review })
+        } catch (error) {
+          console.warn(`[dsh-novel-forge] author backfill ch.${chapter.no} failed:`, (error as Error).message)
+        }
+      }
+      project.updatedAt = new Date().toISOString()
+      saveProject(config.outputDir, project)
+      send({ type: 'author-backfill-done', count: done })
+      res.end()
+    },
+  }
+
+  // --------------------------------------------------------------- config
+  const configRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.config,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<ConfigPatch>(req)
+      if (body === undefined) {
+        writeJson(res, 400, { error: '无效的配置 JSON' })
+        return
+      }
+      try {
+        const next = await patchConfig(body)
+        writeJson(res, 200, { config: next })
+      } catch (error) {
+        writeJson(res, 400, { error: (error as Error).message })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- open-folder
+  const openFolderRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.openFolder,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const dir = config.outputDir
+      const child = spawn('explorer', [dir], { shell: false })
+      let responded = false
+      child.on('error', (error) => {
+        if (responded) return
+        responded = true
+        writeJson(res, 500, { ok: false, error: error.message })
+      })
+      child.on('exit', (code) => {
+        if (responded) return
+        responded = true
+        if (code === 0) writeJson(res, 200, { ok: true })
+        else writeJson(res, 500, { ok: false, error: `explorer 退出码 ${code}` })
+      })
+    },
+  }
+
+  // ---------------------------------------------------------- plugin update
+  /** 插件自更新：在 DSH profile 目录拉取最新 npm 版（仅下载，需重启 DSH 生效）。 */
+  const pluginUpdateRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.pluginUpdate,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const profileDir = join(homedir(), '.dsh', 'profiles', 'web')
+      const response: PluginUpdateResponse = await new Promise((resolve) => {
+        const child = spawn('pnpm', ['add', '@waterwx/dsh-novel-forge@latest'], { cwd: profileDir, shell: true })
+        let acc = ''
+        child.stdout.on('data', (d: Buffer) => { acc += String(d) })
+        child.stderr.on('data', (d: Buffer) => { acc += String(d) })
+        child.on('error', (error) => resolve({ ok: false, message: '无法执行更新：' + error.message }))
+        child.on('close', (code) => {
+          if (code === 0) resolve({ ok: true, message: '已更新到最新版本，请重启 DSH 生效。' })
+          else resolve({ ok: false, message: '更新失败（退出码 ' + code + '）：' + acc.slice(-400) })
+        })
+      })
+      writeJson(res, 200, response)
+    },
+  }
+
+  // ------------------------------------------------------- outline suggest
+  /** 开书想法 → AI 大纲：2-3 个可选方案（支持暂留换批：count 只补空槽 + exclude 避开已留方向）。 */
+  const outlineSuggestRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.outlineSuggest,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const body = await readJsonBody<OutlineSuggestRequest>(req)
+      const idea = body?.idea?.trim() ?? ''
+      if (idea.length < 50) {
+        writeJson(res, 400, { error: '想法太短（<50 字），请多写一两句：主角是谁、什么世界、想要什么爽点' })
+        return
+      }
+      const count = body?.count !== undefined ? Math.max(1, Math.min(3, Math.floor(body.count))) : 3
+      const exclude = Array.isArray(body?.exclude) ? body.exclude.filter((e): e is string => typeof e === 'string' && e.trim() !== '').map(e => e.trim().slice(0, 200)) : []
+      try {
+        const candidates = await suggestOutlines(ctx, config, idea, count, exclude)
+        const response: OutlineSuggestResponse = { candidates }
+        writeJson(res, 200, response)
+      } catch (error) {
+        writeJson(res, 500, { error: `大纲方案生成失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+  // ------------------------------------------------- outline reverse
+  /** 反推大纲：从已写章节正文反向生成全书总纲（NDJSON 流式进度）。 */
+  const outlineReverseRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.outlineReverse,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: JobFrame): void => {
+        res.write(JSON.stringify(frame) + '\n')
+      }
+      try {
+        const outline = await reverseOutlineFromChapters(ctx, config, project, config.outputDir, (done, total, phase) => {
+          send({ type: 'outline-progress', done, total, phase })
+        })
+        // 保存总纲（仅更新文本，不动书名/进度）。
+        project.outline = outline
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        send({ type: 'outline-done', outline, chars: outline.length })
+      } catch (error) {
+        send({ type: 'error', no: 0, message: (error as Error).message })
+      } finally {
+        res.end()
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- llm-test
+  /** LLM 连通性测试：对选中的提供商/模型发一次最小真实调用。 */
+  const llmTestRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmTest,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<LlmTestRequest>(req)
+      const provider = (body?.provider ?? '').trim()
+      const model = (body?.model ?? '').trim()
+      if (provider === '' || model === '') {
+        writeJson(res, 400, { error: 'provider 与 model 必填' })
+        return
+      }
+      const result = await testLlmModel(ctx, provider, model)
+      writeJson(res, 200, result satisfies LlmTestResponse)
+    },
+  }
+
+  // ------------------------------------------------------------- llm-add
+  /** 添加模型：厂商直填 API Key，或自定义 OpenAI 兼容路由（写 DSH 凭据 + router）。 */
+  const addModelRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.addModel,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<AddModelRequest>(req)
+      if (body === undefined) {
+        writeJson(res, 400, { error: '缺少请求体' })
+        return
+      }
+      try {
+        const result = await registerLlmModel(ctx, body)
+        writeJson(res, 200, result satisfies AddModelResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `添加模型失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- llm-vendors
+  /** 运行时厂商目录（DSH pi-ai 可配置提供方 + 内置适配器）。 */
+  const llmVendorsRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmVendors,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      try {
+        const result = await listLlmVendors(ctx)
+        writeJson(res, 200, result satisfies LlmVendorsResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `读取厂商目录失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- llm-models
+  /** 查询某个 provider 当前可用的模型（添加成功后可即时刷新下拉）。 */
+  const llmModelsRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmModels,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      const url = new URL(req.url ?? '', 'http://localhost')
+      const provider = decodeURIComponent((url.searchParams.get('provider') ?? '').trim())
+      try {
+        const result = await listLlmModels(ctx, provider)
+        writeJson(res, 200, result satisfies LlmModelsResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `读取模型列表失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+  // ---------------------------------------------------------- llm-providers
+  /** 已注册的提供方路由列表（提供方管理卡片）。 */
+  const llmProvidersRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmProviders,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      try {
+        const result = await listLlmProviders(ctx)
+        writeJson(res, 200, result satisfies LlmProvidersResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `读取提供方列表失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+  // ------------------------------------------------------------- llm-remove
+  /** 移除一个提供方（unset key + 移除 llm-pi-ai 路由）。 */
+  const llmRemoveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.llmRemove,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<RemoveProviderRequest>(req)
+      if (body === undefined) {
+        writeJson(res, 400, { error: '缺少请求体' })
+        return
+      }
+      try {
+        const result = await removeLlmProvider(ctx, body)
+        writeJson(res, 200, result satisfies RemoveProviderResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `移除提供方失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+
+  // ----------------------------------------------------------- breakdown
+  /** 拆书分析：对已写章节做结构/人物/文风/卖点体检（两阶段：源笔记→分节分析）。 */
+  const breakdownRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.breakdown,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const config = getConfig()
+      const project = requireProject(res)
+      if (project === undefined) return
+      const body = await readJsonBody<BreakdownRequest>(req)
+      try {
+        const result = await breakdownBook(
+          ctx,
+          config,
+          project,
+          config.outputDir,
+          body?.scope ?? 'recent',
+          body?.preset ?? 'quick',
+          body?.budgetTokens ?? 50000,
+        )
+        writeJson(res, 200, result satisfies BreakdownResponse)
+      } catch (error) {
+        writeJson(res, 500, { error: `拆书分析失败：${(error as Error).message}` })
+      }
+    },
+  }
+
+
+  // ----------------------------------------------------------- production run
+  /** 生产单执行器（单例）：计划补足 → 逐章生成 → 被拒分级处理 → 断点续跑。 */
+  const runner = new ProductionRunner({ ctx, getConfig })
+
+  const runStartRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.runStart,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<RunStartRequest & { bookId?: string }>(req)
+      const config = getConfig()
+      const outputDir = resolveOutputDir(config, body?.bookId)
+      const project = loadProject(outputDir)
+      if (project === undefined) {
+        writeJson(res, 400, { error: '输出目录中没有项目' })
+        return
+      }
+      const startNo = Number.isInteger(body?.startNo) && (body!.startNo! >= 1) ? body!.startNo! : 1
+      let endNo: number
+      if (Number.isInteger(body?.endNo) && (body!.endNo! >= startNo)) {
+        endNo = body!.endNo!
+      } else if (Number.isInteger(body?.count) && (body!.count! >= 1) && (body!.count! <= 200)) {
+        const last = Math.max(0, ...project.chapters.map(c => c.no))
+        endNo = last + body!.count!
+      } else {
+        writeJson(res, 400, { error: '请提供 endNo 或 count（1-200）' })
+        return
+      }
+      try {
+        const state = await runner.start(startNo, endNo, outputDir)
+        writeJson(res, 200, state satisfies RunState)
+      } catch (error) {
+        writeJson(res, 409, { error: (error as Error).message })
+      }
+    },
+  }
+
+  const runControlRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.runControl,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<RunControlRequest>(req)
+      const state = runner.status()
+      if (state === null) {
+        writeJson(res, 400, { error: '没有生产单' })
+        return
+      }
+      if (body?.action === 'pause') runner.pause()
+      else if (body?.action === 'resume') runner.resume()
+      else if (body?.action === 'stop') runner.stop()
+      else {
+        writeJson(res, 400, { error: 'action 须为 pause / resume / stop' })
+        return
+      }
+      writeJson(res, 200, runner.status())
+    },
+  }
+
+  const runStatusRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.runStatus,
+    handler: (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      writeJson(res, 200, runner.status())
+    },
+  }
+
+  // -------------------------------------------------- author assets (总数据)
+  const authorAssetsRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.authorAssets,
+    handler: (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      const response: AuthorAssetsResponse = { assets: loadAuthorAssets() }
+      writeJson(res, 200, response)
+    },
+  }
+
+  const authorAssetsUpsertRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.authorAssetsUpsert,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<AuthorAssetUpsertRequest>(req)
+      const asset = body?.asset
+      if (asset === undefined || asset.name.trim() === '' || asset.content.trim() === '') {
+        writeJson(res, 400, { error: 'asset 须含 name / content' })
+        return
+      }
+      const response: AuthorAssetsResponse = { assets: upsertAuthorAsset(asset) }
+      writeJson(res, 200, response)
+    },
+  }
+
+  const authorAssetsRemoveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.authorAssetsRemove,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<AuthorAssetRemoveRequest>(req)
+      const id = body?.id ?? ''
+      if (id === '') { writeJson(res, 400, { error: 'id 必填' }); return }
+      const response: AuthorAssetsResponse = { assets: removeAuthorAsset(id) }
+      writeJson(res, 200, response)
+    },
+  }
+
+  const authorAssetsImportDefaultRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.authorAssetsImportDefault,
+    handler: (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const response: AuthorAssetsResponse = { assets: importDefaultAuthorAssets() }
+      writeJson(res, 200, response)
+    },
+  }
+
+  // --------------------------------------------------- adaptation (改编 P0 分析)
+  const adaptAnalyzeRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptAnalyze,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptAnalyzeRequest>(req)
+      const config = getConfig()
+      let text = body?.text?.trim() ?? ''
+      if (text === '' && body?.filePath !== undefined && body.filePath !== '') {
+        try {
+          text = readFileSync(body.filePath, 'utf8')
+        } catch (err) {
+          writeJson(res, 400, { error: '读取文件失败：' + (err as Error).message })
+          return
+        }
+      }
+      if (text.length < 200) {
+        writeJson(res, 400, { error: '全文内容过短（<200 字符），请上传完整小说文本' })
+        return
+      }
+      try {
+        const response: AdaptAnalyzeResponse = await analyzeAdaptation(ctx, config, text)
+        writeJson(res, 200, response)
+      } catch (err) {
+        writeJson(res, 400, { error: (err as Error).message })
+      }
+    },
+  }
+
+  const adaptProposeRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptPropose,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptProposeRequest>(req)
+      const config = getConfig()
+      const text = (body?.text ?? '').trim()
+      const selections = body?.selections ?? []
+      if (text.length < 200 || selections.length === 0) {
+        writeJson(res, 400, { error: '请提供全文与至少一条要改的维度' })
+        return
+      }
+      try {
+        const response: AdaptProposeResponse = await proposeAdaptation(ctx, config, text, selections, body?.dimensions)
+        writeJson(res, 200, response)
+      } catch (err) {
+        writeJson(res, 400, { error: (err as Error).message })
+      }
+    },
+  }
+
+  const adaptExecuteRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptExecute,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptExecuteRequest>(req)
+      const text = body?.text ?? ''
+      const mappings = body?.mappings ?? []
+      if (text.length < 200 || mappings.length === 0) {
+        writeJson(res, 400, { error: '请提供全文与映射表' })
+        return
+      }
+      if (body?.mode === 'rewrite') {
+        try {
+          const result = await rewriteAdaptationBook(ctx, getConfig(), text, mappings, body?.rules, { maxChapters: body?.maxChapters, startNo: body?.startNo, endNo: body?.endNo })
+          const response: AdaptExecuteResponse = { adaptedText: result.adaptedText, mappings: mappings.length, hits: result.hits, mode: 'rewrite', rewritten: result.rewritten, skipped: result.skipped }
+          writeJson(res, 200, response)
+        } catch (err) {
+          writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+        }
+        return
+      }
+      const { adaptedText, hits } = applyAdaptationReplacements(text, mappings)
+      const response: AdaptExecuteResponse = { adaptedText, mappings: mappings.length, hits, mode: 'replace' }
+      writeJson(res, 200, response)
+    },
+  }
+
+  /** rewrite 逐章重写：NDJSON 流式进度（支持分段 startNo/endNo）。 */
+  const adaptRewriteStreamRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptRewriteStream,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptExecuteRequest>(req)
+      const text = body?.text ?? ''
+      const mappings = body?.mappings ?? []
+      if (text.length < 200 || mappings.length === 0) { writeJson(res, 400, { error: '请提供全文与映射表' }); return }
+      res.writeHead(200, {
+        'content-type': 'application/x-ndjson; charset=utf-8',
+        'cache-control': 'no-cache',
+        'x-accel-buffering': 'no',
+        'referrer-policy': 'no-referrer',
+      })
+      const send = (frame: AdaptRewriteFrame): void => { res.write(JSON.stringify(frame) + '\n') }
+      try {
+        const result = await rewriteAdaptationBook(ctx, getConfig(), text, mappings, body?.rules, {
+          maxChapters: body?.maxChapters,
+          startNo: body?.startNo,
+          endNo: body?.endNo,
+          onProgress: (info) => send({ type: 'progress', completed: info.completed, total: info.total, no: info.no, title: info.title }),
+        })
+        const response: AdaptExecuteResponse = { adaptedText: result.adaptedText, mappings: mappings.length, hits: result.hits, mode: 'rewrite', rewritten: result.rewritten, skipped: result.skipped }
+        send({ type: 'done', result: response })
+      } catch (err) {
+        send({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+      } finally {
+        res.end()
+      }
+    },
+  }
+
+  /** 保存改编全文为新书（原书保留，登记书架）。 */
+  const adaptSaveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptSave,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptSaveRequest>(req)
+      const text = (body?.text ?? '').trim()
+      if (text.length < 200) {
+        writeJson(res, 400, { error: '改编全文内容过短（<200 字符）' })
+        return
+      }
+      const bookName = (body?.bookName ?? '').trim().slice(0, 40) || '改编新书'
+      const outDir = (body?.outputDir ?? '').trim() !== '' && body?.outputDir !== undefined && body.outputDir.trim() !== ''
+        ? body.outputDir.trim()
+        : defaultOutputDirFor(bookName)
+      // 原书保留：若目录已被另一本书占用则拒绝，避免误覆盖原书/别的书。
+      const occupied = loadBookshelf().books.find(b => b.outputDir === outDir)
+      if (occupied !== undefined && occupied.bookName !== bookName) {
+        writeJson(res, 409, { error: `目录已被《${occupied.bookName}》占用，请更换书名或输出目录` })
+        return
+      }
+      try {
+        const result = importBookTextFromText(text, outDir, bookName)
+        // 有反推大纲时写进新项目，便于后续续写/编辑（importBookTextFromText 默认 outline=书名）。
+        const outline = (body?.outline ?? '').trim()
+        if (outline !== '') {
+          const project = loadProject(outDir)
+          if (project !== undefined) {
+            project.outline = outline
+            saveProject(outDir, project)
+          }
+        }
+        const { book } = importDir(outDir)
+        const response: AdaptSaveResponse = { book, bookName: result.bookName, chapters: result.chapters, skipped: result.skipped, outputDir: outDir }
+        writeJson(res, 200, response)
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  /** 从源全文 + 编辑后方案提炼新书资料并保存为「待写新书」。 */
+  const adaptMaterializeRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptMaterialize,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptMaterializeRequest>(req)
+      const text = (body?.text ?? '').trim()
+      if (text.length < 200) { writeJson(res, 400, { error: '源书全文内容过短（<200 字符）' }); return }
+      const proposal = body?.proposal
+      if (proposal === undefined || proposal.mappings.length === 0) { writeJson(res, 400, { error: '请先提供至少一条映射的改编方案' }); return }
+      const bookName = (body?.bookName ?? '').trim().slice(0, 40) || '改编新书'
+      const outDir = (body?.outputDir ?? '').trim() !== '' && body?.outputDir !== undefined && body.outputDir.trim() !== ''
+        ? body.outputDir.trim()
+        : defaultOutputDirFor(bookName)
+      // 原书保留：若目录已被另一本书占用则拒绝。
+      const occupied = loadBookshelf().books.find(b => b.outputDir === outDir)
+      if (occupied !== undefined && occupied.bookName !== bookName) {
+        writeJson(res, 409, { error: `目录已被《${occupied.bookName}》占用，请更换书名或输出目录` })
+        return
+      }
+      try {
+        const result = await materializeAdaptedBook(ctx, getConfig(), {
+          text,
+          bookName,
+          outputDir: outDir,
+          outline: body?.outline,
+          proposal,
+          chapterCount: body?.chapterCount,
+        })
+        // 预览：只返回提炼资料，不落盘；保存走 /adapt/materialize-save。
+        const response: AdaptMaterializeResponse = result
+        writeJson(res, 200, response)
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  /** 保存预览/微调后的新书资料为新书（原书保留，登记书架）。 */
+  const adaptMaterializeSaveRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.adaptMaterializeSave,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      if (!getConfig().enableAdaptMode) { writeJson(res, 404, { error: '改编模式未开启' }); return }
+      const body = await readJsonBody<AdaptMaterializeSaveRequest>(req)
+      if (body === undefined || body === null || (body.outline ?? '').trim() === '') {
+        writeJson(res, 400, { error: '请提供改编后总纲' })
+        return
+      }
+      const bookName = (body.bookName ?? '').trim().slice(0, 40) || '改编新书'
+      const outDir = (body.outputDir ?? '').trim() !== '' && body.outputDir !== undefined && body.outputDir.trim() !== ''
+        ? body.outputDir.trim()
+        : defaultOutputDirFor(bookName)
+      const occupied = loadBookshelf().books.find(b => b.outputDir === outDir)
+      if (occupied !== undefined && occupied.bookName !== bookName) {
+        writeJson(res, 409, { error: `目录已被《${occupied.bookName}》占用，请更换书名或输出目录` })
+        return
+      }
+      try {
+        const result = saveMaterializedBook(outDir, bookName, {
+          outline: body.outline,
+          bible: body.bible,
+          roles: body.roles,
+          world: body.world,
+          volumes: body.volumes,
+          chapters: body.chapters,
+        })
+        const { book } = importDir(outDir)
+        const response: AdaptMaterializeSaveResponse = { ...result, book }
+        writeJson(res, 200, response)
+      } catch (err) {
+        writeJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+      }
+    },
+  }
+
+  // ------------------------------------------ theme custom background (upload + serve)
+  const THEME_BG_DIR = join(homedir(), '.dsh', 'dsh-novel-forge-assets')
+  const MIME_BY_EXT: Record<string, string> = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }
+
+  const themeBackgroundUploadRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.themeBackgroundUpload,
+    handler: async (req, res) => {
+      if (!guard(req, res, 'POST')) return
+      const body = await readJsonBody<{ dataUrl?: string }>(req)
+      const dataUrl = body?.dataUrl ?? ''
+      const m = /^data:image\/(png|jpeg|jpg|webp|gif);base64,(.+)$/i.exec(dataUrl)
+      if (m === null) { writeJson(res, 400, { error: '仅支持 PNG/JPG/WebP/GIF 图片' }); return }
+      const ext = m[1]!.toLowerCase() === 'jpg' ? 'jpeg' : m[1]!.toLowerCase()
+      const buf = Buffer.from(m[2]!, 'base64')
+      if (buf.length === 0) { writeJson(res, 400, { error: '图片数据为空' }); return }
+      mkdirSync(THEME_BG_DIR, { recursive: true })
+      const name = 'theme-bg-' + Date.now().toString(36) + '-' + randomBytes(3).toString('hex') + '.' + ext
+      writeFileSync(join(THEME_BG_DIR, name), buf)
+      writeJson(res, 200, { url: NOVEL_API.themeBackgroundGet + '/' + name })
+    },
+  }
+
+  const themeBackgroundGetRoute: WebRoute = {
+    kind: 'prefix',
+    path: NOVEL_API.themeBackgroundGet,
+    handler: (req, res) => {
+      if (!guard(req, res, 'GET')) return
+      let pathName = ''
+      try { pathName = new URL(req.url ?? '', 'http://localhost').pathname } catch { /* ignore */ }
+      const name = basename(pathName)
+      if (!name.startsWith('theme-bg-')) { writeJson(res, 404, { error: 'not found' }); return }
+      const file = join(THEME_BG_DIR, name)
+      if (!existsSync(file)) { writeJson(res, 404, { error: 'not found' }); return }
+      const ext = extname(file).slice(1)
+      const type = MIME_BY_EXT[ext] ?? 'application/octet-stream'
+      res.writeHead(200, { 'content-type': type, 'cache-control': 'public, max-age=31536000' })
+      res.end(readFileSync(file))
+    },
+  }
+
+  return [
+    statusRoute,
+    loadOutlineRoute,
+    saveOutlineRoute,
+    bibleRoute,
+    volumesRoute,
+    planRoute,
+    generateRoute,
+    reviewRoute,
+    rewriteRoute,
+    polishRoute,
+    draftApplyRoute,
+    draftDiscardRoute,
+    summaryRoute,
+    foreshadowRoute,
+    exportRoute,
+    chapterRoute,
+    chapterCheckRoute,
+    chapterSaveRoute,
+    assetsRoute,
+    styleEngineRoute,
+    styleFormulaRoute,
+    styleDetectRoute,
+    marketRadarRoute,
+    marketRadarScanRoute,
+    marketRadarApplyRoute,
+    marketRadarSyncRoute,
+    marketRadarBriefRoute,
+    knowledgeRoute,
+    bookAnalysisRoute,
+    ideaInspirationRoute,
+    marketIdeaInspirationRoute,
+    directorRoute,
+    directorTodosRoute,
+    llmLiveRoute,
+    assistantRoute,
+    assistantHistoryRoute,
+    assistantClearRoute,
+    bookshelfRoute,
+    bookshelfActivateRoute,
+    bookshelfRemoveRoute,
+    bookshelfImportDirRoute,
+    bookshelfImportTextRoute,
+    bookshelfImportTextPreviewRoute,
+    resetRoute,
+    auditRoute,
+    charactersRefreshRoute,
+    factsBackfillRoute,
+    biblePatchRoute,
+    blurbRoute,
+    coverRoute,
+    worldRoute,
+    renameRoute,
+    plotlinesRoute,
+    rolesRoute,
+    sensitiveRoute,
+    reviewBackfillRoute,
+    chapterResetRoute,
+    chapterApproveRoute,
+    configRoute,
+    openFolderRoute,
+    pluginUpdateRoute,
+    outlineSuggestRoute,
+    outlineReverseRoute,
+    llmTestRoute,
+    addModelRoute,
+    llmVendorsRoute,
+    llmModelsRoute,
+    llmProvidersRoute,
+    llmRemoveRoute,
+    breakdownRoute,
+    runStartRoute,
+    runControlRoute,
+    runStatusRoute,
+    authorAssetsRoute,
+    authorAssetsUpsertRoute,
+    authorAssetsRemoveRoute,
+    authorAssetsImportDefaultRoute,
+    adaptAnalyzeRoute,
+    adaptProposeRoute,
+    adaptExecuteRoute,
+    adaptSaveRoute,
+    adaptMaterializeRoute,
+    adaptMaterializeSaveRoute,
+    adaptRewriteStreamRoute,
+    themeBackgroundUploadRoute,
+    themeBackgroundGetRoute,
+  ]
+}
+
+// Re-export for tests / type consumers.
+export type {
+  ConfigPatch,
+  NovelConfig,
+  StatusResponse,
+  PlanResponse,
+  LoadOutlineResponse,
+  BibleResponse,
+  VolumesResponse,
+  ExportResponse,
+}
+export { chapterFileName }