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

package/src/protocol.ts

@@ -15,6 +15,34 @@ export const NOVEL_API = {
   bible: '/api/dsh-novel-forge/bible',
   assets: '/api/dsh-novel-forge/assets',
   styleEngine: '/api/dsh-novel-forge/style-engine',
+  styleFormula: '/api/dsh-novel-forge/style-formula',
+  styleDetect: '/api/dsh-novel-forge/style-detect',
+  knowledge: '/api/dsh-novel-forge/knowledge',
+  bookAnalysis: '/api/dsh-novel-forge/book-analysis',
+  ideaInspiration: '/api/dsh-novel-forge/idea-inspiration',
+  ideaInspirationMarket: '/api/dsh-novel-forge/idea-inspiration/market',
+  director: '/api/dsh-novel-forge/director',
+  directorTodos: '/api/dsh-novel-forge/director/todos',
+  llmLive: '/api/dsh-novel-forge/llm-live/stream',
+  /** 查看某次调用实际发送的 Prompt（按 sessionId）。 */
+  llmPrompt: '/api/dsh-novel-forge/llm-live/prompt',
+  /** 清零本次运行的用量账本。 */
+  usageReset: '/api/dsh-novel-forge/usage/reset',
+  /** 章节历史版本（快照）。 */
+  snapshot: '/api/dsh-novel-forge/snapshot',
+  /** 修订指令合并（POST：汇总审稿/时间线/张力为一轮）。 */
+  revisionPlan: '/api/dsh-novel-forge/revision/plan',
+  /** 张力曲线（GET 数据 / POST 设置）。 */
+  tension: '/api/dsh-novel-forge/tension',
+  /** 提示词槽位（GET 列表 / POST 写入）。 */
+  promptSlots: '/api/dsh-novel-forge/prompt-slots',
+  /** 故事时间线（GET 列表 / POST 操作）。 */
+  timeline: '/api/dsh-novel-forge/timeline',
+  marketRadar: '/api/dsh-novel-forge/market-radar',
+  marketRadarScan: '/api/dsh-novel-forge/market-radar/scan',
+  marketRadarApply: '/api/dsh-novel-forge/market-radar/apply',
+  marketRadarSync: '/api/dsh-novel-forge/market-radar/foundation-sync',
+  marketRadarBrief: '/api/dsh-novel-forge/market-radar/brief',
   generate: '/api/dsh-novel-forge/generate',
   review: '/api/dsh-novel-forge/review',
   rewrite: '/api/dsh-novel-forge/rewrite',
@@ -36,6 +64,24 @@ export const NOVEL_API = {
   /** 清空助手对话记录。 */
   assistantClear: '/api/dsh-novel-forge/assistant/clear',
   bookshelf: '/api/dsh-novel-forge/bookshelf',
+  /** 导入已有项目目录（含 novel-project.json）到书架。 */
+  bookshelfImportDir: '/api/dsh-novel-forge/bookshelf/import-dir',
+  /** 导入 txt/md 全本：拆章建项目并登记书架。 */
+  bookshelfImportText: '/api/dsh-novel-forge/bookshelf/import-text',
+  /** 导入 txt/md 全本：拆章预览（不落盘）。 */
+  bookshelfImportTextPreview: '/api/dsh-novel-forge/bookshelf/import-text/preview',
+  /** LLM 模型连通性测试：真实最小调用，验证 Key / 端点 / 模型可用。 */
+  llmTest: '/api/dsh-novel-forge/llm-test',
+  /** 添加模型：厂商直填 key 或自定义路由，写进 DSH 凭据与 llm-pi-ai 路由。 */
+  addModel: '/api/dsh-novel-forge/llm-add',
+  /** 运行时厂商目录（DSH pi-ai 可配置提供方 + 内置适配器）。 */
+  llmVendors: '/api/dsh-novel-forge/llm-vendors',
+  /** 查询某个 provider 当前可用的模型（添加成功后可即时刷新）。 */
+  llmModels: '/api/dsh-novel-forge/llm-models',
+  /** 已注册的提供方路由列表（提供方管理）。 */
+  llmProviders: '/api/dsh-novel-forge/llm-providers',
+  /** 移除一个提供方。 */
+  llmRemove: '/api/dsh-novel-forge/llm-remove',
   /** 重置项目（可选携带新大纲）：清空设定/卷/章节/伏笔/资产/事实库。 */
   reset: '/api/dsh-novel-forge/reset',
   /** 全书一致性质检：LLM 扫描已生成章节，输出矛盾问题清单。 */
@@ -44,22 +90,20 @@ export const NOVEL_API = {
   charactersRefresh: '/api/dsh-novel-forge/characters/refresh',
   /** 事实库回填：对历史已生成章节批量抽取事实（旧章节无事实记录时用）。 */
   factsBackfill: '/api/dsh-novel-forge/facts/backfill',
-  /** 设定圣经局部修补（如世界观规则编辑）。 */
+  /** 道藏局部修补（如世界观规则编辑）。 */
   biblePatch: '/api/dsh-novel-forge/bible/patch',
   /** 小说简介：生成（AI）/补全（AI）/保存。 */
   blurb: '/api/dsh-novel-forge/blurb',
   /** 重命名当前书（同步项目与书架条目）。 */
   rename: '/api/dsh-novel-forge/rename',
-  /** 大世界：AI 提炼 / 保存结构化数据（境界/区域/势力）。 */
+  /** 大世界：提炼 / 保存结构化数据（境界/区域/势力）。 */
   world: '/api/dsh-novel-forge/world',
   /** 封面：GET 读取（dataUrl）/ POST 上传或移除。 */
   cover: '/api/dsh-novel-forge/blurb/cover',
   /** 剧情线管理：增删改 + 关联章节。 */
   plotlines: '/api/dsh-novel-forge/plotlines',
-  /** 角色库：AI 提炼 / 采纳 / 更新 / 删除。 */
+  /** 角色库：提炼 / 采纳 / 更新 / 删除。 */
   roles: '/api/dsh-novel-forge/roles',
-  scenes: '/api/dsh-novel-forge/scenes',
-  visualRules: '/api/dsh-novel-forge/visual-rules',
   /** 作者复盘补跑：对已写章节补齐 authorReview（全书流式 / 单章 JSON）。 */
   reviewBackfill: '/api/dsh-novel-forge/review/backfill',
   /** 章节复位：generating 卡死 → pending（可重新生成）。 */
@@ -68,13 +112,12 @@ export const NOVEL_API = {
   chapterApprove: '/api/dsh-novel-forge/chapter/approve',
   /** 敏感词检查：全书已写章节或指定文本。 */
   sensitiveCheck: '/api/dsh-novel-forge/sensitive-check',
-  /** 开书想法 → AI 补全大纲：输入一句话想法，生成 2-3 个可选大纲方案。 */
+  /** 开书想法 → 补全大纲：输入一句话想法，生成 2-3 个可选大纲方案。 */
   outlineSuggest: '/api/dsh-novel-forge/outline/suggest',
+  /** 反推大纲：从已写章节正文反向生成全书总纲（NDJSON 流）。 */
+  outlineReverse: '/api/dsh-novel-forge/outline/reverse',
   /** 拆书分析：对已写章节做结构/人物/文风/卖点四维体检（两阶段：源笔记→分节分析）。 */
   breakdown: '/api/dsh-novel-forge/breakdown',
-  /** 漫剧分镜生成：章节 → 角色锚点 + 分镜表（可适配豆包/Seedance/SD）。 */
-  /** 漫剧分集计划：读一卷 → 按故事弧线分集（高潮拆集/过渡并章）。 */
-  /** 漫画脚本：章节 → 分页分格漫画脚本（含角色视觉锚点）。 */
   /** 生产单：启动批量生产（计划补足 + 逐章生成 + 被拒分级处理）。 */
   runStart: '/api/dsh-novel-forge/run/start',
   /** 生产单控制：pause / resume / stop。 */
@@ -82,7 +125,39 @@ export const NOVEL_API = {
   /** 生产单状态（含进度统计与日志）。 */
   runStatus: '/api/dsh-novel-forge/run/status',
   config: '/api/dsh-novel-forge/config',
+  /** 输出目录迁移：dryRun 预览 / 确认后搬文件并联动配置与书架。 */
+  moveOutputDir: '/api/dsh-novel-forge/move-output-dir',
+  /** 本书参数：POST {} 读取；POST {patch} 合并保存（存 novel-project.json）。 */
+  bookSettings: '/api/dsh-novel-forge/book-settings',
   openFolder: '/api/dsh-novel-forge/open-folder',
+  /** 插件自更新：在 DSH profile 目录拉取最新 npm 版（下载后需重启 DSH 生效）。 */
+  pluginUpdate: '/api/dsh-novel-forge/plugin/update',
+  /** 作者资产库/总数据：读取个人跨书资产（笔法/红线/套路/角色模板/世界观模板）。 */
+  authorAssets: '/api/dsh-novel-forge/author-assets',
+  /** 作者资产库：新增/更新一条资产（upsert by id）。 */
+  authorAssetsUpsert: '/api/dsh-novel-forge/author-assets/upsert',
+  /** 作者资产库：删除一条资产。 */
+  authorAssetsRemove: '/api/dsh-novel-forge/author-assets/remove',
+  /** 作者资产库：导入默认（书架书的写作资产/角色 + 内置全局库）批量沉淀。 */
+  authorAssetsImportDefault: '/api/dsh-novel-forge/author-assets/import-default',
+  /** 改编模式：上传全文 → 分析 → 原文设定卡片/可改范围矩阵。 */
+  adaptAnalyze: '/api/dsh-novel-forge/adapt/analyze',
+  /** 改编模式：确认要改的维度 → 生成映射表/改编规则/联动影响清单。 */
+  adaptPropose: '/api/dsh-novel-forge/adapt/propose',
+  /** 改编模式：执行术语替换（全局替换 + 命中统计 + 改编文本预览）。 */
+  adaptExecute: '/api/dsh-novel-forge/adapt/execute',
+  /** 改编模式：保存改编全文为新书（原书保留，登记书架）。 */
+  adaptSave: '/api/dsh-novel-forge/adapt/save',
+  /** 改编模式：从源全文 + 编辑后方案提炼新书资料并保存为「待写新书」。 */
+  adaptMaterialize: '/api/dsh-novel-forge/adapt/materialize',
+  /** 改编模式：rewrite 逐章重写（NDJSON 流式进度）。 */
+  adaptRewriteStream: '/api/dsh-novel-forge/adapt/rewrite-stream',
+  /** 改编模式：把预览/微调后的新书资料写入并登记书架。 */
+  adaptMaterializeSave: '/api/dsh-novel-forge/adapt/materialize-save',
+  /** 主题自定义背景：上传图片（POST，存盘并返回服务端 URL）。 */
+  themeBackgroundUpload: '/api/dsh-novel-forge/theme/background',
+  /** 主题自定义背景：读取已上传文件（GET prefix，/theme/background/<name>）。 */
+  themeBackgroundGet: '/api/dsh-novel-forge/theme/background',
 } as const
 
 /** 书架：一本书的条目。 */
@@ -130,6 +205,62 @@ export interface BookRemoveRequest {
   id: string
 }
 
+/** POST /bookshelf/import-dir 请求：导入已有项目目录。 */
+export interface BookImportDirRequest {
+  /** 项目目录（须含 novel-project.json）。 */
+  outputDir: string
+}
+
+/** POST /bookshelf/import-dir 响应。 */
+export interface BookImportDirResponse {
+  book: BookEntry
+  /** true = 目录已在书架中（本次为重新激活）。 */
+  existed: boolean
+}
+
+/** POST /bookshelf/import-text 请求：导入 txt/md 全本。两种模式二选一：
+ *  - filePath：服务器本地文件路径；
+ *  - text + fileName：浏览器上传的全文内容（fileName 用于推断书名）。
+ */
+export interface BookImportTextRequest {
+  /** 模式一：源文件绝对路径（txt 或 md）。 */
+  filePath?: string
+  /** 模式二：浏览器上传的全文内容。 */
+  text?: string
+  /** 模式二：原文件名（txt/md），用于推断书名与显示。 */
+  fileName?: string
+  /** 输出目录；缺省为 ~/.dsh/novels/书名。 */
+  outputDir?: string
+}
+
+/** POST /bookshelf/import-text 响应。 */
+export interface BookImportTextResponse {
+  bookName: string
+  /** 成功拆出的章节数。 */
+  chapters: number
+  /** 因内容过短被跳过的章节标题列表。 */
+  skipped: string[]
+  /** 登记后的书架条目。 */
+  book: BookEntry
+}
+
+/** POST /bookshelf/import-text/preview 请求：上传全文做拆章预览（不落盘）。 */
+export interface BookImportTextPreviewRequest {
+  text: string
+  /** 原文件名（txt/md），用于推断书名。 */
+  fileName?: string
+}
+
+/** POST /bookshelf/import-text/preview 响应。 */
+export interface BookImportTextPreviewResponse {
+  /** 预计书名（fileName 去扩展名）。 */
+  bookName: string
+  /** 识别出的章节（已按正文长度过滤过短章节）。 */
+  chapters: Array<{ no: number; title: string; chars: number }>
+  /** 因内容过短被跳过的章节标题列表。 */
+  skipped: string[]
+}
+
 /** Chapter lifecycle states (the writing pipeline's state machine). */
 export type ChapterStatus =
   | 'pending'      // planned, not started
@@ -152,6 +283,18 @@ export interface ChapterPlan {
   beats: string
   /** Target character count (defaults to the configured chapter size). */
   targetChars: number
+  /** 本章必达项（必须推进的局面/关系/信息/风险/决策变化）。 */
+  mustAdvance?: string[]
+  /** 本章必须保持/不得破坏的项（如人物状态、已有伏笔不提前揭）。 */
+  mustPreserve?: string[]
+  /** 本章不可违背的人物硬事实（身份/阵营/境界/当前位置/知情度）。 */
+  characterHardFacts?: string[]
+  /** 伏笔操作指令（seed/touch/pressure/partial_reveal/payoff/forbid）。 */
+  payoffDirectives?: Array<{ no?: number; operation?: 'seed' | 'touch' | 'pressure' | 'partial_reveal' | 'payoff' | 'forbid'; text?: string }>
+  /** 章末钩子要求（悬念/反转/新线索/未闭合选择）。 */
+  endingHook?: string
+  /** 本章义务合约（人类可读摘要，供生成与审稿共同锚定）。 */
+  obligation?: string
   /** Generation/review state. */
   status: ChapterStatus
   /** 进入 generating 的时间（用于超时自动复位；未在生成时无此字段）。 */
@@ -168,6 +311,10 @@ export interface ChapterPlan {
   review?: ReviewReport
   /** 作者复盘：钩子兑现/结尾钩子/剧情线推进/连续性/节奏趋势（生成后自动）。 */
   authorReview?: AuthorReview
+  /** 本章目标张力 0-100（规划或作者设定；用于张力曲线）。 */
+  tension?: number
+  /** 本章实际张力 0-100（审稿时模型打分；缺省时回落到 review.tension）。 */
+  tensionActual?: number
   /**
    * 待确认草稿：润色（去AI味）或整章重写的产物正文。生成时先存这里，
    * 用户看过对比后点「采纳」才覆盖正文文件；点「放弃」则丢弃。刷新页面不丢失。
@@ -191,18 +338,46 @@ export interface AuthorReview {
   continuity: string
   /** 近期节奏趋势提示（拖沓/爽点密度等）。 */
   trend: string
+  /** 本章发生的关键状态变化（人物状态/世界局面/关系/资源），用于回灌整本与事实库。 */
+  stateChanges?: string[]
+  /** 本章新引入或升级的冲突（供整本控制层与后续卷节奏参考）。 */
+  newConflicts?: string[]
+  /** 本章埋下/推进的新线索（供知识与伏笔系统回灌）。 */
+  clues?: string[]
+  /** 本章缺席但值得注意的角色及风险（卷级职责/缺席风险）。 */
+  absentRisks?: string[]
   /** 复盘时间。 */
   reviewedAt: string
 }
 
+/** 审稿维度（结构化定位问题类别；与 review-policy.ts 的 REVIEW_DIMENSIONS 对齐）。 */
+export type ReviewDimension = 'character' | 'setting' | 'redline' | 'writing' | 'pacing' | 'logic' | 'anti-ai' | 'presentation' | 'compliance'
+
 /** One review finding. */
+/** 问题严重度（审稿 / 时间线 / 张力共用）。 */
+export type Severity = 'high' | 'medium' | 'low'
+
 export interface ReviewIssue {
   /** Severity: high = must fix, medium = should fix, low = suggestion. */
-  severity: 'high' | 'medium' | 'low'
+  severity: Severity
+  /** 问题维度（可选；缺省由前端按 item 推断）。 */
+  dimension?: ReviewDimension
   /** What the problem is. */
   item: string
   /** Concrete suggestion for fixing it. */
   suggestion: string
+  /** 命中的反 AI 规则名（结构化，便于统计）。 */
+  ruleName?: string
+  /** 规则类别：forbidden / risk / encourage。 */
+  ruleType?: 'forbidden' | 'risk' | 'encourage'
+  /** 问题细分类（如 套话 句式 段落 心理 设定）。 */
+  category?: string
+  /** 命中的原文摘录。 */
+  excerpt?: string
+  /** 判定理由。 */
+  reason?: string
+  /** 是否可自动改写。 */
+  canAutoRewrite?: boolean
 }
 
 /** AI review report for one chapter. */
@@ -215,6 +390,14 @@ export interface ReviewReport {
   verdict: string
   /** Individual findings. */
   issues: ReviewIssue[]
+  /** 风险分 0-100（越高越需人工处理；源自 LLM 复核与本地扫描）。 */
+  riskScore?: number
+  /** 本地 AI 味指数 0-100（越高越像 AI；LLM 复核锚点，供 UI 展示）。 */
+  aiFlavor?: number
+  /** 本地扫描命中的高频套话（按次数降序，取前若干）。 */
+  aiPhrases?: Array<{ word: string; count: number }>
+  /** 本章张力 0-100（审稿模型评分；用于张力曲线的"实际"值）。 */
+  tension?: number
   /** When the review ran. */
   reviewedAt: string
 }
@@ -231,6 +414,139 @@ export interface Volume {
   chapterStart: number
   /** Last chapter number (inclusive). */
   chapterEnd: number
+  /** 卷级战略（这一卷的定位/承转，如「立威卷」「冲突升级卷」）。 */
+  strategy?: string
+  /** 卷节奏板（这一卷的节奏安排：起-承-转-合/爽点密度/关键节点）。 */
+  pacing?: string
+}
+
+/** 开书定盘：面向读者的承诺与流派定位（生成/规划均可引用）。 */
+export interface BookContract {
+  /** 一句话卖点/题材承诺。 */
+  promise?: string
+  /** 主推进模式名（从推进模式库选）。 */
+  primaryModeName?: string
+  /** 辅助推进模式名。 */
+  secondaryModeNames?: string[]
+  /** 整体文风基调（一句话）。 */
+  tone?: string
+  /** 目标平台（如「番茄」）。 */
+  targetPlatform?: string
+}
+
+/** 书内知识库文档（供生成/规划时检索注入的参考资料）。 */
+export interface KnowledgeDoc {
+  id: string
+  title: string
+  content: string
+  updatedAt: string
+}
+
+/** POST /knowledge request：增删改知识库文档。 */
+export interface KnowledgeRequest {
+  action: 'add' | 'remove' | 'replace'
+  doc?: { id?: string; title: string; content: string }
+  id?: string
+}
+
+/** POST /book-analysis request。 */
+export interface BookAnalysisRequest {
+  text: string
+}
+
+/** 书分析/拆书结果。 */
+export interface BookAnalysisResult {
+  sellingPoints: string[]
+  structure: string[]
+  lessons: string[]
+  risks: string[]
+}
+
+/** POST /idea-inspiration request。 */
+export interface IdeaInspirationRequest {
+  idea: string
+  count?: number
+}
+
+/** 创意灵感结果：多方向开书灵感。 */
+export interface IdeaInspirationResult {
+  ideas: Array<{ title: string; hook: string; genre: string; pov: string; payoff: string }>
+}
+
+/** POST /director request。 */
+export interface DirectorRequest {
+  focus?: string
+}
+
+/** 自动导演编排建议（下一卷/阶段编排 + 修复再平衡）。 */
+export interface DirectorAdvice {
+  summary: string
+  nextArc: string[]
+  pacing: string
+  risks: string[]
+  fixes: string[]
+}
+
+/** 自动导演「采纳」后生成的书内待办项。 */
+export interface DirectorTodo {
+  id: string
+  text: string
+  /** 来源：风险 或 修复。 */
+  source: 'risk' | 'fix'
+  done: boolean
+  createdAt: string
+}
+
+/** 题材雷达：单条市场信号。 */
+export interface MarketRadarSignal {
+  id: string
+  kind: 'genre' | 'protagonist' | 'advantage' | 'opening' | 'relationship' | 'title_pattern' | 'opportunity' | 'crowding'
+  title: string
+  detail: string
+  /** 趋势：current / rising / stable / falling。 */
+  direction?: 'current' | 'rising' | 'stable' | 'falling'
+  /** 是否建议优先考虑。 */
+  recommended?: boolean
+}
+
+/** 题材雷达：生产底座（引用内置题材/推进模式库，或给出新资产）。 */
+export interface ProductionFoundation {
+  genre: { existingId?: string; name: string; description: string; template?: string }
+  primaryStoryMode: { existingId?: string; name: string; driver: string; readerExpectation: string }
+  secondaryStoryMode?: { existingId?: string; name: string; driver: string; readerExpectation: string }
+}
+
+/** 题材雷达：开书创意简报（可执行，严禁照搬具体作品/命名）。 */
+export interface MarketCreativeBrief {
+  promptBlock: string
+  openingIdea: string
+  coreAdvantage: string
+  bookSellingPoint: string
+  first30ChapterPromise: string
+}
+
+/** 题材雷达结果。 */
+export interface MarketRadarResult {
+  signals: MarketRadarSignal[]
+  productionFoundation: ProductionFoundation
+  /** 开书创意简报（可选；用「用信号创作」接口单独生成）。 */
+  creativeBrief?: MarketCreativeBrief
+}
+
+/** POST /market-radar request。 */
+export interface MarketRadarRequest {
+  platform?: string
+  genre?: string
+  keywords?: string
+  feedText?: string
+  /** 已扫描的上榜记录（来自真实榜单抓取），用于让分析基于真实榜单证据。 */
+  candidates?: Array<{ title: string; author?: string; tags?: string[]; synopsis?: string; category?: string; heatLabel?: string }>
+}
+
+/** POST /market-radar/brief request：用选中的信号 + 影响模式生成开书创意。 */
+export interface MarketRadarBriefRequest {
+  influenceMode: 'follow_hot' | 'differentiate' | 'light'
+  signals: MarketRadarSignal[]
 }
 
 /** A character card from the story bible. */
@@ -264,6 +580,175 @@ export interface StoryBible {
 }
 
 /** A planted/active/resolved foreshadowing thread. */
+/** 修订建议来源：审稿 / 时间线 / 张力。 */
+export type RevisionSource = 'review' | 'timeline' | 'tension'
+
+/** 一条待修订条目（合并层排序后的最小单位）。 */
+export interface RevisionItem {
+  /** 稳定 id（source:chapter:index）。 */
+  id: string
+  source: RevisionSource
+  severity: Severity
+  /** 归属章节号（0 = 全书级）。 */
+  chapterNo: number
+  item: string
+  suggestion: string
+  /** 去重时合并掉的同类条数（>=2 时展示）。 */
+  count?: number
+}
+
+/** POST /revision/plan 请求：把该章三类建议合并成一份修订指令。 */
+export interface RevisionPlanRequest {
+  op: 'plan'
+  chapterNo?: number
+  /** 显式指定的审稿意见（面板勾选后传入；缺省取已落盘报告）。 */
+  reviewIssues?: ReviewIssue[]
+  includeTimeline?: boolean
+  includeTension?: boolean
+  bookId?: string
+}
+
+/** POST /revision/plan 响应。 */
+export interface RevisionPlanResponse {
+  chapterNo: number
+  items: RevisionItem[]
+  /** 唯一修订指令（面板直接把它交给 /rewrite）。 */
+  instruction: string
+  counts: Record<RevisionSource, number>
+  /** 因上限被截断的条数。 */
+  omitted: number
+  /** 验证基准（复核时逐条核对本轮下发的全部条目）。 */
+  baseline: ReviewReport
+  /** 一行摘要。 */
+  summary: string
+}
+
+/**
+ * 张力曲线形状预设：
+ * `escalation` 递进爬升 / `suspense` 悬疑加压 / `wave` 波浪呼吸 /
+ * `frontLoad` 前紧后稳 / `flat` 平稳推进 / `custom` 自定义。
+ */
+export type TensionCurvePreset = 'escalation' | 'suspense' | 'wave' | 'frontLoad' | 'flat' | 'custom'
+
+/** 张力曲线配置（随项目保存）。 */
+export interface TensionCurveConfig {
+  preset: TensionCurvePreset
+  /** preset=custom 时的逐章采样（0-100；缺省按章节数取默认值）。 */
+  custom?: number[]
+}
+
+/** 张力曲线的一条问题（实际 vs 目标 / 曲线形状）。 */
+export interface TensionIssue {
+  severity: 'high' | 'medium' | 'low'
+  chapters: number[]
+  item: string
+  suggestion: string
+}
+
+/** 张力曲线数据点（面板绘图用）。 */
+export interface TensionCurvePoint {
+  no: number
+  title: string
+  /** 目标张力。 */
+  target?: number
+  /** 实际张力（审稿打分）。 */
+  actual?: number
+  /** 参考曲线在此处的取值。 */
+  reference?: number
+}
+
+/** GET /tension 响应。 */
+export interface TensionResponse {
+  preset: TensionCurvePreset
+  points: TensionCurvePoint[]
+  /** 规则核对发现的问题。 */
+  issues: TensionIssue[]
+}
+
+/** POST /tension 请求。 */
+export interface TensionRequest {
+  op: 'preset' | 'set' | 'clear'
+  preset?: TensionCurvePreset
+  chapterNo?: number
+  /** op=set 时的目标张力（0-100）。 */
+  tension?: number
+}
+
+/** 允许作者编辑的提示词槽位 id（白名单）。 */
+export type PromptSlotId = 'styleExtra' | 'antiAiExtra' | 'dialogueExtra' | 'endingHookExtra'
+
+/** 一个提示词槽位的当前内容。 */
+export interface PromptSlotState {
+  id: PromptSlotId
+  label: string
+  hint: string
+  placeholder: string
+  maxChars: number
+  value: string
+}
+
+/** GET /prompt-slots 响应。 */
+export interface PromptSlotsResponse {
+  slots: PromptSlotState[]
+}
+
+/** POST /prompt-slots 请求：设置或清空一个槽位。 */
+export interface PromptSlotsRequest {
+  id: PromptSlotId
+  /** 空串 = 清空该槽位（恢复默认）。 */
+  value: string
+}
+
+/**
+ * 故事时间线事件：从章节正文抽取的「故事内时间点 + 地点 + 参与角色 + 事件」。
+ * 用途：后续章节的时间连续性与地点衔接（比编年录更强调"顺序"）。
+ */
+export interface TimelineEvent {
+  /** 稳定 id（时间线内唯一）。 */
+  id: string
+  /** 所属章节号。 */
+  chapterNo: number
+  /** 故事内时间点（如「第三日黄昏」「入宗三个月后」「同日夜」）。 */
+  time: string
+  /** 相对顺序（同书内递增；无法判断时缺省）。用于检测时间倒流。 */
+  order?: number
+  /** 地点。 */
+  place: string
+  /** 参与角色（角色名）。 */
+  characters: string[]
+  /** 事件一句话。 */
+  event: string
+  /** 来源：模型抽取 / 作者手改。 */
+  source: 'extracted' | 'manual'
+  createdAt: string
+}
+
+/** 时间线矛盾（规则初筛 + AI 复核）。 */
+export interface TimelineIssue {
+  severity: 'high' | 'medium' | 'low'
+  /** 定位到的章节（可多个）。 */
+  chapters: number[]
+  /** 问题描述。 */
+  item: string
+  /** 建议修法。 */
+  suggestion: string
+}
+
+/** GET /timeline 响应。 */
+export interface TimelineResponse {
+  events: TimelineEvent[]
+  /** 规则初筛发现的问题（瞬时计算，不落盘）。 */
+  issues?: TimelineIssue[]
+}
+
+/** POST /timeline 请求：op=extract 抽单章 / check 全量检查 / update 手改 / remove 删除 / clear 清空。 */
+export interface TimelineRequest {
+  op: 'extract' | 'check' | 'update' | 'remove' | 'clear'
+  chapterNo?: number
+  event?: TimelineEvent
+  id?: string
+}
+
 export interface Foreshadow {
   /** Stable id. */
   id: string
@@ -305,6 +790,8 @@ export interface AuditResponse {
   auditedChapters: number
   /** 质检时间。 */
   auditedAt: string
+  /** 本次质检使用的模型（auditModel 或全局 model）。 */
+  model?: string
 }
 
 /** 全书质检的实时状态（通过 /status 暴露给面板/外部读取）。 */
@@ -376,7 +863,7 @@ export interface PlotlineHealthReport {
   }>
 }
 
-/** AI 剧情方案：下一阶段目标 + 建议新线。 */
+/** 剧情方案：下一阶段目标 + 建议新线。 */
 export interface PlotlinePlan {
   /** 下一阶段（未来 5-10 章）剧情方向。 */
   direction: string
@@ -387,7 +874,7 @@ export interface PlotlinePlan {
 /** POST /plotlines 响应。 */
 export interface PlotlinesResponse {
   plotlines: Plotline[]
-  /** op=suggest 时的 AI 建议候选线。 */
+  /** op=suggest 时的 建议候选线。 */
   suggestions?: Plotline[]
   /** op=health 时的健康检查报告。 */
   health?: PlotlineHealthReport
@@ -508,7 +995,7 @@ export interface RoleStatusCard {
   appearances: number
 }
 
-/** 角色库条目（主表：作者维护 + AI 提炼 + 编年录自动聚合）。 */
+/** 角色库条目（主表：作者维护 + 提炼 + 编年录自动聚合）。 */
 export interface RoleRecord {
   /** 角色名（唯一键）。 */
   name: string
@@ -528,122 +1015,33 @@ export interface RoleRecord {
   knowledge: string[]
   /** 首次出场章节（编年录聚合，可手动修正）。 */
   firstChapter?: number
-  /** 动漫形象描述词（AI 绘图用：中文描述 + 英文标签 + 关键外貌标签）。 */
-  imagePrompt?: {
-    /** 中文外貌描述：连贯一段（发色/瞳色/服装/气质/标志物）。 */
-    zh: string
-    /** 英文绘图标签：booru 风格逗号分隔。 */
-    en: string
-    /** 中文关键标签（发色/瞳色/服装/气质/标志物）。 */
-    tags: string[]
-    /** 依据来源说明（哪几章哪些描写）。 */
-    source?: string
-  }
-  /** 角色参考图（dataURL 或 URL）。用于漫画/漫剧出图时锁定角色一致性。 */
-  imageUrl?: string
-  /** 角色图集（图像锚点）：立绘/四视图/表情/场景/细节等，label 标注用途。 */
-  gallery?: RoleImage[]
-  /** 该角色所需的情绪表情清单（提炼时 LLM 补全 6-12 个，如"疲惫/麻木/压抑悲伤"）。 */
-  expressions?: string[]
-  /** LLM 精修的四类生图提示词包（前端拼装版之外的高质量版，promptKit 接口生成）。 */
-  promptKit?: {
-    /** 立绘：全身/半身正视图。 */
-    portrait: { zh: string; en: string }
-    /** 四视图：正面/侧面/背面设定表。 */
-    sheet: { zh: string; en: string }
-    /** 表情：同一脸部锚换情绪，每表情一段。 */
-    expressions: { name: string; zh: string; en: string }[]
-    /** 细节：标志物局部特写。 */
-    details: { zh: string; en: string }
-  }
-  /** 漫画/漫剧重要性：main=必须建卡保证一致；support=有锚点即可；extra=路人随机生成不约束。 */
-  importance?: 'main' | 'support' | 'extra'
 }
 
-/** 角色图集条目：一张已定型的角色图（图像锚点）。 */
-export interface RoleImage {
-  /** 用途标签：立绘 / 四视图 / 表情-疲惫 / 场景 / 细节 等。 */
-  label: string
-  /** dataURL 或 URL。 */
-  dataUrl: string
-}
-
-/** 场景库条目：从正文提炼的「镜头场景」视觉锚点（漫剧分镜/生图用）。 */
-export interface SceneCard {
-  /** 场景名（唯一键），如「旧茶渡·地下石殿」。 */
-  name: string
-  /** 一句话定位：空间/氛围/功能。 */
-  summary: string
-  /** 幕归属：第一幕·后场 / 第二幕·卖场 / …（便于按剧情段落组织）。 */
-  act?: string
-  /** 时间光态：夜间闭店后 / 雨夜 / 凌晨 / 频闪灯… */
-  moment?: string
-  /** 关键情节镜头 1-3 条：该场景拍什么（人物动作+情绪+镜头推进）。 */
-  beats?: string[]
-  /** 人物在场状态：主角/关键角色在该场景的状态一句话。 */
-  characterState?: string
-  /** 环境构成：空间结构/陈设/标志物。 */
-  elements: string[]
-  /** 色调与光影（含 HEX 色板，可空）。 */
-  palette: string[]
-  /** 氛围关键词：压抑/神秘/空旷… */
-  moods: string[]
-  /** 中文生图提示词（连贯一段，写实电影感）。 */
-  zh: string
-  /** 英文生图提示词（逗号分隔标签）。 */
-  en: string
-  /** 关键标签。 */
-  tags: string[]
-  /** 依据来源（哪几章哪些描写）。 */
-  source?: string
-  /** 场景图集（图像锚点）：全景/局部/氛围 等。 */
-  gallery?: RoleImage[]
-}
-
-/** POST /scenes 请求：场景库提炼 / 采纳 / 更新 / 删除 / 图集。 */
-export interface ScenesRequest {
-  op: 'extract' | 'adopt' | 'update' | 'remove' | 'image' | 'removeImage'
-  /** adopt / update 时传入的场景卡（adopt 可修改后采纳）。 */
-  scene?: SceneCard
-  /** remove / image 时的场景名。 */
+/** POST /roles 请求：角色库增删改 + 提炼 + 参考图上传。 */
+export interface RolesRequest {
+  op: 'extract' | 'adopt' | 'update' | 'remove'
+  /** adopt / update 时传入的角色（adopt 可修改后采纳）。 */
+  role?: RoleRecord
+  /** remove 时的角色名。 */
   name?: string
-  /** op='image' 时的图片 dataURL 与用途标签（全景/局部/氛围）。 */
-  dataUrl?: string
-  label?: string
 }
 
-/** POST /visual-rules 请求：视觉世界观规则提炼 / 保存。 */
-export interface VisualRulesRequest {
-  op: 'extract' | 'save'
-  /** op=save 时的规则数组。 */
-  rules?: string[]
-}
 
-/** POST /visual-rules 响应。 */
-export interface VisualRulesResponse {
-  rules: string[]
-}
-
-/** POST /scenes 响应。 */
-export interface ScenesResponse {
-  scenes: SceneCard[]
-  /** op=extract 时的 AI 候选场景。 */
-  candidates?: SceneCard[]
+/** POST /llm-test 请求：对选中的提供商/模型发一次最小真实调用。 */
+export interface LlmTestRequest {
+  provider: string
+  model: string
 }
 
-/** POST /roles 请求：角色库增删改 + AI 提炼 + 参考图上传。 */
-export interface RolesRequest {
-  op: 'extract' | 'adopt' | 'update' | 'remove' | 'visual' | 'image' | 'removeImage' | 'imageGenerate' | 'promptKit'
-  /** adopt / update 时传入的角色（adopt 可修改后采纳）。 */
-  role?: RoleRecord
-  /** remove 时的角色名。 */
-  name?: string
-  /** op='image' 时的参考图 dataURL。 */
-  dataUrl?: string
-  /** op='image' 时的图集用途标签（立绘/四视图/表情-x/场景/细节）；缺省视为角色参考图（imageUrl）。 */
-  label?: string
-  /** op='imageGenerate' 时的漫画风格预设 id（用于统一角色图与漫画页风格）。 */
-  style?: string
+/** POST /llm-test 响应。 */
+export interface LlmTestResponse {
+  ok: boolean
+  /** 连通延迟（毫秒）。 */
+  ms?: number
+  /** 失败原因（已映射为人话）。 */
+  message?: string
+  /** 稳定错误码（LlmError code），便于排查。 */
+  code?: string
 }
 
 /** POST /roles 响应。 */
@@ -651,15 +1049,9 @@ export interface RolesResponse {
   roles: RoleRecord[]
   /** op=extract 时的 AI 候选角色。 */
   candidates?: RoleRecord[]
-  /** op=visual 时的动漫形象描述词（已写入角色卡）。 */
-  visual?: RoleRecord['imagePrompt']
-  /** op=promptKit 时的四类提示词精修包（已写入角色卡）。 */
-  promptKit?: RoleRecord['promptKit']
-  /** op=image 时的角色参考图 dataURL。 */
-  imageUrl?: string
 }
 
-/** POST /bible/patch 请求：局部修补设定圣经。 */
+/** POST /bible/patch 请求：局部修补道藏。 */
 export interface BiblePatchRequest {
   worldRules?: string[]
   redLines?: string[]
@@ -668,10 +1060,10 @@ export interface BiblePatchRequest {
   characters?: CharacterCard[]
 }
 
-/** POST /blurb 请求：AI 生成/补全或手动保存小说简介。 */
+/** POST /blurb 请求：生成/补全或手动保存小说简介。 */
 export interface BlurbRequest {
   action: 'generate' | 'save'
-  /** 已写好的开头（AI 补全时使用；留空 = 全量生成）。 */
+  /** 已写好的开头（补全时使用；留空 = 全量生成）。 */
   partial?: string
   /** 手动保存的完整简介（action=save 时）。 */
   text?: string
@@ -743,7 +1135,7 @@ export interface WorldState {
   factions: WorldFaction[]
 }
 
-/** POST /world 请求：AI 提炼或手动保存。 */
+/** POST /world 请求：提炼或手动保存。 */
 export interface WorldRequest {
   action: 'generate' | 'save'
   /** action=save 时的完整世界数据。 */
@@ -775,31 +1167,172 @@ export interface ProjectState {
   assets?: ProjectAssets
   /** 事实库/时间线：每章生成后抽取，注入后续章节保持一致性。 */
   facts?: ChapterFact[]
-  /** 小说简介（面向读者的作品门面，AI 生成或手动保存）。 */
+  /** 书内知识库文档（可检索资料/设定/参考）。 */
+  knowledgeDocs?: KnowledgeDoc[]
+  /** 自动导演待办：风险/修复「采纳」后生成的随手清单。 */
+  todos?: DirectorTodo[]
+  /** 小说简介（面向读者的作品门面，生成或手动保存）。 */
   blurb?: string
+  /** 开书定盘：书籍级承诺与流派定位（前30章承诺/主副模式/文风/平台）。 */
+  bookContract?: BookContract
   /** 封面文件名（相对输出目录，如 cover.png）。 */
   coverPath?: string
   /** 大世界结构化数据（境界体系/区域/势力）。 */
   world?: WorldState
   /** 剧情线（主线/支线/人物线/悬念线）。 */
   plotlines?: Plotline[]
-  /** 角色库（作者维护 + AI 提炼的主表）。 */
+  /** 角色库（作者维护 + 提炼的主表）。 */
   roles?: RoleRecord[]
-  /** 场景库（作者维护 + AI 提炼的主表）。 */
-  scenes?: SceneCard[]
-  /** 视觉世界观规则（生图/生视频必须遵守，从道藏提炼，注入所有提示词）。 */
-  visualRules?: string[]
   /** 人物志：角色当前状态聚合结果（从编年录刷新后存档，打开页面直接显示）。 */
   roleStatus?: RoleStatusCard[]
-  /** 漫剧分镜结果缓存：章号 → 分镜（持久化，刷新不丢）。 */
-  /** 漫剧分集计划缓存：卷号/0=全书 → 分集计划（持久化，刷新不丢）。 */
-  /** 漫画脚本缓存：章号 → 漫画脚本（持久化，刷新不丢）。 */
+  /** 故事时间线（逐章抽取：时间点 / 地点 / 参与角色 / 事件）。 */
+  timeline?: TimelineEvent[]
+  /** 张力曲线配置（形状预设 + 自定义采样）。 */
+  tensionCurve?: TensionCurveConfig
+  /** 作者自定义的提示词槽位（白名单见 prompt-slots.ts）。 */
+  promptSlots?: Partial<Record<PromptSlotId, string>>
+  /** 本书参数（写作/审稿/推理/模型快切；未设字段回退全局 config）。 */
+  bookSettings?: BookSettings
   /** ISO timestamps. */
   createdAt: string
   updatedAt: string
 }
 
-/** Runtime config surface exposed to the panel (subset of plugin Config). */
+/** 本书参数（存 novel-project.json.bookSettings；未设字段回退全局 config）。 */
+export interface BookSettings {
+  /** 本书使用的提供方路由（快切器写入）。 */
+  provider?: string
+  /** 本书使用的主模型 id。 */
+  model?: string
+  /** 本书写作推理档位。 */
+  reasoningEffort?: 'off' | 'low' | 'high' | 'max'
+  /** 本书分析类任务推理档位。 */
+  analysisReasoning?: 'off' | 'low' | 'high' | 'max'
+  /** 本书每章目标字数。 */
+  chapterChars?: number
+  /** 本书单章最大输出 tokens。 */
+  maxTokens?: number
+  /** 本书审稿通过分。 */
+  reviewPassScore?: number
+  /** 本书是否写完自动审稿。 */
+  autoReview?: boolean
+  /** 本书是否自动作者复盘。 */
+  autoAuthorReview?: boolean
+  /** 本书是否修稿后自动复审。 */
+  autoReviewAfterRevise?: boolean
+}
+
+/** 手动添加的模型库条目（只存插件内，不改 DSH 全局）。 */
+export interface SavedModel {
+  /** 唯一 id（前端生成的短 id）。 */
+  id: string
+  /** 展示名（可为空，回退到 model）。 */
+  name: string
+  /** DSH 提供商路由（如 zai-coding-cn）。 */
+  provider: string
+  /** 模型 id（如 glm-5.3-flash）。 */
+  model: string
+}
+
+/** DSH 模型添加：厂商预设（选择厂商，直接填 API Key）。 */
+export interface LlmVendor {
+  id: string
+  name: string
+  /** 该厂商对应的 provider 路由。 */
+  route: string
+  /** DSH 凭据引用名（写入 .credentials.yaml 的 refs）。 */
+  apiKeyEnv: string
+  /** 默认模型 id。 */
+  defaultModel: string
+  /** 建议可选模型 id 列表（下拉 data-list 用）。 */
+  models: string[]
+  /** 内置适配器（如 deepseek-official），无需注册 pi-ai 路由。 */
+  builtin?: boolean
+}
+
+/** 预置的常见厂商（id=provider 路由；添加模型下拉兜底用，其余厂商由运行时目录动态补充）。 */
+export const LLM_VENDORS: LlmVendor[] = [
+  // 注意：本列表只是「运行时目录不可用」时的兜底建议值；实际以 ctx.llm.listModels() 为准
+  // （见 engine.ts listLlmVendors），避免 DSH 侧模型改名后这里的条目过期。
+  { id: 'deepseek-official', name: 'DeepSeek', route: 'deepseek-official', apiKeyEnv: 'DEEPSEEK_API_KEY', defaultModel: 'deepseek-flash', models: ['deepseek-flash', 'deepseek-v4-pro'], builtin: true },
+  { id: 'zai-coding-cn', name: '智谱 GLM', route: 'zai-coding-cn', apiKeyEnv: 'ZAI_CODING_CN_API_KEY', defaultModel: 'glm-5.3-flash', models: ['glm-4.5-air', 'glm-4.7', 'glm-5-turbo', 'glm-5.1', 'glm-5.2', 'glm-5.3', 'glm-5.3-flash', 'glm-5v-turbo'] },
+  { id: 'qwen-token-plan-cn', name: '千问百炼', route: 'qwen-token-plan-cn', apiKeyEnv: 'QWEN_TOKEN_PLAN_CN_API_KEY', defaultModel: 'qwen3.7-max', models: ['qwen3.6-flash', 'qwen3.6-plus', 'qwen3.7-max', 'qwen3.7-plus', 'qwen3.8-max', 'qwen3.8-max-preview'] },
+  { id: 'openrouter', name: 'OpenRouter', route: 'openrouter', apiKeyEnv: 'OPENROUTER_API_KEY', defaultModel: 'z-ai/glm-5.3-flash', models: ['z-ai/glm-4.6', 'z-ai/glm-4.7', 'z-ai/glm-5', 'z-ai/glm-5-turbo', 'z-ai/glm-5.1', 'z-ai/glm-5.2', 'z-ai/glm-5.3-flash', 'auto', 'deepseek/deepseek-v4-flash', 'anthropic/claude-sonnet-4.6'] },
+]
+
+/** 运行时厂商目录的一项（添加到模型下拉；由 DSH 的 pi-ai 可配置提供方动态生成）。 */
+export interface LlmVendorOption {
+  /** provider 路由 id（也是厂商下拉的值）。 */
+  id: string
+  /** 展示名。 */
+  name: string
+  /** 建议模型 id（可为空，用户手填）。 */
+  models: string[]
+  /** 已知 DSH 凭据引用名；为空时 host 生成 `PI_AI_<ID>_API_KEY`。 */
+  apiKeyEnv?: string
+  /** 内置适配器（只写凭据，不注册 pi-ai 路由）。 */
+  builtin?: boolean
+}
+
+/** GET /llm-vendors 响应。 */
+export interface LlmVendorsResponse {
+  vendors: LlmVendorOption[]
+}
+
+/** /llm-models 里的一条模型。 */
+export interface LlmModelOption { id: string; name: string }
+
+/** GET /llm-models?provider=x 响应。 */
+export interface LlmModelsResponse {
+  models: LlmModelOption[]
+}
+
+/** GET /llm-providers 响应：当前已注册的提供方路由。 */
+export interface LlmProvidersResponse {
+  providers: { id: string; name: string }[]
+}
+
+/** POST /llm-remove 请求：移除一个提供方（unset key + 移除 llm-pi-ai 路由）。 */
+export interface RemoveProviderRequest {
+  provider: string
+  /** 该提供方对应的 DSH 凭据引用名（用于 unset）。 */
+  apiKeyEnv?: string
+}
+
+/** POST /llm-remove 响应。 */
+export interface RemoveProviderResponse {
+  ok: boolean
+  message?: string
+}
+
+/** POST /llm-add 请求：添加一个模型（厂商直填 key，或自定义路由）。 */
+export interface AddModelRequest {
+  mode: 'vendor' | 'custom'
+  /** 厂商模式用：provider 路由 id（来自 /llm-vendors）。 */
+  vendor?: string
+  /** 厂商已知的 DSH 凭据引用名（可选；为空时 host 生成）。 */
+  apiKeyEnv?: string
+  /** 自定义模式用：provider 路由 id。 */
+  provider?: string
+  /** 模型 id。 */
+  model: string
+  /** API Key。 */
+  apiKey: string
+  /** 展示名（可选）。 */
+  name?: string
+  /** 自定义模式用：OpenAI 兼容 base URL。 */
+  baseURL?: string
+}
+
+/** POST /llm-add 响应。 */
+export interface AddModelResponse {
+  ok: boolean
+  saved: SavedModel
+  provider: string
+  message?: string
+}
+
+/** 手动添加的模型库条目（只存插件内，不改 DSH 全局）。 */
 export interface NovelConfig {
   /** Absolute path of the default docx outline to load. */
   outlinePath: string
@@ -807,10 +1340,25 @@ export interface NovelConfig {
   outputDir: string
   /** LLM provider route (e.g. deepseek-official). */
   provider: string
-  /** LLM model id (e.g. deepseek-v4-flash). */
+  /** LLM model id (e.g. deepseek-flash). */
   model: string
+  /** 生成正文用模型（缺省用 model）。 */
+  generateModel?: string
+  /** 审稿用模型（缺省用 model；建议用更强的 reasoner/pro）。 */
+  reviewModel?: string
+  /** 全书质检(审计)用模型（缺省用 model）。 */
+  auditModel?: string
+  /**
+   * 备用模型：主模型调用失败（网络/限流/额度/服务不可用）时自动切换重试一次。
+   * 留空表示不切换。批量连写时能显著减少"整批中断"。
+   */
+  fallbackModel?: string
+  /** 是否在出章后自动抽取故事时间线（失败不阻断出章）。默认开。 */
+  autoTimeline?: boolean
   /** LLM reasoning effort: off = no thinking; low/high/max = thinking intensity. */
   reasoningEffort: 'off' | 'low' | 'high' | 'max'
+  /** 分析类任务（提炼/拆书/反推大纲等）的推理档位；默认 low，不受上面写作档位影响。 */
+  analysisReasoning: 'off' | 'low' | 'high' | 'max'
   /** Target characters per chapter. */
   chapterChars: number
   /** Max output tokens per chapter call. */
@@ -823,15 +1371,192 @@ export interface NovelConfig {
   autoAuthorReview: boolean
   /** 修订/润色产出草稿后是否自动附带一次 AI 审查（工作区显示新稿评分与剩余问题）。 */
   autoReviewAfterRevise: boolean
-  /** 豆包/Seedream 生图 API Key（保存在服务端配置，不暴露给前端明文回显）。 */
-  imageApiKey?: string
-  /** 豆包/Seedream 生图模型 ID（如 doubao-seedream-5-0-pro-260628）。 */
-  imageApiModel?: string
-  /** 是否启用豆包生图（默认关，避免误调用付费 API）。 */
-  imageApiEnabled?: boolean
+  /** 自定义背景图（URL 或 dataURL 或服务端路径引用；空 = 使用主题默认背景）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80（0 = 不遮罩）。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样，越小越透，新拟态/黏土可见背景图）。 */
+  themeOpacity?: number
+  /** 是否启用改编模式（默认关闭；发布后开启）。 */
+  enableAdaptMode?: boolean
+  /** 手动添加的模型库（「我的模型」条目；只存插件内）。 */
+  savedModels?: SavedModel[]
+}
+
+/** POST /move-output-dir request：dryRun=true 仅预览；确认时须带 to。 */
+export interface MoveOutputDirRequest {
+  /** 新输出目录（绝对路径）。 */
+  to?: string
+  /** 只列出当前目录内容，不搬移。 */
+  dryRun?: boolean
+}
+
+/** POST /move-output-dir response。 */
+export interface MoveOutputDirResponse {
+  from: string
+  to?: string
+  /** 当前（或迁移后）目录内容清单。 */
+  files: string[]
+  bytes: number
+  /** 联动重指向的书架条目数。 */
+  movedBooks: number
+  /** settings 默认输出目录是否同步更新。 */
+  defaultUpdated: boolean
+}
+
+/** POST /book-settings request：patch 省略 = 读取；字段传 null = 删除本书覆盖（回退全局）。 */
+export interface BookSettingsRequest {
+  patch?: { [K in keyof BookSettings]?: BookSettings[K] | null }
+}
+
+/** POST /book-settings response。 */
+export interface BookSettingsResponse {
+  /** 本书已设置的参数（未设字段缺省 = 回退全局）。 */
+  settings: BookSettings
+  /** 应用回退链后的生效配置（全局 + 本书覆盖）。 */
+  effective: NovelConfig
+  /** 当前是否有打开的书。 */
+  hasBook: boolean
 }
 
 /** GET /status response. */
+/**
+ * 创作阶段契约（宿主计算的「当前阶段 → 本轮允许的动作」）。
+ * 计算逻辑在 stage-contract.ts；这里是宿主与面板/助手共享的线上形状。
+ */
+export interface StageInfo {
+  /** 阶段标识。 */
+  id: 'outline' | 'bible' | 'plan' | 'write' | 'wait' | 'review' | 'revise' | 'export'
+  /** 中文阶段名。 */
+  label: string
+  /** 建议的下一步动作（助手工具名；无对应工具时为空数组）。 */
+  recommend: string[]
+  /** 本阶段允许的写操作（作者只说了「继续」时的唯一命令集）。 */
+  allow: string[]
+  /** 为什么处于该阶段。 */
+  reason: string
+}
+
+// ------------------------------------------------------------ LLM 实况 / 用量
+
+/** 单次 LLM 调用的 token 用量（来自 dsh-llm 的 usage chunk）。 */
+export interface LlmTokenUsage {
+  inputTokens: number
+  outputTokens: number
+  /** 供应商给出的总用量（缺失时由输入+输出推导）。 */
+  totalTokens?: number
+  /** 思考（reasoning）通道用量。 */
+  reasoningTokens?: number
+  /** 命中缓存的输入用量。 */
+  cacheReadTokens?: number
+}
+
+/** LLM 实况帧：宿主 → 浏览器的 SSE 事件（每次调用一组 session_* 事件）。 */
+export interface LlmLiveFrame {
+  type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed'
+  /** 宿主生成，形如 ll-<base36>-<n>。 */
+  sessionId: string
+  /** 本次调用用途（如 正文生成/审稿/章节规划）。 */
+  label?: string
+  /** 使用模型。 */
+  model?: string
+  /** 事件时间（ISO）。 */
+  at: string
+  /** session_started：交互上下文。 */
+  context?: { taskId?: string; interactionId: string }
+  /** output_delta / reasoning_delta：本次增量文本。 */
+  content?: string
+  /** session 累计字符数。 */
+  totalChars?: number
+  /** reasoning 累计字符数。 */
+  totalReasoningChars?: number
+  /** phase_changed：新阶段。 */
+  phase?: 'requesting' | 'streaming' | 'completed' | 'failed'
+  /** phase_changed：阶段描述。 */
+  phaseMessage?: string
+  /** session_completed：最终预览（截断）。 */
+  preview?: string
+  /** session_completed：失败信息。 */
+  error?: string
+  /** session_completed：本次用量（供应商未上报时缺省）。 */
+  usage?: LlmTokenUsage
+  /** session_completed：本次调用耗时（毫秒）。 */
+  elapsedMs?: number
+  /** session_completed：首字耗时（毫秒；未拿到文本时缺省）。 */
+  firstTokenMs?: number
+  /** session_started：是否已记录可查看的 Prompt（面板据此显示「查看 Prompt」）。 */
+  hasPrompt?: boolean
+  /** session_started：Prompt 字符数（system + user）。 */
+  promptChars?: number
+}
+
+/** 按用途分组的用量。 */
+export interface LlmUsageBucket {
+  label: string
+  calls: number
+  failed: number
+  inputTokens: number
+  outputTokens: number
+  reasoningTokens: number
+  elapsedMs: number
+}
+
+/** 本次运行（进程内，重启归零）的 LLM 用量汇总。 */
+export interface LlmUsageSummary {
+  calls: number
+  failed: number
+  inputTokens: number
+  outputTokens: number
+  reasoningTokens: number
+  totalTokens: number
+  elapsedMs: number
+  /** 供应商未上报 usage 的调用次数（用于说明数据为何不完整）。 */
+  callsWithoutUsage: number
+  byLabel: LlmUsageBucket[]
+}
+
+/** 一次调用的 Prompt 记录（供面板查看「实际发送了什么」）。 */
+export interface LlmPromptRecord {
+  sessionId: string
+  label?: string
+  model?: string
+  at: string
+  system?: string
+  user?: string
+  /** system + user 的字符数（记录被截断时仍给出原始长度）。 */
+  chars: number
+  /** 记录本身是否被截断。 */
+  truncated?: boolean
+}
+
+/** 章节历史版本（快照）：覆盖写入前自动留存，可回滚。 */
+export interface ChapterSnapshot {
+  id: string
+  chapterNo: number
+  /** 快照文件（相对书目录）。 */
+  file: string
+  /** 留存原因（生成覆盖 / 采纳草稿 / 修订 / 手工）。 */
+  reason: string
+  chars: number
+  at: string
+}
+
+/** GET /snapshot 响应。 */
+export interface SnapshotResponse {
+  snapshots: ChapterSnapshot[]
+  /** 快照占用字节数。 */
+  bytes: number
+}
+
+/** POST /snapshot 请求：op=create 手工存档 / restore 回滚 / remove 删除 / prune 只留最近 N 个。 */
+export interface SnapshotRequest {
+  op: 'create' | 'restore' | 'remove' | 'prune'
+  chapterNo?: number
+  id?: string
+  /** prune：每章保留数量。 */
+  keep?: number
+}
+
 export interface StatusResponse {
   config: NovelConfig
   /** The persisted project, when one exists in the output dir. */
@@ -840,11 +1565,26 @@ export interface StatusResponse {
   generatedFiles: string[]
   /** 全书质检实时状态（用于面板/外部读取进度）。 */
   audit?: AuditStatus
+  /** 宿主按项目真实状态算出的创作阶段（面板角标 / 外部自动化共用）。 */
+  stage?: StageInfo
+  /** 本次运行（进程内）的 LLM 用量汇总：调用次数 / 输入·输出·思考 token / 耗时。 */
+  usage?: LlmUsageSummary
+  /**
+   * 截断声明：本次响应中被裁掉的字段说明（如「编年录：共 320 条，仅返回最近 80 条」）。
+   * 消费方不得把缺失字段当作"不存在"，需要完整数据时走专用接口。
+   */
+  truncations?: string[]
 }
 
 /** 生产单状态（生产单 = 区间批量生产执行器：计划补足 + 逐章生成 + 被拒分级处理）。 */
 export interface RunState {
   runId: string
+  /**
+   * 本批次归属的书名（可选，兼容旧 run-state.json）。
+   * 生产单是全局单实例，而 /run/status 恢复时会扫书架取第一个有 run-state 的目录，
+   * 因此"这是哪本书的批次"必须显式带上，否则芯片/面板只能显示一个无法归属的状态。
+   */
+  bookName?: string
   /** 区间起点（含）。 */
   startNo: number
   /** 区间终点（含）。 */
@@ -950,13 +1690,15 @@ export type JobFrame =
   | { type: 'start'; no: number; title: string }
   | { type: 'delta'; text: string }
   | { type: 'progress'; chars: number }
-  | { type: 'done'; no: number; file: string; chars: number; title: string }
+  | { type: 'done'; no: number; file: string; chars: number; title: string; warn?: string }
   | { type: 'review'; no: number; report: ReviewReport }
   | { type: 'author-review'; no: number; review: AuthorReview }
   | { type: 'author-backfill-done'; count: number }
   | { type: 'rewritten'; no: number; file: string; chars: number }
   /** 润色/重写完成，产物作为待确认草稿（尚未覆盖正文）。 */
   | { type: 'drafted'; no: number; chars: number; draft: string }
+  | { type: 'outline-progress'; done: number; total: number; phase: string }
+  | { type: 'outline-done'; outline: string; chars: number }
   | { type: 'error'; no: number; message: string }
 
 /** POST /review request: review one written chapter. */
@@ -1017,13 +1759,41 @@ export interface ChapterResponse {
 }
 
 /** POST /export request/response. */
+/**
+ * 导出范围：
+ * - `book`       整本正文（txt / md）
+ * - `settings`   项目设定（总纲 / 道藏 / 大世界 / 写作资产 / 卷首语）
+ * - `plan`       规划（卷计划 + 章节计划，含每章目标/要点/钩子/硬事实）
+ * - `characters` 角色（角色库 + 人物志当前状态）
+ * - `review`     质检记录（逐章审稿 + 作者复盘 + 伏笔/剧情线状态）
+ * - `project`    项目 JSON（完整状态，用于备份/迁移；仅 json 格式）
+ */
+export type ExportScope = 'book' | 'settings' | 'plan' | 'characters' | 'review' | 'project'
+
+/** 导出范围全集（宿主校验用；顺序即 UI 展示顺序）。 */
+export const EXPORT_SCOPE_VALUES: readonly ExportScope[] = ['book', 'settings', 'plan', 'characters', 'review', 'project']
+
+/** 导出范围的中文标签。 */
+export const EXPORT_SCOPE_LABELS: Record<ExportScope, string> = {
+  book: '整本正文',
+  settings: '项目设定',
+  plan: '规划（卷/章节）',
+  characters: '角色',
+  review: '质检记录',
+  project: '项目备份 JSON',
+}
+
 export interface ExportRequest {
-  format: 'txt' | 'md'
+  format: 'txt' | 'md' | 'json'
+  /** 缺省 `book`（兼容旧调用）。 */
+  scope?: ExportScope
 }
 export interface ExportResponse {
   file: string
   chars: number
   chapters: number
+  scope: ExportScope
+  format: 'txt' | 'md' | 'json'
 }
 
 /** POST /config request: patch any subset of the runtime config. */
@@ -1032,16 +1802,30 @@ export interface ConfigPatch {
   outputDir?: string
   provider?: string
   model?: string
+  generateModel?: string
+  reviewModel?: string
+  auditModel?: string
+  /** 备用模型（主模型失败时自动切换重试一次；空串 = 关闭）。 */
+  fallbackModel?: string
+  /** 出章后自动抽取故事时间线（默认开）。 */
+  autoTimeline?: boolean
   reasoningEffort?: 'off' | 'low' | 'high' | 'max'
+  analysisReasoning?: 'off' | 'low' | 'high' | 'max'
   chapterChars?: number
   maxTokens?: number
   reviewPassScore?: number
   autoReview?: boolean
   autoAuthorReview?: boolean
   autoReviewAfterRevise?: boolean
-  imageApiKey?: string
-  imageApiModel?: string
-  imageApiEnabled?: boolean
+  /** 自定义背景图（URL / dataURL / 服务端路径引用）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样）。 */
+  themeOpacity?: number
+  enableAdaptMode?: boolean
+  /** 手动添加的模型库（完整替换保存）。 */
+  savedModels?: SavedModel[]
 }
 
 // ------------------------------------------------------------ assistant
@@ -1068,6 +1852,8 @@ export type AssistantFrame =
   | { type: 'tool'; name: string; status: 'start' | 'done' | 'error'; detail?: string }
   /** Live output while a tool runs (e.g. chapter text being generated). */
   | { type: 'toolDelta'; name: string; text: string }
+  /** 工具完整结果（供前端渲染成结构化卡片，如拆书/导演）。 */
+  | { type: 'toolResult'; name: string; text: string }
   | { type: 'done' }
   | { type: 'error'; message: string }
 
@@ -1080,16 +1866,22 @@ export interface AssistantHistoryResponse {
 
 /** 题材基底库：一本书属于哪个阅读市场。树形（题材→子题材→下级）。 */
 export interface GenreNode {
+  /** 稳定标识（内置库交叉引用）。 */
+  id?: string
   /** 题材名称（标签，如「仙侠修真」「都市异能」）。 */
   name: string
   /** 题材特征、常见爽点、叙事重心或读者期待。 */
   description: string
+  /** 该题材的写法指引（开书定盘/卷计划用，区别于「读者期待」）。 */
+  template?: string
   /** 子题材。 */
   children: GenreNode[]
 }
 
 /** 推进模式库：读者为什么继续看下一章。 */
 export interface ProgressionMode {
+  /** 稳定标识（与内置库交叉引用）。 */
+  key?: string
   /** 模式名称（如「升级变强」「经营扩张」「解谜揭露」）。 */
   name: string
   /** 核心驱动力：靠什么制造追读动力。 */
@@ -1102,12 +1894,34 @@ export interface ProgressionMode {
   risks: string[]
   /** 主模式或辅助模式。 */
   primary: boolean
+  /** 该模式的写法指引（开书定盘/卷计划用）。 */
+  template?: string
+  /** 推进单位序列（每章如何推进，如「立威→打破质疑→扩大影响→碾压」）。 */
+  progressionUnits?: string[]
+  /** 允许出现的冲突形态。 */
+  allowedConflictForms?: string[]
+  /** 应避免的冲突形态（跑偏信号）。 */
+  forbiddenConflictForms?: string[]
+  /** 冲突烈度上限（low/medium/high），用于卷/章计划和审稿对齐。 */
+  conflictCeiling?: 'low' | 'medium' | 'high'
+  /** 单章推进单位说明。 */
+  chapterUnit?: string
+  /** 卷末应兑现的回报。 */
+  volumeReward?: string
+  /** 主驱动必须持续出现的信号（读者期待确认）。 */
+  mandatorySignals?: string[]
+  /** 反信号：出现即跑偏。 */
+  antiSignals?: string[]
+  /** 优先用的问题解决方式。 */
+  resolutionStyle?: string
 }
 
 /** 反 AI 规则：一条「要避免的问题 + 修正方向」。 */
 export interface AntiAiRule {
   /** 规则名（如「禁止解释型心理描写」「AI 高频套话」）。 */
   name: string
+  /** 稳定标识（与 defaultAntiAiRuleKeys 交叉引用；缺省用 name）。 */
+  key?: string
   /** 要避免的表达问题，具体可检查。 */
   avoid: string
   /** 推荐修正方向。 */
@@ -1116,9 +1930,60 @@ export interface AntiAiRule {
   detectPatterns?: string[]
   /** 是否内置全局规则（内置规则随插件发布，项目规则为用户自定义）。 */
   builtin?: boolean
+  /** 规则类别：forbidden=禁止类（命中即问题）/ risk=风险类（需注意但不硬伤）/ encourage=鼓励类（不命中不算错，只作建议）。 */
+  severity?: 'forbidden' | 'risk' | 'encourage'
+  /** 问题严重度（用于审稿优先级；缺省按类别推断）。 */
+  riskLevel?: 'low' | 'medium' | 'high'
+  /** 生成时直接注入的约束指令（缺失时回退到 avoid）。 */
+  promptInstruction?: string
+  /** 是否允许自动改写（risk 类通常 false）。 */
+  autoRewrite?: boolean
+  /** 是否为全局基线规则（新书默认启用，防止规则丢失后降级）。 */
+  globalBaselineEnabled?: boolean
+  /** 是否启用（缺省 true）。 */
+  enabled?: boolean
+  /** 作用域（缺省 all）。 */
+  scope?: Array<'writing' | 'review' | 'polish' | 'all'>
+}
+
+/** 预置叙事风格模板（一键绑定无需样本文本）。 */
+export interface StyleTemplateNarrativeRules {
+  progressionMode?: string
+  sceneUnitPattern?: string[]
+  multiPov?: boolean
+  looping?: boolean
+  endingStyle?: string
+  povSwitchStyle?: string
+  summary?: string
+}
+
+export interface StyleTemplateCharacterRules {
+  allowSelfReflection?: boolean
+  emotionExpression?: string
+  defenseMechanisms?: string[]
+  facePriority?: boolean
+  dialogueStyle?: string
+  summary?: string
+}
+
+export interface StyleTemplateLanguageRules {
+  register?: string
+  roughness?: number
+  allowIncompleteSentences?: boolean
+  allowSwearing?: boolean
+  sentenceVariation?: string
+  allowUselessDetails?: boolean
+  summary?: string
+}
+
+export interface StyleTemplateRhythmRules {
+  pace?: string
+  paragraphDensity?: string
+  allowFragmentedFlow?: boolean
+  actionOverExplanation?: boolean
+  summary?: string
 }
 
-/** 预置写法模板（来自 AI-Novel-Writing-Assistant 内置数据，一键绑定无需样本文本）。 */
 export interface StyleTemplate {
   /** 模板 key（如 power-up-escalation）。 */
   key: string
@@ -1130,18 +1995,66 @@ export interface StyleTemplate {
   category: string
   /** 适用题材。 */
   applicableGenres: string[]
-  /** 叙述规则。 */
+  /** 标签（便于筛选）。 */
+  tags?: string[]
+  /** 一句话分析（模板定位说明）。 */
+  analysisMarkdown?: string
+  /** 叙述规则（结构化）。 */
+  narrative?: StyleTemplateNarrativeRules
+  /** 角色规则（结构化）。 */
+  character?: StyleTemplateCharacterRules
+  /** 语言规则（结构化）。 */
+  language?: StyleTemplateLanguageRules
+  /** 节奏规则（结构化）。 */
+  rhythm?: StyleTemplateRhythmRules
+  /** 叙述规则（扁平，兼容旧数据）。 */
   proseRules: string[]
-  /** 角色/台词规则。 */
+  /** 角色/台词规则（扁平，兼容旧数据）。 */
   dialogueRules: string[]
-  /** 语言规则。 */
+  /** 语言规则（扁平，兼容旧数据）。 */
   languageRules: string[]
-  /** 节奏规则。 */
+  /** 节奏规则（扁平，兼容旧数据）。 */
   rhythmRules: string[]
   /** 该模板默认绑定的反 AI 规则 key（内置规则名）。 */
   defaultAntiAiRuleKeys: string[]
 }
 
+/** 起始风格画像：无样本文本也能快速绑定一套写法。 */
+export interface StarterStyleProfile {
+  /** stable key（如 starter-power-up）。 */
+  key: string
+  /** 绑定到的写法模板 key。 */
+  templateKey: string
+  /** 画像名。 */
+  name: string
+  /** 画像说明。 */
+  description: string
+}
+
+/** 剧情桥段库：可复用的情节套路/桥段（作者阅读经验沉淀，与书内 Plotline 不同层）。 */
+export interface PlotBeatTemplate {
+  /** 模板 key（如 face-slap / exit-wedding）。 */
+  key: string
+  /** 桥段名（如「打脸」「退婚」）。 */
+  name: string
+  /** 分类（如「装逼打脸」「身份逆袭」）。 */
+  category: string
+  /** 一句话说明。 */
+  summary: string
+  /** 适用位置（开局/前期/中期/后期/高潮/结尾）。 */
+  position: string
+  /** 前置条件。 */
+  preconditions: string[]
+  /** 爽点来源。 */
+  payoffSource: string[]
+  /** 常用组合（可搭配的桥段）。 */
+  combos: string[]
+  /** 禁忌（别用烂/别用死）。 */
+  taboos: string[]
+  /** 适用题材。 */
+  applicableGenres: string[]
+}
+
 /** 写法引擎：从样本文本提取的叙事风格资产。 */
 export interface StyleAsset {
   /** 资产名（如「林越式痞坏」「冷峻猎手风」）。 */
@@ -1156,6 +2069,32 @@ export interface StyleAsset {
   boundaries: string[]
   /** 来源样本文本（可空）。 */
   sourceText?: string
+  /** 仿写预设：imitate=高保真仿写 / balanced=平衡 / transfer=迁移（去指纹）。 */
+  preset?: 'imitate' | 'balanced' | 'transfer'
+  /** 指纹风险：仿写时照搬原作独特表达的风险。 */
+  fingerprintRisk?: 'low' | 'medium' | 'high'
+  /** 净化后的写作指引（可安全用于生成，去掉了会暴露来源的具体细节）。 */
+  writingGuidance?: string[]
+  /** 禁止照搬的原作特有实体（人名/地名/核心设定句式），生成时需避开。 */
+  forbiddenEntities?: string[]
+  /** 创建时间。 */
+  createdAt: string
+}
+
+/** 写作公式（从样本文本分层提取的"这套文怎么写"浓缩，供生成/改写复用）。 */
+export interface StyleFormula {
+  /** 稳定 key。 */
+  key: string
+  /** 公式名。 */
+  name: string
+  /** 提取深度：basic=骨架 / standard=完整 / deep=逐句细化。 */
+  depth: 'basic' | 'standard' | 'deep'
+  /** 重点聚焦域（如 开场/对话/节奏/爽点密度）。 */
+  focusAreas: string[]
+  /** 公式正文（Markdown）。 */
+  formula: string
+  /** 应用指引（生成/改写时如何套用）。 */
+  applyGuidance: string
   /** 创建时间。 */
   createdAt: string
 }
@@ -1172,6 +2111,8 @@ export interface ProjectAssets {
   antiAiRules: AntiAiRule[]
   /** 绑定的写法资产。 */
   styleAssets: StyleAsset[]
+  /** 写作公式（分层提取：basic/standard/deep）。 */
+  styleFormulas?: StyleFormula[]
   /** 资产更新时间。 */
   updatedAt?: string
 }
@@ -1187,6 +2128,10 @@ export interface AssetsResponse {
   styleTemplates: StyleTemplate[]
   /** 内置推进模式候选。 */
   progressionLibrary: ProgressionMode[]
+  /** 起始风格画像（无样本文本快速绑定写法）。 */
+  starterStyleProfiles: StarterStyleProfile[]
+  /** 内置剧情桥段库（可复用套路）。 */
+  plotBeatLibrary: PlotBeatTemplate[]
 }
 
 /** POST /assets request：更新项目写作资产（部分字段可选）。 */
@@ -1196,6 +2141,7 @@ export interface AssetsPatch {
   auxiliaryProgressions?: ProgressionMode[]
   antiAiRules?: AntiAiRule[]
   styleAssets?: StyleAsset[]
+  styleFormulas?: StyleFormula[]
 }
 
 /** POST /style-engine request：从样本文本提取写法资产。 */
@@ -1205,3 +2151,287 @@ export interface StyleEngineRequest {
   /** 资产名（可选，默认「风格资产 N」）。 */
   name?: string
 }
+
+// ---------------------------------------------------------- author assets (总数据)
+
+/** 作者资产库中一条可跨书复用的资产（笔法/红线/套路/角色模板/世界观模板等）。 */
+export interface AuthorStyleAsset {
+  /** 稳定 id（本地唯一）。 */
+  id: string
+  /** 资产名（如「短句快节奏爽文风」「林越式痞坏角色」）。 */
+  name: string
+  /** 资产类型。 */
+  kind: 'style' | 'antiAi' | 'progression' | 'genre' | 'roleTemplate' | 'worldTemplate' | 'plotBeat' | 'custom'
+  /** 一句话摘要。 */
+  summary: string
+  /** 资产正文内容（按 kind 约定解读的文本/JSON 描述）。 */
+  content: string
+  /** 结构化载荷（角色模板/世界观模板等可结构化字段；缺省为 null）。 */
+  structured?: Record<string, unknown>
+  /** 来源书名（哪本书提炼/收藏而来）。 */
+  sourceBooks: string[]
+  /** 标签。 */
+  tags: string[]
+  /** 来源样本文本（可选）。 */
+  sourceText?: string
+  /** 创建时间。 */
+  createdAt: string
+  /** 更新时间。 */
+  updatedAt: string
+}
+
+/** 作者资产库（跨书总数据）：按作者维度聚合的可复用资产。 */
+export interface AuthorAssetLibrary {
+  /** 货架版本，便于未来迁移。 */
+  version: 1
+  items: AuthorStyleAsset[]
+}
+
+/** GET /author-assets 响应。 */
+export interface AuthorAssetsResponse {
+  assets: AuthorAssetLibrary
+}
+
+/** POST /author-assets/upsert 请求：新增或按 id 更新一条资产。 */
+export interface AuthorAssetUpsertRequest {
+  asset: AuthorStyleAsset
+}
+
+/** POST /author-assets/remove 请求：删除一条资产。 */
+export interface AuthorAssetRemoveRequest {
+  id: string
+}
+
+// ---------------------------------------------------------- adaptation (改编模式)
+
+/** 改编可改范围的单个维度（矩阵的一行）。 */
+export interface AdaptationDimension {
+  /** 维度 key（如 realm/name/goldenFinger…）。 */
+  key: string
+  /** 维度名（如「大世界」「修为体系」「主角名」「金手指」）。 */
+  title: string
+  /** 可改度：保留 / 可改影响大 / 可改影响小 / 可自由改 / 仅视觉包装。 */
+  mutability: 'locked' | 'big' | 'small' | 'free' | 'visual'
+  /** 原文当前值（从正文提炼，附证据）。 */
+  current: string
+  /** 该值在正文中的出现证据（章节/频次，可空）。 */
+  evidence?: string
+  /** 建议的候选新值（可空，每套含名称与一句话说明）。 */
+  candidates?: Array<{ name: string; desc?: string }>
+  /** 联动影响说明（改了会影响哪些章节/角色/伏笔/术语）。 */
+  impact: string
+  /** 风险评级。 */
+  risk: 'high' | 'medium' | 'low'
+}
+
+/** POST /adapt/analyze 请求：上传全文做改编分析。 */
+export interface AdaptAnalyzeRequest {
+  /** 全文文本（优先）。 */
+  text: string
+  /** 或服务器端全文文件路径。 */
+  filePath?: string
+}
+
+/** POST /adapt/analyze 响应。 */
+export interface AdaptAnalyzeResponse {
+  /** 识别书名（文件名推断或正文首行）。 */
+  bookName: string
+  /** 拆出的章节数。 */
+  chapters: number
+  /** 反推的初始大纲（可空）。 */
+  outline?: string
+  /** 可改范围矩阵。 */
+  dimensions: AdaptationDimension[]
+  /** 分析消耗说明。 */
+  note?: string
+}
+
+/** 一条改编映射（原值 → 新值）。 */
+export interface AdaptationMapping {
+  /** 原值（如「林尘」「练气」「青云宗」）。 */
+  source: string
+  /** 新值（如「楚风」「凝元」「天渊阁」）。 */
+  target: string
+  /** 适用范围。 */
+  scope: 'name' | 'realm' | 'faction' | 'term' | 'other'
+  /** 说明（可空）。 */
+  note?: string
+}
+
+/** 改编规则：哪些必须保留、哪些允许改、一致性约束。 */
+export interface AdaptationRules {
+  /** 必须保留的要素（骨架/人物动机/伏笔逻辑/爽点结构…）。 */
+  preserve: string[]
+  /** 允许改变的要素。 */
+  change: string[]
+  /** 改编红线/一致性要求。 */
+  constraints: string[]
+}
+
+/** 一组改编方案（映射表 + 规则 + 联动影响清单）。 */
+export interface AdaptationProposal {
+  /** 映射表（原→新）。 */
+  mappings: AdaptationMapping[]
+  /** 改编规则。 */
+  rules: AdaptationRules
+  /** 联动影响清单。 */
+  impacts: Array<{ item: string; detail: string; risk: 'high' | 'medium' | 'low'; chapters?: number[] }>
+}
+
+/** POST /adapt/propose 请求：由用户勾选的维度 + 新值生成改编方案。 */
+export interface AdaptProposeRequest {
+  /** 原文全文（复用，便于 LLM 核对联动影响）。 */
+  text: string
+  /** 用户确认要改的维度（含原值与新值）。 */
+  selections: Array<{ key: string; title: string; current: string; target: string; mutability: string }>
+  /** 若已分析过，可携带完整矩阵作为上下文。 */
+  dimensions?: AdaptationDimension[]
+}
+
+/** POST /adapt/propose 响应。 */
+export interface AdaptProposeResponse {
+  proposal: AdaptationProposal
+}
+
+/** POST /adapt/execute 请求：执行改编（replace=术语替换；rewrite=逐章 LLM 重写）。 */
+export interface AdaptExecuteRequest {
+  /** 原文全文。 */
+  text: string
+  /** 改编映射表。 */
+  mappings: AdaptationMapping[]
+  /** 改编规则（rewrite 模式生效：保留/允许变/红线）。 */
+  rules?: AdaptationRules
+  /** 执行模式：replace（术语替换）或 rewrite（逐章重写）。 */
+  mode?: 'replace' | 'rewrite'
+  /** rewrite 模式：只重写前 N 章（0/缺省 = 全部，且在 startNo/endNo 窗口内）。 */
+  maxChapters?: number
+  /** rewrite 模式：起始章号（含，默认 1）。 */
+  startNo?: number
+  /** rewrite 模式：结束章号（含；0/缺省 = 到全书末尾）。 */
+  endNo?: number
+}
+
+/** POST /adapt/execute 响应。 */
+export interface AdaptExecuteResponse {
+  /** 改编后的全文。 */
+  adaptedText: string
+  /** 执行的映射数。 */
+  mappings: number
+  /** 命中统计：每条映射的替换次数。 */
+  hits: Array<{ source: string; target: string; count: number }>
+  /** 执行模式（replace / rewrite）。 */
+  mode?: 'replace' | 'rewrite'
+  /** rewrite 模式的逐章结果（no/title/chars）。 */
+  rewritten?: Array<{ no: number; title: string; chars: number }>
+  /** rewrite 模式下重写失败、保留原章的章节号。 */
+  skipped?: number[]
+}
+
+/** POST /adapt/rewrite-stream 的 NDJSON 帧（逐章进度 + 结束结果）。 */
+export type AdaptRewriteFrame =
+  | { type: 'progress'; completed: number; total: number; no: number; title: string }
+  | { type: 'done'; result: AdaptExecuteResponse }
+  | { type: 'error'; message: string }
+
+/** POST /adapt/save 请求：保存改编全文为新书（原书保留，登记书架）。 */
+export interface AdaptSaveRequest {
+  /** 改编后的全文。 */
+  text: string
+  /** 新书名（缺省为「改编新书」；建议用「<原著>·改编版」）。 */
+  bookName?: string
+  /** 新书输出目录（缺省 ~/.dsh/novels/书名）。 */
+  outputDir?: string
+  /** 可附带反推大纲（写进新项目，便于后续续写/编辑）。 */
+  outline?: string
+}
+
+/** POST /adapt/save 响应。 */
+export interface AdaptSaveResponse {
+  /** 登记后的书架条目。 */
+  book: BookEntry
+  /** 新书名。 */
+  bookName: string
+  /** 成功拆出的章节数。 */
+  chapters: number
+  /** 因内容过短被跳过的章节标题列表。 */
+  skipped: string[]
+  /** 新书输出目录。 */
+  outputDir: string
+}
+
+/** POST /adapt/materialize 请求：从源全文 + 用户编辑后的改编方案，提炼新书资料并保存为「待写新书」。 */
+export interface AdaptMaterializeRequest {
+  /** 源书全文。 */
+  text: string
+  /** 新书名（缺省为「<源书名>·改编版」）。 */
+  bookName?: string
+  /** 新书输出目录（缺省 ~/.dsh/novels/书名）。 */
+  outputDir?: string
+  /** 反推大纲（来自分析；缺少时用源文章题兜底）。 */
+  outline?: string
+  /** 用户编辑后的改编方案（映射表 + 规则）。 */
+  proposal: AdaptationProposal
+  /** 拟规划章节数（缺省 30，可在前端调整）。 */
+  chapterCount?: number
+}
+
+/** POST /adapt/materialize 响应：提炼后的新书资料（预览，尚未落盘；保存走 /adapt/materialize-save）。 */
+export interface AdaptMaterializeResponse {
+  /** 书架条目（仅在已保存时存在；预览阶段为 undefined）。 */
+  book?: BookEntry
+  /** 新书名。 */
+  bookName: string
+  /** 改编后总纲。 */
+  outline: string
+  /** 改编后道藏。 */
+  bible: StoryBible
+  /** 改编后角色库。 */
+  roles: RoleRecord[]
+  /** 改编后大世界。 */
+  world: WorldState
+  /** 改编后卷计划。 */
+  volumes: Volume[]
+  /** 改编后章节计划（status=pending）。 */
+  chapters: ChapterPlan[]
+  /** 新书输出目录。 */
+  outputDir: string
+}
+
+/** POST /adapt/materialize-save 请求：把预览/微调后的新书资料写入并登记书架。 */
+export interface AdaptMaterializeSaveRequest {
+  /** 新书名（缺省为「改编版」）。 */
+  bookName?: string
+  /** 新书输出目录（缺省 ~/.dsh/novels/书名）。 */
+  outputDir?: string
+  /** 改编后总纲。 */
+  outline: string
+  /** 改编后道藏。 */
+  bible: StoryBible
+  /** 改编后角色库。 */
+  roles: RoleRecord[]
+  /** 改编后大世界。 */
+  world: WorldState
+  /** 改编后卷计划。 */
+  volumes: Volume[]
+  /** 改编后章节计划（status=pending）。 */
+  chapters: ChapterPlan[]
+}
+
+/** POST /adapt/materialize-save 响应。 */
+export interface AdaptMaterializeSaveResponse {
+  /** 登记后的书架条目。 */
+  book: BookEntry
+  /** 新书名。 */
+  bookName: string
+  /** 成功写入的章节数。 */
+  chapters: number
+  /** 新书输出目录。 */
+  outputDir: string
+}
+
+/** POST /plugin/update 响应：插件自更新结果。 */
+export interface PluginUpdateResponse {
+  ok: boolean
+  /** 更新结果说明（成功/失败/环境提示）。 */
+  message: string
+}