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

package/README.md

@@ -15,6 +15,7 @@ npm install @lark-apaas/nestjs-capability
 - 从 `server/capabilities/` 目录加载能力配置
 - 加载并实例化关联的插件
 - 多种调用方式（Node 调用、Debug 调用、前端调用）
+- 流式调用支持（SSE）
 - 模板参数解析
 
 ## 快速开始
@@ -59,6 +60,36 @@ export class TaskService {
 }
 ```
 
+### 流式调用
+
+用于 LLM 对话等流式输出场景：
+
+```typescript
+@Injectable()
+export class ChatService {
+  constructor(private readonly capabilityService: CapabilityService) {}
+
+  async *chat(message: string): AsyncIterable<{ content: string }> {
+    const stream = this.capabilityService
+      .load('ai_chat')
+      .callStream('chat', { message });
+
+    for await (const chunk of stream) {
+      yield chunk as { content: string };
+    }
+  }
+}
+```
+
+普通调用会自动聚合流式结果：
+
+```typescript
+// 即使是流式 action，call() 也会返回聚合后的完整结果
+const result = await this.capabilityService
+  .load('ai_chat')
+  .call('chat', { message: 'hello' });
+```
+
 ### 上下文覆盖
 
 ```typescript
@@ -128,16 +159,42 @@ POST /api/capability/:capability_id
 }
 ```
 
-### Debug 调用（仅开发环境）
+### 前端流式调用
 
 ```
-POST /__innerapi__/capability/debug/:capability_id
+POST /api/capability/:capability_id/stream
 
 请求体：
 {
-  "action": "run",
+  "action": "chat",
   "params": {
+    "message": "hello"
+  }
+}
+
+响应（SSE 格式）：
+data: {"content":"Hello"}
+data: {"content":" World"}
+data: [DONE]
+```
+
+### Debug 调用（仅开发环境）
+
+```
+POST /__innerapi__/capability/debug/:capability_id
+
+请求体（所有字段可选）：
+{
+  "action": "run",              // 可选，默认使用插件第一个 action
+  "params": {                   // 可选，用户输入参数
     "group_name": "测试群"
+  },
+  "capability": {               // 可选，完整的 capability 配置（优先使用）
+    "id": "test",
+    "pluginID": "@test/plugin",
+    "pluginVersion": "1.0.0",
+    "name": "测试",
+    "formValue": {}
   }
 }
 
@@ -150,11 +207,30 @@ POST /__innerapi__/capability/debug/:capability_id
     "capabilityConfig": { ... },
     "resolvedParams": { ... },
     "duration": 123,
-    "pluginID": "@xxx/plugin"
+    "pluginID": "@xxx/plugin",
+    "action": "run"
   }
 }
 ```
 
+### Debug 流式调用（仅开发环境）
+
+```
+POST /__innerapi__/capability/debug/:capability_id/stream
+
+请求体（所有字段可选）：
+{
+  "action": "chat",
+  "params": { "message": "hello" },
+  "capability": { ... }
+}
+
+响应（SSE 格式）：
+data: {"content":"Hello"}
+data: {"content":" World"}
+data: [DONE]
+```
+
 ### 列出所有能力（仅开发环境）
 
 ```
@@ -192,16 +268,30 @@ interface CapabilityService {
   // 加载能力并返回执行器
   load(capabilityId: string): CapabilityExecutor;
 
+  // 使用传入的配置加载能力执行器（用于 debug 场景）
+  loadWithConfig(config: CapabilityConfig): CapabilityExecutor;
+
   // 设置自定义能力目录
   setCapabilitiesDir(dir: string): void;
 }
 
 interface CapabilityExecutor {
+  // 调用能力（流式 action 会自动聚合结果）
   call(
     actionName: string,
     input: unknown,
     context?: Partial<PluginActionContext>
   ): Promise<unknown>;
+
+  // 流式调用能力（返回 AsyncIterable）
+  callStream(
+    actionName: string,
+    input: unknown,
+    context?: Partial<PluginActionContext>
+  ): AsyncIterable<unknown>;
+
+  // 检查 action 是否为流式
+  isStream(actionName: string): Promise<boolean>;
 }
 ```
 
@@ -257,10 +347,22 @@ interface CapabilityConfig {
 
 ```typescript
 interface PluginInstance {
+  // 执行 action（必需）
   run(actionName: string, context: PluginActionContext, input: unknown): Promise<unknown>;
+
+  // 流式执行 action（可选）
+  runStream?(actionName: string, context: PluginActionContext, input: unknown): AsyncIterable<unknown>;
+
+  // 检查是否为流式 action（可选）
+  isStreamAction?(actionName: string): boolean;
+
+  // 聚合流式结果（可选，默认返回 chunks 数组）
+  aggregate?(actionName: string, chunks: unknown[]): unknown;
+
+  // Action 相关
   hasAction(actionName: string): boolean;
-  getActionSchema(actionName: string): ActionSchema | null;
   listActions(): string[];
+  getActionSchema(actionName: string): ActionSchema | null;
   getInputSchema(actionName: string, config?: unknown): ZodSchema | undefined;
   getOutputSchema(actionName: string, input: unknown, config?: unknown): ZodSchema | undefined;
 }

package/dist/index.cjs

@@ -57,7 +57,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);
@@ -71,12 +74,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 = {};
@@ -278,13 +294,44 @@ 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"),
+      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.pluginID);
+    if (!pluginInstance.hasAction(actionName)) {
+      throw new ActionNotFoundError(config.pluginID, actionName);
+    }
+    return pluginInstance.isStreamAction?.(actionName) ?? false;
+  }
+  /**
+  * 执行 capability（始终返回 Promise）
+  * - unary action: 直接返回结果
+  * - stream action: 内部聚合所有 chunk 后返回
+  */
+  async executeCall(config, actionName, input, contextOverride) {
     const startTime = Date.now();
     try {
       const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginID);
@@ -293,13 +340,24 @@ var CapabilityService = class _CapabilityService {
       }
       const resolvedParams = this.templateEngineService.resolve(config.formValue, input);
       const context = this.buildActionContext(contextOverride);
+      const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
       this.logger.log({
         message: "Executing capability",
         capabilityId: config.id,
         action: actionName,
-        pluginID: config.pluginID
+        pluginID: config.pluginID,
+        isStream
       });
-      const result = await pluginInstance.run(actionName, context, resolvedParams);
+      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({
         message: "Capability executed successfully",
         capabilityId: config.id,
@@ -318,6 +376,51 @@ var CapabilityService = class _CapabilityService {
       throw error;
     }
   }
+  /**
+  * 流式执行 capability
+  * - stream action: 返回原始 AsyncIterable
+  * - unary action: 包装为单次 yield
+  */
+  async *executeCallStream(config, actionName, input, contextOverride) {
+    const startTime = Date.now();
+    try {
+      const pluginInstance = await this.pluginLoaderService.loadPlugin(config.pluginID);
+      if (!pluginInstance.hasAction(actionName)) {
+        throw new ActionNotFoundError(config.pluginID, actionName);
+      }
+      const resolvedParams = this.templateEngineService.resolve(config.formValue, input);
+      const context = this.buildActionContext(contextOverride);
+      const isStream = pluginInstance.isStreamAction?.(actionName) ?? false;
+      this.logger.log({
+        message: "Executing capability (stream)",
+        capabilityId: config.id,
+        action: actionName,
+        pluginID: config.pluginID,
+        isStream
+      });
+      if (isStream && pluginInstance.runStream) {
+        yield* pluginInstance.runStream(actionName, context, resolvedParams);
+      } else {
+        const result = await pluginInstance.run(actionName, context, resolvedParams);
+        yield result;
+      }
+      this.logger.log({
+        message: "Capability stream completed",
+        capabilityId: config.id,
+        action: actionName,
+        duration: Date.now() - startTime
+      });
+    } catch (error) {
+      this.logger.error({
+        message: "Capability stream execution failed",
+        capabilityId: config.id,
+        action: actionName,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
+      throw error;
+    }
+  }
   buildActionContext(override) {
     return {
       logger: this.logger,
@@ -369,9 +472,11 @@ var DebugController = class {
     __name(this, "DebugController");
   }
   capabilityService;
+  pluginLoaderService;
   templateEngineService;
-  constructor(capabilityService, templateEngineService) {
+  constructor(capabilityService, pluginLoaderService, templateEngineService) {
     this.capabilityService = capabilityService;
+    this.pluginLoaderService = pluginLoaderService;
     this.templateEngineService = templateEngineService;
   }
   list() {
@@ -387,8 +492,14 @@ var DebugController = class {
       }))
     };
   }
-  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 import_common4.HttpException({
@@ -397,9 +508,35 @@ var DebugController = class {
         error: "CAPABILITY_NOT_FOUND"
       }, import_common4.HttpStatus.NOT_FOUND);
     }
-    const resolvedParams = this.templateEngineService.resolve(config.formValue, body.params);
+    return config;
+  }
+  /**
+  * 获取 action 名称
+  * 优先使用传入的 action，否则使用插件第一个 action
+  */
+  async getActionName(pluginID, bodyAction) {
+    if (bodyAction) {
+      return bodyAction;
+    }
+    const pluginInstance = await this.pluginLoaderService.loadPlugin(pluginID);
+    const actions = pluginInstance.listActions();
+    if (actions.length === 0) {
+      throw new import_common4.HttpException({
+        code: 1,
+        message: `Plugin ${pluginID} has no actions`,
+        error: "NO_ACTIONS"
+      }, import_common4.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.pluginID, 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);
       return {
         code: 0,
         message: "success",
@@ -408,7 +545,8 @@ var DebugController = class {
           capabilityConfig: config,
           resolvedParams,
           duration: Date.now() - startTime,
-          pluginID: config.pluginID
+          pluginID: config.pluginID,
+          action
         }
       };
     } catch (error) {
@@ -430,7 +568,8 @@ var DebugController = class {
           error: "PLUGIN_NOT_FOUND",
           debug: {
             duration,
-            pluginID: config.pluginID
+            pluginID: config.pluginID,
+            action
           }
         }, import_common4.HttpStatus.INTERNAL_SERVER_ERROR);
       }
@@ -441,7 +580,8 @@ var DebugController = class {
           error: "ACTION_NOT_FOUND",
           debug: {
             duration,
-            pluginID: config.pluginID
+            pluginID: config.pluginID,
+            action
           }
         }, import_common4.HttpStatus.BAD_REQUEST);
       }
@@ -452,11 +592,51 @@ var DebugController = class {
         debug: {
           duration,
           pluginID: config.pluginID,
+          action,
           resolvedParams
         }
       }, import_common4.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.pluginID, body.action);
+      const capability = this.capabilityService.loadWithConfig(config);
+      const stream = capability.callStream(action, params);
+      for await (const chunk of stream) {
+        res.write(`data: ${JSON.stringify(chunk)}
+
+`);
+      }
+      res.write("data: [DONE]\n\n");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      let errorCode = "EXECUTION_ERROR";
+      if (error instanceof CapabilityNotFoundError) {
+        errorCode = "CAPABILITY_NOT_FOUND";
+      } else if (error instanceof PluginNotFoundError) {
+        errorCode = "PLUGIN_NOT_FOUND";
+      } else if (error instanceof ActionNotFoundError) {
+        errorCode = "ACTION_NOT_FOUND";
+      } else if (error instanceof import_common4.HttpException) {
+        const response = error.getResponse();
+        errorCode = response.error ?? "EXECUTION_ERROR";
+      }
+      res.write(`data: ${JSON.stringify({
+        error: message,
+        code: errorCode
+      })}
+
+`);
+    } finally {
+      res.end();
+    }
+  }
 };
 _ts_decorate4([
   (0, import_common4.Get)("list"),
@@ -471,15 +651,29 @@ _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([
+  (0, import_common4.Post)("debug/:capability_id/stream"),
+  _ts_param2(0, (0, import_common4.Param)("capability_id")),
+  _ts_param2(1, (0, import_common4.Body)()),
+  _ts_param2(2, (0, import_common4.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([
   (0, import_common4.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);
@@ -562,6 +756,39 @@ var WebhookController = class {
       }, import_common5.HttpStatus.INTERNAL_SERVER_ERROR);
     }
   }
+  async executeStream(capabilityId, body, res) {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    try {
+      const capability = this.capabilityService.load(capabilityId);
+      const stream = capability.callStream(body.action, body.params);
+      for await (const chunk of stream) {
+        res.write(`data: ${JSON.stringify(chunk)}
+
+`);
+      }
+      res.write("data: [DONE]\n\n");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      let errorCode = "EXECUTION_ERROR";
+      if (error instanceof CapabilityNotFoundError) {
+        errorCode = "CAPABILITY_NOT_FOUND";
+      } else if (error instanceof PluginNotFoundError) {
+        errorCode = "PLUGIN_NOT_FOUND";
+      } else if (error instanceof ActionNotFoundError) {
+        errorCode = "ACTION_NOT_FOUND";
+      }
+      res.write(`data: ${JSON.stringify({
+        error: message,
+        code: errorCode
+      })}
+
+`);
+    } finally {
+      res.end();
+    }
+  }
 };
 _ts_decorate5([
   (0, import_common5.Get)("list"),
@@ -580,6 +807,19 @@ _ts_decorate5([
   ]),
   _ts_metadata3("design:returntype", Promise)
 ], WebhookController.prototype, "execute", null);
+_ts_decorate5([
+  (0, import_common5.Post)(":capability_id/stream"),
+  _ts_param3(0, (0, import_common5.Param)("capability_id")),
+  _ts_param3(1, (0, import_common5.Body)()),
+  _ts_param3(2, (0, import_common5.Res)()),
+  _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([
   (0, import_common5.Controller)("api/capability"),
   _ts_metadata3("design:type", Function),