飞书联调指南（完整版）
August 15, 2026 · View on GitHub
目标：只看这一篇文档，就能把 dsh-im-feishu 从零跑通——在飞书里指挥 DeepSeek Harness 的真实 agent。
全文约 15 分钟。分四部分： ① 接入飞书（扫码 1 分钟 / 手动 10 分钟，二选一） ② 安装插件（一条命令） ③ 在飞书里使用（派活 / 审批 / 查状态） ④ 常见问题排查
先说清楚：这个"界面"是什么
这个插件没有网页界面。 它的"界面"就是飞书的聊天窗口：
- 你在飞书里私聊机器人 = 给 agent 派活
- agent 的回答 = 机器人发回的消息（带流式打字效果）
- 危险操作 = 机器人发来一张审批卡片，上面有【批准】【拒绝】按钮
- 你不在电脑前，手机上的飞书就是全部操作界面
你的电脑上只需要跑一个后台进程（桥接程序），它负责：连飞书长连接收消息 → 交给 agent 干活 → 把结果发回飞书。终端窗口只用来观察连接状态。
① 接入飞书（二选一：网页扫码 1 分钟 / 手动 10 分钟）
方式一：网页扫码接入（推荐，约 1 分钟，不碰终端）
不需要手动建应用、勾权限、配订阅——在 DeepSeek Harness 网页里直接扫码， 应用名、权限、事件、回调都按本插件需求预填：
- 启动
dsh web，打开浏览器 设置 → 插件 → 飞书 页签 - 点「📱 扫码绑定 | Scan to connect」
- 网页出现二维码 → 用手机飞书扫码 → 在手机上确认（预填项都在，无需改动）
- 页面显示「🎉 绑定成功」→ 重启
dsh web，在飞书里私聊机器人开始使用
说明：
- 凭据写入 Host 本机
$DSH_HOME/dsh-im/feishu-credentials.json（仅本机可读）， App Secret 不会出现在浏览器里，也无需设置任何环境变量。- 预填的权限/事件/回调走飞书官方灰度（平台支持才自动生效）；灰度未覆盖时确认页是默认模板， 按下方「方式三」手动补勾即可，结果一样。
- 扫码创建的应用属于扫码人所在企业，需要是企业成员（自己当管理员最省事）。
方式二：终端扫码（CLI，1 分钟）
没有网页时用：npx -y dsh-im-feishu-qr → 终端二维码 → 手机飞书扫码 → 重启。
方式三：手动创建（扫码失败 / 需要精细控制时）
下面的手动步骤与扫码等价，三选一即可。
⚠️ 长连接模式只支持企业自建应用（个人/商店应用不行）。你需要是企业管理成员（自己就是管理员最省事，发布不用等别人批）。
1. 创建应用
- 打开 飞书开放平台，用飞书账号登录
- 点「创建企业自建应用」
- 填应用名称（如
DSH Agent）、图标（随意选一个） - 创建后进入应用详情页
2. 开启机器人能力
左侧菜单「添加应用能力」→「机器人」→ 打开开关。
3. 记录凭据
左侧「凭证与基础信息」→「应用凭证」，记录两样：
| 名称 | 示例 | 说明 |
|---|---|---|
| App ID | cli_你的AppID | 公开标识，cli_ 开头 |
| App Secret | 你的AppSecret | 相当于密码，只在你自己的机器上使用；怀疑泄露可在后台重置 |
4. 添加权限
左侧「权限管理」→「添加权限」，搜索并添加以下权限（必须）：
| 权限标识 | 说明 |
|---|---|
im:message.p2p_msg:readonly | 接收用户单聊消息必需（事件 im.message.receive_v1 推送依赖它，官方文档明确要求） |
im:message:send_as_bot | 以机器人身份发送消息（回消息/发审批卡片必需） |
⚠️ 坑：笼统的
im:message不能让事件订阅生效。接收单聊消息必须im:message.p2p_msg:readonly；接收群聊 @ 机器人消息必须im:message.group_at_msg:readonly（群聊可选）。
可选（用到再加）：
| 权限标识 | 说明 |
|---|---|
im:message.group_at_msg:readonly | 接收群聊中 @ 机器人的消息（群聊用） |
im:resource | 读取图片/文件资源（IM 附件落盘用） |
im:chat:readonly | 读取群信息（群聊用） |
5. 订阅「事件」——接收用户消息
左侧「开发配置」→「事件与回调」→ 页面顶部点「事件配置」页签：
- 订阅方式选「使用长连接接收事件」（本地就能收，不需要公网 IP/域名）
- 点「添加事件」，搜索并添加：接收消息（事件名
im.message.receive_v1） - 保存
注意：长连接模式只有企业自建应用能用；添加事件后必须发布版本才生效（见第 7 步）。
6. 订阅「回调」——接收审批按钮点击（关键，容易找错地方）
card.action.trigger 不在「事件配置」里，它在另一个页签：
- 仍在「开发配置」→「事件与回调」页面
- 页面顶部点「回调配置」页签（⚠️ 不是「事件配置」！）
- 页面底部「已订阅的回调」→「添加回调」
- 选择「卡片回传交互」（对应新版事件名
card.action.trigger）→ 确认添加 - 保存
漏掉这一步的后果：审批卡片能收到、能显示，但点【批准】【拒绝】按钮没反应。 在配好之前，审批可以用文本命令代替：
/approve <id> yes（见 ③）。
7. 设置可用范围 + 发布版本（不发布 = 白配）
可用范围：左侧「权限管理」→「可用范围」→ 把你自己（和要使用的人）加入。 否则机器人收不到你的消息。
发布：左侧「应用发布」→「版本管理与发布」→「创建版本」：
- 填版本号（如
1.0.0、1.0.1）、更新说明 - 保存 → 申请线上发布
- 等企业管理员审批通过（如果应用是你创建的且你是管理员，通常自己点一下就过）
每次修改权限/事件/回调后，都要重新创建版本并发布才会生效。
8. 自查清单（发布后对照）
- 应用是企业自建应用
- 机器人能力已开启
- 有
im:message.p2p_msg:readonly（收单聊必需）和im:message:send_as_bot（发送必需）权限 - 「事件配置」里加了
im.message.receive_v1，订阅方式为长连接 - 「回调配置」里加了
card.action.trigger（审批按钮用） - 可用范围包含你
- 最新版本已发布并通过审批
② 安装插件（一条命令）
前提：已装好 DeepSeek Harness（dsh 命令可用；提示 command not found 先 npm install -g @deepseek-ai/dsh）。
dsh plugin --profile web add dsh-im dsh-im-feishu -w
-w是给 pnpm 的（profile 是 workspace 根，pnpm 9 必须显式声明；报ERR_PNPM_ADDING_TO_ROOT时带上它）。
配置环境变量（在启动 dsh web 前导出）：
| 变量 | 来源 | 必须 |
|---|---|---|
FEISHU_APP_ID | 飞书开放平台 → 凭证与基础信息 | ✅ |
FEISHU_APP_SECRET | 同上 | ✅ |
DEEPSEEK_API_KEY | DeepSeek 开放平台 | ✅ |
export FEISHU_APP_ID=cli_你的AppID
export FEISHU_APP_SECRET=你的AppSecret
export DEEPSEEK_API_KEY=sk-你的Key
dsh web
启动后飞书通道自动连接（官方长连接，免公网）；在飞书里私聊机器人即可使用。
想不装进 DSH、克隆仓库直接跑联调脚本？见文末「附：不装进 DSH 的联调方式」。
③ 在飞书里使用
打开飞书 App/桌面端 → 搜索你的机器人应用名 → 私聊它。
第一次：信任确认
- 普通用户零配置：你的第一条消息会收到"尚未被授权/已向管理员确认"提示，管理员（配置里
security.admins的人）点 ✅ 按钮或回复/trust feishu:<你的open_id>即放行，永久生效。 - 管理员只需配置一次：在
$DSH_HOME/profiles/web/cordis.patch.yml的im.security.admins里填入你自己的用户键（如["feishu:ou_78e92c..."]）即可——管理员隐式放行，无需重复写allowlist。 - 个人自用想省事：把
im.security.trustOnFirstContact设为true（首条消息自动信任，跳过确认）。
常用操作
| 你在飞书里发 | 会发生什么 |
|---|---|
/new | 创建新会话，agent 就绪 |
直接发任务，如 列出当前目录内容 | agent 执行，结果流式逐段发回，最后附结果卡片（耗时 + token 用量） |
| 任务里触发危险命令（如删除文件） | 收到审批卡片：工具名、参数（已脱敏）、风险等级、【批准】【拒绝】按钮 |
| 点【批准】 | agent 继续执行，完成后发结果卡片 |
| 点【拒绝】 | agent 收到"用户拒绝了"，停止该操作 |
/approve <id> yes 或 /approve <id> no | 文本方式审批（卡片按钮没配好时用这个） |
/status | 渠道连接状态、会话列表、等待中的审批 |
/log | 把最近一次任务的完整输出以文件发回（长输出被截断时用） |
/mute /unmute | 关闭/打开本聊天通知 |
/help | 命令列表 |
群聊（可选）
把机器人拉进群，群里 @ 机器人 发消息即可；群里只有 allowlist 成员能派活，管理员才能审批。
④ 常见问题排查
| 现象 | 原因与解决 |
|---|---|
启动 dsh web 报 appSecret or clientAssertionProvider is required | 没配凭据：要么 export FEISHU_APP_ID / FEISHU_APP_SECRET 再启动，要么用 npx -y dsh-im-feishu-qr 扫码接入（自动写凭据文件）；缺凭据时通道会优雅断开，不会崩整个 dsh web |
| 飞书通道没连上 | ① App ID/Secret 复制完整吗？② 应用是企业自建吗？③ 长连接只认 cli_ 开头的 ID ④ 环境变量有没有在启动 dsh web 前导出 |
| 连上了，但发消息 bot 不回 | ① 「事件配置」里加了 im.message.receive_v1 并发布了吗？② 可用范围包含你吗？③ 你私聊的是这个应用吗？ |
| bot 回消息报"无权限"/"未授权" | 首次接触触发信任流程：管理员 /trust feishu:<open_id> 授权；或配置 trustOnFirstContact: true 自动信任 |
| 审批卡片显示但按钮点了没反应 | 「回调配置」页签里没加 card.action.trigger（见 ① 第 6 步），或用 /approve <id> yes 文本审批 |
| 发消息报权限错误 | 缺 im:message:send_as_bot 权限，或新权限没重新发布版本 |
| 改了配置不生效 | 每次改权限/事件/回调都要重新创建版本并发布，等审批通过 |
| agent 执行出错 | 终端窗口会打印 agent 日志；把终端输出截图给我排查 |
附：不装进 DSH 的联调方式（开发者）
需要克隆本仓库 + Node.js 22+：
npm install
FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx DEEPSEEK_API_KEY=sk-xxx \
node demo/feishu-real.mjs --mode demo
--mode demo：首条消息自动信任（个人联调用）；--mode prod：严格 allowlist（真实部署基线）。
附：真实效果长什么样
机器人发来的消息大致如下（飞书聊天窗口里）：
✅ 任务完成
完成！我做了以下操作：
1. 创建了 hello.py ...
2. 运行了它，输出 hello world
⏱ 5.8s · 🔢 790 in / 375 out tokens
审批卡片：
🔐 审批请求
工具: demo-shell
参数: {command=rm -rf build}
风险: high
原因: 工具 "demo-shell" 被判定为 high 风险（IM 远程审批，默认拒绝）
会话: im-feishu-oc_xxxxx
[✅ 批准] [❌ 拒绝]