> 这是第一代方案，线上机器人已被第二代取代。
> 第二代：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: 从主仓库打包/同步"），内容与主仓库重复，已归档（只读，可恢复）。
dsh-feishu
让 agent 真正住进飞书。
MCP server · 长连接机器人 · 卡片网关 · DSH 设置页 · MIT
它是什么
飞书会话就是 agent 的操作台。在手机上发一句话，它在你的机器上执行，把文件、卡片、
多维表格发回会话——而不是回你一段「建议执行以下命令」。
不需要公网 IP、内网穿透、域名或证书：机器人主动向飞书发起 WebSocket 长连接，不开放入站端口。
它由三个角色组成，各自负责一段：
| 角色 | 职责 |
|---|---|
feishu-bot |
常驻长连接。身份校验、会话管理、任务队列、进度卡、审批按钮。自身不执行任务 |
| agent | 实际执行方。dsh --profile headless 调用模型，43 个 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 自检，完成一步点亮一项）：
- 建应用 —— 直达开放平台的链接，附 11 项权限清单，可一键复制
- 填凭据 —— App ID / Secret，保存时先校验再落盘，凭据错误不会写坏文件
- 选会话 —— 「扫描我的会话」列出机器人所在会话，无需手抄 32 位
oc_串 - 自检 —— 九项逐个真调接口：凭据文件、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
安装器执行四步，每步可单独重跑：
- 校验凭据 —— 实际换取一次
tenant_access_token并列出会话，凭据错误立即报出 - 写密钥文件 ——
~/.config/dsh/feishu.env，权限0600 - 安装 MCP 启动包装 —— 生成
dsh-feishu-mcp脚本（stdio 子进程的环境变量会被清空，
密钥需由包装脚本自行 source） - 修改 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//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/ 架构 · 契约 · 工具清单 · 各模块说明
改动代码前请遵守两条硬约束：
- stdout 只能输出 MCP 的 JSON-RPC。任何
console.log都会破坏协议，日志一律走 stderr。 - 工具 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
