@actalk/inkos-studio 1.4.1 → 1.5.0-canary.47.1

package/dist/api/server.js

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { streamSSE } from "hono/streaming";
 import { serve } from "@hono/node-server";
-import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionRequest, resolveSessionActiveBook, listBookSessions, loadBookSession, appendManualSessionMessages, createAndPersistBookSession, renameBookSession, deleteBookSession, migrateBookSession, SessionAlreadyMigratedError, runAgentSession, buildAgentSystemPrompt, resolveServicePreset, resolveServiceProviderFamily, resolveServiceModelsBaseUrl, resolveServiceModel, loadSecrets, saveSecrets, listModelsForService, isApiKeyOptionalForEndpoint, getAllEndpoints, probeModelsFromUpstream, fetchWithProxy, chatCompletion, buildExportArtifact, GLOBAL_ENV_PATH, COVER_PROVIDER_PRESETS, Scheduler, coverSecretKey, resolveCoverProviderPreset, } from "@actalk/inkos-core";
+import { StateManager, PipelineRunner, createLLMClient, createLogger, createInteractionToolsFromDeps, computeAnalytics, loadProjectConfig, loadProjectSession, processProjectInteractionRequest, resolveSessionActiveBook, listBookSessions, loadBookSession, appendManualSessionMessages, createAndPersistBookSession, renameBookSession, deleteBookSession, migrateBookSession, SessionAlreadyMigratedError, runAgentSession, resolveServicePreset, resolveServiceProviderFamily, resolveServiceModelsBaseUrl, guessServiceFromBaseUrl, resolveServiceModel, loadSecrets, saveSecrets, listModelsForService, isApiKeyOptionalForEndpoint, getAllEndpoints, probeModelsFromUpstream, fetchWithProxy, chatCompletion, buildExportArtifact, evaluateBookQuality, ConsolidatorAgent, DetectionConfigSchema, InputGovernanceModeSchema, GLOBAL_ENV_PATH, COVER_PROVIDER_PRESETS, createPlayDB, PlayStore, buildPlayEntityImagePrompt, buildPlaySceneImagePrompt, generatePlayImage, readPlayImageManifest, readPlayImageSettings, writePlayImageSettings, Scheduler, coverSecretKey, resolveCoverProviderPreset, SessionKindSchema, isExplicitWriteChapterCommand, isUsablePlayInitialScene, isWriteNextInstruction, normalizeActionSource as normalizeCoreActionSource, normalizeActionPayload as normalizeCoreActionPayload, normalizePlayMode as normalizeCorePlayMode, normalizeRequestedIntent as normalizeCoreRequestedIntent, inferLanguage, createGenerateCoverTool, createPlayStartTool, createShortFictionRunTool, createSubAgentTool, } from "@actalk/inkos-core";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { isSafeBookId } from "./safety.js";
@@ -31,8 +31,13 @@ const AGENT_LABELS = {
 };
 const TOOL_LABELS = {
     read: "读取文件", edit: "编辑文件", grep: "搜索", ls: "列目录",
+    propose_action: "确认动作",
     short_fiction_run: "短篇生产",
     generate_cover: "生成封面",
+    play_edit: "编辑互动世界",
+    play_start: "启动互动世界",
+    play_revise: "重做互动回合",
+    play_step: "推进互动世界",
 };
 function resolveToolLabel(tool, agent) {
     if (tool === "sub_agent" && agent)
@@ -77,6 +82,9 @@ const NON_TEXT_MODEL_ID_PARTS = [
 ];
 const SERVICE_MODELS_PROBE_TIMEOUT_MS = 4_000;
 const SERVICE_CHAT_PROBE_TIMEOUT_MS = 8_000;
+// Hard ceiling for the whole /doctor connectivity probe (models + chat fallback
+// loop) so the diagnostics page never spins on a slow/rate-limited upstream.
+const DOCTOR_LLM_PROBE_BUDGET_MS = 9_000;
 const MAX_DISCOVERED_MODELS_TO_PING = 2;
 const MAX_GENERIC_FALLBACK_MODELS_TO_PING = 2;
 function isTextChatModelId(modelId) {
@@ -168,10 +176,64 @@ function hasSuccessfulSubAgentExec(execs, agent) {
         && exec.status === "completed"
         && !isLikelyFailedToolResult(exec));
 }
-function isWriteNextInstruction(instruction) {
-    const trimmed = instruction.trim();
-    return /^(continue|继续|继续写|写下一章|write next|下一章|再来一章)$/i.test(trimmed)
-        || /(继续写|写下一章|下一章|再来一章|write\s+next)/i.test(trimmed);
+function hasSuccessfulToolExec(execs, tool) {
+    return execs.some((exec) => exec.tool === tool
+        && exec.status === "completed"
+        && !isLikelyFailedToolResult(exec));
+}
+function hasSuccessfulToolResult(execs) {
+    return execs.some((exec) => exec.status === "completed" && !isLikelyFailedToolResult(exec));
+}
+function normalizeStudioSessionKind(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const parsed = SessionKindSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new ApiError(400, "INVALID_SESSION_KIND", `Invalid sessionKind: ${String(value)}`);
+    }
+    return parsed.data;
+}
+function normalizeStudioActionSource(value) {
+    try {
+        return normalizeCoreActionSource(value);
+    }
+    catch {
+        throw new ApiError(400, "INVALID_ACTION_SOURCE", `Invalid actionSource: ${String(value)}`);
+    }
+}
+function normalizeStudioRequestedIntent(value) {
+    try {
+        return normalizeCoreRequestedIntent(value);
+    }
+    catch {
+        throw new ApiError(400, "INVALID_REQUESTED_INTENT", `Invalid requestedIntent: ${String(value)}`);
+    }
+}
+function normalizeStudioActionPayload(value) {
+    try {
+        return normalizeCoreActionPayload(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ApiError(400, "INVALID_ACTION_PAYLOAD", `Invalid actionPayload: ${message}`);
+    }
+}
+function normalizeStudioPlayMode(value) {
+    try {
+        return normalizeCorePlayMode(value);
+    }
+    catch {
+        throw new ApiError(400, "INVALID_PLAY_MODE", `Invalid playMode: ${String(value)}`);
+    }
+}
+function shouldRunDirectWriteNext(args) {
+    if (!args.agentBookId || args.sessionKind !== "book")
+        return false;
+    if (args.requestedIntent === "write_next")
+        return true;
+    if (args.actionSource === "free-text")
+        return isExplicitWriteChapterCommand(args.instruction);
+    return isWriteNextInstruction(args.instruction);
 }
 const CHAT_EDIT_WARNING = "[warning] Chat external edit requires review before continuation.";
 const CHAT_EDIT_TEXT_EXTENSIONS = /\.(md|txt|json|ya?ml)$/i;
@@ -191,6 +253,18 @@ function parseReplacementInstruction(instruction) {
     }
     return null;
 }
+function isExplicitExternalChatEditInstruction(instruction) {
+    const trimmed = instruction.trim();
+    if (!trimmed)
+        return false;
+    if (/[?？]\s*$/.test(trimmed))
+        return false;
+    if (/^(?:请问|能否|能不能|可以|可不可以|是否|是不是|怎么|怎样|为什么|如果|假如|要不要|建议|讨论)\b/u.test(trimmed)) {
+        return false;
+    }
+    const imperative = trimmed.replace(/^(?:请|麻烦|帮我|直接|现在)\s*/u, "");
+    return /^(?:第\s*\d{1,4}\s*章\s*)?(?:把|将)\s*/u.test(imperative);
+}
 function parseChapterNumberForEdit(instruction) {
     const match = instruction.match(/第\s*(\d{1,4})\s*章/);
     if (!match?.[1])
@@ -278,6 +352,8 @@ async function tryHandleExternalChatEdit(params) {
     const replacement = parseReplacementInstruction(params.instruction);
     if (!replacement)
         return null;
+    if (!isExplicitExternalChatEditInstruction(params.instruction))
+        return null;
     const explicitPath = parseExplicitEditPath(params.instruction);
     if (explicitPath) {
         const target = resolveExternalChatEditPath(params.root, explicitPath);
@@ -342,27 +418,247 @@ async function tryHandleExternalChatEdit(params) {
         responseText: `已直接编辑 ${params.activeBookId} 第 ${chapterNumber} 章，并标记为需要复核。`,
     };
 }
-function looksLikeBookCreatedClaim(responseText) {
-    return /(?:已|已经|成功).{0,12}(?:创建|建书|初始化|保存).{0,12}(?:作品|书|书籍|文件夹)?/.test(responseText)
-        || /\b(?:created|initiali[sz]ed|saved)\b.{0,40}\b(?:book|project|novel)\b/i.test(responseText);
-}
 function validateAgentActionExecution(args) {
     const failedExec = args.collectedToolExecs.find(isLikelyFailedToolResult);
     if (failedExec) {
         return `${failedExec.label} 执行失败：${failedExec.error ?? failedExec.result ?? "未知错误"}`;
     }
     if (args.agentBookId
-        && isWriteNextInstruction(args.instruction)
+        && args.requestedIntent === "write_next"
         && !hasSuccessfulSubAgentExec(args.collectedToolExecs, "writer")) {
         return "模型声称已完成下一章，但没有实际调用写作工具。请重试；如果仍失败，请检查模型是否支持工具调用。";
     }
     if (!args.agentBookId
-        && looksLikeBookCreatedClaim(args.responseText)
-        && !resolveCreatedBookIdFromToolExecs(args.collectedToolExecs)) {
-        return "模型声称已创建作品，但没有实际调用建书工具，也没有生成作品文件。请补充书名/题材后重试，或换用支持工具调用的模型。";
+        && args.requestedIntent === "create_book"
+        && !hasSuccessfulSubAgentExec(args.collectedToolExecs, "architect")) {
+        return "已确认建书，但模型没有实际调用建书工具。请重试；如果仍失败，请检查模型是否支持工具调用。";
+    }
+    if (args.requestedIntent === "short_run" && !hasSuccessfulToolExec(args.collectedToolExecs, "short_fiction_run")) {
+        return "已确认生成短篇，但模型没有实际调用短篇生产工具。请重试；如果仍失败，请检查模型是否支持工具调用。";
+    }
+    if (args.requestedIntent === "play_start" && !hasSuccessfulToolExec(args.collectedToolExecs, "play_start")) {
+        return "已确认启动互动世界，但模型没有实际调用互动世界工具。请重试；如果仍失败，请检查模型是否支持工具调用。";
+    }
+    if (args.requestedIntent === "generate_cover" && !hasSuccessfulToolExec(args.collectedToolExecs, "generate_cover")) {
+        return "已确认生成封面，但模型没有实际调用封面工具。请重试；如果仍失败，请检查模型是否支持工具调用。";
     }
     return undefined;
 }
+function classifyAgentFailure(message) {
+    const text = message.trim();
+    if (!text)
+        return "unknown";
+    if (/API\s*返回|上游|upstream|Bad Gateway|temporarily unavailable|rate limit|quota|API Key|unauthorized|forbidden|无法连接到 API|fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|LLM returned empty response|Provider finish_reason|reasoning_content/i.test(text)) {
+        return "llm";
+    }
+    if (/PlannerParseError|Architect output missing|required sections|missing YAML frontmatter|frontmatter delimiters|parseMemo|Book creation artifact is incomplete|Short-hit draft is incomplete|工具执行失败|执行失败|sub_agent|tool execution|RUNTIME_STATE_DELTA|JSON parse|解析失败/i.test(text)) {
+        return "internal";
+    }
+    return "unknown";
+}
+function formatAgentFailure(message) {
+    const kind = classifyAgentFailure(message);
+    if (kind === "llm") {
+        return { code: "AGENT_LLM_ERROR", message, status: 502 };
+    }
+    if (kind === "internal") {
+        return { code: "AGENT_INTERNAL_ERROR", message: `InkOS 内部流程错误：${message}`, status: 500 };
+    }
+    return { code: "AGENT_ERROR", message, status: 500 };
+}
+class ConfirmedActionExecutionError extends Error {
+    exec;
+    constructor(message, exec, cause) {
+        super(message);
+        this.name = "ConfirmedActionExecutionError";
+        this.exec = exec;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+function suppressManualTextForTool(exec) {
+    return exec.tool === "play_start" || exec.tool === "play_step" || exec.tool === "play_revise";
+}
+function manualToolAssistantMessage(responseText, exec, provider, model) {
+    return {
+        role: "assistant",
+        content: [{ type: "text", text: suppressManualTextForTool(exec) ? "" : responseText }],
+        api: "anthropic-messages",
+        provider,
+        model,
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: "toolUse",
+        timestamp: Date.now(),
+    };
+}
+function manualToolAppendOptions(sessionKind, exec) {
+    return {
+        sessionKind,
+        legacyDisplay: { toolExecutions: [exec] },
+    };
+}
+function isConfirmedProductionAction(args) {
+    return (args.actionSource === "button" || args.actionSource === "slash")
+        && (args.requestedIntent === "create_book"
+            || args.requestedIntent === "short_run"
+            || args.requestedIntent === "play_start"
+            || args.requestedIntent === "generate_cover");
+}
+function requirePayloadText(value, message) {
+    const text = value?.trim();
+    if (!text) {
+        throw new ApiError(400, "CONFIRMED_ACTION_PAYLOAD_INCOMPLETE", message);
+    }
+    return text;
+}
+function toolResultText(result) {
+    const text = extractToolError(result).trim();
+    return text || "已完成。";
+}
+async function executeConfirmedProductionAction(args) {
+    const id = `direct-${args.requestedIntent}-${Date.now().toString(36)}`;
+    const actionPayload = args.actionPayload;
+    let tool;
+    let params;
+    let agent;
+    if (args.requestedIntent === "create_book") {
+        const payload = actionPayload?.createBook;
+        const title = requirePayloadText(payload?.title, "确认建书缺少书名，请重新生成确认卡。");
+        tool = createSubAgentTool(args.pipeline, null, args.root, { actionPayload });
+        agent = "architect";
+        params = {
+            agent,
+            instruction: args.instruction,
+            title,
+            ...(payload?.genre ? { genre: payload.genre } : {}),
+            ...(payload?.platform ? { platform: payload.platform } : {}),
+            ...(payload?.language ? { language: payload.language } : {}),
+            ...(payload?.targetChapters ? { targetChapters: payload.targetChapters } : {}),
+            ...(payload?.chapterWordCount ? { chapterWordCount: payload.chapterWordCount } : {}),
+        };
+    }
+    else if (args.requestedIntent === "short_run") {
+        const payload = actionPayload?.shortRun;
+        const direction = payload?.direction?.trim() || args.instruction.trim();
+        if (!direction)
+            throw new ApiError(400, "CONFIRMED_ACTION_PAYLOAD_INCOMPLETE", "确认短篇缺少方向，请重新生成确认卡。");
+        tool = createShortFictionRunTool(args.pipeline, args.root, { actionPayload });
+        params = {
+            direction,
+            ...(payload?.reference ? { reference: payload.reference } : {}),
+            ...(payload?.storyId ? { storyId: payload.storyId } : {}),
+            ...(payload?.chapters ? { chapters: payload.chapters } : {}),
+            ...(payload?.charsPerChapter ? { charsPerChapter: payload.charsPerChapter } : {}),
+            ...(payload?.cover !== undefined ? { cover: payload.cover } : {}),
+        };
+    }
+    else if (args.requestedIntent === "generate_cover") {
+        const payload = actionPayload?.generateCover;
+        const title = requirePayloadText(payload?.title, "确认生成封面缺少标题，请重新生成确认卡。");
+        tool = createGenerateCoverTool(args.root, { actionPayload });
+        params = {
+            title,
+            ...(payload?.intro ? { intro: payload.intro } : {}),
+            ...(payload?.sellingPoints ? { sellingPoints: payload.sellingPoints } : {}),
+            ...(payload?.coverPrompt ? { coverPrompt: payload.coverPrompt } : {}),
+            ...(payload?.outputDir ? { outputDir: payload.outputDir } : {}),
+        };
+    }
+    else if (args.requestedIntent === "play_start") {
+        const payload = actionPayload?.playStart;
+        const title = requirePayloadText(payload?.title, "确认启动互动世界缺少标题，请重新生成确认卡。");
+        const fallbackScene = [payload?.premise, args.instruction].filter((part) => typeof part === "string" && part.trim().length > 0).join("\n\n");
+        const initialScene = isUsablePlayInitialScene(payload?.initialScene)
+            ? payload?.initialScene?.trim()
+            : fallbackScene.trim();
+        const confirmedActionPayload = actionPayload
+            ? {
+                ...actionPayload,
+                playStart: {
+                    ...payload,
+                    title,
+                    ...(initialScene ? { initialScene } : {}),
+                },
+            }
+            : undefined;
+        tool = createPlayStartTool(args.pipeline, args.root, args.sessionId, args.playMode, { actionPayload: confirmedActionPayload });
+        params = {
+            title,
+            ...(payload?.premise ? { premise: payload.premise } : {}),
+            ...(payload?.worldContract ? { worldContract: payload.worldContract } : {}),
+            ...(payload?.visualContract ? { visualContract: payload.visualContract } : {}),
+            ...(payload?.mode ? { mode: payload.mode } : {}),
+            ...(initialScene ? { initialScene } : {}),
+            ...(payload?.suggestedActions ? { suggestedActions: payload.suggestedActions } : {}),
+        };
+    }
+    else {
+        throw new ApiError(400, "UNSUPPORTED_CONFIRMED_ACTION", `Unsupported confirmed action: ${args.requestedIntent}`);
+    }
+    const exec = {
+        id,
+        tool: tool.name,
+        agent,
+        label: resolveToolLabel(tool.name, agent),
+        status: "running",
+        args: params,
+        stages: agent ? PIPELINE_STAGES[agent]?.map(label => ({ label, status: "pending" })) : undefined,
+        startedAt: Date.now(),
+    };
+    broadcast("tool:start", {
+        sessionId: args.streamSessionId,
+        id,
+        tool: tool.name,
+        args: params,
+        stages: exec.stages?.map(stage => stage.label),
+    });
+    try {
+        const result = await tool.execute(id, params, undefined, (partialResult) => {
+            broadcast("tool:update", {
+                sessionId: args.streamSessionId,
+                tool: tool.name,
+                partialResult,
+            });
+        });
+        exec.status = "completed";
+        exec.completedAt = Date.now();
+        exec.result = toolResultText(result);
+        exec.details = result?.details;
+        exec.stages = exec.stages?.map(stage => ({ ...stage, status: "completed" }));
+        broadcast("tool:end", {
+            sessionId: args.streamSessionId,
+            id,
+            tool: tool.name,
+            result,
+            details: exec.details,
+            isError: false,
+        });
+        return exec;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const result = { content: [{ type: "text", text: message }] };
+        exec.status = "error";
+        exec.completedAt = Date.now();
+        exec.error = message;
+        broadcast("tool:end", {
+            sessionId: args.streamSessionId,
+            id,
+            tool: tool.name,
+            result,
+            isError: true,
+        });
+        throw new ConfirmedActionExecutionError(message, exec, error);
+    }
+}
 const subscribers = new Set();
 const bookCreateStatus = new Map();
 // 内存缓存：service -> 模型列表 + 更新时间戳；避免每次 sidebar 挂载时都打真实 LLM /models
@@ -381,6 +677,16 @@ function deriveBookIdFromTitle(title) {
         .replace(/^-+|-+$/g, "")
         .slice(0, 30);
 }
+async function completeBookExists(bookDir) {
+    try {
+        await access(join(bookDir, "book.json"));
+        await access(join(bookDir, "story", "story_bible.md"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function resolveArchitectBookIdFromArgs(args) {
     if (!args || args.agent !== "architect" || args.revise === true)
         return null;
@@ -400,9 +706,12 @@ function resolveCreatedBookIdFromToolExecs(execs) {
         if (details?.kind === "book_created" && typeof details.bookId === "string" && details.bookId.trim()) {
             return details.bookId.trim();
         }
-        const fromArgs = resolveArchitectBookIdFromArgs(exec.args);
-        if (fromArgs)
-            return fromArgs;
+    }
+    return null;
+}
+function resolveCreatedBookIdFromDetails(details) {
+    if (details?.kind === "book_created" && typeof details.bookId === "string" && details.bookId.trim()) {
+        return details.bookId.trim();
     }
     return null;
 }
@@ -519,7 +828,24 @@ async function loadRawConfig(root) {
 async function saveRawConfig(root, config) {
     await writeFile(join(root, "inkos.json"), JSON.stringify(config, null, 2), "utf-8");
 }
-async function readEnvConfigSummary(path) {
+function unquoteEnvValue(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function toEnvConfigSummary(values) {
+    return {
+        detected: values.detected,
+        provider: values.provider,
+        service: values.service ?? null,
+        baseUrl: values.baseUrl,
+        model: values.model,
+        hasApiKey: values.hasApiKey,
+    };
+}
+async function readEnvConfigValues(path) {
     try {
         const raw = await readFile(path, "utf-8");
         const values = new Map();
@@ -531,41 +857,55 @@ async function readEnvConfigSummary(path) {
             if (!match)
                 continue;
             const [, key, value] = match;
-            values.set(key, value.trim());
+            values.set(key, unquoteEnvValue(value));
         }
         const provider = values.get("INKOS_LLM_PROVIDER") ?? null;
+        const service = values.get("INKOS_LLM_SERVICE") ?? null;
         const baseUrl = values.get("INKOS_LLM_BASE_URL") ?? null;
         const model = values.get("INKOS_LLM_MODEL") ?? null;
         const apiKey = values.get("INKOS_LLM_API_KEY") ?? "";
-        const detected = Boolean(provider || baseUrl || model || apiKey);
+        const detected = Boolean(provider || service || baseUrl || model || apiKey);
         return {
             detected,
             provider,
+            service,
             baseUrl,
             model,
             hasApiKey: apiKey.length > 0,
+            apiKey: apiKey.length > 0 ? apiKey : null,
         };
     }
     catch {
         return {
             detected: false,
             provider: null,
+            service: null,
             baseUrl: null,
             model: null,
             hasApiKey: false,
+            apiKey: null,
         };
     }
 }
 async function readEnvConfigStatus(root) {
-    const project = await readEnvConfigSummary(join(root, ".env"));
-    const global = await readEnvConfigSummary(GLOBAL_ENV_PATH);
+    const project = await readEnvConfigValues(join(root, ".env"));
+    const global = await readEnvConfigValues(GLOBAL_ENV_PATH);
     return {
-        project,
-        global,
+        project: toEnvConfigSummary(project),
+        global: toEnvConfigSummary(global),
         effectiveSource: project.detected ? "project" : global.detected ? "global" : null,
         runtimeUsesEnv: false,
     };
 }
+async function readEffectiveEnvConfigValues(root) {
+    const project = await readEnvConfigValues(join(root, ".env"));
+    if (project.detected)
+        return { source: "project", values: project };
+    const global = await readEnvConfigValues(GLOBAL_ENV_PATH);
+    if (global.detected)
+        return { source: "global", values: global };
+    return null;
+}
 async function resolveConfiguredServiceBaseUrl(root, serviceId, inlineBaseUrl) {
     if (inlineBaseUrl?.trim())
         return inlineBaseUrl.trim();
@@ -917,7 +1257,11 @@ async function probeServiceCapabilities(args) {
                 stream: plan.stream,
             });
             try {
-                await withTimeout(chatCompletion(client, model, [{ role: "user", content: "Reply with OK only." }], { maxTokens: 16 }), SERVICE_CHAT_PROBE_TIMEOUT_MS, "service connection test");
+                await withTimeout(
+                // A connectivity probe wants a fast pass/fail — never the transient
+                // retry+backoff, which would multiply the time when the upstream is
+                // rate-limiting (and make the diagnostics page hang).
+                chatCompletion(client, model, [{ role: "user", content: "Reply with OK only." }], { maxTokens: 16, retry: false }), SERVICE_CHAT_PROBE_TIMEOUT_MS, "service connection test");
                 const models = discoveredModels.length > 0
                     ? discoveredModels
                     : fallbackTextModelsForEndpoint(endpoint, preset);
@@ -1028,9 +1372,16 @@ export function createStudioServer(initialConfig, root) {
             defaultLLMConfig: currentConfig.llm,
             foundationReviewRetries: currentConfig.foundation?.reviewRetries ?? 2,
             writingReviewRetries: currentConfig.writing?.reviewRetries ?? 1,
+            chapterReviewMode: currentConfig.writing?.reviewMode === "manual" ? "manual" : "auto",
             modelOverrides: currentConfig.modelOverrides,
             notifyChannels: currentConfig.notify,
             logger,
+            onContextCompression: (event) => {
+                broadcast("context:compression", {
+                    ...(overrides?.sessionIdForSSE ? { sessionId: overrides.sessionIdForSSE } : {}),
+                    ...event,
+                });
+            },
             onStreamProgress: (progress) => {
                 broadcast("llm:progress", {
                     ...(overrides?.sessionIdForSSE ? { sessionId: overrides.sessionIdForSSE } : {}),
@@ -1083,13 +1434,11 @@ export function createStudioServer(initialConfig, root) {
         const bookConfig = buildStudioBookConfig(body, now);
         const bookId = bookConfig.id;
         const bookDir = state.bookDir(bookId);
-        try {
-            await access(join(bookDir, "book.json"));
-            await access(join(bookDir, "story", "story_bible.md"));
-            return c.json({ error: `Book "${bookId}" already exists` }, 409);
+        if (!bookId) {
+            return c.json({ error: "Could not derive a valid book id from title" }, 400);
         }
-        catch {
-            // The target book is not fully initialized yet, so creation can continue.
+        if (await completeBookExists(bookDir)) {
+            return c.json({ error: `Book "${bookId}" already exists` }, 409);
         }
         broadcast("book:creating", { bookId, title: body.title });
         bookCreateStatus.set(bookId, { status: "creating" });
@@ -1109,7 +1458,19 @@ export function createStudioServer(initialConfig, root) {
             },
             tools,
         }).then(async (result) => {
-            const createdBookId = result.details?.bookId ?? result.session.activeBookId ?? bookId;
+            const createdBookId = resolveCreatedBookIdFromDetails(result.details);
+            if (!createdBookId) {
+                const error = "Book creation did not produce a completed book artifact.";
+                bookCreateStatus.set(bookId, { status: "error", error });
+                broadcast("book:error", { bookId, error });
+                return;
+            }
+            if (!await completeBookExists(join(root, "books", createdBookId))) {
+                const error = "Book creation artifact is incomplete on disk.";
+                bookCreateStatus.set(createdBookId, { status: "error", error });
+                broadcast("book:error", { bookId: createdBookId, error });
+                return;
+            }
             const book = await loadStudioBookListSummary(state, createdBookId).catch(() => undefined);
             bookCreateStatus.delete(createdBookId);
             broadcast("book:created", { bookId: createdBookId, ...(book ? { book } : {}) });
@@ -1123,10 +1484,18 @@ export function createStudioServer(initialConfig, root) {
     app.get("/api/v1/books/:id/create-status", async (c) => {
         const id = c.req.param("id");
         const status = bookCreateStatus.get(id);
-        if (!status) {
-            return c.json({ status: "missing" }, 404);
+        if (status) {
+            return c.json(status);
         }
-        return c.json(status);
+        // No in-memory entry. On success the entry is deleted, and a long architect
+        // run (or a server restart) can also drop it — so a bare 404 is ambiguous
+        // ("done" vs "never existed"). Check disk: if the foundation is fully
+        // written, the book really is ready; report that truthfully.
+        const { isBookFoundationComplete } = await import("@actalk/inkos-core");
+        if (await isBookFoundationComplete(state.bookDir(id))) {
+            return c.json({ status: "ready" });
+        }
+        return c.json({ status: "missing" }, 404);
     });
     // --- Chapters ---
     app.get("/api/v1/books/:id/chapters/:num", async (c) => {
@@ -1199,10 +1568,12 @@ export function createStudioServer(initialConfig, root) {
     // GET handler tags them with `legacy: true` so the UI can surface that the
     // edits won't land where the user expects.
     const LEGACY_SHIM_FILES = new Set(["story_bible.md", "book_rules.md"]);
+    const RUNTIME_DIAGNOSTIC_FILE_RE = /^runtime\/chapter-\d{4}\.(?:intent\.md|plan\.md|context\.json|rule-stack\.yaml|trace\.json)$/;
     /**
      * Validate a requested truth-file path:
      *   1. Must be one of the declared flat files, an outline/* allow-listed
-     *      entry, or a roles/**\/*.md file under 主要角色/ | 次要角色/.
+     *      entry, a runtime chapter trace file, or a roles/**\/*.md file under
+     *      主要角色/ | 次要角色/.
      *   2. Must resolve to a path inside bookDir/story/ (no `..`, no absolute
      *      paths, no traversal via the tier-name segment).
      */
@@ -1217,6 +1588,7 @@ export function createStudioServer(initialConfig, root) {
         // both — Studio used to drop English books to read-only.
         const allowed = TRUTH_FLAT_FILES.includes(file)
             || TRUTH_OUTLINE_FILES.includes(file)
+            || RUNTIME_DIAGNOSTIC_FILE_RE.test(file)
             || /^roles\/(主要角色|次要角色|major|minor)\/[^/]+\.md$/.test(file);
         if (!allowed)
             return null;
@@ -1252,14 +1624,34 @@ export function createStudioServer(initialConfig, root) {
         // can warn users their edits won't reach the runtime.
         // Hotfix: only tag as legacy when the book actually HAS the new layout.
         // Pre-Phase-5 books use story_bible/book_rules as the authoritative source.
-        const { isNewLayoutBook } = await import("@actalk/inkos-core");
+        const { isNewLayoutBook, tryParseBookRulesFrontmatter } = await import("@actalk/inkos-core");
         const legacy = LEGACY_SHIM_FILES.has(file) && await isNewLayoutBook(bookDir);
         try {
             const content = await readFile(resolved, "utf-8");
-            return c.json({ file, content, ...(legacy ? { legacy: true } : {}) });
+            // Files like outline/story_frame.md carry a YAML frontmatter block of
+            // structured fields (protagonist / genreLock / prohibitions / ...). Parse
+            // it here so the UI can render those as friendly cards instead of dumping
+            // raw YAML at the reader. `content` stays raw so the editor round-trips it
+            // unchanged; `body` is the prose with the frontmatter stripped.
+            const parsed = tryParseBookRulesFrontmatter(content);
+            const structured = parsed ? { frontmatter: parsed.rules, body: parsed.body } : {};
+            const runtimeDiagnostic = RUNTIME_DIAGNOSTIC_FILE_RE.test(file);
+            return c.json({
+                file,
+                content,
+                ...structured,
+                ...(legacy ? { legacy: true } : {}),
+                ...(runtimeDiagnostic ? { readonly: true, readonlyReason: "runtime-diagnostic" } : {}),
+            });
         }
         catch {
-            return c.json({ file, content: null, ...(legacy ? { legacy: true } : {}) });
+            const runtimeDiagnostic = RUNTIME_DIAGNOSTIC_FILE_RE.test(file);
+            return c.json({
+                file,
+                content: null,
+                ...(legacy ? { legacy: true } : {}),
+                ...(runtimeDiagnostic ? { readonly: true, readonlyReason: "runtime-diagnostic" } : {}),
+            });
         }
     });
     // --- Analytics ---
@@ -1299,6 +1691,87 @@ export function createStudioServer(initialConfig, root) {
         });
         return c.json({ status: "drafting", bookId: id });
     });
+    app.get("/api/v1/books/:id/eval", async (c) => {
+        const id = c.req.param("id");
+        const chapters = c.req.query("chapters");
+        try {
+            return c.json(await evaluateBookQuality({ state, bookId: id, chapters }));
+        }
+        catch (e) {
+            return c.json({ error: String(e) }, 500);
+        }
+    });
+    app.post("/api/v1/books/:id/consolidate", async (c) => {
+        const id = c.req.param("id");
+        try {
+            const pipelineConfig = await buildPipelineConfig();
+            const consolidator = new ConsolidatorAgent({
+                client: pipelineConfig.client,
+                model: pipelineConfig.model,
+                projectRoot: root,
+            });
+            const result = await consolidator.consolidate(state.bookDir(id));
+            broadcast("consolidate:complete", { bookId: id, ...result });
+            return c.json(result);
+        }
+        catch (e) {
+            broadcast("consolidate:error", { bookId: id, error: String(e) });
+            return c.json({ error: String(e) }, 500);
+        }
+    });
+    app.post("/api/v1/books/:id/plan", async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json().catch(() => ({ context: undefined }));
+        try {
+            const pipeline = new PipelineRunner(await buildPipelineConfig());
+            return c.json(await pipeline.planChapter(id, body.context));
+        }
+        catch (e) {
+            return c.json({ error: String(e) }, 500);
+        }
+    });
+    app.post("/api/v1/books/:id/compose", async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json().catch(() => ({ context: undefined }));
+        try {
+            const pipeline = new PipelineRunner(await buildPipelineConfig());
+            return c.json(await pipeline.composeChapter(id, body.context));
+        }
+        catch (e) {
+            return c.json({ error: String(e) }, 500);
+        }
+    });
+    app.post("/api/v1/books/:id/repair-state/:chapter", async (c) => {
+        const id = c.req.param("id");
+        const chapterNum = parseInt(c.req.param("chapter"), 10);
+        try {
+            const pipeline = new PipelineRunner(await buildPipelineConfig());
+            const result = await pipeline.repairChapterState(id, chapterNum);
+            broadcast("repair-state:complete", { bookId: id, chapter: chapterNum });
+            return c.json(result);
+        }
+        catch (e) {
+            broadcast("repair-state:error", { bookId: id, chapter: chapterNum, error: String(e) });
+            return c.json({ error: String(e) }, 500);
+        }
+    });
+    app.post("/api/v1/books/:id/foundation/revise", async (c) => {
+        const id = c.req.param("id");
+        const { feedback } = await c.req.json().catch(() => ({ feedback: undefined }));
+        if (!feedback?.trim()) {
+            return c.json({ error: "feedback is required" }, 400);
+        }
+        try {
+            const pipeline = new PipelineRunner(await buildPipelineConfig());
+            await pipeline.reviseFoundation(id, feedback.trim());
+            broadcast("foundation:revised", { bookId: id });
+            return c.json({ ok: true });
+        }
+        catch (e) {
+            broadcast("foundation:error", { bookId: id, error: String(e) });
+            return c.json({ error: String(e) }, 500);
+        }
+    });
     app.post("/api/v1/books/:id/chapters/:num/approve", async (c) => {
         const id = c.req.param("id");
         const num = parseInt(c.req.param("num"), 10);
@@ -1398,6 +1871,45 @@ export function createStudioServer(initialConfig, root) {
             envConfig,
         });
     });
+    app.post("/api/v1/services/config/import-env", async (c) => {
+        const env = await readEffectiveEnvConfigValues(root);
+        if (!env || !env.values.apiKey) {
+            return c.json({
+                error: "未检测到可导入的 LLM 环境变量配置，或缺少 INKOS_LLM_API_KEY。",
+            }, 400);
+        }
+        const config = await loadRawConfig(root);
+        config.llm = config.llm ?? {};
+        const llm = config.llm;
+        const existingServices = normalizeServiceConfig(llm.services);
+        const explicitService = env.values.service?.trim();
+        const guessedService = env.values.baseUrl ? guessServiceFromBaseUrl(env.values.baseUrl) : null;
+        const service = explicitService || guessedService || "custom";
+        const entry = service === "custom"
+            ? {
+                service: "custom",
+                name: "Env LLM",
+                ...(env.values.baseUrl ? { baseUrl: env.values.baseUrl } : {}),
+            }
+            : { service };
+        const serviceKey = serviceConfigKey(entry);
+        llm.services = mergeServiceConfig(existingServices, [entry]);
+        llm.service = serviceKey;
+        llm.configSource = "studio";
+        if (env.values.model)
+            llm.defaultModel = env.values.model;
+        syncTopLevelLlmMirror(llm);
+        const secrets = await loadSecrets(root);
+        secrets.services[serviceKey] = { apiKey: env.values.apiKey };
+        await saveSecrets(root, secrets);
+        await saveRawConfig(root, config);
+        return c.json({
+            ok: true,
+            source: env.source,
+            service: serviceKey,
+            defaultModel: env.values.model ?? null,
+        });
+    });
     app.put("/api/v1/services/config", async (c) => {
         const body = await c.req.json();
         const config = await loadRawConfig(root);
@@ -1431,16 +1943,24 @@ export function createStudioServer(initialConfig, root) {
         const llm = config.llm ?? {};
         const cover = normalizeCoverConfig(llm.cover);
         const secrets = await loadSecrets(root);
+        const keyFor = (service) => Boolean(secrets.services[coverSecretKey(service)]?.apiKey || secrets.services[service]?.apiKey);
+        // "Configured" = a cover service is selected AND has a key, OR a cover
+        // endpoint is provided via env (the CLI/power-user path). This is the gate
+        // for the Play auto-illustration toggles.
+        const envConfigured = Boolean((process.env.INKOS_COVER_BASE_URL || process.env.INKOS_COVER_ENDPOINT)
+            && (process.env.INKOS_COVER_API_KEY || keyFor("kkaiapi")));
+        const configured = Boolean(cover?.service && keyFor(cover.service)) || envConfigured;
         return c.json({
             service: cover?.service ?? null,
             model: cover?.model ?? null,
+            configured,
             providers: COVER_PROVIDER_PRESETS.map((provider) => ({
                 service: provider.service,
                 label: provider.label,
                 baseUrl: provider.baseUrl,
                 defaultModel: provider.defaultModel,
                 models: provider.models,
-                connected: Boolean(secrets.services[coverSecretKey(provider.service)]?.apiKey || secrets.services[provider.service]?.apiKey),
+                connected: keyFor(provider.service),
             })),
         });
     });
@@ -1732,6 +2252,45 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 500);
         }
     });
+    app.get("/api/v1/project/input-governance-mode", async (c) => {
+        const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
+        return c.json({ mode: raw.inputGovernanceMode === "legacy" ? "legacy" : "v2" });
+    });
+    app.put("/api/v1/project/input-governance-mode", async (c) => {
+        const { mode } = await c.req.json();
+        const parsed = InputGovernanceModeSchema.safeParse(mode);
+        if (!parsed.success) {
+            return c.json({ error: "mode must be legacy or v2" }, 400);
+        }
+        const configPath = join(root, "inkos.json");
+        const raw = JSON.parse(await readFile(configPath, "utf-8"));
+        raw.inputGovernanceMode = parsed.data;
+        const { writeFile: writeFileFs } = await import("node:fs/promises");
+        await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
+        return c.json({ ok: true, mode: parsed.data });
+    });
+    app.get("/api/v1/project/detection", async (c) => {
+        const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
+        return c.json({ detection: raw.detection ?? null });
+    });
+    app.put("/api/v1/project/detection", async (c) => {
+        const { detection } = await c.req.json();
+        const configPath = join(root, "inkos.json");
+        const raw = JSON.parse(await readFile(configPath, "utf-8"));
+        if (detection === null) {
+            delete raw.detection;
+        }
+        else {
+            const parsed = DetectionConfigSchema.safeParse(detection);
+            if (!parsed.success) {
+                return c.json({ error: parsed.error.issues.map((issue) => issue.message).join("; ") }, 400);
+            }
+            raw.detection = parsed.data;
+        }
+        const { writeFile: writeFileFs } = await import("node:fs/promises");
+        await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
+        return c.json({ ok: true, detection: raw.detection ?? null });
+    });
     // --- Truth files browser ---
     app.get("/api/v1/books/:id/truth", async (c) => {
         const id = c.req.param("id");
@@ -1740,7 +2299,7 @@ export function createStudioServer(initialConfig, root) {
         async function listDir(subdir) {
             try {
                 const entries = await readdir(join(storyDir, subdir));
-                return entries.filter((f) => f.endsWith(".md") || f.endsWith(".json"));
+                return entries.filter((f) => f.endsWith(".md") || f.endsWith(".json") || f.endsWith(".yaml"));
             }
             catch {
                 return [];
@@ -1753,9 +2312,12 @@ export function createStudioServer(initialConfig, root) {
             try {
                 const content = await readFile(join(storyDir, relPath), "utf-8");
                 const isShim = LEGACY_SHIM_FILES.has(relPath) && newLayout;
+                const isRuntimeDiagnostic = RUNTIME_DIAGNOSTIC_FILE_RE.test(relPath);
                 const entry = isShim
                     ? { name: relPath, size: content.length, preview: content.slice(0, 200), legacy: true }
-                    : { name: relPath, size: content.length, preview: content.slice(0, 200) };
+                    : isRuntimeDiagnostic
+                        ? { name: relPath, size: content.length, preview: content.slice(0, 200), readonly: true, readonlyReason: "runtime-diagnostic" }
+                        : { name: relPath, size: content.length, preview: content.slice(0, 200) };
                 return entry;
             }
             catch {
@@ -1773,6 +2335,9 @@ export function createStudioServer(initialConfig, root) {
             const minorRolesZh = (await listDir("roles/次要角色")).map((f) => `roles/次要角色/${f}`);
             const majorRolesEn = (await listDir("roles/major")).map((f) => `roles/major/${f}`);
             const minorRolesEn = (await listDir("roles/minor")).map((f) => `roles/minor/${f}`);
+            const runtimeFiles = (await listDir("runtime"))
+                .map((f) => `runtime/${f}`)
+                .filter((f) => RUNTIME_DIAGNOSTIC_FILE_RE.test(f));
             const all = [
                 ...flatFiles,
                 ...outlineFiles,
@@ -1780,6 +2345,7 @@ export function createStudioServer(initialConfig, root) {
                 ...minorRolesZh,
                 ...majorRolesEn,
                 ...minorRolesEn,
+                ...runtimeFiles,
             ];
             const described = await Promise.all(all.map(describe));
             const result = described.filter((x) => x !== null);
@@ -1875,6 +2441,142 @@ export function createStudioServer(initialConfig, root) {
             activeBookId,
         });
     });
+    // Play worlds are created and advanced by the play_start / play_step agent
+    // tools (worldId === sessionId). The HUD only needs to read a run's state,
+    // so just the run-detail endpoint remains; the old save-slot list/create
+    // endpoints were only used by the removed standalone play page.
+    app.get("/api/v1/play/runs/:worldId/:runId", async (c) => {
+        const worldId = normalizeApiBookId(c.req.param("worldId"), "worldId") ?? "default-world";
+        const runId = normalizeApiBookId(c.req.param("runId"), "runId") ?? "default-run";
+        const store = new PlayStore(root);
+        const db = createPlayDB(store.runDir(worldId, runId));
+        const [transcript, currentState, world] = await Promise.all([
+            store.readTranscript(worldId, runId),
+            store.loadCurrentState(worldId, runId).catch(() => null),
+            store.loadWorld(worldId).catch(() => null),
+        ]);
+        const graph = db.snapshot();
+        db.close?.();
+        // Merge generated illustrations (decoupled sidecar) onto entities so the
+        // HUD can render portraits/stills without touching the event-sourced graph.
+        const runDir = store.runDir(worldId, runId);
+        const [manifest, imageSettings] = await Promise.all([
+            readPlayImageManifest(runDir),
+            readPlayImageSettings(runDir),
+        ]);
+        const imageUrlFor = (file) => file ? `/api/v1/play/runs/${encodeURIComponent(worldId)}/${encodeURIComponent(runId)}/images/${encodeURIComponent(file)}` : undefined;
+        const sceneImageUrls = Object.fromEntries(Object.entries(manifest)
+            .filter(([key, entry]) => key.startsWith("scene-turn-") && entry.status === "ready" && entry.file)
+            .map(([key, entry]) => [key, imageUrlFor(entry.file)]));
+        const entitiesWithImages = (graph.entities ?? []).map((entity) => {
+            const entry = manifest[entity.id];
+            return entry?.status === "ready" && entry.file
+                ? { ...entity, imageUrl: imageUrlFor(entry.file) }
+                : entity;
+        });
+        // Illustration of the current moment, if one was generated for this turn.
+        const sceneTurn = currentState?.turn ?? 0;
+        const sceneEntry = manifest[`scene-turn-${sceneTurn}`];
+        const sceneImageUrl = sceneEntry?.status === "ready" ? imageUrlFor(sceneEntry.file) : undefined;
+        return c.json({
+            worldId,
+            runId,
+            title: world?.title ?? null,
+            transcript,
+            currentState,
+            graph: { ...graph, entities: entitiesWithImages },
+            imageSettings,
+            sceneImageUrls,
+            ...(sceneImageUrl ? { sceneImageUrl } : {}),
+        });
+    });
+    // --- Interactive-world illustration (Play auto-config images) ---
+    app.put("/api/v1/play/runs/:worldId/:runId/image-settings", async (c) => {
+        const worldId = normalizeApiBookId(c.req.param("worldId"), "worldId") ?? "default-world";
+        const runId = normalizeApiBookId(c.req.param("runId"), "runId") ?? "default-run";
+        const body = await c.req.json().catch(() => ({}));
+        const settings = {
+            actors: Boolean(body.actors),
+            moments: Boolean(body.moments),
+            inventory: Boolean(body.inventory),
+        };
+        const runDir = new PlayStore(root).runDir(worldId, runId);
+        await writePlayImageSettings(runDir, settings);
+        return c.json({ ok: true, imageSettings: settings });
+    });
+    app.post("/api/v1/play/runs/:worldId/:runId/generate-image", async (c) => {
+        const worldId = normalizeApiBookId(c.req.param("worldId"), "worldId") ?? "default-world";
+        const runId = normalizeApiBookId(c.req.param("runId"), "runId") ?? "default-run";
+        const body = await c.req.json().catch(() => ({ target: "entity" }));
+        const store = new PlayStore(root);
+        const runDir = store.runDir(worldId, runId);
+        const [world, currentState] = await Promise.all([
+            store.loadWorld(worldId).catch(() => null),
+            store.loadCurrentState(worldId, runId).catch(() => null),
+        ]);
+        const worldContext = world
+            ? {
+                premise: world.premise,
+                worldContract: world.worldContract,
+                visualContract: world.visualContract,
+            }
+            : undefined;
+        let key;
+        let prompt;
+        if (body.target === "scene") {
+            // The current moment defaults to the rendered scene projection so the UI
+            // can offer a one-tap "illustrate this moment" without re-sending prose.
+            const sceneText = ((body.sceneText ?? "").trim()
+                || (await store.readProjection(worldId, runId, "projections/scene.md").catch(() => "")).trim());
+            if (!sceneText)
+                return c.json({ error: "no current scene to illustrate" }, 400);
+            key = body.sceneKey?.trim() || `scene-turn-${currentState?.turn ?? 0}`;
+            prompt = buildPlaySceneImagePrompt(sceneText, worldContext);
+        }
+        else {
+            const entityId = body.entityId?.trim();
+            if (!entityId)
+                return c.json({ error: "entityId is required for an entity image" }, 400);
+            const db = createPlayDB(runDir);
+            const graph = db.snapshot();
+            db.close?.();
+            const entity = (graph.entities ?? []).find((e) => e.id === entityId);
+            if (!entity)
+                return c.json({ error: `entity not found: ${entityId}` }, 404);
+            key = entity.id;
+            prompt = buildPlayEntityImagePrompt(entity, worldContext);
+        }
+        try {
+            const entry = await generatePlayImage({ root, runDir, key, prompt });
+            const url = entry.status === "ready" && entry.file
+                ? `/api/v1/play/runs/${encodeURIComponent(worldId)}/${encodeURIComponent(runId)}/images/${encodeURIComponent(entry.file)}`
+                : undefined;
+            return c.json({ key, ok: entry.status === "ready", ...entry, ...(url ? { url } : {}) });
+        }
+        catch (e) {
+            // Resolution failure = cover API not configured.
+            return c.json({ error: e instanceof Error ? e.message : String(e), needsCoverConfig: true }, 400);
+        }
+    });
+    app.get("/api/v1/play/runs/:worldId/:runId/images/:file", async (c) => {
+        const worldId = normalizeApiBookId(c.req.param("worldId"), "worldId") ?? "default-world";
+        const runId = normalizeApiBookId(c.req.param("runId"), "runId") ?? "default-run";
+        const file = c.req.param("file");
+        if (!file || file.includes("/") || file.includes("..") || file.includes("\0")) {
+            return c.json({ error: "Invalid image file" }, 400);
+        }
+        const runDir = new PlayStore(root).runDir(worldId, runId);
+        try {
+            const { readFile: readFileFs } = await import("node:fs/promises");
+            const content = await readFileFs(join(runDir, "images", file));
+            const ext = file.split(".").pop()?.toLowerCase() ?? "";
+            const contentType = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+            return new Response(content, { headers: { "Content-Type": contentType } });
+        }
+        catch {
+            return c.notFound();
+        }
+    });
     // -- Per-book session endpoints --
     app.get("/api/v1/sessions", async (c) => {
         const bookId = c.req.query("bookId");
@@ -1890,10 +2592,24 @@ export function createStudioServer(initialConfig, root) {
     app.post("/api/v1/sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
         const bookId = normalizeApiBookId(body.bookId, "bookId");
+        const sessionKind = normalizeStudioSessionKind(body.sessionKind, bookId ? "book" : "chat");
+        const playMode = normalizeStudioPlayMode(body.playMode);
         const sessionId = body.sessionId;
         // sessionId 只允许 timestamp-random 格式；防止注入任意文件名
         const safeSessionId = sessionId && /^[0-9]+-[a-z0-9]+$/.test(sessionId) ? sessionId : undefined;
-        const session = await createAndPersistBookSession(root, bookId, safeSessionId);
+        const session = await createAndPersistBookSession(root, bookId, safeSessionId, sessionKind, ...(playMode ? [{ playMode }] : []));
+        return c.json({ session });
+    });
+    app.put("/api/v1/sessions/:sessionId/play-mode", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        const playMode = normalizeStudioPlayMode(body.playMode);
+        if (!playMode) {
+            throw new ApiError(400, "INVALID_PLAY_MODE", "playMode is required");
+        }
+        const existing = await loadBookSession(root, c.req.param("sessionId"));
+        if (!existing)
+            return c.json({ error: "Session not found" }, 404);
+        const session = await createAndPersistBookSession(root, existing.bookId, existing.sessionId, existing.sessionKind, { playMode });
         return c.json({ session });
     });
     app.put("/api/v1/sessions/:sessionId", async (c) => {
@@ -1914,7 +2630,7 @@ export function createStudioServer(initialConfig, root) {
         return c.json({ ok: true });
     });
     app.post("/api/v1/agent", async (c) => {
-        const { instruction, activeBookId, sessionId: reqSessionId, model: reqModel, service: reqService } = await c.req.json();
+        const { instruction, activeBookId, sessionId: reqSessionId, sessionKind: reqSessionKind, actionSource: reqActionSource, requestedIntent: reqRequestedIntent, actionPayload: reqActionPayload, playMode: reqPlayMode, model: reqModel, service: reqService, } = await c.req.json();
         const sessionId = reqSessionId;
         if (!instruction?.trim()) {
             return c.json({ error: "No instruction provided" }, 400);
@@ -1926,7 +2642,11 @@ export function createStudioServer(initialConfig, root) {
             const message = nonTextModelMessage(reqModel);
             return c.json({ error: message, response: message }, 400);
         }
-        broadcast("agent:start", { instruction, activeBookId, sessionId });
+        const actionSource = normalizeStudioActionSource(reqActionSource);
+        const requestedIntent = normalizeStudioRequestedIntent(reqRequestedIntent);
+        const actionPayload = normalizeStudioActionPayload(reqActionPayload);
+        const playMode = normalizeStudioPlayMode(reqPlayMode);
+        broadcast("agent:start", { instruction, activeBookId, sessionId, actionSource, requestedIntent });
         try {
             // Load config + create LLM client (pipeline created after model resolution)
             const config = await loadCurrentProjectConfig({ requireApiKey: false });
@@ -1944,9 +2664,15 @@ export function createStudioServer(initialConfig, root) {
                 throw new ApiError(409, "SESSION_BOOK_MISMATCH", `Session ${bookSession.sessionId} is bound to ${persistedBookId}, not ${requestedActiveBookId}`);
             }
             const agentBookId = requestedActiveBookId ?? persistedBookId;
+            const sessionKind = normalizeStudioSessionKind(reqSessionKind, bookSession.sessionKind ?? (agentBookId ? "book" : "chat"));
+            if (bookSession.sessionKind !== sessionKind || (playMode && bookSession.playMode !== playMode)) {
+                const updatedSession = await createAndPersistBookSession(root, bookSession.bookId, bookSession.sessionId, sessionKind, ...(playMode ? [{ playMode }] : []));
+                bookSession = updatedSession;
+            }
+            let activeBookConfig = null;
             if (agentBookId) {
                 try {
-                    await state.loadBookConfig(agentBookId);
+                    activeBookConfig = await state.loadBookConfig(agentBookId);
                 }
                 catch {
                     throw new ApiError(404, "BOOK_NOT_FOUND", `Book not found: ${agentBookId}`);
@@ -1965,12 +2691,14 @@ export function createStudioServer(initialConfig, root) {
                     sessionTitleBroadcasted = true;
                 }
             };
-            const externalEdit = await tryHandleExternalChatEdit({
-                root,
-                state,
-                instruction,
-                activeBookId: agentBookId,
-            });
+            const externalEdit = requestedIntent === "edit_artifact" || sessionKind === "edit"
+                ? await tryHandleExternalChatEdit({
+                    root,
+                    state,
+                    instruction,
+                    activeBookId: agentBookId,
+                })
+                : null;
             if (externalEdit) {
                 await appendManualSessionMessages(root, bookSession.sessionId, [{
                         role: "assistant",
@@ -1988,13 +2716,14 @@ export function createStudioServer(initialConfig, root) {
                         },
                         stopReason: "stop",
                         timestamp: Date.now(),
-                    }], instruction);
+                    }], instruction, { sessionKind });
                 await refreshBookSessionFromTranscript();
-                broadcast("agent:complete", { instruction, activeBookId: externalEdit.activeBookId, sessionId: bookSession.sessionId });
+                broadcast("agent:complete", { instruction, activeBookId: externalEdit.activeBookId, sessionId: bookSession.sessionId, sessionKind });
                 return c.json({
                     response: externalEdit.responseText,
                     session: {
                         sessionId: bookSession.sessionId,
+                        sessionKind,
                         ...(externalEdit.activeBookId ? { activeBookId: externalEdit.activeBookId } : {}),
                     },
                 });
@@ -2086,9 +2815,94 @@ export function createStudioServer(initialConfig, root) {
                 currentConfig: config,
                 sessionIdForSSE: bookSession.sessionId,
             }));
-            if (agentBookId && isWriteNextInstruction(instruction)) {
+            if (requestedIntent && isConfirmedProductionAction({ actionSource, requestedIntent })) {
+                const pendingBookId = requestedIntent === "create_book" && actionPayload?.createBook?.title
+                    ? deriveBookIdFromTitle(actionPayload.createBook.title)
+                    : null;
+                if (pendingBookId) {
+                    bookCreateStatus.set(pendingBookId, { status: "creating" });
+                    broadcast("book:creating", {
+                        bookId: pendingBookId,
+                        title: actionPayload?.createBook?.title ?? pendingBookId,
+                        sessionId: streamSessionId,
+                    });
+                }
+                try {
+                    const exec = await executeConfirmedProductionAction({
+                        pipeline,
+                        root,
+                        sessionId: bookSession.sessionId,
+                        streamSessionId,
+                        instruction,
+                        requestedIntent,
+                        actionPayload,
+                        ...(playMode ? { playMode } : {}),
+                    });
+                    let createdBookId = null;
+                    if (exec.tool === "sub_agent" && exec.agent === "architect" && exec.status === "completed") {
+                        createdBookId = resolveCreatedBookIdFromToolExecs([exec]);
+                        if (createdBookId) {
+                            try {
+                                const migratedSession = await migrateBookSession(root, bookSession.sessionId, createdBookId);
+                                if (migratedSession) {
+                                    bookSession = migratedSession;
+                                }
+                            }
+                            catch (e) {
+                                if (!(e instanceof SessionAlreadyMigratedError)) {
+                                    throw e;
+                                }
+                            }
+                            const book = await loadStudioBookListSummary(state, createdBookId).catch(() => undefined);
+                            bookCreateStatus.delete(createdBookId);
+                            broadcast("book:created", {
+                                bookId: createdBookId,
+                                sessionId: bookSession.sessionId,
+                                ...(book ? { book } : {}),
+                            });
+                        }
+                    }
+                    const responseText = exec.result ?? "已完成。";
+                    await appendManualSessionMessages(root, bookSession.sessionId, [
+                        manualToolAssistantMessage(responseText, exec, configuredEntry?.service ?? reqService ?? config.llm.provider, reqModel ?? config.llm.model),
+                    ], instruction, manualToolAppendOptions(sessionKind, exec));
+                    await refreshBookSessionFromTranscript();
+                    broadcast("agent:complete", { instruction, activeBookId: createdBookId ?? agentBookId, sessionId: bookSession.sessionId, sessionKind });
+                    return c.json({
+                        response: responseText,
+                        session: {
+                            sessionId: bookSession.sessionId,
+                            sessionKind,
+                            ...(createdBookId ?? agentBookId ? { activeBookId: createdBookId ?? agentBookId } : {}),
+                        },
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (pendingBookId) {
+                        bookCreateStatus.set(pendingBookId, { status: "error", error: message });
+                        broadcast("book:error", { bookId: pendingBookId, sessionId: streamSessionId, error: message });
+                    }
+                    if (error instanceof ConfirmedActionExecutionError) {
+                        await appendManualSessionMessages(root, bookSession.sessionId, [
+                            manualToolAssistantMessage(message, error.exec, configuredEntry?.service ?? reqService ?? config.llm.provider, reqModel ?? config.llm.model),
+                        ], instruction, manualToolAppendOptions(sessionKind, error.exec)).catch(() => undefined);
+                        await refreshBookSessionFromTranscript().catch(() => undefined);
+                    }
+                    broadcast("agent:error", { instruction, activeBookId: agentBookId, sessionId: bookSession.sessionId, sessionKind, error: message });
+                    return c.json({
+                        error: { code: "AGENT_ACTION_FAILED", message },
+                        response: message,
+                    }, 502);
+                }
+            }
+            if (shouldRunDirectWriteNext({ instruction, agentBookId, sessionKind, actionSource, requestedIntent })) {
+                const directWriteBookId = agentBookId;
+                if (!directWriteBookId) {
+                    throw new ApiError(400, "BOOK_ID_REQUIRED", "write_next requires an active book");
+                }
                 const toolCallId = `direct-writer-${Date.now().toString(36)}`;
-                const toolArgs = { agent: "writer", bookId: agentBookId };
+                const toolArgs = { agent: "writer", bookId: directWriteBookId };
                 broadcast("tool:start", {
                     sessionId: streamSessionId,
                     id: toolCallId,
@@ -2097,17 +2911,24 @@ export function createStudioServer(initialConfig, root) {
                     stages: PIPELINE_STAGES.writer,
                 });
                 try {
-                    const writeResult = await pipeline.writeNextChapter(agentBookId);
-                    const responseText = [
-                        `已为 ${agentBookId} 完成第 ${writeResult.chapterNumber} 章`,
-                        writeResult.title ? `《${writeResult.title}》` : "",
-                        `，字数 ${writeResult.wordCount}，状态 ${writeResult.status}。`,
-                    ].join("");
+                    const writeResult = await pipeline.writeNextChapter(directWriteBookId);
+                    const writeNeedsReview = Boolean(writeResult.status && writeResult.status !== "ready-for-review");
+                    const responseText = writeNeedsReview
+                        ? [
+                            `已为 ${directWriteBookId} 写出第 ${writeResult.chapterNumber} 章`,
+                            writeResult.title ? `《${writeResult.title}》` : "",
+                            `，字数 ${writeResult.wordCount}，但审稿未通过，状态 ${writeResult.status}，需要复核后再继续。`,
+                        ].join("")
+                        : [
+                            `已为 ${directWriteBookId} 完成第 ${writeResult.chapterNumber} 章`,
+                            writeResult.title ? `《${writeResult.title}》` : "",
+                            `，字数 ${writeResult.wordCount}，状态 ${writeResult.status}。`,
+                        ].join("");
                     const toolResult = {
                         content: [{ type: "text", text: responseText }],
                         details: {
                             kind: "chapter_written",
-                            bookId: agentBookId,
+                            bookId: directWriteBookId,
                             chapterNumber: writeResult.chapterNumber,
                             title: writeResult.title,
                             wordCount: writeResult.wordCount,
@@ -2120,38 +2941,48 @@ export function createStudioServer(initialConfig, root) {
                         tool: "sub_agent",
                         result: toolResult,
                         details: toolResult.details,
-                        isError: false,
+                        isError: writeNeedsReview,
                     });
-                    await appendManualSessionMessages(root, bookSession.sessionId, [{
-                            role: "assistant",
-                            content: [{ type: "text", text: responseText }],
-                            api: "anthropic-messages",
-                            provider: configuredEntry?.service ?? reqService ?? config.llm.provider,
-                            model: reqModel ?? config.llm.model,
-                            usage: {
-                                input: 0,
-                                output: 0,
-                                cacheRead: 0,
-                                cacheWrite: 0,
-                                totalTokens: 0,
-                                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-                            },
-                            stopReason: "toolUse",
-                            timestamp: Date.now(),
-                        }], instruction);
+                    const exec = {
+                        id: toolCallId,
+                        tool: "sub_agent",
+                        agent: "writer",
+                        label: resolveToolLabel("sub_agent", "writer"),
+                        status: writeNeedsReview ? "error" : "completed",
+                        args: toolArgs,
+                        result: responseText,
+                        details: toolResult.details,
+                        startedAt: Date.now(),
+                        completedAt: Date.now(),
+                    };
+                    await appendManualSessionMessages(root, bookSession.sessionId, [
+                        manualToolAssistantMessage(responseText, exec, configuredEntry?.service ?? reqService ?? config.llm.provider, reqModel ?? config.llm.model),
+                    ], instruction, manualToolAppendOptions(sessionKind, exec));
                     await refreshBookSessionFromTranscript();
-                    broadcast("agent:complete", { instruction, activeBookId: agentBookId, sessionId: bookSession.sessionId });
+                    broadcast("agent:complete", { instruction, activeBookId: directWriteBookId, sessionId: bookSession.sessionId, sessionKind });
                     return c.json({
                         response: responseText,
                         session: {
                             sessionId: bookSession.sessionId,
-                            activeBookId: agentBookId,
+                            sessionKind,
+                            activeBookId: directWriteBookId,
                         },
                     });
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     const toolResult = { content: [{ type: "text", text: message }] };
+                    const exec = {
+                        id: toolCallId,
+                        tool: "sub_agent",
+                        agent: "writer",
+                        label: resolveToolLabel("sub_agent", "writer"),
+                        status: "error",
+                        args: toolArgs,
+                        error: message,
+                        startedAt: Date.now(),
+                        completedAt: Date.now(),
+                    };
                     broadcast("tool:end", {
                         sessionId: streamSessionId,
                         id: toolCallId,
@@ -2159,13 +2990,25 @@ export function createStudioServer(initialConfig, root) {
                         result: toolResult,
                         isError: true,
                     });
-                    broadcast("agent:error", { instruction, activeBookId: agentBookId, sessionId: bookSession.sessionId, error: message });
+                    await appendManualSessionMessages(root, bookSession.sessionId, [
+                        manualToolAssistantMessage(message, exec, configuredEntry?.service ?? reqService ?? config.llm.provider, reqModel ?? config.llm.model),
+                    ], instruction, manualToolAppendOptions(sessionKind, exec)).catch(() => undefined);
+                    await refreshBookSessionFromTranscript().catch(() => undefined);
+                    broadcast("agent:error", { instruction, activeBookId: agentBookId, sessionId: bookSession.sessionId, sessionKind, error: message });
                     return c.json({
                         error: { code: "AGENT_ACTION_FAILED", message },
                         response: message,
                     }, 502);
                 }
             }
+            // The surface agent should speak the user's language, not just the project default.
+            // Pre-commitment surfaces (chat / play / short / book-create, no book yet) infer it
+            // from the instruction; committed book/edit sessions keep the configured language.
+            // Without this, an English request on a zh-default project gets Chinese replies — and
+            // a Chinese play world, because play_start then infers from the rewritten premise.
+            const configLanguage = config.language === "en" ? "en" : "zh";
+            const bookLanguage = activeBookConfig?.language === "en" ? "en" : activeBookConfig?.language === "zh" ? "zh" : undefined;
+            const surfaceLanguage = agentBookId ? (bookLanguage ?? configLanguage) : inferLanguage(instruction);
             // Run pi-agent session
             const collectedToolExecs = [];
             const result = await runAgentSession({
@@ -2174,8 +3017,19 @@ export function createStudioServer(initialConfig, root) {
                 pipeline,
                 projectRoot: root,
                 bookId: agentBookId,
+                sessionKind,
+                playMode,
+                actionSource,
+                requestedIntent,
+                actionPayload,
                 sessionId: bookSession.sessionId,
-                language: config.language ?? "zh",
+                language: surfaceLanguage,
+                onContextCompression: (event) => {
+                    broadcast("context:compression", {
+                        sessionId: streamSessionId,
+                        ...event,
+                    });
+                },
                 onEvent: (event) => {
                     if (event.type === "message_update") {
                         const ame = event.assistantMessageEvent;
@@ -2271,7 +3125,7 @@ export function createStudioServer(initialConfig, root) {
                 const actionExecutionError = validateAgentActionExecution({
                     instruction,
                     agentBookId,
-                    responseText: result.responseText,
+                    requestedIntent,
                     collectedToolExecs,
                 });
                 if (actionExecutionError) {
@@ -2290,6 +3144,12 @@ export function createStudioServer(initialConfig, root) {
                     return null;
                 if (broadcastedCreatedBookId === createdBookId)
                     return createdBookId;
+                if (!await completeBookExists(join(root, "books", createdBookId))) {
+                    const error = "Book creation artifact is incomplete on disk.";
+                    bookCreateStatus.set(createdBookId, { status: "error", error });
+                    broadcast("book:error", { bookId: createdBookId, sessionId: bookSession.sessionId, error });
+                    return null;
+                }
                 try {
                     const migratedSession = await migrateBookSession(root, bookSession.sessionId, createdBookId);
                     if (migratedSession) {
@@ -2312,95 +3172,54 @@ export function createStudioServer(initialConfig, root) {
                 return createdBookId;
             };
             if (!result.responseText) {
-                if (result.errorMessage) {
-                    if (resolveCreatedBookIdFromToolExecs(collectedToolExecs)) {
-                        await finalizeCreatedBook();
-                    }
+                if (hasSuccessfulToolExec(collectedToolExecs, "propose_action")) {
+                    await refreshBookSessionFromTranscript();
+                    broadcast("agent:complete", { instruction, activeBookId, sessionId: bookSession.sessionId, sessionKind });
                     return c.json({
-                        error: { code: "AGENT_LLM_ERROR", message: result.errorMessage },
-                        response: result.errorMessage,
-                    }, 502);
-                }
-                try {
-                    const fallbackClient = createLLMClient({
-                        ...config.llm,
-                        service: configuredEntry?.service ?? reqService ?? config.llm.service,
-                        model: reqModel ?? config.llm.model,
-                        apiKey: agentApiKey ?? config.llm.apiKey,
-                        baseUrl: configuredEntry?.baseUrl ?? "",
-                        ...(configuredEntry?.apiFormat ? { apiFormat: configuredEntry.apiFormat } : {}),
-                        ...(configuredEntry?.stream !== undefined ? { stream: configuredEntry.stream } : {}),
-                    });
-                    const fallback = await chatCompletion(fallbackClient, reqModel ?? config.llm.model, [
-                        { role: "system", content: buildAgentSystemPrompt(agentBookId, config.language ?? "zh") },
-                        { role: "user", content: instruction },
-                    ], { maxTokens: 256 });
-                    if (fallback.content?.trim()) {
-                        const actionExecutionError = validateAgentActionExecution({
-                            instruction,
-                            agentBookId,
-                            responseText: fallback.content,
-                            collectedToolExecs,
-                        });
-                        if (actionExecutionError) {
-                            return c.json({
-                                error: { code: "AGENT_ACTION_NOT_EXECUTED", message: actionExecutionError },
-                                response: actionExecutionError,
-                            }, 502);
-                        }
-                        await appendManualSessionMessages(root, bookSession.sessionId, [{
-                                role: "assistant",
-                                content: [{ type: "text", text: fallback.content }],
-                                api: "anthropic-messages",
-                                provider: configuredEntry?.service ?? reqService ?? config.llm.provider,
-                                model: reqModel ?? config.llm.model,
-                                usage: {
-                                    input: 0,
-                                    output: 0,
-                                    cacheRead: 0,
-                                    cacheWrite: 0,
-                                    totalTokens: 0,
-                                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-                                },
-                                stopReason: "stop",
-                                timestamp: Date.now(),
-                            }], instruction);
-                        await refreshBookSessionFromTranscript();
-                        const createdBookId = await finalizeCreatedBook();
-                        return c.json({
-                            response: fallback.content,
-                            session: {
-                                sessionId: bookSession.sessionId,
-                                ...(createdBookId ? { activeBookId: createdBookId } : {}),
-                            },
-                        });
-                    }
-                }
-                catch {
-                    // fall through to probe-based diagnosis below
-                }
-                try {
-                    const probeClient = createLLMClient({
-                        ...config.llm,
-                        service: configuredEntry?.service ?? reqService ?? config.llm.service,
-                        model: reqModel ?? config.llm.model,
-                        apiKey: agentApiKey ?? config.llm.apiKey,
-                        baseUrl: configuredEntry?.baseUrl ?? "",
-                        ...(configuredEntry?.apiFormat ? { apiFormat: configuredEntry.apiFormat } : {}),
-                        ...(configuredEntry?.stream !== undefined ? { stream: configuredEntry.stream } : {}),
+                        response: "",
+                        session: {
+                            sessionId: bookSession.sessionId,
+                            sessionKind,
+                            ...(bookSession.bookId ? { activeBookId: bookSession.bookId } : {}),
+                        },
                     });
-                    await chatCompletion(probeClient, reqModel ?? config.llm.model, [{ role: "user", content: "ping" }], { maxTokens: 5 });
                 }
-                catch (probeError) {
-                    const probeMessage = probeError instanceof Error ? probeError.message : String(probeError);
+                if (result.errorMessage) {
                     if (resolveCreatedBookIdFromToolExecs(collectedToolExecs)) {
                         await finalizeCreatedBook();
                     }
+                    const failure = formatAgentFailure(result.errorMessage);
                     return c.json({
-                        error: { code: "AGENT_EMPTY_RESPONSE", message: probeMessage },
-                        response: probeMessage,
+                        error: { code: failure.code, message: failure.message },
+                        response: failure.message,
+                    }, failure.status);
+                }
+                const actionExecutionError = validateAgentActionExecution({
+                    instruction,
+                    agentBookId,
+                    requestedIntent,
+                    collectedToolExecs,
+                });
+                if (actionExecutionError) {
+                    return c.json({
+                        error: { code: "AGENT_ACTION_NOT_EXECUTED", message: actionExecutionError },
+                        response: actionExecutionError,
                     }, 502);
                 }
+                await refreshBookSessionFromTranscript();
+                const createdBookId = await finalizeCreatedBook();
+                if (requestedIntent || createdBookId || hasSuccessfulToolResult(collectedToolExecs)) {
+                    const responseSessionKind = bookSession.sessionKind ?? sessionKind;
+                    broadcast("agent:complete", { instruction, activeBookId, sessionId: bookSession.sessionId, sessionKind: responseSessionKind });
+                    return c.json({
+                        response: "",
+                        session: {
+                            sessionId: bookSession.sessionId,
+                            sessionKind: responseSessionKind,
+                            ...(createdBookId ?? bookSession.bookId ? { activeBookId: createdBookId ?? bookSession.bookId } : {}),
+                        },
+                    });
+                }
                 const emptyMessage = "模型未返回文本内容。请检查协议类型（chat/responses）、流式开关或上游服务兼容性。";
                 if (resolveCreatedBookIdFromToolExecs(collectedToolExecs)) {
                     await finalizeCreatedBook();
@@ -2412,11 +3231,13 @@ export function createStudioServer(initialConfig, root) {
             }
             await refreshBookSessionFromTranscript();
             await finalizeCreatedBook();
-            broadcast("agent:complete", { instruction, activeBookId, sessionId: bookSession.sessionId });
+            const responseSessionKind = bookSession.sessionKind ?? sessionKind;
+            broadcast("agent:complete", { instruction, activeBookId, sessionId: bookSession.sessionId, sessionKind: responseSessionKind });
             return c.json({
                 response: result.responseText,
                 session: {
                     sessionId: bookSession.sessionId,
+                    sessionKind: responseSessionKind,
                     ...(bookSession.bookId ? { activeBookId: bookSession.bookId } : {}),
                 },
             });
@@ -2430,7 +3251,7 @@ export function createStudioServer(initialConfig, root) {
                 throw new ApiError(409, "SESSION_ALREADY_MIGRATED", migratedMessage);
             }
             const msg = e instanceof Error ? e.message : String(e);
-            broadcast("agent:error", { instruction, activeBookId, sessionId, error: msg });
+            broadcast("agent:error", { instruction, activeBookId, sessionId, sessionKind: reqSessionKind, error: msg });
             // Agent busy — return 429 with user-friendly message
             if (/already processing|prompt.*queue/i.test(msg)) {
                 return c.json({
@@ -2438,7 +3259,8 @@ export function createStudioServer(initialConfig, root) {
                     response: "正在处理中，请等待当前操作完成后再发送。",
                 }, 429);
             }
-            return c.json({ error: { code: "AGENT_ERROR", message: msg } }, 500);
+            const failure = formatAgentFailure(msg);
+            return c.json({ error: { code: failure.code, message: failure.message } }, failure.status);
         }
     });
     // --- Language setup ---
@@ -2620,6 +3442,21 @@ export function createStudioServer(initialConfig, root) {
         await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
         return c.json({ ok: true });
     });
+    // --- Chapter review mode (C4a: auto pipeline vs manual checkpoint) ---
+    app.get("/api/v1/project/chapter-review-mode", async (c) => {
+        const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
+        return c.json({ mode: raw.writing?.reviewMode === "manual" ? "manual" : "auto" });
+    });
+    app.put("/api/v1/project/chapter-review-mode", async (c) => {
+        const { mode } = await c.req.json();
+        const next = mode === "manual" ? "manual" : "auto";
+        const configPath = join(root, "inkos.json");
+        const raw = JSON.parse(await readFile(configPath, "utf-8"));
+        raw.writing = { ...(raw.writing ?? {}), reviewMode: next };
+        const { writeFile: writeFileFs } = await import("node:fs/promises");
+        await writeFileFs(configPath, JSON.stringify(raw, null, 2), "utf-8");
+        return c.json({ ok: true, mode: next });
+    });
     // --- Notify channels ---
     app.get("/api/v1/project/notify", async (c) => {
         const raw = JSON.parse(await readFile(join(root, "inkos.json"), "utf-8"));
@@ -2673,6 +3510,9 @@ export function createStudioServer(initialConfig, root) {
                 return c.json({ error: "Legacy compat shim; edit outline/story_frame.md instead" }, 400);
             }
         }
+        if (RUNTIME_DIAGNOSTIC_FILE_RE.test(file)) {
+            return c.json({ error: "Runtime diagnostic files are read-only" }, 400);
+        }
         const { content } = await c.req.json();
         const { writeFile: writeFileFs, mkdir: mkdirFs } = await import("node:fs/promises");
         const { dirname: dirnameFs } = await import("node:path");
@@ -3005,6 +3845,98 @@ export function createStudioServer(initialConfig, root) {
             return c.json({ error: String(e) }, 500);
         }
     });
+    // --- Side-story (番外) init: companion book inheriting a parent's canon ---
+    app.post("/api/v1/spinoff/init", async (c) => {
+        const body = await c.req.json();
+        if (!body.title?.trim() || !body.parentBookId?.trim()) {
+            return c.json({ error: "title and parentBookId are required" }, 400);
+        }
+        let parent;
+        try {
+            parent = await state.loadBookConfig(body.parentBookId);
+        }
+        catch {
+            return c.json({ error: `Parent book "${body.parentBookId}" not found` }, 404);
+        }
+        const language = (body.language ?? parent.language);
+        const now = new Date().toISOString();
+        const bookConfig = buildStudioBookConfig({
+            title: body.title,
+            genre: body.genre ?? parent.genre ?? "other",
+            platform: body.platform ?? parent.platform,
+            targetChapters: body.targetChapters ?? parent.targetChapters,
+            chapterWordCount: body.chapterWordCount ?? parent.chapterWordCount,
+            ...(language ? { language } : {}),
+        }, now);
+        const bookId = bookConfig.id;
+        if (!bookId) {
+            return c.json({ error: "Could not derive a valid book id from title" }, 400);
+        }
+        if (await completeBookExists(state.bookDir(bookId))) {
+            return c.json({ error: `Book "${bookId}" already exists` }, 409);
+        }
+        broadcast("spinoff:start", { bookId, title: body.title, parentBookId: body.parentBookId });
+        bookCreateStatus.set(bookId, { status: "creating" });
+        void (async () => {
+            try {
+                const pipeline = new PipelineRunner(await buildPipelineConfig());
+                await pipeline.initSpinoffBook(bookConfig, body.parentBookId, body.direction);
+                const book = await loadStudioBookListSummary(state, bookId).catch(() => undefined);
+                bookCreateStatus.delete(bookId);
+                broadcast("spinoff:complete", { bookId });
+                broadcast("book:created", { bookId, ...(book ? { book } : {}) });
+            }
+            catch (e) {
+                const error = e instanceof Error ? e.message : String(e);
+                bookCreateStatus.set(bookId, { status: "error", error });
+                broadcast("spinoff:error", { bookId, error });
+                broadcast("book:error", { bookId, error });
+            }
+        })();
+        return c.json({ status: "creating", bookId });
+    });
+    // --- Imitation (仿写) init: original story imitating a reference work's style ---
+    app.post("/api/v1/imitation/init", async (c) => {
+        const body = await c.req.json();
+        if (!body.title?.trim() || !body.referenceText?.trim() || !body.storyIdea?.trim()) {
+            return c.json({ error: "title, referenceText and storyIdea are required" }, 400);
+        }
+        const now = new Date().toISOString();
+        const bookConfig = buildStudioBookConfig({
+            title: body.title,
+            genre: body.genre ?? "other",
+            platform: body.platform,
+            targetChapters: body.targetChapters,
+            chapterWordCount: body.chapterWordCount,
+            ...(body.language ? { language: body.language } : {}),
+        }, now);
+        const bookId = bookConfig.id;
+        if (!bookId) {
+            return c.json({ error: "Could not derive a valid book id from title" }, 400);
+        }
+        if (await completeBookExists(state.bookDir(bookId))) {
+            return c.json({ error: `Book "${bookId}" already exists` }, 409);
+        }
+        broadcast("imitation:start", { bookId, title: body.title });
+        bookCreateStatus.set(bookId, { status: "creating" });
+        void (async () => {
+            try {
+                const pipeline = new PipelineRunner(await buildPipelineConfig());
+                await pipeline.initImitationBook(bookConfig, body.referenceText, body.storyIdea, body.sourceName);
+                const book = await loadStudioBookListSummary(state, bookId).catch(() => undefined);
+                bookCreateStatus.delete(bookId);
+                broadcast("imitation:complete", { bookId });
+                broadcast("book:created", { bookId, ...(book ? { book } : {}) });
+            }
+            catch (e) {
+                const error = e instanceof Error ? e.message : String(e);
+                bookCreateStatus.set(bookId, { status: "error", error });
+                broadcast("imitation:error", { bookId, error });
+                broadcast("book:error", { bookId, error });
+            }
+        })();
+        return c.json({ status: "creating", bookId });
+    });
     // --- Radar Scan ---
     app.post("/api/v1/radar/scan", async (c) => {
         broadcast("radar:start", {});
@@ -3049,7 +3981,10 @@ export function createStudioServer(initialConfig, root) {
         try {
             const currentConfig = await loadCurrentProjectConfig({ requireApiKey: false });
             const service = currentConfig.llm.service ?? currentConfig.llm.provider;
-            const probe = await probeServiceCapabilities({
+            // Hard overall budget so the diagnostics page never hangs on a slow /
+            // rate-limited upstream — if we can't confirm connectivity quickly, report
+            // it as not-connected rather than spinning.
+            const probe = await withTimeout(probeServiceCapabilities({
                 root,
                 service,
                 apiKey: currentConfig.llm.apiKey,
@@ -3058,10 +3993,10 @@ export function createStudioServer(initialConfig, root) {
                 preferredStream: currentConfig.llm.stream,
                 preferredModel: currentConfig.llm.model,
                 proxyUrl: currentConfig.llm.proxyUrl,
-            });
+            }), DOCTOR_LLM_PROBE_BUDGET_MS, "doctor llm probe");
             checks.llmConnected = probe.ok;
         }
-        catch { /* ignore */ }
+        catch { /* slow/unreachable upstream — leave llmConnected false */ }
         return c.json(checks);
     });
     return app;