SuperAPI AI 工具集

sync-codex

编程与开发

查看项目

更新于 11-06 09:09

技能介绍

用途

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 的仓库)后仍需自运行、自测试的场景。具体收费与价格信息暂未提供。