hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/pipe-script-output.md

sidebar_position	title	description
12	将脚本输出推送到消息平台	使用 `hermes send` 将任意 shell 脚本、cron 任务、CI hook 或监控守护进程的文本发送到 Telegram、Discord、Slack、Signal 等平台。

将脚本输出推送到消息平台

hermes send 是一个轻量、可脚本化的 CLI，能将消息推送到 Hermes 已配置的任意消息平台。可以把它理解为跨平台的通知专用 curl——无需运行中的 gateway，无需 LLM，也无需在每个脚本里重复粘贴 bot token。

适用场景：

• 系统监控（内存、磁盘、GPU 温度、长时任务完成通知）
• CI/CD 通知（部署完成、测试失败）
• 需要将结果推送给你的 cron 脚本
• 从终端发送一次性消息
• 将任意工具的输出管道到任意平台（make | hermes send --to slack:#builds）

该命令复用 hermes gateway 已有的凭据和平台适配器，无需维护第二套配置。

---

快速开始

# 向某平台的默认频道发送纯文本
hermes send --to telegram "deploy finished"

# 将任意命令的 stdout 通过管道传入
echo "RAM 92%" | hermes send --to telegram:-1001234567890

# 发送文件
hermes send --to discord:#ops --file /tmp/report.md

# 附加主题/标题行
hermes send --to slack:#eng --subject "[CI] build.log" --file build.log

# 指定线程目标（Telegram 话题、Discord 线程）
hermes send --to telegram:-1001234567890:17585 "threaded reply"

# 列出所有已配置的目标
hermes send --list

# 按平台过滤
hermes send --list telegram

---

参数参考

标志	说明
-t, --to TARGET	目标地址。参见目标格式。
message（位置参数）	消息文本。省略时从 --file 或 stdin 读取。
-f, --file PATH	从文件读取消息体。--file - 强制从 stdin 读取。
-s, --subject LINE	在消息体前添加标题/主题行。
-l, --list	列出可用目标。可选位置参数用于按平台过滤。
-q, --quiet	成功时不输出到 stdout（仅返回退出码——适合脚本使用）。
--json	输出发送结果的原始 JSON。
-h, --help	显示内置帮助文本。

目标格式

格式	示例	含义
platform	telegram	发送到该平台配置的默认频道
platform:chat_id	telegram:-1001234567890	指定数字 chat / 群组 / 用户
platform:chat_id:thread_id	telegram:-1001234567890:17585	指定线程或 Telegram 论坛话题
platform:#channel	discord:#ops	易读的频道名称（通过频道目录解析）
platform:+E164	signal:+15551234567	以电话号码寻址的平台：Signal、SMS、WhatsApp

Hermes 附带适配器的所有平台均可作为目标： telegram、discord、slack、signal、sms、whatsapp、matrix、 mattermost、feishu、dingtalk、wecom、weixin、email 等。

退出码

码	含义
0	发送（或列出）成功
1	平台层面投递失败（认证、权限、网络）
2	用法 / 参数 / 配置错误

退出码遵循标准 Unix 惯例，脚本可以像处理 curl 或 grep 一样对其进行分支判断。

---

消息体解析顺序

hermes send 按以下顺序解析消息体：

1. 位置参数 — hermes send --to telegram "hi"
2. --file PATH — hermes send --to telegram --file msg.txt
3. 管道 stdin — echo hi | hermes send --to telegram

当 stdin 是 TTY（无管道）时，Hermes 不会等待输入——你会收到明确的用法错误提示。这可以防止脚本在意外省略消息体时挂起。

---

实际使用示例

监控：内存 / 磁盘告警

用一行简洁的代码替换 watchdog 脚本中的 curl https://api.telegram.org/... 调用：

#!/usr/bin/env bash
ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
if [ "$ram_pct" -ge 85 ]; then
  hermes send --to telegram --subject "⚠ MEMORY WARNING" \
    "RAM ${ram_pct}% on $(hostname)"
fi

由于 hermes send 复用你的 Hermes 配置，同一脚本可在任何安装了 Hermes 的主机上运行——无需手动将 bot token 导出到每台机器的环境变量中。

:::tip 不要用 gateway 监控自身 对于可能在 gateway 本身出现问题时触发的 watchdog（OOM 告警、磁盘满告警），请继续使用最简单的 curl 调用，而非 hermes send。如果 Python 解释器因机器抖动无法加载，你仍然希望告警能发出去。 :::

CI / CD：构建与测试结果

# 在 .github/workflows/deploy.yml 或任意 CI 脚本中
if ./scripts/deploy.sh; then
  hermes send --to slack:#deploys "✅ ${CI_COMMIT_SHA:0:7} deployed"
else
  tail -n 100 deploy.log | hermes send \
    --to slack:#deploys --subject "❌ deploy failed"
  exit 1
fi

Cron：每日报告

# Crontab 条目
0 9 * * * /usr/local/bin/generate-metrics.sh \
  | /home/me/.hermes/bin/hermes send \
      --to telegram --subject "Daily metrics $(date +%Y-%m-%d)"

长时任务：完成后推送通知

./train.py --epochs 200 && \
  hermes send --to telegram "training done" || \
  hermes send --to telegram "training failed (exit $?)"

脚本中使用 --json 与 --quiet

# 投递失败时让脚本硬失败；成功时不污染日志
hermes send --to telegram --quiet "keepalive" || {
  echo "Telegram delivery failed" >&2
  exit 1
}

# 捕获消息 ID 以便后续编辑 / 回复线程
msg_id=$(hermes send --to discord:#ops --json "build started" \
  | jq -r .message_id)

---

hermes send 需要 gateway 运行吗？

通常不需要。 对于所有基于 bot token 的平台——Telegram、Discord、Slack、Signal、SMS、WhatsApp Cloud API 等——hermes send 直接使用 ~/.hermes/.env 和 ~/.hermes/config.yaml 中的凭据调用平台的 REST 接口。它是一个独立的子进程，消息投递完成后即退出。

只有依赖持久适配器连接的插件平台才需要运行中的 gateway（例如，某个保持长连接 WebSocket 的自定义插件）。此时你会收到明确的错误提示，指引你启动 gateway；执行 hermes gateway start 后重试即可。

---

列出与发现目标

在向特定频道发送消息之前，可以查看可用目标：

# 列出所有已配置平台的所有目标
hermes send --list

# 仅列出 Telegram 目标
hermes send --list telegram

# 机器可读格式
hermes send --list --json

列表数据来源于 ~/.hermes/channel_directory.json，gateway 运行期间每隔几分钟刷新一次。如果看到"尚未发现频道"，请先启动一次 gateway（hermes gateway start）以填充缓存。

易读名称（discord:#ops、slack:#engineering）在发送时通过该缓存解析，无需记忆数字 ID。

---

与其他方案的对比

方案	多平台	复用 Hermes 凭据	需要 gateway	最适合
hermes send	✅	✅	否（bot token）	以下所有场景
对各平台直接 curl	各自单独编写	手动管理	否	关键 watchdog
带 --deliver 的 cron 任务	✅	✅	否	定时 agent 任务
send_message agent 工具	✅	✅	否	agent 循环内部

hermes send 有意保持最简接口。如果需要 agent 决定说什么，请在对话或 cron 任务中使用 send_message 工具。如果需要定时运行并生成 LLM 内容，请使用带 deliver='telegram:...' 的 cronjob(action='create', prompt=...)。如果只需要管道传输原始字符串，直接用 hermes send。

---

相关文档

• 用 Cron 自动化一切 — 输出自动投递到任意平台的定时任务。
• Gateway 内部机制 — hermes send 与 cron 投递共享的投递路由器。
• 消息平台配置 — 各平台的一次性配置说明。