@lark-apaas/nestjs-capability 0.0.1-alpha.0 → 0.0.1-alpha.10

package/README.md

@@ -15,6 +15,7 @@ npm install @lark-apaas/nestjs-capability
 - 从 `server/capabilities/` 目录加载能力配置
 - 加载并实例化关联的插件
 - 多种调用方式（Node 调用、Debug 调用、前端调用）
+- 流式调用支持（SSE）
 - 模板参数解析
 
 ## 快速开始
@@ -59,17 +60,56 @@ 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
+// 覆盖 userContext
 const result = await this.capabilityService
   .load('notify_task_created')
   .call('run', inputParams, {
     userContext: {
       userId: 'custom-user-id',
       tenantId: 'custom-tenant-id',
+      appId: 'custom-app-id',
     },
   });
+
+// 设置调试模式（插件可据此返回更详细的错误信息）
+const debugResult = await this.capabilityService
+  .load('ai_chat')
+  .call('chat', inputParams, {
+    isDebug: true,
+  });
 ```
 
 ## 能力配置
@@ -128,16 +168,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 +216,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 +277,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 +356,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;
 }
@@ -275,10 +386,17 @@ interface PluginActionContext {
   userContext: {
     userId: string;         // 用户 ID
     tenantId: string;       // 租户 ID
+    appId: string;          // 应用 ID
   };
+  isDebug: boolean;         // 是否为调试模式
 }
 ```
 
+**isDebug 说明：**
+- `DebugController` 调用时 `isDebug = true`
+- `WebhookController` 或其他调用时 `isDebug = false`
+- 插件可据此返回更详细的错误信息、调试日志等
+
 ## 错误类型
 
 | 错误 | 描述 |