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. WeCom グループボットの設定からwebhook URL を取得します。次のような形式です。

   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. 最初に見出しを書く

1 行目で何が起きたかを伝えてください。結論を後回しにしないでください。

Claude Code 备份同步完成 ✅

2. 状態と差分を区別する

• 状態：現在の合計数（例：ソースにはメインセッションが 1075 件あり、バックアップには 2328 件あります）。
• 差分：今回の実行で変化した内容（例：03:00 以降、メインセッション 13 件とその他のファイル 230 件が追加されました）。

今日新たに追加されたのが 13 件だけなら、「セッション 1075 件を同期しました」とは書かないでください。

3. すべての数値の意味を明示する

件数には必ず、その数値が何を数えているかを添えてください。次のような書き方がおすすめです。

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

「セッション」のように定義のない用語は避けてください。ワークフローのジャーナル、サブエージェントのファイル、ツールの出力が含まれている可能性があります。

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，可选]

ルール:

• 原因ではなく症状に対してアラートを出します (例: 「CPU 99%」ではなく「API エラー率 > 10%」)。
• 受信者が具体的に何もできない場合は、アラートとして送信しないでください。
• 不確実性について正直に伝えてください。根本原因を推測しないでください。

ステータス更新

日常的な「問題なし」の更新に使用します。

[任务名] 状态正常 ✅

- 检查时间：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 ポリシーを継承します。必要なプロキシは引き続き使用する必要があります。Tencent ドメインから直接接続が必要であると推測しないでください。ホストが要求する場合は、HTTP(S) プロキシを明示的に設定してください。Python urllib は汎用的な SOCKS ALL_PROXY ルーティングを実装していません。macOS では、空のプロキシ環境でもシステムプロキシが選択されることがあります。プロキシの選択、例外、および HTTP バイパスと TUN の診断については、tunnel-doctor とそのプロキシ競合リファレンス (proxy_conflict_reference.md、NO_PROXY セクション) を読み込んでください。すべてのプロキシをクリアするのではなく、送信元プロセスを検査してください。

送信元をアップグレードした後は、既存の set_recipient.py ワークフローを使用して、設定されたダイジェストを更新し、同じスコープとラベルを維持してください。 ガードを通過するためだけに、グループのラベルを self に変更しないでください。

ワークフロー: スクリプトに WeCom 通知を追加する

ユーザーが「バックアップスクリプトから WeCom 通知を送信できるようにしたい」と依頼した場合は、次のようにします:

1. Webhook が設定されていることを確認します (クイックスタートを参照)。
2. 明示的な受信者スコープ/ラベルを確認します。スコープが self の場合にのみ自動送信します。
3. 通知タイプ (バックアップ完了、アラート、ステータス更新、カスタム) を特定します。
4. スクリプト出力から正確な数値とその定義を収集します。
5. 上記のテンプレートを使用してメッセージを作成します。
6. others の場合は、人間による確認を取得します。その後、scripts/send_wecom.py を呼び出します。
7. メッセージが設定されたターゲットに届いたことを確認します。自動モニター/ワーカー統合の場合は、以下の受信契約に従ってください。

自動ワーカーの配信結果

既存のバインド済み送信者と宛先を使用し、イベントの識別情報と配信状態は所有するワーカー内で管理してください。1つの自動イベントについて、send_message(..., max_attempts=1) またはサポートされているガード所有のアウトボックス経路を呼び出します。手動送信の一般的な再試行デフォルトは、ワーカーの配信ポリシーではありません。

後続の試行が許可されるかを判断する前に、解析した応答を分類してください。

根拠	ワーカーの結果
errcode=0 の整数を含む JSON オブジェクト	API が受け付けました。受信者による確認は別の観測事項です
errcode がゼロ以外の整数である JSON オブジェクト	API に明示的に拒否されました
errcode がない、または null、ブール値、文字列、整数以外、無効な JSON、タイムアウト、接続切断	不明です。イベントの識別情報を維持し、自動的に再送しないでください

Python では type(code) is int で判定してください。isinstance(False, int) は true になり、False == 0 が受け付けられたことになってはいけません。汎用送信者が有効な応答を返す前に例外を発生させた場合、所有するワーカーは結果を不明のまま保持します。新しいテストでは、曖昧な古いイベントの名前を変えたり再送したりせず、明示的なテストラベルを付けた、実際に別個のイベントを使用してください。実際のスケジューラー／ワーカー → イベント → 送信者 → 配信結果の経路を検証してください。単独のボット呼び出しでは、バックグラウンドの一連の処理は検証できません。

このスキルでできないこと

• WeCom グループボットの作成や管理は行いません。まず WeCom から webhook キーを取得してください。
• webhook が誰に届くかは推測しません。set_recipient.py で宛先を明示的に分類してください。
• リッチメディアメッセージ（Markdown カード、ニュース、画像）は扱いません。プレーンテキストのみです。
• 手動の --message／--file 送信では、一時的なエラーに対して最大3回再試行します。ガード所有の 自動 --outbox 配信では HTTP リクエストを正確に1回だけ送信し、ガードが承認した ペイロードダイジェストが必要です。後続の実行で既存のペイロードが送信されることはありません。
• ホストのプロキシ設定を変更したり、失敗後にルートを自動的に切り替えたりすることはありません。

トラブルシューティング

Connection closed またはタイムアウト

プロキシの認証情報を表示せずに、設定済みのルートを確認してください。ホストで承認されている直接接続／プロキシのポリシーに従い、そのルート上で失敗した接続を診断してください。プロキシを黙って解除したり、別のエンドポイントを試したり、結果が不明な送信を再送したりしないでください。

curl は 200 を返したが、メッセージが届かない

応答本文を確認してください。HTTP 200 でも errcode がゼロ以外なら失敗です。errcode=0 は API が受け付けたことを意味し、受信者への到達を示すものではありません。配信確認が必要な場合は、意図したグループとメッセージを確認してください。ボットへの直接テストでは、SLS などのスケジューラーは検証できません。承認されたテスト回数の範囲内で、そのネイティブな経路を個別に実行して確認してください。

設定ファイルが見つからない

セットアップ手順をもう一度実行してください。スクリプトは webhook_url フィールドを含む ~/.config/setup-notifications-via-wecom/config.json を想定しています。

参考資料

• references/message_best_practices.md — このセッションでの修正をもとにまとめた簡潔なチェックリストです。
• references/sls-recurring-notifications.md — SLS を利用した定期レポートについては、結果サイズの上限、評価日、既存の所有者の再利用、ネイティブ配信の受け付け条件を確認してください。
• scripts/send_wecom.py — 送信スクリプトです。
• scripts/set_recipient.py — webhook を表示せずに、self と others の区別に加え、正規の送信者パス／ダイジェストをアトミックに記録します。