Notify via Telegram Skill

Notify via Telegram

把 Telegram 通知视为用户对当前长任务的“结果订阅”，不是一般通知渠道。Bot Token 和目标 Chat ID 保存在用户本地配置文件中，不写入提示词、命令参数或仓库。

授权边界

只有用户在当前任务中显式调用 $dcjanus:notify-via-telegram 并要求通过 Telegram 通知，才允许发送。
不要因为任务耗时较长、执行了很多步骤、skill 被自动识别或普通任务完成而推断授权。
授权只覆盖当前任务，不延续到之后的任务。
默认不发送开始、进度、阶段完成、单条命令失败或自动重试消息。
在最终成功、确定无法继续的最终失败或必须等待用户输入时发送。可自动恢复的中间失败不发送。
等待用户处理时发送一次；用户回复并恢复执行后，当前订阅继续有效，任务最终结束时再发送结果。
每个通知事件只尝试发送一次。发送失败后不要自动重试，避免结果不确定时产生重复消息。

执行约定

Agent 调用时使用 --json，并把全局参数放在子命令前。

通知格式

只使用以下状态：

success：整个任务最终完成。
failed：整个任务确定无法完成，而不是某个中间步骤失败。
action-required：任务暂停，必须等待用户输入或授权。

title 和 summary 必填；verification、action、context 可选。保持内容简洁，不发送完整日志、堆栈、凭据或冗长本地路径。

发送成功结果：

./scripts/notify.py --json send \
  --status success \
  --title "任务标题" \
  --summary "最终结果的一句话摘要" \
  --verification "关键验证结果" \
  --context "仓库或任务上下文"

发送失败结果：

./scripts/notify.py --json send \
  --status failed \
  --title "任务标题" \
  --summary "无法完成的直接原因" \
  --action "建议的下一步"

等待用户处理：

./scripts/notify.py --json send \
  --status action-required \
  --title "任务标题" \
  --summary "当前状态" \
  --action "需要用户决定或提供的内容"

在不读取配置、不访问 Telegram 的情况下预览同样的结构化参数：

./scripts/notify.py preview \
  --status success \
  --title "任务标题" \
  --summary "最终结果的一句话摘要"

所有输入字段按纯文本传入，不添加 HTML、Markdown 或 RichText 结构。脚本负责排版和 Codex 会话链接；--json preview 返回与发送一致的 rich_message，不读取配置、不联网。

配置

默认配置文件为 ${XDG_CONFIG_HOME:-~/.config}/notify-via-telegram/config.toml；可用 NOTIFY_VIA_TELEGRAM_CONFIG 或全局 --config 指定其它文件。

./scripts/notify.py config path
./scripts/notify.py config show
./scripts/notify.py config get chat-id
./scripts/notify.py config set chat-id <chat-id>
./scripts/notify.py config set bot-token
./scripts/notify.py config unset chat-id
./scripts/notify.py config check

config set bot-token 需要用户在交互式终端中隐藏输入；不要索取 Token，也不要尝试通过命令行参数传入。
config show、config get bot-token 与所有 JSON 输出都不会回显 Token。
config check 会访问 Telegram 验证 Bot 与目标 Chat，但不会发送消息。
配置缺失时，告诉用户应执行哪些配置命令；不要替用户猜测 Token 或 Chat ID。

发送成功后读取 JSON 中的 message_id。发送失败时，把通知失败与原任务结果分开报告，不要因此改变原任务的最终状态。

维护

仅在修改消息排版或深链 bridge 时阅读 implementation.md。

Agent Skills: Notify via Telegram

Install this agent skill to your local

Skill Files