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：
- 访问 https://gitee.com 或 https://gist.github.com
- 创建一个新的 Gist（可以是空的）
- 从 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_xxxWindows:
# 上传当前会话（最近一个）~/.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 listWindows:
~/.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"环境变量参考
| 变量名 | 必需 | 默认值 | 说明 |
|---|---|---|---|
GITEE_TOKEN | 是* | - | Gitee API 令牌（使用 Gitee 时） |
GITHUB_TOKEN | 是* | - | GitHub API 令牌（使用 GitHub 时） |
OPENCODE_SYNC_PLATFORM | 否 | gitee | 平台选择：gitee或github |
OPENCODE_SYNC_GIST_ID | 否 | - | Gist ID（可选，也可通过映射文件配置） |
*使用对应平台时必需
文件说明
.session-gist.json：保存在项目根目录，记录该项目对应的 Gist ID 和平台信息。建议将其加入.gitignore。- 会话 JSON 文件：上传时会自动命名为
<project-name>-<session-title>.json。
注意事项
- Gist ID 不会自动创建：脚本永远不会自动创建新的 Gist，必须由用户明确提供 Gist ID。
- 会话 ID 自动添加：导出时会自动添加
id字段，确保可以成功导入。 - 项目隔离：每个项目的 Gist 映射文件保存在各自的项目根目录，互不干扰。
- 平台选择：默认使用 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字段。
