AI 工作版本管理
用户与 AI 迭代时常常丢失好版本：一次重新生成就覆盖了，一次撤销就过头了，或者对话偏离了方向。本技能将每一次改动都变成一个编号版本，该版本会一直保留直到用户主动删除，这样用户可以查看、对比并恢复任何历史状态。
三条规则
- 每次改动都生成一个版本。 一个用户请求中改变文件的操作为一个版本，在该轮对话结束时、您在回复之前保存。按请求保存（而非按每次文件编辑保存）能让历史保持可读性。
- 回退绝不删除版本。 只有脚本写入
.ai-versions/。切勿编辑、移动或删除其中的任何内容，即使被要求清理也请拒绝。请引导用户使用backup。 - 回退本身也是一个新版本。 使用脚本恢复；绝不要凭记忆重建旧工作。恢复操作会保存为一个新版本，因此也可以被撤销。
脚本负责选择每个版本号。切勿猜测版本号；报告脚本打印出的数字即可。
按项目选择模式
- 您可以运行命令并编辑文件（Claude Code, Cursor, Codex, Windsurf, Copilot, Gemini CLI, Replit Agent, claude.ai 含代码执行）：使用下方的文件模式。
- 项目包含
.github/workflows/ai-versions.yml：它使用 GitHub 版本层。不要运行init。相反，每次改动时覆盖.ai-versions/pending.json，需要回退时写入.ai-versions/restore.json。两者均在 assets/rules/github-layer-rules.md 中描述。 - 您无法运行命令（纯聊天）：遵循 references/chat-mode.md。
- 用户在 Lovable、Bolt 或 v0（Bolt 和 v0 处于测试阶段：尚未进行实时测试）或 Figma Make 中构建，并询问如何在该环境中进行版本管理：请阅读 references/app-builders.md。
文件模式
脚本位于本技能文件夹（即存放此 SKILL.md 的文件夹）内的 scripts/aiv.py。请使用完整路径调用它，并通过 --root 指定项目：
python3 "<本技能文件夹>/scripts/aiv.py" --root "<项目文件夹>" <命令>
# Windows: 将 python3 替换为 py
init 之后，每个项目也拥有自己的副本，因此从项目文件夹执行 python3 .ai-versions/aiv.py <命令> 效果相同。下文中的 aiv 表示两种形式均可。如果未安装 Python，请告知用户需要安装（python.org），并在安装完成前使用聊天模式。
初始化
在您首次编辑一个尚未包含 .ai-versions/ 的项目之前，请运行 init。它会将当前文件保存为 v1.0.0，这样用户始终可以回到您改动之前的状态。
如果该文件夹包含的项目之外还有其他内容（如沙盒、主文件夹、下载文件夹），请限定范围：init --only poster.html assets/。如果文件夹包含超过 5,000 个文件，init 将拒绝执行，因为这通常意味着选择了错误的文件夹。
每次改动后
aiv save --bump minor --summary "添加了包含三个方案的定价区域" \
--reason "新区域；布局和样式不变" --prompt "添加包含三个方案的定价"
--bump | 向用户展示为 | 适用场景 |
|---|---|---|
patch | 小调整 | 功能不变，细微调整：文字、颜色、间距、尺寸、小修复 |
minor | 新功能 | 新内容，方向不变：一个区域、页面、组件、功能 |
major | 大变更 | 方向改变：重新设计、新布局、新样式系统、移除功能 |
一次请求包含多项改动时，取最高级别。在两个级别间不确定时，取较低级别并在 --reason 中说明。边界情况（文档、重构、内容更新）见 references/bump-levels.md。
--summary 应面向用户而非开发者：“放大了主图”，而不是“更新 Hero.tsx”。将用户的请求缩短为一行，放入 --prompt。
然后在您的回复末尾加上一行，例如：已保存 v1.3.0（新功能）：添加了包含三个方案的定价区域。
如果 save 发现当前文件与某个旧版本完全一致，它会将该次保存记录为“回退到该版本”。请告知用户发生了什么。
用户提出请求时
| 用户说 | 运行 | 然后 |
|---|---|---|
| "显示版本", "历史" | list | 显示简短的表格。如需可视化时间线，运行 view 并分享它生成的 HTML 文件。 |
| "v1.3.0 中有什么变化" | diff v1.3.0^ v1.3.0 | 用通俗语言解释。vX^ 表示 vX 之前的版本。 |
| "比较 v1.2 和 v2.0" | diff v1.2.0 v2.0.0 --stat，然后不加 --stat 以获取详细信息 | 说明发生了什么变化、哪些地方变好了、哪些地方变差了。如果可以渲染作品（HTML、图片），请并排展示两者。 |
| "回到 v1.2.0", "撤销那个" | restore v1.2.0，或 restore prev 用于撤消 | 然后执行下面的步骤。 |
| "只恢复旧版头部", "保留新文本但用回旧设计" | restore v1.2.0 --path <文件> | 仅更改这些文件；该恢复保存为“小调整”。 |
| "从 v1.2.0 尝试另一个方向" | restore v1.2.0 | 然后进行新的改动并照常保存。 |
| "当前版本是什么", "有未保存的内容吗" | status | |
| "给我 v1.2.0 的文件" | export v1.2.0 --out v1.2.0.zip | |
| "在另一个聊天或工具中继续这个" | backup --out history.zip | 在新位置执行：import history.zip。 |
当用户模糊地描述版本时（“那个蓝色的”、“重新设计之前”），运行 list 并匹配摘要内容。如果有两个版本都符合，请询问用户。
回退之后
完整恢复会将所有项目文件恢复到之前的状态，包括用户可能不认为是工作组成部分的文件（如笔记或数据）。告知用户哪些文件发生了变化（脚本会列出它们）。如果它先保存了未保存的工作，请告知是哪个版本保存了该工作，并提供恢复特定文件的选项：restore <那个版本> --path <文件>。当请求明确只针对项目的一部分（如“旧的颜色”）时，从一开始就使用 --path。
运行 handoff <您恢复的版本>，并将其输出视为进行下一次改动前的当前事实。它只会列出导致该版本的决策，并命名被放弃的决策，这样从废弃方向产生的指令就不会悄悄混回来。如果对话很长，建议用户在一个新聊天中继续，并将 handoff 文本交给用户粘贴过去。
防止遗忘保存的安全网
在 Claude Code 或 Cursor 中，对每个项目提供一次此建议：install-hooks claude-code 或 install-hooks cursor。它会添加一个钩子，在您结束时将任何您忘记保存的改动保存为“小调整”。仅在用户同意后安装，因为它会写入他们的工具设置。
版本交流方式
使用用户的词语：小调整、新功能、大变更、已回退。提及版本号，而不是提交记录、.ai-versions/ 中的文件或哈希值。工具特定的说明（claude.ai, Replit, Windows）见 references/tools.md。
当用户回退时，提醒他们一次：只有文件会恢复回来；数据库行记录和其他实时数据将保持原样。
全部命令
| 命令 | 功能 |
|---|---|
init [--only PATH...] | 开始记录历史并保存 v1.0.0 |
save --bump B --summary S [--reason R] [--prompt P] | 将当前文件保存为新版本 |
status | 当前版本及未保存的更改 |
list [--all] [--json] | 列出版本，最新的在前 |
show V | 显示一个版本的详细信息及变更文件 |
diff [A] [B] [--stat] [--path P...] | 无参数：未保存的更改。一个参数：A 到最新。两个参数：A 到 B |
restore V [--path P...] [--note N] | 回退（所有文件或仅部分文件）；先保存未保存的工作，然后将恢复本身保存为新版本 |
handoff [V] | 清理上下文，以便从 V 版本继续 |
view [--out FILE] | 所有版本的 HTML 时间线 |
export V --out DIR_or_ZIP | 导出某个版本的文件 |
backup --out FILE.zip / import FILE.zip | 移动整个历史记录 |
install-hooks claude-code|cursor | 自动保存 AI 遗忘的内容 |
setup-github [--with-pill] | 为 app builder 仓库添加 GitHub 层 |
doctor | 检查历史记录是否缺失 |
版本可以写成 v1.2.0、1.2.0、latest、prev 或 v1.2.0^。