docs(update):更新Project Caffeine 项目命名和版本号规范指南文档

Signed-off-by: gzkoala <guohao@gitconomy.org>

docs/guide/project-caffeine-version-name-convetion-guide.md

@@ -1,19 +1,22 @@
 <!--
 ---
-title: "Project Caffeine项目命名规则指南"
-description: "详细阐述 Project Caffeine（萃取者计划）的核心命名隐喻、A-Z 咖啡图谱版本号规范及其在 Git 与工程化中的配置标准"
-type: "Guide"
-file: "project-caffeine-version-name-convention-guide.md"
-version: "v1.0.0 (Arabica)"
-author: "Gitconomy Research-郭晧"
+title: Project Caffeine项目命名规则指南
+description: 详细阐述 Project Caffeine（萃取者计划）的核心命名隐喻、A-Z 咖啡图谱版本号规范及其在 Git 与工程化中的配置标准
+type: Guide
+file: project-caffeine-nanming-convention-guide.md
+version: v1.0.1
+author: Gitconomy Research-郭晧
 date: 2026-02-28
+last-update: 2026-03-02
+update-description: 增建代码版本号的规则说明
 tags:
   - Project Caffeine
   - Name Convention
-  - A-Z版本迭代
+  - Version Controll
+  - Revision Rules
   - Project Management
-license: "CC BY-SA 4.0"
-status: "Active"
+license: CC BY-SA 4.0
+status: Active
 ---
 -->
 # Project Caffeine项目版本命名规则指南
@@ -83,6 +86,71 @@ status: "Active"
 
 ---
 
+这是一个非常必要的补充！在工程化实践中，虽然“A-Z咖啡代号”赋予了项目极客的浪漫主义色彩，但在底层的代码包管理（如 `package.json`）、Git 标签（Tag）以及依赖追踪中，计算机只认识严谨的数字。
+
+我们需要将极客代号与业界标准的 **语义化版本控制 (Semantic Versioning, SemVer)** 完美缝合。
+
+我为您拟定了一个全新的小节，建议将其作为 **“3. 项目代码版本号 (SemVer) 规范”** 插入到原文档中（原有的“3. 分支与工程配置规范”顺延为第 4 节）。您可以直接复制以下内容：
+
+---
+
+## 3. 项目代码版本号 (SemVer) 规范
+
+本项目代码的基础版本号严格遵循 "语义化版本控制规范"，基本格式为 `主版本号.次版本号.修订号` (`MAJOR.MINOR.PATCH`)。为了将工程实践与我们的项目文化结合，这三个维度的数字将与 A-Z 咖啡代号以及敏捷开发 (Agile) 的 Sprint 周期深度绑定：
+
+1. **主版本号 (MAJOR)**：与 A-Z 咖啡图谱的大代号严格对应。
+
+    - **触发条件**：当系统架构发生重大重构、API 发生不兼容变更，或核心业务理念发生代际升级时递增。
+    - **命名映射**：`v1.x.x` 阶段的所有代码统称为 **Arabica**，当主版本号升级至 `v2.x.x` 时，代号整体更替为 **Bourbon**，以此类推。
+
+2. **次版本号 (MINOR)**：与敏捷开发中的 **Sprint（迭代冲刺周期）** 强绑定。
+
+    - **触发条件**：在一个主代号周期内，向下兼容地新增了核心功能或完成了新的 Sprint 目标。
+
+    - **命名映射**：
+
+        - Arabica Sprint 1 交付版本的基线为 `v1.0.0`。
+        - Arabica Sprint 2 交付版本的基线为 `v1.1.0`。
+
+3. **修订号 (PATCH)**：对应日常的缺陷修复与微调。
+
+    - **触发条件**：进行了向下兼容的 Bug 修复、安全补丁更新或细微的性能优化（不包含新功能）。
+    - **命名映射**：在 Sprint 1 (`v1.0.0`) 发布后，如果修复了一个路径防穿越的安全漏洞，版本号应升级为 `v1.0.1`。
+
+4. **预发布与环境后缀 (Prerelease Tags)**：
+
+    - 在正式的 Release 发布之前，处于开发或测试阶段的代码，必须在版本号后通过连字符 `-` 追加状态标识。
+
+    - **示例**：
+
+        - `v1.0.0-alpha.1`（Sprint 1 的内部开发测试版）
+        - `v1.1.0-rc.1`（Sprint 2 的 Release Candidate 发布候选版）
+
+
+**代码配置示例 (`package.json`)：**
+
+``` json
+{
+  "name": "@project-caffeine/mcp-server",
+  "version": "1.0.0",
+  "description": "Project Caffeine Arabica (Sprint 1) Release",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+```
+---
+
+## 4. 分支与工程配置规范
+
+为了将该命名规则严格落实到开发环节，团队需遵循以下工程配置标准：
+
+1. **环境变量注入**：在工程的 `package.json` 及系统级 `.env` 文件中，需显式声明代号。
+2. **Git 分支管理**：所有的 Release 发布分支需携带字母代号后缀，例如：`release/v1.0-arabica`, `release/v2.1-bourbon`。
+3. **架构图注规范**：根据《图形即代码设计规范指南》，所有的系统架构 SVG 拓扑图中，右上角及面包屑导航的注释必须带有当前版本的咖啡代号，例如 `Release: v1.0.0 (Arabica)`。
+
+---
+
 ## 许可声明
 
 本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026  Gitconomy Research.