Session Manager

在本机的 Codex、Claude Code、OpenCode 之间迁移可见对话历史。适配器把来源会话解析成统一的 user/assistant 消息序列，再生成目标工具能读取的会话格式，因此三个工具之间的六种转换方向都可用同一套命令。

支持范围

默认迁移用户/助手可见文本、消息顺序、时间、标题和工作目录。内部 thinking、工具调用与工具结果、审批/沙箱状态和多媒体附件不跨工具伪装成目标端原生记录。

平台和默认目录

支持 macOS、Windows、Linux。可以自动发现默认目录，也可以通过 --source-home、--target-home 或对应环境变量指定其他位置。

可用环境变量：Codex CODEX_HOME、Claude CLAUDE_CONFIG_DIR；OpenCode 在 macOS/Linux 遵循 XDG_DATA_HOME。OPENCODE_GLOBAL_DATA_DIR 可覆盖 Session Manager 的 OpenCode 数据目录；导入时会核对 OpenCode CLI 实际使用的数据库，避免导入到另一个数据目录。

安装

需要 Python 3.11 或更高版本。命令行只使用 Python 标准库；桌面界面使用 PyQt-Fluent-Widgets。

PyPI 包名是 coding-agent-session-manager，安装后的命令为 session-manager：

# CLI
python -m pip install coding-agent-session-manager

# CLI + 桌面 GUI
python -m pip install "coding-agent-session-manager[gui]"

从源码开发时使用可编辑安装：

python -m pip install -e .

安装桌面 GUI 依赖：

python -m pip install -e ".[gui]"

也可以不安装，直接从项目目录运行：

python -m coding_agent_session_manager --help

桌面 GUI

session-manager gui

GUI 可以浏览来源会话、查看 user/assistant 消息、用 Ctrl/Shift 多选会话并选择目标 Agent。迁移可以直接执行；“预览迁移”是可选的。批量直迁会逐条加载和写入，不会先把整批对话全部读入内存。GUI 也支持备份选中会话或当前来源工具的全部会话。OpenCode 目标会自动调用官方导入命令并注册到原项目；无法自动导入时会提供命令。GUI 默认使用 macOS、Windows、Linux 的工具数据目录；也可通过 --codex-home、--claude-home、--opencode-home 覆盖。

使用

# 列出所有工具最近的会话
session-manager list all

# 列出某个工具的会话（JSON 输出）
session-manager list codex --json

# 先预览转换计划；默认不会写入
session-manager convert codex claude <codex-session-id>

# 确认后执行
session-manager convert codex claude <codex-session-id> --write

# 批量预览 / 批量执行（执行时逐条迁移）
session-manager convert codex claude <session-id-1> <session-id-2>
session-manager convert codex claude <session-id-1> <session-id-2> --write

# 其他方向
session-manager convert claude codex <claude-session-id> --write
session-manager convert opencode claude <opencode-session-id> --write
session-manager convert claude opencode <claude-session-id> --write

# 备份一条会话 / 某个工具的全部会话
session-manager backup codex <codex-session-id> --output ~/SessionBackups
session-manager backup opencode --all --output ~/SessionBackups

GUI 不需要先点预览才能迁移。CLI 也不需要预先单独运行一次预览命令；需要直接执行时，在同一条命令加 --write。批量执行逐条读取和写入，并汇报每条的写入、跳过或错误状态。

OpenCode 目标会生成标准导入文件并尝试自动导入。CLI 找不到或使用的数据目录与 Session Manager 不一致时，会输出导入命令：

opencode import "<生成的 JSON 文件路径>"

OpenCode 来源数据库始终只读；导入目标时由 OpenCode 官方 CLI 写入其原生数据库，并按会话原工作目录注册。

自定义数据目录

session-manager list claude --home "/custom/claude-config"
session-manager convert opencode codex <session-id> \
  --source-home "/custom/opencode/opencode.db" \
  --target-home "/custom/codex" \
  --write

--source-home / --target-home 指向工具数据目录；读取 OpenCode 时也可以直接把 --source-home 指向数据库文件。--output <path> 可把生成结果写到指定路径。

备份

GUI 支持备份选中的会话或当前来源工具的全部会话。命令行示例：

session-manager backup claude <session-id>
session-manager backup codex --all --output ~/SessionBackups

每次备份都会创建带时间戳的新目录和 manifest.json。Codex、Claude Code 备份原生 JSONL 文件；OpenCode 备份该会话关联的 SQLite 原始行（含消息与 parts），并保持来源数据库只读。

冲突策略

默认 --on-conflict skip：相同来源重复迁移时使用稳定目标 ID，若目标已存在就跳过。也可以显式指定：

--on-conflict overwrite   # 覆盖同 ID 的目标会话
--on-conflict fork        # 生成新的目标会话 ID

开发和测试

python -m unittest discover -s tests -v

适配器遵循 AgentAdapter 接口。新增工具时实现会话发现、加载、目标格式计划、冲突检测和写入，再注册到 coding_agent_session_manager/registry.py，即可接入统一转换流程。

GitHub Actions 构建与发布

.github/workflows/release.yml 在推送到 main 时运行测试、构建四个平台安装包，并发布一个按 commit SHA 命名的 GitHub 预发布版；PR 只运行测试和构建，不发布 Release。

推送与 pyproject.toml 版本一致的标签（例如 v0.1.0）时，工作流会发布正式 GitHub Release 和 PyPI wheel/sdist：

git tag v0.1.0
git push origin v0.1.0

平台资产包括 Windows x86_64 ZIP、macOS Intel 与 Apple Silicon .app ZIP、Linux x86_64 tar.gz，以及 SHA256SUMS。macOS/Windows 构建目前未做代码签名/公证，首次打开时系统可能显示安全提示。

下载后：Windows 解压运行 SessionManager.exe；macOS 解压并打开 SessionManager.app；Linux 解压后运行 SessionManager/SessionManager。

PyPI 通过 GitHub OIDC Trusted Publishing 发布。首次发布前，在 PyPI 账户的 Publishing 设置添加 pending publisher：distribution coding-agent-session-manager、owner yhf98、repository agent-session-manager、workflow release.yml（environment 留空）；如果项目已存在，则在项目 Publishing 设置中添加。工作流已配置 id-token: write，不需要保存 PyPI API token。

macOS、Windows、Linux 的桌面包会作为 GitHub Release Assets 发布；Python/CLI 用户可安装 coding-agent-session-manager，桌面 GUI 可安装 [gui] extra。

License

Session Manager 按 GNU GPL v3.0 only 发布，与 PyQt-Fluent-Widgets 的 GPLv3 许可保持一致。