飞书智控台 yinsang0910-star/dsh-feishu

dsh-feishu

让智能体真正住进飞书。
MCP server · 长连接机器人 · 卡片网关 · DSH 设置页 · MIT

它是什么

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

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

它由三个角色组成，各自负责一段：

| 角色 | 职责 |
| feishu-bot | 常驻长连接。身份校验、会话管理、任务队列、进度卡、审批按钮。自身不执行任务 |
| agent | 实际执行方。dsh --profile headless 调用模型，36 个 MCP 工具是它的操作面 |
| gateway | 只做一件事：把卡片按钮的点击精确投递给正在等待回答的那次 feishu_ask |

它解决什么问题

| 你说 | 它做 |
| 把上周的纳米技术报告发我 | 在工作区找到 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 字节且不发送。

方式二：命令行安装

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. 修改配置档 —— 幂等地向 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 正常返回 36 个工具，只有真正调用工具才返回「飞书凭据未配置」——目录站与客户端的自检因此不会看到「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（本项目自带模板默认已带）。

36 个工具

工具名在客户端里带前缀，形如 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 36 个工具的 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 | 36 个工具逐个说明、危险等级、还缺什么 |
| 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