@downcity/agent 1.1.153 → 1.1.160

package/src/executor/messages/AssistantFileResource.ts

@@ -140,22 +140,92 @@ async function read_remote_resource(raw_url: string): Promise<{
   filename?: string;
   bytes: Buffer;
 }> {
-  const response = await fetch(raw_url);
-  if (!response.ok) {
-    throw new Error(`Failed to download assistant file resource: ${response.status}`);
+  const result = await fetch_with_retry(raw_url);
+  if (!result.ok) {
+    throw new Error(
+      `Failed to download assistant file resource: ${result.status} :: url=${raw_url}`,
+    );
   }
-  const array_buffer = await response.arrayBuffer();
+  const array_buffer = await result.arrayBuffer();
   const bytes = Buffer.from(array_buffer);
   if (bytes.length === 0) {
-    throw new Error("Downloaded assistant file resource is empty");
+    throw new Error(`Downloaded assistant file resource is empty :: url=${raw_url}`);
   }
   return {
-    mediaType: response.headers.get("content-type")?.split(";")[0]?.trim(),
+    mediaType: result.headers.get("content-type")?.split(";")[0]?.trim(),
     filename: filename_from_url(raw_url),
     bytes,
   };
 }
 
+/**
+ * 带重试的 fetch 远程资源。
+ *
+ * 关键点（中文）
+ * - 对 transient 网络错误（fetch failed / UND_ERR_* / ECONNRESET 等）做 2 次指数退避重试。
+ * - 最终失败时把 error.cause 链展开到 message，方便定位是代理问题、DNS 问题还是上游问题。
+ */
+async function fetch_with_retry(
+  raw_url: string,
+): Promise<Response> {
+  const delays_ms = [250, 1_000];
+  const attempts = delays_ms.length + 1;
+  let last_error: unknown;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await fetch(raw_url);
+    } catch (error) {
+      last_error = error;
+      if (!is_transient_fetch_error(error) || attempt === attempts - 1) {
+        throw enrich_fetch_error(error, raw_url);
+      }
+      const delay_ms = delays_ms[attempt] ?? 1_000;
+      await new Promise((resolve) => setTimeout(resolve, delay_ms));
+    }
+  }
+  throw enrich_fetch_error(last_error, raw_url);
+}
+
+function is_transient_fetch_error(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const text = `${error.message} ${describe_error_cause(error)}`;
+  return /fetch failed|UND_ERR|ECONN(RESET|REFUSED|ABORTED)|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up/i.test(
+    text,
+  );
+}
+
+function enrich_fetch_error(error: unknown, url: string): Error {
+  if (!(error instanceof Error)) {
+    return new Error(`Download failed: ${String(error)} :: url=${url}`);
+  }
+  const cause_text = describe_error_cause(error);
+  const enriched = new Error(
+    `${error.message}${cause_text ? ` :: cause=${cause_text}` : ""} :: url=${url}`,
+    error.cause ? { cause: error.cause } : undefined,
+  );
+  enriched.stack = error.stack;
+  return enriched;
+}
+
+function describe_error_cause(error: Error): string {
+  const parts: string[] = [];
+  let current: unknown = (error as { cause?: unknown }).cause;
+  let depth = 0;
+  while (current && depth < 3) {
+    if (current instanceof Error) {
+      const code = (current as { code?: unknown }).code;
+      const code_text = typeof code === "string" && code ? `[${code}] ` : "";
+      parts.push(`${code_text}${current.message || current.name}`.trim());
+      current = (current as { cause?: unknown }).cause;
+    } else {
+      parts.push(String(current));
+      break;
+    }
+    depth += 1;
+  }
+  return parts.filter(Boolean).join(" -> ");
+}
+
 async function read_local_resource(
   projectRoot: string,
   raw_url: string,
@@ -191,19 +261,55 @@ async function materialize_file_part(params: {
   if (raw_url.startsWith("resources://")) return params.part;
 
   const parsed_data_url = parse_data_url(raw_url);
-  const source = parsed_data_url
-    ? {
-        mediaType: parsed_data_url.media_type,
+  if (parsed_data_url) {
+    const media_type =
+      String(params.part.mediaType || parsed_data_url.media_type || "").trim() ||
+      "application/octet-stream";
+    const file_path = await write_resource_file({
+      projectRoot: params.projectRoot,
+      mediaType: media_type,
+      filename:
+        typeof params.part.filename === "string" ? params.part.filename : undefined,
+      bytes: parsed_data_url.bytes,
+    });
+    return {
+      ...params.part,
+      mediaType: media_type,
+      url: to_resources_url(params.projectRoot, file_path),
+    };
+  }
+
+  if (raw_url.startsWith("http://") || raw_url.startsWith("https://")) {
+    try {
+      const source = await read_remote_resource(raw_url);
+      const media_type =
+        String(params.part.mediaType || source.mediaType || "").trim() ||
+        "application/octet-stream";
+      const file_path = await write_resource_file({
+        projectRoot: params.projectRoot,
+        mediaType: media_type,
         filename:
           typeof params.part.filename === "string"
             ? params.part.filename
-            : undefined,
-        bytes: parsed_data_url.bytes,
-      }
-    : raw_url.startsWith("http://") || raw_url.startsWith("https://")
-      ? await read_remote_resource(raw_url)
-      : await read_local_resource(params.projectRoot, raw_url);
+            : source.filename,
+        bytes: source.bytes,
+      });
+      return {
+        ...params.part,
+        mediaType: media_type,
+        url: to_resources_url(params.projectRoot, file_path),
+      };
+    } catch (error) {
+      // 关键点（中文）：远程下载失败时保留原始 URL，不让整张图导致 action 失败。
+      // 这样图片至少以链接形式存在，用户可手动点击或后续再试。
+      console.warn(
+        `[AssistantFileResource] remote download failed, keeping original url :: ${describe_error_cause(error instanceof Error ? error : new Error(String(error)))} :: url=${raw_url}`,
+      );
+      return params.part;
+    }
+  }
 
+  const source = await read_local_resource(params.projectRoot, raw_url);
   const media_type =
     String(params.part.mediaType || source.mediaType || "").trim() ||
     "application/octet-stream";
@@ -216,7 +322,6 @@ async function materialize_file_part(params: {
         : source.filename,
     bytes: source.bytes,
   });
-
   return {
     ...params.part,
     mediaType: media_type,

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."),
+});

package/src/executor/tools/plugin/types/PluginTool.ts

@@ -20,6 +20,16 @@ export interface PluginCallInput {
   payload?: JsonObject;
 }
 
+/**
+ * plugin_read 输入。
+ */
+export interface PluginReadInput {
+  /** 要读取的 plugin 名称；不传则列出 plugin 概览。 */
+  plugin?: string;
+  /** 要读取的 action 名称；仅在 plugin 存在时生效。 */
+  action?: string;
+}
+
 /**
  * plugin_call 产生的 assistant 文件摘要。
  */
@@ -57,3 +67,15 @@ export interface PluginCallToolResult {
   /** 返回给模型读取的短摘要数据。 */
   data?: JsonObject;
 }
+
+/**
+ * plugin_read 返回给模型的 metadata。
+ */
+export interface PluginReadToolResult {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 人类可读消息。 */
+  message: string;
+  /** 读取到的 metadata。 */
+  data: JsonObject;
+}

package/src/index.ts

@@ -72,6 +72,14 @@ export type {
 
 // Plugin 作者 API
 export { BasePlugin } from "./plugin/core/BasePlugin.js";
+export {
+  createAction,
+  createPlugin,
+} from "./plugin/core/PluginActionFactory.js";
+export type {
+  CreatePluginActionOptions,
+  CreatePluginOptions,
+} from "./plugin/core/PluginActionFactory.js";
 
 // Session 与即时执行集成
 export { Executor } from "./executor/Executor.js";
@@ -229,6 +237,9 @@ export type {
   PluginActionApi,
   PluginActionCommand,
   PluginActionCommandInput,
+  PluginActionExample,
+  PluginActionInputSchema,
+  PluginActionMetadata,
   PluginActionResult,
   PluginActions,
   PluginAvailability,

package/src/plugin/core/PluginActionFactory.ts

@@ -0,0 +1,185 @@
+/**
+ * PluginActionFactory：创建带 metadata 和 schema 的 plugin/action。
+ *
+ * 关键点（中文）
+ * - `createAction` 让 action 的运行时 schema 与 TypeScript 输入类型保持一致。
+ * - `createPlugin` 只做轻量对象装配，不强制继承 BasePlugin。
+ * - 旧的 class extends BasePlugin 写法仍可继续使用。
+ */
+
+import type { z } from "zod";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type {
+  PluginAction,
+  PluginActionApi,
+  PluginActionCommand,
+  PluginActionExample,
+  PluginActionInputSchema,
+  PluginActionResult,
+  PluginActions,
+} from "@/types/plugin/PluginAction.js";
+import type { Plugin } from "@/types/plugin/PluginDefinition.js";
+import type {
+  PluginAvailability,
+  PluginConfigDefinition,
+  PluginHooks,
+  PluginResolves,
+} from "@/types/plugin/PluginRuntime.js";
+import type {
+  PluginCommandContext,
+  PluginLifecycle,
+} from "@/types/plugin/PluginCommand.js";
+import type {
+  PluginSetupDefinition,
+  PluginUsageDefinition,
+} from "@/types/plugin/PluginSetup.js";
+import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
+import type { StructuredConfig } from "@/types/runtime/agent/AgentContext.js";
+
+/**
+ * 从 Zod schema 推导 JSON 输入类型。
+ */
+type InferZodJson<TSchema extends z.ZodTypeAny> =
+  z.infer<TSchema> extends JsonValue ? z.infer<TSchema> : JsonValue;
+
+/**
+ * createAction 参数。
+ */
+export interface CreatePluginActionOptions<
+  P extends JsonValue,
+  R extends JsonValue,
+> {
+  /** Action 用途说明。 */
+  description?: string;
+  /** Zod 输入 schema。 */
+  input_schema?: z.ZodTypeAny | PluginActionInputSchema<P>;
+  /** Action 调用示例。 */
+  examples?: PluginActionExample<P>[];
+  /** disabled 状态下是否仍允许执行。 */
+  allowWhenDisabled?: boolean;
+  /** CLI 定义。 */
+  command?: PluginActionCommand<P>;
+  /** HTTP 定义。 */
+  api?: PluginActionApi<P>;
+  /** Action 执行器。 */
+  execute: (params: {
+    /** 当前执行上下文。 */
+    context: AgentContext;
+    /** 已通过 schema 校验后的输入。 */
+    input: P;
+    /** 兼容旧命名的 payload。 */
+    payload: P;
+    /** 当前插件名称。 */
+    pluginName: string;
+    /** 当前 Action 名称。 */
+    actionName: string;
+  }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
+}
+
+/**
+ * createPlugin 参数。
+ */
+export interface CreatePluginOptions<TActions extends PluginActions> {
+  /** Plugin 稳定名称。 */
+  name: string;
+  /** Plugin 展示标题。 */
+  title?: string;
+  /** Plugin 用途说明。 */
+  description?: string;
+  /** Plugin 显式 action 集合。 */
+  actions?: TActions;
+  /** Plugin 配置定义。 */
+  config?: PluginConfigDefinition<StructuredConfig>;
+  /** Plugin setup 定义。 */
+  setup?: PluginSetupDefinition;
+  /** Plugin usage 定义。 */
+  usage?: PluginUsageDefinition;
+  /** Plugin hook 集合。 */
+  hooks?: PluginHooks;
+  /** Plugin resolve 集合。 */
+  resolves?: PluginResolves;
+  /** Plugin system 文本构建器。 */
+  system?: (context: AgentContext) => string | Promise<string>;
+  /** 旧生命周期兼容定义。 */
+  lifecycle?: PluginLifecycle;
+  /** Plugin 可用性检查。 */
+  availability?: (
+    context: PluginCommandContext | AgentContext,
+  ) => Promise<PluginAvailability> | PluginAvailability;
+  /** Plugin HTTP 注入定义。 */
+  http?: PluginHttpDefinition;
+}
+
+/**
+ * 归一化输入 schema。
+ */
+function normalize_input_schema<P extends JsonValue>(
+  input_schema: z.ZodTypeAny | PluginActionInputSchema<P> | undefined,
+): PluginActionInputSchema<P> | undefined {
+  if (!input_schema) return undefined;
+  if (typeof (input_schema as z.ZodTypeAny).safeParse === "function") {
+    return { zod: input_schema as z.ZodTypeAny };
+  }
+  return input_schema as PluginActionInputSchema<P>;
+}
+
+/**
+ * 创建带 metadata 的 action。
+ */
+export function createAction<
+  TSchema extends z.ZodTypeAny,
+  R extends JsonValue = JsonValue,
+>(
+  options: CreatePluginActionOptions<InferZodJson<TSchema>, R> & {
+    /** Zod 输入 schema。 */
+    input_schema?: TSchema | PluginActionInputSchema<InferZodJson<TSchema>>;
+  },
+): PluginAction<InferZodJson<TSchema>, R>;
+export function createAction<R extends JsonValue = JsonValue>(
+  options: CreatePluginActionOptions<JsonValue, R>,
+): PluginAction<JsonValue, R>;
+export function createAction(
+  options: CreatePluginActionOptions<JsonValue, JsonValue>,
+): PluginAction<JsonValue, JsonValue> {
+  return {
+    ...(options.description ? { description: options.description } : {}),
+    ...(options.input_schema
+      ? { input_schema: normalize_input_schema(options.input_schema) }
+      : {}),
+    ...(options.examples ? { examples: options.examples } : {}),
+    ...(typeof options.allowWhenDisabled === "boolean"
+      ? { allowWhenDisabled: options.allowWhenDisabled }
+      : {}),
+    ...(options.command ? { command: options.command } : {}),
+    ...(options.api ? { api: options.api } : {}),
+    execute: options.execute,
+  };
+}
+
+/**
+ * 创建 plugin 对象。
+ */
+export function createPlugin<TActions extends PluginActions>(
+  options: CreatePluginOptions<TActions>,
+): Plugin & { actions: TActions } {
+  const name = String(options.name || "").trim();
+  if (!name) {
+    throw new Error("createPlugin requires a non-empty name");
+  }
+  return {
+    name,
+    title: String(options.title || name).trim(),
+    description: String(options.description || "").trim(),
+    actions: options.actions || ({} as TActions),
+    ...(options.config ? { config: options.config } : {}),
+    ...(options.setup ? { setup: options.setup } : {}),
+    ...(options.usage ? { usage: options.usage } : {}),
+    ...(options.hooks ? { hooks: options.hooks } : {}),
+    ...(options.resolves ? { resolves: options.resolves } : {}),
+    ...(options.system ? { system: options.system } : {}),
+    ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+    ...(options.availability ? { availability: options.availability } : {}),
+    ...(options.http ? { http: options.http } : {}),
+  };
+}

package/src/plugin/core/PluginActionRunner.ts

@@ -58,9 +58,22 @@ export async function invokePluginAction(params: {
   }
 
   try {
+    const payload = (params.payload ?? {}) as JsonValue;
+    const schema = action.input_schema?.zod;
+    const parsed_payload = schema ? schema.safeParse(payload) : null;
+    if (parsed_payload && !parsed_payload.success) {
+      return {
+        success: false,
+        error: `Invalid payload for ${params.plugin.name}.${params.actionName}: ${parsed_payload.error.message}`,
+      };
+    }
+    const input_payload = parsed_payload?.success
+      ? parsed_payload.data as JsonValue
+      : payload;
     return await action.execute({
       context: params.context,
-      payload: (params.payload ?? {}) as JsonValue,
+      payload: input_payload,
+      input: input_payload,
       pluginName: params.plugin.name,
       actionName: params.actionName,
     });

package/src/plugin/core/PluginLocalExecution.ts

@@ -135,9 +135,23 @@ export async function runLocalPluginAction(params: {
   }
 
   try {
+    const payload = (params.payload ?? {}) as JsonValue;
+    const schema = action.input_schema?.zod;
+    const parsed_payload = schema ? schema.safeParse(payload) : null;
+    if (parsed_payload && !parsed_payload.success) {
+      return {
+        success: false,
+        error: `Invalid payload for ${plugin.name}.${actionName}: ${parsed_payload.error.message}`,
+        message: `Invalid payload for ${plugin.name}.${actionName}`,
+      };
+    }
+    const input_payload = parsed_payload?.success
+      ? parsed_payload.data as JsonValue
+      : payload;
     return await action.execute({
       context: context as unknown as AgentContext,
-      payload: (params.payload ?? {}) as JsonValue,
+      payload: input_payload,
+      input: input_payload,
       pluginName: plugin.name,
       actionName,
     });