Class JsonlSessionStorage

tutorials/12_session_persistence.py:280–425

JSONL 会话存储器。 设计要点（来自 Reference EP09）： 1. 仅追加写入 — 不修改已有内容 2. 崩溃安全 — 追加写入是原子操作（配合 O_APPEND） 3. 每条消息独立 — 一行坏了不影响其他行 对应 Reference: architecture/zh-CN/09-session-persistence.md - sessionStorage.ts:5,106 行 - JSONL 仅追加存储

# 这是 Reference EP09 描述的生产级方案

class JsonlSessionStorage:
    """
    JSONL 会话存储器。

    设计要点（来自 Reference EP09）：
    1. 仅追加写入 — 不修改已有内容
    2. 崩溃安全 — 追加写入是原子操作（配合 O_APPEND）
    3. 每条消息独立 — 一行坏了不影响其他行

    对应 Reference: architecture/zh-CN/09-session-persistence.md
        - sessionStorage.ts:5,106 行
        - JSONL 仅追加存储
    """

    def __init__(self, base_dir: str):
        self.base_dir = base_dir
        os.makedirs(base_dir, exist_ok=True)

    def _session_path(self, session_id: str) -> str:
        """
        生成会话文件路径。

        对应 Reference: EP09 §1
            ~/.claude/projects/{sanitized_cwd}/{session-id}.jsonl
        """
        return os.path.join(self.base_dir, f"{session_id}.jsonl")

    def append_message(self, session_id: str, message: ConversationMessage):
        """
        追加一条消息到 JSONL 文件。

        这是最核心的写入操作。每条消息一行，追加到文件末尾。

        对应 Reference: EP09 §2
            Project.appendEntry() → enqueueWrite(filePath, entry)
        """
        path = self._session_path(session_id)
        entry = {
            "type": message.role,
            **message.to_dict(),
        }
        line = json.dumps(entry, ensure_ascii=False) + "\n"
        with open(path, "a") as f:
            f.write(line)

    def append_metadata(self, session_id: str, meta_type: str, data: dict):
        """
        追加元数据条目（标题、标签等）。

        对应 Reference: EP09 §1 条目类型
            custom-title, ai-title, last-prompt, tag 等
        """
        entry = {"type": meta_type, **data}
        path = self._session_path(session_id)
        line = json.dumps(entry, ensure_ascii=False) + "\n"
        with open(path, "a") as f:
            f.write(line)