@lark-apaas/nestjs-capability 0.1.10 → 0.1.12

package/dist/index.d.cts

@@ -403,6 +403,16 @@ declare class ActionNotFoundError extends Error {
     readonly actionName: string;
     constructor(pluginKey: string, actionName: string);
 }
+interface ParamDiagnostic {
+    field: string;
+    reason: 'not_provided' | 'empty_value';
+    detail: string;
+}
+declare class RequiredParamMissingError extends Error {
+    readonly capabilityName: string;
+    readonly diagnostics: ParamDiagnostic[];
+    constructor(capabilityName: string, diagnostics: ParamDiagnostic[]);
+}
 interface CapabilityExecutor {
     /**
      * 调用 capability（始终返回 Promise）
@@ -499,6 +509,17 @@ declare class CapabilityService implements OnModuleInit, OnModuleDestroy {
      * 根据 manifest 的 form.refType 决定 formValue 的消费方式
      */
     private loadPluginAndResolveParams;
+    /**
+     * 校验调用方传入的 input 是否满足 paramsSchema.required 约束。
+     *
+     * 注意：校验发生在模板替换之前。paramsSchema.required 声明的是调用方需要传哪些变量
+     * （它们会被 formValue 中的 {{input.xxx}} 引用），不是 resolve 后的 formValue key。
+     *
+     * 诊断原因：
+     *   not_provided — input 中完全没有该字段（key 不存在 / undefined / null），调用方未传
+     *   empty_value  — 调用方传了值但为空（空串/空数组），需要检查数据来源
+     */
+    private validateRequiredParams;
     /**
      * 检查 action 是否为流式
      */
@@ -661,4 +682,4 @@ interface MigrationResponse {
  */
 declare function migrationAdaptor(promise: Promise<unknown>): Promise<MigrationResponse>;
 
-export { ActionNotFoundError, type ActionSchema, type CallEventDetails, type CallerType, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type EventType, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, type PluginManifest, PluginNotFoundError, type PluginPackage, type ResourceEvent, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TelemetryService, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };
+export { ActionNotFoundError, type ActionSchema, type CallEventDetails, type CallerType, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type EventType, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type ParamDiagnostic, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, type PluginManifest, PluginNotFoundError, type PluginPackage, RequiredParamMissingError, type ResourceEvent, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TelemetryService, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };

package/dist/index.d.ts

@@ -403,6 +403,16 @@ declare class ActionNotFoundError extends Error {
     readonly actionName: string;
     constructor(pluginKey: string, actionName: string);
 }
+interface ParamDiagnostic {
+    field: string;
+    reason: 'not_provided' | 'empty_value';
+    detail: string;
+}
+declare class RequiredParamMissingError extends Error {
+    readonly capabilityName: string;
+    readonly diagnostics: ParamDiagnostic[];
+    constructor(capabilityName: string, diagnostics: ParamDiagnostic[]);
+}
 interface CapabilityExecutor {
     /**
      * 调用 capability（始终返回 Promise）
@@ -499,6 +509,17 @@ declare class CapabilityService implements OnModuleInit, OnModuleDestroy {
      * 根据 manifest 的 form.refType 决定 formValue 的消费方式
      */
     private loadPluginAndResolveParams;
+    /**
+     * 校验调用方传入的 input 是否满足 paramsSchema.required 约束。
+     *
+     * 注意：校验发生在模板替换之前。paramsSchema.required 声明的是调用方需要传哪些变量
+     * （它们会被 formValue 中的 {{input.xxx}} 引用），不是 resolve 后的 formValue key。
+     *
+     * 诊断原因：
+     *   not_provided — input 中完全没有该字段（key 不存在 / undefined / null），调用方未传
+     *   empty_value  — 调用方传了值但为空（空串/空数组），需要检查数据来源
+     */
+    private validateRequiredParams;
     /**
      * 检查 action 是否为流式
      */
@@ -661,4 +682,4 @@ interface MigrationResponse {
  */
 declare function migrationAdaptor(promise: Promise<unknown>): Promise<MigrationResponse>;
 
-export { ActionNotFoundError, type ActionSchema, type CallEventDetails, type CallerType, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type EventType, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, type PluginManifest, PluginNotFoundError, type PluginPackage, type ResourceEvent, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TelemetryService, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };
+export { ActionNotFoundError, type ActionSchema, type CallEventDetails, type CallerType, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type EventType, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type ParamDiagnostic, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, type PluginManifest, PluginNotFoundError, type PluginPackage, RequiredParamMissingError, type ResourceEvent, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TelemetryService, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };

package/dist/index.js

@@ -668,6 +668,22 @@ var ActionNotFoundError = class extends Error {
     this.actionName = actionName;
   }
 };
+var RequiredParamMissingError = class extends Error {
+  static {
+    __name(this, "RequiredParamMissingError");
+  }
+  capabilityName;
+  diagnostics;
+  constructor(capabilityName, diagnostics) {
+    const lines = diagnostics.map((d) => `  - ${d.field}: ${d.detail}`).join("\n");
+    super(`\u300C${capabilityName}\u300D\u63D2\u4EF6\u8C03\u7528\u5931\u8D25\uFF0C\u4EE5\u4E0B\u5FC5\u586B\u53C2\u6570\u65E0\u6548:
+${lines}
+\u8BF7\u68C0\u67E5\u8C03\u7528\u4EE3\u7801\u4E2D capabilityClient.load(id).call(action, input) \u7684 input \u5BF9\u8C61\uFF0C\u786E\u8BA4\u4E0A\u8FF0\u53C2\u6570\u5DF2\u6B63\u786E\u4F20\u503C\u4E14\u672A\u5728\u4F20\u9012\u94FE\u8DEF\u4E2D\u4E22\u5931\u3002`);
+    this.name = "RequiredParamMissingError";
+    this.capabilityName = capabilityName;
+    this.diagnostics = diagnostics;
+  }
+};
 var CapabilityService = class _CapabilityService {
   static {
     __name(this, "CapabilityService");
@@ -900,6 +916,59 @@ var CapabilityService = class _CapabilityService {
     };
   }
   /**
+  * 校验调用方传入的 input 是否满足 paramsSchema.required 约束。
+  *
+  * 注意：校验发生在模板替换之前。paramsSchema.required 声明的是调用方需要传哪些变量
+  * （它们会被 formValue 中的 {{input.xxx}} 引用），不是 resolve 后的 formValue key。
+  *
+  * 诊断原因：
+  *   not_provided — input 中完全没有该字段（key 不存在 / undefined / null），调用方未传
+  *   empty_value  — 调用方传了值但为空（空串/空数组），需要检查数据来源
+  */
+  validateRequiredParams(input, paramsSchema, capabilityName) {
+    if (!paramsSchema?.required?.length || !paramsSchema.properties) {
+      return;
+    }
+    if (typeof input !== "object" || input === null) {
+      return;
+    }
+    const params = input;
+    const diagnostics = [];
+    for (const fieldName of paramsSchema.required) {
+      const fieldSchema = paramsSchema.properties[fieldName];
+      if (!fieldSchema) continue;
+      const value = params[fieldName];
+      const schemaType = fieldSchema.type;
+      const desc = fieldSchema.description || fieldName;
+      if (value === void 0 || value === null) {
+        diagnostics.push({
+          field: fieldName,
+          reason: "not_provided",
+          detail: `\u300C${desc}\u300D\u672A\u4F20\u503C\uFF0C\u8C03\u7528\u65B9\u7684 input \u4E2D\u7F3A\u5C11\u300C${fieldName}\u300D\u5B57\u6BB5\u3002\u8BF7\u68C0\u67E5 capabilityClient.load(id).call(action, { ... }) \u4E2D\u662F\u5426\u4F20\u5165\u4E86\u8BE5\u53C2\u6570\uFF0C\u4EE5\u53CA\u6570\u636E\u5728\u7EC4\u4EF6\u4F20\u9012\u94FE\u8DEF\u4E2D\u662F\u5426\u4E22\u5931\uFF08\u5982 state \u672A\u66F4\u65B0\u3001props \u672A\u900F\u4F20\u7B49\uFF09\u3002`
+        });
+        continue;
+      }
+      if (schemaType === "array") {
+        if (Array.isArray(value) && value.length === 0) {
+          diagnostics.push({
+            field: fieldName,
+            reason: "empty_value",
+            detail: `\u300C${desc}\u300D\u4F20\u5165\u4E86\u7A7A\u6570\u7EC4 []\uFF0C\u8BE5\u5B57\u6BB5\u4E3A\u5FC5\u586B\u3002\u8BF7\u786E\u8BA4\u6570\u636E\u6765\u6E90\u662F\u5426\u6B63\u786E\uFF0C\u4F8B\u5982\uFF1A\u5217\u8868\u63A5\u53E3\u662F\u5426\u8FD4\u56DE\u4E86\u6570\u636E\u3001\u6587\u4EF6/\u56FE\u7247\u662F\u5426\u5DF2\u6210\u529F\u4E0A\u4F20\u3002`
+          });
+        }
+      } else if (typeof value === "string" && value === "") {
+        diagnostics.push({
+          field: fieldName,
+          reason: "empty_value",
+          detail: `\u300C${desc}\u300D\u4F20\u5165\u4E86\u7A7A\u5B57\u7B26\u4E32\uFF0C\u8BE5\u5B57\u6BB5\u4E3A\u5FC5\u586B\u3002\u8BF7\u786E\u8BA4\u6570\u636E\u6765\u6E90\u662F\u5426\u6B63\u786E\uFF0C\u4F8B\u5982\uFF1A\u8868\u5355\u5B57\u6BB5\u662F\u5426\u5DF2\u586B\u5199\u3001\u53D8\u91CF\u662F\u5426\u5DF2\u8D4B\u503C\u3002`
+        });
+      }
+    }
+    if (diagnostics.length > 0) {
+      throw new RequiredParamMissingError(capabilityName, diagnostics);
+    }
+  }
+  /**
   * 检查 action 是否为流式
   */
   async checkIsStream(config, actionName) {
@@ -923,6 +992,7 @@ var CapabilityService = class _CapabilityService {
     };
     let isStream = false;
     try {
+      this.validateRequiredParams(input, config.paramsSchema, config.name);
       const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
@@ -983,6 +1053,7 @@ var CapabilityService = class _CapabilityService {
     };
     const chunks = [];
     try {
+      this.validateRequiredParams(input, config.paramsSchema, config.name);
       const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
@@ -1043,6 +1114,7 @@ var CapabilityService = class _CapabilityService {
     };
     const chunks = [];
     try {
+      this.validateRequiredParams(input, config.paramsSchema, config.name);
       const { pluginInstance, resolvedParams } = await this.loadPluginAndResolveParams(config, input);
       if (!pluginInstance.hasAction(actionName)) {
         throw new ActionNotFoundError(config.pluginKey, actionName);
@@ -1904,6 +1976,7 @@ export {
   PluginLoadError,
   PluginLoaderService,
   PluginNotFoundError,
+  RequiredParamMissingError,
   TelemetryService,
   TemplateEngineService,
   WebhookController,