opencode会话同步skill

Session Sync

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

功能特性

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

安装

全局安装（推荐）

bash 复制代码

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

项目本地安装

bash 复制代码

# 复制session-sync到项目本地 skill 目录
 cp -r session-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文件)

bash 复制代码

# 使用 Gitee（默认）
export GITEE_TOKEN="your-gitee-token"

# 或使用 GitHub
export GITHUB_TOKEN="your-github-token"
export OPENCODE_SYNC_PLATFORM="github"

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

powershell 复制代码

# 使用 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:

bash 复制代码

export OPENCODE_SYNC_GIST_ID="your-gist-id"

Windows (PowerShell):

powershell 复制代码

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

方式二：映射文件

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

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 复制代码

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

# 上传指定会话
bash ~/.config/opencode/skills/session-sync/scripts/sync.sh push ses_xxx

Windows:

powershell 复制代码

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

# 上传指定会话
~/.config/opencode/skills/session-sync/scripts/sync.ps1 push ses_xxx

恢复会话（Pull）

从 Gist 下载并恢复会话：

Linux/macOS:

bash 复制代码

# 列出 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:

powershell 复制代码

# 列出 Gist 中的所有会话文件
~/.config/opencode/skills/session-sync/scripts/sync.ps1 pull

# 恢复指定会话
~/.config/opencode/skills/session-sync/scripts/sync.ps1 pull "projectname-sessiontitle.json"

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

bash 复制代码

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

列出现有会话

Linux/macOS:

bash 复制代码

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

Windows:

powershell 复制代码

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

工作流程示例

场景一：备份当前会话

bash 复制代码

# 1. 配置环境变量
export GITEE_TOKEN="your-token"
export OPENCODE_SYNC_GIST_ID="your-gist-id"

# 2. 上传当前会话
bash scripts/sync.sh push

# 输出：
# [session-sync] 项目: myproject
# [session-sync] 正在导出会话: ses_xxx ...
# [session-sync] 正在更新现有 Gist: abc123 ...
# [session-sync] 已更新: https://gist.github.com/abc123

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

bash 复制代码

# 1. 配置环境变量
export GITEE_TOKEN="your-token"
export OPENCODE_SYNC_GIST_ID="your-gist-id"

# 2. 列出可用的会话文件
bash scripts/sync.sh pull

# 输出：
# Gist 中可用的会话文件：
#  1. myproject-feature1.json
#  2. myproject-bugfix.json

# 3. 恢复指定会话
bash scripts/sync.sh pull "myproject-feature1.json"

# 4. 继续会话
opencode --continue

场景三：跨平台同步

在 macOS 上上传：

bash 复制代码

export GITEE_TOKEN="your-token"
export OPENCODE_SYNC_GIST_ID="your-gist-id"
bash scripts/sync.sh push

在 Windows 上下载：

powershell 复制代码

$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)步骤配置 Gist ID。

错误：Missing key at ["id"]

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