@downcity/agent 1.1.152 → 1.1.157

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。 */