Session 管理 —— --continue、--session 与恢复流程全解析

简介

在使用 AI 编程 Agent 工具进行项目开发时，一个常见且重要的需求是：如何中断对话后重新恢复上下文？

想象以下场景：

你下午用 OpenCode 讨论了半小时的架构设计方案，下班后明天早上想接着继续
你在一个复杂的 Bug 修复过程中意外关闭了终端
你需要在多个不同项目之间切换，每个项目都有独立的对话历史
你想要把一段有价值的对话保存下来，作为后续开发的参考

这些场景的核心需求就是 Session 管理——保存、恢复、切换和重用对话上下文。

OpenCode 提供了强大的会话管理机制，通过 --continue、--session 参数以及会话 ID 系统，让你可以灵活地管理对话历史。本文将全面解析这些功能的使用方法、内部原理和最佳实践。

一、Session 基础概念

1.1 什么是 Session？

一个 Session（会话）就是一次完整的对话上下文，包含：

text

Session 组成：
├── 用户输入的历史消息
├── AI 的回复和代码操作
├── 工具调用的结果
├── 文件修改的记录
├── 上下文状态（当前目录、环境变量等）
└── 元数据（时间戳、使用的模型等）

每个 Session 都有一个唯一的标识符，通常是一个 UUID 或时间戳+哈希的组合。

1.2 Session 的生命周期

text

创建 ──→ 交互 ──→ 保存 ──→ [恢复] ──→ 继续交互 ──→ 关闭
  ↑                                        │
  └────────────────────────────────────────┘
              可以多次恢复

Session 可以：

创建：启动一个新的对话
交互：发送消息、接收回复、执行工具
保存：自动或手动保存对话历史
恢复：加载之前的对话继续
关闭：结束并归档会话

二、启动新 Session

2.1 默认行为

当你直接启动 OpenCode 时，会自动创建一个新的 Session：

bash

# 启动新 Session
opencode

# 指定工作目录启动
opencode /opt/data/my-project

OpenCode 会为这次对话生成一个唯一的 Session ID，并自动保存到本地存储中。

2.2 Session ID 的格式

Session ID 通常采用以下格式：

text

# Session ID 示例
20240115-143022-abc123def
session_2024-01-15_14-30-22-uuid

具体格式取决于 OpenCode 的版本和配置，但核心原则是全局唯一且可排序。

2.3 查看当前 Session 信息

bash

# 在 OpenCode 交互界面中
/session info

# 或查看会话列表
/sessions list

输出示例：

text

当前会话:
  ID: 20240115-143022-abc123def
  开始时间: 2024-01-15 14:30:22
  消息数: 23
  工具调用: 8
  工作目录: /opt/data/my-project

三、--continue：恢复上一个 Session

3.1 基本用法

--continue 参数用于恢复最近一次使用的 Session：

bash

# 恢复上次会话
opencode --continue

# 简写形式（如果支持）
opencode -c

这是最常用的恢复方式，适合"中断后继续"的场景。

3.2 --continue 的内部流程

text

执行 opencode --continue
        │
        ▼
┌─────────────────────┐
│ 读取 last_session_id │
│ 从本地存储中查找     │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ 加载会话历史         │
│ - 消息记录           │
│ - 工具调用结果       │
│ - 文件修改记录       │
│ - 上下文状态         │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ 重建 AI 上下文       │
│ (注入历史到 system   │
│  prompt)            │
└────────┬────────────┘
         │
         ▼
    可以继续对话

3.3 --continue 的使用场景

bash

# 场景 1：下班后继续上午的工作
# 上午：
opencode  # 工作了2小时，讨论了数据库重构方案
# 下班
# 第二天早上：
opencode --continue  # 自动恢复昨天的对话

# 场景 2：中断的 Bug 修复
opencode  # 正在排查一个复杂的并发 Bug
# 突然需要开会，Ctrl+C 退出
# 开完会回来：
opencode --continue  # 接着排查

3.4 --continue 的注意事项

bash

# ⚠️ 注意 1：--continue 恢复的是最近一个 Session
# 如果你中间打开了新的 Session，它会恢复那个新的

# 解决方法：使用 --session 指定具体 ID
opencode --session 20240115-143022-abc123def

# ⚠️ 注意 2：恢复后的 Session 会继承之前的上下文
# 如果之前的上下文很大，可能会增加 token 消耗
# 建议：定期清理不需要的历史

四、--session：指定 Session ID 恢复

4.1 基本用法

--session 参数允许你通过 Session ID 精确恢复某个特定会话：

bash

# 通过 Session ID 恢复
opencode --session 20240115-143022-abc123def

# 恢复后继续对话
(opencode prompt)> 接着我们刚才讨论的数据库重构方案...

4.2 查看历史 Session 列表

bash

# 列出所有 Session
opencode --sessions list

# 或使用内部命令
/sessions list

# 按时间排序
/sessions list --sort time

# 搜索特定项目的 Session
/sessions search "my-project"

输出示例：

text

Session 列表：
  ID                              项目            开始时间        消息数
  ─────────────────────────────── ─────────────── ────────────── ──────
  20240115-143022-abc123def       my-project      2024-01-15 14:30  45
  20240114-091500-xyz789ghi       api-service     2024-01-14 09:15  23
  20240113-160000-mno456pqr       web-frontend    2024-01-13 16:00  67
  20240112-100000-stu123vwx       data-pipeline   2024-01-12 10:00  12

4.3 从 Session 列表中恢复

bash

# 方法 1：直接指定 ID
opencode --session 20240114-091500-xyz789ghi

# 方法 2：使用索引（如果工具支持）
opencode --session @2  # 恢复列表中的第 2 个

# 方法 3：交互式选择
opencode --session select  # 弹出选择界面

五、Session 存储与管理

5.1 存储位置

OpenCode 的 Session 数据通常存储在以下位置：

bash

# 默认存储路径
~/.config/opencode/sessions/
├── 20240115-143022-abc123def.json
├── 20240114-091500-xyz789ghi.json
└── ...

# 或
~/.local/share/opencode/sessions/

5.2 Session 文件格式

一个典型的 Session 文件结构：

json

{
  "id": "20240115-143022-abc123def",
  "created_at": "2024-01-15T14:30:22Z",
  "updated_at": "2024-01-15T16:45:00Z",
  "workdir": "/opt/data/my-project",
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "请帮我重构 database.py 中的连接池逻辑",
      "timestamp": "2024-01-15T14:30:25Z"
    },
    {
      "role": "assistant",
      "content": "好的，让我先查看当前的数据库连接实现...",
      "tool_calls": [
        {
          "tool": "read_file",
          "args": {"path": "database.py"},
          "result": "..."
        }
      ]
    }
  ],
  "file_changes": [
    {
      "path": "database.py",
      "action": "modified",
      "diff": "--- a/database.py\n+++ b/database.py\n..."
    }
  ],
  "metadata": {
    "total_tokens": 15420,
    "total_cost": 0.0231,
    "tool_calls_count": 8
  }
}

5.3 手动管理 Session 文件

bash

# 查看 Session 文件列表
ls -la ~/.config/opencode/sessions/

# 查看某个 Session 的大小（评估历史长度）
wc -l ~/.config/opencode/sessions/20240115-143022-abc123def.json

# 清理旧的 Session 文件（保留最近 30 天）
find ~/.config/opencode/sessions/ -name "*.json" -mtime +30 -delete

# 备份 Session 数据
cp -r ~/.config/opencode/sessions/ ~/backup/opencode-sessions-$(date +%Y%m%d)/

六、高级恢复场景

6.1 恢复后从特定点继续

有时你不想恢复整个 Session，而是想从某个中间点开始：

bash

# 方法：创建新 Session 但注入部分历史
# 1. 导出历史消息
opencode --export-session 20240115-143022-abc123def > history.md

# 2. 在新 Session 中引用
opencode
(opencode prompt)> 参考以下历史对话继续：
(opencode prompt)> ```
(opencode prompt)> [粘贴关键历史内容]
(opencode prompt)> ```
(opencode prompt)> 请接着讨论数据库连接池的优化方案

6.2 跨项目恢复 Session

bash

# 场景：在 A 项目中启动了 Session，想在 B 项目中继续讨论

# 方法 1：恢复原始 Session（保持在原始工作目录）
opencode --session 20240115-143022-abc123def

# 方法 2：恢复并切换工作目录
opencode --session 20240115-143022-abc123def --workdir /opt/data/new-project

# ⚠️ 注意：切换工作目录后，之前引用的文件路径可能失效

6.3 Session 分支与合并

bash

# 场景：你想基于一个现有 Session 创建多个分支，分别探索不同方案

# 分支 1：探索方案 A
opencode --session 20240115-143022-abc123def --branch "方案A-使用Redis"

# 分支 2：探索方案 B
opencode --session 20240115-143022-abc123def --branch "方案B-使用Memcached"

# 这样你有两个独立的新 Session，都继承了原 Session 的历史

七、实战工作流：Session 管理最佳实践

7.1 项目级 Session 管理

bash

# 为每个项目维护独立的 Session

# 项目 A：后端 API 开发
opencode --workdir /opt/data/backend-api
# ... 工作 ...
# 退出后恢复：
opencode --continue  # 恢复后端 API 的 Session

# 项目 B：前端开发
opencode --workdir /opt/data/frontend-app
# ... 工作 ...
# 恢复前端 Session：
opencode --continue  # 恢复前端 App 的 Session

7.2 任务级 Session 管理

bash

# 按任务粒度创建 Session，而不是按项目

# 任务 1：修复登录 Bug
opencode --session new
(opencode prompt)> 帮我修复登录页面的 Token 过期问题
# ... 完成后退出 ...

# 任务 2：添加新功能
opencode --session new
(opencode prompt)> 在用户页面添加头像上传功能
# ... 完成后退出 ...

# 后续恢复某个任务：
opencode --sessions list  # 查看列表
opencode --session <任务对应的ID>

7.3 自动保存与手动保存

bash

# OpenCode 通常会自动保存 Session
# 但你也可以手动触发保存

# 在交互界面中：
/save  # 手动保存当前 Session
/save as "数据库重构方案讨论"  # 保存并命名

# 查看保存的 Session
/sessions list --recent

7.4 Session 清理策略

python

# 定期清理脚本示例
import os
import json
from datetime import datetime, timedelta

SESSION_DIR = os.path.expanduser("~/.config/opencode/sessions/")

# 清理超过 90 天的 Session
cutoff = datetime.now() - timedelta(days=90)

for filename in os.listdir(SESSION_DIR):
    if filename.endswith(".json"):
        filepath = os.path.join(SESSION_DIR, filename)
        with open(filepath) as f:
            data = json.load(f)
            created = datetime.fromisoformat(data["created_at"].replace("Z", "+00:00"))
            if created < cutoff:
                print(f"删除旧 Session: {filename}")
                os.remove(filepath)

八、常见问题与故障排查

8.1 问题：--continue 找不到上次 Session

bash

# 原因 1：中间打开了新 Session
# 解决：使用 --session 指定具体 ID

# 原因 2：Session 文件被删除或移动
# 解决：检查存储目录
ls -la ~/.config/opencode/sessions/

# 原因 3：使用了不同的工作目录
# 解决：切换到原始工作目录后再 --continue
cd /opt/data/my-project
opencode --continue

8.2 问题：恢复后上下文丢失

bash

# 原因：Session 文件损坏或不完整
# 排查步骤：

# 1. 检查 Session 文件
cat ~/.config/opencode/sessions/20240115-143022-abc123def.json | jq '.messages | length'

# 2. 如果消息数为 0 或文件损坏，可能无法恢复
# 3. 从备份中恢复（如果你有定期备份的话）

8.3 问题：Session 过大导致性能下降

bash

# 原因：Session 历史太长，token 数量过多
# 解决方案：

# 1. 创建新 Session 而不是继续旧 Session
opencode --session new

# 2. 在新 Session 中简要总结之前的进展
(opencode prompt)> 之前我们讨论了数据库重构，结论是使用连接池...
(opencode prompt)> 请继续帮我优化查询性能

# 3. 或者使用 /compact 命令压缩历史（如果支持）
/compact  # 压缩历史消息，保留关键信息

九、Session 与团队协作

9.1 导出和分享 Session

bash

# 导出 Session 为 Markdown
opencode --export-session 20240115-143022-abc123def --format markdown > discussion.md

# 导出为 JSON
opencode --export-session 20240115-143022-abc123def --format json > session.json

# 分享给团队成员
scp session.json team-member@server:/opt/data/shared/sessions/

9.2 导入他人 Session

bash

# 导入团队分享的 Session
opencode --import-session /opt/data/shared/sessions/session.json

# 导入后作为新 Session 继续
opencode --continue

总结

本文全面解析了 OpenCode 的 Session 管理机制：

Session 是对话上下文的载体，包含消息历史、工具调用、文件修改等
--continue 快速恢复最近一次会话，适合日常中断后继续
--session 精确恢复指定会话，适合多项目多任务管理
Session 文件存储在本地配置目录，可以手动备份和清理
恢复流程包括加载历史、重建上下文、继续交互三个阶段
最佳实践包括按任务粒度创建 Session、定期清理、备份重要对话

掌握 Session 管理技巧，可以让你的 AI 编程工作流更加连贯高效，不再因为中断而丢失宝贵的上下文。