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

package/README.md

@@ -310,15 +310,53 @@ interface CapabilityExecutor {
 
 ```typescript
 interface PluginLoaderService {
-  // 加载插件并创建实例（带缓存）
-  loadPlugin(pluginID: string): PluginInstance;
+  // 加载插件并创建实例
+  // - 对于 refType: "config" 的插件，每次调用都创建新实例
+  // - 对于 refType: "action" 的插件，使用缓存
+  loadPlugin(pluginID: string, config?: unknown): PluginInstance;
 
   // 检查插件是否已安装
   isPluginInstalled(pluginID: string): boolean;
 
-  // 清除插件缓存
+  // 读取插件的 manifest.json
+  getManifest(pluginID: string): PluginManifest | null;
+
+  // 检查插件是否需要 config（form.refType === 'config'）
+  isConfigRequired(pluginID: string): boolean;
+
+  // 清除插件缓存（包括 manifest 缓存）
   clearCache(pluginID?: string): void;
 }
+
+interface PluginManifest {
+  name: string;
+  form?: {
+    refType?: 'config' | 'action';
+    schema?: unknown;
+  };
+  [key: string]: unknown;
+}
+```
+
+#### form.refType 说明
+
+插件的 `manifest.json` 中可以通过 `form.refType` 字段指定 `formValue` 的消费方式：
+
+| refType | 行为 | 缓存策略 |
+|---------|------|----------|
+| `"config"` | `formValue` 作为 config 传给 `create()` 函数 | 不缓存实例，每次重新创建 |
+| `"action"` 或不设置 | `formValue` 通过模板引擎解析后作为 action 参数 | 缓存实例 |
+
+**manifest.json 示例：**
+
+```json
+{
+  "name": "@test/feishu-bitable",
+  "form": {
+    "refType": "config",
+    "schema": { ... }
+  }
+}
 ```
 
 ### TemplateEngineService

package/dist/index.cjs

@@ -114,13 +114,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;
         }
@@ -132,8 +132,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;
       }
@@ -148,8 +148,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) {
@@ -165,8 +165,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;
     }
@@ -178,8 +178,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) {
@@ -228,6 +228,8 @@ TemplateEngineService = _ts_decorate([
 var import_common2 = require("@nestjs/common");
 var import_node_module = require("module");
 var import_node_url = require("url");
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
 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);
@@ -264,13 +266,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;
@@ -281,8 +345,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) {
@@ -303,6 +366,7 @@ var PluginLoaderService = class _PluginLoaderService {
   /**
   * 清除插件缓存
   * - 清除应用层 pluginInstances 缓存
+  * - 清除 manifest 缓存
   * - 清除 Node.js CJS 模块缓存（require.cache）
   * - 更新版本号，下次 import 时绕过 ESM 缓存
   * @param pluginKey - 插件标识，不传则清除所有
@@ -310,6 +374,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}`);
@@ -319,6 +384,7 @@ var PluginLoaderService = class _PluginLoaderService {
         this.pluginVersions.set(key, Date.now());
       }
       this.pluginInstances.clear();
+      this.manifestCache.clear();
       this.logger.log("Cleared all plugin caches");
     }
   }
@@ -364,8 +430,8 @@ PluginLoaderService = _ts_decorate2([
 // src/services/capability.service.ts
 var import_common3 = require("@nestjs/common");
 var import_nestjs_common = require("@lark-apaas/nestjs-common");
-var fs = __toESM(require("fs"), 1);
-var path = __toESM(require("path"), 1);
+var fs2 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
 var chokidar = __toESM(require("chokidar"), 1);
 
 // src/utils/log-utils.ts
@@ -488,7 +554,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");
   }
   /**
   * 设置模块配置
@@ -519,11 +585,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, {
@@ -588,7 +654,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}`);
@@ -626,14 +692,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);
@@ -678,10 +744,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);
     }
@@ -700,11 +786,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)", {
@@ -751,11 +836,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)", {
@@ -802,11 +886,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)", {
@@ -982,11 +1065,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`);
@@ -998,7 +1082,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
@@ -1055,7 +1139,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,