session-export

UniSessions 是一个优先考虑 SDK 的 AI CLI 会话转换器，用于x、Claude Code、Pi 和 OpenCode 会话，并在其上构建了 MCP 聊天。 <div align="center ▄▄▄ ▄▄▄▄▄ █▀██ ██ ██▀▀▀▀█▄ ██ ██ ▄ ▀▀ ▀ ▄▀ ▀▀ ▄ ██ ██ ████▄ ██ ▄▄ ▄█▀█▄ ▄██▀█ ▄██▀█ ██ ▄████▄ ▄█ ██ ██ ██ ██ ▄ ▀██▄█▀ ▀███▄ ▀██ ██ ██ ██ ██ █████▄ ▀█████▄▄██ ▀█▄██ ▀▄▀█▄▄▄█▄▄██▄▄██▀▄█████▀▄▀██▄▄██▀ ``` **在 Codex、OpenCode 和 Claude Code 之间转换 AI话格式。** 我使用了很多 AI 编程 CLIx、Claude Code、Pi 和 OpenCode，并不丢失有用的对话历史的情况下，将一个会话工具转移到另一个工具。 [](https.python.org/) []() [![https://img.shields.io/badge/Providers-4%20(Codex%20%7C%20Pi%7C%20OpenCode%20%720Claude)-purple)]() []() []() []() [](https://github.com/vibheksoni/session-export/stargazers) </div> --- ## 目录 - [为什么我创建了这个](#为什么我创建了这个) 快速开始](#快速 [支持的 AI 编程代理](#支持的-ai-编程代理) - [所有 12 种转换方向](#所有-12种转换方向) 列出会话](#如何列出会话) -转换会话](#如何转换会话) - [如何](#如何处理冲突) - [如何批量导出](#导出) - [如何使用自定义路径](#如何) - [用于代理聊天回忆的 MCP代理聊天回忆的-mcp-服务器) -法](#sdk-用法) - [架构- [默认会话路径](#默认会话路径) - [数据保真度](#数据保真度) 性能](#性能) - [FAQ](#faq) 贡献](#贡献) - [开发](#开发) -](#许可证) ## 为什么我创建了这个 我寻找了一个可以将一个 AI CLI 会话转换为另一个 AI CLI 会话格式的工具，但没有找到，所以我创建了一个。 我还希望我的代理能够记住其他会话中的事情我在某个项目中解决了一个错误，我希望告诉嘿，在另一个会话中，我通过执行 X 修复”，它会去检查并学习它，而不是让我再次解释同样的事情。 所以，这个工具做两件事： 在 Codex、Pi、OpenCode 和 Claude Code 之间以任意方向移动会话，所有 12 种组合 让您的代理搜索所有旧聊天历史记录，跨越所有项目和提供商，以便它可以回忆您之前做了什么并从中然后，我希望该项目不要局限于 CLI 或 MCP，它是一个优先考虑 SDK 的项目，因此您可以将其用于其他项目，做一些很酷的事情，比如为它构建一个 GUI 或其他您想要的东西，CLI 和 MCP 服务器只是建立在 SDK 之上的。 ## 快速开始 克隆仓库并直接从中运行。 ```powershell git clone https://github.com/vibheksoni/session-export.git cd session-export python -m unisessions list codex python -m unisessions list pi python -m unisessions list opencode python -m unisessions list claude ``` 转换单个会话（先进行 dry-run，然后写入）： ```powershell python -m unisessions codex-to-pi <session-id> python -m unisessions codex-to-pi <session-id> --write python -m unisessions claude-to-pi <session-id> --write ``` 批量导出所有 Codex 会话到 Pi： ```powershell python -m unisessions codex-to-pi-all --workers 8 ``` 通过 MCP 搜索所有会话： ```powershell python -m uniscp_server ``` ## 支持的 AI 编程代理 | 代理 | 存储 | 会话格式 | 会话 ID | | --- | --- | --- | --- | | [OpenAI Codex](https://github.com/openai/codex) | `codex` | JSONL 卷动文件，位于日期树下 | UUID v7 | | [Pi](github.com/ear-works/pi-coding | `pi` | JSONL 追加树，位于 cwd 编码目录中 | UUID v| [OpenCode://github.com/sst/opencode) | `opencode` | 官方导出/导入 JSON | 以_` 开头的 | Claude Code](https://docs.anthropic/docs/claude-code) | `claude` | JSONL 转录文件，位于 cwd 消毒目录中 | UUID v4 | ## 所有 12 种转换方向 | 来源 \ 目标 | Pi | Codex | OpenCode | Claude | | --- | --- | --- | --- | --- | | **Codex** | `codex-to-pi` | - | `codexencode` | `-to-claude`Pi** | - | `pi-to-code `pi-to` | `pi-to-claude` | | **OpenCode** | `opencode-to-pi` | `opencode-to-codex` | - | `opencode-to-claude` | Claude** | `claude-to-pi` | `claude-to-codex` | `claude-to-opencode` | - | ## 如何列出会话 ```powershell python -m unisessions list codex python -m unisessions list pi python -m unisessions list opencode python -m unisessions list claude ``` ## 如何转换会话 所有命令默认进行 dry-run。添加 `--write` 以生成输出。 ```powershell python -m unisessions codex-to-pi <session-id> --write python -m unisessions pi-to-codex <session-id> --write python -m unisessions codex-to-opencode <session-id> --write -m unisessions pi-to-opencode <session-id> --write python -m unisessions opencode-to-codex <session-id> --write python -m unisessions opencode-to-pi <session-id> --write python -m unisessions claude-to-pi <session-id> --write python -m unisessions pi-to-claude <session-id> --write python -m unisessions claude-to-codex <session-id> --write python -m unisessions codex-to-claude <session-id> --write python -m unisessions claude-to-opencode <session-id> --write python -m unisessions opencode-to-claude <session-id> --write ``` ## 如何处理冲突 当目标文件已经存在时，使用 `--on-conflict` 控制行为： | 模式 | 行为 | | --- | --- | | `skip`（默认） | 如果目标存在，则跳过 | | `overwrite` | 用新内容替换现有目标 | | `fork` | 生成新的 UUID 会话 ID，保留旧文件不变 | | `update` | 如果不变，则跳过，如果源更改，则覆盖（快速头部元数据 + 行数检查） | ```powershell python -m unisessions codex-to-pi <id> --write --on-conflict fork python -m unisessions codex-to-pi <id> --write --on-conflict update ``` ## 如何批量导出 将所有 Codex 会话导出到一个或多个目标，支持并行处理： ```powershell python -m unisessions codex-to-pi-all --write --workers 8 python -m unisessions export-all --write --targets pi opencode claude --workers 8 ``` ## 如何使用自定义路径 使用系统默认值时，省略路径标志。对于备份或暂存： ```powershell python -m unisessions --codex-session-dir C:\path\to\sessions list codex python -m unisessions --pi-session-dir C:\path\to\pi\sessions list pi python -m unisessions --opencode-session-dir C:\path\to\opencode\exports list opencode python -m unisessions --claude-session-dir C:\path\to\claude\projectsaude ``` OpenCode 输出文件使用官方导入/导出 JSON 格式。使用 `opencode import <-json>` 加载它们。 ## 用于代理聊天回忆的 MCP 服务器 UniSessions 配备了一个 [FastMCP](https://github.com/jlowin/fast) 服务器，该服务器在解析的会话聊天上公开了一个 SQLite FTS5 全文搜索AI 代理可以使用它来回忆过去的对话，找到讨论了什么，并跨所有提供商搜索。 ### 设置 ```powershell python -m unisessions.mcp_server ``` ### MCP 客户端配置 ```json { "mcpServers": { "unisessions": { "command": "unisessions-mcp", "args": [], "env": { "UNISESSIONS_SEARCH_INDEX": "C:\\Users\\you\\AppData\\Localessions\\search.sqlite" } } } } ``` ### 应用程序管理的服务器的 HTTP 传输 ```powershell unisessions-mcp --transport streamable-http --host 127.0.0.1 --port 8765 --path /mcp unisessions-mcp --transport http --host 127.0.0.1 --port 876unisessions-mcp --transport sse --host 127.0.0.1 --port 8765 ``` 环境变量：`UNISESSIONS_MCP_TRANSPORT`、`UNISESSIONS_MCP_HOST`、`UNISESSIONS_MCP_PORT`、`S_MCP_PATH`、`UNISESSIONS_LOG_LEVEL`、`UNISESSIONS_MCP_SHOW_BANNER`、`UNISESSIONS_SEARCH_INDEX`。 工具 | 工具 | 描述 | | --- | | `list_chats` | 全局列出会话或按提供商和项目 | | `index | 报告已索引、缺失、、已删除和刷新大小的计数 | | `refresh_chats 将会话解析到 SQLite FTS5 索引中以实现快速回忆 | | `search_chats` | 具有字面、正则表达式、所有关键词和任意关键词模式的全文本搜索 | | `search_sessions` | 查找与主题匹配的会话，并带有匹配计数和顶部片段 | `ats` 返回具有 `search_metadata`（总匹配数、去重、搜索会话数、搜索消息数、截断）和按相关性评分排名的 `results` 数组。跨压缩周期的重复消息会折叠为单个命中，并带有 `duplicate_count` 字段。 `search_chats`（`code、`pi`encode`、`claude`）、cwd、``、`role`（`user`、`assistant消息类型（`message`、`comp、`contextual`）、`exclude_keywords` 以过滤掉假阳性，`max_per_session`（默认为 5）以防止单个会话淹没结果，日期范围（`after`、`before`）和过时索引策略（`refresh`、`skip`、`error`）。 搜索在解析的 `TextMessage` 行上运行，而不是原始 JSON 文件，因此语义过滤器如 `roles=["user"]` 保持正确。工具调用和工具输出被排除，以保持回忆仅关注聊天文本。内部原始匹配上限为 200，以防止大规模会话超时。 **性能**：热索引搜索 ~35-40ms 适用于 20 会话的语料冷索引刷新 ~39-49s（I/O 绑定）。调用 `index_status`，然后调用 `refresh_chats_index`，然后使用 `search_chats`，并使用 `stale_policy="skip"` 进行快速交互式回忆。 ## SDK 用法 在 `session_sdk` 之上构建您自己的应用程序，而无需 CLI： ```python from session_sdk import ( CodexStore, PiStore, PiDcpStore, CodexToPiConverter, SessionIdFactory, WindowsDefaults, ) defaults = WindowsDefaults() codex = CodexStore(defaults.codex_home) pi = PiStore(defaults.pi_agent_home) dcp = PiDcpStore(defaults.pi_home) converter =ToPiConverter(codex, pi, dcp, SessionIdFactory()) plan = converter.plan("your-session-id-here") print(f"Source: {plan.source.path}") print(f"Destination: {plan.destination}") print(f"Records: {len(plan.records)}") converter.write(plan, overwrite=False) 搜索 API ```python from session_sdk import ( CodexStore, PiStore, OpenCodeStore, ClaudeStore, SessionSearchEngine, WindowsDefaults, ) defaults = WindowsDefaults() engine = SessionSearchEngine( CodexStore(defaults.codex_home), PiStore(defaults.pi_agent_home), OpenCodeStore(defaults.opencode_data_home), claude=ClaudeStore(defaults.claude_home), ) engine.refresh_index(provider="claude") response = engine.search( authentication", provider="claude", roles=["assistant"], stale_policy="skip", ) for hit in response["results"]: print(f"{hit['session_id']} [{hit['role']}] {hit['snippet'][:80]}") # SDK 出口，用于具有自定义排名或过滤的应用程序。 raw_rows = engine.raw_search_rows(query="authentication", provider="claude") engine.close() ``` ## 架构 ``` session-export/ pyproject.toml # 两个包 + 可选 [mcp] 额外依赖 session_sdk/ # SDK 核心（无 CLI 依赖） __init__.py # 公共 API 表面 json_types.py # JSON 类型守卫和强制转换 jsonl # JSONL 读取/写入帮助器（或json可用时使用orjson models.py # SessionSummary、TextMessage、NativeSession、ConversionPlan .py # WindowsDefaults、路径编码、SessionIdFactory、时间戳 stores.py # CodexStore、PiStore、PiDcpStore、Store、ClaudeStore converters.py # 提取器、构建器、12个转换器 search.py # 解析的 SQLite FTS5 聊天回忆索引/搜索 unisessions/ # CLI 和 MCP 应用程序（依赖 session_sdk） __init__.py __main__.py # python -m unisessions cli.py # argparse、命令路由、dry-run/write、冲突解决 mcp_server.py # 用于聊天回忆/搜索的 FastMCP 工具 tests/ test_conversion.py # 22 个测试 docs/ # 完整 API 文档 examples/ # 7 个测试的 Python 示例脚本 requirements.txt # tiktoken（必需）、orjson + google-re2（可选） requirements-mcp.txt # 用于 MCP 服务器的 fastmcp ``` ### 依赖链（无循环） ``` json_types （叶子） jsonl -> json_types models -> json_types paths （叶子） stores -> models, jsonl, json_types, paths converters -> stores, models, paths, json_types search -> stores, converters, models ``` SDK 永远不会导入 CLI。`unisessions` 依赖于 `session_sdk`，而不是相反。 ## 默认会话路径 | 代理 | 默认位置 | | --- | --- | | Codex 会话 | `~/.codex/sessions` | | Codex 存档 | `~/.codex/archived_sessions` | | Pi 会话 | `~/.pi/agent/sessions` | | Pi DCP 边车 | `~/.pi-dcp/sessions` | | OpenCode 数据 | `%APPDATA%\opencode` 或 `OPENCODE_GLOBAL_DATA_DIR` | | Claude Code | `~/.claude` 或 `CLAUDE_CONFIG_DIR` | ## 数据保真度 UniSessions 执行文本历史记录转换，而不是完整的行为状态重放。它保留用户/助手/系统文本和足够的元数据，以便目标工具打开会话。它不完全保留每个工具调用、提供者特定的事件、批准状态、沙盒状态、MCP 运行时或仅 UI 的事件。 ### 紧凑性处理 紧凑性标记在所有四种格式中保留，以便目标工具可以正确重建上下文： - **Pi**：`type="compaction"` 条目，带有 `summary`、`firstKeptEntryId`、`tokensBefore`、`details` 和 `fromHook=True` - **Codex**：`type="compacted"` 记录，带有 `payload.message` 摘要文本 - **OpenCode**：用户消息，带有 `CompactionPart` + 助手 `summary=True` - **Claude Code**：`system` 条目，带有 `subtype="compact_boundary"` + `logicalParentUuid`，后跟用户消息，带有 `isCompactSummary=true` ### 上下文消息处理 Codex 注入上下文消息（权限、AGENTS.md 说明、环境上下文、技能、插件）作为 `developer` 或 `user` 角色消息。这些消息由 SDK 提取器标记为 `is_contextual=True`，并在导出时被所有构建器跳过，以防止目标工具中的负载溢出。SDK 使用者仍然可以检查这些消息。 ## 性能 - 可用时使用 `orjson` 进行 JSON 解析（比标准库快 2 倍） - 可用时使用 `google-re2` 进行正则表达式搜索（比标准库 `re` 快 4 倍） - 通过缓存路径索引和 ID 索引实现 O(1) 会话查找 - `has_changes()` 读取头部元数据 + 行数（无完整 JSON 解析批量导出在会话之间重用转换器实例 - 默认批量：8（可选择更高；32 个工作线程测得的 2 倍） - 热：~35-40ms 20 会话的语料库 - 冷索引刷新：~49s（I/O 绑定；线程帮助适中） ## FAQ **我可以将 Claude Code 会话转换为 Pi 会话吗？** 是的。使用 `python -m un claude-to-pi <session-id> --write`。在 Codex、Pi、OpenCode 和 Claude Code 之间支持所有 12 种转换方向。 **我可以一次导出所有 Codex 会话吗？** 是的。使用 `python -m unisessions codex-to-pi-all --write --workers 8` 将所有 Codex 会话批量导出到 Pi。您也可以使用 `export-all --write --targets pi opencode claude` 一次导出到多个目标。 **我的 AI 代理可以搜索我的旧聊天？** 是的。 服务器公开了 `search_chats` 和 `search_sessions` 工具，它们对解析的聊天消息执行全文搜索。您的代理可以回忆任何会话中讨论的内容，跨项目。搜索在 SQLite FTS5 索引上运行，因此热查询约为 35ms。结果按相关性排名，去重，限制每个会话以防止超时。 **如果目标会话已经存在，会发生什么？** on-conflict` 控制行为：`skip`（默认）、`、`fork` UUID，保留旧文件）或`（如果不变，则跳过，如果源更改，则覆盖）。 是否保留工具调用和工具输出？** 不。该工具执行文本转换，保留用户和助手聊天消息、压缩摘要和会话元数据。工具调用和工具输出在当前版本中不保留。 **我可以在不 的情况下使用 SDK ** 是的。SDK（`session_sdk`）是一个独立的库，没有 CLI 依赖项。在您自己的 Python 项目中直接导入存储、转换器和搜索引擎。CLI 和 MCP 服务器是在其上构建的薄**支持哪些会话格式？** Codex JSONL 卷动文件、Pi JSONL 追加树条目、OpenCode 导出/导入 JSON 和 Claude Code JSONL 转录文件。所有四种格式在所有 12 种转换方向中都受支持。 **批量导出有多快？** 使用 8 个工作线程，276 个 Codex 会话到 Pi 的大约需要 65 秒。（700MB+）每个需要几秒钟。默认工作线程数为 8，因为在 I/O 工作负载中，较高的计数会测量较慢的性能。 ##1. 复刻仓库. 创建一个分支：` -b feature/your-feature` 3. 运行测试：`python unittest discover -s tests -4. 提交一个包含更改 PR。 ## 开发 ```python -m compileall session_sdk unisessions tests python -m unittest discover -s tests -v ``` 22 个测试涵盖转换形状、压缩提取/发射、dry-run 安全、助手使用估计、OpenCode JSON 形状、自定义会话目录、路径编码、Claude 提取和转换、搜索行为、搜索索引持久性、正则表达式完整索引搜索、关键字收缩处理和重复边缘情况。 ## 链接