Feishu Agent Bridge

Portable Windows bridge that sends Feishu/Lark messages to Codex, OpenCode, or CodeBuddy and returns the result to Feishu.

Features

• Uses the globally installed lark-cli identity; no Feishu credentials are copied into bridge configuration.
• Supports Codex, OpenCode, and CodeBuddy with runtime provider switching.
• Keeps one provider-specific agent session per Feishu chat.
• Accepts direct messages without an @ mention.
• Sends group-task results to the requester for private review before posting them back to the group.
• Runs as a hidden, per-user Windows scheduled task.
• Preserves task and session state across bridge restarts.
• Rejects stale event replays and persists processed event IDs across restarts.

Requirements

• Windows
• Node.js 20 or later
• A globally installed and configured lark-cli
• At least one supported agent CLI:
  • Codex
  • OpenCode
  • CodeBuddy

Install

npm install -g @helixcli/feishu-agent-bridge

Verify the Feishu bot identity before setup:

lark-cli auth status --json --verify

The bot identity must report status: "ready" and verified: true.

Quick start

Interactive setup:

feishu-agent setup --workdir D:\work

Non-interactive setup with a selected provider:

feishu-agent setup --workdir D:\work --agent codex --json

Setup verifies the selected provider and installs a hidden scheduled task for the current Windows user.

Check the bridge after setup:

feishu-agent doctor --json
feishu-agent status
feishu-agent logs --tail 100

Provider management

feishu-agent agent list
feishu-agent agent current
feishu-agent agent use codex
feishu-agent agent use opencode
feishu-agent agent use codebuddy

Provider sessions are isolated. Switching providers starts a new session for the next task instead of reusing another provider's session.

When a provider switch is requested from inside a running bridge task, the bridge hot-reloads the configuration after the current reply. This avoids terminating the task that requested the switch. A switch issued from a normal terminal restarts the running scheduled task.

Feishu conversations

Direct messages from real users do not require an @ mention. Group messages follow the configured group trigger behavior.

Each Feishu chat keeps one persistent provider-specific session. Topic threads in the same group share that group session.

Start a fresh session in Feishu:

@bot /new
@bot /new <first task>

Inspect or reset sessions locally:

feishu-agent session list
feishu-agent session show <chat-id>
feishu-agent session new <chat-id>
feishu-agent session reset <chat-id>

Group-task approval

Group results are sent privately for review before they are posted back to the original group or thread.

待确认任务
选择 A123
修改 A123：补充要求
确认发送 A123
取消 A123

Only 确认发送 A123 authorizes posting the result to the original group. Other confirmation-like wording remains private conversation content.

Service management

feishu-agent service start
feishu-agent service stop
feishu-agent service restart
feishu-agent service uninstall

The service runs as the installing user, not as SYSTEM.

Configuration

Show the portable configuration:

feishu-agent config show

Update an allowlisted value:

feishu-agent config set bridge.logLevel debug
feishu-agent config set bridge.logLevel normal

Messages older than 10 minutes are ignored by default when Feishu replays events after an outage. Change the limit in seconds, or set it to 0 to disable stale-event filtering:

feishu-agent config set bridge.maxEventAgeSeconds 600

Configuration is stored in %USERPROFILE%\.feishu-agent\config.json. Session bindings and pending approvals are stored separately in %USERPROFILE%\.feishu-agent\sessions.json.

Do not place Feishu tokens, app secrets, or provider credentials in bridge configuration. The bridge reads Feishu identity from lark-cli and reuses each provider CLI's own login state.

Update

Check for a newer release without installing it:

feishu-agent update

Install an available update:

feishu-agent update --yes

Restart the service when the update output provides a restart command.

Troubleshooting

feishu-agent doctor --json
feishu-agent status
feishu-agent logs --tail 100

Common checks:

• lark-cli must be available globally.
• lark-cli auth status --json --verify must report a ready, verified bot identity.
• The selected agent CLI must be installed and authenticated.
• feishu-agent status should show the service and Feishu event consumer as running.
• Normal logs report event skipped reason=stale or event skipped reason=duplicate when replay protection discards an event.

Use debug logging only while diagnosing routing or latency, then restore normal logging:

feishu-agent config set bridge.logLevel debug
feishu-agent service restart

# After diagnosis
feishu-agent config set bridge.logLevel normal
feishu-agent service restart

License

MIT