GenarrativeAI/Genarrative
6
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Refine play type integration flow and docs

Browse Source
This commit is contained in:
kdletters
2026-06-03 00:57:24 +08:00
parent dbe4c902b4
commit 67ba40c678
35 changed files with 2226 additions and 619 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
src/services/miniGameDraftGenerationProgress.test.ts
View File

@@ -36,9 +36,7 @@ describe('miniGameDraftGenerationProgress', () => {
expect(progress?.steps[0]?.detail).toBe(
'建立可恢复草稿，整理首关描述与关卡结构，约 8 秒。',
);
expect(progress?.steps[2]?.detail).toBe(
'生成 1:1 拼图首图，预计 4 分钟。',
);
expect(progress?.steps[2]?.detail).toBe('生成 1:1 拼图首图，预计 4 分钟。');
expect(progress?.estimatedRemainingMs).toBe(446_500);
expect(progress?.overallProgress).toBe(0);
expect(progress?.steps[0]?.completed).toBeGreaterThan(0);
@@ -72,7 +70,7 @@ describe('miniGameDraftGenerationProgress', () => {
error: null,
};
const progress = buildMiniGameDraftGenerationProgress(state, 7000);
const progress = buildMiniGameDraftGenerationProgress(state, 130_000);
expect(progress?.overallProgress).toBeGreaterThan(0);
expect(progress?.overallProgress).toBeLessThan(88);
@@ -105,8 +103,8 @@ describe('miniGameDraftGenerationProgress', () => {
expect(longRunningProgress?.phaseId).toBe('compile');
expect(longRunningProgress?.steps[0]?.status).toBe('active');
expect(longRunningProgress?.steps[1]?.status).toBe('pending');
expect(longRunningProgress?.overallProgress).toBeLessThanOrEqual(98);
expect(longRunningProgress?.overallProgress).toBeGreaterThan(40);
expect(longRunningProgress?.overallProgress).toBeLessThan(5);
expect(longRunningProgress?.overallProgress).toBeGreaterThan(0);
expect(realProgress?.phaseId).toBe('puzzle-cover-image');
expect(realProgress?.steps[1]?.status).toBe('completed');
expect(realProgress?.steps[2]?.status).toBe('active');
@@ -145,7 +143,10 @@ describe('miniGameDraftGenerationProgress', () => {
};
const progress = buildMiniGameDraftGenerationProgress(state, 20_000);
const writeBackProgress = buildMiniGameDraftGenerationProgress(state, 206_000);
const writeBackProgress = buildMiniGameDraftGenerationProgress(
state,
206_000,
);
expect(progress?.steps.map((step) => step.label)).toEqual([
'编译首关草稿',
@@ -175,13 +176,14 @@ describe('miniGameDraftGenerationProgress', () => {
expect(progress?.phaseId).toBe('compile');
expect(progress?.overallProgress).toBeLessThan(88);
expect(progress?.overallProgress).toBeGreaterThan(80);
expect(progress?.overallProgress).toBeLessThan(5);
expect(progress?.overallProgress).toBeGreaterThan(0);
expect(progress?.estimatedRemainingMs).toBe(0);
expect(progress?.steps[0]?.status).toBe('active');
expect(progress?.steps[0]?.completed).toBe(0.98);
expect(progress?.steps.slice(1).every((step) => step.status === 'pending')).toBe(
true,
);
expect(
progress?.steps.slice(1).every((step) => step.status === 'pending'),
).toBe(true);
});
test('puzzle draft generation advances steps from backend progress percent only', () => {
@@ -221,9 +223,11 @@ describe('miniGameDraftGenerationProgress', () => {
);
expect(imageProgress?.phaseId).toBe('puzzle-cover-image');
expect(imageProgress?.overallProgress).toBeLessThan(88);
expect(imageProgress?.steps[2]?.status).toBe('active');
expect(imageProgress?.steps[3]?.status).toBe('pending');
expect(uiProgress?.phaseId).toBe('puzzle-ui-assets');
expect(uiProgress?.overallProgress).toBeLessThan(94);
expect(uiProgress?.steps[4]?.status).toBe('active');
expect(uiProgress?.steps[5]?.status).toBe('pending');
expect(writeProgress?.phaseId).toBe('puzzle-select-image');
@@ -249,6 +253,7 @@ describe('miniGameDraftGenerationProgress', () => {
const progress = buildMiniGameDraftGenerationProgress(state, 121_000);
expect(progress?.phaseId).toBe('puzzle-cover-image');
expect(progress?.overallProgress).toBeLessThan(88);
expect(progress?.steps[2]?.status).toBe('active');
expect(progress?.steps[2]?.completed).toBeLessThan(0.02);
});
@@ -619,55 +624,58 @@ describe('miniGameDraftGenerationProgress', () => {
});
test('puzzle generation anchors expose form payload as the display source', () => {
const entries = buildPuzzleGenerationAnchorEntries({
sessionId: 'puzzle-session-1',
currentTurn: 1,
progressPercent: 0,
stage: 'collecting_anchors',
anchorPack: {
themePromise: {
key: 'themePromise',
label: '题材承诺',
value: '雨夜猫街',
status: 'locked',
},
visualSubject: {
key: 'visualSubject',
label: '画面主体',
value: '一只猫在雨夜灯牌下回头。',
status: 'locked',
},
visualMood: {
key: 'visualMood',
label: '视觉气质',
value: '清晰、适合拼图切块',
status: 'inferred',
},
compositionHooks: {
key: 'compositionHooks',
label: '拼图记忆点',
value: '主体轮廓、色块分区、局部细节',
status: 'inferred',
},
tagsAndForbidden: {
key: 'tagsAndForbidden',
label: '标签与禁忌',
value: '猫咪、雨夜、拼图；禁止标题字',
status: 'inferred',
const entries = buildPuzzleGenerationAnchorEntries(
{
sessionId: 'puzzle-session-1',
currentTurn: 1,
progressPercent: 0,
stage: 'collecting_anchors',
anchorPack: {
themePromise: {
key: 'themePromise',
label: '题材承诺',
value: '雨夜猫街',
status: 'locked',
},
visualSubject: {
key: 'visualSubject',
label: '画面主体',
value: '一只猫在雨夜灯牌下回头。',
status: 'locked',
},
visualMood: {
key: 'visualMood',
label: '视觉气质',
value: '清晰、适合拼图切块',
status: 'inferred',
},
compositionHooks: {
key: 'compositionHooks',
label: '拼图记忆点',
value: '主体轮廓、色块分区、局部细节',
status: 'inferred',
},
tagsAndForbidden: {
key: 'tagsAndForbidden',
label: '标签与禁忌',
value: '猫咪、雨夜、拼图；禁止标题字',
status: 'inferred',
},
},
draft: null,
messages: [],
lastAssistantReply: null,
publishedProfileId: null,
suggestedActions: [],
resultPreview: null,
updatedAt: '2026-04-29T00:00:00.000Z',
},
draft: null,
messages: [],
lastAssistantReply: null,
publishedProfileId: null,
suggestedActions: [],
resultPreview: null,
updatedAt: '2026-04-29T00:00:00.000Z',
}, {
seedText: '一只猫在雨夜灯牌下回头。',
pictureDescription: '一只猫在雨夜灯牌下回头。',
referenceImageSrc: null,
});
{
seedText: '一只猫在雨夜灯牌下回头。',
pictureDescription: '一只猫在雨夜灯牌下回头。',
referenceImageSrc: null,
},
);
expect(entries).toEqual([
{

179
src/services/miniGameDraftGenerationProgress.ts
View File

@@ -216,7 +216,10 @@ function resolvePuzzleBackendProgressPercent(
state: MiniGameDraftGenerationState,
) {
const progressPercent = state.metadata?.puzzleProgressPercent;
if (typeof progressPercent !== 'number' || !Number.isFinite(progressPercent)) {
if (
typeof progressPercent !== 'number' ||
!Number.isFinite(progressPercent)
) {
return null;
}
@@ -571,13 +574,13 @@ export function createMiniGameDraftGenerationState(
? 'square-hole-draft'
: kind === 'match3d'
? 'match3d-work-title'
: kind === 'baby-object-match'
? 'baby-object-draft'
: kind === 'jump-hop'
? 'jump-hop-draft'
: kind === 'wooden-fish'
? 'wooden-fish-draft'
: 'compile',
: kind === 'baby-object-match'
? 'baby-object-draft'
: kind === 'jump-hop'
? 'jump-hop-draft'
: kind === 'wooden-fish'
? 'wooden-fish-draft'
: 'compile',
startedAtMs,
completedAssetCount: 0,
totalAssetCount: 0,
@@ -784,10 +787,7 @@ function resolvePuzzleActiveStepElapsedProgressRatio(
// 中文注释：未收到后端真实里程碑时，跨步骤必须卡住；
// 但当前步骤内的假进度要按整段等待时间继续向前走，避免短步骤几秒后停死。
const fallbackDurationMs = Math.max(1, resolvePuzzleEstimatedWaitMs(state));
return Math.max(
0,
Math.min(0.98, elapsedMs / fallbackDurationMs),
);
return Math.max(0, Math.min(0.98, elapsedMs / fallbackDurationMs));
}
function resolveElapsedActiveStepProgressRatio(
@@ -809,53 +809,7 @@ function resolveElapsedActiveStepProgressRatio(
? WOODEN_FISH_ESTIMATED_WAIT_MS
: 1;
return Math.max(
0,
Math.min(0.98, elapsedMs / Math.max(1, estimatedWaitMs)),
);
}
function resolvePuzzleOverallProgress(
state: MiniGameDraftGenerationState,
activeStepProgressRatio: number,
) {
const backendProgressPercent = resolvePuzzleBackendProgressPercent(state);
// 中文注释：88 以下的后端进度只保留为会话事实，不参与首帧总进度抬升。
// 生成页恢复时必须先从 0% 起步，再由当前步骤内的假进度平滑推进。
const backendProgressFloor =
backendProgressPercent != null &&
backendProgressPercent >= PUZZLE_COMPILE_MILESTONE_PROGRESS
? backendProgressPercent
: 0;
const range =
state.phase === 'puzzle-select-image'
? {
start: PUZZLE_UI_MILESTONE_PROGRESS,
end: PUZZLE_NON_READY_MAX_PROGRESS,
}
: state.phase === 'puzzle-ui-assets'
? {
start: PUZZLE_IMAGE_MILESTONE_PROGRESS,
end: PUZZLE_UI_MILESTONE_PROGRESS,
}
: state.phase === 'puzzle-cover-image' ||
state.phase === 'puzzle-level-scene'
? {
start: PUZZLE_COMPILE_MILESTONE_PROGRESS,
end: PUZZLE_IMAGE_MILESTONE_PROGRESS,
}
: {
start: 0,
end: PUZZLE_COMPILE_MILESTONE_PROGRESS,
};
const fakeProgress =
range.start + (range.end - range.start) * activeStepProgressRatio;
const nextProgress = Math.min(
PUZZLE_NON_READY_MAX_PROGRESS,
Math.max(range.start, backendProgressFloor, fakeProgress),
);
return nextProgress;
return Math.max(0, Math.min(0.98, elapsedMs / Math.max(1, estimatedWaitMs)));
}
export function buildMiniGameDraftGenerationProgress(
@@ -867,7 +821,8 @@ export function buildMiniGameDraftGenerationProgress(
}
const effectiveNowMs =
typeof state.finishedAtMs === 'number' && Number.isFinite(state.finishedAtMs)
typeof state.finishedAtMs === 'number' &&
Number.isFinite(state.finishedAtMs)
? state.finishedAtMs
: nowMs;
const elapsedMs = Math.max(0, effectiveNowMs - state.startedAtMs);
@@ -894,42 +849,42 @@ export function buildMiniGameDraftGenerationProgress(
...state,
phase: woodenFishTimeline.phase,
}
: state.kind === 'big-fish' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveBigFishPhaseByElapsedMs(elapsedMs),
}
: state.kind === 'square-hole' &&
: state.kind === 'big-fish' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveSquareHolePhaseByElapsedMs(elapsedMs),
phase: resolveBigFishPhaseByElapsedMs(elapsedMs),
}
: state.kind === 'match3d' &&
: state.kind === 'square-hole' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveMatch3DPhaseByElapsedMs(elapsedMs, state.phase),
phase: resolveSquareHolePhaseByElapsedMs(elapsedMs),
}
: state.kind === 'baby-object-match' &&
: state.kind === 'match3d' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveBabyObjectMatchPhaseByElapsedMs(elapsedMs),
phase: resolveMatch3DPhaseByElapsedMs(elapsedMs, state.phase),
}
: state.kind === 'jump-hop' &&
: state.kind === 'baby-object-match' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveJumpHopPhaseByElapsedMs(elapsedMs),
phase: resolveBabyObjectMatchPhaseByElapsedMs(elapsedMs),
}
: state;
: state.kind === 'jump-hop' &&
state.phase !== 'failed' &&
state.phase !== 'ready'
? {
...state,
phase: resolveJumpHopPhaseByElapsedMs(elapsedMs),
}
: state;
const puzzleTimedSteps =
normalizedState.kind === 'puzzle'
@@ -944,22 +899,23 @@ export function buildMiniGameDraftGenerationProgress(
const activeStepIndex = getActiveStepIndex(steps, normalizedState.phase);
const activeStep = steps[activeStepIndex] ?? steps[0];
const activeStepProgressRatio =
normalizedState.kind === 'puzzle'
normalizedState.phase === 'failed'
? 0
: normalizedState.kind === 'puzzle'
? normalizedState.phase === 'ready'
? 1
: normalizedState.phase === 'failed'
? 0
: resolvePuzzleActiveStepElapsedProgressRatio(
normalizedState,
puzzleTimedSteps ?? buildPuzzleTimedSteps(normalizedState),
activeStepIndex,
elapsedMs,
effectiveNowMs,
)
: resolvePuzzleActiveStepElapsedProgressRatio(
normalizedState,
puzzleTimedSteps ?? buildPuzzleTimedSteps(normalizedState),
activeStepIndex,
elapsedMs,
effectiveNowMs,
)
: normalizedState.totalAssetCount > 0
? Math.min(
1,
normalizedState.completedAssetCount / normalizedState.totalAssetCount,
normalizedState.completedAssetCount /
normalizedState.totalAssetCount,
)
: normalizedState.phase === 'ready'
? 1
@@ -968,16 +924,16 @@ export function buildMiniGameDraftGenerationProgress(
normalizedState.kind,
elapsedMs,
)
: normalizedState.kind === 'square-hole'
: normalizedState.kind === 'square-hole'
? resolveElapsedActiveStepProgressRatio(
normalizedState.kind,
elapsedMs,
)
: normalizedState.kind === 'match3d'
? resolveElapsedActiveStepProgressRatio(
normalizedState.kind,
elapsedMs,
)
: normalizedState.kind === 'match3d'
? resolveElapsedActiveStepProgressRatio(
normalizedState.kind,
elapsedMs,
)
: normalizedState.kind === 'baby-object-match'
? resolveElapsedActiveStepProgressRatio(
normalizedState.kind,
@@ -1002,20 +958,11 @@ export function buildMiniGameDraftGenerationProgress(
? Math.max(1, completedWeight)
: normalizedState.phase === 'ready'
? 100
: normalizedState.kind === 'puzzle'
? resolvePuzzleOverallProgress(
normalizedState,
activeStepProgressRatio,
)
: completedWeight + activeStep.weight * activeStepProgressRatio;
: completedWeight + activeStep.weight * activeStepProgressRatio;
const cappedOverallProgress =
normalizedState.phase === 'ready' || normalizedState.phase === 'failed'
? overallProgress
: normalizedState.kind === 'puzzle'
? Math.min(PUZZLE_NON_READY_MAX_PROGRESS, overallProgress)
: normalizedState.kind === 'wooden-fish'
? Math.min(PUZZLE_NON_READY_MAX_PROGRESS, overallProgress)
: overallProgress;
: Math.min(PUZZLE_NON_READY_MAX_PROGRESS, overallProgress);
return {
phaseId: normalizedState.phase,
@@ -1036,9 +983,9 @@ export function buildMiniGameDraftGenerationProgress(
? '宝贝识物草稿已准备完成，可进入结果页继续发布。'
: normalizedState.kind === 'jump-hop'
? '跳一跳草稿已准备完成，可进入结果页试玩或发布。'
: normalizedState.kind === 'wooden-fish'
? '敲木鱼草稿已准备完成，可进入结果页试玩或发布。'
: '首关草稿与正式图已准备完成，可进入结果页补作品信息。'
: normalizedState.kind === 'wooden-fish'
? '敲木鱼草稿已准备完成，可进入结果页试玩或发布。'
: '首关草稿与正式图已准备完成，可进入结果页补作品信息。'
: activeStep.detail),
batchLabel: activeStep.label,
overallProgress: clampProgress(cappedOverallProgress),
@@ -1046,10 +993,13 @@ export function buildMiniGameDraftGenerationProgress(
totalWeight: 100,
elapsedMs,
estimatedRemainingMs:
normalizedState.phase === 'ready'
normalizedState.phase === 'ready' || normalizedState.phase === 'failed'
? 0
: normalizedState.kind === 'puzzle'
? Math.max(0, resolvePuzzleEstimatedWaitMs(normalizedState) - elapsedMs)
? Math.max(
0,
resolvePuzzleEstimatedWaitMs(normalizedState) - elapsedMs,
)
: normalizedState.kind === 'big-fish'
? Math.max(0, 7_000 - elapsedMs)
: normalizedState.kind === 'square-hole'
@@ -1057,15 +1007,12 @@ export function buildMiniGameDraftGenerationProgress(
: normalizedState.kind === 'match3d'
? Math.max(0, MATCH3D_ESTIMATED_WAIT_MS - elapsedMs)
: normalizedState.kind === 'baby-object-match'
? Math.max(
0,
BABY_OBJECT_MATCH_ESTIMATED_WAIT_MS - elapsedMs,
)
? Math.max(0, BABY_OBJECT_MATCH_ESTIMATED_WAIT_MS - elapsedMs)
: normalizedState.kind === 'jump-hop'
? Math.max(0, JUMP_HOP_ESTIMATED_WAIT_MS - elapsedMs)
: normalizedState.kind === 'wooden-fish'
? Math.max(0, WOODEN_FISH_ESTIMATED_WAIT_MS - elapsedMs)
: null,
: normalizedState.kind === 'wooden-fish'
? Math.max(0, WOODEN_FISH_ESTIMATED_WAIT_MS - elapsedMs)
: null,
activeStepIndex,
steps: buildMiniGameProgressSteps(
steps,