fix(#87): prevent session data loss on abnormal exit / 修复异常退出时会话数据丢失 (#108)

* feat(console): 引入会话心跳机制防止数据丢失
- 新增功能: 实现后台心跳线程以定期持久化会话时长
  * 在 `src/console/main.py` 中新增 `_session_heartbeat` 函数，通过 `threading.Thread` 启动守护进程
  * 引入环境变量 `SESSION_UPDATE_INTERVAL` (默认 30 秒) 控制心跳频率
  * 调用 `db.update_session_duration(session_id)` 异步更新数据库中的 `sessions` 表
- 修复问题: 优化异常终止场景下的会话数据完整性
  * 在 `_cleanup` 函数中添加逻辑，设置 `threading.Event` (`_session_heartbeat_stop`) 以安全停止心跳线程
  * 在 `src/console/commands/systems/quit_cmd.py` 的 `execute` 方法中显式调用 `db.close_session`，确保 `/quit` 命令触发时立即保存状态
- 重构优化: 扩展数据库管理器支持增量更新
  * 在 `src/core/database_manager.py` 中新增 `update_session_duration` 方法，仅计算并更新持续时间而不关闭会话连接
- 文档更新: 补充环境配置说明
  * 在 `.env.example` 文件中添加 `SESSION_UPDATE_INTERVAL` 配置项及其注释

* docs(readme): 新增会话持久化间隔环境变量
- 文档更新: 补充新的配置项说明
  * 在 `README_ZH.md` 和 `README.md` 的环境变量表中添加 `SESSION_UPDATE_INTERVAL`
  * 说明该变量用于控制会话持续时间持久化的时间间隔，默认值为 30 秒

Author: SunYanbox

.env.example

@@ -25,3 +25,7 @@ RESULT_CLEANUP_MINUTES=15
 # 是否自动复制结果（支持 true/false/yes/no/on/off）
 MANUALAID_AUTO_COPY=true
 
+# 会话持续时间持久化间隔（秒）
+# 应用会每隔 N 秒将当前会话耗时写入数据库，
+SESSION_UPDATE_INTERVAL=30
+

README.md

@@ -167,14 +167,15 @@ also require audit approval before execution.
 
 Copy `.env.example` to `.env` and adjust as needed:
 
-| Variable                       | Default | Description                         |
-| ------------------------------ | ------- | ----------------------------------- |
-| `TOOL_MAX_RESULT_LENGTH`       | 30000   | Max characters in tool output       |
-| `TOOL_LIST_TRUNCATE_THRESHOLD` | 100     | Max items in list results           |
-| `TOOL_DICT_TRUNCATE_THRESHOLD` | 100     | Max key-value pairs in dict results |
-| `MANUALAID_AUTO_COPY`          | true    | Auto-copy results to clipboard      |
-| `MANUALAID_AUTO_VIEW`          | true    | Auto-view results in viewer         |
-| `RESULT_EXPIRE_MINUTES`        | 5       | Result cache expiration (minutes)   |
+| Variable                       | Default | Description                               |
+| ------------------------------ | ------- | ----------------------------------------- |
+| `TOOL_MAX_RESULT_LENGTH`       | 30000   | Max characters in tool output             |
+| `TOOL_LIST_TRUNCATE_THRESHOLD` | 100     | Max items in list results                 |
+| `TOOL_DICT_TRUNCATE_THRESHOLD` | 100     | Max key-value pairs in dict results       |
+| `MANUALAID_AUTO_COPY`          | true    | Auto-copy results to clipboard            |
+| `MANUALAID_AUTO_VIEW`          | true    | Auto-view results in viewer               |
+| `RESULT_EXPIRE_MINUTES`        | 5       | Result cache expiration (minutes)         |
+| `SESSION_UPDATE_INTERVAL`      | 30      | Session duration persistence interval (s) |
 
 ---
 

README_ZH.md

@@ -152,14 +152,15 @@ ManualAid 注册了 12 个工具供 LLM 通过 XML 函数调用使用:
 
 复制 `.env.example` 为 `.env` 并根据需要调整:
 
-| 变量                           | 默认值 | 描述                   |
-| ------------------------------ | ------ | ---------------------- |
-| `TOOL_MAX_RESULT_LENGTH`       | 30000  | 工具输出的最大字符数   |
-| `TOOL_LIST_TRUNCATE_THRESHOLD` | 100    | 列表结果的最大条目数   |
-| `TOOL_DICT_TRUNCATE_THRESHOLD` | 100    | 字典结果的最大键值对数 |
-| `MANUALAID_AUTO_COPY`          | true   | 自动将结果复制到剪贴板 |
-| `MANUALAID_AUTO_VIEW`          | true   | 自动在查看器中显示结果 |
-| `RESULT_EXPIRE_MINUTES`        | 5      | 结果缓存过期时间(分钟) |
+| 变量                           | 默认值 | 描述                       |
+| ------------------------------ | ------ | -------------------------- |
+| `TOOL_MAX_RESULT_LENGTH`       | 30000  | 工具输出的最大字符数       |
+| `TOOL_LIST_TRUNCATE_THRESHOLD` | 100    | 列表结果的最大条目数       |
+| `TOOL_DICT_TRUNCATE_THRESHOLD` | 100    | 字典结果的最大键值对数     |
+| `MANUALAID_AUTO_COPY`          | true   | 自动将结果复制到剪贴板     |
+| `MANUALAID_AUTO_VIEW`          | true   | 自动在查看器中显示结果     |
+| `RESULT_EXPIRE_MINUTES`        | 5      | 结果缓存过期时间(分钟)     |
+| `SESSION_UPDATE_INTERVAL`      | 30     | 会话持续时间持久化间隔(秒) |
 
 ---
 

src/console/commands/systems/quit_cmd.py

@@ -14,5 +14,10 @@ def __init__(self):
         self.usage = "/quit or /q or /exit"
 
     def execute(self, context: CommandContext) -> CommandResult:
+        # Close session explicitly before exit (atexit handler is a fallback,
+        # but explicit is more reliable when sys.exit triggers early shutdown).
+        session_id = getattr(context.tool_registry, "_current_session_id", None)
+        if session_id is not None and hasattr(context.workspace, "db"):
+            context.workspace.db.close_session(session_id)
         context.console.print("[bold]Goodbye![/bold]")
         sys.exit(0)

src/console/main.py

@@ -2,7 +2,10 @@
 
 import argparse
 import atexit
+import contextlib
+import os
 import sys
+import threading
 import time
 from pathlib import Path
 
@@ -16,6 +19,22 @@
 
 tool_registry = ToolRegistry()
 
+# Session heartbeat: periodically persists session duration so that abnormal
+# termination (window close, Ctrl+C, SIGKILL) loses minimal data.
+_session_heartbeat_stop: threading.Event | None = None
+
+
+def _session_heartbeat(
+    db,
+    session_id: int,
+    stop_event: threading.Event,
+    interval: float,
+) -> None:
+    """Periodically persist session duration during normal operation."""
+    while not stop_event.wait(interval):
+        with contextlib.suppress(Exception):
+            db.update_session_duration(session_id)
+
 
 def init_workspace(start_path: str | None = None) -> Workspace | None:
     """初始化工作区"""
@@ -42,12 +61,26 @@ def init_workspace(start_path: str | None = None) -> Workspace | None:
     tool_registry.set_session_id(session_id)
     workspace._current_session_id = session_id
 
+    # Start a daemon heartbeat thread to periodically persist session duration
+    global _session_heartbeat_stop
+    _session_heartbeat_stop = threading.Event()
+    interval = int(os.getenv("SESSION_UPDATE_INTERVAL", "30"))
+    thread = threading.Thread(
+        target=_session_heartbeat,
+        args=(workspace.db, session_id, _session_heartbeat_stop, interval),
+        daemon=True,
+    )
+    thread.start()
+
     atexit.register(_cleanup, workspace, session_id)
 
     return workspace
 
 
 def _cleanup(workspace: Workspace, session_id: int) -> None:
+    global _session_heartbeat_stop
+    if _session_heartbeat_stop is not None:
+        _session_heartbeat_stop.set()
     if session_id and hasattr(workspace, "db"):
         workspace.db.close_session(session_id)
         workspace.db.close()

src/core/database_manager.py

@@ -216,6 +216,21 @@ def close_session(self, session_id: int) -> None:
                 (duration, session_id),
             )
 
+    def update_session_duration(self, session_id: int) -> None:
+        """Persist current elapsed duration without closing the session.
+
+        Used by the periodic heartbeat so that abnormal termination (window
+        close, Ctrl+C, SIGKILL) loses at most the heartbeat interval's worth
+        of session duration data.
+        """
+        row = self.fetchone("SELECT created_at FROM sessions WHERE id = ?", (session_id,))
+        if row:
+            duration = time.time() - row[0]
+            self.execute(
+                "UPDATE sessions SET duration = ? WHERE id = ?",
+                (duration, session_id),
+            )
+
     # -- Tool call logging --
 
     def log_tool_call(