send-media

在 Telegram 上发送媒体

从个人 Telegram 账号发送文件、照片、视频、语音消息和文档。

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

前置检查

检查会话是否已授权（不能只确认文件存在）：

bun "$SCRIPT" check-auth

如果状态为 EXPIRED，请先运行 /tlg:setup（使用 3 步非交互式授权流程）。

用法：tg-cli.ts（简单场景）

/usr/bin/env bash << 'EOF'
ROOT="$(cc-plugin-root tlg)"
SCRIPT="$ROOT/scripts/tg-cli.ts"

# Send a photo/image (auto-detected)
bun "$SCRIPT" send-file @username /path/to/photo.jpg

# Send with caption (plain text only)
bun "$SCRIPT" send-file -1003958083153 /path/to/image.png -c "Check this out"

# Force send as document (no preview)
bun "$SCRIPT" send-file @username /path/to/image.png --document

# Send voice note
bun "$SCRIPT" send-file -1003958083153 /path/to/audio.ogg --voice

# Send round video
bun "$SCRIPT" send-file @username /path/to/video.mp4 --video-note
EOF

已知限制：通过 CLI 添加的说明文字只能是纯文本（不支持 HTML）。如需格式化说明文字，请使用 draft 技能在已保存消息中撰写消息，将其复制到目标聊天，然后在那里手动附加文件。

参数（tg-cli.ts）

参数	类型	描述
recipient	string/int	用户名、电话号码或聊天 ID
file	path	本地文件路径
-c/--caption	string	说明文字（通过 CLI 只能使用纯文本）
--voice	flag	作为语音消息发送
--video-note	flag	作为圆形视频发送
--document	flag	强制作为文档发送（不显示媒体预览）

支持的格式

GramJS 会根据扩展名自动检测媒体类型。可使用标志进行覆盖。

类型	扩展名	备注
照片	jpg, png, webp	Telegram 会进行压缩
视频	mp4, mov, avi	使用 --document 可跳过压缩
音频	mp3, m4a, flac	以音频播放器形式发送
语音	ogg (opus)	需要 --voice 标志
文档	pdf, zip, md, any	作为文件附件发送

反模式（绝对不要这样做）

反模式	失败原因
未先检查授权状态就运行 bun "$SCRIPT"	如果会话已过期，授权将失败
在 -c 说明文字中使用格式化文本	CLI 说明文字只能是纯文本 — 格式化说明文字请使用 draft 技能
前置检查时只确认会话文件存在	会话文件可能存在但已过期 — 必须使用 check-auth 检查

执行后复盘

此技能执行完毕后，关闭前请检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的说明或错误表。
2. 参数或输出是否发生变化？ — 如果 tg-cli.ts 的接口发生变化，请相应更新用法示例和参数表。
3. 是否需要采用变通方法？ — 如果你不得不临时变通（使用不同标志、增加步骤），请更新此 SKILL.md，确保下次调用时不必重复采用相同的变通方法。

仅在问题真实且可复现时进行更新，不要基于猜测更新。