xykong Flux Notifier Skill
使用时机
| 场景 | event_type | 是否阻塞 |
|---|---|---|
| 任务完成，无需决策 | completion |
否（加 --no-wait） |
| 需要用户选择下一步 | choice |
是（默认） |
| 后台步骤完成汇报 | step |
否（加 --no-wait） |
| 需要用户提供文字输入 | input_required |
是 |
| 普通信息推送 | info |
否（加 --no-wait） |
| 非关键警告 | warning |
否（加 --no-wait） |
| 需要用户介入的严重错误 | error |
是 |
调用方式
安装后直接调用（推荐）：
# 安装
uv tool install flux-notifier # 或: pipx install flux-notifier / pip install flux-notifier
# 调用
notify send [选项]
常用选项
| 选项 | 说明 |
|---|---|
--title TEXT |
通知标题（必填） |
--body TEXT |
正文，支持 Markdown |
--json TEXT |
完整 JSON payload（与 --title 互斥） |
--file PATH |
从 JSON 文件读取 payload |
--actions TEXT |
操作按钮 JSON 数组 |
--event-type TEXT |
事件类型，默认 info |
--targets TEXT |
逗号分隔的终端名，不填则推送全部 |
--timeout INTEGER |
等待响应超时秒数（阻塞场景必须设置） |
--no-wait |
有 actions 也立即返回，不等待用户响应 |
使用示例
1. 简单完成通知（非阻塞）
notify send \
--title "代码审查完成" \
--body "在 **auth.py** 发现 3 个问题，已生成修复方案。" \
--no-wait
2. 需要用户决策（阻塞）
import subprocess, json
payload = {
"version": "1",
"event_type": "choice",
"title": "是否部署到生产环境？",
"body": "所有测试通过，**3 个文件**已修改，准备部署。",
"actions": [
{"id": "deploy", "label": "立即部署", "style": "primary"},
{"id": "review", "label": "先审查", "style": "default"},
{"id": "abort", "label": "中止", "style": "destructive"}
],
"metadata": {"source_app": "opencode", "priority": "high"}
}
result = subprocess.run(
["notify", "send", "--json", json.dumps(payload), "--timeout", "300"],
capture_output=True, text=True
)
response = json.loads(result.stdout)
action_id = response.get("action_id") # "deploy" | "review" | "abort" | None（超时）
3. 带跳转链接的错误通知
payload = {
"version": "1",
"event_type": "error",
"title": "构建失败",
"body": "`src/auth.ts:42` 发现类型错误",
"actions": [
{
"id": "open",
"label": "在 VS Code 中打开",
"style": "primary",
"jump_to": {"type": "vscode", "target": "vscode://file/path/to/src/auth.ts:42"}
}
]
}
result = subprocess.run(
["notify", "send", "--json", json.dumps(payload), "--timeout", "300"],
capture_output=True, text=True
)
4. 步骤汇报附带截图（非阻塞）
payload = {
"version": "1",
"event_type": "step",
"title": "数据库迁移完成",
"body": "已执行 **12 条迁移**，耗时 3.2s。",
"image": {"url": "https://...screenshot.png", "alt": "迁移日志"},
"metadata": {"source_app": "opencode", "priority": "low"}
}
subprocess.run(
["notify", "send", "--json", json.dumps(payload), "--no-wait"],
capture_output=True
)
响应格式
有 actions 时（等待用户响应）：
{
"notification_id": "uuid",
"action_id": "deploy",
"timestamp": "2026-03-08T10:00:00Z",
"source_terminal": "macos",
"timeout": false
}
超时时：{"action_id": null, "timeout": true, ...}
无 actions 时（立即返回）：
{"notification_id": "uuid", "delivered": ["macos", "feishu_webhook"], "failed": [], "timestamp": "..."}
决策规则
- choice / input_required / error：必须阻塞等待用户响应，
--timeout 300为推荐值。 - completion / step / info / warning：使用
--no-wait，避免阻断 AI 工作流。 - 紧急事件：在 metadata 中设置
"priority": "urgent"。 - 超时处理：检查响应中的
"timeout": true，并进行重试或中止处理。
问题诊断与首次配置
触发条件：以下任一情况出现时，必须读取 troubleshooting.md 并主动引导用户修复，
而不是直接报错或停止工作：
| 触发信号 | 说明 |
|---|---|
输出包含 WARNING flux_notifier.router: no adapters configured |
无任何适配器启用 |
响应 JSON 中 delivered: [] |
通知未送达任何终端 |
响应 JSON 中 failed 列表非空 |
至少一个适配器发送失败 |
| 用户说"没收到通知" / "通知没弹出来" | 用户侧感知到通知丢失 |
执行时报 FileNotFoundError、ValidationError |
配置文件缺失或格式错误 |
处理规则：
- 执行
troubleshooting.md中的"快速诊断命令"，定位问题层级。 - 根据诊断结果，主动询问用户期望使用哪个通知终端（
troubleshooting.md§ 选择适配器）。 - 按用户选择，逐步执行对应适配器的配置流程，途中需要用户提供的信息（Webhook URL、 App Secret 等）要明确向用户索取，不要假设或跳过。
- 配置完成后，必须执行验证命令，确认
delivered非空后再继续原任务。 - 若用户环境不在 macOS 上（如服务器、CI），跳过 macOS 选项，优先推荐飞书 Webhook 或邮件。
附加文件路径（同目录）：
troubleshooting.md
JSON Schema 快速参考
{
"version": "1",
"event_type": "completion | choice | step | input_required | info | warning | error",
"title": "string（必填，最长 128 字符）",
"body": "string（可选，支持 Markdown，最长 4096 字符）",
"image": {"url": "string", "alt": "string"},
"actions": [
{
"id": "string（唯一，最长 64 字符）",
"label": "string（最长 64 字符）",
"style": "primary | destructive | default",
"jump_to": {"type": "url | vscode | pycharm | terminal", "target": "string"}
}
],
"metadata": {
"source_app": "opencode",
"priority": "low | normal | high | urgent",
"ttl": 300
}
}