9 · 会话持久化与后台任务（Session Persistence and Background Tasks）

代理式研究运行时 · 本章是 jcode DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目jcode 章节9 状态全文译文模块存储与持久化、接口与服务契约、界面与交互、智能体运行时

项目要点页2.5 参考项目项目章节目录jcode DeepWiki 原始章节Session Persistence and Background Tasks 上一章8.2 下一章9.1

源码线索

src/agent.rs
src/background.rs
src/main.rs
src/message/notifications.rs
src/protocol.rs
src/server.rs
src/server/tests.rs
src/session.rs
src/tool/bash.rs
src/tool/bg.rs

模块标签

存储与持久化
接口与服务契约
界面与交互
智能体运行时
测试、发布与运维

中文译文

会话持久化与后台任务（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/1jehuang/jcode/9-session-persistence-and-background-tasks

翻译时间：2026-05-27T08:45:20.431Z

翻译模型：deepseek-chat

原文字符数：6278

项目：jcode (jcode)

---

会话持久化与后台任务

存储布局

所有持久化数据都集中在 jcode 主目录下，通常为 ~/.jcode/。系统使用平台感知逻辑来解析这些路径，并应用严格的权限加固来保护敏感凭证和会话数据 src/session.rs:3-17。

路径	描述
`~/.jcode/sessions/`	会话 JSON 和 JSONL 日志文件的主要存储位置 `src/session.rs:42`。
`~/.jcode/active_pids/`	活跃会话的 PID 文件，用于检测崩溃 `src/session.rs:8-10`。
`~/.jcode/tasks/`	后台任务输出和状态 JSON 文件的存储位置 `src/background.rs:31-33`。
`~/.jcode/auth.json`	提供商凭证和 OAuth 令牌的存储位置。
`~/.jcode/config.toml`	全局用户配置和安全设置。

来源： src/session.rs:1-43, src/background.rs:31-48

会话持久化模型

jcode 采用混合持久化策略，以平衡性能与崩溃恢复能力。每个对话都由一个 Session 结构体表示 src/session.rs:64-155。

JSON 快照： 定期对会话进行完整状态序列化，包括元数据、压缩状态和消息历史 src/session.rs:72-76。
JSONL 日志： 通过 SessionPersistState 实时、仅追加地记录新消息和事件 src/session.rs:142。这确保了即使在保存完整快照之前进程被终止，对话也可以被重建 src/session.rs:25-26。
易记 ID： 通过 new_memorable_session_id 为会话分配人类友好的 ID（例如 "fox"、"oak"），以便于手动恢复和多会话管理 src/session.rs:1, src/session.rs:112-113。

关于序列化格式和恢复逻辑的详细信息，请参阅 会话生命周期与日志。

会话状态转换

SessionStatus 枚举跟踪会话的生命周期，允许 TUI 和服务器检测崩溃或重新加载 src/session.rs:114-116。

graph TD
    "活跃[SessionStatus::Active]" -- "用户退出" --> "已关闭[SessionStatus::Closed]"
    "活跃[SessionStatus::Active]" -- "恐慌/SIGKILL" --> "已崩溃[SessionStatus::Crashed]"
    "活跃[SessionStatus::Active]" -- "热重载" --> "已重载[SessionStatus::Reloaded]"
    "已崩溃[SessionStatus::Crashed]" -- "recover_crashed_sessions()" --> "活跃[SessionStatus::Active]"
    "活跃[SessionStatus::Active]" -- "CompactionManager" --> "已压缩[SessionStatus::Compacted]"

来源： src/session.rs:64-125, src/session.rs:18-21, src/agent.rs:38

后台任务管理

BackgroundTaskManager 允许工具（如 bash）生成进程，这些进程即使在 TUI 断开连接或服务器重启后也能继续运行 src/background.rs:36-40。

任务跟踪： 每个任务通过 generate_task_id 分配一个唯一 ID src/background.rs:57-77，并通过 .status.json 文件进行跟踪 src/background.rs:83-84。
PID 核对： 系统使用 active_pids 来检查分离的任务在系统重载后是否仍然存活 src/session.rs:8-10。
输出流式传输： 任务的标准输出和标准错误被重定向到 .output 文件 src/background.rs:79-81。BgTool 允许代理对这些文件执行 tail 或 wait 操作 src/tool/bg.rs:42-98。
进度解析： bash 工具解析标准输出中的 JCODE_PROGRESS JSON 标记或基于正则表达式的模式（例如 42%），以更新 UI src/tool/bash.rs:26-91。

关于进程接管和后台事件总线的详细信息，请参阅 后台任务与进程管理。

后台任务逻辑流程

此图展示了 BackgroundTaskManager 如何使用代码实体将 Agent 的请求桥接到操作系统进程状态。

sequenceDiagram
    participant A as "代理 [src/agent.rs]"
    participant B as "BackgroundTaskManager [src/background.rs]"
    participant F as "文件系统 [~/.jcode/tasks/]"
    participant P as "操作系统进程 (PID)"

    A->>B: "BackgroundTaskManager::new()"
    B->>P: "TokioCommand::spawn()"
    P-->>B: "子进程 PID"
    B->>F: "write_status_file(.status.json)"
    Note over P: "进程分离运行..."
    P->>F: "追加到 .output 文件"
    B->>P: "try_reap_child_process(pid)"
    B->>A: "dispatch_background_task_completion()"

来源： src/background.rs:36-192, src/server.rs:45-47, src/tool/bash.rs:19-30

会话恢复与发现

Session 模块提供了发现和预览历史会话的工具。它通过 detect_crashed_sessions 检查是否存在 PID 文件但对应的进程未运行，从而识别崩溃的会话 src/session.rs:18-21。

graph LR
    subgraph "代码实体空间"
        SES["Session::load() [src/session.rs]"]
        DCS["detect_crashed_sessions() [src/session.rs]"]
        RAP["register_active_pid() [src/session.rs]"]
    end

    subgraph "自然语言空间"
        DIR["~/.jcode/sessions/"]
        PDIR["~/.jcode/active_pids/"]
        CRASH["崩溃检测"]
    end

    SES -- "读取" --> DIR
    DCS -- "扫描" --> PDIR
    RAP -- "写入" --> PDIR
    DCS -- "验证" --> CRASH

来源： src/session.rs:1-38, src/session.rs:64-155