> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 会话与上下文

Step Code 自动保存会话，支持恢复、分支导航、派生和导出。上下文接近模型窗口时，可通过压缩保留重要信息并继续工作。

## 会话存储

会话按工作目录分组，默认保存在 `~/.stepcode/agent/sessions/`。每个 JSONL 文件内部是树结构，记录通过 `id` 和 `parentId` 关联。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
~/.stepcode/agent/sessions/
├── <编码后的工作目录 A>/
│   └── <会话文件>.jsonl
└── <编码后的工作目录 B>/
    └── <会话文件>.jsonl
```

使用 `--session-dir <目录>` 自定义会话目录，或 `--no-session` 创建不保存的临时会话。会话文件是内部格式，不建议手工编辑。

## 启动与恢复会话

| 命令                        | 作用             |
| ------------------------- | -------------- |
| `step`                    | 在当前目录新建会话      |
| `step -c`                 | 继续最近一次会话       |
| `step -r`                 | 浏览历史会话并选择恢复    |
| `step --session <路径或 ID>` | 恢复指定会话，支持部分 ID |
| `step --fork <路径或 ID>`    | 从已有会话派生新会话文件   |
| `step --name "鉴权改造"`      | 设置会话名称         |

## 在 TUI 中切换会话

| 命令              | 作用                          |
| --------------- | --------------------------- |
| `/new`、`/clear` | 新建会话，清空当前对话上下文              |
| `/resume`       | 打开会话选择器                     |
| `/name`         | 为当前会话命名                     |
| `/session`      | 查看文件路径、ID、消息数、token 用量和成本信息 |
| `/fork`         | 派生独立会话                      |

会话选择器中可输入搜索词，Ctrl+S 切换排序，Ctrl+N 筛选命名会话，Ctrl+R 重命名，Ctrl+D 删除。删除前请确认是否还需要保留记录。

## 上下文压缩

自动压缩在上下文用量超过 `contextWindow - reserveTokens` 后，于工具批次结束等安全点执行。也可以手动指定需要保留的信息：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/compact 保留鉴权改造的目标、接口约定、已改文件、验证结果和未解决的问题
```

压缩保留最近约 `keepRecentTokens` 的消息，其余由模型生成八段结构化摘要，包含当前目标、已改文件、已验证结论和失败尝试等信息。后续请求由系统提示、摘要和保留消息组成。重要约定和验收结果也建议记录在项目文件中。

在 `config.toml` 中配置：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[compaction]
enabled = true
reserveTokens = 16384
keepRecentTokens = 20000
```

`enabled = false` 关闭自动压缩，但仍可手动运行 `/compact`。预留量和近期消息量应与模型上下文窗口匹配。

## 会话树与派生

| 命令       | 行为               | 适用场景            |
| -------- | ---------------- | --------------- |
| `/tree`  | 在同一会话文件中选择历史节点继续 | 回到较早的决策点尝试另一种方案 |
| `/fork`  | 从选定的用户消息派生新会话    | 隔离不同对话方案        |
| `/clone` | 将当前分支完整复制到新会话    | 保存当前状态后继续       |

`/tree` 中使用方向键导航、Enter 选择节点、Ctrl+O 切换过滤器（默认、无工具、仅用户消息、仅带标签）、Shift+L 编辑标签。选择用户消息时，其文本可回填到输入框，修改后重发形成新分支。

切换分支时可以生成摘要，帮助新位置理解被离开分支的内容；相关选项在 `[branchSummary]` 中配置。

<Note>
  会话分支只隔离对话记录，不会撤销磁盘文件修改，也不会创建 Git 分支。需要隔离代码实验时，请另行使用 Git 分支或 worktree。摘要和后续模型请求仍可能产生用量。
</Note>

## 导出与分享

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/export session.html
/export session.jsonl
/import session.jsonl
```

也可以在命令行导出：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --export /path/to/session.jsonl session.html
```

`/export [file]` 默认导出 HTML；使用 `.jsonl` 扩展名导出 JSONL，`/import <file>` 将其恢复为当前会话。导出可能包含代码、命令输出与路径，分享前请检查。

## 下一步

* [数据路径](/docs/zh/step-code/configuration/data-paths)
* [常见使用案例](/docs/zh/step-code/guides/use-cases)
* [交互与输入](/docs/zh/step-code/guides/interaction)