@downcity/agent 1.1.153 → 1.1.157

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

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 {

package/src/types/plugin/PluginAction.ts

@@ -8,8 +8,9 @@
 
 import type { Command } from "commander";
 import type { Context as HonoContext } from "hono";
+import type { z } from "zod";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { JsonValue } from "@/types/common/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /**
  * Plugin action 调用参数。
@@ -93,13 +94,51 @@ export interface PluginActionApi<P extends JsonValue = JsonValue> {
   mapInput?: (ctx: HonoContext) => P | Promise<P>;
 }
 
+/**
+ * Plugin Action 示例。
+ */
+export interface PluginActionExample<P extends JsonValue = JsonValue> {
+  /** 示例标题。 */
+  title: string;
+  /** 示例说明。 */
+  description?: string;
+  /** 示例 payload。 */
+  payload: P;
+}
+
+/**
+ * Plugin Action 输入 schema。
+ *
+ * 关键点（中文）
+ * - 优先支持 Zod，运行时用 safeParse 做校验。
+ * - `json_schema` 用于给模型或 UI 读取；没有时仍可依赖 description/examples。
+ */
+export interface PluginActionInputSchema<P extends JsonValue = JsonValue> {
+  /** Zod schema，负责运行时校验与 TypeScript 推导。 */
+  zod?: z.ZodTypeAny;
+  /** 面向模型和 UI 的 JSON Schema 描述。 */
+  json_schema?: JsonObject;
+}
+
+/**
+ * Plugin Action 元数据。
+ */
+export interface PluginActionMetadata<P extends JsonValue = JsonValue> {
+  /** Action 用途说明。 */
+  description?: string;
+  /** Action 输入 schema。 */
+  input_schema?: PluginActionInputSchema<P>;
+  /** Action 调用示例。 */
+  examples?: PluginActionExample<P>[];
+}
+
 /**
  * Plugin Action 定义。
  */
 export interface PluginAction<
   P extends JsonValue = JsonValue,
   R extends JsonValue = JsonValue,
-> {
+> extends PluginActionMetadata<P> {
   /**
    * disabled 状态下是否仍允许执行。
    *
@@ -118,6 +157,8 @@ export interface PluginAction<
     context: AgentContext;
     /** 输入 payload。 */
     payload: P;
+    /** 已通过 schema 校验后的输入。 */
+    input: P;
     /** 当前插件名称。 */
     pluginName: string;
     /** 当前 Action 名称。 */

package/src/types/plugin/PluginRuntime.ts

@@ -12,6 +12,7 @@ import type {
 } from "@/types/runtime/agent/AgentContext.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
+import type { PluginActionExample } from "@/types/plugin/PluginAction.js";
 
 /**
  * Plugin 概览视图。
@@ -39,6 +40,42 @@ export interface PluginView {
   hasAvailability: boolean;
 }
 
+/**
+ * Plugin Action 读取视图。
+ */
+export interface PluginActionReadView {
+  /** Action 名称。 */
+  name: string;
+  /** Action 用途说明。 */
+  description: string;
+  /** 是否声明输入 schema。 */
+  has_input_schema: boolean;
+  /** JSON Schema 形式的输入说明。 */
+  input_schema?: JsonValue;
+  /** Action 调用示例。 */
+  examples?: PluginActionExample[];
+  /** disabled 状态下是否仍允许执行。 */
+  allow_when_disabled: boolean;
+  /** 是否声明 CLI command。 */
+  has_command: boolean;
+  /** 是否声明 HTTP API。 */
+  has_api: boolean;
+}
+
+/**
+ * Plugin 读取视图。
+ */
+export interface PluginReadView {
+  /** Plugin 稳定名称。 */
+  name: string;
+  /** Plugin 展示标题。 */
+  title: string;
+  /** Plugin 用途说明。 */
+  description: string;
+  /** Action 列表或指定 action。 */
+  actions: PluginActionReadView[];
+}
+
 /**
  * Plugin 可用性结果。
  */
@@ -57,6 +94,13 @@ export interface PluginAvailability {
 export interface AgentPlugins {
   /** 列出全部已注册 plugin。 */
   list(): PluginView[];
+  /** 读取 plugin / action metadata。 */
+  read(params: {
+    /** Plugin 名称。 */
+    plugin?: string;
+    /** Action 名称。 */
+    action?: string;
+  }): PluginReadView | { plugins: PluginView[] };
   /** 检查指定 plugin 可用性。 */
   availability(pluginName: string): Promise<PluginAvailability>;
   /** 运行指定 plugin action。 */