个人微信机器人接口：按稳定性分四级，哪些能长期依赖

选个人微信机器人接口，功能全不全不是第一判断标准，稳定性分级才是。核心原因是这些接口背后的协议依赖差别很大：消息收发走的是核心会话通道，而朋友圈、群设置这类接口受账号状态、登录时长、群角色三重影响，同一个平台上有的接口能跑一年，有的三天就失效。

把接口按稳定性分级，做两件事会立刻变简单：向业务方承诺功能时知道边界在哪，技术方案设计时知道哪些环节要准备降级。

接口来自 WTAPI——基于 iPad/Mac 协议的微信机器人接口服务，把消息、好友、群、朋友圈这些能力做成标准 HTTP API。说直白点：你的程序调用它给的网址，就能用这个微信号收消息/发消息/管群，扫码登录、掉线重连这些协议层的工作由它完成。

先给一个接口探针矩阵——把你要依赖的接口全部跑一遍，输出可用性报告。这比读文档可靠：

# 个人微信机器人接口: 稳定性探针矩阵 | 真实接口, 替换环境变量后可运行
# 文档站: weiti.apifox.cn   官网: www.chuapi.com
import os, requests, time

BASE = os.environ.get("WTAPI_BASE", "https://wx.chuapi.com")
TOKEN, APP_ID = os.environ["WTAPI_TOKEN"], os.environ["WTAPI_APPID"]
HDR = {"Content-Type": "application/json", "X-finder-TOKEN": TOKEN}

def probe(path: str, **params) -> tuple[bool, str]:
    """返回 (是否可用, 说明)。判定不只看 HTTP 状态码"""
    try:
        r = requests.post(f"{BASE}/finder/v2/api/{path}", headers=HDR,
                          json={"appId": APP_ID, **params}, timeout=15)
    except requests.RequestException as e:
        return False, f"网络异常 {e}"
    if r.status_code != 200:
        return False, f"HTTP {r.status_code}"
    d = r.json()
    if d.get("code") not in (None, 200):
        return False, f"code={d.get('code')} {d.get('msg', '')}"
    return True, "ok"

# 只读接口 + 自发自收, 全部零副作用
PROBES = [
    ("L1", "发送文本", "message/postText", {"toWxid": "filehelper",
                                          "content": f"probe {int(time.time())}"}),
    ("L1", "通讯录读取", "contacts/fetchContactsList", {}),
    ("L2", "标签列表", "label/list", {}),
]

report = []
for level, name, path, params in PROBES:
    ok, msg = probe(path, **params)
    report.append((level, name, "可用" if ok else "不可用", msg))
    time.sleep(1)                                  # 探针也限流, 别自己触发风控

print(f"{'级别':<4}{'接口':<12}{'状态':<8}说明")
for level, name, status, msg in report:
    print(f"{level:<6}{name:<14}{status:<10}{msg}")

这段只探测了三个接口，重点在判定逻辑：HTTP 200 不等于可用，还要看返回体里的 code。凡是发出去类接口，最终判定要看返回体里有没有代表成功的业务字段。

一、四级稳定性模型

按“依赖什么才能跑通”分四级，这是判断稳定性的核心依据：

级别	定义	依赖条件	可承诺程度
L1 核心	只要有有效登录态就能用	仅登录态	可长期依赖
L2 常规	需要实例数据完整	登录态 + 数据同步	可依赖，需异常兜底
L3 受限	受账号状态或时间窗口约束	登录态 + 账号条件	不可承诺，需降级方案
L4 不建议	高风险操作	触碰风控红线	不应纳入产品

依赖条件越少，稳定性越高。这个判断标准比“接口是否标注 deprecated”实用得多——因为大多数受限接口不会标注。

二、四级接口的典型清单

级别	典型接口	说明
L1	发文本/图片/文件、收消息回调	机器人产品的地基，几乎所有功能都建立在这上面
L1	拉取通讯录	只读，量大时注意处理耗时
L2	建群、邀请成员、群信息查询	依赖好友关系是否完整
L2	标签列表、标签成员读写	需注意全量覆盖语义
L3	朋友圈发布	新设备登录后有数天受限期
L3	群公告设置	仅群主/管理员可调
L3	群名/群备注修改	备注仅自己可见，易误判为失败
L4	抢红包、自动收款类	风控高度敏感，不建议做
L4	高频批量群发	单次量大极易触发限制

这张表最右两行值得单独说：L4 不是技术做不到，是做成了也活不久。这类功能上线后通常在一两周内出现账号受限，之后要么换号要么下线，投入的开发和运营成本全部沉没。

三、L3 受限接口的现实影响

L3 是选型时最容易误判的一级，因为它能调通但不一定生效。

以朋友圈为例：接口路径存在，参数正确，返回 200，但新登录的设备在数天内实际发不出去。表现是返回体里缺少成功标识。如果代码只看状态码，会以为发了一周的朋友圈，实际一条都没出去。

群公告是另一种 L3：接口一直可用，但你如果不是群主或管理员，调用就是失败。而且它是整体覆盖语义，写新公告会冲掉旧公告，写错没有撤销。

对待 L3 接口的正确态度是：做，但不承诺。产品上可以说“支持朋友圈发布”，但要配合状态检测与失败提示，不能当成核心卖点写进合同。

四、稳定性要持续验证，不能只测一次

接口稳定性会随账号状态变化。今天可用的朋友圈，明天这个号进入观察期就不可用了。所以探针不该只跑一次，应该定时跑：

频率	探测内容	用途
每分钟	发送接口（发给自己）	判断登录态是否存活
每小时	只读接口（通讯录、标签）	判断数据同步是否正常
每天	L3 接口	观察受限状态变化

第一行是最重要的：用发送接口做活体检测。个人号最常见的事故是静默掉线——进程还活着，登录态已经失效，机器人以为自己还在工作。定时发一条给自己的消息，失败就告警，这比任何日志监控都直接。

# 活体检测: 用发送接口判断登录态是否存活
def is_alive() -> bool:
    try:
        r = requests.post(f"{BASE}/finder/v2/api/message/postText",
            headers=HDR,
            json={"appId": APP_ID, "toWxid": "filehelper",
                  "content": f"alive {int(time.time())}"},
            timeout=10)
        return r.status_code == 200 and r.json().get("code") in (None, 200)
    except Exception:
        return False

# 定时任务里: 连续 2 次失败则告警, 避免网络抖动误报
fail_count = 0
while True:
    if is_alive():
        fail_count = 0
    else:
        fail_count += 1
        if fail_count >= 2:
            print("[告警] 登录态可能已失效, 需重新登录")
    time.sleep(60)

连续两次失败才告警，是为了过滤网络抖动。单次失败很常见，连续失败基本就是登录态问题。

五、按分级做功能承诺

把分级结论翻译成产品语言：

功能	依赖级别	建议的对外表述
自动回复	L1	可承诺稳定可用
群管理与成员操作	L2	可承诺，注明需群角色满足条件
朋友圈运营	L3	说明受账号状态影响，不承诺时效
群公告推送	L3	说明需群主/管理员权限
批量群发	视量而定	明确限流策略，不做无限量承诺

这张表的用处是：销售和产品不用再问技术“这个能不能做”，直接查表即可。同时它也避免了一个常见问题——把 L3 能力当成核心卖点签进合同，上线后被账号状态卡住。

六、接口分级自检清单

1. 计划使用的接口是否都跑过探针，结论是否记录
2. 是否区分了“HTTP 200”与“业务成功”
3. L3 接口是否有降级方案或失败提示
4. L4 能力是否已从需求列表中剔除
5. 是否有定时活体检测，是否配置了告警
6. 探针是否也做了限流，避免自己触发风控
7. 对外承诺的功能，是否都标注了依赖级别