LIghtJUNction/codex-sync

Profil LIghtJUNction

Dernière activité source enregistrée: 19 juillet 2026 à 10:50

Catalogue SkillsMP mis à jour: 17 octobre 2026 à 00:09

skills collectés: 1

Étoiles GitHub: 1
Forks GitHub: 0

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

# Codex Sync 在同一局域网的多台电脑之间同步 Codex 聊天记录和配置。提供命令行与内置 Web 界面。 ## 架构同步能力分为“通用核心、Codex 语义合并、传输适配器”三层： ```text HTTP / Web ───────┐ USB / SMB / Relay ├─ SnapshotSource ─ sync::core │ ├─ 清单、路径与哈希校验 SSH ──────────────┴─ 安全传输包 ──────┼─ 原子读写与冲突策略 └─ sync::codex ├─ rollout 增量去重 ├─ SQLite 合并 └─ session_index 修复 ``` - `sync::core` 是唯一的文件级同步基础实现。Web/HTTP 只负责网络读取，USB、SMB 和 Relay 只负责目录读写；清单验证、增量判断、冲突保留、哈希验证和原子落盘全部复用核心逻辑。 - `sync::codex` 是唯一的 Codex 数据语义实现。SSH 只负责调用系统 `ssh`/`scp` 传输安全包，rollout、SQLite 和侧栏索引的合并由该模块统一完成。 - `SnapshotSource` 是传输来源的 Rust trait。新增 S3、对象存储或其他只读来源时，只需为新类型实现这个 trait 的 `manifest` 与 `read` 方法；新增共享目录类型可直接复用现有目录适配器。源码采用 Rust 2018+ 的模块布局：`sync.rs`/`sync/`、`cli.rs`/`cli/` 由同名文件声明同名目录中的子模块，不使用 `mod.rs`。`lib.rs` 暴露可复用库，`main.rs` 只负责启动 CLI。这样传输协议不再各自维护一套同步规则，安全校验和合并行为也不会随适配器增加而分叉。 ## 快速开始 ```bash cargo build --release ./target/release/codex-sync init ``` 编辑 `~/.config/codex-sync/config.toml`，把 `shared_key` 改成一个随机长字符串；每台电脑使用相同密钥。随后运行： ```bash ./target/release/codex-sync serve ``` `shared_key` 至少需要 32 个字符。建议使用密码管理器生成的随机值；`init` 会在 Unix 系统将配置文件权限设为仅当前用户可读写。默认单文件上限为 256 MiB、单次清单上限为 100,000 个文件；可在配置中按需调整： ```toml max_file_size_bytes = 268435456 max_files = 100000 ``` 打开 `http://localhost:8787`，在页面中输入共享密钥（仅保存于当前浏览器会话）。也可以使用命令行： ```bash codex-sync peers codex-sync pull 192.168.1.20:8787 codex-sync status ``` ## U 盘离线中转在电脑 A 上导出（macOS 示例）： ```bash codex-sync usb export /Volumes/MYUSB ``` 把 U 盘插到电脑 B，查看并导入： ```bash codex-sync usb list /Volumes/MYUSB codex-sync usb import /Volumes/MYUSB ``` 如果 U 盘中有多台电脑的快照，`usb list` 会显示每个快照的具体目录，导入时指定该目录即可。导入会验证 BLAKE3 哈希；同名但内容不同的文件默认保存为冲突副本。需要明确覆盖时使用 `usb import PATH --overwrite`。 ## SMB 服务器中转 Codex Sync 使用操作系统已经挂载的 SMB 目录，不保存服务器用户名或密码。先通过系统连接共享： - macOS：访达 → 前往 → 连接服务器，输入 `smb://服务器/codex-sync`，通常挂载到 `/Volumes/codex-sync`。 - Windows：在资源管理器映射网络驱动器，例如 `Z:`。 - Linux：用桌面文件管理器挂载，或将共享挂载到 `/mnt/codex-sync`。电脑 A 推送快照： ```bash codex-sync smb push /Volumes/codex-sync ``` 电脑 B 查看并拉取： ```bash codex-sync smb list /Volumes/codex-sync codex-sync smb pull /Volumes/codex-sync ``` Windows 示例： ```powershell codex-sync.exe smb push Z:\ codex-sync.exe smb pull Z:\ ``` 共享中有多个设备快照时，先通过 `smb list` 找到目标快照的完整路径，再将它传给 `smb pull`。默认保留冲突副本；明确覆盖时添加 `--overwrite`。SMB 快照和 U 盘快照使用相同的开放目录格式，可以相互复制。 ## 其他中转方式 `relay` 支持任何在操作系统中表现为普通目录的中转服务，包括： - NFS、AFP 或 NAS 挂载目录 - WebDAV 挂载盘 - Syncthing、Resilio Sync 等点对点同步目录 - Dropbox、OneDrive、iCloud Drive、Google Drive 等桌面同步目录 - 虚拟机共享目录、远程开发共享目录通用用法： ```bash # 电脑 A 发布快照 codex-sync relay push /path/to/shared-folder # 电脑 B 查看及获取 codex-sync relay list /path/to/shared-folder codex-sync relay pull /path/to/shared-folder ``` 例如使用 Syncthing：先让两台电脑同步同一个 `CodexRelay` 文件夹，再分别运行： ```bash codex-sync relay push ~/Sync/CodexRelay codex-sync relay pull ~/Sync/CodexRelay ``` 例如使用 Windows OneDrive： ```powershell codex-sync.exe relay push "$env:OneDrive\CodexRelay" codex-sync.exe relay pull "$env:OneDrive\CodexRelay" ``` 使用云同步目录时，请等待云盘客户端完成上传或下载后再执行 `pull`。清单采用最后写入的原子替换方式，未完成的快照不会被识别为可导入快照。 ## 合并 CC-Switch 多账号记录 Codex Sync 可以把本机 CC-Switch 不同供应商产生的历史记录统一归入当前登录的 Codex 账号。先预览： ```bash codex-sync cc-switch status codex-sync cc-switch merge ``` 确认数量后，关闭 Codex 和 CC-Switch，再执行： ```bash codex-sync cc-switch merge --apply ``` 合并会同时更新会话 JSONL 的 `model_provider` 和 `state_5.sqlite` 的记录桶。执行前自动备份到 `~/.codex/codex-sync-backups/cc-switch-merge-时间戳`，该目录默认不会参与设备同步。此操作不读取、复制或修改 API Key、Token、`auth.json` 和供应商认证配置。 ## 修复本机多 provider / model 历史如果切换 API、provider、模型或登录方式后，本机历史文件还在但 Codex 侧栏不再显示，可以使用不依赖 CC-Switch 的 `history` 命令。先预览： ```bash codex-sync history doctor codex-sync history status codex-sync history merge ``` `history doctor` 是只读诊断命令，会检查 SQLite `quick_check`、非法会话 JSONL、缺失或重复的 `session_meta`、孤立或缺失的 rollout、重复/缺失/残留的侧栏索引。它默认永远不修改数据。只有侧栏索引存在可安全重建的问题时，才可执行： ```bash codex-sync history doctor --apply ``` 普通 `--apply` 不修改 SQLite、rollout 或 provider/model，只重建 `session_index.jsonl`。命令持有 SQLite 写锁，先保存原索引，在同目录写入并 `fsync` 临时文件后原子替换，随即复检；任何错误都会原子恢复原索引。非法 JSONL 和重复 `session_meta` 只会报告，不会被冒险自动修改。缺失 rollout 已经在备份中定位并人工确认时，可以显式恢复： ```bash codex-sync history doctor \ --restore-missing ~/.codex/codex-sync-backups/.../rollout-ID.jsonl \ --apply ``` 恢复前会验证来源是普通文件、大小受限、每行 JSON 合法、恰好包含一条 `session_meta`、线程 ID 和文件名均与数据库中缺失的 `rollout_path` 一致，并拒绝目录穿越或符号链接。目标 rollout 与索引分别使用原子替换，失败时删除新目标并恢复原索引。正式执行前仍建议完全退出 Codex 和 CC-Switch，避免应用在修复完成后用内存中的旧状态再次覆盖索引。对于已经停止写入、但混入多条 `session_meta` 的单个 rollout，可逐个执行： ```bash codex-sync history doctor \ --dedupe-session-meta ~/.codex/sessions/.../rollout-ID.jsonl \ --apply ``` 命令只保留线程数据库中该 `rollout_path` 对应 ID 的元数据行，其他事件行按原字节顺序保留。每次只处理一个文件，修改前保存原文件，提交前重新比较源字节，使用同步落盘后的原子替换；验证或提交失败时恢复原文件。正在写入的当前任务必须等 Codex 完全退出后再处理。确认待归并数量后执行： ```bash codex-sync history merge --apply ``` 该命令会把 `state_5.sqlite` 的线程归属和会话 JSONL 的 `session_meta` 统一到当前 `config.toml` 中的 `model_provider` / `model`，并补齐 `session_index.jsonl` 缺少的侧栏条目。使用 ChatGPT 登录且没有显式配置 `model_provider` 时，采用 Codex 内置的 `openai` provider。修改前会在线备份数据库、侧栏索引和会话文件，因此 Codex 正在运行时也会等待数据库写锁；若仍繁忙则安全失败，不会跳过备份强行写入。手动备份和恢复： ```bash codex-sync history backup codex-sync history restore ~/.codex/codex-sync-backups/history-merge-时间戳 codex-sync history restore ~/.codex/codex-sync-backups/history-merge-时间戳 --apply ``` 恢复默认也只预览，并且正式恢复前会再创建一份 `pre-history-restore` 安全备份。本功能的设计参考了 [GODGOD126/codex-history-sync-tool](https://github.com/GODGOD126/codex-history-sync-tool)，并在 Rust CLI 中扩展为 macOS、Linux 和 Windows 通用实现。 ## 默认同步方向 “把本机记录同步到某个目标”始终表示单向的“本机 → 目标”。目标端只作为写入位置，不会自动读取、下载或合并目标端已有的 Codex 记录。只有明确执行 `pull`、`import` 或提出从远端恢复时，才会把远端数据带回本机。 ## SSH 单向同步并合并本机与远端都安装 `codex-sync` 后，只需运行： ```bash codex-sync ssh push lty ``` `lty` 可以是 `~/.ssh/config` 中的主机别名，也可以是 `user@host`。该命令固定执行“本机 → 远端”： - 只从本机 `~/.codex` 提取会话、归档会话、附件、索引和 SQLite 线程记录。 - 不读取或下载远端已有聊天记录。 - 使用系统 `ssh`/`scp`，沿用现有 SSH Agent、密钥和主机配置。 - 上传后由远端 `codex-sync` 校验 BLAKE3 清单，再合并进远端 `~/.codex`。 - 默认进行增量合并：只追加本机新增记录，保留远端已有记录，且绝不把远端记录下载回本机。 - 同名 JSONL 会话会按事件行去重合并；同名附件或二进制文件仍保留远端版本并报告冲突。 - 每个 rollout 始终只保留一条 `session_meta`；数据库合并后按线程 ID 自动重建 `session_index.jsonl`，避免记录已入库但侧栏缺失。 - 仅在明确需要让远端完全等同于本机时，使用 `codex-sync ssh push HOST --mirror`；远端独有记录会先备份再移出活动历史。 - 导入的会话自动归入远端当前 `model_provider`。 - 修改前备份远端数据库和索引到 `~/.codex/codex-sync-backups/sync-import-时间戳`。 - 合并完成后自动删除两端临时传输包。如果远端尚未安装： ```bash ssh lty 'cargo install codex-sync' ``` ## 同步策略与安全 - 默认同步 `~/.codex`，排除 `auth.json`、凭据、日志、缓存和临时文件。 - 所有 API（包括状态、发现和 Web 拉取）均要求共享密钥认证；密钥不会经节点发现广播或写入 U 盘快照。 - LAN 与离线导入均校验清单路径、文件数量、文件大小和 BLAKE3 哈希；下载写入使用同步落盘后的原子替换，并拒绝写入符号链接。 - SMB 账号和密码由操作系统管理，不会写入 Codex Sync 配置或快照。 - 默认只拉取。遇到同名但内容不同的文件时，远端版本保存为 `.conflict-节点名`，不会覆盖本地内容。 - `pull --overwrite` 会覆盖不同内容的本地文件，使用前请自行备份。 - 服务默认监听 `0.0.0.0:8787`，请只在可信局域网使用，并通过系统防火墙限制访问。当前 LAN API 使用共享密钥而非 TLS；跨不可信网络时请使用 SSH、VPN 或受保护的中转目录。 ## 当前范围项目提供生产使用的安全基线：受限数据范围、配置权限、端到端完整性校验、冲突保留、原子发布、SSH 备份/合并，以及 macOS、Linux、Windows CI 门禁。自动后台双向同步、设备审批、TLS 终止与系统服务安装仍需按部署环境单独配置。 ## 许可证本项目采用 [MIT License](LICENSE) 开源。

Chargement du README du dépôt…

Skills dans ce dépôt

Développeurs de logiciels

1 catégories métier · 100% classifié

skill

métier

description

mis à jour

sync-codex-records

Développeurs de logiciels

Safely synchronize, merge, repair, migrate, back up, export, import, or relay local Codex chat records and configuration with this repository's codex-sync CLI. Use when a user asks to sync Codex conversations between computers over LAN or SSH; move or back up…

Langue du texte source : anglais

2026-07-19

Affichage de 1 skills collectés sur 1.

Installer avec un assistant IA

Copiez ce prompt dans l’assistant IA que vous utilisez.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/LIghtJUNction/codex-sync.