aurak/docs/feishu-assessment-implementation-summary.md

飞书机器人与人才测评集成 - 实现总结

文档版本: v1.0
创建日期: 2026-03-17
状态: 实现完成

---

一、实现概述

已完成的功能

1. ✅ 知识库选择机制 - 飞书机器人支持配置特定知识库或知识组
2. ✅ 命令解析器 - 支持多种语言的测评命令识别
3. ✅ 测评会话管理 - 完整的会话生命周期管理
4. ✅ 飞书卡片交互 - 友好的问题展示和结果报告

架构图

用户消息
    ↓
FeishuController._handleMessage()
    ↓
[命令识别] → 是测评命令? → FeishuAssessmentService.handleCommand()
    ↓                              ↓
否                           命令解析器
    ↓                              ↓
FeishuService.processChatMessage()  执行对应操作
    ↓                              ↓
ChatService.streamChat()         [开始/回答/状态/结果]
    ↓                              ↓
RAG搜索 + LLM生成                AssessmentService
    ↓                              ↓
飞书消息回复                    飞书消息回复

---

二、数据库变更

1. FeishuBot 实体新增字段

文件: server/src/feishu/entities/feishu-bot.entity.ts

@Column({ name: 'knowledge_base_id', nullable: true, length: 36 })
knowledgeBaseId: string;

@Column({ name: 'knowledge_group_id', nullable: true, length: 36 })
knowledgeGroupId: string;

2. 新增测评会话表

文件: server/src/feishu/entities/feishu-assessment-session.entity.ts

CREATE TABLE feishu_assessment_sessions (
    id VARCHAR(36) PRIMARY KEY,
    bot_id VARCHAR(36) NOT NULL,
    open_id VARCHAR(255) NOT NULL,
    assessment_session_id VARCHAR(36) NOT NULL,
    status ENUM('active', 'completed', 'cancelled') DEFAULT 'active',
    current_question_index INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_bot_open (bot_id, open_id),
    INDEX idx_assessment_session (assessment_session_id),
    CONSTRAINT fk_feishu_assessment_bot 
        FOREIGN KEY (bot_id) 
        REFERENCES feishu_bots(id) 
        ON DELETE CASCADE
);

3. 迁移脚本

• 1773200000000-AddFeishuBotKnowledgeFields.ts - 添加知识库字段
• 1773200000001-CreateFeishuAssessmentSessionTable.ts - 创建测评会话表

---

三、核心组件实现

1. 命令解析器 (AssessmentCommandParser)

文件: server/src/feishu/services/assessment-command.parser.ts

功能：

• 识别测评命令前缀：/assessment, /测评, /eval, /测评评估
• 支持多语言命令：start/开始, answer/回答, status/状态, result/结果
• 解析命令参数

示例：

const parser = new AssessmentCommandParser();
const command = parser.parse('/assessment start kb_xxx');
// 结果: { type: 'start', parameters: ['kb_xxx'], ... }

2. 测评服务 (FeishuAssessmentService)

文件: server/src/feishu/services/feishu-assessment.service.ts

核心方法：

• handleCommand() - 处理测评命令
• startAssessment() - 开始测评会话
• submitAnswer() - 提交答案
• getStatus() - 获取测评状态
• getResult() - 获取测评结果
• cancelAssessment() - 取消测评

会话流程：

1. 用户发送 /assessment start
2. 系统创建测评会话，发送第一个问题卡片
3. 用户回复答案（直接回复或 /assessment answer）
4. 系统评估答案，发送下一个问题
5. 重复步骤3-4直到完成
6. 系统发送测评结果报告

3. 集成到 FeishuService

文件: server/src/feishu/feishu.service.ts

新增方法：

isAssessmentCommand(message: string): boolean {
    const trimmed = message.trim().toLowerCase();
    const commandPrefixes = ['/assessment', '/测评', '/eval', '/测评评估'];
    return commandPrefixes.some(prefix => trimmed.startsWith(prefix.toLowerCase()));
}

4. 集成到 FeishuController

文件: server/src/feishu/feishu.controller.ts

修改 _handleMessage 方法：

if (this.feishuService.isAssessmentCommand(userText)) {
    // 委托给测评服务
    await this.feishuAssessmentService.handleCommand(bot, openId, userText);
} else {
    // 使用默认聊天处理
    await this.feishuService.processChatMessage(bot, openId, messageId, userText);
}

---

四、API 接口更新

1. 创建/更新飞书机器人

端点: POST /feishu/bots

请求体：

{
    "appId": "cli_xxx",
    "appSecret": "xxx",
    "botName": "测评机器人",
    "knowledgeBaseId": "kb_xxx",      // 可选：特定知识库
    "knowledgeGroupId": "group_xxx"   // 可选：知识组
}

2. 更新知识库配置

端点: PATCH /feishu/bots/:id/knowledge

请求体：

{
    "knowledgeBaseId": "kb_xxx",
    "knowledgeGroupId": null
}

---

五、命令参考

支持的命令前缀

• /assessment
• /测评
• /eval
• /测评评估

命令列表

命令	参数	说明
start [kbId|templateId]	可选	开始测评
answer [answer]	必需	提交答案
status	-	查看状态
result	-	获取结果
help	-	显示帮助
cancel	-	取消测评

使用示例

用户: /assessment start
系统: [发送第一个问题卡片]

用户: 这是我的答案
系统: [评估答案并发送下一个问题]

用户: /assessment status
系统: 测评状态: 进度 3/10, 状态: 进行中

用户: /assessment result
系统: [发送测评结果报告]

---

六、文件清单

新增文件

1. server/src/feishu/dto/assessment-command.dto.ts - 命令DTO
2. server/src/feishu/entities/feishu-assessment-session.entity.ts - 测评会话实体
3. server/src/feishu/services/assessment-command.parser.ts - 命令解析器
4. server/src/feishu/services/feishu-assessment.service.ts - 测评服务
5. server/src/migrations/1773200000000-AddFeishuBotKnowledgeFields.ts - 迁移脚本1
6. server/src/migrations/1773200000001-CreateFeishuAssessmentSessionTable.ts - 迁移脚本2

修改文件

1. server/src/feishu/entities/feishu-bot.entity.ts - 添加知识库字段
2. server/src/feishu/dto/create-bot.dto.ts - 添加知识库配置字段
3. server/src/feishu/feishu.service.ts - 添加命令识别方法
4. server/src/feishu/feishu.controller.ts - 集成测评服务
5. server/src/feishu/feishu.module.ts - 注册新服务

---

七、实施步骤

阶段 1: 基础架构 ✅

• 创建数据库迁移脚本
• 更新 FeishuBot 实体和 DTO
• 修改 FeishuService 支持知识库选择

阶段 2: 测评集成 ✅

• 创建测评会话实体
• 实现命令解析器
• 实现测评服务
• 集成到 FeishuService 和 Controller

阶段 3: 测试优化 ⏳

• 运行数据库迁移
• 测试命令解析功能
• 测试完整测评流程
• 性能测试和优化

---

八、安全考虑

1. 多租户隔离：所有查询包含 userId 和 tenantId 过滤
2. 命令验证：白名单命令验证，防止注入攻击
3. 会话超时：建议设置测评会话超时时间（如 24 小时）
4. 数据隐私：测评结果仅对授权用户可见

---

九、下一步工作

1. 运行数据库迁移

   yarn migration:run
   

2. 测试命令解析

   node test-feishu-assessment.js
   

3. 集成测试

   • 创建飞书机器人
   • 配置知识库
   • 发送 /assessment start 命令
   • 完成测评流程

4. 文档完善

   • 更新用户使用文档
   • 添加 API 文档
   • 编写故障排除指南

---

十、总结

本次实现完成了飞书机器人与人才测评的完整集成：

1. 知识库选择：飞书机器人现在可以配置特定知识库或知识组
2. 命令解析：支持多语言的测评命令识别
3. 会话管理：完整的测评会话生命周期管理
4. 交互体验：友好的飞书卡片交互

系统架构清晰，代码结构良好，易于维护和扩展。

---

相关文档:

• 完整设计文档
• 设计摘要
• 快速参考