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

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# @lark-apaas/nestjs-capability
+
+用于加载和执行能力（插件实例）的 NestJS 模块。
+
+## 安装
+
+```bash
+npm install @lark-apaas/nestjs-capability
+```
+
+## 概述
+
+本模块提供以下功能：
+
+- 从 `server/capabilities/` 目录加载能力配置
+- 加载并实例化关联的插件
+- 多种调用方式（Node 调用、Debug 调用、前端调用）
+- 模板参数解析
+
+## 快速开始
+
+### 模块注册
+
+```typescript
+// app.module.ts
+import { CapabilityModule } from '@lark-apaas/nestjs-capability';
+import * as path from 'path';
+
+@Module({
+  imports: [
+    CapabilityModule.forRoot({
+      capabilitiesDir: path.join(__dirname, '../capabilities'),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Node 调用
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CapabilityService } from '@lark-apaas/nestjs-capability';
+
+@Injectable()
+export class TaskService {
+  constructor(private readonly capabilityService: CapabilityService) {}
+
+  async onTaskCreated(task: Task) {
+    const result = await this.capabilityService
+      .load('create_feishu_group_for_task')
+      .call('run', {
+        group_name: `任务群 - ${task.name}`,
+        creator_id: task.creatorId,
+      });
+
+    return result;
+  }
+}
+```
+
+### 上下文覆盖
+
+```typescript
+const result = await this.capabilityService
+  .load('notify_task_created')
+  .call('run', inputParams, {
+    userContext: {
+      userId: 'custom-user-id',
+      tenantId: 'custom-tenant-id',
+    },
+  });
+```
+
+## 能力配置
+
+能力配置是位于 `server/capabilities/` 目录下的 JSON 文件：
+
+```json
+{
+  "id": "create_feishu_group_for_task",
+  "pluginID": "@official-components/feishu-group-create",
+  "pluginVersion": "1.0.5",
+  "name": "任务创建时自动创建飞书群组",
+  "description": "在任务创建时，根据任务名称自动生成飞书群组",
+  "paramsSchema": {
+    "type": "object",
+    "properties": {
+      "group_name": { "type": "string" }
+    }
+  },
+  "formValue": {
+    "group_name": "{{input.group_name}}",
+    "members": ["123"]
+  },
+  "createdAt": 1764234360374,
+  "updatedAt": 1764234360374
+}
+```
+
+### 模板语法
+
+`formValue` 字段支持模板占位符：
+
+- `{{input.xxx}}` - 引用用户输入参数
+- `{{input.user.name}}` - 支持嵌套路径
+
+## HTTP API
+
+### 前端调用
+
+```
+POST /api/capability/:capability_id
+
+请求体：
+{
+  "action": "run",
+  "params": {
+    "group_name": "项目A群"
+  }
+}
+
+响应：
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+### Debug 调用（仅开发环境）
+
+```
+POST /__innerapi__/capability/debug/:capability_id
+
+请求体：
+{
+  "action": "run",
+  "params": {
+    "group_name": "测试群"
+  }
+}
+
+响应：
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... },
+  "debug": {
+    "capabilityConfig": { ... },
+    "resolvedParams": { ... },
+    "duration": 123,
+    "pluginID": "@xxx/plugin"
+  }
+}
+```
+
+### 列出所有能力（仅开发环境）
+
+```
+GET /__innerapi__/capability/list
+
+响应：
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "create_feishu_group_for_task",
+      "name": "任务创建时自动创建飞书群组",
+      "pluginID": "@official-components/feishu-group-create",
+      "pluginVersion": "1.0.5"
+    }
+  ]
+}
+```
+
+## 服务
+
+### CapabilityService
+
+用于加载和执行能力的核心服务。
+
+```typescript
+interface CapabilityService {
+  // 列出所有已加载的能力
+  listCapabilities(): CapabilityConfig[];
+
+  // 获取指定能力
+  getCapability(capabilityId: string): CapabilityConfig | null;
+
+  // 加载能力并返回执行器
+  load(capabilityId: string): CapabilityExecutor;
+
+  // 设置自定义能力目录
+  setCapabilitiesDir(dir: string): void;
+}
+
+interface CapabilityExecutor {
+  call(
+    actionName: string,
+    input: unknown,
+    context?: Partial<PluginActionContext>
+  ): Promise<unknown>;
+}
+```
+
+### PluginLoaderService
+
+用于加载和缓存插件实例的服务。
+
+```typescript
+interface PluginLoaderService {
+  // 加载插件并创建实例（带缓存）
+  loadPlugin(pluginID: string): PluginInstance;
+
+  // 检查插件是否已安装
+  isPluginInstalled(pluginID: string): boolean;
+
+  // 清除插件缓存
+  clearCache(pluginID?: string): void;
+}
+```
+
+### TemplateEngineService
+
+用于解析 formValue 模板的服务。
+
+```typescript
+interface TemplateEngineService {
+  resolve(
+    template: Record<string, unknown>,
+    input: Record<string, unknown>
+  ): Record<string, unknown>;
+}
+```
+
+## 接口定义
+
+### CapabilityConfig
+
+```typescript
+interface CapabilityConfig {
+  id: string;           // 能力唯一标识
+  pluginID: string;     // 关联的插件 ID
+  pluginVersion: string; // 关联的插件版本
+  name: string;         // 能力名称
+  description: string;  // 能力描述
+  paramsSchema: JSONSchema; // 输入参数 JSON Schema
+  formValue: Record<string, unknown>; // 参数映射模板
+  createdAt: number;    // 创建时间戳
+  updatedAt: number;    // 更新时间戳
+}
+```
+
+### PluginInstance
+
+```typescript
+interface PluginInstance {
+  run(actionName: string, context: PluginActionContext, input: unknown): Promise<unknown>;
+  hasAction(actionName: string): boolean;
+  getActionSchema(actionName: string): ActionSchema | null;
+  listActions(): string[];
+  getInputSchema(actionName: string, config?: unknown): ZodSchema | undefined;
+  getOutputSchema(actionName: string, input: unknown, config?: unknown): ZodSchema | undefined;
+}
+```
+
+### PluginActionContext
+
+```typescript
+interface PluginActionContext {
+  logger: Logger;           // 日志记录器
+  httpClient: PlatformHttpClient; // HTTP 客户端（平台鉴权）
+  userContext: {
+    userId: string;         // 用户 ID
+    tenantId: string;       // 租户 ID
+  };
+}
+```
+
+## 错误类型
+
+| 错误 | 描述 |
+|------|------|
+| `CapabilityNotFoundError` | 指定 ID 的能力不存在 |
+| `PluginNotFoundError` | 插件未安装 |
+| `PluginLoadError` | 插件加载或初始化失败 |
+| `ActionNotFoundError` | 插件中不存在指定的 Action |
+
+## 模块配置
+
+```typescript
+interface CapabilityModuleOptions {
+  // 能力配置目录路径（默认：server/capabilities）
+  capabilitiesDir?: string;
+}
+```
+
+## 依赖
+
+- `@lark-apaas/nestjs-common` - 提供 RequestContextService 和 PLATFORM_HTTP_CLIENT
+- `@nestjs/common` - NestJS 框架
+
+## 许可证
+
+MIT