用途
sync-codex 用于在 easy-claude 框架中把以 .claude/ 为权威源的项目配置,同步成 Codex 可用的镜像产物,并对其执行完整校验。典型使用时点:某一变更对 .claude/** 的编辑已定稿、提交之前,运行本技能重新生成并验证 .agents/、.codex/、AGENTS.md 等产物。
主要能力
- 单一入口的 20 阶段流水线:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs。可用--list-stages查看各阶段清单,无需记忆。 - 第 1 阶段 CLAUDE.md 预检:缺失则初始化,标记管理的过期文件则更新,无标记文件视为项目自有、保持不动。
- 第 2-4 阶段生成 Codex 镜像:技能镜像写入
.agents/skills/,以.agents/skills/.codex-mirror.json记录自身生成的条目并清理源已消失的条目;写入.codex/agents/*.toml、.codex/hooks.json,并生成 AGENTS.md 投影。第 2 阶段还会把 TUI 通知与状态栏键写入.codex/config.toml。 - 第 5 阶段只重写指定文档中的
<!-- COUNT:… -->标记值。 - 第 6-20 阶段为只读校验:工具测试、可选的 tech-spec 新鲜度与特性注册表校验、3 个 hook 套件门禁、其他 Codex 校验器以及跨表面一致性检查。
- 技能档案(skillProfile)映射:把项目配置中的 skillProfile 映射到每个技能镜像的
agents/openai.yaml,并按需同步 Claude 侧的 skillOverrides。 - opencode 移交:项目存在本地
.opencode/目录且 20 个阶段全部通过后,自动移交给 sync-opencode(该移交属于集成步骤,不计入 20 阶段)。
使用方式
运行完整流水线:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs
查看阶段清单:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --list-stages
某阶段失败时单独重跑并输出详细信息,然后重跑完整流水线并检查生成的差异:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --only=<stage> --verbose
退出码 0 表示通过,并检查标准输出摘要。另有 --verify-only(只执行只读阶段,移交也继承只读约定)与 --skip=claude-md(跳过第 1 阶段,供 ai-context-refresh 完成编辑后调用,避免根文件被处理两次)。
主要规则与限制
.claude为权威源,.agents、.codex、AGENTS.md均为可丢弃的生成产物,不得手工编辑;已重命名,旧斜杠命令不再解析,应使用$sync-codex。- 可移植性:
.claude/与.codex/可复制进任意仓库,所有入口都用普通 node 调用;外部唯一要求是 node >= 18,无需 node_modules、npm 或 lockfile;目录清单再生成额外需要 Python 3。不要用宿主包的 package.json 脚本来驱动。 - 必须按顺序评估全部 20 个阶段;已配置阶段遇首个非零退出即失败,可选阶段在未声明其配置约定时显式跳过。
- 第 2 阶段仅管理其记录的镜像条目,其他工具安装或仅为 Codex 编写的条目保持原样;同名冲突时先把原条目备份到
tmp/codex-sync/replaced/<name>。 - 第 2 阶段不再写入
model_auto_compact_token_limit,仅在值恰为旧内置值 500000 时移除该顶层键;project_doc_max_bytes = 98304同理仅在恰为该旧值时移除,自定义值保留。 - 第 4 阶段生成的 AGENTS.md 只承载项目信息;共享协议与工作流路由通过镜像 hook 投递,首次同步及任何 handler 变更后需在 Codex
/hooks中审阅,未审阅前 Codex 收不到通用规则。 - 项目配置存在但 JSON 非法时同步失败(无法判断是否隐藏技能);拒绝的技能档案会在任何写入前退出 1。
- 测试阶段只在子进程中设
CK_FRAMEWORK_MODE=on,不改动用户保存的偏好。 - 幂等:可安全重复运行,第二次运行只产生时间戳差异。
适用场景
适用于使用 easy-claude 框架、需要在 Claude 与 Codex(以及可选 opencode)之间保持配置与技能一致的项目,尤其是把相关目录复制到不同语言仓库(如 Python、.NET 或无 package.json 的仓库)后仍需自运行、自测试的场景。具体收费与价格信息暂未提供。