@musnows/scriverse 0.7.11 → 0.7.13

package/dist/ai.js

@@ -63,6 +63,9 @@ const interactiveStreamErrorCodes = new Set([
 function isInteractiveStreamError(error) {
     return error instanceof AppError && interactiveStreamErrorCodes.has(error.code);
 }
+function isAuthorNoteChapter(chapter) {
+    return String(chapter.chapterType ?? "") === "作者的话";
+}
 function interactiveStreamRequestCancelledError() {
     return new AppError(499, "AI_STREAM_REQUEST_CANCELLED", "AI 流式请求已取消");
 }
@@ -1200,11 +1203,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)
             : [];
@@ -1256,30 +1259,49 @@ export class ContextBuilder {
         if (scope.type === "selection") {
             if (!scope.selection)
                 throw new AppError(400, "SELECTION_REQUIRED", "选中文本上下文不能为空");
+            const selectionChapter = scope.chapterId ? this.store.getChapter(scope.chapterId) : null;
+            if (selectionChapter && selectionChapter.workId !== workId)
+                throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
             // 分析任务会在 selection 中放入服务端 CHAPTER 标记，不能转义
-            contentSections.push(wrapAiContextRegion("selection", `当前选中文本：\n${scope.selection}`, { escape: false }));
-            if (scope.chapterId)
-                this.appendChapter(contentSections, workId, scope.chapterId, false);
+            if (!selectionChapter || !isAuthorNoteChapter(selectionChapter)) {
+                contentSections.push(wrapAiContextRegion("selection", `当前选中文本：\n${scope.selection}`, { escape: false }));
+                if (scope.chapterId)
+                    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 (scope.selection)
+            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 && (!scope.chapterId || !isAuthorNoteChapter(this.store.getChapter(scope.chapterId)))) {
                 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.filter((chapter) => !isAuthorNoteChapter(chapter));
+                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") {
@@ -1287,7 +1309,7 @@ export class ContextBuilder {
             const volumes = tree.volumes;
             contentSections.push(wrapAiContextRegion("book", "全书正文（按问题相关度选取原文，完整结构见章节概要）："));
             for (const volume of volumes) {
-                for (const chapter of volume.chapters) {
+                for (const chapter of volume.chapters.filter((item) => !isAuthorNoteChapter(item))) {
                     contentSections.push(wrapAiContextRegion("chapter", `[# ${String(volume.title)} / ${String(chapter.title)} | 版本 ${String(chapter.versionNo)}]\n${String(chapter.content)}`));
                 }
             }
@@ -1302,7 +1324,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));
@@ -1371,8 +1393,9 @@ export class ContextBuilder {
                 if (chapter.workId !== workId)
                     throw new AppError(400, "CHAPTER_WORK_MISMATCH", "引用章节不属于当前作品");
             }
-            if (chapters.length) {
-                contentSections.push(wrapAiContextRegion("referenced_chapters", `作者主动引用的章节：\n${chapters
+            const eligibleChapters = chapters.filter((chapter) => !isAuthorNoteChapter(chapter));
+            if (eligibleChapters.length) {
+                contentSections.push(wrapAiContextRegion("referenced_chapters", `作者主动引用的章节：\n${eligibleChapters
                     .map((chapter) => `[${String(chapter.title)} | 版本 ${String(chapter.versionNo)}]\n${String(chapter.content)}`)
                     .join("\n\n")}`));
             }
@@ -1477,6 +1500,8 @@ export class ContextBuilder {
         const chapter = this.store.getChapter(chapterId);
         if (chapter.workId !== workId)
             throw new AppError(400, "CHAPTER_WORK_MISMATCH", "章节不属于当前作品");
+        if (isAuthorNoteChapter(chapter))
+            return;
         sections.push(wrapAiContextRegion("chapter", includeContent
             ? `当前章节：${String(chapter.title)} | 版本 ${String(chapter.versionNo)}\n${String(chapter.content)}`
             : `所在章节：${String(chapter.title)} | 版本 ${String(chapter.versionNo)}`));
@@ -1490,7 +1515,7 @@ export class ContextBuilder {
             return;
         const perVolumeBudget = Math.max(24, Math.floor(maximumTokens / volumes.length));
         for (const volume of volumes) {
-            const chapters = volume.chapters;
+            const chapters = volume.chapters.filter((chapter) => !isAuthorNoteChapter(chapter));
             const ranked = chapters.map((chapter, order) => {
                 const summary = summaryByChapterId.get(String(chapter.id)) ?? "";
                 const line = `- ${String(chapter.title)}：${summary || "尚无章节概要"}`;
@@ -1519,9 +1544,12 @@ export class ContextBuilder {
         }
     }
     appendPreviousChapterTail(sections, workId, chapterId) {
+        const current = this.store.getChapter(chapterId);
+        if (current.workId !== workId || isAuthorNoteChapter(current))
+            return;
         const tree = this.store.getWorkTree(workId);
         const chapters = tree.volumes
-            .flatMap((volume) => volume.chapters);
+            .flatMap((volume) => volume.chapters.filter((chapter) => !isAuthorNoteChapter(chapter)));
         const index = chapters.findIndex((chapter) => chapter.id === chapterId);
         if (index <= 0)
             return;
@@ -1532,6 +1560,9 @@ export class ContextBuilder {
         sections.push(wrapAiContextRegion("previous_chapter_tail", `上一章节结尾：${String(previous.title)} | 版本 ${String(previous.versionNo)}\n${content.slice(-5000)}`));
     }
     appendChapterKnowledge(sections, workId, chapterId) {
+        const chapter = this.store.getChapter(chapterId);
+        if (chapter.workId !== workId || isAuthorNoteChapter(chapter))
+            return;
         const outline = this.store.getChapterOutline(chapterId);
         if (outline) {
             sections.push(wrapAiContextRegion("chapter_outline", `当前章大纲（创作约束）：\n目标：${String(outline.goal) || "未填写"}\n冲突：${String(outline.conflict) || "未填写"}\n转折：${String(outline.turningPoint) || "未填写"}\n状态：${String(outline.status)}`));
@@ -2686,6 +2717,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 +2888,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,
@@ -3251,7 +3452,26 @@ export class AiManager {
             && titleModelId
             && (conversationBefore?.title === "新对话" || conversationBefore?.title === defaultTitle));
         const processStartedAt = process.hrtime.bigint();
-        const generated = await this.generate({ ...input, taskType: "chat" }, onDelta);
+        let persistedConversationMessage = null;
+        let streamedConversationContent = "";
+        const persistStreamDelta = (delta) => {
+            if (input.conversationId && input.assistantMessageRequestId && delta.length > 0) {
+                streamedConversationContent += delta;
+                persistedConversationMessage = this.store.upsertAiConversationAssistantMessage(input.conversationId, input.assistantMessageRequestId, streamedConversationContent);
+            }
+            onDelta(delta);
+        };
+        let generated;
+        try {
+            generated = await this.generate({ ...input, taskType: "chat" }, persistStreamDelta);
+        }
+        catch (error) {
+            if (persistedConversationMessage && input.conversationId && input.assistantMessageRequestId) {
+                const interruptionCode = error instanceof AppError ? error.code : "AI_STREAM_FAILED";
+                persistedConversationMessage = this.store.upsertAiConversationAssistantMessage(input.conversationId, input.assistantMessageRequestId, streamedConversationContent, { interrupted: true, interruptionCode }, true);
+            }
+            throw error;
+        }
         const processDurationMs = Math.min(86_400_000, Math.max(0, Math.round(Number(process.hrtime.bigint() - processStartedAt) / 1_000_000)));
         const chapter = input.scope.chapterId ? this.store.getChapter(input.scope.chapterId) : null;
         const suggestionId = id("suggestion");
@@ -3259,22 +3479,17 @@ export class AiManager {
        source_text, content, action, status, created_at, created_by_user_id) VALUES (?, ?, ?, ?, ?, 'chat', ?, ?, ?, 'note', 'pending', ?, ?)`, suggestionId, generated.callId, input.workId, chapter ? String(chapter.id) : null, chapter ? Number(chapter.versionNo) : null, input.instruction, input.scope.selection ?? "", generated.content, now(), currentRequestActor()?.userId ?? null);
         const modelDisplayName = typeof generated.model.displayName === "string" ? generated.model.displayName : undefined;
         const conversationMessage = input.conversationId && input.assistantMessageRequestId
-            ? this.store.addAiConversationMessage(input.conversationId, {
-                role: "assistant",
-                content: generated.content,
-                requestId: input.assistantMessageRequestId,
-                metadata: {
-                    ...(modelDisplayName ? { modelDisplayName } : {}),
-                    outputTokens: generated.outputTokens,
-                    processDurationMs,
-                    ...(generated.reasoningContent === undefined ? {} : { reasoningContent: generated.reasoningContent }),
-                    ...(generated.cacheHitPercent === undefined ? {} : { cacheHitPercent: generated.cacheHitPercent }),
-                    toolCalls: generated.toolCalls,
-                    processSteps: generated.processSteps,
-                    ...(generated.anthropicContent?.length ? { anthropicContent: generated.anthropicContent } : {})
-                }
-            })
-            : null;
+            ? this.store.upsertAiConversationAssistantMessage(input.conversationId, input.assistantMessageRequestId, generated.content, {
+                ...(modelDisplayName ? { modelDisplayName } : {}),
+                outputTokens: generated.outputTokens,
+                processDurationMs,
+                ...(generated.reasoningContent === undefined ? {} : { reasoningContent: generated.reasoningContent }),
+                ...(generated.cacheHitPercent === undefined ? {} : { cacheHitPercent: generated.cacheHitPercent }),
+                toolCalls: generated.toolCalls,
+                processSteps: generated.processSteps,
+                ...(generated.anthropicContent?.length ? { anthropicContent: generated.anthropicContent } : {})
+            }, true)
+            : persistedConversationMessage;
         if (shouldGenerateTitle && conversationMessage && input.conversationId) {
             void this.generateConversationTitle(input.workId, input.conversationId, titleModelId, firstUserContent, generated.content, defaultTitle).catch((error) => {
                 logger.warn("ai.conversation_title.failed", { workId: input.workId, conversationId: input.conversationId, error: aiErrorForLog(error) });
@@ -4356,7 +4571,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 +4638,9 @@ export class AiManager {
             };
         }
         const args = parsed.data;
+        const scopedChapterIds = scope && (scope.type === "chapter" || scope.type === "volume" || scope.type === "book")
+            ? 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");
@@ -4634,7 +4852,7 @@ export class AiManager {
                     .map((item) => item.trim()).filter(Boolean).slice(0, 10);
                 const seenParagraphs = new Set();
                 for (const identityTerm of identityTerms) {
-                    for (const paragraph of this.store.searchChapterParagraphs(workId, identityTerm, 50)) {
+                    for (const paragraph of this.store.searchChapterParagraphs(workId, identityTerm, 50, { excludeAuthorNotes: true })) {
                         const key = `${String(paragraph.chapterId)}:${String(paragraph.paragraph)}`;
                         if (seenParagraphs.has(key))
                             continue;
@@ -4669,7 +4887,7 @@ export class AiManager {
         if (name === "story_index") {
             const { offset, limit, cursor } = args;
             const work = this.store.getWork(workId);
-            const chapterPage = this.store.getStoryIndexChapterPage(workId, offset, limit);
+            const chapterPage = this.store.getStoryIndexChapterPage(workId, offset, limit, { excludeAuthorNotes: true });
             const workRecords = structuralToolResultRecords([{
                     id: work.id,
                     title: work.title,
@@ -4721,10 +4939,15 @@ 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)
                         return { chapterId, error: { code: "CHAPTER_WORK_MISMATCH", message: "The requested chapter belongs to a different work." } };
+                    if (isAuthorNoteChapter(chapter))
+                        return { chapterId, error: { code: "CHAPTER_AUTHOR_NOTE_EXCLUDED", message: "Author notes are excluded from AI context." } };
                     const content = collapseAiBlankLines(String(chapter.content));
                     return { chapterId, title: chapter.title, versionNo: chapter.versionNo, ...(include !== "content" ? { summary: summaries.get(chapterId) ?? "" } : {}), ...(include !== "summary" ? { content } : {}) };
                 }
@@ -4742,7 +4965,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, { excludeAuthorNotes: true })
+                .filter((match) => !scopedChapterIds || scopedChapterIds.has(String(match.chapterId)));
             const records = structuralToolResultRecords(matches, maximumRecordChars);
             const result = paginateToolResultRecords(records, cursor, (page, pagination) => ({
                 ok: true,
@@ -4770,6 +4994,15 @@ export class AiManager {
                     : sourceType === "chapter-outline" ? "outline" : sourceType;
                 if (!requestedCategories.has(type))
                     return [];
+                if (sourceType === "chapter") {
+                    try {
+                        if (isAuthorNoteChapter(this.store.getChapter(String(item.id))))
+                            return [];
+                    }
+                    catch {
+                        return [];
+                    }
+                }
                 return [{
                         ...item,
                         ...this.hybridAiSearchDetails(workId, sourceType, String(item.id)),
@@ -5417,7 +5650,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 +6102,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 +6488,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 +7219,43 @@ 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.filter((chapterId) => {
+                try {
+                    return !isAuthorNoteChapter(this.store.getChapter(chapterId));
+                }
+                catch {
+                    return false;
+                }
+            }));
         }
         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)));
     }
@@ -6979,6 +7265,8 @@ export class AiManager {
                 const chapter = this.store.getChapter(sourceId);
                 if (String(chapter.workId) !== workId)
                     return null;
+                if (isAuthorNoteChapter(chapter))
+                    return null;
                 return {
                     sourceType,
                     sourceId,
@@ -7859,6 +8147,79 @@ 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 (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 +9096,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));
@@ -8780,7 +9158,7 @@ export class AiManager {
         });
     }
     isAutomaticAnalysisChapter(chapter) {
-        return !chapter.excludedFromAnalysis && chapter.chapterType !== "作者的话";
+        return !chapter.excludedFromAnalysis && !isAuthorNoteChapter(chapter);
     }
     buildChapterChunks(chapters, maximumChars = 10_000) {
         const chunks = [];