coze-file-send: 把文件 / 图片发给用户
你跟用户在 coze 平台聊天, 对话默认纯文本。生成的图片 / PDF / 报告 / 图表等文件用户不会自动看到 — 必须用 coze-bridge send 主动发, 用户才能在聊天界面看到。
先决条件: 从 <coze-context> 提取身份 ID
每条用户消息开头云端会注入一段身份上下文块。Coze 有两种聊天形态, 上下文块格式不同:
单聊消息:
<coze-context>
单聊消息
account_id: 7639...001
agent_id: 7639...571
session_id: 7639...999
</coze-context>
群聊消息 (多了 group_id):
<coze-context>
群聊消息
account_id: 7639...001
agent_id: 7639...571
session_id: 7639...999
group_id: 7639...888
</coze-context>
调 coze-bridge send 时必须用 --agent-id 和 --session-id flag 把对应 ID 带上。命令无状态, 每次调用都要带, 不带会 exit 4。
两种模式: 决策树
你要发的文件在哪里?
├─ 本地 (你刚生成 / cp 来的) → 模式 A (本地文件)
└─ 已在群文件里 (你从 coze agent 拿到 path) → 模式 B (群文件)
需要群聊上下文, 单聊场景没有这种 path
关键差异:
| 维度 | 模式 A: 本地文件 | 模式 B: 群文件 |
|---|
| 适用场景 | 单聊 / 群聊均可 | 仅群聊 (需要 group_id 来源) |
<path> 含义 | 本地文件路径 | 群文件路径 (原样透传) |
| 是否上传 | 是 (走 HTTP API) | 否 (直接 WS 通知 IM) |
--mime | 自动探测 (忽略) | 必填 |
| 大小限制 | ≤ 50MB | 无 (云端管) |
命令调用规范
永远用固定路径 ~/.coze/bridge/bin/coze-bridge 调用 CLI, 不要用裸 coze-bridge — 不同 framework 的 bash tool 继承 PATH 不一致, 裸命令可能 exit 127。固定路径是 daemon 启动时一定写好的 shim, 跨 framework / 跨平台都解析得到。
(注: 这里指 CLI 二进制本身的路径; 传给 CLI 的文件 <path> 参数另说, 见各模式。)
模式 A: 本地文件 (单聊 / 群聊都可用)
# 图片
~/.coze/bridge/bin/coze-bridge send image <localPath> \
--agent-id <agent_id> --session-id <session_id> \
[--caption "说明文字"]
# 通用文件
~/.coze/bridge/bin/coze-bridge send file <localPath> \
--agent-id <agent_id> --session-id <session_id> \
[--caption "..."] [--name "report.pdf"]
参数:
image: 图片 (png / jpeg / webp / gif), 聊天界面直接渲染file: 通用文件 (pdf / text / markdown 等), 显示为附件<localPath>: 本地文件路径 (相对当前目录或绝对路径)--agent-id / --session-id: 从 <coze-context> 抄过来 (必填)--caption: 一行说明 (可选, 但强烈推荐 — 用户体验好十倍)--name: 用户看到的文件名 (默认从 path 取 basename)
典型用法:
生成 + 发 (必须 && 串行 — 文件没写完时 send 会读到残缺):
python3 plot.py && ~/.coze/bridge/bin/coze-bridge send image plot.png \
--agent-id <agent_id> --session-id <session_id> \
--caption "训练曲线 (epoch 1-100)"
批量发 (同一 turn 内 ID 不变):
A=<agent_id>; S=<session_id>
for f in chart1.png chart2.png chart3.png; do
~/.coze/bridge/bin/coze-bridge send image "$f" --agent-id "$A" --session-id "$S" --caption "$f"
done
生成 PDF + 发:
pandoc report.md -o report.pdf && ~/.coze/bridge/bin/coze-bridge send file report.pdf \
--agent-id <agent_id> --session-id <session_id> \
--caption "本周报告"
模式 B: 群文件 (仅群聊可用)
触发: 你用 coze agent 命令把文件上传到群里 (拿到群文件 path), 或从群里获取到一个已有的群文件 path, 现在要把它发给当前用户看。文件已在云端, 你不需要重新上传, 直接透传即可。
前提: <coze-context> 是群聊消息 (有 group_id)。单聊场景下你不会有群文件 path, 用不到本模式。
~/.coze/bridge/bin/coze-bridge send file <groupFilePath> \
--agent-id <agent_id> --session-id <session_id> \
--group-file --mime <mimeType> \
[--name "..."] [--caption "..."]
参数:
<groupFilePath>: 群文件绝对路径 (/ 开头; 从 coze agent file write/upload 或 coze agent file list/read 输出拿来, 原样填——返回的路径已经是 / 开头的)--group-file: 群文件模式开关 (必填)--mime: mime 类型 (必填 — 云端没有本地文件可探, 必须显式)
- 常见:
application/pdf, image/png, image/jpeg, text/markdown, text/plain
--name: 用户看到的文件名 (默认取 path basename; 群文件场景强烈建议显式给个可读名字)
path 来源限制: 群文件 path 只能来自 coze agent ... 命令输出。不要自己编, 也不要把网上找的 URL 当群文件 path — 云端找不到对应资源会失败。
典型用法:
# 你刚 coze agent file write 改了群文件, 转发给用户
~/.coze/bridge/bin/coze-bridge send file "/本周周报.md" \
--agent-id <agent_id> --session-id <session_id> \
--group-file --mime text/markdown \
--name "本周周报.md" --caption "已按你的要求更新"
群文件协作产出 → 让用户看到的完整衔接 pattern 见 coze-project 技能的"协作产出"一节。
何时不该用 --group-file:
- 你自己刚生成的本地文件 → 用模式 A, 让 Bridge 上传
- 你只有本地路径, 不知道云端 path → 用模式 A
- 网上随手下载的链接 → 先下到本地, 再用模式 A 走上传
何时该触发 (适用于两种模式)
| 场景 | 例子 | 模式 |
|---|
| 用户明说要看 | "show me", "send me", "把图发我", "可以给我看吗" | A 或 B |
| 用户问结果, 你刚生成了文件 | 用户问"训练效果怎么样", 你跑了 matplotlib 出了 plot.png | A |
| PDF / 报告 / 导出任务 | 用户说"出个周报", 你 pandoc 出了 report.pdf | A |
| 截图 / OCR / 图像处理 | 你截了图 / 做了图像处理 | A |
| 数据分析可视化 | 你画了 chart | A |
| 群文件协作产出 | 你 coze agent 改了群文件, 用户在等结果 | B |
| 任何"做完应该展示给用户"的文件 | 用户的隐式期望 — 不要等 ta 问 | A 或 B |
⚠️ 生成文件 ≠ 送达用户 — 必须显式 coze-bridge send, 否则用户看不到。
何时不该触发
- 纯文本回答 (直接说就行)
- 短代码块 / 命令输出 (markdown 代码块够了)
- 大于 50MB 的本地文件 (模式 A 会被拒; 模式 B 不受此限)
- 你只有想象出来的"path 字符串", 没真上传/改过 (模式 B 会失败)
退出码
| 退出码 | 含义 | 你的动作 |
|---|
| 0 | 成功送达用户 | 简短报告"已发送 <name>"给用户即可 |
| 3 | 文件 / 路径 / 格式问题, 或 --group-file 缺 --mime | 看 stderr, 换路径 / 转格式 / 补 --mime 后重试 |
| 4 | 环境问题 (缺 flag / daemon 没起 / 鉴权失败) | 看 stderr; 如果是缺 flag 自查 <coze-context> 重新抄 ID 再发 |
| 5 | 网络 / 上传失败 | 重试 1 次; 仍失败告诉用户"上传失败, 稍后再试" |
stderr 的错误信息可以直接转给用户, 不要硬翻译。
常见错误 + 修法
missing --agent-id and/or --session-id (exit 4): 没从 <coze-context> 抄 ID。重新看本 turn 用户消息开头的 <coze-context> 块, 把 agent_id / session_id 原样填到 flag 里。
coze-bridge daemon not running (exit 4): daemon 挂了, 你重试也修不了, 告诉用户"暂时无法发送文件"。
文件路径不对 (模式 A): 把文件先 cp 到当前目录, 用相对路径 ./foo.png。
文件 > 50MB (模式 A):
- 图片压缩:
magick convert input.png -resize 50% output.png
- PDF 压缩:
gs -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook -sDEVICE=pdfwrite -o out.pdf in.pdf
- 拆分多次发
- 真发不了告诉用户"文件太大, 当前支持 50MB 以内"
格式不支持:
- 转格式:
.svg → .png (用 ImageMagick); .docx → .pdf (libreoffice --headless --convert-to pdf)
- 如果是 PDF 但用了
send image, 改成 send file
上传失败 (模式 A): 重试 1 次 (网络瞬断常见); 仍失败告诉用户稍后再试
--group-file requires --mime (exit 3): 模式 B 下 mime 必须显式给, 加 --mime application/pdf / --mime image/png 等。
path is not a regular file (exit 3, 模式 A 误用): 你拿了群文件 path 但走了模式 A → daemon 把字符串当本地路径 stat 失败。修法: 改用模式 B, 加 --group-file --mime <m>。
模式 B 找不到云端资源: 把本地真实文件当群文件发 → 云端按"群文件引用"路由, 查不到不存在的资源失败。修法: 本地文件走模式 A, 让 Bridge 帮你上传。
不要做的事
- ❌ 不要忘记带
--agent-id / --session-id — 命令无状态, 每次都要从 <coze-context> 抄
- ❌ 不要自己编 agent_id / session_id — 只能用
<coze-context> 里云端下发的值
- ❌ 不要把 acpSessionId / 本地 session ID 当
--session-id — 必须用 <coze-context> 里那个云端下发的 session_id
- ❌ 不要 inline base64 长图到对话里 — 用户聊天界面看不到 base64, 全是乱码
- ❌ 不要把绝对路径贴给用户 — 用户没办法访问你的文件
- ❌ 不要后台 spawn (
&) 跟 send 串 — 文件还没写完时 send 会读到残缺
- ❌ 不要在生成命令报错时还发文件 — 检查
&& 是否能跑到 send
- ❌ 不要把群文件 path 当本地路径走模式 A — 必须用模式 B +
--group-file --mime
- ❌ 不要把本地文件走模式 B — 群文件模式跳过上传, 云端找不到
- ❌ 不要在单聊场景下走模式 B — 单聊没有 group_id 来源, 你也不会有群文件 path
总结
核心信号: 你脑里冒出"用户会想看到这个文件" → 从 <coze-context> 抄 agent_id/session_id → 立刻 coze-bridge send, 不要等用户主动问。
两种模式速选:
- 文件在你本地 (你刚生成 / cp 进来) → 模式 A, Bridge 帮你上传
- 文件在云端群文件里 (你用
coze agent 拿到 path) → 模式 B, --group-file --mime <m>, 不上传