illusion-code 0.2.9__tar.gz → 0.2.11__tar.gz

{illusion_code-0.2.9 → illusion_code-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: illusion-code
-Version: 0.2.9
+Version: 0.2.11
 Summary: Open-source Python port of Claude Code - an AI-powered CLI coding assistant
 Project-URL: Homepage, https://github.com/YunTaiHua/illusion-code
 Project-URL: Repository, https://github.com/YunTaiHua/illusion-code

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/terminal/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@illusion/terminal",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@illusion/terminal",
-      "version": "0.2.9",
+      "version": "0.2.11",
       "dependencies": {
         "chalk": "^5.6.2",
         "ink": "^5.1.0",

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/terminal/package.json

@@ -24,5 +24,5 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.3"
   },
-  "version": "0.2.9"
+  "version": "0.2.11"
 }

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/terminal/src/version.ts

@@ -6,4 +6,4 @@
  */
 
 /** 当前版本号 */
-export const VERSION = '0.2.9';
+export const VERSION = '0.2.11';

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@illusion/web",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@illusion/web",
-      "version": "0.2.9",
+      "version": "0.2.11",
       "dependencies": {
         "highlight.js": "^11.11.0",
         "react": "^18.3.1",

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illusion/web",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "private": true,
   "type": "module",
   "scripts": {

{illusion_code-0.2.9 → illusion_code-0.2.11}/frontend/web/src/version.ts

@@ -6,4 +6,4 @@
  */
 
 /** 当前版本号 */
-export const VERSION = '0.2.9';
+export const VERSION = '0.2.11';

{illusion_code-0.2.9 → illusion_code-0.2.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "illusion-code"
-version = "0.2.9"
+version = "0.2.11"
 description = "Open-source Python port of Claude Code - an AI-powered CLI coding assistant"
 readme = "README.md"
 license = "MIT"

{illusion_code-0.2.9 → illusion_code-0.2.11}/src/illusion/__init__.py

@@ -23,4 +23,4 @@ IllusionCode 是一个 AI 驱动的编程助手，提供交互式会话和命令
 
 from __future__ import annotations
 
-__version__ = "0.2.9"
+__version__ = "0.2.11"

{illusion_code-0.2.9 → illusion_code-0.2.11}/src/illusion/channels/__init__.py

@@ -35,6 +35,8 @@ logger = logging.getLogger(__name__)
 def _config_fingerprint(cfg: "ChannelsConfig") -> str:
     """计算渠道配置指纹（用于检测配置变更后重启守护进程）
 
+    遍历 ChannelRegistry，对每个已启用渠道调用其 fingerprint_factory 生成标识。
+
     Args:
         cfg: 渠道配置
 
@@ -44,14 +46,14 @@ def _config_fingerprint(cfg: "ChannelsConfig") -> str:
     import hashlib
     import json as _json
 
-    # 只取影响守护进程行为的字段
+    from illusion.channels.registry import ChannelRegistry
+
+    # 遍历 registry 调用各渠道的 fingerprint_factory
     enabled_channels = []
-    if cfg.feishu.enabled:
-        enabled_channels.append(f"feishu:{cfg.feishu.app_id}")
-    if cfg.weixin.enabled:
-        enabled_channels.append(f"weixin:{cfg.weixin.account_id}:{cfg.weixin.token}")
-    if cfg.qq.enabled:
-        enabled_channels.append(f"qq:{cfg.qq.app_id}:{cfg.qq.client_secret}")
+    for desc in ChannelRegistry.all_descriptors():
+        channel_cfg = getattr(cfg, desc.config_attr, None)
+        if channel_cfg is not None and channel_cfg.enabled:
+            enabled_channels.append(desc.fingerprint_factory(channel_cfg))
     raw = _json.dumps(sorted(enabled_channels), ensure_ascii=False)
     return hashlib.md5(raw.encode()).hexdigest()
 
@@ -173,6 +175,68 @@ def kill_channel_daemon(proc: "subprocess.Popen[bytes] | None") -> None:
             pass
 
 
+def is_channel_daemon_running() -> bool:
+    """检查渠道守护进程是否正在运行（通过 PID 文件，不依赖 proc 引用）
+
+    用于退出时判断是否需要询问用户是否一同退出渠道。
+
+    Returns:
+        bool: 守护进程在运行返回 True
+    """
+    from illusion.config.paths import get_channels_data_dir
+    from illusion.channels.pid import PidFile
+    pid_file = PidFile(get_channels_data_dir() / "daemon.pid")
+    return pid_file.is_running()
+
+
+def stop_channel_daemon_by_pid() -> bool:
+    """通过 PID 文件停止渠道守护进程（不依赖 proc 引用）
+
+    供退出时交互式确认使用：无论当前进程是否是 spawn 者，
+    都可以通过 PID 文件停止守护进程。
+
+    Windows 上用 taskkill /T /F 终止整个进程树（守护进程可能 spawn 了
+    aiohttp/WS 子线程，单独 TerminateProcess 可能留下孤儿线程）。
+    Unix 上用 SIGTERM 终止进程组。
+
+    Returns:
+        bool: 成功停止返回 True，守护进程不存在或已停止返回 False
+    """
+    from illusion.config.paths import get_channels_data_dir
+    from illusion.channels.pid import PidFile, read_pid
+
+    pid_file = PidFile(get_channels_data_dir() / "daemon.pid")
+    if not pid_file.is_running():
+        pid_file.release()
+        return False
+
+    old_pid = read_pid(pid_file.path)
+    if old_pid is not None:
+        try:
+            if os.name == "nt":
+                # Windows: 用 taskkill /T /F 终止整个进程树
+                # /T = 终止子进程，/F = 强制终止
+                import subprocess as _sp
+                _sp.run(
+                    ["taskkill", "/PID", str(old_pid), "/T", "/F"],
+                    capture_output=True, timeout=5,
+                )
+            else:
+                # Unix: 用 SIGTERM 终止进程组
+                import signal
+                os.kill(old_pid, signal.SIGTERM)
+        except (OSError, ProcessLookupError, Exception):  # noqa: BLE001
+            pass
+        # 等待进程退出，最多 3 秒
+        for _ in range(30):
+            if not pid_file.is_running():
+                break
+            import time as _time
+            _time.sleep(0.1)
+    pid_file.release()
+    return True
+
+
 class ChannelRunner:
     """渠道消息接入 agent 的运行器
 
@@ -210,6 +274,8 @@ class ChannelRunner:
         # 按 chat_id 串行化 agent turn，避免并行消息导致会话历史覆盖
         # （同一会话连发多条消息时，M2/M3 排队等 M1 完成后再跑）
         self._chat_locks: dict[str, asyncio.Lock] = {}
+        # 当前正在运行的 agent task（按 chat_id 索引），供 /stop 中断
+        self._active_agent_tasks: dict[str, asyncio.Task[None]] = {}
         self._stop = False
 
     def _get_chat_lock(self, chat_id: str) -> asyncio.Lock:
@@ -254,20 +320,6 @@ class ChannelRunner:
         Args:
             msg: 入站消息
         """
-        # 检查 /delete 信号：先执行 /new（清所有会话+发确认），再处理消息
-        if self.session_store.check_signal():
-            for path in self.session_store.data_dir.glob("*.json"):
-                try:
-                    path.unlink()
-                except OSError:
-                    pass
-            from illusion.config.i18n import t as _t
-            # 统一使用 cmd_new，避免渠道专属文案不一致
-            await self.channel.send_text(
-                msg.chat_id, _t("cmd_new"), reply_to=msg.message_id,
-            )
-            self.session_store.clear_signal()
-
         # 1. 待回复的权限/询问——不加锁，让回复立即送达
         # （agent turn 持锁等待回复时，下一条消息作为回复立即 set_result，
         #   不会因锁阻塞导致 300s 超时）
@@ -277,6 +329,13 @@ class ChannelRunner:
                 fut.set_result(msg.text)
             return
 
+        # /stop 命令：立即中断当前 chat_id 正在运行的 agent task，不排队等锁
+        # 必须在 _chat_locks 之前处理，否则会卡在串行队列里等到 agent 完成才生效
+        text = msg.text.strip()
+        if text.lower() == "/stop":
+            await self._handle_stop(msg)
+            return
+
         # 2/3. 斜杠命令 + agent turn：按 chat_id 串行化
         async with self._get_chat_lock(msg.chat_id):
             # 进入锁后再次检查 pending_replies：前一个 agent turn 可能
@@ -293,41 +352,74 @@ class ChannelRunner:
                 return
 
             # 3. 跑 agent
+            # 将当前 task 注册到 _active_agent_tasks，供 /stop 中断
+            current_task = asyncio.current_task()
+            if current_task is not None:
+                self._active_agent_tasks[msg.chat_id] = current_task
             try:
                 await self._run_agent(msg)
+            except asyncio.CancelledError:
+                # /stop 取消：agent 已中断，发提示消息
+                from illusion.config.i18n import t as _t
+                logger.info("agent 任务被 /stop 中断: chat_id=%s", msg.chat_id)
+                try:
+                    await self.channel.send_text(
+                        msg.chat_id, _t("cmd_stop_done"),
+                        reply_to=msg.message_id,
+                    )
+                except Exception:  # noqa: BLE001
+                    pass
+                raise
             except Exception as exc:  # noqa: BLE001
                 logger.exception("处理渠道消息异常: %s", exc)
                 try:
                     await self.channel.send_text(msg.chat_id, f"❌ 处理失败: {str(exc)[:100]}")
                 except Exception:  # noqa: BLE001
                     pass
+            finally:
+                # 清理 task 注册（无论正常完成、异常还是取消）
+                self._active_agent_tasks.pop(msg.chat_id, None)
 
     def _get_command_handler(self) -> Any:
         """按渠道类型返回对应的斜杠命令处理器
 
+        遍历 ChannelRegistry，匹配 adapter_class 后调用 command_handler_factory。
+
         Returns:
             BaseCommandHandler 实例或 None（未知渠道）
         """
-        from illusion.channels.feishu.adapter import FeishuChannel
-        from illusion.channels.feishu.commands import FeishuCommandHandler
-        if isinstance(self.channel, FeishuChannel):
-            return FeishuCommandHandler(self.channel, self.session_store)
-        try:
-            from illusion.channels.weixin.adapter import WeixinChannel
-            from illusion.channels.weixin.commands import WeixinCommandHandler
-            if isinstance(self.channel, WeixinChannel):
-                return WeixinCommandHandler(self.channel, self.session_store)
-        except ImportError:
-            pass  # 微信模块不可用时跳过
-        try:
-            from illusion.channels.qq.adapter import QQChannel
-            from illusion.channels.qq.commands import QQCommandHandler
-            if isinstance(self.channel, QQChannel):
-                return QQCommandHandler(self.channel, self.session_store)
-        except ImportError:
-            pass  # QQ 模块不可用时跳过
+        from illusion.channels.registry import ChannelRegistry
+
+        for desc in ChannelRegistry.all_descriptors():
+            if isinstance(self.channel, desc.adapter_class):
+                return desc.command_handler_factory(self.channel, self.session_store)
         return None
 
+    async def _handle_stop(self, msg: "InboundMessage") -> None:
+        """处理 /stop 命令：中断当前 chat_id 正在运行的 agent 任务
+
+        不加 _chat_locks 锁，立即取消正在运行的 agent task。
+        如果没有正在运行的任务，回复提示"无正在执行的任务"。
+
+        Args:
+            msg: /stop 命令消息
+        """
+        from illusion.config.i18n import t as _t
+
+        task = self._active_agent_tasks.get(msg.chat_id)
+        if task is None or task.done():
+            # 无正在运行的任务
+            await self.channel.send_text(
+                msg.chat_id, _t("cmd_stop_no_task"),
+                reply_to=msg.message_id,
+            )
+            return
+
+        # 取消任务：触发 CancelledError，_run_agent 的 except 块清理流式控制器
+        # _handle_message 的 except CancelledError 块发送"已中断"提示
+        task.cancel()
+        logger.info("/stop 已取消 agent 任务: chat_id=%s", msg.chat_id)
+
     def _build_channel_tools(self, msg: "InboundMessage") -> list[Any]:
         """构造渠道内置工具列表
 
@@ -429,6 +521,14 @@ class ChannelRunner:
         key = self.session_store.build_session_key(msg)
         session = self.session_store.get_or_create(key, msg.user_id, msg.chat_type)
 
+        # 提前落盘会话索引（仅当文件尚不存在时）：确保 session_id 落盘，
+        # 这样进程崩溃后下次启动 get_or_create 能命中该会话记录接续，
+        # 而非新建会话。注意：绝不覆盖已有 messages（否则会清空历史）。
+        try:
+            self.session_store.ensure_indexed(session)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("会话索引提前落盘失败: %s", exc)
+
         # 检测渠道是否支持消息编辑（仅飞书支持卡片 patch）
         from illusion.channels.feishu.adapter import FeishuChannel
         from illusion.channels.qq.adapter import QQChannel
@@ -482,18 +582,12 @@ class ChannelRunner:
             await streaming_controller.start()
         elif qq_c2c_streaming and qq_channel is not None:
             # QQ C2C：用 stream_messages API 流式（首次有文本时才启动）
-            # 确保 token 已获取
-            if not qq_channel._token:
-                from illusion.channels.qq.api import ensure_token
-                qq_channel._token = await ensure_token(
-                    qq_channel._session,
-                    qq_channel.config.app_id,
-                    qq_channel.config.client_secret,
-                )
+            # 确保 token 已获取（通过 _get_token，重连后自动刷新）
+            token = await qq_channel._get_token()
             from illusion.channels.qq.streaming import QQStreamingController
             qq_streaming_controller = QQStreamingController(
                 session=qq_channel._session,
-                token=qq_channel._token,
+                token=token,
                 openid=msg.chat_id,
                 msg_id=msg.message_id,
             )
@@ -613,6 +707,20 @@ class ChannelRunner:
                     logger.warning("渠道会话持久化失败: %s", exc)
             else:
                 logger.warning("无法从 bundle.engine 获取会话历史，跳过持久化")
+        except asyncio.CancelledError:
+            # /stop 中断：清理流式控制器后重新抛出，让上层 _handle_message 发提示
+            logger.info("agent 任务被取消: chat_id=%s", msg.chat_id)
+            if supports_edit and streaming_controller:
+                try:
+                    await streaming_controller.error("已中断")
+                except Exception:  # noqa: BLE001
+                    pass
+            elif qq_streaming_controller:
+                try:
+                    await qq_streaming_controller.abort("已中断")
+                except Exception:  # noqa: BLE001
+                    pass
+            raise
         except Exception as exc:
             logger.exception("agent 处理异常")
             if supports_edit and streaming_controller:
@@ -757,10 +865,8 @@ def _create_session_store(
 ) -> Any:
     """根据渠道类型创建对应的 SessionStore
 
-    飞书 → FeishuSessionStore
-    QQ → QQSessionStore
-    微信 → WeixinSessionStore
-    未知 → FeishuSessionStore（向后兼容）
+    遍历 ChannelRegistry，匹配 adapter_class 后调用 session_store_factory。
+    未知渠道回退到 FeishuSessionStore（向后兼容）。
 
     Args:
         channel: 渠道实例
@@ -770,30 +876,13 @@ def _create_session_store(
     Returns:
         对应渠道的 SessionStore 实例
     """
-    from illusion.channels.feishu.adapter import FeishuChannel
-    if isinstance(channel, FeishuChannel):
-        from illusion.channels.feishu.session_map import FeishuSessionStore
-        return FeishuSessionStore(
-            data_dir=data_dir,
-            group_sessions_per_user=group_sessions_per_user,
-        )
-    try:
-        from illusion.channels.qq.adapter import QQChannel
-        if isinstance(channel, QQChannel):
-            from illusion.channels.qq.session_map import QQSessionStore
-            return QQSessionStore(
-                data_dir=data_dir,
-                group_sessions_per_user=group_sessions_per_user,
+    from illusion.channels.registry import ChannelRegistry
+
+    for desc in ChannelRegistry.all_descriptors():
+        if isinstance(channel, desc.adapter_class):
+            return desc.session_store_factory(
+                channel, data_dir, group_sessions_per_user
             )
-    except ImportError:
-        pass
-    try:
-        from illusion.channels.weixin.adapter import WeixinChannel
-        if isinstance(channel, WeixinChannel):
-            from illusion.channels.weixin.session_map import WeixinSessionStore
-            return WeixinSessionStore(data_dir=data_dir)
-    except ImportError:
-        pass
     # 未知渠道回退到飞书（向后兼容）
     from illusion.channels.feishu.session_map import FeishuSessionStore
     return FeishuSessionStore(

{illusion_code-0.2.9 → illusion_code-0.2.11}/src/illusion/channels/base_commands.py

@@ -80,6 +80,10 @@ class BaseCommandHandler:
         elif cmd == "new":
             self.session_store.clear(key)
             await self._reply(msg, t("cmd_new"))
+        elif cmd == "stop":
+            # /stop 在 ChannelRunner._handle_message 开头已被拦截处理，
+            # 不会走到这里。此分支仅作为防御性兜底（如 PC 终端直接调用）
+            await self._reply(msg, t("cmd_stop_no_task"))
         elif cmd == "model":
             await self._cmd_model(msg, key, args)
         elif cmd == "sessions":

{illusion_code-0.2.9 → illusion_code-0.2.11}/src/illusion/channels/config.py

@@ -161,24 +161,34 @@ class ChannelsConfig(BaseModel):
     def has_enabled_channels(self) -> bool:
         """是否有任何已启用的渠道
 
+        遍历 ChannelRegistry 检查每个渠道的 enabled 字段。
+
         Returns:
             bool: 任一渠道 enabled 为 True 时返回 True
         """
-        return self.feishu.enabled or self.weixin.enabled or self.qq.enabled
+        from illusion.channels.registry import ChannelRegistry
+
+        for desc in ChannelRegistry.all_descriptors():
+            channel_cfg = getattr(self, desc.config_attr, None)
+            if channel_cfg is not None and channel_cfg.enabled:
+                return True
+        return False
 
     def enabled_channel_names(self) -> list[str]:
         """返回所有已启用渠道的名称列表
 
+        遍历 ChannelRegistry 收集已启用渠道名。
+
         Returns:
             list[str]: 已启用渠道名列表
         """
+        from illusion.channels.registry import ChannelRegistry
+
         names: list[str] = []
-        if self.feishu.enabled:
-            names.append("feishu")
-        if self.weixin.enabled:
-            names.append("weixin")
-        if self.qq.enabled:
-            names.append("qq")
+        for desc in ChannelRegistry.all_descriptors():
+            channel_cfg = getattr(self, desc.config_attr, None)
+            if channel_cfg is not None and channel_cfg.enabled:
+                names.append(desc.name)
         return names
 
 

illusion_code-0.2.11/src/illusion/channels/exit_handler.py

@@ -0,0 +1,83 @@
+"""共享退出处理器
+==================
+
+统一 Ctrl+C / 正常退出时的守护进程退出行为，消除 cli.py 中
+main() 和 web_start() 重复的内联退出确认逻辑。
+
+行为规则：
+    1. 守护进程未运行 → 直接返回（程序正常退出）
+    2. channels.json 无配置或无启用渠道 → 直接返回
+    3. 否则弹出确认提示：
+       - 输入 y/Y/yes/回车（空输入）→ 停止守护进程
+       - 输入期间再次 Ctrl+C（KeyboardInterrupt）→ 停止守护进程
+       - 其他任何输入 → 不停止（守护进程保留运行）
+       - EOF（非 TTY 环境，如管道）→ 不停止
+
+函数说明：
+    - handle_daemon_exit_on_interrupt: 退出时调用，按上述规则处理
+    - _confirm_exit: 私有确认函数
+
+使用示例：
+    >>> from illusion.channels.exit_handler import handle_daemon_exit_on_interrupt
+    >>> # 在 cli.py 的 finally 块中调用
+    >>> handle_daemon_exit_on_interrupt()
+"""
+from __future__ import annotations
+
+from illusion.channels import (
+    is_channel_daemon_running,
+    stop_channel_daemon_by_pid,
+)
+from illusion.channels.config import load_channels_config
+
+
+def handle_daemon_exit_on_interrupt() -> None:
+    """Ctrl+C 或正常退出时的守护进程退出处理
+
+    行为：
+    1. 守护进程未运行 → 直接返回（程序正常退出）
+    2. channels.json 无配置或无启用渠道 → 直接返回
+    3. 否则弹出确认提示：
+       - 输入 y/Y/yes/回车（空输入）→ 停止守护进程
+       - 输入期间再次 Ctrl+C（KeyboardInterrupt）→ 停止守护进程
+       - 其他任何输入 → 不停止（守护进程保留运行）
+
+    退出路径必须比正常路径更健壮：任何异常（如 channels.json 权限不足、
+    PID 文件读取失败）都不应破坏退出体验，静默吞掉并记日志。
+    """
+    try:
+        if not is_channel_daemon_running():
+            return
+        cfg = load_channels_config()
+        if not cfg.has_enabled_channels():
+            return
+        if _confirm_exit():
+            stop_channel_daemon_by_pid()
+    except Exception:  # noqa: BLE001
+        # 退出路径防御性兜底：避免配置文件异常/PID 读取失败等导致丑陋 traceback
+        import logging
+        logging.getLogger(__name__).debug("exit handler suppressed exception", exc_info=True)
+
+
+def _confirm_exit() -> bool:
+    """确认是否退出守护进程
+
+    y/Y/yes/空回车/二次 Ctrl+C 均视为确认；
+    其他输入或 EOF 视为拒绝。
+
+    Returns:
+        bool: True 表示确认停止守护进程
+    """
+    from illusion.config.i18n import t
+
+    try:
+        answer = input(t("channel_daemon_exit_prompt") + " ").strip()
+        return answer.lower() in ("", "y", "yes")
+    except KeyboardInterrupt:
+        # 再次 Ctrl+C = 确认退出。Windows 终端会回显 "^C" 到屏幕，
+        # 打印明确的确认信息让用户知道 Ctrl+C 已被正确处理
+        print()
+        print(t("channel_daemon_exit_confirmed"))
+        return True
+    except EOFError:
+        return False  # 非 TTY 环境（如管道）默认不杀

{illusion_code-0.2.9 → illusion_code-0.2.11}/src/illusion/channels/feishu/session_map.py

@@ -98,21 +98,6 @@ class FeishuSessionStore:
         safe = key.replace(":", "_").replace("/", "_")  # 安全文件名
         return self.data_dir / f"{safe}.json"
 
-    def check_signal(self) -> bool:
-        """检查 /delete 信号文件是否存在
-
-        Returns:
-            bool: 信号存在返回 True
-        """
-        return (self.data_dir / ".delete_signal").exists()
-
-    def clear_signal(self) -> None:
-        """删除信号文件"""
-        try:
-            (self.data_dir / ".delete_signal").unlink()
-        except OSError:
-            pass
-
     def get_or_create(self, key: str, user_id: str, chat_type: str) -> FeishuSession:
         """获取或创建会话
 
@@ -125,6 +110,10 @@ class FeishuSessionStore:
 
         Returns:
             FeishuSession: 会话状态
+
+        Note:
+            会话索引在 _run_agent 进入 agent turn 前即提前落盘，
+            保证进程崩溃后下次启动能接续同一 session_id。
         """
         path = self._key_to_path(key)
         if path.exists():
@@ -178,6 +167,27 @@ class FeishuSessionStore:
         except FileNotFoundError:
             pass  # 已删除
 
+    def ensure_indexed(self, session: FeishuSession) -> None:
+        """确保会话索引已落盘（仅当文件不存在时创建）
+
+        与 save 不同：本方法绝不覆盖已有 messages，只在文件尚不存在时
+        写入 session_id 等索引字段，供进程崩溃后接续使用。
+
+        Args:
+            session: 会话状态
+        """
+        path = self._key_to_path(session.key)
+        if path.exists():
+            return  # 已有记录，绝不覆盖（避免清空历史）
+        data = {
+            "session_id": session.session_id,
+            "messages": [],
+            "user_id": session.user_id,
+            "chat_type": session.chat_type,
+            "model": session.model,
+        }
+        atomic_write_text(path, json.dumps(data, ensure_ascii=False, indent=2))
+
     def clear_by_session_id(self, session_id: str) -> bool:
         """按 session_id 删除会话文件（用于 /delete 命令跨渠道清理）