@musnows/scriverse 0.4.11 → 0.5.0

package/dist/ai.js

@@ -33,6 +33,59 @@ function thinkingParameters(provider, model) {
     return { thinking: { type: boolValue(model, "thinking_enabled") ? "enabled" : "disabled" } };
 }
 const AGENT_TOOL_IDS = ["story_index", "read_chapters", "grep", "search_story_entities", "read_character_sections"];
+function redactProviderSecret(value, apiKey) {
+    if (!apiKey)
+        return value;
+    return value.split(apiKey).join("[REDACTED]");
+}
+function redactProviderSecrets(value, apiKey, depth = 0) {
+    if (typeof value === "string")
+        return redactProviderSecret(value, apiKey);
+    if (value === null || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (depth >= 32)
+        return "[REDACTED_DEPTH_LIMIT]";
+    if (Array.isArray(value))
+        return value.map((item) => redactProviderSecrets(item, apiKey, depth + 1));
+    if (!value || typeof value !== "object")
+        return null;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactProviderSecrets(item, apiKey, depth + 1)]));
+}
+function sanitizeCompletionTraceResponse(value) {
+    const response = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const choices = Array.isArray(response.choices) ? response.choices : [];
+    return {
+        choices: choices.map((choice) => {
+            const choiceRecord = choice && typeof choice === "object" && !Array.isArray(choice) ? choice : {};
+            const message = choiceRecord.message && typeof choiceRecord.message === "object" && !Array.isArray(choiceRecord.message)
+                ? choiceRecord.message
+                : {};
+            const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+            return {
+                finish_reason: typeof choiceRecord.finish_reason === "string" || choiceRecord.finish_reason === null ? choiceRecord.finish_reason : null,
+                message: {
+                    content: typeof message.content === "string" || message.content === null ? message.content : null,
+                    reasoning_content: typeof message.reasoning_content === "string" || message.reasoning_content === null ? message.reasoning_content : null,
+                    tool_calls: toolCalls.map((toolCall) => {
+                        const toolCallRecord = toolCall && typeof toolCall === "object" && !Array.isArray(toolCall) ? toolCall : {};
+                        const fn = toolCallRecord.function && typeof toolCallRecord.function === "object" && !Array.isArray(toolCallRecord.function)
+                            ? toolCallRecord.function
+                            : {};
+                        return {
+                            id: typeof toolCallRecord.id === "string" ? toolCallRecord.id : "",
+                            type: "function",
+                            function: {
+                                name: typeof fn.name === "string" ? fn.name : "",
+                                arguments: fn.arguments ?? ""
+                            }
+                        };
+                    })
+                }
+            };
+        }),
+        ...(response.usage && typeof response.usage === "object" && !Array.isArray(response.usage) ? { usage: response.usage } : {})
+    };
+}
 const MAX_AGENT_TOOL_ROUNDS = 6;
 const MAX_AGENT_TOOL_CALLS = 12;
 const MAX_CONFIGURED_AGENT_TOOL_CALLS = 48;
@@ -202,6 +255,43 @@ export function resolveOutputTokens(usage, content) {
     }
     return estimateAiTokens(content);
 }
+function resolveInputCacheUsage(usage) {
+    if (!usage || typeof usage !== "object")
+        return null;
+    const record = usage;
+    const promptDetails = record.prompt_tokens_details && typeof record.prompt_tokens_details === "object"
+        ? record.prompt_tokens_details
+        : {};
+    const inputDetails = record.input_tokens_details && typeof record.input_tokens_details === "object"
+        ? record.input_tokens_details
+        : {};
+    const cached = promptDetails.cached_tokens
+        ?? inputDetails.cached_tokens
+        ?? record.prompt_cache_hit_tokens
+        ?? record.cache_read_input_tokens
+        ?? record.cached_input_tokens;
+    if (typeof cached !== "number" || !Number.isFinite(cached))
+        return null;
+    const reportedInput = record.prompt_tokens ?? record.input_tokens;
+    const missed = record.prompt_cache_miss_tokens;
+    const inputTokens = typeof reportedInput === "number" && Number.isFinite(reportedInput)
+        ? Math.max(0, Math.round(reportedInput))
+        : typeof missed === "number" && Number.isFinite(missed)
+            ? Math.max(0, Math.round(cached)) + Math.max(0, Math.round(missed))
+            : 0;
+    if (inputTokens <= 0)
+        return null;
+    return {
+        inputTokens,
+        cachedInputTokens: Math.min(inputTokens, Math.max(0, Math.round(cached)))
+    };
+}
+export function resolveCacheHitPercent(usage) {
+    const resolved = resolveInputCacheUsage(usage);
+    if (!resolved)
+        return undefined;
+    return Math.round(resolved.cachedInputTokens / resolved.inputTokens * 1_000) / 10;
+}
 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))
@@ -428,13 +518,16 @@ export class ContextBuilder {
             ? [`作品：${String(work.title)}\n作者：${String(work.author) || "未填写"}`]
             : [];
         const contentSections = [];
-        const lockedSettings = this.store.listSettings(workId).filter((item) => item.locked);
+        const availableSettings = this.store.listSettings(workId);
+        const contextualSettings = scope.includeAllSettings ? availableSettings : availableSettings.filter((item) => item.locked);
         const allCharacters = this.store.listCharacters(workId);
         const lockedCharacters = allCharacters.filter((item) => Array.isArray(item.lockedFields) && item.lockedFields.length > 0);
         const organizations = this.store.listOrganizations(workId);
-        const relationshipConstraints = selectRelationshipConstraints(this.store, workId, scope.characterIds ?? []);
-        if (includeAutomaticContext && lockedSettings.length > 0) {
-            constraints.push(`作者锁定设定（硬约束）：\n${lockedSettings
+        const relationshipConstraints = scope.excludeRelationshipConstraints
+            ? []
+            : selectRelationshipConstraints(this.store, workId, scope.characterIds ?? []);
+        if (includeAutomaticContext && contextualSettings.length > 0) {
+            constraints.push(`${scope.includeAllSettings ? "全部作品设定（关系分析参考）" : "作者锁定设定（硬约束）"}：\n${contextualSettings
                 .map((item) => `- [${String(item.category)}] ${String(item.title)}：${String(item.content)}`)
                 .join("\n")}`);
         }
@@ -1020,7 +1113,7 @@ export class AiManager {
        source_text, content, action, status, created_at, created_by_user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)`, suggestionId, generated.callId, input.workId, chapter ? String(chapter.id) : null, chapter ? Number(chapter.versionNo) : null, input.taskType, input.instruction, effectiveInput.scope.selection ?? "", generated.content, action, now(), currentRequestActor()?.userId ?? null);
         if (input.taskType === "continue")
             await this.runSuggestionGuard(suggestionId);
-        return { ...this.getSuggestion(suggestionId), outputTokens: generated.outputTokens, toolCalls: generated.toolCalls, processSteps: generated.processSteps };
+        return { ...this.getSuggestion(suggestionId), outputTokens: generated.outputTokens, ...(generated.cacheHitPercent === undefined ? {} : { cacheHitPercent: generated.cacheHitPercent }), toolCalls: generated.toolCalls, processSteps: generated.processSteps };
     }
     async createStreamingChat(input, onDelta) {
         const generated = this.enabledAgentTools(input.workId, "chat").length
@@ -1032,7 +1125,7 @@ export class AiManager {
         const suggestionId = id("suggestion");
         this.store.db.run(`INSERT INTO ai_suggestions (id, call_id, work_id, chapter_id, chapter_version, task_type, instruction,
        source_text, content, action, status, created_at, created_by_user_id) VALUES (?, ?, ?, ?, ?, 'chat', ?, ?, ?, 'note', 'pending', ?, ?)`, suggestionId, generated.callId, input.workId, chapter ? String(chapter.id) : null, chapter ? Number(chapter.versionNo) : null, input.instruction, input.scope.selection ?? "", generated.content, now(), currentRequestActor()?.userId ?? null);
-        return { ...this.getSuggestion(suggestionId), outputTokens: generated.outputTokens, toolCalls: generated.toolCalls, processSteps: generated.processSteps };
+        return { ...this.getSuggestion(suggestionId), outputTokens: generated.outputTokens, ...(generated.cacheHitPercent === undefined ? {} : { cacheHitPercent: generated.cacheHitPercent }), toolCalls: generated.toolCalls, processSteps: generated.processSteps };
     }
     async runSuggestionGuard(suggestionId, candidateContent) {
         const suggestion = this.getSuggestion(suggestionId);
@@ -1183,6 +1276,7 @@ export class AiManager {
         return this.store.db.all("SELECT * FROM ai_calls WHERE work_id = ? ORDER BY created_at DESC LIMIT 200", workId).map((row) => ({
             id: stringValue(row, "id"),
             workId: stringValue(row, "work_id"),
+            taskId: row.task_id === null ? null : stringValue(row, "task_id"),
             taskType: stringValue(row, "task_type"),
             provider: this.getProvider(stringValue(row, "provider_id")),
             model: this.getModel(stringValue(row, "model_id")),
@@ -1203,6 +1297,7 @@ export class AiManager {
         return paginated(rows.map((row) => ({
             id: stringValue(row, "id"),
             workId: stringValue(row, "work_id"),
+            taskId: row.task_id === null ? null : stringValue(row, "task_id"),
             taskType: stringValue(row, "task_type"),
             provider: this.getProvider(stringValue(row, "provider_id")),
             model: this.getModel(stringValue(row, "model_id")),
@@ -1216,6 +1311,55 @@ export class AiManager {
             completedAt: row.completed_at === null ? null : stringValue(row, "completed_at")
         })), pagination);
     }
+    getTaskTrace(taskId) {
+        this.store.getTask(taskId);
+        const rows = this.store.db.all(`SELECT call.*, trace.initial_messages_json, trace.rounds_json, trace.created_at AS trace_created_at,
+        trace.updated_at AS trace_updated_at, provider.name AS provider_name,
+        model.display_name AS model_display_name, model.model_id AS external_model_id
+       FROM ai_calls call
+       LEFT JOIN ai_call_traces trace ON trace.call_id = call.id
+       LEFT JOIN providers provider ON provider.id = call.provider_id
+       LEFT JOIN models model ON model.id = call.model_id
+       WHERE call.task_id = ?
+       ORDER BY call.created_at ASC, call.id ASC`, taskId);
+        const calls = rows.map((row) => {
+            const hasTrace = row.initial_messages_json !== null && row.initial_messages_json !== undefined;
+            return {
+                id: stringValue(row, "id"),
+                taskType: stringValue(row, "task_type"),
+                provider: {
+                    id: stringValue(row, "provider_id"),
+                    name: row.provider_name === null ? "已删除的供应商" : stringValue(row, "provider_name"),
+                    deleted: row.provider_name === null
+                },
+                model: {
+                    id: stringValue(row, "model_id"),
+                    displayName: row.model_display_name === null ? "已删除的模型" : stringValue(row, "model_display_name"),
+                    modelId: row.external_model_id === null ? null : stringValue(row, "external_model_id"),
+                    deleted: row.model_display_name === null
+                },
+                contextScope: json(stringValue(row, "context_scope_json"), {}),
+                parameters: json(stringValue(row, "parameters_json"), {}),
+                status: stringValue(row, "status"),
+                failure: row.failure === null ? null : stringValue(row, "failure"),
+                inputChars: numberValue(row, "input_chars"),
+                outputChars: numberValue(row, "output_chars"),
+                createdAt: stringValue(row, "created_at"),
+                completedAt: row.completed_at === null ? null : stringValue(row, "completed_at"),
+                trace: hasTrace ? {
+                    initialMessages: json(stringValue(row, "initial_messages_json"), []),
+                    rounds: json(stringValue(row, "rounds_json"), []),
+                    createdAt: stringValue(row, "trace_created_at"),
+                    updatedAt: stringValue(row, "trace_updated_at")
+                } : null
+            };
+        });
+        return {
+            taskId,
+            captured: calls.some((call) => call.trace !== null),
+            calls
+        };
+    }
     async runTask(taskId, modelId) {
         const task = this.store.getTask(taskId);
         const workId = String(task.workId);
@@ -1270,6 +1414,7 @@ export class AiManager {
             else {
                 const generated = await this.generate({
                     workId,
+                    taskId,
                     taskType: taskType === "book-analysis" ? "book-analysis" : "chapter-analysis",
                     instruction: "请基于上下文完成分析，给出有原文依据的中文结论。",
                     scope,
@@ -1731,8 +1876,20 @@ export class AiManager {
         });
         const callId = id("call");
         const timestamp = now();
-        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, timestamp, currentRequestActor()?.userId ?? null);
+        const traceRounds = [];
+        this.store.db.transaction(() => {
+            this.store.db.run(`INSERT INTO ai_calls (id, work_id, task_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.taskId ?? null, input.taskType, stringValue(provider, "id"), stringValue(model, "id"), JSON.stringify(input.scope), JSON.stringify(parameters), context.length + input.instruction.length, timestamp, currentRequestActor()?.userId ?? null);
+            if (input.taskId) {
+                this.store.db.run(`INSERT INTO ai_call_traces (call_id, task_id, initial_messages_json, rounds_json, created_at, updated_at)
+           VALUES (?, ?, ?, '[]', ?, ?)`, callId, input.taskId, JSON.stringify(messages), timestamp, timestamp);
+            }
+        });
+        const saveTrace = () => {
+            if (!input.taskId)
+                return;
+            this.store.db.run("UPDATE ai_call_traces SET rounds_json = ?, updated_at = ? WHERE call_id = ?", JSON.stringify(traceRounds), now(), callId);
+        };
         const callStartedAt = process.hrtime.bigint();
         logger.info("ai.call.started", {
             callId,
@@ -1745,16 +1902,44 @@ export class AiManager {
             instructionChars: input.instruction.length,
             toolCount: tools.length
         });
+        let activeApiKey = "";
         try {
             const apiKey = this.decryptKey(provider);
+            activeApiKey = apiKey;
             const endpoint = `${normalizeBaseUrl(stringValue(provider, "base_url"))}/chat/completions`;
             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;
+            let cacheUsageComplete = true;
+            let totalInputTokens = 0;
+            let totalCachedInputTokens = 0;
             const requestCompletion = async (toolChoice) => {
+                const traceRound = {
+                    round: traceRounds.length + 1,
+                    requestedAt: now(),
+                    request: {
+                        model: stringValue(model, "model_id"),
+                        messages: structuredClone(completionMessages),
+                        parameters: structuredClone(parameters),
+                        tools: toolChoice === "auto" ? structuredClone(tools) : [],
+                        toolChoice
+                    },
+                    attempts: [],
+                    toolExecutions: []
+                };
+                traceRounds.push(traceRound);
+                saveTrace();
                 let lastFailure = null;
                 for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
                     let retryable = true;
                     const attemptStartedAt = process.hrtime.bigint();
+                    const traceAttempt = {
+                        attempt,
+                        startedAt: now(),
+                        status: "running"
+                    };
+                    traceRound.attempts.push(traceAttempt);
+                    saveTrace();
                     logger.info("ai.call.attempt_started", { callId, attempt, maximumAttempts, toolChoice });
                     try {
                         const candidate = await this.scheduleProviderRequest(provider, input.signal, async () => {
@@ -1793,13 +1978,32 @@ export class AiManager {
                         });
                         if (candidate.ok) {
                             try {
-                                return JSON.parse(candidate.body);
+                                const parsed = redactProviderSecrets(JSON.parse(candidate.body), apiKey);
+                                traceAttempt.completedAt = now();
+                                traceAttempt.status = "completed";
+                                traceAttempt.httpStatus = candidate.status;
+                                traceAttempt.response = sanitizeCompletionTraceResponse(parsed);
+                                saveTrace();
+                                completionRequestCount += 1;
+                                const cacheUsage = resolveInputCacheUsage(parsed.usage);
+                                if (!cacheUsage)
+                                    cacheUsageComplete = false;
+                                else {
+                                    totalInputTokens += cacheUsage.inputTokens;
+                                    totalCachedInputTokens += cacheUsage.cachedInputTokens;
+                                }
+                                return parsed;
                             }
                             catch {
                                 throw new Error(`Chat Completions returned invalid JSON: ${candidate.body.slice(0, 500)}`);
                             }
                         }
                         lastFailure = new Error(`HTTP ${candidate.status}: ${candidate.body.slice(0, 500)}`);
+                        traceAttempt.completedAt = now();
+                        traceAttempt.status = "failed";
+                        traceAttempt.httpStatus = candidate.status;
+                        traceAttempt.failure = redactProviderSecret(`HTTP ${candidate.status}: ${candidate.body.slice(0, 2_000)}`, apiKey);
+                        saveTrace();
                         if (candidate.status !== 429 && candidate.status < 500) {
                             retryable = false;
                             throw lastFailure;
@@ -1807,6 +2011,14 @@ export class AiManager {
                     }
                     catch (error) {
                         lastFailure = error;
+                        if (traceAttempt.status === "running") {
+                            traceAttempt.completedAt = now();
+                            traceAttempt.status = "failed";
+                            traceAttempt.failure = error instanceof Error
+                                ? redactProviderSecret(error.message.slice(0, 2_000), apiKey)
+                                : "AI request failed";
+                            saveTrace();
+                        }
                         logger.warn("ai.call.attempt_failed", {
                             callId,
                             attempt,
@@ -1868,6 +2080,8 @@ export class AiManager {
                     const execution = this.executeAgentTool(input.workId, toolCall);
                     logger.info("ai.tool_call.completed", { callId, toolName: execution.name, status: execution.status, round });
                     executedToolCalls.push(execution);
+                    traceRounds.at(-1)?.toolExecutions.push(execution);
+                    saveTrace();
                     processSteps.push({ id: id("process"), type: "tool", round, toolCall: execution, createdAt: execution.calledAt });
                     input.onToolCall?.(execution, round);
                     completionMessages.push({ role: "tool", tool_call_id: toolCall.id, content: JSON.stringify(execution.result) });
@@ -1897,6 +2111,9 @@ export class AiManager {
             }
             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;
             logger.info("ai.call.completed", {
                 callId,
                 workId: input.workId,
@@ -1907,10 +2124,10 @@ export class AiManager {
                 outputTokens,
                 toolCallCount: executedToolCalls.length
             });
-            return { callId, content, outputTokens, provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: executedToolCalls, processSteps };
+            return { callId, content, outputTokens, ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }), provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: executedToolCalls, 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,
@@ -2024,7 +2241,7 @@ export class AiManager {
             }
             if (streamedResult === null)
                 throw lastFailure instanceof Error ? lastFailure : new Error("AI 流式请求重试后仍未返回响应");
-            const { content, reasoning, outputTokens } = streamedResult;
+            const { content, reasoning, outputTokens, cacheHitPercent } = streamedResult;
             const processSteps = reasoning.trim()
                 ? [{ id: thinkingStepId, type: "thinking", round: 1, content: reasoning, createdAt: thinkingCreatedAt }]
                 : [];
@@ -2038,7 +2255,7 @@ export class AiManager {
                 outputChars: content.length,
                 outputTokens
             });
-            return { callId, content, outputTokens, provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: [], processSteps };
+            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 流式调用失败";
@@ -2105,7 +2322,8 @@ export class AiManager {
             consumeEvent(buffer);
         if (!content.trim())
             throw new Error(`Chat Completions 流式响应缺少可用正文，finish_reason=${finishReason}`);
-        return { content, reasoning, outputTokens: resolveOutputTokens(usage, content) };
+        const cacheHitPercent = resolveCacheHitPercent(usage);
+        return { content, reasoning, outputTokens: resolveOutputTokens(usage, content), ...(cacheHitPercent === undefined ? {} : { cacheHitPercent }) };
     }
     async runChapterAnalysis(workId, scope, modelId, taskId) {
         if (!scope.chapterId)
@@ -2113,6 +2331,7 @@ export class AiManager {
         const chapter = this.store.getChapter(scope.chapterId);
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "chapter-analysis",
             signal: this.taskSignal(taskId),
             instruction: "分析本章并输出 JSON 对象，字段为 summary（1至3句）、events（数组）、characters（数组）、settings（数组）、evidence（数组，每项含 conclusion 和 quote）、uncertainties（数组）。",
@@ -2132,6 +2351,7 @@ export class AiManager {
     async runTimelineAnalysis(workId, scope, modelId, taskId) {
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "timeline-analysis",
             signal: this.taskSignal(taskId),
             instruction: "抽取大事件候选并输出 JSON 数组。每项字段：name、description、eventType、timeLabel、timeSort（无法确定为 null）、location、impactScope、chapterIds、participantIds、evidence。必须区分发生时间与叙述时间；不确定时使用‘时间待定’。",
@@ -2171,6 +2391,7 @@ export class AiManager {
             throw new AppError(409, "CHAPTERS_REQUIRED", "世界观分析范围内没有章节");
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "book-analysis",
             signal: this.taskSignal(taskId),
             instruction: [
@@ -2268,6 +2489,7 @@ export class AiManager {
                 return { candidates: [], callId: null };
             const generated = await this.generateTaggedJson({
                 workId,
+                taskId,
                 taskType: "book-analysis",
                 signal: this.taskSignal(taskId),
                 maxAttempts: 2,
@@ -2411,6 +2633,7 @@ export class AiManager {
     async runConsistencyCheck(workId, scope, modelId, taskId) {
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "consistency-check",
             signal: this.taskSignal(taskId),
             instruction: "检查设定、人物状态、关系和时间是否冲突，输出 JSON 数组。每项字段：itemType、severity（low/medium/high）、title、description、entityRefs、evidence、suggestion。没有问题时输出 []。",
@@ -2466,6 +2689,7 @@ export class AiManager {
         }).join("\n");
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "book-analysis",
             signal: this.taskSignal(taskId),
             scope: scope.type === "none" ? scope : { type: "none" },
@@ -2586,6 +2810,7 @@ export class AiManager {
     async verifyCharacterTitlePairs(workId, pairs, modelId, taskId) {
         const generated = await this.generateTaggedJson({
             workId,
+            taskId,
             taskType: "book-analysis",
             signal: this.taskSignal(taskId),
             scope: { type: "none" },
@@ -2639,6 +2864,7 @@ export class AiManager {
         const extractChunk = async (text, maxAttempts = 3) => {
             const generated = await this.generateTaggedJson({
                 workId,
+                taskId,
                 taskType: "book-analysis",
                 signal: this.taskSignal(taskId),
                 maxAttempts,
@@ -2991,6 +3217,17 @@ export class AiManager {
         const characters = this.store.listCharacters(workId);
         if (characters.length < 2)
             throw new AppError(409, "CHARACTERS_REQUIRED", "人物关系分析至少需要两个角色档案");
+        const selectedCharacterIds = new Set(scope.characterIds ?? []);
+        for (const characterId of selectedCharacterIds) {
+            const character = characters.find((item) => item.id === characterId);
+            if (!character)
+                throw new AppError(400, "CHARACTER_WORK_MISMATCH", "被分析角色不属于当前作品");
+        }
+        const targeted = selectedCharacterIds.size > 0;
+        const targetedRoster = characters
+            .filter((character) => selectedCharacterIds.has(String(character.id)))
+            .map((character) => `${String(character.id)} | ${String(character.name)}`)
+            .join("\n");
         const chapters = this.getScopeChapters(workId, scope);
         if (chapters.length === 0)
             throw new AppError(409, "CHAPTERS_REQUIRED", "人物关系分析范围内没有章节");
@@ -3005,13 +3242,32 @@ export class AiManager {
         const extractChunk = async (text, maxAttempts = 3) => {
             const generated = await this.generateTaggedJson({
                 workId,
+                taskId,
                 taskType: "relationship-analysis",
                 signal: this.taskSignal(taskId),
                 maxAttempts,
-                scope: { type: "selection", selection: text },
+                scope: {
+                    type: "selection",
+                    selection: text,
+                    includeAllSettings: scope.includeAllSettings,
+                    ...(targeted ? { characterIds: [...selectedCharacterIds], excludeRelationshipConstraints: scope.replaceExistingRelationships === true } : {})
+                },
                 ...(modelId ? { modelId } : {}),
                 parameters: { temperature: 0.1 },
-                instruction: [
+                instruction: targeted ? [
+                    "你是定向人物关系证据收集器。本阶段只建立跨章节证据账本，不下最终关系结论。",
+                    "被分析角色：",
+                    targetedRoster,
+                    "完整角色规范表：",
+                    roster,
+                    "规则：",
+                    "1. 只记录与至少一名被分析角色直接有关的互动、称谓、亲缘线索、权力行为、情感变化、冲突、回忆或第三方陈述。",
+                    "2. 单次见面、同场出现和含糊代词可以作为待汇总线索，但必须如实描述，不能在本阶段升级为长期关系。",
+                    "3. 人物引用优先填写规范表中的 characterId；暂时不能确定对方身份时填写 relatedReference，禁止创造角色。",
+                    "4. 每条线索只引用一个连续原文短句，quote 不超过 80 字，并准确提供 chapterId、chapterTitle 和 contextType。",
+                    "5. 输出 JSON 数组。字段：targetCharacterId、relatedCharacterId、relatedReference、observation、possibleCategory、possibleSubtype、directionHint、timeHint、chapterId、chapterTitle、quote、contextType。",
+                    "6. 没有与目标角色直接相关的线索时输出 []。"
+                ].join("\n") : [
                     "你是小说人物关系抽取器，不是续写者。只抽取角色规范表中人物之间、对跨章节人物图有长期意义且有原文证据的关系。",
                     "角色规范表：",
                     roster,
@@ -3042,7 +3298,12 @@ export class AiManager {
                     "23. 输出 JSON 数组。字段：fromCharacterId、toCharacterId、category（family/social/emotional/conflict/uncertain）、subtype、keywords、directed、currentStatus、timeRange、confidence、evidence。",
                     "24. 共同执行一次任务、同属一个组织、在同一集体场景中被感谢或落泪、替第三人转发消息，都不能单独证明同事、朋友或盟友。此类关系必须有原文明示身份，或至少两个不同章节的持续互动证据。"
                 ].join("\n"),
-                extraSystemPrompt: "关系候选必须可审计。严禁把梦境伴侣、醉后梦话、单次约定、同章共现、礼称、同族归属、救援照护或类比提及写成现实长期关系。逐句校验说话人和关系方向。"
+                extraSystemPrompt: [
+                    targeted
+                        ? "你正在为指定角色收集可审计的跨章节关系线索。不得在证据收集阶段把单次互动直接判定为长期关系。"
+                        : "关系候选必须可审计。严禁把梦境伴侣、醉后梦话、单次约定、同章共现、礼称、同族归属、救援照护或类比提及写成现实长期关系。逐句校验说话人和关系方向。",
+                    scope.additionalPrompt?.trim() ? `作者追加的关系分析提示：\n${scope.additionalPrompt.trim()}` : ""
+                ].filter(Boolean).join("\n\n")
             });
             const extracted = extractJson(generated.content);
             if (!Array.isArray(extracted))
@@ -3066,7 +3327,8 @@ export class AiManager {
             }
         }, (completed) => {
             if (taskId && this.store.getTask(taskId).status === "running") {
-                this.store.updateTask(taskId, { status: "running", progress: Math.min(92, 5 + Math.round(completed / chunks.length * 87)) });
+                const maximumProgress = targeted ? 72 : 92;
+                this.store.updateTask(taskId, { status: "running", progress: Math.min(maximumProgress, 5 + Math.round(completed / chunks.length * (maximumProgress - 5))) });
             }
         });
         let fallbackSegmentCount = 0;
@@ -3087,6 +3349,88 @@ export class AiManager {
                 batchCount: chunks.length
             });
         }
+        const targetedEvidenceCount = targeted ? rawCandidates.length : 0;
+        let aggregationBatchCount = 0;
+        if (targeted && rawCandidates.length > 0) {
+            const evidenceGroups = new Map();
+            for (const evidence of rawCandidates) {
+                const target = String(evidence.targetCharacterId ?? "");
+                const related = String(evidence.relatedCharacterId ?? evidence.relatedReference ?? "unknown");
+                const key = `${target}|${related}`;
+                const group = evidenceGroups.get(key) ?? [];
+                group.push(evidence);
+                evidenceGroups.set(key, group);
+            }
+            const evidenceBatches = [];
+            let currentBatch = [];
+            let currentLength = 0;
+            for (const group of evidenceGroups.values()) {
+                const groupLength = JSON.stringify(group).length;
+                if (currentBatch.length > 0 && currentLength + groupLength > 60_000) {
+                    evidenceBatches.push(currentBatch);
+                    currentBatch = [];
+                    currentLength = 0;
+                }
+                currentBatch.push(...group);
+                currentLength += groupLength;
+            }
+            if (currentBatch.length > 0)
+                evidenceBatches.push(currentBatch);
+            aggregationBatchCount = evidenceBatches.length;
+            const aggregationResults = await this.processChunks(evidenceBatches, Math.min(concurrency, 4), async (evidenceBatch) => {
+                const generated = await this.generateTaggedJson({
+                    workId,
+                    taskId,
+                    taskType: "relationship-analysis",
+                    signal: this.taskSignal(taskId),
+                    maxAttempts: 2,
+                    scope: {
+                        type: "entities",
+                        includeAllSettings: scope.includeAllSettings,
+                        characterIds: [...selectedCharacterIds],
+                        excludeRelationshipConstraints: scope.replaceExistingRelationships === true
+                    },
+                    ...(modelId ? { modelId } : {}),
+                    parameters: { temperature: 0.1 },
+                    instruction: [
+                        "你是小说人物关系全局归纳器。请综合分析范围内为指定角色收集的全部跨章节证据线索，形成最终长期关系候选。",
+                        "被分析角色：",
+                        targetedRoster,
+                        "完整角色规范表：",
+                        roster,
+                        "证据账本：",
+                        JSON.stringify(evidenceBatch),
+                        "归纳规则：",
+                        "1. 只输出至少一端属于被分析角色的关系，另一端也必须解析为角色规范表中的 characterId。",
+                        "2. 综合不同章节、不同阶段和设定信息判断关系；设定只用于身份消歧和辅助理解，不能代替章节原文证据。",
+                        "3. 单次见面、同场出现、一次任务协作、同组织或同族不能单独升级为长期朋友、同事、盟友、君臣或亲属。",
+                        "4. evidence 只能使用证据账本中的连续原文 quote，必须包含 chapterId、chapterTitle、quote、contextType、supports；quote 不超过 80 字。",
+                        "5. category 只能是 family、social、emotional、conflict、uncertain；confidence 低于 0.6 不输出。",
+                        "6. subtype 使用稳定简短中文词；父母子女、君臣、师生、倾慕、施害与受害等有方向关系必须正确设置 from、to 和 directed=true。",
+                        "7. 同一人物对的阶段变化合并进 timeRange.stages；同一 category/subtype 不得输出反向重复边。",
+                        "8. keywords 提供 2 至 8 个描述双方互动、权力结构、情感阶段或剧情张力的中文关键词。",
+                        "9. 输出 JSON 数组。字段：fromCharacterId、toCharacterId、category、subtype、keywords、directed、currentStatus、timeRange、confidence、evidence。"
+                    ].join("\n"),
+                    extraSystemPrompt: [
+                        "你正在执行指定角色的跨章节关系归纳。所有结论必须能回溯到证据账本中的章节原文，不得沿用缺乏本次证据的旧关系。",
+                        scope.additionalPrompt?.trim() ? `作者追加的关系分析提示：\n${scope.additionalPrompt.trim()}` : ""
+                    ].filter(Boolean).join("\n\n")
+                });
+                const extracted = extractJson(generated.content);
+                if (!Array.isArray(extracted))
+                    throw new AppError(502, "AI_INVALID_JSON", "定向人物关系归纳结果必须是数组");
+                return {
+                    candidates: extracted.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item)),
+                    callId: generated.callId
+                };
+            }, (completed) => {
+                if (taskId && this.store.getTask(taskId).status === "running") {
+                    this.store.updateTask(taskId, { status: "running", progress: Math.min(92, 72 + Math.round(completed / evidenceBatches.length * 20)) });
+                }
+            });
+            rawCandidates.splice(0, rawCandidates.length, ...aggregationResults.flatMap((result) => result.candidates));
+            callIds.push(...aggregationResults.map((result) => result.callId));
+        }
         const chapterById = new Map(chapters.map((chapter) => [String(chapter.id), chapter]));
         const categories = new Set(["family", "social", "emotional", "conflict", "uncertain"]);
         const merged = new Map();
@@ -3104,6 +3448,10 @@ export class AiManager {
                 skipped.push({ index, reason: "人物引用无效" });
                 return;
             }
+            if (targeted && !selectedCharacterIds.has(fromResolved) && !selectedCharacterIds.has(toResolved)) {
+                skipped.push({ index, reason: "关系不涉及本次选定角色" });
+                return;
+            }
             if (typeof candidate.category !== "string" || !categories.has(candidate.category)) {
                 skipped.push({ index, reason: "关系分类无效" });
                 return;
@@ -3213,10 +3561,17 @@ export class AiManager {
             merged.delete(key);
         }
         const relationshipIds = [];
+        let replacedRelationshipCount = 0;
         this.store.db.transaction(() => {
-            if (scope.type === "book") {
+            if (!targeted && scope.type === "book") {
                 this.store.db.run("DELETE FROM relationships WHERE work_id = ? AND confirmation_status = 'pending' AND locked = 0", workId);
             }
+            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)
+                    this.store.deleteRelationship(String(relationship.id));
+                replacedRelationshipCount = relationshipsToReplace.length;
+            }
             const existing = this.store.listRelationships(workId).filter((relationship) => relationship.confirmationStatus !== "rejected");
             const unorderedPairKey = (fromCharacterId, toCharacterId) => {
                 const pair = [String(fromCharacterId), String(toCharacterId)].sort((left, right) => left.localeCompare(right));
@@ -3413,7 +3768,11 @@ export class AiManager {
             skippedCount: skipped.length,
             fallbackSegmentCount,
             policyOmittedSegmentCount,
-            scopeType: scope.type
+            scopeType: scope.type,
+            targetedCharacterCount: selectedCharacterIds.size,
+            targetedEvidenceCount,
+            aggregationBatchCount,
+            replacedRelationshipCount
         });
         return {
             relationshipIds,
@@ -3424,6 +3783,10 @@ export class AiManager {
             coveredChapterCount: chapters.length,
             fallbackSegmentCount,
             policyOmittedSegmentCount,
+            targetedCharacterIds: [...selectedCharacterIds],
+            targetedEvidenceCount,
+            aggregationBatchCount,
+            replacedRelationshipCount,
             callIds
         };
     }