13 · 怎样从飞书发送语音、图片和文件给 Hermes
多媒体输入不是“模型自动全懂”：先看清下载、转写、分析和回复分别发生在哪里。
这是第三篇场景课程。你会从飞书私聊依次发送一段语音、一张虚构截图和一份不含隐私的文档，让 Hermes 把三种输入汇总成一份检查表。重点不是展示识别能力，而是确认每一项输入是否真的进入处理链、哪些内容不确定、失败后从哪里恢复。
看完会得到什么
- 一次经过真实转写的短语音输入
- 一张经过图像能力读取的练习截图
- 一份被 Gateway 接收并交给 Agent 处理的虚构文档
- 一份区分“语音 / 图片 / 文件 / 不确定项”的飞书回复
- 一套能判断失败发生在上传、下载、工具、模型还是交付阶段的方法
开始前
- 预计时间：20—35 分钟；首次本地语音模型下载可能更久
- 前置课程：11 · 怎样把 Hermes 接入飞书，并完成第一个移动端任务
- 建议前置：08 工具与 toolsets、10 排错与恢复
- 已验证日期：2026-07-18
- 已实测环境：Hermes Agent 0.18.2，Linux x86_64；本地核对了
hermes tools list、hermes doctor和 Gateway 状态命令 - 平台事实范围：已对照当日 Hermes 飞书、Vision、Voice & TTS 官方文档；飞书客户端上传限制和模型能力以你的实际账号与配置为准
- 输入位置：系统终端、飞书私聊
- 本篇会修改：Hermes 的本地媒体缓存和会话记录；如果本地 STT 首次拉取模型，还会占用缓存与磁盘空间
- 本篇不会修改：正式文档、原始附件、飞书群配置，也不会使用真实客户或内部资料
先认识本篇术语
| 术语 | 中文直觉 | 本篇用途 |
|---|---|---|
| Media attachment | 随消息发送的图片、音频或文件 | 由飞书 Gateway 下载到 Hermes 可处理的位置 |
| STT | Speech-to-Text，语音转文字 | 把语音内容变成 Agent 可读的文本 |
| Vision | 让模型或图像工具读取图片内容 | 提取截图中的标题、状态和问题 |
| Document extraction | 从文档容器中取得可读文字 | 让 Agent 读取附件正文，而不是只看到文件名 |
| Cache | 为处理附件保存的本地临时副本 | 便于工具读取，也意味着敏感附件可能落到运行机器 |
| Multimodal | 同一任务包含多种输入类型 | 本篇把语音、截图和文档合并验收 |
先看处理路径
“机器人收到了消息”只证明事件到达，不证明附件下载、转写或分析成功。验收要分别检查三条分支，最后再检查汇总回复。
第一步：确认 Gateway 和最小工具状态
在系统终端运行：
hermes gateway status --deep
hermes tools list
hermes doctor- 输入位置：运行 Hermes 的系统终端
- 读取或修改：只读取 Gateway、toolsets、依赖和配置状态
- 成功判断：飞书 Gateway 可用；工具列表中能看见当前平台所需能力；
doctor没有报告阻塞本篇的核心问题 - 失败先查：先修 Gateway，再区分 STT、Vision 和文档依赖，不要一次重装所有组件
本地 CLI 的工具列表不一定等于飞书平台实际启用的 toolsets。Hermes 可以按平台配置工具范围；如果你刚更改工具，按官方说明重启 Gateway 或开始新会话后再测。
还要回到飞书开放平台确认应用具有 im:resource。Hermes 官方飞书文档把它列为访问用户发送图片、文件和音频的必要权限。权限修改后通常需要发布新版本并完成企业审批才会生效。
第二步：准备三份完全虚构的输入
不要拿真实会议录音、客户截图或内部合同做第一次测试。准备下面三项。
1. 一段 8—15 秒语音
照着读：
练习任务的截止时间是周五十八点，负责人是小林，风险是还没有确认场地。2. 一张练习截图
在任意本地文本编辑器中显示下面三行，再截图，只保留这三行：
项目：移动端资料检查
状态：等待复核
问题：缺少来源链接截图中不要出现桌面通知、账号头像、浏览器标签、文件路径或其他消息。
3. 一份练习文档
创建一个纯文本文件 media-practice.txt：
交付物：一页活动说明
必须包含：目标、流程、联系人
禁止内容：未经确认的预算数字纯文本便于你逐字核对。官方飞书适配器当前会自动提取小型 .txt、.md 文件的内容；其他文档格式可能需要文档解析或文件工具，失败面更大，适合在基础路径通过后再测。
第三步：先单独发送语音
在与飞书机器人的私聊中发送语音，并附带或紧接着发送：
请只转写刚才的语音，并按“截止时间 / 负责人 / 风险”三项列出。
听不清的部分标记为“不确定”，不要猜。检查真实回复：
- “周五 18:00”没有被改成别的日期；
- 负责人是“小林”；
- 风险是“尚未确认场地”；
- 若语音不清楚，回复明确标记不确定，而不是补词。
STT 的结果是模型后续判断的输入。转写一旦错了，后面的总结再流畅也不合格。
STT 能力从哪里来
Hermes 官方文档当前支持本地和云端语音转写路径。默认本地路径依赖 faster-whisper 或可用的本地 Whisper 命令；云端路径可能需要单独凭据、产生费用并把音频发送给服务商。
本篇不要求你更换 provider。只记录实际使用的是本地还是云端，并确认：
- 音频是否离开运行机器；
- 是否会产生调用费用；
- 凭据是否通过 Hermes 配置而非聊天提供；
- 首次模型下载需要多少时间和磁盘空间。
不确定当前路径时，先检查配置与日志，不要根据回复速度猜测。
第四步：单独发送截图
发送练习截图，并写：
请读取这张练习截图，只列出“项目 / 状态 / 问题”三项。
如果某一项看不清，标记“不确定”；不要根据常识补充。核对三项是否逐字对应截图。图像路径可能有两种：当前主模型直接支持视觉输入，或 Hermes 调用 Vision 工具分析。无论哪一种，都要以真实工具状态和回复为准，不能因为模型“支持图片”就假设飞书附件已经成功下载。
截图中的小字、裁剪、压缩和对比度都会影响识别。失败时先发送更清晰、范围更小的截图，而不是要求模型“再猜一次”。
第五步：单独发送文件
发送 media-practice.txt，并写：
请只根据这个附件回答：
1. 交付物是什么；
2. 必须包含哪三项；
3. 哪类内容禁止写入。
如果你只能看到文件名、看不到正文，请直接说明，不要推测。合格回复应能对应文件正文。只复述文件名不算读取成功；声称读到了正文却出现文件中没有的预算数字，也不合格。
第六步：完成一个有边界的多媒体汇总
前三项分别通过后，在同一私聊发送：
请基于本次会话中刚才的语音、练习截图和 media-practice.txt，输出一份“练习检查表”，只包含四节：
## 语音
列出截止时间、负责人、风险。
## 图片
列出项目、状态、问题。
## 文件
列出交付物、三项必须内容、禁止内容。
## 不确定项
列出任何未成功转写、未看清或未读取的内容；如果没有，写“无”。
限制：
- 不联网；
- 不读取其他会话或本地文件；
- 不修改或转发三个输入；
- 不补充输入中没有的信息。这一步验证当前会话能否把三种已经处理过的输入组合起来。若其中一种前面失败，汇总应把它放进“不确定项”，而不是用另外两种输入填空。
权限检查
本篇会访问：
- 你主动发送的语音、截图和练习文档；
- 飞书消息与资源下载接口；
- Hermes 运行机器上的媒体缓存；
- 配置的 STT、Vision 或主模型服务。
可以批准：
- 下载三份虚构练习媒体到 Hermes 本地缓存；
- 为转写与分析把必要内容交给已经确认的数据处理路径；
- 在同一飞书私聊回复结果。
需要停下来确认：
- 真实会议、客户材料、身份证件、合同或未公开截图要上传到云端模型；
- Agent 要把附件转发给其他人、其他会话或外部服务；
- 为了读取一个文件而请求扫描整个主目录；
- 日志或排错要求打印完整凭据；
- 生成回复后要覆盖、删除或公开原始附件。
不应输入的信息：API key、App Secret、密码、私钥、助记词，以及没有明确处理授权的个人信息或业务机密。
多媒体任务的隐私边界
文字消息、音频、图片和文档都可能在链路上形成副本：飞书服务端有消息附件，Gateway 会下载到运行机器，云端 STT 或视觉模型还可能接收媒体内容。删除飞书消息不一定同步清除所有本地缓存或服务端处理记录。
因此，决定“能不能发”之前，先问数据是否允许进入每一段链路，而不是只问机器人是否有能力读取。
出错时按这个顺序查
三种输入都失败
- 检查
hermes gateway status --deep； - 确认普通文字消息仍能收到回复；
- 检查飞书应用的
im:resource权限是否已发布并获批； - 查看 Gateway 日志中的资源下载错误；
- 对照官方飞书媒体支持说明。
只有语音失败
- 确认音频格式被飞书适配器接收；
- 检查本地 STT 依赖或已配置的云端 STT 凭据；
- 查看首次本地模型是否仍在下载；
- 用更短、更清楚的语音重试一次；
- 若无任何 STT provider 可用，接受“无法转写”的明确提示，不让 Agent猜内容。
只有截图失败
- 确认附件已成功下载，而不是只收到占位消息；
- 检查飞书平台的 Vision toolset 或当前模型是否具备视觉能力；
- 裁剪无关区域、放大文字、提高对比度；
- 重新发送一次虚构截图；
- 不把 OCR 猜测当作事实。
只有文件失败
- 先用本篇的短
.txt文件排除复杂格式问题； - 确认回复是否只看到了文件名；
- 检查附件大小和飞书下载日志；
- 再判断是否需要文档解析工具；
- 不要为了测试把真实敏感文件换进来。
回复发不回来
如果日志显示处理已经完成，但飞书没有回复，问题在交付段，而不是识别段。检查机器人发送权限、Gateway 连接和消息长度；保留处理日志，不要反复上传同一敏感附件。
怎样停止与恢复
发现附件范围不对或数据不应处理时：
- 在飞书中停止继续发送；
- 回到 Gateway 前台进程按
Ctrl+C，或运行：
hermes gateway stop- 检查实际下载和调用到了哪一步；
- 按组织的数据保留要求处理本地缓存和平台附件；
- 涉及云端凭据泄露时，在服务端撤销，而不是只清空会话；
- 修正权限或 toolsets 后，重新启动 Gateway，并只用虚构材料复测。
停止 Gateway 能阻断新消息，不会自动撤销已经发生的上传、模型调用或外部发送。
本篇作品
保存一张经过脱敏的飞书回复截图，或复制最终“练习检查表”到本地笔记。作品应包含四节，并保留“不确定项”。另记录：
验证日期：2026-07-18
语音：成功 / 失败；STT 路径：本地 / 云端 / 不确定
图片：成功 / 失败；处理路径：主模型 / Vision 工具 / 不确定
文件：成功 / 失败；格式：.txt
外发：仅回复原飞书私聊
真实敏感数据：未使用本篇验收
- [ ] Gateway 与飞书文字路径先通过，再测试媒体
- [ ] 飞书应用具备已生效的资源读取权限
- [ ] 语音中的三项能追溯到真实转写，听不清处没有猜测
- [ ] 截图中的三项与图片一致，没有补充截图外信息
- [ ] 文件回答来自正文，而不是只根据文件名推测
- [ ] 汇总回复包含语音、图片、文件和不确定项四节
- [ ] 能说明附件可能在哪些位置形成副本
- [ ] 能停止 Gateway，并区分停止新处理与撤销既有外部影响
- [ ] 全程只使用虚构材料，没有暴露凭据或个人隐私
下一篇
下一篇进入高级选修：把两个独立研究子任务交给 Delegation 子代理，并由父 Agent 验证来源、比较结果和控制并发。你会看到“并行”为什么不等于“自动可信”。