AI 助手主动消息落地实录：投递、心跳、状态机与防重复提问

AI 助手主动消息落地实录：投递、心跳、状态机与防重复提问

本文为脱敏示例。文中出现的主机、路径、账号、渠道标识与配置项均为通用描述或占位符，不代表任何具体部署环境；示例代码只保留最小可运行片段。

一、目标：不是"定时播报"，而是"有事才说"

把个人助手接进聊天工具之后，很快会遇到一个体验问题：它只在被叫到时才说话。

按时推送早报是一种常见解法，但那是"闹钟"——到点必发，内容模板化。真正想做的是让助手像人一样：有值得说的事就说，没有就不打扰。

这两件事在工程上是完全不同的路径：

这篇文章记录一次完整落地的过程，重点放在遇到的具体问题和解决方式，而不是某个框架的用法说明。

二、投递层：主动发消息为什么比回复难

2.1 问题一：回复有上下文，主动发送没有

回复消息时，平台会告诉程序"谁发来的、回给谁"。主动发送没有这个上下文，必须显式指定收件人；而不同平台的收件人标识并不通用——有的用用户维度 ID，有的用会话维度 ID。

2.2 问题二：用户维度接口对主动发送有限制

实测中最典型的一个失败是这样的：

平台返回：230101 Sending messages to users is temporarily unavailable

排查思路：

这类差异往往跟客户端版本有关，文档不一定写清楚，只能靠实测确定。

2.3 问题三：命令型投递把 stdout/stderr 一起发出去了

为了先单独验证投递层（不引入模型变量），我们用"执行一条命令并把输出投递出去"的方式测试。结果用户收到的消息长这样：

stdout:
probe-ok

stderr:
sh: 35: [: not found

两个问题：

• 投递层会把标准输出和标准错误分开标注后一起发出，对用户来说非常工程化；
• 命令本身有语法错误，产生了一行噪声，也被原样投递。

解决方式：

• 验证阶段允许这种噪声，但要记得它是包装层造成的，不是投递本身有问题；
• 正式使用改为参数数组形式调用脚本，或者让脚本只向标准输出写正文、把诊断信息写日志文件；
• 助手生成的（走模型那一侧）消息是干净的，所以"验证投递"和"验证内容"要分开测。

2.4 问题四：怎么证明是"主动发送"而不是"回复"

很关键但容易被忽略的一点：如果只看到"用户收到了消息"，无法区分它是主动发送成功，还是刚刚回复了一条入站消息。

验收要同时核对三件事：

第三项才是"主动"的证据。命令大致如下：

# 通用形态：建一个一次性任务，稍后只投递一条固定内容
scheduler add \\
–at "<now+3min>" \\
–command "printf 'probe-ok'" \\
–announce –channel "<channel>" –to "<conversation-id>" \\
–delete-after-run

小细节：创建任务时想加"精确时间"或"输出 JSON"之类的参数，不同实现支持程度不一样，遇到不认识的参数先看帮助文本再判断，不要凭经验硬套。

三、心跳：从"没配"到"真的在跑"

3.1 问题五：以为没开，其实一直在空转

启用之前先做基线检查，结果发现一件反直觉的事：

• 配置里没有任何心跳相关字段；
• 但会话记录里每 30 分钟就有一条系统注入的"轮次提示"。

也就是说，心跳一直在跑，只是它的投递目标默认是"无"：模型照常思考、照常回复静默标记，但结果不发给任何人。

结论："用户收不到主动消息"不一定是故障，可能只是投递目标没打开。排查顺序应该是：先确认机制是否在运行，再确认结果是否被投递。

3.2 问题六：静默标记必须在投递前被剥离

心跳的静默约定是：没事时回复一个固定标记（例如 IDLE_MARK），系统识别到就把整条消息丢掉。最小判断逻辑：

SILENT_MARK = "IDLE_MARK"

def should_deliver(reply_text: str, max_ack_chars: int = 300) -> bool:
"""True 表示需要投递给用户。"""
text = (reply_text or "").strip()
if not text:
return False
# 只有"标记 + 少量残留"才当作没事；残留过长说明模型确实说了内容
if text.startswith(SILENT_MARK) and len(text) <= max_ack_chars:
return False
return True

坑在于：这段判断在真实实现里分散在很多环节——回复归一化、运行时收尾、轮次结束、会话记录过滤、任务策略……任何一处漏掉，静默标记都会作为一条消息发到用户手机上。这类机制最常见的线上事故就是这么来的。

两个对策：

• 阈值要显式配置（残留超过 N 个字符就不视为"没事"），不要依赖默认值；
• 上线顺序必须是先验证"没事时真的不发"，再验证"有事时能发"。反过来的话，异常现象会混在一起，很难定位。

3.3 配置怎么写才可靠

心跳的配置项不多，但每个都影响行为。实际使用的一组（脱敏后）：

{
"heartbeat": {
"every": "30m", // 轮次周期
"target": "last", // 投给最近活跃的渠道；默认通常是"不投递"
"activeHours": { "start": "08:00", "end": "23:30", "timezone": "Asia/Shanghai" },
"ackMaxChars": 300, // 静默标记的残留阈值
"lightContext": false, // 需要读状态文件，不能只带最小上下文
"isolatedSession": false, // 要保留对话上下文才"像人"
"skipWhenBusy": true, // 有任务在跑时让路
"timeoutSeconds": 120,
"prompt": "读取行为规则文件并严格执行；没有具体理由就回复静默标记。"
}
}

配置流程本身也有讲究：

3.4 问题七：重启期间 CLI 连不上

重启后立刻执行命令，遇到的是：

TLS mismatch (connecting with ws:// to a wss:// gateway, or vice versa)
Gateway process stopped or became unreachable

原因不是配置坏了，而是重启窗口里 CLI 连不上服务端。解决方式很简单：重启后先做一次连通性检查（能看到"网关可达"和渠道状态），再继续后续操作；不要拿重启中途的失败结果当配置问题去排查。

四、行为规则：把"像人"写成可执行的文件

心跳轮次能看到完整对话，但"该不该说"是模型每次的判断。要让判断稳定，得给一份可执行的规则文件，而不是一句"请自然地提醒用户"。

五道门，顺序固定，任一道不通过就停止：

# 主动接触纪律（模板）

只在「有依据 + 此刻有意义 + 不打扰」三条同时成立时才开口。

1. 依据门：只能引用真实存在的数据；推断必须标注。
2. 空闲门：距用户最近一次发言小于 2 小时 → 静默。
3. 频率门：每天最多 N 条；同一件事每天最多一次。
4. 打扰门：23:30—08:00 静默（紧急故障除外，且一句话说完）。
5. 内容门：不追问用户为什么不回；不出现路径、日志、行号、凭据。

按优先级挑第一件成立的：系统异常 > 到期任务 > 当天情况变化 > 有依据的建议 > 其余不发。

措辞：一句话为主，最多两段；不用标题、序号，不用「提醒」「播报」这类框架词。
没有可说的，只回静默标记。

还有一条容易忽略的经验：人设要单独成文件，并在所有渠道共用。否则同一个助手在网页里克制专业、在聊天工具里像换了个人。这种不一致几乎总是来自"每个渠道各写一份提示词"，而不是模型本身的问题。

正确分层是：

五、状态文件与探针：为什么"多久没说话"必须自己记

5.1 问题八：机制里没有"距上次用户发言多久"

心跳轮次有完整上下文，但通常没有现成的空闲时长字段。没有它，"空闲门"只能靠模型猜，稳定性很差。

解法：在对话之外维护一个小状态文件，由独立探针定期更新，轮次开始前先读：

{
"lastUserMessageAt": "2026-01-01T10:00:00+08:00",
"lastUserMessageAgeMinutes": 134,
"proactiveCountToday": 0,
"pendingQuestion": null,
"unansweredQuestions": []
}

5.2 问题九：把会话文件修改时间当"用户活跃"是错的

第一版探针图省事，用会话文件的 mtime 当作"用户刚说过话"的信号。结果完全失效：心跳轮次本身也在往同一个会话里写，每次轮次都刷新 mtime，于是系统永远认为"用户刚刚活跃"。

改成读取会话记录里的真实用户消息才好使，但紧接着遇到下一个坑。

5.3 问题十：系统注入的轮次提示会被当成用户消息

心跳是往会话里注入一条消息来驱动的，这条消息的角色也是 user。如果不过滤，探针会把"每 30 分钟的轮次提示"当成"用户又说了一句"，空闲判断照样失真。

过滤条件要写清楚：

SKIP_MARKS = ("heartbeat poll", "[Tool")

def latest_real_user_message(lines):
"""从后往前找最近一条真实用户发言的时间戳。"""
for line in reversed(lines):
msg = line.get("message")
if not isinstance(msg, dict) or msg.get("role") != "user":
continue
text = (msg.get("content") or "").strip()
if not text:
continue
# 1) 系统注入的轮次提示带固定标记
if any(m in text for m in SKIP_MARKS):
continue
# 2) 工具回执也是 user 角色
# 3) 超长内容基本是系统提示词，不是用户打的字
if len(text) > 1500:
continue
return msg.get("timestamp")
return None

配套三条经验：

• 探针不调用模型，只读写文件和查任务回执，成本几乎为零；
• 探针必须能独立、反复运行，这样状态迁移可以写用例断言，而不是靠观察；
• 状态文件建议只有一个写入者（探针），不要让模型也直接改，否则并发写会损坏状态。

六、主动提问：怎样不变成重复打扰

如果主动消息只有"报告事项"，大部分时间其实无话可说。自然的扩展是：没事时向用户提一个问题，慢慢了解他的偏好。

6.1 问题十一：用户不回答怎么办

最差的做法是每轮重新问一遍，或者把问题永远挂着等回答。都会变成骚扰。

把提问也做成状态机：

两条硬约束：

• 同一问题方向最多出现两次；
• 维护"已放弃方向"列表作为去重依据，新问题先比对，命中相似方向直接跳过。

迁移逻辑很小，可以直接用隔离用例断言：

def next_state(age_hours, attempts, answered):
if answered:
return "answered"
if age_hours > 48 or (attempts >= 2 and age_hours > 24):
return "unanswered" # 放弃该方向，换新的
if age_hours > 24:
return "stale" # 该换一种问法了
return "open" # 静默等待

age=3h attempts=1 → open
age=30h attempts=1 → stale
age=60h attempts=1 → unanswered
age=30h attempts=2 → unanswered
age=10h attempts=2 → open
answered=True → answered

6.2 为什么状态机要放在探针里

这是整个设计里最重要的一个决定：模型只需要按状态表行动，不需要"记住"自己问过什么（它本来也记不准）。状态由探针推进，即使某一轮模型没有照做，状态也不会停在原地，同一个问题不会反复出现。

6.3 提问本身的纪律

• 一次只问一个，能让用户一两句答完；不列选项清单，不像问卷；
• 开头一句说明为什么问，再问；
• 不问敏感面（凭据、住址、关系、财务细节）；
• 已有答案的不重复问；
• 用户不回答不代表可以催——不重述上次的问题。

七、回答落库：别让问答停在聊天里

主动提问如果聊完就没了，谈不上"更了解用户"。回答要按类型落到不同位置：

三条纪律：

• 标注来源与日期；不确定的标为推断，不把随口一句写成长期事实；
• 从"待确认问题"列表里移除已回答条目，避免下次当新问题再问；
• 敏感内容不进提问范围，也不因为"能问"就扩大记录范围。

八、问题排查与工程卫生小结

上面十一个问题里，有一半跟功能无关，而是远程操作和脚本层面的。集中记一下，省得重复踩：

还有两条"顺序"经验：

• 先建基线：改动前记录配置文件哈希、任务列表快照、当前时间戳，出问题能回退；
• 可逆优先：所有测试任务都带"运行后自删"，配置改动保留备份文件，重启类操作先确认回滚方式。

九、完成层级：怎么描述才不算夸大

落地状态建议按层级表述，而不是一句"做完了"：

十、复盘：四个结论

结语

把助手从"定时播报"改成"主动开口"，本质是把它从一条流水线改成一个有状态的会话参与者。真正的工作量不在调用模型，而在三件事：投递层的边界验证、行为规则的显式化、状态的可验证维护。

后两件事做完，主动消息才可能像个正常人；只做第一件，它只是个换了文案的闹钟。