Skip to main content
Glama
cv-cat
by cv-cat

Lark Agentx - 당신의 Feishu AI 어시스턴트 🚀

Python Version Node.js Version

Feishu(Lark) 기반의 AI 에이전트로, 대규모 언어 모델(LLM)이 Feishu를 통해 함수 호출 및 메시지 처리를 수행할 수 있도록 구현되었습니다.

Feishu 봇을 설정할 필요 없이, 당신의 Feishu 계정이 곧 AI 어시스턴트가 됩니다.

함수와 주석만 정의하면, Feishu 봇이 상황에 맞춰 자동으로 호출합니다.

프로젝트 개요 🌟

Lark Agentx는 다음과 같은 기능을 갖춘 현대적인 Python 애플리케이션입니다:

  • 📊 Feishu Protobuf 형식으로 전송되는 Websockets 및 API를 리버스 엔지니어링하여 메시지를 수신하고 기록

  • 🤖 대규모 언어 모델이 호출할 수 있는 사용자 정의 함수 제공

  • 🔄 MCP (Model Context Protocol) 기반의 함수 호출 프레임워크 구현

  • 💾 SQLAlchemy를 사용하여 메시지를 MySQL 데이터베이스에 저장

Related MCP server: Feishu MCP Server

효과 화면🧸

✨ 주요 기능

  • 함수 등록 메커니즘: 간단하고 직관적인 함수 등록 데코레이터

  • 메시지 자동 처리: 수신된 모든 메시지(개인 채팅 및 그룹 채팅) 기록

  • 비동기 처리: async/await 패턴을 사용한 비동기 통신

  • 데이터 영속성: SQLAlchemy를 사용하여 MySQL 데이터베이스에 메시지 저장

  • 유연한 설정: 환경 변수를 통한 설정

  • 컨테이너화 배포: Docker를 통한 빠른 배포 지원

  • 지능형 함수 호출: 사용자가 입력한 텍스트를 AI가 자동으로 분석하여 가장 적합한 함수를 호출하며, 개발자는 함수와 주석 설명만 추가하면 됩니다.

📦 현재 지원되는 함수

프로젝트에는 현재 대규모 언어 모델이 호출할 수 있는 다음 함수들이 내장되어 있습니다:

함수명

설명

tell_joke

무작위 농담 말하기

get_time

현재 시간 가져오기

fortune

무작위 운세 뽑기

get_weather

도시 날씨 가져오기

count_daily_speakers

오늘 발언한 사람 수 통계 가져오기

get_top_speaker_today

오늘 가장 많이 발언한 사용자 가져오기

send_message

지정된 사용자에게 메시지 보내기

list_tools

사용 가능한 모든 도구와 설명 나열

extra_order_from_content

텍스트에서 주문 번호, 상품명, 수량 등 주문 정보 추출

Feishu에서 트리거 명령어를 입력한 후 실행할 작업을 입력하여 이러한 기능을 호출할 수 있습니다. 예: /run 농담 하나 해줘

📂 프로젝트 구조

project/
├── app/                    # 应用程序模块
│   ├── api/                # API相关模块
│   │   ├── auth.py         # 认证模块
│   │   └── lark_client.py  # 飞书客户端
│   ├── config/             # 配置模块
│   │   └── settings.py     # 应用配置
│   ├── core/               # 核心业务逻辑
│   │   ├── mcp_server.py   # MCP服务器(函数注册和处理)
│   │   ├── llm_service.py  # LLM服务
│   │   └── message_service.py  # 消息处理服务
│   ├── db/                 # 数据库相关
│   │   ├── models.py       # 数据模型
│   │   └── session.py      # 数据库会话管理
│   └── utils/              # 工具函数
├── builder/                # 请求构建器
├── extension/              # 扩展功能
│   └── weather_api/        # 天气API集成
├── static/                 # 静态资源
│   ├── resource/           # 图片资源
│   ├── proto_pb2.py        # 协议定义
│   └── lark_decrypt.js     # 飞书解密工具
├── .env                    # 环境变量
├── main.py                 # 应用入口
├── requirements.txt        # 项目依赖
├── docker-compose.yml      # Docker Compose配置
└── Dockerfile              # Docker配置

🛠️ 사용자 정의 함수 개발

app/core/mcp_server.py 파일에서 @register_tool 데코레이터를 사용하여 자신만의 사용자 정의 함수를 추가할 수 있습니다:

@register_tool(name="tell_joke", description="讲一个随机笑话")
def tell_joke() -> str:
    jokes = [
        "为什么程序员都喜欢黑色?因为他们不喜欢 bug 光。",
        "Python 和蛇有什么共同点?一旦缠上你就放不下了。",
        "为什么 Java 开发者很少被邀去派对?因为他们总是抛出异常。",
    ]
    return random.choice(jokes)

@register_tool(name="send_message", description="给指定用户发送消息 {user:用户名称 content:消息内容}")
def send_message(user: str, content: str) -> str:
    """给指定用户发送私信"""
    lark_client = LarkClient(get_auth())
    # ... 实现逻辑 ...
    return f"成功向 {user} 发送了私信: '{content}'"

중요: 함수와 해당 설명을 추가하기만 하면, AI가 사용자의 텍스트를 기반으로 자동으로 분석하여 가장 적합한 함수를 호출합니다. 수동으로 함수 매칭 로직을 구현할 필요가 없습니다.

🔧 환경 요구 사항

  • Python 3.10+

  • Node.js 18+

  • MySQL 데이터베이스

📦 설치 방법

로컬 환경 사용

  1. 의존성 설치:

    pip install -r requirements.txt
  2. Windows 사용자 주의: Windows 시스템은 다음 의존성을 추가로 설치해야 합니다:

    pip install win-inet-pton==1.1.0

Docker 사용

방법 1: 이미지 개별 빌드

# 构建镜像 
docker build -t feishuapp .

# 运行容器 需要外部mysql 通过docker网关连接宿主机mysql 推荐--env-file
docker run -it feishuapp bash

방법 2: Docker Compose 사용 (권장)

# 启动所有服务(应用和数据库)
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止所有服务
docker-compose down

Docker Compose를 사용하면 MySQL 데이터베이스와 애플리케이션 서비스를 포함한 전체 애플리케이션 환경을 한 번에 시작할 수 있어 더 편리하고 효율적입니다.

🛠️ 설정 설명

.env.example 파일을 복사하여 .env 파일로 이름을 변경하고 다음 설정을 포함하세요:

# 数据库设置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=lark_messages

# 飞书的Cookie设置 - 只需配置LARK_COOKIE即可,告别飞书机器人
LARK_COOKIE=""

# 调用函数的触发前缀 (以FUNCTION_TRIGGER_FLAG开头的消息会被大模型解析,所有消息都会被记录到数据库,无论是否以该前缀开头)
FUNCTION_TRIGGER_FLAG="/run"

# 机器人发言前缀 (暂未使用)
AI_BOT_PREFIX="Lark AI Bot:"

# OpenAI API配置 默认是通义千问的,满足OpenAI的大模型厂商都可以
OPENAI_API_KEY=""
OPENAI_API_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_API_MODEL="qwen-plus"

🚀 사용 가이드

애플리케이션 실행

방법 1: 직접 실행

python main.py

방법 2: Docker Compose 사용

docker-compose up -d

애플리케이션은 다음을 수행합니다:

  1. MCP 서버 초기화

  2. Feishu API에 연결하고 당신의 Feishu 계정을 AI 어시스턴트로 사용

  3. 수신되는 메시지 리스닝

  4. Feishu를 통해 대규모 언어 모델이 시작한 함수 호출 처리 및 실행

  5. 메시지를 MySQL 데이터베이스에 저장

🗄️ 데이터베이스 구조

애플리케이션은 메시지를 messages 테이블에 저장하며, 테이블 구조는 다음과 같습니다:

열 이름

타입

설명

id

INT (PK)

기본 키

user_name

VARCHAR(255)

메시지 발신자 이름

user_id

VARCHAR(255)

발신자의 Feishu 사용자 ID

content

TEXT

메시지 내용

is_group_chat

BOOLEAN

그룹 채팅 여부

group_name

VARCHAR(255)

그룹 채팅 이름 (해당 시)

chat_id

VARCHAR(255)

채팅 ID

message_time

DATETIME

메시지 발송 시간

created_at

DATETIME

레코드 생성 시간

🤝 기여 가이드

기여를 환영합니다! 언제든지 Pull Request를 제출해 주세요.

  1. 이 저장소를 Fork 하세요

  2. 기능 브랜치 생성 (git checkout -b feature/amazing-feature)

  3. 변경 사항 커밋 (git commit -m '멋진 기능 추가')

  4. 브랜치에 푸시 (git push origin feature/amazing-feature)

  5. Pull Request 열기

🐛 문제 및 지원

문제가 발생하거나 궁금한 점이 있으면 issue 제출 또는 토론 포럼을 방문해 주세요.

📈 Star 추이

🍔 커뮤니티 그룹

크롤러와 AI 에이전트에 관심이 있다면, 작성자 홈페이지의 위챗(wx)을 통해 초대받아 그룹 채팅에 참여하세요.

ps: 7번 그룹에 가입해 주세요. 인원이 꽉 찼거나 만료된 경우 issue를 남겨주세요 | 위챗(wx)으로 알려주세요

group7

Related MCP Connectors

Related MCP Servers