koishi-plugin-p-draw 1.2.13 → 1.3.1

package/lib/comfy.js

@@ -0,0 +1,81 @@
+// ComfyUI 结果等待与输出提取。
+// waitComfyResult 依赖一个注入的 comfyGet（由 http 客户端提供），可独立单测。
+
+function outputImages(history) {
+  const images = []
+  const outputs = history.outputs || {}
+  if (outputs && typeof outputs === 'object') {
+    for (const nodeOutput of Object.values(outputs)) {
+      if (!nodeOutput || typeof nodeOutput !== 'object') continue
+      for (const image of nodeOutput.images || []) {
+        if (image && typeof image === 'object') images.push(image)
+      }
+    }
+  }
+  return images
+}
+
+// ------------------------------------------------------------------
+// ComfyUI 结果等待：优先 WebSocket 事件，失败/不可用回退轮询
+// ------------------------------------------------------------------
+function waitViaWebSocket(baseUrl, promptId, clientId, timeoutMs) {
+  return new Promise((resolve) => {
+    let socket
+    let timer = null
+    let settled = false
+    const finish = (ok) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      try { if (socket) socket.close() } catch (e) { /* ignore */ }
+      resolve(ok)
+    }
+    try {
+      const wsUrl = baseUrl.replace(/^https:/i, 'wss:').replace(/^http:/i, 'ws:') + `/ws?clientId=${encodeURIComponent(clientId)}`
+      socket = new WebSocket(wsUrl)
+    } catch (e) {
+      finish(false)
+      return
+    }
+    timer = setTimeout(() => finish(false), timeoutMs)
+    socket.onmessage = (ev) => {
+      let msg
+      try { msg = JSON.parse(String(ev.data)) } catch (e) { return }
+      if (!msg || typeof msg !== 'object') return
+      if (msg.type === 'execution_success' && msg.data && msg.data.prompt_id === promptId) { finish(true); return }
+      if (msg.type === 'execution_error' || msg.type === 'execution_interrupted') { finish(false) }
+    }
+    socket.onerror = () => finish(false)
+    socket.onclose = () => finish(false)
+  })
+}
+
+async function waitComfyResult(ctx, comfyGet, baseUrl, promptId, clientId, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs
+  if (typeof WebSocket !== 'undefined') {
+    const remaining = Math.max(0, deadline - Date.now())
+    try {
+      const viaWs = await waitViaWebSocket(baseUrl, promptId, clientId, remaining)
+      if (viaWs) {
+        try {
+          const data = await comfyGet(`/history/${promptId}`, 20000)
+          if (data && data[promptId]) return data[promptId]
+        } catch (e) { /* fall through */ }
+      }
+    } catch (e) { /* fall through to polling */ }
+  }
+  while (Date.now() < deadline) {
+    try {
+      const data = await comfyGet(`/history/${promptId}`, 20000)
+      if (data && data[promptId]) return data[promptId]
+    } catch (e) { /* transient */ }
+    await ctx.sleep(pollMs)
+  }
+  return null
+}
+
+module.exports = {
+  outputImages,
+  waitViaWebSocket,
+  waitComfyResult,
+}

package/lib/http.js

@@ -0,0 +1,74 @@
+// ComfyUI HTTP 客户端工厂：统一 GET/POST/GET-bytes，带超时与错误详情提取。
+// 不再需要在 apply 里重复三套 fetch + AbortController。
+
+// 构造 ComfyUI 专用客户端。getBaseUrl 在每次调用时求值，保证配置热更新生效。
+function buildComfyClient({ getBaseUrl }) {
+  async function get(apiPath, timeout = 20000) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeout)
+    try {
+      const res = await fetch(getBaseUrl() + apiPath, { signal: controller.signal })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      return await res.json()
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function post(apiPath, body, timeout = 20000) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeout)
+    try {
+      const res = await fetch(getBaseUrl() + apiPath, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+      if (!res.ok) {
+        // ComfyUI /prompt 校验失败时会返回 node_errors 等详细错误，尽量带出来便于排查
+        const text = await res.text().catch(() => '')
+        const detail = (() => {
+          try {
+            const data = JSON.parse(text)
+            const nodeErrors = (data && data.node_errors) || (data && data.error && data.error.extra_info && data.error.extra_info.node_errors) || null
+            if (nodeErrors && typeof nodeErrors === 'object') {
+              const lines = Object.entries(nodeErrors).map(([id, e]) => {
+                const cls = (e && e.class_type) || ''
+                const errs = (e && Array.isArray(e.errors) && e.errors.length)
+                  ? e.errors.map(x => `${(x && x.message) || ''}${x && x.details ? ' | ' + x.details : ''}`.trim()).join('; ')
+                  : JSON.stringify(e)
+                return `  #${id} [${cls}]: ${errs}`
+              })
+              if (lines.length) return `\n${lines.join('\n')}`
+            }
+            if (data && data.error) {
+              return `${data.error.message || ''}${data.error.details ? ' ' + data.error.details : ''}`.trim()
+            }
+          } catch (e) { /* ignore */ }
+          return text.slice(0, 800)
+        })()
+        throw new Error(`HTTP ${res.status}${detail ? '：' + detail : ''}`)
+      }
+      return await res.json()
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function getBytes(apiPath, timeout = 120000) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeout)
+    try {
+      const res = await fetch(getBaseUrl() + apiPath, { signal: controller.signal })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      return Buffer.from(await res.arrayBuffer())
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return { get, post, getBytes }
+}
+
+module.exports = { buildComfyClient }

package/lib/i18n.js

@@ -0,0 +1,152 @@
+// 中文文案与配置描述（zhCN），供 Config schema 与 i18n.define 使用。
+
+const zhCN = {
+  comfyuiBaseUrl: { $description: 'ComfyUI 地址' },
+  workflow: { $description: '工作流类型（内置 anima_t2i）' },
+  customWorkflowEnabled: { $description: '使用自定义 ComfyUI 工作流 JSON' },
+  customWorkflowPath: { $description: '自定义工作流 JSON 路径（相对插件目录）' },
+  customWorkflowOverrideParameters: { $description: '用插件参数覆盖自定义工作流参数' },
+  timeout: { $description: '单次生成超时（秒）' },
+  pollInterval: { $description: '生成状态查询间隔（秒）' },
+  unetName: { $description: '主模型文件名' },
+  clipName: { $description: '文本编码器文件名' },
+  vaeName: { $description: 'VAE 文件名' },
+  width: { $description: '默认宽度' },
+  height: { $description: '默认高度' },
+  allowedSizes: { $description: '可用尺寸列表（宽x高）' },
+  steps: { $description: '采样步数' },
+  cfg: { $description: 'CFG 强度' },
+  samplerName: { $description: '采样器' },
+  scheduler: { $description: '调度器' },
+  qualityPrefix: { $description: '质量词前缀' },
+  negativePrompt: { $description: '负面提示词' },
+  promptOptimizeEnabled: { $description: '启用自然语言优化（需要配置下方 LLM 接口）' },
+  llmBaseUrl: { $description: 'LLM 接口地址（OpenAI 兼容，例如 https://api.deepseek.com/v1）' },
+  llmApiKey: { $description: 'LLM API Key' },
+  llmModel: { $description: 'LLM 模型名（留空则不优化，原样生图）' },
+  llmMaxTokens: { $description: 'LLM 输出上限' },
+  webSearchEnabled: { $description: '启用联网搜索（指令里写“联网/搜索/查一下”等触发）' },
+  tavilyApiKey: { $description: 'Tavily API Key（联网搜索用，https://tavily.com 申请）' },
+  webSearchMaxResults: { $description: '联网搜索结果数量' },
+  webSearchDepth: { $description: '搜索深度（basic / advanced）' },
+  webSearchQueryTemplate: { $description: '搜索词模板（{prompt} 代表用户需求）' },
+  promptOptimizeTemplate: { $description: '自然语言优化模板（支持 {theme} {search_block} 占位符）' },
+  fixedCharacters: { $description: '固定角色（格式：角色名=tags）' },
+  artistPresets: { $description: '画师组（格式：名称=tags）' },
+  activeArtistPreset: { $description: '启用的画师组名称' },
+  defaultArtistTags: { $description: '备用画师 tags' },
+  styleTags: { $description: '画风 tags' },
+  queueEnabled: { $description: '启用生成队列（逐张顺序执行）' },
+  queueMaxRequests: { $description: '队列最大任务数（0 表示不限制）' },
+  batchMax: { $description: '单次指令最多生成的张数（支持 x3 / 3张 / --数量 3 等写法）' },
+  price: { $description: '一张图消耗的 P 点' },
+  multiPrice: { $description: '多人指令（p-draw 多人）单张消耗的 P 点' },
+  couponPrice: { $description: '提示词优化券单价（P 点/张，购买询问时显示）' },
+  couponAskTimeout: { $description: '提示词优化券确认等待时间（秒）' },
+  img2imgDenoise: { $description: '普通以图生图（p-draw i2i）的去噪强度，越小越接近原图（建议 0.4-0.7）' },
+  i2iMode: { $description: 'i2i 模式选择方式：ask=每次询问 / style=直接换风格（漫画化）/ ootd=直接换装换姿势 / plain=普通 img2img' },
+  i2iAskTimeout: { $description: 'i2i 模式询问等待时间（秒）' },
+  seriesAskTimeout: { $description: '连续图 LLM 使用确认等待时间（秒）' },
+  i2iStyleDenoise: { $description: '换风格模式（漫画化）的去噪强度，越大风格变化越彻底（建议 0.7-0.85）' },
+  i2iOotdDenoise: { $description: '换装换姿势模式（保留角色）的去噪强度（建议 0.5-0.6）' },
+  i2iControlNetStrength: { $description: '换风格模式的 ControlNet 强度，越大构图锁得越死（建议 0.5-0.8）' },
+  i2iIPAdapterPath: { $description: 'Anima IP-Adapter 模型文件路径（换装换姿势模式保脸用；需安装 comfyui-anima-ipadapter 节点并把模型路径填到这里）' },
+  i2iIPAdapterWeight: { $description: '换装换姿势模式的 IP-Adapter 权重，越大角色特征保留越强（建议 0.6-1.0）' },
+  controlNetModel: { $description: 'ControlNet 模型文件名（留空自动检测 Qwen/Anima 系 ControlNet；需放到 ComfyUI/models/controlnet）' },
+  taggerEnabled: { $description: 'i2i 前自动识图（需 ComfyUI 安装 WD14 Tagger 节点与模型；识别出的标签会注入提示词优化）' },
+  taggerModel: { $description: '识图模型名（WD14 Tagger 节点里可选模型）' },
+  taggerThreshold: { $description: '识图标签置信度阈值' },
+  taggerCharacterThreshold: { $description: '识图角色标签置信度阈值' },
+  adminUsers: { $description: '免 P 点管理员用户 ID 列表' },
+  outputLogs: { $description: '是否在控制台输出详细日志' },
+  multiVerifyEnabled: { $description: '多人图生成后启用视觉校验（需配置下方视觉模型）' },
+  multiVerifyPassScore: { $description: '多人视觉校验合格分数（0-10）' },
+  multiCandidateCount: { $description: '多人候选采样数量（校验失败时最多重试 候选数-1 次）' },
+  multiSendDegradedCandidate: { $description: '多人候选全部不达标时仍发送最优候选' },
+  verifyLlmBaseUrl: { $description: '视觉校验 LLM 接口地址（OpenAI 兼容；留空则跳过校验）' },
+  verifyLlmApiKey: { $description: '视觉校验 LLM API Key' },
+  verifyLlmModel: { $description: '视觉校验 LLM 模型名（需支持图片输入，如 qwen-vl）' },
+  adminOnly: { $description: '仅管理员可用（adminUsers 中的用户）' },
+  allowedUserIds: { $description: '用户白名单（QQ 号，留空表示不限制）' },
+  blockedUserIds: { $description: '用户黑名单（QQ 号，黑名单优先于白名单）' },
+  allowedGroupIds: { $description: 'QQ 群白名单（群号，留空表示不限制）' },
+  blockedGroupIds: { $description: 'QQ 群黑名单（群号，黑名单优先于白名单）' },
+  commands: {
+    'p-draw': {
+      description: '连接本地 ComfyUI 生图，消耗 P 点',
+      messages: {
+        'not-permitted': 'ComfyUI 助手已关闭，或当前用户没有使用权限。',
+        usage: 'p-draw 帮助（本指令名可自行更换，如 /anm）：\n\n【生成】\n  p-draw <描述>\n  例：p-draw 一个女孩，白色裙子，立绘，简单背景\n  可加 --seed 数字 固定种子（单张 / 批量 / 连续图均支持）\n\n【多人生成】\n  p-draw 多人 <描述>（2-4 人画面）\n  例：p-draw 多人 左边若叶睦抱着吉他，右边千早爱音牵着她的手\n\n【连续图】\n  p-draw 连续 <角色>：<阶段1> → <阶段2> → ...\n  例：p-draw 连续 少女：清纯校服 → 换上晚礼服 → 华丽登场\n  全阶段共用同一 seed，角色外观尽量一致；可加 --seed 数字 固定种子\n  阶段分隔：→ / -> / |\n\n【批量张数】\n  描述后加 x3 / ×3 / 3张 / 三张 / --数量 3，例：p-draw 一个女孩 x3\n  多张按 张数×单价 一次性扣 P 点，余额不足则不生成\n\n【尺寸】\n  竖图 / 横图 / 方图 / 长竖图 / 宽屏，或 1024x1536：描述 / --尺寸 1216x832\n  例：p-draw 竖图：狐莉站在梨花树下\n\n【原样模式】\n  p-draw 无优化 masterpiece, best quality, 1girl, solo\n\n【提示词优化】\n  配置 LLM（llmBaseUrl/llmModel）后：\n  全局优化开启 → 每次自动把中文描述转成 Danbooru tags\n  全局优化关闭 → 生图时询问是否使用「提示词优化券」（p-shop 购买，每张图扣 1 张）：\n    有券 → 确认后消耗券并优化，拒绝则取消本次生图\n    没券 → 询问是否购买（显示价格），确认后购买并消耗、优化生图；\n          拒绝一次会再次警告，再拒绝则直接生图（不优化）；\n          P 点不足买不起券时，会询问是否仍然生图\n  无优化 <tags> 原样生图，不耗券\n  连续图逐阶段强制优化；多人指令依赖 LLM 规划（未配置会提示）\n\n【画师组】\n  创建画师组 名称=tags / 追加画师组 名称=tags / 切换画师组 名称 / 查看画师组 / 删除画师组 名称\n\n【固定角色】\n  添加角色 名称=tags\n\n【以图生图】\n  p-draw i2i <描述>，并在同一条消息里附一张原图（文件/截图/链接均可）\n  例：p-draw i2i 换成晚礼服，背景换成舞台灯光\n  发送后会询问处理模式（可配置 i2iMode 固定模式跳过询问）：\n    ① 换风格（漫画化）：保留原图构图，转成二次元画风（需 ControlNet）\n    ② 换装换姿势：保留角色长相，重新设计服装/姿势/场景（需 Anima IP-Adapter）\n    ③ 取消：不生成\n  可加 --denoise 0.6 单独调整强度；未装 ControlNet/IPAdapter 时自动回退普通 img2img\n\n【模型】\n  p-draw 模型（查看当前与可用模型） / p-draw 模型 名称（切换，支持模糊匹配）/ p-draw 模型 默认（重置）\n  例：p-draw 模型 anima-aesthetic\n\n【状态】\n  p-draw 状态（查看 ComfyUI 连接状态与模型可用性）',
+        'account-notExists': '君现在还没有 p 点，请先签到哦',
+        'no-enough-p': '君的 p 点不够 {0}p 哦，先去签个到吧qwq',
+        'no-prompt': '请提供画面描述，例如：p-draw 一个女孩，白色裙子',
+        generating: '正在生成中，请稍候...',
+        charged: '已扣除 {0} P 点，出图后余额会再核对。',
+        queued: '已加入生成队列，当前第 {0} 位（队列上限 {1}）。',
+        'prompt-degraded': '提示词优化服务不可用{0}，本次已使用原始提示词继续生成；结果可能不符合 Danbooru Tag 预期。',
+        'token-used': '已消耗 {0} 张提示词优化券，本次每张图都会使用 LLM 提示词优化。',
+        'token-short': '提示词优化券不足（需 {0} 张，现有 {1} 张），本次未使用 LLM 优化。',
+        'coupon-ask-use': '你有提示词优化券 {0} 张，本次生图需要消耗 {1} 张。\n是否使用提示词优化券进行 LLM 优化？\n（回复「是」使用 / 回复「否」取消本次生图）',
+        'coupon-use-confirmed': '已消耗 {0} 张提示词优化券，本次每张图都会使用 LLM 优化。',
+        'coupon-use-cancelled': '已取消本次生图（未使用提示词优化券）。',
+        'coupon-cancelled': '未收到有效回复，本次操作已取消。',
+        'coupon-ask-buy': '提示词优化券不足（需 {0} 张，现有 {1} 张）。\n提示词优化券价格：{2} P/张，本次共需 {3} P。\n是否购买并使用？\n（回复「是」购买 / 回复「否」不购买）',
+        'coupon-buy-warn': '不使用提示词优化券的话，生成的图可能不好看。\n是否仍要购买并使用提示词优化券？\n（回复「是」购买 / 回复「否」直接生图）',
+        'coupon-bought-used': '已购买 {0} 张提示词优化券（扣除 {1} P），并消耗 {0} 张用于本次 LLM 优化。',
+        'coupon-buy-cancelled': '好的，本次不使用提示词优化券，直接生图。',
+        'coupon-buy-pshort': 'P 点不足，无法购买提示词优化券（需 {0} P，现有 {1} P）。\n是否仍然生图（不使用 LLM 优化）？\n（回复「是」生图 / 回复「否」取消本次生图）',
+        'coupon-consume-fail': '提示词优化券操作失败，本次未使用 LLM 优化。',
+        'generate-failed': '生成失败：{0}',
+        'generate-ok': '已扣除 {0} P 点，seed={1}',
+        'generate-ok-batch': '已扣除 {0} P 点，共 {1} 张（seed：{2}）',
+        'batch-partial': '本次共生成 {0}/{1} 张，失败 {2} 张：{3}',
+        'batch-limit': '每次最多生成 {0} 张，本次已按 {0} 张处理。',
+        'batch-count': '本次共生成 {0} 张。',
+        'artist-format': '请使用「名称=tags」的格式。例：p-draw 创建画师组 千代风格=@artist_a, @artist_b,',
+        'artist-created': '已保存并启用画师组「{0}」：\n{1}',
+        'artist-appended': '已追加画师组「{0}」：\n{1}',
+        'artist-default-appended': '已追加默认画师 tags：\n{0}',
+        'artist-use-format': '请写要启用的画师组名称。例：p-draw 切换画师组 千代风格',
+        'artist-default': '已切回默认画师 tags。',
+        'artist-not-found': '没有找到画师组「{0}」。',
+        'artist-used': '已启用画师组「{0}」：\n{1}',
+        'artist-deleted': '已删除画师组「{0}」。',
+        'artist-delete-format': '请写要删除的画师组名称。例：p-draw 删除画师组 千代风格',
+        'character-format': '请使用「名称=tags」的格式。例：p-draw 添加角色 狐莉=1girl, solo, fox girl',
+        'character-created': '已保存角色「{0}」：\n{1}',
+        'multi-usage': '多人生图：p-draw 多人 <描述>（2-4 人画面）\n例：p-draw 多人 左边若叶睦抱着吉他，右边千早爱音牵着她的手',
+        'multi-verify-passed': '多人图已通过视觉校验（{0} 分）。',
+        'multi-verify-failed': '多人图未通过视觉校验{0}，已重试 {1} 次。',
+        'multi-verify-degraded': '多人图校验失败，已发送最优候选{0}。',
+        'multi-verify-discarded': '多人图校验失败且未启用降级发送，本次图片不发送。',
+        'multi-degraded': '多人视觉校验不可用{0}，本次已直接发送生成结果。',
+        'multi-verify-error': '多人视觉校验调用失败：{0}',
+        'series-usage': '连续图：p-draw 连续 <角色>：<阶段1> → <阶段2> → ...\n例：p-draw 连续 少女：清纯校服 → 换上晚礼服 → 华丽登场\n或用 | 分隔，可加 --seed 固定种子保证角色一致。',
+        'series-llm-ask': '是否使用 LLM 优化连续图各阶段提示词？\n1. 是（使用 LLM，自动整理成 Danbooru tags）\n2. 否（不使用 LLM，直接用你输入的内容）\n3. 取消（不生成）\n请回复 1 / 2 / 3',
+        'series-llm-invalid': '未识别的回答，请回复 1（使用 LLM）/ 2（不使用 LLM）/ 3（取消）。',
+        'series-no-llm': '本次未使用 LLM 优化，直接使用你输入的描述/tags。',
+        'series-ok': '已扣除 {0} P 点，共 {1} 张连续图（seed={2}）',
+        'model-usage': '当前模型：{0}\n可用模型：\n{1}\n用法：p-draw 模型 <名称>（支持模糊匹配，如 anima-aesthetic）；p-draw 模型 默认 恢复默认。',
+        'model-switched': '已切换为模型「{0}」，对之后的生图生效。',
+        'model-reset': '已恢复默认模型「{0}」。',
+        'model-not-found': '未找到模型「{0}」。可用模型：\n{1}',
+        'model-no-draw': '「模型」只能用来切换/查看模型，不能生图。请先用「p-draw 模型 <名称>」切换，再单独发送要画的内容。',
+        'model-ambiguous': '「{0}」匹配到多个模型，请写得更具体些：\n{1}',
+        'no-optimize': '提示：本次未使用 LLM 优化（{0}）。',
+        'i2i-no-image': 'i2i（以图生图）需要附一张原图。用法：p-draw i2i <描述>，并在同一条消息里带上图片。',
+        'i2i-upload-fail': '原图上传 ComfyUI 失败：{0}',
+        'i2i-no-custom-workflow': 'i2i（以图生图）暂不支持自定义工作流（customWorkflowEnabled），请关闭后再试。',
+        'i2i-mode-ask': '请选择 i2i 处理模式：\n① 换风格（漫画化）——保留原图构图，转成二次元画风\n② 换装换姿势——保留角色长相，重新设计服装/姿势/场景\n③ 取消——不生成\n回复 1 / 2 / 3 或对应名称即可。',
+        'i2i-mode-invalid': '没有理解你的选择。请回复 ①换风格（漫画化） / ②换装换姿势 / ③取消。',
+        'i2i-mode-cancelled': '已取消本次 i2i 生图。',
+        'i2i-mode-style': '已选择【换风格（漫画化）】：保留原图构图，转成二次元画风。',
+        'i2i-mode-ootd': '已选择【换装换姿势】：保留角色长相，重新设计服装/姿势/场景。',
+        'i2i-no-controlnet': '未检测到可用的 Anima ControlNet-LLLite，本次「换风格」将使用普通 img2img，构图保留效果会弱一些。',
+        'i2i-no-ipadapter': '未检测到可用的 Anima IP-Adapter，本次「换装换姿势」将使用普通 img2img，角色保留效果会弱一些。',
+        'multi-no-llm': '多人指令需要 LLM 规划，但当前未配置 llmBaseUrl / llmModel。请管理员在配置中填写后使用。',
+      },
+    },
+  },
+}
+
+module.exports = { zhCN }

package/lib/media.js

@@ -0,0 +1,22 @@
+// 消息媒体来源处理。
+// OneBot 不一定能读取机器人进程本地的 file:// 路径，因此发送前转换为 Buffer。
+
+const fsp = require('fs/promises')
+const { fileURLToPath } = require('url')
+
+async function materializeImageSource(source, readFile = fsp.readFile) {
+  if (typeof source !== 'string' || !/^file:\/\//i.test(source)) return source
+  let filePath
+  try {
+    filePath = fileURLToPath(source)
+  } catch (e) {
+    return source
+  }
+  try {
+    return await readFile(filePath)
+  } catch (e) {
+    return source
+  }
+}
+
+module.exports = { materializeImageSource }

package/lib/multi.js

@@ -0,0 +1,262 @@
+// 多人规划纯函数库（移植自 anima multi_person_prompt / command_actions）。
+// 不依赖 koishi，可独立单测。
+
+const MULTI_PERSON_NEGATIVE_TAGS = [
+  'split screen', 'comic panels', 'multiple views', 'character sheet',
+  'duplicate characters', 'cloned character', 'extra person', 'extra girl', 'extra boy',
+  'twins', 'merged bodies', 'fused characters',
+]
+
+const MULTI_SAFE_SLOTS = new Set(['left', 'right', 'center', 'foreground', 'background', 'far left', 'far right'])
+const MULTI_UNSAFE_COMPOSITION_MARKERS = [
+  'split screen', 'panel', 'multiple views', 'alternate views', 'character sheet',
+  'top left', 'top right', 'bottom left', 'bottom right',
+]
+const MULTI_SAFE_SPATIAL_MODES = new Set(['shared_contact', 'shared_scene', 'explicit_positions'])
+
+function buildMultiPersonPlanPrompt(userPrompt, fixedCharacters = {}) {
+  const fixedNote = Object.keys(fixedCharacters).length
+    ? `Locally saved characters explicitly mentioned by the user:\n${JSON.stringify(fixedCharacters, null, 2)}`
+    : 'No locally saved character name was detected.'
+  return `Plan one coherent Anima image containing 2 to 4 people.
+
+Use the user's requested identities, count, clothing, expressions, props, positions, and relationships. You may freely design compatible mutable details, background, lighting, and atmosphere when the user leaves them open.
+
+Separate every person into an independent semantic block. Position slots are bookkeeping only and must never describe separate regions, panels, views, or sides of the image. Prefer one shared central group. Use explicit positions only when the user directly asks for left/right or foreground/background placement. Never use top_left, top_right, bottom_left, bottom_right, upper, lower, panel, or "side of the image".
+
+For an existing named character, preserve the user's written name in "name" and provide the most likely Danbooru character tag in "danbooru_candidate". For an original or generic person, leave "danbooru_candidate" empty.
+
+When a person matches one of the locally saved characters below, their saved tags are authoritative. Leave "appearance" empty and do not restate or alter their hair, eyes, species, ears, tail, body type, age, or fixed accessories. Only plan mutable clothing, expression, pose, and props.
+
+Return JSON only with this exact shape:
+{
+  "count_tags": ["2girls"],
+  "common_tags": ["medium shot", "outdoors"],
+  "characters": [
+    {
+      "slot": "left",
+      "name": "character name from the user",
+      "danbooru_candidate": "romanized_character_tag",
+      "role": "short semantic role such as rider or supporting girl",
+      "visual_label": "distinctive visible label such as white-haired fox girl",
+      "identity_anchors": ["3 to 6 short appearance tags"],
+      "emphasized_anchors": ["0 to 3 explicitly requested unusual traits"],
+      "appearance": "Visible identity traits for a non-fixed character only; empty for a locally saved character.",
+      "clothing": "One concise English clothing phrase.",
+      "expression": "One concise English expression phrase.",
+      "pose": "One concise English body pose that does not repeat the interaction.",
+      "props": ["visible prop held or worn by this person"]
+    },
+    {
+      "slot": "right",
+      "name": "second character name from the user",
+      "danbooru_candidate": "romanized_character_tag",
+      "appearance": "",
+      "clothing": "One concise English clothing phrase.",
+      "expression": "One concise English expression phrase.",
+      "pose": "One concise English body pose.",
+      "props": []
+    }
+  ],
+  "relationship_tag": "holding hands",
+  "interactions": [
+    "Character A is holding Character B's hand."
+  ],
+  "spatial_mode": "shared_contact",
+  "composition": "A single unified full-frame composition using one camera view."
+}
+
+Rules:
+- Include exactly 2 to 4 character objects.
+- count_tags must agree with the number and genders requested by the user.
+- common_tags contain only shared scene, framing, camera, lighting, atmosphere, and count tags.
+- relationship_tag is one short Danbooru-style relationship or action tag and appears immediately after the count tags in the final prompt.
+- Do not put character names or character-specific appearance in common_tags.
+- role is optional semantic bookkeeping and is not used to identify a person in the final interaction sentence.
+- visual_label must be a unique 2 to 6 word visible description derived from identity_anchors, such as "white-haired fox girl" or "silver-haired vampire girl". Do not use names, ordinal labels, rider, supporter, top, bottom, left, or right as visual_label.
+- identity_anchors must contain only 3 to 6 concise visible identity traits. For locally saved characters, select them only from the saved defining tags.
+- emphasized_anchors may contain at most 3 identity_anchors that the user explicitly requested and that are unusual, contrastive, or likely to be confused between people. Never invent emphasis.
+- For locally saved characters, appearance must be empty and saved defining tags must never be contradicted.
+- Do not output quality tags, safety tags, artist tags, Markdown, or explanations.
+- Keep character fields and relationships visually concrete.
+- Preserve the user's explicit interaction direction and gaze direction.
+- Put the complete directed relationship in exactly one interactions entry. Character pose fields must not repeat the relationship.
+- Refer to people inside interactions exclusively as Character A, Character B, Character C, or Character D. Never use their names, translated names, or Danbooru tags there.
+- spatial_mode must be shared_contact for physical interaction, shared_scene for a non-contact group, or explicit_positions only when the user explicitly requests relative positions.
+- Prefer a single coherent moment rather than multiple competing actions.
+- composition must use affirmative language to request one unified full-frame camera view.
+
+${fixedNote}
+
+User request:
+${userPrompt}
+`
+}
+
+function cleanMultiText(value, limit) {
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, limit).trim()
+}
+
+function multiStringTuple(value, limit, itemLimit) {
+  if (!Array.isArray(value)) return []
+  const result = []
+  for (const item of value) {
+    const text = cleanMultiText(item, itemLimit)
+    if (text) result.push(text)
+  }
+  return result.slice(0, limit)
+}
+
+function normalizeMultiSlot(value) {
+  const slot = cleanMultiText(value, 40).toLowerCase().replace(/_/g, ' ').replace(/-/g, ' ').replace(/\s+/g, ' ').trim()
+  return MULTI_SAFE_SLOTS.has(slot) ? slot : ''
+}
+
+function parseMultiPersonPlan(text) {
+  let raw = String(text || '').trim()
+  raw = raw.replace(/^```(?:json)?\s*/i, '')
+  raw = raw.replace(/\s*```$/, '')
+  const match = raw.match(/\{[\s\S]*\}/)
+  if (match) raw = match[0]
+  let data
+  try {
+    data = JSON.parse(raw)
+  } catch (e) {
+    return null
+  }
+  if (!data || typeof data !== 'object') return null
+  const rawCharacters = data.characters
+  if (!Array.isArray(rawCharacters) || rawCharacters.length < 2 || rawCharacters.length > 4) return null
+  if (rawCharacters.some(item => !item || typeof item !== 'object')) return null
+
+  const defaultSlots = {
+    2: ['left', 'right'],
+    3: ['left', 'center', 'right'],
+    4: ['far left', 'left', 'right', 'far right'],
+  }[rawCharacters.length]
+  const proposedSlots = rawCharacters.map(item => normalizeMultiSlot(item.slot))
+  if (
+    proposedSlots.some(slot => !slot) ||
+    new Set(proposedSlots).size !== proposedSlots.length ||
+    (rawCharacters.length === 2 && !(new Set(proposedSlots).size === 2 && ['left', 'right'].every(s => proposedSlots.includes(s)) || ['foreground', 'background'].every(s => proposedSlots.includes(s))))
+  ) {
+    proposedSlots.splice(0, proposedSlots.length, ...defaultSlots)
+  }
+
+  const characters = proposedSlots.map((slot, index) => {
+    const item = rawCharacters[index]
+    return {
+      slot,
+      name: cleanMultiText(item.name, 120),
+      danbooru_candidate: cleanMultiText(item.danbooru_candidate, 160),
+      appearance: cleanMultiText(item.appearance, 500),
+      clothing: cleanMultiText(item.clothing, 400),
+      expression: cleanMultiText(item.expression, 240),
+      pose: cleanMultiText(item.pose, 400),
+      props: multiStringTuple(item.props, 12, 120),
+      role: cleanMultiText(item.role, 80),
+      visual_label: cleanMultiText(item.visual_label, 100),
+      identity_anchors: multiStringTuple(item.identity_anchors, 6, 100),
+      emphasized_anchors: multiStringTuple(item.emphasized_anchors, 3, 100),
+    }
+  })
+
+  const countTags = multiStringTuple(data.count_tags, 8, 80)
+  const commonTags = multiStringTuple(data.common_tags, 50, 100)
+  const interactions = multiStringTuple(data.interactions, 1, 500)
+  const composition = cleanMultiText(data.composition, 700)
+  let spatialMode = cleanMultiText(data.spatial_mode, 40).toLowerCase()
+  const relationshipTag = cleanMultiText(data.relationship_tag, 120)
+  if (!MULTI_SAFE_SPATIAL_MODES.has(spatialMode)) spatialMode = interactions.length ? 'shared_contact' : 'shared_scene'
+  let compositionSafe = composition
+  if (MULTI_UNSAFE_COMPOSITION_MARKERS.some(marker => compositionSafe.toLowerCase().includes(marker))) compositionSafe = ''
+  return {
+    count_tags: countTags.length ? countTags : [`${characters.length}people`],
+    common_tags: commonTags,
+    characters,
+    interactions,
+    composition: compositionSafe,
+    spatial_mode: spatialMode,
+    relationship_tag: relationshipTag,
+  }
+}
+
+function renderMultiPersonCharacter(character, opts = {}) {
+  const {
+    alias = '', resolvedIdentity = '', fixedTags = '', groupedContact = false,
+    explicitPositions = false, identityAnchors = [], includePose = true, asTagStream = false,
+  } = opts
+  let label = String(alias || character.visual_label || character.role || '').trim()
+  if (explicitPositions && character.slot) label = `${character.slot} ${label}`
+  const identity = String(resolvedIdentity || character.danbooru_candidate || '').trim()
+  const details = []
+  if (identity && !fixedTags) details.push(identity)
+  if (identityAnchors.length) {
+    details.push(...identityAnchors)
+  } else if (fixedTags) {
+    for (const part of fixedTags.split(',')) {
+      const t = part.trim().replace(/^ +| +$/g, '').replace(/^\(|\)$/g, '')
+      if (t) details.push(t)
+    }
+  }
+  if (!identityAnchors.length && !fixedTags && character.appearance) details.push(character.appearance)
+  if (character.clothing) details.push(character.clothing)
+  if (character.expression) details.push(character.expression)
+  if (includePose && character.pose) details.push(character.pose)
+  if (character.props && character.props.length) details.push(...character.props)
+  const joined = details.filter(Boolean).join(', ')
+  if (asTagStream) return [label, joined].filter(Boolean).join(', ')
+  return `${label}: ${joined}.`
+}
+
+// ------------------------------------------------------------------
+// 多人尺寸自动选择（移植自 anima command_actions multi_person 分支）
+// ------------------------------------------------------------------
+function multiPersonAutoSize(prompt, allowedSizes) {
+  if (!Array.isArray(allowedSizes) || !allowedSizes.length) return null
+  const promptLower = String(prompt || '').toLowerCase()
+  // 修复：JS 中 \b 边界不识别 CJK（三/四 与两侧都非 \w，\b 永远不成立），
+  // 导致「三个人/四人」等中文人数无法触发宽屏尺寸。改用否定数字 lookbehind 匹配。
+  const threeOrMore = /(?<!\d)(?:三|四)\s*(?:人|个|名)|(?<!\d)(?:3|4)(?:\s*(?:人|个|名)|(?:girls?|boys?|people))\b/i.test(promptLower)
+  const verticallyStacked = [
+    '骑在肩', '骑肩', '肩膀上', '背着', '抱起', '扑倒', '压在', '上下叠',
+    'on the shoulders', 'piggyback', 'carrying', 'on top of', 'stacked',
+  ].some(marker => promptLower.includes(marker))
+  const physicalContact = [
+    '牵手', '拥抱', '接吻', '搂着', '抱着', '挽着',
+    'holding hands', 'hugging', 'embracing', 'kissing', 'arm around',
+  ].some(marker => promptLower.includes(marker))
+  const target = threeOrMore
+    ? [1216, 832]
+    : verticallyStacked
+      ? [1024, 1536]
+      : physicalContact
+        ? [1024, 1024]
+        : [1152, 896]
+  let best = allowedSizes[0]
+  let bestScore = Infinity
+  for (const size of allowedSizes) {
+    const ratioDiff = Math.abs(size[0] / size[1] - target[0] / target[1])
+    const areaDiff = Math.abs(size[0] * size[1] - target[0] * target[1])
+    const score = ratioDiff * 10000 + areaDiff
+    if (score < bestScore) {
+      bestScore = score
+      best = size
+    }
+  }
+  return best
+}
+
+module.exports = {
+  MULTI_PERSON_NEGATIVE_TAGS,
+  MULTI_SAFE_SLOTS,
+  MULTI_UNSAFE_COMPOSITION_MARKERS,
+  MULTI_SAFE_SPATIAL_MODES,
+  buildMultiPersonPlanPrompt,
+  cleanMultiText,
+  multiStringTuple,
+  normalizeMultiSlot,
+  parseMultiPersonPlan,
+  renderMultiPersonCharacter,
+  multiPersonAutoSize,
+}