Caspian流式回复完整指南:用 thread.stream() 实现打字机效果实时更新
Caspian流式回复完整指南:用 thread.stream() 实现打字机效果实时更新
Caspian 是面向 AI 智能体的开源通信 SDK,支持 Telegram、Slack、Discord、邮件、WhatsApp、SMS 等渠道。本教程讲一个很实用的功能:流式回复(streaming reply)——用一行 thread.stream(),让机器人的长回答像打字机一样边生成边显示,而不是干等几十秒才收到一整段消息。
为什么需要流式回复
传统机器人的模式是"收消息 → 思考很久 → 发完整回复"。当回答是一段长文(比如让 AI 总结文档、写邮件、讲故事)时,用户体验会很差:
- 用户盯着屏幕干等,不知道机器人卡没卡;
- 消息越长等待越久,中途无法看到任何进展。
流式回复把体验反了过来:先发出第一条消息,之后每生成一段文字就编辑(edit)这条消息,用户看到文字"自己长出来",就像 ChatGPT 网页版的效果。
thread.stream() 工作原理
Python SDK 中,stream() 定义在 handler 拿到的 Thread 对象上:
def stream(self, *, min_chars: int = 24, throttle: float = 0.5) -> Stream:
它的内部逻辑非常清晰(见 Stream 类实现):
- 首次 flush 时发一条 Post,并记下返回的
message_id; - 后续每次 flush 都发 Edit,用同一
message_id更新那条消息的全文; close()时兜底:无论之前发过几次,最后一定会把完整文本发出去。
两个参数控制"发送节奏":
| 参数 | 默认值 | 作用 |
|---|---|---|
min_chars |
24 | 新增文字累计到这么多字符才值得发一次,避免频繁调用 |
throttle |
0.5 | 两次编辑之间的最小间隔(秒),防止触发平台限流 |
还有一个关键属性 live:当运行时具备实时发送能力(有 transport 且渠道支持编辑消息)时为 True,表示真正边写边发;否则 Stream 会自动降级为缓冲模式——攒够全文,在 close() 时一次性 post()。这一点在 StreamSink 端口定义 中有说明:你的 handler 代码不需要为"能不能流式"写任何分支,SDK 自动处理。
三步开启打字机效果(Python)
第 1 步:注册 handler,声明 overlap: "stream"
@cx.on_message({"channel": "telegram", "overlap": "stream"})
def stream_story(thread, msg, ctx):
with thread.stream(min_chars=1, throttle=0.25) as out:
for chunk in llm_stream: # 任意 chunk 来源
out.append(chunk)
overlap 是同一会话里新消息到达时的并发策略,stream 表示"边流边并行",与打字机效果是绝配。策略状态机实现在 overlap.py。
第 2 步:用 with 上下文管理器
这是官方推荐写法。with 退出时自动调用 close(),保证最终全文一定发出——即使中途抛异常也不会留下半截消息。
第 3 步:逐块 append
每个 chunk 进来后 SDK 自行判断:够 min_chars 且距上次 flush 超过 throttle 秒,才真正发一次 Edit。快模型每 token 一个 chunk 也不会被限流。
调参速查:让打字节奏更自然
min_chars=1、throttle=0.25:最快的视觉节奏,适合演示(官方 Telegram 示例 就用的这组参数);- 默认
min_chars=24, throttle=0.5:适合生产,省配额; throttle=0:关闭节流(不建议,容易撞平台编辑频率限制)。
测试文件 test_streaming.py 验证了完整行为:一次 sendMessage 首发 + 多次 editMessageText,且最终文本完整。
TypeScript 版:同一套契约
TypeScript SDK 提供 camelCase 版本的同一 API(thread.ts 中 stream 定义):
const out = thread.stream({ minChars: 1, throttle: 0.25 })
for (const chunk of story) {
await out.append(chunk)
}
await out.close()
TS 没有上下文管理器,所以要显式 await out.close() 兜底。对照示例见 examples/telegram-ts/app.ts。
常见问题
问:我的渠道不支持编辑消息,流式还有用吗?
有。live 为 False 时自动降级为缓冲 + 一次 Post,回复照常送达,代码零改动(见 降级测试)。
问:流式消息和 thread.typing() 什么关系?
typing() 发的是"对方正在输入…"指示器,适合短思考;流式回复是真实文本的持续更新,适合长回答。二者可配合使用。
问:支持哪些渠道? 任何支持"编辑已发消息"的渠道都能真正流式,例如 Telegram(webhook 或 poll)、Discord(socket)、Slack(socket 或 webhook);托管模式覆盖网关支持的所有渠道。渠道能力一览见 中文 README。
小结
thread.stream()= 先发一条、边写边 Edit,实现打字机效果;with保证收尾,live决定实时还是缓冲降级,代码无需分支;- 用
min_chars和throttle两个参数调节节奏与平台限流; - Python 与 TypeScript 同一契约,改个命名即可切换语言。
更多可运行示例都在 examples/ 目录,每个渠道一个文件夹,可直接照抄。

