飞书机器人插件icanotcode/dsh-feishu-bot

DeepSeek Harness 飞书机器人

从飞书向本机 Harness 发起任务，在原消息下接收答复与文件。

Tests
License: MIT
Node.js ≥22.13

简体中文 · English

快速开始 · 飞书接入指南 · 常见问题 · 反馈问题

简介

dsh-feishu-bot 让一个 DeepSeek Harness 服务器连接多个飞书机器人，每个机器人对应独立项目。在 Harness 的 Plugin list 中展开插件卡片，即可选择或添加机器人，分别配置应用凭据、事件接收方式和项目目录。

插件提供 开发者服务器（HTTP Webhook） 和 长连接（WebSocket） 两种接入方式：已有公网地址、ngrok 或 Cloudflare Tunnel 的用户可以使用 Webhook；只在本机运行、没有公网入口的用户可以选择长连接。保存配置后切换生效。

飞书文本 / 图文 / 附件 → Webhook / 长连接 → Harness Agent → 回复原消息与文件

这是独立维护的社区插件，与 DeepSeek、飞书无隶属关系。当前版本为 0.2.0，通过本仓库源码安装；尚未发布到 npm。

设置界面

飞书插件设置界面

当前多机器人配置界面的隔离测试截图，展示机器人选择、添加、启停及独立项目目录。图中 App ID 和路径均为测试数据，密码不回显；为完整展示表单上半部，截图时扩大了设置对话框。

当前能力

| 能力 | 当前行为 |
| --- | --- |
| 多机器人与项目 | 一个 Harness 同时连接多个飞书应用；按机器人隔离凭据、姓名资料、会话、历史数据库和附件 |
| 插件列表入口 | 在 Plugin list 中展开 feishu-bot 卡片，直接管理配置 |
| 两种接收方式 | Webhook 与长连接二选一，保存后更新运行状态 |
| 消息与附件 | 接收 im.message.receive_v1 的文本、图文（post）、图片、文件、视频和音频；同一租户、用户和聊天复用当前 Harness 会话 |
| 文件发送与看图 | 向当前消息回复个人目录中的文件或媒体；明确支持图片的模型可读取历史图片 |
| 个人邮箱发信 | 私聊输入本人邮箱，由 Agent 自动查询 SMTP 配置，验证授权码后继续当前发信任务；支持个人目录附件，不支持收信 |
| 工作状态 | 开始处理时在原消息添加敲键盘表情回应（Typing），结束时尝试清除；状态更新失败不阻断任务或答复 |
| 自动答复 | Agent 完成后向原消息回复最终文本，较长回复分段发送 |
| Webhook 验证 | 处理地址验证、Verification Token、加密请求解密和签名校验 |
| 公网接入 | Webhook 可选 ngrok、Cloudflare Tunnel 或自定义 HTTPS 地址；ngrok / Cloudflare 可在面板启动并守护 |
| 连接排错 | 按需检查已保存的应用凭据、项目目录与接入配置，展开逐项结果；不自动保存或启动隧道 |
| 连接检查 | 测试应用凭据、显示长连接状态、检测本机 ngrok 隧道 |
| 用户接入 | 飞书后台控制应用可用范围；首次对话必须提供并确认姓名，无需预填 open_id 或用户名 |
| 用户隔离 | 每用户独立工作目录及 SQLite 数据库，不同聊天上下文分开；重名不会合并数据 |
| 会话管理 | 每个机器人中的每位用户同一时间最多一个当前可见的 Harness 会话，以确认的姓名命名；支持 /new、/whoami、/help、/status |
| 历史记录 | 保存消息时间戳，Agent 可查询、读取、创建笔记、修改及软删除当前用户在当前聊天的记录 |
| 每日切换 | 默认 Asia/Macau 凌晨 4 点归档旧会话，下一条消息开启新上下文；等待运行任务完成，保留历史与文件 |

远程飞书会话仅开放受限的工作区文件、个人历史、当前消息附件及个人邮箱工具，不开放任意 Shell、通用 MCP 或可能跨用户访问数据的飞书 API。工作区写入权限只允许操作该用户子目录；只读模式禁止修改工作区文件。新用户使用所属机器人的权限预设；旧配置中已有的个人权限覆盖继续保留。管理员控制本机 Harness 和数据目录，不属于远程用户隔离边界。

使用示例

先完成下文的姓名确认，再在飞书私聊机器人发送：

请阅读工作目录里的 README，用中文概括这个项目的用途。

或者把机器人加入群聊后 @机器人：

根据之前讨论的要求，整理工作目录中的方案草稿。

Harness 会出现一个对应会话，处理完成后由插件回复最终文本。这些是自然语言请求示例，执行结果取决于模型、Agent 预设、工作目录和权限。同一聊天的后续消息延续上下文；/new 或切换到另一个群聊/私聊会归档旧会话，再为后续消息开启新上下文。同一机器人中的同一用户同一时间最多保留一个当前可见会话，旧任务仍在执行时先等它结束，不会强制终止。

文件、图片、视频与音频

完成姓名确认后，可直接发送文件、图片、视频、音频或含图片的飞书图文消息（post）。插件将收到的资源保存到个人工作目录的 incoming/...，在历史中记录原始名称、接收时间和相对路径；以后可按名称、日期查询并重新读取。/new 和每日上下文切换不会删除这些文件。未确认姓名时只继续姓名确认，不下载附件，完成确认后请重新发送。

| 操作 | 插件限制 |
| --- | --- |
| 接收资源 | 每条消息最多 10 个资源，合计不超过 100 MiB |
| 发送图片 | 单张不超过 10 MiB |
| 发送文件、视频、音频 | 单个不超过 30 MiB |
| 视频消息 | 仅 MP4；其他视频格式可作为普通文件发送 |
| 音频消息 | 仅 OPUS；其他音频格式可作为普通文件发送 |

可以要求“把这份 CSV 整理成 Markdown 表格并发给我”。在 workspace-write 权限下，Agent 可用受限的 workspace_write 工具生成 TXT、Markdown 或 CSV，再调用 feishu_send_file 上传并回复当前飞书消息；只在回复中写路径不会发送文件。

发送工具参数为 feishu_send_file(path, kind, coverPath?, duration?)：path 是当前用户工作目录内的相对路径，kind 为 file（默认）、image、video 或 audio；coverPath 为视频封面图片的相对路径，duration 单位为毫秒。工具没有收件人参数，只能在处理当前已领取的飞书消息时使用，不能从 Harness 空闲会话任意向他人发送。

图片理解使用 Harness 已配置的模型，不增加模型或要求修改 Harness 核心。只有当前模型明确声明支持图片输入时才交给它看图；feishu_read_image 可读取个人目录里的历史图片。纯文本模型仍可保存、查找和发送图片文件，但不能看图。视频和音频收发不等于内容理解；插件不提供自动视频分析、语音转写、OCR、转码或通用 PDF/Office 解析，也不开放任意 Shell。新增能力继续使用唯一的 Plugin list 入口，不增加面板导航。

使用前请按 接入指南中的附件权限 开通对应 API 权限并发布应用。

通过个人邮箱发信

完成姓名确认后，普通聊天无需绑定邮箱。首次要求发送邮件时，或主动在机器人私聊发送 /mail，才进入绑定流程：本人邮箱 → 自动匹配 SMTP 服务 → 授权码 → 继续发送。已知邮箱快速匹配，未知域名由 Agent 调用专用 feishu_mail_discover 工具在线查询 DNS 邮件提交记录、域名官方 HTTPS 自动配置和 Thunderbird ISPDB；若标准配置发现未成功，再通过 Harness 已配置的搜索引擎搜索服务商官方资料，读取网页正文并提取 SMTP 配置。插件核实官网与邮箱域名的关联、配置原文及端点，并在不提交授权码的情况下探测 TLS／SMTP 连接。普通用户无需填写服务器、端口或加密方式；找到可用配置后才询问授权码。网页搜索需管理员已为 Harness 配置可用的搜索服务；若搜索服务不可用、没有可靠配置或网络不可达，会说明暂时无法完成并保留当前发送任务，可用 /mail retry 重查，不保证任意邮箱都能识别。/mail server 仅作为高级手动覆盖保留。按提示直接发送授权码或使用 /mail code 授权码；等待授权码时发送的普通文本由入口拦截，不会作为任务交给模型。认证只验证 SMTP 登录，不会发送测试信。

若因明确的发送请求进入配置，插件保留当前请求及其中已明确的收件人。验证通过后直接继续该任务；缺少收件人、主题或正文时只补问缺项，无需重说发送指令。主动发送 /mail 仅配置邮箱，没有当前发送任务时不会自动发信，也不会重放历史草稿。发件人与收件人固定取自当前用户的绑定，Agent 不能自行指定账号或更换收件人。使用 /mail status 查看状态、/mail to 新邮箱地址 修改收件人、/mail reset 删除自己的绑定、/mail cancel 取消未完成配置（保留已就绪绑定）；取消和重置都会丢弃待续的发送任务。不同机器人、租户和用户分别保存邮箱资料，姓名相同不会混用授权。

插件读取 skills/feishu-assistant/SKILL.md，将指引加入每条进入 Agent 的飞书消息，无需另行安装 Skill。在线发现只使用邮箱域名，搜索关键词只包含域名与固定的 SMTP 官方配置关键词，不向查询服务提交完整邮箱或授权码。MX 记录仅辅助核实服务商关系，不直接作为发信地址。网页正文只作为配置资料，不能改变智能体指令；配置校验使用本次读取的官网来源链接和原文证据（临时缓存有效期 10 分钟，重启后需重新查找）。拒绝访问私网地址及重定向绕过，连接始终验证证书。这份轻量 Skill 提供聊天与邮件工具指引；姓名确认、邮箱配置和授权码保护由插件入口的状态机处理。授权码保存到 Harness credentials，并在进入 Webhook 投递、历史与模型前脱敏；插件不会删除飞书平台本身保留的聊天记录。

支持自定义 SMTP 发信，要求 TLS／STARTTLS 和邮箱授权码认证；不支持 OAuth 登录或 IMAP 收信。结果为 SMTP 服务器接受，不代表邮件已送达；结果不确定时不会自动重发。目前尚未完成真实外部邮箱的端到端收件验收。命令、附件限制与设置细节见 个人邮箱发信。

快速开始

1. 准备环境

- Node.js 22.13 或更新版本（历史存储使用内置 node:sqlite）、npm、Git。
- 可正常运行的 DeepSeek Harness；已配置模型，并能在网页会话中得到答复。
- 一个已启用机器人能力的飞书企业自建应用及其 App ID、App Secret。

当前兼容验证基于 Harness 0.1.5-rc.2 相关组件，使用 Web profile。其他版本和运行方式尚未验证。

插件面向 Linux、Windows 和 macOS，使用相同的 Node.js 安装命令；Webhook 模式需另行安装对应系统的 ngrok 或 cloudflared，长连接模式不需要隧道。当前本机实测环境为 Linux；三系统自动测试配置不等于三系统均已完成真实飞书收发验收。Windows 可使用 PowerShell，不需要照搬 Bash 的 alias；工作目录填写本机路径，例如 C:\Projects\my-project。详情见 平台与端口说明。

尚未安装 Harness 时，先运行：

npm install -g @deepseek-ai/dsh

2. 安装并启动

git clone https://github.com/icanotcode/dsh-feishu-bot.git
cd dsh-feishu-bot
npm ci
npm run setup:harness
打开启动日志给出的本机地址，默认端口为 3080。进入 设置 → 插件 → Plugin list，搜索 feishu，展开 Global plugins（全局插件） 中的 feishu-bot 卡片，即可直接配置。插件仅保留此入口，不再添加独立的飞书标签页或侧栏菜单。

setup:harness 检查 Node.js 和 Harness，复用安装脚本把当前仓库链接到 web profile、补充 Webhook 运行时，再启动 Harness；可重复运行，修改已有配置前会备份。安装后请保留仓库目录。 已有实例占用端口时不会终止它，也不会将“端口已有服务”当作插件配置完成；按提示在原终端停止旧实例后重新运行。需要分步操作时仍可使用 install:harness 和 start:harness。自定义 DSH_HOME 时，安装和启动必须使用相同的值。

3. 填写信息并一键配置

先填写 App ID、App Secret 和 Agent 预设，并在「任务处理」中点击 搜索项目，按名称或路径检索并选择项目目录，再选择接收方式。列表来自 Harness 已添加的项目及机器人已绑定目录，不扫描磁盘。插件只在所选项目的 .feishu-users/ 下为每位用户创建独立目录，不直接共享项目已有文件：

| 项目 | 开发者服务器（Webhook） | 长连接（WebSocket） |
| --- | --- | --- |
| 连接方向 | 飞书向公网 HTTPS 地址推送 | 本机主动连接飞书 |
| 公网地址 / 隧道 | 需要可达的 HTTPS 入口；可选 ngrok、Cloudflare Tunnel 或自定义地址 | 不需要任何隧道 |
| 应用凭据 | App ID、App Secret | App ID、App Secret |
| 回调验证配置 | Verification Token；启用加密时还需 Encrypt Key | 不需要 Token / Encrypt Key |
| 飞书后台订阅方式 | 将事件发送至开发者服务器 | 使用长连接接收事件 |
| 当前实现默认值 | 默认接收方式 | 在设置页选择后保存 |

填写所选模式需要的字段并点击 保存配置。日常面板显示当前连接状态，异常时醒目提示；需要排错时，在「事件接收方式」中点击 检查连接问题，展开已保存配置的逐项检查结果，再点击 收起检查结果 恢复简洁视图。检查不会保存表单、启动隧道或发送测试消息；隧道仍由原来的启动按钮管理。

创建飞书应用、授予权限、发布版本、安装隧道程序、购买或充值外部服务仍由管理员完成；检查结果不能代替真实消息验收。

两种模式均需订阅 接收消息 im.message.receive_v1，开通接收和回复消息的权限，并完成飞书应用版本的发布/生效流程。

- Webhook：插件「公网服务地址」填 https://your-domain.example，先保存验证凭据，再在飞书后台填写完整地址 https://your-domain.example/webhook/feishu。
- 长连接：保存应用凭据与接收方式，等插件显示已连接，再在飞书后台选择长连接并配置事件。

Cloudflare Quick Tunnel 可在另一个终端启动（需先安装 cloudflared）：

npm run start:cloudflare -- --port 3080

在插件选择 Cloudflare Tunnel，将日志中生成的 https://…trycloudflare.com 根地址填入「公网服务地址」并保存。默认机器人使用该地址加 /webhook/feishu；其他机器人请复制各自面板生成的完整地址。Quick Tunnel 域名会变化，长期使用建议配置命名隧道。也可直接使用插件面板的一键启动和守护；保存地址本身不代表公网连通。

完整字段解释、飞书权限、两种隧道命令和配置顺序见 飞书接入指南。

4. 验证第一次回复

先在飞书后台设置应用可用范围，插件中不再填写用户 open_id 和姓名名单。首次聊天时，机器人先询问姓名；回复 Alex、我叫Alex 或 /name Alex，核对机器人复述的姓名后回复 确认。

确认完成前，插件只处理姓名确认，不回答其他问题，也不执行任务。 /new、/status、/whoami 和 /help 不能跳过这一步。确认前发送的任务不会自动执行，完成确认后请重新发送。姓名持久保存，重启、/new 和每日切换无需重新填写；升级前已配置过姓名的用户也需亲自确认一次。

确认姓名后发送简单文本，确认 Harness 中出现包含该姓名的会话，并在飞书收到最终答复。再发送追问验证同一聊天沿用会话，发送 /new 验证切换。群聊测试需先加入机器人并 @机器人。

「测试连接成功」说明应用凭据通过认证；「请求地址保存成功」说明地址验证通过；「长连接已连接」说明连接已建立。只有实际收到机器人答复，才验证了完整链路。

一个服务器连接多个机器人

在插件卡片顶部使用 当前机器人 选择器切换应用。点击 添加机器人，填写名称并通过 搜索项目 选择独立项目目录；创建后填写该机器人的 App ID、App Secret，选择 Webhook 或长连接并保存。每个机器人使用不同的飞书 App ID，项目目录不能重复；在同一服务器内可混用两种接入方式。

「任务处理」和「添加机器人」使用相同的搜索下拉框：点击目录框展开全部项目；只有点击右侧 搜索图标 才显示搜索框，输入项目名称或路径后，下方同一个列表实时筛选；选择后再保存配置或创建机器人。列表包含 Harness 已添加的项目和机器人已绑定目录，不会遍历磁盘。被其他机器人占用或无法访问的目录不可选。找不到目标时，先在 Harness 中添加该项目，再刷新项目列表。选择项目不会扩大远程用户权限，每位用户仍只能访问所选目录下自己的 .feishu-users//。

项目目录搜索选择器

App ID 绑定后不能替换；接入另一个飞书应用时请新增机器人，保留各自历史。同一应用的 App Secret 等凭据可以更新，任务运行中需先等任务完成。

重命名只修改显示名称，不迁移或合并历史。停用保留配置和数据，同时停止该机器人接收消息和执行新任务；正在处理任务时会拒绝停用，请等任务完成再操作。切换机器人时，未保存的配置需要确认放弃；已保存凭据不会显示出来或复制给其他机器人。
ngrok / Cloudflare 是服务器共享的一个公网入口，在 默认机器人（共享隧道设置） 下管理。默认机器人即使使用长连接，其他启用的机器人使用 Webhook 时仍可在这里管理隧道。各机器人有独立回调路径：默认机器人保留原 /webhook/feishu，新增机器人使用该路径下的独立子路径。请分别复制所选机器人的完整 Webhook 地址到对应飞书应用，不能共用同一个回调地址。公网根地址改变时，更新所有使用 Webhook 的飞书应用。

已有入口策略若只放行默认回调，还需允许新增机器人各自的 POST 回调路径；管理页面继续保留原访问保护，插件不会自动改写策略。

升级后原凭据、工作目录、会话和历史继续属于默认机器人。新增机器人不会继承原应用密钥或个人资料；同一人在不同机器人下独立确认姓名、使用各自项目的数据，每个机器人内仍保持每用户最多一个当前会话。

隧道启动与自动重启

在 Plugin list 的飞书卡片中选择默认机器人，再选择 ngrok 或 Cloudflare，保存配置后点击 启动当前端口的隧道。先安装对应系统的原生程序，加入 PATH 或填写程序绝对路径；Linux、Windows、macOS 均不依赖 Bash/alias。端口直接取 Harness 实际监听值。

隧道守护滑动开关保存后生效：开启时自动启动缺失的隧道，异常退出后退避重试，最长等待 60 秒；关闭只取消自动重试，不停止已有进程。停止托管隧道只停止插件启动的进程，并暂停本次守护；手动启动或关闭守护保存后重新开启可恢复。守护随 Harness 运行，并非系统常驻服务。

ngrok 可设置 Traffic Policy 文件；留空时探测 ~/.config/ngrok/policy.yaml，不会修改策略内容。已有匹配端口和域名的 ngrok 会被复用而非重复启动；外部进程不会被插件停止。Cloudflare 支持 临时 Quick Tunnel 和 固定的本地管理命名隧道；后者需要现成的本地配置、凭据和 DNS。命名模式使用临时配置副本指向当前端口，不修改原文件。暂不支持仅凭 Cloudflare Dashboard tunnel token 配置远程管理隧道。

临时模式会显示本次分配的 URL，重启后地址改变时须更新飞书回调地址。进程状态、隧道连接和飞书回调验证是不同检查；请以飞书保存回调及实际收发结果确认完整链路。详见 隧道设置。

默认配置与数据保存

| 配置 | 默认行为 |
| --- | --- |
| 接收方式 | webhook |
| 公网接入方式 | ngrok；可在 Webhook 设置中改为 Cloudflare Tunnel 或自定义公网地址 |
| 回调路径 | 默认机器人保留 /webhook/feishu；新增机器人自动分配独立子路径 |
| Agent 预设 | standard，需已在 Harness 中安装 |
| 权限预设 | workspace-write；仅可改为 read-only，不接受完全访问权限 |
| 项目目录 | 从 Harness 项目搜索下拉框选择；每位用户仅使用该目录下自己的 .feishu-users/ 子目录 |
| 用户接入 | 飞书应用可用范围控制接入；首次聊天提供姓名并回复 确认 后才能发起任务 |
| 每日上下文切换 | 04:00，Asia/Macau；归档旧会话，忙碌时等任务完成，SQLite 历史和 Harness 归档日志不删除 |
| 模型 | 未单独指定时使用 Harness 的默认模型配置 |
| 普通配置 | 默认机器人的原 feishu-bot.json 保留；新增机器人使用独立配置和机器人清单，均存入 DSH_HOME（默认 ~/.dsh） |
| 密钥 | 由 Harness 凭据服务保存；设置页留空保留已有值，环境变量提供的值需在启动环境中修改 |

在 Harness 界面删除飞书 workspace 只会移除工作区注册，下一条普通飞书消息会恢复工作区并继续原会话；这与 Archive 后新建会话不同。若直接删除磁盘工作目录，插件只能重建空目录，无法恢复已删除的工作文件；独立存放的历史数据库不受仅删除工作目录影响。

在 Harness 中手动 Archive 当前飞书会话后，下一条普通飞书消息会创建可见的新会话。旧会话保持归档，历史仍可查询；若旧任务仍在运行，则等它完成后再切换。归档会开启新的上下文，不会自动复制旧上下文。/status 可查看当前会话是否已归档。

数据库按机器人来源、租户与用户的稳定身份分开，不以可更改的姓名作为身份依据。姓名保存为用户资料并用于会话标题；同名用户不会共用数据库，姓名也不会成为数据库或工作目录的路径。同一用户在群聊与私聊之间切换时，先归档上一个聊天的当前会话，再新建上下文，不混用上下文；Agent 历史工具仍仅能访问当前用户、当前聊天的记录。历史包含时间戳，保存在本机 SQLite 数据库中。

/new 和每日切换会将旧会话从 Harness 当前列表归档，保留 SQLite 历史、Harness 归档日志和工作文件；下一条消息才创建新会话。重启时会补归档已关闭但仍遗留在当前列表中的会话。旧数据库缺少身份资料时，在首次通过验证的飞书消息中自动补齐，此后即使没有新消息，也会按时执行每日切换。

可向 Agent 请求“查找上个月本聊天讨论的方案”“记录一条项目笔记”或“更正这条历史记录”。修改或软删除只影响历史数据库，不会追溯修改 Harness 原会话日志、飞书消息或已加载的模型上下文；需要刷新当前上下文时再发送 /new。历史 CRUD 不是整机数据擦除。

支持范围与验证状态

当前聊天入口支持文本、图文及图片/文件/视频/音频输入，支持最终文本答复与当前消息的文件发送；不提供流式输出。历史记录持久保存，但不是可靠投递队列；处理中重启不保证恢复未交付的答复。

除 im.message.receive_v1 外，尚未处理机器人入群/出群、消息已读/撤回、用户 reaction 事件、云文档评论、会议/纪要/妙记事件；也未实现 card.action.trigger 卡片按钮回调 或通用定时任务执行器。每日上下文切换不等于支持任意 cron 任务。这些事件无需为本插件额外订阅。主动添加/清除 Typing 工作状态表情不需要订阅 reaction 事件，需开通 im:message.reactions:write_only 并完成飞书应用权限发布，见接入指南。

已有自动测试及本地检查；0.2.0 的真实飞书多用户收发和三平台完整链路仍需验收。欢迎按接入指南进行试用并反馈环境、复现步骤和脱敏日志。

常见问题
- 保存请求地址提示 3 秒超时：先检查转发端口、完整路径、代理登录拦截和 Encrypt Key 配置。
- 为什么地址要加 /webhook/feishu？ 域名将请求送到服务器，路径将请求交给飞书接收接口；默认根路径是 Harness 页面。
- 看到已连接，却收不到回复：继续检查事件订阅、应用发布、消息权限以及 Harness 会话中的执行结果。

具体步骤与 HTTP 状态码说明见 排错指南。

更新与参与

升级到当前版本：先检查飞书后台的应用可用范围；本地用户白名单已取消，原名单不再限制接入，已有个人权限覆盖仍保留。所有用户首次使用新版时都需亲自提供并确认姓名，旧名单中的姓名不会自动完成确认。旧的完全访问权限不再支持，请改成只读或工作区写入。远程会话也不再拥有通用 Shell、MCP 和跨用户飞书工具。旧版逐消息会话不会自动合并为新会话或导入历史库。

在仓库目录中更新，完成后重启正在使用此插件的 Harness：

git pull --ff-only
npm ci
npm run install:harness

版本变更见 更新日志。本地验证命令为 npm test。提交问题或改进前可阅读 贡献说明。需要向社区介绍本插件时，可使用 社区介绍文案。

许可与参考

代码使用 MIT 许可证，第三方依赖遵循各自的许可证。

文档组织参考了 xmanrui/dsh-im 的中英文入口和分层接入指南；本页列出的能力以本仓库实现为准。