tavern-harness 0.1.0

package/src/core/prompts.ts

@@ -0,0 +1,254 @@
+import type {
+  ChatParticipant,
+  ChatSession,
+  NetworkMessage,
+} from '../types/models';
+import { sanitizeHistoryContentForModel } from './openai';
+import { translate } from './i18n';
+import { NEW_TOPIC_MARKER } from './toolDefinitions';
+
+// ============================================================
+// 提示词组装 — 与 MainViewModel.buildNpcSystemPrompt 等一致
+// ============================================================
+
+export function buildNpcSystemPrompt(
+  npcPrompt: string,
+  worldBookContent?: string | null,
+  userPersonaPrompt?: string | null
+): string {
+  return (
+    npcPrompt +
+    (worldBookContent ? `\n\n=== ${translate('prompt.worldBook')} ===\n${worldBookContent}` : '') +
+    (userPersonaPrompt ? `\n\n=== ${translate('prompt.userInfo')} ===\n${userPersonaPrompt}` : '')
+  );
+}
+
+export function buildGroupSystemPrompt(
+  activeSpeakerName: string,
+  activeNpcPrompt: string,
+  worldBookContent?: string | null,
+  userPersonaPrompt?: string | null,
+  requestPayload?: {
+    allSpeakerNames: string[];
+    mentionOnlyMode?: boolean;
+  }
+): string {
+  const others = (requestPayload?.allSpeakerNames ?? []).filter((n) => n !== activeSpeakerName);
+  const playerName = 'User';
+
+  return (
+    `You are participating in a multi-character conversation. Reply only as ${activeSpeakerName}.\n` +
+    `Never write dialogue for another participant.\n` +
+    `Write only ${activeSpeakerName}'s message body. Do not begin your reply with a speaker label such as [${activeSpeakerName}], ${activeSpeakerName}:, or any other [name] prefix; the application already identifies the speaker.\n` +
+    (others.length > 0
+      ? `The other participants are: ${others.join(', ')}.\nThe user (a participant named "${playerName}") may speak at any moment — when they do, respond naturally as ${activeSpeakerName}.\n`
+      : '') +
+    `Messages prefixed with [${translate('prompt.roleTag')}] are utterances by that participant; messages prefixed with [${playerName}] are the user's.\n` +
+    (requestPayload?.mentionOnlyMode
+      ? `End your reply by mentioning exactly one next participant with @name. If your reply already mentions a participant, do not add another mention.\n`
+      : `When you need to direct the next speaker, you may use @${translate('prompt.roleTag')} in your reply to call on another participant.\n`) +
+    `\n=== ${activeSpeakerName} ===\n` +
+    activeNpcPrompt +
+    (worldBookContent ? `\n\n=== ${translate('prompt.worldBook')} ===\n${worldBookContent}` : '') +
+    (userPersonaPrompt ? `\n\n=== ${translate('prompt.userInfo')} ===\n${userPersonaPrompt}` : '')
+  );
+}
+
+export const STANDARD_SYSTEM_PROMPT = 'You are a helpful assistant.';
+
+// ============================================================
+// 历史消息 → 网络消息（GROUP 角色折叠 / 附件 / 思考清理）
+// ============================================================
+
+export function buildNetworkMessagesForSession(p: {
+  messages: Array<{
+    role: string;
+    content: string;
+    speakerParticipantId: number | null;
+    speakerName: string | null;
+    thinkingContent: string | null;
+    toolCallsJson: string;
+    toolCallId: string | null;
+    attachments: string[];
+  }>;
+  session: ChatSession | null;
+  participants: ChatParticipant[];
+  activeSpeakerParticipantId: number | null;
+}): NetworkMessage[] {
+  const { session, participants, activeSpeakerParticipantId } = p;
+  const messages = trimMessagesForNewTopic(p.messages, session);
+  const result: NetworkMessage[] = [];
+  const participantMap = new Map(participants.map((pp) => [pp.participantId, pp]));
+  const isGroup = session?.mode === 'GROUP';
+  const omittedToolCallIds = new Set<string>();
+  if (isGroup) {
+    for (const m of messages) {
+      if (m.role !== 'assistant' || m.speakerParticipantId === activeSpeakerParticipantId) continue;
+      for (const toolCall of parseToolCalls(m.toolCallsJson)) omittedToolCallIds.add(toolCall.id);
+    }
+  }
+
+  for (const m of messages) {
+    if (m.role === 'tool') {
+      if (m.toolCallId != null && omittedToolCallIds.has(m.toolCallId)) continue;
+      result.push({
+        role: 'tool',
+        content: m.content,
+        tool_call_id: m.toolCallId ?? undefined,
+      });
+      continue;
+    }
+    if (m.role === 'system') {
+      result.push({ role: 'system', content: m.content });
+      continue;
+    }
+
+    const speakerIsActive =
+      m.speakerParticipantId != null && m.speakerParticipantId === activeSpeakerParticipantId;
+    const toolCalls = parseToolCalls(m.toolCallsJson);
+    if (m.role === 'assistant' && toolCalls.length > 0) {
+      if (!isGroup || speakerIsActive) {
+        result.push({
+          role: 'assistant',
+          content: sanitizeHistoryContentForModel(m.content),
+          tool_calls: toolCalls,
+        });
+      } else {
+        const content = sanitizeHistoryContentForModel(m.content);
+        if (content.length > 0) {
+          const hasLeadingLabel = /^\[[^\]\r\n]+\]/.test(content);
+          const speaker = m.speakerParticipantId != null ? participantMap.get(m.speakerParticipantId) : undefined;
+          const label = speaker?.displayName ?? m.speakerName ?? '用户';
+          result.push({ role: 'user', content: hasLeadingLabel ? content : `[${label}] ${content}` });
+        }
+      }
+      continue;
+    }
+
+    if (isGroup) {
+      if (m.role === 'assistant' && speakerIsActive) {
+        result.push({
+          role: 'assistant',
+          content: sanitizeHistoryContentForModel(m.content),
+        });
+        continue;
+      }
+      const hasLeadingLabel = /^\[[^\]\r\n]+\]/.test(m.content);
+      if (hasLeadingLabel) {
+        result.push({ role: 'user', content: buildContentWithAttachments(m.content, m.attachments) });
+        continue;
+      }
+      const isPlayer = m.role === 'user' && m.speakerParticipantId == null;
+      // 折叠成 user 消息，前缀 [标签]
+      const speaker = m.speakerParticipantId != null ? participantMap.get(m.speakerParticipantId) : undefined;
+      const label = isPlayer || m.speakerParticipantId == null ? '用户' : (speaker?.displayName ?? m.speakerName ?? '用户');
+      const text = buildContentWithAttachments(m.content, m.attachments);
+      result.push({ role: 'user', content: `[${label}] ${text}` });
+      continue;
+    }
+
+    // 非群聊
+    result.push({
+      role: m.role as NetworkMessage['role'],
+      content: buildContentWithAttachments(sanitizeHistoryContentForModel(m.content), m.attachments),
+    });
+  }
+
+  return result;
+}
+
+function trimMessagesForNewTopic<T extends {
+  role: string;
+  content: string;
+  speakerParticipantId: number | null;
+  toolCallsJson: string;
+}>(
+  messages: T[],
+  session: ChatSession | null
+): T[] {
+  let lastNewTopicIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'system' && messages[i].content === NEW_TOPIC_MARKER) {
+      lastNewTopicIdx = i;
+      break;
+    }
+  }
+  if (lastNewTopicIdx < 0) return messages;
+
+  const before = messages.slice(0, lastNewTopicIdx);
+  const after = messages.slice(lastNewTopicIdx + 1);
+  const keepSystems = before.filter((m) => m.role === 'system' && m.content !== NEW_TOPIC_MARKER);
+
+  let keepGreeting: T | null = null;
+  if (session?.mode === 'NPC' && session.associatedId != null) {
+    const firstUserIdx = before.findIndex((m) => m.role === 'user');
+    const greetingRange = firstUserIdx >= 0 ? before.slice(0, firstUserIdx) : before;
+    keepGreeting =
+      [...greetingRange]
+        .reverse()
+        .find(
+          (m) =>
+            m.role === 'assistant' &&
+            m.speakerParticipantId === session.associatedId &&
+            (!m.toolCallsJson || m.toolCallsJson === '[]')
+        ) ?? null;
+  }
+
+  return [...keepSystems, ...(keepGreeting ? [keepGreeting] : []), ...after];
+}
+
+/** 附件转 data URL content parts（base64 图片/视频） */
+function buildContentWithAttachments(content: string, attachments: string[]): string | NetworkMessage['content'] {
+  if (!attachments || attachments.length === 0) {
+    return content || null;
+  }
+  const parts: NonNullable<NetworkMessage['content']> = [];
+  if (content) parts.push({ type: 'text', text: content });
+  for (const url of attachments) {
+    const isImage = /^data:image\//.test(url);
+    parts.push({
+      type: isImage ? 'image_url' : 'video_url',
+      [isImage ? 'image_url' : 'video_url']: { url },
+    });
+  }
+  return parts as NetworkMessage['content'];
+}
+
+function parseToolCalls(json: string): NonNullable<NetworkMessage['tool_calls']> {
+  if (!json) return [];
+  try {
+    const arr = JSON.parse(json);
+    if (!Array.isArray(arr)) return [];
+    const result: NonNullable<NetworkMessage['tool_calls']> = [];
+    for (const tc of arr) {
+      if (!tc || typeof tc !== 'object') continue;
+      // 已是标准网络格式（id/type/function）
+      if (tc.id && tc.type === 'function' && tc.function && typeof tc.function === 'object') {
+        const fn = tc.function as { name?: unknown; arguments?: unknown };
+        result.push({
+          id: String(tc.id),
+          type: 'function',
+          function: {
+            name: String(fn.name ?? ''),
+            arguments: typeof fn.arguments === 'string' ? fn.arguments : JSON.stringify(fn.arguments ?? {}),
+          },
+        });
+        continue;
+      }
+      // 内部 ToolCallRecord 格式（id/name/argumentsJson/contentOffset）
+      if (tc.id && tc.name) {
+        result.push({
+          id: String(tc.id),
+          type: 'function',
+          function: {
+            name: String(tc.name),
+            arguments: typeof tc.argumentsJson === 'string' ? tc.argumentsJson : JSON.stringify(tc.argumentsJson ?? {}),
+          },
+        });
+      }
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}

package/src/core/proxy.ts

@@ -0,0 +1,58 @@
+// ============================================================
+// CORS 代理辅助：当直连请求被浏览器跨域拦截（CORS）时，
+// 自动回退到 Vite 开发服务器的同源代理。
+// 代理规则：http://<当前站点>/api/<host:port>/<剩余路径>
+// 例：http://192.168.1.5:8788/v1/ → http://localhost:5173/api/192.168.1.5:8788/v1/
+// ============================================================
+
+/** 判断当前环境是否可能提供代理（Vite dev 服务器） */
+function canUseProxy(): boolean {
+  if (typeof window === 'undefined') return false;
+  // 仅当页面运行在开发服务器（非 file:// 等）时可用
+  return /^https?:\/\//.test(window.location.origin);
+}
+
+/** 该 URL 是否已经是同源 /api/ 代理形式 */
+export function isProxyUrl(url: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const u = new URL(url);
+    return u.origin === window.location.origin && u.pathname.startsWith('/api/');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 把直连 Base URL 转换为同源代理 URL。
+ * 返回 null 表示不需要/无法转换（如已是代理、或非 http(s) URL）。
+ * 例：
+ *   http://192.168.1.5:8788        → http://localhost:5173/api/192.168.1.5:8788
+ *   http://192.168.1.5:8788/v1/    → http://localhost:5173/api/192.168.1.5:8788/v1/
+ *   https://api.deepseek.com/v1/   → null（公有 HTTPS 服务一般带 CORS；不代理外网）
+ */
+export function toProxyUrl(baseUrl: string): string | null {
+  if (!canUseProxy() || isProxyUrl(baseUrl)) return null;
+  let u: URL;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+  // 仅代理内网/局域网地址，外网公开 API 保持直连（避免滥用代理）
+  const ipv4 = /^\d{1,3}(\.\d{1,3}){3}$/.test(u.hostname);
+  const isPrivateHost = ipv4 || u.hostname === 'localhost' || u.hostname === '127.0.0.1';
+  if (!isPrivateHost) return null;
+
+  const host = u.host; // hostname:port
+  const rest = u.pathname.replace(/^\/+/, '');
+  const path = `/api/${host}/${rest}`.replace(/\/+$/, '');
+  return `${window.location.origin}${path}`;
+}
+
+/** 判断 fetch 失败是否“像” CORS / 网络层问题（可用代理回退） */
+export function isNetworkLikeError(e: unknown): boolean {
+  const msg = (e as Error)?.message || String(e);
+  return /Failed to fetch|NetworkError|Load failed|TypeError|Network request failed/i.test(msg);
+}

package/src/core/sillyTavernImporter.ts

@@ -0,0 +1,317 @@
+import type { NpcCharacter } from '../types/models';
+
+// ============================================================
+// SillyTavern PNG 角色卡导入（chara v2 / ccv3 tEXt 块）
+// ============================================================
+// 依据官方规范实现：
+// - v2: https://github.com/malfoyslastname/character-card-spec-v2/blob/main/spec_v2.md
+//   JSON 结构为 { spec, spec_version, data: TavernCardV2 }，
+//   PNG 嵌入的 chara 块内容是「把 JSON 字符串按 UTF-8 编码后，再整体做 base64」的结果
+// - v3: https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md
+//   PNG 嵌入的 ccv3 块内容同样是「JSON 字符串 utf-8 -> base64」
+
+/** TavernCardV2 的 data 字段（v2 卡字段全部嵌套在 data 中） */
+interface TavernV2Data {
+  name?: string;
+  description?: string;
+  personality?: string;
+  scenario?: string;
+  first_mes?: string;
+  mes_example?: string;
+  system_prompt?: string;
+  post_history_instructions?: string;
+  alternate_greetings?: string[];
+  character_book?: StLorebook;
+  extensions?: Record<string, unknown>;
+}
+
+/** 顶层共有的信封结构（v2 用 spec='chara_card_v2'，v3 用 spec='chara_card_v3'） */
+interface StEnvelope {
+  /** v2 时存在：'chara_card_v2' */
+  spec?: string;
+  /** v3 时存在：'chara_card_v3' */
+  spec_version?: string;
+  /** v2 卡的 data 字段 */
+  data?: TavernV2Data;
+  // -------- v3 字段（CharacterCardV3 是 TavernCardV2 的超集，且字段就在顶层） --------
+  name?: string;
+  description?: string;
+  personality?: string;
+  scenario?: string;
+  first_mes?: string;
+  mes_example?: string;
+  system_prompt?: string;
+  post_history_instructions?: string;
+  /** v3 的额外开场白（备用），创建对话时随机选用 */
+  alternate_greetings?: string[];
+  character_book?: StLorebook;
+  /** v3 的 assets 图标（可选 base64 data URL） */
+  assets?: Array<{ type?: string; uri?: string; name?: string; ext?: string }>;
+}
+
+interface StLorebook {
+  name?: string;
+  description?: string;
+  scan_depth?: number;
+  token_budget?: number;
+  recursive_scanning?: boolean;
+  extensions?: Record<string, unknown>;
+  entries?: Array<{
+    enabled?: boolean;
+    name?: string;
+    comment?: string;
+    keys?: string[];
+    secondary_keys?: string[];
+    content?: string;
+    selective?: boolean;
+    constant?: boolean;
+    position?: 'before_char' | 'after_char';
+  }>;
+}
+
+const MAX_PNG_SIZE = 8 * 1024 * 1024;
+
+/** 尝试把字节解码为 UTF-8 文本 */
+function utf8Decode(bytes: Uint8Array): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    // 退化为 latin1，保证不会抛错
+    let s = '';
+    for (const b of bytes) s += String.fromCharCode(b);
+    return s;
+  }
+}
+
+/** 标准 base64 解码（返回 UTF-8 文本） */
+function safeBase64Decode(text: string): string | null {
+  const trimmed = text.replace(/\s/g, '');
+  // 去掉可能残留的 data:...;base64, 前缀
+  const commaIdx = trimmed.indexOf(',');
+  const body = commaIdx >= 0 && /^data:[\w.+-]+\/[^;]+;base64$/i.test(trimmed.slice(0, commaIdx))
+    ? trimmed.slice(commaIdx + 1)
+    : trimmed;
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(body) || body.length % 4 === 1) return null;
+  try {
+    const bin = atob(body);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return utf8Decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析 PNG tEXt 块（chara / ccv3）。
+ * 返回归一化后的卡片数据：v2 卡会把 data 字段展开到顶层，与 v3 字段结构对齐。
+ */
+function parsePngChara(buffer: ArrayBuffer): { key: 'ccv3' | 'chara'; data: StEnvelope } | null {
+  if (buffer.byteLength > MAX_PNG_SIZE) throw new Error('PNG 文件超过 8MB');
+  const bytes = new Uint8Array(buffer);
+  const dv = new DataView(buffer);
+
+  // PNG 签名校验
+  if (
+    bytes[0] !== 0x89 || bytes[1] !== 0x50 || bytes[2] !== 0x4e || bytes[3] !== 0x47 ||
+    bytes[4] !== 0x0d || bytes[5] !== 0x0a || bytes[6] !== 0x1a || bytes[7] !== 0x0a
+  ) {
+    throw new Error('不是合法的 PNG 文件');
+  }
+
+  let offset = 8;
+  let ccv3: string | null = null;
+  let chara: string | null = null;
+
+  while (offset + 8 <= buffer.byteLength) {
+    const length = dv.getUint32(offset);
+    const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + length;
+    if (dataEnd + 4 > buffer.byteLength) break;
+
+    if (type === 'tEXt') {
+      // keyword\0text
+      let sep = dataStart;
+      while (sep < dataEnd && bytes[sep] !== 0) sep++;
+      const keyword = utf8Decode(bytes.subarray(dataStart, sep));
+      const rawText = bytes.subarray(sep + 1, dataEnd);
+      if (keyword === 'ccv3') ccv3 = utf8Decode(rawText);
+      else if (keyword === 'chara') chara = utf8Decode(rawText);
+    }
+    offset = dataEnd + 4; // 跳过 CRC
+    if (type === 'IEND') break;
+  }
+
+  // 官方规范：tEXt 内容的 JSON 是 utf-8 -> base64 编码，先尝试 base64 解码再 JSON.parse
+  const candidates: Array<{ key: 'ccv3' | 'chara'; raw: string | null }> = [
+    { key: 'ccv3', raw: ccv3 },
+    { key: 'chara', raw: chara },
+  ];
+
+  for (const { key, raw } of candidates) {
+    if (!raw) continue;
+    for (const text of [safeBase64Decode(raw), raw]) {
+      if (!text) continue;
+      try {
+        const json = JSON.parse(text) as unknown;
+        const data = normalizeCard(json);
+        if (data) return { key, data };
+      } catch {
+        /* 尝试下一种解码 */
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * 把规范里的两种信封结构归一化为统一的字段结构：
+ * - v2: { spec, spec_version, data: {...} }  -> 展开 data
+ * - v3: { spec, spec_version, ...顶层字段 }    -> 原样
+ * 也兼容某些工具导出的「字段直接裸露在顶层」的 v2 变体。
+ */
+function normalizeCard(json: unknown): StEnvelope | null {
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) return null;
+  const obj = json as Record<string, unknown>;
+
+  // 情况一：有 data 字段（v2 规范信封）
+  if (obj.data && typeof obj.data === 'object' && !Array.isArray(obj.data)) {
+    const data = obj.data as Record<string, unknown>;
+    return {
+      spec: typeof obj.spec === 'string' ? obj.spec : undefined,
+      spec_version: typeof obj.spec_version === 'string' ? obj.spec_version : undefined,
+      ...(data as unknown as TavernV2Data),
+    };
+  }
+
+  // 情况二：顶层直接是卡数据（v3 规范 / v2 变体）
+  // 必须至少有一个角色字段，避免把乱码 JSON 误判成卡
+  const hasCardField = ['name', 'description', 'personality', 'first_mes', 'scenario'].some(
+    (k) => typeof obj[k] === 'string'
+  );
+  if (hasCardField) {
+    return {
+      spec: typeof obj.spec === 'string' ? obj.spec : undefined,
+      spec_version: typeof obj.spec_version === 'string' ? obj.spec_version : undefined,
+      ...(obj as unknown as TavernV2Data),
+    };
+  }
+
+  return null;
+}
+
+/** 从 SillyTavern 结构化字段组装人设 prompt（与 App 一致） */
+function buildPromptFromStructured(data: StEnvelope, fallbackName: string): string {
+  const sections: Array<[string, string | undefined]> = [
+    ['角色描述', data.description],
+    ['性格', data.personality],
+    ['场景', data.scenario],
+    ['示例对话', data.mes_example],
+    ['系统提示词', data.system_prompt],
+    ['历史后指令', data.post_history_instructions],
+  ];
+  const parts = sections
+    .filter(([, v]) => v && v.trim())
+    .map(([k, v]) => `### ${k}\n${v}`);
+  if (parts.length === 0) return `你是${fallbackName}。`;
+  return parts.join('\n\n');
+}
+
+/** 从卡片内嵌资源中提取头像（v3 assets 里的 base64 data URL） */
+function extractAvatarFromCard(data: StEnvelope): string | null {
+  const icon = (data.assets ?? []).find((a) => a?.type === 'icon' && a?.uri?.startsWith('data:image/'));
+  if (icon?.uri) return icon.uri.slice(0, 2_000_000); // 控制存储体积
+  return null;
+}
+
+/** 把 PNG 文件字节转成 data URL（导入时作为角色头像的兜底来源） */
+function pngToDataUrl(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let bin = '';
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return `data:image/png;base64,${btoa(bin)}`;
+}
+
+/**
+ * 解析头像：优先卡内 assets 图标（v3），否则直接用 PNG 文件本身作为头像。
+ * 卡片 PNG 通常就是角色立绘/头像，保证几乎所有角色卡导入后都有头像。
+ */
+function resolveAvatar(data: StEnvelope, pngDataUrl: string | null): string | null {
+  return extractAvatarFromCard(data) ?? pngDataUrl;
+}
+
+/** 渲染内嵌 Lorebook（character_book）为可读文本 */
+function renderLorebook(book: StLorebook | undefined, fallbackName: string) {
+  if (!book || !Array.isArray(book.entries)) return null;
+  const entries = book.entries.filter((e) => e.enabled !== false && e.content && e.content.trim());
+  if (entries.length === 0) return null;
+  const rendered = entries
+    .map(
+      (e) =>
+        `### ${e.name || e.comment || '条目'}\n` +
+        (e.keys && e.keys.length > 0 ? `触发词：${e.keys.join('、')}\n` : '') +
+        e.content
+    )
+    .join('\n\n');
+  return {
+    name: (book.name || `${fallbackName} 的世界书`).slice(0, 60),
+    content: rendered.slice(0, 10_000),
+  };
+}
+
+/** 归一化多开场白：主开场白 + 去重后的 alternate_greetings（去空白/截断） */
+function buildGreetings(data: StEnvelope, maxLen = 1000): { greeting: string; alternateGreetings: string[] } {
+  const greeting = (data.first_mes ?? '').slice(0, maxLen);
+  const alternates = (data.alternate_greetings ?? [])
+    .map((g) => (typeof g === 'string' ? g.trim() : ''))
+    .filter((g, i, arr) => g && g !== greeting && arr.indexOf(g) === i)
+    .slice(0, 20)
+    .map((g) => g.slice(0, maxLen));
+  return { greeting, alternateGreetings: alternates };
+}
+
+// ============================================================
+// 预填草稿（不落库）：UI 把解析结果填入「新建角色 / 新建 Lorebook」表单，
+// 由用户确认后手动保存
+// ============================================================
+
+export interface ParsedSillyTavernCard {
+  /** v2 / v3 */
+  version: string;
+  /** 预填到新建角色表单的数据（含头像、人设 prompt、开场白） */
+  character: NpcCharacter;
+  /** 卡内嵌的 Lorebook（若有），预填到新建 Lorebook 表单 */
+  worldBook: { name: string; content: string } | null;
+}
+
+/** 解析 PNG 角色卡为表单草稿，不写入数据库（PNG 图片本身作为头像） */
+export async function parseSillyTavernCardFile(file: File): Promise<ParsedSillyTavernCard> {
+  const buffer = await file.arrayBuffer();
+  const parsed = parsePngChara(buffer);
+  if (!parsed) throw new Error('未找到角色卡数据（ccv3 / chara）');
+
+  const { key, data } = parsed;
+  const name = data.name?.trim() || '未命名角色';
+  const { greeting, alternateGreetings } = buildGreetings(data);
+
+  const character: NpcCharacter = {
+    name,
+    prompt: buildPromptFromStructured(data, name),
+    greeting,
+    alternateGreetings,
+    avatarColorOrdinal: Math.floor(Math.random() * 6),
+    avatarDataUrl: resolveAvatar(data, pngToDataUrl(buffer)),
+    enabledToolNames: [],
+    isBuiltIn: false,
+    createdAt: Date.now(),
+  };
+
+  const lorebook = renderLorebook(data.character_book, name);
+  const worldBook = lorebook ? { name: lorebook.name, content: lorebook.content } : null;
+
+  return { version: key === 'ccv3' ? 'v3' : 'v2', character, worldBook };
+}