@downcity/agent 1.1.92 → 1.1.97

package/scripts/image-plugin-job.test.mjs

@@ -1,9 +1,10 @@
 /**
- * @file 验证 ImagePlugin 的可观察图片任务协议。
+ * @file 验证 ImagePlugin 对 Agent 保持直接生图体验。
  *
  * 关键点（中文）
- * - `create` 应快速返回 job_id，而不是同步等待图片完成。
- * - `status/result` 可查询同一个任务，成功后 result 返回 UIMessage。
+ * - Agent 只调用 `generate` action。
+ * - 插件内部负责 image_create/image_result 轮询。
+ * - 成功后返回 UIMessage，后续由 plugin bridge 落盘 file parts。
  */
 
 import test from "node:test";
@@ -26,130 +27,75 @@ function create_image_message() {
   };
 }
 
-test("ImagePlugin create/status/result exposes async image jobs", async () => {
-  let finish_image;
-  const image_promise = new Promise((resolve) => {
-    finish_image = () => resolve(create_image_message());
-  });
+test("ImagePlugin generate polls create/result until the image succeeds", async () => {
+  const calls = [];
   const plugin = new ImagePlugin({
-    image: async () => image_promise,
+    create: (input) => {
+      calls.push(["create", input.prompt]);
+      return {
+        job_id: "img_custom",
+        status: "running",
+        poll_after_ms: 1,
+      };
+    },
+    result: () => {
+      calls.push(["result"]);
+      return calls.filter(([name]) => name === "result").length === 1
+        ? {
+            job_id: "img_custom",
+            status: "running",
+            poll_after_ms: 1,
+          }
+        : {
+            job_id: "img_custom",
+            status: "succeeded",
+            result: create_image_message(),
+          };
+    },
     poll_interval_ms: 1,
     wait_timeout_ms: 100,
   });
 
-  const created = await plugin.actions.create.execute({
+  const result = await plugin.actions.generate.execute({
     context: {},
     payload: { prompt: "draw" },
     pluginName: "image",
-    actionName: "create",
-  });
-
-  assert.equal(created.success, true);
-  assert.equal(created.data.status, "running");
-  assert.match(created.data.job_id, /^img_/);
-
-  const before = await plugin.actions.status.execute({
-    context: {},
-    payload: { job_id: created.data.job_id },
-    pluginName: "image",
-    actionName: "status",
-  });
-
-  assert.equal(before.success, true);
-  assert.equal(before.data.status, "running");
-
-  finish_image();
-  await new Promise((resolve) => setTimeout(resolve, 0));
-
-  const after = await plugin.actions.status.execute({
-    context: {},
-    payload: { job_id: created.data.job_id },
-    pluginName: "image",
-    actionName: "status",
-  });
-
-  assert.equal(after.success, true);
-  assert.equal(after.data.status, "succeeded");
-  assert.equal("result" in after.data, false);
-
-  const result = await plugin.actions.result.execute({
-    context: {},
-    payload: { job_id: created.data.job_id },
-    pluginName: "image",
-    actionName: "result",
+    actionName: "generate",
   });
 
   assert.equal(result.success, true);
   assert.equal(result.data.role, "assistant");
   assert.equal(result.data.parts[0].type, "file");
+  assert.deepEqual(calls, [
+    ["create", "draw"],
+    ["result"],
+    ["result"],
+  ]);
 });
 
-test("ImagePlugin accepts custom job API without synchronous image function", async () => {
-  const message = create_image_message();
+test("ImagePlugin generate reports job failure", async () => {
   const plugin = new ImagePlugin({
     create: () => ({
-      job_id: "img_custom",
+      job_id: "img_failed",
       status: "running",
       poll_after_ms: 1,
     }),
-    status: () => ({
-      job_id: "img_custom",
-      status: "succeeded",
-    }),
     result: () => ({
-      job_id: "img_custom",
-      status: "succeeded",
-      result: message,
+      job_id: "img_failed",
+      status: "failed",
+      error: "provider failed",
     }),
+    poll_interval_ms: 1,
+    wait_timeout_ms: 100,
   });
 
-  const created = await plugin.actions.create.execute({
+  const result = await plugin.actions.generate.execute({
     context: {},
     payload: { prompt: "draw" },
     pluginName: "image",
-    actionName: "create",
-  });
-
-  assert.equal(created.success, true);
-  assert.equal(created.data.job_id, "img_custom");
-
-  const result = await plugin.actions.result.execute({
-    context: {},
-    payload: { job_id: "img_custom" },
-    pluginName: "image",
-    actionName: "result",
-  });
-
-  assert.equal(result.success, true);
-  assert.equal(result.data.parts[0].type, "file");
-});
-
-test("ImagePlugin strips accidental result data from custom status responses", async () => {
-  const plugin = new ImagePlugin({
-    create: () => ({
-      job_id: "img_status_result",
-      status: "succeeded",
-    }),
-    status: () => ({
-      job_id: "img_status_result",
-      status: "succeeded",
-      result: create_image_message(),
-    }),
-    result: () => ({
-      job_id: "img_status_result",
-      status: "succeeded",
-      result: create_image_message(),
-    }),
-  });
-
-  const status = await plugin.actions.status.execute({
-    context: {},
-    payload: { job_id: "img_status_result" },
-    pluginName: "image",
-    actionName: "status",
+    actionName: "generate",
   });
 
-  assert.equal(status.success, true);
-  assert.equal(status.data.status, "succeeded");
-  assert.equal("result" in status.data, false);
+  assert.equal(result.success, false);
+  assert.match(result.error, /provider failed/);
 });

package/src/index.ts

@@ -232,10 +232,8 @@ export type {
   ImagePluginJobCreateResult,
   ImagePluginJobResult,
   ImagePluginJobStatus,
-  ImagePluginJobStatusResult,
   ImagePluginMessage,
   ImagePluginOptions,
-  ImagePluginResult,
   ImagePluginTextContent,
 } from "./types/plugin/ImagePlugin.js";
 

package/src/plugin/core/ImagePlugin.ts

@@ -2,19 +2,15 @@
  * ImagePlugin：Agent 内置图片生成插件。
  *
  * 关键点（中文）
- * - 插件只负责把外部 image 函数暴露为 agent 可调用 action。
- * - 具体模型、Provider、鉴权与上游协议由调用方传入的 image 函数处理。
+ * - 对 Agent 只暴露同步体验的 `generate` action。
+ * - City / provider 的异步任务细节由插件内部 create + result 轮询封装。
  * - action 返回 AI SDK UIMessage，后续由 plugin tool bridge 抽取 file parts 写回 assistant 消息。
  */
 
-import crypto from "node:crypto";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type {
   ImagePluginInput,
-  ImagePluginJobCreateResult,
-  ImagePluginJobResult,
-  ImagePluginJobStatusResult,
   ImagePluginOptions,
   ImagePluginResult,
 } from "@/types/plugin/ImagePlugin.js";
@@ -27,37 +23,6 @@ const DEFAULT_IMAGE_PLUGIN_DESCRIPTION =
 const DEFAULT_WAIT_TIMEOUT_MS = 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 
-type LocalImageJobRecord = {
-  /**
-   * 图片任务唯一 ID。
-   */
-  job_id: string;
-  /**
-   * 当前任务状态。
-   */
-  status: "queued" | "running" | "succeeded" | "failed";
-  /**
-   * 成功时的图片结果。
-   */
-  result?: ImagePluginResult;
-  /**
-   * 失败时的错误信息。
-   */
-  error?: string;
-  /**
-   * 人类可读状态说明。
-   */
-  message?: string;
-  /**
-   * 任务创建时间。
-   */
-  created_at: string;
-  /**
-   * 任务更新时间。
-   */
-  updated_at: string;
-};
-
 /**
  * 判断值是否为普通对象。
  */
@@ -77,43 +42,22 @@ function normalize_image_payload(payload: JsonValue | undefined): ImagePluginInp
   return { ...record } as ImagePluginInput;
 }
 
-function normalize_job_id_payload(payload: JsonValue | undefined): { job_id: string } {
-  const record = to_record(payload ?? {});
-  const job_id = String(record?.job_id || "").trim();
-  if (!job_id) {
-    throw new TypeError("ImagePlugin job action requires job_id");
-  }
-  return { job_id };
-}
-
 /**
  * 校验 image 函数返回的 UIMessage。
  */
 function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   const record = to_record(result);
   if (!record || !Array.isArray(record.parts)) {
-    throw new TypeError("ImagePlugin image function must return an AI SDK UIMessage");
+    throw new TypeError("ImagePlugin image provider must return an AI SDK UIMessage");
   }
   return result;
 }
 
 /**
- * 归一化任务状态查询结果，确保 status action 不携带图片结果。
+ * 等待指定毫秒数。
  */
-function normalize_job_status_result(
-  result: ImagePluginJobStatusResult,
-): ImagePluginJobStatusResult {
-  return {
-    job_id: result.job_id,
-    status: result.status,
-    ...(result.message ? { message: result.message } : {}),
-    ...(result.error ? { error: result.error } : {}),
-    ...(typeof result.poll_after_ms === "number"
-      ? { poll_after_ms: result.poll_after_ms }
-      : {}),
-    ...(result.created_at ? { created_at: result.created_at } : {}),
-    ...(result.updated_at ? { updated_at: result.updated_at } : {}),
-  };
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 /**
@@ -135,13 +79,10 @@ export class ImagePlugin extends BasePlugin {
    */
   readonly description: string;
 
-  private readonly image: ImagePluginOptions["image"];
-  private readonly create_job?: ImagePluginOptions["create"];
-  private readonly read_job_status?: ImagePluginOptions["status"];
-  private readonly read_job_result?: ImagePluginOptions["result"];
+  private readonly create_job: NonNullable<ImagePluginOptions["create"]>;
+  private readonly read_job_result: NonNullable<ImagePluginOptions["result"]>;
   private readonly wait_timeout_ms: number;
   private readonly poll_interval_ms: number;
-  private readonly local_jobs = new Map<string, LocalImageJobRecord>();
 
   constructor(options: ImagePluginOptions) {
     super();
@@ -149,32 +90,15 @@ export class ImagePlugin extends BasePlugin {
     if (!name) {
       throw new Error("ImagePlugin requires a non-empty name");
     }
-    const has_custom_job_api = Boolean(
-      options.create || options.status || options.result,
-    );
-    if (
-      has_custom_job_api &&
-      (typeof options.create !== "function" ||
-        typeof options.status !== "function" ||
-        typeof options.result !== "function")
-    ) {
-      throw new Error(
-        "ImagePlugin custom job API requires create, status, and result functions",
-      );
-    }
-    if (!has_custom_job_api && typeof options.image !== "function") {
-      throw new Error(
-        "ImagePlugin requires either image(input) or create/status/result functions",
-      );
+    if (typeof options.create !== "function" || typeof options.result !== "function") {
+      throw new Error("ImagePlugin requires create and result functions");
     }
     this.name = name;
     this.title = String(options.title || DEFAULT_IMAGE_PLUGIN_TITLE).trim();
     this.description = String(
       options.description || DEFAULT_IMAGE_PLUGIN_DESCRIPTION,
     ).trim();
-    this.image = options.image;
     this.create_job = options.create;
-    this.read_job_status = options.status;
     this.read_job_result = options.result;
     this.wait_timeout_ms =
       typeof options.wait_timeout_ms === "number" && options.wait_timeout_ms > 0
@@ -191,108 +115,38 @@ export class ImagePlugin extends BasePlugin {
    */
   system(_context: AgentContext): string {
     return [
-      "Image generation is available through the plugin_call tool as an observable job workflow.",
-      `Call plugin "${this.name}" action "create" when the user asks to create, render, draw, or edit an image.`,
-      `Then call plugin "${this.name}" action "status" with { job_id } to inspect progress.`,
-      `When status is succeeded, call plugin "${this.name}" action "result" with { job_id } to attach the generated files.`,
-      "Use action \"generate\" only as a compatibility shortcut when you explicitly need to wait for completion.",
-      "Pass a JSON payload with prompt, optional size/aspect_ratio/quality/n, and optional provider_options to create/generate.",
+      "Image generation is available through the plugin_call tool.",
+      `Call plugin "${this.name}" action "generate" when the user asks to create, render, draw, or edit an image.`,
+      "Pass a JSON payload with prompt, optional size/aspect_ratio/quality/n, and optional provider_options.",
+      "The generated image files will be attached to the final assistant message automatically.",
     ].join("\n");
   }
 
-  private create_local_job(input: ImagePluginInput): ImagePluginJobCreateResult {
-    if (typeof this.image !== "function") {
-      throw new Error("ImagePlugin local image job requires image(input)");
-    }
-    const now = new Date().toISOString();
-    const job_id = `img_${crypto.randomUUID()}`;
-    const record: LocalImageJobRecord = {
-      job_id,
-      status: "running",
-      message: "image job is running",
-      created_at: now,
-      updated_at: now,
-    };
-    this.local_jobs.set(job_id, record);
-
-    void this.run_local_job(record, input, this.image);
-
-    return {
-      job_id,
-      status: record.status,
-      message: record.message,
-      poll_after_ms: this.poll_interval_ms,
-      created_at: record.created_at,
-      updated_at: record.updated_at,
-    };
-  }
-
-  private async run_local_job(
-    record: LocalImageJobRecord,
-    input: ImagePluginInput,
-    image: NonNullable<ImagePluginOptions["image"]>,
-  ): Promise<void> {
-    try {
-      const message = normalize_image_result(await image(input));
-      record.status = "succeeded";
-      record.result = message;
-      record.message = "image job succeeded";
-      record.updated_at = new Date().toISOString();
-    } catch (error) {
-      record.status = "failed";
-      record.error = String(error);
-      record.message = "image job failed";
-      record.updated_at = new Date().toISOString();
+  private async generate_image(input: ImagePluginInput): Promise<ImagePluginResult> {
+    const job = await this.create_job(input);
+    const job_id = String(job.job_id || "").trim();
+    if (!job_id) {
+      throw new Error("ImagePlugin image_create result requires job_id");
     }
-  }
-
-  private read_local_job(job_id: string): LocalImageJobRecord {
-    const record = this.local_jobs.get(job_id);
-    if (!record) {
-      throw new Error(`Unknown image job: ${job_id}`);
-    }
-    return record;
-  }
 
-  private serialize_local_status(record: LocalImageJobRecord): ImagePluginJobStatusResult {
-    return {
-      job_id: record.job_id,
-      status: record.status,
-      ...(record.message ? { message: record.message } : {}),
-      ...(record.error ? { error: record.error } : {}),
-      ...(record.status === "running" || record.status === "queued"
-        ? { poll_after_ms: this.poll_interval_ms }
-        : {}),
-      created_at: record.created_at,
-      updated_at: record.updated_at,
-    };
-  }
-
-  private serialize_local_result(record: LocalImageJobRecord): ImagePluginJobResult {
-    return {
-      job_id: record.job_id,
-      status: record.status,
-      ...(record.result ? { result: record.result } : {}),
-      ...(record.error ? { error: record.error } : {}),
-      ...(record.message ? { message: record.message } : {}),
-      created_at: record.created_at,
-      updated_at: record.updated_at,
-    };
-  }
-
-  private async wait_for_job(job_id: string): Promise<ImagePluginResult> {
     const deadline = Date.now() + this.wait_timeout_ms;
+    let poll_after_ms =
+      typeof job.poll_after_ms === "number" && job.poll_after_ms > 0
+        ? job.poll_after_ms
+        : this.poll_interval_ms;
     while (Date.now() <= deadline) {
-      const result = this.read_job_result
-        ? await this.read_job_result({ job_id })
-        : this.serialize_local_result(this.read_local_job(job_id));
+      const result = await this.read_job_result({ job_id });
       if (result.status === "succeeded" && result.result) {
         return normalize_image_result(result.result);
       }
       if (result.status === "failed") {
         throw new Error(result.error || result.message || "image job failed");
       }
-      await new Promise((resolve) => setTimeout(resolve, this.poll_interval_ms));
+      poll_after_ms =
+        typeof result.poll_after_ms === "number" && result.poll_after_ms > 0
+          ? result.poll_after_ms
+          : this.poll_interval_ms;
+      await sleep(poll_after_ms);
     }
     throw new Error(`image job timed out: ${job_id}`);
   }
@@ -301,92 +155,11 @@ export class ImagePlugin extends BasePlugin {
    * 显式 action 集合。
    */
   readonly actions = {
-    create: {
-      execute: async ({ payload }: { payload: JsonValue }) => {
-        try {
-          const input = normalize_image_payload(payload);
-          const result = this.create_job
-            ? await this.create_job(input)
-            : this.create_local_job(input);
-          return {
-            success: true,
-            data: result as unknown as JsonObject,
-            message: result.message || "image job created",
-          };
-        } catch (error) {
-          return {
-            success: false,
-            error: String(error),
-            message: String(error),
-          };
-        }
-      },
-    },
-    status: {
-      execute: async ({ payload }: { payload: JsonValue }) => {
-        try {
-          const input = normalize_job_id_payload(payload);
-          const result = this.read_job_status
-            ? normalize_job_status_result(await this.read_job_status(input))
-            : this.serialize_local_status(this.read_local_job(input.job_id));
-          return {
-            success: true,
-            data: result as unknown as JsonObject,
-            message: result.message || `image job ${result.status}`,
-          };
-        } catch (error) {
-          return {
-            success: false,
-            error: String(error),
-            message: String(error),
-          };
-        }
-      },
-    },
-    result: {
-      execute: async ({ payload }: { payload: JsonValue }) => {
-        try {
-          const input = normalize_job_id_payload(payload);
-          const result = this.read_job_result
-            ? await this.read_job_result(input)
-            : this.serialize_local_result(this.read_local_job(input.job_id));
-          if (result.status === "succeeded" && result.result) {
-            return {
-              success: true,
-              data: result.result as unknown as JsonObject,
-              message: result.message || "image job succeeded",
-            };
-          }
-          if (result.status === "failed") {
-            return {
-              success: false,
-              data: result as unknown as JsonObject,
-              error: result.error || result.message || "image job failed",
-              message: result.message || "image job failed",
-            };
-          }
-          return {
-            success: true,
-            data: result as unknown as JsonObject,
-            message: result.message || `image job ${result.status}`,
-          };
-        } catch (error) {
-          return {
-            success: false,
-            error: String(error),
-            message: String(error),
-          };
-        }
-      },
-    },
     generate: {
       execute: async ({ payload }: { payload: JsonValue }) => {
         try {
           const input = normalize_image_payload(payload);
-          const job = this.create_job
-            ? await this.create_job(input)
-            : this.create_local_job(input);
-          const message = await this.wait_for_job(job.job_id);
+          const message = await this.generate_image(input);
           return {
             success: true,
             data: message as unknown as JsonObject,

package/src/types/plugin/ImagePlugin.ts

@@ -84,14 +84,14 @@ export interface ImagePluginInput {
 }
 
 /**
- * ImagePlugin 生成结果。
+ * ImagePlugin 图片任务状态。
  */
-export type ImagePluginResult = UIMessage;
+export type ImagePluginJobStatus = "queued" | "running" | "succeeded" | "failed";
 
 /**
- * ImagePlugin 图片任务状态。
+ * ImagePlugin 生成结果。
  */
-export type ImagePluginJobStatus = "queued" | "running" | "succeeded" | "failed";
+export type ImagePluginResult = UIMessage;
 
 /**
  * ImagePlugin 图片任务创建结果。
@@ -101,8 +101,6 @@ export interface ImagePluginJobCreateResult {
   job_id: string;
   /** 当前任务状态。 */
   status: ImagePluginJobStatus;
-  /** 查询任务状态的路径或 URL。 */
-  status_path?: string;
   /** 读取任务结果的路径或 URL。 */
   result_path?: string;
   /** 人类可读状态说明。 */
@@ -115,26 +113,6 @@ export interface ImagePluginJobCreateResult {
   updated_at?: string;
 }
 
-/**
- * ImagePlugin 图片任务状态查询结果。
- */
-export interface ImagePluginJobStatusResult {
-  /** 图片任务唯一 ID。 */
-  job_id: string;
-  /** 当前任务状态。 */
-  status: ImagePluginJobStatus;
-  /** 人类可读状态说明。 */
-  message?: string;
-  /** 失败时的错误信息。 */
-  error?: string;
-  /** 建议下次轮询前等待的毫秒数。 */
-  poll_after_ms?: number;
-  /** 任务创建时间。 */
-  created_at?: string;
-  /** 任务更新时间。 */
-  updated_at?: string;
-}
-
 /**
  * ImagePlugin 图片任务结果查询结果。
  */
@@ -149,6 +127,8 @@ export interface ImagePluginJobResult {
   error?: string;
   /** 人类可读状态说明。 */
   message?: string;
+  /** 任务未完成时建议下次轮询前等待的毫秒数。 */
+  poll_after_ms?: number;
   /** 任务创建时间。 */
   created_at?: string;
   /** 任务更新时间。 */
@@ -165,13 +145,9 @@ export interface ImagePluginOptions {
   title?: string;
   /** Plugin 用途说明。 */
   description?: string;
-  /** 可选：图片生成函数；未传 `create/status/result` 时用于本地后台任务兼容。 */
-  image?: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
-  /** 可选：创建图片生成任务，通常传入 `(input) => city.ai.imageJobCreate(input)`。 */
+  /** 可选：创建图片生成任务，通常传入 `(input) => city.ai.image_create(input)`。 */
   create?: (input: ImagePluginInput) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
-  /** 可选：查询图片生成任务状态，通常传入 `(input) => city.ai.imageJobStatus(input)`。 */
-  status?: (input: { job_id: string }) => Promise<ImagePluginJobStatusResult> | ImagePluginJobStatusResult;
-  /** 可选：读取图片生成任务结果，通常传入 `(input) => city.ai.imageJobResult(input)`。 */
+  /** 可选：读取图片生成任务结果，通常传入 `(input) => city.ai.image_result(input)`。 */
   result?: (input: { job_id: string }) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
   /** 兼容 `generate` 动作等待任务完成的最长毫秒数。 */
   wait_timeout_ms?: number;