EN 中文

# Session Management

# 会话管理

Save, resume, fork, compact, and distil sessions.

保存、恢复、分叉、压缩和提炼会话。

seek automatically saves every conversation to disk. Sessions store the full message history, token usage, model, and metadata so you can resume, fork, or review any past run.

seek 自动将每次对话保存到磁盘。会话存储完整的消息历史、token 用量、模型和元数据，以便恢复、分叉或审查任何历史记录。

## Storage Location

## 存储位置

Sessions are stored as JSONL files in:

会话以 JSONL 文件存储在：

- Linux / macOS: `~/.seek/sessions/` (override with `$SEEK_HOME`)
- Windows: `%USERPROFILE%\.seek\sessions\`

Each session is one file named by its ID, e.g. `20240522-143201-abc.jsonl`.

每个会话是一个以 ID 命名的文件

## Basic Operations

## 基本操作

    $ seek --list                      # List saved sessions (most recent first)
    $ seek --continue                  # Resume the most recent session
    $ seek --resume 20240522-143201-abc # Resume a specific session by ID
    $ seek --no-save -p "scratch work" # Ephemeral session (no save)

## Forking with /branch

## 用 /branch 分叉

`/branch` creates a child session that shares the same history up to the fork point. The original session is preserved unchanged. Useful for exploring two approaches from the same starting point. The new session ID is printed; use `--resume <id>` to switch between branches.

`/branch` 创建一个子会话，共享分叉点之前的历史。原始会话保持不变。适用于从同一起点探索两种方案。打印新会话 ID；用 `--resume <id>` 在分支间切换。

## Compacting with /compact

## 用 /compact 压缩

Long sessions accumulate token cost. `/compact` summarises the older portion of the history into a single assistant message, then continues. Run `/compact` before a long task if you're near your context limit.

长会话会累积 token 成本。`/compact` 将较早的历史摘要为一条助手消息。接近上下文限制时运行它。

## Distilling with /distill

## 用 /distill 提炼

`/distill` scans the current session's conversation history and uses the DeepSeek reasoning model to propose ≤3 project-level decisions worth remembering. Each candidate is presented for y/n/e review before being written to project memory (M layer). This is the primary feed mechanism for the M index — run it at the end of a session when you've made non-obvious decisions.

`/distill` 扫描当前会话历史，使用 DeepSeek 推理模型提出 ≤3 条值得记忆的项目级决策。每条候选需要 y/n/e 审查后写入项目记忆（M 层）。这是 M 索引的主要输入机制——在做出非显而易见决策的会话结束时运行。

## Checkpoint Safety Net

## 检查点安全网

seek provides a two-layer safety net that makes destructive operations reversible within a session.

seek 提供双层安全网，让会话内的破坏性操作可逆。

- Git checkpoint — before the first destructive action in each turn, seek automatically snapshots the entire working tree (`git stash create`) into a custom ref namespace (`refs/seek/checkpoints/`). Use `/restore <turn>` or `seek checkpoint restore <turn>` to roll back. HEAD is never altered.
- Git 检查点 — 每个 turn 首次破坏性操作前自动快照整个工作树到自定义 ref 命名空间。用 `/restore <turn>` 或 `seek checkpoint restore <turn>` 回滚，HEAD 不变。
- File checkpoint (undo/redo) — every write or edit snapshots the original file as a content-addressed SHA-256 blob. Use `/undo` / `/redo` to step through file changes. Cleans up when the session ends.
- 文件检查点（撤销/重做） — 每次写入/编辑前快照源文件为内容寻址 blob。用 `/undo` / `/redo` 前后步进，会话结束时自动清理。

The two layers complement each other: git checkpoints cover all file changes (including from bash), while file checkpoints work per-file and outside git repos. See `seek checkpoint list` and `seek checkpoint prune`.

两层互补：git 检查点覆盖所有文件（含 bash 造成的变更），文件检查点覆盖单文件且在非 git 仓库中也能用。

## Token Accounting

## Token 统计

The status bar shows cumulative token counts across the session:

状态栏显示会话累计 token 统计：

- prompt — tokens sent to the model (cached + uncached)
- hit — tokens served from DeepSeek's prefix cache (~50× cheaper)
- gen — generated completion tokens

## RPC Mode (IDE Integration)

## RPC 模式（IDE 集成）

`seek --rpc` starts a JSON-RPC 2.0 server over stdin/stdout. Host processes send requests and receive streaming responses without a terminal.

`seek --rpc` 启动一个 JSON-RPC 2.0 服务（stdin/stdout）。宿主进程发送请求并接收流式响应，无需终端。

    $ seek --rpc

📖 Detailed RPC protocol documentation is in `docs/guide-sessions.md`. 📖 详细 RPC 协议文档见 `docs/guide-sessions.md`。