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 字段。

opencode会话同步skill

Session Sync

功能特性

安装

全局安装（推荐）

项目本地安装

目录结构

前置配置

1. 配置 API Token

2. 配置 Gist ID

使用方式

上传会话（Push）

恢复会话（Pull）

列出现有会话

工作流程示例

场景一：备份当前会话

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

场景三：跨平台同步

环境变量参考

文件说明

注意事项

故障排除

错误：缺少 Token

错误：未配置 Gist ID

错误：Missing key at "id"

错误：Missing key at $"id"$