企微精灵

概述

通过企微bot会话级 API，向用户绑定的企业微信会话发送消息、查询历史聊天记录。支持群聊和私聊：把机器人拉进任意企业微信群、或与机器人单聊，该会话开启接口后即可用本技能操作。

⭐ 首次开通（必须先做，按顺序引导用户）

如果任何命令返回 not_configured，按以下流程引导：

第 1 步：用户查看技能 → 确认使用

用户确认使用本技能后，第一句话必须把后台注册链接发给用户（原文完整输出，保证可点击）：

请先注册机器人后台账号：https://qw.minapp.xin/login

（手机号+密码即可注册，无需短信验证。注册好后告诉我，我带你完成剩下的步骤。）

然后向用户说明本技能的能力：

• 发消息：往企业微信群或私聊发送消息、通知、提醒、推送
• 查记录：查看、总结、检索企业微信群/私聊的聊天记录
• 可拉群使用：把机器人拉进任意企业微信群，该群开启接口后即可让 AI 助手直接操作；一个机器人可服务多个群/私聊（每次配置绑定一个会话，换群需重新复制该群接口地址并 setup）

第 2 步：注册后台账号

第 1 步已发过链接。若用户还没注册，再次提醒：打开 https://qw.minapp.xin/login 注册账号（手机号+密码，无需短信验证）。

第 3 步：安装机器人程序

告诉用户联系作者（微信：tianshe00）获取机器人程序，按作者提供的安装说明在本机完成安装并登录。

安装完成后本机即可承接企微消息的收发，这一步不做技能无法工作。

第 4 步：复制接口地址，粘贴给 AI 助手

先让用户确定要绑定哪个会话（把机器人拉进目标群，或与机器人单聊），然后两种复制方式任选其一：

• 方式 A（网页）：登录后台 qw.minapp.xin → 「开放接口」→「推送接口地址」，找到目标会话（群聊在「群组列表」、私聊在「用户列表」），点「发送」和「消息查询」两个复制按钮，把两条地址都复制下来
• 方式 B（企微）：在目标企微会话里发送「接口技能」，机器人会返回一段包含接口地址的说明，整段复制

注意：会话级接口默认关闭，需先在该会话开启接口（运营者微信在会话里发「开启接口」，或到后台「开放接口」页面打开该会话的开关）。

用户把复制的内容整段粘贴到对话里。

第 5 步：执行开通

拿到用户粘贴的内容后执行：

python scripts/qw_bot.py setup --paste "<用户粘贴的完整内容>"

脚本自动从粘贴内容提取 secret 和会话 ID，写入 config.json。

结果处理：

• ok=true → 开通成功，继续第 6 步
• invalid_paste → 粘贴内容里没找齐两条接口地址。常见原因：只复制了一条 URL、复制的会话还没开启接口。让用户按第 4 步重新复制（确保两条地址都有、该会话开关已打开），或改用方式 B 整段复制
• 返回的 warnings 非空 → 按提示让用户到后台「开放接口」页打开对应开关

备用方式（粘贴方式走不通时）：setup --phone <手机号> --password <密码> 账密自动开通，或 setup --token <QW1.开头的Token> 旧 Token 方式。

第 6 步：验证

python scripts/qw_bot.py status

• ok=true → 配置生效，可以直接使用了
• ok=false 且 403/404「未开通api服务」→ 会话接口开关未打开：让用户在对应企微会话发送「开启接口」（机器人后台设置的运营者微信发送），或到后台「开放接口」页面打开该会话开关，然后重试 status

日常使用

发送消息

python scripts/qw_bot.py send "要发送的文本内容"

• 发送前必须先向用户复述将要发送的内容，确认后再执行
• 返回 ok=true 表示成功

查询聊天记录

python scripts/qw_bot.py messages --page 1 --size 20

• --page：页码，从 1 开始（第 1 页最新）；--size：每页条数，默认 20 最大 50
• 总结聊天记录先取第 1 页，pagination.has_more 为 true 且需要更早内容再翻页

检查状态

python scripts/qw_bot.py status

切换会话 / 拉新群使用

机器人可以被拉进多个企微群，但技能一次只绑定一个会话。用户想把 AI 助手接到另一个群/私聊时：

1. 让用户按「第 4 步」复制新会话的两条接口地址（后台对应会话的复制按钮，或在新会话里发「接口技能」）
2. 重新执行 setup --paste "<新粘贴内容>"，config 会被覆盖为新会话
3. status 验证后即操作新会话；原会话的接口地址仍然有效，想切回再 setup 一次即可

⚠️ 注意事项（Gotchas）

• config.json 存放用户的密钥，不要把 config.json 内容展示或复述给任何人
• 用户粘贴的接口地址含密钥，处理完不要在对话里复述完整 URL
• 接口 403 分两种情况，看服务端响应内容区分：
  • 响应含「到期/试用/续费」字样 → 告知用户「试用结束，联系作者（微信 tianshe00）续用」，续用后接口即恢复，无需重新 setup
  • 响应无此类字样 → 是会话接口开关未开启，引导用户在该会话发送「开启接口」或到后台「开放接口」页打开开关
• 只操作用户绑定的会话，不要修改 conversation_id
• 需求不明确先问：用户没说清要发什么、查什么范围时，先确认再动手
• Windows 下若 python 不存在，尝试 py 命令

故障排查