Version Management Skill

版本管理

执行方式： 版本管理完全由本 Skill + send_file 实现；前后端不维护 Git、不记版本流水。Agent 在云机项目目录执行 git 与文件操作。下文 git 均为完整可执行命令；后期封装为 tool 后替换指令段落，决策逻辑与流程顺序不变。

对用户沟通规则： 版本管理的技术细节（git 命令、meta.json 更新、版本号计算等）是内部执行过程，禁止在对话中向用户展示或提及。用户只需看到：生成结果 + send_file 吐出的版本卡片。如需告知版本信息，只说"已保存为 V{n}"，不解释底层操作。

⚠️ 路径硬规则（最高优先级，写任何文件之前先执行本节）

本 Skill 必须在写出第一个入口文件之前介入，而不是产出之后补救。 任何入口文件（.html / .jsx / .tsx / .vue）第一次写入磁盘时，目标路径就必须位于 我的项目/{项目名}/ 内。

基准路径

「我的项目」固定位于工作区根目录，与 send_file 的 file_path 写法 /我的项目/{项目名}/... 一一对应。执行任何 mkdir / cd / 写文件操作之前，必须先回到工作区根目录（或使用从根目录起算的完整路径）；禁止在未确认 pwd 的情况下使用相对路径 我的项目/...——这是「我的项目」文件夹长在错误位置的常见原因。

写文件前的固定顺序（不可调换）

# 1. 确定项目名（生成规则见 §1.2）
# 2. 回到工作区根目录，创建项目目录
cd {工作区根目录}
mkdir -p "我的项目/{项目名}/assets"
# 3. 进入项目目录，之后所有文件【直接】在此目录内创建
cd "我的项目/{项目名}"
# 4. 写入 index.html / prototype.html 等入口文件与代码文件
# 5. 再进入 §1 的 git / meta.json / send_file 流程

违例清单（以下任何一种都算流程错误，即使事后移动也算）

• 先把文件写到工作区根目录、~/Desktop、/tmp 或当前任意目录，再移动进项目目录
• 只在对话中贴代码块，不落盘
• 在项目目录之外执行写文件命令

写文件前自检（最后一道闸）

调用任何写文件命令之前，自问一句：「我即将写入的目标路径，是否位于 我的项目/{项目名}/ 之内？」 答案不是 → 停止，先执行上面的固定顺序建目录，再写文件。

0. 与 Design Skill 的衔接（必读）

本 Skill 与 Design Skill 并列协作（二者由同一个 Design Agent 同时承载）：Design Skill 负责设计产出，本 Skill 负责落盘与版本管理。本节描述二者在 HTML 交付场景下的协同过程。

触发不依赖 Design Skill。 本 Skill 按文件类型触发：只要产出或修改入口文件（.html / .jsx / .tsx / .vue）就必须走本 Skill，与该任务是否经过 Design Skill 路由无关——包括未走任何设计流程、直接裸改已有 HTML 文字/颜色的情况（此时跳过 quality-gate，直接 资源校验 → git → meta.json → send_file）。

触发顺序（与 Design Skill 协同时）

Design Skill 路由 → 场景 skill（portfolio / deck / prototype 等）
→ 【写文件前】按本 Skill 顶部「路径硬规则」先建 我的项目/{项目名}/
→ 产出 .html / .jsx / .tsx / .vue → 文件【直接写入】我的项目/{项目名}/（不是事后移动）
→ quality-gate.md 通过
→ 本 Skill（资源校验 → git → meta.json → send_file）

禁止经 Design Skill 的产出在 quality gate 未通过时 commit 或 send_file。 禁止 Design Skill 在未经本 Skill 完成的情况下，将 HTML 网页项目视为已交付（仅贴代码块、不落盘、不写 我的项目/ 均不算交付）。

Design Skill 负责 / 本 Skill 负责

commit 摘要建议

git commit -m 与 meta.json 的 summary 可带上场景，便于用户识别，例如：

• V2: 首页 hero 改版（portfolio）
• V3: 基于 V1：换国际主义风格（landing-page）

读取入口

Design 侧的衔接说明见：SKILL.md § Version Management Handoff。落盘、git、meta.json、send_file 等机制以本 Skill 为准（design 仅移交、不重复定义）。

0.1 预览现状（已知限制，维持线上）

Agent 须知： 上述限制不影响版本提交与 send_file 吐出；勿因预览失败而改为内联全部资源或强行单文件化。

1. 项目创建

1.1 判断规则

产出物包含以下类型的前端文件：.html、.jsx、.tsx、.vue → 必须创建/更新项目并走版本流程（与当时走的是哪个调用方 Skill 无关）。 产出物是 image、doc、ppt、JSON、design spec、纯文本等 → 普通文件，不创建项目。

常见误判（禁止）： 因路由到某个调用方场景就认为「只贴代码块」或「写 Desktop 即可」；凡写出入口 HTML/前端文件即按项目交付。

1.2 路径强制检查（关键规则）

所有 web_project 文件必须保存到 我的项目/{项目名}/ 下。禁止保存到 workspace root、Desktop、临时目录或仅贴代码块。

首选做法是预防而非补救：按文件顶部「⚠️ 路径硬规则」，在写出第一个文件之前就建好项目目录并直接写入。以下检查是 commit / send_file 前的最后门禁：

1. 写入前：按顶部硬规则先建目录、直接写入正确位置
2. commit / send_file 前：执行下方门禁脚本；发现散落文件 → 必须先 mv 进项目目录，重新校验通过后才能继续
3. 项目名生成规则：根据用户意图、内容主题自动生成语义化中文或英文项目名（如 北京旅游网站、企业客户管理后台）

# 提交前路径门禁（在工作区根目录执行）
cd {工作区根目录}

# (a) 项目目录内必须存在至少一个入口文件（不限定 index.html，prototype.html 等同样有效）
ls "我的项目/{项目名}/"*.html "我的项目/{项目名}/"*.jsx \
   "我的项目/{项目名}/"*.tsx "我的项目/{项目名}/"*.vue 2>/dev/null | grep -q . \
  || { echo "ERROR: 我的项目/{项目名}/ 内没有入口文件，禁止 commit / send_file"; }

# (b) 工作区根目录及其他位置不得散落入口文件
find . -maxdepth 2 -not -path "./我的项目/*" \
  \( -name '*.html' -o -name '*.jsx' -o -name '*.tsx' -o -name '*.vue' \) \
  | while read -r f; do
      echo "STRAY: $f → 必须执行 mv \"$f\" \"我的项目/{项目名}/\" 后重新校验"
    done

任一项报 ERROR / STRAY → 禁止 commit 与 send_file，先纠正路径再重跑门禁。

1.3 文件结构规则

核心原则：项目目录自包含，所有文件（代码 + 资源 + export 产物）都进 Git 追踪。

• 单文件 vs 多文件： 不强制单文件（内联 JS/CSS），也不鼓励一律多文件。根据项目复杂度自行判断：
  • 简单落地页、H5、单页展示 → 可单文件 index.html
  • 需复用样式/脚本、组件较多 → 可多文件（如 index.html + style.css + main.js）
• 用户上传落点： upload/；项目内资源唯一目录：我的项目/{项目名}/assets/
• 代码中通过相对路径引用：assets/{文件名}，禁止引用 upload/ 路径（预览时由后端将相对路径替换为 OSS 链接，Agent 无需手写 OSS 地址）
• 资源使用语义化英文命名（如 hero-banner.png），避免中文和空格
• assets/ 进入 Git 追踪——每个版本的快照包含当时的全部资源，恢复历史版本时代码和资源一起回退，确保任意历史版本可完整预览

资源的处理（upload → assets，必做）

禁止 HTML 写 assets/xxx 而磁盘无对应文件（常见裂图原因：只写了路径，未从 upload/ 复制）。

1. 在 upload/ 找源文件（消息附件路径、find upload、ls -lt upload 最近上传）
2. mkdir -p 我的项目/{项目名}/assets
3. cp upload/{源} 我的项目/{项目名}/assets/{名}——{名} 与 HTML 中 assets/{名} 完全一致（HTML 已写好则按引用名复制重命名）
4. 再写/改 HTML 引用；多张图逐步 cp
5. 提交前校验（有 MISSING 不得 commit / send_file）：

cd 我的项目/{项目名}
grep -ohE 'assets/[a-zA-Z0-9_.-]+' index.html 2>/dev/null | sort -u | while read -r ref; do
  [ -f "$ref" ] || echo "MISSING: $ref"
done

6. 无 MISSING 后按 §3 创建版本并 send_file

资源来源（三种，落盘规则相同）

共用： 凡 HTML 含 assets/ 引用，提交前必做上述校验；无文件则补落盘或改引用，禁止带 MISSING commit。 先有 HTML 无图： 可用占位文案/样式，但不要写不存在的 assets/xxx；用户传图或 Agent 补图后再写真实引用并 cp。

跨版本保留用户图片（重要）

用户已上传并引用在 assets/ 中的图片，在后续自然语言 / 评论 / 参数编辑器编辑产生新版本时：

• 用户未要求去掉该模块、未要求换图 → 必须保留原有 assets/ 文件及 HTML 中的 assets/... 引用，勿删除、勿改路径、勿要求用户重传
• 仅改样式、文案、布局等 → 只改代码文件，不动 assets/（除非用户明确要求替换资源）
• git add . 会自动将未改动的 assets/ 文件纳入新版本快照（Git 自动复用未变文件，不重复存储），无需手动处理

小样文件保留规则

若正式构建前存在小样阶段（模型先生成一个包含多个编号设计方向的 HTML 供用户选择），小样 HTML 必须移入 我的项目/{项目名}/ 下保存，命名为 style-samples.html；用户不满意要求重新出方向时，后续轮次递增命名为 style-samples-2.html、style-samples-3.html，禁止覆盖已有小样文件。所有小样文件禁止命名为 index.html 或其他入口文件名。小样通过 send_file 吐出供用户预览和选择。style-samples*.html 已在 .gitignore 中通配排除，不进 Git 版本历史、不计入项目版本号。禁止在小样文件落盘到项目目录之前删除小样源文件/源文件夹。

1.4 创建流程

首次为用户产出入口文件时（第 1–3 步必须发生在写出任何代码文件之前，见顶部「⚠️ 路径硬规则」）：

1. 根据用户意图生成项目名称
2. 回到工作区根目录；若「我的项目」不存在：mkdir -p 我的项目/
3. 创建项目目录与 assets：mkdir -p 我的项目/{项目名}/assets，然后 cd 进入，所有文件直接在此目录内写出
4. 用户图先从 upload/ cp 到 assets/，再写 HTML；禁止只写 assets/ 路径不落盘
5. Git 初始化与首次提交：

cd 我的项目/{项目名}
git init
echo -e "meta.json\nstyle-samples*.html" > .gitignore
git add .
git commit -m "V1: {一句话摘要}"
git tag v1
# ↑ 以上必须全部执行完，然后创建 meta.json，最后调用 send_file 吐出 V1

6. 创建 meta.json（结构见 §5）
7. 调用 send_file 吐出该版本（见 §3.4），title = 项目名称（如 北京旅游网站）

1.5 项目目录结构

upload/                  ← 用户上传落点（不进项目 Git）

我的项目/
└── {项目名}/
    ├── .git/
    ├── .gitignore       ← 排除 meta.json 和 style-samples*.html
    ├── meta.json        ← 版本元数据（不进 Git）
    ├── style-samples*.html ← 设计方向小样，含多个编号方向供用户选择（不进 Git，可选，可多轮）
    ├── index.html       ← 主入口（进 Git，路径因项目而异）
    ├── ...              ← 其他代码文件（进 Git）
    ├── assets/          ← 资源文件（进 Git，随版本快照一起追踪）
    └── export/          ← export 导出产物（进 Git，固定图片类项目用）

2. 多项目管理

2.1 识别当前项目

按优先级判断：

1. 用户自然语言中明确提到的项目名
2. 前端传入的当前 tab 对应项目（仅用于识别项目，不决定编辑哪个版本）
3. 本 session 中最近操作的项目
4. 均无法判断 → 扫描 我的项目/ 子目录，读各项目 meta.json，列出项目并追问

2.2 切换项目

读取目标项目 meta.json，告知用户：「已切换到项目：{项目名}，当前版本 V{n}」

2.3 非项目任务

非入口文件产出的任务不触发任何项目或版本操作。

3. 版本管理

3.1 编辑入口与版本确定

自然语言默认：编辑最新项目的最新版本。

确定项目：按 §2 优先级（用户指名 > 前端上下文 > 最近操作 > 追问）。

确定版本：

不追问。所有版本均可恢复；误编非预期版本可通过恢复回退。

评论编辑与参数编辑的处理规则

用户在预览区（包括历史版本预览）使用评论编辑或参数编辑后，前端生成 MD 指令发送给 Agent。MD 指令中包含项目名和版本号，Agent 按以下规则处理：

1. 从 MD 指令中解析项目名 → 定位 我的项目/{项目名}/
2. 从 MD 指令中解析版本号 → 得到 V{n}
3. 读取该项目 meta.json 的 latest_version，判断版本关系：
   • 指定版本 = 最新版本 → 直接在当前工作区编辑 → 按 §3.3 创建新版本
   • 指定版本 ≠ 最新版本（历史版本） → 必须按 §4.4 合并流程执行（先 git checkout v{n} -- . 恢复到指定版本，再执行编辑，最后一次性 commit 为新版本）。禁止跳过恢复步骤，无论 Agent 认为当前版本与目标版本差异多小，都必须严格恢复后再改。
4. 按锚点在项目目录内所有 HTML 文件中搜索匹配，定位目标元素并执行修改
5. 完成后按 §3.3 / §4.4 的 git 指令创建版本 + 更新 meta.json + send_file

MD 模板由前端维护。 本 Skill 不定义具体 MD 格式；只要包含项目名、版本号、锚点、修改内容即可被 Agent 解析。

3.2 创建版本的时机

3.3 创建版本的 Git 指令

修改完成后，在项目目录执行：

cd 我的项目/{项目名}
LATEST_TAG=$(git tag --sort=-v:refname | head -n 1)
NEXT_NUM=$((${LATEST_TAG#v} + 1))
NEXT_TAG="v${NEXT_NUM}"
git add .
git commit -m "V${NEXT_NUM}: {一句话摘要}"
git tag $NEXT_TAG
# ↑ 以上必须全部执行完，然后更新 meta.json，最后调用 send_file 吐出新版本

3.4 对话流输出（send_file）

每生成一个新版本，必须调用 send_file。

3.4.1 默认规则：单入口文件项目

调用示例：

{"title": "北京旅游网站", "ext": "web_project", "file_path": "/我的项目/北京旅游网站/index.html", "project_name": "北京旅游网站", "version": "V3"}

3.4.2 多入口文件项目（新增规则）

当项目包含多个独立入口 HTML 文件时（例如 index.html + light.html，或多个页面）：

1. 所有入口文件必须在同一 commit 中提交（git add . 自然包含全部）
2. send_file 策略：
   • 若只有一个主入口（其他为辅助），默认只吐主入口
   • 若调用方 Skill 有显式要求吐出多个文件（如 prototype 双文件），按调用方要求执行
   • 禁止遗漏：所有 HTML 文件都必须被 git 追踪
3. 禁止对项目目录调用 ext=directory 吐文件夹

示例（index.html 为主入口，light.html 为新增变体）：

# 同一次 commit 包含两个文件
git add index.html light.html assets/
git commit -m "V4: 新增 light 主题变体"
git tag v4

send_file 只吐主入口：

{"title": "北京旅游网站", "ext": "web_project", "file_path": "/我的项目/北京旅游网站/index.html", "project_name": "北京旅游网站", "version": "V4"}

3.4.3 Prototype 双文件交付（稳定规则）

当调用方 Skill 为 prototype.md 且该版本包含双交付文件（可交互原型 + 流程文档）时：

1. 版本纳入范围（必做） 本次版本必须同时纳入并提交两个 HTML 文件（通常为 prototype.html 与 flow.html），禁止只提交其中一个。
2. 对话流输出（必做） 对同一版本号调用 send_file 两次，分别吐出两个单文件：
   • 第一次：prototype.html
   • 第二次：flow.html
3. 卡片命名建议 在 title 中标注文件角色，便于用户区分（title 不含版本号）：
   • {项目名}-prototype
   • {项目名}-flow
4. 禁止项
   • 禁止将 prototype.html + flow.html 打包为目录一次性吐出
   • 禁止只吐其中一个文件并声称已完成 prototype 双交付

示例（同一版本 V4，连续两次）：

{"title":"企业客户管理后台-prototype","ext":"web_project","file_path":"/我的项目/企业客户管理后台/prototype.html","project_name":"企业客户管理后台","version":"V4"}
{"title":"企业客户管理后台-flow","ext":"web_project","file_path":"/我的项目/企业客户管理后台/flow.html","project_name":"企业客户管理后台","version":"V4"}

3.4.4 固定图片导出项目（小红书卡片等，新增规则）

对于 fixed-image 输出目标的场景（如小红书卡片、封面图、长图），典型流程为：

1. 先生成 HTML（设计阶段产物）→ 按常规保存到 我的项目/{项目名}/
2. 后执行 export 导出图片 → 导出产物保存到 我的项目/{项目名}/export/
3. 版本管理： HTML 和 export/ 都进 Git 追踪，同一次 commit
4. send_file 策略（必做）：
   • 第一次： 吐出 HTML 文件（ext: web_project）
   • 第二次： 吐出 export 产物
     • 若导出为单张图片：ext: 具体扩展名（如 png、jpg），file_path: /我的项目/{项目名}/export/xxx.png
     • 若导出为文件夹（多张图）：ext: directory，file_path: /我的项目/{项目名}/export/

关键规则：

• HTML 和 export 产物必须在同一个项目目录下
• 两者必须在同一个版本（commit）中
• 禁止 export 产物散落在项目目录外

示例（小红书长图项目，V2）：

# 项目目录结构
cd 我的项目/小红书旅行攻略
git add .
git commit -m "V2: 优化封面配色与排版"
git tag v2

send_file 调用（连续两次）：

{"title":"小红书旅行攻略","ext":"web_project","file_path":"/我的项目/小红书旅行攻略/index.html","project_name":"小红书旅行攻略","version":"V2"}
{"title":"小红书旅行攻略-export","ext":"directory","file_path":"/我的项目/小红书旅行攻略/export/"}

3.5 对话流卡片与「基于该版本编辑」

• 历史版本与最新版本在预览区顶部展示一致（具体 UI 由前端实现）；Agent 不区分两套预览协议
• 对话流中每个由 send_file 产生的版本卡片均带「基于该版本编辑」按钮（前端实现）
• 用户点击后，输入框预填：「基于「{项目名称}」V{n}版本进行编辑」（例：基于「北京旅游网站」V2版本进行编辑；版本号用大写 V + 数字，与 send_file.version 一致）
• Agent 收到该句式 → 按 §4 合并流程处理（文案中 V{n} 转为 TARGET_TAG=v{n}）
• 最新版与历史版卡片均展示该按钮；预览区顶栏样式一致（由前端实现，Agent 无额外动作）

说明： 不提供单独的「版本列表」能力；用户通过对话流历史卡片或自然语言指定版本即可。

4. 版本恢复

4.1 恢复范围

恢复是整个项目目录状态的恢复（代码文件 + assets/ 资源 + export/ 产物）。git checkout 还原目标版本的完整工作树，确保恢复后的版本可完整预览。

4.2 恢复入口

没有独立的前端「恢复」按钮。恢复通过以下方式触发：

4.3 标准恢复（仅恢复，不附带编辑）

恢复 = checkout + 提交新版本 + send_file，三步缺一不可。仅执行 checkout 不算恢复完成。 执行指令：

cd 我的项目/{项目名}
TARGET_TAG="v{用户指定的版本号}"
LATEST_TAG=$(git tag --sort=-v:refname | head -n 1)
NEXT_NUM=$((${LATEST_TAG#v} + 1))
NEXT_TAG="v${NEXT_NUM}"
git checkout $TARGET_TAG -- .
git add .
git commit -m "V${NEXT_NUM}: 恢复至 V{目标版本号}"
git tag $NEXT_TAG
# ↑ 以上必须全部执行完，然后更新 meta.json，最后调用 send_file 吐出新版本

恢复后状态理解： 以工作区文件（代码 + assets/ + export/）+ meta.json 为准；不依赖后端版本服务或历史对话回放。

恢复后 Agent 向用户确认：

• 当前项目名和新版本号
• 包含哪些文件/页面
• 相比恢复前的差异（如"不包含美食推荐板块，该功能在 V3 中添加"）
• 调用 send_file 吐出新版本主入口（参数同 §3.4）。

版本编号始终递增（V4 恢复到 V2 → 产生 V5）。原有版本保留。

4.4 恢复 + 编辑合并流程（只产生一个版本）

适用：用户指定基于历史版本编辑（含「基于「{项目名称}」V{n}版本进行编辑」）。

版本号规则： 无论基于哪个历史版本编辑，新版本号必须是当前最新版本 +1 的纯数字递增（如当前 V8 → 新版本 V9）。禁止使用带后缀的版本号（如 V4-light、V4-dark、V2-new 等），禁止以基准版本号为前缀命名。禁止覆盖、移动或删除已有版本的 tag——已有版本永远保留，新版本只能追加。

执行指令：

cd 我的项目/{项目名}
TARGET_TAG="v{目标版本号}"
git checkout $TARGET_TAG -- .
# ↓ 在此基础上执行用户请求的编辑（修改文件内容），不做中间 commit
LATEST_TAG=$(git tag --sort=-v:refname | head -n 1)
NEXT_NUM=$((${LATEST_TAG#v} + 1))
NEXT_TAG="v${NEXT_NUM}"
git add .
git commit -m "V${NEXT_NUM}: 基于 V{目标版本号}：{编辑内容摘要}"
git tag $NEXT_TAG
# ↑ 以上必须全部执行完，然后更新 meta.json，最后调用 send_file 吐出新版本

5. meta.json 结构

每个项目一份，记录项目整体状态。通过 .gitignore 排除，不进入版本历史。

{
  "project_name": "北京旅游网站",
  "latest_version": "v3",
  "is_published": false,
  "published_version": null,
  "domain": null,
  "versions": [
    {
      "id": "v1",
      "timestamp": "2026-05-01T14:30:00+08:00",
      "based_on": null,
      "summary": "首页 + 景点列表"
    },
    {
      "id": "v2",
      "timestamp": "2026-05-05T10:30:00+08:00",
      "based_on": null,
      "summary": "风格变更为国际主义"
    },
    {
      "id": "v3",
      "timestamp": "2026-05-06T14:30:00+08:00",
      "based_on": "v1",
      "summary": "基于 V1：重新设计页面布局"
    }
  ]
}

6. 操作速查

7. 附录：预览与路径（Agent 参考）

• 工作区内： HTML 使用 assets/xxx.png 等相对路径；多文件项目内 link / script 使用相对路径引用同目录或子目录代码文件
• 用户预览时： 后端在云机解析绝对路径并替换为 OSS 链接；Agent 不要在源码中写 OSS URL
• Git 追踪范围： 代码文件 + assets/ 资源 + export/ 产物均进 Git；meta.json 和 style-samples*.html 被 .gitignore 排除
• 已知限制： 多文件项目的 JS/CSS 预览、历史版本预览与最新不一致——见 §0.1，本期不修复