FeiShu 项目文档

项目概述

这是一个用于与 FeiShu（飞书）集成的工具包，支持多种功能模块开发。

安装使用

安装依赖

npm install @feishu/abc123

使用指南

初始化配置

import { FeiShuClient } from '@feishu/core';

const config: ClientConfig = {
  appId: 'your_app_id',
  appSecret: 'your_app_secret'
};

const client = new FeiShuClient(config);

功能模块

消息发送

发送文本消息

await client.sendMessage('open_chat_id', 'hello world');

发送卡片消息

const card = {
  type: 'message_card',
  content: [{
    type: 'text',
    text: '卡片内容'
  }]
};

await client.sendCardMessage('open_chat_id', card);

错误处理

所有 API 请求错误将通过 FeiShuApiError 类进行包装：

try {
  // 执行 API 操作
} catch (error) {
  if (error instanceof FeiShuApiError) {
    // 处理特定的 API 错误
    console.error(`飞书 API 错误 (${error.code}): ${error.message}`);
  } else {
    // 处理通用错误
    console.error('意外错误:', error);
  }
  // 转换为用户友好的消息
  throw new FeiShuApiError('操作失败', { cause: error });
}

扩展指南

添加新功能步骤

1. 创建客户端类

   在 src/client/feature/ 目录下创建新客户端类：

   // src/client/feature/feature-client.ts
   export class FeatureClient extends ApiClient {
     async getFeatureData(id: string): Promise<FeatureData> {
       return this.request<FeatureResponse>('/feature/get', { id });
     }
   }
   

2. 创建服务类

   在 src/services/feature/ 目录下创建新服务类：

   // src/services/feature/feature-service.ts
   export class FeatureService {
     private client: FeatureClient;
     
     constructor(config: ApiClientConfig) {
       this.client = new FeatureClient(config);
     }
     
     async getFeature(id: string): Promise<Feature> {
       try {
         const data = await this.client.getFeatureData(id);
         return this.transformData(data);
       } catch (error) {
         handleError(error);
       }
     }
   }
   

3. 注册服务

   在 src/services/index.ts 中导出新服务：

   // src/services/index.ts
   export { FeatureService } from './feature/feature-service';
   

4. 创建 MCP 工具

   在 src/server/tools/feature-tools.ts 中创建工具函数：

   // src/server/tools/feature-tools.ts
   export function createFeatureTool() {
     return {
       getFeature: async (id: string) => {
         const service = new FeatureService({ /* 配置 */ });
         return await service.getFeature(id);
       }
     };
   }
   

5. 使用新功能

   import { createFeatureTool } from './tools/feature-tools';
   
   const tool = createFeatureTool();
   await tool.getFeature('123');
   

贡献指南

提交代码规范

请遵循以下提交规范：

1. 每个提交必须有明确的提交信息
2. 保持代码格式统一
3. 提交前通过所有测试用例

创建新功能模块

1. 在 src/components/ 下创建新组件
2. 实现组件逻辑
3. 在示例页面中集成组件

错误处理

请参考错误处理文档：错误处理指南

项目结构

project/
├── src/
│   ├── client/
│   │   └── feature/
│   │       └── feature-client.ts
│   └── services/
│       └── feature/
│           └── feature-service.ts
└── tools/
    └── feature-tools.ts

许可证

本项目遵循 MIT 协议。

以上是该项目的完整文档指南，涵盖了安装、使用、开发和错误处理等各个方面。