Skip to content

Commit fa38bec

Browse files
bot-talk-kclaude
andcommitted
docs: README 新增"通道稳定性"小节,突出人性化互动设计
- 对比表加"通道自愈"行,与 Server 酱对比更有记忆点 - 原 💡 Tip 改为指向新小节,不再只说"重新扫码" - 新 "🛡️ 通道稳定性" 小节以"一字换一执"的人性化交互为叙事骨架: · 先诚实承认这是腾讯 ClawBot 协议层缺陷 · 再讲核心设计洞察:把被迫保活变成双向可感知对话 · 列出 7 层脚手架(ack / 补发 / retry-queue / neg2-probe / 限流 / poller supervisor / 预防性提醒)每项对应代码 · 诚实边界:"数天一次重扫"而非"永不失联" · 链到 docs/ilink-pitfalls.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8d31e87 commit fa38bec

1 file changed

Lines changed: 30 additions & 1 deletion

File tree

README.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,35 @@ Push notifications to your WeChat — free, open-source, self-hostable.
3030
| **SDK** | Python / Node.js / Go | 官方仅 API |
3131
| **数据隐私** | 自部署,数据完全自控 | 第三方存储 |
3232
| **API 兼容** | 兼容 Server酱格式 ||
33+
| **通道自愈** | 限流 + 重试 + 补发 + 探测,7 层机制 | 断了要自己手动重试 |
34+
35+
## 🛡️ 通道稳定性:用一次一字的互动替代复杂保活
36+
37+
**坦白告知**:BotTalk 底层依赖的 [微信 ClawBot](https://ilinkai.weixin.qq.com) 是腾讯仍在内测灰度阶段的协议,存在一个我们无法绕开的限制——**通道如果长时间没有用户互动,会被微信平台静默断开**。这是协议层缺陷,不是 BotTalk 的 bug,也不是任何同类方案能从根本解决的。
38+
39+
我们的做法不是硬扛协议缺陷,而是**通过人性化的互动设计巧妙避开它**
40+
41+
> 用户收到推送后顺手回一字("好" "在" "1")→ 系统**秒回** ✅ "收到,通道状态已刷新" → ClawBot 的 context_token 同步刷新 → 期间失败的消息立即自动补发,带原始时间戳。
42+
43+
这一来一回的"一字换一执",本来只是为了绕过腾讯的保活限制,实际把**被迫的保活动作变成了双向可感知的对话**:用户一眼知道通道活着,有掌控感;通道顺带就刷新了。大多数社区方案(包括腾讯官方 [openclaw-weixin](https://github.com/Tencent/openclaw-weixin) SDK)在这个问题上止步于"能发能收"——掉线让用户自己去猜、去重扫。
44+
45+
### 支撑这个互动闭环的 7 层脚手架
46+
47+
| 机制 | 作用 | 用户感受 |
48+
|------|------|----------|
49+
| ✉️ **用户回复秒回执** | 收到用户任意消息整批统一回一条 ✅ 确认 | 一字就能确认通道死活,告别沉默焦虑 |
50+
|**回复触发补发** | 用户回字即刻唤醒 pending 重试并真正发出,带原始推送时间前缀 | 沉默一整天回一字,漏掉的消息立刻到 |
51+
| 🔁 **延时重试队列**(持久化)| 失败消息按 2 / 5 / 15 / 60 分钟退避重试,完整 failure_history 留痕 | 瞬时抖动自动修复,无需用户介入 |
52+
| 🔍 **ret:-2 持续探测** | 重试用尽后每小时低频探测,最多 48 小时 | 通道自然恢复时自动补送历史消息 |
53+
| 🚦 **客户端限流队列** | 同通道最小 10s 发送间隔,防 burst 触发服务端限流 | 批量推送不再集体翻车 |
54+
| 💓 **Poller 心跳监控** | 每 2 分钟扫长轮询进程,挂死自动重启(epoch 机制防双 loop 并发)| 容器运行零人工干预 |
55+
| 📢 **预防性保活提醒** | 4h 无成功推 + 20h 无回复时主动提示用户回一字 | 通道接近沉睡前提前唤醒,降低重扫概率 |
56+
57+
**错误码分类处理**`ret:-14` 会二次 `getUpdates` 确认是真 session 死还是"半死态"(账号被微信风控),避免把可恢复通道误标失效。
58+
59+
**诚实边界**:这套机制无法让通道"永不失联"——协议缺陷在腾讯修复前没有银弹。但实测下来,**绝大多数抖动在用户无感知的情况下就被修复**,真正需要重扫的情况从"每天数次"降至"数天一次"。
60+
61+
完整协议踩坑分析和实现细节见 [iLink Pitfalls 指南](docs/ilink-pitfalls.md)
3362

3463
## 🚀 一分钟上手
3564

@@ -45,7 +74,7 @@ https://bot-talk.com/YOUR_SENDKEY.send?title=Hello
4574

4675
就这么简单。收到微信消息了吗?
4776

48-
> 💡 由于微信 ClawBot 当前策略是同一微信号只保持一个活跃通道,绑定新应用会自动失效之前的连接。如果发现消息未收到,只需重新扫码即可恢复,秒级完成
77+
> 💡 微信 ClawBot 是腾讯内测灰度协议,通道偶尔会被平台静默断开。BotTalk 后台有 **7 层自愈机制** 尽量让你无感——详见下方「[通道稳定性](#-通道稳定性用一次一字的互动替代复杂保活)」小节。如真的收不到消息,只需重新扫码即可秒级恢复(SendKey 和历史不变)
4978
5079
## 📡 API
5180

0 commit comments

Comments
 (0)