convez.ai
PluginAutomaçãoAvançado
songqingjun060

Feishu-Claudecode-Qiao

songqingjun060/feishu-claudecode-qiao

Bot Feishu integrado ao Claude Code com regras de grupo e suporte a mídia local

Ver no GitHub
InicialPluginScore · de 0 a 100

Bridge local que conecta Feishu (plataforma de colaboração chinesa) ao Claude Code, gerenciando conversas em grupo, regras de segurança, transferência de mídia e fluxos de arquivo local. Funciona como intermediário entre mensagens do Feishu e CLI do Claude, retornando respostas, arquivos gerados e resultados de consultas.

Instalação

$npx convez-ai songqingjun060/feishu-claudecode-qiao

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de tarefas técnicas em grupos Feishu via Claude Code
  • Processamento de imagens, áudio (com transcrição Whisper) e arquivos em conversas Feishu
  • Gerenciamento centralizado de sessões Claude com histórico, compressão e contexto persistente
  • Aplicação de regras de permissão granulares por grupo e membro com auditoria

Veredito

Solução robusta para ambientes corporativos que usam Feishu como plataforma colaborativa, oferecendo integração profunda com Claude Code, segurança granular e controle de acesso a caminhos locais. Recomendado para equipes de desenvolvimento que buscam automação técnica integrada ao Feishu com auditoria completa.

README

A tradução para o português deste README ainda está na fila.

Feishu-Claudecode-Qiao

中文说明

Feishu-Claudecode-Qiao 是一个本地运行的飞书机器人桥接工具,用来把飞书消息转交给 Claude Code CLI 处理,再把 Claude 的回复、生成文件或查询结果发回飞书。

它的定位不是把所有能力都塞进桥本身,而是让桥负责飞书通信、安全规则、文件收发和会话管理,让 Claude Code 负责真正的代码、文档、表格、PDF、压缩包和本地工具调用。

功能特性

  • 支持飞书个人会话和群聊中的文本对话。
  • 群聊回复会引用原消息并 @ 发送者。
  • 收到消息后添加临时响应标记,处理完成后自动清理。
  • 将 Claude 的 Markdown 回复转换成飞书交互卡片。
  • 支持按会话配置工作目录、可访问路径、权限档位和会话模式。
  • 支持 Claude 会话记录、上下文延续和自动压缩。
  • 支持把 Claude Code 生成的本地文件上传回当前飞书会话。
  • 支持下载飞书图片,并把本地图片路径交给 Claude Code 处理。
  • 支持下载飞书音频,并用 Whisper 转写。
  • 支持“先发音频,再 @ 机器人”的群聊音频处理流程。
  • 支持下载飞书普通文件,并把本地文件路径交给 Claude Code 处理。
  • 支持审计日志、运行状态检查和 doctor 自检。

项目结构

feishu_claudecode_qiao/
  bridge.py              主事件循环、飞书 API、Claude CLI 调用
  config.py              TOML 和环境变量配置
  security.py            路径白名单、敏感词、风险意图检查
  chat_rules.py          会话规则文件管理
  rule_engine.py         默认/会话/成员规则合并
  session_store.py       Claude 会话元数据和压缩计数
  commands.py            /help、/rules、/context、/workspace、/permission
  audit.py               JSONL 审计日志
  doctor.py              环境自检
  message_formatter.py   Markdown 转飞书卡片
  logger.py              滚动日志
tests/                   Pytest 回归测试

运行数据默认写入 data_dir:

data/
  bridge.pid
  sessions.json
  rules/<chat_id>.json
  logs/bridge.log
  logs/messages.log
  logs/audit.jsonl
  images/
  attachments/

data/、data-test/、config.toml、config.realtest.toml、日志和压缩包默认不提交到 Git。

安装

python -m pip install -e ".[dev]"

如需音频转写能力:

python -m pip install -e ".[voice]"

开发和测试环境推荐:

python -m pip install -e ".[dev,voice]"
python -m pytest -q

配置

复制示例配置:

copy config.example.toml config.toml

编辑 config.toml:

[feishu]
app_id = "cli_xxxxx"
app_secret = "xxxxx"
domain = "https://open.feishu.cn"

[claude]
command = "claude"
work_dir = "."
permission_mode = "safe"

[whisper]
model = "base"

[bridge]
data_dir = "./data"
log_level = "INFO"
max_upload_mb = 20
require_mention_in_group = true
bot_display_name = "your-bot-display-name"
personal_permission_profile = "admin"
bot_owner_id = ""
bot_admins = []

[security]
allowed_paths = []
blocked_keywords = []

也可以使用 FEISHUCLAUDECODE_ 前缀的环境变量覆盖配置。

飞书应用权限

修改飞书应用权限后,需要重新发布应用。通常需要以下能力:

  • 接收消息事件。
  • 发送消息。
  • 添加和删除消息表情回应。
  • 回复消息。
  • 读取消息资源,用于下载图片、音频和文件。
  • 上传文件。
  • im:message.group_msg,用于群聊中“先发音频/文件,再 @ 机器人”的历史消息查找。

如果缺少 im:message.group_msg,桥仍然可以处理飞书直接推送的媒体事件,但无法主动回查群里的上一条音频或文件。

群聊与个人权限

个人会话使用 bridge.personal_permission_profile。可信的本地部署可以设置为 admin,对应 Claude Code 的 bypassPermissions。

群聊建议保持:

require_mention_in_group = true

这样机器人只响应明确 @ 当前机器人的消息。匹配规则是精确匹配:飞书 mention ID 必须等于当前应用 ID,或 mention 展示名必须和 bot_display_name 完全一致。多个机器人在同一个群里时,务必正确设置 bot_display_name。

群规则只对当前群生效。规则管理不依赖飞书群管理员:

  • 如果配置了 bridge.bot_admins,只有列表中的用户能改群规则。
  • 如果没有配置 bridge.bot_admins,只有 bridge.bot_owner_id 能改群规则。

安全模型

规则合并顺序:

default -> chat -> member -> temporary

权限档位:

档位Claude CLI 模式适用场景
readonlydefault只读对话
safedefault普通群聊
devacceptEdits可信开发群
adminbypassPermissions高信任维护场景
statelessdefault不保留会话

桥还会检查:

  • 本地路径是否在允许范围内。
  • 群聊是否精确 @ 当前机器人。
  • 是否命中阻断关键词。
  • 是否存在删除、移动、覆盖、shell、敏感路径读取等高风险意图。
  • 是否需要确认或拒绝。

workspace 和 allowed_paths 会写入发送给 Claude Code 的安全边界提示中,要求 Claude 只讨论和处理当前会话授权的路径;桥本身仍会在读取本地路径、缓存文件和上传文件时做硬性路径校验。

注意:allowed_paths = [] 不是“允许全盘”。如需允许访问本地路径,请在规则或配置里明确放行。

文件处理

桥负责接收飞书文件、下载到本地、保存近期文件上下文,并把本地文件路径交给 Claude Code。

具体内容解析优先交给 Claude Code 和本机工具:

  • PDF:Claude Code 可使用 pypdf、pdfplumber 等 Python 工具。
  • Word:可使用 python-docx。
  • Excel/CSV:可使用 openpyxl、pandas。
  • PPT:可使用 python-pptx。
  • 压缩包:可先列出内容,再按需解压分析。
  • 视频:可使用 ffprobe、ffmpeg 提取元数据、关键帧、缩略图或音频。

桥本身不会把这些能力都内置成重型解析器,避免和 Claude Code 的工具能力重复。

启动

启动或重启飞书事件订阅:

python start_ws.py restart --config config.toml --profile qiao-test

启动桥服务:

python -m feishu_claudecode_qiao --config config.toml

Windows 推荐使用前台窗口运行,便于观察日志:

.\run_foreground.ps1 -Config config.toml -Profile qiao-test

Windows 一键启动或重启:

.\start_all.ps1
.\start_all.ps1 -Restart
.\start_all.ps1 -Restart -Foreground

查看状态:

python -m feishu_claudecode_qiao --config config.toml --status

停止:

python start_ws.py stop --config config.toml
python -m feishu_claudecode_qiao --config config.toml --stop

环境自检:

python -m feishu_claudecode_qiao --config config.toml --doctor

飞书命令

命令作用
/help显示命令列表
/rules查看当前生效规则
/context查看当前会话元数据
/summary查看最近一次压缩摘要
/ask <问题>单次提问,不写入长期上下文
/new开启新的 Claude 会话
/reset重置当前会话
/compact强制压缩当前会话
/workspace查看或修改工作目录
/permission查看或修改权限档位

已验证流程

  • 群聊文本对话。
  • 群聊引用回复并 @ 发送者。
  • 收到消息添加响应标记,完成后清理。
  • 本地文件上传到飞书会话。
  • 个人音频转写。
  • 群聊中先发送音频,再 @ 机器人处理。
  • 图片下载后交给 Claude Code 使用本机工具处理。
  • 重启后不重复处理旧事件。
  • Claude 会话丢失时自动清理并重试。

故障排查

参见 docs/TROUBLESHOOTING.md。

安全说明

参见 SECURITY.md。不要提交真实飞书密钥、config.toml、config.realtest.toml、运行数据或日志。


English Documentation

Feishu-Claudecode-Qiao is a local Feishu bot bridge for Claude Code CLI. It receives Feishu messages, applies per-chat rules and safety checks, calls Claude Code, and sends formatted replies, generated files, or query results back to Feishu.

The bridge is intentionally lightweight: it handles Feishu communication, safety rules, file transfer, and session state, while Claude Code handles code work, document analysis, spreadsheets, PDFs, archives, local tools, and project operations.

Features

  • Text chat with Claude Code in Feishu direct messages and group chats.
  • Group replies quote the source message and mention the sender.
  • Temporary reaction when a message is received, removed after processing.
  • Markdown output converted to Feishu interactive cards.
  • Per-chat workspace, allowed paths, permission profile, and session mode.
  • Claude session store with context continuity and automatic compaction support.
  • Upload local files generated by Claude Code back to the current Feishu chat.
  • Download Feishu images and pass local image paths to Claude Code.
  • Download Feishu audio and transcribe it with Whisper.
  • Group workflow for "send audio first, then mention the bot".
  • Download Feishu files and pass local file paths to Claude Code.
  • Audit logs, status checks, and doctor diagnostics.

Project Structure

feishu_claudecode_qiao/
  bridge.py              Main event loop, Feishu API calls, Claude CLI calls
  config.py              TOML and environment configuration
  security.py            Path whitelist, blocked keywords, risky intent checks
  chat_rules.py          Per-chat rule file management
  rule_engine.py         Default/chat/member rule merging
  session_store.py       Claude session metadata and compaction counters
  commands.py            /help, /rules, /context, /workspace, /permission
  audit.py               JSONL audit log writer
  doctor.py              Environment self-check
  message_formatter.py   Markdown to Feishu card formatter
  logger.py              Rotating log setup
tests/                   Pytest regression tests

Runtime data is written under data_dir:

data/
  bridge.pid
  sessions.json
  rules/<chat_id>.json
  logs/bridge.log
  logs/messages.log
  logs/audit.jsonl
  images/
  attachments/

data/, data-test/, config.toml, config.realtest.toml, logs, and release archives are intentionally ignored by Git.

Install

python -m pip install -e ".[dev]"

Optional audio support:

python -m pip install -e ".[voice]"

Recommended development setup:

python -m pip install -e ".[dev,voice]"
python -m pytest -q

Configuration

Copy the example config:

copy config.example.toml config.toml

Edit config.toml:

[feishu]
app_id = "cli_xxxxx"
app_secret = "xxxxx"
domain = "https://open.feishu.cn"

[claude]
command = "claude"
work_dir = "."
permission_mode = "safe"

[whisper]
model = "base"

[bridge]
data_dir = "./data"
log_level = "INFO"
max_upload_mb = 20
require_mention_in_group = true
bot_display_name = "your-bot-display-name"
personal_permission_profile = "admin"
bot_owner_id = ""
bot_admins = []

[security]
allowed_paths = []
blocked_keywords = []

Environment variables with the FEISHUCLAUDECODE_ prefix can override config values.

Feishu App Permissions

Enable and publish the Feishu app after permission changes. Required capabilities usually include:

  • Receive message events.
  • Send messages.
  • Add and delete message reactions.
  • Reply to messages.
  • Read message resources for image/audio/file downloads.
  • Upload files.
  • im:message.group_msg for group-history lookup when a user sends audio or a file first and mentions the bot later.

Without im:message.group_msg, the bridge can still process media events pushed directly by Feishu, but it cannot fetch recent group history to recover the previous audio or file.

Direct Message And Group Permissions

Direct messages use bridge.personal_permission_profile. Trusted local deployments can set it to admin, which maps to Claude Code bypassPermissions.

For group chats, keep:

require_mention_in_group = true

With this setting, the bridge only handles messages that mention the current bot. Mention matching is exact: the Feishu mention ID must match the configured app ID, or the mention display name must exactly equal bot_display_name. Set bot_display_name carefully when multiple bots are installed in the same group.

Group rules apply only to the group where the bot is mentioned. Rule management does not depend on Feishu group administrator status:

  • If bridge.bot_admins is non-empty, only those users can change group rules.
  • Otherwise, bridge.bot_owner_id is the only rule manager.

Safety Model

Rules merge in this order:

default -> chat -> member -> temporary

Permission profile mapping:

ProfileClaude CLI modeIntended use
readonlydefaultRead-only conversations
safedefaultNormal group use
devacceptEditsTrusted development group
adminbypassPermissionsHighly trusted maintenance only
statelessdefaultNo session persistence

The bridge also checks:

  • Whether a local path is allowed.
  • Whether a group message exactly mentions the current bot.
  • Blocked keywords.
  • Risky intents such as delete, move, overwrite, shell, and sensitive path reads.
  • Whether confirmation or denial is required.

workspace and allowed_paths are included in the security-boundary prompt sent to Claude Code, instructing Claude to only discuss and operate on paths authorized for the current chat. The bridge still enforces hard path checks when exposing local paths, caching files, or uploading files.

Note: allowed_paths = [] does not mean "allow all drives". Add explicit paths in rules or config when local access is required.

File Handling

The bridge receives Feishu files, downloads them locally, keeps recent file context, and passes local file paths to Claude Code.

Content parsing is delegated to Claude Code and local tools:

  • PDF: pypdf, pdfplumber, or similar Python tools.
  • Word: python-docx.
  • Excel/CSV: openpyxl, pandas.
  • PowerPoint: python-pptx.
  • Archives: list contents first, then extract as needed.
  • Video: ffprobe and ffmpeg for metadata, keyframes, thumbnails, or audio extraction.

The bridge does not embed heavy parsers for every file type, avoiding duplicated functionality with Claude Code.

Run

Start or restart the Feishu event subscriber:

python start_ws.py restart --config config.toml --profile qiao-test

Start the bridge:

python -m feishu_claudecode_qiao --config config.toml

On Windows, use one visible foreground window:

.\run_foreground.ps1 -Config config.toml -Profile qiao-test

One-command Windows start or restart:

.\start_all.ps1
.\start_all.ps1 -Restart
.\start_all.ps1 -Restart -Foreground

Status:

python -m feishu_claudecode_qiao --config config.toml --status

Stop:

python start_ws.py stop --config config.toml
python -m feishu_claudecode_qiao --config config.toml --stop

Doctor:

python -m feishu_claudecode_qiao --config config.toml --doctor

Chat Commands

CommandPurpose
/helpShow command list
/rulesShow effective rules
/contextShow current session metadata
/summaryShow latest compaction summary
/memoryShow current chat rolling memory
/memory historyShow recent saved memory summaries
/memory clearClear current chat long-term memory
/ask <question>Ask once without storing long-term context
/newStart a new Claude session
/resetReset current session
/compactForce session compaction
/workspaceShow or update workspace
/permissionShow or update permission profile

Tested Flows

  • Text group chat.
  • Quoted group reply with sender mention.
  • Receive reaction and reaction cleanup after processing.
  • Local desktop file upload to Feishu chat.
  • Direct-message audio transcription.
  • Group audio transcription after sending audio then mentioning the bot.
  • Image download and Claude Code local-tool analysis workflow.
  • Restart without replaying old events.
  • Missing Claude session auto-clear and retry.

Troubleshooting

See docs/TROUBLESHOOTING.md.

Security

See SECURITY.md. Never commit real Feishu secrets, config.toml, config.realtest.toml, runtime data, or logs.

Ver o original no GitHub

Bom para

Relacionados