@musnows/scriverse 0.3.0 → 0.3.1

package/README.en.md

@@ -203,7 +203,7 @@ Expected response:
 {
   "data": {
     "status": "ok",
-    "version": "0.3.0",
+    "version": "0.3.1",
     "protocol": "openai-chat-completions"
   }
 }

package/README.md

@@ -209,7 +209,7 @@ curl http://127.0.0.1:13210/api/health
 {
   "data": {
     "status": "ok",
-    "version": "0.3.0",
+    "version": "0.3.1",
     "protocol": "openai-chat-completions"
   }
 }

package/dist/ai.js

@@ -1,13 +1,24 @@
 import { PLATFORM_AI_WORK_ID } from "./database.js";
 import { AppError, notFound } from "./errors.js";
+import { logger, sanitizeError } from "./logger.js";
 import { currentRequestActor } from "./request-context.js";
 import { fetchSafeAiEndpoint } from "./security.js";
 import { clamp, id, json, maskSecret, normalizeBaseUrl, now } from "./utils.js";
 import { z } from "zod";
+export function aiErrorForLog(error) {
+    const sanitized = sanitizeError(error);
+    const message = typeof sanitized.message === "string" ? sanitized.message : "AI operation failed";
+    const httpStatus = message.match(/^HTTP (\d{3}):/u)?.[1];
+    if (httpStatus)
+        return { name: sanitized.name ?? "Error", message: `Provider returned HTTP ${httpStatus}` };
+    if (message.includes("returned invalid JSON"))
+        return { name: sanitized.name ?? "Error", message: "Provider returned invalid JSON" };
+    return sanitized;
+}
 const allowedParameters = new Set(["temperature", "top_p", "max_tokens", "presence_penalty", "frequency_penalty", "seed"]);
 const DEFAULT_MAX_TOKENS = 32_000;
 const DEFAULT_CONTEXT_WINDOW = 128_000;
-const AGENT_TOOL_IDS = ["story_index", "read_chapters", "query_story_knowledge"];
+const AGENT_TOOL_IDS = ["story_index", "read_chapters", "grep", "query_story_knowledge"];
 const MAX_AGENT_TOOL_ROUNDS = 6;
 const MAX_AGENT_TOOL_CALLS = 12;
 const storyIndexArguments = z.object({
@@ -18,6 +29,10 @@ const readChaptersArguments = z.object({
     chapterIds: z.array(z.string().min(1).max(200)).min(1).max(3),
     include: z.enum(["summary", "content", "both"]).default("both")
 }).strict();
+const grepArguments = z.object({
+    keyword: z.string().trim().min(1).max(200),
+    limit: z.number().int().min(1).max(100).default(20)
+}).strict();
 const queryStoryKnowledgeArguments = z.object({
     query: z.string().trim().min(1).max(200),
     categories: z.array(z.enum(["setting", "character", "race", "organization", "timeline", "relationship", "outline", "foreshadow"])).max(8).default([])
@@ -39,6 +54,14 @@ const AGENT_TOOL_DEFINITIONS = {
             parameters: { type: "object", properties: { chapterIds: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 3 }, include: { type: "string", enum: ["summary", "content", "both"] } }, required: ["chapterIds"], additionalProperties: false }
         }
     },
+    grep: {
+        type: "function",
+        function: {
+            name: "grep",
+            description: "在当前作品的章节正文索引中查询关键字，返回关键字所在的完整段落及章节标题和 ID。默认返回前 20 条，可按需调整 limit。",
+            parameters: { type: "object", properties: { keyword: { type: "string", minLength: 1, maxLength: 200 }, limit: { type: "integer", minimum: 1, maximum: 100, default: 20 } }, required: ["keyword"], additionalProperties: false }
+        }
+    },
     query_story_knowledge: {
         type: "function",
         function: {
@@ -642,6 +665,7 @@ export class AiManager {
         this.validateOutboundUrl = validateOutboundUrl;
         this.contextBuilder = new ContextBuilder(store);
         this.store.setAnalysisTaskQueuedHandler((workId) => this.scheduleAutoRun(workId));
+        logger.info("ai.manager.ready");
     }
     resetAutoRunBatch(workId) {
         this.autoRunBatches.set(workId, { claimed: 0, starting: new Set() });
@@ -662,6 +686,7 @@ export class AiManager {
             void this.drainAutoRun(workId);
         }, 0);
         this.autoRunTimers.set(workId, timer);
+        logger.debug("ai.auto_run.scheduled", { workId });
     }
     startAutoRunBatch(workId) {
         this.store.getWork(workId);
@@ -671,6 +696,11 @@ export class AiManager {
         }
         this.resetAutoRunBatch(workId);
         this.scheduleAutoRun(workId);
+        logger.info("ai.auto_run.batch_started", {
+            workId,
+            concurrency: settings.autoRunConcurrency,
+            batchLimit: settings.autoRunBatchLimit
+        });
         return {
             workId,
             autoRunEnabled: true,
@@ -681,11 +711,13 @@ export class AiManager {
         };
     }
     dispose() {
+        logger.info("ai.manager.disposing", { scheduledWorks: this.autoRunTimers.size, activeTasks: this.taskControllers.size });
         for (const timer of this.autoRunTimers.values())
             clearTimeout(timer);
         this.autoRunTimers.clear();
         this.autoRunBatches.clear();
         this.store.setAnalysisTaskQueuedHandler(null);
+        logger.info("ai.manager.disposed");
     }
     getAutoRunBatch(workId) {
         const existing = this.autoRunBatches.get(workId);
@@ -697,6 +729,7 @@ export class AiManager {
     }
     async drainAutoRun(workId) {
         try {
+            logger.debug("ai.auto_run.drain_started", { workId });
             const settings = this.store.getWorkAiSettings(workId);
             if (!settings.autoRunEnabled)
                 return;
@@ -726,7 +759,8 @@ export class AiManager {
                 });
             }
         }
-        catch {
+        catch (error) {
+            logger.warn("ai.auto_run.drain_failed", { workId, error: aiErrorForLog(error) });
             // 数据库已关闭或作品不存在时忽略自动调度
         }
     }
@@ -795,6 +829,8 @@ export class AiManager {
         const apiKey = this.decryptKey(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, {
@@ -809,11 +845,23 @@ export class AiManager {
             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,
+                ok: true,
+                availableModelCount: availableModels.length,
+                durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000
+            });
             return { ok: true, availableModels, provider: this.getProvider(providerId) };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "连接失败";
             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,
+                ok: false,
+                durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+                error: aiErrorForLog(error)
+            });
             return { ok: false, error: message, provider: this.getProvider(providerId) };
         }
         finally {
@@ -1061,12 +1109,15 @@ export class AiManager {
         const task = this.store.getTask(taskId);
         const workId = String(task.workId);
         const batch = this.getAutoRunBatch(workId);
+        const startedAt = process.hrtime.bigint();
+        logger.info("ai.task.started", { taskId, workId, taskType: task.taskType, modelId: modelId ?? null });
         if (task.status !== "pending")
             throw new AppError(409, "TASK_NOT_PENDING", "只有待执行任务可以运行");
         if (!this.store.isTaskSourceCurrent(taskId)) {
             const expired = this.store.updateTask(taskId, { status: "expired" });
             batch.starting.delete(taskId);
             this.scheduleAutoRun(workId);
+            logger.warn("ai.task.expired", { taskId, workId, durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000 });
             return expired;
         }
         const settings = this.store.getWorkAiSettings(workId);
@@ -1113,15 +1164,20 @@ export class AiManager {
                 });
                 result = { content: generated.content, callId: generated.callId };
             }
-            if (!this.taskCanCommit(taskId))
+            if (!this.taskCanCommit(taskId)) {
+                logger.warn("ai.task.result_discarded", { taskId, workId, durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000 });
                 return this.store.getTask(taskId);
-            return this.store.updateTask(taskId, { status: "review", progress: 100, result });
+            }
+            const completed = this.store.updateTask(taskId, { status: "review", progress: 100, result });
+            logger.info("ai.task.completed", { taskId, workId, durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000 });
+            return completed;
         }
         catch (error) {
             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 }] });
+            logger.error("ai.task.failed", { taskId, workId, durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000, error: aiErrorForLog(error) });
             throw error;
         }
         finally {
@@ -1135,6 +1191,7 @@ export class AiManager {
         this.taskControllers.get(taskId)?.abort(new Error("分析任务已取消"));
         this.taskControllers.delete(taskId);
         this.scheduleAutoRun(String(task.workId));
+        logger.warn("ai.task.cancelled", { taskId, workId: task.workId });
         return task;
     }
     contextBudget(input, model) {
@@ -1288,7 +1345,7 @@ export class AiManager {
             ? [
                 `当前可用作品查询工具：${enabledToolIds.join("、")}。`,
                 "当作者询问当前作品、项目、章节、情节、人物、关系、世界观或设定，而预加载上下文为空或不足时，必须先调用工具主动查询；不得直接声称没有上下文，也不得先要求作者补充本系统已经能够查询的信息。",
-                "整体介绍、作品基本信息、目录或章节定位优先调用 story_index；需要原文事实或精确措辞时调用 read_chapters；查询设定、人物、组织、时间线、关系、大纲或伏笔时调用 query_story_knowledge。",
+                "整体介绍、作品基本信息、目录或章节定位优先调用 story_index；按关键字定位正文段落时调用 grep；已知章节 ID 且需要原文事实或精确措辞时调用 read_chapters；查询设定、人物、组织、时间线、关系、大纲或伏笔时调用 query_story_knowledge。",
                 "根据问题选择最少且必要的工具。工具结果仍不足时才说明未知，并明确已经查询过什么；不要重复无效调用。"
             ].join("\n")
             : "";
@@ -1370,8 +1427,9 @@ export class AiManager {
             : null;
         const schema = name === "story_index" ? storyIndexArguments
             : name === "read_chapters" ? readChaptersArguments
-                : name === "query_story_knowledge" ? queryStoryKnowledgeArguments
-                    : null;
+                : name === "grep" ? grepArguments
+                    : name === "query_story_knowledge" ? queryStoryKnowledgeArguments
+                        : null;
         if (!schema) {
             return {
                 id: toolCall.id,
@@ -1450,6 +1508,18 @@ export class AiManager {
             });
             return { id: toolCall.id, name, calledAt, arguments: { chapterIds, include }, status: "completed", result: { ok: true, data: { chapters, contentLimitChars: 36_000 } } };
         }
+        if (name === "grep") {
+            const { keyword, limit } = args;
+            const matches = this.store.searchChapterParagraphs(workId, keyword, limit);
+            return {
+                id: toolCall.id,
+                name,
+                calledAt,
+                arguments: { keyword, limit },
+                status: "completed",
+                result: { ok: true, data: { keyword, limit, matches } }
+            };
+        }
         if (name === "query_story_knowledge") {
             const { query, categories: categoryList } = args;
             const categories = new Set(categoryList);
@@ -1500,6 +1570,18 @@ export class AiManager {
         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 callStartedAt = process.hrtime.bigint();
+        logger.info("ai.call.started", {
+            callId,
+            workId: input.workId,
+            taskType: input.taskType,
+            providerId: stringValue(provider, "id"),
+            modelId: stringValue(model, "id"),
+            streaming: false,
+            contextChars: context.length,
+            instructionChars: input.instruction.length,
+            toolCount: tools.length
+        });
         try {
             const apiKey = this.decryptKey(provider);
             const endpoint = `${normalizeBaseUrl(stringValue(provider, "base_url"))}/chat/completions`;
@@ -1509,6 +1591,8 @@ export class AiManager {
                 let lastFailure = null;
                 for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
                     let retryable = true;
+                    const attemptStartedAt = process.hrtime.bigint();
+                    logger.info("ai.call.attempt_started", { callId, attempt, maximumAttempts, toolChoice });
                     try {
                         const candidate = await this.scheduleProviderRequest(provider, input.signal, async () => {
                             const controller = new AbortController();
@@ -1532,6 +1616,13 @@ export class AiManager {
                                 input.signal?.removeEventListener("abort", forwardAbort);
                             }
                         });
+                        logger.info("ai.call.attempt_completed", {
+                            callId,
+                            attempt,
+                            status: candidate.status,
+                            ok: candidate.ok,
+                            durationMs: Number(process.hrtime.bigint() - attemptStartedAt) / 1_000_000
+                        });
                         if (candidate.ok) {
                             try {
                                 return JSON.parse(candidate.body);
@@ -1548,6 +1639,13 @@ export class AiManager {
                     }
                     catch (error) {
                         lastFailure = error;
+                        logger.warn("ai.call.attempt_failed", {
+                            callId,
+                            attempt,
+                            retryable: retryable && attempt < maximumAttempts && !input.signal?.aborted,
+                            durationMs: Number(process.hrtime.bigint() - attemptStartedAt) / 1_000_000,
+                            error: aiErrorForLog(error)
+                        });
                         if (input.signal?.aborted)
                             throw error;
                         if (!retryable || attempt >= maximumAttempts)
@@ -1599,6 +1697,7 @@ export class AiManager {
                 });
                 for (const toolCall of toolCalls) {
                     const execution = this.executeAgentTool(input.workId, toolCall);
+                    logger.info("ai.tool_call.completed", { callId, toolName: execution.name, status: execution.status, round });
                     executedToolCalls.push(execution);
                     processSteps.push({ id: id("process"), type: "tool", round, toolCall: execution, createdAt: execution.calledAt });
                     input.onToolCall?.(execution, round);
@@ -1622,11 +1721,30 @@ export class AiManager {
                 throw new Error(`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);
-            return { callId, content, outputTokens: resolveOutputTokens(payload.usage, content), provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: executedToolCalls, processSteps };
+            const outputTokens = resolveOutputTokens(payload.usage, content);
+            logger.info("ai.call.completed", {
+                callId,
+                workId: input.workId,
+                taskType: input.taskType,
+                streaming: false,
+                durationMs: Number(process.hrtime.bigint() - callStartedAt) / 1_000_000,
+                outputChars: content.length,
+                outputTokens,
+                toolCallCount: executedToolCalls.length
+            });
+            return { callId, content, outputTokens, provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: executedToolCalls, processSteps };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "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,
+                workId: input.workId,
+                taskType: input.taskType,
+                streaming: false,
+                durationMs: Number(process.hrtime.bigint() - callStartedAt) / 1_000_000,
+                error: aiErrorForLog(error)
+            });
             throw new AppError(502, "AI_CALL_FAILED", "AI 调用失败", { callId, failure: message });
         }
     }
@@ -1642,6 +1760,17 @@ export class AiManager {
         const callId = id("call");
         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();
+        logger.info("ai.call.started", {
+            callId,
+            workId: input.workId,
+            taskType: input.taskType,
+            providerId: stringValue(provider, "id"),
+            modelId: stringValue(model, "id"),
+            streaming: true,
+            contextChars: context.length,
+            instructionChars: input.instruction.length
+        });
         try {
             const apiKey = this.decryptKey(provider);
             const endpoint = `${normalizeBaseUrl(stringValue(provider, "base_url"))}/chat/completions`;
@@ -1652,6 +1781,8 @@ export class AiManager {
             const thinkingStepId = id("process");
             const thinkingCreatedAt = now();
             for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
+                const attemptStartedAt = process.hrtime.bigint();
+                logger.info("ai.call.attempt_started", { callId, attempt, maximumAttempts, streaming: true });
                 try {
                     const candidate = await this.scheduleProviderRequest(provider, input.signal, async () => {
                         const controller = new AbortController();
@@ -1684,6 +1815,14 @@ export class AiManager {
                             input.signal?.removeEventListener("abort", forwardAbort);
                         }
                     });
+                    logger.info("ai.call.attempt_completed", {
+                        callId,
+                        attempt,
+                        status: candidate.status,
+                        ok: candidate.ok,
+                        durationMs: Number(process.hrtime.bigint() - attemptStartedAt) / 1_000_000,
+                        streaming: true
+                    });
                     if (candidate.ok) {
                         streamedResult = candidate.result;
                         break;
@@ -1694,6 +1833,14 @@ export class AiManager {
                 }
                 catch (error) {
                     lastFailure = error;
+                    logger.warn("ai.call.attempt_failed", {
+                        callId,
+                        attempt,
+                        retryable: !input.signal?.aborted && !emitted && attempt < maximumAttempts,
+                        durationMs: Number(process.hrtime.bigint() - attemptStartedAt) / 1_000_000,
+                        streaming: true,
+                        error: aiErrorForLog(error)
+                    });
                     if (input.signal?.aborted || emitted || attempt >= maximumAttempts)
                         throw error;
                 }
@@ -1707,11 +1854,28 @@ export class AiManager {
                 ? [{ 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);
+            logger.info("ai.call.completed", {
+                callId,
+                workId: input.workId,
+                taskType: input.taskType,
+                streaming: true,
+                durationMs: Number(process.hrtime.bigint() - callStartedAt) / 1_000_000,
+                outputChars: content.length,
+                outputTokens
+            });
             return { callId, content, outputTokens, provider: this.mapProvider(provider), model: this.mapModel(model), context, toolCalls: [], processSteps };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "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,
+                workId: input.workId,
+                taskType: input.taskType,
+                streaming: true,
+                durationMs: Number(process.hrtime.bigint() - callStartedAt) / 1_000_000,
+                error: aiErrorForLog(error)
+            });
             throw new AppError(502, "AI_CALL_FAILED", "AI 调用失败", { callId, failure: message });
         }
     }
@@ -3206,6 +3370,13 @@ export class AiManager {
             };
             signal?.addEventListener("abort", onAbort, { once: true });
             schedule.queue.push(entry);
+            logger.debug("ai.provider_queue.enqueued", {
+                providerId,
+                active: schedule.active,
+                queued: schedule.queue.length,
+                concurrencyLimit: schedule.concurrencyLimit,
+                rpmLimit: schedule.rpmLimit
+            });
             this.pumpProviderSchedule(providerId);
         });
     }
@@ -3230,16 +3401,19 @@ export class AiManager {
             }
             schedule.active += 1;
             schedule.starts.push(Date.now());
+            logger.debug("ai.provider_queue.dispatched", { providerId, active: schedule.active, queued: schedule.queue.length });
             void Promise.resolve()
                 .then(entry.run)
                 .then(entry.resolve, entry.reject)
                 .finally(() => {
                 schedule.active -= 1;
+                logger.debug("ai.provider_queue.finished", { providerId, active: schedule.active, queued: schedule.queue.length });
                 this.pumpProviderSchedule(providerId);
             });
         }
         if (schedule.queue.length > 0 && schedule.active < schedule.concurrencyLimit && schedule.starts.length >= schedule.rpmLimit) {
             const delay = Math.max(1, (schedule.starts[0] ?? Date.now()) + 60_000 - Date.now() + 1);
+            logger.info("ai.provider_queue.rate_limited", { providerId, queued: schedule.queue.length, retryInMs: delay });
             schedule.timer = setTimeout(() => this.pumpProviderSchedule(providerId), delay);
             schedule.timer.unref?.();
         }