Skip to content

README.md

Latest commit

 

History

History
129 lines (85 loc) · 3.77 KB

README.md

File metadata and controls

129 lines (85 loc) · 3.77 KB
Raw

Feishu CLI Bot Listener

This directory runs a blocking Feishu message listener. It consumes Feishu IM events with lark-cli, handles a small set of built-in commands, and delegates unknown tasks to a local AI agent.

Feishu message -> event-bot.py -> built-in command or local agent -> Feishu reply

Required Configuration

Set runtime identifiers with environment variables. Do not store real chat ids, user ids, or credentials in repository files.

Variable Required Description
FEISHU_CHAT_ID Yes Target Feishu chat id that the bot listens to and replies in.
FEISHU_USER_OPEN_ID Yes Feishu user open id allowed to trigger the bot.
FEISHU_BOT_AGENT No Agent executor: codex or deepseek. Defaults to codex.
FEISHU_BOT_WORKDIR No Working directory for delegated agent tasks. Defaults to this directory.
LARK_CLI No Path or command name for lark-cli. Defaults to lark-cli.
CODEX_CLI No Path or command name for codex. Defaults to codex.
DEEPSEEK_CLI No Path or command name for deepseek. Defaults to deepseek.

Files

  • event-bot.py: the bot program. It consumes im.message.receive_v1 events with lark-cli event consume.
  • run-feishu-bot.sh: a single-command startup wrapper for Codex or DeepSeek mode.
  • README.md: this operating guide.

Runtime locks, logs, caches, and local auth files are not part of the source interface.

Start

Check whether the listener is already running:

pgrep -af "event-bot.py"

Start with Codex:

cd lark-cli
export FEISHU_CHAT_ID="<feishu chat id>"
export FEISHU_USER_OPEN_ID="<feishu user open id>"
./run-feishu-bot.sh codex

Start with DeepSeek:

cd lark-cli
export FEISHU_CHAT_ID="<feishu chat id>"
export FEISHU_USER_OPEN_ID="<feishu user open id>"
./run-feishu-bot.sh deepseek

Direct Python startup is also supported:

FEISHU_BOT_AGENT=codex python3 event-bot.py

The listener is ready when stderr includes:

[event] ready event_key=im.message.receive_v1

Behavior

event-bot.py only processes text messages from FEISHU_USER_OPEN_ID inside FEISHU_CHAT_ID.

Built-in command groups:

  • Help: help, ?, and the configured Chinese aliases.
  • Time: time and the configured Chinese aliases.
  • Agenda: agenda and the configured Chinese aliases.
  • Tasks: tasks and the configured Chinese aliases.
  • Spreadsheet creation: the configured Chinese create-sheet aliases.
  • Contact lookup: the configured Chinese contact-search aliases.

If a message does not match a built-in command, the bot delegates the full message to the selected local agent:

  • FEISHU_BOT_AGENT=codex -> codex exec
  • FEISHU_BOT_AGENT=deepseek -> deepseek exec --auto --output-format text

Delegated tasks are expected to do the requested work and return a concise Feishu reply.

Stop

Find the process:

pgrep -af "event-bot.py"

Stop it:

kill <PID>

Do not run multiple listener processes for the same chat. The script writes .event-bot.lock to avoid duplicate consumers.

Troubleshooting

Missing FEISHU_CHAT_ID or FEISHU_USER_OPEN_ID

Export both values before starting the listener.

macOS Keychain error from lark-cli

Run the bot from a normal terminal session that can access Keychain, or configure lark-cli to use a non-Keychain credential store.

Sandbox or network errors from delegated agents

Retry the same startup command outside the restricted sandbox if the selected CLI needs network or system access.

DeepSeek rejects multi-line shell commands

Use the wrapper:

./run-feishu-bot.sh deepseek

lark-cli event status rejects --as

That command does not support --as; do not use lark-cli event status --as bot for diagnostics.