@musnows/scriverse 0.7.11 → 0.7.12

package/dist/ai.js

@@ -1200,11 +1200,11 @@ export class ContextBuilder {
             ? [wrapAiContextRegion("work", `作品：${String(work.title)}\n作者：${String(work.author) || "未填写"}`)]
             : [];
         const contentSections = [];
-        const availableSettings = this.store.listSettings(workId);
+        const availableSettings = includeSettingInfo ? this.store.listSettings(workId) : [];
         const contextualSettings = !includeSettingInfo
             ? []
             : scope.includeAllSettings ? availableSettings : availableSettings.filter((item) => item.locked);
-        const allCharacters = this.store.listCharacters(workId);
+        const allCharacters = includeSettingInfo ? this.store.listCharacters(workId) : [];
         const lockedCharacters = includeSettingInfo
             ? allCharacters.filter((item) => Array.isArray(item.lockedFields) && item.lockedFields.length > 0)
             : [];
@@ -1262,24 +1262,37 @@ export class ContextBuilder {
                 this.appendChapter(contentSections, workId, scope.chapterId, false);
         }
         else if (scope.type === "chapter") {
-            if (!scope.chapterId)
+            const chapterIds = [...new Set([
+                    ...(scope.chapterId ? [scope.chapterId] : []),
+                    ...(scope.chapterIds ?? [])
+                ])];
+            if (chapterIds.length === 0)
                 throw new AppError(400, "CHAPTER_REQUIRED", "章节上下文缺少章节标识");
-            this.appendPreviousChapterTail(contentSections, workId, scope.chapterId);
-            this.appendChapter(contentSections, workId, scope.chapterId, true);
+            if (chapterIds.length === 1 && scope.chapterId)
+                this.appendPreviousChapterTail(contentSections, workId, scope.chapterId);
+            for (const chapterId of chapterIds)
+                this.appendChapter(contentSections, workId, chapterId, true);
             if (scope.selection)
                 contentSections.push(wrapAiContextRegion("selection", `当前选中文本（本次修改目标）：\n${scope.selection}`, { escape: false }));
         }
         else if (scope.type === "volume") {
-            if (!scope.volumeId)
+            const volumeIds = [...new Set([
+                    ...(scope.volumeId ? [scope.volumeId] : []),
+                    ...(scope.volumeIds ?? [])
+                ])];
+            if (volumeIds.length === 0)
                 throw new AppError(400, "VOLUME_REQUIRED", "卷上下文缺少卷标识");
             const tree = this.store.getWorkTree(workId);
-            const volume = tree.volumes.find((item) => item.id === scope.volumeId);
-            if (!volume)
-                throw notFound("卷");
-            const chapters = volume.chapters;
-            contentSections.push(wrapAiContextRegion("volume", `当前卷：${String(volume.title)}`));
-            for (const chapter of chapters) {
-                contentSections.push(wrapAiContextRegion("chapter", `[${String(volume.title)} / ${String(chapter.title)} | 版本 ${String(chapter.versionNo)}]\n${String(chapter.content)}`));
+            const volumes = tree.volumes;
+            for (const volumeId of volumeIds) {
+                const volume = volumes.find((item) => item.id === volumeId);
+                if (!volume)
+                    throw notFound("卷");
+                const chapters = volume.chapters;
+                contentSections.push(wrapAiContextRegion("volume", `当前卷：${String(volume.title)}`));
+                for (const chapter of chapters) {
+                    contentSections.push(wrapAiContextRegion("chapter", `[${String(volume.title)} / ${String(chapter.title)} | 版本 ${String(chapter.versionNo)}]\n${String(chapter.content)}`));
+                }
             }
         }
         else if (scope.type === "book") {
@@ -1302,7 +1315,7 @@ export class ContextBuilder {
                 : "设定库目录：\n（暂无设定条目）"));
         }
         if (scope.includeBookSummary || scope.type === "book" || scope.type === "volume") {
-            this.appendBookSummary(contentSections, workId, bookSummaryMaximumTokens ?? Math.max(160, Math.floor(maximumTokens * 0.35)), query, scope.type === "volume" ? scope.volumeId : undefined);
+            this.appendBookSummary(contentSections, workId, bookSummaryMaximumTokens ?? Math.max(160, Math.floor(maximumTokens * 0.35)), query, scope.type === "volume" && !scope.volumeIds?.length ? scope.volumeId : undefined);
         }
         if (scope.characterIds?.length) {
             const characters = scope.characterIds.map((characterId) => this.store.getCharacter(characterId));
@@ -2686,6 +2699,166 @@ export class AiManager {
             model: this.getModel(stringValue(row, "model_id"))
         })), pagination);
     }
+    analysisTaskContextPreviewInput(workId, taskType, scope) {
+        const previewTaskType = this.analysisTaskModelPurpose(taskType);
+        let previewScope = scope;
+        let instruction = "请基于所选分析范围完成结构化小说分析，只引用注入资料中的事实并给出可追溯证据。";
+        let agentToolIds;
+        if (taskType === "chapter-analysis") {
+            const chapters = this.getScopeChapters(workId, scope);
+            if (chapters.length === 0)
+                throw new AppError(409, "CHAPTERS_REQUIRED", "章节分析范围内没有章节");
+            const chapter = [...chapters].sort((left, right) => String(right.content).length - String(left.content).length)[0];
+            if (!chapter)
+                throw new AppError(409, "CHAPTERS_REQUIRED", "章节分析范围内没有章节");
+            previewScope = {
+                ...scope,
+                type: "chapter",
+                chapterId: String(chapter.id),
+                chapterIds: undefined,
+                volumeId: undefined,
+                volumeIds: undefined
+            };
+            instruction = "分析当前章节并输出结构化结果，字段包括摘要、事件、人物、设定、证据和不确定项。";
+        }
+        else if (taskType === "character-extraction" || taskType === "character-summary" || taskType === "setting-extraction") {
+            const chapters = this.getScopeChapters(workId, scope);
+            if (chapters.length === 0)
+                throw new AppError(409, "CHAPTERS_REQUIRED", "分析范围内没有章节");
+            const chunks = this.buildChapterChunks(chapters, 10_000);
+            const selection = [...chunks].sort((left, right) => right.text.length - left.text.length)[0]?.text ?? "";
+            previewScope = { type: "selection", selection };
+            instruction = taskType === "setting-extraction"
+                ? "从本批正文抽取可复用的世界设定候选，并为每条候选提供原文证据。"
+                : "从本批正文抽取人物候选，并为每位候选提供原文首次出现证据。";
+        }
+        else if (taskType === "relationship-analysis") {
+            const targeted = Boolean(scope.characterIds?.length);
+            const characters = targeted
+                ? this.store.db.all(`SELECT id, name, aliases_json FROM characters
+           WHERE work_id = ? AND merged_into_character_id IS NULL ORDER BY name`, workId).map((row) => ({
+                    id: String(row.id),
+                    name: String(row.name),
+                    aliases: json(String(row.aliases_json), [])
+                }))
+                : this.store.listCharacters(workId);
+            const roster = characters.map((character) => `${String(character.id)} | ${String(character.name)}${Array.isArray(character.aliases) && character.aliases.length ? ` | 别名：${character.aliases.join("、")}` : ""}`).join("\n");
+            let selection = "本次范围没有可注入的正文或设定数据。";
+            if (scope.type === "settings") {
+                const chunks = this.buildSettingChunks(this.relationshipSettingSources(workId, characters), 12_000);
+                selection = [...chunks].sort((left, right) => right.text.length - left.text.length)[0]?.text ?? selection;
+                previewScope = { type: "settings", selection };
+            }
+            else {
+                if (targeted && scope.type === "book") {
+                    const stats = this.store.db.get(`SELECT COUNT(*) AS chapter_count,
+               COALESCE(SUM(LENGTH(chapter.content)), 0) AS total_characters
+             FROM chapters chapter
+             JOIN volumes volume ON volume.id = chapter.volume_id
+             WHERE chapter.work_id = ? AND chapter.deleted_at IS NULL AND volume.deleted_at IS NULL
+               AND chapter.excluded_from_analysis = 0 AND chapter.chapter_type <> '作者的话'`, workId) ?? {};
+                    const chapterCount = Number(stats.chapter_count ?? 0);
+                    const totalCharacters = Number(stats.total_characters ?? 0);
+                    if (chapterCount > 0 && totalCharacters > 0) {
+                        const previewCharacters = Math.min(totalCharacters + chapterCount * 80, 12_000);
+                        selection = `<CHAPTER id="context-preview" title="上下文预检">\n${"字".repeat(previewCharacters)}\n</CHAPTER>`;
+                    }
+                }
+                else {
+                    const chunks = this.buildChapterChunks(this.getScopeChapters(workId, scope), 12_000);
+                    selection = [...chunks].sort((left, right) => right.text.length - left.text.length)[0]?.text ?? selection;
+                }
+                previewScope = {
+                    type: "selection",
+                    selection,
+                    ...(targeted ? { suppressAutomaticContext: true } : {})
+                };
+            }
+            instruction = `抽取本批正文或设定中的人物长期关系候选，只使用原文证据。角色规范表：\n${roster}`;
+        }
+        else if (taskType === "character-identity-audit") {
+            const characters = this.store.listCharacters(workId);
+            const roster = characters.map((character) => `${String(character.id)} | ${String(character.name)} | 别名=${JSON.stringify(character.aliases)} | 身份=${String(character.attributes.identity ?? "未知")}`).join("\n");
+            instruction = `审核角色规范表，找出疑似重复角色并给出原文证据。角色规范表：\n${roster}`;
+            agentToolIds = ["search_story_entities", "grep", "read_chapters"];
+        }
+        else if (taskType === "timeline-analysis") {
+            instruction = "抽取所选范围内的大事件候选，区分发生时间与叙述时间，并为每项提供原文证据。";
+        }
+        else if (taskType === "worldview-analysis") {
+            instruction = "分析所选范围内已经出现的世界观，区分事实、传闻和未知项，并为结论提供原文证据。";
+        }
+        else if (taskType === "consistency-check") {
+            instruction = "检查所选范围内的设定、人物状态、关系和时间冲突，并为每项问题提供原文证据。";
+        }
+        return { taskType: previewTaskType, instruction, scope: previewScope, ...(agentToolIds ? { agentToolIds } : {}) };
+    }
+    previewAnalysisTaskContext(workId, input) {
+        this.store.getWork(workId);
+        const scope = (input.scope ?? { type: "book" });
+        const { model } = this.resolveModel(workId, this.analysisTaskModelPurpose(input.taskType), input.modelId);
+        const previewInput = this.analysisTaskContextPreviewInput(workId, input.taskType, scope);
+        const modelId = stringValue(model, "id");
+        const modelName = stringValue(model, "display_name") || stringValue(model, "model_id");
+        const contextWindow = numberValue(model, "context_window") || DEFAULT_CONTEXT_WINDOW;
+        const compactThreshold = Math.min(90, Math.max(50, Number(this.store.getWorkAiSettings(workId).contextCompactThreshold) || 85));
+        const thresholdTokens = Math.max(256, Math.floor(contextWindow * compactThreshold / 100));
+        const budget = this.contextBudget({ workId, ...previewInput }, model);
+        const base = {
+            allowed: false,
+            taskType: input.taskType,
+            modelId,
+            modelName,
+            contextWindow,
+            thresholdPercent: compactThreshold,
+            thresholdTokens,
+            availableInputTokens: Number(budget.availableInputTokens),
+            contextBudgetTokens: Number(budget.workContextBudgetTokens),
+            requiredContextWindow: null,
+            estimatedInputTokens: null,
+            estimatedContextTokens: null,
+            omittedContextBlocks: 0,
+            degradedContextBlocks: 0
+        };
+        let usage;
+        try {
+            usage = this.getContextUsage({
+                workId,
+                taskType: previewInput.taskType,
+                modelId,
+                scope: previewInput.scope,
+                instruction: previewInput.instruction,
+                agentToolIds: previewInput.agentToolIds
+            });
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "CONSTRAINT_CONTEXT_TOO_LARGE")
+                throw error;
+            return {
+                ...base,
+                overThreshold: true,
+                message: `当前分析范围注入的锁定设定和人物资料已超过模型“${modelName}”的安全上下文容量，请切换到上下文更长的模型，或缩小分析范围后重试。`
+            };
+        }
+        const estimatedInputTokens = Number(usage.inputTokens) || 0;
+        const estimatedContextTokens = Number(usage.contextTokens) || 0;
+        const omittedContextBlocks = Number(usage.omittedContextBlocks) || 0;
+        const degradedContextBlocks = Number(usage.degradedContextBlocks) || 0;
+        const overThreshold = estimatedInputTokens >= thresholdTokens || omittedContextBlocks > 0 || degradedContextBlocks > 0;
+        return {
+            ...base,
+            allowed: !overThreshold,
+            overThreshold,
+            estimatedInputTokens,
+            estimatedContextTokens,
+            omittedContextBlocks,
+            degradedContextBlocks,
+            requiredContextWindow: overThreshold ? Math.ceil(estimatedInputTokens * 100 / compactThreshold) : null,
+            message: overThreshold
+                ? `当前分析范围预计注入约 ${estimatedInputTokens.toLocaleString("zh-CN")} Token，已达到模型“${modelName}”安全阈值（${contextWindow.toLocaleString("zh-CN")} Token 的 ${compactThreshold}%），部分资料将被压缩或省略。请切换到上下文更长的模型，或缩小分析范围后重试。`
+                : "当前分析范围在所选模型的安全上下文阈值内。"
+        };
+    }
     createTask(workId, input) {
         this.store.getWork(workId);
         const modelPurpose = this.analysisTaskModelPurpose(input.taskType);
@@ -2697,7 +2870,17 @@ export class AiManager {
             ? input.scope
             : null;
         if (relationshipScope && Array.isArray(relationshipScope.relationshipSourceRefs)) {
-            this.relationshipSourcesFromRefs(workId, relationshipScope, this.store.listCharacters(workId), relationshipScope.relationshipSourceRefs);
+            this.validateRelationshipSourceRefs(workId, relationshipScope, relationshipScope.relationshipSourceRefs);
+        }
+        if (modelId) {
+            const contextPreview = this.previewAnalysisTaskContext(workId, {
+                taskType: input.taskType,
+                scope: input.scope,
+                modelId
+            });
+            if (contextPreview.allowed !== true) {
+                throw new AppError(413, "AI_CONTEXT_TOO_LARGE", String(contextPreview.message), contextPreview);
+            }
         }
         return this.store.createTask(workId, {
             taskType: input.taskType,
@@ -4356,7 +4539,7 @@ export class AiManager {
             .filter(([, module]) => canReadWorkModule(permissions, module))
             .map(([category]) => category));
     }
-    async executeAgentTool(workId, toolCall, maximumResultChars = AGENT_TOOL_RESULT_MAX_CHARS, roleplayCharacterId = null, allowedToolIds, signal, onUsage) {
+    async executeAgentTool(workId, toolCall, maximumResultChars = AGENT_TOOL_RESULT_MAX_CHARS, roleplayCharacterId = null, allowedToolIds, signal, onUsage, scope) {
         const name = toolCall.function.name;
         const calledAt = now();
         const maximumRecordChars = Math.max(128, Math.min(6_000, maximumResultChars - 500));
@@ -4423,6 +4606,9 @@ export class AiManager {
             };
         }
         const args = parsed.data;
+        const scopedChapterIds = scope && (scope.type === "chapter" || scope.type === "volume")
+            ? new Set(this.getScopeChapters(workId, scope).map((chapter) => String(chapter.id)))
+            : null;
         if (name === "recall_relationship") {
             if (!roleplayCharacterId)
                 throw new Error("Roleplay character is required for recall_relationship");
@@ -4721,6 +4907,9 @@ export class AiManager {
             const { chapterIds, include, cursor } = args;
             const summaries = new Map(this.store.listCurrentChapterInsights(workId).map((item) => [String(item.chapterId), String(item.summary)]));
             const chapters = chapterIds.map((chapterId) => {
+                if (scopedChapterIds && !scopedChapterIds.has(chapterId)) {
+                    return { chapterId, error: { code: "CHAPTER_OUTSIDE_ANALYSIS_SCOPE", message: "The requested chapter is outside the current analysis scope." } };
+                }
                 try {
                     const chapter = this.store.getChapter(chapterId);
                     if (chapter.workId !== workId)
@@ -4742,7 +4931,8 @@ export class AiManager {
         }
         if (name === "grep") {
             const { keyword, limit, cursor } = args;
-            const matches = this.store.searchChapterParagraphs(workId, keyword, limit);
+            const matches = this.store.searchChapterParagraphs(workId, keyword, limit)
+                .filter((match) => !scopedChapterIds || scopedChapterIds.has(String(match.chapterId)));
             const records = structuralToolResultRecords(matches, maximumRecordChars);
             const result = paginateToolResultRecords(records, cursor, (page, pagination) => ({
                 ok: true,
@@ -5417,7 +5607,7 @@ export class AiManager {
                 const maximumResultChars = toolResultMaximumChars(assistantToolMessage, toolCalls.length);
                 const currentRoundMessages = [assistantToolMessage];
                 for (const toolCall of toolCalls) {
-                    const execution = await this.executeAgentTool(input.workId, toolCall, maximumResultChars, generationRoleplayCharacterId, allowedToolIds, input.signal, trackUsage);
+                    const execution = await this.executeAgentTool(input.workId, toolCall, maximumResultChars, generationRoleplayCharacterId, allowedToolIds, input.signal, trackUsage, input.scope);
                     logger.info("ai.tool_call.completed", {
                         callId,
                         toolName: execution.name,
@@ -5869,27 +6059,52 @@ export class AiManager {
         };
     }
     async runChapterAnalysis(workId, scope, modelId, taskId) {
-        if (!scope.chapterId)
-            throw new AppError(400, "CHAPTER_REQUIRED", "章节分析必须指定章节");
-        const chapter = this.store.getChapter(scope.chapterId);
-        const generated = await this.generateTaggedJson({
-            workId,
-            taskId,
-            taskType: "chapter-analysis",
-            signal: this.taskSignal(taskId),
-            instruction: "分析本章并输出 JSON 对象，字段为 summary（1至3句）、events（数组）、characters（数组）、settings（数组）、evidence（数组，每项含 conclusion 和 quote）、uncertainties（数组）。",
-            scope,
-            ...(modelId ? { modelId } : {}),
-            extraSystemPrompt: "本任务要求严格输出可解析的 JSON。"
-        });
-        const data = extractJson(generated.content);
-        if (!this.taskCanCommit(taskId))
-            return { interrupted: true, callId: generated.callId };
-        const insightId = id("insight");
-        this.store.db.run(`INSERT INTO chapter_insights (id, chapter_id, chapter_version, summary, events_json, characters_json,
-       settings_json, evidence_json, uncertainties_json, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'review', ?)`, insightId, String(chapter.id), Number(chapter.versionNo), data.summary ?? "", JSON.stringify(data.events ?? []), JSON.stringify(data.characters ?? []), JSON.stringify(data.settings ?? []), JSON.stringify(data.evidence ?? []), JSON.stringify(data.uncertainties ?? []), now());
-        this.store.db.run("UPDATE chapters SET analysis_status = 'review' WHERE id = ?", String(chapter.id));
-        return { insightId, chapterId: chapter.id, chapterVersion: chapter.versionNo, callId: generated.callId, ...data };
+        const chapters = this.getScopeChapters(workId, scope);
+        if (chapters.length === 0)
+            throw new AppError(409, "CHAPTERS_REQUIRED", "章节分析范围内没有章节");
+        const analyses = [];
+        const insightIds = [];
+        const callIds = [];
+        for (const [index, chapter] of chapters.entries()) {
+            const chapterScope = {
+                ...scope,
+                type: "chapter",
+                chapterId: String(chapter.id),
+                chapterIds: undefined,
+                volumeId: undefined,
+                volumeIds: undefined
+            };
+            const generated = await this.generateTaggedJson({
+                workId,
+                taskId,
+                taskType: "chapter-analysis",
+                signal: this.taskSignal(taskId),
+                instruction: "分析本章并输出 JSON 对象，字段为 summary（1至3句）、events（数组）、characters（数组）、settings（数组）、evidence（数组，每项含 conclusion 和 quote）、uncertainties（数组）。",
+                scope: chapterScope,
+                ...(modelId ? { modelId } : {}),
+                extraSystemPrompt: "本任务要求严格输出可解析的 JSON。"
+            });
+            const data = extractJson(generated.content);
+            if (!this.taskCanCommit(taskId))
+                return { interrupted: true, callIds };
+            const insightId = id("insight");
+            this.store.db.run(`INSERT INTO chapter_insights (id, chapter_id, chapter_version, summary, events_json, characters_json,
+         settings_json, evidence_json, uncertainties_json, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'review', ?)`, insightId, String(chapter.id), Number(chapter.versionNo), data.summary ?? "", JSON.stringify(data.events ?? []), JSON.stringify(data.characters ?? []), JSON.stringify(data.settings ?? []), JSON.stringify(data.evidence ?? []), JSON.stringify(data.uncertainties ?? []), now());
+            this.store.db.run("UPDATE chapters SET analysis_status = 'review' WHERE id = ?", String(chapter.id));
+            analyses.push({ insightId, chapterId: chapter.id, chapterVersion: chapter.versionNo, callId: generated.callId, ...data });
+            insightIds.push(insightId);
+            callIds.push(generated.callId);
+            if (taskId && this.store.getTask(taskId).status === "running") {
+                this.store.updateTask(taskId, { status: "running", progress: Math.min(95, Math.round((index + 1) / chapters.length * 95)) });
+            }
+        }
+        return {
+            ...(chapters.length === 1 ? analyses[0] : {}),
+            insightIds,
+            chapterIds: chapters.map((chapter) => String(chapter.id)),
+            chapterCount: chapters.length,
+            callIds
+        };
     }
     async runTimelineAnalysis(workId, scope, modelId, taskId) {
         const generated = await this.generateTaggedJson({
@@ -6230,18 +6445,24 @@ export class AiManager {
                 `首次章节=${String(character.firstChapterId ?? "未知")}`
             ].join(" | ");
         }).join("\n");
+        const selectedScopeDescription = scope.type === "chapter"
+            ? `指定章节：${[...(scope.chapterIds ?? []), ...(scope.chapterId ? [scope.chapterId] : [])].join("、")}`
+            : scope.type === "volume"
+                ? `指定分卷：${[...(scope.volumeIds ?? []), ...(scope.volumeId ? [scope.volumeId] : [])].join("、")}`
+                : scope.type === "book" ? "全书" : "当前分析范围";
         const generated = await this.generateTaggedJson({
             workId,
             taskId,
             taskType: "book-analysis",
             signal: this.taskSignal(taskId),
-            scope: scope.type === "none" ? scope : { type: "none" },
+            scope,
             ...(modelId ? { modelId } : {}),
             parameters: { temperature: 0.1 },
             agentToolIds: requiredTools,
             agentToolCallLimit: 48,
             instruction: [
                 "审核角色规范表，找出可能把同一个角色误建成两个档案的组合，最多输出 12 组。",
+                `本次只审核${selectedScopeDescription}内的正文证据。search_story_entities 可以查询角色档案，但 grep 和 read_chapters 只能用于当前分析范围，不能扩大到范围外章节。`,
                 "角色规范表：",
                 roster,
                 "你必须主动使用 search_story_entities 按角色主名或别名查找角色档案和关系，并使用 grep 分别搜索疑似组合两侧的主名或别名；需要上下文时再用 read_chapters。工具调用总数不得超过 48 次。",
@@ -6955,21 +7176,36 @@ export class AiManager {
         if (scope.type === "settings")
             return new Set();
         if (scope.type === "chapter") {
-            if (!scope.chapterId)
+            const chapterIds = [...new Set([
+                    ...(scope.chapterId ? [scope.chapterId] : []),
+                    ...(scope.chapterIds ?? [])
+                ])];
+            if (chapterIds.length === 0)
                 throw new AppError(400, "CHAPTER_REQUIRED", "分析范围缺少章节标识");
-            const chapter = this.store.getChapter(scope.chapterId);
-            if (String(chapter.workId) !== workId)
-                throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
-            return new Set([scope.chapterId]);
+            for (const chapterId of chapterIds) {
+                const chapter = this.store.getChapter(chapterId);
+                if (String(chapter.workId) !== workId)
+                    throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
+            }
+            return new Set(chapterIds);
         }
         if (scope.type === "volume") {
-            if (!scope.volumeId)
+            const volumeIds = [...new Set([
+                    ...(scope.volumeId ? [scope.volumeId] : []),
+                    ...(scope.volumeIds ?? [])
+                ])];
+            if (volumeIds.length === 0)
                 throw new AppError(400, "VOLUME_REQUIRED", "分析范围缺少分卷标识");
-            const volume = this.store.getVolume(scope.volumeId);
-            if (String(volume.workId) !== workId)
-                throw new AppError(400, "VOLUME_WORK_MISMATCH", "分卷不属于当前作品");
-            return new Set(this.store.db.all(`SELECT id FROM chapters WHERE work_id = ? AND volume_id = ? AND deleted_at IS NULL
-         AND excluded_from_analysis = 0 AND chapter_type <> '作者的话'`, workId, scope.volumeId).map((row) => String(row.id)));
+            const chapterIds = new Set();
+            for (const volumeId of volumeIds) {
+                const volume = this.store.getVolume(volumeId);
+                if (String(volume.workId) !== workId)
+                    throw new AppError(400, "VOLUME_WORK_MISMATCH", "分卷不属于当前作品");
+                for (const row of this.store.db.all(`SELECT id FROM chapters WHERE work_id = ? AND volume_id = ? AND deleted_at IS NULL
+           AND excluded_from_analysis = 0 AND chapter_type <> '作者的话'`, workId, volumeId))
+                    chapterIds.add(String(row.id));
+            }
+            return chapterIds;
         }
         return new Set(this.store.db.all(`SELECT id FROM chapters WHERE work_id = ? AND deleted_at IS NULL AND excluded_from_analysis = 0 AND chapter_type <> '作者的话'`, workId).map((row) => String(row.id)));
     }
@@ -7859,6 +8095,80 @@ export class AiManager {
         const settings = availableSettings.filter((source) => requestedRefs.has(this.relationshipIndexedSourceKey(source.sourceType, source.sourceId)));
         return { chapters, settings };
     }
+    validateRelationshipSourceRefs(workId, scope, refs) {
+        for (const ref of refs) {
+            const currentVersion = this.relationshipSourceRefVersion(workId, scope, ref.sourceType, ref.sourceId);
+            if (currentVersion === null || currentVersion !== ref.sourceVersion) {
+                throw new AppError(409, "RELATIONSHIP_SOURCE_PREVIEW_STALE", "来源已在预检后发生变化，请重新预览", {
+                    sourceType: ref.sourceType,
+                    sourceId: ref.sourceId
+                });
+            }
+        }
+    }
+    relationshipSourceRefVersion(workId, scope, sourceType, sourceId) {
+        if (sourceType === "chapter") {
+            if (scope.type === "settings")
+                return null;
+            const chapter = this.store.db.get(`SELECT chapter.version_no, chapter.volume_id, chapter.chapter_type, chapter.excluded_from_analysis
+         FROM chapters chapter
+         JOIN volumes volume ON volume.id = chapter.volume_id
+         WHERE chapter.id = ? AND chapter.work_id = ?
+           AND chapter.deleted_at IS NULL AND volume.deleted_at IS NULL`, sourceId, workId);
+            if (!chapter)
+                return null;
+            if (scope.type === "chapter" && scope.chapterId !== sourceId)
+                return null;
+            if (scope.type === "volume" && scope.volumeId !== String(chapter.volume_id))
+                return null;
+            if ((scope.type === "book" || scope.type === "volume")
+                && (Boolean(chapter.excluded_from_analysis) || String(chapter.chapter_type) === "作者的话"))
+                return null;
+            return String(chapter.version_no);
+        }
+        if (scope.type !== "settings" && scope.includeAllSettings !== true)
+            return null;
+        if (sourceType === "work") {
+            const work = this.store.db.get("SELECT version_no FROM works WHERE id = ? AND id = ? AND deleted_at IS NULL", sourceId, workId);
+            return work ? String(work.version_no) : null;
+        }
+        if (sourceType === "character") {
+            const character = this.store.db.get("SELECT version_no FROM characters WHERE id = ? AND work_id = ? AND merged_into_character_id IS NULL", sourceId, workId);
+            return character ? String(character.version_no) : null;
+        }
+        if (sourceType === "review") {
+            const review = this.store.db.get("SELECT updated_at FROM review_items WHERE id = ? AND work_id = ?", sourceId, workId);
+            return review ? String(review.updated_at) : null;
+        }
+        if (sourceType === "chapter-outline") {
+            const outline = this.store.db.get(`SELECT outline.chapter_id FROM chapter_outlines outline
+         JOIN chapters chapter ON chapter.id = outline.chapter_id
+         WHERE outline.chapter_id = ? AND chapter.work_id = ? AND chapter.deleted_at IS NULL`, sourceId, workId);
+            if (!outline)
+                return null;
+            const version = this.store.db.get(`SELECT COALESCE(MAX(version_no), 0) AS version_no FROM entity_versions
+         WHERE work_id = ? AND entity_type = 'chapter-outline' AND entity_id = ?`, workId, sourceId);
+            return String(Number(version?.version_no ?? 0));
+        }
+        const tableBySourceType = {
+            setting: "settings",
+            race: "races",
+            organization: "organizations",
+            "timeline-track": "timeline_tracks",
+            "timeline-event": "timeline_events",
+            relationship: "relationships",
+            foreshadow: "foreshadows"
+        };
+        const table = tableBySourceType[sourceType];
+        if (!table)
+            return null;
+        const source = this.store.db.get(`SELECT id FROM ${table} WHERE id = ? AND work_id = ?`, sourceId, workId);
+        if (!source)
+            return null;
+        const version = this.store.db.get(`SELECT COALESCE(MAX(version_no), 0) AS version_no FROM entity_versions
+       WHERE work_id = ? AND entity_type = ? AND entity_id = ?`, workId, sourceType, sourceId);
+        return String(Number(version?.version_no ?? 0));
+    }
     async previewRelationshipSources(workId, scope, modelId) {
         const characters = this.store.listCharacters(workId);
         if (characters.length < 2)
@@ -8735,20 +9045,37 @@ export class AiManager {
         const tree = this.store.getWorkTree(workId);
         const volumes = tree.volumes;
         if (scope.type === "chapter") {
-            if (!scope.chapterId)
+            const chapterIds = [...new Set([
+                    ...(scope.chapterId ? [scope.chapterId] : []),
+                    ...(scope.chapterIds ?? [])
+                ])];
+            if (chapterIds.length === 0)
                 throw new AppError(400, "CHAPTER_REQUIRED", "分析范围缺少章节标识");
-            const chapter = this.store.getChapter(scope.chapterId);
-            if (chapter.workId !== workId)
-                throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
-            return [chapter];
+            const selected = new Set(chapterIds);
+            const chapters = volumes.flatMap((volume) => volume.chapters)
+                .filter((chapter) => selected.has(String(chapter.id)) && this.isAutomaticAnalysisChapter(chapter));
+            if (chapters.length !== selected.size) {
+                for (const chapterId of chapterIds) {
+                    const chapter = this.store.getChapter(chapterId);
+                    if (chapter.workId !== workId)
+                        throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
+                }
+            }
+            return chapters;
         }
         if (scope.type === "volume") {
-            if (!scope.volumeId)
-                throw new AppError(400, "VOLUME_REQUIRED", "分析范围缺少卷标识");
-            const volume = volumes.find((item) => item.id === scope.volumeId);
-            if (!volume)
+            const volumeIds = [...new Set([
+                    ...(scope.volumeId ? [scope.volumeId] : []),
+                    ...(scope.volumeIds ?? [])
+                ])];
+            if (volumeIds.length === 0)
+                throw new AppError(400, "VOLUME_REQUIRED", "分析范围缺少分卷标识");
+            const selected = new Set(volumeIds);
+            const selectedVolumes = volumes.filter((volume) => selected.has(String(volume.id)));
+            if (selectedVolumes.length !== selected.size)
                 throw notFound("卷");
-            return volume.chapters.filter((chapter) => this.isAutomaticAnalysisChapter(chapter));
+            return selectedVolumes.flatMap((volume) => volume.chapters)
+                .filter((chapter) => this.isAutomaticAnalysisChapter(chapter));
         }
         return volumes.flatMap((volume) => volume.chapters)
             .filter((chapter) => this.isAutomaticAnalysisChapter(chapter));