@lark-apaas/client-capability

前端 SDK，用于调用后端能力（Capability）接口。

安装

npm install @lark-apaas/client-capability

概述

本 SDK 提供以下功能：

• 封装 /api/capability/:id HTTP 调用
• 流式调用支持（SSE）
• 统一的错误处理
• 与服务端 API 一致的链式调用风格

快速开始

基础使用

import { capabilityClient } from '@lark-apaas/client-capability';

// 加载能力并调用
const result = await capabilityClient.load('create_feishu_group').call('run', {
  group_name: '项目讨论群',
  members: ['user_001', 'user_002'],
});

console.log(result);

流式调用

用于 LLM 对话等流式输出场景：

import { capabilityClient } from '@lark-apaas/client-capability';

// 泛型参数 T 表示 delta 的类型（插件的 OutputSchema）
const stream = capabilityClient.load('ai_chat').callStream<{ content: string }>('chat', {
  message: 'hello',
});

for await (const chunk of stream) {
  console.log(chunk.content);  // chunk 即为 delta，类型为 { content: string }
}

自定义配置

import { createClient } from '@lark-apaas/client-capability';

const client = createClient({
  // 全局路径前缀（线上环境）
  baseURL: '/spark/a',  // 请求路径: /spark/a/api/capability/xxx
  fetchOptions: {
    credentials: 'include',
    headers: {
      'X-Custom-Header': 'value',
    },
  },
});

const result = await client.load('xxx').call('run', params);

baseURL 配置说明：

| 环境 | baseURL | 实际请求路径 | |-----|---------|-------------| | 本地开发 | ''（默认） | /api/capability/xxx | | 线上环境 | '/spark/a' | /spark/a/api/capability/xxx |

错误处理

import {
  capabilityClient,
  CapabilityNotFoundError,
  ExecutionError
} from '@lark-apaas/client-capability';

try {
  const result = await capabilityClient.load('create_feishu_group').call('run', params);
} catch (error) {
  if (error instanceof CapabilityNotFoundError) {
    console.error('能力不存在:', error.message);
  } else if (error instanceof ExecutionError) {
    console.error('执行失败:', error.message);
  } else {
    throw error;
  }
}

流式调用错误处理

import { capabilityClient, NetworkError, ExecutionError } from '@lark-apaas/client-capability';

try {
  const stream = capabilityClient.load('ai_chat').callStream('chat', { message: 'hello' });
  for await (const chunk of stream) {
    process(chunk);
  }
} catch (error) {
  if (error instanceof NetworkError) {
    console.error('网络中断:', error.message);
  } else if (error instanceof ExecutionError) {
    console.error('执行错误:', error.message);
  }
}

API

CapabilityClient

class CapabilityClient {
  /**
   * 加载能力，返回执行器
   * @param capabilityId - 能力 ID
   * @returns 能力执行器
   */
  load(capabilityId: string): CapabilityExecutor;
}

CapabilityExecutor

interface CapabilityExecutor {
  /**
   * 调用能力
   * @param action - Action 名称
   * @param params - 输入参数
   * @returns Action 执行结果
   */
  call<T = unknown>(
    action: string,
    params?: Record<string, unknown>
  ): Promise<T>;

  /**
   * 流式调用能力
   * @param action - Action 名称
   * @param params - 输入参数
   * @returns AsyncIterable，逐个 yield chunk
   */
  callStream<T = unknown>(
    action: string,
    params?: Record<string, unknown>
  ): AsyncIterable<T>;
}

配置选项

interface CapabilityClientOptions {
  /** 全局路径前缀，默认 ''。例如线上环境可设置为 '/spark/a' */
  baseURL?: string;
  /** 自定义 fetch 配置 */
  fetchOptions?: RequestInit;
}

错误类型

| 错误类型 | 错误码 | 描述 | |---------|--------|------| | CapabilityError | - | 错误基类 | | CapabilityNotFoundError | CAPABILITY_NOT_FOUND | 能力不存在 | | ActionNotFoundError | ACTION_NOT_FOUND | Action 不存在 | | NetworkError | NETWORK_ERROR | 网络错误 | | ExecutionError | EXECUTION_ERROR | 执行错误 |

导出

// 默认客户端实例
export { capabilityClient } from '@lark-apaas/client-capability';

// 创建自定义客户端
export { createClient, CapabilityClient } from '@lark-apaas/client-capability';

// 类型
export type { CapabilityClientOptions, CapabilityExecutor } from '@lark-apaas/client-capability';

// 错误类型
export {
  CapabilityError,
  CapabilityNotFoundError,
  ActionNotFoundError,
  NetworkError,
  ExecutionError,
} from '@lark-apaas/client-capability';

与服务端 API 对比

客户端与服务端使用一致的链式调用风格：

// 客户端
import { capabilityClient } from '@lark-apaas/client-capability';
const result = await capabilityClient.load('xxx').call('run', params);

// 服务端
import { CapabilityService } from '@lark-apaas/nestjs-capability';
const result = await capabilityService.load('xxx').call('run', params);

许可证

MIT