1仕組みと動作原理
2つのレイヤーに分離：1回限りの「送信機セットアップ」（Webhook の保存、受信者区分の紐付け、テスト送信検証）＋ 送信ごとの「明確な伝達」（メッセージ作成規約とテンプレート）。送信自体はスクリプトが WeCom グループボットの Webhook に POST を行う形式です。
setup-notifications-via-wecom/SKILL.md
1. **One-time setup**: store the webhook URL, test connectivity, and create a reusable sender script. 2. **Send messages**: craft messages that distinguish state from delta, define every number, and avoid the misleading patterns that made earlier backup-sync notifications confusing.
これは「なぜ法務レベルで正確なステータス配信が可能なのか」も説明しています。能力の半分はスクリプトにあり、もう半分はドキュメント作成の規律にあります。
Tencent 系サービスはローカルプロキシを迂回する必要があるため、スクリプトはリクエスト送信前に能動的に6つのプロキシ環境変数を消去します。これは中国本土のネットワーク環境に必要な対応であり、任意の最適化ではありません。
setup-notifications-via-wecom/scripts/send_wecom.py
def clear_proxy_env(): """Remove proxy env vars so Tencent endpoints are reached directly.""" for name in ( "http_proxy", "https_proxy", "all_proxy", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", ): os.environ.pop(name, None)
SKILL.md 側の対応する記述：'The bundled script `scripts/send_wecom.py` handles the actual HTTP call, including the proxy-unset rule required for Tencent services in mainland China.'
受信者識別情報は推測可能な項目ではなく必須の設定項目へと昇格：config には recipient_scope（self/others）と recipient_label が必須であり、欠落時は即座にハード障害として終了し、エージェントによる推測を許可しません。
setup-notifications-via-wecom/scripts/send_wecom.py
recipient_scope = config.get("recipient_scope") if recipient_scope not in VALID_RECIPIENT_SCOPES: print( f"Missing or invalid 'recipient_scope' in {CONFIG_PATH}; " "run scripts/set_recipient.py with self or others.", file=sys.stderr, ) sys.exit(1)
設計意図（SKILL.md）：'`self` may send automatically; `others` requires human confirmation; missing identity fails fast.'
改ざん・すり替え防止チェーン：set_recipient.py が送信スクリプトの絶対パスと sha256 を config に書き込み、送信前に send_wecom.py が再計算して照合します。不一致があれば送信を拒否し、「送信機自体のすり替え」を脅威モデルとして防ぎます。
setup-notifications-via-wecom/scripts/send_wecom.py
sender_path = Path(sender_path_value).expanduser().resolve() running_sender = Path(__file__).resolve() if sender_path != running_sender or not sender_path.is_file(): print( f"Configured sender does not match this executable: {running_sender}", file=sys.stderr, ) sys.exit(1) if not isinstance(sender_sha256, str) or sha256_path(sender_path) != sender_sha256: print( "Configured sender digest is stale; rerun scripts/set_recipient.py.", file=sys.stderr, ) sys.exit(1)
set_recipient.py 側の該当書き込み処理：sender_sha256 = sha256_path(sender_path)。
自動送信（outbox パス）はより厳格な単一回承認を採用：runaway-guard によるペイロードダイジェストの提示が必須であり、スクリプトはスキーマ、スコープ、Webhook ダイジェスト、送信機フィンガープリントがすべて一致した場合にのみ送信し、HTTP 試行は1回のみに限定されます。
setup-notifications-via-wecom/scripts/send_wecom.py
"status": "pending_auto_self", "sender_skill": "notify-wecom", "recipient_scope": "self", "recipient_label": config["recipient_label"], "webhook_sha256": webhook_sha256,
SKILL.md 側における動作差異の説明：'Manual `--message` / `--file` sends retry transient errors up to 3 times. Guard-owned automatic `--outbox` delivery makes exactly one HTTP attempt and requires the guard-approved payload digest; a later run never sends a pre-existing payload.'
設定の書き込みはアトミックに実行：一時ファイル + fsync + os.replace + ディレクトリ fsync を行い、元のファイルパーミッション（デフォルト 0600）を維持することで、設定の破損や権限の緩和を防ぎます。
setup-notifications-via-wecom/scripts/set_recipient.py
mode = stat.S_IMODE(path.stat().st_mode) or 0o600 tmp = path.with_name(f".tinkle_{path.name}.{os.getpid()}.tmp") try: fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode) with os.fdopen(fd, "w", encoding="utf-8") as handle: json.dump(config, handle, ensure_ascii=False, indent=2) handle.write("\n") handle.flush() os.fsync(handle.fileno()) os.chmod(tmp, mode) os.replace(tmp, path)
関連テスト RecipientConfigTests.test_setter_preserves_webhook_and_mode で Webhook が上書きされず mode が維持されることを明示的にアサートしています。
2コア機能
01WeCom グループボット Webhook の初回設定と導通テスト送信
02受信者分類のバインド（self は自動送信 / others は人手による確認が必要）および送信機フィンガープリントのバインド
03プレーンテキストメッセージの送信（--message / --file / --outbox の3つの排他的エントリ）
04プロキシ環境変数の隔離（Tencent への直接接続）
05一時的エラーのリトライ（手動送信時は最大3回、2秒間隔）
06レスポンスボディの真偽判定（HTTP 200 は成功を意味せず、errcode の確認が必須）
07メッセージ長のハード制限（UTF-8 換算で 4096 バイト）
083種類のメッセージテンプレート ＋ 作成規約（バックアップ完了 / アラート / ステータス更新）
09メッセージ作成チェックリスト（状態と増分の区別、各数値への定義付与、ノイズ排除、アラートは原因ではなく症状のみ報告）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| api | 企业微信群机器人 webhook（腾讯官方） |
| cli | uv（以 --no-project 方式运行脚本，避免依赖项目环境） |
| cli | python3（脚本运行时；标准库 urllib 发请求） |
| cli | curl（文档提供的等价内联发送方式） |
| cli | env（清代理的 shell 内建） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: uv run --no-project python scripts/set_recipient.py --scope self|others --l
- scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストールを宣言
- 网络端点: 外部ネットワークアクセスの宣言: POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<KEY>（JSON ペイロード {"ms
- 本地工作目录: ファイル I/O と成果物出力: ~/.config 配下に設定ディレクトリと config.json を作成（ユーザーまたはエージェントがシェルで実行、SKILL.md に chmod 60 の記載あり）
監査ノート： オレンジ判定のトリガーは【認証情報の読み取り】です。スクリプトは ~/.config/setup-notifications-via-wecom/config.json から webhook_url（この URL 内の key= パラメータは対象グループに任意のメッセージを送信可能な Bearer トークンとして機能する）および同じファイル内の識別・完全性フィールドを読み取る必要があります。同時にプロセス内でプロキシ環境変数を消去し、外部への POST を実行します。レッドではない理由：セキュリティのダウングレード（TLS 検証の無効化、スクレイピング対策の回避、大量データ収集など）がなく、トークンが意図しない対象へ送信されることもなく（対象はキーが属する Tencent 公式エンドポイント）、メッセージ内容も 4096 バイト制限と errcode チェックによって保護されています。イエローではない理由：ローカル認証情報の読み取りと外部送信を伴い、config 内の sender_path/sender_sha256 バインドは作者自身が「送信機のすり替え」を脅威モデルとして明確に想定していることを示しています。緩和策と設計の特長：self/others の権限分離 ＋ others は人手確認必須 ＋ 識別情報の欠落時は即座に失敗；outbox 自動送信は1回限りの HTTP 試行かつガードが承認したペイロードダイジェストを要求；パーミッションを保持するアトミックな config 書き込み。利用上のアドバイス：Webhook は 0600 権限の config にのみ保存しリポジトリにはコミットしないこと。また、Web からスクレイピングした内容をそのまま通知本文として送信しないようにしてください。
5二重目の独立検証
- [ok] 每条外部依赖的调用点是否真实存在 — webhook 端点（SKILL.md Quick Start 第 2 步 + 脚本 docstring + 内联 curl 三处一致）、uv --no-project（SKILL.md 命令块，脚本以 uv run 方式被调用）、python3/urllib（脚本 import 段与 urllib.request.Request/urlopen）、curl（SKILL.md 内联等价示例）、env -u / env|grep（SKILL.md 两处）。无推测项。
- [ok] 凭证/密钥处理是否有反例（例如把 webhook 打印出去、写入日志、发往第三方） — 反例检索失败：全目录 grep webhook 的每一处均不打印其值——SKILL.md 的 set_recipient 说明写 'without exposing or rewriting the webhook value'；脚本只把它用于 urllib.request.Request(webhook_url, …)，出错时的报错文案（load_config 的四条 sys.exit 提示）不含 URL 本身；唯一的 webhook 值落点是 config.json 与用户自行执行的 echo（SKILL.md 明示 chmod 600）。发信目标与密钥归属同一服务。第一遍结论成立。
- [ok] 「self 可自动发、others 需人工确认」是否只是文档口号（脚本是否真的挡） — 脚本层面真实生效：recipient_scope 不在 {self, others} 即 sys.exit(1)；outbox 自动路径额外要求 payload.delivery 的 recipient_scope 必须为 'self'、recipient_label 与 webhook_sha256 必须与当前 config 完全一致，任一不符即拒绝（'Outbox item is not bound to this explicit self target'）。不是纯口号。
- [ok] 发信器指纹绑定能否被绕过（是否只在文档里说、代码里没验） — 代码里确实验：send_wecom.py 同时比对 sender_path != running_sender 与 sha256_path(sender_path) != sender_sha256，两处不符都 sys.exit(1)。相应地，config 本身被篡改时这两个字段可被一起改写——这是该机制的边界，已在 security.injection_surface 第 ③ 点写明，不算被遗漏。
- [ok] 写盘是否可能损坏配置或放宽权限 — set_recipient.py 用 O_EXCL 建临时文件、fsync 文件、os.chmod(tmp, mode) 后 os.replace，并对父目录 fsync；mode 取自原文件（stat.S_IMODE(path.stat().st_mode) or 0o600），不会放宽。tests 里 test_setter_preserves_webhook_and_mode 对 webhook 与权限有直接断言。结论成立。
- [ok] references 与 SKILL.md 的规范条数/内容是否一致 — SKILL.md 的 Message Best Practices 8 条（标题先行/状态vs增量/数字定义/地点用词/去噪音/精确不居高临下/验证指标/下一步）在 references/message_best_practices.md 中为 12 节（多出告警 vs 状态更新、告警额外规则、常见错误模板、发送前自检），属扩充而非冲突。
- [ok] 同一 pin 下本 skill 是否曾产出过旧侦查记录 — data/analysis 目录中不存在 setup-notifications-via-wecom.json 的旧记录（本次为首次产出）。同 repo 其他 slug 有旧记录的情况见各自文件。
- [ok] pin commit 与 skill.path 是否与任务书一致 — git rev-parse HEAD = d5c4678cb5d4fd6acc9c922690df035dbd33d247；目录位于仓库根，相对路径 setup-notifications-via-wecom；本目录最后提交 878f947（2026-09-07）。GitHub API 复核 MIT / stars 1392 / pushed 2026-09-15T09:30:04Z。
6結論
最適な用途： 適した用途：中国語圏の技術チームにおいて「スクリプトの実行結果を WeCom グループへ確実に通知したい」ニーズ（バックアップ/同期/cron/サービス健全性の定型レポート、特に「内容が分かりにくい、漏れがあるか不明」と指摘されたことがある現場）。また、個人用の自己確認チャンネル（self）と外部グループ向け（others）を区別し、送信機が勝手に置き換えられないようにしたいチームにも適しています。
不向きな用途： 適さない用途：リッチメディアカード/画像/ファイルメッセージを必要とするシナリオ（プレーンテキストのみサポート）；複数チャネル（Slack/Lark/メール）の一元的な抽象化を求めるシナリオ（本スキルは WeCom のみに特化）；設定を永続化せず単発でメッセージを送信したいシナリオ（設定が必須の前提条件であり、欠落時はハード障害となります）；Webhook トークンを高セキュリティ管理の外部金庫等で一元管理しているチーム（ローカルの 0600 ファイルに配置する必要があります）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload setup-notifications-via-wecom.tar.gz
sha256:
Option B · Copy Guide for Agent75c3e6008604ce81…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.