Session Sync

OpenCode 会话同步工具 - 将会话导出保存到 GitHub/Gitee Gist，或从 Gist 拉取历史会话并导入本地。

仓库地址：skills: skill合集

功能特性

• 📤上传会话：将当前或指定的 OpenCode 会话导出为 JSON，上传/更新到 Gist
• 📥恢复会话：从 Gist 下载历史会话 JSON 并导入到当前项目
• 🔧自动管理 Gist ID：每个项目独立管理自己的 Gist 映射，无需用户记忆
• 🖥️跨平台支持：支持 Linux、macOS 和 Windows
• 🔒安全可靠：Gist 默认为私有，保护您的会话内容

安装

全局安装（推荐）

# 复制session-sync到全局 skill 目录cp-rsession-sync ~/.config/opencode/skills/session-sync

项目本地安装

# 复制session-sync到项目本地 skill 目录cp-rsession-sync ./.opencode/skills/session-sync

目录结构

session-sync/ ├── SKILL.md # 技能说明文档（Agent 使用） ├── README.md # 本文件 └── scripts/ ├── sync.sh # Linux/macOS 同步脚本 └── sync.ps1 # Windows 同步脚本

前置配置

1. 配置 API Token

在使用前，需要配置 GitHub 或 Gitee 的 API Token：

Linux/macOS:(Linux可以写入到.bashrc文件)

# 使用 Gitee（默认）exportGITEE_TOKEN="your-gitee-token"# 或使用 GitHubexportGITHUB_TOKEN="your-github-token"exportOPENCODE_SYNC_PLATFORM="github"

Windows (PowerShell):（Windows可以通过环境变量设置）

# 使用 Gitee（默认）$env:GITEE_TOKEN ="your-gitee-token"# 或使用 GitHub$env:GITHUB_TOKEN ="your-github-token"$env:OPENCODE_SYNC_PLATFORM ="github"

💡获取 Token：

• GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic)
• Gitee: 设置 → 私人令牌 → 生成新令牌
• 只需勾选gist权限

2. 配置 Gist ID

方式一：环境变量（推荐）

Linux/macOS:

exportOPENCODE_SYNC_GIST_ID="your-gist-id"

Windows (PowerShell):

$env:OPENCODE_SYNC_GIST_ID ="your-gist-id"

方式二：映射文件

在项目根目录创建.session-gist.json：

{"gist_id":"your-gist-id","platform":"gitee"}

💡获取 Gist ID：

1. 访问 https://gitee.com 或 https://gist.github.com
2. 创建一个新的 Gist（可以是空的）
3. 从 URL 中复制 Gist ID，例如：
   • URL:https://gist.github.com/username/abc123def456
   • Gist ID:abc123def456

使用方式

上传会话（Push）

将当前或指定的会话上传到 Gist：

Linux/macOS:

# 上传当前会话（最近一个）bash~/.config/opencode/skills/session-sync/scripts/sync.sh push# 上传指定会话bash~/.config/opencode/skills/session-sync/scripts/sync.sh push ses_xxx

Windows:

# 上传当前会话（最近一个）~/.config/opencode/skills/session-sync/scripts/sync.ps1 push# 上传指定会话~/.config/opencode/skills/session-sync/scripts/sync.ps1 push ses_xxx

恢复会话（Pull）

从 Gist 下载并恢复会话：

Linux/macOS:

# 列出 Gist 中的所有会话文件bash~/.config/opencode/skills/session-sync/scripts/sync.sh pull# 恢复指定会话bash~/.config/opencode/skills/session-sync/scripts/sync.sh pull"projectname-sessiontitle.json"

Windows:

# 列出 Gist 中的所有会话文件~/.config/opencode/skills/session-sync/scripts/sync.ps1 pull# 恢复指定会话~/.config/opencode/skills/session-sync/scripts/sync.ps1 pull"projectname-sessiontitle.json"

恢复后，使用以下命令继续会话：

opencode--continue# 或opencode--session<session-id>

列出现有会话

Linux/macOS:

bash~/.config/opencode/skills/session-sync/scripts/sync.sh list

Windows:

~/.config/opencode/skills/session-sync/scripts/sync.ps1 list

工作流程示例

场景一：备份当前会话

# 1. 配置环境变量exportGITEE_TOKEN="your-token"exportOPENCODE_SYNC_GIST_ID="your-gist-id"# 2. 上传当前会话bashscripts/sync.sh push# 输出：# [session-sync] 项目: myproject# [session-sync] 正在导出会话: ses_xxx ...# [session-sync] 正在更新现有 Gist: abc123 ...# [session-sync] 已更新: https://gist.github.com/abc123

场景二：在新电脑上恢复会话

# 1. 配置环境变量exportGITEE_TOKEN="your-token"exportOPENCODE_SYNC_GIST_ID="your-gist-id"# 2. 列出可用的会话文件bashscripts/sync.sh pull# 输出：# Gist 中可用的会话文件：# 1. myproject-feature1.json# 2. myproject-bugfix.json# 3. 恢复指定会话bashscripts/sync.sh pull"myproject-feature1.json"# 4. 继续会话opencode--continue

场景三：跨平台同步

在 macOS 上上传：

exportGITEE_TOKEN="your-token"exportOPENCODE_SYNC_GIST_ID="your-gist-id"bashscripts/sync.sh push

在 Windows 上下载：

$env:GITEE_TOKEN ="your-token"$env:OPENCODE_SYNC_GIST_ID ="your-gist-id"scripts/sync.ps1 pull"myproject-session.json"

环境变量参考

*使用对应平台时必需

文件说明

• .session-gist.json：保存在项目根目录，记录该项目对应的 Gist ID 和平台信息。建议将其加入.gitignore。
• 会话 JSON 文件：上传时会自动命名为<project-name>-<session-title>.json。

注意事项

1. Gist ID 不会自动创建：脚本永远不会自动创建新的 Gist，必须由用户明确提供 Gist ID。
2. 会话 ID 自动添加：导出时会自动添加id字段，确保可以成功导入。
3. 项目隔离：每个项目的 Gist 映射文件保存在各自的项目根目录，互不干扰。
4. 平台选择：默认使用 Gitee，如需使用 GitHub，请设置OPENCODE_SYNC_PLATFORM=github。

故障排除

错误：缺少 Token

错误：缺少 Token。请设置 GITHUB_TOKEN 或 GITEE_TOKEN 环境变量。

解决：按照前置配置步骤配置 API Token。

错误：未配置 Gist ID

错误：项目 'xxx' 未配置 Gist ID。

解决：按照配置 Gist ID步骤配置 Gist ID。

错误：Missing key at [“id”]

解决：此问题已在最新版本中修复。请确保使用最新版本的脚本，导出时会自动添加id字段。