FeishuAI-Orchestrator: Your Personal Feishu AI Interface 🤖

This system is an AI Agent built atop the Feishu/Lark platform, enabling Large Language Models (LLMs) to perform tool invocation and message processing directly through the client interface.

Key Feature: No Bot Token Required – Your personal Feishu identity acts as the AI assistant.

Operation: Define your functions with clear docstrings, and the system automatically maps user intent to the correct function execution.

Core System Features 🛠️

Lark Agentx (renamed to FeishuAI-Orchestrator) is a contemporary application designed to:

• 🌐 Reverse-engineer Feishu's proprietary Protobuf WebSocket traffic and standard APIs to monitor and log all conversational data.
• ⚙️ Expose developer-defined functions for LLM invocation.
• 🔄 Implement a robust function-calling infrastructure compliant with the Model Context Protocol (MCP).
• 🗄️ Persist message logs into a MySQL database utilizing SQLAlchemy for ORM capabilities.

Capabilities Showcase ✨

• Tool Registration: Intuitive decorator-based mechanism for adding new capabilities.
• Message Capture: Comprehensive logging of all received private and group messages.
• Asynchronous Processing: Built with async/await patterns for efficient I/O operations.
• Data Persistence: Reliable storage of conversation metadata in MySQL.
• Configuration Flexibility: Environment variable driven setup for deployment.
• Containerization: Docker support for streamlined deployment and setup.
• Intelligent Dispatch: The AI autonomously analyzes user input to select and execute the most relevant registered function based solely on descriptions.

Available Built-in Capabilities (Tools) 📚

The system natively supports the following actions for the LLM to invoke:

Tool Name	Purpose
tell_joke	Recite a humorous anecdote.
get_time	Retrieve the current system timestamp.
fortune	Generate a random daily horoscope/luck reading.
get_weather	Fetch meteorological data for a specified locale.
count_daily_speakers	Report on the number of unique participants today.
get_top_speaker_today	Identify the user with the highest message volume today.
send_message	Dispatch a private message to another user.
list_tools	Output a catalog of all available functions and their descriptions.
extra_order_from_content	Parse unstructured text to extract structured order details (ID, item, quantity, etc.).

Interaction is typically initiated via a trigger prefix followed by the command, e.g., /run Fetch today's weather for Beijing.

Custom Tool Development Guide 🧩

To integrate new functionality, modify app/core/mcp_server.py and use the @register_tool decorator:

python import random from app.core.mcp_server import register_tool

Assume LarkClient is imported elsewhere

@register_tool(name="tell_joke", description="Deliver a randomly selected humorous story") def deliver_humor() -> str: jokes_list = [ "Why do programmers prefer dark mode? Because light attracts bugs.", "What do Python and snakes have in common? Once they wrap around you, letting go is hard.", "Why are Java developers rarely invited to gatherings? They always throw exceptions.", ] return random.choice(jokes_list)

@register_tool(name="send_message", description="Deliver a private message to a target user {user:target_username content:message_text}") def dispatch_private_note(user: str, content: str) -> str: """Sends a direct message via the Lark API.""" # Replace with actual Lark client initialization logic # lark_client = LarkClient(get_auth()) # ... implementation details ... return f"Successfully routed private communication to {user} with content: '{content}'"

Crucial Note: Focus only on defining the function logic and providing comprehensive descriptions. The orchestration layer handles all input parsing and tool mapping autonomously.

Deployment & Configuration 🚀

Prerequisites

• Python version 3.10 or newer.
• Node.js version 18 or newer (if using any Node-dependent utilities).
• Operational MySQL instance.

Installation Steps

Local Setup:

1. Install Python dependencies: bash pip install -r requirements.txt

2. Windows Specific Fix (if required): bash pip install win-inet-pton==1.1.0

Containerized Deployment (Recommended):

Use docker-compose.yml for rapid setup, which handles both the application service and an integrated MySQL database.

bash

Start all linked services in detached mode

docker-compose up -d

Monitor combined logs

docker-compose logs -f

Stop and remove all containers and networks

docker-compose down

Environment Variables (.env File)

Copy .env.example to .env and populate the settings:

env

Database Connection Details

DB_HOST=mysql_service DB_PORT=3306 DB_USER=root DB_PASSWORD=secure_pass DB_NAME=lark_log_db

Feishu Session Cookie (Crucial for non-bot access)

LARK_COOKIE="your_session_cookie_here"

Command Prefix for LLM Function Invocation Trigger (All messages are logged regardless)

FUNCTION_TRIGGER_FLAG="/act"

LLM Provider Settings (Defaulted for OpenAI compatible endpoints, e.g., Alibaba Cloud)

OPENAI_API_KEY="your_api_key" OPENAI_API_BASE_URL="https://api.example.com/v1" OPENAI_API_MODEL="powerful-llm-model-name"

Data Schema: Message Logging 📊

All user interactions are logged into the messages relational table:

| Field Name | Data Type | Purpose | |---|---| | id | INT (PK) | Unique Record Identifier | | user_name | VARCHAR(255) | Sender's Display Name | | user_id | VARCHAR(255) | Sender's Unique Feishu ID | | content | TEXT | The full textual input from the user | | is_group_chat | BOOLEAN | Flag indicating group versus private message | | group_name | VARCHAR(255) | Contextual group name (NULL if PM) | | chat_id | VARCHAR(255) | Identifier for the specific conversation thread | | message_time | DATETIME | Timestamp of when the message was sent | | created_at | DATETIME | Timestamp when the record was created in DB |

Contribution Guidelines 🤝

We welcome external contributions! To participate:

1. Fork the repository.
2. Establish a new feature branch (git checkout -b feat/new-capability).
3. Commit your modifications (git commit -m 'Introduce feature X').
4. Push the branch (git push origin feat/new-capability).
5. Submit a comprehensive Pull Request.

Support & Feedback ❓

For bug reports, inquiries, or feature suggestions, please utilize the project's Issue Tracker or join our Discussion Forum.