Skip to content

Looper v2.14.169

Choose a tag to compare

@github-actions github-actions released this 13 Nov 03:10
· 163 commits to main since this release
955eee1

Looper v2.14.169

This is the patch release v2.14.169, a hotfix line in which each merged change ships at once. It documents one change: #1310 (Recover Lark messages sent during service restarts).

Release Decision

Who should upgrade: Installations that run the lark-cli Lark channel and restart the service while users may be sending messages. Others need not upgrade for behavior.

What this release solves: #1310 answers eligible Lark messages sent while the service restarts, which the long connection does not replay.

Breaking changes: No. There is no migration or database schema change. The channel adds a small local state file per Lark channel in the runtime root. The bridge boundary is unchanged: upgrade to v2.13.165 first if the installation is older.

How to verify: Check the installed version.

looper --version   # looper 2.14.169

Contributors: Maintainer @foolzzz authored #1310; no community contribution was included in this release.

Upgrading

The bridge boundary is unchanged: an installation older than v2.13.165 must upgrade to v2.13.165 first (upgrade to v2.13.165 first) and be started once; see the Upgrading section of the v2.14.0 release for the steps and rollback. An installation on v2.14.0 to v2.14.168 upgrades directly. There is no database schema change.

Behavior changes

Read in the code of #1310:

  • Restart state (looper/agents/channels/lark_inbox.py, lark.py). Each lark-cli channel keeps a SQLite file .local/lark/<channel>/inbox.sqlite3 under the runtime root with a restart boundary, the latest 20,000 handled message IDs (no message content), and unfinished recovery windows. While the consumer is ready and no message is being handled, the boundary is saved every five seconds; a clean stop saves its stop time, and an interrupted handler or disconnected consumer keeps the earlier boundary. A missing boundary starts without replaying history.
  • Catch-up after start (looper/agents/channels/lark.py, lark_transport.py, lark_cli.py). After the consumer reports readiness (the ready marker, or its first live message; a 60 second wait otherwise ends with a warning), a background task lists raw chat history through lark-cli api GET /open-apis/im/v1/messages --as bot, from the saved boundary minus 10 seconds. A boundary older than 15 minutes skips the whole window, and a recovered message older than 15 minutes is skipped. Threads are read too: embedded replies, and a separate root scan for groups and topics.
  • Which chats (looper/db/chat_bindings.py). Chats with an explicit binding first, then, when the default Manager accepts unbound chats, chats observed in the last 24 hours; at most 100 chats, 5 pages per chat, 50 messages per page. A page limit reached or a failed listing warns and keeps that chat's window for the next start (dropped once older than 15 minutes).
  • Admission and deduplication (lark.py). Recovered messages go through the same handler as live ones (admission, group bot-mention check, routing, attachments, disabled chats). Live and recovered input share a lock and the durable receipts, so a message is handled once. A failed chat or message does not block other chats or live input. Each start logs one lark_catchup INFO summary.
  • Limits. P2P chats are recovered only when the bot can resolve the chat mode and read its history; otherwise a warning is logged and the chat is skipped. A never-observed unbound chat cannot be discovered during downtime. An expired window is not listed, so its message count is unknown. The bot needs history and chat-info read permissions; there is no user-identity fallback. The bot-token Lark transport is unchanged, and messages sent to it during a restart can still be lost.
  • Model-visible changes: None to prompts or tool descriptions. A Manager can receive a message later than it was sent, as the same input it would have received live.

Optional Capability Activation & Use

No new optional capability activation is introduced in this release.

Validation

Reported by the pull request: #1310 reports targeted tests passing (recovery and history transport, attachment failure variants, the schema upgrade case, catch-up candidate discovery, and a combined run of 18), an isolated real looper serve run with channels disabled and no real Lark traffic, and an independent read-only review with no blocking defects. A broader run was interrupted after seven failures; six timing or setup cases passed on rerun, and a foreign-key assertion that also fails on the original main test with the local PostgreSQL 18 (it expects ForeignKeyViolationError, the database reports RestrictViolationError) is outside the change. The pull request does not report a clean full suite, nor real Lark permissions or P2P access.

CI: CI runs after the release is drafted; its result is not recorded here.

Not tested for this draft: a local full suite, real Lark traffic and the built wheel. The release documentation gate checks the body only.

中文摘要

本版本是 patch release v2.14.169(热修线,每个合并的改动立即发布),说明一项改动:#1310(恢复服务重启期间发送的 Lark 消息)。

升级决策

**谁需要升级:**运行 lark-cli Lark 渠道、且重启服务时可能有用户发消息的安装。其他安装没有行为上的升级需求。

解决了什么:#1310 在服务重启后回复重启期间发送的符合条件的 Lark 消息,这些消息长连接不会重放。

**是否有破坏性变更:**否。没有迁移或数据库结构变更。每个 Lark 渠道在运行时根目录下新增一个小的本地状态文件。桥接边界不变:早于 v2.13.165 的安装须先升级到 v2.13.165。

**如何验证:**核对版本为 2.14.169。

**贡献者:**维护者 @foolzzz 提交 #1310;本版本无社区贡献。

looper --version   # looper 2.14.169

升级

桥接边界不变:早于 v2.13.165 的安装必须先升级到 v2.13.165 并启动一次(upgrade to v2.13.165 first 即先升级到 v2.13.165),步骤与回退见 v2.14.0 发布说明的升级一节。v2.14.0 至 v2.14.168 上的安装可直接升级。数据库没有结构变更。

行为变化与入口

以下在 #1310 的代码中可见:

  • 重启状态(looper/agents/channels/lark_inbox.py、lark.py)。每个 lark-cli 渠道在运行时根目录的 .local/lark/<channel>/inbox.sqlite3 保存重启边界、最近 20,000 个已处理消息 ID(不含消息内容)以及未完成的恢复窗口。消费者就绪且没有消息在处理时,每五秒保存一次边界;正常停止会保存停止时间,处理被打断或消费者断开则保留更早的边界。边界缺失时不回放历史。
  • 启动后追补(lark.py、lark_transport.py、lark_cli.py)。消费者报告就绪后(ready 标记或首条实时消息;否则等待 60 秒后警告),后台任务通过 lark-cli api GET /open-apis/im/v1/messages --as bot 列出原始聊天历史,从保存的边界减 10 秒开始。边界早于 15 分钟则整个窗口跳过,早于 15 分钟的单条消息也跳过。话题线程同样会读取:内嵌回复,以及对群和话题的独立根消息扫描。
  • 哪些聊天(looper/db/chat_bindings.py)。先是有显式绑定的聊天,然后在默认 Manager 接受未绑定聊天时,加上最近 24 小时内观察到的聊天;最多 100 个聊天,每个聊天 5 页,每页 50 条。达到页数上限或列表失败会警告,并保留该聊天的窗口到下次启动(超过 15 分钟后丢弃)。
  • 准入与去重(lark.py)。恢复的消息走与实时消息相同的处理流程(准入、群内 @ 机器人检查、路由、附件、停用聊天)。实时与恢复输入共用锁和持久化回执,每条消息只处理一次。单个聊天或消息失败不会阻塞其他聊天或实时输入。每次启动记录一条 lark_catchup INFO 摘要。
  • **限制。**仅当机器人能解析聊天模式并读取历史时才恢复 P2P 聊天,否则记录警告并跳过。从未观察到的未绑定聊天无法在停机期间被发现。过期窗口不会被列出,因此其消息数未知。机器人需要历史与聊天信息读取权限,没有用户身份回退。bot-token 的 Lark 传输不变,发送给它的消息在重启期间仍可能丢失。
  • **面向模型的变化:**提示词和工具描述没有变化。Manager 可能比发送时间更晚收到消息,其内容与实时收到的相同。

可选能力启用与使用

本版本未新增可选能力启用入口。

验证

PR 报告的:#1310 报告了通过的定向测试(恢复与历史传输、附件失败变体、schema 升级用例、追补候选发现,以及合并运行的 18 个用例)、在禁用渠道且不发送真实 Lark 流量下的隔离 looper serve 运行,以及无阻塞缺陷的独立只读评审。更大范围的运行在七个失败后被中断;其中六个时序或准备问题重跑通过,另有一个外键断言在原 main 测试上、本地 PostgreSQL 18 下同样失败(期望 ForeignKeyViolationError,数据库返回 RestrictViolationError),与本改动无关。PR 未报告完整套件的干净通过,也未验证真实 Lark 权限或 P2P 访问。

**CI:**发布草稿后 CI 会运行,其结果未在此记录。

**本次草稿未测试:**本地完整套件、真实 Lark 流量以及构建出的 wheel。发布文档 gate 只检查正文。