Merge pull request 'hermes/visual-novel-genarrative' (#18) from hermes/visual-novel-genarrative into master

Reviewed-on: #18
2026-05-13 21:19:38 +08:00
parent 5b96265c50 c1131e6f55
commit 57de9a8df6
14 changed files with 1050 additions and 89 deletions
--- a/src/services/creation-agent/creationAgentClientFactory.ts
+++ b/src/services/creation-agent/creationAgentClientFactory.ts
@@ -68,6 +68,28 @@ async function openCreationAgentSsePost(
  return response;
 }

+type CreationAgentNormalizedStreamEvent =
+  | {
+      kind: 'reply_delta';
+      text: string;
+    }
+  | {
+      kind: 'session';
+      session: unknown;
+    }
+  | {
+      kind: 'error';
+      message: string;
+    }
+  | null;
+
+type CreationAgentStreamOptions = TextStreamOptions & {
+  normalizeEvent?: (
+    eventName: string,
+    parsed: Record<string, unknown>,
+  ) => CreationAgentNormalizedStreamEvent;
+};
+
 /**
 * 三类作品创作 Agent 都遵循同一组 HTTP/SSE 端点形状。
 * 这里统一请求骨架，玩法 client 只保留路径、类型与中文错误文案差异。
@@ -128,7 +150,7 @@ export function createCreationAgentClient<
  const streamMessage = async (
    sessionId: string,
    payload: TSendMessagePayload,
-    options: TextStreamOptions = {},
+    options: CreationAgentStreamOptions = {},
  ): Promise<TSession> => {
    const response = await openCreationAgentSsePost(
      `${apiBase}/${encodeURIComponent(sessionId)}/messages/stream`,
--- a/src/services/creation-agent/creationAgentSse.test.ts
+++ b/src/services/creation-agent/creationAgentSse.test.ts
@@ -1,6 +1,9 @@
-import { expect, test } from 'vitest';
+import { expect, test, vi } from 'vitest';

-import { readCreationAgentSessionFromSse } from './creationAgentSse';
+import {
+  normalizeVisualNovelAgentStreamEvent,
+  readCreationAgentSessionFromSse,
+} from './creationAgentSse';

 function createChunkedStreamResponse(chunks: Uint8Array[]) {
  const stream = new ReadableStream<Uint8Array>({
@@ -76,3 +79,51 @@ test('readCreationAgentSessionFromSse keeps streamed updates before error event'

  expect(updates).toEqual(['先把方洞万能的反差定住。']);
 });
+
+test('readCreationAgentSessionFromSse can normalize typed visual novel stream events', async () => {
+  const encoder = new TextEncoder();
+  const session = {
+    sessionId: 'vn-session-1',
+    ownerUserId: 'user-1',
+    progressPercent: 100,
+    stage: 'draft_ready',
+  };
+  const onUpdate = vi.fn();
+
+  const response = createChunkedStreamResponse([
+    encoder.encode(
+      'data: {"type":"start","sessionId":"vn-session-1"}\n\n' +
+        'data: {"type":"phase","phase":"synthesis"}\n\n' +
+        'data: {"type":"text_delta","text":"视觉小说底稿已生成。"}\n\n' +
+        `data: ${JSON.stringify({ type: 'complete', session })}\n\n` +
+        'data: {"type":"done"}\n\n',
+    ),
+  ]);
+
+  await expect(
+    readCreationAgentSessionFromSse(response, {
+      fallbackMessage: '发送失败',
+      incompleteMessage: '结果不完整',
+      normalizeEvent: normalizeVisualNovelAgentStreamEvent,
+      onUpdate,
+    }),
+  ).resolves.toEqual(session);
+  expect(onUpdate).toHaveBeenCalledWith('视觉小说底稿已生成。');
+});
+
+test('readCreationAgentSessionFromSse surfaces typed visual novel error events', async () => {
+  const encoder = new TextEncoder();
+  const response = createChunkedStreamResponse([
+    encoder.encode(
+      'data: {"type":"error","message":"视觉小说流式创作失败","retryable":true}\n\n',
+    ),
+  ]);
+
+  await expect(
+    readCreationAgentSessionFromSse(response, {
+      fallbackMessage: '发送失败',
+      incompleteMessage: '结果不完整',
+      normalizeEvent: normalizeVisualNovelAgentStreamEvent,
+    }),
+  ).rejects.toThrow('视觉小说流式创作失败');
+});
--- a/src/services/creation-agent/creationAgentSse.ts
+++ b/src/services/creation-agent/creationAgentSse.ts
@@ -1,9 +1,27 @@
+import type { VisualNovelAgentStreamEvent } from '../../../packages/shared/src/contracts/visualNovel';
 import type { TextStreamOptions } from '../aiTypes';

 type CreationAgentSseOptions<TSession> = TextStreamOptions & {
  fallbackMessage: string;
  incompleteMessage: string;
  resolveSession?: (rawSession: unknown) => TSession | null;
+  normalizeEvent?: (
+    eventName: string,
+    parsed: Record<string, unknown>,
+  ) =>
+    | {
+        kind: 'reply_delta';
+        text: string;
+      }
+    | {
+        kind: 'session';
+        session: unknown;
+      }
+    | {
+        kind: 'error';
+        message: string;
+      }
+    | null;
 };

 function findSseEventBoundary(buffer: string) {
@@ -65,6 +83,66 @@ function parseJsonObject(data: string) {
  }
 }

+type NormalizedCreationAgentSseEvent = NonNullable<
+  CreationAgentSseOptions<unknown>['normalizeEvent']
+> extends (eventName: string, parsed: Record<string, unknown>) => infer TResult
+  ? TResult
+  : never;
+
+function normalizeDefaultCreationAgentEvent(
+  eventName: string,
+  parsed: Record<string, unknown>,
+): NormalizedCreationAgentSseEvent {
+  if (eventName === 'reply_delta') {
+    const text = parsed.text;
+    return typeof text === 'string' ? { kind: 'reply_delta', text } : null;
+  }
+
+  if (eventName === 'session' && parsed.session) {
+    return { kind: 'session', session: parsed.session };
+  }
+
+  if (eventName === 'error') {
+    const message =
+      typeof parsed.message === 'string' && parsed.message.trim()
+        ? parsed.message.trim()
+        : '';
+    return { kind: 'error', message };
+  }
+
+  return null;
+}
+
+export function normalizeVisualNovelAgentStreamEvent(
+  eventName: string,
+  parsed: Record<string, unknown>,
+): NormalizedCreationAgentSseEvent {
+  const typedEventName =
+    eventName === 'message' && typeof parsed.type === 'string'
+      ? parsed.type
+      : eventName;
+  const event = {
+    ...parsed,
+    type: typedEventName,
+  } as VisualNovelAgentStreamEvent;
+
+  switch (event.type) {
+    case 'text_delta':
+      return typeof event.text === 'string'
+        ? { kind: 'reply_delta', text: event.text }
+        : null;
+    case 'complete':
+      return event.session ? { kind: 'session', session: event.session } : null;
+    case 'error':
+      return {
+        kind: 'error',
+        message: event.message.trim(),
+      };
+    default:
+      return normalizeDefaultCreationAgentEvent(eventName, parsed);
+  }
+}
+
 export async function readCreationAgentSessionFromSse<TSession>(
  response: Response,
  options: CreationAgentSseOptions<TSession>,
@@ -81,15 +159,10 @@ export async function readCreationAgentSessionFromSse<TSession>(
    ((rawSession: unknown) => (rawSession as TSession | null) ?? null);
  let buffer = '';
  let finalSession: TSession | null = null;
+  const normalizeEvent =
+    options.normalizeEvent ?? normalizeDefaultCreationAgentEvent;

-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) {
-      break;
-    }
-
-    buffer += decoder.decode(value, { stream: true });
-
+  const consumeBuffer = () => {
    for (;;) {
      const boundary = findSseEventBoundary(buffer);
      if (!boundary) {
@@ -105,70 +178,40 @@ export async function readCreationAgentSessionFromSse<TSession>(
      }

      const parsed = parseJsonObject(data);
+      if (!parsed) {
+        continue;
+      }
+      const normalized = normalizeEvent(eventName, parsed);

-      if (eventName === 'reply_delta' && parsed) {
-        const text = parsed.text;
-        if (typeof text === 'string') {
-          options.onUpdate?.(text);
-        }
+      if (normalized?.kind === 'reply_delta') {
+        options.onUpdate?.(normalized.text);
        continue;
      }

-      if (eventName === 'session' && parsed?.session) {
-        finalSession = resolveSession(parsed.session);
+      if (normalized?.kind === 'session') {
+        finalSession = resolveSession(normalized.session);
        continue;
      }

-      if (eventName === 'error' && parsed) {
-        const message =
-          typeof parsed.message === 'string' && parsed.message.trim()
-            ? parsed.message.trim()
-            : options.fallbackMessage;
-        throw new Error(message);
+      if (normalized?.kind === 'error') {
+        throw new Error(normalized.message || options.fallbackMessage);
      }
    }
+  };
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+
+    buffer += decoder.decode(value, { stream: true });
+    consumeBuffer();
  }

  // 流结束后再 flush 一次解码器，避免 UTF-8 多字节字符残留在内部缓冲里。
  buffer += decoder.decode();
-
-  for (;;) {
-    const boundary = findSseEventBoundary(buffer);
-    if (!boundary) {
-      break;
-    }
-
-    const eventBlock = buffer.slice(0, boundary.index);
-    buffer = buffer.slice(boundary.index + boundary.length);
-    const { eventName, data } = parseSseEventBlock(eventBlock);
-
-    if (!data) {
-      continue;
-    }
-
-    const parsed = parseJsonObject(data);
-
-    if (eventName === 'reply_delta' && parsed) {
-      const text = parsed.text;
-      if (typeof text === 'string') {
-        options.onUpdate?.(text);
-      }
-      continue;
-    }
-
-    if (eventName === 'session' && parsed?.session) {
-      finalSession = resolveSession(parsed.session);
-      continue;
-    }
-
-    if (eventName === 'error' && parsed) {
-      const message =
-        typeof parsed.message === 'string' && parsed.message.trim()
-          ? parsed.message.trim()
-          : options.fallbackMessage;
-      throw new Error(message);
-    }
-  }
+  consumeBuffer();

  if (!finalSession) {
    throw new Error(options.incompleteMessage);
--- a/src/services/rpg-creation/rpgCreationAgentClient.ts
+++ b/src/services/rpg-creation/rpgCreationAgentClient.ts
@@ -72,7 +72,7 @@ export async function streamRpgCreationMessage(
  sessionId: string,
  payload: SendRpgAgentMessageRequest,
  options: TextStreamOptions = {},
-) {
+): Promise<RpgAgentSessionSnapshot> {
  const response = await openRpgCreationSsePost(
    `/api/runtime${RPG_AGENT_API_BASE}/${encodeURIComponent(sessionId)}/messages/stream`,
    payload,
--- a/src/services/visual-novel-creation/index.ts
+++ b/src/services/visual-novel-creation/index.ts
@@ -1,3 +1,4 @@
-export * from './visualNovelCreationClient';
 export * from './visualNovelAssetClient';
 export * from './visualNovelAudioGenerationClient';
+export * from './visualNovelCreationClient';
+export * from './visualNovelImageGenerationClient';
--- a/src/services/visual-novel-creation/visualNovelCreationClient.ts
+++ b/src/services/visual-novel-creation/visualNovelCreationClient.ts
@@ -9,7 +9,10 @@ import type {
 } from '../../../packages/shared/src/contracts/visualNovel';
 import type { TextStreamOptions } from '../aiTypes';
 import { type ApiRetryOptions, requestJson } from '../apiClient';
-import { createCreationAgentClient } from '../creation-agent';
+import {
+  createCreationAgentClient,
+  normalizeVisualNovelAgentStreamEvent,
+} from '../creation-agent';

 const VISUAL_NOVEL_AGENT_API_BASE = '/api/creation/visual-novel/sessions';
 const VISUAL_NOVEL_CREATION_WRITE_RETRY: ApiRetryOptions = {
@@ -61,7 +64,10 @@ export function streamVisualNovelMessage(
  payload: SendVisualNovelMessageRequest,
  options: TextStreamOptions = {},
 ) {
-  return visualNovelAgentHttpClient.streamMessage(sessionId, payload, options);
+  return visualNovelAgentHttpClient.streamMessage(sessionId, payload, {
+    ...options,
+    normalizeEvent: normalizeVisualNovelAgentStreamEvent,
+  });
 }

 export function executeVisualNovelAction(
--- a/src/services/visual-novel-creation/visualNovelImageGenerationClient.ts
+++ b/src/services/visual-novel-creation/visualNovelImageGenerationClient.ts
@@ -0,0 +1,158 @@
+import type {
+  VisualNovelCharacterDraft,
+  VisualNovelResultDraft,
+  VisualNovelSceneDraft,
+} from '../../../packages/shared/src/contracts/visualNovel';
+import type {
+  CustomWorldSceneImageRequest,
+  CustomWorldSceneImageResult,
+} from '../aiTypes';
+import { generateRpgWorldSceneImage } from '../rpg-creation/rpgCreationAssetClient';
+
+export type VisualNovelImageGenerationKind =
+  | 'cover'
+  | 'scene_background'
+  | 'character_standee';
+
+export type VisualNovelImageGenerationRequest = {
+  kind: VisualNovelImageGenerationKind;
+  draft: VisualNovelResultDraft;
+  scene?: VisualNovelSceneDraft | null;
+  character?: VisualNovelCharacterDraft | null;
+  prompt?: string;
+  referenceImageSrc?: string;
+};
+
+function buildVisualNovelProfile(
+  draft: VisualNovelResultDraft,
+): CustomWorldSceneImageRequest['profile'] {
+  return {
+    id: draft.profileId?.trim() || 'visual-novel-draft',
+    name: draft.workTitle.trim() || draft.world.title.trim() || '视觉小说作品',
+    subtitle: draft.world.title.trim() || draft.workTitle.trim() || '视觉小说',
+    summary: draft.workDescription.trim() || draft.world.summary.trim(),
+    tone:
+      draft.world.defaultTone.trim() || draft.world.literaryStyle.trim() || '视觉小说',
+    playerGoal: draft.world.playerRole.trim() || '推进剧情并完成关键选择',
+    settingText: [
+      draft.world.premise,
+      draft.world.background,
+      draft.world.literaryStyle,
+    ]
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .join('\n'),
+  };
+}
+
+function buildVisualNovelLandmark(
+  payload: VisualNovelImageGenerationRequest,
+): CustomWorldSceneImageRequest['landmark'] {
+  if (payload.kind === 'scene_background' && payload.scene) {
+    return {
+      id: payload.scene.sceneId,
+      name: payload.scene.name.trim() || '视觉小说场景',
+      description: payload.scene.description.trim() || payload.draft.world.summary,
+    };
+  }
+
+  if (payload.kind === 'character_standee' && payload.character) {
+    return {
+      id: payload.character.characterId,
+      name: `${payload.character.name.trim() || '视觉小说角色'}立绘`,
+      description: [
+        payload.character.appearance,
+        payload.character.personality,
+        payload.character.role,
+        payload.character.relationshipToPlayer,
+      ]
+        .map((part) => part?.trim() ?? '')
+        .filter(Boolean)
+        .join('；'),
+    };
+  }
+
+  return {
+    id: payload.draft.profileId?.trim() || 'visual-novel-cover',
+    name: `${payload.draft.workTitle.trim() || '视觉小说'}封面`,
+    description:
+      payload.draft.workDescription.trim() ||
+      payload.draft.world.summary.trim() ||
+      payload.draft.world.premise.trim(),
+  };
+}
+
+function buildDefaultVisualNovelImagePrompt(
+  payload: VisualNovelImageGenerationRequest,
+) {
+  const draft = payload.draft;
+  if (payload.kind === 'scene_background' && payload.scene) {
+    return [
+      `视觉小说场景背景：${payload.scene.name}`,
+      payload.scene.description,
+      draft.world.defaultTone,
+      '16:9 横版背景图，无文字，无 UI，无人物特写',
+    ]
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .join('，');
+  }
+
+  if (payload.kind === 'character_standee' && payload.character) {
+    return [
+      `视觉小说角色立绘：${payload.character.name}`,
+      payload.character.appearance,
+      payload.character.personality,
+      payload.character.tone,
+      '透明感二次元全身或半身立绘，干净背景，无文字，无 UI',
+    ]
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .join('，');
+  }
+
+  return [
+    `视觉小说作品封面：${draft.workTitle}`,
+    draft.workDescription,
+    draft.world.summary,
+    draft.world.defaultTone,
+    '精致视觉小说封面构图，无文字，无 UI，适合 4:3/16:9 裁切',
+  ]
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join('，');
+}
+
+function resolveVisualNovelImageSize(kind: VisualNovelImageGenerationKind) {
+  if (kind === 'character_standee') {
+    return '768*1024';
+  }
+  return '1280*720';
+}
+
+export async function generateVisualNovelImageAsset(
+  payload: VisualNovelImageGenerationRequest,
+): Promise<CustomWorldSceneImageResult> {
+  const userPrompt =
+    payload.prompt?.trim() || buildDefaultVisualNovelImagePrompt(payload);
+
+  if (!userPrompt.trim()) {
+    throw new Error('请先补充图片生成提示词。');
+  }
+
+  return generateRpgWorldSceneImage({
+    profile: buildVisualNovelProfile(payload.draft),
+    landmark: buildVisualNovelLandmark(payload),
+    userPrompt,
+    size: resolveVisualNovelImageSize(payload.kind),
+    ...(payload.referenceImageSrc?.trim()
+      ? { referenceImageSrc: payload.referenceImageSrc.trim() }
+      : {}),
+  });
+}
+
+export function buildVisualNovelImageGenerationPrompt(
+  payload: VisualNovelImageGenerationRequest,
+) {
+  return buildDefaultVisualNovelImagePrompt(payload);
+}