@lark-apaas/nestjs-capability 0.1.3 → 0.1.4-alpha.0

package/dist/index.d.ts

@@ -178,7 +178,7 @@ interface PluginInstance {
     aggregate?(actionName: string, chunks: unknown[]): unknown;
 }
 interface PluginPackage {
-    create(): PluginInstance;
+    create(config?: unknown): PluginInstance;
 }
 
 /**
@@ -258,6 +258,14 @@ declare class TemplateEngineService {
     private getDefaultValueFromSchema;
 }
 
+interface PluginManifest {
+    name: string;
+    form?: {
+        refType?: 'config' | 'action';
+        schema?: unknown;
+    };
+    [key: string]: unknown;
+}
 declare class PluginNotFoundError extends Error {
     readonly pluginKey: string;
     constructor(pluginKey: string);
@@ -270,11 +278,30 @@ declare class PluginLoaderService {
     private readonly pluginInstances;
     /** 记录每个插件的加载版本（时间戳），用于 ESM 缓存绕过 */
     private readonly pluginVersions;
-    loadPlugin(pluginKey: string): Promise<PluginInstance>;
+    /** 缓存插件的 manifest.json */
+    private readonly manifestCache;
+    /**
+     * 从入口路径向上查找包根目录（包含 package.json 的目录）
+     */
+    private findPackageRoot;
+    /**
+     * 读取并缓存 manifest
+     */
+    getManifest(pluginKey: string): PluginManifest | null;
+    /**
+     * 检查插件是否需要 config（form.refType === 'config'）
+     */
+    isConfigRequired(pluginKey: string): boolean;
+    loadPlugin(pluginKey: string, config?: unknown): Promise<PluginInstance>;
+    /**
+     * 创建插件实例（内部方法）
+     */
+    private createPluginInstance;
     isPluginInstalled(pluginKey: string): boolean;
     /**
      * 清除插件缓存
      * - 清除应用层 pluginInstances 缓存
+     * - 清除 manifest 缓存
      * - 清除 Node.js CJS 模块缓存（require.cache）
      * - 更新版本号，下次 import 时绕过 ESM 缓存
      * @param pluginKey - 插件标识，不传则清除所有
@@ -394,6 +421,11 @@ declare class CapabilityService implements OnModuleInit, OnModuleDestroy {
      */
     loadWithConfig(config: CapabilityConfig): CapabilityExecutor;
     private createExecutor;
+    /**
+     * 加载插件实例并解析参数
+     * 根据 manifest 的 form.refType 决定 formValue 的消费方式
+     */
+    private loadPluginAndResolveParams;
     /**
      * 检查 action 是否为流式
      */
@@ -535,4 +567,4 @@ interface MigrationResponse {
  */
 declare function migrationAdaptor(promise: Promise<unknown>): Promise<MigrationResponse>;
 
-export { ActionNotFoundError, type ActionSchema, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, PluginNotFoundError, type PluginPackage, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };
+export { ActionNotFoundError, type ActionSchema, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, type PluginManifest, PluginNotFoundError, type PluginPackage, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };

package/dist/index.js

@@ -65,13 +65,13 @@ var TemplateEngineService = class {
   resolveString(template, input, paramsSchema) {
     const wholeMatch = template.match(this.WHOLE_STRING_EXPR_REGEX);
     if (wholeMatch) {
-      const path2 = wholeMatch[1];
-      const value = this.getValueByPath(input, path2);
+      const path3 = wholeMatch[1];
+      const value = this.getValueByPath(input, path3);
       if (value !== void 0) {
         return value;
       }
       if (paramsSchema) {
-        const defaultValue = this.getDefaultValueForPath(path2, paramsSchema);
+        const defaultValue = this.getDefaultValueForPath(path3, paramsSchema);
         if (defaultValue !== void 0) {
           return defaultValue;
         }
@@ -83,8 +83,8 @@ var TemplateEngineService = class {
       return template;
     }
     this.EXPR_REGEX.lastIndex = 0;
-    const result = template.replace(this.EXPR_REGEX, (match, path2) => {
-      const value = this.getValueByPath(input, path2);
+    const result = template.replace(this.EXPR_REGEX, (match, path3) => {
+      const value = this.getValueByPath(input, path3);
       if (value === void 0) {
         return match;
       }
@@ -99,8 +99,8 @@ var TemplateEngineService = class {
     }
     return result;
   }
-  getValueByPath(obj, path2) {
-    const keys = path2.split(".");
+  getValueByPath(obj, path3) {
+    const keys = path3.split(".");
     let current = obj;
     for (const key of keys) {
       if (current === null || current === void 0) {
@@ -116,8 +116,8 @@ var TemplateEngineService = class {
   * @param schema - JSON Schema
   * @returns 默认值，如果无法确定则返回 undefined
   */
-  getDefaultValueForPath(path2, schema) {
-    const fieldSchema = this.getSchemaForPath(path2, schema);
+  getDefaultValueForPath(path3, schema) {
+    const fieldSchema = this.getSchemaForPath(path3, schema);
     if (!fieldSchema) {
       return void 0;
     }
@@ -129,8 +129,8 @@ var TemplateEngineService = class {
   * @param schema - 根 JSON Schema
   * @returns 路径对应的 schema，如果不存在则返回 undefined
   */
-  getSchemaForPath(path2, schema) {
-    const keys = path2.split(".");
+  getSchemaForPath(path3, schema) {
+    const keys = path3.split(".");
     let currentSchema = schema;
     for (const key of keys) {
       if (!currentSchema?.properties) {
@@ -179,6 +179,8 @@ TemplateEngineService = _ts_decorate([
 import { Injectable as Injectable2, Logger } from "@nestjs/common";
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
+import * as fs from "fs";
+import * as path from "path";
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -215,13 +217,75 @@ var PluginLoaderService = class _PluginLoaderService {
   pluginInstances = /* @__PURE__ */ new Map();
   /** 记录每个插件的加载版本（时间戳），用于 ESM 缓存绕过 */
   pluginVersions = /* @__PURE__ */ new Map();
-  async loadPlugin(pluginKey) {
+  /** 缓存插件的 manifest.json */
+  manifestCache = /* @__PURE__ */ new Map();
+  /**
+  * 从入口路径向上查找包根目录（包含 package.json 的目录）
+  */
+  findPackageRoot(entryPath) {
+    let dir = path.dirname(entryPath);
+    while (dir !== path.dirname(dir)) {
+      if (fs.existsSync(path.join(dir, "package.json"))) {
+        return dir;
+      }
+      dir = path.dirname(dir);
+    }
+    return null;
+  }
+  /**
+  * 读取并缓存 manifest
+  */
+  getManifest(pluginKey) {
+    if (this.manifestCache.has(pluginKey)) {
+      return this.manifestCache.get(pluginKey) ?? null;
+    }
+    try {
+      const entryPath = require2.resolve(pluginKey);
+      const packageRoot = this.findPackageRoot(entryPath);
+      if (!packageRoot) {
+        this.manifestCache.set(pluginKey, null);
+        return null;
+      }
+      const manifestPath = path.join(packageRoot, "manifest.json");
+      if (!fs.existsSync(manifestPath)) {
+        this.manifestCache.set(pluginKey, null);
+        return null;
+      }
+      const content = fs.readFileSync(manifestPath, "utf-8");
+      const manifest = JSON.parse(content);
+      this.manifestCache.set(pluginKey, manifest);
+      return manifest;
+    } catch {
+      this.manifestCache.set(pluginKey, null);
+      return null;
+    }
+  }
+  /**
+  * 检查插件是否需要 config（form.refType === 'config'）
+  */
+  isConfigRequired(pluginKey) {
+    const manifest = this.getManifest(pluginKey);
+    return manifest?.form?.refType === "config";
+  }
+  async loadPlugin(pluginKey, config) {
+    const isConfigRequired = this.isConfigRequired(pluginKey);
+    if (isConfigRequired) {
+      return this.createPluginInstance(pluginKey, config);
+    }
     const cached = this.pluginInstances.get(pluginKey);
     if (cached) {
       this.logger.debug(`Using cached plugin instance: ${pluginKey}`);
       return cached;
     }
-    this.logger.log(`Loading plugin: ${pluginKey}`);
+    const instance = await this.createPluginInstance(pluginKey);
+    this.pluginInstances.set(pluginKey, instance);
+    return instance;
+  }
+  /**
+  * 创建插件实例（内部方法）
+  */
+  async createPluginInstance(pluginKey, config) {
+    this.logger.log(`Loading plugin: ${pluginKey}${config !== void 0 ? " (with config)" : ""}`);
     try {
       const resolvedPath = require2.resolve(pluginKey);
       const version = this.pluginVersions.get(pluginKey) ?? 0;
@@ -232,8 +296,7 @@ var PluginLoaderService = class _PluginLoaderService {
       if (typeof pluginPackage.create !== "function") {
         throw new PluginLoadError(pluginKey, "Plugin does not export create() function");
       }
-      const instance = pluginPackage.create();
-      this.pluginInstances.set(pluginKey, instance);
+      const instance = pluginPackage.create(config);
       this.logger.log(`Plugin loaded successfully: ${pluginKey}`);
       return instance;
     } catch (error) {
@@ -254,6 +317,7 @@ var PluginLoaderService = class _PluginLoaderService {
   /**
   * 清除插件缓存
   * - 清除应用层 pluginInstances 缓存
+  * - 清除 manifest 缓存
   * - 清除 Node.js CJS 模块缓存（require.cache）
   * - 更新版本号，下次 import 时绕过 ESM 缓存
   * @param pluginKey - 插件标识，不传则清除所有
@@ -261,6 +325,7 @@ var PluginLoaderService = class _PluginLoaderService {
   clearCache(pluginKey) {
     if (pluginKey) {
       this.pluginInstances.delete(pluginKey);
+      this.manifestCache.delete(pluginKey);
       this.clearNodeModuleCache(pluginKey);
       this.pluginVersions.set(pluginKey, Date.now());
       this.logger.log(`Cleared cache for plugin: ${pluginKey}`);
@@ -270,6 +335,7 @@ var PluginLoaderService = class _PluginLoaderService {
         this.pluginVersions.set(key, Date.now());
       }
       this.pluginInstances.clear();
+      this.manifestCache.clear();
       this.logger.log("Cleared all plugin caches");
     }
   }
@@ -315,8 +381,8 @@ PluginLoaderService = _ts_decorate2([
 // src/services/capability.service.ts
 import { Injectable as Injectable3, Logger as Logger2, Inject } from "@nestjs/common";
 import { RequestContextService, PLATFORM_HTTP_CLIENT } from "@lark-apaas/nestjs-common";
-import * as fs from "fs";
-import * as path from "path";
+import * as fs2 from "fs";
+import * as path2 from "path";
 import * as chokidar from "chokidar";
 
 // src/utils/log-utils.ts
@@ -439,7 +505,7 @@ var CapabilityService = class _CapabilityService {
     this.pluginLoaderService = pluginLoaderService;
     this.templateEngineService = templateEngineService;
     const isDev = process.env.NODE_ENV === "development";
-    this.capabilitiesDir = path.join(process.cwd(), isDev ? "server/capabilities" : "capabilities");
+    this.capabilitiesDir = path2.join(process.cwd(), isDev ? "server/capabilities" : "capabilities");
   }
   /**
   * 设置模块配置
@@ -470,11 +536,11 @@ var CapabilityService = class _CapabilityService {
     if (this.fileWatcher) {
       return;
     }
-    if (!fs.existsSync(this.capabilitiesDir)) {
+    if (!fs2.existsSync(this.capabilitiesDir)) {
       this.logger.warn(`Cannot start watching: directory not found: ${this.capabilitiesDir}`);
       return;
     }
-    const pattern = path.join(this.capabilitiesDir, "*.json");
+    const pattern = path2.join(this.capabilitiesDir, "*.json");
     const debounce = this.options.watchDebounce ?? 300;
     this.logger.log(`Starting file watcher: ${pattern}`);
     this.fileWatcher = chokidar.watch(pattern, {
@@ -539,7 +605,7 @@ var CapabilityService = class _CapabilityService {
   * 从文件加载单个能力配置
   */
   loadCapabilityFromFile(filePath) {
-    const content = fs.readFileSync(filePath, "utf-8");
+    const content = fs2.readFileSync(filePath, "utf-8");
     const config = JSON.parse(content);
     if (!config.id) {
       this.logger.warn(`Skipping capability without id: ${filePath}`);
@@ -577,14 +643,14 @@ var CapabilityService = class _CapabilityService {
   // ==================== 原有方法 ====================
   async loadCapabilities() {
     this.logger.log(`Loading capabilities from ${this.capabilitiesDir}`);
-    if (!fs.existsSync(this.capabilitiesDir)) {
+    if (!fs2.existsSync(this.capabilitiesDir)) {
       this.logger.warn(`Capabilities directory not found: ${this.capabilitiesDir}`);
       return;
     }
-    const files = fs.readdirSync(this.capabilitiesDir).filter((f) => f.endsWith(".json"));
+    const files = fs2.readdirSync(this.capabilitiesDir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
       try {
-        const filePath = path.join(this.capabilitiesDir, file);
+        const filePath = path2.join(this.capabilitiesDir, file);
         this.loadCapabilityFromFile(filePath);
       } catch (error) {
         this.logger.error(`Failed to load capability from ${file}:`, error);
@@ -629,10 +695,30 @@ var CapabilityService = class _CapabilityService {
     };
   }
   /**
+  * 加载插件实例并解析参数
+  * 根据 manifest 的 form.refType 决定 formValue 的消费方式
+  */
+  async loadPluginAndResolveParams(config, input) {
+    const isConfigRequired = this.pluginLoaderService.isConfigRequired(config.pluginKey);
+    if (isConfigRequired) {
+      const pluginInstance2 = await this.pluginLoaderService.loadPlugin(config.pluginKey, config.formValue);
+      return {
+        pluginInstance: pluginInstance2,
+        resolvedParams: input
+      };
+    }
+    const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+    const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input, config.paramsSchema) : input;
+    return {
+      pluginInstance,
+      resolvedParams
+    };
+  }
+  /**
   * 检查 action 是否为流式
   */
   async checkIsStream(config, actionName) {
-    const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+    const { pluginInstance } = await this.loadPluginAndResolveParams(config, {});
     if (!pluginInstance.hasAction(actionName)) {
       throw new ActionNotFoundError(config.pluginKey, actionName);
     }
@@ -651,11 +737,10 @@ var CapabilityService = class _CapabilityService {
       action: actionName
     };
     try {
-      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+      const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
       }
-      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input, config.paramsSchema) : input;
       const context = this.buildActionContext(contextOverride);
       const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
       this.logger.log("Executing capability (call)", {
@@ -702,11 +787,10 @@ var CapabilityService = class _CapabilityService {
     };
     const chunks = [];
     try {
-      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+      const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
       }
-      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input, config.paramsSchema) : input;
       const context = this.buildActionContext(contextOverride);
       const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
       this.logger.log("Executing capability (stream)", {
@@ -753,11 +837,10 @@ var CapabilityService = class _CapabilityService {
     };
     const chunks = [];
     try {
-      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+      const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
       }
-      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input, config.paramsSchema) : input;
       const context = this.buildActionContext(contextOverride);
       const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
       this.logger.log("Executing capability (streamWithEvents)", {
@@ -933,11 +1016,12 @@ var DebugController = class _DebugController {
   * 获取 action 名称
   * 优先使用传入的 action，否则使用插件第一个 action
   */
-  async getActionName(pluginKey, bodyAction) {
+  async getActionName(pluginKey, formValue, bodyAction) {
     if (bodyAction) {
       return bodyAction;
     }
-    const pluginInstance = await this.pluginLoaderService.loadPlugin(pluginKey);
+    const isConfigRequired = this.pluginLoaderService.isConfigRequired(pluginKey);
+    const pluginInstance = isConfigRequired ? await this.pluginLoaderService.loadPlugin(pluginKey, formValue) : await this.pluginLoaderService.loadPlugin(pluginKey);
     const actions = pluginInstance.listActions();
     if (actions.length === 0) {
       throw new Error(`Plugin ${pluginKey} has no actions`);
@@ -949,7 +1033,7 @@ var DebugController = class _DebugController {
     const params = body.params ?? {};
     try {
       const config = this.getCapabilityConfig(capabilityId, body.capability);
-      const action = await this.getActionName(config.pluginKey, body.action);
+      const action = await this.getActionName(config.pluginKey, config.formValue, body.action);
       const resolvedParams = this.templateEngineService.resolve(config.formValue, params, config.paramsSchema);
       const result = await this.capabilityService.loadWithConfig(config).call(action, params, {
         isDebug: true
@@ -1006,7 +1090,7 @@ var DebugController = class _DebugController {
     res.setHeader("Connection", "keep-alive");
     try {
       const config = this.getCapabilityConfig(capabilityId, body.capability);
-      const action = await this.getActionName(config.pluginKey, body.action);
+      const action = await this.getActionName(config.pluginKey, config.formValue, body.action);
       const loggerContext = {
         capability_id: config.id,
         plugin_key: config.pluginKey,