@actalk/inkos-core 1.6.3 → 1.7.0

package/dist/agent/agent-tools.js

@@ -12,9 +12,11 @@ import { safeChildPath } from "../utils/path-safety.js";
 import { normalizePlatformId, normalizePlatformOrOther } from "../models/book.js";
 import { generateShortFictionCover, runShortFictionProduction } from "../pipeline/short-fiction-runner.js";
 import { runInteractiveFilmCreation, runScriptCreation, runStoryboardCreation } from "../pipeline/script-storyboard-runner.js";
+import { createTranslationProjectFromFile } from "../translation/index.js";
 import { runResearchReport } from "../agents/researcher.js";
 import { ingestMaterial } from "../materials/ingest.js";
 import { retrieveMaterials } from "../materials/retrieve.js";
+import { loadChaptersFromPath } from "./chapter-import-source.js";
 import { createPlayDB } from "../play/play-db-factory.js";
 import { PlayRunner } from "../play/play-runner.js";
 import { PlayStore } from "../play/play-store.js";
@@ -49,6 +51,10 @@ function createDeterministicInteractionTools(pipeline, projectRoot) {
 function closePlayDB(db) {
     db.close?.();
 }
+// runnerFactory 注入的测试替身没有 close 方法，可选调用兜底。
+function closePlayRunner(runner) {
+    runner.close?.();
+}
 function safePlayId(value, fallback) {
     const raw = (value?.trim() || fallback).slice(0, 80);
     if (!raw || raw === "." || raw === ".." || raw.includes("/") || raw.includes("\\") || raw.includes("\0")) {
@@ -98,6 +104,7 @@ const ProposeActionParams = Type.Object({
         Type.Literal("script_create"),
         Type.Literal("storyboard_create"),
         Type.Literal("interactive_film_create"),
+        Type.Literal("translation_create"),
         Type.Literal("draft_structure"),
         Type.Literal("connect_choice"),
         Type.Literal("remove_node"),
@@ -229,6 +236,13 @@ const ProposeActionParams = Type.Object({
         projectId: Type.Optional(Type.String({ description: "Optional output id under interactive-films/." })),
         outDir: Type.Optional(Type.String({ description: "Optional project-relative output directory. Default interactive-films/." })),
     }, { description: "Structured execution args for action=interactive_film_create." })),
+    translationCreate: Type.Optional(Type.Object({
+        filePath: Type.Optional(Type.String({ description: "Project-relative EPUB/PDF/TXT/Markdown source file path to translate." })),
+        sourceLanguage: Type.Optional(Type.String({ description: "Source language as a human-readable name, e.g. Auto detect, Japanese, English, Chinese (Simplified), 繁体中文（台湾）. Do not require ISO abbreviations." })),
+        targetLanguage: Type.Optional(Type.String({ description: "Target language as a human-readable name, e.g. Chinese (Simplified), English, Japanese, Korean, Brazilian Portuguese. Do not require ISO abbreviations." })),
+        title: Type.Optional(Type.String({ description: "Optional translation project title." })),
+        segmentMaxChars: Type.Optional(Type.Number({ description: "Optional long-paragraph split threshold." })),
+    }, { description: "Structured execution args for action=translation_create." })),
 });
 function proposedActionSessionKind(action) {
     if (action === "create_book")
@@ -241,6 +255,8 @@ function proposedActionSessionKind(action) {
         return "storyboard";
     if (action === "interactive_film_create")
         return "interactive-film";
+    if (action === "translation_create")
+        return "chat";
     if (action === "draft_structure" || action === "connect_choice" || action === "remove_node")
         return "interactive-film-authoring";
     if (action === "fanfic_init" || action === "continuation_import" || action === "spinoff_create" || action === "style_imitation")
@@ -282,6 +298,8 @@ function proposedActionFallbackTitle(action, isZh) {
             return isZh ? "创建分镜" : "Create storyboard";
         case "interactive_film_create":
             return isZh ? "创建互动影游" : "Create interactive film";
+        case "translation_create":
+            return isZh ? "创建翻译项目" : "Create translation project";
         case "draft_structure":
             return isZh ? "生成故事结构" : "Draft story structure";
         case "connect_choice":
@@ -392,6 +410,11 @@ function proposedActionPayload(params) {
         if (interactiveFilmCreate)
             payload.interactiveFilmCreate = interactiveFilmCreate;
     }
+    if (params.action === "translation_create") {
+        const translationCreate = compactObject(params.translationCreate);
+        if (translationCreate)
+            payload.translationCreate = translationCreate;
+    }
     return Object.keys(payload).length > 0 ? payload : undefined;
 }
 function validateProposedActionPayload(payload) {
@@ -432,6 +455,12 @@ function assertExecutableProposedAction(params, payload) {
     }
     if (params.action === "interactive_film_create") {
         requireProposedText(payload?.interactiveFilmCreate?.title, "interactiveFilmCreate.title");
+        return;
+    }
+    if (params.action === "translation_create") {
+        requireProposedText(payload?.translationCreate?.filePath, "translationCreate.filePath");
+        requireProposedText(payload?.translationCreate?.sourceLanguage, "translationCreate.sourceLanguage");
+        requireProposedText(payload?.translationCreate?.targetLanguage, "translationCreate.targetLanguage");
     }
 }
 export function createProposeActionTool(language = "zh", options = {}) {
@@ -562,7 +591,16 @@ function prepareSubAgentArguments(args) {
     }
     return prepared;
 }
+function runPipelineWithAbortSignal(pipeline, signal, task) {
+    // PipelineRunner owns the async cancellation scope. The fallback keeps
+    // lightweight embedders/test doubles source-compatible.
+    const runner = pipeline;
+    return runner.runWithAbortSignal
+        ? runner.runWithAbortSignal(signal, task)
+        : task();
+}
 export function createSubAgentTool(pipeline, activeBookId, projectRoot, options = {}) {
+    const sessionIsZh = (options.language ?? "zh") !== "en";
     return {
         name: "sub_agent",
         description: options.architectCreateOnly
@@ -586,7 +624,9 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                     return textResult("No active book. Only the architect agent can create a book from this session.");
                 }
                 if (activeBookId && agent === "architect" && !revise) {
-                    return textResult("当前已有书籍，不需要建书。如果你想创建新书，请先回到首页。");
+                    return textResult(sessionIsZh
+                        ? "当前已有书籍，不需要建书。如果你想创建新书，请先回到首页。"
+                        : "This session already has a book, so no new book is needed. To create a new book, go back to the home page first.");
                 }
                 switch (agent) {
                     case "architect": {
@@ -597,9 +637,11 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                             }
                             const targetBookId = resolveToolBookId("architect", bookId, activeBookId);
                             progress(`Revising foundation for "${targetBookId}"...`);
-                            await pipeline.reviseFoundation(targetBookId, feedback ?? instruction);
+                            await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.reviseFoundation(targetBookId, feedback ?? instruction));
                             progress(`Foundation revised for "${targetBookId}".`);
-                            return textResult(`Book "${targetBookId}" 架构稿已按要求重写。原书的条目式架构稿已备份到 story/.backup-phase4-<时间戳>/。`);
+                            return textResult(sessionIsZh
+                                ? `Book "${targetBookId}" 架构稿已按要求重写。原书的条目式架构稿已备份到 story/.backup-phase4-<时间戳>/。`
+                                : `Book "${targetBookId}" foundation has been rewritten as requested. The previous itemized foundation was backed up to story/.backup-phase4-<timestamp>/.`);
                         }
                         const confirmedTitle = createBookPayload?.title?.trim();
                         const resolvedTitle = confirmedTitle || title?.trim();
@@ -614,7 +656,7 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                         const now = new Date().toISOString();
                         const resolvedLanguage = createBookPayload?.language ?? language ?? inferLanguage(instruction);
                         progress(`Starting architect for book "${id}"...`);
-                        await pipeline.initBook({
+                        await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.initBook({
                             id,
                             title: resolvedTitle,
                             genre: createBookPayload?.genre ?? genre ?? "general",
@@ -625,14 +667,14 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                             chapterWordCount: createBookPayload?.chapterWordCount ?? chapterWordCount ?? defaultChapterLength(resolvedLanguage),
                             createdAt: now,
                             updatedAt: now,
-                        }, { externalContext: instruction });
+                        }, { externalContext: instruction }));
                         progress(`Architect finished — book "${id}" foundation created.`);
                         return textResult(`Book "${resolvedTitle}" (${id}) initialised successfully. Foundation files are ready.`, { kind: "book_created", bookId: id, title: resolvedTitle });
                     }
                     case "writer": {
                         const targetBookId = resolveToolBookId("writer", bookId, activeBookId);
                         progress(`Writing next chapter for "${targetBookId}"...`);
-                        const result = await pipeline.writeNextChapter(targetBookId, chapterWordCount);
+                        const result = await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.writeNextChapter(targetBookId, chapterWordCount));
                         progress(`Writer finished chapter for "${targetBookId}".`);
                         const resultStatus = result.status;
                         const wordCount = result.wordCount ?? "unknown";
@@ -653,7 +695,7 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                     case "auditor": {
                         const targetBookId = resolveToolBookId("auditor", bookId, activeBookId);
                         progress(`Auditing chapter ${chapterNumber ?? "latest"} for "${targetBookId}"...`);
-                        const audit = await pipeline.auditDraft(targetBookId, chapterNumber);
+                        const audit = await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.auditDraft(targetBookId, chapterNumber));
                         progress(`Audit complete for "${targetBookId}".`);
                         const issueLines = (audit.issues ?? [])
                             .map((i) => `[${i.severity}] ${i.description}`)
@@ -665,7 +707,7 @@ export function createSubAgentTool(pipeline, activeBookId, projectRoot, options
                         const targetBookId = resolveToolBookId("reviser", bookId, activeBookId);
                         const resolvedMode = mode ?? "spot-fix";
                         progress(`Revising "${targetBookId}" chapter ${chapterNumber ?? "latest"} in ${resolvedMode} mode...`);
-                        const result = await pipeline.reviseDraft(targetBookId, chapterNumber, resolvedMode, instruction);
+                        const result = await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.reviseDraft(targetBookId, chapterNumber, resolvedMode, instruction));
                         const applied = result.applied !== false;
                         const resultChapter = result.chapterNumber ?? chapterNumber;
                         const details = {
@@ -952,6 +994,76 @@ export function createRetrieveMaterialTool(projectRoot) {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// 5. Chapter Import Tool (import_chapters)
+// ---------------------------------------------------------------------------
+const ImportChaptersParams = Type.Object({
+    bookId: Type.Optional(Type.String({
+        description: "Target book ID to import into. In active-book sessions, omit it to use the current active book; if provided, it must match the active book. In general chat there is no active book, so it is required and must be an existing book.",
+    })),
+    sourcePath: Type.String({
+        description: "Local path of the chapter source: either the stored_path from the Uploaded Files block (project-relative, e.g. .inkos/uploads/<session>/novel.txt) or an absolute path on this machine that the user provided. A directory imports each .md/.txt file as one chapter in filename order; a single file is split into chapters automatically by heading lines.",
+    }),
+    splitPattern: Type.Optional(Type.String({
+        description: "Single-file mode only: custom JavaScript regex source matching chapter heading lines. Omit to use the default pattern, which matches \"第X章/第X回\" and \"Chapter N\" headings.",
+    })),
+    resumeFrom: Type.Optional(Type.Number({
+        description: "Resume an interrupted import from chapter N (1-based). Required when the book already has chapters: replay starts at chapter N and earlier chapters are kept. Omit for a fresh import into an empty book.",
+    })),
+    importMode: Type.Optional(Type.Union([
+        Type.Literal("continuation"),
+        Type.Literal("series"),
+    ], {
+        description: "continuation (default): the book picks up exactly where the imported text left off, no new spacetime. series: shared universe but an independent new story, so a new spacetime is generated.",
+    })),
+});
+export function createImportChaptersTool(pipeline, activeBookId, projectRoot) {
+    return {
+        name: "import_chapters",
+        description: "Import an existing novel's chapters from a local file or directory into an InkOS book as real chapters (not reference material). " +
+            "InkOS reverse-engineers foundation/truth files from the imported text and replays every chapter to rebuild story state, so the book can be continued afterwards. " +
+            "Use ingest_material instead when the user only wants to archive reference material without touching book chapters.",
+        label: "Import Chapters",
+        parameters: ImportChaptersParams,
+        async execute(_toolCallId, params, _signal, onUpdate) {
+            const targetBookId = resolveToolBookId("import_chapters", params.bookId, activeBookId);
+            const state = new StateManager(projectRoot);
+            const existingChapterCount = (await state.getNextChapterNumber(targetBookId)) - 1;
+            if (existingChapterCount > 0 && params.resumeFrom === undefined) {
+                throw new Error(`Book "${targetBookId}" already has ${existingChapterCount} chapter(s). ` +
+                    `Pass resumeFrom=<n> to resume/append from chapter n, or ask the user to clear the existing chapters first.`);
+            }
+            const resolvedSourcePath = isAbsolute(params.sourcePath)
+                ? params.sourcePath
+                : resolve(projectRoot, params.sourcePath);
+            onUpdate?.(textResult(`Reading chapters from ${resolvedSourcePath}...`));
+            const chapters = await loadChaptersFromPath(resolvedSourcePath, params.splitPattern);
+            onUpdate?.(textResult(`Found ${chapters.length} chapter(s); importing into "${targetBookId}"...`));
+            const result = await runPipelineWithAbortSignal(pipeline, _signal, () => pipeline.importChapters({
+                bookId: targetBookId,
+                chapters,
+                resumeFrom: params.resumeFrom,
+                importMode: params.importMode,
+            }));
+            const regeneratedFoundation = (params.resumeFrom ?? 1) === 1;
+            return textResult([
+                `Imported ${result.importedCount} chapter(s) into book "${result.bookId}".`,
+                `Total imported length: ${result.totalWords}. Next chapter to write: ${result.nextChapter}.`,
+                regeneratedFoundation
+                    ? "Foundation and truth files were reverse-engineered from the imported text; chapter files and the chapter index were rebuilt by sequential replay."
+                    : `Resumed replay from chapter ${params.resumeFrom}; earlier chapters and the existing foundation were kept.`,
+                `The book can now be continued with sub_agent(agent="writer") in the book session.`,
+            ].join("\n"), {
+                kind: "chapters_imported",
+                bookId: result.bookId,
+                importedCount: result.importedCount,
+                totalWords: result.totalWords,
+                nextChapter: result.nextChapter,
+                importMode: params.importMode ?? "continuation",
+            });
+        },
+    };
+}
 function slugResearchTopic(topic) {
     const slug = topic
         .normalize("NFKC")
@@ -987,7 +1099,7 @@ const ShortFictionRunParams = Type.Object({
         description: "Target complete short chapter count, 12-18. Default 12.",
     })),
     charsPerChapter: Type.Optional(Type.Number({
-        description: "Target Chinese characters per chapter, 900-1200. Default 1000. Do not use total story length here.",
+        description: "Per-chapter length in the story language's native unit: 900-1200 Chinese characters (default 1000) for zh, or 600-800 English words (default 650) for en. Do not use total story length here.",
     })),
     cover: Type.Optional(Type.Boolean({
         description: "Whether to attempt cover image generation after synopsis and cover prompt. Default true; use false if the user only wants text assets.",
@@ -1034,6 +1146,7 @@ export function createShortFictionRunTool(pipeline, projectRoot, options = {}) {
                 storyId: shortPayload?.storyId ?? params.storyId,
                 chapterCount: shortPayload?.chapters ?? params.chapters,
                 charsPerChapter: shortPayload?.charsPerChapter ?? params.charsPerChapter,
+                language: options.language,
                 cover: shortPayload?.cover ?? params.cover,
                 coverBaseUrl: params.coverBaseUrl,
                 coverEndpoint: params.coverEndpoint,
@@ -1072,7 +1185,53 @@ function summarizeCoverGenerationError(error) {
     return text.slice(0, 300);
 }
 // ---------------------------------------------------------------------------
-// 3. Script and Storyboard tools
+// 3. Translation tool
+// ---------------------------------------------------------------------------
+const TranslationCreateParams = Type.Object({
+    filePath: Type.String({
+        description: "Project-relative EPUB/PDF/TXT/Markdown source file path to translate.",
+    }),
+    sourceLanguage: Type.String({
+        description: "Source language as a human-readable name, e.g. Auto detect, Japanese, English, Chinese (Simplified), 繁体中文（台湾）. Do not require ISO abbreviations.",
+    }),
+    targetLanguage: Type.String({
+        description: "Target language as a human-readable name, e.g. Chinese (Simplified), English, Japanese, Korean, Brazilian Portuguese. Do not require ISO abbreviations.",
+    }),
+    title: Type.Optional(Type.String({
+        description: "Optional translation project title.",
+    })),
+    segmentMaxChars: Type.Optional(Type.Number({
+        description: "Optional max chars per segment before splitting long paragraphs.",
+    })),
+});
+export function createTranslationCreateTool(projectRoot, options = {}) {
+    return {
+        name: "translation_create",
+        description: "Create an InkOS translation project from an EPUB/PDF/TXT/Markdown file. " +
+            "This only ingests and segments the source; running the actual translation is a separate long task.",
+        label: "Translation",
+        parameters: TranslationCreateParams,
+        async execute(_toolCallId, params) {
+            const payload = options.actionPayload?.translationCreate;
+            const result = await createTranslationProjectFromFile(projectRoot, {
+                filePath: payload?.filePath ?? params.filePath,
+                sourceLanguage: payload?.sourceLanguage ?? params.sourceLanguage,
+                targetLanguage: payload?.targetLanguage ?? params.targetLanguage,
+                title: payload?.title ?? params.title,
+                segmentMaxChars: payload?.segmentMaxChars ?? params.segmentMaxChars,
+            });
+            return textResult([
+                `Translation project "${result.manifest.title}" created.`,
+                `ID: ${result.manifest.id}`,
+                `Source: ${result.manifest.source.kind} ${result.manifest.sourceLanguage} -> ${result.manifest.targetLanguage}`,
+                `Chapters: ${result.manifest.chapters.length}`,
+                `Manifest: ${result.manifestPath}`,
+            ].join("\n"), { kind: "translation_project_created", ...result });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 4. Script and Storyboard tools
 // ---------------------------------------------------------------------------
 const ScriptCreateParams = Type.Object({
     title: Type.String({
@@ -1135,6 +1294,7 @@ export function createScriptCreationTool(pipeline, projectRoot, options = {}) {
                 requirements: payload?.requirements ?? params.requirements,
                 episodeCount: payload?.episodeCount ?? params.episodeCount,
                 episodeDuration: payload?.episodeDuration ?? params.episodeDuration,
+                language: options.language,
                 projectId: payload?.projectId ?? params.projectId,
                 outDir: payload?.outDir ?? params.outDir,
                 onProgress: progress,
@@ -1208,6 +1368,7 @@ export function createStoryboardCreationTool(pipeline, projectRoot, options = {}
                 aspectRatio: payload?.aspectRatio ?? params.aspectRatio,
                 granularity: payload?.granularity ?? params.granularity,
                 maxShots: payload?.maxShots ?? params.maxShots,
+                language: options.language,
                 projectId: payload?.projectId ?? params.projectId,
                 outDir: payload?.outDir ?? params.outDir,
                 onProgress: progress,
@@ -1287,6 +1448,7 @@ export function createInteractiveFilmCreationTool(pipeline, projectRoot, options
                 episodeDuration: payload?.episodeDuration ?? params.episodeDuration,
                 budget: payload?.budget ?? params.budget,
                 referenceMode: payload?.referenceMode ?? params.referenceMode,
+                language: options.language,
                 projectId: payload?.projectId ?? params.projectId,
                 outDir: payload?.outDir ?? params.outDir,
                 onProgress: progress,
@@ -1588,7 +1750,7 @@ const PlayEditParams = Type.Object({
         description: "Short human-readable note summarizing what changed.",
     })),
 });
-export function createPlayEditTool(projectRoot, sessionId) {
+export function createPlayEditTool(projectRoot, sessionId, language = "zh") {
     return {
         name: "play_edit",
         description: "Persistently edit the active InkOS Play world card, visual contract, player persona, or entity/role cards without advancing time or narrating a turn. " +
@@ -1601,8 +1763,11 @@ export function createPlayEditTool(projectRoot, sessionId) {
             const runId = "main";
             const world = await store.loadWorld(worldId);
             if (!world) {
-                return textResult("还没有可编辑的互动世界。先用 play_start 开一局。");
+                return textResult(language === "en"
+                    ? "There is no interactive world to edit yet. Start one with play_start first."
+                    : "还没有可编辑的互动世界。先用 play_start 开一局。");
             }
+            const isZh = (world.language ?? "zh") !== "en";
             const patch = {};
             const nextWorldContract = mergeContract(world.worldContract, params.worldContract, params.worldContractReplacements, params.worldContractAppend);
             const nextVisualContract = mergeContract(world.visualContract, params.visualContract, params.visualContractReplacements, params.visualContractAppend);
@@ -1626,9 +1791,9 @@ export function createPlayEditTool(projectRoot, sessionId) {
                     upsertPlayEditEntity(db, {
                         id: "actor_player",
                         type: "actor",
-                        label: existingPlayer?.label ?? "玩家",
+                        label: existingPlayer?.label ?? (isZh ? "玩家" : "Player"),
                         summary: playerPersona,
-                        status: "已更新",
+                        status: isZh ? "已更新" : "Updated",
                     });
                     updatedEntities += 1;
                 }
@@ -1645,7 +1810,7 @@ export function createPlayEditTool(projectRoot, sessionId) {
                     premise: updatedWorld.premise,
                     graphEditedAt: new Date().toISOString(),
                 });
-                return textResult(params.note?.trim() || "互动世界设定已更新。", {
+                return textResult(params.note?.trim() || (isZh ? "互动世界设定已更新。" : "Interactive world settings updated."), {
                     kind: "play_world_updated",
                     worldId,
                     runId,
@@ -1680,7 +1845,9 @@ export function createPlayStepTool(pipeline, projectRoot, sessionId, options = {
             const runId = "main";
             const world = await store.loadWorld(worldId);
             if (!world) {
-                return textResult("还没有可推进的互动世界。先用 play_start 开一局。");
+                return textResult(options.language === "en"
+                    ? "There is no interactive world to advance yet. Start one with play_start first."
+                    : "还没有可推进的互动世界。先用 play_start 开一局。");
             }
             const target = { worldId, runId, world };
             onUpdate?.(textResult(`Advancing "${target.worldId}" / "${target.runId}"...`));
@@ -1714,6 +1881,9 @@ export function createPlayStepTool(pipeline, projectRoot, sessionId, options = {
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
+            finally {
+                closePlayRunner(runner);
+            }
             const db = createPlayDB(store.runDir(target.worldId, target.runId));
             let graph;
             try {
@@ -1751,8 +1921,11 @@ export function createPlayReviseTool(pipeline, projectRoot, sessionId, options =
             const runId = "main";
             const world = await store.loadWorld(worldId);
             if (!world) {
-                return textResult("还没有可重做的互动世界。先用 play_start 开一局。");
+                return textResult(options.language === "en"
+                    ? "There is no interactive world to redo yet. Start one with play_start first."
+                    : "还没有可重做的互动世界。先用 play_start 开一局。");
             }
+            const isZh = (world.language ?? "zh") !== "en";
             const ctx = pipeline.createAgentContext("play");
             const runner = options.runnerFactory?.({ projectRoot, worldId, runId, ctx }) ?? new PlayRunner({
                 projectRoot,
@@ -1760,46 +1933,55 @@ export function createPlayReviseTool(pipeline, projectRoot, sessionId, options =
                 runId,
                 ctx,
             });
-            if (params.action === "restore_variant") {
-                const turn = params.turn;
-                const variantId = params.variantId?.trim();
-                if (typeof turn !== "number" || !Number.isFinite(turn) || !variantId) {
-                    return textResult("恢复版本需要 turn 和 variantId。");
-                }
-                onUpdate?.(textResult(`Restoring play variant "${variantId}"...`));
-                const restored = await runner.restoreVariant({
-                    turn: Math.trunc(turn),
-                    variantId,
-                });
-                return textResult(restored.sceneText || "已切换到指定互动回合版本。", {
-                    kind: "play_variant_restored",
-                    worldId,
-                    runId,
-                    title: world.title,
-                    turn: restored.turn,
-                    variantId: restored.variantId,
-                    sceneText: restored.sceneText,
-                });
-            }
-            const replacement = params.action === "edit_last_input" ? params.input?.trim() : undefined;
-            if (params.action === "edit_last_input" && !replacement) {
-                return textResult("编辑上一条玩家动作需要提供新的 input。");
-            }
-            onUpdate?.(textResult(params.action === "edit_last_input" ? "Replaying edited play turn..." : "Regenerating last play turn..."));
             let replay;
+            // finally 关闭 runner 自建的 play.db 连接：句柄不关闭时 Windows 上无法删除数据库文件。
             try {
-                replay = await runner.regenerateLastTurn(replacement);
+                if (params.action === "restore_variant") {
+                    const turn = params.turn;
+                    const variantId = params.variantId?.trim();
+                    if (typeof turn !== "number" || !Number.isFinite(turn) || !variantId) {
+                        return textResult(isZh
+                            ? "恢复版本需要 turn 和 variantId。"
+                            : "Restoring a variant requires both turn and variantId.");
+                    }
+                    onUpdate?.(textResult(`Restoring play variant "${variantId}"...`));
+                    const restored = await runner.restoreVariant({
+                        turn: Math.trunc(turn),
+                        variantId,
+                    });
+                    return textResult(restored.sceneText || (isZh ? "已切换到指定互动回合版本。" : "Switched to the requested play turn variant."), {
+                        kind: "play_variant_restored",
+                        worldId,
+                        runId,
+                        title: world.title,
+                        turn: restored.turn,
+                        variantId: restored.variantId,
+                        sceneText: restored.sceneText,
+                    });
+                }
+                const replacement = params.action === "edit_last_input" ? params.input?.trim() : undefined;
+                if (params.action === "edit_last_input" && !replacement) {
+                    return textResult(isZh
+                        ? "编辑上一条玩家动作需要提供新的 input。"
+                        : "Editing the previous player action requires a new input.");
+                }
+                onUpdate?.(textResult(params.action === "edit_last_input" ? "Replaying edited play turn..." : "Regenerating last play turn..."));
+                try {
+                    replay = await runner.regenerateLastTurn(replacement);
+                }
+                catch (err) {
+                    return textResult(isZh
+                        ? "（上一回合暂时不能安全重做。继续输入新的动作，我会从当前状态推进。）"
+                        : "(The previous turn cannot be safely regenerated yet. Enter a new action and I will continue from the current state.)", {
+                        kind: "play_revise_failed",
+                        worldId,
+                        runId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
             }
-            catch (err) {
-                const isZh = (world.language ?? "zh") !== "en";
-                return textResult(isZh
-                    ? "（上一回合暂时不能安全重做。继续输入新的动作，我会从当前状态推进。）"
-                    : "(The previous turn cannot be safely regenerated yet. Enter a new action and I will continue from the current state.)", {
-                    kind: "play_revise_failed",
-                    worldId,
-                    runId,
-                    error: err instanceof Error ? err.message : String(err),
-                });
+            finally {
+                closePlayRunner(runner);
             }
             const db = createPlayDB(store.runDir(worldId, runId));
             let graph;