@waterwx/dsh-novel-forge 1.7.3 → 1.8.0

package/src/client/text.ts

@@ -0,0 +1,28 @@
+/**
+ * 客户端文件文本智能解码：兼容 UTF-8 BOM / UTF-16 / UTF-8 / GB18030(GBK)。
+ * 浏览器 File.text() 固定按 UTF-8 解码，GBK 中文网文 txt 会乱码，这里兜底。
+ */
+
+/**
+ * 读取一个 File 的文本，按编码探测兜底解码。
+ * @returns 解码后的文本。
+ */
+export async function readFileTextSmart(file: File): Promise<string> {
+  const buf = await file.arrayBuffer()
+  const u8 = new Uint8Array(buf)
+  // UTF-8 BOM
+  if (u8.length >= 3 && u8[0] === 0xEF && u8[1] === 0xBB && u8[2] === 0xBF) {
+    return new TextDecoder('utf-8').decode(u8.subarray(3))
+  }
+  // UTF-16 LE / BE
+  if (u8.length >= 2 && u8[0] === 0xFF && u8[1] === 0xFE) return new TextDecoder('utf-16le').decode(u8.subarray(2))
+  if (u8.length >= 2 && u8[0] === 0xFE && u8[1] === 0xFF) return new TextDecoder('utf-16be').decode(u8.subarray(2))
+  // UTF-8（宽松），含替换符则回退 GB18030
+  const utf8 = new TextDecoder('utf-8', { fatal: false }).decode(u8)
+  if (!utf8.includes('\uFFFD')) return utf8
+  try {
+    return new TextDecoder('gb18030').decode(u8)
+  } catch {
+    return utf8
+  }
+}

package/src/engine.ts

@@ -46,6 +46,13 @@ import {
   emotionZh,
 } from './story-beat-language.ts'
 import type {
+  AdaptationDimension,
+  AdaptAnalyzeResponse,
+  AdaptationMapping,
+  AdaptationProposal,
+  AdaptationRules,
+  AdaptProposeResponse,
+  AdaptExecuteResponse,
   AuditIssue,
   AuthorReview,
   BreakdownResponse,
@@ -3336,6 +3343,220 @@ export async function reverseOutlineFromChapters(
   return outline.trim()
 }
 
+/**
+ * 改编模式 P0：全文分析 → 原文设定卡片 / 可改范围矩阵。
+ * 拆章统计 + 取样正文，让 LLM 一次输出结构化 JSON：
+ * { bookName, outline, dimensions: [{key,title,mutability,current,evidence,candidates,impact,risk}] }。
+ */
+export async function analyzeAdaptation(
+  ctx: Context,
+  config: NovelConfig,
+  text: string,
+): Promise<AdaptAnalyzeResponse> {
+  const chapters = splitBookText(text).filter(c => c.body.length >= 50)
+  if (chapters.length === 0) throw new Error('未能从全文拆出章节（内容过短或无章节结构）')
+
+  // 取样：取首/1/3/2/3/尾各章正文节选，控制 token 预算。
+  const sampleBodies: string[] = []
+  const n = chapters.length
+  const pick = (i: number): void => {
+    const c = chapters[i]
+    if (c !== undefined) sampleBodies.push('第' + c.no + '章《' + (c.title || '无题') + '》\n' + c.body.slice(0, 1200))
+  }
+  pick(0)
+  if (n > 3) { pick(Math.floor(n / 3)); pick(Math.floor((2 * n) / 3)) }
+  if (n > 1) pick(n - 1)
+
+  const system = '你是改编策划分析助手。'
+  const user = [
+    '你是一位资深网文编辑兼改编策划。下面给你一部已完结/连载小说的若干章正文节选。请通读并输出该书的「原文设定卡片」与「可改范围矩阵」。',
+    '输出合法 JSON 对象：',
+    '{"bookName": "书名", "outline": "一句话主线梗概（100字内）", "dimensions": [{"key":"realm","title":"大世界","mutability":"big|small|free|locked|visual","current":"当前值","evidence":"证据（出现章节/频次）","candidates":["候选1","候选2"],"impact":"改了会影响什么","risk":"high|medium|low"}]}',
+    'dimensions 至少覆盖以下维度（key/title）：realm 大世界、cultivation 修为体系、protagonist 主角、goldenFinger 金手指、supporting 配角与势力人物名、faction 势力/组织、style 文风与叙事、ending 结局走向、timeline 时间线/编年、foreshadow 伏笔/暗线。',
+    'mutability 取值：locked=建议保留、big=可改影响大、small=可改影响小、free=可自由改、visual=仅视觉包装。',
+    '每个 dimension.current 必须忠于文本，能引用原文就用原文（尤其角色名/境界名/势力名/金手指名）。',
+    '重要：所有字符串值内部不得包含换行符；JSON 必须在一段内完整结束；直接输出 JSON，不要 Markdown 代码块。',
+  ].join('\n')
+  const textOut = await complete(ctx, config, {
+    system,
+    user: user + '\n\n' + sampleBodies.join('\n\n---\n\n'),
+    temperature: 0.3,
+    maxTokens: Math.max(config.maxTokens, 6000),
+    reasoning: config.analysisReasoning ?? 'low',
+  })
+  const raw = parseJsonObject<{ bookName?: unknown; outline?: unknown; dimensions?: unknown }>(textOut)
+  const bookName = typeof raw.bookName === 'string' ? raw.bookName.trim() : '未命名'
+  const dims = Array.isArray(raw.dimensions)
+    ? raw.dimensions
+        .filter((d): d is Record<string, unknown> => typeof d === 'object' && d !== null)
+        .map(d => normalizeAdaptationDimension(d))
+        .filter((d): d is AdaptationDimension => d !== null)
+    : []
+  // 反推大纲：独立 LLM 调用，从章节正文节选生成全书总纲（Markdown）。
+  let outline: string | undefined
+  try {
+    outline = await reverseOutlineFromAdaptationText(ctx, config, chapters)
+  } catch {
+    outline = typeof raw.outline === 'string' && raw.outline.trim() !== '' ? raw.outline.trim() : undefined
+  }
+  return {
+    bookName,
+    chapters: chapters.length,
+    outline,
+    dimensions: dims,
+    note: '基于节选分析（首/中/末取样）+ 反推大纲。如需逐章全文级深度分析请后续启用全文流式入口。',
+  }
+}
+
+/** 校验并归一化一行的改编维度数据（来自 LLM）。 */
+function normalizeAdaptationDimension(d: Record<string, unknown>): AdaptationDimension | null {
+  const key = typeof d.key === 'string' ? d.key : ''
+  const title = typeof d.title === 'string' ? d.title : ''
+  if (key === '' || title === '') return null
+  const mutability = (['locked', 'big', 'small', 'free', 'visual'] as const).includes(d.mutability as AdaptationDimension['mutability'])
+    ? d.mutability as AdaptationDimension['mutability']
+    : 'small'
+  const risk = (['high', 'medium', 'low'] as const).includes(d.risk as AdaptationDimension['risk'])
+    ? d.risk as AdaptationDimension['risk']
+    : 'medium'
+  return {
+    key,
+    title,
+    mutability,
+    current: typeof d.current === 'string' ? d.current : '',
+    evidence: typeof d.evidence === 'string' ? d.evidence : undefined,
+    candidates: Array.isArray(d.candidates) ? d.candidates.filter((x): x is string => typeof x === 'string') : [],
+    impact: typeof d.impact === 'string' ? d.impact : '',
+    risk,
+  }
+}
+
+/** 从全文拆出的章节节选反推全书总纲（Markdown），用于改编 P0 的「反推大纲」。 */
+async function reverseOutlineFromAdaptationText(
+  ctx: Context,
+  config: NovelConfig,
+  chapters: Array<{ no: number; title: string; body: string }>,
+): Promise<string> {
+  // 均匀采样最多 20 章，每章正文前 600 字，控制成本。
+  const n = chapters.length
+  const sample: string[] = []
+  const count = Math.min(n, 20)
+  for (let i = 0; i < count; i++) {
+    const idx = Math.floor((i * n) / count)
+    const c = chapters[idx]
+    if (c === undefined) continue
+    sample.push('第' + c.no + '章《' + (c.title || '无题') + '》\n' + c.body.slice(0, 600))
+  }
+  const system = [
+    '你是一位经验丰富的小说主编。根据下面若干章节的正文节选，反推出这本书的总纲（可作为后续改编与章节续写的骨架）。',
+    '要求：',
+    '1. 第一行写《书名》（可从正文推断，否则《未命名》）。',
+    '2. 按故事弧线划分卷/部分：每卷给卷名与主旨（标注覆盖章节范围）。',
+    '3. 对每章列出：章节号 + 标题 + 一句话核心情节。',
+    '4. 最后给出：全书主线、主要人物弧线、已埋设待回收的伏笔清单。',
+    '5. 输出纯文本 Markdown 结构（# 一级标题、## 二级标题、- 列表），不要寒暄，不要其他输出。',
+  ].join('\n')
+  const user = sample.join('\n\n---\n\n')
+  const text = await complete(ctx, config, { system, user, temperature: 0.4, maxTokens: Math.max(config.maxTokens, 6000), reasoning: config.analysisReasoning ?? 'low' })
+  return text.trim()
+}
+
+/** 改编方案：由用户勾选的维度与新值，生成 LLM 映射表/规则/影响清单。 */
+export async function proposeAdaptation(
+  ctx: Context,
+  config: NovelConfig,
+  text: string,
+  selections: Array<{ key: string; title: string; current: string; target: string; mutability: string }>,
+  dimensions?: AdaptationDimension[],
+): Promise<AdaptProposeResponse> {
+  const selLines = selections.map(s => '- ' + s.title + '（' + s.key + '）：' + s.current + ' → ' + s.target).join('\n')
+  const dimLines = (dimensions ?? []).map(d => '- ' + d.title + '：' + d.current + '（可改度：' + d.mutability + '，风险：' + d.risk + '）').join('\n')
+  const system = '你是改编策划。'
+  const user = [
+    '下面给出改编决策：用户想改哪些维度、改成什么值。请生成一份可执行的「改编方案」。',
+    '要求输出合法 JSON 对象：',
+    '{"mappings": [{"source":"原值","target":"新值","scope":"name|realm|faction|term|other","note":"说明"}], "rules": {"preserve":["必须保留的要素"],"change":["允许改变的要素"],"constraints":["改编红线/一致性要求"]}, "impacts": [{"item":"受影响项","detail":"说明","risk":"high|medium|low","chapters":[章号]}]}',
+    'mappings 需把用户确认的新值展开为「原→新」条目（如主角名/境界名/势力名/术语），并补充用户未填但关联的必改项（如改了修为体系名，相关的境界名一并列映射）。',
+    'rules.preserve 至少包含：故事骨架、人物动机、伏笔逻辑、爽点结构。',
+    'impacts 列出每个改动会影响的内容（术语/角色/章节/伏笔），能定位章号尽量定位；无法定位则给章节区间提示。',
+    '重要：所有字符串值内部不得包含换行符；JSON 必须在一段内完整结束；直接输出 JSON，不要 Markdown 代码块。',
+    '',
+    '用户要改：',
+    selLines,
+    '',
+    '原文可改矩阵（已分析）：',
+    dimLines,
+  ].join('\n')
+  const out = await complete(ctx, config, { system, user, temperature: 0.3, maxTokens: Math.max(config.maxTokens, 6000), reasoning: config.analysisReasoning ?? 'low' })
+  const raw = parseJsonObject<{ mappings?: unknown; rules?: unknown; impacts?: unknown }>(out)
+  const mappings = Array.isArray(raw.mappings)
+    ? raw.mappings
+        .filter((m): m is Record<string, unknown> => typeof m === 'object' && m !== null)
+        .map(m => normalizeAdaptationMapping(m))
+        .filter((m): m is AdaptationMapping => m !== null)
+    : []
+  const rules = normalizeAdaptationRules(raw.rules)
+  const impacts = Array.isArray(raw.impacts)
+    ? raw.impacts
+        .filter((i): i is Record<string, unknown> => typeof i === 'object' && i !== null)
+        .map(i => normalizeAdaptationImpact(i))
+    : []
+  return { proposal: { mappings, rules, impacts } }
+}
+
+/** 剧本术语替换执行：按映射表做精确替换并统计命中。 */
+export function applyAdaptationReplacements(
+  text: string,
+  mappings: AdaptationMapping[],
+): { adaptedText: string; hits: Array<{ source: string; target: string; count: number }> } {
+  const seen = new Set<string>()
+  const unique = mappings.filter(m => {
+    const s = m.source.trim()
+    if (s === '' || s === m.target.trim()) return false
+    if (seen.has(s)) return false
+    seen.add(s)
+    return true
+  }).sort((a, b) => b.source.length - a.source.length)
+  let adapted = text
+  const hits: Array<{ source: string; target: string; count: number }> = []
+  for (const m of unique) {
+    const count = adapted.split(m.source).length - 1
+    if (count > 0) adapted = adapted.split(m.source).join(m.target)
+    hits.push({ source: m.source, target: m.target, count })
+  }
+  return { adaptedText: adapted, hits }
+}
+
+/** 校验归一化一条映射（来自 LLM）。 */
+function normalizeAdaptationMapping(m: Record<string, unknown>): AdaptationMapping | null {
+  const source = typeof m.source === 'string' ? m.source.trim() : ''
+  const target = typeof m.target === 'string' ? m.target.trim() : ''
+  if (source === '' || target === '') return null
+  const scope = (['name', 'realm', 'faction', 'term', 'other'] as const).includes(m.scope as AdaptationMapping['scope'])
+    ? m.scope as AdaptationMapping['scope']
+    : 'other'
+  return { source, target, scope, note: typeof m.note === 'string' ? m.note : undefined }
+}
+
+/** 校验归一化改编规则（来自 LLM）。 */
+function normalizeAdaptationRules(r: unknown): AdaptationRules {
+  const obj = typeof r === 'object' && r !== null ? r as Record<string, unknown> : {}
+  const arr = (v: unknown): string[] => Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+  return { preserve: arr(obj.preserve), change: arr(obj.change), constraints: arr(obj.constraints) }
+}
+
+/** 校验归一化一条影响项（来自 LLM）。 */
+function normalizeAdaptationImpact(i: Record<string, unknown>): { item: string; detail: string; risk: 'high' | 'medium' | 'low'; chapters?: number[] } {
+  const risk = (['high', 'medium', 'low'] as const).includes(i.risk as 'high' | 'medium' | 'low') ? i.risk as 'high' | 'medium' | 'low' : 'medium'
+  const chapters = Array.isArray(i.chapters) ? i.chapters.filter((x): x is number => typeof x === 'number') : undefined
+  return {
+    item: typeof i.item === 'string' ? i.item : '',
+    detail: typeof i.detail === 'string' ? i.detail : '',
+    risk,
+    chapters: chapters !== undefined && chapters.length > 0 ? chapters : undefined,
+  }
+}
+
 /**
  * 摘要 + 事实抽取合并为一次 LLM 调用（省一次调用与一次正文输入，
  * 批量生成时整体开销约省 25%）。

package/src/index.ts

@@ -70,6 +70,14 @@ export interface Config {
   imageApiModel?: string
   /** 是否启用豆包生图（旧字段，兼容迁移用）。 */
   imageApiEnabled?: boolean
+  /** 自定义背景图（URL / dataURL / 服务端路径引用）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样）。 */
+  themeOpacity?: number
+  /** 是否启用改编模式（默认关闭）。 */
+  enableAdaptMode?: boolean
 }
 
 export const Config: z<Config> = z.object({
@@ -98,6 +106,10 @@ export const Config: z<Config> = z.object({
   imageApiKey: z.string().default(''),
   imageApiModel: z.string().default(''),
   imageApiEnabled: z.boolean().default(false),
+  themeBackground: z.string().default(''),
+  themeBackgroundBlur: z.number().default(0),
+  themeOpacity: z.number().default(100),
+  enableAdaptMode: z.boolean().default(false),
 })
 
 /** Schema defaults, re-read for hand-built test contexts. */
@@ -157,6 +169,10 @@ export function resolveConfig(value: Partial<Config> | undefined): NovelConfig {
       return active?.model ?? value?.imageApiModel
     })(),
     imageApiEnabled: value?.imageApiEnabled ?? false,
+    themeBackground: value?.themeBackground ?? '',
+    themeBackgroundBlur: value?.themeBackgroundBlur ?? 0,
+    themeOpacity: value?.themeOpacity ?? 100,
+    enableAdaptMode: value?.enableAdaptMode ?? false,
   }
 }
 
@@ -199,6 +215,10 @@ export function apply(ctx: Context, config?: Config): void {
     if (patch.imageApiKey !== undefined) next.imageApiKey = patch.imageApiKey
     if (patch.imageApiModel !== undefined) next.imageApiModel = patch.imageApiModel
     if (patch.imageApiEnabled !== undefined) next.imageApiEnabled = patch.imageApiEnabled
+    if (patch.themeBackground !== undefined) next.themeBackground = patch.themeBackground
+    if (patch.themeBackgroundBlur !== undefined) next.themeBackgroundBlur = patch.themeBackgroundBlur
+    if (patch.themeOpacity !== undefined) next.themeOpacity = patch.themeOpacity
+    if (patch.enableAdaptMode !== undefined) next.enableAdaptMode = patch.enableAdaptMode
     if (patch.imageModels !== undefined) next.imageModels = patch.imageModels
     // Persist through the settings seam when available; otherwise keep in memory.
     // (ctx.get is the non-strict service access — no inject requirement, same

package/src/protocol.ts

@@ -113,6 +113,24 @@ export const NOVEL_API = {
   runStatus: '/api/dsh-novel-forge/run/status',
   config: '/api/dsh-novel-forge/config',
   openFolder: '/api/dsh-novel-forge/open-folder',
+  /** 作者资产库/总数据：读取个人跨书资产（笔法/红线/套路/角色模板/世界观模板）。 */
+  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',
+  /** 主题自定义背景：上传图片（POST，存盘并返回服务端 URL）。 */
+  themeBackgroundUpload: '/api/dsh-novel-forge/theme/background',
+  /** 主题自定义背景：读取已上传文件（GET prefix，/theme/background/<name>）。 */
+  themeBackgroundGet: '/api/dsh-novel-forge/theme/background',
 } as const
 
 /** 书架：一本书的条目。 */
@@ -1252,6 +1270,14 @@ export interface NovelConfig {
   imageApiModel?: string
   /** 是否启用生图（= 存在启用条目）。 */
   imageApiEnabled?: boolean
+  /** 自定义背景图（URL 或 dataURL 或服务端路径引用；空 = 使用主题默认背景）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80（0 = 不遮罩）。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样，越小越透，新拟态/黏土可见背景图）。 */
+  themeOpacity?: number
+  /** 是否启用改编模式（默认关闭；发布后开启）。 */
+  enableAdaptMode?: boolean
 }
 
 /** GET /status response. */
@@ -1468,6 +1494,13 @@ export interface ConfigPatch {
   imageApiKey?: string
   imageApiModel?: string
   imageApiEnabled?: boolean
+  /** 自定义背景图（URL / dataURL / 服务端路径引用）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样）。 */
+  themeOpacity?: number
+  enableAdaptMode?: boolean
   /** 生图模型库（完整替换保存）。 */
   imageModels?: ImageModelConfig[]
 }
@@ -1633,3 +1666,166 @@ export interface StyleEngineRequest {
   /** 资产名（可选，默认「风格资产 N」）。 */
   name?: string
 }
+
+// ---------------------------------------------------------- author assets (总数据)
+
+/** 作者资产库中一条可跨书复用的资产（笔法/红线/套路/角色模板/世界观模板等）。 */
+export interface AuthorStyleAsset {
+  /** 稳定 id（本地唯一）。 */
+  id: string
+  /** 资产名（如「短句快节奏爽文风」「林越式痞坏角色」）。 */
+  name: string
+  /** 资产类型。 */
+  kind: 'style' | 'antiAi' | 'progression' | 'genre' | 'roleTemplate' | 'worldTemplate' | '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
+  /** AI 建议的候选新值（可空）。 */
+  candidates?: 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 请求：执行改编（首版为术语替换）。 */
+export interface AdaptExecuteRequest {
+  /** 原文全文。 */
+  text: string
+  /** 改编映射表。 */
+  mappings: AdaptationMapping[]
+  /** 改编规则（可选，后续逐章改写使用；替换模式暂不依赖）。 */
+  rules?: AdaptationRules
+  /** 执行模式：首版仅 replace（术语替换）。 */
+  mode?: 'replace' | 'rewrite'
+}
+
+/** POST /adapt/execute 响应。 */
+export interface AdaptExecuteResponse {
+  /** 改编后的全文。 */
+  adaptedText: string
+  /** 执行的映射数。 */
+  mappings: number
+  /** 命中统计：每条映射的替换次数。 */
+  hits: Array<{ source: string; target: string; count: number }>
+}