@musnows/scriverse 0.5.3 → 0.5.5

package/dist/ai.js

@@ -1,11 +1,12 @@
+import { buildCompletionRequestBody, normalizeProviderBaseUrl, parseCompletionPayload, providerCompletionEndpoint, providerModelEndpoints, providerRequestHeaders } from "./ai-protocol.js";
 import { PLATFORM_AI_WORK_ID } from "./database.js";
 import { AppError, notFound } from "./errors.js";
 import { logger, sanitizeError } from "./logger.js";
 import { paginated, paginationSql } from "./pagination.js";
 import { currentRequestActor } from "./request-context.js";
 import { fetchSafeAiEndpoint } from "./security.js";
-import { RELATIONSHIP_SEARCH_POLICY_VERSION, RelationshipApproximateMatchLimitError, findApproximateNameMatchesChunked, ftsPhrase, normalizeRelationshipSearchText, relationshipCharacterTokenText, relationshipCharacterTokens, relationshipPinyinTokenText, relationshipPinyinTokens } from "./relationship-search.js";
-import { clamp, id, json, maskSecret, normalizeBaseUrl, now } from "./utils.js";
+import { RELATIONSHIP_SEARCH_POLICY_VERSION, RelationshipApproximateMatchLimitError, findApproximateNameMatchesChunked, ftsPhrase, isRelationshipPhoneticReference, normalizeRelationshipSearchText, relationshipCharacterTokenText, relationshipCharacterTokens, relationshipPinyinTokenText, relationshipPinyinTokens } from "./relationship-search.js";
+import { clamp, id, json, maskSecret, now } from "./utils.js";
 import { z } from "zod";
 export function aiErrorForLog(error) {
     const sanitized = sanitizeError(error);
@@ -25,6 +26,10 @@ const RELATIONSHIP_MAX_FUZZY_SOURCES = 200;
 const RELATIONSHIP_MAX_FUZZY_SCAN_CHARACTERS = 4_000_000;
 const RELATIONSHIP_MAX_FUZZY_MATCHES = 600;
 const RELATIONSHIP_MAX_SOURCE_MATCHES = 256;
+const RELATIONSHIP_PREFILTER_DISABLE_HINT = "请取消勾选“分析前按人物名称和拼音过滤来源”后重新预览";
+function relationshipCandidateLimitMessage(message) {
+    return `${message}；${RELATIONSHIP_PREFILTER_DISABLE_HINT}`;
+}
 function isGeminiProviderOrModel(provider, model) {
     const endpoint = stringValue(provider, "base_url").toLowerCase();
     const modelId = stringValue(model, "model_id").toLowerCase();
@@ -33,9 +38,22 @@ function isGeminiProviderOrModel(provider, model) {
 function isKimiModelId(modelId) {
     return modelId.toLowerCase().includes("kimi");
 }
+function providerProtocol(provider) {
+    return stringValue(provider, "protocol") === "anthropic-messages" ? "anthropic-messages" : "openai-chat-completions";
+}
+function isLongCatProvider(provider) {
+    try {
+        return new URL(stringValue(provider, "base_url")).hostname.toLowerCase() === "api.longcat.chat";
+    }
+    catch {
+        return false;
+    }
+}
 function thinkingParameters(provider, model) {
     if (isGeminiProviderOrModel(provider, model))
         return {};
+    if (providerProtocol(provider) === "anthropic-messages" && !isLongCatProvider(provider))
+        return {};
     return { thinking: { type: boolValue(model, "thinking_enabled") ? "enabled" : "disabled" } };
 }
 const AGENT_TOOL_IDS = ["story_index", "read_chapters", "grep", "search_story_entities", "read_character_sections"];
@@ -305,10 +323,25 @@ export function resolveOutputTokens(usage, content) {
     }
     return estimateAiTokens(content);
 }
+function reportedTokenCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.round(value))
+        : null;
+}
 function resolveInputCacheUsage(usage) {
     if (!usage || typeof usage !== "object")
         return null;
     const record = usage;
+    const anthropicCacheRead = reportedTokenCount(record.cache_read_input_tokens);
+    const anthropicCacheCreation = reportedTokenCount(record.cache_creation_input_tokens);
+    if (anthropicCacheRead !== null || anthropicCacheCreation !== null) {
+        const uncachedInputTokens = reportedTokenCount(record.input_tokens) ?? 0;
+        const cachedInputTokens = anthropicCacheRead ?? 0;
+        const inputTokens = uncachedInputTokens + cachedInputTokens + (anthropicCacheCreation ?? 0);
+        if (inputTokens <= 0)
+            return null;
+        return { inputTokens, cachedInputTokens };
+    }
     const promptDetails = record.prompt_tokens_details && typeof record.prompt_tokens_details === "object"
         ? record.prompt_tokens_details
         : {};
@@ -342,6 +375,37 @@ export function resolveCacheHitPercent(usage) {
         return undefined;
     return Math.round(resolved.cachedInputTokens / resolved.inputTokens * 1_000) / 10;
 }
+export function resolveAiTokenUsage(usage, estimatedInputTokens, estimatedOutputTokens) {
+    const record = usage && typeof usage === "object" && !Array.isArray(usage)
+        ? usage
+        : {};
+    const reportedInputTokens = reportedTokenCount(record.prompt_tokens ?? record.input_tokens);
+    const reportedOutputTokens = reportedTokenCount(record.completion_tokens ?? record.output_tokens);
+    const cacheUsage = resolveInputCacheUsage(record);
+    const inputTokens = cacheUsage?.inputTokens
+        ?? reportedInputTokens
+        ?? Math.max(0, Math.round(estimatedInputTokens));
+    const outputTokens = reportedOutputTokens ?? Math.max(0, Math.round(estimatedOutputTokens));
+    return {
+        inputTokens,
+        outputTokens,
+        cachedInputTokens: cacheUsage?.cachedInputTokens ?? 0,
+        cacheEligibleInputTokens: cacheUsage?.inputTokens ?? 0,
+        source: reportedInputTokens !== null && reportedOutputTokens !== null
+            ? "reported"
+            : reportedInputTokens === null && reportedOutputTokens === null
+                ? "estimated"
+                : "mixed"
+    };
+}
+function completionPayloadOutputText(payload) {
+    const message = payload.choices?.[0]?.message;
+    return [
+        message?.reasoning_content ?? "",
+        message?.content ?? "",
+        ...(message?.tool_calls ?? []).map((toolCall) => `${toolCall.function.name}\n${String(toolCall.function.arguments ?? "")}`)
+    ].filter(Boolean).join("\n");
+}
 function normalizeModelPreset(input, modelId = "") {
     const maxTokens = typeof input.max_tokens === "number" && Number.isFinite(input.max_tokens)
         ? Math.round(clamp(input.max_tokens, 1, 32_768))
@@ -864,6 +928,7 @@ export class AiManager {
     relationshipIndexBuilds = new Map();
     relationshipSelectionCache = new Map();
     relationshipSelectionBuilds = new Map();
+    relationshipIndexSyncTimers = new Map();
     relationshipIndexSerial = Promise.resolve();
     relationshipIndexTimer = null;
     relationshipIndexDisposed = false;
@@ -876,12 +941,101 @@ export class AiManager {
         this.authorizeTaskRun = authorizeTaskRun;
         this.contextBuilder = new ContextBuilder(store);
         this.store.setAnalysisTaskQueuedHandler((workId) => this.scheduleAutoRun(workId));
+        this.store.setRelationshipIndexQueuedHandler((workId) => this.scheduleRelationshipIndexSync(workId));
         this.relationshipIndexTimer = setTimeout(() => {
             this.relationshipIndexTimer = null;
             void this.schedulePendingRelationshipIndexes();
         }, 0);
         logger.info("ai.manager.ready");
     }
+    getPlatformTokenUsage(timezoneOffset) {
+        return this.getTokenUsage(null, timezoneOffset, true);
+    }
+    getWorkTokenUsage(workId, timezoneOffset) {
+        this.store.getWork(workId);
+        return this.getTokenUsage(workId, timezoneOffset, false);
+    }
+    getTokenUsage(workId, timezoneOffset, includeWorks) {
+        const scopeSql = workId === null ? "" : " AND call.work_id = ?";
+        const scopeParams = workId === null ? [] : [workId];
+        const usageFilter = "(call.input_tokens > 0 OR call.output_tokens > 0)";
+        const summary = this.store.db.get(`SELECT
+         COALESCE(SUM(call.input_tokens), 0) AS input_tokens,
+         COALESCE(SUM(call.output_tokens), 0) AS output_tokens,
+         COALESCE(SUM(call.cached_input_tokens), 0) AS cached_input_tokens,
+         COALESCE(SUM(call.cache_eligible_input_tokens), 0) AS cache_eligible_input_tokens,
+         COUNT(*) AS request_count,
+         COALESCE(SUM(CASE WHEN call.token_usage_source = 'reported' THEN 0 ELSE 1 END), 0) AS estimated_request_count,
+         MIN(call.created_at) AS first_used_at,
+         MAX(call.created_at) AS last_used_at
+       FROM ai_calls call
+       JOIN works work ON work.id = call.work_id
+       WHERE COALESCE(work.is_internal, 0) = 0 AND ${usageFilter}${scopeSql}`, ...scopeParams) ?? {};
+        const daily = this.store.db.all(`SELECT
+         date(call.created_at, printf('%+d minutes', ?)) AS usage_date,
+         COALESCE(SUM(call.input_tokens), 0) AS input_tokens,
+         COALESCE(SUM(call.output_tokens), 0) AS output_tokens,
+         COALESCE(SUM(call.cached_input_tokens), 0) AS cached_input_tokens,
+         COALESCE(SUM(call.cache_eligible_input_tokens), 0) AS cache_eligible_input_tokens,
+         COUNT(*) AS request_count,
+         COALESCE(SUM(CASE WHEN call.token_usage_source = 'reported' THEN 0 ELSE 1 END), 0) AS estimated_request_count
+       FROM ai_calls call
+       JOIN works work ON work.id = call.work_id
+       WHERE COALESCE(work.is_internal, 0) = 0 AND ${usageFilter}${scopeSql}
+       GROUP BY usage_date
+       ORDER BY usage_date`, timezoneOffset, ...scopeParams).map((row) => this.mapTokenUsageRow(row, { date: stringValue(row, "usage_date") }));
+        const works = includeWorks
+            ? this.store.db.all(`SELECT
+           work.id AS work_id,
+           work.title AS work_title,
+           COALESCE(SUM(call.input_tokens), 0) AS input_tokens,
+           COALESCE(SUM(call.output_tokens), 0) AS output_tokens,
+           COALESCE(SUM(call.cached_input_tokens), 0) AS cached_input_tokens,
+           COALESCE(SUM(call.cache_eligible_input_tokens), 0) AS cache_eligible_input_tokens,
+           COUNT(call.id) AS request_count,
+           COALESCE(SUM(CASE WHEN call.id IS NULL OR call.token_usage_source = 'reported' THEN 0 ELSE 1 END), 0) AS estimated_request_count,
+           MIN(call.created_at) AS first_used_at,
+           MAX(call.created_at) AS last_used_at
+         FROM works work
+         LEFT JOIN ai_calls call ON call.work_id = work.id AND ${usageFilter}
+         WHERE COALESCE(work.is_internal, 0) = 0
+         GROUP BY work.id, work.title
+         ORDER BY (COALESCE(SUM(call.input_tokens), 0) + COALESCE(SUM(call.output_tokens), 0)) DESC, work.title`).map((row) => this.mapTokenUsageRow(row, {
+                workId: stringValue(row, "work_id"),
+                workTitle: stringValue(row, "work_title"),
+                firstUsedAt: row.first_used_at === null ? null : stringValue(row, "first_used_at"),
+                lastUsedAt: row.last_used_at === null ? null : stringValue(row, "last_used_at")
+            }))
+            : undefined;
+        return {
+            summary: this.mapTokenUsageRow(summary, {
+                firstUsedAt: summary.first_used_at === null || summary.first_used_at === undefined ? null : stringValue(summary, "first_used_at"),
+                lastUsedAt: summary.last_used_at === null || summary.last_used_at === undefined ? null : stringValue(summary, "last_used_at")
+            }),
+            daily,
+            ...(works ? { works } : {}),
+            timezoneOffset
+        };
+    }
+    mapTokenUsageRow(row, extra) {
+        const inputTokens = numberValue(row, "input_tokens");
+        const outputTokens = numberValue(row, "output_tokens");
+        const cachedInputTokens = numberValue(row, "cached_input_tokens");
+        const cacheEligibleInputTokens = numberValue(row, "cache_eligible_input_tokens");
+        return {
+            ...extra,
+            totalTokens: inputTokens + outputTokens,
+            inputTokens,
+            outputTokens,
+            cachedInputTokens,
+            cacheEligibleInputTokens,
+            cacheHitRate: cacheEligibleInputTokens > 0
+                ? Math.round(cachedInputTokens / cacheEligibleInputTokens * 1_000) / 10
+                : null,
+            requestCount: numberValue(row, "request_count"),
+            estimatedRequestCount: numberValue(row, "estimated_request_count")
+        };
+    }
     resetAutoRunBatch(workId) {
         this.autoRunBatches.set(workId, { claimed: 0, starting: new Set() });
     }
@@ -932,10 +1086,14 @@ export class AiManager {
         this.autoRunTimers.clear();
         this.autoRunBatches.clear();
         this.relationshipIndexDisposed = true;
+        for (const timer of this.relationshipIndexSyncTimers.values())
+            clearTimeout(timer);
+        this.relationshipIndexSyncTimers.clear();
         if (this.relationshipIndexTimer)
             clearTimeout(this.relationshipIndexTimer);
         this.relationshipIndexTimer = null;
         this.store.setAnalysisTaskQueuedHandler(null);
+        this.store.setRelationshipIndexQueuedHandler(null);
         logger.info("ai.manager.disposed");
     }
     getAutoRunBatch(workId) {
@@ -990,10 +1148,12 @@ export class AiManager {
         const providerId = id("provider");
         const encrypted = this.vault.encrypt(input.apiKey);
         const timestamp = now();
-        this.store.db.run(`INSERT INTO providers (id, work_id, name, base_url, encrypted_key, key_iv, key_tag, key_hint, status,
+        const protocol = input.protocol ?? "openai-chat-completions";
+        const baseUrl = normalizeProviderBaseUrl(input.baseUrl);
+        this.store.db.run(`INSERT INTO providers (id, work_id, name, base_url, protocol, encrypted_key, key_iv, key_tag, key_hint, status,
        connection_status, concurrency_limit, rpm_limit, max_tokens, note, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'unchecked', ?, ?, ?, ?, ?, ?)`, providerId, PLATFORM_AI_WORK_ID, input.name, normalizeBaseUrl(input.baseUrl), encrypted.encrypted, encrypted.iv, encrypted.tag, maskSecret(input.apiKey), input.status ?? "disabled", input.concurrencyLimit ?? 10, input.rpmLimit ?? 10, input.maxTokens ?? DEFAULT_MAX_TOKENS, input.note ?? "", timestamp, timestamp);
-        this.store.audit(PLATFORM_AI_WORK_ID, "provider.created", "provider", providerId, { name: input.name, baseUrl: normalizeBaseUrl(input.baseUrl) });
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'unchecked', ?, ?, ?, ?, ?, ?)`, providerId, PLATFORM_AI_WORK_ID, input.name, baseUrl, protocol, encrypted.encrypted, encrypted.iv, encrypted.tag, maskSecret(input.apiKey), input.status ?? "disabled", input.concurrencyLimit ?? 10, input.rpmLimit ?? 10, input.maxTokens ?? DEFAULT_MAX_TOKENS, input.note ?? "", timestamp, timestamp);
+        this.store.audit(PLATFORM_AI_WORK_ID, "provider.created", "provider", providerId, { name: input.name, baseUrl, protocol });
         return this.getProvider(providerId);
     }
     listProviders() {
@@ -1022,10 +1182,12 @@ export class AiManager {
             keyHint = maskSecret(input.apiKey);
             connectionStatus = "unchecked";
         }
-        if (input.baseUrl && normalizeBaseUrl(input.baseUrl) !== stringValue(row, "base_url"))
+        if (input.baseUrl && normalizeProviderBaseUrl(input.baseUrl) !== stringValue(row, "base_url"))
+            connectionStatus = "unchecked";
+        if (input.protocol && input.protocol !== providerProtocol(row))
             connectionStatus = "unchecked";
-        this.store.db.run(`UPDATE providers SET name = ?, base_url = ?, encrypted_key = ?, key_iv = ?, key_tag = ?, key_hint = ?,
-       status = ?, connection_status = ?, concurrency_limit = ?, rpm_limit = ?, max_tokens = ?, note = ?, updated_at = ? WHERE id = ?`, input.name ?? stringValue(row, "name"), input.baseUrl ? normalizeBaseUrl(input.baseUrl) : stringValue(row, "base_url"), encryptedKey, keyIv, keyTag, keyHint, input.status ?? stringValue(row, "status"), connectionStatus, input.concurrencyLimit ?? numberValue(row, "concurrency_limit"), input.rpmLimit ?? numberValue(row, "rpm_limit"), input.maxTokens ?? numberValue(row, "max_tokens"), input.note ?? stringValue(row, "note"), now(), providerId);
+        this.store.db.run(`UPDATE providers SET name = ?, base_url = ?, protocol = ?, encrypted_key = ?, key_iv = ?, key_tag = ?, key_hint = ?,
+       status = ?, connection_status = ?, concurrency_limit = ?, rpm_limit = ?, max_tokens = ?, note = ?, updated_at = ? WHERE id = ?`, input.name ?? stringValue(row, "name"), input.baseUrl ? normalizeProviderBaseUrl(input.baseUrl) : stringValue(row, "base_url"), input.protocol ?? providerProtocol(row), encryptedKey, keyIv, keyTag, keyHint, input.status ?? stringValue(row, "status"), connectionStatus, input.concurrencyLimit ?? numberValue(row, "concurrency_limit"), input.rpmLimit ?? numberValue(row, "rpm_limit"), input.maxTokens ?? numberValue(row, "max_tokens"), input.note ?? stringValue(row, "note"), now(), providerId);
         this.store.audit(PLATFORM_AI_WORK_ID, "provider.updated", "provider", providerId, {
             fields: Object.keys(input).filter((key) => key !== "apiKey"),
             keyReplaced: Boolean(input.apiKey)
@@ -1051,26 +1213,40 @@ export class AiManager {
     async testProvider(providerId) {
         const row = this.getProviderRow(providerId);
         const apiKey = this.decryptKey(row);
+        const protocol = providerProtocol(row);
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 10_000);
         const startedAt = process.hrtime.bigint();
         logger.info("ai.provider_test.started", { providerId });
         try {
-            const endpoint = `${normalizeBaseUrl(stringValue(row, "base_url"))}/models`;
-            const response = await this.outboundFetch(endpoint, {
-                headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
-                signal: controller.signal
-            });
-            if (!response.ok) {
+            let payload = null;
+            let lastFailure = "AI 供应商没有返回模型列表";
+            const endpoints = providerModelEndpoints(stringValue(row, "base_url"), protocol);
+            for (let index = 0; index < endpoints.length; index += 1) {
+                const endpoint = endpoints[index];
+                if (!endpoint)
+                    continue;
+                const response = await this.outboundFetch(endpoint, {
+                    headers: providerRequestHeaders(protocol, apiKey, "application/json"),
+                    signal: controller.signal
+                });
+                if (response.ok) {
+                    payload = (await response.json());
+                    break;
+                }
                 const message = await response.text();
-                throw new Error(`HTTP ${response.status}: ${message.slice(0, 300)}`);
+                lastFailure = `HTTP ${response.status}: ${message.slice(0, 300)}`;
+                if (response.status !== 404 || index === endpoints.length - 1)
+                    break;
             }
-            const payload = (await response.json());
+            if (!payload)
+                throw new Error(lastFailure);
             const availableModels = Array.isArray(payload.data) ? payload.data.map((item) => item.id).filter(Boolean) : [];
             const timestamp = now();
             this.store.db.run("UPDATE providers SET connection_status = 'success', last_error = NULL, last_success_at = ?, updated_at = ? WHERE id = ?", timestamp, timestamp, providerId);
             logger.info("ai.provider_test.completed", {
                 providerId,
+                protocol,
                 ok: true,
                 availableModelCount: availableModels.length,
                 durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000
@@ -1078,10 +1254,11 @@ export class AiManager {
             return { ok: true, availableModels, provider: this.getProvider(providerId) };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : "连接失败";
+            const message = error instanceof Error ? redactProviderSecret(error.message, apiKey) : "连接失败";
             this.store.db.run("UPDATE providers SET connection_status = 'failed', last_error = ?, updated_at = ? WHERE id = ?", message, now(), providerId);
             logger.warn("ai.provider_test.completed", {
                 providerId,
+                protocol,
                 ok: false,
                 durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
                 error: aiErrorForLog(error)
@@ -1192,12 +1369,226 @@ export class AiManager {
         const modelId = input.modelId ?? (defaultRow ? stringValue(defaultRow, "model_id") : undefined);
         if (modelId)
             this.resolveModel(workId, modelPurpose, modelId);
+        const relationshipScope = input.taskType === "relationship-analysis" && input.scope
+            ? input.scope
+            : null;
+        if (relationshipScope && Array.isArray(relationshipScope.relationshipSourceRefs)) {
+            this.relationshipSourcesFromRefs(workId, relationshipScope, this.store.listCharacters(workId), relationshipScope.relationshipSourceRefs);
+        }
         return this.store.createTask(workId, {
             taskType: input.taskType,
             ...(input.scope ? { scope: input.scope } : {}),
             ...(modelId ? { modelId } : {})
         });
     }
+    applyRelationshipChangePreview(taskId) {
+        const task = this.store.getTask(taskId);
+        if (task.taskType !== "relationship-analysis") {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_REQUIRED", "只有人物关系分析任务可以应用关系变更");
+        }
+        const result = this.store.getTaskStoredResult(taskId);
+        const preview = result.relationshipChangePreview && typeof result.relationshipChangePreview === "object"
+            && !Array.isArray(result.relationshipChangePreview)
+            ? result.relationshipChangePreview
+            : null;
+        if (!preview)
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_REQUIRED", "该任务没有待确认的关系变更");
+        if (preview.status !== "pending") {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_NOT_PENDING", preview.status === "applied"
+                ? "本次关系变更已经应用"
+                : "本次关系变更已经放弃");
+        }
+        if (!this.store.isTaskSourceCurrent(taskId)) {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_SOURCE_CHANGED", "分析来源已发生变化，请重新运行分析后再应用");
+        }
+        const operations = Array.isArray(preview.operations)
+            ? preview.operations.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)
+                && ["created", "updated", "deleted"].includes(String(item.action)))
+            : [];
+        if (operations.length !== Number(preview.totalCount ?? operations.length) || operations.length > 5_000) {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_INVALID", "关系变更预览数据不完整，请重新运行分析");
+        }
+        const workId = String(task.workId);
+        const relationshipInput = (snapshot) => ({
+            fromCharacterId: String(snapshot.fromCharacterId),
+            toCharacterId: String(snapshot.toCharacterId),
+            category: String(snapshot.category),
+            subtype: String(snapshot.subtype ?? ""),
+            keywords: Array.isArray(snapshot.keywords) ? snapshot.keywords.map(String) : [],
+            directed: snapshot.directed === true,
+            currentStatus: String(snapshot.currentStatus ?? "active"),
+            timeRange: snapshot.timeRange && typeof snapshot.timeRange === "object" && !Array.isArray(snapshot.timeRange)
+                ? snapshot.timeRange
+                : {},
+            confidence: Number(snapshot.confidence ?? 0.5),
+            evidence: Array.isArray(snapshot.evidence) ? snapshot.evidence : [],
+            confirmationStatus: String(snapshot.confirmationStatus ?? "pending"),
+            locked: snapshot.locked === true
+        });
+        return this.store.db.transaction(() => {
+            const currentResult = this.store.getTaskStoredResult(taskId);
+            const currentPreview = currentResult.relationshipChangePreview && typeof currentResult.relationshipChangePreview === "object"
+                && !Array.isArray(currentResult.relationshipChangePreview)
+                ? currentResult.relationshipChangePreview
+                : null;
+            if (currentPreview?.status !== "pending") {
+                throw new AppError(409, "RELATIONSHIP_PREVIEW_NOT_PENDING", currentPreview?.status === "applied"
+                    ? "本次关系变更已经应用"
+                    : "本次关系变更已经放弃");
+            }
+            for (const operation of operations) {
+                if (operation.action === "created")
+                    continue;
+                const before = operation.before;
+                const expectedVersionNo = Number(operation.expectedVersionNo ?? before?.versionNo);
+                let current;
+                try {
+                    current = this.store.getRelationship(operation.relationshipId);
+                }
+                catch {
+                    throw new AppError(409, "RELATIONSHIP_PREVIEW_STALE", "待处理的人物关系已经不存在，请重新运行分析", {
+                        relationshipId: operation.relationshipId
+                    });
+                }
+                if (String(current.workId) !== workId || !Number.isInteger(expectedVersionNo) || Number(current.versionNo) !== expectedVersionNo) {
+                    throw new AppError(409, "RELATIONSHIP_PREVIEW_STALE", "人物关系已在预览后发生变化，请重新运行分析", {
+                        relationshipId: operation.relationshipId,
+                        expectedVersionNo,
+                        actualVersionNo: Number(current.versionNo)
+                    });
+                }
+            }
+            const appliedResults = [];
+            const appliedRelationshipIds = [];
+            for (const operation of operations.filter((item) => item.action === "deleted")) {
+                const before = operation.before;
+                this.store.deleteRelationship(operation.relationshipId, Number(operation.expectedVersionNo ?? before.versionNo));
+                appliedResults.push(this.relationshipResultSnapshot(workId, "deleted", before));
+            }
+            for (const operation of operations.filter((item) => item.action === "updated")) {
+                const after = operation.after;
+                const updated = this.store.updateRelationship(operation.relationshipId, relationshipInput(after), "analysis", taskId, "应用 AI 人物关系变更预览", Number(operation.expectedVersionNo ?? operation.before?.versionNo));
+                appliedRelationshipIds.push(String(updated.id));
+                appliedResults.push(this.relationshipResultSnapshot(workId, "updated", updated));
+            }
+            for (const operation of operations.filter((item) => item.action === "created")) {
+                const created = this.store.createRelationship(workId, relationshipInput(operation.after), "analysis", taskId);
+                appliedRelationshipIds.push(String(created.id));
+                appliedResults.push(this.relationshipResultSnapshot(workId, "created", created));
+            }
+            const unchangedResults = Array.isArray(currentResult.relationshipResults)
+                ? currentResult.relationshipResults.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)
+                    && item.action === "unchanged")
+                : [];
+            const appliedAt = now();
+            const nextResult = {
+                ...currentResult,
+                relationshipIds: appliedRelationshipIds,
+                candidateCount: appliedRelationshipIds.length,
+                createdCount: operations.filter((item) => item.action === "created").length,
+                updatedCount: operations.filter((item) => item.action === "updated").length,
+                deletedCount: operations.filter((item) => item.action === "deleted").length,
+                relationshipResults: [...appliedResults, ...unchangedResults],
+                relationshipChangePreview: {
+                    ...currentPreview,
+                    status: "applied",
+                    appliedAt,
+                    appliedRelationshipIds
+                }
+            };
+            const updatedTask = this.store.updateTask(taskId, { status: String(task.status), result: nextResult });
+            this.store.audit(workId, "relationship.analysis.changes-applied", "analysis-task", taskId, {
+                createdCount: nextResult.createdCount,
+                updatedCount: nextResult.updatedCount,
+                deletedCount: nextResult.deletedCount
+            });
+            logger.info("ai.relationship_changes.applied", {
+                taskId,
+                workId,
+                createdCount: nextResult.createdCount,
+                updatedCount: nextResult.updatedCount,
+                deletedCount: nextResult.deletedCount
+            });
+            return updatedTask;
+        });
+    }
+    discardRelationshipChangePreview(taskId) {
+        const task = this.store.getTask(taskId);
+        if (task.taskType !== "relationship-analysis") {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_REQUIRED", "只有人物关系分析任务可以放弃关系变更");
+        }
+        const result = this.store.getTaskStoredResult(taskId);
+        const preview = result.relationshipChangePreview && typeof result.relationshipChangePreview === "object"
+            && !Array.isArray(result.relationshipChangePreview)
+            ? result.relationshipChangePreview
+            : null;
+        if (!preview)
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_REQUIRED", "该任务没有待确认的关系变更");
+        if (preview.status !== "pending") {
+            throw new AppError(409, "RELATIONSHIP_PREVIEW_NOT_PENDING", preview.status === "applied"
+                ? "本次关系变更已经应用"
+                : "本次关系变更已经放弃");
+        }
+        return this.store.db.transaction(() => {
+            const currentResult = this.store.getTaskStoredResult(taskId);
+            const currentPreview = currentResult.relationshipChangePreview && typeof currentResult.relationshipChangePreview === "object"
+                && !Array.isArray(currentResult.relationshipChangePreview)
+                ? currentResult.relationshipChangePreview
+                : null;
+            if (currentPreview?.status !== "pending") {
+                throw new AppError(409, "RELATIONSHIP_PREVIEW_NOT_PENDING", currentPreview?.status === "applied"
+                    ? "本次关系变更已经应用"
+                    : "本次关系变更已经放弃");
+            }
+            const discardedAt = now();
+            const updatedTask = this.store.updateTask(taskId, {
+                status: String(task.status),
+                result: {
+                    ...currentResult,
+                    relationshipChangePreview: { ...currentPreview, status: "discarded", discardedAt }
+                }
+            });
+            this.store.audit(String(task.workId), "relationship.analysis.changes-discarded", "analysis-task", taskId, {
+                changeCount: Number(currentPreview.totalCount ?? 0)
+            });
+            logger.info("ai.relationship_changes.discarded", {
+                taskId,
+                workId: task.workId,
+                changeCount: Number(currentPreview.totalCount ?? 0)
+            });
+            return updatedTask;
+        });
+    }
+    rerunTask(taskId) {
+        const original = this.store.getTask(taskId);
+        const rerunnableStatuses = new Set(["review", "completed", "partial", "expired", "cancelled"]);
+        if (!rerunnableStatuses.has(String(original.status))) {
+            throw new AppError(409, "TASK_NOT_RERUNNABLE", "只有已结束的分析任务可以按原配置重跑");
+        }
+        const originalScope = original.scope && typeof original.scope === "object" && !Array.isArray(original.scope)
+            ? original.scope
+            : {};
+        const { targetCharacters: _targetCharacters, relationshipSourceRefs: _relationshipSourceRefs, ...scope } = originalScope;
+        const originalModel = original.model && typeof original.model === "object" && !Array.isArray(original.model)
+            ? original.model
+            : null;
+        const modelId = typeof originalModel?.id === "string" ? originalModel.id : undefined;
+        if (modelId)
+            this.resolveModel(String(original.workId), this.analysisTaskModelPurpose(String(original.taskType)), modelId);
+        const rerun = this.store.createTask(String(original.workId), {
+            taskType: String(original.taskType),
+            scope,
+            ...(modelId ? { modelId } : {}),
+            rerunOfTaskId: taskId
+        });
+        logger.info("ai.task.rerun_created", {
+            taskId: rerun.id,
+            originalTaskId: taskId,
+            workId: original.workId,
+            taskType: original.taskType
+        });
+        return { ...rerun, rerunOfTaskId: taskId };
+    }
     async createSuggestion(input) {
         const action = input.taskType === "continue" ? "append" : input.taskType === "polish" ? "replace-selection" : "note";
         if (action === "replace-selection" && !input.scope.selection) {
@@ -1572,7 +1963,10 @@ export class AiManager {
             if (this.store.getTask(taskId).status !== "running")
                 return this.store.getTask(taskId);
             const message = error instanceof Error ? error.message : "分析失败";
-            this.store.updateTask(taskId, { status: "partial", progress: 100, failures: [{ message }] });
+            const failure = error instanceof AppError
+                ? { message, code: error.code, ...(error.details === undefined ? {} : { details: error.details }) }
+                : { message };
+            this.store.updateTask(taskId, { status: "partial", progress: 100, failures: [failure] });
             logger.error("ai.task.failed", { taskId, workId, durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000, error: aiErrorForLog(error) });
             throw error;
         }
@@ -2028,22 +2422,43 @@ export class AiManager {
             this.store.db.run("UPDATE ai_call_traces SET rounds_json = ?, source_refs_json = ?, updated_at = ? WHERE call_id = ?", JSON.stringify(traceRounds), JSON.stringify(taskTraceSourceRefs(messages, traceRounds)), now(), callId);
         };
         const callStartedAt = process.hrtime.bigint();
+        const protocol = providerProtocol(provider);
         logger.info("ai.call.started", {
             callId,
             workId: input.workId,
             taskType: input.taskType,
             providerId: stringValue(provider, "id"),
             modelId: stringValue(model, "id"),
+            protocol,
             streaming: false,
             contextChars: context.length,
             instructionChars: input.instruction.length,
             toolCount: tools.length
         });
         let activeApiKey = "";
+        let trackedInputTokens = 0;
+        let trackedOutputTokens = 0;
+        let trackedCachedInputTokens = 0;
+        let trackedCacheEligibleInputTokens = 0;
+        const trackedUsageSources = new Set();
+        const trackUsage = (usage) => {
+            trackedInputTokens += usage.inputTokens;
+            trackedOutputTokens += usage.outputTokens;
+            trackedCachedInputTokens += usage.cachedInputTokens;
+            trackedCacheEligibleInputTokens += usage.cacheEligibleInputTokens;
+            trackedUsageSources.add(usage.source);
+        };
+        const trackedUsageSource = () => {
+            if (trackedUsageSources.size === 1 && trackedUsageSources.has("reported"))
+                return "reported";
+            if (trackedUsageSources.size === 1 && trackedUsageSources.has("estimated"))
+                return "estimated";
+            return "mixed";
+        };
         try {
             const apiKey = this.decryptKey(provider);
             activeApiKey = apiKey;
-            const endpoint = `${normalizeBaseUrl(stringValue(provider, "base_url"))}/chat/completions`;
+            const endpoint = providerCompletionEndpoint(stringValue(provider, "base_url"), protocol);
             const timeoutMs = input.taskType === "book-analysis" || input.taskType === "relationship-analysis" ? 300_000 : 60_000;
             const maximumAttempts = Math.round(clamp(input.maxAttempts ?? 3, 1, 5));
             let completionRequestCount = 0;
@@ -2090,13 +2505,15 @@ export class AiManager {
                             try {
                                 const response = await this.outboundFetch(endpoint, {
                                     method: "POST",
-                                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", Accept: "application/json" },
-                                    body: JSON.stringify({
+                                    headers: providerRequestHeaders(protocol, apiKey, "application/json"),
+                                    body: JSON.stringify(buildCompletionRequestBody({
+                                        protocol,
                                         model: stringValue(model, "model_id"),
                                         messages: completionMessages,
-                                        ...parameters,
-                                        ...(tools.length && toolChoice === "auto" ? { tools, tool_choice: "auto" } : {})
-                                    }),
+                                        parameters,
+                                        tools,
+                                        toolChoice
+                                    })),
                                     signal: controller.signal
                                 });
                                 return { ok: response.ok, status: response.status, body: await response.text() };
@@ -2115,7 +2532,7 @@ export class AiManager {
                         });
                         if (candidate.ok) {
                             try {
-                                const parsed = redactProviderSecrets(JSON.parse(candidate.body), apiKey);
+                                const parsed = parseCompletionPayload(protocol, redactProviderSecrets(JSON.parse(candidate.body), apiKey));
                                 traceAttempt.completedAt = now();
                                 traceAttempt.status = "completed";
                                 traceAttempt.httpStatus = candidate.status;
@@ -2129,10 +2546,12 @@ export class AiManager {
                                     totalInputTokens += cacheUsage.inputTokens;
                                     totalCachedInputTokens += cacheUsage.cachedInputTokens;
                                 }
+                                const outputText = completionPayloadOutputText(parsed);
+                                trackUsage(resolveAiTokenUsage(parsed.usage, estimateAiTokens(JSON.stringify(completionMessages)), outputText ? estimateAiTokens(outputText) : 0));
                                 return parsed;
                             }
                             catch {
-                                throw new Error(`Chat Completions returned invalid JSON: ${candidate.body.slice(0, 500)}`);
+                                throw new Error(`${protocol === "anthropic-messages" ? "Anthropic Messages" : "Chat Completions"} returned invalid JSON: ${candidate.body.slice(0, 500)}`);
                             }
                         }
                         lastFailure = new Error(`HTTP ${candidate.status}: ${candidate.body.slice(0, 500)}`);
@@ -2211,7 +2630,8 @@ export class AiManager {
                     role: "assistant",
                     content: choice.message.content ?? null,
                     reasoning_content: choice.message.reasoning_content ?? null,
-                    tool_calls: normalizedToolCalls
+                    tool_calls: normalizedToolCalls,
+                    ...(choice.message.anthropic_content?.length ? { anthropic_content: choice.message.anthropic_content } : {})
                 });
                 for (const toolCall of toolCalls) {
                     const execution = this.executeAgentTool(input.workId, toolCall);
@@ -2244,13 +2664,17 @@ export class AiManager {
                 const suffix = choice?.finish_reason === "length" || reasoningLength > 0
                     ? `；模型已生成 ${reasoningLength} 个推理字符，请提高 max_tokens 输出预算`
                     : "";
-                throw new Error(`Chat Completions 响应缺少可用正文，finish_reason=${choice?.finish_reason ?? "unknown"}${suffix}`);
+                throw new Error(`${protocol === "anthropic-messages" ? "Anthropic Messages" : "Chat Completions"} 响应缺少可用正文，finish_reason=${choice?.finish_reason ?? "unknown"}${suffix}`);
             }
-            this.store.db.run("UPDATE ai_calls SET status = 'completed', output_chars = ?, completed_at = ? WHERE id = ?", content.length, now(), callId);
             const outputTokens = resolveOutputTokens(payload.usage, content);
             const cacheHitPercent = cacheUsageComplete && completionRequestCount > 0 && totalInputTokens > 0
                 ? Math.round(totalCachedInputTokens / totalInputTokens * 1_000) / 10
                 : undefined;
+            this.store.db.run(`UPDATE ai_calls
+         SET status = 'completed', output_chars = ?, input_tokens = ?, output_tokens = ?,
+             cached_input_tokens = ?, cache_eligible_input_tokens = ?, cache_usage_available = ?,
+             token_usage_source = ?, completed_at = ?
+         WHERE id = ?`, content.length, trackedInputTokens, trackedOutputTokens, trackedCachedInputTokens, trackedCacheEligibleInputTokens, trackedCacheEligibleInputTokens > 0 ? 1 : 0, trackedUsageSource(), now(), callId);
             logger.info("ai.call.completed", {
                 callId,
                 workId: input.workId,
@@ -2265,7 +2689,11 @@ export class AiManager {
         }
         catch (error) {
             const message = error instanceof Error ? redactProviderSecret(error.message, activeApiKey) : "AI 调用失败";
-            this.store.db.run("UPDATE ai_calls SET status = 'failed', failure = ?, completed_at = ? WHERE id = ?", message, now(), callId);
+            this.store.db.run(`UPDATE ai_calls
+         SET status = 'failed', failure = ?, input_tokens = ?, output_tokens = ?,
+             cached_input_tokens = ?, cache_eligible_input_tokens = ?, cache_usage_available = ?,
+             token_usage_source = ?, completed_at = ?
+         WHERE id = ?`, message, trackedInputTokens, trackedOutputTokens, trackedCachedInputTokens, trackedCacheEligibleInputTokens, trackedCacheEligibleInputTokens > 0 ? 1 : 0, trackedUsageSource(), now(), callId);
             logger.error("ai.call.failed", {
                 callId,
                 workId: input.workId,
@@ -2290,19 +2718,23 @@ export class AiManager {
         this.store.db.run(`INSERT INTO ai_calls (id, work_id, task_type, provider_id, model_id, context_scope_json, parameters_json,
        status, input_chars, created_at, created_by_user_id) VALUES (?, ?, ?, ?, ?, ?, ?, 'running', ?, ?, ?)`, callId, input.workId, input.taskType, stringValue(provider, "id"), stringValue(model, "id"), JSON.stringify(input.scope), JSON.stringify(parameters), context.length + input.instruction.length, now(), currentRequestActor()?.userId ?? null);
         const callStartedAt = process.hrtime.bigint();
+        const protocol = providerProtocol(provider);
         logger.info("ai.call.started", {
             callId,
             workId: input.workId,
             taskType: input.taskType,
             providerId: stringValue(provider, "id"),
             modelId: stringValue(model, "id"),
+            protocol,
             streaming: true,
             contextChars: context.length,
             instructionChars: input.instruction.length
         });
+        let activeApiKey = "";
         try {
             const apiKey = this.decryptKey(provider);
-            const endpoint = `${normalizeBaseUrl(stringValue(provider, "base_url"))}/chat/completions`;
+            activeApiKey = apiKey;
+            const endpoint = providerCompletionEndpoint(stringValue(provider, "base_url"), protocol);
             const maximumAttempts = Math.round(clamp(input.maxAttempts ?? 3, 1, 5));
             let streamedResult = null;
             let lastFailure = null;
@@ -2324,13 +2756,19 @@ export class AiManager {
                         try {
                             const response = await this.outboundFetch(endpoint, {
                                 method: "POST",
-                                headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", Accept: "text/event-stream" },
-                                body: JSON.stringify({ model: stringValue(model, "model_id"), messages, ...parameters, stream: true, stream_options: { include_usage: true } }),
+                                headers: providerRequestHeaders(protocol, apiKey, "text/event-stream"),
+                                body: JSON.stringify(buildCompletionRequestBody({
+                                    protocol,
+                                    model: stringValue(model, "model_id"),
+                                    messages,
+                                    parameters,
+                                    stream: true
+                                })),
                                 signal: controller.signal
                             });
                             if (!response.ok)
                                 return { ok: false, status: response.status, body: await response.text() };
-                            const streamed = await this.readCompletionStream(response, (delta) => {
+                            const streamed = await this.readCompletionStream(response, protocol, estimateAiTokens(JSON.stringify(messages)), (delta) => {
                                 emitted = true;
                                 onDelta(delta);
                             }, (delta) => {
@@ -2378,11 +2816,15 @@ export class AiManager {
             }
             if (streamedResult === null)
                 throw lastFailure instanceof Error ? lastFailure : new Error("AI 流式请求重试后仍未返回响应");
-            const { content, reasoning, outputTokens, cacheHitPercent } = streamedResult;
+            const { content, reasoning, outputTokens, cacheHitPercent, tokenUsage } = streamedResult;
             const processSteps = reasoning.trim()
                 ? [{ id: thinkingStepId, type: "thinking", round: 1, content: reasoning, createdAt: thinkingCreatedAt }]
                 : [];
-            this.store.db.run("UPDATE ai_calls SET status = 'completed', output_chars = ?, completed_at = ? WHERE id = ?", content.length, now(), callId);
+            this.store.db.run(`UPDATE ai_calls
+         SET status = 'completed', output_chars = ?, input_tokens = ?, output_tokens = ?,
+             cached_input_tokens = ?, cache_eligible_input_tokens = ?, cache_usage_available = ?,
+             token_usage_source = ?, completed_at = ?
+         WHERE id = ?`, content.length, tokenUsage.inputTokens, tokenUsage.outputTokens, tokenUsage.cachedInputTokens, tokenUsage.cacheEligibleInputTokens, tokenUsage.cacheEligibleInputTokens > 0 ? 1 : 0, tokenUsage.source, now(), callId);
             logger.info("ai.call.completed", {
                 callId,
                 workId: input.workId,
@@ -2395,7 +2837,7 @@ export class AiManager {
             return { callId, content, outputTokens, ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }), provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: [], processSteps };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : "AI 流式调用失败";
+            const message = error instanceof Error ? redactProviderSecret(error.message, activeApiKey) : "AI 流式调用失败";
             this.store.db.run("UPDATE ai_calls SET status = 'failed', failure = ?, completed_at = ? WHERE id = ?", message, now(), callId);
             logger.error("ai.call.failed", {
                 callId,
@@ -2408,9 +2850,10 @@ export class AiManager {
             throw new AppError(502, "AI_CALL_FAILED", "AI 调用失败", { callId, failure: message });
         }
     }
-    async readCompletionStream(response, onDelta, onThinkingDelta) {
+    async readCompletionStream(response, protocol, estimatedInputTokens, onDelta, onThinkingDelta) {
+        const protocolLabel = protocol === "anthropic-messages" ? "Anthropic Messages" : "Chat Completions";
         if (!response.body)
-            throw new Error("Chat Completions 流式响应缺少正文");
+            throw new Error(`${protocolLabel} 流式响应缺少正文`);
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
@@ -2427,19 +2870,59 @@ export class AiManager {
             if (!data || data === "[DONE]")
                 return;
             const payload = JSON.parse(data);
-            if (payload.error)
-                throw new Error(payload.error.message || "上游流式响应返回错误");
-            if (payload.usage)
-                usage = payload.usage;
-            const choice = payload.choices?.[0];
-            if (choice?.finish_reason)
+            const error = payload.error && typeof payload.error === "object" && !Array.isArray(payload.error)
+                ? payload.error
+                : null;
+            if (error)
+                throw new Error(typeof error.message === "string" ? error.message : "上游流式响应返回错误");
+            if (protocol === "anthropic-messages") {
+                const eventUsage = payload.usage && typeof payload.usage === "object" && !Array.isArray(payload.usage)
+                    ? payload.usage
+                    : null;
+                const message = payload.message && typeof payload.message === "object" && !Array.isArray(payload.message)
+                    ? payload.message
+                    : null;
+                const messageUsage = message?.usage && typeof message.usage === "object" && !Array.isArray(message.usage)
+                    ? message.usage
+                    : null;
+                if (eventUsage || messageUsage) {
+                    usage = { ...(usage && typeof usage === "object" ? usage : {}), ...(messageUsage ?? {}), ...(eventUsage ?? {}) };
+                }
+                const eventDelta = payload.delta && typeof payload.delta === "object" && !Array.isArray(payload.delta)
+                    ? payload.delta
+                    : {};
+                if (typeof eventDelta.stop_reason === "string")
+                    finishReason = eventDelta.stop_reason;
+                if (eventDelta.type === "thinking_delta" && typeof eventDelta.thinking === "string" && eventDelta.thinking.length > 0) {
+                    reasoning += eventDelta.thinking;
+                    onThinkingDelta(eventDelta.thinking);
+                }
+                if (eventDelta.type === "text_delta" && typeof eventDelta.text === "string" && eventDelta.text.length > 0) {
+                    content += eventDelta.text;
+                    onDelta(eventDelta.text);
+                }
+                return;
+            }
+            const streamUsage = payload.usage && typeof payload.usage === "object" && !Array.isArray(payload.usage)
+                ? payload.usage
+                : null;
+            if (streamUsage)
+                usage = streamUsage;
+            const choices = Array.isArray(payload.choices) ? payload.choices : [];
+            const choice = choices[0] && typeof choices[0] === "object" && !Array.isArray(choices[0])
+                ? choices[0]
+                : null;
+            if (typeof choice?.finish_reason === "string")
                 finishReason = choice.finish_reason;
-            const thinkingDelta = choice?.delta?.reasoning_content;
+            const deltaRecord = choice?.delta && typeof choice.delta === "object" && !Array.isArray(choice.delta)
+                ? choice.delta
+                : {};
+            const thinkingDelta = deltaRecord.reasoning_content;
             if (typeof thinkingDelta === "string" && thinkingDelta.length > 0) {
                 reasoning += thinkingDelta;
                 onThinkingDelta(thinkingDelta);
             }
-            const delta = choice?.delta?.content;
+            const delta = deltaRecord.content;
             if (typeof delta === "string" && delta.length > 0) {
                 content += delta;
                 onDelta(delta);
@@ -2458,9 +2941,16 @@ export class AiManager {
         if (buffer.trim())
             consumeEvent(buffer);
         if (!content.trim())
-            throw new Error(`Chat Completions 流式响应缺少可用正文，finish_reason=${finishReason}`);
+            throw new Error(`${protocolLabel} 流式响应缺少可用正文，finish_reason=${finishReason}`);
         const cacheHitPercent = resolveCacheHitPercent(usage);
-        return { content, reasoning, outputTokens: resolveOutputTokens(usage, content), ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }) };
+        const outputTokens = resolveOutputTokens(usage, content);
+        return {
+            content,
+            reasoning,
+            outputTokens,
+            ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }),
+            tokenUsage: resolveAiTokenUsage(usage, estimatedInputTokens, outputTokens)
+        };
     }
     async runChapterAnalysis(workId, scope, modelId, taskId) {
         if (!scope.chapterId)
@@ -3356,6 +3846,104 @@ export class AiManager {
         const workIds = this.store.db.all("SELECT DISTINCT work_id FROM relationship_source_index_queue ORDER BY work_id").map((row) => String(row.work_id));
         await Promise.allSettled(workIds.map((workId) => this.ensureRelationshipSearchIndex(workId)));
     }
+    scheduleRelationshipIndexSync(workId) {
+        if (this.relationshipIndexDisposed)
+            return;
+        const existing = this.relationshipIndexSyncTimers.get(workId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.relationshipIndexSyncTimers.delete(workId);
+            try {
+                const status = this.getRelationshipSearchIndexStatus(workId);
+                if (Number(status.queuedSourceCount ?? 0) > 0) {
+                    void this.ensureRelationshipSearchIndex(workId).catch(() => undefined);
+                }
+            }
+            catch {
+                // 作品可能已在等待期间被删除
+            }
+        }, 2_000);
+        this.relationshipIndexSyncTimers.set(workId, timer);
+        logger.debug("relationship.search_index.auto_sync_scheduled", { workId });
+    }
+    getRelationshipSearchIndexStatus(workId) {
+        this.store.getWork(workId);
+        const row = this.store.db.get("SELECT status, generation, error, updated_at FROM relationship_source_index_state WHERE work_id = ?", workId);
+        const queuedSources = this.store.db.all(`SELECT source_type, COUNT(*) AS count, MIN(queued_at) AS oldest_queued_at
+       FROM relationship_source_index_queue WHERE work_id = ?
+       GROUP BY source_type ORDER BY source_type`, workId).map((item) => ({
+            sourceType: String(item.source_type),
+            count: Number(item.count ?? 0),
+            oldestQueuedAt: String(item.oldest_queued_at ?? "")
+        }));
+        const queuedSourceCount = queuedSources.reduce((total, item) => total + item.count, 0);
+        const storedStatus = String(row?.status ?? "");
+        const status = storedStatus === "building"
+            ? "building"
+            : queuedSourceCount > 0
+                ? "queued"
+                : storedStatus || "ready";
+        return {
+            workId,
+            status,
+            generation: Number(row?.generation ?? 0),
+            queuedSourceCount,
+            queuedSources,
+            indexedSourceCount: Number(this.store.db.get("SELECT COUNT(*) AS count FROM relationship_source_search WHERE work_id = ?", workId)?.count ?? 0),
+            indexedParagraphCount: Number(this.store.db.get(`SELECT COUNT(*) AS count FROM chapter_paragraph_pinyin_fts pinyin
+         JOIN chapter_paragraph_search paragraph ON paragraph.id = pinyin.rowid
+         WHERE paragraph.work_id = ?`, workId)?.count ?? 0),
+            error: String(row?.error ?? ""),
+            updatedAt: String(row?.updated_at ?? "")
+        };
+    }
+    syncRelationshipSearchIndex(workId) {
+        const status = this.getRelationshipSearchIndexStatus(workId);
+        if (Number(status.queuedSourceCount ?? 0) > 0 || status.status === "building") {
+            void this.ensureRelationshipSearchIndex(workId).catch(() => undefined);
+        }
+        return status;
+    }
+    rebuildRelationshipSearchIndex(workId) {
+        this.store.getWork(workId);
+        const timestamp = now();
+        const queueSources = [
+            { table: "works", sourceType: "work", idColumn: "id" },
+            { table: "chapters", sourceType: "chapter", idColumn: "id" },
+            { table: "settings", sourceType: "setting", idColumn: "id" },
+            { table: "characters", sourceType: "character", idColumn: "id" },
+            { table: "races", sourceType: "race", idColumn: "id" },
+            { table: "organizations", sourceType: "organization", idColumn: "id" },
+            { table: "timeline_tracks", sourceType: "timeline-track", idColumn: "id" },
+            { table: "timeline_events", sourceType: "timeline-event", idColumn: "id" },
+            { table: "relationships", sourceType: "relationship", idColumn: "id" },
+            { table: "foreshadows", sourceType: "foreshadow", idColumn: "id" },
+            { table: "review_items", sourceType: "review", idColumn: "id" }
+        ];
+        this.store.db.transaction(() => {
+            this.store.db.run(`INSERT INTO relationship_source_index_queue(work_id, source_type, source_id, queued_at)
+         SELECT work_id, source_type, source_id, ? FROM relationship_source_search WHERE work_id = ?
+         ON CONFLICT(work_id, source_type, source_id) DO UPDATE SET queued_at = excluded.queued_at`, timestamp, workId);
+            for (const source of queueSources) {
+                const workColumn = source.table === "works" ? "id" : "work_id";
+                this.store.db.run(`INSERT INTO relationship_source_index_queue(work_id, source_type, source_id, queued_at)
+           SELECT ${workColumn}, ?, ${source.idColumn}, ? FROM ${source.table} WHERE ${workColumn} = ?
+           ON CONFLICT(work_id, source_type, source_id) DO UPDATE SET queued_at = excluded.queued_at`, source.sourceType, timestamp, workId);
+            }
+            this.store.db.run(`INSERT INTO relationship_source_index_queue(work_id, source_type, source_id, queued_at)
+         SELECT chapter.work_id, 'chapter-outline', outline.chapter_id, ?
+         FROM chapter_outlines outline JOIN chapters chapter ON chapter.id = outline.chapter_id
+         WHERE chapter.work_id = ?
+         ON CONFLICT(work_id, source_type, source_id) DO UPDATE SET queued_at = excluded.queued_at`, timestamp, workId);
+            this.store.db.run(`INSERT INTO relationship_source_index_state(work_id, status, generation, error, updated_at)
+         VALUES (?, 'queued', 0, '', ?)
+         ON CONFLICT(work_id) DO UPDATE SET status = 'queued', error = '', updated_at = excluded.updated_at`, workId, timestamp);
+        });
+        const status = this.getRelationshipSearchIndexStatus(workId);
+        void this.ensureRelationshipSearchIndex(workId).catch(() => undefined);
+        return status;
+    }
     ensureRelationshipSearchIndex(workId) {
         const existing = this.relationshipIndexBuilds.get(workId);
         if (existing)
@@ -3533,7 +4121,6 @@ export class AiManager {
     }
     relationshipFuzzyIndexMatches(workId, reference, includeSettings, scope) {
         const result = new Set();
-        const characterTokens = [...new Set(relationshipCharacterTokens(reference))];
         const pinyinTokens = [...new Set(relationshipPinyinTokens(reference))];
         const score = new Map();
         const add = (key) => {
@@ -3577,45 +4164,57 @@ export class AiManager {
                 result.add(this.relationshipIndexedSourceKey(String(row.source_type), String(row.source_id)));
         }
         const normalizedCharacters = [...normalizeRelationshipSearchText(reference).trim()];
-        if (includeChapters) {
-            for (const character of [...new Set(normalizedCharacters)]) {
+        const addSelectiveSignal = (keys) => {
+            if (keys.size > RELATIONSHIP_MAX_FUZZY_SOURCES)
+                return;
+            for (const key of keys)
+                add(key);
+        };
+        for (const character of [...new Set(normalizedCharacters)]) {
+            const keys = new Set();
+            if (includeChapters) {
                 for (const row of this.store.db.all(`SELECT DISTINCT paragraph.chapter_id FROM chapter_paragraph_short_terms term
            JOIN chapter_paragraph_search paragraph ON paragraph.id = term.paragraph_id
            WHERE paragraph.work_id = ? AND term.term = ? ${chapterScope.sql}
            LIMIT 201`, workId, character, ...chapterScope.params))
-                    add(this.relationshipIndexedSourceKey("chapter", String(row.chapter_id)));
-            }
-            for (const token of pinyinTokens) {
-                for (const row of this.store.db.all(`SELECT DISTINCT paragraph.chapter_id FROM chapter_paragraph_pinyin_fts
-           JOIN chapter_paragraph_search paragraph ON paragraph.id = chapter_paragraph_pinyin_fts.rowid
-           WHERE paragraph.work_id = ? AND chapter_paragraph_pinyin_fts MATCH ? ${chapterScope.sql}
-           LIMIT 201`, workId, token, ...chapterScope.params))
-                    add(this.relationshipIndexedSourceKey("chapter", String(row.chapter_id)));
+                    keys.add(this.relationshipIndexedSourceKey("chapter", String(row.chapter_id)));
             }
-        }
-        if (includeSettings) {
-            for (const token of characterTokens) {
-                for (const row of this.store.db.all(`SELECT source.source_type, source.source_id FROM relationship_source_exact_fts
+            if (includeSettings) {
+                const token = relationshipCharacterTokens(character)[0];
+                if (token)
+                    for (const row of this.store.db.all(`SELECT source.source_type, source.source_id FROM relationship_source_exact_fts
            JOIN relationship_source_search source ON source.id = relationship_source_exact_fts.rowid
            WHERE source.work_id = ? AND relationship_source_exact_fts MATCH ?
-           AND NOT (source.source_type = 'review' AND EXISTS (
+             AND NOT (source.source_type = 'review' AND EXISTS (
                SELECT 1 FROM review_items review
                WHERE review.id = source.source_id AND review.item_type = 'character-name-variant'
              ))
            LIMIT 201`, workId, token))
-                    add(this.relationshipIndexedSourceKey(String(row.source_type), String(row.source_id)));
+                        keys.add(this.relationshipIndexedSourceKey(String(row.source_type), String(row.source_id)));
+            }
+            addSelectiveSignal(keys);
+        }
+        for (const token of pinyinTokens) {
+            const keys = new Set();
+            if (includeChapters) {
+                for (const row of this.store.db.all(`SELECT DISTINCT paragraph.chapter_id FROM chapter_paragraph_pinyin_fts
+           JOIN chapter_paragraph_search paragraph ON paragraph.id = chapter_paragraph_pinyin_fts.rowid
+           WHERE paragraph.work_id = ? AND chapter_paragraph_pinyin_fts MATCH ? ${chapterScope.sql}
+           LIMIT 201`, workId, token, ...chapterScope.params))
+                    keys.add(this.relationshipIndexedSourceKey("chapter", String(row.chapter_id)));
             }
-            for (const token of pinyinTokens) {
+            if (includeSettings) {
                 for (const row of this.store.db.all(`SELECT source.source_type, source.source_id FROM relationship_source_pinyin_fts
            JOIN relationship_source_search source ON source.id = relationship_source_pinyin_fts.rowid
            WHERE source.work_id = ? AND relationship_source_pinyin_fts MATCH ?
-           AND NOT (source.source_type = 'review' AND EXISTS (
+             AND NOT (source.source_type = 'review' AND EXISTS (
                SELECT 1 FROM review_items review
                WHERE review.id = source.source_id AND review.item_type = 'character-name-variant'
              ))
            LIMIT 201`, workId, token))
-                    add(this.relationshipIndexedSourceKey(String(row.source_type), String(row.source_id)));
+                    keys.add(this.relationshipIndexedSourceKey(String(row.source_type), String(row.source_id)));
             }
+            addSelectiveSignal(keys);
         }
         const threshold = Math.max(1, [...normalizeRelationshipSearchText(reference).trim()].length - 1);
         for (const [key, count] of score)
@@ -3636,6 +4235,7 @@ export class AiManager {
             String(character.code ?? ""),
             String(character.species ?? ""),
             String(character.race?.name ?? ""),
+            String(character.attributes?.identity ?? ""),
             ...(Array.isArray(character.organizations) ? character.organizations.map((item) => String(item.name ?? "")) : []),
             ...[...relatedIds].flatMap((relatedId) => {
                 try {
@@ -3685,16 +4285,19 @@ export class AiManager {
             for (const character of targetCharacters) {
                 const targetCharacterId = String(character.id);
                 const exactReferences = [...new Set([String(character.name), ...character.aliases].map((item) => item.trim()).filter(Boolean))];
-                const fuzzyReferenceCount = exactReferences.filter((reference) => [...normalizeRelationshipSearchText(reference).trim()].length >= 2).length;
+                const anchors = this.relationshipIdentityAnchors(workId, character);
+                const fuzzyReferenceCount = exactReferences.filter(isRelationshipPhoneticReference).length;
                 if (fuzzyReferenceCount > RELATIONSHIP_MAX_FUZZY_REFERENCES) {
-                    throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "人物名称和别名过多，无法在安全预算内完成疑似写法匹配", {
+                    throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage("人物名称和别名过多，无法在安全预算内完成疑似写法匹配"), {
                         characterId: targetCharacterId,
+                        targetName: String(character.name),
+                        reason: "registered-references",
                         fuzzyReferenceCount,
-                        maximumFuzzyReferences: RELATIONSHIP_MAX_FUZZY_REFERENCES
+                        maximumFuzzyReferences: RELATIONSHIP_MAX_FUZZY_REFERENCES,
+                        identityAnchorCount: anchors.length
                     });
                 }
                 const normalizedExactReferences = new Set(exactReferences.map((item) => normalizeRelationshipSearchText(item).trim()));
-                const anchors = this.relationshipIdentityAnchors(workId, character);
                 const anchorKeys = new Set();
                 for (const anchor of anchors) {
                     for (const chapterId of this.relationshipChapterExactMatches(workId, anchor)) {
@@ -3717,24 +4320,35 @@ export class AiManager {
                     if (includeSettings)
                         for (const key of this.relationshipSettingExactMatches(workId, reference))
                             exactKeys.add(key);
+                    if (!isRelationshipPhoneticReference(reference))
+                        continue;
                     const referenceLength = [...normalizeRelationshipSearchText(reference).trim()].length;
                     if (referenceLength < 2)
                         continue;
-                    const fuzzyIndexKeys = referenceLength === 2
+                    const rawFuzzyIndexKeys = referenceLength === 2
                         ? anchorKeys
                         : this.relationshipFuzzyIndexMatches(workId, reference, includeSettings, scope);
+                    const fuzzyIndexKeys = rawFuzzyIndexKeys.size > RELATIONSHIP_MAX_FUZZY_SOURCES && anchorKeys.size > 0
+                        ? new Set([...rawFuzzyIndexKeys].filter((key) => anchorKeys.has(key)))
+                        : rawFuzzyIndexKeys;
                     for (const key of fuzzyIndexKeys) {
                         const ref = this.relationshipIndexedSourceRef(key);
                         if (ref.sourceType === "chapter" && !allowedChapterIds.has(ref.sourceId))
                             continue;
                         if (ref.sourceType !== "chapter" && !includeSettings)
                             continue;
+                        if (exactKeys.has(key))
+                            continue;
                         targetIndexCandidateKeys.add(key);
                         if (targetIndexCandidateKeys.size > RELATIONSHIP_MAX_FUZZY_SOURCES) {
-                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "疑似人物名来源过多，请补充人物别名或身份资料后重试", {
+                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage(`“${String(character.name)}”的拼音疑似来源仍然过多`), {
                                 characterId: targetCharacterId,
+                                targetName: String(character.name),
+                                reference,
+                                reason: "candidate-sources",
                                 candidateCount: targetIndexCandidateKeys.size,
-                                maximum: RELATIONSHIP_MAX_FUZZY_SOURCES
+                                maximum: RELATIONSHIP_MAX_FUZZY_SOURCES,
+                                identityAnchorCount: anchors.length
                             });
                         }
                         let indexed = loadedSources.get(key);
@@ -3751,10 +4365,14 @@ export class AiManager {
                         const normalizedSearchable = normalizeRelationshipSearchText(searchable);
                         fuzzyScanCharacters += normalizedSearchable.length;
                         if (fuzzyScanCharacters > RELATIONSHIP_MAX_FUZZY_SCAN_CHARACTERS) {
-                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "疑似人物名待核对文本过多，请缩小分析范围或补充人物别名", {
+                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage(`“${String(character.name)}”的拼音疑似来源待核对文本过多`), {
                                 characterId: targetCharacterId,
+                                targetName: String(character.name),
+                                reference,
+                                reason: "scan-characters",
                                 scannedCharacters: fuzzyScanCharacters,
-                                maximumScannedCharacters: RELATIONSHIP_MAX_FUZZY_SCAN_CHARACTERS
+                                maximumScannedCharacters: RELATIONSHIP_MAX_FUZZY_SCAN_CHARACTERS,
+                                identityAnchorCount: anchors.length
                             });
                         }
                         const referenceCharacters = [...normalizeRelationshipSearchText(reference).trim()];
@@ -3765,11 +4383,15 @@ export class AiManager {
                         catch (error) {
                             if (!(error instanceof RelationshipApproximateMatchLimitError))
                                 throw error;
-                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "单个来源中的疑似人物名写法过多，请缩小分析范围或补充人物别名", {
+                            throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage(`单个来源中“${String(character.name)}”的拼音疑似写法过多`), {
                                 characterId: targetCharacterId,
+                                targetName: String(character.name),
+                                reference,
+                                reason: "source-matches",
                                 sourceType: indexed.sourceType,
                                 sourceId: indexed.sourceId,
-                                maximumSourceMatches: error.maximumCandidates
+                                maximumSourceMatches: error.maximumCandidates,
+                                identityAnchorCount: anchors.length
                             });
                         }
                         for (const match of approximateMatches) {
@@ -3789,10 +4411,14 @@ export class AiManager {
                             candidateOccurrences.set(occurrenceKey, occurrenceCount + 1);
                             fuzzyMatchCount += 1;
                             if (fuzzyMatchCount > RELATIONSHIP_MAX_FUZZY_MATCHES) {
-                                throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "疑似人物名写法过多，请缩小分析范围或补充人物别名", {
+                                throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage(`“${String(character.name)}”的拼音疑似写法仍然过多`), {
                                     characterId: targetCharacterId,
+                                    targetName: String(character.name),
+                                    reference,
+                                    reason: "fuzzy-matches",
                                     fuzzyMatchCount,
-                                    maximumFuzzyMatches: RELATIONSHIP_MAX_FUZZY_MATCHES
+                                    maximumFuzzyMatches: RELATIONSHIP_MAX_FUZZY_MATCHES,
+                                    identityAnchorCount: anchors.length
                                 });
                             }
                             targetFuzzySourceKeys.add(key);
@@ -3816,10 +4442,13 @@ export class AiManager {
                     }
                 }
                 if (targetFuzzySourceKeys.size > RELATIONSHIP_MAX_FUZZY_SOURCES) {
-                    throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", "疑似人物名来源过多，请补充人物别名或身份资料后重试", {
+                    throw new AppError(409, "RELATIONSHIP_MATCH_CANDIDATES_EXCEEDED", relationshipCandidateLimitMessage(`“${String(character.name)}”的拼音疑似来源仍然过多`), {
                         characterId: targetCharacterId,
+                        targetName: String(character.name),
+                        reason: "candidate-sources",
                         candidateCount: targetFuzzySourceKeys.size,
-                        maximum: RELATIONSHIP_MAX_FUZZY_SOURCES
+                        maximum: RELATIONSHIP_MAX_FUZZY_SOURCES,
+                        identityAnchorCount: anchors.length
                     });
                 }
             }
@@ -3976,10 +4605,14 @@ export class AiManager {
        WHERE chapter.work_id = ? ORDER BY volume.sort_order, chapter.sort_order`, workId).map((row, index) => [String(row.id), index]));
         chapters.sort((left, right) => (chapterOrder.get(String(left.id)) ?? Number.MAX_SAFE_INTEGER) - (chapterOrder.get(String(right.id)) ?? Number.MAX_SAFE_INTEGER));
         settings.sort((left, right) => `${left.sourceType}:${left.id}`.localeCompare(`${right.sourceType}:${right.id}`, "zh-CN"));
+        const matchKinds = {};
+        for (const key of selectedKeys)
+            matchKinds[key] = local.exactKeys.includes(key) ? "exact" : "fuzzy";
         return {
             generation,
             chapters,
             settings,
+            matchKinds,
             variantDecisions: verified.decisions,
             verificationCallIds: verified.callIds,
             summary: {
@@ -4007,6 +4640,7 @@ export class AiManager {
         const serialize = (value) => JSON.stringify(cleanStrings(value), null, 2);
         const source = (title, value, version) => ({
             id: sourceType === "setting" ? sourceId : `${sourceType}:${sourceId}`,
+            sourceId,
             title,
             sourceType,
             content: serialize(value),
@@ -4175,11 +4809,174 @@ export class AiManager {
             return materialized ? [materialized] : [];
         });
     }
+    relationshipChangeOperations(before, after) {
+        const beforeById = new Map(before.map((relationship) => [String(relationship.id), relationship]));
+        const afterById = new Map(after.map((relationship) => [String(relationship.id), relationship]));
+        return [
+            ...before.flatMap((relationship) => {
+                const relationshipId = String(relationship.id);
+                const next = afterById.get(relationshipId);
+                if (!next) {
+                    return [{
+                            action: "deleted",
+                            relationshipId,
+                            expectedVersionNo: Number(relationship.versionNo),
+                            before: relationship
+                        }];
+                }
+                if (Number(next.versionNo) !== Number(relationship.versionNo)) {
+                    return [{
+                            action: "updated",
+                            relationshipId,
+                            expectedVersionNo: Number(relationship.versionNo),
+                            before: relationship,
+                            after: next
+                        }];
+                }
+                return [];
+            }),
+            ...after.flatMap((relationship) => {
+                const relationshipId = String(relationship.id);
+                return beforeById.has(relationshipId)
+                    ? []
+                    : [{ action: "created", relationshipId, after: relationship }];
+            })
+        ];
+    }
+    relationshipResultSnapshot(workId, action, relationship) {
+        const evidence = Array.isArray(relationship.evidence)
+            ? relationship.evidence.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+            : [];
+        const characterName = (characterId) => {
+            try {
+                const character = this.store.getCharacter(String(characterId));
+                return character.workId === workId ? String(character.name) : String(characterId);
+            }
+            catch {
+                return String(characterId);
+            }
+        };
+        return {
+            relationshipId: String(relationship.id),
+            action,
+            fromCharacterId: String(relationship.fromCharacterId),
+            fromCharacterName: characterName(relationship.fromCharacterId),
+            toCharacterId: String(relationship.toCharacterId),
+            toCharacterName: characterName(relationship.toCharacterId),
+            category: String(relationship.category),
+            subtype: String(relationship.subtype),
+            keywords: Array.isArray(relationship.keywords) ? relationship.keywords.map(String) : [],
+            directed: Boolean(relationship.directed),
+            currentStatus: String(relationship.currentStatus ?? ""),
+            timeRange: relationship.timeRange && typeof relationship.timeRange === "object" && !Array.isArray(relationship.timeRange)
+                ? relationship.timeRange
+                : {},
+            confidence: Number(relationship.confidence ?? 0),
+            confirmationStatus: String(relationship.confirmationStatus ?? "pending"),
+            evidenceCount: evidence.length,
+            evidence: evidence.slice(0, 3).map((item) => ({
+                chapterId: String(item.chapterId ?? ""),
+                chapterTitle: String(item.chapterTitle ?? item.settingTitle ?? ""),
+                quote: String(item.quote ?? ""),
+                supports: String(item.supports ?? "")
+            })),
+            evidenceTruncated: evidence.length > 3
+        };
+    }
+    relationshipSourcesFromRefs(workId, scope, characters, refs) {
+        const requestedRefs = new Map(refs.map((ref) => [
+            this.relationshipIndexedSourceKey(ref.sourceType, ref.sourceId),
+            ref
+        ]));
+        const availableChapters = scope.type === "settings" ? [] : this.getScopeChapters(workId, scope);
+        const includeSettings = scope.type === "settings" || scope.includeAllSettings === true;
+        const availableSettings = includeSettings ? this.relationshipSettingSources(workId, characters) : [];
+        const availableVersions = new Map([
+            ...availableChapters.map((chapter) => [
+                this.relationshipIndexedSourceKey("chapter", String(chapter.id)),
+                String(chapter.versionNo ?? "")
+            ]),
+            ...availableSettings.map((source) => [
+                this.relationshipIndexedSourceKey(source.sourceType, source.sourceId),
+                source.version
+            ])
+        ]);
+        for (const [sourceKey, ref] of requestedRefs) {
+            const currentVersion = availableVersions.get(sourceKey);
+            if (currentVersion === undefined || currentVersion !== ref.sourceVersion) {
+                throw new AppError(409, "RELATIONSHIP_SOURCE_PREVIEW_STALE", "来源已在预检后发生变化，请重新预览", {
+                    sourceType: ref.sourceType,
+                    sourceId: ref.sourceId
+                });
+            }
+        }
+        const chapters = availableChapters.filter((chapter) => requestedRefs.has(this.relationshipIndexedSourceKey("chapter", String(chapter.id))));
+        const settings = availableSettings.filter((source) => requestedRefs.has(this.relationshipIndexedSourceKey(source.sourceType, source.sourceId)));
+        return { chapters, settings };
+    }
+    async previewRelationshipSources(workId, scope, modelId) {
+        const characters = this.store.listCharacters(workId);
+        if (characters.length < 2)
+            throw new AppError(409, "CHARACTERS_REQUIRED", "人物关系分析至少需要两个角色档案");
+        const selectedCharacterIds = new Set(scope.characterIds ?? []);
+        if (selectedCharacterIds.size === 0) {
+            throw new AppError(400, "RELATIONSHIP_PREVIEW_CHARACTERS_REQUIRED", "请先选择需要定向分析的角色");
+        }
+        for (const characterId of selectedCharacterIds) {
+            if (!characters.some((character) => String(character.id) === characterId)) {
+                throw new AppError(400, "CHARACTER_WORK_MISMATCH", "被分析角色不属于当前作品");
+            }
+        }
+        const preFilterRelationshipSources = scope.preFilterRelationshipSources !== false;
+        const sourceSelection = preFilterRelationshipSources
+            ? await this.selectRelationshipSources(workId, scope, characters, selectedCharacterIds, modelId)
+            : null;
+        const chapters = sourceSelection?.chapters
+            ?? (scope.type === "settings" ? [] : this.getScopeChapters(workId, scope));
+        const settings = sourceSelection?.settings
+            ?? (scope.type === "settings" || scope.includeAllSettings === true
+                ? this.relationshipSettingSources(workId, characters)
+                : []);
+        const sources = [
+            ...chapters.map((chapter) => ({
+                sourceType: "chapter",
+                sourceId: String(chapter.id),
+                title: String(chapter.title),
+                version: String(chapter.versionNo ?? ""),
+                characterCount: String(chapter.content ?? "").length,
+                matchType: sourceSelection?.matchKinds[this.relationshipIndexedSourceKey("chapter", String(chapter.id))] ?? "scope"
+            })),
+            ...settings.map((setting) => ({
+                sourceType: setting.sourceType,
+                sourceId: setting.sourceId,
+                title: setting.title,
+                version: setting.version,
+                characterCount: setting.content.length,
+                matchType: sourceSelection?.matchKinds[this.relationshipIndexedSourceKey(setting.sourceType, setting.sourceId)] ?? "scope"
+            }))
+        ];
+        if (sources.length > 5_000) {
+            throw new AppError(409, "RELATIONSHIP_SOURCE_PREVIEW_TOO_LARGE", "预检来源超过 5000 条，请缩小分析范围");
+        }
+        return {
+            preFilterRelationshipSources,
+            chapterCount: chapters.length,
+            settingCount: settings.length,
+            sourceCount: sources.length,
+            totalCharacters: sources.reduce((total, source) => total + source.characterCount, 0),
+            estimatedBatchCount: this.buildChapterChunks(chapters, 12_000).length + this.buildSettingChunks(settings, 12_000).length,
+            sources,
+            indexGeneration: sourceSelection?.generation ?? null,
+            selectionSummary: sourceSelection?.summary ?? null,
+            verificationCallCount: sourceSelection?.verificationCallIds.length ?? 0
+        };
+    }
     async runRelationshipAnalysis(workId, scope, modelId, taskId) {
         const characters = this.store.listCharacters(workId);
         if (characters.length < 2)
             throw new AppError(409, "CHARACTERS_REQUIRED", "人物关系分析至少需要两个角色档案");
         const settingsOnly = scope.type === "settings";
+        const includesSettings = settingsOnly || scope.includeAllSettings === true;
         const selectedCharacterIds = new Set(scope.characterIds ?? []);
         for (const characterId of selectedCharacterIds) {
             const character = characters.find((item) => item.id === characterId);
@@ -4187,19 +4984,24 @@ export class AiManager {
                 throw new AppError(400, "CHARACTER_WORK_MISMATCH", "被分析角色不属于当前作品");
         }
         const targeted = selectedCharacterIds.size > 0;
+        const preFilterRelationshipSources = targeted && scope.preFilterRelationshipSources !== false;
+        const previewRelationshipChanges = scope.previewRelationshipChanges === true;
         const targetedRoster = characters
             .filter((character) => selectedCharacterIds.has(String(character.id)))
             .map((character) => `${String(character.id)} | ${String(character.name)}`)
             .join("\n");
-        const sourceSelection = targeted
+        const previewedSources = Array.isArray(scope.relationshipSourceRefs)
+            ? this.relationshipSourcesFromRefs(workId, scope, characters, scope.relationshipSourceRefs)
+            : null;
+        const sourceSelection = !previewedSources && preFilterRelationshipSources
             ? await this.selectRelationshipSources(workId, scope, characters, selectedCharacterIds, modelId, taskId)
             : null;
-        const scopedChapters = targeted ? [] : settingsOnly ? [] : this.getScopeChapters(workId, scope);
-        const chapters = sourceSelection?.chapters ?? scopedChapters;
-        const availableSettings = targeted ? [] : settingsOnly || scope.includeAllSettings === true
+        const scopedChapters = preFilterRelationshipSources || settingsOnly ? [] : this.getScopeChapters(workId, scope);
+        const chapters = previewedSources?.chapters ?? sourceSelection?.chapters ?? scopedChapters;
+        const availableSettings = !preFilterRelationshipSources && (settingsOnly || scope.includeAllSettings === true)
             ? this.relationshipSettingSources(workId, characters)
             : [];
-        const settings = sourceSelection?.settings ?? availableSettings;
+        const settings = previewedSources?.settings ?? sourceSelection?.settings ?? availableSettings;
         if (!targeted && settingsOnly && availableSettings.length === 0)
             throw new AppError(409, "SETTINGS_REQUIRED", "人物关系分析范围内没有设定数据");
         if (!targeted && !settingsOnly && scopedChapters.length === 0 && availableSettings.length === 0) {
@@ -4214,7 +5016,9 @@ export class AiManager {
                 relationshipIds: [],
                 candidateCount: 0,
                 rawCandidateCount: 0,
-                skipped: [{ index: -1, reason: "没有章节或设定数据命中被分析角色的名称或别名" }],
+                skipped: [{ index: -1, reason: preFilterRelationshipSources
+                            ? "没有章节或设定数据命中被分析角色的名称或别名"
+                            : "人物关系分析范围内没有章节或设定数据" }],
                 batchCount: 0,
                 coveredChapterCount: 0,
                 coveredSettingCount: 0,
@@ -4224,6 +5028,19 @@ export class AiManager {
                 targetedEvidenceCount: 0,
                 aggregationBatchCount: 0,
                 replacedRelationshipCount: 0,
+                preFilterRelationshipSources,
+                ...(previewRelationshipChanges ? {
+                    relationshipChangePreview: {
+                        status: "pending",
+                        totalCount: 0,
+                        createdCount: 0,
+                        updatedCount: 0,
+                        deletedCount: 0,
+                        generatedAt: now(),
+                        operations: []
+                    }
+                } : {}),
+                sourcePreviewApplied: Boolean(previewedSources),
                 sourceSelection: sourceSelection?.summary,
                 callIds: sourceSelection?.verificationCallIds ?? []
             };
@@ -4611,14 +5428,16 @@ export class AiManager {
             const relationshipId = String(relationship.id);
             const previous = relationshipOutcomes.get(relationshipId);
             relationshipOutcomes.set(relationshipId, {
-                action: previous?.action === "created" ? "created" : action,
+                action: action === "deleted" ? "deleted" : previous?.action === "created" ? "created" : action,
                 relationship
             });
         };
         let replacedRelationshipCount = 0;
+        let relationshipChangeOperations = [];
+        const relationshipsBeforePreview = previewRelationshipChanges ? this.store.listRelationships(workId) : [];
         if (!this.taskCanCommit(taskId))
             return { interrupted: true, callIds };
-        this.store.db.transaction(() => {
+        const processRelationshipChanges = () => {
             if (targeted && scope.replaceExistingRelationships === true) {
                 const relationshipsToReplace = this.store.listRelationships(workId).filter((relationship) => selectedCharacterIds.has(String(relationship.fromCharacterId)) || selectedCharacterIds.has(String(relationship.toCharacterId)));
                 for (const relationship of relationshipsToReplace)
@@ -4823,9 +5642,31 @@ export class AiManager {
                 recordRelationshipOutcome("created", relationship);
                 existing.push(relationship);
             }
-            if (taskId && settingsOnly)
+            if (taskId && includesSettings)
                 this.store.refreshTaskSourceVersions(taskId);
-        });
+            if (previewRelationshipChanges) {
+                relationshipChangeOperations = this.relationshipChangeOperations(relationshipsBeforePreview, this.store.listRelationships(workId));
+            }
+        };
+        if (previewRelationshipChanges)
+            this.store.db.rollbackTransaction(processRelationshipChanges);
+        else
+            this.store.db.transaction(processRelationshipChanges);
+        if (previewRelationshipChanges) {
+            const unchangedOutcomes = [...relationshipOutcomes.values()].filter((outcome) => outcome.action === "unchanged");
+            relationshipOutcomes.clear();
+            for (const operation of relationshipChangeOperations) {
+                recordRelationshipOutcome(operation.action, (operation.action === "deleted" ? operation.before : operation.after));
+            }
+            for (const outcome of unchangedOutcomes) {
+                if (!relationshipOutcomes.has(String(outcome.relationship.id))) {
+                    recordRelationshipOutcome("unchanged", outcome.relationship);
+                }
+            }
+            relationshipIds.length = 0;
+            if (taskId && includesSettings)
+                this.store.refreshTaskSourceVersions(taskId);
+        }
         if (sourceSelection) {
             const acceptedVariants = sourceSelection.variantDecisions.filter((decision) => decision.verdict === "same" && decision.confidence >= 0.8);
             const reviewIds = new Set();
@@ -4872,48 +5713,21 @@ export class AiManager {
             });
             sourceSelection.summary.reviewIds = [...reviewIds];
         }
-        const characterNameById = new Map(characters.map((character) => [String(character.id), String(character.name)]));
-        const relationshipResults = [...relationshipOutcomes.values()].map(({ action, relationship }) => {
-            const evidence = Array.isArray(relationship.evidence)
-                ? relationship.evidence.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item))
-                : [];
-            return {
-                relationshipId: String(relationship.id),
-                action,
-                fromCharacterId: String(relationship.fromCharacterId),
-                fromCharacterName: characterNameById.get(String(relationship.fromCharacterId)) ?? String(relationship.fromCharacterId),
-                toCharacterId: String(relationship.toCharacterId),
-                toCharacterName: characterNameById.get(String(relationship.toCharacterId)) ?? String(relationship.toCharacterId),
-                category: String(relationship.category),
-                subtype: String(relationship.subtype),
-                keywords: Array.isArray(relationship.keywords) ? relationship.keywords.map(String) : [],
-                directed: Boolean(relationship.directed),
-                currentStatus: String(relationship.currentStatus ?? ""),
-                timeRange: relationship.timeRange && typeof relationship.timeRange === "object" && !Array.isArray(relationship.timeRange)
-                    ? relationship.timeRange
-                    : {},
-                confidence: Number(relationship.confidence ?? 0),
-                confirmationStatus: String(relationship.confirmationStatus ?? "pending"),
-                evidenceCount: evidence.length,
-                evidence: evidence.slice(0, 3).map((item) => ({
-                    chapterId: String(item.chapterId ?? ""),
-                    chapterTitle: String(item.chapterTitle ?? chapterById.get(String(item.chapterId))?.title ?? ""),
-                    quote: String(item.quote ?? ""),
-                    supports: String(item.supports ?? "")
-                })),
-                evidenceTruncated: evidence.length > 3
-            };
-        });
+        if (previewRelationshipChanges && taskId && includesSettings)
+            this.store.refreshTaskSourceVersions(taskId);
+        const relationshipResults = [...relationshipOutcomes.values()].map(({ action, relationship }) => this.relationshipResultSnapshot(workId, action, relationship));
         const createdCount = relationshipResults.filter((item) => item.action === "created").length;
         const updatedCount = relationshipResults.filter((item) => item.action === "updated").length;
+        const deletedCount = relationshipResults.filter((item) => item.action === "deleted").length;
         const unchangedCount = relationshipResults.filter((item) => item.action === "unchanged").length;
-        this.store.audit(workId, "relationship.analysis.completed", "work", workId, {
+        this.store.audit(workId, previewRelationshipChanges ? "relationship.analysis.previewed" : "relationship.analysis.completed", "work", workId, {
             batchCount: chunks.length,
             coveredChapterCount: chapters.length,
             coveredSettingCount: settings.length,
             rawCandidateCount: rawCandidates.length,
             savedCount: relationshipIds.length,
             updatedCount,
+            deletedCount,
             unchangedCount,
             skippedCount: skipped.length,
             fallbackSegmentCount,
@@ -4922,15 +5736,28 @@ export class AiManager {
             targetedCharacterCount: selectedCharacterIds.size,
             targetedEvidenceCount,
             aggregationBatchCount,
-            replacedRelationshipCount
+            replacedRelationshipCount,
+            preFilterRelationshipSources
         });
         return {
             relationshipIds,
-            candidateCount: relationshipIds.length,
+            candidateCount: previewRelationshipChanges ? createdCount + updatedCount : relationshipIds.length,
             createdCount,
             updatedCount,
+            deletedCount,
             unchangedCount,
             relationshipResults,
+            ...(previewRelationshipChanges ? {
+                relationshipChangePreview: {
+                    status: "pending",
+                    totalCount: relationshipChangeOperations.length,
+                    createdCount,
+                    updatedCount,
+                    deletedCount,
+                    generatedAt: now(),
+                    operations: relationshipChangeOperations
+                }
+            } : {}),
             analysisTarget: {
                 mode: targeted ? "targeted-characters" : "all-relationships",
                 scopeType: scope.type,
@@ -4939,7 +5766,8 @@ export class AiManager {
                     .filter((character) => selectedCharacterIds.has(String(character.id)))
                     .map((character) => String(character.name)),
                 coveredChapterCount: chapters.length,
-                includeAllSettings: scope.includeAllSettings === true
+                includeAllSettings: scope.includeAllSettings === true,
+                preFilterRelationshipSources
             },
             rawCandidateCount: rawCandidates.length,
             skipped,
@@ -4952,6 +5780,8 @@ export class AiManager {
             targetedEvidenceCount,
             aggregationBatchCount,
             replacedRelationshipCount,
+            preFilterRelationshipSources,
+            sourcePreviewApplied: Boolean(previewedSources),
             ...(sourceSelection ? { sourceSelection: sourceSelection.summary } : {}),
             callIds
         };
@@ -5610,6 +6440,7 @@ export class AiManager {
             scope: "platform",
             name: stringValue(row, "name"),
             baseUrl: stringValue(row, "base_url"),
+            protocol: providerProtocol(row),
             apiKey: stringValue(row, "key_hint"),
             status: stringValue(row, "status"),
             connectionStatus: stringValue(row, "connection_status"),