小鹅通商家企微机器人操作 Skill
目标与边界
让商家在企业微信群里 @机器人，由 WorkBuddy 通过当前授权的小鹅通店铺连接器查询或操作店铺。
本 Skill 只覆盖：
- 企微智能机器人创建与 WorkBuddy 绑定；
- 当前小鹅通店铺的查询；
- 直播创建、讲师挂载、回读校验与链接交付。
不把任何 Bot ID、Secret、Webhook、Token、EncodingAESKey、app_id 或店铺凭证写入 Skill。这些属于每个商家自己的配置，必须由商家在对应平台完成授权。
第一原则：先判断用户要的是哪种机器人
先问一句并按目标分流：
| 用户想要的结果 | 正确选择 | 不能选什么 |
|---|---|---|
| 群里只能由系统向群发送订单/告警通知 | 群机器人 Webhook | 它不能接收消息，不能响应 @机器人 |
群里 @机器人 后查询小鹅通并回复 |
智能机器人 → API 模式 → 使用长连接 | 群机器人 Webhook、智能机器人普通模式 |
| 已有公网服务并自行维护回调、验签、加解密 | 智能机器人 → API 模式 → URL 回调 | 不要同时配置长连接 |
| 不接 WorkBuddy，只使用企业微信内置 AI 能力 | 智能机器人普通模式 | 不要误以为它会调用当前小鹅通连接器 |
最容易选错的三个入口
- 群机器人 Webhook：地址通常是
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...。这是单向发送接口，不会把群消息推给 WorkBuddy，无法实现@机器人 → 查询/建播。 - 智能机器人普通模式：能在企微里对话，但不是 API 接入，不会把消息交给 WorkBuddy，也不会自动使用小鹅通连接器。
- 智能机器人 API 模式中的 URL 回调：只有在商家有公网可访问服务、愿意自己维护回调协议时才选。个人电脑或普通 WorkBuddy 使用场景应选长连接。
企微创建流程：按顺序操作
0. 先确认商家具备这些前置条件
- 已安装并能打开 WorkBuddy，且当前账号允许使用企微助理集成；
- 已在 WorkBuddy 连接器面板登录并授权自己的小鹅通账号/店铺；
- 准备使用企业微信内部群（外部群、互联群、上下游群不作为首选测试环境）；
- 由这个智能机器人的创建者完成创建和首次绑定；企业管理员身份不自动等于该机器人的创建者；
- 明白“安装 Skill”不等于“完成授权”：每个商家都必须用自己的企微机器人和自己的小鹅通连接器。
A. 正确创建
- 企业微信客户端：工作台 → 智能机器人 → 创建机器人 → 手动创建。
- 选择 API 模式创建，不是普通模式。
- 填机器人名称、可使用成员/可见范围；确认由该机器人创建者操作后续绑定；先保存。
- API 配置中选择 使用长连接。
- 复制 Bot ID，点击“点击获取”复制 Secret。
- 长连接模式只需要 Bot ID + Secret；不要填写 URL、Token、Encoding-AESKey。
- Secret 只通过安全输入框传给 WorkBuddy，不能发群、截图或粘贴到公共文档。
B. WorkBuddy 绑定
设置 → 助理设置 → 集成（BETA）→ 企微助理集成 → 配置 → WebSocket 长连接 → 填 Bot ID + Secret → 注册。
- 公有云通常留空自定义 WebSocket 地址。
- 只有企业微信私有化部署才填写管理员提供的
ws://或wss://地址。 - 同一个智能机器人同时只能有一个有效长连接；不要让另一台电脑或另一套服务同时连接同一 Bot。
C. 如果误选了 URL 回调
不要把 Webhook 地址、Bot Secret、Token、EncodingAESKey 混填。正确顺序是：
- 企微 API 配置选择“使用 URL 回调”；
- 在企微生成并保存 Token、EncodingAESKey；
- WorkBuddy 切换到 URL 回调，填入这两个值并注册；
- 复制 WorkBuddy 生成的 Webhook URL；
- 把该 URL 回填企微页面并保存。
无公网服务时不要走这条路线，回到“使用长连接”。API 长连接与 URL 回调互斥，切换会使另一种方式失效。
企微创建防错检查表
绑定前必须逐项确认：
- [ ] 入口是“智能机器人”，不是“群机器人”；
- [ ] 选择了“手动创建”；
- [ ] 选择了“API 模式创建”；
- [ ] API 配置选择“使用长连接”；
- [ ] 使用的是这个机器人自己的 Bot ID + Secret；
- [ ] 创建者是这个机器人的创建者，不是只拥有企业管理员/企业创建人身份；
- [ ] 可使用成员包含实际要发消息的商家成员；
- [ ] 没有开启会把机器人限制为“仅创建者可用”的个人授权；
- [ ] 没有把 Secret 写进 Skill、群消息、截图或日志；
- [ ] WorkBuddy 显示已注册/已连接。
“当前账号非机器人所属企业，暂无法授权，仅限机器人创建者”通常表示当前账号不是该具体机器人的创建者。不要反复授权旧机器人；由正确创建者创建新机器人或让该机器人创建者完成绑定。
绑定后验证：四层证据链
不要只看到“注册成功”就交付。按以下顺序验证：
推荐的最小真实测试话术：
@机器人 查询当前小鹅通店铺信息
@机器人 列出店铺最近 5 场直播
第一句验证连接器和店铺身份，第二句验证业务工具路由。若只回复“收到”但没有返回店铺数据，不能判定小鹅通链路已通。
- 配置层：WorkBuddy 的企微渠道已启用，模式为 WebSocket，Bot ID 非空。
- 认证层：日志出现
Connected successfully和Authenticated successfully。 - 消息层：在企业内部群里发送
@机器人 你好，确认收到入站消息并完成回复；群里必须 @ 才触发。 - 业务层：发送
@机器人 查询当前小鹅通店铺信息，机器人必须调用小鹅通连接器并返回当前店铺，而不是返回金融工作台或编造数据。
若要进一步验证网络，检查长连接仍处于 ESTABLISHED；不要用 curl 访问 WebSocket 地址的 HTTP 404 作为失败依据。
第二原则：所有数据必须走当前小鹅通店铺连接器
连接前置检查
- 确认 WorkBuddy 的小鹅通连接器已连接；若未登录/过期，让商家在连接器面板重新连接。
- 先调用当前店铺信息工具，确认授权店铺名称和店铺 ID；店铺身份来自当前会话，不让用户手填
app_id。 - 只使用当前会话实际提供的工具和 schema；先搜索相关工具，不能凭记忆拼工具名或字段。
- 查询时按店铺当前授权范围执行；不能把一个店铺的 ID 静默用于另一个店铺。
查询路由示例
- 店铺信息：当前店铺信息工具；
- 课程/图文/音视频/电子书：课程资源列表，再按需查详情；“书籍”在小鹅通通常对应电子书资源；
- 订单：先按时间、状态缩小订单列表，再查订单详情；
- 直播：直播列表，再查指定直播详情；
- 直播讲师：先查讲师/候选列表；同名时用 user_id 和历史直播记录消歧。
查询工具可以直接执行，但仍须把店铺名称和数据口径说清楚。
第三原则：直播创建必须防止误建
直播创建是写操作、不可逆；连接器没有删除直播能力。下架、停售或隐藏不等于删除，真正删除要去小鹅通后台。
创建前收集的信息
至少确认：
- 名称；
- 开始时间（把“今天中午/明天9点”换成绝对日期时间）；
- 时长，并计算结束时间；
- 售卖方式；付费必须有价格，加密必须有密码；
- 讲师；同名讲师不得猜，必须用 user_id 或让用户选择。
标题按更严格的 45 字以内控制。连接器的 zb_stop_at 是结束时间字符串，不要把官方接口的“秒数”直接照搬。
售卖方式映射
| 用户说法 | 连接器参数 | 备注 |
|---|---|---|
| 免费 | payment_type=1 |
无价格、无密码 |
| 付费 | payment_type=2 + piece_price |
价格单位是分；199 元传 19900 |
| 加密 | payment_type=3 + resource_password |
密码长度以当前 schema 为准；创建后回读密码状态 |
| 指定用户 | payment_type=4 |
类型可设，但名单通常需到后台添加 |
| 课程关联 | 需要 sale_type/relation_info |
若当前连接器未暴露，必须说明只能后台设置，不要硬凑字段 |
严格确认协议
- 先读取
live_create当前 schema；只传 schema 中存在的字段。 - 先做不带确认标志的预检，让系统返回
confirmation_required；这一步不得视为创建成功。 - 把店铺、名称、开始/结束时间、时长、售卖方式、价格/密码状态、讲师、直播类型、上下架状态完整展示。
- 只有用户明确确认后，才带确认标志执行；参数必须与确认摘要逐字段一致。用户修改任何字段，重新确认。
- 创建成功后再用正确的讲师批量添加工具挂讲师；不要把讲师字段硬塞进创建参数，也不要用“编辑讲师”替代“批量添加”。
- 失败、超时或连接中断时，先查询直播列表/详情确认是否已落库，禁止盲目重试。
创建后强制回读
必须核对：
- 直播 ID、名称、开始时间、结束时间；
payment_type、价格、密码状态；alive_type、横竖屏、是否公开、是否上架、是否停售、是否回放；teacher_list中目标讲师的 user_id、姓名和角色；- 观看链接/页面链接；如需管理入口，另查页面链接。
写接口返回成功但回读不一致，不算完成。
能力边界：必须如实说明
- 连接器不能删除直播；
- 连接器不能保证指定学员名单已写入，需后台补充；
- 连接器未暴露课程关联字段时，不能完成关联售卖；
- 连接器通常拿不到第三方 OBS 推流地址；不能把观看/拉流地址冒充推流地址；
- 企微群机器人必须在企业内部群使用，外部群/互联群可能不支持；
- 机器人没有消息入站就不能凭空向任意群主动发送，除非当前平台明确支持并已授权。
故障处理顺序
- 企微注册失败：先核对机器人类型、API 模式、连接方式、Bot ID/Secret 是否来自同一机器人，再检查 Secret 是否已刷新失效；
- “非机器人所属企业”：核对具体创建者，不要只看企业创建人身份；
- 群里无回复：先确认确实 @ 了机器人，再查可见范围、个人授权限制、是否误用 Webhook/普通模式；
- 小鹅工具为空：重新连接器并重新获取当前会话工具，不自动重放旧调用；
unknown field：重新读取 schema，删除自造字段；confirmation_required：这是正常的写操作保护，不是报错；展示摘要并等待明确确认；- 直播创建后讲师为空：通常是正常的分两步流程，先查详情，再调用批量添加讲师；不要重复创建。
给商家的推荐用法
安装或导入本 Skill 后，商家可以在群里这样说：
@机器人 查询当前小鹅通店铺信息
@机器人 查询本周订单和退款
@机器人 列出店铺电子书
@机器人 创建一场直播：今天 19:30，时长 60 分钟，名称“新品公开课”，免费，讲师“张老师”
对于最后一种写操作，机器人必须先列出完整参数并等待确认；商家不要把 Secret、Token、密码或店铺访问凭证发到群里。
交付标准
一次合格交付必须包含：
- 企微机器人类型和连接方式；
- 当前小鹅通店铺名称；
- 查询或写入的具体结果；
- 直播写操作的确认与回读证据；
- 观看链接与开播方式（若适用）；
- 未完成项、平台限制和用户下一步操作；
- 不输出任何 Secret、Token、密码或临时凭证。
详细决策表和验收清单见 references/merchant-checklist.md。
