@downcity/city 0.2.94 → 0.2.101

package/bin/service/ai/ai-service.js

@@ -9,21 +9,23 @@
  * 路由（City 自动生成）：
  * - POST /v1/ai/text             — 文本生成
  * - POST /v1/ai/stream           — 流式生成
- * - POST /v1/ai/image            — 图片生成
  * - POST /v1/ai/video            — 视频生成
+ * - POST /v1/ai/image/create     — 创建图片生成任务
+ * - POST /v1/ai/image/result     — 查询图片生成任务
+ * - POST /v1/ai/image/persist    — 后台持久化图片结果（admin）
  * - POST /v1/ai/chat/completions — OpenAI 兼容端点
  * - GET  /v1/ai/models           — 模型列表
  */
 import { Service } from "../service.js";
-import { httpError, randomSecret } from "../../utils/helpers.js";
+import { httpError } from "../../utils/helpers.js";
 import { sqliteAsyncJobs } from "../async-job/schema.js";
 import { normalizeAIUsage } from "./helpers.js";
-/** AIService 直接暴露的 SDK 通路模态列表。 */
-const MODALITIES = ["text", "stream", "image", "video", "tts", "asr"];
+/** AIService 直接暴露的 SDK 通路模态列表。图片只通过 image/create + image/result 暴露。 */
+const MODALITIES = ["text", "stream", "video", "tts", "asr"];
 /** 用户侧默认以 text 模态排序模型 */
 const DEFAULT_MODEL_MODE = "text";
-/** 图片任务轮询建议间隔 */
-const IMAGE_JOB_POLL_AFTER_MS = 2_000;
+/** 图片任务的内部 action 列表。 */
+const IMAGE_ACTION_MODES = ["image_create", "image_persist"];
 /** 图片生成任务在通用 async_jobs 表中的类型。 */
 const IMAGE_GENERATE_JOB_TYPE = "ai.image.generate";
 /**
@@ -56,15 +58,6 @@ function isProviderChargedOutput(value) {
 function isPromiseLike(value) {
     return Boolean(value && typeof value === "object" && "then" in value && typeof value.then === "function");
 }
-/**
- * 读取必填字符串。
- */
-function readRequiredString(value, label) {
-    const text = readOptionalString(value);
-    if (!text)
-        throw httpError(422, `${label} is required`);
-    return text;
-}
 /**
  * 读取可选字符串。
  */
@@ -72,57 +65,71 @@ function readOptionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 /**
- * 归一化图片任务输出。
+ * 读取可空字符串字段。
  */
-async function normalizeImageJobOutput(output) {
-    if (!isResponse(output))
-        return output;
-    const text = await output.text();
-    if (!output.ok) {
-        throw httpError(output.status, text || output.statusText || "image generation failed");
-    }
-    return text ? JSON.parse(text) : {};
+function readNullableString(value) {
+    return typeof value === "string" ? value : null;
 }
 /**
- * 解析已持久化的图片任务结果。
+ * 读取任务状态。
  */
-function parseImageJobResult(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
+function readJobStatus(value) {
+    return value === "queued" || value === "running" || value === "succeeded" || value === "failed"
+        ? value
+        : "failed";
 }
 /**
- * 解析可恢复任务状态。
+ * 安全解析 JSON 对象。
  */
-function parseImageJobStepState(raw) {
-    if (!raw)
-        return undefined;
+function parseRecordJson(value) {
+    if (typeof value !== "string" || !value.trim())
+        return {};
     try {
-        const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : undefined;
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : {};
     }
     catch {
-        return undefined;
+        return {};
     }
 }
 /**
- * 解析已持久化的图片任务输入。
+ * 安全解析 UIMessage。
  */
-function parseImageJobInput(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : {};
-    }
-    catch {
-        return {};
+function parseImageMessage(value) {
+    const record = parseRecordJson(value);
+    return record.role === "assistant" && Array.isArray(record.parts)
+        ? record
+        : undefined;
+}
+/**
+ * 把 TableApi 普通行转成图片任务记录。
+ */
+function rowToAsyncJobRecord(row) {
+    return {
+        job_id: String(row.job_id ?? ""),
+        job_type: String(row.job_type ?? ""),
+        status: readJobStatus(row.status),
+        input_json: String(row.input_json ?? "{}"),
+        state_json: readNullableString(row.state_json),
+        result_json: readNullableString(row.result_json),
+        error: readNullableString(row.error),
+        message: readNullableString(row.message),
+        city_id: readNullableString(row.city_id),
+        user_id: readNullableString(row.user_id),
+        service_id: readNullableString(row.service_id),
+        model_id: readNullableString(row.model_id),
+        created_at: String(row.created_at ?? ""),
+        updated_at: String(row.updated_at ?? ""),
+    };
+}
+/**
+ * 保留已知 HTTP 错误状态，其它异常统一包装成上游错误。
+ */
+function imageActionError(error, fallback_message) {
+    if (error instanceof Error && typeof error.statusCode === "number") {
+        return error;
     }
+    return httpError(502, error instanceof Error ? error.message : fallback_message);
 }
 /**
  * 从输出对象中读取 provider usage。
@@ -161,54 +168,60 @@ function countImageOutputs(output) {
     return count > 0 ? count : undefined;
 }
 /**
- * 判断 provider 是否返回了图片任务推进结果。
+ * 判断 provider 是否返回了图片任务创建结果。
  */
-function isImageJobStepResult(value) {
+function isImageProviderCreateResult(value) {
     if (!value || typeof value !== "object")
         return false;
-    const status = value.status;
-    return status === "running" || status === "succeeded" || status === "failed";
+    const record = value;
+    return typeof record.job_id === "string" &&
+        Boolean(record.job_id.trim()) &&
+        isImageJobStatus(record.status);
 }
 /**
- * 把类型化任务记录转成 TableApi 使用的普通行。
+ * 判断 provider 是否返回了图片任务查询结果。
  */
-function recordToRow(record) {
-    return { ...record };
-}
-/**
- * 把 TableApi 普通行转成图片任务记录。
- */
-function rowToAsyncJobRecord(row) {
-    return {
-        job_id: String(row.job_id ?? ""),
-        job_type: String(row.job_type ?? ""),
-        status: readJobStatus(row.status),
-        input_json: String(row.input_json ?? "{}"),
-        state_json: readNullableString(row.state_json),
-        result_json: readNullableString(row.result_json),
-        error: readNullableString(row.error),
-        message: readNullableString(row.message),
-        city_id: readNullableString(row.city_id),
-        user_id: readNullableString(row.user_id),
-        service_id: readNullableString(row.service_id),
-        model_id: readNullableString(row.model_id),
-        created_at: String(row.created_at ?? ""),
-        updated_at: String(row.updated_at ?? ""),
-    };
+function isImageProviderResult(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (typeof record.job_id !== "string" || !record.job_id.trim())
+        return false;
+    if (!isImageJobStatus(record.status))
+        return false;
+    if (record.status === "succeeded") {
+        const result = isRecord(record.result) ? record.result : undefined;
+        if (!result || result.role !== "assistant" || !Array.isArray(result.parts))
+            return false;
+    }
+    return true;
 }
 /**
- * 读取任务状态。
+ * 判断 provider 是否返回了图片持久化结果。
  */
-function readJobStatus(value) {
-    return value === "queued" || value === "running" || value === "succeeded" || value === "failed"
-        ? value
-        : "failed";
+function isImageProviderPersistResult(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (typeof record.job_id !== "string" || !record.job_id.trim())
+        return false;
+    if (!isImageJobStatus(record.status))
+        return false;
+    if (record.status === "succeeded") {
+        const result = isRecord(record.result) ? record.result : undefined;
+        if (!result || result.role !== "assistant" || !Array.isArray(result.parts))
+            return false;
+    }
+    return true;
 }
 /**
- * 读取可空字符串字段。
+ * 判断图片任务状态。
  */
-function readNullableString(value) {
-    return typeof value === "string" ? value : null;
+function isImageJobStatus(value) {
+    return value === "queued" ||
+        value === "running" ||
+        value === "succeeded" ||
+        value === "failed";
 }
 export class AIService extends Service {
     /** 模型注册表 */
@@ -233,6 +246,9 @@ export class AIService extends Service {
         this.action("image/result", async (ctx) => this.readImageJob(ctx), {
             auth: ["user", "admin"],
         });
+        this.action("image/persist", async (ctx) => this.persistImageJob(ctx), {
+            auth: ["admin"],
+        });
         // OpenAI 兼容端点
         this.action("chat/completions", async (ctx) => this.handleChatCompletions(ctx), {
             auth: ["user", "admin"],
@@ -295,6 +311,17 @@ export class AIService extends Service {
         throw httpError(422, `No model registered`);
     }
     getAction(model, mode) {
+        if (mode === "image" || IMAGE_ACTION_MODES.includes(mode)) {
+            const has_image_actions = Boolean(model.actions.image_create && model.actions.image_persist);
+            if (!has_image_actions)
+                return undefined;
+            return mode === "image"
+                ? model.actions.image_create
+                : model.actions[mode];
+        }
+        if (mode === "image_result") {
+            return model.actions.image_result;
+        }
         return model.actions[(mode ?? "text")];
     }
     resolveOpenAIAction(model) {
@@ -370,9 +397,12 @@ export class AIService extends Service {
     }
     getModelModalities(model) {
         const modalities = Object.keys(model.actions).filter((key) => model.actions[key] !== undefined);
+        if (modalities.includes("image_create") && modalities.includes("image_persist")) {
+            modalities.push("image");
+        }
         if (!modalities.includes("openai") && this.resolveOpenAIAction(model))
             modalities.push("openai");
-        return modalities;
+        return modalities.filter((mode) => mode !== "image_create" && mode !== "image_persist" && mode !== "image_result");
     }
     getModelEnvRequirements(model) {
         const requirements = model.env
@@ -415,211 +445,173 @@ export class AIService extends Service {
     }
     // ========== 图片任务通路 ==========
     async createImageJob(ctx) {
-        const resolved = this.resolve({ model: ctx.input.model, mode: "image" }, ctx.env);
-        const job_id = `img_${randomSecret(12)}`;
+        const resolved = this.resolve({ model: ctx.input.model, mode: "image_create" }, ctx.env);
         this.attachResolvedModel(ctx, resolved.model, "image/create");
-        await this.handleCharge(ctx, resolved.model?.bill?.(ctx, { job_id }), false);
-        const now = new Date().toISOString();
-        const record = {
-            job_id,
-            job_type: IMAGE_GENERATE_JOB_TYPE,
-            status: "queued",
-            input_json: JSON.stringify(ctx.input),
-            state_json: null,
-            result_json: null,
-            error: null,
-            message: "queued",
-            city_id: ctx.city?.city_id ?? readOptionalString(ctx.input.city_id),
-            user_id: ctx.user?.user_id ?? null,
-            service_id: "ai",
-            model_id: resolved.model?.id ?? null,
-            created_at: now,
-            updated_at: now,
-        };
-        await this.asyncJobTable(ctx).insert(recordToRow(record));
-        const job_ctx = {
-            ...ctx,
-            input: { ...ctx.input },
-            locals: {},
-            output: undefined,
-            error: undefined,
-        };
-        if (resolved.model?.actions.image_job) {
-            let advanced;
-            try {
-                advanced = await this.advanceImageJob(job_ctx, record);
-            }
-            catch (error) {
-                await this.updateImageJob(ctx, job_id, {
-                    status: "failed",
-                    error: error instanceof Error ? error.message : String(error),
-                    message: "failed",
-                    updated_at: new Date().toISOString(),
-                });
-                throw httpError(502, error instanceof Error ? error.message : "image_job action failed");
+        try {
+            const created = await resolved.action(ctx);
+            if (!isImageProviderCreateResult(created)) {
+                throw httpError(500, "image_create action returned invalid result");
             }
-            return {
-                job_id,
-                status: advanced.status,
-                poll_after_ms: IMAGE_JOB_POLL_AFTER_MS,
-            };
+            await this.insertImageJob(ctx, created);
+            return created;
         }
-        else {
-            const promise = this.runImageJob(job_id, job_ctx);
-            if (ctx.waitUntil)
-                ctx.waitUntil(promise);
-            else
-                void promise;
+        catch (error) {
+            throw imageActionError(error, "image_create action failed");
         }
-        return {
-            job_id,
-            status: "queued",
-            poll_after_ms: IMAGE_JOB_POLL_AFTER_MS,
-        };
     }
     async readImageJob(ctx) {
-        const job_id = readRequiredString(ctx.input.job_id, "job_id");
-        const record = await this.getImageJob(ctx, job_id);
-        if (!record)
-            throw httpError(404, `Image job not found: ${job_id}`);
-        this.ensureImageJobAccess(ctx, record);
-        if (record.status === "queued" || record.status === "running") {
-            const advanced = await this.advanceImageJob(ctx, record);
-            return this.toImageJobResult(advanced);
-        }
-        return this.toImageJobResult(record);
-    }
-    async advanceImageJob(ctx, record) {
-        const input = parseImageJobInput(record.input_json);
-        const resolved = this.resolve({ model: input.model, mode: "image" }, ctx.env);
-        const step_action = resolved.model?.actions.image_job;
-        if (!step_action)
-            return record;
-        this.attachResolvedModel(ctx, resolved.model, "image");
-        const step_ctx = {
-            ...ctx,
-            input,
-            locals: {
-                ...ctx.locals,
-                image_job: {
-                    job_id: record.job_id,
-                    status: record.status,
-                    state: parseImageJobStepState(record.state_json),
-                },
-            },
-        };
-        const output = await step_action(step_ctx);
-        if (!isImageJobStepResult(output)) {
-            throw httpError(500, "image_job action returned invalid result");
-        }
-        const updated_at = new Date().toISOString();
-        if (output.status === "succeeded") {
-            if (!output.result)
-                throw httpError(500, "image_job action succeeded without result");
-            await this.updateImageJob(ctx, record.job_id, {
-                status: "succeeded",
-                state_json: null,
-                result_json: JSON.stringify(output.result),
-                error: null,
-                message: output.message ?? "succeeded",
-                updated_at,
-            });
-        }
-        else if (output.status === "failed") {
-            await this.updateImageJob(ctx, record.job_id, {
-                status: "failed",
-                error: output.error ?? output.message ?? "image generation failed",
-                message: output.message ?? "failed",
-                updated_at,
-            });
+        const job = await this.requireImageJob(ctx);
+        try {
+            const model_id = readOptionalString(ctx.input.model);
+            const model = model_id ? this.modelMap.get(model_id) : undefined;
+            if (model?.actions.image_result) {
+                this.attachResolvedModel(ctx, model, "image/result");
+                this.attachImageJobContext(ctx, job);
+                const output = await model.actions.image_result(ctx);
+                if (!isImageProviderResult(output)) {
+                    throw httpError(500, "image_result action returned invalid result");
+                }
+                return output;
+            }
+            if (job.model_id && this.modelMap.has(job.model_id)) {
+                this.attachResolvedModel(ctx, this.modelMap.get(job.model_id), "image/result");
+            }
+            const output = this.imageJobToResult(job);
+            if (!isImageProviderResult(output)) {
+                throw httpError(500, "image_result action returned invalid result");
+            }
+            return output;
         }
-        else {
-            await this.updateImageJob(ctx, record.job_id, {
-                status: "running",
-                state_json: output.state ? JSON.stringify(output.state) : record.state_json,
-                error: null,
-                message: output.message ?? "running",
-                updated_at,
-            });
+        catch (error) {
+            throw imageActionError(error, "image_result action failed");
         }
-        const next = await this.getImageJob(ctx, record.job_id);
-        return next ?? record;
     }
-    async runImageJob(job_id, ctx) {
+    /**
+     * 持久化图片任务结果，并在持久化成功后触发计费。
+     *
+     * 关键点（中文）
+     * - 这个方法供后台 worker / queue / cron 调用，不是前端轮询 API。
+     * - AIService 使用内置 async_jobs 持久化任务，Provider 只负责把上游结果转成固定返回协议。
+     */
+    async persistImageJob(ctx) {
+        const job = await this.requireImageJob(ctx);
+        if (!ctx.input.model && job.model_id) {
+            ctx.input = { ...ctx.input, model: job.model_id };
+        }
+        const resolved = this.resolve({ model: ctx.input.model, mode: "image_persist" }, ctx.env);
+        this.attachResolvedModel(ctx, resolved.model, "image/persist");
+        this.attachImageJobContext(ctx, job);
+        const started_at = Date.now();
         try {
-            await this.updateImageJob(ctx, job_id, {
-                status: "running",
-                message: "running",
-                error: null,
-                updated_at: new Date().toISOString(),
-            });
-            const resolved = this.resolve({ model: ctx.input.model, mode: "image" }, ctx.env);
-            this.attachResolvedModel(ctx, resolved.model, "image");
             const output = await resolved.action(ctx);
-            const result = await normalizeImageJobOutput(output);
-            await this.updateImageJob(ctx, job_id, {
-                status: "succeeded",
-                state_json: null,
-                result_json: JSON.stringify(result),
-                error: null,
-                message: "succeeded",
-                updated_at: new Date().toISOString(),
-            });
+            if (!isImageProviderPersistResult(output)) {
+                throw httpError(500, "image_persist action returned invalid result");
+            }
+            if (output.status === "succeeded") {
+                this.attachOutputMetering(ctx, output.result, "image", started_at);
+                await this.updateImageJobFromPersist(ctx, job, output);
+                const charge = resolved.model?.bill?.(ctx, output);
+                await this.handleCharge(ctx, charge, isPromiseLike(charge));
+            }
+            else {
+                await this.updateImageJobFromPersist(ctx, job, output);
+            }
+            return output;
         }
         catch (error) {
-            await this.updateImageJob(ctx, job_id, {
-                status: "failed",
-                error: error instanceof Error ? error.message : String(error),
-                message: "failed",
-                updated_at: new Date().toISOString(),
-            });
+            throw imageActionError(error, "image_persist action failed");
         }
     }
-    asyncJobTable(ctx) {
+    /**
+     * 写入图片任务。
+     */
+    async insertImageJob(ctx, created) {
         const table = ctx.db.async_jobs;
         if (!table)
-            throw httpError(500, "Async job table is not initialized");
-        return table;
-    }
-    async getImageJob(ctx, job_id) {
-        const rows = await this.asyncJobTable(ctx).select({
-            job_id,
+            throw httpError(500, "AI async_jobs table is not initialized");
+        const now = new Date().toISOString();
+        await table.insert({
+            job_id: created.job_id,
             job_type: IMAGE_GENERATE_JOB_TYPE,
+            status: created.status,
+            input_json: JSON.stringify(ctx.input ?? {}),
+            state_json: JSON.stringify(created.metadata ?? {}),
+            result_json: null,
+            error: created.error ?? null,
+            message: created.message ?? null,
+            city_id: ctx.city?.city_id ?? null,
+            user_id: ctx.user?.user_id ?? null,
+            service_id: "ai",
+            model_id: ctx.metering?.model_id ?? null,
+            created_at: now,
+            updated_at: now,
         });
-        return rows[0] ? rowToAsyncJobRecord(rows[0]) : undefined;
     }
-    async updateImageJob(ctx, job_id, values) {
-        await this.asyncJobTable(ctx).update({
-            where: {
-                job_id,
-                job_type: IMAGE_GENERATE_JOB_TYPE,
-            },
-            values: recordToRow(values),
-        });
+    /**
+     * 读取图片任务。
+     */
+    async requireImageJob(ctx) {
+        const table = ctx.db.async_jobs;
+        if (!table)
+            throw httpError(500, "AI async_jobs table is not initialized");
+        const job_id = readOptionalString(ctx.input.job_id);
+        if (!job_id)
+            throw httpError(422, "job_id is required");
+        const rows = await table.select({ job_id, job_type: IMAGE_GENERATE_JOB_TYPE });
+        const row = rows[0];
+        if (!row)
+            throw httpError(404, `Image job not found: ${job_id}`);
+        return rowToAsyncJobRecord(row);
     }
-    ensureImageJobAccess(ctx, record) {
-        if (ctx.identity?.kind !== "user")
-            return;
-        if (record.city_id && ctx.city?.city_id && record.city_id !== ctx.city.city_id) {
-            throw httpError(404, `Image job not found: ${record.job_id}`);
-        }
-        if (record.user_id && ctx.user?.user_id && record.user_id !== ctx.user.user_id) {
-            throw httpError(404, `Image job not found: ${record.job_id}`);
-        }
+    /**
+     * 把 async_jobs 记录注入 Provider 可读取的上下文。
+     */
+    attachImageJobContext(ctx, job) {
+        const image_job = {
+            record: job,
+            input: parseRecordJson(job.input_json),
+            state: parseRecordJson(job.state_json),
+        };
+        ctx.locals.ai_image_job = image_job;
+        ctx.input = {
+            ...parseRecordJson(job.input_json),
+            ...ctx.input,
+            job_id: job.job_id,
+        };
     }
-    toImageJobResult(record) {
-        const result = record.status === "succeeded" && record.result_json
-            ? parseImageJobResult(record.result_json)
-            : undefined;
+    /**
+     * 将图片任务记录转成默认 result 返回。
+     */
+    imageJobToResult(job) {
         return {
-            job_id: record.job_id,
-            status: record.status,
-            result,
-            error: record.error ?? undefined,
-            message: record.message ?? undefined,
-            poll_after_ms: IMAGE_JOB_POLL_AFTER_MS,
+            job_id: job.job_id,
+            status: job.status,
+            result: job.status === "succeeded" ? parseImageMessage(job.result_json) : undefined,
+            error: job.error ?? undefined,
+            message: job.message ?? undefined,
+            poll_after_ms: job.status === "running" || job.status === "queued" ? 2_000 : undefined,
+            metadata: parseRecordJson(job.state_json),
         };
     }
+    /**
+     * 按 persist 输出更新图片任务。
+     */
+    async updateImageJobFromPersist(ctx, job, output) {
+        const table = ctx.db.async_jobs;
+        if (!table)
+            throw httpError(500, "AI async_jobs table is not initialized");
+        await table.update({
+            where: { job_id: job.job_id, job_type: IMAGE_GENERATE_JOB_TYPE },
+            values: {
+                status: output.status,
+                state_json: JSON.stringify(output.metadata ?? parseRecordJson(job.state_json)),
+                result_json: output.result ? JSON.stringify(output.result) : job.result_json ?? null,
+                error: output.error ?? null,
+                message: output.message ?? null,
+                updated_at: new Date().toISOString(),
+            },
+        });
+    }
     // ========== OpenAI 兼容通路 ==========
     async handleChatCompletions(ctx) {
         const body = ctx.input;
@@ -716,11 +708,12 @@ export class AIService extends Service {
             .then(async (line) => {
             if (!line || line.amount_microcredits <= 0)
                 return;
-            if (!ctx.user?.user_id)
+            const user_id = line.user_id ?? ctx.user?.user_id;
+            if (!user_id)
                 return;
             await this.balance?.charge({
-                user_id: ctx.user.user_id,
                 ...line,
+                user_id,
             });
         });
         if (!defer) {