dsh-cosplay-studio 2.0.4 → 2.1.0

package/README.md

@@ -13,6 +13,17 @@
 | ![芙莉莲·回眸](screenshots/01-frieren-lookback.jpg) | ![芙莉莲·半蹲](screenshots/02-frieren-crouch.jpg) | ![芙莉莲·正面](screenshots/03-frieren-front.jpg) |
 | ![芙宁娜·风中长发](screenshots/04-furina-wind.jpg) | ![芙宁娜·正面浅笑](screenshots/05-furina-front.jpg) | ![芙宁娜·侧身垂眸](screenshots/06-furina-profile.jpg) |
 
+## 工作流程
+
+四步都在同一个工作台里完成，每一步都能先看、再改，确认后才往下走：
+
+| 步骤 | 界面 |
+| --- | --- |
+| ① 角色研究：联网检索 + 图片分类 + 视觉模型提取特征 + 粗略草图确认 | ![角色研究与基准图](screenshots/07-research-and-base.png) |
+| ② 基准图微调：输入要求手动改，或让视觉模型比对参考图后智能改 | ![基准图微调](screenshots/08-base-edit.png) |
+| ③ 镜头脚本：按角色特征生成 6 镜，可逐镜改、智能补镜、手动加镜 | ![镜头脚本](screenshots/09-shot-script.png) |
+| ④ 成片与导出：先出 1440×2560 原图 PNG，再按需导出 JPEG / 预览 / 文案 | ![成片与导出](screenshots/10-export.png) |
+
 ---
 
 ## 一、安装
@@ -30,7 +41,7 @@ D:\DSH\profiles\desktop\node_modules\dsh-cosplay-studio
 ```json
 {
   "dependencies": {
-    "dsh-cosplay-studio": "2.0.2"
+    "dsh-cosplay-studio": "2.1.0"
   },
   "dsh": {
     "profile": {
@@ -45,7 +56,7 @@ D:\DSH\profiles\desktop\node_modules\dsh-cosplay-studio
 ### 方式 B：打包分发
 
 ```bash
-pnpm pack          # 产出 dsh-cosplay-studio-2.0.2.tgz
+pnpm pack          # 产出 dsh-cosplay-studio-2.1.0.tgz
 ```
 
 把 `.tgz` 或整个目录发给别人；对方按方式 A 解压/放入 `node_modules` 并在 `package.json` 登记即可。发布到 npm 后可走插件市场安装。
@@ -90,25 +101,30 @@ curl -L -o dsh-cosplay-studio.tgz \
 
 | 入口 | 做法 | 说明 |
 | --- | --- | --- |
-| A 角色名 | 输入角色名（可加作品名） | 配了对话模型时会联网式补全角色设定；没配就用内置模板 |
-| B 参考图 | 上传一张二次元角色图 | 图是唯一设计依据，按图上服装配饰拆解 |
-| C 随机推荐 | 点「随机推荐 3 个热门角色」/「换一批」 | 内置 28 个近年高热角色池；配了对话模型时会额外合并当季推荐 |
+| A 角色名 | 输入角色名（可加作品名） | 自动联网检索角色资料与立绘/cosplay 图，视觉模型提取发型、服装、道具、性格等特征 |
+| B 参考图 | 上传一张二次元角色图 | 图是唯一设计依据；视觉模型读图提取特征，必要时可「补充网络参考图」 |
+| C 随机推荐 | 点「随机推荐 3 个热门角色」/「换一批」 | 内置 28 个近年高热角色池，选中后自动走入口 A 的研究流程 |
 
-选定角色后点「创建项目」。
+选定角色后点「创建项目」，插件会用 DSH 宿主的检索 / 视觉能力做一轮**角色形象研究**：检索资料 → 下载并分类角色参考图（自动跳过风景、汉字、截图）→ 提取外观特征 → 生成 640×1024 粗略草图供确认。整个过程有分阶段进度（正在检索信息 / 正在根据参考图分析特征 / 正在生成粗略草图）。研究结果不满意可以「重新研究」，参考图项目可以「补充网络参考图」。
 
-### 两道闸门
+### 三道闸门
 
-1. **基准图**：先生成 1152×2048 基准图。确认人物、服装、背景都对了，再点「确认基准图，进入镜头脚本」。未确认前不会出任何成片。
-2. **镜头脚本**：生成 4–6 镜（每镜含情境/表情/动作/手/机位/道具），可逐镜改。确认后才会跑 1440×2560 成片。
+1. **角色形象**：看研究出的特征与粗略草图，必要时直接改特征字段后保存。
+2. **基准图**：生成 1152×2048 基准图。确认人物、服装、背景都对了再往下；不满意可以「微调基准图」——输入要求手动改，或让视觉模型比对参考图/角色卡后智能改，结果作为新版本追加，旧图保留。
+3. **镜头脚本**：按角色特征生成 6 镜（每镜含情境/表情/动作/手/机位/道具，且带角色专属细节），可逐镜改，也可「智能补 2 镜（不重复）」或手动加一镜。确认后才跑 1440×2560 成片。
 
 ### 出片与导出
 
-成片按技能流程处理：**P7 去油光 → P7b 身体化妆（腿脚肤色统一）→ 导出 JPEG（≤1.95MB）**，并生成：
+成片直接按 1440×2560 出原图（`raw/*.png`，不额外压缩），先看原图：
+
+- 每张成片可以单独「微调」：输入要求手动改，或「智能修改」让视觉模型比对参考图/已确认基准图后只修最需要改的瑕疵（手、脚、五官、衣边）；改动幅度可选，改坏了可以「撤销上次微调」。
+- 满意后再「导出成片」：可选 **去油光** / **身体化妆**，导出 JPEG（默认 q95、上限 6 MB）并生成：
+  - `00_基准角色_<角色>.jpg`
+  - `00_全套预览.jpg`（2×2 拼图）
+  - `01_动作名.jpg`、`02_动作名.jpg` …
+  - `文案.txt`（标题 3 条 / 正文 / 标签）
 
-- `00_基准角色_<角色>.jpg`
-- `00_全套预览.jpg`（2×2 拼图）
-- `01_动作名.jpg`、`02_动作名.jpg` …
-- `文案.txt`（标题 3 条 / 正文 / 标签）
+导出时会把参考图带来的白色海报留白自动补成角色配色的满幅渐变（不需要可以关闭）。去油光 / 身体化妆 / 预览 / 文案都改为可选的后续步骤，不再强制和出片绑在一起。
 
 ---
 
@@ -141,6 +157,7 @@ curl -L -o dsh-cosplay-studio.tgz \
 ## 六、已知限制
 
 - 只支持 NVIDIA GPU（8GB 显存起步）；4K 会 OOM。
-- 姿势、鞋、手套等细节在 6 步采样下仍可能漂移，插件不做自动视觉质检，需要逐镜改与重跑。
-- 未配置对话模型时，角色卡与镜头脚本使用内置模板（姿势与镜头组合固定）。
+- 本地 Z-Image-Turbo 的 img2img 结构惯性较强：基准图/成片微调能可靠地改道具、服饰细节、手部细节，但抬手臂、换姿势这类大幅动作会被原图压住；姿势请交给镜头脚本，或直接用更大改动幅度重绘（可能改变人物与构图）。
+- 智能修改会先给出问题清单再重绘，对已有成片重绘仍可能把鞋子/边缘改坏；每次覆盖前都备份在 `raw/.history/`，可随时「撤销上次微调」。
+- 联网检索使用 Bing 网页兜底（DSH 账号的 web.search 在插件 HTTP 请求里拿不到发起会话），个别角色可能仍混入不相关图片；插件会用视觉模型过滤风景、汉字、截图，并在研究日志里写明跳过原因。
 - 背景渐变颜色刻意避开米/沙/驼等接近肤色的色系，否则 P7b 的肤色遮罩会把背景一起提亮。

package/lib/card.js

@@ -17,10 +17,32 @@ export const DEFAULT_POSE = 'standing in a relaxed three-quarter turn toward the
 // HANDS is a fixed paragraph in v2.1 — it never changes across shots.
 export const DEFAULT_HANDS = 'exactly five fingers on each hand, fingers clearly separated, natural knuckles, no extra or fused fingers'
 
+// Hands and feet are the weakest area of the local model. This paragraph is
+// appended to every base/shot prompt; the matching terms also go into the
+// negative prompt (see comfy.js EXTRA_NEGATIVE).
+export const LIMB_DETAIL = 'Extremities are rendered carefully: each hand has exactly five fingers with natural knuckles, clean nails and correct proportion for the pose; each foot has exactly five toes where the shoes expose them, and the shoes, straps and laces sit correctly on the feet with believable weight; no melted, duplicated or missing parts.'
+
 // Poses with a turned body tend to crop the legs. This sentence rides along in
 // the POSE line so every shot still frames the whole figure head to shoes.
 const POSE_FRAMING = 'The entire figure stays inside the frame from the top of the head down to the shoes, with empty backdrop above the head and empty floor around the feet.'
 
+// Reference projects start from an uploaded picture. The text encoder does not
+// know that character, so every design detail must be delegated to the picture
+// itself and img2img (denoise ~0.75) carries it into the photo.
+const REFERENCE_IDENTITY = 'Photorealistic live-action cosplay photograph of a real 18-year-old East Asian woman cosplaying the exact character shown in the reference image. Keep the reference character\'s identity exactly: the same hairstyle and hair colour, eye colour, face shape, skin tone, costume pieces with their exact colours and patterns, accessories, held prop and overall silhouette, translating the illustration into real fabric, leather, metal, lace and feathers with believable material weight and clean seams.'
+
+// Full-bleed gradient: the user's brief is "character-adapted pure colour
+// backdrop, no blank or white areas". The colours come from the character card
+// palette (top / bottom), so each project gets its own backdrop instead of a
+// generic grey studio wall.
+const referenceBackdrop = (palette) => {
+  const top = String(palette?.top ?? '').trim() || 'ivory white'
+  const bottom = String(palette?.bottom ?? '').trim() || 'pale grey'
+  return `BACKDROP: one perfectly smooth vertical gradient studio backdrop that fills the whole frame edge to edge, from ${top} at the top to ${bottom} at the bottom, taken from the character's own signature palette; no white areas, no blank paper, no visible wall or floor line, no light spots or bright patches, evenly lit and completely empty, the shot contains only the person against this full-bleed gradient, no scenery, nothing else in the frame.`
+}
+
+const LIGHTING = 'LIGHTING AND CAMERA: soft key light from camera left slightly above eye level, soft fill from the right, gentle falloff, even exposure with natural skin tone, highlights are soft and controlled. Sony A7R IV, 85mm f/1.8, ISO 800, shallow depth of field, fine film grain. The face and eyes are tack-sharp and in critical focus, no motion blur on the subject, the backdrop stays a smooth even gradient top to bottom. Ultra photorealistic, looks like a real person photographed at a cosplay shoot, not anime, not illustration, not 3D render, no plastic waxy skin. Vertical 9:16 composition.'
+
 // Backdrops stay off the beige / sand / terracotta corner of the colour wheel:
 // the P7b body-makeup mask treats low-saturation tan as skin, so a skin-toned
 // paper backdrop gets brightened and left with visible streaks.
@@ -47,26 +69,38 @@ function hashText(text) {
   return hash
 }
 
-export function defaultDetails(character, series = '') {
+export function defaultDetails(character, series = '', options = {}) {
+  const name = String(character ?? '').trim() || 'a mysterious heroine'
+  const from = String(series ?? '').trim()
+  // Reference projects: the picture is the only design source, so the card
+  // must not invent hair / costume details that would fight the image.
+  const reference = options.reference === true
+  const canonical = from === '' ? `${name}'s official design` : `${name}'s official design in ${from}`
   const palette = PALETTES[hashText(character + series) % PALETTES.length]
   return {
-    character: String(character ?? '').trim() || 'a mysterious heroine',
-    series: String(series ?? '').trim(),
+    character: name,
+    series: from,
     genderWord: 'woman',
-    hair: 'long straight jet-black hair falling past the shoulder blades, the ends cleanly cut, a few fine strands framing the jaw',
-    face: DEFAULT_FACE,
-    eyeColor: 'dark brown',
+    hair: reference
+      ? 'the hairstyle and hair colour exactly as shown in the reference image'
+      : `${canonical}: the canonical hairstyle, hair colour and length`,
+    face: reference
+      ? 'the face shape, features and eyes exactly as shown in the reference image'
+      : 'the canonical face shape and features of the character',
+    eyeColor: reference ? 'the eye colour shown in the reference image' : 'the canonical eye colour',
     skinTone: SKIN_TONES[hashText(character) % SKIN_TONES.length],
     bangsRule: DEFAULT_BANGS,
     eyeCover: '',
     braid: '',
-    costume: `a faithful, well-made cosplay rendition of ${String(character ?? 'the character').trim()}'s signature outfit, covering the exact top, skirt or trousers, sleeves, belt and accessories, made in fabric and leather with visible stitching, believable material weight and clean seams, worn over a natural body with realistic proportions, together with the character's matching boots worn on both feet and, where the design calls for them, her gloves`,
-    paletteTop: palette[0],
-    paletteBottom: palette[1],
-    props: 'empty hands',
+    costume: reference
+      ? 'the exact costume, accessories and held prop shown in the reference image, every piece and colour faithful to the picture, made in fabric, leather, metal and lace with visible stitching, believable material weight and clean seams, worn over a natural body with realistic proportions, together with the matching boots worn on both feet'
+      : `a faithful, well-made cosplay rendition of ${canonical}, covering the exact top, skirt or trousers, sleeves, belt and accessories, made in fabric and leather with visible stitching, believable material weight and clean seams, worn over a natural body with realistic proportions, together with the character's matching boots worn on both feet and, where the design calls for them, her gloves`,
+    paletteTop: reference ? 'ivory white' : palette[0],
+    paletteBottom: reference ? 'pale grey' : palette[1],
+    props: reference ? 'the signature prop shown in the reference image' : 'empty hands',
     personality: 'composed, quietly confident, a little guarded',
-    identity: 'a wandering swordswoman',
-    element: 'wind',
+    identity: reference ? 'the character shown in the reference image' : name,
+    element: reference ? '' : 'wind',
   }
 }
 
@@ -96,7 +130,7 @@ export function buildCard(details) {
     '',
     `HANDS: ${DEFAULT_HANDS}.`,
     '',
-    'LIGHTING AND CAMERA: soft key light from camera left slightly above eye level, soft fill from the right, gentle falloff, even exposure with natural skin tone, highlights are soft and controlled. Sony A7R IV, 85mm f/1.8, ISO 800, shallow depth of field, fine film grain. The face and eyes are tack-sharp and in critical focus, no motion blur on the subject, the backdrop stays a smooth even gradient top to bottom. Ultra photorealistic, looks like a real person photographed at a cosplay shoot, not anime, not illustration, not 3D render, no plastic waxy skin. Vertical 9:16 composition.',
+    LIGHTING,
   ].join('\n')
 }
 
@@ -112,11 +146,55 @@ export function shotPrompt(card, shot) {
       ? 'her hands are empty and relaxed'
       : `she holds ${props} lightly in one hand`,
   )
+  parts.push(LIMB_DETAIL)
   if (!/inside the frame/i.test(pose)) parts.push(POSE_FRAMING)
   const line = parts.join('. ').replace(/\.\.+/g, '.').replace(/\.$/, '')
   return card.replace(/^POSE: .*$/m, `POSE: ${line}.`)
 }
 
+/* -------------------------------------------- reference (uploaded picture) */
+
+/**
+ * Base image for a reference project: the picture carries every design detail.
+ * The optional detail line is the researched text description — img2img uses it
+ * to reconstruct pieces the illustration hides (back of the costume, materials).
+ */
+export function referenceBasePrompt(detailLine = '', palette = null) {
+  const details = String(detailLine ?? '').trim()
+  const paragraphs = [REFERENCE_IDENTITY]
+  if (details !== '') paragraphs.push(`CHARACTER DETAILS FROM RESEARCH: ${details}.`)
+  paragraphs.push(FRAMING, LIMB_DETAIL, referenceBackdrop(palette), LIGHTING)
+  return paragraphs.join('\n\n')
+}
+
+/**
+ * Shot prompt for a reference project. Like shotPrompt() it swaps only the
+ * action, but the character paragraphs come from the reference image instead
+ * of a name the text encoder may not know.
+ */
+export function referenceShotPrompt(shot, detailLine = '', palette = null) {
+  const pose = String(shot.pose ?? '').trim() || DEFAULT_POSE
+  const hands = String(shot.hands ?? '').trim()
+  const props = String(shot.props ?? '').trim()
+  const details = String(detailLine ?? '').trim()
+  const parts = [REFERENCE_IDENTITY]
+  if (details !== '') parts.push(`CHARACTER DETAILS FROM RESEARCH: ${details}.`)
+  parts.push(FRAMING, '')
+  if (String(shot.situation ?? '').trim() !== '') parts.push(`SITUATION: ${String(shot.situation).trim()}`)
+  if (String(shot.expression ?? '').trim() !== '') parts.push(`EXPRESSION: ${String(shot.expression).trim()}`)
+  parts.push(`POSE: ${pose}${/inside the frame/i.test(pose) ? '' : ` ${POSE_FRAMING}`}`)
+  parts.push(`HANDS: ${hands === '' ? DEFAULT_HANDS : hands}`)
+  parts.push(
+    props === '' || /^(no props|empty hands|none)$/i.test(props)
+      ? 'PROP: her hands are empty and relaxed'
+      : `PROP: she holds ${props} lightly in one hand`,
+  )
+  if (String(shot.camera ?? '').trim() !== '') parts.push(`CAMERA: ${String(shot.camera).trim()}`)
+  parts.push(LIMB_DETAIL)
+  parts.push('', referenceBackdrop(palette), '', LIGHTING)
+  return parts.join('\n')
+}
+
 /* --------------------------------------------------------------- script */
 
 const SHOT_ARCHETYPES = [
@@ -182,10 +260,15 @@ const SHOT_ARCHETYPES = [
   },
 ]
 
-/** Rule based script: the six archetypes, no model required. */
+/** Rule based script: the archetypes in a character-specific order, no model required. */
 export function ruleScript(details, count = 6) {
   const wanted = Math.max(1, Math.min(SHOT_ARCHETYPES.length, Number(count) || 6))
-  return SHOT_ARCHETYPES.slice(0, wanted).map((shot, index) => ({
+  // Rotate the archetype order by a hash of the character name so two projects
+  // do not start with the same shot, and the fallback still varies.
+  const offset = Number.parseInt(hashText(String(details?.character ?? '')), 36) % SHOT_ARCHETYPES.length || 0
+  const ordered = [...SHOT_ARCHETYPES.slice(offset), ...SHOT_ARCHETYPES.slice(0, offset)]
+  const personality = String(details?.personality ?? '').trim()
+  return ordered.slice(0, wanted).map((shot, index) => ({
     id: index + 1,
     type: shot.type,
     title: shot.title,
@@ -195,7 +278,7 @@ export function ruleScript(details, count = 6) {
     hands: shot.hands,
     camera: shot.camera,
     props: shot.props === 'the character signature prop' ? (details?.props || 'empty hands') : shot.props,
-    prompt: `${shot.type}｜${shot.title}`,
+    prompt: `${shot.type}｜${shot.title}${personality === '' ? '' : `（${personality}）`}`,
   }))
 }
 
@@ -283,20 +366,67 @@ JSON 字段（全部字符串）：
   "note": "一句中文备注：你判断最难还原的一件配饰"
 }`
 
-const SCRIPT_SYSTEM = `你是真人 cosplay 棚拍的摄影指导。给定角色设定，设计一组镜头脚本，只输出 JSON 数组，不要解释。
+export const SCRIPT_SYSTEM = `你是真人 cosplay 棚拍的摄影指导。给定角色设定，设计一组镜头脚本，只输出 JSON 数组，不要解释。
 
 硬性要求：
-1. 每一镜必须同时给出六项：情境（situation）、表情（expression）、动作（pose）、手（hands）、机位（camera）、道具（props）。
-2. 差异化：表情不重样；至少一镜不看镜头；机位至少两种；手的位置每镜不同；动作里包含站、坐/蹲、动态抓拍、道具镜头中的至少三种。
-3. 姿势必须完整落在画面内：全身从头到鞋，头顶留空、脚下留地；不要写只拍半身或裁掉腿的机位。
-4. 只写正向画面，禁止 not / no / without 这类负向句；禁止摄影棚器材实景词（softbox、light stand、strobe、reflector、studio、spotlight）。
-5. 手部宁少勿多：能一手扶腰、一手垂放就够；道具只写单手轻握的一件；没有道具写 empty hands。
-6. 角色一律 18 岁以上成年人；不写性化、暴露或暗示性动作。
-7. 每组 4–6 镜，全部英文（type 与 title 用中文，title 不超过 12 个字）。
+1. 每一镜必须同时给出六项：情境（situation）、表情（expression）、动作（pose）、手（hands）、机位（camera）、道具（props），每项都要具体到可以直接写进图片提示词。
+2. 情境写「她在做什么具体的事」：例如刚从舞台侧幕走出来、整理被风吹乱的披风、把道具横在身前打量、蹲下系鞋带；不要写「站着摆拍」这类空话。
+3. 动作写清重心在左腿还是右腿、身体朝向、下巴高度、肩线松紧；表情写清眼睛看哪里、眼睑开合、嘴角状态；手写清两只手各自在哪、手指是张开/并拢/轻握。
+4. 机位写清高度（平视/低机位/高机位）、角度（正面/三分之四侧面/背面回眸）、距离与构图占比；每镜至少两种机位，至少一镜不看镜头。
+5. 差异化：表情不重样；手的位置每镜不同；姿态覆盖站、坐/蹲、动态抓拍、道具镜头中的至少三种；至少一镜带这个角色标志性的小动作或道具互动。
+6. 每一镜至少两处只属于这个角色的具体细节（发饰、纹样、配色、道具、元素），不要写成通用模特。
+7. 姿势必须完整落在画面内：全身从头到鞋，头顶留空、脚下留地；不要写只拍半身或裁掉腿的机位。
+8. 只写正向画面，禁止 not / no / without 这类负向句；禁止摄影棚器材实景词（softbox、light stand、strobe、reflector、spotlight）。
+9. 手部宁少勿多：能一手扶腰、一手垂放就够；道具只写单手轻握的一件；没有道具写 empty hands。
+10. 角色一律 18 岁以上成年人；不写性化、暴露或暗示性动作。
+11. 每组 4–6 镜，全部英文（type 与 title 用中文，title 不超过 12 个字）。
 
 每镜字段：
 {"type":"A 情绪特写|B 不看她|C 动态抓拍|D 标志动作 + 道具|E 极端机位|F 坐蹲卧","title":"中文小标题","situation":"...","expression":"...","pose":"...","hands":"...","camera":"...","props":"..."}`
 
+/** User turn for the script model: character facts + the shots we already have
+ *  (smart add must not repeat an existing expression/pose/camera). */
+export function scriptUserText(details, count = 6, existing = []) {
+  const lines = [
+    `角色：${details?.character ?? ''}（${details?.series || '作品未知'}）`,
+    `性格：${details?.personality ?? ''}`,
+    `身份：${details?.identity ?? ''}`,
+    `元素/能力：${details?.element ?? ''}`,
+    `标志道具：${details?.props ?? 'empty hands'}`,
+    `发型发色：${details?.hair ?? ''}`,
+    `服装：${String(details?.costume ?? '').slice(0, 400)}`,
+  ]
+  if (Array.isArray(existing) && existing.length > 0) {
+    lines.push('', '已有分镜（新分镜必须与它们不重复；可延续同一组角色的性格与服装细节）：')
+    existing.slice(0, 12).forEach((shot, index) => {
+      lines.push(`${index + 1}. ${shot?.title ?? ''}｜情境：${shot?.situation ?? ''}｜表情：${shot?.expression ?? ''}｜动作：${shot?.pose ?? ''}｜手：${shot?.hands ?? ''}｜机位：${shot?.camera ?? ''}`)
+    })
+  }
+  lines.push('', `需要${existing?.length > 0 ? '新增' : '输出'}的镜头数量：${count}`, '按系统提示输出 JSON 数组。')
+  return lines.join('\n')
+}
+
+/** Normalise a model's shot array into the project shot shape. */
+export function normalizeShotItems(list, startIndex = 1) {
+  if (!Array.isArray(list) || list.length === 0) throw new Error('脚本不是数组')
+  return list.slice(0, 8).map((item, index) => {
+    const type = String(item?.type ?? '').trim() || `${String.fromCharCode(65 + ((startIndex - 1 + index) % 6))} 镜头`
+    const title = String(item?.title ?? '').trim() || `镜头${startIndex + index}`
+    return {
+      id: startIndex + index,
+      type,
+      title,
+      situation: String(item?.situation ?? '').trim(),
+      expression: String(item?.expression ?? '').trim(),
+      pose: String(item?.pose ?? '').trim(),
+      hands: String(item?.hands ?? '').trim(),
+      camera: String(item?.camera ?? '').trim(),
+      props: String(item?.props ?? 'empty hands').trim() || 'empty hands',
+      prompt: `${type}｜${title}`,
+    }
+  })
+}
+
 /** Ask the chat model for the character details (throws when unavailable). */
 export async function researchCharacter(config, { character, series = '' } = {}) {
   if (!llmConfigured(config)) throw new Error('未配置对话模型')
@@ -319,32 +449,6 @@ export async function researchCharacter(config, { character, series = '' } = {})
 /** Ask the chat model for the shot script (throws when unavailable). */
 export async function writeScript(config, details, count = 6) {
   if (!llmConfigured(config)) throw new Error('未配置对话模型')
-  const user = [
-    `角色：${details?.character ?? ''}（${details?.series || '作品未知'}）`,
-    `性格：${details?.personality ?? ''}`,
-    `身份：${details?.identity ?? ''}`,
-    `元素/能力：${details?.element ?? ''}`,
-    `标志道具：${details?.props ?? 'empty hands'}`,
-    `镜头数量：${count}`,
-    '按系统提示输出 JSON 数组。',
-  ].join('\n')
-  const text = await chatComplete(config, SCRIPT_SYSTEM, user)
-  const list = extractJson(text)
-  if (!Array.isArray(list) || list.length === 0) throw new Error('脚本不是数组')
-  return list.slice(0, 8).map((item, index) => {
-    const type = String(item.type ?? '').trim() || `${String.fromCharCode(65 + index)} 镜头`
-    const title = String(item.title ?? '').trim() || `镜头${index + 1}`
-    return {
-      id: index + 1,
-      type,
-      title,
-      situation: String(item.situation ?? '').trim(),
-      expression: String(item.expression ?? '').trim(),
-      pose: String(item.pose ?? '').trim(),
-      hands: String(item.hands ?? '').trim(),
-      camera: String(item.camera ?? '').trim(),
-      props: String(item.props ?? 'empty hands').trim() || 'empty hands',
-      prompt: `${type}｜${title}`,
-    }
-  })
+  const text = await chatComplete(config, SCRIPT_SYSTEM, scriptUserText(details, count))
+  return normalizeShotItems(extractJson(text), 1)
 }