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.
• Uses persistent structured transports where providers support them: Codex App Server plus OpenCode and CodeBuddy ACP, with the existing CLI adapters retained as safe compatibility fallbacks.
• Keeps one provider-specific agent session per Feishu chat.
• Accepts direct messages without an @ mention.
• Supplies the triggering message ID, timestamp, sender and quote/thread references to the agent. For requests about earlier images/files, the agent is instructed to look up relevant chat messages with lark-cli, download the selected attachment and read it before answering. Retrieval is agent-driven and requires access to those messages; unrelated attachments are not automatically downloaded.
• Sends group-task results only to the authorized CLI user 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
请关闭这条待确认任务

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

Approval routing (2.0.2)

All group-task previews go to the verified authorized lark-cli user, including tasks from humans, bots and apps. Missing in-memory owner identity triggers lark-cli auth status --json --verify. Sender mentions do not control approval routing. If no authorized owner can be obtained, the pending result is retained without posting its body to the group.

The agent interprets requests to close a bridge preview semantically, then calls feishu-agent approval close <id> --json. No cancellation phrases are intercepted with regular expressions. Ordinary Feishu business tasks remain lark-cli task operations. Ambiguous targets require clarification. Repeated close is idempotent and in-flight agent completions cannot reopen closed approvals. Only the authorized user's private agent invocation can use approval capabilities; local terminal operations use the verified CLI account.

approval list --json shows pending records (use --all for history). approval show <id> --json includes raw output, body readiness and delivery failures. approval retry <id> --json retries private delivery with the same idempotency key. Transient delivery failures get at most three attempts; permission failures remain visible without automatic retry. status includes pending/delivery problem counts. A sent preview is not duplicated by retry.

Quoted previews, an active selection or a unique pending task provide candidate IDs to the private AI dispatcher; only a CLI revision request resumes the originating provider/session. Multiple unselected tasks are passed as context to the agent so it can clarify or close an explicitly identified record. Group sending still requires 确认发送 <id>.

A single local formatting pass repairs bracket typos in explicit group-reply delimiters without rerunning any business operation. Completely unmarked output is retained as needs_format; the user can ask the agent to revise or supply the intended group body. Legacy unmarked summaries cannot be sent as group bodies.

AI-to-CLI message routing

Only /new (including /new <task>) and 确认发送 <id> are intercepted directly by the bridge. All other requests are interpreted by the agent, including old spellings such as 待确认任务, 选择 A123, and 修改 A123：.... No listing, selection, revision, closure or natural-new-session message regex and no new-session output marker is used.

Agent capabilities:

feishu-agent approval list --json
feishu-agent approval show A123 --json
feishu-agent approval select A123 --json
feishu-agent approval revise A123 --text "shorten the reply" --json
feishu-agent approval revise A123 --file ./changes.txt --json
feishu-agent approval close A123 --json
feishu-agent approval retry A123 --json
feishu-agent session new <chat-id> --json

The authorized user's private session acts as a dispatcher. Listing or selecting does not regenerate a preview. approval revise queues one explicit target and the requested changes; after the dispatcher returns, the bridge resumes the original provider/session once, saves the result and sends a new private preview. The CLI's queued response does not mean the revision has completed. Closed tasks are never reopened by completion. Use approval show to inspect revision status (queued, running, completed, failed); do not blindly rerun a running operation. Local terminal revision calls run synchronously.

Quoted/selected/unique records are context, not authorization or a forced action. If the target is ambiguous, the agent asks for clarification. Group messages require a native Feishu mention; merely mentioning the bot's name in plain text does not trigger execution. Format/ID validation and permission checks remain deterministic.

CodeBuddy permission default (2.0.3)

New configurations default to bypassPermissions instead of auto, avoiding auto-classifier no-verdict failures on ordinary commands. Explicit existing permission modes are preserved. To opt an existing installation into this behavior, run feishu-agent config set agent.providers.codebuddy.permissionMode bypassPermissions.

Ordinary bypassPermissions still retains HIGH/CRITICAL checks. Only the separately opt-in fullPermissionBypass setting below changes this; neither setting creates isolation. dangerouslySkipPermissions remains false. Provider/model selection and the bridge service-control restrictions are unchanged.

Bridge-only full CodeBuddy permission bypass (2.0.3)

To explicitly enable full permission bypass for CodeBuddy processes launched by this bridge, configure:

{
  "permissionMode": "bypassPermissions",
  "dangerouslySkipPermissions": false,
  "fullPermissionBypass": true
}

agent.providers.codebuddy.fullPermissionBypass is a portable boolean setting, default false. When true, the bridge injects CODEBUDDY_IS_SANDBOX=1 only into the CodeBuddy ACP process and CodeBuddy CLI fallback process. It requires bypassPermissions or dangerouslySkipPermissions. It does not modify system/user environment variables, standalone CodeBuddy, Codex or OpenCode. This disables CodeBuddy HIGH/CRITICAL approval checks as well; despite the environment-variable name it does not create a sandbox or isolate filesystem/network access. Do not claim that the host is isolated.

Enable this setting only on explicit user request acknowledging full permission bypass. Use feishu-agent config set agent.providers.codebuddy.fullPermissionBypass true; to revert, set false. From a trusted local terminal restart an active bridge after installing code that adds this setting. Feishu group-send confirmation and business-task controls remain separate and unchanged. Existing task instructions still apply; disabling prompts is not authorization to perform unrelated actions.

This feature is available from 2.0.3. Version 2.0.2 does not recognize fullPermissionBypass.