@lark-apaas/nestjs-capability 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/index.js

@@ -1,11 +1,21 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
+
+// src/interfaces/error-codes.ts
+var ErrorCodes = {
+  /** 成功 */
+  SUCCESS: "0",
+  /** 能力不存在 */
+  CAPABILITY_NOT_FOUND: "k_ec_cap_001",
+  /** 插件不存在 */
+  PLUGIN_NOT_FOUND: "k_ec_cap_002",
+  /** Action 不存在 */
+  ACTION_NOT_FOUND: "k_ec_cap_003",
+  /** 参数验证失败 */
+  PARAMS_VALIDATION_ERROR: "k_ec_cap_004",
+  /** 执行失败 */
+  EXECUTION_ERROR: "k_ec_cap_005"
+};
 
 // src/services/template-engine.service.ts
 import { Injectable } from "@nestjs/common";
@@ -20,7 +30,10 @@ var TemplateEngineService = class {
   static {
     __name(this, "TemplateEngineService");
   }
-  TEMPLATE_REGEX = /^\{\{input\.(.+)\}\}$/;
+  // 匹配 {{input.xxx}} 或 {{input.xxx.yyy}} 表达式
+  EXPR_REGEX = /\{\{input\.([a-zA-Z_][a-zA-Z_0-9]*(?:\.[a-zA-Z_][a-zA-Z_0-9]*)*)\}\}/g;
+  // 匹配整串单个表达式
+  WHOLE_STRING_EXPR_REGEX = /^\{\{input\.([a-zA-Z_][a-zA-Z_0-9]*(?:\.[a-zA-Z_][a-zA-Z_0-9]*)*)\}\}$/;
   resolve(template, input) {
     if (typeof template === "string") {
       return this.resolveString(template, input);
@@ -34,12 +47,25 @@ var TemplateEngineService = class {
     return template;
   }
   resolveString(template, input) {
-    const match = template.match(this.TEMPLATE_REGEX);
-    if (!match) {
+    const wholeMatch = template.match(this.WHOLE_STRING_EXPR_REGEX);
+    if (wholeMatch) {
+      const path2 = wholeMatch[1];
+      const value = this.getValueByPath(input, path2);
+      return value !== void 0 ? value : template;
+    }
+    this.EXPR_REGEX.lastIndex = 0;
+    if (!this.EXPR_REGEX.test(template)) {
       return template;
     }
-    const path2 = match[1];
-    return this.getValueByPath(input, path2);
+    this.EXPR_REGEX.lastIndex = 0;
+    const result = template.replace(this.EXPR_REGEX, (match, path2) => {
+      const value = this.getValueByPath(input, path2);
+      if (value === void 0) {
+        return match;
+      }
+      return String(value);
+    });
+    return result;
   }
   resolveObject(template, input) {
     const result = {};
@@ -66,6 +92,8 @@ TemplateEngineService = _ts_decorate([
 
 // src/services/plugin-loader.service.ts
 import { Injectable as Injectable2, Logger } from "@nestjs/common";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
 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);
@@ -73,12 +101,13 @@ function _ts_decorate2(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate2, "_ts_decorate");
+var require2 = createRequire(import.meta.url);
 var PluginNotFoundError = class extends Error {
   static {
     __name(this, "PluginNotFoundError");
   }
-  constructor(pluginID) {
-    super(`Plugin not found: ${pluginID}`);
+  constructor(pluginKey) {
+    super(`Plugin not found: ${pluginKey}`);
     this.name = "PluginNotFoundError";
   }
 };
@@ -86,8 +115,8 @@ var PluginLoadError = class extends Error {
   static {
     __name(this, "PluginLoadError");
   }
-  constructor(pluginID, reason) {
-    super(`Failed to load plugin ${pluginID}: ${reason}`);
+  constructor(pluginKey, reason) {
+    super(`Failed to load plugin ${pluginKey}: ${reason}`);
     this.name = "PluginLoadError";
   }
 };
@@ -97,46 +126,100 @@ var PluginLoaderService = class _PluginLoaderService {
   }
   logger = new Logger(_PluginLoaderService.name);
   pluginInstances = /* @__PURE__ */ new Map();
-  async loadPlugin(pluginID) {
-    const cached = this.pluginInstances.get(pluginID);
+  /** 记录每个插件的加载版本（时间戳），用于 ESM 缓存绕过 */
+  pluginVersions = /* @__PURE__ */ new Map();
+  async loadPlugin(pluginKey) {
+    const cached = this.pluginInstances.get(pluginKey);
     if (cached) {
-      this.logger.debug(`Using cached plugin instance: ${pluginID}`);
+      this.logger.debug(`Using cached plugin instance: ${pluginKey}`);
       return cached;
     }
-    this.logger.log(`Loading plugin: ${pluginID}`);
+    this.logger.log(`Loading plugin: ${pluginKey}`);
     try {
-      const pluginPackage = (await import(pluginID)).default;
+      const resolvedPath = require2.resolve(pluginKey);
+      const version = this.pluginVersions.get(pluginKey) ?? 0;
+      const fileUrl = pathToFileURL(resolvedPath).href;
+      const importPath = version > 0 ? `${fileUrl}?v=${version}` : fileUrl;
+      const mod = await import(importPath);
+      const pluginPackage = mod.default ?? mod;
       if (typeof pluginPackage.create !== "function") {
-        throw new PluginLoadError(pluginID, "Plugin does not export create() function");
+        throw new PluginLoadError(pluginKey, "Plugin does not export create() function");
       }
       const instance = pluginPackage.create();
-      this.pluginInstances.set(pluginID, instance);
-      this.logger.log(`Plugin loaded successfully: ${pluginID}`);
+      this.pluginInstances.set(pluginKey, instance);
+      this.logger.log(`Plugin loaded successfully: ${pluginKey}`);
       return instance;
     } catch (error) {
       if (error.code === "MODULE_NOT_FOUND") {
-        throw new PluginNotFoundError(pluginID);
+        throw new PluginNotFoundError(pluginKey);
       }
-      throw new PluginLoadError(pluginID, error instanceof Error ? error.message : String(error));
+      throw new PluginLoadError(pluginKey, error instanceof Error ? error.message : String(error));
     }
   }
-  isPluginInstalled(pluginID) {
+  isPluginInstalled(pluginKey) {
     try {
-      __require.resolve(pluginID);
+      require2.resolve(pluginKey);
       return true;
     } catch {
       return false;
     }
   }
-  clearCache(pluginID) {
-    if (pluginID) {
-      this.pluginInstances.delete(pluginID);
-      this.logger.log(`Cleared cache for plugin: ${pluginID}`);
+  /**
+  * 清除插件缓存
+  * - 清除应用层 pluginInstances 缓存
+  * - 清除 Node.js CJS 模块缓存（require.cache）
+  * - 更新版本号，下次 import 时绕过 ESM 缓存
+  * @param pluginKey - 插件标识，不传则清除所有
+  */
+  clearCache(pluginKey) {
+    if (pluginKey) {
+      this.pluginInstances.delete(pluginKey);
+      this.clearNodeModuleCache(pluginKey);
+      this.pluginVersions.set(pluginKey, Date.now());
+      this.logger.log(`Cleared cache for plugin: ${pluginKey}`);
     } else {
+      for (const key of this.pluginInstances.keys()) {
+        this.clearNodeModuleCache(key);
+        this.pluginVersions.set(key, Date.now());
+      }
       this.pluginInstances.clear();
       this.logger.log("Cleared all plugin caches");
     }
   }
+  /**
+  * 清除 CJS 模块缓存
+  */
+  clearNodeModuleCache(pluginKey) {
+    try {
+      const resolvedPath = require2.resolve(pluginKey);
+      const mod = require2.cache[resolvedPath];
+      if (mod) {
+        this.clearModuleAndChildren(mod, pluginKey);
+      }
+      delete require2.cache[resolvedPath];
+    } catch {
+    }
+  }
+  /**
+  * 递归清除子模块缓存
+  */
+  clearModuleAndChildren(mod, pluginKey) {
+    const pluginScope = pluginKey.startsWith("@") ? pluginKey.split("/").slice(0, 2).join("/") : pluginKey;
+    mod.children.forEach((child) => {
+      if (child.filename.includes(`node_modules/${pluginScope}`)) {
+        this.clearModuleAndChildren(child, pluginKey);
+        delete require2.cache[child.filename];
+      }
+    });
+  }
+  /**
+  * 强制重新加载插件
+  * @param pluginKey - 插件标识
+  */
+  async reloadPlugin(pluginKey) {
+    this.clearCache(pluginKey);
+    return this.loadPlugin(pluginKey);
+  }
 };
 PluginLoaderService = _ts_decorate2([
   Injectable2()
@@ -147,6 +230,29 @@ import { Injectable as Injectable3, Logger as Logger2, Inject } from "@nestjs/co
 import { RequestContextService, PLATFORM_HTTP_CLIENT } from "@lark-apaas/nestjs-common";
 import * as fs from "fs";
 import * as path from "path";
+import * as chokidar from "chokidar";
+
+// src/utils/log-utils.ts
+var DEFAULT_MAX_LENGTH = 1e3;
+function truncateString(str, maxLength) {
+  if (str.length <= maxLength) {
+    return str;
+  }
+  return str.slice(0, maxLength) + `... [truncated, total ${str.length} chars]`;
+}
+__name(truncateString, "truncateString");
+function stringifyForLog(value, maxLength = DEFAULT_MAX_LENGTH) {
+  try {
+    const str = JSON.stringify(value, null, 2);
+    return truncateString(str, maxLength);
+  } catch {
+    const str = String(value);
+    return truncateString(str, maxLength);
+  }
+}
+__name(stringifyForLog, "stringifyForLog");
+
+// src/services/capability.service.ts
 function _ts_decorate3(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);
@@ -177,8 +283,8 @@ var ActionNotFoundError = class extends Error {
   static {
     __name(this, "ActionNotFoundError");
   }
-  constructor(pluginID, actionName) {
-    super(`Action '${actionName}' not found in plugin ${pluginID}`);
+  constructor(pluginKey, actionName) {
+    super(`Action '${actionName}' not found in plugin ${pluginKey}`);
     this.name = "ActionNotFoundError";
   }
 };
@@ -187,25 +293,150 @@ var CapabilityService = class _CapabilityService {
     __name(this, "CapabilityService");
   }
   requestContextService;
-  httpClient;
+  platformHttpClient;
   pluginLoaderService;
   templateEngineService;
   logger = new Logger2(_CapabilityService.name);
   capabilities = /* @__PURE__ */ new Map();
+  /** 文件路径到 capability id 的映射，用于文件删除时查找 */
+  filePathToId = /* @__PURE__ */ new Map();
   capabilitiesDir;
-  constructor(requestContextService, httpClient, pluginLoaderService, templateEngineService) {
+  fileWatcher = null;
+  options = {};
+  constructor(requestContextService, platformHttpClient, pluginLoaderService, templateEngineService) {
     this.requestContextService = requestContextService;
-    this.httpClient = httpClient;
+    this.platformHttpClient = platformHttpClient;
     this.pluginLoaderService = pluginLoaderService;
     this.templateEngineService = templateEngineService;
-    this.capabilitiesDir = path.join(process.cwd(), "server/capabilities");
+    const isDev = process.env.NODE_ENV === "development";
+    this.capabilitiesDir = path.join(process.cwd(), isDev ? "server/capabilities" : "capabilities");
+  }
+  /**
+  * 设置模块配置
+  */
+  setOptions(options) {
+    this.options = options;
+    if (options.capabilitiesDir) {
+      this.capabilitiesDir = options.capabilitiesDir;
+    }
   }
   setCapabilitiesDir(dir) {
     this.capabilitiesDir = dir;
   }
   async onModuleInit() {
     await this.loadCapabilities();
+    if (this.options.enableWatching) {
+      this.startWatching();
+    }
+  }
+  async onModuleDestroy() {
+    this.stopWatching();
+  }
+  // ==================== 文件监听相关方法 ====================
+  /**
+  * 启动文件监听（沙箱环境自动调用）
+  */
+  startWatching() {
+    if (this.fileWatcher) {
+      return;
+    }
+    if (!fs.existsSync(this.capabilitiesDir)) {
+      this.logger.warn(`Cannot start watching: directory not found: ${this.capabilitiesDir}`);
+      return;
+    }
+    const pattern = path.join(this.capabilitiesDir, "*.json");
+    const debounce = this.options.watchDebounce ?? 300;
+    this.logger.log(`Starting file watcher: ${pattern}`);
+    this.fileWatcher = chokidar.watch(pattern, {
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        // 等待写入完成
+        stabilityThreshold: debounce,
+        pollInterval: 100
+      }
+    });
+    this.fileWatcher.on("add", (filePath) => this.handleFileAdd(filePath)).on("change", (filePath) => this.handleFileChange(filePath)).on("unlink", (filePath) => this.handleFileUnlink(filePath)).on("error", (error) => this.logger.error("File watcher error:", error));
+    this.logger.log("File watcher started");
+  }
+  /**
+  * 停止文件监听
+  */
+  stopWatching() {
+    if (this.fileWatcher) {
+      this.fileWatcher.close();
+      this.fileWatcher = null;
+      this.logger.log("File watcher stopped");
+    }
+  }
+  /**
+  * 重新加载所有能力配置
+  */
+  async reloadAllCapabilities() {
+    this.capabilities.clear();
+    this.filePathToId.clear();
+    await this.loadCapabilities();
+  }
+  handleFileAdd(filePath) {
+    this.logger.log(`Capability file added: ${filePath}`);
+    try {
+      this.loadCapabilityFromFile(filePath);
+    } catch (error) {
+      this.logger.error(`Failed to load new capability: ${filePath}`, error);
+    }
+  }
+  handleFileChange(filePath) {
+    this.logger.log(`Capability file changed: ${filePath}`);
+    try {
+      this.reloadCapabilityFromFile(filePath);
+    } catch (error) {
+      this.logger.error(`Failed to reload capability: ${filePath}`, error);
+    }
+  }
+  handleFileUnlink(filePath) {
+    this.logger.log(`Capability file removed: ${filePath}`);
+    this.removeCapabilityByFile(filePath);
+  }
+  /**
+  * 从文件加载单个能力配置
+  */
+  loadCapabilityFromFile(filePath) {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const config = JSON.parse(content);
+    if (!config.id) {
+      this.logger.warn(`Skipping capability without id: ${filePath}`);
+      return;
+    }
+    this.capabilities.set(config.id, config);
+    this.filePathToId.set(filePath, config.id);
+    this.logger.log(`Loaded capability: ${config.id} (${config.name})`);
   }
+  /**
+  * 重新加载单个能力配置
+  */
+  reloadCapabilityFromFile(filePath) {
+    const oldId = this.filePathToId.get(filePath);
+    if (oldId) {
+      const oldConfig = this.capabilities.get(oldId);
+      if (oldConfig) {
+        this.pluginLoaderService.clearCache(oldConfig.pluginKey);
+      }
+      this.capabilities.delete(oldId);
+    }
+    this.loadCapabilityFromFile(filePath);
+  }
+  /**
+  * 根据文件路径移除能力配置
+  */
+  removeCapabilityByFile(filePath) {
+    const capabilityId = this.filePathToId.get(filePath);
+    if (capabilityId) {
+      this.capabilities.delete(capabilityId);
+      this.filePathToId.delete(filePath);
+      this.logger.log(`Removed capability: ${capabilityId}`);
+    }
+  }
+  // ==================== 原有方法 ====================
   async loadCapabilities() {
     this.logger.log(`Loading capabilities from ${this.capabilitiesDir}`);
     if (!fs.existsSync(this.capabilitiesDir)) {
@@ -216,14 +447,7 @@ var CapabilityService = class _CapabilityService {
     for (const file of files) {
       try {
         const filePath = path.join(this.capabilitiesDir, file);
-        const content = fs.readFileSync(filePath, "utf-8");
-        const config = JSON.parse(content);
-        if (!config.id) {
-          this.logger.warn(`Skipping capability without id: ${file}`);
-          continue;
-        }
-        this.capabilities.set(config.id, config);
-        this.logger.log(`Loaded capability: ${config.id} (${config.name})`);
+        this.loadCapabilityFromFile(filePath);
       } catch (error) {
         this.logger.error(`Failed to load capability from ${file}:`, error);
       }
@@ -241,56 +465,246 @@ var CapabilityService = class _CapabilityService {
     if (!config) {
       throw new CapabilityNotFoundError(capabilityId);
     }
+    return this.createExecutor(config);
+  }
+  /**
+  * 使用传入的配置加载能力执行器
+  * 用于 debug 场景，支持用户传入自定义配置
+  */
+  loadWithConfig(config) {
+    return this.createExecutor(config);
+  }
+  createExecutor(config) {
     return {
       call: /* @__PURE__ */ __name(async (actionName, input, contextOverride) => {
-        return this.execute(config, actionName, input, contextOverride);
-      }, "call")
+        return this.executeCall(config, actionName, input, contextOverride);
+      }, "call"),
+      callStream: /* @__PURE__ */ __name((actionName, input, contextOverride) => {
+        return this.executeCallStream(config, actionName, input, contextOverride);
+      }, "callStream"),
+      callStreamWithEvents: /* @__PURE__ */ __name((actionName, input, contextOverride) => {
+        return this.executeCallStreamWithEvents(config, actionName, input, contextOverride);
+      }, "callStreamWithEvents"),
+      isStream: /* @__PURE__ */ __name(async (actionName) => {
+        return this.checkIsStream(config, actionName);
+      }, "isStream")
     };
   }
-  async execute(config, actionName, input, contextOverride) {
+  /**
+  * 检查 action 是否为流式
+  */
+  async checkIsStream(config, actionName) {
+    const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+    if (!pluginInstance.hasAction(actionName)) {
+      throw new ActionNotFoundError(config.pluginKey, actionName);
+    }
+    return pluginInstance.isStreamAction?.(actionName) ?? false;
+  }
+  /**
+  * 执行 capability（始终返回 Promise）
+  * - unary action: 直接返回结果
+  * - stream action: 内部聚合所有 chunk 后返回
+  */
+  async executeCall(config, actionName, input, contextOverride) {
     const startTime = Date.now();
+    const loggerContext = {
+      capability_id: config.id,
+      plugin_key: config.pluginKey,
+      action: actionName
+    };
     try {
-      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginID);
+      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
       if (!pluginInstance.hasAction(actionName)) {
-        throw new ActionNotFoundError(config.pluginID, actionName);
+        throw new ActionNotFoundError(config.pluginKey, actionName);
       }
-      const resolvedParams = this.templateEngineService.resolve(config.formValue, input);
+      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input) : input;
       const context = this.buildActionContext(contextOverride);
-      this.logger.log({
-        message: "Executing capability",
-        capabilityId: config.id,
-        action: actionName,
-        pluginID: config.pluginID
+      const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
+      this.logger.log("Executing capability (call)", {
+        ...loggerContext,
+        is_stream: isStream,
+        input: stringifyForLog(input)
       });
-      const result = await pluginInstance.run(actionName, context, resolvedParams);
-      this.logger.log({
-        message: "Capability executed successfully",
-        capabilityId: config.id,
-        action: actionName,
-        duration: Date.now() - startTime
+      let result;
+      if (isStream && pluginInstance.runStream) {
+        const chunks = [];
+        for await (const chunk of pluginInstance.runStream(actionName, context, resolvedParams)) {
+          chunks.push(chunk);
+        }
+        result = pluginInstance.aggregate ? pluginInstance.aggregate(actionName, chunks) : chunks;
+      } else {
+        result = await pluginInstance.run(actionName, context, resolvedParams);
+      }
+      this.logger.log("Capability (call) executed successfully", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        output: stringifyForLog(result)
       });
       return result;
     } catch (error) {
-      this.logger.error({
-        message: "Capability execution failed",
-        capabilityId: config.id,
-        action: actionName,
-        error: error instanceof Error ? error.message : String(error),
-        duration: Date.now() - startTime
+      this.logger.error("Capability (call) execution failed", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  /**
+  * 流式执行 capability
+  * - stream action: 返回原始 AsyncIterable
+  * - unary action: 包装为单次 yield
+  */
+  async *executeCallStream(config, actionName, input, contextOverride) {
+    const startTime = Date.now();
+    const loggerContext = {
+      capability_id: config.id,
+      plugin_key: config.pluginKey,
+      action: actionName
+    };
+    const chunks = [];
+    try {
+      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+      if (!pluginInstance.hasAction(actionName)) {
+        throw new ActionNotFoundError(config.pluginKey, actionName);
+      }
+      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input) : input;
+      const context = this.buildActionContext(contextOverride);
+      const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
+      this.logger.log("Executing capability (stream)", {
+        ...loggerContext,
+        is_stream: isStream,
+        input: stringifyForLog(input)
+      });
+      if (isStream && pluginInstance.runStream) {
+        for await (const chunk of pluginInstance.runStream(actionName, context, resolvedParams)) {
+          chunks.push(chunk);
+          yield chunk;
+        }
+      } else {
+        const result = await pluginInstance.run(actionName, context, resolvedParams);
+        chunks.push(result);
+        yield result;
+      }
+      const aggregatedResult = pluginInstance.aggregate ? pluginInstance.aggregate(actionName, chunks) : chunks;
+      this.logger.log("Capability (stream) executed successfully", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        output: stringifyForLog(aggregatedResult)
+      });
+    } catch (error) {
+      this.logger.error("Capability (stream) execution failed", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        error: error instanceof Error ? error.message : String(error)
       });
       throw error;
     }
   }
+  /**
+  * 流式执行 capability，返回带事件协议的流
+  * - 优先使用 pluginInstance.runStreamWithEvents
+  * - 如果插件不支持，则包装 runStream/run 为 StreamEvent
+  */
+  async *executeCallStreamWithEvents(config, actionName, input, contextOverride) {
+    const startTime = Date.now();
+    const loggerContext = {
+      capability_id: config.id,
+      plugin_key: config.pluginKey,
+      action: actionName
+    };
+    const chunks = [];
+    try {
+      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginKey);
+      if (!pluginInstance.hasAction(actionName)) {
+        throw new ActionNotFoundError(config.pluginKey, actionName);
+      }
+      const resolvedParams = config.formValue ? this.templateEngineService.resolve(config.formValue, input) : input;
+      const context = this.buildActionContext(contextOverride);
+      const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
+      this.logger.log("Executing capability (streamWithEvents)", {
+        ...loggerContext,
+        is_stream: isStream,
+        input: stringifyForLog(input)
+      });
+      if (pluginInstance.runStreamWithEvents) {
+        for await (const event of pluginInstance.runStreamWithEvents(actionName, context, resolvedParams)) {
+          if (event.type === "data") {
+            chunks.push(event.data);
+            yield event;
+          } else if (event.type === "done") {
+            const aggregatedResult2 = pluginInstance.aggregate ? pluginInstance.aggregate(actionName, chunks) : chunks;
+            yield {
+              type: "done",
+              metadata: {
+                ...event.metadata,
+                aggregated: aggregatedResult2
+              }
+            };
+          } else {
+            yield event;
+          }
+        }
+      } else {
+        if (isStream && pluginInstance.runStream) {
+          for await (const chunk of pluginInstance.runStream(actionName, context, resolvedParams)) {
+            chunks.push(chunk);
+            yield {
+              type: "data",
+              data: chunk
+            };
+          }
+        } else {
+          const result = await pluginInstance.run(actionName, context, resolvedParams);
+          chunks.push(result);
+          yield {
+            type: "data",
+            data: result
+          };
+        }
+        const aggregatedResult2 = pluginInstance.aggregate ? pluginInstance.aggregate(actionName, chunks) : chunks;
+        yield {
+          type: "done",
+          metadata: {
+            chunks: chunks.length,
+            duration: Date.now() - startTime,
+            aggregated: aggregatedResult2
+          }
+        };
+      }
+      const aggregatedResult = pluginInstance.aggregate ? pluginInstance.aggregate(actionName, chunks) : chunks;
+      this.logger.log("Capability (streamWithEvents) executed successfully", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        output: stringifyForLog(aggregatedResult)
+      });
+    } catch (error) {
+      this.logger.error("Capability (streamWithEvents) execution failed", {
+        ...loggerContext,
+        duration_ms: Date.now() - startTime,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      yield {
+        type: "error",
+        error: {
+          code: "EXECUTION_ERROR",
+          message: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  }
   buildActionContext(override) {
     return {
       logger: this.logger,
-      httpClient: this.httpClient,
-      userContext: override?.userContext ?? this.getUserContext()
+      platformHttpClient: this.platformHttpClient,
+      userContext: override?.userContext ?? this.getUserContext(),
+      isDebug: override?.isDebug ?? false
     };
   }
   getUserContext() {
     const ctx = this.requestContextService.getContext();
     return {
+      appId: ctx?.appId ?? "",
       userId: ctx?.userId ?? "",
       tenantId: ctx?.tenantId ?? ""
     };
@@ -309,7 +723,7 @@ CapabilityService = _ts_decorate3([
 ], CapabilityService);
 
 // src/controllers/debug.controller.ts
-import { Controller, Post, Get, Param, Body, HttpException, HttpStatus } from "@nestjs/common";
+import { Controller, Post, Get, Param, Body, Res, HttpException, HttpStatus, Logger as Logger3 } from "@nestjs/common";
 function _ts_decorate4(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);
@@ -327,31 +741,41 @@ function _ts_param2(paramIndex, decorator) {
   };
 }
 __name(_ts_param2, "_ts_param");
-var DebugController = class {
+var DebugController = class _DebugController {
   static {
     __name(this, "DebugController");
   }
   capabilityService;
+  pluginLoaderService;
   templateEngineService;
-  constructor(capabilityService, templateEngineService) {
+  logger = new Logger3(_DebugController.name);
+  constructor(capabilityService, pluginLoaderService, templateEngineService) {
     this.capabilityService = capabilityService;
+    this.pluginLoaderService = pluginLoaderService;
     this.templateEngineService = templateEngineService;
   }
   list() {
     const capabilities = this.capabilityService.listCapabilities();
     return {
-      code: 0,
-      message: "success",
-      data: capabilities.map((c) => ({
-        id: c.id,
-        name: c.name,
-        pluginID: c.pluginID,
-        pluginVersion: c.pluginVersion
-      }))
+      status_code: ErrorCodes.SUCCESS,
+      data: {
+        capabilities: capabilities.map((c) => ({
+          id: c.id,
+          name: c.name,
+          pluginID: c.pluginKey,
+          pluginVersion: c.pluginVersion
+        }))
+      }
     };
   }
-  async debug(capabilityId, body) {
-    const startTime = Date.now();
+  /**
+  * 获取 capability 配置
+  * 优先使用 body.capability，否则从服务获取
+  */
+  getCapabilityConfig(capabilityId, bodyCapability) {
+    if (bodyCapability) {
+      return bodyCapability;
+    }
     const config = this.capabilityService.getCapability(capabilityId);
     if (!config) {
       throw new HttpException({
@@ -360,72 +784,194 @@ var DebugController = class {
         error: "CAPABILITY_NOT_FOUND"
       }, HttpStatus.NOT_FOUND);
     }
-    const resolvedParams = this.templateEngineService.resolve(config.formValue, body.params);
+    return config;
+  }
+  /**
+  * 获取 action 名称
+  * 优先使用传入的 action，否则使用插件第一个 action
+  */
+  async getActionName(pluginKey, bodyAction) {
+    if (bodyAction) {
+      return bodyAction;
+    }
+    const pluginInstance = await this.pluginLoaderService.loadPlugin(pluginKey);
+    const actions = pluginInstance.listActions();
+    if (actions.length === 0) {
+      throw new HttpException({
+        code: 1,
+        message: `Plugin ${pluginKey} has no actions`,
+        error: "NO_ACTIONS"
+      }, HttpStatus.BAD_REQUEST);
+    }
+    return actions[0];
+  }
+  async debug(capabilityId, body) {
+    const startTime = Date.now();
+    const params = body.params ?? {};
+    const config = this.getCapabilityConfig(capabilityId, body.capability);
+    const action = await this.getActionName(config.pluginKey, body.action);
+    const resolvedParams = this.templateEngineService.resolve(config.formValue, params);
     try {
-      const result = await this.capabilityService.load(capabilityId).call(body.action, body.params);
+      const result = await this.capabilityService.loadWithConfig(config).call(action, params, {
+        isDebug: true
+      });
       return {
-        code: 0,
-        message: "success",
-        data: result,
-        debug: {
-          capabilityConfig: config,
-          resolvedParams,
-          duration: Date.now() - startTime,
-          pluginID: config.pluginID
+        status_code: ErrorCodes.SUCCESS,
+        data: {
+          output: result,
+          debug: {
+            capabilityConfig: config,
+            resolvedParams,
+            duration: Date.now() - startTime,
+            pluginID: config.pluginKey,
+            action
+          }
         }
       };
     } catch (error) {
-      const duration = Date.now() - startTime;
       if (error instanceof CapabilityNotFoundError) {
         throw new HttpException({
-          code: 1,
-          message: error.message,
-          error: "CAPABILITY_NOT_FOUND",
-          debug: {
-            duration
-          }
+          status_code: ErrorCodes.CAPABILITY_NOT_FOUND,
+          error_msg: `Capability not found: ${capabilityId}`
         }, HttpStatus.NOT_FOUND);
       }
       if (error instanceof PluginNotFoundError) {
         throw new HttpException({
-          code: 1,
-          message: error.message,
-          error: "PLUGIN_NOT_FOUND",
-          debug: {
-            duration,
-            pluginID: config.pluginID
-          }
+          status_code: ErrorCodes.PLUGIN_NOT_FOUND,
+          error_msg: `Plugin not found: ${config.pluginKey}`
         }, HttpStatus.INTERNAL_SERVER_ERROR);
       }
       if (error instanceof ActionNotFoundError) {
         throw new HttpException({
-          code: 1,
-          message: error.message,
-          error: "ACTION_NOT_FOUND",
-          debug: {
-            duration,
-            pluginID: config.pluginID
-          }
+          status_code: ErrorCodes.ACTION_NOT_FOUND,
+          error_msg: `Action '${action}' not found in plugin ${config.pluginKey}`
         }, HttpStatus.BAD_REQUEST);
       }
       throw new HttpException({
-        code: 1,
-        message: error instanceof Error ? error.message : String(error),
-        error: "EXECUTION_ERROR",
-        debug: {
-          duration,
-          pluginID: config.pluginID,
-          resolvedParams
-        }
+        status_code: ErrorCodes.EXECUTION_ERROR,
+        error_msg: `Execution failed: ${error instanceof Error ? error.message : String(error)}`
       }, HttpStatus.INTERNAL_SERVER_ERROR);
     }
   }
+  async debugStream(capabilityId, body, res) {
+    const params = body.params ?? {};
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    try {
+      const config = this.getCapabilityConfig(capabilityId, body.capability);
+      const action = await this.getActionName(config.pluginKey, body.action);
+      const loggerContext = {
+        capability_id: config.id,
+        plugin_key: config.pluginKey,
+        action
+      };
+      this.logger.log(`Executing capability (stream)`, {
+        ...loggerContext,
+        input: stringifyForLog(params)
+      });
+      const capability = this.capabilityService.loadWithConfig(config);
+      const eventStream = capability.callStreamWithEvents(action, params, {
+        isDebug: true
+      });
+      let pendingChunk = null;
+      for await (const event of eventStream) {
+        switch (event.type) {
+          case "data": {
+            if (pendingChunk !== null) {
+              const response = {
+                status_code: ErrorCodes.SUCCESS,
+                data: {
+                  type: "content",
+                  delta: pendingChunk
+                }
+              };
+              res.write(`data: ${JSON.stringify(response)}
+
+`);
+            }
+            pendingChunk = event.data;
+            break;
+          }
+          case "done": {
+            if (pendingChunk !== null) {
+              const response = {
+                status_code: ErrorCodes.SUCCESS,
+                data: {
+                  type: "content",
+                  delta: pendingChunk,
+                  finished: true
+                }
+              };
+              res.write(`data: ${JSON.stringify(response)}
+
+`);
+            }
+            this.logger.log(`Capability (stream) executed successfully`, {
+              ...loggerContext,
+              duration_ms: event.metadata.duration,
+              output: stringifyForLog(event.metadata.aggregated)
+            });
+            res.end();
+            return;
+          }
+          case "error": {
+            const response = {
+              status_code: ErrorCodes.SUCCESS,
+              data: {
+                type: "error",
+                error: {
+                  code: 0,
+                  message: event.error.message
+                }
+              }
+            };
+            res.write(`data: ${JSON.stringify(response)}
+
+`);
+            res.end();
+            return;
+          }
+        }
+      }
+      if (pendingChunk !== null) {
+        const response = {
+          status_code: ErrorCodes.SUCCESS,
+          data: {
+            type: "content",
+            delta: pendingChunk,
+            finished: true
+          }
+        };
+        res.write(`data: ${JSON.stringify(response)}
+
+`);
+      }
+      res.end();
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      const response = {
+        status_code: ErrorCodes.SUCCESS,
+        data: {
+          type: "error",
+          error: {
+            code: 0,
+            message: errorMsg
+          }
+        }
+      };
+      res.write(`data: ${JSON.stringify(response)}
+
+`);
+      res.end();
+    }
+  }
 };
 _ts_decorate4([
   Get("list"),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", []),
-  _ts_metadata2("design:returntype", typeof ListResponse === "undefined" ? Object : ListResponse)
+  _ts_metadata2("design:returntype", typeof SuccessResponse === "undefined" ? Object : SuccessResponse)
 ], DebugController.prototype, "list", null);
 _ts_decorate4([
   Post("debug/:capability_id"),
@@ -434,21 +980,35 @@ _ts_decorate4([
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     String,
-    typeof ExecuteRequestBody === "undefined" ? Object : ExecuteRequestBody
+    typeof DebugRequestBody === "undefined" ? Object : DebugRequestBody
   ]),
   _ts_metadata2("design:returntype", Promise)
 ], DebugController.prototype, "debug", null);
+_ts_decorate4([
+  Post("debug/:capability_id/stream"),
+  _ts_param2(0, Param("capability_id")),
+  _ts_param2(1, Body()),
+  _ts_param2(2, Res()),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    String,
+    typeof DebugRequestBody === "undefined" ? Object : DebugRequestBody,
+    typeof Response === "undefined" ? Object : Response
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], DebugController.prototype, "debugStream", null);
 DebugController = _ts_decorate4([
   Controller("__innerapi__/capability"),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof CapabilityService === "undefined" ? Object : CapabilityService,
+    typeof PluginLoaderService === "undefined" ? Object : PluginLoaderService,
     typeof TemplateEngineService === "undefined" ? Object : TemplateEngineService
   ])
 ], DebugController);
 
 // src/controllers/webhook.controller.ts
-import { Controller as Controller2, Get as Get2, Post as Post2, Param as Param2, Body as Body2, HttpException as HttpException2, HttpStatus as HttpStatus2 } from "@nestjs/common";
+import { Controller as Controller2, Get as Get2, Post as Post2, Param as Param2, Body as Body2, Res as Res2, HttpException as HttpException2, HttpStatus as HttpStatus2, Logger as Logger4 } from "@nestjs/common";
 function _ts_decorate5(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);
@@ -466,71 +1026,176 @@ function _ts_param3(paramIndex, decorator) {
   };
 }
 __name(_ts_param3, "_ts_param");
-var WebhookController = class {
+var WebhookController = class _WebhookController {
   static {
     __name(this, "WebhookController");
   }
   capabilityService;
+  logger = new Logger4(_WebhookController.name);
   constructor(capabilityService) {
     this.capabilityService = capabilityService;
   }
   list() {
     const capabilities = this.capabilityService.listCapabilities();
     return {
-      code: 0,
-      message: "success",
-      data: capabilities.map((c) => ({
-        id: c.id,
-        name: c.name,
-        description: c.description,
-        pluginID: c.pluginID,
-        pluginVersion: c.pluginVersion
-      }))
+      status_code: ErrorCodes.SUCCESS,
+      data: {
+        capabilities: capabilities.map((c) => ({
+          id: c.id,
+          name: c.name,
+          pluginID: c.pluginKey,
+          pluginVersion: c.pluginVersion
+        }))
+      }
     };
   }
   async execute(capabilityId, body) {
     try {
       const result = await this.capabilityService.load(capabilityId).call(body.action, body.params);
       return {
-        code: 0,
-        message: "success",
-        data: result
+        status_code: ErrorCodes.SUCCESS,
+        data: {
+          output: result
+        }
       };
     } catch (error) {
       if (error instanceof CapabilityNotFoundError) {
         throw new HttpException2({
-          code: 1,
-          message: error.message,
-          error: "CAPABILITY_NOT_FOUND"
+          status_code: ErrorCodes.CAPABILITY_NOT_FOUND,
+          error_msg: `Capability not found: ${capabilityId}`
         }, HttpStatus2.NOT_FOUND);
       }
       if (error instanceof PluginNotFoundError) {
         throw new HttpException2({
-          code: 1,
-          message: error.message,
-          error: "PLUGIN_NOT_FOUND"
+          status_code: ErrorCodes.PLUGIN_NOT_FOUND,
+          error_msg: `Plugin not found`
         }, HttpStatus2.INTERNAL_SERVER_ERROR);
       }
       if (error instanceof ActionNotFoundError) {
         throw new HttpException2({
-          code: 1,
-          message: error.message,
-          error: "ACTION_NOT_FOUND"
+          status_code: ErrorCodes.ACTION_NOT_FOUND,
+          error_msg: `Action '${body.action}' not found`
         }, HttpStatus2.BAD_REQUEST);
       }
       throw new HttpException2({
-        code: 1,
-        message: error instanceof Error ? error.message : String(error),
-        error: "EXECUTION_ERROR"
+        status_code: ErrorCodes.EXECUTION_ERROR,
+        error_msg: `Execution failed: ${error instanceof Error ? error.message : String(error)}`
       }, HttpStatus2.INTERNAL_SERVER_ERROR);
     }
   }
+  async executeStream(capabilityId, body, res) {
+    const loggerContext = {
+      capability_id: capabilityId,
+      action: body.action
+    };
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    try {
+      this.logger.log(`Executing capability (stream)`, {
+        ...loggerContext,
+        input: stringifyForLog(body.params)
+      });
+      const capability = this.capabilityService.load(capabilityId);
+      const eventStream = capability.callStreamWithEvents(body.action, body.params);
+      let pendingChunk = null;
+      for await (const event of eventStream) {
+        switch (event.type) {
+          case "data": {
+            if (pendingChunk !== null) {
+              const response = {
+                status_code: ErrorCodes.SUCCESS,
+                data: {
+                  type: "content",
+                  delta: pendingChunk
+                }
+              };
+              res.write(`data: ${JSON.stringify(response)}
+
+`);
+            }
+            pendingChunk = event.data;
+            break;
+          }
+          case "done": {
+            if (pendingChunk !== null) {
+              const response = {
+                status_code: ErrorCodes.SUCCESS,
+                data: {
+                  type: "content",
+                  delta: pendingChunk,
+                  finished: true
+                }
+              };
+              res.write(`data: ${JSON.stringify(response)}
+
+`);
+            }
+            this.logger.log(`Capability (stream) executed successfully`, {
+              ...loggerContext,
+              duration_ms: event.metadata.duration,
+              output: stringifyForLog(event.metadata.aggregated)
+            });
+            res.end();
+            return;
+          }
+          case "error": {
+            const response = {
+              status_code: ErrorCodes.SUCCESS,
+              data: {
+                type: "error",
+                error: {
+                  code: 0,
+                  message: event.error.message
+                }
+              }
+            };
+            res.write(`data: ${JSON.stringify(response)}
+
+`);
+            res.end();
+            return;
+          }
+        }
+      }
+      if (pendingChunk !== null) {
+        const response = {
+          status_code: ErrorCodes.SUCCESS,
+          data: {
+            type: "content",
+            delta: pendingChunk,
+            finished: true
+          }
+        };
+        res.write(`data: ${JSON.stringify(response)}
+
+`);
+      }
+      res.end();
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      const response = {
+        status_code: ErrorCodes.SUCCESS,
+        data: {
+          type: "error",
+          error: {
+            code: 0,
+            message: errorMsg
+          }
+        }
+      };
+      res.write(`data: ${JSON.stringify(response)}
+
+`);
+      res.end();
+    }
+  }
 };
 _ts_decorate5([
   Get2("list"),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", []),
-  _ts_metadata3("design:returntype", typeof ListResponse === "undefined" ? Object : ListResponse)
+  _ts_metadata3("design:returntype", typeof SuccessResponse === "undefined" ? Object : SuccessResponse)
 ], WebhookController.prototype, "list", null);
 _ts_decorate5([
   Post2(":capability_id"),
@@ -543,6 +1208,19 @@ _ts_decorate5([
   ]),
   _ts_metadata3("design:returntype", Promise)
 ], WebhookController.prototype, "execute", null);
+_ts_decorate5([
+  Post2(":capability_id/stream"),
+  _ts_param3(0, Param2("capability_id")),
+  _ts_param3(1, Body2()),
+  _ts_param3(2, Res2()),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
+    String,
+    typeof ExecuteRequestBody === "undefined" ? Object : ExecuteRequestBody,
+    typeof Response === "undefined" ? Object : Response
+  ]),
+  _ts_metadata3("design:returntype", Promise)
+], WebhookController.prototype, "executeStream", null);
 WebhookController = _ts_decorate5([
   Controller2("api/capability"),
   _ts_metadata3("design:type", Function),
@@ -553,7 +1231,7 @@ WebhookController = _ts_decorate5([
 
 // src/capability.module.ts
 import { Module } from "@nestjs/common";
-import { RequestContextService as RequestContextService2, PLATFORM_HTTP_CLIENT as PLATFORM_HTTP_CLIENT2 } from "@lark-apaas/nestjs-common";
+import { CommonModule, RequestContextService as RequestContextService2, PLATFORM_HTTP_CLIENT as PLATFORM_HTTP_CLIENT2 } from "@lark-apaas/nestjs-common";
 function _ts_decorate6(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);
@@ -580,6 +1258,9 @@ var CapabilityModule = class _CapabilityModule {
   static forRoot(options) {
     return {
       module: _CapabilityModule,
+      imports: [
+        CommonModule
+      ],
       controllers: getControllers(),
       providers: [
         {
@@ -590,8 +1271,8 @@ var CapabilityModule = class _CapabilityModule {
           provide: CapabilityService,
           useFactory: /* @__PURE__ */ __name((requestContextService, httpClient, pluginLoader, templateEngine, moduleOptions) => {
             const service = new CapabilityService(requestContextService, httpClient, pluginLoader, templateEngine);
-            if (moduleOptions?.capabilitiesDir) {
-              service.setCapabilitiesDir(moduleOptions.capabilitiesDir);
+            if (moduleOptions) {
+              service.setOptions(moduleOptions);
             }
             return service;
           }, "useFactory"),
@@ -614,6 +1295,9 @@ var CapabilityModule = class _CapabilityModule {
 };
 CapabilityModule = _ts_decorate6([
   Module({
+    imports: [
+      CommonModule
+    ],
     controllers: getControllers(),
     providers: [
       CapabilityService,
@@ -631,6 +1315,7 @@ export {
   CapabilityNotFoundError,
   CapabilityService,
   DebugController,
+  ErrorCodes,
   PluginLoadError,
   PluginLoaderService,
   PluginNotFoundError,