---
name: versioning-rule
description: 版本号规则（X.Y.Z 语义 + **版本号只在提交时变化** + **0.x 合法开发期、1.0 稳定线**（2026-10-02 修订，对齐 SemVer 2.0.0 §4 + Go/Cargo 官方）+ **大版本换代判定：结构不同 = 大版本+1**）——适用于本机所有 DSH 自研插件（dsh-*）与 gamebanana-mods-downloader（gbmd）三组件。涉及任何版本号更新、发版、打包、CRX 命名、新建插件、判断新旧版本/自更新时加载；约束所有 AI 所有会话一律遵守。
whenToUse: 更新任意 DSH 自研插件或 gbmd 组件的版本号、打包 CRX、写更新日志版本号、统计提交版本、新建 dsh-* 插件项目（package.json 写 version）、自更新/版本比对、判断远端是否为新版本时。
generatedBy: deepseek-official/deepseek-v4-flash + EIGHTfs 2026-08-20（补充大版本换代判定）+ 2026-08-21（确立：版本只在提交时变化）+ 2026-10-02（修订：0.x 合法开发期——调研 SemVer 2.0.0 §4、Go v0、Cargo 0.y.z 语义后重设计）
---

# 版本号规则（versioning-rule）

> **权威源 = dsh-git-push 插件项目 skills/**（版本控制 skill 归 dsh-git-push 插件权威，2026-08-21 确立）；公用目录 .dsh/skills 与 ai-work-archive 为副本。（X.Y.Z 语义 + 版本只在提交时变化 + 0.x 合法开发期/1.0 稳定线 + 大版本换代判定）

> 适用范围（2026-08-18 扩展）：**本机所有 DSH 自研插件（dsh-*）** + gamebanana-mods-downloader 三组件（浏览器扩展/Server/画廊）。
> ⚠️ **版本线（2026-10-02 修订，原「1 开头硬规则」废弃）**：**0.x 是合法开发期**（SemVer 2.0.0 §4：主版本号为零的软件处于开发初始阶段，一切都可能随时被改变）；**1.0.0 是稳定线**（正式环境使用 / 公共 API 稳定被依赖 / 开始担心向下兼容时升 1.0）。禁止把 0.x 当「不合规」强制修正——0.x 序列合法，达到稳定才升 1.0。

## 零、⭐ 核心规则：版本号只在提交时变化（2026-08-21 确立，最高优先）

> **原话**：「版本控制只在提交时变化，比如 2.0.0 哪怕开发 10 几个功能，也只是提交一次，保存 2.1.0」

- **版本号只在提交（commit）时变化**：开发过程中无论做了多少功能、改了多少代码，版本号一律不动
- **一次提交 = 一个小版本**：提交一次保存时，版本号升一个小版本（**2.0.0 → 2.1.0**）
- **功能个数不决定版本号**：哪怕开发 10 几个功能，只要只提交一次，版本号也只升一个小版本（2.1.0），**绝不按功能数逐个升**
- 一句话：**版本号指向「提交存档」而非「功能进度」**——Y = 第几次提交存档，不是第几个功能

### 落地细则

1. **开发期（未提交）**：`package.json` 等版本字段保持当前值不变，不随功能开发逐个改动
2. **提交时**：先把版本号 Y+1（Z 归 0），再提交；提交信息里的版本号与 package.json 一致
3. **一次提交内含的功能数不限**：版本号只反映提交存档次序，不反映功能数量
4. **子功能新增/修复提交**：同一提交版本存档后，新增子功能（全新或修复/更新）→ Y 不变、Z 累加（仍只在提交时变化）
5. **大版本换代**（结构不同 X+1，见第三节）仍按提交时变化执行——一次提交内可同时完成 X+1
6. **0.x 开发期同样遵守**：模块版本只在提交时变化（0.1.0 → 0.2.0 也是一次提交）

### ⭐ 项目级覆盖示例：dsh-git-push 重构版（2026-09 用户绑定，不改变通用规则）

> 适用项目 = **dsh-git-push 重构版（workspace 下重建的 v2 项目）**。此项目用户明确要求：
> **版本号只在提交时变化 + bug 修复只动第三位（1.0.x）+ 1.1.0 仅在已知 bug 全部修完时才有资格**。
> 这是对「第零节提交节奏」的本项目特例覆盖，其他 dsh-* 项目仍按通用规则（提交升 Y）。

- **bug 修复**：1.0.3 → 1.0.4（**第三位** +1，Y 不动）——每修一批 bug、通过双扫描 + 测试，提交一次
- **1.1.0（Y+1）**：**仅当「已知 bug 已全部修完」** 才允许（不是改了点东西就升 1.1.0）
- **阶段**：当前处于 1.0.x（修 bug 集），1.1.0 是「已知 bug 清零」里程碑
- **提交纪律**（本项目）：commit msg 格式 `<版本> <入口名>：做了什么`；本地 master 提交，**不推送远端**（除非用户另行授权）
- **验证门槛**（本项目每次提交前）：npm test 全绿 + 双扫描 0 blocker + README/WORKBOARD 版本行同步

### 正反例

- ✅ 2.0.0 开发了 10 几个功能，只提交一次 → 存档为 **2.1.0**（不管功能数）
- ❌ 2.0.0 每开发一个功能就升一次版本（2.0.0 → 2.1.0 → 2.2.0 → 2.3.0…）——**禁止**，版本不按功能数升
- ✅ 2.1.0 提交后修了 3 次 bug，3 次补丁提交 → 2.1.3
- ✅ 项目重构为新结构，一次提交 → 大版本 +1（如 2.1.0 → 3.0.0）

## 一、规则（X.Y.Z 语义）

- 格式：**X.Y.Z**（三个小数段）
  - **X** = 大版本（重大重构/不兼容变更才 +1；**X 从 0 起合法**——0.x 为开发初始阶段，SemVer §4；达到稳定后 X ≥ 1）
  - **Y** = 提交版本序号（**每次提交 +1**；一次提交可含任意多个功能）
  - **Z** = **新增子功能数量**（全新的子功能 + 子功能的修复及更新都计入；2026-08-21 更清晰定义）
- 版本号指向**当前最新提交的存档进度**（不是功能数/全局累计）
- **1.0.0（Y=0）默认含义**：**不含代码**的架构设计文档 + 任务清单 + README 文档（项目初始交付物，还没有任何功能代码；第一个功能提交落地才升到 1.1.0）

## 二、⭐ 版本线：0.x 合法开发期 → 1.0 稳定线（2026-10-02 修订，原「1 开头硬规则」废弃）

> 依据调研（2026-10-02，来源记录见 ai-work-archive/开发者文档/版本号设计调研-SemVer与业界实践-20261002.md）：
> - **SemVer 2.0.0 §4**：主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变；
> - **SemVer FAQ**：0.y.z 阶段以 0.1.0 起步、每次发行递增次版本号；主版本号为零就是为了做快速开发；
> - **Go 官方**：v0 = 开发中不稳定、无兼容承诺；v1+ 允许对 v0 用户做不兼容变更；
> - **Cargo**：0.y.z 中 y 变化按 major 处理、z 变化按 minor 处理、0.0.z 永远算 major。

### 落地规则

1. **0.x = 合法开发期**：新插件/项目可从 `0.1.0` 起步（开发中、API 未定型、无稳定承诺），**不强制 1 开头**
2. **0.x 阶段语义**（对齐 Cargo 压缩版）：
   - `0.Y` 递增 = **不兼容/大变更**（相当于 1.x 的 major bump）——开发期 API 随便改，bump 次版本即可
   - `0.Z` 递增 = **兼容新增**（相当于 minor）
   - `0.0.Z` 递增 = **重大变化**（0.0.x 是最早原型期，任何改动都是破坏性的）
3. **1.0.0 = 稳定线**（SemVer FAQ + Go）：达到以下任一即应升 1.0——
   - 软件被用于**正式环境**
   - 公共 API **稳定且被使用者依赖**
   - 开始**担心向下兼容**问题
4. **升 1.0 后**：X ≥ 1，完整 major/minor/patch 语义（不兼容变更 X+1、兼容新增 Y+1、修复 Z+1）
5. **0.x 不当作「不合规」**：禁止「0.x → 1.x 强制修正」（0.2.0 → 1.2.0 之类除非用户明确要求）
6. **例外场景**：内置模块（待 burn-in）0.x 起步照旧（本就在 0.x 合法范围内）；第三方依赖版本由上游决定不改

### 反面教材（2026-08-18 旧规，保留作历史）

> 旧规曾把 dsh-session-manager 0.1.0→0.10.0 序列强制修正为 1.x（0.10.0 → 1.10.0）。
> **2026-10-02 修订后此为历史教训而非现行做法**：0.x 序列本身合法，无需修正；
> 真正该做的是——项目达到稳定（正式环境/稳定 API）时**主动规划升 1.0**，而不是把 0.x 当错误强改。

### ⭐ 例外：内置模块版本从 0 开始（2026-08-19 补充，与 0.x 合法化一致）

- **内置模块** = 独立开发、最终 **burn-in 内置进正式插件**的小模块（如 dsh-workflow-audit → 并入 dsh-session-manager；开发模式见 dsh-link-bridge skill）
- 这类模块**独立阶段版本从 0 开始**：`v0.1.0` 起步（0.x = 待内置、未并入主插件）
- **内置成功后**：模块不再有独立版本，随主插件版本走（主插件 1.x）
- 适用示例：**dsh-workflow-audit v0.1.0**（2026-08-19 起）
- **版本只在提交时变化同样适用**：模块开发期版本不动，提交时 0.1.0 → 0.2.0（见第零节）

### 1.0.0 vs 0.1.0 的对应关系（2026-08-19 补充，⚠️ 必读）

- **插件主版本 `1.0.0`** = 无代码文档版：架构设计 + **模块设计思路** + 任务清单 + README（还没有任何功能代码）
- **功能模块实际写出来**（开始有代码）→ 该模块版本 = **`0.1.0`**（第一个功能，待内置）
- **每个功能模块都从 `0.1.0` 开始**（不是按模块序号排：第二个模块也是 0.1.0 起步）
- **模块内部有新功能/完善 → 提交时升 0.2**：0.1.0 → 0.2.0 → 0.3.0...（Y = 该模块的第几次提交存档，Z = 新增子功能数量；版本只在提交时变化）
- 全部内置完成后：插件升 1.1.0（首个功能落地），后续模块内置随插件版本走

## 三、⭐ 大版本换代判定（2026-08-20 确立，自更新/版本比对必读）

> **结构不同 = 大版本换代（大版本 + 1）**。这条规则用于「判断远端版本是否真的是可自动更新的新版本」。

### 核心规则

1. **结构不同（structureMismatch）＝ 本地已处于新大版本结构（旧系列大版本 + 1）**
2. 旧结构的版本号（即使数字更高，如 1.13.0）属于**旧大版本系列**，**永远不构成"可自动更新的新版本"**
3. 新旧结构切换必须**人工处理**或等待新版本（同结构）正式提交——**禁止自动用旧结构覆盖新代码**

### 判定示例（dsh-git-rescue 实测，2026-08-20）

| 本地 | 远端 | 远端结构 | 判定 | 处理 |
|------|------|----------|------|------|
| 2.0.0（新根级结构） | 1.13.0（旧 components/ 子树） | 旧 | updateAvailable=true（版本号更高是事实）但 majorUpgrade=true | **不自动更新**，人工/等新版本提交 |
| 2.0.0 | 2.0.0（根级） | 同 | updateAvailable=false | 已是最新 |
| 2.0.0 | 2.1.0（根级） | 同 | updateAvailable=true + majorUpgrade=false | 可自动更新 |

### 落地（dsh-git-rescue 自更新）

- `lib/self-update.js` 的 `checkForUpdate()`：
  - 版本来源探测：根级 `package.json` 优先，旧位置 `components/git-rescue/package.json` 回退（**如实报告远端版本号**）
  - 结构校验：远端根必须存在 `lib/index.js`（新大版本结构）→ `structureMismatch` + `majorUpgrade`
  - 返回 `{ updateAvailable, structureMismatch, majorUpgrade, detail }`
- `applyUpdate()`：遇 `structureMismatch`/`majorUpgrade` **拒绝执行**（防旧结构覆盖新代码）
- 单测：T9/T9.5/T9.6（compareVersions / allowlist 路径 / 真实远端结构判定）

### 操作指引（遇到版本比对/自更新判断时）

1. 读远端 `package.json` 版本号（根级优先，旧位置回退）——**如实报告**
2. 检查远端结构是否与本地一致（根级 `lib/` 是否存在）——**结构不同 = 大版本换代**
3. 结构相同才允许自动更新；结构不同 → 人工处理 / 等新版本提交

## 三·补、⭐ 子功能版本线（2026-08-21 确立，权威）

> 子功能（插件内 git 版本管理 / guardian / 自动更新等）独立计版本，两条规则线：

| 子功能版本 | 含义 | 递增规则 |
|-----------|------|---------|
| **0 开头**（0.x） | 目录结构不兼容（不能覆盖实现更新）| 换代/不兼容即用 0 开头；**功能缺失导致救援（插件设计目的）失败 +1** |
| **1 开头**（1.x） | 结构兼容，正常功能演进 | **新增几种功能 +几**（每新增一种子功能版本 +1） |

- **0 开头场景**：子功能结构不兼容（无法简单覆盖更新）→ 从 0 重新计；期间每补一个"功能缺失导致救援失败"的漏洞 Z+1
- **1 开头场景**：新增子功能（全新）→ 版本 +1；子功能的修复/更新也计入（Z 累加）
- 示例（dsh-git-rescue 重建实测）：git 版本管理 0.1.2（0 起步 + 2 次修复）、guardian 自动救援 0.1（0 起步 1 功能）、自动更新 1.1（1 起步新增 1 功能）

## 四、示例（已实测确认）

| 场景 | 版本 | 说明 |
|---|---|---|
| 2.2.3 | 第 2 次提交存档 | 该提交版本修了 3 次 bug |
| 2.5.1 | 第 5 次提交存档 | 该提交版本修了 1 次 bug |
| 1.4.0 | 第 4 次提交存档 | 该提交版本还没修过 bug |
| 1.0.0 | 初始版本 | 默认=不含代码：架构设计 + 任务清单 + README |
| 2.0.0 → 2.1.0 | 开发 10 几个功能、只提交一次 | 不管功能数，一次提交只升一个小版本（2026-08-21 确立） |

## 五、DSH 自研插件当前版本基线（2026-08-18 检修后均为 1.x；2026-10-02 修订：0.x 合法，此表为历史现状参考）

| 插件 | 版本 | 插件 | 版本 |
|---|---|---|---|
| dsh-session-manager | 1.10.0 | dsh-git-rescue | **2.0.0（2026-08-20 重构，旧 1.13.0 → 新大版本 2.0.0）** |
| dsh-whale-musume | 1.3.0 | dsh-bili-publisher | 1.2.0 |
| dsh-shift-router-src | 1.5.0 | dsh-session-search | 1.0.0 |
| dsh-ai-work-archive / dsh-git-push / dsh-image-preview / dsh-header-layout / dsh-model-router-v2 / dsh-session-group / dsh-task-completion / dsh-test-env-entry / dsh-test-sync-plugin | 1.0.0 | | |

## 六、落地位置

- **DSH 插件**：`package.json` 的 `version` 字段（唯一权威位置；插件加载信息、client bundle rev 均以它为准）
- gbmd 扩展：`extension/manifest.json` 的 `version`（MV3 要求 X.Y.Z 三段）
- gbmd Server：`server/package.json` + `server/app.js` 启动日志（`gbmd-server vX.Y.Z 已启动`）
- gbmd 画廊：`gallery/server.js` 头部注释（`gbmd-gallery vX.Y.Z`）
- README：更新日志标题（新功能提交必须整理 README 版本记录，见 release-docs-rule）
- CRX 打包名：`gamebanana-mods-downloader-vX.Y.Z.crx`

## 七、更新步骤（每次发版 / 改版本）

1. **确认当前版本号**（开发期版本号一律不动，见第零节）
2. **有功能/变更待提交** → 版本号升一个小版本：Y+1、Z 归 0（提交一次一个小版本，不按功能数升）
3. **数清该提交版本修了几次 bug Z**（bug 补丁提交 Y 不变、Z+1）
4. **检查版本是否达到 1.0 稳定线**——0.x 合法（开发期）；若已正式环境使用/稳定 API 被依赖，则规划升 1.0（见第二节）
5. **判断是否大版本换代**（结构是否变化）——结构变了则 X+1（见第三节）
6. 改对应文件的 version 字段（DSH 插件=package.json；gbmd=各自位置）
7. 同步 README 更新日志标题（release-docs-rule：新功能必须整理 README）
8. 部署副本同步（主实例 `~/.dsh/profiles/web/node_modules/<插件>/package.json`、测试实例 `node_modules_local`）
9. 提交（**提交即存档新版本号**；推送另按提交推送纪律）

## 八、检修清单（发现/怀疑版本号问题时）

- [ ] 扫 `package.json` version 是否 0.x（`grep '"version"' */package.json | grep '"0\.'`）——**0.x 合法（开发期）**，核对是否已达稳定线该升 1.0；不达稳定继续 0.x 即可，不做强制修正
- [ ] 已达稳定（正式环境/稳定 API）→ 升 1.0.0（同步主实例/测试实例部署副本）
- [ ] 第三方依赖（@deepseek-ai/@dsh-external）跳过
- [ ] 0.x 项目核对稳定线（正式环境/稳定 API）——达标则升 1.0；未达标保持 0.x（合法开发期）
- [ ] 结构是否变化（自更新是否会被旧结构版本误导）——结构不同 = 大版本换代
- [ ] **版本号是否只在提交时变化**——开发期乱升版本号（按功能数逐个升）要修正为提交时一次性升

## 九、注意

- **版本只在提交时变化（2026-08-21 确立）**：开发多少功能都不升版本，提交一次升一个小版本（2.0.0 → 2.1.0）；功能个数不决定版本号
- 功能"加→改→移除→恢复"算 **1 个功能**；移除+恢复合计算 1 次改动（功能计数只在整理 README 时用，不决定版本号）
- 合并类提交（如"gameIdFixes 合并"）算独立功能还是子步骤，按功能主题判断（只影响 README 描述，不影响版本号规则）
- 无法确定时，读 git log 按提交主题归类，或问用户
- 看到 **1.0.0** 一律按「无代码文档版」处理（架构设计+任务清单+README），不要误以为有功能；有代码的第一个功能提交落地从 1.1.0 起
- **看到旧结构高版本号（如 1.13.0）不要误判为可自动更新的新版本**——结构不同 = 大版本换代（第三节）

## 相关

