setup-notifications-via-wecom

通过 WeCom 设置通知

概述

此技能可帮助你通过 WeCom 群机器人 webhook 发送清晰、明确的技术通知。 请使用以下设置和发送工作流：

1. 一次性设置：保存 webhook URL、测试连接，并创建可复用的发送脚本。
2. 发送消息：撰写能够区分状态与增量、定义每个数字含义，并避免导致以往备份同步通知令人困惑的误导性表达的消息。

随附脚本 scripts/send_wecom.py 使用主机网络配置处理实际 HTTP 调用。收件人身份必须通过明确配置指定： self 可以自动发送；others 需要人工确认；未配置身份时会快速失败。

如果要集成现有的 Alibaba Cloud SLS 通知流水线或定期摘要，请阅读 SLS 适配器指南。 复用项目的采样器、调度器和 SLS 同步负责人；随附的发送脚本仍负责普通纯文本发送。

何时使用此技能

在以下情况下触发此技能：

• 用户说“发送 WeCom 通知”“企业微信通知”“企微机器人”或“webhook 通知”。
• 用户想为备份、同步、cron 任务或服务状态设置告警。
• 用户要求你撰写状态或告警消息，而你需要确保内容清晰明确。
• 用户提到某条消息令人困惑或具有误导性，并希望修正。

快速开始：配置 Webhook

1. 检查现有配置：

   cat ~/.config/setup-notifications-via-wecom/config.json
   

   如果配置存在且包含 webhook_url，请跳转到发送消息。

2. 获取 webhook URL：从 WeCom 群机器人设置中获取。格式如下：

   https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY
   

3. 私下保存（放在技能包之外，以便更新后仍然保留）：

   mkdir -p ~/.config/setup-notifications-via-wecom
   echo '{"webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"}' \
     > ~/.config/setup-notifications-via-wecom/config.json
   chmod 600 ~/.config/setup-notifications-via-wecom/config.json
   

4. 准确判断目标并绑定规范发送脚本，不要暴露或改写 webhook 值：

   uv run --no-project python scripts/set_recipient.py \
     --scope self --label "My private self channel"
   

   只有当配置的 webhook 仅对用户可见时才使用 self。其他任何个人或群组都使用 others。目标不明确时不要猜测。该命令还会记录此发送脚本的绝对路径和摘要；发送脚本升级后，请重新运行该命令，再次发送。

5. 测试连接：发送一条测试消息（从技能目录运行）：

   uv run --no-project python scripts/send_wecom.py --message "WeCom webhook test ✅"
   

   如果你在 WeCom 群里看到该消息，说明设置已完成。

消息最佳实践

这些规则来自实际修正。请将其应用于每条通知。

1. 先写标题

第一行必须说明发生了什么。不要把结论藏在后面。

Claude Code 备份同步完成 ✅

2. 区分状态与增量

• 状态：当前总量（例如，源目录有 1075 个主会话，备份有 2328 个）。
• 增量：本次运行中发生的变化（例如，自 03:00 以来新增了 13 个主会话和 230 个其他文件）。

如果今天只有 13 个会话是新增的，就不要说“已同步 1075 个会话”。

3. 定义每个数字

每个数量都必须说明其统计对象。建议这样写：

- 源目录主 session：1075 个
- 备份主 session：2328 个

避免单独使用“session”等未定义术语，因为它可能包括工作流日志、子 Agent 文件或工具输出。

4. 使用直白的位置名称，不要用行话

建议使用：

• “电脑上”／“源目录”
• “备份里”／“备份仓库”

避免使用：

• “当前”
• “含历史”
• “旧 session”（除非已定义）

5. 省略无关信息

除非用户明确要求，否则不要包含提交哈希、文件路径、内部文档引用或冗长解释。

6. 技术表述准确，不要居高临下

使用正确的技术术语并加以定义。不要为了“大白话”而把所有内容都简化到失去准确性。

7. 包含验证指标

如果用户问“有没有遗漏？”，请直接回答：

- 验证：0 缺失，0 滞后

8. 以接下来的操作收尾

告诉用户是否需要采取任何操作：

- 下一步：无需操作，下次自动同步 03:00

通知模板

备份同步完成

备份或同步任务完成且需要报告完整性时使用。

Claude Code 备份同步完成 ✅

- 自动同步：今日 03:00 正常执行
- 本次手动同步：补充 03:00 后的增量
  - 主 session：13 个
  - 子代理/工具输出/工作流：230 个
  - 合计：243 个文件
- 验证：0 缺失，0 滞后
- 当前状态：
  - 源目录主 session：1075 个
  - 备份主 session：2328 个
- 下一步：无需操作，下次自动同步 03:00

告警

用于需要立即采取行动的情况。请勿将此模板用于常规的“一切正常”更新。

🚨 [P?] [服务/任务名] [症状]

- 影响：[谁/什么受影响，程度如何]
- 严重程度：[P1–P5 等级]
- 开始时间：[YYYY-MM-DD HH:MM TZ]
- 已采取：[正在做的动作]
- 下一步：[建议动作或预计下次更新时间]
- 相关链接：[dashboard/runbook，可选]

规则：

• 针对症状而非原因发出告警（例如，“API 错误率 > 10%”，而非“CPU 99%”）。
• 如果接收者无法采取任何具体行动，请勿将其作为告警发送。
• 如实说明不确定性；不要猜测根本原因。

状态更新

用于常规的“一切正常”更新。

[任务名] 状态正常 ✅

- 检查时间：2026-06-24 03:00 CST
- 关键指标：
  - 源目录主 session：1075 个
  - 备份主 session：2328 个
- 本次变更：无
- 下一步：无需操作

发送消息

发送前请读取 recipient_scope 和 recipient_label。self 目标是用户自己的投递渠道，无需授权。others 目标表示向外部发送：展示准确的标签和消息，并等待当前有效的人工确认门控。元数据缺失或无效属于配置错误，不能因此自行猜测。

Webhook URL 匹配只能证明是同一端点，不能证明接收者范围相同。如果新观察结果与已存储的 self 标签冲突，请暂停该次发送，并核实准确的群组和受众。仅显示成员名称并不能证明其属于另一个人的身份。对于已确认的 self 绑定，请保留正常的自动投递；不要重新标记群组或改写共享元数据来绕过确认边界。对于定期发送到 others 的消息，确认必须涵盖确切的群组、报告内容和计划安排，以及任何另行要求的部署审批。

选项 A：直接使用捆绑脚本

uv run --no-project python scripts/send_wecom.py \
  --message "你的消息内容"

对于多行消息，请使用文件：

cat > /tmp/wecom_msg.txt <<'EOF'
Claude Code 备份同步完成 ✅

- 验证：0 缺失，0 滞后
EOF

uv run --no-project python scripts/send_wecom.py \
  --file /tmp/wecom_msg.txt

选项 B：内联 curl

如果你不想使用脚本：

curl -s -X POST 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "msgtype": "text",
    "text": {
      "content": "YOUR_MESSAGE"
    }
  }'

网络：遵循主机／项目的 HTTP(S) 代理和 no_proxy 策略。必须使用代理时，必须继续使用；不要根据腾讯域名推断必须直接连接。主机要求使用 HTTP(S) 代理时，请显式配置：Python urllib 不支持通用 SOCKS ALL_PROXY 路由。在 macOS 上，即使代理环境变量为空，也可能会选择系统代理。要排查代理选择、例外情况以及 HTTP 绕过与 TUN 诊断，请加载 tunnel-doctor 及其代理冲突参考文档（proxy_conflict_reference.md 的 NO_PROXY 部分）；请检查发送进程，而不是清除所有代理。

升级发送器后，请使用现有的 set_recipient.py 工作流刷新其配置的摘要，同时保留相同的范围和标签。不要仅为通过校验而将群组重新标记为 self。

工作流：为脚本添加企业微信通知

当用户提出“让我的备份脚本发送企业微信通知”时，请执行以下操作：

1. 确认 Webhook 已配置（参见快速入门）。
2. 读取明确的接收者范围／标签；仅当范围为 self 时自动发送。
3. 确定通知类型（备份完成、告警、状态更新、自定义）。
4. 从脚本输出中收集准确的数值及其定义。
5. 使用上述模板撰写消息。
6. 对于 others，先取得人工确认；然后调用 scripts/send_wecom.py。
7. 确认消息已送达配置的目标。对于自动监控器／工作器集成，请遵循下文的回执约定。

自动工作进程回执

使用现有绑定的发送方和目标；在所属工作进程中保留事件身份和投递状态。对于单个自动事件，调用 send_message(..., max_attempts=1) 或受支持的由守卫拥有的发件箱路径。通用手动发送的重试默认值不是工作进程的投递策略。

在决定是否允许后续尝试之前，先对已解析的响应进行分类：

证据	工作进程结果
errcode=0 的 JSON 对象，且值为整数	API 已接受；接收方确认属于另一项观察
errcode 为非零整数的 JSON 对象	API 明确拒绝
errcode 缺失或为 null、布尔值、字符串、非整数、无效 JSON、超时或连接中断	未知；保留事件身份，不要自动重放

对于 Python，使用 type(code) is int 进行测试；isinstance(False, int) 为真，而且 False == 0 不应被视为已接受。如果通用发送方在返回有效响应前抛出异常，所属工作进程应将结果保留为未知。新测试必须使用明确的测试标签来测试一个真正不同的事件，而不是给含糊不清的旧事件改名或重新提交。验证实际的调度器/工作进程 → 事件 → 发送方 → 回执路径；独立的机器人调用无法验证后台链路。

此技能不做什么

• 它不会创建或管理 WeCom 群机器人——请先从 WeCom 获取 webhook 密钥。
• 它不会推断 webhook 会触达谁——请使用 set_recipient.py 明确分类目标。
• 它不处理富媒体消息（markdown 卡片、新闻、图片）——仅支持纯文本。
• 手动 --message / --file 发送在遇到暂时性错误时最多重试 3 次。由守卫拥有的自动 --outbox 投递只进行一次 HTTP 尝试，并要求使用经守卫批准的负载摘要；后续运行绝不会发送已有负载。
• 它不会更改主机代理配置，也不会在失败后自动切换路由。

故障排查

Connection closed 或超时

检查已配置的路由，但不要打印代理凭据。遵循主机批准的直连/代理策略，并在该路由上诊断连接故障。 不要擅自清除代理、尝试其他端点，也不要重放含糊不清的发送。

未收到消息，但 curl 返回了 200

检查响应正文：HTTP 200 但 errcode 非零表示失败。errcode=0 表示 API 已接受，不代表接收方已收到。需要确认接收情况时，请核实目标群组和消息。直接测试机器人无法验证 SLS/其他调度器：请在授权测试次数内，单独执行并检查该原生路径。

找不到配置文件

重新运行设置步骤。脚本要求 ~/.config/setup-notifications-via-wecom/config.json 中包含 webhook_url 字段。

参考资料

• references/message_best_practices.md — 根据本次会话中的修正提炼出的精简检查清单。
• references/sls-recurring-notifications.md — 阅读有关由 SLS 支持的定期报告的内容：结果大小限制、评估日期、复用现有所有者以及原生投递验收。
• scripts/send_wecom.py — 发送脚本。
• scripts/set_recipient.py — 原子性地记录 self 与 others，以及规范的发送方路径/摘要，且不会打印 webhook。