Feishu-AGY SDK Bridge (Python)

中文文档 (Chinese Version)

This repository contains the native Python SDK implementation of the Feishu (Lark) integration for the Google Antigravity SDK.

It is a Python SDK-native rewrite of the original Feishu-AGY Bridge Node.js version. Unlike the CLI/PTY version, this version directly utilizes Google Antigravity SDK Hooks (google-antigravity), offering a clean, native, and robust communication loop without PTY window issues or regex scraping of stdout.

---

Features

• Native Hooks Integration: Intercepts tool calls and questions programmatically using @hooks.pre_tool_call_decide and @hooks.on_interaction.
• Zero Scraping: Replaces stdout parsing and log-file watchers with direct, structured objects (ToolCall, AskQuestionInteractionSpec).
• Lark API Python SDK: Integrates using official lark-oapi.
• Asyncio Workflow: Blocks agent execution cleanly when waiting for Feishu card approval, resuming automatically upon webhook payload reception.

---

Prerequisites

• Python: v3.10 or higher.
• Lark Suite custom App: Set up with bot capabilities and event subscription.

---

Setup & Running

1. Clone and navigate to the directory:

   cd /Users/emu/Desktop/feishu-agy-sdk-bridge

2. Create a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables:

   cp .env.example .env
   # Open .env and add your FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_DEFAULT_CHAT_ID, and GEMINI_API_KEY

5. Run the agent:

   python main.py "Your prompt goes here"

---

Architecture details

When Agent runs a task:

1. Before calling a tool (e.g. executing commands or reading files), google-antigravity calls the @hooks.pre_tool_call_decide hook.
2. The hook builds an interactive card and sends it to your Feishu group or direct chat.
3. The hook creates a thread-safe asyncio.Event and halts execution using await event.wait().
4. When you click Approve or Deny in Feishu, Lark triggers your webhook server endpoint (which should map to handle_feishu_webhook).
5. Your webhook handler sets the response in the map and triggers event.set(), resuming the hook block and continuing execution.

---

Supported Commands

You can interact with the bot using the following slash commands in the Feishu chat:

• /new [flags] <prompt>: Start a new session. Flags:
  • --sandbox: Run in sandbox mode.
  • --dangerously-skip-permissions: Auto-approve all tool calls.
  • --model <model>: Specify a Gemini model.
  • --add-dir <dir>: Restrict workspace path to the given directory.
• /list: List all local sessions, showing running status and the default session.
• /switch <index/session-id>: Switch the default active session.
• /resume <index/session-id> [flags]: Resume a stopped/inactive session. Supports the same flags as /new.
• /model [alias]: Show current model or switch active model (e.g., /model flash).
• /models: Fetch and list all available models.
• /plugins [subcommand]: Manage plugins (e.g. /plugins list).
• /changelog: Display release notes.
• /update: Update the AGY CLI tool.
• /stop [index/session-id]: Interrupt and stop a running session.
• /del <index/session-id/all>: Delete specific session data or all sessions (/del all).
• /settings: Show settings card to change language and card themes.
• /help: Show the command help guide.