Codex Skill版本管理怎么做：规则、脚本和样例要一起留痕

给Codex Skill做轻量版本管理：规则、脚本和样例一起留痕，每次修改写清目的并运行回归，出现退化时能恢复上个可用版本。

2026-07-28约 4 分钟阅读Codex使用教程

先看重点：快速结论

同一输入契约同时约束说明、脚本、资源和测试。
版本号不保证行为相同，还要记录客户端、模型、运行时与外部依赖。

本文目录 · 跳到当前步骤

只给 SKILL.md 改一个版本号，不能恢复旧行为。规则、脚本、资源和依赖若来自不同时间，旧提示词也可能调用新脚本。本页对任务统计脚本建立一个能比较和回退的检查点。

哪些内容要一起保存

在该 Skill 目录加入 fixtures/、CHANGELOG.md 和 environment.md。固定样本至少包含 normal.json、empty.json、invalid-status.json 与 duplicate-id.json；具体数据沿用前两篇并保留完整输入。

environment.md 可以按下面记录，未运行的字段明确留待填写，不编写一份假测试结果：

markdown

# 验证环境
- 验证日期：待实际运行填写
- Codex 客户端与版本：待填写
- 实际模型或配置：待填写；不记录凭证
- Node.js 版本：运行 node --version 后填写
- 输入契约：id/title 非空、id 唯一、status 仅 done/todo
- 外部依赖：无；脚本只读本地 JSON
- Skill 调用测试：尚未执行
- Node 脚本测试：尚未执行

说明输出和脚本输出可以采用不同表现形式，但字段含义必须一致。脚本返回 todoIds 数组，说明不能又把 todo 解释为“已经逾期”。

建立 v1 检查点

在单独的教学仓库或分支中确认这些文件都是自己的本次改动。先查看范围：

powershell

git status --short -- .agents/skills/task-status-summary
git diff -- .agents/skills/task-status-summary

运行调试篇的正常与异常命令，把实际输出写入 CHANGELOG.md。只有实际验证后才能写通过；当前文章不代表你的客户端测试完成。确认后限定路径提交：

powershell

git add -- .agents/skills/task-status-summary
git diff --cached --stat
git commit -m "Add task status summary v1"
git tag task-status-summary-v1

如果暂存区还有无关文件，先处理归属，不能直接提交这一切。标签已存在时不要强制覆盖，查清它指向的提交或另起新标签。Git 未配置身份时，按自己的身份配置，不从教程复制陌生作者。

v2 必须带着失败样本来改

假设真实输入需要增加 blocked 状态。这个变更不能只把资源改成三种状态，还要同时定义 blocked 的含义、计数字段、说明输出和未知状态处理。

固定输入	v1 预期	拟议 v2 预期
done、todo、todo	total 3，done 1，todo 2	原字段不变，新增 blocked 0
[]	total/done/todo 为 0	再有 blocked 0
一条 blocked	拒绝未知状态	blocked 1，不计入 todo
重复 id	拒绝	仍拒绝
一条其他未知状态	拒绝	仍拒绝

这张表是变更设计，不是当前 v1 脚本已经支持的功能。让 Codex 围绕它修改并加入测试；若只把 blocked 静默归为 todo，即使程序退出 0 也不满足新契约。比较时对齐同一输入、运行时和 Skill 文件版本，保留 v1 与 v2 的结果。

回退要恢复整个 Skill 范围

如果 v2 回归失败，先保存本次失败改动的 diff 或单独提交，避免覆盖尚未留存的工作。确认 Skill 范围内没有他人未保存的改动，再按标签恢复已跟踪文件：

powershell

git restore --source=task-status-summary-v1 --worktree -- .agents/skills/task-status-summary
git diff -- .agents/skills/task-status-summary
git status --short -- .agents/skills/task-status-summary

这个操作会覆盖该范围的已跟踪工作区内容，不适合在未检查的混合工作区直接执行；它不会替你清理额外未跟踪文件。若 v2 新增了同名入口或脚本，逐个核对，避免客户端仍发现另一个副本，不要运行全仓库清理命令。

回退后重跑正常、空数组、重复 ID 和未知状态，再重新验证客户端发现的是该目录的版本。根据当前官方说明检查重载状态，必要时重启客户端。

为什么回退后仍可能不同

Git 能恢复保存过的文件，不能倒退远程模型、外部 API、系统环境或自动升级的客户端。把脚本确定性测试与模型调用测试分开记录；前者一致但后者变化时，应继续排查模型、输入上下文和权限，而不是反复覆盖 Skill 文件。

版本管理的交付是一组可定位文件、输入、环境和结果。是否发布 v2 取决于真实回归，不取决于版本号看起来更新。

资料来源

Git tag
轻量版本检查点。
Git restore
只恢复明确的已跟踪路径；注意工作区覆盖。
OpenAI Skills
Skill 组成与发现方式。

下一步

继续阅读与你当前问题相关的教程：