@musnows/scriverse 0.8.7 → 0.9.0

package/dist/app.js

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os";
 import { pipeline } from "node:stream/promises";
 import { z, ZodError } from "zod";
 import { AI_PROVIDER_PROTOCOL_OPTIONS, AI_PROVIDER_PROTOCOLS, AI_THINKING_TYPES, MAX_TOKENS_PARAMETERS } from "./ai-protocol.js";
+import { MAX_AI_ANALYSIS_TIMEOUT_SECONDS, MIN_AI_ANALYSIS_TIMEOUT_SECONDS } from "./ai-analysis-timeout.js";
 import { aiConversationExportContentDisposition, exportAiConversationMarkdown } from "./ai-conversation-export.js";
 import { DEFAULT_AI_CHAT_TAB_LIMIT } from "./ai-chat-tab-limit.js";
 import { MAX_AI_STREAM_IDLE_TIMEOUT_SECONDS, MIN_AI_STREAM_IDLE_TIMEOUT_SECONDS, normalizeAiStreamIdleTimeoutSeconds } from "./ai-stream-timeout.js";
@@ -29,10 +30,12 @@ import { isOfficialGoogleVertexBaseUrl, parseGoogleServiceAccount } from "./goog
 import { HYBRID_SEARCH_TYPES, MAXIMUM_WORK_SEARCH_QUERY_LENGTH, readableHybridSearchTypes } from "./hybrid-search.js";
 import { applyImportFileHints, parseNovelText } from "./parser.js";
 import { aiConversationTaskTypes, attachmentPermissionModules, RECYCLE_BIN_RETENTION_DAYS, Store, versionedEntityTypes, WORK_AGENT_TOOL_IDS } from "./store.js";
+import { composeRoleplayStoredUserContent } from "./roleplay-turn.js";
 import { paginated, parsePagination } from "./pagination.js";
 import { normalizeUploadFileName } from "./utils.js";
 import { assertSafeAiEndpoint, assertSafeS3Endpoint, createApiRateLimitMiddleware, createAuthenticationRateLimitMiddleware, createBasicAuthMiddleware, createCaptchaRateLimitMiddleware, createExpensiveApiRateLimitMiddleware, createSameOriginMiddleware, createSecurityHeadersMiddleware, createUploadRateLimitMiddleware, enforceCaseInsensitiveRouting, normalizeApiPath, resolveTrustProxySetting, verifySetupToken } from "./security.js";
 import { ImageCaptchaService } from "./image-captcha.js";
+import { OfflineSyncService } from "./offline-sync.js";
 import { assertSafeImportedPlainText, decodeUtf8ImportedText } from "./import-security.js";
 import { InvalidRasterImageError, readRasterImageMetadata } from "./image-metadata.js";
 import { createRequestLoggingMiddleware, sanitizeRequestPath } from "./http-logging.js";
@@ -40,6 +43,7 @@ import { accountReference, logger, sanitizeError } from "./logger.js";
 import { currentRequestActor, runWithRequestActor } from "./request-context.js";
 import { S3BackupManager } from "./s3-backup.js";
 import { APP_VERSION } from "./version.js";
+import { DESKTOP_SYNC_PROTOCOL, desktopCompatibilityMetadata } from "./desktop-protocol.js";
 import { ReleaseUpdateChecker } from "./release-update.js";
 import { CHARACTER_AVATAR_IMAGE_MAX_BYTES, DEFAULT_IMAGE_UPLOAD_LIMITS, formatUploadLimit } from "./upload-limits.js";
 import { canReadWorkModule, canWriteWorkModule, chapterAnnotationPermissionModule, fullWorkModulePermissions, proseReplacementPermissionModules } from "./work-permissions.js";
@@ -126,6 +130,14 @@ const loginSchema = z.object({
     password: z.string().max(200),
     ...captchaFields
 }).strict();
+const desktopLoginSchema = z.object({
+    username: z.string().trim().min(1).max(100),
+    password: z.string().max(200),
+    desktopId: z.string().uuid(),
+    profileId: z.string().uuid(),
+    clientVersion: z.string().trim().min(1).max(80),
+    ...captchaFields
+}).strict();
 const userUpdateSchema = z.object({ role: z.enum(["admin", "user"]).optional(), status: z.enum(["active", "disabled"]).optional() }).strict();
 const memberRoleValueSchema = z.enum(["editor", "settings-editor", "viewer"]);
 const moduleAccessSchema = z.enum(["none", "read", "write"]);
@@ -201,6 +213,7 @@ const workSchema = z.object({
     coverUrl: z.string().url().nullable().optional(),
     tags: optionalStrings
 });
+const workOfflineAccessSchema = z.object({ enabled: z.boolean() }).strict();
 const settingSchema = z.object({
     title: nonEmpty.max(200),
     category: nonEmpty.max(100),
@@ -212,6 +225,31 @@ const settingSchema = z.object({
     scope: jsonObject.optional(),
     authorNote: z.string().max(20_000).optional()
 });
+const chapterSyncSnapshotSchema = z.object({
+    title: nonEmpty.max(300),
+    content: z.string().max(2_000_000),
+    chapterType: chapterTypeSchema
+}).strict();
+const settingSyncSnapshotSchema = settingSchema.strict();
+const syncMutationBaseFields = {
+    mutationId: z.string().uuid(),
+    entityId: identifier,
+    operation: z.literal("update"),
+    baseVersionNo: z.number().int().positive(),
+    changeNote: z.string().trim().min(1).max(500).default("Desktop 离线修改")
+};
+const syncPushSchema = z.object({
+    clientId: z.string().uuid(),
+    mutations: z.array(z.discriminatedUnion("entityType", [
+        z.object({ ...syncMutationBaseFields, entityType: z.literal("chapter"), localSnapshot: chapterSyncSnapshotSchema }).strict(),
+        z.object({ ...syncMutationBaseFields, entityType: z.literal("setting"), localSnapshot: settingSyncSnapshotSchema }).strict()
+    ])).min(1).max(20)
+}).strict().superRefine((input, context) => {
+    const mutationIds = input.mutations.map((mutation) => mutation.mutationId);
+    if (new Set(mutationIds).size !== mutationIds.length) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["mutations"], message: "同一批次不能重复 mutationId" });
+    }
+});
 const globalReplaceSchema = z.object({
     find: z.string().min(1).max(500),
     replacement: z.string().max(200_000),
@@ -378,6 +416,7 @@ const providerBaseSchema = z.object({
     note: z.string().max(10_000).optional(),
     concurrencyLimit: z.number().int().min(1).max(100).optional(),
     rpmLimit: z.number().int().min(1).max(10_000).optional(),
+    analysisTimeoutSeconds: z.number().int().min(MIN_AI_ANALYSIS_TIMEOUT_SECONDS).max(MAX_AI_ANALYSIS_TIMEOUT_SECONDS).optional(),
     dailyTokenQuota: z.number().int().min(1, "Token 额度必须设置大于 0").max(2_000_000_000).nullable().optional(),
     monthlyTokenQuota: z.number().int().min(1, "Token 额度必须设置大于 0").max(2_000_000_000).nullable().optional()
 });
@@ -603,6 +642,51 @@ const contextSchema = z.object({
     includeBookSummary: z.boolean().optional(),
     includeSettingInfo: z.boolean().optional()
 });
+const desktopLocalAiRuntimeModelSchema = z.object({
+    id: identifier,
+    providerId: identifier,
+    providerName: nonEmpty.max(200),
+    protocol: z.literal("openai-chat-completions"),
+    maxTokensParameter: z.enum(MAX_TOKENS_PARAMETERS),
+    thinkingType: z.enum(["enabled", "adaptive"]),
+    concurrencyLimit: z.number().int().min(1).max(100),
+    rpmLimit: z.number().int().min(1).max(10_000),
+    analysisTimeoutSeconds: z.number().int().min(MIN_AI_ANALYSIS_TIMEOUT_SECONDS).max(MAX_AI_ANALYSIS_TIMEOUT_SECONDS),
+    displayName: nonEmpty.max(200),
+    modelId: nonEmpty.max(300),
+    purposes: z.array(z.enum(TASK_TYPES)).min(1).max(TASK_TYPES.length),
+    contextNote: z.string().max(10_000),
+    contextWindow: z.number().int().min(32_768).max(2_000_000),
+    outputNote: z.string().max(10_000),
+    preset: z.object({
+        temperature: z.number().min(0).max(2),
+        max_tokens: z.number().int().min(1).max(2_000_000)
+    }).strict(),
+    thinkingEnabled: z.boolean(),
+    thinkingEffort: z.enum(["default", "auto", "low", "medium", "high", "xhigh", "max"]),
+    multimodalEnabled: z.boolean(),
+    note: z.string().max(10_000)
+}).strict().refine((input) => input.preset.max_tokens < input.contextWindow, {
+    path: ["preset", "max_tokens"],
+    message: "本地 AI 最大输出令牌数必须小于上下文窗口"
+});
+const desktopLocalAiRunSchema = z.object({
+    taskType: z.enum(["chat", "continue", "polish"]),
+    instruction: nonEmpty.max(100_000),
+    scope: contextSchema,
+    runtimeModel: desktopLocalAiRuntimeModelSchema,
+    conversationId: identifier.optional(),
+    currentMessageId: identifier.optional(),
+    citations: aiCitationsSchema.optional(),
+    imageAttachmentIds: z.array(identifier).max(4).optional(),
+    sceneDirection: z.string().max(20_000).optional()
+}).strict();
+const desktopLocalAiCompletionResponseSchema = z.object({
+    requestId: identifier,
+    status: z.number().int().min(100).max(599),
+    body: z.string().max(4 * 1024 * 1024),
+    retryAfter: z.string().max(500).optional()
+}).strict();
 /** 创建任务 API 的分析类型校验：仅允许可新建类型，历史类型在运行层保留防御性拒绝。 */
 export const creatableAnalysisTaskTypeSchema = z.enum(CREATABLE_ANALYSIS_TASK_TYPES);
 const relationshipSourceRefSchema = z.object({
@@ -757,6 +841,9 @@ function data(response, value, status = 200) {
 function noContent(response) {
     response.status(204).end();
 }
+function hasInteractiveSession(request) {
+    return request.authMethod === "session" || request.authMethod === "desktop-session";
+}
 async function sendEpub(response, archive, title, fallbackStem) {
     response.type(EPUB_MIME_TYPE);
     response.setHeader("Content-Disposition", epubContentDisposition(title, fallbackStem));
@@ -1004,7 +1091,16 @@ function redactAiConversation(record, permissions) {
         result.agentTools = [
             ...(permissions.characters !== "none" ? ["recall_self"] : []),
             ...(permissions.characters !== "none" && permissions.relationships !== "none" ? ["recall_relationship"] : []),
+            ...(permissions.characters !== "none"
+                && (permissions.relationships !== "none" || permissions.organizations !== "none" || permissions.timeline !== "none")
+                ? ["recall_other"]
+                : []),
+            ...((permissions.races !== "none" || permissions.organizations !== "none" || permissions.settings !== "none") ? ["recall_known"] : []),
             ...(permissions.prose !== "none" ? ["recall_story"] : []),
+            ...["settings", "characters", "races", "organizations", "timeline", "relationships", "outlines"]
+                .some((module) => permissions[module] !== "none")
+                ? ["image"]
+                : [],
             "calculate_time"
         ];
     }
@@ -1105,7 +1201,8 @@ export function createRuntime(options) {
     const characterAvatarStorage = new AttachmentStorage(options.characterAvatarDirectory
         ?? (temporaryStorageRoot ? join(temporaryStorageRoot, "character-avatars") : join(dirname(options.databasePath), "character-avatars")), CHARACTER_AVATAR_IMAGE_MAX_BYTES);
     mkdirSync(characterAvatarStorage.temporaryDirectory, { recursive: true, mode: 0o700 });
-    const auth = new UserAuthService(database);
+    const credentialVault = new CredentialVault(options.masterSecret);
+    const auth = new UserAuthService(database, credentialVault);
     const collaborationPresence = new CollaborationPresence(45_000, Date.now, 120_000, 50, { store: new PresenceStore(database) });
     const publishCollaborativeChange = (workId, pageKey, options = {}) => {
         const actor = currentRequestActor();
@@ -1136,6 +1233,7 @@ export function createRuntime(options) {
         ? auth.listUsers().find((user) => user.status === "active") ?? null
         : null;
     const store = new Store(database);
+    const offlineSync = new OfflineSyncService(database, store);
     const platformAiSettings = store.getPlatformAiSettings();
     const platformAiStreamIdleTimeoutMs = normalizeAiStreamIdleTimeoutSeconds(Number(platformAiSettings.streamIdleTimeoutSeconds)) * 1_000;
     let attachmentCleanupChain = Promise.resolve();
@@ -1197,7 +1295,6 @@ export function createRuntime(options) {
         return lockedModelId ?? requestedModelId;
     };
     const captcha = new ImageCaptchaService({ revealAnswer: options.revealCaptchaAnswer === true });
-    const credentialVault = new CredentialVault(options.masterSecret);
     const backups = new S3BackupManager(database, credentialVault, store, attachmentStorage, {
         ...options.backupOptions,
         characterAvatarStorage,
@@ -1215,11 +1312,11 @@ export function createRuntime(options) {
     });
     if (!options.liteLlmPriceCache && options.liteLlmPriceCachePath)
         liteLlmPriceCache.start();
-    const ai = new AiManager(store, credentialVault, options.fetchImpl ?? fetch, options.developmentServer === true
+    const ai = new AiManager(store, credentialVault, options.fetchImpl ?? fetch, options.developmentServer === true || options.disableAiEndpointValidation === true
         ? undefined
         : options.security ? (url) => assertSafeAiEndpoint(url, options.security?.allowPrivateAiEndpoints) : undefined, (task, actor) => {
         const requiredModules = analysisTaskReadModules(task.taskType, task.scope);
-        const creator = actor ? null : database.get("SELECT created_by_user_id FROM analysis_tasks WHERE id = ?", String(task.id));
+        const creator = actor ? null : database.get("SELECT created_by_user_id, created_via_api_key FROM analysis_tasks WHERE id = ?", String(task.id));
         const userId = actor?.userId ?? (typeof creator?.created_by_user_id === "string" ? creator.created_by_user_id : null);
         if (!userId)
             return;
@@ -1229,13 +1326,14 @@ export function createRuntime(options) {
         auth.assertWorkAccess(user, String(task.workId), {
             read: requiredModules,
             write: ["ai-analysis"]
-        }, false, actor?.allowAdminAccess ?? false);
+        }, false, actor?.allowAdminAccess ?? (user.role === "admin" && Number(creator?.created_via_api_key) !== 1));
     }, attachmentStorage, {
         interactiveStreamIdleTimeoutMs: options.aiStreamIdleTimeoutMs ?? platformAiStreamIdleTimeoutMs,
         retryPolicy: options.aiRetryPolicy,
         retrySleep: options.aiRetrySleep,
         aiChatImageMaxBytes: uploadLimits.chatImageBytes,
-        liteLlmPriceCache
+        liteLlmPriceCache,
+        allowPrivateAiEndpoints: options.security?.allowPrivateAiEndpoints === true
     });
     const app = express();
     enforceCaseInsensitiveRouting(app);
@@ -1279,6 +1377,7 @@ export function createRuntime(options) {
             status: "ok",
             bootId,
             version: APP_VERSION,
+            ...desktopCompatibilityMetadata(),
             versionLabel: options.betaVersionLabel ?? null,
             protocol: "openai-chat-completions",
             protocols: [...AI_PROVIDER_PROTOCOLS],
@@ -1297,9 +1396,11 @@ export function createRuntime(options) {
     app.use(createApiRateLimitMiddleware(options.security?.apiRateLimit, options.security?.apiRateWindowMs));
     if (options.security?.enforceSameOrigin ?? true)
         app.use(createSameOriginMiddleware());
+    app.use("/api/sync/works", express.json({ limit: "3mb" }));
     app.use(express.json({ limit: "2mb" }));
     app.get("/api/auth/session", (request, response) => {
-        const session = auth.authenticate(request);
+        const desktopSession = auth.authenticateDesktop(request);
+        const session = desktopSession ? null : auth.authenticate(request);
         const registrationOpen = options.security?.allowRegistration === true;
         const setupRequired = !auth.hasUsers();
         const setupTokenRequired = setupRequired && Boolean(options.security?.setupToken);
@@ -1308,8 +1409,17 @@ export function createRuntime(options) {
             data(response, { authenticated: true, user: developmentUser, csrfToken: null, bootId, setupRequired: false, setupTokenRequired: false, registrationOpen });
             return;
         }
-        data(response, session
-            ? { authenticated: true, user: session.user, csrfToken: session.csrfToken, bootId, setupRequired: false, setupTokenRequired: false, registrationOpen }
+        const interactiveSession = desktopSession ?? session;
+        data(response, interactiveSession
+            ? {
+                authenticated: true,
+                user: interactiveSession.user,
+                csrfToken: desktopSession ? null : session.csrfToken,
+                bootId,
+                setupRequired: false,
+                setupTokenRequired: false,
+                registrationOpen
+            }
             : { authenticated: false, user: null, csrfToken: null, bootId, setupRequired, setupTokenRequired, registrationOpen });
     });
     app.get("/api/auth/captcha", (_request, response) => {
@@ -1339,6 +1449,19 @@ export function createRuntime(options) {
         logger.info("auth.login.succeeded", { actorRef: accountReference(result.session.user.userId) });
         data(response, { user: result.session.user, csrfToken: result.session.csrfToken });
     });
+    app.post("/api/desktop/auth/login", (request, response) => {
+        const input = parse(desktopLoginSchema, request.body);
+        captcha.consume(input.captchaId, input.captchaAnswer);
+        const result = auth.loginDesktop(input.username, input.password, {
+            desktopId: input.desktopId,
+            profileId: input.profileId,
+            clientVersion: input.clientVersion
+        });
+        response.setHeader("Cache-Control", "no-store");
+        runWithRequestActor(result.session.user, () => store.audit(null, "user.logged-in", "user", result.session.user.userId, { source: "desktop" }));
+        logger.info("auth.desktop_login.succeeded", { actorRef: accountReference(result.session.user.userId) });
+        data(response, { token: result.token, expiresAt: result.session.expiresAt, user: result.session.user });
+    });
     app.use(createUserSessionMiddleware(auth, {
         disabled: options.disableUserAuth === true,
         resolveBypassUser: getDevelopmentUser
@@ -1353,14 +1476,17 @@ export function createRuntime(options) {
         data(response, { authenticated: true, user: request.authUser, apiKeyPrefix: request.authApiKey?.prefix ?? null });
     });
     app.delete("/api/auth/session", (request, response) => {
-        if (request.authSession)
+        if (request.authDesktopSession)
+            auth.revokeDesktop(request.authDesktopSession.id);
+        if (request.authSession) {
             auth.revoke(request.authSession.id);
-        clearSessionCookie(response, request.secure);
+            clearSessionCookie(response, request.secure);
+        }
         noContent(response);
     });
     app.post("/api/auth/onboarding/complete", (request, response) => {
-        if (!request.authUser || request.authMethod !== "session")
-            throw new AppError(401, "SESSION_REQUIRED", "请使用网页会话完成新手引导");
+        if (!request.authUser || !hasInteractiveSession(request))
+            throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话完成新手引导");
         parse(z.object({}).strict(), request.body ?? {});
         const updated = auth.completeOnboarding(request.authUser.userId);
         store.audit(null, "user.onboarding-completed", "user", updated.userId);
@@ -1410,21 +1536,38 @@ export function createRuntime(options) {
         data(response, updated);
     });
     app.patch("/api/auth/password", (request, response) => {
-        if (!request.authUser || !request.authSession)
+        const activeSession = request.authDesktopSession
+            ? { id: request.authDesktopSession.id, kind: "desktop" }
+            : request.authSession
+                ? { id: request.authSession.id, kind: "browser" }
+                : null;
+        if (!request.authUser || !activeSession)
             throw new AppError(401, "AUTH_REQUIRED", "请先登录");
         const input = parse(passwordChangeSchema, request.body);
-        auth.changePassword(request.authUser.userId, request.authSession.id, input.currentPassword, input.newPassword);
+        auth.changePassword(request.authUser.userId, activeSession.id, input.currentPassword, input.newPassword, activeSession.kind);
         store.audit(null, "user.password-changed", "user", request.authUser.userId);
         noContent(response);
     });
     app.get("/api/auth/api-key", (request, response) => {
-        if (!request.authUser || request.authMethod !== "session")
-            throw new AppError(401, "SESSION_REQUIRED", "请使用网页会话管理 API Key");
+        if (!request.authUser || !hasInteractiveSession(request))
+            throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话管理 API Key");
         data(response, auth.getApiKeyStatus(request.authUser.userId));
     });
+    app.post("/api/auth/api-key/reveal", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request))
+            throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话管理 API Key");
+        parse(z.object({}).strict(), request.body ?? {});
+        const userId = request.authUser.userId;
+        const revealed = database.transaction(() => {
+            const secret = auth.revealApiKey(userId);
+            store.audit(null, "user.api-key-copied", "user", userId, { prefix: secret.prefix });
+            return { apiKey: secret.apiKey };
+        });
+        data(response, revealed);
+    });
     app.post("/api/auth/api-key/reset", (request, response) => {
-        if (!request.authUser || request.authMethod !== "session")
-            throw new AppError(401, "SESSION_REQUIRED", "请使用网页会话管理 API Key");
+        if (!request.authUser || !hasInteractiveSession(request))
+            throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话管理 API Key");
         parse(z.object({}).strict(), request.body ?? {});
         const userId = request.authUser.userId;
         const result = database.transaction(() => {
@@ -1512,8 +1655,8 @@ export function createRuntime(options) {
         data(response, pagination ? store.getWorkDirectoryPage(request.params.workId, pagination) : store.getWorkDirectory(request.params.workId));
     });
     app.post("/api/works/:workId/presence", (request, response) => {
-        if (!request.authUser || request.authMethod !== "session")
-            throw new AppError(401, "SESSION_REQUIRED", "请使用网页会话上报协作状态");
+        if (!request.authUser || !hasInteractiveSession(request))
+            throw new AppError(401, "SESSION_REQUIRED", "请使用交互式会话上报协作状态");
         const input = parse(presenceHeartbeatSchema, request.body);
         data(response, collaborationPresence.heartbeat(request.params.workId, input.clientId, {
             userId: request.authUser.userId,
@@ -1564,6 +1707,77 @@ export function createRuntime(options) {
         const { expectedVersionNo, changeNote, ...input } = parse(workSchema.partial().extend({ expectedVersionNo: expectedVersionNoSchema, changeNote: changeNoteSchema }).strict(), request.body);
         data(response, store.updateWork(request.params.workId, input, expectedVersionNo, "manual", null, changeNote));
     });
+    app.patch("/api/works/:workId/offline-access", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用网页或 Desktop 登录管理离线访问");
+        }
+        const input = parse(workOfflineAccessSchema, request.body);
+        data(response, store.setWorkOfflineAccess(request.params.workId, input.enabled));
+    });
+    app.post("/api/sync/works/:workId/snapshots", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录创建同步快照");
+        }
+        parse(z.object({}).strict(), request.body ?? {});
+        response.setHeader("Cache-Control", "no-store");
+        data(response, offlineSync.createSnapshot(request.params.workId, request.authUser.userId), 201);
+    });
+    app.get("/api/sync/works/:workId/changes", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录读取同步变更");
+        }
+        const query = parse(z.object({
+            after: z.coerce.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
+            limit: z.coerce.number().int().min(1).max(200).default(200)
+        }).strict(), request.query);
+        response.setHeader("Cache-Control", "no-store");
+        data(response, offlineSync.listChanges(request.params.workId, query.after, query.limit));
+    });
+    app.post("/api/sync/works/:workId/push", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录提交离线变更");
+        }
+        if (Buffer.byteLength(JSON.stringify(request.body ?? {}), "utf8") > DESKTOP_SYNC_PROTOCOL.maxMutationBytes) {
+            throw new AppError(413, "SYNC_PUSH_TOO_LARGE", `同步批次不能超过 ${DESKTOP_SYNC_PROTOCOL.maxMutationBytes} bytes`);
+        }
+        const input = parse(syncPushSchema, request.body);
+        response.setHeader("Cache-Control", "no-store");
+        data(response, offlineSync.pushMutations(request.params.workId, request.authUser.userId, input.clientId, input.mutations));
+    });
+    app.get("/api/sync/works/:workId/mutations/:mutationId", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录读取同步变更结果");
+        }
+        const mutationId = parse(z.string().uuid(), request.params.mutationId);
+        response.setHeader("Cache-Control", "no-store");
+        data(response, offlineSync.getMutationResult(request.params.workId, request.authUser.userId, mutationId));
+    });
+    app.get("/api/sync/snapshots/:snapshotId/items", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录读取同步快照");
+        }
+        const snapshotId = parse(z.string().uuid(), request.params.snapshotId);
+        const snapshot = offlineSync.describeOwnedSnapshot(snapshotId, request.authUser.userId);
+        auth.assertActiveWork(snapshot.workId);
+        auth.assertWorkAccess(request.authUser, snapshot.workId, { read: ["prose", "settings"] }, false, true);
+        const query = parse(z.object({
+            after: z.coerce.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
+            limit: z.coerce.number().int().min(1).max(100).default(100)
+        }).strict(), request.query);
+        response.setHeader("Cache-Control", "no-store");
+        data(response, offlineSync.readSnapshotPage(snapshotId, request.authUser.userId, query.after, query.limit));
+    });
+    app.delete("/api/sync/snapshots/:snapshotId", (request, response) => {
+        if (!request.authUser || !hasInteractiveSession(request)) {
+            throw new AppError(401, "SESSION_REQUIRED", "请使用 Desktop 或网页登录删除同步快照");
+        }
+        const snapshotId = parse(z.string().uuid(), request.params.snapshotId);
+        const snapshot = offlineSync.describeOwnedSnapshot(snapshotId, request.authUser.userId);
+        auth.assertActiveWork(snapshot.workId);
+        auth.assertWorkAccess(request.authUser, snapshot.workId, { read: ["prose", "settings"] }, false, true);
+        offlineSync.deleteSnapshot(snapshotId, request.authUser.userId);
+        noContent(response);
+    });
     app.delete("/api/works/:workId", async (request, response) => {
         const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
         ai.deleteWork(request.params.workId, input.expectedVersionNo);
@@ -1725,7 +1939,7 @@ export function createRuntime(options) {
     });
     app.get("/api/works/:workId/chapter-annotations", (request, response) => {
         const pagination = parsePagination(request.query);
-        const permissions = requestPermissions(request, request.params.workId);
+        const permissions = requestPermissions(request, String(request.params.workId));
         data(response, pagination
             ? store.listWorkChapterAnnotationsPage(request.params.workId, pagination, readableChapterAnnotationKinds(permissions))
             : store.listWorkChapterAnnotations(request.params.workId, readableChapterAnnotationKinds(permissions)));
@@ -1866,6 +2080,10 @@ export function createRuntime(options) {
         data(response, store.createDraft(request.params.workId, parse(draftSchema, request.body)), 201);
     });
     app.get("/api/drafts/:draftId", (request, response) => data(response, store.getDraft(request.params.draftId)));
+    app.patch("/api/drafts/:draftId/favorite", (request, response) => {
+        const input = parse(z.object({ isFavorite: z.boolean() }).strict(), request.body);
+        data(response, store.setDraftFavorite(request.params.draftId, input.isFavorite));
+    });
     app.patch("/api/drafts/:draftId", (request, response) => {
         const { changeNote, expectedVersionNo, ...input } = parse(draftSchema.partial().extend({
             changeNote: changeNoteSchema,
@@ -1889,6 +2107,12 @@ export function createRuntime(options) {
     });
     app.get("/api/works/:workId/settings/context", (request, response) => data(response, store.listSettings(request.params.workId, true)));
     app.get("/api/settings/:settingId", (request, response) => data(response, store.getSetting(request.params.settingId)));
+    app.patch("/api/settings/:settingId/favorite", (request, response) => {
+        const input = parse(z.object({ isFavorite: z.boolean() }).strict(), request.body);
+        const setting = store.setSettingFavorite(request.params.settingId, input.isFavorite);
+        publishEntityChange(String(setting.workId), "setting", String(setting.id));
+        data(response, setting);
+    });
     app.patch("/api/settings/:settingId", (request, response) => {
         const { changeNote, expectedVersionNo, ...input } = parse(settingSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
         const setting = store.updateSetting(request.params.settingId, input, "manual", null, changeNote, expectedVersionNo);
@@ -1976,6 +2200,12 @@ export function createRuntime(options) {
         }
         data(response, redactCharacterLinks(result.character, requestPermissions(request)));
     });
+    app.patch("/api/characters/:characterId/favorite", (request, response) => {
+        const input = parse(z.object({ isFavorite: z.boolean() }).strict(), request.body);
+        const character = store.setCharacterFavorite(request.params.characterId, input.isFavorite);
+        publishEntityChange(String(character.workId), "character", String(character.id));
+        data(response, redactCharacterLinks(character, requestPermissions(request)));
+    });
     app.patch("/api/characters/:characterId", (request, response) => {
         const { changeNote, expectedVersionNo, ...input } = parse(characterUpdateSchema.extend({ expectedVersionNo: expectedVersionNoSchema }), request.body);
         const character = store.updateCharacter(request.params.characterId, input, "manual", null, changeNote, expectedVersionNo);
@@ -2184,6 +2414,12 @@ export function createRuntime(options) {
     app.get("/api/organizations/:organizationId", (request, response) => {
         data(response, redactOrganizationMembers(store.getOrganization(request.params.organizationId), requestPermissions(request)));
     });
+    app.patch("/api/organizations/:organizationId/favorite", (request, response) => {
+        const input = parse(z.object({ isFavorite: z.boolean() }).strict(), request.body);
+        const organization = store.setOrganizationFavorite(request.params.organizationId, input.isFavorite);
+        publishEntityChange(String(organization.workId), "organization", String(organization.id));
+        data(response, redactOrganizationMembers(organization, requestPermissions(request)));
+    });
     app.patch("/api/organizations/:organizationId", (request, response) => {
         const { changeNote, expectedVersionNo, ...input } = parse(organizationSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
         const organization = store.updateOrganization(request.params.organizationId, input, "manual", null, changeNote, expectedVersionNo);
@@ -2799,6 +3035,61 @@ export function createRuntime(options) {
             ? mapRecords(ai.listSuggestionsPage(request.params.workId, pagination, status), (suggestion) => redactSuggestion(suggestion, permissions))
             : ai.listSuggestions(request.params.workId, status).map((suggestion) => redactSuggestion(suggestion, permissions)));
     });
+    const desktopLocalAiActorScope = (request) => {
+        const actor = currentRequestActor();
+        return request.authUser?.userId ? `user:${request.authUser.userId}` : actor?.userId ? `user:${actor.userId}` : "auth-disabled";
+    };
+    const assertDesktopLocalAiPermission = (request) => {
+        const permissions = requestPermissions(request, String(request.params.workId));
+        if (!canWriteWorkModule(permissions, "ai-chat")) {
+            throw new AppError(403, "WORK_MODULE_WRITE_DENIED", "你没有使用创作助手的权限");
+        }
+        return permissions;
+    };
+    app.post("/api/works/:workId/desktop-local-ai/runs", async (request, response) => {
+        const input = parse(desktopLocalAiRunSchema, request.body);
+        const permissions = assertDesktopLocalAiPermission(request);
+        const citations = input.citations ?? [];
+        for (const citation of citations) {
+            if (store.getChapter(citation.chapterId).workId !== request.params.workId) {
+                throw new AppError(400, "CITATION_WORK_MISMATCH", "引用章节不属于当前作品");
+            }
+        }
+        if (input.conversationId) {
+            assertRequestAiConversationOwner(request, input.conversationId);
+            const conversation = store.getAiConversationSummary(input.conversationId);
+            if (String(conversation.workId) !== request.params.workId) {
+                throw new AppError(400, "CONVERSATION_WORK_MISMATCH", "AI 对话不属于当前作品");
+            }
+        }
+        data(response, await ai.startDesktopLocalAiRun({
+            workId: request.params.workId,
+            taskType: input.taskType,
+            instruction: instructionWithCitations(input.instruction, citations),
+            scope: input.scope,
+            runtimeModel: input.runtimeModel,
+            ...(input.conversationId ? { conversationId: input.conversationId } : {}),
+            ...(input.currentMessageId ? { excludeConversationMessageId: input.currentMessageId } : {}),
+            ...(input.imageAttachmentIds?.length ? { imageAttachmentIds: input.imageAttachmentIds } : {}),
+            ...(input.sceneDirection ? { sceneDirection: input.sceneDirection } : {})
+        }, desktopLocalAiActorScope(request), currentRequestActor(), permissions), 202);
+    });
+    app.get("/api/works/:workId/desktop-local-ai/runs/:runId", (request, response) => {
+        assertDesktopLocalAiPermission(request);
+        const runId = parse(identifier, request.params.runId);
+        data(response, ai.desktopLocalAiRunStatus(runId, request.params.workId, desktopLocalAiActorScope(request)));
+    });
+    app.post("/api/works/:workId/desktop-local-ai/runs/:runId/responses", (request, response) => {
+        assertDesktopLocalAiPermission(request);
+        const runId = parse(identifier, request.params.runId);
+        const input = parse(desktopLocalAiCompletionResponseSchema, request.body);
+        data(response, ai.submitDesktopLocalAiCompletion(runId, request.params.workId, desktopLocalAiActorScope(request), input));
+    });
+    app.delete("/api/works/:workId/desktop-local-ai/runs/:runId", (request, response) => {
+        assertDesktopLocalAiPermission(request);
+        const runId = parse(identifier, request.params.runId);
+        data(response, ai.cancelDesktopLocalAiRun(runId, request.params.workId, desktopLocalAiActorScope(request)));
+    });
     app.post("/api/works/:workId/suggestions", async (request, response) => {
         const input = parse(z.object({
             taskType: z.enum(TASK_TYPES),
@@ -2829,7 +3120,13 @@ export function createRuntime(options) {
     });
     app.post("/api/works/:workId/chat/stream", async (request, response) => {
         const input = parse(z.object({
-            instruction: nonEmpty.max(100_000),
+            instruction: z.string().max(100_000).default(""),
+            sceneDirection: z.string().max(20_000).optional(),
+            scenePin: z.object({
+                location: z.string().max(200).optional(),
+                present: z.string().max(500).optional(),
+                timeLabel: z.string().max(200).optional()
+            }).strict().optional(),
             scope: contextSchema,
             modelId: identifier.optional(),
             parameters: jsonObject.optional(),
@@ -2850,7 +3147,6 @@ export function createRuntime(options) {
             if (store.getChapter(citation.chapterId).workId !== request.params.workId)
                 throw new AppError(400, "CITATION_WORK_MISMATCH", "引用章节不属于当前作品");
         }
-        const resolvedInstruction = instructionWithCitations(input.instruction, citations);
         const existingRequest = store.findAiConversationStreamRequest(actorScope, request.params.workId, idempotencyKey);
         if (existingRequest && input.conversationId && existingRequest.conversationId !== input.conversationId) {
             throw new AppError(409, "IDEMPOTENCY_KEY_REUSED", "该请求标识已用于另一项 AI 对话请求");
@@ -2865,6 +3161,20 @@ export function createRuntime(options) {
             throw new AppError(400, "CONVERSATION_WORK_MISMATCH", "AI 对话不属于当前作品");
         }
         const conversationId = String(conversation.id);
+        const isRoleplay = Boolean(conversation.roleplayCharacter);
+        const instructionText = input.instruction.trim();
+        const sceneDirection = isRoleplay ? (input.sceneDirection ?? "").trim() : "";
+        if (!instructionText && !sceneDirection) {
+            throw new AppError(400, "INSTRUCTION_REQUIRED", isRoleplay ? "请输入角色台词或场景旁白" : "请输入指令");
+        }
+        if (!existingRequest && isRoleplay && input.scenePin !== undefined) {
+            store.setAiConversationScenePin(conversationId, request.params.workId, input.scenePin);
+        }
+        const storedUserContent = isRoleplay
+            ? composeRoleplayStoredUserContent(sceneDirection, instructionText)
+            : instructionText;
+        const resolvedInstruction = instructionWithCitations(instructionText, citations);
+        const mentionSource = [sceneDirection, resolvedInstruction].filter(Boolean).join("\n");
         const modelId = resolveConversationModelId(request.params.workId, conversationId, input.modelId);
         const permissions = requestPermissions(request, request.params.workId);
         const controller = new AbortController();
@@ -2905,7 +3215,7 @@ export function createRuntime(options) {
                     workId: request.params.workId,
                     modelId,
                     scope: input.scope,
-                    instruction: resolvedInstruction,
+                    instruction: mentionSource,
                     excludeConversationMessageId: input.currentMessageId
                 }, { ignoreWarning: input.ignoreContextWarning === true });
                 preparedConversation = redactAiConversation(store.getAiConversationSummary(conversationId), permissions);
@@ -2930,7 +3240,7 @@ export function createRuntime(options) {
                 : ai.resolveInstructionMentions({
                     workId: request.params.workId,
                     taskType: "chat",
-                    instruction: resolvedInstruction,
+                    instruction: mentionSource,
                     scope: input.scope,
                     conversationId
                 });
@@ -2947,7 +3257,7 @@ export function createRuntime(options) {
                 idempotencyKey,
                 requestHash,
                 userMessage: {
-                    content: input.instruction,
+                    content: storedUserContent,
                     citations,
                     ...(input.currentMessageId ? { existingMessageId: input.currentMessageId } : {}),
                     ...((modelId || mentionCharacterIds.length || mentionRaceIds.length || mentionOrganizationIds.length || input.imageAttachmentIds?.length) ? { metadata: {
@@ -3005,6 +3315,7 @@ export function createRuntime(options) {
             const suggestion = await ai.createStreamingChat({
                 workId: request.params.workId,
                 instruction: resolvedInstruction,
+                ...(sceneDirection ? { sceneDirection } : {}),
                 // 仍由生成路径基于原始范围持久化累计注入，保证预解析不会吞掉本轮自动命中。
                 scope: input.scope,
                 signal: controller.signal,
@@ -3310,6 +3621,7 @@ export function createRuntime(options) {
             backups.dispose();
             liteLlmPriceCache.dispose();
             ai.dispose();
+            offlineSync.dispose();
             const cancelledStreamRequests = store.cancelActiveAiConversationStreamRequests();
             if (cancelledStreamRequests > 0)
                 logger.info("ai.stream.requests_cancelled", { count: cancelledStreamRequests });
@@ -3335,6 +3647,6 @@ export function createRuntime(options) {
         })();
         return closePromise;
     };
-    return { app, database, store, ai, liteLlmPriceCache, backups, auth, attachmentStorage, characterAvatarStorage, cleanupAttachments, close };
+    return { app, database, store, ai, liteLlmPriceCache, backups, auth, offlineSync, attachmentStorage, characterAvatarStorage, cleanupAttachments, close };
 }
 //# sourceMappingURL=app.js.map