@downcity/agent 1.1.153 → 1.1.157

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

@@ -1,16 +1,20 @@
 /**
- * @file 验证 ImagePlugin 对 Agent 保持直接生图体验。
+ * @file 验证 ImagePlugin 的两步式图片任务协议。
  *
  * 关键点（中文）
- * - 插件暴露 image_create / image_result 两个任务 action，并保留 generate 便捷 action。
- * - image_result 默认轮询到终态，成功后返回 UIMessage 方便 tool bridge 自动挂载图片。
- * - 成功后返回 UIMessage，后续由 plugin bridge 落盘 file parts。
+ * - 插件只暴露 image_create / image_result 两个任务 action。
+ * - image_result 只读取一次当前状态，不在 plugin 层等待终态。
+ * - 成功图片仍以 UIMessage 返回，后续由 plugin bridge 落盘 file parts。
  */
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 import { ImagePlugin } from "../../plugins/bin/index.js";
+import { createAgentPluginRegistry } from "../bin/agent/local/AgentPluginFactory.js";
 
 function create_image_message() {
   return {
@@ -27,38 +31,27 @@ function create_image_message() {
   };
 }
 
-test("ImagePlugin generate creates and polls image jobs", async () => {
-  const calls = [];
-  const message = create_image_message();
-  const plugin = new ImagePlugin({
-    min_poll_interval_ms: 1,
-    image_create: (input) => {
-      calls.push(["create", input.prompt]);
-      return { job_id: "img_1", status: "queued", poll_after_ms: 1 };
-    },
-    image_result: (input) => {
-      calls.push(["result", input.job_id]);
-      return calls.length === 2
-        ? { job_id: input.job_id, status: "running", poll_after_ms: 1 }
-        : { job_id: input.job_id, status: "succeeded", result: message, poll_after_ms: 1 };
-    },
+function create_context(rootPath = process.cwd()) {
+  return { rootPath };
+}
+
+function create_registry(plugin, rootPath = process.cwd()) {
+  return createAgentPluginRegistry({
+    plugins: [plugin],
+    get_context: () => create_context(rootPath),
   });
+}
 
-  const result = await plugin.actions.generate.execute({
-    context: {},
-    payload: { prompt: "draw" },
-    pluginName: "image",
-    actionName: "generate",
+test("ImagePlugin exposes only job-style image actions", async () => {
+  const plugin = new ImagePlugin({
+    image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
   });
 
-  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", "img_1"],
-    ["result", "img_1"],
-  ]);
+  assert.equal("image_create" in plugin.actions, true);
+  assert.equal("image_result" in plugin.actions, true);
+  assert.equal("models" in plugin.actions, true);
+  assert.equal("generate" in plugin.actions, false);
 });
 
 test("ImagePlugin image_create returns image job", async () => {
@@ -73,7 +66,7 @@ test("ImagePlugin image_create returns image job", async () => {
   });
 
   const result = await plugin.actions.image_create.execute({
-    context: {},
+    context: create_context(),
     payload: { prompt: "draw" },
     pluginName: "image",
     actionName: "image_create",
@@ -110,7 +103,7 @@ test("ImagePlugin models lists image-capable models", async () => {
   });
 
   const result = await plugin.actions.models.execute({
-    context: {},
+    context: create_context(),
     payload: {},
     pluginName: "image",
     actionName: "models",
@@ -122,60 +115,81 @@ test("ImagePlugin models lists image-capable models", async () => {
   assert.equal(result.data.items[0].meta.provider, "test");
 });
 
-test("ImagePlugin image_result waits by default and returns final message", async () => {
+test("ImagePlugin exposes action metadata through plugin registry", async () => {
+  const plugin = new ImagePlugin({
+    image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+  });
+  const registry = create_registry(plugin);
+
+  const metadata = registry.read({
+    plugin: "image",
+    action: "image_create",
+  });
+
+  assert.equal(metadata.name, "image");
+  assert.equal(metadata.actions.length, 1);
+  assert.equal(metadata.actions[0].name, "image_create");
+  assert.equal(metadata.actions[0].has_input_schema, true);
+  assert.match(metadata.actions[0].description, /Create an async image job/);
+  assert.equal(metadata.actions[0].examples[0].payload.prompt.includes("rainy city"), true);
+});
+
+test("ImagePlugin image_result reads pending state once", async () => {
   const calls = [];
-  const message = create_image_message();
   const plugin = new ImagePlugin({
-    min_poll_interval_ms: 1,
     image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
     image_result: (input) => {
       calls.push(input.job_id);
-      return calls.length === 1
-        ? { job_id: input.job_id, status: "running", poll_after_ms: 1 }
-        : { job_id: input.job_id, status: "succeeded", result: message, poll_after_ms: 1 };
+      return {
+        job_id: input.job_id,
+        status: "running",
+        message: "upstream pending",
+        poll_after_ms: 1,
+      };
     },
   });
 
   const result = await plugin.actions.image_result.execute({
-    context: {},
+    context: create_context(),
     payload: { job_id: "img_1" },
     pluginName: "image",
     actionName: "image_result",
   });
 
   assert.equal(result.success, true);
-  assert.equal(result.data.role, "assistant");
-  assert.equal(result.data.parts[0].type, "file");
-  assert.deepEqual(calls, ["img_1", "img_1"]);
+  assert.equal(result.data.job_id, "img_1");
+  assert.equal(result.data.status, "running");
+  assert.equal(result.data.message, "upstream pending");
+  assert.deepEqual(calls, ["img_1"]);
 });
 
-test("ImagePlugin image_result can read once without waiting", async () => {
-  const calls = [];
+test("ImagePlugin image_result returns final message when succeeded", async () => {
+  const message = create_image_message();
   const plugin = new ImagePlugin({
-    min_poll_interval_ms: 1,
     image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
-    image_result: (input) => {
-      calls.push(input.job_id);
-      return { job_id: input.job_id, status: "running", poll_after_ms: 1 };
-    },
+    image_result: (input) => ({
+      job_id: input.job_id,
+      status: "succeeded",
+      result: message,
+      poll_after_ms: 1,
+    }),
   });
 
   const result = await plugin.actions.image_result.execute({
-    context: {},
-    payload: { job_id: "img_1", until_finish: false },
+    context: create_context(),
+    payload: { job_id: "img_1" },
     pluginName: "image",
     actionName: "image_result",
   });
 
   assert.equal(result.success, true);
-  assert.equal(result.data.job_id, "img_1");
-  assert.equal(result.data.status, "running");
-  assert.deepEqual(calls, ["img_1"]);
+  assert.equal(result.data.role, "assistant");
+  assert.equal(result.data.parts[0].type, "file");
 });
 
-test("ImagePlugin image_result reports failed terminal job by default", async () => {
+test("ImagePlugin image_result reports failed terminal job", async () => {
   const plugin = new ImagePlugin({
-    min_poll_interval_ms: 1,
     image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
     image_result: (input) => ({
       job_id: input.job_id,
@@ -186,7 +200,7 @@ test("ImagePlugin image_result reports failed terminal job by default", async ()
   });
 
   const result = await plugin.actions.image_result.execute({
-    context: {},
+    context: create_context(),
     payload: { job_id: "img_1" },
     pluginName: "image",
     actionName: "image_result",
@@ -194,22 +208,149 @@ test("ImagePlugin image_result reports failed terminal job by default", async ()
 
   assert.equal(result.success, false);
   assert.match(result.error, /provider failed/);
+  assert.equal(result.data.job_id, "img_1");
 });
 
-test("ImagePlugin generate reports image failure", async () => {
+test("ImagePlugin image_result payload is schema validated by registry", async () => {
   const plugin = new ImagePlugin({
-    min_poll_interval_ms: 1,
     image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
-    image_result: () => ({ job_id: "img_1", status: "failed", error: "provider failed", poll_after_ms: 1 }),
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
   });
+  const registry = create_registry(plugin);
 
-  const result = await plugin.actions.generate.execute({
-    context: {},
-    payload: { prompt: "draw" },
-    pluginName: "image",
-    actionName: "generate",
+  const result = await registry.runAction({
+    plugin: "image",
+    action: "image_result",
+    payload: {},
   });
 
   assert.equal(result.success, false);
-  assert.match(result.error, /provider failed/);
+  assert.match(result.error, /Invalid payload/);
+});
+
+test("ImagePlugin image_create converts local content image paths", async () => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-image-plugin-content-"));
+  try {
+    await fs.writeFile(path.join(tempDir, "input.png"), Buffer.from("png"));
+    let captured_input;
+    const plugin = new ImagePlugin({
+      image_create: (input) => {
+        captured_input = input;
+        return { job_id: "img_1", status: "queued", poll_after_ms: 1 };
+      },
+      image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+    });
+
+    const result = await plugin.actions.image_create.execute({
+      context: create_context(tempDir),
+      payload: {
+        content: [
+          { type: "text", text: "change background" },
+          { type: "image", url: "./input.png" },
+        ],
+      },
+      pluginName: "image",
+      actionName: "image_create",
+    });
+
+    assert.equal(result.success, true);
+    assert.equal(captured_input.messages[0].content[0].text, "change background");
+    assert.match(captured_input.messages[0].content[1].data_url, /^data:image\/png;base64,/);
+    assert.equal(captured_input.messages[0].content[1].media_type, "image/png");
+    assert.equal("content" in captured_input, false);
+    assert.equal("prompt" in captured_input, false);
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("ImagePlugin image_create uses content instead of prompt when both exist", async () => {
+  let captured_input;
+  const plugin = new ImagePlugin({
+    image_create: (input) => {
+      captured_input = input;
+      return { job_id: "img_1", status: "queued", poll_after_ms: 1 };
+    },
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+  });
+
+  const result = await plugin.actions.image_create.execute({
+    context: create_context(),
+    payload: {
+      prompt: "ignore this prompt",
+      content: [{ type: "text", text: "use this content" }],
+    },
+    pluginName: "image",
+    actionName: "image_create",
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(captured_input.messages[0].content[0].text, "use this content");
+  assert.equal("prompt" in captured_input, false);
+});
+
+test("ImagePlugin image_create keeps remote content image URLs", async () => {
+  let captured_input;
+  const plugin = new ImagePlugin({
+    image_create: (input) => {
+      captured_input = input;
+      return { job_id: "img_1", status: "queued", poll_after_ms: 1 };
+    },
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+  });
+
+  const result = await plugin.actions.image_create.execute({
+    context: create_context(),
+    payload: {
+      content: [
+        { type: "text", text: "use this style" },
+        { type: "image", url: "https://example.com/input.webp", media_type: "image/webp" },
+      ],
+    },
+    pluginName: "image",
+    actionName: "image_create",
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(captured_input.messages[0].content[1].url, "https://example.com/input.webp");
+  assert.equal(captured_input.messages[0].content[1].media_type, "image/webp");
+});
+
+test("ImagePlugin image_create rejects legacy messages and data URLs", async () => {
+  const plugin = new ImagePlugin({
+    image_create: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+    image_result: () => ({ job_id: "img_1", status: "queued", poll_after_ms: 1 }),
+  });
+
+  const messages_result = await plugin.actions.image_create.execute({
+    context: create_context(),
+    payload: {
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: "legacy" }],
+        },
+      ],
+    },
+    pluginName: "image",
+    actionName: "image_create",
+  });
+
+  assert.equal(messages_result.success, false);
+  assert.match(messages_result.error, /messages is not supported/);
+
+  const data_url_result = await plugin.actions.image_create.execute({
+    context: create_context(),
+    payload: {
+      content: [
+        { type: "text", text: "edit this" },
+        { type: "image", url: "data:image/png;base64,cG5n" },
+      ],
+    },
+    pluginName: "image",
+    actionName: "image_create",
+  });
+
+  assert.equal(data_url_result.success, false);
+  assert.match(data_url_result.error, /does not accept data URLs/);
 });

package/scripts/plugin-tool-bridge.test.mjs

@@ -14,9 +14,13 @@ import fs from "node:fs/promises";
 
 import {
   invokePluginCallTool,
+  invokePluginReadTool,
   setPluginToolRuntime,
 } from "../bin/executor/tools/plugin/PluginToolBridge.js";
 import { withSessionRunScope } from "../bin/executor/SessionRunScope.js";
+import { createAction, createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
+import { createAgentPluginRegistry } from "../bin/agent/local/AgentPluginFactory.js";
+import { z } from "zod";
 
 function create_run_context(project_root) {
   return {
@@ -36,6 +40,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
 
   setPluginToolRuntime({
     list: () => [],
+    read: () => ({ plugins: [] }),
     availability: async () => ({ enabled: true, available: true, reasons: [] }),
     runAction: async () => ({
       success: true,
@@ -65,8 +70,8 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
   const result = await withSessionRunScope({ runContext: run_context }, () =>
     invokePluginCallTool({
       plugin: "image",
-      action: "generate",
-      payload: { prompt: "draw" },
+      action: "image_result",
+      payload: { job_id: "img_1" },
     }),
   );
 
@@ -86,3 +91,109 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
   assert.equal(pending_parts.length, 1);
   assert.equal(pending_parts[0].url, result.files[0].url);
 });
+
+test("invokePluginReadTool returns plugin action metadata", async () => {
+  setPluginToolRuntime({
+    list: () => [],
+    read: () => ({
+      name: "image",
+      title: "Image",
+      description: "Create images",
+      actions: [
+        {
+          name: "image_create",
+          description: "Create image job",
+          has_input_schema: true,
+          input_schema: {
+            type: "object",
+            properties: {
+              prompt: { type: "string" },
+            },
+          },
+          examples: [
+            {
+              title: "Text-only image",
+              payload: { prompt: "draw" },
+            },
+          ],
+          allow_when_disabled: false,
+          has_command: false,
+          has_api: false,
+        },
+      ],
+    }),
+    availability: async () => ({ enabled: true, available: true, reasons: [] }),
+    runAction: async () => ({ success: false, error: "not used" }),
+    pipeline: async (_, value) => value,
+    guard: async () => {},
+    effect: async () => {},
+    resolve: async () => {
+      throw new Error("not implemented");
+    },
+  });
+
+  const result = await invokePluginReadTool({
+    plugin: "image",
+    action: "image_create",
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.data.name, "image");
+  assert.equal(result.data.actions[0].name, "image_create");
+  assert.equal(result.data.actions[0].has_input_schema, true);
+  assert.equal(result.data.actions[0].examples[0].payload.prompt, "draw");
+});
+
+test("PluginRegistry validates action payload with metadata schema", async () => {
+  const plugin = createPlugin({
+    name: "demo",
+    title: "Demo",
+    description: "Demo plugin",
+    actions: {
+      echo: createAction({
+        description: "Echo text",
+        input_schema: {
+          zod: z.object({
+            text: z.string(),
+          }),
+          json_schema: {
+            type: "object",
+            required: ["text"],
+            properties: {
+              text: { type: "string" },
+            },
+          },
+        },
+        execute: async ({ input }) => ({
+          success: true,
+          data: { text: input.text },
+          message: "echoed",
+        }),
+      }),
+    },
+  });
+  const registry = createAgentPluginRegistry({
+    plugins: [plugin],
+    get_context: () => ({ rootPath: process.cwd() }),
+  });
+
+  const metadata = registry.read({ plugin: "demo", action: "echo" });
+  assert.equal(metadata.actions[0].description, "Echo text");
+  assert.equal(metadata.actions[0].has_input_schema, true);
+
+  const invalid = await registry.runAction({
+    plugin: "demo",
+    action: "echo",
+    payload: {},
+  });
+  assert.equal(invalid.success, false);
+  assert.match(invalid.error, /Invalid payload/);
+
+  const valid = await registry.runAction({
+    plugin: "demo",
+    action: "echo",
+    payload: { text: "hello" },
+  });
+  assert.equal(valid.success, true);
+  assert.equal(valid.data.text, "hello");
+});

package/src/agent/local/services/AgentAssemblyService.ts

@@ -184,6 +184,7 @@ export class AgentAssemblyService {
     });
     const plugins = plugin_registry;
     if (this.should_register_plugin_call_tool(plugin_instances)) {
+      tools.plugin_read = tools.plugin_read || plugin_tools.plugin_read;
       tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
     }
     const resolve_session_model = this.resolve_session_model;

package/src/executor/composer/system/default/assets/plugin.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/plugin.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "# Plugin State\n\n你正在一个基于 plugin 的执行环境中工作。\n\n## Plugin 调用规则\n\n- 当你需要使用 plugin 能力时，优先通过可用的 tool 调用 plugin action。\n- 若当前工具集中存在 `plugin_call`，使用 `plugin_call({ plugin, action, payload })` 触发对应 plugin action。\n- `plugin_call.plugin` 是 plugin 名称，例如 `skill`、`task`、`memory`、`contact`。\n- `plugin_call.action` 是 action 名称，例如 `list`、`lookup`、`create`、`run`。\n- `plugin_call.payload` 是结构化 JSON payload；没有参数时传 `{}`。\n- ActionSchedule 是 Agent 内部用于延迟执行 plugin action 的能力，不是独立 plugin。\n\n## 可用 plugin 概览\n\n- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact`。\n- 当前内建本地 plugin：`auth` / `skill`。\n\n具体 plugin 能力以该 plugin 的 action 和 system 提示为准。\n";
+const TEXT_MODULE_CONTENT = "# Plugin State\n\n你正在一个基于 plugin 的执行环境中工作。\n\n## Plugin 调用规则\n\n- 当你需要使用 plugin 能力时，优先通过可用的 tool 调用 plugin action。\n- 若当前工具集中存在 `plugin_read`，在不确定 plugin action、参数 schema 或示例时，先使用 `plugin_read({ plugin, action? })` 读取 metadata。\n- 若当前工具集中存在 `plugin_call`，使用 `plugin_call({ plugin, action, payload })` 触发对应 plugin action。\n- `plugin_call.plugin` 是 plugin 名称，例如 `skill`、`task`、`memory`、`contact`。\n- `plugin_call.action` 是 action 名称，例如 `list`、`lookup`、`create`、`run`。\n- `plugin_call.payload` 是结构化 JSON payload；没有参数时传 `{}`。如果 action metadata 声明了 input schema，payload 必须符合 schema。\n- ActionSchedule 是 Agent 内部用于延迟执行 plugin action 的能力，不是独立 plugin。\n\n## 可用 plugin 概览\n\n- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact`。\n- 当前内建本地 plugin：`auth` / `skill`。\n\n具体 plugin 能力以 `plugin_read` 返回的 action metadata 和该 plugin 的 system 提示为准。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/plugin.prompt.ts.txt

@@ -5,10 +5,11 @@
 ## Plugin 调用规则
 
 - 当你需要使用 plugin 能力时，优先通过可用的 tool 调用 plugin action。
+- 若当前工具集中存在 `plugin_read`，在不确定 plugin action、参数 schema 或示例时，先使用 `plugin_read({ plugin, action? })` 读取 metadata。
 - 若当前工具集中存在 `plugin_call`，使用 `plugin_call({ plugin, action, payload })` 触发对应 plugin action。
 - `plugin_call.plugin` 是 plugin 名称，例如 `skill`、`task`、`memory`、`contact`。
 - `plugin_call.action` 是 action 名称，例如 `list`、`lookup`、`create`、`run`。
-- `plugin_call.payload` 是结构化 JSON payload；没有参数时传 `{}`。
+- `plugin_call.payload` 是结构化 JSON payload；没有参数时传 `{}`。如果 action metadata 声明了 input schema，payload 必须符合 schema。
 - ActionSchedule 是 Agent 内部用于延迟执行 plugin action 的能力，不是独立 plugin。
 
 ## 可用 plugin 概览
@@ -16,4 +17,4 @@
 - 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact`。
 - 当前内建本地 plugin：`auth` / `skill`。
 
-具体 plugin 能力以该 plugin 的 action 和 system 提示为准。
+具体 plugin 能力以 `plugin_read` 返回的 action metadata 和该 plugin 的 system 提示为准。

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -15,6 +15,8 @@ import type {
   PluginCallInput,
   PluginCallToolFileResult,
   PluginCallToolResult,
+  PluginReadInput,
+  PluginReadToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
 import { materializeAssistantFileParts } from "@executor/messages/AssistantFileResource.js";
 import {
@@ -206,3 +208,31 @@ export async function invokePluginCallTool(
     };
   }
 }
+
+/**
+ * 读取 plugin / action metadata。
+ */
+export async function invokePluginReadTool(
+  input: PluginReadInput,
+): Promise<PluginReadToolResult> {
+  try {
+    const runtime = require_plugin_tool_runtime();
+    const data = runtime.read({
+      plugin: typeof input.plugin === "string" ? input.plugin : undefined,
+      action: typeof input.action === "string" ? input.action : undefined,
+    });
+    return {
+      success: true,
+      message: "plugin metadata read",
+      data: data as unknown as JsonObject,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: String(error),
+      data: {
+        error: String(error),
+      },
+    };
+  }
+}

package/src/executor/tools/plugin/PluginToolDefinition.ts

@@ -8,9 +8,19 @@
  */
 
 import { tool } from "ai";
-import type { PluginCallInput } from "@/executor/tools/plugin/types/PluginTool.js";
-import { invokePluginCallTool, setPluginToolRuntime } from "./PluginToolBridge.js";
-import { plugin_call_input_schema } from "./PluginToolSchemas.js";
+import type {
+  PluginCallInput,
+  PluginReadInput,
+} from "@/executor/tools/plugin/types/PluginTool.js";
+import {
+  invokePluginCallTool,
+  invokePluginReadTool,
+  setPluginToolRuntime,
+} from "./PluginToolBridge.js";
+import {
+  plugin_call_input_schema,
+  plugin_read_input_schema,
+} from "./PluginToolSchemas.js";
 
 export { setPluginToolRuntime } from "./PluginToolBridge.js";
 
@@ -19,14 +29,25 @@ export { setPluginToolRuntime } from "./PluginToolBridge.js";
  */
 export const plugin_call = tool({
   description:
-    "Call a registered agent plugin action. Use this for plugin capabilities such as image generation. Generated files may be attached to the final assistant message automatically.",
+    "Call a registered agent plugin action. Use plugin_read first when you need the action list, input schema, or examples. Generated files may be attached to the final assistant message automatically.",
   inputSchema: plugin_call_input_schema,
   execute: async (input) => await invokePluginCallTool(input as PluginCallInput),
 });
 
+/**
+ * `plugin_read`：读取已注册 plugin / action metadata。
+ */
+export const plugin_read = tool({
+  description:
+    "Read registered agent plugin metadata, including action names, descriptions, input schemas, and examples. Use this before plugin_call when the payload shape is unclear.",
+  inputSchema: plugin_read_input_schema,
+  execute: async (input) => await invokePluginReadTool(input as PluginReadInput),
+});
+
 /**
  * Plugin 工具导出集合。
  */
 export const plugin_tools = {
   plugin_call,
+  plugin_read,
 };

package/src/executor/tools/plugin/PluginToolSchemas.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 
 export const plugin_call_input_schema = z.object({
   plugin: z.string().describe("Registered plugin name to call, for example image."),
-  action: z.string().describe("Plugin action name to execute, for example generate."),
+  action: z.string().describe("Plugin action name to execute, for example image_create."),
   payload: z
     .object({})
     .passthrough()
@@ -18,3 +18,14 @@ export const plugin_call_input_schema = z.object({
     .default({})
     .describe("JSON payload passed to the plugin action."),
 });
+
+export const plugin_read_input_schema = z.object({
+  plugin: z
+    .string()
+    .optional()
+    .describe("Registered plugin name to inspect. Omit to list plugins."),
+  action: z
+    .string()
+    .optional()
+    .describe("Plugin action name to inspect. Requires plugin."),
+});