Skip to main content
Glama

这是第一代方案,线上机器人已被第二代取代。 第二代:dsh-feishu-channel —— 它不再给每条消息 spawn 一个 dsh headless 子进程,而是接进 DSH 的原生会话 (inbox 的 next-turn / next-step),所以「跑着的时候补一句」能真的插进去,而不是排队。

第一代仍然有价值的两个部分:packages/mcp(43 个工具的 MCP server,任何时候都能单独用) 与 packages/dsh-plugin(DSH 里的飞书连接设置页)。services/feishu-bot 是现在线上那个 bot.py 的前身。

仓库打扫记录:dsh-feishu-mcp、dsh-feishu-plugin 原本是本仓库 packages/mcp、packages/dsh-plugin 的构建产物镜像(提交信息里写着 "sync: 从主仓库打包/同步"),内容与主仓库重复,已归档(只读,可恢复)。


它是什么

飞书会话就是 agent 的操作台。在手机上发一句话,它在你的机器上执行,把文件、卡片、 多维表格发回会话——而不是回你一段「建议执行以下命令」。

不需要公网 IP、内网穿透、域名或证书:机器人主动向飞书发起 WebSocket 长连接,不开放入站端口。

它由三个角色组成,各自负责一段:

角色

职责

feishu-bot

常驻长连接。身份校验、会话管理、任务队列、进度卡、审批按钮。自身不执行任务

agent

实际执行方。dsh --profile headless 调用模型,43 个 MCP 工具是它的操作面

gateway

只做一件事:把卡片按钮的点击精确投递给正在等待回答的那次 feishu_ask

Related MCP server: Feishu/Lark OpenAPI MCP

它解决什么问题

你说

它做

把上周的纳米技术报告发我

在工作区找到 3 份 .docx,上传并发送到会话

建一张读书清单的多维表格

建表 → 建 4 个字段 → 写入第一条记录,返回链接

跑一下这个季度的文献综述,做完汇报

排进队列,进度在同一张卡片里刷新,聊天中只占一个气泡

清一下 /home/agent/work/old

先发审批卡,确认后才执行

我在高铁上,帮我看下服务器还活着吗

返回 CPU / 内存 / 磁盘 / 服务状态

发一张试卷照片,说「帮我批改」

图片经 read_image 真正打开,逐题给出对错

换个最会想的模型,慢慢算

/模型 点按钮换模型,/思考 切 reasoningEffort(含 auto 自动挡),切换前先真跑一次确认可用

群里三个人同时发话

并行执行(默认上限 3 路),同一个人的任务仍按顺序;回复 @ 到人,群静音也收得到

选中一张旧图说「你重新做这个」

先取回被引用的消息,图片重新下载落盘,模型再看一遍

机器人另外承担:白名单认领、每人一份独立会话记忆、任务队列、超时兜底、每日汇报、危险动作拦截。 图片与文件消息的处理见 BOT-ATTACHMENTS.md,群内免 @ 见 BOT-GROUP-MODE.md,并发与引用回溯见 BOT-RUNTIME.md。

安装

前置条件:一个飞书自建应用、一台能运行 DeepSeek Harness 的机器、Node 22+。 应用需要开通的 scope 见权限。

方式一:设置页向导(推荐)

装好插件后,DSH 设置面板左栏会多出「飞书连接」,内含四步向导 (步骤条 1 建应用 → 2 填凭据 → 3 选会话 → 4 自检,完成一步点亮一项):

  1. 建应用 —— 直达开放平台的链接,附 11 项权限清单,可一键复制

  2. 填凭据 —— App ID / Secret,保存时先校验再落盘,凭据错误不会写坏文件

  3. 选会话 —— 「扫描我的会话」列出机器人所在会话,无需手抄 32 位 oc_ 串

  4. 自检 —— 九项逐个真调接口:凭据文件、MCP 挂载、应用凭据、机器人身份、会话列表、 目标会话、读聊天记录、上传文件、云空间

自检每项下方一行小字是判定依据:凭据文件末四位、token 剩余秒数、机器人应用名、会话名、 file_key 前几位。九项全绿时底部提示「工具已经挂进 profile,重启 DSH 之后 mcp__feishu__* 就能用了」。 失败项会给出该开通的 scope 与跳转链接,并支持「一次开通全部缺失权限」。

自检不往会话里发任何内容:读历史只读 1 条,上传只传 20 字节且不发送。

方式二:命令行安装

只装 DSH 里的飞书设置页(不装 MCP、不跑安装器)时,直接从本仓库装插件包:

dsh plugin --profile web add "github:yinsang0910-star/dsh-feishu#path:packages/dsh-plugin"

#path:packages/dsh-plugin 不能省——仓库根是 pnpm workspace,只有这个子目录是 DSH bundle(dsh.bundle.patch + dsh.client.platform: web,dist/ 已随仓库提交,装完不需要构建)。装完重启 DSH,设置里会多出「飞书」页。

要连机器人一起装,再跑下面的安装器:

pnpm install && pnpm build

node scripts/install.mjs \
  --app-id cli_xxxxxxxx \
  --app-secret xxxxxxxx \
  --chat-id oc_xxxxxxxx

安装器执行四步,每步可单独重跑:

  1. 校验凭据 —— 实际换取一次 tenant_access_token 并列出会话,凭据错误立即报出

  2. 写密钥文件 —— ~/.config/dsh/feishu.env,权限 0600

  3. 安装 MCP 启动包装 —— 生成 dsh-feishu-mcp 脚本(stdio 子进程的环境变量会被清空, 密钥需由包装脚本自行 source)

  4. 修改 profile —— 幂等地向 cordis.patch.yml 写入带哨兵的托管块

重启 DSH 后,让模型报告工具清单:

echo '你有哪些 mcp__feishu__ 工具?只列名字' | dsh --profile headless --json -

--uninstall 只回滚第 3、4 步,不改动密钥文件。可选参数:--profile <名字>(默认 headless)、 --dir <安装目录>、--skip-check。

关于建应用的两点

扫码建应用:第 2 步的「扫码创建」走飞书官方 RFC 8628 设备授权流程。 二维码内容是 open.feishu.cn/page/launcher?user_code=...,手机确认后应用自动创建, App ID 与 Secret 直接写入本机 feishu.env——浏览器全程不接触 secret,也不需要手抄任何一串。

权限仍需手动开通:应用创建后按第 1 步的清单勾选(提供深链与一键复制)。 飞书没有允许第三方代开权限的通道,这一步无法省略。

只挂 MCP,不要机器人

MCP server 已打成自包含单文件(SDK 与 core 都打包在内),不需要 pnpm install,也不从 npm 安装。

Claude Desktop:从 Releases 下载 dsh-feishu-mcp-<版本>.mcpb,双击安装,在配置面板填入 App ID 与 App Secret。 (同一产物也在镜像仓库 dsh-feishu-mcp 的 Releases 中。)

其他 stdio 客户端:

npx github:yinsang0910-star/dsh-feishu-mcp

或从 Releases 下载 dsh-feishu-mcp-<版本>.mjs,node dsh-feishu-mcp.mjs 即可运行(1.5 MB,含全部依赖)。

Docker(镜像里不含任何凭据,运行时注入):

docker build -t dsh-feishu-mcp .
docker run --rm -i -e FEISHU_APP_ID=cli_xxx -e FEISHU_APP_SECRET=xxx dsh-feishu-mcp

未配置凭据时进程仍会启动并完成握手,tools/list 正常返回 43 个工具,只有真正调用工具才返回「飞书凭据未配置」——目录站与客户端的自检因此不会看到「server 崩了」。

提供 FEISHU_APP_ID / FEISHU_APP_SECRET 即可运行。挂进 DSH 的方式是编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml:

- insert:
    - id: mcp-feishu
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: feishu
        command: npx
        args: ['-y', 'github:yinsang0910-star/dsh-feishu-mcp']
        # feishu_ask 最多阻塞 600s,工具超时必须比它大
        toolCallTimeoutMs: 660000
        env:
          FEISHU_APP_ID: 'cli_xxx'
          FEISHU_APP_SECRET: 'xxx'
          FEISHU_DEFAULT_CHAT_ID: 'oc_xxx'

serverName: feishu 决定工具前缀(mcp__feishu__*),改动它前缀随之改变。 改代码时改为运行本仓库产物:command: node + args: ['/绝对路径/packages/mcp/dist/server.js']。

镜像仓库 yinsang0910-star/dsh-feishu-mcp 由 scripts/publish-mcp-repo.ps1 单向同步,请勿在该仓库直接改代码。

装完之后

建议同时装记忆插件

本项目只保证会话内连续(同一人 + 同一工作目录)。跨会话、跨项目的长期记忆建议交给 dsh-mnemon(作者 @Grivn,MIT)。

不装的症状很具体:今天告诉它「我叫什么、别用术语」,明天开新会话它一样不知道。装了之后 这些写进 ~/.mnemon/runtime/,每次进上下文。

需要注意:机器人在飞书里跑的是 headless profile,桌面端装过的记忆插件对它无效—— headless 默认只挂了 base + headless 两个 bundle。一条命令补齐:

bash services/agent-workspace/install-mnemon.sh      # 幂等,已装则只做检查

原理、验证方法、三个坑与回滚见 MNEMON.md。

先看一眼指令

/help 返回一张可点击的卡片:切换模型、切换 reasoningEffort、查看状态、管理工作区、 开关群内是否需要 @。完整指令见 BOT-COMMANDS.md。

权限

在飞书开放平台「权限管理」开通以下 scope,修改后需要发布版本才生效:

scope

用于

im:message:send_as_bot

所有发送类工具

im:resource

文件 / 图片的上传下载

im:chat

列会话、列成员

im:message.group_msg

读群聊历史(feishu_recent / feishu_ask)

im:message.p2p_msg:readonly

读单聊历史

drive:drive

云空间

docx:document · docx:document:create

读写云文档

wiki:wiki:readonly

知识库

bitable:app

多维表格

contact:user.id:readonly

邮箱 / 手机 → open_id

两项不属于 scope 配置:

  • 机器人必须先被拉进群,feishu_chats 只列它已加入的会话。

  • 卡片要支持原地更新,发卡时必须带 config.update_multi = true(本项目自带模板默认已带)。

43 个工具

工具名在客户端里带前缀,形如 mcp__feishu__feishu_send_text。参数细节见 TOOL-CONTRACT.md,逐个工具的说明与危险等级见 MCP-TOOLS.md。

分组

工具

身份 / 卡片

feishu_whoami 查机器人身份与可达会话 · feishu_send_info_card 发「标签+值」信息卡

发消息

feishu_send_text 纯文本 · feishu_send_card 任意卡片 JSON · feishu_update_card 原地刷新 · feishu_reply 引用回复

文件

feishu_send_file 本地文件(30MB,可批量 + 说明文字)· feishu_send_image 图片(10MB)· feishu_download 把消息附件落到本地

上下文

feishu_recent 读最近消息(时间正序、默认滤掉机器人自己)· feishu_ask 发问并等人回答

会话与成员

feishu_chats 列机器人所在会话 · feishu_members 列成员

群与消息管理

feishu_recall 撤回消息(删群里的旧文件也走它)· feishu_forward 转发 · feishu_pin 置顶 · feishu_chat_update 改群名与权限 · feishu_chat_create 建群 · feishu_chat_dissolve 解散群 · feishu_chat_files 列群文件 · feishu_file_delete 删云空间文件

多维表格

feishu_bitable_tables · feishu_bitable_fields(带类型码与写入形态)· feishu_bitable_records(单元格渲染成人话)· feishu_bitable_add · feishu_bitable_update · feishu_bitable_delete

表格 / 文档 / 云空间 / 知识库

feishu_sheet_create · feishu_sheet_read(按 A1 区间读值)· feishu_drive_list · feishu_doc_read · feishu_doc_blocks(按块读结构)· feishu_doc_create · feishu_wiki_spaces · feishu_wiki_node · feishu_user_lookup

飞书没有「群文件列表」这个端点:群里的文件是挂在消息上的附件,feishu_chat_files 的实现是 翻最近的群消息再筛出 file / media / audio 类型。删除同理——删的是那条消息,所以走 feishu_recall。

另有卡片模板(progressCard / resultCard / askCard / chatListCard)与统一错误翻译: scope 未开通时,FeishuApiError.missingScopes 把需要开通的项拼进错误文本,模型可据此提示。

设计取舍

为什么不是 @larksuiteoapi/lark-mcp

官方 lark-mcp 覆盖的是广度:把飞书 OpenAPI 按元数据整体暴露给模型。它的定位没问题,但 「把 IM 当作 agent 界面」最要紧的四项能力它不具备:

缺口

lark-mcp

本项目

发送本地文件

没有 im.v1.file.create 这条链路,本地文件无法进入会话

feishu_send_file / feishu_send_image:路径 → 上传 → 发消息

会话上下文

只有「列消息」的原始接口

feishu_recent:拍平成 [时间] 发送人:内容,模型可直接阅读

阻塞式提问

标准 MCP 是请求-响应模型,没有「等待人回答」

feishu_ask:发带按钮的卡片,阻塞直到点击,把答案带回

卡片原地更新

只能发卡,不能改卡,进度只能刷屏

feishu_update_card:聊天里只留一个气泡,反复刷新

需求是「用脚本批量调用飞书 OpenAPI」时,lark-mcp 更合适;需求是「让 agent 在飞书里像同事一样干活」时, 缺的正是上面四项。

架构

架构

packages/
├── core/          @yisang0910/core      API 客户端 · 类型 · 卡片模板(零第三方 HTTP 依赖)
├── mcp/           @yisang0910/mcp       43 个工具的 MCP server
├── gateway/       @yisang0910/gateway   卡片问答网关(HTTP + 可选长连接)
└── dsh-plugin/    @yisang0910/plugin    DSH 设置页(在 Web UI 里填凭据、测连接)
services/
├── feishu-bot/        飞书长连接机器人 + 一键部署脚本
└── agent-workspace/   工作区清理器 + 记忆插件安装脚本
docs/             架构 · 契约 · 工具清单 · 各模块说明

改动代码前请遵守两条硬约束:

  1. stdout 只能输出 MCP 的 JSON-RPC。任何 console.log 都会破坏协议,日志一律走 stderr。

  2. 工具 handler 必须整体 try/catch,异常翻译成 fail(...) 返回,不得向上抛出。

状态

版本 0.1.0(Release v0.1.0), 实验阶段:接口与工具名仍可能变化,暂不保证向后兼容。

  • 194 个单测(core 117 + gateway 77),CI 执行 typecheck + test + build + 打包冒烟

  • 下载:Release 提供 dsh-feishu-mcp-0.1.0.mcpb(Claude Desktop 双击安装)与 dsh-feishu-mcp-0.1.0.mjs(自包含单文件,node 直接运行),附 SHA256SUMS.txt

  • 暂未发布到 npm:npm 的 2FA 政策阻塞了首次发布,原因与出路见 NPM-PUBLISH.md。插件与 MCP 均可直接从 GitHub 安装 (dsh plugin … add github:… / npx github:…),不依赖 npm

  • 已知限制:feishu_ask 轮询存在延迟与配额成本、单文件上限 30 MB、无多实例锁 —— 详见 ARCHITECTURE.md

文档

按阅读顺序排列:

文档

讲什么

ARCHITECTURE.md

分层、关键取舍、已知限制

TOOL-CONTRACT.md

写工具前必读的实现契约

MCP-TOOLS.md

43 个工具逐个说明、危险等级、还缺什么

MNEMON.md

推荐搭配的记忆插件:为什么、怎么装、怎么验

DEPLOY.md

部署到服务器

GATEWAY.md

网关协议与部署

BOT-INTEGRATION.md

机器人与网关怎么对接

BOT-COMMANDS.md

全部指令 + 换模型/换思考强度怎么落地

BOT-RUNTIME.md

并发、回复 @ 到人、引用旧消息回溯

BOT-ATTACHMENTS.md

图片/文件消息怎么收(read_image 真看图)

BOT-GROUP-MODE.md

群聊不用 @ 也能用(/要@ /免@)

AGENT-WORKSPACE.md

工作区归档规则与清理分级

NPM-PUBLISH.md

发布到 npm 的阻塞点与出路

另有两份仓库级说明:CONTRIBUTING.md(环境、目录、提交前要跑什么)与 SECURITY.md(凭据放在哪、怎么报告问题、设计上的边界)。

License

MIT

Available Tools

43 tools
feishu_ask发问并等人回答(会阻塞)A

在飞书里发一张带选项的卡片问一个问题,然后等人回答,把答案拿回来。用在真的缺关键信息、又没法自己查的时候:要用户拍板方案、要一个他没写在文档里的参数、要确认某个动作要不要执行。⚠️ 这个调用会阻塞(默认 120 秒,最多 600 秒),期间什么都做不了,所以不要滥用,一次任务最多问一两个问题;能靠 feishu_recent 从上下文里读出来的、能自己查到的、能用合理默认值继续的,都不要问。回答来源有两条:①点卡片上的选项按钮(需要网关在跑,毫秒级返回);②对方直接打字回一句。两条都走不通才会超时。返回 answered=true 时 text 就是对方的原话;answered=false 表示超时(不是报错),此时应当按默认方案继续或换个问法,不要反复重试。

Inputs: question (required), chat_id, options, timeout_seconds, +1 more.

feishu_bitable_add新增多维表格记录A

往某个数据表里新增一条记录,返回 record_id(后续更新要用)。这是写操作,会真的改用户的表:不确定字段名和类型时,先调 feishu_bitable_fields 看定义、feishu_bitable_records 看现有数据的写法,别凭猜写。fields 的 key 必须是字段名(不是 field_id),值形态要匹配字段类型:文本传字符串、数字传数字、日期传毫秒时间戳、单选传选项字符串、多选/人员/附件/关联传数组。适合:把对话里的结论、待办、采集到的数据落进表。不适合:批量导入几百条(逐条调用会很慢)。

Inputs: fields (required), table_id (required), app_token (required).

feishu_bitable_delete删除多维表格记录A
Destructive

按 record_id 删掉一条记录。不可撤销:删了就没了,没有回收站。record_id 必须先通过 feishu_bitable_records 查到,别自己编。一次只能删一条,要删多条就多次调用。如果用户只是想改状态(比如改成「已完成」),用 feishu_bitable_update,别删。

Inputs: confirm (required), table_id (required), app_token (required), record_id (required).

feishu_bitable_fields数据表的字段定义A
Read-only

列出某个数据表的全部字段:字段名、field_id、类型码 + 中文类型名,以及这个字段写入时该传的值形态。新增/更新记录之前先调这个:飞书不同字段类型吃的 JSON 形态完全不同(文本传字符串、日期传毫秒时间戳、人员传 [{"id":"ou_xxx"}]、附件传 [{"file_token":"box_xxx"}]),先看类型码再写 fields,能避免 1254001 / 1254045 之类的字段校验报错。字段名就是 feishu_bitable_add / feishu_bitable_update 里 fields 的 key,必须一字不差。只返回文本,不修改数据。

Inputs: table_id (required), app_token (required).

feishu_bitable_records查询多维表格记录A
Read-only

读取某个数据表里的记录,每条都带 record_id,并把字段值展开成人话(人员显示名字、附件显示文件名、多选用顿号连接、日期显示原始毫秒值)。适合:核对数据、找要改的那条记录(先查到 record_id 再 update)、给用户汇报表里有什么。record_id 是更新记录的唯一凭据,所以查询结果里一定会带上。limit 默认 50、最大 500;has_more=true 时把返回的 page_token 传回来继续翻页。只返回文本,不修改数据。

Inputs: table_id (required), app_token (required), limit, page_token.

feishu_bitable_tables多维表格里的数据表A
Read-only

列出一张飞书多维表格(Base)里包含哪些数据表,返回每张表的 table_id 与表名。这是所有 bitable 操作的入口:后续查字段、查记录、加记录都要 table_id,而 table_id 只能从这里拿到(用户一般只给 app_token 或一条 Base 链接)。app_token 就是 Base 链接里 /base/ 后面那一串(如 HMr9bcTJcabU8KsD6UGcwVWln9e)。只返回文本,不修改任何数据,可放心在探索阶段调用。不适合:已有 table_id 只是要看字段(用 feishu_bitable_fields);要看记录内容(用 feishu_bitable_records)。

Inputs: app_token (required).

feishu_bitable_update更新多维表格记录A

按 record_id 更新某条记录的部分字段(只覆盖 fields 里出现的字段,其余字段不动)。写操作,会真的改用户的表:record_id 必须先通过 feishu_bitable_records 查到,别自己编。值形态的规矩和 feishu_bitable_add 一样:文本传字符串、数字传数字、日期传毫秒时间戳、单选传选项字符串、多选/人员/附件/关联传数组。适合:修正一条错数据、推进状态、补填附件。不适合:整表批量改(逐条调用)。

Inputs: fields (required), table_id (required), app_token (required), record_id (required).

feishu_chat_announcement读 / 改群公告A

群公告是群顶部那条所有人都能看到的说明。action=get 读现有内容;action=set 改写(mode=replace 整段替换,mode=append 接在末尾)。改公告需要机器人是群主或管理员。

Inputs: action (required), chat_id (required), mode, content.

feishu_chat_create建一个群A

新建群并把指定的人拉进来。机器人建完就是群主,后续能改群名、发消息、置顶。成员要用 open_id(ou_ 开头);不确定 id 先用 feishu_user_lookup 查。

Inputs: name (required), description, member_open_ids.

feishu_chat_dissolve解散一个群A
Destructive

解散群。不可撤销:群和群里的消息都会消失,机器人必须是群主。执行前先跟人确认一遍群名和群 id。

Inputs: chat_id (required), confirm (required).

feishu_chat_files列群里发过的文件A
Read-only

列出群里发过的文件(对应飞书群聊顶部的「文件」标签页),带消息 id、文件名、大小、发送时间。飞书没有独立的「群文件列表」接口,文件是挂在消息上的,所以这里翻最近的群消息再筛出来。要删某个文件:拿这里的 message_id 去调 feishu_recall。

Inputs: chat_id (required), pages, keyword, page_size.

feishu_chats机器人所在的会话A
Read-only

列出机器人当前所在的所有会话(群 + 单聊),返回 chat_id 与名字,供后续发送/读历史时当 target 用。只返回文本,不会往飞书里发任何消息,所以可以放心在探索阶段调用。不确定"该往哪个群发"、或者需要 chat_id 但手上只有群名时,先调这个。人数只在飞书真的返回了 member_count 时才显示;需要确切成员名单请改用 feishu_members。with_members=true 会额外对每个群发一次成员请求(前 5 个名字),会话多时会明显变慢。

Inputs: limit, with_members.

feishu_chat_update改群信息(群名 / 描述 / 谁能拉人)A

改群名、群描述,或调整「谁能邀请成员 / 谁能分享群名片 / 谁能 @所有人」。只传要改的字段,其它保持不动。

Inputs: chat_id (required), name, description, at_all_permission, +2 more.

feishu_doc_append往文档末尾追加正文A

在已有文档最后追加若干段落(每个字符串一段)。配合 feishu_doc_create 建空文档后往里写。只能追加纯文本段落:加粗、表格、图片、标题层级这些富文本结构目前不支持。要改文档中间的内容请用 feishu_doc_blocks 找到块再处理(尚未开放块级编辑)。

Inputs: paragraphs (required), document_id (required).

feishu_doc_blocks读文档结构化块A
Read-only

按块(block)读一篇云文档的结构:每块有 block_id、block_type 与内容。和 feishu_doc_read 的区别:doc_read 给的是拼接好的纯文本,适合通读;doc_blocks 保留段落/标题/表格/图片块的分块结构,适合定位「第几段」「哪个表格」以及后续按 block_id 做精细操作。飞书文档的块类型是数字编码(如 2=文本、3-11=各级标题、31=表格),本工具会把能识别的文字内容抽出来,识别不了的块只给类型码。

Inputs: document_id (required), max_pages, page_size.

feishu_doc_create新建飞书文档A

在云空间里新建一个空的 docx 文档,返回 document_id,后续可用 feishu_doc_read 读回校验。使用场景:需要把结果沉淀成一份飞书文档、并且希望它在云空间里可被同事打开时。只建空文档,不写正文内容;需要正文请建完后再用其它编辑能力写。前置条件(重要):当前应用缺 docx:document:create,调用大概率返回 99991672。真失败了不要重试、也不要换参数硬试,去开放平台开通 docx:document:create 并重新发布版本。folder_token 不填等于建在应用自己的根目录(通常同事看不到,建议显式给一个已共享的文件夹)。

Inputs: title (required), folder_token.

feishu_doc_read读飞书文档正文A
Read-only

读取一个 docx 文档的纯文本正文(不含图片、表格结构、评论),用于总结、摘录、问答。使用场景:手上已有 document_id,想看文档写了什么。document_id 从哪来:feishu_drive_list 里 docx 条目的 token;或者知识库场景下 feishu_wiki_node 返回的 obj_token(注意是 obj_token,不是 node_token)。前置条件(重要):应用目前有 docs:doc,但没有 docx:document:readonly,读已有文档很可能返回 99991672;拿到这个错误时,需要在开放平台开通 docx:document(或只读版)并重新发布版本后才生效。不要用它读电子表格(用表格工具)或多维表格(用 feishu_bitable_* 工具)。只读,不改文档。

Inputs: document_id (required), max_chars.

feishu_download把用户发来的附件下载到本地A

下载某条飞书消息里的附件(文件或图片)到本地磁盘,返回绝对路径,之后就能用 bash/脚本处理它。典型链路:用户发来一个 docx → 本工具下载 → 本地解析/改写 → feishu_send_file 发回。不传 file_key 时会自动从消息 content 里取(file_key 或 image_key);落盘名优先用消息里自带的名字,没有就用 _<fileKey前8位>.<后缀>,同名文件自动加 -1 后缀不覆盖。

Inputs: message_id (required), kind, dest_dir, file_key.

feishu_drive_list列云空间文件A
Read-only

列出云空间(我的空间)里某个文件夹下的文件,返回类型、名字、token、修改时间。使用场景:模型只知道"有个文档/表格",需要先找到它的 token 时;或者要盘点某个目录里都有什么。folder_token 不填等于根目录。返回的 token 就是下一步要用的钥匙:docx 类型的 token 传给 feishu_doc_read 读正文;bitable 类型的 token 传给 feishu_bitable_tables 看表结构。前置条件:应用需要有云空间读取权限(drive:drive 或 drive:drive.metadata:readonly),且目标文件夹已共享给该应用。只读操作,不会修改云空间任何内容。

Inputs: limit, folder_token.

feishu_file_delete删云空间里的文件(不是群消息附件)A
Destructive

删除云空间(我的空间/共享空间)里的文件、文档、表格、多维表格或空文件夹。注意:群聊里发的文件是消息附件,那个用 feishu_recall 删消息;这里的 file_token 是云文档体系里的 token(来自 feishu_drive_list),两者不通用。

Inputs: file_token (required), type.

feishu_forward转发一条消息到别的会话A

把某条消息原样转发到另一个群或某个人(不经过改写,卡片/图片/文件都保持原样)。适合:把结果同步给另一个群、把用户发的图转给负责人。

Inputs: to (required), message_id (required), to_type.

feishu_members会话成员名单A
Read-only

列出某个会话(群/单聊)里的成员,返回名字 + open_id。适合:确认某人在不在群里、拿到 open_id 用于 @ 或私聊、核对群规模。不适合:只是想看有哪些群(用 feishu_chats);想读聊天内容(用上下文相关工具)。chat_id 不填时用 FEISHU_DEFAULT_CHAT_ID;两者都没有会直接报错说明。只返回文本,不往飞书发消息。

Inputs: limit, chat_id.

feishu_merge_forward把多条消息合并成一份记录转发A

把 2~50 条消息打包成一张「会话记录」卡片发到别处,适合「把这段讨论转给另一个人看」。和 feishu_forward 的区别:forward 是一条一条转,merge_forward 是合成一份带来源的摘要。

Inputs: receive_id (required), message_ids (required), receive_id_type.

feishu_permission_member文档/文件夹的协作者(加人、看谁有权限、移除)A

管云文档的协作者。action=add 把一个人加进协作者(perm=view 可读 / edit 可编辑 / full_access 可管理);action=list 看现在有哪些人、各自什么权限;action=remove 移除一个人。member_type=openid 时 member_id 传 open_id(ou_ 开头),先 feishu_user_lookup 拿到。注意 token 是云文档 token,不是消息附件。

Inputs: token (required), action (required), perm, type, +2 more.

feishu_pin置顶 / 取消置顶一条消息A

把一条消息钉在群顶部(公告性质的关键结论),或取消置顶。适合:把最终结论、规范文件、长期有效的清单钉住。

Inputs: message_id (required), unpin.

feishu_reaction给消息加表情回应 / 查看 / 撤掉A

表情回应是飞书里最轻的「我看到了 / 收到 / 干完了」信号,不占聊天版面。action=add 加一个(emoji_type 用飞书的表情名,如 SMILE、THUMBSUP、DONE、OK、HEART);action=list 看这条消息上有谁回应了什么(返回 reaction_id,撤掉时要用);action=remove 撤掉一个(只能撤机器人自己加的)。

Inputs: action (required), message_id (required), emoji_type, reaction_id.

feishu_recall撤回一条消息A
Destructive

撤回机器人自己发出去的消息(飞书只允许撤回 24 小时内的、且只能撤回自己发的)。也用于「删掉群里那个旧文件」——文件是挂在消息上的,删了消息文件就一起没了。不是自己发的消息会失败,这不是权限问题而是飞书规则。

Inputs: message_id (required).

feishu_recent读会话最近的聊天(模型的上文)A
Read-only

拉取某个飞书会话最近的消息,按时间正序(早→晚)拍平成文本,让模型知道「刚才聊了什么、谁在说」。典型用法:被叫醒后、要回复之前、要接着上文改文件之前,先调一次这个再动手;也用来确认某个人刚才发的那句话的 message_id,好配合 feishu_reply / feishu_download 用。默认会过滤掉机器人自己发的消息(对模型是噪音),需要看自己说过什么时传 include_bot=true。format=compact 只有「时间 发送人:内容」,适合快速读;format=full 额外带 message_id / msg_type / sender_id,适合接下来要针对某条消息做操作。要「发问并等人回答」不要用这个(轮询要自己写),用 feishu_ask。

Inputs: limit, format, chat_id, include_bot, +1 more.

feishu_reply引用回复某条消息A

在会话里对某条消息做引用回复(飞书会把它挂在原消息下面)。适合:用户点名提问、需要保留"回的是哪一条"的上下文、在刷屏群里避免歧义。不适合:只是想发一条新消息(用 feishu_send_text);需要排版或要后续刷新(用卡片相关工具,回复接口只发纯文本)。

Inputs: text (required), message_id (required).

feishu_send_card发一张交互卡片A

发一张飞书交互卡片(JSON 卡片结构,原样提交,不做模板加工)。适合:需要排版的内容(分块、分隔线、备注脚注)、要展示多字段状态、以及之后需要原地刷新的那类消息。不适合:只有一两句话的短提示(用 feishu_send_text 更直接)。想让卡片后续可被 feishu_update_card 更新,必须在卡片里写 config.update_multi = true。最小可用卡片示例:{ "config": { "wide_screen_mode": true, "update_multi": true }, "header": { "template": "blue", "title": { "tag": "plain_text", "content": "构建结果" } }, "elements": [ { "tag": "div", "text": { "tag": "lark_md", "content": "状态:通过\n耗时:42s" } }, { "tag": "hr" }, { "tag": "note", "elements": [ { "tag": "plain_text", "content": "由 dsh-feishu 发送" } ] } ] }

Inputs: card (required), target.

feishu_send_file把本地文件发进会话A

把本地磁盘上的文件上传并发到飞书会话(文档、压缩包、日志、报表、生成的代码包都行)。这是本项目最核心的工具:任何"我在本地做好了,给你看看"的场景都走它。单个文件上限 30MB,超了会直接报错并给出替代方案。要一次发多个文件,把第一个放 path,其余放 paths;caption 非空时会先发一条纯文本说明再发文件,适合"这是刚才跑出来的结果,重点看第 3 页"。纯图片想直接预览的改用 feishu_send_image;只是想说话不要用这个,用 feishu_send_text。

Inputs: path (required), name, paths, target, +1 more.

feishu_send_image把本地图片发进会话A

把本地图片以"图片消息"发到飞书会话,收到的人可以直接在聊天里看到缩略图、点开大图。只在需要预览时用;要发 PDF、压缩包、代码等非图片文件请用 feishu_send_file。支持 png / jpg / jpeg / gif / webp / bmp,单张上限 10MB。截图、图表、设计稿的效果图都适合走这条。

Inputs: path (required), target, caption.

feishu_send_info_card发一张信息卡A

把"标签 + 值"这类结构化信息渲染成一张飞书卡片发出去。适合汇报状态、列出项目、展示统计;不适合长文本(那用 feishu_send_text)。

Inputs: title (required), fields (required), footer, target.

feishu_send_text发一条纯文本A

往指定会话发一条纯文本消息。适合短结论、一句话提示、快速确认、临时回复。不适合:超过约 30 行的长内容、需要排版/表格/多段落层级的内容 —— 那些改用 feishu_send_card(卡片能分块、加分隔线、加备注,可读得多)。也不适合需要后续原地刷新的场景:文本发出去就改不了,要更新请用卡片 + feishu_update_card。

Inputs: text (required), target.

feishu_sheet_create新建电子表格A

在飞书云空间里新建一张空的电子表格(Sheets),返回 spreadsheet_token 与可分享的链接。写操作,会在用户的云文档里真的建一个文件。适合:用户要"建个表记录一下"这类从零开始的场景。不适合:已经有表格只是要写数据(应该拿现有 spreadsheet_token 去读写,而不是新建)。folder_token 不填就建在"我的空间"根目录;要建进某个文件夹,先用云空间相关工具拿到文件夹 token。建完可以接着用 feishu_send_text 把链接发给用户。

Inputs: title (required), folder_token.

feishu_sheet_meta看电子表格有哪些工作表A
Read-only

列出表格里每个工作表的 sheet_id、标题、行列数。写值前先看这个:飞书的写入接口要 sheet_id,而表格链接里给的是 spreadsheet_token,两者不是一回事。feishu_sheet_write 不带 sheet 前缀时会自动取第一个工作表,所以简单场景可以跳过这一步。

Inputs: spreadsheet_token (required).

feishu_sheet_read读电子表格单元格A
Read-only

按 A1 区间读一个电子表格的值,返回二维数组(行 × 列)。区间写法:Sheet1!A1:D20(带表名更稳),或 A1:D20(默认第一个工作表)。读整列可以用 Sheet1!A:A。只能读值和公式结果,读不到样式、批注、合并单元格信息。配合 feishu_sheet_create 新建表;写入目前没有开放(飞书的写入接口要求先拿到 sheet_id,需要先读一次拿元数据,暂未支持)。

Inputs: range (required), spreadsheet_token (required).

feishu_sheet_write往电子表格写值 / 追加行A
Destructive

把二维数组写进表格。range 写 "Sheet1!A1:B2"(带表名)或只写 "A1:B2"(默认第一个工作表)。mode=overwrite 覆盖区间内原有的值;mode=append 接在已有数据末尾往下追加(不覆盖)。values 是行 × 列:[[1,"甲"],[2,"乙"]] 表示两行两列。空字符串写空格,null 会留空。只写值,改不了样式、合并单元格、公式(写进去的字符串会被当文本)。

Inputs: range (required), values (required), spreadsheet_token (required), mode.

feishu_update_card原地更新已发出的卡片A

把已发出的卡片整张替换成新内容,聊天里不新增消息气泡 —— 这是"不刷屏"的关键手段。典型用法:先发一张进度卡,之后反复 update 同一个 message_id 推进进度 / 换成结果卡。限制:只有发出时带 config.update_multi = true 的卡片才能更新,否则飞书会报错;也不能更新别人发的消息,只能用自己发出的 message_id。不适合:想让用户看到历史过程的每一步(每次都会覆盖,只留最新一版);需要保留每步记录就用 feishu_send_text 逐条追加。

Inputs: card (required), message_id (required).

feishu_user_lookup查飞书用户A
Read-only

用邮箱、手机号或 open_id 查飞书用户,返回 open_id 与名字。使用场景:手上只有同事邮箱/手机号,需要 open_id 才能私聊或 @ 他;或者拿到 open_id 后想确认这人是谁。用法优先级:给了 open_id 就查这一个人的详情(名字、邮箱、手机号最全);否则按 emails / mobiles 批量查(两个都给会各查一次);都不给会直接报错说明用法。重要:查到记录但 open_id 为空,说明该邮箱/手机号不在本企业通讯录(或不在应用可见范围内),这不是 bug,也不能拿它当发送目标。拿到 open_id 后可以直接作为 feishu_send_text 的 target 单聊这个人。前置条件:应用需要通讯录权限(如 contact:user.id:readonly),且用户在应用可见范围内。只读。

Inputs: emails, mobiles, open_id.

feishu_whoami我是谁 / 默认往哪发A
Read-only

返回机器人身份(open_id、名字)与当前默认会话配置。在发任何消息之前不确定目标会话时,先调这个。如果 default_chat_id 为空,说明必须先指定 target 才能发送。

Inputs: no named parameters.

feishu_wiki_node查知识库节点A
Read-only

知识库节点查询:给 token 就查这个节点(node_token 或 obj_token 都行),给 space_id 而不给 token 就列出该空间的根节点。使用场景:从知识库链接里拿到一段 token,需要知道它对应哪篇文档/哪张表;或者要遍历某个空间有哪些内容。关键点:返回里的 obj_token 才是真正文档/表格的 token——读内容、读表要用 obj_token;node_token 只用于继续在 wiki 里翻节点,传给 feishu_doc_read 会失败。前置条件:应用需被加入该知识库并有 wiki 读权限。只读,不改节点。

Inputs: token, space_id.

feishu_wiki_spaces列知识库空间A
Read-only

列出机器人能看到的飞书知识库(wiki)空间,返回 space_id 与名字。使用场景:要按知识库找文档时,先拿空间列表,再用 feishu_wiki_node(传 space_id)列出根节点。前置条件:应用需要被加入知识库(知识库设置 → 成员/应用),否则返回空列表——空列表不代表接口坏了,而是这个应用还没被加入任何知识库,需要在知识库设置里添加此应用。只读,不改知识库结构。

Inputs: limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 43 tools

    Disambiguation4/5

    Descriptions explicitly cross-reference siblings with "不适合…请用 X" guidance, so send_text/send_card/send_info_card/send_file/send_image/reply are mostly separable, as are forward vs merge_forward and doc_read vs doc_blocks. Remaining soft spots: send_info_card vs send_card (one is a label/value convenience wrapper over the other), and doc_read vs doc_blocks both read the same document.

    Naming Consistency3/5

    Everything is snake_case with a feishu_ prefix, but the verb/noun ordering and verbs themselves are inconsistent: feishu_send_text and feishu_sheet_create put the action first, feishu_bitable_tables and feishu_doc_read are resource-first, and creation is variously create (sheet/doc/chat) vs add (bitable) vs send (message). Several tools drop the action entirely (feishu_forward, feishu_pin, feishu_whoami, feishu_recent, feishu_ask, feishu_recall), and some multiplex actions via parameters (feishu_reaction, feishu_chat_announcement) while others spawn separate tools.

    Tool Count2/5

    43 tools is large and heavy for a single MCP server; messaging, chat admin, drive, docs, sheets, bitable, wiki and permissions are all packed in. The breadth is real, but an agent picking from 43 similarly-named feishu_* tools pays a real selection cost, and some near-duplicates (send_card vs send_info_card, sheet_meta vs sheet_read) inflate the count.

    Completeness4/5

    Coverage is unusually broad: full CRUD on bitable records, sheet read/write/create/meta, doc read/create/append, drive listing, wiki navigation, chat lifecycle, permissions and reactions. Gaps are acknowledged rather than hidden — no block-level doc editing, no adding/removing members from an existing group, and no message search or message edit.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A tool designed to help users connect AI Agents with the Feishu/Lark platform, encapsulating Feishu/Lark Open Platform API interfaces as MCP tools for document processing, conversation management, calendar scheduling and more.
      33,913 npm
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control Feishu (Lark) through structured tools for messaging, calendar, tasks, and documents.
      3
      MIT