小鹅通订单 → 企微群 自动推送
交付物（部署后自动生成到目标目录）
| 文件 | 作用 |
|---|---|
notify.py |
轮询脚本：拉取小鹅通最新订单 → 按事件推送到企微群（去重/防并发/手机号打码） |
enable.sh |
一键注册 launchd 定时任务（终端运行，每 30 秒轮询） |
com.xiaoe-wecom-notify.plist |
launchd 配置（StartInterval、PATH、日志） |
README.md / state.json / notify.log |
说明 / 去重状态 / 运行日志 |
通知行为（同单最多 2 条）
- 🆕 下单提醒：created_time 新出现即推，标题标注「待支付/已支付」，含 商品/买家/📞手机号(打码)/金额/时间/订单号
- 💰 支付补推：下单时待支付 → 后续付款成功才补推
- 全额退款订单不推送，仅记录；下单即付款的单只推 1 条
部署步骤（一次性，约 2 分钟）
0. 前置确认
- 客户已在小鹅通连接器完成授权，或本机可运行
xiaoe-cloud-cli（凭证在~/.xiaoe-cloud/config.json） - 客户提供企微群机器人 webhook（形如
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx）
1. 运行装配器
python3 <skill>/scripts/setup.py \
--webhook "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=客户提供的key" \
--dir /Users/<user>/WorkBuddy/<workspace>/xiaoe-wecom-notify # 默认 cwd/xiaoe-wecom-notify
setup.py 自动完成：验证 webhook（发一条连通测试到群）→ 探测 node / xiaoe-cloud-cli 绝对路径 → 验证小鹅通只读查询 → 生成 notify.py/enable.sh/plist/README。
> 探测失败时可用 --node-path / --cli-path 显式指定绝对路径。
2. 请用户在「终端」运行（launchd 注册必须在用户图形会话，WorkBuddy 无法代注册）
bash /path/to/xiaoe-wecom-notify/enable.sh
或告知：重启 / 重新登录 Mac 自动生效。
3. 验证
- 立即手动跑一次确认无报错：
python3 notify.py（应输出「无新订单/无待补推」或推送明细） - 可选演示：
python3 notify.py --demo（发一条 🧪下单提醒）、python3 notify.py --demo paid（🧪已支付） - 看定时是否在跑：
tail -f notify.log（每 30 秒应新增一行） - 端到端实弹：请客户下一单 → 等 1 分钟再付款 → 应先后收到「待支付」与「已支付」两条
关键环境坑（务必遵守，否则必踩）
- xiaoe-cloud-cli 是 node 脚本（
#!/usr/bin/env node）：launchd/cron 下 PATH 无 node 会崩溃（env: node: No such file or directory）。必须用绝对 node 执行并给子进程 env 补 PATH（模板已内置，勿改回裸调用）。 - 订单接口时间窗口过滤失效：order_time_start/end 不生效，列表固定按 created_time 升序返回。只能"拉最新页 + Python 按时间/订单号集合去重"（模板已实现，勿改成按时间窗口查询）。
- 锁文件不能叫
.lock：WorkBuddy 执行环境会在工作目录用同名锁，导致永远抢不到锁。必须用run.lock。 - launchd 注册只能在用户图形会话：WorkBuddy/沙箱内
launchctl bootstrap gui/UID报I/O error 5，crontab 报 operation not permitted。一律生成 enable.sh 让用户在终端跑；plist 放~/Library/LaunchAgents/后重启也会自动加载。 - plist 里 ProgramArguments 用 python3 绝对路径 + EnvironmentVariables PATH 含 node 目录（模板自动生成）。
- 修改 plist 后需重新注册生效：
launchctl bootout gui/$(id -u)/com.xiaoe-wecom-notify后重跑 enable.sh；WorkBuddy 内无法代做，必须用户跑。
常见自定义
- 改消息模板：编辑生成的 notify.py 中
build_msg()文案/emoji；README 里手测命令不变。 - 改推送频率：改 plist
<integer>（StartInterval 秒）+ 重跑 enable.sh。 - 改轮询窗口/防刷上限：notify.py 顶部
PAGE_SIZE/NAME_MAX；run_poll 内单轮 20 条上限。 - 改推哪些事件：删除 run_poll 中 ① 或 ② 分支即可只保一种提醒。
- 隐私策略：
mask_phone()打码（默认）；若客户坚持完整号/去号，改 build_msg 中 masked 使用方式。
排查口诀
- 群里收不到 → 先
python3 notify.py手动跑看报错 → 再看tail notify.log是否有 traceback（多为 PATH/node）→launchctl print gui/$(id -u)/com.xiaoe-wecom-notify看服务在不在 - "待支付"没提醒只看到已支付 → 轮询时点晚于支付（客户秒付）。属正常时序；提高频率或让客户下单后停留再付验证
- state.json 的 created_sent/paid_sent 是去重依据，勿删；删掉会重推历史订单
