Developer
0a9588abb7
- Add pagination support to findAll (page, limit query params) - Add findByTemplateId method to service - Add GET /by-template/:templateId endpoint to controller - Service already includes CRUD for QuestionBank and QuestionBankItem
956 lines
28 KiB
Markdown
956 lines
28 KiB
Markdown
# Feishu Bot Integration Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Enable Feishu (飞书) bot integration as a standalone **Plugin** that users can manage via the system's "Plugins" menu. This allows users to bind bots, interact with RAG, and access assessment features in a modular, plug-and-play fashion.
|
|
|
|
**Architecture:** Implement the integration as a pluggable `FeishuModule`. It acts as a bridge between Feishu Open Platform and AuraK's core services. The plugin is managed through the new `/plugins` workspace, isolating its UI and backend logic from the core system.
|
|
|
|
**Tech Stack:**
|
|
- NestJS (existing)
|
|
- Feishu Open Platform APIs (im/v1/messages, auth/v3/tenant_access_token)
|
|
- Event subscription (Webhooks)
|
|
- Existing: ChatService, AssessmentService, JWT Auth
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
│ Feishu User│─────▶│ Feishu Server│─────▶│ AuraK API │
|
|
│ (User A) │◀─────│ Webhook │◀─────│ /feishu/* │
|
|
└─────────────┘ └──────────────┘ └─────────────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ FeishuModule│
|
|
│ - Bot Entity│
|
|
│ - Message │
|
|
│ - Events │
|
|
└─────────────┘
|
|
│
|
|
┌───────────────────────┼───────────────────────┐
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ ChatService │ │AssessmentSvc│ │ PluginsSvc │
|
|
│ (RAG Q&A) │ │ (评测对话) │ │ (插件状态管理)│
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
```
|
|
|
|
**Plugin Isolation Strategy:**
|
|
- **Backend**: `FeishuModule` is a standalone NestJS module. It handles its own database entities and webhook logic.
|
|
- **Frontend**: Integrated as a sub-view within `/plugins`. When the Feishu plugin is "enabled", its configuration UI is rendered.
|
|
- **Decoupling**: Communicates with core services via standard service calls or an event-subscriber pattern.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
|
|
### New Files to Create
|
|
|
|
```
|
|
server/src/
|
|
├── feishu/
|
|
│ ├── feishu.module.ts # Module definition
|
|
│ ├── feishu.controller.ts # Webhook endpoints
|
|
│ ├── feishu.service.ts # Business logic
|
|
│ ├── feishu.gateway.ts # Event handling (optional)
|
|
│ ├── entities/
|
|
│ │ └── feishu-bot.entity.ts # Bot configuration entity
|
|
│ ├── dto/
|
|
│ │ ├── create-bot.dto.ts # Create bot DTO
|
|
│ │ ├── bind-bot.dto.ts # Bind bot DTO
|
|
│ │ └── feishu-webhook.dto.ts # Webhook event DTO
|
|
│ └── interfaces/
|
|
│ └── feishu.interface.ts # TypeScript interfaces
|
|
```
|
|
|
|
### Existing Files to Modify
|
|
|
|
```
|
|
server/src/
|
|
├── app.module.ts # Import FeishuModule
|
|
├── user/
|
|
│ └── user.entity.ts # Add one-to-many relation to FeishuBot
|
|
├── user/user.service.ts # Add methods to get/set Feishu binding
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 1: Entity and DTO Definitions
|
|
|
|
### Task 1.1: Create FeishuBot Entity
|
|
|
|
**Files:**
|
|
- Create: `server/src/feishu/entities/feishu-bot.entity.ts`
|
|
|
|
- [ ] **Step 1: Create the FeishuBot entity file**
|
|
|
|
```typescript
|
|
import {
|
|
Entity,
|
|
PrimaryGeneratedColumn,
|
|
Column,
|
|
CreateDateColumn,
|
|
UpdateDateColumn,
|
|
ManyToOne,
|
|
JoinColumn,
|
|
} from 'typeorm';
|
|
import { User } from '../../user/user.entity';
|
|
|
|
@Entity('feishu_bots')
|
|
export class FeishuBot {
|
|
@PrimaryGeneratedColumn('uuid')
|
|
id: string;
|
|
|
|
@Column({ name: 'user_id' })
|
|
userId: string; // Plugin manages its own relationship to the core User
|
|
|
|
@ManyToOne(() => User)
|
|
@JoinColumn({ name: 'user_id' })
|
|
user: User;
|
|
|
|
@Column({ name: 'app_id', length: 64 })
|
|
appId: string;
|
|
// ... (rest of the fields as defined previously)
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Decoupled Relation**
|
|
Instead of modifying the core `User` entity directly, the `FeishuBot` entity maintains its own reference to `User`. This keeps the core system clean and allows the plugin to be purely optional.
|
|
|
|
|
|
- [ ] **Step 3: Create DTOs**
|
|
|
|
Create: `server/src/feishu/dto/create-bot.dto.ts`
|
|
```typescript
|
|
import { IsString, IsNotEmpty, IsOptional, IsBoolean } from 'class-validator';
|
|
|
|
export class CreateFeishuBotDto {
|
|
@IsString()
|
|
@IsNotEmpty()
|
|
appId: string;
|
|
|
|
@IsString()
|
|
@IsNotEmpty()
|
|
appSecret: string;
|
|
|
|
@IsString()
|
|
@IsOptional()
|
|
verificationToken?: string;
|
|
|
|
@IsString()
|
|
@IsOptional()
|
|
encryptKey?: string;
|
|
|
|
@IsString()
|
|
@IsOptional()
|
|
botName?: string;
|
|
|
|
@IsBoolean()
|
|
@IsOptional()
|
|
enabled?: boolean;
|
|
}
|
|
```
|
|
|
|
Create: `server/src/feishu/dto/bind-bot.dto.ts`
|
|
```typescript
|
|
import { IsString, IsNotEmpty, IsUUID } from 'class-validator';
|
|
|
|
export class BindFeishuBotDto {
|
|
@IsUUID()
|
|
@IsNotEmpty()
|
|
botId: string;
|
|
|
|
@IsString()
|
|
@IsNotEmpty()
|
|
verificationCode?: string; // Optional: 用于验证绑定关系
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 2: Core Service Implementation
|
|
|
|
### Task 2.1: Create Feishu Service
|
|
|
|
**Files:**
|
|
- Create: `server/src/feishu/feishu.service.ts`
|
|
|
|
- [ ] **Step 1: Implement FeishuService with token management and message sending**
|
|
|
|
```typescript
|
|
import { Injectable, Logger } from '@nestjs/common';
|
|
import { InjectRepository } from '@nestjs/typeorm';
|
|
import { Repository } from 'typeorm';
|
|
import { ConfigService } from '@nestjs/config';
|
|
import { HttpService } from '@nestjs/axios';
|
|
import { FeishuBot } from './entities/feishu-bot.entity';
|
|
import { CreateFeishuBotDto } from './dto/create-bot.dto';
|
|
|
|
@Injectable()
|
|
export class FeishuService {
|
|
private readonly logger = new Logger(FeishuService.name);
|
|
private readonly feishuApiBase = 'https://open.feishu.cn/open-apis';
|
|
|
|
constructor(
|
|
@InjectRepository(FeishuBot)
|
|
private botRepository: Repository<FeishuBot>,
|
|
private httpService: HttpService,
|
|
private configService: ConfigService,
|
|
) {}
|
|
|
|
/**
|
|
* Create or update a Feishu bot for a user
|
|
*/
|
|
async createBot(userId: string, dto: CreateFeishuBotDto): Promise<FeishuBot> {
|
|
// Check if bot already exists for this user with same appId
|
|
const existing = await this.botRepository.findOne({
|
|
where: { userId, appId: dto.appId },
|
|
});
|
|
|
|
if (existing) {
|
|
// Update existing bot
|
|
Object.assign(existing, dto);
|
|
return this.botRepository.save(existing);
|
|
}
|
|
|
|
// Create new bot
|
|
const bot = this.botRepository.create({
|
|
userId,
|
|
...dto,
|
|
});
|
|
return this.botRepository.save(bot);
|
|
}
|
|
|
|
/**
|
|
* Get all bots for a user
|
|
*/
|
|
async getUserBots(userId: string): Promise<FeishuBot[]> {
|
|
return this.botRepository.find({ where: { userId } });
|
|
}
|
|
|
|
/**
|
|
* Get bot by ID
|
|
*/
|
|
async getBotById(botId: string): Promise<FeishuBot | null> {
|
|
return this.botRepository.findOne({ where: { id: botId } });
|
|
}
|
|
|
|
/**
|
|
* Get bot by appId
|
|
*/
|
|
async getBotByAppId(appId: string): Promise<FeishuBot | null> {
|
|
return this.botRepository.findOne({ where: { appId } });
|
|
}
|
|
|
|
/**
|
|
* Get or refresh tenant_access_token
|
|
*/
|
|
async getValidToken(bot: FeishuBot): Promise<string> {
|
|
// Check if token is still valid (expire in 2 hours, refresh at 1.5 hours)
|
|
if (
|
|
bot.tokenExpiresAt &&
|
|
bot.tenantAccessToken &&
|
|
new Date(bot.tokenExpiresAt) > new Date(Date.now() + 30 * 60 * 1000)
|
|
) {
|
|
return bot.tenantAccessToken;
|
|
}
|
|
|
|
// Refresh token
|
|
const response = await this.httpService
|
|
.post(`${this.feishuApiBase}/auth/v3/tenant_access_token/internal`, {
|
|
app_id: bot.appId,
|
|
app_secret: bot.appSecret,
|
|
})
|
|
.toPromise();
|
|
|
|
if (response.data.code !== 0) {
|
|
throw new Error(`Failed to get token: ${response.data.msg}`);
|
|
}
|
|
|
|
const { tenant_access_token, expire } = response.data;
|
|
|
|
// Update bot with new token
|
|
bot.tenantAccessToken = tenant_access_token;
|
|
bot.tokenExpiresAt = new Date(Date.now() + expire * 1000);
|
|
await this.botRepository.save(bot);
|
|
|
|
return tenant_access_token;
|
|
}
|
|
|
|
/**
|
|
* Send message to Feishu user
|
|
*/
|
|
async sendMessage(
|
|
bot: FeishuBot,
|
|
receiveIdType: 'open_id' | 'user_id' | 'union_id' | 'chat_id',
|
|
receiveId: string,
|
|
messageType: 'text' | 'interactive' | 'post',
|
|
content: any,
|
|
): Promise<string> {
|
|
const token = await this.getValidToken(bot);
|
|
|
|
const response = await this.httpService
|
|
.post(
|
|
`${this.feishuApiBase}/im/v1/messages?receive_id_type=${receiveIdType}`,
|
|
{
|
|
receive_id: receiveId,
|
|
msg_type: messageType,
|
|
content: JSON.stringify(content),
|
|
},
|
|
{
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
},
|
|
},
|
|
)
|
|
.toPromise();
|
|
|
|
if (response.data.code !== 0) {
|
|
throw new Error(`Failed to send message: ${response.data.msg}`);
|
|
}
|
|
|
|
return response.data.data.message_id;
|
|
}
|
|
|
|
/**
|
|
* Send text message (convenience method)
|
|
*/
|
|
async sendTextMessage(
|
|
bot: FeishuBot,
|
|
receiveIdType: 'open_id' | 'user_id' | 'chat_id',
|
|
receiveId: string,
|
|
text: string,
|
|
): Promise<string> {
|
|
return this.sendMessage(bot, receiveIdType, receiveId, 'text', { text });
|
|
}
|
|
|
|
/**
|
|
* Reply to a message
|
|
*/
|
|
async replyMessage(
|
|
bot: FeishuBot,
|
|
messageId: string,
|
|
messageType: 'text' | 'interactive' | 'post',
|
|
content: any,
|
|
): Promise<string> {
|
|
const token = await this.getValidToken(bot);
|
|
|
|
const response = await this.httpService
|
|
.post(
|
|
`${this.feishuApiBase}/im/v1/messages/${messageId}/reply`,
|
|
{
|
|
msg_type: messageType,
|
|
content: JSON.stringify(content),
|
|
},
|
|
{
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
},
|
|
},
|
|
)
|
|
.toPromise();
|
|
|
|
if (response.data.code !== 0) {
|
|
throw new Error(`Failed to reply message: ${response.data.msg}`);
|
|
}
|
|
|
|
return response.data.data.message_id;
|
|
}
|
|
|
|
/**
|
|
* Upload image for sending
|
|
*/
|
|
async uploadImage(
|
|
bot: FeishuBot,
|
|
imageType: 'message' | 'avatar',
|
|
image: Buffer,
|
|
imageName: string,
|
|
): Promise<string> {
|
|
const token = await this.getValidToken(bot);
|
|
|
|
const FormData = require('form-data');
|
|
const form = new FormData();
|
|
form.append('image_type', imageType);
|
|
form.append('image', image, { filename: imageName });
|
|
|
|
const response = await this.httpService
|
|
.post(`${this.feishuApiBase}/im/v1/images`, form, {
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
...form.getHeaders(),
|
|
},
|
|
})
|
|
.toPromise();
|
|
|
|
if (response.data.code !== 0) {
|
|
throw new Error(`Failed to upload image: ${response.data.msg}`);
|
|
}
|
|
|
|
return response.data.data.image_key;
|
|
}
|
|
|
|
/**
|
|
* Delete bot
|
|
*/
|
|
async deleteBot(botId: string): Promise<void> {
|
|
await this.botRepository.delete(botId);
|
|
}
|
|
|
|
/**
|
|
* Enable/disable bot
|
|
*/
|
|
async setBotEnabled(botId: string, enabled: boolean): Promise<FeishuBot> {
|
|
const bot = await this.botRepository.findOne({ where: { id: botId } });
|
|
if (!bot) {
|
|
throw new Error('Bot not found');
|
|
}
|
|
bot.enabled = enabled;
|
|
return this.botRepository.save(bot);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 3: Controller and Webhook Endpoints
|
|
|
|
### Task 3.1: Create Feishu Controller
|
|
|
|
**Files:**
|
|
- Create: `server/src/feishu/feishu.controller.ts`
|
|
|
|
- [ ] **Step 1: Implement webhook endpoints**
|
|
|
|
```typescript
|
|
import {
|
|
Controller,
|
|
Post,
|
|
Get,
|
|
Delete,
|
|
Body,
|
|
Param,
|
|
Query,
|
|
Headers,
|
|
UseGuards,
|
|
Request,
|
|
RawBodyRequest,
|
|
Req,
|
|
} from '@nestjs/common';
|
|
import { Request as ExpressRequest } from 'express';
|
|
import { FeishuService } from './feishu.service';
|
|
import { CreateFeishuBotDto } from './dto/create-bot.dto';
|
|
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
|
|
import { CreateSignatureDto, VerifyWebhookDto } from './dto/webhook.dto';
|
|
|
|
@Controller('feishu')
|
|
export class FeishuController {
|
|
constructor(private readonly feishuService: FeishuService) {}
|
|
|
|
/**
|
|
* GET /feishu/bots - List user's bots
|
|
* Requires JWT auth
|
|
*/
|
|
@Get('bots')
|
|
@UseGuards(JwtAuthGuard)
|
|
async listBots(@Request() req) {
|
|
const bots = await this.feishuService.getUserBots(req.user.id);
|
|
// Mask sensitive data
|
|
return bots.map((bot) => ({
|
|
id: bot.id,
|
|
appId: bot.appId,
|
|
botName: bot.botName,
|
|
enabled: bot.enabled,
|
|
isDefault: bot.isDefault,
|
|
createdAt: bot.createdAt,
|
|
}));
|
|
}
|
|
|
|
/**
|
|
* POST /feishu/bots - Create a new bot
|
|
* Requires JWT auth
|
|
*/
|
|
@Post('bots')
|
|
@UseGuards(JwtAuthGuard)
|
|
async createBot(@Request() req, @Body() dto: CreateFeishuBotDto) {
|
|
const bot = await this.feishuService.createBot(req.user.id, dto);
|
|
return {
|
|
id: bot.id,
|
|
appId: bot.appId,
|
|
botName: bot.botName,
|
|
enabled: bot.enabled,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* DELETE /feishu/bots/:id - Delete a bot
|
|
* Requires JWT auth
|
|
*/
|
|
@Delete('bots/:id')
|
|
@UseGuards(JwtAuthGuard)
|
|
async deleteBot(@Request() req, @Param('id') botId: string) {
|
|
await this.feishuService.deleteBot(botId);
|
|
return { success: true };
|
|
}
|
|
|
|
/**
|
|
* POST /feishu/webhook - Feishu webhook endpoint
|
|
* Public endpoint - no auth required (uses verification token)
|
|
*/
|
|
@Post('webhook')
|
|
async handleWebhook(
|
|
@Body() body: any,
|
|
@Headers('x-xsign') xSign?: string,
|
|
@Headers('x-timESTAMP') xTimestamp?: string,
|
|
) {
|
|
this.logger.log(`Received webhook: ${JSON.stringify(body)}`);
|
|
|
|
const { type, schema, event } = body;
|
|
|
|
// Handle URL verification (飞书首次配置时验证)
|
|
if (type === 'url_verification') {
|
|
return {
|
|
challenge: body.challenge,
|
|
};
|
|
}
|
|
|
|
// Handle event callback
|
|
if (type === 'event_callback') {
|
|
const { event_type, token } = body;
|
|
|
|
// Verify token
|
|
if (token !== body?.verify_token) {
|
|
this.logger.warn('Webhook token verification failed');
|
|
return { success: false };
|
|
}
|
|
|
|
// Handle different event types
|
|
switch (event_type) {
|
|
case 'im.message.p2p_msg_received':
|
|
// Handle private message
|
|
await this.handleP2PMsg(event);
|
|
break;
|
|
|
|
case 'im.message.group_at_msg_received':
|
|
// Handle group @message
|
|
await this.handleGroupMsg(event);
|
|
break;
|
|
|
|
default:
|
|
this.logger.log(`Unhandled event type: ${event_type}`);
|
|
}
|
|
}
|
|
|
|
return { success: true };
|
|
}
|
|
|
|
/**
|
|
* Handle private message
|
|
*/
|
|
private async handleP2PMsg(event: any) {
|
|
const { message } = event;
|
|
const { message_id, chat_id, sender, message_type, body } = message;
|
|
|
|
// Get message content
|
|
const content = JSON.parse(message.content || '{}');
|
|
const text = content.text || '';
|
|
|
|
// Find bot by app_id (from chat or event)
|
|
const openId = sender?.id?.open_id;
|
|
if (!openId) {
|
|
this.logger.warn('No sender open_id found');
|
|
return;
|
|
}
|
|
|
|
// Find user's bot
|
|
const bot = await this.feishuService.getBotByAppId(sender?.sender_id?.app_id);
|
|
if (!bot || !bot.enabled) {
|
|
this.logger.warn('Bot not found or disabled');
|
|
return;
|
|
}
|
|
|
|
// Process message through RAG/Chat service
|
|
await this.processMessage(bot, openId, message_id, text);
|
|
}
|
|
|
|
/**
|
|
* Handle group message (@bot)
|
|
*/
|
|
private async handleGroupMsg(event: any) {
|
|
const { message } = event;
|
|
const { message_id, chat_id, sender, message_type, content } = message;
|
|
|
|
// Check if bot was mentioned
|
|
const msgContent = JSON.parse(content || '{}');
|
|
// Group messages often require specific handling
|
|
|
|
// Similar to P2P but with chat_id context
|
|
await this.handleP2PMsg(event);
|
|
}
|
|
|
|
/**
|
|
* Process message through ChatService
|
|
*/
|
|
private async processMessage(
|
|
bot: any,
|
|
openId: string,
|
|
messageId: string,
|
|
text: string,
|
|
) {
|
|
// TODO: Integrate with ChatService
|
|
// This will be implemented in Chunk 5
|
|
|
|
// For now, echo back (placeholder)
|
|
try {
|
|
await this.feishuService.sendTextMessage(
|
|
bot,
|
|
'open_id',
|
|
openId,
|
|
`Received: ${text}`,
|
|
);
|
|
} catch (error) {
|
|
this.logger.error('Failed to send response', error);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Create webhook DTOs**
|
|
|
|
Create: `server/src/feishu/dto/webhook.dto.ts`
|
|
```typescript
|
|
import { IsString, IsOptional } from 'class-validator';
|
|
|
|
export class CreateSignatureDto {
|
|
@IsString()
|
|
@IsOptional()
|
|
timestamp?: string;
|
|
|
|
@IsString()
|
|
@IsOptional()
|
|
nonce?: string;
|
|
}
|
|
|
|
export class VerifyWebhookDto {
|
|
@IsString()
|
|
token: string;
|
|
|
|
@IsString()
|
|
@IsOptional()
|
|
challenge?: string;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 4: Plugin Registration
|
|
|
|
### Task 4.1: Register Feishu Plugin
|
|
**Note:** This module acts as an optional extension to the AuraK ecosystem.
|
|
|
|
**Files:**
|
|
- Create: `server/src/feishu/feishu.module.ts`
|
|
- Modify: `server/src/app.module.ts`
|
|
|
|
- [ ] **Step 1: Create FeishuModule with isolated exports**
|
|
|
|
|
|
```typescript
|
|
import { Module, forwardRef } from '@nestjs/common';
|
|
import { TypeOrmModule } from '@nestjs/typeorm';
|
|
import { HttpModule } from '@nestjs/axios';
|
|
import { FeishuController } from './feishu.controller';
|
|
import { FeishuService } from './feishu.service';
|
|
import { FeishuBot } from './entities/feishu-bot.entity';
|
|
import { ChatModule } from '../chat/chat.module';
|
|
import { UserModule } from '../user/user.module';
|
|
|
|
@Module({
|
|
imports: [
|
|
TypeOrmModule.forFeature([FeishuBot]),
|
|
HttpModule,
|
|
forwardRef(() => ChatModule),
|
|
forwardRef(() => UserModule),
|
|
],
|
|
controllers: [FeishuController],
|
|
providers: [FeishuService],
|
|
exports: [FeishuService, TypeOrmModule],
|
|
})
|
|
export class FeishuModule {}
|
|
```
|
|
|
|
- [ ] **Step 2: Add FeishuModule to AppModule**
|
|
|
|
Modify: `server/src/app.module.ts`
|
|
|
|
Add import:
|
|
```typescript
|
|
import { FeishuModule } from './feishu/feishu.module';
|
|
```
|
|
|
|
Add to imports array:
|
|
```typescript
|
|
FeishuModule,
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 5: Integration with ChatService
|
|
|
|
### Task 5.1: Connect Feishu messages to ChatService
|
|
|
|
**Files:**
|
|
- Modify: `server/src/feishu/feishu.controller.ts`
|
|
- Modify: `server/src/feishu/feishu.service.ts`
|
|
|
|
- [ ] **Step 1: Extend FeishuService to handle chat integration**
|
|
|
|
Add to FeishuService:
|
|
```typescript
|
|
// Import these
|
|
import { ChatService } from '../chat/chat.service';
|
|
import { ModelConfigService } from '../model-config/model-config.service';
|
|
import { TenantService } from '../tenant/tenant.service';
|
|
import { UserService } from '../user/user.service';
|
|
import { ModelType } from '../types';
|
|
|
|
// Add to constructor
|
|
constructor(
|
|
// ... existing
|
|
private chatService: ChatService,
|
|
private modelConfigService: ModelConfigService,
|
|
private tenantService: TenantService,
|
|
private userService: UserService,
|
|
) {}
|
|
|
|
/**
|
|
* Process chat message through RAG
|
|
*/
|
|
async processChatMessage(
|
|
bot: FeishuBot,
|
|
openId: string,
|
|
messageId: string,
|
|
userMessage: string,
|
|
): Promise<void> {
|
|
// Get user by Feishu open_id mapping (future: map table)
|
|
// For now, use userId from bot
|
|
const userId = bot.userId;
|
|
|
|
// Get user's tenant
|
|
const user = await this.userService.findById(userId);
|
|
const tenantId = user?.tenantId || 'default';
|
|
|
|
// Get user's LLM config
|
|
const llmModel = await this.modelConfigService.findDefaultByType(
|
|
tenantId,
|
|
ModelType.LLM,
|
|
);
|
|
|
|
if (!llmModel) {
|
|
await this.sendTextMessage(bot, 'open_id', openId, '请先配置 LLM 模型');
|
|
return;
|
|
}
|
|
|
|
// Send "thinking" message
|
|
await this.sendTextMessage(bot, 'open_id', openId, '正在思考...');
|
|
|
|
// Stream chat response
|
|
const stream = this.chatService.streamChat(
|
|
userMessage,
|
|
[], // No history for now (future: persist per openId)
|
|
userId,
|
|
llmModel as any,
|
|
user?.userSetting?.language || 'zh',
|
|
undefined, // selectedEmbeddingId
|
|
undefined, // selectedGroups
|
|
undefined, // selectedFiles
|
|
undefined, // historyId
|
|
false, // enableRerank
|
|
undefined, // selectedRerankId
|
|
undefined, // temperature
|
|
undefined, // maxTokens
|
|
10, // topK
|
|
0.7, // similarityThreshold
|
|
undefined, // rerankSimilarityThreshold
|
|
undefined, // enableQueryExpansion
|
|
undefined, // enableHyDE
|
|
tenantId,
|
|
);
|
|
|
|
let fullResponse = '';
|
|
for await (const chunk of stream) {
|
|
if (chunk.type === 'content') {
|
|
fullResponse += chunk.data;
|
|
// Could send incrementally, but Feishu prefers complete messages
|
|
}
|
|
}
|
|
|
|
// Send final response
|
|
// Truncate if too long (Feishu has limits)
|
|
const maxLength = 5000;
|
|
const finalMessage = fullResponse.length > maxLength
|
|
? fullResponse.substring(0, maxLength) + '...(内容过长)'
|
|
: fullResponse;
|
|
|
|
await this.sendTextMessage(bot, 'open_id', openId, finalMessage);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Update controller to use chat integration**
|
|
|
|
Modify the `processMessage` method in FeishuController to call `feishuService.processChatMessage()`:
|
|
|
|
```typescript
|
|
private async processMessage(
|
|
bot: any,
|
|
openId: string,
|
|
messageId: string,
|
|
text: string,
|
|
) {
|
|
try {
|
|
await this.feishuService.processChatMessage(bot, openId, messageId, text);
|
|
} catch (error) {
|
|
this.logger.error('Failed to process message', error);
|
|
try {
|
|
await this.feishuService.sendTextMessage(
|
|
bot,
|
|
'open_id',
|
|
openId,
|
|
'抱歉，处理消息时发生错误，请稍后重试。',
|
|
);
|
|
} catch (sendError) {
|
|
this.logger.error('Failed to send error message', sendError);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Chunk 6: Frontend Integration (Optional)
|
|
|
|
### Task 6.1: Add Feishu sub-view to Plugins
|
|
**Files:**
|
|
- Create: `web/src/pages/Plugins/FeishuPlugin.tsx`
|
|
- Modify: `web/src/components/views/PluginsView.tsx`
|
|
- Modify: `web/src/services/api.ts`
|
|
|
|
- [ ] **Step 1: Create the Plugin Configuration UI**
|
|
This view should match the design of other plugin cards in the /plugins page but provide a detailed setup guide and form for:
|
|
- App ID / App Secret
|
|
- Webhook URL (Read-only generated URL)
|
|
- Verification Token & Encrypt Key
|
|
|
|
- [ ] **Step 2: Register the Plugin in PluginsView**
|
|
Modify the main plugins listing to include "Feishu Bot" as an available (or installed) plugin.
|
|
|
|
Modify: `web/src/services/api.ts`
|
|
```typescript
|
|
// Add Feishu API calls
|
|
export const feishuApi = {
|
|
listBots: () => api.get('/feishu/bots'),
|
|
createBot: (data: CreateBotDto) => api.post('/feishu/bots', data),
|
|
deleteBot: (botId: string) => api.delete(`/feishu/bots/${botId}`),
|
|
};
|
|
```
|
|
|
|
- [ ] **Step 3: Implementation of PluginsView.tsx**
|
|
If `web/src/components/views/PluginsView.tsx` does not exist, create a generic plugin management layout that can host the Feishu configuration.
|
|
|
|
**Layout Requirements:**
|
|
- Grid of available plugins.
|
|
- Status toggle (Enabled/Disabled).
|
|
- Detail/Configuration view for active plugins.
|
|
|
|
|
|
## Testing Strategy
|
|
|
|
### Unit Tests
|
|
|
|
- `feishu.service.spec.ts` - Test token refresh, message sending
|
|
- `feishu.controller.spec.ts` - Test webhook endpoints
|
|
|
|
### Integration Tests
|
|
|
|
- Test full flow: Feishu message → Webhook → ChatService → Response
|
|
|
|
### Manual Testing
|
|
|
|
1. Create Feishu app in 开放平台
|
|
2. Configure webhook URL (use ngrok for local)
|
|
3. Subscribe to message events
|
|
4. Send message to bot
|
|
5. Verify RAG response
|
|
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
1. **Token Storage**: Encrypt `app_secret` and `encrypt_key` before storing in DB.
|
|
2. **Webhook Verification**:
|
|
- Verify `verify_token` for simplicity.
|
|
- **Recommended**: Validate `X-Lark-Signature` using `encrypt_key` to ensure authenticity.
|
|
|
|
3. **Rate Limiting**: Implement a message queue (e.g., BullMQ) for outbound messages to respect Feishu's global and per-bot rate limits.
|
|
4. **User Privacy**: Implement an opt-in flow for group chats to ensure the bot only processes messages when explicitly allowed or mentioned.
|
|
|
|
---
|
|
|
|
## Advanced Optimizations (Recommended)
|
|
|
|
### 1. Webhook Performance & Reliability
|
|
- **Immediate Response**: Feishu requires a response within 3 seconds. The RAG process can take 10s+.
|
|
- **Optimization**: The `handleWebhook` should only validate the request and push the event to an internal queue, returning `200 OK` immediately. A background worker then processes the RAG logic and sends the response.
|
|
- **Deduplication**: Use the `event_id` in the webhook payload to ignore duplicate retries from Feishu.
|
|
|
|
### 2. UX: Managed "Thinking" State
|
|
- **Simulated Streaming**: Since Feishu doesn't support SSE, send an initial "Thinking..." message and use the `PATCH /im/v1/messages/:message_id` API to update the message content every few seconds as chunks arrive.
|
|
- **Interactive Cards**: Use [Message Cards](https://open.feishu.cn/document/common-capabilities/message-card/message-card-overview) instead of plain text for:
|
|
- Showing search citations with clickable links.
|
|
- Providing "Regenerate" or "Clear Context" buttons.
|
|
- Displaying assessment results with formatting (tables/charts).
|
|
|
|
### 3. Context & History Management
|
|
- **OpenID Mapping**: Maintain a mapping between Feishu `open_id` and AuraK `userId` to persist chat history across different devices/platforms.
|
|
- **Thread Support**: Use Feishu's `root_id` and `parent_id` to allow users to ask follow-up questions within a thread, keeping the UI clean.
|
|
|
|
### 4. Multi-modal Support
|
|
- **File Ingestion**: Support `im.message.file_received` events. If a user sends a PDF/Docx to the bot, automatically import it into a "Feishu Uploads" group for immediate RAG context.
|
|
- **Image Analysis**: Use the `VisionService` to handle images sent via Feishu.
|
|
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Assessment Integration**: Bind assessment sessions to Feishu conversations using interactive card forms.
|
|
2. **Rich Responses**: Use Feishu interactive cards for better visual presentation.
|
|
3. **Multi-bot Support**: Users can have multiple bots for different specialized tasks.
|
|
4. **Group Chats**: Support bot in group chats with specific @mention logic and moderation.
|
|
5. **Voice Messages**: Handle voice message transcription via Feishu's audio-to-text API for accessibility.
|
|
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
- `@nestjs/axios` - For HTTP requests to Feishu API
|
|
- `form-data` - For file/image uploads
|
|
- Optional: `crypto` (built-in) - For signature verification
|
|
|
|
---
|
|
|
|
## Reference Links
|
|
|
|
- [飞书开放平台 - 机器人文档](https://open.feishu.cn/document/faq/bot)
|
|
- [飞书事件订阅](https://open.feishu.cn/document/server-docs/event-subscription-guide/overview)
|
|
- [消息发送 API](https://open.feishu.cn/document/server-docs/im-v1/message-content-description)
|
|
- [获取 tenant_access_token](https://open.feishu.cn/document/server-docs/authentication-management/access-token)
|
|
|
|
---
|
|
|
|
> **Plan created:** 2026-03-16
|
|
> **Based on:** Feishu integration analysis
|