@downcity/agent 1.1.152 → 1.1.157

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

@@ -4,15 +4,19 @@
  * 关键点（中文）
  * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 AgentPlugins 调用 action。
  * - 如果 action 返回 AI SDK UIMessage，则抽取 file parts 并入最终 assistant 消息。
- * - 返回给模型的 tool result 只保留短摘要，避免 data URL 等大内容污染上下文。
+ * - 返回给模型的 tool result 只保留短摘要和本地绝对路径，避免 data URL 等大内容污染上下文。
  */
 
+import path from "node:path";
 import type { FileUIPart } from "ai";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   PluginCallInput,
+  PluginCallToolFileResult,
   PluginCallToolResult,
+  PluginReadInput,
+  PluginReadToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
 import { materializeAssistantFileParts } from "@executor/messages/AssistantFileResource.js";
 import {
@@ -69,27 +73,57 @@ function extract_assistant_file_parts(data: JsonValue | undefined): FileUIPart[]
   return parts.filter(is_file_part);
 }
 
+/**
+ * 解析当前项目根目录，保持与 assistant 文件落盘逻辑一致。
+ */
+function resolve_project_root(project_root: string | undefined): string {
+  const raw = String(project_root || "").trim();
+  return path.resolve(raw || process.cwd());
+}
+
+/**
+ * 将 `resources://` URL 转成本机绝对路径。
+ */
+function resolve_resources_file_path(
+  project_root: string,
+  raw_url: string,
+): string {
+  const prefix = "resources://";
+  const raw = String(raw_url || "").trim();
+  if (!raw.startsWith(prefix)) return "";
+  const relative = raw.slice(prefix.length).replace(/^\/+/, "");
+  if (!relative) return "";
+
+  const file_path = path.resolve(project_root, relative);
+  const rel = path.relative(project_root, file_path);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return "";
+  return file_path;
+}
+
+/**
+ * 构建返回给模型和用户可见的文件摘要。
+ */
+function summarize_materialized_files(
+  parts: FileUIPart[],
+  project_root: string,
+): PluginCallToolFileResult[] {
+  return parts.map((part, index) => ({
+    index,
+    media_type: part.mediaType,
+    filename: typeof part.filename === "string" ? part.filename : "",
+    url: String(part.url || ""),
+    path: resolve_resources_file_path(project_root, String(part.url || "")),
+  }));
+}
+
 /**
  * 生成给模型读取的短摘要。
  */
-function summarize_action_data(data: JsonValue | undefined): JsonObject {
+function summarize_action_data(data: JsonValue | undefined): JsonObject | undefined {
   const message = to_json_object(data);
   const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
-  const file_parts = parts.filter(is_file_part);
   if (parts.length > 0) {
-    return {
-      kind: "ui_message",
-      role: typeof message?.role === "string" ? message.role : "assistant",
-      part_count: parts.length,
-      file_count: file_parts.length,
-      files: file_parts.map((part, index) => ({
-        index,
-        mediaType: part.mediaType,
-        filename: typeof part.filename === "string" ? part.filename : "",
-        // 关键点（中文）：不把 data URL 或长 URL 原样返回给模型，完整内容只进入 assistant file part。
-        has_url: Boolean(part.url),
-      })),
-    };
+    return undefined;
   }
   if (data === undefined) return {};
   return {
@@ -135,29 +169,33 @@ export async function invokePluginCallTool(
       action,
       payload,
     });
+    const project_root = resolve_project_root(getSessionRunContext()?.projectRoot);
     const raw_file_parts = result.success
       ? extract_assistant_file_parts(result.data)
       : [];
     const file_parts =
       raw_file_parts.length > 0
         ? await materializeAssistantFileParts({
-            projectRoot: getSessionRunContext()?.projectRoot,
+            projectRoot: project_root,
             parts: raw_file_parts,
           })
         : [];
+    const files = summarize_materialized_files(file_parts, project_root);
     if (file_parts.length > 0) {
       enqueueAssistantFileParts(file_parts);
     }
+    const data = summarize_action_data(result.data);
     return {
       success: result.success,
       plugin,
       action,
       assistant_file_count: file_parts.length,
+      ...(files.length > 0 ? { files } : {}),
       message:
         String(result.message || result.error || "").trim() ||
         (result.success ? "plugin action completed" : "plugin action failed"),
       ...(result.error ? { error: result.error } : {}),
-      data: summarize_action_data(result.data),
+      ...(data === undefined ? {} : { data }),
     };
   } catch (error) {
     return {
@@ -170,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,32 @@ export interface PluginCallInput {
   payload?: JsonObject;
 }
 
+/**
+ * plugin_read 输入。
+ */
+export interface PluginReadInput {
+  /** 要读取的 plugin 名称；不传则列出 plugin 概览。 */
+  plugin?: string;
+  /** 要读取的 action 名称；仅在 plugin 存在时生效。 */
+  action?: string;
+}
+
+/**
+ * plugin_call 产生的 assistant 文件摘要。
+ */
+export interface PluginCallToolFileResult {
+  /** 文件在本轮 assistant 文件列表中的顺序。 */
+  index: number;
+  /** 文件 MIME 类型，例如 `image/png`。 */
+  media_type: string;
+  /** 原始文件名；若上游未提供则为空字符串。 */
+  filename: string;
+  /** 持久化到历史消息中的资源 URL，通常为 `resources://.downcity/resources/...`。 */
+  url: string;
+  /** 当前机器可直接打开的绝对文件路径。 */
+  path: string;
+}
+
 /**
  * plugin_call 返回给模型的摘要结果。
  */
@@ -32,6 +58,8 @@ export interface PluginCallToolResult {
   action: string;
   /** 本次 action 产生并写入 assistant 消息的 file part 数量。 */
   assistant_file_count: number;
+  /** 本次 action 产生的文件摘要，包含可直接打开的绝对路径。 */
+  files?: PluginCallToolFileResult[];
   /** 人类可读消息。 */
   message: string;
   /** 错误信息。 */
@@ -39,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,
     });

package/src/plugin/core/PluginRegistry.ts

@@ -14,6 +14,8 @@ import type {
   PluginActionResult,
   AgentPlugins,
   PluginAvailability,
+  PluginActionReadView,
+  PluginReadView,
   PluginView,
 } from "@/plugin/types/Plugin.js";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
@@ -128,6 +130,60 @@ export class PluginRegistry implements AgentPlugins {
       .sort((a, b) => a.name.localeCompare(b.name));
   }
 
+  /**
+   * 读取 action metadata。
+   */
+  private readAction(
+    actionName: string,
+    action: NonNullable<Plugin["actions"]>[string],
+  ): PluginActionReadView {
+    return {
+      name: actionName,
+      description: String(action.description || "").trim(),
+      has_input_schema: Boolean(action.input_schema),
+      ...(action.input_schema?.json_schema
+        ? { input_schema: action.input_schema.json_schema }
+        : {}),
+      ...(action.examples ? { examples: action.examples } : {}),
+      allow_when_disabled: action.allowWhenDisabled === true,
+      has_command: Boolean(action.command),
+      has_api: Boolean(action.api),
+    };
+  }
+
+  /**
+   * 读取 plugin / action metadata。
+   */
+  read(params: {
+    plugin?: string;
+    action?: string;
+  }): PluginReadView | { plugins: PluginView[] } {
+    const pluginName = String(params.plugin || "").trim();
+    if (!pluginName) {
+      return { plugins: this.list() };
+    }
+    const plugin = this.get(pluginName);
+    if (!plugin) {
+      return {
+        name: pluginName,
+        title: pluginName,
+        description: "",
+        actions: [],
+      };
+    }
+    const actionName = String(params.action || "").trim();
+    const actions = Object.entries(plugin.actions || {})
+      .filter(([name]) => !actionName || name === actionName)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, action]) => this.readAction(name, action));
+    return {
+      name: plugin.name,
+      title: String(plugin.title || plugin.name || "").trim(),
+      description: String(plugin.description || "").trim(),
+      actions,
+    };
+  }
+
   /**
    * 检查 plugin 可用性。
    */
@@ -162,6 +218,28 @@ export class PluginRegistry implements AgentPlugins {
     };
   }
 
+  /**
+   * 按 action schema 校验 payload。
+   */
+  private parseActionPayload(params: {
+    pluginName: string;
+    actionName: string;
+    payload: JsonValue;
+    action: NonNullable<Plugin["actions"]>[string];
+  }): PluginActionResult<JsonValue> | { input: JsonValue } {
+    const schema = params.action.input_schema?.zod;
+    if (!schema) return { input: params.payload };
+    const parsed = schema.safeParse(params.payload);
+    if (parsed.success) {
+      return { input: parsed.data as JsonValue };
+    }
+    return {
+      success: false,
+      error: `Invalid payload for ${params.pluginName}.${params.actionName}: ${parsed.error.message}`,
+      message: `Invalid payload for ${params.pluginName}.${params.actionName}`,
+    };
+  }
+
   /**
    * 运行 plugin action。
    */
@@ -208,9 +286,19 @@ export class PluginRegistry implements AgentPlugins {
     }
 
     try {
+      const parsed_payload = this.parseActionPayload({
+        pluginName: plugin.name,
+        actionName,
+        payload: (params.payload ?? {}) as JsonValue,
+        action,
+      });
+      if (!("input" in parsed_payload)) {
+        return parsed_payload;
+      }
       return await action.execute({
         context,
-        payload: (params.payload ?? {}) as JsonValue,
+        payload: parsed_payload.input,
+        input: parsed_payload.input,
         pluginName: plugin.name,
         actionName,
       });

package/src/plugin/types/Plugin.ts

@@ -24,9 +24,12 @@ export type {
   PluginActionApi,
   PluginActionCommand,
   PluginActionCommandInput,
+  PluginActionExample,
   PluginActionInvokeParams,
   PluginActionInvokePort,
   PluginActionInvokeResult,
+  PluginActionInputSchema,
+  PluginActionMetadata,
   PluginActionResult,
   PluginActions,
 } from "@/types/plugin/PluginAction.js";
@@ -38,8 +41,10 @@ export type {
   PluginHooks,
   PluginPipelineHook,
   AgentPlugins,
+  PluginActionReadView,
   PluginResolveHook,
   PluginResolves,
+  PluginReadView,
   PluginView,
 } from "@/types/plugin/PluginRuntime.js";
 export type {