From 45d14b1e1d2fa77ca34de6c299f03679abb56930 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:24:20 +0800
Subject: [PATCH 001/121] fix(cognitive): retry display name sync after index
 failures

---
 docs/cognitive-memory.md                   |  2 +
 src/Undefined/cognitive/service/service.py | 13 ++--
 tests/test_cognitive_service.py            | 89 ++++++++++++++++++++++
 3 files changed, 98 insertions(+), 6 deletions(-)

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
index 73cb01a3..c1e87df1 100644
--- a/docs/cognitive-memory.md
+++ b/docs/cognitive-memory.md
@@ -98,6 +98,8 @@ end → pending（持久化入队顺序）
 
 等待顺位的任务留在磁盘队列，不创建等待协程、不占执行名额。群侧写与发送者侧写分别调度，某个用户目标被阻塞时，同一任务已经轮到的群目标可以先执行。不同实体的 LLM 合并可以同时进行；Chroma 的实际数据库访问仍使用下文的共享单 worker 调度。昵称刷新和侧写恢复复用同一实体锁，避免基于旧副本覆盖正文。
 
+昵称刷新先更新侧写向量，再提交 Markdown 文件中的新名称。向量暂时不可写时，文件仍保留旧名称，后续同名消息可继续重试，重启后也不会因名称已更新而跳过。文件写入失败时向量可能已更新，但下一次刷新仍按实际文件重试；名称相同且无需刷新时不重复写入。
+
 **进度与恢复**：任务保存 `_enqueue_order` 以及 `_historian_progress`（已改写文本、已入库事件数、已完成侧写目标）。自动重试只处理未完成部分，阶段切换不增加 `_retry_count`。文件、向量和目标进度均提交后才放行下一个同实体更新；明确 `skip=true` 也会完成目标。没有有效更新或明确跳过的模型结束按失败处理。
 
 失败不会自动回滚已经写入的侧写文件。向量写入或进度保存失败时，重试会重新读取当前实际文件；重试耗尽后，后续任务同样基于当前实际版本继续。正常停止等待在途阶段结束；外层取消或停止超时触发取消时，事件改写和侧写合并的模型调用可立即中断，只等待已经开始的文件、向量、对应进度及队列状态提交收敛，再释放实体占用。取消后尚未完成队列切换的任务保留 `processing` 与已保存进度，后续恢复时不重做已提交部分。启动及轮询恢复超过 `stale_job_timeout_seconds` 的遗留 `processing`，排除活跃任务；未达到恢复阈值的遗留任务仍占其未完成实体的顺位，不阻塞其他实体。
diff --git a/src/Undefined/cognitive/service/service.py b/src/Undefined/cognitive/service/service.py
index 841a65c9..82f55335 100644
--- a/src/Undefined/cognitive/service/service.py
+++ b/src/Undefined/cognitive/service/service.py
@@ -144,12 +144,6 @@ async def _sync() -> bool:
                 updated_markdown = _serialize_profile_markdown(
                     frontmatter, summary, evaluation=evaluation, roast=roast
                 )
-                await self._profile_storage.write_profile(
-                    normalized_entity_type,
-                    normalized_entity_id,
-                    updated_markdown,
-                )
-
                 profile_doc, profile_metadata = _build_profile_vector_payload(
                     entity_type=normalized_entity_type,
                     entity_id=normalized_entity_id,
@@ -166,6 +160,13 @@ async def _sync() -> bool:
                     profile_metadata,
                     priority=CHROMA_PRIORITY_FOREGROUND,
                 )
+                # 文件中的名称决定是否需要重试；索引成功后再提交名称，避免
+                # 一次向量写入失败后，被「名称未变化」永久跳过（重启后也一样）。
+                await self._profile_storage.write_profile(
+                    normalized_entity_type,
+                    normalized_entity_id,
+                    updated_markdown,
+                )
                 logger.info(
                     "[认知服务] 已刷新侧写展示名: entity_type=%s entity_id=%s old=%s new=%s",
                     normalized_entity_type,
diff --git a/tests/test_cognitive_service.py b/tests/test_cognitive_service.py
index 0a8e7cfb..59f9cf53 100644
--- a/tests/test_cognitive_service.py
+++ b/tests/test_cognitive_service.py
@@ -862,6 +862,95 @@ async def test_sync_profile_display_name_noops_when_name_unchanged() -> None:
     assert vector_store.last_upsert_profile is None
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("entity_type", ["user", "group"])
+async def test_sync_profile_display_name_retries_after_vector_failure(
+    entity_type: str,
+) -> None:
+    existing_profile = "---\nname: 旧名称\ntags: []\n---\n既有侧写内容\n"
+
+    class FailingOnceVectorStore(_FakeVectorStore):
+        attempts: int = 0
+
+        async def upsert_profile(
+            self,
+            profile_id: str,
+            document: str,
+            metadata: dict[str, Any],
+            **kwargs: Any,
+        ) -> None:
+            self.attempts += 1
+            if self.attempts == 1:
+                raise RuntimeError("temporary vector failure")
+            await super().upsert_profile(profile_id, document, metadata, **kwargs)
+
+    vectors = FailingOnceVectorStore()
+    storage = _FakeProfileStorage(existing_profile)
+    service = CognitiveService(
+        lambda: SimpleNamespace(enabled=True), vectors, _FakeJobQueue(), storage
+    )
+    with pytest.raises(RuntimeError, match="temporary vector failure"):
+        await service.sync_profile_display_name(
+            entity_type=entity_type, entity_id="12345", preferred_name="新名称"
+        )
+    assert storage.profile == existing_profile
+    assert storage.last_write is None
+
+    # 重建服务模拟重启：重试不能依赖进程内的脏标记。
+    service = CognitiveService(
+        lambda: SimpleNamespace(enabled=True), vectors, _FakeJobQueue(), storage
+    )
+    assert await service.sync_profile_display_name(
+        entity_type=entity_type, entity_id="12345", preferred_name="新名称"
+    )
+    assert vectors.attempts == 2
+    assert vectors.last_upsert_profile is not None
+    assert vectors.last_upsert_profile[2]["name"] == "新名称"
+    assert storage.profile is not None
+    assert "name: 新名称" in storage.profile
+    assert "既有侧写内容" in storage.profile
+    assert not await service.sync_profile_display_name(
+        entity_type=entity_type, entity_id="12345", preferred_name="新名称"
+    )
+    assert vectors.attempts == 2
+
+
+@pytest.mark.asyncio
+async def test_sync_profile_display_name_retries_after_file_failure() -> None:
+    existing_profile = "---\nname: 旧名称\ntags: []\n---\n既有侧写内容\n"
+
+    class FailingOnceStorage(_FakeProfileStorage):
+        attempts: int = 0
+
+        async def write_profile(
+            self, entity_type: str, entity_id: str, content: str
+        ) -> None:
+            self.attempts += 1
+            if self.attempts == 1:
+                raise OSError("temporary file failure")
+            await super().write_profile(entity_type, entity_id, content)
+
+    vectors = _FakeVectorStore()
+    storage = FailingOnceStorage(existing_profile)
+    service = CognitiveService(
+        lambda: SimpleNamespace(enabled=True), vectors, _FakeJobQueue(), storage
+    )
+    with pytest.raises(OSError, match="temporary file failure"):
+        await service.sync_profile_display_name(
+            entity_type="user", entity_id="12345", preferred_name="新名称"
+        )
+    assert storage.profile == existing_profile
+    assert await service.sync_profile_display_name(
+        entity_type="user", entity_id="12345", preferred_name="新名称"
+    )
+    assert storage.attempts == 2
+    assert storage.profile is not None
+    assert "name: 新名称" in storage.profile
+    assert "既有侧写内容" in storage.profile
+    assert vectors.last_upsert_profile is not None
+    assert vectors.last_upsert_profile[2]["name"] == "新名称"
+
+
 def test_parse_profile_markdown_old_two_part_has_empty_evaluation() -> None:
     from Undefined.cognitive.service.helpers import _parse_profile_markdown
 

From e4b6d16cc58f0dace25472c47d3a082422267054 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:24:58 +0800
Subject: [PATCH 002/121] fix(batching): finish completed speculative replies
 before new input

---
 docs/message-batching.md                      |  1 +
 .../services/message_batcher/scheduler.py     | 17 +++++++---
 tests/test_message_batcher.py                 | 32 +++++++++++++++++++
 3 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/docs/message-batching.md b/docs/message-batching.md
index 3393e245..77557b0a 100644
--- a/docs/message-batching.md
+++ b/docs/message-batching.md
@@ -133,6 +133,7 @@ allow_cancel_after_send = false
   - inflight **尚未发消息** → 调 `inflight_task.cancel()`，桶回到 `TYPING`，新消息追加进去，重置 T1/T2；inflight 协程在 `RequestContext` 里清理后退出，**不写入回复历史**。
   - T2 已经把请求入队但 coordinator 还没注册 inflight → 取消旧 `BatchDispatchToken`；旧请求即使稍后被队列取出，也会在 `execute_reply` 入口跳过，新消息继续合并进重新计时的 batch。
   - inflight **已经发过消息** 且 `allow_cancel_after_send=False`（默认安全） → 不取消 inflight，**新消息开新 batch**（旧桶在 inflight 自然结束后清理）。
+  - 投机调用已经回复并完成 → 立即结束旧 batch；窗口内后续消息也会开启新 batch，不再把已回答的旧消息合并重放。此时任务已经完成，`allow_cancel_after_send` 不改变该行为。尚未回复就完成的投机仍保留原消息，允许后续补充重新合并。
 - **FINALIZING**：旧 batch 已到 T1，若此时又来新消息，直接开新桶，不阻塞旧 inflight 收尾。
 - `allow_cancel_after_send=True` 会在 inflight 已发过消息后仍取消，可能造成半截回复、重复回复或上下文撕裂，仅极端场景启用。
 
diff --git a/src/Undefined/services/message_batcher/scheduler.py b/src/Undefined/services/message_batcher/scheduler.py
index 45b0cf93..30dcd4a0 100644
--- a/src/Undefined/services/message_batcher/scheduler.py
+++ b/src/Undefined/services/message_batcher/scheduler.py
@@ -340,11 +340,20 @@ def unregister_inflight(
                 state.phase.value,
             )
             return
+        if (
+            state.phase is BatchPhase.SPECULATING
+            and state.inflight is not None
+            and was_message_sent(state.inflight.request_context)
+        ):
+            # 已回复且模型已结束，旧批次无需再等待 T1；完成后不能再取消，
+            # 新消息必须开新桶，不能重放旧 items（与 allow_cancel_after_send 无关）。
+            self._cancel_t1(state)
+            self._cancel_t2(state)
+            state.phase = BatchPhase.FINALIZING
+            self._buckets.pop(key, None)
         state.inflight = None
-        # 若 phase 是 SPECULATING 且 T1 已经 fire 过（FINALIZING 才 unregister），
-        # 此时 inflight 自然结束 → 桶已经在 _on_t1_timer 中弹出，无需再做事
-        # 若仍在 SPECULATING（T1 未到）：inflight 已结束但仍可能有新消息进来；
-        # 保持 SPECULATING，新消息会按 SPECULATING 分支处理（已发消息开新 batch / 未发追加）
+        # 未发回复的投机仍保留 items，后续补充消息可以重新合并；T1 已到的桶
+        # 则交给 _handle_t1 收尾，避免注销旧任务时误删后来创建的新桶。
         logger.debug(
             "[MessageBatcher] 注销 inflight 任务: scope=%s sender=%s phase=%s",
             scope,
diff --git a/tests/test_message_batcher.py b/tests/test_message_batcher.py
index 09048d0f..5970bb74 100644
--- a/tests/test_message_batcher.py
+++ b/tests/test_message_batcher.py
@@ -429,6 +429,38 @@ async def flush(items: list[BufferedMessage]) -> None:
     assert not inflight_task.cancelled()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("already_sent", [False, True])
+@pytest.mark.parametrize("allow_cancel_after_send", [False, True])
+async def test_completed_speculation_does_not_reprocess_answered_items(
+    already_sent: bool, allow_cancel_after_send: bool
+) -> None:
+    cfg = MessageBatcherConfig(
+        enabled=True,
+        window_seconds=100.0,
+        pre_send_seconds=50.0,
+        allow_cancel_after_send=allow_cancel_after_send,
+    )
+    rec = _Recorder()
+    batcher = MessageBatcher(cfg, rec)
+    fake_ctx = _FakeRequestContext()
+    fake_ctx.set_resource("message_sent_this_turn", already_sent)
+    try:
+        await batcher.submit(_make_item(text="m1"))
+        await batcher._handle_t2(("group:1", 100))
+        inflight = asyncio.create_task(asyncio.sleep(0))
+        batcher.register_inflight("group:1", 100, inflight, fake_ctx)
+        await inflight
+        batcher.unregister_inflight("group:1", 100, inflight)
+
+        await batcher.submit(_make_item(text="m2"))
+        await batcher.flush_sender("group:1", 100)
+        expected = [["m1"], ["m2"]] if already_sent else [["m1"], ["m1", "m2"]]
+        assert [[item.text for item in items] for items in rec.batches] == expected
+    finally:
+        await batcher.flush_all()
+
+
 @pytest.mark.asyncio
 async def test_speculative_cancelled_when_already_sent_with_allow_flag() -> None:
     """``allow_cancel_after_send=True`` 时即便已发过消息也强制取消 inflight。

From 7a8202db0677eb857ca5b7e43684bbf3f216ad0a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:26:45 +0800
Subject: [PATCH 003/121] fix(jm): honor session paths and isolate malformed
 inputs and chapters

---
 config.toml.example            |  4 +-
 docs/configuration.md          |  6 ++-
 src/Undefined/jm/client.py     |  3 ++
 src/Undefined/jm/downloader.py | 60 +++++++++++------------
 src/Undefined/jm/parser.py     | 10 ++--
 tests/test_jm_downloader.py    | 87 +++++++++++++++++++++++++++++++++-
 tests/test_jm_parser.py        | 43 +++++++++++++++++
 tests/test_jm_tool.py          | 16 +++++++
 8 files changed, 192 insertions(+), 37 deletions(-)

diff --git a/config.toml.example b/config.toml.example
index a556f52a..21a67eae 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -1611,8 +1611,8 @@ request_timeout = 20.0
 # zh: 图片下载超时（秒）。<=0 回退 60，>600 截断到 600。
 # en: Image download timeout (seconds). <=0 falls back to 60, >600 is clamped to 600.
 image_timeout = 60.0
-# zh: jmcpy 的配置目录（登录态与会话文件所在目录，可指向已登录的 JMCPY_HOME）。留空使用平台默认目录。
-# en: jmcpy config directory (login session files; point it at an existing JMCPY_HOME). Empty uses the platform default directory.
+# zh: jmcpy 的配置目录（登录态与会话文件所在目录）。显式值优先；留空读取 JMCPY_HOME，两者均为空时使用平台默认目录。
+# en: jmcpy config directory (login session files). An explicit value takes precedence; empty falls back to JMCPY_HOME, then the platform default directory.
 session_dir = ""
 
 # zh: Code Delivery Agent 配置（代码交付 Agent，在 Docker 容器中编写代码并打包上传）。
diff --git a/docs/configuration.md b/docs/configuration.md
index 2f55a95e..a3939cdd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1131,16 +1131,18 @@ api_key = "replace-with-your-key"
 | `download_concurrency` | `8` | 图片下载并发数 | `<1` 回退 `8`，`>32` 截断到 `32` |
 | `request_timeout` | `20.0` | 接口请求超时（秒） | `<=0` 回退 `20`，`>120` 截断到 `120` |
 | `image_timeout` | `60.0` | 图片下载超时（秒） | `<=0` 回退 `60`，`>600` 截断到 `600` |
-| `session_dir` | `""` | jmcpy 配置目录（登录态会话文件所在目录） | 空时用 jmcpy 的平台默认目录 |
+| `session_dir` | `""` | jmcpy 配置目录（登录态会话文件所在目录） | 非空值优先；空时使用 `JMCPY_HOME`，两者均为空时使用平台默认目录 |
 
 触发规则：
 - 匹配 `JM` 前缀加 5–8 位车号：`JM1114751`、`jm 1114751`、`jm:1114751`、`jm-1114751`；前缀前必须是边界（`xxjm1234567` 不触发），数字后不跟数字（9 位以上不会被截成 8 位）。
 - 匹配主机名含 `18comic` 或 `jmcomic` 的链接，车号取自 `/album/<id>`、`/photo/<id>` 或 `?id=<id>`。
 - 裸数字不触发，避免群号、时间戳等误报；QQ 分享卡片（`json` 消息段）里的链接同样会解析。
+- 畸形 URL 只跳过该链接，仍会继续解析同一条消息或后续分享卡片中的合法车号。
 
 自动提取行为：
 - 命中后发送一次外层合并转发，固定两个节点：**本子信息**（车号、标题、作者、章节数、标签、观看/点赞、页数、zip 大小、被跳过的章节数、简介预览，末尾是可直接复制的 `JM<车号>`）、**PDF 解密密码**（每次随机生成 8 位，字母表去掉 `0/O/1/l/I` 等形近字符，适用于 zip 内所有 PDF）。打包好的 zip **不进转发**，而是紧随转发之后单独作为一条文件消息发送。
 - 多章节本子会把全部章节按顺序下载（`max_chapters` 可限制章数），**每章各出一份 AES-256 加密 PDF**（都用同一个密码），再打包成一个**无密码** zip：`JM<车号> <标题>.zip`，内部条目是 `JM<车号> <序号>[ <章节标题>].pdf`，序号补零所以解压后按文件名就是阅读顺序。zip 不需要密码，密码在每个章节 PDF 内部由阅读器询问。
+- 服务端章节序号重复或缺失导致冲突时，下载目录与章节 PDF 的产物序号会顺延，保持唯一且符合阅读顺序；`uid` 模式也使用独立章节目录，避免复用同标题的上一章图片。下载结果中的章节元数据仍保留服务端原始序号。
 - 每页按 `pdf_dpi` 统一换算物理尺寸（`页宽 = 像素宽 ÷ DPI × 72`），下载与合成都不缩放像素：PDF 里的页就是站点源图的原始分辨率，画质上限由站点自己提供的图决定。
 - 每页只做一次有损编码：取服务端原始字节（无损落盘）→ 解扰 → JPEG（`image_quality`，4:4:4）→ 直接作为 PDF 的图像数据，中间不再多一代重编码。需要更高画质时可把 `image_quality` 提到 `98`/`100`（约 `+30%`/`+50%` 体积），源图本身的分辨率无法通过配置提升。
 - 单章 PDF 按 `chapter_max_file_size` 判定：组装时累计**编码后字节**（JPEG 重编码 4:4:4 / q95 可能比源 WebP 大），超过上限就中止这一章、不落盘，其余章节照常打包，信息节点会写明「N 章未打包」。这是**单章**上限，zip 总体积随章节数增长、不受配置约束；旧键 `[jm].max_file_size` 已失效（回退默认 100），请改用 `chapter_max_file_size`。
@@ -1155,7 +1157,7 @@ api_key = "replace-with-your-key"
 - 除了自动提取，`jm_book` 工具让 AI 也能按需处理车号：`output_mode=send`（默认，等价自动提取）、`uid`（只下载并**把所有章节合成一份未加密 PDF** 注册为附件 UID，交给 `file_analysis_agent` 用 `extract_pdf` / `describe_pdf_page` 解析，不发送消息、不打包 zip）、`info`（只返回本子信息，不下载）。
 - `info_agent` 的 `jm_search` 工具查询本子列表，`mode` 三种：`search`（关键词检索，可用 `target` 限定站内/作品/作者/标签/角色，也可直接输入纯数字车号）、`browse`（按分类浏览，不需要关键词）与 `ranking`（日/周/月排行，用 `time_range` 选日榜/周榜/月榜，固定按观看数排序）。三种模式共用 `genre` 大分类、`page` 翻页与 `n`（默认 5、上限 20）；`search` / `browse` 另支持 `sort`（最新/观看/图片/点赞/评分/评论）与 `time_range` 时间范围；`sub_genre` 副分类必须与 `genre` 同时给出，且只有网页端接口支持，网页端被反爬拦截时会直接返回失败原因。只返回车号、标题、作者、分类与更新时间，不下载也不发送。查询复用同一份 `[jm]` 配置（代理、`request_timeout`、`session_dir`），且**不受** `auto_extract_enabled` 影响——该开关只约束自动提取管线。
 - jmcpy 的 HTTP 请求是异步的，但图片解码与 PDF 合成是同步 CPU 工作；这些步骤在线程中执行，不阻塞事件循环。副作用是单次自动提取不可取消，由 `request_timeout` / `image_timeout` 与 jmcpy 的多端点重试兜底。
-- 默认不登录即可使用；需要在 jmcpy 中登录（例如访问账号可见内容）时，用 jmcpy 自己的方式保存会话，再把 `session_dir` 指向同一配置目录（或设置 `JMCPY_HOME`）。
+- 默认不登录即可使用；需要在 jmcpy 中登录（例如访问账号可见内容）时，用 jmcpy 自己的方式保存会话，再把 `session_dir` 指向同一配置目录，或在 `session_dir` 留空时设置 `JMCPY_HOME`。目录值会去除首尾空白，显式 `session_dir` 优先于环境变量。
 - 请遵守所在地法律法规与目标站点服务条款，只处理你有权获取的内容。
 
 ---
diff --git a/src/Undefined/jm/client.py b/src/Undefined/jm/client.py
index 4d73d5e9..8bf22368 100644
--- a/src/Undefined/jm/client.py
+++ b/src/Undefined/jm/client.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Any
 
@@ -20,6 +21,8 @@
 def build_settings(config: Any) -> Settings:
     """把 ``[jm]`` 配置映射成 jmcpy 的 :class:`~jmcpy.Settings`。"""
     home = str(getattr(config, "jm_session_dir", "") or "").strip()
+    if not home:
+        home = os.environ.get("JMCPY_HOME", "").strip()
     return Settings(
         proxy=get_request_proxy(_PROXY_PROBE_URL, proxy_scope="jm", config=config),
         timeout=float(getattr(config, "jm_request_timeout", 20.0)),
diff --git a/src/Undefined/jm/downloader.py b/src/Undefined/jm/downloader.py
index 6e9deaaa..487e53e2 100644
--- a/src/Undefined/jm/downloader.py
+++ b/src/Undefined/jm/downloader.py
@@ -26,7 +26,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Iterator, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 import asyncio
@@ -165,11 +165,33 @@ def _book_file_name(book: Book, suffix: str) -> str:
     return f"{_BOOK_ID_PREFIX}{book.book_id} {title}{suffix}"
 
 
+def _chapter_artifact_indices(
+    chapters: Sequence[tuple[int, int, str]],
+) -> Iterator[str]:
+    """生成递增且唯一的章节产物序号，保留正常序号与阅读顺序。"""
+    previous_index: int | None = None
+    for chapter_id, chapter_order, _title in chapters:
+        index = (
+            chapter_order
+            if previous_index is None
+            else max(chapter_order, previous_index + 1)
+        )
+        if index != chapter_order:
+            logger.warning(
+                "[JM] 章节产物序号冲突，顺延避免覆盖: chapter=%s order=%s → %s",
+                chapter_id,
+                chapter_order,
+                index,
+            )
+        previous_index = index
+        yield f"{index:0{_CHAPTER_INDEX_DIGITS}d}"
+
+
 def _chapter_pdf_name(stem: str, title: str) -> str:
     """章节 PDF 名：``<产物名主体>[ <章节标题>].pdf``。
 
-    ``stem`` 由 :func:`_download_archive_sync` 内的 ``artifact_stem`` 生成，已经保证
-    同一次下载内唯一。章节标题写在文件名里便于挑选章节；服务端没给标题时只留序号。
+    ``stem`` 使用 :func:`_chapter_artifact_indices` 的唯一序号。章节标题写在文件名里
+    便于挑选章节；服务端没给标题时只留序号。
     """
     chapter_title = sanitize_filename(title)
     return (
@@ -319,40 +341,19 @@ def _download_archive_sync(
     """逐章下载并各出一份加密 PDF，最后打包成无密码 zip。"""
     limit_bytes = _chapter_limit_bytes(chapter_max_file_size_mb)
     built: list[_ChapterPdf] = []
-    used_orders: set[int] = set()
     downloaded_chapters = 0
     skipped_chapters = 0
     failed_pages = 0
     page_count = 0
 
-    def artifact_index(chapter_order: int, local_index: int, chapter_id: int) -> str:
-        """章节产物的序号（补零字符串），用于下载目录名与 zip 条目名。
-
-        优先用服务端章节序号（与阅读顺序一致）；服务端返回重复序号（异常数据）时退回
-        本次下载的局部序号，否则两条章节会撞同一个下载目录与图片文件名
-        （``overwrite=False`` 会拿旧图），也会撞同一个 zip 条目名而丢掉一份 PDF。
-        """
-        index = chapter_order
-        if index in used_orders:
-            index = local_index
-            logger.warning(
-                "[JM] 服务端返回重复章节序号，改用局部序号避免覆盖: book=%s chapter=%s order=%s → %s",
-                book_id,
-                chapter_id,
-                chapter_order,
-                index,
-            )
-        used_orders.add(index)
-        return f"{index:0{_CHAPTER_INDEX_DIGITS}d}"
-
     with Client(settings) as client:
         book = client.get_book(book_id)
         # 声明总数取本子自身的章节列表，不受 max_chapters 截断影响
         declared_chapters = len(book.chapters) or 1
         chapters = _ordered_chapters(book, max_chapters=max_chapters)
 
-        for local_index, (chapter_id, chapter_order, chapter_title) in enumerate(
-            chapters, start=1
+        for (chapter_id, chapter_order, chapter_title), index in zip(
+            chapters, _chapter_artifact_indices(chapters), strict=True
         ):
             chapter = client.get_chapter(chapter_id)
             if not len(chapter):
@@ -360,7 +361,6 @@ def artifact_index(chapter_order: int, local_index: int, chapter_id: int) -> str
                     "[JM] 章节没有图片，跳过: book=%s chapter=%s", book_id, chapter_id
                 )
                 continue
-            index = artifact_index(chapter_order, local_index, chapter_id)
             # 每章独立的目录：同名目录复用同名目录时，overwrite=False 会拿旧图。
             # decode=False 取服务端原始字节（无损），解扰与编码在写 PDF 时做一次。
             result = client.download(
@@ -481,7 +481,9 @@ def _download_plain_sync(
         failed_pages = 0
         downloaded_chapters = 0
 
-        for chapter_id, chapter_order, _title in chapters:
+        for (chapter_id, _chapter_order, _title), index in zip(
+            chapters, _chapter_artifact_indices(chapters), strict=True
+        ):
             chapter = client.get_chapter(chapter_id)
             if not len(chapter):
                 logger.info(
@@ -491,7 +493,7 @@ def _download_plain_sync(
             result = client.download(
                 chapter,
                 output=ExportFormat.PATH,
-                dest=task_dir / f"c{chapter_order:0{_CHAPTER_INDEX_DIGITS}d}",
+                dest=task_dir / f"c{index}",
                 decode=False,
                 concurrency=settings.concurrency,
             )
diff --git a/src/Undefined/jm/parser.py b/src/Undefined/jm/parser.py
index 8ad2334b..238e8259 100644
--- a/src/Undefined/jm/parser.py
+++ b/src/Undefined/jm/parser.py
@@ -42,7 +42,11 @@ def _strip_wrapper_chars(value: str) -> str:
     return html.unescape(value).strip().rstrip(_URL_WRAPPERS)
 
 
-def _is_jm_host(host: str) -> bool:
+def _is_jm_url(value: str) -> bool:
+    try:
+        host = urlsplit(value).hostname or ""
+    except ValueError:
+        return False
     return any(keyword in host for keyword in _JM_HOST_KEYWORDS)
 
 
@@ -53,7 +57,7 @@ def normalize_jm_id(value: int | str) -> str | None:
     （普通数字串与非禁漫链接都不会被误判成车号）。
     """
     if isinstance(value, str) and "://" in value:
-        if not _is_jm_host(urlsplit(value).hostname or ""):
+        if not _is_jm_url(value):
             return None
     try:
         digits = normalize_book_id(value)
@@ -83,7 +87,7 @@ def _iter_candidates(text: str) -> Iterator[tuple[int, str]]:
     """产出 ``(位置, 候选串)``：链接与 ``JM`` 车号混排时也按原文顺序排列。"""
     for match in _URL_REGEX.finditer(text):
         candidate = _strip_wrapper_chars(match.group(0))
-        if _is_jm_host(urlsplit(candidate).hostname or ""):
+        if _is_jm_url(candidate):
             yield match.start(), candidate
     for match in _JM_TOKEN_REGEX.finditer(text):
         yield match.start(), match.group(1)
diff --git a/tests/test_jm_downloader.py b/tests/test_jm_downloader.py
index b180aa14..429de1f2 100644
--- a/tests/test_jm_downloader.py
+++ b/tests/test_jm_downloader.py
@@ -148,7 +148,9 @@ def download(
         paths: list[Path] = []
         for name in chapter.pictures:
             path = dest / name
-            path.write_bytes(b"page")
+            # jmcpy 默认不覆盖同名页面：保留章节身份以验证不会复用上一章图片。
+            if not path.exists():
+                path.write_bytes(str(chapter.chapter_id).encode())
             paths.append(path)
         self.downloads.append(
             {
@@ -479,6 +481,60 @@ async def test_download_book_keeps_every_chapter_when_orders_collide(
     assert sorted(path.name for path in task_dir.glob("*.pdf")) == []
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("password", [None, "Ab3xK9Qm"])
+@pytest.mark.parametrize(
+    ("orders", "expected_indices"),
+    [
+        ((2, 2), ("002", "003")),
+        ((2, 2, 3), ("002", "003", "004")),
+        ((1, 3, 3, 4), ("001", "003", "004", "005")),
+        ((3, 3, 3), ("003", "004", "005")),
+    ],
+)
+async def test_download_book_preserves_chapter_pages_when_orders_collide(
+    monkeypatch: pytest.MonkeyPatch,
+    orders: tuple[int, ...],
+    expected_indices: tuple[str, ...],
+    password: str | None,
+) -> None:
+    chapter_ids = [111 * index for index in range(1, len(orders) + 1)]
+    _install_client(
+        monkeypatch,
+        chapters=[
+            (chapter_id, order, "序章")
+            for chapter_id, order in zip(chapter_ids, orders, strict=True)
+        ],
+    )
+    captured = _capture_write_pdf(monkeypatch)
+
+    result, _ = await download_book("1114751", config=_config(), password=password)
+
+    assert result.ok
+    assert result.page_count == len(orders) * 2
+    assert [item["dest"].name for item in _FakeClient.instances[0].downloads] == [
+        f"c{index}" for index in expected_indices
+    ]
+    sources = [
+        path.read_bytes() for call in captured["calls"] for path in call["sources"]
+    ]
+    assert sources == [
+        str(chapter_id).encode() for chapter_id in chapter_ids for _ in range(2)
+    ]
+    if password is not None:
+        archive = _archive(result)
+        assert archive.zip_path is not None
+        assert _zip_entries(archive.zip_path) == [
+            f"JM1114751 {index} 序章.pdf" for index in expected_indices
+        ]
+        assert [pdf.order for pdf in archive.pdfs] == list(orders)
+        assert [pdf.chapter_id for pdf in archive.pdfs] == chapter_ids
+    else:
+        plain = _plain(result)
+        assert plain.pdf_path is not None
+        assert len(captured["calls"]) == 1
+
+
 @pytest.mark.asyncio
 async def test_download_book_skips_chapter_whose_pages_all_failed(
     monkeypatch: pytest.MonkeyPatch,
@@ -613,6 +669,7 @@ def test_build_settings_leaves_home_unset_when_session_dir_empty(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.setattr(jm_client, "get_request_proxy", lambda *_args, **_kwargs: None)
+    monkeypatch.delenv("JMCPY_HOME", raising=False)
 
     settings = jm_client.build_settings(_config(jm_session_dir="  "))
 
@@ -620,6 +677,34 @@ def test_build_settings_leaves_home_unset_when_session_dir_empty(
     assert settings.proxy is None
 
 
+@pytest.mark.parametrize(
+    ("session_dir", "env_home", "expected_home"),
+    [
+        ("", "/tmp/jmcpy-env", Path("/tmp/jmcpy-env")),
+        ("  ", "  /tmp/jmcpy-env  ", Path("/tmp/jmcpy-env")),
+        (" /tmp/jmcpy-explicit ", "/tmp/jmcpy-env", Path("/tmp/jmcpy-explicit")),
+        ("", "  ", None),
+    ],
+)
+def test_build_settings_resolves_session_dir_before_jmcpy_home(
+    monkeypatch: pytest.MonkeyPatch,
+    session_dir: str,
+    env_home: str,
+    expected_home: Path | None,
+) -> None:
+    monkeypatch.setenv("JMCPY_HOME", env_home)
+    monkeypatch.setattr(jm_client, "get_request_proxy", lambda *_args, **_kwargs: None)
+
+    settings = jm_client.build_settings(_config(jm_session_dir=session_dir))
+
+    assert settings.home == expected_home
+    assert (
+        settings.resolved_session_path
+        == (expected_home if expected_home is not None else settings.resolved_home)
+        / "session.json"
+    )
+
+
 def _page_png(path: Path, size: tuple[int, int], *, band: int = 0) -> Path:
     image = Image.new("RGB", size, (255, 255, 255))
     for index in range(0, size[1], 7):
diff --git a/tests/test_jm_parser.py b/tests/test_jm_parser.py
index 55f03e0a..0e292c64 100644
--- a/tests/test_jm_parser.py
+++ b/tests/test_jm_parser.py
@@ -3,6 +3,8 @@
 import json
 from typing import Any
 
+import pytest
+
 from Undefined.jm.parser import (
     extract_from_json_message,
     extract_jm_ids,
@@ -27,6 +29,25 @@ def test_normalize_jm_id_rejects_out_of_range_and_garbage() -> None:
     assert normalize_jm_id("https://example.com/album/1114751") is None
 
 
+@pytest.mark.parametrize(
+    "value",
+    [
+        "https://[18comic.vip/album/1114751",
+        "https://[invalid]/album/1114751",
+    ],
+)
+def test_normalize_jm_id_rejects_malformed_url(value: str) -> None:
+    assert normalize_jm_id(value) is None
+
+
+def test_extract_jm_ids_skips_malformed_urls_and_keeps_text_order() -> None:
+    assert extract_jm_ids(
+        "JM1111111 https://[example.com/anything "
+        "https://[18comic.vip/album/3333333 "
+        "https://18comic.vip/album/2222222 JM4444444"
+    ) == ["1111111", "2222222", "4444444"]
+
+
 def test_extract_jm_ids_accepts_token_forms() -> None:
     assert extract_jm_ids("jm1234567") == ["1234567"]
     assert extract_jm_ids("看看 JM 1114751 吧") == ["1114751"]
@@ -141,3 +162,25 @@ def test_extract_from_json_message_skips_broken_json_body() -> None:
     segments = [{"type": "json", "data": {"data": "{not json"}}]
 
     assert extract_from_json_message(segments) == []
+
+
+def test_extract_from_json_message_keeps_ids_after_malformed_url() -> None:
+    segments: list[dict[str, Any]] = [
+        {
+            "type": "json",
+            "data": {
+                "data": json.dumps(
+                    {
+                        "bad_url": "https://[18comic.vip/album/1114751",
+                        "text": "JM2222222",
+                    }
+                )
+            },
+        },
+        {
+            "type": "json",
+            "data": {"data": json.dumps({"url": "https://18comic.vip/album/3333333"})},
+        },
+    ]
+
+    assert extract_from_json_message(segments) == ["2222222", "3333333"]
diff --git a/tests/test_jm_tool.py b/tests/test_jm_tool.py
index a89ee514..66f5823b 100644
--- a/tests/test_jm_tool.py
+++ b/tests/test_jm_tool.py
@@ -58,6 +58,22 @@ async def test_jm_book_info_mode_rejects_bad_book_id(
     fetch.assert_not_awaited()
 
 
+@pytest.mark.asyncio
+async def test_jm_book_rejects_malformed_url_without_fetching(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    fetch = AsyncMock()
+    monkeypatch.setattr(jm_tool, "jm_book_info_text", fetch)
+
+    result = await execute(
+        {"book_id": "https://[18comic.vip/album/350234", "output_mode": "info"},
+        _context(),
+    )
+
+    assert "无法解析禁漫车号" in result
+    fetch.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_jm_book_uid_mode_registers_attachment(
     monkeypatch: pytest.MonkeyPatch,

From d70d4cba62b0aff774ae7ca4c49ae834a058db13 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:27:22 +0800
Subject: [PATCH 004/121] fix(deploy): defer writes and map interpreter files
 for host Docker

Accept UTF-8 BOM configuration and preserve cancellation without side effects.
---
 docs/deployment.md                            |  2 +
 docs/docker-deploy.md                         |  6 +-
 src/Undefined/deploy/config_patch.py          |  2 +-
 src/Undefined/deploy/generate.py              | 11 +++
 src/Undefined/deploy/runner.py                | 55 ++++++------
 .../deploy/templates/compose.bot.yaml         |  4 +
 .../skills/tools/python_interpreter/README.md | 17 +++-
 .../tools/python_interpreter/handler.py       | 51 ++++++++---
 tests/test_deploy_config_patch.py             | 21 +++++
 tests/test_deploy_generate.py                 | 37 ++++++++
 tests/test_deploy_runner.py                   | 60 +++++++++++++
 tests/test_python_interpreter_handler.py      | 90 +++++++++++++++++++
 12 files changed, 314 insertions(+), 42 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index ae437ef1..5c75d6b2 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -201,6 +201,8 @@ uv run deploy up
 
 部署结束后，按终端显示的地址和密码进入 WebUI，填写模型 API 与 QQ 身份配置，到 NapCat 扫码登录后，再返回 WebUI 点击“启动机器人”。`container` 与 `host` 模式都会将 `[webui].autostart_bot` 设为 `false`、`[onebot].file_send_mode` 设为 `"stream"`。**环境准备、首次配置、远程访问和常见问题请直接看 [Docker 一键部署指南](docker-deploy.md)**。
 
+向导在最终确认前只读取配置，取消不会生成文件或初始化子模块；已有 `config.toml` 支持 UTF-8 BOM 编码。`container` 模式还会为 Python 解释器自动映射已共享的 `deploy/data/cache/python_interpreter/`，让宿主 Docker 从正确的宿主路径读取执行文件。手工挂载 Docker socket 的容器需按 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)配置共享路径。
+
 ---
 
 ## pip/uv tool 部署（快速体验）
diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md
index 1843e3ce..2f612f3a 100644
--- a/docs/docker-deploy.md
+++ b/docs/docker-deploy.md
@@ -56,7 +56,7 @@ uv run deploy up
 | 发布端口的绑定地址 | 保持 `127.0.0.1`；在服务器上部署时，访问方法见下文[远程访问](#在自己的电脑上访问服务器) |
 | 是否拉取 NagaAgent 子模块 | 不需要 NagaAgent 代码问答时选“否” |
 
-向导随后会展示配置变更，确认后开始拉取镜像和启动容器。首次运行需要下载依赖与镜像，请等待命令完成。
+向导随后会展示配置变更，最终确认前只读取配置和模板；选择取消不会创建 `config.toml` 或拉取 NagaAgent 子模块。确认后才生成配置、按需初始化子模块、拉取镜像并启动容器。首次运行需要下载依赖与镜像，请等待命令完成。
 
 如需跳过向导，可用 `uv run deploy up --yes` 代替；首次执行采用默认配置，之后执行会沿用上次的部署选择。只想提前查看变更时，可用 `uv run deploy up --dry-run`，它不会写文件或启动容器。
 
@@ -85,7 +85,7 @@ uv run deploy status
 3. 配置 `models.chat`、`models.vision`、`models.agent` 的 API 地址、API Key 和模型名称；其他已启用功能所需的模型也应按配置提示填写。完整要求见 [配置必填项](configuration.md#3-严格模式stricttrue必填项)。
 4. 保存配置并检查校验结果；字段缺失或无效时，按提示补齐。
 
-也可以直接编辑仓库根目录的 `config.toml`。部署工具已填写 OneBot 连接和所选服务的地址，首次部署通常无需再改这些项。**模型 API 和 QQ 身份信息需要你自己填写，容器启动不代表这些配置已完成。**
+也可以直接编辑仓库根目录的 `config.toml`，部署工具与 Bot 一样支持 UTF-8 和 UTF-8 BOM 编码。部署工具已填写 OneBot 连接和所选服务的地址，首次部署通常无需再改这些项。**模型 API 和 QQ 身份信息需要你自己填写，容器启动不代表这些配置已完成。**
 
 ### 扫码登录并测试回复
 
@@ -227,6 +227,8 @@ uv run deploy up --port bot_webui=18787 --port napcat_webui=16099
 
 重新运行向导可以调整模式和可选服务。重复部署会重新生成 Compose 与服务配置，并复用已有有效凭据；对生成文件的手工修改可能被覆盖。修改过 WebUI 密码时，以 `config.toml` 中的当前值为准。
 
+`container` 模式的 Python 解释器使用 `deploy/data/cache/python_interpreter/` 中独立的临时工作目录。部署工具通过容器环境变量传入这份共享目录在 Bot 内和宿主机上的不同路径，使宿主 Docker 能读取脚本、依赖清单和生成的文件；不会共享整个宿主 `/tmp`。`host` 模式继续使用系统临时目录。手工部署容器时的设置方法见 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)。
+
 ### 更新版本
 
 先备份配置与数据，并将仓库更新到要部署的已发布版本，再执行：
diff --git a/src/Undefined/deploy/config_patch.py b/src/Undefined/deploy/config_patch.py
index 25bc229c..2bec12cf 100644
--- a/src/Undefined/deploy/config_patch.py
+++ b/src/Undefined/deploy/config_patch.py
@@ -107,7 +107,7 @@ def load_toml(path: Path) -> dict[str, Any]:
     if not path.is_file():
         return {}
     try:
-        return tomllib.loads(path.read_text(encoding="utf-8"))
+        return tomllib.loads(path.read_text(encoding="utf-8-sig"))
     except tomllib.TOMLDecodeError as exc:
         raise ConfigError(f"{path} 解析失败：{exc}") from exc
     except OSError as exc:
diff --git a/src/Undefined/deploy/generate.py b/src/Undefined/deploy/generate.py
index 5c519a9d..058e62a9 100644
--- a/src/Undefined/deploy/generate.py
+++ b/src/Undefined/deploy/generate.py
@@ -67,6 +67,10 @@
 
 #: 挂进本体容器的宿主机 Docker socket（DooD）。
 DOCKER_SOCKET_ENV = "UNDEFINED_DEPLOY_DOCKER_SOCKET"
+#: Python 解释器在已挂载 data/ 下共享文件；两端路径允许不同。
+PYTHON_INTERPRETER_TMP_SUBDIR = Path("cache") / "python_interpreter"
+PYTHON_INTERPRETER_LOCAL_DIR_ENV = "UNDEFINED_DEPLOY_PYTHON_INTERPRETER_LOCAL_DIR"
+PYTHON_INTERPRETER_HOST_DIR_ENV = "UNDEFINED_DEPLOY_PYTHON_INTERPRETER_HOST_DIR"
 
 
 class GenerateError(RuntimeError):
@@ -264,6 +268,13 @@ def prev(name: str) -> str | None:
         "UNDEFINED_DEPLOY_LXMUSIC2API_UID": str(_current_uid()),
         "UNDEFINED_DEPLOY_LXMUSIC2API_GID": str(_current_gid()),
     }
+    if ctx.mode == catalog.MODE_CONTAINER:
+        env[PYTHON_INTERPRETER_LOCAL_DIR_ENV] = str(
+            Path(CONTAINER_REPO_PATH) / "data" / PYTHON_INTERPRETER_TMP_SUBDIR
+        )
+        env[PYTHON_INTERPRETER_HOST_DIR_ENV] = str(
+            ctx.layout.data_dir / PYTHON_INTERPRETER_TMP_SUBDIR
+        )
 
     # 端口与绑定：默认只绑回环，远程访问需显式改 --port-bind
     for key, spec in catalog.port_specs().items():
diff --git a/src/Undefined/deploy/runner.py b/src/Undefined/deploy/runner.py
index baee85a3..4ca053e5 100644
--- a/src/Undefined/deploy/runner.py
+++ b/src/Undefined/deploy/runner.py
@@ -486,37 +486,21 @@ def run_up(options: dict[str, Any]) -> int:
             _previous_port_bind(previous_state, previous_env)
         ) or _previous_port_bind(previous_state, previous_env)
 
-    # 子模块必须先就绪：能力开关与目标代码由同一问决定
-    if nagaagent_enabled and not dry_run:
-        try:
-            result = nagaagent.ensure_submodule(repo)
-        except RuntimeError as exc:
-            print(f"错误：{exc}")
-            return EXIT_ERROR
-        print(
-            "NagaAgent 子模块："
-            + ("已就绪" if result == "already-ready" else "拉取完成")
-        )
-
     # 端口与绑定地址必须像凭据一样跨次复用：否则重跑 up 会静默把 --port /
     # --port-bind 退回默认值（远程访问会无声中断）。
     ports = _resolve_ports(previous_state, previous_env)
     ports.update(options.get("port_overrides") or {})
 
-    # 全新部署时必须先落一份完整配置：否则只渲染被 patch 的几个键，
-    # 生成出来的 config.toml 没有 [models]/[core]，用户无从填写模型端。
-    # dry-run 不落盘，因此跳过创建，只按现有（可能为空）配置推导。
-    if not dry_run:
-        try:
-            if config_patch.ensure_config_file(
-                repo / "config.toml", repo / "config.toml.example"
-            ):
-                print("config.toml：已从 config.toml.example 生成")
-        except config_patch.ConfigError as exc:
-            print(f"错误：{exc}")
-            return EXIT_ERROR
-
-    existing_config = config_patch.load_toml(repo / "config.toml")
+    # 确认前只读现有配置或模板：取消和 dry-run 都不创建配置、不拉取子模块。
+    config_path = repo / "config.toml"
+    example_path = repo / "config.toml.example"
+    try:
+        existing_config = config_patch.load_toml(
+            config_path if config_path.is_file() else example_path
+        )
+    except config_patch.ConfigError as exc:
+        print(f"错误：{exc}")
+        return EXIT_ERROR
 
     ctx = generate.GenerateContext(
         repo=repo,
@@ -564,6 +548,25 @@ def run_up(options: dict[str, Any]) -> int:
             print("已取消，未改动任何文件。")
             return EXIT_OK
 
+    if not dry_run:
+        # 子模块先就绪，再开启能力；所有写入都必须在最终确认之后。
+        if nagaagent_enabled:
+            try:
+                result = nagaagent.ensure_submodule(repo)
+            except RuntimeError as exc:
+                print(f"错误：{exc}")
+                return EXIT_ERROR
+            print(
+                "NagaAgent 子模块："
+                + ("已就绪" if result == "already-ready" else "拉取完成")
+            )
+        try:
+            if config_patch.ensure_config_file(config_path, example_path):
+                print("config.toml：已从 config.toml.example 生成")
+        except config_patch.ConfigError as exc:
+            print(f"错误：{exc}")
+            return EXIT_ERROR
+
     project_name = (
         previous_state.project_name if previous_state else catalog.COMPOSE_PROJECT_NAME
     )
diff --git a/src/Undefined/deploy/templates/compose.bot.yaml b/src/Undefined/deploy/templates/compose.bot.yaml
index 43f0091b..ce81f8b8 100644
--- a/src/Undefined/deploy/templates/compose.bot.yaml
+++ b/src/Undefined/deploy/templates/compose.bot.yaml
@@ -19,6 +19,10 @@ services:
     networks:
       - undefined-deploy
     working_dir: /data/Undefined
+    environment:
+      # Docker bind mount 来源由宿主 daemon 解析；不可把 Bot 容器的 /tmp 直接传给它。
+      UNDEFINED_PYTHON_INTERPRETER_LOCAL_DIR: ${UNDEFINED_DEPLOY_PYTHON_INTERPRETER_LOCAL_DIR}
+      UNDEFINED_PYTHON_INTERPRETER_HOST_DIR: ${UNDEFINED_DEPLOY_PYTHON_INTERPRETER_HOST_DIR}
     ports:
       - "${UNDEFINED_DEPLOY_PORT_BOT_WEBUI_BIND}:${UNDEFINED_DEPLOY_PORT_BOT_WEBUI}:8787"
       - "${UNDEFINED_DEPLOY_PORT_BOT_API_BIND}:${UNDEFINED_DEPLOY_PORT_BOT_API}:8788"
diff --git a/src/Undefined/skills/tools/python_interpreter/README.md b/src/Undefined/skills/tools/python_interpreter/README.md
index f934f487..92ada344 100644
--- a/src/Undefined/skills/tools/python_interpreter/README.md
+++ b/src/Undefined/skills/tools/python_interpreter/README.md
@@ -4,7 +4,7 @@
 
 限制说明：
 - 主执行容器**无法访问网络**且只读（`--network none --read-only`）
-- 无法访问宿主机文件系统（`send_files` 除外，见下）
+- 仅挂载本次执行的临时工作目录到 `/tmp`；`send_files` 只能回传该目录内的产物
 
 ## 参数
 
@@ -14,6 +14,21 @@
 | `libraries` | list[string] | 否 | 需要的第三方库；指定后容器会先联网执行 `pip install`，再在无网环境运行代码 |
 | `send_files` | list[string] | 否 | 需要回传的容器内 `/tmp/` 产物路径；执行后作为附件返回 |
 
+## 容器内使用宿主 Docker
+
+源码或 `host` 模式下，Bot 与 Docker daemon 使用同一宿主文件系统，工具默认在系统临时目录中创建工作目录。
+
+Bot 本身在容器中且挂载宿主 Docker socket 时，Docker 的 bind mount 来源由宿主 daemon 解析，需要显式映射共享目录的两端路径。`uv run deploy up` 的 `container` 模式自动复用已有 `data/` 挂载，并设置：
+
+| Bot 环境变量 | 一键部署中的值 |
+|---|---|
+| `UNDEFINED_PYTHON_INTERPRETER_LOCAL_DIR` | `/data/Undefined/data/cache/python_interpreter`，Bot 可读写的共享目录 |
+| `UNDEFINED_PYTHON_INTERPRETER_HOST_DIR` | 当前仓库的 `deploy/data/cache/python_interpreter` 绝对路径，宿主 Docker 可见的同一目录 |
+
+手工部署时，同时设置这两个变量为对应的绝对路径，并保证指向同一份共享目录。工具在 Bot 侧创建独立工作目录、写入脚本，向 Docker 传入对应宿主路径，再从 Bot 侧读取输出并清理。不会挂载整个宿主 `/tmp`。更换仓库位置后应重新生成部署配置，避免保留旧的宿主绝对路径。
+
+执行目录在完成后清理；需要回传文件时会保留 30 秒，让附件发送完成。
+
 目录结构：
 - `config.json`：工具定义
 - `handler.py`：执行逻辑
diff --git a/src/Undefined/skills/tools/python_interpreter/handler.py b/src/Undefined/skills/tools/python_interpreter/handler.py
index f23365db..7fdb57e9 100644
--- a/src/Undefined/skills/tools/python_interpreter/handler.py
+++ b/src/Undefined/skills/tools/python_interpreter/handler.py
@@ -18,6 +18,8 @@
 TIMEOUT = 480  # 8 分钟
 TIMEOUT_WITH_LIBS = 600  # 10 分钟（pip 安装需要更多时间）
 OUTPUT_FILE_RETENTION_SECONDS = 30.0
+SHARED_LOCAL_DIR_ENV = "UNDEFINED_PYTHON_INTERPRETER_LOCAL_DIR"
+SHARED_HOST_DIR_ENV = "UNDEFINED_PYTHON_INTERPRETER_HOST_DIR"
 
 # 图片扩展名（内联发送而非文件附件）
 _IMAGE_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"})
@@ -27,6 +29,26 @@
 _PENDING_CLEANUP_TASKS: set[asyncio.Task[None]] = set()
 
 
+def _create_execution_dirs() -> tuple[str, str]:
+    """返回 Bot 本地工作目录与 Docker daemon 可见的 bind mount 来源。"""
+    local_dir = os.getenv(SHARED_LOCAL_DIR_ENV, "").strip()
+    host_dir = os.getenv(SHARED_HOST_DIR_ENV, "").strip()
+    if not local_dir and not host_dir:
+        tmpdir = tempfile.mkdtemp(prefix="pyinterp_")
+        return tmpdir, tmpdir
+    if not local_dir or not host_dir:
+        raise ValueError(
+            f"必须同时配置 {SHARED_LOCAL_DIR_ENV} 和 {SHARED_HOST_DIR_ENV}"
+        )
+    local_root = Path(local_dir)
+    host_root = Path(host_dir)
+    if not local_root.is_absolute() or not host_root.is_absolute():
+        raise ValueError("Python 解释器共享目录必须是绝对路径")
+    local_root.mkdir(parents=True, exist_ok=True)
+    tmpdir = tempfile.mkdtemp(prefix="pyinterp_", dir=local_root)
+    return tmpdir, str(host_root / Path(tmpdir).name)
+
+
 def _get_output_relative_path(container_path: str) -> PurePosixPath | None:
     try:
         relative = PurePosixPath(container_path).relative_to("/tmp")
@@ -172,25 +194,27 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     memory = MEMORY_LIMIT_WITH_LIBS if has_libs else MEMORY_LIMIT
     timeout = TIMEOUT_WITH_LIBS if has_libs else TIMEOUT
 
-    host_tmpdir = tempfile.mkdtemp(prefix="pyinterp_")
+    execution_dir: str | None = None
     defer_cleanup = False
 
     try:
+        local_tmpdir, docker_tmpdir = await asyncio.to_thread(_create_execution_dirs)
+        execution_dir = local_tmpdir
         for fpath in send_files:
-            if _resolve_output_host_path(fpath, host_tmpdir) is None:
+            if _resolve_output_host_path(fpath, local_tmpdir) is None:
                 return f"错误: 输出文件路径必须位于容器 /tmp 目录内: '{fpath}'"
 
-        script_path = os.path.join(host_tmpdir, "_script.py")
+        script_path = os.path.join(local_tmpdir, "_script.py")
         deadline = time.monotonic() + timeout
 
         if has_libs:
             # 单独安装依赖，再以无网络/只读根文件系统执行用户代码。
-            req_path = os.path.join(host_tmpdir, "_requirements.txt")
+            req_path = os.path.join(local_tmpdir, "_requirements.txt")
             with open(req_path, "w", encoding="utf-8") as f:
                 for lib in libraries:
                     f.write(lib + "\n")
             install_timeout = max(deadline - time.monotonic(), 1.0)
-            install_cmd = _build_install_cmd(host_tmpdir, memory)
+            install_cmd = _build_install_cmd(docker_tmpdir, memory)
             install_code, install_stdout, install_stderr = await _run_docker_command(
                 install_cmd,
                 timeout=install_timeout,
@@ -207,7 +231,7 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
 
             exec_timeout = max(deadline - time.monotonic(), 1.0)
             cmd = _build_exec_cmd(
-                host_tmpdir,
+                docker_tmpdir,
                 memory,
                 pythonpath="/tmp/_site_packages",
             )
@@ -215,7 +239,7 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
             # 将代码写入脚本文件（避免 shell 引号转义问题）
             with open(script_path, "w", encoding="utf-8") as f:
                 f.write(code)
-            cmd = _build_exec_cmd(host_tmpdir, memory)
+            cmd = _build_exec_cmd(docker_tmpdir, memory)
             exec_timeout = timeout
 
         logger.info(
@@ -243,7 +267,9 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
                 )
 
             if send_files and exit_code == 0:
-                file_result = await _send_output_files(send_files, host_tmpdir, context)
+                file_result = await _send_output_files(
+                    send_files, local_tmpdir, context
+                )
                 if file_result:
                     parts.append(file_result)
                 defer_cleanup = True
@@ -257,10 +283,11 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
         logger.exception("[Python解释器] 执行出错: %s", e)
         return "执行出错，请检查代码或重试"
     finally:
-        if defer_cleanup:
-            _schedule_output_dir_cleanup(host_tmpdir)
-        else:
-            shutil.rmtree(host_tmpdir, ignore_errors=True)
+        if execution_dir is not None:
+            if defer_cleanup:
+                _schedule_output_dir_cleanup(execution_dir)
+            else:
+                await asyncio.to_thread(shutil.rmtree, execution_dir, True)
 
 
 async def _send_output_files(
diff --git a/tests/test_deploy_config_patch.py b/tests/test_deploy_config_patch.py
index f00b4640..e10362c5 100644
--- a/tests/test_deploy_config_patch.py
+++ b/tests/test_deploy_config_patch.py
@@ -8,6 +8,7 @@
 import pytest
 
 from Undefined.deploy import config_patch
+from Undefined.config.toml_io import load_toml_data
 from Undefined.webui.utils.comment import parse_comment_map
 
 #: 故意写成「已有注释 + 已有用户自定义值 + 嵌套表」的形态，
@@ -63,6 +64,26 @@ def _plan(config_path: Path, desired: dict[str, object]) -> config_patch.PatchPl
     )
 
 
+def test_apply_accepts_bom_config_and_preserves_original_backup(
+    config_dir: tuple[Path, Path, Path],
+) -> None:
+    config, example, backup_dir = config_dir
+    config.write_text(EXAMPLE, encoding="utf-8-sig")
+    original = config.read_bytes()
+    assert config_patch.load_toml(config) == load_toml_data(config, strict=True)
+
+    outcome = config_patch.apply_plan(
+        _plan(config, {"onebot.ws_url": "ws://napcat:3001"}),
+        example_path=example,
+        backup_dir=backup_dir,
+    )
+
+    assert outcome.written is True
+    assert outcome.backup_path is not None
+    assert outcome.backup_path.read_bytes() == original
+    assert config_patch.load_toml(config)["onebot"]["ws_url"] == "ws://napcat:3001"
+
+
 def test_plan_items_report_current_and_about(
     config_dir: tuple[Path, Path, Path],
 ) -> None:
diff --git a/tests/test_deploy_generate.py b/tests/test_deploy_generate.py
index 86f41a83..d43e7d04 100644
--- a/tests/test_deploy_generate.py
+++ b/tests/test_deploy_generate.py
@@ -128,6 +128,43 @@ def test_container_mode_publishes_bot_ports(tmp_path: Path) -> None:
     assert env["UNDEFINED_DEPLOY_PORT_BOT_WEBUI_BIND"] == catalog.DEFAULT_PORT_BIND
 
 
+def test_container_maps_python_interpreter_paths_to_existing_data_mount(
+    tmp_path: Path,
+) -> None:
+    ctx = _ctx(tmp_path)
+    config = generate.build(ctx)
+    bot = _compose_services(config.compose_text)["undefined-bot"]
+    environment = bot["environment"]
+    local_root = Path(config.env[generate.PYTHON_INTERPRETER_LOCAL_DIR_ENV])
+    host_root = Path(config.env[generate.PYTHON_INTERPRETER_HOST_DIR_ENV])
+
+    assert local_root != host_root
+    # 真实 host 来源必须由 data/ 挂载及同一相对路径推出，不能传 Bot 的绝对路径。
+    data_mount = next(
+        volume for volume in bot["volumes"] if volume.endswith(":/data/Undefined/data")
+    )
+    source, target = data_mount.split(":")
+    assert host_root == (ctx.layout.root / source).resolve() / local_root.relative_to(
+        target
+    )
+    assert environment["UNDEFINED_PYTHON_INTERPRETER_LOCAL_DIR"] == (
+        "${" + generate.PYTHON_INTERPRETER_LOCAL_DIR_ENV + "}"
+    )
+    assert environment["UNDEFINED_PYTHON_INTERPRETER_HOST_DIR"] == (
+        "${" + generate.PYTHON_INTERPRETER_HOST_DIR_ENV + "}"
+    )
+    assert not any(volume.endswith(":/tmp") for volume in bot["volumes"])
+
+
+def test_host_mode_leaves_python_interpreter_temp_paths_unchanged(
+    tmp_path: Path,
+) -> None:
+    config = generate.build(_ctx(tmp_path, mode=catalog.MODE_HOST))
+    assert generate.PYTHON_INTERPRETER_LOCAL_DIR_ENV not in config.env
+    assert generate.PYTHON_INTERPRETER_HOST_DIR_ENV not in config.env
+    assert "undefined-bot" not in _compose_services(config.compose_text)
+
+
 def test_unselected_service_ports_are_not_published(tmp_path: Path) -> None:
     env = generate.build(_ctx(tmp_path)).env
     assert "UNDEFINED_DEPLOY_PORT_SEARXNG" not in env
diff --git a/tests/test_deploy_runner.py b/tests/test_deploy_runner.py
index bd12e63d..8b551e6a 100644
--- a/tests/test_deploy_runner.py
+++ b/tests/test_deploy_runner.py
@@ -628,6 +628,66 @@ def test_up_creates_full_config_from_example_on_fresh_clone(
     assert parsed["webui"]["autostart_bot"] is False
 
 
+@pytest.mark.parametrize("existing_config", (False, True))
+def test_cancel_up_writes_nothing_and_does_not_initialize_submodule(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    existing_config: bool,
+) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "config.toml.example").write_text(CONFIG_TOML, encoding="utf-8")
+    if existing_config:
+        (repo / "config.toml").write_text(CONFIG_TOML, encoding="utf-8")
+    before = {path.name: path.read_bytes() for path in repo.iterdir()}
+    answers = iter(("", "", "n"))
+    monkeypatch.setattr(runner, "repo_root", lambda: repo)
+    monkeypatch.setattr(runner, "wizard_enabled", lambda options: True)
+    monkeypatch.setattr(runner.Wizard, "_ask", lambda self, prompt: next(answers))
+
+    def unexpected_side_effect(*args: object, **kwargs: object) -> None:
+        raise AssertionError("取消前不能写入子模块或调用 Docker")
+
+    monkeypatch.setattr(nagaagent, "ensure_submodule", unexpected_side_effect)
+    monkeypatch.setattr(docker_cli, "check_availability", unexpected_side_effect)
+
+    assert runner.run_up(_yes_options(yes=False, dry_run=False, nagaagent=True)) == 0
+    assert {path.name: path.read_bytes() for path in repo.iterdir()} == before
+    assert "已取消，未改动任何文件。" in capsys.readouterr().out
+
+
+def test_up_accepts_bom_config(
+    fake_repo: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_path = fake_repo / "config.toml"
+    config_path.write_text(CONFIG_TOML, encoding="utf-8-sig")
+    _stub_docker(monkeypatch)
+
+    assert runner.run_up(_yes_options(dry_run=False)) == 0
+    assert (
+        tomllib.loads(config_path.read_text())["onebot"]["file_send_mode"] == "stream"
+    )
+
+
+def test_up_reports_invalid_config_before_any_write(
+    fake_repo: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    config_path = fake_repo / "config.toml"
+    config_path.write_text("[broken", encoding="utf-8")
+
+    def unexpected_submodule(*args: object, **kwargs: object) -> None:
+        raise AssertionError("无效配置不能触发子模块写入")
+
+    monkeypatch.setattr(nagaagent, "ensure_submodule", unexpected_submodule)
+    assert runner.run_up(_yes_options(dry_run=False, nagaagent=True)) != 0
+    assert config_path.read_text() == "[broken"
+    assert not (fake_repo / "deploy").exists()
+    assert "解析失败" in capsys.readouterr().out
+
+
 @pytest.mark.parametrize("mode", catalog.DEPLOY_MODES)
 @pytest.mark.parametrize("previous_file_mode", ("local", "url"))
 def test_up_replaces_legacy_startup_and_file_transport_settings(
diff --git a/tests/test_python_interpreter_handler.py b/tests/test_python_interpreter_handler.py
index 6683eb8d..6ba24d52 100644
--- a/tests/test_python_interpreter_handler.py
+++ b/tests/test_python_interpreter_handler.py
@@ -4,6 +4,7 @@
 import os
 import tempfile
 from pathlib import Path
+from typing import Any
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -11,6 +12,12 @@
 from Undefined.skills.tools.python_interpreter import handler as python_handler
 
 
+@pytest.fixture(autouse=True)
+def clear_shared_directory_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(python_handler.SHARED_LOCAL_DIR_ENV, raising=False)
+    monkeypatch.delenv(python_handler.SHARED_HOST_DIR_ENV, raising=False)
+
+
 class _FakeProcess:
     def __init__(self, *, returncode: int = 0) -> None:
         self.returncode = returncode
@@ -76,6 +83,13 @@ async def _fake_create_subprocess_exec(
         *args: str, **kwargs: object
     ) -> _FakeProcess:
         calls.append(tuple(args))
+        source = Path(args[args.index("-v") + 1].removesuffix(":/tmp"))
+        assert source.is_dir()
+        if len(calls) == 1:
+            assert (source / "_requirements.txt").read_text() == "requests\n"
+            assert not (source / "_script.py").exists()
+        else:
+            assert (source / "_script.py").read_text() == "print('hello')"
         return _FakeProcess()
 
     real_mkdtemp = tempfile.mkdtemp
@@ -162,3 +176,79 @@ async def test_cleanup_output_dir_later_removes_directory(tmp_path: Path) -> Non
     await python_handler._cleanup_output_dir_later(str(host_tmpdir), 0)
 
     assert not host_tmpdir.exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("with_libraries", (False, True))
+async def test_shared_directory_uses_daemon_path_and_reads_outputs_locally(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, with_libraries: bool
+) -> None:
+    # 两个名字模拟 bind mount 两端：Bot 和宿主 daemon 路径不同，底层目录相同。
+    host_root = tmp_path / "daemon" / "shared"
+    host_root.mkdir(parents=True)
+    local_root = tmp_path / "bot" / "shared"
+    local_root.parent.mkdir()
+    local_root.symlink_to(host_root, target_is_directory=True)
+    monkeypatch.setenv(python_handler.SHARED_LOCAL_DIR_ENV, str(local_root))
+    monkeypatch.setenv(python_handler.SHARED_HOST_DIR_ENV, str(host_root))
+    mounts: list[Path] = []
+    cleanup_paths: list[str] = []
+
+    async def run_docker(cmd: list[str], *, timeout: float) -> tuple[int, str, str]:
+        source = Path(cmd[cmd.index("-v") + 1].removesuffix(":/tmp"))
+        mounts.append(source)
+        assert source.parent == host_root
+        if "--network" not in cmd:
+            assert (source / "_requirements.txt").read_text() == "requests\n"
+            assert not (source / "_script.py").exists()
+            return 0, "", ""
+        assert (source / "_script.py").read_text() == "print('shared')"
+        (source / "result.txt").write_text("shared output", encoding="utf-8")
+        return 0, "shared\n", ""
+
+    async def send_outputs(
+        files: list[str], execution_dir: str, context: dict[str, Any]
+    ) -> str:
+        assert Path(execution_dir).parent == local_root
+        output = python_handler._resolve_output_host_path(files[0], execution_dir)
+        assert output is not None
+        assert output.read_text() == "shared output"
+        return "已发送: result.txt"
+
+    monkeypatch.setattr(python_handler, "_run_docker_command", run_docker)
+    monkeypatch.setattr(python_handler, "_send_output_files", send_outputs)
+    monkeypatch.setattr(
+        python_handler, "_schedule_output_dir_cleanup", cleanup_paths.append
+    )
+
+    result = await python_handler.execute(
+        {
+            "code": "print('shared')",
+            "libraries": ["requests"] if with_libraries else [],
+            "send_files": ["/tmp/result.txt"],
+        },
+        {},
+    )
+
+    assert result == "shared\n\n已发送: result.txt"
+    assert len(mounts) == (2 if with_libraries else 1)
+    assert len(set(mounts)) == 1
+    assert len(cleanup_paths) == 1
+    await python_handler._cleanup_output_dir_later(cleanup_paths[0], 0)
+    assert not mounts[0].exists()
+
+
+@pytest.mark.parametrize("missing", ("local", "host"))
+def test_shared_directory_requires_both_paths(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, missing: str
+) -> None:
+    name = (
+        python_handler.SHARED_HOST_DIR_ENV
+        if missing == "local"
+        else python_handler.SHARED_LOCAL_DIR_ENV
+    )
+    monkeypatch.setenv(name, str(tmp_path / "shared"))
+
+    with pytest.raises(ValueError, match="必须同时配置"):
+        python_handler._create_execution_dirs()
+    assert not (tmp_path / "shared").exists()

From 5f134c90bef80f3e5d9297806f44cf85c474b1b6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:29:54 +0800
Subject: [PATCH 005/121] docs(development): document the CI coverage gate

---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 45ed82a9..5cc69a56 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -63,7 +63,7 @@ Both main prompt variants and `res/IMPORTANT/each.md` guide replies to add usefu
 `group_analysis.member_activity` distinguishes recency (`member_list`), retrieved window message counts (`history`), and weighted indicators (`hybrid`, default). History-mode timestamps must come from messages inside the selected window. History aggregation uses `try_parse_message_time` and skips invalid timestamps before counting or ranking; `parse_message_time` retains its current-time fallback for existing display callers. Missing/zero `last_sent_time` means unknown, not proof of inactivity or never speaking; last-message time does not indicate current online status. See [the toolset documentation](src/Undefined/skills/toolsets/group_analysis/README.md) for reporting limits.
 
 ## Testing Guidelines
-Write tests as `tests/test_<feature>.py`. Async tests use `pytest-asyncio`. Add or update coverage for behavior changes in APIs, config loading/hot reload, cognitive memory, meme or knowledge flows, and WebUI/runtime routes. If you touch `apps/undefined-console/` or `src/Undefined/webui/static/js/`, run `npm run check` in `apps/undefined-console/` in addition to the Python checks; if you touch `apps/undefined-chat/`, run `npm run check` in `apps/undefined-chat/` (it bundles Vitest unit/e2e suites, so cover changed behavior there). No fixed coverage threshold is configured, so cover touched paths well.
+Write tests as `tests/test_<feature>.py`. Async tests use `pytest-asyncio`. Add or update coverage for behavior changes in APIs, config loading/hot reload, cognitive memory, meme or knowledge flows, and WebUI/runtime routes. If you touch `apps/undefined-console/` or `src/Undefined/webui/static/js/`, run `npm run check` in `apps/undefined-console/` in addition to the Python checks; if you touch `apps/undefined-chat/`, run `npm run check` in `apps/undefined-chat/` (it bundles Vitest unit/e2e suites, so cover changed behavior there). CI runs `pytest --cov --cov-report=term` with the 65% minimum configured in `pyproject.toml`; cover touched paths well in addition to satisfying this overall gate.
 
 ## Commit & Pull Request Guidelines
 Recent history follows Conventional Commits with optional scopes, for example `fix(webui): refine launcher return flow` and `feat(commands): add /version (/v) slash command`. Keep commit subjects imperative and concise. Keep `code/NagaAgent/` syncs separate from local feature work when possible. If you are bumping release versions, prefer `uv run python scripts/bump_version.py <version>` so `pyproject.toml`, `src/Undefined/__init__.py`, and the `package.json` + Tauri config of both `apps/undefined-console/` and `apps/undefined-chat/` stay in sync. For pull requests, include a short impact summary, linked issues, and the commands you ran; attach screenshots for WebUI or Tauri UI changes.

From 9743776079d9bfc8bde88c794f86706b7014ed30 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:32:21 +0800
Subject: [PATCH 006/121] fix(chat): publish history readiness after session
 release

---
 docs/openapi.md                     |  2 +
 src/Undefined/api/routes/chat.py    |  3 +-
 tests/test_runtime_api_chat_jobs.py | 73 +++++++++++++++++++++++++++++
 3 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index 46d635e9..febb77dc 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -584,6 +584,8 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 
 `events` 只包含 `after` 之后的持久事件以及当前运行阶段快照。快照使用当前 `last_seq`，便于刷新或断线后以 `job_id + seq` 轮询续接，但不会推进序号或重复写入历史。
 
+`done`、`error` 或 `cancelled` 终态事件可能早于历史落盘与任务收尾完成。客户端应继续查询 job，直到快照的 `history_finalized = true`，再重载历史、释放会话发送锁；该字段只有在历史已完成且任务已解除会话占用时才为 `true`，与 Runtime 接受下一任务的门槛一致。详情接口与 JSON 事件接口使用相同的完成信号。
+
 Runtime 在同一个 job 条件锁内维护事件、顶层阶段、Agent 阶段和耗时快照，因此 JSON 查询和兼容 SSE 都应看到一致的 job 状态。
 - `GET /api/v1/chat/jobs/{job_id}/events?after=<seq>` 加请求头 `Accept: text/event-stream`：兼容 SSE 订阅；SSE 帧包含 `id: <seq>`，长时间无事件时会发送 keep-alive 注释帧。
 - `POST /api/v1/chat/jobs/{job_id}/cancel`：取消运行中的 job。
diff --git a/src/Undefined/api/routes/chat.py b/src/Undefined/api/routes/chat.py
index 93349c4b..abc3efd6 100644
--- a/src/Undefined/api/routes/chat.py
+++ b/src/Undefined/api/routes/chat.py
@@ -280,7 +280,8 @@ def snapshot(self) -> dict[str, Any]:
             "messages": list(self.outputs),
             "current_agent_stages": self.current_agent_stage_snapshots(now),
             "current_tool_calls": self.current_tool_call_snapshots(now),
-            "history_finalized": self.history_finalized,
+            # 对外完成信号与新任务/历史修改的放行门槛一致。
+            "history_finalized": self.history_finalized and self.done.is_set(),
             "waiting_input": None,
         }
 
diff --git a/tests/test_runtime_api_chat_jobs.py b/tests/test_runtime_api_chat_jobs.py
index 0da2ee17..5ebac482 100644
--- a/tests/test_runtime_api_chat_jobs.py
+++ b/tests/test_runtime_api_chat_jobs.py
@@ -106,6 +106,79 @@ async def _last_webchat_record(server: RuntimeAPIServer) -> dict[str, Any]:
     return cast(dict[str, Any], messages[-1])
 
 
+@pytest.mark.asyncio
+async def test_history_finalized_is_published_only_after_job_releases_session(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def run_chat(ctx: RuntimeAPIContext, *, text: str, send_output: Any) -> str:
+        await send_output(42, "final")
+        return "chat"
+
+    title_entered = asyncio.Event()
+    release_title = asyncio.Event()
+
+    async def schedule_title(conversation_id: str) -> None:
+        title_entered.set()
+        await release_title.wait()
+
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_chat)
+    monkeypatch.setattr(manager, "maybe_schedule_title_generation", schedule_title)
+    job = await manager.create_job("first")
+    detail_request = cast(
+        web.Request,
+        cast(Any, _DummyRequest(match_info={"job_id": job.job_id}, query={})),
+    )
+    events_request = cast(
+        web.Request,
+        cast(
+            Any,
+            _DummyRequest(
+                match_info={"job_id": job.job_id},
+                query={"format": "json"},
+                headers={"Accept": "application/json"},
+            ),
+        ),
+    )
+    try:
+        await asyncio.wait_for(title_entered.wait(), timeout=2.0)
+        # 真实 job 已经落盘，但最终收尾仍占用会话。
+        assert job.status == "done"
+        assert job.history_finalized is True
+        assert not job.done.is_set()
+        assert await manager.has_running_job(job.conversation_id)
+        assert (await manager.snapshot(job))["history_finalized"] is False
+        response = await server._chat_job_detail_handler(detail_request)
+        assert json.loads(response.text or "{}")["history_finalized"] is False
+        events_response = await server._chat_job_events_handler(events_request)
+        assert isinstance(events_response, web.Response)
+        payload = json.loads(events_response.text or "{}")
+        assert payload["job"]["history_finalized"] is False
+        assert any(event["event"] == "done" for event in payload["events"])
+        with pytest.raises(RuntimeError, match="still running"):
+            await manager.create_job("too early", job.conversation_id)
+
+        release_title.set()
+        assert job.task is not None
+        await asyncio.wait_for(job.task, timeout=2.0)
+        assert job.done.is_set()
+        assert not await manager.has_running_job(job.conversation_id)
+        response = await server._chat_job_detail_handler(detail_request)
+        assert json.loads(response.text or "{}")["history_finalized"] is True
+        events_response = await server._chat_job_events_handler(events_request)
+        assert isinstance(events_response, web.Response)
+        assert (
+            json.loads(events_response.text or "{}")["job"]["history_finalized"] is True
+        )
+        next_job = await manager.create_job("next", job.conversation_id)
+        assert next_job.task is not None
+        await asyncio.wait_for(next_job.task, timeout=2.0)
+    finally:
+        release_title.set()
+        await manager.stop()
+
+
 async def _store_runtime_attachment(
     attachment_id: str = "attachment123",
     *,

From 3ffaaf4beddbfadec608de67e98a81d38c94422f Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:34:28 +0800
Subject: [PATCH 007/121] fix(chat): align native pagination and preserve job
 recovery state

---
 .../src-tauri/src/native_tests.rs             |  24 +-
 .../src-tauri/src/runtime_client.rs           |   5 +-
 .../src/chat-store/runtime-contract.test.ts   | 472 ++++++++++++++++++
 .../src/chat-store/store.test.ts              |   2 +
 apps/undefined-chat/src/chat-store/store.ts   | 174 +++++--
 docs/undefined-chat.md                        |   6 +-
 6 files changed, 627 insertions(+), 56 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/runtime-contract.test.ts

diff --git a/apps/undefined-chat/src-tauri/src/native_tests.rs b/apps/undefined-chat/src-tauri/src/native_tests.rs
index 9c81f7f4..78e50909 100644
--- a/apps/undefined-chat/src-tauri/src/native_tests.rs
+++ b/apps/undefined-chat/src-tauri/src/native_tests.rs
@@ -9,7 +9,7 @@ use crate::preview::{
 };
 use crate::runtime_client::{
     build_runtime_url, job_events_url, parse_sse_chunks, runtime_health_from_body_result,
-    RuntimeRequestInput, StartJobEventStreamInput, Utf8ChunkDecoder,
+    ConversationHistoryInput, RuntimeRequestInput, StartJobEventStreamInput, Utf8ChunkDecoder,
 };
 use crate::secret::{
     api_key_status_from_storage, classify_secret_storage, derive_stronghold_key,
@@ -27,6 +27,28 @@ use crate::{
     },
 };
 
+#[test]
+fn history_input_accepts_runtime_numeric_cursors() {
+    for before in [0, 70] {
+        let input: ConversationHistoryInput = serde_json::from_value(serde_json::json!({
+            "conversationId": "default",
+            "limit": 50,
+            "before": before,
+        }))
+        .unwrap();
+        assert_eq!(input.conversation_id, "default");
+        assert_eq!(input.limit, Some(50));
+        assert_eq!(input.before, Some(before));
+    }
+    for input in [
+        serde_json::json!({"conversationId": "default"}),
+        serde_json::json!({"conversationId": "default", "before": null}),
+    ] {
+        let input: ConversationHistoryInput = serde_json::from_value(input).unwrap();
+        assert_eq!(input.before, None);
+    }
+}
+
 #[test]
 fn normalize_runtime_url_removes_trailing_slashes() {
     let value = normalize_runtime_url("http://127.0.0.1:8788///").unwrap();
diff --git a/apps/undefined-chat/src-tauri/src/runtime_client.rs b/apps/undefined-chat/src-tauri/src/runtime_client.rs
index 920efcdb..5f129464 100644
--- a/apps/undefined-chat/src-tauri/src/runtime_client.rs
+++ b/apps/undefined-chat/src-tauri/src/runtime_client.rs
@@ -92,7 +92,7 @@ pub struct ConversationHistoryInput {
     #[serde(default)]
     pub limit: Option<u32>,
     #[serde(default)]
-    pub before: Option<String>,
+    pub before: Option<u64>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
@@ -495,8 +495,7 @@ pub async fn get_history(
         path.push_str(&format!("&limit={limit}"));
     }
     if let Some(before) = input.before {
-        path.push_str("&before=");
-        path.push_str(&urlencoding::encode(&before));
+        path.push_str(&format!("&before={before}"));
     }
     request_json_command(
         &app,
diff --git a/apps/undefined-chat/src/chat-store/runtime-contract.test.ts b/apps/undefined-chat/src/chat-store/runtime-contract.test.ts
new file mode 100644
index 00000000..15d822ef
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/runtime-contract.test.ts
@@ -0,0 +1,472 @@
+import { invoke } from "@tauri-apps/api/core";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createTauriRuntimeClient } from "../runtime-client/tauri";
+import { event, historyItem, job, runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+
+function runtimeJob(overrides: Record<string, unknown> = {}) {
+	return {
+		job_id: "job-1",
+		conversation_id: "default",
+		status: "running",
+		reply: "",
+		messages: [],
+		last_seq: 0,
+		current_tool_calls: [],
+		history_finalized: false,
+		...overrides,
+	};
+}
+
+describe("Runtime job contract through the native client", () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+		vi.useFakeTimers();
+	});
+	afterEach(() => {
+		vi.clearAllTimers();
+		vi.useRealTimers();
+	});
+
+	test("fallback preserves the timeline and completed calls without double counting snapshot text", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		const running = job();
+		vi.mocked(invoke).mockResolvedValue({
+			status: 200,
+			ok: true,
+			body: {
+				job: runtimeJob({
+					reply: "你好\n\n世界",
+					messages: ["你好", "世界"],
+					last_seq: 4,
+				}),
+				after: 3,
+				last_seq: 4,
+				events: [
+					{
+						seq: 4,
+						event: "message",
+						payload: {
+							job_id: "job-1",
+							conversation_id: "default",
+							content: "世界",
+						},
+					},
+				],
+			},
+		});
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			event({ seq: 1, event: "message", payload: { content: "你好" } }),
+			event({
+				seq: 2,
+				event: "tool_start",
+				payload: { webchat_call_id: "search-1", name: "search" },
+			}),
+			event({
+				seq: 3,
+				event: "tool_end",
+				payload: {
+					webchat_call_id: "search-1",
+					ok: true,
+					result_preview: "结果",
+				},
+			}),
+		]);
+		store.handleRuntimeStatus({
+			subscriptionId: "sub-1",
+			jobId: "job-1",
+			status: "error",
+			detail: "SSE disconnected",
+		});
+		await vi.waitFor(() => {
+			expect(store.getSnapshot().activeJobsByConversation.default?.reply).toBe(
+				"你好\n\n世界",
+			);
+		});
+		const active = store.getSnapshot().activeJobsByConversation.default;
+		expect(active?.currentTimeline).toEqual([
+			{ type: "message", seq: 1, content: "你好" },
+			{ type: "call", seq: 2, callId: "search-1" },
+			{ type: "message", seq: 4, content: "世界" },
+		]);
+		expect(active?.currentToolCalls[0]).toMatchObject({
+			id: "search-1",
+			status: "done",
+			resultPreview: "结果",
+		});
+		expect(invoke).toHaveBeenCalledWith("fetch_job_events_json", {
+			input: { jobId: "job-1", afterSeq: 3, conversationId: "default" },
+		});
+		await vi.advanceTimersByTimeAsync(1000);
+		expect(store.getSnapshot().activeJobsByConversation.default?.reply).toBe(
+			"你好\n\n世界",
+		);
+		expect(
+			store.getSnapshot().activeJobsByConversation.default?.currentTimeline,
+		).toEqual(active?.currentTimeline);
+	});
+
+	test.each(["sse", "json"])(
+		"%s terminal delivery waits for history_finalized before releasing the job and reloading history",
+		async (transport) => {
+			const nativeClient = createTauriRuntimeClient();
+			const running = job();
+			const terminalEvent = {
+				seq: 1,
+				event: "done",
+				payload: {
+					job_id: "job-1",
+					conversation_id: "default",
+					status: "done",
+				},
+			};
+			vi.mocked(invoke)
+				.mockResolvedValueOnce({
+					status: 200,
+					ok: true,
+					body: {
+						job: runtimeJob({ status: "done", last_seq: 1 }),
+						events: [terminalEvent],
+					},
+				})
+				.mockResolvedValueOnce({
+					status: 200,
+					ok: true,
+					body: {
+						job: runtimeJob({
+							status: "done",
+							last_seq: 1,
+							history_finalized: true,
+						}),
+						events: [],
+					},
+				});
+			const client = runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+				fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			if (transport === "sse") {
+				store.applyRuntimeEvents("job-1", [terminalEvent]);
+				await vi.advanceTimersByTimeAsync(1000);
+			} else {
+				store.handleRuntimeStatus({
+					subscriptionId: "sub-1",
+					jobId: "job-1",
+					status: "error",
+					detail: "closed",
+				});
+				await vi.waitFor(() => expect(invoke).toHaveBeenCalledTimes(1));
+			}
+			expect(client.getHistory).toHaveBeenCalledTimes(1);
+			expect(store.getSnapshot().jobConversationById["job-1"]).toBe("default");
+			expect(
+				store.getSnapshot().activeJobsByConversation.default?.historyFinalized,
+			).toBe(false);
+			store.updateDraft("default", "下一条");
+			await store.sendSelectedMessage();
+			expect(client.sendMessage).not.toHaveBeenCalled();
+			await vi.advanceTimersByTimeAsync(1000);
+			expect(client.getHistory).toHaveBeenCalledTimes(2);
+			expect(client.stopJobEventStream).toHaveBeenCalledWith("sub-1");
+			expect(
+				store.getSnapshot().activeJobsByConversation.default,
+			).toBeUndefined();
+			expect(store.getSnapshot().jobConversationById["job-1"]).toBeUndefined();
+			expect(store.getSnapshot().connectionState).toBe("connected");
+		},
+	);
+
+	test("an accepted message keeps its history and empty draft when native SSE startup rejects", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		vi.mocked(invoke).mockImplementation(async (command) => {
+			if (command === "start_job_event_stream") {
+				throw new Error("native subscription failed");
+			}
+			return {
+				status: command === "send_message" ? 202 : 200,
+				ok: true,
+				body:
+					command === "send_message"
+						? runtimeJob()
+						: { job: runtimeJob(), events: [] },
+			};
+		});
+		const client = runtimeClientStub({
+			sendMessage: nativeClient.sendMessage,
+			startJobEventStream: nativeClient.startJobEventStream,
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "已经发送");
+		await store.sendSelectedMessage();
+		await vi.waitFor(() =>
+			expect(invoke).toHaveBeenCalledWith("fetch_job_events_json", {
+				input: { jobId: "job-1", afterSeq: 0, conversationId: "default" },
+			}),
+		);
+		expect(store.getSnapshot().draftsByConversation.default).toBe("");
+		expect(store.getSnapshot().sendError).toBeNull();
+		expect(store.getSnapshot().connectionState).toBe("json_fallback");
+		expect(store.getSnapshot().historyByConversation.default?.items).toEqual([
+			expect.objectContaining(
+				historyItem({
+					content: "已经发送",
+					timestamp: expect.any(String),
+					messageId: expect.any(String),
+				}),
+			),
+		]);
+		expect(store.getSnapshot().activeJobsByConversation.default?.jobId).toBe(
+			"job-1",
+		);
+	});
+
+	test.each(["response", "error"])(
+		"ignores a late old-job %s after finalization and a new send",
+		async (completion) => {
+			const nativeClient = createTauriRuntimeClient();
+			let resolveOld!: (value: unknown) => void;
+			let rejectOld!: (reason: Error) => void;
+			const pending = new Promise((resolve, reject) => {
+				resolveOld = resolve;
+				rejectOld = reject;
+			});
+			vi.mocked(invoke)
+				.mockReturnValueOnce(pending)
+				.mockResolvedValueOnce({
+					status: 200,
+					ok: true,
+					body: {
+						job: runtimeJob({
+							status: "done",
+							last_seq: 1,
+							history_finalized: true,
+						}),
+						events: [],
+					},
+				});
+			const running = job();
+			const client = runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+				fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+				sendMessage: vi.fn(async () => job({ jobId: "job-new" })),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			const broken = {
+				subscriptionId: "sub-1",
+				jobId: "job-1",
+				status: "error",
+				detail: "closed",
+			};
+			store.handleRuntimeStatus(broken);
+			store.handleRuntimeStatus(broken);
+			await vi.waitFor(() =>
+				expect(
+					store.getSnapshot().activeJobsByConversation.default,
+				).toBeUndefined(),
+			);
+			store.updateDraft("default", "新任务");
+			await store.sendSelectedMessage();
+			if (completion === "response") {
+				resolveOld({
+					status: 200,
+					ok: true,
+					body: { job: runtimeJob(), events: [] },
+				});
+			} else {
+				rejectOld(new Error("old request failed"));
+			}
+			await vi.advanceTimersByTimeAsync(0);
+			expect(store.getSnapshot().activeJobsByConversation.default?.jobId).toBe(
+				"job-new",
+			);
+			expect(store.getSnapshot().jobConversationById["job-1"]).toBeUndefined();
+			expect(store.getSnapshot().connectionState).toBe("streaming");
+			store.applyRuntimeEvents("job-1", [
+				{ seq: 2, event: "done", payload: { conversation_id: "default" } },
+			]);
+			expect(store.getSnapshot().activeJobsByConversation.default?.jobId).toBe(
+				"job-new",
+			);
+		},
+	);
+
+	test("an older concurrent response cannot replace the latest same-job snapshot", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		let resolveOld!: (value: unknown) => void;
+		const pending = new Promise((resolve) => {
+			resolveOld = resolve;
+		});
+		vi.mocked(invoke)
+			.mockReturnValueOnce(pending)
+			.mockResolvedValueOnce({
+				status: 200,
+				ok: true,
+				body: {
+					job: runtimeJob({ reply: "已有\n\n新增", last_seq: 2 }),
+					events: [{ seq: 2, event: "message", payload: { content: "新增" } }],
+				},
+			});
+		const running = job();
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			{ seq: 1, event: "message", payload: { content: "已有" } },
+		]);
+		const broken = {
+			subscriptionId: "sub-1",
+			jobId: "job-1",
+			status: "error",
+			detail: "closed",
+		};
+		store.handleRuntimeStatus(broken);
+		store.handleRuntimeStatus(broken);
+		await vi.waitFor(() =>
+			expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(2),
+		);
+		const latest = store.getSnapshot().activeJobsByConversation.default;
+		resolveOld({
+			status: 200,
+			ok: true,
+			body: { job: runtimeJob({ reply: "已有", last_seq: 1 }), events: [] },
+		});
+		await vi.advanceTimersByTimeAsync(0);
+		expect(store.getSnapshot().activeJobsByConversation.default).toEqual(
+			latest,
+		);
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(2);
+	});
+
+	test("a snapshot overtaken by SSE keeps the consumed cursor and polls again", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		let resolveOld!: (value: unknown) => void;
+		const pending = new Promise((resolve) => {
+			resolveOld = resolve;
+		});
+		vi.mocked(invoke)
+			.mockReturnValueOnce(pending)
+			.mockResolvedValueOnce({
+				status: 200,
+				ok: true,
+				body: {
+					job: runtimeJob({ reply: "已有\n\n新增", last_seq: 2 }),
+					events: [],
+				},
+			});
+		const running = job();
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			{ seq: 1, event: "message", payload: { content: "已有" } },
+		]);
+		store.handleRuntimeStatus({
+			subscriptionId: "sub-1",
+			jobId: "job-1",
+			status: "error",
+			detail: "closed",
+		});
+		store.applyRuntimeEvents("job-1", [
+			{ seq: 2, event: "message", payload: { content: "新增" } },
+		]);
+		const latest = store.getSnapshot().activeJobsByConversation.default;
+		resolveOld({
+			status: 200,
+			ok: true,
+			body: { job: runtimeJob({ reply: "已有", last_seq: 1 }), events: [] },
+		});
+		await vi.advanceTimersByTimeAsync(0);
+		expect(store.getSnapshot().activeJobsByConversation.default).toEqual(
+			latest,
+		);
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(2);
+		await vi.advanceTimersByTimeAsync(1000);
+		expect(invoke).toHaveBeenLastCalledWith("fetch_job_events_json", {
+			input: { jobId: "job-1", afterSeq: 2, conversationId: "default" },
+		});
+		expect(store.getSnapshot().activeJobsByConversation.default?.reply).toBe(
+			"已有\n\n新增",
+		);
+		expect(
+			store.getSnapshot().activeJobsByConversation.default?.currentTimeline,
+		).toEqual(latest?.currentTimeline);
+	});
+
+	test("cancellation keeps the real event cursor so its finalized snapshot can finish", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		vi.mocked(invoke)
+			.mockResolvedValueOnce({
+				status: 200,
+				ok: true,
+				body: runtimeJob({ status: "cancelled", last_seq: 4 }),
+			})
+			.mockResolvedValueOnce({
+				status: 200,
+				ok: true,
+				body: {
+					job: runtimeJob({
+						status: "cancelled",
+						last_seq: 4,
+						history_finalized: true,
+					}),
+					events: [
+						{
+							seq: 4,
+							event: "error",
+							payload: {
+								job_id: "job-1",
+								conversation_id: "default",
+								error: "cancelled",
+							},
+						},
+					],
+				},
+			});
+		const running = job();
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+			cancelJob: nativeClient.cancelJob,
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			{ seq: 3, event: "message", payload: { content: "取消前回复" } },
+		]);
+		await store.cancelJob("job-1");
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(3);
+		expect(store.getSnapshot().activeJobsByConversation.default?.status).toBe(
+			"cancelled",
+		);
+		expect(client.getHistory).toHaveBeenCalledTimes(1);
+		await vi.advanceTimersByTimeAsync(1000);
+		expect(invoke).toHaveBeenLastCalledWith("fetch_job_events_json", {
+			input: { jobId: "job-1", afterSeq: 3, conversationId: "default" },
+		});
+		expect(
+			store.getSnapshot().activeJobsByConversation.default,
+		).toBeUndefined();
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(4);
+		expect(client.getHistory).toHaveBeenCalledTimes(2);
+	});
+});
diff --git a/apps/undefined-chat/src/chat-store/store.test.ts b/apps/undefined-chat/src/chat-store/store.test.ts
index aeb4f08a..9e2f804e 100644
--- a/apps/undefined-chat/src/chat-store/store.test.ts
+++ b/apps/undefined-chat/src/chat-store/store.test.ts
@@ -383,6 +383,7 @@ describe("chat store", () => {
 			jobId: "job-1",
 			conversationId: "default",
 			status: "done",
+			historyFinalized: true,
 			lastSeq: 2,
 		});
 		const client = runtimeClientStub({
@@ -455,6 +456,7 @@ describe("chat store", () => {
 			jobId: "job-1",
 			conversationId: "default",
 			status: "cancelled",
+			historyFinalized: true,
 			lastSeq: 4,
 		});
 		const client = runtimeClientStub({
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 6202eebc..184cdee2 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -168,7 +168,9 @@ function withoutConversationJob(
 
 export function isJobRunning(job: ChatJob | null | undefined): boolean {
 	return Boolean(
-		job && !["done", "error", "cancelled"].includes(job.status.toLowerCase()),
+		job &&
+			(!["done", "error", "cancelled"].includes(job.status.toLowerCase()) ||
+				!job.historyFinalized),
 	);
 }
 
@@ -672,6 +674,8 @@ export function createChatStore({
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
 	/** 每个 job 当前的 JSON 轮询退避间隔（ms），随连续失败指数增长、成功后重置 */
 	const fallbackBackoffByJob = new Map<string, number>();
+	const latestFallbackRequestByJob = new Map<string, number>();
+	let fallbackRequestGeneration = 0;
 	let unlistenRuntimeSse: (() => void) | null = null;
 	/** bootstrap 重入保护：已在进行中的 bootstrap promise，避免并发重入导致 SSE 监听泄漏 */
 	let inFlightBootstrap: Promise<void> | null = null;
@@ -706,6 +710,7 @@ export function createChatStore({
 			clearTimeout(timer);
 		}
 		fallbackTimersByJob.clear();
+		latestFallbackRequestByJob.clear();
 	}
 
 	async function loadHistory(conversationId: string): Promise<void> {
@@ -737,13 +742,18 @@ export function createChatStore({
 		if (subscriptionsByJob.has(job.jobId)) {
 			return;
 		}
-		const subscription = await client.startJobEventStream({
-			jobId: job.jobId,
-			afterSeq: state.eventCursorByJob[job.jobId] ?? job.lastSeq,
-			conversationId: job.conversationId,
-		});
-		if (subscription.subscriptionId) {
-			subscriptionsByJob.set(job.jobId, subscription.subscriptionId);
+		try {
+			const subscription = await client.startJobEventStream({
+				jobId: job.jobId,
+				afterSeq: state.eventCursorByJob[job.jobId] ?? job.lastSeq,
+				conversationId: job.conversationId,
+			});
+			if (subscription.subscriptionId) {
+				subscriptionsByJob.set(job.jobId, subscription.subscriptionId);
+			}
+		} catch {
+			// job 已建立；订阅失败只切换传输方式，不能回滚成功发送的输入。
+			fetchJobEventsFallback(job.jobId);
 		}
 	}
 
@@ -754,6 +764,25 @@ export function createChatStore({
 			fallbackTimersByJob.delete(jobId);
 		}
 		fallbackBackoffByJob.delete(jobId);
+		latestFallbackRequestByJob.delete(jobId);
+	}
+
+	function finishJob(jobId: string, conversationId: string): void {
+		const active = state.activeJobsByConversation[conversationId];
+		if (active && active.jobId !== jobId) {
+			return;
+		}
+		stopFallbackPolling(jobId);
+		const subscriptionId = subscriptionsByJob.get(jobId);
+		if (subscriptionId) {
+			subscriptionsByJob.delete(jobId);
+			void client.stopJobEventStream(subscriptionId);
+		}
+		dispatch({ type: "job/remove", conversationId, jobId });
+		if (Object.keys(state.activeJobsByConversation).length === 0) {
+			dispatch({ type: "connection/set", connectionState: "connected" });
+		}
+		void loadHistory(conversationId);
 	}
 
 	/** 计算并推进某个 job 的下一次轮询退避间隔（指数增长，封顶 JSON_FALLBACK_MAX_MS） */
@@ -779,6 +808,18 @@ export function createChatStore({
 	}
 
 	function fetchJobEventsFallback(jobId: string): void {
+		const conversationId = state.jobConversationById[jobId];
+		if (
+			!conversationId ||
+			state.activeJobsByConversation[conversationId]?.jobId !== jobId
+		) {
+			return;
+		}
+		const requestGeneration = ++fallbackRequestGeneration;
+		latestFallbackRequestByJob.set(jobId, requestGeneration);
+		const isCurrentRequest = (): boolean =>
+			latestFallbackRequestByJob.get(jobId) === requestGeneration &&
+			state.activeJobsByConversation[conversationId]?.jobId === jobId;
 		const timer = fallbackTimersByJob.get(jobId);
 		if (timer) {
 			clearTimeout(timer);
@@ -789,29 +830,51 @@ export function createChatStore({
 			.fetchJobEventsJson({
 				jobId,
 				afterSeq: state.eventCursorByJob[jobId] ?? 0,
-				conversationId: state.jobConversationById[jobId],
+				conversationId,
 			})
 			.then((response) => {
+				if (!isCurrentRequest()) {
+					return;
+				}
+				const active = state.activeJobsByConversation[conversationId];
+				const consumedSeq = Math.max(
+					state.eventCursorByJob[jobId] ?? 0,
+					active?.lastSeq ?? 0,
+				);
+				if (response.job.lastSeq < consumedSeq) {
+					// SSE 可能在请求途中推进；旧快照不能回退正文或阶段，继续拉取即可。
+					scheduleFallbackPolling(jobId);
+					return;
+				}
 				// 拉取成功：重置退避间隔
 				fallbackBackoffByJob.delete(jobId);
-				dispatch({ type: "job/upsert", job: response.job });
+				// 先续接事件保留此前时间线，再应用权威正文快照，避免增量重复计数。
 				applyRuntimeEvents(jobId, response.events);
-				const hasTerminalEvent = response.events.some((item) =>
-					TERMINAL_EVENTS.has(item.event),
-				);
+				const replayedJob =
+					state.activeJobsByConversation[response.job.conversationId];
+				dispatch({
+					type: "job/upsert",
+					job: {
+						...response.job,
+						currentTimeline: replayedJob?.currentTimeline ?? [],
+						// Runtime 运行快照只含未结束调用，完整调用树由事件回放保留。
+						currentToolCalls:
+							replayedJob?.currentToolCalls ?? response.job.currentToolCalls,
+					},
+				});
 				if (isJobRunning(response.job)) {
 					scheduleFallbackPolling(jobId, JSON_FALLBACK_BASE_MS);
-				} else if (!hasTerminalEvent && response.job.conversationId) {
-					void loadHistory(response.job.conversationId);
-					dispatch({ type: "connection/set", connectionState: "connected" });
+				} else if (response.job.conversationId) {
+					finishJob(jobId, response.job.conversationId);
 				}
 			})
 			.catch(() => {
+				if (!isCurrentRequest()) {
+					return;
+				}
 				// 单次失败不直接放弃：仅当该 job 仍是活跃任务时按指数退避继续重试，
 				// 否则停止轮询。连接状态保持 json_fallback（仍在尝试），而非直接 disconnected。
-				const conversationId = state.jobConversationById[jobId];
 				const stillActive =
-					conversationId != null &&
 					state.activeJobsByConversation[conversationId]?.jobId === jobId;
 				if (stillActive) {
 					scheduleFallbackPolling(jobId, nextFallbackDelay(jobId));
@@ -891,7 +954,10 @@ export function createChatStore({
 			if (selected) {
 				await loadHistory(selected);
 			}
-			if (activeJobs.jobs.length > 0) {
+			if (
+				activeJobs.jobs.length > 0 &&
+				state.connectionState !== "json_fallback"
+			) {
 				dispatch({ type: "connection/set", connectionState: "streaming" });
 			}
 		} catch (err) {
@@ -1006,16 +1072,6 @@ export function createChatStore({
 		dispatch({ type: "draft/set", conversationId, draft });
 	}
 
-	function latestEventSeq(jobId: string): number {
-		const cursor = state.eventCursorByJob[jobId] ?? 0;
-		const events = state.eventsByJob[jobId] ?? [];
-		const lastEventSeq = events.reduce(
-			(maxSeq, item) => Math.max(maxSeq, item.seq),
-			0,
-		);
-		return Math.max(cursor, lastEventSeq);
-	}
-
 	async function sendSelectedMessage(): Promise<void> {
 		// in-flight 锁：从点击到 job 建立期间阻止重复发送，
 		// 避免快速双击重复插入乐观消息 / 重复请求后端
@@ -1115,19 +1171,29 @@ export function createChatStore({
 
 	async function cancelJob(jobId: string): Promise<void> {
 		const conversationId = state.jobConversationById[jobId];
+		if (!conversationId) {
+			return;
+		}
 		try {
 			const cancelled = await client.cancelJob(jobId);
-			dispatch({ type: "job/upsert", job: cancelled });
-			applyRuntimeEvents(jobId, [
-				{
-					seq: Math.max(latestEventSeq(jobId), cancelled.lastSeq) + 1,
-					event: "cancelled",
-					payload: {
-						job_id: jobId,
-						conversation_id: cancelled.conversationId || conversationId,
-					},
+			const current = state.activeJobsByConversation[conversationId];
+			if (current?.jobId !== jobId) {
+				return;
+			}
+			dispatch({
+				type: "job/upsert",
+				job: {
+					...cancelled,
+					currentTimeline: current.currentTimeline,
+					currentToolCalls: current.currentToolCalls,
 				},
-			]);
+			});
+			// 取消响应不是增量事件，不伪造序号；真正终态由 Runtime 游标续接。
+			if (isJobRunning(cancelled)) {
+				scheduleFallbackPolling(jobId);
+			} else {
+				finishJob(jobId, conversationId);
+			}
 		} catch (err) {
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		}
@@ -1432,22 +1498,28 @@ export function createChatStore({
 			}
 		}
 
-		// 终态事件：清理 job 并重载历史
-		const doneEvent = events.find((item) =>
-			["done", "error", "cancelled"].includes(item.event),
+		// 终态事件先保留会话和展示状态，确认 Runtime 历史落盘后再释放发送锁。
+		const doneEvent = events.find(
+			(item) => item.seq > prevCursor && TERMINAL_EVENTS.has(item.event),
 		);
 		if (doneEvent && conversationId) {
-			stopFallbackPolling(jobId);
-			const subscriptionId = subscriptionsByJob.get(jobId);
-			if (subscriptionId) {
-				subscriptionsByJob.delete(jobId);
-				void client.stopJobEventStream(subscriptionId);
+			const currentJob = state.activeJobsByConversation[conversationId];
+			if (currentJob && currentJob.jobId !== jobId) {
+				return;
 			}
-			dispatch({ type: "job/remove", conversationId, jobId });
-			if (Object.keys(state.activeJobsByConversation).length === 0) {
-				dispatch({ type: "connection/set", connectionState: "connected" });
+			if (currentJob && !currentJob.historyFinalized) {
+				const status =
+					doneEvent.payload.error === "cancelled"
+						? "cancelled"
+						: doneEvent.event;
+				dispatch({
+					type: "job/upsert",
+					job: { ...currentJob, status },
+				});
+				scheduleFallbackPolling(jobId);
+			} else {
+				finishJob(jobId, conversationId);
 			}
-			void loadHistory(conversationId);
 		}
 	}
 
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 557b7b94..44612daf 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -57,7 +57,11 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 事件策略：
 
 - 默认使用 SSE 订阅 job events。
-- SSE error/closed 时使用 `job_id + seq` 调用 JSON events fallback 补齐遗漏事件。
+- SSE error/closed 或原生订阅建立失败时使用 `job_id + seq` 调用 JSON events fallback 补齐遗漏事件；消息已成功创建 job 后，订阅失败不会撤回用户消息或恢复已发送草稿。
+- JSON fallback 先续接增量事件，再应用 Runtime 的完整正文与阶段快照，保留已有消息/工具时间线和已结束调用，避免把快照正文再次累计。
+- 重叠 JSON 请求按 job 身份和请求代次校验；已结束、已被替换的 job 或落后于已消费事件游标的回包会被忽略，避免迟到响应覆盖下一轮任务或回退回复内容。
+- `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。
+- 历史分页的 `before` / `next_before` 是非负数值索引；React 与 Tauri command 使用同一数值契约，首屏不传 `before`。
 - Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs，并重新建立事件订阅。
 - 当前没有公开的 store 方法在 resume 时逐 job 主动补齐；这部分仍依赖 SSE 断线 fallback。
 

From 8d6ca8dc73f41dae6bd89c36a111b013a7cd5760 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:35:32 +0800
Subject: [PATCH 008/121] fix(python-interpreter): clean directories created
 during cancellation

---
 src/Undefined/skills/shared.py                | 12 +++-
 .../skills/tools/python_interpreter/README.md |  2 +-
 .../tools/python_interpreter/handler.py       | 16 ++++-
 tests/test_python_interpreter_handler.py      | 71 +++++++++++++++++++
 4 files changed, 97 insertions(+), 4 deletions(-)

diff --git a/src/Undefined/skills/shared.py b/src/Undefined/skills/shared.py
index 4c12d647..302dc96c 100644
--- a/src/Undefined/skills/shared.py
+++ b/src/Undefined/skills/shared.py
@@ -7,13 +7,23 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from collections.abc import Coroutine
+from typing import TYPE_CHECKING, Any, TypeVar
 
 if TYPE_CHECKING:
     from jmcpy import Genre, SearchTarget, SortBy, SubGenre, TimeRange
 
     from Undefined.jm.searcher import JmListingMode
 
+_ResultT = TypeVar("_ResultT")
+
+
+async def run_cancellation_safe(operation: Coroutine[Any, Any, _ResultT]) -> _ResultT:
+    """复用公共 IO 的取消保护，等待临界区结束后再传播取消。"""
+    from Undefined.utils.io import run_cancellation_safe as run_io_cancellation_safe
+
+    return await run_io_cancellation_safe(operation)
+
 
 def private_access_error(
     runtime_config: Any,
diff --git a/src/Undefined/skills/tools/python_interpreter/README.md b/src/Undefined/skills/tools/python_interpreter/README.md
index 92ada344..11a9a8fd 100644
--- a/src/Undefined/skills/tools/python_interpreter/README.md
+++ b/src/Undefined/skills/tools/python_interpreter/README.md
@@ -27,7 +27,7 @@ Bot 本身在容器中且挂载宿主 Docker socket 时，Docker 的 bind mount
 
 手工部署时，同时设置这两个变量为对应的绝对路径，并保证指向同一份共享目录。工具在 Bot 侧创建独立工作目录、写入脚本，向 Docker 传入对应宿主路径，再从 Bot 侧读取输出并清理。不会挂载整个宿主 `/tmp`。更换仓库位置后应重新生成部署配置，避免保留旧的宿主绝对路径。
 
-执行目录在完成后清理；需要回传文件时会保留 30 秒，让附件发送完成。
+执行目录在完成后清理；需要回传文件时会保留 30 秒，让附件发送完成。创建目录期间收到取消时，会先等待后台创建线程结束，再清理本次目录并传播取消，避免遗留临时工作目录。
 
 目录结构：
 - `config.json`：工具定义
diff --git a/src/Undefined/skills/tools/python_interpreter/handler.py b/src/Undefined/skills/tools/python_interpreter/handler.py
index 7fdb57e9..3f6c2f60 100644
--- a/src/Undefined/skills/tools/python_interpreter/handler.py
+++ b/src/Undefined/skills/tools/python_interpreter/handler.py
@@ -8,6 +8,8 @@
 from pathlib import Path, PurePosixPath
 from typing import Any, Dict
 
+from Undefined.skills.shared import run_cancellation_safe
+
 logger = logging.getLogger(__name__)
 
 # Docker 执行配置
@@ -197,9 +199,17 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     execution_dir: str | None = None
     defer_cleanup = False
 
-    try:
+    async def prepare_execution_dirs() -> tuple[str, str]:
+        nonlocal execution_dir
         local_tmpdir, docker_tmpdir = await asyncio.to_thread(_create_execution_dirs)
+        # 在线程完成后、取消传播前记录所有权，finally 才能清掉创建中的目录。
         execution_dir = local_tmpdir
+        return local_tmpdir, docker_tmpdir
+
+    try:
+        local_tmpdir, docker_tmpdir = await run_cancellation_safe(
+            prepare_execution_dirs()
+        )
         for fpath in send_files:
             if _resolve_output_host_path(fpath, local_tmpdir) is None:
                 return f"错误: 输出文件路径必须位于容器 /tmp 目录内: '{fpath}'"
@@ -287,7 +297,9 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
             if defer_cleanup:
                 _schedule_output_dir_cleanup(execution_dir)
             else:
-                await asyncio.to_thread(shutil.rmtree, execution_dir, True)
+                await run_cancellation_safe(
+                    asyncio.to_thread(shutil.rmtree, execution_dir, True)
+                )
 
 
 async def _send_output_files(
diff --git a/tests/test_python_interpreter_handler.py b/tests/test_python_interpreter_handler.py
index 6ba24d52..9edf1fe8 100644
--- a/tests/test_python_interpreter_handler.py
+++ b/tests/test_python_interpreter_handler.py
@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import os
 import tempfile
+import threading
 from pathlib import Path
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock
@@ -252,3 +254,72 @@ def test_shared_directory_requires_both_paths(
     with pytest.raises(ValueError, match="必须同时配置"):
         python_handler._create_execution_dirs()
     assert not (tmp_path / "shared").exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("shared_directory", (False, True))
+async def test_cancel_during_directory_creation_waits_and_removes_directory(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    shared_directory: bool,
+) -> None:
+    started = threading.Event()
+    release = threading.Event()
+    created_dirs: list[Path] = []
+    real_mkdtemp = tempfile.mkdtemp
+
+    def controlled_mkdtemp(prefix: str, dir: str | Path | None = None) -> str:
+        name = real_mkdtemp(prefix=prefix, dir=dir if dir is not None else tmp_path)
+        path = Path(name)
+        (path / "created.txt").write_text(
+            "created before cancellation", encoding="utf-8"
+        )
+        created_dirs.append(path)
+        started.set()
+        if not release.wait(5):
+            raise RuntimeError("test did not release directory creation")
+        return name
+
+    if shared_directory:
+        root = tmp_path / "shared"
+        monkeypatch.setenv(python_handler.SHARED_LOCAL_DIR_ENV, str(root))
+        monkeypatch.setenv(python_handler.SHARED_HOST_DIR_ENV, str(root))
+    else:
+        monkeypatch.delenv(python_handler.SHARED_LOCAL_DIR_ENV, raising=False)
+        monkeypatch.delenv(python_handler.SHARED_HOST_DIR_ENV, raising=False)
+    monkeypatch.setattr(tempfile, "mkdtemp", controlled_mkdtemp)
+    docker = AsyncMock(
+        side_effect=AssertionError("cancelled creation must not run Docker")
+    )
+    monkeypatch.setattr(python_handler, "_run_docker_command", docker)
+
+    task = asyncio.create_task(
+        python_handler.execute({"code": "print('cancelled')"}, {})
+    )
+    try:
+        assert await asyncio.to_thread(started.wait, 5), (
+            "directory creation did not start"
+        )
+        assert len(created_dirs) == 1
+        assert (created_dirs[0] / "created.txt").is_file()
+
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done(), "cancellation must wait for directory ownership"
+        assert created_dirs[0].is_dir()
+        docker.assert_not_awaited()
+
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=5)
+
+        assert task.cancelled()
+        assert not created_dirs[0].exists()
+        assert not list(tmp_path.rglob("pyinterp_*"))
+        docker.assert_not_awaited()
+    finally:
+        release.set()
+        if not task.done():
+            task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task

From 33b83a19d7b4e1d0c1c9e9cb6ddd7117365b4830 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:38:51 +0800
Subject: [PATCH 009/121] fix(chat): ignore stale cancellation errors and
 stream statuses

---
 .../src/chat-store/runtime-contract.test.ts   | 104 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  17 ++-
 docs/undefined-chat.md                        |   1 +
 3 files changed, 116 insertions(+), 6 deletions(-)

diff --git a/apps/undefined-chat/src/chat-store/runtime-contract.test.ts b/apps/undefined-chat/src/chat-store/runtime-contract.test.ts
index 15d822ef..1ae9a9a4 100644
--- a/apps/undefined-chat/src/chat-store/runtime-contract.test.ts
+++ b/apps/undefined-chat/src/chat-store/runtime-contract.test.ts
@@ -469,4 +469,108 @@ describe("Runtime job contract through the native client", () => {
 		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(4);
 		expect(client.getHistory).toHaveBeenCalledTimes(2);
 	});
+
+	test("an old cancellation rejection cannot overwrite a new job's send error", async () => {
+		const nativeClient = createTauriRuntimeClient();
+		let rejectCancel!: (reason: Error) => void;
+		const pendingCancel = new Promise((_resolve, reject) => {
+			rejectCancel = reject;
+		});
+		vi.mocked(invoke)
+			.mockReturnValueOnce(pendingCancel)
+			.mockResolvedValueOnce({
+				status: 200,
+				ok: true,
+				body: {
+					job: runtimeJob({ status: "done", history_finalized: true }),
+					events: [],
+				},
+			});
+		const running = job();
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+			cancelJob: nativeClient.cancelJob,
+			fetchJobEventsJson: nativeClient.fetchJobEventsJson,
+			sendMessage: vi.fn(async () => job({ jobId: "job-new" })),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		const cancelling = store.cancelJob("job-1");
+		store.handleRuntimeStatus({
+			subscriptionId: "sub-1",
+			jobId: "job-1",
+			status: "error",
+			detail: "closed",
+		});
+		await vi.waitFor(() =>
+			expect(
+				store.getSnapshot().activeJobsByConversation.default,
+			).toBeUndefined(),
+		);
+		store.updateDraft("default", "新任务");
+		await store.sendSelectedMessage();
+		rejectCancel(new Error("old cancellation failed"));
+		await cancelling;
+		expect(store.getSnapshot().sendError).toBeNull();
+		expect(store.getSnapshot().activeJobsByConversation.default?.jobId).toBe(
+			"job-new",
+		);
+	});
+
+	test.each(["connected", "error", "closed"])(
+		"a late old SSE %s status cannot change a new job's connection state",
+		async (status) => {
+			const running = job();
+			const client = runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: running, jobs: [running] })),
+				fetchJobEventsJson: vi.fn(async () => ({
+					job: job({ status: "done", historyFinalized: true }),
+					after: 0,
+					lastSeq: 0,
+					events: [],
+				})),
+				sendMessage: vi.fn(async () => job({ jobId: "job-new" })),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.handleRuntimeStatus({
+				subscriptionId: "sub-1",
+				jobId: "job-1",
+				status: "error",
+				detail: "closed",
+			});
+			await vi.waitFor(() =>
+				expect(
+					store.getSnapshot().activeJobsByConversation.default,
+				).toBeUndefined(),
+			);
+			store.updateDraft("default", "新任务");
+			await store.sendSelectedMessage();
+			// 活跃新任务进入正常 fallback，随后旧通知不能改变这一状态或发起额外请求。
+			const newStatus = {
+				subscriptionId: "sub-new",
+				jobId: "job-new",
+				detail: "closed",
+			};
+			store.handleRuntimeStatus({ ...newStatus, status: "connected" });
+			expect(store.getSnapshot().connectionState).toBe("streaming");
+			vi.mocked(client.fetchJobEventsJson).mockImplementationOnce(
+				() => new Promise(() => {}),
+			);
+			store.handleRuntimeStatus({ ...newStatus, status: "closed" });
+			expect(store.getSnapshot().connectionState).toBe("json_fallback");
+			const requests = vi.mocked(client.fetchJobEventsJson).mock.calls.length;
+			store.handleRuntimeStatus({
+				subscriptionId: "sub-1",
+				jobId: "job-1",
+				status,
+				detail: "late",
+			});
+			expect(store.getSnapshot().connectionState).toBe("json_fallback");
+			expect(client.fetchJobEventsJson).toHaveBeenCalledTimes(requests);
+			expect(store.getSnapshot().activeJobsByConversation.default?.jobId).toBe(
+				"job-new",
+			);
+		},
+	);
 });
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 184cdee2..b62ff717 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -1195,6 +1195,9 @@ export function createChatStore({
 				finishJob(jobId, conversationId);
 			}
 		} catch (err) {
+			if (state.activeJobsByConversation[conversationId]?.jobId !== jobId) {
+				return;
+			}
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		}
 	}
@@ -1528,6 +1531,13 @@ export function createChatStore({
 	}
 
 	function handleRuntimeStatus(status: RuntimeSseStatus): void {
+		const conversationId = state.jobConversationById[status.jobId];
+		if (
+			!conversationId ||
+			state.activeJobsByConversation[conversationId]?.jobId !== status.jobId
+		) {
+			return;
+		}
 		if (status.status === "connected") {
 			dispatch({ type: "connection/set", connectionState: "streaming" });
 			return;
@@ -1537,12 +1547,7 @@ export function createChatStore({
 			return;
 		}
 		if (status.status === "closed") {
-			const conversationId = state.jobConversationById[status.jobId];
-			if (conversationId && state.activeJobsByConversation[conversationId]) {
-				fetchJobEventsFallback(status.jobId);
-				return;
-			}
-			dispatch({ type: "connection/set", connectionState: "connected" });
+			fetchJobEventsFallback(status.jobId);
 		}
 	}
 
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 44612daf..606165f6 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -60,6 +60,7 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 - SSE error/closed 或原生订阅建立失败时使用 `job_id + seq` 调用 JSON events fallback 补齐遗漏事件；消息已成功创建 job 后，订阅失败不会撤回用户消息或恢复已发送草稿。
 - JSON fallback 先续接增量事件，再应用 Runtime 的完整正文与阶段快照，保留已有消息/工具时间线和已结束调用，避免把快照正文再次累计。
 - 重叠 JSON 请求按 job 身份和请求代次校验；已结束、已被替换的 job 或落后于已消费事件游标的回包会被忽略，避免迟到响应覆盖下一轮任务或回退回复内容。
+- 取消请求错误和 SSE 的连接状态通知同样只作用于对应的活跃 job，旧任务的迟到通知不会改写新任务的错误或连接状态。
 - `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。
 - 历史分页的 `before` / `next_before` 是非负数值索引；React 与 Tauri command 使用同一数值契约，首屏不传 `before`。
 - Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs，并重新建立事件订阅。

From 7d93d19b75683aa1c97c601193d3a5fc97ab3286 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 11:59:50 +0800
Subject: [PATCH 010/121] fix(douyin): stop fallback after uncertain delivery
 errors

---
 src/Undefined/douyin/sender.py                |  4 ++
 .../skills/tools/douyin_video/README.md       |  2 +
 tests/test_douyin_sender.py                   | 40 +++++++++++++++++++
 3 files changed, 46 insertions(+)

diff --git a/src/Undefined/douyin/sender.py b/src/Undefined/douyin/sender.py
index 7a6a90d8..7d4a6810 100644
--- a/src/Undefined/douyin/sender.py
+++ b/src/Undefined/douyin/sender.py
@@ -237,6 +237,10 @@ async def send_douyin_video(
         return f"已发送抖音合并转发「{video_info.title}」"
     except Exception as exc:
         logger.exception("[Douyin] 处理视频失败: %s", video_id)
+        if getattr(exc, "delivery_uncertain", False) or getattr(
+            exc, "file_transfer_error", False
+        ):
+            raise
         video_info, error = await _recover_video_info_after_failure(
             video_id,
             video_info,
diff --git a/src/Undefined/skills/tools/douyin_video/README.md b/src/Undefined/skills/tools/douyin_video/README.md
index e3167d6f..4f666a81 100644
--- a/src/Undefined/skills/tools/douyin_video/README.md
+++ b/src/Undefined/skills/tools/douyin_video/README.md
@@ -10,5 +10,7 @@
 
 `send` 模式会发送一条两节点合并转发：视频信息、视频文件或视频状态。`uid` 模式会下载视频并注册为当前会话附件 UID，供 `file_analysis_agent` 继续分析。`info` 模式只返回标题、作者、时长、简介、封面 URL 和分享链接，不下载视频、不发送消息、不注册附件。
 
+发送遇到投递结果不确定或本地文件准备失败时，会保留该错误并停止发送，不再发送降级信息卡片；已经下载的视频仍会清理。
+
 配置依赖：
 - `config.toml` 中的 `[douyin]` 段控制代理、自动提取、时长限制、文件大小限制和清晰度探测顺序。
diff --git a/tests/test_douyin_sender.py b/tests/test_douyin_sender.py
index 35539b45..72c04d6e 100644
--- a/tests/test_douyin_sender.py
+++ b/tests/test_douyin_sender.py
@@ -10,6 +10,8 @@
 import Undefined.douyin.sender as douyin_sender
 from Undefined.attachments import AttachmentRegistry
 from Undefined.douyin.models import DouyinVideoInfo
+from Undefined.onebot.client import OneBotDeliveryUncertainError
+from Undefined.onebot.file_errors import FileTransferError
 
 
 def _video_info() -> DouyinVideoInfo:
@@ -25,6 +27,44 @@ def _video_info() -> DouyinVideoInfo:
     )
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "error",
+    [
+        OneBotDeliveryUncertainError("send_forward_msg", "timeout"),
+        FileTransferError("stream", "prepare failed"),
+    ],
+)
+async def test_send_douyin_video_does_not_fallback_after_delivery_error(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    error: RuntimeError,
+) -> None:
+    video_path = tmp_path / "douyin.mp4"
+    video_path.write_bytes(b"video")
+    send_mock = AsyncMock(side_effect=error)
+    sender: Any = SimpleNamespace(send_group_forward_message=send_mock)
+    monkeypatch.setattr(
+        douyin_sender,
+        "download_video",
+        AsyncMock(return_value=(video_path, _video_info(), "1080p", 5)),
+    )
+    cleanup_mock = AsyncMock()
+    monkeypatch.setattr(douyin_sender, "cleanup_path", cleanup_mock)
+    recover_mock = AsyncMock()
+    monkeypatch.setattr(douyin_sender, "get_video_info", recover_mock)
+
+    with pytest.raises(type(error)) as caught:
+        await douyin_sender.send_douyin_video(
+            _video_info().aweme_id, sender, "group", 123456
+        )
+
+    assert caught.value is error
+    send_mock.assert_awaited_once()
+    recover_mock.assert_not_awaited()
+    cleanup_mock.assert_awaited_once_with(video_path)
+
+
 @pytest.mark.asyncio
 async def test_send_douyin_video_records_two_node_forward(
     monkeypatch: pytest.MonkeyPatch,

From 58dabe7d73317c7e9c8cd216090f23e0a4c1cf23 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:00:01 +0800
Subject: [PATCH 011/121] fix(chat): create attachment downloads without
 overwriting files

---
 apps/undefined-chat/src-tauri/src/download.rs | 39 +++++++------
 .../src-tauri/src/native_tests.rs             | 55 ++++++++++++++++++-
 docs/undefined-chat.md                        |  2 +-
 3 files changed, 78 insertions(+), 18 deletions(-)

diff --git a/apps/undefined-chat/src-tauri/src/download.rs b/apps/undefined-chat/src-tauri/src/download.rs
index f8611267..57d66478 100644
--- a/apps/undefined-chat/src-tauri/src/download.rs
+++ b/apps/undefined-chat/src-tauri/src/download.rs
@@ -10,6 +10,7 @@ use tauri_plugin_http::reqwest::Response;
 use tokio::io::AsyncWriteExt;
 
 const MAX_PREVIEW_BYTES: usize = 10 * 1024 * 1024;
+pub(crate) const MAX_DOWNLOAD_NAME_CANDIDATES: usize = 1000;
 
 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -153,12 +154,11 @@ pub async fn save_attachment(
     tokio::fs::create_dir_all(&download_dir)
         .await
         .map_err(|err| format!("download directory create failed: {err}"))?;
-    let mut path = download_dir.join(safe_file_name(
+    let path = download_dir.join(safe_file_name(
         input.file_name.as_deref(),
         &input.attachment_id,
     ));
-    path = unique_path(path).await;
-    let mut file = tokio::fs::File::create(&path)
+    let (path, mut file) = create_unique_file(path)
         .await
         .map_err(|err| format!("attachment output create failed: {err}"))?;
     let mut bytes_written = 0u64;
@@ -224,11 +224,9 @@ pub async fn preview_attachment_bytes(
     })
 }
 
-async fn unique_path(path: PathBuf) -> PathBuf {
-    if tokio::fs::metadata(&path).await.is_err() {
-        return path;
-    }
-
+pub(crate) async fn create_unique_file(
+    path: PathBuf,
+) -> std::io::Result<(PathBuf, tokio::fs::File)> {
     let parent = path
         .parent()
         .map(PathBuf::from)
@@ -238,18 +236,27 @@ async fn unique_path(path: PathBuf) -> PathBuf {
         .and_then(|value| value.to_str())
         .unwrap_or("attachment");
     let extension = path.extension().and_then(|value| value.to_str());
-    for index in 1..1000 {
-        let file_name = if let Some(extension) = extension {
-            format!("{stem} ({index}).{extension}")
+    for index in 0..MAX_DOWNLOAD_NAME_CANDIDATES {
+        let candidate = if index == 0 {
+            path.clone()
         } else {
-            format!("{stem} ({index})")
+            let file_name = if let Some(extension) = extension {
+                format!("{stem} ({index}).{extension}")
+            } else {
+                format!("{stem} ({index})")
+            };
+            parent.join(file_name)
         };
-        let candidate = parent.join(file_name);
-        if tokio::fs::metadata(&candidate).await.is_err() {
-            return candidate;
+        match tokio::fs::File::create_new(&candidate).await {
+            Ok(file) => return Ok((candidate, file)),
+            Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => continue,
+            Err(err) => return Err(err),
         }
     }
-    path
+    Err(std::io::Error::new(
+        std::io::ErrorKind::AlreadyExists,
+        "no unused attachment download file name is available",
+    ))
 }
 
 #[cfg(test)]
diff --git a/apps/undefined-chat/src-tauri/src/native_tests.rs b/apps/undefined-chat/src-tauri/src/native_tests.rs
index 78e50909..0039b9a8 100644
--- a/apps/undefined-chat/src-tauri/src/native_tests.rs
+++ b/apps/undefined-chat/src-tauri/src/native_tests.rs
@@ -20,7 +20,7 @@ use crate::state::{
     AppRuntimeConfig, RuntimeConfigInput, RuntimeRequestPath, APP_CONFIG_FILE_NAME,
 };
 use crate::{
-    download::test_safe_file_name,
+    download::{create_unique_file, test_safe_file_name, MAX_DOWNLOAD_NAME_CANDIDATES},
     upload::{
         attachment_file_name, attachments_url, parse_file_path, requires_regular_file_check,
         upload_uses_streaming_body, UploadAttachmentInput,
@@ -298,6 +298,59 @@ fn attachment_save_file_name_sanitizes_path_like_input() {
     );
 }
 
+#[test]
+fn concurrent_attachment_saves_preserve_existing_and_each_other() {
+    let root = std::env::temp_dir().join(format!("undefined-download-{}", uuid::Uuid::new_v4()));
+    std::fs::create_dir_all(&root).unwrap();
+    let path = root.join("report.txt");
+    std::fs::write(&path, b"existing").unwrap();
+    tauri::async_runtime::block_on(async {
+        use tokio::io::AsyncWriteExt;
+        let (first, second) = futures_util::future::join(
+            create_unique_file(path.clone()),
+            create_unique_file(path.clone()),
+        )
+        .await;
+        let (first_path, mut first_file) = first.unwrap();
+        let (second_path, mut second_file) = second.unwrap();
+        assert_ne!(first_path, second_path);
+        assert_ne!(first_path, path);
+        assert_ne!(second_path, path);
+        first_file.write_all(b"first attachment").await.unwrap();
+        second_file.write_all(b"second attachment").await.unwrap();
+        first_file.flush().await.unwrap();
+        second_file.flush().await.unwrap();
+        assert_eq!(tokio::fs::read(&path).await.unwrap(), b"existing");
+        assert_eq!(
+            tokio::fs::read(first_path).await.unwrap(),
+            b"first attachment"
+        );
+        assert_eq!(
+            tokio::fs::read(second_path).await.unwrap(),
+            b"second attachment"
+        );
+    });
+    std::fs::remove_dir_all(root).unwrap();
+}
+
+#[test]
+fn attachment_save_fails_when_all_file_names_are_occupied() {
+    let root = std::env::temp_dir().join(format!("undefined-download-{}", uuid::Uuid::new_v4()));
+    std::fs::create_dir_all(&root).unwrap();
+    let path = root.join("report.txt");
+    std::fs::write(&path, b"existing").unwrap();
+    for index in 1..MAX_DOWNLOAD_NAME_CANDIDATES {
+        std::fs::write(root.join(format!("report ({index}).txt")), b"existing").unwrap();
+    }
+    let error = tauri::async_runtime::block_on(create_unique_file(path.clone())).unwrap_err();
+    assert_eq!(error.kind(), std::io::ErrorKind::AlreadyExists);
+    assert!(error
+        .to_string()
+        .contains("no unused attachment download file name"));
+    assert_eq!(std::fs::read(path).unwrap(), b"existing");
+    std::fs::remove_dir_all(root).unwrap();
+}
+
 #[test]
 fn upload_file_path_parser_keeps_android_content_uri_as_url() {
     let path = parse_file_path("content://media/external/images/media/42").unwrap();
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 606165f6..b05ebe0d 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -81,7 +81,7 @@ API Key 不应暴露给 React 状态树或日志。Tauri 负责保存、读取
 
 附件上传由 Tauri 从文件句柄流式读取并转发到 Runtime，React 只持有文件选择结果和上传状态。桌面路径和 `file://` URL 会做 regular file 校验；Android `content://` URI 交给 `tauri-plugin-fs` 打开，不强制使用本地 `metadata().is_file()` 判定。
 
-下载和预览同样通过 Tauri 受控命令处理。图片附件通过 `AttachmentImage` 或附件预览按钮调用 `previewAttachment`，Rust 端带 auth 拉取附件字节，再转为 `Blob` URL 渲染；全屏预览走应用内 `ImageViewerModal`，关闭时释放临时 URL。
+下载和预览同样通过 Tauri 受控命令处理。下载以原子创建方式占用文件名，同名文件依次添加数字后缀，并发下载也不会覆盖已有文件；可用候选名耗尽时明确报错。图片附件通过 `AttachmentImage` 或附件预览按钮调用 `previewAttachment`，Rust 端带 auth 拉取附件字节，再转为 `Blob` URL 渲染；全屏预览走应用内 `ImageViewerModal`，关闭时释放临时 URL。
 
 历史时间线未接入全局图片查看回调时使用本地 `ImagePreview`。可从图片通过 Enter / Space 打开，焦点进入关闭按钮，Tab / Shift+Tab 保持在预览内；Escape、点击遮罩或关闭按钮均可关闭，焦点恢复到触发图片。
 

From c55e3a2b24e6df68c3a358a55a2e4115302495c2 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:01:03 +0800
Subject: [PATCH 012/121] fix(automations): serialize snapshot persistence
 through cancellation

---
 docs/automations.md                       |  2 +
 src/Undefined/automations/storage.py      | 22 +++--
 tests/test_automation_storage_ordering.py | 98 +++++++++++++++++++++++
 3 files changed, 114 insertions(+), 8 deletions(-)
 create mode 100644 tests/test_automation_storage_ordering.py

diff --git a/docs/automations.md b/docs/automations.md
index 2f0fce8b..f153491a 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -91,6 +91,8 @@
 
 启动时若还没有 `data/automations.json` 但存在旧的 `scheduled_tasks.json`，会自动把旧任务转换为流程图格式写入新文件；旧文件保留不动，之后也不再双写。旧 `/api/v1/schedules` 接口与 `scheduler.*` 工具已下线，统一使用 `/api/v1/automations` 与 `automation.*`。
 
+任务编辑、删除与运行结果的保存共用串行写入锁，每次写入冻结完整快照并原子替换文件。并发保存不会让旧快照覆盖后续删除或新增；保存期间收到取消时，会先等磁盘写入完成再释放锁并传播取消。
+
 ## 配置与限制
 
 `[automations]` 配置节控制总开关、最大节点数（30）、全局并发（16，支持热更新）、节点 / 整图超时（600s / 1200s）、循环上限（默认 25，无内置硬顶）等，完整字段见 [配置说明](configuration.md)。事件类工作流默认不设冷却时间。
diff --git a/src/Undefined/automations/storage.py b/src/Undefined/automations/storage.py
index 91f64226..c830f0b6 100644
--- a/src/Undefined/automations/storage.py
+++ b/src/Undefined/automations/storage.py
@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import asyncio
+from copy import deepcopy
 import logging
 from pathlib import Path
 from typing import Any
@@ -25,6 +27,7 @@ def __init__(
     ) -> None:
         self.path = path or AUTOMATIONS_FILE_PATH
         self.legacy_path = legacy_path or LEGACY_TASKS_FILE_PATH
+        self._save_lock = asyncio.Lock()
 
     def load_tasks(self) -> dict[str, Any]:
         loaded_from_legacy = False
@@ -59,14 +62,17 @@ def load_tasks(self) -> dict[str, Any]:
     async def save_all(self, tasks: dict[str, Any]) -> None:
         from Undefined.utils import io
 
-        data_to_save: dict[str, Any] = {}
-        for task_id, task_info in tasks.items():
-            if isinstance(task_info, dict):
-                data_to_save[str(task_id)] = task_info
-            else:
-                logger.warning("[自动化] 跳过未知任务格式: %s", task_id)
-        await io.write_json(self.path, data_to_save, use_lock=True)
-        logger.info("[自动化] 已保存 %s 条到 %s", len(data_to_save), self.path)
+        async with self._save_lock:
+            data_to_save: dict[str, Any] = {}
+            for task_id, task_info in tasks.items():
+                if isinstance(task_info, dict):
+                    data_to_save[str(task_id)] = deepcopy(task_info)
+                else:
+                    logger.warning("[自动化] 跳过未知任务格式: %s", task_id)
+            await io.run_cancellation_safe(
+                io.write_json(self.path, data_to_save, use_lock=True)
+            )
+            logger.info("[自动化] 已保存 %s 条到 %s", len(data_to_save), self.path)
 
     def _write_json_sync(self, path: Path, data: dict[str, Any]) -> None:
         from Undefined.utils.io import write_json_sync
diff --git a/tests/test_automation_storage_ordering.py b/tests/test_automation_storage_ordering.py
new file mode 100644
index 00000000..2a2bdebc
--- /dev/null
+++ b/tests/test_automation_storage_ordering.py
@@ -0,0 +1,98 @@
+"""Automation persistence stays ordered across concurrent mutations and cancellation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from Undefined.automations.service import AutomationService
+from Undefined.automations.storage import AutomationStorage
+from Undefined.utils import io
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_first", [False, True])
+async def test_running_task_save_cannot_restore_concurrently_deleted_task(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, cancel_first: bool
+) -> None:
+    storage = AutomationStorage(tmp_path / "automations.json", tmp_path / "legacy.json")
+    service = AutomationService(
+        SimpleNamespace(),
+        SimpleNamespace(),
+        SimpleNamespace(),
+        SimpleNamespace(),
+        storage,
+    )
+    service.tasks.update({"a": {"task_id": "a"}, "b": {"task_id": "b"}})
+    started = asyncio.Event()
+    release = asyncio.Event()
+    writes: list[dict[str, Any]] = []
+    write_json = io.write_json
+
+    async def gated_write(path: Path | str, data: Any, use_lock: bool = True) -> None:
+        writes.append(data)
+        if len(writes) == 1:
+            started.set()
+            await release.wait()
+        await write_json(path, data, use_lock=use_lock)
+
+    monkeypatch.setattr(io, "write_json", gated_write)
+    first = asyncio.create_task(service._mark_run("a", status="ok"))
+    second: asyncio.Task[bool] | None = None
+    try:
+        await asyncio.wait_for(started.wait(), 1)
+        if cancel_first:
+            first.cancel()
+        second = asyncio.create_task(service.remove_task("b"))
+        await asyncio.sleep(0)
+        assert "b" not in service.tasks
+        assert len(writes) == 1
+        release.set()
+        results = await asyncio.gather(first, second, return_exceptions=True)
+        if cancel_first:
+            assert isinstance(results[0], asyncio.CancelledError)
+        else:
+            assert results[0] is None
+        assert results[1] is True
+        saved = json.loads(storage.path.read_text("utf-8"))
+        assert set(saved) == {"a"}
+        assert saved["a"]["current_executions"] == 1
+        assert set(storage.load_tasks()) == {"a"}
+    finally:
+        release.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )
+        service.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_snapshot_does_not_change_while_disk_write_is_pending(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    storage = AutomationStorage(tmp_path / "automations.json", tmp_path / "legacy.json")
+    tasks: dict[str, Any] = {"a": {"nodes": [{"args": {"message": "before"}}]}}
+    started = asyncio.Event()
+    release = asyncio.Event()
+    write_json = io.write_json
+
+    async def gated_write(path: Path | str, data: Any, use_lock: bool = True) -> None:
+        started.set()
+        await release.wait()
+        await write_json(path, data, use_lock=use_lock)
+
+    monkeypatch.setattr(io, "write_json", gated_write)
+    saving = asyncio.create_task(storage.save_all(tasks))
+    try:
+        await asyncio.wait_for(started.wait(), 1)
+        tasks["a"]["nodes"][0]["args"]["message"] = "after"
+    finally:
+        release.set()
+        await saving
+    saved = json.loads(storage.path.read_text("utf-8"))
+    assert saved["a"]["nodes"][0]["args"]["message"] == "before"

From 2dfb9c3457af4dc5102fcc91942029a7afb95285 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:01:55 +0800
Subject: [PATCH 013/121] fix(arxiv): settle inflight waiters when owner is
 cancelled

---
 src/Undefined/arxiv/sender.py                 |  4 ++
 .../skills/tools/arxiv_paper/README.md        |  2 +
 tests/test_arxiv_sender.py                    | 52 +++++++++++++++++++
 3 files changed, 58 insertions(+)

diff --git a/src/Undefined/arxiv/sender.py b/src/Undefined/arxiv/sender.py
index cf3115d5..553c5169 100644
--- a/src/Undefined/arxiv/sender.py
+++ b/src/Undefined/arxiv/sender.py
@@ -380,6 +380,10 @@ async def send_arxiv_paper(
             summary_preview_chars=summary_preview_chars,
             context=context,
         )
+    except asyncio.CancelledError:
+        if not future.done():
+            future.cancel()
+        raise
     except Exception as exc:
         if not future.done():
             future.set_exception(exc)
diff --git a/src/Undefined/skills/tools/arxiv_paper/README.md b/src/Undefined/skills/tools/arxiv_paper/README.md
index c514f5f1..d128ec36 100644
--- a/src/Undefined/skills/tools/arxiv_paper/README.md
+++ b/src/Undefined/skills/tools/arxiv_paper/README.md
@@ -15,6 +15,8 @@
 4. 尝试下载并上传 PDF
 5. 下载超限或 PDF 失败时仅保留信息消息
 
+同一会话的同一论文并发发送会共享在途结果。主发送任务取消时，等待该结果的调用也会收到取消，不记录成功去重时间；单个等待调用取消不会取消主发送任务。
+
 `uid` 模式流程：
 1. 下载 PDF
 2. 注册为当前会话附件 UID
diff --git a/tests/test_arxiv_sender.py b/tests/test_arxiv_sender.py
index 312075b5..8934d072 100644
--- a/tests/test_arxiv_sender.py
+++ b/tests/test_arxiv_sender.py
@@ -43,6 +43,58 @@ def _sender() -> Any:
     )
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_owner", [True, False])
+async def test_inflight_send_cancellation_settles_waiters(
+    monkeypatch: pytest.MonkeyPatch,
+    cancel_owner: bool,
+) -> None:
+    started = asyncio.Event()
+    release = asyncio.Event()
+
+    async def _fake_once(**_: object) -> str:
+        started.set()
+        await release.wait()
+        return "sent"
+
+    monkeypatch.setattr(arxiv_sender, "_send_arxiv_paper_once", _fake_once)
+    options: dict[str, Any] = {
+        "paper_id": "2501.01234",
+        "sender": _sender(),
+        "target_type": "group",
+        "target_id": 123456,
+        "max_file_size": 100,
+        "author_preview_limit": 2,
+        "summary_preview_chars": 1000,
+    }
+    owner = asyncio.create_task(send_arxiv_paper(**options))
+    await started.wait()
+    follower = asyncio.create_task(send_arxiv_paper(**options))
+    await asyncio.sleep(0)
+    key = ("group", 123456, "2501.01234")
+    future = arxiv_sender._INFLIGHT_SENDS[key]
+    assert not follower.done()
+
+    cancelled_task = owner if cancel_owner else follower
+    cancelled_task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await cancelled_task
+
+    if cancel_owner:
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(follower, timeout=1)
+        assert future.cancelled()
+        assert key not in arxiv_sender._RECENT_SENDS
+    else:
+        assert not future.done()
+        assert not owner.done()
+        release.set()
+        assert await asyncio.wait_for(owner, timeout=1) == "sent"
+        assert future.result() == "sent"
+        assert key in arxiv_sender._RECENT_SENDS
+    assert key not in arxiv_sender._INFLIGHT_SENDS
+
+
 @pytest.mark.asyncio
 async def test_send_arxiv_paper_sends_info_and_pdf(
     monkeypatch: pytest.MonkeyPatch,

From 9288097c0c3c3e80f3e6ec71258bc5b4f6fda9c3 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:02:21 +0800
Subject: [PATCH 014/121] fix(webui): preserve file charset when compressing
 downloads

---
 docs/management-api.md     |  2 +-
 src/Undefined/webui/app.py |  6 +++-
 tests/test_webui_gzip.py   | 68 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_webui_gzip.py

diff --git a/docs/management-api.md b/docs/management-api.md
index fba87f4a..a5902ad1 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -339,7 +339,7 @@ Content-Type: multipart/form-data
 }
 ```
 
-`runtime/chat/files` 仍保留为旧 WebUI 浏览器文件缓存兼容路径；新客户端和新 WebChat 功能应使用 `runtime/chat/attachments`。
+`runtime/chat/files` 仍保留为旧 WebUI 浏览器文件缓存兼容路径；新客户端和新 WebChat 功能应使用 `runtime/chat/attachments`。其 `runtime/chat/file?id=...` 下载响应支持 gzip 协商，可压缩的文本 / HTML 文件会保留 MIME、UTF-8 charset 和附件下载头。
 
 WebUI 内嵌聊天渲染 `<attachment uid="..."/>` / `<pic uid="..."/>` 图片时会把 Runtime 返回的 `/api/v1/chat/attachments/{uid}/preview` 规整为 Management 代理路径 `/api/runtime/chat/attachments/{uid}/preview`，浏览器不直接请求 Runtime API。普通 Markdown 图片（如 `![Image #1](https://...)`）仍由前端安全 renderer 输出可点击预览的 `<img>`，不走附件代理。
 
diff --git a/src/Undefined/webui/app.py b/src/Undefined/webui/app.py
index ad0b5379..f9dfdb8d 100644
--- a/src/Undefined/webui/app.py
+++ b/src/Undefined/webui/app.py
@@ -160,7 +160,11 @@ async def gzip_middleware(
                     mime = _GZIP_MIME.get(
                         file_path.suffix.lower(), "application/octet-stream"
                     )
-                    new_resp = web.Response(body=compressed, content_type=mime)
+                    new_resp = web.Response(
+                        body=compressed,
+                        status=response.status,
+                        headers={"Content-Type": mime},
+                    )
                     # 保留外层中间件已设置的 header（如安全头）
                     _skip = {
                         "content-length",
diff --git a/tests/test_webui_gzip.py b/tests/test_webui_gzip.py
new file mode 100644
index 00000000..56cfab5a
--- /dev/null
+++ b/tests/test_webui_gzip.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import gzip
+from pathlib import Path
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import make_mocked_request
+
+from Undefined.webui.app import gzip_middleware
+
+
+@pytest.mark.parametrize(
+    ("suffix", "content_type", "charset"),
+    [
+        (".txt", "text/plain", "utf-8"),
+        (".html", "text/html", "utf-8"),
+        (".json", "application/json", None),
+    ],
+)
+async def test_gzip_file_download_preserves_content_and_headers(
+    tmp_path: Path, suffix: str, content_type: str, charset: str | None
+) -> None:
+    original = ("聊天附件内容\n" * 100).encode("utf-8")
+    path = tmp_path / f"attachment{suffix}"
+    path.write_bytes(original)
+
+    async def handler(request: web.Request) -> web.StreamResponse:
+        return web.FileResponse(
+            path,
+            status=202,
+            headers={
+                "Content-Disposition": 'attachment; filename="report.txt"',
+                "Cache-Control": "no-store",
+            },
+        )
+
+    request = make_mocked_request(
+        "GET", "/api/runtime/chat/file?id=abc", headers={"Accept-Encoding": "gzip"}
+    )
+    response = await gzip_middleware(request, handler)
+    assert isinstance(response, web.Response)
+    assert isinstance(response.body, bytes)
+    assert gzip.decompress(response.body) == original
+    assert response.status == 202
+    assert response.content_type == content_type
+    assert response.charset == charset
+    assert response.headers["Content-Encoding"] == "gzip"
+    assert (
+        response.headers["Content-Disposition"] == 'attachment; filename="report.txt"'
+    )
+    assert response.headers["Cache-Control"] == "no-store"
+
+
+async def test_gzip_file_download_without_accept_encoding_is_unchanged(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "report.txt"
+    path.write_bytes(b"chat attachment\n" * 100)
+    original = web.FileResponse(path)
+
+    async def handler(request: web.Request) -> web.StreamResponse:
+        return original
+
+    request = make_mocked_request("GET", "/api/runtime/chat/file?id=abc")
+    response = await gzip_middleware(request, handler)
+    assert response is original
+    assert "Content-Encoding" not in response.headers

From d4030f1ed4ae5299bc5dea78c0e43d661caaa85e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:03:56 +0800
Subject: [PATCH 015/121] fix(onebot): reconnect without waiting for message
 handlers

---
 ARCHITECTURE.md                           |   2 +
 src/Undefined/onebot/client.py            |  37 +++++---
 tests/test_onebot_connection_lifecycle.py | 107 ++++++++++++++++++++++
 3 files changed, 133 insertions(+), 13 deletions(-)
 create mode 100644 tests/test_onebot_connection_lifecycle.py

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 6a095b02..06833845 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -886,6 +886,8 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 
 微信接入由主进程独立管理，不依赖 OneBot 是否在线。`WeixinService` 先校验帐号与 peer，再把已绑定来源映射为逻辑 QQ 私聊交给 `MessageHandler`；未知来源在写历史或调用 AI 之前进入隔离存储。`DeliveryAddress` 将逻辑身份与物理通道分离：`qq:<id>` 和 `wechat:<id>` 可共享同一个用户历史、认知记忆与权限，但发送器、消息合并 scope 和 transport 元数据保持通道隔离。自动化同样持久化规范 `address`，旧 `target_type + target_id` 在加载时转换为 `group:` 或 `qq:` 地址。
 
+OneBot 消息处理任务由客户端跨连接跟踪。网络断线只结束接收循环、通知未完成的 API 请求连接失败，不等待媒体下载等处理任务即可重连；已有处理任务继续运行。主动断开、停止或取消连接任务时，会取消并等待这些处理任务收尾，避免后台任务遗留。
+
 ### "车站-列车" 队列模型
 
 针对高并发消息处理，Undefined 实现了全新的 **ModelQueue** 调度机制：
diff --git a/src/Undefined/onebot/client.py b/src/Undefined/onebot/client.py
index 52993435..b05e6c48 100644
--- a/src/Undefined/onebot/client.py
+++ b/src/Undefined/onebot/client.py
@@ -126,6 +126,7 @@ def __init__(
             Callable[[dict[str, Any]], Coroutine[Any, Any, None]] | None
         ) = None
         self._running = False
+        self._tasks: set[asyncio.Task[None]] = set()
         self.file_transport = (
             file_transport
             if file_transport is not None
@@ -190,12 +191,22 @@ async def connect(self) -> None:
 
     async def disconnect(self) -> None:
         """断开连接"""
-        self._running = False
-        if self.ws:
-            logger.info("[WebSocket] 正在主动断开连接...")
-            await self.ws.close()
-            self.ws = None
-            logger.info("[WebSocket] 连接已断开")
+        self.stop()
+        try:
+            if self.ws:
+                logger.info("[WebSocket] 正在主动断开连接...")
+                await self.ws.close()
+                self.ws = None
+                logger.info("[WebSocket] 连接已断开")
+        finally:
+            await self._cancel_message_tasks()
+
+    async def _cancel_message_tasks(self) -> None:
+        tasks = tuple(self._tasks)
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
 
     async def _call_api(
         self,
@@ -914,7 +925,7 @@ async def run(self) -> None:
             raise RuntimeError("WebSocket 未连接")
 
         self._running = True
-        self._tasks: set[asyncio.Task[None]] = set()
+        cancelled = False
         logger.info("[WebSocket] 消息接收循环已启动")
 
         try:
@@ -941,6 +952,9 @@ async def run(self) -> None:
                     break
                 except Exception as e:
                     logger.exception(f"[WebSocket] 接收消息时发生异常: {e}")
+        except asyncio.CancelledError:
+            cancelled = True
+            raise
         finally:
             self._running = False
             for future in self._pending_responses.values():
@@ -948,12 +962,9 @@ async def run(self) -> None:
                     future.set_exception(
                         ConnectionError("OneBot WebSocket 接收循环已停止")
                     )
-            # 等待所有后台任务完成
-            if self._tasks:
-                logger.debug(
-                    f"[WebSocket] 正在等待 {len(self._tasks)} 个异步任务完成..."
-                )
-                await asyncio.gather(*self._tasks, return_exceptions=True)
+            # 消息处理跨连接跟踪；网络断线不等待长任务，主动停止才取消收尾。
+            if cancelled or getattr(self, "_should_stop", False):
+                await self._cancel_message_tasks()
             logger.info("[WebSocket] 接收循环已停止")
 
     async def _dispatch_message(self, data: dict[str, Any]) -> None:
diff --git a/tests/test_onebot_connection_lifecycle.py b/tests/test_onebot_connection_lifecycle.py
new file mode 100644
index 00000000..15ec8473
--- /dev/null
+++ b/tests/test_onebot_connection_lifecycle.py
@@ -0,0 +1,107 @@
+"""OneBot reconnect does not wait for unrelated message work."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, cast
+
+import pytest
+from websockets.exceptions import ConnectionClosedOK
+
+from Undefined.onebot.client import OneBotClient
+
+
+class _WebSocket:
+    def __init__(self, handler_started: asyncio.Event | None = None) -> None:
+        self.handler_started = handler_started
+        self.sent_message = False
+        self.closed = asyncio.Event()
+
+    async def recv(self) -> str:
+        if self.handler_started is not None:
+            if not self.sent_message:
+                self.sent_message = True
+                return json.dumps({"post_type": "message", "message_type": "group"})
+            await self.handler_started.wait()
+        else:
+            await self.closed.wait()
+        raise ConnectionClosedOK(None, None)
+
+    async def close(self) -> None:
+        self.closed.set()
+
+
+@pytest.mark.asyncio
+async def test_reconnect_preserves_inflight_handler_without_waiting(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = OneBotClient("ws://example.invalid")
+    started = asyncio.Event()
+    release = asyncio.Event()
+    finished = asyncio.Event()
+    reconnected = asyncio.Event()
+    connections = 0
+
+    async def handler(data: dict[str, Any]) -> None:
+        started.set()
+        await release.wait()
+        finished.set()
+
+    async def connect() -> None:
+        nonlocal connections
+        connections += 1
+        client.ws = cast(Any, _WebSocket(started if connections == 1 else None))
+        if connections == 2:
+            reconnected.set()
+
+    client.set_message_handler(handler)
+    monkeypatch.setattr(client, "connect", connect)
+    pending: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+    client._pending_responses["waiting"] = pending
+    running = asyncio.create_task(client.run_with_reconnect(reconnect_interval=0))
+    try:
+        await asyncio.wait_for(reconnected.wait(), 1)
+        assert connections == 2
+        assert len(client._tasks) == 1
+        assert not finished.is_set()
+        assert isinstance(pending.exception(), ConnectionError)
+        release.set()
+        await asyncio.wait_for(finished.wait(), 1)
+        await asyncio.sleep(0)
+        assert not client._tasks
+    finally:
+        release.set()
+        running.cancel()
+        await asyncio.gather(running, return_exceptions=True)
+        await client.disconnect()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("disconnect", [False, True])
+async def test_shutdown_cancels_and_collects_message_handlers(disconnect: bool) -> None:
+    client = OneBotClient("ws://example.invalid")
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+
+    async def handler(data: dict[str, Any]) -> None:
+        started.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelled.set()
+
+    client.set_message_handler(handler)
+    client.ws = cast(Any, _WebSocket())
+    await client._dispatch_message({"post_type": "message"})
+    running = asyncio.create_task(client.run())
+    await asyncio.wait_for(started.wait(), 1)
+    if disconnect:
+        await asyncio.wait_for(client.disconnect(), 1)
+        await asyncio.wait_for(running, 1)
+    else:
+        running.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(running, 1)
+    assert cancelled.is_set()
+    assert not client._tasks

From 9a3803fedf4fecae8016f13bc93cfc7ea16ac6d1 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:06:53 +0800
Subject: [PATCH 016/121] fix(ai): propagate cancellation to queued model calls

---
 docs/message-batching.md                      |   1 +
 src/Undefined/ai/client/queue.py              |  17 +++
 .../services/coordinator/background.py        |  18 ++-
 tests/test_queued_llm_cancellation.py         | 134 ++++++++++++++++++
 4 files changed, 169 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_queued_llm_cancellation.py

diff --git a/docs/message-batching.md b/docs/message-batching.md
index 77557b0a..726ef228 100644
--- a/docs/message-batching.md
+++ b/docs/message-batching.md
@@ -149,6 +149,7 @@ allow_cancel_after_send = false
 - `flush_all()` 在关停时设置 shutdown 标记，循环遍历所有桶执行等价 T1 路径，并 `await` 所有未完成的 flush task；若收尾过程中又出现新桶，会继续清空直到没有 pending bucket。shutdown 之后的新消息直接发车，不再开缓冲桶。
 - `MessageHandler.close()` 的顺序是：停止自动管线热重载 → `message_batcher.flush_all()` → `queue_manager.drain()` 等待已入队/在途回复自然收敛 → `queue_manager.stop()` → flush 历史落盘。
 - coordinator 在 `execute_reply` 入口调用 `register_inflight(scope, sender_id, task, ctx)`，在 `finally` 调 `unregister_inflight(...)`；`asyncio.CancelledError` 被识别为 "投机抢占"，仅记录信息日志且不重试。
+- 主调用取消或等待超时会同步取消其 LLM 子请求：尚未执行或正在等待重试的子请求会跳过模型调用，已执行的模型任务会收到取消。已经发到上游的请求无法撤回，但不会继续排队重试或产生无人消费的新调用。
 
 ### 兼容回退
 
diff --git a/src/Undefined/ai/client/queue.py b/src/Undefined/ai/client/queue.py
index fb97fcb1..7262e043 100644
--- a/src/Undefined/ai/client/queue.py
+++ b/src/Undefined/ai/client/queue.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from dataclasses import dataclass
 import logging
 from typing import Any
 from uuid import uuid4
@@ -29,6 +30,19 @@
 logger = logging.getLogger(__name__)
 
 
+@dataclass(slots=True)
+class QueuedLLMCallState:
+    """Share caller cancellation with queued retries and the active model task."""
+
+    cancelled: bool = False
+    task: asyncio.Task[dict[str, Any]] | None = None
+
+    def cancel(self) -> None:
+        self.cancelled = True
+        if self.task is not None and not self.task.done():
+            self.task.cancel()
+
+
 class ClientQueueMixin(ClientSetupMixin):
     """统一队列 LLM 调用与会话摘要投递。"""
 
@@ -107,6 +121,7 @@ async def submit_queued_llm_call(
             )
         request_id = uuid4().hex
         event: asyncio.Event = asyncio.Event()
+        call_state = QueuedLLMCallState()
         # 挂起表：QueueManager 回调 set_llm_call_result 时唤醒等待方
         self._pending_llm_calls[request_id] = (event, None)
         model_name = getattr(model_config, "model_name", "default")
@@ -121,6 +136,7 @@ async def submit_queued_llm_call(
             "max_tokens": effective_max_tokens,
             "transport_state": transport_state,
             "skip_prefetch_tools": skip_prefetch_tools,
+            "_llm_call_state": call_state,
         }
         ctx = RequestContext.current()
         if ctx is not None:
@@ -168,6 +184,7 @@ async def submit_queued_llm_call(
                 )
                 raise
         finally:
+            call_state.cancel()
             entry = self._pending_llm_calls.pop(request_id, None)
         _, result = entry if entry is not None else (None, None)
         if isinstance(result, Exception):
diff --git a/src/Undefined/services/coordinator/background.py b/src/Undefined/services/coordinator/background.py
index 34e8b956..1a75fae3 100644
--- a/src/Undefined/services/coordinator/background.py
+++ b/src/Undefined/services/coordinator/background.py
@@ -3,10 +3,12 @@
 from __future__ import annotations
 
 
+import asyncio
 import logging
 from typing import TYPE_CHECKING, Any, cast
 
 from Undefined.ai.queue_budget import resolve_effective_retry_count
+from Undefined.ai.client.queue import QueuedLLMCallState
 from Undefined.services.queue_manager import QUEUE_LANE_BACKGROUND
 from Undefined.utils.resources import read_text_resource
 
@@ -149,12 +151,18 @@ async def _execute_queued_llm_call(self, request: dict[str, Any]) -> None:
         retry_count = int(request.get("_retry_count", 0) or 0)
         queue_lane = str(request.get("_queue_lane") or QUEUE_LANE_BACKGROUND)
         call_type = str(request.get("call_type", "background") or "background")
+        call_state = request.get("_llm_call_state")
+        if isinstance(call_state, QueuedLLMCallState) and call_state.cancelled:
+            logger.info(
+                "[queued_llm_cancelled] 跳过已取消的调用: request_id=%s", request_id
+            )
+            return
         try:
             max_tokens_raw = request.get("max_tokens")
             if max_tokens_raw is None:
                 max_tokens_raw = getattr(request["model_config"], "max_tokens", 4096)
             max_tokens = int(max_tokens_raw) if max_tokens_raw is not None else 4096
-            result = await self.ai.request_model(
+            model_call = self.ai.request_model(
                 model_config=request["model_config"],
                 messages=request["messages"],
                 tools=request.get("tools"),
@@ -164,6 +172,14 @@ async def _execute_queued_llm_call(self, request: dict[str, Any]) -> None:
                 transport_state=request.get("transport_state"),
                 skip_prefetch_tools=bool(request.get("skip_prefetch_tools", False)),
             )
+            if isinstance(call_state, QueuedLLMCallState):
+                call_state.task = asyncio.create_task(model_call)
+                try:
+                    result = await call_state.task
+                finally:
+                    call_state.task = None
+            else:
+                result = await model_call
             self.ai.set_llm_call_result(request_id, result)
             if retry_count > 0:
                 logger.info(
diff --git a/tests/test_queued_llm_cancellation.py b/tests/test_queued_llm_cancellation.py
new file mode 100644
index 00000000..2ae7fa4b
--- /dev/null
+++ b/tests/test_queued_llm_cancellation.py
@@ -0,0 +1,134 @@
+"""Caller cancellation propagates through queued LLM execution and retries."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+
+from Undefined.ai.client import AIClient
+from Undefined.ai.client import queue as queue_module
+from Undefined.services.coordinator.background import BackgroundMixin
+
+
+class _CapturingQueue:
+    def __init__(self) -> None:
+        self.enqueued = asyncio.Event()
+        self.request: dict[str, Any] = {}
+
+    def get_max_retries(self) -> int:
+        return 1
+
+    async def add_queued_llm_request(
+        self, request: dict[str, Any], **kwargs: Any
+    ) -> SimpleNamespace:
+        self.request = dict(request)
+        self.enqueued.set()
+        return SimpleNamespace(estimated_wait_seconds=0)
+
+
+def _client_and_coordinator() -> tuple[Any, Any, _CapturingQueue]:
+    queue = _CapturingQueue()
+    client: Any = object.__new__(AIClient)
+    client._queue_manager = queue
+    client._pending_llm_calls = {}
+    client._get_runtime_config = lambda: SimpleNamespace(ai_request_max_retries=1)
+    client.request_model = AsyncMock(return_value={"choices": []})
+    coordinator: Any = object.__new__(BackgroundMixin)
+    coordinator.ai = client
+    coordinator.config = SimpleNamespace(ai_request_max_retries=1)
+    coordinator.queue_manager = queue
+    return client, coordinator, queue
+
+
+def _submit(client: Any) -> asyncio.Task[dict[str, Any]]:
+    return asyncio.create_task(
+        client.submit_queued_llm_call(
+            model_config=SimpleNamespace(model_name="chat", max_tokens=64),
+            messages=[{"role": "user", "content": "hello"}],
+            queue_lane="background",
+        )
+    )
+
+
+def _zero_timeout(*args: Any, **kwargs: Any) -> float:
+    return 0.0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("timeout", [False, True])
+async def test_cancelled_waiter_is_skipped_before_model_dispatch(
+    monkeypatch: pytest.MonkeyPatch, timeout: bool
+) -> None:
+    client, coordinator, queue = _client_and_coordinator()
+    if timeout:
+        monkeypatch.setattr(
+            queue_module, "compute_queued_llm_timeout_seconds", _zero_timeout
+        )
+    caller = _submit(client)
+    await asyncio.wait_for(queue.enqueued.wait(), 1)
+    if not timeout:
+        caller.cancel()
+    with pytest.raises(TimeoutError if timeout else asyncio.CancelledError):
+        await caller
+    await coordinator._execute_queued_llm_call(queue.request)
+    client.request_model.assert_not_awaited()
+    assert not client._pending_llm_calls
+
+
+@pytest.mark.asyncio
+async def test_caller_cancellation_stops_active_model_task() -> None:
+    client, coordinator, queue = _client_and_coordinator()
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+
+    async def request_model(**kwargs: Any) -> dict[str, Any]:
+        started.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelled.set()
+        return {}
+
+    client.request_model = AsyncMock(side_effect=request_model)
+    caller = _submit(client)
+    await asyncio.wait_for(queue.enqueued.wait(), 1)
+    dispatch = asyncio.create_task(coordinator._execute_queued_llm_call(queue.request))
+    await asyncio.wait_for(started.wait(), 1)
+    caller.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await caller
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(dispatch, 1)
+    assert cancelled.is_set()
+    assert not client._pending_llm_calls
+
+
+@pytest.mark.asyncio
+async def test_cancelled_waiter_is_not_called_again_after_retryable_failure() -> None:
+    client, coordinator, queue = _client_and_coordinator()
+    client.request_model = AsyncMock(side_effect=RuntimeError("retryable"))
+    caller = _submit(client)
+    await asyncio.wait_for(queue.enqueued.wait(), 1)
+    with pytest.raises(RuntimeError, match="retryable"):
+        await coordinator._execute_queued_llm_call(queue.request)
+    assert not caller.done()
+    caller.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await caller
+    await coordinator._execute_queued_llm_call({**queue.request, "_retry_count": 1})
+    client.request_model.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_uncancelled_queued_call_delivers_its_result() -> None:
+    client, coordinator, queue = _client_and_coordinator()
+    caller = _submit(client)
+    await asyncio.wait_for(queue.enqueued.wait(), 1)
+    await coordinator._execute_queued_llm_call(queue.request)
+    assert await asyncio.wait_for(caller, 1) == {"choices": []}
+    client.request_model.assert_awaited_once()
+    assert not client._pending_llm_calls

From 67d61b4d6cf4e962ae3fe4b0c1e95dcfec877291 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:07:02 +0800
Subject: [PATCH 017/121] fix(config): preserve valid settings and retry failed
 hot updates

---
 docs/configuration.md                         |   6 +-
 docs/python-api.md                            |   4 +-
 src/Undefined/config/build_config.py          |  11 +-
 src/Undefined/config/config_class.py          |   9 +-
 src/Undefined/config/hot_reload.py            |  14 +-
 src/Undefined/config/load_sections/domains.py |  11 +-
 src/Undefined/config/manager.py               |  20 +-
 src/Undefined/config/parsers/helpers.py       |   6 +-
 src/Undefined/config/webui_settings.py        |   8 +-
 tests/test_config_from_mapping.py             |  40 ++++
 tests/test_config_hot_reload.py               | 193 +++++++++++++++++-
 11 files changed, 296 insertions(+), 26 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index a3939cdd..771f8c8d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -69,6 +69,8 @@ Python 显式 mapping / builder.override  >  config.toml  >  环境变量  >  
 
 `from_mapping` / `builder` 仍会读取进程环境变量中**已注册**的兜底项（TOML / mapping 未提供的字段）。注册表见 [`env_registry.py`](../src/Undefined/config/env_registry.py) 与本文 [§8 环境变量兜底](#8-环境变量兜底迁移建议)。
 
+内存构建的所有字段（包括 `[webui]`）都来自传入的 mapping 与上述环境变量；不会读取 `config.toml`、`config.local.json` 或 `.env`。动态管理员文件只在 `Config.load()` 的文件加载入口合并，内存构建仍会把显式超级管理员纳入管理员列表。
+
 ### 2.3 `Config.from_mapping`
 
 结构与 `config.toml` 一致，例如：
@@ -1489,11 +1491,13 @@ api_key = "replace-with-your-key"
 
 ### 5.5 热更新失败的可见性
 
+TOML 语法错误、编码错误或读取失败会中止本次加载，热重载保留上次有效的完整配置，包括白名单、Runtime API 密钥和 WebUI 密码；已加载配置的文件被删除时也不会切换为默认值。修正文件并再次保存后会正常重载。`strict=False` 只放宽必填项校验，不允许把损坏的文件作为空配置使用。
+
 热更新在共享的 `Config` 实例上逐字段就地生效，整个过程没有 `await`，同一事件循环内的读方不会在一次读取里看到“改了一半”的对象；跨 `await` 的多次读取仍可能分别落在变更前后，需要严格一致的快照时请在单次读取中取全所需字段。
 
 应用阶段按步骤隔离：单步抛错不会中断后续步骤，失败步骤会以 `error` 级日志逐条打印（`热更新步骤失败`），并在末尾汇总一条“热更新未完全生效（运行时状态与 config.toml 不一致）”。异步步骤（技能热重载、自动化并发、配置监听器重启）使用被强引用跟踪的后台任务，任务异常同样以 `error` 级日志输出（`热更新后台任务失败`）。配置订阅者回调抛错时记录失败回调名单，其余回调继续执行。
 
-因此若看到上述日志，说明 `config.toml` 已改但对应运行时未生效，需要修复报错原因后重新保存配置；必要时重启进程。
+失败的同步回调、应用步骤和后台任务会保留相应变更。修复报错原因后重新保存相同配置也会重试，不必先把字段改成另一个值；已被后续配置覆盖的旧后台失败不会重放旧值。因此若看到上述应用失败日志，需要修复报错原因后重新保存配置；必要时重启进程。
 - 具体功能是否“立刻体现”，取决于模块是“每次读取配置”还是“启动时缓存”。
 - 对于行为不确定项，建议改完观察日志；必要时重启进程确认。
 
diff --git a/docs/python-api.md b/docs/python-api.md
index 4b243f20..6d7ef330 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -107,10 +107,12 @@ OneBot 内部时间解析提供两种约定：`parse_message_time(message)` 在
 Python 显式 mapping / override  >  config.toml  >  环境变量  >  代码默认值
 ```
 
-- `Config.from_mapping()` / `Config.builder()`：**不读取** `config.toml`，适合测试与无文件部署。
+- `Config.from_mapping()` / `Config.builder()`：**不读取** `config.toml`、`config.local.json` 或 `.env`，适合测试与无文件部署；`[webui]` 与其余字段一样使用传入 mapping，显式超级管理员仍自动加入管理员列表。
 - `Config.load()`：从指定或 CWD 下的 `config.toml` 加载（CLI 路径）。
 - 环境变量仅在 TOML / mapping **未提供**对应项时兜底；详见 [配置详解 — 环境变量兜底](configuration.md#8-环境变量兜底迁移建议)。
 
+`Config.load(strict=False)` 只放宽必填项校验，文件的 TOML 语法、编码或读取错误仍会抛出 `ValueError`。`ConfigManager.reload()` 加载失败时保留原配置；订阅者应用失败会记录日志并保留变更，下次重载相同内容也会再次通知。运行时热更新应用函数会在完成其余同步步骤后汇报失败，后台失败同样会进入重试。
+
 ### `Config.from_mapping`
 
 从内存 dict 构建配置，结构与 `config.toml` 一致：
diff --git a/src/Undefined/config/build_config.py b/src/Undefined/config/build_config.py
index a0e3562b..df353b94 100644
--- a/src/Undefined/config/build_config.py
+++ b/src/Undefined/config/build_config.py
@@ -3,8 +3,7 @@
 from __future__ import annotations
 
 
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from .config_class import Config
@@ -28,7 +27,7 @@ def build_config(
     data: dict[str, Any],
     *,
     strict: bool = True,
-    config_path: Optional[Path] = None,
+    include_local_admins: bool = False,
 ) -> "Config":
     """从已解析的 TOML mapping 构建 Config。"""
     from .config_class import Config
@@ -42,7 +41,9 @@ def build_config(
 
     # 合并 config.toml 与本地 admins.json，超管始终纳入 admin 列表
     superadmin_qq, admin_qqs = _merge_admins(
-        superadmin_qq=ctx["superadmin_qq"], admin_qqs=ctx["admin_qqs"]
+        superadmin_qq=ctx["superadmin_qq"],
+        admin_qqs=ctx["admin_qqs"],
+        include_local_admins=include_local_admins,
     )
     ctx["superadmin_qq"] = superadmin_qq
     ctx["admin_qqs"] = admin_qqs
@@ -52,6 +53,6 @@ def build_config(
     ctx.update(load_network(data))
     ctx.update(load_integrations(data))
     # domains 含 WebUI/API/认知/合并器等子域，放最后以便前面模型段已就绪
-    ctx.update(load_domains(data, config_path=config_path))
+    ctx.update(load_domains(data))
     load_finalize(ctx, strict=strict)  # strict 时校验必填项并打 debug 摘要
     return Config(**ctx)
diff --git a/src/Undefined/config/config_class.py b/src/Undefined/config/config_class.py
index b23d0e7e..968c7d2c 100644
--- a/src/Undefined/config/config_class.py
+++ b/src/Undefined/config/config_class.py
@@ -394,15 +394,16 @@ def load(cls, config_path: Optional[Path] = None, strict: bool = True) -> "Confi
         from .build_config import build_config
 
         _load_env()  # 先加载 .env，供 _get_value 环境变量回退
-        data = load_toml_data(config_path, strict=strict)
-        return build_config(data, strict=strict, config_path=config_path)
+        # strict 只控制必填项校验，损坏的文件始终不能当作空配置应用。
+        data = load_toml_data(config_path, strict=True)
+        return build_config(data, strict=strict, include_local_admins=True)
 
     @classmethod
     def from_mapping(cls, data: dict[str, Any], *, strict: bool = True) -> "Config":
         """从内存 mapping 构建配置（无 TOML 文件）。"""
         from .build_config import build_config
 
-        return build_config(data, strict=strict, config_path=None)
+        return build_config(data, strict=strict)
 
     @classmethod
     def builder(cls) -> "ConfigBuilder":
@@ -742,4 +743,4 @@ def build(self, *, strict: bool = True) -> Config:
         # TOML-style nested overrides for simple top-level keys only
         for key, value in self._overrides.items():
             data[key] = value
-        return build_config(data, strict=strict, config_path=None)
+        return build_config(data, strict=strict)
diff --git a/src/Undefined/config/hot_reload.py b/src/Undefined/config/hot_reload.py
index 1dc9d350..37eb2990 100644
--- a/src/Undefined/config/hot_reload.py
+++ b/src/Undefined/config/hot_reload.py
@@ -159,6 +159,7 @@ class HotReloadContext:
 def _spawn_hot_reload_task(
     coro: Coroutine[Any, Any, None],
     description: str,
+    on_failure: Callable[[], None] | None = None,
 ) -> None:
     """创建热更新后台任务并回收异常，避免静默失败。"""
     task = asyncio.create_task(coro, name=f"config-hot-reload:{description}")
@@ -170,6 +171,8 @@ def _on_done(finished: asyncio.Task[None]) -> None:
             return
         exc = finished.exception()
         if exc is not None:
+            if on_failure is not None:
+                on_failure()
             logger.error(
                 "[配置] 热更新后台任务失败: %s（该部分配置未生效）",
                 description,
@@ -198,6 +201,9 @@ def apply_config_updates(
 
     handler = context.message_handler
 
+    def _retry_failed_update() -> None:
+        context.config_manager.retry_failed_update(changes)
+
     def _apply_security() -> None:
         context.security_service.apply_config(updated)
 
@@ -244,6 +250,7 @@ def _apply_automations() -> None:
         _spawn_hot_reload_task(
             _apply_message_handler_automations_hot_reload(updated, handler),
             "automations",
+            on_failure=_retry_failed_update,
         )
 
     def _apply_model_configs() -> None:
@@ -261,10 +268,12 @@ def _apply_skills_reload() -> None:
         _spawn_hot_reload_task(
             _apply_skills_hot_reload(updated, context.ai_client),
             "skills",
+            on_failure=_retry_failed_update,
         )
         _spawn_hot_reload_task(
             _apply_message_handler_skills_hot_reload(updated, handler),
             "message-handler-skills",
+            on_failure=_retry_failed_update,
         )
 
     def _apply_config_watcher() -> None:
@@ -275,6 +284,7 @@ def _apply_config_watcher() -> None:
                 updated.skills_hot_reload_debounce,
             ),
             "config-watcher",
+            on_failure=_retry_failed_update,
         )
 
     steps: list[tuple[str, Callable[[], None]]] = []
@@ -319,6 +329,7 @@ def _apply_config_watcher() -> None:
             "如怀疑异步部分未生效，请检索『热更新后台任务失败』日志",
             ", ".join(failed),
         )
+        raise RuntimeError(f"热更新步骤失败: {', '.join(failed)}")
 
 
 def _log_restart_required(changed_keys: set[str]) -> None:
@@ -410,6 +421,7 @@ def _registry_name(registry: Any) -> str:
         logger.info("[配置] 技能热重载已禁用")
         if failed:
             logger.error("[配置] 部分注册表热重载未停止: %s", ", ".join(failed))
+            raise RuntimeError(f"技能热重载未停止: {', '.join(failed)}")
         return
 
     for registry in registries:
@@ -426,7 +438,7 @@ def _registry_name(registry: Any) -> str:
             )
     if failed:
         logger.error("[配置] 以下注册表热重载未生效: %s", ", ".join(failed))
-        return
+        raise RuntimeError(f"技能热重载未生效: {', '.join(failed)}")
     logger.info(
         "[配置] 技能热重载已更新: interval=%.2fs debounce=%.2fs",
         updated.skills_hot_reload_interval,
diff --git a/src/Undefined/config/load_sections/domains.py b/src/Undefined/config/load_sections/domains.py
index 5d4028f1..d3a78898 100644
--- a/src/Undefined/config/load_sections/domains.py
+++ b/src/Undefined/config/load_sections/domains.py
@@ -5,8 +5,7 @@
 # 配置分段加载：按 table 解析 TOML → ctx 字段 dict
 
 import logging
-from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from ..domain_parsers import (
     _parse_api_config,
@@ -25,16 +24,14 @@
     _parse_image_gen_config,
     _parse_image_gen_model_config,
 )
-from ..webui_settings import load_webui_settings
+from ..webui_settings import parse_webui_settings
 
 logger = logging.getLogger(__name__)
 
 
-def load_domains(
-    data: dict[str, Any], *, config_path: Optional[Path] = None
-) -> dict[str, Any]:
+def load_domains(data: dict[str, Any]) -> dict[str, Any]:
     # 子域配置：WebUI/API/认知/表情包/合并器/Naga/生图等，与 core/models 段解耦
-    webui_settings = load_webui_settings(config_path)
+    webui_settings = parse_webui_settings(data)
     api_config = _parse_api_config(data)
 
     cognitive = _parse_cognitive_config(data)
diff --git a/src/Undefined/config/manager.py b/src/Undefined/config/manager.py
index 825d4b71..50f93851 100644
--- a/src/Undefined/config/manager.py
+++ b/src/Undefined/config/manager.py
@@ -24,6 +24,7 @@ def __init__(self, config_path: Path | None = None) -> None:
         self._watch_stop: asyncio.Event | None = None
         self._last_snapshot: dict[str, tuple[int, int]] = {}
         self._reload_lock = asyncio.Lock()
+        self._pending_changes: dict[str, tuple[Any, Any]] = {}
 
     def load(self, strict: bool = True) -> Config:
         if self._config is None:
@@ -33,17 +34,33 @@ def load(self, strict: bool = True) -> Config:
     def replace(self, config: Config) -> None:
         """替换缓存的配置实例（库嵌入 ``set_config`` 注入时使用）。"""
         self._config = config
+        self._pending_changes.clear()
 
     def reload(self, strict: bool = False) -> dict[str, tuple[Any, Any]]:
         if self._config is None:
             self._config = Config.load(config_path=self.config_path, strict=strict)
             return {}
+        if not self.config_path.is_file():
+            raise FileNotFoundError(f"配置文件不存在，保留当前配置: {self.config_path}")
         new_config = Config.load(config_path=self.config_path, strict=strict)
-        changes = self._config.update_from(new_config)
+        changes = dict(self._pending_changes)
+        changes.update(self._config.update_from(new_config))
+        self._pending_changes.clear()
         if changes:
             self._notify(changes)
         return changes
 
+    def retry_failed_update(self, changes: dict[str, tuple[Any, Any]]) -> None:
+        """保留未应用的变更，下次保存时重试；忽略已被新配置取代的异步失败。"""
+        if self._config is None:
+            return
+        for key, change in changes.items():
+            current: Any = self._config
+            for part in key.split("."):
+                current = getattr(current, part, None)
+            if current == change[1]:
+                self._pending_changes[key] = change
+
     def subscribe(self, callback: ConfigChangeCallback) -> None:
         self._callbacks.append(callback)
 
@@ -128,6 +145,7 @@ def _notify(self, changes: dict[str, tuple[Any, Any]]) -> None:
             try:
                 callback(config, changes)
             except Exception:
+                self.retry_failed_update(changes)
                 name = getattr(callback, "__qualname__", repr(callback))
                 failed.append(name)
                 logger.error("[配置] 热更新回调执行失败: %s", name, exc_info=True)
diff --git a/src/Undefined/config/parsers/helpers.py b/src/Undefined/config/parsers/helpers.py
index c60baeea..fa47676e 100644
--- a/src/Undefined/config/parsers/helpers.py
+++ b/src/Undefined/config/parsers/helpers.py
@@ -22,9 +22,11 @@
 
 
 # 合并多来源配置
-def _merge_admins(superadmin_qq: int, admin_qqs: list[int]) -> tuple[int, list[int]]:
+def _merge_admins(
+    superadmin_qq: int, admin_qqs: list[int], *, include_local_admins: bool = True
+) -> tuple[int, list[int]]:
     # admins.json 与 config.toml 的 admin_qq 合并，去重后超管必在列表中
-    local_admins = load_local_admins()
+    local_admins = load_local_admins() if include_local_admins else []
     all_admins = list(set(admin_qqs + local_admins))
     if superadmin_qq and superadmin_qq not in all_admins:
         all_admins.append(superadmin_qq)
diff --git a/src/Undefined/config/webui_settings.py b/src/Undefined/config/webui_settings.py
index 47206f51..46f4303f 100644
--- a/src/Undefined/config/webui_settings.py
+++ b/src/Undefined/config/webui_settings.py
@@ -4,7 +4,7 @@
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 from .coercers import _coerce_bool, _coerce_int, _coerce_str, _normalize_str, _get_value
 
@@ -36,7 +36,11 @@ def display_url(self) -> str:
 def load_webui_settings(config_path: Optional[Path] = None) -> WebUISettings:
     from .loader import load_toml_data  # lazy to avoid circular
 
-    data = load_toml_data(config_path)
+    return parse_webui_settings(load_toml_data(config_path))
+
+
+def parse_webui_settings(data: dict[str, Any]) -> WebUISettings:
+    """从已解析的配置构建 WebUI 设置，不再读取文件。"""
     config_exists = bool(data)
     url_value = _get_value(data, ("webui", "url"), None)
     port_value = _get_value(data, ("webui", "port"), None)
diff --git a/tests/test_config_from_mapping.py b/tests/test_config_from_mapping.py
index 5d88efba..ad1a5d2d 100644
--- a/tests/test_config_from_mapping.py
+++ b/tests/test_config_from_mapping.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 
 import pytest
 
@@ -35,6 +36,45 @@ def test_from_mapping_builds_without_toml() -> None:
     assert cfg.chat_model.model_name == "gpt-test"
 
 
+@pytest.mark.parametrize("use_builder", [False, True])
+def test_memory_config_uses_webui_mapping_without_disk_reads(
+    monkeypatch: pytest.MonkeyPatch, use_builder: bool
+) -> None:
+    def _unexpected_read(*args: Any, **kwargs: Any) -> Any:
+        raise AssertionError("内存配置不应读取 TOML 或本地管理员文件")
+
+    monkeypatch.setattr("Undefined.config.loader.load_toml_data", _unexpected_read)
+    monkeypatch.setattr(
+        "Undefined.config.config_class.load_toml_data", _unexpected_read
+    )
+    monkeypatch.setattr(
+        "Undefined.config.parsers.helpers.load_local_admins", _unexpected_read
+    )
+    monkeypatch.setenv("WEBUI_PORT", "19876")
+    mapping = {
+        **_MINIMAL_MAPPING,
+        "core": {"superadmin_qq": 11, "admin_qq": [22]},
+        "webui": {
+            "url": "::1",
+            "port": 12345,
+            "password": "mapping-password",
+            "autostart_bot": True,
+            "check_updates": False,
+        },
+    }
+    config = (
+        Config.builder().with_mapping(mapping).build(strict=False)
+        if use_builder
+        else Config.from_mapping(mapping, strict=False)
+    )
+    assert config.webui_url == "::1"
+    assert config.webui_port == 12345
+    assert config.webui_password == "mapping-password"
+    assert config.webui_autostart_bot is True
+    assert config.webui_check_updates is False
+    assert set(config.admin_qqs) == {11, 22}
+
+
 def test_tool_search_defaults() -> None:
     cfg = Config.from_mapping(_MINIMAL_MAPPING, strict=False)
 
diff --git a/tests/test_config_hot_reload.py b/tests/test_config_hot_reload.py
index 3e77b5a4..c046af41 100644
--- a/tests/test_config_hot_reload.py
+++ b/tests/test_config_hot_reload.py
@@ -7,6 +7,7 @@
 
 import pytest
 
+from Undefined.config import Config
 from Undefined.config.hot_reload import HotReloadContext, apply_config_updates
 
 
@@ -705,7 +706,7 @@ def apply_config(self, config: Any) -> None:
         security_service=cast(Any, _BrokenSecurity()),
     )
 
-    with caplog.at_level("ERROR"):
+    with caplog.at_level("ERROR"), pytest.raises(RuntimeError, match="security"):
         apply_config_updates(
             updated,
             {"security_model.model_name": ("old", "new")},
@@ -763,6 +764,194 @@ def _record(config: Any, changes: dict[str, Any]) -> None:
     assert "回调未完成" in caplog.text
 
 
+@pytest.mark.parametrize("broken", ["[core\n", "\xff"])
+def test_invalid_reload_preserves_access_and_authentication(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, broken: str
+) -> None:
+    from Undefined.config.manager import ConfigManager
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    valid = '[access]\nmode="allowlist"\nallowed_group_ids=[111]\n[api]\nauth_key="private-key"\n'
+    path.write_text(valid, encoding="utf-8")
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    calls: list[dict[str, Any]] = []
+    manager.subscribe(lambda _config, changes: calls.append(changes))
+
+    path.write_bytes(broken.encode("latin-1"))
+    with pytest.raises(ValueError):
+        manager.reload(strict=False)
+    assert manager.load(strict=False) is config
+    assert config.access_mode == "allowlist"
+    assert config.is_group_allowed(111)
+    assert not config.is_group_allowed(999)
+    assert config.api.auth_key == "private-key"
+    assert calls == []
+
+    path.write_text(valid.replace("[111]", "[222]"), encoding="utf-8")
+    assert manager.reload(strict=False)
+    assert config.is_group_allowed(222)
+    assert not config.is_group_allowed(111)
+    assert len(calls) == 1
+
+
+def test_failed_callback_retries_identical_saved_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from Undefined.config.manager import ConfigManager
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text('[models.chat]\nmodel_name="old"\n', encoding="utf-8")
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    attempts = 0
+    applied: list[str] = []
+
+    def _apply(updated: Config, changes: dict[str, Any]) -> None:
+        nonlocal attempts
+        attempts += 1
+        assert "chat_model.model_name" in changes
+        if attempts == 1:
+            raise RuntimeError("transient failure")
+        applied.append(updated.chat_model.model_name)
+
+    manager.subscribe(_apply)
+    path.write_text('[models.chat]\nmodel_name="new"\n', encoding="utf-8")
+    assert manager.reload(strict=False)
+    assert config.chat_model.model_name == "new"
+    assert applied == []
+    assert manager.reload(strict=False)
+    assert applied == ["new"]
+    assert manager.reload(strict=False) == {}
+    assert attempts == 2
+
+
+def test_runtime_step_failure_retries_identical_saved_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from Undefined.config.manager import ConfigManager
+
+    class _FlakyQueue(_FakeQueueManager):
+        def update_max_retries(self, max_retries: int) -> None:
+            if not self.max_retries:
+                self.max_retries.append(-1)
+                raise RuntimeError("queue temporarily unavailable")
+            super().update_max_retries(max_retries)
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text("[core]\nai_request_max_retries=2\n", encoding="utf-8")
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    queue = _FlakyQueue()
+    context = HotReloadContext(
+        ai_client=cast(Any, _FakeAIClient()),
+        queue_manager=cast(Any, queue),
+        config_manager=manager,
+        security_service=cast(Any, _FakeSecurityService()),
+    )
+    manager.subscribe(
+        lambda config, changes: apply_config_updates(config, changes, context)
+    )
+    path.write_text("[core]\nai_request_max_retries=7\n", encoding="utf-8")
+    manager.reload(strict=False)
+    assert queue.max_retries == [-1]
+    manager.reload(strict=False)
+    assert queue.max_retries == [-1, 7]
+    assert manager.reload(strict=False) == {}
+
+
+@pytest.mark.asyncio
+async def test_runtime_background_failure_retries_identical_saved_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from Undefined.config.manager import ConfigManager
+
+    class _FlakyHandler(_FakeMessageHandler):
+        async def apply_automations_hot_reload_config(
+            self, *, max_concurrent: int
+        ) -> None:
+            if not self.automation_updates:
+                self.automation_updates.append(-1)
+                raise RuntimeError("automation temporarily unavailable")
+            await super().apply_automations_hot_reload_config(
+                max_concurrent=max_concurrent
+            )
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text("[automations]\nmax_concurrent=2\n", encoding="utf-8")
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    handler = _FlakyHandler()
+    context = HotReloadContext(
+        ai_client=cast(Any, _FakeAIClient()),
+        queue_manager=cast(Any, _FakeQueueManager()),
+        config_manager=manager,
+        security_service=cast(Any, _FakeSecurityService()),
+        message_handler=cast(Any, handler),
+    )
+    manager.subscribe(
+        lambda config, changes: apply_config_updates(config, changes, context)
+    )
+    path.write_text("[automations]\nmax_concurrent=7\n", encoding="utf-8")
+    manager.reload(strict=False)
+    for _ in range(3):
+        await asyncio.sleep(0)
+    assert handler.automation_updates == [-1]
+    manager.reload(strict=False)
+    for _ in range(3):
+        await asyncio.sleep(0)
+    assert handler.automation_updates == [-1, 7]
+    assert manager.reload(strict=False) == {}
+
+
+@pytest.mark.asyncio
+async def test_background_failure_retries_without_replaying_stale_values(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from Undefined.config.hot_reload import _spawn_hot_reload_task
+    from Undefined.config.manager import ConfigManager
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text('[models.chat]\nmodel_name="old"\n', encoding="utf-8")
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    attempts: list[str] = []
+    release = asyncio.Event()
+
+    async def _fail() -> None:
+        await release.wait()
+        raise RuntimeError("background failure")
+
+    def _apply(updated: Config, changes: dict[str, Any]) -> None:
+        attempts.append(updated.chat_model.model_name)
+        if len(attempts) == 1:
+            _spawn_hot_reload_task(
+                _fail(), "retry-test", lambda: manager.retry_failed_update(changes)
+            )
+
+    manager.subscribe(_apply)
+    path.write_text('[models.chat]\nmodel_name="new"\n', encoding="utf-8")
+    manager.reload(strict=False)
+    release.set()
+    for _ in range(3):
+        await asyncio.sleep(0)
+    assert manager.reload(strict=False)
+    assert attempts == ["new", "new"]
+
+    manager.retry_failed_update({"chat_model.model_name": ("old", "obsolete")})
+    assert manager.reload(strict=False) == {}
+
+
 def test_weixin_config_updates_in_place_for_hot_reload(tmp_path: Path) -> None:
     """WeixinService 持有 config.weixin 对象，热更新必须原地改字段而非换身份。"""
     from dataclasses import replace as dc_replace
@@ -805,7 +994,7 @@ def test_security_step_skipped_when_unrelated_keys_change() -> None:
     )
     security_service = _FakeSecurityService()
     context = HotReloadContext(
-        ai_client=cast(Any, SimpleNamespace()),
+        ai_client=cast(Any, SimpleNamespace(apply_search_config=lambda _url: None)),
         queue_manager=cast(Any, _FakeQueueManager()),
         config_manager=cast(Any, SimpleNamespace()),
         security_service=cast(Any, security_service),

From 55a238ab5015ec46e7562c6adc4c51784db3177d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:08:01 +0800
Subject: [PATCH 018/121] fix(skills): preserve inflight stats across hot
 reload

---
 src/Undefined/skills/README.md      |  2 ++
 src/Undefined/skills/registry.py    | 10 ++++---
 tests/test_skills_registry_stats.py | 45 +++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/src/Undefined/skills/README.md b/src/Undefined/skills/README.md
index ca78dd17..bd9cabae 100644
--- a/src/Undefined/skills/README.md
+++ b/src/Undefined/skills/README.md
@@ -4,6 +4,8 @@
 
 技能目录，包含基础工具（tools）、智能代理（agents）、工具集合（toolsets）和 Anthropic Skills（anthropic_skills）。它构成了 Undefined 机器人的所有核心能力基座。
 
+技能热重载删除或重命名工具时，已经开始的调用继续使用原处理器和统计对象完成，成功结果、异常与取消语义保持不变；后续调用使用重载后的技能列表。
+
 ## 目录结构
 
 ```
diff --git a/src/Undefined/skills/registry.py b/src/Undefined/skills/registry.py
index f1fbb3bc..60a2afc9 100644
--- a/src/Undefined/skills/registry.py
+++ b/src/Undefined/skills/registry.py
@@ -490,6 +490,8 @@ async def _execute(
         args = parse_tool_arguments(args, logger=logger, tool_name=name)
         async with self._items_lock:
             item = self._items.get(name)
+            if item is not None:
+                stats = self._stats.setdefault(name, SkillStats())
 
         if not item:
             if logger.isEnabledFor(logging.INFO) and self.kind in {
@@ -547,7 +549,7 @@ async def _execute(
                 result = await self._execute_with_timeout(handler, args, context)
                 duration = time.monotonic() - start_time
 
-                self._stats[name].record_success(duration)
+                stats.record_success(duration)
                 self._log_event(
                     "execute", name, status="success", duration_ms=int(duration * 1000)
                 )
@@ -558,7 +560,7 @@ async def _execute(
 
         except RegistryExecutionTimeoutError:
             duration = time.monotonic() - start_time
-            self._stats[name].record_failure(duration, "timeout")
+            stats.record_failure(duration, "timeout")
             self._log_event(
                 "execute", name, status="timeout", duration_ms=int(duration * 1000)
             )
@@ -569,7 +571,7 @@ async def _execute(
 
         except asyncio.CancelledError:
             duration = time.monotonic() - start_time
-            self._stats[name].record_failure(duration, "cancelled")
+            stats.record_failure(duration, "cancelled")
             self._log_event(
                 "execute", name, status="cancelled", duration_ms=int(duration * 1000)
             )
@@ -580,7 +582,7 @@ async def _execute(
 
         except Exception as e:
             duration = time.monotonic() - start_time
-            self._stats[name].record_failure(duration, str(e))
+            stats.record_failure(duration, str(e))
             logger.exception(f"[执行异常] {name}")
             self._log_event(
                 "execute", name, status="error", duration_ms=int(duration * 1000)
diff --git a/tests/test_skills_registry_stats.py b/tests/test_skills_registry_stats.py
index 0f446074..2b30a9de 100644
--- a/tests/test_skills_registry_stats.py
+++ b/tests/test_skills_registry_stats.py
@@ -4,6 +4,7 @@
 
 import asyncio
 from typing import Any
+from pathlib import Path
 
 import pytest
 
@@ -165,3 +166,47 @@ async def wait_forever(args: dict[str, Any], context: dict[str, Any]) -> str:
 
     with pytest.raises(asyncio.CancelledError):
         await task
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("outcome", ["success", "failure", "cancelled"])
+async def test_inflight_execution_keeps_stats_after_skill_removed(
+    tmp_path: Path,
+    outcome: str,
+) -> None:
+    started = asyncio.Event()
+    release = asyncio.Event()
+
+    async def handler(args: dict[str, Any], context: dict[str, Any]) -> str:
+        _ = args, context
+        started.set()
+        await release.wait()
+        if outcome == "failure":
+            raise RuntimeError("handler failure")
+        return "completed"
+
+    registry = BaseRegistry(base_dir=tmp_path, kind="tool", timeout_seconds=0)
+    registry.register_external_item("removed", _schema("removed"), handler)
+    stats = registry.get_stats()["removed"]
+    task = asyncio.create_task(registry.execute_strict("removed", {}, {}))
+    await started.wait()
+    await registry._reload_items()
+    assert "removed" not in registry.get_stats()
+
+    if outcome == "cancelled":
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert stats.last_error == "cancelled"
+    else:
+        release.set()
+        if outcome == "failure":
+            with pytest.raises(RuntimeError, match="handler failure"):
+                await task
+            assert stats.last_error == "handler failure"
+        else:
+            assert await task == "completed"
+            assert stats.success == 1
+    assert stats.count == 1
+    assert stats.failure == (0 if outcome == "success" else 1)
+    assert await registry.execute("removed", {}, {}) == "未找到项目: removed"

From 3ee4f02175f6e4f7869e6d3cb48f77f5a0226248 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:08:33 +0800
Subject: [PATCH 019/121] fix(deploy): abort the wizard on keyboard interrupt

---
 docs/deployment.md             |  2 +-
 docs/docker-deploy.md          |  2 +-
 src/Undefined/deploy/runner.py |  2 +-
 tests/test_deploy_runner.py    | 50 +++++++++++++++++++++++++++++++++-
 4 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 5c75d6b2..6b5d47c7 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -201,7 +201,7 @@ uv run deploy up
 
 部署结束后，按终端显示的地址和密码进入 WebUI，填写模型 API 与 QQ 身份配置，到 NapCat 扫码登录后，再返回 WebUI 点击“启动机器人”。`container` 与 `host` 模式都会将 `[webui].autostart_bot` 设为 `false`、`[onebot].file_send_mode` 设为 `"stream"`。**环境准备、首次配置、远程访问和常见问题请直接看 [Docker 一键部署指南](docker-deploy.md)**。
 
-向导在最终确认前只读取配置，取消不会生成文件或初始化子模块；已有 `config.toml` 支持 UTF-8 BOM 编码。`container` 模式还会为 Python 解释器自动映射已共享的 `deploy/data/cache/python_interpreter/`，让宿主 Docker 从正确的宿主路径读取执行文件。手工挂载 Docker socket 的容器需按 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)配置共享路径。
+向导在最终确认前只读取配置，选择“否”或按 Ctrl+C 取消都不会生成文件或初始化子模块；Ctrl+C 会立即结束命令，不会采用默认的“继续”。已有 `config.toml` 支持 UTF-8 BOM 编码。`container` 模式还会为 Python 解释器自动映射已共享的 `deploy/data/cache/python_interpreter/`，让宿主 Docker 从正确的宿主路径读取执行文件。手工挂载 Docker socket 的容器需按 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)配置共享路径。
 
 ---
 
diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md
index 2f612f3a..c7498c20 100644
--- a/docs/docker-deploy.md
+++ b/docs/docker-deploy.md
@@ -56,7 +56,7 @@ uv run deploy up
 | 发布端口的绑定地址 | 保持 `127.0.0.1`；在服务器上部署时，访问方法见下文[远程访问](#在自己的电脑上访问服务器) |
 | 是否拉取 NagaAgent 子模块 | 不需要 NagaAgent 代码问答时选“否” |
 
-向导随后会展示配置变更，最终确认前只读取配置和模板；选择取消不会创建 `config.toml` 或拉取 NagaAgent 子模块。确认后才生成配置、按需初始化子模块、拉取镜像并启动容器。首次运行需要下载依赖与镜像，请等待命令完成。
+向导随后会展示配置变更，最终确认前只读取配置和模板；选择“否”或按 Ctrl+C 取消不会创建 `config.toml` 或拉取 NagaAgent 子模块。Ctrl+C 会立即结束命令，不会采用默认的“继续”。确认后才生成配置、按需初始化子模块、拉取镜像并启动容器。首次运行需要下载依赖与镜像，请等待命令完成。
 
 如需跳过向导，可用 `uv run deploy up --yes` 代替；首次执行采用默认配置，之后执行会沿用上次的部署选择。只想提前查看变更时，可用 `uv run deploy up --dry-run`，它不会写文件或启动容器。
 
diff --git a/src/Undefined/deploy/runner.py b/src/Undefined/deploy/runner.py
index 4ca053e5..6acddee9 100644
--- a/src/Undefined/deploy/runner.py
+++ b/src/Undefined/deploy/runner.py
@@ -175,7 +175,7 @@ def confirm(self, question: str, default: bool = True) -> bool:
     def _ask(self, prompt: str) -> str:
         try:
             return input(f"{prompt}: ")
-        except (EOFError, KeyboardInterrupt):
+        except EOFError:
             print("\n（未输入，使用默认值）")
             return ""
 
diff --git a/tests/test_deploy_runner.py b/tests/test_deploy_runner.py
index 8b551e6a..bcc574a7 100644
--- a/tests/test_deploy_runner.py
+++ b/tests/test_deploy_runner.py
@@ -17,7 +17,8 @@
 import pytest
 import yaml
 
-from Undefined.deploy import catalog, docker_cli, generate, nagaagent, runner
+from Undefined.deploy import catalog, cli, docker_cli, generate, nagaagent, runner
+from Undefined.deploy.catalog import EXIT_ERROR
 from Undefined.deploy.docker_cli import CommandResult, DockerAvailability
 from Undefined.deploy.state import DeployLayout, read_state
 
@@ -657,6 +658,53 @@ def unexpected_side_effect(*args: object, **kwargs: object) -> None:
     assert "已取消，未改动任何文件。" in capsys.readouterr().out
 
 
+@pytest.mark.parametrize("existing_config", (False, True))
+def test_ctrl_c_at_final_confirmation_aborts_without_side_effects(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    existing_config: bool,
+) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "config.toml.example").write_text(CONFIG_TOML, encoding="utf-8")
+    if existing_config:
+        (repo / "config.toml").write_text(CONFIG_TOML, encoding="utf-8")
+    before = {path.name: path.read_bytes() for path in repo.iterdir()}
+    monkeypatch.setattr(runner, "repo_root", lambda: repo)
+    monkeypatch.setattr(runner, "wizard_enabled", lambda options: True)
+
+    def _interrupt_final_confirmation(prompt: str) -> str:
+        if "按以上计划继续" in prompt:
+            raise KeyboardInterrupt
+        return ""
+
+    def _unexpected_side_effect(*args: object, **kwargs: object) -> None:
+        raise AssertionError("Ctrl+C 取消前不能写入子模块或调用 Docker")
+
+    monkeypatch.setattr("builtins.input", _interrupt_final_confirmation)
+    monkeypatch.setattr(nagaagent, "ensure_submodule", _unexpected_side_effect)
+    monkeypatch.setattr(docker_cli, "check_availability", _unexpected_side_effect)
+
+    assert (
+        cli.main(
+            [
+                "up",
+                "--mode",
+                "container",
+                "--with",
+                "",
+                "--with-nagaagent",
+                "--port-bind",
+                "127.0.0.1",
+            ]
+        )
+        == EXIT_ERROR
+    )
+    assert {path.name: path.read_bytes() for path in repo.iterdir()} == before
+    assert "已取消。" in capsys.readouterr().out
+
+
 def test_up_accepts_bom_config(
     fake_repo: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

From 9762adf483750a83f1caeadcfd126adc3c9ed86d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:09:51 +0800
Subject: [PATCH 020/121] fix(file-analysis): confine archive extraction and
 cache cleanup

---
 .../agents/file_analysis_agent/README.md      |   2 +
 .../agents/file_analysis_agent/prompt.md      |   1 +
 .../tools/cleanup_temp/config.json            |   2 +-
 .../tools/cleanup_temp/handler.py             |  30 ++-
 .../tools/extract_archive/config.json         |   4 +-
 .../tools/extract_archive/handler.py          |  25 +-
 src/Undefined/skills/shared.py                |  27 +++
 tests/test_file_analysis_archive_cleanup.py   | 218 ++++++++++++++++++
 tests/test_skills_import_boundary.py          |   1 -
 9 files changed, 296 insertions(+), 14 deletions(-)
 create mode 100644 tests/test_file_analysis_archive_cleanup.py

diff --git a/src/Undefined/skills/agents/file_analysis_agent/README.md b/src/Undefined/skills/agents/file_analysis_agent/README.md
index 92b94552..64542628 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/README.md
+++ b/src/Undefined/skills/agents/file_analysis_agent/README.md
@@ -15,6 +15,8 @@
 - 内部附件 UID（`pic_xxx` / `file_xxx`）由工具按当前会话作用域解析；多模态分析可直接传 UID，其他解析工具先用 `download_file` 转成本地路径
 - `download_file` 的附件回源遇到目标策略拒绝、响应读取异常等失败时，会记录日志并返回“附件 UID 本地化失败”，不会继续尝试 URL 下载；`TimeoutError` 及其他 `OSError` 仍返回“附件文件读取失败”，任务取消正常向上传递
 - PDF 文字提取走 `extract_pdf`；扫描版、图表、版式或指定页码范围视觉分析走 `describe_pdf_page`
+- `extract_archive(list)` 可以列出本地压缩包；解压前先用 `download_file` 取得下载缓存内路径，解压目标限定为压缩包所在目录的子目录。TAR 显式使用 `data` 安全过滤器，拒绝越界成员、指向外部的链接及设备文件。缺少 `tarfile.data_filter` 的旧 Python 补丁版本仍可列出文件，但会拒绝 TAR 解压并提示更新补丁版本，不回退到无过滤解压。
+- `cleanup_temp.task_uuid` 只接受下载缓存的直接子目录名，拒绝绝对路径、路径跳转和符号链接；留空清理时跳过符号链接目录。
 
 开发提示：
 - 解析类工具尽量使用异步 I/O 或 `asyncio.to_thread`
diff --git a/src/Undefined/skills/agents/file_analysis_agent/prompt.md b/src/Undefined/skills/agents/file_analysis_agent/prompt.md
index bae93718..3a015e43 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/prompt.md
+++ b/src/Undefined/skills/agents/file_analysis_agent/prompt.md
@@ -24,6 +24,7 @@
 - 对图片和多模态文件，重点报告客观可见信息，例如文字、UI、场景、人物、角色、应用/游戏名称和关键元素。
 - `analyze_multimodal` 可能返回同文件历史分析记录；历史内容足够时直接基于它回答，只有确实需要新角度时才强制重新分析。
 - 涉及临时下载或解压后，任务结束前清理临时目录。
+- 压缩包必须先通过 `download_file` 放入下载缓存；解压目标使用压缩包所在目录的子目录。清理时只传缓存的直接子目录名，不传完整路径。
 
 回答要求：
 - 先给最有用的结论，再整理证据、摘录或结构化数据。
diff --git a/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/config.json b/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/config.json
index 637730ef..bcae9e15 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/config.json
+++ b/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/config.json
@@ -8,7 +8,7 @@
             "properties": {
                 "task_uuid": {
                     "type": "string",
-                    "description": "任务 UUID（缓存目录名），留空则清理所有下载缓存目录"
+                    "description": "下载缓存的直接子目录名，不接受路径或符号链接；留空则清理所有非符号链接下载缓存子目录"
                 }
             }
         }
diff --git a/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/handler.py b/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/handler.py
index c431119f..c662db60 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/handler.py
+++ b/src/Undefined/skills/agents/file_analysis_agent/tools/cleanup_temp/handler.py
@@ -1,6 +1,12 @@
 from typing import Any, Dict
 import logging
-import shutil
+from pathlib import Path
+
+from Undefined.skills.shared import (
+    delete_download_cache_directory,
+    download_cache_root,
+    resolve_download_cache_path,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -9,29 +15,39 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     """清理系统生成的临时文件和缓存"""
     task_uuid: str = args.get("task_uuid", "")
 
-    from Undefined.utils.paths import DOWNLOAD_CACHE_DIR
-
-    cache_dir = DOWNLOAD_CACHE_DIR
+    cache_dir = download_cache_root(context)
 
     if not cache_dir.exists():
         return "下载缓存目录不存在"
 
     try:
         if task_uuid:
+            if (
+                task_uuid in {".", ".."}
+                or Path(task_uuid).name != task_uuid
+                or "\\" in task_uuid
+            ):
+                return "错误：task_uuid 必须是下载缓存的直接子目录名"
             target_dir = cache_dir / task_uuid
+            if target_dir.is_symlink():
+                return "错误：不能清理符号链接目录"
+            target_dir = resolve_download_cache_path(target_dir, context)
             if target_dir.exists():
-                shutil.rmtree(target_dir)
+                await delete_download_cache_directory(target_dir)
                 return f"已清理下载缓存目录: {target_dir}"
             else:
                 return f"下载缓存目录不存在: {target_dir}"
         else:
             count = 0
             for item in cache_dir.iterdir():
-                if item.is_dir():
-                    shutil.rmtree(item)
+                if item.is_dir() and not item.is_symlink():
+                    target_dir = resolve_download_cache_path(item, context)
+                    await delete_download_cache_directory(target_dir)
                     count += 1
             return f"已清理 {count} 个下载缓存目录"
 
+    except ValueError as exc:
+        return f"错误：{exc}"
     except Exception as e:
         logger.exception(f"清理下载缓存目录失败: {e}")
         return "清理下载缓存目录失败，请稍后重试"
diff --git a/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/config.json b/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/config.json
index 5c24b92d..7032a6e9 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/config.json
+++ b/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/config.json
@@ -8,7 +8,7 @@
             "properties": {
                 "file_path": {
                     "type": "string",
-                    "description": "本地压缩包路径"
+                    "description": "本地压缩包路径；解压前须用 download_file 将其放入下载缓存"
                 },
                 "action": {
                     "type": "string",
@@ -16,7 +16,7 @@
                 },
                 "extract_path": {
                     "type": "string",
-                    "description": "解压目标路径（可选），默认为临时目录"
+                    "description": "解压目标路径（可选），必须是当前压缩包所在缓存目录的子目录；默认 extracted_<文件名>"
                 }
             },
             "required": ["file_path"]
diff --git a/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/handler.py b/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/handler.py
index 185eaee0..dff413bb 100644
--- a/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/handler.py
+++ b/src/Undefined/skills/agents/file_analysis_agent/tools/extract_archive/handler.py
@@ -2,6 +2,8 @@
 from typing import Any, Dict
 import logging
 
+from Undefined.skills.shared import resolve_download_cache_path
+
 logger = logging.getLogger(__name__)
 
 
@@ -10,8 +12,23 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     file_path: str = args.get("file_path", "")
     action: str = args.get("action", "list")
     extract_path: str | None = args.get("extract_path")
-
-    path = Path(file_path)
+    if action not in {"list", "extract"}:
+        return "错误：action 只能是 list 或 extract"
+    try:
+        path = Path(file_path).resolve()
+        if action == "extract":
+            path = resolve_download_cache_path(path, context)
+            target = (
+                Path(extract_path)
+                if extract_path
+                else path.parent / f"extracted_{path.stem}"
+            )
+            target = resolve_download_cache_path(target, context)
+            if target == path.parent or not target.is_relative_to(path.parent):
+                raise ValueError("解压目标必须是当前压缩包所在目录的子目录")
+            extract_path = str(target)
+    except (OSError, ValueError) as exc:
+        return f"错误：{exc}"
 
     if not path.exists():
         return f"错误：文件不存在 {file_path}"
@@ -101,6 +118,8 @@ async def _extract_tar(path: Path, action: str, extract_path: str | None) -> str
         return "\n".join(info)
 
     else:
+        if not hasattr(tarfile, "data_filter"):
+            return "当前 Python 缺少安全 TAR 解压能力，请更新 Python 补丁版本；仍可使用 list 列出文件"
         if extract_path:
             target_dir = Path(extract_path)
         else:
@@ -108,7 +127,7 @@ async def _extract_tar(path: Path, action: str, extract_path: str | None) -> str
             target_dir.mkdir(exist_ok=True)
 
         with tarfile.open(path, "r:*") as tar_ref:
-            tar_ref.extractall(target_dir)
+            tar_ref.extractall(target_dir, filter="data")
 
         info.append(f"\n已解压到：{target_dir}")
         info.append(f"解压文件数：{len(file_list)}")
diff --git a/src/Undefined/skills/shared.py b/src/Undefined/skills/shared.py
index 302dc96c..b4e07742 100644
--- a/src/Undefined/skills/shared.py
+++ b/src/Undefined/skills/shared.py
@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 from collections.abc import Coroutine
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, TypeVar
 
 if TYPE_CHECKING:
@@ -25,6 +26,29 @@ async def run_cancellation_safe(operation: Coroutine[Any, Any, _ResultT]) -> _Re
     return await run_io_cancellation_safe(operation)
 
 
+def download_cache_root(context: dict[str, Any]) -> Path:
+    """取得执行上下文的下载缓存根目录。"""
+    from Undefined.utils.paths import DOWNLOAD_CACHE_DIR
+
+    return Path(context.get("download_cache_dir") or DOWNLOAD_CACHE_DIR).resolve()
+
+
+def resolve_download_cache_path(path: Path, context: dict[str, Any]) -> Path:
+    """解析缓存内路径，拒绝缓存根本身和通过符号链接逃逸的路径。"""
+    root = download_cache_root(context)
+    resolved = path.resolve()
+    if resolved == root or not resolved.is_relative_to(root):
+        raise ValueError("路径必须位于下载缓存目录内，且不能是缓存根目录")
+    return resolved
+
+
+async def delete_download_cache_directory(path: Path) -> None:
+    """通过公共异步 IO 清理已验证的下载缓存子目录。"""
+    from Undefined.utils.io import delete_tree
+
+    await delete_tree(path)
+
+
 def private_access_error(
     runtime_config: Any,
     target_id: int,
@@ -176,6 +200,8 @@ async def jm_send_book(
 
 
 __all__ = [
+    "delete_download_cache_directory",
+    "download_cache_root",
     "jm_book_attachment_text",
     "jm_book_info_text",
     "jm_normalize_book_id",
@@ -184,4 +210,5 @@ async def jm_send_book(
     "jm_send_book",
     "parse_positive_int",
     "private_access_error",
+    "resolve_download_cache_path",
 ]
diff --git a/tests/test_file_analysis_archive_cleanup.py b/tests/test_file_analysis_archive_cleanup.py
new file mode 100644
index 00000000..d9f1902d
--- /dev/null
+++ b/tests/test_file_analysis_archive_cleanup.py
@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import io
+from pathlib import Path
+import tarfile
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+
+from Undefined.skills.agents.file_analysis_agent.tools.cleanup_temp import (
+    handler as cleanup_handler,
+)
+from Undefined.skills.agents.file_analysis_agent.tools.extract_archive import (
+    handler as archive_handler,
+)
+
+
+def _archive_context(tmp_path: Path) -> tuple[dict[str, Any], Path]:
+    root = tmp_path / "downloads"
+    task_dir = root / "task"
+    task_dir.mkdir(parents=True)
+    return {"download_cache_dir": root}, task_dir / "input.tar"
+
+
+def _write_tar(path: Path, member: tarfile.TarInfo, content: bytes = b"") -> None:
+    with tarfile.open(path, "w") as archive:
+        if member.isfile():
+            member.size = len(content)
+            archive.addfile(member, io.BytesIO(content))
+        else:
+            archive.addfile(member)
+
+
+@pytest.mark.asyncio
+async def test_archive_extracts_regular_tar_inside_task_directory(
+    tmp_path: Path,
+) -> None:
+    context, path = _archive_context(tmp_path)
+    _write_tar(path, tarfile.TarInfo("nested/readme.txt"), b"safe contents")
+
+    result = await archive_handler.execute(
+        {"file_path": str(path), "action": "extract"}, context
+    )
+
+    assert "已解压到" in result
+    assert (path.parent / "extracted_input/nested/readme.txt").read_bytes() == (
+        b"safe contents"
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("member_kind", ["traversal", "symlink", "hardlink", "device"])
+async def test_tar_rejects_unsafe_members(
+    tmp_path: Path,
+    member_kind: str,
+) -> None:
+    context, path = _archive_context(tmp_path)
+    victim = tmp_path / "victim.txt"
+    victim.write_bytes(b"keep")
+    if member_kind == "traversal":
+        member = tarfile.TarInfo("../../../victim.txt")
+    else:
+        member = tarfile.TarInfo("unsafe")
+        member.type = {
+            "symlink": tarfile.SYMTYPE,
+            "hardlink": tarfile.LNKTYPE,
+            "device": tarfile.CHRTYPE,
+        }[member_kind]
+        member.linkname = "../../../victim.txt"
+    _write_tar(path, member, b"overwritten")
+
+    result = await archive_handler.execute(
+        {"file_path": str(path), "action": "extract"}, context
+    )
+
+    assert "解析压缩包失败" in result
+    assert victim.read_bytes() == b"keep"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("target_kind", ["outside", "symlink", "other_task", "parent"])
+async def test_archive_rejects_extract_target_outside_current_task(
+    tmp_path: Path,
+    target_kind: str,
+) -> None:
+    context, path = _archive_context(tmp_path)
+    _write_tar(path, tarfile.TarInfo("readme.txt"), b"data")
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    if target_kind == "outside":
+        target = outside
+    elif target_kind == "symlink":
+        target = path.parent / "alias"
+        target.symlink_to(outside, target_is_directory=True)
+    elif target_kind == "other_task":
+        target = path.parent.parent / "other_task"
+    else:
+        target = path.parent
+
+    result = await archive_handler.execute(
+        {"file_path": str(path), "action": "extract", "extract_path": str(target)},
+        context,
+    )
+
+    assert result.startswith("错误：")
+    assert not (target / "readme.txt").exists()
+    assert not (outside / "readme.txt").exists()
+
+
+@pytest.mark.asyncio
+async def test_archive_rejects_source_outside_download_cache(tmp_path: Path) -> None:
+    context, _ = _archive_context(tmp_path)
+    source = tmp_path / "outside.tar"
+    _write_tar(source, tarfile.TarInfo("readme.txt"), b"data")
+
+    result = await archive_handler.execute(
+        {"file_path": str(source), "action": "extract"}, context
+    )
+
+    assert "下载缓存目录内" in result
+
+
+@pytest.mark.asyncio
+async def test_archive_can_list_source_outside_download_cache(tmp_path: Path) -> None:
+    context, _ = _archive_context(tmp_path)
+    source = tmp_path / "outside.tar"
+    _write_tar(source, tarfile.TarInfo("readme.txt"), b"data")
+
+    result = await archive_handler.execute({"file_path": str(source)}, context)
+
+    assert "readme.txt" in result
+    assert not (tmp_path / "extracted_outside").exists()
+
+
+@pytest.mark.asyncio
+async def test_tar_without_safe_filter_refuses_extraction(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    context, path = _archive_context(tmp_path)
+    _write_tar(path, tarfile.TarInfo("readme.txt"), b"data")
+    monkeypatch.delattr(tarfile, "data_filter")
+    extract_mock = Mock()
+    monkeypatch.setattr(tarfile.TarFile, "extractall", extract_mock)
+
+    result = await archive_handler.execute(
+        {"file_path": str(path), "action": "extract"}, context
+    )
+    listed = await archive_handler.execute({"file_path": str(path)}, context)
+
+    assert "缺少安全 TAR 解压能力" in result
+    assert "readme.txt" in listed
+    extract_mock.assert_not_called()
+    assert not (path.parent / "extracted_input").exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("task_uuid", ["../outside", "..", ".", "nested/task", "a\\b"])
+async def test_cleanup_rejects_path_arguments(
+    tmp_path: Path,
+    task_uuid: str,
+) -> None:
+    context, _ = _archive_context(tmp_path)
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    marker = outside / "keep.txt"
+    marker.write_text("keep")
+
+    result = await cleanup_handler.execute({"task_uuid": task_uuid}, context)
+
+    assert "错误：" in result
+    assert marker.read_text() == "keep"
+    assert Path(context["download_cache_dir"]).is_dir()
+
+
+@pytest.mark.asyncio
+async def test_cleanup_rejects_absolute_path_and_symbolic_link(tmp_path: Path) -> None:
+    context, _ = _archive_context(tmp_path)
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    marker = outside / "keep.txt"
+    marker.write_text("keep")
+    alias = Path(context["download_cache_dir"]) / "alias"
+    alias.symlink_to(outside, target_is_directory=True)
+
+    for task_uuid in (str(outside), "alias"):
+        result = await cleanup_handler.execute({"task_uuid": task_uuid}, context)
+        assert "错误：" in result
+    assert marker.read_text() == "keep"
+    assert alias.is_symlink()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("clear_all", [True, False])
+async def test_cleanup_removes_only_cache_directories(
+    tmp_path: Path,
+    clear_all: bool,
+) -> None:
+    context, path = _archive_context(tmp_path)
+    path.write_bytes(b"data")
+    root = Path(context["download_cache_dir"])
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    marker = outside / "keep.txt"
+    marker.write_text("keep")
+    alias = root / "alias"
+    alias.symlink_to(outside, target_is_directory=True)
+
+    result = await cleanup_handler.execute(
+        {} if clear_all else {"task_uuid": "task"}, context
+    )
+
+    assert "已清理" in result
+    assert not path.parent.exists()
+    assert root.is_dir()
+    assert alias.is_symlink()
+    assert marker.read_text() == "keep"
diff --git a/tests/test_skills_import_boundary.py b/tests/test_skills_import_boundary.py
index 7941024a..70a8188c 100644
--- a/tests/test_skills_import_boundary.py
+++ b/tests/test_skills_import_boundary.py
@@ -36,7 +36,6 @@
         "agents/entertainment_agent/tools/minecraft_skin/handler.py::Undefined.utils.paths",
         "agents/entertainment_agent/tools/wenchang_dijun/handler.py::Undefined.attachments",
         "agents/file_analysis_agent/handler.py::Undefined.attachments",
-        "agents/file_analysis_agent/tools/cleanup_temp/handler.py::Undefined.utils.paths",
         "agents/file_analysis_agent/tools/describe_pdf_page/handler.py::Undefined.utils",
         "agents/file_analysis_agent/tools/describe_pdf_page/handler.py::Undefined.utils.paths",
         "agents/info_agent/tools/arxiv_search/handler.py::Undefined.arxiv.client",

From af4b31ebbf879a9fa11d570406cb4db879a85e67 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:10:37 +0800
Subject: [PATCH 021/121] fix(ai): share task progress across tool call rounds

---
 src/Undefined/ai/client/ask_loop.py           |  1 +
 .../skills/tools/task_progress/README.md      |  2 +
 .../skills/tools/task_progress/handler.py     |  5 +-
 tests/test_tool_search_ask_loop.py            | 78 +++++++++++++++++++
 4 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/src/Undefined/ai/client/ask_loop.py b/src/Undefined/ai/client/ask_loop.py
index 3ef5f40d..9ffb5213 100644
--- a/src/Undefined/ai/client/ask_loop.py
+++ b/src/Undefined/ai/client/ask_loop.py
@@ -316,6 +316,7 @@ async def emit_webchat_stage(stage: str, detail: Any | None = None) -> None:
         # 注入常用资源（用于工具执行）
         tool_context.setdefault("ai_client", self)
         tool_context.setdefault("runtime_config", self._get_runtime_config())
+        tool_context.setdefault("_task_progress", [])
         if not isinstance(
             tool_context.get(MUSIC_TRACK_STORE_CONTEXT_KEY),
             MusicTrackReferenceStore,
diff --git a/src/Undefined/skills/tools/task_progress/README.md b/src/Undefined/skills/tools/task_progress/README.md
index 4b6c3ae1..4782de33 100644
--- a/src/Undefined/skills/tools/task_progress/README.md
+++ b/src/Undefined/skills/tools/task_progress/README.md
@@ -2,6 +2,8 @@
 
 任务进度追踪。处理需要多步骤、多 Agent 协作的复杂请求时，先用 plan 动作规划步骤，再在每步完成后用 update 动作标记进度。每次调用都会返回当前完整进度。
 
+同一次主 AI 请求的各轮工具调用共享计划；`plan` 替换计划内容，后续 `update` 能继续更新。不同请求默认各自保存计划，不跨请求持久化。
+
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `action` | `string(plan/update)` | 是 | plan: 创建任务计划（会替换已有计划）；update: 更新指定步骤的状态 |
diff --git a/src/Undefined/skills/tools/task_progress/handler.py b/src/Undefined/skills/tools/task_progress/handler.py
index 9327c70b..b75fcc75 100644
--- a/src/Undefined/skills/tools/task_progress/handler.py
+++ b/src/Undefined/skills/tools/task_progress/handler.py
@@ -61,7 +61,7 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     if not isinstance(tasks_input, list) or len(tasks_input) == 0:
         return "tasks 必须是非空数组"
 
-    task_store: list[dict[str, Any]] = context.get("_task_progress", [])
+    task_store: list[dict[str, Any]] = context.setdefault("_task_progress", [])
 
     if action == "plan":
         new_tasks: list[dict[str, Any]] = []
@@ -79,8 +79,7 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
             new_tasks.append({"id": tid, "description": desc, "status": status})
 
         new_tasks.sort(key=lambda t: t.get("id", 0))
-        task_store = new_tasks
-        context["_task_progress"] = task_store
+        task_store[:] = new_tasks
 
         logger.info(f"[task_progress] 创建计划，共 {len(task_store)} 个步骤")
         return f"计划已创建\n{_format_task_list(task_store)}"
diff --git a/tests/test_tool_search_ask_loop.py b/tests/test_tool_search_ask_loop.py
index b06bfb0b..d3f23b65 100644
--- a/tests/test_tool_search_ask_loop.py
+++ b/tests/test_tool_search_ask_loop.py
@@ -16,6 +16,9 @@
     MUSIC_TRACK_STORE_CONTEXT_KEY,
     MusicTrackReferenceStore,
 )
+from Undefined.skills.tools.task_progress.handler import (
+    execute as execute_task_progress,
+)
 from Undefined.utils.easter_egg_calls import (
     format_batched_easter_egg_message,
     main_call_key,
@@ -158,6 +161,81 @@ async def _submit_queued_llm_call(**kwargs: Any) -> dict[str, Any]:
     return client
 
 
+@pytest.mark.asyncio
+async def test_task_progress_state_survives_rounds_and_replanning() -> None:
+    stores: list[list[dict[str, Any]]] = []
+    results: list[str] = []
+
+    async def execute_tool(
+        name: str, args: dict[str, Any], context: dict[str, Any]
+    ) -> str:
+        if name == "end":
+            context["conversation_ended"] = True
+            return "ended"
+        assert name == "task_progress"
+        stores.append(context["_task_progress"])
+        result = await execute_task_progress(args, context)
+        results.append(result)
+        return result
+
+    client = _build_client(
+        execute_tool=execute_tool,
+        tool_search_enabled=False,
+        schemas=[_tool("task_progress"), _tool("end")],
+        llm_responses=[
+            _llm_tool_calls(
+                _tool_call(
+                    "plan_first",
+                    "task_progress",
+                    '{"action":"plan","tasks":[{"id":1,"description":"first"}]}',
+                )
+            ),
+            _llm_tool_calls(
+                _tool_call(
+                    "update_first",
+                    "task_progress",
+                    '{"action":"update","tasks":[{"id":1,"status":"done"}]}',
+                )
+            ),
+            _llm_tool_calls(
+                _tool_call(
+                    "plan_again",
+                    "task_progress",
+                    '{"action":"plan","tasks":[{"id":2,"description":"second"}]}',
+                )
+            ),
+            _llm_tool_calls(
+                _tool_call(
+                    "update_second",
+                    "task_progress",
+                    '{"action":"update","tasks":[{"id":2,"status":"done"}]}',
+                )
+            ),
+            _llm_tool_calls(_tool_call("end_first", "end")),
+            _llm_tool_calls(
+                _tool_call(
+                    "update_new_request",
+                    "task_progress",
+                    '{"action":"update","tasks":[{"id":2,"status":"done"}]}',
+                )
+            ),
+            _llm_tool_calls(_tool_call("end_second", "end")),
+        ],
+    )
+
+    assert await AIClient.ask(client, "plan and complete tasks") == ""
+    assert await AIClient.ask(client, "new request") == ""
+
+    assert results[0].startswith("计划已创建")
+    assert "进度: 1/1" in results[1]
+    assert results[2].startswith("计划已创建")
+    assert "进度: 1/1" in results[3]
+    assert all(store is stores[0] for store in stores[:4])
+    assert stores[0] == [{"id": 2, "description": "second", "status": "done"}]
+    assert stores[4] is not stores[0]
+    assert results[4] == "还没有任务计划，请先用 plan 动作创建"
+
+
 @pytest.mark.asyncio
 async def test_music_track_reference_store_survives_tool_search_rounds() -> None:
     stores: list[object] = []

From c0006d74ca5390152771b0e50d642d8212392b5e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:11:31 +0800
Subject: [PATCH 022/121] fix(webui): wait for authoritative history before
 releasing chat jobs

---
 docs/management-api.md                    |   2 +-
 docs/webui-guide.md                       |   4 +-
 src/Undefined/webui/static/js/runtime.js  |  96 ++++++++++++-----
 tests/frontend/runtime_chat_harness.js    | 119 ++++++++++++++++++++++
 tests/test_webui_runtime_chat_behavior.py |  27 +++++
 5 files changed, 217 insertions(+), 31 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index a5902ad1..b89375ac 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -355,7 +355,7 @@ WebUI 内嵌聊天渲染 `<attachment uid="..."/>` / `<pic uid="..."/>` 图片
 - 校验：
   - `conversation_id` 不一致时返回 `404`，避免跨会话误续接。
 - 响应：
-  - 默认 JSON：持久事件、当前顶层 `stage` 快照、当前 `agent_stage` 快照、`current_tool_calls` 和耗时字段。
+  - 默认 JSON：持久事件、当前顶层 `stage` 快照、当前 `agent_stage` 快照、`current_tool_calls`、耗时字段和 `job.history_finalized`。`done` / `error` / `cancelled` 终态可能先于历史收尾发布；WebUI 保留发送锁并继续轮询，直到 `history_finalized=true` 后刷新权威历史，刷新成功才释放任务；刷新失败时保留发送锁并通过现有轮询重试。
   - SSE：事件帧和 keep-alive 由 Runtime 透传。
 
 ```json
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 32bfc73d..e5c02379 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -160,8 +160,8 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - WebUI 场景下，代码优先直接作为聊天回复输出，不要默认转成文件附件；只有用户明确要求文件交付、代码过长不适合聊天展示，或确需附件工作流时才使用文件。所有代码块都应显式标注语言，例如 ` ```python `、` ```javascript `、` ```html `、` ```bash `，不确定语言时用 ` ```text `。
 - AI 消息支持引用：可引用整条 AI 消息、选中的某段文字，或 HTML 预览中点选的元素。引用会显示在输入框右侧的待发送引用条中，可在发送前移除；实际发送时不会新增接口或附件，而是自动在用户消息前拼接为 Markdown `>` 引用块，例如 `> 引用 AI:`，随后和文本、图片、文件一起进入同一条 WebChat job 消息。发送后的引用块会像代码块一样折叠显示，展开后内部固定高度并可滚动。发送失败时待引用内容会保留，发送成功后清空。
 - 默认加载最新 50 条消息并滚动到底部；向上滚动到顶部会按后端返回的 `next_before` 游标懒加载更早历史，并保持原视口偏移，避免一次性恢复大量工具块造成卡顿。“自动滚动到底部”开关默认开启并保存在浏览器本地，关闭后 AI 回复、工具 / Agent 状态和 AI 阶段刷新不会打断当前位置；首次加载和主动发送新消息仍会定位到底部。系统开启减少动态效果时，聊天滚动会改为即时跳转。
-- 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 `conversation_id + job_id + seq` 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；如果后端已完成 job 并落盘，前端会刷新历史并解除发送锁。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
-- 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口并解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 `reuse_previous_user_message=true` 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
+- 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 `conversation_id + job_id + seq` 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；`done` / `error` / `cancelled` 终态先到时仍保留 job 和发送锁，并继续轮询等待 `history_finalized=true`；确认后端收尾完成后刷新权威历史，刷新成功才解除发送锁；历史慢响应或刷新失败期间继续保留锁，并通过原轮询重试恢复。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
+- 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口，等待历史收尾完成后解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 `reuse_previous_user_message=true` 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
 - 运行中的 AI 气泡会在 `AI` 标签后实时显示当前阶段和后端计算的总已用时，例如构建上下文、查长期记忆、查认知记忆、等待模型、等待工具、发送消息；任务完成后该位置显示本轮回复总用时。工具 / Agent 摘要行会在名称旁显示调用耗时，运行中先显示后端快照时间，轮询间隙用本地时间临时递增，下一次查询后自动校准；结束后固定显示后端结束事件的总耗时。轮询刷新只更新已有状态和计时节点，结构未变化时不会重建工具 / Agent 块，避免运行中闪烁。状态条区分运行中、成功和失败；整轮回复总耗时会写入 WebChat 历史 metadata。
 - WebChat job 事件会更新同一个 AI 气泡；AI 正文和主对话工具 / Agent 调用按事件时序显示，例如工具调用、正文回复、结束工具会依次出现在同一气泡内。
 - 工具 / Agent 调用块展开后会分区展示由后端脱敏截断后的输入和输出预览；Agent 内部工具、子 Agent 和发送出的正文会按后端提供的 timeline 嵌套显示，并保留各自状态、输出和耗时。Agent 内部阶段只作为对应 Agent 摘要行的当前状态展示，不单独占用一行。并发工具结束事件按实际完成时间发布，结构化预览会渲染为带颜色的键值字段。输出内容继续支持 Markdown、安全 HTML、图片和文件卡片渲染，并保留适合移动端的单行工具摘要。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index cc490150..a6102a27 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -28,6 +28,7 @@
         chatHistoryCursor: null,
         chatHistoryHasMore: false,
         chatHistoryLoading: false,
+        chatHistoryFinalization: null,
         chatTopLoadSuppressedUntil: 0,
         chatAutoScroll: true,
         // 视图是否仍「钉」在底部。用户主动往上翻时置 false：此时不能再自动滚到底
@@ -5119,7 +5120,7 @@
 
     async function loadChatHistory(
         force = false,
-        { resumeActiveJob = true } = {},
+        { resumeActiveJob = true, expectedJobId = "" } = {},
     ) {
         if (!currentChatConversationId()) {
             await loadChatConversations();
@@ -5132,6 +5133,7 @@
             return;
         }
         runtimeState.chatHistoryLoading = true;
+        const conversationId = currentChatConversationId();
         const res = await api(
             chatUrl("/api/runtime/chat/history", { limit: 50 }),
         );
@@ -5140,6 +5142,13 @@
             runtimeState.chatHistoryLoading = false;
             throw new Error(buildRequestError(res, data));
         }
+        if (
+            conversationId !== currentChatConversationId() ||
+            (expectedJobId && runtimeState.activeJobId !== expectedJobId)
+        ) {
+            runtimeState.chatHistoryLoading = false;
+            return;
+        }
 
         clearChatMessages();
         const items = data && Array.isArray(data.items) ? data.items : [];
@@ -5208,6 +5217,48 @@
         }
     }
 
+    async function finishChatJob(payload = {}) {
+        // 终态事件先于历史落盘发布：保留 job 和轮询，直到 Runtime 确认收尾完成。
+        if (payload.history_finalized === false) {
+            runtimeState.chatBusy = true;
+            syncChatBusyControls();
+            return;
+        }
+        const jobId = runtimeState.activeJobId;
+        if (payload.history_finalized === true) {
+            let finalization = runtimeState.chatHistoryFinalization;
+            if (!finalization || finalization.jobId !== jobId) {
+                finalization = {
+                    jobId,
+                    promise: loadChatHistory(true, {
+                        resumeActiveJob: false,
+                        expectedJobId: jobId,
+                    }),
+                };
+                runtimeState.chatHistoryFinalization = finalization;
+            }
+            try {
+                await finalization.promise;
+            } catch (_error) {
+                // 历史刷新失败仍保留发送锁，现有 job 轮询会再次尝试收尾。
+                return;
+            } finally {
+                if (runtimeState.chatHistoryFinalization === finalization) {
+                    runtimeState.chatHistoryFinalization = null;
+                }
+            }
+            if (runtimeState.activeJobId !== jobId) return;
+        }
+        stopChatPolling();
+        runtimeState.activeJobId = null;
+        runtimeState.activeJobConversationId = "";
+        runtimeState.chatBusy = false;
+        setButtonLoading(get("btnRuntimeChatSend"), false);
+        syncChatBusyControls();
+        syncChatMessageActions();
+        loadChatConversations({ selectFirst: false }).catch(() => {});
+    }
+
     function applyChatEvent(event, payload, seq = 0) {
         if (seq)
             runtimeState.lastEventSeq = Math.max(
@@ -5241,14 +5292,7 @@
                 (event === "done" || event === "error") &&
                 (!eventJobId || eventJobId === runtimeState.activeJobId)
             ) {
-                stopChatPolling();
-                runtimeState.activeJobId = null;
-                runtimeState.activeJobConversationId = "";
-                runtimeState.chatBusy = false;
-                setButtonLoading(get("btnRuntimeChatSend"), false);
-                syncChatBusyControls();
-                syncChatMessageActions();
-                loadChatConversations({ selectFirst: false }).catch(() => {});
+                finishChatJob(payload || {});
             }
             return;
         }
@@ -5296,7 +5340,6 @@
             return;
         }
         if (event === "done") {
-            stopChatPolling();
             if (
                 payload &&
                 payload.reply &&
@@ -5317,27 +5360,15 @@
                 }
             }
             finalizeActiveChatMessage(payload || {});
-            runtimeState.activeJobId = null;
-            runtimeState.activeJobConversationId = "";
-            runtimeState.chatBusy = false;
             runtimeState.chatHistoryLoaded = true;
-            setButtonLoading(get("btnRuntimeChatSend"), false);
-            syncChatBusyControls();
-            syncChatMessageActions();
-            loadChatConversations({ selectFirst: false }).catch(() => {});
+            finishChatJob(payload || {});
             return;
         }
         if (event === "error") {
-            stopChatPolling();
             const item = findActiveChatMessage(eventJobId);
             finalizeActiveChatMessage();
             removeEmptyChatMessage(item);
-            runtimeState.activeJobId = null;
-            runtimeState.activeJobConversationId = "";
-            runtimeState.chatBusy = false;
-            setButtonLoading(get("btnRuntimeChatSend"), false);
-            syncChatBusyControls();
-            syncChatMessageActions();
+            finishChatJob(payload || {});
             const message = String(
                 payload && (payload.error || payload.message)
                     ? payload.error || payload.message
@@ -5357,22 +5388,28 @@
 
     function applyChatEventsPayload(data, jobId) {
         const events = data && Array.isArray(data.events) ? data.events : [];
+        const job = data && data.job ? data.job : null;
         events
             .filter((entry) => entry && typeof entry === "object")
             .sort((a, b) => Number(a.seq || 0) - Number(b.seq || 0))
             .forEach((entry) => {
                 applyChatEvent(
                     String(entry.event || ""),
-                    entry.payload || {},
+                    ["done", "error"].includes(String(entry.event || "")) && job
+                        ? {
+                              ...(entry.payload || {}),
+                              history_finalized: job.history_finalized,
+                          }
+                        : entry.payload || {},
                     Number(entry.seq || 0),
                 );
             });
-        const job = data && data.job ? data.job : null;
         applyChatJobSnapshot(job, jobId);
         if (
             job &&
             runtimeState.activeJobId === jobId &&
-            ["done", "error", "cancelled"].includes(String(job.status || ""))
+            ["done", "error", "cancelled"].includes(String(job.status || "")) &&
+            job.history_finalized !== false
         ) {
             applyChatEvent(
                 job.status === "done" ? "done" : "error",
@@ -5383,6 +5420,7 @@
                           job_id: job.job_id || jobId,
                           conversation_id: job.conversation_id || "",
                           duration_ms: job.duration_ms,
+                          history_finalized: job.history_finalized,
                       },
                 Number(job.last_seq || runtimeState.lastEventSeq),
             );
@@ -5391,6 +5429,8 @@
 
     function applyChatJobSnapshot(job, jobId) {
         if (!job || runtimeState.activeJobId !== jobId) return;
+        const status = String(job.status || "");
+        if (["done", "error", "cancelled"].includes(status)) return;
         const jobConversationId = String(job.conversation_id || "").trim();
         if (
             jobConversationId &&
@@ -5400,7 +5440,6 @@
         }
         const item = ensureStreamingMessage(jobId);
         if (!item) return;
-        const status = String(job.status || "");
         if (!["done", "error", "cancelled"].includes(status)) {
             const stage = String(job.current_stage || "").trim();
             if (stage) {
@@ -5616,6 +5655,7 @@
                             runtimeState.activeJobConversationId ||
                             currentChatConversationId(),
                         duration_ms: data && data.duration_ms,
+                        history_finalized: data && data.history_finalized,
                     },
                     Number(data && data.last_seq ? data.last_seq : 0),
                 );
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index 04685d80..4d930e27 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -2756,6 +2756,125 @@ SCENARIOS.workflow_tool_args_json_round_trip = async (env) => {
     };
 };
 
+async function jobWaitsForHistoryFinalization(env, status, controlledHistory = false) {
+    const { window, setRoutes } = env;
+    let jobPosts = 0;
+    let historyFinalized = false;
+    let historyReads = 0;
+    let firstEventBatch = true;
+    let historyAttempts = 0;
+    let resolveHistory = null;
+    let rejectHistory = null;
+    const snapshot = () => ({
+        job_id: "job-finalizing",
+        conversation_id: "conv-1",
+        status,
+        last_seq: 2,
+        history_finalized: historyFinalized,
+        reply: "answer",
+        error: status === "done" ? "" : status,
+    });
+    setRoutes([
+        {
+            match: "/chat/conversations",
+            reply: () => ({ body: {
+                conversations: [{ id: "conv-1", title: "t" }],
+                active_job: jobPosts === 1 && !historyFinalized ? snapshot() : null,
+            } }),
+        },
+        {
+            match: "/chat/history",
+            reply: () => {
+                historyReads += 1;
+                return { body: {
+                    items: historyFinalized ? [{ role: "bot", content: "persisted answer" }] : [],
+                    has_more: false,
+                    next_before: null,
+                } };
+            },
+        },
+        { match: "/chat/jobs/active", reply: { body: { job: null } } },
+        {
+            match: "/jobs/job-finalizing/events",
+            reply: () => {
+                const events = firstEventBatch ? [
+                    { seq: 1, event: "message", payload: { job_id: "job-finalizing", conversation_id: "conv-1", content: "answer" } },
+                    { seq: 2, event: status === "done" ? "done" : "error", payload: { job_id: "job-finalizing", conversation_id: "conv-1", reply: "answer", error: status } },
+                ] : [];
+                firstEventBatch = false;
+                return { body: { events, job: snapshot() } };
+            },
+        },
+        {
+            match: "/jobs/job-next/events",
+            reply: { body: { events: [], job: { job_id: "job-next", conversation_id: "conv-1", status: "running" } } },
+        },
+        {
+            match: "/chat/jobs",
+            reply: () => {
+                jobPosts += 1;
+                return { body: { job_id: jobPosts === 1 ? "job-finalizing" : "job-next", conversation_id: "conv-1" } };
+            },
+        },
+    ]);
+    if (controlledHistory) {
+        const fetch = window.fetch;
+        window.fetch = (url, options) => {
+            if (historyFinalized && String(url).includes("/chat/history")) {
+                historyAttempts += 1;
+                return new Promise((resolve, reject) => {
+                    resolveHistory = () => fetch(url, options).then(resolve, reject);
+                    rejectHistory = reject;
+                });
+            }
+            return fetch(url, options);
+        };
+    }
+    window.RuntimeController.init();
+    await window.RuntimeController.loadChatHistory(true);
+    const input = window.document.getElementById("runtimeChatInput");
+    const button = window.document.getElementById("btnRuntimeChatSend");
+    input.value = "first";
+    button.click();
+    await tick();
+    input.value = "second";
+    button.click();
+    await tick();
+    const beforeFinalization = { disabled: button.disabled, jobPosts, historyReads };
+    historyFinalized = true;
+    await settle(650);
+    let slowHistory = null;
+    if (controlledHistory) {
+        button.click();
+        await tick();
+        const whilePending = { disabled: button.disabled, jobPosts, historyAttempts };
+        rejectHistory(new Error("temporary history refresh failure"));
+        await tick();
+        await settle(650);
+        button.click();
+        await tick();
+        const afterFailure = { disabled: button.disabled, jobPosts, historyAttempts };
+        resolveHistory();
+        await tick();
+        slowHistory = { whilePending, afterFailure };
+    }
+    const afterFinalization = { disabled: button.disabled, historyReads, botTexts: botNodes(window).map((node) => node.contentText) };
+    button.click();
+    await tick();
+    return {
+        beforeFinalization,
+        afterFinalization,
+        jobPosts,
+        eventRequests: env.requests.filter((url) => url.includes("/jobs/job-finalizing/events")).length,
+        slowHistory,
+    };
+}
+SCENARIOS.history_finalization_slow_history = (env) => jobWaitsForHistoryFinalization(env, "done", true);
+
+for (const status of ["done", "error", "cancelled"]) {
+    SCENARIOS[`history_finalization_${status}`] = (env) => jobWaitsForHistoryFinalization(env, status);
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index 8d9b67fa..c1777bad 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -117,6 +117,33 @@ def test_final_message_reuses_streaming_node() -> None:
     assert [node["contentTexts"] for node in _user_nodes(result)] == [["hi"]]
 
 
+@pytest.mark.parametrize("status", ["done", "error", "cancelled"])
+def test_terminal_job_keeps_polling_until_history_is_finalized(status: str) -> None:
+    result = run_scenario(f"history_finalization_{status}")
+    assert result["beforeFinalization"] == {
+        "disabled": True,
+        "jobPosts": 1,
+        "historyReads": 1,
+    }
+    assert result["afterFinalization"]["disabled"] is False
+    assert result["afterFinalization"]["historyReads"] == 2
+    assert result["afterFinalization"]["botTexts"] == ["persisted answer"]
+    assert result["jobPosts"] == 2
+    assert result["eventRequests"] >= 2
+
+
+def test_history_refresh_keeps_send_locked_until_success_and_retries_failure() -> None:
+    result = run_scenario("history_finalization_slow_history")
+    assert result["slowHistory"] == {
+        "whilePending": {"disabled": True, "jobPosts": 1, "historyAttempts": 1},
+        "afterFailure": {"disabled": True, "jobPosts": 1, "historyAttempts": 2},
+    }
+    assert result["afterFinalization"]["disabled"] is False
+    assert result["afterFinalization"]["historyReads"] == 2
+    assert result["afterFinalization"]["botTexts"] == ["persisted answer"]
+    assert result["jobPosts"] == 2
+
+
 # --------------------------------------------------------------------------- #
 # 工具生命周期
 # --------------------------------------------------------------------------- #

From 21dfb0baf164df2418e97639a14979a5e9909dac Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:12:27 +0800
Subject: [PATCH 023/121] fix(knowledge): preserve source chunks until
 replacement succeeds

---
 docs/knowledge.md                  |  2 +
 src/Undefined/knowledge/manager.py | 10 +++-
 src/Undefined/knowledge/store.py   | 24 +++++++-
 tests/test_knowledge.py            | 89 +++++++++++++++++++++++++++++-
 4 files changed, 118 insertions(+), 7 deletions(-)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index e212986d..b27be0fc 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -188,6 +188,8 @@ chunk_size=4, chunk_overlap=1 → step=3
 
 `.manifest.json` 记录每个文件的 SHA256 hash。扫描时只对新增或内容变更的文件重新嵌入，未变更的文件跳过。
 
+变更文件先完成读取与嵌入，再写入新块，成功后才删除该来源的旧块并更新 hash。读取、嵌入或新块写入失败时保留旧索引和旧 hash，下次扫描可重试；主动删除文件或把内容清空则会移除其旧索引。索引写入与清理串行执行，取消时先等待已发起的磁盘操作完成。
+
 ### 站台/发车队列
 
 嵌入与重排请求都通过内置队列串行发送，按各自 `queue_interval_seconds` 控制发车间隔；embedding/rerank 默认值均为 `0.0`，非正数都表示请求到达立即发车。多行文本按 `embed_batch_size` 分批，每批一次 API 调用。
diff --git a/src/Undefined/knowledge/manager.py b/src/Undefined/knowledge/manager.py
index a7a73760..e81f0f8b 100644
--- a/src/Undefined/knowledge/manager.py
+++ b/src/Undefined/knowledge/manager.py
@@ -287,15 +287,18 @@ async def embed_knowledge_base(self, kb_name: str) -> int:
                 continue
             if store is None:
                 store = self._get_store(kb_name)
-            await store.delete_by_source(relative_source)
             try:
                 content = await asyncio.to_thread(text_file.read_text, "utf-8")
             except (OSError, UnicodeDecodeError):
-                if manifest.pop(relative_source, None) is not None:
-                    manifest_changed = True
+                logger.warning(
+                    "[知识库] 读取失败，保留旧索引: kb=%s source=%s",
+                    kb_name,
+                    relative_source,
+                )
                 continue
             lines = chunk_lines(content, self._chunk_size, self._chunk_overlap)
             if not lines:
+                await store.delete_by_source(relative_source)
                 manifest[relative_source] = fhash
                 manifest_changed = True
                 continue
@@ -306,6 +309,7 @@ async def embed_knowledge_base(self, kb_name: str) -> int:
                 lines,
                 embeddings,
                 metadata_base={"source": relative_source, "kb": kb_name},
+                replace_source=True,
             )
             manifest[relative_source] = fhash
             manifest_changed = True
diff --git a/src/Undefined/knowledge/store.py b/src/Undefined/knowledge/store.py
index 766a37c8..f433ce61 100644
--- a/src/Undefined/knowledge/store.py
+++ b/src/Undefined/knowledge/store.py
@@ -10,6 +10,8 @@
 
 import chromadb
 
+from Undefined.utils import io
+
 logger = logging.getLogger(__name__)
 
 
@@ -20,6 +22,7 @@ def __init__(
         self, name: str, chroma_dir: Path, *, create_if_missing: bool = True
     ) -> None:
         self.name = name
+        self._write_lock = asyncio.Lock()
         self._client = chromadb.PersistentClient(path=str(chroma_dir))
         if create_if_missing:
             self._collection = self._client.get_or_create_collection(
@@ -42,6 +45,8 @@ async def add_chunks(
         chunks: list[str],
         embeddings: list[list[float]],
         metadata_base: dict[str, Any] | None = None,
+        *,
+        replace_source: bool = False,
     ) -> int:
         if not chunks:
             return 0
@@ -52,14 +57,26 @@ async def add_chunks(
         ]
 
         def _upsert() -> None:
+            previous_ids = (
+                self._collection.get(where={"source": source}, include=[])["ids"]
+                if replace_source and source
+                else []
+            )
             self._collection.upsert(
                 ids=ids,
                 embeddings=embeddings,  # type: ignore[arg-type]
                 documents=chunks,
                 metadatas=metadatas,  # type: ignore[arg-type]
             )
-
-        await asyncio.to_thread(_upsert)
+            current_ids = set(ids)
+            stale_ids = [
+                chunk_id for chunk_id in previous_ids if chunk_id not in current_ids
+            ]
+            if stale_ids:
+                self._collection.delete(ids=stale_ids)
+
+        async with self._write_lock:
+            await io.run_cancellation_safe(asyncio.to_thread(_upsert))
         return len(chunks)
 
     async def delete_by_source(self, source: str) -> None:
@@ -69,7 +86,8 @@ async def delete_by_source(self, source: str) -> None:
         def _delete() -> None:
             self._collection.delete(where={"source": source})
 
-        await asyncio.to_thread(_delete)
+        async with self._write_lock:
+            await io.run_cancellation_safe(asyncio.to_thread(_delete))
 
     async def query(
         self, query_embedding: list[float], top_k: int = 5
diff --git a/tests/test_knowledge.py b/tests/test_knowledge.py
index ba03ec54..137a6b73 100644
--- a/tests/test_knowledge.py
+++ b/tests/test_knowledge.py
@@ -8,6 +8,8 @@
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import pytest
+
 from chromadb.errors import NotFoundError
 from Undefined.knowledge.chunker import chunk_lines
 from Undefined.knowledge.embedder import Embedder
@@ -444,10 +446,95 @@ async def test_embed_replaces_changed_file_chunks(tmp_path: Path) -> None:
         added = await manager.embed_knowledge_base("kb1")
 
     assert added == 1
-    store.delete_by_source.assert_awaited_once_with("texts/doc.txt")
+    store.delete_by_source.assert_not_awaited()
+    assert store.add_chunks.await_args.kwargs["replace_source"] is True
     assert "texts/doc.txt" in json.loads(manifest_path.read_text("utf-8"))
 
 
+@pytest.mark.parametrize("failure", ["read", "embed", "upsert"])
+async def test_failed_reindex_keeps_real_old_chunks_and_retries(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, failure: str
+) -> None:
+    manager, embedder = _make_manager(tmp_path)
+    kb_dir = _make_kb(tmp_path, "kb1", {"doc.txt": "new contents"})
+    source_path = kb_dir / "texts/doc.txt"
+    manifest_path = kb_dir / ".manifest.json"
+    manifest_path.write_text('{"texts/doc.txt":"outdated"}', "utf-8")
+    store = manager._get_store("kb1")
+    await store.add_chunks(
+        ["old contents"], [[0.1, 0.2]], {"source": "texts/doc.txt", "kb": "kb1"}
+    )
+    original_read = Path.read_text
+
+    def unreadable(path: Path, *args: Any, **kwargs: Any) -> str:
+        if path == source_path:
+            raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid")
+        return original_read(path, *args, **kwargs)
+
+    def failed_upsert(**kwargs: Any) -> None:
+        raise RuntimeError("upsert failed")
+
+    with monkeypatch.context() as failure_patch:
+        if failure == "read":
+            failure_patch.setattr(Path, "read_text", unreadable)
+        elif failure == "embed":
+            failure_patch.setattr(
+                embedder,
+                "embed",
+                AsyncMock(side_effect=TimeoutError("embedding failed")),
+            )
+        else:
+            failure_patch.setattr(store._collection, "upsert", failed_upsert)
+        if failure == "read":
+            assert await manager.embed_knowledge_base("kb1") == 0
+        else:
+            with pytest.raises((TimeoutError, RuntimeError), match="failed"):
+                await manager.embed_knowledge_base("kb1")
+        assert store._collection.get(where={"source": "texts/doc.txt"})[
+            "documents"
+        ] == ["old contents"]
+        assert json.loads(manifest_path.read_text("utf-8")) == {
+            "texts/doc.txt": "outdated"
+        }
+
+    assert await manager.embed_knowledge_base("kb1") == 1
+    assert store._collection.get(where={"source": "texts/doc.txt"})["documents"] == [
+        "new contents"
+    ]
+    assert json.loads(manifest_path.read_text("utf-8"))["texts/doc.txt"] != "outdated"
+
+
+async def test_source_replacement_removes_stale_chunks_only_after_success(
+    tmp_path: Path,
+) -> None:
+    store = KnowledgeStore("knowledge_test", tmp_path / "chroma")
+    await store.add_chunks(
+        ["keep", "remove"], [[0.1, 0.2], [0.2, 0.3]], {"source": "a.txt"}
+    )
+    await store.add_chunks(["remove"], [[0.2, 0.3]], {"source": "b.txt"})
+
+    assert (
+        await store.add_chunks(
+            ["keep"], [[0.3, 0.4]], {"source": "a.txt"}, replace_source=True
+        )
+        == 1
+    )
+    assert store._collection.get(where={"source": "a.txt"})["documents"] == ["keep"]
+    assert store._collection.get(where={"source": "b.txt"})["documents"] == ["remove"]
+
+
+async def test_empty_file_update_removes_real_previous_chunks(tmp_path: Path) -> None:
+    manager, embedder = _make_manager(tmp_path)
+    kb_dir = _make_kb(tmp_path, "kb1", {"doc.txt": "   \n"})
+    store = manager._get_store("kb1")
+    await store.add_chunks(["old"], [[0.1, 0.2]], {"source": "texts/doc.txt"})
+
+    assert await manager.embed_knowledge_base("kb1") == 0
+    assert not store._collection.get(where={"source": "texts/doc.txt"})["ids"]
+    assert "texts/doc.txt" in json.loads((kb_dir / ".manifest.json").read_text("utf-8"))
+    embedder.embed.assert_not_awaited()
+
+
 async def test_semantic_search_missing_kb_does_not_create_store(tmp_path: Path) -> None:
     manager, embedder = _make_manager(tmp_path)
     results = await manager.semantic_search("missing", "hello")

From 913e075cf600dd95d89727f26468338e8d56b2ab Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:13:22 +0800
Subject: [PATCH 024/121] fix(webui): allow remote chat images under image CSP

---
 docs/management-api.md             |  2 +-
 docs/webui-guide.md                |  2 +-
 src/Undefined/webui/app.py         |  2 +-
 tests/test_webui_csp_images.py     | 80 ++++++++++++++++++++++++++++++
 tests/test_webui_management_api.py |  5 +-
 5 files changed, 87 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_webui_csp_images.py

diff --git a/docs/management-api.md b/docs/management-api.md
index b89375ac..4468566a 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -341,7 +341,7 @@ Content-Type: multipart/form-data
 
 `runtime/chat/files` 仍保留为旧 WebUI 浏览器文件缓存兼容路径；新客户端和新 WebChat 功能应使用 `runtime/chat/attachments`。其 `runtime/chat/file?id=...` 下载响应支持 gzip 协商，可压缩的文本 / HTML 文件会保留 MIME、UTF-8 charset 和附件下载头。
 
-WebUI 内嵌聊天渲染 `<attachment uid="..."/>` / `<pic uid="..."/>` 图片时会把 Runtime 返回的 `/api/v1/chat/attachments/{uid}/preview` 规整为 Management 代理路径 `/api/runtime/chat/attachments/{uid}/preview`，浏览器不直接请求 Runtime API。普通 Markdown 图片（如 `![Image #1](https://...)`）仍由前端安全 renderer 输出可点击预览的 `<img>`，不走附件代理。
+WebUI 内嵌聊天渲染 `<attachment uid="..."/>` / `<pic uid="..."/>` 图片时会把 Runtime 返回的 `/api/v1/chat/attachments/{uid}/preview` 规整为 Management 代理路径 `/api/runtime/chat/attachments/{uid}/preview`，浏览器不直接请求 Runtime API。普通 Markdown 图片（如 `![Image #1](https://...)`）仍由前端安全 renderer 输出可点击预览的 `<img>`，浏览器直接加载 HTTP/HTTPS 图片，不走附件代理。WebUI CSP 的 `img-src` 允许 HTTP/HTTPS 来源；脚本与 API 请求继续受原有 `script-src` / `connect-src` 限制。
 
 ### `runtime/chat/jobs/{job_id}/events`
 
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index e5c02379..d9a54fb4 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -156,7 +156,7 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - 旧版 WebChat 历史会在首次打开时自动迁移到默认会话。迁移完成后会写入标记文件，之后不会重复迁移；即使删除该默认会话，也不会再从旧历史文件恢复。未选择会话的旧接口调用会按需创建一个空的默认会话以保持向后兼容。
 - 会话标题先使用第一条用户消息的前若干字符作为临时标题；当会话已有首问和首答后，后端会使用 chat model 根据首问 + 首答生成正式标题。手动重命名的标题不会被自动生成覆盖；临时或生成失败的标题会在后续能处理时继续尝试。
 - 支持文本、图片和文件消息。图片或文件可通过 `+` 选择，也可直接粘贴到输入框；粘贴只会加入待发送附件条，不会立即发送，点击发送或按 Enter 时才随同当前文本进入同一条 WebChat 消息。无待发送附件时输入框会占满可用宽度；添加附件后右侧预览轨道随数量平滑展开，图片显示缩略图，附件较多时输入框保持最小可用宽度并压缩预览卡片，避免输入区跳动。移动端会把引用和附件预览轨道放到输入框上方，保证正文输入和发送按钮不被挤压。
-- AI 回复支持 Markdown 渲染，Markdown 内的常见 HTML 片段会经过 WebUI 白名单净化后自动渲染；完整 HTML 文档或独立块级 HTML 片段会先净化再直渲染，避免被 Markdown 缩进规则误判成代码块。脚本、事件属性、危险协议、危险样式以及 `head` / `style` 等文档元信息会被剥离。聊天中的图片可点击放大查看，支持点击遮罩、关闭按钮或按 `Esc` 退出。代码块使用本地随包的 highlight.js 做多语言语法高亮，不依赖外部 CDN；显式语言优先，未知语言会自动检测，库不可用时回退为安全转义文本。较长代码块默认以固定高度折叠，代码区内部可滚动，可用常驻工具栏展开 / 折叠，复制和运行按钮始终可见。可运行的 HTML 代码块会额外显示“运行”，在前端沙箱 iframe 中本地预览完整 HTML/CSS/JS，不调用后端执行；预览环境允许 inline script 以支持完整 HTML 交互，但不允许 `unsafe-eval`，安全边界依赖 WebUI CSP 和 iframe sandbox。预览小窗可拖动位置并调整大小，窗口尺寸变化时会自动保持在可见区域。HTML 预览面板可关闭，也可进入选择模式：第一次点击 iframe 内元素只预览并锁定引用范围，第二次点击确认后才把对应 HTML 片段加入待引用区。
+- AI 回复支持 Markdown 渲染，Markdown 内的常见 HTML 片段会经过 WebUI 白名单净化后自动渲染；完整 HTML 文档或独立块级 HTML 片段会先净化再直渲染，避免被 Markdown 缩进规则误判成代码块。脚本、事件属性、危险协议、危险样式以及 `head` / `style` 等文档元信息会被剥离。聊天中的图片可点击放大查看，支持点击遮罩、关闭按钮或按 `Esc` 退出；普通 Markdown 远端图片由浏览器直接加载 HTTP/HTTPS 来源，附件图片仍通过 Management 代理预览。代码块使用本地随包的 highlight.js 做多语言语法高亮，不依赖外部 CDN；显式语言优先，未知语言会自动检测，库不可用时回退为安全转义文本。较长代码块默认以固定高度折叠，代码区内部可滚动，可用常驻工具栏展开 / 折叠，复制和运行按钮始终可见。可运行的 HTML 代码块会额外显示“运行”，在前端沙箱 iframe 中本地预览完整 HTML/CSS/JS，不调用后端执行；预览环境允许 inline script 以支持完整 HTML 交互，但不允许 `unsafe-eval`，安全边界依赖 WebUI CSP 和 iframe sandbox。预览小窗可拖动位置并调整大小，窗口尺寸变化时会自动保持在可见区域。HTML 预览面板可关闭，也可进入选择模式：第一次点击 iframe 内元素只预览并锁定引用范围，第二次点击确认后才把对应 HTML 片段加入待引用区。
 - WebUI 场景下，代码优先直接作为聊天回复输出，不要默认转成文件附件；只有用户明确要求文件交付、代码过长不适合聊天展示，或确需附件工作流时才使用文件。所有代码块都应显式标注语言，例如 ` ```python `、` ```javascript `、` ```html `、` ```bash `，不确定语言时用 ` ```text `。
 - AI 消息支持引用：可引用整条 AI 消息、选中的某段文字，或 HTML 预览中点选的元素。引用会显示在输入框右侧的待发送引用条中，可在发送前移除；实际发送时不会新增接口或附件，而是自动在用户消息前拼接为 Markdown `>` 引用块，例如 `> 引用 AI:`，随后和文本、图片、文件一起进入同一条 WebChat job 消息。发送后的引用块会像代码块一样折叠显示，展开后内部固定高度并可滚动。发送失败时待引用内容会保留，发送成功后清空。
 - 默认加载最新 50 条消息并滚动到底部；向上滚动到顶部会按后端返回的 `next_before` 游标懒加载更早历史，并保持原视口偏移，避免一次性恢复大量工具块造成卡顿。“自动滚动到底部”开关默认开启并保存在浏览器本地，关闭后 AI 回复、工具 / Agent 状态和 AI 阶段刷新不会打断当前位置；首次加载和主动发送新消息仍会定位到底部。系统开启减少动态效果时，聊天滚动会改为即时跳转。
diff --git a/src/Undefined/webui/app.py b/src/Undefined/webui/app.py
index f9dfdb8d..857f896b 100644
--- a/src/Undefined/webui/app.py
+++ b/src/Undefined/webui/app.py
@@ -34,7 +34,7 @@
     "script-src 'self' 'nonce-{nonce}'; "
     "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "
     "font-src 'self' https://fonts.gstatic.com data:; "
-    "img-src 'self' data: blob:; "
+    "img-src 'self' data: blob: http: https:; "
     "connect-src 'self'; "
     "base-uri 'self'; "
     "frame-ancestors 'none'"
diff --git a/tests/test_webui_csp_images.py b/tests/test_webui_csp_images.py
new file mode 100644
index 00000000..ea8bf1bf
--- /dev/null
+++ b/tests/test_webui_csp_images.py
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import base64
+from html import escape
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import make_mocked_request
+from playwright.async_api import Error, Route, async_playwright
+
+from test_webui_runtime_chat_behavior import run_scenario
+from Undefined.render import _is_missing_playwright_browser
+from Undefined.webui.app import security_headers_middleware
+
+
+@pytest.mark.parametrize("scheme", ["http", "https"])
+async def test_rendered_remote_image_loads_under_actual_webui_csp(scheme: str) -> None:
+    rendered = run_scenario("markdown_sanitizes_unsafe_content")
+    source = next(
+        image["src"]
+        for image in rendered["images"]
+        if image["src"].startswith("https:")
+    )
+    image_url = source.replace("https:", f"{scheme}:", 1)
+    page_url = "http://management.example.test/index"
+    script_url = "https://script.example.test/blocked.js"
+    fetch_url = "https://api.example.test/blocked"
+    html = (
+        f'<img id="remote" src="{escape(image_url, quote=True)}">'
+        f'<script src="{script_url}"></script>'
+    )
+
+    async def handler(request: web.Request) -> web.StreamResponse:
+        return web.Response(text=html, content_type="text/html")
+
+    response = await security_headers_middleware(
+        make_mocked_request("GET", "/"), handler
+    )
+    csp = response.headers["Content-Security-Policy"]
+    intercepted: list[str] = []
+    pixel = base64.b64decode(
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jZrQAAAAASUVORK5CYII="
+    )
+
+    async def fulfill(route: Route) -> None:
+        intercepted.append(route.request.url)
+        if route.request.url == page_url:
+            await route.fulfill(
+                status=200,
+                content_type="text/html",
+                headers={"Content-Security-Policy": csp},
+                body=html,
+            )
+        else:
+            await route.fulfill(status=200, content_type="image/png", body=pixel)
+
+    async with async_playwright() as playwright:
+        try:
+            browser = await playwright.chromium.launch(headless=True)
+        except Error as error:
+            if _is_missing_playwright_browser(error):
+                pytest.skip(
+                    "Run `uv run playwright install chromium` for CSP browser tests"
+                )
+            raise
+        try:
+            page = await browser.new_page()
+            await page.route("**/*", fulfill)
+            await page.goto(page_url, wait_until="load")
+            assert await page.locator("#remote").evaluate(
+                "image => image.complete && image.naturalWidth === 1"
+            )
+            assert await page.evaluate(
+                "url => fetch(url).then(() => false).catch(() => true)", fetch_url
+            )
+            assert image_url in intercepted
+            assert script_url not in intercepted
+            assert fetch_url not in intercepted
+        finally:
+            await browser.close()
diff --git a/tests/test_webui_management_api.py b/tests/test_webui_management_api.py
index b4d330bd..743e84ca 100644
--- a/tests/test_webui_management_api.py
+++ b/tests/test_webui_management_api.py
@@ -1214,7 +1214,10 @@ async def _handler(_request: web.Request) -> web.StreamResponse:
     request = make_mocked_request("GET", "/")
     response = await webui_app.security_headers_middleware(request, _handler)
 
-    assert "img-src 'self' data: blob:;" in response.headers["Content-Security-Policy"]
+    assert (
+        "img-src 'self' data: blob: http: https:;"
+        in response.headers["Content-Security-Policy"]
+    )
 
 
 async def test_non_static_responses_have_no_explicit_cache_control() -> None:

From a202c20e205915f9877d32752d02d30983b3afdb Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:15:42 +0800
Subject: [PATCH 025/121] fix(automations): finish pending saves before
 propagating cancellation

---
 docs/automations.md                       |  2 +-
 src/Undefined/automations/storage.py      | 23 ++++++++++++-----------
 tests/test_automation_storage_ordering.py | 17 ++++++++++++-----
 3 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/docs/automations.md b/docs/automations.md
index f153491a..722ab6de 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -91,7 +91,7 @@
 
 启动时若还没有 `data/automations.json` 但存在旧的 `scheduled_tasks.json`，会自动把旧任务转换为流程图格式写入新文件；旧文件保留不动，之后也不再双写。旧 `/api/v1/schedules` 接口与 `scheduler.*` 工具已下线，统一使用 `/api/v1/automations` 与 `automation.*`。
 
-任务编辑、删除与运行结果的保存共用串行写入锁，每次写入冻结完整快照并原子替换文件。并发保存不会让旧快照覆盖后续删除或新增；保存期间收到取消时，会先等磁盘写入完成再释放锁并传播取消。
+任务编辑、删除与运行结果的保存共用串行写入锁，每次写入冻结完整快照并原子替换文件。并发保存不会让旧快照覆盖后续删除或新增；等待保存锁或写入期间收到取消时，已发生的内存变更仍会完成持久化，再释放锁并传播取消。
 
 ## 配置与限制
 
diff --git a/src/Undefined/automations/storage.py b/src/Undefined/automations/storage.py
index c830f0b6..62f9402c 100644
--- a/src/Undefined/automations/storage.py
+++ b/src/Undefined/automations/storage.py
@@ -62,17 +62,18 @@ def load_tasks(self) -> dict[str, Any]:
     async def save_all(self, tasks: dict[str, Any]) -> None:
         from Undefined.utils import io
 
-        async with self._save_lock:
-            data_to_save: dict[str, Any] = {}
-            for task_id, task_info in tasks.items():
-                if isinstance(task_info, dict):
-                    data_to_save[str(task_id)] = deepcopy(task_info)
-                else:
-                    logger.warning("[自动化] 跳过未知任务格式: %s", task_id)
-            await io.run_cancellation_safe(
-                io.write_json(self.path, data_to_save, use_lock=True)
-            )
-            logger.info("[自动化] 已保存 %s 条到 %s", len(data_to_save), self.path)
+        async def save_snapshot() -> None:
+            async with self._save_lock:
+                data_to_save: dict[str, Any] = {}
+                for task_id, task_info in tasks.items():
+                    if isinstance(task_info, dict):
+                        data_to_save[str(task_id)] = deepcopy(task_info)
+                    else:
+                        logger.warning("[自动化] 跳过未知任务格式: %s", task_id)
+                await io.write_json(self.path, data_to_save, use_lock=True)
+                logger.info("[自动化] 已保存 %s 条到 %s", len(data_to_save), self.path)
+
+        await io.run_cancellation_safe(save_snapshot())
 
     def _write_json_sync(self, path: Path, data: dict[str, Any]) -> None:
         from Undefined.utils.io import write_json_sync
diff --git a/tests/test_automation_storage_ordering.py b/tests/test_automation_storage_ordering.py
index 2a2bdebc..eeae1c45 100644
--- a/tests/test_automation_storage_ordering.py
+++ b/tests/test_automation_storage_ordering.py
@@ -16,9 +16,9 @@
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("cancel_first", [False, True])
+@pytest.mark.parametrize("cancel_when", ["none", "writing", "waiting"])
 async def test_running_task_save_cannot_restore_concurrently_deleted_task(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, cancel_first: bool
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, cancel_when: str
 ) -> None:
     storage = AutomationStorage(tmp_path / "automations.json", tmp_path / "legacy.json")
     service = AutomationService(
@@ -46,19 +46,26 @@ async def gated_write(path: Path | str, data: Any, use_lock: bool = True) -> Non
     second: asyncio.Task[bool] | None = None
     try:
         await asyncio.wait_for(started.wait(), 1)
-        if cancel_first:
+        if cancel_when == "writing":
             first.cancel()
         second = asyncio.create_task(service.remove_task("b"))
         await asyncio.sleep(0)
         assert "b" not in service.tasks
         assert len(writes) == 1
+        if cancel_when == "waiting":
+            second.cancel()
+            await asyncio.sleep(0)
+            assert not second.done()
         release.set()
         results = await asyncio.gather(first, second, return_exceptions=True)
-        if cancel_first:
+        if cancel_when == "writing":
             assert isinstance(results[0], asyncio.CancelledError)
         else:
             assert results[0] is None
-        assert results[1] is True
+        if cancel_when == "waiting":
+            assert isinstance(results[1], asyncio.CancelledError)
+        else:
+            assert results[1] is True
         saved = json.loads(storage.path.read_text("utf-8"))
         assert set(saved) == {"a"}
         assert saved["a"]["current_executions"] == 1

From c5f6cd4cccbd4359bcd22e41d4b34716c24b4a63 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:15:45 +0800
Subject: [PATCH 026/121] fix(scripts): keep reembedding dry runs read-only

---
 docs/cognitive-memory.md               |   2 +-
 scripts/README.md                      |   6 +-
 scripts/reembed_cognitive.py           | 106 ++++++++++++++--------
 tests/test_reembed_cognitive_script.py | 118 ++++++++++++++++++++++++-
 4 files changed, 192 insertions(+), 40 deletions(-)

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
index c1e87df1..d37b460e 100644
--- a/docs/cognitive-memory.md
+++ b/docs/cognitive-memory.md
@@ -447,7 +447,7 @@ data/cognitive/
 
 更换嵌入模型（维度变化或模型升级）后，需要对向量库进行全量重嵌入。详见 [`scripts/reembed_cognitive.py`](../scripts/reembed_cognitive.py)。
 
-向量维度发生变化时脚本会先读全量记录、再删除并重建 collection 后写回（ChromaDB 定维后无法原地改维，直接 upsert 异维向量会失败）；建议先 `--dry-run` 确认维度变化与记录数。
+向量维度发生变化时脚本先把新向量写入临时 collection，全部完成并校验后才删除旧库并换名（ChromaDB 定维后无法原地改维，直接 upsert 异维向量会失败）。建议先 `--dry-run` 确认维度变化与记录数：预览在系统临时目录的完整副本上读取，源 Chroma 文件和 collection 不会被修改，也不会清理或换名遗留的临时 collection；仍会调用嵌入 API，并可能记录 token 用量。请预留副本所需的临时磁盘空间，并按以下步骤停止写入后运行。
 
 ```bash
 # 1. 先在 config.toml 中更新 [models.embedding] 为新模型配置
diff --git a/scripts/README.md b/scripts/README.md
index a8968496..98b514e0 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -65,7 +65,9 @@ python scripts/sync_config_template.py --stdout
 
 **原理**：ChromaDB 存储了完整的原文本（`documents`），脚本读取所有记录，用新模型重新计算向量后 upsert 覆写，metadata 保持不变。
 
-**维度变化**：collection 在首次写入时定维，异维 upsert 会直接报 `InvalidArgumentError`。脚本会先比较新旧向量维度，检测到变化时先读全量记录、再删除并重建 collection，最后按新维度写回；`--dry-run` 只提示会重建，不做任何写入。
+**维度变化**：collection 在首次写入时定维，异维 upsert 会直接报 `InvalidArgumentError`。脚本把新向量写入临时 collection，全部写完并校验记录数后才删除旧库、把临时库换名为正式库。实际运行会清理未完成的临时库，或在正式库缺失时恢复临时库。
+
+`--dry-run` 先复制向量库到系统临时目录，仅在副本上打开 Chroma 客户端，源向量库的数据和文件均不修改。它不会创建缺失的 collection、删除残留临时库或把临时库换名；若只有临时库，会读取其中的记录预览恢复后的重嵌入。预览仍会调用嵌入 API 计算向量，并可能记录 token 用量；需要足够临时磁盘空间保存完整副本。运行前停止机器人及其他写入该库的进程，保证复制和正式迁移读取一致的数据。
 
 **前置条件**：先在 `config.toml` 中将 `[models.embedding]` 更新为新模型配置。
 
@@ -82,7 +84,7 @@ uv run python scripts/reembed_cognitive.py --profiles-only
 # 自定义批大小（默认 32，降低可减小 API 压力）
 uv run python scripts/reembed_cognitive.py --batch-size 16
 
-# 模拟运行（不实际写入，用于验证配置和统计数量）
+# 模拟运行（不修改源 ChromaDB，用于验证配置和统计数量）
 uv run python scripts/reembed_cognitive.py --dry-run
 
 # 详细日志
diff --git a/scripts/reembed_cognitive.py b/scripts/reembed_cognitive.py
index 74f362fe..da368b88 100755
--- a/scripts/reembed_cognitive.py
+++ b/scripts/reembed_cognitive.py
@@ -26,7 +26,7 @@
     # 自定义批大小（默认 32）
     uv run python scripts/reembed_cognitive.py --batch-size 16
 
-    # 模拟运行（不实际写入）
+    # 模拟运行（在临时副本读取，不修改源 ChromaDB）
     uv run python scripts/reembed_cognitive.py --dry-run
 """
 
@@ -37,7 +37,10 @@
 import logging
 import sys
 import time
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from pathlib import Path
+from tempfile import TemporaryDirectory
 from typing import Any
 
 import chromadb
@@ -53,6 +56,11 @@
 from Undefined.config.models import EmbeddingModelConfig  # noqa: E402
 from Undefined.knowledge.embedder import Embedder  # noqa: E402
 from Undefined.token_usage_storage import TokenUsageStorage  # noqa: E402
+from Undefined.utils.io import (  # noqa: E402
+    copy_file_atomic,
+    ensure_dir,
+    iter_rglob_files,
+)
 
 logger = logging.getLogger("reembed_cognitive")
 
@@ -61,6 +69,7 @@
 
 # 维度迁移时临时 collection 的后缀
 _STAGING_SUFFIX = "__rebuild_tmp"
+_COPY_CHUNK_SIZE = 1024 * 1024
 
 
 def _staging_name(collection_name: str) -> str:
@@ -90,7 +99,7 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--dry-run",
         action="store_true",
-        help="模拟运行：计算向量但不写入 ChromaDB",
+        help="模拟运行：从临时副本读取并计算向量，不修改源 ChromaDB",
     )
     parser.add_argument(
         "--db-path",
@@ -380,6 +389,43 @@ def _build_embedder(config: Config) -> Embedder:
     return embedder
 
 
+@asynccontextmanager
+async def _open_chroma(db_path: Path, *, dry_run: bool) -> AsyncIterator[Any]:
+    """预览只打开临时副本，隔离客户端初始化、迁移或索引维护的写入。"""
+    if not dry_run:
+        yield chromadb.PersistentClient(path=str(db_path))
+        return
+    with TemporaryDirectory(prefix="undefined-reembed-preview-") as directory:
+        preview_path = Path(directory) / "chroma"
+        await ensure_dir(preview_path)
+        async for source in iter_rglob_files(db_path):
+            await copy_file_atomic(
+                source,
+                preview_path / source.relative_to(db_path),
+                chunk_size=_COPY_CHUNK_SIZE,
+            )
+        logger.info("dry-run：在临时副本读取，源 ChromaDB 不会被修改")
+        yield chromadb.PersistentClient(path=str(preview_path))
+
+
+def _load_collection(client: Any, name: str, *, dry_run: bool) -> Any | None:
+    if not dry_run:
+        _recover_stale_staging(client, name)
+        return client.get_or_create_collection(name, metadata={"hnsw:space": "cosine"})
+
+    names = {collection.name for collection in client.list_collections()}
+    staging_name = _staging_name(name)
+    if name in names:
+        if staging_name in names:
+            logger.info("dry-run：保留遗留临时 collection %s，不执行清理", staging_name)
+        return client.get_collection(name)
+    if staging_name in names:
+        logger.info("dry-run：读取 %s 预览恢复后的记录，不执行换名", staging_name)
+        return client.get_collection(staging_name)
+    logger.info("dry-run：collection %s 不存在，跳过且不创建", name)
+    return None
+
+
 async def _main(args: argparse.Namespace) -> None:
     config = Config.load(strict=False)
 
@@ -396,41 +442,29 @@ async def _main(args: argparse.Namespace) -> None:
         logger.error("ChromaDB 目录不存在: %s", db_path)
         sys.exit(1)
 
-    client = chromadb.PersistentClient(path=str(db_path))
-    embedder = _build_embedder(config)
-
     total_processed = 0
-
-    try:
-        if not args.profiles_only:
-            _recover_stale_staging(client, "cognitive_events")
-            events_col = client.get_or_create_collection(
-                "cognitive_events", metadata={"hnsw:space": "cosine"}
-            )
-            total_processed += await _reembed_collection(
-                events_col,
-                "cognitive_events",
-                embedder,
-                args.batch_size,
-                args.dry_run,
-                client,
-            )
-
-        if not args.events_only:
-            _recover_stale_staging(client, "cognitive_profiles")
-            profiles_col = client.get_or_create_collection(
-                "cognitive_profiles", metadata={"hnsw:space": "cosine"}
-            )
-            total_processed += await _reembed_collection(
-                profiles_col,
-                "cognitive_profiles",
-                embedder,
-                args.batch_size,
-                args.dry_run,
-                client,
-            )
-    finally:
-        await embedder.stop()
+    async with _open_chroma(Path(db_path), dry_run=args.dry_run) as client:
+        embedder = _build_embedder(config)
+        try:
+            collection_names = []
+            if not args.profiles_only:
+                collection_names.append("cognitive_events")
+            if not args.events_only:
+                collection_names.append("cognitive_profiles")
+            for name in collection_names:
+                collection = _load_collection(client, name, dry_run=args.dry_run)
+                if collection is None:
+                    continue
+                total_processed += await _reembed_collection(
+                    collection,
+                    name,
+                    embedder,
+                    args.batch_size,
+                    args.dry_run,
+                    client,
+                )
+        finally:
+            await embedder.stop()
 
     logger.info("全部完成，共处理 %d 条记录。", total_processed)
 
diff --git a/tests/test_reembed_cognitive_script.py b/tests/test_reembed_cognitive_script.py
index 38f27e31..53442533 100644
--- a/tests/test_reembed_cognitive_script.py
+++ b/tests/test_reembed_cognitive_script.py
@@ -2,7 +2,7 @@
 
 import importlib.util
 from pathlib import Path
-from types import ModuleType
+from types import ModuleType, SimpleNamespace
 from typing import Any, cast
 
 import chromadb
@@ -29,11 +29,15 @@ class _FixedDimEmbedder:
     def __init__(self, dimension: int) -> None:
         self._dimension = dimension
         self.calls: list[list[str]] = []
+        self.stopped = False
 
     async def embed(self, texts: list[str]) -> list[list[float]]:
         self.calls.append(list(texts))
         return [[0.1] * self._dimension for _ in texts]
 
+    async def stop(self) -> None:
+        self.stopped = True
+
 
 class _DriftingDimEmbedder:
     """首批返回 dim_a、之后返回 dim_b 的假嵌入器，模拟模型输出漂移。"""
@@ -137,6 +141,118 @@ async def test_reembed_dry_run_reports_dimension_change_without_writing(
     assert len(unchanged_sample["embeddings"][0]) == 3
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("name", ["cognitive_events", "cognitive_profiles"])
+@pytest.mark.parametrize("scenario", ["formal_and_staging", "only_staging", "missing"])
+async def test_main_dry_run_preserves_collections_and_source_files(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str, scenario: str
+) -> None:
+    module = _load_script_module()
+    db_path = tmp_path / "db"
+    persistent_client = chromadb.PersistentClient
+    source_client = persistent_client(path=str(db_path))
+    staging_name = f"{name}__rebuild_tmp"
+    if scenario == "formal_and_staging":
+        _seed_collection(source_client, name, dimension=3, count=2)
+    if scenario != "missing":
+        _seed_collection(source_client, staging_name, dimension=3, count=2)
+    names_before = {collection.name for collection in source_client.list_collections()}
+    files_before = {
+        path.relative_to(db_path): path.read_bytes()
+        for path in db_path.rglob("*")
+        if path.is_file()
+    }
+    opened_paths: list[Path] = []
+
+    class _ReadOnlyClient:
+        def __init__(self, client: Any) -> None:
+            self._client = client
+
+        def list_collections(self) -> list[Any]:
+            return cast(list[Any], self._client.list_collections())
+
+        def get_collection(self, collection_name: str) -> Any:
+            return self._client.get_collection(collection_name)
+
+        def get_or_create_collection(self, *args: Any, **kwargs: Any) -> Any:
+            raise AssertionError("dry-run 不能创建 collection")
+
+        def delete_collection(self, *args: Any, **kwargs: Any) -> None:
+            raise AssertionError("dry-run 不能删除 collection")
+
+    def _open_preview(*, path: str) -> _ReadOnlyClient:
+        preview_path = Path(path)
+        assert preview_path != db_path
+        opened_paths.append(preview_path)
+        return _ReadOnlyClient(persistent_client(path=path))
+
+    def _unexpected_recovery(*args: Any, **kwargs: Any) -> None:
+        raise AssertionError("dry-run 不能清理或换名 staging")
+
+    config = SimpleNamespace(
+        cognitive=SimpleNamespace(vector_store_path=str(db_path)),
+        resolve_embedding_model=lambda _feature: SimpleNamespace(
+            model_name="fake-embedding", dimensions=5
+        ),
+    )
+    embedder = _FixedDimEmbedder(5)
+    monkeypatch.setattr(module, "Config", SimpleNamespace(load=lambda **kwargs: config))
+    monkeypatch.setattr(module, "_build_embedder", lambda _config: embedder)
+    monkeypatch.setattr(module, "_recover_stale_staging", _unexpected_recovery)
+    monkeypatch.setattr(module.chromadb, "PersistentClient", _open_preview)
+    args = SimpleNamespace(
+        db_path=None,
+        events_only=name == "cognitive_events",
+        profiles_only=name == "cognitive_profiles",
+        batch_size=2,
+        dry_run=True,
+    )
+    await module._main(args)
+
+    assert {
+        path.relative_to(db_path): path.read_bytes()
+        for path in db_path.rglob("*")
+        if path.is_file()
+    } == files_before
+    assert {
+        collection.name for collection in source_client.list_collections()
+    } == names_before
+    assert embedder.stopped
+    assert len(embedder.calls) == (0 if scenario == "missing" else 1)
+    assert len(opened_paths) == 1
+    assert not opened_paths[0].exists()
+
+
+@pytest.mark.asyncio
+async def test_main_dry_run_does_not_initialize_an_empty_source_directory(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    module = _load_script_module()
+    db_path = tmp_path / "empty-db"
+    db_path.mkdir()
+    config = SimpleNamespace(
+        cognitive=SimpleNamespace(vector_store_path=str(db_path)),
+        resolve_embedding_model=lambda _feature: SimpleNamespace(
+            model_name="fake-embedding", dimensions=5
+        ),
+    )
+    embedder = _FixedDimEmbedder(5)
+    monkeypatch.setattr(module, "Config", SimpleNamespace(load=lambda **kwargs: config))
+    monkeypatch.setattr(module, "_build_embedder", lambda _config: embedder)
+    await module._main(
+        SimpleNamespace(
+            db_path=None,
+            events_only=False,
+            profiles_only=False,
+            batch_size=2,
+            dry_run=True,
+        )
+    )
+    assert list(db_path.iterdir()) == []
+    assert embedder.calls == []
+    assert embedder.stopped
+
+
 @pytest.mark.asyncio
 async def test_reembed_migration_leaves_no_staging_collection(
     tmp_path: Path,

From 2f4a73e8750c3f2e1b57332aa013a2dd2939da50 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:17:44 +0800
Subject: [PATCH 027/121] fix(onebot): collect message tasks when reconnect is
 cancelled

---
 ARCHITECTURE.md                           |  2 +-
 src/Undefined/onebot/client.py            | 41 +++++++++--------
 tests/test_onebot_connection_lifecycle.py | 54 +++++++++++++++++++++++
 3 files changed, 78 insertions(+), 19 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 06833845..0cd3a19d 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -886,7 +886,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 
 微信接入由主进程独立管理，不依赖 OneBot 是否在线。`WeixinService` 先校验帐号与 peer，再把已绑定来源映射为逻辑 QQ 私聊交给 `MessageHandler`；未知来源在写历史或调用 AI 之前进入隔离存储。`DeliveryAddress` 将逻辑身份与物理通道分离：`qq:<id>` 和 `wechat:<id>` 可共享同一个用户历史、认知记忆与权限，但发送器、消息合并 scope 和 transport 元数据保持通道隔离。自动化同样持久化规范 `address`，旧 `target_type + target_id` 在加载时转换为 `group:` 或 `qq:` 地址。
 
-OneBot 消息处理任务由客户端跨连接跟踪。网络断线只结束接收循环、通知未完成的 API 请求连接失败，不等待媒体下载等处理任务即可重连；已有处理任务继续运行。主动断开、停止或取消连接任务时，会取消并等待这些处理任务收尾，避免后台任务遗留。
+OneBot 消息处理任务由客户端跨连接跟踪。网络断线只结束接收循环、通知未完成的 API 请求连接失败，不等待媒体下载等处理任务即可重连；已有处理任务继续运行。主动断开、停止或取消连接任务时，会取消并等待这些处理任务收尾，连接建立或重连等待阶段收到取消也会执行同样的清理，避免后台任务遗留。
 
 ### "车站-列车" 队列模型
 
diff --git a/src/Undefined/onebot/client.py b/src/Undefined/onebot/client.py
index b05e6c48..3639b9e7 100644
--- a/src/Undefined/onebot/client.py
+++ b/src/Undefined/onebot/client.py
@@ -1067,24 +1067,29 @@ async def run_with_reconnect(self, reconnect_interval: float = 5.0) -> None:
         self._should_stop = False
         reconnect_count = 0
 
-        while not self._should_stop:
-            try:
-                if reconnect_count > 0:
-                    logger.info(f"[WebSocket] 正在尝试第 {reconnect_count} 次重连...")
-                await self.connect()
-                reconnect_count = 0  # 连接成功重置计数
-                await self.run()
-            except websockets.ConnectionClosed as e:
-                logger.warning(f"[WebSocket] 连接已断开: {e}")
-            except Exception as e:
-                logger.error(f"[WebSocket] 发生错误: {e}")
-
-            if self._should_stop:
-                break
-
-            reconnect_count += 1
-            logger.info(f"{reconnect_interval} 秒后尝试重连...")
-            await asyncio.sleep(reconnect_interval)
+        try:
+            while not self._should_stop:
+                try:
+                    if reconnect_count > 0:
+                        logger.info(
+                            f"[WebSocket] 正在尝试第 {reconnect_count} 次重连..."
+                        )
+                    await self.connect()
+                    reconnect_count = 0  # 连接成功重置计数
+                    await self.run()
+                except websockets.ConnectionClosed as e:
+                    logger.warning(f"[WebSocket] 连接已断开: {e}")
+                except Exception as e:
+                    logger.error(f"[WebSocket] 发生错误: {e}")
+
+                if self._should_stop:
+                    break
+
+                reconnect_count += 1
+                logger.info(f"{reconnect_interval} 秒后尝试重连...")
+                await asyncio.sleep(reconnect_interval)
+        finally:
+            await self._cancel_message_tasks()
 
     def stop(self) -> None:
         """停止运行"""
diff --git a/tests/test_onebot_connection_lifecycle.py b/tests/test_onebot_connection_lifecycle.py
index 15ec8473..584bb0af 100644
--- a/tests/test_onebot_connection_lifecycle.py
+++ b/tests/test_onebot_connection_lifecycle.py
@@ -105,3 +105,57 @@ async def handler(data: dict[str, Any]) -> None:
             await asyncio.wait_for(running, 1)
     assert cancelled.is_set()
     assert not client._tasks
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("phase", ["sleep", "connect"])
+async def test_reconnect_gap_cancellation_collects_previous_handlers(
+    monkeypatch: pytest.MonkeyPatch, phase: str
+) -> None:
+    client = OneBotClient("ws://example.invalid")
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+    gap = asyncio.Event()
+    connections = 0
+    original_run = client.run
+
+    async def handler(data: dict[str, Any]) -> None:
+        started.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelled.set()
+
+    async def connect() -> None:
+        nonlocal connections
+        connections += 1
+        if connections == 1:
+            client.ws = cast(Any, _WebSocket(started))
+        else:
+            gap.set()
+            await asyncio.Event().wait()
+
+    async def run() -> None:
+        await original_run()
+        if phase == "sleep":
+            gap.set()
+
+    client.set_message_handler(handler)
+    monkeypatch.setattr(client, "connect", connect)
+    monkeypatch.setattr(client, "run", run)
+    running = asyncio.create_task(
+        client.run_with_reconnect(reconnect_interval=60 if phase == "sleep" else 0)
+    )
+    try:
+        await asyncio.wait_for(gap.wait(), 1)
+        assert client._tasks
+        assert not cancelled.is_set()
+        running.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(running, 1)
+        assert cancelled.is_set()
+        assert not client._tasks
+    finally:
+        running.cancel()
+        await asyncio.gather(running, return_exceptions=True)
+        await client.disconnect()

From 83036d2c049d4b527ff8df405f24df8f1e3f04ea Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:19:49 +0800
Subject: [PATCH 028/121] fix(webui): apply validated settings without
 rereading config

---
 docs/configuration.md                  |  16 +++-
 docs/python-api.md                     |   2 +
 src/Undefined/config/webui_settings.py |  21 +++-
 src/Undefined/webui/app.py             |  15 ++-
 src/Undefined/webui/routes/_auth.py    |   9 +-
 tests/test_webui_config_hot_reload.py  | 128 +++++++++++++++++++++++++
 tests/test_webui_settings.py           |  43 ++++++++-
 7 files changed, 221 insertions(+), 13 deletions(-)
 create mode 100644 tests/test_webui_config_hot_reload.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 771f8c8d..146d5e6c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1207,9 +1207,12 @@ api_key = "replace-with-your-key"
 | `check_updates` | `true` | 打开 WebUI 时是否在后台检查 GitHub 正式 Release |
 
 关键行为：
-- 默认密码 `changeme` 禁止登录，必须先修改。
+
+- 默认密码 `changeme` 禁止登录，必须先修改；显式写入 `password = "changeme"` 也保持默认密码模式。
 - 未配置或为空时，会回退默认密码并标记为”默认密码模式”。
-- `webui.url/port/password/autostart_bot` 修改需重启 WebUI 进程（机器人主进程中也属于重启生效类）。
+- `webui.url` / `webui.port` 修改需重启 WebUI 进程，以重新绑定监听地址和端口。
+- `webui.password` 在配置成功加载后立即刷新 Management 的登录密码，无需重启 WebUI。
+- `webui.autostart_bot` 控制下一次 WebUI 启动时是否自动启动机器人；修改不会立即启动或停止当前机器人进程。
 - `check_updates` 支持热更新；关闭后只停止页面打开时的自动检查，概览页仍可手动检查。
 - `autostart_bot=true` 时，运行 `uv run Undefined-webui` 会自动拉起 bot 进程，无需手动点击启动按钮；与 WebUI 更新重启后的自动恢复机制（`pending_bot_autostart` marker）互不冲突。
 - `uv run deploy up` 在 `container` 与 `host` 模式下都会写入 `autostart_bot = false`；部署后先完成配置与 QQ 登录，再在 WebUI 点击“启动机器人”。
@@ -1439,6 +1442,7 @@ api_key = "replace-with-your-key"
 
 ### 5.2 明确“需重启”的字段
 以下变更会被记录为“需重启生效”：
+
 - `logging.level`
 - `logging.file_path`
 - `logging.max_size_mb`
@@ -1448,8 +1452,6 @@ api_key = "replace-with-your-key"
 - `onebot.token`
 - `webui.url`
 - `webui.port`
-- `webui.password`
-- `webui.autostart_bot`
 - `api.*`（`enabled/host/port/auth_key/openapi_enabled`）
 - `memes.blob_dir`
 - `memes.preview_dir`
@@ -1459,7 +1461,11 @@ api_key = "replace-with-your-key"
 - `naga.*`（`enabled/api_url/api_key/use_proxy/moderation_enabled/mode/allowed_group_ids/blocked_group_ids/allowed_private_ids/blocked_private_ids`）
 - `models.embedding` / `models.embedding.features.*` / `models.rerank`（嵌入与重排运行时在启动时构造，热更新只提示需重启）
 
+Management 的 WebUI 配置按 [§4.23](#423-webui) 的时机生效：密码和检查更新开关支持热更新，自动启动开关控制下次启动。机器人运行时日志可能仍把 `webui.password` / `webui.autostart_bot` 归为重启提示，这不表示 Management 必须重启才能使用新密码。
+
 ### 5.3 明确“会执行热应用”的字段
+
+- `webui.password` / `webui.check_updates`（Management 的登录密码与检查更新开关立即刷新）
 - `onebot.file_send_mode` / `onebot.file_send_host`（新投递读取快照；进行中投递及旧 URL 生命周期不变）
 - 模型发车间隔 / 模型名 / 模型池变更（队列间隔刷新）
 - `models.grok.model_name` / `models.grok.queue_interval_seconds`（队列间隔刷新）
@@ -1493,6 +1499,8 @@ api_key = "replace-with-your-key"
 
 TOML 语法错误、编码错误或读取失败会中止本次加载，热重载保留上次有效的完整配置，包括白名单、Runtime API 密钥和 WebUI 密码；已加载配置的文件被删除时也不会切换为默认值。修正文件并再次保存后会正常重载。`strict=False` 只放宽必填项校验，不允许把损坏的文件作为空配置使用。
 
+运行中的 WebUI 直接从本次已验证的 `Config` 快照刷新设置，不再次读取文件；即使文件随后被其他进程写坏或删除，也不会把密码重置为默认值。首次启动的独立 WebUI 设置加载仍允许用默认设置显示初始化页面，但默认密码始终禁止登录。
+
 热更新在共享的 `Config` 实例上逐字段就地生效，整个过程没有 `await`，同一事件循环内的读方不会在一次读取里看到“改了一半”的对象；跨 `await` 的多次读取仍可能分别落在变更前后，需要严格一致的快照时请在单次读取中取全所需字段。
 
 应用阶段按步骤隔离：单步抛错不会中断后续步骤，失败步骤会以 `error` 级日志逐条打印（`热更新步骤失败`），并在末尾汇总一条“热更新未完全生效（运行时状态与 config.toml 不一致）”。异步步骤（技能热重载、自动化并发、配置监听器重启）使用被强引用跟踪的后台任务，任务异常同样以 `error` 级日志输出（`热更新后台任务失败`）。配置订阅者回调抛错时记录失败回调名单，其余回调继续执行。
diff --git a/docs/python-api.md b/docs/python-api.md
index 6d7ef330..e42b380f 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -113,6 +113,8 @@ Python 显式 mapping / override  >  config.toml  >  环境变量  >  代码默
 
 `Config.load(strict=False)` 只放宽必填项校验，文件的 TOML 语法、编码或读取错误仍会抛出 `ValueError`。`ConfigManager.reload()` 加载失败时保留原配置；订阅者应用失败会记录日志并保留变更，下次重载相同内容也会再次通知。运行时热更新应用函数会在完成其余同步步骤后汇报失败，后台失败同样会进入重试。
 
+`WebUISettings.from_config(config, config_exists=...)` 从已验证的 Config 构建设置，不读文件；运行中的 WebUI 使用该入口刷新同一次重载的快照。`config_exists` 表示这份快照是否来自现存配置；显式或隐式的 `changeme` 都会标记为默认密码模式，禁止登录。独立 `load_webui_settings()` 保留首次启动的宽松解析和初始化默认值，不应拿它替代已验证的运行时快照。
+
 ### `Config.from_mapping`
 
 从内存 dict 构建配置，结构与 `config.toml` 一致：
diff --git a/src/Undefined/config/webui_settings.py b/src/Undefined/config/webui_settings.py
index 46f4303f..1372627b 100644
--- a/src/Undefined/config/webui_settings.py
+++ b/src/Undefined/config/webui_settings.py
@@ -4,10 +4,13 @@
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from .coercers import _coerce_bool, _coerce_int, _coerce_str, _normalize_str, _get_value
 
+if TYPE_CHECKING:
+    from .config_class import Config
+
 DEFAULT_WEBUI_URL = "127.0.0.1"
 DEFAULT_WEBUI_PORT = 8787
 DEFAULT_WEBUI_PASSWORD = "changeme"
@@ -25,6 +28,20 @@ class WebUISettings:
     using_default_password: bool
     config_exists: bool
 
+    @classmethod
+    def from_config(cls, config: Config, *, config_exists: bool) -> WebUISettings:
+        """从已验证的 Config 构建运行时设置，不重新读取配置文件。"""
+        password = config.webui_password or DEFAULT_WEBUI_PASSWORD
+        return cls(
+            url=config.webui_url,
+            port=config.webui_port,
+            password=password,
+            autostart_bot=config.webui_autostart_bot,
+            check_updates=config.webui_check_updates,
+            using_default_password=password == DEFAULT_WEBUI_PASSWORD,
+            config_exists=config_exists,
+        )
+
     @property
     def display_url(self) -> str:
         """用于日志和展示的格式化 URL。"""
@@ -72,6 +89,6 @@ def parse_webui_settings(data: dict[str, Any]) -> WebUISettings:
         password=password_normalized,
         autostart_bot=autostart_bot,
         check_updates=check_updates,
-        using_default_password=False,
+        using_default_password=password_normalized == DEFAULT_WEBUI_PASSWORD,
         config_exists=config_exists,
     )
diff --git a/src/Undefined/webui/app.py b/src/Undefined/webui/app.py
index 857f896b..9833ba3f 100644
--- a/src/Undefined/webui/app.py
+++ b/src/Undefined/webui/app.py
@@ -8,7 +8,13 @@
 from typing import Any, Awaitable, Callable
 from aiohttp import web
 
-from Undefined.config import load_webui_settings, get_config_manager, get_config
+from Undefined.config import (
+    Config,
+    WebUISettings,
+    load_webui_settings,
+    get_config_manager,
+    get_config,
+)
 from Undefined.utils.cors import is_allowed_cors_origin, normalize_origin
 from Undefined.utils import io as async_io
 from Undefined.utils.self_update import resolve_repo_root
@@ -302,7 +308,7 @@ def create_app(*, redirect_to_config_once: bool = False) -> web.Application:
     # 一次性客户端重定向提示（由 index 处理）
     app[REDIRECT_TO_CONFIG_ONCE_APP_KEY] = redirect_to_config_once
 
-    def _on_config_change(config: Any, changes: dict[str, Any]) -> None:
+    def _on_config_change(config: Config, changes: dict[str, Any]) -> None:
         webui_keys = {
             "webui_url",
             "webui_port",
@@ -314,7 +320,10 @@ def _on_config_change(config: Any, changes: dict[str, Any]) -> None:
             changes
         ):
             logger.info("[WebUI] 检测到 WebUI 配置变更，正在热重载设置...")
-            app[SETTINGS_APP_KEY] = load_webui_settings()
+            # 本次快照已成功读取；后续外部写入不能覆盖已验证的设置。
+            app[SETTINGS_APP_KEY] = WebUISettings.from_config(
+                config, config_exists=True
+            )
 
     config_manager.subscribe(_on_config_change)
 
diff --git a/src/Undefined/webui/routes/_auth.py b/src/Undefined/webui/routes/_auth.py
index bcab3ecc..ed4c0776 100644
--- a/src/Undefined/webui/routes/_auth.py
+++ b/src/Undefined/webui/routes/_auth.py
@@ -4,7 +4,7 @@
 from aiohttp.web_response import Response
 
 from Undefined.config.loader import CONFIG_PATH, DEFAULT_WEBUI_PASSWORD
-from Undefined.config import get_config_manager, load_webui_settings
+from Undefined.config import WebUISettings, get_config_manager
 from ._shared import (
     auth_capabilities,
     routes,
@@ -260,8 +260,11 @@ async def password_handler(request: web.Request) -> Response:
     CONFIG_PATH.write_text(
         render_toml(patched, comments=load_comment_map()), encoding="utf-8"
     )
-    get_config_manager().reload()
-    request.app[SETTINGS_APP_KEY] = load_webui_settings()
+    manager = get_config_manager()
+    manager.reload()
+    request.app[SETTINGS_APP_KEY] = WebUISettings.from_config(
+        manager.load(strict=False), config_exists=True
+    )
     get_session_store(request).clear()
 
     resp = web.json_response({"success": True, "message": "Password updated"})
diff --git a/tests/test_webui_config_hot_reload.py b/tests/test_webui_config_hot_reload.py
new file mode 100644
index 00000000..b7881621
--- /dev/null
+++ b/tests/test_webui_config_hot_reload.py
@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import make_mocked_request
+
+from Undefined.config import Config
+from Undefined.config.manager import ConfigManager
+from Undefined.webui import app as webui_app
+from Undefined.webui.routes import _auth
+from Undefined.webui.routes._shared import SESSION_STORE_APP_KEY, SETTINGS_APP_KEY
+
+
+def _manager_and_app(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> tuple[Path, ConfigManager, web.Application]:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text('[webui]\npassword="private-old"\n', encoding="utf-8")
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    monkeypatch.setattr(webui_app, "get_config_manager", lambda: manager)
+    return path, manager, webui_app.create_app()
+
+
+def test_management_invalid_reload_preserves_cached_settings(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path, manager, app = _manager_and_app(tmp_path, monkeypatch)
+    previous = app[SETTINGS_APP_KEY]
+    path.write_text("[webui\n", encoding="utf-8")
+    with pytest.raises(ValueError):
+        manager.reload(strict=False)
+    assert app[SETTINGS_APP_KEY] is previous
+    assert previous.password == "private-old"
+    assert not previous.using_default_password
+
+
+@pytest.mark.parametrize("external_write", ["malformed", "deleted"])
+def test_management_reload_uses_validated_snapshot_after_external_write(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, external_write: str
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text('[webui]\npassword="private-old"\n', encoding="utf-8")
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    monkeypatch.setattr(webui_app, "get_config_manager", lambda: manager)
+
+    def _write_after_config_loaded(_config: Config, _changes: dict[str, Any]) -> None:
+        if external_write == "malformed":
+            path.write_text("[webui\n", encoding="utf-8")
+        else:
+            path.unlink()
+
+    # 模拟另一进程在已验证读取后、WebUI 订阅回调前编辑文件。
+    manager.subscribe(_write_after_config_loaded)
+    app = webui_app.create_app()
+    valid = '[webui]\npassword="private-new"\nport=18787\ncheck_updates=false\n'
+    path.write_text(valid, encoding="utf-8")
+    assert manager.reload(strict=False)
+    settings = app[SETTINGS_APP_KEY]
+    assert settings.password == config.webui_password == "private-new"
+    assert settings.port == config.webui_port == 18787
+    assert not settings.check_updates
+    assert not settings.using_default_password
+    assert settings.config_exists
+
+    path.write_text(valid, encoding="utf-8")
+    assert manager.reload(strict=False) == {}
+    assert app[SETTINGS_APP_KEY].password == "private-new"
+
+
+@pytest.mark.asyncio
+async def test_management_hot_reload_explicit_default_password_rejects_login(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path, manager, app = _manager_and_app(tmp_path, monkeypatch)
+    path.write_text('[webui]\npassword="changeme"\n', encoding="utf-8")
+    manager.reload(strict=False)
+    assert app[SETTINGS_APP_KEY].using_default_password
+    request = make_mocked_request("POST", "/api/login", app=app)
+
+    async def _json() -> dict[str, str]:
+        return {"password": "changeme"}
+
+    monkeypatch.setattr(request, "json", _json)
+    response = await _auth.login_handler(request)
+    assert response.status == 403
+    payload = cast(web.Response, response).text
+    assert payload is not None
+    assert '"code": "default_password"' in payload
+
+
+@pytest.mark.asyncio
+async def test_password_change_keeps_validated_settings_after_external_write(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path, manager, app = _manager_and_app(tmp_path, monkeypatch)
+    monkeypatch.setattr(_auth, "get_config_manager", lambda: manager)
+
+    def _corrupt_after_webui_callback(
+        _config: Config, _changes: dict[str, Any]
+    ) -> None:
+        path.write_text("[webui\n", encoding="utf-8")
+
+    manager.subscribe(_corrupt_after_webui_callback)
+    sessions = app[SESSION_STORE_APP_KEY]
+    token = sessions.create()
+    request = make_mocked_request(
+        "POST", "/api/password", headers={"X-Auth-Token": token}, app=app
+    )
+
+    async def _json() -> dict[str, str]:
+        return {"current_password": "private-old", "new_password": "private-new"}
+
+    monkeypatch.setattr(request, "json", _json)
+    response = await _auth.password_handler(request)
+    assert response.status == 200
+    assert path.read_text(encoding="utf-8") == "[webui\n"
+    assert app[SETTINGS_APP_KEY].password == "private-new"
+    assert not app[SETTINGS_APP_KEY].using_default_password
+    assert not sessions.is_valid(token)
diff --git a/tests/test_webui_settings.py b/tests/test_webui_settings.py
index 2e689d26..bdad95da 100644
--- a/tests/test_webui_settings.py
+++ b/tests/test_webui_settings.py
@@ -7,7 +7,10 @@
 
 from pathlib import Path
 
-from Undefined.config.webui_settings import load_webui_settings
+import pytest
+
+from Undefined.config import Config
+from Undefined.config.webui_settings import WebUISettings, load_webui_settings
 
 
 def test_load_webui_settings_with_autostart_bot_true(tmp_path: Path) -> None:
@@ -188,3 +191,41 @@ def test_load_webui_settings_check_updates_can_be_disabled(tmp_path: Path) -> No
     settings = load_webui_settings(config_file)
 
     assert settings.check_updates is False
+
+
+def test_load_webui_settings_explicit_default_password_stays_disabled(
+    tmp_path: Path,
+) -> None:
+    config_file = tmp_path / "config.toml"
+    config_file.write_text('[webui]\npassword="changeme"\n', encoding="utf-8")
+    settings = load_webui_settings(config_file)
+    assert settings.password == "changeme"
+    assert settings.using_default_password is True
+    assert settings.config_exists is True
+
+
+@pytest.mark.parametrize("password", ["private-password", "changeme"])
+@pytest.mark.parametrize("config_exists", [False, True])
+def test_settings_from_config_preserves_snapshot_metadata(
+    password: str, config_exists: bool
+) -> None:
+    config = Config.from_mapping(
+        {
+            "webui": {
+                "url": "::1",
+                "port": 18787,
+                "password": password,
+                "autostart_bot": True,
+                "check_updates": False,
+            }
+        },
+        strict=False,
+    )
+    settings = WebUISettings.from_config(config, config_exists=config_exists)
+    assert settings.url == "::1"
+    assert settings.port == 18787
+    assert settings.password == password
+    assert settings.autostart_bot is True
+    assert settings.check_updates is False
+    assert settings.using_default_password is (password == "changeme")
+    assert settings.config_exists is config_exists

From 9dbf6f3d78072018a845f96b5958a0bd23396f4a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 12:39:41 +0800
Subject: [PATCH 029/121] fix(api): use a typed application key for runtime
 context

---
 docs/development.md           |  2 ++
 src/Undefined/api/app.py      |  4 +++-
 tests/test_runtime_api_app.py | 31 +++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_runtime_api_app.py

diff --git a/docs/development.md b/docs/development.md
index 94fa2249..b6345220 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -63,6 +63,8 @@ src/Undefined/
 - **Toolsets 开发专版**：[toolsets/README.md](../src/Undefined/skills/toolsets/README.md)
 - **Commands 开发专版**：[详细斜杠指令开发指南](slash-commands.md)
 
+Runtime API 和 WebUI 向 aiohttp `Application` 存储上下文等共享对象时，使用模块级 `web.AppKey` 常量并在所有读写处复用，保持类型安全并避免 `NotAppKeyWarning`。Runtime API 的应用构造回归测试会将该警告视为错误。
+
 ### CHANGELOG 维护约定
 
 - 仓库根目录的 `CHANGELOG.md` 是正式版本历史的唯一事实来源。
diff --git a/src/Undefined/api/app.py b/src/Undefined/api/app.py
index ea47393b..15bbb0a5 100644
--- a/src/Undefined/api/app.py
+++ b/src/Undefined/api/app.py
@@ -44,6 +44,8 @@
 
 logger = logging.getLogger(__name__)
 
+RUNTIME_API_CONTEXT_APP_KEY = web.AppKey("runtime_api_context", RuntimeAPIContext)
+
 
 class RuntimeAPIServer:
     def __init__(
@@ -145,7 +147,7 @@ async def _auth_middleware(
             return response
 
         app = web.Application(middlewares=[_auth_middleware])
-        app["runtime_api_context"] = self._context
+        app[RUNTIME_API_CONTEXT_APP_KEY] = self._context
         app.add_routes(
             [
                 web.get("/health", self._health_handler),
diff --git a/tests/test_runtime_api_app.py b/tests/test_runtime_api_app.py
new file mode 100644
index 00000000..a53a5358
--- /dev/null
+++ b/tests/test_runtime_api_app.py
@@ -0,0 +1,31 @@
+"""Regression coverage for Runtime API application construction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from Undefined.api import RuntimeAPIContext, RuntimeAPIServer, webchat_store
+from Undefined.api.app import RUNTIME_API_CONTEXT_APP_KEY
+
+
+@pytest.mark.filterwarnings("error::aiohttp.web_exceptions.NotAppKeyWarning")
+def test_application_preserves_context_without_app_key_warning(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(webchat_store, "WEBCHAT_CONVERSATIONS_DIR", tmp_path)
+    context = RuntimeAPIContext(
+        config_getter=SimpleNamespace,
+        onebot=None,
+        ai=None,
+        command_dispatcher=None,
+        queue_manager=None,
+        history_manager=None,
+    )
+    server = RuntimeAPIServer(context, host="127.0.0.1", port=0)
+
+    app = server._create_app()
+
+    assert app[RUNTIME_API_CONTEXT_APP_KEY] is context

From 61a9d4bc5501f6886aa2a47a734ceda8ee8d9379 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:00:06 +0800
Subject: [PATCH 030/121] fix(batcher): bind inflight replies to their batch
 token

---
 docs/message-batching.md                      |   5 +-
 src/Undefined/services/coordinator/group.py   |  18 ++-
 src/Undefined/services/coordinator/private.py |  16 ++-
 .../services/message_batcher/scheduler.py     |  30 +++--
 tests/test_message_batcher.py                 |  66 +++++++--
 tests/test_message_batcher_integration.py     | 126 ++++++++++++++++++
 6 files changed, 233 insertions(+), 28 deletions(-)

diff --git a/docs/message-batching.md b/docs/message-batching.md
index 726ef228..04f7b34a 100644
--- a/docs/message-batching.md
+++ b/docs/message-batching.md
@@ -145,10 +145,11 @@ allow_cancel_after_send = false
 - T2 预发送会给队列请求附带 `BatchDispatchToken`。新消息抢占时先取消旧 token；若旧请求已入队但尚未执行，`AICoordinator.execute_reply()` 会直接跳过，避免队列拥堵窗口里的陈旧回复。
 - T2 的 `flush_callback` 若异常或被取消，桶会从 `SPECULATING` 回滚到 `TYPING` 并换新 token，保留原 items 等 T1 正常重试，避免静默丢消息。
 - T1 到期时如果 batch 已经被 T2 投机发出，只负责结束 bucket/等待已知 inflight，不会再次调用 `flush_callback`，避免同一批消息重复入队。
-- `unregister_inflight(scope, sender_id, task)` 必须携带 task 身份并校验；旧任务的 `finally` 不会误清理新一轮已注册的 inflight。
+- inflight 注册必须携带当前批次的 `BatchDispatchToken`，并校验 token 对象身份与取消状态；同一发送者独立旁路的 `@bot`、拍一拍回复不会覆盖投机任务，也不会被后续批次补充误取消。
+- `unregister_inflight(scope, sender_id, task, token=...)` 同时校验 token 和 task 身份；旧任务的 `finally` 不会误清理新一轮已注册的 inflight。
 - `flush_all()` 在关停时设置 shutdown 标记，循环遍历所有桶执行等价 T1 路径，并 `await` 所有未完成的 flush task；若收尾过程中又出现新桶，会继续清空直到没有 pending bucket。shutdown 之后的新消息直接发车，不再开缓冲桶。
 - `MessageHandler.close()` 的顺序是：停止自动管线热重载 → `message_batcher.flush_all()` → `queue_manager.drain()` 等待已入队/在途回复自然收敛 → `queue_manager.stop()` → flush 历史落盘。
-- coordinator 在 `execute_reply` 入口调用 `register_inflight(scope, sender_id, task, ctx)`，在 `finally` 调 `unregister_inflight(...)`；`asyncio.CancelledError` 被识别为 "投机抢占"，仅记录信息日志且不重试。
+- coordinator 在执行回复时调用 `register_inflight(scope, sender_id, task, ctx, token=...)`，仅注册成功后才在 `finally` 注销同一 token 的任务；`asyncio.CancelledError` 被识别为 "投机抢占"，仅记录信息日志且不重试。
 - 主调用取消或等待超时会同步取消其 LLM 子请求：尚未执行或正在等待重试的子请求会跳过模型调用，已执行的模型任务会收到取消。已经发到上游的请求无法撤回，但不会继续排队重试或产生无人消费的新调用。
 
 ### 兼容回退
diff --git a/src/Undefined/services/coordinator/group.py b/src/Undefined/services/coordinator/group.py
index e07ea97d..4c88d518 100644
--- a/src/Undefined/services/coordinator/group.py
+++ b/src/Undefined/services/coordinator/group.py
@@ -13,7 +13,11 @@
 from Undefined.context import RequestContext
 from Undefined.context_resource_registry import collect_context_resources
 from Undefined.render import render_html_to_image, render_markdown_to_html
-from Undefined.services.message_batcher import BufferedMessage, make_scope
+from Undefined.services.message_batcher import (
+    BatchDispatchToken,
+    BufferedMessage,
+    make_scope,
+)
 from Undefined.utils.recent_messages import get_recent_messages_prefer_local
 from Undefined.utils.xml import (
     escape_xml_attr,
@@ -207,6 +211,10 @@ async def _execute_auto_reply(self, request: dict[str, Any]) -> None:
         )
         # 用于向 batcher 注册 inflight 任务（仅当本请求源自合并桶时生效）
         batcher_scope: str | None = make_scope(group_id=group_id) if group_id else None
+        batch_token_raw = request.get("_message_batcher_token")
+        batch_token = (
+            batch_token_raw if isinstance(batch_token_raw, BatchDispatchToken) else None
+        )
 
         async with RequestContext(
             request_type="group",
@@ -290,10 +298,10 @@ async def send_like_cb(uid: int, times: int = 1) -> None:
                     batcher is not None
                     and batcher_scope is not None
                     and current_task is not None
-                ):
-                    batcher.register_inflight(
-                        batcher_scope, sender_id, current_task, ctx
+                    and batcher.register_inflight(
+                        batcher_scope, sender_id, current_task, ctx, token=batch_token
                     )
+                ):
                     registered_task = current_task
                 try:
                     await self.ai.ask(
@@ -331,7 +339,7 @@ async def send_like_cb(uid: int, times: int = 1) -> None:
                         and registered_task is not None
                     ):
                         batcher.unregister_inflight(
-                            batcher_scope, sender_id, registered_task
+                            batcher_scope, sender_id, registered_task, token=batch_token
                         )
             except asyncio.CancelledError:
                 # 投机预发送被新消息抢占取消：不写错误日志、不重试
diff --git a/src/Undefined/services/coordinator/private.py b/src/Undefined/services/coordinator/private.py
index cdb6cf14..58635e62 100644
--- a/src/Undefined/services/coordinator/private.py
+++ b/src/Undefined/services/coordinator/private.py
@@ -19,7 +19,11 @@
 from Undefined.context import RequestContext
 from Undefined.context_resource_registry import collect_context_resources
 from Undefined.render import render_html_to_image, render_markdown_to_html
-from Undefined.services.message_batcher import BufferedMessage, make_scope
+from Undefined.services.message_batcher import (
+    BatchDispatchToken,
+    BufferedMessage,
+    make_scope,
+)
 from Undefined.utils.recent_messages import get_recent_messages_prefer_local
 from Undefined.utils.message_targets import DeliveryAddress, parse_delivery_address
 from Undefined.utils.message_reply import ReplyContext
@@ -187,6 +191,10 @@ async def _execute_private_reply(self, request: dict[str, Any]) -> None:
             raise ValueError("私聊投递地址与逻辑 QQ 身份不一致")
         channel = address.channel
         batcher_scope = str(request.get("batch_scope") or make_scope(user_id=user_id))
+        batch_token_raw = request.get("_message_batcher_token")
+        batch_token = (
+            batch_token_raw if isinstance(batch_token_raw, BatchDispatchToken) else None
+        )
 
         async with RequestContext(
             request_type="private",
@@ -315,8 +323,10 @@ async def send_private_cb(
                     batcher is not None
                     and batcher_scope is not None
                     and current_task is not None
+                    and batcher.register_inflight(
+                        batcher_scope, user_id, current_task, ctx, token=batch_token
+                    )
                 ):
-                    batcher.register_inflight(batcher_scope, user_id, current_task, ctx)
                     registered_task = current_task
                 typing_started = False
                 try:
@@ -375,7 +385,7 @@ async def send_private_cb(
                         and registered_task is not None
                     ):
                         batcher.unregister_inflight(
-                            batcher_scope, user_id, registered_task
+                            batcher_scope, user_id, registered_task, token=batch_token
                         )
                 if result:
                     scope_key = build_attachment_scope(
diff --git a/src/Undefined/services/message_batcher/scheduler.py b/src/Undefined/services/message_batcher/scheduler.py
index 30dcd4a0..f97d808f 100644
--- a/src/Undefined/services/message_batcher/scheduler.py
+++ b/src/Undefined/services/message_batcher/scheduler.py
@@ -305,34 +305,46 @@ def register_inflight(
         sender_id: int,
         task: asyncio.Task[Any],
         request_context: Any = None,
-    ) -> None:
+        *,
+        token: BatchDispatchToken | None,
+    ) -> bool:
         """coordinator 在 ``execute_reply`` 开头上报 inflight LLM 任务。
 
-        如果桶不存在或 phase 不是 SPECULATING，则忽略（说明这次 fire 不是投机的）。
+        只接受当前投机批次的 token，独立旁路请求或过期批次不能占用此桶。
         """
         key = (scope, sender_id)
         state = self._buckets.get(key)
-        if state is None:
-            return
-        if state.phase is not BatchPhase.SPECULATING:
-            return
+        if (
+            state is None
+            or state.phase is not BatchPhase.SPECULATING
+            or token is None
+            or token.cancelled
+            or state.dispatch_token is not token
+        ):
+            return False
         state.inflight = _InflightInfo(task=task, request_context=request_context)
         logger.debug(
             "[MessageBatcher] 注册 inflight 任务: scope=%s sender=%s",
             scope,
             sender_id,
         )
+        return True
 
     # 注销 inflight 任务
     def unregister_inflight(
-        self, scope: str, sender_id: int, task: asyncio.Task[Any]
+        self,
+        scope: str,
+        sender_id: int,
+        task: asyncio.Task[Any],
+        *,
+        token: BatchDispatchToken | None,
     ) -> None:
         """coordinator 在 ``execute_reply`` 结束（含异常/取消）时上报。"""
         key = (scope, sender_id)
         state = self._buckets.get(key)
-        if state is None:
+        if state is None or token is None or state.dispatch_token is not token:
             return
-        if state.inflight is not None and state.inflight.task is not task:
+        if state.inflight is None or state.inflight.task is not task:
             logger.debug(
                 "[MessageBatcher] 忽略过期 inflight 注销: scope=%s sender=%s phase=%s",
                 scope,
diff --git a/tests/test_message_batcher.py b/tests/test_message_batcher.py
index 5970bb74..98d48158 100644
--- a/tests/test_message_batcher.py
+++ b/tests/test_message_batcher.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from dataclasses import replace
 import time
 
 import pytest
@@ -42,6 +43,12 @@ def _make_item(
     )
 
 
+def _current_token(batcher: MessageBatcher) -> BatchDispatchToken:
+    token = batcher._buckets[("group:1", 100)].dispatch_token
+    assert token is not None
+    return token
+
+
 class _Recorder:
     def __init__(self) -> None:
         self.batches: list[list[BufferedMessage]] = []
@@ -388,7 +395,9 @@ async def slow_flush(items: list[BufferedMessage]) -> None:
     await asyncio.sleep(0.1)
     # 模拟 coordinator 上报 inflight
     inflight_task = next(iter(batcher._pending_tasks))
-    batcher.register_inflight("group:1", 100, inflight_task, fake_ctx)
+    batcher.register_inflight(
+        "group:1", 100, inflight_task, fake_ctx, token=_current_token(batcher)
+    )
     # 第二条消息到达，应取消 inflight
     await batcher.submit(_make_item(text="m2"))
     await asyncio.wait_for(cancelled.wait(), timeout=1.0)
@@ -421,7 +430,9 @@ async def flush(items: list[BufferedMessage]) -> None:
     await batcher.submit(_make_item(text="m1"))
     await asyncio.sleep(0.08)
     inflight_task = next(iter(batcher._pending_tasks))
-    batcher.register_inflight("group:1", 100, inflight_task, fake_ctx)
+    batcher.register_inflight(
+        "group:1", 100, inflight_task, fake_ctx, token=_current_token(batcher)
+    )
     # 新消息到达：投机已发过消息，inflight 不应被 cancel
     await batcher.submit(_make_item(text="m2"))
     # 等 inflight 自然完成
@@ -449,9 +460,10 @@ async def test_completed_speculation_does_not_reprocess_answered_items(
         await batcher.submit(_make_item(text="m1"))
         await batcher._handle_t2(("group:1", 100))
         inflight = asyncio.create_task(asyncio.sleep(0))
-        batcher.register_inflight("group:1", 100, inflight, fake_ctx)
+        token = _current_token(batcher)
+        batcher.register_inflight("group:1", 100, inflight, fake_ctx, token=token)
         await inflight
-        batcher.unregister_inflight("group:1", 100, inflight)
+        batcher.unregister_inflight("group:1", 100, inflight, token=token)
 
         await batcher.submit(_make_item(text="m2"))
         await batcher.flush_sender("group:1", 100)
@@ -494,7 +506,9 @@ async def flush(items: list[BufferedMessage]) -> None:
     await asyncio.sleep(0.08)
     assert batcher._pending_tasks
     inflight_task = next(iter(batcher._pending_tasks))
-    batcher.register_inflight("group:1", 100, inflight_task, fake_ctx)
+    batcher.register_inflight(
+        "group:1", 100, inflight_task, fake_ctx, token=_current_token(batcher)
+    )
 
     await batcher.submit(_make_item(text="m2"))
     # 正常情况下 cancel 信号会在 50ms 内传到 callback；超时即视为未取消
@@ -564,7 +578,9 @@ async def flush(items: list[BufferedMessage]) -> None:
     await batcher.submit(_make_item(text="m1"))
     await asyncio.wait_for(inflight_started.wait(), timeout=0.5)
     inflight_task = next(iter(batcher._pending_tasks))
-    batcher.register_inflight("group:1", 100, inflight_task, fake_ctx)
+    batcher.register_inflight(
+        "group:1", 100, inflight_task, fake_ctx, token=_current_token(batcher)
+    )
     # 等到 T1 触发，桶切到 FINALIZING 等 inflight
     await asyncio.sleep(0.12)
     # 此刻新消息进入 FINALIZING 分支，开新桶
@@ -701,13 +717,16 @@ async def enqueue_only(items: list[BufferedMessage]) -> None:
     try:
         await batcher.submit(_make_item(text="m1"))
         await asyncio.sleep(0.08)
-        batcher.register_inflight("group:1", 100, old_task, fake_ctx)
+        old_token = _current_token(batcher)
+        batcher.register_inflight("group:1", 100, old_task, fake_ctx, token=old_token)
 
         await batcher.submit(_make_item(text="m2"))
         await asyncio.sleep(0.08)
-        batcher.register_inflight("group:1", 100, new_task, fake_ctx)
+        new_token = _current_token(batcher)
+        batcher.register_inflight("group:1", 100, new_task, fake_ctx, token=new_token)
 
-        batcher.unregister_inflight("group:1", 100, old_task)
+        batcher.unregister_inflight("group:1", 100, old_task, token=old_token)
+        batcher.unregister_inflight("group:1", 100, new_task, token=old_token)
         snap = batcher.snapshot()
         assert snap["buckets"][0]["has_inflight"] is True
     finally:
@@ -716,6 +735,35 @@ async def enqueue_only(items: list[BufferedMessage]) -> None:
         await asyncio.gather(old_task, new_task, return_exceptions=True)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("invalid_token", ["missing", "same_fields", "cancelled"])
+async def test_inflight_registration_requires_current_token_identity(
+    invalid_token: str,
+) -> None:
+    batcher = MessageBatcher(
+        MessageBatcherConfig(enabled=True, window_seconds=60.0, pre_send_seconds=10.0),
+        _Recorder(),
+    )
+    task = asyncio.create_task(asyncio.sleep(60.0))
+    try:
+        await batcher.submit(_make_item())
+        await batcher._handle_t2(("group:1", 100))
+        current_token = _current_token(batcher)
+        token: BatchDispatchToken | None = current_token
+        if invalid_token == "missing":
+            token = None
+        elif invalid_token == "same_fields":
+            token = replace(current_token)
+        else:
+            current_token.cancel()
+        assert not batcher.register_inflight("group:1", 100, task, token=token)
+        assert batcher._buckets[("group:1", 100)].inflight is None
+    finally:
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        await batcher.flush_all()
+
+
 @pytest.mark.asyncio
 async def test_flush_all_loops_until_concurrent_bucket_is_flushed() -> None:
     """flush_all 快照后若 callback 又创建新桶，也应继续清空。"""
diff --git a/tests/test_message_batcher_integration.py b/tests/test_message_batcher_integration.py
index f638bcd7..4c8745a8 100644
--- a/tests/test_message_batcher_integration.py
+++ b/tests/test_message_batcher_integration.py
@@ -20,6 +20,7 @@
 from Undefined.handlers import MessageHandler
 from Undefined.services.coordinator import AICoordinator
 from Undefined.services.message_batcher import BatchDispatchToken, MessageBatcher
+from Undefined.services.queue_manager import QueueManager
 
 
 def _make_coordinator(
@@ -391,6 +392,131 @@ async def test_execute_reply_skips_cancelled_batch_token() -> None:
     execute_auto.assert_not_called()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("bypass", ["group_at", "group_poke", "private_poke"])
+async def test_bypass_reply_preserves_speculative_inflight_ownership(
+    bypass: str,
+) -> None:
+    coordinator, _mock_queue, batcher = _make_coordinator(window_seconds=60.0)
+    batcher.update_config(
+        MessageBatcherConfig(enabled=True, window_seconds=60.0, pre_send_seconds=10.0)
+    )
+    coordinator.config.bot_qq = 999
+    coordinator.config.get_context_recent_messages_limit = lambda: 0
+    coordinator.scheduler = None
+    sent: list[str] = []
+
+    async def send_message(_target: Any, message: str, **_kwargs: Any) -> None:
+        sent.append(message)
+
+    coordinator.sender = SimpleNamespace(
+        send_group_message=send_message,
+        send_address_message=send_message,
+        send_private_message=AsyncMock(),
+    )
+    coordinator.onebot = SimpleNamespace(
+        get_image=AsyncMock(), get_forward_msg=AsyncMock(), send_like=AsyncMock()
+    )
+    coordinator.ai.memory_storage = None
+    coordinator.ai.runtime_config = coordinator.config
+    started = {name: asyncio.Event() for name in ("old", "bypass", "new")}
+    release = {name: asyncio.Event() for name in started}
+    old_cancelled = asyncio.Event()
+    finish_old_cancel = asyncio.Event()
+    tasks: dict[str, asyncio.Task[Any]] = {}
+    requests: dict[str, dict[str, Any]] = {}
+
+    def request_name(question: str) -> str:
+        if "独立旁路" in question:
+            return "bypass"
+        return "new" if "批次补充" in question else "old"
+
+    async def ask(question: str, **kwargs: Any) -> None:
+        name = request_name(question)
+        current_task = asyncio.current_task()
+        assert current_task is not None
+        tasks[name] = current_task
+        started[name].set()
+        try:
+            await release[name].wait()
+        except asyncio.CancelledError:
+            if name == "old":
+                old_cancelled.set()
+                # 让旧请求的 finally 在新 token 注册之后执行。
+                await finish_old_cancel.wait()
+            raise
+        await kwargs["send_message_callback"](f"{name} reply")
+
+    async def execute(request: dict[str, Any]) -> None:
+        requests[request_name(request["full_question"])] = request
+        await coordinator.execute_reply(request)
+
+    coordinator.ai.ask = ask
+    coordinator._is_at_bot = lambda content: any(
+        item.get("type") == "at" for item in content
+    )
+    queue = QueueManager(ai_request_interval=0.0)
+    coordinator.queue_manager = queue
+    queue.start(execute)
+    scope = "private:100" if bypass == "private_poke" else "group:1"
+    key = (scope, 100)
+
+    async def submit(text: str, *, independent: bool = False) -> None:
+        if bypass == "private_poke":
+            await coordinator.handle_private_reply(100, text, [], is_poke=independent)
+        else:
+            content = (
+                [{"type": "at", "data": {"qq": "999"}}]
+                if independent and bypass == "group_at"
+                else []
+            )
+            await coordinator.handle_auto_reply(
+                1,
+                100,
+                text,
+                content,
+                is_poke=independent and bypass == "group_poke",
+            )
+
+    try:
+        await submit("旧批次")
+        await batcher._handle_t2(key)
+        await asyncio.wait_for(started["old"].wait(), timeout=1.0)
+        await submit("独立旁路", independent=True)
+        await asyncio.wait_for(started["bypass"].wait(), timeout=1.0)
+        assert "_message_batcher_token" not in requests["bypass"]
+        state = batcher._buckets[key]
+        assert state.inflight is not None
+        assert state.inflight.task is tasks["old"]
+
+        await submit("批次补充")
+        await asyncio.wait_for(old_cancelled.wait(), timeout=1.0)
+        assert not tasks["bypass"].done()
+        assert requests["old"]["_message_batcher_token"].cancelled
+        await batcher._handle_t2(key)
+        await asyncio.wait_for(started["new"].wait(), timeout=1.0)
+        finish_old_cancel.set()
+        with pytest.raises(asyncio.CancelledError):
+            await tasks["old"]
+        state = batcher._buckets[key]
+        assert state.inflight is not None
+        assert state.inflight.task is tasks["new"]
+
+        release["bypass"].set()
+        await tasks["bypass"]
+        assert state.inflight is not None
+        assert state.inflight.task is tasks["new"]
+        release["new"].set()
+        await tasks["new"]
+        assert sent == ["bypass reply", "new reply"]
+    finally:
+        finish_old_cancel.set()
+        for state in list(batcher._buckets.values()):
+            batcher._cancel_t1(state)
+            batcher._cancel_t2(state)
+        await queue.stop()
+
+
 @pytest.mark.asyncio
 async def test_message_handler_close_flushes_batcher_then_drains_queue() -> None:
     handler: Any = object.__new__(MessageHandler)

From 186f53ae7e4382bfb32ad82b3cefacf9803a9027 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:00:22 +0800
Subject: [PATCH 031/121] fix(cognitive): confine profile paths to their
 storage directory

---
 docs/python-api.md                            |   2 +
 src/Undefined/api/routes/cognitive.py         |   5 +-
 src/Undefined/cognitive/profile_storage.py    |  32 +++-
 .../skills/toolsets/cognitive/README.md       |   5 +-
 .../toolsets/cognitive/get_profile/handler.py |  11 +-
 tests/test_cognitive_profile_paths.py         | 155 ++++++++++++++++++
 6 files changed, 199 insertions(+), 11 deletions(-)
 create mode 100644 tests/test_cognitive_profile_paths.py

diff --git a/docs/python-api.md b/docs/python-api.md
index e42b380f..c86360bf 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -297,6 +297,8 @@ server = RuntimeAPIServer(RuntimeAPIContext(...))
 | `Undefined.api` | stable | `RuntimeAPIServer`, `RuntimeAPIContext` |
 | `Undefined.mcp` | subpackage | `MCPToolRegistry`, `MCPToolSetRegistry` |
 
+`ProfileStorage` 的所有读写、历史版本和合并锁操作只接受 `user` / `group` 实体类型，以及非空的单层实体 ID（不接受路径分隔符、`.` / `..` 或 Windows 盘符）。侧写文件与历史版本解析符号链接后必须仍位于 `base_path` 内，否则抛出 `ValueError`；Runtime 的侧写查询接口将这类错误转换为 HTTP 400。
+
 ---
 
 ## 相关文档
diff --git a/src/Undefined/api/routes/cognitive.py b/src/Undefined/api/routes/cognitive.py
index 66096994..57d803cc 100644
--- a/src/Undefined/api/routes/cognitive.py
+++ b/src/Undefined/api/routes/cognitive.py
@@ -75,7 +75,10 @@ async def cognitive_profile_handler(
     if not entity_type or not entity_id:
         return _json_error("entity_type/entity_id are required", status=400)
 
-    profile = await cognitive_service.get_profile(entity_type, entity_id)
+    try:
+        profile = await cognitive_service.get_profile(entity_type, entity_id)
+    except ValueError as exc:
+        return _json_error(str(exc), status=400)
     return web.json_response(
         {
             "entity_type": entity_type,
diff --git a/src/Undefined/cognitive/profile_storage.py b/src/Undefined/cognitive/profile_storage.py
index ac657363..e8798642 100644
--- a/src/Undefined/cognitive/profile_storage.py
+++ b/src/Undefined/cognitive/profile_storage.py
@@ -7,7 +7,7 @@
 import os
 import tempfile
 from datetime import datetime
-from pathlib import Path
+from pathlib import Path, PureWindowsPath
 from typing import Any
 
 from Undefined.utils.io import run_cancellation_safe
@@ -30,6 +30,7 @@ def __init__(self, base_path: str | Path, revision_keep: int = 5) -> None:
         )
 
     def _get_lock(self, entity_type: str, entity_id: str) -> asyncio.Lock:
+        self._validate_entity(entity_type, entity_id)
         # setdefault 原子插入：并发首次进入同一实体时双方拿到同一把锁，
         # 不会出现各自建锁、后建覆盖先建导致互斥失效
         return self._locks.setdefault(f"{entity_type}:{entity_id}", asyncio.Lock())
@@ -41,15 +42,38 @@ def merge_guard(self, entity_type: str, entity_id: str) -> asyncio.Lock:
         （后写覆盖先写，先前的观察永久丢失）。与文件写入锁分开，避免与
         `write_profile` 的锁重入死锁。锁的创建经 `dict.setdefault` 原子完成。
         """
+        self._validate_entity(entity_type, entity_id)
         return self._merge_locks.setdefault(
             f"{entity_type}:{entity_id}", asyncio.Lock()
         )
 
     def _profile_path(self, entity_type: str, entity_id: str) -> Path:
-        return self._base / f"{entity_type}s" / f"{entity_id}.md"
+        self._validate_entity(entity_type, entity_id)
+        return self._contained_path(self._base / f"{entity_type}s" / f"{entity_id}.md")
 
     def _history_dir(self, entity_type: str, entity_id: str) -> Path:
-        return self._base / "history" / entity_type / entity_id
+        self._validate_entity(entity_type, entity_id)
+        return self._contained_path(self._base / "history" / entity_type / entity_id)
+
+    @staticmethod
+    def _validate_entity(entity_type: str, entity_id: str) -> None:
+        if entity_type not in {"user", "group"}:
+            raise ValueError(f"非法的侧写实体类型: {entity_type!r}")
+        if (
+            not entity_id.strip()
+            or entity_id in {".", ".."}
+            or "/" in entity_id
+            or "\\" in entity_id
+            or "\x00" in entity_id
+            or PureWindowsPath(entity_id).drive
+        ):
+            raise ValueError(f"非法的侧写实体 ID: {entity_id!r}")
+
+    def _contained_path(self, path: Path) -> Path:
+        # 同时检查已存在的目录/文件符号链接，不能只过滤输入中的 ../。
+        if not path.resolve().is_relative_to(self._base.resolve()):
+            raise ValueError("侧写路径超出存储目录")
+        return path
 
     async def read_profile(self, entity_type: str, entity_id: str) -> str | None:
         p = self._profile_path(entity_type, entity_id)
@@ -169,7 +193,7 @@ async def read_revision(
     ) -> str | None:
         """读取指定历史版本内容；版本名取 `list_revisions` 的返回值。"""
         name = self._normalize_revision_name(revision)
-        path = self._history_dir(entity_type, entity_id) / name
+        path = self._contained_path(self._history_dir(entity_type, entity_id) / name)
 
         def _read() -> str | None:
             if not path.exists():
diff --git a/src/Undefined/skills/toolsets/cognitive/README.md b/src/Undefined/skills/toolsets/cognitive/README.md
index 3cd96298..8565738a 100644
--- a/src/Undefined/skills/toolsets/cognitive/README.md
+++ b/src/Undefined/skills/toolsets/cognitive/README.md
@@ -7,7 +7,9 @@
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `entity_type` | `string(user/group)` | 是 | 实体类型 |
-| `entity_id` | `string` | 是 | 用户ID或群ID |
+| `entity_id` | `string` | 是 | 用户ID或群ID，不接受路径、空值或 Windows 盘符 |
+
+实体类型仅支持 `user` / `group`。侧写与历史版本都只能访问配置的侧写存储目录；指向目录外的符号链接会被拒绝。非法查询在工具中返回参数错误，在 Runtime API 中返回 HTTP 400。
 
 ## search_events
 
@@ -33,4 +35,3 @@
 | `query` | `string` | 是 | 搜索关键词 |
 | `entity_type` | `string(user/group)` | 否 | 限定类型（可选） |
 | `top_k` | `integer` | 否 | 返回条数，默认8 |
-
diff --git a/src/Undefined/skills/toolsets/cognitive/get_profile/handler.py b/src/Undefined/skills/toolsets/cognitive/get_profile/handler.py
index 1a126634..77fdfb2a 100644
--- a/src/Undefined/skills/toolsets/cognitive/get_profile/handler.py
+++ b/src/Undefined/skills/toolsets/cognitive/get_profile/handler.py
@@ -5,8 +5,11 @@ async def execute(args: dict[str, Any], context: dict[str, Any]) -> str:
     cognitive_service = context.get("cognitive_service")
     if not cognitive_service or not cognitive_service.enabled:
         return "认知记忆系统未启用"
-    profile = await cognitive_service.get_profile(
-        entity_type=args["entity_type"],
-        entity_id=args["entity_id"],
-    )
+    try:
+        profile = await cognitive_service.get_profile(
+            entity_type=args["entity_type"],
+            entity_id=args["entity_id"],
+        )
+    except ValueError as exc:
+        return f"侧写查询参数无效: {exc}"
     return profile if profile else "暂无该实体的侧写信息"
diff --git a/tests/test_cognitive_profile_paths.py b/tests/test_cognitive_profile_paths.py
new file mode 100644
index 00000000..6daf45d8
--- /dev/null
+++ b/tests/test_cognitive_profile_paths.py
@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from aiohttp.test_utils import make_mocked_request
+
+from Undefined.api import RuntimeAPIContext
+from Undefined.api.routes.cognitive import cognitive_profile_handler
+from Undefined.cognitive.profile_storage import ProfileStorage
+from Undefined.skills.toolsets.cognitive.get_profile.handler import execute
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("entity_type", "entity_id"),
+    [
+        ("other", "10001"),
+        ("../user", "10001"),
+        ("user", ""),
+        ("user", "  "),
+        ("user", "."),
+        ("user", ".."),
+        ("user", "../../outside"),
+        ("user", "sub/name"),
+        ("user", "sub\\name"),
+        ("user", "C:outside"),
+        ("user", "name\x00"),
+    ],
+)
+async def test_profile_operations_reject_invalid_entities(
+    tmp_path: Path, entity_type: str, entity_id: str
+) -> None:
+    storage = ProfileStorage(tmp_path / "profiles")
+    outside = tmp_path / "outside.md"
+    outside.write_text("private", encoding="utf-8")
+    with pytest.raises(ValueError):
+        await storage.read_profile(entity_type, entity_id)
+    with pytest.raises(ValueError):
+        await storage.write_profile(entity_type, entity_id, "changed")
+    with pytest.raises(ValueError):
+        await storage.list_revisions(entity_type, entity_id)
+    with pytest.raises(ValueError):
+        await storage.read_revision(entity_type, entity_id, "revision.md")
+    with pytest.raises(ValueError):
+        await storage.restore_revision(entity_type, entity_id, "revision.md")
+    with pytest.raises(ValueError):
+        storage.merge_guard(entity_type, entity_id)
+    assert outside.read_text(encoding="utf-8") == "private"
+    assert not storage._locks
+    assert not storage._merge_locks
+    assert not (tmp_path / "profiles").exists()
+
+
+@pytest.mark.asyncio
+async def test_profile_operations_reject_absolute_id(tmp_path: Path) -> None:
+    outside = tmp_path / "outside.md"
+    outside.write_text("private", encoding="utf-8")
+    storage = ProfileStorage(tmp_path / "profiles")
+    entity_id = str(outside.with_suffix(""))
+    with pytest.raises(ValueError):
+        await storage.read_profile("user", entity_id)
+    with pytest.raises(ValueError):
+        await storage.write_profile("user", entity_id, "changed")
+    assert outside.read_text(encoding="utf-8") == "private"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("link_kind", ["directory", "file", "history", "revision"])
+async def test_profiles_reject_links_outside_storage(
+    tmp_path: Path, link_kind: str
+) -> None:
+    base = tmp_path / "profiles"
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    secret = outside / "10001.md"
+    secret.write_text("private", encoding="utf-8")
+    base.mkdir()
+    storage = ProfileStorage(base)
+    if link_kind == "directory":
+        (base / "users").symlink_to(outside, target_is_directory=True)
+    elif link_kind == "file":
+        (base / "users").mkdir()
+        (base / "users" / "10001.md").symlink_to(secret)
+    else:
+        history = base / "history" / "user" / "10001"
+        history.parent.mkdir(parents=True)
+        if link_kind == "history":
+            history.symlink_to(outside, target_is_directory=True)
+        else:
+            history.mkdir()
+            (history / "revision.md").symlink_to(secret)
+
+    if link_kind in {"directory", "file"}:
+        with pytest.raises(ValueError):
+            await storage.read_profile("user", "10001")
+        with pytest.raises(ValueError):
+            await storage.write_profile("user", "10001", "changed")
+    else:
+        with pytest.raises(ValueError):
+            await storage.read_revision("user", "10001", "revision.md")
+        with pytest.raises(ValueError):
+            await storage.restore_revision("user", "10001", "revision.md")
+        if link_kind == "history":
+            with pytest.raises(ValueError):
+                await storage.list_revisions("user", "10001")
+            with pytest.raises(ValueError):
+                await storage.write_profile("user", "10001", "changed")
+    assert secret.read_text(encoding="utf-8") == "private"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("entity_type", ["user", "group"])
+async def test_profiles_keep_valid_non_numeric_ids(
+    tmp_path: Path, entity_type: str
+) -> None:
+    storage = ProfileStorage(tmp_path)
+    await storage.write_profile(entity_type, "new-0", "v1")
+    await storage.write_profile(entity_type, "new-0", "v2")
+    revisions = await storage.list_revisions(entity_type, "new-0")
+    await storage.restore_revision(entity_type, "new-0", revisions[0])
+    assert await storage.read_profile(entity_type, "new-0") == "v1"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("entity_type", ["user", "invalid"])
+async def test_profile_query_reports_invalid_parameters_without_reading_secret(
+    tmp_path: Path, entity_type: str
+) -> None:
+    storage = ProfileStorage(tmp_path / "profiles")
+    (tmp_path / "outside.md").write_text("private", encoding="utf-8")
+    service = SimpleNamespace(enabled=True, get_profile=storage.read_profile)
+    context = RuntimeAPIContext(
+        config_getter=lambda: None,
+        onebot=None,
+        ai=None,
+        command_dispatcher=None,
+        queue_manager=None,
+        history_manager=None,
+        cognitive_service=service,
+    )
+    args: dict[str, Any] = {
+        "entity_type": entity_type,
+        "entity_id": "../../outside",
+    }
+    request = make_mocked_request("GET", "/profile", match_info=args)
+    response = await cognitive_profile_handler(context, request)
+    assert response.status == 400
+    assert "private" not in json.loads(response.text or "{}").get("error", "")
+    result = await execute(args, {"cognitive_service": service})
+    assert result.startswith("侧写查询参数无效:")
+    assert "private" not in result

From 0d72a78b9ee4344228751151f496566038f4f351 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:02:12 +0800
Subject: [PATCH 032/121] fix(knowledge): skip cancelled queued model requests

---
 docs/knowledge.md                   |  2 +
 src/Undefined/knowledge/embedder.py |  2 +
 src/Undefined/knowledge/reranker.py |  2 +
 tests/test_knowledge.py             | 65 +++++++++++++++++++++++++++++
 4 files changed, 71 insertions(+)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index b27be0fc..79a29d9d 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -194,6 +194,8 @@ chunk_size=4, chunk_overlap=1 → step=3
 
 嵌入与重排请求都通过内置队列串行发送，按各自 `queue_interval_seconds` 控制发车间隔；embedding/rerank 默认值均为 `0.0`，非正数都表示请求到达立即发车。多行文本按 `embed_batch_size` 分批，每批一次 API 调用。
 
+调用方取消仍在排队的请求时，队列会在出队时跳过该请求，不调用模型，也不消耗发车间隔；已经发给模型的请求不在这个排队取消规则内。
+
 ```
 texts → split_lines → [batch 1, batch 2, ...] → Queue → API (间隔发车)
 ```
diff --git a/src/Undefined/knowledge/embedder.py b/src/Undefined/knowledge/embedder.py
index 29988bc0..cb929759 100644
--- a/src/Undefined/knowledge/embedder.py
+++ b/src/Undefined/knowledge/embedder.py
@@ -60,6 +60,8 @@ async def _process_loop(self) -> None:
         """站台/发车：按固定间隔从队列取任务并执行。"""
         while True:
             job = await self._queue.get()
+            if job.future.cancelled():
+                continue
             try:
                 result = await self._requester.embed(self._config, job.texts)
                 if not job.future.done():
diff --git a/src/Undefined/knowledge/reranker.py b/src/Undefined/knowledge/reranker.py
index a29e63f3..06276193 100644
--- a/src/Undefined/knowledge/reranker.py
+++ b/src/Undefined/knowledge/reranker.py
@@ -56,6 +56,8 @@ async def stop(self) -> None:
     async def _process_loop(self) -> None:
         while True:
             job = await self._queue.get()
+            if job.future.cancelled():
+                continue
             try:
                 result = await self._requester.rerank(
                     model_config=self._config,
diff --git a/tests/test_knowledge.py b/tests/test_knowledge.py
index 137a6b73..e042358d 100644
--- a/tests/test_knowledge.py
+++ b/tests/test_knowledge.py
@@ -154,6 +154,71 @@ async def fake_rerank(
     assert sorted(order) == ["q1", "q2", "q3"]
 
 
+@pytest.mark.parametrize("kind", ["embedding", "rerank"])
+async def test_cancelled_queued_requests_do_not_reach_provider(kind: str) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+    calls: list[str] = []
+
+    async def record_call(value: str) -> None:
+        calls.append(value)
+        if value == "first":
+            entered.set()
+            await release.wait()
+
+    async def fake_embed(config: Any, texts: list[str]) -> list[list[float]]:
+        await record_call(texts[0])
+        return [[1.0]]
+
+    async def fake_rerank(
+        model_config: Any,
+        query: str,
+        documents: list[str],
+        top_n: int | None = None,
+    ) -> list[dict[str, Any]]:
+        await record_call(query)
+        return [{"index": 0, "relevance_score": 1.0, "document": documents[0]}]
+
+    worker: Embedder | Reranker
+    if kind == "embedding":
+        worker, requester = _make_embedder()
+        requester.embed = fake_embed
+    else:
+        worker, requester = _make_reranker()
+        requester.rerank = fake_rerank
+
+    async def submit(value: str) -> Any:
+        if isinstance(worker, Embedder):
+            return await worker.embed([value])
+        return await worker.rerank(value, [value])
+
+    worker.start()
+    tasks: list[asyncio.Task[Any]] = []
+    try:
+        first = asyncio.create_task(submit("first"))
+        tasks.append(first)
+        await asyncio.wait_for(entered.wait(), timeout=2)
+        cancelled = asyncio.create_task(submit("cancelled"))
+        tasks.append(cancelled)
+        await asyncio.sleep(0)  # 让第二个请求进入真实队列。
+        assert worker._queue.qsize() == 1
+        cancelled.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await cancelled
+        third = asyncio.create_task(submit("third"))
+        tasks.append(third)
+        release.set()
+        results = await asyncio.wait_for(asyncio.gather(first, third), timeout=2)
+        assert all(results)
+        assert calls == ["first", "third"]
+    finally:
+        release.set()
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await worker.stop()
+
+
 # ── manager ──────────────────────────────────────────────────────────────────
 
 

From fafbe82458af034d8bb5b61f10ce7451e9ac1725 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:02:57 +0800
Subject: [PATCH 033/121] fix(scripts): synchronize restored profile search
 vectors

---
 docs/cognitive-memory.md             |  13 +-
 scripts/README.md                    |  12 +-
 scripts/reembed_cognitive.py         |   1 +
 scripts/restore_profile.py           | 131 +++++++++++++--
 tests/test_restore_profile_script.py | 229 +++++++++++++++++++++++++++
 5 files changed, 367 insertions(+), 19 deletions(-)
 create mode 100644 tests/test_restore_profile_script.py

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
index d37b460e..d8d772ca 100644
--- a/docs/cognitive-memory.md
+++ b/docs/cognitive-memory.md
@@ -447,6 +447,8 @@ data/cognitive/
 
 更换嵌入模型（维度变化或模型升级）后，需要对向量库进行全量重嵌入。详见 [`scripts/reembed_cognitive.py`](../scripts/reembed_cognitive.py)。
 
+重嵌入读取 Chroma 中现有的检索正文，不从侧写 Markdown 重建内容。恢复历史侧写或补同步当前侧写时，使用下方的 `restore_profile.py restore` / `sync`。
+
 向量维度发生变化时脚本先把新向量写入临时 collection，全部完成并校验后才删除旧库并换名（ChromaDB 定维后无法原地改维，直接 upsert 异维向量会失败）。建议先 `--dry-run` 确认维度变化与记录数：预览在系统临时目录的完整副本上读取，源 Chroma 文件和 collection 不会被修改，也不会清理或换名遗留的临时 collection；仍会调用嵌入 API，并可能记录 token 用量。请预留副本所需的临时磁盘空间，并按以下步骤停止写入后运行。
 
 ```bash
@@ -482,13 +484,18 @@ uv run python scripts/restore_profile.py list --entity-type user --entity-id {us
 # 预览某个版本内容（不改动文件）
 uv run python scripts/restore_profile.py show --entity-type user --entity-id {user_id} --revision {timestamp}.md
 
-# 恢复该版本（先 dry-run 确认，再实际恢复）
+# 停止机器人及其他写入侧写/向量库的进程后，先预览，再恢复并同步检索
 uv run python scripts/restore_profile.py restore --entity-type user --entity-id {user_id} --revision {timestamp}.md --dry-run
 uv run python scripts/restore_profile.py restore --entity-type user --entity-id {user_id} --revision {timestamp}.md
+
+# 若向量同步失败，修复错误后从当前 Markdown 重试，不必再次恢复快照
+uv run python scripts/restore_profile.py sync --entity-type user --entity-id {user_id} --dry-run
+uv run python scripts/restore_profile.py sync --entity-type user --entity-id {user_id}
 ```
 
-恢复只改侧写 Markdown 与历史快照，不会更新 ChromaDB 中的侧写向量；若同一实体在
-`cognitive_profiles` 里有旧向量，请按[更换嵌入模型](#更换嵌入模型)的方式重嵌入侧写。
+`restore` 默认同时恢复 Markdown、保存当前内容的历史快照，并用当前 cognitive 嵌入模型同步 `cognitive_profiles` 中该实体的检索正文和向量，其他实体保持不变。检索正文沿用运行时格式，包含恢复版本中的名称、标签、评价、锐评与正文。模型调用失败时尚未恢复文件；若文件已恢复而向量写入失败，命令会报错，可用 `sync` 从当前文件补同步。文件和向量库之间没有跨存储事务，请保持机器人及其他写入进程停止，直到同步成功。
+
+`--dry-run` 只展示将恢复的内容、检索正文和两个目录，不写盘、不打开 Chroma、不调用模型。目录默认读取 `cognitive.profiles_path` 与 `cognitive.vector_store_path`；操作独立副本时同时指定 `--profiles-path` 和 `--db-path`。实际恢复/同步可能调用嵌入 API 并记录 token 用量；若已更换嵌入模型维度，请先按[更换嵌入模型](#更换嵌入模型)重建整个向量库，再恢复或同步单个侧写。
 
 **级别 3：完整移除**
 
diff --git a/scripts/README.md b/scripts/README.md
index 98b514e0..1fd047f6 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -65,6 +65,8 @@ python scripts/sync_config_template.py --stdout
 
 **原理**：ChromaDB 存储了完整的原文本（`documents`），脚本读取所有记录，用新模型重新计算向量后 upsert 覆写，metadata 保持不变。
 
+脚本不重新读取侧写 Markdown，也不用于历史侧写恢复。恢复版本或从当前 Markdown 更新检索正文与向量，请使用下方的 `restore_profile.py restore` / `sync`。
+
 **维度变化**：collection 在首次写入时定维，异维 upsert 会直接报 `InvalidArgumentError`。脚本把新向量写入临时 collection，全部写完并校验记录数后才删除旧库、把临时库换名为正式库。实际运行会清理未完成的临时库，或在正式库缺失时恢复临时库。
 
 `--dry-run` 先复制向量库到系统临时目录，仅在副本上打开 Chroma 客户端，源向量库的数据和文件均不修改。它不会创建缺失的 collection、删除残留临时库或把临时库换名；若只有临时库，会读取其中的记录预览恢复后的重嵌入。预览仍会调用嵌入 API 计算向量，并可能记录 token 用量；需要足够临时磁盘空间保存完整副本。运行前停止机器人及其他写入该库的进程，保证复制和正式迁移读取一致的数据。
@@ -107,14 +109,20 @@ uv run python scripts/restore_profile.py list --entity-type user --entity-id 123
 # 查看某个历史版本内容
 uv run python scripts/restore_profile.py show --entity-type user --entity-id 123456 --revision 20260101000000000000.md
 
-# 恢复某个历史版本（恢复前会把当前内容另存为新快照，可再次回退）
+# 停止机器人及其他写入进程后恢复，并同步该实体的检索正文与向量
 uv run python scripts/restore_profile.py restore --entity-type user --entity-id 123456 --revision 20260101000000000000.md
 
 # 仅预览，不写盘
 uv run python scripts/restore_profile.py restore --entity-type user --entity-id 123456 --revision 20260101000000000000.md --dry-run
+
+# 补同步当前 Markdown（例如恢复成功但向量写入失败后重试）
+uv run python scripts/restore_profile.py sync --entity-type user --entity-id 123456 --dry-run
+uv run python scripts/restore_profile.py sync --entity-type user --entity-id 123456
 ```
 
-**注意**：恢复只改侧写 Markdown 与历史快照，不会更新 ChromaDB 中的侧写向量；需要同步检索结果时按 `docs/cognitive-memory.md` 的说明重嵌入。
+`restore` 默认恢复 Markdown、把当前内容另存为历史快照，并使用当前 cognitive 嵌入配置更新 `cognitive_profiles` 中该实体的检索正文与向量。`sync` 只从当前 Markdown 补同步检索，不创建快照。模型请求失败时文件保持原状；向量写入失败时命令报错，已恢复文件保留，可修复错误后重跑 `sync`，无需依赖可能已被清理的旧快照。文件与向量库没有跨存储事务，实际恢复/同步前需停止机器人和其他写入进程，成功后再启动。
+
+`--dry-run` 展示文件内容、检索正文与路径，不打开 Chroma、不调用模型、不写盘。目录默认来自 `cognitive.profiles_path` 与 `cognitive.vector_store_path`；操作独立副本时同时传入 `--profiles-path` 和 `--db-path`。实际恢复/同步会调用嵌入 API，可能记录 token 用量。若新模型维度不同于现有库，先完成全库重嵌入再恢复/同步单个侧写。
 
 ### release_notes.py — 发布版本校验与 Release notes 生成
 
diff --git a/scripts/reembed_cognitive.py b/scripts/reembed_cognitive.py
index da368b88..48ea62f9 100755
--- a/scripts/reembed_cognitive.py
+++ b/scripts/reembed_cognitive.py
@@ -6,6 +6,7 @@
 
 原理：ChromaDB 存储了完整的原文本（documents），本脚本读取所有记录，
 用新模型重新计算向量，然后通过 upsert 覆写回去。metadata 保持不变。
+它不会重新读取侧写 Markdown；历史恢复与当前文件同步使用 restore_profile.py。
 
 维度变化：ChromaDB 的 collection 在首次写入时定维，异维向量 upsert 会直接失败
 （InvalidArgumentError）。脚本会先比较新旧向量维度，检测到变化时把新向量全部
diff --git a/scripts/restore_profile.py b/scripts/restore_profile.py
index c18993d4..b577b1c7 100644
--- a/scripts/restore_profile.py
+++ b/scripts/restore_profile.py
@@ -16,8 +16,9 @@
     # 仅预览将要恢复的内容（不写盘）
     uv run python scripts/restore_profile.py restore --entity-type user --entity-id 123456 --revision 20260101000000000000.md --dry-run
 
-恢复只改侧写 Markdown 文件与历史快照，不会重建 ChromaDB 中的侧写向量；如需同时刷新
-检索向量，请按 docs/cognitive-memory.md 的说明重嵌入。
+恢复同时更新侧写 Markdown、历史快照和该实体的 ChromaDB 检索正文与向量。
+若向量写入失败，可用 sync 动作从当前 Markdown 重试，不必再次恢复历史版本。
+实际恢复或同步前，应停止机器人及其他写入侧写/向量库的进程。
 """
 
 from __future__ import annotations
@@ -27,15 +28,26 @@
 import logging
 import sys
 from pathlib import Path
+from typing import Any
 
 # 将项目 src 加入 sys.path，使脚本可以直接 uv run 执行
 _PROJECT_ROOT = Path(__file__).resolve().parent.parent
+_SCRIPTS_DIR = _PROJECT_ROOT / "scripts"
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
 _SRC_DIR = _PROJECT_ROOT / "src"
 if str(_SRC_DIR) not in sys.path:
     sys.path.insert(0, str(_SRC_DIR))
 
 from Undefined.cognitive.profile_storage import ProfileStorage  # noqa: E402
+from Undefined.cognitive.service.helpers import (  # noqa: E402
+    _build_profile_vector_payload,
+    _current_profile_name,
+    _normalize_profile_tags,
+    _parse_profile_markdown,
+)
 from Undefined.config.loader import Config  # noqa: E402
+from reembed_cognitive import _build_embedder, _open_chroma  # noqa: E402
 
 logger = logging.getLogger("restore_profile")
 
@@ -46,8 +58,13 @@ def _parse_args() -> argparse.Namespace:
     )
     parser.add_argument(
         "action",
-        choices=("list", "show", "restore"),
-        help="list=列出历史版本；show=查看版本内容；restore=恢复版本",
+        choices=("list", "show", "restore", "sync"),
+        help="list=列出历史版本；show=查看版本；restore=恢复并同步检索；sync=同步当前侧写检索",
+    )
+    parser.add_argument(
+        "--db-path",
+        default="",
+        help="ChromaDB 目录（默认读取 config.toml 中的 cognitive.vector_store_path）",
     )
     parser.add_argument(
         "--entity-type",
@@ -86,6 +103,67 @@ def _print_revisions(revisions: list[str]) -> None:
         print(f"{index:>3}. {name}")
 
 
+def _vector_payload(
+    content: str, entity_type: str, entity_id: str
+) -> tuple[str, dict[str, Any]]:
+    """沿用运行时侧写格式；无 frontmatter 的旧文件仍可同步正文。"""
+    parsed = _parse_profile_markdown(content)
+    if parsed is None:
+        frontmatter: dict[str, Any] = {}
+        evaluation, summary, roast = "", content, ""
+    else:
+        frontmatter, evaluation, summary, roast = parsed
+    return _build_profile_vector_payload(
+        entity_type=entity_type,
+        entity_id=entity_id,
+        effective_name=_current_profile_name(entity_type, frontmatter),
+        tags=_normalize_profile_tags(frontmatter.get("tags")),
+        summary=summary,
+        evaluation=evaluation,
+        roast=roast,
+    )
+
+
+async def _restore_and_sync(
+    config: Config,
+    storage: ProfileStorage,
+    *,
+    entity_type: str,
+    entity_id: str,
+    revision: str | None,
+    document: str,
+    metadata: dict[str, Any],
+    db_path: Path,
+) -> None:
+    embedder = _build_embedder(config)
+    try:
+        # 模型请求失败时，尚未改动侧写文件和向量库。
+        embeddings = await embedder.embed([document])
+        if len(embeddings) != 1 or not embeddings[0]:
+            raise RuntimeError("嵌入模型没有返回该侧写的有效向量，未恢复侧写")
+        async with _open_chroma(db_path, dry_run=False) as client:
+            collection = client.get_or_create_collection(
+                "cognitive_profiles", metadata={"hnsw:space": "cosine"}
+            )
+            if revision is not None:
+                await storage.restore_revision(entity_type, entity_id, revision)
+            try:
+                await asyncio.to_thread(
+                    collection.upsert,
+                    ids=[f"{entity_type}:{entity_id}"],
+                    documents=[document],
+                    embeddings=embeddings,
+                    metadatas=[metadata],
+                )
+            except Exception as exc:
+                raise RuntimeError(
+                    "侧写检索同步失败；当前 Markdown 已保留。修复向量库/模型配置后，"
+                    "使用 sync 动作重试当前侧写，无需再次恢复历史版本。"
+                ) from exc
+    finally:
+        await embedder.stop()
+
+
 async def _main(args: argparse.Namespace) -> None:
     config = Config.load(strict=False)
     base_path = args.profiles_path or config.cognitive.profiles_path
@@ -113,22 +191,47 @@ async def _main(args: argparse.Namespace) -> None:
         print(content)
         return
 
-    # restore
-    content = await storage.read_revision(entity_type, entity_id, args.revision)
+    revision = args.revision if args.action == "restore" else None
+    content = (
+        await storage.read_revision(entity_type, entity_id, revision)
+        if revision is not None
+        else await storage.read_profile(entity_type, entity_id)
+    )
     if content is None:
-        logger.error("历史版本不存在: %s:%s/%s", entity_type, entity_id, args.revision)
+        logger.error(
+            "侧写或历史版本不存在: %s:%s/%s", entity_type, entity_id, revision or "当前"
+        )
         sys.exit(1)
+    document, metadata = _vector_payload(content, entity_type, entity_id)
+    db_path = Path(args.db_path or config.cognitive.vector_store_path)
+    print(f"侧写目录: {base_path}")
+    print(f"ChromaDB 目录: {db_path}")
     if args.dry_run:
-        print(
-            f"[dry-run] 将把 {entity_type}:{entity_id} 恢复为 {args.revision}，"
-            f"当前内容会先存为新快照。"
-        )
+        if revision is not None:
+            print(
+                f"[dry-run] 将把 {entity_type}:{entity_id} 恢复为 {revision}，"
+                "当前内容会先存为新快照。"
+            )
+        print(f"[dry-run] 将同步 cognitive_profiles 中的 {entity_type}:{entity_id}")
         print("---- 恢复后的内容 ----")
         print(content)
+        print("---- 检索正文 ----")
+        print(document)
         return
-    restored = await storage.restore_revision(entity_type, entity_id, args.revision)
-    print(f"已恢复 {entity_type}:{entity_id} 到历史版本 {restored}")
-    print("当前内容已另存为新快照，可再次用 list / restore 回退。")
+    await _restore_and_sync(
+        config,
+        storage,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        revision=revision,
+        document=document,
+        metadata=metadata,
+        db_path=db_path,
+    )
+    if revision is not None:
+        print(f"已恢复 {entity_type}:{entity_id} 到历史版本 {revision}")
+        print("当前内容已另存为新快照，可再次用 list / restore 回退。")
+    print(f"已同步 {entity_type}:{entity_id} 的检索正文与向量。")
 
 
 def main() -> None:
diff --git a/tests/test_restore_profile_script.py b/tests/test_restore_profile_script.py
new file mode 100644
index 00000000..72eca75d
--- /dev/null
+++ b/tests/test_restore_profile_script.py
@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+import chromadb
+import pytest
+
+from Undefined.cognitive.profile_storage import ProfileStorage
+from Undefined.cognitive.service.helpers import _serialize_profile_markdown
+from Undefined.config.loader import Config
+
+
+def _load_script() -> ModuleType:
+    path = Path(__file__).resolve().parent.parent / "scripts" / "restore_profile.py"
+    spec = importlib.util.spec_from_file_location("restore_profile_script", path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class _Embedder:
+    def __init__(self, *, fail: bool = False) -> None:
+        self.fail = fail
+        self.calls: list[list[str]] = []
+        self.stopped = False
+
+    async def embed(self, documents: list[str]) -> list[list[float]]:
+        self.calls.append(documents)
+        if self.fail:
+            raise RuntimeError("embedding unavailable")
+        return [[1.0, 0.0, 0.0] for _ in documents]
+
+    async def stop(self) -> None:
+        self.stopped = True
+
+
+def _args(
+    revision: str, *, action: str = "restore", dry_run: bool = False
+) -> argparse.Namespace:
+    return argparse.Namespace(
+        action=action,
+        entity_type="user",
+        entity_id="123",
+        revision=revision,
+        profiles_path="",
+        db_path="",
+        dry_run=dry_run,
+    )
+
+
+async def _seed_profiles(tmp_path: Path) -> tuple[Config, ProfileStorage, str, str]:
+    config = Config.from_mapping(
+        {
+            "cognitive": {
+                "vector_store": {"path": str(tmp_path / "chroma")},
+                "profile": {"path": str(tmp_path / "profiles"), "revision_keep": 1},
+            }
+        },
+        strict=False,
+    )
+    assert Path(config.cognitive.profiles_path).resolve().is_relative_to(tmp_path)
+    assert Path(config.cognitive.vector_store_path).resolve().is_relative_to(tmp_path)
+    assert (
+        (Path(config.cognitive.profiles_path) / "history")
+        .resolve()
+        .is_relative_to(tmp_path)
+    )
+    storage = ProfileStorage(config.cognitive.profiles_path, revision_keep=1)
+    recovered = _serialize_profile_markdown(
+        {
+            "entity_type": "user",
+            "entity_id": "123",
+            "nickname": "恢复的名称",
+            "tags": ["原标签"],
+        },
+        "GOOD recovered profile",
+        evaluation="恢复的评价",
+        roast="恢复的锐评",
+    )
+    await storage.write_profile("user", "123", recovered)
+    await storage.write_profile("user", "123", "BAD mistaken profile")
+    revision = (await storage.list_revisions("user", "123"))[0]
+    return config, storage, revision, recovered
+
+
+def _seed_vectors(config: Config, tmp_path: Path) -> Any:
+    assert Path(config.cognitive.vector_store_path).resolve().is_relative_to(tmp_path)
+    client: Any = chromadb.PersistentClient(path=config.cognitive.vector_store_path)
+    collection = client.get_or_create_collection(
+        "cognitive_profiles", metadata={"hnsw:space": "cosine"}
+    )
+    collection.upsert(
+        ids=["user:123", "group:999"],
+        documents=["BAD mistaken profile", "unrelated profile"],
+        embeddings=[[0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
+        metadatas=[
+            {"entity_type": "user", "entity_id": "123", "nickname": "错误名称"},
+            {"entity_type": "group", "entity_id": "999"},
+        ],
+    )
+    return collection
+
+
+def _files(path: Path) -> dict[Path, bytes]:
+    return {
+        file.relative_to(path): file.read_bytes()
+        for file in path.rglob("*")
+        if file.is_file()
+    }
+
+
+@pytest.fixture(autouse=True)
+def _isolate_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+
+
+@pytest.mark.asyncio
+async def test_restore_syncs_actual_markdown_and_vectors_without_touching_other_entities(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    module = _load_script()
+    config, storage, revision, recovered = await _seed_profiles(tmp_path)
+    collection = _seed_vectors(config, tmp_path)
+    embedder = _Embedder()
+    monkeypatch.setattr(module.Config, "load", lambda **kwargs: config)
+    monkeypatch.setattr(module, "_build_embedder", lambda cfg: embedder)
+
+    await module._main(_args(revision))
+
+    assert await storage.read_profile("user", "123") == recovered
+    result = collection.get(
+        ids=["user:123"], include=["documents", "embeddings", "metadatas"]
+    )
+    document = result["documents"][0]
+    assert "GOOD recovered profile" in document
+    assert "BAD mistaken profile" not in document
+    assert "恢复的评价" in document and "恢复的锐评" in document
+    assert "原标签" in document
+    assert embedder.calls == [[document]]
+    assert list(result["embeddings"][0]) == [1.0, 0.0, 0.0]
+    assert result["metadatas"][0]["nickname"] == "恢复的名称"
+    other = collection.get(ids=["group:999"], include=["documents", "embeddings"])
+    assert other["documents"] == ["unrelated profile"]
+    assert list(other["embeddings"][0]) == [0.0, 0.0, 1.0]
+    assert embedder.stopped
+
+
+@pytest.mark.asyncio
+async def test_restore_dry_run_does_not_open_chroma_or_call_model(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    module = _load_script()
+    config, storage, revision, recovered = await _seed_profiles(tmp_path)
+    before = _files(tmp_path)
+    monkeypatch.setattr(module.Config, "load", lambda **kwargs: config)
+
+    def forbidden(*args: Any, **kwargs: Any) -> Any:
+        raise AssertionError("dry-run must not construct a client or model")
+
+    monkeypatch.setattr(module, "_open_chroma", forbidden)
+    monkeypatch.setattr(module, "_build_embedder", forbidden)
+    await module._main(_args(revision, dry_run=True))
+
+    assert _files(tmp_path) == before
+    assert await storage.read_profile("user", "123") == "BAD mistaken profile"
+    assert recovered in capsys.readouterr().out
+    assert not Path(config.cognitive.vector_store_path).exists()
+
+
+@pytest.mark.asyncio
+async def test_embedding_failure_leaves_files_and_vectors_unchanged(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    module = _load_script()
+    config, _, revision, _ = await _seed_profiles(tmp_path)
+    _seed_vectors(config, tmp_path)
+    before = _files(tmp_path)
+    embedder = _Embedder(fail=True)
+    monkeypatch.setattr(module.Config, "load", lambda **kwargs: config)
+    monkeypatch.setattr(module, "_build_embedder", lambda cfg: embedder)
+
+    with pytest.raises(RuntimeError, match="embedding unavailable"):
+        await module._main(_args(revision))
+
+    assert _files(tmp_path) == before
+    assert embedder.stopped
+
+
+@pytest.mark.asyncio
+async def test_sync_retries_vector_failure_after_revision_was_pruned(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    module = _load_script()
+    config, storage, revision, recovered = await _seed_profiles(tmp_path)
+    collection = _seed_vectors(config, tmp_path)
+    embedder = _Embedder()
+    monkeypatch.setattr(module.Config, "load", lambda **kwargs: config)
+    monkeypatch.setattr(module, "_build_embedder", lambda cfg: embedder)
+    original_upsert = type(collection).upsert
+    fail_next = True
+
+    def upsert_once(self: Any, *args: Any, **kwargs: Any) -> None:
+        nonlocal fail_next
+        if fail_next:
+            fail_next = False
+            raise RuntimeError("Chroma temporarily unavailable")
+        original_upsert(self, *args, **kwargs)
+
+    monkeypatch.setattr(type(collection), "upsert", upsert_once)
+    with pytest.raises(RuntimeError, match="使用 sync 动作重试"):
+        await module._main(_args(revision))
+
+    assert "已同步" not in capsys.readouterr().out
+    assert await storage.read_profile("user", "123") == recovered
+    assert revision not in await storage.list_revisions("user", "123")
+    assert collection.get(ids=["user:123"])["documents"] == ["BAD mistaken profile"]
+    history_before = _files(tmp_path / "profiles" / "history")
+
+    await module._main(_args("", action="sync"))
+
+    result = collection.get(ids=["user:123"], include=["documents", "embeddings"])
+    assert "GOOD recovered profile" in result["documents"][0]
+    assert list(result["embeddings"][0]) == [1.0, 0.0, 0.0]
+    assert _files(tmp_path / "profiles" / "history") == history_before

From 7e4f80803137fff81b987d9e6d8ab49d47c6ada9 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:04:12 +0800
Subject: [PATCH 034/121] fix(bilibili): settle download threads before
 cancelled cleanup

---
 src/Undefined/bilibili/downloader.py          |  22 ++--
 .../skills/tools/bilibili_video/README.md     |   2 +
 tests/test_bilibili_downloader_adapter.py     | 103 ++++++++++++++++++
 3 files changed, 118 insertions(+), 9 deletions(-)

diff --git a/src/Undefined/bilibili/downloader.py b/src/Undefined/bilibili/downloader.py
index ffacff78..b2faa80a 100644
--- a/src/Undefined/bilibili/downloader.py
+++ b/src/Undefined/bilibili/downloader.py
@@ -13,6 +13,7 @@
 from Undefined.bilibili.download_core import QUALITY_MAP as QUALITY_MAP
 from Undefined.bilibili.download_core import download_video as download_video_core
 from Undefined.bilibili.models import VideoInfo as VideoInfo
+from Undefined.utils import io
 from Undefined.utils.paths import DOWNLOAD_CACHE_DIR, ensure_dir
 
 logger = logging.getLogger(__name__)
@@ -114,13 +115,15 @@ async def download_video(
     work_dir = ensure_dir(output_dir / uuid.uuid4().hex)
 
     try:
-        downloaded_path, video_info, actual_qn = await asyncio.to_thread(
-            partial(
-                _download_video_sync,
-                bvid,
-                work_dir=work_dir,
-                cookie=cookie,
-                prefer_quality=prefer_quality,
+        downloaded_path, video_info, actual_qn = await io.run_cancellation_safe(
+            asyncio.to_thread(
+                partial(
+                    _download_video_sync,
+                    bvid,
+                    work_dir=work_dir,
+                    cookie=cookie,
+                    prefer_quality=prefer_quality,
+                )
             )
         )
 
@@ -131,8 +134,9 @@ async def download_video(
             actual_qn,
         )
         return downloaded_path, video_info, actual_qn
-    except Exception:
-        _cleanup_dir(work_dir)
+    except BaseException:
+        # 下载线程已收敛，取消/失败时在释放所有权前清理，避免线程稍后重建产物。
+        await io.run_cancellation_safe(asyncio.to_thread(_cleanup_dir, work_dir))
         raise
 
 
diff --git a/src/Undefined/skills/tools/bilibili_video/README.md b/src/Undefined/skills/tools/bilibili_video/README.md
index d89aa7f1..bdb0df5e 100644
--- a/src/Undefined/skills/tools/bilibili_video/README.md
+++ b/src/Undefined/skills/tools/bilibili_video/README.md
@@ -33,6 +33,8 @@
 配置依赖：
 - `config.toml` 中的 `[bilibili]` 段控制清晰度、时长限制、文件大小限制等
 
+下载超时或取消时，会等待正在运行的下载/合并线程完成，再清理整个工作目录并传播取消；等待期间不会发送下载结果。工具超时或停机收尾因此可能超过触发取消的时间点。正常下载完成后，产物由发送或附件注册流程接管并清理；自动提取和图文嵌套视频共用这一下载路径。
+
 自动提取行为：
 - 自动处理管线命中 B 站链接、BV 号或 AV 号后，会发送一次外层合并转发，包含视频信息、视频文件或视频状态、弹幕列表三个节点。
 - 弹幕通过 Bilibili protobuf 接口分段拉取；弹幕列表会按每 100 条弹幕拆成一个内层合并转发。
diff --git a/tests/test_bilibili_downloader_adapter.py b/tests/test_bilibili_downloader_adapter.py
index fdc7a401..eba083c1 100644
--- a/tests/test_bilibili_downloader_adapter.py
+++ b/tests/test_bilibili_downloader_adapter.py
@@ -1,12 +1,18 @@
 from __future__ import annotations
 
+import asyncio
 from pathlib import Path
+import threading
 from types import TracebackType
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock
 
 import pytest
 
 from Undefined.bilibili import downloader
 from Undefined.bilibili.models import DownloadResult, VideoInfo, VideoStats
+from Undefined.bilibili.sender import send_bilibili_video
 
 
 @pytest.mark.asyncio
@@ -181,3 +187,100 @@ def _fake_download_core(
     assert called["bvid"] == "BV1xx411c7mD"
     assert called["prefer_quality"] == 64
     assert called["overwrite"] is True
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("via_sender", [False, True])
+async def test_cancelled_download_waits_for_thread_then_cleans_artifacts(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, via_sender: bool
+) -> None:
+    started = threading.Event()
+    release = threading.Event()
+    finished = threading.Event()
+    sender = SimpleNamespace(send_group_forward_message=AsyncMock())
+
+    def download_sync(
+        bvid: str, *, work_dir: Path, cookie: str, prefer_quality: int
+    ) -> tuple[Path, VideoInfo, int]:
+        (work_dir / "stream.part").write_bytes(b"partial")
+        started.set()
+        try:
+            if not release.wait(timeout=5.0):
+                raise TimeoutError("test download was not released")
+            output = work_dir / "video.mp4"
+            output.write_bytes(b"finished after caller cancellation")
+            info = VideoInfo(
+                bvid=bvid,
+                aid=1,
+                title="test",
+                duration=1,
+                cover_url="",
+                up_name="test",
+                desc="",
+                cid=1,
+                page_duration=1,
+                stats=VideoStats(),
+            )
+            return output, info, prefer_quality
+        finally:
+            finished.set()
+
+    monkeypatch.setattr(downloader, "_download_video_sync", download_sync)
+    monkeypatch.setattr(downloader, "DOWNLOAD_CACHE_DIR", tmp_path)
+    if via_sender:
+        monkeypatch.setattr(
+            "Undefined.bilibili.sender.normalize_to_bvid",
+            AsyncMock(return_value="BV1xx411c7mD"),
+        )
+        task: asyncio.Task[Any] = asyncio.create_task(
+            send_bilibili_video(
+                "BV1xx411c7mD",
+                cast(Any, sender),
+                cast(Any, SimpleNamespace()),
+                "group",
+                1,
+                max_duration=0,
+                danmaku_enabled=False,
+            )
+        )
+    else:
+        task = asyncio.create_task(
+            downloader.download_video("BV1xx411c7mD", output_dir=tmp_path)
+        )
+    try:
+        assert await asyncio.to_thread(started.wait, 2.0)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done()
+        assert not finished.is_set()
+        assert list(tmp_path.rglob("stream.part"))
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=2.0)
+        assert finished.is_set()
+        assert list(tmp_path.iterdir()) == []
+        sender.send_group_forward_message.assert_not_awaited()
+    finally:
+        release.set()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_failed_download_cleans_partial_artifacts_and_preserves_error(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    error = RuntimeError("download failed")
+
+    def download_sync(
+        bvid: str, *, work_dir: Path, cookie: str, prefer_quality: int
+    ) -> tuple[Path, VideoInfo, int]:
+        (work_dir / "stream.part").write_bytes(b"partial")
+        raise error
+
+    monkeypatch.setattr(downloader, "_download_video_sync", download_sync)
+    with pytest.raises(RuntimeError) as exc_info:
+        await downloader.download_video("BV1xx411c7mD", output_dir=tmp_path)
+    assert exc_info.value is error
+    assert list(tmp_path.iterdir()) == []

From 55a8c963cb4eed38e5a979c1660587ddde4f7d6e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:04:41 +0800
Subject: [PATCH 035/121] fix(runtime): drain background workers before closing
 model queues

---
 docs/deployment.md          |  2 +-
 src/Undefined/main.py       | 40 ++++++++++++----
 tests/test_main_shutdown.py | 96 ++++++++++++++++++++++++++++++++++++-
 3 files changed, 127 insertions(+), 11 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 6b5d47c7..ead48817 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -156,7 +156,7 @@ uv run Undefined-webui
 
 #### 优雅停机
 
-`SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：停止 OneBot 连接、关闭 Runtime API 与微信服务、停止史官 / memes worker、断开连接、关闭 AI 客户端与检索运行时、停止配置热重载并释放渲染资源。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程，无需额外配置；请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
+`SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：停止 OneBot 连接、关闭 Runtime API 与微信服务、停止史官 / memes worker，再由消息处理器排空并关闭 AI 队列、落盘历史，最后断开连接、关闭 AI 客户端与检索运行时、停止配置热重载并释放渲染资源。等待 worker 收尾期间模型队列保持可用，史官在向量写入后继续提交侧写模型请求也能完成；消息处理器收尾时新落盘的认知任务留待下次启动处理。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程，无需额外配置；请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
 
 #### 自动启动选项
 
diff --git a/src/Undefined/main.py b/src/Undefined/main.py
index 4535e56f..ec269b34 100644
--- a/src/Undefined/main.py
+++ b/src/Undefined/main.py
@@ -1,11 +1,13 @@
 """程序入口"""
 
+from __future__ import annotations
+
 import asyncio
 import logging
 import signal
 import time
 import sys
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from logging.handlers import RotatingFileHandler
 from pathlib import Path
 
@@ -40,6 +42,10 @@
 from Undefined.render import close_browser as close_render_browser
 from Undefined.utils.render_cache import close_render_cache
 
+if TYPE_CHECKING:
+    from Undefined.cognitive import HistorianWorker
+    from Undefined.memes import MemeWorker
+
 
 def ensure_runtime_dirs() -> None:
     """确保运行时目录存在"""
@@ -528,14 +534,12 @@ def _apply_config_updates(
                 await weixin_service.stop()
             except Exception:
                 logger.exception("[清理] WeixinService stop 失败")
-        try:
-            await handler.close()
-        except Exception:
-            logger.exception("[清理] MessageHandler close 失败")
-        if meme_worker is not None:
-            await meme_worker.stop()
-        if historian_worker:
-            await historian_worker.stop()
+        await _close_message_workers(
+            handler,
+            meme_worker=meme_worker,
+            historian_worker=historian_worker,
+            logger=logger,
+        )
         await onebot.disconnect()
         await ai.close()
         if retrieval_registry is not None:
@@ -547,6 +551,24 @@ def _apply_config_updates(
         logger.info("[退出] 机器人已停止运行")
 
 
+async def _close_message_workers(
+    handler: MessageHandler,
+    *,
+    meme_worker: MemeWorker | None,
+    historian_worker: HistorianWorker | None,
+    logger: logging.Logger,
+) -> None:
+    """先收敛仍会提交模型调用的 worker，再由 handler 排空并关闭队列。"""
+    if meme_worker is not None:
+        await meme_worker.stop()
+    if historian_worker is not None:
+        await historian_worker.stop()
+    try:
+        await handler.close()
+    except Exception:
+        logger.exception("[清理] MessageHandler close 失败")
+
+
 class ShutdownSignalGuard:
     """优雅停机信号注册的句柄：携带停机事件并支持恢复安装前的信号状态。"""
 
diff --git a/tests/test_main_shutdown.py b/tests/test_main_shutdown.py
index ff2fdb07..e1015c0e 100644
--- a/tests/test_main_shutdown.py
+++ b/tests/test_main_shutdown.py
@@ -4,13 +4,107 @@
 import logging
 import os
 import signal
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock
 import pytest
 
-from Undefined.main import _run_until_shutdown, install_shutdown_signal_handlers
+from Undefined.ai import AIClient
+from Undefined.cognitive import HistorianWorker
+from Undefined.handlers import MessageHandler
+from Undefined.main import (
+    _close_message_workers,
+    _run_until_shutdown,
+    install_shutdown_signal_handlers,
+)
+from Undefined.services.queue_manager import QueueManager
 
 logger = logging.getLogger("test-main-shutdown")
 
 
+@pytest.mark.asyncio
+async def test_shutdown_keeps_model_queue_alive_between_historian_phases() -> None:
+    queue = QueueManager(ai_request_interval=0, max_retries=0)
+    ai = AIClient.__new__(AIClient)
+    ai._queue_manager = queue
+    ai._pending_llm_calls = {}
+    ai.runtime_config = cast(Any, SimpleNamespace(ai_request_max_retries=0))
+    model = SimpleNamespace(model_name="historian", max_tokens=100)
+    calls: list[str] = []
+
+    async def execute_model(request: dict[str, Any]) -> None:
+        calls.append(request["call_type"])
+        ai.set_llm_call_result(request["request_id"], {"ok": True})
+
+    queue.start(execute_model)
+    between_phases = asyncio.Event()
+    release_io = asyncio.Event()
+
+    async def phase() -> None:
+        await ai.submit_background_llm_call(model, [], call_type="rewrite")
+        between_phases.set()
+        await release_io.wait()  # 向量/磁盘阶段完成后还需要一次模型调用。
+        await ai.submit_background_llm_call(model, [], call_type="merge")
+
+    worker = HistorianWorker(
+        job_queue=SimpleNamespace(
+            recover_stale=AsyncMock(), list_jobs=AsyncMock(return_value=[])
+        ),
+        vector_store=None,
+        profile_storage=None,
+        ai_client=ai,
+        config_getter=lambda: SimpleNamespace(
+            poll_interval_seconds=1, stale_job_timeout_seconds=60
+        ),
+    )
+    await worker.start()
+    phase_task = asyncio.create_task(phase())
+    worker._inflight_tasks.add(phase_task)
+    handler = MessageHandler.__new__(MessageHandler)
+    handler._background_tasks = set()
+    cast(Any, handler).pipeline_registry = SimpleNamespace(stop_hot_reload=AsyncMock())
+    cast(Any, handler).ai_coordinator = SimpleNamespace(queue_manager=queue)
+    flush_batches = AsyncMock()
+    flush_history = AsyncMock()
+    cast(Any, handler).message_batcher = SimpleNamespace(flush_all=flush_batches)
+    cast(Any, handler).history_manager = SimpleNamespace(
+        flush_pending_saves=flush_history
+    )
+    meme = SimpleNamespace(stop=AsyncMock())
+    close_task: asyncio.Task[None] | None = None
+    try:
+        await asyncio.wait_for(between_phases.wait(), timeout=2)
+        close_task = asyncio.create_task(
+            _close_message_workers(
+                handler,
+                meme_worker=cast(Any, meme),
+                historian_worker=worker,
+                logger=logger,
+            )
+        )
+        await asyncio.sleep(0)
+        assert not close_task.done()
+        assert queue._processor_tasks
+        assert calls == ["rewrite"]
+        flush_batches.assert_not_awaited()
+        release_io.set()
+        await asyncio.wait_for(close_task, timeout=2)
+        assert calls == ["rewrite", "merge"]
+        assert not ai._pending_llm_calls
+        assert not queue._processor_tasks
+        meme.stop.assert_awaited_once()
+        flush_history.assert_awaited_once()
+    finally:
+        release_io.set()
+        phase_task.cancel()
+        if close_task is not None:
+            close_task.cancel()
+            await asyncio.gather(close_task, return_exceptions=True)
+        await asyncio.gather(phase_task, return_exceptions=True)
+        await worker.stop()
+        await queue.stop()
+
+
 class _SlowOneBot:
     def __init__(self) -> None:
         self.cancelled = False

From f7b07893be045755d456aa27c573535f3f23bde0 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:05:42 +0800
Subject: [PATCH 036/121] fix(deploy): preserve distinct configuration backups

---
 docs/docker-deploy.md                |  2 +
 src/Undefined/deploy/config_patch.py | 18 ++++++-
 tests/test_deploy_config_patch.py    | 77 ++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 2 deletions(-)

diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md
index c7498c20..ff1b38c4 100644
--- a/docs/docker-deploy.md
+++ b/docs/docker-deploy.md
@@ -251,6 +251,8 @@ uv run deploy up --pull always
 | `deploy/backup/` | 部署工具修改 `config.toml` 前的备份 |
 | `deploy/searxng/`、`deploy/firecrawl/`、`deploy/lxmusic2api/` | 已选服务的配置，以及音乐服务的音源、数据和下载文件 |
 
+每次实际修改已有 `config.toml` 前，部署工具会保存独立备份，文件名为 `config_<UTC时间戳>_<唯一后缀>.toml`。同一秒内的多次更新也会保留各次修改前的内容；命令输出会显示本次备份的完整路径。配置无变更或 `--dry-run` 时不创建备份。
+
 备份时保存 `config.toml`、`deploy/` 和你使用的自定义目录。Firecrawl 等服务还使用 Docker 命名卷，备份这些服务时需另行备份对应卷；仅复制 `deploy/` 不能保存全部数据库数据。
 
 普通停止使用 `uv run deploy down` 即可。**`down --volumes` 会删除 Compose 管理的数据卷；`down --purge` 还会删除整个 `deploy/`，包括登录态、凭据、配置备份和容器模式下的 Bot 数据，不可恢复。**
diff --git a/src/Undefined/deploy/config_patch.py b/src/Undefined/deploy/config_patch.py
index 2bec12cf..295c66c2 100644
--- a/src/Undefined/deploy/config_patch.py
+++ b/src/Undefined/deploy/config_patch.py
@@ -16,6 +16,8 @@
 from __future__ import annotations
 
 import tomllib
+import os
+import tempfile
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -207,9 +209,21 @@ def apply_plan(
 
     backup_path: Path | None = None
     if plan.config_path.is_file():
+        original = plan.config_path.read_text(encoding="utf-8")
         backup_dir.mkdir(parents=True, exist_ok=True)
-        backup_path = backup_dir / f"{BACKUP_FILE_PREFIX}{utc_stamp_compact()}.toml"
-        write_text(backup_path, plan.config_path.read_text(encoding="utf-8"))
+        # 独占创建预留名称；秒级时间戳相同或并发备份也不会覆盖旧文件。
+        descriptor, name = tempfile.mkstemp(
+            prefix=f"{BACKUP_FILE_PREFIX}{utc_stamp_compact()}_",
+            suffix=".toml",
+            dir=backup_dir,
+        )
+        os.close(descriptor)
+        backup_path = Path(name)
+        try:
+            write_text(backup_path, original)
+        except BaseException:
+            backup_path.unlink(missing_ok=True)
+            raise
 
     write_text(plan.config_path, rendered)
     return PatchOutcome(
diff --git a/tests/test_deploy_config_patch.py b/tests/test_deploy_config_patch.py
index e10362c5..bc763576 100644
--- a/tests/test_deploy_config_patch.py
+++ b/tests/test_deploy_config_patch.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import tomllib
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 import pytest
@@ -233,6 +234,82 @@ def test_apply_is_noop_when_nothing_changes(
     assert not backup_dir.exists()
 
 
+def test_same_second_updates_keep_each_previous_config(
+    config_dir: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config, example, backup_dir = config_dir
+    monkeypatch.chdir(config.parent)
+    assert backup_dir.resolve().is_relative_to(config.parent)
+    monkeypatch.setattr(config_patch, "utc_stamp_compact", lambda: "20261006T123456Z")
+    original = config.read_text(encoding="utf-8")
+    first = config_patch.apply_plan(
+        _plan(config, {"webui.port": 8788}), example_path=example, backup_dir=backup_dir
+    )
+    intermediate = config.read_text(encoding="utf-8")
+    second = config_patch.apply_plan(
+        _plan(config, {"webui.port": 8789}), example_path=example, backup_dir=backup_dir
+    )
+
+    assert first.backup_path is not None and second.backup_path is not None
+    assert first.backup_path != second.backup_path
+    assert first.backup_path.read_text(encoding="utf-8") == original
+    assert second.backup_path.read_text(encoding="utf-8") == intermediate
+    assert len(list(backup_dir.glob("config_*.toml"))) == 2
+    assert config_patch.load_toml(config)["webui"]["port"] == 8789
+
+
+def test_concurrent_backups_reserve_distinct_names(
+    config_dir: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config, example, backup_dir = config_dir
+    monkeypatch.chdir(config.parent)
+    assert backup_dir.resolve().is_relative_to(config.parent)
+    other = config.with_name("other.toml")
+    other.write_text(EXAMPLE.replace("8787", "8790"), encoding="utf-8")
+    originals = {path.read_text(encoding="utf-8") for path in (config, other)}
+    monkeypatch.setattr(config_patch, "utc_stamp_compact", lambda: "20261006T123456Z")
+
+    def apply(path: Path) -> config_patch.PatchOutcome:
+        return config_patch.apply_plan(
+            _plan(path, {"webui.port": 8788}),
+            example_path=example,
+            backup_dir=backup_dir,
+        )
+
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        futures = [executor.submit(apply, path) for path in (config, other)]
+        outcomes = [future.result() for future in futures]
+
+    paths = {outcome.backup_path for outcome in outcomes}
+    assert None not in paths
+    assert len(paths) == 2
+    assert {
+        path.read_text(encoding="utf-8") for path in paths if path is not None
+    } == originals
+
+
+def test_failed_backup_keeps_config_and_removes_empty_reserved_file(
+    config_dir: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config, example, backup_dir = config_dir
+    monkeypatch.chdir(config.parent)
+    assert backup_dir.resolve().is_relative_to(config.parent)
+    original = config.read_bytes()
+
+    def fail_write(path: Path, content: str) -> None:
+        raise OSError("backup write failed")
+
+    monkeypatch.setattr(config_patch, "write_text", fail_write)
+    with pytest.raises(OSError, match="backup write failed"):
+        config_patch.apply_plan(
+            _plan(config, {"webui.port": 8788}),
+            example_path=example,
+            backup_dir=backup_dir,
+        )
+    assert config.read_bytes() == original
+    assert list(backup_dir.glob("config_*.toml")) == []
+
+
 def test_apply_is_idempotent(config_dir: tuple[Path, Path, Path]) -> None:
     config, example, backup_dir = config_dir
     plan = _plan(config, {"onebot.ws_url": "ws://napcat:3001"})

From bde8ee83cf928a2ef538b18d2992c373e5d9e6d2 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:08:06 +0800
Subject: [PATCH 037/121] fix(chat): isolate runtime state and stale
 asynchronous responses

---
 apps/undefined-chat/src/App.test.tsx          | 111 +++++++++
 apps/undefined-chat/src/App.tsx               |  19 +-
 .../src/chat-store/runtime-scope.test.ts      | 217 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  98 +++++++-
 .../rendering/AttachmentImageContext.test.tsx |  58 +++++
 .../src/rendering/AttachmentImageContext.tsx  |  36 +--
 docs/undefined-chat.md                        |   2 +
 7 files changed, 518 insertions(+), 23 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/runtime-scope.test.ts

diff --git a/apps/undefined-chat/src/App.test.tsx b/apps/undefined-chat/src/App.test.tsx
index d0b519a9..1758373f 100644
--- a/apps/undefined-chat/src/App.test.tsx
+++ b/apps/undefined-chat/src/App.test.tsx
@@ -1,5 +1,6 @@
 import { open } from "@tauri-apps/plugin-dialog";
 import {
+	act,
 	fireEvent,
 	render,
 	screen,
@@ -12,6 +13,10 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
 import { App } from "./App";
 import { LanguageProvider, LOCALE_STORAGE_KEY } from "./i18n";
 import { createTauriRuntimeClient } from "./runtime-client/tauri";
+import type {
+	AttachmentPreviewResult,
+	RuntimeConfig,
+} from "./runtime-client/types";
 import { conversation, historyItem, runtimeClientStub } from "./test-fixtures";
 
 vi.mock("./runtime-client/tauri", () => ({
@@ -30,6 +35,14 @@ function renderApp(ui: ReactElement = <App />) {
 	return render(<LanguageProvider>{ui}</LanguageProvider>);
 }
 
+async function connectRuntime(runtimeUrl: string): Promise<void> {
+	fireEvent.keyDown(window, { key: ",", ctrlKey: true });
+	await userEvent.clear(screen.getByLabelText("Runtime URL"));
+	await userEvent.type(screen.getByLabelText("Runtime URL"), runtimeUrl);
+	await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+	await screen.findByText(runtimeUrl);
+}
+
 describe("App", () => {
 	beforeEach(() => {
 		vi.resetAllMocks();
@@ -425,6 +438,104 @@ describe("App", () => {
 		});
 	});
 
+	test("ignores a file picker opened on the previous Runtime", async () => {
+		let resolvePicker!: (path: string) => void;
+		vi.mocked(open).mockImplementationOnce(
+			() =>
+				new Promise((resolve) => {
+					resolvePicker = resolve;
+				}),
+		);
+		let config: RuntimeConfig = {
+			runtimeUrl: "http://runtime-a.test",
+			hasApiKey: true,
+		};
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => config),
+			saveRuntimeConfig: vi.fn(async (runtimeUrl) => {
+				config = { ...config, runtimeUrl };
+				return config;
+			}),
+		});
+		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+		renderApp();
+		await screen.findByLabelText("消息输入");
+		await userEvent.click(screen.getByRole("button", { name: "添加附件" }));
+		await connectRuntime("http://runtime-b.test");
+		await waitFor(() => {
+			expect(client.getHistory).toHaveBeenCalledTimes(2);
+		});
+		resolvePicker("/tmp/runtime-a-private.txt");
+		await waitFor(() => {
+			expect(screen.getByLabelText("消息输入")).toHaveValue("");
+		});
+		expect(client.uploadAttachment).not.toHaveBeenCalled();
+	});
+
+	test("ignores a direct attachment preview returned from the previous Runtime", async () => {
+		let resolvePreview!: (result: AttachmentPreviewResult) => void;
+		let config: RuntimeConfig = {
+			runtimeUrl: "http://runtime-a.test",
+			hasApiKey: true,
+		};
+		const client = runtimeClientStub();
+		const getHistory = client.getHistory;
+		client.getRuntimeConfig = vi.fn(async () => config);
+		client.saveRuntimeConfig = vi.fn(async (runtimeUrl) => {
+			config = { ...config, runtimeUrl };
+			return config;
+		});
+		client.getHistory = vi.fn(async (request) => ({
+			...(await getHistory(request)),
+			items:
+				config.runtimeUrl === "http://runtime-a.test"
+					? [
+							historyItem({
+								attachments: [
+									{
+										id: "pic_a",
+										name: "private-a.png",
+										kind: "image",
+										mediaType: "image/png",
+										size: 20 * 1024 * 1024,
+										downloadUrl: "/api/v1/chat/attachments/pic_a",
+										previewUrl: "/api/v1/chat/attachments/pic_a/preview",
+										discarded: false,
+									},
+								],
+							}),
+						]
+					: [],
+		}));
+		client.previewAttachment = vi.fn(
+			() =>
+				new Promise<AttachmentPreviewResult>((resolve) => {
+					resolvePreview = resolve;
+				}),
+		);
+		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+		const createSpy = vi.spyOn(URL, "createObjectURL");
+		renderApp();
+		await screen.findByText("private-a.png");
+		await userEvent.click(screen.getByRole("button", { name: "预览" }));
+		await connectRuntime("http://runtime-b.test");
+		await waitFor(() => {
+			expect(screen.queryByText("private-a.png")).toBeNull();
+		});
+		await act(async () => {
+			resolvePreview({
+				status: 200,
+				ok: true,
+				mediaType: "image/png",
+				bytes: [1, 2, 3, 4],
+				body: null,
+			});
+		});
+		expect(screen.queryByRole("dialog", { name: "图片查看器" })).toBeNull();
+		expect(createSpy).not.toHaveBeenCalled();
+		createSpy.mockRestore();
+	});
+
 	test("uses native attachment bridges for timeline actions", async () => {
 		const client = runtimeClientStub({
 			getHistory: vi.fn(async () => ({
diff --git a/apps/undefined-chat/src/App.tsx b/apps/undefined-chat/src/App.tsx
index ceee074c..375b3e42 100644
--- a/apps/undefined-chat/src/App.tsx
+++ b/apps/undefined-chat/src/App.tsx
@@ -129,7 +129,7 @@ export function App() {
 	): Promise<void> {
 		setSetupError(null);
 		try {
-			await client.saveRuntimeConfig(url);
+			const config = await client.saveRuntimeConfig(url);
 			if (allowInsecure) {
 				await client.confirmInsecureStorageFallback();
 			}
@@ -138,7 +138,7 @@ export function App() {
 				await client.saveApiKey(apiKey);
 			}
 			setIsSettingsOpen(false);
-			await store.bootstrap();
+			await store.bootstrap({ runtimeUrl: config.runtimeUrl });
 		} catch (err) {
 			setSetupError(err instanceof Error ? err.message : String(err));
 		}
@@ -165,10 +165,12 @@ export function App() {
 	}
 
 	async function previewAttachment(attachment: Attachment): Promise<void> {
+		const runtimeConfig = store.getSnapshot().runtimeConfig;
 		try {
 			const result = await client.previewAttachment({
 				attachmentId: attachment.id,
 			});
+			if (store.getSnapshot().runtimeConfig !== runtimeConfig) return;
 			if (!result.ok || result.bytes.length === 0) {
 				window.alert(result.body ?? t("attachment.previewFailed"));
 				return;
@@ -188,11 +190,13 @@ export function App() {
 			window.open(url, "_blank", "noopener,noreferrer");
 			window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
 		} catch (err) {
+			if (store.getSnapshot().runtimeConfig !== runtimeConfig) return;
 			window.alert(err instanceof Error ? err.message : String(err));
 		}
 	}
 
 	async function addAttachment(conversationId: string): Promise<void> {
+		const runtimeConfig = store.getSnapshot().runtimeConfig;
 		try {
 			const selected = await open({
 				multiple: false,
@@ -201,10 +205,12 @@ export function App() {
 				pickerMode: "document",
 				fileAccessMode: "copy",
 			});
+			if (store.getSnapshot().runtimeConfig !== runtimeConfig) return;
 			if (typeof selected === "string") {
 				await store.addAttachmentPath(conversationId, selected);
 			}
 		} catch (err) {
+			if (store.getSnapshot().runtimeConfig !== runtimeConfig) return;
 			window.alert(err instanceof Error ? err.message : String(err));
 		}
 	}
@@ -215,7 +221,9 @@ export function App() {
 			return;
 		}
 		// 尚无会话：先自动创建再把示例填入草稿
+		const runtimeConfig = store.getSnapshot().runtimeConfig;
 		void store.createConversation().then(() => {
+			if (store.getSnapshot().runtimeConfig !== runtimeConfig) return;
 			const conversationId = store.getSnapshot().selectedConversationId;
 			if (conversationId) {
 				store.updateDraft(conversationId, prompt);
@@ -293,7 +301,7 @@ export function App() {
 				previewImageUrlRef.current = null;
 			}
 		};
-	}, []);
+	}, [state.runtimeConfig?.runtimeUrl]);
 
 	useEffect(() => {
 		if (!isMobile || !isMobileSidebarActive) {
@@ -460,7 +468,10 @@ export function App() {
 	]);
 
 	return (
-		<AttachmentImageProvider client={client}>
+		<AttachmentImageProvider
+			client={client}
+			runtimeUrl={state.runtimeConfig?.runtimeUrl}
+		>
 			<main className="chat-app">
 				{/* 移动端侧边栏背景遮罩 */}
 				<div
diff --git a/apps/undefined-chat/src/chat-store/runtime-scope.test.ts b/apps/undefined-chat/src/chat-store/runtime-scope.test.ts
new file mode 100644
index 00000000..b885adf6
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/runtime-scope.test.ts
@@ -0,0 +1,217 @@
+import { invoke } from "@tauri-apps/api/core";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { createTauriRuntimeClient } from "../runtime-client/tauri";
+import type { Attachment, HistoryResponse } from "../runtime-client/types";
+import {
+	conversation,
+	historyItem,
+	job,
+	runtimeClientStub,
+} from "../test-fixtures";
+import { createChatStore } from "./store";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	let reject!: (reason: Error) => void;
+	const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+		resolve = resolvePromise;
+		reject = rejectPromise;
+	});
+	return { promise, resolve, reject };
+}
+
+describe("Runtime instance isolation", () => {
+	beforeEach(() => vi.resetAllMocks());
+
+	test("a new Runtime sharing the default conversation sends only its own editor state through Tauri", async () => {
+		const id = "legacy-system-42";
+		let runtimeUrl = "http://runtime-a.example";
+		let invokedOrigin = "";
+		vi.mocked(invoke).mockImplementation(async () => {
+			invokedOrigin = runtimeUrl;
+			return {
+				status: 202,
+				ok: true,
+				body: { job_id: "new", conversation_id: id },
+			};
+		});
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => ({ runtimeUrl, hasApiKey: true })),
+			listConversations: vi.fn(async () => ({
+				conversations: [conversation({ id })],
+				activeJob: null,
+				defaultConversationId: id,
+				virtualUserId: "webchat",
+			})),
+			getHistory: vi.fn(async () => ({
+				conversationId: id,
+				virtualUserId: "webchat",
+				permission: "superadmin",
+				count: 1,
+				limit: 50,
+				before: null,
+				hasMore: false,
+				nextBefore: null,
+				total: 1,
+				items: [
+					historyItem({
+						messageId: runtimeUrl,
+						role: "bot",
+						content: runtimeUrl,
+					}),
+				],
+			})),
+			sendMessage: createTauriRuntimeClient().sendMessage,
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft(id, "A private draft");
+		store.addReferenceFromMessageId(id, runtimeUrl);
+		await store.addAttachmentPath(id, "/mock/a-private.pdf");
+		store.dispatch({ type: "autoScroll/set", enabled: false });
+		runtimeUrl = "http://runtime-b.example";
+		await store.bootstrap({ runtimeUrl });
+		const state = store.getSnapshot();
+		expect(state.draftsByConversation).toEqual({});
+		expect(state.referencesByConversation).toEqual({});
+		expect(state.attachmentsByConversation).toEqual({});
+		expect(state.historyByConversation[id].items[0].content).toBe(runtimeUrl);
+		expect(state.autoScrollEnabled).toBe(false);
+		store.updateDraft(id, "B request");
+		await store.sendSelectedMessage();
+		expect(invokedOrigin).toBe(runtimeUrl);
+		expect(invoke).toHaveBeenCalledWith("send_message", {
+			input: {
+				conversationId: id,
+				message: { text: "B request", attachment_ids: [], references: [] },
+			},
+		});
+	});
+
+	test("reconnecting to the same Runtime preserves drafts, references, and ready attachments", async () => {
+		const client = runtimeClientStub();
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "keep draft");
+		store.addReference("default", { messageId: "a", quote: "keep quote" });
+		await store.addAttachmentPath("default", "/mock/a.pdf");
+		const before = store.getSnapshot();
+		await store.bootstrap({
+			runtimeUrl: before.runtimeConfig?.runtimeUrl,
+			resuming: true,
+		});
+		const after = store.getSnapshot();
+		expect(after.draftsByConversation).toEqual(before.draftsByConversation);
+		expect(after.referencesByConversation).toEqual(
+			before.referencesByConversation,
+		);
+		expect(after.attachmentsByConversation).toEqual(
+			before.attachmentsByConversation,
+		);
+	});
+
+	test("old history, uploads, and failed sends cannot repopulate a replacement Runtime", async () => {
+		let runtimeUrl = "http://runtime-a.example";
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => ({ runtimeUrl, hasApiKey: true })),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		const history = deferred<HistoryResponse>();
+		const upload = deferred<Attachment>();
+		const send = deferred<ReturnType<typeof job>>();
+		vi.mocked(client.getHistory).mockImplementationOnce(() => history.promise);
+		vi.mocked(client.uploadAttachment).mockImplementationOnce(
+			() => upload.promise,
+		);
+		vi.mocked(client.sendMessage).mockImplementationOnce(() => send.promise);
+		store.updateDraft("default", "A pending send");
+		const oldSend = store.sendSelectedMessage();
+		const oldUpload = store.addAttachmentPath("default", "/mock/a.pdf");
+		const oldHistory = store.reloadHistory("default");
+		runtimeUrl = "http://runtime-b.example";
+		await store.bootstrap({ runtimeUrl });
+		store.updateDraft("default", "B new draft");
+		history.resolve({
+			conversationId: "default",
+			virtualUserId: "webchat",
+			permission: "superadmin",
+			count: 1,
+			limit: 50,
+			before: null,
+			hasMore: false,
+			nextBefore: null,
+			total: 1,
+			items: [historyItem({ content: "A late history" })],
+		});
+		upload.resolve({
+			id: "A-uid",
+			name: "a.pdf",
+			size: 1,
+			mediaType: "application/pdf",
+			kind: "file",
+			downloadUrl: "",
+			previewUrl: null,
+			discarded: false,
+		});
+		send.reject(new Error("A late send failure"));
+		await Promise.all([oldHistory, oldUpload, oldSend]);
+		expect(store.getSnapshot().draftsByConversation.default).toBe(
+			"B new draft",
+		);
+		expect(store.getSnapshot().attachmentsByConversation).toEqual({});
+		expect(store.getSnapshot().historyByConversation.default.items).toEqual([]);
+		expect(store.getSnapshot().sendError).toBeNull();
+		await store.sendSelectedMessage();
+		expect(client.sendMessage).toHaveBeenLastCalledWith({
+			conversationId: "default",
+			message: { text: "B new draft", attachmentIds: [], references: [] },
+		});
+	});
+
+	test("a replacement Runtime preempts an old bootstrap and ignores its late SSE callback", async () => {
+		let runtimeUrl = "http://runtime-a.example";
+		const history = deferred<HistoryResponse>();
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => ({ runtimeUrl, hasApiKey: true })),
+		});
+		vi.mocked(client.getHistory).mockImplementationOnce(() => history.promise);
+		const store = createChatStore({ client });
+		const oldBootstrap = store.bootstrap();
+		await vi.waitFor(() => expect(client.getHistory).toHaveBeenCalledTimes(1));
+		const oldStatus = vi.mocked(client.listenRuntimeSse).mock.calls[0][1];
+		runtimeUrl = "http://runtime-b.example";
+		const newJob = job();
+		vi.mocked(client.getActiveJobs).mockResolvedValue({
+			job: newJob,
+			jobs: [newJob],
+		});
+		await store.bootstrap({ runtimeUrl });
+		oldStatus({
+			subscriptionId: "old",
+			jobId: newJob.jobId,
+			status: "closed",
+			detail: "late",
+		});
+		expect(client.fetchJobEventsJson).not.toHaveBeenCalled();
+		history.resolve({
+			conversationId: "default",
+			virtualUserId: "webchat",
+			permission: "superadmin",
+			count: 1,
+			limit: 50,
+			before: null,
+			hasMore: false,
+			nextBefore: null,
+			total: 1,
+			items: [historyItem({ content: "A late bootstrap" })],
+		});
+		await oldBootstrap;
+		expect(store.getSnapshot().runtimeConfig?.runtimeUrl).toBe(runtimeUrl);
+		expect(store.getSnapshot().historyByConversation.default.items).toEqual([]);
+		expect(store.getSnapshot().connectionState).toBe("streaming");
+	});
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index b62ff717..45c029c4 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -26,6 +26,7 @@ export type {
 
 export type ChatStore = {
 	bootstrap: (opts?: {
+		runtimeUrl?: string;
 		preserveSelectionId?: string;
 		resuming?: boolean;
 	}) => Promise<void>;
@@ -669,6 +670,8 @@ export function createChatStore({
 	client: RuntimeClient;
 }): ChatStore {
 	let state = createInitialChatState();
+	let runtimeUrl: string | null = null;
+	let runtimeGeneration = 0;
 	const listeners = new Set<() => void>();
 	const subscriptionsByJob = new Map<string, string>();
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
@@ -711,15 +714,32 @@ export function createChatStore({
 		}
 		fallbackTimersByJob.clear();
 		latestFallbackRequestByJob.clear();
+		fallbackBackoffByJob.clear();
+	}
+
+	function resetRuntimeScope(nextUrl: string): void {
+		runtimeUrl = nextUrl;
+		runtimeGeneration += 1;
+		clearNativeSubscriptions();
+		sendInFlight = false;
+		lastCommandsFetchedAt = 0;
+		state = {
+			...createInitialChatState(),
+			autoScrollEnabled: state.autoScrollEnabled,
+			platform: state.platform,
+			settings: state.settings,
+		};
 	}
 
 	async function loadHistory(conversationId: string): Promise<void> {
+		const generation = runtimeGeneration;
 		dispatch({ type: "history/loading", conversationId });
 		try {
 			const history = await client.getHistory({
 				conversationId,
 				limit: HISTORY_LIMIT,
 			});
+			if (generation !== runtimeGeneration) return;
 			dispatch({
 				type: "history/set",
 				conversationId,
@@ -729,6 +749,7 @@ export function createChatStore({
 				total: history.total,
 			});
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			// 单会话历史加载失败降级为会话级错误，不升级为全局致命错误
 			dispatch({
 				type: "history/error",
@@ -739,6 +760,7 @@ export function createChatStore({
 	}
 
 	async function startStreamForJob(job: ChatJob): Promise<void> {
+		const generation = runtimeGeneration;
 		if (subscriptionsByJob.has(job.jobId)) {
 			return;
 		}
@@ -748,10 +770,17 @@ export function createChatStore({
 				afterSeq: state.eventCursorByJob[job.jobId] ?? job.lastSeq,
 				conversationId: job.conversationId,
 			});
+			if (generation !== runtimeGeneration) {
+				if (subscription.subscriptionId) {
+					void client.stopJobEventStream(subscription.subscriptionId);
+				}
+				return;
+			}
 			if (subscription.subscriptionId) {
 				subscriptionsByJob.set(job.jobId, subscription.subscriptionId);
 			}
 		} catch {
+			if (generation !== runtimeGeneration) return;
 			// job 已建立；订阅失败只切换传输方式，不能回滚成功发送的输入。
 			fetchJobEventsFallback(job.jobId);
 		}
@@ -800,7 +829,9 @@ export function createChatStore({
 		if (fallbackTimersByJob.has(jobId)) {
 			return;
 		}
+		const generation = runtimeGeneration;
 		const timer = setTimeout(() => {
+			if (generation !== runtimeGeneration) return;
 			fallbackTimersByJob.delete(jobId);
 			fetchJobEventsFallback(jobId);
 		}, delayMs ?? JSON_FALLBACK_BASE_MS);
@@ -808,6 +839,7 @@ export function createChatStore({
 	}
 
 	function fetchJobEventsFallback(jobId: string): void {
+		const generation = runtimeGeneration;
 		const conversationId = state.jobConversationById[jobId];
 		if (
 			!conversationId ||
@@ -818,6 +850,7 @@ export function createChatStore({
 		const requestGeneration = ++fallbackRequestGeneration;
 		latestFallbackRequestByJob.set(jobId, requestGeneration);
 		const isCurrentRequest = (): boolean =>
+			generation === runtimeGeneration &&
 			latestFallbackRequestByJob.get(jobId) === requestGeneration &&
 			state.activeJobsByConversation[conversationId]?.jobId === jobId;
 		const timer = fallbackTimersByJob.get(jobId);
@@ -892,6 +925,7 @@ export function createChatStore({
 		preserveSelectionId?: string,
 		resuming = false,
 	): Promise<void> {
+		let generation = runtimeGeneration;
 		dispatch({ type: "bootstrap/start" });
 		// Android 切后台返回等续接场景：标记为 resuming，连接成功后由后续状态覆盖
 		if (resuming) {
@@ -899,6 +933,15 @@ export function createChatStore({
 		}
 		try {
 			const runtimeConfig = await client.getRuntimeConfig();
+			if (generation !== runtimeGeneration) return;
+			if (
+				runtimeConfig?.runtimeUrl &&
+				runtimeConfig.runtimeUrl !== runtimeUrl
+			) {
+				resetRuntimeScope(runtimeConfig.runtimeUrl);
+				generation = runtimeGeneration;
+				dispatch({ type: "bootstrap/start" });
+			}
 			if (!runtimeConfig?.runtimeUrl || !runtimeConfig.hasApiKey) {
 				dispatch({
 					type: "bootstrap/error",
@@ -915,6 +958,7 @@ export function createChatStore({
 					client.getActiveJobs(),
 					client.listCommands(),
 				]);
+			if (generation !== runtimeGeneration) return;
 			lastCommandsFetchedAt = Date.now();
 			// 仅选取真实存在于会话列表中的会话：defaultConversationId 是后端常量
 			// （legacy-system-42），未必对应已存在的会话，盲目用它会触发 getHistory 404
@@ -944,16 +988,27 @@ export function createChatStore({
 				commands: commands.commands,
 			});
 			clearNativeSubscriptions();
-			unlistenRuntimeSse = await client.listenRuntimeSse(
-				handleRuntimeEvent,
-				handleRuntimeStatus,
+			const unlisten = await client.listenRuntimeSse(
+				(event) => {
+					if (generation === runtimeGeneration) handleRuntimeEvent(event);
+				},
+				(status) => {
+					if (generation === runtimeGeneration) handleRuntimeStatus(status);
+				},
 			);
+			if (generation !== runtimeGeneration) {
+				unlisten();
+				return;
+			}
+			unlistenRuntimeSse = unlisten;
 			for (const activeJob of activeJobs.jobs) {
+				if (generation !== runtimeGeneration) return;
 				await startStreamForJob(activeJob);
 			}
 			if (selected) {
 				await loadHistory(selected);
 			}
+			if (generation !== runtimeGeneration) return;
 			if (
 				activeJobs.jobs.length > 0 &&
 				state.connectionState !== "json_fallback"
@@ -961,14 +1016,20 @@ export function createChatStore({
 				dispatch({ type: "connection/set", connectionState: "streaming" });
 			}
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "bootstrap/error", error: errorMessage(err) });
 		}
 	}
 
 	async function bootstrap(opts?: {
+		runtimeUrl?: string;
 		preserveSelectionId?: string;
 		resuming?: boolean;
 	}): Promise<void> {
+		if (opts?.runtimeUrl && opts.runtimeUrl !== runtimeUrl) {
+			resetRuntimeScope(opts.runtimeUrl);
+			inFlightBootstrap = null;
+		}
 		// 重入保护：App 挂载与 Android resume 可能并发触发 bootstrap，
 		// 复用进行中的 promise，避免重复 clearNativeSubscriptions / listenRuntimeSse 造成监听泄漏
 		if (inFlightBootstrap) {
@@ -976,7 +1037,7 @@ export function createChatStore({
 		}
 		const run = runBootstrap(opts?.preserveSelectionId, opts?.resuming).finally(
 			() => {
-				inFlightBootstrap = null;
+				if (inFlightBootstrap === run) inFlightBootstrap = null;
 			},
 		);
 		inFlightBootstrap = run;
@@ -988,6 +1049,7 @@ export function createChatStore({
 	 * 使 Skills 热重载新增的命令可见。未连接或未配置时跳过。
 	 */
 	async function refreshCommandsIfStale(): Promise<void> {
+		const generation = runtimeGeneration;
 		if (!state.runtimeConfig?.hasApiKey || state.bootstrapping) {
 			return;
 		}
@@ -996,6 +1058,7 @@ export function createChatStore({
 		}
 		try {
 			const commands = await client.listCommands();
+			if (generation !== runtimeGeneration) return;
 			lastCommandsFetchedAt = Date.now();
 			dispatch({ type: "commands/set", commands: commands.commands });
 		} catch {
@@ -1004,19 +1067,25 @@ export function createChatStore({
 	}
 
 	async function createConversation(title?: string): Promise<void> {
+		const generation = runtimeGeneration;
 		dispatch({ type: "conversation/creating", creating: true });
 		try {
 			const conversation = await client.createConversation(title);
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "conversation/upsert", conversation });
 			await loadHistory(conversation.id);
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		} finally {
-			dispatch({ type: "conversation/creating", creating: false });
+			if (generation === runtimeGeneration) {
+				dispatch({ type: "conversation/creating", creating: false });
+			}
 		}
 	}
 
 	async function deleteConversation(conversationId: string): Promise<void> {
+		const generation = runtimeGeneration;
 		const wasSelected = state.selectedConversationId === conversationId;
 		const nextSelectedId = wasSelected
 			? (state.conversations.find((item) => item.id !== conversationId)?.id ??
@@ -1024,6 +1093,7 @@ export function createChatStore({
 			: state.selectedConversationId;
 		try {
 			await client.deleteConversation(conversationId);
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "conversation/remove", conversationId, nextSelectedId });
 			if (
 				wasSelected &&
@@ -1033,6 +1103,7 @@ export function createChatStore({
 				await loadHistory(nextSelectedId);
 			}
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		}
 	}
@@ -1041,8 +1112,10 @@ export function createChatStore({
 		conversationId: string,
 		newTitle: string,
 	): Promise<void> {
+		const generation = runtimeGeneration;
 		try {
 			await client.renameConversation(conversationId, newTitle);
+			if (generation !== runtimeGeneration) return;
 			// 更新本地 state 中的会话标题
 			const conversation = state.conversations.find(
 				(item) => item.id === conversationId,
@@ -1054,6 +1127,7 @@ export function createChatStore({
 				});
 			}
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		}
 	}
@@ -1073,6 +1147,7 @@ export function createChatStore({
 	}
 
 	async function sendSelectedMessage(): Promise<void> {
+		const generation = runtimeGeneration;
 		// in-flight 锁：从点击到 job 建立期间阻止重复发送，
 		// 避免快速双击重复插入乐观消息 / 重复请求后端
 		if (sendInFlight) {
@@ -1142,10 +1217,12 @@ export function createChatStore({
 		try {
 			dispatch({ type: "send/error", error: null });
 			const job = await client.sendMessage(input);
+			if (generation !== runtimeGeneration) return;
 			dispatch({ type: "job/upsert", job });
 			dispatch({ type: "connection/set", connectionState: "streaming" });
 			await startStreamForJob(job);
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			// 发送失败：移除乐观用户消息并恢复草稿/附件/引用
 			const currentHistory = state.historyByConversation[conversationId];
 			if (currentHistory) {
@@ -1165,17 +1242,19 @@ export function createChatStore({
 			dispatch({ type: "references/set", conversationId, references });
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		} finally {
-			sendInFlight = false;
+			if (generation === runtimeGeneration) sendInFlight = false;
 		}
 	}
 
 	async function cancelJob(jobId: string): Promise<void> {
+		const generation = runtimeGeneration;
 		const conversationId = state.jobConversationById[jobId];
 		if (!conversationId) {
 			return;
 		}
 		try {
 			const cancelled = await client.cancelJob(jobId);
+			if (generation !== runtimeGeneration) return;
 			const current = state.activeJobsByConversation[conversationId];
 			if (current?.jobId !== jobId) {
 				return;
@@ -1195,6 +1274,7 @@ export function createChatStore({
 				finishJob(jobId, conversationId);
 			}
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			if (state.activeJobsByConversation[conversationId]?.jobId !== jobId) {
 				return;
 			}
@@ -1206,6 +1286,7 @@ export function createChatStore({
 		conversationId: string,
 		filePath: string,
 	): Promise<void> {
+		const generation = runtimeGeneration;
 		const trimmed = filePath.trim();
 		if (!trimmed) {
 			return;
@@ -1224,6 +1305,7 @@ export function createChatStore({
 		dispatch({ type: "attachments/set", conversationId, attachments: queued });
 		try {
 			const attachment = await client.uploadAttachment({ filePath: trimmed });
+			if (generation !== runtimeGeneration) return;
 			const current = state.attachmentsByConversation[conversationId] ?? [];
 			dispatch({
 				type: "attachments/set",
@@ -1241,6 +1323,7 @@ export function createChatStore({
 				),
 			});
 		} catch (err) {
+			if (generation !== runtimeGeneration) return;
 			const current = state.attachmentsByConversation[conversationId] ?? [];
 			dispatch({
 				type: "attachments/set",
@@ -1552,6 +1635,7 @@ export function createChatStore({
 	}
 
 	async function loadMoreHistory(conversationId: string): Promise<void> {
+		const generation = runtimeGeneration;
 		const historyState = state.historyByConversation[conversationId];
 		if (!historyState?.hasMore || historyState.loading) {
 			return;
@@ -1565,6 +1649,7 @@ export function createChatStore({
 				historyState.nextBefore ?? undefined,
 				HISTORY_LIMIT,
 			);
+			if (generation !== runtimeGeneration) return;
 
 			const newItems = [...response.items, ...historyState.items];
 
@@ -1577,6 +1662,7 @@ export function createChatStore({
 				total: response.total,
 			});
 		} catch (error) {
+			if (generation !== runtimeGeneration) return;
 			dispatch({
 				type: "history/error",
 				conversationId,
diff --git a/apps/undefined-chat/src/rendering/AttachmentImageContext.test.tsx b/apps/undefined-chat/src/rendering/AttachmentImageContext.test.tsx
index adf67af6..7b97fd67 100644
--- a/apps/undefined-chat/src/rendering/AttachmentImageContext.test.tsx
+++ b/apps/undefined-chat/src/rendering/AttachmentImageContext.test.tsx
@@ -130,4 +130,62 @@ describe("AttachmentImageContext", () => {
 		expect(revokeSpy).toHaveBeenCalledTimes(2);
 		revokeSpy.mockRestore();
 	});
+
+	it("Provider 卸载后迟到的预览不再创建或缓存旧实例 blob", async () => {
+		let resolve!: (result: AttachmentPreviewResult) => void;
+		const createSpy = vi.spyOn(URL, "createObjectURL");
+		const { client } = makeClient(
+			() =>
+				new Promise((done) => {
+					resolve = done;
+				}),
+		);
+		const { result, unmount } = renderHook(() => useAttachmentImage(), {
+			wrapper: makeWrapper(client),
+		});
+		const pending = result.current.loadAttachmentBlob("pic_old");
+		unmount();
+		resolve(imageResult());
+		expect(await pending).toBeNull();
+		expect(createSpy).not.toHaveBeenCalled();
+		createSpy.mockRestore();
+	});
+
+	it("切换 Runtime 释放旧缓存，相同 UID 在新实例重新加载并拒绝旧回包", async () => {
+		let resolve!: (result: AttachmentPreviewResult) => void;
+		let runtimeUrl = "http://runtime-a.test";
+		const { client, previewAttachment } = makeClient();
+		previewAttachment.mockImplementationOnce(
+			() =>
+				new Promise((done) => {
+					resolve = done;
+				}),
+		);
+		function Wrapper({ children }: { children: ReactNode }) {
+			return (
+				<AttachmentImageProvider client={client} runtimeUrl={runtimeUrl}>
+					{children}
+				</AttachmentImageProvider>
+			);
+		}
+		const { result, rerender } = renderHook(() => useAttachmentImage(), {
+			wrapper: Wrapper,
+		});
+		const pending = result.current.loadAttachmentBlob("pic_pending");
+		const cached = await result.current.loadAttachmentBlob("pic_shared");
+		const revokeSpy = vi.spyOn(URL, "revokeObjectURL");
+		runtimeUrl = "http://runtime-b.test";
+		rerender();
+		expect(revokeSpy).toHaveBeenCalledWith(cached?.url);
+		const current = await result.current.loadAttachmentBlob("pic_shared");
+		expect(current?.url).not.toBe(cached?.url);
+		const createSpy = vi.spyOn(URL, "createObjectURL");
+		resolve(imageResult());
+		expect(await pending).toBeNull();
+		expect(createSpy).not.toHaveBeenCalled();
+		expect(await result.current.loadAttachmentBlob("pic_shared")).toBe(current);
+		expect(previewAttachment).toHaveBeenCalledTimes(3);
+		revokeSpy.mockRestore();
+		createSpy.mockRestore();
+	});
 });
diff --git a/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx b/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
index b41a55e0..c8484434 100644
--- a/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
+++ b/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
@@ -5,7 +5,6 @@ import {
 	useContext,
 	useEffect,
 	useMemo,
-	useRef,
 } from "react";
 import type { RuntimeClient } from "../runtime-client/types";
 
@@ -26,6 +25,8 @@ const DEFAULT_MAX_CACHE_SIZE = 60;
 export type AttachmentImageProviderProps = {
 	/** 仅依赖 previewAttachment，便于测试以最小桩注入 */
 	client: Pick<RuntimeClient, "previewAttachment">;
+	/** 按 Runtime URL 隔离 UID 缓存，保持消费组件与 DOM 的生命周期。 */
+	runtimeUrl?: string | null;
 	/** blob 缓存上限，超出按 LRU 淘汰并 revoke。默认 60。 */
 	maxCacheSize?: number;
 	children: ReactNode;
@@ -41,23 +42,28 @@ export type AttachmentImageProviderProps = {
  * - LRU 缓存 uid→blobUrl：缩略图/正文图/全屏大图复用同一 blob，避免重复拉取。
  * - inflight 去重：同一 UID 并发请求只发一次。
  * - blob URL 归本 Provider 所有：消费组件**不**自行 revoke（缩略图与大图共享同一
- *   URL，组件卸载即 revoke 会让仍打开的大图破图），仅在 LRU 淘汰或 Provider 卸载
- *   时 revoke。
+ *   URL，组件卸载即 revoke 会让仍打开的大图破图），仅在 LRU 淘汰、切换 Runtime
+ *   或 Provider 卸载时 revoke。
  */
 export function AttachmentImageProvider({
 	client,
+	runtimeUrl,
 	maxCacheSize = DEFAULT_MAX_CACHE_SIZE,
 	children,
 }: AttachmentImageProviderProps) {
-	const cacheRef = useRef<Map<string, LoadedAttachmentBlob>>(new Map());
-	const inflightRef = useRef<Map<string, Promise<LoadedAttachmentBlob | null>>>(
-		new Map(),
+	const scope = useMemo(
+		() => ({
+			runtimeUrl,
+			cache: new Map<string, LoadedAttachmentBlob>(),
+			inflight: new Map<string, Promise<LoadedAttachmentBlob | null>>(),
+			generation: 0,
+		}),
+		[runtimeUrl],
 	);
 
 	const loadAttachmentBlob = useCallback(
 		(uid: string): Promise<LoadedAttachmentBlob | null> => {
-			const cache = cacheRef.current;
-			const inflight = inflightRef.current;
+			const { cache, inflight } = scope;
 
 			const cached = cache.get(uid);
 			if (cached) {
@@ -71,8 +77,10 @@ export function AttachmentImageProvider({
 			if (pending) return pending;
 
 			const promise = (async (): Promise<LoadedAttachmentBlob | null> => {
+				const generation = scope.generation;
 				try {
 					const result = await client.previewAttachment({ attachmentId: uid });
+					if (generation !== scope.generation) return null;
 					if (!result.ok || result.bytes.length === 0) {
 						return null;
 					}
@@ -97,26 +105,28 @@ export function AttachmentImageProvider({
 				} catch {
 					return null;
 				} finally {
-					inflight.delete(uid);
+					if (generation === scope.generation) inflight.delete(uid);
 				}
 			})();
 
 			inflight.set(uid, promise);
 			return promise;
 		},
-		[client, maxCacheSize],
+		[client, maxCacheSize, scope],
 	);
 
-	// Provider 卸载时释放全部 blob URL
+	// 切换 Runtime 或卸载时释放全部 blob URL，拒绝旧作用域迟到的响应。
 	useEffect(() => {
-		const cache = cacheRef.current;
+		const { cache, inflight } = scope;
 		return () => {
+			scope.generation += 1;
+			inflight.clear();
 			for (const { url } of cache.values()) {
 				URL.revokeObjectURL(url);
 			}
 			cache.clear();
 		};
-	}, []);
+	}, [scope]);
 
 	const value = useMemo<AttachmentImageContextValue>(
 		() => ({ loadAttachmentBlob }),
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index b05ebe0d..d6b4de95 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -50,6 +50,8 @@ Undefined Chat 不持久化权威聊天数据。以下内容都以 Runtime 返
 
 本地只保存 UI 相关状态，例如当前会话、草稿、事件游标、窗口布局、连接档案和是否允许不安全存储降级。刷新、重启或换端之后，客户端必须重新从 Runtime 恢复会话和任务状态。
 
+连接到不同 Runtime 时，会清理旧实例的草稿、附件 UID、消息引用、历史、任务和图片预览缓存，并丢弃旧实例迟到的请求或订阅通知，避免相同会话 ID 造成跨实例误发送。同一 Runtime 的重连及 Android 恢复保留编辑状态和 UI 偏好；自动滚动、平台与布局偏好在切换实例时也保留。
+
 ## 连接与事件
 
 Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 React 传入任意 URL 后绕过目标主机限制。React 不直接持有 API Key；受保护请求由 Rust 侧注入 `X-Undefined-API-Key`。

From 36e2ab1a2deca57fde3349b2c902ca880404c154 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:10:20 +0800
Subject: [PATCH 038/121] fix(scripts): retry incomplete version
 synchronization

---
 scripts/README.md                 |   1 +
 scripts/bump_version.py           |  32 ++++--
 tests/test_bump_version_script.py | 176 ++++++++++++++++++++++++++++++
 3 files changed, 200 insertions(+), 9 deletions(-)

diff --git a/scripts/README.md b/scripts/README.md
index 1fd047f6..aaca81e9 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -179,6 +179,7 @@ uv run python scripts/bump_version.py 3.6.0 --commit
 - `apps/undefined-chat/src-tauri/Cargo.lock`
 
 非 dry-run 时脚本还会执行 `uv sync`，并分别在 Console / Chat 下执行 `npm install --package-lock-only` 与 `cargo update --workspace`，保证 lock 文件和 manifest 不漂移。
+每次运行都会逐一核对所有版本文件，即使 `pyproject.toml` 已是目标版本也会补齐其余目标；非 dry-run 时仍完整执行锁文件同步。若写文件或同步依赖中途失败，修复原因后重跑同一个版本即可继续，不会因主版本已更新而跳过。锁同步实际修改的 `uv.lock`、`package-lock.json` 和 `Cargo.lock` 也会列入变更清单，`--commit` 会包含这些文件。`--dry-run` 只预览版本文件差异，不写盘或执行依赖同步。
 脚本更新 JSON manifest 时只替换顶层 `version` 字段，保留现有格式，避免 Tauri 配置与 Biome 格式化规则漂移。
 
 ### prepare_tauri_android.py — 生成后 Android 修补
diff --git a/scripts/bump_version.py b/scripts/bump_version.py
index 72ee5064..421ad6db 100644
--- a/scripts/bump_version.py
+++ b/scripts/bump_version.py
@@ -247,13 +247,7 @@ def bump_project_versions(
         raise ValueError(f"'{version}' 不是合法的语义版本号 (x.y.z)")
 
     current = _read_current_version(root)
-    if version == current:
-        return BumpResult(
-            old_version=current,
-            new_version=version,
-            changed_paths=(),
-        )
-
+    # pyproject 可能已在上次失败前写完；同版本也必须逐一核对其余目标。
     changed: list[str] = []
     text_targets: tuple[tuple[Path, str, str], ...] = (
         (
@@ -274,8 +268,25 @@ def bump_project_versions(
     for app in NATIVE_APPS:
         changed.extend(_update_native_app_versions(root, app, version, dry_run))
 
-    if changed and not dry_run:
+    if not dry_run:
+        lock_paths = [root / "uv.lock"]
+        for app in NATIVE_APPS:
+            lock_paths.extend(
+                [
+                    app.app_root(root) / "package-lock.json",
+                    app.tauri_root(root) / "Cargo.lock",
+                ]
+            )
+        before_sync = {
+            path: path.read_bytes() if path.is_file() else None for path in lock_paths
+        }
+        # manifest 已一致也可能是上次同步 lock 失败后的重跑。
         sync_lock_files(root, dry_run=False)
+        for path, previous in before_sync.items():
+            content = path.read_bytes() if path.is_file() else None
+            relative = _relative(root, path)
+            if content != previous and relative not in changed:
+                changed.append(relative)
 
     return BumpResult(
         old_version=current,
@@ -310,7 +321,10 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     if not result.changed_paths:
-        print(f"版本已经是 {result.old_version}，无需更新")
+        if dry_run:
+            print(f"版本文件已经是 {result.old_version}；实际执行时仍会同步 lock 文件")
+        else:
+            print(f"版本文件已经是 {result.old_version}，lock 文件同步完成")
         return 0
 
     prefix = "(dry-run) " if dry_run else ""
diff --git a/tests/test_bump_version_script.py b/tests/test_bump_version_script.py
index a13cf30f..26f8ff3c 100644
--- a/tests/test_bump_version_script.py
+++ b/tests/test_bump_version_script.py
@@ -2,6 +2,7 @@
 
 import importlib.util
 import json
+import subprocess
 from pathlib import Path
 import sys
 from types import ModuleType
@@ -26,6 +27,16 @@ def _load_script() -> ModuleType:
 bump_version = _load_script()
 
 
+@pytest.fixture(autouse=True)
+def _isolate_commands(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    def forbidden(*args: Any, **kwargs: Any) -> Any:
+        raise AssertionError("tests must not run external commands")
+
+    monkeypatch.setattr(bump_version.subprocess, "run", forbidden)
+
+
 def _write_bump_project(root: Path, *, version: str = "1.2.3") -> None:
     (root / "src" / "Undefined").mkdir(parents=True)
     (root / "pyproject.toml").write_text(
@@ -214,3 +225,168 @@ def test_bump_project_versions_rejects_invalid_version(tmp_path: Path) -> None:
             project_root=tmp_path,
             dry_run=True,
         )
+
+
+def _assert_all_versions(root: Path, version: str) -> None:
+    assert (
+        tomllib_loads((root / "pyproject.toml").read_text(encoding="utf-8"))["project"][
+            "version"
+        ]
+        == version
+    )
+    assert f'__version__: str = "{version}"' in (
+        root / "src" / "Undefined" / "__init__.py"
+    ).read_text(encoding="utf-8")
+    for app in bump_version.NATIVE_APPS:
+        app_root = app.app_root(root)
+        tauri_root = app.tauri_root(root)
+        assert _json_version(app_root / "package.json") == version
+        assert _package_lock_versions(app_root / "package-lock.json") == (
+            version,
+            version,
+        )
+        assert (
+            tomllib_loads((tauri_root / "Cargo.toml").read_text(encoding="utf-8"))[
+                "package"
+            ]["version"]
+            == version
+        )
+        assert _json_version(tauri_root / "tauri.conf.json") == version
+        assert (
+            _cargo_lock_root_version(tauri_root / "Cargo.lock", app.cargo_package)
+            == version
+        )
+
+
+@pytest.mark.parametrize(
+    "failed_path",
+    ["src/Undefined/__init__.py", "apps/undefined-chat/package.json"],
+)
+def test_same_version_retry_finishes_all_targets_after_partial_write(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, failed_path: str
+) -> None:
+    _write_bump_project(tmp_path)
+    assert Path.cwd() == tmp_path
+    original_write = bump_version._write_if_changed
+    sync_calls: list[Path] = []
+    monkeypatch.setattr(
+        bump_version,
+        "sync_lock_files",
+        lambda root, *, dry_run: sync_calls.append(root),
+    )
+
+    def fail_write(path: Path, text: str, dry_run: bool) -> bool:
+        assert path.resolve().is_relative_to(tmp_path)
+        if path == tmp_path / failed_path:
+            raise OSError("temporarily unavailable")
+        result: bool = original_write(path, text, dry_run)
+        return result
+
+    monkeypatch.setattr(bump_version, "_write_if_changed", fail_write)
+    with pytest.raises(OSError, match="temporarily unavailable"):
+        bump_version.bump_project_versions(
+            "2.0.0", project_root=tmp_path, dry_run=False
+        )
+    assert bump_version._read_current_version(tmp_path) == "2.0.0"
+    assert not sync_calls
+    monkeypatch.setattr(bump_version, "_write_if_changed", original_write)
+
+    result = bump_version.bump_project_versions(
+        "2.0.0", project_root=tmp_path, dry_run=False
+    )
+
+    assert result.old_version == result.new_version == "2.0.0"
+    assert result.changed_paths
+    assert sync_calls == [tmp_path]
+    _assert_all_versions(tmp_path, "2.0.0")
+
+
+def test_same_version_retry_reruns_all_lock_commands_after_sync_failure(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path)
+    calls: list[tuple[tuple[str, ...], Path]] = []
+    fail_next_npm = True
+    uv_runs = 0
+
+    def run(
+        command: list[str], *, cwd: Path, check: bool
+    ) -> subprocess.CompletedProcess[bytes]:
+        nonlocal fail_next_npm, uv_runs
+        assert cwd.resolve().is_relative_to(tmp_path)
+        assert check
+        calls.append((tuple(command), cwd))
+        if command[0] == "npm" and fail_next_npm:
+            fail_next_npm = False
+            raise subprocess.CalledProcessError(1, command)
+        if command[0] == "uv":
+            uv_runs += 1
+            (cwd / "uv.lock").write_text(f"sync_count={uv_runs}\n", encoding="utf-8")
+        return subprocess.CompletedProcess(command, 0)
+
+    monkeypatch.setattr(bump_version.subprocess, "run", run)
+    with pytest.raises(subprocess.CalledProcessError):
+        bump_version.bump_project_versions(
+            "2.0.0", project_root=tmp_path, dry_run=False
+        )
+    _assert_all_versions(tmp_path, "2.0.0")
+    calls.clear()
+
+    result = bump_version.bump_project_versions(
+        "2.0.0", project_root=tmp_path, dry_run=False
+    )
+
+    assert [command for command, _ in calls] == [
+        ("uv", "sync"),
+        ("npm", "install", "--package-lock-only"),
+        ("cargo", "update", "--workspace"),
+        ("npm", "install", "--package-lock-only"),
+        ("cargo", "update", "--workspace"),
+    ]
+    assert result.changed_paths == ("uv.lock",)
+    _assert_all_versions(tmp_path, "2.0.0")
+
+
+def test_same_version_dry_run_detects_other_target_without_writing_or_syncing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path, version="2.0.0")
+    target = tmp_path / "src" / "Undefined" / "__init__.py"
+    target.write_text('__version__: str = "1.2.3"\n', encoding="utf-8")
+    before = {path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()}
+    monkeypatch.setattr(
+        bump_version,
+        "sync_lock_files",
+        lambda *args, **kwargs: pytest.fail("dry-run must not sync"),
+    )
+
+    result = bump_version.bump_project_versions(
+        "2.0.0", project_root=tmp_path, dry_run=True
+    )
+
+    assert result.changed_paths == ("src/Undefined/__init__.py",)
+    assert {
+        path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()
+    } == before
+
+
+def test_same_version_cli_reports_completed_lock_sync(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    _write_bump_project(tmp_path, version="2.0.0")
+    sync_calls: list[Path] = []
+    monkeypatch.setattr(bump_version, "_PROJECT_ROOT", tmp_path)
+    monkeypatch.setattr(
+        bump_version,
+        "sync_lock_files",
+        lambda root, *, dry_run: sync_calls.append(root),
+    )
+
+    assert bump_version.main(["2.0.0"]) == 0
+
+    assert sync_calls == [tmp_path]
+    output = capsys.readouterr().out
+    assert "lock 文件同步完成" in output
+    assert "无需更新" not in output

From 132852d8edecec923bed80d019c839a80df545f6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:11:00 +0800
Subject: [PATCH 039/121] fix(weixin): flatten nested forward content before
 delivery

---
 docs/wechat-ilink.md                          |   2 +
 .../skills/tools/bilibili_opus/README.md      |   2 +
 src/Undefined/utils/sender.py                 |   7 +
 tests/test_bilibili_opus_sender.py            |  75 +++++-
 tests/test_sender.py                          | 241 ++++++++++++++++++
 5 files changed, 325 insertions(+), 2 deletions(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 14b21e42..74cd2938 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -109,6 +109,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 微信文本中的 `<`、`>`、`&` 等特殊符号和 `<attachment uid="..."/>` 附件标签应原样发送，不使用 HTML/XML 实体。微信没有 QQ 合并转发卡片的等价合同。默认情况下，Undefined 会把当前微信私聊的转发节点展开为保留原顺序的文本与媒体项目，再优先通过一个或多个 iLink `sendmessage.item_list` 请求投递；这是一种实验性多项目消息，不会生成可展开的 QQ 式转发卡片。单次项目数由 `multi_item_max_items` 限制，媒体合计仍受 `media_max_size_mb` 约束。若上游明确拒绝多项目结构，会从当前批次起自动回退为逐段发送；网络超时、会话暂停或服务端错误等结果不确定的失败不会降级重发，以免产生重复消息。设置 `multi_item_messages_enabled=false` 可直接使用逐段模式。包含本地 CQ 图片、文件、视频或音频的消息会走统一附件发送层，媒体本地路径不会作为正文发给用户。
 
+转发节点中的嵌套节点会递归展开，保留每层的发送者标题、正文以及文本和媒体的先后顺序；Bilibili 长正文分段和嵌套卡片也按这一规则发送。逐段模式与多项目模式都会在首个项目发出前校验所有层级的本地媒体，并完成全部语音准备。任一层媒体不存在、超限、使用当前不支持的远程来源或语音准备失败时，整个转发在投递前失败。
+
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
 
 Bot 层通过 `messages.send_voice(uid, address?)` 显式选择“作为语音发送”。普通 `<attachment uid="file_xxx"/>` 始终保留原始文件语义，即使扩展名是 `.wav`；`CQ:record`、`CQ:audio` 和内部明确标记为 voice 的媒体回调则发送原生语音。QQ 侧继续转换为 `CQ:record`，微信侧先用 FFmpeg 归一化为 24 kHz、16-bit、单声道 PCM，再由 `silk-python` 编码为 Tencent SILK。部署机必须能从 `PATH` 找到 `ffmpeg`；缺失、音频无效或超出 `[weixin].media_max_size_mb` 时会在任何消息段发出前失败，不会自动改成文件。
diff --git a/src/Undefined/skills/tools/bilibili_opus/README.md b/src/Undefined/skills/tools/bilibili_opus/README.md
index 9dd8b01a..adec4011 100644
--- a/src/Undefined/skills/tools/bilibili_opus/README.md
+++ b/src/Undefined/skills/tools/bilibili_opus/README.md
@@ -19,6 +19,8 @@
 4. 发送合并转发：第一条是图文信息（封面、标题、UP主、时间、数据、原文链接），第二条是正文（文本与图片按原始顺序混排；单节点上限 1200 字 / 9 张图，超出时切成 `正文 1/N` 并整体收进顶层 `正文` 的嵌套内容，避免顶层卡片预览携带全文而被 QQ 拒收）
 5. 正文里的图文/视频卡片各自成为独立嵌套合并转发，按 `opus_nested_depth` / `opus_nested_max_cards` 递归展开，超界降级为一行文本 + 链接
 
+微信私聊发送时，这些嵌套节点会递归展开成有序文本与本地媒体项目，保留长正文分段、嵌套卡片内容和发送者标题。发送前统一校验所有层级的媒体并准备语音；逐段模式和多项目模式都使用这一流程。微信目前仅支持本地媒体来源，任一媒体准备失败时不会先投递部分正文。
+
 `uid` 模式流程：
 1. 拉取图文并收集正文图片 URL
 2. 按 `max_images` 上限逐张 `register_remote_url`（超过附件大小上限时自动降级为 URL 引用）
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index 6e07869a..2e1feb8c 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -1963,6 +1963,13 @@ def flush_text() -> None:
                 if not isinstance(segment, dict):
                     continue
                 segment_type = str(segment.get("type", "") or "").strip().lower()
+                if segment_type == "node":
+                    nested_units = await self._build_weixin_forward_units([segment])
+                    if nested_units:
+                        flush_text()
+                        node_units.extend(nested_units)
+                        has_content = True
+                    continue
                 if segment_type not in {
                     "text",
                     "image",
diff --git a/tests/test_bilibili_opus_sender.py b/tests/test_bilibili_opus_sender.py
index cede3dbc..d74d7e9f 100644
--- a/tests/test_bilibili_opus_sender.py
+++ b/tests/test_bilibili_opus_sender.py
@@ -1,12 +1,13 @@
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from pathlib import Path
 from types import SimpleNamespace
-from typing import Any
+from typing import Any, cast
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
+from weixin_ilink_client import OutboundMessageItem, OutboundTextItem
 
 import Undefined.bilibili.opus_sender as opus_sender
 from Undefined.bilibili.errors import OpusUnavailableError
@@ -23,6 +24,9 @@
     VideoStats,
 )
 from Undefined.onebot.client import OneBotDeliveryUncertainError
+from Undefined.utils.history import MessageHistoryManager
+from Undefined.utils.message_targets import DeliveryAddress
+from Undefined.utils.sender import AddressBoundSender, MessageSender
 
 
 def _author(name: str = "测试UP") -> OpusAuthor:
@@ -534,6 +538,73 @@ async def test_send_opus_sends_forward_with_history(
     assert call.kwargs["history_message"].startswith("[Bilibili 图文] 「测试图文」")
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multi_item_enabled", [False, True])
+async def test_send_opus_to_wechat_preserves_nested_long_body(
+    monkeypatch: pytest.MonkeyPatch,
+    multi_item_enabled: bool,
+) -> None:
+    body = "A" * NODE_TEXT_BUDGET + "B" * NODE_TEXT_BUDGET + "C" * 80
+    info = _info(TextBlock(body), cover_url="")
+    monkeypatch.setattr(opus_sender, "_fetch_opus_info", AsyncMock(return_value=info))
+    config = _config()
+    config.weixin = SimpleNamespace(
+        multi_item_messages_enabled=multi_item_enabled,
+        multi_item_max_items=2,
+        media_max_size_mb=100,
+    )
+
+    def is_private_allowed(_user_id: int) -> bool:
+        return True
+
+    config.is_private_allowed = is_private_allowed
+    history = SimpleNamespace(add_private_message=AsyncMock())
+    sender = MessageSender(
+        MagicMock(), cast(MessageHistoryManager, history), bot_qq=10000, config=config
+    )
+    delivered: list[str] = []
+
+    async def send_text(_user_id: int, text: str, **_kwargs: Any) -> str:
+        delivered.append(text)
+        return f"client-{len(delivered)}"
+
+    async def send_items(_user_id: int, items: Sequence[OutboundMessageItem]) -> str:
+        for item in items:
+            assert isinstance(item, OutboundTextItem)
+            delivered.append(item.text)
+        return f"client-{len(delivered)}"
+
+    sender.set_weixin_service(
+        SimpleNamespace(send_text=send_text, send_items=send_items)
+    )
+    bound_sender = AddressBoundSender(sender, DeliveryAddress("wechat", 20001))
+
+    result = await opus_sender.send_opus(
+        info.opus_id,
+        sender=cast(MessageSender, bound_sender),
+        target_type="private",
+        target_id=20001,
+        config=config,
+    )
+
+    assert result.startswith("已发送 Bilibili 图文合并转发")
+    assert "图文信息" in delivered[0]
+    joined = "".join(delivered)
+    assert joined.count("A") == NODE_TEXT_BUDGET
+    assert joined.count("B") == NODE_TEXT_BUDGET
+    assert joined.count("C") == 80
+    assert (
+        joined.index("A" * NODE_TEXT_BUDGET)
+        < joined.index("B" * NODE_TEXT_BUDGET)
+        < joined.index("C" * 80)
+    )
+    history.add_private_message.assert_awaited_once()
+    assert (
+        history.add_private_message.await_args.kwargs["transport"]["channel"]
+        == "wechat"
+    )
+
+
 @pytest.mark.asyncio
 async def test_send_opus_propagates_delivery_uncertain(
     monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/test_sender.py b/tests/test_sender.py
index 0d2df237..2e2a311a 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -2,6 +2,8 @@
 
 import logging
 import nturl2path
+from collections.abc import Sequence
+from copy import deepcopy
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, cast
@@ -12,6 +14,7 @@
     ApiError,
     HttpError,
     OutboundMediaItem,
+    OutboundMessageItem,
     OutboundTextItem,
     RefMessage,
     RequestTimeoutError,
@@ -38,6 +41,7 @@
     _local_path_from_segment_source,
 )
 from Undefined.weixin.audio import PreparedWeixinVoice
+from Undefined.weixin.service import WeixinService, WeixinServiceError
 
 
 @pytest.fixture
@@ -1569,6 +1573,243 @@ async def send_file(_user_id: int, path: str | Path, **_kwargs: Any) -> str:
     assert "type=at" in caplog.text
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multi_item_enabled", [False, True])
+async def test_send_wechat_nested_forward_preserves_text_and_media_order(
+    sender: MessageSender,
+    tmp_path: Path,
+    multi_item_enabled: bool,
+) -> None:
+    image_path = tmp_path / "nested.png"
+    voice_path = tmp_path / "nested.wav"
+    video_path = tmp_path / "nested.mp4"
+    for path in (image_path, voice_path, video_path):
+        await async_io.write_bytes(path, path.name.encode())
+    weixin_config = cast(Any, sender.config.weixin)
+    weixin_config.multi_item_messages_enabled = multi_item_enabled
+    weixin_config.multi_item_max_items = 3
+    weixin_config.media_max_size_mb = 100
+    events: list[tuple[str, str]] = []
+    prepared = PreparedWeixinVoice(content=b"silk", duration_ms=200)
+
+    async def validate_media_files(paths: Sequence[str | Path]) -> None:
+        assert list(paths) == [image_path, voice_path, video_path]
+        assert events == []
+        events.append(("prepare", "validate"))
+
+    async def prepare_voice(path: Path) -> PreparedWeixinVoice:
+        assert path == voice_path
+        assert events == [("prepare", "validate")]
+        events.append(("prepare", "voice"))
+        return prepared
+
+    async def send_text(_user_id: int, text: str, **_kwargs: Any) -> str:
+        events.append(("text", text))
+        return f"client-{len(events)}"
+
+    async def send_file(_user_id: int, path: str | Path, **kwargs: Any) -> str:
+        events.append((str(kwargs["kind"]), Path(path).name))
+        return f"client-{len(events)}"
+
+    async def send_prepared_voice(
+        _user_id: int, value: PreparedWeixinVoice, **_kwargs: Any
+    ) -> str:
+        assert value is prepared
+        events.append(("voice", voice_path.name))
+        return f"client-{len(events)}"
+
+    async def send_items(_user_id: int, items: Sequence[OutboundMessageItem]) -> str:
+        for item in items:
+            if isinstance(item, OutboundTextItem):
+                events.append(("text", item.text))
+            else:
+                events.append((str(item.kind), item.file_name))
+        return f"client-{len(events)}"
+
+    service = SimpleNamespace(
+        validate_media_files=validate_media_files,
+        prepare_voice=prepare_voice,
+        send_text=send_text,
+        send_file=send_file,
+        send_prepared_voice=send_prepared_voice,
+        send_items=send_items,
+    )
+    sender.set_weixin_service(service)
+    nodes = [
+        {
+            "type": "node",
+            "data": {
+                "name": "Parent",
+                "content": [
+                    {"type": "text", "data": {"text": "Before"}},
+                    {
+                        "type": "node",
+                        "data": {
+                            "name": "Child",
+                            "content": [
+                                {"type": "text", "data": {"text": "Child-start"}},
+                                {
+                                    "type": "image",
+                                    "data": {"file": image_path.as_uri()},
+                                },
+                                {
+                                    "type": "node",
+                                    "data": {
+                                        "name": "Grandchild",
+                                        "content": [
+                                            {
+                                                "type": "text",
+                                                "data": {"text": "Deep-start"},
+                                            },
+                                            {
+                                                "type": "record",
+                                                "data": {"file": voice_path.as_uri()},
+                                            },
+                                            {
+                                                "type": "video",
+                                                "data": {"file": video_path.as_uri()},
+                                            },
+                                            {
+                                                "type": "node",
+                                                "data": {
+                                                    "name": "Leaf",
+                                                    "content": "Leaf-text",
+                                                },
+                                            },
+                                            {
+                                                "type": "text",
+                                                "data": {"text": "Deep-end"},
+                                            },
+                                        ],
+                                    },
+                                },
+                                {"type": "text", "data": {"text": "Child-end"}},
+                            ],
+                        },
+                    },
+                    {"type": "text", "data": {"text": "After"}},
+                ],
+            },
+        },
+        {"type": "node", "data": {"name": "Last", "content": "Last-text"}},
+    ]
+    original_nodes = deepcopy(nodes)
+
+    await AddressBoundSender(
+        sender, DeliveryAddress("wechat", 12345)
+    ).send_private_forward_message(12345, nodes, history_message="Nested forward")
+
+    assert events == [
+        ("prepare", "validate"),
+        ("prepare", "voice"),
+        ("text", "**Parent**\nBefore"),
+        ("text", "**Child**\nChild-start"),
+        ("image", image_path.name),
+        ("text", "**Grandchild**\nDeep-start"),
+        ("voice", voice_path.name),
+        ("video", video_path.name),
+        ("text", "**Leaf**\nLeaf-text"),
+        ("text", "Deep-end"),
+        ("text", "Child-end"),
+        ("text", "After"),
+        ("text", ("\n" if multi_item_enabled else "") + "---\n**Last**\nLast-text"),
+    ]
+    assert nodes == original_nodes
+    cast(AsyncMock, sender.history_manager.add_private_message).assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multi_item_enabled", [False, True])
+@pytest.mark.parametrize("failure", ["oversized", "missing", "remote", "voice"])
+async def test_send_wechat_nested_forward_preflights_all_media_before_delivery(
+    sender: MessageSender,
+    tmp_path: Path,
+    multi_item_enabled: bool,
+    failure: str,
+) -> None:
+    image_path = tmp_path / "valid.png"
+    invalid_path = tmp_path / "invalid.bin"
+    await async_io.write_bytes(image_path, b"image")
+    if failure != "missing":
+        await async_io.write_bytes(
+            invalid_path,
+            b"x" * (1024 * 1024 + 1) if failure == "oversized" else b"voice",
+        )
+    weixin_config = cast(Any, sender.config.weixin)
+    weixin_config.multi_item_messages_enabled = multi_item_enabled
+    weixin_config.media_max_size_mb = 1
+    validation_service = cast(
+        WeixinService, SimpleNamespace(weixin_config=weixin_config)
+    )
+
+    async def validate_media_files(paths: Sequence[str | Path]) -> None:
+        await WeixinService.validate_media_files(validation_service, paths)
+
+    service = SimpleNamespace(
+        validate_media_files=AsyncMock(side_effect=validate_media_files),
+        prepare_voice=AsyncMock(side_effect=WeixinServiceError("invalid voice")),
+        send_text=AsyncMock(),
+        send_file=AsyncMock(),
+        send_prepared_voice=AsyncMock(),
+        send_items=AsyncMock(),
+    )
+    sender.set_weixin_service(service)
+    invalid_source = (
+        "https://example.com/invalid.bin"
+        if failure == "remote"
+        else invalid_path.as_uri()
+    )
+    nodes = [
+        {
+            "type": "node",
+            "data": {
+                "content": [
+                    {"type": "text", "data": {"text": "Must not be sent"}},
+                    {
+                        "type": "node",
+                        "data": {
+                            "content": [
+                                {
+                                    "type": "image",
+                                    "data": {"file": image_path.as_uri()},
+                                },
+                                {
+                                    "type": "node",
+                                    "data": {
+                                        "content": [
+                                            {
+                                                "type": "record"
+                                                if failure == "voice"
+                                                else "file",
+                                                "data": {"file": invalid_source},
+                                            },
+                                        ]
+                                    },
+                                },
+                            ]
+                        },
+                    },
+                ]
+            },
+        }
+    ]
+
+    with pytest.raises((WeixinServiceError, ValueError)):
+        await AddressBoundSender(
+            sender, DeliveryAddress("wechat", 12345)
+        ).send_private_forward_message(12345, nodes, history_message="Nested forward")
+
+    service.send_text.assert_not_awaited()
+    service.send_file.assert_not_awaited()
+    service.send_prepared_voice.assert_not_awaited()
+    service.send_items.assert_not_awaited()
+    cast(AsyncMock, sender.history_manager.add_private_message).assert_not_awaited()
+    if failure in {"oversized", "voice"}:
+        service.validate_media_files.assert_awaited_once_with(
+            [image_path, invalid_path]
+        )
+
+
 @pytest.mark.asyncio
 async def test_send_wechat_forward_uses_ordered_multi_item_message(
     sender: MessageSender,

From cb48f925333b2ce37ed2a2ecd3df8961c8d0e1c0 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:12:17 +0800
Subject: [PATCH 040/121] docs(scripts): clarify cognitive storage
 configuration paths

---
 docs/cognitive-memory.md     | 2 +-
 scripts/README.md            | 2 +-
 scripts/reembed_cognitive.py | 2 +-
 scripts/restore_profile.py   | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
index d8d772ca..9c161ec9 100644
--- a/docs/cognitive-memory.md
+++ b/docs/cognitive-memory.md
@@ -495,7 +495,7 @@ uv run python scripts/restore_profile.py sync --entity-type user --entity-id {us
 
 `restore` 默认同时恢复 Markdown、保存当前内容的历史快照，并用当前 cognitive 嵌入模型同步 `cognitive_profiles` 中该实体的检索正文和向量，其他实体保持不变。检索正文沿用运行时格式，包含恢复版本中的名称、标签、评价、锐评与正文。模型调用失败时尚未恢复文件；若文件已恢复而向量写入失败，命令会报错，可用 `sync` 从当前文件补同步。文件和向量库之间没有跨存储事务，请保持机器人及其他写入进程停止，直到同步成功。
 
-`--dry-run` 只展示将恢复的内容、检索正文和两个目录，不写盘、不打开 Chroma、不调用模型。目录默认读取 `cognitive.profiles_path` 与 `cognitive.vector_store_path`；操作独立副本时同时指定 `--profiles-path` 和 `--db-path`。实际恢复/同步可能调用嵌入 API 并记录 token 用量；若已更换嵌入模型维度，请先按[更换嵌入模型](#更换嵌入模型)重建整个向量库，再恢复或同步单个侧写。
+`--dry-run` 只展示将恢复的内容、检索正文和两个目录，不写盘、不打开 Chroma、不调用模型。目录默认读取 TOML 配置的 `cognitive.profile.path` 与 `cognitive.vector_store.path`；操作独立副本时同时指定 `--profiles-path` 和 `--db-path`。实际恢复/同步可能调用嵌入 API 并记录 token 用量；若已更换嵌入模型维度，请先按[更换嵌入模型](#更换嵌入模型)重建整个向量库，再恢复或同步单个侧写。
 
 **级别 3：完整移除**
 
diff --git a/scripts/README.md b/scripts/README.md
index aaca81e9..256994bc 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -122,7 +122,7 @@ uv run python scripts/restore_profile.py sync --entity-type user --entity-id 123
 
 `restore` 默认恢复 Markdown、把当前内容另存为历史快照，并使用当前 cognitive 嵌入配置更新 `cognitive_profiles` 中该实体的检索正文与向量。`sync` 只从当前 Markdown 补同步检索，不创建快照。模型请求失败时文件保持原状；向量写入失败时命令报错，已恢复文件保留，可修复错误后重跑 `sync`，无需依赖可能已被清理的旧快照。文件与向量库没有跨存储事务，实际恢复/同步前需停止机器人和其他写入进程，成功后再启动。
 
-`--dry-run` 展示文件内容、检索正文与路径，不打开 Chroma、不调用模型、不写盘。目录默认来自 `cognitive.profiles_path` 与 `cognitive.vector_store_path`；操作独立副本时同时传入 `--profiles-path` 和 `--db-path`。实际恢复/同步会调用嵌入 API，可能记录 token 用量。若新模型维度不同于现有库，先完成全库重嵌入再恢复/同步单个侧写。
+`--dry-run` 展示文件内容、检索正文与路径，不打开 Chroma、不调用模型、不写盘。目录默认来自 TOML 配置的 `cognitive.profile.path` 与 `cognitive.vector_store.path`；操作独立副本时同时传入 `--profiles-path` 和 `--db-path`。实际恢复/同步会调用嵌入 API，可能记录 token 用量。若新模型维度不同于现有库，先完成全库重嵌入再恢复/同步单个侧写。
 
 ### release_notes.py — 发布版本校验与 Release notes 生成
 
diff --git a/scripts/reembed_cognitive.py b/scripts/reembed_cognitive.py
index 48ea62f9..2e6de6d4 100755
--- a/scripts/reembed_cognitive.py
+++ b/scripts/reembed_cognitive.py
@@ -106,7 +106,7 @@ def _parse_args() -> argparse.Namespace:
         "--db-path",
         type=str,
         default=None,
-        help="ChromaDB 路径（默认读取 config.toml 中的 cognitive.vector_store_path）",
+        help="ChromaDB 路径（默认读取 config.toml 中的 cognitive.vector_store.path）",
     )
     parser.add_argument(
         "-v",
diff --git a/scripts/restore_profile.py b/scripts/restore_profile.py
index b577b1c7..164641ff 100644
--- a/scripts/restore_profile.py
+++ b/scripts/restore_profile.py
@@ -64,7 +64,7 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--db-path",
         default="",
-        help="ChromaDB 目录（默认读取 config.toml 中的 cognitive.vector_store_path）",
+        help="ChromaDB 目录（默认读取 config.toml 中的 cognitive.vector_store.path）",
     )
     parser.add_argument(
         "--entity-type",
@@ -81,7 +81,7 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--profiles-path",
         default="",
-        help="侧写目录（默认读取 config.toml 中的 cognitive.profiles_path）",
+        help="侧写目录（默认读取 config.toml 中的 cognitive.profile.path）",
     )
     parser.add_argument(
         "--dry-run",

From 2530c2ca1879bb34d1949df5e183ff76f88c1d6b Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:15:44 +0800
Subject: [PATCH 041/121] fix(cognitive): validate profile paths inside file IO
 threads

---
 docs/python-api.md                         |  2 +-
 src/Undefined/cognitive/profile_storage.py | 13 +++---
 tests/test_cognitive_profile_paths.py      | 52 ++++++++++++++++++++++
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/docs/python-api.md b/docs/python-api.md
index c86360bf..950892df 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -297,7 +297,7 @@ server = RuntimeAPIServer(RuntimeAPIContext(...))
 | `Undefined.api` | stable | `RuntimeAPIServer`, `RuntimeAPIContext` |
 | `Undefined.mcp` | subpackage | `MCPToolRegistry`, `MCPToolSetRegistry` |
 
-`ProfileStorage` 的所有读写、历史版本和合并锁操作只接受 `user` / `group` 实体类型，以及非空的单层实体 ID（不接受路径分隔符、`.` / `..` 或 Windows 盘符）。侧写文件与历史版本解析符号链接后必须仍位于 `base_path` 内，否则抛出 `ValueError`；Runtime 的侧写查询接口将这类错误转换为 HTTP 400。
+`ProfileStorage` 的所有读写、历史版本和合并锁操作只接受 `user` / `group` 实体类型，以及非空的单层实体 ID（不接受路径分隔符、`.` / `..` 或 Windows 盘符）。侧写文件与历史版本解析符号链接后必须仍位于 `base_path` 内，否则抛出 `ValueError`；路径解析与文件访问一起在线程中执行，避免阻塞事件循环。Runtime 的侧写查询接口将这类错误转换为 HTTP 400。
 
 ---
 
diff --git a/src/Undefined/cognitive/profile_storage.py b/src/Undefined/cognitive/profile_storage.py
index e8798642..a064e835 100644
--- a/src/Undefined/cognitive/profile_storage.py
+++ b/src/Undefined/cognitive/profile_storage.py
@@ -76,12 +76,12 @@ def _contained_path(self, path: Path) -> Path:
         return path
 
     async def read_profile(self, entity_type: str, entity_id: str) -> str | None:
-        p = self._profile_path(entity_type, entity_id)
         logger.info(
             "[认知侧写] 读取侧写: entity_type=%s entity_id=%s", entity_type, entity_id
         )
 
         def _read() -> str | None:
+            p = self._profile_path(entity_type, entity_id)
             if not p.exists():
                 return None
             return p.read_text(encoding="utf-8")
@@ -106,10 +106,10 @@ async def write_profile(
             len(content or ""),
         )
         async with self._get_lock(entity_type, entity_id):
-            p = self._profile_path(entity_type, entity_id)
-            hist_dir = self._history_dir(entity_type, entity_id)
 
             def _write() -> None:
+                p = self._profile_path(entity_type, entity_id)
+                hist_dir = self._history_dir(entity_type, entity_id)
                 p.parent.mkdir(parents=True, exist_ok=True)
                 hist_dir.mkdir(parents=True, exist_ok=True)
 
@@ -156,9 +156,8 @@ def _write() -> None:
         )
 
     async def list_revisions(self, entity_type: str, entity_id: str) -> list[str]:
-        hist_dir = self._history_dir(entity_type, entity_id)
-
         def _list() -> list[str]:
+            hist_dir = self._history_dir(entity_type, entity_id)
             if not hist_dir.exists():
                 return []
             return sorted(f.name for f in hist_dir.glob("*.md"))
@@ -193,9 +192,11 @@ async def read_revision(
     ) -> str | None:
         """读取指定历史版本内容；版本名取 `list_revisions` 的返回值。"""
         name = self._normalize_revision_name(revision)
-        path = self._contained_path(self._history_dir(entity_type, entity_id) / name)
 
         def _read() -> str | None:
+            path = self._contained_path(
+                self._history_dir(entity_type, entity_id) / name
+            )
             if not path.exists():
                 return None
             return path.read_text(encoding="utf-8")
diff --git a/tests/test_cognitive_profile_paths.py b/tests/test_cognitive_profile_paths.py
index 6daf45d8..a9bb14fc 100644
--- a/tests/test_cognitive_profile_paths.py
+++ b/tests/test_cognitive_profile_paths.py
@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import asyncio
 import json
+import threading
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any
@@ -14,6 +16,56 @@
 from Undefined.skills.toolsets.cognitive.get_profile.handler import execute
 
 
+@pytest.mark.asyncio
+async def test_profile_paths_are_validated_in_file_io_threads(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    storage = ProfileStorage(tmp_path)
+    event_loop_thread = threading.get_ident()
+    checked_threads: list[int] = []
+    original = storage._contained_path
+
+    def check_path(path: Path) -> Path:
+        checked_threads.append(threading.get_ident())
+        return original(path)
+
+    monkeypatch.setattr(storage, "_contained_path", check_path)
+    await storage.write_profile("user", "10001", "v1")
+    await storage.write_profile("user", "10001", "v2")
+    assert await storage.read_profile("user", "10001") == "v2"
+    revisions = await storage.list_revisions("user", "10001")
+    assert await storage.read_revision("user", "10001", revisions[0]) == "v1"
+    await storage.restore_revision("user", "10001", revisions[0])
+    assert checked_threads
+    assert event_loop_thread not in checked_threads
+
+
+@pytest.mark.asyncio
+async def test_profile_read_checks_links_after_dispatching_file_io(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    base = tmp_path / "profiles"
+    users = base / "users"
+    users.mkdir(parents=True)
+    (users / "10001.md").write_text("safe", encoding="utf-8")
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    (outside / "10001.md").write_text("private", encoding="utf-8")
+    storage = ProfileStorage(base)
+    original = asyncio.to_thread
+
+    async def dispatch_after_link_change(
+        func: Any, /, *args: Any, **kwargs: Any
+    ) -> Any:
+        users.rename(base / "original-users")
+        users.symlink_to(outside, target_is_directory=True)
+        return await original(func, *args, **kwargs)
+
+    monkeypatch.setattr(asyncio, "to_thread", dispatch_after_link_change)
+    with pytest.raises(ValueError, match="超出存储目录"):
+        await storage.read_profile("user", "10001")
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     ("entity_type", "entity_id"),

From 4e3b173ea45c9197ed515780abbf22f912d2b955 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:18:56 +0800
Subject: [PATCH 042/121] fix(scripts): commit all managed version targets on
 retry

---
 scripts/README.md                 |   2 +-
 scripts/bump_version.py           |  68 ++++++++++++----
 tests/test_bump_version_script.py | 127 ++++++++++++++++++++++++++++++
 3 files changed, 179 insertions(+), 18 deletions(-)

diff --git a/scripts/README.md b/scripts/README.md
index 256994bc..a5e4d742 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -179,7 +179,7 @@ uv run python scripts/bump_version.py 3.6.0 --commit
 - `apps/undefined-chat/src-tauri/Cargo.lock`
 
 非 dry-run 时脚本还会执行 `uv sync`，并分别在 Console / Chat 下执行 `npm install --package-lock-only` 与 `cargo update --workspace`，保证 lock 文件和 manifest 不漂移。
-每次运行都会逐一核对所有版本文件，即使 `pyproject.toml` 已是目标版本也会补齐其余目标；非 dry-run 时仍完整执行锁文件同步。若写文件或同步依赖中途失败，修复原因后重跑同一个版本即可继续，不会因主版本已更新而跳过。锁同步实际修改的 `uv.lock`、`package-lock.json` 和 `Cargo.lock` 也会列入变更清单，`--commit` 会包含这些文件。`--dry-run` 只预览版本文件差异，不写盘或执行依赖同步。
+每次运行都会逐一核对所有版本文件，即使 `pyproject.toml` 已是目标版本也会补齐其余目标；非 dry-run 时仍完整执行锁文件同步。若写文件或同步依赖中途失败，修复原因后重跑同一个版本即可继续，不会因主版本已更新而跳过。锁同步实际修改的 `uv.lock`、`package-lock.json` 和 `Cargo.lock` 也会列入本次变更清单。`--commit` 会核对并暂存上述完整的版本管理目标与 `uv.lock`，包括上次失败前已写入的目标，即使本次没有文件写入差异也会检查；只有这些目标存在待提交差异时才创建提交，已暂存的无关文件保持暂存状态，不纳入版本提交。`--dry-run` 只预览版本文件差异，不写盘、执行依赖同步或运行 Git。
 脚本更新 JSON manifest 时只替换顶层 `version` 字段，保留现有格式，避免 Tauri 配置与 Biome 格式化规则漂移。
 
 ### prepare_tauri_android.py — 生成后 Android 修补
diff --git a/scripts/bump_version.py b/scripts/bump_version.py
index 421ad6db..018c5b67 100644
--- a/scripts/bump_version.py
+++ b/scripts/bump_version.py
@@ -303,6 +303,46 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _commit_version_files(project_root: Path, version: str) -> bool:
+    """提交全部受管理目标的差异，包括上次失败前已写入的文件。"""
+    paths = ["pyproject.toml", "src/Undefined/__init__.py", "uv.lock"]
+    for app in NATIVE_APPS:
+        paths.extend(
+            [
+                app.package_json,
+                app.package_lock,
+                app.cargo_toml,
+                app.tauri_conf,
+                app.cargo_lock,
+            ]
+        )
+    subprocess.run(["git", "add", "--", *paths], cwd=project_root, check=True)
+    diff = subprocess.run(
+        ["git", "diff", "--cached", "--quiet", "--", *paths],
+        cwd=project_root,
+        check=False,
+    )
+    if diff.returncode == 0:
+        return False
+    if diff.returncode != 1:
+        raise subprocess.CalledProcessError(diff.returncode, diff.args)
+    # 明确限定提交范围，保留用户已暂存的其他文件。
+    subprocess.run(
+        [
+            "git",
+            "commit",
+            "--only",
+            "-m",
+            f"chore(version): bump version to {version}",
+            "--",
+            *paths,
+        ],
+        cwd=project_root,
+        check=True,
+    )
+    return True
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv)
@@ -325,26 +365,20 @@ def main(argv: list[str] | None = None) -> int:
             print(f"版本文件已经是 {result.old_version}；实际执行时仍会同步 lock 文件")
         else:
             print(f"版本文件已经是 {result.old_version}，lock 文件同步完成")
-        return 0
-
-    prefix = "(dry-run) " if dry_run else ""
-    print(f"{prefix}版本 {result.old_version} → {result.new_version}\n")
-    for path in result.changed_paths:
-        print(f"  ✓ {path}")
+        if not should_commit or dry_run:
+            return 0
+    else:
+        prefix = "(dry-run) " if dry_run else ""
+        print(f"{prefix}版本 {result.old_version} → {result.new_version}\n")
+        for path in result.changed_paths:
+            print(f"  ✓ {path}")
 
     if should_commit and not dry_run:
         print("\n创建 git commit...")
-        subprocess.run(
-            ["git", "add", *result.changed_paths, "uv.lock"],
-            cwd=_PROJECT_ROOT,
-            check=True,
-        )
-        subprocess.run(
-            ["git", "commit", "-m", f"chore(version): bump version to {new_version}"],
-            cwd=_PROJECT_ROOT,
-            check=True,
-        )
-        print(f"\n完成! 已提交版本 {new_version}")
+        if _commit_version_files(_PROJECT_ROOT, new_version):
+            print(f"\n完成! 已提交版本 {new_version}")
+        else:
+            print(f"\n版本 {new_version} 的受管理文件没有待提交差异")
     elif not dry_run:
         print(f"\n完成! 版本已更新为 {new_version}")
         print("提示: 使用 --commit 可自动提交，或手动 git add + commit")
diff --git a/tests/test_bump_version_script.py b/tests/test_bump_version_script.py
index 26f8ff3c..e502b887 100644
--- a/tests/test_bump_version_script.py
+++ b/tests/test_bump_version_script.py
@@ -390,3 +390,130 @@ def test_same_version_cli_reports_completed_lock_sync(
     output = capsys.readouterr().out
     assert "lock 文件同步完成" in output
     assert "无需更新" not in output
+
+
+def _record_git(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    staged_difference: bool,
+) -> list[list[str]]:
+    calls: list[list[str]] = []
+
+    def run(
+        command: list[str], *, cwd: Path, check: bool
+    ) -> subprocess.CompletedProcess[bytes]:
+        assert cwd == tmp_path
+        assert command[0] == "git"
+        calls.append(command)
+        code = int(staged_difference) if command[1] == "diff" else 0
+        return subprocess.CompletedProcess(command, code)
+
+    monkeypatch.setattr(bump_version.subprocess, "run", run)
+    return calls
+
+
+def _assert_complete_git_scope(calls: list[list[str]]) -> None:
+    expected = {"pyproject.toml", "src/Undefined/__init__.py", "uv.lock"}
+    for app in bump_version.NATIVE_APPS:
+        expected.update(
+            [
+                app.package_json,
+                app.package_lock,
+                app.cargo_toml,
+                app.tauri_conf,
+                app.cargo_lock,
+            ]
+        )
+    assert [command[1] for command in calls] == ["add", "diff", "commit"]
+    for command in calls:
+        assert set(command[command.index("--") + 1 :]) == expected
+    assert "--cached" in calls[1] and "--quiet" in calls[1]
+    assert "--only" in calls[2]
+
+
+def test_main_partial_failure_retry_commits_prior_pyproject_write(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path)
+    monkeypatch.setattr(bump_version, "_PROJECT_ROOT", tmp_path)
+    monkeypatch.setattr(bump_version, "sync_lock_files", lambda *args, **kwargs: None)
+    calls = _record_git(tmp_path, monkeypatch, staged_difference=True)
+    original_write = bump_version._write_if_changed
+
+    def fail_init(path: Path, text: str, dry_run: bool) -> bool:
+        assert path.resolve().is_relative_to(tmp_path)
+        if path.name == "__init__.py":
+            raise OSError("controlled write failure")
+        result: bool = original_write(path, text, dry_run)
+        return result
+
+    monkeypatch.setattr(bump_version, "_write_if_changed", fail_init)
+    assert bump_version.main(["2.0.0", "--commit"]) == 1
+    assert bump_version._read_current_version(tmp_path) == "2.0.0"
+    assert not calls
+    monkeypatch.setattr(bump_version, "_write_if_changed", original_write)
+
+    assert bump_version.main(["2.0.0", "--commit"]) == 0
+
+    _assert_all_versions(tmp_path, "2.0.0")
+    _assert_complete_git_scope(calls)
+
+
+def test_main_lock_failure_retry_commits_when_this_run_changes_no_files(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path)
+    monkeypatch.setattr(bump_version, "_PROJECT_ROOT", tmp_path)
+    calls = _record_git(tmp_path, monkeypatch, staged_difference=True)
+    sync_count = 0
+
+    def sync(root: Path, *, dry_run: bool) -> None:
+        nonlocal sync_count
+        assert root == tmp_path and not dry_run
+        sync_count += 1
+        if sync_count == 1:
+            raise subprocess.CalledProcessError(
+                1, ["npm", "install", "--package-lock-only"]
+            )
+
+    monkeypatch.setattr(bump_version, "sync_lock_files", sync)
+    assert bump_version.main(["2.0.0", "--commit"]) == 1
+    _assert_all_versions(tmp_path, "2.0.0")
+    before = {path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()}
+    assert not calls
+
+    assert bump_version.main(["2.0.0", "--commit"]) == 0
+
+    assert {
+        path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()
+    } == before
+    assert sync_count == 2
+    _assert_complete_git_scope(calls)
+
+
+def test_main_commit_skips_creation_without_managed_git_differences(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path, version="2.0.0")
+    monkeypatch.setattr(bump_version, "_PROJECT_ROOT", tmp_path)
+    monkeypatch.setattr(bump_version, "sync_lock_files", lambda *args, **kwargs: None)
+    calls = _record_git(tmp_path, monkeypatch, staged_difference=False)
+
+    assert bump_version.main(["2.0.0", "--commit"]) == 0
+
+    assert [command[1] for command in calls] == ["add", "diff"]
+
+
+def test_main_dry_run_commit_never_calls_git_or_lock_sync(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _write_bump_project(tmp_path)
+    monkeypatch.setattr(bump_version, "_PROJECT_ROOT", tmp_path)
+    monkeypatch.setattr(
+        bump_version, "sync_lock_files", lambda *args, **kwargs: pytest.fail("dry-run")
+    )
+
+    # autouse fixture also forbids every actual subprocess.
+    assert bump_version.main(["2.0.0", "--commit", "--dry-run"]) == 0
+    _assert_all_versions(tmp_path, "1.2.3")

From 842fd05a31bdcefababb29a17c526137f929e675 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:21:20 +0800
Subject: [PATCH 043/121] fix(chat): suspend requests and recover failed
 connection changes

---
 apps/undefined-chat/src/App.test.tsx          | 155 ++++++++++++++++--
 apps/undefined-chat/src/App.tsx               |  83 +++++++++-
 .../chat-store/connection-recovery.test.ts    |  60 +++++++
 apps/undefined-chat/src/chat-store/store.ts   |  47 +++++-
 .../src/connection-recovery.test.tsx          | 108 ++++++++++++
 apps/undefined-chat/src/i18n/index.ts         |  10 ++
 .../src/runtime-client/tauri.test.ts          |  17 ++
 .../src/runtime-client/tauri.ts               |  15 +-
 .../src/runtime-client/types.ts               |   1 +
 apps/undefined-chat/src/test-fixtures.ts      |   1 +
 .../tests/e2e/connection-setup.test.tsx       |  21 ++-
 docs/undefined-chat.md                        |   2 +
 12 files changed, 485 insertions(+), 35 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/connection-recovery.test.ts
 create mode 100644 apps/undefined-chat/src/connection-recovery.test.tsx

diff --git a/apps/undefined-chat/src/App.test.tsx b/apps/undefined-chat/src/App.test.tsx
index 1758373f..799a9ffd 100644
--- a/apps/undefined-chat/src/App.test.tsx
+++ b/apps/undefined-chat/src/App.test.tsx
@@ -165,12 +165,14 @@ describe("App", () => {
 	test("saves initial Runtime config and API key before reconnecting", async () => {
 		const client = runtimeClientStub({
 			getRuntimeConfig: vi
-				.fn()
+				.fn(
+					async (): Promise<RuntimeConfig | null> => ({
+						runtimeUrl: "http://127.0.0.1:8788",
+						hasApiKey: true,
+					}),
+				)
 				.mockResolvedValueOnce(null)
-				.mockResolvedValueOnce({
-					runtimeUrl: "http://127.0.0.1:8788",
-					hasApiKey: true,
-				}),
+				.mockResolvedValueOnce(null),
 		});
 		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
 
@@ -195,12 +197,14 @@ describe("App", () => {
 	test("requires an explicit opt-in before confirming insecure API key storage fallback", async () => {
 		const client = runtimeClientStub({
 			getRuntimeConfig: vi
-				.fn()
+				.fn(
+					async (): Promise<RuntimeConfig | null> => ({
+						runtimeUrl: "http://127.0.0.1:8788",
+						hasApiKey: true,
+					}),
+				)
 				.mockResolvedValueOnce(null)
-				.mockResolvedValueOnce({
-					runtimeUrl: "http://127.0.0.1:8788",
-					hasApiKey: true,
-				}),
+				.mockResolvedValueOnce(null),
 		});
 		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
 
@@ -232,6 +236,137 @@ describe("App", () => {
 		expect(await screen.findByRole("button", { name: /新会话/ })).toBeTruthy();
 	});
 
+	test("restores the previous Native target and blocks sending after key storage fails", async () => {
+		let nativeConfig: RuntimeConfig = {
+			runtimeUrl: "http://runtime-a.test",
+			hasApiKey: true,
+		};
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => nativeConfig),
+			saveRuntimeConfig: vi.fn(async (runtimeUrl) => {
+				nativeConfig = { ...nativeConfig, runtimeUrl };
+				return nativeConfig;
+			}),
+			saveApiKey: vi.fn(async () => {
+				throw new Error("keyring denied");
+			}),
+		});
+		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+		renderApp();
+		await screen.findByLabelText("消息输入");
+		await userEvent.type(screen.getByLabelText("消息输入"), "A draft");
+		fireEvent.keyDown(window, { key: ",", ctrlKey: true });
+		await userEvent.type(screen.getByLabelText("API Key"), "B-key");
+		await userEvent.clear(screen.getByLabelText("Runtime URL"));
+		await userEvent.type(
+			screen.getByLabelText("Runtime URL"),
+			"http://runtime-b.test",
+		);
+		await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+		await screen.findByText(/keyring denied/);
+		expect(nativeConfig.runtimeUrl).toBe("http://runtime-a.test");
+		expect(client.saveRuntimeConfig).toHaveBeenLastCalledWith(
+			"http://runtime-a.test",
+		);
+		expect(screen.getByLabelText("Runtime URL")).toHaveValue(
+			"http://runtime-a.test",
+		);
+		expect(screen.getByLabelText("消息输入")).toHaveValue("A draft");
+		expect(screen.getByLabelText("消息输入")).toBeDisabled();
+		fireEvent.keyDown(window, { key: "Escape" });
+		expect(screen.getByLabelText("Runtime URL")).toBeInTheDocument();
+		expect(client.sendMessage).not.toHaveBeenCalled();
+		expect(client.listConversations).toHaveBeenCalledTimes(1);
+		// 恢复界面不能留空沿用未知状态的密钥；明确重新保存后才解除暂停。
+		await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+		expect(await screen.findByText("请输入 API Key")).toBeInTheDocument();
+		client.saveApiKey = vi.fn(async () => client.loadApiKeyStatus());
+		await userEvent.type(screen.getByLabelText("API Key"), "A-key");
+		await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+		await waitFor(() => {
+			expect(screen.queryByLabelText("Runtime URL")).toBeNull();
+			expect(screen.getByLabelText("消息输入")).toBeEnabled();
+		});
+		expect(screen.getByLabelText("消息输入")).toHaveValue("A draft");
+		await userEvent.click(screen.getByRole("button", { name: "发送" }));
+		expect(client.sendMessage).toHaveBeenCalledWith({
+			conversationId: "default",
+			message: { text: "A draft", attachmentIds: [], references: [] },
+		});
+	});
+
+	test("clears a first configuration after key storage fails", async () => {
+		let nativeConfig: RuntimeConfig | null = null;
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => nativeConfig),
+			saveRuntimeConfig: vi.fn(async (runtimeUrl) => {
+				nativeConfig = { runtimeUrl, hasApiKey: false };
+				return nativeConfig;
+			}),
+			clearRuntimeConfig: vi.fn(async () => {
+				nativeConfig = null;
+			}),
+			saveApiKey: vi.fn(async () => {
+				throw new Error("keyring denied");
+			}),
+		});
+		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+		renderApp();
+		await screen.findByLabelText("Runtime URL");
+		await userEvent.type(screen.getByLabelText("API Key"), "B-key");
+		await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+		await screen.findByText(/keyring denied/);
+		expect(nativeConfig).toBeNull();
+		expect(client.clearRuntimeConfig).toHaveBeenCalledOnce();
+		expect(client.listConversations).not.toHaveBeenCalled();
+		expect(screen.getByLabelText("消息输入")).toBeDisabled();
+	});
+
+	test("shows the actual Native target and requires recovery if URL rollback fails", async () => {
+		let nativeConfig: RuntimeConfig = {
+			runtimeUrl: "http://runtime-a.test",
+			hasApiKey: true,
+		};
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => nativeConfig),
+			saveRuntimeConfig: vi.fn(async (runtimeUrl) => {
+				if (runtimeUrl === "http://runtime-a.test") {
+					throw new Error("restore denied");
+				}
+				nativeConfig = { ...nativeConfig, runtimeUrl };
+				return nativeConfig;
+			}),
+			saveApiKey: vi.fn(async () => {
+				// 模拟底层已经更新密钥但回执失败；客户端不得推断旧密钥仍安全。
+				nativeConfig = { ...nativeConfig, hasApiKey: true };
+				throw new Error("key write receipt failed");
+			}),
+		});
+		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+		renderApp();
+		await screen.findByLabelText("消息输入");
+		await userEvent.type(screen.getByLabelText("消息输入"), "private A draft");
+		fireEvent.keyDown(window, { key: ",", ctrlKey: true });
+		await userEvent.type(screen.getByLabelText("API Key"), "B-key");
+		await userEvent.clear(screen.getByLabelText("Runtime URL"));
+		await userEvent.type(
+			screen.getByLabelText("Runtime URL"),
+			"http://runtime-b.test",
+		);
+		await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+		await screen.findByText(/restore denied/);
+		expect(nativeConfig.runtimeUrl).toBe("http://runtime-b.test");
+		expect(screen.getByLabelText("Runtime URL")).toHaveValue(
+			"http://runtime-b.test",
+		);
+		expect(screen.getByLabelText("消息输入")).toHaveValue("");
+		expect(screen.getByLabelText("消息输入")).toBeDisabled();
+		fireEvent.keyDown(window, { key: "Escape" });
+		expect(screen.getByLabelText("API Key")).toBeInTheDocument();
+		expect(client.sendMessage).not.toHaveBeenCalled();
+		expect(client.listConversations).toHaveBeenCalledTimes(1);
+	});
+
 	test("opens and closes the mobile conversation drawer with accessible state", async () => {
 		const originalInnerWidth = window.innerWidth;
 		Object.defineProperty(window, "innerWidth", {
diff --git a/apps/undefined-chat/src/App.tsx b/apps/undefined-chat/src/App.tsx
index 375b3e42..20a120f2 100644
--- a/apps/undefined-chat/src/App.tsx
+++ b/apps/undefined-chat/src/App.tsx
@@ -29,7 +29,7 @@ import {
 } from "./platform/PlatformContext";
 import { AttachmentImageProvider } from "./rendering/AttachmentImageContext";
 import { createTauriRuntimeClient } from "./runtime-client/tauri";
-import type { Attachment } from "./runtime-client/types";
+import type { Attachment, RuntimeConfig } from "./runtime-client/types";
 import { useTheme } from "./theme/use-theme";
 import { isImageAttachment } from "./utils/attachment";
 
@@ -89,6 +89,11 @@ export function App() {
 		: null;
 
 	const [setupError, setSetupError] = useState<string | null>(null);
+	const [isConnecting, setIsConnecting] = useState(false);
+	const [connectionRecoveryGeneration, setConnectionRecoveryGeneration] =
+		useState(0);
+	const connectionRecoveryRequired = connectionRecoveryGeneration > 0;
+	const connectionUpdateInFlightRef = useRef(false);
 
 	const needsSetup =
 		!state.runtimeConfig?.runtimeUrl || !state.runtimeConfig.hasApiKey;
@@ -127,9 +132,18 @@ export function App() {
 		apiKey: string,
 		allowInsecure: boolean,
 	): Promise<void> {
+		if (connectionUpdateInFlightRef.current) return;
+		connectionUpdateInFlightRef.current = true;
+		setIsConnecting(true);
 		setSetupError(null);
+		let previousConfig: RuntimeConfig | null = null;
+		let savedConfig: RuntimeConfig | null = null;
+		let writeStarted = false;
 		try {
-			const config = await client.saveRuntimeConfig(url);
+			previousConfig = await client.getRuntimeConfig();
+			store.suspendRuntime();
+			writeStarted = true;
+			savedConfig = await client.saveRuntimeConfig(url);
 			if (allowInsecure) {
 				await client.confirmInsecureStorageFallback();
 			}
@@ -137,10 +151,50 @@ export function App() {
 			if (apiKey) {
 				await client.saveApiKey(apiKey);
 			}
+			await store.bootstrap({
+				runtimeUrl: savedConfig.runtimeUrl,
+				resumeSuspended: true,
+			});
+			if (store.getSnapshot().error) {
+				setSetupError(store.getSnapshot().error);
+				store.suspendRuntime(savedConfig);
+				setConnectionRecoveryGeneration((generation) => generation + 1);
+				return;
+			}
+			setConnectionRecoveryGeneration(0);
 			setIsSettingsOpen(false);
-			await store.bootstrap({ runtimeUrl: config.runtimeUrl });
 		} catch (err) {
-			setSetupError(err instanceof Error ? err.message : String(err));
+			let detail = err instanceof Error ? err.message : String(err);
+			if (writeStarted) {
+				try {
+					if (previousConfig) {
+						await client.saveRuntimeConfig(previousConfig.runtimeUrl);
+					} else {
+						await client.clearRuntimeConfig();
+					}
+				} catch (rollbackError) {
+					detail = t("setup.error.rollbackFailed", {
+						error: detail,
+						rollbackError:
+							rollbackError instanceof Error
+								? rollbackError.message
+								: String(rollbackError),
+					});
+				}
+				let actualConfig = savedConfig ?? previousConfig;
+				try {
+					actualConfig = await client.getRuntimeConfig();
+				} catch {
+					// 无法读取时保留最后一次成功保存的目标，仍禁止 Runtime 请求。
+				}
+				store.suspendRuntime(actualConfig);
+				setConnectionRecoveryGeneration((generation) => generation + 1);
+				detail = t("setup.error.reconfigure", { error: detail });
+			}
+			setSetupError(detail);
+		} finally {
+			connectionUpdateInFlightRef.current = false;
+			setIsConnecting(false);
 		}
 	}
 
@@ -231,7 +285,7 @@ export function App() {
 		});
 	}
 
-	const showModal = needsSetup || isSettingsOpen;
+	const showModal = needsSetup || isSettingsOpen || connectionRecoveryRequired;
 
 	const closeMobileSidebar = useCallback((): void => {
 		setIsMobileSidebarActive(false);
@@ -607,13 +661,20 @@ export function App() {
 						{/* 模态框 / 配置面板：统一 ConnectionSetup（首次连接 / 运行期修改两种模式） */}
 						{showModal ? (
 							<ConnectionSetup
-								mode={needsSetup ? "setup" : "settings"}
+								key={connectionRecoveryGeneration}
+								mode={
+									needsSetup || connectionRecoveryRequired
+										? "setup"
+										: "settings"
+								}
 								currentUrl={state.runtimeConfig?.runtimeUrl}
 								onConnect={(url, apiKey, allowInsecure) => {
 									void handleConnect(url, apiKey, allowInsecure);
 								}}
 								onClose={
-									needsSetup ? undefined : () => setIsSettingsOpen(false)
+									needsSetup || isConnecting || connectionRecoveryRequired
+										? undefined
+										: () => setIsSettingsOpen(false)
 								}
 								error={setupError}
 							>
@@ -699,7 +760,13 @@ export function App() {
 									: []
 							}
 							commandSuggestions={state.commands}
-							disabled={isJobRunning(activeJob)}
+							disabled={
+								isJobRunning(activeJob) ||
+								isConnecting ||
+								connectionRecoveryRequired ||
+								state.bootstrapping ||
+								state.connectionState === "disconnected"
+							}
 							draft={
 								selectedConversationId
 									? (state.draftsByConversation[selectedConversationId] ?? "")
diff --git a/apps/undefined-chat/src/chat-store/connection-recovery.test.ts b/apps/undefined-chat/src/chat-store/connection-recovery.test.ts
new file mode 100644
index 00000000..97fa5732
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/connection-recovery.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, test, vi } from "vitest";
+import type { RuntimeConfig } from "../runtime-client/types";
+import { runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+describe("connection configuration suspension", () => {
+	test("blocks Runtime operations and lifecycle bootstrap until explicit connection recovery", async () => {
+		let runtimeConfig: RuntimeConfig = {
+			runtimeUrl: "http://runtime-a.test",
+			hasApiKey: true,
+		};
+		const client = runtimeClientStub({
+			getRuntimeConfig: vi.fn(async () => runtimeConfig),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "A draft");
+		store.suspendRuntime();
+		await Promise.all([
+			store.sendSelectedMessage(),
+			store.createConversation(),
+			store.deleteConversation("default"),
+			store.renameConversation("default", "unsafe rename"),
+			store.selectConversation("default"),
+			store.addAttachmentPath("default", "/mock/a.txt"),
+			store.reloadHistory("default"),
+			store.loadMoreHistory("default"),
+			store.cancelJob("job-1"),
+			store.refreshCommandsIfStale(),
+			store.bootstrap({ resuming: true }),
+		]);
+		expect(client.sendMessage).not.toHaveBeenCalled();
+		expect(client.createConversation).not.toHaveBeenCalled();
+		expect(client.deleteConversation).not.toHaveBeenCalled();
+		expect(client.renameConversation).not.toHaveBeenCalled();
+		expect(client.uploadAttachment).not.toHaveBeenCalled();
+		expect(client.cancelJob).not.toHaveBeenCalled();
+		expect(client.getHistory).toHaveBeenCalledTimes(1);
+		expect(client.listCommands).toHaveBeenCalledTimes(1);
+		expect(client.getRuntimeConfig).toHaveBeenCalledTimes(1);
+		expect(store.getSnapshot().draftsByConversation.default).toBe("A draft");
+		await store.bootstrap({ resumeSuspended: true });
+		await store.sendSelectedMessage();
+		expect(client.sendMessage).toHaveBeenCalledWith({
+			conversationId: "default",
+			message: { text: "A draft", attachmentIds: [], references: [] },
+		});
+		runtimeConfig = { ...runtimeConfig, runtimeUrl: "http://runtime-b.test" };
+		store.suspendRuntime(runtimeConfig);
+		expect(store.getSnapshot().runtimeConfig).toEqual(runtimeConfig);
+		expect(store.getSnapshot().conversations).toEqual([]);
+		expect(store.getSnapshot().draftsByConversation).toEqual({});
+		expect(store.getSnapshot().connectionState).toBe("disconnected");
+		await store.bootstrap();
+		expect(client.getRuntimeConfig).toHaveBeenCalledTimes(2);
+		await store.bootstrap({ resumeSuspended: true });
+		expect(store.getSnapshot().runtimeConfig).toEqual(runtimeConfig);
+		expect(store.getSnapshot().connectionState).toBe("connected");
+	});
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 45c029c4..b68de85c 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -1,6 +1,7 @@
 import type {
 	HistoryItem,
 	RuntimeClient,
+	RuntimeConfig,
 	RuntimeSseEvent,
 	RuntimeSseStatus,
 	SendMessageInput,
@@ -29,7 +30,9 @@ export type ChatStore = {
 		runtimeUrl?: string;
 		preserveSelectionId?: string;
 		resuming?: boolean;
+		resumeSuspended?: boolean;
 	}) => Promise<void>;
+	suspendRuntime: (runtimeConfig?: RuntimeConfig | null) => void;
 	refreshCommandsIfStale: () => Promise<void>;
 	createConversation: (title?: string) => Promise<void>;
 	deleteConversation: (conversationId: string) => Promise<void>;
@@ -672,6 +675,7 @@ export function createChatStore({
 	let state = createInitialChatState();
 	let runtimeUrl: string | null = null;
 	let runtimeGeneration = 0;
+	let runtimeSuspended = false;
 	const listeners = new Set<() => void>();
 	const subscriptionsByJob = new Map<string, string>();
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
@@ -731,7 +735,27 @@ export function createChatStore({
 		};
 	}
 
+	function suspendRuntime(runtimeConfig = state.runtimeConfig): void {
+		if (runtimeConfig?.runtimeUrl && runtimeConfig.runtimeUrl !== runtimeUrl) {
+			resetRuntimeScope(runtimeConfig.runtimeUrl);
+		} else {
+			runtimeGeneration += 1;
+			clearNativeSubscriptions();
+			sendInFlight = false;
+		}
+		runtimeSuspended = true;
+		inFlightBootstrap = null;
+		state = {
+			...state,
+			runtimeConfig,
+			bootstrapping: false,
+			connectionState: "disconnected",
+		};
+		emit();
+	}
+
 	async function loadHistory(conversationId: string): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		dispatch({ type: "history/loading", conversationId });
 		try {
@@ -760,6 +784,7 @@ export function createChatStore({
 	}
 
 	async function startStreamForJob(job: ChatJob): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		if (subscriptionsByJob.has(job.jobId)) {
 			return;
@@ -926,13 +951,14 @@ export function createChatStore({
 		resuming = false,
 	): Promise<void> {
 		let generation = runtimeGeneration;
+		let runtimeConfig: RuntimeConfig | null = null;
 		dispatch({ type: "bootstrap/start" });
 		// Android 切后台返回等续接场景：标记为 resuming，连接成功后由后续状态覆盖
 		if (resuming) {
 			dispatch({ type: "connection/set", connectionState: "resuming" });
 		}
 		try {
-			const runtimeConfig = await client.getRuntimeConfig();
+			runtimeConfig = await client.getRuntimeConfig();
 			if (generation !== runtimeGeneration) return;
 			if (
 				runtimeConfig?.runtimeUrl &&
@@ -960,6 +986,7 @@ export function createChatStore({
 				]);
 			if (generation !== runtimeGeneration) return;
 			lastCommandsFetchedAt = Date.now();
+			runtimeSuspended = false;
 			// 仅选取真实存在于会话列表中的会话：defaultConversationId 是后端常量
 			// （legacy-system-42），未必对应已存在的会话，盲目用它会触发 getHistory 404
 			const conversationIds = new Set(
@@ -1017,7 +1044,11 @@ export function createChatStore({
 			}
 		} catch (err) {
 			if (generation !== runtimeGeneration) return;
-			dispatch({ type: "bootstrap/error", error: errorMessage(err) });
+			dispatch({
+				type: "bootstrap/error",
+				runtimeConfig,
+				error: errorMessage(err),
+			});
 		}
 	}
 
@@ -1025,7 +1056,9 @@ export function createChatStore({
 		runtimeUrl?: string;
 		preserveSelectionId?: string;
 		resuming?: boolean;
+		resumeSuspended?: boolean;
 	}): Promise<void> {
+		if (runtimeSuspended && !opts?.resumeSuspended) return;
 		if (opts?.runtimeUrl && opts.runtimeUrl !== runtimeUrl) {
 			resetRuntimeScope(opts.runtimeUrl);
 			inFlightBootstrap = null;
@@ -1049,6 +1082,7 @@ export function createChatStore({
 	 * 使 Skills 热重载新增的命令可见。未连接或未配置时跳过。
 	 */
 	async function refreshCommandsIfStale(): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		if (!state.runtimeConfig?.hasApiKey || state.bootstrapping) {
 			return;
@@ -1067,6 +1101,7 @@ export function createChatStore({
 	}
 
 	async function createConversation(title?: string): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		dispatch({ type: "conversation/creating", creating: true });
 		try {
@@ -1085,6 +1120,7 @@ export function createChatStore({
 	}
 
 	async function deleteConversation(conversationId: string): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		const wasSelected = state.selectedConversationId === conversationId;
 		const nextSelectedId = wasSelected
@@ -1112,6 +1148,7 @@ export function createChatStore({
 		conversationId: string,
 		newTitle: string,
 	): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		try {
 			await client.renameConversation(conversationId, newTitle);
@@ -1133,6 +1170,7 @@ export function createChatStore({
 	}
 
 	async function selectConversation(conversationId: string): Promise<void> {
+		if (runtimeSuspended) return;
 		if (state.selectedConversationId === conversationId) {
 			return;
 		}
@@ -1147,6 +1185,7 @@ export function createChatStore({
 	}
 
 	async function sendSelectedMessage(): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		// in-flight 锁：从点击到 job 建立期间阻止重复发送，
 		// 避免快速双击重复插入乐观消息 / 重复请求后端
@@ -1247,6 +1286,7 @@ export function createChatStore({
 	}
 
 	async function cancelJob(jobId: string): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		const conversationId = state.jobConversationById[jobId];
 		if (!conversationId) {
@@ -1286,6 +1326,7 @@ export function createChatStore({
 		conversationId: string,
 		filePath: string,
 	): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		const trimmed = filePath.trim();
 		if (!trimmed) {
@@ -1635,6 +1676,7 @@ export function createChatStore({
 	}
 
 	async function loadMoreHistory(conversationId: string): Promise<void> {
+		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
 		const historyState = state.historyByConversation[conversationId];
 		if (!historyState?.hasMore || historyState.loading) {
@@ -1673,6 +1715,7 @@ export function createChatStore({
 
 	return {
 		bootstrap,
+		suspendRuntime,
 		refreshCommandsIfStale,
 		createConversation,
 		deleteConversation,
diff --git a/apps/undefined-chat/src/connection-recovery.test.tsx b/apps/undefined-chat/src/connection-recovery.test.tsx
new file mode 100644
index 00000000..0f4cb882
--- /dev/null
+++ b/apps/undefined-chat/src/connection-recovery.test.tsx
@@ -0,0 +1,108 @@
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { App } from "./App";
+import { LanguageProvider, LOCALE_STORAGE_KEY } from "./i18n";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+
+describe("connection recovery through the real Tauri client and store", () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+		localStorage.clear();
+		localStorage.setItem(LOCALE_STORAGE_KEY, "zh-CN");
+		vi.mocked(listen).mockResolvedValue(() => undefined);
+	});
+
+	test.each([false, true])(
+		"key failure with rollback failure=%s keeps UI and Native target consistent and prevents Runtime requests",
+		async (rollbackFails) => {
+			let nativeUrl = "http://runtime-a.test";
+			const runtimeCalls: Array<{ command: string; origin: string }> = [];
+			vi.mocked(invoke).mockImplementation(async (command, args) => {
+				switch (command) {
+					case "get_runtime_config":
+						return { runtimeUrl: nativeUrl };
+					case "load_api_key_status":
+						return { available: true, storage: "system-keyring" };
+					case "save_runtime_config": {
+						const { input } = args as { input: { runtimeUrl: string } };
+						if (rollbackFails && input.runtimeUrl === "http://runtime-a.test") {
+							throw new Error("rollback denied");
+						}
+						nativeUrl = input.runtimeUrl;
+						return { runtimeUrl: nativeUrl };
+					}
+					case "save_api_key":
+						throw new Error("keyring denied");
+				}
+				runtimeCalls.push({ command, origin: nativeUrl });
+				switch (command) {
+					case "probe_runtime":
+						return { status: 200, ok: true, body: "ok" };
+					case "list_conversations":
+						return {
+							conversations: [
+								{ id: "legacy-system-42", title: "A conversation" },
+							],
+							default_conversation_id: "legacy-system-42",
+						};
+					case "get_history":
+						return {
+							conversation_id: "legacy-system-42",
+							items: [
+								{ message_id: "a-history", role: "user", content: "A history" },
+							],
+						};
+					case "get_active_jobs":
+						return { jobs: [] };
+					case "list_commands":
+						return { commands: [] };
+					default:
+						throw new Error(`Unexpected Native command: ${command}`);
+				}
+			});
+			render(
+				<LanguageProvider>
+					<App />
+				</LanguageProvider>,
+			);
+			await screen.findByText("A history");
+			await userEvent.type(
+				screen.getByLabelText("消息输入"),
+				"A private draft",
+			);
+			fireEvent.keyDown(window, { key: ",", ctrlKey: true });
+			await userEvent.clear(screen.getByLabelText("Runtime URL"));
+			await userEvent.type(
+				screen.getByLabelText("Runtime URL"),
+				"http://runtime-b.test",
+			);
+			await userEvent.type(screen.getByLabelText("API Key"), "B-key");
+			await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+			await screen.findByText(/keyring denied/);
+			expect(nativeUrl).toBe(
+				rollbackFails ? "http://runtime-b.test" : "http://runtime-a.test",
+			);
+			expect(screen.getByLabelText("Runtime URL")).toHaveValue(nativeUrl);
+			expect(screen.getByLabelText("消息输入")).toBeDisabled();
+			expect(screen.getByLabelText("消息输入")).toHaveValue(
+				rollbackFails ? "" : "A private draft",
+			);
+			fireEvent.keyDown(window, { key: "Escape" });
+			expect(screen.getByLabelText("Runtime URL")).toBeInTheDocument();
+			fireEvent.keyDown(window, { key: "Enter", ctrlKey: true });
+			expect(runtimeCalls.map(({ origin }) => origin)).toEqual(
+				Array(5).fill("http://runtime-a.test"),
+			);
+			expect(
+				vi
+					.mocked(invoke)
+					.mock.calls.filter(([command]) => command === "send_message"),
+			).toEqual([]);
+		},
+	);
+});
diff --git a/apps/undefined-chat/src/i18n/index.ts b/apps/undefined-chat/src/i18n/index.ts
index 014b5a87..a7a8a2cb 100644
--- a/apps/undefined-chat/src/i18n/index.ts
+++ b/apps/undefined-chat/src/i18n/index.ts
@@ -53,6 +53,8 @@ export type TranslationKey =
 	| "setup.error.needUrl"
 	| "setup.error.needApiKey"
 	| "setup.error.invalidUrl"
+	| "setup.error.reconfigure"
+	| "setup.error.rollbackFailed"
 	// 附件操作（App 级 alert / 选择器）
 	| "attachment.saveFailed"
 	| "attachment.saved"
@@ -224,6 +226,10 @@ export const dictionaries: Record<Locale, TranslationDictionary> = {
 		"setup.error.needUrl": "请输入 Runtime URL",
 		"setup.error.needApiKey": "请输入 API Key",
 		"setup.error.invalidUrl": "URL 格式不正确",
+		"setup.error.reconfigure":
+			"连接配置保存失败，请重新输入 API Key 并连接。{error}",
+		"setup.error.rollbackFailed":
+			"{error}；恢复旧 Runtime URL 失败：{rollbackError}",
 		"attachment.saveFailed": "附件保存失败",
 		"attachment.saved": "已保存 {name}",
 		"attachment.previewFailed": "附件无法预览",
@@ -377,6 +383,10 @@ export const dictionaries: Record<Locale, TranslationDictionary> = {
 		"setup.error.needUrl": "Please enter the Runtime URL",
 		"setup.error.needApiKey": "Please enter the API Key",
 		"setup.error.invalidUrl": "Invalid URL format",
+		"setup.error.reconfigure":
+			"Connection settings were not saved. Enter the API key and reconnect. {error}",
+		"setup.error.rollbackFailed":
+			"{error}; restoring the previous Runtime URL failed: {rollbackError}",
 		"attachment.saveFailed": "Failed to save attachment",
 		"attachment.saved": "Saved {name}",
 		"attachment.previewFailed": "Attachment cannot be previewed",
diff --git a/apps/undefined-chat/src/runtime-client/tauri.test.ts b/apps/undefined-chat/src/runtime-client/tauri.test.ts
index b74a56af..74bb9470 100644
--- a/apps/undefined-chat/src/runtime-client/tauri.test.ts
+++ b/apps/undefined-chat/src/runtime-client/tauri.test.ts
@@ -17,6 +17,23 @@ describe("createTauriRuntimeClient", () => {
 		vi.resetAllMocks();
 	});
 
+	test("clears the persisted target through the registered Native command", async () => {
+		vi.mocked(invoke).mockResolvedValueOnce(undefined);
+		await createTauriRuntimeClient().clearRuntimeConfig();
+		expect(invoke).toHaveBeenCalledWith("clear_runtime_config");
+	});
+
+	test("does not persist a URL if the API key status request rejects", async () => {
+		vi.mocked(invoke).mockRejectedValueOnce(
+			new Error("key status unavailable"),
+		);
+		await expect(
+			createTauriRuntimeClient().saveRuntimeConfig("http://runtime-b.test"),
+		).rejects.toThrow("key status unavailable");
+		expect(invoke).toHaveBeenCalledTimes(1);
+		expect(invoke).toHaveBeenCalledWith("load_api_key_status");
+	});
+
 	test("normalizes conversation and active job responses from Tauri commands", async () => {
 		vi.mocked(invoke).mockResolvedValueOnce({
 			status: 200,
diff --git a/apps/undefined-chat/src/runtime-client/tauri.ts b/apps/undefined-chat/src/runtime-client/tauri.ts
index 0bdedde8..cf772dc9 100644
--- a/apps/undefined-chat/src/runtime-client/tauri.ts
+++ b/apps/undefined-chat/src/runtime-client/tauri.ts
@@ -464,12 +464,11 @@ export function createTauriRuntimeClient(): RuntimeClient {
 		},
 
 		async saveRuntimeConfig(runtimeUrl: string): Promise<RuntimeConfig> {
-			const [config, apiKeyStatus] = await Promise.all([
-				invoke("save_runtime_config", {
-					input: { runtimeUrl },
-				}),
-				this.loadApiKeyStatus(),
-			]);
+			// 先确认密钥状态可读取，避免并行读取失败时 URL 已保存却丢失回执。
+			const apiKeyStatus = await this.loadApiKeyStatus();
+			const config = await invoke("save_runtime_config", {
+				input: { runtimeUrl },
+			});
 			const normalized = normalizeRuntimeConfig(config, apiKeyStatus);
 			if (!normalized) {
 				throw new Error("Runtime config response did not include runtimeUrl");
@@ -477,6 +476,10 @@ export function createTauriRuntimeClient(): RuntimeClient {
 			return normalized;
 		},
 
+		async clearRuntimeConfig(): Promise<void> {
+			await invoke("clear_runtime_config");
+		},
+
 		async saveApiKey(apiKey: string): Promise<ApiKeyStatus> {
 			return normalizeApiKeyStatus(await invoke("save_api_key", { apiKey }));
 		},
diff --git a/apps/undefined-chat/src/runtime-client/types.ts b/apps/undefined-chat/src/runtime-client/types.ts
index 949c19ac..59021848 100644
--- a/apps/undefined-chat/src/runtime-client/types.ts
+++ b/apps/undefined-chat/src/runtime-client/types.ts
@@ -293,6 +293,7 @@ export type EventStreamSubscription = {
 export type RuntimeClient = {
 	getRuntimeConfig: () => Promise<RuntimeConfig | null>;
 	saveRuntimeConfig: (runtimeUrl: string) => Promise<RuntimeConfig>;
+	clearRuntimeConfig: () => Promise<void>;
 	saveApiKey: (apiKey: string) => Promise<ApiKeyStatus>;
 	confirmInsecureStorageFallback: () => Promise<ApiKeyStatus>;
 	loadApiKeyStatus: () => Promise<ApiKeyStatus>;
diff --git a/apps/undefined-chat/src/test-fixtures.ts b/apps/undefined-chat/src/test-fixtures.ts
index e10b778e..08ac82b8 100644
--- a/apps/undefined-chat/src/test-fixtures.ts
+++ b/apps/undefined-chat/src/test-fixtures.ts
@@ -153,6 +153,7 @@ export function runtimeClientStub(
 			runtimeUrl,
 			hasApiKey: true,
 		})),
+		clearRuntimeConfig: vi.fn(async () => undefined),
 		saveApiKey: vi.fn(async () => apiKeyStatus),
 		confirmInsecureStorageFallback: vi.fn(async () => ({
 			...apiKeyStatus,
diff --git a/apps/undefined-chat/tests/e2e/connection-setup.test.tsx b/apps/undefined-chat/tests/e2e/connection-setup.test.tsx
index 28cfefaa..0f3c4ffa 100644
--- a/apps/undefined-chat/tests/e2e/connection-setup.test.tsx
+++ b/apps/undefined-chat/tests/e2e/connection-setup.test.tsx
@@ -3,6 +3,7 @@ import userEvent from "@testing-library/user-event";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { App } from "../../src/App";
 import { createTauriRuntimeClient } from "../../src/runtime-client/tauri";
+import type { RuntimeConfig } from "../../src/runtime-client/types";
 import { runtimeClientStub } from "../../src/test-fixtures";
 import { renderWithProviders } from "../../src/test-utils";
 
@@ -50,12 +51,12 @@ describe("E2E: Connection Setup Flow", () => {
 	test("保存配置并在连接后引导应用", async () => {
 		const client = runtimeClientStub({
 			getRuntimeConfig: vi
-				.fn()
-				.mockResolvedValueOnce(null)
-				.mockResolvedValueOnce({
+				.fn(async (): Promise<RuntimeConfig | null> => ({
 					runtimeUrl: "http://localhost:8788",
 					hasApiKey: true,
-				}),
+				}))
+				.mockResolvedValueOnce(null)
+				.mockResolvedValueOnce(null),
 		});
 		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
 
@@ -118,12 +119,12 @@ describe("E2E: Connection Setup Flow", () => {
 	test("支持不安全存储降级选项", async () => {
 		const client = runtimeClientStub({
 			getRuntimeConfig: vi
-				.fn()
-				.mockResolvedValueOnce(null)
-				.mockResolvedValueOnce({
+				.fn(async (): Promise<RuntimeConfig | null> => ({
 					runtimeUrl: "http://localhost:8788",
 					hasApiKey: true,
-				}),
+				}))
+				.mockResolvedValueOnce(null)
+				.mockResolvedValueOnce(null),
 		});
 		vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
 
@@ -168,7 +169,9 @@ describe("E2E: Connection Setup Flow", () => {
 		await userEvent.type(keyInput, "sk-test");
 		await userEvent.click(connectBtn);
 
-		expect(await screen.findByText("网络连接失败")).toBeInTheDocument();
+		expect(await screen.findByText(/网络连接失败/)).toBeInTheDocument();
+		expect(client.clearRuntimeConfig).toHaveBeenCalledOnce();
+		expect(screen.getByLabelText("消息输入")).toBeDisabled();
 	});
 
 	test("已有配置时可以通过设置按钮重新打开配置面板", async () => {
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index d6b4de95..251070cf 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -56,6 +56,8 @@ Undefined Chat 不持久化权威聊天数据。以下内容都以 Runtime 返
 
 Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 React 传入任意 URL 后绕过目标主机限制。React 不直接持有 API Key；受保护请求由 Rust 侧注入 `X-Undefined-API-Key`。
 
+保存连接配置时会暂停 Runtime 请求及任务订阅。URL 保存后，密钥或降级确认失败会恢复先前 URL（首次配置则清除新 URL）；客户端显示原生端实际保存的目标，并保持不可发送的配置界面，要求重新输入密钥后连接。恢复 URL 失败时也保持此限制；原生配置无法读取时保留最后确认的目标并继续禁用请求。不会用旧会话界面操作新目标，或假定失败的密钥写入一定没有副作用。
+
 事件策略：
 
 - 默认使用 SSE 订阅 job events。

From 09665d16956c9e0124b33e92ff1b61263b0404ff Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:21:52 +0800
Subject: [PATCH 044/121] fix(webui): ignore stale chat job poll completions

---
 docs/webui-guide.md                       |   1 +
 src/Undefined/webui/static/js/runtime.js  |  30 ++---
 tests/frontend/runtime_chat_harness.js    | 139 ++++++++++++++++++++++
 tests/test_webui_runtime_chat_behavior.py |  17 +++
 4 files changed, 170 insertions(+), 17 deletions(-)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index d9a54fb4..3509894e 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -161,6 +161,7 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - AI 消息支持引用：可引用整条 AI 消息、选中的某段文字，或 HTML 预览中点选的元素。引用会显示在输入框右侧的待发送引用条中，可在发送前移除；实际发送时不会新增接口或附件，而是自动在用户消息前拼接为 Markdown `>` 引用块，例如 `> 引用 AI:`，随后和文本、图片、文件一起进入同一条 WebChat job 消息。发送后的引用块会像代码块一样折叠显示，展开后内部固定高度并可滚动。发送失败时待引用内容会保留，发送成功后清空。
 - 默认加载最新 50 条消息并滚动到底部；向上滚动到顶部会按后端返回的 `next_before` 游标懒加载更早历史，并保持原视口偏移，避免一次性恢复大量工具块造成卡顿。“自动滚动到底部”开关默认开启并保存在浏览器本地，关闭后 AI 回复、工具 / Agent 状态和 AI 阶段刷新不会打断当前位置；首次加载和主动发送新消息仍会定位到底部。系统开启减少动态效果时，聊天滚动会改为即时跳转。
 - 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 `conversation_id + job_id + seq` 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；`done` / `error` / `cancelled` 终态先到时仍保留 job 和发送锁，并继续轮询等待 `history_finalized=true`；确认后端收尾完成后刷新权威历史，刷新成功才解除发送锁；历史慢响应或刷新失败期间继续保留锁，并通过原轮询重试恢复。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
+- 切换对话后再发起新任务时，迟到的旧任务轮询响应不会覆盖新回复、改变新任务的发送锁和取消按钮，或打断新任务续接；旧请求的失败提示也不会影响当前任务。
 - 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口，等待历史收尾完成后解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 `reuse_previous_user_message=true` 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
 - 运行中的 AI 气泡会在 `AI` 标签后实时显示当前阶段和后端计算的总已用时，例如构建上下文、查长期记忆、查认知记忆、等待模型、等待工具、发送消息；任务完成后该位置显示本轮回复总用时。工具 / Agent 摘要行会在名称旁显示调用耗时，运行中先显示后端快照时间，轮询间隙用本地时间临时递增，下一次查询后自动校准；结束后固定显示后端结束事件的总耗时。轮询刷新只更新已有状态和计时节点，结构未变化时不会重建工具 / Agent 块，避免运行中闪烁。状态条区分运行中、成功和失败；整轮回复总耗时会写入 WebChat 历史 metadata。
 - WebChat job 事件会更新同一个 AI 气泡；AI 正文和主对话工具 / Agent 调用按事件时序显示，例如工具调用、正文回复、结束工具会依次出现在同一气泡内。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index a6102a27..0ef38567 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -5387,6 +5387,7 @@
     }
 
     function applyChatEventsPayload(data, jobId) {
+        if (runtimeState.activeJobId !== jobId) return;
         const events = data && Array.isArray(data.events) ? data.events : [];
         const job = data && data.job ? data.job : null;
         events
@@ -5480,27 +5481,22 @@
                     format: "json",
                 }),
             ]);
+            if (runtimeState.activeJobId !== jobId) return;
             runtimeState.chatPollBackoffMs = CHAT_POLL_INTERVAL_MS;
             applyChatEventsPayload(data, jobId);
         } catch (error) {
-            if (runtimeState.activeJobId === jobId) {
-                showToast(t("runtime.chat_reconnecting"), "warning", 1800);
-                runtimeState.chatPollBackoffMs = Math.min(
-                    8000,
-                    Math.max(
-                        CHAT_POLL_INTERVAL_MS,
-                        runtimeState.chatPollBackoffMs * 1.6,
-                    ),
-                );
-            } else {
-                showToast(
-                    `${t("runtime.failed")}: ${appendRuntimeApiHint(error.message || error)}`,
-                    "error",
-                    5000,
-                );
-            }
+            if (runtimeState.activeJobId !== jobId) return;
+            showToast(t("runtime.chat_reconnecting"), "warning", 1800);
+            runtimeState.chatPollBackoffMs = Math.min(
+                8000,
+                Math.max(
+                    CHAT_POLL_INTERVAL_MS,
+                    runtimeState.chatPollBackoffMs * 1.6,
+                ),
+            );
         }
-        if (runtimeState.activeJobId !== jobId || !runtimeState.chatBusy) {
+        if (runtimeState.activeJobId !== jobId) return;
+        if (!runtimeState.chatBusy) {
             stopChatPolling();
             return;
         }
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index 4d930e27..233d816f 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -343,6 +343,7 @@ function createEnv(root, options = {}) {
         requests,
         requestDetails,
         setRoutes,
+        response,
         scrollActivity,
         scrollTopWrites,
         eventSourceConstructions,
@@ -2875,6 +2876,144 @@ for (const status of ["done", "error", "cancelled"]) {
     SCENARIOS[`history_finalization_${status}`] = (env) => jobWaitsForHistoryFinalization(env, status);
 }
 
+async function staleChatJobPoll(env, outcome) {
+    const { window, setRoutes, response } = env;
+    let jobPosts = 0;
+    let oldFinished = false;
+    let newPolls = 0;
+    const oldJob = {
+        job_id: "old",
+        conversation_id: "A",
+        status: "running",
+        last_seq: 2,
+        history_finalized: false,
+    };
+    const newJob = { ...oldJob, job_id: "new" };
+    setRoutes([
+        {
+            match: "/chat/conversations",
+            reply: { body: {
+                conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+                active_job: null,
+            } },
+        },
+        {
+            match: "/chat/history",
+            reply: (url) => ({ body: {
+                items: oldFinished && url.includes("conversation_id=A")
+                    ? [{ role: "bot", content: "old-persisted" }] : [],
+                has_more: false,
+                next_before: null,
+            } }),
+        },
+        {
+            match: "/chat/jobs/active",
+            reply: (url) => ({ body: {
+                job: url.includes("conversation_id=A") && jobPosts > 0 && !oldFinished
+                    ? oldJob : null,
+            } }),
+        },
+        {
+            match: "/jobs/old/events",
+            reply: { body: { job: oldJob, events: [
+                { seq: 1, event: "meta", payload: { job_id: "old", conversation_id: "A" } },
+                { seq: 2, event: "message", payload: { job_id: "old", conversation_id: "A", content: "old-live" } },
+            ] } },
+        },
+        {
+            match: "/jobs/new/events",
+            reply: (url) => {
+                newPolls += 1;
+                const after = Number(new URL(url, window.location.href).searchParams.get("after"));
+                const events = [
+                    { seq: 1, event: "meta", payload: { job_id: "new", conversation_id: "A" } },
+                    { seq: 2, event: "message", payload: { job_id: "new", conversation_id: "A", content: "new-live" } },
+                    ...(newPolls > 1 ? [{ seq: 3, event: "message", payload: { job_id: "new", conversation_id: "A", content: "new-followup" } }] : []),
+                ].filter((event) => event.seq > after);
+                return { body: { job: newJob, events } };
+            },
+        },
+        {
+            match: "/chat/jobs",
+            reply: () => ({ body: {
+                job_id: ++jobPosts === 1 ? "old" : "new", conversation_id: "A",
+            } }),
+        },
+    ]);
+    const fetch = window.fetch;
+    const pending = [];
+    let deferOld = false;
+    window.fetch = (url, options) => {
+        if (deferOld && String(url).includes("/jobs/old/events")) {
+            return new Promise((resolve, reject) => pending.push({ url: String(url), resolve, reject }));
+        }
+        return fetch(url, options);
+    };
+    window.RuntimeController.init();
+    await window.RuntimeController.loadChatHistory(true);
+    const input = window.document.getElementById("runtimeChatInput");
+    const button = window.document.getElementById("btnRuntimeChatSend");
+    input.value = "first";
+    button.click();
+    await tick();
+    deferOld = true;
+    window.document.querySelector('[data-conversation-select="B"]').click();
+    await tick();
+    window.document.querySelector('[data-conversation-select="A"]').click();
+    await tick();
+    if (pending.length !== 2) {
+        throw new Error(`expected two overlapping old job polls, got ${pending.length}`);
+    }
+    oldFinished = true;
+    pending[0].resolve(response(200, {
+        job: { ...oldJob, status: "done", last_seq: 3, history_finalized: true },
+        events: [{ seq: 3, event: "done", payload: { job_id: "old", conversation_id: "A", reply: "old-live" } }],
+    }));
+    await tick();
+    const oldUnlocked = !button.disabled;
+    input.value = "second";
+    button.click();
+    await tick();
+    const snapshot = () => ({
+        disabled: button.disabled,
+        nodes: chatNodes(window).map((node) => ({ text: node.contentText, job: node.jobId })),
+        cancelIds: Array.from(window.document.querySelectorAll("[data-cancel-job]"))
+            .filter((element) => !element.hidden).map((element) => element.dataset.cancelJob),
+    });
+    const beforeLate = snapshot();
+    if (outcome === "failure") {
+        pending[1].reject(new Error("obsolete poll failure"));
+    } else {
+        const terminal = outcome === "done";
+        pending[1].resolve(response(200, {
+            job: terminal ? { ...oldJob, status: "done", history_finalized: true } : oldJob,
+            events: terminal ? [
+                { seq: 99, event: "done", payload: { job_id: "old", conversation_id: "A", reply: "INTRUDER" } },
+            ] : [
+                { seq: 98, event: "meta", payload: { job_id: "old", conversation_id: "A" } },
+                { seq: 99, event: "message", payload: { job_id: "old", conversation_id: "A", content: "INTRUDER" } },
+            ],
+        }));
+    }
+    await tick();
+    const afterLate = snapshot();
+    await settle(650);
+    return {
+        oldUnlocked,
+        jobPosts,
+        beforeLate,
+        afterLate,
+        newPolls,
+        allNodes: chatNodes(window),
+        nextPollUrls: env.requests.filter((url) => url.includes("/jobs/new/events")),
+        toastText: textOf(window, "toast-container"),
+    };
+}
+
+for (const outcome of ["events", "done", "failure"]) {
+    SCENARIOS[`stale_job_poll_${outcome}`] = (env) => staleChatJobPoll(env, outcome);
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index c1777bad..c1b44834 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -656,6 +656,23 @@ def test_auto_scroll_toggle_persists_preference() -> None:
 # --------------------------------------------------------------------------- #
 
 
+@pytest.mark.parametrize("outcome", ["events", "done", "failure"])
+def test_late_old_job_poll_cannot_replace_or_stop_new_job(outcome: str) -> None:
+    result = run_scenario(f"stale_job_poll_{outcome}")
+
+    assert result["oldUnlocked"] is True, result
+    assert result["jobPosts"] == 2, result
+    assert result["beforeLate"]["disabled"] is True, result
+    assert result["beforeLate"]["cancelIds"] == ["new"], result
+    assert result["afterLate"] == result["beforeLate"], result
+    assert result["newPolls"] >= 2, result
+    assert any("after=2&" in url for url in result["nextPollUrls"]), result
+    assert "obsolete poll failure" not in result["toastText"], result
+    bots = _bot_nodes(result)
+    assert [node["jobId"] for node in bots] == ["", "new"], bots
+    assert bots[-1]["contentTexts"] == ["new-live", "new-followup"], bots
+
+
 def test_foreign_conversation_events_are_ignored() -> None:
     """别的会话的事件不得写进当前会话的聊天区。
 

From 55483708540c7e4a13fc527e047f802a5c41a87d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:26:07 +0800
Subject: [PATCH 045/121] fix(chat): preserve later edits when message sending
 fails

---
 .../src/chat-store/send-recovery.test.ts      | 239 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  36 ++-
 docs/undefined-chat.md                        |   2 +
 3 files changed, 272 insertions(+), 5 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/send-recovery.test.ts

diff --git a/apps/undefined-chat/src/chat-store/send-recovery.test.ts b/apps/undefined-chat/src/chat-store/send-recovery.test.ts
new file mode 100644
index 00000000..3dc8679f
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/send-recovery.test.ts
@@ -0,0 +1,239 @@
+import { describe, expect, test, vi } from "vitest";
+import type { Attachment, RuntimeClient } from "../runtime-client/types";
+import { conversation, job, runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	let reject!: (reason: Error) => void;
+	const promise = new Promise<T>((done, fail) => {
+		resolve = done;
+		reject = fail;
+	});
+	return { promise, resolve, reject };
+}
+
+function attachment(id: string): Attachment {
+	return {
+		id,
+		name: `${id}.txt`,
+		size: 4,
+		mediaType: "text/plain",
+		kind: "file",
+		downloadUrl: null,
+		previewUrl: null,
+		discarded: false,
+	};
+}
+
+describe("send failure recovery", () => {
+	test.each(["new draft", ""])(
+		"preserves later text edits including an intentional empty draft (%j)",
+		async (laterDraft) => {
+			const sent = deferred<never>();
+			const client = runtimeClientStub({
+				sendMessage: vi
+					.fn<RuntimeClient["sendMessage"]>()
+					.mockImplementationOnce(() => sent.promise)
+					.mockResolvedValueOnce(job()),
+				uploadAttachment: vi.fn(async () => attachment("file_a")),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("default", "  first message  ");
+			store.addReference("default", { messageId: "a", quote: "first quote" });
+			await store.addAttachmentPath("default", "/mock/a.txt");
+			const original = store.getSnapshot();
+			const sending = store.sendSelectedMessage();
+			expect(client.sendMessage).toHaveBeenCalledWith({
+				conversationId: "default",
+				message: {
+					text: "first message",
+					attachmentIds: ["file_a"],
+					references: [{ messageId: "a", quote: "first quote" }],
+				},
+			});
+			store.updateDraft("default", "typed after sending");
+			store.updateDraft("default", laterDraft);
+			sent.reject(new Error("POST failed"));
+			await sending;
+			const state = store.getSnapshot();
+			expect(state.draftsByConversation.default).toBe(laterDraft);
+			expect(state.attachmentsByConversation.default).toEqual(
+				original.attachmentsByConversation.default,
+			);
+			expect(state.referencesByConversation.default).toEqual(
+				original.referencesByConversation.default,
+			);
+			expect(
+				state.historyByConversation.default.items.some(
+					(item) => item.content === "first message",
+				),
+			).toBe(false);
+			expect(state.sendError).toBe("POST failed");
+			await store.sendSelectedMessage();
+			expect(client.sendMessage).toHaveBeenLastCalledWith({
+				conversationId: "default",
+				message: {
+					text: laterDraft,
+					attachmentIds: ["file_a"],
+					references: [{ messageId: "a", quote: "first quote" }],
+				},
+			});
+		},
+	);
+
+	test("preserves a new pending attachment and a new reference while restoring unchanged text", async () => {
+		const sent = deferred<never>();
+		const uploaded = deferred<Attachment>();
+		const client = runtimeClientStub({
+			sendMessage: vi.fn(() => sent.promise),
+			uploadAttachment: vi
+				.fn()
+				.mockResolvedValueOnce(attachment("file_a"))
+				.mockImplementationOnce(() => uploaded.promise),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "  unchanged text  ");
+		store.addReference("default", { messageId: "a", quote: "old quote" });
+		await store.addAttachmentPath("default", "/mock/a.txt");
+		const sending = store.sendSelectedMessage();
+		const uploading = store.addAttachmentPath("default", "/mock/b.txt");
+		store.addReference("default", { messageId: "b", quote: "new quote" });
+		const edited = store.getSnapshot();
+		sent.reject(new Error("POST failed"));
+		await sending;
+		expect(store.getSnapshot().draftsByConversation.default).toBe(
+			"  unchanged text  ",
+		);
+		expect(store.getSnapshot().attachmentsByConversation.default).toEqual(
+			edited.attachmentsByConversation.default,
+		);
+		expect(store.getSnapshot().referencesByConversation.default).toEqual([
+			{ messageId: "b", quote: "new quote" },
+		]);
+		uploaded.resolve(attachment("file_b"));
+		await uploading;
+		expect(store.getSnapshot().attachmentsByConversation.default).toMatchObject(
+			[{ name: "file_b.txt", status: "ready", attachmentId: "file_b" }],
+		);
+	});
+
+	test("does not restore attachments or references after they were edited then cleared", async () => {
+		const sent = deferred<never>();
+		const client = runtimeClientStub({
+			sendMessage: vi.fn(() => sent.promise),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "keep original");
+		store.addReference("default", { messageId: "a", quote: "old quote" });
+		await store.addAttachmentPath("default", "/mock/a.txt");
+		const sending = store.sendSelectedMessage();
+		await store.addAttachmentPath("default", "/mock/b.txt");
+		const newAttachment =
+			store.getSnapshot().attachmentsByConversation.default[0];
+		store.clearAttachment("default", newAttachment.id);
+		store.addReference("default", { messageId: "b", quote: "new quote" });
+		store.clearReference("default", "b");
+		sent.reject(new Error("POST failed"));
+		await sending;
+		expect(store.getSnapshot().draftsByConversation.default).toBe(
+			"keep original",
+		);
+		expect(store.getSnapshot().attachmentsByConversation.default).toEqual([]);
+		expect(store.getSnapshot().referencesByConversation.default).toEqual([]);
+	});
+
+	test("editing another conversation still restores this conversation's unchanged fields", async () => {
+		const sent = deferred<never>();
+		const client = runtimeClientStub({
+			sendMessage: vi.fn(() => sent.promise),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "  exact original  ");
+		const sending = store.sendSelectedMessage();
+		store.updateDraft("other", "other conversation draft");
+		sent.reject(new Error("POST failed"));
+		await sending;
+		expect(store.getSnapshot().draftsByConversation.default).toBe(
+			"  exact original  ",
+		);
+		expect(store.getSnapshot().draftsByConversation.other).toBe(
+			"other conversation draft",
+		);
+	});
+
+	test.each(["attachments", "references"])(
+		"an edited %s field does not stop restoration of the other unchanged field",
+		async (editedField) => {
+			const sent = deferred<never>();
+			const client = runtimeClientStub({
+				sendMessage: vi.fn(() => sent.promise),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("default", "original draft");
+			store.addReference("default", { messageId: "a", quote: "old quote" });
+			await store.addAttachmentPath("default", "/mock/a.txt");
+			const original = store.getSnapshot();
+			const sending = store.sendSelectedMessage();
+			if (editedField === "attachments") {
+				await store.addAttachmentPath("default", "/mock/b.txt");
+			} else {
+				store.addReference("default", { messageId: "b", quote: "new quote" });
+			}
+			const edited = store.getSnapshot();
+			sent.reject(new Error("POST failed"));
+			await sending;
+			const recovered = store.getSnapshot();
+			expect(recovered.attachmentsByConversation.default).toEqual(
+				editedField === "attachments"
+					? edited.attachmentsByConversation.default
+					: original.attachmentsByConversation.default,
+			);
+			expect(recovered.referencesByConversation.default).toEqual(
+				editedField === "references"
+					? edited.referencesByConversation.default
+					: original.referencesByConversation.default,
+			);
+		},
+	);
+
+	test.each([false, true])(
+		"removing a conversation clears its revision and rejects stale recovery (reimport=%s)",
+		async (reimport) => {
+			const sent = deferred<never>();
+			const client = runtimeClientStub({
+				sendMessage: vi.fn(() => sent.promise),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("default", "deleted draft");
+			const sending = store.sendSelectedMessage();
+			await store.deleteConversation("default");
+			if (reimport) {
+				// 同名会话重新导入并两次编辑，也不能复用已删除会话的旧修订。
+				store.dispatch({
+					type: "conversation/upsert",
+					conversation: conversation(),
+				});
+				store.updateDraft("default", "new draft");
+				store.updateDraft("default", "");
+			}
+			sent.reject(new Error("POST failed"));
+			await sending;
+			expect(store.getSnapshot().draftsByConversation.default).toBe(
+				reimport ? "" : undefined,
+			);
+			expect(
+				store.getSnapshot().attachmentsByConversation.default,
+			).toBeUndefined();
+			expect(
+				store.getSnapshot().referencesByConversation.default,
+			).toBeUndefined();
+		},
+	);
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index b68de85c..c466191d 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -676,6 +676,8 @@ export function createChatStore({
 	let runtimeUrl: string | null = null;
 	let runtimeGeneration = 0;
 	let runtimeSuspended = false;
+	const draftRevisionsByConversation = new Map<string, number>();
+	let draftRevision = 0;
 	const listeners = new Set<() => void>();
 	const subscriptionsByJob = new Map<string, string>();
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
@@ -698,6 +700,11 @@ export function createChatStore({
 	}
 
 	function dispatch(action: ChatAction): void {
+		if (action.type === "draft/set") {
+			draftRevisionsByConversation.set(action.conversationId, ++draftRevision);
+		} else if (action.type === "conversation/remove") {
+			draftRevisionsByConversation.delete(action.conversationId);
+		}
 		state = chatReducer(state, action);
 		// 自动滚动偏好在状态更新后持久化（reducer 保持纯函数，副作用集中在此）
 		if (action.type === "autoScroll/set") {
@@ -727,6 +734,7 @@ export function createChatStore({
 		clearNativeSubscriptions();
 		sendInFlight = false;
 		lastCommandsFetchedAt = 0;
+		draftRevisionsByConversation.clear();
 		state = {
 			...createInitialChatState(),
 			autoScrollEnabled: state.autoScrollEnabled,
@@ -1201,7 +1209,8 @@ export function createChatStore({
 			dispatch({ type: "send/error", error: "error.conversationRunning" });
 			return;
 		}
-		const text = (state.draftsByConversation[conversationId] ?? "").trim();
+		const draft = state.draftsByConversation[conversationId] ?? "";
+		const text = draft.trim();
 		const attachments = state.attachmentsByConversation[conversationId] ?? [];
 		if (
 			attachments.some((item) => ["queued", "uploading"].includes(item.status))
@@ -1244,6 +1253,10 @@ export function createChatStore({
 		dispatch({ type: "draft/set", conversationId, draft: "" });
 		dispatch({ type: "attachments/set", conversationId, attachments: [] });
 		dispatch({ type: "references/set", conversationId, references: [] });
+		const clearedDraftRevision =
+			draftRevisionsByConversation.get(conversationId);
+		const clearedAttachments = state.attachmentsByConversation[conversationId];
+		const clearedReferences = state.referencesByConversation[conversationId];
 
 		const input: SendMessageInput = {
 			conversationId,
@@ -1262,7 +1275,7 @@ export function createChatStore({
 			await startStreamForJob(job);
 		} catch (err) {
 			if (generation !== runtimeGeneration) return;
-			// 发送失败：移除乐观用户消息并恢复草稿/附件/引用
+			// 发送失败：移除乐观消息，仅恢复发送后未再次编辑的字段。
 			const currentHistory = state.historyByConversation[conversationId];
 			if (currentHistory) {
 				dispatch({
@@ -1276,9 +1289,22 @@ export function createChatStore({
 					total: Math.max(0, currentHistory.total - 1),
 				});
 			}
-			dispatch({ type: "draft/set", conversationId, draft: text });
-			dispatch({ type: "attachments/set", conversationId, attachments });
-			dispatch({ type: "references/set", conversationId, references });
+			if (
+				draftRevisionsByConversation.get(conversationId) ===
+				clearedDraftRevision
+			) {
+				dispatch({ type: "draft/set", conversationId, draft });
+			}
+			if (
+				state.attachmentsByConversation[conversationId] === clearedAttachments
+			) {
+				dispatch({ type: "attachments/set", conversationId, attachments });
+			}
+			if (
+				state.referencesByConversation[conversationId] === clearedReferences
+			) {
+				dispatch({ type: "references/set", conversationId, references });
+			}
 			dispatch({ type: "send/error", error: errorMessage(err) });
 		} finally {
 			if (generation === runtimeGeneration) sendInFlight = false;
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 251070cf..2e45e349 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -52,6 +52,8 @@ Undefined Chat 不持久化权威聊天数据。以下内容都以 Runtime 返
 
 连接到不同 Runtime 时，会清理旧实例的草稿、附件 UID、消息引用、历史、任务和图片预览缓存，并丢弃旧实例迟到的请求或订阅通知，避免相同会话 ID 造成跨实例误发送。同一 Runtime 的重连及 Android 恢复保留编辑状态和 UI 偏好；自动滚动、平台与布局偏好在切换实例时也保留。
 
+发送请求会立即清空编辑器并显示乐观用户消息。发送失败时移除该乐观消息，仅恢复请求后未再编辑的原始草稿、附件或引用；新输入和主动清空保留，各字段独立判断，不覆盖用户准备的下一条消息。
+
 ## 连接与事件
 
 Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 React 传入任意 URL 后绕过目标主机限制。React 不直接持有 API Key；受保护请求由 Rust 侧注入 `X-Undefined-API-Key`。

From 0270b50016ec43aeb82bb4897320d68b3f486f94 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 13:31:12 +0800
Subject: [PATCH 046/121] fix(webui): scope history pagination to its request

---
 docs/webui-guide.md                       |   1 +
 src/Undefined/webui/static/js/runtime.js  |  50 +++++--
 tests/frontend/runtime_chat_harness.js    | 174 ++++++++++++++++++++++
 tests/test_webui_runtime_chat_behavior.py |  37 +++++
 4 files changed, 251 insertions(+), 11 deletions(-)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 3509894e..f2e5cb84 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -160,6 +160,7 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - WebUI 场景下，代码优先直接作为聊天回复输出，不要默认转成文件附件；只有用户明确要求文件交付、代码过长不适合聊天展示，或确需附件工作流时才使用文件。所有代码块都应显式标注语言，例如 ` ```python `、` ```javascript `、` ```html `、` ```bash `，不确定语言时用 ` ```text `。
 - AI 消息支持引用：可引用整条 AI 消息、选中的某段文字，或 HTML 预览中点选的元素。引用会显示在输入框右侧的待发送引用条中，可在发送前移除；实际发送时不会新增接口或附件，而是自动在用户消息前拼接为 Markdown `>` 引用块，例如 `> 引用 AI:`，随后和文本、图片、文件一起进入同一条 WebChat job 消息。发送后的引用块会像代码块一样折叠显示，展开后内部固定高度并可滚动。发送失败时待引用内容会保留，发送成功后清空。
 - 默认加载最新 50 条消息并滚动到底部；向上滚动到顶部会按后端返回的 `next_before` 游标懒加载更早历史，并保持原视口偏移，避免一次性恢复大量工具块造成卡顿。“自动滚动到底部”开关默认开启并保存在浏览器本地，关闭后 AI 回复、工具 / Agent 状态和 AI 阶段刷新不会打断当前位置；首次加载和主动发送新消息仍会定位到底部。系统开启减少动态效果时，聊天滚动会改为即时跳转。
+- 切换会话或离开后重新进入同一会话时，上一页面的迟到历史响应会被忽略，不会混入当前历史、覆盖分页游标或清除当前正在加载的状态；旧请求的网络失败也不会给当前会话显示错误或打断其加载。后续分页继续使用当前会话返回的游标。
 - 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 `conversation_id + job_id + seq` 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；`done` / `error` / `cancelled` 终态先到时仍保留 job 和发送锁，并继续轮询等待 `history_finalized=true`；确认后端收尾完成后刷新权威历史，刷新成功才解除发送锁；历史慢响应或刷新失败期间继续保留锁，并通过原轮询重试恢复。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
 - 切换对话后再发起新任务时，迟到的旧任务轮询响应不会覆盖新回复、改变新任务的发送锁和取消按钮，或打断新任务续接；旧请求的失败提示也不会影响当前任务。
 - 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口，等待历史收尾完成后解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 `reuse_previous_user_message=true` 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index 0ef38567..271288ee 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -28,6 +28,7 @@
         chatHistoryCursor: null,
         chatHistoryHasMore: false,
         chatHistoryLoading: false,
+        chatHistoryRequest: null,
         chatHistoryFinalization: null,
         chatTopLoadSuppressedUntil: 0,
         chatAutoScroll: true,
@@ -2097,6 +2098,10 @@
     function clearChatMessages() {
         const log = get("runtimeChatLog");
         if (!log) return;
+        runtimeState.chatHistoryRequest = null;
+        runtimeState.chatHistoryLoading = false;
+        const loader = get("runtimeChatLoadMore");
+        if (loader) loader.textContent = "";
         clearToolCollapseTimers();
         log.innerHTML = "";
         runtimeState.streamingMessageId = null;
@@ -5058,6 +5063,7 @@
         runtimeState.chatHistoryCursor = null;
         runtimeState.chatHistoryHasMore = false;
         runtimeState.chatHistoryLoading = false;
+        runtimeState.chatHistoryRequest = null;
         runtimeState.chatTopLoadSuppressedUntil = 0;
         runtimeState.lastEventSeq = 0;
         runtimeState.streamingMessageId = null;
@@ -5133,19 +5139,27 @@
             return;
         }
         runtimeState.chatHistoryLoading = true;
-        const conversationId = currentChatConversationId();
-        const res = await api(
-            chatUrl("/api/runtime/chat/history", { limit: 50 }),
-        );
-        const data = await parseJsonSafe(res);
+        const request = { conversationId: currentChatConversationId() };
+        runtimeState.chatHistoryRequest = request;
+        let res;
+        let data;
+        try {
+            res = await api(
+                chatUrl("/api/runtime/chat/history", { limit: 50 }),
+            );
+            data = await parseJsonSafe(res);
+        } catch (error) {
+            if (!isCurrentChatHistoryRequest(request)) return;
+            runtimeState.chatHistoryLoading = false;
+            runtimeState.chatHistoryRequest = null;
+            throw error;
+        }
+        if (!isCurrentChatHistoryRequest(request)) return;
         if (!res.ok || (data && data.error)) {
             runtimeState.chatHistoryLoading = false;
             throw new Error(buildRequestError(res, data));
         }
-        if (
-            conversationId !== currentChatConversationId() ||
-            (expectedJobId && runtimeState.activeJobId !== expectedJobId)
-        ) {
+        if (expectedJobId && runtimeState.activeJobId !== expectedJobId) {
             runtimeState.chatHistoryLoading = false;
             return;
         }
@@ -5166,6 +5180,13 @@
         }
     }
 
+    function isCurrentChatHistoryRequest(request) {
+        return (
+            runtimeState.chatHistoryRequest === request &&
+            request.conversationId === currentChatConversationId()
+        );
+    }
+
     async function loadOlderChatHistory() {
         const log = get("runtimeChatLog");
         if (
@@ -5176,6 +5197,8 @@
         )
             return;
         runtimeState.chatHistoryLoading = true;
+        const request = { conversationId: currentChatConversationId() };
+        runtimeState.chatHistoryRequest = request;
         const loader = get("runtimeChatLoadMore");
         if (loader) loader.textContent = t("runtime.chat_loading_more");
         const previousHeight = log.scrollHeight;
@@ -5189,6 +5212,7 @@
                 }),
             );
             const data = await parseJsonSafe(res);
+            if (!isCurrentChatHistoryRequest(request)) return;
             if (!res.ok || (data && data.error)) {
                 throw new Error(buildRequestError(res, data));
             }
@@ -5206,14 +5230,18 @@
             runtimeState.chatHistoryHasMore = !!(data && data.has_more);
             log.scrollTop = previousTop + (log.scrollHeight - previousHeight);
         } catch (error) {
+            if (!isCurrentChatHistoryRequest(request)) return;
             showToast(
                 `${t("runtime.failed")}: ${appendRuntimeApiHint(error.message || error)}`,
                 "error",
                 5000,
             );
         } finally {
-            runtimeState.chatHistoryLoading = false;
-            if (loader) loader.textContent = "";
+            if (isCurrentChatHistoryRequest(request)) {
+                runtimeState.chatHistoryLoading = false;
+                runtimeState.chatHistoryRequest = null;
+                if (loader) loader.textContent = "";
+            }
         }
     }
 
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index 233d816f..dfc3a348 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3014,6 +3014,180 @@ for (const outcome of ["events", "done", "failure"]) {
     SCENARIOS[`stale_job_poll_${outcome}`] = (env) => staleChatJobPoll(env, outcome);
 }
 
+async function staleChatHistoryPage(env, returnToSameConversation, outcome) {
+    const { window, setRoutes, response } = env;
+    const historyReads = { A: 0, B: 0 };
+    setRoutes([
+        {
+            match: "/chat/conversations",
+            reply: { body: {
+                conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+                active_job: null,
+            } },
+        },
+        { match: "/chat/jobs/active", reply: { body: { job: null } } },
+        {
+            match: "/chat/history",
+            reply: (url) => {
+                const conversationId = new URL(url, window.location.href).searchParams.get("conversation_id");
+                historyReads[conversationId] += 1;
+                return { body: {
+                    conversation_id: conversationId,
+                    items: [{ role: "bot", content: `${conversationId}-current-${historyReads[conversationId]}` }],
+                    has_more: true,
+                    next_before: conversationId === "A" ? 10 : 20,
+                } };
+            },
+        },
+    ]);
+    const fetch = window.fetch;
+    const pending = [];
+    window.fetch = (url, options) => {
+        if (new URL(String(url), window.location.href).searchParams.has("before")) {
+            return new Promise((resolve, reject) => pending.push({ url: String(url), resolve, reject }));
+        }
+        return fetch(url, options);
+    };
+    window.RuntimeController.init();
+    await window.RuntimeController.loadChatHistory(true);
+    await settle(1800);
+    const log = chatLog(window);
+    const loadOlder = () => {
+        log.scrollTop = 0;
+        log.dispatchEvent(new window.Event("scroll"));
+    };
+    const snapshot = () => ({
+        texts: botNodes(window).map((node) => node.contentText),
+        title: textOf(window, "runtimeChatCurrentTitle"),
+        loader: textOf(window, "runtimeChatLoadMore"),
+        scrollTop: log.scrollTop,
+    });
+    loadOlder();
+    await tick();
+    if (pending.length !== 1) throw new Error("first conversation did not request older history");
+    window.document.querySelector('[data-conversation-select="B"]').click();
+    await tick();
+    if (returnToSameConversation) {
+        window.document.querySelector('[data-conversation-select="A"]').click();
+        await tick();
+    }
+    await settle(1800);
+    loadOlder();
+    await tick();
+    if (pending.length !== 2) throw new Error("current view did not request older history");
+    const beforeLate = snapshot();
+    if (outcome === "failure") {
+        pending[0].reject(new Error("obsolete history page failure"));
+    } else {
+        pending[0].resolve(response(200, {
+            conversation_id: "A",
+            items: [{ role: "bot", content: "A-obsolete-page" }],
+            has_more: true,
+            next_before: 7,
+        }));
+    }
+    await tick();
+    const afterLate = snapshot();
+    loadOlder();
+    await tick();
+    const requestsWhileCurrentPagePending = pending.length;
+    const target = returnToSameConversation ? "A" : "B";
+    pending[1].resolve(response(200, {
+        conversation_id: target,
+        items: [{ role: "bot", content: `${target}-legitimate-older` }],
+        has_more: true,
+        next_before: 3,
+    }));
+    await tick();
+    const afterCurrentPage = snapshot();
+    loadOlder();
+    await tick();
+    return {
+        target,
+        beforeLate,
+        afterLate,
+        requestsWhileCurrentPagePending,
+        afterCurrentPage,
+        pageUrls: pending.map((request) => request.url),
+        toastText: textOf(window, "toast-container"),
+    };
+}
+
+for (const target of ["other", "same"]) {
+    for (const outcome of ["success", "failure"]) {
+        SCENARIOS[`stale_history_page_${target}_${outcome}`] = (env) =>
+            staleChatHistoryPage(env, target === "same", outcome);
+    }
+}
+
+async function staleLatestChatHistory(env, initialLoad, failure) {
+    const { window, setRoutes, response } = env;
+    setRoutes([
+        { match: "/chat/conversations", reply: { body: {
+            conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+            active_job: null,
+        } } },
+        { match: "/chat/jobs/active", reply: { body: { job: null } } },
+        { match: "/chat/history", reply: { body: {
+            items: [{ role: "bot", content: "initial history" }],
+            has_more: false, next_before: null,
+        } } },
+    ]);
+    const fetch = window.fetch;
+    const pending = [];
+    let deferA = initialLoad;
+    window.fetch = (url, options) => {
+        if (deferA && String(url).includes("/chat/history") && String(url).includes("conversation_id=A")) {
+            if (failure === "parse") {
+                return Promise.resolve({ ...response(200, {}),
+                    json: () => new Promise((resolve, reject) => pending.push({ resolve, reject })),
+                });
+            }
+            return new Promise((resolve, reject) => pending.push({ resolve, reject }));
+        }
+        return fetch(url, options);
+    };
+    window.RuntimeController.init();
+    if (initialLoad) {
+        window.__harness.setAuthenticated(true);
+        window.RuntimeController.onTabActivated("chat");
+        await tick();
+    } else {
+        await window.RuntimeController.loadChatHistory(true);
+        window.document.querySelector('[data-conversation-select="B"]').click();
+        await tick();
+        deferA = true;
+        window.document.querySelector('[data-conversation-select="A"]').click();
+        await tick();
+    }
+    window.document.querySelector('[data-conversation-select="B"]').click();
+    await tick();
+    window.document.querySelector('[data-conversation-select="A"]').click();
+    await tick();
+    if (pending.length !== 2) throw new Error(`expected two pending A latest reads, got ${pending.length}`);
+    const snapshot = () => ({
+        texts: botNodes(window).map((node) => node.contentText),
+        title: textOf(window, "runtimeChatCurrentTitle"),
+        toasts: window.document.querySelectorAll(".toast").length,
+        activeRequests: env.requests.filter((url) => url.includes("/chat/jobs/active")).length,
+    });
+    const beforeLate = snapshot();
+    pending[0].reject(new Error("obsolete latest history failure"));
+    await tick();
+    const afterLate = snapshot();
+    const body = { items: [{ role: "bot", content: "A-current-latest" }], has_more: false, next_before: null };
+    pending[1].resolve(failure === "parse" ? body : response(200, body));
+    await tick();
+    return { beforeLate, afterLate, afterCurrent: snapshot() };
+}
+
+for (const loading of ["initial", "forced"]) {
+    for (const failure of ["network", "parse"]) {
+        SCENARIOS[`stale_latest_history_${loading}_${failure}`] = (env) =>
+            staleLatestChatHistory(env, loading === "initial", failure);
+    }
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index c1b44834..bfa06bb4 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -288,6 +288,43 @@ def test_lazy_loading_older_history_keeps_viewport_position() -> None:
     assert result["lazyLoadScrollTop"] == result["lazyLoadExpectedTop"], result
 
 
+@pytest.mark.parametrize("target", ["other", "same"])
+@pytest.mark.parametrize("outcome", ["success", "failure"])
+def test_late_history_page_cannot_modify_current_view_or_its_loading_state(
+    target: str, outcome: str
+) -> None:
+    result = run_scenario(f"stale_history_page_{target}_{outcome}")
+
+    assert result["afterLate"] == result["beforeLate"], result
+    assert result["beforeLate"]["loader"], result
+    assert result["requestsWhileCurrentPagePending"] == 2, result
+    conversation_id = "A" if target == "same" else "B"
+    current_text = f"{conversation_id}-current-{2 if target == 'same' else 1}"
+    assert result["beforeLate"]["texts"] == [current_text], result
+    assert result["afterCurrentPage"]["texts"] == [
+        f"{conversation_id}-legitimate-older",
+        current_text,
+    ], result
+    assert result["afterCurrentPage"]["loader"] == "", result
+    assert len(result["pageUrls"]) == 3, result
+    assert f"conversation_id={conversation_id}" in result["pageUrls"][-1], result
+    assert "before=3" in result["pageUrls"][-1], result
+    assert "obsolete history page failure" not in result["toastText"], result
+
+
+@pytest.mark.parametrize("loading", ["initial", "forced"])
+@pytest.mark.parametrize("failure", ["network", "parse"])
+def test_late_latest_history_failure_cannot_trigger_current_view_recovery(
+    loading: str, failure: str
+) -> None:
+    result = run_scenario(f"stale_latest_history_{loading}_{failure}")
+
+    assert result["beforeLate"]["title"] == "A", result
+    assert result["afterLate"] == result["beforeLate"], result
+    assert result["afterCurrent"]["texts"] == ["A-current-latest"], result
+    assert result["afterCurrent"]["toasts"] == 0, result
+
+
 # --------------------------------------------------------------------------- #
 # 工具块：快照去重与自动折叠
 # --------------------------------------------------------------------------- #

From d785f34b72c27c721e7d29cdea8512328cb23e7a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:15:06 +0800
Subject: [PATCH 047/121] fix(jm): clean cancelled downloads after event loop
 shutdown

---
 docs/configuration.md          |  2 +-
 src/Undefined/jm/downloader.py | 13 ++++++------
 tests/test_jm_downloader.py    | 36 ++++++++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 146d5e6c..03155a73 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1158,7 +1158,7 @@ api_key = "replace-with-your-key"
 - 车号不存在、接口不可用时发送一行 `JM 提取失败：<原因>`，日志记录异常类型与堆栈；车号与链接混排时按原文顺序取第一个，分享卡片结构异常只跳过该段。
 - 除了自动提取，`jm_book` 工具让 AI 也能按需处理车号：`output_mode=send`（默认，等价自动提取）、`uid`（只下载并**把所有章节合成一份未加密 PDF** 注册为附件 UID，交给 `file_analysis_agent` 用 `extract_pdf` / `describe_pdf_page` 解析，不发送消息、不打包 zip）、`info`（只返回本子信息，不下载）。
 - `info_agent` 的 `jm_search` 工具查询本子列表，`mode` 三种：`search`（关键词检索，可用 `target` 限定站内/作品/作者/标签/角色，也可直接输入纯数字车号）、`browse`（按分类浏览，不需要关键词）与 `ranking`（日/周/月排行，用 `time_range` 选日榜/周榜/月榜，固定按观看数排序）。三种模式共用 `genre` 大分类、`page` 翻页与 `n`（默认 5、上限 20）；`search` / `browse` 另支持 `sort`（最新/观看/图片/点赞/评分/评论）与 `time_range` 时间范围；`sub_genre` 副分类必须与 `genre` 同时给出，且只有网页端接口支持，网页端被反爬拦截时会直接返回失败原因。只返回车号、标题、作者、分类与更新时间，不下载也不发送。查询复用同一份 `[jm]` 配置（代理、`request_timeout`、`session_dir`），且**不受** `auto_extract_enabled` 影响——该开关只约束自动提取管线。
-- jmcpy 的 HTTP 请求是异步的，但图片解码与 PDF 合成是同步 CPU 工作；这些步骤在线程中执行，不阻塞事件循环。副作用是单次自动提取不可取消，由 `request_timeout` / `image_timeout` 与 jmcpy 的多端点重试兜底。
+- 图片下载、解码与 PDF 合成在专用线程池执行，不阻塞事件循环。取消提取会结束等待，但不会强停仍在写盘的同步线程；线程结束后清理本次任务目录，即使 Bot 的事件循环已经关闭也会清理，避免残留原图或未加密 PDF。下载本身由 `request_timeout` / `image_timeout` 与 jmcpy 的多端点重试收敛。
 - 默认不登录即可使用；需要在 jmcpy 中登录（例如访问账号可见内容）时，用 jmcpy 自己的方式保存会话，再把 `session_dir` 指向同一配置目录，或在 `session_dir` 留空时设置 `JMCPY_HOME`。目录值会去除首尾空白，显式 `session_dir` 优先于环境变量。
 - 请遵守所在地法律法规与目标站点服务条款，只处理你有权获取的内容。
 
diff --git a/src/Undefined/jm/downloader.py b/src/Undefined/jm/downloader.py
index 487e53e2..f3fe3584 100644
--- a/src/Undefined/jm/downloader.py
+++ b/src/Undefined/jm/downloader.py
@@ -27,7 +27,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Iterator, Sequence
-from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import Future, ThreadPoolExecutor
 from dataclasses import dataclass, field
 import asyncio
 import functools
@@ -596,17 +596,18 @@ async def download_book(
         download = functools.partial(
             _download_archive_sync, book_id, task_dir, password=password, **options
         )
-    future: asyncio.Future[JmDownload] = loop.run_in_executor(_DOWNLOAD_POOL, download)
+    worker_future: Future[JmDownload] = _DOWNLOAD_POOL.submit(download)
+    future = asyncio.wrap_future(worker_future, loop=loop)
     try:
         # shield：协程被取消时不要把线程一起取消——同步下载停不下来，强行删目录
         # 只会被后续写入重新创建，所以等它跑完再清理
         result = await asyncio.shield(future)
     except BaseException:
-        if future.done():
+        if worker_future.done():
             # 异常路径下调用方拿不到 task_dir，必须在这里清掉已下载的原图
             await cleanup_download_dir(task_dir)
         else:
-            _cleanup_when_finished(future, task_dir, loop=loop)
+            _cleanup_when_finished(worker_future, task_dir, loop=loop)
         raise
     return result, task_dir
 
@@ -616,14 +617,14 @@ def _remove_dir_now(path: Path) -> None:
 
 
 def _cleanup_when_finished(
-    future: "asyncio.Future[JmDownload]",
+    future: Future[JmDownload],
     task_dir: Path,
     *,
     loop: asyncio.AbstractEventLoop,
 ) -> None:
     """线程仍在写盘时，等它结束后再删任务目录（取消/超时路径）。"""
 
-    def _on_done(_future: "asyncio.Future[JmDownload]") -> None:
+    def _on_done(_future: Future[JmDownload]) -> None:
         try:
             loop.run_in_executor(None, _remove_dir_now, task_dir)
         except RuntimeError:
diff --git a/tests/test_jm_downloader.py b/tests/test_jm_downloader.py
index 429de1f2..dff55fa3 100644
--- a/tests/test_jm_downloader.py
+++ b/tests/test_jm_downloader.py
@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor
 import re
+import threading
 from types import SimpleNamespace
 from typing import Any, Literal, TypeAlias
 import zipfile
@@ -956,3 +958,37 @@ def _slow(*_args: Any, **_kwargs: Any) -> Any:
             break
         await asyncio.sleep(0.05)
     assert list((tmp_path / "jm").glob("*")) == [], "取消后必须清掉任务目录"
+
+
+def test_cancelled_download_cleans_up_after_event_loop_closes(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    started = threading.Event()
+    release = threading.Event()
+    pool = ThreadPoolExecutor(max_workers=1)
+    monkeypatch.setattr(jm_downloader, "_DOWNLOAD_POOL", pool)
+
+    def download(book_id: str, task_dir: Path, **options: Any) -> Any:
+        started.set()
+        assert release.wait(5)
+        (task_dir / "raw-page.jpg").write_bytes(b"temporary original")
+        return SimpleNamespace()
+
+    monkeypatch.setattr(jm_downloader, "_download_plain_sync", download)
+
+    async def cancel_download() -> None:
+        task = asyncio.create_task(download_book("1114751", config=_config()))
+        assert await asyncio.to_thread(started.wait, 5)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert list((tmp_path / "jm").glob("*"))
+
+    try:
+        asyncio.run(cancel_download())
+        # 专用下载线程在 loop 关闭后才写入原图并完成。
+        release.set()
+    finally:
+        release.set()
+        pool.shutdown(wait=True)
+    assert list((tmp_path / "jm").glob("*")) == []

From 6bc41fd42702b27f50db3b4f2de9c1a1601808a6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:17:26 +0800
Subject: [PATCH 048/121] fix(chat): guard conversation history request
 ordering

---
 apps/undefined-chat/README.md                 |   2 +-
 .../src/chat-store/history-order.test.ts      | 179 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  38 +++-
 3 files changed, 214 insertions(+), 5 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/history-order.test.ts

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index 21a152c6..991aa5d1 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -7,7 +7,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 ## 当前能力
 
 - 会话管理：创建、删除、重命名、切换会话。当前没有置顶字段/API。
-- 消息历史：初始加载、cursor-based 加载更早消息、滚动锚点保持和长历史窗口化渲染。
+- 消息历史：初始加载、cursor-based 加载更早消息、滚动锚点保持和长历史窗口化渲染。同一会话的重载与分页共用请求顺序保护；发送新消息、完成任务刷新或删除会话后，迟到的旧响应不会覆盖正文、游标或加载状态。
 - 消息渲染：Markdown、表格、任务列表、引用块、代码高亮、代码块复制；正文 HTML 经 sanitize 内联渲染，HTML 代码块可在独立预览窗口中运行。
 - 附件：系统文件选择器、上传状态队列、Tauri 流式上传、下载和预览。当前显示上传中/成功/失败状态，不显示百分比进度。
 - 图片：正文 `<attachment uid/>` 内联图、附件缩略图、blob 缓存、全屏查看、缩放、旋转和可滚动查看区域。
diff --git a/apps/undefined-chat/src/chat-store/history-order.test.ts b/apps/undefined-chat/src/chat-store/history-order.test.ts
new file mode 100644
index 00000000..cf698203
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/history-order.test.ts
@@ -0,0 +1,179 @@
+import { describe, expect, test, vi } from "vitest";
+import type {
+	HistoryPageResponse,
+	HistoryResponse,
+} from "../runtime-client/types";
+import { historyItem, job, runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	let reject!: (reason: Error) => void;
+	const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+		resolve = resolvePromise;
+		reject = rejectPromise;
+	});
+	return { promise, resolve, reject };
+}
+
+function history(start: number, end: number, total = end): HistoryResponse {
+	return {
+		conversationId: "default",
+		virtualUserId: "webchat",
+		permission: "superadmin",
+		count: end - start,
+		items: Array.from({ length: end - start }, (_, index) =>
+			historyItem({
+				messageId: `message-${start + index}`,
+				content: `正文 ${start + index}`,
+			}),
+		),
+		limit: 50,
+		before: null,
+		hasMore: start > 0,
+		nextBefore: start > 0 ? start : null,
+		total,
+	};
+}
+
+describe("history request ordering within one Runtime", () => {
+	test("a late page cannot replace the final history after sending and cancelling a job", async () => {
+		const oldPage = deferred<HistoryPageResponse>();
+		const finalHistory = history(72, 122);
+		finalHistory.items.splice(
+			-2,
+			2,
+			historyItem({ messageId: "new-user", content: "新问题" }),
+			historyItem({
+				messageId: "new-bot",
+				role: "bot",
+				content: "新回复",
+			}),
+		);
+		const client = runtimeClientStub({
+			getHistory: vi
+				.fn()
+				.mockResolvedValueOnce(history(70, 120))
+				.mockResolvedValueOnce(finalHistory),
+			getHistoryPage: vi.fn(() => oldPage.promise),
+			cancelJob: vi.fn(async () =>
+				job({ status: "cancelled", historyFinalized: true }),
+			),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		const pendingPage = store.loadMoreHistory("default");
+		store.updateDraft("default", "新问题");
+		await store.sendSelectedMessage();
+		await store.cancelJob("job-1");
+		await vi.waitFor(() => {
+			expect(store.getSnapshot().historyByConversation.default.items).toEqual(
+				finalHistory.items,
+			);
+		});
+		oldPage.resolve({ ...history(20, 70, 120), before: 70, cursor: 20 });
+		await pendingPage;
+		expect(store.getSnapshot().historyByConversation.default).toEqual({
+			items: finalHistory.items,
+			hasMore: true,
+			nextBefore: 72,
+			total: 122,
+			loading: false,
+			error: null,
+		});
+	});
+
+	test.each(["success", "error"])(
+		"a superseded reload %s cannot replace a newer reload",
+		async (outcome) => {
+			const oldReload = deferred<HistoryResponse>();
+			const newer = history(72, 122);
+			const client = runtimeClientStub();
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			vi.mocked(client.getHistory)
+				.mockImplementationOnce(() => oldReload.promise)
+				.mockResolvedValueOnce(newer);
+			const pending = store.reloadHistory("default");
+			await store.reloadHistory("default");
+			if (outcome === "success") oldReload.resolve(history(70, 120));
+			else oldReload.reject(new Error("旧请求失败"));
+			await pending;
+			expect(store.getSnapshot().historyByConversation.default).toEqual({
+				items: newer.items,
+				hasMore: true,
+				nextBefore: 72,
+				total: 122,
+				loading: false,
+				error: null,
+			});
+		},
+	);
+
+	test("an old page error cannot clear a newer reload's loading state", async () => {
+		const page = deferred<HistoryPageResponse>();
+		const reload = deferred<HistoryResponse>();
+		const client = runtimeClientStub({
+			getHistory: vi.fn(async () => history(70, 120)),
+			getHistoryPage: vi.fn(() => page.promise),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		const pendingPage = store.loadMoreHistory("default");
+		vi.mocked(client.getHistory).mockImplementationOnce(() => reload.promise);
+		const pendingReload = store.reloadHistory("default");
+		page.reject(new Error("迟到分页错误"));
+		await pendingPage;
+		expect(store.getSnapshot().historyByConversation.default.loading).toBe(
+			true,
+		);
+		expect(store.getSnapshot().historyByConversation.default.error).toBeNull();
+		reload.resolve(history(72, 122));
+		await pendingReload;
+		expect(store.getSnapshot().historyByConversation.default.loading).toBe(
+			false,
+		);
+	});
+
+	test.each(["page", "reload"])(
+		"an in-flight %s cannot remove a newly sent optimistic message",
+		async (kind) => {
+			const response = deferred<HistoryPageResponse>();
+			const client = runtimeClientStub({
+				getHistory: vi.fn(async () => history(70, 120)),
+				getHistoryPage: vi.fn(() => response.promise),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			vi.mocked(client.getHistory).mockImplementationOnce(
+				() => response.promise,
+			);
+			const pending =
+				kind === "page"
+					? store.loadMoreHistory("default")
+					: store.reloadHistory("default");
+			store.updateDraft("default", "保留新问题");
+			await store.sendSelectedMessage();
+			response.resolve({ ...history(20, 70, 120), before: 70, cursor: 20 });
+			await pending;
+			const saved = store.getSnapshot().historyByConversation.default;
+			expect(saved.items.at(-1)?.content).toBe("保留新问题");
+			expect(saved.total).toBe(121);
+			expect(saved.nextBefore).toBe(70);
+			expect(saved.loading).toBe(false);
+		},
+	);
+
+	test("a pending history response cannot recreate a deleted conversation's history", async () => {
+		const response = deferred<HistoryResponse>();
+		const client = runtimeClientStub();
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		vi.mocked(client.getHistory).mockImplementationOnce(() => response.promise);
+		const pending = store.reloadHistory("default");
+		await store.deleteConversation("default");
+		response.resolve(history(70, 120));
+		await pending;
+		expect(store.getSnapshot().historyByConversation.default).toBeUndefined();
+	});
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index c466191d..e768f89a 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -678,6 +678,8 @@ export function createChatStore({
 	let runtimeSuspended = false;
 	const draftRevisionsByConversation = new Map<string, number>();
 	let draftRevision = 0;
+	const historyRequestsByConversation = new Map<string, number>();
+	let historyRequestGeneration = 0;
 	const listeners = new Set<() => void>();
 	const subscriptionsByJob = new Map<string, string>();
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
@@ -700,6 +702,14 @@ export function createChatStore({
 	}
 
 	function dispatch(action: ChatAction): void {
+		if (
+			action.type === "history/set" ||
+			action.type === "history/error" ||
+			action.type === "message/optimisticUser" ||
+			action.type === "conversation/remove"
+		) {
+			historyRequestsByConversation.delete(action.conversationId);
+		}
 		if (action.type === "draft/set") {
 			draftRevisionsByConversation.set(action.conversationId, ++draftRevision);
 		} else if (action.type === "conversation/remove") {
@@ -726,6 +736,7 @@ export function createChatStore({
 		fallbackTimersByJob.clear();
 		latestFallbackRequestByJob.clear();
 		fallbackBackoffByJob.clear();
+		historyRequestsByConversation.clear();
 	}
 
 	function resetRuntimeScope(nextUrl: string): void {
@@ -765,13 +776,14 @@ export function createChatStore({
 	async function loadHistory(conversationId: string): Promise<void> {
 		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
+		const request = beginHistoryRequest(conversationId);
 		dispatch({ type: "history/loading", conversationId });
 		try {
 			const history = await client.getHistory({
 				conversationId,
 				limit: HISTORY_LIMIT,
 			});
-			if (generation !== runtimeGeneration) return;
+			if (!isCurrentHistoryRequest(conversationId, generation, request)) return;
 			dispatch({
 				type: "history/set",
 				conversationId,
@@ -781,7 +793,7 @@ export function createChatStore({
 				total: history.total,
 			});
 		} catch (err) {
-			if (generation !== runtimeGeneration) return;
+			if (!isCurrentHistoryRequest(conversationId, generation, request)) return;
 			// 单会话历史加载失败降级为会话级错误，不升级为全局致命错误
 			dispatch({
 				type: "history/error",
@@ -791,6 +803,23 @@ export function createChatStore({
 		}
 	}
 
+	function beginHistoryRequest(conversationId: string): number {
+		const request = ++historyRequestGeneration;
+		historyRequestsByConversation.set(conversationId, request);
+		return request;
+	}
+
+	function isCurrentHistoryRequest(
+		conversationId: string,
+		generation: number,
+		request: number,
+	): boolean {
+		return (
+			generation === runtimeGeneration &&
+			historyRequestsByConversation.get(conversationId) === request
+		);
+	}
+
 	async function startStreamForJob(job: ChatJob): Promise<void> {
 		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
@@ -1709,6 +1738,7 @@ export function createChatStore({
 			return;
 		}
 
+		const request = beginHistoryRequest(conversationId);
 		dispatch({ type: "history/loading", conversationId });
 
 		try {
@@ -1717,7 +1747,7 @@ export function createChatStore({
 				historyState.nextBefore ?? undefined,
 				HISTORY_LIMIT,
 			);
-			if (generation !== runtimeGeneration) return;
+			if (!isCurrentHistoryRequest(conversationId, generation, request)) return;
 
 			const newItems = [...response.items, ...historyState.items];
 
@@ -1730,7 +1760,7 @@ export function createChatStore({
 				total: response.total,
 			});
 		} catch (error) {
-			if (generation !== runtimeGeneration) return;
+			if (!isCurrentHistoryRequest(conversationId, generation, request)) return;
 			dispatch({
 				type: "history/error",
 				conversationId,

From d38ecc0d8b9b3a8de8477724581b3a5c76f552a2 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:20:34 +0800
Subject: [PATCH 049/121] fix(chat): render failed code highlighting as plain
 text

---
 apps/undefined-chat/README.md                 |  2 +-
 .../src/rendering/CodeBlock.test.tsx          | 38 +++++++++++++++++++
 .../src/rendering/CodeBlock.tsx               | 15 ++++++--
 .../src/rendering/MarkdownContent.test.tsx    | 13 +++++++
 4 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index 991aa5d1..d256f0da 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -8,7 +8,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 
 - 会话管理：创建、删除、重命名、切换会话。当前没有置顶字段/API。
 - 消息历史：初始加载、cursor-based 加载更早消息、滚动锚点保持和长历史窗口化渲染。同一会话的重载与分页共用请求顺序保护；发送新消息、完成任务刷新或删除会话后，迟到的旧响应不会覆盖正文、游标或加载状态。
-- 消息渲染：Markdown、表格、任务列表、引用块、代码高亮、代码块复制；正文 HTML 经 sanitize 内联渲染，HTML 代码块可在独立预览窗口中运行。
+- 消息渲染：Markdown、表格、任务列表、引用块、代码高亮、代码块复制；未知语言或高亮失败时保留为纯文本代码，代码中的 HTML 不会插入正文。正文 HTML 经 sanitize 内联渲染，HTML 代码块可在独立预览窗口中运行。
 - 附件：系统文件选择器、上传状态队列、Tauri 流式上传、下载和预览。当前显示上传中/成功/失败状态，不显示百分比进度。
 - 图片：正文 `<attachment uid/>` 内联图、附件缩略图、blob 缓存、全屏查看、缩放、旋转和可滚动查看区域。
 - 命令：斜杠命令、子命令提示、方向键导航、Tab/Enter 补全；空态反馈（加载中/无匹配/不可用）；窗口聚焦按 TTL 刷新命令列表。
diff --git a/apps/undefined-chat/src/rendering/CodeBlock.test.tsx b/apps/undefined-chat/src/rendering/CodeBlock.test.tsx
index fff133fb..25e98b14 100644
--- a/apps/undefined-chat/src/rendering/CodeBlock.test.tsx
+++ b/apps/undefined-chat/src/rendering/CodeBlock.test.tsx
@@ -1,5 +1,6 @@
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import hljs from "highlight.js";
 import type { ReactElement } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { LanguageProvider, LOCALE_STORAGE_KEY } from "../i18n";
@@ -30,6 +31,7 @@ describe("CodeBlock", () => {
 
 	afterEach(() => {
 		vi.clearAllMocks();
+		vi.restoreAllMocks();
 	});
 
 	it("应该渲染代码块", () => {
@@ -190,6 +192,42 @@ describe("CodeBlock", () => {
 		}).not.toThrow();
 	});
 
+	it.each(["notalanguage", "vue"])(
+		"未知语言 %s 的 HTML 保持为可复制的代码文本",
+		async (language) => {
+			const code =
+				'<style>body { color: red; }</style>\n<form id="injected"><input name="password"></form>\n& <script>alert("x")</script>';
+			const { container } = renderCodeBlock(
+				<CodeBlock code={code} language={language} />,
+			);
+			expect(container.querySelector("code")?.textContent).toBe(code);
+			expect(container.querySelector("style, form, input, script")).toBeNull();
+			expect(screen.getByText("plaintext")).toBeInTheDocument();
+			fireEvent.click(screen.getByText("复制"));
+			await waitFor(() => expect(mockWriteText).toHaveBeenCalledWith(code));
+		},
+	);
+
+	it.each(["highlight", "highlightAuto"] as const)(
+		"%s 抛出异常时 HTML 同样保持为文本",
+		(method) => {
+			vi.spyOn(hljs, method).mockImplementation(() => {
+				throw new Error("受控高亮异常");
+			});
+			vi.spyOn(console, "error").mockImplementation(() => undefined);
+			const code =
+				'<style>body { display: none; }</style><form id="injected" />';
+			const { container } = renderCodeBlock(
+				<CodeBlock
+					code={code}
+					language={method === "highlight" ? "html" : undefined}
+				/>,
+			);
+			expect(container.querySelector("code")?.textContent).toBe(code);
+			expect(container.querySelector("style, form")).toBeNull();
+		},
+	);
+
 	it("应该正确渲染空代码", () => {
 		const code = "";
 		renderCodeBlock(<CodeBlock code={code} language="javascript" />);
diff --git a/apps/undefined-chat/src/rendering/CodeBlock.tsx b/apps/undefined-chat/src/rendering/CodeBlock.tsx
index 53d66edf..5c1bb41c 100644
--- a/apps/undefined-chat/src/rendering/CodeBlock.tsx
+++ b/apps/undefined-chat/src/rendering/CodeBlock.tsx
@@ -39,6 +39,9 @@ export function CodeBlock({
 				// htm 别名映射到 html
 				const normalizedLanguage =
 					language.toLowerCase() === "htm" ? "html" : language;
+				if (!hljs.getLanguage(normalizedLanguage)) {
+					return { highlightedCode: null, detectedLanguage: "plaintext" };
+				}
 				// 指定了语言，尝试使用指定语言高亮
 				const result = hljs.highlight(trimmedCode, {
 					language: normalizedLanguage,
@@ -58,7 +61,7 @@ export function CodeBlock({
 		} catch (err) {
 			console.error("Highlight error:", err);
 			return {
-				highlightedCode: trimmedCode,
+				highlightedCode: null,
 				detectedLanguage: "plaintext",
 			};
 		}
@@ -141,9 +144,13 @@ export function CodeBlock({
 				<pre>
 					<code
 						className={`hljs ${showLineNumbers ? "line-numbers" : ""}`}
-						// highlight.js output is sanitized.
-						dangerouslySetInnerHTML={{ __html: highlightedCode }}
-					/>
+						// Only highlighter output is HTML; fallback code is rendered as text.
+						dangerouslySetInnerHTML={
+							highlightedCode === null ? undefined : { __html: highlightedCode }
+						}
+					>
+						{highlightedCode === null ? code.trim() : undefined}
+					</code>
 				</pre>
 			</div>
 		</div>
diff --git a/apps/undefined-chat/src/rendering/MarkdownContent.test.tsx b/apps/undefined-chat/src/rendering/MarkdownContent.test.tsx
index 94a56570..b1ab04da 100644
--- a/apps/undefined-chat/src/rendering/MarkdownContent.test.tsx
+++ b/apps/undefined-chat/src/rendering/MarkdownContent.test.tsx
@@ -198,6 +198,19 @@ describe("MarkdownContent", () => {
 		expect(screen.getByText("复制")).toBeInTheDocument();
 	});
 
+	it("未知 fenced-code 语言不会将代码里的 HTML 插入正文", () => {
+		const code =
+			'<style>body { color: red; }</style>\n<form id="injected"><input name="password"></form>';
+		const { container } = render(
+			<MarkdownContent
+				content={`段落\n\n\`\`\`notalanguage\n${code}\n\`\`\``}
+				onPreviewHtml={mockOnPreviewHtml}
+			/>,
+		);
+		expect(container.querySelector("code")?.textContent).toBe(code);
+		expect(container.querySelector("style, form, input")).toBeNull();
+	});
+
 	it("渲染混合内容", () => {
 		const mixedContent = `# 标题
 

From 0ebaac5753e059f082f4950a169b632f329e8357 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:20:52 +0800
Subject: [PATCH 050/121] fix(webui): ignore stale active job recovery
 responses

---
 docs/webui-guide.md                       |  1 +
 src/Undefined/webui/static/js/runtime.js  | 30 +++++++
 tests/frontend/runtime_chat_harness.js    | 97 +++++++++++++++++++++++
 tests/test_webui_runtime_chat_behavior.py | 20 +++++
 4 files changed, 148 insertions(+)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index f2e5cb84..2049262e 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -163,6 +163,7 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - 切换会话或离开后重新进入同一会话时，上一页面的迟到历史响应会被忽略，不会混入当前历史、覆盖分页游标或清除当前正在加载的状态；旧请求的网络失败也不会给当前会话显示错误或打断其加载。后续分页继续使用当前会话返回的游标。
 - 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 `conversation_id + job_id + seq` 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；`done` / `error` / `cancelled` 终态先到时仍保留 job 和发送锁，并继续轮询等待 `history_finalized=true`；确认后端收尾完成后刷新权威历史，刷新成功才解除发送锁；历史慢响应或刷新失败期间继续保留锁，并通过原轮询重试恢复。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
 - 切换对话后再发起新任务时，迟到的旧任务轮询响应不会覆盖新回复、改变新任务的发送锁和取消按钮，或打断新任务续接；旧请求的失败提示也不会影响当前任务。
+- 查询运行中任务的恢复请求同样绑定发起时的会话和任务身份；切换会话、返回原会话或建立新任务后，旧恢复请求的迟到回包与失败重试不会改变当前会话正文、任务状态或发送锁。
 - 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口，等待历史收尾完成后解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 `reuse_previous_user_message=true` 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
 - 运行中的 AI 气泡会在 `AI` 标签后实时显示当前阶段和后端计算的总已用时，例如构建上下文、查长期记忆、查认知记忆、等待模型、等待工具、发送消息；任务完成后该位置显示本轮回复总用时。工具 / Agent 摘要行会在名称旁显示调用耗时，运行中先显示后端快照时间，轮询间隙用本地时间临时递增，下一次查询后自动校准；结束后固定显示后端结束事件的总耗时。轮询刷新只更新已有状态和计时节点，结构未变化时不会重建工具 / Agent 块，避免运行中闪烁。状态条区分运行中、成功和失败；整轮回复总耗时会写入 WebChat 历史 metadata。
 - WebChat job 事件会更新同一个 AI 气泡；AI 正文和主对话工具 / Agent 调用按事件时序显示，例如工具调用、正文回复、结束工具会依次出现在同一气泡内。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index 271288ee..398ef492 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -43,6 +43,7 @@
         chatClockTimer: null,
         activeJobResumeTimer: null,
         activeJobResumeAttempts: 0,
+        activeJobResumeRequest: null,
         toolBlocks: new Map(),
         toolCollapseTimers: new Map(),
         chatAttachments: [],
@@ -5059,6 +5060,9 @@
     }
 
     function resetChatConversationState() {
+        stopActiveJobResumeTimer();
+        runtimeState.activeJobResumeAttempts = 0;
+        runtimeState.activeJobResumeRequest = null;
         runtimeState.chatHistoryLoaded = false;
         runtimeState.chatHistoryCursor = null;
         runtimeState.chatHistoryHasMore = false;
@@ -5535,6 +5539,9 @@
     }
 
     async function attachChatJob(jobId, after = 0) {
+        runtimeState.activeJobResumeRequest = null;
+        stopActiveJobResumeTimer();
+        runtimeState.activeJobResumeAttempts = 0;
         stopChatPolling();
         runtimeState.activeJobId = jobId;
         runtimeState.activeJobConversationId =
@@ -5548,6 +5555,14 @@
         pollChatJob(jobId).catch(() => {});
     }
 
+    function isCurrentActiveJobResumeRequest(request) {
+        return (
+            runtimeState.activeJobResumeRequest === request &&
+            request.conversationId === currentChatConversationId() &&
+            request.jobId === String(runtimeState.activeJobId || "")
+        );
+    }
+
     async function resumeActiveChatJob() {
         const localJobId = runtimeState.activeJobId
             ? String(runtimeState.activeJobId)
@@ -5562,10 +5577,16 @@
         ) {
             return;
         }
+        const request = {
+            conversationId: currentChatConversationId(),
+            jobId: localJobId,
+        };
+        runtimeState.activeJobResumeRequest = request;
         try {
             const data = await fetchJsonOrThrow(
                 chatUrl("/api/runtime/chat/jobs/active"),
             );
+            if (!isCurrentActiveJobResumeRequest(request)) return;
             const job = data && data.job ? data.job : null;
             if (!job || !job.job_id) {
                 stopActiveJobResumeTimer();
@@ -5574,6 +5595,7 @@
                     stopChatPolling();
                     stopChatClock();
                     runtimeState.activeJobId = null;
+                    request.jobId = "";
                     runtimeState.activeJobConversationId = "";
                     runtimeState.chatBusy = false;
                     setButtonLoading(get("btnRuntimeChatSend"), false);
@@ -5585,6 +5607,12 @@
                 }
                 return;
             }
+            if (
+                job.conversation_id &&
+                String(job.conversation_id) !== request.conversationId
+            ) {
+                return;
+            }
             stopActiveJobResumeTimer();
             runtimeState.activeJobResumeAttempts = 0;
             const jobId = String(job.job_id);
@@ -5608,6 +5636,7 @@
             ensureStreamingMessage(jobId);
             attachChatJob(jobId, runtimeState.lastEventSeq).catch(() => {});
         } catch (_error) {
+            if (!isCurrentActiveJobResumeRequest(request)) return;
             runtimeState.activeJobResumeAttempts += 1;
             if (
                 runtimeState.activeJobResumeAttempts >
@@ -5622,6 +5651,7 @@
             );
             stopActiveJobResumeTimer();
             runtimeState.activeJobResumeTimer = setTimeout(() => {
+                if (!isCurrentActiveJobResumeRequest(request)) return;
                 resumeActiveChatJob().catch(() => {});
             }, delay);
         }
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index dfc3a348..b5a2d507 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3188,6 +3188,103 @@ for (const loading of ["initial", "forced"]) {
     }
 }
 
+async function staleActiveJobResume(env, returnToSameConversation, outcome) {
+    const { window, setRoutes, response } = env;
+    const currentJob = {
+        job_id: "current-A", conversation_id: "A", status: "running",
+    };
+    setRoutes([
+        {
+            match: "/chat/conversations",
+            reply: { body: {
+                conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+                active_job: null,
+            } },
+        },
+        {
+            match: "/chat/history",
+            reply: (url) => ({ body: {
+                items: [{ role: "bot", content: url.includes("conversation_id=B") ? "B-history" : "A-history" }],
+                has_more: false, next_before: null,
+            } }),
+        },
+        {
+            match: "/chat/jobs/active",
+            reply: (url) => ({ body: {
+                job: returnToSameConversation && url.includes("conversation_id=A") ? currentJob : null,
+            } }),
+        },
+        {
+            match: "/jobs/current-A/events",
+            reply: (url) => {
+                const after = Number(new URL(url, window.location.href).searchParams.get("after"));
+                return { body: { job: currentJob, events: [
+                    { seq: 1, event: "meta", payload: currentJob },
+                    { seq: 2, event: "message", payload: { ...currentJob, content: "current-live" } },
+                ].filter((event) => event.seq > after) } };
+            },
+        },
+        {
+            match: "/jobs/obsolete-A/events",
+            reply: { body: { job: { job_id: "obsolete-A", conversation_id: "A", status: "running" }, events: [] } },
+        },
+    ]);
+    const fetch = window.fetch;
+    let pending;
+    const resumeUrls = [];
+    window.fetch = (url, options) => {
+        if (String(url).includes("/chat/jobs/active")) {
+            resumeUrls.push(String(url));
+            if (!pending && String(url).includes("conversation_id=A")) {
+                return new Promise((resolve, reject) => { pending = { resolve, reject }; });
+            }
+        }
+        return fetch(url, options);
+    };
+    window.RuntimeController.init();
+    const initialLoad = window.RuntimeController.loadChatHistory(true);
+    await tick();
+    if (!pending) throw new Error("initial A resume request was not dispatched");
+    window.document.querySelector('[data-conversation-select="B"]').click();
+    await tick();
+    if (returnToSameConversation) {
+        window.document.querySelector('[data-conversation-select="A"]').click();
+        await tick();
+    }
+    const snapshot = () => ({
+        title: textOf(window, "runtimeChatCurrentTitle"),
+        nodes: chatNodes(window).map((node) => ({ text: node.contentText, job: node.jobId })),
+        disabled: window.document.getElementById("btnRuntimeChatSend").disabled,
+        cancelIds: Array.from(window.document.querySelectorAll("[data-cancel-job]"))
+            .filter((element) => !element.hidden).map((element) => element.dataset.cancelJob),
+    });
+    const beforeLate = snapshot();
+    const resumeCountBeforeLate = resumeUrls.length;
+    if (outcome === "failure") {
+        pending.reject(new Error("obsolete resume failure"));
+    } else {
+        pending.resolve(response(200, {
+            job: outcome === "empty" ? null : { job_id: "obsolete-A", conversation_id: "A", status: "running" },
+        }));
+    }
+    await initialLoad;
+    await tick();
+    const afterLate = snapshot();
+    if (outcome === "failure") await settle(1100);
+    return {
+        beforeLate, afterLate, afterRetryWindow: snapshot(),
+        resumeCountBeforeLate, resumeCountAfterLate: resumeUrls.length,
+        obsoletePolls: env.requests.filter((url) => url.includes("/jobs/obsolete-A/events")),
+    };
+}
+
+for (const target of ["other", "same"]) {
+    for (const outcome of ["running", "empty", "failure"]) {
+        SCENARIOS[`stale_active_job_resume_${target}_${outcome}`] = (env) =>
+            staleActiveJobResume(env, target === "same", outcome);
+    }
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index bfa06bb4..d9092e22 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -693,6 +693,26 @@ def test_auto_scroll_toggle_persists_preference() -> None:
 # --------------------------------------------------------------------------- #
 
 
+@pytest.mark.parametrize("target", ["other", "same"])
+@pytest.mark.parametrize("outcome", ["running", "empty", "failure"])
+def test_late_active_job_resume_cannot_replace_current_conversation_or_job(
+    target: str, outcome: str
+) -> None:
+    result = run_scenario(f"stale_active_job_resume_{target}_{outcome}")
+
+    before = result["beforeLate"]
+    assert before["title"] == ("A" if target == "same" else "B"), result
+    assert before["nodes"][0]["text"] == (
+        "A-history" if target == "same" else "B-history"
+    ), result
+    assert before["disabled"] is (target == "same"), result
+    assert before["cancelIds"] == (["current-A"] if target == "same" else []), result
+    assert result["afterLate"] == before, result
+    assert result["afterRetryWindow"] == before, result
+    assert result["resumeCountAfterLate"] == result["resumeCountBeforeLate"], result
+    assert result["obsoletePolls"] == [], result
+
+
 @pytest.mark.parametrize("outcome", ["events", "done", "failure"])
 def test_late_old_job_poll_cannot_replace_or_stop_new_job(outcome: str) -> None:
     result = run_scenario(f"stale_job_poll_{outcome}")

From 56a53b8261add658574910f7be853d2ed327faa4 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:22:02 +0800
Subject: [PATCH 051/121] fix(api): close chat admission and roll back failed
 job creation

---
 docs/openapi.md                     |   1 +
 src/Undefined/api/routes/chat.py    |  71 ++++++----
 src/Undefined/api/webchat_store.py  |  14 +-
 tests/test_runtime_api_chat_jobs.py | 196 ++++++++++++++++++++++++++++
 4 files changed, 255 insertions(+), 27 deletions(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index febb77dc..72f54437 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -523,6 +523,7 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 
 - `POST /api/v1/chat/jobs`：创建后台 job。兼容旧 Body `{"message":"...","conversation_id":"..."}`，也支持结构化 Body `{"message":{"text":"...","attachment_ids":["..."],"references":[{"message_id":"...","quote":"..."}]},"conversation_id":"..."}`；`conversation_id` 可选。取消后重试最后一条纯文本用户消息时，可传 `reuse_previous_user_message: true`，Runtime 会要求最后一条可见用户历史与本次文本完全一致，并跳过重复写入用户历史。
 - WebChat job 在同一会话内 single-flight；如果目标会话已有 job 正在运行或收尾落盘，创建新 job 返回 `409`。不同会话可以并发运行。兼容的非流式 `POST /api/v1/chat` 也走同一套会话级 job 锁，只是等待完成后返回同步结果。
+- Runtime 开始停止后，新的 job 和同步／SSE 聊天请求返回 `503`；此前已进入创建阶段的历史写入会先收敛，再取消并收尾其任务。结构化消息的历史预写失败时会撤销未启动的 job，缓存与磁盘均不追加失败消息，存储恢复后可以正常重试。若取消发生在历史原子写入已提交之后，该条用户历史会保留，但不会遗留未启动的 active job。
 - 附件先通过 `POST /api/v1/chat/attachments` 以 multipart 上传并由 Runtime 返回附件 metadata；发送消息时只传 Runtime 生成的 `attachment_ids`。客户端不应把本地文件内容、下载 URL 或临时缓存路径拼入 `message.text`。
 - 引用内容通过结构化 `references` 提交。Runtime 负责把引用写入历史 metadata，并按需要生成 AI 可见上下文；客户端不把引用块拼接进最终历史作为真源。
 - `GET /api/v1/chat/jobs/active?conversation_id=<id>`：返回兼容字段 `job` 和 active `jobs[]`。不传时 `jobs[]` 包含所有运行中 WebChat job，`job` 为最新 active job；传入 `conversation_id` 时只返回目标会话的 active job。
diff --git a/src/Undefined/api/routes/chat.py b/src/Undefined/api/routes/chat.py
index abc3efd6..382811b3 100644
--- a/src/Undefined/api/routes/chat.py
+++ b/src/Undefined/api/routes/chat.py
@@ -379,14 +379,23 @@ def current_tool_call_snapshots(
         return payloads
 
 
+class ChatJobManagerClosingError(RuntimeError):
+    """Runtime 正在收尾，不能接受新的聊天任务。"""
+
+
 class ChatJobManager:
     def __init__(self, ctx: RuntimeAPIContext) -> None:
         self._ctx = ctx
         self._jobs: dict[str, ChatJob] = {}
         self._lock = asyncio.Lock()
+        self._closing = False
         self._title_schedule_lock = asyncio.Lock()
         self.conversation_store = WebChatConversationStore()
 
+    def begin_shutdown(self) -> None:
+        """立即关闭任务创建入口，已有任务由 stop 收尾。"""
+        self._closing = True
+
     async def create_job(
         self,
         text: str,
@@ -397,6 +406,8 @@ async def create_job(
         pre_record_user_history: bool = False,
         reuse_previous_user_history: bool = False,
     ) -> ChatJob:
+        if self._closing:
+            raise ChatJobManagerClosingError("Chat service is stopping")
         await self.conversation_store.ensure_ready(self._ctx.history_manager)
         requested_conversation_id = str(conversation_id or "").strip()
         resolved_conversation_id = requested_conversation_id or _DEFAULT_CONVERSATION_ID
@@ -421,6 +432,8 @@ async def create_job(
             or reuse_previous_user_history,
         )
         async with self._lock:
+            if self._closing:
+                raise ChatJobManagerClosingError("Chat service is stopping")
             if any(
                 self._job_blocks_history_mutation(existing)
                 for existing in self._jobs.values()
@@ -428,37 +441,45 @@ async def create_job(
             ):
                 raise RuntimeError("Chat job is still running")
             self._jobs[job.job_id] = job
-        if pre_record_user_history:
-            await self.conversation_store.append_message(
-                resolved_conversation_id,
-                role="user",
-                text_content=text,
-                display_name=_VIRTUAL_USER_NAME,
-                user_name=_VIRTUAL_USER_NAME,
-                attachments=job.user_history_attachments or None,
-                references=job.user_history_references or None,
-            )
+            try:
+                # stop 必须等创建阶段收敛后再快照，避免漏掉稍后才启动的 task。
+                if pre_record_user_history:
+                    await self.conversation_store.append_message(
+                        resolved_conversation_id,
+                        role="user",
+                        text_content=text,
+                        display_name=_VIRTUAL_USER_NAME,
+                        user_name=_VIRTUAL_USER_NAME,
+                        attachments=job.user_history_attachments or None,
+                        references=job.user_history_references or None,
+                    )
+                await self._append_event(
+                    job,
+                    "meta",
+                    {
+                        "job_id": job.job_id,
+                        "conversation_id": job.conversation_id,
+                        "virtual_user_id": _VIRTUAL_USER_ID,
+                        "permission": "superadmin",
+                    },
+                )
+                await self._append_stage(job, "received")
+                job.task = asyncio.create_task(
+                    self._run_job(job), name=f"webchat:{job.job_id}"
+                )
+            except BaseException:
+                self._jobs.pop(job.job_id, None)
+                raise
         logger.info(
             "[RuntimeAPI][WebChat] 创建 job: job_id=%s conversation_id=%s text_len=%s",
             job.job_id,
             job.conversation_id,
             len(text),
         )
-        await self._append_event(
-            job,
-            "meta",
-            {
-                "job_id": job.job_id,
-                "conversation_id": job.conversation_id,
-                "virtual_user_id": _VIRTUAL_USER_ID,
-                "permission": "superadmin",
-            },
-        )
-        await self._append_stage(job, "received")
-        job.task = asyncio.create_task(self._run_job(job), name=f"webchat:{job.job_id}")
         return job
 
     async def stop(self) -> None:
+        self.begin_shutdown()
         async with self._lock:
             jobs = list(self._jobs.values())
         for job in jobs:
@@ -2956,6 +2977,8 @@ async def chat_handler(
             job = await job_manager.create_job(text, conversation_id)
         except KeyError:
             return _json_error("Conversation not found", status=404)
+        except ChatJobManagerClosingError as exc:
+            return _json_error(str(exc), status=503)
         except RuntimeError:
             return _json_error("Chat job is still running", status=409)
         try:
@@ -2989,6 +3012,8 @@ async def chat_handler(
         job = await job_manager.create_job(text, conversation_id)
     except KeyError:
         return _json_error("Conversation not found", status=404)
+    except ChatJobManagerClosingError as exc:
+        return _json_error(str(exc), status=503)
     except RuntimeError:
         return _json_error("Chat job is still running", status=409)
     logger.info(
@@ -3106,6 +3131,8 @@ async def chat_job_create_handler(
         return _json_error("Attachment not found", status=404)
     except ValueError as exc:
         return _json_error(str(exc), status=400)
+    except ChatJobManagerClosingError as exc:
+        return _json_error(str(exc), status=503)
     except RuntimeError:
         return _json_error("Chat job is still running", status=409)
     logger.info(
diff --git a/src/Undefined/api/webchat_store.py b/src/Undefined/api/webchat_store.py
index 366313ca..b1a44381 100644
--- a/src/Undefined/api/webchat_store.py
+++ b/src/Undefined/api/webchat_store.py
@@ -257,7 +257,7 @@ async def append_message(
     ) -> dict[str, Any]:
         conv_id = _normalize_conversation_id(conversation_id)
         async with self._get_lock(conv_id):
-            conv = self._require_conversation_locked(conv_id)
+            conv = _copy_json(self._require_conversation_locked(conv_id))
             timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
             normalized_role = "bot" if role == "bot" else "user"
             record: dict[str, Any] = {
@@ -554,10 +554,14 @@ def _require_conversation_locked(self, conversation_id: str) -> dict[str, Any]:
 
     async def _save_conversation_locked(self, conv: dict[str, Any]) -> None:
         normalized = _normalize_conversation(conv, str(conv.get("id") or uuid4().hex))
-        self._cache[str(normalized["id"])] = normalized
-        await io.write_json(
-            self._path_for(str(normalized["id"])), normalized, use_lock=True
-        )
+
+        async def commit() -> None:
+            await io.write_json(
+                self._path_for(str(normalized["id"])), normalized, use_lock=True
+            )
+            self._cache[str(normalized["id"])] = normalized
+
+        await io.run_cancellation_safe(commit())
 
     def _conversation_summary(self, conv: dict[str, Any]) -> dict[str, Any]:
         messages = _messages(conv)
diff --git a/tests/test_runtime_api_chat_jobs.py b/tests/test_runtime_api_chat_jobs.py
index 5ebac482..5ffaf36b 100644
--- a/tests/test_runtime_api_chat_jobs.py
+++ b/tests/test_runtime_api_chat_jobs.py
@@ -3,6 +3,7 @@
 import asyncio
 import hashlib
 import json
+import threading
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, cast
@@ -977,6 +978,201 @@ async def test_chat_job_cancelled_error_event_is_appended_once() -> None:
     assert len(cancelled_events) == 1
 
 
+@pytest.mark.asyncio
+async def test_chat_job_history_write_failure_rolls_back_creation_and_cache(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    await manager.conversation_store.ensure_ready()
+    conversation = await manager.conversation_store.ensure_default_conversation()
+    conversation_id = str(conversation["id"])
+    history_path = manager.conversation_store._path_for(conversation_id)
+    original_disk = history_path.read_bytes()
+    original_write = async_io.write_json_sync
+    fail_once = True
+
+    def write_json(file_path: Path | str, data: Any, use_lock: bool = True) -> None:
+        nonlocal fail_once
+        if Path(file_path) == history_path and data.get("messages") and fail_once:
+            fail_once = False
+            raise OSError("history disk unavailable")
+        original_write(file_path, data, use_lock)
+
+    run_chat = AsyncMock(return_value="chat")
+    monkeypatch.setattr(async_io, "write_json_sync", write_json)
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_chat)
+
+    def request() -> web.Request:
+        return cast(
+            web.Request,
+            cast(
+                Any,
+                _DummyRequest(
+                    _json={
+                        "conversation_id": conversation_id,
+                        "message": {"text": "hello"},
+                    }
+                ),
+            ),
+        )
+
+    with pytest.raises(OSError, match="history disk unavailable"):
+        await server._chat_job_create_handler(request())
+
+    assert not manager._jobs
+    assert await manager.get_active_job(conversation_id) is None
+    page = await manager.conversation_store.get_history_page(
+        conversation_id, limit=50, before=None
+    )
+    assert page.total == 0
+    assert history_path.read_bytes() == original_disk
+    run_chat.assert_not_awaited()
+
+    retry = await server._chat_job_create_handler(request())
+    assert retry.status == 202
+    job = await manager.get_job(str(json.loads(retry.text or "{}")["job_id"]))
+    assert job is not None and job.task is not None
+    await asyncio.wait_for(job.task, timeout=2)
+    page = await manager.conversation_store.get_history_page(
+        conversation_id, limit=50, before=None
+    )
+    assert [record["message"] for record in page.records] == ["hello"]
+    assert len(json.loads(history_path.read_text(encoding="utf-8"))["messages"]) == 1
+    assert await manager.clear_history_when_idle(conversation_id) == 1
+    await server.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("endpoint", ["job", "sync", "sse"])
+async def test_chat_stop_rejects_new_jobs_while_existing_job_finishes(
+    endpoint: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    started = asyncio.Event()
+    cancelling = asyncio.Event()
+    release = asyncio.Event()
+    calls: list[str] = []
+
+    async def run_chat(_ctx: Any, *, text: str, **_kwargs: Any) -> str:
+        calls.append(text)
+        started.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelling.set()
+            await release.wait()
+        return "chat"
+
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_chat)
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    job = await manager.create_job("old")
+    other = await manager.conversation_store.create_conversation()
+    await asyncio.wait_for(started.wait(), timeout=2)
+    stopping = asyncio.create_task(server.stop())
+    try:
+        await asyncio.wait_for(cancelling.wait(), timeout=2)
+        body: dict[str, Any] = {
+            "conversation_id": str(other["id"]),
+            "message": {"text": "new"} if endpoint == "job" else "new",
+            "stream": endpoint == "sse",
+        }
+        request = cast(web.Request, cast(Any, _DummyRequest(_json=body)))
+        response: web.StreamResponse
+        if endpoint == "job":
+            response = await server._chat_job_create_handler(request)
+        else:
+            response = await server._chat_handler(request)
+        assert response.status == 503
+        assert len(manager._jobs) == 1
+        assert calls == ["old"]
+        release.set()
+        await asyncio.wait_for(stopping, timeout=2)
+        assert job.status == "cancelled"
+        assert job.done.is_set()
+        assert not await manager.has_running_job()
+        with pytest.raises(runtime_api_chat.ChatJobManagerClosingError):
+            await manager.create_job("after stop")
+    finally:
+        release.set()
+        await stopping
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_creation", [False, True])
+async def test_chat_stop_waits_for_in_progress_history_write(
+    cancel_creation: bool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    started = threading.Event()
+    release = threading.Event()
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    await manager.conversation_store.ensure_ready()
+    conversation = await manager.conversation_store.ensure_default_conversation()
+    conversation_id = str(conversation["id"])
+    history_path = manager.conversation_store._path_for(conversation_id)
+    original_write = async_io.write_json_sync
+
+    def controlled_write(
+        file_path: Path | str, data: Any, use_lock: bool = True
+    ) -> None:
+        if Path(file_path) == history_path and data.get("messages"):
+            started.set()
+            if not release.wait(timeout=3):
+                raise TimeoutError("history write not released")
+        original_write(file_path, data, use_lock)
+
+    async def run_chat(_ctx: Any, **_kwargs: Any) -> str:
+        await asyncio.Event().wait()
+        return "chat"
+
+    monkeypatch.setattr(async_io, "write_json_sync", controlled_write)
+    run_mock = AsyncMock(side_effect=run_chat)
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_mock)
+    creation = asyncio.create_task(
+        manager.create_job("hello", conversation_id, pre_record_user_history=True)
+    )
+    stopping: asyncio.Task[None] | None = None
+    try:
+        assert await asyncio.wait_for(asyncio.to_thread(started.wait, 1), timeout=2)
+        stopping = asyncio.create_task(server.stop())
+        await asyncio.sleep(0)
+        assert manager._closing
+        with pytest.raises(runtime_api_chat.ChatJobManagerClosingError):
+            await manager.create_job("new")
+        if cancel_creation:
+            creation.cancel()
+            await asyncio.sleep(0)
+            assert not creation.done()
+        assert not stopping.done()
+        release.set()
+        if cancel_creation:
+            with pytest.raises(asyncio.CancelledError):
+                await creation
+            run_mock.assert_not_awaited()
+            assert not manager._jobs
+        else:
+            job = await creation
+            await asyncio.wait_for(stopping, timeout=2)
+            assert job.status == "cancelled"
+            assert job.done.is_set()
+            assert job.task is not None and job.task.done()
+        await asyncio.wait_for(stopping, timeout=2)
+        assert not await manager.has_running_job()
+        page = await manager.conversation_store.get_history_page(
+            conversation_id, limit=50, before=None
+        )
+        assert [record["message"] for record in page.records] == ["hello"]
+        assert (
+            len(json.loads(history_path.read_text(encoding="utf-8"))["messages"]) == 1
+        )
+    finally:
+        release.set()
+        await asyncio.gather(creation, return_exceptions=True)
+        if stopping is not None:
+            await stopping
+
+
 @pytest.mark.asyncio
 async def test_runtime_api_stop_cancels_running_webchat_job(
     monkeypatch: pytest.MonkeyPatch,

From 19b84f0f14f9072ced2bb8bea97d3b077f30a672 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:25:19 +0800
Subject: [PATCH 052/121] fix(runtime): drain accepted work before closing
 transports

---
 docs/deployment.md              |   2 +-
 src/Undefined/api/app.py        |  30 ++++++++-
 src/Undefined/main.py           |  88 ++++++++++++++++++-------
 src/Undefined/onebot/client.py  |  13 ++++
 src/Undefined/weixin/service.py |  27 ++++++++
 tests/test_main_shutdown.py     | 113 +++++++++++++++++++++++++++++++-
 tests/test_onebot_file_urls.py  |  56 ++++++++++++++++
 tests/test_weixin_service.py    |  57 ++++++++++++++++
 8 files changed, 356 insertions(+), 30 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index ead48817..769b998f 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -156,7 +156,7 @@ uv run Undefined-webui
 
 #### 优雅停机
 
-`SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：停止 OneBot 连接、关闭 Runtime API 与微信服务、停止史官 / memes worker，再由消息处理器排空并关闭 AI 队列、落盘历史，最后断开连接、关闭 AI 客户端与检索运行时、停止配置热重载并释放渲染资源。等待 worker 收尾期间模型队列保持可用，史官在向量写入后继续提交侧写模型请求也能完成；消息处理器收尾时新落盘的认知任务留待下次启动处理。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程，无需额外配置；请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
+`SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：先停止 QQ、微信与普通 Runtime API 的新接入，等待已接受的入站处理和 API 请求收尾，停止史官 / memes worker，再由消息处理器排空 AI 队列并落盘历史。排空期间保留 OneBot 响应接收、微信发送和 Runtime 文件下载能力，回复完成后才关闭传输、AI 客户端、检索运行时与渲染资源。等待 worker 收尾期间模型队列保持可用，史官在向量写入后继续提交侧写模型请求也能完成；消息处理器收尾时新落盘的认知任务留待下次启动处理。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程；其强制终止等待时间应覆盖实际模型和下载收尾耗时。请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
 
 #### 自动启动选项
 
diff --git a/src/Undefined/api/app.py b/src/Undefined/api/app.py
index 15bbb0a5..d913c1c2 100644
--- a/src/Undefined/api/app.py
+++ b/src/Undefined/api/app.py
@@ -62,6 +62,8 @@ def __init__(
         self._runner: web.AppRunner | None = None
         self._sites: list[web.TCPSite] = []
         self._background_tasks: set[asyncio.Task[Any]] = set()
+        self._request_tasks: set[asyncio.Task[Any]] = set()
+        self._stopping = False
         self._naga_state = NagaState()
         self._chat_job_manager = chat.ChatJobManager(context)
         transport = getattr(context.onebot, "file_transport", None)
@@ -96,10 +98,22 @@ async def start(self) -> None:
         cfg = self._context.config_getter()
         logger.info("[RuntimeAPI] 已启动: %s", cfg.api.display_url)
 
+    def begin_shutdown(self) -> None:
+        """关闭普通 API 接入，但保留待发 OneBot 文件的 HTTP 服务。"""
+        self._stopping = True
+        self._chat_job_manager.begin_shutdown()
+
+    async def drain_requests(self) -> None:
+        await self._chat_job_manager.stop()
+        tasks = self._request_tasks - {asyncio.current_task()}
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
     async def stop(self) -> None:
+        self.begin_shutdown()
+        await self.drain_requests()
         if self._file_store is not None:
             self._file_store.unavailable()
-        await self._chat_job_manager.stop()
 
         for task in self._background_tasks:
             task.cancel()
@@ -142,7 +156,19 @@ async def _auth_middleware(
                         response = _json_error("Unauthorized", status=401)
                         _apply_cors_headers(request, response)
                         return response
-            response = await handler(request)
+            is_file_request = onebot_files.is_file_request(request)
+            if self._stopping and not is_file_request:
+                response = _json_error("Runtime is shutting down", status=503)
+                _apply_cors_headers(request, response)
+                return response
+            task = asyncio.current_task()
+            if task is not None and not is_file_request:
+                self._request_tasks.add(task)
+            try:
+                response = await handler(request)
+            finally:
+                if task is not None:
+                    self._request_tasks.discard(task)
             _apply_cors_headers(request, response)
             return response
 
diff --git a/src/Undefined/main.py b/src/Undefined/main.py
index ec269b34..43e813d4 100644
--- a/src/Undefined/main.py
+++ b/src/Undefined/main.py
@@ -514,8 +514,11 @@ def _apply_config_updates(
             )
 
     shutdown_guard = install_shutdown_signal_handlers(logger)
+    onebot_run_task: asyncio.Task[None] | None = None
     try:
-        await _run_until_shutdown(onebot, shutdown_guard.event, logger)
+        onebot_run_task = await _run_until_shutdown(
+            onebot, shutdown_guard.event, logger
+        )
     except KeyboardInterrupt:
         # 仅在信号处理器注册全部失败（如非主线程运行）时才会走到这里；
         # 正常安装后 SIGINT 会转为停机事件，不再抛 KeyboardInterrupt
@@ -524,6 +527,59 @@ def _apply_config_updates(
         logger.exception("[异常] 运行期间发生未捕获的错误: %s", exc)
     finally:
         logger.info("[清理] 正在关闭机器人并释放资源...")
+        try:
+            await _close_message_runtime(
+                onebot,
+                handler,
+                runtime_api_server=runtime_api_server,
+                weixin_service=weixin_service,
+                meme_worker=meme_worker,
+                historian_worker=historian_worker,
+                logger=logger,
+            )
+        finally:
+            if onebot_run_task is not None:
+                onebot_run_task.cancel()
+                await asyncio.gather(onebot_run_task, return_exceptions=True)
+        await ai.close()
+        if retrieval_registry is not None:
+            await retrieval_registry.stop()
+        await config_manager.stop_hot_reload()
+        await close_render_browser()
+        await close_render_cache()
+        shutdown_guard.restore()
+        logger.info("[退出] 机器人已停止运行")
+
+
+async def _close_message_runtime(
+    onebot: OneBotClient,
+    handler: MessageHandler,
+    *,
+    runtime_api_server: RuntimeAPIServer | None,
+    weixin_service: WeixinService | None,
+    meme_worker: MemeWorker | None,
+    historian_worker: HistorianWorker | None,
+    logger: logging.Logger,
+) -> None:
+    """先关闭新接入并排空已接受任务，最后释放回复所依赖的传输资源。"""
+    onebot.stop_accepting_messages()
+    if weixin_service is not None:
+        weixin_service.stop_accepting_messages()
+    if runtime_api_server is not None:
+        runtime_api_server.begin_shutdown()
+    try:
+        if runtime_api_server is not None:
+            await runtime_api_server.drain_requests()
+        await onebot.drain_message_tasks()
+        if weixin_service is not None:
+            await weixin_service.drain_message_tasks()
+        await _close_message_workers(
+            handler,
+            meme_worker=meme_worker,
+            historian_worker=historian_worker,
+            logger=logger,
+        )
+    finally:
         if runtime_api_server is not None:
             try:
                 await runtime_api_server.stop()
@@ -534,21 +590,7 @@ def _apply_config_updates(
                 await weixin_service.stop()
             except Exception:
                 logger.exception("[清理] WeixinService stop 失败")
-        await _close_message_workers(
-            handler,
-            meme_worker=meme_worker,
-            historian_worker=historian_worker,
-            logger=logger,
-        )
         await onebot.disconnect()
-        await ai.close()
-        if retrieval_registry is not None:
-            await retrieval_registry.stop()
-        await config_manager.stop_hot_reload()
-        await close_render_browser()
-        await close_render_cache()
-        shutdown_guard.restore()
-        logger.info("[退出] 机器人已停止运行")
 
 
 async def _close_message_workers(
@@ -659,8 +701,8 @@ async def _run_until_shutdown(
     onebot: OneBotClient,
     shutdown_event: asyncio.Event,
     logger: logging.Logger,
-) -> None:
-    """运行 OneBot 连接，收到停止信号或连接任务结束时返回。"""
+) -> asyncio.Task[None]:
+    """等待停机条件；返回仍可收发的连接任务，由调用方在排空后关闭。"""
     run_task = asyncio.create_task(onebot.run_with_reconnect(), name="onebot-run")
     stop_task = asyncio.create_task(shutdown_event.wait(), name="shutdown-wait")
     try:
@@ -671,15 +713,13 @@ async def _run_until_shutdown(
         if run_task in done:
             # 连接任务自行结束：把异常抛给上层处理
             run_task.result()
-            return
+            return run_task
         logger.info("[退出] 收到停止信号 (SIGTERM/SIGINT)，正在优雅停机...")
+        return run_task
+    except BaseException:
         run_task.cancel()
-        try:
-            await run_task
-        except asyncio.CancelledError:
-            pass
-        except Exception as exc:
-            logger.warning("[退出] 停止 OneBot 连接时发生异常: %s", exc)
+        await asyncio.gather(run_task, return_exceptions=True)
+        raise
     finally:
         stop_task.cancel()
         try:
diff --git a/src/Undefined/onebot/client.py b/src/Undefined/onebot/client.py
index 3639b9e7..90a930e4 100644
--- a/src/Undefined/onebot/client.py
+++ b/src/Undefined/onebot/client.py
@@ -126,6 +126,7 @@ def __init__(
             Callable[[dict[str, Any]], Coroutine[Any, Any, None]] | None
         ) = None
         self._running = False
+        self._accepting_messages = True
         self._tasks: set[asyncio.Task[None]] = set()
         self.file_transport = (
             file_transport
@@ -208,6 +209,15 @@ async def _cancel_message_tasks(self) -> None:
         if tasks:
             await asyncio.gather(*tasks, return_exceptions=True)
 
+    def stop_accepting_messages(self) -> None:
+        """停止接收新事件，保留 API 响应接收与发送能力供已接受任务收尾。"""
+        self._accepting_messages = False
+
+    async def drain_message_tasks(self) -> None:
+        """等待已经接受的入站处理完成；调用前须关闭新消息接入。"""
+        if self._tasks:
+            await asyncio.gather(*tuple(self._tasks), return_exceptions=True)
+
     async def _call_api(
         self,
         action: str,
@@ -987,6 +997,9 @@ async def _dispatch_message(self, data: dict[str, Any]) -> None:
                 )
                 return
 
+        if not self._accepting_messages:
+            return
+
         # 事件类型的消息异步处理，不阻塞接收循环
         post_type = data.get("post_type")
         if post_type == "message":
diff --git a/src/Undefined/weixin/service.py b/src/Undefined/weixin/service.py
index 332eac06..c757a090 100644
--- a/src/Undefined/weixin/service.py
+++ b/src/Undefined/weixin/service.py
@@ -260,6 +260,8 @@ def __init__(
         self._lifecycle_lock = asyncio.Lock()
         self._running = False
         self._closed = False
+        self._accepting_messages = True
+        self._inbound_completions: set[asyncio.Future[None]] = set()
 
     def _build_client(
         self,
@@ -316,6 +318,14 @@ async def stop(self) -> None:
             self._running = False
             self._closed = True
 
+    def stop_accepting_messages(self) -> None:
+        """停止新入站消息，保持已连接帐号可发送排空中的回复。"""
+        self._accepting_messages = False
+
+    async def drain_message_tasks(self) -> None:
+        if self._inbound_completions:
+            await asyncio.gather(*tuple(self._inbound_completions))
+
     async def status(self) -> dict[str, Any]:
         accounts = await self.store.list_accounts()
         return {
@@ -857,6 +867,23 @@ async def _handle_inbound(
         alias: str,
         client: WeixinClientProtocol,
         message: InboundMessage,
+    ) -> None:
+        if not self._accepting_messages:
+            return
+        completion: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+        self._inbound_completions.add(completion)
+        try:
+            await self._process_inbound(alias, client, message)
+        finally:
+            self._inbound_completions.discard(completion)
+            if not completion.done():
+                completion.set_result(None)
+
+    async def _process_inbound(
+        self,
+        alias: str,
+        client: WeixinClientProtocol,
+        message: InboundMessage,
     ) -> None:
         account = await self.store.get_account(alias)
         if account is None:
diff --git a/tests/test_main_shutdown.py b/tests/test_main_shutdown.py
index e1015c0e..3ef881b8 100644
--- a/tests/test_main_shutdown.py
+++ b/tests/test_main_shutdown.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import os
 import signal
@@ -14,10 +15,12 @@
 from Undefined.handlers import MessageHandler
 from Undefined.main import (
     _close_message_workers,
+    _close_message_runtime,
     _run_until_shutdown,
     install_shutdown_signal_handlers,
 )
 from Undefined.services.queue_manager import QueueManager
+from Undefined.onebot.client import OneBotClient
 
 logger = logging.getLogger("test-main-shutdown")
 
@@ -123,7 +126,7 @@ async def run_with_reconnect(self) -> None:
 
 
 @pytest.mark.asyncio
-async def test_run_until_shutdown_cancels_onebot_on_signal() -> None:
+async def test_run_until_shutdown_keeps_onebot_alive_for_drain() -> None:
     onebot = _SlowOneBot()
     shutdown_event = asyncio.Event()
 
@@ -132,11 +135,115 @@ async def test_run_until_shutdown_cancels_onebot_on_signal() -> None:
     )
     await asyncio.sleep(0.05)
     shutdown_event.set()
-    await asyncio.wait_for(task, timeout=2)
-
+    connection = await asyncio.wait_for(task, timeout=2)
+    assert onebot.cancelled is False
+    assert not connection.done()
+    connection.cancel()
+    await asyncio.gather(connection, return_exceptions=True)
     assert onebot.cancelled is True
 
 
+class _ReplyWebSocket:
+    close_code: int | None = None
+
+    def __init__(self) -> None:
+        self.frames: asyncio.Queue[str] = asyncio.Queue()
+        self.receiving = asyncio.Event()
+        self.sent: list[dict[str, Any]] = []
+
+    async def recv(self) -> str:
+        self.receiving.set()
+        return await self.frames.get()
+
+    async def send(self, payload: str) -> None:
+        request = json.loads(payload)
+        self.sent.append(request)
+        await self.frames.put(json.dumps({"echo": request["echo"], "status": "ok"}))
+
+    async def close(self) -> None:
+        self.close_code = 1000
+        await self.frames.put("{}")
+
+
+@pytest.mark.asyncio
+async def test_shutdown_finishes_accepted_reply_before_closing_transport(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    onebot = OneBotClient("ws://isolated.invalid")
+    socket = _ReplyWebSocket()
+    onebot.ws = cast(Any, socket)
+    monkeypatch.setattr(onebot, "connect", AsyncMock())
+    shutdown = asyncio.Event()
+    wait_task = asyncio.create_task(_run_until_shutdown(onebot, shutdown, logger))
+    await asyncio.wait_for(socket.receiving.wait(), 1)
+    queue = QueueManager(ai_request_interval=0, max_retries=0)
+    reply_started = asyncio.Event()
+    release_reply = asyncio.Event()
+    order: list[str] = []
+
+    async def reply(request: dict[str, Any]) -> None:
+        reply_started.set()
+        await release_reply.wait()
+        response = await onebot.send_group_message(1, "accepted reply")
+        assert response["status"] == "ok"
+        order.append("delivered")
+
+    calls: list[str] = []
+
+    async def inbound(data: dict[str, Any]) -> None:
+        calls.append("accepted")
+        await queue.add_private_request({"type": "private_reply"})
+
+    queue.start(reply)
+    onebot.set_message_handler(inbound)
+    await onebot._dispatch_message({"post_type": "message"})
+    await asyncio.wait_for(reply_started.wait(), 1)
+    handler = MessageHandler.__new__(MessageHandler)
+    handler._background_tasks = set()
+    cast(Any, handler).pipeline_registry = SimpleNamespace(stop_hot_reload=AsyncMock())
+    cast(Any, handler).ai_coordinator = SimpleNamespace(queue_manager=queue)
+    cast(Any, handler).message_batcher = SimpleNamespace(flush_all=AsyncMock())
+
+    async def flush() -> None:
+        order.append("history")
+
+    cast(Any, handler).history_manager = SimpleNamespace(flush_pending_saves=flush)
+    shutdown.set()
+    connection = await asyncio.wait_for(wait_task, 1)
+    close_task = asyncio.create_task(
+        _close_message_runtime(
+            onebot,
+            handler,
+            runtime_api_server=None,
+            weixin_service=None,
+            meme_worker=None,
+            historian_worker=None,
+            logger=logger,
+        )
+    )
+    try:
+        await asyncio.sleep(0)
+        assert onebot._running
+        assert not close_task.done()
+        await onebot._dispatch_message({"post_type": "message"})
+        await onebot._dispatch_message(
+            {"post_type": "notice", "notice_type": "notify", "sub_type": "poke"}
+        )
+        assert calls == ["accepted"]
+        release_reply.set()
+        await asyncio.wait_for(close_task, 2)
+        await asyncio.wait_for(connection, 1)
+        assert order == ["delivered", "history"]
+        assert len(socket.sent) == 1
+        assert socket.frames.empty()
+    finally:
+        release_reply.set()
+        close_task.cancel()
+        connection.cancel()
+        await asyncio.gather(close_task, connection, return_exceptions=True)
+        await queue.stop()
+
+
 @pytest.mark.asyncio
 async def test_run_until_shutdown_propagates_connection_error() -> None:
     with pytest.raises(RuntimeError, match="connection boom"):
diff --git a/tests/test_onebot_file_urls.py b/tests/test_onebot_file_urls.py
index a4f45817..d26b7cf9 100644
--- a/tests/test_onebot_file_urls.py
+++ b/tests/test_onebot_file_urls.py
@@ -116,6 +116,62 @@ async def test_get_head_range_tokens_source_cleanup_mode_and_actual_port(
     assert token not in caplog.text
 
 
+async def test_shutdown_blocks_api_but_keeps_url_delivery_available(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "pending.txt"
+    source.write_bytes(b"accepted media")
+    async with runtime(tmp_path) as (server, store, _, _, _):
+        server.begin_shutdown()
+        await server.drain_requests()
+        url = await store.publish(source, "127.0.0.1")
+        async with ClientSession() as http:
+            async with http.get(f"http://127.0.0.1:{store.port}/health") as response:
+                assert response.status == 503
+            async with http.get(url) as response:
+                assert response.status == 200
+                assert await response.read() == b"accepted media"
+
+
+async def test_shutdown_waits_for_accepted_runtime_request(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def health(self: RuntimeAPIServer, request: web.Request) -> web.Response:
+        entered.set()
+        await release.wait()
+        return web.json_response({"ok": True})
+
+    monkeypatch.setattr(RuntimeAPIServer, "_health_handler", health)
+    async with runtime(tmp_path) as (server, store, _, _, _):
+        async with ClientSession() as http:
+
+            async def fetch_health() -> int:
+                async with http.get(
+                    f"http://127.0.0.1:{store.port}/health"
+                ) as response:
+                    await response.read()
+                    return response.status
+
+            request = asyncio.create_task(fetch_health())
+            await asyncio.wait_for(entered.wait(), 1)
+            server.begin_shutdown()
+            drain = asyncio.create_task(server.drain_requests())
+            try:
+                await asyncio.sleep(0)
+                assert not drain.done()
+                release.set()
+                assert await asyncio.wait_for(request, 1) == 200
+                await asyncio.wait_for(drain, 1)
+                assert not server._request_tasks
+            finally:
+                release.set()
+                await asyncio.gather(request, drain, return_exceptions=True)
+
+
 async def test_tokens_are_per_file_and_ipv6_format(tmp_path: Path) -> None:
     source = tmp_path / "file"
     source.write_bytes(b"abc")
diff --git a/tests/test_weixin_service.py b/tests/test_weixin_service.py
index a9eb1a46..26999d12 100644
--- a/tests/test_weixin_service.py
+++ b/tests/test_weixin_service.py
@@ -238,6 +238,63 @@ def _account() -> WeixinAccount:
     )
 
 
+@pytest.mark.asyncio
+async def test_quiesce_keeps_sending_available_until_accepted_inbound_finishes(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    config = _config(tmp_path)
+    store = WeixinStore(config.weixin)
+    await store.save_account(_account())
+    client = FakeClient()
+
+    def factory(
+        account: WeixinAccount,
+        state: UndefinedIlinkStateStore,
+        options: ClientOptions,
+    ) -> WeixinClientProtocol:
+        return client
+
+    service = WeixinService(
+        config,
+        store=store,
+        login_manager=cast(QrLoginManager, FakeLoginManager()),
+        client_factory=factory,
+    )
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def process(
+        alias: str, current_client: WeixinClientProtocol, message: InboundMessage
+    ) -> None:
+        entered.set()
+        await release.wait()
+        await service.send_text(10001, "accepted reply")
+
+    monkeypatch.setattr(service, "_process_inbound", process)
+    message = InboundMessage.from_mapping("bot-account", {"from_user_id": "peer-1"})
+    await service.start()
+    await asyncio.wait_for(client.run_started.wait(), 1)
+    task = asyncio.create_task(service._handle_inbound("primary", client, message))
+    await asyncio.wait_for(entered.wait(), 1)
+    service.stop_accepting_messages()
+    drain = asyncio.create_task(service.drain_message_tasks())
+    try:
+        await service._handle_inbound("primary", client, message)
+        await asyncio.sleep(0)
+        assert not drain.done()
+        assert not client.closed
+        release.set()
+        await asyncio.wait_for(drain, 1)
+        await task
+        assert client.sent_text == [("peer-1", "accepted reply")]
+    finally:
+        release.set()
+        await asyncio.gather(task, drain, return_exceptions=True)
+        await service.stop()
+    assert client.closed
+
+
 @pytest.mark.asyncio
 async def test_privileged_binding_requires_confirmation_before_network(
     tmp_path: Path,

From 217deba0e6562390f9c7e9cf5e8eed411197dab2 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:26:03 +0800
Subject: [PATCH 053/121] fix(chat): retain blobs while images are displayed

---
 apps/undefined-chat/README.md                 |   2 +-
 .../src/image-viewer/ImageViewerModal.tsx     |   2 +
 .../src/rendering/AttachmentImage.tsx         |   6 +-
 .../src/rendering/AttachmentImageContext.tsx  |  71 ++++++--
 .../src/rendering/blob-lifecycle.test.tsx     | 154 ++++++++++++++++++
 5 files changed, 218 insertions(+), 17 deletions(-)
 create mode 100644 apps/undefined-chat/src/rendering/blob-lifecycle.test.tsx

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index d256f0da..16813556 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -10,7 +10,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 消息历史：初始加载、cursor-based 加载更早消息、滚动锚点保持和长历史窗口化渲染。同一会话的重载与分页共用请求顺序保护；发送新消息、完成任务刷新或删除会话后，迟到的旧响应不会覆盖正文、游标或加载状态。
 - 消息渲染：Markdown、表格、任务列表、引用块、代码高亮、代码块复制；未知语言或高亮失败时保留为纯文本代码，代码中的 HTML 不会插入正文。正文 HTML 经 sanitize 内联渲染，HTML 代码块可在独立预览窗口中运行。
 - 附件：系统文件选择器、上传状态队列、Tauri 流式上传、下载和预览。当前显示上传中/成功/失败状态，不显示百分比进度。
-- 图片：正文 `<attachment uid/>` 内联图、附件缩略图、blob 缓存、全屏查看、缩放、旋转和可滚动查看区域。
+- 图片：正文 `<attachment uid/>` 内联图、附件缩略图、blob 缓存、全屏查看、缩放、旋转和可滚动查看区域。LRU 目标缓存 60 张；挂载中的图片和已打开的大图持有 blob 引用，超过目标时只淘汰无人使用的项，关闭或卸载消费者后再释放多余缓存。
 - 命令：斜杠命令、子命令提示、方向键导航、Tab/Enter 补全；空态反馈（加载中/无匹配/不可用）；窗口聚焦按 TTL 刷新命令列表。
 - 引用：引用 bot 消息、划词引用选中文本、发送引用、引用芯片跳转当前已加载源消息；源消息不在当前页时会自动加载一页更早历史，仍未命中需手动继续加载更早历史。
 - 工具调用块：层级展示、状态、运行中实时计时、阶段明细（stage detail）、与 WebUI 一致的输入/输出预览（JSON/Python 风格结构化、Markdown 输出、附件图片预览）；历史回放支持 timeline/calls/events 多级回退。
diff --git a/apps/undefined-chat/src/image-viewer/ImageViewerModal.tsx b/apps/undefined-chat/src/image-viewer/ImageViewerModal.tsx
index 60018c72..5e096574 100644
--- a/apps/undefined-chat/src/image-viewer/ImageViewerModal.tsx
+++ b/apps/undefined-chat/src/image-viewer/ImageViewerModal.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import type { ImageViewerState } from "../chat-store/types";
 import { useTranslation } from "../i18n";
+import { useRetainedAttachmentBlobUrl } from "../rendering/AttachmentImageContext";
 
 export type ImageViewerModalProps = {
 	imageViewer: ImageViewerState | null;
@@ -15,6 +16,7 @@ export function ImageViewerModal({
 	const previousActiveElementRef = useRef<HTMLElement | null>(null);
 	const [zoom, setZoom] = useState(1);
 	const [rotation, setRotation] = useState(0);
+	useRetainedAttachmentBlobUrl(imageViewer?.open ? imageViewer.src : null);
 
 	useEffect(() => {
 		if (imageViewer?.open) {
diff --git a/apps/undefined-chat/src/rendering/AttachmentImage.tsx b/apps/undefined-chat/src/rendering/AttachmentImage.tsx
index 2169fc9a..5b3ed682 100644
--- a/apps/undefined-chat/src/rendering/AttachmentImage.tsx
+++ b/apps/undefined-chat/src/rendering/AttachmentImage.tsx
@@ -33,12 +33,13 @@ export function AttachmentImage({
 	style,
 	onOpenImage,
 }: AttachmentImageProps) {
-	const { loadAttachmentBlob } = useAttachmentImage();
+	const { loadAttachmentBlob, retainAttachmentBlob } = useAttachmentImage();
 	const { t } = useTranslation();
 	const [state, setState] = useState<LoadState>({ status: "loading" });
 
 	useEffect(() => {
 		let cancelled = false;
+		const release = retainAttachmentBlob(uid);
 		setState({ status: "loading" });
 		loadAttachmentBlob(uid)
 			.then((loaded) => {
@@ -52,8 +53,9 @@ export function AttachmentImage({
 			});
 		return () => {
 			cancelled = true;
+			release();
 		};
-	}, [uid, loadAttachmentBlob]);
+	}, [uid, loadAttachmentBlob, retainAttachmentBlob]);
 
 	if (state.status === "loading") {
 		return (
diff --git a/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx b/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
index c8484434..6a594680 100644
--- a/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
+++ b/apps/undefined-chat/src/rendering/AttachmentImageContext.tsx
@@ -4,6 +4,7 @@ import {
 	useCallback,
 	useContext,
 	useEffect,
+	useLayoutEffect,
 	useMemo,
 } from "react";
 import type { RuntimeClient } from "../runtime-client/types";
@@ -15,6 +16,8 @@ export type LoadedAttachmentBlob = {
 
 type AttachmentImageContextValue = {
 	loadAttachmentBlob: (uid: string) => Promise<LoadedAttachmentBlob | null>;
+	retainAttachmentBlob: (uid: string) => () => void;
+	retainBlobUrl: (url: string) => (() => void) | undefined;
 };
 
 const AttachmentImageContext =
@@ -27,7 +30,7 @@ export type AttachmentImageProviderProps = {
 	client: Pick<RuntimeClient, "previewAttachment">;
 	/** 按 Runtime URL 隔离 UID 缓存，保持消费组件与 DOM 的生命周期。 */
 	runtimeUrl?: string | null;
-	/** blob 缓存上限，超出按 LRU 淘汰并 revoke。默认 60。 */
+	/** blob 缓存目标上限；超出时仅淘汰无消费者的 LRU 项。默认 60。 */
 	maxCacheSize?: number;
 	children: ReactNode;
 };
@@ -42,8 +45,8 @@ export type AttachmentImageProviderProps = {
  * - LRU 缓存 uid→blobUrl：缩略图/正文图/全屏大图复用同一 blob，避免重复拉取。
  * - inflight 去重：同一 UID 并发请求只发一次。
  * - blob URL 归本 Provider 所有：消费组件**不**自行 revoke（缩略图与大图共享同一
- *   URL，组件卸载即 revoke 会让仍打开的大图破图），仅在 LRU 淘汰、切换 Runtime
- *   或 Provider 卸载时 revoke。
+ *   URL，组件卸载即 revoke 会让仍打开的大图破图）。消费者持有引用期间跳过
+ *   LRU 淘汰；切换 Runtime 或 Provider 卸载时统一 revoke。
  */
 export function AttachmentImageProvider({
 	client,
@@ -56,11 +59,48 @@ export function AttachmentImageProvider({
 			runtimeUrl,
 			cache: new Map<string, LoadedAttachmentBlob>(),
 			inflight: new Map<string, Promise<LoadedAttachmentBlob | null>>(),
+			consumers: new Map<string, number>(),
 			generation: 0,
 		}),
 		[runtimeUrl],
 	);
 
+	const evictUnused = useCallback(() => {
+		for (const [uid, loaded] of scope.cache) {
+			if (scope.cache.size <= maxCacheSize) break;
+			if (scope.consumers.has(uid)) continue;
+			scope.cache.delete(uid);
+			URL.revokeObjectURL(loaded.url);
+		}
+	}, [maxCacheSize, scope]);
+
+	const retainAttachmentBlob = useCallback(
+		(uid: string): (() => void) => {
+			const generation = scope.generation;
+			scope.consumers.set(uid, (scope.consumers.get(uid) ?? 0) + 1);
+			let released = false;
+			return () => {
+				if (released || generation !== scope.generation) return;
+				released = true;
+				const remaining = (scope.consumers.get(uid) ?? 1) - 1;
+				if (remaining > 0) scope.consumers.set(uid, remaining);
+				else scope.consumers.delete(uid);
+				evictUnused();
+			};
+		},
+		[scope, evictUnused],
+	);
+
+	const retainBlobUrl = useCallback(
+		(url: string): (() => void) | undefined => {
+			for (const [uid, loaded] of scope.cache) {
+				if (loaded.url === url) return retainAttachmentBlob(uid);
+			}
+			return undefined;
+		},
+		[scope, retainAttachmentBlob],
+	);
+
 	const loadAttachmentBlob = useCallback(
 		(uid: string): Promise<LoadedAttachmentBlob | null> => {
 			const { cache, inflight } = scope;
@@ -93,14 +133,7 @@ export function AttachmentImageProvider({
 						mediaType,
 					};
 					cache.set(uid, loaded);
-					// 超上限淘汰最旧（队首）并 revoke
-					while (cache.size > maxCacheSize) {
-						const oldestKey = cache.keys().next().value;
-						if (oldestKey === undefined) break;
-						const victim = cache.get(oldestKey);
-						cache.delete(oldestKey);
-						if (victim) URL.revokeObjectURL(victim.url);
-					}
+					evictUnused();
 					return loaded;
 				} catch {
 					return null;
@@ -112,7 +145,7 @@ export function AttachmentImageProvider({
 			inflight.set(uid, promise);
 			return promise;
 		},
-		[client, maxCacheSize, scope],
+		[client, evictUnused, scope],
 	);
 
 	// 切换 Runtime 或卸载时释放全部 blob URL，拒绝旧作用域迟到的响应。
@@ -121,6 +154,7 @@ export function AttachmentImageProvider({
 		return () => {
 			scope.generation += 1;
 			inflight.clear();
+			scope.consumers.clear();
 			for (const { url } of cache.values()) {
 				URL.revokeObjectURL(url);
 			}
@@ -129,8 +163,8 @@ export function AttachmentImageProvider({
 	}, [scope]);
 
 	const value = useMemo<AttachmentImageContextValue>(
-		() => ({ loadAttachmentBlob }),
-		[loadAttachmentBlob],
+		() => ({ loadAttachmentBlob, retainAttachmentBlob, retainBlobUrl }),
+		[loadAttachmentBlob, retainAttachmentBlob, retainBlobUrl],
 	);
 
 	return (
@@ -152,3 +186,12 @@ export function useAttachmentImage(): AttachmentImageContextValue {
 	}
 	return value;
 }
+
+/** 大图独立持有 Provider 的 URL；外部图片和无 Provider 的查看器无需持有。 */
+export function useRetainedAttachmentBlobUrl(url: string | null): void {
+	const value = useContext(AttachmentImageContext);
+	// 在被动 effect 释放缩略图前接管引用，支持同次渲染中移除源缩略图。
+	useLayoutEffect(() => {
+		if (url) return value?.retainBlobUrl(url);
+	}, [value, url]);
+}
diff --git a/apps/undefined-chat/src/rendering/blob-lifecycle.test.tsx b/apps/undefined-chat/src/rendering/blob-lifecycle.test.tsx
new file mode 100644
index 00000000..5e878248
--- /dev/null
+++ b/apps/undefined-chat/src/rendering/blob-lifecycle.test.tsx
@@ -0,0 +1,154 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { StrictMode, useState } from "react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { ImageViewerState } from "../chat-store/types";
+import { LanguageProvider } from "../i18n";
+import { ImageViewerModal } from "../image-viewer/ImageViewerModal";
+import { runtimeClientStub } from "../test-fixtures";
+import { AttachmentImage } from "./AttachmentImage";
+import { AttachmentImageProvider } from "./AttachmentImageContext";
+
+function Gallery({
+	images,
+	removeOnOpen = false,
+}: {
+	images: { id: string; uid: string }[];
+	removeOnOpen?: boolean;
+}) {
+	const [viewer, setViewer] = useState<ImageViewerState | null>(null);
+	const [hideThumbnails, setHideThumbnails] = useState(false);
+	return (
+		<>
+			{!hideThumbnails &&
+				images.map(({ id, uid }) => (
+					<AttachmentImage
+						key={id}
+						uid={uid}
+						alt={id}
+						onOpenImage={(src, alt) => {
+							setViewer({ open: true, src, alt });
+							if (removeOnOpen) setHideThumbnails(true);
+						}}
+					/>
+				))}
+			<ImageViewerModal imageViewer={viewer} onClose={() => setViewer(null)} />
+		</>
+	);
+}
+
+describe("active image blob lifetimes", () => {
+	afterEach(() => vi.restoreAllMocks());
+
+	test("61 mounted images keep their URLs, and an open viewer retains a removed thumbnail", async () => {
+		const revoke = vi.spyOn(URL, "revokeObjectURL").mockClear();
+		const client = runtimeClientStub();
+		const uids = Array.from({ length: 61 }, (_, index) => `pic_${index}`);
+		const tree = (shown: string[]) => (
+			<LanguageProvider>
+				<AttachmentImageProvider client={client}>
+					<Gallery images={shown.map((uid) => ({ id: uid, uid }))} />
+				</AttachmentImageProvider>
+			</LanguageProvider>
+		);
+		const { rerender, unmount } = render(tree(uids.slice(0, 1)));
+		const first = (await screen.findByAltText("pic_0")) as HTMLImageElement;
+		const firstUrl = first.src;
+		rerender(tree(uids));
+		await waitFor(() =>
+			expect(document.querySelectorAll("img")).toHaveLength(61),
+		);
+		expect(screen.getByAltText("pic_0")).toBe(first);
+		expect(first).toHaveAttribute("src", firstUrl);
+		expect(revoke).not.toHaveBeenCalled();
+		expect(firstUrl).toMatch(/^blob:/);
+		expect((await (await fetch(firstUrl)).arrayBuffer()).byteLength).toBe(4);
+		fireEvent.click(first);
+		expect(screen.getByRole("dialog").querySelector("img")).toHaveAttribute(
+			"src",
+			firstUrl,
+		);
+		rerender(tree(uids.slice(1)));
+		expect(first.isConnected).toBe(false);
+		expect(revoke).not.toHaveBeenCalledWith(firstUrl);
+		expect((await (await fetch(firstUrl)).arrayBuffer()).byteLength).toBe(4);
+		fireEvent.click(screen.getByRole("button", { name: "关闭" }));
+		expect(revoke).toHaveBeenCalledWith(firstUrl);
+		expect(revoke).toHaveBeenCalledTimes(1);
+		await expect(fetch(firstUrl)).rejects.toThrow();
+		unmount();
+		expect(revoke).toHaveBeenCalledTimes(61);
+	});
+
+	test("two consumers sharing a UID retain it until both unmount", async () => {
+		const revoke = vi.spyOn(URL, "revokeObjectURL").mockClear();
+		const client = runtimeClientStub();
+		const tree = (count: number) => (
+			<LanguageProvider>
+				<AttachmentImageProvider client={client} maxCacheSize={0}>
+					<Gallery
+						images={["first", "second"].slice(0, count).map((id) => ({
+							id,
+							uid: "pic_shared",
+						}))}
+					/>
+				</AttachmentImageProvider>
+			</LanguageProvider>
+		);
+		const { rerender } = render(tree(2));
+		const first = await screen.findByAltText("first");
+		const second = await screen.findByAltText("second");
+		const url = first.getAttribute("src");
+		expect(second).toHaveAttribute("src", url);
+		expect(client.previewAttachment).toHaveBeenCalledTimes(1);
+		rerender(tree(1));
+		expect(revoke).not.toHaveBeenCalledWith(url);
+		rerender(tree(0));
+		expect(revoke).toHaveBeenCalledWith(url);
+	});
+
+	test("opening a viewer and removing its source in the same render transfers the reference", async () => {
+		const revoke = vi.spyOn(URL, "revokeObjectURL").mockClear();
+		render(
+			<LanguageProvider>
+				<AttachmentImageProvider client={runtimeClientStub()} maxCacheSize={0}>
+					<Gallery
+						images={[{ id: "handoff", uid: "pic_handoff" }]}
+						removeOnOpen
+					/>
+				</AttachmentImageProvider>
+			</LanguageProvider>,
+		);
+		const thumbnail = await screen.findByAltText("handoff");
+		const url = thumbnail.getAttribute("src");
+		fireEvent.click(thumbnail);
+		expect(thumbnail.isConnected).toBe(false);
+		expect(screen.getByRole("dialog").querySelector("img")).toHaveAttribute(
+			"src",
+			url,
+		);
+		expect(revoke).not.toHaveBeenCalledWith(url);
+		fireEvent.click(screen.getByRole("button", { name: "关闭" }));
+		expect(revoke).toHaveBeenCalledWith(url);
+	});
+
+	test("StrictMode cleanup does not discard the current consumer's blob", async () => {
+		const revoke = vi.spyOn(URL, "revokeObjectURL").mockClear();
+		const { unmount } = render(
+			<StrictMode>
+				<LanguageProvider>
+					<AttachmentImageProvider
+						client={runtimeClientStub()}
+						maxCacheSize={0}
+					>
+						<Gallery images={[{ id: "strict", uid: "pic_strict" }]} />
+					</AttachmentImageProvider>
+				</LanguageProvider>
+			</StrictMode>,
+		);
+		const thumbnail = await screen.findByAltText("strict");
+		const url = thumbnail.getAttribute("src");
+		expect(revoke).not.toHaveBeenCalledWith(url);
+		unmount();
+		expect(revoke).toHaveBeenCalledWith(url);
+	});
+});

From 590790e60a67c0b4d0cdc75f23a36beea98aefb0 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:34:50 +0800
Subject: [PATCH 054/121] fix(console): preserve schemes and IPv6 in profile
 migration

---
 apps/undefined-console/README.md              |  10 +-
 apps/undefined-console/biome.json             |   1 +
 apps/undefined-console/package.json           |   3 +-
 .../src/connection-profiles.test.cjs          | 252 ++++++++++++++++++
 apps/undefined-console/src/main.ts            |  85 +++++-
 5 files changed, 337 insertions(+), 14 deletions(-)
 create mode 100644 apps/undefined-console/src/connection-profiles.test.cjs

diff --git a/apps/undefined-console/README.md b/apps/undefined-console/README.md
index c89902d8..67ee0771 100644
--- a/apps/undefined-console/README.md
+++ b/apps/undefined-console/README.md
@@ -7,7 +7,7 @@ A `Tauri v2` management client for Undefined that targets the remote Management
 - Desktop builds for `Windows`, `macOS`, and `Linux`
 - Android build support from the same codebase
 - Mobile-friendly shell for connecting to remote instances
-- Separate connection profiles for `Management` and `Runtime-only` modes
+- Local connection profiles with separate Management and Runtime protocol/port settings
 
 ## Scripts
 
@@ -39,8 +39,12 @@ npm run tauri:build:no-strip
 
 ## Connection model
 
-- **Management mode**: connect with `management_url` and a password/token flow.
-- **Runtime-only mode**: connect with `runtime_url` and `X-Undefined-API-Key` compatible credentials.
+- **Management**: open the configured WebUI, optionally logging in with its management password before navigation.
+- **Runtime**: probe the configured Runtime's `/health` and `/openapi.json`. Chat authentication is configured in Undefined Chat or the WebUI.
+
+The connection editor stores a host and separate protocol/port choices for Management and Runtime. New profiles use HTTP by default; select HTTPS for TLS endpoints. Existing profiles using `managementUrl` / `runtimeUrl` are migrated with their original HTTP/HTTPS protocols and ports. IPv6 hosts accept either `::1` or `[::1]` and produce a URL with a single pair of brackets. Saving and reloading a migrated profile preserves these choices.
+
+`npm test` runs the connection migration, save/reload, probe, and login regressions with in-memory storage and network/navigation stubs. It is included in `npm run check` and never contacts a real instance.
 
 This scaffold intentionally keeps the frontend shell lightweight. It is suitable for embedding into both browser-hosted WebUI and Tauri clients.
 
diff --git a/apps/undefined-console/biome.json b/apps/undefined-console/biome.json
index 98b69ab7..f60f58d2 100644
--- a/apps/undefined-console/biome.json
+++ b/apps/undefined-console/biome.json
@@ -5,6 +5,7 @@
     "files": {
         "includes": [
             "**/src/**/*.ts",
+            "**/src/**/*.cjs",
             "**/package.json",
             "**/tsconfig.json",
             "**/vite.config.ts",
diff --git a/apps/undefined-console/package.json b/apps/undefined-console/package.json
index 131b5758..d611a9fc 100644
--- a/apps/undefined-console/package.json
+++ b/apps/undefined-console/package.json
@@ -9,9 +9,10 @@
 		"lint": "biome check src package.json tsconfig.json vite.config.ts src-tauri/tauri.conf.json src-tauri/capabilities/default.json",
 		"lint:webui": "biome check --config-path ../../biome.json ../../src/Undefined/webui/static/js",
 		"typecheck": "tsc --noEmit",
+		"test": "node --test src/connection-profiles.test.cjs",
 		"tauri:fmt:check": "cargo fmt --manifest-path src-tauri/Cargo.toml --all --check",
 		"tauri:check": "cargo check --manifest-path src-tauri/Cargo.toml",
-		"check": "npm run lint && npm run lint:webui && npm run typecheck && npm run tauri:fmt:check && npm run tauri:check",
+		"check": "npm run lint && npm run lint:webui && npm run typecheck && npm run test && npm run tauri:fmt:check && npm run tauri:check",
 		"build": "npm run typecheck && vite build",
 		"preview": "vite preview --host 0.0.0.0 --port 4173",
 		"tauri:dev": "tauri dev",
diff --git a/apps/undefined-console/src/connection-profiles.test.cjs b/apps/undefined-console/src/connection-profiles.test.cjs
new file mode 100644
index 00000000..8bb0c50e
--- /dev/null
+++ b/apps/undefined-console/src/connection-profiles.test.cjs
@@ -0,0 +1,252 @@
+const assert = require("node:assert/strict");
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+const { test } = require("node:test");
+const ts = require("typescript");
+
+const PROFILE_KEY = "undefined.console.profiles";
+const source = readFileSync(join(__dirname, "main.ts"), "utf8");
+const compiled = ts.transpileModule(source, {
+	compilerOptions: {
+		module: ts.ModuleKind.CommonJS,
+		target: ts.ScriptTarget.ES2022,
+	},
+}).outputText;
+
+// Execute the actual app and its form handlers. Storage, HTTP and navigation are
+// isolated in memory; imports outside the two mocked Tauri modules are rejected.
+function loadConsole(profiles, { native = false } = {}) {
+	const storage = new Map();
+	if (profiles !== undefined)
+		storage.set(PROFILE_KEY, JSON.stringify(profiles));
+	const calls = [];
+	const navigations = [];
+	const app = { innerHTML: "" };
+	const form = {
+		values: {},
+		addEventListener(event, handler) {
+			this[event] = handler;
+		},
+	};
+	const document = {
+		documentElement: { lang: "", dataset: {} },
+		querySelector(selector) {
+			if (selector === "#app") return app;
+			if (selector === "#profile-form") return form;
+			return null;
+		},
+		querySelectorAll: () => [],
+	};
+	const request = async (url, init = {}) => {
+		// No branch invokes Node/global fetch or any real Runtime.
+		calls.push({ url, ...init });
+		return new Response(
+			JSON.stringify({
+				access_token: "FAKE-TOKEN",
+				refresh_token: "FAKE-REFRESH",
+			}),
+			{ status: 200, headers: { "Content-Type": "application/json" } },
+		);
+	};
+	const exports = {};
+	const load = new Function(
+		"require",
+		"exports",
+		"localStorage",
+		"document",
+		"window",
+		"fetch",
+		"FormData",
+		`${compiled}\nreturn { state, openWebui, runProbes, buildManagementUrl, buildRuntimeUrl };`,
+	);
+	const consoleApp = load(
+		(name) => {
+			if (name === "@tauri-apps/api/core") return { isTauri: () => native };
+			if (name === "@tauri-apps/plugin-http") return { fetch: request };
+			if (name === "./style.css") return {};
+			throw new Error(`Unexpected import: ${name}`);
+		},
+		exports,
+		{
+			getItem: (key) => storage.get(key) ?? null,
+			setItem: (key, value) => storage.set(key, value),
+		},
+		document,
+		{
+			location: {
+				href: "tauri://localhost/",
+				assign: (url) => navigations.push(url),
+			},
+		},
+		request,
+		class FormData {
+			constructor(currentForm) {
+				this.values = currentForm.values;
+			}
+			get(key) {
+				return this.values[key] ?? null;
+			}
+		},
+	);
+	return {
+		...consoleApp,
+		app,
+		storage,
+		calls,
+		navigations,
+		submit(values) {
+			form.values = values;
+			form.submit({ currentTarget: form, preventDefault() {} });
+		},
+	};
+}
+
+test("legacy HTTPS origins stay HTTPS through the actual password login and probes", async () => {
+	const app = loadConsole(
+		[
+			{
+				id: "tls",
+				managementUrl: "https://secure.example:443",
+				runtimeUrl: "https://secure.example:9443",
+				password: "FAKE-PASSWORD",
+			},
+		],
+		{ native: true },
+	);
+	const profile = app.state.profiles[0];
+	assert.equal(profile.managementScheme, "https");
+	assert.equal(profile.runtimeScheme, "https");
+	assert.equal(profile.managementPort, "443");
+	assert.equal(profile.runtimePort, "9443");
+	await app.openWebui();
+	assert.equal(
+		app.calls[0].url,
+		"https://secure.example:443/api/v1/management/auth/login",
+	);
+	assert.equal(app.calls[0].method, "POST");
+	assert.equal(app.calls[0].body, '{"password":"FAKE-PASSWORD"}');
+	assert.equal(new URL(app.navigations[0]).origin, "https://secure.example");
+	await app.runProbes();
+	assert.ok(app.calls.every((call) => new URL(call.url).protocol === "https:"));
+	assert.ok(
+		app.calls.some((call) => call.url === "https://secure.example:9443/health"),
+	);
+});
+
+test("legacy IPv6 produces one pair of brackets and reaches login/navigation", async () => {
+	const app = loadConsole([
+		{
+			id: "ipv6",
+			managementUrl: "http://[::1]:8787",
+			runtimeUrl: "https://[::1]:9443",
+			password: "FAKE-PASSWORD",
+		},
+	]);
+	const profile = app.state.profiles[0];
+	assert.equal(profile.host, "::1");
+	assert.equal(app.buildManagementUrl(profile), "http://[::1]:8787");
+	assert.equal(app.buildRuntimeUrl(profile), "https://[::1]:9443");
+	await app.openWebui();
+	assert.equal(
+		app.calls[0].url,
+		"http://[::1]:8787/api/v1/management/auth/login",
+	);
+	assert.equal(new URL(app.navigations[0]).origin, "http://[::1]:8787");
+});
+
+test("the editor saves migrated protocol choices and reloads them without legacy URL fields", async () => {
+	const app = loadConsole([
+		{
+			id: "migration",
+			name: "TLS connection",
+			managementUrl: "https://[2001:db8::1]:8443",
+			runtimeUrl: "http://[2001:db8::1]:8788",
+		},
+	]);
+	assert.match(
+		app.app.innerHTML,
+		/name="managementScheme"><option value="http">HTTP<\/option><option value="https" selected>/,
+	);
+	assert.match(
+		app.app.innerHTML,
+		/name="runtimeScheme"><option value="http" selected>/,
+	);
+	app.submit({
+		name: "TLS connection",
+		host: "[2001:db8::1]",
+		managementScheme: "https",
+		managementPort: "8443",
+		runtimeScheme: "http",
+		runtimePort: "8788",
+	});
+	const saved = JSON.parse(app.storage.get(PROFILE_KEY));
+	assert.equal(saved[0].managementUrl, undefined);
+	assert.equal(saved[0].runtimeUrl, undefined);
+	const reloaded = loadConsole(saved);
+	const profile = reloaded.state.profiles[0];
+	assert.equal(
+		reloaded.buildManagementUrl(profile),
+		"https://[2001:db8::1]:8443",
+	);
+	assert.equal(reloaded.buildRuntimeUrl(profile), "http://[2001:db8::1]:8788");
+	await reloaded.openWebui();
+	assert.equal(
+		new URL(reloaded.navigations[0]).origin,
+		"https://[2001:db8::1]:8443",
+	);
+});
+
+test("the editor can explicitly choose distinct protocols and persist a TLS Runtime", () => {
+	const app = loadConsole();
+	app.submit({
+		name: "Mixed connection",
+		host: "example.test",
+		managementScheme: "http",
+		managementPort: "8787",
+		runtimeScheme: "https",
+		runtimePort: "443",
+	});
+	const reloaded = loadConsole(JSON.parse(app.storage.get(PROFILE_KEY)));
+	const profile = reloaded.state.profiles[0];
+	assert.equal(
+		reloaded.buildManagementUrl(profile),
+		"http://example.test:8787",
+	);
+	assert.equal(
+		new URL(reloaded.buildRuntimeUrl(profile)).origin,
+		"https://example.test",
+	);
+});
+
+test("existing host/port profiles without protocol fields keep their HTTP defaults", () => {
+	const app = loadConsole([
+		{
+			id: "current",
+			host: "localhost",
+			managementPort: "8787",
+			runtimePort: "8788",
+		},
+	]);
+	const profile = app.state.profiles[0];
+	assert.equal(app.buildManagementUrl(profile), "http://localhost:8787");
+	assert.equal(app.buildRuntimeUrl(profile), "http://localhost:8788");
+	const initial = loadConsole();
+	assert.equal(
+		initial.buildManagementUrl(initial.state.profiles[0]),
+		"http://127.0.0.1:8787",
+	);
+});
+
+test("both bare and already-bracketed current IPv6 hosts are valid after reload", () => {
+	for (const host of ["::1", "[::1]"]) {
+		const app = loadConsole([
+			{ id: "current", host, managementPort: "8787", runtimePort: "8788" },
+		]);
+		const profile = app.state.profiles[0];
+		assert.equal(app.buildManagementUrl(profile), "http://[::1]:8787");
+		assert.equal(
+			new URL(app.buildRuntimeUrl(profile)).origin,
+			"http://[::1]:8788",
+		);
+	}
+});
diff --git a/apps/undefined-console/src/main.ts b/apps/undefined-console/src/main.ts
index 165015f0..1eb5326c 100644
--- a/apps/undefined-console/src/main.ts
+++ b/apps/undefined-console/src/main.ts
@@ -5,12 +5,15 @@ import "./style.css";
 type Lang = "zh" | "en";
 type Theme = "light" | "dark";
 type ProbeKind = "management" | "runtime" | "profile" | "configuration";
+type ConnectionScheme = "http" | "https";
 
 type ConnectionProfile = {
 	id: string;
 	name: string;
 	host: string;
+	managementScheme: ConnectionScheme;
 	managementPort: string;
+	runtimeScheme: ConnectionScheme;
 	runtimePort: string;
 	password: string;
 	notes: string;
@@ -53,7 +56,9 @@ const messages = {
 		host: "IP / 域名",
 		host_placeholder: "例如：192.168.2.1 或 example.com",
 		management_port: "Management 端口",
+		management_scheme: "Management 协议",
 		runtime_port: "Runtime 端口",
+		runtime_scheme: "Runtime 协议",
 		password: "管理密码",
 		password_placeholder: "填写后打开 WebUI 时会自动尝试登录",
 		notes: "备注",
@@ -109,7 +114,9 @@ const messages = {
 		host: "Host / IP",
 		host_placeholder: "For example: 192.168.2.1 or example.com",
 		management_port: "Management port",
+		management_scheme: "Management protocol",
 		runtime_port: "Runtime port",
+		runtime_scheme: "Runtime protocol",
 		password: "Management password",
 		password_placeholder: "If filled, WebUI will try to sign in automatically",
 		notes: "Notes",
@@ -185,17 +192,37 @@ function loadPreference<T extends Lang | Theme>(
 	}
 }
 
-function parseLegacyUrl(url: string): { host: string; port: string } {
+function normalizeHost(host: string): string {
+	const text = host.trim();
+	return text.startsWith("[") && text.endsWith("]") ? text.slice(1, -1) : text;
+}
+
+function connectionScheme(
+	value: unknown,
+	fallback: ConnectionScheme = "http",
+): ConnectionScheme {
+	return value === "http" || value === "https" ? value : fallback;
+}
+
+function parseLegacyUrl(url: string): {
+	host: string;
+	port: string;
+	scheme: ConnectionScheme;
+} {
 	const text = String(url || "").trim();
-	if (!text) return { host: "", port: "" };
+	const empty = { host: "", port: "", scheme: "http" as const };
+	if (!text) return empty;
 	try {
 		const parsed = new URL(text);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+			return empty;
 		return {
-			host: parsed.hostname || "",
+			host: normalizeHost(parsed.hostname),
 			port: parsed.port || (parsed.protocol === "https:" ? "443" : "80"),
+			scheme: parsed.protocol === "https:" ? "https" : "http",
 		};
 	} catch {
-		return { host: "", port: "" };
+		return empty;
 	}
 }
 
@@ -207,7 +234,9 @@ function loadProfiles(): ConnectionProfile[] {
 				id: crypto.randomUUID(),
 				name: messages.zh.profile_default_name,
 				host: "127.0.0.1",
+				managementScheme: "http",
 				managementPort: "8787",
+				runtimeScheme: "http",
 				runtimePort: "8788",
 				password: "",
 				notes: messages.zh.profile_default_notes,
@@ -220,15 +249,22 @@ function loadProfiles(): ConnectionProfile[] {
 		return parsed.map((item) => {
 			const management = parseLegacyUrl(String(item.managementUrl || ""));
 			const runtime = parseLegacyUrl(String(item.runtimeUrl || ""));
-			const host = String(item.host || management.host || runtime.host || "");
+			const host = normalizeHost(
+				String(item.host || management.host || runtime.host || ""),
+			);
 			return {
 				id: String(item.id || crypto.randomUUID()),
 				name: String(item.name || messages.zh.profile_new_name),
 				host,
+				managementScheme: connectionScheme(
+					item.managementScheme,
+					management.scheme,
+				),
 				managementPort: String(
 					item.managementPort || management.port || "8787",
 				),
 				runtimePort: String(item.runtimePort || runtime.port || "8788"),
+				runtimeScheme: connectionScheme(item.runtimeScheme, runtime.scheme),
 				password: String(item.password || ""),
 				notes: String(item.notes || ""),
 			};
@@ -262,22 +298,31 @@ function selectedProfile(): ConnectionProfile | undefined {
 }
 
 function formatHost(host: string): string {
-	if (host.includes(":")) return `[${host}]`;
-	return host;
+	const normalized = normalizeHost(host);
+	return normalized.includes(":") ? `[${normalized}]` : normalized;
 }
 
 function buildManagementUrl(profile: ConnectionProfile): string {
 	const host = profile.host.trim();
 	const port = profile.managementPort.trim();
 	if (!host || !port) return "";
-	return `http://${formatHost(host)}:${port}`;
+	return `${profile.managementScheme}://${formatHost(host)}:${port}`;
 }
 
 function buildRuntimeUrl(profile: ConnectionProfile): string {
 	const host = profile.host.trim();
 	const port = profile.runtimePort.trim();
 	if (!host || !port) return "";
-	return `http://${formatHost(host)}:${port}`;
+	return `${profile.runtimeScheme}://${formatHost(host)}:${port}`;
+}
+
+function schemeOptions(selected: ConnectionScheme): string {
+	return (["http", "https"] as const)
+		.map(
+			(scheme) =>
+				`<option value="${scheme}"${scheme === selected ? " selected" : ""}>${scheme.toUpperCase()}</option>`,
+		)
+		.join("");
 }
 
 function badge(status: ProbeState["status"]): string {
@@ -645,10 +690,18 @@ function render(): void {
                                     <label for="host">${t("host")}</label>
                                     <input id="host" name="host" value="${escapeAttribute(profile?.host ?? "")}" placeholder="${escapeAttribute(t("host_placeholder"))}" />
                                 </div>
+                                <div class="field">
+                                    <label for="management-scheme">${t("management_scheme")}</label>
+                                    <select id="management-scheme" name="managementScheme">${schemeOptions(profile?.managementScheme ?? "http")}</select>
+                                </div>
                                 <div class="field">
                                     <label for="management-port">${t("management_port")}</label>
                                     <input id="management-port" name="managementPort" value="${escapeAttribute(profile?.managementPort ?? "")}" inputmode="numeric" />
                                 </div>
+                                <div class="field">
+                                    <label for="runtime-scheme">${t("runtime_scheme")}</label>
+                                    <select id="runtime-scheme" name="runtimeScheme">${schemeOptions(profile?.runtimeScheme ?? "http")}</select>
+                                </div>
                                 <div class="field">
                                     <label for="runtime-port">${t("runtime_port")}</label>
                                     <input id="runtime-port" name="runtimePort" value="${escapeAttribute(profile?.runtimePort ?? "")}" inputmode="numeric" />
@@ -692,8 +745,16 @@ function bindEvents(): void {
 			const nextProfile: ConnectionProfile = {
 				id: state.selectedId || crypto.randomUUID(),
 				name: String(form.get("name") || t("profile_new_name")).trim(),
-				host: String(form.get("host") || "").trim(),
+				host: normalizeHost(String(form.get("host") || "")),
+				managementScheme: connectionScheme(
+					form.get("managementScheme"),
+					selectedProfile()?.managementScheme,
+				),
 				managementPort: String(form.get("managementPort") || "").trim(),
+				runtimeScheme: connectionScheme(
+					form.get("runtimeScheme"),
+					selectedProfile()?.runtimeScheme,
+				),
 				runtimePort: String(form.get("runtimePort") || "").trim(),
 				password: String(form.get("password") || "").trim(),
 				notes: String(form.get("notes") || "").trim(),
@@ -749,7 +810,9 @@ function bindEvents(): void {
 				id: crypto.randomUUID(),
 				name: t("profile_new_name"),
 				host: "",
+				managementScheme: "http",
 				managementPort: "",
+				runtimeScheme: "http",
 				runtimePort: "",
 				password: "",
 				notes: "",
@@ -768,7 +831,9 @@ function bindEvents(): void {
 				id: crypto.randomUUID(),
 				name: t("profile_seed_name"),
 				host: "127.0.0.1",
+				managementScheme: "http",
 				managementPort: "8787",
+				runtimeScheme: "http",
 				runtimePort: "8788",
 				password: "",
 				notes: t("profile_seed_notes"),

From fa84cc41154b8b14c2fc4f609c3372311924eaf0 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:36:30 +0800
Subject: [PATCH 055/121] fix(naga): preserve delivered results when usage
 persistence fails

---
 docs/naga_integration_contract.md     |   1 +
 docs/openapi.md                       |   2 +
 src/Undefined/api/routes/naga/send.py |  53 ++++--
 tests/test_runtime_api_naga.py        | 232 ++++++++++++++++++++++++++
 4 files changed, 276 insertions(+), 12 deletions(-)

diff --git a/docs/naga_integration_contract.md b/docs/naga_integration_contract.md
index 223676e6..ad5f27f3 100644
--- a/docs/naga_integration_contract.md
+++ b/docs/naga_integration_contract.md
@@ -104,6 +104,7 @@ Authorization: Bearer <config.[naga].api_key>
 - 若渲染失败，会回退为文本发送，并在响应中标记 `render_fallback=true`
 - 当 `mode=both` 时：两条通道都必须先通过会话策略，否则整单 HTTP 403（`naga policy denied`），不会部分投递；策略通过后若发送链路部分失败，只要至少一条通道发送成功仍可返回 `200`，由 `sent_private` / `sent_group` 表示实际投递结果
 - 成功响应会额外带 `partial_success` 与 `delivery_status`，用于显式区分“完全成功”和“部分成功”
+- 实际投递结果确认后，先提交同 `uuid` 的幂等结果，再保存使用统计。统计落盘失败只记录日志，不改变已成功或部分成功的投递结果；该阶段遇到取消也先收敛结果和租约，再传播取消，同 `uuid` 重试不会重新发送。进程重启及幂等缓存有效期仍遵循既有缓存边界。
 - 对同一个 `uuid` 的重复调用：
   - 若 payload 完全一致，则直接复用首个结果
   - 若 payload 不一致，则返回 `409`
diff --git a/docs/openapi.md b/docs/openapi.md
index 72f54437..51e68c5a 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -982,6 +982,8 @@ Naga 集成端点仅在以下条件同时满足时注册：
 - 绑定流程使用 `bind_uuid` 驱动，而不是早期的 scoped token。
 - 发送流程使用 `bind_uuid + naga_id + delivery_signature` 三元组验签。
 - 发送流程支持调用方提供 `uuid` 作为幂等键；相同键的重复请求会直接复用首个结果。
+- 投递成功后，使用次数等统计的持久化失败只记录日志，仍返回实际投递结果并保留 `uuid` 幂等结果；同键重试不会再次发送。统计信息在该次持久化失败后可能暂时未落盘。
+- 已确认的投递结果会先提交幂等状态，再保存使用统计；收尾期间取消请求会等待这段提交和投递租约释放后再传播取消，同键重试仍复用已确认结果。该保护区不包含审核或实际发送，不会把未确认的投递转换为成功。
 - `target.qq_id` / `target.group_id` 必须显式提供，并且必须等于已绑定目标。
 - `target.mode` 支持 `private` / `group` / `both`。
 - `message.format` 支持 `text` / `markdown` / `html`。
diff --git a/src/Undefined/api/routes/naga/send.py b/src/Undefined/api/routes/naga/send.py
index 32c39de6..4406da73 100644
--- a/src/Undefined/api/routes/naga/send.py
+++ b/src/Undefined/api/routes/naga/send.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable, Callable
 import logging
 import os
 import uuid as _uuid
@@ -26,6 +27,7 @@
     is_nagaagent_active_for_group,
     is_nagaagent_active_for_private,
 )
+from Undefined.utils.io import run_cancellation_safe
 
 logger = logging.getLogger(__name__)
 
@@ -145,6 +147,19 @@ async def naga_messages_send_handler(
             message_key,
             inflight_count,
         )
+    result_committed = False
+
+    async def commit_result(response: Response) -> None:
+        nonlocal result_committed
+        if request_uuid:
+            await naga_state.finish_request_uuid(
+                request_uuid,
+                message_key,
+                status=response.status,
+                payload=_parse_response_payload(response),
+            )
+        result_committed = True
+
     try:
         if request_uuid:
             # 可选 uuid 启用幂等：冲突/缓存/等待/owner 四态由 NagaState 协调。
@@ -203,21 +218,17 @@ async def naga_messages_send_handler(
             content=content,
             trace_id=trace_id,
             message_key=message_key,
+            commit_result=commit_result,
         )
-        if request_uuid:
-            await naga_state.finish_request_uuid(
-                request_uuid,
-                message_key,
-                status=response.status,
-                payload=_parse_response_payload(response),
-            )
+        if not result_committed:
+            await run_cancellation_safe(commit_result(response))
         return response
     except Exception as exc:
-        if request_uuid:
+        if request_uuid and not result_committed:
             await naga_state.fail_request_uuid(request_uuid, message_key, exc)
         raise
     finally:
-        remaining = await naga_state.track_send_done(message_key)
+        remaining = await run_cancellation_safe(naga_state.track_send_done(message_key))
         logger.info(
             "[NagaSend] 请求退出: trace=%s naga_id=%s bind_uuid=%s request_uuid=%s key=%s inflight_remaining=%s",
             trace_id,
@@ -247,6 +258,7 @@ async def naga_messages_send_impl(
     content: str,
     trace_id: str,
     message_key: str,
+    commit_result: Callable[[Response], Awaitable[None]] | None = None,
 ) -> Response:
     from Undefined.api.naga_store import mask_token
 
@@ -697,7 +709,6 @@ async def _ensure_delivery_active() -> tuple[Any, Response | None]:
                 status=502,
             )
 
-        await naga_store.record_usage(naga_id, bind_uuid=bind_uuid)
         partial_success = mode == "both" and (sent_private != sent_group)
         logger.info(
             "[NagaSend] 请求完成: trace=%s naga_id=%s bind_uuid=%s key=%s sent_private=%s sent_group=%s partial=%s rendered=%s fallback=%s",
@@ -711,7 +722,7 @@ async def _ensure_delivery_active() -> tuple[Any, Response | None]:
             rendered,
             render_fallback,
         )
-        return web.json_response(
+        response = web.json_response(
             {
                 "ok": True,
                 "naga_id": naga_id,
@@ -727,5 +738,23 @@ async def _ensure_delivery_active() -> tuple[Any, Response | None]:
                 "moderation": moderation,
             }
         )
+
+        async def complete_delivery() -> Response:
+            # 仅保护已经确认的结果；审核与实际发送仍可正常取消。
+            if commit_result is not None:
+                await commit_result(response)
+            try:
+                await naga_store.record_usage(naga_id, bind_uuid=bind_uuid)
+            except Exception:
+                logger.exception(
+                    "[NagaSend] 投递完成但使用统计保存失败: trace=%s naga_id=%s bind_uuid=%s key=%s",
+                    trace_id,
+                    naga_id,
+                    bind_uuid,
+                    message_key,
+                )
+            return response
+
+        return await run_cancellation_safe(complete_delivery())
     finally:
-        await naga_store.release_delivery(bind_uuid=bind_uuid)
+        await run_cancellation_safe(naga_store.release_delivery(bind_uuid=bind_uuid))
diff --git a/tests/test_runtime_api_naga.py b/tests/test_runtime_api_naga.py
index 36ceb19d..b78fb033 100644
--- a/tests/test_runtime_api_naga.py
+++ b/tests/test_runtime_api_naga.py
@@ -2,6 +2,7 @@
 
 import asyncio
 import json
+import threading
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, cast
@@ -12,7 +13,14 @@
 
 from Undefined.api import RuntimeAPIContext, RuntimeAPIServer
 from Undefined.api.naga_store import NagaStore
+from Undefined.onebot.client import OneBotDeliveryUncertainError
 from Undefined.services.security import NagaModerationResult
+from Undefined.utils import io as async_io
+
+
+@pytest.fixture(autouse=True)
+def _isolate_runtime_data(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
 
 
 def _json(response: Response) -> Any:
@@ -809,6 +817,230 @@ async def moderate_naga_message(
     assert sender.group_messages == [(456, "hello")]
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", ["group", "both"])
+async def test_naga_usage_write_failure_keeps_delivery_and_uuid_result(
+    mode: str,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    class _Sender(_FakeSender):
+        async def send_group_message(
+            self, group_id: int, message: str, **kwargs: Any
+        ) -> None:
+            if mode == "both":
+                raise RuntimeError("controlled group rejection")
+            await super().send_group_message(group_id, message, **kwargs)
+
+    path = tmp_path / "naga_bindings.json"
+    store = NagaStore(path)
+    await store.submit_binding("alice", qq_id=123, group_id=456, bind_uuid="uuid_a")
+    await store.activate_binding(
+        bind_uuid="uuid_a", naga_id="alice", delivery_signature="sig_1"
+    )
+    sender = _Sender()
+    server = _make_server(store=store, sender=sender)
+    started = threading.Event()
+    release = threading.Event()
+    original_write = async_io.write_json_sync
+    statistics_writes = 0
+
+    def write_usage(file_path: Path | str, data: Any, use_lock: bool = True) -> None:
+        nonlocal statistics_writes
+        if Path(file_path) == path:
+            statistics_writes += 1
+            started.set()
+            if not release.wait(timeout=3):
+                raise TimeoutError("usage write not released")
+            raise OSError("usage disk unavailable")
+        original_write(file_path, data, use_lock)
+
+    monkeypatch.setattr(async_io, "write_json_sync", write_usage)
+    body: dict[str, Any] = {
+        "bind_uuid": "uuid_a",
+        "naga_id": "alice",
+        "delivery_signature": "sig_1",
+        "uuid": "req-usage-failure",
+        "target": {"qq_id": 123, "group_id": 456, "mode": mode},
+        "message": {"format": "text", "content": "hello"},
+    }
+
+    async def send() -> Response:
+        return await server._naga_messages_send_handler(
+            _make_request(
+                json_body=body, headers={"Authorization": "Bearer shared-key"}
+            )
+        )
+
+    first = asyncio.create_task(send())
+    second: asyncio.Task[Response] | None = None
+    try:
+        assert await asyncio.wait_for(asyncio.to_thread(started.wait, 1), timeout=2)
+        assert len(sender.private_messages) + len(sender.group_messages) == 1
+        second = asyncio.create_task(send())
+        await asyncio.sleep(0)
+        assert not first.done()
+        release.set()
+        first_response, second_response = await asyncio.wait_for(
+            asyncio.gather(first, second), timeout=2
+        )
+        retry_response = await send()
+        assert (
+            first_response.status
+            == second_response.status
+            == retry_response.status
+            == 200
+        )
+        payload = _json(first_response)
+        assert payload == _json(second_response) == _json(retry_response)
+        assert payload["ok"] is True
+        assert payload["sent_private"] is (mode == "both")
+        assert payload["sent_group"] is (mode == "group")
+        assert payload["partial_success"] is (mode == "both")
+        assert len(sender.private_messages) + len(sender.group_messages) == 1
+        assert statistics_writes == 1
+        assert not store._active_deliveries
+        assert not server._naga_state.request_uuid_inflight
+        assert "req-usage-failure" in server._naga_state.request_uuid_results
+        assert "使用统计保存失败" in caplog.text
+        assert (
+            json.loads(path.read_text(encoding="utf-8"))["bindings"]["alice"][
+                "use_count"
+            ]
+            == 0
+        )
+    finally:
+        release.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )
+        await server.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("statistics_fail", [False, True])
+async def test_naga_cancel_after_delivery_commits_uuid_before_propagating(
+    statistics_fail: bool,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    path = tmp_path / "naga_bindings.json"
+    store = NagaStore(path)
+    await store.submit_binding("alice", qq_id=123, group_id=456, bind_uuid="uuid_a")
+    await store.activate_binding(
+        bind_uuid="uuid_a", naga_id="alice", delivery_signature="sig_1"
+    )
+    sender = _FakeSender()
+    server = _make_server(store=store, sender=sender)
+    started = threading.Event()
+    release = threading.Event()
+    original_write = async_io.write_json_sync
+    writes = 0
+
+    def write_usage(file_path: Path | str, data: Any, use_lock: bool = True) -> None:
+        nonlocal writes
+        if Path(file_path) == path:
+            writes += 1
+            started.set()
+            if not release.wait(timeout=3):
+                raise TimeoutError("usage write not released")
+            if statistics_fail:
+                raise OSError("usage disk unavailable")
+        original_write(file_path, data, use_lock)
+
+    monkeypatch.setattr(async_io, "write_json_sync", write_usage)
+    body: dict[str, Any] = {
+        "bind_uuid": "uuid_a",
+        "naga_id": "alice",
+        "delivery_signature": "sig_1",
+        "uuid": "req-cancelled-usage",
+        "target": {"qq_id": 123, "group_id": 456, "mode": "group"},
+        "message": {"format": "text", "content": "hello"},
+    }
+
+    async def send() -> Response:
+        return await server._naga_messages_send_handler(
+            _make_request(
+                json_body=body, headers={"Authorization": "Bearer shared-key"}
+            )
+        )
+
+    owner = asyncio.create_task(send())
+    try:
+        assert await asyncio.wait_for(asyncio.to_thread(started.wait, 1), timeout=2)
+        assert sender.group_messages == [(456, "hello")]
+        assert "req-cancelled-usage" in server._naga_state.request_uuid_results
+        assert not server._naga_state.request_uuid_inflight
+        owner.cancel()
+        await asyncio.sleep(0)
+        owner.cancel()
+        await asyncio.sleep(0)
+        assert not owner.done()
+        assert store._active_deliveries == {"uuid_a": 1}
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(owner, timeout=2)
+        assert not store._active_deliveries
+        assert not server._naga_state.send_inflight
+        retry = await send()
+        assert retry.status == 200
+        assert _json(retry)["sent_group"] is True
+        assert sender.group_messages == [(456, "hello")]
+        assert writes == 1
+        assert json.loads(path.read_text(encoding="utf-8"))["bindings"]["alice"][
+            "use_count"
+        ] == (0 if statistics_fail else 1)
+    finally:
+        release.set()
+        await asyncio.gather(owner, return_exceptions=True)
+        await server.stop()
+
+
+@pytest.mark.asyncio
+async def test_naga_uncertain_delivery_does_not_become_confirmed_success(
+    tmp_path: Path,
+) -> None:
+    class _UncertainSender(_FakeSender):
+        calls = 0
+
+        async def send_group_message(
+            self, group_id: int, message: str, **_kwargs: Any
+        ) -> None:
+            self.calls += 1
+            raise OneBotDeliveryUncertainError(
+                "send_group_msg", "controlled missing acknowledgement"
+            )
+
+    store = NagaStore(tmp_path / "naga_bindings.json")
+    await store.submit_binding("alice", qq_id=123, group_id=456, bind_uuid="uuid_a")
+    await store.activate_binding(
+        bind_uuid="uuid_a", naga_id="alice", delivery_signature="sig_1"
+    )
+    sender = _UncertainSender()
+    server = _make_server(store=store, sender=sender)
+    body: dict[str, Any] = {
+        "bind_uuid": "uuid_a",
+        "naga_id": "alice",
+        "delivery_signature": "sig_1",
+        "uuid": "req-uncertain",
+        "target": {"qq_id": 123, "group_id": 456, "mode": "group"},
+        "message": {"format": "text", "content": "hello"},
+    }
+    request = _make_request(
+        json_body=body, headers={"Authorization": "Bearer shared-key"}
+    )
+    first = await server._naga_messages_send_handler(request)
+    retry = await server._naga_messages_send_handler(request)
+    assert first.status == retry.status == 502
+    assert _json(first) == _json(retry)
+    assert _json(first)["ok"] is False
+    assert _json(first)["sent_group"] is False
+    assert sender.calls == 1
+    assert not store._active_deliveries
+    await server.stop()
+
+
 @pytest.mark.asyncio
 async def test_naga_messages_send_deduplicates_inflight_uuid(
     tmp_path: Path,

From 818146158ee7c05cde657f5510b57c85fef07be6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:36:31 +0800
Subject: [PATCH 056/121] fix(webui): honor configurable graceful shutdown
 deadlines

---
 config.toml.example                           |  3 +
 docs/configuration.md                         | 10 +++-
 docs/deployment.md                            |  2 +
 src/Undefined/config/config_class.py          |  1 +
 src/Undefined/config/env_registry.py          |  1 +
 src/Undefined/config/load_sections/domains.py |  1 +
 src/Undefined/config/webui_settings.py        | 16 +++++
 src/Undefined/webui/app.py                    |  5 +-
 src/Undefined/webui/core.py                   | 15 ++++-
 tests/test_webui_process_shutdown.py          | 60 +++++++++++++++++++
 tests/test_webui_settings.py                  | 24 ++++++++
 11 files changed, 134 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_webui_process_shutdown.py

diff --git a/config.toml.example b/config.toml.example
index 21a67eae..276dc338 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -1685,6 +1685,9 @@ autostart_bot = false
 # zh: 每次打开 WebUI 时是否在后台检查 GitHub Release 更新。
 # en: Check GitHub Releases for updates in the background whenever WebUI is opened.
 check_updates = true
+# zh: 停止机器人时等待优雅收尾的秒数；0 等待自然结束，正整数超时后强制终止。
+# en: Graceful bot shutdown timeout in seconds; 0 waits until completion, positive values force termination after the deadline.
+stop_timeout_seconds = 0
 
 # zh: 微信 ClawBot/iLink 私聊接入。凭据与游标仅写入 state_dir，不写入本配置。
 # zh: 关闭时不会创建网络连接；二维码登录只能从管理界面显式发起。
diff --git a/docs/configuration.md b/docs/configuration.md
index 03155a73..5e35059d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1205,6 +1205,7 @@ api_key = "replace-with-your-key"
 | `password` | `changeme` | WebUI 登录密码 |
 | `autostart_bot` | `false` | WebUI 启动时是否自动启动机器人进程 |
 | `check_updates` | `true` | 打开 WebUI 时是否在后台检查 GitHub 正式 Release |
+| `stop_timeout_seconds` | `0` | 停止 Bot 的收尾期限（秒）；`0` 等待自然结束，正整数超时后强制终止 |
 
 关键行为：
 
@@ -1214,6 +1215,7 @@ api_key = "replace-with-your-key"
 - `webui.password` 在配置成功加载后立即刷新 Management 的登录密码，无需重启 WebUI。
 - `webui.autostart_bot` 控制下一次 WebUI 启动时是否自动启动机器人；修改不会立即启动或停止当前机器人进程。
 - `check_updates` 支持热更新；关闭后只停止页面打开时的自动检查，概览页仍可手动检查。
+- `stop_timeout_seconds` 支持热更新，下一次停止操作读取新值，进行中的停止保持开始时的期限。默认等待模型、下载、回复和历史收尾；设置正整数时需覆盖实际收尾耗时，超时强制终止可能跳过未完成的落盘。环境变量为 `WEBUI_STOP_TIMEOUT_SECONDS`，TOML 显式配置优先。
 - `autostart_bot=true` 时，运行 `uv run Undefined-webui` 会自动拉起 bot 进程，无需手动点击启动按钮；与 WebUI 更新重启后的自动恢复机制（`pending_bot_autostart` marker）互不冲突。
 - `uv run deploy up` 在 `container` 与 `host` 模式下都会写入 `autostart_bot = false`；部署后先完成配置与 QQ 登录，再在 WebUI 点击“启动机器人”。
 - 自动检查在 WebUI 鉴权成功后异步执行，失败不会阻塞或打扰页面。GitHub Release 查询在 WebUI 进程内缓存 15 分钟；同一时刻的并发检查会共享一个在途任务，查询失败时也不会逐个重试外部请求。
@@ -1465,7 +1467,7 @@ Management 的 WebUI 配置按 [§4.23](#423-webui) 的时机生效：密码和
 
 ### 5.3 明确“会执行热应用”的字段
 
-- `webui.password` / `webui.check_updates`（Management 的登录密码与检查更新开关立即刷新）
+- `webui.password` / `webui.check_updates` / `webui.stop_timeout_seconds`（Management 的登录密码、检查更新开关与下次停止的收尾期限刷新）
 - `onebot.file_send_mode` / `onebot.file_send_host`（新投递读取快照；进行中投递及旧 URL 生命周期不变）
 - 模型发车间隔 / 模型名 / 模型池变更（队列间隔刷新）
 - `models.grok.model_name` / `models.grok.queue_interval_seconds`（队列间隔刷新）
@@ -1920,6 +1922,12 @@ TOML 语法错误、编码错误或读取失败会中止本次加载，热重载
 |-----------|----------|
 | `weather.api_key` | `WEATHER_API_KEY` |
 
+#### `webui`
+
+| TOML 路径 | 环境变量 |
+|-----------|----------|
+| `webui.stop_timeout_seconds` | `WEBUI_STOP_TIMEOUT_SECONDS` |
+
 #### `xxapi`
 
 | TOML 路径 | 环境变量 |
diff --git a/docs/deployment.md b/docs/deployment.md
index 769b998f..3dc85806 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -158,6 +158,8 @@ uv run Undefined-webui
 
 `SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：先停止 QQ、微信与普通 Runtime API 的新接入，等待已接受的入站处理和 API 请求收尾，停止史官 / memes worker，再由消息处理器排空 AI 队列并落盘历史。排空期间保留 OneBot 响应接收、微信发送和 Runtime 文件下载能力，回复完成后才关闭传输、AI 客户端、检索运行时与渲染资源。等待 worker 收尾期间模型队列保持可用，史官在向量写入后继续提交侧写模型请求也能完成；消息处理器收尾时新落盘的认知任务留待下次启动处理。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程；其强制终止等待时间应覆盖实际模型和下载收尾耗时。请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
 
+WebUI 停止 Bot 默认等待优雅收尾自然完成；如需设置强制终止期限，配置 `[webui].stop_timeout_seconds` 为正整数秒，`0` 表示不设置期限。它不改变 Docker 或 systemd 自己的停止期限，请同时给外层进程管理器留足时间。
+
 #### 自动启动选项
 
 若希望 WebUI 启动后自动拉起机器人进程，可在 `config.toml` 中设置：
diff --git a/src/Undefined/config/config_class.py b/src/Undefined/config/config_class.py
index 968c7d2c..a4b32c4e 100644
--- a/src/Undefined/config/config_class.py
+++ b/src/Undefined/config/config_class.py
@@ -154,6 +154,7 @@ class Config:
     webui_password: str
     webui_autostart_bot: bool
     webui_check_updates: bool
+    webui_stop_timeout_seconds: int
     api: APIConfig
     weixin: WeixinConfig
     # Code Delivery Agent
diff --git a/src/Undefined/config/env_registry.py b/src/Undefined/config/env_registry.py
index d017a969..2bbbb83e 100644
--- a/src/Undefined/config/env_registry.py
+++ b/src/Undefined/config/env_registry.py
@@ -44,6 +44,7 @@
 
 # TOML 路径 → 环境变量名；供 _get_value 在 TOML 缺省时回退，以及文档/工具生成
 ENV_REGISTRY: Final[dict[tuple[str, ...], str]] = {
+    ("webui", "stop_timeout_seconds"): "WEBUI_STOP_TIMEOUT_SECONDS",
     **_GENERATION_MODEL_ENV_REGISTRY,
     ("access", "allowed_group_ids"): "ALLOWED_GROUP_IDS",
     ("access", "allowed_private_ids"): "ALLOWED_PRIVATE_IDS",
diff --git a/src/Undefined/config/load_sections/domains.py b/src/Undefined/config/load_sections/domains.py
index d3a78898..6b889147 100644
--- a/src/Undefined/config/load_sections/domains.py
+++ b/src/Undefined/config/load_sections/domains.py
@@ -53,6 +53,7 @@ def load_domains(data: dict[str, Any]) -> dict[str, Any]:
         "webui_password": webui_settings.password,
         "webui_autostart_bot": webui_settings.autostart_bot,
         "webui_check_updates": webui_settings.check_updates,
+        "webui_stop_timeout_seconds": webui_settings.stop_timeout_seconds,
         "api": api_config,
         "cognitive": cognitive,
         "memes": memes,
diff --git a/src/Undefined/config/webui_settings.py b/src/Undefined/config/webui_settings.py
index 1372627b..c8cd8854 100644
--- a/src/Undefined/config/webui_settings.py
+++ b/src/Undefined/config/webui_settings.py
@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any, Optional
 
 from .coercers import _coerce_bool, _coerce_int, _coerce_str, _normalize_str, _get_value
+from .env_registry import env_key_for_path
 
 if TYPE_CHECKING:
     from .config_class import Config
@@ -16,6 +17,7 @@
 DEFAULT_WEBUI_PASSWORD = "changeme"
 DEFAULT_WEBUI_AUTOSTART_BOT = False
 DEFAULT_WEBUI_CHECK_UPDATES = True
+DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS = 0
 
 
 @dataclass
@@ -27,6 +29,7 @@ class WebUISettings:
     check_updates: bool
     using_default_password: bool
     config_exists: bool
+    stop_timeout_seconds: int = DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
 
     @classmethod
     def from_config(cls, config: Config, *, config_exists: bool) -> WebUISettings:
@@ -40,6 +43,7 @@ def from_config(cls, config: Config, *, config_exists: bool) -> WebUISettings:
             check_updates=config.webui_check_updates,
             using_default_password=password == DEFAULT_WEBUI_PASSWORD,
             config_exists=config_exists,
+            stop_timeout_seconds=config.webui_stop_timeout_seconds,
         )
 
     @property
@@ -71,6 +75,16 @@ def parse_webui_settings(data: dict[str, Any]) -> WebUISettings:
         port = DEFAULT_WEBUI_PORT
     autostart_bot = _coerce_bool(autostart_bot_value, DEFAULT_WEBUI_AUTOSTART_BOT)
     check_updates = _coerce_bool(check_updates_value, DEFAULT_WEBUI_CHECK_UPDATES)
+    stop_timeout_seconds = _coerce_int(
+        _get_value(
+            data,
+            ("webui", "stop_timeout_seconds"),
+            env_key_for_path(("webui", "stop_timeout_seconds")),
+        ),
+        DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS,
+    )
+    if stop_timeout_seconds < 0:
+        stop_timeout_seconds = DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
 
     password_normalized = _normalize_str(password_value)
     if not password_normalized:
@@ -82,6 +96,7 @@ def parse_webui_settings(data: dict[str, Any]) -> WebUISettings:
             check_updates=check_updates,
             using_default_password=True,
             config_exists=config_exists,
+            stop_timeout_seconds=stop_timeout_seconds,
         )
     return WebUISettings(
         url=url,
@@ -91,4 +106,5 @@ def parse_webui_settings(data: dict[str, Any]) -> WebUISettings:
         check_updates=check_updates,
         using_default_password=password_normalized == DEFAULT_WEBUI_PASSWORD,
         config_exists=config_exists,
+        stop_timeout_seconds=stop_timeout_seconds,
     )
diff --git a/src/Undefined/webui/app.py b/src/Undefined/webui/app.py
index 9833ba3f..2bc897a3 100644
--- a/src/Undefined/webui/app.py
+++ b/src/Undefined/webui/app.py
@@ -298,12 +298,14 @@ def create_app(*, redirect_to_config_once: bool = False) -> web.Application:
     )
 
     # 初始化核心组件
-    app[BOT_APP_KEY] = BotProcessController()
     app[SESSION_STORE_APP_KEY] = SessionStore()
 
     # 配置 WebUI 设置热重载
     config_manager = get_config_manager()
     app[SETTINGS_APP_KEY] = load_webui_settings()
+    app[BOT_APP_KEY] = BotProcessController(
+        stop_timeout_getter=lambda: app[SETTINGS_APP_KEY].stop_timeout_seconds
+    )
 
     # 一次性客户端重定向提示（由 index 处理）
     app[REDIRECT_TO_CONFIG_ONCE_APP_KEY] = redirect_to_config_once
@@ -315,6 +317,7 @@ def _on_config_change(config: Config, changes: dict[str, Any]) -> None:
             "webui_password",
             "webui_autostart_bot",
             "webui_check_updates",
+            "webui_stop_timeout_seconds",
         }
         if any(key.startswith("webui.") for key in changes) or webui_keys.intersection(
             changes
diff --git a/src/Undefined/webui/core.py b/src/Undefined/webui/core.py
index db41f46e..bd09d447 100644
--- a/src/Undefined/webui/core.py
+++ b/src/Undefined/webui/core.py
@@ -1,4 +1,5 @@
 import asyncio
+from collections.abc import Callable
 from dataclasses import dataclass
 import logging
 import os
@@ -8,6 +9,7 @@
 import time
 import secrets
 from typing import Any
+from Undefined.config.webui_settings import DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
 
 logger = logging.getLogger(__name__)
 
@@ -118,7 +120,9 @@ def clear(self) -> None:
 
 
 class BotProcessController:
-    def __init__(self) -> None:
+    def __init__(
+        self, *, stop_timeout_getter: Callable[[], float] | None = None
+    ) -> None:
         self._process: asyncio.subprocess.Process | None = None
         self._started_at: float | None = None
         self._lock = asyncio.Lock()
@@ -127,6 +131,9 @@ def __init__(self) -> None:
         self._start_new_session = not self._is_windows
         self._creationflags = 0
         self._ctrl_break_signal: int | None = None
+        self._stop_timeout_getter = stop_timeout_getter or (
+            lambda: DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
+        )
         if self._is_windows:
             self._creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
             self._ctrl_break_signal = getattr(signal, "CTRL_BREAK_EVENT", None)
@@ -193,6 +200,7 @@ async def stop(self) -> dict[str, Any]:
                 return self.status()
             logger.info("[WebUI] 停止机器人进程: pid=%s", self._process.pid)
             process = self._process
+            stop_timeout = self._stop_timeout_getter()
             try:
                 if self._start_new_session and process.pid:
                     try:
@@ -211,7 +219,10 @@ async def stop(self) -> dict[str, Any]:
                     process.terminate()
 
                 try:
-                    await asyncio.wait_for(process.wait(), timeout=5)
+                    await asyncio.wait_for(
+                        process.wait(),
+                        timeout=stop_timeout if stop_timeout > 0 else None,
+                    )
                 except asyncio.TimeoutError:
                     logger.warning("[WebUI] 机器人进程未及时退出，强制终止")
                     if self._start_new_session and process.pid:
diff --git a/tests/test_webui_process_shutdown.py b/tests/test_webui_process_shutdown.py
new file mode 100644
index 00000000..deb8156c
--- /dev/null
+++ b/tests/test_webui_process_shutdown.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+import sys
+
+import pytest
+
+from Undefined.webui import core
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(os.name == "nt", reason="POSIX SIGTERM child fixture")
+@pytest.mark.parametrize("force_timeout", [None, 0.05])
+async def test_stop_honors_graceful_completion_and_configured_deadline(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    force_timeout: float | None,
+) -> None:
+    child = tmp_path / "child.py"
+    child.write_text(
+        "import asyncio, signal\n"
+        "from pathlib import Path\n"
+        "async def main() -> None:\n"
+        "    root = Path(__file__).parent\n"
+        "    stop = asyncio.Event()\n"
+        "    asyncio.get_running_loop().add_signal_handler(signal.SIGTERM, stop.set)\n"
+        "    (root / 'ready').touch()\n"
+        "    await stop.wait()\n"
+        "    (root / 'started').touch()\n"
+        "    await asyncio.sleep(6)\n"
+        "    (root / 'finished').touch()\n"
+        "asyncio.run(main())\n"
+    )
+    monkeypatch.setattr(core, "BOT_COMMAND", (sys.executable, str(child)))
+    controller = core.BotProcessController(
+        stop_timeout_getter=(lambda: force_timeout)
+        if force_timeout is not None
+        else None
+    )
+    await controller.start()
+    process = controller._process
+    assert process is not None
+
+    async def ready() -> None:
+        while not (tmp_path / "ready").exists():
+            await asyncio.sleep(0.01)
+
+    try:
+        await asyncio.wait_for(ready(), 3)
+        status = await asyncio.wait_for(controller.stop(), 8)
+        assert not status["running"]
+        assert (tmp_path / "started").exists()
+        assert (tmp_path / "finished").exists() is (force_timeout is None)
+        assert (process.returncode == 0) is (force_timeout is None)
+    finally:
+        if process.returncode is None:
+            process.kill()
+            await process.wait()
diff --git a/tests/test_webui_settings.py b/tests/test_webui_settings.py
index bdad95da..5442e8b9 100644
--- a/tests/test_webui_settings.py
+++ b/tests/test_webui_settings.py
@@ -229,3 +229,27 @@ def test_settings_from_config_preserves_snapshot_metadata(
     assert settings.check_updates is False
     assert settings.using_default_password is (password == "changeme")
     assert settings.config_exists is config_exists
+
+
+@pytest.mark.parametrize("timeout", [0, 30, 600])
+def test_stop_timeout_uses_config_snapshot(timeout: int) -> None:
+    config = Config.from_mapping(
+        {"webui": {"stop_timeout_seconds": timeout}}, strict=False
+    )
+    settings = WebUISettings.from_config(config, config_exists=True)
+    assert settings.stop_timeout_seconds == timeout
+
+
+def test_stop_timeout_environment_fallback_and_toml_precedence(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("WEBUI_STOP_TIMEOUT_SECONDS", "120")
+    config = Config.from_mapping({}, strict=False)
+    assert config.webui_stop_timeout_seconds == 120
+    config = Config.from_mapping({"webui": {"stop_timeout_seconds": 0}}, strict=False)
+    assert config.webui_stop_timeout_seconds == 0
+
+
+def test_negative_stop_timeout_uses_unlimited_default() -> None:
+    config = Config.from_mapping({"webui": {"stop_timeout_seconds": -1}}, strict=False)
+    assert config.webui_stop_timeout_seconds == 0

From 9f0d087b817f1d459142b2bb1fd28385db501fad Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:36:33 +0800
Subject: [PATCH 057/121] fix(webui): serialize config saves and preserve
 distinct backups

---
 docs/webui-guide.md                          |   6 +-
 src/Undefined/webui/routes/_config.py        |  26 +++-
 src/Undefined/webui/static/js/config-form.js |  73 +++++++----
 tests/frontend/runtime_chat_harness.js       | 113 ++++++++++++++++-
 tests/test_webui_config_backups.py           | 121 +++++++++++++++++++
 tests/test_webui_config_save_behavior.py     |  61 ++++++++++
 6 files changed, 370 insertions(+), 30 deletions(-)
 create mode 100644 tests/test_webui_config_backups.py
 create mode 100644 tests/test_webui_config_save_behavior.py

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 2049262e..f33aa3cd 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -54,18 +54,20 @@ WebUI 的主要页签如下。
 
 页面会自动刷新，也可手动触发。
 
+停止 Bot 时，WebUI 默认等待运行中的任务自然完成收尾；`[webui].stop_timeout_seconds` 默认为 `0`，设置为正整数后才会在对应秒数超时后强制终止。热更新后的值从下一次停止操作生效。
+
 ### 配置管理（Config）
 
 提供两种编辑方式：
 
-- **表单模式**：按固定纵向顺序展示配置分组，组内字段会根据可用宽度自动排布；浏览长分组时标题和折叠入口会保持可见，展开或折叠不会打乱其他分组的位置。
+- **表单模式**：按固定纵向顺序展示配置分组，组内字段会根据可用宽度自动排布；浏览长分组时标题和折叠入口会保持可见，展开或折叠不会打乱其他分组的位置。自动保存按顺序提交，保存期间的连续修改会合并为最新表单快照；只有最新修改保存成功后才显示“已保存”。
 - **TOML 原始编辑器**：直接编辑 `config.toml` 文本，带语法高亮，适合批量变更。
 
 其他能力：
 
 - **验证**：保存前自动进行 TOML 语法检查和严格配置校验，错误项会标红提示。
 - **搜索与折叠**：搜索会临时展开匹配分组并保留原折叠状态，清除搜索后自动恢复；也可使用“全部展开 / 全部折叠”快速整理页面。
-- **配置历史**：每次保存自动生成带时间戳的备份（最多 50 版本），可随时回滚到任意历史版本。
+- **配置历史**：每次保存自动生成带时间戳和唯一后缀的备份（最多 50 版本），同一秒内保存也会分别保留；历史按备份生成时间列出，可随时回滚到任意历史版本，旧版备份仍可使用。
 - **模板同步**：一键将 `config.toml.example` 中新增的配置项合并到当前配置，不覆盖已有值。
 
 > 配置支持热更新——大多数配置项修改后即时生效，无需重启 Bot。需要重启的项（如 `onebot_ws_url`、`webui_port`）会在保存时提示。
diff --git a/src/Undefined/webui/routes/_config.py b/src/Undefined/webui/routes/_config.py
index e3f44e43..6a1832e1 100644
--- a/src/Undefined/webui/routes/_config.py
+++ b/src/Undefined/webui/routes/_config.py
@@ -29,6 +29,13 @@
 _MAX_BACKUPS = 50
 
 
+def _config_backups() -> list[Path]:
+    return sorted(
+        _BACKUP_DIR.glob("config_*.toml"),
+        key=lambda path: (path.stat().st_mtime_ns, path.name),
+    )
+
+
 def _backup_config() -> str | None:
     """Create a timestamped backup of the current config.toml.
 
@@ -37,14 +44,21 @@ def _backup_config() -> str | None:
     if not CONFIG_PATH.exists():
         return None
     _BACKUP_DIR.mkdir(parents=True, exist_ok=True)
-    ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
-    backup_name = f"config_{ts}.toml"
-    shutil.copy2(CONFIG_PATH, _BACKUP_DIR / backup_name)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S_%f")
+    with NamedTemporaryFile(
+        prefix=f"config_{ts}_", suffix=".toml", dir=_BACKUP_DIR, delete=False
+    ) as backup:
+        backup_path = Path(backup.name)
+    try:
+        shutil.copyfile(CONFIG_PATH, backup_path)
+    except Exception:
+        backup_path.unlink(missing_ok=True)
+        raise
     # Trim old backups beyond the cap
-    backups = sorted(_BACKUP_DIR.glob("config_*.toml"))
+    backups = _config_backups()
     while len(backups) > _MAX_BACKUPS:
         backups.pop(0).unlink(missing_ok=True)
-    return backup_name
+    return backup_path.name
 
 
 @routes.get("/api/v1/management/config")
@@ -222,7 +236,7 @@ async def config_history_handler(request: web.Request) -> Response:
     if not _BACKUP_DIR.exists():
         return web.json_response({"backups": []})
     backups: list[dict[str, object]] = []
-    for f in sorted(_BACKUP_DIR.glob("config_*.toml"), reverse=True):
+    for f in reversed(_config_backups()):
         stat = f.stat()
         backups.append({"name": f.name, "size": stat.st_size, "mtime": stat.st_mtime})
     return web.json_response({"backups": backups})
diff --git a/src/Undefined/webui/static/js/config-form.js b/src/Undefined/webui/static/js/config-form.js
index 1b00b5ed..e77e6182 100644
--- a/src/Undefined/webui/static/js/config-form.js
+++ b/src/Undefined/webui/static/js/config-form.js
@@ -1,5 +1,8 @@
 let configFormLayoutInitialized = false;
 let configLayoutResizeObserver = null;
+let configSavePromise = null;
+let configPendingSave = null;
+let configSaveRevision = 0;
 
 function getConfigStickyChromeElements() {
     return [
@@ -123,6 +126,7 @@ function isRequestParamsPath(path) {
 }
 
 function scheduleAutoSave() {
+    configSaveRevision += 1;
     if (state.saveTimer) clearTimeout(state.saveTimer);
     showSaveStatus("saving", t("config.typing"));
     state.saveTimer = setTimeout(() => {
@@ -382,10 +386,15 @@ function showSaveStatus(status, text) {
         el.classList.add("active");
         txt.innerText = text || t("config.saving");
     } else if (status === "saved") {
+        const revision = configSaveRevision;
         el.classList.remove("active");
         txt.innerText = text || t("config.saved");
         setTimeout(() => {
-            if (!state.saveTimer) {
+            if (
+                !state.saveTimer &&
+                state.saveStatus === "saved" &&
+                revision === configSaveRevision
+            ) {
                 el.style.opacity = "0";
                 state.saveStatus = "idle";
                 updateSaveStatusText();
@@ -1232,6 +1241,9 @@ function parseInputValue(input) {
 }
 
 async function autoSave() {
+    if (state.saveTimer) clearTimeout(state.saveTimer);
+    state.saveTimer = null;
+    configSaveRevision += 1;
     showSaveStatus("saving");
 
     const patch = {};
@@ -1271,27 +1283,46 @@ async function autoSave() {
         patch[aotPath] = entries;
     });
 
-    try {
-        const res = await api("/api/patch", {
-            method: "POST",
-            body: JSON.stringify({ patch }),
-        });
-        const data = await res.json();
-        if (data.success) {
-            showSaveStatus("saved");
-            if (data.warning)
-                showToast(
-                    `${t("common.warning")}: ${data.warning}`,
-                    "warning",
-                    5000,
-                );
-        } else {
-            showSaveStatus("error", t("config.save_error"));
-            showToast(`${t("common.error")}: ${data.error}`, "error", 5000);
+    configPendingSave = { patch, revision: configSaveRevision };
+    if (configSavePromise) return configSavePromise;
+    configSavePromise = (async () => {
+        while (configPendingSave) {
+            const pending = configPendingSave;
+            configPendingSave = null;
+            try {
+                const res = await api("/api/patch", {
+                    method: "POST",
+                    body: JSON.stringify({ patch: pending.patch }),
+                });
+                const data = await res.json();
+                if (pending.revision !== configSaveRevision) continue;
+                if (data.success) {
+                    showSaveStatus("saved");
+                    if (data.warning)
+                        showToast(
+                            `${t("common.warning")}: ${data.warning}`,
+                            "warning",
+                            5000,
+                        );
+                } else {
+                    showSaveStatus("error", t("config.save_error"));
+                    showToast(
+                        `${t("common.error")}: ${data.error}`,
+                        "error",
+                        5000,
+                    );
+                }
+            } catch (e) {
+                if (pending.revision !== configSaveRevision) continue;
+                showSaveStatus("error", t("config.save_network_error"));
+                showToast(`${t("common.error")}: ${e.message}`, "error", 5000);
+            }
         }
-    } catch (e) {
-        showSaveStatus("error", t("config.save_network_error"));
-        showToast(`${t("common.error")}: ${e.message}`, "error", 5000);
+    })();
+    try {
+        await configSavePromise;
+    } finally {
+        configSavePromise = null;
     }
 }
 
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index b5a2d507..e85bf0e8 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -226,6 +226,9 @@ function createEnv(root, options = {}) {
             get() {
                 return this.textContent;
             },
+            set(value) {
+                this.textContent = value;
+            },
             configurable: true,
         });
     }
@@ -318,6 +321,7 @@ function createEnv(root, options = {}) {
             path.join(staticDir, name),
         ),
         path.join(staticDir, "runtime.js"),
+        ...(options.scripts || []).map((name) => path.join(staticDir, name)),
     ];
     // harness 专用垫片：产品脚本里 `const state = {...}` 属于这次 eval 的词法作用域，
     // 后续 window.eval 看不到它。只有拼在同一次 eval 里才能改 `state.authenticated`
@@ -3285,6 +3289,109 @@ for (const target of ["other", "same"]) {
     }
 }
 
+async function configAutoSave(env, outcome) {
+    const { window, response } = env;
+    env.setRoutes([
+        { match: "/api/config/summary", reply: { body: {
+            data: { onebot: { file_send_mode: "local", file_send_host: "initial" } }, comments: {},
+        } } },
+    ]);
+    const fetch = window.fetch;
+    const pending = [];
+    let inFlight = 0;
+    let maxInFlight = 0;
+    let saved = null;
+    window.fetch = (url, options) => {
+        if (String(url) === "/api/patch") {
+            inFlight += 1;
+            maxInFlight = Math.max(maxInFlight, inFlight);
+            return new Promise((resolve, reject) => {
+                pending.push({ patch: JSON.parse(options.body).patch, resolve, reject });
+            });
+        }
+        return fetch(url, options);
+    };
+    await window.loadConfig();
+    const mode = window.document.querySelector('[data-path="onebot.file_send_mode"].config-input');
+    const host = window.document.querySelector('[data-path="onebot.file_send_host"].config-input');
+    if (!mode || !host) throw new Error("config form was not built");
+    const changeMode = (value) => {
+        mode.value = value;
+        mode.dispatchEvent(new window.Event("change", { bubbles: true }));
+    };
+    const snapshot = () => ({
+        requestCount: pending.length,
+        status: textOf(window, "saveStatusText"),
+        active: window.document.getElementById("saveStatus").classList.contains("active"),
+        opacity: window.document.getElementById("saveStatus").style.opacity,
+        toasts: window.document.querySelector(".toast-container")?.textContent || "",
+    });
+    const finish = (index, result = { success: true }) => {
+        inFlight -= 1;
+        if (result.success) saved = pending[index].patch;
+        pending[index].resolve(response(200, result));
+    };
+    changeMode("stream");
+    await tick();
+    if (outcome === "saved_timer") {
+        finish(0);
+        await tick();
+        changeMode("url");
+        await tick();
+        await settle(2100);
+        const whilePending = snapshot();
+        finish(1);
+        await tick();
+        return { whilePending, final: snapshot(), saved, maxInFlight };
+    }
+    if (outcome === "typing") {
+        host.value = "updated-host";
+        host.dispatchEvent(new window.Event("input", { bubbles: true }));
+    } else {
+        changeMode("url");
+        changeMode("local");
+    }
+    await tick();
+    const beforeOldResponse = snapshot();
+    if (outcome === "network_error") {
+        inFlight -= 1;
+        pending[0].reject(new Error("obsolete save failure"));
+    } else {
+        finish(0, outcome === "api_error"
+            ? { success: false, error: "obsolete save failure" }
+            : { success: true, warning: "obsolete save warning" });
+    }
+    await tick();
+    const afterOldResponse = snapshot();
+    if (outcome === "typing") await settle(1100);
+    if (pending.length !== 2) throw new Error(`expected latest save after old response, got ${pending.length}`);
+    if (outcome.startsWith("latest_")) {
+        if (outcome === "latest_network_error") {
+            inFlight -= 1;
+            pending[1].reject(new Error("latest save failure"));
+        } else {
+            finish(1, { success: false, error: "latest save failure" });
+        }
+        await tick();
+        const afterFailure = snapshot();
+        changeMode("url");
+        await tick();
+        finish(2);
+        await tick();
+        return { afterFailure, final: snapshot(), saved, maxInFlight };
+    }
+    finish(1);
+    await tick();
+    return {
+        beforeOldResponse, afterOldResponse, final: snapshot(), maxInFlight, saved,
+        patches: pending.map((entry) => entry.patch),
+    };
+}
+
+for (const outcome of ["success", "network_error", "api_error", "typing", "saved_timer", "latest_network_error", "latest_api_error"]) {
+    SCENARIOS[`config_autosave_${outcome}`] = (env) => configAutoSave(env, outcome);
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
@@ -3295,7 +3402,11 @@ async function main() {
         );
     }
     const root = resolveRoot(args.root);
-    const env = createEnv(root);
+    const env = createEnv(root, {
+        scripts: args.scenario.startsWith("config_autosave_")
+            ? ["config-form.js"]
+            : [],
+    });
     const result = await scenario(env);
     process.stdout.write(
         `${JSON.stringify({ ok: true, scenario: args.scenario, result })}\n`,
diff --git a/tests/test_webui_config_backups.py b/tests/test_webui_config_backups.py
new file mode 100644
index 00000000..b74984fa
--- /dev/null
+++ b/tests/test_webui_config_backups.py
@@ -0,0 +1,121 @@
+"""配置备份的同秒保存、历史顺序及恢复兼容性回归。"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+from aiohttp import web
+
+from Undefined.webui.routes import _config
+
+
+class ConfigRequest(SimpleNamespace):
+    async def json(self) -> dict[str, object]:
+        return cast(dict[str, object], self.body)
+
+
+@pytest.fixture
+def backup_config(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    config_path = tmp_path / "config.toml"
+    backup_dir = tmp_path / "config_backups"
+    monkeypatch.setattr(_config, "CONFIG_PATH", config_path)
+    monkeypatch.setattr(_config, "_BACKUP_DIR", backup_dir)
+    monkeypatch.setattr(_config, "check_auth", lambda _request: True)
+
+    class FrozenDatetime:
+        @staticmethod
+        def now(_tz: object) -> datetime:
+            return datetime(2026, 10, 6, 12, 0, 0, tzinfo=timezone.utc)
+
+    monkeypatch.setattr(_config, "datetime", FrozenDatetime)
+    return config_path
+
+
+def test_same_timestamp_backups_preserve_each_saved_version(
+    backup_config: Path,
+) -> None:
+    names: list[str] = []
+    for value in ("first", "second", "third"):
+        backup_config.write_text(f'value = "{value}"\n', encoding="utf-8")
+        name = _config._backup_config()
+        assert name is not None
+        names.append(name)
+    assert len(set(names)) == 3
+    assert [(_config._BACKUP_DIR / name).read_text() for name in names] == [
+        'value = "first"\n',
+        'value = "second"\n',
+        'value = "third"\n',
+    ]
+
+
+def test_backup_limit_keeps_latest_versions(backup_config: Path) -> None:
+    names: list[str] = []
+    for index in range(_config._MAX_BACKUPS + 2):
+        backup_config.write_text(f"version = {index}\n", encoding="utf-8")
+        name = _config._backup_config()
+        assert name is not None
+        names.append(name)
+        os.utime(_config._BACKUP_DIR / name, ns=(index + 1, index + 1))
+    assert len(list(_config._BACKUP_DIR.glob("config_*.toml"))) == _config._MAX_BACKUPS
+    assert not (_config._BACKUP_DIR / names[0]).exists()
+    assert not (_config._BACKUP_DIR / names[1]).exists()
+    assert (_config._BACKUP_DIR / names[-1]).read_text() == (
+        f"version = {_config._MAX_BACKUPS + 1}\n"
+    )
+
+
+async def test_backup_history_and_restore_accept_legacy_and_unique_names(
+    backup_config: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    backup_config.write_text('value = "original"\n', encoding="utf-8")
+    unique_name = _config._backup_config()
+    assert unique_name is not None
+    unique_path = _config._BACKUP_DIR / unique_name
+    legacy = _config._BACKUP_DIR / "config_20261006_120000.toml"
+    legacy.write_text('value = "legacy"\n', encoding="utf-8")
+    os.utime(legacy, ns=(1, 1))
+    os.utime(unique_path, ns=(2, 2))
+    monkeypatch.setattr(
+        _config, "get_config_manager", lambda: SimpleNamespace(reload=lambda: None)
+    )
+    request = ConfigRequest(body={})
+    response = await _config.config_history_handler(cast(web.Request, request))
+    body: dict[str, Any] = json.loads(cast(web.Response, response).text or "{}")
+    assert [item["name"] for item in body["backups"]] == [unique_name, legacy.name]
+    for name, expected in (
+        (unique_name, 'value = "original"\n'),
+        (legacy.name, 'value = "legacy"\n'),
+    ):
+        backup_config.write_text('value = "current"\n', encoding="utf-8")
+        request = ConfigRequest(body={"name": name})
+        response = await _config.config_restore_handler(cast(web.Request, request))
+        assert response.status == 200
+        assert backup_config.read_text() == expected
+    assert len(list(_config._BACKUP_DIR.glob("config_*.toml"))) == 4
+
+
+def test_failed_backup_removes_partial_file(
+    backup_config: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    backup_config.write_text("version = 1\n", encoding="utf-8")
+
+    def fail_copy(_source: Path, target: Path) -> None:
+        target.write_text("partial", encoding="utf-8")
+        raise OSError("backup write failed")
+
+    monkeypatch.setattr(shutil, "copyfile", fail_copy)
+    with pytest.raises(OSError, match="backup write failed"):
+        _config._backup_config()
+    assert list(_config._BACKUP_DIR.glob("config_*.toml")) == []
+
+
+def test_missing_config_does_not_create_backup(backup_config: Path) -> None:
+    assert _config._backup_config() is None
+    assert not _config._BACKUP_DIR.exists()
diff --git a/tests/test_webui_config_save_behavior.py b/tests/test_webui_config_save_behavior.py
new file mode 100644
index 00000000..464f89ae
--- /dev/null
+++ b/tests/test_webui_config_save_behavior.py
@@ -0,0 +1,61 @@
+"""配置表单通过真实控件保存时的请求顺序和状态回归。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from test_webui_runtime_chat_behavior import run_scenario
+
+
+@pytest.mark.parametrize("outcome", ["success", "network_error", "api_error"])
+def test_auto_save_serializes_and_coalesces_latest_snapshot(outcome: str) -> None:
+    result = run_scenario(f"config_autosave_{outcome}")
+    assert result["beforeOldResponse"]["requestCount"] == 1
+    assert result["maxInFlight"] == 1
+    assert result["afterOldResponse"]["active"] is True
+    assert "obsolete save" not in result["afterOldResponse"]["toasts"]
+    patches: list[dict[str, Any]] = result["patches"]
+    assert [patch["onebot.file_send_mode"] for patch in patches] == [
+        "stream",
+        "local",
+    ]
+    assert result["saved"]["onebot.file_send_mode"] == "local"
+    assert result["final"]["active"] is False
+    assert result["final"]["status"] == "已保存"
+
+
+def test_old_auto_save_cannot_mark_debounced_edit_as_saved() -> None:
+    result = run_scenario("config_autosave_typing")
+    assert result["afterOldResponse"]["requestCount"] == 1
+    assert result["afterOldResponse"]["active"] is True
+    assert "obsolete save" not in result["afterOldResponse"]["toasts"]
+    assert result["saved"]["onebot.file_send_host"] == "updated-host"
+    assert result["maxInFlight"] == 1
+    assert result["final"]["status"] == "已保存"
+
+
+def test_saved_status_timeout_does_not_hide_new_inflight_save() -> None:
+    result = run_scenario("config_autosave_saved_timer")
+    assert result["whilePending"]["requestCount"] == 2
+    assert result["whilePending"]["active"] is True
+    assert result["whilePending"]["opacity"] == "1"
+    assert result["saved"]["onebot.file_send_mode"] == "url"
+    assert result["final"]["status"] == "已保存"
+
+
+@pytest.mark.parametrize("outcome", ["network_error", "api_error"])
+def test_latest_auto_save_failure_remains_visible_and_next_edit_can_retry(
+    outcome: str,
+) -> None:
+    result = run_scenario(f"config_autosave_latest_{outcome}")
+    assert result["afterFailure"]["requestCount"] == 2
+    assert result["afterFailure"]["active"] is False
+    assert "latest save failure" in result["afterFailure"]["toasts"]
+    assert result["afterFailure"]["status"] == (
+        "网络错误" if outcome == "network_error" else "保存失败"
+    )
+    assert result["saved"]["onebot.file_send_mode"] == "url"
+    assert result["final"]["status"] == "已保存"
+    assert result["maxInFlight"] == 1

From 733924a7c4cc1ab8e946a4aebb76a5bcabedbd98 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:44:35 +0800
Subject: [PATCH 058/121] fix(arxiv): scope send deduplication to physical
 delivery routes

---
 docs/configuration.md         |   1 +
 docs/wechat-ilink.md          |   1 +
 src/Undefined/arxiv/sender.py |  19 ++++-
 src/Undefined/utils/sender.py |   5 ++
 tests/test_arxiv_sender.py    | 141 +++++++++++++++++++++++++++++++++-
 5 files changed, 162 insertions(+), 5 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 5e35059d..b9b32355 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1092,6 +1092,7 @@ api_key = "replace-with-your-key"
 - 命中 `arxiv.org/abs/...`、`arxiv.org/pdf/...` 或 `arXiv:<id>` 时直接触发。
 - 裸新式编号仅在消息中同时出现 `arxiv` 关键词时触发，避免误判普通数字串。
 - PDF 下载或上传失败时不会额外发送失败提示，只保留论文信息消息。
+- 同一论文按物理投递地址去重：同一地址的并发请求复用在途发送，发送完成后一小时内跳过重复请求。`qq:<QQ号>`、`wechat:<QQ号>` 和 `group:<群号>` 独立计数；同一逻辑 QQ 在 QQ 和微信请求论文时，两端都能收到。
 - 自动提取仍默认发送论文信息与 PDF；若用户要求分析 arXiv 论文内容，`file_analysis_agent` 会通过 `arxiv_paper(output_mode=uid)` 获取 PDF 附件 UID 后再分析；只需标题、作者、摘要和链接等元信息时可使用 `arxiv_paper(output_mode=info)`。
 
 ---
diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 74cd2938..6f74edc8 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -14,6 +14,7 @@ Undefined 可以通过微信 ClawBot 的 iLink 接口接收和发送微信私聊
 - 微信入站消息带有 `channel="wechat"`、`address="wechat:12345678"` 和“微信私聊”位置。
 - 历史与 QQ 私聊 `12345678` 共用逻辑会话，但每条记录保留 transport 元数据。
 - QQ 与微信的短窗口消息合并桶分开，避免两个物理通道互相抢占回复。
+- arXiv 自动提取的在途合并和一小时去重按物理投递地址隔离；在 QQ 收到论文后，微信仍可独立获取同一篇论文。
 - 用户侧写按 `user:<逻辑QQ号>` 统一排序：QQ 私聊、该用户在群聊中的观察和 iLink 私聊共用同一条侧写更新顺序。事件改写仍可并发；侧写合并按史官入队顺序执行，后一次模型调用读取前一次提交后的完整侧写。不同逻辑用户的侧写可以并发更新。
 
 已入队的史官任务使用入队时保存的逻辑身份；后续改绑不改变旧任务目标。微信帐号别名、微信原生 ID、投递地址和消息合并桶均不作为侧写排序键。`group:<群号>` 与 `user:<QQ号>` 是不同实体，即使数字相同也互不阻塞。
diff --git a/src/Undefined/arxiv/sender.py b/src/Undefined/arxiv/sender.py
index 553c5169..1fd4080f 100644
--- a/src/Undefined/arxiv/sender.py
+++ b/src/Undefined/arxiv/sender.py
@@ -12,6 +12,7 @@
 from Undefined.arxiv.downloader import cleanup_download_path, download_paper_pdf
 from Undefined.arxiv.models import PaperInfo
 from Undefined.arxiv.parser import normalize_arxiv_id
+from Undefined.utils.message_targets import DeliveryAddress
 
 if TYPE_CHECKING:
     from Undefined.utils.sender import MessageSender
@@ -21,7 +22,7 @@
 _INFLIGHT_LOCK = asyncio.Lock()
 _INFLIGHT_SENDS: dict[tuple[str, int, str], asyncio.Future[str]] = {}
 
-# Time-based dedup: maps (target_type, target_id, paper_id) → monotonic timestamp
+# Time-based dedup: maps (delivery_channel, target_id, paper_id) → monotonic timestamp
 _RECENT_SENDS: dict[tuple[str, int, str], float] = {}
 _DEDUP_COOLDOWN_SECONDS: float = 3600.0  # 1 hour
 _RECENT_SENDS_MAX_SIZE: int = 1000
@@ -332,7 +333,17 @@ async def send_arxiv_paper(
     if normalized is None:
         return f"无法解析 arXiv 标识: {paper_id}"
 
-    key = (target_type, int(target_id), normalized)
+    address = DeliveryAddress(
+        "group" if target_type == "group" else "qq", int(target_id)
+    )
+    bound_address = getattr(sender, "delivery_address", None)
+    if (
+        isinstance(bound_address, DeliveryAddress)
+        and bound_address.target_type == target_type
+        and bound_address.target_id == address.target_id
+    ):
+        address = bound_address
+    key = (address.channel, address.target_id, normalized)
     created = False
 
     async with _INFLIGHT_LOCK:
@@ -348,7 +359,7 @@ async def send_arxiv_paper(
             logger.info(
                 "[arXiv] 论文近期已发送，跳过: paper=%s target=%s:%s",
                 normalized,
-                target_type,
+                address.channel,
                 target_id,
             )
             return f"论文 {normalized} 近期已发送过，已跳过"
@@ -364,7 +375,7 @@ async def send_arxiv_paper(
         logger.info(
             "[arXiv] 复用在途发送任务: paper=%s target=%s:%s",
             normalized,
-            target_type,
+            address.channel,
             target_id,
         )
         return await asyncio.shield(future)
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index 2e1feb8c..f6a08a8c 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -1770,6 +1770,11 @@ def __init__(self, sender: MessageSender, address: DeliveryAddress) -> None:
         self._sender = sender
         self._address = address
 
+    @property
+    def delivery_address(self) -> DeliveryAddress:
+        """当前私聊的物理投递地址；其他目标仍按原发送器路由。"""
+        return self._address
+
     def __getattr__(self, name: str) -> Any:
         return getattr(self._sender, name)
 
diff --git a/tests/test_arxiv_sender.py b/tests/test_arxiv_sender.py
index 8934d072..a3a5d090 100644
--- a/tests/test_arxiv_sender.py
+++ b/tests/test_arxiv_sender.py
@@ -3,7 +3,7 @@
 import asyncio
 from pathlib import Path
 from types import SimpleNamespace
-from typing import Any
+from typing import Any, cast
 from unittest.mock import AsyncMock
 
 import pytest
@@ -12,6 +12,9 @@
 from Undefined.arxiv.models import PaperInfo
 from Undefined.arxiv.sender import send_arxiv_paper
 import Undefined.arxiv.sender as arxiv_sender
+from Undefined.handlers.auto_extract import AutoExtractMixin
+from Undefined.utils.message_targets import DeliveryAddress
+from Undefined.utils.sender import AddressBoundSender, MessageSender
 
 
 @pytest.fixture(autouse=True)
@@ -43,6 +46,142 @@ def _sender() -> Any:
     )
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("overlap", [False, True])
+@pytest.mark.parametrize("first_channel", ["qq", "wechat"])
+async def test_auto_extract_deduplicates_per_physical_delivery_address(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    overlap: bool,
+    first_channel: str,
+) -> None:
+    started = {"qq": asyncio.Event(), "wechat": asyncio.Event()}
+    release = asyncio.Event()
+    if not overlap:
+        release.set()
+
+    async def qq_send(
+        _user_id: int, _message: list[dict[str, Any]], **_: Any
+    ) -> dict[str, Any]:
+        started["qq"].set()
+        await release.wait()
+        return {"data": {"message_id": 11}}
+
+    async def wechat_send(*_: Any, **__: Any) -> str:
+        started["wechat"].set()
+        await release.wait()
+        return "wechat-11"
+
+    onebot: Any = SimpleNamespace(send_private_message=AsyncMock(side_effect=qq_send))
+    weixin = SimpleNamespace(send_text=AsyncMock(side_effect=wechat_send))
+    history: Any = SimpleNamespace(add_private_message=AsyncMock())
+    config: Any = SimpleNamespace(
+        is_private_allowed=lambda _: True,
+        arxiv_auto_extract_max_items=1,
+        arxiv_max_file_size=100,
+        arxiv_author_preview_limit=20,
+        arxiv_summary_preview_chars=1000,
+    )
+    sender = MessageSender(onebot, history, bot_qq=999, config=config)
+    sender.set_weixin_service(weixin)
+    senders: dict[str, Any] = {
+        "qq": sender,
+        "wechat": AddressBoundSender(sender, DeliveryAddress("wechat", 12345678)),
+    }
+    handler = AutoExtractMixin.__new__(AutoExtractMixin)
+    handler.config = config
+    handler.sender = sender
+    monkeypatch.setattr(
+        arxiv_sender, "get_paper_info", AsyncMock(return_value=_paper_info())
+    )
+    monkeypatch.setattr(
+        arxiv_sender,
+        "download_paper_pdf",
+        AsyncMock(return_value=(PaperDownloadResult(None, None, "failed"), tmp_path)),
+    )
+    monkeypatch.setattr(arxiv_sender, "cleanup_download_path", AsyncMock())
+
+    async def extract(channel: str) -> None:
+        await handler._handle_arxiv_extract(
+            12345678, ["2501.01234"], "private", senders[channel]
+        )
+
+    second_channel = "wechat" if first_channel == "qq" else "qq"
+    tasks: list[asyncio.Task[None]] = []
+    try:
+        tasks.append(asyncio.create_task(extract(first_channel)))
+        await asyncio.wait_for(started[first_channel].wait(), timeout=1)
+        if not overlap:
+            await tasks[0]
+        tasks.append(asyncio.create_task(extract(second_channel)))
+        await asyncio.wait_for(started[second_channel].wait(), timeout=1)
+        if overlap:
+            # 两端各有自己的在途发送，同路由的追随者仍应复用。
+            tasks.extend(asyncio.create_task(extract(channel)) for channel in senders)
+            await asyncio.sleep(0)
+            assert all(not task.done() for task in tasks)
+    finally:
+        release.set()
+        await asyncio.gather(*tasks)
+
+    await extract("qq")
+    await extract("wechat")
+    assert onebot.send_private_message.await_count == 1
+    assert weixin.send_text.await_count == 1
+    assert history.add_private_message.await_count == 2
+    assert set(arxiv_sender._RECENT_SENDS) == {
+        ("qq", 12345678, "2501.01234"),
+        ("wechat", 12345678, "2501.01234"),
+    }
+    assert not arxiv_sender._INFLIGHT_SENDS
+
+
+@pytest.mark.asyncio
+async def test_bound_sender_other_target_keeps_qq_deduplication(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    onebot: Any = SimpleNamespace(
+        send_private_message=AsyncMock(return_value={"data": {"message_id": 11}})
+    )
+    history: Any = SimpleNamespace(add_private_message=AsyncMock())
+    config: Any = SimpleNamespace(is_private_allowed=lambda _: True)
+    sender = MessageSender(
+        onebot,
+        history,
+        bot_qq=999,
+        config=config,
+    )
+    weixin = SimpleNamespace(send_text=AsyncMock())
+    sender.set_weixin_service(weixin)
+    bound_sender = AddressBoundSender(sender, DeliveryAddress("wechat", 12345678))
+    monkeypatch.setattr(
+        arxiv_sender, "get_paper_info", AsyncMock(return_value=_paper_info())
+    )
+    monkeypatch.setattr(
+        arxiv_sender,
+        "download_paper_pdf",
+        AsyncMock(
+            return_value=(PaperDownloadResult(None, None, "failed"), Path("unused"))
+        ),
+    )
+    monkeypatch.setattr(arxiv_sender, "cleanup_download_path", AsyncMock())
+    options: dict[str, Any] = {
+        "paper_id": "2501.01234",
+        "target_type": "private",
+        "target_id": 87654321,
+        "max_file_size": 100,
+        "author_preview_limit": 20,
+        "summary_preview_chars": 1000,
+    }
+    await send_arxiv_paper(sender=cast(Any, bound_sender), **options)
+    result = await send_arxiv_paper(sender=sender, **options)
+
+    assert "近期已发送过" in result
+    onebot.send_private_message.assert_awaited_once()
+    weixin.send_text.assert_not_awaited()
+    assert set(arxiv_sender._RECENT_SENDS) == {("qq", 87654321, "2501.01234")}
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize("cancel_owner", [True, False])
 async def test_inflight_send_cancellation_settles_waiters(

From 9f7631608ee2ff99ef44317edca535e38cac85f9 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:46:49 +0800
Subject: [PATCH 059/121] fix(attachments): preserve CQ parameter values on
 delivery

---
 docs/configuration.md                 |   2 +
 src/Undefined/attachments/render.py   |   2 +-
 src/Undefined/utils/common.py         |  14 ++-
 tests/test_attachment_cq_roundtrip.py | 137 ++++++++++++++++++++++++++
 tests/test_utils_common.py            |  32 ++++++
 5 files changed, 185 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_attachment_cq_roundtrip.py

diff --git a/docs/configuration.md b/docs/configuration.md
index b9b32355..48d076cd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -705,6 +705,8 @@ document_instruction = "passage: "
 
 外部接收的远程图片或文件默认会先下载到附件缓存再生成 UID，避免后续 URL 失效；大文件超过阈值时，UID 仍会生成，但绑定的是 URL 引用而不是缓存文件，AI 可在上下文中看到原始 `source_ref`。如果本地缓存因总容量或时间清理被删除，但记录仍保留 URL，后续需要文件内容时会优先按 URL 回源下载。
 
+仅保留 URL 引用的远程图片按登记的原始 URL 发送，查询参数中的逗号、方括号和 `&` 不会被截断。内部 CQ 参数会转义，并在转换为 OneBot 消息段时仅解码一次；URL 中原本的 `&#44;`、`&amp;` 等字面实体保持原样。这不改变远程下载上限或目标校验策略。
+
 远程附件下载默认只允许公网 HTTP(S) 目标，拒绝 URL 内的凭据、回环、私网、链路本地、组播等非公网目标。域名的全部解析结果都必须符合策略；实际请求固定到已校验的 IP，并保留原始 Host、TLS SNI 和证书校验，避免校验后再次解析造成 DNS 重绑定绕过。每次重定向和后续回源都重新校验目标；DNS、连接、跳转与下载共用 120 秒总时限，最多跟随 20 次跳转。策略拒绝或网络错误不会降级登记成新的 URL 引用。
 
 需要从 NapCat 等内网媒体服务下载时，只将确认可信的精确 origin 加入 `remote_download_allow_private_origins`；该配置允许从对应服务的任意路径下载，不会放行其他端口、协议或跳转目标。修改配置只影响后续下载，不删除现有缓存。仅登记 URL 引用时不会发起 DNS 或 HTTP 请求；真正回源时仍须通过当时的目标策略。`use_proxy` 保持生效，代理会收到已校验的目标 IP，代理地址本身由部署者信任；代理模式也需要 Bot 本机能够解析目标域名。
diff --git a/src/Undefined/attachments/render.py b/src/Undefined/attachments/render.py
index 102f7809..0ec83919 100644
--- a/src/Undefined/attachments/render.py
+++ b/src/Undefined/attachments/render.py
@@ -159,7 +159,7 @@ def _render_image_tag(
         history_parts.append(replacement)
         return False
 
-    cq_args = [f"file={image_source}"]
+    cq_args = [f"file={_escape_cq_component(image_source)}"]
     for key, value in dict(getattr(record, "segment_data", {}) or {}).items():
         cleaned_key = str(key or "").strip()
         cleaned_value = str(value or "").strip()
diff --git a/src/Undefined/utils/common.py b/src/Undefined/utils/common.py
index 0d8900e6..ca1991be 100644
--- a/src/Undefined/utils/common.py
+++ b/src/Undefined/utils/common.py
@@ -419,6 +419,16 @@ def process_at_mentions(message: str) -> str:
     return message
 
 
+def _unescape_cq_parameter(value: str) -> str:
+    """仅解码 CQ 参数实体一次；最后还原 &，避免再次解码字面实体。"""
+    return (
+        value.replace("&#91;", "[")
+        .replace("&#93;", "]")
+        .replace("&#44;", ",")
+        .replace("&amp;", "&")
+    )
+
+
 def message_to_segments(message: str) -> List[Dict[str, Any]]:
     """将包含 CQ 码的字符串转换为 OneBot 消息段数组
 
@@ -446,7 +456,9 @@ def message_to_segments(message: str) -> List[Dict[str, Any]]:
             for arg_pair in cq_args_str.split(","):
                 if "=" in arg_pair:
                     k, v = arg_pair.split("=", 1)
-                    data[k.strip()] = v.strip()
+                    data[_unescape_cq_parameter(k.strip())] = _unescape_cq_parameter(
+                        v.strip()
+                    )
 
         segments.append({"type": cq_type, "data": data})
         last_pos = match.end()
diff --git a/tests/test_attachment_cq_roundtrip.py b/tests/test_attachment_cq_roundtrip.py
new file mode 100644
index 00000000..0ac6dcfa
--- /dev/null
+++ b/tests/test_attachment_cq_roundtrip.py
@@ -0,0 +1,137 @@
+"""CQ 参数从附件登记到最终 OneBot JSON 请求的无损往返。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, cast
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from Undefined.attachments import AttachmentRegistry, render_message_with_attachments
+from Undefined.attachments import remote as attachment_remote
+from Undefined.config import Config
+from Undefined.onebot.client import OneBotClient
+from Undefined.utils.history import MessageHistoryManager
+from Undefined.utils.sender import MessageSender
+
+
+class _RecordingWebSocket:
+    close_code: int | None = None
+
+    def __init__(self, client: OneBotClient) -> None:
+        self.client = client
+        self.requests: list[dict[str, Any]] = []
+
+    async def send(self, payload: str) -> None:
+        request = cast(dict[str, Any], json.loads(payload))
+        self.requests.append(request)
+        echo = str(request["echo"])
+        self.client._pending_responses[echo].set_result(
+            {"status": "ok", "retcode": 0, "data": {"message_id": 42}, "echo": echo}
+        )
+
+
+@pytest.mark.parametrize("target_type", ["group", "private"])
+@pytest.mark.parametrize("mode", ["local", "url", "stream"])
+@pytest.mark.parametrize(
+    "source_url",
+    [
+        "https://8.8.8.8/image.png?crop=1,2",
+        "https://8.8.8.8/image.png?list=[one,two]",
+        "https://8.8.8.8/image.png?x=1&y=2",
+        "https://8.8.8.8/image.png?literal=&#44;&#91;&#93;&amp;",
+        "https://8.8.8.8/image.png?literal=[CQ:at,qq=12345]",
+        "https://8.8.8.8/image.png?x=%2C%5B%5D%26&literal=&amp;#91;",
+    ],
+)
+async def test_url_only_image_cq_preserves_source_and_metadata_on_wire(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    source_url: str,
+    target_type: str,
+    mode: str,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    async def unexpected_dns(host: str, port: int) -> tuple[str, ...]:
+        raise AssertionError(f"URL-only 登记不得触发 DNS: {host}:{port}")
+
+    monkeypatch.setattr(attachment_remote, "resolve_host_addresses", unexpected_dns)
+    registry_path = tmp_path / "registry.json"
+    cache_dir = tmp_path / "attachments"
+    registry = AttachmentRegistry(
+        registry_path=registry_path,
+        cache_dir=cache_dir,
+        remote_download_max_bytes=0,
+    )
+    assert registry_path.is_relative_to(tmp_path)
+    assert cache_dir.is_relative_to(tmp_path)
+    scope = f"{target_type}:10001"
+    summary = "a,b]&[&#44;&#91;&#93;&amp;"
+    record = await registry.register_remote_url(
+        scope,
+        source_url,
+        kind="image",
+        display_name="remote.png",
+        segment_data={"summary": summary, "subType": "1"},
+    )
+    assert record.local_path is None
+    rendered = await render_message_with_attachments(
+        f'前文 <attachment uid="{record.uid}"/> 后文',
+        registry=registry,
+        scope_key=scope,
+        strict=True,
+    )
+
+    config = Config.from_mapping({"onebot": {"file_send_mode": mode}}, strict=False)
+    onebot = OneBotClient("ws://unused.invalid", config_getter=lambda: config)
+    onebot.file_transport.store.cache_dir = tmp_path / "onebot-files"
+    assert onebot.file_transport.store.cache_dir.is_relative_to(tmp_path)
+    websocket = _RecordingWebSocket(onebot)
+    onebot.ws = cast(Any, websocket)
+    history = MagicMock(spec=MessageHistoryManager)
+    history.add_group_message = AsyncMock()
+    history.add_private_message = AsyncMock()
+    sender = MessageSender(
+        onebot,
+        history,
+        bot_qq=20002,
+        config=config,
+        attachment_registry=registry,
+    )
+    if target_type == "group":
+        result = await sender.send_group_message(
+            10001,
+            rendered.delivery_text,
+            history_message=rendered.history_text,
+            attachments=rendered.attachments,
+        )
+        history_call = history.add_group_message.await_args
+    else:
+        result = await sender.send_private_message(
+            10001,
+            rendered.delivery_text,
+            history_message=rendered.history_text,
+            attachments=rendered.attachments,
+        )
+        history_call = history.add_private_message.await_args
+
+    assert result == 42
+    assert len(websocket.requests) == 1
+    request = websocket.requests[0]
+    assert request["action"] == f"send_{target_type}_msg"
+    assert request["params"]["message"] == [
+        {"type": "text", "data": {"text": "前文 "}},
+        {
+            "type": "image",
+            "data": {"file": source_url, "summary": summary, "subType": "1"},
+        },
+        {"type": "text", "data": {"text": " 后文"}},
+    ]
+    assert history_call is not None
+    assert history_call.kwargs["attachments"] == rendered.attachments
+    assert (await registry.resolve_async(record.uid, scope)) == record
+    assert not onebot._pending_responses
+    assert not onebot.file_transport.store.cache_dir.exists()
diff --git a/tests/test_utils_common.py b/tests/test_utils_common.py
index c1075b45..3cad42b6 100644
--- a/tests/test_utils_common.py
+++ b/tests/test_utils_common.py
@@ -165,6 +165,38 @@ def test_cq_without_args(self) -> None:
         segs = message_to_segments("[CQ:face]")
         assert segs == [{"type": "face", "data": {}}]
 
+    def test_cq_parameters_decode_after_splitting(self) -> None:
+        segs = message_to_segments(
+            "before [CQ:image,file=https://example.com/image.png?crop=1&#44;2"
+            "&amp;list=&#91;one&#44;two&#93;,summary=x&#44;y&#93;&amp;&#91;] after"
+        )
+        assert segs == [
+            {"type": "text", "data": {"text": "before "}},
+            {
+                "type": "image",
+                "data": {
+                    "file": "https://example.com/image.png?crop=1,2&list=[one,two]",
+                    "summary": "x,y]&[",
+                },
+            },
+            {"type": "text", "data": {"text": " after"}},
+        ]
+
+    def test_cq_parameters_decode_literal_entities_only_once(self) -> None:
+        segs = message_to_segments(
+            "[CQ:share,title=&amp;#44;&amp;#91;&amp;#93;&amp;amp;&lt;&quot;]"
+        )
+        assert segs == [
+            {
+                "type": "share",
+                "data": {"title": "&#44;&#91;&#93;&amp;&lt;&quot;"},
+            }
+        ]
+
+    def test_plain_text_entities_are_not_decoded_as_cq_parameters(self) -> None:
+        text = "正文 &amp; &#44; &#91;CQ:at,qq=123&#93;"
+        assert message_to_segments(text) == [{"type": "text", "data": {"text": text}}]
+
 
 # ---------------------------------------------------------------------------
 # matches_xinliweiyuan

From aaa71e7a02b6962ccc6755c43158f3153868467f Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:48:54 +0800
Subject: [PATCH 060/121] fix(api): normalize memory time filters to comparable
 instants

---
 docs/openapi.md                  |   2 +
 src/Undefined/api/_helpers.py    |   7 +-
 tests/test_runtime_api_memory.py | 123 +++++++++++++++++++++++++++++++
 3 files changed, 129 insertions(+), 3 deletions(-)

diff --git a/docs/openapi.md b/docs/openapi.md
index 51e68c5a..04d6a313 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -197,6 +197,8 @@ HEAD /api/v1/onebot/files/{file_id}?token=...
 
 说明：仅提供查看/查询，不提供写入接口，不改变现有记忆存储格式。
 
+时间筛选接受带 `Z`、明确 UTC 偏移或无时区的 ISO 时间。无时区查询与旧记录中的无时区 `created_at` 均按 Bot 所在系统的本地时区解释（采用该日期的时区偏移），转换到 UTC 后比较；带偏移的时间按其实际时刻比较。上下界均包含在结果中；开始晚于结束时自动交换上下界。无效查询时间返回 `400`，无法解析创建时间的记录在启用时间筛选时跳过。响应中的 `created_at` 保留原始存储字符串。
+
 ### 表情包库
 
 - `GET /api/v1/memes`
diff --git a/src/Undefined/api/_helpers.py b/src/Undefined/api/_helpers.py
index e65b37f2..7f0f96fb 100644
--- a/src/Undefined/api/_helpers.py
+++ b/src/Undefined/api/_helpers.py
@@ -8,7 +8,7 @@
 import logging
 from contextlib import suppress
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Awaitable, Callable
 from urllib.parse import urlsplit
 
@@ -191,6 +191,7 @@ def _optional_query_param(request: web.Request, key: str) -> str | None:
 
 
 def _parse_query_time(value: str | None) -> datetime | None:
+    """统一为 UTC；旧记录及无时区查询沿用系统本地时间含义。"""
     text = str(value or "").strip()
     if not text:
         return None
@@ -198,8 +199,8 @@ def _parse_query_time(value: str | None) -> datetime | None:
     if "T" in text:
         candidates.append(text.replace("T", " "))
     for candidate in candidates:
-        with suppress(ValueError):
-            return datetime.fromisoformat(candidate)
+        with suppress(ValueError, OverflowError, OSError):
+            return datetime.fromisoformat(candidate).astimezone(timezone.utc)
     return None
 
 
diff --git a/tests/test_runtime_api_memory.py b/tests/test_runtime_api_memory.py
index 465ea320..30632ec7 100644
--- a/tests/test_runtime_api_memory.py
+++ b/tests/test_runtime_api_memory.py
@@ -1,14 +1,19 @@
 from __future__ import annotations
 
 import json
+from datetime import datetime, timezone
+import os
+import time
 from types import SimpleNamespace
 from typing import Any, cast
 
 import pytest
 from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
 
 from Undefined.api import RuntimeAPIContext, RuntimeAPIServer
 from Undefined.memory import Memory
+from Undefined.api.routes.memory import memory_list_handler
 
 
 class _DummyMemoryStorage:
@@ -34,6 +39,124 @@ async def delete(self, _uuid: str) -> bool:
         raise AssertionError("memory query endpoint should be read-only")
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("query_kind", "expected"),
+    [
+        ("naive", ["m1"]),
+        ("z", ["m1"]),
+        ("offset", ["m1"]),
+        ("mixed", ["m1"]),
+        ("reversed_mixed", ["m1", "m2"]),
+        ("from", ["m2"]),
+        ("to", ["m1"]),
+    ],
+)
+async def test_memory_http_filters_compare_instants_and_include_boundaries(
+    query_kind: str, expected: list[str]
+) -> None:
+    storage = _DummyMemoryStorage()
+    first_local = datetime.fromisoformat(storage._items[0].created_at)
+    second_local = datetime.fromisoformat(storage._items[1].created_at)
+    first_utc = first_local.astimezone(timezone.utc)
+    second_utc = second_local.astimezone(timezone.utc)
+    first_z = first_utc.isoformat().replace("+00:00", "Z")
+    second_z = second_utc.isoformat().replace("+00:00", "Z")
+    first_offset = first_local.astimezone().isoformat()
+    queries = {
+        "naive": {
+            "time_from": first_local.isoformat(),
+            "time_to": first_local.isoformat(),
+        },
+        "z": {"time_from": first_z, "time_to": first_z},
+        "offset": {"time_from": first_offset, "time_to": first_offset},
+        "mixed": {"time_from": first_z, "time_to": first_local.isoformat()},
+        "reversed_mixed": {"time_from": second_local.isoformat(), "time_to": first_z},
+        "from": {"time_from": second_z},
+        "to": {"time_to": first_z},
+    }
+    # 混合新旧存储格式，输出仍保留原始时间字符串。
+    storage._items.extend(
+        [
+            Memory(uuid="old", fact="旧记录", created_at="2020-01-01T00:00:00Z"),
+            Memory(uuid="invalid", fact="无效时间", created_at="invalid"),
+        ]
+    )
+    context: Any = SimpleNamespace(ai=SimpleNamespace(memory_storage=storage))
+
+    async def handle(request: web.Request) -> web.Response:
+        return await memory_list_handler(context, request)
+
+    app = web.Application()
+    app.router.add_get("/api/v1/memory", handle)
+    async with TestClient(TestServer(app)) as client:
+        response = await client.get("/api/v1/memory", params=queries[query_kind])
+        assert response.status == 200
+        body = await response.json()
+    if query_kind == "to":
+        expected = ["old", *expected]
+    assert [item["uuid"] for item in body["items"]] == expected
+    assert all(
+        item["created_at"] in {row.created_at for row in storage._items}
+        for item in body["items"]
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("field", ["time_from", "time_to"])
+@pytest.mark.parametrize(
+    "value", ["invalid", "2026-02-30T00:00:00", "2026-01-01T00:00:00+25:00"]
+)
+async def test_memory_invalid_time_filter_returns_400(field: str, value: str) -> None:
+    context: Any = SimpleNamespace(
+        ai=SimpleNamespace(memory_storage=_DummyMemoryStorage())
+    )
+    request = cast(web.Request, SimpleNamespace(query={field: value}))
+    response = await memory_list_handler(context, request)
+    assert response.status == 400
+    assert json.loads(response.text or "{}") == {
+        "error": f"{field} must be ISO datetime"
+    }
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(not hasattr(time, "tzset"), reason="需要 POSIX 时区切换 API")
+@pytest.mark.parametrize("system_zone", ["UTC", "Asia/Shanghai", "America/New_York"])
+@pytest.mark.parametrize("local_time", ["2026-02-25T10:00:00", "2026-07-25T10:00:00"])
+async def test_memory_naive_time_uses_system_zone_at_record_date(
+    monkeypatch: pytest.MonkeyPatch, system_zone: str, local_time: str
+) -> None:
+    from zoneinfo import ZoneInfo
+
+    utc_time = (
+        datetime.fromisoformat(local_time)
+        .replace(tzinfo=ZoneInfo(system_zone))
+        .astimezone(timezone.utc)
+    )
+    storage = _DummyMemoryStorage()
+    storage._items = [Memory(uuid="m1", fact="当地时间", created_at=local_time)]
+    context: Any = SimpleNamespace(ai=SimpleNamespace(memory_storage=storage))
+    request = cast(
+        web.Request,
+        SimpleNamespace(
+            query={"time_from": utc_time.isoformat(), "time_to": utc_time.isoformat()}
+        ),
+    )
+    previous_zone = os.environ.get("TZ")
+    try:
+        monkeypatch.setenv("TZ", system_zone)
+        time.tzset()
+        response = await memory_list_handler(context, request)
+        assert response.status == 200
+        assert json.loads(response.text or "{}")["total"] == 1
+    finally:
+        if previous_zone is None:
+            monkeypatch.delenv("TZ", raising=False)
+        else:
+            monkeypatch.setenv("TZ", previous_zone)
+        time.tzset()
+
+
 @pytest.mark.asyncio
 async def test_runtime_memory_endpoint_read_only_and_searchable() -> None:
     context = RuntimeAPIContext(

From 7e7f27f21fe5070dbeed5475d4a13e95cd5d0977 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:50:20 +0800
Subject: [PATCH 061/121] fix(webui): preserve workflow edits across stale
 responses

---
 docs/webui-guide.md                        |   1 +
 src/Undefined/webui/static/js/schedules.js |  74 +++++++--
 tests/frontend/runtime_chat_harness.js     | 180 +++++++++++++++++++++
 tests/test_webui_schedules_behavior.py     |  76 +++++++++
 4 files changed, 319 insertions(+), 12 deletions(-)
 create mode 100644 tests/test_webui_schedules_behavior.py

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index f33aa3cd..ebc14b06 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -130,6 +130,7 @@ AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：
 - **全屏画布**：左侧节点盘，中间点选出点再点目标连线，右侧结构化检查器。空白 LLM 的工具 / 工具集 / Agent 用搜索点选。工具参数值按 JSON 编辑并保留数字、布尔值、数组、对象与字符串类型。工具与 LLM 节点可勾选「存储为变量」并填写名称，下游用 `{{名称}}` 引用输出。三种 LLM 节点还可配置变量提取（名称 + 说明），运行时注入 `extract_<名称>` 工具。分支带 case 锚点；检查器修改 case 的 ID / 文本时会保留高级 JSON 中的 mentions、text_match、sender_ids 与 clock 条件。循环以分组框表示；JSON 仅作为高级排障。
 - **Start 检查器**：场景多选（群 / QQ 私聊 / 微信）、群号与 QQ、@ 条款、剩余文本、`pass_text`、clock / 星期、冷却与时间类字段。新建默认关闭「拦截主 AI」和「自动发送终值」；关闭拦截时工作流后台执行，主 AI 立刻继续。
 - **深链接**：`/?tab=schedules&task=<id>` 直接打开一条自动化。
+- **编辑与保存**：保存期间可以继续编辑或切换任务。回包只更新发起保存的编辑器；后续修改保留为待保存草稿，编辑器显示“草稿”，不会被旧快照覆盖或跳回列表。只有当前修订保存成功后才显示“自动化已保存”。新稿首次保存后会接收服务端分配的任务 ID，后续保存更新该任务。迟到的验证结果也不会替换当前任务或当前修订的校验提示。
 
 WebUI 会先验证登录态，再通过后端代理访问 Runtime API 的 `/api/v1/automations`。浏览器前端不会直接读取或暴露 `[api].auth_key`。
 
diff --git a/src/Undefined/webui/static/js/schedules.js b/src/Undefined/webui/static/js/schedules.js
index 896a1daa..f12ece64 100644
--- a/src/Undefined/webui/static/js/schedules.js
+++ b/src/Undefined/webui/static/js/schedules.js
@@ -21,6 +21,8 @@
         canvas: null,
         inspector: null,
         savedSnapshot: "",
+        editorGeneration: 0,
+        editorRevision: 0,
         issues: [],
         page: "list",
         editorInView: false,
@@ -124,6 +126,15 @@
         return window.confirm(t("schedules.confirm_leave"));
     }
 
+    function isCurrentEditor(generation, revision) {
+        return (
+            scheduleState.editing &&
+            scheduleState.editorGeneration === generation &&
+            (revision === undefined ||
+                scheduleState.editorRevision === revision)
+        );
+    }
+
     function paletteGroups() {
         const meta = scheduleState.catalog.node_type_meta || [];
         const byId = {};
@@ -352,7 +363,16 @@
     function ensureGraph(task) {
         if (!scheduleState.graph) {
             scheduleState.graph = G.createGraph(task);
+            let previousSnapshot = snapshotOf(scheduleState.graph.payload());
             scheduleState.graph.subscribe(() => {
+                const snapshot = snapshotOf(scheduleState.graph.payload());
+                if (snapshot !== previousSnapshot) {
+                    previousSnapshot = snapshot;
+                    scheduleState.editorRevision += 1;
+                    if (scheduleState.editing) {
+                        setEditorStatus(t("schedules.draft"));
+                    }
+                }
                 if (scheduleState.editing) syncEditorChrome();
             });
             scheduleState.canvas = window.WorkflowCanvas.createCanvas(
@@ -430,7 +450,9 @@
                     !scheduleState.editing || !scheduleState.draftNew;
                 return;
             }
-            node.disabled = !scheduleState.editing;
+            node.disabled =
+                !scheduleState.editing ||
+                (id === "btnWfSave" && scheduleState.busy);
         });
         const del = get("btnWfDelete");
         if (del) {
@@ -448,6 +470,7 @@
 
     function openDraft(task) {
         if (!confirmLeave()) return;
+        scheduleState.editorGeneration += 1;
         scheduleState.draftNew = true;
         scheduleState.selectedId = "";
         scheduleState.issues = [];
@@ -480,6 +503,7 @@
         );
         if (!task) return;
         if (!confirmLeave()) return;
+        scheduleState.editorGeneration += 1;
         scheduleState.draftNew = false;
         scheduleState.selectedId = taskId;
         scheduleState.issues = [];
@@ -499,6 +523,7 @@
 
     function closeEditor() {
         if (!confirmLeave()) return;
+        scheduleState.editorGeneration += 1;
         setEditing(false);
         scheduleState.dirty = false;
         writeTaskQuery("");
@@ -516,6 +541,8 @@
 
     async function validateDraft() {
         if (!scheduleState.graph) return;
+        const generation = scheduleState.editorGeneration;
+        const revision = scheduleState.editorRevision;
         try {
             const response = await api("/api/runtime/automations/validate", {
                 method: "POST",
@@ -523,11 +550,13 @@
                 body: JSON.stringify(scheduleState.graph.payload()),
             });
             const body = await parseJsonSafe(response);
+            if (!isCurrentEditor(generation, revision)) return;
             scheduleState.issues = Array.isArray(body?.issues)
                 ? body.issues
                 : [];
             syncEditorChrome();
         } catch (_error) {
+            if (!isCurrentEditor(generation, revision)) return;
             scheduleState.issues = [];
         }
     }
@@ -592,6 +621,8 @@
 
     async function save() {
         if (!scheduleState.graph || scheduleState.busy) return;
+        const generation = scheduleState.editorGeneration;
+        const revision = scheduleState.editorRevision;
         try {
             const payload = scheduleState.graph.payload();
             const taskId = scheduleState.draftNew
@@ -611,23 +642,38 @@
             );
             const body = await parseJsonSafe(response);
             if (!response.ok) throw new Error(requestError(response, body));
-            setEditorStatus(t("schedules.saved"), "success");
             showToast(t("schedules.saved"), "success");
-            scheduleState.draftNew = false;
-            scheduleState.selectedId = body.task?.task_id || taskId;
-            if (body.task) {
-                ensureGraph(body.task);
+            const unchanged = isCurrentEditor(generation, revision);
+            let savedRevision = null;
+            if (isCurrentEditor(generation)) {
+                scheduleState.draftNew = false;
+                scheduleState.selectedId = body.task?.task_id || taskId;
+                if (unchanged && body.task) ensureGraph(body.task);
                 scheduleState.savedSnapshot = snapshotOf(
-                    scheduleState.graph.payload(),
+                    unchanged
+                        ? scheduleState.graph.payload()
+                        : G.createGraph(body.task || payload).payload(),
+                );
+                syncEditorChrome();
+                writeTaskQuery(scheduleState.selectedId);
+                setEditorStatus(
+                    t(unchanged ? "schedules.saved" : "schedules.draft"),
+                    unchanged ? "success" : "",
                 );
+                savedRevision = scheduleState.editorRevision;
             }
-            scheduleState.dirty = false;
-            writeTaskQuery(scheduleState.selectedId);
             await refresh({ force: true, skipOpenFromQuery: true });
-            window.requestAnimationFrame(() =>
-                window.requestAnimationFrame(() => showSchedulePage("list")),
-            );
+            if (unchanged && savedRevision !== null) {
+                window.requestAnimationFrame(() =>
+                    window.requestAnimationFrame(() => {
+                        if (isCurrentEditor(generation, savedRevision)) {
+                            showSchedulePage("list");
+                        }
+                    }),
+                );
+            }
         } catch (error) {
+            if (!isCurrentEditor(generation)) return;
             setEditorStatus(
                 `${t("schedules.save_failed")}: ${error.message || error}`,
                 "error",
@@ -752,6 +798,10 @@
     }
 
     function bindEvents() {
+        get("scheduleEditorView")?.addEventListener("input", () => {
+            scheduleState.editorRevision += 1;
+            if (scheduleState.editing) setEditorStatus(t("schedules.draft"));
+        });
         get("btnSchedulesRefresh")?.addEventListener("click", refresh);
         get("btnSchedulesNew")?.addEventListener("click", showPresetDialog);
         get("btnPresetClose")?.addEventListener("click", hidePresetDialog);
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index e85bf0e8..ca9eed91 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3392,6 +3392,184 @@ for (const outcome of ["success", "network_error", "api_error", "typing", "saved
     SCENARIOS[`config_autosave_${outcome}`] = (env) => configAutoSave(env, outcome);
 }
 
+function workflowEditorFixture(env) {
+    const { window, response } = env;
+    const tasks = ["A", "B"].map((id) => ({
+        task_id: id, task_name: `${id}-original`, enabled: true,
+        nodes: [{ id: "start", type: "start", kind: "message", channels: ["group"] }],
+        edges: [], ui: { positions: {}, zoom: 1, pan: { x: 40, y: 40 } },
+    }));
+    const pendingSaves = [];
+    const validations = [];
+    let deferredValidation = null;
+    let deferredList = null;
+    let deferNextList = false;
+    let deferNextValidation = false;
+    let currentIssues = [];
+    const pages = [];
+    window.document.getElementById("scheduleListView").getBoundingClientRect = () => ({ top: 0 });
+    window.document.getElementById("scheduleEditorView").getBoundingClientRect = () => ({ top: 1000 });
+    const scroller = window.document.getElementById("schedulePages");
+    scroller.getBoundingClientRect = () => ({ top: 0 });
+    scroller.scrollTo = ({ top }) => pages.push(top === 1000 ? "editor" : "list");
+    window.fetch = (url, options = {}) => {
+        const endpoint = String(url);
+        const method = options.method || "GET";
+        if (endpoint.endsWith("/automations/catalog")) {
+            return Promise.resolve(response(200, { node_type_meta: [], presets: [] }));
+        }
+        if (endpoint.endsWith("/automations/validate")) {
+            validations.push(JSON.parse(options.body));
+            if (deferNextValidation) {
+                deferNextValidation = false;
+                return new Promise((resolve, reject) => { deferredValidation = { resolve, reject }; });
+            }
+            return Promise.resolve(response(200, { issues: currentIssues }));
+        }
+        if (["POST", "PATCH"].includes(method)) {
+            return new Promise((resolve, reject) => {
+                pendingSaves.push({ url: endpoint, method, payload: JSON.parse(options.body), resolve, reject });
+            });
+        }
+        if (endpoint.endsWith("/automations")) {
+            if (deferNextList) {
+                deferNextList = false;
+                return new Promise((resolve) => { deferredList = resolve; });
+            }
+            return Promise.resolve(response(200, { items: tasks }));
+        }
+        throw new Error(`unexpected workflow request: ${method} ${endpoint}`);
+    };
+    window.confirm = () => true;
+    window.SchedulesController.init();
+    const input = window.document.getElementById("wfTaskName");
+    return {
+        pendingSaves, validations, pages, input,
+        open(id) { window.document.querySelector(`[data-task-id="${id}"]`).click(); },
+        edit(value, commit = true) {
+            input.value = value;
+            input.dispatchEvent(new window.Event("input", { bubbles: true }));
+            if (commit) input.dispatchEvent(new window.Event("change", { bubbles: true }));
+        },
+        save() { window.document.getElementById("btnWfSave").click(); },
+        finishSave(index) {
+            const request = pendingSaves[index];
+            const id = request.method === "POST" ? "created" : request.url.split("/").at(-1);
+            const task = { ...tasks.find((item) => item.task_id === id), ...request.payload, task_id: id };
+            const existing = tasks.findIndex((item) => item.task_id === id);
+            if (existing >= 0) tasks[existing] = task;
+            else tasks.push(task);
+            request.resolve(response(200, { task }));
+        },
+        failSave(index) { pendingSaves[index].reject(new Error("obsolete save failure")); },
+        deferList() { deferNextList = true; },
+        finishList() {
+            if (!deferredList) throw new Error("list refresh was not dispatched");
+            deferredList(response(200, { items: tasks }));
+        },
+        deferValidation() { deferNextValidation = true; },
+        setIssues(issues) { currentIssues = issues; },
+        finishValidation(outcome) {
+            if (!deferredValidation) throw new Error("validation was not dispatched");
+            if (outcome === "failure") deferredValidation.reject(new Error("obsolete validation failure"));
+            else deferredValidation.resolve(response(200, { issues: [
+                { path: "nodes", message: "obsolete issue one" },
+                { path: "edges", message: "obsolete issue two" },
+            ] }));
+        },
+        snapshot() {
+            const graph = JSON.parse(window.document.getElementById("wfGraphJson").value);
+            return {
+                input: input.value, graphName: graph.task_name,
+                id: window.document.getElementById("wfTaskId").value,
+                idDisabled: window.document.getElementById("wfTaskId").disabled,
+                dirty: window.document.getElementById("tab-schedules").classList.contains("is-dirty"),
+                page: pages.at(-1), status: textOf(window, "wfEditorStatus"),
+                issueBadge: textOf(window, "wfIssueBadge"),
+            };
+        },
+    };
+}
+
+async function workflowEditorSave(env, target) {
+    const fixture = workflowEditorFixture(env);
+    const { window } = env;
+    await window.SchedulesController.refresh();
+    if (target === "new") {
+        window.document.getElementById("btnSchedulesNew").click();
+        window.document.querySelector('[data-preset-id=""]').click();
+    } else fixture.open("A");
+    await tick();
+    fixture.edit("first-edit");
+    fixture.save();
+    await tick();
+    if (!fixture.pendingSaves.length) throw new Error("save was not dispatched");
+    if (target.startsWith("switch") || target.startsWith("same")) {
+        fixture.open("B");
+        await tick();
+        if (target.startsWith("same")) {
+            fixture.open("A");
+            await tick();
+        }
+    } else if (target === "typing") {
+        fixture.input.focus();
+        fixture.edit("later-edit", false);
+    } else if (target !== "normal" && target !== "refresh") fixture.edit("later-edit");
+    if (target === "refresh") fixture.deferList();
+    const beforeResponse = fixture.snapshot();
+    if (target.endsWith("_failure")) fixture.failSave(0);
+    else fixture.finishSave(0);
+    await tick();
+    if (target === "refresh") {
+        fixture.edit("later-edit");
+        fixture.finishList();
+        await tick();
+    }
+    const afterResponse = fixture.snapshot();
+    if (target === "typing") {
+        fixture.input.blur();
+        fixture.input.dispatchEvent(new window.Event("change", { bubbles: true }));
+    }
+    let secondSave = null;
+    if (["edited", "new", "typing", "refresh"].includes(target)) {
+        fixture.save();
+        await tick();
+        const request = fixture.pendingSaves[1];
+        if (!request) throw new Error("second save was not dispatched");
+        secondSave = { url: request.url, method: request.method, name: request.payload.task_name };
+        fixture.finishSave(1);
+        await tick();
+    }
+    return { beforeResponse, afterResponse, final: fixture.snapshot(), secondSave,
+        firstSave: { method: fixture.pendingSaves[0].method, name: fixture.pendingSaves[0].payload.task_name } };
+}
+
+for (const target of ["normal", "edited", "switch", "same", "switch_failure", "same_failure", "new", "typing", "refresh"]) {
+    SCENARIOS[`workflow_editor_save_${target}`] = (env) => workflowEditorSave(env, target);
+}
+
+for (const target of ["switch", "edit"]) {
+    for (const outcome of ["response", "failure"]) {
+        SCENARIOS[`workflow_editor_validation_${target}_${outcome}`] = async (env) => {
+            const fixture = workflowEditorFixture(env);
+            await env.window.SchedulesController.refresh();
+            fixture.deferValidation();
+            fixture.open("A");
+            await tick();
+            if (target === "switch") {
+                fixture.setIssues([{ path: "nodes", message: "current B issue" }]);
+                fixture.open("B");
+                await tick();
+            } else fixture.edit("current-edit");
+            const beforeResponse = fixture.snapshot();
+            fixture.finishValidation(outcome);
+            await tick();
+            fixture.edit(target === "switch" ? "B-current-edit" : "current-edit");
+            return { beforeResponse, afterResponse: fixture.snapshot() };
+        };
+    }
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
@@ -3405,6 +3583,8 @@ async function main() {
     const env = createEnv(root, {
         scripts: args.scenario.startsWith("config_autosave_")
             ? ["config-form.js"]
+            : args.scenario.startsWith("workflow_editor_")
+              ? ["workflow-graph.js", "workflow-canvas.js", "workflow-inspector.js", "schedules.js"]
             : [],
     });
     const result = await scenario(env);
diff --git a/tests/test_webui_schedules_behavior.py b/tests/test_webui_schedules_behavior.py
new file mode 100644
index 00000000..74b08b72
--- /dev/null
+++ b/tests/test_webui_schedules_behavior.py
@@ -0,0 +1,76 @@
+"""工作流编辑器通过真实按钮与异步回包交错保存的行为回归。"""
+
+from __future__ import annotations
+
+import pytest
+
+from test_webui_runtime_chat_behavior import run_scenario
+
+
+@pytest.mark.parametrize("target", ["edited", "typing", "refresh"])
+def test_save_preserves_later_edit_and_saves_it_on_next_click(target: str) -> None:
+    result = run_scenario(f"workflow_editor_save_{target}")
+    assert result["firstSave"] == {"method": "PATCH", "name": "first-edit"}
+    assert result["afterResponse"]["input"] == "later-edit"
+    assert result["afterResponse"]["page"] == "editor"
+    assert result["afterResponse"]["status"] == "草稿"
+    if target != "typing":
+        assert result["afterResponse"]["graphName"] == "later-edit"
+        assert result["afterResponse"]["dirty"] is True
+    assert result["secondSave"] == {
+        "url": "/api/runtime/automations/A",
+        "method": "PATCH",
+        "name": "later-edit",
+    }
+    assert result["final"]["dirty"] is False
+    assert result["final"]["page"] == "list"
+
+
+@pytest.mark.parametrize("target", ["switch", "same", "switch_failure", "same_failure"])
+def test_old_save_cannot_replace_reopened_editor(target: str) -> None:
+    result = run_scenario(f"workflow_editor_save_{target}")
+    assert result["afterResponse"] == result["beforeResponse"]
+    assert result["afterResponse"]["input"] == (
+        "B-original" if target.startswith("switch") else "A-original"
+    )
+    assert result["afterResponse"]["page"] == "editor"
+
+
+def test_new_task_keeps_later_draft_and_uses_assigned_id_for_next_save() -> None:
+    result = run_scenario("workflow_editor_save_new")
+    assert result["firstSave"] == {"method": "POST", "name": "first-edit"}
+    assert result["afterResponse"]["input"] == "later-edit"
+    assert result["afterResponse"]["graphName"] == "later-edit"
+    assert result["afterResponse"]["dirty"] is True
+    assert result["afterResponse"]["status"] == "草稿"
+    assert result["afterResponse"]["id"] == "created"
+    assert result["afterResponse"]["idDisabled"] is True
+    assert result["secondSave"] == {
+        "url": "/api/runtime/automations/created",
+        "method": "PATCH",
+        "name": "later-edit",
+    }
+    assert result["final"]["dirty"] is False
+
+
+def test_unchanged_save_updates_baseline_and_returns_to_list() -> None:
+    result = run_scenario("workflow_editor_save_normal")
+    assert result["afterResponse"]["input"] == "first-edit"
+    assert result["afterResponse"]["graphName"] == "first-edit"
+    assert result["afterResponse"]["dirty"] is False
+    assert result["afterResponse"]["page"] == "list"
+    assert result["afterResponse"]["status"] == "自动化已保存"
+
+
+@pytest.mark.parametrize("target", ["switch", "edit"])
+@pytest.mark.parametrize("outcome", ["response", "failure"])
+def test_late_validation_cannot_replace_current_editor_issues(
+    target: str, outcome: str
+) -> None:
+    result = run_scenario(f"workflow_editor_validation_{target}_{outcome}")
+    assert (
+        result["afterResponse"]["issueBadge"] == result["beforeResponse"]["issueBadge"]
+    )
+    assert result["afterResponse"]["input"] == (
+        "B-current-edit" if target == "switch" else "current-edit"
+    )

From 8133c35952b8ecd333eb63752e5d8167acfd06f8 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:56:25 +0800
Subject: [PATCH 062/121] fix(cognitive): repair profile indexes before
 confirming skipped merges

---
 docs/cognitive-memory.md                    |   2 +-
 src/Undefined/cognitive/historian/worker.py |  43 ++++++-
 tests/test_cognitive_historian_ordering.py  | 122 +++++++++++++++++++-
 3 files changed, 162 insertions(+), 5 deletions(-)

diff --git a/docs/cognitive-memory.md b/docs/cognitive-memory.md
index 9c161ec9..14bb8711 100644
--- a/docs/cognitive-memory.md
+++ b/docs/cognitive-memory.md
@@ -100,7 +100,7 @@ end → pending（持久化入队顺序）
 
 昵称刷新先更新侧写向量，再提交 Markdown 文件中的新名称。向量暂时不可写时，文件仍保留旧名称，后续同名消息可继续重试，重启后也不会因名称已更新而跳过。文件写入失败时向量可能已更新，但下一次刷新仍按实际文件重试；名称相同且无需刷新时不重复写入。
 
-**进度与恢复**：任务保存 `_enqueue_order` 以及 `_historian_progress`（已改写文本、已入库事件数、已完成侧写目标）。自动重试只处理未完成部分，阶段切换不增加 `_retry_count`。文件、向量和目标进度均提交后才放行下一个同实体更新；明确 `skip=true` 也会完成目标。没有有效更新或明确跳过的模型结束按失败处理。
+**进度与恢复**：任务保存 `_enqueue_order` 以及 `_historian_progress`（已改写文本、已入库事件数、已完成侧写目标）。自动重试只处理未完成部分，阶段切换不增加 `_retry_count`。文件、向量和目标进度均提交后才放行下一个同实体更新。明确 `skip=true` 时不改写文件，但仍从当前侧写快照补齐向量索引，再保存目标完成进度；向量失败继续重试，不能因模型判定无需修改而提前确认任务。没有 frontmatter 的旧侧写以原文正文兼容索引；没有侧写文件时无需写入向量。没有有效更新或明确跳过的模型结束按失败处理。
 
 失败不会自动回滚已经写入的侧写文件。向量写入或进度保存失败时，重试会重新读取当前实际文件；重试耗尽后，后续任务同样基于当前实际版本继续。正常停止等待在途阶段结束；外层取消或停止超时触发取消时，事件改写和侧写合并的模型调用可立即中断，只等待已经开始的文件、向量、对应进度及队列状态提交收敛，再释放实体占用。取消后尚未完成队列切换的任务保留 `processing` 与已保存进度，后续恢复时不重做已提交部分。启动及轮询恢复超过 `stale_job_timeout_seconds` 的遗留 `processing`，排除活跃任务；未达到恢复阈值的遗留任务仍占其未完成实体的顺位，不阻塞其他实体。
 
diff --git a/src/Undefined/cognitive/historian/worker.py b/src/Undefined/cognitive/historian/worker.py
index b4370a16..74a42423 100644
--- a/src/Undefined/cognitive/historian/worker.py
+++ b/src/Undefined/cognitive/historian/worker.py
@@ -18,6 +18,9 @@
 )
 from Undefined.cognitive.service.helpers import (
     _build_profile_vector_payload,
+    _current_profile_name,
+    _normalize_profile_tags,
+    _parse_profile_markdown,
     _profile_section_error,
     _serialize_profile_markdown,
 )
@@ -563,6 +566,36 @@ async def _write_profile(
             perspective,
         )
 
+    async def _sync_profile_vector(
+        self, entity_type: str, entity_id: str, profile: str | None
+    ) -> None:
+        """skip 仍需补齐当前文件索引，不能提前确认失败写入的目标。"""
+        if profile is None:
+            return
+        parsed = _parse_profile_markdown(profile)
+        if parsed is None:
+            # 兼容没有 frontmatter 的旧侧写，仅将原文作为正文索引。
+            frontmatter: dict[str, Any] = {}
+            evaluation, summary, roast = "", profile, ""
+        else:
+            frontmatter, evaluation, summary, roast = parsed
+        document, metadata = _build_profile_vector_payload(
+            entity_type=entity_type,
+            entity_id=entity_id,
+            effective_name=_current_profile_name(entity_type, frontmatter) or entity_id,
+            tags=_normalize_profile_tags(frontmatter.get("tags")),
+            summary=summary,
+            evaluation=evaluation,
+            roast=roast,
+        )
+        await call_vector_store_method(
+            self._vector_store.upsert_profile,
+            f"{entity_type}:{entity_id}",
+            document,
+            metadata,
+            priority=CHROMA_PRIORITY_BACKGROUND,
+        )
+
     @staticmethod
     def _historical_event_dedupe_key(
         event: dict[str, Any],
@@ -896,7 +929,15 @@ async def _merge_profile_target(
                             skip_reason or "unspecified",
                         )
                         await run_cancellation_safe(
-                            self._commit_profile_target(job, event_id, target, progress)
+                            self._commit_profile_target(
+                                job,
+                                event_id,
+                                target,
+                                progress,
+                                self._sync_profile_vector(
+                                    entity_type, entity_id, existing_profile
+                                ),
+                            )
                         )
                         tool_results.append(
                             {
diff --git a/tests/test_cognitive_historian_ordering.py b/tests/test_cognitive_historian_ordering.py
index ab3167cd..6cab32c3 100644
--- a/tests/test_cognitive_historian_ordering.py
+++ b/tests/test_cognitive_historian_ordering.py
@@ -22,7 +22,7 @@
 from Undefined.cognitive.job_queue import JobQueue, QueuedJob
 from Undefined.cognitive.profile_storage import ProfileStorage
 from Undefined.cognitive.service import CognitiveService
-from Undefined.utils.io import write_json
+from Undefined.utils.io import read_json, write_json
 
 
 def make_job(label: str, *keys: EntityKey) -> dict[str, Any]:
@@ -400,6 +400,115 @@ async def test_vector_failure_retries_current_file_before_follower(
     assert h.worker.rewrites["A"] == 1
 
 
+@pytest.mark.asyncio
+async def test_profile_vector_failure_then_model_skip_repairs_index_before_completion(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    h = harness(tmp_path)
+    key = ("user", "1")
+    h.vectors.profile_failures = 1
+    h.vectors.profiles["user:1"] = "OLD INDEX"
+    submit = h.ai.submit_background_llm_call
+    write = h.storage.write_profile
+    writes: list[str] = []
+
+    async def skip_updated_profile(**kwargs: Any) -> dict[str, Any]:
+        if "profile A" in str(kwargs["messages"][0]["content"]):
+            h.ai.skips.add("A")
+        return await submit(**kwargs)
+
+    async def record_write(entity_type: str, entity_id: str, content: str) -> None:
+        writes.append(content)
+        await write(entity_type, entity_id, content)
+
+    monkeypatch.setattr(h.ai, "submit_background_llm_call", skip_updated_profile)
+    monkeypatch.setattr(h.storage, "write_profile", record_write)
+    await h.queue.enqueue(make_job("A", key))
+    async with running(h):
+        await drained(h)
+    assert len(h.ai.calls) == 2
+    assert "profile A" in h.ai.calls[1][2]
+    assert len(writes) == 1
+    assert (await h.storage.read_profile(*key)) == writes[0]
+    assert "profile A" in h.vectors.profiles["user:1"]
+    assert "evaluation" in h.vectors.profiles["user:1"]
+    assert "roast" in h.vectors.profiles["user:1"]
+    assert h.queue.snapshot()["failed"] == 0
+
+
+@pytest.mark.asyncio
+async def test_skip_after_process_restart_repairs_persisted_profile_index(
+    tmp_path: Path,
+) -> None:
+    h = harness(tmp_path)
+    key = ("user", "1")
+    first = await h.queue.enqueue(make_job("A", key))
+    claimed = await h.queue.claim(first)
+    assert claimed is not None
+    await h.worker._process_job_with_retry(*claimed)
+    h.vectors.profile_failures = 1
+    claimed = await h.queue.claim(first)
+    assert claimed is not None
+    await h.worker._process_job_with_retry(
+        *claimed, target={"entity_type": key[0], "entity_id": key[1]}
+    )
+    written = await h.storage.read_profile(*key)
+    assert written is not None and "profile A" in written
+    assert h.queue.snapshot()["pending"] == 1
+
+    resumed = harness(tmp_path)
+    resumed.ai.skips.add("A")
+    resumed.vectors.profiles["user:1"] = "OLD INDEX"
+    async with running(resumed):
+        await drained(resumed)
+    assert len(resumed.ai.calls) == 1
+    assert not resumed.worker.rewrites
+    assert (await resumed.storage.read_profile(*key)) == written
+    assert "profile A" in resumed.vectors.profiles["user:1"]
+    assert resumed.queue.snapshot()["failed"] == 0
+
+
+@pytest.mark.asyncio
+async def test_skip_index_failure_does_not_confirm_target_complete(
+    tmp_path: Path,
+) -> None:
+    h = harness(tmp_path, retries=1)
+    key = ("user", "1")
+    await h.storage.write_profile(*key, "legacy profile")
+    h.ai.skips.add("A")
+    h.vectors.profiles["user:1"] = "OLD INDEX"
+    h.vectors.profile_failures = 2
+    first = await h.queue.enqueue(make_job("A", key))
+    async with running(h):
+        await drained(h)
+    assert len(h.ai.calls) == 2
+    assert h.queue.snapshot()["failed"] == 1
+    failed_path = Path(h.queue.snapshot()["paths"]["failed"]) / f"{first}.json"
+    failed_data = await read_json(failed_path)
+    assert isinstance(failed_data, dict)
+    assert not HistorianProgress.from_job(failed_data).completed_targets
+    assert h.vectors.profiles["user:1"] == "OLD INDEX"
+    assert (await h.storage.read_profile(*key)) == "legacy profile"
+
+
+@pytest.mark.asyncio
+async def test_later_skip_repairs_profile_left_by_failed_predecessor(
+    tmp_path: Path,
+) -> None:
+    h = harness(tmp_path, retries=0)
+    key = ("user", "1")
+    h.vectors.profile_failures = 1
+    h.ai.skips.add("B")
+    await h.queue.enqueue(make_job("A", key))
+    await h.queue.enqueue(make_job("B", key))
+    async with running(h):
+        await drained(h)
+    assert [label for label, _, _ in h.ai.calls] == ["A", "B"]
+    assert h.queue.snapshot()["failed"] == 1
+    assert "profile A" in h.ai.calls[1][2]
+    assert "profile A" in h.vectors.profiles["user:1"]
+
+
 @pytest.mark.asyncio
 async def test_terminal_vector_failure_does_not_rollback_existing_file(
     tmp_path: Path,
@@ -607,7 +716,9 @@ async def test_cancelling_worker_does_not_wait_for_model(
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("stage", ["file", "vector", "checkpoint", "skip_checkpoint"])
+@pytest.mark.parametrize(
+    "stage", ["file", "vector", "checkpoint", "skip_checkpoint", "skip_vector"]
+)
 async def test_cancellation_waits_for_profile_commit_before_release(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, stage: str
 ) -> None:
@@ -633,9 +744,12 @@ async def blocked_checkpoint(job_id: str, job: dict[str, Any]) -> None:
 
     if stage == "file":
         monkeypatch.setattr(h.storage, "write_profile", blocked_write)
-    elif stage == "vector":
+    elif stage in {"vector", "skip_vector"}:
         h.vectors.profile_gate = gate
         started = h.vectors.profile_started
+        if stage == "skip_vector":
+            await h.storage.write_profile(*key, "legacy profile")
+            h.ai.skips.add("A")
     else:
         monkeypatch.setattr(h.queue, "checkpoint", blocked_checkpoint)
         if stage == "skip_checkpoint":
@@ -669,6 +783,8 @@ async def blocked_checkpoint(job_id: str, job: dict[str, Any]) -> None:
     assert h.worker.rewrites["A"] == 1
     if stage == "skip_checkpoint":
         assert h.ai.calls[-1][2] == "（暂无侧写）"
+    elif stage == "skip_vector":
+        assert h.ai.calls[-1][2] == "legacy profile"
     else:
         assert "profile A" in h.ai.calls[-1][2]
 

From 06a53b6165cab8450a9b7066b51b68c290c62dee Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 19:56:59 +0800
Subject: [PATCH 063/121] fix(memes): guard reanalysis against concurrent
 record mutations

---
 docs/management-api.md         |   1 +
 docs/memes.md                  |   2 +
 docs/openapi.md                |   2 +
 docs/webui-guide.md            |   2 +-
 src/Undefined/memes/models.py  |   2 +
 src/Undefined/memes/service.py | 231 ++++++++++------
 src/Undefined/memes/store.py   |  74 ++++-
 tests/test_meme_reanalysis.py  | 491 +++++++++++++++++++++++++++++++++
 8 files changed, 706 insertions(+), 99 deletions(-)
 create mode 100644 tests/test_meme_reanalysis.py

diff --git a/docs/management-api.md b/docs/management-api.md
index 4468566a..7a5eaf03 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -412,6 +412,7 @@ data: {"stage":"waiting_tools"}
   1. 判定是否表情包
   2. 生成纯文本描述与标签
 - 管理页的“重建索引”只重建向量索引，不重新跑判定。
+- 重分析期间可编辑或删除条目；旧结果会在核对编辑修订和记录身份后丢弃，包含旧任务的删除判定。不会覆盖人工修改、恢复已删除条目或影响同 UID 重新入库的记录。分析保留最新使用次数；已开始的记录与索引写入在取消时仍会先完成收尾。
 
 ## 7. 适用场景
 
diff --git a/docs/memes.md b/docs/memes.md
index 7b98f913..46b8d45f 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -54,4 +54,6 @@ gif_analysis_frames = 6         # GIF 的抽帧数量
 除了在聊天中自动捕获，你还可以通过前端 WebUI 或直接调用 Management API / Runtime API 对库内表情包进行增删改查。
 包括：列出分页表情包库、删除、触发 `reanalyze`（重新判定解析）、`reindex`（强制重建向量缓存）。
 
+重分析期间仍可编辑或删除条目。模型返回后会核对编辑修订和记录身份，过期结果会被丢弃，包括旧任务的删除判定；不会覆盖人工修改、恢复已删除条目或影响同 UID 重新入库的记录。使用次数单独累加，分析保留最新计数；GIF 多帧临时文件按分析任务独立清理。最终记录与索引写入开始后，取消等待该次写入收尾。
+
 * Management API 完整接口参阅 [Management API — Runtime 代理](management-api.md#6-runtime-代理)，Runtime API 直连接口参阅 [Runtime API — 表情包库](openapi.md#表情包库)。
diff --git a/docs/openapi.md b/docs/openapi.md
index 04d6a313..e5099d98 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -226,6 +226,8 @@ HEAD /api/v1/onebot/files/{file_id}?token=...
 - 表情包库条目使用统一图片 `uid`，与普通图片 `<attachment uid="..."/>` 语义一致。
 - 入库文本和向量索引只使用纯文本 `description + tags + aliases`，不依赖 OCR。
 - 后台重跑分析使用两阶段 LLM 管线：先判定，再描述。
+- 重分析期间可继续编辑或删除条目；提交结果时会核对编辑修订和记录身份，丢弃过期结果，包括旧任务的“不属于表情包”删除判定。旧分析不会覆盖人工修改、恢复已删除条目或影响同 UID 重新入库的记录。
+- 发送产生的使用次数不使分析失效；分析只更新生成字段并保留最新计数。最终记录与向量写入按内容串行收尾，取消会等待已开始的写入完成。GIF 多帧重分析的临时文件按任务独立清理。
 
 ### 自动化
 
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index ebc14b06..163f1901 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -118,7 +118,7 @@ AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：
 - **浏览与搜索**：分页列表展示，支持关键词搜索和语义搜索（以及混合模式）。输入时自动防抖搜索，Enter 立即触发。
 - **筛选与排序**：按启用 / 禁用、静态 / 动态、置顶等条件筛选，按创建或更新时间排序。
 - **详情与操作**：查看元数据（UID、描述、标签）和预览图；支持编辑描述 / 标签、启用 / 禁用、置顶 / 取消、删除。
-- **重分析 / 重索引**：对单张表情包重新触发 AI 描述生成或搜索索引更新。
+- **重分析 / 重索引**：对单张表情包重新触发 AI 描述生成或搜索索引更新。分析期间可继续编辑或删除；旧结果不会覆盖人工修改、恢复已删除条目或删除新修订，使用次数仍会保留。
 - **统计概览**：总数、启用 / 禁用数、静态 / 动态数等。
 
 ### 自动化（Automations）
diff --git a/src/Undefined/memes/models.py b/src/Undefined/memes/models.py
index d4637535..115f5d65 100644
--- a/src/Undefined/memes/models.py
+++ b/src/Undefined/memes/models.py
@@ -30,6 +30,8 @@ class MemeRecord:
     updated_at: str = ""
     status: str = "ready"
     segment_data: dict[str, str] = field(default_factory=dict)
+    revision: int = 0
+    generation: str = ""
 
     @property
     def description(self) -> str:
diff --git a/src/Undefined/memes/service.py b/src/Undefined/memes/service.py
index 6af0f798..ee42efae 100644
--- a/src/Undefined/memes/service.py
+++ b/src/Undefined/memes/service.py
@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Mapping
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
 from dataclasses import replace
 import hashlib
 import logging
@@ -34,6 +35,7 @@
 from Undefined.memes.search import MemeSearchMixin
 from Undefined.memes.store import MemeStore
 from Undefined.memes.vector_store import MemeVectorStore
+from Undefined.utils.io import run_cancellation_safe
 from Undefined.utils.paths import ensure_dir
 
 logger = logging.getLogger(__name__)
@@ -66,7 +68,7 @@ def __init__(
         self._ai_client = ai_client
         self._attachment_registry = attachment_registry
         self._retrieval_runtime = retrieval_runtime
-        # Serialize same-content ingest jobs within the process to avoid duplicates.
+        # Serialize same-content ingest and final metadata/index mutations.
         self._ingest_digest_locks: dict[str, IngestDigestLockEntry] = {}
         self._ingest_digest_locks_guard = asyncio.Lock()
         self._global_image_cache: dict[str, AttachmentRecord] = {}
@@ -124,6 +126,18 @@ async def _release_ingest_digest_lock_reference(
             if current is entry and entry.users == 0 and not entry.lock.locked():
                 self._ingest_digest_locks.pop(digest, None)
 
+    @asynccontextmanager
+    async def _meme_mutation_lock(self, digest: str) -> AsyncIterator[None]:
+        entry = await self._acquire_ingest_digest_lock(digest)
+        try:
+            yield
+        finally:
+            await run_cancellation_safe(
+                self._release_ingest_digest_lock_reference(
+                    digest, entry, release_lock=True
+                )
+            )
+
     def _preview_dir(self) -> Path:
         return ensure_dir(Path(self._cfg().preview_dir))
 
@@ -288,57 +302,80 @@ async def update_meme(
         if record is None:
             return None
 
-        next_tags = list(record.tags) if tags is None else _normalize_tags(tags)
-        next_aliases = (
-            list(record.aliases) if aliases is None else _normalize_tags(aliases)
-        )
-        next_manual = (
-            record.manual_description
-            if manual_description is None
-            else str(manual_description or "").strip()
-        )
-        next_enabled = record.enabled if enabled is None else bool(enabled)
-        next_pinned = record.pinned if pinned is None else bool(pinned)
-        next_search_text = build_search_text(
-            manual_description=next_manual,
-            auto_description=record.auto_description,
-            ocr_text="",
-            tags=next_tags,
-            aliases=next_aliases,
-        )
-
-        updated = await self._store.update_fields(
-            uid,
-            {
-                "manual_description": next_manual,
-                "tags_json": next_tags,
-                "aliases_json": next_aliases,
-                "enabled": next_enabled,
-                "pinned": next_pinned,
-                "search_text": next_search_text,
-                "updated_at": _now_iso(),
-            },
-        )
-        if updated is None:
-            return None
-        self._invalidate_global_image_cache(uid)
-        await self._vector_store.upsert(updated)
-        return self.serialize_record(updated)
+        async def commit() -> dict[str, Any] | None:
+            current = await self._store.get(uid)
+            if current is None or current.generation != record.generation:
+                return None
+            next_tags = list(current.tags) if tags is None else _normalize_tags(tags)
+            next_aliases = (
+                list(current.aliases) if aliases is None else _normalize_tags(aliases)
+            )
+            next_manual = (
+                current.manual_description
+                if manual_description is None
+                else str(manual_description or "").strip()
+            )
+            next_search_text = build_search_text(
+                manual_description=next_manual,
+                auto_description=current.auto_description,
+                ocr_text="",
+                tags=next_tags,
+                aliases=next_aliases,
+            )
 
-    async def delete_meme(self, uid: str) -> bool:
-        record = await self._store.delete(uid)
+            updated = await self._store.update_fields(
+                uid,
+                {
+                    "manual_description": next_manual,
+                    "tags_json": next_tags,
+                    "aliases_json": next_aliases,
+                    "enabled": current.enabled if enabled is None else bool(enabled),
+                    "pinned": current.pinned if pinned is None else bool(pinned),
+                    "search_text": next_search_text,
+                    "updated_at": _now_iso(),
+                },
+                expected_record=current,
+            )
+            if updated is None:
+                return None
+            self._invalidate_global_image_cache(uid)
+            await self._vector_store.upsert(updated)
+            return self.serialize_record(updated)
+
+        async with self._meme_mutation_lock(record.content_sha256):
+            return await run_cancellation_safe(commit())
+
+    async def delete_meme(
+        self, uid: str, *, expected_record: MemeRecord | None = None
+    ) -> bool:
+        record = expected_record or await self._store.get(uid)
         if record is None:
             return False
-        self._invalidate_global_image_cache(uid)
-        await self._vector_store.delete(uid)
-        await asyncio.to_thread(self._delete_file_if_exists, Path(record.blob_path))
-        if record.preview_path and record.preview_path != record.blob_path:
+
+        async def commit() -> bool:
+            current = await self._store.get(uid)
+            if current is None or current.generation != record.generation:
+                return False
+            deleted = await self._store.delete(
+                uid, expected_record=expected_record or current
+            )
+            if deleted is None:
+                return False
+            self._invalidate_global_image_cache(uid)
+            await self._vector_store.delete(uid)
             await asyncio.to_thread(
-                self._delete_file_if_exists,
-                Path(record.preview_path),
+                self._delete_file_if_exists, Path(deleted.blob_path)
             )
-        await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
-        return True
+            if deleted.preview_path and deleted.preview_path != deleted.blob_path:
+                await asyncio.to_thread(
+                    self._delete_file_if_exists,
+                    Path(deleted.preview_path),
+                )
+            await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
+            return True
+
+        async with self._meme_mutation_lock(record.content_sha256):
+            return await run_cancellation_safe(commit())
 
     def _delete_file_if_exists(self, path: Path) -> None:
         try:
@@ -704,7 +741,14 @@ async def _process_reindex_job(self, job: Mapping[str, Any]) -> None:
         record = await self._store.get(uid)
         if record is None:
             return
-        await self._vector_store.upsert(record)
+
+        async def commit() -> None:
+            current = await self._store.get(uid)
+            if current is not None and current.generation == record.generation:
+                await self._vector_store.upsert(current)
+
+        async with self._meme_mutation_lock(record.content_sha256):
+            await run_cancellation_safe(commit())
 
     async def _process_reanalyze_job(self, job: Mapping[str, Any]) -> None:
         uid = str(job.get("uid") or "").strip()
@@ -722,45 +766,51 @@ async def _process_reanalyze_job(self, job: Mapping[str, Any]) -> None:
         if record.is_animated:
             cfg = self._cfg()
             if str(getattr(cfg, "gif_analysis_mode", "grid")).lower() == "multi":
-                analyze_path = await self._prepare_gif_multi_frames(
-                    Path(record.blob_path), uid
-                )
+                frame_owner = f"{uid}_{uuid4().hex}"
+                try:
+                    analyze_path = await run_cancellation_safe(
+                        self._prepare_gif_multi_frames(
+                            Path(record.blob_path), frame_owner
+                        )
+                    )
+                    await self._reanalyze_record(record, analyze_path)
+                finally:
+                    await run_cancellation_safe(
+                        asyncio.to_thread(self._cleanup_gif_frame_files, frame_owner)
+                    )
+                return
+        await self._reanalyze_record(record, analyze_path)
+
+    async def _reanalyze_record(
+        self, record: MemeRecord, analyze_path: str | list[str]
+    ) -> None:
+        uid = record.uid
+        ai_client = self._ai_client
+        if ai_client is None:
+            raise RuntimeError("reanalyze requires ai_client")
         try:
-            judgement = await self._ai_client.judge_meme_image(analyze_path)
+            judgement = await ai_client.judge_meme_image(analyze_path)
         except Exception as exc:
             if _is_retryable_llm_error(exc):
-                if isinstance(analyze_path, list):
-                    await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
                 raise
             logger.exception(
                 "[memes] judge stage failed during reanalyze: uid=%s err=%s", uid, exc
             )
-            if isinstance(analyze_path, list):
-                await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
             return
         if not bool(judgement.get("is_meme", False)):
-            if isinstance(analyze_path, list):
-                await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
-            await self.delete_meme(uid)
+            await self.delete_meme(uid, expected_record=record)
             return
         try:
-            described = await self._ai_client.describe_meme_image(analyze_path)
+            described = await ai_client.describe_meme_image(analyze_path)
         except Exception as exc:
             if _is_retryable_llm_error(exc):
-                if isinstance(analyze_path, list):
-                    await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
                 raise
             logger.exception(
                 "[memes] describe stage failed during reanalyze: uid=%s err=%s",
                 uid,
                 exc,
             )
-            if isinstance(analyze_path, list):
-                await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
             return
-        # GIF 多帧文件用完即清理
-        if isinstance(analyze_path, list):
-            await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
         auto_description = str(described.get("description") or "").strip()
         next_tags = _normalize_tags(described.get("tags"))
         if not auto_description and not next_tags:
@@ -768,23 +818,34 @@ async def _process_reanalyze_job(self, job: Mapping[str, Any]) -> None:
                 "[memes] reanalyze describe failed, skip update: uid=%s", uid
             )
             return
-        next_record = replace(
-            record,
-            auto_description=auto_description,
-            ocr_text="",
-            tags=next_tags,
-            search_text=build_search_text(
-                manual_description=record.manual_description,
-                auto_description=auto_description,
-                ocr_text="",
-                tags=next_tags,
-                aliases=record.aliases,
-            ),
-            updated_at=_now_iso(),
-        )
-        saved = await self._store.upsert_record(next_record)
-        self._invalidate_global_image_cache(saved.uid)
-        await self._vector_store.upsert(saved)
+
+        async def commit() -> None:
+            current = await self._store.get(uid)
+            if current is None:
+                return
+            saved = await self._store.update_fields(
+                uid,
+                {
+                    "auto_description": auto_description,
+                    "ocr_text": "",
+                    "tags_json": next_tags,
+                    "search_text": build_search_text(
+                        manual_description=current.manual_description,
+                        auto_description=auto_description,
+                        ocr_text="",
+                        tags=next_tags,
+                        aliases=current.aliases,
+                    ),
+                    "updated_at": _now_iso(),
+                },
+                expected_record=record,
+            )
+            if saved is not None:
+                self._invalidate_global_image_cache(saved.uid)
+                await self._vector_store.upsert(saved)
+
+        async with self._meme_mutation_lock(record.content_sha256):
+            await run_cancellation_safe(commit())
 
     async def _process_ingest_job(self, job: Mapping[str, Any]) -> None:
         if self._attachment_registry is None:
diff --git a/src/Undefined/memes/store.py b/src/Undefined/memes/store.py
index 7c15d73d..9253df89 100644
--- a/src/Undefined/memes/store.py
+++ b/src/Undefined/memes/store.py
@@ -7,6 +7,7 @@
 import sqlite3
 import threading
 from typing import Any, Callable
+from uuid import uuid4
 
 from Undefined.memes.models import MemeRecord, MemeSourceRecord, normalize_string_list
 
@@ -78,6 +79,24 @@ def _row_to_record(row: sqlite3.Row) -> MemeRecord:
         updated_at=str(row["updated_at"] or ""),
         status=str(row["status"] or "ready"),
         segment_data=_json_loads_dict(row["segment_data_json"]),
+        revision=int(row["revision"]),
+        generation=str(row["generation"]),
+    )
+
+
+def _record_condition(
+    uid: str, expected_record: MemeRecord | None
+) -> tuple[str, list[Any]]:
+    if expected_record is None:
+        return "uid = ?", [uid]
+    return (
+        "uid = ? AND revision = ? AND generation = ? AND content_sha256 = ?",
+        [
+            uid,
+            expected_record.revision,
+            expected_record.generation,
+            expected_record.content_sha256,
+        ],
     )
 
 
@@ -138,10 +157,26 @@ def _init_sync(self) -> None:
                     created_at TEXT NOT NULL,
                     updated_at TEXT NOT NULL,
                     status TEXT NOT NULL DEFAULT 'ready',
-                    segment_data_json TEXT NOT NULL DEFAULT '{}'
+                    segment_data_json TEXT NOT NULL DEFAULT '{}',
+                    revision INTEGER NOT NULL DEFAULT 0,
+                    generation TEXT NOT NULL DEFAULT ''
                 )
                 """
             )
+            columns = {str(row[1]) for row in conn.execute("PRAGMA table_info(memes)")}
+            if "revision" not in columns:
+                conn.execute(
+                    "ALTER TABLE memes ADD COLUMN revision INTEGER NOT NULL DEFAULT 0"
+                )
+            if "generation" not in columns:
+                conn.execute(
+                    "ALTER TABLE memes ADD COLUMN generation TEXT NOT NULL DEFAULT ''"
+                )
+            for row in conn.execute("SELECT uid FROM memes WHERE generation = ''"):
+                conn.execute(
+                    "UPDATE memes SET generation = ? WHERE uid = ?",
+                    (uuid4().hex, str(row[0])),
+                )
             conn.execute(
                 """
                 CREATE TABLE IF NOT EXISTS meme_sources (
@@ -280,8 +315,8 @@ def _run() -> MemeRecord:
                         file_size, width, height, is_animated, enabled, pinned,
                         auto_description, manual_description, ocr_text, tags_json,
                         aliases_json, search_text, use_count, last_used_at,
-                        created_at, updated_at, status, segment_data_json
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        created_at, updated_at, status, segment_data_json, generation
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                     ON CONFLICT(uid) DO UPDATE SET
                         content_sha256 = excluded.content_sha256,
                         blob_path = excluded.blob_path,
@@ -304,7 +339,8 @@ def _run() -> MemeRecord:
                         created_at = excluded.created_at,
                         updated_at = excluded.updated_at,
                         status = excluded.status,
-                        segment_data_json = excluded.segment_data_json
+                        segment_data_json = excluded.segment_data_json,
+                        revision = memes.revision + 1
                     """,
                     (
                         record.uid,
@@ -330,6 +366,7 @@ def _run() -> MemeRecord:
                         record.updated_at,
                         record.status,
                         _json_dumps(record.segment_data),
+                        uuid4().hex,
                     ),
                 )
                 conn.execute("DELETE FROM meme_fts WHERE uid = ?", (record.uid,))
@@ -549,7 +586,11 @@ def _run() -> tuple[list[MemeRecord], int]:
         return await asyncio.to_thread(_run)
 
     async def update_fields(
-        self, uid: str, values: dict[str, Any]
+        self,
+        uid: str,
+        values: dict[str, Any],
+        *,
+        expected_record: MemeRecord | None = None,
     ) -> MemeRecord | None:
         await self.initialize()
         if not values:
@@ -557,9 +598,11 @@ async def update_fields(
 
         def _run() -> MemeRecord | None:
             with self._connect() as conn:
+                conn.execute("BEGIN IMMEDIATE")
+                condition, condition_params = _record_condition(uid, expected_record)
                 row = conn.execute(
-                    "SELECT * FROM memes WHERE uid = ? LIMIT 1",
-                    (uid,),
+                    f"SELECT * FROM memes WHERE {condition} LIMIT 1",
+                    tuple(condition_params),
                 ).fetchone()
                 if row is None:
                     return None
@@ -591,9 +634,10 @@ def _run() -> MemeRecord | None:
                     params.append(normalizer(raw_value))
                 if not assignments:
                     return _row_to_record(row)
-                params.append(uid)
+                assignments.append("revision = revision + 1")
+                params.extend(condition_params)
                 conn.execute(
-                    f"UPDATE memes SET {', '.join(assignments)} WHERE uid = ?",
+                    f"UPDATE memes SET {', '.join(assignments)} WHERE {condition}",
                     tuple(params),
                 )
                 search_text_row = conn.execute(
@@ -645,19 +689,23 @@ def _run() -> MemeRecord | None:
 
         return await asyncio.to_thread(_run)
 
-    async def delete(self, uid: str) -> MemeRecord | None:
+    async def delete(
+        self, uid: str, *, expected_record: MemeRecord | None = None
+    ) -> MemeRecord | None:
         await self.initialize()
 
         def _run() -> MemeRecord | None:
             with self._connect() as conn:
+                conn.execute("BEGIN IMMEDIATE")
+                condition, params = _record_condition(uid, expected_record)
                 row = conn.execute(
-                    "SELECT * FROM memes WHERE uid = ? LIMIT 1",
-                    (uid,),
+                    f"SELECT * FROM memes WHERE {condition} LIMIT 1",
+                    tuple(params),
                 ).fetchone()
                 if row is None:
                     return None
                 record = _row_to_record(row)
-                conn.execute("DELETE FROM memes WHERE uid = ?", (uid,))
+                conn.execute(f"DELETE FROM memes WHERE {condition}", tuple(params))
                 conn.execute("DELETE FROM meme_sources WHERE uid = ?", (uid,))
                 conn.execute("DELETE FROM meme_fts WHERE uid = ?", (uid,))
                 conn.commit()
diff --git a/tests/test_meme_reanalysis.py b/tests/test_meme_reanalysis.py
new file mode 100644
index 00000000..60e44e28
--- /dev/null
+++ b/tests/test_meme_reanalysis.py
@@ -0,0 +1,491 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from pathlib import Path
+import sqlite3
+import threading
+from types import SimpleNamespace
+from typing import Any, cast
+
+from aiohttp import web
+from PIL import Image
+import pytest
+
+from Undefined.api._context import RuntimeAPIContext
+from Undefined.api.routes.memes import meme_delete_handler, meme_update_handler
+from Undefined.memes import MemeService, MemeStore, MemeVectorStore
+from Undefined.memes.models import MemeRecord
+from Undefined.memes._image_utils import extract_gif_frames
+
+
+class _ControlledAI:
+    def __init__(self, *, is_meme: bool = True) -> None:
+        self.is_meme = is_meme
+        self.entered = asyncio.Event()
+        self.release = asyncio.Event()
+
+    async def judge_meme_image(self, _path: str | list[str]) -> dict[str, Any]:
+        self.entered.set()
+        await self.release.wait()
+        return {"is_meme": self.is_meme}
+
+    async def describe_meme_image(self, _path: str | list[str]) -> dict[str, Any]:
+        return {"description": "generated description", "tags": ["generated"]}
+
+
+class _RecordingVectors:
+    def __init__(self) -> None:
+        self.records: dict[str, MemeRecord] = {}
+        self.block_analysis = False
+        self.entered = asyncio.Event()
+        self.release = asyncio.Event()
+
+    async def upsert(self, record: MemeRecord) -> None:
+        if self.block_analysis and record.manual_description == "original manual":
+            self.entered.set()
+            await self.release.wait()
+        self.records[record.uid] = record
+
+    async def delete(self, uid: str) -> None:
+        self.records.pop(uid, None)
+
+
+def _config(tmp_path: Path) -> SimpleNamespace:
+    return SimpleNamespace(enabled=True, preview_dir=str(tmp_path / "previews"))
+
+
+def _record(tmp_path: Path) -> MemeRecord:
+    blob = tmp_path / "meme.png"
+    blob.write_bytes(b"isolated image")
+    return MemeRecord(
+        uid="pic_reanalysis",
+        content_sha256="same content",
+        blob_path=str(blob),
+        preview_path=str(blob),
+        mime_type="image/png",
+        file_size=blob.stat().st_size,
+        width=1,
+        height=1,
+        is_animated=False,
+        enabled=True,
+        pinned=False,
+        auto_description="original auto",
+        manual_description="original manual",
+        ocr_text="",
+        tags=["original"],
+        aliases=["original alias"],
+        search_text="original manual original original alias",
+        use_count=7,
+        created_at="2026-10-06T12:00:00",
+        updated_at="2026-10-06T12:00:00",
+    )
+
+
+async def _fixture(
+    tmp_path: Path, ai: _ControlledAI, *, store: MemeStore | None = None
+) -> tuple[MemeService, MemeStore, _RecordingVectors, MemeRecord]:
+    store = store or MemeStore(tmp_path / "memes.sqlite3")
+    record = await store.upsert_record(_record(tmp_path))
+    vectors = _RecordingVectors()
+    await vectors.upsert(record)
+    config = _config(tmp_path)
+    service = MemeService(
+        config_getter=lambda: config,
+        store=store,
+        vector_store=cast(MemeVectorStore, vectors),
+        ai_client=ai,
+    )
+    return service, store, vectors, record
+
+
+def _context(service: MemeService) -> RuntimeAPIContext:
+    return RuntimeAPIContext(
+        config_getter=lambda: SimpleNamespace(),
+        onebot=None,
+        ai=None,
+        command_dispatcher=None,
+        queue_manager=None,
+        history_manager=None,
+        meme_service=service,
+    )
+
+
+def _request(uid: str, payload: dict[str, Any] | None = None) -> web.Request:
+    async def json_body() -> dict[str, Any]:
+        return payload or {}
+
+    return cast(web.Request, SimpleNamespace(match_info={"uid": uid}, json=json_body))
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("is_meme", [True, False])
+@pytest.mark.parametrize("mutation", ["edit", "delete", "reinsert"])
+async def test_reanalysis_discards_result_after_api_mutation(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    is_meme: bool,
+    mutation: str,
+) -> None:
+    ai = _ControlledAI(is_meme=is_meme)
+    service, store, vectors, original = await _fixture(tmp_path, ai)
+    # Same-second edits must still invalidate the old analysis.
+    monkeypatch.setattr("Undefined.memes.service._now_iso", lambda: original.updated_at)
+    task = asyncio.create_task(
+        service.process_job({"kind": "reanalyze", "uid": original.uid})
+    )
+    try:
+        await asyncio.wait_for(ai.entered.wait(), timeout=3)
+        if mutation == "edit":
+            response = await meme_update_handler(
+                _context(service),
+                _request(
+                    original.uid,
+                    {
+                        "manual_description": "new manual",
+                        "tags": ["new tag"],
+                        "aliases": ["new alias"],
+                        "enabled": False,
+                        "pinned": True,
+                    },
+                ),
+            )
+            assert response.status == 200
+            edited = await store.get(original.uid)
+            assert edited is not None
+            assert edited.updated_at == original.updated_at
+            assert edited.revision > original.revision
+        else:
+            response = await meme_delete_handler(
+                _context(service), _request(original.uid)
+            )
+            assert response.status == 200
+            assert not Path(original.blob_path).exists()
+            if mutation == "reinsert":
+                Path(original.blob_path).write_bytes(b"isolated image")
+                inserted = await store.upsert_record(
+                    replace(original, manual_description="new incarnation")
+                )
+                await vectors.upsert(inserted)
+                assert inserted.revision == original.revision
+                assert inserted.generation != original.generation
+        before = await store.get(original.uid)
+        vector_before = vectors.records.get(original.uid)
+        ai.release.set()
+        await asyncio.wait_for(task, timeout=3)
+        assert await store.get(original.uid) == before
+        assert vectors.records.get(original.uid) == vector_before
+        assert Path(original.blob_path).exists() == (mutation != "delete")
+        assert service._ingest_digest_locks == {}
+    finally:
+        ai.release.set()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("phase", ["analysis", "commit"])
+async def test_reanalysis_preserves_concurrent_usage_without_discarding_description(
+    tmp_path: Path, phase: str
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _ControlledStore(MemeStore):
+        async def update_fields(
+            self,
+            uid: str,
+            values: dict[str, Any],
+            *,
+            expected_record: MemeRecord | None = None,
+        ) -> MemeRecord | None:
+            if phase == "commit" and "auto_description" in values:
+                entered.set()
+                await release.wait()
+            return await super().update_fields(
+                uid, values, expected_record=expected_record
+            )
+
+    ai = _ControlledAI()
+    service, store, vectors, original = await _fixture(
+        tmp_path, ai, store=_ControlledStore(tmp_path / "memes.sqlite3")
+    )
+    task = asyncio.create_task(
+        service.process_job({"kind": "reanalyze", "uid": original.uid})
+    )
+    try:
+        await asyncio.wait_for(ai.entered.wait(), timeout=3)
+        if phase == "commit":
+            ai.release.set()
+            await asyncio.wait_for(entered.wait(), timeout=3)
+        used_at = "2026-10-06T12:00:02"
+        used = await store.increment_use(original.uid, used_at)
+        assert used is not None and used.revision == original.revision
+        ai.release.set()
+        release.set()
+        await asyncio.wait_for(task, timeout=3)
+        saved = await store.get(original.uid)
+        assert saved is not None
+        assert saved.auto_description == "generated description"
+        assert saved.tags == ["generated"]
+        assert saved.manual_description == original.manual_description
+        assert saved.aliases == original.aliases
+        assert saved.use_count == 8
+        assert saved.last_used_at == used_at
+        assert vectors.records[original.uid] == saved
+    finally:
+        ai.release.set()
+        release.set()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mutation", ["edit", "delete"])
+async def test_cancelled_reanalysis_finishes_index_before_following_api_mutation(
+    tmp_path: Path, mutation: str
+) -> None:
+    ai = _ControlledAI()
+    ai.release.set()
+    service, store, vectors, original = await _fixture(tmp_path, ai)
+    vectors.block_analysis = True
+    analysis = asyncio.create_task(
+        service.process_job({"kind": "reanalyze", "uid": original.uid})
+    )
+    following: asyncio.Task[web.Response] | None = None
+    try:
+        await asyncio.wait_for(vectors.entered.wait(), timeout=3)
+        analysis.cancel()
+        if mutation == "edit":
+            following = asyncio.create_task(
+                meme_update_handler(
+                    _context(service),
+                    _request(original.uid, {"manual_description": "new manual"}),
+                )
+            )
+        else:
+            following = asyncio.create_task(
+                meme_delete_handler(_context(service), _request(original.uid))
+            )
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        analysis.cancel()
+        assert not analysis.done()
+        assert not following.done()
+        vectors.release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(analysis, timeout=3)
+        response = await asyncio.wait_for(following, timeout=3)
+        assert response.status == 200
+        saved = await store.get(original.uid)
+        if mutation == "edit":
+            assert saved is not None and saved.manual_description == "new manual"
+            assert vectors.records[original.uid] == saved
+        else:
+            assert saved is None
+            assert original.uid not in vectors.records
+            assert not Path(original.blob_path).exists()
+        assert service._ingest_digest_locks == {}
+    finally:
+        vectors.release.set()
+        await asyncio.gather(
+            analysis, *([following] if following else []), return_exceptions=True
+        )
+
+
+@pytest.mark.asyncio
+async def test_existing_meme_database_migrates_identity_and_guards_stale_writes(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "legacy.sqlite3"
+    with sqlite3.connect(path) as conn:
+        conn.execute("""
+            CREATE TABLE memes (
+                uid TEXT PRIMARY KEY, content_sha256 TEXT NOT NULL,
+                blob_path TEXT NOT NULL, preview_path TEXT, mime_type TEXT NOT NULL,
+                file_size INTEGER NOT NULL, width INTEGER, height INTEGER,
+                is_animated INTEGER NOT NULL DEFAULT 0, enabled INTEGER NOT NULL DEFAULT 1,
+                pinned INTEGER NOT NULL DEFAULT 0, auto_description TEXT NOT NULL DEFAULT '',
+                manual_description TEXT NOT NULL DEFAULT '', ocr_text TEXT NOT NULL DEFAULT '',
+                tags_json TEXT NOT NULL DEFAULT '[]', aliases_json TEXT NOT NULL DEFAULT '[]',
+                search_text TEXT NOT NULL DEFAULT '', use_count INTEGER NOT NULL DEFAULT 0,
+                last_used_at TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'ready',
+                segment_data_json TEXT NOT NULL DEFAULT '{}'
+            )
+        """)
+        conn.execute(
+            "INSERT INTO memes(uid, content_sha256, blob_path, mime_type, file_size, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                "pic_legacy",
+                "digest",
+                str(tmp_path / "legacy.png"),
+                "image/png",
+                1,
+                "same second",
+                "same second",
+            ),
+        )
+    store = MemeStore(path)
+    original = await store.get("pic_legacy")
+    assert original is not None and original.revision == 0 and original.generation
+    reopened = MemeStore(path)
+    assert await reopened.get(original.uid) == original
+    changed = await store.update_fields(
+        original.uid,
+        {
+            "manual_description": "fresh",
+            "search_text": "fresh",
+            "updated_at": original.updated_at,
+        },
+    )
+    assert changed is not None and changed.revision == 1
+    assert changed.generation == original.generation
+    assert (
+        await store.update_fields(
+            original.uid, {"search_text": "stale"}, expected_record=original
+        )
+        is None
+    )
+    assert await store.delete(original.uid, expected_record=original) is None
+    assert await store.get(original.uid) == changed
+    assert (await store.search_keyword("fresh", limit=5))[0][
+        "record"
+    ].uid == original.uid
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("old_is_meme", [True, False])
+async def test_stale_gif_analysis_only_cleans_its_own_frames(
+    tmp_path: Path, old_is_meme: bool
+) -> None:
+    entered = [asyncio.Event(), asyncio.Event()]
+    release = [asyncio.Event(), asyncio.Event()]
+    inputs: list[list[str]] = []
+
+    class _ConcurrentAI:
+        async def judge_meme_image(self, paths: list[str]) -> dict[str, Any]:
+            index = len(inputs)
+            inputs.append(paths)
+            entered[index].set()
+            await release[index].wait()
+            assert all(Path(path).is_file() for path in paths)
+            return {"is_meme": old_is_meme if index == 0 else True}
+
+        async def describe_meme_image(self, paths: list[str]) -> dict[str, Any]:
+            assert all(Path(path).is_file() for path in paths)
+            return {"description": "generated description", "tags": ["generated"]}
+
+    service, store, vectors, original = await _fixture(tmp_path, _ControlledAI())
+    gif = tmp_path / "meme.gif"
+    first = Image.new("RGBA", (2, 2), "red")
+    second = Image.new("RGBA", (2, 2), "blue")
+    first.save(gif, format="GIF", save_all=True, append_images=[second], duration=100)
+    first.close()
+    second.close()
+    record = await store.upsert_record(
+        replace(original, blob_path=str(gif), preview_path=None, is_animated=True)
+    )
+    config = _config(tmp_path)
+    config.gif_analysis_mode = "multi"
+    service._config_getter = lambda: config
+    service._ai_client = _ConcurrentAI()
+    old = asyncio.create_task(
+        service.process_job({"kind": "reanalyze", "uid": record.uid})
+    )
+    new: asyncio.Task[None] | None = None
+    try:
+        await asyncio.wait_for(entered[0].wait(), timeout=3)
+        response = await meme_update_handler(
+            _context(service),
+            _request(record.uid, {"manual_description": "new manual"}),
+        )
+        assert response.status == 200
+        new = asyncio.create_task(
+            service.process_job({"kind": "reanalyze", "uid": record.uid})
+        )
+        await asyncio.wait_for(entered[1].wait(), timeout=3)
+        assert not set(inputs[0]) & set(inputs[1])
+        release[0].set()
+        await asyncio.wait_for(old, timeout=3)
+        assert not any(Path(path).exists() for path in inputs[0])
+        assert all(Path(path).is_file() for path in inputs[1])
+        assert not new.done()
+        release[1].set()
+        await asyncio.wait_for(new, timeout=3)
+        saved = await store.get(record.uid)
+        assert saved is not None
+        assert saved.manual_description == "new manual"
+        assert saved.auto_description == "generated description"
+        assert vectors.records[record.uid] == saved
+        assert gif.is_file()
+        assert not list(Path(config.preview_dir).glob("*_f*.png"))
+    finally:
+        for event in release:
+            event.set()
+        await asyncio.gather(old, *([new] if new else []), return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_cancelled_gif_frame_creation_waits_for_thread_before_cleanup(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    ai = _ControlledAI()
+    service, store, _vectors, original = await _fixture(tmp_path, ai)
+    gif = tmp_path / "meme.gif"
+    image = Image.new("RGBA", (2, 2), "red")
+    image.save(gif, format="GIF")
+    image.close()
+    record = await store.upsert_record(
+        replace(original, blob_path=str(gif), preview_path=None, is_animated=True)
+    )
+    config = _config(tmp_path)
+    config.gif_analysis_mode = "multi"
+    service._config_getter = lambda: config
+    entered = threading.Event()
+    release = threading.Event()
+
+    def controlled_extract(source: Path, frames: int) -> list[Image.Image]:
+        entered.set()
+        assert release.wait(timeout=5)
+        return extract_gif_frames(source, frames)
+
+    monkeypatch.setattr(
+        "Undefined.memes.service._extract_gif_frames", controlled_extract
+    )
+    task = asyncio.create_task(
+        service.process_job({"kind": "reanalyze", "uid": record.uid})
+    )
+    try:
+        assert await asyncio.to_thread(entered.wait, 3)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        assert not task.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=3)
+        assert await store.get(record.uid) == record
+        assert gif.is_file()
+        assert not list(Path(config.preview_dir).glob("*_f*.png"))
+        assert not ai.entered.is_set()
+    finally:
+        release.set()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("is_meme", [True, False])
+async def test_current_reanalysis_applies_positive_or_negative_result(
+    tmp_path: Path, is_meme: bool
+) -> None:
+    ai = _ControlledAI(is_meme=is_meme)
+    ai.release.set()
+    service, store, vectors, original = await _fixture(tmp_path, ai)
+    await service.process_job({"kind": "reanalyze", "uid": original.uid})
+    saved = await store.get(original.uid)
+    if is_meme:
+        assert saved is not None and saved.auto_description == "generated description"
+        assert vectors.records[original.uid] == saved
+    else:
+        assert saved is None
+        assert original.uid not in vectors.records
+        assert not Path(original.blob_path).exists()

From beabf70a3f6c6726c8fea8be2ae31c718d3e7814 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 20:00:01 +0800
Subject: [PATCH 064/121] fix(webui): scope WeChat login work to its dialog

---
 docs/webui-guide.md                     |   1 +
 src/Undefined/webui/static/js/weixin.js | 103 +++++++++---
 tests/frontend/runtime_chat_harness.js  | 213 ++++++++++++++++++++++++
 tests/test_webui_weixin_behavior.py     |  82 +++++++++
 4 files changed, 375 insertions(+), 24 deletions(-)
 create mode 100644 tests/test_webui_weixin_behavior.py

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 163f1901..d39b67a7 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -141,6 +141,7 @@ WebUI 会先验证登录态，再通过后端代理访问 Runtime API 的 `/api/
 可从首页的“微信接入”快捷入口直接打开，也可进入控制台后从侧栏切换到该页面。
 
 - **扫码绑定**：填写本地帐号别名与逻辑 QQ 号；页面会在二维码生成期间显示加载状态，并支持刷新二维码、查询扫码状态和提交验证码。
+- **登录弹窗隔离**：关闭或重新打开弹窗会停止旧会话轮询、释放旧二维码并取消旧登录会话。创建登录、二维码、刷新、验证码与扫码状态的迟到响应只作用于原弹窗；关闭前尚未返回的登录创建请求返回后也会取消其旧会话，不会覆盖新帐号别名或关闭新弹窗。
 - **帐号生命周期**：查看在线/离线/异常状态，启停、改绑或解绑帐号。
 - **权限确认**：绑定管理员或超级管理员逻辑 QQ 时，页面要求第二次明确确认。
 - **隔离来源**：只显示未匹配来源的元数据与计数；消息正文不会进入 WebUI、历史或 AI。
diff --git a/src/Undefined/webui/static/js/weixin.js b/src/Undefined/webui/static/js/weixin.js
index 23b466e1..bdcb16e8 100644
--- a/src/Undefined/webui/static/js/weixin.js
+++ b/src/Undefined/webui/static/js/weixin.js
@@ -18,6 +18,7 @@
         qrObjectUrl: "",
         qrRevision: 0,
         dialogPreviousFocus: null,
+        dialogGeneration: 0,
     };
 
     class WeixinRequestError extends Error {
@@ -393,6 +394,7 @@
 
     async function loadAll(force = false) {
         if (weixinState.busy || (!force && weixinState.loaded)) return;
+        const generation = weixinState.dialogGeneration;
         setBusy(true);
         setPageStatus(t("common.loading"));
         try {
@@ -415,7 +417,27 @@
                 "error",
             );
         } finally {
-            setBusy(false);
+            if (generation === weixinState.dialogGeneration) setBusy(false);
+        }
+    }
+
+    function isCurrentDialog(generation, sessionId) {
+        return (
+            generation === weixinState.dialogGeneration &&
+            !get("weixinDialogBackdrop")?.hidden &&
+            (sessionId === undefined || sessionId === weixinState.sessionId)
+        );
+    }
+
+    async function cancelLoginSession(sessionId) {
+        if (!sessionId) return;
+        try {
+            await requestJson(
+                `${ENDPOINT}/login/${encodeURIComponent(sessionId)}`,
+                { method: "DELETE" },
+            );
+        } catch (_error) {
+            // The session may already be confirmed or expired.
         }
     }
 
@@ -430,7 +452,10 @@
     function schedulePoll(delay = POLL_DELAY_MS) {
         stopPolling();
         if (!weixinState.sessionId) return;
+        const generation = weixinState.dialogGeneration;
+        const sessionId = weixinState.sessionId;
         weixinState.pollTimer = window.setTimeout(() => {
+            if (!isCurrentDialog(generation, sessionId)) return;
             pollLogin().catch(() => undefined);
         }, delay);
     }
@@ -470,8 +495,13 @@
     }
 
     async function loadQrImage() {
+        const generation = weixinState.dialogGeneration;
         const sessionId = weixinState.sessionId;
+        const revision = weixinState.qrRevision;
         if (!sessionId) return;
+        const isCurrent = () =>
+            isCurrentDialog(generation, sessionId) &&
+            revision === weixinState.qrRevision;
         clearQrImage();
         setQrFrameState("loading");
         try {
@@ -487,7 +517,7 @@
                 );
             }
             const blob = await response.blob();
-            if (sessionId !== weixinState.sessionId) return;
+            if (!isCurrent()) return;
             const image = get("weixinQrImage");
             if (!(image instanceof HTMLImageElement)) {
                 throw new Error(t("weixin.qr_load_failed"));
@@ -495,10 +525,10 @@
             weixinState.qrObjectUrl = URL.createObjectURL(blob);
             image.src = weixinState.qrObjectUrl;
             await image.decode();
-            if (sessionId !== weixinState.sessionId) return;
+            if (!isCurrent()) return;
             setQrFrameState("ready");
         } catch (error) {
-            if (sessionId !== weixinState.sessionId) return;
+            if (!isCurrent()) return;
             clearQrImage();
             setQrFrameState("error");
             throw error;
@@ -523,13 +553,18 @@
 
     async function pollLogin() {
         if (!weixinState.sessionId || weixinState.polling) return;
-        weixinState.polling = true;
+        const generation = weixinState.dialogGeneration;
         const sessionId = weixinState.sessionId;
+        const request = { generation, sessionId };
+        weixinState.polling = request;
+        const isCurrent = () =>
+            isCurrentDialog(generation, sessionId) &&
+            weixinState.polling === request;
         try {
             const payload = await requestJson(
                 `${ENDPOINT}/login/${encodeURIComponent(sessionId)}`,
             );
-            if (sessionId !== weixinState.sessionId) return;
+            if (!isCurrent()) return;
             const status = String(payload.status || "wait");
             const message = String(payload.message || "");
             if (status === "confirmed") {
@@ -537,7 +572,11 @@
                 stopPolling();
                 weixinState.loaded = false;
                 await loadAll(true);
-                window.setTimeout(() => closeDialog(false), 500);
+                if (!isCurrentDialog(generation, sessionId)) return;
+                window.setTimeout(() => {
+                    if (isCurrentDialog(generation, sessionId))
+                        closeDialog(false);
+                }, 500);
                 return;
             }
             if (status === "need_verifycode") {
@@ -555,7 +594,7 @@
             }
             if (schedulePollForStatus(status)) schedulePoll();
         } catch (error) {
-            if (sessionId !== weixinState.sessionId) return;
+            if (!isCurrent()) return;
             setQrView(
                 "weixin.poll_failed",
                 error instanceof Error ? error.message : String(error),
@@ -564,7 +603,7 @@
                 schedulePoll(3000);
             }
         } finally {
-            weixinState.polling = false;
+            if (weixinState.polling === request) weixinState.polling = false;
         }
     }
 
@@ -600,6 +639,9 @@
     }
 
     function openBindingDialog(mode, account = null) {
+        closeDialog(true);
+        weixinState.dialogGeneration += 1;
+        const generation = weixinState.dialogGeneration;
         weixinState.dialogMode = mode;
         weixinState.dialogAlias = account ? String(account.alias || "") : "";
         weixinState.confirmationToken = "";
@@ -625,6 +667,7 @@
         updateDialogLabels();
         showDialog();
         window.requestAnimationFrame(() => {
+            if (!isCurrentDialog(generation)) return;
             const focusTarget = mode === "rebind" ? qqInput : aliasInput;
             if (focusTarget) focusTarget.focus();
         });
@@ -632,19 +675,11 @@
 
     async function closeDialog(cancelLogin = true) {
         const sessionId = weixinState.sessionId;
+        weixinState.dialogGeneration += 1;
         weixinState.sessionId = "";
         stopPolling();
         clearQrImage();
-        if (cancelLogin && sessionId) {
-            try {
-                await requestJson(
-                    `${ENDPOINT}/login/${encodeURIComponent(sessionId)}`,
-                    { method: "DELETE" },
-                );
-            } catch (_error) {
-                // The session may already be confirmed or expired.
-            }
-        }
+        setBusy(false);
         const backdrop = get("weixinDialogBackdrop");
         const dialog = get("weixinDialog");
         if (dialog) releaseFocus(dialog);
@@ -658,6 +693,7 @@
         if (previousFocus && typeof previousFocus.focus === "function") {
             previousFocus.focus();
         }
+        if (cancelLogin) await cancelLoginSession(sessionId);
     }
 
     function showConfirmation(payload) {
@@ -673,6 +709,7 @@
     async function submitBinding(event) {
         event.preventDefault();
         if (weixinState.busy) return;
+        const generation = weixinState.dialogGeneration;
         const alias = String(get("weixinAliasInput")?.value || "").trim();
         const qqId = Number.parseInt(
             String(get("weixinQqInput")?.value || ""),
@@ -694,10 +731,12 @@
                     `${ENDPOINT}/accounts/${encodeURIComponent(alias)}`,
                     { method: "PATCH", body: JSON.stringify(payload) },
                 );
+                if (!isCurrentDialog(generation)) return;
                 setDialogStatus(t("weixin.rebind_saved"), "success");
                 weixinState.loaded = false;
                 setBusy(false);
                 await loadAll(true);
+                if (!isCurrentDialog(generation)) return;
                 await closeDialog(false);
                 return;
             }
@@ -705,6 +744,10 @@
                 method: "POST",
                 body: JSON.stringify(payload),
             });
+            if (!isCurrentDialog(generation)) {
+                await cancelLoginSession(String(result.session_id || ""));
+                return;
+            }
             weixinState.sessionId = String(result.session_id || "");
             weixinState.qrRevision += 1;
             const form = get("weixinBindingForm");
@@ -713,8 +756,10 @@
             if (qrStep) qrStep.hidden = false;
             setQrView("weixin.wait_scan", "");
             await loadQrImage();
+            if (!isCurrentDialog(generation)) return;
             schedulePoll(200);
         } catch (error) {
+            if (!isCurrentDialog(generation)) return;
             if (
                 error instanceof WeixinRequestError &&
                 error.status === 409 &&
@@ -735,55 +780,65 @@
                 );
             }
         } finally {
-            setBusy(false);
+            if (isCurrentDialog(generation)) setBusy(false);
         }
     }
 
     async function refreshQr() {
         if (!weixinState.sessionId || weixinState.busy) return;
+        const generation = weixinState.dialogGeneration;
+        const sessionId = weixinState.sessionId;
         setBusy(true);
         try {
             await requestJson(
-                `${ENDPOINT}/login/${encodeURIComponent(weixinState.sessionId)}/refresh`,
+                `${ENDPOINT}/login/${encodeURIComponent(sessionId)}/refresh`,
                 { method: "POST", body: "{}" },
             );
+            if (!isCurrentDialog(generation, sessionId)) return;
+            stopPolling();
             weixinState.qrRevision += 1;
             await loadQrImage();
+            if (!isCurrentDialog(generation, sessionId)) return;
             setQrView("weixin.wait_scan", "");
             schedulePoll(200);
         } catch (error) {
+            if (!isCurrentDialog(generation, sessionId)) return;
             setQrView(
                 "weixin.refresh_failed",
                 error instanceof Error ? error.message : String(error),
             );
         } finally {
-            setBusy(false);
+            if (isCurrentDialog(generation, sessionId)) setBusy(false);
         }
     }
 
     async function submitVerifyCode(event) {
         event.preventDefault();
         if (!weixinState.sessionId || weixinState.busy) return;
+        const generation = weixinState.dialogGeneration;
+        const sessionId = weixinState.sessionId;
         const input = get("weixinVerifyInput");
         const code = String(input?.value || "").trim();
         if (!code) return;
         setBusy(true);
         try {
             await requestJson(
-                `${ENDPOINT}/login/${encodeURIComponent(weixinState.sessionId)}/verify`,
+                `${ENDPOINT}/login/${encodeURIComponent(sessionId)}/verify`,
                 { method: "POST", body: JSON.stringify({ code }) },
             );
+            if (!isCurrentDialog(generation, sessionId)) return;
             if (input) input.value = "";
             setQrView("weixin.verify_submitted", "");
             schedulePoll(200);
         } catch (error) {
+            if (!isCurrentDialog(generation, sessionId)) return;
             setQrView(
                 "weixin.verify_failed",
                 error instanceof Error ? error.message : String(error),
                 true,
             );
         } finally {
-            setBusy(false);
+            if (isCurrentDialog(generation, sessionId)) setBusy(false);
         }
     }
 
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index ca9eed91..f98b34c6 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3570,6 +3570,217 @@ for (const target of ["switch", "edit"]) {
     }
 }
 
+function weixinDialogFixture(env) {
+    const { window, response } = env;
+    const endpoint = "/api/v1/management/runtime/weixin";
+    const sessions = new Map();
+    const held = new Set();
+    const pending = [];
+    const calls = [];
+    const revoked = [];
+    const blobSessions = new WeakMap();
+    let blobId = 0;
+    window.URL.createObjectURL = (blob) => `blob:fixture-qr-${blobSessions.get(blob)}-${++blobId}`;
+    window.URL.revokeObjectURL = (url) => revoked.push(url);
+    window.HTMLImageElement.prototype.decode = async () => {};
+    const defaults = (request, payload) => {
+        if (request.kind === "login") {
+            const sessionId = payload?.session_id;
+            if (!sessionId) throw new Error("login fixture needs a session_id");
+            sessions.set(sessionId, request.body);
+        }
+        if (request.kind === "cancel") sessions.delete(request.sessionId);
+        if (request.kind === "poll" && payload?.status === "confirmed") sessions.delete(request.sessionId);
+        if (request.kind === "qr") return {
+            ...response(200, {}), blob: async () => {
+                const blob = new window.Blob([`qr-${request.sessionId}`], { type: "image/png" });
+                blobSessions.set(blob, request.sessionId);
+                return blob;
+            },
+        };
+        if (request.kind === "status") return response(200, {
+            enabled: true, running: true,
+            accounts: [{ alias: "B", qq_id: 2, enabled: true, connected: true }],
+        });
+        if (request.kind === "pending" || request.kind === "audit") return response(200, { items: [] });
+        return response(200, payload || (request.kind === "poll" ? { status: "wait" } : {}));
+    };
+    window.fetch = (url, options = {}) => {
+        const route = new window.URL(String(url), window.location.href).pathname;
+        const method = options.method || "GET";
+        const login = route.match(/\/login\/([^/]+)(?:\/(qr\.png|refresh|verify))?$/);
+        let kind;
+        if (route === endpoint) kind = "status";
+        else if (route === `${endpoint}/pending`) kind = "pending";
+        else if (route === `${endpoint}/audit`) kind = "audit";
+        else if (route === `${endpoint}/login` && method === "POST") kind = "login";
+        else if (login) kind = method === "DELETE" ? "cancel" : login[2] === "qr.png" ? "qr" : login[2] || "poll";
+        else if (route.includes("/accounts/") && method === "PATCH") kind = "rebind";
+        else throw new Error(`unexpected Weixin request: ${method} ${route}`);
+        const request = { kind, url: String(url), method, sessionId: login?.[1] || "", body: options.body ? JSON.parse(options.body) : null };
+        calls.push(request);
+        if (kind === "login" || held.delete(kind)) return new Promise((resolve, reject) => {
+            pending.push({ ...request, resolve, reject, done: false });
+        });
+        return Promise.resolve(defaults(request));
+    };
+    const element = (id) => window.document.getElementById(id);
+    window.WeixinController.init();
+    return {
+        calls, sessions, revoked,
+        hold(kind) { held.add(kind); },
+        finish(kind, payload, sessionId = "") {
+            const request = pending.find((item) => !item.done && item.kind === kind && (!sessionId || item.sessionId === sessionId));
+            if (!request) throw new Error(`no pending ${kind} ${sessionId}`);
+            request.done = true;
+            request.resolve(defaults(request, payload));
+        },
+        fail(kind, sessionId = "", confirmation = false) {
+            const request = pending.find((item) => !item.done && item.kind === kind && (!sessionId || item.sessionId === sessionId));
+            if (!request) throw new Error(`no pending ${kind} ${sessionId}`);
+            request.done = true;
+            if (confirmation) request.resolve(response(409, { requires_confirmation: true, confirmation_token: "obsolete-token", error: "obsolete confirmation" }));
+            else request.reject(new Error(`obsolete ${kind} failure`));
+        },
+        open(alias = "A", qqId = "1") {
+            element("btnWeixinBind").click();
+            element("weixinAliasInput").value = alias;
+            element("weixinQqInput").value = qqId;
+        },
+        rebind() { window.document.querySelector('[data-weixin-action="rebind"][data-alias="B"]').click(); },
+        submit() { element("btnWeixinBindingSubmit").click(); },
+        close() { element("btnWeixinDialogClose").click(); },
+        refresh() { element("btnWeixinQrRefresh").click(); },
+        verify() {
+            element("weixinVerifyInput").value = "123456";
+            element("weixinVerifyForm").querySelector('button[type="submit"]').click();
+        },
+        snapshot() {
+            return {
+                hidden: element("weixinDialogBackdrop").hidden,
+                alias: element("weixinAliasInput").value,
+                bindingHidden: element("weixinBindingForm").hidden,
+                qrHidden: element("weixinQrStep").hidden,
+                qrSrc: element("weixinQrImage").getAttribute("src"),
+                qrFrame: element("weixinQrFrame").dataset.state,
+                qrState: textOf(window, "weixinQrState"),
+                qrMessage: textOf(window, "weixinQrMessage"),
+                dialogStatus: textOf(window, "weixinDialogStatus"),
+                confirmationHidden: element("weixinConfirmationPanel").hidden,
+                submitDisabled: element("btnWeixinBindingSubmit").disabled,
+                verifyHidden: element("weixinVerifyForm").hidden,
+                overflow: window.document.body.style.overflow,
+            };
+        },
+    };
+}
+
+async function staleWeixinDialogRequest(env, kind, outcome) {
+    const { window } = env;
+    const fixture = weixinDialogFixture(env);
+    await window.WeixinController.loadAll(true);
+    if (kind === "rebind") fixture.rebind();
+    else fixture.open();
+    if (kind !== "login") fixture.hold(kind);
+    if (kind === "rebind") fixture.submit();
+    else {
+        fixture.submit();
+        await tick();
+        if (kind !== "login") {
+            fixture.finish("login", { session_id: "old-A" });
+            await tick();
+            if (kind === "poll") await settle(250);
+            if (kind === "refresh") fixture.refresh();
+            if (kind === "verify") {
+                fixture.hold("poll");
+                await settle(250);
+                fixture.finish("poll", { status: "need_verifycode" }, "old-A");
+                await tick();
+                fixture.verify();
+            }
+        }
+    }
+    await tick();
+    fixture.close();
+    await tick();
+    const closed = fixture.snapshot();
+    fixture.open("C", "3");
+    fixture.submit();
+    await tick();
+    if (kind === "qr" || kind === "poll") {
+        fixture.hold("poll");
+        fixture.finish("login", { session_id: "new-C" });
+        await tick();
+        if (kind === "poll") await settle(250);
+    }
+    const beforeLate = fixture.snapshot();
+    if (outcome === "failure" || outcome === "confirmation") fixture.fail(kind, kind === "login" || kind === "rebind" ? "" : "old-A", outcome === "confirmation");
+    else fixture.finish(kind, kind === "login" ? { session_id: "old-A" } : kind === "poll" ? { status: outcome === "confirmed" ? "confirmed" : "wait", message: "obsolete poll" } : {}, kind === "login" || kind === "rebind" ? "" : "old-A");
+    await tick();
+    const afterLate = fixture.snapshot();
+    if (kind === "poll") {
+        fixture.finish("poll", { status: "need_verifycode", message: "current C verification" }, "new-C");
+        await tick();
+    } else if (kind !== "qr") {
+        fixture.finish("login", { session_id: "new-C" });
+        await tick();
+    }
+    return { closed, beforeLate, afterLate, current: fixture.snapshot(),
+        sessions: Array.from(fixture.sessions.entries()), revoked: fixture.revoked,
+        calls: fixture.calls.map(({ kind: requestKind, sessionId, body }) => ({ kind: requestKind, sessionId, body })) };
+}
+
+for (const kind of ["login", "qr", "poll", "refresh", "verify", "rebind"]) {
+    for (const outcome of kind === "login" ? ["success", "failure", "confirmation"] : kind === "poll" ? ["success", "failure", "confirmed"] : ["success", "failure"]) {
+        SCENARIOS[`weixin_dialog_late_${kind}_${outcome}`] = (env) => staleWeixinDialogRequest(env, kind, outcome);
+    }
+}
+
+SCENARIOS.weixin_dialog_slow_cancel = async (env) => {
+    const fixture = weixinDialogFixture(env);
+    await env.window.WeixinController.loadAll(true);
+    fixture.open(); fixture.submit(); await tick();
+    fixture.finish("login", { session_id: "old-A" }); await tick();
+    fixture.hold("cancel"); fixture.close(); await tick();
+    const closed = fixture.snapshot();
+    fixture.open("C", "3"); fixture.submit(); await tick();
+    fixture.finish("login", { session_id: "new-C" }); await tick();
+    const beforeLate = fixture.snapshot();
+    fixture.finish("cancel", {}, "old-A"); await tick();
+    return { closed, beforeLate, afterLate: fixture.snapshot(), sessions: Array.from(fixture.sessions.keys()) };
+};
+
+SCENARIOS.weixin_dialog_replace_cancels_existing = async (env) => {
+    const fixture = weixinDialogFixture(env);
+    await env.window.WeixinController.loadAll(true);
+    fixture.open(); fixture.submit(); await tick();
+    fixture.finish("login", { session_id: "old-A" }); await tick();
+    fixture.rebind(); await tick();
+    return { current: fixture.snapshot(), sessions: Array.from(fixture.sessions.keys()), revoked: fixture.revoked,
+        cancelIds: fixture.calls.filter((item) => item.kind === "cancel").map((item) => item.sessionId) };
+};
+
+for (const boundary of ["load", "timer", "normal"]) {
+    SCENARIOS[`weixin_dialog_confirmed_${boundary}`] = async (env) => {
+        const fixture = weixinDialogFixture(env);
+        await env.window.WeixinController.loadAll(true);
+        env.window.document.getElementById("btnWeixinBind").focus();
+        fixture.open(); fixture.hold("poll"); fixture.submit(); await tick();
+        fixture.finish("login", { session_id: "old-A" }); await tick(); await settle(250);
+        if (boundary === "load") fixture.hold("status");
+        fixture.finish("poll", { status: "confirmed" }, "old-A"); await tick();
+        if (boundary !== "normal") {
+            fixture.close(); await tick(); fixture.open("C", "3"); fixture.submit(); await tick();
+        }
+        const beforeLate = fixture.snapshot();
+        if (boundary === "load") { fixture.finish("status"); await tick(); }
+        await settle(550);
+        const afterLate = fixture.snapshot();
+        if (boundary !== "normal") { fixture.finish("login", { session_id: "new-C" }); await tick(); }
+        return { beforeLate, afterLate, current: fixture.snapshot(), focus: env.window.document.activeElement?.id || "" };
+    };
+}
+
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.scenario) throw new Error("缺少 --scenario");
@@ -3585,6 +3796,8 @@ async function main() {
             ? ["config-form.js"]
             : args.scenario.startsWith("workflow_editor_")
               ? ["workflow-graph.js", "workflow-canvas.js", "workflow-inspector.js", "schedules.js"]
+              : args.scenario.startsWith("weixin_dialog_")
+                ? ["weixin.js"]
             : [],
     });
     const result = await scenario(env);
diff --git a/tests/test_webui_weixin_behavior.py b/tests/test_webui_weixin_behavior.py
new file mode 100644
index 00000000..5c3643b3
--- /dev/null
+++ b/tests/test_webui_weixin_behavior.py
@@ -0,0 +1,82 @@
+"""微信登录弹窗真实交互与旧请求归属的行为回归。"""
+
+from __future__ import annotations
+
+import pytest
+
+from test_webui_runtime_chat_behavior import run_scenario
+
+
+@pytest.mark.parametrize(
+    ("kind", "outcome"),
+    [
+        (kind, outcome)
+        for kind in ("login", "qr", "poll", "refresh", "verify", "rebind")
+        for outcome in (
+            ("success", "failure", "confirmation")
+            if kind == "login"
+            else ("success", "failure", "confirmed")
+            if kind == "poll"
+            else ("success", "failure")
+        )
+    ],
+)
+def test_old_login_work_cannot_replace_new_dialog(kind: str, outcome: str) -> None:
+    result = run_scenario(f"weixin_dialog_late_{kind}_{outcome}")
+    assert result["closed"]["hidden"] is True
+    assert result["closed"]["overflow"] == ""
+    assert result["beforeLate"]["alias"] == "C"
+    assert result["afterLate"] == result["beforeLate"]
+    assert result["current"]["hidden"] is False
+    assert result["current"]["alias"] == "C"
+    assert result["current"]["qrHidden"] is False
+    assert result["current"]["qrFrame"] == "ready"
+    assert result["current"]["qrSrc"].startswith("blob:fixture-qr-new-C-")
+    assert result["sessions"] == [["new-C", {"alias": "C", "qq_id": 3}]]
+    if kind == "poll":
+        assert result["current"]["verifyHidden"] is False
+        assert result["current"]["qrMessage"] == "current C verification"
+    if kind == "login" and outcome == "success":
+        assert [
+            item["sessionId"] for item in result["calls"] if item["kind"] == "cancel"
+        ] == ["old-A"]
+        assert not any(
+            item["sessionId"] == "old-A" and item["kind"] in ("qr", "poll")
+            for item in result["calls"]
+        )
+
+
+def test_cancel_hides_immediately_and_late_delete_does_not_close_new_dialog() -> None:
+    result = run_scenario("weixin_dialog_slow_cancel")
+    assert result["closed"]["hidden"] is True
+    assert result["closed"]["submitDisabled"] is False
+    assert result["afterLate"] == result["beforeLate"]
+    assert result["afterLate"]["hidden"] is False
+    assert result["sessions"] == ["new-C"]
+
+
+def test_replacing_dialog_cancels_existing_session_and_releases_qr() -> None:
+    result = run_scenario("weixin_dialog_replace_cancels_existing")
+    assert result["sessions"] == []
+    assert result["cancelIds"] == ["old-A"]
+    assert result["current"]["alias"] == "B"
+    assert result["current"]["qrHidden"] is True
+    assert result["current"]["qrSrc"] is None
+    assert len(result["revoked"]) == 1
+
+
+@pytest.mark.parametrize("boundary", ["load", "timer"])
+def test_old_confirmation_cannot_close_or_unlock_new_dialog(boundary: str) -> None:
+    result = run_scenario(f"weixin_dialog_confirmed_{boundary}")
+    assert result["afterLate"] == result["beforeLate"]
+    assert result["afterLate"]["submitDisabled"] is True
+    assert result["current"]["alias"] == "C"
+    assert result["current"]["qrFrame"] == "ready"
+
+
+def test_current_confirmation_still_closes_dialog_and_restores_focus() -> None:
+    result = run_scenario("weixin_dialog_confirmed_normal")
+    assert result["beforeLate"]["hidden"] is False
+    assert result["afterLate"]["hidden"] is True
+    assert result["afterLate"]["overflow"] == ""
+    assert result["focus"] == "btnWeixinBind"

From e5aa5ea205b28e5925c3797854558c7cea50f855 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Tue, 6 Oct 2026 20:20:49 +0800
Subject: [PATCH 065/121] fix(chat): split production chunks and preserve full
 highlighting

---
 AGENTS.md                                     |  2 +-
 apps/undefined-chat/README.md                 |  4 +-
 apps/undefined-chat/biome.json                |  1 +
 apps/undefined-chat/package.json              |  5 +-
 .../tests/build-chunks.node.mjs               | 82 +++++++++++++++++++
 apps/undefined-chat/vite.config.ts            | 28 +++++++
 docs/build.md                                 |  2 +-
 docs/undefined-chat.md                        |  3 +
 8 files changed, 122 insertions(+), 5 deletions(-)
 create mode 100644 apps/undefined-chat/tests/build-chunks.node.mjs

diff --git a/AGENTS.md b/AGENTS.md
index 5cc69a56..8f17c27b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,7 +21,7 @@ Use `uv` for the root project:
 
 For the console app, run `cd apps/undefined-console && npm ci && npm run check`. Use `npm run dev` for the Vite shell and `npm run tauri:dev` for the desktop shell.
 
-For the native chat client, run `cd apps/undefined-chat && npm ci && npm run check` (Biome + TypeScript + Vitest unit/e2e + `cargo fmt --check`/`cargo check`/`cargo test`). Use `npm run tauri:dev` for the desktop shell.
+For the native chat client, run `cd apps/undefined-chat && npm ci && npm run check` (Biome + TypeScript + Vitest unit/e2e + Node production-build regression + `cargo fmt --check`/`cargo check`/`cargo test`). Use `npm run tauri:dev` for the desktop shell.
 
 ## Coding Style & Naming Conventions
 Use 4-space indentation. Python code must be fully type-annotated and pass strict mypy checks. Disk I/O should go through `src/Undefined/utils/io.py` so writes stay async-safe and atomic. Follow `snake_case` for modules and functions, `PascalCase` for classes, and prefer extending existing services/helpers over introducing one-off abstractions. Skills handlers must not import repo-local modules outside `skills/` (only `Undefined.skills.*` and same-directory relative imports are allowed); pass dependencies through the execution context, share helpers via `src/Undefined/skills/shared.py`, and keep `tests/test_skills_import_boundary.py`'s ratchet baseline shrinking. WebUI JavaScript in `src/Undefined/webui/static/js/` and both native apps use Biome 2.5.10; keep the two package pins, lockfiles, and three configuration schemas in sync. Nested app configurations set `root: false` for checks launched from the repository root and use `extends: []` (explicit no-inherit) plus their own `formatter.indentStyle = "tab"`, so the root WebUI rules never leak into app checks. App changes must satisfy Biome, TypeScript, and Cargo checks.
diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index 16813556..a639307b 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -45,7 +45,9 @@ npm run check
 npm run tauri:dev
 ```
 
-`npm run check` 当前包含 Biome、TypeScript、unit/jsdom integration tests、cargo fmt、cargo check 和 cargo test。
+`npm run check` 当前包含 Biome、TypeScript、unit/jsdom integration tests、独立 Node production build 回归、cargo fmt、cargo check 和 cargo test。
+
+`npm run build` 将应用、React、其余依赖与代码高亮模块分别打包。highlight.js 的全部语言定义按文件名区间拆成四组，仍同步注册并保留自动检测；分包控制单个 chunk 的体积并细化缓存粒度，全部语言支持保持一致。总下载体积基本不变，独立 gzip 压缩会因减少字典复用而增加压缩体积。`npm run test:build` 在临时目录构建，检查默认 500 kB 限制、chunk 导入图，并执行生产高亮模块，核对完整语言列表、各语言高亮和自动检测结果。
 
 Biome 固定为 **2.5.10**，与 Console 和根目录 WebUI 配置保持一致；使用 `npm ci` 安装锁定版本。App 的 `biome.json` 使用独立嵌套配置（`root: false`），不继承 WebUI 格式规则，并显式启用 React 的 `noArrayIndexKey` 检查，避免依赖自动检测造成漏检；升级约定见 [构建文档](../../docs/build.md#6-git-hook-集成)。
 
diff --git a/apps/undefined-chat/biome.json b/apps/undefined-chat/biome.json
index 6fa9115c..27a2485c 100644
--- a/apps/undefined-chat/biome.json
+++ b/apps/undefined-chat/biome.json
@@ -9,6 +9,7 @@
         "includes": [
             "**/src/**/*.ts",
             "**/src/**/*.tsx",
+            "**/tests/**/*.mjs",
             "**/package.json",
             "**/tsconfig.json",
             "**/vite.config.ts",
diff --git a/apps/undefined-chat/package.json b/apps/undefined-chat/package.json
index b5c63158..68b36d54 100644
--- a/apps/undefined-chat/package.json
+++ b/apps/undefined-chat/package.json
@@ -6,12 +6,13 @@
 	"scripts": {
 		"tauri": "tauri",
 		"dev": "vite --host 0.0.0.0 --port 1430",
-		"lint": "biome check src package.json tsconfig.json vite.config.ts src-tauri/tauri.conf.json src-tauri/capabilities/default.json",
+		"lint": "biome check src tests/build-chunks.node.mjs package.json tsconfig.json vite.config.ts src-tauri/tauri.conf.json src-tauri/capabilities/default.json",
 		"typecheck": "tsc --noEmit",
 		"test": "vitest run",
 		"test:unit": "vitest run",
 		"test:e2e": "vitest run --config vitest.e2e.config.ts",
-		"test:all": "npm run test:unit && npm run test:e2e",
+		"test:build": "node --test tests/build-chunks.node.mjs",
+		"test:all": "npm run test:unit && npm run test:e2e && npm run test:build",
 		"test:watch": "vitest watch",
 		"test:e2e:watch": "vitest watch --config vitest.e2e.config.ts",
 		"tauri:fmt:check": "cargo fmt --manifest-path src-tauri/Cargo.toml --all --check",
diff --git a/apps/undefined-chat/tests/build-chunks.node.mjs b/apps/undefined-chat/tests/build-chunks.node.mjs
new file mode 100644
index 00000000..535da54f
--- /dev/null
+++ b/apps/undefined-chat/tests/build-chunks.node.mjs
@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import hljs from "highlight.js";
+import { build, createLogger } from "vite";
+
+test("production chunks preserve full highlighting without oversized or circular chunks", async () => {
+	const directory = await mkdtemp(join(tmpdir(), "undefined-chat-build-"));
+	try {
+		const warnings = [];
+		const logger = createLogger("silent");
+		logger.warn = (message) => warnings.push(message);
+		const result = await build({
+			root: fileURLToPath(new URL("..", import.meta.url)),
+			customLogger: logger,
+			build: { outDir: directory, emptyOutDir: true },
+		});
+		assert.ok(!("close" in result), "Expected a one-shot production build");
+		const outputs = Array.isArray(result) ? result : [result];
+		const chunks = outputs.flatMap((output) =>
+			output.output.filter((item) => item.type === "chunk"),
+		);
+		assert.ok(chunks.length > 1);
+		assert.deepEqual(warnings, []);
+		const byFile = new Map(chunks.map((chunk) => [chunk.fileName, chunk]));
+		for (const chunk of chunks) {
+			assert.ok(Buffer.byteLength(chunk.code) <= 500_000, chunk.fileName);
+		}
+
+		function checkImports(file, ancestors) {
+			assert.ok(
+				!ancestors.includes(file),
+				`Circular chunk import through ${file}`,
+			);
+			const chunk = byFile.get(file);
+			assert.ok(chunk, `Missing emitted chunk ${file}`);
+			for (const dependency of [...chunk.imports, ...chunk.dynamicImports]) {
+				checkImports(dependency, [...ancestors, file]);
+			}
+		}
+		for (const chunk of chunks) checkImports(chunk.fileName, []);
+
+		// Execute the emitted CJS wrappers and language chunks, not source imports.
+		await writeFile(join(directory, "package.json"), '{"type":"module"}');
+		const highlighterChunk = chunks.find((chunk) =>
+			Object.keys(chunk.modules).some((id) =>
+				id.endsWith("/highlight.js/lib/index.js"),
+			),
+		);
+		assert.ok(highlighterChunk);
+		const exports = await import(
+			pathToFileURL(join(directory, highlighterChunk.fileName)).href
+		);
+		const bundled = Object.values(exports).find(
+			(value) => typeof value?.listLanguages === "function",
+		);
+		assert.ok(bundled, "Missing initialized production highlighter");
+		assert.deepEqual(bundled.listLanguages(), hljs.listLanguages());
+		for (const language of hljs.listLanguages()) {
+			const code = 'if (value) { return "hello"; } // test';
+			assert.equal(
+				bundled.highlight(code, { language, ignoreIllegals: true }).value,
+				hljs.highlight(code, { language, ignoreIllegals: true }).value,
+				language,
+			);
+		}
+		const code = 'def greet(name):\n    return "hello " + name';
+		assert.equal(
+			bundled.highlightAuto(code).language,
+			hljs.highlightAuto(code).language,
+		);
+		assert.equal(
+			bundled.highlightAuto(code).value,
+			hljs.highlightAuto(code).value,
+		);
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+	}
+});
diff --git a/apps/undefined-chat/vite.config.ts b/apps/undefined-chat/vite.config.ts
index b24829ad..d7d80a60 100644
--- a/apps/undefined-chat/vite.config.ts
+++ b/apps/undefined-chat/vite.config.ts
@@ -1,6 +1,28 @@
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vitest/config";
 
+function manualChunks(id: string): string | undefined {
+	// Keep CJS helpers independent so vendor chunks never need to import the app.
+	if (id.includes("commonjsHelpers.js")) return "vendor-helpers";
+	const language = id.match(/\/highlight\.js\/lib\/languages\/([^/.]+)\.js/);
+	if (language) {
+		// Keep every language synchronously registered, in bounded stable groups.
+		const initial = language[1][0];
+		const group =
+			initial < "g"
+				? "a-f"
+				: initial < "m"
+					? "g-l"
+					: initial < "s"
+						? "m-r"
+						: "s-z";
+		return `highlight-languages-${group}`;
+	}
+	if (id.includes("/node_modules/highlight.js/")) return "highlight";
+	if (/\/node_modules\/(react|react-dom|scheduler)\//.test(id)) return "react";
+	if (id.includes("/node_modules/")) return "vendor";
+}
+
 export default defineConfig({
 	plugins: [react()],
 	server: {
@@ -13,6 +35,12 @@ export default defineConfig({
 	},
 	build: {
 		target: ["es2022", "chrome110", "safari16"],
+		rollupOptions: {
+			output: {
+				manualChunks,
+				onlyExplicitManualChunks: true,
+			},
+		},
 	},
 	test: {
 		environment: "jsdom",
diff --git a/docs/build.md b/docs/build.md
index 4c019d87..937a1f92 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -443,7 +443,7 @@ npm run check  # 代码检查与测试（lint/typecheck/test/cargo fmt/check/tes
 
 cd ../undefined-chat
 npm install
-npm run check  # Biome、TypeScript、unit + e2e（jsdom）测试、cargo fmt/check/test
+npm run check  # Biome、TypeScript、unit + e2e（jsdom）、Node 生产构建回归、cargo fmt/check/test
 ```
 
 如果本次改动涉及 Android 构建链：
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 2e45e349..64708e1e 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -133,10 +133,13 @@ HTML 采用与 WebUI 基线对齐的双层策略：
 - `npm run typecheck`
 - `npm run test:unit`
 - `npm run test:e2e`（Vitest + jsdom integration tests）
+- `npm run test:build`（独立 Node 测试：临时生产构建、chunk 体积与导入图、全语言高亮一致性）
 - `npm run tauri:fmt:check`
 - `npm run tauri:check`
 - `npm run tauri:test`
 
+生产构建将应用、React、其他依赖与高亮模块分开；全部高亮语言仍同步注册并保持自动检测。分包控制单个 chunk 的大小并细化缓存粒度，总下载体积基本不变；独立 gzip 压缩会因减少字典复用而增加压缩体积。构建回归执行实际输出的高亮模块，核对语言顺序、逐语言结果与自动检测，并检查默认体积门槛和导入图无环。
+
 jsdom integration tests 不等同于真实 Tauri/Android E2E。发布前仍应执行 Android smoke checklist 和必要的桌面 Tauri smoke。
 
 版本必须与 `pyproject.toml` 主版本一致。`scripts/bump_version.py <version>` 会同步更新 Chat/Console 的 package、Tauri 配置和 lock 文件。Android release job 会先运行 `npm run tauri:android:init`，为 Undefined Chat 注入 `HtmlPreviewActivity` / `SecretPlugin` 并用 `tauri:android:prepare:check` 校验生成工程。

From c270e7aea583164ce3b11008a78d9aa78b26e899 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:24:39 +0800
Subject: [PATCH 066/121] fix(deploy): format IPv6 service URLs correctly

---
 docs/docker-deploy.md            |  4 +++-
 src/Undefined/deploy/generate.py | 18 +++++++-------
 tests/test_deploy_generate.py    | 40 ++++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 10 deletions(-)

diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md
index ff1b38c4..e88e6b1c 100644
--- a/docs/docker-deploy.md
+++ b/docs/docker-deploy.md
@@ -278,13 +278,15 @@ uv run Undefined-webui
 | `--with searxng,firecrawl,lxmusic2api` | 设置完整的可选服务列表，按需删减；也可使用 `--with-searxng` 等独立参数 |
 | `--with-nagaagent` / `--no-nagaagent` | 开启或关闭 NagaAgent 代码问答，首次默认关闭 |
 | `--port KEY=PORT` | 修改宿主机发布端口，可重复使用；端口键见 `uv run deploy up --help` |
-| `--port-bind ADDR` | 设置所有发布端口的绑定地址，首次默认 `127.0.0.1` |
+| `--port-bind ADDR` | 设置所有发布端口的绑定地址，首次默认 `127.0.0.1`；支持 IPv4、裸 IPv6（如 `::1`）和带方括号的 IPv6（如 `[::1]`） |
 | `--pull missing\|always\|never` | 镜像拉取策略，默认 `missing`；分别表示本地缺少时拉取、总是检查更新、不拉取 |
 | `--dry-run` | 预览配置差异与 Compose，隐藏凭据，不写文件、不启动容器 |
 | `--yes` / `-y` | 跳过向导，未指定项沿用上次选择或首次默认值 |
 
 ### 配置修改与运行权限
 
+`host` 模式生成的服务连接 URL 会为 IPv6 地址补上方括号；`0.0.0.0`、`::` 与 `[::]` 仅用于监听，生成连接目标时改用回环地址。
+
 部署工具会更新 OneBot 连接、WebUI / Runtime 监听地址与凭据、Bot 启动方式、文件发送模式和所选服务地址；模型、访问控制、提示词和历史配置的取值会保留。已有配置在写入前会备份，但写回时可能调整排序、空行或部分注释，可先用 `--dry-run` 查看计划。
 
 每次执行 `uv run deploy up`，`container` 与 `host` 模式都会写入 `webui.autostart_bot = false` 和 `onebot.file_send_mode = "stream"`。Bot 由你在 WebUI 中手动启动；本地文件通过已有 OneBot WebSocket 分块上传给 NapCat，无需共享发送目录，也不依赖 Runtime 提供下载地址。`file_send_host` 仅供 URL 模式使用，部署工具不再改写它。
diff --git a/src/Undefined/deploy/generate.py b/src/Undefined/deploy/generate.py
index 058e62a9..bb09d808 100644
--- a/src/Undefined/deploy/generate.py
+++ b/src/Undefined/deploy/generate.py
@@ -19,6 +19,7 @@
 from Undefined.deploy import catalog, images, nagaagent
 from Undefined.deploy.config_patch import PatchPlan
 from Undefined.deploy.state import DeployLayout
+from Undefined.config.models import format_netloc
 
 #: 本体在 compose 里的服务名（与 compose.bot.yaml 一致）。
 BOT_SERVICE_NAME: Final[str] = "undefined-bot"
@@ -183,7 +184,8 @@ def _connect_host(bind: str) -> str:
     ``0.0.0.0`` / ``::`` 是监听语义（所有网卡），拿去当连接目标在部分平台上并
     不可用；本体与依赖服务都在本机时应当连回环。
     """
-    return "127.0.0.1" if bind in ("0.0.0.0", "::") else bind
+    host = bind.removeprefix("[").removesuffix("]")
+    return "127.0.0.1" if host in ("0.0.0.0", "::") else host
 
 
 def compose_service_urls(ctx: GenerateContext) -> dict[str, str]:
@@ -208,9 +210,8 @@ def compose_service_urls(ctx: GenerateContext) -> dict[str, str]:
     if mode == catalog.MODE_HOST:
         host = _connect_host(ctx.port_bind)
         return {
-            "searxng": f"http://{host}:{ctx.port('searxng')}",
-            "firecrawl": f"http://{host}:{ctx.port('firecrawl')}",
-            "lxmusic2api": f"http://{host}:{ctx.port('lxmusic2api')}",
+            key: f"http://{format_netloc(host, ctx.port(key))}"
+            for key in ("searxng", "firecrawl", "lxmusic2api")
         }
     raise GenerateError(f"未知部署模式 {mode!r}")
 
@@ -224,7 +225,7 @@ def _websocket_url(ctx: GenerateContext) -> str:
     """
     if ctx.mode == catalog.MODE_CONTAINER:
         return f"ws://{NAPCAT_SERVICE_NAME}:{catalog.container_port('napcat_ws')}"
-    return f"ws://{_connect_host(ctx.port_bind)}:{ctx.port('napcat_ws')}"
+    return f"ws://{format_netloc(_connect_host(ctx.port_bind), ctx.port('napcat_ws'))}"
 
 
 def build_env(ctx: GenerateContext) -> dict[str, str]:
@@ -334,11 +335,10 @@ def prev(name: str) -> str | None:
 
 def _searxng_base_url(ctx: GenerateContext) -> str:
     port = ctx.port("searxng")
-    if ctx.port_bind in ("0.0.0.0", "::"):
+    host = ctx.port_bind.removeprefix("[").removesuffix("]")
+    if host in ("0.0.0.0", "::"):
         host = "localhost"
-    else:
-        host = ctx.port_bind
-    return f"http://{host}:{port}"
+    return f"http://{format_netloc(host, port)}"
 
 
 def _selected_port_keys(ctx: GenerateContext) -> set[str]:
diff --git a/tests/test_deploy_generate.py b/tests/test_deploy_generate.py
index d43e7d04..32134ca9 100644
--- a/tests/test_deploy_generate.py
+++ b/tests/test_deploy_generate.py
@@ -5,6 +5,7 @@
 import re
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlsplit
 
 import pytest
 import yaml
@@ -892,6 +893,45 @@ def test_host_mode_connect_urls_never_use_wildcard_bind(tmp_path: Path) -> None:
     assert "0.0.0.0" not in config.env["UNDEFINED_DEPLOY_SEARXNG_BASE_URL"]
 
 
+@pytest.mark.parametrize("bind", ["::1", "[::1]", "2001:db8::42"])
+def test_host_mode_ipv6_connect_urls_are_parseable(tmp_path: Path, bind: str) -> None:
+    ctx = _ctx(
+        tmp_path,
+        mode=catalog.MODE_HOST,
+        port_bind=bind,
+        services=("searxng", "firecrawl", "lxmusic2api"),
+        ports={"napcat_ws": 13001, "searxng": 18080},
+    )
+    config = generate.build(ctx)
+    expected_host = bind.removeprefix("[").removesuffix("]")
+    urls = generate.compose_service_urls(ctx)
+    for service, url in urls.items():
+        parsed = urlsplit(url)
+        assert parsed.hostname == expected_host
+        assert parsed.port == ctx.port(service)
+    websocket = urlsplit(config.websocket_url)
+    assert websocket.hostname == expected_host
+    assert websocket.port == 13001
+    searxng = urlsplit(config.env["UNDEFINED_DEPLOY_SEARXNG_BASE_URL"])
+    assert searxng.hostname == expected_host
+    assert searxng.port == 18080
+
+
+@pytest.mark.parametrize("bind", ["::", "[::]"])
+def test_host_mode_ipv6_wildcard_urls_use_loopback(tmp_path: Path, bind: str) -> None:
+    ctx = _ctx(tmp_path, mode=catalog.MODE_HOST, port_bind=bind)
+    config = generate.build(ctx)
+    assert urlsplit(config.websocket_url).hostname == "127.0.0.1"
+    assert (
+        urlsplit(config.env["UNDEFINED_DEPLOY_SEARXNG_BASE_URL"]).hostname
+        == "localhost"
+    )
+    assert all(
+        urlsplit(url).hostname == "127.0.0.1"
+        for url in generate.compose_service_urls(ctx).values()
+    )
+
+
 def test_bot_container_forbids_privilege_escalation(tmp_path: Path) -> None:
     """本体容器以 root 运行且挂着宿主 docker.sock，至少要禁止提权。
 

From 2bb4bf75d395c5a8392051e97994b6f0adb3aa4a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:27:19 +0800
Subject: [PATCH 067/121] fix(webui): serialize auth token refreshes by session

---
 docs/management-api.md                    |   2 +
 src/Undefined/webui/static/js/api.js      |  54 ++++++++----
 tests/test_webui_auth_refresh_behavior.py | 103 ++++++++++++++++++++++
 3 files changed, 142 insertions(+), 17 deletions(-)
 create mode 100644 tests/test_webui_auth_refresh_behavior.py

diff --git a/docs/management-api.md b/docs/management-api.md
index 7a5eaf03..fc113e34 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -75,6 +75,8 @@ Management API 兼容两套鉴权：
 
 ### 查询会话
 
+WebUI 的并发请求共用同一次 refresh token 轮换；旧会话的迟到刷新响应不会覆盖新登录的令牌，也不会清除新会话。浏览器的 Cookie Session 认证继续兼容。
+
 - `GET /api/v1/management/auth/session`
 
 返回当前是否已认证、是否仍在使用默认密码、配置文件是否存在，以及控制面的 capabilities。
diff --git a/src/Undefined/webui/static/js/api.js b/src/Undefined/webui/static/js/api.js
index ed8287e5..47899511 100644
--- a/src/Undefined/webui/static/js/api.js
+++ b/src/Undefined/webui/static/js/api.js
@@ -165,26 +165,46 @@ function updateAuthFromPayload(payload) {
     return true;
 }
 
+let _authRefreshRequest = null;
+
 async function refreshAccessToken() {
-    if (!state.authRefreshToken) {
+    const refreshToken = state.authRefreshToken;
+    if (!refreshToken) {
         throw new Error("Unauthorized");
     }
-    const response = await apiWithFallback(authEndpointCandidates("refresh"), {
-        method: "POST",
-        body: JSON.stringify({ refresh_token: state.authRefreshToken }),
-        headers: state.authAccessToken
-            ? { Authorization: `Bearer ${state.authAccessToken}` }
-            : {},
-    });
-    const payload = await response
-        .clone()
-        .json()
-        .catch(() => ({}));
-    if (!response.ok || !updateAuthFromPayload(payload)) {
-        clearStoredAuthTokens();
-        throw new Error("Unauthorized");
+    if (_authRefreshRequest?.token === refreshToken) {
+        return _authRefreshRequest.promise;
+    }
+    const request = { token: refreshToken, promise: null };
+    request.promise = (async () => {
+        const response = await apiWithFallback(
+            authEndpointCandidates("refresh"),
+            {
+                method: "POST",
+                body: JSON.stringify({ refresh_token: refreshToken }),
+                headers: state.authAccessToken
+                    ? { Authorization: `Bearer ${state.authAccessToken}` }
+                    : {},
+            },
+        );
+        const payload = await response
+            .clone()
+            .json()
+            .catch(() => ({}));
+        // 登录或退出可能已替换会话；旧请求不能改写新令牌。
+        if (state.authRefreshToken !== refreshToken) return payload;
+        if (!response.ok || !updateAuthFromPayload(payload)) {
+            clearStoredAuthTokens();
+            throw new Error("Unauthorized");
+        }
+        return payload;
+    })();
+    _authRefreshRequest = request;
+    try {
+        return await request.promise;
+    } finally {
+        if (_authRefreshRequest === request) _authRefreshRequest = null;
     }
-    return payload;
 }
 
 async function api(path, options = {}) {
@@ -216,7 +236,7 @@ async function api(path, options = {}) {
                 _skipRefreshRetry: true,
             });
         } catch (_error) {
-            clearStoredAuthTokens();
+            // refreshAccessToken 只清除仍属于失败请求的令牌。
         }
     }
     if (res.status === 401) {
diff --git a/tests/test_webui_auth_refresh_behavior.py b/tests/test_webui_auth_refresh_behavior.py
new file mode 100644
index 00000000..1edb5541
--- /dev/null
+++ b/tests/test_webui_auth_refresh_behavior.py
@@ -0,0 +1,103 @@
+"""Concurrent WebUI refreshes share one rotation and respect session replacement."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+import pytest
+
+from test_webui_runtime_chat_behavior import REPO_ROOT, _require_env
+
+
+def _run_refresh_scenario(scenario: str) -> dict[str, Any]:
+    _require_env()
+    script = r"""
+const fs = require('node:fs');
+const vm = require('node:vm');
+const input = JSON.parse(fs.readFileSync(0, 'utf8'));
+const state = {authAccessToken: 'oldA', authRefreshToken: 'oldR',
+  authAccessTokenExpiresAt: Date.now() + 10, authenticated: true};
+const pending = [];
+let resources = 0;
+const context = vm.createContext({state, Response, AbortController, Map,
+  FormData, Blob, URLSearchParams, console, setTimeout, clearTimeout,
+  window: {setTimeout: () => 1}, refreshUI: () => {},
+  storeAuthTokens: tokens => Object.assign(state, {authAccessToken: tokens.accessToken,
+    authRefreshToken: tokens.refreshToken, authAccessTokenExpiresAt: tokens.accessTokenExpiresAt}),
+  clearStoredAuthTokens: () => Object.assign(state, {authAccessToken: '',
+    authRefreshToken: '', authAccessTokenExpiresAt: 0}),
+  fetch: async (path, options) => {
+    if (path === '/refresh') return new Promise(resolve => pending.push({resolve,
+      body: JSON.parse(options.body)}));
+    resources++;
+    return new Response('{}', {status: input.scenario === 'cookie' || state.authAccessToken ? 200 : 401});
+  },
+});
+vm.runInContext(fs.readFileSync(input.source, 'utf8'), context);
+vm.runInContext('AUTH_ENDPOINTS.refresh = ["/refresh"]', context);
+const pair = {access_token: 'newA', refresh_token: 'newR', expires_in: 900};
+const tick = async () => { for(let i=0; i<10; i++) await new Promise(r => setImmediate(r)); };
+(async () => {
+  if (input.scenario.startsWith('replacement')) {
+    const request = vm.runInContext('refreshAccessToken()', context);
+    await tick();
+    Object.assign(state, {authAccessToken: 'loginA', authRefreshToken: 'loginR'});
+    pending[0].resolve(new Response(JSON.stringify(pair), {
+      status: input.scenario === 'replacement_error' ? 401 : 200}));
+    await request;
+  } else {
+    const calls = vm.runInContext('Promise.allSettled([api("/status"), api("/system")])', context);
+    await tick();
+    const refreshCountWhilePending = pending.length;
+    pending[0].resolve(new Response(JSON.stringify(pair), {status: input.scenario === 'failure' ? 401 : 200}));
+    const results = await calls;
+    console.log(JSON.stringify({state, refreshCountWhilePending, refreshes: pending.length,
+      inputs: pending.map(item => item.body), resources, results: results.map(item => item.status)}));
+    return;
+  }
+  console.log(JSON.stringify({state, refreshes: pending.length}));
+})().catch(error => { console.error(error); process.exitCode = 1; });
+"""
+    completed = subprocess.run(
+        ["node", "-e", script],
+        input=json.dumps(
+            {
+                "source": str(REPO_ROOT / "src/Undefined/webui/static/js/api.js"),
+                "scenario": scenario,
+            }
+        ),
+        capture_output=True,
+        text=True,
+        timeout=15,
+        check=False,
+    )
+    assert completed.returncode == 0, completed.stderr
+    result: dict[str, Any] = json.loads(completed.stdout.strip().splitlines()[-1])
+    return result
+
+
+@pytest.mark.parametrize("scenario", ["token", "cookie"])
+def test_parallel_api_requests_share_one_auth_refresh(scenario: str) -> None:
+    result = _run_refresh_scenario(scenario)
+    assert result["refreshCountWhilePending"] == result["refreshes"] == 1
+    assert result["inputs"] == [{"refresh_token": "oldR"}]
+    assert result["state"]["authAccessToken"] == "newA"
+    assert result["state"]["authRefreshToken"] == "newR"
+    assert result["resources"] == 2
+    assert result["results"] == ["fulfilled", "fulfilled"]
+
+
+@pytest.mark.parametrize("scenario", ["replacement_success", "replacement_error"])
+def test_late_refresh_response_preserves_new_login(scenario: str) -> None:
+    result = _run_refresh_scenario(scenario)
+    assert result["state"]["authAccessToken"] == "loginA"
+    assert result["state"]["authRefreshToken"] == "loginR"
+
+
+def test_failed_shared_refresh_clears_its_own_expired_tokens() -> None:
+    result = _run_refresh_scenario("failure")
+    assert result["refreshes"] == 1
+    assert result["state"]["authRefreshToken"] == ""
+    assert result["results"] == ["rejected", "rejected"]

From ce9467a91f08b2abfee1717cfa74f75388bea987 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:27:58 +0800
Subject: [PATCH 068/121] fix(memes): reject stale attachment cache fills

---
 docs/memes.md                  |   2 +
 src/Undefined/memes/search.py  |  62 +++++++++--------
 src/Undefined/memes/service.py |  38 +----------
 tests/test_meme_lifecycle.py   | 118 +++++++++++++++++++++++++++++++++
 4 files changed, 156 insertions(+), 64 deletions(-)
 create mode 100644 tests/test_meme_lifecycle.py

diff --git a/docs/memes.md b/docs/memes.md
index 46b8d45f..24b3a9b0 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -56,4 +56,6 @@ gif_analysis_frames = 6         # GIF 的抽帧数量
 
 重分析期间仍可编辑或删除条目。模型返回后会核对编辑修订和记录身份，过期结果会被丢弃，包括旧任务的删除判定；不会覆盖人工修改、恢复已删除条目或影响同 UID 重新入库的记录。使用次数单独累加，分析保留最新计数；GIF 多帧临时文件按分析任务独立清理。最终记录与索引写入开始后，取消等待该次写入收尾。
 
+编辑、停用或删除会使全局 UID 附件缓存失效。正在读取旧记录的解析线程会重新核对失效代次，重新读取当前状态，不会把停用前的记录重新缓存。
+
 * Management API 完整接口参阅 [Management API — Runtime 代理](management-api.md#6-runtime-代理)，Runtime API 直连接口参阅 [Runtime API — 表情包库](openapi.md#表情包库)。
diff --git a/src/Undefined/memes/search.py b/src/Undefined/memes/search.py
index c1de5703..555cb1d7 100644
--- a/src/Undefined/memes/search.py
+++ b/src/Undefined/memes/search.py
@@ -31,6 +31,7 @@ class MemeSearchMixin:
         _cfg: Any
         _global_image_cache: dict[str, AttachmentRecord]
         _global_image_cache_lock: threading.Lock
+        _global_image_cache_generation: int
         _job_queue: Any | None
         _retrieval_runtime: Any | None
         _store: MemeStore
@@ -41,34 +42,39 @@ def resolve_global_image_sync(self, uid: str) -> AttachmentRecord | None:
         if not normalized_uid:
             return None
 
-        with self._global_image_cache_lock:
-            cached = self._global_image_cache.get(normalized_uid)
-        if cached is not None:
-            return cached
-
-        record = self._store.get_sync(normalized_uid)
-        if record is None or not record.enabled or record.status != "ready":
-            return None
-        # scope_key 留空：表情库 UID 全局可解析，不受会话 scope 限制
-        attachment = AttachmentRecord(
-            uid=record.uid,
-            scope_key="",
-            kind="image",
-            media_type="image",
-            display_name=Path(record.blob_path).name,
-            source_kind="meme_library",
-            source_ref=Path(record.blob_path).resolve().as_uri(),
-            local_path=record.blob_path,
-            mime_type=record.mime_type,
-            sha256=record.content_sha256,
-            created_at=record.created_at,
-            segment_data={"subType": "1"},
-            semantic_kind="meme",
-            description=record.description,
-        )
-        with self._global_image_cache_lock:
-            self._global_image_cache[normalized_uid] = attachment
-        return attachment
+        while True:
+            with self._global_image_cache_lock:
+                cached = self._global_image_cache.get(normalized_uid)
+                generation = self._global_image_cache_generation
+            if cached is not None:
+                return cached
+
+            # 数据库读取在线程中完成；读期间的失效不能被迟到回填覆盖。
+            record = self._store.get_sync(normalized_uid)
+            with self._global_image_cache_lock:
+                if generation != self._global_image_cache_generation:
+                    continue
+                if record is None or not record.enabled or record.status != "ready":
+                    return None
+                # scope_key 留空：表情库 UID 全局可解析，不受会话 scope 限制
+                attachment = AttachmentRecord(
+                    uid=record.uid,
+                    scope_key="",
+                    kind="image",
+                    media_type="image",
+                    display_name=Path(record.blob_path).name,
+                    source_kind="meme_library",
+                    source_ref=Path(record.blob_path).resolve().as_uri(),
+                    local_path=record.blob_path,
+                    mime_type=record.mime_type,
+                    sha256=record.content_sha256,
+                    created_at=record.created_at,
+                    segment_data={"subType": "1"},
+                    semantic_kind="meme",
+                    description=record.description,
+                )
+                self._global_image_cache[normalized_uid] = attachment
+                return attachment
 
     async def resolve_global_image(self, uid: str) -> AttachmentRecord | None:
         return await asyncio.to_thread(self.resolve_global_image_sync, uid)
diff --git a/src/Undefined/memes/service.py b/src/Undefined/memes/service.py
index ee42efae..443413b8 100644
--- a/src/Undefined/memes/service.py
+++ b/src/Undefined/memes/service.py
@@ -73,6 +73,7 @@ def __init__(
         self._ingest_digest_locks_guard = asyncio.Lock()
         self._global_image_cache: dict[str, AttachmentRecord] = {}
         self._global_image_cache_lock = threading.Lock()
+        self._global_image_cache_generation = 0
 
     @property
     def enabled(self) -> bool:
@@ -150,42 +151,7 @@ def _invalidate_global_image_cache(self, uid: str) -> None:
             return
         with self._global_image_cache_lock:
             self._global_image_cache.pop(normalized_uid, None)
-
-    def resolve_global_image_sync(self, uid: str) -> AttachmentRecord | None:
-        normalized_uid = str(uid or "").strip()
-        if not normalized_uid:
-            return None
-
-        with self._global_image_cache_lock:
-            cached = self._global_image_cache.get(normalized_uid)
-        if cached is not None:
-            return cached
-
-        record = self._store.get_sync(normalized_uid)
-        if record is None or not record.enabled or record.status != "ready":
-            return None
-        attachment = AttachmentRecord(
-            uid=record.uid,
-            scope_key="",
-            kind="image",
-            media_type="image",
-            display_name=Path(record.blob_path).name,
-            source_kind="meme_library",
-            source_ref=Path(record.blob_path).resolve().as_uri(),
-            local_path=record.blob_path,
-            mime_type=record.mime_type,
-            sha256=record.content_sha256,
-            created_at=record.created_at,
-            segment_data={"subType": "1"},
-            semantic_kind="meme",
-            description=record.description,
-        )
-        with self._global_image_cache_lock:
-            self._global_image_cache[normalized_uid] = attachment
-        return attachment
-
-    async def resolve_global_image(self, uid: str) -> AttachmentRecord | None:
-        return await asyncio.to_thread(self.resolve_global_image_sync, uid)
+            self._global_image_cache_generation += 1
 
     async def get_meme(self, uid: str) -> dict[str, Any] | None:
         record = await self._store.get(uid)
diff --git a/tests/test_meme_lifecycle.py b/tests/test_meme_lifecycle.py
new file mode 100644
index 00000000..edc89e27
--- /dev/null
+++ b/tests/test_meme_lifecycle.py
@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+import threading
+from types import SimpleNamespace
+from typing import cast
+
+import pytest
+
+from Undefined.memes import MemeService, MemeStore, MemeVectorStore
+from Undefined.memes.models import MemeRecord
+
+
+class _Vectors:
+    def __init__(self) -> None:
+        self.records: dict[str, MemeRecord] = {}
+
+    async def upsert(self, record: MemeRecord) -> None:
+        self.records[record.uid] = record
+
+    async def delete(self, uid: str) -> None:
+        self.records.pop(uid, None)
+
+
+def _record(tmp_path: Path) -> MemeRecord:
+    blob = tmp_path / "meme.png"
+    blob.write_bytes(b"isolated meme")
+    return MemeRecord(
+        uid="pic_lifecycle",
+        content_sha256="isolated content",
+        blob_path=str(blob),
+        preview_path=str(blob),
+        mime_type="image/png",
+        file_size=blob.stat().st_size,
+        width=1,
+        height=1,
+        is_animated=False,
+        enabled=True,
+        pinned=False,
+        auto_description="original description",
+        manual_description="",
+        ocr_text="",
+        search_text="original description",
+        created_at="2026-10-07T12:00:00",
+        updated_at="2026-10-07T12:00:00",
+    )
+
+
+async def _fixture(
+    tmp_path: Path, *, store: MemeStore | None = None, vectors: _Vectors | None = None
+) -> tuple[MemeService, MemeStore, _Vectors, MemeRecord]:
+    store = store or MemeStore(tmp_path / "memes.sqlite3")
+    record = await store.upsert_record(_record(tmp_path))
+    vectors = vectors or _Vectors()
+    await vectors.upsert(record)
+    config = SimpleNamespace(
+        enabled=True,
+        preview_dir=str(tmp_path / "previews"),
+        max_items=1,
+        max_total_bytes=1024,
+        keyword_top_k=10,
+        semantic_top_k=10,
+        rerank_top_k=10,
+    )
+    service = MemeService(
+        config_getter=lambda: config,
+        store=store,
+        vector_store=cast(MemeVectorStore, vectors),
+    )
+    return service, store, vectors, record
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mutation", ["disable", "edit", "delete"])
+async def test_delayed_global_image_read_cannot_restore_invalidated_cache(
+    tmp_path: Path, mutation: str
+) -> None:
+    entered = threading.Event()
+    release = threading.Event()
+
+    class _DelayedReadStore(MemeStore):
+        armed = False
+
+        def get_sync(self, uid: str) -> MemeRecord | None:
+            record = super().get_sync(uid)
+            if self.armed and not entered.is_set():
+                entered.set()
+                assert release.wait(timeout=5)
+            return record
+
+    store = _DelayedReadStore(tmp_path / "memes.sqlite3")
+    service, _, _, record = await _fixture(tmp_path, store=store)
+    store.armed = True
+    resolving = asyncio.create_task(service.resolve_global_image(record.uid))
+    try:
+        assert await asyncio.to_thread(entered.wait, 3)
+        if mutation == "delete":
+            assert await service.delete_meme(record.uid)
+        else:
+            assert await service.update_meme(
+                record.uid,
+                enabled=False if mutation == "disable" else None,
+                manual_description="edited description" if mutation == "edit" else None,
+            )
+        release.set()
+        resolved = await asyncio.wait_for(resolving, timeout=3)
+        cached = await service.resolve_global_image(record.uid)
+        if mutation == "edit":
+            assert resolved is not None
+            assert resolved.description == "edited description"
+            assert cached is resolved
+        else:
+            assert resolved is None
+            assert cached is None
+    finally:
+        release.set()
+        await asyncio.gather(resolving, return_exceptions=True)

From 6857bab68300445c4c41ce60529bba67fc779b27 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:28:55 +0800
Subject: [PATCH 069/121] fix(chat): serialize conversation deletion with job
 acceptance

---
 docs/management-api.md              |  2 +-
 docs/openapi.md                     |  2 +-
 src/Undefined/api/routes/chat.py    | 60 +++++++++++++--------
 tests/test_runtime_api_chat_jobs.py | 83 +++++++++++++++++++++++++++++
 4 files changed, 122 insertions(+), 25 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index fc113e34..e296a08e 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -244,7 +244,7 @@ GET /api/v1/management/runtime/commands?scope=webui&q=help
   - `PATCH` 传 `{"title":"..."}`。
   - `DELETE` 使用路径参数 `conversation_id`。
 - 校验：
-  - 删除会话时 Runtime 会检查是否存在运行中或收尾落盘中的 WebChat job。
+  - 删除会话与接受新任务共用串行边界；存在运行中或收尾落盘的 WebChat job 时返回 `409`，已删除会话创建新任务返回 `404`。
 - 响应：
   - `200` / `201`：会话列表或会话对象。
   - `404`：会话不存在。
diff --git a/docs/openapi.md b/docs/openapi.md
index e5099d98..67c22431 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -397,7 +397,7 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 - `GET /api/v1/chat/conversations`：列出 WebChat 会话，响应包含 `conversations`、`active_job`、`default_conversation_id` 和 `virtual_user_id`。
 - `POST /api/v1/chat/conversations`：新建会话，Body 可选 `{"title":"..."}`。不传标题时先使用临时标题。
 - `PATCH /api/v1/chat/conversations/{conversation_id}`：重命名会话，Body 为 `{"title":"..."}`。手动标题会标记为 `manual`，后续不会被自动标题覆盖。
-- `DELETE /api/v1/chat/conversations/{conversation_id}`：删除会话 JSON。若目标会话存在运行中或收尾落盘的 WebChat job，返回 `409`。
+- `DELETE /api/v1/chat/conversations/{conversation_id}`：删除会话 JSON。与新任务接受共用串行边界；若目标会话存在运行中或收尾落盘的 WebChat job，返回 `409`，删除后的会话创建新任务返回 `404`。
 
 会话标题由后端维护。第一条用户消息写入后会先用首问前若干字符作为临时标题；当该会话同时具备首问和首答时，后端会调标题生成模型用“首问 + 首答”生成正式标题。标题生成带状态和内容哈希校验，避免并发回复、手动重命名或历史变化时把旧标题写回新内容。
 
diff --git a/src/Undefined/api/routes/chat.py b/src/Undefined/api/routes/chat.py
index 382811b3..fd07ddf6 100644
--- a/src/Undefined/api/routes/chat.py
+++ b/src/Undefined/api/routes/chat.py
@@ -411,35 +411,38 @@ async def create_job(
         await self.conversation_store.ensure_ready(self._ctx.history_manager)
         requested_conversation_id = str(conversation_id or "").strip()
         resolved_conversation_id = requested_conversation_id or _DEFAULT_CONVERSATION_ID
-        conversation = await self.conversation_store.get_conversation(
-            resolved_conversation_id
-        )
-        if conversation is None:
-            if requested_conversation_id:
-                raise KeyError(resolved_conversation_id)
-            conversation = await self.conversation_store.ensure_default_conversation()
-            resolved_conversation_id = str(conversation["id"])
-        now = time.time()
-        job = ChatJob(
-            job_id=uuid4().hex,
-            text=text,
-            created_at=now,
-            updated_at=now,
-            conversation_id=resolved_conversation_id,
-            user_history_attachments=list(user_history_attachments or []),
-            user_history_references=list(user_history_references or []),
-            user_history_pre_recorded=pre_record_user_history
-            or reuse_previous_user_history,
-        )
         async with self._lock:
             if self._closing:
                 raise ChatJobManagerClosingError("Chat service is stopping")
+            # 会话存在性检查与 job 接受必须和删除共用同一串行边界。
+            conversation = await self.conversation_store.get_conversation(
+                resolved_conversation_id
+            )
+            if conversation is None:
+                if requested_conversation_id:
+                    raise KeyError(resolved_conversation_id)
+                conversation = (
+                    await self.conversation_store.ensure_default_conversation()
+                )
+                resolved_conversation_id = str(conversation["id"])
             if any(
                 self._job_blocks_history_mutation(existing)
                 for existing in self._jobs.values()
                 if existing.conversation_id == resolved_conversation_id
             ):
                 raise RuntimeError("Chat job is still running")
+            now = time.time()
+            job = ChatJob(
+                job_id=uuid4().hex,
+                text=text,
+                created_at=now,
+                updated_at=now,
+                conversation_id=resolved_conversation_id,
+                user_history_attachments=list(user_history_attachments or []),
+                user_history_references=list(user_history_references or []),
+                user_history_pre_recorded=pre_record_user_history
+                or reuse_previous_user_history,
+            )
             self._jobs[job.job_id] = job
             try:
                 # stop 必须等创建阶段收敛后再快照，避免漏掉稍后才启动的 task。
@@ -587,6 +590,18 @@ async def clear_history_when_idle(
                 or 0
             )
 
+    async def delete_conversation_when_idle(self, conversation_id: str) -> bool | None:
+        """删除空闲会话；None 表示会话仍被已接受的任务占用。"""
+        await self.conversation_store.ensure_ready(self._ctx.history_manager)
+        async with self._lock:
+            if any(
+                self._job_blocks_history_mutation(job)
+                and job.conversation_id == conversation_id
+                for job in self._jobs.values()
+            ):
+                return None
+            return await self.conversation_store.delete_conversation(conversation_id)
+
     async def cancel_job(self, job_id: str) -> ChatJob | None:
         job = await self.get_job(job_id)
         if job is None:
@@ -2832,11 +2847,10 @@ async def chat_conversation_delete_handler(
     job_manager: ChatJobManager,
     request: web.Request,
 ) -> Response:
-    await job_manager.conversation_store.ensure_ready(ctx.history_manager)
     conversation_id = str(request.match_info.get("conversation_id", "") or "").strip()
-    if await job_manager.has_running_job(conversation_id):
+    existed = await job_manager.delete_conversation_when_idle(conversation_id)
+    if existed is None:
         return _json_error("Chat job is still running", status=409)
-    existed = await job_manager.conversation_store.delete_conversation(conversation_id)
     if not existed:
         return _json_error("Conversation not found", status=404)
     logger.info(
diff --git a/tests/test_runtime_api_chat_jobs.py b/tests/test_runtime_api_chat_jobs.py
index 5ffaf36b..f347fafd 100644
--- a/tests/test_runtime_api_chat_jobs.py
+++ b/tests/test_runtime_api_chat_jobs.py
@@ -107,6 +107,89 @@ async def _last_webchat_record(server: RuntimeAPIServer) -> dict[str, Any]:
     return cast(dict[str, Any], messages[-1])
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("first_operation", ["create", "delete"])
+@pytest.mark.parametrize("pre_record_user_history", [False, True])
+async def test_conversation_delete_and_job_acceptance_are_serialized(
+    monkeypatch: pytest.MonkeyPatch,
+    first_operation: str,
+    pre_record_user_history: bool,
+) -> None:
+    release_chat = asyncio.Event()
+    chat_started = asyncio.Event()
+
+    async def run_chat(_ctx: RuntimeAPIContext, **_kwargs: Any) -> str:
+        chat_started.set()
+        await release_chat.wait()
+        return "chat"
+
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_chat)
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    store = manager.conversation_store
+    await store.ensure_ready(manager._ctx.history_manager)
+    conversation = await store.create_conversation()
+    conversation_id = str(conversation["id"])
+    request = cast(
+        web.Request,
+        cast(Any, _DummyRequest(match_info={"conversation_id": conversation_id})),
+    )
+    # 模拟重命名/文件写入持有真实会话锁，让两种请求在同一边界排队。
+    conversation_lock = store._get_lock(conversation_id)
+    await conversation_lock.acquire()
+
+    async def create() -> runtime_api_chat.ChatJob | None:
+        try:
+            return await manager.create_job(
+                "hello",
+                conversation_id,
+                pre_record_user_history=pre_record_user_history,
+            )
+        except KeyError:
+            return None
+
+    async def delete() -> web.Response:
+        return await server._chat_conversation_delete_handler(request)
+
+    try:
+        if first_operation == "create":
+            creation = asyncio.create_task(create())
+            await asyncio.sleep(0)
+            deletion = asyncio.create_task(delete())
+        else:
+            deletion = asyncio.create_task(delete())
+            await asyncio.sleep(0)
+            creation = asyncio.create_task(create())
+        await asyncio.sleep(0)
+        conversation_lock.release()
+        job, response = await asyncio.wait_for(
+            asyncio.gather(creation, deletion), timeout=2
+        )
+        if first_operation == "create":
+            assert job is not None
+            assert response.status == 409
+            assert await store.get_conversation(conversation_id) is not None
+            await asyncio.wait_for(chat_started.wait(), timeout=2)
+            await store.append_message(
+                conversation_id,
+                role="bot",
+                text_content="reply",
+                display_name="Bot",
+                user_name="Bot",
+            )
+        else:
+            assert response.status == 200
+            assert job is None
+            assert not manager._jobs
+            assert not chat_started.is_set()
+            assert await store.get_conversation(conversation_id) is None
+    finally:
+        if conversation_lock.locked():
+            conversation_lock.release()
+        release_chat.set()
+        await server.stop()
+
+
 @pytest.mark.asyncio
 async def test_history_finalized_is_published_only_after_job_releases_session(
     monkeypatch: pytest.MonkeyPatch,

From 93a3f426379899308b9d8ebf2ae83f65fb16d4e9 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:29:36 +0800
Subject: [PATCH 070/121] fix(chat): preserve selection when renaming
 conversations

---
 apps/undefined-chat/README.md                 |  1 +
 .../chat-store/conversation-rename.test.ts    | 51 +++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   | 11 +++-
 apps/undefined-chat/src/chat-store/types.ts   |  6 ++-
 .../message-timeline/MessageTimeline.test.tsx | 16 ++++--
 5 files changed, 77 insertions(+), 8 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/conversation-rename.test.ts

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index a639307b..b0d7e71f 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -15,6 +15,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 引用：引用 bot 消息、划词引用选中文本、发送引用、引用芯片跳转当前已加载源消息；源消息不在当前页时会自动加载一页更早历史，仍未命中需手动继续加载更早历史。
 - 工具调用块：层级展示、状态、运行中实时计时、阶段明细（stage detail）、与 WebUI 一致的输入/输出预览（JSON/Python 风格结构化、Markdown 输出、附件图片预览）；历史回放支持 timeline/calls/events 多级回退。
 - 自动滚动：智能跟随底部，可在设置面板开关，偏好持久化到 localStorage。
+- 重命名只更新目标会话标题，保留当前会话、输入草稿与移动端面板；请求期间切换会话也不会被迟到响应切回。
 - 事件：SSE 优先，断开时 JSON fallback（指数退避重连，活跃任务持续重试）。
 - 快捷键：Ctrl/Cmd+N 新会话，Ctrl/Cmd+K 聚焦输入并打开命令模式，Ctrl/Cmd+/ 切换侧栏，Ctrl/Cmd+, 打开设置，Escape 关闭当前弹层/抽屉。
 - i18n：中英双语运行时切换，提供语言切换 UI，并按系统语言自动检测默认语言。
diff --git a/apps/undefined-chat/src/chat-store/conversation-rename.test.ts b/apps/undefined-chat/src/chat-store/conversation-rename.test.ts
new file mode 100644
index 00000000..f493c566
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/conversation-rename.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test, vi } from "vitest";
+import { conversation, runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+describe("conversation rename", () => {
+	test.each([false, true])(
+		"keeps the current conversation during rename (switch while pending: %s)",
+		async (switchWhilePending) => {
+			let finishRename!: (value: { ok: boolean }) => void;
+			const client = runtimeClientStub({
+				listConversations: vi.fn(async () => ({
+					conversations: [conversation({ id: "A" }), conversation({ id: "B" })],
+					activeJob: null,
+					defaultConversationId: "A",
+					virtualUserId: "webchat",
+				})),
+				renameConversation: vi.fn(
+					() =>
+						new Promise<{ ok: boolean }>((resolve) => {
+							finishRename = resolve;
+						}),
+				),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			if (!switchWhilePending) await store.selectConversation("B");
+			const rename = store.renameConversation("A", "Renamed A");
+			if (switchWhilePending) await store.selectConversation("B");
+			store.updateDraft("B", "B draft");
+			store.dispatch({ type: "mobile-panel/set", panel: "conversations" });
+			finishRename({ ok: true });
+			await rename;
+			expect(store.getSnapshot().selectedConversationId).toBe("B");
+			expect(store.getSnapshot().settings.mobilePanel).toBe("conversations");
+			expect(store.getSnapshot().draftsByConversation.B).toBe("B draft");
+			expect(
+				store.getSnapshot().conversations.find((item) => item.id === "A")
+					?.title,
+			).toBe("Renamed A");
+			await store.sendSelectedMessage();
+			expect(client.sendMessage).toHaveBeenCalledWith({
+				conversationId: "B",
+				message: {
+					text: "B draft",
+					attachmentIds: [],
+					references: [],
+				},
+			});
+		},
+	);
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index e768f89a..24eb3950 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -301,8 +301,14 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 							item.id === action.conversation.id ? action.conversation : item,
 						)
 					: [action.conversation, ...state.conversations],
-				selectedConversationId: action.conversation.id,
-				settings: { ...state.settings, mobilePanel: "chat" },
+				selectedConversationId:
+					action.select === false
+						? state.selectedConversationId
+						: action.conversation.id,
+				settings:
+					action.select === false
+						? state.settings
+						: { ...state.settings, mobilePanel: "chat" },
 			};
 		}
 		case "conversation/creating":
@@ -1198,6 +1204,7 @@ export function createChatStore({
 				dispatch({
 					type: "conversation/upsert",
 					conversation: { ...conversation, title: newTitle },
+					select: false,
 				});
 			}
 		} catch (err) {
diff --git a/apps/undefined-chat/src/chat-store/types.ts b/apps/undefined-chat/src/chat-store/types.ts
index 7c1a2e35..0f2889fc 100644
--- a/apps/undefined-chat/src/chat-store/types.ts
+++ b/apps/undefined-chat/src/chat-store/types.ts
@@ -197,7 +197,11 @@ export type ChatAction =
 	  }
 	// 会话管理
 	| { type: "conversation/select"; conversationId: string }
-	| { type: "conversation/upsert"; conversation: Conversation }
+	| {
+			type: "conversation/upsert";
+			conversation: Conversation;
+			select?: boolean;
+	  }
 	| {
 			type: "conversation/remove";
 			conversationId: string;
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimeline.test.tsx b/apps/undefined-chat/src/message-timeline/MessageTimeline.test.tsx
index 4b81297b..e11a52fc 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimeline.test.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimeline.test.tsx
@@ -1,4 +1,10 @@
-import { fireEvent, screen, waitFor, within } from "@testing-library/react";
+import {
+	act,
+	fireEvent,
+	screen,
+	waitFor,
+	within,
+} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import type { ReactNode } from "react";
 import { afterEach, describe, expect, test, vi } from "vitest";
@@ -304,10 +310,10 @@ describe("MessageTimeline", () => {
 			configurable: true,
 			value: 1400,
 		});
-		await Promise.resolve();
-		for (const callback of rafCallbacks.splice(0)) {
-			callback(0);
-		}
+		await act(async () => {
+			await Promise.resolve();
+			for (const callback of rafCallbacks.splice(0)) callback(0);
+		});
 
 		expect(timeline.scrollTop).toBe(420);
 		expect(onLoadMoreHistory).toHaveBeenCalledOnce();

From b42b54d4c503f94f1f607c881c5f699fe8885cd3 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:30:10 +0800
Subject: [PATCH 071/121] fix(memes): preserve delivery success and serialize
 usage indexing

---
 docs/memes.md                  |   1 +
 src/Undefined/memes/search.py  |  32 ++++-
 src/Undefined/memes/service.py |   6 +-
 tests/test_meme_lifecycle.py   | 205 ++++++++++++++++++++++++++++++++-
 4 files changed, 237 insertions(+), 7 deletions(-)

diff --git a/docs/memes.md b/docs/memes.md
index 24b3a9b0..96f28d68 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -28,6 +28,7 @@ Undefined 平台自 3.3.0 版本起内置了强大的**全局表情包库**功
 存储与索引完成后，AI Agent 会通过内置的 `memes.*` 系列工具使用表情包：
 - **`memes.search_memes`**：支持关键词检索（基于 SQLite）、语义检索（基于 ChromaDB 向量相似度）与混合检索（Hybrid）。AI 可借此根据当前对话的语境快速寻找最有梗的静态图或 GIF。
 - **发送机制**：使用统一的图片 `uid` 进行索引。系统不仅提供了 `memes.send_meme_by_uid` 让 AI 一键发送表情包，还支持 AI 输出 `<attachment uid="..."/>` 统一资源标签指令进行图文混排；用户发来的图片在 AI 上下文中也使用同一格式，旧 `<pic>` / `[图片 uid=...]` 仅作为兼容格式保留。
+- **投递结果与统计**：发送器确认完成后，使用次数或索引更新失败只记录日志，工具仍返回已发送，避免因统计故障重复投递。使用统计与编辑、停用、删除共用内容锁，索引写入会保留当前描述和启用状态；旧发送不会累计到同 UID 重新入库的记录。搜索结果以当前 SQLite 的启用状态为准，即使向量索引暂时未更新也不会返回已停用条目。
 - **回复顺序**：只有当本轮明确是纯表情包 / 纯反应图回复时，AI 才应先搜索并发送表情包。凡是需要文字承接、解释、答疑、推进任务或确认操作的场景，都必须先发送必要文字；轻松聊天、吐槽、附和、接梗、表达情绪、被拍一拍或被 @ 后的短回应等场景，文字发送成功后会更积极地在后续轮次补发一张独立表情包。严肃答疑、代码排查、长任务推进、隐私/安全拒绝或信息不足追问默认不补表情包，避免影响信息传递。
 
 ## 目录结构与配置
diff --git a/src/Undefined/memes/search.py b/src/Undefined/memes/search.py
index 555cb1d7..995f435d 100644
--- a/src/Undefined/memes/search.py
+++ b/src/Undefined/memes/search.py
@@ -16,8 +16,10 @@
 )
 from Undefined.utils.message_targets import resolve_delivery_address
 from Undefined.utils.coerce import safe_int
+from Undefined.utils.io import run_cancellation_safe
 
 if TYPE_CHECKING:
+    from contextlib import AbstractAsyncContextManager
     import threading
 
     from Undefined.memes.store import MemeStore
@@ -37,6 +39,10 @@ class MemeSearchMixin:
         _store: MemeStore
         _vector_store: MemeVectorStore
 
+        def _meme_mutation_lock(
+            self, digest: str
+        ) -> AbstractAsyncContextManager[None]: ...
+
     def resolve_global_image_sync(self, uid: str) -> AttachmentRecord | None:
         normalized_uid = str(uid or "").strip()
         if not normalized_uid:
@@ -276,7 +282,11 @@ async def search_memes(
             existing = merged.get(uid)
             if existing is None:
                 stored_record = missing_records.get(uid)
-                if stored_record is None:
+                if (
+                    stored_record is None
+                    or stored_record.status != "ready"
+                    or (not include_disabled and not stored_record.enabled)
+                ):
                     continue
                 existing = {
                     "record": stored_record,
@@ -465,10 +475,22 @@ async def send_meme_by_uid(self, uid: str, context: dict[str, Any]) -> str:
         else:
             return "发送失败：当前 sender 不支持微信投递地址"
 
-        now = _now_iso()
-        updated_record = await self._store.increment_use(uid, now)
-        if updated_record is not None:
-            await self._vector_store.upsert(updated_record)
+        async def record_usage() -> None:
+            current = await self._store.get(uid)
+            if current is None or current.generation != record.generation:
+                return
+            updated_record = await self._store.increment_use(uid, _now_iso())
+            if updated_record is not None:
+                await self._vector_store.upsert(updated_record)
+
+        try:
+            async with self._meme_mutation_lock(record.content_sha256):
+                await run_cancellation_safe(record_usage())
+        except Exception:
+            # 投递已经完成；统计失败不能使调用者据此重发同一张图片。
+            logger.warning(
+                "[memes] 已发送但使用统计/索引更新失败: uid=%s", uid, exc_info=True
+            )
         if sent_message_id is not None:
             return f"表情包已发送（message_id={sent_message_id}）"
         return "表情包已发送"
diff --git a/src/Undefined/memes/service.py b/src/Undefined/memes/service.py
index 443413b8..9eb87554 100644
--- a/src/Undefined/memes/service.py
+++ b/src/Undefined/memes/service.py
@@ -485,7 +485,11 @@ async def search_memes(
             existing = merged.get(uid)
             if existing is None:
                 stored_record = missing_records.get(uid)
-                if stored_record is None:
+                if (
+                    stored_record is None
+                    or stored_record.status != "ready"
+                    or (not include_disabled and not stored_record.enabled)
+                ):
                     continue
                 existing = {
                     "record": stored_record,
diff --git a/tests/test_meme_lifecycle.py b/tests/test_meme_lifecycle.py
index edc89e27..7611039d 100644
--- a/tests/test_meme_lifecycle.py
+++ b/tests/test_meme_lifecycle.py
@@ -4,12 +4,14 @@
 from pathlib import Path
 import threading
 from types import SimpleNamespace
-from typing import cast
+from typing import Any, cast
+from unittest.mock import AsyncMock
 
 import pytest
 
 from Undefined.memes import MemeService, MemeStore, MemeVectorStore
 from Undefined.memes.models import MemeRecord
+from Undefined.skills.toolsets.memes.send_meme_by_uid.handler import execute
 
 
 class _Vectors:
@@ -22,6 +24,15 @@ async def upsert(self, record: MemeRecord) -> None:
     async def delete(self, uid: str) -> None:
         self.records.pop(uid, None)
 
+    async def query(
+        self, query: str, *, top_k: int, include_disabled: bool = False
+    ) -> list[dict[str, Any]]:
+        return [
+            {"uid": record.uid, "semantic_score": 1.0}
+            for record in self.records.values()
+            if include_disabled or record.enabled
+        ][:top_k]
+
 
 def _record(tmp_path: Path) -> MemeRecord:
     blob = tmp_path / "meme.png"
@@ -116,3 +127,195 @@ def get_sync(self, uid: str) -> MemeRecord | None:
     finally:
         release.set()
         await asyncio.gather(resolving, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["usage", "index"])
+async def test_successful_meme_delivery_stays_successful_after_stat_failure(
+    tmp_path: Path, failure: str
+) -> None:
+    class _FailingStore(MemeStore):
+        async def increment_use(self, uid: str, used_at: str) -> MemeRecord | None:
+            if failure == "usage":
+                raise RuntimeError("isolated usage write failure")
+            return await super().increment_use(uid, used_at)
+
+    class _FailingVectors(_Vectors):
+        async def upsert(self, record: MemeRecord) -> None:
+            if failure == "index" and record.use_count:
+                raise RuntimeError("isolated index failure")
+            await super().upsert(record)
+
+    service, store, _, record = await _fixture(
+        tmp_path,
+        store=_FailingStore(tmp_path / "memes.sqlite3"),
+        vectors=_FailingVectors(),
+    )
+    sender = SimpleNamespace(send_group_message=AsyncMock(return_value=1234))
+
+    result = await execute(
+        {"uid": record.uid},
+        {
+            "meme_service": service,
+            "request_type": "group",
+            "group_id": 123,
+            "sender": sender,
+        },
+    )
+
+    assert result == "表情包已发送（message_id=1234）"
+    sender.send_group_message.assert_awaited_once()
+    saved = await store.get(record.uid)
+    assert saved is not None
+    assert saved.use_count == (0 if failure == "usage" else 1)
+    assert service._ingest_digest_locks == {}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mutation", ["edit", "disable", "delete"])
+@pytest.mark.parametrize("cancel", [False, True])
+async def test_meme_usage_index_finishes_before_following_mutation(
+    tmp_path: Path, mutation: str, cancel: bool
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _DelayedVectors(_Vectors):
+        async def upsert(self, record: MemeRecord) -> None:
+            if record.use_count == 1 and not entered.is_set():
+                entered.set()
+                await release.wait()
+            await super().upsert(record)
+
+    service, store, vectors, record = await _fixture(
+        tmp_path, vectors=_DelayedVectors()
+    )
+    sender = SimpleNamespace(send_group_message=AsyncMock(return_value=1234))
+    sending = asyncio.create_task(
+        service.send_meme_by_uid(
+            record.uid, {"request_type": "group", "group_id": 123, "sender": sender}
+        )
+    )
+    following: asyncio.Task[Any] | None = None
+    try:
+        await asyncio.wait_for(entered.wait(), timeout=3)
+        if cancel:
+            sending.cancel()
+        if mutation == "delete":
+            following = asyncio.create_task(service.delete_meme(record.uid))
+        else:
+            following = asyncio.create_task(
+                service.update_meme(
+                    record.uid,
+                    manual_description="latest description",
+                    enabled=False if mutation == "disable" else None,
+                )
+            )
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        if cancel:
+            sending.cancel()
+        assert not sending.done()
+        assert not following.done()
+        release.set()
+        if cancel:
+            with pytest.raises(asyncio.CancelledError):
+                await asyncio.wait_for(sending, timeout=3)
+        else:
+            assert await asyncio.wait_for(sending, timeout=3) == (
+                "表情包已发送（message_id=1234）"
+            )
+        assert await asyncio.wait_for(following, timeout=3)
+        saved = await store.get(record.uid)
+        if mutation == "delete":
+            assert saved is None
+            assert record.uid not in vectors.records
+        else:
+            assert saved is not None
+            assert saved.manual_description == "latest description"
+            assert saved.use_count == 1
+            assert saved.enabled == (mutation != "disable")
+            assert vectors.records[record.uid] == saved
+        sender.send_group_message.assert_awaited_once()
+        assert service._ingest_digest_locks == {}
+    finally:
+        release.set()
+        await asyncio.gather(
+            sending,
+            *([following] if following is not None else []),
+            return_exceptions=True,
+        )
+
+
+@pytest.mark.asyncio
+async def test_old_meme_delivery_does_not_increment_reinserted_uid(
+    tmp_path: Path,
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def send_group_message(*_args: Any, **_kwargs: Any) -> int:
+        entered.set()
+        await release.wait()
+        return 1234
+
+    service, store, vectors, record = await _fixture(tmp_path)
+    sending = asyncio.create_task(
+        service.send_meme_by_uid(
+            record.uid,
+            {
+                "request_type": "group",
+                "group_id": 123,
+                "sender": SimpleNamespace(send_group_message=send_group_message),
+            },
+        )
+    )
+    try:
+        await asyncio.wait_for(entered.wait(), timeout=3)
+        assert await service.delete_meme(record.uid)
+        inserted = await store.upsert_record(_record(tmp_path))
+        assert inserted.generation != record.generation
+        await vectors.upsert(inserted)
+        release.set()
+        assert await asyncio.wait_for(sending, timeout=3) == (
+            "表情包已发送（message_id=1234）"
+        )
+        assert await store.get(record.uid) == inserted
+        assert vectors.records[record.uid] == inserted
+    finally:
+        release.set()
+        await asyncio.gather(sending, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", ["semantic", "hybrid"])
+async def test_semantic_search_filters_disabled_sql_record_despite_stale_index(
+    tmp_path: Path, mode: str
+) -> None:
+    service, store, _, record = await _fixture(tmp_path)
+    assert await store.update_fields(record.uid, {"enabled": False}) is not None
+
+    result = await service.search_memes("original description", query_mode=mode)
+    included = await service.search_memes(
+        "original description", query_mode=mode, include_disabled=True
+    )
+
+    assert result["count"] == 0
+    assert included["count"] == 1
+    assert included["items"][0]["enabled"] is False
+
+
+@pytest.mark.asyncio
+async def test_delivery_error_does_not_increment_meme_usage(tmp_path: Path) -> None:
+    service, store, vectors, record = await _fixture(tmp_path)
+    sender = SimpleNamespace(
+        send_group_message=AsyncMock(
+            side_effect=RuntimeError("isolated delivery failure")
+        )
+    )
+    with pytest.raises(RuntimeError, match="isolated delivery failure"):
+        await service.send_meme_by_uid(
+            record.uid, {"request_type": "group", "group_id": 123, "sender": sender}
+        )
+    assert await store.get(record.uid) == record
+    assert vectors.records[record.uid] == record

From 999769115255ba11500d5c7ed0fb05c9a00a24eb Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:31:15 +0800
Subject: [PATCH 072/121] fix(download): validate compressed wire sizes
 separately

---
 docs/configuration.md                |   4 +-
 src/Undefined/utils/http_download.py |  11 ++-
 tests/test_http_download.py          | 141 +++++++++++++++++++++++++++
 3 files changed, 151 insertions(+), 5 deletions(-)
 create mode 100644 tests/test_http_download.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 48d076cd..47e4f756 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -988,7 +988,9 @@ summary = ""
 |---|---:|---|---|
 | `use_proxy` | `false` | URL 文件下载等消息工具联网请求是否使用 `[proxy]` 中的代理地址 | |
 | `send_text_file_max_size_kb` | `512` | 文本文件发送上限（KB） | `<=0` 回退 `512` |
-| `send_url_file_max_size_mb` | `100` | URL 文件发送上限（MB） | `<=0` 回退 `100` |
+| `send_url_file_max_size_mb` | `100` | URL 文件发送上限（MB），按 HTTP 解压后的落盘字节计算 | `<=0` 回退 `100` |
+
+下载预检与完整性校验中的 `Content-Length` 按 HTTP 传输字节比较；gzip 等压缩响应仍按实际解码后的文件大小执行容量限制。
 
 ---
 
diff --git a/src/Undefined/utils/http_download.py b/src/Undefined/utils/http_download.py
index 216ac989..e5d5f870 100644
--- a/src/Undefined/utils/http_download.py
+++ b/src/Undefined/utils/http_download.py
@@ -70,6 +70,7 @@ async def download_remote_file(
     proxy_scope: str = "messages",
     proxy_config: Any | None = None,
 ) -> tuple[str, int]:
+    """下载解码后的文件；预检大小按 HTTP 传输字节校验，容量按落盘字节限制。"""
     part_path = target_path.with_suffix(f"{target_path.suffix}.part")
 
     try:
@@ -108,14 +109,16 @@ async def download_remote_file(
                             raise ValueError("下载中发现文件超过大小限制，已取消下载")
                         if (
                             expected_size is not None
-                            and downloaded_size > expected_size
+                            and response.num_bytes_downloaded > expected_size
                         ):
                             raise ValueError("下载中发现文件超出预检大小，已取消下载")
                         await f.write(chunk)
                     await f.flush()
-
-        if expected_size is not None and downloaded_size != expected_size:
-            raise ValueError("下载完成后大小与预检不一致，已取消下载")
+                if (
+                    expected_size is not None
+                    and response.num_bytes_downloaded != expected_size
+                ):
+                    raise ValueError("下载完成后大小与预检不一致，已取消下载")
 
         await asyncio.to_thread(os.replace, part_path, target_path)
         return str(target_path.resolve()), downloaded_size
diff --git a/tests/test_http_download.py b/tests/test_http_download.py
new file mode 100644
index 00000000..95aa26f8
--- /dev/null
+++ b/tests/test_http_download.py
@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import gzip
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+
+from Undefined.utils import http_download
+
+
+def _mock_download_client(
+    monkeypatch: pytest.MonkeyPatch,
+    content: bytes,
+    *,
+    content_encoding: str | None = None,
+    content_length: int | None = None,
+) -> None:
+    client_type = httpx.AsyncClient
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        headers: dict[str, str] = {}
+        if content_encoding is not None:
+            headers["content-encoding"] = content_encoding
+        if content_length is not None:
+            headers["content-length"] = str(content_length)
+        return httpx.Response(
+            200,
+            headers=headers,
+            stream=httpx.ByteStream(b"" if request.method == "HEAD" else content),
+        )
+
+    def client(**kwargs: Any) -> httpx.AsyncClient:
+        return client_type(**kwargs, transport=httpx.MockTransport(handle))
+
+    monkeypatch.setattr(httpx, "AsyncClient", client)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("compressed", [False, True])
+async def test_download_checks_wire_size_and_writes_decoded_content(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, compressed: bool
+) -> None:
+    content = b"%PDF-1.4\n" + b"compressed download\n" * 300
+    wire_content = gzip.compress(content) if compressed else content
+    _mock_download_client(
+        monkeypatch,
+        wire_content,
+        content_encoding="gzip" if compressed else None,
+        content_length=len(wire_content),
+    )
+    probe = await http_download.probe_remote_file(
+        "https://example.test/file.pdf", timeout_seconds=1
+    )
+    target = tmp_path / "file.pdf"
+    path, size = await http_download.download_remote_file(
+        probe.final_url,
+        target,
+        max_file_size_bytes=len(content),
+        timeout_seconds=1,
+        expected_size=probe.content_length,
+        chunk_size=128,
+    )
+    assert Path(path) == target
+    assert size == len(content)
+    assert target.read_bytes() == content
+    assert not target.with_suffix(".pdf.part").exists()
+
+
+@pytest.mark.asyncio
+async def test_download_limits_decompressed_file_and_preserves_existing_target(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    content = b"large decoded content" * 1000
+    encoded = gzip.compress(content)
+    _mock_download_client(
+        monkeypatch, encoded, content_encoding="gzip", content_length=len(encoded)
+    )
+    target = tmp_path / "file.bin"
+    target.write_bytes(b"previous file")
+    with pytest.raises(ValueError, match="超过大小限制"):
+        await http_download.download_remote_file(
+            "https://example.test/file.bin",
+            target,
+            max_file_size_bytes=1024,
+            timeout_seconds=1,
+            expected_size=len(encoded),
+            chunk_size=128,
+        )
+    assert target.read_bytes() == b"previous file"
+    assert not target.with_suffix(".bin.part").exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("compressed", [False, True])
+@pytest.mark.parametrize("size_delta", [-1, 1])
+async def test_download_rejects_wire_size_changes_without_get_content_length(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    compressed: bool,
+    size_delta: int,
+) -> None:
+    content = b"download" * 100
+    encoded = gzip.compress(content) if compressed else content
+    _mock_download_client(
+        monkeypatch, encoded, content_encoding="gzip" if compressed else None
+    )
+    target = tmp_path / "file.bin"
+    with pytest.raises(ValueError, match="预检"):
+        await http_download.download_remote_file(
+            "https://example.test/file.bin",
+            target,
+            max_file_size_bytes=4096,
+            timeout_seconds=1,
+            expected_size=len(encoded) + size_delta,
+            chunk_size=128,
+        )
+    assert not target.exists()
+    assert not target.with_suffix(".bin.part").exists()
+
+
+@pytest.mark.asyncio
+async def test_download_rejects_changed_get_content_length(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    encoded = gzip.compress(b"download" * 100)
+    _mock_download_client(
+        monkeypatch, encoded, content_encoding="gzip", content_length=len(encoded)
+    )
+    target = tmp_path / "file.bin"
+    with pytest.raises(ValueError, match="大小与预检不一致"):
+        await http_download.download_remote_file(
+            "https://example.test/file.bin",
+            target,
+            max_file_size_bytes=4096,
+            timeout_seconds=1,
+            expected_size=len(encoded) + 1,
+        )
+    assert not target.exists()
+    assert not target.with_suffix(".bin.part").exists()

From ab8dfedf70af730a71683b1d14fe6d21f1c5ccc2 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:32:21 +0800
Subject: [PATCH 073/121] fix(ai): hash complete multimodal cache identities

---
 docs/configuration.md                   |  2 +
 src/Undefined/ai/multimodal/analyzer.py |  8 ++-
 tests/test_multimodal_analysis_cache.py | 92 +++++++++++++++++++++++++
 3 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_multimodal_analysis_cache.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 47e4f756..1aa91272 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -370,6 +370,8 @@ Prompt caching 补充：
 - `responses_force_stateless_replay=false`
 - `use_proxy=false`
 
+媒体分析的进程内缓存按完整媒体来源、媒体类型与补充指令区分；相同输入复用结果，长路径或 data URL 的共同前缀不会串用分析结果。
+
 ### 4.4.4 `[models.security]` 安全模型
 
 字段：
diff --git a/src/Undefined/ai/multimodal/analyzer.py b/src/Undefined/ai/multimodal/analyzer.py
index 71759af3..fe463625 100644
--- a/src/Undefined/ai/multimodal/analyzer.py
+++ b/src/Undefined/ai/multimodal/analyzer.py
@@ -329,7 +329,7 @@ async def analyze(
     ) -> dict[str, str]:
         """分析媒体文件。
 
-        始终调用视觉模型进行真实分析，不会因历史缓存而跳过。
+        相同媒体类型、完整来源与补充指令复用本次进程内的分析结果。
 
         Args:
             media_url: 媒体文件 URL 或本地路径
@@ -350,7 +350,11 @@ async def analyze(
             len(prompt_extra),
         )
 
-        cache_key = f"{detected_type}:{media_url[:100]}:{prompt_extra}"
+        cache_key = hashlib.sha256(
+            json.dumps(
+                [detected_type, media_url, prompt_extra], ensure_ascii=False
+            ).encode("utf-8")
+        ).hexdigest()
         if cache_key in self._cache:
             logger.debug("[媒体分析] 命中缓存: key=%s", cache_key[:120])
             return self._cache[cache_key]
diff --git a/tests/test_multimodal_analysis_cache.py b/tests/test_multimodal_analysis_cache.py
new file mode 100644
index 00000000..a8bee92a
--- /dev/null
+++ b/tests/test_multimodal_analysis_cache.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any, cast
+from unittest.mock import AsyncMock
+
+from PIL import Image
+from PIL.PngImagePlugin import PngInfo
+import pytest
+
+from Undefined.ai.multimodal import MultimodalAnalyzer
+from Undefined.config.models import VisionModelConfig
+
+
+def _analyzer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> tuple[MultimodalAnalyzer, AsyncMock]:
+    monkeypatch.setattr(MultimodalAnalyzer, "_load_history", lambda self: None)
+    requester = AsyncMock()
+    requester.request.side_effect = [
+        {"choices": [{"message": {"content": "描述：red image"}}]},
+        {"choices": [{"message": {"content": "描述：blue image"}}]},
+    ]
+    return (
+        MultimodalAnalyzer(
+            requester=cast(Any, requester),
+            vision_config=VisionModelConfig(
+                api_url="https://example.invalid/v1",
+                api_key="test-only",
+                model_name="vision-test",
+            ),
+        ),
+        requester,
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("source_kind", ["path", "data_url"])
+async def test_analysis_cache_distinguishes_complete_media_source(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, source_kind: str
+) -> None:
+    directory = tmp_path / ("common-prefix-" * 10)
+    directory.mkdir()
+    sources: list[str] = []
+    metadata = PngInfo()
+    metadata.add_text("common-metadata", "same prefix " * 20)
+    for color in ["red", "blue"]:
+        path = directory / f"{color}.png"
+        with Image.new("RGB", (1, 1), color=color) as image:
+            image.save(path, pnginfo=metadata)
+        sources.append(
+            str(path)
+            if source_kind == "path"
+            else "data:image/png;base64," + base64.b64encode(path.read_bytes()).decode()
+        )
+    assert sources[0][:100] == sources[1][:100]
+    analyzer, requester = _analyzer(monkeypatch)
+
+    first = await analyzer.analyze(sources[0], "image")
+    second = await analyzer.analyze(sources[1], "image")
+    repeated = await analyzer.analyze(sources[0], "image")
+
+    assert first["description"] == "red image"
+    assert second["description"] == "blue image"
+    assert repeated == first
+    assert requester.request.await_count == 2
+    first_content = requester.request.await_args_list[0].kwargs["messages"][0][
+        "content"
+    ][1]
+    second_content = requester.request.await_args_list[1].kwargs["messages"][0][
+        "content"
+    ][1]
+    assert first_content != second_content
+
+
+@pytest.mark.asyncio
+async def test_analysis_cache_distinguishes_extra_instructions(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    path = tmp_path / "image.png"
+    with Image.new("RGB", (1, 1), color="red") as image:
+        image.save(path)
+    analyzer, requester = _analyzer(monkeypatch)
+
+    first = await analyzer.analyze(str(path), "image", "describe color")
+    second = await analyzer.analyze(str(path), "image", "describe mood")
+    repeated = await analyzer.analyze(str(path), "image", "describe color")
+
+    assert first != second
+    assert repeated == first
+    assert requester.request.await_count == 2

From 66b046ea989c7584409a0c6c7272f8213b87a674 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:32:55 +0800
Subject: [PATCH 074/121] fix(webui): honor shutdown policy and avoid watcher
 deadlocks

---
 docs/configuration.md                |  2 +-
 docs/deployment.md                   |  2 +-
 docs/webui-guide.md                  |  2 +-
 src/Undefined/webui/app.py           |  7 ++-
 src/Undefined/webui/core.py          | 30 +++++++----
 src/Undefined/webui/routes/_bot.py   | 10 ++--
 tests/test_webui_process_shutdown.py | 73 ++++++++++++++++++++++++-
 tests/test_webui_update.py           | 80 +++++++++++++++++++++++++++-
 8 files changed, 182 insertions(+), 24 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 1aa91272..627575af 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1222,7 +1222,7 @@ api_key = "replace-with-your-key"
 - `webui.password` 在配置成功加载后立即刷新 Management 的登录密码，无需重启 WebUI。
 - `webui.autostart_bot` 控制下一次 WebUI 启动时是否自动启动机器人；修改不会立即启动或停止当前机器人进程。
 - `check_updates` 支持热更新；关闭后只停止页面打开时的自动检查，概览页仍可手动检查。
-- `stop_timeout_seconds` 支持热更新，下一次停止操作读取新值，进行中的停止保持开始时的期限。默认等待模型、下载、回复和历史收尾；设置正整数时需覆盖实际收尾耗时，超时强制终止可能跳过未完成的落盘。环境变量为 `WEBUI_STOP_TIMEOUT_SECONDS`，TOML 显式配置优先。
+- `stop_timeout_seconds` 支持热更新，下一次停止操作读取新值，进行中的停止保持开始时的期限。停止按钮、WebUI 关停与更新前停止共用此期限；请求取消也会先等待子进程清理收敛。默认等待模型、下载、回复和历史收尾；设置正整数时需覆盖实际收尾耗时，超时强制终止可能跳过未完成的落盘。环境变量为 `WEBUI_STOP_TIMEOUT_SECONDS`，TOML 显式配置优先。
 - `autostart_bot=true` 时，运行 `uv run Undefined-webui` 会自动拉起 bot 进程，无需手动点击启动按钮；与 WebUI 更新重启后的自动恢复机制（`pending_bot_autostart` marker）互不冲突。
 - `uv run deploy up` 在 `container` 与 `host` 模式下都会写入 `autostart_bot = false`；部署后先完成配置与 QQ 登录，再在 WebUI 点击“启动机器人”。
 - 自动检查在 WebUI 鉴权成功后异步执行，失败不会阻塞或打扰页面。GitHub Release 查询在 WebUI 进程内缓存 15 分钟；同一时刻的并发检查会共享一个在途任务，查询失败时也不会逐个重试外部请求。
diff --git a/docs/deployment.md b/docs/deployment.md
index 3dc85806..c654a65e 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -158,7 +158,7 @@ uv run Undefined-webui
 
 `SIGINT`（Ctrl+C）与 `SIGTERM` 都会触发同一套优雅停机流程：先停止 QQ、微信与普通 Runtime API 的新接入，等待已接受的入站处理和 API 请求收尾，停止史官 / memes worker，再由消息处理器排空 AI 队列并落盘历史。排空期间保留 OneBot 响应接收、微信发送和 Runtime 文件下载能力，回复完成后才关闭传输、AI 客户端、检索运行时与渲染资源。等待 worker 收尾期间模型队列保持可用，史官在向量写入后继续提交侧写模型请求也能完成；消息处理器收尾时新落盘的认知任务留待下次启动处理。容器、systemd、supervisor 等默认以 `SIGTERM` 停止进程；其强制终止等待时间应覆盖实际模型和下载收尾耗时。请避免使用 `SIGKILL`（`docker kill -s KILL`），否则会跳过全部落盘清理。
 
-WebUI 停止 Bot 默认等待优雅收尾自然完成；如需设置强制终止期限，配置 `[webui].stop_timeout_seconds` 为正整数秒，`0` 表示不设置期限。它不改变 Docker 或 systemd 自己的停止期限，请同时给外层进程管理器留足时间。
+WebUI 停止 Bot 默认等待优雅收尾自然完成；停止按钮、WebUI 关停和更新前停止都使用 `[webui].stop_timeout_seconds`，不会另以固定的 5 或 8 秒截断。正整数表示强制终止期限，`0` 表示不设置期限。停止请求被取消时也会先收敛子进程清理。它不改变 Docker 或 systemd 自己的停止期限，请同时给外层进程管理器留足时间。
 
 #### 自动启动选项
 
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index d39b67a7..75affba4 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -54,7 +54,7 @@ WebUI 的主要页签如下。
 
 页面会自动刷新，也可手动触发。
 
-停止 Bot 时，WebUI 默认等待运行中的任务自然完成收尾；`[webui].stop_timeout_seconds` 默认为 `0`，设置为正整数后才会在对应秒数超时后强制终止。热更新后的值从下一次停止操作生效。
+停止 Bot 时，WebUI 默认等待运行中的任务自然完成收尾；`[webui].stop_timeout_seconds` 默认为 `0`，设置为正整数后才会在对应秒数超时后强制终止。停止按钮、关闭 WebUI 与更新前停止共用此规则，取消请求也会等子进程清理完成。热更新后的值从下一次停止操作生效。
 
 ### 配置管理（Config）
 
diff --git a/src/Undefined/webui/app.py b/src/Undefined/webui/app.py
index 2bc897a3..cd2f2a1a 100644
--- a/src/Undefined/webui/app.py
+++ b/src/Undefined/webui/app.py
@@ -281,10 +281,9 @@ async def on_shutdown(app: web.Application) -> None:
         logger.info("[WebUI] 正在关闭，无运行中的机器人进程")
         return
     logger.info("[WebUI] 正在关闭，准备停止机器人进程...")
-    try:
-        await asyncio.wait_for(bot.stop(), timeout=5)
-    except asyncio.TimeoutError:
-        logger.warning("[WebUI] 关闭超时：机器人进程停止失败")
+    result = await bot.stop()
+    if result.get("running"):
+        logger.warning("[WebUI] 关闭时机器人进程仍未退出")
 
 
 async def on_cleanup(app: web.Application) -> None:
diff --git a/src/Undefined/webui/core.py b/src/Undefined/webui/core.py
index bd09d447..aa7f9da9 100644
--- a/src/Undefined/webui/core.py
+++ b/src/Undefined/webui/core.py
@@ -10,6 +10,7 @@
 import secrets
 from typing import Any
 from Undefined.config.webui_settings import DEFAULT_WEBUI_STOP_TIMEOUT_SECONDS
+from Undefined.utils.io import run_cancellation_safe
 
 logger = logging.getLogger(__name__)
 
@@ -193,6 +194,11 @@ async def start(self) -> dict[str, Any]:
             return self.status()
 
     async def stop(self) -> dict[str, Any]:
+        # 客户端断开/重复取消不能留下未收敛的子进程或提前释放生命周期锁。
+        return await run_cancellation_safe(self._stop())
+
+    async def _stop(self) -> dict[str, Any]:
+        watch_task: asyncio.Task[None] | None = None
         async with self._lock:
             if not self._process or self._process.returncode is not None:
                 self._process = None
@@ -244,17 +250,21 @@ async def stop(self) -> dict[str, Any]:
             except Exception as e:
                 logger.error(f"停止进程出错: {e}")
             finally:
-                if self._watch_task and not self._watch_task.done():
-                    self._watch_task.cancel()
-                    try:
-                        await self._watch_task
-                    except asyncio.CancelledError:
-                        pass
-                self._watch_task = None
-                self._process = None
-                self._started_at = None
+                if process.returncode is not None:
+                    watch_task = self._watch_task
+                    self._watch_task = None
+                    self._process = None
+                    self._started_at = None
 
-            return self.status()
+        # watcher 的 finally 也会取得 _lock，必须在释放锁后等待。
+        if watch_task is not None:
+            if not watch_task.done():
+                watch_task.cancel()
+            try:
+                await watch_task
+            except asyncio.CancelledError:
+                pass
+        return self.status()
 
     async def _watch_process(self, process: asyncio.subprocess.Process) -> None:
         try:
diff --git a/src/Undefined/webui/routes/_bot.py b/src/Undefined/webui/routes/_bot.py
index d3bc133f..9ca2888c 100644
--- a/src/Undefined/webui/routes/_bot.py
+++ b/src/Undefined/webui/routes/_bot.py
@@ -380,11 +380,11 @@ async def update_restart_handler(request: web.Request) -> Response:
     marker = get_pending_bot_autostart_marker(repo_root)
     if was_running:
         try:
-            await asyncio.wait_for(bot.stop(), timeout=8)
-        except asyncio.TimeoutError:
-            return web.json_response(
-                {"success": False, "error": "bot_stop_timeout"}, status=500
-            )
+            stopped = await bot.stop()
+            if stopped.get("running"):
+                return web.json_response(
+                    {"success": False, "error": "bot_stop_failed"}, status=500
+                )
         except Exception:
             logger.warning("[WebUI][更新] 停止 Bot 进程失败", exc_info=True)
             return web.json_response(
diff --git a/tests/test_webui_process_shutdown.py b/tests/test_webui_process_shutdown.py
index deb8156c..52aba7ea 100644
--- a/tests/test_webui_process_shutdown.py
+++ b/tests/test_webui_process_shutdown.py
@@ -4,19 +4,25 @@
 import os
 from pathlib import Path
 import sys
+from typing import cast
 
 import pytest
+from aiohttp import web
 
 from Undefined.webui import core
+from Undefined.webui.app import on_shutdown
+from Undefined.webui.routes._shared import BOT_APP_KEY
 
 
 @pytest.mark.asyncio
 @pytest.mark.skipif(os.name == "nt", reason="POSIX SIGTERM child fixture")
 @pytest.mark.parametrize("force_timeout", [None, 0.05])
+@pytest.mark.parametrize("entrypoint", ["controller", "shutdown"])
 async def test_stop_honors_graceful_completion_and_configured_deadline(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     force_timeout: float | None,
+    entrypoint: str,
 ) -> None:
     child = tmp_path / "child.py"
     child.write_text(
@@ -49,7 +55,13 @@ async def ready() -> None:
 
     try:
         await asyncio.wait_for(ready(), 3)
-        status = await asyncio.wait_for(controller.stop(), 8)
+        if entrypoint == "shutdown":
+            await asyncio.wait_for(
+                on_shutdown(cast(web.Application, {BOT_APP_KEY: controller})), 8
+            )
+            status = controller.status()
+        else:
+            status = await asyncio.wait_for(controller.stop(), 8)
         assert not status["running"]
         assert (tmp_path / "started").exists()
         assert (tmp_path / "finished").exists() is (force_timeout is None)
@@ -58,3 +70,62 @@ async def ready() -> None:
         if process.returncode is None:
             process.kill()
             await process.wait()
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(os.name == "nt", reason="POSIX SIGTERM child fixture")
+async def test_repeated_stop_cancellation_waits_for_process_and_releases_lock(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    child = tmp_path / "child.py"
+    child.write_text(
+        "import asyncio, signal\n"
+        "from pathlib import Path\n"
+        "async def main() -> None:\n"
+        "    root = Path(__file__).parent\n"
+        "    stop = asyncio.Event()\n"
+        "    asyncio.get_running_loop().add_signal_handler(signal.SIGTERM, stop.set)\n"
+        "    (root / 'ready').touch()\n"
+        "    await stop.wait()\n"
+        "    (root / 'stopping').touch()\n"
+        "    while not (root / 'release').exists():\n"
+        "        await asyncio.sleep(0.01)\n"
+        "    (root / 'finished').touch()\n"
+        "asyncio.run(main())\n"
+    )
+    monkeypatch.setattr(core, "BOT_COMMAND", (sys.executable, str(child)))
+    controller = core.BotProcessController()
+    await controller.start()
+    process = controller._process
+    assert process is not None
+
+    async def wait_for_file(name: str) -> None:
+        while not (tmp_path / name).exists():
+            await asyncio.sleep(0.01)
+
+    stop_task: asyncio.Task[dict[str, object]] | None = None
+    try:
+        await asyncio.wait_for(wait_for_file("ready"), 3)
+        stop_task = asyncio.create_task(controller.stop())
+        await asyncio.wait_for(wait_for_file("stopping"), 3)
+        for _ in range(2):
+            stop_task.cancel()
+            await asyncio.sleep(0)
+        assert not stop_task.done()
+        assert controller.status()["running"]
+        assert controller._lock.locked()
+        (tmp_path / "release").touch()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(stop_task, 3)
+        assert (tmp_path / "finished").exists()
+        assert process.returncode == 0
+        assert not controller._lock.locked()
+        assert controller._watch_task is None
+        assert not (await asyncio.wait_for(controller.stop(), 1))["running"]
+    finally:
+        (tmp_path / "release").touch()
+        if process.returncode is None:
+            process.kill()
+            await process.wait()
+        if stop_task is not None:
+            await asyncio.gather(stop_task, return_exceptions=True)
diff --git a/tests/test_webui_update.py b/tests/test_webui_update.py
index a82716a6..5627ee49 100644
--- a/tests/test_webui_update.py
+++ b/tests/test_webui_update.py
@@ -2,6 +2,8 @@
 
 import asyncio
 import json
+import os
+import sys
 from collections.abc import Iterator
 from pathlib import Path
 from types import SimpleNamespace
@@ -19,6 +21,7 @@
     apply_git_release_update,
 )
 from Undefined.webui.routes import _bot
+from Undefined.webui import core
 from Undefined.webui.routes._shared import BOT_APP_KEY, SETTINGS_APP_KEY
 
 
@@ -63,6 +66,81 @@ def _release(tag: str = "v3.8.0") -> GitHubReleaseInfo:
     )
 
 
+@pytest.mark.asyncio
+@pytest.mark.skipif(os.name == "nt", reason="POSIX SIGTERM child fixture")
+async def test_update_waits_for_bot_shutdown_beyond_old_outer_timeout(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    child = tmp_path / "child.py"
+    child.write_text(
+        "import asyncio, signal\n"
+        "from pathlib import Path\n"
+        "async def main() -> None:\n"
+        "    root = Path(__file__).parent\n"
+        "    stop = asyncio.Event()\n"
+        "    asyncio.get_running_loop().add_signal_handler(signal.SIGTERM, stop.set)\n"
+        "    (root / 'ready').touch()\n"
+        "    await stop.wait()\n"
+        "    await asyncio.sleep(9)\n"
+        "    (root / 'finished').touch()\n"
+        "asyncio.run(main())\n"
+    )
+    monkeypatch.setattr(core, "BOT_COMMAND", (sys.executable, str(child)))
+    controller = core.BotProcessController()
+    monkeypatch.setattr(_bot, "check_auth", lambda _request: True)
+    monkeypatch.setattr(
+        _bot,
+        "_load_release_payload",
+        AsyncMock(
+            return_value=({"latest_version": "v3.8.0", "update_available": True}, None)
+        ),
+    )
+    monkeypatch.setattr(
+        _bot,
+        "_check_git_eligibility",
+        AsyncMock(
+            return_value=GitUpdateResult(
+                eligible=True, updated=False, repo_root=tmp_path, reason="eligible"
+            )
+        ),
+    )
+
+    def apply_after_shutdown(*_args: object, **_kwargs: object) -> GitUpdateResult:
+        assert (tmp_path / "finished").exists()
+        assert not controller.status()["running"]
+        return GitUpdateResult(
+            eligible=True, updated=True, repo_root=tmp_path, reason="updated"
+        )
+
+    monkeypatch.setattr(_bot, "apply_git_release_update", apply_after_shutdown)
+    restart = MagicMock()
+    monkeypatch.setattr(_bot, "restart_process", restart)
+    await controller.start()
+    process = controller._process
+    assert process is not None
+
+    async def ready() -> None:
+        while not (tmp_path / "ready").exists():
+            await asyncio.sleep(0.01)
+
+    try:
+        await asyncio.wait_for(ready(), 3)
+        request = cast(
+            web.Request,
+            _DummyRequest(app={BOT_APP_KEY: controller}, can_read_body=False),
+        )
+        response = await asyncio.wait_for(_bot.update_restart_handler(request), 12)
+        assert _payload(response)["will_restart"] is True
+        assert process.returncode == 0
+        assert _bot._release_restart_task is not None
+        await _bot._release_restart_task
+        restart.assert_called_once()
+    finally:
+        if process.returncode is None:
+            process.kill()
+            await process.wait()
+
+
 @pytest.fixture(autouse=True)
 def _isolate_release_cache() -> Iterator[None]:
     _bot._reset_release_cache()
@@ -389,7 +467,7 @@ async def track_marker_write(path: Path, content: str) -> None:
 
     bot = MagicMock()
     bot.status.return_value = {"running": True}
-    bot.stop = AsyncMock()
+    bot.stop = AsyncMock(return_value={"running": False})
     bot.start = AsyncMock()
     policy = GitUpdatePolicy(update_timeout_seconds=0.01)
     monkeypatch.setattr(_bot, "GitUpdatePolicy", lambda: policy)

From ce9cb82d27c02676d719cb8d2fd3bc4507342b6d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:34:41 +0800
Subject: [PATCH 075/121] fix(memes): make pruning and failed deletion safely
 retryable

---
 docs/memes.md                  |   2 +
 src/Undefined/memes/service.py |  85 ++++++++-------
 tests/test_meme_lifecycle.py   | 190 +++++++++++++++++++++++++++++++++
 3 files changed, 236 insertions(+), 41 deletions(-)

diff --git a/docs/memes.md b/docs/memes.md
index 96f28d68..8247ddc4 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -59,4 +59,6 @@ gif_analysis_frames = 6         # GIF 的抽帧数量
 
 编辑、停用或删除会使全局 UID 附件缓存失效。正在读取旧记录的解析线程会重新核对失效代次，重新读取当前状态，不会把停用前的记录重新缓存。
 
+容量清理复用人工删除的内容锁和修订校验；候选列出后才置顶或编辑的条目会跳过，多个清理任务串行检查当前容量。删除会先完成向量、原图、预览与 GIF 临时帧清理，最后移除 SQLite 记录。索引或文件删除失败时，元数据仍保留并计入容量，可在故障恢复后重试删除；此前已清理的文件允许再次删除。
+
 * Management API 完整接口参阅 [Management API — Runtime 代理](management-api.md#6-runtime-代理)，Runtime API 直连接口参阅 [Runtime API — 表情包库](openapi.md#表情包库)。
diff --git a/src/Undefined/memes/service.py b/src/Undefined/memes/service.py
index 9eb87554..c899f5be 100644
--- a/src/Undefined/memes/service.py
+++ b/src/Undefined/memes/service.py
@@ -71,6 +71,7 @@ def __init__(
         # Serialize same-content ingest and final metadata/index mutations.
         self._ingest_digest_locks: dict[str, IngestDigestLockEntry] = {}
         self._ingest_digest_locks_guard = asyncio.Lock()
+        self._prune_lock = asyncio.Lock()
         self._global_image_cache: dict[str, AttachmentRecord] = {}
         self._global_image_cache_lock = threading.Lock()
         self._global_image_cache_generation = 0
@@ -320,42 +321,56 @@ async def delete_meme(
 
         async def commit() -> bool:
             current = await self._store.get(uid)
-            if current is None or current.generation != record.generation:
-                return False
-            deleted = await self._store.delete(
-                uid, expected_record=expected_record or current
-            )
-            if deleted is None:
+            if (
+                current is None
+                or current.generation != record.generation
+                or current.content_sha256 != record.content_sha256
+                or (
+                    expected_record is not None
+                    and current.revision != expected_record.revision
+                )
+            ):
                 return False
-            self._invalidate_global_image_cache(uid)
+            # 保留可重试的 SQL 记录和容量统计，直到所有外部收尾成功。
             await self._vector_store.delete(uid)
             await asyncio.to_thread(
-                self._delete_file_if_exists, Path(deleted.blob_path)
+                self._delete_file_if_exists, Path(current.blob_path), strict=True
             )
-            if deleted.preview_path and deleted.preview_path != deleted.blob_path:
+            if current.preview_path and current.preview_path != current.blob_path:
                 await asyncio.to_thread(
                     self._delete_file_if_exists,
-                    Path(deleted.preview_path),
+                    Path(current.preview_path),
+                    strict=True,
                 )
-            await asyncio.to_thread(self._cleanup_gif_frame_files, uid)
+            await asyncio.to_thread(self._cleanup_gif_frame_files, uid, strict=True)
+            deleted = await self._store.delete(
+                uid, expected_record=expected_record or current
+            )
+            if deleted is None:
+                return False
+            self._invalidate_global_image_cache(uid)
             return True
 
         async with self._meme_mutation_lock(record.content_sha256):
             return await run_cancellation_safe(commit())
 
-    def _delete_file_if_exists(self, path: Path) -> None:
+    def _delete_file_if_exists(self, path: Path, *, strict: bool = False) -> None:
         try:
             path.unlink(missing_ok=True)
         except OSError:
+            if strict:
+                raise
             logger.debug("[memes] 删除文件失败: path=%s", path, exc_info=True)
 
-    def _cleanup_gif_frame_files(self, uid: str) -> None:
+    def _cleanup_gif_frame_files(self, uid: str, *, strict: bool = False) -> None:
         """清理 GIF 多帧分析产生的临时帧文件 ({uid}_f{i}.png)。"""
         preview_dir = self._preview_dir()
         for frame_file in preview_dir.glob(f"{uid}_f*.png"):
             try:
                 frame_file.unlink(missing_ok=True)
             except OSError:
+                if strict:
+                    raise
                 logger.debug(
                     "[memes] 删除帧文件失败: path=%s", frame_file, exc_info=True
                 )
@@ -1103,37 +1118,25 @@ async def _generate_uid(self) -> str:
             return candidate
 
     async def _prune_if_needed(self) -> None:
-        stats = await self._store.stats()
-        cfg = self._cfg()
-        total_count = int(stats.get("total_count", 0))
-        total_bytes = int(stats.get("total_bytes", 0))
-        if total_count <= int(cfg.max_items) and total_bytes <= int(
-            cfg.max_total_bytes
-        ):
-            return
-        candidates = await self._store.list_prune_candidates()
-        for candidate in candidates:
-            if candidate.pinned:
-                continue
+        async with self._prune_lock:
+            cfg = self._cfg()
+            stats = await self._store.stats()
+            total_count = int(stats.get("total_count", 0))
+            total_bytes = int(stats.get("total_bytes", 0))
             if total_count <= int(cfg.max_items) and total_bytes <= int(
                 cfg.max_total_bytes
             ):
-                break
-            deleted = await self._store.delete(candidate.uid)
-            if deleted is None:
-                continue
-            self._invalidate_global_image_cache(candidate.uid)
-            await self._vector_store.delete(candidate.uid)
-            await asyncio.to_thread(
-                self._delete_file_if_exists, Path(deleted.blob_path)
-            )
-            if deleted.preview_path and deleted.preview_path != deleted.blob_path:
-                await asyncio.to_thread(
-                    self._delete_file_if_exists,
-                    Path(deleted.preview_path),
-                )
-            total_count -= 1
-            total_bytes -= int(deleted.file_size)
+                return
+            candidates = await self._store.list_prune_candidates()
+            for candidate in candidates:
+                if candidate.pinned:
+                    continue
+                stats = await self._store.stats()
+                if int(stats.get("total_count", 0)) <= int(cfg.max_items) and int(
+                    stats.get("total_bytes", 0)
+                ) <= int(cfg.max_total_bytes):
+                    break
+                await self.delete_meme(candidate.uid, expected_record=candidate)
 
     async def blob_path_for_uid(
         self, uid: str, *, preview: bool = False
diff --git a/tests/test_meme_lifecycle.py b/tests/test_meme_lifecycle.py
index 7611039d..2c268e37 100644
--- a/tests/test_meme_lifecycle.py
+++ b/tests/test_meme_lifecycle.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from dataclasses import replace
 from pathlib import Path
 import threading
 from types import SimpleNamespace
@@ -319,3 +320,192 @@ async def test_delivery_error_does_not_increment_meme_usage(tmp_path: Path) -> N
         )
     assert await store.get(record.uid) == record
     assert vectors.records[record.uid] == record
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mutation", ["pin", "edit", "delete_other"])
+@pytest.mark.parametrize("parallel", [False, True])
+async def test_prune_skips_candidate_changed_after_snapshot(
+    tmp_path: Path, mutation: str, parallel: bool
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _SnapshotStore(MemeStore):
+        async def list_prune_candidates(self) -> list[MemeRecord]:
+            records = await super().list_prune_candidates()
+            entered.set()
+            await release.wait()
+            return records
+
+    service, store, vectors, record = await _fixture(
+        tmp_path, store=_SnapshotStore(tmp_path / "memes.sqlite3")
+    )
+    other_blob = tmp_path / "other.png"
+    other_blob.write_bytes(b"second isolated meme")
+    other = await store.upsert_record(
+        replace(
+            record,
+            uid="pic_other",
+            content_sha256="other content",
+            blob_path=str(other_blob),
+            preview_path=str(other_blob),
+            file_size=other_blob.stat().st_size,
+            use_count=1,
+            generation="",
+        )
+    )
+    await vectors.upsert(other)
+    pruning = asyncio.create_task(service._prune_if_needed())
+    prunings = [pruning]
+    try:
+        await asyncio.wait_for(entered.wait(), timeout=3)
+        if parallel:
+            prunings.append(asyncio.create_task(service._prune_if_needed()))
+        if mutation == "delete_other":
+            assert await service.delete_meme(other.uid)
+        else:
+            assert await service.update_meme(
+                record.uid,
+                pinned=True if mutation == "pin" else None,
+                manual_description="edited description" if mutation == "edit" else None,
+            )
+        protected = await store.get(record.uid)
+        release.set()
+        await asyncio.wait_for(asyncio.gather(*prunings), timeout=3)
+        assert await store.get(record.uid) == protected
+        assert Path(record.blob_path).is_file()
+        assert vectors.records[record.uid] == protected
+        assert await store.get(other.uid) is None
+        assert not other_blob.exists()
+        assert (await store.stats())["total_count"] == 1
+        assert service._ingest_digest_locks == {}
+    finally:
+        release.set()
+        await asyncio.gather(*prunings, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["index", "blob", "preview", "frames"])
+async def test_failed_delete_keeps_metadata_and_allows_cleanup_retry(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, failure: str
+) -> None:
+    armed = False
+
+    class _FailingVectors(_Vectors):
+        async def delete(self, uid: str) -> None:
+            if armed and failure == "index":
+                raise RuntimeError("isolated vector delete failure")
+            await super().delete(uid)
+
+    service, store, vectors, record = await _fixture(
+        tmp_path, vectors=_FailingVectors()
+    )
+    preview = tmp_path / "preview.png"
+    preview.write_bytes(b"isolated preview")
+    record = await store.upsert_record(replace(record, preview_path=str(preview)))
+    await vectors.upsert(record)
+    frames = tmp_path / "previews"
+    frames.mkdir()
+    frame = frames / f"{record.uid}_f0.png"
+    frame.write_bytes(b"isolated frame")
+    target = {
+        "blob": Path(record.blob_path),
+        "preview": preview,
+        "frames": frame,
+    }.get(failure)
+    original_unlink = Path.unlink
+
+    def failing_unlink(self: Path, missing_ok: bool = False) -> None:
+        if armed and self == target:
+            raise OSError("isolated file delete failure")
+        original_unlink(self, missing_ok=missing_ok)
+
+    monkeypatch.setattr(Path, "unlink", failing_unlink)
+    armed = True
+    error_type = RuntimeError if failure == "index" else OSError
+    with pytest.raises(error_type, match="isolated .* delete failure"):
+        await service.delete_meme(record.uid)
+    assert await store.get(record.uid) == record
+    assert (await store.stats())["total_count"] == 1
+    assert (await store.stats())["total_bytes"] == record.file_size
+    if failure == "index":
+        assert Path(record.blob_path).is_file()
+        assert preview.is_file()
+        assert frame.is_file()
+        assert vectors.records[record.uid] == record
+    else:
+        assert target is not None and target.is_file()
+
+    armed = False
+    assert await service.delete_meme(record.uid)
+    assert await store.get(record.uid) is None
+    assert record.uid not in vectors.records
+    assert not Path(record.blob_path).exists()
+    assert not preview.exists()
+    assert not frame.exists()
+    assert (await store.stats())["total_count"] == 0
+    assert service._ingest_digest_locks == {}
+
+
+@pytest.mark.asyncio
+async def test_stale_conditional_delete_does_not_touch_index_or_files(
+    tmp_path: Path,
+) -> None:
+    service, store, vectors, record = await _fixture(tmp_path)
+    assert await service.update_meme(
+        record.uid, manual_description="latest description"
+    )
+    current = await store.get(record.uid)
+
+    assert not await service.delete_meme(record.uid, expected_record=record)
+
+    assert await store.get(record.uid) == current
+    assert vectors.records[record.uid] == current
+    assert Path(record.blob_path).is_file()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_delete_finishes_cleanup_before_following_edit(
+    tmp_path: Path,
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _DelayedVectors(_Vectors):
+        async def delete(self, uid: str) -> None:
+            entered.set()
+            await release.wait()
+            await super().delete(uid)
+
+    service, store, vectors, record = await _fixture(
+        tmp_path, vectors=_DelayedVectors()
+    )
+    deleting = asyncio.create_task(service.delete_meme(record.uid))
+    editing: asyncio.Task[dict[str, Any] | None] | None = None
+    try:
+        await asyncio.wait_for(entered.wait(), timeout=3)
+        deleting.cancel()
+        editing = asyncio.create_task(
+            service.update_meme(record.uid, manual_description="must not restore")
+        )
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        deleting.cancel()
+        assert not deleting.done()
+        assert not editing.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(deleting, timeout=3)
+        assert await asyncio.wait_for(editing, timeout=3) is None
+        assert await store.get(record.uid) is None
+        assert record.uid not in vectors.records
+        assert not Path(record.blob_path).exists()
+        assert service._ingest_digest_locks == {}
+    finally:
+        release.set()
+        await asyncio.gather(
+            deleting,
+            *([editing] if editing is not None else []),
+            return_exceptions=True,
+        )

From 864951df4222a96a0cfda940e415f7b55ba082ca Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:34:44 +0800
Subject: [PATCH 076/121] fix(weixin): serialize account changes with client
 lifecycle

---
 docs/wechat-ilink.md            |   2 +
 src/Undefined/weixin/service.py |  62 +++++-----
 tests/test_weixin_service.py    | 193 ++++++++++++++++++++++++++++++++
 3 files changed, 230 insertions(+), 27 deletions(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 6f74edc8..842e2b55 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -86,6 +86,8 @@ audit_max_records = 1000
 
 若目标 QQ 是管理员或超级管理员，第一次提交只返回权限继承警告和短时确认 token；必须再次明确确认才会创建二维码登录。确认、登录、启停、改绑和解绑都会写入审计记录。
 
+帐号启停、改绑、扫码绑定完成和解绑共用生命周期串行边界。解绑先完成时，排队中的启用或改绑请求会返回帐号不存在，不会重新建立已删除帐号的连接；同别名重新绑定使用新扫码凭据。服务关闭后不会再接受启用、改绑或绑定完成操作。
+
 ## 隔离与访问控制
 
 iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 ID 或来源 ID 不匹配的消息，Undefined 会在 AI、命令、管线和历史处理之前隔离：
diff --git a/src/Undefined/weixin/service.py b/src/Undefined/weixin/service.py
index c757a090..b6050c84 100644
--- a/src/Undefined/weixin/service.py
+++ b/src/Undefined/weixin/service.py
@@ -495,13 +495,15 @@ async def set_account_enabled(
         *,
         actor: str = "management-api",
     ) -> dict[str, Any]:
-        try:
-            account = await self.store.set_account_enabled(alias, enabled)
-        except KeyError as exc:
-            raise WeixinNotFoundError(f"帐号 {alias} 不存在") from exc
-        except ValueError as exc:
-            raise WeixinServiceError(str(exc)) from exc
         async with self._lifecycle_lock:
+            if self._closed:
+                raise WeixinServiceError("微信服务已关闭")
+            try:
+                account = await self.store.set_account_enabled(alias, enabled)
+            except KeyError as exc:
+                raise WeixinNotFoundError(f"帐号 {alias} 不存在") from exc
+            except ValueError as exc:
+                raise WeixinServiceError(str(exc)) from exc
             if enabled and self._running and self.weixin_config.enabled:
                 await self._start_account_locked(account)
             elif not enabled:
@@ -550,20 +552,23 @@ async def rebind_account(
     ) -> dict[str, Any]:
         normalized = self._normalize_alias(alias)
         self._validate_qq_id(qq_id)
-        existing = await self.store.get_account(normalized)
-        if existing is None:
-            raise WeixinNotFoundError(f"帐号 {normalized} 不存在")
-        await self._require_privileged_confirmation(
-            operation="rebind",
-            alias=normalized,
-            qq_id=qq_id,
-            confirmation_token=confirmation_token,
-            actor=actor,
-        )
-        try:
-            updated = await self.store.rebind_account(normalized, qq_id)
-        except ValueError as exc:
-            raise WeixinConflictError(str(exc)) from exc
+        async with self._lifecycle_lock:
+            if self._closed:
+                raise WeixinServiceError("微信服务已关闭")
+            existing = await self.store.get_account(normalized)
+            if existing is None:
+                raise WeixinNotFoundError(f"帐号 {normalized} 不存在")
+            await self._require_privileged_confirmation(
+                operation="rebind",
+                alias=normalized,
+                qq_id=qq_id,
+                confirmation_token=confirmation_token,
+                actor=actor,
+            )
+            try:
+                updated = await self.store.rebind_account(normalized, qq_id)
+            except ValueError as exc:
+                raise WeixinConflictError(str(exc)) from exc
         await self.store.append_audit(
             "account_rebound",
             actor=actor,
@@ -736,18 +741,21 @@ async def _complete_login(
             created_at=now,
             updated_at=now,
         )
-        try:
-            await self.store.save_account(account)
-        except ValueError as exc:
-            raise WeixinConflictError(str(exc)) from exc
+        async with self._lifecycle_lock:
+            self._ensure_available()
+            if await self.store.get_account(account.alias) is not None:
+                raise WeixinConflictError(f"帐号别名 {account.alias} 已存在")
+            try:
+                await self.store.save_account(account)
+            except ValueError as exc:
+                raise WeixinConflictError(str(exc)) from exc
+            if self._running and self.weixin_config.enabled:
+                await self._start_account_locked(account)
         await self.store.append_audit(
             "account_bound",
             actor=actor,
             details={"alias": account.alias, "qq_id": account.qq_id},
         )
-        async with self._lifecycle_lock:
-            if self._running and self.weixin_config.enabled:
-                await self._start_account_locked(account)
         return account
 
     async def _start_account_locked(self, account: WeixinAccount) -> None:
diff --git a/tests/test_weixin_service.py b/tests/test_weixin_service.py
index 26999d12..8ee8896e 100644
--- a/tests/test_weixin_service.py
+++ b/tests/test_weixin_service.py
@@ -35,6 +35,7 @@
 from Undefined.weixin.service import (
     WeixinClientProtocol,
     WeixinConfirmationRequired,
+    WeixinNotFoundError,
     WeixinService,
     WeixinServiceError,
 )
@@ -798,6 +799,198 @@ async def test_remove_account_purges_sdk_runtime_state(tmp_path: Path) -> None:
         await service.stop()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("first_operation", ["remove", "enable"])
+async def test_account_remove_and_enable_share_lifecycle_boundary(
+    tmp_path: Path, first_operation: str
+) -> None:
+    config = _config(tmp_path)
+    store = WeixinStore(config.weixin)
+    await store.save_account(_account())
+    clients: list[FakeClient] = []
+
+    def factory(
+        account: WeixinAccount,
+        state: UndefinedIlinkStateStore,
+        options: ClientOptions,
+    ) -> WeixinClientProtocol:
+        client = FakeClient()
+        clients.append(client)
+        return client
+
+    login_manager = FakeLoginManager()
+    service = WeixinService(
+        config,
+        store=store,
+        login_manager=cast(QrLoginManager, login_manager),
+        client_factory=factory,
+    )
+    await service.start()
+    await asyncio.wait_for(clients[0].run_started.wait(), timeout=1)
+    await store._lock.acquire()
+    try:
+        if first_operation == "remove":
+            removal = asyncio.create_task(service.remove_account("primary"))
+            await asyncio.sleep(0)
+            enabling = asyncio.create_task(service.set_account_enabled("primary", True))
+        else:
+            enabling = asyncio.create_task(service.set_account_enabled("primary", True))
+            await asyncio.sleep(0)
+            removal = asyncio.create_task(service.remove_account("primary"))
+        await asyncio.sleep(0)
+        store._lock.release()
+        assert await asyncio.wait_for(removal, timeout=2) is True
+        if first_operation == "remove":
+            with pytest.raises(WeixinNotFoundError):
+                await asyncio.wait_for(enabling, timeout=2)
+        else:
+            assert (await asyncio.wait_for(enabling, timeout=2))["alias"] == "primary"
+        assert await store.get_account("primary") is None
+        assert service._runtimes == {}
+        assert len(clients) == 1
+        assert clients[0].closed
+
+        # 同别名重新绑定只能使用新扫码凭据，不能复活已删除的客户端。
+        started = await service.start_login(alias="primary", qq_id=10002)
+        credentials = WeixinCredentials(
+            "replacement-account",
+            "replacement-secret",
+            "https://ilink.example.test",
+            "peer-2",
+        )
+        login_manager.poll_result = QrPollResult(
+            QrStatus.CONFIRMED, "confirmed", credentials
+        )
+        result = await service.poll_login(started.session_id)
+        assert result.account is not None
+        assert len(clients) == 2
+        persisted = await store.get_account("primary")
+        assert persisted is not None
+        assert persisted.credentials.account_id == "replacement-account"
+        assert persisted.qq_id == 10002
+        assert service._runtimes["primary"].client is clients[1]
+    finally:
+        if store._lock.locked():
+            store._lock.release()
+        await service.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", ["remove", "stop"])
+@pytest.mark.parametrize("account_operation", ["enable", "rebind"])
+async def test_delayed_account_close_cannot_be_followed_by_stale_enable(
+    tmp_path: Path, operation: str, account_operation: str
+) -> None:
+    config = _config(tmp_path)
+    store = WeixinStore(config.weixin)
+    account = _account()
+    await store.save_account(account)
+    close_entered = asyncio.Event()
+    release_close = asyncio.Event()
+
+    class DelayedCloseClient(FakeClient):
+        async def aclose(self) -> None:
+            close_entered.set()
+            await release_close.wait()
+            await super().aclose()
+
+    client = DelayedCloseClient()
+
+    def factory(
+        current: WeixinAccount,
+        state: UndefinedIlinkStateStore,
+        options: ClientOptions,
+    ) -> WeixinClientProtocol:
+        assert current.credentials.account_id == account.credentials.account_id
+        return client
+
+    service = WeixinService(
+        config,
+        store=store,
+        login_manager=cast(QrLoginManager, FakeLoginManager()),
+        client_factory=factory,
+    )
+    await service.start()
+    await asyncio.wait_for(client.run_started.wait(), timeout=1)
+    closing = asyncio.create_task(
+        service.remove_account("primary") if operation == "remove" else service.stop()
+    )
+    try:
+        await asyncio.wait_for(close_entered.wait(), timeout=1)
+        enabling = asyncio.create_task(
+            service.set_account_enabled("primary", True)
+            if account_operation == "enable"
+            else service.rebind_account("primary", 10002)
+        )
+        await asyncio.sleep(0)
+        assert await store.get_account("primary") is account
+        release_close.set()
+        await asyncio.wait_for(closing, timeout=2)
+        error_type = (
+            WeixinNotFoundError if operation == "remove" else WeixinServiceError
+        )
+        with pytest.raises(error_type):
+            await asyncio.wait_for(enabling, timeout=2)
+        assert not service._runtimes
+        assert (await service.status())["accounts"] == (
+            [] if operation == "remove" else [account.to_public_dict()]
+        )
+    finally:
+        release_close.set()
+        await service.stop()
+
+
+@pytest.mark.asyncio
+async def test_login_completion_and_removal_cannot_leave_an_orphan_runtime(
+    tmp_path: Path,
+) -> None:
+    config = _config(tmp_path)
+    store = WeixinStore(config.weixin)
+    login_manager = FakeLoginManager()
+    clients: list[FakeClient] = []
+
+    def factory(
+        account: WeixinAccount,
+        state: UndefinedIlinkStateStore,
+        options: ClientOptions,
+    ) -> WeixinClientProtocol:
+        client = FakeClient()
+        clients.append(client)
+        return client
+
+    service = WeixinService(
+        config,
+        store=store,
+        login_manager=cast(QrLoginManager, login_manager),
+        client_factory=factory,
+    )
+    await service.start()
+    started = await service.start_login(alias="primary", qq_id=10001)
+    login_manager.poll_result = QrPollResult(
+        QrStatus.CONFIRMED, "confirmed", _account().credentials
+    )
+    await store._lock.acquire()
+    try:
+        completing = asyncio.create_task(service.poll_login(started.session_id))
+        await asyncio.sleep(0)
+        removal = asyncio.create_task(service.remove_account("primary"))
+        await asyncio.sleep(0)
+        store._lock.release()
+        completed, removed = await asyncio.wait_for(
+            asyncio.gather(completing, removal), timeout=2
+        )
+        assert completed.account is not None
+        assert removed is True
+        assert await store.get_account("primary") is None
+        assert not service._runtimes
+        assert len(clients) == 1
+        assert clients[0].closed
+    finally:
+        if store._lock.locked():
+            store._lock.release()
+        await service.stop()
+
+
 @pytest.mark.asyncio
 async def test_disabled_service_status_stays_stopped(tmp_path: Path) -> None:
     service = WeixinService(

From afaa7d8072d8c488294994ff5a0af49f2adb05c6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:37:43 +0800
Subject: [PATCH 077/121] fix(webui): isolate log streams and responses by view

---
 docs/webui-guide.md                       |  1 +
 src/Undefined/webui/static/js/log-view.js | 46 ++++++++++++---
 tests/test_webui_logs_frontend.py         | 68 +++++++++++++++++++++++
 3 files changed, 108 insertions(+), 7 deletions(-)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 75affba4..e952a82b 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -75,6 +75,7 @@ WebUI 的主要页签如下。
 ### 日志查看（Logs）
 
 - 支持 **Bot 日志** 和 **WebUI 日志** 切换。
+- 切换类别会关闭旧实时流；迟到的日志快照或文件列表不会覆盖当前类别与文件选择。
 - **实时流式推送**（SSE）：日志实时滚动到最新。
 - 可暂停 / 恢复流式推送，WebUI 默认显示最近 5000 行；接口支持 `lines` 参数，范围 1–10000（未传时默认 1000）。
 - 搜索、日志等级和时间范围均按完整日志记录过滤；关键词命中多行 JSON、参数或异常堆栈中的任意续行时，会保留并显示该记录的全部内容。
diff --git a/src/Undefined/webui/static/js/log-view.js b/src/Undefined/webui/static/js/log-view.js
index d147a5a1..40835bed 100644
--- a/src/Undefined/webui/static/js/log-view.js
+++ b/src/Undefined/webui/static/js/log-view.js
@@ -1,4 +1,8 @@
 const LOG_TAIL_LINES = 5000;
+let _logViewGeneration = 0;
+let _logFetchRequest = 0;
+const _logFilesRequests = new Map();
+const _logCurrentFiles = new Map();
 
 async function fetchLogs(force = false) {
     if (!force && !shouldFetch("logs")) return;
@@ -12,18 +16,29 @@ async function fetchLogs(force = false) {
         renderLogs();
         return;
     }
+    const type = state.logType;
+    const file = state.logFile;
+    const generation = _logViewGeneration;
+    const request = ++_logFetchRequest;
+    const isCurrent = () =>
+        request === _logFetchRequest &&
+        generation === _logViewGeneration &&
+        type === state.logType &&
+        file === state.logFile;
     try {
         const params = new URLSearchParams({
             lines: String(LOG_TAIL_LINES),
-            type: state.logType,
+            type,
         });
-        if (state.logFile) params.set("file", state.logFile);
+        if (file) params.set("file", file);
         const res = await api(`/api/logs?${params.toString()}`);
         const text = await res.text();
+        if (!isCurrent()) return;
         state.logsRaw = text || "";
         recordFetchSuccess("logs");
         renderLogs();
     } catch (e) {
+        if (!isCurrent()) return;
         recordFetchError("logs");
         if (!container) return;
         container.dataset.placeholder = "true";
@@ -167,11 +182,13 @@ function startLogStream() {
     const stream = new EventSource(`/api/logs/stream?${params.toString()}`);
     state.logStream = stream;
     stream.onmessage = (event) => {
+        if (state.logStream !== stream) return;
         state.logsRaw = event.data || "";
         recordFetchSuccess("logs");
         renderLogs();
     };
     stream.onerror = () => {
+        if (state.logStream !== stream) return;
         state.logStreamFailed = true;
         stopLogStream();
         if (state.logAutoRefresh && !state.logsPaused) startLogTimer();
@@ -240,25 +257,40 @@ async function copyLogsToClipboard() {
 }
 
 async function fetchLogFiles(force = false) {
-    if (state.logFiles[state.logType] && !force) {
+    const type = state.logType;
+    const generation = _logViewGeneration;
+    if (state.logFiles[type] && !force) {
+        state.logFileCurrent = _logCurrentFiles.get(type) || "";
         updateLogFileSelect();
         return;
     }
+    const request = (_logFilesRequests.get(type) || 0) + 1;
+    _logFilesRequests.set(type, request);
     try {
-        const res = await api(`/api/logs/files?type=${state.logType}`);
+        const res = await api(`/api/logs/files?type=${type}`);
         const data = await res.json();
-        state.logFiles[state.logType] = data.files || [];
+        if (_logFilesRequests.get(type) !== request) return;
+        state.logFiles[type] = data.files || [];
+        _logCurrentFiles.set(type, data.current || "");
+        if (state.logType !== type || generation !== _logViewGeneration) return;
         state.logFileCurrent = data.current || "";
         updateLogFileSelect();
-    } catch (e) {
-        state.logFiles[state.logType] = [];
+        updateLogRefreshState();
+    } catch (_error) {
+        if (_logFilesRequests.get(type) !== request) return;
+        state.logFiles[type] = [];
     }
 }
 
 function setLogType(type) {
     if (state.logType === type) return;
+    stopLogStream();
+    stopLogTimer();
+    _logViewGeneration += 1;
     state.logType = type;
     state.logFile = "";
+    state.logFileCurrent = "";
+    state.logStreamEnabled = type !== "all";
     state.logsRaw = "";
     state.logStreamFailed = false;
     updateLogTabs();
diff --git a/tests/test_webui_logs_frontend.py b/tests/test_webui_logs_frontend.py
index 906b0d22..e74ea11b 100644
--- a/tests/test_webui_logs_frontend.py
+++ b/tests/test_webui_logs_frontend.py
@@ -170,3 +170,71 @@ def test_log_view_delegates_all_filters_to_record_parser() -> None:
     assert "timeFrom:" in filter_fn
     assert "timeTo:" in filter_fn
     assert "const LOG_TAIL_LINES = 5000;" in source
+
+
+def test_log_category_switch_closes_old_stream_and_ignores_stale_responses() -> None:
+    from test_webui_runtime_chat_behavior import REPO_ROOT, _require_env
+
+    _require_env()
+    script = r"""
+const fs = require('node:fs');
+const vm = require('node:vm');
+const {JSDOM} = require(process.argv[1] + '/tests/frontend/node_modules/jsdom');
+const root = process.argv[1];
+const dom = new JSDOM(fs.readFileSync(root + '/src/Undefined/webui/templates/index.html', 'utf8'), {pretendToBeVisual: true});
+const state = {view: 'app', tab: 'logs', authenticated: true, logType: 'bot',
+  logFile: '', logFiles: {}, logFileCurrent: '', logsRaw: '', logStreamEnabled: true,
+  logAutoRefresh: true, logSearch: '', logLevel: 'all', logAtBottom: true};
+const pending = [];
+const streams = [];
+class EventSource {
+  constructor(url) { this.url = url; this.closed = false; streams.push(this); }
+  close() { this.closed = true; }
+}
+const context = vm.createContext({state, URLSearchParams, Map, EventSource,
+  window: {EventSource}, document: dom.window.document,
+  get: id => dom.window.document.getElementById(id), t: key => key,
+  escapeHtml: text => text, shouldFetch: () => true,
+  recordFetchSuccess: () => {}, recordFetchError: () => {},
+  startLogTimer: () => {}, stopLogTimer: () => {},
+  api: async path => new Promise(resolve => pending.push({path, resolve})),
+});
+vm.runInContext(fs.readFileSync(root + '/src/Undefined/webui/static/js/ui.js', 'utf8'), context);
+vm.runInContext(fs.readFileSync(root + '/src/Undefined/webui/static/js/log-view.js', 'utf8'), context);
+const tick = async () => { for(let i=0;i<5;i++) await new Promise(r=>setImmediate(r)); };
+const answer = (path, data) => pending.find(item => item.path === path).resolve({
+  json: async () => data, text: async () => data});
+(async () => {
+  vm.runInContext('startLogStream(); fetchLogs(true); setLogType("webui"); setLogType("bot")', context);
+  if (!streams[0].closed || !streams[1].closed || streams.length !== 3)
+    throw new Error('category switch must replace the stream');
+  streams[2].onmessage({data: 'CURRENT_BOT'});
+  answer('/api/logs/files?type=bot', {files: [{name:'bot.log',current:true}],current:'bot.log'});
+  await tick();
+  answer('/api/logs/files?type=webui', {files: [{name:'webui.log',current:true}],current:'webui.log'});
+  answer('/api/logs?lines=5000&type=bot', 'STALE_BOT_SNAPSHOT');
+  await tick();
+  const select = dom.window.document.getElementById('logFileSelect');
+  console.log(JSON.stringify({closed: streams.slice(0,2).map(item=>item.closed),
+    activeUrl: state.logStream.url, logsRaw:state.logsRaw,
+    options:Array.from(select.options).map(item=>item.value), selected:select.value,
+    botCache:state.logFiles.bot.map(item=>item.name),
+    webuiCache:state.logFiles.webui.map(item=>item.name)}));
+  dom.window.close();
+})().catch(error=>{console.error(error);process.exitCode=1;});
+"""
+    completed = subprocess.run(
+        ["node", "-e", script, str(REPO_ROOT)],
+        capture_output=True,
+        text=True,
+        timeout=15,
+        check=False,
+    )
+    assert completed.returncode == 0, completed.stderr
+    result = json.loads(completed.stdout.strip().splitlines()[-1])
+    assert result["closed"] == [True, True]
+    assert result["activeUrl"].endswith("type=bot")
+    assert result["logsRaw"] == "CURRENT_BOT"
+    assert result["options"] == result["botCache"] == ["bot.log"]
+    assert result["selected"] == "bot.log"
+    assert result["webuiCache"] == ["webui.log"]

From 92f0cbc0b64f78c303cb02c32dea7093fc6d6beb Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:37:49 +0800
Subject: [PATCH 078/121] fix(memes): preserve cancellation during indexing
 failures

---
 src/Undefined/memes/search.py |  4 +++
 tests/test_meme_lifecycle.py  | 55 +++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/src/Undefined/memes/search.py b/src/Undefined/memes/search.py
index 995f435d..662584b2 100644
--- a/src/Undefined/memes/search.py
+++ b/src/Undefined/memes/search.py
@@ -491,6 +491,10 @@ async def record_usage() -> None:
             logger.warning(
                 "[memes] 已发送但使用统计/索引更新失败: uid=%s", uid, exc_info=True
             )
+            task = asyncio.current_task()
+            if task is not None and task.cancelling():
+                # 收尾异常可能与外部取消同时发生，仍需保留任务的取消语义。
+                raise asyncio.CancelledError
         if sent_message_id is not None:
             return f"表情包已发送（message_id={sent_message_id}）"
         return "表情包已发送"
diff --git a/tests/test_meme_lifecycle.py b/tests/test_meme_lifecycle.py
index 2c268e37..5a506696 100644
--- a/tests/test_meme_lifecycle.py
+++ b/tests/test_meme_lifecycle.py
@@ -509,3 +509,58 @@ async def delete(self, uid: str) -> None:
             *([editing] if editing is not None else []),
             return_exceptions=True,
         )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["usage", "index"])
+async def test_cancelled_meme_usage_preserves_cancellation_when_cleanup_fails(
+    tmp_path: Path, failure: str
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _DelayedFailingStore(MemeStore):
+        async def increment_use(self, uid: str, used_at: str) -> MemeRecord | None:
+            if failure == "usage":
+                entered.set()
+                await release.wait()
+                raise RuntimeError("isolated usage failure after cancellation")
+            return await super().increment_use(uid, used_at)
+
+    class _DelayedFailingVectors(_Vectors):
+        async def upsert(self, record: MemeRecord) -> None:
+            if failure == "index" and record.use_count:
+                entered.set()
+                await release.wait()
+                raise RuntimeError("isolated index failure after cancellation")
+            await super().upsert(record)
+
+    service, store, _, record = await _fixture(
+        tmp_path,
+        store=_DelayedFailingStore(tmp_path / "memes.sqlite3"),
+        vectors=_DelayedFailingVectors(),
+    )
+    sender = SimpleNamespace(send_group_message=AsyncMock(return_value=1234))
+    sending = asyncio.create_task(
+        service.send_meme_by_uid(
+            record.uid, {"request_type": "group", "group_id": 123, "sender": sender}
+        )
+    )
+    try:
+        await asyncio.wait_for(entered.wait(), timeout=3)
+        sending.cancel()
+        await asyncio.sleep(0)
+        sending.cancel()
+        assert not sending.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(sending, timeout=3)
+        assert sending.cancelled()
+        sender.send_group_message.assert_awaited_once()
+        saved = await store.get(record.uid)
+        assert saved is not None
+        assert saved.use_count == (0 if failure == "usage" else 1)
+        assert service._ingest_digest_locks == {}
+    finally:
+        release.set()
+        await asyncio.gather(sending, return_exceptions=True)

From a3b54e9d869897a9e6c90fb5796dfaab484d197e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:38:25 +0800
Subject: [PATCH 079/121] fix(chat): expose complete timelines in job snapshots

---
 docs/management-api.md              |   3 +-
 docs/openapi.md                     |   1 +
 src/Undefined/api/routes/chat.py    |  12 ++-
 tests/test_runtime_api_chat_jobs.py | 111 ++++++++++++++++++++++++++++
 4 files changed, 124 insertions(+), 3 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index e296a08e..21865f99 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -280,7 +280,8 @@ GET /api/v1/management/runtime/commands?scope=webui&q=help
   - `404`：会话不存在。
   - `409`：job 正在运行或历史尚未完成落盘。
 - 元数据语义：
-  - `webchat.duration_ms`、`webchat.events`、`webchat.timeline`、`current_tool_calls`、`stage` / `agent_stage` 是 **display-only**，用于刷新后恢复工具 / Agent 展示块、阶段和耗时。
+  - `webchat.duration_ms`、`webchat.events`、`webchat.timeline`、`current_timeline`、`current_tool_calls`、`stage` / `agent_stage` 是 **display-only**，用于刷新后恢复工具 / Agent 展示块、阶段和耗时。
+  - Job 快照的 `current_timeline` 包含截至 `last_seq` 的完整正文与嵌套调用；客户端接受后从 `last_seq` 续流。增量重放缓冲保留最近 1000 条事件，完整展示快照和历史不按这个上限截断。
   - 这些 WebChat 展示元数据不是 **AI-context**，不会作为后续 AI 对话上下文注入。
   - 工具 / Agent 输入输出预览由 Runtime 统一脱敏和截断。
 
diff --git a/docs/openapi.md b/docs/openapi.md
index 67c22431..93b889c1 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -377,6 +377,7 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 - WebChat 不发布模型 token 级文本增量，也不发布工具参数增量；正文以 `message` 事件展示，工具只按生命周期事件展示。
 - `stage`、`agent_stage`、`webchat.calls`、`webchat.timeline`、`current_tool_calls` 和 `duration_ms` 是 display-only 展示元数据，不作为 AI-context 注入后续对话。
 - 工具结束事件 payload 会尽量带 `duration_ms`。运行中的 job 快照会在 `current_tool_calls` 返回仍在执行的工具 / Agent 及其后端计算的 `duration_ms`。
+- Job 快照的 `current_timeline` 包含截至 `last_seq` 的完整展示时间线（正文、已结束和运行中的调用及 Agent 内嵌时间线），客户端接受快照后从该序号续接事件。只有 SSE/JSON 增量事件重放缓冲保留最近 1000 条，完整展示快照与历史不会因此截掉早期正文。
 - WebUI 每 0.5 秒查询一次；查询间隙只用本地时间临时递增显示，下一次查询后以 Runtime 返回值校准。
 - 并发工具按实际完成时间发布结束事件，LLM tool message 回填仍保持模型要求的原始顺序。
 - 工具 / Agent 事件 payload 由后端补齐调用链字段：`webchat_call_id`、`parent_webchat_call_id`、`depth`、`agent_path`。
diff --git a/src/Undefined/api/routes/chat.py b/src/Undefined/api/routes/chat.py
index fd07ddf6..6e051100 100644
--- a/src/Undefined/api/routes/chat.py
+++ b/src/Undefined/api/routes/chat.py
@@ -260,6 +260,14 @@ def snapshot(self) -> dict[str, Any]:
         now = time.time()
         elapsed_ms = _job_elapsed_ms(self, now)
         stage_elapsed_ms = _stage_elapsed_ms(self, now)
+        timeline_events = (
+            _finalize_webchat_history_events(self)
+            if self.status in {"done", "error", "cancelled"}
+            else [
+                {"seq": item.seq, "event": item.event, "payload": dict(item.payload)}
+                for item in self.webchat_events
+            ]
+        )
         return {
             "job_id": self.job_id,
             "conversation_id": self.conversation_id,
@@ -280,6 +288,7 @@ def snapshot(self) -> dict[str, Any]:
             "messages": list(self.outputs),
             "current_agent_stages": self.current_agent_stage_snapshots(now),
             "current_tool_calls": self.current_tool_call_snapshots(now),
+            "current_timeline": _build_webchat_timeline(timeline_events),
             # 对外完成信号与新任务/历史修改的放行门槛一致。
             "history_finalized": self.history_finalized and self.done.is_set(),
             "waiting_input": None,
@@ -963,9 +972,8 @@ def _append_event_locked(
         if len(job.events) > _CHAT_JOB_EVENT_BUFFER_LIMIT:
             job.events = job.events[-_CHAT_JOB_EVENT_BUFFER_LIMIT:]
         if item.event in _WEBCHAT_HISTORY_EVENTS:
+            # 展示快照与历史需要完整内容；只有 SSE 重放缓冲采用固定上限。
             job.webchat_events.append(item)
-            if len(job.webchat_events) > _CHAT_JOB_EVENT_BUFFER_LIMIT:
-                job.webchat_events = job.webchat_events[-_CHAT_JOB_EVENT_BUFFER_LIMIT:]
         job.changed.notify_all()
         return item
 
diff --git a/tests/test_runtime_api_chat_jobs.py b/tests/test_runtime_api_chat_jobs.py
index f347fafd..33a722dc 100644
--- a/tests/test_runtime_api_chat_jobs.py
+++ b/tests/test_runtime_api_chat_jobs.py
@@ -190,6 +190,117 @@ async def delete() -> web.Response:
         await server.stop()
 
 
+@pytest.mark.asyncio
+async def test_running_job_snapshot_contains_complete_nested_display_timeline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    ready = asyncio.Event()
+    release = asyncio.Event()
+
+    async def run_chat(
+        _ctx: RuntimeAPIContext,
+        *,
+        send_output: Any,
+        webchat_event_callback: Any,
+        **_kwargs: Any,
+    ) -> str:
+        await send_output(42, "root prefix")
+        await webchat_event_callback(
+            "tool_start",
+            {
+                "tool_call_id": "agent-tool",
+                "webchat_call_id": "agent",
+                "name": "web_agent",
+                "is_agent": True,
+                "arguments": {"password": "must-not-leak"},
+            },
+        )
+        await send_output(42, "agent message")
+        nested = {
+            "tool_call_id": "search-tool",
+            "webchat_call_id": "agent/search",
+            "parent_webchat_call_id": "agent",
+            "name": "search",
+        }
+        await webchat_event_callback("tool_start", nested)
+        await webchat_event_callback(
+            "tool_end", {**nested, "ok": True, "result": "completed search"}
+        )
+        ready.set()
+        await release.wait()
+        return "chat"
+
+    monkeypatch.setattr(runtime_api_chat, "run_webui_chat", run_chat)
+    server = RuntimeAPIServer(_context(), host="127.0.0.1", port=8788)
+    manager = server._chat_job_manager
+    job = await manager.create_job("hello")
+    try:
+        await asyncio.wait_for(ready.wait(), timeout=2)
+        detail = await server._chat_job_detail_handler(
+            cast(
+                web.Request, cast(Any, _DummyRequest(match_info={"job_id": job.job_id}))
+            )
+        )
+        snapshot = json.loads(detail.text or "{}")
+        assert snapshot["last_seq"] == job.next_seq - 1
+        assert snapshot["messages"] == ["root prefix", "agent message"]
+        timeline = snapshot["current_timeline"]
+        assert [item["type"] for item in timeline] == ["message", "call"]
+        assert timeline[0]["content"] == "root prefix"
+        agent = timeline[1]["call"]
+        assert agent["webchat_call_id"] == "agent"
+        assert agent["status"] == "running"
+        assert [item["type"] for item in agent["timeline"]] == ["message", "call"]
+        assert agent["timeline"][0]["content"] == "agent message"
+        child = agent["timeline"][1]["call"]
+        assert child["status"] == "done"
+        assert child["result_preview"] == "completed search"
+        assert agent["children"] == [child]
+        assert "must-not-leak" not in json.dumps(timeline)
+        assert len(snapshot["current_tool_calls"]) == 1
+        assert snapshot["current_tool_calls"][0]["webchat_call_id"] == "agent"
+        events, refreshed, _live = await manager.events_after_with_snapshot(
+            job, snapshot["last_seq"]
+        )
+        assert events == []
+        assert refreshed["current_timeline"] == timeline
+    finally:
+        release.set()
+        await server.stop()
+
+
+@pytest.mark.asyncio
+async def test_job_snapshot_preserves_display_content_beyond_sse_replay_limit() -> None:
+    manager = runtime_api_chat.ChatJobManager(_context())
+    job = runtime_api_chat.ChatJob("snapshot-job", "hello", 1, 1, status="running")
+    for index in range(runtime_api_chat._CHAT_JOB_EVENT_BUFFER_LIMIT + 5):
+        await manager._append_event(job, "message", {"content": f"message-{index}"})
+    snapshot = await manager.snapshot(job)
+    timeline = snapshot["current_timeline"]
+    assert len(job.events) == runtime_api_chat._CHAT_JOB_EVENT_BUFFER_LIMIT
+    assert len(timeline) == runtime_api_chat._CHAT_JOB_EVENT_BUFFER_LIMIT + 5
+    assert timeline[0]["content"] == "message-0"
+    assert timeline[-1]["content"] == (
+        f"message-{runtime_api_chat._CHAT_JOB_EVENT_BUFFER_LIMIT + 4}"
+    )
+    assert timeline[-1]["seq"] == snapshot["last_seq"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status", ["error", "cancelled"])
+async def test_terminal_snapshot_finalizes_unclosed_display_calls(status: str) -> None:
+    manager = runtime_api_chat.ChatJobManager(_context())
+    job = runtime_api_chat.ChatJob("terminal-job", "hello", 1, 1, status=status)
+    await manager.append_lifecycle_event(
+        job,
+        "tool_start",
+        {"tool_call_id": "tool", "webchat_call_id": "tool", "name": "search"},
+    )
+    timeline = (await manager.snapshot(job))["current_timeline"]
+    assert timeline[0]["call"]["status"] == status
+    assert timeline == runtime_api_chat._build_webchat_history_payload(job)["timeline"]
+
+
 @pytest.mark.asyncio
 async def test_history_finalized_is_published_only_after_job_releases_session(
     monkeypatch: pytest.MonkeyPatch,

From 352b88d324a2c03b49a66ec96efcd6d5b8cea65e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:38:52 +0800
Subject: [PATCH 080/121] fix(webui): preserve meme selection and unsaved
 drafts

---
 docs/webui-guide.md                    |   1 +
 src/Undefined/webui/static/js/memes.js |  95 ++++++++++++++++-------
 tests/test_webui_memes_behavior.py     | 102 +++++++++++++++++++++++++
 3 files changed, 171 insertions(+), 27 deletions(-)
 create mode 100644 tests/test_webui_memes_behavior.py

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index e952a82b..42071255 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -119,6 +119,7 @@ AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：
 - **浏览与搜索**：分页列表展示，支持关键词搜索和语义搜索（以及混合模式）。输入时自动防抖搜索，Enter 立即触发。
 - **筛选与排序**：按启用 / 禁用、静态 / 动态、置顶等条件筛选，按创建或更新时间排序。
 - **详情与操作**：查看元数据（UID、描述、标签）和预览图；支持编辑描述 / 标签、启用 / 禁用、置顶 / 取消、删除。
+- 详情响应只更新当前选中条目；保存或后台刷新期间继续编辑的草稿会保留，不会被迟到响应覆盖。
 - **重分析 / 重索引**：对单张表情包重新触发 AI 描述生成或搜索索引更新。分析期间可继续编辑或删除；旧结果不会覆盖人工修改、恢复已删除条目或删除新修订，使用次数仍会保留。
 - **统计概览**：总数、启用 / 禁用数、静态 / 动态数等。
 
diff --git a/src/Undefined/webui/static/js/memes.js b/src/Undefined/webui/static/js/memes.js
index eec97a04..1c2a5718 100644
--- a/src/Undefined/webui/static/js/memes.js
+++ b/src/Undefined/webui/static/js/memes.js
@@ -6,6 +6,8 @@
         loadingMore: false,
         selectedUid: "",
         detail: null,
+        detailRequestSeq: 0,
+        saving: false,
         listItems: [],
         total: 0,
         page: 0,
@@ -51,6 +53,16 @@
         return String(get(id)?.value || fallback || "").trim();
     }
 
+    function detailDraftSnapshot() {
+        return JSON.stringify([
+            get("memesDetailManualDescription")?.value || "",
+            get("memesDetailTags")?.value || "",
+            get("memesDetailAliases")?.value || "",
+            !!get("memesDetailEnabled")?.checked,
+            !!get("memesDetailPinned")?.checked,
+        ]);
+    }
+
     function showError(error) {
         showToast(
             String(error && error.message ? error.message : error),
@@ -360,6 +372,7 @@
             state.loading = true;
             if (state.queryKey !== queryKey) {
                 state.selectedUid = "";
+                state.detailRequestSeq += 1;
                 state.detail = null;
                 renderDetail(null);
             }
@@ -423,6 +436,7 @@
                 !state.listItems.some((item) => item.uid === state.selectedUid)
             ) {
                 state.selectedUid = "";
+                state.detailRequestSeq += 1;
                 state.detail = null;
                 renderDetail(null);
             }
@@ -446,10 +460,12 @@
 
     async function refreshAll() {
         if (state.loading) return;
+        const selectedUid = state.selectedUid;
+        const expectedDraft = detailDraftSnapshot();
         try {
             await Promise.all([fetchStats(), fetchList()]);
-            if (state.selectedUid) {
-                await loadDetail(state.selectedUid, { silent: true });
+            if (selectedUid && state.selectedUid === selectedUid) {
+                await loadDetail(selectedUid, { silent: true, expectedDraft });
             }
             state.loaded = true;
         } catch (error) {
@@ -460,19 +476,36 @@
     async function loadDetail(uid, options = {}) {
         const targetUid = String(uid || "").trim();
         if (!targetUid) return;
-        const response = await api(
-            `/api/v1/management/memes/${encodeURIComponent(targetUid)}`,
-        );
-        if (!response.ok) throw new Error(await response.text());
-        const payload = await response.json();
-        state.selectedUid = targetUid;
-        renderDetail(payload);
-        if (!options.silent) {
+        if (options.silent && state.selectedUid !== targetUid) return;
+        if (state.selectedUid !== targetUid) {
+            state.selectedUid = targetUid;
+            renderDetail(null);
             renderList();
         }
+        const requestSeq = ++state.detailRequestSeq;
+        const expectedDraft = options.expectedDraft ?? detailDraftSnapshot();
+        const isCurrent = () =>
+            requestSeq === state.detailRequestSeq &&
+            state.selectedUid === targetUid;
+        try {
+            const response = await api(
+                `/api/v1/management/memes/${encodeURIComponent(targetUid)}`,
+            );
+            if (!isCurrent()) return;
+            if (!response.ok) throw new Error(await response.text());
+            const payload = await response.json();
+            if (!isCurrent()) return;
+            // 后台刷新与保存后的刷新不能替换请求期间继续编辑的草稿。
+            if (state.detail && expectedDraft !== detailDraftSnapshot()) return;
+            renderDetail(payload);
+            if (!options.silent) renderList();
+        } catch (error) {
+            if (isCurrent()) throw error;
+        }
     }
 
     async function saveDetail() {
+        if (state.saving) return;
         const record = selectedRecord();
         if (!record) {
             showToast(t("memes.select_prompt"), "warning");
@@ -487,20 +520,26 @@
             enabled: !!get("memesDetailEnabled").checked,
             pinned: !!get("memesDetailPinned").checked,
         };
-        const response = await api(
-            `/api/v1/management/memes/${encodeURIComponent(record.uid)}`,
-            {
-                method: "PATCH",
-                body: JSON.stringify(payload),
-            },
-        );
-        if (!response.ok) throw new Error(await response.text());
-        showToast(t("memes.saved"), "success");
-        await Promise.all([
-            loadDetail(record.uid, { silent: true }),
-            fetchStats(),
-            fetchList(),
-        ]);
+        const expectedDraft = detailDraftSnapshot();
+        state.saving = true;
+        const button = get("btnMemesSave");
+        if (button) button.disabled = true;
+        try {
+            const response = await api(
+                `/api/v1/management/memes/${encodeURIComponent(record.uid)}`,
+                { method: "PATCH", body: JSON.stringify(payload) },
+            );
+            if (!response.ok) throw new Error(await response.text());
+            showToast(t("memes.saved"), "success");
+            await Promise.all([
+                loadDetail(record.uid, { silent: true, expectedDraft }),
+                fetchStats(),
+                fetchList(),
+            ]);
+        } finally {
+            state.saving = false;
+            if (button) button.disabled = false;
+        }
     }
 
     async function queueAction(kind) {
@@ -538,9 +577,11 @@
             { method: "DELETE" },
         );
         if (!response.ok) throw new Error(await response.text());
-        state.selectedUid = "";
-        state.detail = null;
-        renderDetail(null);
+        if (state.selectedUid === record.uid) {
+            state.selectedUid = "";
+            state.detailRequestSeq += 1;
+            renderDetail(null);
+        }
         showToast(t("memes.deleted"), "success");
         await Promise.all([fetchStats(), fetchList()]);
     }
diff --git a/tests/test_webui_memes_behavior.py b/tests/test_webui_memes_behavior.py
new file mode 100644
index 00000000..ff9f40d4
--- /dev/null
+++ b/tests/test_webui_memes_behavior.py
@@ -0,0 +1,102 @@
+"""Meme detail selection and drafts survive delayed management responses."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+import pytest
+
+from test_webui_runtime_chat_behavior import REPO_ROOT, _require_env
+
+
+def _run_meme_scenario(scenario: str) -> dict[str, Any]:
+    _require_env()
+    script = r"""
+const fs=require('node:fs');
+const root=process.argv[1], scenario=process.argv[2];
+const {JSDOM}=require(root+'/tests/frontend/node_modules/jsdom');
+const dom=new JSDOM(fs.readFileSync(root+'/src/Undefined/webui/templates/index.html','utf8'),
+  {url:'http://isolated.example',runScripts:'outside-only'});
+const w=dom.window, details=[], patches=[];
+w.get=id=>w.document.getElementById(id);w.t=k=>k;w.escapeHtml=s=>String(s);w.showToast=()=>{};
+w.confirm=()=>true;
+w.api=async(path,opts={})=>{
+  if(path.endsWith('/stats'))return {ok:true,json:async()=>({})};
+  if(path.includes('/memes?'))return {ok:true,json:async()=>({items:[{uid:'A'},{uid:'B'}],total:2,page:1,page_size:50})};
+  if(opts.method==='PATCH'||opts.method==='DELETE')return new Promise(resolve=>patches.push({path,body:opts.body&&JSON.parse(opts.body),resolve}));
+  return new Promise(resolve=>details.push({uid:path.split('/').at(-1),resolve}));
+};
+w.eval(fs.readFileSync(root+'/src/Undefined/webui/static/js/memes.js','utf8'));
+w.MemesController.init();w.MemesController.onTabActivated('memes');
+const tick=async()=>{for(let i=0;i<10;i++)await new Promise(r=>setImmediate(r));};
+const answer=(request,text)=>request.resolve({ok:true,json:async()=>({record:{uid:request.uid,
+  manual_description:text,enabled:true},sources:[]})});
+const click=uid=>w.document.querySelector(`[data-meme-uid="${uid}"]`).click();
+(async()=>{
+  await tick();click('A');await tick();
+  if(scenario==='selection'){
+    click('B');answer(details[1],'B saved');await tick();
+    w.get('memesDetailManualDescription').value='B unsaved';answer(details[0],'A saved');await tick();
+  }else{
+    answer(details[0],'A saved');await tick();
+    if(scenario==='refresh'){
+      w.get('btnMemesRefresh').click();await tick();
+      w.get('memesDetailManualDescription').value='A draft during refresh';
+      answer(details[1],'A refreshed');await tick();
+    }else{
+      w.get('memesDetailManualDescription').value='A first edit';w.get('btnMemesSave').click();await tick();
+      if(scenario==='save_switch'){
+        click('B');answer(details[1],'B saved');await tick();
+        w.get('memesDetailManualDescription').value='B unsaved';
+      }else if(scenario==='save_edit')w.get('memesDetailManualDescription').value='A second unsaved edit';
+      patches[0].resolve({ok:true});await tick();
+      if(scenario!=='save_switch')answer(details[1],'A first edit');
+      await tick();
+    }
+  }
+  console.log(JSON.stringify({uid:w.get('memesDetailUid').textContent,
+    draft:w.get('memesDetailManualDescription').value,detailRequests:details.map(item=>item.uid),
+    sent:patches.map(item=>item.body),saveEnabled:!w.get('btnMemesSave').disabled}));
+  dom.window.close();
+})().catch(error=>{console.error(error);process.exitCode=1;});
+"""
+    completed = subprocess.run(
+        ["node", "-e", script, str(REPO_ROOT), scenario],
+        capture_output=True,
+        text=True,
+        timeout=15,
+        check=False,
+    )
+    assert completed.returncode == 0, completed.stderr
+    result: dict[str, Any] = json.loads(completed.stdout.strip().splitlines()[-1])
+    return result
+
+
+def test_late_meme_detail_cannot_change_selection_or_draft() -> None:
+    result = _run_meme_scenario("selection")
+    assert result["uid"] == "B"
+    assert result["draft"] == "B unsaved"
+
+
+@pytest.mark.parametrize(
+    ("scenario", "uid", "draft"),
+    [
+        ("save_edit", "A", "A second unsaved edit"),
+        ("save_switch", "B", "B unsaved"),
+        ("save_unchanged", "A", "A first edit"),
+        ("refresh", "A", "A draft during refresh"),
+    ],
+)
+def test_meme_background_refresh_preserves_later_edits(
+    scenario: str, uid: str, draft: str
+) -> None:
+    result = _run_meme_scenario(scenario)
+    assert result["uid"] == uid
+    assert result["draft"] == draft
+    assert result["saveEnabled"] is True
+    if scenario.startswith("save_"):
+        assert result["sent"][0]["manual_description"] == "A first edit"
+    if scenario == "save_switch":
+        assert result["detailRequests"] == ["A", "B"]

From eb64c53a516df183114bcb504c05df7fa3496ea3 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:40:27 +0800
Subject: [PATCH 081/121] fix(config): serialize replacements and preserve
 cancelled writes

---
 docs/configuration.md                        |   2 +
 docs/management-api.md                       |   2 +
 docs/webui-guide.md                          |   2 +
 src/Undefined/utils/io.py                    |   6 +-
 src/Undefined/webui/routes/_auth.py          |  43 ++-
 src/Undefined/webui/routes/_config.py        | 113 ++++--
 src/Undefined/webui/static/js/config-form.js | 196 +++++++----
 src/Undefined/webui/static/js/main.js        |  25 +-
 src/Undefined/webui/utils/config_io.py       |   6 +
 src/Undefined/webui/utils/config_sync.py     |  24 +-
 tests/frontend/runtime_chat_harness.js       |  90 ++++-
 tests/test_webui_config_save_behavior.py     |  24 ++
 tests/test_webui_config_transactions.py      | 352 +++++++++++++++++++
 13 files changed, 734 insertions(+), 151 deletions(-)
 create mode 100644 tests/test_webui_config_transactions.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 627575af..501b959d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -19,6 +19,8 @@
 - 示例模板：`config.toml.example`
 - 启动 WebUI 时，如 `config.toml` 不存在，会自动用示例模板生成。
 - 已有 `config.toml` 想补齐新增配置项/注释时，可用 WebUI 的“同步模板”按钮，或运行 `python scripts/sync_config_template.py`（也支持 `uv run python scripts/sync_config_template.py`）。
+- Management 的整体保存、增量修改、恢复、模板同步和密码更新共用配置文件读改写锁，并原子替换文件；请求取消会等写入、主循环热更新及必要的凭据撤销完成后再传播。备份列表与恢复读取也同备份裁剪串行。
+- WebUI 恢复、同步或重新加载时会停止旧保存队列，等在途保存结束后再替换配置；期间表单暂停编辑，完成后以服务器配置重建。
 
 ### 1.2 运行时本地文件
 - `config.local.json`：运行时维护的本地管理员列表（如 `/admin add`）。
diff --git a/docs/management-api.md b/docs/management-api.md
index 21865f99..7c6a2502 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -142,6 +142,8 @@ WebUI 的并发请求共用同一次 refresh token 轮换；旧会话的迟到
 - `validate`：先做 TOML 语法校验，再做严格配置校验
 - `sync-template`：把 `config.toml.example` 中新增字段/注释同步到当前配置
 
+整体保存、PATCH、历史恢复、模板同步及密码更新使用同一文件读改写锁，原子落盘后在主事件循环更新运行时配置。请求取消会先等待写入与更新收敛；密码更新同时刷新管理设置并撤销旧会话令牌。历史列表和恢复读取与备份裁剪串行，已被裁剪的备份恢复返回 `404`。
+
 ## 5. 日志、系统与 Bot 控制
 
 ### 日志
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 42071255..513f49dc 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -70,6 +70,8 @@ WebUI 的主要页签如下。
 - **配置历史**：每次保存自动生成带时间戳和唯一后缀的备份（最多 50 版本），同一秒内保存也会分别保留；历史按备份生成时间列出，可随时回滚到任意历史版本，旧版备份仍可使用。
 - **模板同步**：一键将 `config.toml.example` 中新增的配置项合并到当前配置，不覆盖已有值。
 
+恢复历史、同步模板和重新加载会先清除旧的待保存快照与输入计时器，等正在保存的请求结束后再执行；期间表单暂停编辑，完成后展示服务器上的配置，避免旧自动保存覆盖恢复结果。
+
 > 配置支持热更新——大多数配置项修改后即时生效，无需重启 Bot。需要重启的项（如 `onebot_ws_url`、`webui_port`）会在保存时提示。
 
 ### 日志查看（Logs）
diff --git a/src/Undefined/utils/io.py b/src/Undefined/utils/io.py
index b0f051f3..9a3b07cd 100644
--- a/src/Undefined/utils/io.py
+++ b/src/Undefined/utils/io.py
@@ -365,7 +365,9 @@ def sync_delete() -> bool:
     return await asyncio.to_thread(sync_delete)
 
 
-def _write_text_sync(target: Path, content: str, use_lock: bool) -> None:
+def write_text_sync(file_path: str | Path, content: str, use_lock: bool = True) -> None:
+    """在线程中的读改写事务内复用文本原子写入；已持文件锁时传 False。"""
+    target = Path(file_path)
     target.parent.mkdir(parents=True, exist_ok=True)
 
     def atomic_write() -> None:
@@ -442,7 +444,7 @@ async def write_text(
 ) -> None:
     """原子写入文本文件"""
     target = Path(file_path)
-    await asyncio.to_thread(_write_text_sync, target, content, use_lock)
+    await asyncio.to_thread(write_text_sync, target, content, use_lock)
 
 
 async def read_text(file_path: str | Path, use_lock: bool = False) -> str | None:
diff --git a/src/Undefined/webui/routes/_auth.py b/src/Undefined/webui/routes/_auth.py
index ed4c0776..f194e275 100644
--- a/src/Undefined/webui/routes/_auth.py
+++ b/src/Undefined/webui/routes/_auth.py
@@ -1,3 +1,4 @@
+import asyncio
 import tomllib
 
 from aiohttp import web
@@ -5,6 +6,8 @@
 
 from Undefined.config.loader import CONFIG_PATH, DEFAULT_WEBUI_PASSWORD
 from Undefined.config import WebUISettings, get_config_manager
+from Undefined.utils import io as async_io
+from ..utils.config_io import config_write_lock
 from ._shared import (
     auth_capabilities,
     routes,
@@ -244,28 +247,34 @@ async def password_handler(request: web.Request) -> Response:
             status=400,
         )
 
-    source = read_config_source()
-    try:
-        data_dict = (
-            tomllib.loads(source["content"]) if source["content"].strip() else {}
+    def write_password() -> None:
+        with config_write_lock(CONFIG_PATH):
+            source = read_config_source()
+            data_dict = (
+                tomllib.loads(source["content"]) if source["content"].strip() else {}
+            )
+            patched = apply_patch(data_dict, {"webui.password": new_password})
+            async_io.write_text_sync(
+                CONFIG_PATH,
+                render_toml(patched, comments=load_comment_map()),
+                use_lock=False,
+            )
+
+    async def password_and_reload() -> None:
+        await asyncio.to_thread(write_password)
+        manager = get_config_manager()
+        manager.reload()
+        request.app[SETTINGS_APP_KEY] = WebUISettings.from_config(
+            manager.load(strict=False), config_exists=True
         )
+        get_session_store(request).clear()
+
+    try:
+        await async_io.run_cancellation_safe(password_and_reload())
     except tomllib.TOMLDecodeError as exc:
         return web.json_response(
             {"success": False, "error": f"TOML parse error: {exc}"}, status=400
         )
-    if not isinstance(data_dict, dict):
-        data_dict = {}
-
-    patched = apply_patch(data_dict, {"webui.password": new_password})
-    CONFIG_PATH.write_text(
-        render_toml(patched, comments=load_comment_map()), encoding="utf-8"
-    )
-    manager = get_config_manager()
-    manager.reload()
-    request.app[SETTINGS_APP_KEY] = WebUISettings.from_config(
-        manager.load(strict=False), config_exists=True
-    )
-    get_session_store(request).clear()
 
     resp = web.json_response({"success": True, "message": "Password updated"})
     resp.del_cookie(SESSION_COOKIE)
diff --git a/src/Undefined/webui/routes/_config.py b/src/Undefined/webui/routes/_config.py
index 6a1832e1..a66b290f 100644
--- a/src/Undefined/webui/routes/_config.py
+++ b/src/Undefined/webui/routes/_config.py
@@ -11,8 +11,11 @@
 from Undefined.config.loader import Config
 from Undefined.config.loader import CONFIG_PATH, load_toml_data
 from Undefined.config import get_config_manager
+from Undefined.utils import io as async_io
+from ..utils.config_io import config_write_lock
 from ._shared import routes, check_auth
 from ..utils import (
+    ConfigTemplateSyncResult,
     read_config_source,
     validate_toml,
     validate_required_config,
@@ -82,10 +85,18 @@ async def save_config_handler(request: web.Request) -> Response:
     if not valid:
         return web.json_response({"success": False, "error": msg}, status=400)
     try:
-        _backup_config()
-        CONFIG_PATH.write_text(content, encoding="utf-8")
-        get_config_manager().reload()
-        logic_valid, logic_msg = validate_required_config()
+
+        def write_config() -> None:
+            with config_write_lock(CONFIG_PATH):
+                _backup_config()
+                async_io.write_text_sync(CONFIG_PATH, content, use_lock=False)
+
+        async def save_and_reload() -> tuple[bool, str]:
+            await asyncio.to_thread(write_config)
+            get_config_manager().reload()
+            return validate_required_config()
+
+        logic_valid, logic_msg = await async_io.run_cancellation_safe(save_and_reload())
         return web.json_response(
             {
                 "success": True,
@@ -162,21 +173,29 @@ async def config_patch_handler(request: web.Request) -> Response:
     if not isinstance(patch, dict):
         return web.json_response({"error": "Invalid payload"}, status=400)
 
-    source = read_config_source()
+    def write_patch() -> None:
+        with config_write_lock(CONFIG_PATH):
+            source = read_config_source()
+            data = tomllib.loads(source["content"]) if source["content"].strip() else {}
+            patched = apply_patch(data, patch)
+            _backup_config()
+            async_io.write_text_sync(
+                CONFIG_PATH,
+                render_toml(patched, comments=load_comment_map()),
+                use_lock=False,
+            )
+
+    async def patch_and_reload() -> tuple[bool, str]:
+        await asyncio.to_thread(write_patch)
+        get_config_manager().reload()
+        return validate_required_config()
+
     try:
-        data = tomllib.loads(source["content"]) if source["content"].strip() else {}
+        validation_ok, validation_msg = await async_io.run_cancellation_safe(
+            patch_and_reload()
+        )
     except tomllib.TOMLDecodeError as exc:
         return web.json_response({"error": f"TOML parse error: {exc}"}, status=400)
-    if not isinstance(data, dict):
-        data = {}
-
-    patched = apply_patch(data, patch)
-    _backup_config()
-    CONFIG_PATH.write_text(
-        render_toml(patched, comments=load_comment_map()), encoding="utf-8"
-    )
-    get_config_manager().reload()
-    validation_ok, validation_msg = validate_required_config()
     return web.json_response(
         {
             "success": True,
@@ -193,15 +212,20 @@ async def sync_config_template_handler(request: web.Request) -> Response:
         return web.json_response({"error": "Unauthorized"}, status=401)
     prune = request.query.get("prune") == "true"
     write = request.query.get("write", "true").lower() != "false"
-    try:
+
+    async def sync_and_reload() -> tuple[ConfigTemplateSyncResult, bool, str | None]:
         result = await asyncio.to_thread(sync_config_file, prune=prune, write=write)
         validation_ok = True
         validation_msg: str | None = None
         if write:
-            await asyncio.to_thread(get_config_manager().reload)
-            validation_ok, validation_msg = await asyncio.to_thread(
-                validate_required_config
-            )
+            get_config_manager().reload()
+            validation_ok, validation_msg = validate_required_config()
+        return result, validation_ok, validation_msg
+
+    try:
+        result, validation_ok, validation_msg = await async_io.run_cancellation_safe(
+            sync_and_reload()
+        )
         return web.json_response(
             {
                 "success": True,
@@ -233,12 +257,20 @@ async def config_history_handler(request: web.Request) -> Response:
     """Return the list of config backups, newest first."""
     if not check_auth(request):
         return web.json_response({"error": "Unauthorized"}, status=401)
-    if not _BACKUP_DIR.exists():
-        return web.json_response({"backups": []})
-    backups: list[dict[str, object]] = []
-    for f in reversed(_config_backups()):
-        stat = f.stat()
-        backups.append({"name": f.name, "size": stat.st_size, "mtime": stat.st_mtime})
+
+    def read_history() -> list[dict[str, object]]:
+        with config_write_lock(CONFIG_PATH):
+            if not _BACKUP_DIR.exists():
+                return []
+            backups: list[dict[str, object]] = []
+            for f in reversed(_config_backups()):
+                stat = f.stat()
+                backups.append(
+                    {"name": f.name, "size": stat.st_size, "mtime": stat.st_mtime}
+                )
+            return backups
+
+    backups = await asyncio.to_thread(read_history)
     return web.json_response({"backups": backups})
 
 
@@ -258,13 +290,24 @@ async def config_restore_handler(request: web.Request) -> Response:
     backup_path = (_BACKUP_DIR / name).resolve()
     if not str(backup_path).startswith(str(_BACKUP_DIR.resolve())):
         return web.json_response({"error": "Invalid backup name"}, status=400)
-    if not backup_path.exists():
+
+    def write_restore() -> None:
+        with config_write_lock(CONFIG_PATH):
+            content = backup_path.read_text(encoding="utf-8")
+            valid, msg = validate_toml(content)
+            if not valid:
+                raise ValueError(f"Backup TOML invalid: {msg}")
+            _backup_config()
+            async_io.write_text_sync(CONFIG_PATH, content, use_lock=False)
+
+    async def restore_and_reload() -> None:
+        await asyncio.to_thread(write_restore)
+        get_config_manager().reload()
+
+    try:
+        await async_io.run_cancellation_safe(restore_and_reload())
+    except FileNotFoundError:
         return web.json_response({"error": "Backup not found"}, status=404)
-    content = backup_path.read_text(encoding="utf-8")
-    valid, msg = validate_toml(content)
-    if not valid:
-        return web.json_response({"error": f"Backup TOML invalid: {msg}"}, status=400)
-    _backup_config()
-    CONFIG_PATH.write_text(content, encoding="utf-8")
-    get_config_manager().reload()
+    except ValueError as exc:
+        return web.json_response({"error": str(exc)}, status=400)
     return web.json_response({"success": True, "message": "Restored"})
diff --git a/src/Undefined/webui/static/js/config-form.js b/src/Undefined/webui/static/js/config-form.js
index e77e6182..95e8dfc2 100644
--- a/src/Undefined/webui/static/js/config-form.js
+++ b/src/Undefined/webui/static/js/config-form.js
@@ -3,6 +3,34 @@ let configLayoutResizeObserver = null;
 let configSavePromise = null;
 let configPendingSave = null;
 let configSaveRevision = 0;
+let configOperationPromise = null;
+let configLoadPromise = null;
+
+async function runConfigOperation(operation) {
+    // 恢复/同步/重新加载替换整个表单，旧快照不能在它们之后继续保存。
+    configSaveRevision += 1;
+    configPendingSave = null;
+    if (state.saveTimer) clearTimeout(state.saveTimer);
+    state.saveTimer = null;
+    const previous = configOperationPromise;
+    const form = get("formSections");
+    if (form) form.inert = true;
+    const current = (async () => {
+        if (previous) await previous.catch(() => {});
+        if (configSavePromise) await configSavePromise;
+        if (configLoadPromise) await configLoadPromise;
+        return await operation();
+    })();
+    configOperationPromise = current;
+    try {
+        return await current;
+    } finally {
+        if (configOperationPromise === current) {
+            configOperationPromise = null;
+            if (form) form.inert = false;
+        }
+    }
+}
 
 function getConfigStickyChromeElements() {
     return [
@@ -62,23 +90,30 @@ function initConfigFormLayout() {
 }
 
 async function loadConfig() {
-    if (state.configLoading) return;
+    if (configLoadPromise) return configLoadPromise;
     state.configLoading = true;
     state.configLoaded = false;
     setConfigState("loading");
+    configLoadPromise = (async () => {
+        try {
+            const res = await api("/api/config/summary");
+            const data = await res.json();
+            state.config = data.data;
+            state.comments = data.comments || {};
+            state.configLoaded = true;
+            buildConfigForm();
+            setConfigState(null);
+        } catch (e) {
+            setConfigState("error");
+            showToast(t("config.error"), "error", 5000);
+        } finally {
+            state.configLoading = false;
+        }
+    })();
     try {
-        const res = await api("/api/config/summary");
-        const data = await res.json();
-        state.config = data.data;
-        state.comments = data.comments || {};
-        state.configLoaded = true;
-        buildConfigForm();
-        setConfigState(null);
-    } catch (e) {
-        setConfigState("error");
-        showToast(t("config.error"), "error", 5000);
+        await configLoadPromise;
     } finally {
-        state.configLoading = false;
+        configLoadPromise = null;
     }
 }
 
@@ -126,6 +161,7 @@ function isRequestParamsPath(path) {
 }
 
 function scheduleAutoSave() {
+    if (configOperationPromise) return;
     configSaveRevision += 1;
     if (state.saveTimer) clearTimeout(state.saveTimer);
     showSaveStatus("saving", t("config.typing"));
@@ -1241,6 +1277,7 @@ function parseInputValue(input) {
 }
 
 async function autoSave() {
+    if (configOperationPromise) return;
     if (state.saveTimer) clearTimeout(state.saveTimer);
     state.saveTimer = null;
     configSaveRevision += 1;
@@ -1331,74 +1368,79 @@ async function syncConfigTemplate(button) {
     setButtonLoading(button, true);
     showSaveStatus("saving", t("config.syncing"));
     try {
-        const previewRes = await api("/api/config/sync-template?write=false", {
-            method: "POST",
-        });
-        const previewData = await previewRes.json();
-        if (!previewData.success) {
-            showSaveStatus("error", t("config.save_error"));
-            showToast(
-                `${t("common.error")}: ${previewData.error || t("config.sync_error")}`,
-                "error",
-                5000,
+        await runConfigOperation(async () => {
+            const previewRes = await api(
+                "/api/config/sync-template?write=false",
+                {
+                    method: "POST",
+                },
             );
-            return;
-        }
+            const previewData = await previewRes.json();
+            if (!previewData.success) {
+                showSaveStatus("error", t("config.save_error"));
+                showToast(
+                    `${t("common.error")}: ${previewData.error || t("config.sync_error")}`,
+                    "error",
+                    5000,
+                );
+                return;
+            }
 
-        let shouldPrune = false;
-        if (
-            Array.isArray(previewData.removed_paths) &&
-            previewData.removed_paths.length > 0
-        ) {
-            const listing = previewData.removed_paths
-                .map((p) => `  - ${p}`)
-                .join("\n");
-            shouldPrune = confirm(
-                `${t("config.prune_confirm")}\n\n${listing}\n\n${t("config.prune_confirm_action")}`,
-            );
-        }
+            let shouldPrune = false;
+            if (
+                Array.isArray(previewData.removed_paths) &&
+                previewData.removed_paths.length > 0
+            ) {
+                const listing = previewData.removed_paths
+                    .map((p) => `  - ${p}`)
+                    .join("\n");
+                shouldPrune = confirm(
+                    `${t("config.prune_confirm")}\n\n${listing}\n\n${t("config.prune_confirm_action")}`,
+                );
+            }
 
-        const finalUrl = shouldPrune
-            ? "/api/config/sync-template?prune=true"
-            : "/api/config/sync-template";
-        const finalRes = await api(finalUrl, { method: "POST" });
-        const finalData = await finalRes.json();
-        if (!finalData.success) {
-            showSaveStatus("error", t("config.save_error"));
-            showToast(
-                `${t("common.error")}: ${finalData.error || t("config.sync_error")}`,
-                "error",
-                5000,
-            );
-            return;
-        }
+            const finalUrl = shouldPrune
+                ? "/api/config/sync-template?prune=true"
+                : "/api/config/sync-template";
+            const finalRes = await api(finalUrl, { method: "POST" });
+            const finalData = await finalRes.json();
+            if (!finalData.success) {
+                showSaveStatus("error", t("config.save_error"));
+                showToast(
+                    `${t("common.error")}: ${finalData.error || t("config.sync_error")}`,
+                    "error",
+                    5000,
+                );
+                return;
+            }
 
-        await loadConfig();
-        showSaveStatus("saved", t("config.saved"));
-        if (finalData.warning) {
-            showToast(
-                `${t("common.warning")}: ${finalData.warning}`,
-                "warning",
-                5000,
-            );
-        }
-        if (shouldPrune) {
-            const removedCount = Number.isFinite(finalData.removed_count)
-                ? finalData.removed_count
-                : Array.isArray(finalData.removed_paths)
-                  ? finalData.removed_paths.length
-                  : 0;
-            showToast(
-                `${t("config.prune_success")} (-${removedCount})`,
-                "info",
-                4000,
-            );
-        } else {
-            const suffix = Number.isFinite(finalData.added_count)
-                ? ` (+${finalData.added_count})`
-                : "";
-            showToast(`${t("config.sync_success")}${suffix}`, "info", 4000);
-        }
+            await loadConfig();
+            showSaveStatus("saved", t("config.saved"));
+            if (finalData.warning) {
+                showToast(
+                    `${t("common.warning")}: ${finalData.warning}`,
+                    "warning",
+                    5000,
+                );
+            }
+            if (shouldPrune) {
+                const removedCount = Number.isFinite(finalData.removed_count)
+                    ? finalData.removed_count
+                    : Array.isArray(finalData.removed_paths)
+                      ? finalData.removed_paths.length
+                      : 0;
+                showToast(
+                    `${t("config.prune_success")} (-${removedCount})`,
+                    "info",
+                    4000,
+                );
+            } else {
+                const suffix = Number.isFinite(finalData.added_count)
+                    ? ` (+${finalData.added_count})`
+                    : "";
+                showToast(`${t("config.sync_success")}${suffix}`, "info", 4000);
+            }
+        });
     } catch (e) {
         showSaveStatus("error", t("config.sync_error"));
         showToast(`${t("common.error")}: ${e.message}`, "error", 5000);
@@ -1410,7 +1452,7 @@ async function syncConfigTemplate(button) {
 async function resetConfig() {
     if (!confirm(t("config.reset_confirm"))) return;
     try {
-        await loadConfig();
+        await runConfigOperation(loadConfig);
         showToast(t("config.reload_success"), "info");
     } catch (e) {
         showToast(t("config.reload_error"), "error");
diff --git a/src/Undefined/webui/static/js/main.js b/src/Undefined/webui/static/js/main.js
index b7289408..2b0b9b4b 100644
--- a/src/Undefined/webui/static/js/main.js
+++ b/src/Undefined/webui/static/js/main.js
@@ -978,17 +978,22 @@ async function init() {
                         if (!confirm(t("config.history_restore_confirm")))
                             return;
                         try {
-                            await api("/api/config/history/restore", {
-                                method: "POST",
-                                headers: {
-                                    "Content-Type": "application/json",
-                                },
-                                body: JSON.stringify({ name }),
+                            await runConfigOperation(async () => {
+                                await api("/api/config/history/restore", {
+                                    method: "POST",
+                                    headers: {
+                                        "Content-Type": "application/json",
+                                    },
+                                    body: JSON.stringify({ name }),
+                                });
+                                showToast(
+                                    t("config.history_restored"),
+                                    "success",
+                                );
+                                panel.style.display = "none";
+                                if (formGrid) formGrid.style.display = "";
+                                await loadConfig();
                             });
-                            showToast(t("config.history_restored"), "success");
-                            panel.style.display = "none";
-                            if (formGrid) formGrid.style.display = "";
-                            loadConfig();
                         } catch (e) {
                             showToast(
                                 `${t("common.error")}: ${e.message}`,
diff --git a/src/Undefined/webui/utils/config_io.py b/src/Undefined/webui/utils/config_io.py
index ebf824ec..a4694b9d 100644
--- a/src/Undefined/webui/utils/config_io.py
+++ b/src/Undefined/webui/utils/config_io.py
@@ -8,6 +8,7 @@
 from Undefined.config import load_webui_settings
 from Undefined.config.loader import CONFIG_PATH, Config
 from Undefined.utils.resources import resolve_resource_path
+from Undefined.utils.file_lock import FileLock
 
 logger = logging.getLogger(__name__)
 
@@ -15,6 +16,11 @@
 TomlData = dict[str, Any]
 
 
+def config_write_lock(config_path: Path) -> FileLock:
+    """所有配置写入口共同保护读取、变换与原子替换，锁文件不随替换移动。"""
+    return FileLock(config_path.with_name(f"{config_path.name}.lock"))
+
+
 def _resolve_config_example_path(path: Path = CONFIG_EXAMPLE_PATH) -> Path | None:
     if path.exists():
         return path
diff --git a/src/Undefined/webui/utils/config_sync.py b/src/Undefined/webui/utils/config_sync.py
index c3df03a6..9e5d7ff7 100644
--- a/src/Undefined/webui/utils/config_sync.py
+++ b/src/Undefined/webui/utils/config_sync.py
@@ -8,9 +8,14 @@
 from typing import Any
 
 from Undefined.config.loader import CONFIG_PATH
+from Undefined.utils.io import write_text_sync
 
 from .comment import CommentMap, parse_comment_map_text
-from .config_io import CONFIG_EXAMPLE_PATH, _resolve_config_example_path
+from .config_io import (
+    CONFIG_EXAMPLE_PATH,
+    _resolve_config_example_path,
+    config_write_lock,
+)
 from .toml_render import TomlData, merge_defaults, render_toml
 
 _PASSTHROUGH_KEYS = {"request_params"}
@@ -290,11 +295,12 @@ def sync_config_file(
     if resolved_example is None or not resolved_example.exists():
         raise FileNotFoundError(f"config example not found: {example_path}")
 
-    current_text = (
-        config_path.read_text(encoding="utf-8") if config_path.exists() else ""
-    )
-    example_text = resolved_example.read_text(encoding="utf-8")
-    result = sync_config_text(current_text, example_text, prune=prune)
-    if write:
-        config_path.write_text(result.content, encoding="utf-8")
-    return result
+    with config_write_lock(config_path):
+        current_text = (
+            config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+        )
+        example_text = resolved_example.read_text(encoding="utf-8")
+        result = sync_config_text(current_text, example_text, prune=prune)
+        if write:
+            write_text_sync(config_path, result.content, use_lock=False)
+        return result
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index f98b34c6..39a190cc 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3392,6 +3392,94 @@ for (const outcome of ["success", "network_error", "api_error", "typing", "saved
     SCENARIOS[`config_autosave_${outcome}`] = (env) => configAutoSave(env, outcome);
 }
 
+async function configReplacement(env, operation) {
+    const { window, response, root } = env;
+    const calls = [];
+    let serverMode = "local";
+    let finishPatch;
+    let patchCount = 0;
+    window.confirm = () => true;
+    window.fetch = async (url, options = {}) => {
+        const route = String(url);
+        calls.push(route);
+        if (route === "/api/config/summary") return response(200, {
+            data: { onebot: { file_send_mode: serverMode, file_send_host: "localhost" } },
+            comments: {},
+        });
+        if (route === "/api/patch") {
+            patchCount += 1;
+            serverMode = JSON.parse(options.body).patch["onebot.file_send_mode"];
+            if (patchCount === 1) return new Promise((resolve) => { finishPatch = resolve; });
+            return response(200, { success: true });
+        }
+        if (route === "/api/config/history") return response(200, {
+            backups: [{ name: "config_previous.toml", mtime: 1, size: 1 }],
+        });
+        if (route === "/api/config/history/restore") {
+            serverMode = "local";
+            return response(200, { success: true });
+        }
+        if (route.startsWith("/api/config/sync-template")) return response(200, {
+            success: true, removed_paths: [], added_count: 1,
+        });
+        throw new Error(`unexpected config route: ${route}`);
+    };
+    // 使用真实历史按钮的处理器，避免仅测试串行 helper 而漏掉其调用入口。
+    const main = fs.readFileSync(path.join(root, "src/Undefined/webui/static/js/main.js"), "utf8");
+    const start = main.indexOf('    get("btnConfigHistory")?.addEventListener');
+    const end = main.indexOf("    const logout = async", start);
+    window.eval(main.slice(start, end));
+    await window.loadConfig();
+    const mode = () => window.document.querySelector('[data-path="onebot.file_send_mode"].config-input');
+    const changeMode = (value) => {
+        mode().value = value;
+        mode().dispatchEvent(new window.Event("change", { bubbles: true }));
+    };
+    changeMode("stream");
+    await tick();
+    changeMode("url");
+    // 同时覆盖已排队快照与尚未触发的 debounce。
+    const host = window.document.querySelector('[data-path="onebot.file_send_host"].config-input');
+    host.value = "obsolete-host";
+    host.dispatchEvent(new window.Event("input", { bubbles: true }));
+    let completion;
+    if (operation === "restore" || operation === "restore_sync") {
+        window.get("btnConfigHistory").click();
+        await tick();
+        window.document.querySelector("[data-restore-name]").click();
+        if (operation === "restore_sync") {
+            completion = window.syncConfigTemplate(window.get("btnSyncConfigTemplate"));
+        }
+    } else if (operation === "sync") {
+        completion = window.syncConfigTemplate(window.get("btnSyncConfigTemplate"));
+    } else {
+        completion = window.resetConfig();
+    }
+    await tick();
+    const beforeResponse = {
+        patchCount,
+        mutationCount: calls.filter((url) => url.includes("/restore") || url.includes("sync-template")).length,
+        formInert: window.get("formSections").inert,
+    };
+    finishPatch(response(200, { success: true, warning: "obsolete save warning" }));
+    if (completion) await completion;
+    await tick();
+    await settle(1100);
+    return {
+        beforeResponse,
+        patchCount,
+        calls,
+        serverMode,
+        formMode: mode().value,
+        formInert: window.get("formSections").inert,
+        toasts: window.document.querySelector(".toast-container")?.textContent || "",
+    };
+}
+
+for (const operation of ["restore", "sync", "reload", "restore_sync"]) {
+    SCENARIOS[`config_replacement_${operation}`] = (env) => configReplacement(env, operation);
+}
+
 function workflowEditorFixture(env) {
     const { window, response } = env;
     const tasks = ["A", "B"].map((id) => ({
@@ -3792,7 +3880,7 @@ async function main() {
     }
     const root = resolveRoot(args.root);
     const env = createEnv(root, {
-        scripts: args.scenario.startsWith("config_autosave_")
+        scripts: args.scenario.startsWith("config_autosave_") || args.scenario.startsWith("config_replacement_")
             ? ["config-form.js"]
             : args.scenario.startsWith("workflow_editor_")
               ? ["workflow-graph.js", "workflow-canvas.js", "workflow-inspector.js", "schedules.js"]
diff --git a/tests/test_webui_config_save_behavior.py b/tests/test_webui_config_save_behavior.py
index 464f89ae..afd47128 100644
--- a/tests/test_webui_config_save_behavior.py
+++ b/tests/test_webui_config_save_behavior.py
@@ -59,3 +59,27 @@ def test_latest_auto_save_failure_remains_visible_and_next_edit_can_retry(
     assert result["saved"]["onebot.file_send_mode"] == "url"
     assert result["final"]["status"] == "已保存"
     assert result["maxInFlight"] == 1
+
+
+@pytest.mark.parametrize("operation", ["restore", "sync", "reload", "restore_sync"])
+def test_config_replacement_discards_old_snapshots_and_waits_for_inflight_save(
+    operation: str,
+) -> None:
+    result = run_scenario(f"config_replacement_{operation}")
+    assert result["beforeResponse"] == {
+        "patchCount": 1,
+        "mutationCount": 0,
+        "formInert": True,
+    }
+    assert result["patchCount"] == 1
+    assert (
+        result["serverMode"]
+        == result["formMode"]
+        == ("local" if operation.startswith("restore") else "stream")
+    )
+    assert result["formInert"] is False
+    assert "obsolete save warning" not in result["toasts"]
+    if operation == "restore_sync":
+        assert result["calls"].index("/api/config/history/restore") < result[
+            "calls"
+        ].index("/api/config/sync-template?write=false")
diff --git a/tests/test_webui_config_transactions.py b/tests/test_webui_config_transactions.py
new file mode 100644
index 00000000..968059ed
--- /dev/null
+++ b/tests/test_webui_config_transactions.py
@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import threading
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+from aiohttp import web
+
+from Undefined.config import WebUISettings
+from Undefined.config.manager import ConfigManager
+from Undefined.utils import io as async_io
+from Undefined.utils.file_lock import FileLock
+from Undefined.webui.core import SessionStore
+from Undefined.webui.routes import _auth, _config
+from Undefined.webui.routes._shared import SESSION_STORE_APP_KEY, SETTINGS_APP_KEY
+from Undefined.webui.utils import config_io, config_sync
+
+
+class ConfigRequest(SimpleNamespace):
+    async def json(self) -> dict[str, Any]:
+        return cast(dict[str, Any], self.body)
+
+
+@dataclass
+class ConfigTransactionFixture:
+    path: Path
+    example: Path
+    backups: Path
+    manager: ConfigManager
+    app: web.Application
+    sessions: SessionStore
+
+    def request(self, body: dict[str, Any] | None = None) -> web.Request:
+        return cast(
+            web.Request,
+            cast(Any, ConfigRequest(body=body or {}, app=self.app, query={})),
+        )
+
+
+@pytest.fixture
+def transaction_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> ConfigTransactionFixture:
+    monkeypatch.chdir(tmp_path)
+    path = tmp_path / "config.toml"
+    example = tmp_path / "config.toml.example"
+    backups = tmp_path / "backups"
+    backups.mkdir()
+    path.write_text(
+        "[core]\nbot_qq=10001\nsuperadmin_qq=20002\n"
+        '[api]\nport=11111\n[webui]\npassword="previous-secret"\n',
+        encoding="utf-8",
+    )
+    example.write_text(
+        "[core]\nbot_qq=0\nsuperadmin_qq=0\n[api]\nport=8788\n"
+        '[webui]\npassword="changeme"\nstop_timeout_seconds=3\n',
+        encoding="utf-8",
+    )
+    (backups / "config_fixture.toml").write_text(
+        path.read_text().replace("11111", "33333"), encoding="utf-8"
+    )
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    app = web.Application()
+    sessions = SessionStore()
+    app[SETTINGS_APP_KEY] = WebUISettings.from_config(config, config_exists=True)
+    app[SESSION_STORE_APP_KEY] = sessions
+    for module in (_config, _auth, config_io):
+        monkeypatch.setattr(module, "CONFIG_PATH", path)
+    for module in (_config, _auth):
+        monkeypatch.setattr(module, "get_config_manager", lambda: manager)
+        monkeypatch.setattr(module, "check_auth", lambda _request: True)
+    monkeypatch.setattr(_config, "_BACKUP_DIR", backups)
+    monkeypatch.setattr(_config, "validate_required_config", lambda: (True, "OK"))
+
+    def sync(*, prune: bool, write: bool) -> config_sync.ConfigTemplateSyncResult:
+        return config_sync.sync_config_file(
+            config_path=path, example_path=example, prune=prune, write=write
+        )
+
+    monkeypatch.setattr(_config, "sync_config_file", sync)
+    return ConfigTransactionFixture(path, example, backups, manager, app, sessions)
+
+
+async def _wait_thread_event(event: threading.Event) -> None:
+    assert await asyncio.wait_for(asyncio.to_thread(event.wait, 2), timeout=3)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("endpoint", ["save", "patch", "restore", "sync", "password"])
+async def test_config_request_repeated_cancellation_finishes_write_and_main_loop_reload(
+    transaction_config: ConfigTransactionFixture,
+    monkeypatch: pytest.MonkeyPatch,
+    endpoint: str,
+) -> None:
+    fixture = transaction_config
+    loop = asyncio.get_running_loop()
+    reloaded_on: list[asyncio.AbstractEventLoop] = []
+
+    def on_reload(_config_value: Any, _changes: Any) -> None:
+        reloaded_on.append(asyncio.get_running_loop())
+
+    fixture.manager.subscribe(on_reload)
+    session = fixture.sessions.create()
+    tokens = fixture.sessions.issue_auth_tokens()
+    entered = threading.Event()
+    release = threading.Event()
+    original_write = async_io.write_text_sync
+
+    def blocked_write(
+        file_path: Path | str, content: str, use_lock: bool = True
+    ) -> None:
+        if Path(file_path) == fixture.path:
+            entered.set()
+            assert release.wait(3), "test did not release configuration write"
+        original_write(file_path, content, use_lock)
+
+    monkeypatch.setattr(async_io, "write_text_sync", blocked_write)
+    monkeypatch.setattr(config_sync, "write_text_sync", blocked_write)
+    if endpoint == "save":
+        operation = _config.save_config_handler(
+            fixture.request(
+                {"content": fixture.path.read_text().replace("11111", "22222")}
+            )
+        )
+    elif endpoint == "patch":
+        operation = _config.config_patch_handler(
+            fixture.request({"patch": {"api.port": 22222}})
+        )
+    elif endpoint == "restore":
+        operation = _config.config_restore_handler(
+            fixture.request({"name": "config_fixture.toml"})
+        )
+    elif endpoint == "sync":
+        operation = _config.sync_config_template_handler(fixture.request())
+    else:
+        operation = _auth.password_handler(
+            fixture.request(
+                {
+                    "current_password": "previous-secret",
+                    "new_password": "updated-secret",
+                }
+            )
+        )
+
+    async def perform_request() -> web.StreamResponse:
+        return await operation
+
+    task = asyncio.create_task(perform_request())
+    try:
+        await _wait_thread_event(entered)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=3)
+        parsed = tomllib.loads(fixture.path.read_text())
+        assert reloaded_on == [loop]
+        loaded = fixture.manager.load(strict=False)
+        assert loaded.api.port == parsed["api"]["port"]
+        if endpoint in {"save", "patch"}:
+            assert loaded.api.port == 22222
+        elif endpoint == "restore":
+            assert loaded.api.port == 33333
+        elif endpoint == "sync":
+            assert parsed["webui"]["stop_timeout_seconds"] == 3
+        else:
+            assert parsed["webui"]["password"] == "updated-secret"
+            assert fixture.app[SETTINGS_APP_KEY].password == "updated-secret"
+            assert not fixture.sessions.is_valid(session)
+            assert not fixture.sessions.is_valid(str(tokens["access_token"]))
+            assert not fixture.sessions.is_valid(str(tokens["refresh_token"]))
+    finally:
+        release.set()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("first_operation", ["sync", "patch"])
+async def test_template_sync_and_patch_preserve_both_changes_in_either_order(
+    transaction_config: ConfigTransactionFixture,
+    monkeypatch: pytest.MonkeyPatch,
+    first_operation: str,
+) -> None:
+    fixture = transaction_config
+    first_write_entered = threading.Event()
+    release_first_write = threading.Event()
+    second_lock_attempted = threading.Event()
+    original_write = async_io.write_text_sync
+    original_lock = config_io.config_write_lock
+    thread_lock = threading.Lock()
+    lock_count = 0
+    write_count = 0
+
+    def tracked_lock(path: Path) -> Any:
+        nonlocal lock_count
+        with thread_lock:
+            lock_count += 1
+            if lock_count == 2:
+                second_lock_attempted.set()
+        return original_lock(path)
+
+    def blocked_write(
+        file_path: Path | str, content: str, use_lock: bool = True
+    ) -> None:
+        nonlocal write_count
+        with thread_lock:
+            write_count += 1
+            first = write_count == 1
+        if first:
+            first_write_entered.set()
+            assert release_first_write.wait(3), "test did not release first write"
+        original_write(file_path, content, use_lock)
+
+    monkeypatch.setattr(async_io, "write_text_sync", blocked_write)
+    monkeypatch.setattr(config_sync, "write_text_sync", blocked_write)
+    monkeypatch.setattr(_config, "config_write_lock", tracked_lock)
+    monkeypatch.setattr(config_sync, "config_write_lock", tracked_lock)
+
+    async def sync() -> Any:
+        return await _config.sync_config_template_handler(fixture.request())
+
+    async def patch() -> Any:
+        return await _config.config_patch_handler(
+            fixture.request({"patch": {"api.port": 22222}})
+        )
+
+    first = asyncio.create_task(sync() if first_operation == "sync" else patch())
+    second: asyncio.Task[Any] | None = None
+    try:
+        await _wait_thread_event(first_write_entered)
+        second = asyncio.create_task(patch() if first_operation == "sync" else sync())
+        await _wait_thread_event(second_lock_attempted)
+        assert not second.done()
+        release_first_write.set()
+        responses = await asyncio.wait_for(asyncio.gather(first, second), timeout=3)
+        assert [response.status for response in responses] == [200, 200]
+        parsed = tomllib.loads(fixture.path.read_text())
+        assert parsed["api"]["port"] == 22222
+        assert parsed["webui"]["stop_timeout_seconds"] == 3
+        assert fixture.manager.load(strict=False).api.port == 22222
+    finally:
+        release_first_write.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("reader", ["history", "restore"])
+@pytest.mark.parametrize("first_operation", ["read", "patch"])
+async def test_backup_reads_are_serialized_with_actual_backup_trimming(
+    transaction_config: ConfigTransactionFixture,
+    monkeypatch: pytest.MonkeyPatch,
+    reader: str,
+    first_operation: str,
+) -> None:
+    fixture = transaction_config
+    selected_backup = fixture.backups / "config_fixture.toml"
+    os.utime(selected_backup, ns=(1, 1))
+    monkeypatch.setattr(_config, "_MAX_BACKUPS", 1)
+    first_locked = threading.Event()
+    release_first = threading.Event()
+    second_attempted = threading.Event()
+    counter_lock = threading.Lock()
+    lock_count = 0
+    loop_thread = threading.get_ident()
+    original_lock = config_io.config_write_lock
+
+    class PausingConfigLock:
+        def __init__(self, lock: FileLock, first: bool) -> None:
+            self.lock = lock
+            self.first = first
+
+        def __enter__(self) -> PausingConfigLock:
+            self.lock.__enter__()
+            if self.first:
+                first_locked.set()
+                assert release_first.wait(3), "test did not release config lock"
+            return self
+
+        def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+            self.lock.__exit__(exc_type, exc, tb)
+
+    def tracked_lock(path: Path) -> PausingConfigLock:
+        nonlocal lock_count
+        assert threading.get_ident() != loop_thread
+        with counter_lock:
+            lock_count += 1
+            first = lock_count == 1
+            if lock_count == 2:
+                second_attempted.set()
+        return PausingConfigLock(original_lock(path), first)
+
+    monkeypatch.setattr(_config, "config_write_lock", tracked_lock)
+
+    async def read_backup() -> web.StreamResponse:
+        if reader == "history":
+            return await _config.config_history_handler(fixture.request())
+        return await _config.config_restore_handler(
+            fixture.request({"name": selected_backup.name})
+        )
+
+    async def patch() -> web.StreamResponse:
+        return await _config.config_patch_handler(
+            fixture.request({"patch": {"api.port": 22222}})
+        )
+
+    first = asyncio.create_task(read_backup() if first_operation == "read" else patch())
+    second: asyncio.Task[web.StreamResponse] | None = None
+    try:
+        await _wait_thread_event(first_locked)
+        second = asyncio.create_task(
+            patch() if first_operation == "read" else read_backup()
+        )
+        await _wait_thread_event(second_attempted)
+        assert not second.done()
+        release_first.set()
+        first_response, second_response = await asyncio.wait_for(
+            asyncio.gather(first, second), timeout=3
+        )
+        read_response = first_response if first_operation == "read" else second_response
+        patch_response = (
+            first_response if first_operation == "patch" else second_response
+        )
+        assert patch_response.status == 200
+        assert not selected_backup.exists()
+        assert len(list(fixture.backups.glob("config_*.toml"))) == 1
+        assert tomllib.loads(fixture.path.read_text())["api"]["port"] == 22222
+        if reader == "restore" and first_operation == "patch":
+            assert read_response.status == 404
+        else:
+            assert read_response.status == 200
+        if reader == "history":
+            payload = json.loads(cast(web.Response, read_response).text or "{}")
+            names = [backup["name"] for backup in payload["backups"]]
+            assert (selected_backup.name in names) is (first_operation == "read")
+    finally:
+        release_first.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )

From d6f531d4df8f3fcdb0884a23b132852bcdb0b269 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:42:15 +0800
Subject: [PATCH 082/121] fix(chat): preserve snapshot and nested agent
 timelines

---
 apps/undefined-chat/README.md                 |   4 +-
 .../src/chat-store/snapshot-recovery.test.tsx | 468 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   | 172 ++++++-
 apps/undefined-chat/src/chat-store/types.ts   |   4 +-
 .../src/message-timeline/MessageTimeline.tsx  |   5 +
 .../MessageTimelineContent.test.tsx           |  46 ++
 .../MessageTimelineContent.tsx                |  67 ++-
 .../src/message-timeline/ToolBlock.README.md  |  16 +-
 .../src/message-timeline/ToolBlock.tsx        |  63 ++-
 .../src/runtime-client/tauri.ts               |  85 +++-
 .../src/runtime-client/types.ts               |   2 +
 docs/undefined-chat.md                        |  10 +-
 12 files changed, 864 insertions(+), 78 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index b0d7e71f..e5e0bc2d 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -16,7 +16,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 工具调用块：层级展示、状态、运行中实时计时、阶段明细（stage detail）、与 WebUI 一致的输入/输出预览（JSON/Python 风格结构化、Markdown 输出、附件图片预览）；历史回放支持 timeline/calls/events 多级回退。
 - 自动滚动：智能跟随底部，可在设置面板开关，偏好持久化到 localStorage。
 - 重命名只更新目标会话标题，保留当前会话、输入草稿与移动端面板；请求期间切换会话也不会被迟到响应切回。
-- 事件：SSE 优先，断开时 JSON fallback（指数退避重连，活跃任务持续重试）。
+- 事件：SSE 优先，断开时 JSON fallback（指数退避重连，活跃任务持续重试）；完整任务快照恢复消息与已结束调用，并按快照游标续接，旧 Runtime 的正文前缀也会保留。
 - 快捷键：Ctrl/Cmd+N 新会话，Ctrl/Cmd+K 聚焦输入并打开命令模式，Ctrl/Cmd+/ 切换侧栏，Ctrl/Cmd+, 打开设置，Escape 关闭当前弹层/抽屉。
 - i18n：中英双语运行时切换，提供语言切换 UI，并按系统语言自动检测默认语言。
 
@@ -31,7 +31,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 Android：
 
 - 文件选择器返回的 `content://` URI 通过 Tauri fs plugin 打开，上传链路仍需要真机/模拟器 smoke 覆盖。
-- 生命周期监听使用 Tauri `tauri://suspended` / `tauri://resumed` 事件；恢复前台时重新 bootstrap 并恢复 Runtime 订阅。逐 job 主动补齐仍依赖 store 的 SSE 断线 fallback 行为。
+- 生命周期监听使用 Tauri `tauri://suspended` / `tauri://resumed` 事件；恢复前台时重新 bootstrap，接受 Runtime 的完整任务时间线与对应游标后恢复订阅；快照内已有事件不会重复追加。
 - Android 通过生成工程注入的 `SecretPlugin` 使用 Android Keystore + AES-GCM 保存 API Key：密钥在 AndroidKeyStore 中生成且不可导出，加密后的密文存放在 `MODE_PRIVATE` 的 SharedPreferences 中。Android 生成插件已接入并有脚本/Rust 测试覆盖，真实设备仍需 smoke 验证；只有平台安全存储不可用且用户显式确认时，才允许不安全文件降级。
 
 iOS：
diff --git a/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx b/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx
new file mode 100644
index 00000000..9740199c
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx
@@ -0,0 +1,468 @@
+import { invoke } from "@tauri-apps/api/core";
+import { screen, within } from "@testing-library/react";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { MessageTimeline } from "../message-timeline/MessageTimeline";
+import { createTauriRuntimeClient } from "../runtime-client/tauri";
+import type { ChatJob } from "../runtime-client/types";
+import { event, job, runtimeClientStub } from "../test-fixtures";
+import { renderWithProviders } from "../test-utils";
+import { createChatStore } from "./store";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+
+function renderJob(activeJob: ChatJob) {
+	return renderWithProviders(
+		<MessageTimeline
+			items={[]}
+			activeJob={activeJob}
+			connectionState="streaming"
+			hasMoreHistory={false}
+			onLoadMoreHistory={vi.fn()}
+			onPreviewAttachment={vi.fn()}
+			onPreviewHtml={vi.fn()}
+			onSaveAttachment={vi.fn()}
+		/>,
+	);
+}
+
+function nativeSnapshot(lastSeq: number) {
+	return {
+		job_id: "job-1",
+		conversation_id: "default",
+		status: "running",
+		last_seq: lastSeq,
+		reply: "Agent before\n\nAgent after\n\nMain answer",
+		history_finalized: false,
+		current_tool_calls: [
+			{
+				webchat_call_id: "agent",
+				name: "research",
+				is_agent: true,
+				status: "running",
+				current_stage: "thinking",
+				current_stage_detail: "Model detail",
+				elapsed_ms: 1000,
+			},
+		],
+		current_timeline: [
+			{
+				type: "call",
+				seq: 1,
+				call: {
+					id: "agent",
+					name: "research",
+					status: "running",
+					is_agent: true,
+					children: [{ id: "nested", name: "search", status: "done" }],
+					timeline: [
+						{ type: "message", seq: 2, content: "Agent before" },
+						{
+							type: "call",
+							seq: 3,
+							call: { id: "nested", name: "search", status: "done" },
+						},
+						{ type: "message", seq: 4, content: "Agent after" },
+					],
+				},
+			},
+			{ type: "message", seq: 5, content: "Main answer" },
+		],
+	};
+}
+
+describe("job snapshot recovery", () => {
+	beforeEach(() => vi.resetAllMocks());
+
+	test("keeps a legacy snapshot prefix when the next SSE message arrives", async () => {
+		const active = job({ lastSeq: 6, reply: "Saved prefix" });
+		const store = createChatStore({
+			client: runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+			}),
+		});
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			event({ seq: 7, event: "message", payload: { content: "Next message" } }),
+		]);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		expect(screen.getByText("Saved prefix")).toBeTruthy();
+		expect(screen.getByText("Next message")).toBeTruthy();
+	});
+
+	test("cold native snapshots preserve completed tools and nested message order", async () => {
+		vi.mocked(invoke).mockResolvedValue({
+			status: 200,
+			ok: true,
+			body: { job: nativeSnapshot(6), jobs: [nativeSnapshot(6)] },
+		});
+		const native = createTauriRuntimeClient();
+		const store = createChatStore({
+			client: runtimeClientStub({ getActiveJobs: native.getActiveJobs }),
+		});
+		await store.bootstrap();
+		const active = store.getSnapshot().activeJobsByConversation.default;
+		expect(active.currentToolCalls[0]?.children?.[0]?.status).toBe("done");
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(6);
+		renderJob(active);
+		const agent = screen.getByText("research").closest("details");
+		expect(agent).not.toBeNull();
+		expect(within(agent as HTMLElement).getByText("Agent before")).toBeTruthy();
+		expect(within(agent as HTMLElement).getByText("Agent after")).toBeTruthy();
+		expect(screen.getAllByText("Agent before")).toHaveLength(1);
+		expect(screen.getByText(/Model detail/)).toBeTruthy();
+		const before = screen.getByText("Agent before"),
+			search = screen.getByText("search"),
+			after = screen.getByText("Agent after");
+		expect(
+			before.compareDocumentPosition(search) & Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+		expect(
+			search.compareDocumentPosition(after) & Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+		expect(agent?.contains(screen.getByText("Main answer"))).toBe(false);
+	});
+
+	test.each([false, true])(
+		"resume advances the cursor with its accepted snapshot (legacy: %s)",
+		async (legacy) => {
+			const native = createTauriRuntimeClient();
+			let snapshot = nativeSnapshot(6);
+			vi.mocked(invoke).mockImplementation(async () => {
+				const raw: Record<string, unknown> = { ...snapshot };
+				if (legacy) delete raw.current_timeline;
+				return { status: 200, ok: true, body: { job: raw, jobs: [raw] } };
+			});
+			const client = runtimeClientStub({ getActiveJobs: native.getActiveJobs });
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			snapshot = {
+				...nativeSnapshot(7),
+				reply:
+					"Agent before\n\nAgent after\n\nMain answer\n\nSnapshot addition",
+				current_timeline: [
+					...nativeSnapshot(7).current_timeline,
+					{ type: "message", seq: 7, content: "Snapshot addition" },
+				],
+			};
+			await store.bootstrap({ resuming: true });
+			expect(client.startJobEventStream).toHaveBeenLastCalledWith({
+				jobId: "job-1",
+				conversationId: "default",
+				afterSeq: 7,
+			});
+			store.applyRuntimeEvents("job-1", [
+				event({
+					seq: 7,
+					event: "message",
+					payload: { content: "Snapshot addition" },
+				}),
+			]);
+			expect(
+				store
+					.getSnapshot()
+					.activeJobsByConversation.default.reply.match(/Snapshot addition/g),
+			).toHaveLength(1);
+			renderJob(store.getSnapshot().activeJobsByConversation.default);
+			expect(screen.getAllByText(/Snapshot addition/)).toHaveLength(1);
+		},
+	);
+
+	test("streamed agent messages stay in their parent without a duplicated reply fallback", async () => {
+		const active = job();
+		const store = createChatStore({
+			client: runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+			}),
+		});
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			event({
+				seq: 1,
+				event: "agent_start",
+				payload: { webchat_call_id: "agent", name: "research", is_agent: true },
+			}),
+			event({
+				seq: 2,
+				event: "message",
+				payload: {
+					content: "Only inside agent",
+					parent_webchat_call_id: "agent",
+				},
+			}),
+		]);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		const agent = screen.getByText("research").closest("details");
+		expect(
+			within(agent as HTMLElement).getByText("Only inside agent"),
+		).toBeTruthy();
+		expect(screen.getAllByText("Only inside agent")).toHaveLength(1);
+	});
+
+	test("nested streamed agents retain message/call order and do not leak a fallback at the root", async () => {
+		const active = job();
+		const store = createChatStore({
+			client: runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+			}),
+		});
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			event({
+				seq: 1,
+				event: "agent_start",
+				payload: { webchat_call_id: "outer", name: "outer", is_agent: true },
+			}),
+			event({
+				seq: 2,
+				event: "agent_start",
+				payload: {
+					webchat_call_id: "inner",
+					name: "inner",
+					is_agent: true,
+					parent_webchat_call_id: "outer",
+				},
+			}),
+			event({
+				seq: 3,
+				event: "message",
+				payload: { content: "Before search", parent_webchat_call_id: "inner" },
+			}),
+			event({
+				seq: 4,
+				event: "tool_start",
+				payload: {
+					webchat_call_id: "search",
+					name: "search",
+					parent_webchat_call_id: "inner",
+				},
+			}),
+			event({
+				seq: 5,
+				event: "tool_end",
+				payload: {
+					webchat_call_id: "search",
+					name: "search",
+					parent_webchat_call_id: "inner",
+					ok: true,
+				},
+			}),
+			event({
+				seq: 6,
+				event: "message",
+				payload: { content: "After search", parent_webchat_call_id: "inner" },
+			}),
+		]);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		const inner = screen.getByText("inner").closest("details");
+		expect(inner?.contains(screen.getByText("Before search"))).toBe(true);
+		expect(inner?.contains(screen.getByText("After search"))).toBe(true);
+		expect(screen.getAllByText("Before search")).toHaveLength(1);
+		expect(screen.getAllByText("search")).toHaveLength(1);
+		expect(
+			screen
+				.getByText("Before search")
+				.compareDocumentPosition(screen.getByText("search")) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+		expect(
+			screen
+				.getByText("search")
+				.compareDocumentPosition(screen.getByText("After search")) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+	});
+
+	test("JSON recovery applies the complete snapshot and rejects its duplicated event", async () => {
+		vi.mocked(invoke).mockResolvedValue({
+			status: 200,
+			ok: true,
+			body: {
+				job: nativeSnapshot(6),
+				events: [
+					{ seq: 5, event: "message", payload: { content: "Main answer" } },
+				],
+			},
+		});
+		const native = createTauriRuntimeClient();
+		const active = job();
+		const store = createChatStore({
+			client: runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+				fetchJobEventsJson: native.fetchJobEventsJson,
+			}),
+		});
+		await store.bootstrap();
+		store.handleRuntimeStatus({
+			jobId: "job-1",
+			subscriptionId: "sub-1",
+			status: "error",
+			detail: "disconnected",
+		});
+		await vi.waitFor(() =>
+			expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(6),
+		);
+		store.applyRuntimeEvents("job-1", [
+			event({ seq: 5, event: "message", payload: { content: "Main answer" } }),
+		]);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		expect(screen.getAllByText("Main answer")).toHaveLength(1);
+		expect(screen.getAllByText("Agent before")).toHaveLength(1);
+		store.suspendRuntime();
+	});
+
+	test("legacy JSON snapshots recover message gaps outside the replay buffer", async () => {
+		const active = job({ lastSeq: 6, reply: "Prefix", messages: ["Prefix"] });
+		const store = createChatStore({
+			client: runtimeClientStub({
+				getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+				fetchJobEventsJson: vi.fn(async () => ({
+					job: job({
+						lastSeq: 9,
+						reply: "Prefix\n\nMissing buffered message\n\nLatest",
+						messages: ["Prefix", "Missing buffered message", "Latest"],
+					}),
+					events: [
+						event({ seq: 9, event: "message", payload: { content: "Latest" } }),
+					],
+					after: 6,
+					lastSeq: 9,
+				})),
+			}),
+		});
+		await store.bootstrap();
+		store.handleRuntimeStatus({
+			jobId: "job-1",
+			subscriptionId: "sub-1",
+			status: "error",
+			detail: "disconnected",
+		});
+		await vi.waitFor(() =>
+			expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(9),
+		);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		expect(screen.getByText("Prefix")).toBeTruthy();
+		expect(screen.getByText("Missing buffered message")).toBeTruthy();
+		expect(screen.getAllByText("Latest")).toHaveLength(1);
+		store.suspendRuntime();
+	});
+
+	test("a late bootstrap snapshot cannot roll back events consumed while it was loading", async () => {
+		const active = job({ lastSeq: 6, reply: "Prefix" });
+		let resolveSnapshot!: (value: { job: ChatJob; jobs: ChatJob[] }) => void;
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		vi.mocked(client.getActiveJobs).mockImplementationOnce(
+			() =>
+				new Promise((resolve) => {
+					resolveSnapshot = resolve;
+				}),
+		);
+		const bootstrap = store.bootstrap({ resuming: true });
+		await vi.waitFor(() => expect(resolveSnapshot).toBeDefined());
+		store.applyRuntimeEvents("job-1", [
+			event({ seq: 8, event: "message", payload: { content: "Newer event" } }),
+		]);
+		resolveSnapshot({ job: active, jobs: [active] });
+		await bootstrap;
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(8);
+		expect(client.startJobEventStream).toHaveBeenLastCalledWith({
+			jobId: "job-1",
+			conversationId: "default",
+			afterSeq: 8,
+		});
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		expect(screen.getByText("Newer event")).toBeTruthy();
+	});
+
+	test("a tool recovered inside a snapshot uses its later streamed completion", async () => {
+		const snapshot = nativeSnapshot(6);
+		const agent = snapshot.current_timeline[0].call;
+		if (!agent) throw new Error("fixture must contain the agent");
+		agent.children[0].status = "running";
+		const child = agent.timeline[1].call;
+		if (!child) throw new Error("fixture must contain the child");
+		child.status = "running";
+		vi.mocked(invoke).mockResolvedValue({
+			status: 200,
+			ok: true,
+			body: { job: snapshot, jobs: [snapshot] },
+		});
+		const native = createTauriRuntimeClient();
+		const store = createChatStore({
+			client: runtimeClientStub({ getActiveJobs: native.getActiveJobs }),
+		});
+		await store.bootstrap();
+		store.applyRuntimeEvents("job-1", [
+			event({
+				seq: 7,
+				event: "tool_end",
+				payload: {
+					webchat_call_id: "nested",
+					parent_webchat_call_id: "agent",
+					name: "search",
+					ok: true,
+					result_preview: "Latest completed result",
+				},
+			}),
+		]);
+		renderJob(store.getSnapshot().activeJobsByConversation.default);
+		expect(
+			screen.getByText("search").closest("details")?.classList.contains("done"),
+		).toBe(true);
+		expect(screen.getByText("Latest completed result")).toBeTruthy();
+		expect(screen.getAllByText("search")).toHaveLength(1);
+	});
+
+	test.each([false, true])(
+		"an in-flight JSON snapshot cannot overwrite later SSE (complete timeline: %s)",
+		async (complete) => {
+			let resolveSnapshot!: (value: unknown) => void;
+			vi.mocked(invoke).mockImplementation(
+				() =>
+					new Promise((resolve) => {
+						resolveSnapshot = resolve;
+					}),
+			);
+			const native = createTauriRuntimeClient();
+			const active = job();
+			const store = createChatStore({
+				client: runtimeClientStub({
+					getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+					fetchJobEventsJson: native.fetchJobEventsJson,
+				}),
+			});
+			await store.bootstrap();
+			store.handleRuntimeStatus({
+				jobId: "job-1",
+				subscriptionId: "sub-1",
+				status: "error",
+				detail: "disconnected",
+			});
+			store.applyRuntimeEvents("job-1", [
+				event({
+					seq: 8,
+					event: "message",
+					payload: { content: "Newer SSE message" },
+				}),
+			]);
+			const latest = store.getSnapshot().activeJobsByConversation.default;
+			const snapshot: Record<string, unknown> = nativeSnapshot(6);
+			if (!complete) delete snapshot.current_timeline;
+			resolveSnapshot({
+				status: 200,
+				ok: true,
+				body: { job: snapshot, events: [] },
+			});
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			expect(store.getSnapshot().activeJobsByConversation.default).toEqual(
+				latest,
+			);
+			expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(8);
+			store.suspendRuntime();
+		},
+	);
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 24eb3950..3912a9ad 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -178,6 +178,32 @@ export function isJobRunning(job: ChatJob | null | undefined): boolean {
 	);
 }
 
+function acceptJobSnapshot(job: ChatJob, previous?: ChatJob): ChatJob {
+	if (job.hasTimelineSnapshot || job.currentTimeline.length > 0) return job;
+	const sameJob = previous?.jobId === job.jobId ? previous : undefined;
+	if (sameJob && job.reply === sameJob.reply) {
+		return {
+			...job,
+			currentTimeline: sameJob.currentTimeline,
+			currentToolCalls: sameJob.currentToolCalls,
+		};
+	}
+	// 旧 Runtime 没有 timeline，先保存完整正文前缀，再续接快照之后的事件。
+	return {
+		...job,
+		currentTimeline: [
+			...(job.reply
+				? [{ type: "message" as const, seq: job.lastSeq, content: job.reply }]
+				: []),
+			...job.currentToolCalls.map((call) => ({
+				type: "call" as const,
+				seq: job.lastSeq,
+				callId: call.id,
+			})),
+		],
+	};
+}
+
 export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 	switch (action.type) {
 		case "connection/set":
@@ -190,7 +216,14 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 				error: null,
 			};
 		case "bootstrap/success": {
-			const activeJobs = activeJobsByConversation(action.activeJobs);
+			const snapshots = action.activeJobs.map((job) => {
+				const previous = state.activeJobsByConversation[job.conversationId];
+				// 订阅仍可能在 bootstrap 请求期间前进；更旧快照不能倒退已展示事件。
+				if (previous?.jobId === job.jobId && previous.lastSeq > job.lastSeq)
+					return previous;
+				return acceptJobSnapshot(job, previous);
+			});
+			const activeJobs = activeJobsByConversation(snapshots);
 			return {
 				...state,
 				bootstrapping: false,
@@ -204,7 +237,13 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 				})),
 				selectedConversationId: action.selectedConversationId,
 				activeJobsByConversation: activeJobs,
-				jobConversationById: jobConversationById(action.activeJobs),
+				jobConversationById: jobConversationById(snapshots),
+				eventCursorByJob: {
+					...state.eventCursorByJob,
+					...Object.fromEntries(
+						snapshots.map((job) => [job.jobId, job.lastSeq]),
+					),
+				},
 				commands: action.commands,
 				error: null,
 			};
@@ -354,6 +393,7 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 			return { ...state, sendError: action.error };
 		case "commands/set":
 			return { ...state, commands: action.commands };
+		case "job/snapshot":
 		case "job/upsert": {
 			const activeJobs = { ...state.activeJobsByConversation };
 			const jobConversations = {
@@ -370,6 +410,16 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 				...state,
 				activeJobsByConversation: activeJobs,
 				jobConversationById: jobConversations,
+				eventCursorByJob:
+					action.type === "job/snapshot"
+						? {
+								...state.eventCursorByJob,
+								[action.job.jobId]: Math.max(
+									state.eventCursorByJob[action.job.jobId] ?? 0,
+									action.job.lastSeq,
+								),
+							}
+						: state.eventCursorByJob,
 				conversations: state.conversations.map((item) =>
 					item.id === action.job.conversationId
 						? { ...item, isRunning: isJobRunning(action.job) }
@@ -632,6 +682,23 @@ function chatEventFromRuntimeEvent(event: RuntimeSseEvent): ChatEvent {
  * 对齐 WebUI upsertTimelineToolBlock 的 key 策略（webchat_call_id || tool_call_id）。
  * 有 parentCallId 时在匹配父块的 children 里递归 upsert；否则在顶层 upsert。
  */
+function updateToolCall(
+	list: ToolCallSnapshot[],
+	callId: string,
+	patch: (call: ToolCallSnapshot) => ToolCallSnapshot,
+): ToolCallSnapshot[] {
+	return list.map((call) =>
+		call.id === callId
+			? patch(call)
+			: {
+					...call,
+					children: call.children
+						? updateToolCall(call.children, callId, patch)
+						: undefined,
+				},
+	);
+}
+
 function upsertToolCall(
 	list: ToolCallSnapshot[],
 	callId: string,
@@ -835,7 +902,7 @@ export function createChatStore({
 		try {
 			const subscription = await client.startJobEventStream({
 				jobId: job.jobId,
-				afterSeq: state.eventCursorByJob[job.jobId] ?? job.lastSeq,
+				afterSeq: Math.max(state.eventCursorByJob[job.jobId] ?? 0, job.lastSeq),
 				conversationId: job.conversationId,
 			});
 			if (generation !== runtimeGeneration) {
@@ -949,20 +1016,28 @@ export function createChatStore({
 				}
 				// 拉取成功：重置退避间隔
 				fallbackBackoffByJob.delete(jobId);
-				// 先续接事件保留此前时间线，再应用权威正文快照，避免增量重复计数。
-				applyRuntimeEvents(jobId, response.events);
+				if (!response.job.hasTimelineSnapshot) {
+					// 旧服务仅提供 reply；先回放增量以保留已有调用树。
+					applyRuntimeEvents(jobId, response.events);
+				}
 				const replayedJob =
 					state.activeJobsByConversation[response.job.conversationId];
-				dispatch({
-					type: "job/upsert",
-					job: {
-						...response.job,
-						currentTimeline: replayedJob?.currentTimeline ?? [],
-						// Runtime 运行快照只含未结束调用，完整调用树由事件回放保留。
-						currentToolCalls:
-							replayedJob?.currentToolCalls ?? response.job.currentToolCalls,
-					},
-				});
+				const replayComplete =
+					!response.job.messages.length ||
+					JSON.stringify(response.job.messages) ===
+						JSON.stringify(replayedJob?.messages);
+				const snapshot = response.job.hasTimelineSnapshot
+					? response.job
+					: acceptJobSnapshot({
+							...response.job,
+							currentTimeline: replayComplete
+								? (replayedJob?.currentTimeline ?? [])
+								: [],
+							currentToolCalls:
+								replayedJob?.currentToolCalls ?? response.job.currentToolCalls,
+						});
+				dispatch({ type: "job/snapshot", job: snapshot });
+
 				if (isJobRunning(response.job)) {
 					scheduleFallbackPolling(jobId, JSON_FALLBACK_BASE_MS);
 				} else if (response.job.conversationId) {
@@ -1306,7 +1381,7 @@ export function createChatStore({
 			dispatch({ type: "send/error", error: null });
 			const job = await client.sendMessage(input);
 			if (generation !== runtimeGeneration) return;
-			dispatch({ type: "job/upsert", job });
+			dispatch({ type: "job/snapshot", job: acceptJobSnapshot(job) });
 			dispatch({ type: "connection/set", connectionState: "streaming" });
 			await startStreamForJob(job);
 		} catch (err) {
@@ -1529,7 +1604,9 @@ export function createChatStore({
 			conversationId && state.activeJobsByConversation[conversationId];
 		if (activeJob && activeJob.jobId === jobId) {
 			let updatedJob = activeJob;
-			const newEvents = events.filter((item) => item.seq > prevCursor);
+			const newEvents = (state.eventsByJob[jobId] ?? []).filter(
+				(item) => item.seq > prevCursor,
+			);
 			for (const event of newEvents) {
 				if (event.event === "stage" && event.payload) {
 					// stage 事件：更新 currentStage/Detail/StartedAt（对齐 WebUI setChatStage）
@@ -1558,14 +1635,38 @@ export function createChatStore({
 						event.payload.content ?? event.payload.message ?? "",
 					);
 					if (content) {
+						const parentCallId = String(
+							event.payload.parent_webchat_call_id || "",
+						);
 						updatedJob = {
 							...updatedJob,
 							reply: updatedJob.reply + content,
-							currentTimeline: [
-								...updatedJob.currentTimeline,
-								{ type: "message", seq: event.seq, content },
-							],
+							messages: [...updatedJob.messages, content],
 						};
+						if (parentCallId) {
+							updatedJob = {
+								...updatedJob,
+								currentToolCalls: updateToolCall(
+									updatedJob.currentToolCalls,
+									parentCallId,
+									(parent) => ({
+										...parent,
+										timeline: [
+											...(parent.timeline ?? []),
+											{ type: "message", seq: event.seq, content },
+										],
+									}),
+								),
+							};
+						} else {
+							updatedJob = {
+								...updatedJob,
+								currentTimeline: [
+									...updatedJob.currentTimeline,
+									{ type: "message", seq: event.seq, content },
+								],
+							};
+						}
 					}
 				} else if (
 					event.event === "tool_start" ||
@@ -1624,6 +1725,22 @@ export function createChatStore({
 								}),
 							),
 						};
+						if (isStart && parentCallId) {
+							updatedJob = {
+								...updatedJob,
+								currentToolCalls: updateToolCall(
+									updatedJob.currentToolCalls,
+									parentCallId,
+									(parent) => ({
+										...parent,
+										timeline: [
+											...(parent.timeline ?? []),
+											{ type: "call", seq: event.seq, callId },
+										],
+									}),
+								),
+							};
+						}
 						// 顶层 tool_start/agent_start 首次进入主时间线（对齐 WebUI append 顺序；
 						// 嵌套子工具在父块 children 内，由 ToolBlock 递归渲染，不进主时间线）
 						if (
@@ -1682,8 +1799,17 @@ export function createChatStore({
 					}
 				}
 			}
-			if (updatedJob !== activeJob) {
-				dispatch({ type: "job/upsert", job: updatedJob });
+			if (newEvents.length > 0) {
+				dispatch({
+					type: "job/upsert",
+					job: {
+						...updatedJob,
+						lastSeq: Math.max(
+							updatedJob.lastSeq,
+							state.eventCursorByJob[jobId] ?? 0,
+						),
+					},
+				});
 			}
 		}
 
diff --git a/apps/undefined-chat/src/chat-store/types.ts b/apps/undefined-chat/src/chat-store/types.ts
index 0f2889fc..f6ec8523 100644
--- a/apps/undefined-chat/src/chat-store/types.ts
+++ b/apps/undefined-chat/src/chat-store/types.ts
@@ -44,7 +44,8 @@ export type ToolBlockStatus = "running" | "done" | "error" | "cancelled";
 export type TimelineEntry =
 	| { type: "input"; timestamp: number; content: string }
 	| { type: "output"; timestamp: number; content: string }
-	| { type: "error"; timestamp: number; message: string };
+	| { type: "error"; timestamp: number; message: string }
+	| { type: "call"; timestamp: number; callId: string };
 
 export type ToolBlock = {
 	webchatCallId: string;
@@ -213,6 +214,7 @@ export type ChatAction =
 	| { type: "send/error"; error: string | null }
 	// 任务与事件
 	| { type: "job/upsert"; job: ChatJob }
+	| { type: "job/snapshot"; job: ChatJob }
 	| { type: "job/remove"; conversationId: string; jobId: string }
 	| { type: "events/apply"; jobId: string; events: ChatEvent[] }
 	// 工具块
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimeline.tsx b/apps/undefined-chat/src/message-timeline/MessageTimeline.tsx
index 9e379123..050acf75 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimeline.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimeline.tsx
@@ -95,6 +95,7 @@ function convertToolCallSnapshot(snap: ToolCallSnapshot): HistoryToolCall {
 		ui_hint: snap.uiHint,
 		duration_ms: snap.durationMs ?? snap.elapsedMs ?? undefined,
 		current_stage: snap.currentStage,
+		current_stage_detail: snap.detail,
 		children: snap.children?.map(convertToolCallSnapshot),
 		timeline: snap.timeline,
 	};
@@ -849,6 +850,9 @@ export function MessageTimeline({
 											<MessageTimelineContent
 												timeline={timeline}
 												fallbackContent={item.content}
+												completeTimeline={Boolean(
+													item.webchat?.timeline?.length,
+												)}
 												attachments={item.attachments}
 												onPreviewHtml={onPreviewHtml}
 												onImageClick={onOpenImage}
@@ -931,6 +935,7 @@ export function MessageTimeline({
 							<MessageTimelineContent
 								timeline={buildStreamingTimeline(activeJob)}
 								fallbackContent={activeJob.reply || ""}
+								completeTimeline
 								attachments={[]}
 								onPreviewHtml={onPreviewHtml}
 								onImageClick={onOpenImage}
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
index a423d9b7..84eeeb71 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
@@ -40,6 +40,52 @@ describe("hasRenderableTimeline", () => {
 });
 
 describe("MessageTimelineContent", () => {
+	test("keeps historical Agent messages and nested calls inside the Agent in order", () => {
+		renderContent(
+			<MessageTimelineContent
+				onPreviewHtml={vi.fn()}
+				fallbackContent="Before After Final"
+				timeline={[
+					{
+						type: "call",
+						call: {
+							id: "agent",
+							name: "research",
+							is_agent: true,
+							status: "done",
+							timeline: [
+								{ type: "message", content: "Before" },
+								{
+									type: "call",
+									call: { id: "nested", name: "search", status: "done" },
+								},
+								{ type: "message", content: "After" },
+							],
+						},
+					},
+					{ type: "message", content: "Final" },
+				]}
+			/>,
+		);
+		const agent = screen.getByText("research").closest("details");
+		expect(agent?.contains(screen.getByText("Before"))).toBe(true);
+		expect(agent?.contains(screen.getByText("After"))).toBe(true);
+		expect(agent?.contains(screen.getByText("Final"))).toBe(false);
+		expect(screen.getAllByText("Before")).toHaveLength(1);
+		expect(
+			screen
+				.getByText("Before")
+				.compareDocumentPosition(screen.getByText("search")) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+		expect(
+			screen
+				.getByText("search")
+				.compareDocumentPosition(screen.getByText("After")) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+	});
+
 	test("renders message text and tool calls in order without duplicating content", () => {
 		renderContent(
 			<MessageTimelineContent
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
index f3ff6e8d..3247a2cc 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
@@ -30,12 +30,16 @@ type HistoryTimelineEntry = {
 	stage?: string;
 	detail?: string;
 	call?: HistoryToolCall;
+	callId?: string;
+	seq?: number;
 };
 
 export type MessageTimelineContentProps = {
 	timeline: unknown[];
 	/** 完整正文，timeline 中无任何顶层 message 文本时作为兜底渲染 */
 	fallbackContent?: string;
+	/** 完整时间线内的 Agent 正文也已渲染；仅调用树回退仍可使用正文兜底。 */
+	completeTimeline?: boolean;
 	attachments?: Attachment[];
 	onPreviewHtml: (input: HtmlPreviewRequest) => void;
 	/**
@@ -61,6 +65,23 @@ function normalizeEntries(timeline: unknown[]): HistoryTimelineEntry[] {
 	);
 }
 
+function hasTimelineMessage(entries: HistoryTimelineEntry[]): boolean {
+	return entries.some((entry) =>
+		entry.type === "message"
+			? Boolean(entry.content?.trim())
+			: entry.type === "call" && isToolCall(entry.call)
+				? hasCallMessage(entry.call)
+				: false,
+	);
+}
+
+function hasCallMessage(call: HistoryToolCall): boolean {
+	return (
+		hasTimelineMessage(normalizeEntries(call.timeline ?? [])) ||
+		(call.children ?? []).some(hasCallMessage)
+	);
+}
+
 /**
  * 判断 timeline 是否包含可渲染的工具调用或消息片段。
  * 仅在为真时才走统一时间线渲染模式。
@@ -93,29 +114,30 @@ function convertHistoryToolCallToToolBlock(
 					? "cancelled"
 					: "done";
 
-	// 转换子工具调用（优先从 timeline 中提取，兼容旧的 children 字段）
 	const children = new Map<string, ToolBlockType>();
-
-	// 从 timeline 中提取子调用（新格式）
-	if (Array.isArray(call.timeline)) {
-		const childCalls = call.timeline.filter(
-			(e): e is HistoryTimelineEntry & { call: HistoryToolCall } =>
-				e.type === "call" && isToolCall(e.call),
-		);
-
-		childCalls.forEach((entry, idx) => {
-			const childBlock = convertHistoryToolCallToToolBlock(entry.call, idx);
-			children.set(childBlock.webchatCallId, childBlock);
-		});
-	}
-
-	// 兼容旧格式：直接的 children 数组
+	const timeline: ToolBlockType["timeline"] = [];
+	// 旧 children 与新版时间线引用同一子块，时间线保留 Agent 正文与调用的先后顺序。
 	if (Array.isArray(call.children)) {
 		call.children.forEach((child, idx) => {
 			const childBlock = convertHistoryToolCallToToolBlock(child, idx);
 			children.set(childBlock.webchatCallId, childBlock);
 		});
 	}
+	normalizeEntries(call.timeline ?? []).forEach((entry, idx) => {
+		const timestamp = entry.seq ?? idx;
+		if (entry.type === "message" && entry.content) {
+			timeline.push({ type: "output", timestamp, content: entry.content });
+		} else if (entry.type === "call") {
+			let callId = entry.callId;
+			if (isToolCall(entry.call)) {
+				const childBlock = convertHistoryToolCallToToolBlock(entry.call, idx);
+				callId = childBlock.webchatCallId;
+				children.set(callId, childBlock);
+			}
+			if (callId && children.has(callId))
+				timeline.push({ type: "call", timestamp, callId });
+		}
+	});
 
 	const now = Date.now();
 	const startTime = now - (call.duration_ms || 0);
@@ -132,7 +154,7 @@ function convertHistoryToolCallToToolBlock(
 		currentStage: call.current_stage,
 		stageDetail: call.current_stage_detail,
 		children,
-		timeline: [],
+		timeline,
 		startTime,
 		endTime,
 	};
@@ -145,14 +167,17 @@ function convertHistoryToolCallToToolBlock(
 export function MessageTimelineContent({
 	timeline,
 	fallbackContent,
+	completeTimeline = false,
 	attachments = [],
 	onPreviewHtml,
 	onImageClick,
 }: MessageTimelineContentProps) {
 	const entries = normalizeEntries(timeline);
-	const hasMessageText = entries.some(
-		(e) => e.type === "message" && Boolean(e.content?.trim()),
-	);
+	const hasMessageText =
+		entries.some(
+			(entry) => entry.type === "message" && Boolean(entry.content?.trim()),
+		) ||
+		(completeTimeline && hasTimelineMessage(entries));
 
 	// 本地图片预览状态：仅在外部未提供 onImageClick 时启用
 	const [previewImage, setPreviewImage] = useState<{
@@ -197,7 +222,7 @@ export function MessageTimelineContent({
 				return null;
 			})}
 
-			{/* timeline 中无任何顶层文本时，用完整正文兜底 */}
+			{/* 时间线完全没有正文时才兜底，避免重复展示 Agent 内正文。 */}
 			{!hasMessageText && fallbackContent?.trim() ? (
 				<MarkdownContent
 					content={fallbackContent}
diff --git a/apps/undefined-chat/src/message-timeline/ToolBlock.README.md b/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
index 800ea810..c41e6e2e 100644
--- a/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
+++ b/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
@@ -6,7 +6,7 @@
 
 - ✅ **可折叠展开** - 使用 `<details>` 元素实现原生折叠/展开（running 自动展开，done/error 后 2s 自动折叠，用户交互后不再自动折叠）
 - ✅ **状态指示** - 支持 running / done / error / cancelled 状态，带视觉反馈
-- ✅ **时间线展示** - 显示工具执行的输入、输出、错误历史
+- ✅ **时间线展示** - 显示工具执行的输入、输出、错误历史；Agent 内正文支持 Markdown，并与子调用按时间线顺序交错展示
 - ✅ **嵌套渲染** - 支持递归渲染子工具调用
 - ✅ **实时计时** - 运行中通过统一时钟 `useChatClock` 每 500ms 刷新用时，结束后定格；自动格式化（ms/s/m）
 - ✅ **Agent 阶段明细** - Agent 运行中在状态位展示阶段标签（`currentStage`），并可附加阶段明细 `stageDetail`（如模型名/子步骤）
@@ -37,7 +37,8 @@ export type ToolBlock = {
 export type TimelineEntry =
   | { type: "input"; timestamp: number; content: string }
   | { type: "output"; timestamp: number; content: string }
-  | { type: "error"; timestamp: number; message: string };
+  | { type: "error"; timestamp: number; message: string }
+  | { type: "call"; timestamp: number; callId: string };
 ```
 
 ## 使用示例
@@ -69,7 +70,12 @@ const toolBlock = {
 const childTool = { /* ... */ };
 const parentTool = {
   // ...
-  children: new Map([["child-id", childTool]])
+  children: new Map([["child-id", childTool]]),
+  timeline: [
+    { type: "output", timestamp: 1, content: "调用之前的说明" },
+    { type: "call", timestamp: 2, callId: "child-id" },
+    { type: "output", timestamp: 3, content: "调用之后的说明" }
+  ]
 };
 
 <ToolBlock {...parentTool} />
@@ -92,7 +98,7 @@ const toolBlocks = useStore(state => state.toolBlocksByJob[jobId]);
 实时运行的工具块由 store 维护；历史消息则由 `MessageTimelineContent` 消费一条已交错好的
 `timeline`，其中 `type === "call"` 的条目经 `convertHistoryToolCallToToolBlock` 转换为本组件所需的
 `ToolBlock`（映射 `arguments_preview`/`result_preview`/`is_agent`/`current_stage`/`current_stage_detail`
-等字段，并按 `duration_ms` 反推 `startTime`）。
+等字段，并按 `duration_ms` 反推 `startTime`）。嵌套 `message` 转为输出条目，`call` 引用对应子块；已被时间线引用的子块不会再次追加到末尾。
 
 `timeline` 由 `MessageTimeline` 的 `buildHistoryTimeline` 按可用性多级回退构建：
 
@@ -158,7 +164,7 @@ const toolBlocks = useStore(state => state.toolBlocksByJob[jobId]);
 - 状态样式（running / done / error）
 - 时长格式化（ms / s / m）
 - 折叠展开交互
-- 时间线渲染（input / output / error）
+- 时间线渲染（input / output / error / call），流式与历史 Agent 正文归属和子调用先后顺序
 - 嵌套子工具递归渲染（单个 / 多个）
 - 空状态处理（无时间线、无子工具）
 - 结果预览：JSON/Python 风格结构化、非结构化 Markdown、附件图片标签 fallback
diff --git a/apps/undefined-chat/src/message-timeline/ToolBlock.tsx b/apps/undefined-chat/src/message-timeline/ToolBlock.tsx
index aec975d6..a801c669 100644
--- a/apps/undefined-chat/src/message-timeline/ToolBlock.tsx
+++ b/apps/undefined-chat/src/message-timeline/ToolBlock.tsx
@@ -195,9 +195,12 @@ function renderPreviewSection({
 }
 
 function renderTimelineEntry(
-	entry: ToolBlockType["timeline"][number],
+	entry: Exclude<ToolBlockType["timeline"][number], { type: "call" }>,
 	index: number,
 	t: TranslateFn,
+	attachments: Attachment[],
+	onPreviewHtml: (input: HtmlPreviewRequest) => void,
+	onImageClick?: (src: string, alt: string) => void,
 ): React.ReactElement {
 	const content = entry.type === "error" ? entry.message : entry.content;
 	const label =
@@ -215,7 +218,14 @@ function renderTimelineEntry(
 	return (
 		<div className={className} key={index}>
 			<span className="timeline-label">{label}</span>
-			<div className="timeline-content">{content}</div>
+			<div className="timeline-content">
+				<MarkdownContent
+					content={content}
+					attachments={attachments}
+					onPreviewHtml={onPreviewHtml}
+					onImageClick={onImageClick}
+				/>
+			</div>
 		</div>
 	);
 }
@@ -359,16 +369,45 @@ export function ToolBlock({
 
 			{childrenArray.length > 0 || timeline.length > 0 ? (
 				<div className="runtime-tool-children">
-					{timeline.map((entry, index) => renderTimelineEntry(entry, index, t))}
-					{childrenArray.map((child) => (
-						<ToolBlock
-							key={child.webchatCallId}
-							{...child}
-							attachments={attachments}
-							onPreviewHtml={onPreviewHtml}
-							onImageClick={onImageClick}
-						/>
-					))}
+					{timeline.map((entry, index) => {
+						if (entry.type !== "call")
+							return renderTimelineEntry(
+								entry,
+								index,
+								t,
+								attachments,
+								onPreviewHtml,
+								onImageClick,
+							);
+						const child = children.get(entry.callId);
+						return child ? (
+							<ToolBlock
+								key={child.webchatCallId}
+								{...child}
+								attachments={attachments}
+								onPreviewHtml={onPreviewHtml}
+								onImageClick={onImageClick}
+							/>
+						) : null;
+					})}
+					{childrenArray
+						.filter(
+							(child) =>
+								!timeline.some(
+									(entry) =>
+										entry.type === "call" &&
+										entry.callId === child.webchatCallId,
+								),
+						)
+						.map((child) => (
+							<ToolBlock
+								key={child.webchatCallId}
+								{...child}
+								attachments={attachments}
+								onPreviewHtml={onPreviewHtml}
+								onImageClick={onImageClick}
+							/>
+						))}
 				</div>
 			) : null}
 
diff --git a/apps/undefined-chat/src/runtime-client/tauri.ts b/apps/undefined-chat/src/runtime-client/tauri.ts
index cf772dc9..50e659c5 100644
--- a/apps/undefined-chat/src/runtime-client/tauri.ts
+++ b/apps/undefined-chat/src/runtime-client/tauri.ts
@@ -217,8 +217,39 @@ function normalizeEvent(value: unknown): ChatEvent {
 	};
 }
 
-function normalizeToolCall(value: unknown): ToolCallSnapshot {
-	const raw = record(value);
+function normalizeToolCall(
+	value: unknown,
+	liveCalls?: Map<string, RawRecord>,
+): ToolCallSnapshot {
+	const original = record(value);
+	const id =
+		text(original.id) ||
+		text(original.webchat_call_id) ||
+		text(original.webchatCallId) ||
+		text(original.name, "tool");
+	const raw: RawRecord = {
+		...original,
+		...liveCalls?.get(id),
+		children: original.children,
+		timeline: original.timeline,
+	};
+	const children = new Map(
+		arrayRecords(raw.children).map((child) => {
+			const normalized = normalizeToolCall(child, liveCalls);
+			return [normalized.id, normalized];
+		}),
+	);
+	const timeline = Array.isArray(raw.timeline)
+		? raw.timeline.map((value) => {
+				const entry = record(value);
+				if (entry.type !== "call" || !entry.call) return value;
+				const child = normalizeToolCall(entry.call, liveCalls);
+				children.set(child.id, child);
+				// 流式更新只改 children；时间线引用同一个子块，不能保留旧 inline 状态。
+				return { type: "call", seq: numberValue(entry.seq), callId: child.id };
+			})
+		: undefined;
+
 	return {
 		id:
 			text(raw.id) ||
@@ -229,7 +260,11 @@ function normalizeToolCall(value: unknown): ToolCallSnapshot {
 		status: text(raw.status, "running"),
 		elapsedMs: nullableNumber(field(raw, "elapsedMs", "elapsed_ms")),
 		durationMs: nullableNumber(field(raw, "durationMs", "duration_ms")),
-		detail: text(raw.detail) || text(raw.result_preview) || undefined,
+		detail:
+			text(raw.detail) ||
+			text(raw.current_stage_detail) ||
+			text(raw.result_preview) ||
+			undefined,
 		argumentsPreview:
 			text(raw.argumentsPreview) ||
 			text(raw.arguments_preview) ||
@@ -244,8 +279,8 @@ function normalizeToolCall(value: unknown): ToolCallSnapshot {
 		currentStage:
 			text(raw.currentStage) || text(raw.current_stage) || undefined,
 		isAgent: bool(raw.isAgent) || bool(raw.is_agent) || undefined,
-		children: arrayRecords(raw.children).map(normalizeToolCall),
-		timeline: Array.isArray(raw.timeline) ? raw.timeline : undefined,
+		children: [...children.values()],
+		timeline,
 	};
 }
 
@@ -273,6 +308,37 @@ function normalizeJob(value: unknown): ChatJob | null {
 	if (!jobId) {
 		return null;
 	}
+	const rawTimeline = field(raw, "currentTimeline", "current_timeline");
+	const hasTimelineSnapshot = Array.isArray(rawTimeline);
+	const liveCalls = arrayRecords(
+		field(raw, "currentToolCalls", "current_tool_calls"),
+	);
+	const liveById = new Map(
+		liveCalls.map((call) => [
+			text(call.id) ||
+				text(call.webchat_call_id) ||
+				text(call.webchatCallId) ||
+				text(call.name, "tool"),
+			call,
+		]),
+	);
+	const currentToolCalls: ToolCallSnapshot[] = [];
+	const currentTimeline: ChatJob["currentTimeline"] = [];
+	for (const entry of arrayRecords(rawTimeline)) {
+		const seq = numberValue(entry.seq);
+		if (entry.type === "message" && text(entry.content)) {
+			currentTimeline.push({
+				type: "message",
+				seq,
+				content: text(entry.content),
+			});
+		} else if (entry.type === "call" && entry.call) {
+			const call = normalizeToolCall(entry.call, liveById);
+			currentToolCalls.push(call);
+			currentTimeline.push({ type: "call", seq, callId: call.id });
+		}
+	}
+
 	return {
 		jobId,
 		conversationId: text(field(raw, "conversationId", "conversation_id")),
@@ -299,11 +365,12 @@ function normalizeJob(value: unknown): ChatJob | null {
 		currentAgentStages: arrayRecords(
 			field(raw, "currentAgentStages", "current_agent_stages"),
 		).map(normalizeAgentStage),
-		currentToolCalls: arrayRecords(
-			field(raw, "currentToolCalls", "current_tool_calls"),
-		).map(normalizeToolCall),
+		currentToolCalls: hasTimelineSnapshot
+			? currentToolCalls
+			: liveCalls.map((call) => normalizeToolCall(call)),
 		historyFinalized: bool(field(raw, "historyFinalized", "history_finalized")),
-		currentTimeline: [],
+		currentTimeline,
+		hasTimelineSnapshot,
 		waitingInput: field(raw, "waitingInput", "waiting_input") ?? null,
 	};
 }
diff --git a/apps/undefined-chat/src/runtime-client/types.ts b/apps/undefined-chat/src/runtime-client/types.ts
index 59021848..5d626649 100644
--- a/apps/undefined-chat/src/runtime-client/types.ts
+++ b/apps/undefined-chat/src/runtime-client/types.ts
@@ -138,6 +138,8 @@ export type ChatJob = {
 	currentToolCalls: ToolCallSnapshot[];
 	/** 流式时间线：按事件到达顺序的 message 段 + 顶层 call（对齐 WebUI append 顺序） */
 	currentTimeline: StreamingTimelineItem[];
+	/** Runtime 提供完整时间线快照；缺省时兼容旧服务的 reply-only 快照。 */
+	hasTimelineSnapshot?: boolean;
 	historyFinalized: boolean;
 	waitingInput: unknown | null;
 };
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 64708e1e..82e8b3e1 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -6,7 +6,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的原生优先 WebChat 客户端
 
 | 能力 | 当前状态 | 说明 |
 |---|---|---|
-| 会话管理 | 已实现 | 创建、删除、重命名、切换；未实现置顶会话 |
+| 会话管理 | 已实现 | 创建、删除、重命名、切换；重命名保留当前会话、草稿与移动端面板，未实现置顶会话 |
 | 历史分页 | 已实现 | cursor-based 加载更早消息，prepend 后保持滚动锚点；超长历史采用窗口化渲染 |
 | Markdown 渲染 | 已实现 | 表格、引用、列表、任务列表、链接、内联/块级代码 |
 | 代码高亮 | 已实现 | highlight.js，多语言自动/显式高亮，支持复制 |
@@ -14,7 +14,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的原生优先 WebChat 客户端
 | HTML 预览窗口 | 已实现 | 独立窗口/Android Activity，临时 file URL，预览窗口内可运行脚本；保留 `connect-src 'none'`、导航守卫、IPC 隔离、1 MB 限制和临时文件清理 |
 | 附件上传/下载 | 已实现 | Tauri 流式上传、下载、预览；显示上传状态，不显示百分比进度 |
 | 图片展示 | 已实现 | UID 附件图片经 Tauri 预览接口转 blob，支持内联、附件区和全屏查看 |
-| 工具调用块 | 已实现 | 层级展示、状态、运行中实时计时（统一时钟）、阶段明细（stage detail）、与 WebUI 一致的输入/输出预览（JSON/Python 风格结构化、Markdown 输出、附件图片预览）；历史回放支持 timeline/calls/events 多级回退 |
+| 工具调用块 | 已实现 | 层级展示、状态、运行中实时计时（统一时钟）、阶段明细（stage detail）、与 WebUI 一致的输入/输出预览（JSON/Python 风格结构化、Markdown 输出、附件图片预览）；Agent 内正文与子调用按时间线顺序展示；历史回放支持 timeline/calls/events 多级回退 |
 | 事件流 | 已实现 | SSE 优先，断开/错误时 JSON fallback（指数退避重连，活跃任务持续重试） |
 | 命令面板 | 已实现 | `/` 候选、子命令、方向键、Tab/Enter 补全；空态反馈（加载中/无匹配/不可用）；窗口聚焦按 TTL 刷新命令列表 |
 | 消息引用 | 已实现 | 引用 bot 消息、划词引用选中文本、发送引用、引用芯片跳转当前已加载源消息（不在当前页时自动加载一页更早历史，仍未命中需手动继续） |
@@ -64,13 +64,13 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 
 - 默认使用 SSE 订阅 job events。
 - SSE error/closed 或原生订阅建立失败时使用 `job_id + seq` 调用 JSON events fallback 补齐遗漏事件；消息已成功创建 job 后，订阅失败不会撤回用户消息或恢复已发送草稿。
-- JSON fallback 先续接增量事件，再应用 Runtime 的完整正文与阶段快照，保留已有消息/工具时间线和已结束调用，避免把快照正文再次累计。
+- Runtime 任务快照包含 `current_timeline`：完整的顶层消息、已结束和运行中的调用树，以及 Agent 内消息与子调用的顺序。客户端接受此快照时同时推进到 `last_seq`，SSE 与 JSON 只追加后续序号，避免正文丢失或重复。
+- 旧 Runtime 缺少 `current_timeline` 时，客户端保留快照的完整正文前缀，JSON fallback 先续接事件以保留已有调用树；重放缓冲缺失消息时按权威正文恢复。旧服务无法仅凭正文提供完整的 Agent 嵌套顺序。
 - 重叠 JSON 请求按 job 身份和请求代次校验；已结束、已被替换的 job 或落后于已消费事件游标的回包会被忽略，避免迟到响应覆盖下一轮任务或回退回复内容。
 - 取消请求错误和 SSE 的连接状态通知同样只作用于对应的活跃 job，旧任务的迟到通知不会改写新任务的错误或连接状态。
 - `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。
 - 历史分页的 `before` / `next_before` 是非负数值索引；React 与 Tauri command 使用同一数值契约，首屏不传 `before`。
-- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs，并重新建立事件订阅。
-- 当前没有公开的 store 方法在 resume 时逐 job 主动补齐；这部分仍依赖 SSE 断线 fallback。
+- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs；每个任务接受完整快照及其游标后重新建立事件订阅。请求途中已消费更高序号时保留更新的本地状态。
 
 ## 安全存储
 

From fea67d5693b5f63c82bf4c58608ca53975ea1b20 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:44:26 +0800
Subject: [PATCH 083/121] fix(webui): keep live logs ahead of delayed snapshots

---
 src/Undefined/webui/static/js/log-view.js |  4 +++-
 tests/test_webui_logs_frontend.py         | 12 +++++++++---
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/Undefined/webui/static/js/log-view.js b/src/Undefined/webui/static/js/log-view.js
index 40835bed..3be04fc8 100644
--- a/src/Undefined/webui/static/js/log-view.js
+++ b/src/Undefined/webui/static/js/log-view.js
@@ -183,6 +183,8 @@ function startLogStream() {
     state.logStream = stream;
     stream.onmessage = (event) => {
         if (state.logStream !== stream) return;
+        // 流消息比此前发出的 GET 新，不能让迟到快照回退正文。
+        _logFetchRequest += 1;
         state.logsRaw = event.data || "";
         recordFetchSuccess("logs");
         renderLogs();
@@ -224,7 +226,7 @@ function updateLogRefreshState() {
         startLogTimer();
         return;
     }
-    if (startLogStream()) {
+    if (state.logStream || startLogStream()) {
         stopLogTimer();
         return;
     }
diff --git a/tests/test_webui_logs_frontend.py b/tests/test_webui_logs_frontend.py
index e74ea11b..752df554 100644
--- a/tests/test_webui_logs_frontend.py
+++ b/tests/test_webui_logs_frontend.py
@@ -187,6 +187,7 @@ def test_log_category_switch_closes_old_stream_and_ignores_stale_responses() ->
   logAutoRefresh: true, logSearch: '', logLevel: 'all', logAtBottom: true};
 const pending = [];
 const streams = [];
+let activePollTimers = 0;
 class EventSource {
   constructor(url) { this.url = url; this.closed = false; streams.push(this); }
   close() { this.closed = true; }
@@ -196,7 +197,7 @@ class EventSource {
   get: id => dom.window.document.getElementById(id), t: key => key,
   escapeHtml: text => text, shouldFetch: () => true,
   recordFetchSuccess: () => {}, recordFetchError: () => {},
-  startLogTimer: () => {}, stopLogTimer: () => {},
+  startLogTimer: () => {activePollTimers=1;}, stopLogTimer: () => {activePollTimers=0;},
   api: async path => new Promise(resolve => pending.push({path, resolve})),
 });
 vm.runInContext(fs.readFileSync(root + '/src/Undefined/webui/static/js/ui.js', 'utf8'), context);
@@ -214,9 +215,13 @@ class EventSource {
   answer('/api/logs/files?type=webui', {files: [{name:'webui.log',current:true}],current:'webui.log'});
   answer('/api/logs?lines=5000&type=bot', 'STALE_BOT_SNAPSHOT');
   await tick();
+  vm.runInContext('fetchLogs(true)', context);
+  streams[2].onmessage({data:'NEWER_LIVE_BOT'});
+  answer('/api/logs?lines=5000&type=bot&file=bot.log', 'STALE_CURRENT_VIEW_GET');
+  await tick();
   const select = dom.window.document.getElementById('logFileSelect');
   console.log(JSON.stringify({closed: streams.slice(0,2).map(item=>item.closed),
-    activeUrl: state.logStream.url, logsRaw:state.logsRaw,
+    activeUrl: state.logStream.url, logsRaw:state.logsRaw, activePollTimers,
     options:Array.from(select.options).map(item=>item.value), selected:select.value,
     botCache:state.logFiles.bot.map(item=>item.name),
     webuiCache:state.logFiles.webui.map(item=>item.name)}));
@@ -234,7 +239,8 @@ class EventSource {
     result = json.loads(completed.stdout.strip().splitlines()[-1])
     assert result["closed"] == [True, True]
     assert result["activeUrl"].endswith("type=bot")
-    assert result["logsRaw"] == "CURRENT_BOT"
+    assert result["logsRaw"] == "NEWER_LIVE_BOT"
+    assert result["activePollTimers"] == 0
     assert result["options"] == result["botCache"] == ["bot.log"]
     assert result["selected"] == "bot.log"
     assert result["webuiCache"] == ["webui.log"]

From ffba02a4a605a89cb569499e09a7b049d8630e3c Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:44:29 +0800
Subject: [PATCH 084/121] fix(webui): retain meme drafts outside refreshed
 result pages

---
 docs/webui-guide.md                    |  2 +-
 src/Undefined/webui/static/js/memes.js | 11 +---
 tests/test_webui_memes_behavior.py     | 70 +++++++++++++++++++++++---
 3 files changed, 65 insertions(+), 18 deletions(-)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 513f49dc..67127b83 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -121,7 +121,7 @@ AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：
 - **浏览与搜索**：分页列表展示，支持关键词搜索和语义搜索（以及混合模式）。输入时自动防抖搜索，Enter 立即触发。
 - **筛选与排序**：按启用 / 禁用、静态 / 动态、置顶等条件筛选，按创建或更新时间排序。
 - **详情与操作**：查看元数据（UID、描述、标签）和预览图；支持编辑描述 / 标签、启用 / 禁用、置顶 / 取消、删除。
-- 详情响应只更新当前选中条目；保存或后台刷新期间继续编辑的草稿会保留，不会被迟到响应覆盖。
+- 详情响应只更新当前选中条目；保存或同一筛选下的后台刷新会保留继续编辑的草稿，即使条目因停用或分页暂时移出列表。显式修改筛选或删除选中条目时才清除详情。
 - **重分析 / 重索引**：对单张表情包重新触发 AI 描述生成或搜索索引更新。分析期间可继续编辑或删除；旧结果不会覆盖人工修改、恢复已删除条目或删除新修订，使用次数仍会保留。
 - **统计概览**：总数、启用 / 禁用数、静态 / 动态数等。
 
diff --git a/src/Undefined/webui/static/js/memes.js b/src/Undefined/webui/static/js/memes.js
index 1c2a5718..9c47fce7 100644
--- a/src/Undefined/webui/static/js/memes.js
+++ b/src/Undefined/webui/static/js/memes.js
@@ -431,15 +431,8 @@
             state.listItems = append
                 ? state.listItems.concat(nextItems)
                 : nextItems;
-            if (
-                state.selectedUid &&
-                !state.listItems.some((item) => item.uid === state.selectedUid)
-            ) {
-                state.selectedUid = "";
-                state.detailRequestSeq += 1;
-                state.detail = null;
-                renderDetail(null);
-            }
+            // 同一查询刷新或分页只更新列表；详情可能因编辑后不再匹配筛选，
+            // 或不在新首页中，仍保留选中内容和未提交草稿。
             renderList();
             return payload;
         } finally {
diff --git a/tests/test_webui_memes_behavior.py b/tests/test_webui_memes_behavior.py
index ff9f40d4..53da983a 100644
--- a/tests/test_webui_memes_behavior.py
+++ b/tests/test_webui_memes_behavior.py
@@ -19,12 +19,21 @@ def _run_meme_scenario(scenario: str) -> dict[str, Any]:
 const {JSDOM}=require(root+'/tests/frontend/node_modules/jsdom');
 const dom=new JSDOM(fs.readFileSync(root+'/src/Undefined/webui/templates/index.html','utf8'),
   {url:'http://isolated.example',runScripts:'outside-only'});
-const w=dom.window, details=[], patches=[];
+const w=dom.window, details=[], patches=[], listRequests=[];
+let hideSavedRecord = false;
 w.get=id=>w.document.getElementById(id);w.t=k=>k;w.escapeHtml=s=>String(s);w.showToast=()=>{};
 w.confirm=()=>true;
+if(scenario==='save_filtered')w.get('memesEnabledFilter').value='true';
+if(scenario==='save_paginated')w.get('memesPageSize').value='1';
 w.api=async(path,opts={})=>{
   if(path.endsWith('/stats'))return {ok:true,json:async()=>({})};
-  if(path.includes('/memes?'))return {ok:true,json:async()=>({items:[{uid:'A'},{uid:'B'}],total:2,page:1,page_size:50})};
+  if(path.includes('/memes?')){
+    const params=new URL(path,'http://isolated.example').searchParams;
+    listRequests.push({enabled:params.get('enabled'),page:Number(params.get('page')),query:params.get('q')});
+    const paginated=scenario==='save_paginated';
+    const items=paginated?[{uid:params.get('page')==='2'?'A':'B'}]:hideSavedRecord?[{uid:'B'}]:[{uid:'A'},{uid:'B'}];
+    return {ok:true,json:async()=>({items,total:2,page:Number(params.get('page')),page_size:paginated?1:50,has_more:paginated&&params.get('page')==='1'})};
+  }
   if(opts.method==='PATCH'||opts.method==='DELETE')return new Promise(resolve=>patches.push({path,body:opts.body&&JSON.parse(opts.body),resolve}));
   return new Promise(resolve=>details.push({uid:path.split('/').at(-1),resolve}));
 };
@@ -32,33 +41,48 @@ def _run_meme_scenario(scenario: str) -> dict[str, Any]:
 w.MemesController.init();w.MemesController.onTabActivated('memes');
 const tick=async()=>{for(let i=0;i<10;i++)await new Promise(r=>setImmediate(r));};
 const answer=(request,text)=>request.resolve({ok:true,json:async()=>({record:{uid:request.uid,
-  manual_description:text,enabled:true},sources:[]})});
+  manual_description:text,enabled:request.uid==='A'&&hideSavedRecord?false:true},sources:[]})});
 const click=uid=>w.document.querySelector(`[data-meme-uid="${uid}"]`).click();
 (async()=>{
-  await tick();click('A');await tick();
+  await tick();
+  if(scenario==='save_paginated'){w.get('btnMemesLoadMore').click();await tick();}
+  click('A');await tick();
   if(scenario==='selection'){
     click('B');answer(details[1],'B saved');await tick();
     w.get('memesDetailManualDescription').value='B unsaved';answer(details[0],'A saved');await tick();
   }else{
     answer(details[0],'A saved');await tick();
-    if(scenario==='refresh'){
+    if(scenario==='query_change'){
+      w.get('memesSearchInput').value='different query';w.get('btnMemesSearch').click();await tick();
+    }else if(scenario==='delete'){
+      w.get('btnMemesDelete').click();await tick();patches[0].resolve({ok:true});await tick();
+    }else if(scenario==='refresh'){
       w.get('btnMemesRefresh').click();await tick();
       w.get('memesDetailManualDescription').value='A draft during refresh';
       answer(details[1],'A refreshed');await tick();
     }else{
-      w.get('memesDetailManualDescription').value='A first edit';w.get('btnMemesSave').click();await tick();
+      w.get('memesDetailManualDescription').value='A first edit';
+      if(scenario==='save_filtered')w.get('memesDetailEnabled').checked=false;
+      w.get('btnMemesSave').click();await tick();
       if(scenario==='save_switch'){
         click('B');answer(details[1],'B saved');await tick();
         w.get('memesDetailManualDescription').value='B unsaved';
-      }else if(scenario==='save_edit')w.get('memesDetailManualDescription').value='A second unsaved edit';
+      }else if(['save_edit','save_filtered','save_paginated'].includes(scenario))w.get('memesDetailManualDescription').value='A second unsaved edit';
+      if(scenario==='save_filtered')hideSavedRecord=true;
       patches[0].resolve({ok:true});await tick();
       if(scenario!=='save_switch')answer(details[1],'A first edit');
       await tick();
+      if(['save_filtered','save_paginated'].includes(scenario)){
+        w.get('btnMemesSave').click();await tick();
+        patches[1]?.resolve({ok:true});await tick();
+        if(details[2])answer(details[2],'A second unsaved edit');await tick();
+      }
     }
   }
   console.log(JSON.stringify({uid:w.get('memesDetailUid').textContent,
     draft:w.get('memesDetailManualDescription').value,detailRequests:details.map(item=>item.uid),
-    sent:patches.map(item=>item.body),saveEnabled:!w.get('btnMemesSave').disabled}));
+    sent:patches.map(item=>item.body),saveEnabled:!w.get('btnMemesSave').disabled,
+    panelVisible:w.get('memesDetailPanel').style.display!=='none',enabled:w.get('memesDetailEnabled').checked,listRequests}));
   dom.window.close();
 })().catch(error=>{console.error(error);process.exitCode=1;});
 """
@@ -100,3 +124,33 @@ def test_meme_background_refresh_preserves_later_edits(
         assert result["sent"][0]["manual_description"] == "A first edit"
     if scenario == "save_switch":
         assert result["detailRequests"] == ["A", "B"]
+
+
+@pytest.mark.parametrize("scenario", ["save_filtered", "save_paginated"])
+def test_meme_list_refresh_keeps_selected_draft_outside_current_results(
+    scenario: str,
+) -> None:
+    result = _run_meme_scenario(scenario)
+    assert result["uid"] == "A"
+    assert result["panelVisible"] is True
+    assert result["draft"] == "A second unsaved edit"
+    assert result["saveEnabled"] is True
+    assert [body["manual_description"] for body in result["sent"]] == [
+        "A first edit",
+        "A second unsaved edit",
+    ]
+    if scenario == "save_filtered":
+        assert result["sent"][0]["enabled"] is False
+        assert result["sent"][1]["enabled"] is False
+        assert result["enabled"] is False
+        assert all(request["enabled"] == "true" for request in result["listRequests"])
+    else:
+        assert [request["page"] for request in result["listRequests"]] == [1, 2, 1, 1]
+
+
+@pytest.mark.parametrize("scenario", ["query_change", "delete"])
+def test_explicit_meme_query_change_or_delete_clears_selected_detail(
+    scenario: str,
+) -> None:
+    result = _run_meme_scenario(scenario)
+    assert result["panelVisible"] is False

From fa4d2d785f643909bdefe192e66e41e4e50fb20e Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 10:49:52 +0800
Subject: [PATCH 085/121] fix(chat): replay legacy resumes and preserve history
 call IDs

---
 .../src/chat-store/snapshot-recovery.test.tsx | 161 +++++++++++++++++-
 apps/undefined-chat/src/chat-store/store.ts   |  54 ++++--
 .../MessageTimelineContent.test.tsx           |  39 +++++
 .../MessageTimelineContent.tsx                |   8 +-
 .../src/message-timeline/ToolBlock.README.md  |   2 +-
 docs/undefined-chat.md                        |   2 +-
 6 files changed, 244 insertions(+), 22 deletions(-)

diff --git a/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx b/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx
index 9740199c..43c3045d 100644
--- a/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx
+++ b/apps/undefined-chat/src/chat-store/snapshot-recovery.test.tsx
@@ -33,6 +33,7 @@ function nativeSnapshot(lastSeq: number) {
 		status: "running",
 		last_seq: lastSeq,
 		reply: "Agent before\n\nAgent after\n\nMain answer",
+		messages: ["Agent before", "Agent after", "Main answer"],
 		history_finalized: false,
 		current_tool_calls: [
 			{
@@ -133,13 +134,17 @@ describe("job snapshot recovery", () => {
 				if (legacy) delete raw.current_timeline;
 				return { status: 200, ok: true, body: { job: raw, jobs: [raw] } };
 			});
-			const client = runtimeClientStub({ getActiveJobs: native.getActiveJobs });
+			const client = runtimeClientStub({
+				getActiveJobs: native.getActiveJobs,
+				fetchJobEventsJson: native.fetchJobEventsJson,
+			});
 			const store = createChatStore({ client });
 			await store.bootstrap();
 			snapshot = {
 				...nativeSnapshot(7),
 				reply:
 					"Agent before\n\nAgent after\n\nMain answer\n\nSnapshot addition",
+				messages: [...nativeSnapshot(7).messages, "Snapshot addition"],
 				current_timeline: [
 					...nativeSnapshot(7).current_timeline,
 					{ type: "message", seq: 7, content: "Snapshot addition" },
@@ -465,4 +470,158 @@ describe("job snapshot recovery", () => {
 			store.suspendRuntime();
 		},
 	);
+
+	test.each(["running", "done", "error", "cancelled"])(
+		"legacy resume replays same-body tool and Agent changes before advancing the cursor (%s)",
+		async (status) => {
+			let seq = 1;
+			const rawSnapshot = () => ({
+				job_id: "job-1",
+				conversation_id: "default",
+				status: "running",
+				last_seq: seq,
+				reply: "Same body",
+				messages: ["Same body"],
+				current_tool_calls: [],
+				history_finalized: false,
+			});
+			const replay = [
+				{
+					seq: 2,
+					event: "agent_start",
+					payload: {
+						webchat_call_id: "agent",
+						name: "research",
+						is_agent: true,
+					},
+				},
+				{
+					seq: 3,
+					event: "agent_stage",
+					payload: {
+						webchat_call_id: "agent",
+						agent_name: "research",
+						stage: "thinking",
+						detail: "Newest stage detail",
+					},
+				},
+				{
+					seq: 4,
+					event: "tool_start",
+					payload: {
+						webchat_call_id: "nested",
+						parent_webchat_call_id: "agent",
+						name: "search",
+					},
+				},
+				...(status === "running"
+					? []
+					: [
+							{
+								seq: 5,
+								event: "tool_end",
+								payload: {
+									webchat_call_id: "nested",
+									parent_webchat_call_id: "agent",
+									name: "search",
+									status,
+									ok: status !== "error",
+									result_preview: "Completed search",
+								},
+							},
+						]),
+				{
+					seq: 6,
+					event: "tool_start",
+					payload: { webchat_call_id: "pending", name: "pending" },
+				},
+			];
+			vi.mocked(invoke).mockImplementation(async (command) => ({
+				status: 200,
+				ok: true,
+				body:
+					command === "get_active_jobs"
+						? { job: rawSnapshot(), jobs: [rawSnapshot()] }
+						: { job: rawSnapshot(), events: replay, after: 1, last_seq: seq },
+			}));
+			const native = createTauriRuntimeClient();
+			const client = runtimeClientStub({
+				getActiveJobs: native.getActiveJobs,
+				fetchJobEventsJson: native.fetchJobEventsJson,
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			seq = 6;
+			await store.bootstrap({ resuming: true });
+			const active = store.getSnapshot().activeJobsByConversation.default;
+			expect(active.reply).toBe("Same body");
+			expect(
+				active.currentToolCalls.find((call) => call.id === "agent"),
+			).toMatchObject({
+				currentStage: "thinking",
+				detail: "Newest stage detail",
+				children: [{ id: "nested", status }],
+			});
+			expect(
+				active.currentToolCalls.some((call) => call.id === "pending"),
+			).toBe(true);
+			expect(invoke).toHaveBeenCalledWith("fetch_job_events_json", {
+				input: { jobId: "job-1", conversationId: "default", afterSeq: 1 },
+			});
+			expect(client.startJobEventStream).toHaveBeenLastCalledWith({
+				jobId: "job-1",
+				conversationId: "default",
+				afterSeq: 6,
+			});
+			store.applyRuntimeEvents(
+				"job-1",
+				replay.map((item) => event(item)),
+			);
+			renderJob(store.getSnapshot().activeJobsByConversation.default);
+			expect(screen.getAllByText("search")).toHaveLength(1);
+			expect(
+				screen
+					.getByText("search")
+					.closest("details")
+					?.classList.contains(status),
+			).toBe(true);
+			store.suspendRuntime();
+		},
+	);
+
+	test("a failed legacy resume replay keeps the old cursor available for SSE recovery", async () => {
+		let active = job({
+			lastSeq: 1,
+			reply: "Same body",
+			messages: ["Same body"],
+		});
+		const client = runtimeClientStub({
+			getActiveJobs: vi.fn(async () => ({ job: active, jobs: [active] })),
+			fetchJobEventsJson: vi.fn(async () => {
+				throw new Error("offline");
+			}),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		active = { ...active, lastSeq: 4 };
+		await store.bootstrap({ resuming: true });
+		expect(store.getSnapshot().eventCursorByJob["job-1"]).toBe(1);
+		expect(client.startJobEventStream).toHaveBeenLastCalledWith({
+			jobId: "job-1",
+			conversationId: "default",
+			afterSeq: 1,
+		});
+		store.applyRuntimeEvents("job-1", [
+			event({
+				seq: 2,
+				event: "tool_start",
+				payload: { webchat_call_id: "recovered", name: "recovered" },
+			}),
+		]);
+		expect(
+			store.getSnapshot().activeJobsByConversation.default.currentToolCalls[0]
+				?.name,
+		).toBe("recovered");
+		store.suspendRuntime();
+	});
 });
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 3912a9ad..bc31d604 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -228,7 +228,7 @@ export function chatReducer(state: ChatState, action: ChatAction): ChatState {
 				...state,
 				bootstrapping: false,
 				connectionState:
-					action.activeJobs.length > 0 ? "streaming" : "connected",
+					Object.keys(activeJobs).length > 0 ? "streaming" : "connected",
 				runtimeConfig: action.runtimeConfig,
 				health: action.health,
 				conversations: action.conversations.map((item) => ({
@@ -973,14 +973,16 @@ export function createChatStore({
 		fallbackTimersByJob.set(jobId, timer);
 	}
 
-	function fetchJobEventsFallback(jobId: string): void {
+	async function fetchJobEventsFallback(
+		jobId: string,
+	): Promise<ChatJob | null> {
 		const generation = runtimeGeneration;
 		const conversationId = state.jobConversationById[jobId];
 		if (
 			!conversationId ||
 			state.activeJobsByConversation[conversationId]?.jobId !== jobId
 		) {
-			return;
+			return null;
 		}
 		const requestGeneration = ++fallbackRequestGeneration;
 		latestFallbackRequestByJob.set(jobId, requestGeneration);
@@ -994,16 +996,14 @@ export function createChatStore({
 			fallbackTimersByJob.delete(jobId);
 		}
 		dispatch({ type: "connection/set", connectionState: "json_fallback" });
-		void client
+		return client
 			.fetchJobEventsJson({
 				jobId,
 				afterSeq: state.eventCursorByJob[jobId] ?? 0,
 				conversationId,
 			})
 			.then((response) => {
-				if (!isCurrentRequest()) {
-					return;
-				}
+				if (!isCurrentRequest()) return null;
 				const active = state.activeJobsByConversation[conversationId];
 				const consumedSeq = Math.max(
 					state.eventCursorByJob[jobId] ?? 0,
@@ -1012,7 +1012,7 @@ export function createChatStore({
 				if (response.job.lastSeq < consumedSeq) {
 					// SSE 可能在请求途中推进；旧快照不能回退正文或阶段，继续拉取即可。
 					scheduleFallbackPolling(jobId);
-					return;
+					return active ?? null;
 				}
 				// 拉取成功：重置退避间隔
 				fallbackBackoffByJob.delete(jobId);
@@ -1043,11 +1043,10 @@ export function createChatStore({
 				} else if (response.job.conversationId) {
 					finishJob(jobId, response.job.conversationId);
 				}
+				return snapshot;
 			})
 			.catch(() => {
-				if (!isCurrentRequest()) {
-					return;
-				}
+				if (!isCurrentRequest()) return null;
 				// 单次失败不直接放弃：仅当该 job 仍是活跃任务时按指数退避继续重试，
 				// 否则停止轮询。连接状态保持 json_fallback（仍在尝试），而非直接 disconnected。
 				const stillActive =
@@ -1056,11 +1055,9 @@ export function createChatStore({
 					scheduleFallbackPolling(jobId, nextFallbackDelay(jobId));
 				} else {
 					stopFallbackPolling(jobId);
-					dispatch({
-						type: "connection/set",
-						connectionState: "disconnected",
-					});
+					dispatch({ type: "connection/set", connectionState: "disconnected" });
 				}
+				return null;
 			});
 	}
 
@@ -1123,13 +1120,34 @@ export function createChatStore({
 				conversationsResponse.conversations[0]?.id ||
 				activeJobs.jobs[0]?.conversationId ||
 				"";
+			const recoveredJobs: ChatJob[] = [];
+			for (const snapshot of activeJobs.jobs) {
+				const previous =
+					state.activeJobsByConversation[snapshot.conversationId];
+				if (
+					!snapshot.hasTimelineSnapshot &&
+					previous?.jobId === snapshot.jobId &&
+					snapshot.lastSeq > previous.lastSeq
+				) {
+					// 旧 API 不含完整调用树；推进游标前用同一 JSON 回放补齐后台工具/阶段事件。
+					const recovered = await fetchJobEventsFallback(snapshot.jobId);
+					if (generation !== runtimeGeneration) return;
+					recoveredJobs.push(
+						recovered ??
+							state.activeJobsByConversation[snapshot.conversationId] ??
+							previous,
+					);
+				} else {
+					recoveredJobs.push(snapshot);
+				}
+			}
 			dispatch({
 				type: "bootstrap/success",
 				runtimeConfig,
 				health,
 				conversations: conversationsResponse.conversations,
 				selectedConversationId: selected,
-				activeJobs: activeJobs.jobs,
+				activeJobs: recoveredJobs,
 				commands: commands.commands,
 			});
 			clearNativeSubscriptions();
@@ -1146,7 +1164,7 @@ export function createChatStore({
 				return;
 			}
 			unlistenRuntimeSse = unlisten;
-			for (const activeJob of activeJobs.jobs) {
+			for (const activeJob of Object.values(state.activeJobsByConversation)) {
 				if (generation !== runtimeGeneration) return;
 				await startStreamForJob(activeJob);
 			}
@@ -1155,7 +1173,7 @@ export function createChatStore({
 			}
 			if (generation !== runtimeGeneration) return;
 			if (
-				activeJobs.jobs.length > 0 &&
+				Object.keys(state.activeJobsByConversation).length > 0 &&
 				state.connectionState !== "json_fallback"
 			) {
 				dispatch({ type: "connection/set", connectionState: "streaming" });
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
index 84eeeb71..fc0e7eaa 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.test.tsx
@@ -40,6 +40,45 @@ describe("hasRenderableTimeline", () => {
 });
 
 describe("MessageTimelineContent", () => {
+	test("uses Runtime snake_case IDs to render one child shared by children and timeline", () => {
+		const child = {
+			webchat_call_id: "agent/search",
+			name: "search",
+			status: "done",
+			timeline: [{ type: "message", content: "Nested completed body" }],
+		};
+		renderContent(
+			<MessageTimelineContent
+				onPreviewHtml={vi.fn()}
+				completeTimeline
+				timeline={[
+					{
+						type: "call",
+						call: {
+							webchat_call_id: "agent",
+							name: "research",
+							is_agent: true,
+							status: "done",
+							children: [child],
+							timeline: [
+								{ type: "message", content: "Before child" },
+								{ type: "call", call: child },
+							],
+						},
+					},
+				]}
+			/>,
+		);
+		expect(screen.getAllByText("search")).toHaveLength(1);
+		expect(screen.getAllByText("Nested completed body")).toHaveLength(1);
+		expect(
+			screen
+				.getByText("search")
+				.closest("details")
+				?.getAttribute("data-call-id"),
+		).toBe("agent/search");
+	});
+
 	test("keeps historical Agent messages and nested calls inside the Agent in order", () => {
 		renderContent(
 			<MessageTimelineContent
diff --git a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
index 3247a2cc..2c613a24 100644
--- a/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
+++ b/apps/undefined-chat/src/message-timeline/MessageTimelineContent.tsx
@@ -11,6 +11,8 @@ import "./ToolBlock.css";
 
 type HistoryToolCall = {
 	id?: string;
+	webchat_call_id?: string;
+	tool_call_id?: string;
 	name: string;
 	is_agent?: boolean;
 	status: string;
@@ -144,7 +146,11 @@ function convertHistoryToolCallToToolBlock(
 	const endTime = mappedStatus === "running" ? undefined : now;
 
 	return {
-		webchatCallId: call.id || `call-${index}-${call.name}`,
+		webchatCallId:
+			call.id ||
+			call.webchat_call_id ||
+			call.tool_call_id ||
+			`call-${index}-${call.name}`,
 		toolName: call.name || "--",
 		status: mappedStatus,
 		isAgent: call.is_agent,
diff --git a/apps/undefined-chat/src/message-timeline/ToolBlock.README.md b/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
index c41e6e2e..0b5420e4 100644
--- a/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
+++ b/apps/undefined-chat/src/message-timeline/ToolBlock.README.md
@@ -98,7 +98,7 @@ const toolBlocks = useStore(state => state.toolBlocksByJob[jobId]);
 实时运行的工具块由 store 维护；历史消息则由 `MessageTimelineContent` 消费一条已交错好的
 `timeline`，其中 `type === "call"` 的条目经 `convertHistoryToolCallToToolBlock` 转换为本组件所需的
 `ToolBlock`（映射 `arguments_preview`/`result_preview`/`is_agent`/`current_stage`/`current_stage_detail`
-等字段，并按 `duration_ms` 反推 `startTime`）。嵌套 `message` 转为输出条目，`call` 引用对应子块；已被时间线引用的子块不会再次追加到末尾。
+等字段，并按 `duration_ms` 反推 `startTime`）。调用身份兼容 Runtime 的 `webchat_call_id`、`tool_call_id` 与已有 `id`，同一子调用在 `children` 和 `timeline` 中只渲染一次。嵌套 `message` 转为输出条目，`call` 引用对应子块；已被时间线引用的子块不会再次追加到末尾。
 
 `timeline` 由 `MessageTimeline` 的 `buildHistoryTimeline` 按可用性多级回退构建：
 
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 82e8b3e1..1bcf9db1 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -65,7 +65,7 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 - 默认使用 SSE 订阅 job events。
 - SSE error/closed 或原生订阅建立失败时使用 `job_id + seq` 调用 JSON events fallback 补齐遗漏事件；消息已成功创建 job 后，订阅失败不会撤回用户消息或恢复已发送草稿。
 - Runtime 任务快照包含 `current_timeline`：完整的顶层消息、已结束和运行中的调用树，以及 Agent 内消息与子调用的顺序。客户端接受此快照时同时推进到 `last_seq`，SSE 与 JSON 只追加后续序号，避免正文丢失或重复。
-- 旧 Runtime 缺少 `current_timeline` 时，客户端保留快照的完整正文前缀，JSON fallback 先续接事件以保留已有调用树；重放缓冲缺失消息时按权威正文恢复。旧服务无法仅凭正文提供完整的 Agent 嵌套顺序。
+- 旧 Runtime 缺少 `current_timeline` 时，客户端保留快照的完整正文前缀，JSON fallback 先续接事件以保留已有调用树；重放缓冲缺失消息时按权威正文恢复。同一任务恢复时，推进游标前复用 JSON 回放补齐后台工具开始、结束和 Agent 阶段变化，即使正文没有改变；回放失败保留旧游标供 SSE 继续恢复。旧服务无法仅凭正文恢复已超出事件缓冲的完整 Agent 嵌套顺序。
 - 重叠 JSON 请求按 job 身份和请求代次校验；已结束、已被替换的 job 或落后于已消费事件游标的回包会被忽略，避免迟到响应覆盖下一轮任务或回退回复内容。
 - 取消请求错误和 SSE 的连接状态通知同样只作用于对应的活跃 job，旧任务的迟到通知不会改写新任务的错误或连接状态。
 - `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。

From a8240b3f97286b5720226914beab24ab2b27e45c Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:28:03 +0800
Subject: [PATCH 086/121] fix(weixin): mark each acknowledged delivery as sent

---
 docs/wechat-ilink.md          |  2 +
 src/Undefined/utils/sender.py |  3 ++
 tests/test_sender.py          | 82 +++++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 842e2b55..2c430e63 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -114,6 +114,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 转发节点中的嵌套节点会递归展开，保留每层的发送者标题、正文以及文本和媒体的先后顺序；Bilibili 长正文分段和嵌套卡片也按这一规则发送。逐段模式与多项目模式都会在首个项目发出前校验所有层级的本地媒体，并完成全部语音准备。任一层媒体不存在、超限、使用当前不支持的远程来源或语音准备失败时，整个转发在投递前失败。
 
+每次文本、文件、语音或多项目批次收到发送确认后，都会立即标记当前轮已经输出；这个标记不依赖历史记录开关。后续批次失败时，前面已经确认发送的事实仍会保留，`end` 不会将整轮误判为没有输出。
+
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
 
 Bot 层通过 `messages.send_voice(uid, address?)` 显式选择“作为语音发送”。普通 `<attachment uid="file_xxx"/>` 始终保留原始文件语义，即使扩展名是 `.wav`；`CQ:record`、`CQ:audio` 和内部明确标记为 voice 的媒体回调则发送原生语音。QQ 侧继续转换为 `CQ:record`，微信侧先用 FFmpeg 归一化为 24 kHz、16-bit、单声道 PCM，再由 `silk-python` 编码为 Tencent SILK。部署机必须能从 `PATH` 找到 `ffmpeg`；缺失、音频无效或超出 `[weixin].media_max_size_mb` 时会在任何消息段发出前失败，不会自动改成文件。
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index f6a08a8c..f5290022 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -557,6 +557,7 @@ async def send_address_file(
             name=name,
             kind=kind,
         )
+        mark_message_sent_this_turn()
         sent_at_ms = time.time_ns() // 1_000_000
         if not auto_history:
             return
@@ -673,6 +674,7 @@ async def _send_weixin_prepared_voice(
                 prepared,
             )
         ).strip()
+        mark_message_sent_this_turn()
         if not auto_history:
             return sent_message_id
         sent_at_ms = time.time_ns() // 1_000_000
@@ -2068,6 +2070,7 @@ async def _send_weixin_multi_item_units(
                 sequential_fallback = True
                 receipts.extend(await self._send_weixin_forward_units(batch))
             else:
+                mark_message_sent_this_turn()
                 if receipt:
                     receipts.append(receipt)
         return receipts
diff --git a/tests/test_sender.py b/tests/test_sender.py
index 2e2a311a..95544178 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -1258,6 +1258,54 @@ async def test_send_wechat_file_records_client_id_and_send_time(
     assert isinstance(history_kwargs["transport"]["sent_at_ms"], int)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("auto_history", [False, True])
+@pytest.mark.parametrize("kind", ["file", "voice"])
+async def test_wechat_media_ack_marks_turn_before_history(
+    sender: MessageSender,
+    tmp_path: Path,
+    auto_history: bool,
+    kind: str,
+) -> None:
+    source = tmp_path / "report.wav"
+    await async_io.write_bytes(source, b"isolated media")
+    service = SimpleNamespace(
+        send_file=AsyncMock(return_value="file-ack"),
+        prepare_voice=AsyncMock(
+            return_value=PreparedWeixinVoice(content=b"silk", duration_ms=200)
+        ),
+        send_prepared_voice=AsyncMock(return_value="voice-ack"),
+    )
+    sender.set_weixin_service(service)
+    async with RequestContext("private", user_id=12345) as ctx:
+        await sender.send_address_file(
+            DeliveryAddress("wechat", 12345),
+            str(source),
+            kind=kind,
+            auto_history=auto_history,
+        )
+        assert ctx.get_resource("message_sent_this_turn") is True
+    history = cast(AsyncMock, sender.history_manager.add_private_message)
+    assert history.await_count == int(auto_history)
+
+
+@pytest.mark.asyncio
+async def test_wechat_media_failure_does_not_mark_turn(
+    sender: MessageSender,
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "report.txt"
+    await async_io.write_text(source, "report")
+    service = SimpleNamespace(send_file=AsyncMock(side_effect=ValueError("invalid")))
+    sender.set_weixin_service(service)
+    async with RequestContext("private", user_id=12345) as ctx:
+        with pytest.raises(ValueError, match="invalid"):
+            await sender.send_address_file(
+                DeliveryAddress("wechat", 12345), str(source)
+            )
+        assert ctx.get_resource("message_sent_this_turn") is None
+
+
 @pytest.mark.asyncio
 async def test_send_wechat_file_enforces_private_access_control(
     sender: MessageSender,
@@ -1864,6 +1912,40 @@ async def test_send_wechat_forward_uses_ordered_multi_item_message(
     assert items[2].text == "B"
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("first_ack", [False, True])
+async def test_wechat_bundle_marks_each_ack_before_later_failure(
+    sender: MessageSender,
+    first_ack: bool,
+) -> None:
+    weixin_config = cast(Any, sender.config.weixin)
+    weixin_config.multi_item_messages_enabled = True
+    weixin_config.multi_item_max_items = 1
+    weixin_config.media_max_size_mb = 100
+    failure = RequestTimeoutError("response lost")
+    service = SimpleNamespace(
+        send_items=AsyncMock(
+            side_effect=["first-ack", failure] if first_ack else failure
+        )
+    )
+    sender.set_weixin_service(service)
+    bound_sender = AddressBoundSender(sender, DeliveryAddress("wechat", 12345))
+    nodes = [
+        {"type": "node", "data": {"name": "Bot", "content": text}}
+        for text in ("first", "second")
+    ]
+    async with RequestContext("private", user_id=12345) as ctx:
+        with pytest.raises(RequestTimeoutError):
+            await bound_sender.send_private_forward_message(
+                12345, nodes, history_message="two nodes"
+            )
+        assert ctx.get_resource("message_sent_this_turn") is (
+            True if first_ack else None
+        )
+    assert service.send_items.await_count == (2 if first_ack else 1)
+    cast(AsyncMock, sender.history_manager.add_private_message).assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_send_wechat_forward_falls_back_after_definitive_bundle_rejection(
     sender: MessageSender,

From 0d0ecaeeea64e8b1e54e6f8bf3f80026acd9ce16 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:28:39 +0800
Subject: [PATCH 087/121] fix(automations): preserve zero loop counts and
 validate integers

---
 docs/automations.md                           |  2 +
 src/Undefined/automations/runner.py           |  2 +-
 src/Undefined/automations/validate.py         |  9 ++++
 .../webui/static/js/workflow-inspector.js     |  2 +-
 tests/test_automations.py                     | 42 +++++++++++++++++++
 5 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/docs/automations.md b/docs/automations.md
index 722ab6de..aa32def6 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -75,6 +75,8 @@
 | `branch.llm` | 由模型在若干选项中单选，选中项决定走向 |
 | `loop.times` / `loop.each` | 循环执行一组子节点，次数受配置的循环上限约束（默认 25，可调大），可用 `{{index}}` / `{{item}}` |
 
+`loop.times.count` 必须为非负整数：`0` 跳过循环体并继续出口路径，省略时使用配置的循环上限。负数、布尔值、字符串和其他非整数类型会在创建、更新或启用时被拒绝；实际执行次数仍受 `max_iterations` 与配置上限约束。
+
 工具节点的 `args` 是 JSON 对象；WebUI 检查器按 JSON 值编辑每个参数，因此数字、布尔值、数组、对象、`null` 与字符串会保留原类型（字符串可写成 JSON 字符串，无法解析为 JSON 的输入也按字符串保存）。`llm.blank.tools` 中的名称先按注册表名称精确匹配，包括 `send_message` 这类裸兼容别名；仅当精确名称不存在时，短名称才按 basename 做唯一无歧义解析。带命名空间的完整名称不会退化为 basename 匹配。
 
 执行规则一句话版：有依赖就等待——普通并行汇合会等所有有效上游完成；条件分支只激活选中路径，未选路径会传播为“跳过”，所以互斥 case 可以直接或在下游安全汇合。无依赖的节点一旦就绪就立即并行执行。循环的 `index` / `item` 是每个循环、每次迭代的局部上下文，嵌套或并行循环不会互相覆盖。LLM 与模板节点默认只产出内容不发消息，勾选 `emit` 后才会发送（消息触发发到当前会话，时间触发发到任务地址）。任一节点失败则整图停止；只有从旧定时任务迁移出的图保留“工具失败后继续”的历史兼容行为。
diff --git a/src/Undefined/automations/runner.py b/src/Undefined/automations/runner.py
index b5a3a3c1..e4036c24 100644
--- a/src/Undefined/automations/runner.py
+++ b/src/Undefined/automations/runner.py
@@ -991,7 +991,7 @@ async def _run_loop_times(
         variables: dict[str, Any],
         emit_if_needed: Callable[[dict[str, Any], str], Awaitable[None]],
     ) -> str:
-        count = int(node.get("count") or self.loop_max_iterations)
+        count = int(node.get("count", self.loop_max_iterations))
         max_iterations = min(
             int(node.get("max_iterations") or self.loop_max_iterations),
             self.loop_max_iterations,
diff --git a/src/Undefined/automations/validate.py b/src/Undefined/automations/validate.py
index 2e54627a..7e18263b 100644
--- a/src/Undefined/automations/validate.py
+++ b/src/Undefined/automations/validate.py
@@ -272,6 +272,15 @@ def collect_automation_issues(
                 )
             )
         if node_type in {"loop.times", "loop.each"}:
+            if node_type == "loop.times" and "count" in node:
+                count = node["count"]
+                if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+                    issues.append(
+                        _issue(
+                            f"{prefix}.count",
+                            "loop count must be a non-negative integer",
+                        )
+                    )
             try:
                 max_iterations = int(node.get("max_iterations") or loop_cap)
             except (TypeError, ValueError):
diff --git a/src/Undefined/webui/static/js/workflow-inspector.js b/src/Undefined/webui/static/js/workflow-inspector.js
index a8ee2dc0..09487818 100644
--- a/src/Undefined/webui/static/js/workflow-inspector.js
+++ b/src/Undefined/webui/static/js/workflow-inspector.js
@@ -392,7 +392,7 @@
                 )}`;
         }
         if (node.type === "loop.times") {
-            return `${field("schedules.count", input("count", node.count || 3, `type="number" min="1"`))}
+            return `${field("schedules.count", input("count", node.count ?? 3, `type="number" min="0"`))}
                 ${field("schedules.max_iterations", input("max_iterations", node.max_iterations || 25, `type="number" min="1"`))}
                 ${field("schedules.body", `<code>${escapeHtml((node.body || []).join(", ") || "—")}</code>`)}`;
         }
diff --git a/tests/test_automations.py b/tests/test_automations.py
index 7cabd0f0..170c5aec 100644
--- a/tests/test_automations.py
+++ b/tests/test_automations.py
@@ -332,6 +332,48 @@ def test_validate_loop_iterations_follow_configured_cap() -> None:
         validate_automation(invalid, loop_max_iterations=200)
 
 
+@pytest.mark.parametrize("count", [-1, True, False, "0", "3", 0.0, 1.5, None, [], {}])
+def test_validate_rejects_invalid_loop_count(count: Any) -> None:
+    task = _loop_cap_task(count=1, max_iterations=25)
+    task["nodes"][1]["count"] = count
+    issues = collect_automation_issues(task)
+    assert any(issue["path"] == "nodes.loop.count" for issue in issues)
+    with pytest.raises(AutomationValidationError, match="non-negative integer"):
+        validate_automation(task)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("count,expected_calls", [(0, 0), (1, 1), (None, 4)])
+async def test_loop_times_zero_skips_body_and_missing_count_uses_cap(
+    count: int | None, expected_calls: int
+) -> None:
+    execute_tool = AsyncMock(return_value="loop body")
+    send_message = AsyncMock()
+    task = _loop_cap_task(count=0 if count is None else count, max_iterations=4)
+    if count is None:
+        task["nodes"][1].pop("count")
+    task["nodes"][2] = {"id": "body", "type": "tool", "tool_name": "audit", "args": {}}
+    task["nodes"].append(
+        {"id": "after", "type": "template", "template": "after", "emit": True}
+    )
+    task["edges"].append({"from": "loop", "to": "after", "kind": "exit"})
+    validate_automation(task, loop_max_iterations=4)
+    runner = _runner(
+        execute_tool=execute_tool, send_message=send_message, loop_max_iterations=4
+    )
+    event = AutomationEvent(kind="time", channel="group")
+    await runner.run(
+        task,
+        event=event,
+        pass_text="",
+        consume_mentions=(),
+        consume_stripped="",
+        mentions_all=(),
+    )
+    assert execute_tool.await_count == expected_calls
+    send_message.assert_awaited_once_with("after")
+
+
 def _runner(
     *,
     execute_tool: Any = None,

From a77f5b2a6fdbe8aaaf7bd1972c8922b287ba34eb Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:30:49 +0800
Subject: [PATCH 088/121] fix(webui): bind chat sends to their original
 conversation

---
 docs/webui-guide.md                       |   1 +
 src/Undefined/webui/static/js/runtime.js  |  74 ++++++++-----
 tests/frontend/runtime_chat_harness.js    | 121 ++++++++++++++++++++++
 tests/test_webui_runtime_chat_behavior.py |  43 ++++++++
 4 files changed, 215 insertions(+), 24 deletions(-)

diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 67127b83..0821bcf7 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -160,6 +160,7 @@ WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：
 - WebUI WebChat 与 [Undefined Chat](undefined-chat.md) 共用 Runtime 的会话、历史、任务、事件和附件合同。区别在于 WebUI 通过 Management 后端代理 Runtime，并以 JSON polling 续接为主；Undefined Chat 是独立 Tauri 客户端，SSE 优先并在断线或 Android 生命周期恢复时使用 JSON fallback。
 - 右侧会话抽屉支持多对话管理：新建对话、切换对话、重命名对话和删除对话。桌面端默认折叠，鼠标移到右侧触发区会自动展开；移动端默认只显示“对话”按钮，点击后展开会话列表，切换会话后自动收起。新建成功后会显示提示，并短暂高亮新会话。多对话只作用于 WebChat，不影响 QQ 私聊 / 群聊历史。每个会话在后端保存为 `data/webchat/conversations/<conversation_id>.json`，删除对话会删除对应 JSON 文件；如果仍有 WebChat job 运行或正在收尾落盘，删除和清空会被拒绝。
 - WebChat 的 AI 视角始终是同一个虚拟私聊用户 `system#42`，权限仍为 `superadmin`。切换 WebUI 会话只切换后端提供给 AI 的当前 WebChat 历史，不改变 `user_id`、`sender_id` 或身份提示，因此 AI 不会把多个 WebUI 会话看成不同真实用户。
+- 发送目标在点击发送时确定；附件上传或创建任务的响应迟到时，仍使用原会话，不会清空其他会话的草稿、附件或引用，也不会接管后来建立的任务。上传期间在同一会话继续输入的草稿、新附件和新引用会保留。
 - 输入框开头输入 `/` 时会从后端 `/api/v1/commands?scope=webui` 获取当前可用斜杠命令并在输入框上方展开补全面板。面板按命令名、别名、说明和用法即时筛选，支持点击选择，也支持方向键选择、`Enter` / `Tab` 填入；直接手打 `/faq`、`/changelog` 或 alias `/cl` 这类复合命令后（命令末尾需带空格），会切换为子命令补全并显示具体用法。命令数据尚未返回时面板显示”正在加载可用命令”，不会提前显示”未找到匹配命令”；输入 `/h` 这类已命中 alias 但命令本身没有声明子命令的内容时（末尾带空格），会显示命令帮助块，包含说明、用法、示例和别名，例如 `/h [命令名] [-t]`，便于继续补参数；只有命令或子命令确实没有匹配项时才显示无匹配提示。命令清单按 WebChat 的虚拟私聊执行身份过滤，因此不会提示当前 WebUI 会话实际不可用的命令。
 - 旧版 WebChat 历史会在首次打开时自动迁移到默认会话。迁移完成后会写入标记文件，之后不会重复迁移；即使删除该默认会话，也不会再从旧历史文件恢复。未选择会话的旧接口调用会按需创建一个空的默认会话以保持向后兼容。
 - 会话标题先使用第一条用户消息的前若干字符作为临时标题；当会话已有首问和首答后，后端会使用 chat model 根据首问 + 首答生成正式标题。手动重命名的标题不会被自动生成覆盖；临时或生成失败的标题会在后续能处理时继续尝试。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index 398ef492..c09ab038 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -29,6 +29,7 @@
         chatHistoryHasMore: false,
         chatHistoryLoading: false,
         chatHistoryRequest: null,
+        chatSendRequest: null,
         chatHistoryFinalization: null,
         chatTopLoadSuppressedUntil: 0,
         chatAutoScroll: true,
@@ -2405,11 +2406,14 @@
         return added.length;
     }
 
-    function clearChatAttachments() {
-        runtimeState.chatAttachments.forEach((item) => {
+    function clearChatAttachments(items = runtimeState.chatAttachments) {
+        items.forEach((item) => {
             if (item.previewUrl) URL.revokeObjectURL(item.previewUrl);
         });
-        runtimeState.chatAttachments = [];
+        const removed = new Set(items);
+        runtimeState.chatAttachments = runtimeState.chatAttachments.filter(
+            (item) => !removed.has(item),
+        );
         renderPendingChatAttachments();
     }
 
@@ -2488,8 +2492,11 @@
         return true;
     }
 
-    function clearChatReferences() {
-        runtimeState.chatReferences = [];
+    function clearChatReferences(items = runtimeState.chatReferences) {
+        const removed = new Set(items);
+        runtimeState.chatReferences = runtimeState.chatReferences.filter(
+            (item) => !removed.has(item),
+        );
         renderPendingChatReferences();
     }
 
@@ -5060,6 +5067,7 @@
     }
 
     function resetChatConversationState() {
+        runtimeState.chatSendRequest = null;
         stopActiveJobResumeTimer();
         runtimeState.activeJobResumeAttempts = 0;
         runtimeState.activeJobResumeRequest = null;
@@ -5726,6 +5734,14 @@
         }
     }
 
+    function isCurrentChatSendRequest(request) {
+        return (
+            runtimeState.chatSendRequest === request &&
+            request.conversationId === currentChatConversationId() &&
+            request.jobId === runtimeState.activeJobId
+        );
+    }
+
     async function sendChatMessage(options = {}) {
         if (runtimeState.chatBusy) return;
         const input = get("runtimeChatInput");
@@ -5736,8 +5752,8 @@
             await createChatConversation({ switchTo: true });
         }
         if (!currentChatConversationId()) return;
-        const message =
-            retryMessage || String((input && input.value) || "").trim();
+        const inputValue = String((input && input.value) || "");
+        const message = retryMessage || inputValue.trim();
         const attachments = [...runtimeState.chatAttachments];
         const references = [...runtimeState.chatReferences];
         const outboundAttachments = retryMessage ? [] : attachments;
@@ -5749,6 +5765,11 @@
         )
             return;
 
+        const request = {
+            conversationId: currentChatConversationId(),
+            jobId: runtimeState.activeJobId,
+        };
+        runtimeState.chatSendRequest = request;
         runtimeState.chatBusy = true;
         setButtonLoading(button, true);
         syncChatBusyControls();
@@ -5762,33 +5783,36 @@
             if (!outboundMessage) {
                 throw new Error("message is required");
             }
-            clearToolCollapseTimers();
-            stopChatPolling();
-            stopChatClock();
-            runtimeState.toolBlocks.clear();
-            runtimeState.streamingMessageId = null;
-            runtimeState.activeChatMessageId = null;
-            runtimeState.lastEventSeq = 0;
-            if (!retryMessage) {
-                appendChatMessage("user", outboundMessage);
-            }
-            if (!retryMessage && input) {
-                input.value = "";
-                closeChatCommandPalette();
-                clearChatAttachments();
-                clearChatReferences();
+            if (isCurrentChatSendRequest(request)) {
+                clearToolCollapseTimers();
+                stopChatPolling();
+                stopChatClock();
+                runtimeState.toolBlocks.clear();
+                runtimeState.streamingMessageId = null;
+                runtimeState.activeChatMessageId = null;
+                runtimeState.lastEventSeq = 0;
+                if (!retryMessage) {
+                    appendChatMessage("user", outboundMessage);
+                    if (input && input.value === inputValue) {
+                        input.value = "";
+                        closeChatCommandPalette();
+                    }
+                    clearChatAttachments(outboundAttachments);
+                    clearChatReferences(outboundReferences);
+                }
+                forceScrollChatToBottomSoon();
             }
-            forceScrollChatToBottomSoon();
 
             const res = await api("/api/runtime/chat/jobs", {
                 method: "POST",
                 body: JSON.stringify({
                     message: outboundMessage,
-                    conversation_id: currentChatConversationId(),
+                    conversation_id: request.conversationId,
                     reuse_previous_user_message: !!retryMessage,
                 }),
             });
             const data = await parseJsonSafe(res);
+            if (!isCurrentChatSendRequest(request)) return;
             if (!res.ok || (data && data.error)) {
                 throw new Error(buildRequestError(res, data));
             }
@@ -5798,8 +5822,10 @@
             }
             ensureStreamingMessage();
             forceScrollChatToBottomSoon();
+            runtimeState.activeJobConversationId = request.conversationId;
             await attachChatJob(jobId, 0);
         } catch (error) {
+            if (!isCurrentChatSendRequest(request)) return;
             runtimeState.chatBusy = false;
             setButtonLoading(button, false);
             syncChatBusyControls();
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index 39a190cc..6cd97bf7 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3018,6 +3018,127 @@ for (const outcome of ["events", "done", "failure"]) {
     SCENARIOS[`stale_job_poll_${outcome}`] = (env) => staleChatJobPoll(env, outcome);
 }
 
+async function staleChatSend(env, boundary, target, outcome, newerJob) {
+    const { window, response } = env;
+    let releaseOld;
+    const posts = [];
+    const polls = [];
+    window.fetch = (url, options = {}) => {
+        const parsed = new window.URL(url, window.location.href);
+        const pathname = parsed.pathname;
+        if (pathname.endsWith("/chat/conversations")) {
+            return Promise.resolve(response(200, {
+                conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+            }));
+        }
+        if (pathname.endsWith("/chat/history")) {
+            return Promise.resolve(response(200, {
+                items: [{ role: "bot", content: `history-${parsed.searchParams.get("conversation_id")}` }],
+                has_more: false,
+            }));
+        }
+        if (pathname.endsWith("/chat/jobs/active")) {
+            return Promise.resolve(response(200, { job: null }));
+        }
+        if (pathname.endsWith("/chat/files")) {
+            return new Promise((resolve) => {
+                releaseOld = () => resolve(response(outcome === "failure" ? 500 : 200,
+                    outcome === "failure" ? { error: "obsolete upload failure" }
+                        : { id: "file-original", name: "original.txt", size: 4 }));
+            });
+        }
+        if (pathname.endsWith("/chat/jobs")) {
+            const body = JSON.parse(options.body);
+            posts.push(body);
+            if (body.message.startsWith("original")) {
+                if (boundary === "post") {
+                    return new Promise((resolve) => {
+                        releaseOld = () => resolve(response(outcome === "failure" ? 409 : 202,
+                            outcome === "failure" ? { error: "obsolete send failure" }
+                                : { job_id: "old", conversation_id: "A" }));
+                    });
+                }
+                return Promise.resolve(response(202, { job_id: "old", conversation_id: "A" }));
+            }
+            return Promise.resolve(response(202, { job_id: "new", conversation_id: body.conversation_id }));
+        }
+        if (pathname.endsWith("/events")) {
+            polls.push(String(url));
+            return Promise.resolve(response(200, { events: [], job: {
+                job_id: pathname.includes("/new/") ? "new" : "old",
+                conversation_id: parsed.searchParams.get("conversation_id"),
+                status: "running", last_seq: 0,
+            } }));
+        }
+        throw new Error(`unexpected route ${pathname}`);
+    };
+    window.RuntimeController.init();
+    await window.RuntimeController.loadChatHistory(true);
+    const input = window.document.getElementById("runtimeChatInput");
+    const button = window.document.getElementById("btnRuntimeChatSend");
+    const pick = (name) => {
+        const picker = window.document.getElementById("runtimeChatFileInput");
+        Object.defineProperty(picker, "files", {
+            configurable: true,
+            value: [new window.File(["file"], name, { type: "text/plain" })],
+        });
+        picker.dispatchEvent(new window.Event("change", { bubbles: true }));
+    };
+    input.value = "original";
+    if (boundary === "upload") pick("original.txt");
+    button.click();
+    await tick();
+    if (target !== "normal" && target !== "edited") {
+        window.document.querySelector('[data-conversation-select="B"]').click();
+        await tick();
+        if (target === "same") {
+            window.document.querySelector('[data-conversation-select="A"]').click();
+            await tick();
+        }
+    }
+    if (newerJob) {
+        input.value = "new-request";
+        button.click();
+        await tick();
+    }
+    if (target !== "normal") {
+        input.value = "later-draft";
+        pick("later.txt");
+    }
+    const snapshot = () => ({
+        title: textOf(window, "runtimeChatCurrentTitle"),
+        draft: input.value,
+        attachments: textOf(window, "runtimeChatAttachments"),
+        disabled: button.disabled,
+        busy: button.getAttribute("aria-busy"),
+        nodes: chatNodes(window).map(({ role, contentText, jobId }) => ({ role, contentText, jobId })),
+        cancelIds: Array.from(window.document.querySelectorAll("[data-cancel-job]"))
+            .filter((node) => !node.hidden).map((node) => node.dataset.cancelJob),
+        toast: textOf(window, "toast-container"),
+    });
+    const beforeLate = snapshot();
+    if (!releaseOld) throw new Error("send did not reach deferred boundary");
+    releaseOld();
+    await tick();
+    const afterLate = snapshot();
+    return { beforeLate, afterLate, posts, polls };
+}
+
+for (const boundary of ["upload", "post"]) {
+    for (const target of ["other", "same"]) {
+        for (const outcome of ["success", "failure"]) {
+            for (const newerJob of [false, true]) {
+                SCENARIOS[`stale_send_${boundary}_${target}_${outcome}_${newerJob}`] =
+                    (env) => staleChatSend(env, boundary, target, outcome, newerJob);
+            }
+        }
+    }
+    SCENARIOS[`stale_send_${boundary}_normal`] =
+        (env) => staleChatSend(env, boundary, "normal", "success", false);
+}
+SCENARIOS.stale_send_upload_edited =
+    (env) => staleChatSend(env, "upload", "edited", "success", false);
+
 async function staleChatHistoryPage(env, returnToSameConversation, outcome) {
     const { window, setRoutes, response } = env;
     const historyReads = { A: 0, B: 0 };
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index d9092e22..872eedf3 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -693,6 +693,49 @@ def test_auto_scroll_toggle_persists_preference() -> None:
 # --------------------------------------------------------------------------- #
 
 
+@pytest.mark.parametrize("boundary", ["upload", "post"])
+@pytest.mark.parametrize("target", ["other", "same"])
+@pytest.mark.parametrize("outcome", ["success", "failure"])
+@pytest.mark.parametrize("newer_job", [False, True])
+def test_late_send_preserves_current_editor_and_job(
+    boundary: str, target: str, outcome: str, newer_job: bool
+) -> None:
+    result = run_scenario(
+        f"stale_send_{boundary}_{target}_{outcome}_{str(newer_job).lower()}"
+    )
+    assert result["afterLate"] == result["beforeLate"], result
+    assert result["afterLate"]["draft"] == "later-draft", result
+    assert "later.txt" in result["afterLate"]["attachments"], result
+    original_posts = [
+        body for body in result["posts"] if body["message"].startswith("original")
+    ]
+    assert len(original_posts) == (
+        0 if boundary == "upload" and outcome == "failure" else 1
+    ), result
+    assert all(body["conversation_id"] == "A" for body in original_posts), result
+    assert all("/jobs/old/events" not in url for url in result["polls"]), result
+    assert result["afterLate"]["cancelIds"] == (["new"] if newer_job else []), result
+
+
+@pytest.mark.parametrize("boundary", ["upload", "post"])
+def test_current_send_still_attaches_its_job(boundary: str) -> None:
+    result = run_scenario(f"stale_send_{boundary}_normal")
+    assert result["posts"][0]["conversation_id"] == "A", result
+    assert result["afterLate"]["draft"] == "", result
+    assert result["afterLate"]["disabled"] is True, result
+    assert result["afterLate"]["cancelIds"] == ["old"], result
+    assert any("/jobs/old/events" in url for url in result["polls"]), result
+
+
+def test_upload_completion_preserves_new_input_and_attachments_in_same_view() -> None:
+    result = run_scenario("stale_send_upload_edited")
+    assert result["posts"][0]["conversation_id"] == "A", result
+    assert result["afterLate"]["draft"] == "later-draft", result
+    assert "later.txt" in result["afterLate"]["attachments"], result
+    assert "original.txt" not in result["afterLate"]["attachments"], result
+    assert result["afterLate"]["cancelIds"] == ["old"], result
+
+
 @pytest.mark.parametrize("target", ["other", "same"])
 @pytest.mark.parametrize("outcome", ["running", "empty", "failure"])
 def test_late_active_job_resume_cannot_replace_current_conversation_or_job(

From b53e14779bfd09e5f87a7fd56a650cddbb21f529 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:33:22 +0800
Subject: [PATCH 089/121] fix(memes): recover stale jobs during worker polling

---
 docs/configuration.md         |   2 +
 docs/memes.md                 |   2 +
 src/Undefined/main.py         |   3 -
 src/Undefined/memes/worker.py |  36 ++++++---
 tests/test_meme_worker.py     | 139 ++++++++++++++++++++++++++++++++++
 5 files changed, 168 insertions(+), 14 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 501b959d..aadf4dbd 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1352,6 +1352,8 @@ api_key = "replace-with-your-key"
 
 ### 4.27 `[memes]` 表情包库
 
+后台队列在启动与轮询时恢复超过 300 秒的遗留 `processing` 任务，并排除当前在途任务；异常退出后快速重启也会在任务过期后恢复。正常停止会等待在途任务结束，详见[表情包库](memes.md)。
+
 | 字段 | 默认值 | 说明 | 约束/回退 |
 |---|---:|---|---|
 | `enabled` | `true` | 是否启用全局表情包库 | 关闭后不会自动入库，也无法使用 `memes.*` 工具 |
diff --git a/docs/memes.md b/docs/memes.md
index 8247ddc4..9c876c8a 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -23,6 +23,8 @@ Undefined 平台自 3.3.0 版本起内置了强大的**全局表情包库**功
 4. **向量化与持久化**：
    提取出的结构化文本与标签被存入 SQLite (`MemeStore`)，并通过嵌入模型向量化后存入 ChromaDB (`MemeVectorStore`)。原图及其生成的预览图（如 GIF 抽帧）持久化存放至数据目录。
 
+任务队列在启动和每次轮询时恢复超过 300 秒的遗留 `processing` 任务。异常退出后快速重启时，尚未过期的任务会在后续轮询中过期恢复；当前 worker 正在执行的任务始终排除，不会因分析耗时较长被重复调度。正常停止会等待在途任务结束。
+
 ## AI 如何使用表情包？
 
 存储与索引完成后，AI Agent 会通过内置的 `memes.*` 系列工具使用表情包：
diff --git a/src/Undefined/main.py b/src/Undefined/main.py
index 43e813d4..aa78192c 100644
--- a/src/Undefined/main.py
+++ b/src/Undefined/main.py
@@ -427,9 +427,6 @@ async def main() -> None:
         logger.info("[认知记忆] 史官后台任务已启动")
 
     if meme_worker is not None:
-        if meme_job_queue is not None:
-            recovered = await meme_job_queue.recover_stale(timeout_seconds=300.0)
-            logger.info("[memes] 启动前陈旧任务恢复完成: recovered=%s", recovered)
         await meme_worker.start()
         logger.info("[memes] 后台任务已启动")
 
diff --git a/src/Undefined/memes/worker.py b/src/Undefined/memes/worker.py
index a0c2cc0b..236d4a0f 100644
--- a/src/Undefined/memes/worker.py
+++ b/src/Undefined/memes/worker.py
@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+from functools import partial
 from typing import Any
 
 logger = logging.getLogger(__name__)
@@ -16,15 +17,18 @@ def __init__(
         poll_interval_seconds: float = 1.0,
         max_retries: int = 3,
         max_concurrency: int = 4,
+        stale_job_timeout_seconds: float = 300.0,
     ) -> None:
         self._job_queue = job_queue
         self._meme_service = meme_service
         self._poll_interval_seconds = max(0.1, float(poll_interval_seconds))
         self._max_retries = max(0, int(max_retries))
         self._max_concurrency = max(1, int(max_concurrency))
+        self._stale_job_timeout_seconds = max(0.0, float(stale_job_timeout_seconds))
         self._stop_event = asyncio.Event()
         self._task: asyncio.Task[None] | None = None
         self._inflight_tasks: set[asyncio.Task[None]] = set()
+        self._active_jobs: set[str] = set()
         self._semaphore = asyncio.Semaphore(self._max_concurrency)
 
     async def start(self) -> None:
@@ -44,18 +48,17 @@ async def stop(self) -> None:
 
     async def _poll_loop(self) -> None:
         while not self._stop_event.is_set():
-            if len(self._inflight_tasks) >= self._max_concurrency:
-                try:
-                    await asyncio.wait_for(
-                        self._stop_event.wait(), timeout=self._poll_interval_seconds
-                    )
-                except asyncio.TimeoutError:
-                    pass
-                continue
             try:
-                result = await self._job_queue.dequeue()
+                await self._job_queue.recover_stale(
+                    self._stale_job_timeout_seconds, exclude_job_ids=self._active_jobs
+                )
+                result = (
+                    await self._job_queue.dequeue()
+                    if len(self._inflight_tasks) < self._max_concurrency
+                    else None
+                )
             except Exception:
-                logger.exception("[memes] dequeue failed")
+                logger.exception("[memes] queue poll failed")
                 try:
                     await asyncio.wait_for(
                         self._stop_event.wait(), timeout=self._poll_interval_seconds
@@ -74,7 +77,18 @@ async def _poll_loop(self) -> None:
             job_id, job = result
             task = asyncio.create_task(self._process_job_with_permit(job_id, job))
             self._inflight_tasks.add(task)
-            task.add_done_callback(self._inflight_tasks.discard)
+            self._active_jobs.add(job_id)
+            task.add_done_callback(partial(self._job_finished, job_id))
+
+    def _job_finished(self, job_id: str, task: asyncio.Task[None]) -> None:
+        self._inflight_tasks.discard(task)
+        self._active_jobs.discard(job_id)
+        if not task.cancelled() and (error := task.exception()) is not None:
+            logger.error(
+                "[memes] job 未收敛，保留 processing 等待恢复: job_id=%s error=%s",
+                job_id,
+                error,
+            )
 
     async def _process_job_with_permit(self, job_id: str, job: dict[str, Any]) -> None:
         async with self._semaphore:
diff --git a/tests/test_meme_worker.py b/tests/test_meme_worker.py
index 8db84376..1447cce6 100644
--- a/tests/test_meme_worker.py
+++ b/tests/test_meme_worker.py
@@ -1,12 +1,17 @@
 from __future__ import annotations
 
 import asyncio
+import os
+import time
+from collections.abc import Collection
+from pathlib import Path
 from types import SimpleNamespace
 from typing import Any
 
 import pytest
 
 from Undefined.memes.worker import MemeWorker
+from Undefined.cognitive.job_queue import JobQueue
 
 
 class _FakeQueue:
@@ -41,6 +46,11 @@ async def requeue(self, job_id: str, error: str) -> None:
     async def fail(self, job_id: str, error: str) -> None:
         self.failed.append((job_id, error))
 
+    async def recover_stale(
+        self, timeout_seconds: float, *, exclude_job_ids: Collection[str] = ()
+    ) -> int:
+        return 0
+
 
 @pytest.mark.asyncio
 async def test_meme_worker_respects_max_concurrency() -> None:
@@ -99,3 +109,132 @@ async def _process_job(job: dict[str, Any]) -> None:
 
     assert queue.dequeue_calls >= 2
     assert processed == []
+
+
+@pytest.mark.asyncio
+async def test_meme_worker_recovers_fast_restart_orphan_after_it_becomes_stale(
+    tmp_path: Path,
+) -> None:
+    previous_queue = JobQueue(tmp_path)
+    orphan = await previous_queue.enqueue({"marker": "orphan"})
+    assert await previous_queue.dequeue() is not None
+    queue = JobQueue(tmp_path)
+    processed: list[str] = []
+    orphan_processed = asyncio.Event()
+
+    async def process_job(job: dict[str, Any]) -> None:
+        processed.append(str(job["marker"]))
+        if job["marker"] == "orphan":
+            orphan_processed.set()
+
+    worker = MemeWorker(
+        job_queue=queue,
+        meme_service=SimpleNamespace(process_job=process_job),
+        poll_interval_seconds=0.1,
+    )
+    await worker.start()
+    try:
+        assert queue.snapshot()["processing"] == 1
+        await queue.enqueue({"marker": "fresh"})
+        stamp = time.time() - 301
+        os.utime(tmp_path / "processing" / f"{orphan}.json", (stamp, stamp))
+        await asyncio.wait_for(orphan_processed.wait(), timeout=2)
+    finally:
+        await worker.stop()
+    assert sorted(processed) == ["fresh", "orphan"]
+    assert queue.snapshot()["processing"] == queue.snapshot()["pending"] == 0
+
+
+@pytest.mark.asyncio
+async def test_meme_worker_does_not_recover_active_long_running_job(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    queue = JobQueue(tmp_path)
+    job_id = await queue.enqueue({"marker": "active"})
+    started = asyncio.Event()
+    release = asyncio.Event()
+    checked = asyncio.Event()
+    calls: list[str] = []
+    real_recover = queue.recover_stale
+
+    async def recover_stale(
+        timeout_seconds: float, *, exclude_job_ids: Collection[str] = ()
+    ) -> int:
+        recovered = await real_recover(timeout_seconds, exclude_job_ids=exclude_job_ids)
+        if started.is_set() and not release.is_set():
+            assert job_id in exclude_job_ids
+            assert recovered == 0
+            checked.set()
+        return recovered
+
+    async def process_job(job: dict[str, Any]) -> None:
+        calls.append(str(job["marker"]))
+        started.set()
+        await release.wait()
+
+    monkeypatch.setattr(queue, "recover_stale", recover_stale)
+    worker = MemeWorker(
+        job_queue=queue,
+        meme_service=SimpleNamespace(process_job=process_job),
+        max_concurrency=1,
+        poll_interval_seconds=0.1,
+    )
+    await worker.start()
+    try:
+        await asyncio.wait_for(started.wait(), timeout=2)
+        stamp = time.time() - 301
+        os.utime(tmp_path / "processing" / f"{job_id}.json", (stamp, stamp))
+        await asyncio.wait_for(checked.wait(), timeout=2)
+        assert queue.snapshot()["processing"] == 1
+        assert queue.snapshot()["pending"] == 0
+        assert calls == ["active"]
+    finally:
+        release.set()
+        await worker.stop()
+    assert not worker._active_jobs
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["cancel", "complete"])
+async def test_meme_worker_recovers_job_after_task_did_not_complete(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    failure: str,
+) -> None:
+    queue = JobQueue(tmp_path)
+    await queue.enqueue({"marker": "retry"})
+    processed = 0
+    finished = asyncio.Event()
+    real_complete = queue.complete
+    complete_calls = 0
+
+    async def process_job(job: dict[str, Any]) -> None:
+        nonlocal processed
+        processed += 1
+        if failure == "cancel" and processed == 1:
+            raise asyncio.CancelledError
+
+    async def complete(job_id: str) -> None:
+        nonlocal complete_calls
+        complete_calls += 1
+        if failure == "complete" and complete_calls == 1:
+            raise OSError("isolated completion failure")
+        await real_complete(job_id)
+        finished.set()
+
+    monkeypatch.setattr(queue, "complete", complete)
+    worker = MemeWorker(
+        job_queue=queue,
+        meme_service=SimpleNamespace(process_job=process_job),
+        stale_job_timeout_seconds=0,
+        poll_interval_seconds=0.1,
+    )
+    await worker.start()
+    try:
+        await asyncio.wait_for(finished.wait(), timeout=2)
+    finally:
+        await worker.stop()
+    assert processed == 2
+    assert not worker._active_jobs
+    assert queue.snapshot()["processing"] == 0

From 5b135df9d312fe28ad5f444a2f181b9a96130056 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:34:13 +0800
Subject: [PATCH 090/121] fix(weixin): preserve uncertain delivery across
 business fallbacks

---
 docs/development.md               |   1 +
 docs/wechat-ilink.md              |   2 +
 src/Undefined/utils/sender.py     |  24 +---
 src/Undefined/weixin/service.py   |   3 +-
 src/Undefined/weixin/transport.py |  54 +++++++++
 tests/test_weixin_delivery.py     | 183 ++++++++++++++++++++++++++++++
 6 files changed, 245 insertions(+), 22 deletions(-)
 create mode 100644 src/Undefined/weixin/transport.py
 create mode 100644 tests/test_weixin_delivery.py

diff --git a/docs/development.md b/docs/development.md
index b6345220..aecceb9d 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -26,6 +26,7 @@ src/Undefined/
 ├── handlers/      # OneBot 消息分流（message_flow / poke / repeat / auto_extract）
 ├── jm/            # 禁漫（JM / 18comic）车号解析、关键词搜索、逐章 PDF 下载合成与 zip 打包
 ├── onebot/        # OneBot WebSocket 客户端
+├── weixin/        # 微信 iLink：service 账号生命周期、store 凭据/映射、audio 语音准备、transport 投递状态适配
 ├── skills/        # 技能插件核心目录 (存放所有的工具与智能体)
 │   ├── tools/           # 基础原子的工具 (独立的功能单元，如读写文件、网络请求等)
 │   ├── toolsets/        # 聚合工具集 (分组后的工具组)
diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 2c430e63..bf146b2d 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -116,6 +116,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 每次文本、文件、语音或多项目批次收到发送确认后，都会立即标记当前轮已经输出；这个标记不依赖历史记录开关。后续批次失败时，前面已经确认发送的事实仍会保留，`end` 不会将整轮误判为没有输出。
 
+消息请求进入 SDK 的 `sendmessage` 派发阶段后，网络超时或非明确拒绝会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败不会被误标为已投递；明确结构拒绝仍可安全回退。
+
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
 
 Bot 层通过 `messages.send_voice(uid, address?)` 显式选择“作为语音发送”。普通 `<attachment uid="file_xxx"/>` 始终保留原始文件语义，即使扩展名是 `.wav`；`CQ:record`、`CQ:audio` 和内部明确标记为 voice 的媒体回调则发送原生语音。QQ 侧继续转换为 `CQ:record`，微信侧先用 FFmpeg 归一化为 24 kHz、16-bit、单声道 PCM，再由 `silk-python` 编码为 Tencent SILK。部署机必须能从 `PATH` 找到 `ffmpeg`；缺失、音频无效或超出 `[weixin].media_max_size_mb` 时会在任何消息段发出前失败，不会自动改成文件。
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index f5290022..5f19704d 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -9,17 +9,12 @@
 from urllib.request import url2pathname
 
 from weixin_ilink_client import (
-    ApiError,
-    HttpError,
     MediaKind,
     OutboundMediaItem,
     OutboundMessageItem,
     OutboundTextItem,
     RefMessage,
-    SessionPausedError,
-    UnsupportedCapabilityError,
 )
-from weixin_ilink_client.constants import STALE_TOKEN_ERROR_CODE
 
 from Undefined.attachments import (
     AttachmentRecord,
@@ -46,6 +41,9 @@
 )
 from Undefined.utils.message_turn import mark_message_sent_this_turn
 from Undefined.weixin.audio import PreparedWeixinVoice
+from Undefined.weixin.transport import (
+    is_definitive_weixin_delivery_rejection as is_definitive_weixin_delivery_rejection,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -98,22 +96,6 @@ def _coerce_qq_reply_id(value: int | str | None) -> int | None:
     return parsed
 
 
-def is_definitive_weixin_delivery_rejection(exc: BaseException) -> bool:
-    if isinstance(exc, SessionPausedError):
-        return False
-    if isinstance(exc, UnsupportedCapabilityError):
-        return True
-    if isinstance(exc, ApiError):
-        return exc.code != STALE_TOKEN_ERROR_CODE
-    if isinstance(exc, HttpError):
-        return 400 <= exc.status_code < 500 and exc.status_code not in {
-            408,
-            425,
-            429,
-        }
-    return False
-
-
 def _format_size(size_bytes: int | None) -> str:
     if size_bytes is None or size_bytes < 0:
         return "未知大小"
diff --git a/src/Undefined/weixin/service.py b/src/Undefined/weixin/service.py
index b6050c84..e5a1dd7e 100644
--- a/src/Undefined/weixin/service.py
+++ b/src/Undefined/weixin/service.py
@@ -47,6 +47,7 @@
 )
 from Undefined.weixin.models import WeixinAccount, normalize_alias
 from Undefined.weixin.store import UndefinedIlinkStateStore, WeixinStore
+from Undefined.weixin.transport import UndefinedIlinkTransport
 
 logger = logging.getLogger(__name__)
 
@@ -269,7 +270,7 @@ def _build_client(
         state_store: UndefinedIlinkStateStore,
         options: ClientOptions,
     ) -> WeixinClientProtocol:
-        transport = IlinkTransport(bot_agent=self._bot_agent)
+        transport = UndefinedIlinkTransport(bot_agent=self._bot_agent)
         return AsyncWeixinIlinkClient(
             account.credentials,
             transport=transport,
diff --git a/src/Undefined/weixin/transport.py b/src/Undefined/weixin/transport.py
new file mode 100644
index 00000000..54f22578
--- /dev/null
+++ b/src/Undefined/weixin/transport.py
@@ -0,0 +1,54 @@
+"""在 iLink 消息派发边界统一仓库投递错误合同。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from weixin_ilink_client import (
+    ApiError,
+    HttpError,
+    IlinkTransport,
+    SessionPausedError,
+    UnsupportedCapabilityError,
+    WeixinCredentials,
+    WeixinIlinkError,
+)
+from weixin_ilink_client.constants import STALE_TOKEN_ERROR_CODE
+
+
+def is_definitive_weixin_delivery_rejection(exc: BaseException) -> bool:
+    """只有明确拒绝的消息结构错误才允许降级重发。"""
+    if isinstance(exc, SessionPausedError):
+        return False
+    if isinstance(exc, UnsupportedCapabilityError):
+        return True
+    if isinstance(exc, ApiError):
+        return exc.code != STALE_TOKEN_ERROR_CODE
+    if isinstance(exc, HttpError):
+        return 400 <= exc.status_code < 500 and exc.status_code not in {408, 425, 429}
+    return False
+
+
+class WeixinDeliveryUncertainError(WeixinIlinkError):
+    """消息派发已发起，但上游没有给出可确认的投递结果。"""
+
+    delivery_uncertain: bool = True
+
+
+class UndefinedIlinkTransport(IlinkTransport):
+    """仅适配 sendmessage；媒体上传与其他准备错误保留原有语义。"""
+
+    async def send_message(
+        self,
+        credentials: WeixinCredentials,
+        message: Mapping[str, Any],
+    ) -> None:
+        try:
+            await super().send_message(credentials, message)
+        except WeixinIlinkError as exc:
+            if is_definitive_weixin_delivery_rejection(exc):
+                raise
+            raise WeixinDeliveryUncertainError(
+                "微信投递结果未确认，禁止自动重发"
+            ) from exc
diff --git a/tests/test_weixin_delivery.py b/tests/test_weixin_delivery.py
new file mode 100644
index 00000000..54d1a692
--- /dev/null
+++ b/tests/test_weixin_delivery.py
@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock, MagicMock
+
+import httpx
+import pytest
+from weixin_ilink_client import (
+    AsyncWeixinIlinkClient,
+    ClientOptions,
+    MediaKind,
+    OutboundMediaItem,
+    RequestTimeoutError,
+    WeixinCredentials,
+)
+
+from Undefined.config import Config
+from Undefined.jm.sender import _send_result
+from Undefined.utils.message_targets import DeliveryAddress
+from Undefined.utils.sender import AddressBoundSender, MessageSender
+from Undefined.weixin.models import WeixinAccount
+from Undefined.weixin.service import WeixinService
+from Undefined.weixin.store import UndefinedIlinkStateStore
+from Undefined.weixin.transport import (
+    UndefinedIlinkTransport,
+    WeixinDeliveryUncertainError,
+)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("response", ["timeout", "server_error", "rejection"])
+async def test_sdk_dispatch_error_controls_jm_fallback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    response: str,
+) -> None:
+    requests: list[dict[str, Any]] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        message = json.loads(request.content)["msg"]
+        requests.append(message)
+        if len(requests) == 1:
+            if response == "timeout":
+                raise httpx.ReadTimeout("response lost after POST", request=request)
+            if response == "server_error":
+                return httpx.Response(503, request=request)
+            return httpx.Response(200, json={"ret": 40001}, request=request)
+        return httpx.Response(200, json={"ret": 0}, request=request)
+
+    config = Config.from_mapping(
+        {"weixin": {"enabled": True, "state_dir": str(tmp_path)}}, strict=False
+    )
+    service = WeixinService(config)
+    credentials = WeixinCredentials(
+        "isolated-account",
+        "isolated-token",
+        "https://isolated.invalid",
+        "isolated-user",
+    )
+    history = MagicMock()
+    history.add_private_message = AsyncMock()
+    sender_config = MagicMock()
+    sender_config.is_private_allowed.return_value = True
+    sender_config.weixin.multi_item_messages_enabled = True
+    sender_config.weixin.multi_item_max_items = 10
+    sender_config.weixin.media_max_size_mb = 100
+    sender = MessageSender(MagicMock(), history, bot_qq=999, config=sender_config)
+    sender.set_weixin_service(service)
+    zip_send = AsyncMock(return_value="zip-ack")
+    monkeypatch.setattr(service, "send_file", zip_send)
+    source = tmp_path / "report.zip"
+    source.write_bytes(b"isolated zip")
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handle)) as http_client:
+        client = AsyncWeixinIlinkClient(
+            credentials,
+            transport=UndefinedIlinkTransport(http_client=http_client),
+        )
+        monkeypatch.setattr(
+            service,
+            "_resolve_runtime",
+            AsyncMock(
+                return_value=(
+                    SimpleNamespace(peer_id="isolated-peer"),
+                    SimpleNamespace(client=client),
+                )
+            ),
+        )
+        status = await _send_result(
+            cast(
+                MessageSender,
+                AddressBoundSender(sender, DeliveryAddress("wechat", 12345)),
+            ),
+            "private",
+            12345,
+            book_id="123456",
+            info_text="book info",
+            password="isolated-password",
+            zip_path=source,
+            history_message="book info",
+        )
+    zip_send.assert_awaited_once()
+    await service.stop()
+    if response == "rejection":
+        assert [len(message["item_list"]) for message in requests] == [2, 1, 1]
+        assert "已发送合并转发" in status
+    else:
+        assert len(requests) == 1
+        assert len(requests[0]["item_list"]) == 2
+        assert "投递结果未确认" in status
+
+
+@pytest.mark.asyncio
+async def test_dispatch_timeout_preserves_sdk_cause() -> None:
+    def timeout(request: httpx.Request) -> httpx.Response:
+        raise httpx.ReadTimeout("response lost", request=request)
+
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    async with httpx.AsyncClient(transport=httpx.MockTransport(timeout)) as client:
+        transport = UndefinedIlinkTransport(http_client=client)
+        with pytest.raises(WeixinDeliveryUncertainError) as raised:
+            await transport.send_message(credentials, {"item_list": []})
+    assert raised.value.delivery_uncertain is True
+    assert isinstance(raised.value.__cause__, RequestTimeoutError)
+    assert isinstance(raised.value.__cause__.__cause__, httpx.ReadTimeout)
+
+
+@pytest.mark.asyncio
+async def test_sdk_media_preparation_failure_is_not_dispatched() -> None:
+    paths: list[str] = []
+
+    def timeout(request: httpx.Request) -> httpx.Response:
+        paths.append(request.url.path)
+        raise httpx.ReadTimeout("upload preparation failed", request=request)
+
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    async with httpx.AsyncClient(transport=httpx.MockTransport(timeout)) as http_client:
+        client = AsyncWeixinIlinkClient(
+            credentials,
+            transport=UndefinedIlinkTransport(http_client=http_client),
+            options=ClientOptions(media_upload_attempts=1),
+        )
+        with pytest.raises(RequestTimeoutError) as raised:
+            await client.send_items(
+                "peer", [OutboundMediaItem(MediaKind.FILE, b"file", "report.txt")]
+            )
+    assert not getattr(raised.value, "delivery_uncertain", False)
+    assert paths == ["/ilink/bot/getuploadurl"]
+
+
+@pytest.mark.asyncio
+async def test_production_client_uses_dispatch_adapter(tmp_path: Path) -> None:
+    config = Config.from_mapping(
+        {"weixin": {"enabled": True, "state_dir": str(tmp_path)}}, strict=False
+    )
+    service = WeixinService(config)
+    account = WeixinAccount(
+        alias="isolated",
+        qq_id=12345,
+        credentials=WeixinCredentials(
+            "account", "token", "https://isolated.invalid", "user"
+        ),
+        enabled=True,
+        created_at="",
+        updated_at="",
+    )
+    client = cast(
+        AsyncWeixinIlinkClient,
+        service._build_client(
+            account,
+            UndefinedIlinkStateStore(tmp_path / "runtime.json"),
+            ClientOptions(),
+        ),
+    )
+    assert isinstance(client.transport, UndefinedIlinkTransport)
+    await client.aclose()
+    await service.stop()

From acd78cac4162e42d87a0c66fdd46bb8e69ce8a09 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:34:31 +0800
Subject: [PATCH 091/121] fix(config): catch up saved changes when restarting
 watchers

---
 docs/configuration.md                |   2 +
 src/Undefined/config/manager.py      |  20 ++--
 tests/test_config_watcher_restart.py | 157 +++++++++++++++++++++++++++
 3 files changed, 172 insertions(+), 7 deletions(-)
 create mode 100644 tests/test_config_watcher_restart.py

diff --git a/docs/configuration.md b/docs/configuration.md
index aadf4dbd..7b0d9073 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1505,6 +1505,8 @@ Management 的 WebUI 配置按 [§4.23](#423-webui) 的时机生效：密码和
 - `skills.hot_reload*`（技能热重载任务重启）
 - `skills.hot_reload_interval/debounce`（配置热更新监听器自身重启）
 
+配置监听器启动和重启时会先重新读取并应用最新文件，再继续轮询；监听器切换期间保存的变更也会追赶应用。读取失败仍保留上次有效配置，监听任务继续运行，文件修正后再次保存即可重新加载。
+
 ### 5.4 其他字段
 - `Config` 对象本身会更新。
 
diff --git a/src/Undefined/config/manager.py b/src/Undefined/config/manager.py
index 50f93851..48a2da53 100644
--- a/src/Undefined/config/manager.py
+++ b/src/Undefined/config/manager.py
@@ -98,6 +98,9 @@ async def stop_hot_reload(self, timeout: float | None = 2.0) -> None:
 
     async def _watch_loop(self, interval: float, debounce: float) -> None:
         self._last_snapshot = self._compute_snapshot()
+        # 启动和重启时追赶 load/上一监听器退出后发生的保存；先记快照，
+        # 保证读取期间另一进程的写入仍能在下一轮被发现。
+        await self._reload_from_disk()
         last_change = 0.0
         pending = False
         while self._watch_stop and not self._watch_stop.is_set():
@@ -109,13 +112,16 @@ async def _watch_loop(self, interval: float, debounce: float) -> None:
                 pending = True
             if pending and (time.monotonic() - last_change) >= debounce:
                 pending = False
-                async with self._reload_lock:
-                    try:
-                        changes = self.reload(strict=False)
-                        if changes:
-                            logger.info("[配置] 已应用热更新: %s", ", ".join(changes))
-                    except Exception as exc:
-                        logger.warning("[配置] 热重载失败: %s", exc)
+                await self._reload_from_disk()
+
+    async def _reload_from_disk(self) -> None:
+        async with self._reload_lock:
+            try:
+                changes = self.reload(strict=False)
+                if changes:
+                    logger.info("[配置] 已应用热更新: %s", ", ".join(changes))
+            except Exception as exc:
+                logger.warning("[配置] 热重载失败: %s", exc)
 
     def _compute_snapshot(self) -> dict[str, tuple[int, int]]:
         snapshot: dict[str, tuple[int, int]] = {}
diff --git a/tests/test_config_watcher_restart.py b/tests/test_config_watcher_restart.py
new file mode 100644
index 00000000..34557e8a
--- /dev/null
+++ b/tests/test_config_watcher_restart.py
@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import AsyncMock
+
+import pytest
+from aiohttp import web
+
+from Undefined.config import Config
+from Undefined.config.hot_reload import (
+    HotReloadContext,
+    _BACKGROUND_TASKS,
+    apply_config_updates,
+)
+from Undefined.config.manager import ConfigManager
+from Undefined.webui.core import SessionStore
+from Undefined.webui.routes import _config
+from Undefined.webui.routes._shared import SESSION_STORE_APP_KEY
+from Undefined.webui.utils import config_io
+
+
+class _Request(SimpleNamespace):
+    async def json(self) -> dict[str, Any]:
+        return cast(dict[str, Any], self.body)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("broken_start", [False, True])
+async def test_watcher_catches_saves_before_start_and_survives_invalid_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, broken_start: bool
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text("[core]\nai_request_max_retries=2\n", encoding="utf-8")
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    applied = asyncio.Event()
+    manager.subscribe(lambda _updated, _changes: applied.set())
+    path.write_text(
+        "[core\n" if broken_start else "[core]\nai_request_max_retries=7\n",
+        encoding="utf-8",
+    )
+    manager.start_hot_reload(interval=0.01, debounce=0.01)
+    try:
+        if broken_start:
+            await asyncio.sleep(0.03)
+            assert config.ai_request_max_retries == 2
+            assert manager._watch_task is not None and not manager._watch_task.done()
+            path.write_text("[core]\nai_request_max_retries=7\n", encoding="utf-8")
+        await asyncio.wait_for(applied.wait(), timeout=2)
+        assert config.ai_request_max_retries == 7
+    finally:
+        await manager.stop_hot_reload()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("change_interval_again", [False, True])
+async def test_management_save_during_watcher_restart_reaches_runtime(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    change_interval_again: bool,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text(
+        "[core]\nbot_qq=10001\nsuperadmin_qq=20002\nai_request_max_retries=2\n"
+        "[skills]\nhot_reload_interval=0.01\nhot_reload_debounce=0.01\n",
+        encoding="utf-8",
+    )
+    runtime = ConfigManager(path)
+    current = runtime.load(strict=False)
+    management = ConfigManager(path)
+    management.load(strict=False)
+    updates: list[int] = []
+    applied = asyncio.Event()
+
+    def update_retries(value: int) -> None:
+        updates.append(value)
+        applied.set()
+
+    registry = SimpleNamespace(
+        stop_hot_reload=AsyncMock(), start_hot_reload=lambda **_: None
+    )
+    context = HotReloadContext(
+        ai_client=cast(
+            Any, SimpleNamespace(tool_registry=registry, agent_registry=registry)
+        ),
+        queue_manager=cast(Any, SimpleNamespace(update_max_retries=update_retries)),
+        config_manager=runtime,
+        security_service=cast(Any, SimpleNamespace(apply_config=lambda _: None)),
+    )
+
+    def on_change(config: Config, changes: dict[str, tuple[Any, Any]]) -> None:
+        apply_config_updates(config, changes, context)
+
+    runtime.subscribe(on_change)
+    app = web.Application()
+    sessions = SessionStore()
+    app[SESSION_STORE_APP_KEY] = sessions
+    token = sessions.create(kind="access")
+    monkeypatch.setattr(_config, "CONFIG_PATH", path)
+    monkeypatch.setattr(config_io, "CONFIG_PATH", path)
+    monkeypatch.setattr(_config, "get_config_manager", lambda: management)
+
+    async def patch_config(body: dict[str, Any]) -> web.StreamResponse:
+        request = cast(
+            web.Request,
+            _Request(
+                body={"patch": body},
+                app=app,
+                headers={"Authorization": f"Bearer {token}"},
+                cookies={},
+                query={},
+            ),
+        )
+        return await _config.config_patch_handler(request)
+
+    stopped = asyncio.Event()
+    release = asyncio.Event()
+    original_stop = runtime.stop_hot_reload
+
+    async def pause_restart(timeout: float | None = 2.0) -> None:
+        await original_stop(timeout)
+        stopped.set()
+        await release.wait()
+
+    monkeypatch.setattr(runtime, "stop_hot_reload", pause_restart)
+    runtime.start_hot_reload(interval=0.01, debounce=0.01)
+    try:
+        await asyncio.sleep(0)
+        first = await patch_config({"skills.hot_reload_interval": 0.02})
+        assert first.status == 200
+        await asyncio.wait_for(stopped.wait(), timeout=2)
+        second_patch: dict[str, Any] = {"core.ai_request_max_retries": 7}
+        if change_interval_again:
+            second_patch["skills.hot_reload_interval"] = 0.03
+        second = await patch_config(second_patch)
+        assert second.status == 200
+        assert current.ai_request_max_retries == 2
+        release.set()
+        await asyncio.wait_for(applied.wait(), timeout=2)
+        assert current.ai_request_max_retries == 7
+        assert updates == [7]
+        assert management.load(strict=False).ai_request_max_retries == 7
+        if _BACKGROUND_TASKS:
+            await asyncio.gather(*list(_BACKGROUND_TASKS))
+        assert runtime._watch_task is not None and not runtime._watch_task.done()
+    finally:
+        release.set()
+        if _BACKGROUND_TASKS:
+            await asyncio.gather(*list(_BACKGROUND_TASKS), return_exceptions=True)
+        await original_stop()

From 88a62a8f085cfd3ac3ddf8f2a8ff3f1639d0033d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:35:11 +0800
Subject: [PATCH 092/121] fix(chat): publish conversation changes after durable
 commits

---
 docs/management-api.md              |   1 +
 docs/openapi.md                     |   1 +
 src/Undefined/api/webchat_store.py  |  23 ++--
 tests/test_webchat_store_commits.py | 206 ++++++++++++++++++++++++++++
 4 files changed, 222 insertions(+), 9 deletions(-)
 create mode 100644 tests/test_webchat_store_commits.py

diff --git a/docs/management-api.md b/docs/management-api.md
index 7c6a2502..eb7b4930 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -247,6 +247,7 @@ GET /api/v1/management/runtime/commands?scope=webui&q=help
   - `DELETE` 使用路径参数 `conversation_id`。
 - 校验：
   - 删除会话与接受新任务共用串行边界；存在运行中或收尾落盘的 WebChat job 时返回 `409`，已删除会话创建新任务返回 `404`。
+  - 新建、改名、清空与标题更新在原子落盘成功后才发布缓存；删除在文件移除后才撤销缓存和标题任务。磁盘错误保留上次成功状态；写入已开始后收到取消，会等待持久操作和缓存更新收敛再释放会话锁。
 - 响应：
   - `200` / `201`：会话列表或会话对象。
   - `404`：会话不存在。
diff --git a/docs/openapi.md b/docs/openapi.md
index 93b889c1..93fc5130 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -391,6 +391,7 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 - 权限视角：`superadmin`。
 - 如果输入以 `/` 开头，按私聊命令分发执行（遵循命令 `allow_in_private` 开放策略）。
 - WebChat 会话持久化在 `data/webchat/conversations/<conversation_id>.json`，一个会话一个 JSON 文件。删除会话会删除对应 JSON；不会写入单个全局 conversations JSON。
+- 会话创建、改名、清空、标题状态及生成标题均在持久写入成功后更新可见缓存；写盘失败保留上次成功状态。删除失败也保留会话与标题任务，便于重试。持久操作开始后取消请求，会等文件和缓存提交收敛后再释放会话锁。
 - 首次加载会自动把旧版 `data/history/private_42.json` 或运行中的旧历史管理器记录迁移到 `legacy-system-42`，并写入 `data/webchat/legacy_private_42_migrated.json` 迁移标记。只要标记存在就不会重复迁移；即使删除迁移出的会话，也不会再次从旧文件恢复。
 
 ### WebUI AI Chat Conversations
diff --git a/src/Undefined/api/webchat_store.py b/src/Undefined/api/webchat_store.py
index b1a44381..14da487f 100644
--- a/src/Undefined/api/webchat_store.py
+++ b/src/Undefined/api/webchat_store.py
@@ -176,7 +176,6 @@ async def create_conversation(
             existing = self._cache.get(conv_id)
             if existing is not None:
                 return _copy_json(existing)
-            self._cache[conv_id] = conv
             await self._save_conversation_locked(conv)
             logger.info(
                 "[WebChat] 创建会话: conversation_id=%s title_source=%s",
@@ -193,7 +192,7 @@ async def rename_conversation(
         if not clean_title:
             raise ValueError("title is required")
         async with self._get_lock(conv_id):
-            conv = self._require_conversation_locked(conv_id)
+            conv = _copy_json(self._require_conversation_locked(conv_id))
             conv["title"] = clean_title
             conv["title_source"] = "manual"
             conv["title_status"] = _TITLE_STATUS_MANUAL
@@ -211,13 +210,16 @@ async def delete_conversation(self, conversation_id: str) -> bool:
         conv_id = _normalize_conversation_id(conversation_id)
         async with self._get_lock(conv_id):
             existed = conv_id in self._cache or self._path_for(conv_id).exists()
-            self._cache.pop(conv_id, None)
             path = self._path_for(conv_id)
-            if path.exists():
-                await asyncio.to_thread(path.unlink)
-            task = self._title_tasks.pop(conv_id, None)
-            if task is not None:
-                task.cancel()
+
+            async def commit_delete() -> None:
+                await io.delete_file(path)
+                self._cache.pop(conv_id, None)
+                task = self._title_tasks.pop(conv_id, None)
+                if task is not None:
+                    task.cancel()
+
+            await io.run_cancellation_safe(commit_delete())
             logger.info(
                 "[WebChat] 删除会话: conversation_id=%s existed=%s",
                 conv_id,
@@ -228,7 +230,7 @@ async def delete_conversation(self, conversation_id: str) -> bool:
     async def clear_conversation(self, conversation_id: str) -> int:
         conv_id = _normalize_conversation_id(conversation_id)
         async with self._get_lock(conv_id):
-            conv = self._require_conversation_locked(conv_id)
+            conv = _copy_json(self._require_conversation_locked(conv_id))
             previous = len(_messages(conv))
             conv["messages"] = []
             conv["updated_at"] = _now_iso()
@@ -375,6 +377,7 @@ async def mark_title_pending(self, conversation_id: str) -> bool:
             first_pair = _first_question_answer_from_conv(conv)
             if first_pair is None:
                 return False
+            conv = _copy_json(conv)
             conv["title_status"] = _TITLE_STATUS_PENDING
             conv["title_basis_hash"] = _title_basis_hash(*first_pair)
             conv["title_requested_at"] = _now_iso()
@@ -407,6 +410,7 @@ async def apply_generated_title(
             first_pair = _first_question_answer_from_conv(conv)
             if first_pair is None or _title_basis_hash(*first_pair) != basis_hash:
                 return False
+            conv = _copy_json(conv)
             conv["title"] = clean_title
             conv["title_source"] = "model"
             conv["title_status"] = _TITLE_STATUS_GENERATED
@@ -430,6 +434,7 @@ async def mark_title_failed(self, conversation_id: str, basis_hash: str) -> None
                 return
             if str(conv.get("title_basis_hash") or "") != basis_hash:
                 return
+            conv = _copy_json(conv)
             conv["title_status"] = _TITLE_STATUS_FAILED
             conv["title_failed_at"] = _now_iso()
             await self._save_conversation_locked(conv)
diff --git a/tests/test_webchat_store_commits.py b/tests/test_webchat_store_commits.py
new file mode 100644
index 00000000..20913039
--- /dev/null
+++ b/tests/test_webchat_store_commits.py
@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from Undefined.api import webchat_store
+from Undefined.utils import io
+
+_OPERATIONS = (
+    "create",
+    "rename",
+    "clear",
+    "append",
+    "delete",
+    "title_pending",
+    "title_generated",
+    "title_failed",
+)
+
+
+async def _seed(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    operation: str,
+) -> webchat_store.WebChatConversationStore:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        webchat_store, "WEBCHAT_CONVERSATIONS_DIR", tmp_path / "conversations"
+    )
+    monkeypatch.setattr(
+        webchat_store, "WEBCHAT_MIGRATION_MARKER_FILE", tmp_path / "migration.json"
+    )
+    monkeypatch.setattr(webchat_store, "HISTORY_DIR", tmp_path / "legacy-history")
+    store = webchat_store.WebChatConversationStore()
+    await store.ensure_ready()
+    await store.create_conversation(conversation_id="existing", title="original")
+    for role, text in (("user", "question"), ("bot", "answer")):
+        await store.append_message(
+            "existing",
+            role=role,
+            text_content=text,
+            display_name="system",
+            user_name="system",
+        )
+    if operation in {"title_generated", "title_failed"}:
+        assert await store.mark_title_pending("existing")
+    return store
+
+
+async def _mutate(
+    store: webchat_store.WebChatConversationStore, operation: str
+) -> object:
+    basis = webchat_store._title_basis_hash("question", "answer")
+    if operation == "create":
+        return await store.create_conversation(conversation_id="new", title="created")
+    if operation == "rename":
+        return await store.rename_conversation("existing", "renamed")
+    if operation == "clear":
+        return await store.clear_conversation("existing")
+    if operation == "append":
+        return await store.append_message(
+            "existing",
+            role="user",
+            text_content="new message",
+            display_name="system",
+            user_name="system",
+        )
+    if operation == "delete":
+        return await store.delete_conversation("existing")
+    if operation == "title_pending":
+        return await store.mark_title_pending("existing")
+    if operation == "title_generated":
+        return await store.apply_generated_title(
+            "existing", title="generated", basis_hash=basis
+        )
+    await store.mark_title_failed("existing", basis)
+    return None
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", _OPERATIONS)
+async def test_failed_conversation_commit_preserves_cache_disk_and_can_retry(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    operation: str,
+) -> None:
+    store = await _seed(tmp_path, monkeypatch, operation)
+    path = tmp_path / "conversations" / "existing.json"
+    before_disk = path.read_bytes()
+    before_cache = await store.get_conversation("existing")
+
+    async def wait_for_title() -> None:
+        await asyncio.Event().wait()
+
+    pending_title = asyncio.create_task(wait_for_title())
+    if operation == "delete":
+        store.register_title_task("existing", pending_title)
+    original_unlink = Path.unlink
+
+    def failed_write(file_path: Path | str, data: Any, use_lock: bool = True) -> None:
+        raise OSError("isolated disk unavailable")
+
+    def failed_unlink(target: Path, *args: Any, **kwargs: Any) -> None:
+        if target == path:
+            raise OSError("isolated disk unavailable")
+        original_unlink(target, *args, **kwargs)
+
+    try:
+        with pytest.MonkeyPatch.context() as failure:
+            if operation == "delete":
+                failure.setattr(Path, "unlink", failed_unlink)
+            else:
+                failure.setattr(io, "write_json_sync", failed_write)
+            with pytest.raises(OSError, match="isolated disk unavailable"):
+                await _mutate(store, operation)
+        assert path.read_bytes() == before_disk
+        assert await store.get_conversation("existing") == before_cache
+        assert await store.get_conversation("new") is None
+        if operation == "delete":
+            assert not pending_title.done()
+        await _mutate(store, operation)
+        target_id = "new" if operation == "create" else "existing"
+        cached = await store.get_conversation(target_id)
+        disk_path = tmp_path / "conversations" / f"{target_id}.json"
+        if operation == "delete":
+            assert cached is None and not disk_path.exists()
+            await asyncio.sleep(0)
+            assert pending_title.cancelled()
+        else:
+            assert cached == json.loads(disk_path.read_text(encoding="utf-8"))
+        restarted = webchat_store.WebChatConversationStore()
+        await restarted.ensure_ready()
+        assert await restarted.get_conversation(target_id) == cached
+        await restarted.stop()
+    finally:
+        pending_title.cancel()
+        await asyncio.gather(pending_title, return_exceptions=True)
+        await store.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", _OPERATIONS)
+async def test_cancelled_conversation_commit_finishes_before_unlocking(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    operation: str,
+) -> None:
+    store = await _seed(tmp_path, monkeypatch, operation)
+    target_id = "new" if operation == "create" else "existing"
+    target_path = tmp_path / "conversations" / f"{target_id}.json"
+    started = threading.Event()
+    release = threading.Event()
+    original_write = io.write_json_sync
+    original_unlink = Path.unlink
+
+    def wait_for_release() -> None:
+        started.set()
+        if not release.wait(timeout=5):
+            raise TimeoutError("test disk release timeout")
+
+    def controlled_write(
+        file_path: Path | str, data: Any, use_lock: bool = True
+    ) -> None:
+        if Path(file_path) == target_path:
+            wait_for_release()
+        original_write(file_path, data, use_lock)
+
+    def controlled_unlink(target: Path, *args: Any, **kwargs: Any) -> None:
+        if target == target_path:
+            wait_for_release()
+        original_unlink(target, *args, **kwargs)
+
+    monkeypatch.setattr(io, "write_json_sync", controlled_write)
+    if operation == "delete":
+        monkeypatch.setattr(Path, "unlink", controlled_unlink)
+    writing = asyncio.create_task(_mutate(store, operation))
+    reader: asyncio.Task[dict[str, Any] | None] | None = None
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        writing.cancel()
+        await asyncio.sleep(0)
+        writing.cancel()
+        reader = asyncio.create_task(store.get_conversation(target_id))
+        await asyncio.sleep(0)
+        assert not writing.done()
+        assert not reader.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await writing
+        cached = await asyncio.wait_for(reader, timeout=2)
+        if operation == "delete":
+            assert cached is None and not target_path.exists()
+        else:
+            assert cached is not None
+            assert cached == json.loads(target_path.read_text(encoding="utf-8"))
+    finally:
+        release.set()
+        await asyncio.gather(writing, return_exceptions=True)
+        if reader is not None:
+            await asyncio.gather(reader, return_exceptions=True)
+        await store.stop()

From d4b7a9d644bc0d783e2180649dfb18a707983835 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:36:02 +0800
Subject: [PATCH 093/121] fix(memory): publish only durable ordered commits

---
 docs/openapi.md                               |   8 +-
 docs/webui-guide.md                           |   2 +
 src/Undefined/api/routes/memory.py            |  15 +-
 src/Undefined/memory.py                       | 128 +++++-----
 .../skills/toolsets/memory/README.md          |   4 +
 tests/test_memory_persistence.py              | 235 ++++++++++++++++++
 6 files changed, 325 insertions(+), 67 deletions(-)
 create mode 100644 tests/test_memory_persistence.py

diff --git a/docs/openapi.md b/docs/openapi.md
index 93fc5130..1ccd2b80 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -187,7 +187,7 @@ HEAD /api/v1/onebot/files/{file_id}?token=...
 说明：这里的 HTTP 探针是“可达性/连通性探测”。只要拿到 HTTP 响应就会记为 `status=ok`，真实业务状态应结合 `http_status` 一起解读。
 当 Naga 集成未启用时，`naga_model` 会以 `status=skipped`、`reason=naga_integration_disabled` 出现在结果中。
 
-### 记忆（只读）
+### 长期记忆
 
 - `GET /api/v1/memory`
 - 查询参数：
@@ -195,7 +195,11 @@ HEAD /api/v1/onebot/files/{file_id}?token=...
   - `top_k`：返回条数上限（可选，正整数）
   - `time_from` / `time_to`：ISO 时间范围过滤（可选）
 
-说明：仅提供查看/查询，不提供写入接口，不改变现有记忆存储格式。
+- `POST /api/v1/memory`：用 `{"fact":"..."}` 创建记忆，成功返回 `201`；重复内容返回已提交记录的 UUID。
+- `PATCH /api/v1/memory/{uuid}`：用 `{"fact":"..."}` 更新记忆，成功返回 `200`。
+- `DELETE /api/v1/memory/{uuid}`：删除记忆，成功返回 `200`；不存在的 UUID 返回 `404`。
+
+增删改先串行原子落盘，再发布内存状态；持久化失败返回 `500` 并保留原记录，故障修复后可重试。等待提交锁时取消不会产生修改，实际写入开始后取消会先等待文件与内存提交完成。存储格式保持兼容。
 
 时间筛选接受带 `Z`、明确 UTC 偏移或无时区的 ISO 时间。无时区查询与旧记录中的无时区 `created_at` 均按 Bot 所在系统的本地时区解释（采用该日期的时区偏移），转换到 UTC 后比较；带偏移的时间按其实际时刻比较。上下界均包含在结果中；开始晚于结束时自动交换上下界。无效查询时间返回 `400`，无法解析创建时间的记录在启用时间筛选时跳过。响应中的 `created_at` 保留原始存储字符串。
 
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index 0821bcf7..cc2f3b04 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -114,6 +114,8 @@ AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：
 - 删除条目
 - 关键词搜索
 
+记忆修改在持久保存成功后才可见；写盘失败会显示失败并保留原记录，可以在故障解除后重试。并发修改按顺序提交，不会由旧快照覆盖后面的成功保存。
+
 ### 表情包库（Memes）
 
 管理 [全局表情包库](memes.md) 的 Web 界面：
diff --git a/src/Undefined/api/routes/memory.py b/src/Undefined/api/routes/memory.py
index 30c114ed..793a00c0 100644
--- a/src/Undefined/api/routes/memory.py
+++ b/src/Undefined/api/routes/memory.py
@@ -104,7 +104,10 @@ async def memory_create_handler(
     fact = str(body.get("fact", "") or "").strip()
     if not fact:
         return _json_error("fact must not be empty", status=400)
-    new_uuid = await memory_storage.add(fact)
+    try:
+        new_uuid = await memory_storage.add(fact)
+    except OSError:
+        return _json_error("Failed to persist memory", status=500)
     if new_uuid is None:
         return _json_error("Failed to create memory", status=500)
     existing = [m for m in memory_storage.get_all() if m.uuid == new_uuid]
@@ -135,7 +138,10 @@ async def memory_update_handler(
     fact = str(body.get("fact", "") or "").strip()
     if not fact:
         return _json_error("fact must not be empty", status=400)
-    ok = await memory_storage.update(target_uuid, fact)
+    try:
+        ok = await memory_storage.update(target_uuid, fact)
+    except OSError:
+        return _json_error("Failed to persist memory", status=500)
     if not ok:
         return _json_error(f"Memory {target_uuid} not found", status=404)
     return web.json_response({"uuid": target_uuid, "fact": fact, "updated": True})
@@ -150,7 +156,10 @@ async def memory_delete_handler(
     target_uuid = str(request.match_info.get("uuid", "")).strip()
     if not target_uuid:
         return _json_error("uuid is required", status=400)
-    ok = await memory_storage.delete(target_uuid)
+    try:
+        ok = await memory_storage.delete(target_uuid)
+    except OSError:
+        return _json_error("Failed to persist memory", status=500)
     if not ok:
         return _json_error(f"Memory {target_uuid} not found", status=404)
     return web.json_response({"uuid": target_uuid, "deleted": True})
diff --git a/src/Undefined/memory.py b/src/Undefined/memory.py
index fd1d401d..1fa936c3 100644
--- a/src/Undefined/memory.py
+++ b/src/Undefined/memory.py
@@ -1,9 +1,10 @@
 """AI 记忆存储管理模块"""
 
+import asyncio
 import json
 import logging
 import uuid
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass, asdict, replace
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
@@ -34,6 +35,8 @@ def __init__(self, max_memories: int = 500) -> None:
         """
         self.max_memories = max_memories
         self._memories: list[Memory] = []
+        self._save_lock = asyncio.Lock()
+        self._needs_rewrite = False
         self._load()
 
     def _load(self) -> None:
@@ -56,6 +59,7 @@ def _load(self) -> None:
                 loaded_memories.append(Memory(**item))
 
             self._memories = loaded_memories
+            self._needs_rewrite = needs_rewrite
             logger.info(
                 "[记忆] 加载完成: count=%s file=%s",
                 len(self._memories),
@@ -70,16 +74,18 @@ def _load(self) -> None:
             logger.warning("[记忆] 加载失败: %s", exc)
             self._memories = []
 
-    async def _save(self) -> None:
-        """保存记忆到文件"""
-        try:
-            from Undefined.utils import io
+    async def _save(self, memories: list[Memory]) -> None:
+        """持有写锁时提交独立快照，落盘后才更新可见状态。"""
+        from Undefined.utils import io
 
-            data = [asdict(m) for m in self._memories]
+        async def commit() -> None:
+            data = [asdict(memory) for memory in memories]
             await io.write_json(MEMORY_FILE_PATH, data, use_lock=True)
-            logger.debug("[记忆] 保存完成: count=%s", len(self._memories))
-        except Exception as exc:
-            logger.error("[记忆] 保存失败: %s", exc)
+            self._memories = memories
+            self._needs_rewrite = False
+            logger.debug("[记忆] 保存完成: count=%s", len(memories))
+
+        await io.run_cancellation_safe(commit())
 
     async def add(self, fact: str) -> Optional[str]:
         """添加一条记忆
@@ -94,38 +100,32 @@ async def add(self, fact: str) -> Optional[str]:
             logger.warning("[记忆] 尝试添加空记忆，已忽略")
             return None
 
-        # 检查是否已存在相同内容
-        for existing in self._memories:
-            if existing.fact == fact.strip():
-                logger.debug("[记忆] 记忆内容已存在，忽略: %s...", fact[:50])
-                return existing.uuid
-
-        memory = Memory(
-            uuid=str(uuid.uuid4()),
-            fact=fact.strip(),
-            created_at=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
-        )
-
-        # 添加到列表末尾
-        self._memories.append(memory)
-
-        # 如果超过上限，移除最旧的
-        if len(self._memories) > self.max_memories:
-            removed = self._memories.pop(0)
+        async with self._save_lock:
+            for existing in self._memories:
+                if existing.fact == fact.strip():
+                    if self._needs_rewrite:
+                        await self._save(self._memories.copy())
+                    logger.debug("[记忆] 记忆内容已存在，忽略: %s...", fact[:50])
+                    return existing.uuid
+
+            memory = Memory(
+                uuid=str(uuid.uuid4()),
+                fact=fact.strip(),
+                created_at=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            )
+            memories = [*self._memories, memory]
+            removed = memories.pop(0) if len(memories) > self.max_memories else None
+            await self._save(memories)
+            if removed is not None:
+                logger.info("[记忆] 超过上限，移除最旧记忆: %s...", removed.fact[:50])
             logger.info(
-                "[记忆] 超过上限，移除最旧记忆: %s...",
-                removed.fact[:50],
+                "[记忆] 已添加: uuid=%s size=%s/%s content=%s...",
+                memory.uuid,
+                len(self._memories),
+                self.max_memories,
+                fact[:50],
             )
-
-        await self._save()
-        logger.info(
-            "[记忆] 已添加: uuid=%s size=%s/%s content=%s...",
-            memory.uuid,
-            len(self._memories),
-            self.max_memories,
-            fact[:50],
-        )
-        return memory.uuid
+            return memory.uuid
 
     async def update(self, memory_uuid: str, fact: str) -> bool:
         """更新一条记忆
@@ -137,16 +137,18 @@ async def update(self, memory_uuid: str, fact: str) -> bool:
         返回:
             是否更新成功
         """
-        for i, m in enumerate(self._memories):
-            if m.uuid == memory_uuid:
-                self._memories[i].fact = fact.strip()
-                await self._save()
-                logger.info(
-                    "[记忆] 已更新: uuid=%s content=%s...",
-                    memory_uuid,
-                    fact[:50],
-                )
-                return True
+        async with self._save_lock:
+            for index, memory in enumerate(self._memories):
+                if memory.uuid == memory_uuid:
+                    memories = self._memories.copy()
+                    memories[index] = replace(memory, fact=fact.strip())
+                    await self._save(memories)
+                    logger.info(
+                        "[记忆] 已更新: uuid=%s content=%s...",
+                        memory_uuid,
+                        fact[:50],
+                    )
+                    return True
         logger.warning("[记忆] 未找到 UUID=%s 的记忆，更新失败", memory_uuid)
         return False
 
@@ -159,16 +161,18 @@ async def delete(self, memory_uuid: str) -> bool:
         返回:
             是否删除成功
         """
-        for i, m in enumerate(self._memories):
-            if m.uuid == memory_uuid:
-                removed = self._memories.pop(i)
-                await self._save()
-                logger.info(
-                    "[记忆] 已删除: uuid=%s content=%s...",
-                    memory_uuid,
-                    removed.fact[:50],
-                )
-                return True
+        async with self._save_lock:
+            for index, memory in enumerate(self._memories):
+                if memory.uuid == memory_uuid:
+                    memories = self._memories.copy()
+                    removed = memories.pop(index)
+                    await self._save(memories)
+                    logger.info(
+                        "[记忆] 已删除: uuid=%s content=%s...",
+                        memory_uuid,
+                        removed.fact[:50],
+                    )
+                    return True
         logger.warning("[记忆] 未找到 UUID=%s 的记忆，删除失败", memory_uuid)
         return False
 
@@ -178,12 +182,12 @@ def get_all(self) -> list[Memory]:
         返回:
             记忆列表（按时间顺序，最早的在前）
         """
-        return self._memories.copy()
+        return [replace(memory) for memory in self._memories]
 
     async def clear(self) -> None:
         """清空所有记忆"""
-        self._memories = []
-        await self._save()
+        async with self._save_lock:
+            await self._save([])
         logger.info("[记忆] 已清空所有记忆")
 
     def count(self) -> int:
diff --git a/src/Undefined/skills/toolsets/memory/README.md b/src/Undefined/skills/toolsets/memory/README.md
index 141019cb..018b1cf6 100644
--- a/src/Undefined/skills/toolsets/memory/README.md
+++ b/src/Undefined/skills/toolsets/memory/README.md
@@ -6,5 +6,9 @@
 - 添加/删除/更新记忆
 - 列出记忆条目
 
+同一运行时中的增删改与清空共用串行提交锁，先原子落盘再发布内存状态，重复内容只从已提交记录中去重。磁盘写入失败会向调用方报告失败，原有记录和容量淘汰状态保持不变；故障修复后可以重试。Runtime API 的持久化失败返回 HTTP 500，不会返回“已保存”。
+
+等待提交锁时取消会中止尚未开始的变更；实际写入开始后，取消会等待该次写入和内存状态提交完成，再释放锁并传播。列出记忆返回独立记录副本，不能绕过持久化流程修改存储。
+
 目录结构：
 - 每个子目录对应一个工具（`config.json` + `handler.py`）
diff --git a/tests/test_memory_persistence.py b/tests/test_memory_persistence.py
new file mode 100644
index 00000000..cb490f2a
--- /dev/null
+++ b/tests/test_memory_persistence.py
@@ -0,0 +1,235 @@
+"""Memory mutations publish only ordered, durable commits."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from Undefined.api.routes.memory import (
+    memory_create_handler,
+    memory_delete_handler,
+    memory_update_handler,
+)
+from Undefined.memory import MemoryStorage
+from Undefined.skills.toolsets.memory.add.handler import execute as add_memory_tool
+from Undefined.utils import io
+
+
+@pytest.fixture
+def memory_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    path = tmp_path / "memory.json"
+    monkeypatch.setattr("Undefined.memory.MEMORY_FILE_PATH", path)
+    return path
+
+
+def _facts(storage: MemoryStorage) -> list[str]:
+    return [memory.fact for memory in storage.get_all()]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_when", ["none", "writing", "waiting"])
+async def test_concurrent_memory_commits_remain_ordered_across_cancellation(
+    memory_path: Path, monkeypatch: pytest.MonkeyPatch, cancel_when: str
+) -> None:
+    storage = MemoryStorage()
+    started = asyncio.Event()
+    release = asyncio.Event()
+    writes: list[list[dict[str, str]]] = []
+    real_write = io.write_json
+
+    async def gated_write(path: Path | str, data: Any, use_lock: bool = True) -> None:
+        writes.append(data)
+        if len(writes) == 1:
+            started.set()
+            await release.wait()
+        await real_write(path, data, use_lock)
+
+    monkeypatch.setattr(io, "write_json", gated_write)
+    first = asyncio.create_task(storage.add("first"))
+    second: asyncio.Task[str | None] | None = None
+    try:
+        await asyncio.wait_for(started.wait(), 1)
+        assert _facts(storage) == []
+        if cancel_when == "writing":
+            first.cancel()
+            await asyncio.sleep(0)
+            first.cancel()
+        second = asyncio.create_task(storage.add("second"))
+        await asyncio.sleep(0)
+        assert len(writes) == 1
+        assert not first.done()
+        if cancel_when == "waiting":
+            second.cancel()
+        release.set()
+        results = await asyncio.gather(first, second, return_exceptions=True)
+        assert isinstance(results[0], asyncio.CancelledError) == (
+            cancel_when == "writing"
+        )
+        assert isinstance(results[1], asyncio.CancelledError) == (
+            cancel_when == "waiting"
+        )
+        expected = ["first"] if cancel_when == "waiting" else ["first", "second"]
+        assert _facts(storage) == _facts(MemoryStorage()) == expected
+        assert [
+            item["fact"] for item in json.loads(memory_path.read_text("utf-8"))
+        ] == expected
+    finally:
+        release.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", ["add", "update", "delete", "clear"])
+async def test_failed_memory_mutation_preserves_committed_state(
+    memory_path: Path, monkeypatch: pytest.MonkeyPatch, operation: str
+) -> None:
+    storage = MemoryStorage(max_memories=1)
+    memory_uuid = await storage.add("original")
+    assert memory_uuid is not None
+    before = memory_path.read_bytes()
+    failed_write = AsyncMock(side_effect=OSError("isolated ENOSPC"))
+    monkeypatch.setattr(io, "write_json", failed_write)
+    with pytest.raises(OSError, match="ENOSPC"):
+        if operation == "add":
+            await storage.add("new")
+        elif operation == "update":
+            await storage.update(memory_uuid, "new")
+        elif operation == "delete":
+            await storage.delete(memory_uuid)
+        else:
+            await storage.clear()
+    assert _facts(storage) == ["original"]
+    assert _facts(MemoryStorage()) == ["original"]
+    assert memory_path.read_bytes() == before
+
+
+@pytest.mark.asyncio
+async def test_memory_failure_is_not_deduplicated_on_healthy_retry(
+    memory_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    storage = MemoryStorage()
+    real_write = io.write_json
+    monkeypatch.setattr(
+        io, "write_json", AsyncMock(side_effect=OSError("isolated ENOSPC"))
+    )
+    with pytest.raises(OSError):
+        await add_memory_tool({"fact": "retry"}, {"memory_storage": storage})
+    assert not memory_path.exists()
+    assert storage.count() == 0
+    monkeypatch.setattr(io, "write_json", real_write)
+    result = await add_memory_tool({"fact": "retry"}, {"memory_storage": storage})
+    assert result.startswith("已保存记忆:")
+    assert _facts(MemoryStorage()) == ["retry"]
+
+
+@pytest.mark.asyncio
+async def test_memory_duplicate_waits_for_initial_commit(
+    memory_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    storage = MemoryStorage()
+    started = asyncio.Event()
+    release = asyncio.Event()
+    real_write = io.write_json
+
+    async def gated_write(path: Path | str, data: Any, use_lock: bool = True) -> None:
+        started.set()
+        await release.wait()
+        await real_write(path, data, use_lock)
+
+    monkeypatch.setattr(io, "write_json", gated_write)
+    first = asyncio.create_task(storage.add("same"))
+    second: asyncio.Task[str | None] | None = None
+    try:
+        await asyncio.wait_for(started.wait(), 1)
+        second = asyncio.create_task(storage.add("same"))
+        await asyncio.sleep(0)
+        assert not second.done()
+        assert not memory_path.exists()
+        release.set()
+        first_uuid, second_uuid = await asyncio.gather(first, second)
+        assert first_uuid == second_uuid
+        assert _facts(MemoryStorage()) == ["same"]
+    finally:
+        release.set()
+        await asyncio.gather(
+            first, *([second] if second is not None else []), return_exceptions=True
+        )
+
+
+@pytest.mark.asyncio
+async def test_memory_legacy_dedup_persists_generated_uuid(memory_path: Path) -> None:
+    memory_path.write_text(
+        json.dumps([{"fact": "legacy", "created_at": "2026-01-01 00:00:00"}]), "utf-8"
+    )
+    storage = MemoryStorage()
+    generated_uuid = await storage.add("legacy")
+    assert MemoryStorage().get_all()[0].uuid == generated_uuid
+
+
+def test_get_all_cannot_mutate_committed_memory(
+    memory_path: Path,
+) -> None:
+    memory_path.write_text(
+        json.dumps(
+            [{"uuid": "u1", "fact": "original", "created_at": "2026-01-01 00:00:00"}]
+        ),
+        "utf-8",
+    )
+    storage = MemoryStorage()
+    storage.get_all()[0].fact = "uncommitted"
+    assert _facts(storage) == ["original"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", ["create", "update", "delete"])
+async def test_memory_http_returns_failure_without_publishing_uncommitted_state(
+    memory_path: Path, monkeypatch: pytest.MonkeyPatch, operation: str
+) -> None:
+    storage = MemoryStorage()
+    memory_uuid = await storage.add("original")
+    context: Any = SimpleNamespace(ai=SimpleNamespace(memory_storage=storage))
+
+    async def create(request: web.Request) -> web.Response:
+        return await memory_create_handler(context, request)
+
+    async def update(request: web.Request) -> web.Response:
+        return await memory_update_handler(context, request)
+
+    async def delete(request: web.Request) -> web.Response:
+        return await memory_delete_handler(context, request)
+
+    app = web.Application()
+    app.router.add_post("/memory", create)
+    app.router.add_patch("/memory/{uuid}", update)
+    app.router.add_delete("/memory/{uuid}", delete)
+    real_write = io.write_json
+    monkeypatch.setattr(
+        io, "write_json", AsyncMock(side_effect=OSError("isolated ENOSPC"))
+    )
+    async with TestClient(TestServer(app)) as client:
+        if operation == "create":
+            response = await client.post("/memory", json={"fact": "new"})
+        elif operation == "update":
+            response = await client.patch(
+                f"/memory/{memory_uuid}", json={"fact": "new"}
+            )
+        else:
+            response = await client.delete(f"/memory/{memory_uuid}")
+        assert response.status == 500
+        assert await response.json() == {"error": "Failed to persist memory"}
+        assert _facts(storage) == _facts(MemoryStorage()) == ["original"]
+        monkeypatch.setattr(io, "write_json", real_write)
+        if operation == "create":
+            retry = await client.post("/memory", json={"fact": "new"})
+            assert retry.status == 201
+            assert _facts(MemoryStorage()) == ["original", "new"]

From 96da594c6b1c905540502fc9339787495e53f86b Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:38:05 +0800
Subject: [PATCH 094/121] fix(attachments): decode local file URIs consistently

---
 docs/configuration.md                   |   2 +
 src/Undefined/attachments/segments.py   |  13 +--
 src/Undefined/onebot/file_references.py |   9 +-
 src/Undefined/utils/paths.py            |  12 +++
 src/Undefined/utils/sender.py           |  10 +--
 tests/test_attachment_file_uri.py       | 114 ++++++++++++++++++++++++
 tests/test_sender.py                    |   2 +-
 7 files changed, 141 insertions(+), 21 deletions(-)
 create mode 100644 tests/test_attachment_file_uri.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 7b0d9073..9b9de9da 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -711,6 +711,8 @@ document_instruction = "passage: "
 
 仅保留 URL 引用的远程图片按登记的原始 URL 发送，查询参数中的逗号、方括号和 `&` 不会被截断。内部 CQ 参数会转义，并在转换为 OneBot 消息段时仅解码一次；URL 中原本的 `&#44;`、`&amp;` 等字面实体保持原样。这不改变远程下载上限或目标校验策略。
 
+本地 `file://` URI 在附件登记、显示名称和发送层共用路径解析规则，只解码一次，支持中文、空格、`localhost` 与 UNC 路径；普通文件路径中的 `%` 保持字面含义。附件记录仍保存原始来源引用。
+
 远程附件下载默认只允许公网 HTTP(S) 目标，拒绝 URL 内的凭据、回环、私网、链路本地、组播等非公网目标。域名的全部解析结果都必须符合策略；实际请求固定到已校验的 IP，并保留原始 Host、TLS SNI 和证书校验，避免校验后再次解析造成 DNS 重绑定绕过。每次重定向和后续回源都重新校验目标；DNS、连接、跳转与下载共用 120 秒总时限，最多跟随 20 次跳转。策略拒绝或网络错误不会降级登记成新的 URL 引用。
 
 需要从 NapCat 等内网媒体服务下载时，只将确认可信的精确 origin 加入 `remote_download_allow_private_origins`；该配置允许从对应服务的任意路径下载，不会放行其他端口、协议或跳转目标。修改配置只影响后续下载，不删除现有缓存。仅登记 URL 引用时不会发起 DNS 或 HTTP 请求；真正回源时仍须通过当时的目标策略。`use_proxy` 保持生效，代理会收到已校验的目标 IP，代理地址本身由部署者信任；代理模式也需要 Bot 本机能够解析目标域名。
diff --git a/src/Undefined/attachments/segments.py b/src/Undefined/attachments/segments.py
index fba9c75f..f036d7ac 100644
--- a/src/Undefined/attachments/segments.py
+++ b/src/Undefined/attachments/segments.py
@@ -21,7 +21,7 @@
     snapshot_forward_tree,
 )
 from Undefined.attachments.models import RegisteredMessageAttachments
-from Undefined.utils.paths import WEBUI_FILE_CACHE_DIR
+from Undefined.utils.paths import WEBUI_FILE_CACHE_DIR, file_uri_path_text
 from Undefined.utils.xml import escape_xml_attr
 
 if TYPE_CHECKING:
@@ -236,8 +236,11 @@ def display_name_from_source(raw_source: str, fallback: str) -> str:
     if not raw_source:
         return fallback
     if raw_source.startswith("file://"):
-        raw_source = raw_source[7:]
-    name = Path(unquote(urlsplit(raw_source).path)).name
+        name = Path(file_uri_path_text(raw_source)).name
+    elif is_localish_path(raw_source):
+        name = Path(raw_source).name
+    else:
+        name = Path(unquote(urlsplit(raw_source).path)).name
     return name or fallback
 
 
@@ -519,7 +522,7 @@ async def _collect_from_segments(
                             ref = record.prompt_ref()
                         elif is_localish_path(resolved_source):
                             local_path = (
-                                resolved_source[7:]
+                                file_uri_path_text(resolved_source)
                                 if resolved_source.startswith("file://")
                                 else resolved_source
                             )
@@ -545,7 +548,7 @@ async def _collect_from_segments(
                         local_file_path = _resolve_webui_file_id(file_id)
                     elif is_localish_path(raw_source):
                         local_file_path = Path(
-                            raw_source[7:]
+                            file_uri_path_text(raw_source)
                             if raw_source.startswith("file://")
                             else raw_source
                         )
diff --git a/src/Undefined/onebot/file_references.py b/src/Undefined/onebot/file_references.py
index fc2cc729..69ab7cf5 100644
--- a/src/Undefined/onebot/file_references.py
+++ b/src/Undefined/onebot/file_references.py
@@ -3,12 +3,11 @@
 from copy import deepcopy
 from pathlib import Path
 from typing import Any, Callable
-from urllib.parse import urlsplit
-from urllib.request import url2pathname
 
 from Undefined.attachments.segments import is_localish_path
 from Undefined.attachments.render import _escape_cq_component
 from Undefined.utils.common import CQ_PATTERN
+from Undefined.utils.paths import file_uri_path_text
 
 _MEDIA_FIELDS = {
     "image": ("file",),
@@ -22,11 +21,7 @@ def local_file_path(value: str) -> Path | None:
     if not is_localish_path(value):
         return None
     if value.startswith("file://"):
-        uri = urlsplit(value)
-        path = url2pathname(uri.path)
-        if uri.netloc and uri.netloc != "localhost":
-            path = f"//{uri.netloc}{path}"
-        return Path(path)
+        return Path(file_uri_path_text(value))
     return Path(value)
 
 
diff --git a/src/Undefined/utils/paths.py b/src/Undefined/utils/paths.py
index 21feeb3c..2630cc45 100644
--- a/src/Undefined/utils/paths.py
+++ b/src/Undefined/utils/paths.py
@@ -1,6 +1,8 @@
 """Common runtime paths."""
 
 from pathlib import Path
+from urllib.parse import urlsplit
+from urllib.request import url2pathname
 
 PACKAGE_ROOT: Path = Path(__file__).resolve().parent.parent
 
@@ -22,6 +24,16 @@
 WEBCHAT_MIGRATION_MARKER_FILE: Path = WEBCHAT_DIR / "legacy_private_42_migrated.json"
 
 
+def file_uri_path_text(source: str) -> str:
+    """解码本地 file URI 的路径一次，保留 localhost 与 UNC authority 语义。"""
+    parsed = urlsplit(source)
+    netloc = parsed.netloc.strip()
+    uri_path = parsed.path
+    if netloc and netloc.lower() != "localhost":
+        uri_path = f"//{netloc}{uri_path}"
+    return url2pathname(uri_path)
+
+
 def ensure_dir(path: Path) -> Path:
     """Ensure a directory exists and return it."""
     path.mkdir(parents=True, exist_ok=True)
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index 5f19704d..5301d257 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -5,8 +5,6 @@
 from pathlib import Path
 import time
 from typing import Any, Literal
-from urllib.parse import urlsplit
-from urllib.request import url2pathname
 
 from weixin_ilink_client import (
     MediaKind,
@@ -40,6 +38,7 @@
     format_markdown_reply,
 )
 from Undefined.utils.message_turn import mark_message_sent_this_turn
+from Undefined.utils.paths import file_uri_path_text
 from Undefined.weixin.audio import PreparedWeixinVoice
 from Undefined.weixin.transport import (
     is_definitive_weixin_delivery_rejection as is_definitive_weixin_delivery_rejection,
@@ -163,12 +162,7 @@ def _iter_segments_deep(value: object) -> list[dict[str, Any]]:
 
 
 def _file_uri_path_text(raw_source: str) -> str:
-    parsed = urlsplit(raw_source)
-    netloc = parsed.netloc.strip()
-    uri_path = parsed.path
-    if netloc and netloc.lower() != "localhost":
-        uri_path = f"//{netloc}{uri_path}"
-    return url2pathname(uri_path)
+    return file_uri_path_text(raw_source)
 
 
 async def _local_path_from_segment_source(source: Any) -> Path | None:
diff --git a/tests/test_attachment_file_uri.py b/tests/test_attachment_file_uri.py
new file mode 100644
index 00000000..3f6b1a34
--- /dev/null
+++ b/tests/test_attachment_file_uri.py
@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import nturl2path
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+
+from Undefined.api.routes.chat import _normalize_webchat_output
+from Undefined.attachments.registry import AttachmentRegistry
+from Undefined.attachments.segments import register_message_attachments
+from Undefined.onebot.file_references import local_file_path
+from Undefined.skills.commands.help import handler as help_handler
+from Undefined.utils.paths import file_uri_path_text
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "filename", ["ascii.png", "中文 image.png", "percent%20literal.png"]
+)
+@pytest.mark.parametrize("kind", ["image", "file"])
+@pytest.mark.parametrize("uri", [False, True])
+async def test_local_attachment_registration_decodes_only_file_uri(
+    tmp_path: Path,
+    filename: str,
+    kind: str,
+    uri: bool,
+) -> None:
+    source = tmp_path / filename
+    source.write_bytes(b"isolated image")
+    registry = AttachmentRegistry(
+        registry_path=tmp_path / "registry.json", cache_dir=tmp_path / "cache"
+    )
+    representation = source.as_uri() if uri else str(source)
+    result = await register_message_attachments(
+        registry=registry,
+        segments=[{"type": kind, "data": {"file": representation}}],
+        scope_key="private:12345",
+    )
+    assert len(result.attachments) == 1
+    record = registry.resolve(result.attachments[0]["uid"], "private:12345")
+    assert record is not None
+    assert record.display_name == filename
+    assert record.source_ref == representation
+    assert record.local_path is not None
+    assert Path(record.local_path).read_bytes() == source.read_bytes()
+
+
+@pytest.mark.asyncio
+async def test_help_rendered_uri_becomes_runtime_preview_attachment(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    render_dir = tmp_path / "中文工作区 render%cache"
+    registry = AttachmentRegistry(
+        registry_path=tmp_path / "registry.json", cache_dir=tmp_path / "cache"
+    )
+    outputs: list[tuple[str, list[dict[str, str]]]] = []
+
+    async def render(html: str, output: str, **kwargs: Any) -> str:
+        Path(output).write_bytes(b"isolated PNG")
+        return output
+
+    async def capture(user_id: int, message: str) -> None:
+        outputs.append(
+            await _normalize_webchat_output(
+                message,
+                registry=registry,
+                scope_key="private:12345",
+                resolve_image_url=None,
+                get_forward_messages=None,
+            )
+        )
+
+    context = SimpleNamespace(
+        scope="private",
+        user_id=12345,
+        sender_id=12345,
+        group_id=0,
+        sender=SimpleNamespace(send_private_message=capture),
+    )
+    monkeypatch.setattr("Undefined.utils.paths.RENDER_CACHE_DIR", render_dir)
+    monkeypatch.setattr("Undefined.render.render_html_to_image", render)
+    await help_handler._send_rendered_html(cast(Any, context), "<h1>help</h1>", "help")
+    assert len(outputs) == 1
+    content, attachments = outputs[0]
+    assert len(attachments) == 1
+    assert content == f'<attachment uid="{attachments[0]["uid"]}"/>'
+
+
+@pytest.mark.parametrize(
+    ("uri", "expected"),
+    [
+        ("file:///tmp/percent%2520.txt", "/tmp/percent%20.txt"),
+        ("file://LOCALHOST/tmp/report%20file.txt", "/tmp/report file.txt"),
+        ("file://server/share/report%20file.txt", "//server/share/report file.txt"),
+    ],
+)
+def test_file_uri_authority_and_single_decoding(uri: str, expected: str) -> None:
+    assert file_uri_path_text(uri) == expected
+    assert local_file_path(uri) == Path(expected)
+
+
+def test_file_uri_preserves_windows_drive_and_unc(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr("Undefined.utils.paths.url2pathname", nturl2path.url2pathname)
+    assert file_uri_path_text("file:///C:/Users/Test%20User/report.txt") == (
+        r"C:\Users\Test User\report.txt"
+    )
+    assert file_uri_path_text("file://server/share/report%20file.txt") == (
+        r"\\server\share\report file.txt"
+    )
diff --git a/tests/test_sender.py b/tests/test_sender.py
index 95544178..de748328 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -84,7 +84,7 @@ def test_file_uri_path_text_supports_windows_drive_and_unc(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     monkeypatch.setattr(
-        "Undefined.utils.sender.url2pathname",
+        "Undefined.utils.paths.url2pathname",
         nturl2path.url2pathname,
     )
 

From d6572ed1242260ea9abc668178beaa05f81d93d1 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:39:05 +0800
Subject: [PATCH 095/121] fix(deploy): recreate lxmusic when generated config
 changes

---
 docs/docker-deploy.md                         |  2 +
 src/Undefined/deploy/generate.py              | 21 +++++++---
 .../deploy/templates/compose.lxmusic2api.yaml |  1 +
 tests/test_deploy_generate.py                 | 31 ++++++++++++++
 tests/test_deploy_runner.py                   | 40 +++++++++++++++++++
 5 files changed, 90 insertions(+), 5 deletions(-)

diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md
index e88e6b1c..dd16cf82 100644
--- a/docs/docker-deploy.md
+++ b/docs/docker-deploy.md
@@ -227,6 +227,8 @@ uv run deploy up --port bot_webui=18787 --port napcat_webui=16099
 
 重新运行向导可以调整模式和可选服务。重复部署会重新生成 Compose 与服务配置，并复用已有有效凭据；对生成文件的手工修改可能被覆盖。修改过 WebUI 密码时，以 `config.toml` 中的当前值为准。
 
+音乐服务生成配置的内容摘要会写入该服务的 Compose label。配置或密钥变化后，`up` 会仅重建需要更新的音乐容器，使单文件挂载读到原子替换后的新配置；内容相同时摘要保持稳定，不会因此重建其他服务。
+
 `container` 模式的 Python 解释器使用 `deploy/data/cache/python_interpreter/` 中独立的临时工作目录。部署工具通过容器环境变量传入这份共享目录在 Bot 内和宿主机上的不同路径，使宿主 Docker 能读取脚本、依赖清单和生成的文件；不会共享整个宿主 `/tmp`。`host` 模式继续使用系统临时目录。手工部署容器时的设置方法见 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)。
 
 ### 更新版本
diff --git a/src/Undefined/deploy/generate.py b/src/Undefined/deploy/generate.py
index bb09d808..a0121572 100644
--- a/src/Undefined/deploy/generate.py
+++ b/src/Undefined/deploy/generate.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import secrets
 import string
@@ -29,6 +30,7 @@
 SEARXNG_SERVICE_NAME: Final[str] = "searxng"
 FIRECRAWL_SERVICE_NAME: Final[str] = "firecrawl-api"
 LXMUSIC2API_SERVICE_NAME: Final[str] = "lxmusic2api"
+SERVICE_CONFIG_DIGEST_LABEL: Final[str] = "io.undefined.config-sha256"
 #: 本体容器内的工作目录（与 compose.bot.yaml 的 working_dir 一致）。
 CONTAINER_REPO_PATH: Final[str] = "/data/Undefined"
 
@@ -637,8 +639,21 @@ def _mount_napcat_ws_template(ctx: GenerateContext, fragments: dict[str, Any]) -
 def build(ctx: GenerateContext) -> GeneratedConfiguration:
     """组装一次 ``up`` 的全部生成物。"""
     env = build_env(ctx)
+    lxmusic2api_config = (
+        render_lxmusic2api_config(env)
+        if catalog.LXMUSIC2API.key in ctx.services
+        else None
+    )
     fragments = load_compose_fragments(compose_fragment_names(ctx))
     apply_context_overrides(ctx, fragments)
+    if lxmusic2api_config is not None:
+        # 单文件 bind mount 持有旧 inode；配置变化必须参与该服务的重建判断。
+        labels = fragments["services"][LXMUSIC2API_SERVICE_NAME].setdefault(
+            "labels", {}
+        )
+        labels[SERVICE_CONFIG_DIGEST_LABEL] = hashlib.sha256(
+            lxmusic2api_config.encode("utf-8")
+        ).hexdigest()
     compose_text = render_compose(fragments, project_name=catalog.COMPOSE_PROJECT_NAME)
     patch_plan = build_patch_plan(ctx, env)
 
@@ -654,11 +669,7 @@ def build(ctx: GenerateContext) -> GeneratedConfiguration:
         firecrawl_env=(
             render_firecrawl_env(env) if catalog.FIRECRAWL.key in ctx.services else None
         ),
-        lxmusic2api_config=(
-            render_lxmusic2api_config(env)
-            if catalog.LXMUSIC2API.key in ctx.services
-            else None
-        ),
+        lxmusic2api_config=lxmusic2api_config,
         napcat_ws_config=render_napcat_ws_config(ctx, env),
         napcat_ws_token=env["UNDEFINED_DEPLOY_NAPCAT_WS_TOKEN"],
         websocket_url=str(patch_plan.desired["onebot.ws_url"]),
diff --git a/src/Undefined/deploy/templates/compose.lxmusic2api.yaml b/src/Undefined/deploy/templates/compose.lxmusic2api.yaml
index 8340b7ca..071ffed3 100644
--- a/src/Undefined/deploy/templates/compose.lxmusic2api.yaml
+++ b/src/Undefined/deploy/templates/compose.lxmusic2api.yaml
@@ -27,6 +27,7 @@ services:
     cap_drop:
       - ALL
     volumes:
+      # 生成层将配置内容摘要写入本服务 label；原子替换后通过 compose up 定向重建。
       - ./lxmusic2api/config.toml:/app/config.toml:ro
       - ./lxmusic2api/.private:/app/.private:ro
       - ./lxmusic2api/data:/app/data
diff --git a/tests/test_deploy_generate.py b/tests/test_deploy_generate.py
index 32134ca9..c20b6297 100644
--- a/tests/test_deploy_generate.py
+++ b/tests/test_deploy_generate.py
@@ -709,6 +709,37 @@ def test_lxmusic2api_config_has_mandatory_fields(tmp_path: Path) -> None:
 # --------------------------------------------------------------------------- #
 
 
+@pytest.mark.parametrize("mode", [catalog.MODE_CONTAINER, catalog.MODE_HOST])
+def test_lxmusic_config_digest_recreates_only_changed_service(
+    tmp_path: Path, mode: str
+) -> None:
+    services = ("lxmusic2api", "searxng")
+    first = generate.build(_ctx(tmp_path, mode=mode, services=services))
+    repeated = generate.build(
+        _ctx(tmp_path, mode=mode, services=services, previous_env=first.env)
+    )
+    assert _compose_services(repeated.compose_text) == _compose_services(
+        first.compose_text
+    )
+    previous = dict(first.env)
+    previous["UNDEFINED_DEPLOY_LXMUSIC2API_KEY"] = "isolated-rotated-key"
+    rotated = generate.build(
+        _ctx(tmp_path, mode=mode, services=services, previous_env=previous)
+    )
+    first_services = _compose_services(first.compose_text)
+    rotated_services = _compose_services(rotated.compose_text)
+    lx_name = generate.LXMUSIC2API_SERVICE_NAME
+    label = generate.SERVICE_CONFIG_DIGEST_LABEL
+    assert (
+        rotated_services[lx_name]["labels"][label]
+        != first_services[lx_name]["labels"][label]
+    )
+    assert {
+        key: value for key, value in rotated_services.items() if key != lx_name
+    } == {key: value for key, value in first_services.items() if key != lx_name}
+    assert "isolated-rotated-key" not in rotated.compose_text
+
+
 def test_container_mode_uses_compose_service_names(tmp_path: Path) -> None:
     urls = generate.compose_service_urls(_ctx(tmp_path))
     assert urls["searxng"] == "http://searxng:8080"
diff --git a/tests/test_deploy_runner.py b/tests/test_deploy_runner.py
index bcc574a7..c22c0cda 100644
--- a/tests/test_deploy_runner.py
+++ b/tests/test_deploy_runner.py
@@ -953,6 +953,46 @@ def test_empty_with_clears_previous_service_selection(
     assert state.services == (), "空元组应清空上次选择，而不是沿用"
 
 
+def test_repeat_up_with_missing_lxmusic_key_updates_service_digest(
+    fake_repo: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _stub_docker(monkeypatch)
+    options = _yes_options(services=("lxmusic2api",), dry_run=False)
+    assert runner.run_up(options) == 0
+    layout = DeployLayout.under(fake_repo)
+    initial_services = yaml.safe_load(layout.compose_file.read_text(encoding="utf-8"))[
+        "services"
+    ]
+    repeat_options = _yes_options(services=None, dry_run=False)
+    assert runner.run_up(repeat_options) == 0
+    assert (
+        yaml.safe_load(layout.compose_file.read_text(encoding="utf-8"))["services"]
+        == initial_services
+    )
+    previous = runner.load_previous_env(layout)
+    old_key = previous.pop("UNDEFINED_DEPLOY_LXMUSIC2API_KEY")
+    layout.env_file.write_text(generate.render_env(previous), encoding="utf-8")
+    assert runner.run_up(repeat_options) == 0
+    services = yaml.safe_load(layout.compose_file.read_text(encoding="utf-8"))[
+        "services"
+    ]
+    lx_name = generate.LXMUSIC2API_SERVICE_NAME
+    label = generate.SERVICE_CONFIG_DIGEST_LABEL
+    assert (
+        services[lx_name]["labels"][label] != initial_services[lx_name]["labels"][label]
+    )
+    assert {key: value for key, value in services.items() if key != lx_name} == {
+        key: value for key, value in initial_services.items() if key != lx_name
+    }
+    host = tomllib.loads(
+        (layout.lxmusic2api_dir / "config.toml").read_text(encoding="utf-8")
+    )
+    bot = tomllib.loads((fake_repo / "config.toml").read_text(encoding="utf-8"))
+    assert host["auth"]["api_key"] != old_key
+    assert bot["lxmusic2api"]["api_key"] == host["auth"]["api_key"]
+
+
 def test_lxmusic2api_config_is_owner_only(tmp_path: Path) -> None:
     """桥接服务的 config.toml 含 api_key，应收紧到属主可读。"""
     import stat

From 4e5c440a8a8fb26595a7e6d9e059a6c6b9ae3204 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:39:19 +0800
Subject: [PATCH 096/121] fix(queue): retain started LLM calls during group
 trimming

---
 docs/configuration.md                   |   2 +
 docs/development.md                     |   2 +
 src/Undefined/services/queue_manager.py |  25 ++--
 tests/test_group_llm_queue_trim.py      | 163 ++++++++++++++++++++++++
 tests/test_queue_manager.py             |  38 ++++++
 5 files changed, 220 insertions(+), 10 deletions(-)
 create mode 100644 tests/test_group_llm_queue_trim.py

diff --git a/docs/configuration.md b/docs/configuration.md
index 9b9de9da..c7ba9146 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -276,6 +276,8 @@ Stream 本地文件投递在同一 Bot 内串行，纯文本不等待上传锁
 | `prompt_cache_enabled` | OpenAI 模式下是否自动生成稳定的 `prompt_cache_key`；Anthropic 模式不发送该字段；默认 `true` |
 | `request_params` | 额外请求体参数（透传给模型 API，保留字段会忽略） |
 
+普通群聊队列过长时，仅裁剪尚未发车的外围请求；已经启动的 AI 调用所等待的 LLM 子请求及重试保留原相对顺序，避免调用方因裁剪而继续等待超时。
+
 请求模式说明：
 - `api_mode="openai.chat_completions"`：走 `AsyncOpenAI.chat.completions.create(...)`
   - `max_tokens > 0` 时发送 `max_tokens`；为 `0` 或负数时省略
diff --git a/docs/development.md b/docs/development.md
index aecceb9d..2670d0d8 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -66,6 +66,8 @@ src/Undefined/
 
 Runtime API 和 WebUI 向 aiohttp `Application` 存储上下文等共享对象时，使用模块级 `web.AppKey` 常量并在所有读写处复用，保持类型安全并避免 `NotAppKeyWarning`。Runtime API 的应用构造回归测试会将该警告视为错误。
 
+普通群聊 lane 超过 10 项时，只对尚未发车的外围请求保留最新 2 项；已启动 AI 调用的 `queued_llm_call` 子请求及其重试始终保留原相对顺序。调用方取消和超时仍通过共享取消状态阻止后续模型执行，队列裁剪不能丢弃内部等待者。
+
 ### CHANGELOG 维护约定
 
 - 仓库根目录的 `CHANGELOG.md` 是正式版本历史的唯一事实来源。
diff --git a/src/Undefined/services/queue_manager.py b/src/Undefined/services/queue_manager.py
index d118c4e1..d2164871 100644
--- a/src/Undefined/services/queue_manager.py
+++ b/src/Undefined/services/queue_manager.py
@@ -117,21 +117,26 @@ def total_retry_count(self) -> int:
         return sum(queue.retry_count() for queue in self.lane_queues().values())
 
     def trim_normal_queue(self) -> None:
-        """如果群聊普通队列超过10个，仅保留最新的2个"""
+        """普通队列过长时只裁剪外围请求，保留所有 LLM 子请求和重试。"""
         queue_size = self.group_normal_queue.qsize()
         if queue_size > 10:
+            requests = self.group_normal_queue.drain()
+            outer_indices = [
+                index
+                for index, request in enumerate(requests)
+                if request.get("type") not in {"queued_llm_call", "background_llm_call"}
+            ]
+            discarded_indices = set(outer_indices[:-2])
+            for index, request in enumerate(requests):
+                if index not in discarded_indices:
+                    self.group_normal_queue.put_nowait(request)
+            if not discarded_indices:
+                return
             logger.warning(
-                "[队列修剪][%s] 群聊普通队列长度=%s 超过阈值(10)，将丢弃旧请求",
+                "[队列修剪][%s] 群聊普通队列长度=%s 超过阈值(10)，丢弃旧外围请求=%s，保留全部LLM子请求",
                 self.model_name,
                 queue_size,
-            )
-            latest_requests = self.group_normal_queue.drain()[-2:]
-            for req in latest_requests:
-                self.group_normal_queue.put_nowait(req)
-            logger.info(
-                "[队列修剪][%s] 修剪完成，保留最新=%s",
-                self.model_name,
-                len(latest_requests),
+                len(discarded_indices),
             )
 
 
diff --git a/tests/test_group_llm_queue_trim.py b/tests/test_group_llm_queue_trim.py
new file mode 100644
index 00000000..73ea736f
--- /dev/null
+++ b/tests/test_group_llm_queue_trim.py
@@ -0,0 +1,163 @@
+"""Ordinary group traffic cannot abandon an already started ask's LLM call."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+
+from Undefined.ai.client import AIClient
+from Undefined.config.models import ChatModelConfig
+from Undefined.services.coordinator import AICoordinator
+from Undefined.services.queue_manager import QueueManager
+
+
+async def _wait_until(predicate: Callable[[], bool]) -> None:
+    async with asyncio.timeout(4):
+        while not predicate():
+            await asyncio.sleep(0.001)
+
+
+def _coordinator(
+    queue: QueueManager, *, fail_first: bool
+) -> tuple[Any, Any, list[str]]:
+    client: Any = object.__new__(AIClient)
+    client._queue_manager = queue
+    client._pending_llm_calls = {}
+    client.runtime_config = SimpleNamespace(
+        superadmin_qq=99999,
+        ai_request_max_retries=int(fail_first),
+        missing_tool_call_retries=0,
+        tool_search_enabled=False,
+        log_thinking=False,
+    )
+    client._get_runtime_config = lambda: client.runtime_config
+    client.chat_config = ChatModelConfig(
+        api_url="https://invalid.invalid/v1",
+        api_key="isolated",
+        model_name="audit",
+        max_tokens=64,
+    )
+    client.tool_manager = SimpleNamespace(get_openai_tools=lambda: [])
+    client._filter_tools_for_runtime_config = lambda tools, **kwargs: tools
+
+    async def build_messages(question: str, **kwargs: Any) -> list[dict[str, Any]]:
+        return [{"role": "user", "content": question}]
+
+    client._prompt_builder = SimpleNamespace(
+        build_messages=build_messages, end_summaries=[]
+    )
+    client._maybe_prefetch_tools = AsyncMock(
+        side_effect=lambda messages, tools, call_type: (messages, None)
+    )
+    client.model_selector = SimpleNamespace(wait_ready=AsyncMock())
+    client._search_wrapper = None
+    client._end_summary_storage = None
+    client._send_private_message_callback = None
+    client._send_image_callback = None
+    client.memory_storage = None
+    client._knowledge_manager = None
+    client._cognitive_service = None
+    client._meme_service = None
+    client._crawl4ai_capabilities = None
+    attempts: list[str] = []
+
+    async def model_request(**kwargs: Any) -> dict[str, Any]:
+        original = "original-first" in str(kwargs["messages"])
+        attempts.append("original" if original else "later")
+        if fail_first and original and attempts.count("original") == 1:
+            raise OSError("isolated retryable failure")
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "content": "original-result" if original else "later-result"
+                    }
+                }
+            ]
+        }
+
+    client.request_model = model_request
+    coordinator: Any = object.__new__(AICoordinator)
+    coordinator.ai = client
+    coordinator.config = SimpleNamespace(
+        superadmin_qq=99999,
+        bot_qq=88888,
+        chat_model=client.chat_config,
+        ai_request_max_retries=int(fail_first),
+    )
+    coordinator.queue_manager = queue
+    coordinator.security = SimpleNamespace(
+        detect_injection=AsyncMock(return_value=False)
+    )
+    coordinator.history_manager = SimpleNamespace(modify_last_group_message=AsyncMock())
+    coordinator.onebot = SimpleNamespace(
+        get_image=AsyncMock(), get_forward_msg=AsyncMock(), send_like=AsyncMock()
+    )
+    coordinator.sender = SimpleNamespace(
+        send_group_message=AsyncMock(), send_private_message=AsyncMock()
+    )
+    coordinator.scheduler = None
+    return coordinator, client, attempts
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("fail_first", [False, True])
+async def test_started_normal_group_ask_survives_outer_queue_trim(
+    fail_first: bool,
+) -> None:
+    queue = QueueManager(ai_request_interval=0.1, max_retries=int(fail_first))
+    coordinator, client, attempts = _coordinator(queue, fail_first=fail_first)
+    queue.start(coordinator.execute_reply)
+    try:
+        await coordinator.handle_auto_reply(
+            group_id=12345, sender_id=20001, text="original-first", message_content=[]
+        )
+        if fail_first:
+            await _wait_until(
+                lambda: (
+                    "audit" in queue._model_queues
+                    and queue._model_queues["audit"].group_normal_queue.retry_count()
+                    == 1
+                )
+            )
+        else:
+            await _wait_until(lambda: len(client._pending_llm_calls) == 1)
+        original_request = next(iter(client._pending_llm_calls))
+        for index in range(11):
+            await coordinator.handle_auto_reply(
+                group_id=12345,
+                sender_id=30000 + index,
+                text=f"later-{index}",
+                message_content=[],
+            )
+        requests = list(queue._model_queues["audit"].group_normal_queue._items)
+        assert requests[0]["request_id"] == original_request
+        assert requests[0]["_queue_lane"] == "group_normal"
+        assert requests[0].get("_retry_count", 0) == int(fail_first)
+        assert [request.get("sender_id") for request in requests[1:]] == [
+            30008,
+            30009,
+            30010,
+        ]
+        await _wait_until(
+            lambda: (
+                coordinator.sender.send_group_message.await_count == 4
+                and not client._pending_llm_calls
+                and queue._active_inflight_count() == 0
+            )
+        )
+        assert attempts.count("original") == 1 + int(fail_first)
+        assert queue._model_queues["audit"].group_normal_queue.empty()
+        replies = [
+            call.args[1]
+            for call in coordinator.sender.send_group_message.await_args_list
+        ]
+        assert replies.count("original-result") == 1
+        assert replies.count("later-result") == 3
+    finally:
+        await queue.stop()
diff --git a/tests/test_queue_manager.py b/tests/test_queue_manager.py
index 99af264a..35aef515 100644
--- a/tests/test_queue_manager.py
+++ b/tests/test_queue_manager.py
@@ -11,10 +11,48 @@
 from Undefined.services.queue_manager import (
     QUEUE_LANE_BACKGROUND,
     QUEUE_LANE_PRIVATE,
+    ModelQueue,
     QueueManager,
 )
 
 
+@pytest.mark.parametrize("llm_type", ["queued_llm_call", "background_llm_call"])
+def test_normal_trim_retains_llm_calls_and_retries_in_original_order(
+    llm_type: str,
+) -> None:
+    queue = ModelQueue("chat")
+    first = {"type": llm_type, "request_id": "first"}
+    retry = {"type": llm_type, "request_id": "retry", "_retry_count": 1}
+    queue.group_normal_queue.put_nowait(first)
+    for index in range(11):
+        queue.group_normal_queue.put_nowait(
+            {"type": "auto_reply", "request_id": str(index)}
+        )
+        if index == 9:
+            queue.group_normal_queue.put_nowait(retry)
+    queue.trim_normal_queue()
+    remaining = queue.group_normal_queue.drain()
+    assert [request["request_id"] for request in remaining] == [
+        "first",
+        "9",
+        "retry",
+        "10",
+    ]
+    assert remaining[0] is first
+    assert remaining[2] is retry
+
+
+def test_normal_trim_with_only_llm_calls_does_not_discard_any() -> None:
+    queue = ModelQueue("chat")
+    requests = [
+        {"type": "queued_llm_call", "request_id": str(index)} for index in range(15)
+    ]
+    for request in requests:
+        queue.group_normal_queue.put_nowait(request)
+    queue.trim_normal_queue()
+    assert queue.group_normal_queue.drain() == requests
+
+
 class _CountingEvent(asyncio.Event):
     def __init__(self) -> None:
         super().__init__()

From 37d1b1d7e278af4bc026b929fe2746100591a0b4 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:46:10 +0800
Subject: [PATCH 097/121] fix(arxiv): clean cancelled downloads after file
 workers settle

---
 docs/configuration.md                         |   1 +
 src/Undefined/arxiv/downloader.py             | 113 ++++----
 .../skills/tools/arxiv_paper/README.md        |   2 +
 src/Undefined/utils/http_download.py          |  23 +-
 tests/test_arxiv_downloader.py                | 267 ++++++++++++++++++
 5 files changed, 348 insertions(+), 58 deletions(-)
 create mode 100644 tests/test_arxiv_downloader.py

diff --git a/docs/configuration.md b/docs/configuration.md
index c7ba9146..89be2c0f 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1106,6 +1106,7 @@ api_key = "replace-with-your-key"
 - PDF 下载或上传失败时不会额外发送失败提示，只保留论文信息消息。
 - 同一论文按物理投递地址去重：同一地址的并发请求复用在途发送，发送完成后一小时内跳过重复请求。`qq:<QQ号>`、`wechat:<QQ号>` 和 `group:<群号>` 独立计数；同一逻辑 QQ 在 QQ 和微信请求论文时，两端都能收到。
 - 自动提取仍默认发送论文信息与 PDF；若用户要求分析 arXiv 论文内容，`file_analysis_agent` 会通过 `arxiv_paper(output_mode=uid)` 获取 PDF 附件 UID 后再分析；只需标题、作者、摘要和链接等元信息时可使用 `arxiv_paper(output_mode=info)`。
+- PDF 预检、流式下载或落盘阶段取消时，会清理本次独立任务目录；网络等待可直接取消，已开始的文件操作先等实际线程完成再清理并传播取消。发送和附件 UID 模式共用此规则。
 
 ---
 
diff --git a/src/Undefined/arxiv/downloader.py b/src/Undefined/arxiv/downloader.py
index 39a3360c..86ec1f6d 100644
--- a/src/Undefined/arxiv/downloader.py
+++ b/src/Undefined/arxiv/downloader.py
@@ -15,6 +15,7 @@
     probe_remote_file,
 )
 from Undefined.utils.paths import DOWNLOAD_CACHE_DIR, ensure_dir
+from Undefined.utils import io
 
 logger = logging.getLogger(__name__)
 
@@ -46,63 +47,69 @@ async def download_paper_pdf(
     task_dir = ensure_dir(_ARXIV_DOWNLOAD_DIR / uuid.uuid4().hex)
     file_path = task_dir / build_download_filename(paper.paper_id)
 
-    final_url = paper.pdf_url
-    expected_size: int | None = None
-
     try:
-        probe = await probe_remote_file(
-            paper.pdf_url,
-            timeout_seconds=min(timeout_seconds, 60.0),
-            follow_redirects=True,
-            context=context,
-            proxy_scope="arxiv",
-        )
-        final_url = probe.final_url
-        expected_size = probe.content_length
-        if expected_size is not None and expected_size > max_file_size_bytes:
-            logger.info(
-                "[arXiv] PDF 超过限制，跳过下载: paper=%s size=%sB limit=%sMB",
+        final_url = paper.pdf_url
+        expected_size: int | None = None
+        try:
+            probe = await probe_remote_file(
+                paper.pdf_url,
+                timeout_seconds=min(timeout_seconds, 60.0),
+                follow_redirects=True,
+                context=context,
+                proxy_scope="arxiv",
+            )
+            final_url = probe.final_url
+            expected_size = probe.content_length
+            if expected_size is not None and expected_size > max_file_size_bytes:
+                logger.info(
+                    "[arXiv] PDF 超过限制，跳过下载: paper=%s size=%sB limit=%sMB",
+                    paper.paper_id,
+                    expected_size,
+                    max_file_size_mb,
+                )
+                return PaperDownloadResult(None, expected_size, "too_large"), task_dir
+        except Exception as exc:
+            logger.warning(
+                "[arXiv] PDF 预检失败，转为直接流式下载: paper=%s err=%s",
                 paper.paper_id,
-                expected_size,
-                max_file_size_mb,
+                exc,
             )
-            return PaperDownloadResult(None, expected_size, "too_large"), task_dir
-    except Exception as exc:
-        logger.warning(
-            "[arXiv] PDF 预检失败，转为直接流式下载: paper=%s err=%s",
-            paper.paper_id,
-            exc,
-        )
 
-    try:
-        _, downloaded_size = await download_remote_file(
-            final_url,
-            file_path,
-            max_file_size_bytes=max_file_size_bytes,
-            timeout_seconds=timeout_seconds,
-            expected_size=expected_size,
-            follow_redirects=True,
-            proxy_scope="arxiv",
-            proxy_config=context.get("runtime_config") if context else None,
-        )
-        logger.info(
-            "[arXiv] PDF 下载完成: paper=%s size=%sB path=%s",
-            paper.paper_id,
-            downloaded_size,
-            file_path,
-        )
-        return PaperDownloadResult(file_path, downloaded_size, "downloaded"), task_dir
-    except ValueError as exc:
-        logger.info(
-            "[arXiv] PDF 下载跳过: paper=%s reason=%s",
-            paper.paper_id,
-            exc,
-        )
-        return PaperDownloadResult(None, None, "skipped"), task_dir
-    except Exception:
-        logger.exception("[arXiv] PDF 下载失败: paper=%s", paper.paper_id)
-        return PaperDownloadResult(None, None, "failed"), task_dir
+        try:
+            _, downloaded_size = await download_remote_file(
+                final_url,
+                file_path,
+                max_file_size_bytes=max_file_size_bytes,
+                timeout_seconds=timeout_seconds,
+                expected_size=expected_size,
+                follow_redirects=True,
+                proxy_scope="arxiv",
+                proxy_config=context.get("runtime_config") if context else None,
+            )
+            logger.info(
+                "[arXiv] PDF 下载完成: paper=%s size=%sB path=%s",
+                paper.paper_id,
+                downloaded_size,
+                file_path,
+            )
+            return PaperDownloadResult(
+                file_path, downloaded_size, "downloaded"
+            ), task_dir
+        except ValueError as exc:
+            logger.info(
+                "[arXiv] PDF 下载跳过: paper=%s reason=%s",
+                paper.paper_id,
+                exc,
+            )
+            return PaperDownloadResult(None, None, "skipped"), task_dir
+        except Exception:
+            logger.exception("[arXiv] PDF 下载失败: paper=%s", paper.paper_id)
+            return PaperDownloadResult(None, None, "failed"), task_dir
+    except BaseException:
+        # 返回前仍由下载器持有任务目录；取消不能落到尚未建立的 sender finally。
+        await cleanup_download_path(task_dir)
+        raise
 
 
 async def cleanup_download_path(task_dir: Path) -> None:
-    await cleanup_download_dir(task_dir)
+    await io.run_cancellation_safe(cleanup_download_dir(task_dir))
diff --git a/src/Undefined/skills/tools/arxiv_paper/README.md b/src/Undefined/skills/tools/arxiv_paper/README.md
index d128ec36..af335333 100644
--- a/src/Undefined/skills/tools/arxiv_paper/README.md
+++ b/src/Undefined/skills/tools/arxiv_paper/README.md
@@ -17,6 +17,8 @@
 
 同一会话的同一论文并发发送会共享在途结果。主发送任务取消时，等待该结果的调用也会收到取消，不记录成功去重时间；单个等待调用取消不会取消主发送任务。
 
+PDF 预检、流式下载或最终落盘阶段取消时，会清理本次独立任务目录。网络等待可立即取消；已经进入磁盘写入或原子替换的操作会先等实际线程完成，再清理并传播取消，避免写盘晚于清理留下文件。发送与附件 UID 模式共用这条清理规则。
+
 `uid` 模式流程：
 1. 下载 PDF
 2. 注册为当前会话附件 UID
diff --git a/src/Undefined/utils/http_download.py b/src/Undefined/utils/http_download.py
index e5d5f870..ff1467f3 100644
--- a/src/Undefined/utils/http_download.py
+++ b/src/Undefined/utils/http_download.py
@@ -1,17 +1,18 @@
 from __future__ import annotations
 
 import asyncio
-import os
 import shutil
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 import aiofiles
+from aiofiles.threadpool.binary import AsyncBufferedIOBase
 import httpx
 
 from Undefined.skills.http_config import build_httpx_client_kwargs
 from Undefined.skills.http_client import request_with_retry
+from Undefined.utils import io
 
 DEFAULT_DOWNLOAD_CHUNK_SIZE = 64 * 1024
 
@@ -100,7 +101,16 @@ async def download_remote_file(
                 ):
                     raise ValueError("远程文件大小与预检不一致，已取消下载")
 
-                async with aiofiles.open(part_path, "wb") as f:
+                output: AsyncBufferedIOBase | None = None
+
+                async def open_output() -> None:
+                    nonlocal output
+                    output = await aiofiles.open(part_path, "wb")
+
+                try:
+                    # 先取得所有权再传播取消，避免 open 线程返回的 handle 无人关闭。
+                    await io.run_cancellation_safe(open_output())
+                    assert output is not None
                     async for chunk in response.aiter_bytes(chunk_size=chunk_size):
                         if not chunk:
                             continue
@@ -112,15 +122,18 @@ async def download_remote_file(
                             and response.num_bytes_downloaded > expected_size
                         ):
                             raise ValueError("下载中发现文件超出预检大小，已取消下载")
-                        await f.write(chunk)
-                    await f.flush()
+                        await io.run_cancellation_safe(output.write(chunk))
+                    await io.run_cancellation_safe(output.flush())
+                finally:
+                    if output is not None:
+                        await io.run_cancellation_safe(output.close())
                 if (
                     expected_size is not None
                     and response.num_bytes_downloaded != expected_size
                 ):
                     raise ValueError("下载完成后大小与预检不一致，已取消下载")
 
-        await asyncio.to_thread(os.replace, part_path, target_path)
+        await io.run_cancellation_safe(io.move_path(part_path, target_path))
         return str(target_path.resolve()), downloaded_size
     finally:
         if part_path.exists():
diff --git a/tests/test_arxiv_downloader.py b/tests/test_arxiv_downloader.py
new file mode 100644
index 00000000..061df8aa
--- /dev/null
+++ b/tests/test_arxiv_downloader.py
@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import threading
+from io import BufferedWriter, FileIO
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any, BinaryIO
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+
+from Undefined.arxiv import downloader
+from Undefined.arxiv.models import PaperInfo
+from Undefined.utils import http_download
+
+
+def _paper() -> PaperInfo:
+    return PaperInfo(
+        paper_id="2501.01234",
+        title="isolated paper",
+        authors=(),
+        summary="",
+        published="",
+        updated="",
+        primary_category="",
+        abs_url="https://isolated.invalid/abs/2501.01234",
+        pdf_url="https://isolated.invalid/pdf/2501.01234.pdf",
+    )
+
+
+@pytest.mark.asyncio
+async def test_arxiv_preflight_cancel_removes_unowned_task_dir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    ready = asyncio.Event()
+
+    async def probe(*args: Any, **kwargs: Any) -> http_download.RemoteFileProbe:
+        ready.set()
+        await asyncio.Event().wait()
+        raise AssertionError("unreachable")
+
+    monkeypatch.setattr(downloader, "_ARXIV_DOWNLOAD_DIR", tmp_path)
+    monkeypatch.setattr(downloader, "probe_remote_file", probe)
+    task = asyncio.create_task(
+        downloader.download_paper_pdf(_paper(), max_file_size_mb=1)
+    )
+    await ready.wait()
+    assert len(list(tmp_path.iterdir())) == 1
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(task, 1)
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.asyncio
+async def test_arxiv_stream_cancel_does_not_wait_for_network_completion(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    ready = asyncio.Event()
+
+    class BlockedStream(httpx.AsyncByteStream):
+        async def __aiter__(self) -> AsyncIterator[bytes]:
+            yield b"x" * http_download.DEFAULT_DOWNLOAD_CHUNK_SIZE
+            ready.set()
+            await asyncio.Event().wait()
+
+    client_type = httpx.AsyncClient
+
+    def reply(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, stream=BlockedStream(), request=request)
+
+    def client(**kwargs: Any) -> httpx.AsyncClient:
+        return client_type(transport=httpx.MockTransport(reply), **kwargs)
+
+    paper = _paper()
+    monkeypatch.setattr(downloader, "_ARXIV_DOWNLOAD_DIR", tmp_path)
+    monkeypatch.setattr(
+        downloader,
+        "probe_remote_file",
+        AsyncMock(
+            return_value=http_download.RemoteFileProbe(
+                paper.pdf_url, httpx.Headers(), None
+            )
+        ),
+    )
+    monkeypatch.setattr(httpx, "AsyncClient", client)
+    task = asyncio.create_task(downloader.download_paper_pdf(paper, max_file_size_mb=1))
+    await ready.wait()
+    assert len(list(tmp_path.rglob("*.part"))) == 1
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(task, 1)
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("replaced_before_cancel", [False, True])
+async def test_arxiv_cancel_waits_for_actual_replace_before_cleanup(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    replaced_before_cancel: bool,
+) -> None:
+    started = threading.Event()
+    release = threading.Event()
+    finished = threading.Event()
+    original_replace = os.replace
+
+    def replace(source: Path, target: Path) -> None:
+        if replaced_before_cancel:
+            original_replace(source, target)
+        started.set()
+        if not release.wait(5):
+            raise AssertionError("replace thread was not released")
+        if not replaced_before_cancel:
+            original_replace(source, target)
+        finished.set()
+
+    client_type = httpx.AsyncClient
+
+    def reply(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"complete PDF bytes", request=request)
+
+    def client(**kwargs: Any) -> httpx.AsyncClient:
+        return client_type(transport=httpx.MockTransport(reply), **kwargs)
+
+    paper = _paper()
+    monkeypatch.setattr(downloader, "_ARXIV_DOWNLOAD_DIR", tmp_path)
+    monkeypatch.setattr(
+        downloader,
+        "probe_remote_file",
+        AsyncMock(
+            return_value=http_download.RemoteFileProbe(
+                paper.pdf_url, httpx.Headers(), None
+            )
+        ),
+    )
+    monkeypatch.setattr(httpx, "AsyncClient", client)
+    monkeypatch.setattr(os, "replace", replace)
+    task = asyncio.create_task(downloader.download_paper_pdf(paper, max_file_size_mb=1))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done()
+        assert not finished.is_set()
+    finally:
+        release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(task, 2)
+    assert finished.is_set()
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("phase", ["open", "close"])
+async def test_arxiv_cancel_waits_for_open_and_closes_acquired_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, phase: str
+) -> None:
+    import aiofiles.threadpool
+
+    started = threading.Event()
+    release = threading.Event()
+    finished = threading.Event()
+    handles: list[BinaryIO] = []
+    original_open = open
+
+    class BlockingWriter(BufferedWriter):
+        def close(self) -> None:
+            if not self.closed:
+                started.set()
+                if not release.wait(5):
+                    raise AssertionError("close thread was not released")
+                super().close()
+                finished.set()
+
+    def open_file(file: str | Path, *args: Any, **kwargs: Any) -> Any:
+        handle = (
+            BlockingWriter(FileIO(file, mode="wb"))
+            if phase == "close"
+            else original_open(file, *args, **kwargs)
+        )
+        handles.append(handle)
+        if phase == "open":
+            started.set()
+            if not release.wait(5):
+                raise AssertionError("open thread was not released")
+            finished.set()
+        return handle
+
+    client_type = httpx.AsyncClient
+
+    def reply(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"PDF bytes", request=request)
+
+    def client(**kwargs: Any) -> httpx.AsyncClient:
+        return client_type(transport=httpx.MockTransport(reply), **kwargs)
+
+    paper = _paper()
+    monkeypatch.setattr(downloader, "_ARXIV_DOWNLOAD_DIR", tmp_path)
+    monkeypatch.setattr(
+        downloader,
+        "probe_remote_file",
+        AsyncMock(
+            return_value=http_download.RemoteFileProbe(
+                paper.pdf_url, httpx.Headers(), None
+            )
+        ),
+    )
+    monkeypatch.setattr(httpx, "AsyncClient", client)
+    monkeypatch.setattr(aiofiles.threadpool, "sync_open", open_file)
+    task = asyncio.create_task(downloader.download_paper_pdf(paper, max_file_size_mb=1))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(asyncio.shield(task), 0.03)
+        assert not finished.is_set()
+    finally:
+        release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(task, 2)
+    assert finished.is_set()
+    assert handles[0].closed
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.asyncio
+async def test_arxiv_cleanup_waits_through_repeated_cancellation(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    task_dir = tmp_path / "download-task"
+    task_dir.mkdir()
+    (task_dir / "paper.pdf").write_bytes(b"PDF")
+    started = threading.Event()
+    release = threading.Event()
+
+    def remove(path: Path) -> None:
+        started.set()
+        if not release.wait(5):
+            raise AssertionError("cleanup thread was not released")
+        shutil.rmtree(path)
+
+    async def cleanup(path: Path) -> None:
+        await asyncio.to_thread(remove, path)
+
+    monkeypatch.setattr(downloader, "cleanup_download_dir", cleanup)
+    task = asyncio.create_task(downloader.cleanup_download_path(task_dir))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(asyncio.shield(task), 0.03)
+    finally:
+        release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await asyncio.wait_for(task, 2)
+    assert not task_dir.exists()

From f2877bb15f54f7e06933e9389808546d45ecb855 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:46:39 +0800
Subject: [PATCH 098/121] docs(memory): clarify durable add failure semantics

---
 src/Undefined/memory.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Undefined/memory.py b/src/Undefined/memory.py
index 1fa936c3..9688c098 100644
--- a/src/Undefined/memory.py
+++ b/src/Undefined/memory.py
@@ -94,7 +94,8 @@ async def add(self, fact: str) -> Optional[str]:
             fact: 记忆内容
 
         返回:
-            新生成的 UUID，如果失败则返回 None
+            新记忆或已有相同事实的 UUID；空白事实返回 None。
+            写入失败向调用方传播异常，并保持原有记忆。
         """
         if not fact or not fact.strip():
             logger.warning("[记忆] 尝试添加空记忆，已忽略")

From 8759662e8acb7b10d0d9a43a196d154657f3fdb8 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:47:53 +0800
Subject: [PATCH 099/121] fix(chat): refresh completed conversations after
 reconnect

---
 apps/undefined-chat/README.md                 |   1 +
 .../src/chat-store/resume-completion.test.ts  | 299 ++++++++++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  33 +-
 .../src/platform/AndroidLifecycle.test.ts     |  51 +++
 docs/undefined-chat.md                        |   3 +-
 5 files changed, 381 insertions(+), 6 deletions(-)
 create mode 100644 apps/undefined-chat/src/chat-store/resume-completion.test.ts

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index e5e0bc2d..d12cc735 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -17,6 +17,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 自动滚动：智能跟随底部，可在设置面板开关，偏好持久化到 localStorage。
 - 重命名只更新目标会话标题，保留当前会话、输入草稿与移动端面板；请求期间切换会话也不会被迟到响应切回。
 - 事件：SSE 优先，断开时 JSON fallback（指数退避重连，活跃任务持续重试）；完整任务快照恢复消息与已结束调用，并按快照游标续接，旧 Runtime 的正文前缀也会保留。
+- 恢复连接时，已从 active 列表消失的本地任务会补刷所属会话的权威历史，包括非当前会话；仍在历史落盘的终态任务继续保留发送锁，已删除会话不再请求。
 - 快捷键：Ctrl/Cmd+N 新会话，Ctrl/Cmd+K 聚焦输入并打开命令模式，Ctrl/Cmd+/ 切换侧栏，Ctrl/Cmd+, 打开设置，Escape 关闭当前弹层/抽屉。
 - i18n：中英双语运行时切换，提供语言切换 UI，并按系统语言自动检测默认语言。
 
diff --git a/apps/undefined-chat/src/chat-store/resume-completion.test.ts b/apps/undefined-chat/src/chat-store/resume-completion.test.ts
new file mode 100644
index 00000000..71bf2529
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/resume-completion.test.ts
@@ -0,0 +1,299 @@
+import { describe, expect, test, vi } from "vitest";
+import type {
+	ActiveJobsResponse,
+	HistoryResponse,
+	JobEventsJsonResponse,
+} from "../runtime-client/types";
+import {
+	conversation,
+	historyItem,
+	job,
+	runtimeClientStub,
+} from "../test-fixtures";
+import { createChatStore } from "./store";
+
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	const promise = new Promise<T>((resolvePromise) => {
+		resolve = resolvePromise;
+	});
+	return { promise, resolve };
+}
+
+function resumeFixture() {
+	let active: ActiveJobsResponse = { job: null, jobs: [] };
+	let completed = false;
+	const client = runtimeClientStub({
+		listConversations: vi.fn(async () => ({
+			conversations: [conversation({ id: "A" }), conversation({ id: "B" })],
+			activeJob: null,
+			defaultConversationId: "A",
+			virtualUserId: "webchat",
+		})),
+		getActiveJobs: vi.fn(async () => active),
+		sendMessage: vi.fn(async () =>
+			job({ jobId: "job-A", conversationId: "A", hasTimelineSnapshot: true }),
+		),
+		getHistory: vi.fn(async ({ conversationId }): Promise<HistoryResponse> => {
+			const items =
+				completed && conversationId === "A"
+					? [
+							historyItem({ messageId: "user-A", content: "question-A" }),
+							historyItem({
+								messageId: "bot-A",
+								role: "bot",
+								content: "completed-in-background",
+							}),
+						]
+					: [];
+			return {
+				conversationId,
+				virtualUserId: "webchat",
+				permission: "superadmin",
+				count: items.length,
+				items,
+				limit: 50,
+				before: null,
+				hasMore: false,
+				nextBefore: null,
+				total: items.length,
+			};
+		}),
+	});
+	const store = createChatStore({ client });
+	return {
+		client,
+		store,
+		complete() {
+			completed = true;
+		},
+		setActive(response: ActiveJobsResponse) {
+			active = response;
+		},
+		async start() {
+			await store.bootstrap();
+			store.updateDraft("A", "question-A");
+			await store.sendSelectedMessage();
+			await store.selectConversation("B");
+		},
+	};
+}
+
+describe("completed jobs omitted from a reconnect snapshot", () => {
+	test("refreshes a nonselected conversation even when its old JSON response arrives after resume", async () => {
+		const { client, store, start, complete } = resumeFixture();
+		const terminal = deferred<JobEventsJsonResponse>();
+		vi.mocked(client.fetchJobEventsJson).mockImplementationOnce(
+			() => terminal.promise,
+		);
+		await start();
+		store.handleRuntimeStatus({
+			jobId: "job-A",
+			subscriptionId: "sub-1",
+			status: "error",
+			detail: "offline",
+		});
+		complete();
+		await store.bootstrap({ preserveSelectionId: "B", resuming: true });
+		terminal.resolve({
+			job: job({
+				jobId: "job-A",
+				conversationId: "A",
+				status: "done",
+				historyFinalized: true,
+				lastSeq: 3,
+			}),
+			events: [],
+			after: 0,
+			lastSeq: 3,
+		});
+		await Promise.resolve();
+		await store.selectConversation("A");
+		expect(store.getSnapshot().historyByConversation.A.items[1].content).toBe(
+			"completed-in-background",
+		);
+		expect(client.getHistory).toHaveBeenCalledTimes(4);
+		const lateTerminal = {
+			jobId: "job-A",
+			subscriptionId: "sub-1",
+			seq: 3,
+			eventType: "done",
+			payload: { conversation_id: "A" },
+		};
+		store.handleRuntimeEvent(lateTerminal);
+		store.handleRuntimeEvent(lateTerminal);
+		await vi.waitFor(() => expect(client.getHistory).toHaveBeenCalledTimes(5));
+		expect(store.getSnapshot().historyByConversation.A.items).toHaveLength(2);
+	});
+
+	test("deduplicates the selected conversation and retains terminal jobs still finalizing history", async () => {
+		const { client, store, start, complete, setActive } = resumeFixture();
+		await start();
+		await store.selectConversation("A");
+		setActive({
+			job: null,
+			jobs: [
+				job({
+					jobId: "job-A",
+					conversationId: "A",
+					status: "done",
+					historyFinalized: false,
+					hasTimelineSnapshot: true,
+				}),
+			],
+		});
+		await store.bootstrap({ preserveSelectionId: "B", resuming: true });
+		expect(client.getHistory).toHaveBeenCalledTimes(3);
+		expect(store.getSnapshot().activeJobsByConversation.A).toBeDefined();
+		setActive({ job: null, jobs: [] });
+		complete();
+		await store.bootstrap({ preserveSelectionId: "A", resuming: true });
+		expect(client.getHistory).toHaveBeenCalledTimes(4);
+		expect(store.getSnapshot().activeJobsByConversation.A).toBeUndefined();
+	});
+
+	test("does not reload a conversation deleted while offline", async () => {
+		const { client, store, start } = resumeFixture();
+		await start();
+		vi.mocked(client.listConversations).mockResolvedValue({
+			conversations: [conversation({ id: "B" })],
+			activeJob: null,
+			defaultConversationId: "B",
+			virtualUserId: "webchat",
+		});
+		await store.bootstrap({ preserveSelectionId: "B", resuming: true });
+		expect(
+			vi
+				.mocked(client.getHistory)
+				.mock.calls.map(([input]) => input.conversationId),
+		).toEqual(["A", "B", "B"]);
+	});
+
+	test("preserves the history request started by a terminal response during bootstrap", async () => {
+		const { client, store, start, complete } = resumeFixture();
+		await start();
+		const snapshot = deferred<ActiveJobsResponse>();
+		vi.mocked(client.getActiveJobs).mockImplementationOnce(
+			() => snapshot.promise,
+		);
+		const terminalHistory = deferred<HistoryResponse>();
+		const getHistory = client.getHistory;
+		vi.mocked(client.getHistory).mockImplementationOnce(
+			() => terminalHistory.promise,
+		);
+		const resuming = store.bootstrap({
+			preserveSelectionId: "B",
+			resuming: true,
+		});
+		await vi.waitFor(() =>
+			expect(client.getActiveJobs).toHaveBeenCalledTimes(2),
+		);
+		vi.mocked(client.fetchJobEventsJson).mockResolvedValue({
+			job: job({
+				jobId: "job-A",
+				conversationId: "A",
+				status: "done",
+				historyFinalized: true,
+				hasTimelineSnapshot: true,
+			}),
+			events: [],
+			after: 0,
+			lastSeq: 0,
+		});
+		store.handleRuntimeStatus({
+			jobId: "job-A",
+			subscriptionId: "sub-1",
+			status: "closed",
+			detail: "done",
+		});
+		await vi.waitFor(() => expect(client.getHistory).toHaveBeenCalledTimes(3));
+		snapshot.resolve({ job: null, jobs: [] });
+		await resuming;
+		complete();
+		// 获取 fixture 的权威历史结果，但不发起新的 store history 请求。
+		terminalHistory.resolve(
+			await getHistory({ conversationId: "A", limit: 50 }),
+		);
+		await vi.waitFor(() =>
+			expect(store.getSnapshot().historyByConversation.A.items).toHaveLength(2),
+		);
+		expect(store.getSnapshot().historyByConversation.A.items[1].content).toBe(
+			"completed-in-background",
+		);
+	});
+
+	test("retries a terminal history refresh invalidated by same-Runtime suspension", async () => {
+		const { client, store, start, complete } = resumeFixture();
+		await start();
+		const pendingHistory = deferred<HistoryResponse>();
+		vi.mocked(client.getHistory).mockImplementationOnce(
+			() => pendingHistory.promise,
+		);
+		vi.mocked(client.fetchJobEventsJson).mockResolvedValue({
+			job: job({
+				jobId: "job-A",
+				conversationId: "A",
+				status: "done",
+				historyFinalized: true,
+				hasTimelineSnapshot: true,
+			}),
+			events: [],
+			after: 0,
+			lastSeq: 0,
+		});
+		store.handleRuntimeStatus({
+			jobId: "job-A",
+			subscriptionId: "sub-1",
+			status: "closed",
+			detail: "done",
+		});
+		await vi.waitFor(() => expect(client.getHistory).toHaveBeenCalledTimes(3));
+		expect(store.getSnapshot().activeJobsByConversation.A).toBeUndefined();
+		expect(store.getSnapshot().historyByConversation.A.loading).toBe(true);
+		store.suspendRuntime();
+		complete();
+		await store.bootstrap({ preserveSelectionId: "B", resumeSuspended: true });
+		expect(client.getHistory).toHaveBeenCalledTimes(5);
+		const finalHistory = store.getSnapshot().historyByConversation.A;
+		pendingHistory.resolve({
+			conversationId: "A",
+			virtualUserId: "webchat",
+			permission: "superadmin",
+			count: 1,
+			limit: 50,
+			before: null,
+			hasMore: false,
+			nextBefore: null,
+			total: 1,
+			items: [historyItem({ content: "obsolete" })],
+		});
+		await Promise.resolve();
+		await store.selectConversation("A");
+		expect(store.getSnapshot().historyByConversation.A).toEqual(finalHistory);
+		expect(finalHistory.items[1].content).toBe("completed-in-background");
+	});
+
+	test("retries a failed background completion refresh when selecting its conversation", async () => {
+		const { client, store, start, complete } = resumeFixture();
+		await start();
+		complete();
+		const getHistory = vi.mocked(client.getHistory).getMockImplementation();
+		if (!getHistory) throw new Error("missing fixture history implementation");
+		let failA = true;
+		vi.mocked(client.getHistory).mockImplementation(async (input) => {
+			if (input.conversationId === "A" && failA)
+				throw new Error("temporary history failure");
+			return getHistory(input);
+		});
+		await store.bootstrap({ preserveSelectionId: "B", resuming: true });
+		expect(store.getSnapshot().historyByConversation.A.error).toBe(
+			"temporary history failure",
+		);
+		failA = false;
+		await store.selectConversation("A");
+		expect(store.getSnapshot().historyByConversation.A.error).toBeNull();
+		expect(store.getSnapshot().historyByConversation.A.items[1].content).toBe(
+			"completed-in-background",
+		);
+	});
+});
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index bc31d604..4cf951c1 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -809,13 +809,13 @@ export function createChatStore({
 		fallbackTimersByJob.clear();
 		latestFallbackRequestByJob.clear();
 		fallbackBackoffByJob.clear();
-		historyRequestsByConversation.clear();
 	}
 
 	function resetRuntimeScope(nextUrl: string): void {
 		runtimeUrl = nextUrl;
 		runtimeGeneration += 1;
 		clearNativeSubscriptions();
+		historyRequestsByConversation.clear();
 		sendInFlight = false;
 		lastCommandsFetchedAt = 0;
 		draftRevisionsByConversation.clear();
@@ -836,6 +836,7 @@ export function createChatStore({
 			sendInFlight = false;
 		}
 		runtimeSuspended = true;
+		historyRequestsByConversation.clear();
 		inFlightBootstrap = null;
 		state = {
 			...state,
@@ -1141,6 +1142,29 @@ export function createChatStore({
 					recoveredJobs.push(snapshot);
 				}
 			}
+			const historyConversationIds = new Set(selected ? [selected] : []);
+			const recoveredJobIds = new Set(recoveredJobs.map((item) => item.jobId));
+			// 已落盘终态会从 active 列表消失；补刷仍存在的非当前会话缓存。
+			for (const previous of Object.values(state.activeJobsByConversation)) {
+				if (
+					conversationIds.has(previous.conversationId) &&
+					!recoveredJobIds.has(previous.jobId)
+				) {
+					historyConversationIds.add(previous.conversationId);
+				}
+			}
+			// 配置暂停可能发生在 finishJob 已移除任务、历史刷新尚未返回时。
+			for (const [conversationId, history] of Object.entries(
+				state.historyByConversation,
+			)) {
+				if (
+					history.loading &&
+					!historyRequestsByConversation.has(conversationId) &&
+					conversationIds.has(conversationId)
+				) {
+					historyConversationIds.add(conversationId);
+				}
+			}
 			dispatch({
 				type: "bootstrap/success",
 				runtimeConfig,
@@ -1168,9 +1192,7 @@ export function createChatStore({
 				if (generation !== runtimeGeneration) return;
 				await startStreamForJob(activeJob);
 			}
-			if (selected) {
-				await loadHistory(selected);
-			}
+			await Promise.all([...historyConversationIds].map(loadHistory));
 			if (generation !== runtimeGeneration) return;
 			if (
 				Object.keys(state.activeJobsByConversation).length > 0 &&
@@ -1312,7 +1334,8 @@ export function createChatStore({
 			return;
 		}
 		dispatch({ type: "conversation/select", conversationId });
-		if (!state.historyByConversation[conversationId]) {
+		const history = state.historyByConversation[conversationId];
+		if (!history || history.error) {
 			await loadHistory(conversationId);
 		}
 	}
diff --git a/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts b/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
index 9e044827..679df93b 100644
--- a/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
+++ b/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
@@ -1,4 +1,11 @@
 import { describe, expect, it, vi } from "vitest";
+import { createChatStore } from "../chat-store/store";
+import {
+	conversation,
+	historyItem,
+	job,
+	runtimeClientStub,
+} from "../test-fixtures";
 import { isAndroid, setupAndroidLifecycle } from "./AndroidLifecycle";
 
 const listeners = new Map<string, () => void | Promise<void>>();
@@ -69,6 +76,50 @@ describe("AndroidLifecycle", () => {
 	});
 
 	describe("setupAndroidLifecycle", () => {
+		it("reloads a completed background conversation through the real resume listener", async () => {
+			let completed = false;
+			const client = runtimeClientStub({
+				listConversations: vi.fn(async () => ({
+					conversations: [conversation({ id: "A" }), conversation({ id: "B" })],
+					activeJob: null,
+					defaultConversationId: "A",
+					virtualUserId: "webchat",
+				})),
+				sendMessage: vi.fn(async () => job({ conversationId: "A" })),
+			});
+			const getHistory = client.getHistory;
+			client.getHistory = vi.fn(async (input) => {
+				const history = await getHistory(input);
+				const items =
+					completed && input.conversationId === "A"
+						? [historyItem({ role: "bot", content: "后台已完成" })]
+						: [];
+				return {
+					...history,
+					conversationId: input.conversationId,
+					items,
+					total: items.length,
+				};
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("A", "question");
+			await store.sendSelectedMessage();
+			await store.selectConversation("B");
+			const cleanup = setupAndroidLifecycle(store);
+			await vi.waitFor(() =>
+				expect(listeners.has("tauri://resumed")).toBe(true),
+			);
+			completed = true;
+			await listeners.get("tauri://resumed")?.();
+			expect(store.getSnapshot().selectedConversationId).toBe("B");
+			await store.selectConversation("A");
+			expect(store.getSnapshot().historyByConversation.A.items[0].content).toBe(
+				"后台已完成",
+			);
+			cleanup();
+		});
+
 		it("re-bootstraps on android resume and cleans listeners", async () => {
 			const mockStore = {
 				bootstrap: vi.fn(async () => undefined),
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 1bcf9db1..93298cd8 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -70,7 +70,8 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 - 取消请求错误和 SSE 的连接状态通知同样只作用于对应的活跃 job，旧任务的迟到通知不会改写新任务的错误或连接状态。
 - `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。
 - 历史分页的 `before` / `next_before` 是非负数值索引；React 与 Tauri command 使用同一数值契约，首屏不传 `before`。
-- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs；每个任务接受完整快照及其游标后重新建立事件订阅。请求途中已消费更高序号时保留更新的本地状态。
+- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs；每个任务接受完整快照及其游标后重新建立事件订阅。已从 active 列表消失的本地任务还会补刷所属会话的权威历史，包括非当前会话；已删除会话不再请求。请求途中已消费更高序号时保留更新的本地状态。
+- 同一 Runtime 重建订阅时保留已开始的终态历史刷新；切换 Runtime 或暂停保存连接配置时，旧请求响应仍会被丢弃。
 
 ## 安全存储
 

From b5c275ee3a2c5f8d4ea9c5e71028872ef70b023b Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:49:14 +0800
Subject: [PATCH 100/121] fix(chat): preserve cache when legacy migration fails

---
 docs/management-api.md              |  2 +-
 docs/openapi.md                     |  4 +--
 src/Undefined/api/webchat_store.py  |  2 +-
 tests/test_webchat_store_commits.py | 55 +++++++++++++++++++++++++++++
 4 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index eb7b4930..5700ab2c 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -247,7 +247,7 @@ GET /api/v1/management/runtime/commands?scope=webui&q=help
   - `DELETE` 使用路径参数 `conversation_id`。
 - 校验：
   - 删除会话与接受新任务共用串行边界；存在运行中或收尾落盘的 WebChat job 时返回 `409`，已删除会话创建新任务返回 `404`。
-  - 新建、改名、清空与标题更新在原子落盘成功后才发布缓存；删除在文件移除后才撤销缓存和标题任务。磁盘错误保留上次成功状态；写入已开始后收到取消，会等待持久操作和缓存更新收敛再释放会话锁。
+  - 新建、改名、清空、旧历史迁移与标题更新在原子落盘成功后才发布缓存；删除在文件移除后才撤销缓存和标题任务。磁盘错误保留上次成功状态；旧历史迁移失败不写完成标记，可恢复存储后重试。写入已开始后收到取消，会等待持久操作和缓存更新收敛再释放会话锁。
 - 响应：
   - `200` / `201`：会话列表或会话对象。
   - `404`：会话不存在。
diff --git a/docs/openapi.md b/docs/openapi.md
index 1ccd2b80..57e20c4e 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -395,8 +395,8 @@ Undefined Chat 使用同一组 Runtime Chat 端点作为权威合同。客户端
 - 权限视角：`superadmin`。
 - 如果输入以 `/` 开头，按私聊命令分发执行（遵循命令 `allow_in_private` 开放策略）。
 - WebChat 会话持久化在 `data/webchat/conversations/<conversation_id>.json`，一个会话一个 JSON 文件。删除会话会删除对应 JSON；不会写入单个全局 conversations JSON。
-- 会话创建、改名、清空、标题状态及生成标题均在持久写入成功后更新可见缓存；写盘失败保留上次成功状态。删除失败也保留会话与标题任务，便于重试。持久操作开始后取消请求，会等文件和缓存提交收敛后再释放会话锁。
-- 首次加载会自动把旧版 `data/history/private_42.json` 或运行中的旧历史管理器记录迁移到 `legacy-system-42`，并写入 `data/webchat/legacy_private_42_migrated.json` 迁移标记。只要标记存在就不会重复迁移；即使删除迁移出的会话，也不会再次从旧文件恢复。
+- 会话创建、改名、清空、旧历史迁移、标题状态及生成标题均在持久写入成功后更新可见缓存；写盘失败保留上次成功状态。删除失败也保留会话与标题任务，便于重试。持久操作开始后取消请求，会等文件和缓存提交收敛后再释放会话锁。
+- 首次加载会自动把旧版 `data/history/private_42.json` 或运行中的旧历史管理器记录迁移到 `legacy-system-42`，并写入 `data/webchat/legacy_private_42_migrated.json` 迁移标记。迁移写盘失败不写完成标记，可在存储恢复后重试。只要标记存在就不会重复迁移；即使删除迁移出的会话，也不会再次从旧文件恢复。
 
 ### WebUI AI Chat Conversations
 
diff --git a/src/Undefined/api/webchat_store.py b/src/Undefined/api/webchat_store.py
index 14da487f..9b59959d 100644
--- a/src/Undefined/api/webchat_store.py
+++ b/src/Undefined/api/webchat_store.py
@@ -505,7 +505,7 @@ async def _migrate_legacy_once(self, legacy_history_manager: Any | None) -> None
                 )
                 conv_id = str(conv["id"])
                 async with self._get_lock(conv_id):
-                    cached = self._require_conversation_locked(conv_id)
+                    cached = _copy_json(self._require_conversation_locked(conv_id))
                     cached["messages"] = [
                         _normalize_history_record(
                             item,
diff --git a/tests/test_webchat_store_commits.py b/tests/test_webchat_store_commits.py
index 20913039..21637908 100644
--- a/tests/test_webchat_store_commits.py
+++ b/tests/test_webchat_store_commits.py
@@ -204,3 +204,58 @@ def controlled_unlink(target: Path, *args: Any, **kwargs: Any) -> None:
         if reader is not None:
             await asyncio.gather(reader, return_exceptions=True)
         await store.stop()
+
+
+@pytest.mark.asyncio
+async def test_failed_legacy_migration_preserves_cache_disk_and_can_retry(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = await _seed(tmp_path, monkeypatch, "migration")
+    conv_id = webchat_store.DEFAULT_WEBCHAT_CONVERSATION_ID
+    await store.create_conversation(conversation_id=conv_id, title="before migration")
+    marker = tmp_path / "migration.json"
+    marker.unlink()
+    legacy_path = (
+        tmp_path
+        / "legacy-history"
+        / f"private_{webchat_store.WEBCHAT_VIRTUAL_USER_ID}.json"
+    )
+    await io.write_json(
+        legacy_path,
+        [{"message": "legacy question", "display_name": "user", "user_id": 42}],
+    )
+    path = tmp_path / "conversations" / f"{conv_id}.json"
+    before_disk = path.read_bytes()
+    before_cache = await store.get_conversation(conv_id)
+    original_write = io.write_json_sync
+
+    def fail_migration_write(
+        file_path: Path | str, data: Any, use_lock: bool = True
+    ) -> None:
+        if Path(file_path) == path:
+            raise OSError("isolated migration write failure")
+        original_write(file_path, data, use_lock)
+
+    try:
+        with pytest.MonkeyPatch.context() as failure:
+            failure.setattr(io, "write_json_sync", fail_migration_write)
+            with pytest.raises(OSError, match="isolated migration write failure"):
+                await store.ensure_ready()
+        assert not marker.exists()
+        assert path.read_bytes() == before_disk
+        assert await store.get_conversation(conv_id) == before_cache
+
+        await store.ensure_ready()
+        cached = await store.get_conversation(conv_id)
+        assert cached is not None
+        assert cached == json.loads(path.read_text(encoding="utf-8"))
+        assert cached["messages"][0]["message"] == "legacy question"
+        assert cached["title"] == "legacy question"
+        assert marker.exists()
+        restarted = webchat_store.WebChatConversationStore()
+        await restarted.ensure_ready()
+        assert await restarted.get_conversation(conv_id) == cached
+        await restarted.stop()
+    finally:
+        await store.stop()

From e7bdec5374c604acd7bb4754ae7bcbea653bbd47 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Wed, 7 Oct 2026 11:50:47 +0800
Subject: [PATCH 101/121] fix(chat): settle pending uploads when saving
 settings

---
 apps/undefined-chat/README.md                 |   1 +
 apps/undefined-chat/src/App.test.tsx          |  81 +++++++++++
 apps/undefined-chat/src/chat-store/store.ts   |  16 +++
 .../src/chat-store/upload-suspension.test.ts  | 130 ++++++++++++++++++
 docs/undefined-chat.md                        |   2 +
 5 files changed, 230 insertions(+)
 create mode 100644 apps/undefined-chat/src/chat-store/upload-suspension.test.ts

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index d12cc735..01cbabc1 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -10,6 +10,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 消息历史：初始加载、cursor-based 加载更早消息、滚动锚点保持和长历史窗口化渲染。同一会话的重载与分页共用请求顺序保护；发送新消息、完成任务刷新或删除会话后，迟到的旧响应不会覆盖正文、游标或加载状态。
 - 消息渲染：Markdown、表格、任务列表、引用块、代码高亮、代码块复制；未知语言或高亮失败时保留为纯文本代码，代码中的 HTML 不会插入正文。正文 HTML 经 sanitize 内联渲染，HTML 代码块可在独立预览窗口中运行。
 - 附件：系统文件选择器、上传状态队列、Tauri 流式上传、下载和预览。当前显示上传中/成功/失败状态，不显示百分比进度。
+- 保存连接配置会把尚未完成的附件上传转为失败状态，恢复连接后可移除并重新选择文件；旧上传结果不能恢复已移除条目。同一 Runtime 已上传成功的附件保留，切换 Runtime 清理旧附件。
 - 图片：正文 `<attachment uid/>` 内联图、附件缩略图、blob 缓存、全屏查看、缩放、旋转和可滚动查看区域。LRU 目标缓存 60 张；挂载中的图片和已打开的大图持有 blob 引用，超过目标时只淘汰无人使用的项，关闭或卸载消费者后再释放多余缓存。
 - 命令：斜杠命令、子命令提示、方向键导航、Tab/Enter 补全；空态反馈（加载中/无匹配/不可用）；窗口聚焦按 TTL 刷新命令列表。
 - 引用：引用 bot 消息、划词引用选中文本、发送引用、引用芯片跳转当前已加载源消息；源消息不在当前页时会自动加载一页更早历史，仍未命中需手动继续加载更早历史。
diff --git a/apps/undefined-chat/src/App.test.tsx b/apps/undefined-chat/src/App.test.tsx
index 799a9ffd..069f88ab 100644
--- a/apps/undefined-chat/src/App.test.tsx
+++ b/apps/undefined-chat/src/App.test.tsx
@@ -14,6 +14,7 @@ import { App } from "./App";
 import { LanguageProvider, LOCALE_STORAGE_KEY } from "./i18n";
 import { createTauriRuntimeClient } from "./runtime-client/tauri";
 import type {
+	Attachment,
 	AttachmentPreviewResult,
 	RuntimeConfig,
 } from "./runtime-client/types";
@@ -573,6 +574,86 @@ describe("App", () => {
 		});
 	});
 
+	test.each(["success", "failure"])(
+		"same-URL settings turn in-flight attachments into removable errors after late %s",
+		async (outcome) => {
+			let resolveUpload!: (value: Attachment) => void;
+			let rejectUpload!: (reason: Error) => void;
+			const pendingUpload = new Promise<Attachment>((resolve, reject) => {
+				resolveUpload = resolve;
+				rejectUpload = reject;
+			});
+			let config: RuntimeConfig = {
+				runtimeUrl: "http://same-runtime.test",
+				hasApiKey: true,
+			};
+			const attachment: Attachment = {
+				id: "file-A",
+				name: "A.txt",
+				size: 4,
+				kind: "file",
+				mediaType: "text/plain",
+				downloadUrl: "/attachment/file-A",
+				previewUrl: null,
+				discarded: false,
+			};
+			const client = runtimeClientStub({
+				getRuntimeConfig: vi.fn(async () => config),
+				saveRuntimeConfig: vi.fn(
+					async (runtimeUrl) => (config = { ...config, runtimeUrl }),
+				),
+				uploadAttachment: vi
+					.fn()
+					.mockImplementationOnce(() => pendingUpload)
+					.mockResolvedValue({ ...attachment, id: "reselected" }),
+			});
+			vi.mocked(createTauriRuntimeClient).mockReturnValue(client);
+			vi.mocked(open).mockResolvedValue("/isolated/A.txt");
+			renderApp();
+			await screen.findByLabelText("消息输入");
+			await userEvent.click(screen.getByRole("button", { name: "添加附件" }));
+			await waitFor(() =>
+				expect(client.uploadAttachment).toHaveBeenCalledTimes(1),
+			);
+			fireEvent.keyDown(window, { key: ",", ctrlKey: true });
+			await screen.findByLabelText("Runtime URL");
+			await userEvent.click(screen.getByRole("button", { name: "保存并连接" }));
+			await waitFor(() =>
+				expect(screen.queryByLabelText("Runtime URL")).toBeNull(),
+			);
+			await act(async () => {
+				if (outcome === "success") resolveUpload(attachment);
+				else rejectUpload(new Error("obsolete upload failure"));
+				await Promise.resolve();
+			});
+			await userEvent.type(screen.getByLabelText("消息输入"), "after-settings");
+			fireEvent.keyDown(screen.getByLabelText("消息输入"), { key: "Enter" });
+			expect(await screen.findByText("请先移除上传失败的附件")).toBeTruthy();
+			expect(client.sendMessage).not.toHaveBeenCalled();
+			await userEvent.click(screen.getByRole("button", { name: "移除 A.txt" }));
+			await userEvent.click(screen.getByRole("button", { name: "添加附件" }));
+			await waitFor(() =>
+				expect(client.uploadAttachment).toHaveBeenCalledTimes(2),
+			);
+			await waitFor(() =>
+				expect(
+					screen.getByRole("list", { name: "附件队列" }).textContent,
+				).toContain("4 B"),
+			);
+			fireEvent.keyDown(screen.getByLabelText("消息输入"), { key: "Enter" });
+			await waitFor(() =>
+				expect(client.sendMessage).toHaveBeenCalledWith({
+					conversationId: "default",
+					message: {
+						text: "after-settings",
+						attachmentIds: ["reselected"],
+						references: [],
+					},
+				}),
+			);
+		},
+	);
+
 	test("ignores a file picker opened on the previous Runtime", async () => {
 		let resolvePicker!: (path: string) => void;
 		vi.mocked(open).mockImplementationOnce(
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 4cf951c1..72db683b 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -843,6 +843,22 @@ export function createChatStore({
 			runtimeConfig,
 			bootstrapping: false,
 			connectionState: "disconnected",
+			attachmentsByConversation: Object.fromEntries(
+				Object.entries(state.attachmentsByConversation).map(
+					([conversationId, attachments]) => [
+						conversationId,
+						attachments.map((item) =>
+							["queued", "uploading"].includes(item.status)
+								? {
+										...item,
+										status: "error" as const,
+										error: "error.attachmentsFailed",
+									}
+								: item,
+						),
+					],
+				),
+			),
 		};
 		emit();
 	}
diff --git a/apps/undefined-chat/src/chat-store/upload-suspension.test.ts b/apps/undefined-chat/src/chat-store/upload-suspension.test.ts
new file mode 100644
index 00000000..4728679f
--- /dev/null
+++ b/apps/undefined-chat/src/chat-store/upload-suspension.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, test, vi } from "vitest";
+import type { Attachment, RuntimeConfig } from "../runtime-client/types";
+import { runtimeClientStub } from "../test-fixtures";
+import { createChatStore } from "./store";
+
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	let reject!: (reason: Error) => void;
+	const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+		resolve = resolvePromise;
+		reject = rejectPromise;
+	});
+	return { promise, resolve, reject };
+}
+
+const uploaded: Attachment = {
+	id: "file-A",
+	name: "A.txt",
+	size: 4,
+	kind: "file",
+	mediaType: "text/plain",
+	downloadUrl: "/attachment/file-A",
+	previewUrl: null,
+	discarded: false,
+};
+
+describe("attachment uploads across connection settings suspension", () => {
+	test.each(["success", "failure"])(
+		"settles late %s uploads according to the connection boundary",
+		async (outcome) => {
+			for (const boundary of [
+				"resume",
+				"same",
+				"different",
+				"completed",
+			] as const) {
+				let config: RuntimeConfig = {
+					runtimeUrl: "http://runtime-a.test",
+					hasApiKey: true,
+				};
+				const pending = deferred<Attachment>();
+				const client = runtimeClientStub({
+					getRuntimeConfig: vi.fn(async () => config),
+					uploadAttachment: vi.fn(async () => pending.promise),
+				});
+				const store = createChatStore({ client });
+				await store.bootstrap();
+				const uploading = store.addAttachmentPath("default", "/isolated/A.txt");
+				const finish = () =>
+					outcome === "success"
+						? pending.resolve(uploaded)
+						: pending.reject(new Error("upload-failed"));
+				if (boundary === "completed") {
+					finish();
+					await uploading;
+				}
+				if (boundary !== "resume") store.suspendRuntime();
+				if (boundary === "different")
+					config = { ...config, runtimeUrl: "http://runtime-b.test" };
+				await store.bootstrap({ resuming: true, resumeSuspended: true });
+				if (boundary !== "completed") {
+					finish();
+					await uploading;
+				}
+				const queue =
+					store.getSnapshot().attachmentsByConversation.default ?? [];
+				expect(queue.map((item) => item.status)).toEqual(
+					boundary === "different"
+						? []
+						: [
+								boundary === "same"
+									? "error"
+									: outcome === "success"
+										? "ready"
+										: "error",
+							],
+				);
+				if (boundary === "same") {
+					expect(queue[0].error).toBe("error.attachmentsFailed");
+					store.updateDraft("default", "send");
+					await store.sendSelectedMessage();
+					expect(store.getSnapshot().sendError).toBe("error.attachmentsFailed");
+					expect(client.sendMessage).not.toHaveBeenCalled();
+				}
+			}
+		},
+	);
+
+	test.each(["success", "failure"])(
+		"removed uploads cannot reappear after late %s responses",
+		async (outcome) => {
+			for (const suspended of [false, true]) {
+				const pending = deferred<Attachment>();
+				const client = runtimeClientStub({
+					uploadAttachment: vi
+						.fn()
+						.mockImplementationOnce(() => pending.promise)
+						.mockResolvedValue({ ...uploaded, id: "reselected" }),
+				});
+				const store = createChatStore({ client });
+				await store.bootstrap();
+				const old = store.addAttachmentPath("default", "/isolated/A.txt");
+				if (suspended) store.suspendRuntime();
+				const id = store.getSnapshot().attachmentsByConversation.default[0].id;
+				store.clearAttachment("default", id);
+				if (suspended) await store.bootstrap({ resumeSuspended: true });
+				await store.addAttachmentPath("default", "/isolated/A.txt");
+				if (outcome === "success") pending.resolve(uploaded);
+				else pending.reject(new Error("obsolete upload failure"));
+				await old;
+				expect(
+					store.getSnapshot().attachmentsByConversation.default,
+				).toHaveLength(1);
+				expect(
+					store.getSnapshot().attachmentsByConversation.default[0].attachmentId,
+				).toBe("reselected");
+				store.updateDraft("default", "send-after-reselect");
+				await store.sendSelectedMessage();
+				expect(client.sendMessage).toHaveBeenCalledWith({
+					conversationId: "default",
+					message: {
+						text: "send-after-reselect",
+						attachmentIds: ["reselected"],
+						references: [],
+					},
+				});
+			}
+		},
+	);
+});
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 93298cd8..8f11452a 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -88,6 +88,8 @@ API Key 不应暴露给 React 状态树或日志。Tauri 负责保存、读取
 
 附件上传由 Tauri 从文件句柄流式读取并转发到 Runtime，React 只持有文件选择结果和上传状态。桌面路径和 `file://` URL 会做 regular file 校验；Android `content://` URI 交给 `tauri-plugin-fs` 打开，不强制使用本地 `metadata().is_file()` 判定。
 
+保存连接配置时，未完成的附件上传会转为失败状态；恢复连接后可移除并重新选择文件。同一 Runtime 已上传成功的附件保留，旧上传的成功或失败响应不会恢复已移除条目。普通同地址重连或 Android 恢复不暂停配置，正在上传的附件仍可正常结算；切换 Runtime 继续清理旧附件。
+
 下载和预览同样通过 Tauri 受控命令处理。下载以原子创建方式占用文件名，同名文件依次添加数字后缀，并发下载也不会覆盖已有文件；可用候选名耗尽时明确报错。图片附件通过 `AttachmentImage` 或附件预览按钮调用 `previewAttachment`，Rust 端带 auth 拉取附件字节，再转为 `Blob` URL 渲染；全屏预览走应用内 `ImageViewerModal`，关闭时释放临时 URL。
 
 历史时间线未接入全局图片查看回调时使用本地 `ImagePreview`。可从图片通过 Enter / Space 打开，焦点进入关闭按钮，Tab / Shift+Tab 保持在预览内；Escape、点击遮罩或关闭按钮均可关闭，焦点恢复到触发图片。

From 5d6fe1d7c4fe76600d6f7994264f7209d93483e6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:09:28 +0800
Subject: [PATCH 102/121] fix(weixin): preserve acknowledged sends when history
 fails

---
 docs/wechat-ilink.md                          |   2 +
 .../skills/toolsets/messages/README.md        |   1 +
 src/Undefined/utils/sender.py                 | 263 ++++++++++--------
 tests/test_sender.py                          |  68 +++++
 tests/test_weixin_delivery.py                 |  18 +-
 5 files changed, 227 insertions(+), 125 deletions(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index bf146b2d..73f662e8 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -116,6 +116,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 每次文本、文件、语音或多项目批次收到发送确认后，都会立即标记当前轮已经输出；这个标记不依赖历史记录开关。后续批次失败时，前面已经确认发送的事实仍会保留，`end` 不会将整轮误判为没有输出。
 
+已收到成功 ACK 后，历史写入或发送后附件登记失败只记录日志，保留实际发送结果，避免业务层把它当作投递失败而补发。任务取消仍正常传播。
+
 消息请求进入 SDK 的 `sendmessage` 派发阶段后，网络超时或非明确拒绝会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败不会被误标为已投递；明确结构拒绝仍可安全回退。
 
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
diff --git a/src/Undefined/skills/toolsets/messages/README.md b/src/Undefined/skills/toolsets/messages/README.md
index 9f7af9a3..36bc397d 100644
--- a/src/Undefined/skills/toolsets/messages/README.md
+++ b/src/Undefined/skills/toolsets/messages/README.md
@@ -18,6 +18,7 @@
 - 文件准备失败不会计作已发送或触发文件消息段回退。协议端不支持 Stream 时返回包含 `onebot.file_send_mode` 切换方法的说明，工具不得自动换模式或重试。Stream 不支持空文件；URL 模式需要协议端访问已启动的 Runtime。
 - Stream／URL 的准备、实际发送和明确失败后的文件消息段回退共用 8 分钟，临时文件保留 16 分钟；URL 副本不会因工具删除源文件而失效。Stream 按块上传，但不保证上游合并及附件登记的整条链路固定内存占用。
 - 消息只包含普通附件标签时会直接派发文件，不会先向 OneBot/微信发送空正文；独立文件发送负责写入历史
+- 微信文本、文件、语音和合并转发收到成功 ACK 后，历史记录或附件登记失败只记录日志，不改变已发送结果，避免上层误判并重复投递；任务取消仍正常传播。
 - OneBot 在文本、附件或语音发送阶段超时时，工具会把结果标记为“未确认但按已投递处理”，禁止 AI 自动重试；私聊不会再尝试群临时会话或其他共享群，只有用户后续明确要求重发时才再次发送。`mark_sent=false` 的后台播报仍保留防重记录，但不会计作本轮用户回复
 - 多文件工程、需要执行命令验证或打包交付，优先使用 `code_delivery_agent`
 - `messages.send_text_file` 默认单文件大小上限为 `512KB`，可通过 `config.toml` 的 `[messages].send_text_file_max_size_kb` 调整
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index 5301d257..99188283 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -1,6 +1,8 @@
 """消息发送管理"""
 
 import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
 from dataclasses import dataclass, replace
 from pathlib import Path
 import time
@@ -65,6 +67,15 @@ class WeixinReplyTargetError(ValueError):
     """Raised when a quoted target is outside the current WeChat route."""
 
 
+@contextmanager
+def _weixin_history_guard(user_id: int) -> Iterator[None]:
+    """ACK 后的历史副作用失败不能被上层当作投递失败并触发重发。"""
+    try:
+        yield
+    except Exception:
+        logger.exception("[历史记录] 记录微信发送失败: user=%s", user_id)
+
+
 def _extract_message_id(result: object) -> int | None:
     if not isinstance(result, dict):
         return None
@@ -537,35 +548,38 @@ async def send_address_file(
         sent_at_ms = time.time_ns() // 1_000_000
         if not auto_history:
             return
-        file_name = name or Path(file_path).name
-        file_size = await _get_file_size(file_path)
-        history_attachments = await self.register_sent_file_attachment(
-            "private",
-            address.target_id,
-            file_path,
-            file_name,
-            kind=(history_attachment.kind if history_attachment else kind or "file"),
-            source_attachment=history_attachment,
-        )
-        history_content = _append_attachment_refs(
-            _build_file_history_message(file_name, file_size),
-            history_attachments,
-        )
-        await self.history_manager.add_private_message(
-            user_id=address.target_id,
-            text_content=history_content,
-            display_name="Bot",
-            user_name="Bot",
-            attachments=history_attachments,
-            message_id=sent_message_id,
-            transport={
-                "channel": "wechat",
-                "address": address.canonical,
-                "direction": "outbound",
-                "message_ids": [sent_message_id],
-                "sent_at_ms": sent_at_ms,
-            },
-        )
+        with _weixin_history_guard(address.target_id):
+            file_name = name or Path(file_path).name
+            file_size = await _get_file_size(file_path)
+            history_attachments = await self.register_sent_file_attachment(
+                "private",
+                address.target_id,
+                file_path,
+                file_name,
+                kind=(
+                    history_attachment.kind if history_attachment else kind or "file"
+                ),
+                source_attachment=history_attachment,
+            )
+            history_content = _append_attachment_refs(
+                _build_file_history_message(file_name, file_size),
+                history_attachments,
+            )
+            await self.history_manager.add_private_message(
+                user_id=address.target_id,
+                text_content=history_content,
+                display_name="Bot",
+                user_name="Bot",
+                attachments=history_attachments,
+                message_id=sent_message_id,
+                transport={
+                    "channel": "wechat",
+                    "address": address.canonical,
+                    "direction": "outbound",
+                    "message_ids": [sent_message_id],
+                    "sent_at_ms": sent_at_ms,
+                },
+            )
 
     async def send_address_voice(
         self,
@@ -653,36 +667,37 @@ async def _send_weixin_prepared_voice(
         mark_message_sent_this_turn()
         if not auto_history:
             return sent_message_id
-        sent_at_ms = time.time_ns() // 1_000_000
-        file_name = name or path.name
-        file_size = await _get_file_size(path)
-        history_attachments = await self.register_sent_file_attachment(
-            "private",
-            address.target_id,
-            str(path),
-            file_name,
-            kind="record",
-            source_attachment=history_attachment,
-        )
-        history_content = _append_attachment_refs(
-            f"[语音] {file_name} ({_format_size(file_size)})",
-            history_attachments,
-        )
-        await self.history_manager.add_private_message(
-            user_id=address.target_id,
-            text_content=history_content,
-            display_name="Bot",
-            user_name="Bot",
-            attachments=history_attachments,
-            message_id=sent_message_id,
-            transport={
-                "channel": "wechat",
-                "address": address.canonical,
-                "direction": "outbound",
-                "message_ids": [sent_message_id],
-                "sent_at_ms": sent_at_ms,
-            },
-        )
+        with _weixin_history_guard(address.target_id):
+            sent_at_ms = time.time_ns() // 1_000_000
+            file_name = name or path.name
+            file_size = await _get_file_size(path)
+            history_attachments = await self.register_sent_file_attachment(
+                "private",
+                address.target_id,
+                str(path),
+                file_name,
+                kind="record",
+                source_attachment=history_attachment,
+            )
+            history_content = _append_attachment_refs(
+                f"[语音] {file_name} ({_format_size(file_size)})",
+                history_attachments,
+            )
+            await self.history_manager.add_private_message(
+                user_id=address.target_id,
+                text_content=history_content,
+                display_name="Bot",
+                user_name="Bot",
+                attachments=history_attachments,
+                message_id=sent_message_id,
+                transport={
+                    "channel": "wechat",
+                    "address": address.canonical,
+                    "direction": "outbound",
+                    "message_ids": [sent_message_id],
+                    "sent_at_ms": sent_at_ms,
+                },
+            )
         return sent_message_id
 
     async def set_address_typing(self, address: DeliveryAddress, typing: bool) -> None:
@@ -852,43 +867,44 @@ async def send_media_unit(
             raise ValueError("微信消息中没有可投递的文本或本地媒体")
 
         if auto_history:
-            history_attachments = _merge_attachment_refs(
-                attachments,
-                await self._register_local_segment_attachments(
-                    "private",
-                    user_id,
-                    segments,
-                ),
-            )
-            history_content = history_message
-            if history_content is None:
-                history_content = text
-            history_content = _append_attachment_refs(
-                history_content,
-                history_attachments,
-            )
-            transport: dict[str, Any] = {
-                "channel": "wechat",
-                "address": f"wechat:{user_id}",
-                "direction": "outbound",
-            }
-            if first_sent_at_ms is not None:
-                transport["sent_at_ms"] = first_sent_at_ms
-            if sent_ids:
-                transport["message_ids"] = list(sent_ids)
-            if reply_to is not None:
-                transport["reply_to"] = str(reply_to)
-                transport["reply_mode"] = reply_mode
-            await self.history_manager.add_private_message(
-                user_id=user_id,
-                text_content=history_content,
-                display_name="Bot",
-                user_name="Bot",
-                message_id=(sent_ids[0] if sent_ids else None),
-                attachments=history_attachments,
-                transport=transport,
-                reply_context=reply_context,
-            )
+            with _weixin_history_guard(user_id):
+                history_attachments = _merge_attachment_refs(
+                    attachments,
+                    await self._register_local_segment_attachments(
+                        "private",
+                        user_id,
+                        segments,
+                    ),
+                )
+                history_content = history_message
+                if history_content is None:
+                    history_content = text
+                history_content = _append_attachment_refs(
+                    history_content,
+                    history_attachments,
+                )
+                transport: dict[str, Any] = {
+                    "channel": "wechat",
+                    "address": f"wechat:{user_id}",
+                    "direction": "outbound",
+                }
+                if first_sent_at_ms is not None:
+                    transport["sent_at_ms"] = first_sent_at_ms
+                if sent_ids:
+                    transport["message_ids"] = list(sent_ids)
+                if reply_to is not None:
+                    transport["reply_to"] = str(reply_to)
+                    transport["reply_mode"] = reply_mode
+                await self.history_manager.add_private_message(
+                    user_id=user_id,
+                    text_content=history_content,
+                    display_name="Bot",
+                    user_name="Bot",
+                    message_id=(sent_ids[0] if sent_ids else None),
+                    attachments=history_attachments,
+                    transport=transport,
+                    reply_context=reply_context,
+                )
         return sent_ids[0] if sent_ids else None
 
     async def _resolve_weixin_reply_context(
@@ -1835,34 +1851,35 @@ async def send_private_forward_message(
         sent_message_ids = await self._send_weixin_forward(messages)
         sent_at_ms = time.time_ns() // 1_000_000
         if auto_history:
-            history_attachments = (
-                await self._sender._register_local_segment_attachments(
-                    "private",
-                    user_id,
-                    _iter_segments_deep(messages),
+            with _weixin_history_guard(user_id):
+                history_attachments = (
+                    await self._sender._register_local_segment_attachments(
+                        "private",
+                        user_id,
+                        _iter_segments_deep(messages),
+                    )
+                )
+                history_content = _append_attachment_refs(
+                    history_message,
+                    history_attachments,
+                )
+                transport: dict[str, Any] = {
+                    "channel": "wechat",
+                    "address": self._address.canonical,
+                    "direction": "outbound",
+                    "sent_at_ms": sent_at_ms,
+                }
+                if sent_message_ids:
+                    transport["message_ids"] = sent_message_ids
+                await self._sender.history_manager.add_private_message(
+                    user_id=user_id,
+                    text_content=history_content,
+                    display_name="Bot",
+                    user_name="Bot",
+                    message_id=(sent_message_ids[0] if sent_message_ids else None),
+                    attachments=history_attachments,
+                    transport=transport,
                 )
-            )
-            history_content = _append_attachment_refs(
-                history_message,
-                history_attachments,
-            )
-            transport: dict[str, Any] = {
-                "channel": "wechat",
-                "address": self._address.canonical,
-                "direction": "outbound",
-                "sent_at_ms": sent_at_ms,
-            }
-            if sent_message_ids:
-                transport["message_ids"] = sent_message_ids
-            await self._sender.history_manager.add_private_message(
-                user_id=user_id,
-                text_content=history_content,
-                display_name="Bot",
-                user_name="Bot",
-                message_id=(sent_message_ids[0] if sent_message_ids else None),
-                attachments=history_attachments,
-                transport=transport,
-            )
 
     async def _send_weixin_forward(
         self,
diff --git a/tests/test_sender.py b/tests/test_sender.py
index de748328..0d2992b1 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import logging
 import nturl2path
 from collections.abc import Sequence
@@ -1306,6 +1307,73 @@ async def test_wechat_media_failure_does_not_mark_turn(
         assert ctx.get_resource("message_sent_this_turn") is None
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", ["text", "file", "voice", "forward"])
+@pytest.mark.parametrize("cancelled", [False, True])
+async def test_wechat_ack_survives_history_failure_without_swallowing_cancel(
+    sender: MessageSender,
+    tmp_path: Path,
+    caplog: pytest.LogCaptureFixture,
+    kind: str,
+    cancelled: bool,
+) -> None:
+    source = tmp_path / "report.wav"
+    await async_io.write_bytes(source, b"isolated media")
+    service = SimpleNamespace(
+        send_text=AsyncMock(return_value="text-ack"),
+        send_file=AsyncMock(return_value="file-ack"),
+        prepare_voice=AsyncMock(
+            return_value=PreparedWeixinVoice(content=b"silk", duration_ms=200)
+        ),
+        send_prepared_voice=AsyncMock(return_value="voice-ack"),
+        send_items=AsyncMock(return_value="forward-ack"),
+    )
+    weixin_config = cast(Any, sender.config.weixin)
+    weixin_config.multi_item_messages_enabled = True
+    weixin_config.multi_item_max_items = 10
+    weixin_config.media_max_size_mb = 100
+    sender.set_weixin_service(service)
+    history = cast(AsyncMock, sender.history_manager.add_private_message)
+    history.side_effect = (
+        asyncio.CancelledError() if cancelled else OSError("history unavailable")
+    )
+    address = DeliveryAddress("wechat", 12345)
+
+    async def send() -> None:
+        if kind == "text":
+            assert await sender.send_address_message(address, "hello") == "text-ack"
+        elif kind == "forward":
+            await AddressBoundSender(sender, address).send_private_forward_message(
+                address.target_id,
+                [{"type": "node", "data": {"name": "Bot", "content": "hello"}}],
+                history_message="hello",
+            )
+        else:
+            await sender.send_address_file(address, str(source), kind=kind)
+
+    async with RequestContext("private", user_id=address.target_id) as ctx:
+        if cancelled:
+            with pytest.raises(asyncio.CancelledError):
+                await send()
+        else:
+            await send()
+            assert "记录微信发送失败" in caplog.text
+        assert ctx.get_resource("message_sent_this_turn") is True
+    history.assert_awaited_once()
+    assert (
+        sum(
+            method.await_count
+            for method in (
+                service.send_text,
+                service.send_file,
+                service.send_prepared_voice,
+                service.send_items,
+            )
+        )
+        == 1
+    )
+
+
 @pytest.mark.asyncio
 async def test_send_wechat_file_enforces_private_access_control(
     sender: MessageSender,
diff --git a/tests/test_weixin_delivery.py b/tests/test_weixin_delivery.py
index 54d1a692..0e78e949 100644
--- a/tests/test_weixin_delivery.py
+++ b/tests/test_weixin_delivery.py
@@ -31,7 +31,9 @@
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("response", ["timeout", "server_error", "rejection"])
+@pytest.mark.parametrize(
+    "response", ["timeout", "server_error", "rejection", "history_error"]
+)
 async def test_sdk_dispatch_error_controls_jm_fallback(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -43,6 +45,8 @@ def handle(request: httpx.Request) -> httpx.Response:
         message = json.loads(request.content)["msg"]
         requests.append(message)
         if len(requests) == 1:
+            if response == "history_error":
+                return httpx.Response(200, json={"ret": 0}, request=request)
             if response == "timeout":
                 raise httpx.ReadTimeout("response lost after POST", request=request)
             if response == "server_error":
@@ -62,6 +66,13 @@ def handle(request: httpx.Request) -> httpx.Response:
     )
     history = MagicMock()
     history.add_private_message = AsyncMock()
+    if response == "history_error":
+        history.add_private_message.side_effect = [
+            OSError("isolated history write failure after ACK"),
+            None,
+            None,
+            None,
+        ]
     sender_config = MagicMock()
     sender_config.is_private_allowed.return_value = True
     sender_config.weixin.multi_item_messages_enabled = True
@@ -103,7 +114,10 @@ def handle(request: httpx.Request) -> httpx.Response:
         )
     zip_send.assert_awaited_once()
     await service.stop()
-    if response == "rejection":
+    if response == "history_error":
+        assert [len(message["item_list"]) for message in requests] == [2]
+        assert "已发送合并转发" in status
+    elif response == "rejection":
         assert [len(message["item_list"]) for message in requests] == [2, 1, 1]
         assert "已发送合并转发" in status
     else:

From ba61847f92194d3c678c097dbe2db9e09e13293a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:12:28 +0800
Subject: [PATCH 103/121] fix(automations): preserve concurrent outputs across
 nested loops

---
 docs/automations.md                   |   2 +-
 src/Undefined/automations/runner.py   |  25 ++++--
 tests/test_automation_loop_outputs.py | 116 ++++++++++++++++++++++++++
 3 files changed, 133 insertions(+), 10 deletions(-)
 create mode 100644 tests/test_automation_loop_outputs.py

diff --git a/docs/automations.md b/docs/automations.md
index aa32def6..68deebc1 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -79,7 +79,7 @@
 
 工具节点的 `args` 是 JSON 对象；WebUI 检查器按 JSON 值编辑每个参数，因此数字、布尔值、数组、对象、`null` 与字符串会保留原类型（字符串可写成 JSON 字符串，无法解析为 JSON 的输入也按字符串保存）。`llm.blank.tools` 中的名称先按注册表名称精确匹配，包括 `send_message` 这类裸兼容别名；仅当精确名称不存在时，短名称才按 basename 做唯一无歧义解析。带命名空间的完整名称不会退化为 basename 匹配。
 
-执行规则一句话版：有依赖就等待——普通并行汇合会等所有有效上游完成；条件分支只激活选中路径，未选路径会传播为“跳过”，所以互斥 case 可以直接或在下游安全汇合。无依赖的节点一旦就绪就立即并行执行。循环的 `index` / `item` 是每个循环、每次迭代的局部上下文，嵌套或并行循环不会互相覆盖。LLM 与模板节点默认只产出内容不发消息，勾选 `emit` 后才会发送（消息触发发到当前会话，时间触发发到任务地址）。任一节点失败则整图停止；只有从旧定时任务迁移出的图保留“工具失败后继续”的历史兼容行为。
+执行规则一句话版：有依赖就等待——普通并行汇合会等所有有效上游完成；条件分支只激活选中路径，未选路径会传播为“跳过”，所以互斥 case 可以直接或在下游安全汇合。无依赖的节点一旦就绪就立即并行执行。循环的 `index` / `item` 是每个循环、每次迭代的局部上下文，嵌套或并行循环不会互相覆盖。循环结束仅回写本轮新增或更新的输出，不会用进入循环时的旧快照覆盖并行分支已经发布的结果。LLM 与模板节点默认只产出内容不发消息，勾选 `emit` 后才会发送（消息触发发到当前会话，时间触发发到任务地址）。任一节点失败则整图停止；只有从旧定时任务迁移出的图保留“工具失败后继续”的历史兼容行为。
 
 ## 变量系统
 
diff --git a/src/Undefined/automations/runner.py b/src/Undefined/automations/runner.py
index e4036c24..351d291e 100644
--- a/src/Undefined/automations/runner.py
+++ b/src/Undefined/automations/runner.py
@@ -214,11 +214,16 @@ def _parse_each_source(raw: str) -> list[Any]:
     return [line for line in text.splitlines() if line.strip()]
 
 
-def _merge_scoped_variables(target: dict[str, Any], scoped: dict[str, Any]) -> None:
-    """Propagate workflow outputs without leaking loop-local index/item values."""
-    for key, value in scoped.items():
-        if key not in {"index", "item"}:
-            target[key] = value
+def _scoped_variable_updates(
+    previous: dict[str, Any], scoped: dict[str, Any]
+) -> dict[str, Any]:
+    """Publish only this iteration's changes, preserving concurrent sibling output."""
+    return {
+        key: value
+        for key, value in scoped.items()
+        if key not in {"index", "item"}
+        and (key not in previous or value != previous[key])
+    }
 
 
 _OPTION_ID_RE = re.compile(r"[^A-Za-z0-9_]+")
@@ -1051,8 +1056,9 @@ async def _run_loop_times(
                 include_bodies=True,
                 only_ids=body,
             )
-            _merge_scoped_variables(loop_variables, iteration_variables)
-            _merge_scoped_variables(variables, iteration_variables)
+            updates = _scoped_variable_updates(loop_variables, iteration_variables)
+            loop_variables.update(updates)
+            variables.update(updates)
         return last
 
     async def _run_loop_each(
@@ -1093,6 +1099,7 @@ async def _run_loop_each(
                 include_bodies=True,
                 only_ids=body,
             )
-            _merge_scoped_variables(loop_variables, iteration_variables)
-            _merge_scoped_variables(variables, iteration_variables)
+            updates = _scoped_variable_updates(loop_variables, iteration_variables)
+            loop_variables.update(updates)
+            variables.update(updates)
         return last
diff --git a/tests/test_automation_loop_outputs.py b/tests/test_automation_loop_outputs.py
new file mode 100644
index 00000000..a11253c6
--- /dev/null
+++ b/tests/test_automation_loop_outputs.py
@@ -0,0 +1,116 @@
+"""Parallel loop scopes must not publish stale copies of sibling outputs."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+
+from Undefined.automations.match import AutomationEvent
+from Undefined.automations.runner import WorkflowRunner
+from Undefined.automations.validate import validate_automation
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("inner_type", ["loop.times", "loop.each"])
+async def test_nested_loop_preserves_concurrently_published_sibling_outputs(
+    inner_type: str,
+) -> None:
+    entered = [asyncio.Event(), asyncio.Event()]
+    release = [asyncio.Event(), asyncio.Event()]
+    inner_calls = 0
+    observed: list[str] = []
+
+    async def execute_tool(
+        name: str, args: dict[str, Any], context: dict[str, Any]
+    ) -> str:
+        nonlocal inner_calls
+        if name == "inner_body":
+            iteration = inner_calls
+            inner_calls += 1
+            entered[iteration].set()
+            await release[iteration].wait()
+            return "inner"
+        iteration = int(args["index"])
+        if name == "producer":
+            await entered[iteration].wait()
+            return str(iteration)
+        if name == "signal":
+            release[iteration].set()
+            return ""
+        observed.append(str(args["value"]))
+        return ""
+
+    runner = WorkflowRunner(
+        execute_tool=execute_tool,
+        ask_main=AsyncMock(return_value=""),
+        submit_llm=AsyncMock(return_value={"choices": []}),
+        send_message=AsyncMock(),
+        get_openai_tools=lambda: [],
+        agent_config=SimpleNamespace(max_tokens=16),
+        tool_context={},
+    )
+    task: dict[str, Any] = {
+        "auto_send_final": False,
+        "nodes": [
+            {"id": "start", "type": "start", "kind": "cron", "cron": "0 9 * * *"},
+            {
+                "id": "outer",
+                "type": "loop.times",
+                "count": 2,
+                "body": ["producer", "signal", "inner", "join"],
+            },
+            {
+                "id": "producer",
+                "type": "tool",
+                "tool_name": "producer",
+                "args": {"index": "{{index}}"},
+                "output_var": "produced",
+            },
+            {
+                "id": "signal",
+                "type": "tool",
+                "tool_name": "signal",
+                "args": {"index": "{{index}}"},
+            },
+            {
+                "id": "inner",
+                "type": inner_type,
+                "count": 1,
+                "source": '["one"]',
+                "body": ["inner_body"],
+            },
+            {"id": "inner_body", "type": "tool", "tool_name": "inner_body"},
+            {
+                "id": "join",
+                "type": "tool",
+                "tool_name": "join",
+                "args": {
+                    "index": "{{index}}",
+                    "value": "{{producer}}|{{nodes.producer.output}}|{{produced}}|{{vars.produced}}",
+                },
+            },
+        ],
+        "edges": [
+            {"from": "start", "to": "outer"},
+            {"from": "producer", "to": "signal"},
+            {"from": "signal", "to": "join"},
+            {"from": "inner", "to": "join"},
+        ],
+    }
+    validate_automation(task)
+    await asyncio.wait_for(
+        runner.run(
+            task,
+            event=AutomationEvent(kind="time", channel="group"),
+            pass_text="",
+            consume_mentions=(),
+            consume_stripped="",
+            mentions_all=(),
+        ),
+        timeout=2,
+    )
+    assert observed == ["0|0|0|0", "1|1|1|1"]

From c857288abfbb4cb70057a8505787bb77a2c9d33d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:14:39 +0800
Subject: [PATCH 104/121] fix(chat): clean up late Android lifecycle
 subscriptions

---
 apps/undefined-chat/README.md                  |  2 +-
 .../src/platform/AndroidLifecycle.test.ts      | 12 ++++++++++++
 .../src/platform/AndroidLifecycle.ts           | 18 +++++++++++-------
 docs/undefined-chat.md                         |  2 +-
 4 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index 01cbabc1..82b37f1f 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -33,7 +33,7 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 Android：
 
 - 文件选择器返回的 `content://` URI 通过 Tauri fs plugin 打开，上传链路仍需要真机/模拟器 smoke 覆盖。
-- 生命周期监听使用 Tauri `tauri://suspended` / `tauri://resumed` 事件；恢复前台时重新 bootstrap，接受 Runtime 的完整任务时间线与对应游标后恢复订阅；快照内已有事件不会重复追加。
+- 生命周期监听使用 Tauri `tauri://suspended` / `tauri://resumed` 事件；恢复前台时重新 bootstrap，接受 Runtime 的完整任务时间线与对应游标后恢复订阅；快照内已有事件不会重复追加。卸载或重新注册时会清理尚在异步注册中的监听，已排队的旧恢复回调不会再发起请求。
 - Android 通过生成工程注入的 `SecretPlugin` 使用 Android Keystore + AES-GCM 保存 API Key：密钥在 AndroidKeyStore 中生成且不可导出，加密后的密文存放在 `MODE_PRIVATE` 的 SharedPreferences 中。Android 生成插件已接入并有脚本/Rust 测试覆盖，真实设备仍需 smoke 验证；只有平台安全存储不可用且用户显式确认时，才允许不安全文件降级。
 
 iOS：
diff --git a/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts b/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
index 679df93b..e89d8833 100644
--- a/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
+++ b/apps/undefined-chat/src/platform/AndroidLifecycle.test.ts
@@ -76,6 +76,18 @@ describe("AndroidLifecycle", () => {
 	});
 
 	describe("setupAndroidLifecycle", () => {
+		it("cleans registrations resolved after teardown and ignores queued resume callbacks", async () => {
+			const client = runtimeClientStub();
+			const store = createChatStore({ client });
+			const cleanup = setupAndroidLifecycle(store);
+			const queuedResume = listeners.get("tauri://resumed");
+			cleanup();
+			await Promise.resolve();
+			expect(unlisten).toHaveBeenCalledTimes(2);
+			await queuedResume?.();
+			expect(client.getRuntimeConfig).not.toHaveBeenCalled();
+		});
+
 		it("reloads a completed background conversation through the real resume listener", async () => {
 			let completed = false;
 			const client = runtimeClientStub({
diff --git a/apps/undefined-chat/src/platform/AndroidLifecycle.ts b/apps/undefined-chat/src/platform/AndroidLifecycle.ts
index 0bcf2865..f20725c5 100644
--- a/apps/undefined-chat/src/platform/AndroidLifecycle.ts
+++ b/apps/undefined-chat/src/platform/AndroidLifecycle.ts
@@ -9,17 +9,21 @@ import type { ChatStore } from "../chat-store/store";
  */
 export function setupAndroidLifecycle(store: ChatStore): () => void {
 	const unlisteners: Array<() => void> = [];
+	let disposed = false;
 	const appWindow = getCurrentWindow();
+	const registerUnlistener = (unlisten: () => void): void => {
+		if (disposed) unlisten();
+		else unlisteners.push(unlisten);
+	};
 
 	// 监听应用暂停事件
 	appWindow
 		.listen<string>(TauriEvent.WINDOW_SUSPENDED, () => {
+			if (disposed) return;
 			console.log("[Lifecycle] App paused");
 			// 可以在这里保存状态或清理资源
 		})
-		.then((unlisten: () => void) => {
-			unlisteners.push(unlisten);
-		})
+		.then(registerUnlistener)
 		.catch((err: unknown) => {
 			console.error("[Lifecycle] Failed to listen android-pause:", err);
 		});
@@ -27,6 +31,7 @@ export function setupAndroidLifecycle(store: ChatStore): () => void {
 	// 监听应用恢复事件
 	appWindow
 		.listen<string>(TauriEvent.WINDOW_RESUMED, async () => {
+			if (disposed) return;
 			console.log("[Lifecycle] App resumed, re-bootstrapping...");
 
 			try {
@@ -58,16 +63,15 @@ export function setupAndroidLifecycle(store: ChatStore): () => void {
 				console.error("[Lifecycle] Failed to reconnect:", err);
 			}
 		})
-		.then((unlisten: () => void) => {
-			unlisteners.push(unlisten);
-		})
+		.then(registerUnlistener)
 		.catch((err: unknown) => {
 			console.error("[Lifecycle] Failed to listen android-resume:", err);
 		});
 
 	// 返回清理函数
 	return () => {
-		for (const unlisten of unlisteners) {
+		disposed = true;
+		for (const unlisten of unlisteners.splice(0)) {
 			unlisten();
 		}
 	};
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 8f11452a..2da6e0a2 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -119,7 +119,7 @@ HTML 采用与 WebUI 基线对齐的双层策略：
 - 会话列表抽屉、遮罩、Escape 关闭、ARIA 状态和焦点恢复。
 - `visualViewport` 驱动的 `--keyboard-inset`，用于输入区软键盘避让。
 - 安全区 `env(safe-area-inset-*)` 和移动端 44px 触控目标。
-- Android 生命周期使用 Tauri `tauri://suspended` / `tauri://resumed`。
+- Android 生命周期使用 Tauri `tauri://suspended` / `tauri://resumed`。卸载或重新注册时也会清理尚未完成的异步监听，已经释放的监听回调不会再次触发重连。
 
 真实设备或模拟器 smoke 建议覆盖：
 

From 26f0d29950172033c61668acc54e969ba18c0af1 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:16:48 +0800
Subject: [PATCH 105/121] fix(weixin): prevent replay after partial message
 delivery

---
 docs/wechat-ilink.md                          |   2 +
 .../skills/toolsets/messages/README.md        |   1 +
 src/Undefined/utils/sender.py                 | 221 ++++++++++--------
 src/Undefined/weixin/transport.py             |   2 +-
 tests/test_sender.py                          |  44 +++-
 tests/test_weixin_delivery.py                 |  41 +++-
 6 files changed, 207 insertions(+), 104 deletions(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 73f662e8..1eaa3053 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -118,6 +118,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 已收到成功 ACK 后，历史写入或发送后附件登记失败只记录日志，保留实际发送结果，避免业务层把它当作投递失败而补发。任务取消仍正常传播。
 
+长文本分片、转发分批或顺序降级中，当前批次被明确拒绝时仍可对该批次降级；如果本条消息已有分片成功，后续失败会保留部分送达状态，禁止业务层把整条消息重新发送。尚无分片成功时，仍保留明确拒绝后的正常降级。
+
 消息请求进入 SDK 的 `sendmessage` 派发阶段后，网络超时或非明确拒绝会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败不会被误标为已投递；明确结构拒绝仍可安全回退。
 
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
diff --git a/src/Undefined/skills/toolsets/messages/README.md b/src/Undefined/skills/toolsets/messages/README.md
index 36bc397d..f967ccdc 100644
--- a/src/Undefined/skills/toolsets/messages/README.md
+++ b/src/Undefined/skills/toolsets/messages/README.md
@@ -19,6 +19,7 @@
 - Stream／URL 的准备、实际发送和明确失败后的文件消息段回退共用 8 分钟，临时文件保留 16 分钟；URL 副本不会因工具删除源文件而失效。Stream 按块上传，但不保证上游合并及附件登记的整条链路固定内存占用。
 - 消息只包含普通附件标签时会直接派发文件，不会先向 OneBot/微信发送空正文；独立文件发送负责写入历史
 - 微信文本、文件、语音和合并转发收到成功 ACK 后，历史记录或附件登记失败只记录日志，不改变已发送结果，避免上层误判并重复投递；任务取消仍正常传播。
+- 微信长文本分片、转发分批或顺序降级中，只要本条消息已有分片收到 ACK，后续失败就按整体投递未完整确认处理，禁止整条自动重发；首片尚未成功时仍保留明确拒绝后的降级行为。
 - OneBot 在文本、附件或语音发送阶段超时时，工具会把结果标记为“未确认但按已投递处理”，禁止 AI 自动重试；私聊不会再尝试群临时会话或其他共享群，只有用户后续明确要求重发时才再次发送。`mark_sent=false` 的后台播报仍保留防重记录，但不会计作本轮用户回复
 - 多文件工程、需要执行命令验证或打包交付，优先使用 `code_delivery_agent`
 - `messages.send_text_file` 默认单文件大小上限为 `512KB`，可通过 `config.toml` 的 `[messages].send_text_file_max_size_kb` 调整
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index 99188283..d7433744 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -1,7 +1,7 @@
 """消息发送管理"""
 
 import logging
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from contextlib import contextmanager
 from dataclasses import dataclass, replace
 from pathlib import Path
@@ -43,6 +43,7 @@
 from Undefined.utils.paths import file_uri_path_text
 from Undefined.weixin.audio import PreparedWeixinVoice
 from Undefined.weixin.transport import (
+    WeixinDeliveryUncertainError,
     is_definitive_weixin_delivery_rejection as is_definitive_weixin_delivery_rejection,
 )
 
@@ -76,6 +77,19 @@ def _weixin_history_guard(user_id: int) -> Iterator[None]:
         logger.exception("[历史记录] 记录微信发送失败: user=%s", user_id)
 
 
+@contextmanager
+def _weixin_partial_delivery_guard(has_sent: Callable[[], bool]) -> Iterator[None]:
+    """后续分片失败时保留本条消息已部分送达的事实，禁止整条降级重发。"""
+    try:
+        yield
+    except Exception as exc:
+        if has_sent() and not getattr(exc, "delivery_uncertain", False):
+            raise WeixinDeliveryUncertainError(
+                "微信消息已部分送达，禁止整条自动重发"
+            ) from exc
+        raise
+
+
 def _extract_message_id(result: object) -> int | None:
     if not isinstance(result, dict):
         return None
@@ -794,75 +808,76 @@ async def send_media_unit(
 
         reply_mode = ""
         reference_pending = reference is not None
-        for unit in delivery_units:
-            if unit.kind == "text":
-                text_chunks = _split_text_chunks(unit.text)
+        with _weixin_partial_delivery_guard(lambda: sent_any):
+            for unit in delivery_units:
+                if unit.kind == "text":
+                    text_chunks = _split_text_chunks(unit.text)
+                    if reference_pending:
+                        assert reference is not None
+                        try:
+                            receipt = await service.send_text(
+                                user_id,
+                                text_chunks[0],
+                                reference=reference,
+                            )
+                        except Exception as exc:
+                            if not is_definitive_weixin_delivery_rejection(exc):
+                                raise
+                            logger.warning(
+                                "[微信引用] 原生引用被明确拒绝，降级为 Markdown: "
+                                "user=%s target=%s error=%s",
+                                user_id,
+                                reply_to,
+                                type(exc).__name__,
+                            )
+                            assert reply_context is not None
+                            fallback_text = format_markdown_reply(
+                                reply_context,
+                                unit.text,
+                            )
+                            for chunk in _split_text_chunks(fallback_text):
+                                record_sent(await service.send_text(user_id, chunk))
+                            reply_mode = "markdown_fallback"
+                        else:
+                            record_sent(receipt)
+                            for chunk in text_chunks[1:]:
+                                record_sent(await service.send_text(user_id, chunk))
+                            reply_mode = "native"
+                        reference_pending = False
+                    else:
+                        for chunk in text_chunks:
+                            record_sent(await service.send_text(user_id, chunk))
+                    continue
+
                 if reference_pending:
                     assert reference is not None
                     try:
-                        receipt = await service.send_text(
-                            user_id,
-                            text_chunks[0],
-                            reference=reference,
+                        receipt = await send_media_unit(
+                            unit,
+                            item_reference=reference,
                         )
                     except Exception as exc:
                         if not is_definitive_weixin_delivery_rejection(exc):
                             raise
                         logger.warning(
-                            "[微信引用] 原生引用被明确拒绝，降级为 Markdown: "
+                            "[微信引用] 原生媒体引用被明确拒绝，降级为 Markdown: "
                             "user=%s target=%s error=%s",
                             user_id,
                             reply_to,
                             type(exc).__name__,
                         )
                         assert reply_context is not None
-                        fallback_text = format_markdown_reply(
-                            reply_context,
-                            unit.text,
-                        )
+                        fallback_text = format_markdown_reply(reply_context, "")
                         for chunk in _split_text_chunks(fallback_text):
                             record_sent(await service.send_text(user_id, chunk))
+                        record_sent(await send_media_unit(unit))
                         reply_mode = "markdown_fallback"
                     else:
                         record_sent(receipt)
-                        for chunk in text_chunks[1:]:
-                            record_sent(await service.send_text(user_id, chunk))
                         reply_mode = "native"
                     reference_pending = False
                 else:
-                    for chunk in text_chunks:
-                        record_sent(await service.send_text(user_id, chunk))
-                continue
-
-            if reference_pending:
-                assert reference is not None
-                try:
-                    receipt = await send_media_unit(
-                        unit,
-                        item_reference=reference,
-                    )
-                except Exception as exc:
-                    if not is_definitive_weixin_delivery_rejection(exc):
-                        raise
-                    logger.warning(
-                        "[微信引用] 原生媒体引用被明确拒绝，降级为 Markdown: "
-                        "user=%s target=%s error=%s",
-                        user_id,
-                        reply_to,
-                        type(exc).__name__,
-                    )
-                    assert reply_context is not None
-                    fallback_text = format_markdown_reply(reply_context, "")
-                    for chunk in _split_text_chunks(fallback_text):
-                        record_sent(await service.send_text(user_id, chunk))
                     record_sent(await send_media_unit(unit))
-                    reply_mode = "markdown_fallback"
-                else:
-                    record_sent(receipt)
-                    reply_mode = "native"
-                reference_pending = False
-            else:
-                record_sent(await send_media_unit(unit))
         if not sent_any and message.strip():
             raise ValueError("微信消息中没有可投递的文本或本地媒体")
 
@@ -2042,30 +2057,35 @@ async def _send_weixin_multi_item_units(
 
         receipts: list[str] = []
         sequential_fallback = False
-        for batch in batches:
-            if sequential_fallback:
-                receipts.extend(await self._send_weixin_forward_units(batch))
-                continue
-            items = await self._weixin_outbound_items(batch)
-            try:
-                receipt = str(
-                    await service.send_items(self._address.target_id, items) or ""
-                ).strip()
-            except Exception as exc:
-                if not self._is_definitive_multi_item_rejection(exc):
-                    raise
-                logger.warning(
-                    "[微信转发] 多项消息被上游明确拒绝，回退顺序发送: "
-                    "address=%s error=%s",
-                    self._address.canonical,
-                    type(exc).__name__,
-                )
-                sequential_fallback = True
-                receipts.extend(await self._send_weixin_forward_units(batch))
-            else:
-                mark_message_sent_this_turn()
-                if receipt:
-                    receipts.append(receipt)
+        sent_any = False
+        with _weixin_partial_delivery_guard(lambda: sent_any):
+            for batch in batches:
+                if sequential_fallback:
+                    receipts.extend(await self._send_weixin_forward_units(batch))
+                    sent_any = True
+                    continue
+                items = await self._weixin_outbound_items(batch)
+                try:
+                    receipt = str(
+                        await service.send_items(self._address.target_id, items) or ""
+                    ).strip()
+                except Exception as exc:
+                    if not self._is_definitive_multi_item_rejection(exc):
+                        raise
+                    logger.warning(
+                        "[微信转发] 多项消息被上游明确拒绝，回退顺序发送: "
+                        "address=%s error=%s",
+                        self._address.canonical,
+                        type(exc).__name__,
+                    )
+                    sequential_fallback = True
+                    receipts.extend(await self._send_weixin_forward_units(batch))
+                    sent_any = True
+                else:
+                    mark_message_sent_this_turn()
+                    sent_any = True
+                    if receipt:
+                        receipts.append(receipt)
         return receipts
 
     async def _weixin_outbound_items(
@@ -2116,40 +2136,45 @@ async def _send_weixin_forward_units(
         units: list[_WeixinDeliveryUnit],
     ) -> list[str]:
         receipts: list[str] = []
-        for unit in units:
-            if unit.kind == "text":
-                for chunk in _split_text_chunks(unit.text):
-                    receipt = await self._sender.send_address_message(
+        sent_any = False
+        with _weixin_partial_delivery_guard(lambda: sent_any):
+            for unit in units:
+                if unit.kind == "text":
+                    for chunk in _split_text_chunks(unit.text):
+                        receipt = await self._sender.send_address_message(
+                            self._address,
+                            chunk,
+                            auto_history=False,
+                        )
+                        sent_any = True
+                        receipt_text = str(receipt or "").strip()
+                        if receipt_text:
+                            receipts.append(receipt_text)
+                    continue
+                if unit.path is None:
+                    raise ValueError("微信转发媒体消息缺少本地文件")
+                if unit.kind == "voice":
+                    if unit.voice is None:
+                        raise ValueError("微信转发语音尚未完成发送前编码")
+                    receipt = await self._sender._send_weixin_prepared_voice(
                         self._address,
-                        chunk,
+                        unit.path,
+                        unit.voice,
+                        name=unit.path.name,
                         auto_history=False,
                     )
-                    receipt_text = str(receipt or "").strip()
-                    if receipt_text:
-                        receipts.append(receipt_text)
-                continue
-            if unit.path is None:
-                raise ValueError("微信转发媒体消息缺少本地文件")
-            if unit.kind == "voice":
-                if unit.voice is None:
-                    raise ValueError("微信转发语音尚未完成发送前编码")
-                receipt = await self._sender._send_weixin_prepared_voice(
+                    sent_any = True
+                    if receipt:
+                        receipts.append(receipt)
+                    continue
+                await self._sender.send_address_file(
                     self._address,
-                    unit.path,
-                    unit.voice,
+                    str(unit.path),
                     name=unit.path.name,
+                    kind=unit.kind,
                     auto_history=False,
                 )
-                if receipt:
-                    receipts.append(receipt)
-                continue
-            await self._sender.send_address_file(
-                self._address,
-                str(unit.path),
-                name=unit.path.name,
-                kind=unit.kind,
-                auto_history=False,
-            )
+                sent_any = True
         return receipts
 
     @staticmethod
diff --git a/src/Undefined/weixin/transport.py b/src/Undefined/weixin/transport.py
index 54f22578..49d9322c 100644
--- a/src/Undefined/weixin/transport.py
+++ b/src/Undefined/weixin/transport.py
@@ -31,7 +31,7 @@ def is_definitive_weixin_delivery_rejection(exc: BaseException) -> bool:
 
 
 class WeixinDeliveryUncertainError(WeixinIlinkError):
-    """消息派发已发起，但上游没有给出可确认的投递结果。"""
+    """消息已开始派发，但无法确认整体投递完成。"""
 
     delivery_uncertain: bool = True
 
diff --git a/tests/test_sender.py b/tests/test_sender.py
index 0d2992b1..4a01bc41 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -43,6 +43,7 @@
 )
 from Undefined.weixin.audio import PreparedWeixinVoice
 from Undefined.weixin.service import WeixinService, WeixinServiceError
+from Undefined.weixin.transport import WeixinDeliveryUncertainError
 
 
 @pytest.fixture
@@ -2003,10 +2004,14 @@ async def test_wechat_bundle_marks_each_ack_before_later_failure(
         for text in ("first", "second")
     ]
     async with RequestContext("private", user_id=12345) as ctx:
-        with pytest.raises(RequestTimeoutError):
+        with pytest.raises(
+            WeixinDeliveryUncertainError if first_ack else RequestTimeoutError
+        ) as raised:
             await bound_sender.send_private_forward_message(
                 12345, nodes, history_message="two nodes"
             )
+        if first_ack:
+            assert raised.value.__cause__ is failure
         assert ctx.get_resource("message_sent_this_turn") is (
             True if first_ack else None
         )
@@ -2014,6 +2019,43 @@ async def test_wechat_bundle_marks_each_ack_before_later_failure(
     cast(AsyncMock, sender.history_manager.add_private_message).assert_not_awaited()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("first_ack", [False, True])
+@pytest.mark.parametrize("cancelled", [False, True])
+async def test_wechat_text_chunks_preserve_partial_ack_on_later_failure(
+    sender: MessageSender,
+    first_ack: bool,
+    cancelled: bool,
+) -> None:
+    failure = asyncio.CancelledError() if cancelled else ApiError(40001, "sendmessage")
+    service = SimpleNamespace(
+        send_text=AsyncMock(
+            side_effect=["first-ack", failure] if first_ack else failure
+        )
+    )
+    sender.set_weixin_service(service)
+    async with RequestContext("private", user_id=12345) as ctx:
+        # 先前无关消息的成功标志不能把本条首次拒绝误判成部分投递。
+        ctx.set_resource("message_sent_this_turn", True)
+        expected_error = (
+            asyncio.CancelledError
+            if cancelled
+            else WeixinDeliveryUncertainError
+            if first_ack
+            else ApiError
+        )
+        with pytest.raises(expected_error) as raised:
+            await sender.send_address_message(
+                DeliveryAddress("wechat", 12345), "x" * (MAX_MESSAGE_LENGTH + 1)
+            )
+        if first_ack and not cancelled:
+            assert raised.value.__cause__ is failure
+        else:
+            assert raised.value is failure
+    assert service.send_text.await_count == (2 if first_ack else 1)
+    cast(AsyncMock, sender.history_manager.add_private_message).assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_send_wechat_forward_falls_back_after_definitive_bundle_rejection(
     sender: MessageSender,
diff --git a/tests/test_weixin_delivery.py b/tests/test_weixin_delivery.py
index 0e78e949..f7e18ab3 100644
--- a/tests/test_weixin_delivery.py
+++ b/tests/test_weixin_delivery.py
@@ -32,7 +32,17 @@
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "response", ["timeout", "server_error", "rejection", "history_error"]
+    "response",
+    [
+        "timeout",
+        "server_error",
+        "rejection",
+        "history_error",
+        "partial_bundle_rejection",
+        "partial_sequential_rejection",
+        "partial_fallback_rejection",
+        "first_sequential_rejection",
+    ],
 )
 async def test_sdk_dispatch_error_controls_jm_fallback(
     tmp_path: Path,
@@ -44,6 +54,18 @@ async def test_sdk_dispatch_error_controls_jm_fallback(
     def handle(request: httpx.Request) -> httpx.Response:
         message = json.loads(request.content)["msg"]
         requests.append(message)
+        rejected_requests = {
+            "partial_bundle_rejection": {2, 3},
+            "partial_sequential_rejection": {2},
+            "partial_fallback_rejection": {1, 3},
+            "first_sequential_rejection": {1},
+        }.get(response)
+        if rejected_requests is not None:
+            return httpx.Response(
+                200,
+                json={"ret": 40001 if len(requests) in rejected_requests else 0},
+                request=request,
+            )
         if len(requests) == 1:
             if response == "history_error":
                 return httpx.Response(200, json={"ret": 0}, request=request)
@@ -75,8 +97,13 @@ def handle(request: httpx.Request) -> httpx.Response:
         ]
     sender_config = MagicMock()
     sender_config.is_private_allowed.return_value = True
-    sender_config.weixin.multi_item_messages_enabled = True
-    sender_config.weixin.multi_item_max_items = 10
+    sender_config.weixin.multi_item_messages_enabled = response not in {
+        "partial_sequential_rejection",
+        "first_sequential_rejection",
+    }
+    sender_config.weixin.multi_item_max_items = (
+        1 if response == "partial_bundle_rejection" else 10
+    )
     sender_config.weixin.media_max_size_mb = 100
     sender = MessageSender(MagicMock(), history, bot_qq=999, config=sender_config)
     sender.set_weixin_service(service)
@@ -114,7 +141,13 @@ def handle(request: httpx.Request) -> httpx.Response:
         )
     zip_send.assert_awaited_once()
     await service.stop()
-    if response == "history_error":
+    if response.startswith("partial_"):
+        assert len(requests) == (2 if response == "partial_sequential_rejection" else 3)
+        assert "投递结果未确认" in status
+    elif response == "first_sequential_rejection":
+        assert [len(message["item_list"]) for message in requests] == [1, 1, 1]
+        assert "合并转发被拒，已改为普通消息发送信息与密码" in status
+    elif response == "history_error":
         assert [len(message["item_list"]) for message in requests] == [2]
         assert "已发送合并转发" in status
     elif response == "rejection":

From b93956166922d5d7146091c3282b43465fa1f63c Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:18:13 +0800
Subject: [PATCH 106/121] fix(webui): isolate stale polls and history during
 sends

---
 docs/management-api.md                    |   2 +
 src/Undefined/webui/static/js/runtime.js  |  19 +++-
 tests/frontend/runtime_chat_harness.js    | 113 +++++++++++++++++++++-
 tests/test_webui_runtime_chat_behavior.py |  37 +++++++
 4 files changed, 164 insertions(+), 7 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index 5700ab2c..b163d3ba 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -353,6 +353,8 @@ WebUI 内嵌聊天渲染 `<attachment uid="..."/>` / `<pic uid="..."/>` 图片
 
 按 `conversation_id + job_id + seq` 续接 WebChat job 事件，支持 JSON 增量查询和兼容 SSE。
 
+WebUI 每次轮询还会校验请求身份；切换会话后重新续接同一任务时，旧响应不会重复追加正文或改写当前重试状态。发送新消息后，发送前发起的迟到历史响应也不能清空当前用户消息和实时回复。
+
 - 参数：
   - `conversation_id`：可选；传入时必须与 job 所属会话一致。
   - `after`：返回大于该 `seq` 的事件。
diff --git a/src/Undefined/webui/static/js/runtime.js b/src/Undefined/webui/static/js/runtime.js
index c09ab038..7e8b3033 100644
--- a/src/Undefined/webui/static/js/runtime.js
+++ b/src/Undefined/webui/static/js/runtime.js
@@ -40,6 +40,7 @@
         streamingMessageId: null,
         activeChatMessageId: null,
         chatPollTimer: null,
+        chatPollRequest: null,
         chatPollBackoffMs: 500,
         chatClockTimer: null,
         activeJobResumeTimer: null,
@@ -972,6 +973,7 @@
     function stopChatPolling() {
         clearTimeout(runtimeState.chatPollTimer);
         runtimeState.chatPollTimer = null;
+        runtimeState.chatPollRequest = null;
     }
 
     function stopChatClock() {
@@ -5511,6 +5513,11 @@
 
     async function pollChatJob(jobId) {
         if (runtimeState.activeJobId !== jobId) return;
+        const request = {};
+        runtimeState.chatPollRequest = request;
+        const isCurrentRequest = () =>
+            runtimeState.chatPollRequest === request &&
+            runtimeState.activeJobId === jobId;
         runtimeState.chatBusy = true;
         setButtonLoading(get("btnRuntimeChatSend"), true);
         syncChatBusyControls();
@@ -5521,11 +5528,11 @@
                     format: "json",
                 }),
             ]);
-            if (runtimeState.activeJobId !== jobId) return;
+            if (!isCurrentRequest()) return;
             runtimeState.chatPollBackoffMs = CHAT_POLL_INTERVAL_MS;
             applyChatEventsPayload(data, jobId);
         } catch (error) {
-            if (runtimeState.activeJobId !== jobId) return;
+            if (!isCurrentRequest()) return;
             showToast(t("runtime.chat_reconnecting"), "warning", 1800);
             runtimeState.chatPollBackoffMs = Math.min(
                 8000,
@@ -5535,7 +5542,7 @@
                 ),
             );
         }
-        if (runtimeState.activeJobId !== jobId) return;
+        if (!isCurrentRequest()) return;
         if (!runtimeState.chatBusy) {
             stopChatPolling();
             return;
@@ -5784,6 +5791,11 @@
                 throw new Error("message is required");
             }
             if (isCurrentChatSendRequest(request)) {
+                runtimeState.chatHistoryRequest = null;
+                runtimeState.chatHistoryLoading = false;
+                runtimeState.chatHistoryLoaded = true;
+                const historyLoader = get("runtimeChatLoadMore");
+                if (historyLoader) historyLoader.textContent = "";
                 clearToolCollapseTimers();
                 stopChatPolling();
                 stopChatClock();
@@ -5826,6 +5838,7 @@
             await attachChatJob(jobId, 0);
         } catch (error) {
             if (!isCurrentChatSendRequest(request)) return;
+            runtimeState.chatHistoryLoaded = false;
             runtimeState.chatBusy = false;
             setButtonLoading(button, false);
             syncChatBusyControls();
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index 6cd97bf7..fa3274c7 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -2968,8 +2968,42 @@ async function staleChatJobPoll(env, outcome) {
     if (pending.length !== 2) {
         throw new Error(`expected two overlapping old job polls, got ${pending.length}`);
     }
+    if (outcome.startsWith("same-")) {
+        pending[1].resolve(response(200, {
+            job: { ...oldJob, last_seq: 3, current_stage: "thinking", current_stage_detail: "current-model" },
+            events: [
+                { seq: 1, event: "meta", payload: oldJob },
+                { seq: 2, event: "message", payload: { ...oldJob, content: "old-live" } },
+                { seq: 3, event: "stage", payload: { ...oldJob, stage: "thinking", detail: "current-model" } },
+            ],
+        }));
+        await tick();
+        const snapshot = () => ({
+            nodes: botNodes(window).map((node) => ({ content: node.contentTexts })),
+            stageDetails: Array.from(window.document.querySelectorAll(".runtime-chat-stage"))
+                .map((node) => node.dataset.stageDetail),
+            disabled: button.disabled,
+            toast: textOf(window, "toast-container"),
+        });
+        const beforeLate = snapshot();
+        if (outcome === "same-failure") {
+            pending[0].reject(new Error("obsolete same job poll failure"));
+        } else {
+            pending[0].resolve(response(200, {
+                job: { ...oldJob, current_stage: "thinking", current_stage_detail: "obsolete-model" },
+                events: [
+                    { seq: 1, event: "meta", payload: oldJob },
+                    { seq: 2, event: "message", payload: { ...oldJob, content: "old-live" } },
+                ],
+            }));
+        }
+        await tick();
+        const afterLate = snapshot();
+        await settle(650);
+        return { beforeLate, afterLate, pollUrls: pending.map((item) => item.url) };
+    }
     oldFinished = true;
-    pending[0].resolve(response(200, {
+    pending[1].resolve(response(200, {
         job: { ...oldJob, status: "done", last_seq: 3, history_finalized: true },
         events: [{ seq: 3, event: "done", payload: { job_id: "old", conversation_id: "A", reply: "old-live" } }],
     }));
@@ -2986,10 +3020,10 @@ async function staleChatJobPoll(env, outcome) {
     });
     const beforeLate = snapshot();
     if (outcome === "failure") {
-        pending[1].reject(new Error("obsolete poll failure"));
+        pending[0].reject(new Error("obsolete poll failure"));
     } else {
         const terminal = outcome === "done";
-        pending[1].resolve(response(200, {
+        pending[0].resolve(response(200, {
             job: terminal ? { ...oldJob, status: "done", history_finalized: true } : oldJob,
             events: terminal ? [
                 { seq: 99, event: "done", payload: { job_id: "old", conversation_id: "A", reply: "INTRUDER" } },
@@ -3014,7 +3048,7 @@ async function staleChatJobPoll(env, outcome) {
     };
 }
 
-for (const outcome of ["events", "done", "failure"]) {
+for (const outcome of ["events", "done", "failure", "same-events", "same-failure"]) {
     SCENARIOS[`stale_job_poll_${outcome}`] = (env) => staleChatJobPoll(env, outcome);
 }
 
@@ -3124,6 +3158,77 @@ async function staleChatSend(env, boundary, target, outcome, newerJob) {
     return { beforeLate, afterLate, posts, polls };
 }
 
+async function historyResponseAfterNewJob(env, sendFails) {
+    const { window, response } = env;
+    let releaseHistory;
+    let deferHistory = false;
+    let running = false;
+    let failedSend = false;
+    const job = { job_id: "new-A", conversation_id: "A", status: "running", last_seq: 2 };
+    window.fetch = (url, options = {}) => {
+        const parsed = new window.URL(url, window.location.href);
+        const pathname = parsed.pathname;
+        if (pathname.endsWith("/chat/conversations")) return Promise.resolve(response(200, {
+            conversations: [{ id: "A", title: "A" }, { id: "B", title: "B" }],
+        }));
+        if (pathname.endsWith("/chat/history")) {
+            if (deferHistory && parsed.searchParams.get("conversation_id") === "A") {
+                return new Promise((resolve) => { releaseHistory = resolve; });
+            }
+            return Promise.resolve(response(200, {
+                items: failedSend ? [{ role: "bot", content: "persisted-after-failed-send" }] : [],
+                has_more: false,
+            }));
+        }
+        if (pathname.endsWith("/chat/jobs/active")) return Promise.resolve(response(200, { job: running ? job : null }));
+        if (pathname.endsWith("/chat/jobs") && options.method === "POST") {
+            if (sendFails) {
+                failedSend = true;
+                return Promise.resolve(response(409, { error: "definite-send-failure" }));
+            }
+            running = true;
+            return Promise.resolve(response(202, job));
+        }
+        if (pathname.endsWith("/events")) {
+            const after = Number(parsed.searchParams.get("after"));
+            return Promise.resolve(response(200, { job, events: [
+                { seq: 1, event: "meta", payload: job },
+                { seq: 2, event: "message", payload: { ...job, content: "new-live-reply" } },
+            ].filter((event) => event.seq > after) }));
+        }
+        throw new Error(`unexpected route ${pathname}`);
+    };
+    window.RuntimeController.init();
+    await window.RuntimeController.loadChatHistory(true);
+    window.document.querySelector('[data-conversation-select="B"]').click();
+    await tick();
+    deferHistory = true;
+    window.document.querySelector('[data-conversation-select="A"]').click();
+    await tick();
+    window.document.getElementById("runtimeChatInput").value = "new-question";
+    window.document.getElementById("btnRuntimeChatSend").click();
+    await tick();
+    const snapshot = () => ({
+        nodes: chatNodes(window).map((node) => ({ role: node.role, content: node.contentTexts })),
+        disabled: window.document.getElementById("btnRuntimeChatSend").disabled,
+    });
+    const beforeLate = snapshot();
+    if (!releaseHistory) throw new Error("A latest history was not pending");
+    releaseHistory(response(200, { items: [{ role: "bot", content: "older-history" }], has_more: false }));
+    await tick();
+    const afterLate = snapshot();
+    deferHistory = false;
+    window.__harness.setAuthenticated(true);
+    window.RuntimeController.onTabActivated("chat");
+    await tick();
+    return { beforeLate, afterLate, afterReopen: snapshot() };
+}
+
+for (const outcome of ["success", "failure"]) {
+    SCENARIOS[`history_response_after_new_job_${outcome}`] = (env) =>
+        historyResponseAfterNewJob(env, outcome === "failure");
+}
+
 for (const boundary of ["upload", "post"]) {
     for (const target of ["other", "same"]) {
         for (const outcome of ["success", "failure"]) {
diff --git a/tests/test_webui_runtime_chat_behavior.py b/tests/test_webui_runtime_chat_behavior.py
index 872eedf3..384460a8 100644
--- a/tests/test_webui_runtime_chat_behavior.py
+++ b/tests/test_webui_runtime_chat_behavior.py
@@ -773,6 +773,43 @@ def test_late_old_job_poll_cannot_replace_or_stop_new_job(outcome: str) -> None:
     assert bots[-1]["contentTexts"] == ["new-live", "new-followup"], bots
 
 
+@pytest.mark.parametrize("outcome", ["events", "failure"])
+def test_late_same_job_poll_cannot_replay_events_or_replace_current_retry(
+    outcome: str,
+) -> None:
+    result = run_scenario(f"stale_job_poll_same-{outcome}")
+
+    assert result["beforeLate"]["nodes"][0]["content"] == ["old-live"], result
+    assert result["afterLate"] == result["beforeLate"], result
+    assert len(result["pollUrls"]) == 3, result
+    assert "after=3&" in result["pollUrls"][-1], result
+
+
+@pytest.mark.parametrize("outcome", ["success", "failure"])
+def test_late_history_cannot_erase_a_new_job_started_while_loading(
+    outcome: str,
+) -> None:
+    result = run_scenario(f"history_response_after_new_job_{outcome}")
+
+    assert result["beforeLate"] == {
+        "nodes": [{"role": "user", "content": ["new-question"]}]
+        + (
+            [{"role": "bot", "content": ["new-live-reply"]}]
+            if outcome == "success"
+            else []
+        ),
+        "disabled": outcome == "success",
+    }, result
+    assert result["afterLate"] == result["beforeLate"], result
+    if outcome == "success":
+        assert result["afterReopen"] == result["beforeLate"], result
+    else:
+        assert result["afterReopen"] == {
+            "nodes": [{"role": "bot", "content": ["persisted-after-failed-send"]}],
+            "disabled": False,
+        }, result
+
+
 def test_foreign_conversation_events_are_ignored() -> None:
     """别的会话的事件不得写进当前会话的聊天区。
 

From fd048798bc3eb4170e617964b0e14c1202ccca7f Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 09:19:17 +0800
Subject: [PATCH 107/121] fix(config): serialize watcher restarts and retire
 stopped tasks

---
 docs/configuration.md                |   2 +-
 src/Undefined/config/hot_reload.py   |   3 +-
 src/Undefined/config/manager.py      |  14 +++-
 tests/test_config_hot_reload.py      |   4 +
 tests/test_config_watcher_restart.py | 117 +++++++++++++++++++++++++++
 5 files changed, 135 insertions(+), 5 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 89be2c0f..7e7ebf4e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1510,7 +1510,7 @@ Management 的 WebUI 配置按 [§4.23](#423-webui) 的时机生效：密码和
 - `skills.hot_reload*`（技能热重载任务重启）
 - `skills.hot_reload_interval/debounce`（配置热更新监听器自身重启）
 
-配置监听器启动和重启时会先重新读取并应用最新文件，再继续轮询；监听器切换期间保存的变更也会追赶应用。读取失败仍保留上次有效配置，监听任务继续运行，文件修正后再次保存即可重新加载。
+配置监听器启动和重启时会先重新读取并应用最新文件，再继续轮询；监听器切换期间保存的变更也会追赶应用。旧监听器收到停止信号后不再发起下一次重载，连续修改监听间隔也只保留使用最新参数的监听任务。读取失败仍保留上次有效配置，监听任务继续运行，文件修正后再次保存即可重新加载。
 
 ### 5.4 其他字段
 - `Config` 对象本身会更新。
diff --git a/src/Undefined/config/hot_reload.py b/src/Undefined/config/hot_reload.py
index 37eb2990..96a0f77c 100644
--- a/src/Undefined/config/hot_reload.py
+++ b/src/Undefined/config/hot_reload.py
@@ -473,8 +473,7 @@ async def _apply_message_handler_automations_hot_reload(
 async def _restart_config_hot_reload(
     config_manager: ConfigManager, interval: float, debounce: float
 ) -> None:
-    await config_manager.stop_hot_reload()
-    config_manager.start_hot_reload(interval=interval, debounce=debounce)
+    await config_manager.restart_hot_reload(interval=interval, debounce=debounce)
     logger.info(
         "[配置] 配置热更新已重启: interval=%.2fs debounce=%.2fs",
         interval,
diff --git a/src/Undefined/config/manager.py b/src/Undefined/config/manager.py
index 48a2da53..06fcb851 100644
--- a/src/Undefined/config/manager.py
+++ b/src/Undefined/config/manager.py
@@ -24,6 +24,7 @@ def __init__(self, config_path: Path | None = None) -> None:
         self._watch_stop: asyncio.Event | None = None
         self._last_snapshot: dict[str, tuple[int, int]] = {}
         self._reload_lock = asyncio.Lock()
+        self._watch_restart_lock = asyncio.Lock()
         self._pending_changes: dict[str, tuple[Any, Any]] = {}
 
     def load(self, strict: bool = True) -> Config:
@@ -92,10 +93,17 @@ async def stop_hot_reload(self, timeout: float | None = 2.0) -> None:
                     except asyncio.CancelledError:
                         pass
         finally:
-            self._watch_task = None
-            self._watch_stop = None
+            if self._watch_task is task:
+                self._watch_task = None
+                self._watch_stop = None
             logger.info("[配置] 热重载已停止")
 
+    async def restart_hot_reload(self, *, interval: float, debounce: float) -> None:
+        """按更新顺序完成停止与启动，避免并发重启丢失后续参数。"""
+        async with self._watch_restart_lock:
+            await self.stop_hot_reload()
+            self.start_hot_reload(interval=interval, debounce=debounce)
+
     async def _watch_loop(self, interval: float, debounce: float) -> None:
         self._last_snapshot = self._compute_snapshot()
         # 启动和重启时追赶 load/上一监听器退出后发生的保存；先记快照，
@@ -105,6 +113,8 @@ async def _watch_loop(self, interval: float, debounce: float) -> None:
         pending = False
         while self._watch_stop and not self._watch_stop.is_set():
             await asyncio.sleep(interval)
+            if self._watch_stop is None or self._watch_stop.is_set():
+                break
             snapshot = self._compute_snapshot()
             if snapshot != self._last_snapshot:
                 self._last_snapshot = snapshot
diff --git a/tests/test_config_hot_reload.py b/tests/test_config_hot_reload.py
index c046af41..f45ce678 100644
--- a/tests/test_config_hot_reload.py
+++ b/tests/test_config_hot_reload.py
@@ -106,6 +106,10 @@ async def stop_hot_reload(self) -> None:
     def start_hot_reload(self, *, interval: float, debounce: float) -> None:
         self.started.append((interval, debounce))
 
+    async def restart_hot_reload(self, *, interval: float, debounce: float) -> None:
+        await self.stop_hot_reload()
+        self.start_hot_reload(interval=interval, debounce=debounce)
+
 
 def test_apply_config_updates_propagates_to_security_service() -> None:
     updated = cast(
diff --git a/tests/test_config_watcher_restart.py b/tests/test_config_watcher_restart.py
index 34557e8a..cf18ac41 100644
--- a/tests/test_config_watcher_restart.py
+++ b/tests/test_config_watcher_restart.py
@@ -155,3 +155,120 @@ async def pause_restart(timeout: float | None = 2.0) -> None:
         if _BACKGROUND_TASKS:
             await asyncio.gather(*list(_BACKGROUND_TASKS), return_exceptions=True)
         await original_stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("reload_before_restart_finishes", [False, True])
+async def test_overlapping_watcher_restarts_keep_only_latest_listener(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    reload_before_restart_finishes: bool,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+
+    def save_interval(interval: float) -> None:
+        path.write_text(
+            f"[skills]\nhot_reload_interval={interval}\nhot_reload_debounce=0.0\n",
+            encoding="utf-8",
+        )
+
+    save_interval(0.05)
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    registry = SimpleNamespace(
+        stop_hot_reload=AsyncMock(), start_hot_reload=lambda **_: None
+    )
+    context = HotReloadContext(
+        ai_client=cast(
+            Any, SimpleNamespace(tool_registry=registry, agent_registry=registry)
+        ),
+        queue_manager=cast(Any, SimpleNamespace()),
+        config_manager=manager,
+        security_service=cast(Any, SimpleNamespace()),
+    )
+    manager.subscribe(
+        lambda config, changes: apply_config_updates(config, changes, context)
+    )
+    listeners: list[tuple[asyncio.Task[Any], float]] = []
+    original_watch = manager._watch_loop
+    original_stop = manager.stop_hot_reload
+    stopping = asyncio.Event()
+
+    async def record_watch(interval: float, debounce: float) -> None:
+        task = asyncio.current_task()
+        assert task is not None
+        listeners.append((task, interval))
+        await original_watch(interval, debounce)
+
+    async def record_stop(timeout: float | None = 2.0) -> None:
+        stopping.set()
+        await original_stop(timeout)
+
+    monkeypatch.setattr(manager, "_watch_loop", record_watch)
+    monkeypatch.setattr(manager, "stop_hot_reload", record_stop)
+    manager.start_hot_reload(interval=0.05, debounce=0.0)
+    try:
+        await asyncio.sleep(0)
+        save_interval(0.08)
+        await asyncio.wait_for(stopping.wait(), timeout=2)
+        assert manager._watch_stop is not None and manager._watch_stop.is_set()
+        save_interval(0.01)
+        if reload_before_restart_finishes:
+            manager.reload(strict=False)
+        async with asyncio.timeout(2):
+            while _BACKGROUND_TASKS:
+                await asyncio.gather(*list(_BACKGROUND_TASKS))
+            await asyncio.sleep(0)
+        live = [(task, interval) for task, interval in listeners if not task.done()]
+        assert len(live) == 1, [interval for _, interval in live]
+        assert live[0][0] is manager._watch_task
+        assert live[0][1] == 0.01
+    finally:
+        await original_stop()
+        for task, _ in listeners:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*(task for task, _ in listeners), return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_late_concurrent_stop_preserves_restarted_watcher(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("Undefined.config.config_class._load_env", lambda: None)
+    path = tmp_path / "config.toml"
+    path.write_text("[core]\nai_request_max_retries=2\n", encoding="utf-8")
+    manager = ConfigManager(path)
+    manager.load(strict=False)
+    listeners: list[asyncio.Task[Any]] = []
+    original_watch = manager._watch_loop
+
+    async def record_watch(interval: float, debounce: float) -> None:
+        task = asyncio.current_task()
+        assert task is not None
+        listeners.append(task)
+        await original_watch(interval, debounce)
+
+    async def stop_then_start() -> None:
+        await manager.stop_hot_reload()
+        manager.start_hot_reload(interval=0.03, debounce=0.0)
+
+    monkeypatch.setattr(manager, "_watch_loop", record_watch)
+    manager.start_hot_reload(interval=0.02, debounce=0.0)
+    try:
+        await asyncio.sleep(0)
+        await asyncio.gather(stop_then_start(), manager.stop_hot_reload())
+        await asyncio.sleep(0)
+        live = [task for task in listeners if not task.done()]
+        assert live == [manager._watch_task]
+        assert manager._watch_stop is not None
+        assert not manager._watch_stop.is_set()
+    finally:
+        await manager.stop_hot_reload()
+        for task in listeners:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*listeners, return_exceptions=True)

From f17f991e643e6840efc1f866d4fa6ff2d6f7dea5 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:10:36 +0800
Subject: [PATCH 108/121] chore(release): prepare v3.18.5

---
 CHANGELOG.md                                  | 19 +++++++++++++++++++
 apps/undefined-chat/package-lock.json         |  4 ++--
 apps/undefined-chat/package.json              |  2 +-
 apps/undefined-chat/src-tauri/Cargo.lock      |  2 +-
 apps/undefined-chat/src-tauri/Cargo.toml      |  2 +-
 apps/undefined-chat/src-tauri/tauri.conf.json |  2 +-
 apps/undefined-console/package-lock.json      |  4 ++--
 apps/undefined-console/package.json           |  2 +-
 apps/undefined-console/src-tauri/Cargo.lock   |  2 +-
 apps/undefined-console/src-tauri/Cargo.toml   |  2 +-
 .../src-tauri/tauri.conf.json                 |  2 +-
 pyproject.toml                                |  2 +-
 src/Undefined/__init__.py                     |  2 +-
 uv.lock                                       |  2 +-
 14 files changed, 34 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index defab789..faa60c15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,22 @@
+## v3.18.5 会话恢复、消息投递与并发持久化修复
+
+本版本集中修复聊天续接、消息发送和后台任务在切换会话、取消、断线、重启及写入失败时的状态错乱：保留已经完成的投递与提交，避免重复回复、旧响应覆盖新操作，以及界面显示成功但数据尚未保存的问题。
+
+- 聊天恢复与历史一致性：WebChat 只有在任务收尾、历史落盘并释放会话占用后才确认完成，创建任务失败会撤销占用，删除会话与接收新任务按顺序处理。完整任务快照保留正文、工具调用与嵌套 Agent 时间线，Chat 客户端修复断线续接、旧版事件重放和分页恢复；离线期间已经完成的会话也会刷新，旧连接、旧会话和旧请求的迟到结果不会覆盖当前状态。
+- WebUI 与客户端交互：修复切换会话后发送归属错误、旧轮询重复追加正文、迟到历史清空刚发送的消息，以及发送失败覆盖后续草稿的问题。保存连接配置时暂停请求，将未完成上传标记失败并忽略迟到结果，旧缓存迁移失败保留原数据；日志、工作流、表情包编辑和微信登录弹窗隔离各自请求，刷新与翻页保留未保存的编辑。登录凭据刷新串行执行，避免并发刷新相互失效。
+- 消息投递不再被后续故障误判：微信按每次服务端确认及时记录已发送状态，支持展开嵌套转发；历史、附件登记或使用统计失败不会把已送达内容当作未发送。分片或批量发送已有部分成功、或投递结果无法确认时，微信、抖音、JM 等业务降级不再重发整条内容；仍保留对明确未投递内容的降级。微信帐号变更与客户端启停串行，OneBot 重连不再等待消息处理任务阻塞；arXiv 去重按实际平台与投递地址隔离。
+- 配置保存与热更新：整体保存、增量修改、恢复、模板同步和密码更新共用原子写入顺序，同一时刻的备份不会互相覆盖；取消请求会等已开始的写入与必要更新完成。热更新失败可以重试，监听器重启会补读停止窗口内的修改，连续调整轮询间隔不会留下多个监听任务或继续使用旧间隔。内存构建配置不再意外读取本地文件，损坏的 TOML 即使使用 `strict=False` 也会明确报错。
+- 停止与取消：停止 Bot 先关闭新任务入口，等待已接收的回复、后台任务和持久化收尾，再关闭模型队列与消息通道。新增 `[webui].stop_timeout_seconds`（环境变量 `WEBUI_STOP_TIMEOUT_SECONDS`），**默认 `0` 表示等待自然结束，正整数才会在对应秒数后强制终止**；停止按钮、关闭 WebUI 和更新前停止共用此规则。取消模型请求会同步清理排队及重试任务，普通群聊队列裁剪保留已启动调用所依赖的子请求。
+- 连续消息与工具状态：已经回复完成的投机批次及时结束，后续消息开启新批次，避免把旧输入再次回复；批次取消只作用于对应任务，不会误伤独立的 @ 或拍一拍回复。`task_progress` 在多轮工具调用间共享，技能热重载保留在途统计；多模态分析缓存使用完整媒体来源、类型与补充指令，避免长链接或 data URL 前缀相同而串用结果。
+- 记忆与知识库：长期记忆和会话数据在落盘成功后才发布新状态，取消会等待已开始的提交，写入失败不会让内存与磁盘各自保留不同版本。知识文件替换先完成新内容读取、嵌入和写入，再清理旧索引；读取、嵌入或新块写入失败时保留旧索引供重试。侧写昵称刷新与史官跳过合并时也会补齐检索索引，索引失败不再提前确认完成；记忆时间筛选统一比较含时区与不含时区的时间。
+- 表情包生命周期：重分析不会覆盖期间的人工编辑、恢复已删除内容或影响同 UID 重新入库的记录；停用、删除与附件缓存失效保持一致，搜索不会返回已停用条目。使用统计失败保留发送成功结果，容量清理跳过刚置顶或修改的候选，删除失败保留可重试记录；异常退出遗留的处理任务会在后续轮询中恢复，正在执行的任务不会被重复调度。
+- 自动化流程：持久化按顺序完成，取消不会让旧快照覆盖新状态；嵌套并行循环只合并本轮修改的变量，避免覆盖同级节点刚产生的输出。`loop.times.count=0` 正确跳过循环，负数、布尔值和字符串不再被当作有效次数。
+- 文件与附件：统一解析本地 `file://` URI，保留中文、空格及原始路径中的百分号；CQ 参数转义与解码保留链接里的逗号、方括号和实体文本。HTTP 压缩响应按传输字节校验完整性、按解压后大小执行容量限制。JM、Bilibili、arXiv 下载及 Python 执行目录在取消后等待后台文件操作结束再清理；JM 配置的会话目录生效，畸形输入和单章异常不再拖垮整次处理。侧写路径与归档解压目标限制在各自目录内，缓存清理拒绝符号链接目录，TAR 解压启用安全过滤。
+- 原生显示与连接：附件下载以独占方式创建文件，避免覆盖同名文件；图片仍显示时保留其 Blob，代码高亮失败回落纯文本，生产构建拆分体积并保留完整语言支持。Console 迁移旧连接时保留协议与 IPv6 地址，Android 生命周期监听即使延迟注册也会在退出后释放。
+- 部署与维护：部署向导中断不再继续写配置，备份名称不冲突，IPv6 服务地址正确加括号；容器模式为 Python 解释器映射宿主 Docker 可见的共享目录，LxMusic 配置变化会触发容器重建。`restore_profile.py restore` 现在同时恢复侧写并同步检索正文与向量，失败后可用 `sync` 补齐，**执行前须停止机器人及其他写入进程**。重嵌入的 `--dry-run` 在临时副本上读取，不修改源向量库，但仍会调用嵌入 API；侧写恢复的 `--dry-run` 不写盘、不调用模型。版本脚本支持失败后重跑，补齐全部版本文件与锁文件，并将此前已修改的版本目标纳入提交。
+
+---
+
 ## v3.18.4 添加宣传片链接
 
 在 README.md 中添加了宣传片链接。
diff --git a/apps/undefined-chat/package-lock.json b/apps/undefined-chat/package-lock.json
index af51a7c5..bf195ae2 100644
--- a/apps/undefined-chat/package-lock.json
+++ b/apps/undefined-chat/package-lock.json
@@ -1,12 +1,12 @@
 {
 	"name": "undefined-chat",
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "undefined-chat",
-			"version": "3.18.4",
+			"version": "3.18.5",
 			"dependencies": {
 				"@tauri-apps/api": "^2.3.0",
 				"@tauri-apps/plugin-dialog": "^2.7.1",
diff --git a/apps/undefined-chat/package.json b/apps/undefined-chat/package.json
index 68b36d54..0b33cc87 100644
--- a/apps/undefined-chat/package.json
+++ b/apps/undefined-chat/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "undefined-chat",
 	"private": true,
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"type": "module",
 	"scripts": {
 		"tauri": "tauri",
diff --git a/apps/undefined-chat/src-tauri/Cargo.lock b/apps/undefined-chat/src-tauri/Cargo.lock
index 6f93c624..0ab76f08 100644
--- a/apps/undefined-chat/src-tauri/Cargo.lock
+++ b/apps/undefined-chat/src-tauri/Cargo.lock
@@ -5431,7 +5431,7 @@ dependencies = [
 
 [[package]]
 name = "undefined_chat"
-version = "3.18.4"
+version = "3.18.5"
 dependencies = [
  "futures-util",
  "keyring",
diff --git a/apps/undefined-chat/src-tauri/Cargo.toml b/apps/undefined-chat/src-tauri/Cargo.toml
index 0869b1c3..70b73278 100644
--- a/apps/undefined-chat/src-tauri/Cargo.toml
+++ b/apps/undefined-chat/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "undefined_chat"
-version = "3.18.4"
+version = "3.18.5"
 description = "Undefined native chat client"
 authors = ["Undefined contributors"]
 license = "MIT"
diff --git a/apps/undefined-chat/src-tauri/tauri.conf.json b/apps/undefined-chat/src-tauri/tauri.conf.json
index e2e06711..230466d6 100644
--- a/apps/undefined-chat/src-tauri/tauri.conf.json
+++ b/apps/undefined-chat/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "https://schema.tauri.app/config/2",
 	"productName": "Undefined Chat",
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"identifier": "com.undefined.chat",
 	"build": {
 		"beforeDevCommand": "npm run dev",
diff --git a/apps/undefined-console/package-lock.json b/apps/undefined-console/package-lock.json
index 559d4873..a29b5aad 100644
--- a/apps/undefined-console/package-lock.json
+++ b/apps/undefined-console/package-lock.json
@@ -1,12 +1,12 @@
 {
 	"name": "undefined-console",
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "undefined-console",
-			"version": "3.18.4",
+			"version": "3.18.5",
 			"dependencies": {
 				"@tauri-apps/api": "^2.3.0",
 				"@tauri-apps/plugin-http": "^2.3.0"
diff --git a/apps/undefined-console/package.json b/apps/undefined-console/package.json
index d611a9fc..a19284a8 100644
--- a/apps/undefined-console/package.json
+++ b/apps/undefined-console/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "undefined-console",
 	"private": true,
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"type": "module",
 	"scripts": {
 		"tauri": "tauri",
diff --git a/apps/undefined-console/src-tauri/Cargo.lock b/apps/undefined-console/src-tauri/Cargo.lock
index 56f7ac0b..4e084ae2 100644
--- a/apps/undefined-console/src-tauri/Cargo.lock
+++ b/apps/undefined-console/src-tauri/Cargo.lock
@@ -4063,7 +4063,7 @@ checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
 [[package]]
 name = "undefined_console"
-version = "3.18.4"
+version = "3.18.5"
 dependencies = [
  "serde",
  "serde_json",
diff --git a/apps/undefined-console/src-tauri/Cargo.toml b/apps/undefined-console/src-tauri/Cargo.toml
index 5b98b80b..e402ee5b 100644
--- a/apps/undefined-console/src-tauri/Cargo.toml
+++ b/apps/undefined-console/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "undefined_console"
-version = "3.18.4"
+version = "3.18.5"
 description = "Undefined cross-platform management console"
 authors = ["Undefined contributors"]
 license = "MIT"
diff --git a/apps/undefined-console/src-tauri/tauri.conf.json b/apps/undefined-console/src-tauri/tauri.conf.json
index 219a3da0..85e5607f 100644
--- a/apps/undefined-console/src-tauri/tauri.conf.json
+++ b/apps/undefined-console/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "https://schema.tauri.app/config/2",
 	"productName": "Undefined Console",
-	"version": "3.18.4",
+	"version": "3.18.5",
 	"identifier": "com.undefined.console",
 	"build": {
 		"beforeDevCommand": "npm run dev",
diff --git a/pyproject.toml b/pyproject.toml
index e776612e..2c781f74 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.18.4"
+version = "3.18.5"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [
diff --git a/src/Undefined/__init__.py b/src/Undefined/__init__.py
index 3b418311..ae2197e5 100644
--- a/src/Undefined/__init__.py
+++ b/src/Undefined/__init__.py
@@ -24,7 +24,7 @@
     from .skills.registry import BaseRegistry as BaseRegistry
     from .skills.tools import ToolRegistry as ToolRegistry
 
-__version__: str = "3.18.4"
+__version__: str = "3.18.5"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
diff --git a/uv.lock b/uv.lock
index 3d534b14..9feb0220 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4729,7 +4729,7 @@ wheels = [
 
 [[package]]
 name = "undefined-bot"
-version = "3.18.4"
+version = "3.18.5"
 source = { editable = "." }
 dependencies = [
     { name = "aiofiles" },

From a8f9fb6cd872604b156659e9a9eb8bc26d38cbd0 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:29:36 +0800
Subject: [PATCH 109/121] fix(automations): preserve legacy null loop counts

---
 docs/automations.md                        |  2 +
 src/Undefined/automations/runner.py        |  4 +-
 tests/test_automation_legacy_loop_count.py | 87 ++++++++++++++++++++++
 3 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_automation_legacy_loop_count.py

diff --git a/docs/automations.md b/docs/automations.md
index 68deebc1..fba5f269 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -77,6 +77,8 @@
 
 `loop.times.count` 必须为非负整数：`0` 跳过循环体并继续出口路径，省略时使用配置的循环上限。负数、布尔值、字符串和其他非整数类型会在创建、更新或启用时被拒绝；实际执行次数仍受 `max_iterations` 与配置上限约束。
 
+直接加载的旧存档若含 `count: null`，运行时按省略次数处理，使用配置的循环上限；这项兼容不放宽新任务的写入校验，也不会把显式的 `0` 改成默认次数。
+
 工具节点的 `args` 是 JSON 对象；WebUI 检查器按 JSON 值编辑每个参数，因此数字、布尔值、数组、对象、`null` 与字符串会保留原类型（字符串可写成 JSON 字符串，无法解析为 JSON 的输入也按字符串保存）。`llm.blank.tools` 中的名称先按注册表名称精确匹配，包括 `send_message` 这类裸兼容别名；仅当精确名称不存在时，短名称才按 basename 做唯一无歧义解析。带命名空间的完整名称不会退化为 basename 匹配。
 
 执行规则一句话版：有依赖就等待——普通并行汇合会等所有有效上游完成；条件分支只激活选中路径，未选路径会传播为“跳过”，所以互斥 case 可以直接或在下游安全汇合。无依赖的节点一旦就绪就立即并行执行。循环的 `index` / `item` 是每个循环、每次迭代的局部上下文，嵌套或并行循环不会互相覆盖。循环结束仅回写本轮新增或更新的输出，不会用进入循环时的旧快照覆盖并行分支已经发布的结果。LLM 与模板节点默认只产出内容不发消息，勾选 `emit` 后才会发送（消息触发发到当前会话，时间触发发到任务地址）。任一节点失败则整图停止；只有从旧定时任务迁移出的图保留“工具失败后继续”的历史兼容行为。
diff --git a/src/Undefined/automations/runner.py b/src/Undefined/automations/runner.py
index 351d291e..617ae9c8 100644
--- a/src/Undefined/automations/runner.py
+++ b/src/Undefined/automations/runner.py
@@ -996,7 +996,9 @@ async def _run_loop_times(
         variables: dict[str, Any],
         emit_if_needed: Callable[[dict[str, Any], str], Awaitable[None]],
     ) -> str:
-        count = int(node.get("count", self.loop_max_iterations))
+        # Persisted legacy graphs can contain null despite current write validation.
+        raw_count = node.get("count")
+        count = self.loop_max_iterations if raw_count is None else int(raw_count)
         max_iterations = min(
             int(node.get("max_iterations") or self.loop_max_iterations),
             self.loop_max_iterations,
diff --git a/tests/test_automation_legacy_loop_count.py b/tests/test_automation_legacy_loop_count.py
new file mode 100644
index 00000000..dd45c6ac
--- /dev/null
+++ b/tests/test_automation_legacy_loop_count.py
@@ -0,0 +1,87 @@
+"""Persisted loop graphs retain their legacy default-count behavior."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, call
+
+import pytest
+
+from Undefined.automations.match import AutomationEvent
+from Undefined.automations.service import AutomationService
+from Undefined.automations.storage import AutomationStorage
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("count_mode", ["null", "missing", "zero"])
+async def test_persisted_loop_count_runs_through_event_service(
+    tmp_path: Path, count_mode: str
+) -> None:
+    loop: dict[str, Any] = {
+        "id": "loop",
+        "type": "loop.times",
+        "body": ["body"],
+        "max_iterations": 3,
+    }
+    if count_mode != "missing":
+        loop["count"] = None if count_mode == "null" else 0
+    task = {
+        "enabled": True,
+        "consume_ai_loop": True,
+        "auto_send_final": False,
+        "nodes": [
+            {
+                "id": "start",
+                "type": "start",
+                "kind": "message",
+                "channels": ["group"],
+                "text": "run",
+            },
+            loop,
+            {
+                "id": "body",
+                "type": "template",
+                "template": "iteration {{index}}",
+                "emit": True,
+            },
+            {"id": "after", "type": "template", "template": "after", "emit": True},
+        ],
+        "edges": [
+            {"from": "start", "to": "loop"},
+            {"from": "loop", "to": "after", "kind": "exit"},
+        ],
+    }
+    path = tmp_path / "automations.json"
+    path.write_text(json.dumps({"legacy": task}), encoding="utf-8")
+    storage = AutomationStorage(path=path)
+    sender = SimpleNamespace(send_group_message=AsyncMock())
+    service = AutomationService(
+        SimpleNamespace(
+            memory_storage=SimpleNamespace(),
+            runtime_config=SimpleNamespace(
+                automations=SimpleNamespace(loop_max_iterations=2)
+            ),
+        ),
+        sender,
+        SimpleNamespace(get_image=AsyncMock(), get_forward_msg=AsyncMock()),
+        SimpleNamespace(),
+        storage=storage,
+    )
+    try:
+        consumed = await service.handle_event(
+            AutomationEvent(kind="message", channel="group", group_id=1, text="run")
+        )
+        assert consumed is True
+        persisted = storage.load_tasks()["legacy"]
+        assert persisted["last_status"] == "ok", persisted["last_error"]
+        assert persisted["current_executions"] == 1
+        expected = [] if count_mode == "zero" else ["iteration 0", "iteration 1"]
+        expected.append("after")
+        assert sender.send_group_message.await_args_list == [
+            call(1, message, reply_to=None) for message in expected
+        ]
+    finally:
+        service.shutdown()

From 8ca1a91c19658a60423c4660e6b59c84a3c00c9d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:30:00 +0800
Subject: [PATCH 110/121] test(memory): verify persistence errors at tool
 boundaries

---
 .../skills/toolsets/memory/README.md          |  2 +
 tests/test_memory_persistence.py              | 57 +++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/src/Undefined/skills/toolsets/memory/README.md b/src/Undefined/skills/toolsets/memory/README.md
index 018b1cf6..dbaa9e3c 100644
--- a/src/Undefined/skills/toolsets/memory/README.md
+++ b/src/Undefined/skills/toolsets/memory/README.md
@@ -8,6 +8,8 @@
 
 同一运行时中的增删改与清空共用串行提交锁，先原子落盘再发布内存状态，重复内容只从已提交记录中去重。磁盘写入失败会向调用方报告失败，原有记录和容量淘汰状态保持不变；故障修复后可以重试。Runtime API 的持久化失败返回 HTTP 500，不会返回“已保存”。
 
+普通工具入口由统一注册表将异常转换为“执行 memory.<操作> 时出错: <原因>”，同时记录错误日志及失败统计；各 handler 不重复捕获。自动化使用的 strict 入口保留异常，让工作流能正确判定失败。
+
 等待提交锁时取消会中止尚未开始的变更；实际写入开始后，取消会等待该次写入和内存状态提交完成，再释放锁并传播。列出记忆返回独立记录副本，不能绕过持久化流程修改存储。
 
 目录结构：
diff --git a/tests/test_memory_persistence.py b/tests/test_memory_persistence.py
index cb490f2a..bad1201a 100644
--- a/tests/test_memory_persistence.py
+++ b/tests/test_memory_persistence.py
@@ -19,7 +19,14 @@
     memory_update_handler,
 )
 from Undefined.memory import MemoryStorage
+from Undefined.skills.tools import ToolRegistry
 from Undefined.skills.toolsets.memory.add.handler import execute as add_memory_tool
+from Undefined.skills.toolsets.memory.delete.handler import (
+    execute as delete_memory_tool,
+)
+from Undefined.skills.toolsets.memory.update.handler import (
+    execute as update_memory_tool,
+)
 from Undefined.utils import io
 
 
@@ -132,6 +139,56 @@ async def test_memory_failure_is_not_deduplicated_on_healthy_retry(
     assert _facts(MemoryStorage()) == ["retry"]
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("operation", ["add", "update", "delete"])
+@pytest.mark.parametrize("strict", [False, True])
+async def test_memory_tools_report_persistence_failure_through_registry(
+    memory_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    operation: str,
+    strict: bool,
+) -> None:
+    storage = MemoryStorage()
+    memory_uuid = await storage.add("original")
+    before = memory_path.read_bytes()
+    tool_name = f"memory.{operation}"
+    registry = ToolRegistry(tools_dir=memory_path.parent / "tools")
+    handlers = {
+        "add": add_memory_tool,
+        "update": update_memory_tool,
+        "delete": delete_memory_tool,
+    }
+    registry.register_external_item(
+        tool_name,
+        {"type": "function", "function": {"name": tool_name}},
+        handlers[operation],
+    )
+    args = {"uuid": memory_uuid, "fact": "new"}
+    context = {"memory_storage": storage}
+    real_write = io.write_json
+    monkeypatch.setattr(
+        io, "write_json", AsyncMock(side_effect=OSError("isolated ENOSPC"))
+    )
+    if strict:
+        with pytest.raises(OSError, match="ENOSPC"):
+            await registry.execute_tool_strict(tool_name, args, context)
+    else:
+        result = await registry.execute_tool(tool_name, args, context)
+        assert result == f"执行 {tool_name} 时出错: isolated ENOSPC"
+    assert _facts(storage) == ["original"]
+    assert memory_path.read_bytes() == before
+    stats = registry.get_stats()[tool_name]
+    assert (stats.count, stats.success, stats.failure) == (1, 0, 1)
+    assert stats.last_error == "isolated ENOSPC"
+
+    monkeypatch.setattr(io, "write_json", real_write)
+    result = await registry.execute_tool(tool_name, args, context)
+    assert result.startswith("已")
+    assert (stats.count, stats.success, stats.failure) == (2, 1, 1)
+    expected = {"add": ["original", "new"], "update": ["new"], "delete": []}
+    assert _facts(storage) == _facts(MemoryStorage()) == expected[operation]
+
+
 @pytest.mark.asyncio
 async def test_memory_duplicate_waits_for_initial_commit(
     memory_path: Path, monkeypatch: pytest.MonkeyPatch

From b450278f785d21181ee928480263d3098f6ddc9f Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:30:27 +0800
Subject: [PATCH 111/121] fix(weixin): preserve errors for known unsent
 messages

---
 docs/wechat-ilink.md              |   8 +-
 src/Undefined/utils/sender.py     |   5 +-
 src/Undefined/weixin/transport.py |  16 ++-
 tests/test_sender.py              |   9 +-
 tests/test_weixin_delivery.py     | 168 ++++++++++++++++++++++++++++--
 5 files changed, 193 insertions(+), 13 deletions(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index 1eaa3053..dcd6f35f 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -108,19 +108,19 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 - 出站：支持 Markdown 渲染的文本、图片、文件、视频、原生语音、同一物理微信会话内的 `reply_to` 引用和输入中状态；超过 4000 字符的文本会自动分片，文本与媒体混合消息会在全量本地预检后按原始片段顺序投递。
 - 明确不支持：跨微信帐号或跨 QQ/微信通道引用、群聊。
 
-发送引用时，`reply_to` 必须是当前 `wechat:<逻辑QQ号>` 历史中可见的 `message_id`。Undefined 会先验证物理路由，再把经过清理的旧消息摘要作为 iLink 原生引用发送；若上游明确拒绝原生引用，则自动改为 Markdown 引用。网络超时、会话暂停等不确定失败不会触发降级重发，以免产生重复消息。
+发送引用时，`reply_to` 必须是当前 `wechat:<逻辑QQ号>` 历史中可见的 `message_id`。Undefined 会先验证物理路由，再把经过清理的旧消息摘要作为 iLink 原生引用发送；若上游明确拒绝原生引用，则自动改为 Markdown 引用。读写中断等投递不确定错误不会触发降级重发；令牌失效或会话暂停也不能靠去掉引用解决，保留原错误。
 
-微信文本中的 `<`、`>`、`&` 等特殊符号和 `<attachment uid="..."/>` 附件标签应原样发送，不使用 HTML/XML 实体。微信没有 QQ 合并转发卡片的等价合同。默认情况下，Undefined 会把当前微信私聊的转发节点展开为保留原顺序的文本与媒体项目，再优先通过一个或多个 iLink `sendmessage.item_list` 请求投递；这是一种实验性多项目消息，不会生成可展开的 QQ 式转发卡片。单次项目数由 `multi_item_max_items` 限制，媒体合计仍受 `media_max_size_mb` 约束。若上游明确拒绝多项目结构，会从当前批次起自动回退为逐段发送；网络超时、会话暂停或服务端错误等结果不确定的失败不会降级重发，以免产生重复消息。设置 `multi_item_messages_enabled=false` 可直接使用逐段模式。包含本地 CQ 图片、文件、视频或音频的消息会走统一附件发送层，媒体本地路径不会作为正文发给用户。
+微信文本中的 `<`、`>`、`&` 等特殊符号和 `<attachment uid="..."/>` 附件标签应原样发送，不使用 HTML/XML 实体。微信没有 QQ 合并转发卡片的等价合同。默认情况下，Undefined 会把当前微信私聊的转发节点展开为保留原顺序的文本与媒体项目，再优先通过一个或多个 iLink `sendmessage.item_list` 请求投递；这是一种实验性多项目消息，不会生成可展开的 QQ 式转发卡片。单次项目数由 `multi_item_max_items` 限制，媒体合计仍受 `media_max_size_mb` 约束。若上游明确拒绝多项目结构，会从当前批次起自动回退为逐段发送；读写中断或服务端错误等投递不确定的失败不会降级重发，令牌失效或会话暂停也不触发拆分消息的结构降级。设置 `multi_item_messages_enabled=false` 可直接使用逐段模式。包含本地 CQ 图片、文件、视频或音频的消息会走统一附件发送层，媒体本地路径不会作为正文发给用户。
 
 转发节点中的嵌套节点会递归展开，保留每层的发送者标题、正文以及文本和媒体的先后顺序；Bilibili 长正文分段和嵌套卡片也按这一规则发送。逐段模式与多项目模式都会在首个项目发出前校验所有层级的本地媒体，并完成全部语音准备。任一层媒体不存在、超限、使用当前不支持的远程来源或语音准备失败时，整个转发在投递前失败。
 
 每次文本、文件、语音或多项目批次收到发送确认后，都会立即标记当前轮已经输出；这个标记不依赖历史记录开关。后续批次失败时，前面已经确认发送的事实仍会保留，`end` 不会将整轮误判为没有输出。
 
-已收到成功 ACK 后，历史写入或发送后附件登记失败只记录日志，保留实际发送结果，避免业务层把它当作投递失败而补发。任务取消仍正常传播。
+已收到成功 ACK 后，历史写入或发送后附件登记失败会记录 ERROR 级日志及异常堆栈，明确提示“消息已送达，但发送后历史或附件记录失败（不重发）”，并保留实际发送结果，避免业务层把它当作投递失败而补发。这类日志表示本地记录需要排查，不能据此重发消息；任务取消仍正常传播。
 
 长文本分片、转发分批或顺序降级中，当前批次被明确拒绝时仍可对该批次降级；如果本条消息已有分片成功，后续失败会保留部分送达状态，禁止业务层把整条消息重新发送。尚无分片成功时，仍保留明确拒绝后的正常降级。
 
-消息请求进入 SDK 的 `sendmessage` 派发阶段后，网络超时或非明确拒绝会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败不会被误标为已投递；明确结构拒绝仍可安全回退。
+消息请求进入 SDK 的 `sendmessage` 派发阶段后，读写中断、远端协议异常或无法确认的服务端错误会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。配置错误、令牌失效、会话暂停，以及 HTTPX 明确发生在连接或连接池阶段的失败保留原异常，不会被误报为可能送达；其中认证与暂停仍不属于可更换消息结构解决的拒绝。连接前失败且没有任何分片成功时，业务层可按既有规则降级；一旦本条已有分片成功，仍禁止整条重发。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败也不会被误标为已投递。
 
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
 
diff --git a/src/Undefined/utils/sender.py b/src/Undefined/utils/sender.py
index d7433744..59be8f40 100644
--- a/src/Undefined/utils/sender.py
+++ b/src/Undefined/utils/sender.py
@@ -74,7 +74,10 @@ def _weixin_history_guard(user_id: int) -> Iterator[None]:
     try:
         yield
     except Exception:
-        logger.exception("[历史记录] 记录微信发送失败: user=%s", user_id)
+        logger.exception(
+            "[历史记录] 微信消息已送达，但发送后历史或附件记录失败（不重发）: user=%s",
+            user_id,
+        )
 
 
 @contextmanager
diff --git a/src/Undefined/weixin/transport.py b/src/Undefined/weixin/transport.py
index 49d9322c..9970d8e0 100644
--- a/src/Undefined/weixin/transport.py
+++ b/src/Undefined/weixin/transport.py
@@ -5,11 +5,14 @@
 from collections.abc import Mapping
 from typing import Any
 
+import httpx
 from weixin_ilink_client import (
     ApiError,
+    ConfigurationError,
     HttpError,
     IlinkTransport,
     SessionPausedError,
+    TransportError,
     UnsupportedCapabilityError,
     WeixinCredentials,
     WeixinIlinkError,
@@ -47,7 +50,18 @@ async def send_message(
         try:
             await super().send_message(credentials, message)
         except WeixinIlinkError as exc:
-            if is_definitive_weixin_delivery_rejection(exc):
+            # 确认未发送与允许更换消息结构降级是两个条件：认证/暂停必须
+            # 保留原错误，但不能靠移除引用或拆分多项消息解决。
+            if isinstance(exc, (ApiError, ConfigurationError)) or (
+                is_definitive_weixin_delivery_rejection(exc)
+            ):
+                raise
+            # SDK 统一包装网络错误，但保留 HTTPX 原因。仅连接/连接池阶段
+            # 可确定请求尚未发出；读写失败仍可能已被服务端接收。
+            if isinstance(exc, TransportError) and isinstance(
+                exc.__cause__,
+                (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout),
+            ):
                 raise
             raise WeixinDeliveryUncertainError(
                 "微信投递结果未确认，禁止自动重发"
diff --git a/tests/test_sender.py b/tests/test_sender.py
index 4a01bc41..f1743705 100644
--- a/tests/test_sender.py
+++ b/tests/test_sender.py
@@ -1358,7 +1358,14 @@ async def send() -> None:
                 await send()
         else:
             await send()
-            assert "记录微信发送失败" in caplog.text
+            failures = [
+                record
+                for record in caplog.records
+                if "微信消息已送达，但发送后历史或附件记录失败" in record.message
+            ]
+            assert len(failures) == 1
+            assert failures[0].levelno == logging.ERROR
+            assert failures[0].exc_info is not None
         assert ctx.get_resource("message_sent_this_turn") is True
     history.assert_awaited_once()
     assert (
diff --git a/tests/test_weixin_delivery.py b/tests/test_weixin_delivery.py
index f7e18ab3..61b5e7ff 100644
--- a/tests/test_weixin_delivery.py
+++ b/tests/test_weixin_delivery.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import time
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, cast
@@ -9,13 +10,18 @@
 import httpx
 import pytest
 from weixin_ilink_client import (
+    ApiError,
     AsyncWeixinIlinkClient,
     ClientOptions,
+    ConfigurationError,
     MediaKind,
     OutboundMediaItem,
     RequestTimeoutError,
+    SessionPausedError,
+    TransportError,
     WeixinCredentials,
 )
+from weixin_ilink_client.constants import STALE_TOKEN_ERROR_CODE
 
 from Undefined.config import Config
 from Undefined.jm.sender import _send_result
@@ -27,6 +33,7 @@
 from Undefined.weixin.transport import (
     UndefinedIlinkTransport,
     WeixinDeliveryUncertainError,
+    is_definitive_weixin_delivery_rejection,
 )
 
 
@@ -35,12 +42,16 @@
     "response",
     [
         "timeout",
+        "connect_error",
+        "connect_timeout",
+        "pool_timeout",
         "server_error",
         "rejection",
         "history_error",
         "partial_bundle_rejection",
         "partial_sequential_rejection",
         "partial_fallback_rejection",
+        "partial_connect_failure",
         "first_sequential_rejection",
     ],
 )
@@ -54,6 +65,10 @@ async def test_sdk_dispatch_error_controls_jm_fallback(
     def handle(request: httpx.Request) -> httpx.Response:
         message = json.loads(request.content)["msg"]
         requests.append(message)
+        if response == "partial_connect_failure":
+            if len(requests) == 2:
+                raise httpx.ConnectError("second batch was not sent", request=request)
+            return httpx.Response(200, json={"ret": 0}, request=request)
         rejected_requests = {
             "partial_bundle_rejection": {2, 3},
             "partial_sequential_rejection": {2},
@@ -67,6 +82,13 @@ def handle(request: httpx.Request) -> httpx.Response:
                 request=request,
             )
         if len(requests) == 1:
+            connection_failure = {
+                "connect_error": httpx.ConnectError,
+                "connect_timeout": httpx.ConnectTimeout,
+                "pool_timeout": httpx.PoolTimeout,
+            }.get(response)
+            if connection_failure is not None:
+                raise connection_failure("request was not sent", request=request)
             if response == "history_error":
                 return httpx.Response(200, json={"ret": 0}, request=request)
             if response == "timeout":
@@ -102,7 +124,7 @@ def handle(request: httpx.Request) -> httpx.Response:
         "first_sequential_rejection",
     }
     sender_config.weixin.multi_item_max_items = (
-        1 if response == "partial_bundle_rejection" else 10
+        1 if response in {"partial_bundle_rejection", "partial_connect_failure"} else 10
     )
     sender_config.weixin.media_max_size_mb = 100
     sender = MessageSender(MagicMock(), history, bot_qq=999, config=sender_config)
@@ -142,7 +164,11 @@ def handle(request: httpx.Request) -> httpx.Response:
     zip_send.assert_awaited_once()
     await service.stop()
     if response.startswith("partial_"):
-        assert len(requests) == (2 if response == "partial_sequential_rejection" else 3)
+        assert len(requests) == (
+            2
+            if response in {"partial_sequential_rejection", "partial_connect_failure"}
+            else 3
+        )
         assert "投递结果未确认" in status
     elif response == "first_sequential_rejection":
         assert [len(message["item_list"]) for message in requests] == [1, 1, 1]
@@ -153,6 +179,9 @@ def handle(request: httpx.Request) -> httpx.Response:
     elif response == "rejection":
         assert [len(message["item_list"]) for message in requests] == [2, 1, 1]
         assert "已发送合并转发" in status
+    elif response in {"connect_error", "connect_timeout", "pool_timeout"}:
+        assert [len(message["item_list"]) for message in requests] == [2, 1, 1]
+        assert "合并转发被拒，已改为普通消息发送信息与密码" in status
     else:
         assert len(requests) == 1
         assert len(requests[0]["item_list"]) == 2
@@ -160,9 +189,21 @@ def handle(request: httpx.Request) -> httpx.Response:
 
 
 @pytest.mark.asyncio
-async def test_dispatch_timeout_preserves_sdk_cause() -> None:
+@pytest.mark.parametrize(
+    "error_type",
+    [
+        httpx.ReadTimeout,
+        httpx.WriteTimeout,
+        httpx.ReadError,
+        httpx.WriteError,
+        httpx.RemoteProtocolError,
+    ],
+)
+async def test_dispatch_failure_preserves_uncertain_sdk_cause(
+    error_type: type[httpx.RequestError],
+) -> None:
     def timeout(request: httpx.Request) -> httpx.Response:
-        raise httpx.ReadTimeout("response lost", request=request)
+        raise error_type("request or response interrupted", request=request)
 
     credentials = WeixinCredentials(
         "account", "token", "https://isolated.invalid", "user"
@@ -172,8 +213,123 @@ def timeout(request: httpx.Request) -> httpx.Response:
         with pytest.raises(WeixinDeliveryUncertainError) as raised:
             await transport.send_message(credentials, {"item_list": []})
     assert raised.value.delivery_uncertain is True
-    assert isinstance(raised.value.__cause__, RequestTimeoutError)
-    assert isinstance(raised.value.__cause__.__cause__, httpx.ReadTimeout)
+    assert isinstance(raised.value.__cause__, TransportError)
+    assert isinstance(raised.value.__cause__.__cause__, error_type)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "error_type", [httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout]
+)
+async def test_pre_dispatch_failure_preserves_sdk_error(
+    error_type: type[httpx.RequestError],
+) -> None:
+    def fail_before_send(request: httpx.Request) -> httpx.Response:
+        raise error_type("request was not sent", request=request)
+
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(fail_before_send)
+    ) as http_client:
+        client = AsyncWeixinIlinkClient(
+            credentials,
+            transport=UndefinedIlinkTransport(http_client=http_client),
+        )
+        with pytest.raises(TransportError) as raised:
+            await client.send_text("peer", "message")
+    assert not getattr(raised.value, "delivery_uncertain", False)
+    assert isinstance(raised.value.__cause__, error_type)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("paused", [False, True])
+@pytest.mark.parametrize("through_sender", [False, True])
+async def test_authentication_rejection_reaches_service_without_uncertain_marker(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    paused: bool,
+    through_sender: bool,
+) -> None:
+    requests: list[str] = []
+
+    def reject_token(request: httpx.Request) -> httpx.Response:
+        requests.append(request.url.path)
+        return httpx.Response(200, json={"ret": STALE_TOKEN_ERROR_CODE})
+
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    config = Config.from_mapping(
+        {"weixin": {"enabled": True, "state_dir": str(tmp_path)}}, strict=False
+    )
+    service = WeixinService(config)
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(reject_token)
+    ) as http_client:
+        client = AsyncWeixinIlinkClient(
+            credentials,
+            transport=UndefinedIlinkTransport(http_client=http_client),
+        )
+        if paused:
+            await client.state_store.set_pause_until(
+                credentials.account_id, time.time() + 60
+            )
+        monkeypatch.setattr(
+            service,
+            "_resolve_runtime",
+            AsyncMock(
+                return_value=(
+                    SimpleNamespace(peer_id="peer"),
+                    SimpleNamespace(client=client),
+                )
+            ),
+        )
+        with pytest.raises(ApiError) as raised:
+            if through_sender:
+                sender_config = MagicMock()
+                sender_config.weixin.multi_item_messages_enabled = True
+                sender_config.weixin.multi_item_max_items = 10
+                sender_config.weixin.media_max_size_mb = 100
+                sender = MessageSender(
+                    MagicMock(), MagicMock(), bot_qq=999, config=sender_config
+                )
+                sender.set_weixin_service(service)
+                bound = AddressBoundSender(sender, DeliveryAddress("wechat", 12345))
+                await bound.send_private_forward_message(
+                    12345,
+                    [{"type": "node", "data": {"name": "Bot", "content": "报告"}}],
+                    history_message="报告",
+                    auto_history=False,
+                )
+            else:
+                await service.send_text(12345, "message")
+    await service.stop()
+    assert raised.value.code == STALE_TOKEN_ERROR_CODE
+    assert not getattr(raised.value, "delivery_uncertain", False)
+    # 认证过期不能靠移除引用或拆分多项消息解决，仍不属于结构降级候选。
+    assert not is_definitive_weixin_delivery_rejection(raised.value)
+    if paused:
+        assert isinstance(raised.value, SessionPausedError)
+        assert requests == []
+    else:
+        assert requests == ["/ilink/bot/sendmessage"]
+
+
+@pytest.mark.asyncio
+async def test_invalid_dispatch_url_is_known_not_sent() -> None:
+    def unexpected_request(request: httpx.Request) -> httpx.Response:
+        pytest.fail("invalid dispatch URL must not produce an HTTP request")
+
+    credentials = WeixinCredentials("account", "token", "http://invalid", "user")
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(unexpected_request)
+    ) as http_client:
+        transport = UndefinedIlinkTransport(http_client=http_client)
+        with pytest.raises(ConfigurationError) as raised:
+            await transport.send_message(credentials, {"item_list": []})
+    assert not getattr(raised.value, "delivery_uncertain", False)
 
 
 @pytest.mark.asyncio

From c5be1c89428eaf3c82e46d558c24c86974354f1d Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:33:53 +0800
Subject: [PATCH 112/121] fix(queue): cap new ordinary group LLM admissions

---
 config.toml.example                        |   3 +
 docs/configuration.md                      |   4 +
 src/Undefined/config/config_class.py       |   1 +
 src/Undefined/config/env_registry.py       |   1 +
 src/Undefined/config/hot_reload.py         |   7 +
 src/Undefined/config/load_sections/core.py |  16 ++
 src/Undefined/config/models.py             |   1 +
 src/Undefined/handlers/message_flow.py     |   1 +
 src/Undefined/services/queue_manager.py    |  36 +++-
 tests/test_core_config.py                  |  40 +++++
 tests/test_end_to_end_message_pipeline.py  |  25 +++
 tests/test_group_llm_queue_capacity.py     | 185 +++++++++++++++++++++
 12 files changed, 319 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_group_llm_queue_capacity.py

diff --git a/config.toml.example b/config.toml.example
index 276dc338..7cf9a1f4 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -28,6 +28,9 @@ context_recent_messages_limit = 20
 # zh: 单次 LLM 请求失败时最大静默重试次数（0=不重试，默认2）。失败的请求会回到原队列的第 2 个位置。
 # en: Max silent retries for a single failed LLM request (0=no retry, default 2). Failed requests are reinserted at position 2 of their original queue lane.
 ai_request_max_retries = 2
+# zh: 每模型普通群聊 LLM 等待队列的新请求准入上限（正整数，默认128，可热更新）。满时拒绝新请求；保留已接收请求和重试，不限制在途调用。
+# en: Per-model admission limit for new ordinary-group queued LLM calls (positive integer, default 128, hot reload). Rejects new calls when full; retains accepted calls and retries, and does not cap in-flight calls.
+group_llm_queue_max_pending = 128
 # zh: 模型返回纯文本但未调用 send_message/end 等工具时的最大纠正重试次数（0=不重试，默认3）。
 # en: Max correction retries when the model returns plain text without tool calls (0=no retry, default 3).
 missing_tool_call_retries = 3
diff --git a/docs/configuration.md b/docs/configuration.md
index 7e7ebf4e..8be01a68 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -199,6 +199,7 @@ model_name = "gpt-4o-mini"
 | `process_poke_message` | `true` | 是否响应拍一拍 | 关闭后忽略 poke |
 | `context_recent_messages_limit` | `20` | 注入到提示词的最近历史条数；当前输入批次发车入队前冻结为请求级快照 | `<0` 视为 `0`（关闭注入）；无固定上限，受 `max_records` 与存储约束；已入队请求不受后续消息或配置热更新影响 |
 | `ai_request_max_retries` | `2` | 单次 LLM 请求失败重试次数；无工具调用且实际 `assistant.content` 为空白时也走此路径，原样重试同一轮请求。安全模型注入检测、Naga 审核与注入回复在遇到可重试 HTTP 错误（429 / 5xx）时同样使用该次数 | `<0` 自动回退到 `0`；支持热更新 |
+| `group_llm_queue_max_pending` | `128` | 每模型普通群聊 LLM 等待队列的新请求准入上限；支持环境变量 `GROUP_LLM_QUEUE_MAX_PENDING` | 必须为正整数，非法值报错；支持热更新，调低不会丢弃已接收请求 |
 | `missing_tool_call_retries` | `3` | 模型返回非空纯文本且无法恢复为本轮可用工具调用时的纠正重试次数（保留 assistant 纯文本 + 通用纠正提示，不写死具体 tool）；空白响应不计入此项；每次进入下一轮纠正重试前，warning 日志会以 `raw_content=repr(...)` 完整记录该轮原始响应；格式与失败回退规则见 [模型 API 与兼容层](model-compatibility.md#文本-tool-call-后备解析) | `<0` 自动回退到 `0`；支持热更新 |
 
 ---
@@ -278,6 +279,8 @@ Stream 本地文件投递在同一 Bot 内串行，纯文本不等待上传锁
 
 普通群聊队列过长时，仅裁剪尚未发车的外围请求；已经启动的 AI 调用所等待的 LLM 子请求及重试保留原相对顺序，避免调用方因裁剪而继续等待超时。
 
+普通群聊的新 LLM 子请求入队前，会按模型检查当前等待中的 LLM 数量；达到 `[core].group_llm_queue_max_pending` 时返回可读的 `QueueFull` 错误并记录日志，调用方会清理该请求的等待状态，不裁剪已接收请求。普通自动回复可能在有限次重试后结束而不发送回复。此限制不作用于其他优先级通道或其他模型；已接收任务的重试仍可回插，调低上限也不清空旧任务。它是新请求的排队准入限制，不是总并发或内存上限：在途调用不计入，重试可能使等待数量暂时超过配置值。
+
 请求模式说明：
 - `api_mode="openai.chat_completions"`：走 `AsyncOpenAI.chat.completions.create(...)`
   - `max_tokens > 0` 时发送 `max_tokens`；为 `0` 或负数时省略
@@ -1484,6 +1487,7 @@ Management 的 WebUI 配置按 [§4.23](#423-webui) 的时机生效：密码和
 ### 5.3 明确“会执行热应用”的字段
 
 - `webui.password` / `webui.check_updates` / `webui.stop_timeout_seconds`（Management 的登录密码、检查更新开关与下次停止的收尾期限刷新）
+- `core.group_llm_queue_max_pending`（下一次普通群聊 LLM 入队使用新上限，保留已接收请求与重试）
 - `onebot.file_send_mode` / `onebot.file_send_host`（新投递读取快照；进行中投递及旧 URL 生命周期不变）
 - 模型发车间隔 / 模型名 / 模型池变更（队列间隔刷新）
 - `models.grok.model_name` / `models.grok.queue_interval_seconds`（队列间隔刷新）
diff --git a/src/Undefined/config/config_class.py b/src/Undefined/config/config_class.py
index a4b32c4e..5d8127da 100644
--- a/src/Undefined/config/config_class.py
+++ b/src/Undefined/config/config_class.py
@@ -66,6 +66,7 @@ class Config:
     inverted_question_enabled: bool
     context_recent_messages_limit: int
     ai_request_max_retries: int
+    group_llm_queue_max_pending: int
     missing_tool_call_retries: int
     nagaagent_mode_enabled: bool
     onebot_ws_url: str
diff --git a/src/Undefined/config/env_registry.py b/src/Undefined/config/env_registry.py
index 2bbbb83e..4c84c6d9 100644
--- a/src/Undefined/config/env_registry.py
+++ b/src/Undefined/config/env_registry.py
@@ -60,6 +60,7 @@
     ("core", "admin_qq"): "ADMIN_QQ",
     ("core", "bot_qq"): "BOT_QQ",
     ("core", "forward_proxy_qq"): "FORWARD_PROXY_QQ",
+    ("core", "group_llm_queue_max_pending"): "GROUP_LLM_QUEUE_MAX_PENDING",
     ("core", "superadmin_qq"): "SUPERADMIN_QQ",
     ("features", "pool_enabled"): "MODEL_POOL_ENABLED",
     ("attachments", "use_proxy"): "ATTACHMENTS_USE_PROXY",
diff --git a/src/Undefined/config/hot_reload.py b/src/Undefined/config/hot_reload.py
index 96a0f77c..54d0cf90 100644
--- a/src/Undefined/config/hot_reload.py
+++ b/src/Undefined/config/hot_reload.py
@@ -210,6 +210,11 @@ def _apply_security() -> None:
     def _apply_retries() -> None:
         context.queue_manager.update_max_retries(updated.ai_request_max_retries)
 
+    def _apply_group_llm_queue_limit() -> None:
+        context.queue_manager.update_group_llm_queue_max_pending(
+            updated.group_llm_queue_max_pending
+        )
+
     def _apply_queue_intervals() -> None:
         context.queue_manager.update_model_intervals(
             build_model_queue_intervals(updated)
@@ -292,6 +297,8 @@ def _apply_config_watcher() -> None:
         steps.append(("security", _apply_security))
     if "ai_request_max_retries" in changed_keys:
         steps.append(("ai_request_max_retries", _apply_retries))
+    if "group_llm_queue_max_pending" in changed_keys:
+        steps.append(("group_llm_queue_max_pending", _apply_group_llm_queue_limit))
     if _needs_queue_interval_update(changed_keys):
         steps.append(("queue_intervals", _apply_queue_intervals))
     if _needs_intro_update(changed_keys):
diff --git a/src/Undefined/config/load_sections/core.py b/src/Undefined/config/load_sections/core.py
index b87628c6..2189f2c2 100644
--- a/src/Undefined/config/load_sections/core.py
+++ b/src/Undefined/config/load_sections/core.py
@@ -17,6 +17,7 @@
 )
 
 from ..onebot import parse_file_send_host, parse_file_send_mode
+from ..models import DEFAULT_GROUP_LLM_QUEUE_MAX_PENDING
 
 logger = logging.getLogger(__name__)
 
@@ -136,6 +137,20 @@ def load_core(
     if ai_request_max_retries < 0:
         ai_request_max_retries = 0
 
+    group_llm_queue_limit_raw = _get_value(
+        data, ("core", "group_llm_queue_max_pending"), "GROUP_LLM_QUEUE_MAX_PENDING"
+    )
+    if group_llm_queue_limit_raw is None:
+        group_llm_queue_max_pending = DEFAULT_GROUP_LLM_QUEUE_MAX_PENDING
+    else:
+        group_llm_queue_max_pending = _coerce_int(group_llm_queue_limit_raw, 0)
+        if (
+            isinstance(group_llm_queue_limit_raw, bool)
+            or not isinstance(group_llm_queue_limit_raw, (int, str))
+            or group_llm_queue_max_pending < 1
+        ):
+            raise ValueError("core.group_llm_queue_max_pending 必须为正整数")
+
     missing_tool_call_retries = _coerce_int(
         _get_value(
             data,
@@ -178,6 +193,7 @@ def load_core(
         "repeat_cooldown_minutes": repeat_cooldown_minutes,
         "context_recent_messages_limit": context_recent_messages_limit,
         "ai_request_max_retries": ai_request_max_retries,
+        "group_llm_queue_max_pending": group_llm_queue_max_pending,
         "missing_tool_call_retries": missing_tool_call_retries,
         "nagaagent_mode_enabled": nagaagent_mode_enabled,
         "onebot_ws_url": onebot_ws_url,
diff --git a/src/Undefined/config/models.py b/src/Undefined/config/models.py
index b48d85c4..3f83c151 100644
--- a/src/Undefined/config/models.py
+++ b/src/Undefined/config/models.py
@@ -9,6 +9,7 @@
 from .api_modes import API_MODE_OPENAI_CHAT_COMPLETIONS, normalize_api_mode
 
 HISTORIAN_MIN_POLL_INTERVAL_SECONDS: float = 0.1
+DEFAULT_GROUP_LLM_QUEUE_MAX_PENDING: int = 128
 PROMPT_FILE_INCLUDE_SLOTS: tuple[str, ...] = ("p0", "p1", "p2", "p3", "summary")
 
 # 支持独立 embedding 配置的功能；顺序即文档与校验顺序
diff --git a/src/Undefined/handlers/message_flow.py b/src/Undefined/handlers/message_flow.py
index a1c8d54c..deaf7319 100644
--- a/src/Undefined/handlers/message_flow.py
+++ b/src/Undefined/handlers/message_flow.py
@@ -173,6 +173,7 @@ def __init__(
         self.rate_limiter = RateLimiter(config)
         self.queue_manager = QueueManager(
             max_retries=config.ai_request_max_retries,
+            group_llm_queue_max_pending=config.group_llm_queue_max_pending,
         )
         self.queue_manager.update_model_intervals(build_model_queue_intervals(config))
 
diff --git a/src/Undefined/services/queue_manager.py b/src/Undefined/services/queue_manager.py
index d2164871..07500aff 100644
--- a/src/Undefined/services/queue_manager.py
+++ b/src/Undefined/services/queue_manager.py
@@ -9,6 +9,7 @@
 from dataclasses import dataclass, field
 from typing import Any, Callable, Coroutine
 
+from Undefined.config.models import DEFAULT_GROUP_LLM_QUEUE_MAX_PENDING
 
 logger = logging.getLogger(__name__)
 
@@ -19,6 +20,7 @@
 QUEUE_LANE_GROUP_MENTION = "group_mention"
 QUEUE_LANE_GROUP_NORMAL = "group_normal"
 QUEUE_LANE_BACKGROUND = "background"
+LLM_CALL_REQUEST_TYPES = frozenset({"queued_llm_call", "background_llm_call"})
 
 STRICT_PRIORITY_QUEUE_LANES = (
     QUEUE_LANE_SUPERADMIN,
@@ -90,6 +92,11 @@ def retry_count(self) -> int:
             1 for item in self._items if int(item.get("_retry_count", 0) or 0) > 0
         )
 
+    def llm_call_count(self) -> int:
+        return sum(
+            1 for item in self._items if item.get("type") in LLM_CALL_REQUEST_TYPES
+        )
+
 
 @dataclass
 class ModelQueue:
@@ -124,7 +131,7 @@ def trim_normal_queue(self) -> None:
             outer_indices = [
                 index
                 for index, request in enumerate(requests)
-                if request.get("type") not in {"queued_llm_call", "background_llm_call"}
+                if request.get("type") not in LLM_CALL_REQUEST_TYPES
             ]
             discarded_indices = set(outer_indices[:-2])
             for index, request in enumerate(requests):
@@ -156,12 +163,14 @@ def __init__(
         ai_request_interval: float = 1.0,
         model_intervals: dict[str, float] | None = None,
         max_retries: int = 2,
+        group_llm_queue_max_pending: int = DEFAULT_GROUP_LLM_QUEUE_MAX_PENDING,
     ) -> None:
         if ai_request_interval < 0:
             ai_request_interval = 0.0
         self.ai_request_interval = ai_request_interval
         self._default_interval = ai_request_interval
         self._max_retries = max(0, max_retries)
+        self.update_group_llm_queue_max_pending(group_llm_queue_max_pending)
         self._model_intervals: dict[str, float] = {}
         self._model_queues: dict[str, ModelQueue] = {}
         self._model_work_events: dict[str, asyncio.Event] = {}
@@ -405,6 +414,17 @@ def update_max_retries(self, max_retries: int) -> None:
         self._max_retries = max(0, int(max_retries))
         logger.info("[队列服务] 已更新最大重试次数: max_retries=%s", self._max_retries)
 
+    def update_group_llm_queue_max_pending(self, max_pending: int) -> None:
+        """只更新普通群聊新 LLM 请求的准入上限，保留已接收请求及重试。"""
+        if (
+            isinstance(max_pending, bool)
+            or not isinstance(max_pending, int)
+            or max_pending < 1
+        ):
+            raise ValueError("core.group_llm_queue_max_pending 必须为正整数")
+        self._group_llm_queue_max_pending = max_pending
+        logger.info("[队列服务] 普通群聊 LLM 排队准入上限=%s", max_pending)
+
     def estimate_wait_seconds(self, model_name: str, lane: str) -> float:
         model_queue = self._model_queues.get(model_name)
         if model_queue is None:
@@ -442,6 +462,20 @@ async def _enqueue_lane_request(
         request["_queue_lane"] = lane
         lane_queue = self._get_lane_queue(queue, lane)
         if lane == QUEUE_LANE_GROUP_NORMAL and not insert_second:
+            if (
+                request.get("type") in LLM_CALL_REQUEST_TYPES
+                and lane_queue.llm_call_count() >= self._group_llm_queue_max_pending
+            ):
+                logger.warning(
+                    "[队列拒绝][%s] 普通群聊 LLM 等待队列已满: limit=%s %s",
+                    model_name,
+                    self._group_llm_queue_max_pending,
+                    self._format_request_meta(request),
+                )
+                raise asyncio.QueueFull(
+                    f"普通群聊 LLM 等待队列已满（模型 {model_name}，"
+                    f"上限 {self._group_llm_queue_max_pending}），请稍后重试"
+                )
             queue.trim_normal_queue()
         if insert_second:
             await lane_queue.put_second(request)
diff --git a/tests/test_core_config.py b/tests/test_core_config.py
index 211ad516..80f5bd5a 100644
--- a/tests/test_core_config.py
+++ b/tests/test_core_config.py
@@ -1,8 +1,12 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
+
+import pytest
 
 from Undefined.config.loader import Config
+from Undefined.config.env_registry import ENV_REGISTRY
 
 
 _MINIMAL = """
@@ -34,3 +38,39 @@ def test_missing_tool_call_retries_clamps_negative(tmp_path: Path) -> None:
 def test_missing_tool_call_retries_loads_explicit_value(tmp_path: Path) -> None:
     cfg = _load(tmp_path, "\n[core]\nmissing_tool_call_retries = 5\n")
     assert cfg.missing_tool_call_retries == 5
+
+
+def test_group_llm_queue_limit_defaults_and_env_precedence(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.delenv("GROUP_LLM_QUEUE_MAX_PENDING", raising=False)
+    assert _load(tmp_path).group_llm_queue_max_pending == 128
+    assert ENV_REGISTRY[("core", "group_llm_queue_max_pending")] == (
+        "GROUP_LLM_QUEUE_MAX_PENDING"
+    )
+    monkeypatch.setenv("GROUP_LLM_QUEUE_MAX_PENDING", "32")
+    assert _load(tmp_path).group_llm_queue_max_pending == 32
+    assert (
+        _load(
+            tmp_path, "\n[core]\ngroup_llm_queue_max_pending = 7\n"
+        ).group_llm_queue_max_pending
+        == 7
+    )
+
+
+@pytest.mark.parametrize("value", [0, -1, True, False, 1.5, "bad", "0", "", []])
+def test_invalid_group_llm_queue_limit_is_rejected(value: Any) -> None:
+    with pytest.raises(
+        ValueError, match="core.group_llm_queue_max_pending 必须为正整数"
+    ):
+        Config.from_mapping(
+            {"core": {"group_llm_queue_max_pending": value}}, strict=False
+        )
+
+
+def test_invalid_group_llm_queue_limit_env_is_rejected(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("GROUP_LLM_QUEUE_MAX_PENDING", "-1")
+    with pytest.raises(ValueError, match="必须为正整数"):
+        _load(tmp_path)
diff --git a/tests/test_end_to_end_message_pipeline.py b/tests/test_end_to_end_message_pipeline.py
index 466895c3..5f90006a 100644
--- a/tests/test_end_to_end_message_pipeline.py
+++ b/tests/test_end_to_end_message_pipeline.py
@@ -13,6 +13,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from pathlib import Path
 from typing import Any, cast
 from unittest.mock import AsyncMock
@@ -25,6 +26,7 @@
 from Undefined.config.loader import Config
 from Undefined.faq import FAQStorage
 from Undefined.handlers import MessageHandler
+from Undefined.services.queue_manager import QUEUE_LANE_GROUP_NORMAL
 
 _BASE_MAPPING: dict[str, Any] = {
     "onebot": {"ws_url": "ws://127.0.0.1:3001", "token": ""},
@@ -187,6 +189,29 @@ def _group_event(
     }
 
 
+@pytest.mark.asyncio
+async def test_message_handler_applies_configured_group_llm_queue_limit(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setitem(_BASE_MAPPING["core"], "group_llm_queue_max_pending", 2)
+    handler, _ = _build_handler(tmp_path)
+    monkeypatch.setattr(handler.ai, "request_model", AsyncMock(return_value={}))
+    monkeypatch.setattr(handler.ai, "set_llm_call_result", lambda *_args: None)
+    try:
+        for _ in range(2):
+            await handler.queue_manager.add_queued_llm_request(
+                {"model_config": handler.config.chat_model, "messages": []},
+                lane=QUEUE_LANE_GROUP_NORMAL,
+                model_name="chat-model",
+            )
+        with pytest.raises(asyncio.QueueFull, match="上限 2"):
+            await handler.queue_manager.add_queued_llm_request(
+                {}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat-model"
+            )
+    finally:
+        await handler.close()
+
+
 @pytest.mark.asyncio
 async def test_group_slash_command_round_trip_invokes_onebot(tmp_path: Path) -> None:
     handler, onebot = _build_handler(tmp_path)
diff --git a/tests/test_group_llm_queue_capacity.py b/tests/test_group_llm_queue_capacity.py
new file mode 100644
index 00000000..258d5aeb
--- /dev/null
+++ b/tests/test_group_llm_queue_capacity.py
@@ -0,0 +1,185 @@
+"""Reject excess new ordinary-group LLM calls without abandoning accepted calls."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+
+from Undefined.ai.client import AIClient
+from Undefined.config import Config
+from Undefined.config.hot_reload import HotReloadContext, apply_config_updates
+from Undefined.config.manager import ConfigManager
+from Undefined.services.queue_manager import (
+    ALL_QUEUE_LANES,
+    QUEUE_LANE_GROUP_NORMAL,
+    QueueManager,
+)
+
+
+@pytest.mark.asyncio
+async def test_default_group_llm_limit_rejects_only_excess_new_calls() -> None:
+    queue = QueueManager()
+    for index in range(128):
+        await queue.add_queued_llm_request(
+            {"request_id": str(index)}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+        )
+    with pytest.raises(asyncio.QueueFull, match="普通群聊 LLM 等待队列已满.*128"):
+        await queue.add_queued_llm_request(
+            {"request_id": "excess"}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+        )
+    assert [
+        item["request_id"]
+        for item in queue._model_queues["chat"].group_normal_queue.drain()
+    ] == [str(index) for index in range(128)]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("llm_type", ["queued_llm_call", "background_llm_call"])
+async def test_full_llm_queue_rejects_before_trimming_outer_requests(
+    llm_type: str,
+) -> None:
+    queue = QueueManager(group_llm_queue_max_pending=1)
+    await queue.add_group_normal_request(
+        {"type": llm_type, "request_id": "accepted"}, model_name="chat"
+    )
+    for index in range(10):
+        await queue.add_group_normal_request(
+            {"type": "auto_reply", "request_id": str(index)}, model_name="chat"
+        )
+    pending = queue._model_queues["chat"].group_normal_queue
+    before = list(pending._items)
+    assert len(before) == 11
+    with pytest.raises(asyncio.QueueFull):
+        await queue.add_group_normal_request(
+            {"type": llm_type, "request_id": "excess"}, model_name="chat"
+        )
+    assert list(pending._items) == before
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "lane", [lane for lane in ALL_QUEUE_LANES if lane != QUEUE_LANE_GROUP_NORMAL]
+)
+async def test_full_group_queue_does_not_restrict_other_lane_or_model(
+    lane: str,
+) -> None:
+    queue = QueueManager(group_llm_queue_max_pending=1)
+    await queue.add_queued_llm_request(
+        {}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+    )
+    for _ in range(2):
+        await queue.add_queued_llm_request({}, lane=lane, model_name="chat")
+    await queue.add_queued_llm_request(
+        {}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="agent"
+    )
+    assert queue.snapshot()["models"]["chat"][lane] == 2
+    assert queue.snapshot()["models"]["agent"][QUEUE_LANE_GROUP_NORMAL] == 1
+
+
+@pytest.mark.asyncio
+async def test_accepted_llm_retry_can_requeue_above_new_admission_limit() -> None:
+    queue = QueueManager(group_llm_queue_max_pending=1, max_retries=1)
+    await queue.add_queued_llm_request(
+        {"request_id": "first"}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+    )
+    pending = queue._model_queues["chat"].group_normal_queue
+    first = pending.get_nowait()
+    await queue.add_queued_llm_request(
+        {"request_id": "second"}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+    )
+
+    async def fail(_request: dict[str, Any]) -> None:
+        raise OSError("retryable upstream failure")
+
+    queue.start(fail)
+    await queue._safe_handle_request(first, "chat", "普通群聊")
+    assert [item["request_id"] for item in pending._items] == ["second", "first"]
+    assert first["_retry_count"] == 1
+    with pytest.raises(asyncio.QueueFull):
+        await queue.add_queued_llm_request(
+            {"request_id": "third"}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+        )
+
+
+@pytest.mark.asyncio
+async def test_submit_rejection_retires_only_the_rejected_waiter() -> None:
+    queue = QueueManager(group_llm_queue_max_pending=1)
+    client: Any = object.__new__(AIClient)
+    client._queue_manager = queue
+    client._pending_llm_calls = {}
+    client._get_runtime_config = lambda: SimpleNamespace(ai_request_max_retries=0)
+
+    async def submit() -> dict[str, Any]:
+        return cast(
+            dict[str, Any],
+            await client.submit_queued_llm_call(
+                model_config=SimpleNamespace(model_name="chat", max_tokens=64),
+                messages=[{"role": "user", "content": "hello"}],
+                queue_lane=QUEUE_LANE_GROUP_NORMAL,
+            ),
+        )
+
+    accepted = asyncio.create_task(submit())
+    try:
+        await asyncio.sleep(0)
+        original = dict(client._pending_llm_calls)
+        assert len(original) == 1
+        with pytest.raises(asyncio.QueueFull, match="请稍后重试"):
+            await submit()
+        assert client._pending_llm_calls == original
+        assert queue.snapshot()["models"]["chat"][QUEUE_LANE_GROUP_NORMAL] == 1
+    finally:
+        accepted.cancel()
+        await asyncio.gather(accepted, return_exceptions=True)
+    assert not client._pending_llm_calls
+
+
+@pytest.mark.asyncio
+async def test_config_hot_reload_changes_admission_without_dropping_queued_calls(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "config.toml"
+    path.write_text("[core]\ngroup_llm_queue_max_pending=2\n", encoding="utf-8")
+    manager = ConfigManager(path)
+    config = manager.load(strict=False)
+    queue = QueueManager(group_llm_queue_max_pending=config.group_llm_queue_max_pending)
+    context = HotReloadContext(
+        ai_client=cast(Any, SimpleNamespace()),
+        queue_manager=queue,
+        config_manager=manager,
+        security_service=cast(Any, SimpleNamespace()),
+    )
+
+    def update(updated: Config, changes: dict[str, tuple[Any, Any]]) -> None:
+        apply_config_updates(updated, changes, context)
+
+    manager.subscribe(update)
+    for index in range(2):
+        await queue.add_queued_llm_request(
+            {"request_id": str(index)}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+        )
+    pending = queue._model_queues["chat"].group_normal_queue
+    before = list(pending._items)
+    path.write_text("[core]\ngroup_llm_queue_max_pending=1\n", encoding="utf-8")
+    assert manager.reload() == {"group_llm_queue_max_pending": (2, 1)}
+    assert list(pending._items) == before
+    with pytest.raises(asyncio.QueueFull):
+        await queue.add_queued_llm_request(
+            {}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+        )
+    path.write_text("[core]\ngroup_llm_queue_max_pending=3\n", encoding="utf-8")
+    assert manager.reload() == {"group_llm_queue_max_pending": (1, 3)}
+    await queue.add_queued_llm_request(
+        {"request_id": "new"}, lane=QUEUE_LANE_GROUP_NORMAL, model_name="chat"
+    )
+    assert list(pending._items)[:2] == before
+    assert pending.qsize() == 3
+    path.write_text("[core]\ngroup_llm_queue_max_pending=0\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="必须为正整数"):
+        manager.reload()
+    assert config.group_llm_queue_max_pending == 3
+    assert pending.qsize() == 3

From b58b4fb54d491ee088ff65217f4d64506c8a3dd6 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:35:07 +0800
Subject: [PATCH 113/121] fix(webui): report failed configuration restores

---
 docs/management-api.md                   |  2 ++
 docs/webui-guide.md                      |  2 ++
 src/Undefined/webui/static/js/main.js    | 21 +++++++++++++-----
 tests/frontend/runtime_chat_harness.js   | 28 ++++++++++++++++++++++--
 tests/test_webui_config_save_behavior.py | 18 +++++++++++++++
 5 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/docs/management-api.md b/docs/management-api.md
index b163d3ba..2df0c053 100644
--- a/docs/management-api.md
+++ b/docs/management-api.md
@@ -144,6 +144,8 @@ WebUI 的并发请求共用同一次 refresh token 轮换；旧会话的迟到
 
 整体保存、PATCH、历史恢复、模板同步及密码更新使用同一文件读改写锁，原子落盘后在主事件循环更新运行时配置。请求取消会先等待写入与更新收敛；密码更新同时刷新管理设置并撤销旧会话令牌。历史列表和恢复读取与备份裁剪串行，已被裁剪的备份恢复返回 `404`。
 
+WebUI 历史恢复同时检查 HTTP 状态及响应中的 `success`，失败时显示服务端错误并保留当前表单与历史面板，不会误报恢复成功或重载覆盖当前编辑。
+
 ## 5. 日志、系统与 Bot 控制
 
 ### 日志
diff --git a/docs/webui-guide.md b/docs/webui-guide.md
index cc2f3b04..9132dfd6 100644
--- a/docs/webui-guide.md
+++ b/docs/webui-guide.md
@@ -72,6 +72,8 @@ WebUI 的主要页签如下。
 
 恢复历史、同步模板和重新加载会先清除旧的待保存快照与输入计时器，等正在保存的请求结束后再执行；期间表单暂停编辑，完成后展示服务器上的配置，避免旧自动保存覆盖恢复结果。
 
+历史恢复须同时得到成功 HTTP 状态和 `success=true` 才显示“已恢复配置”并刷新表单。HTTP 错误、业务拒绝或网络失败会显示错误，保留当前表单与历史面板并恢复编辑，可直接重试恢复。
+
 > 配置支持热更新——大多数配置项修改后即时生效，无需重启 Bot。需要重启的项（如 `onebot_ws_url`、`webui_port`）会在保存时提示。
 
 ### 日志查看（Logs）
diff --git a/src/Undefined/webui/static/js/main.js b/src/Undefined/webui/static/js/main.js
index 2b0b9b4b..c8dfc428 100644
--- a/src/Undefined/webui/static/js/main.js
+++ b/src/Undefined/webui/static/js/main.js
@@ -979,13 +979,22 @@ async function init() {
                             return;
                         try {
                             await runConfigOperation(async () => {
-                                await api("/api/config/history/restore", {
-                                    method: "POST",
-                                    headers: {
-                                        "Content-Type": "application/json",
+                                const res = await api(
+                                    "/api/config/history/restore",
+                                    {
+                                        method: "POST",
+                                        headers: {
+                                            "Content-Type": "application/json",
+                                        },
+                                        body: JSON.stringify({ name }),
                                     },
-                                    body: JSON.stringify({ name }),
-                                });
+                                );
+                                const data = await res.json();
+                                if (!res.ok || !data.success) {
+                                    throw new Error(
+                                        data.error || t("config.save_error"),
+                                    );
+                                }
                                 showToast(
                                     t("config.history_restored"),
                                     "success",
diff --git a/tests/frontend/runtime_chat_harness.js b/tests/frontend/runtime_chat_harness.js
index fa3274c7..a12e780c 100644
--- a/tests/frontend/runtime_chat_harness.js
+++ b/tests/frontend/runtime_chat_harness.js
@@ -3624,6 +3624,7 @@ async function configReplacement(env, operation) {
     let serverMode = "local";
     let finishPatch;
     let patchCount = 0;
+    let restoreAttempts = 0;
     window.confirm = () => true;
     window.fetch = async (url, options = {}) => {
         const route = String(url);
@@ -3642,6 +3643,15 @@ async function configReplacement(env, operation) {
             backups: [{ name: "config_previous.toml", mtime: 1, size: 1 }],
         });
         if (route === "/api/config/history/restore") {
+            restoreAttempts += 1;
+            if (restoreAttempts === 1 && operation.startsWith("restore_failure_")) {
+                if (operation === "restore_failure_network") {
+                    throw new Error("isolated restore failure");
+                }
+                return response(operation === "restore_failure_http" ? 500 : 200, {
+                    success: false, error: "isolated restore failure",
+                });
+            }
             serverMode = "local";
             return response(200, { success: true });
         }
@@ -3669,7 +3679,7 @@ async function configReplacement(env, operation) {
     host.value = "obsolete-host";
     host.dispatchEvent(new window.Event("input", { bubbles: true }));
     let completion;
-    if (operation === "restore" || operation === "restore_sync") {
+    if (operation.startsWith("restore")) {
         window.get("btnConfigHistory").click();
         await tick();
         window.document.querySelector("[data-restore-name]").click();
@@ -3691,8 +3701,22 @@ async function configReplacement(env, operation) {
     if (completion) await completion;
     await tick();
     await settle(1100);
+    let afterFailure = null;
+    if (operation.startsWith("restore_failure_")) {
+        afterFailure = {
+            formMode: mode().value,
+            formHost: window.document.querySelector('[data-path="onebot.file_send_host"].config-input').value,
+            formInert: window.get("formSections").inert,
+            panelVisible: window.get("configHistoryPanel").style.display !== "none",
+            summaryCount: calls.filter((url) => url === "/api/config/summary").length,
+            toasts: window.document.querySelector(".toast-container")?.textContent || "",
+        };
+        window.document.querySelector("[data-restore-name]").click();
+        await tick();
+    }
     return {
         beforeResponse,
+        afterFailure,
         patchCount,
         calls,
         serverMode,
@@ -3702,7 +3726,7 @@ async function configReplacement(env, operation) {
     };
 }
 
-for (const operation of ["restore", "sync", "reload", "restore_sync"]) {
+for (const operation of ["restore", "sync", "reload", "restore_sync", "restore_failure_http", "restore_failure_api", "restore_failure_network"]) {
     SCENARIOS[`config_replacement_${operation}`] = (env) => configReplacement(env, operation);
 }
 
diff --git a/tests/test_webui_config_save_behavior.py b/tests/test_webui_config_save_behavior.py
index afd47128..6ef9eba0 100644
--- a/tests/test_webui_config_save_behavior.py
+++ b/tests/test_webui_config_save_behavior.py
@@ -83,3 +83,21 @@ def test_config_replacement_discards_old_snapshots_and_waits_for_inflight_save(
         assert result["calls"].index("/api/config/history/restore") < result[
             "calls"
         ].index("/api/config/sync-template?write=false")
+
+
+@pytest.mark.parametrize("outcome", ["http", "api", "network"])
+def test_failed_config_restore_preserves_form_and_allows_retry(outcome: str) -> None:
+    result = run_scenario(f"config_replacement_restore_failure_{outcome}")
+    failure = result["afterFailure"]
+    assert failure["formMode"] == "url"
+    assert failure["formHost"] == "obsolete-host"
+    assert failure["formInert"] is False
+    assert failure["panelVisible"] is True
+    assert failure["summaryCount"] == 1
+    assert "isolated restore failure" in failure["toasts"]
+    assert "已恢复配置" not in failure["toasts"]
+    assert result["serverMode"] == result["formMode"] == "local"
+    assert result["formInert"] is False
+    assert result["patchCount"] == 1
+    assert result["calls"].count("/api/config/history/restore") == 2
+    assert "已恢复配置" in result["toasts"]

From a43db99405f93bcb46079397af634c4607d3fb9a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:38:38 +0800
Subject: [PATCH 114/121] fix(chat): preserve new jobs and retire stale stream
 starts

---
 apps/undefined-chat/README.md                 |   3 +-
 .../src/chat-store/resume-completion.test.ts  | 190 +++++++++++++++++-
 apps/undefined-chat/src/chat-store/store.ts   |  36 +++-
 docs/undefined-chat.md                        |   3 +-
 4 files changed, 225 insertions(+), 7 deletions(-)

diff --git a/apps/undefined-chat/README.md b/apps/undefined-chat/README.md
index 82b37f1f..3dc21abd 100644
--- a/apps/undefined-chat/README.md
+++ b/apps/undefined-chat/README.md
@@ -18,7 +18,8 @@ Undefined Chat 是 `apps/undefined-chat/` 下的 Tauri v2 + React 19 原生聊
 - 自动滚动：智能跟随底部，可在设置面板开关，偏好持久化到 localStorage。
 - 重命名只更新目标会话标题，保留当前会话、输入草稿与移动端面板；请求期间切换会话也不会被迟到响应切回。
 - 事件：SSE 优先，断开时 JSON fallback（指数退避重连，活跃任务持续重试）；完整任务快照恢复消息与已结束调用，并按快照游标续接，旧 Runtime 的正文前缀也会保留。
-- 恢复连接时，已从 active 列表消失的本地任务会补刷所属会话的权威历史，包括非当前会话；仍在历史落盘的终态任务继续保留发送锁，已删除会话不再请求。
+- 恢复连接时，已从 active 列表消失的本地任务会补刷所属会话的权威历史，包括非当前会话；仍在历史落盘的终态任务继续保留发送锁，已删除会话不再请求。刷新期间刚获发送确认的新任务不会被较早取得的空列表删除，也会继续订阅事件。
+- SSE 订阅按任务去重在途启动；恢复或结束任务后，迟到的旧订阅会被关闭，旧启动失败不会覆盖当前订阅或启动额外轮询。
 - 快捷键：Ctrl/Cmd+N 新会话，Ctrl/Cmd+K 聚焦输入并打开命令模式，Ctrl/Cmd+/ 切换侧栏，Ctrl/Cmd+, 打开设置，Escape 关闭当前弹层/抽屉。
 - i18n：中英双语运行时切换，提供语言切换 UI，并按系统语言自动检测默认语言。
 
diff --git a/apps/undefined-chat/src/chat-store/resume-completion.test.ts b/apps/undefined-chat/src/chat-store/resume-completion.test.ts
index 71bf2529..4dba85bb 100644
--- a/apps/undefined-chat/src/chat-store/resume-completion.test.ts
+++ b/apps/undefined-chat/src/chat-store/resume-completion.test.ts
@@ -1,8 +1,11 @@
 import { describe, expect, test, vi } from "vitest";
 import type {
 	ActiveJobsResponse,
+	ChatJob,
+	EventStreamSubscription,
 	HistoryResponse,
 	JobEventsJsonResponse,
+	RuntimeHealth,
 } from "../runtime-client/types";
 import {
 	conversation,
@@ -14,10 +17,12 @@ import { createChatStore } from "./store";
 
 function deferred<T>() {
 	let resolve!: (value: T) => void;
-	const promise = new Promise<T>((resolvePromise) => {
+	let reject!: (reason: Error) => void;
+	const promise = new Promise<T>((resolvePromise, rejectPromise) => {
 		resolve = resolvePromise;
+		reject = rejectPromise;
 	});
-	return { promise, resolve };
+	return { promise, resolve, reject };
 }
 
 function resumeFixture() {
@@ -80,6 +85,187 @@ function resumeFixture() {
 }
 
 describe("completed jobs omitted from a reconnect snapshot", () => {
+	test("deduplicates a send ACK subscription while resume is still installing its listener", async () => {
+		const sending = deferred<ChatJob>();
+		const listener = deferred<() => void>();
+		const stream = deferred<EventStreamSubscription>();
+		const accepted = job({ hasTimelineSnapshot: true });
+		const client = runtimeClientStub({
+			sendMessage: vi.fn(() => sending.promise),
+			startJobEventStream: vi
+				.fn()
+				.mockImplementationOnce(() => stream.promise)
+				.mockResolvedValue({
+					subscriptionId: "duplicate-subscription",
+					jobId: accepted.jobId,
+					afterSeq: 0,
+				}),
+			cancelJob: vi.fn(async () =>
+				job({ status: "cancelled", historyFinalized: true }),
+			),
+		});
+		const store = createChatStore({ client });
+		await store.bootstrap();
+		store.updateDraft("default", "question");
+		const sendRequest = store.sendSelectedMessage();
+		vi.mocked(client.getActiveJobs).mockResolvedValueOnce({
+			job: accepted,
+			jobs: [accepted],
+		});
+		vi.mocked(client.listenRuntimeSse).mockImplementationOnce(
+			() => listener.promise,
+		);
+		const resuming = store.bootstrap({ resuming: true });
+		await vi.waitFor(() =>
+			expect(client.listenRuntimeSse).toHaveBeenCalledTimes(2),
+		);
+		sending.resolve(accepted);
+		await vi.waitFor(() =>
+			expect(client.startJobEventStream).toHaveBeenCalledTimes(1),
+		);
+		listener.resolve(() => {});
+		await resuming;
+		stream.resolve({
+			subscriptionId: "single-subscription",
+			jobId: accepted.jobId,
+			afterSeq: 0,
+		});
+		await sendRequest;
+		expect(client.startJobEventStream).toHaveBeenCalledTimes(1);
+		await store.cancelJob(accepted.jobId);
+		expect(client.stopJobEventStream).toHaveBeenCalledExactlyOnceWith(
+			"single-subscription",
+		);
+	});
+
+	test.each(["success", "failure"])(
+		"ignores late pre-resume stream %s without replacing the recovered subscription",
+		async (outcome) => {
+			const sending = deferred<ChatJob>();
+			const health = deferred<RuntimeHealth>();
+			const oldStream = deferred<EventStreamSubscription>();
+			const accepted = job({ hasTimelineSnapshot: true });
+			const client = runtimeClientStub({
+				sendMessage: vi.fn(() => sending.promise),
+				startJobEventStream: vi
+					.fn()
+					.mockImplementationOnce(() => oldStream.promise)
+					.mockResolvedValueOnce({
+						subscriptionId: "recovered-subscription",
+						jobId: accepted.jobId,
+						afterSeq: 0,
+					}),
+				cancelJob: vi.fn(async () =>
+					job({ status: "cancelled", historyFinalized: true }),
+				),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("default", "question");
+			const sendRequest = store.sendSelectedMessage();
+			vi.mocked(client.probeRuntime).mockImplementationOnce(
+				() => health.promise,
+			);
+			const resuming = store.bootstrap({ resuming: true });
+			await vi.waitFor(() =>
+				expect(client.getActiveJobs).toHaveBeenCalledTimes(2),
+			);
+			sending.resolve(accepted);
+			await vi.waitFor(() =>
+				expect(client.startJobEventStream).toHaveBeenCalledTimes(1),
+			);
+			health.resolve({ ok: true, status: 200, body: "ok" });
+			await resuming;
+			expect(client.startJobEventStream).toHaveBeenCalledTimes(2);
+			if (outcome === "success") {
+				oldStream.resolve({
+					subscriptionId: "obsolete-subscription",
+					jobId: accepted.jobId,
+					afterSeq: 0,
+				});
+			} else {
+				oldStream.reject(new Error("obsolete stream start failed"));
+			}
+			await sendRequest;
+			if (outcome === "success") {
+				expect(client.stopJobEventStream).toHaveBeenCalledWith(
+					"obsolete-subscription",
+				);
+			} else {
+				expect(client.stopJobEventStream).not.toHaveBeenCalled();
+			}
+			expect(client.fetchJobEventsJson).not.toHaveBeenCalled();
+			await store.cancelJob(accepted.jobId);
+			expect(client.stopJobEventStream).toHaveBeenLastCalledWith(
+				"recovered-subscription",
+			);
+		},
+	);
+
+	test.each([false, true])(
+		"retains a send accepted during resume without retaining a completed job (snapshot includes send: %s)",
+		async (snapshotIncludesSend) => {
+			const sending = deferred<ChatJob>();
+			const health = deferred<RuntimeHealth>();
+			const previous = job({ jobId: "completed-B", conversationId: "B" });
+			const accepted = job({
+				jobId: "new-A",
+				conversationId: "A",
+				hasTimelineSnapshot: true,
+			});
+			const snapshot = { ...accepted, lastSeq: 3, reply: "newer reply" };
+			const client = runtimeClientStub({
+				listConversations: vi.fn(async () => ({
+					conversations: [conversation({ id: "A" }), conversation({ id: "B" })],
+					activeJob: null,
+					defaultConversationId: "A",
+					virtualUserId: "webchat",
+				})),
+				getActiveJobs: vi
+					.fn()
+					.mockResolvedValueOnce({ job: previous, jobs: [previous] })
+					.mockResolvedValueOnce({
+						job: snapshotIncludesSend ? snapshot : null,
+						jobs: snapshotIncludesSend ? [snapshot] : [],
+					}),
+				sendMessage: vi.fn(() => sending.promise),
+			});
+			const store = createChatStore({ client });
+			await store.bootstrap();
+			store.updateDraft("A", "question-A");
+			const sendRequest = store.sendSelectedMessage();
+			vi.mocked(client.probeRuntime).mockImplementationOnce(
+				() => health.promise,
+			);
+			const resuming = store.bootstrap({
+				preserveSelectionId: "A",
+				resuming: true,
+			});
+			await vi.waitFor(() =>
+				expect(client.getActiveJobs).toHaveBeenCalledTimes(2),
+			);
+			sending.resolve(accepted);
+			await sendRequest;
+			expect(store.getSnapshot().activeJobsByConversation.A?.jobId).toBe(
+				"new-A",
+			);
+			health.resolve({ ok: true, status: 200, body: "ok" });
+			await resuming;
+			expect(store.getSnapshot().activeJobsByConversation.A).toEqual(
+				snapshotIncludesSend ? snapshot : accepted,
+			);
+			expect(store.getSnapshot().activeJobsByConversation.B).toBeUndefined();
+			expect(store.getSnapshot().jobConversationById).toEqual({ "new-A": "A" });
+			expect(store.getSnapshot().connectionState).toBe("streaming");
+			expect(client.startJobEventStream).toHaveBeenLastCalledWith({
+				jobId: "new-A",
+				conversationId: "A",
+				afterSeq: snapshotIncludesSend ? 3 : 0,
+			});
+			expect(client.startJobEventStream).toHaveBeenCalledTimes(3);
+		},
+	);
+
 	test("refreshes a nonselected conversation even when its old JSON response arrives after resume", async () => {
 		const { client, store, start, complete } = resumeFixture();
 		const terminal = deferred<JobEventsJsonResponse>();
diff --git a/apps/undefined-chat/src/chat-store/store.ts b/apps/undefined-chat/src/chat-store/store.ts
index 72db683b..eae2ee0a 100644
--- a/apps/undefined-chat/src/chat-store/store.ts
+++ b/apps/undefined-chat/src/chat-store/store.ts
@@ -755,6 +755,7 @@ export function createChatStore({
 	let historyRequestGeneration = 0;
 	const listeners = new Set<() => void>();
 	const subscriptionsByJob = new Map<string, string>();
+	const streamRequestsByJob = new Map<string, symbol>();
 	const fallbackTimersByJob = new Map<string, ReturnType<typeof setTimeout>>();
 	/** 每个 job 当前的 JSON 轮询退避间隔（ms），随连续失败指数增长、成功后重置 */
 	const fallbackBackoffByJob = new Map<string, number>();
@@ -803,6 +804,7 @@ export function createChatStore({
 			void client.stopJobEventStream(subscriptionId);
 		}
 		subscriptionsByJob.clear();
+		streamRequestsByJob.clear();
 		for (const timer of fallbackTimersByJob.values()) {
 			clearTimeout(timer);
 		}
@@ -913,16 +915,25 @@ export function createChatStore({
 	async function startStreamForJob(job: ChatJob): Promise<void> {
 		if (runtimeSuspended) return;
 		const generation = runtimeGeneration;
-		if (subscriptionsByJob.has(job.jobId)) {
+		if (
+			subscriptionsByJob.has(job.jobId) ||
+			streamRequestsByJob.has(job.jobId)
+		) {
 			return;
 		}
+		const request = Symbol();
+		streamRequestsByJob.set(job.jobId, request);
+		const isCurrentRequest = (): boolean =>
+			generation === runtimeGeneration &&
+			streamRequestsByJob.get(job.jobId) === request &&
+			state.activeJobsByConversation[job.conversationId]?.jobId === job.jobId;
 		try {
 			const subscription = await client.startJobEventStream({
 				jobId: job.jobId,
 				afterSeq: Math.max(state.eventCursorByJob[job.jobId] ?? 0, job.lastSeq),
 				conversationId: job.conversationId,
 			});
-			if (generation !== runtimeGeneration) {
+			if (!isCurrentRequest()) {
 				if (subscription.subscriptionId) {
 					void client.stopJobEventStream(subscription.subscriptionId);
 				}
@@ -932,9 +943,13 @@ export function createChatStore({
 				subscriptionsByJob.set(job.jobId, subscription.subscriptionId);
 			}
 		} catch {
-			if (generation !== runtimeGeneration) return;
+			if (!isCurrentRequest()) return;
 			// job 已建立；订阅失败只切换传输方式，不能回滚成功发送的输入。
 			fetchJobEventsFallback(job.jobId);
+		} finally {
+			if (streamRequestsByJob.get(job.jobId) === request) {
+				streamRequestsByJob.delete(job.jobId);
+			}
 		}
 	}
 
@@ -954,6 +969,7 @@ export function createChatStore({
 			return;
 		}
 		stopFallbackPolling(jobId);
+		streamRequestsByJob.delete(jobId);
 		const subscriptionId = subscriptionsByJob.get(jobId);
 		if (subscriptionId) {
 			subscriptionsByJob.delete(jobId);
@@ -1109,6 +1125,9 @@ export function createChatStore({
 				return;
 			}
 
+			const jobsBeforeRefresh = new Set(
+				Object.values(state.activeJobsByConversation).map((job) => job.jobId),
+			);
 			const [health, conversationsResponse, activeJobs, commands] =
 				await Promise.all([
 					client.probeRuntime(),
@@ -1158,6 +1177,17 @@ export function createChatStore({
 					recoveredJobs.push(snapshot);
 				}
 			}
+			// 快照请求期间，先前发出的发送请求可能刚获 ACK；旧列表不能删除新任务。
+			// 请求开始前已存在的任务仍以服务端列表为准，允许回收离线时已完成的任务。
+			for (const current of Object.values(state.activeJobsByConversation)) {
+				if (jobsBeforeRefresh.has(current.jobId)) continue;
+				const index = recoveredJobs.findIndex(
+					(snapshot) => snapshot.conversationId === current.conversationId,
+				);
+				if (index < 0) recoveredJobs.push(current);
+				else if (recoveredJobs[index].jobId !== current.jobId)
+					recoveredJobs[index] = current;
+			}
 			const historyConversationIds = new Set(selected ? [selected] : []);
 			const recoveredJobIds = new Set(recoveredJobs.map((item) => item.jobId));
 			// 已落盘终态会从 active 列表消失；补刷仍存在的非当前会话缓存。
diff --git a/docs/undefined-chat.md b/docs/undefined-chat.md
index 2da6e0a2..5c0d8b11 100644
--- a/docs/undefined-chat.md
+++ b/docs/undefined-chat.md
@@ -68,9 +68,10 @@ Runtime 请求必须由 Tauri command 拼接到已配置 origin 下，避免 Rea
 - 旧 Runtime 缺少 `current_timeline` 时，客户端保留快照的完整正文前缀，JSON fallback 先续接事件以保留已有调用树；重放缓冲缺失消息时按权威正文恢复。同一任务恢复时，推进游标前复用 JSON 回放补齐后台工具开始、结束和 Agent 阶段变化，即使正文没有改变；回放失败保留旧游标供 SSE 继续恢复。旧服务无法仅凭正文恢复已超出事件缓冲的完整 Agent 嵌套顺序。
 - 重叠 JSON 请求按 job 身份和请求代次校验；已结束、已被替换的 job 或落后于已消费事件游标的回包会被忽略，避免迟到响应覆盖下一轮任务或回退回复内容。
 - 取消请求错误和 SSE 的连接状态通知同样只作用于对应的活跃 job，旧任务的迟到通知不会改写新任务的错误或连接状态。
+- 同一任务正在建立 SSE 订阅时复用该次启动，恢复连接或任务结束会使在途启动失效。迟到的旧订阅句柄会立即关闭，旧启动失败不会触发新的 JSON 轮询；迟到结果不会覆盖当前订阅。
 - `done` / `error` / `cancelled` 事件到达后，客户端继续保留当前会话的 job 和发送锁，通过 JSON polling 等待 `history_finalized=true`，确认历史落盘后再刷新历史并清理订阅。
 - 历史分页的 `before` / `next_before` 是非负数值索引；React 与 Tauri command 使用同一数值契约，首屏不传 `before`。
-- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs；每个任务接受完整快照及其游标后重新建立事件订阅。已从 active 列表消失的本地任务还会补刷所属会话的权威历史，包括非当前会话；已删除会话不再请求。请求途中已消费更高序号时保留更新的本地状态。
+- Android 回到前台时执行 `store.bootstrap()`，刷新配置、会话、当前历史页和 active jobs；每个任务接受完整快照及其游标后重新建立事件订阅。已从 active 列表消失的本地任务还会补刷所属会话的权威历史，包括非当前会话；已删除会话不再请求。请求途中已消费更高序号时保留更新的本地状态。刷新期间刚获发送确认的新任务也会保留，旧空列表不能撤销其订阅；刷新开始前已存在且服务端已结束的任务仍按权威结果回收。
 - 同一 Runtime 重建订阅时保留已开始的终态历史刷新；切换 Runtime 或暂停保存连接配置时，旧请求响应仍会被丢弃。
 
 ## 安全存储

From fdc7bf23ccf68c16d0384956060da58f23f5ca81 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 11:39:20 +0800
Subject: [PATCH 115/121] docs(review): clarify v3.18.5 failure and recovery
 boundaries

---
 CHANGELOG.md  | 10 +++++-----
 docs/memes.md |  2 ++
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index faa60c15..680aa6da 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,16 +3,16 @@
 本版本集中修复聊天续接、消息发送和后台任务在切换会话、取消、断线、重启及写入失败时的状态错乱：保留已经完成的投递与提交，避免重复回复、旧响应覆盖新操作，以及界面显示成功但数据尚未保存的问题。
 
 - 聊天恢复与历史一致性：WebChat 只有在任务收尾、历史落盘并释放会话占用后才确认完成，创建任务失败会撤销占用，删除会话与接收新任务按顺序处理。完整任务快照保留正文、工具调用与嵌套 Agent 时间线，Chat 客户端修复断线续接、旧版事件重放和分页恢复；离线期间已经完成的会话也会刷新，旧连接、旧会话和旧请求的迟到结果不会覆盖当前状态。
-- WebUI 与客户端交互：修复切换会话后发送归属错误、旧轮询重复追加正文、迟到历史清空刚发送的消息，以及发送失败覆盖后续草稿的问题。保存连接配置时暂停请求，将未完成上传标记失败并忽略迟到结果，旧缓存迁移失败保留原数据；日志、工作流、表情包编辑和微信登录弹窗隔离各自请求，刷新与翻页保留未保存的编辑。登录凭据刷新串行执行，避免并发刷新相互失效。
-- 消息投递不再被后续故障误判：微信按每次服务端确认及时记录已发送状态，支持展开嵌套转发；历史、附件登记或使用统计失败不会把已送达内容当作未发送。分片或批量发送已有部分成功、或投递结果无法确认时，微信、抖音、JM 等业务降级不再重发整条内容；仍保留对明确未投递内容的降级。微信帐号变更与客户端启停串行，OneBot 重连不再等待消息处理任务阻塞；arXiv 去重按实际平台与投递地址隔离。
+- WebUI 与客户端交互：修复切换会话后发送归属错误、旧轮询重复追加正文、迟到历史清空刚发送的消息，以及发送失败覆盖后续草稿的问题。保存连接配置时暂停请求，将未完成上传标记失败并忽略迟到结果，旧缓存迁移失败保留原数据；日志、工作流、表情包编辑和微信登录弹窗隔离各自请求，刷新与翻页保留未保存的编辑。恢复配置失败会保留表单并显示错误，不再误报恢复成功；登录凭据刷新串行执行，避免并发刷新相互失效。
+- 消息投递不再被后续故障误判：微信按每次服务端确认及时记录已发送状态，支持展开嵌套转发；历史、附件登记或使用统计失败不会把已送达内容当作未发送。分片或批量发送已有部分成功、或投递结果无法确认时，微信、抖音、JM 等业务降级不再重发整条内容；仍保留对明确未投递内容的降级。令牌失效、会话暂停、配置错误及明确的连接前失败保留原异常，不再误标为可能送达；认证问题不触发拆分消息的结构降级。微信帐号变更与客户端启停串行，OneBot 重连不再等待消息处理任务阻塞；arXiv 去重按实际平台与投递地址隔离。
 - 配置保存与热更新：整体保存、增量修改、恢复、模板同步和密码更新共用原子写入顺序，同一时刻的备份不会互相覆盖；取消请求会等已开始的写入与必要更新完成。热更新失败可以重试，监听器重启会补读停止窗口内的修改，连续调整轮询间隔不会留下多个监听任务或继续使用旧间隔。内存构建配置不再意外读取本地文件，损坏的 TOML 即使使用 `strict=False` 也会明确报错。
-- 停止与取消：停止 Bot 先关闭新任务入口，等待已接收的回复、后台任务和持久化收尾，再关闭模型队列与消息通道。新增 `[webui].stop_timeout_seconds`（环境变量 `WEBUI_STOP_TIMEOUT_SECONDS`），**默认 `0` 表示等待自然结束，正整数才会在对应秒数后强制终止**；停止按钮、关闭 WebUI 和更新前停止共用此规则。取消模型请求会同步清理排队及重试任务，普通群聊队列裁剪保留已启动调用所依赖的子请求。
+- 停止与取消：停止 Bot 先关闭新任务入口，等待已接收的回复、后台任务和持久化收尾，再关闭模型队列与消息通道。新增 `[webui].stop_timeout_seconds`（环境变量 `WEBUI_STOP_TIMEOUT_SECONDS`），**默认 `0` 表示等待自然结束，正整数才会在对应秒数后强制终止**；停止按钮、关闭 WebUI 和更新前停止共用此规则。取消模型请求会同步清理排队及重试任务，普通群聊队列裁剪保留已启动调用所依赖的子请求。新增 `[core].group_llm_queue_max_pending`（默认 `128`，支持热更新），每模型普通群聊 LLM 等待队列满时明确拒绝新请求并清理其等待状态，保留已接收任务与重试；这是排队准入限制，不限制在途调用或总内存，过载时普通自动回复可能结束而不发送消息。
 - 连续消息与工具状态：已经回复完成的投机批次及时结束，后续消息开启新批次，避免把旧输入再次回复；批次取消只作用于对应任务，不会误伤独立的 @ 或拍一拍回复。`task_progress` 在多轮工具调用间共享，技能热重载保留在途统计；多模态分析缓存使用完整媒体来源、类型与补充指令，避免长链接或 data URL 前缀相同而串用结果。
 - 记忆与知识库：长期记忆和会话数据在落盘成功后才发布新状态，取消会等待已开始的提交，写入失败不会让内存与磁盘各自保留不同版本。知识文件替换先完成新内容读取、嵌入和写入，再清理旧索引；读取、嵌入或新块写入失败时保留旧索引供重试。侧写昵称刷新与史官跳过合并时也会补齐检索索引，索引失败不再提前确认完成；记忆时间筛选统一比较含时区与不含时区的时间。
 - 表情包生命周期：重分析不会覆盖期间的人工编辑、恢复已删除内容或影响同 UID 重新入库的记录；停用、删除与附件缓存失效保持一致，搜索不会返回已停用条目。使用统计失败保留发送成功结果，容量清理跳过刚置顶或修改的候选，删除失败保留可重试记录；异常退出遗留的处理任务会在后续轮询中恢复，正在执行的任务不会被重复调度。
-- 自动化流程：持久化按顺序完成，取消不会让旧快照覆盖新状态；嵌套并行循环只合并本轮修改的变量，避免覆盖同级节点刚产生的输出。`loop.times.count=0` 正确跳过循环，负数、布尔值和字符串不再被当作有效次数。
+- 自动化流程：持久化按顺序完成，取消不会让旧快照覆盖新状态；嵌套并行循环只合并本轮修改的变量，避免覆盖同级节点刚产生的输出。`loop.times.count=0` 正确跳过循环，旧存档的 `count:null` 兼容默认次数；新建、更新与启用任务仍严格拒绝负数、布尔值、字符串及 `null`。
 - 文件与附件：统一解析本地 `file://` URI，保留中文、空格及原始路径中的百分号；CQ 参数转义与解码保留链接里的逗号、方括号和实体文本。HTTP 压缩响应按传输字节校验完整性、按解压后大小执行容量限制。JM、Bilibili、arXiv 下载及 Python 执行目录在取消后等待后台文件操作结束再清理；JM 配置的会话目录生效，畸形输入和单章异常不再拖垮整次处理。侧写路径与归档解压目标限制在各自目录内，缓存清理拒绝符号链接目录，TAR 解压启用安全过滤。
-- 原生显示与连接：附件下载以独占方式创建文件，避免覆盖同名文件；图片仍显示时保留其 Blob，代码高亮失败回落纯文本，生产构建拆分体积并保留完整语言支持。Console 迁移旧连接时保留协议与 IPv6 地址，Android 生命周期监听即使延迟注册也会在退出后释放。
+- 原生显示与连接：附件下载以独占方式创建文件，避免覆盖同名文件；图片仍显示时保留其 Blob，代码高亮失败回落纯文本，生产构建拆分体积并保留完整语言支持。Console 迁移旧连接时保留协议与 IPv6 地址，Android 生命周期监听即使延迟注册也会在退出后释放。恢复应用时保留刷新途中刚获确认的新任务，同一任务不会重复建立在途 SSE 订阅；迟到旧句柄会关闭，避免覆盖当前订阅或在取消后泄漏。
 - 部署与维护：部署向导中断不再继续写配置，备份名称不冲突，IPv6 服务地址正确加括号；容器模式为 Python 解释器映射宿主 Docker 可见的共享目录，LxMusic 配置变化会触发容器重建。`restore_profile.py restore` 现在同时恢复侧写并同步检索正文与向量，失败后可用 `sync` 补齐，**执行前须停止机器人及其他写入进程**。重嵌入的 `--dry-run` 在临时副本上读取，不修改源向量库，但仍会调用嵌入 API；侧写恢复的 `--dry-run` 不写盘、不调用模型。版本脚本支持失败后重跑，补齐全部版本文件与锁文件，并将此前已修改的版本目标纳入提交。
 
 ---
diff --git a/docs/memes.md b/docs/memes.md
index 9c876c8a..4ed599a8 100644
--- a/docs/memes.md
+++ b/docs/memes.md
@@ -63,4 +63,6 @@ gif_analysis_frames = 6         # GIF 的抽帧数量
 
 容量清理复用人工删除的内容锁和修订校验；候选列出后才置顶或编辑的条目会跳过，多个清理任务串行检查当前容量。删除会先完成向量、原图、预览与 GIF 临时帧清理，最后移除 SQLite 记录。索引或文件删除失败时，元数据仍保留并计入容量，可在故障恢复后重试删除；此前已清理的文件允许再次删除。
 
+这不是跨 SQLite、向量库与文件系统的原子删除：失败时可能已移除向量或部分文件，语义检索可能暂时缺少该条目，管理记录仍保留以供重试。接口会报告失败，不会宣称已完成；不要提前删除这条元数据，否则后续按 UID 重试将失去资源清理入口。
+
 * Management API 完整接口参阅 [Management API — Runtime 代理](management-api.md#6-runtime-代理)，Runtime API 直连接口参阅 [Runtime API — 表情包库](openapi.md#表情包库)。

From 49607174eecbaa46f1aad065626324bc1a36f9f9 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 12:11:44 +0800
Subject: [PATCH 116/121] fix(weixin): preserve retryable HTTP rejections

---
 docs/wechat-ilink.md              |   2 +
 src/Undefined/weixin/transport.py |   5 ++
 tests/test_weixin_delivery.py     | 108 +++++++++++++++++++++++++++++-
 3 files changed, 114 insertions(+), 1 deletion(-)

diff --git a/docs/wechat-ilink.md b/docs/wechat-ilink.md
index dcd6f35f..6658ae56 100644
--- a/docs/wechat-ilink.md
+++ b/docs/wechat-ilink.md
@@ -122,6 +122,8 @@ iLink 帐号只接受登录结果声明的那个私聊来源。若收到帐号 I
 
 消息请求进入 SDK 的 `sendmessage` 派发阶段后，读写中断、远端协议异常或无法确认的服务端错误会转换为仓库共享的“投递结果未确认”错误，JM、Bilibili 和消息工具也会据此阻止降级重发，保留原始异常供诊断。配置错误、令牌失效、会话暂停，以及 HTTPX 明确发生在连接或连接池阶段的失败保留原异常，不会被误报为可能送达；其中认证与暂停仍不属于可更换消息结构解决的拒绝。连接前失败且没有任何分片成功时，业务层可按既有规则降级；一旦本条已有分片成功，仍禁止整条重发。媒体预检、`getuploadurl` 与 CDN 上传尚未派发消息，失败也不会被误标为已投递。
 
+HTTP 408、425、429 明确拒绝当前请求，保留 SDK 的 `HttpError`，不标记为投递结果不确定；这些错误不触发移除引用或拆分消息的结构降级。尚无分片成功时，调用方可以按自己的重试策略重新投递；传输适配层本身不会自动重试。一旦已有分片成功，后续即使收到上述状态码也继续禁止整条重发。HTTP 503 仍按投递结果不确定处理。
+
 媒体上传由 SDK 在 `getuploadurl` 和 CDN 上传阶段处理临时错误重试；`media_upload_attempts` 控制总尝试次数。多项目消息会先按 `media_upload_concurrency` 有界并发上传媒体，再严格按原始项目顺序组装发送请求，因此并发只缩短准备时间，不改变用户看到的顺序。
 
 Bot 层通过 `messages.send_voice(uid, address?)` 显式选择“作为语音发送”。普通 `<attachment uid="file_xxx"/>` 始终保留原始文件语义，即使扩展名是 `.wav`；`CQ:record`、`CQ:audio` 和内部明确标记为 voice 的媒体回调则发送原生语音。QQ 侧继续转换为 `CQ:record`，微信侧先用 FFmpeg 归一化为 24 kHz、16-bit、单声道 PCM，再由 `silk-python` 编码为 Tencent SILK。部署机必须能从 `PATH` 找到 `ffmpeg`；缺失、音频无效或超出 `[weixin].media_max_size_mb` 时会在任何消息段发出前失败，不会自动改成文件。
diff --git a/src/Undefined/weixin/transport.py b/src/Undefined/weixin/transport.py
index 9970d8e0..259a1455 100644
--- a/src/Undefined/weixin/transport.py
+++ b/src/Undefined/weixin/transport.py
@@ -63,6 +63,11 @@ async def send_message(
                 (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout),
             ):
                 raise
+            # 408/425/429 是服务端明确拒绝（超时未收全、过早数据、限流），
+            # 请求肯定未被正常投递，可整体重试；不能按“结果未确认”禁止重发，
+            # 也不属于可用移除引用/拆分解决的结构性拒绝（sender 侧不做 markdown 降级）。
+            if isinstance(exc, HttpError) and exc.status_code in {408, 425, 429}:
+                raise
             raise WeixinDeliveryUncertainError(
                 "微信投递结果未确认，禁止自动重发"
             ) from exc
diff --git a/tests/test_weixin_delivery.py b/tests/test_weixin_delivery.py
index 61b5e7ff..d6ed59eb 100644
--- a/tests/test_weixin_delivery.py
+++ b/tests/test_weixin_delivery.py
@@ -14,6 +14,7 @@
     AsyncWeixinIlinkClient,
     ClientOptions,
     ConfigurationError,
+    HttpError,
     MediaKind,
     OutboundMediaItem,
     RequestTimeoutError,
@@ -26,7 +27,7 @@
 from Undefined.config import Config
 from Undefined.jm.sender import _send_result
 from Undefined.utils.message_targets import DeliveryAddress
-from Undefined.utils.sender import AddressBoundSender, MessageSender
+from Undefined.utils.sender import MAX_MESSAGE_LENGTH, AddressBoundSender, MessageSender
 from Undefined.weixin.models import WeixinAccount
 from Undefined.weixin.service import WeixinService
 from Undefined.weixin.store import UndefinedIlinkStateStore
@@ -188,6 +189,111 @@ def handle(request: httpx.Request) -> httpx.Response:
         assert "投递结果未确认" in status
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status_code", [400, 408, 425, 429, 503])
+async def test_sdk_http_rejection_preserves_delivery_classification(
+    status_code: int,
+) -> None:
+    requests: list[httpx.Request] = []
+
+    def reject(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(status_code, request=request)
+
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    async with httpx.AsyncClient(transport=httpx.MockTransport(reject)) as http_client:
+        client = AsyncWeixinIlinkClient(
+            credentials,
+            transport=UndefinedIlinkTransport(http_client=http_client),
+        )
+        error_type = WeixinDeliveryUncertainError if status_code == 503 else HttpError
+        with pytest.raises(error_type) as raised:
+            await client.send_text("peer", "message")
+
+    assert len(requests) == 1
+    assert bool(getattr(raised.value, "delivery_uncertain", False)) is (
+        status_code == 503
+    )
+    assert is_definitive_weixin_delivery_rejection(raised.value) is (status_code == 400)
+    http_error = raised.value.__cause__ if status_code == 503 else raised.value
+    assert isinstance(http_error, HttpError)
+    assert http_error.status_code == status_code
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status_code", [408, 425, 429, 503])
+@pytest.mark.parametrize("partial", [False, True])
+async def test_sdk_http_rejection_blocks_reply_fallback_and_partial_resend(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    status_code: int,
+    partial: bool,
+) -> None:
+    requests: list[dict[str, Any]] = []
+
+    def reject(request: httpx.Request) -> httpx.Response:
+        requests.append(json.loads(request.content)["msg"])
+        if partial and len(requests) == 1:
+            return httpx.Response(200, json={"ret": 0}, request=request)
+        return httpx.Response(status_code, request=request)
+
+    config = Config.from_mapping(
+        {"weixin": {"enabled": True, "state_dir": str(tmp_path)}}, strict=False
+    )
+    service = WeixinService(config)
+    history = MagicMock()
+    history.find_private_message_by_id = AsyncMock(
+        return_value={
+            "message_id": "inbound-1",
+            "display_name": "微信用户",
+            "message": "旧消息",
+            "transport": {"channel": "wechat", "address": "wechat:12345"},
+        }
+    )
+    sender = MessageSender(MagicMock(), history, bot_qq=999, config=MagicMock())
+    sender.set_weixin_service(service)
+    credentials = WeixinCredentials(
+        "account", "token", "https://isolated.invalid", "user"
+    )
+    message = "x" * (MAX_MESSAGE_LENGTH + 1) if partial else "message"
+    try:
+        async with httpx.AsyncClient(
+            transport=httpx.MockTransport(reject)
+        ) as http_client:
+            client = AsyncWeixinIlinkClient(
+                credentials,
+                transport=UndefinedIlinkTransport(http_client=http_client),
+            )
+            monkeypatch.setattr(
+                service,
+                "_resolve_runtime",
+                AsyncMock(
+                    return_value=(
+                        SimpleNamespace(peer_id="peer"),
+                        SimpleNamespace(client=client),
+                    )
+                ),
+            )
+            uncertain = partial or status_code == 503
+            error_type = WeixinDeliveryUncertainError if uncertain else HttpError
+            with pytest.raises(error_type) as raised:
+                await sender.send_address_message(
+                    DeliveryAddress("wechat", 12345),
+                    message,
+                    auto_history=False,
+                    reply_to="inbound-1",
+                )
+        assert bool(getattr(raised.value, "delivery_uncertain", False)) is uncertain
+        assert len(requests) == (2 if partial else 1)
+        if partial and status_code != 503:
+            assert isinstance(raised.value.__cause__, HttpError)
+            assert raised.value.__cause__.status_code == status_code
+    finally:
+        await service.stop()
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "error_type",

From bc6533e21c321d5a16534432aa4f60c68334d273 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 12:13:22 +0800
Subject: [PATCH 117/121] fix(onebot): reject new events while disconnecting

---
 docs/python-api.md                        |  6 +++
 src/Undefined/onebot/client.py            |  1 +
 tests/test_onebot_connection_lifecycle.py | 50 +++++++++++++++++++++++
 3 files changed, 57 insertions(+)

diff --git a/docs/python-api.md b/docs/python-api.md
index 950892df..7441a831 100644
--- a/docs/python-api.md
+++ b/docs/python-api.md
@@ -164,6 +164,12 @@ client = OneBotClient(cfg.onebot_ws_url, cfg.onebot_token, config_getter=lambda:
 
 `OneBotFileTransport` 的 `chunk_size`、`timeout` 和 `store` 可用于测试注入，不是额外业务配置。URL 模式需要将同一客户端传入 `RuntimeAPIContext.onebot`，并显式启动 `RuntimeAPIServer`；服务会绑定客户端的临时文件存储与实际监听端口，OneBot 发送方法不会自动启动 Runtime。准备错误为 `FileTransferError`，含 `mode`、`stage`、`user_message` 与 `file_transfer_error` 标记；投递发出后结果未确认仍为 `OneBotDeliveryUncertainError`。详细模式与部署要求见 [配置说明](configuration.md#43-onebot-协议端连接)。
 
+### `OneBotClient` 关闭与重连
+
+`stop_accepting_messages()` 关闭新消息与通知事件入口，但保留已有 API 响应的处理，供已接收任务收尾；随后可用 `drain_message_tasks()` 等待这些任务完成。`disconnect()` 会先关闭新事件入口，再关闭 WebSocket 并取消、回收剩余消息任务，直接调用它也不会在断开期间新建消息任务。
+
+`disconnect()` 用于终止当前客户端，后续启动应创建新的 `OneBotClient`。网络断线时，`run_with_reconnect()` 的自动重连路径不会调用 `disconnect()`，也不会关闭新事件入口。
+
 ### `Config.builder`
 
 链式构建器，适合在 base mapping 上覆盖少量字段：
diff --git a/src/Undefined/onebot/client.py b/src/Undefined/onebot/client.py
index 90a930e4..d2fcdfcf 100644
--- a/src/Undefined/onebot/client.py
+++ b/src/Undefined/onebot/client.py
@@ -192,6 +192,7 @@ async def connect(self) -> None:
 
     async def disconnect(self) -> None:
         """断开连接"""
+        self.stop_accepting_messages()
         self.stop()
         try:
             if self.ws:
diff --git a/tests/test_onebot_connection_lifecycle.py b/tests/test_onebot_connection_lifecycle.py
index 584bb0af..b5588bc9 100644
--- a/tests/test_onebot_connection_lifecycle.py
+++ b/tests/test_onebot_connection_lifecycle.py
@@ -107,6 +107,56 @@ async def handler(data: dict[str, Any]) -> None:
     assert not client._tasks
 
 
+@pytest.mark.asyncio
+async def test_disconnect_rejects_late_events_but_keeps_api_responses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = OneBotClient("ws://example.invalid")
+    socket = _WebSocket()
+    closing = asyncio.Event()
+    allow_close = asyncio.Event()
+    handled: list[dict[str, Any]] = []
+
+    async def close() -> None:
+        closing.set()
+        await allow_close.wait()
+        await _WebSocket.close(socket)
+
+    async def handler(data: dict[str, Any]) -> None:
+        handled.append(data)
+
+    monkeypatch.setattr(socket, "close", close)
+    client.ws = cast(Any, socket)
+    client.set_message_handler(handler)
+    response: asyncio.Future[dict[str, Any]] = (
+        asyncio.get_running_loop().create_future()
+    )
+    client._pending_responses["pending"] = response
+    disconnecting = asyncio.create_task(client.disconnect())
+    try:
+        await asyncio.wait_for(closing.wait(), 1)
+        await client._dispatch_message({"post_type": "message"})
+        await client._dispatch_message(
+            {"post_type": "notice", "notice_type": "notify", "sub_type": "poke"}
+        )
+        await client._dispatch_message(
+            {"post_type": "notice", "notice_type": "group_increase"}
+        )
+        await client._dispatch_message(
+            {"post_type": "notice", "notice_type": "group_decrease"}
+        )
+        await client._dispatch_message({"echo": "pending", "status": "ok"})
+        await asyncio.sleep(0)
+        assert not handled
+        assert not client._tasks
+        assert response.result()["status"] == "ok"
+    finally:
+        allow_close.set()
+        await asyncio.wait_for(disconnecting, 1)
+    assert client.ws is None
+    assert not client._tasks
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize("phase", ["sleep", "connect"])
 async def test_reconnect_gap_cancellation_collects_previous_handlers(

From 377b867915802c1623d4c7fd3df1ffbb68b445a9 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 12:23:59 +0800
Subject: [PATCH 118/121] test(review): cover wizard cancellation and clarify
 cleanup limits

---
 docs/configuration.md       |  2 +-
 docs/deployment.md          |  2 ++
 tests/test_deploy_runner.py | 41 +++++++++++++++++++------------------
 3 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 8be01a68..7d89e3c2 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1109,7 +1109,7 @@ api_key = "replace-with-your-key"
 - PDF 下载或上传失败时不会额外发送失败提示，只保留论文信息消息。
 - 同一论文按物理投递地址去重：同一地址的并发请求复用在途发送，发送完成后一小时内跳过重复请求。`qq:<QQ号>`、`wechat:<QQ号>` 和 `group:<群号>` 独立计数；同一逻辑 QQ 在 QQ 和微信请求论文时，两端都能收到。
 - 自动提取仍默认发送论文信息与 PDF；若用户要求分析 arXiv 论文内容，`file_analysis_agent` 会通过 `arxiv_paper(output_mode=uid)` 获取 PDF 附件 UID 后再分析；只需标题、作者、摘要和链接等元信息时可使用 `arxiv_paper(output_mode=info)`。
-- PDF 预检、流式下载或落盘阶段取消时，会清理本次独立任务目录；网络等待可直接取消，已开始的文件操作先等实际线程完成再清理并传播取消。发送和附件 UID 模式共用此规则。
+- PDF 预检、流式下载或落盘阶段取消时，会清理本次独立任务目录；网络等待可直接取消，已开始的文件操作先等实际线程完成再清理并传播取消。发送和附件 UID 模式共用此规则。此保证针对 `asyncio` 任务取消，不代表所有 `BaseException` 下都能完成清理；清理期间再次发生进程级中断、事件循环被强制停止或进程被强杀时，目录仍可能残留。
 
 ---
 
diff --git a/docs/deployment.md b/docs/deployment.md
index c654a65e..d9150e3f 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -205,6 +205,8 @@ uv run deploy up
 
 向导在最终确认前只读取配置，选择“否”或按 Ctrl+C 取消都不会生成文件或初始化子模块；Ctrl+C 会立即结束命令，不会采用默认的“继续”。已有 `config.toml` 支持 UTF-8 BOM 编码。`container` 模式还会为 Python 解释器自动映射已共享的 `deploy/data/cache/python_interpreter/`，让宿主 Docker 从正确的宿主路径读取执行文件。手工挂载 Docker socket 的容器需按 [Python 解释器工具说明](../src/Undefined/skills/tools/python_interpreter/README.md#容器内使用宿主-docker)配置共享路径。
 
+向导的模式、服务、NagaAgent、绑定地址和最终确认输入均可用 Ctrl+C 取消，CLI 会统一输出“已取消。”并以退出码 `1` 结束，不打印异常堆栈。最终确认选择“否”则正常返回退出码 `0`。
+
 ---
 
 ## pip/uv tool 部署（快速体验）
diff --git a/tests/test_deploy_runner.py b/tests/test_deploy_runner.py
index c22c0cda..326b6d9f 100644
--- a/tests/test_deploy_runner.py
+++ b/tests/test_deploy_runner.py
@@ -659,11 +659,22 @@ def unexpected_side_effect(*args: object, **kwargs: object) -> None:
 
 
 @pytest.mark.parametrize("existing_config", (False, True))
-def test_ctrl_c_at_final_confirmation_aborts_without_side_effects(
+@pytest.mark.parametrize(
+    "interrupt_prompt",
+    [
+        pytest.param("请输入编号 [", id="mode"),
+        pytest.param("请输入编号，逗号或空格分隔", id="services"),
+        pytest.param("拉取 NagaAgent 子模块吗？", id="nagaagent"),
+        pytest.param("绑定地址 [", id="port-bind"),
+        pytest.param("按以上计划继续？", id="confirmation"),
+    ],
+)
+def test_ctrl_c_in_wizard_aborts_without_side_effects(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
     existing_config: bool,
+    interrupt_prompt: str,
 ) -> None:
     repo = tmp_path / "repo"
     repo.mkdir()
@@ -674,35 +685,25 @@ def test_ctrl_c_at_final_confirmation_aborts_without_side_effects(
     monkeypatch.setattr(runner, "repo_root", lambda: repo)
     monkeypatch.setattr(runner, "wizard_enabled", lambda options: True)
 
-    def _interrupt_final_confirmation(prompt: str) -> str:
-        if "按以上计划继续" in prompt:
+    def _interrupt_prompt(prompt: str) -> str:
+        if interrupt_prompt in prompt:
             raise KeyboardInterrupt
+        if "拉取 NagaAgent 子模块吗？" in prompt:
+            return "y"
         return ""
 
     def _unexpected_side_effect(*args: object, **kwargs: object) -> None:
         raise AssertionError("Ctrl+C 取消前不能写入子模块或调用 Docker")
 
-    monkeypatch.setattr("builtins.input", _interrupt_final_confirmation)
+    monkeypatch.setattr("builtins.input", _interrupt_prompt)
     monkeypatch.setattr(nagaagent, "ensure_submodule", _unexpected_side_effect)
     monkeypatch.setattr(docker_cli, "check_availability", _unexpected_side_effect)
 
-    assert (
-        cli.main(
-            [
-                "up",
-                "--mode",
-                "container",
-                "--with",
-                "",
-                "--with-nagaagent",
-                "--port-bind",
-                "127.0.0.1",
-            ]
-        )
-        == EXIT_ERROR
-    )
+    assert cli.main(["up"]) == EXIT_ERROR
     assert {path.name: path.read_bytes() for path in repo.iterdir()} == before
-    assert "已取消。" in capsys.readouterr().out
+    captured = capsys.readouterr()
+    assert "已取消。" in captured.out
+    assert "Traceback" not in captured.out + captured.err
 
 
 def test_up_accepts_bom_config(

From e815810d9425f309df081b376ff51e86a39a557f Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 13:14:29 +0800
Subject: [PATCH 119/121] fix(knowledge): handle source removal during indexing

---
 docs/knowledge.md                  |  2 +-
 src/Undefined/knowledge/manager.py | 21 +++++++---
 tests/test_knowledge.py            | 63 ++++++++++++++++++++++++++++++
 3 files changed, 80 insertions(+), 6 deletions(-)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index 79a29d9d..ff6039e0 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -188,7 +188,7 @@ chunk_size=4, chunk_overlap=1 → step=3
 
 `.manifest.json` 记录每个文件的 SHA256 hash。扫描时只对新增或内容变更的文件重新嵌入，未变更的文件跳过。
 
-变更文件先完成读取与嵌入，再写入新块，成功后才删除该来源的旧块并更新 hash。读取、嵌入或新块写入失败时保留旧索引和旧 hash，下次扫描可重试；主动删除文件或把内容清空则会移除其旧索引。索引写入与清理串行执行，取消时先等待已发起的磁盘操作完成。
+变更文件先完成读取与嵌入，再写入新块，成功后才删除该来源的旧块并更新 hash。hash 或正文读取遇到暂时性 I/O、编码错误时，保留旧索引和旧 hash，并继续扫描其他文件；嵌入或新块写入失败也保留旧索引供下次重试。扫描前删除文件，或扫描列出文件后在 hash / 正文读取时确认文件已不存在，都会移除其索引和 manifest 条目；把内容清空则移除旧索引并记录新的 hash。索引写入与清理串行执行，取消时先等待已发起的磁盘操作完成。
 
 ### 站台/发车队列
 
diff --git a/src/Undefined/knowledge/manager.py b/src/Undefined/knowledge/manager.py
index e81f0f8b..820d391e 100644
--- a/src/Undefined/knowledge/manager.py
+++ b/src/Undefined/knowledge/manager.py
@@ -282,13 +282,22 @@ async def embed_knowledge_base(self, kb_name: str) -> int:
 
         for text_file in text_files:
             relative_source = text_file.relative_to(kb_dir).as_posix()
-            fhash = await self._file_hash(text_file)
-            if manifest.get(relative_source) == fhash:
-                continue
-            if store is None:
-                store = self._get_store(kb_name)
             try:
+                fhash = await self._file_hash(text_file)
+                if manifest.get(relative_source) == fhash:
+                    continue
                 content = await asyncio.to_thread(text_file.read_text, "utf-8")
+            except FileNotFoundError:
+                # 文件列表是快照；hash 或正文读取期间也可能删除源文件。
+                if store is None:
+                    store = self._get_store(kb_name)
+                await store.delete_by_source(relative_source)
+                manifest.pop(relative_source, None)
+                manifest_changed = True
+                logger.info(
+                    "[知识库] kb=%s removed source=%s", kb_name, relative_source
+                )
+                continue
             except (OSError, UnicodeDecodeError):
                 logger.warning(
                     "[知识库] 读取失败，保留旧索引: kb=%s source=%s",
@@ -296,6 +305,8 @@ async def embed_knowledge_base(self, kb_name: str) -> int:
                     relative_source,
                 )
                 continue
+            if store is None:
+                store = self._get_store(kb_name)
             lines = chunk_lines(content, self._chunk_size, self._chunk_overlap)
             if not lines:
                 await store.delete_by_source(relative_source)
diff --git a/tests/test_knowledge.py b/tests/test_knowledge.py
index e042358d..80979234 100644
--- a/tests/test_knowledge.py
+++ b/tests/test_knowledge.py
@@ -497,6 +497,69 @@ async def test_embed_removes_deleted_sources(tmp_path: Path) -> None:
     assert json.loads(manifest_path.read_text("utf-8")) == {}
 
 
+@pytest.mark.parametrize("phase", ["hash", "read"])
+@pytest.mark.parametrize("missing", [False, True])
+async def test_scan_handles_file_io_failure_without_losing_other_sources(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    phase: str,
+    missing: bool,
+) -> None:
+    manager, _ = _make_manager(tmp_path)
+    kb_dir = _make_kb(
+        tmp_path, "kb1", {"a.txt": "updated contents", "z.txt": "healthy contents"}
+    )
+    source_path = kb_dir / "texts/a.txt"
+    manifest_path = kb_dir / ".manifest.json"
+    manifest_path.write_text('{"texts/a.txt":"outdated"}', "utf-8")
+    store = manager._get_store("kb1")
+    await store.add_chunks(
+        ["old contents"], [[0.1, 0.2]], {"source": "texts/a.txt", "kb": "kb1"}
+    )
+    read_bytes = Path.read_bytes
+    read_text = Path.read_text
+
+    def fail_source(path: Path) -> None:
+        if path != source_path:
+            return
+        if missing:
+            path.unlink()
+            raise FileNotFoundError(path)
+        raise OSError("source temporarily unreadable")
+
+    def read_bytes_with_failure(path: Path) -> bytes:
+        fail_source(path)
+        return read_bytes(path)
+
+    def read_text_with_failure(path: Path, *args: Any, **kwargs: Any) -> str:
+        fail_source(path)
+        return read_text(path, *args, **kwargs)
+
+    with monkeypatch.context() as failure_patch:
+        if phase == "hash":
+            failure_patch.setattr(Path, "read_bytes", read_bytes_with_failure)
+        else:
+            failure_patch.setattr(Path, "read_text", read_text_with_failure)
+        assert await manager.embed_knowledge_base("kb1") == 1
+
+    manifest = json.loads(manifest_path.read_text("utf-8"))
+    assert store._collection.get(where={"source": "texts/z.txt"})["documents"] == [
+        "healthy contents"
+    ]
+    assert "texts/z.txt" in manifest
+    old_documents = store._collection.get(where={"source": "texts/a.txt"})["documents"]
+    if missing:
+        assert old_documents == []
+        assert "texts/a.txt" not in manifest
+    else:
+        assert old_documents == ["old contents"]
+        assert manifest["texts/a.txt"] == "outdated"
+        assert await manager.embed_knowledge_base("kb1") == 1
+        assert store._collection.get(where={"source": "texts/a.txt"})["documents"] == [
+            "updated contents"
+        ]
+
+
 async def test_embed_replaces_changed_file_chunks(tmp_path: Path) -> None:
     manager, embedder = _make_manager(tmp_path)
     embedder.embed = AsyncMock(return_value=[[0.1]])

From 8167ee606edd48e3aade04e531bf09083e14ac0a Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 13:17:51 +0800
Subject: [PATCH 120/121] fix(naga): protect UUID failure cleanup and shared
 waiters

---
 docs/naga_integration_contract.md     |   2 +
 docs/openapi.md                       |   1 +
 src/Undefined/api/routes/naga/send.py |  13 +-
 tests/test_runtime_api_naga.py        | 193 ++++++++++++++++++++++++++
 4 files changed, 206 insertions(+), 3 deletions(-)

diff --git a/docs/naga_integration_contract.md b/docs/naga_integration_contract.md
index ad5f27f3..830f1286 100644
--- a/docs/naga_integration_contract.md
+++ b/docs/naga_integration_contract.md
@@ -108,6 +108,8 @@ Authorization: Bearer <config.[naga].api_key>
 - 对同一个 `uuid` 的重复调用：
   - 若 payload 完全一致，则直接复用首个结果
   - 若 payload 不一致，则返回 `409`
+  - 首个请求发生异常并进入失败清理后，会先移除进行中状态并通知等待者，再传播清理期间收到的取消；后续同键请求可以重新尝试。只有首个请求负责清理，等待者不会误删随后重试建立的状态。
+  - 取消某个重复请求只结束它自己的等待，不取消首个请求的共享结果，也不影响其他等待者。
 
 审核规则：
 
diff --git a/docs/openapi.md b/docs/openapi.md
index 57e20c4e..64e326af 100644
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -994,6 +994,7 @@ Naga 集成端点仅在以下条件同时满足时注册：
 - 发送流程支持调用方提供 `uuid` 作为幂等键；相同键的重复请求会直接复用首个结果。
 - 投递成功后，使用次数等统计的持久化失败只记录日志，仍返回实际投递结果并保留 `uuid` 幂等结果；同键重试不会再次发送。统计信息在该次持久化失败后可能暂时未落盘。
 - 已确认的投递结果会先提交幂等状态，再保存使用统计；收尾期间取消请求会等待这段提交和投递租约释放后再传播取消，同键重试仍复用已确认结果。该保护区不包含审核或实际发送，不会把未确认的投递转换为成功。
+- 请求异常退出后的 `uuid` 失败清理由首个请求负责，清理期间取消也会等待进行中状态释放；重复请求的失败或取消只结束自身等待，不取消共享结果、不清理其他请求拥有的状态。
 - `target.qq_id` / `target.group_id` 必须显式提供，并且必须等于已绑定目标。
 - `target.mode` 支持 `private` / `group` / `both`。
 - `message.format` 支持 `text` / `markdown` / `html`。
diff --git a/src/Undefined/api/routes/naga/send.py b/src/Undefined/api/routes/naga/send.py
index 4406da73..36636468 100644
--- a/src/Undefined/api/routes/naga/send.py
+++ b/src/Undefined/api/routes/naga/send.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Awaitable, Callable
 import logging
 import os
@@ -148,6 +149,7 @@ async def naga_messages_send_handler(
             inflight_count,
         )
     result_committed = False
+    owns_request_uuid = False
 
     async def commit_result(response: Response) -> None:
         nonlocal result_committed
@@ -200,11 +202,13 @@ async def commit_result(response: Response) -> None:
                     request_uuid,
                     message_key,
                 )
-                cached_status, cached_payload = await wait_future
+                # 等待者取消只结束自己的请求，不能取消 owner 的共享结果。
+                cached_status, cached_payload = await asyncio.shield(wait_future)
                 return web.json_response(
                     deepcopy(cached_payload),
                     status=int(cached_status),
                 )
+            owns_request_uuid = dedupe_action == "owner"
 
         response = await naga_messages_send_impl(
             ctx,
@@ -224,8 +228,11 @@ async def commit_result(response: Response) -> None:
             await run_cancellation_safe(commit_result(response))
         return response
     except Exception as exc:
-        if request_uuid and not result_committed:
-            await naga_state.fail_request_uuid(request_uuid, message_key, exc)
+        if owns_request_uuid and not result_committed:
+            # 只有 owner 能终结该 UUID；错误清理等锁时也必须抵抗调用方取消。
+            await run_cancellation_safe(
+                naga_state.fail_request_uuid(request_uuid, message_key, exc)
+            )
         raise
     finally:
         remaining = await run_cancellation_safe(naga_state.track_send_done(message_key))
diff --git a/tests/test_runtime_api_naga.py b/tests/test_runtime_api_naga.py
index b78fb033..5cdb73a2 100644
--- a/tests/test_runtime_api_naga.py
+++ b/tests/test_runtime_api_naga.py
@@ -1041,6 +1041,199 @@ async def send_group_message(
     await server.stop()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_cleanup", [False, True])
+async def test_naga_failed_uuid_cleanup_survives_cancellation_and_waiters(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    cancel_cleanup: bool,
+) -> None:
+    entered = asyncio.Event()
+    release_moderation = asyncio.Event()
+    cleanup_started = asyncio.Event()
+
+    class _Security:
+        calls = 0
+
+        async def moderate_naga_message(
+            self, *, message_format: str, content: str
+        ) -> NagaModerationResult:
+            self.calls += 1
+            if self.calls == 1:
+                entered.set()
+                await release_moderation.wait()
+                raise RuntimeError("moderation failed before delivery")
+            return NagaModerationResult(
+                blocked=False,
+                status="passed",
+                categories=[],
+                message="ok",
+                model_name="naga-moderation",
+            )
+
+    store = NagaStore(tmp_path / "naga_bindings.json")
+    await store.submit_binding("alice", qq_id=123, group_id=456, bind_uuid="uuid_a")
+    await store.activate_binding(
+        bind_uuid="uuid_a", naga_id="alice", delivery_signature="sig_1"
+    )
+    sender = _FakeSender()
+    security = _Security()
+    server = _make_server(store=store, sender=sender, security=security)
+    state = server._naga_state
+    fail_request_uuid = state.fail_request_uuid
+    cleanup_calls = 0
+
+    async def tracked_failure(
+        request_uuid: str, payload_hash: str, exc: BaseException
+    ) -> None:
+        nonlocal cleanup_calls
+        cleanup_calls += 1
+        cleanup_started.set()
+        await fail_request_uuid(request_uuid, payload_hash, exc)
+
+    monkeypatch.setattr(state, "fail_request_uuid", tracked_failure)
+    body: dict[str, Any] = {
+        "bind_uuid": "uuid_a",
+        "naga_id": "alice",
+        "delivery_signature": "sig_1",
+        "uuid": "req-failed-cleanup",
+        "target": {"qq_id": 123, "group_id": 456, "mode": "group"},
+        "message": {"format": "text", "content": "hello"},
+    }
+
+    async def send() -> Response:
+        return await server._naga_messages_send_handler(
+            _make_request(
+                json_body=body, headers={"Authorization": "Bearer shared-key"}
+            )
+        )
+
+    owner = asyncio.create_task(send())
+    waiter: asyncio.Task[Response] | None = None
+    lock_held = False
+    try:
+        await asyncio.wait_for(entered.wait(), 1)
+        waiter = asyncio.create_task(send())
+        await asyncio.sleep(0)
+        assert sum(state.send_inflight.values()) == 2
+        await state.request_uuid_lock.acquire()
+        lock_held = True
+        release_moderation.set()
+        await asyncio.wait_for(cleanup_started.wait(), 1)
+        if cancel_cleanup:
+            owner.cancel()
+            await asyncio.sleep(0)
+            owner.cancel()
+            await asyncio.sleep(0)
+        state.request_uuid_lock.release()
+        lock_held = False
+        expected_error = asyncio.CancelledError if cancel_cleanup else RuntimeError
+        with pytest.raises(expected_error):
+            await asyncio.wait_for(owner, 1)
+        assert not state.request_uuid_inflight
+        with pytest.raises(RuntimeError, match="moderation failed"):
+            await asyncio.wait_for(waiter, 1)
+        assert cleanup_calls == 1  # 等待者不拥有失败请求，不能再清理该 UUID。
+        assert not state.send_inflight
+        assert not store._active_deliveries
+        assert sender.group_messages == []
+        retry = await send()
+        assert retry.status == 200
+        assert sender.group_messages == [(456, "hello")]
+        assert security.calls == 2
+    finally:
+        release_moderation.set()
+        if lock_held:
+            state.request_uuid_lock.release()
+        pending = [owner, *([waiter] if waiter is not None else [])]
+        for task in pending:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*pending, return_exceptions=True)
+        await server.stop()
+
+
+@pytest.mark.asyncio
+async def test_naga_cancelled_uuid_waiter_keeps_owner_and_other_waiters(
+    tmp_path: Path,
+) -> None:
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    class _Security:
+        calls = 0
+
+        async def moderate_naga_message(
+            self, *, message_format: str, content: str
+        ) -> NagaModerationResult:
+            self.calls += 1
+            entered.set()
+            await release.wait()
+            return NagaModerationResult(
+                blocked=False,
+                status="passed",
+                categories=[],
+                message="ok",
+                model_name="naga-moderation",
+            )
+
+    store = NagaStore(tmp_path / "naga_bindings.json")
+    await store.submit_binding("alice", qq_id=123, group_id=456, bind_uuid="uuid_a")
+    await store.activate_binding(
+        bind_uuid="uuid_a", naga_id="alice", delivery_signature="sig_1"
+    )
+    sender = _FakeSender()
+    security = _Security()
+    server = _make_server(store=store, sender=sender, security=security)
+    body: dict[str, Any] = {
+        "bind_uuid": "uuid_a",
+        "naga_id": "alice",
+        "delivery_signature": "sig_1",
+        "uuid": "req-cancelled-waiter",
+        "target": {"qq_id": 123, "group_id": 456, "mode": "group"},
+        "message": {"format": "text", "content": "hello"},
+    }
+
+    async def send() -> Response:
+        return await server._naga_messages_send_handler(
+            _make_request(
+                json_body=body, headers={"Authorization": "Bearer shared-key"}
+            )
+        )
+
+    owner = asyncio.create_task(send())
+    tasks = [owner]
+    try:
+        await asyncio.wait_for(entered.wait(), 1)
+        cancelled_waiter = asyncio.create_task(send())
+        tasks.append(cancelled_waiter)
+        await asyncio.sleep(0)
+        cancelled_waiter.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(cancelled_waiter, 1)
+        future = server._naga_state.request_uuid_inflight[body["uuid"]][1]
+        assert not future.done()
+        assert not owner.done()
+        other_waiter = asyncio.create_task(send())
+        tasks.append(other_waiter)
+        await asyncio.sleep(0)
+        release.set()
+        first, second = await asyncio.wait_for(asyncio.gather(owner, other_waiter), 1)
+        assert first.status == second.status == 200
+        assert _json(first) == _json(second)
+        assert sender.group_messages == [(456, "hello")]
+        assert security.calls == 1
+        assert not server._naga_state.request_uuid_inflight
+        assert not server._naga_state.send_inflight
+    finally:
+        release.set()
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await server.stop()
+
+
 @pytest.mark.asyncio
 async def test_naga_messages_send_deduplicates_inflight_uuid(
     tmp_path: Path,

From b383897acbd19ebbe8e1006c3e78281eb0e3bd22 Mon Sep 17 00:00:00 2001
From: Null <1708213363@qq.com>
Date: Sun, 11 Oct 2026 13:21:49 +0800
Subject: [PATCH 121/121] docs(concurrency): explain persistence and lifecycle
 lock boundaries

---
 docs/automations.md                  | 2 +-
 src/Undefined/api/routes/chat.py     | 1 +
 src/Undefined/automations/storage.py | 2 ++
 src/Undefined/weixin/service.py      | 2 ++
 4 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/automations.md b/docs/automations.md
index fba5f269..2dcb3ab4 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -95,7 +95,7 @@
 
 启动时若还没有 `data/automations.json` 但存在旧的 `scheduled_tasks.json`，会自动把旧任务转换为流程图格式写入新文件；旧文件保留不动，之后也不再双写。旧 `/api/v1/schedules` 接口与 `scheduler.*` 工具已下线，统一使用 `/api/v1/automations` 与 `automation.*`。
 
-任务编辑、删除与运行结果的保存共用串行写入锁，每次写入冻结完整快照并原子替换文件。并发保存不会让旧快照覆盖后续删除或新增；等待保存锁或写入期间收到取消时，已发生的内存变更仍会完成持久化，再释放锁并传播取消。
+任务编辑、删除与运行结果的保存共用串行写入锁，每次写入冻结完整快照并原子替换文件。并发保存不会让旧快照覆盖后续删除或新增；等待保存锁或写入期间收到取消时，已发生的内存变更仍会完成持久化，再释放锁并传播取消。调用方在进入保存流程前已经修改共享任务字典，因此等待保存锁也必须受取消保护；仅保护最终写盘会让取消后的内存与磁盘分叉，已删除任务可能在重启后恢复。代价是关闭时需要等待前序写入收敛。
 
 ## 配置与限制
 
diff --git a/src/Undefined/api/routes/chat.py b/src/Undefined/api/routes/chat.py
index 6e051100..68c8bc78 100644
--- a/src/Undefined/api/routes/chat.py
+++ b/src/Undefined/api/routes/chat.py
@@ -424,6 +424,7 @@ async def create_job(
             if self._closing:
                 raise ChatJobManagerClosingError("Chat service is stopping")
             # 会话存在性检查与 job 接受必须和删除共用同一串行边界。
+            # 历史写入也在锁内，其他会话需等待写入完成，确保 stop/删除不会漏掉在途创建。
             conversation = await self.conversation_store.get_conversation(
                 resolved_conversation_id
             )
diff --git a/src/Undefined/automations/storage.py b/src/Undefined/automations/storage.py
index 62f9402c..b4d9cbac 100644
--- a/src/Undefined/automations/storage.py
+++ b/src/Undefined/automations/storage.py
@@ -73,6 +73,8 @@ async def save_snapshot() -> None:
                 await io.write_json(self.path, data_to_save, use_lock=True)
                 logger.info("[自动化] 已保存 %s 条到 %s", len(data_to_save), self.path)
 
+        # 调用方在保存前已修改共享 tasks；等锁时取消也不能丢掉这次持久化，
+        # 否则旧写入完成后，重启可能恢复内存中已经删除的任务。
         await io.run_cancellation_safe(save_snapshot())
 
     def _write_json_sync(self, path: Path, data: dict[str, Any]) -> None:
diff --git a/src/Undefined/weixin/service.py b/src/Undefined/weixin/service.py
index e5a1dd7e..de945d27 100644
--- a/src/Undefined/weixin/service.py
+++ b/src/Undefined/weixin/service.py
@@ -258,6 +258,8 @@ def __init__(
         self._confirmations: dict[str, _Confirmation] = {}
         self._runtimes: dict[str, _AccountRuntime] = {}
         self._login_lock = asyncio.Lock()
+        # 帐号文件提交与客户端启停共用锁，避免删除/改绑与运行时发布交错；
+        # 管理操作会等待彼此的 I/O，消息发送不依赖这把生命周期锁。
         self._lifecycle_lock = asyncio.Lock()
         self._running = False
         self._closed = False