@waterwx/dsh-novel-forge 1.7.0 → 1.7.2

package/src/protocol.ts

@@ -44,6 +44,8 @@ export const NOVEL_API = {
   bookshelfImportTextPreview: '/api/dsh-novel-forge/bookshelf/import-text/preview',
   /** 漫剧方案管理：create/remove/activate。 */
   manhuaPlans: '/api/dsh-novel-forge/manhua/plans',
+  /** 漫剧角色库：从分镜提名（规则+LLM两段式）/ 建卡 / 更新 / 删除 / 形象锚点 / 精修提示词。 */
+  mangaRoles: '/api/dsh-novel-forge/manga/roles',
   /** 分镜·编剧级：单章 → 剧情骨架（节拍链）。 */
   storyboardSkeleton: '/api/dsh-novel-forge/storyboard/skeleton',
   /** 分镜·导演级：骨架 → 分镜表（镜头级）。 */
@@ -225,6 +227,8 @@ export interface StoryboardSkeleton {
   arc: string
   /** 剧情节拍链（时间顺序，因果连贯）。 */
   beats: StoryboardBeat[]
+  /** 本章全部出镜角色（正文中的确切称谓，去重；漫剧角色库提名地基）。 */
+  characters?: string[]
 }
 
 /** POST /storyboard/skeleton 请求：生成单章剧情骨架。 */
@@ -261,6 +265,10 @@ export interface StoryboardShot {
   prevState: string
   /** 本镜头结束状态。 */
   nextState: string
+  /** 本镜头出镜角色（引用小说库规范名/漫剧卡名，1-4 个；漫剧角色库提名地基）。 */
+  characters?: string[]
+  /** 本镜头已绑定漫剧卡的 id（定妆图引用，供出图/生视频时按卡取参考图）。 */
+  mangaRoleIds?: string[]
 }
 
 /** 分镜·导演级：单章分镜表。 */
@@ -269,6 +277,10 @@ export interface StoryboardTable {
   shots: StoryboardShot[]
   /** 生成时注入的场景卡名称（前端标注消费关系）。 */
   usedScenes?: string[]
+  /** 本章全部出镜角色（各镜头 characters 去重汇总；骨架有则兜底）。 */
+  characters?: string[]
+  /** 本章已绑定漫剧卡的 id（去重汇总，定妆图引用）。 */
+  mangaRoleIds?: string[]
 }
 
 /** POST /storyboard/table 请求：骨架 → 分镜表。 */
@@ -293,6 +305,8 @@ export interface StoryboardPrompt {
   shotId: string
   /** 即梦/视频模型可粘贴的中文提示词（画面+运镜+光效+风格词块）。 */
   text: string
+  /** 本镜头绑定的漫剧卡 id（定妆图引用：出图/生视频时按卡取 imageUrl/立绘）。 */
+  mangaRoleIds?: string[]
 }
 
 /** 分镜持久化：单章的分镜产出（骨架 + 分镜表 + 视频提示词，可分别存在）。 */
@@ -354,6 +368,113 @@ export interface MangaPlansResponse {
   plans: MangaPlan[]
 }
 
+/** 漫剧角色卡：制作角色（要建模/出图/锁一致性的「上镜角色」），与小说角色库弱关联。 */
+export interface MangaRoleCard {
+  /** 稳定 id。 */
+  id: string
+  /** 来源小说角色名（只读追溯，非强外键；禁止反向写回小说库）。 */
+  sourceRoleName?: string
+  /** 漫剧用名（可短剧化改名）。 */
+  name: string
+  /** 身份一句话。 */
+  identity: string
+  /** 核心功能：主角/导师/感情线/反派/搭档/线人/功能性。 */
+  coreFunction: 'protagonist' | 'mentor' | 'love_interest' | 'antagonist' | 'sidekick' | 'informant' | 'functional'
+  /** 与主角的关系。 */
+  protagonistRelation: 'enemy' | 'friend' | 'mentor' | 'lover' | 'exploit' | 'neutral'
+  /** 口头禅/说话方式（配音一致性）。 */
+  speechStyle: string
+  /** ≤3 个极致性格标签。 */
+  traits: string[]
+  /** 1-2 个辨识度外貌点。 */
+  appearance: string
+  /** 3-5 个关键剧情节点。 */
+  keyScenes: string[]
+  /** 上场集数（分镜提名导入时记录）。 */
+  appearsInEpisodes: number[]
+  /** 待匹配 → 待确认 → 已导入 → 已定妆 → 已归档。 */
+  status: 'pending_match' | 'pending_confirm' | 'imported' | 'anchored' | 'archived'
+  /** 形象资产（沿用小说角色库同款结构）。 */
+  imagePrompt?: RoleRecord['imagePrompt']
+  /** 情绪表情清单（锚点提炼时产出）。 */
+  expressions?: string[]
+  /** 四类精修生图提示词（立绘/四视图/表情/细节）。 */
+  promptKit?: RoleRecord['promptKit']
+  /** 角色参考图。 */
+  imageUrl?: string
+  /** 图集（图像锚点）。 */
+  gallery?: RoleImage[]
+  /** 生成锚点/精修时的方案风格 id（旧风格检测用）。 */
+  promptStyleId?: string
+  createdAt: string
+  updatedAt: string
+}
+
+/** 分镜提名 → 小说角色库匹配的一条候选。 */
+export interface MangaRoleCandidate {
+  /** 分镜里的原始称谓（正文确切用法）。 */
+  rawName: string
+  /** matched=命中小说角色；ambiguous=多个候选待定；not_in_library=小说库没有；already_imported=已建漫剧卡（跳过）。 */
+  verdict: 'matched' | 'ambiguous' | 'not_in_library' | 'already_imported'
+  /** 规则阶段候选短名单（≤5，精确名优先 + 身份/简称匹配）。 */
+  matches: Array<{ roleName: string; reason: string }>
+  /** LLM/规则确认的命中角色名（ambiguous 时可能为空）。 */
+  matchedRoleName?: string
+  /** not_in_library 时给出建议：backfill=正文有该称谓但小说库漏提炼（回小说库补）；manga_new=漫剧新增角色（直接建卡）。 */
+  novelHint?: 'backfill' | 'manga_new'
+  /** 采纳时预填的漫剧卡建议。 */
+  suggested: {
+    name: string
+    identity: string
+    coreFunction: MangaRoleCard['coreFunction']
+    protagonistRelation: MangaRoleCard['protagonistRelation']
+    speechStyle: string
+    traits: string[]
+    appearance: string
+    keyScenes: string[]
+  }
+}
+
+/** POST /manga/roles 请求：漫剧角色库操作。 */
+export interface MangaRolesRequest {
+  op: 'nominate' | 'adopt' | 'update' | 'remove' | 'visual' | 'promptKit' | 'image' | 'removeImage' | 'imageGenerate' | 'mode'
+  /** op='mode'：短剧精简模式开关。 */
+  shortDramaMode?: boolean
+  /** op='nominate'：从哪章分镜提名角色。 */
+  chapterNo?: number
+  /** op='adopt' / op='update'：漫剧角色卡。 */
+  card?: MangaRoleCard
+  /** op='remove' / 'visual' / 'promptKit' / 'image' / 'removeImage' / 'imageGenerate'：漫剧卡 id。 */
+  id?: string
+  /** op='visual' / 'promptKit'：漫剧方案基底风格 id。 */
+  styleId?: string
+  /** 可选滤镜风格 id。 */
+  filterId?: string
+  /** op='image'：定妆图 dataURL。 */
+  dataUrl?: string
+  /** op='image'：图集用途标签（立绘/四视图/表情-x/场景/细节）；缺省视为角色参考图（imageUrl）。 */
+  label?: string
+  /** op='imageGenerate'：漫画风格预设 id（可选）。 */
+  style?: string
+  /** op='imageGenerate'：生图模型库条目 id（缺省用启用条目）。 */
+  modelId?: string
+}
+
+/** POST /manga/roles 响应。 */
+export interface MangaRolesResponse {
+  cards: MangaRoleCard[]
+  /** op='nominate' 时的 AI 提名候选。 */
+  candidates?: MangaRoleCandidate[]
+  /** op='visual' 时的形象锚点（已写入漫剧卡）。 */
+  visual?: RoleRecord['imagePrompt']
+  /** op='promptKit' 时的四类精修提示词包（已写入漫剧卡）。 */
+  promptKit?: RoleRecord['promptKit']
+  /** op='image' / 'imageGenerate' 时的定妆图 dataURL（已写入漫剧卡）。 */
+  imageUrl?: string
+  /** op='mode' 时的短剧精简模式状态。 */
+  shortDramaMode?: boolean
+}
+
 
 /** Chapter lifecycle states (the writing pipeline's state machine). */
 export type ChapterStatus =
@@ -1045,6 +1166,10 @@ export interface ProjectState {
   plotlines?: Plotline[]
   /** 角色库（作者维护 + AI 提炼的主表）。 */
   roles?: RoleRecord[]
+  /** 漫剧角色库（制作角色投影：从分镜提名导入，独立于小说角色库）。 */
+  mangaRoles?: MangaRoleCard[]
+  /** 短剧精简模式：漫剧角色库按 5-8 上镜角色 / 功能标签 / 关系闭环 / 人设极致化约束。 */
+  shortDramaMode?: boolean
   /** 场景库（作者维护 + AI 提炼的主表）。 */
   scenes?: SceneCard[]
   /** 视觉世界观规则（生图/生视频必须遵守，从道藏提炼，注入所有提示词）。 */

package/src/routes.ts

@@ -60,6 +60,9 @@ import {
   type MangaPlan,
   type MangaPlansRequest,
   type MangaPlansResponse,
+  type MangaRoleCard,
+  type MangaRolesRequest,
+  type MangaRolesResponse,
   type LoadOutlineResponse,
   type NovelConfig,
   type PlotlinesRequest,
@@ -142,12 +145,16 @@ import {
   extractRoles,
   extractScenes,
   generateRolePromptKit,
+  generateMangaRolePromptKit,
   extractVisualRules,
   extractRoleVisual,
+  extractMangaRoleVisual,
+  nominateMangaRoles,
   suggestOutlines,
   reverseOutlineFromChapters,
   breakdownBook,
   generateRoleReferenceImage,
+  generateMangaRoleReferenceImage,
   testImageEndpoint,
   generateStoryboardSkeleton,
   generateStoryboardTable,
@@ -1919,6 +1926,201 @@ export function makeRoutes(deps: NovelRoutesDeps): WebRoute[] {
     },
   }
 
+  // ------------------------------------------------------- manga roles
+  /** 漫剧角色库：从分镜提名（规则+LLM 两段式）/ 建卡 / 更新 / 删除 / 形象锚点 / 精修提示词。 */
+  const mangaRolesRoute: WebRoute = {
+    kind: 'exact',
+    path: NOVEL_API.mangaRoles,
+    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<MangaRolesRequest>(req)
+      if (project.mangaRoles === undefined) project.mangaRoles = []
+      const op = body?.op
+      if (op === 'nominate') {
+        const chapterNo = body?.chapterNo
+        if (typeof chapterNo !== 'number' || chapterNo <= 0) {
+          writeJson(res, 400, { error: 'chapterNo（章号）必填' })
+          return
+        }
+        try {
+          const candidates = await nominateMangaRoles(ctx, config, project, config.outputDir, chapterNo)
+          writeJson(res, 200, { cards: project.mangaRoles, candidates } satisfies MangaRolesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `提名失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'adopt' || op === 'update') {
+        const card = body?.card
+        if (card === undefined || typeof card !== 'object') {
+          writeJson(res, 400, { error: 'card（漫剧角色卡）必填' })
+          return
+        }
+        const name = (card.name ?? '').trim()
+        if (name === '') {
+          writeJson(res, 400, { error: '漫剧角色名不能为空' })
+          return
+        }
+        const now = new Date().toISOString()
+        const existing = card.id !== '' ? project.mangaRoles.find(c => c.id === card.id) : undefined
+        const next: MangaRoleCard = {
+          id: card.id !== '' ? card.id : 'mr-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 6),
+          sourceRoleName: card.sourceRoleName !== undefined && card.sourceRoleName !== '' ? card.sourceRoleName : undefined,
+          name,
+          identity: card.identity ?? '',
+          coreFunction: card.coreFunction ?? 'functional',
+          protagonistRelation: card.protagonistRelation ?? 'neutral',
+          speechStyle: card.speechStyle ?? '',
+          traits: Array.isArray(card.traits) ? card.traits.map(t => String(t).slice(0, 20)).filter(t => t !== '').slice(0, 3) : [],
+          appearance: card.appearance ?? '',
+          keyScenes: Array.isArray(card.keyScenes) ? card.keyScenes.map(k => String(k).slice(0, 120)).filter(k => k !== '').slice(0, 6) : [],
+          appearsInEpisodes: Array.isArray(card.appearsInEpisodes)
+            ? [...new Set(card.appearsInEpisodes.map(n => Number(n)).filter(n => Number.isFinite(n) && n > 0))].sort((a, b) => a - b).slice(0, 200)
+            : [],
+          status: card.status ?? 'imported',
+          imagePrompt: card.imagePrompt,
+          expressions: card.expressions,
+          promptKit: card.promptKit,
+          imageUrl: card.imageUrl,
+          gallery: card.gallery,
+          promptStyleId: card.promptStyleId,
+          createdAt: existing?.createdAt ?? now,
+          updatedAt: now,
+        }
+        if (existing !== undefined) {
+          const idx = project.mangaRoles.findIndex(c => c.id === card.id)
+          project.mangaRoles[idx] = next
+        } else {
+          project.mangaRoles.push(next)
+        }
+        project.updatedAt = now
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards: project.mangaRoles } satisfies MangaRolesResponse)
+        return
+      } else if (op === 'remove') {
+        const id = body?.id
+        if (typeof id !== 'string' || id === '') {
+          writeJson(res, 400, { error: 'id（漫剧卡 id）必填' })
+          return
+        }
+        project.mangaRoles = project.mangaRoles.filter(c => c.id !== id)
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards: project.mangaRoles } satisfies MangaRolesResponse)
+        return
+      } else if (op === 'visual') {
+        const id = body?.id?.trim()
+        if (id === undefined || id === '') {
+          writeJson(res, 400, { error: 'id（漫剧卡 id）必填' })
+          return
+        }
+        try {
+          const visual = await extractMangaRoleVisual(ctx, config, project, config.outputDir, id, body?.styleId, body?.filterId)
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { cards: project.mangaRoles, visual } satisfies MangaRolesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `形象锚点生成失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'promptKit') {
+        const id = body?.id?.trim()
+        if (id === undefined || id === '') {
+          writeJson(res, 400, { error: 'id（漫剧卡 id）必填' })
+          return
+        }
+        try {
+          const kit = await generateMangaRolePromptKit(ctx, config, project, id, body?.styleId, body?.filterId)
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { cards: project.mangaRoles, promptKit: kit } satisfies MangaRolesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `提示词精修失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'image') {
+        // 定妆图上传：带标签进图集；标签含「立绘」时同步为参考图（imageUrl）。
+        const id = body?.id?.trim()
+        const dataUrl = body?.dataUrl?.trim()
+        if (id === undefined || id === '') {
+          writeJson(res, 400, { error: 'id（漫剧卡 id）必填' })
+          return
+        }
+        if (dataUrl === undefined || dataUrl === '') {
+          writeJson(res, 400, { error: 'dataUrl（定妆图）必填' })
+          return
+        }
+        const card = project.mangaRoles.find(c => c.id === id)
+        if (card === undefined) {
+          writeJson(res, 404, { error: '漫剧角色卡不存在' })
+          return
+        }
+        const label = body?.label?.trim() ?? ''
+        if (label !== '') {
+          card.gallery ??= []
+          card.gallery = card.gallery.filter(g => g.label !== label)
+          card.gallery.push({ label, dataUrl })
+          if (label.includes('立绘')) card.imageUrl = dataUrl
+        } else {
+          card.imageUrl = dataUrl
+        }
+        card.updatedAt = new Date().toISOString()
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards: project.mangaRoles, imageUrl: card.imageUrl } satisfies MangaRolesResponse)
+        return
+      } else if (op === 'removeImage') {
+        const id = body?.id?.trim()
+        const label = body?.label?.trim() ?? ''
+        const card = project.mangaRoles.find(c => c.id === id)
+        if (card !== undefined) {
+          if (label !== '') {
+            card.gallery = (card.gallery ?? []).filter(g => g.label !== label)
+            if (label.includes('立绘')) card.imageUrl = undefined
+          } else {
+            card.imageUrl = undefined
+          }
+          card.updatedAt = new Date().toISOString()
+        }
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards: project.mangaRoles } satisfies MangaRolesResponse)
+        return
+      } else if (op === 'imageGenerate') {
+        const id = body?.id?.trim()
+        if (id === undefined || id === '') {
+          writeJson(res, 400, { error: 'id（漫剧卡 id）必填' })
+          return
+        }
+        try {
+          const imageUrl = await generateMangaRoleReferenceImage(ctx, config, project, config.outputDir, id, body?.style ?? '', body?.modelId)
+          project.updatedAt = new Date().toISOString()
+          saveProject(config.outputDir, project)
+          writeJson(res, 200, { cards: project.mangaRoles, imageUrl } satisfies MangaRolesResponse)
+          return
+        } catch (error) {
+          writeJson(res, 500, { error: `定妆图生成失败：${(error as Error).message}` })
+          return
+        }
+      } else if (op === 'mode') {
+        // 短剧精简模式开关（漫剧角色库 5-8 人 / 功能标签 / 关系闭环 / 人设极致化）。
+        project.shortDramaMode = body?.shortDramaMode === true
+        project.updatedAt = new Date().toISOString()
+        saveProject(config.outputDir, project)
+        writeJson(res, 200, { cards: project.mangaRoles, shortDramaMode: project.shortDramaMode } satisfies MangaRolesResponse)
+        return
+      } else {
+        writeJson(res, 400, { error: '未知的 manga/roles op' })
+        return
+      }
+    },
+  }
+
   // ------------------------------------------------------- chapter reset
   /** 章节复位：generating 卡死 → pending（可重新生成）。 */
   const chapterResetRoute: WebRoute = {
@@ -2587,6 +2789,7 @@ export function makeRoutes(deps: NovelRoutesDeps): WebRoute[] {
     renameRoute,
     plotlinesRoute,
     rolesRoute,
+    mangaRolesRoute,
     scenesRoute,
     visualRulesRoute,
     sensitiveRoute,