Files

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

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

2026-03-02 12:51:41 +08:00

9.4 KiB

Raw Blame History

Project Caffeine项目版本命名规则指南

1. 项目代号深度解析：为什么是 "Project Caffeine"？

本科研助手智能体系统旨在解决海量信息检索、深度推理与结构化报告生成的痛点。我们将项目正式定名为 Project Caffeine（萃取者计划），因为咖啡的精细萃取过程，完美隐喻了本系统在编写科研报告时，大语言模型执行一步步深度推理与提纯的完整工作流。

具体而言，咖啡萃取与科研推理存在以下高度的相似之处：

生豆采摘与筛选对应 “全网数据抓取”：面对互联网上杂乱无章的海量原始数据（生豆），我们的“文献查询 MCP Server”就像经验丰富的采摘者，自动连接 arXiv、PubMed 等外部 API 获取生豆，并过滤掉无效的视觉杂音。
精细研磨对应 “语义分块 (Semantic Chunking)”：咖啡豆必须经过精确刻度的研磨才能释放风味。面对导致 Token 超载的超长篇 PDF 论文，系统在本地完成文本解析与“向量切割（语义分块）”，将长文本研磨成大模型能够完美吸收的知识颗粒。
高压萃取对应 “CoT 多步链式推理”：意式咖啡机的高压水流穿过咖啡粉饼的瞬间，即是核心风味物质被提取的过程。这等同于系统的“CoT 推理 MCP Server”强制大模型加载经典思维框架（如 SCQA、SWOT 分析、思维链）。模型在极高的数据密度下进行交叉比对、事实冲突验证与逻辑推演，一步步滤去幻觉与水分。
最终成杯对应 “结构化科研报告”：正如经过滤纸或把手滴落的纯净咖啡液，系统最终“萃取”出的是极具学术深度的研究洞察，并将其沉淀为带有 YAML 元数据的高质量 Markdown 文件，无缝接入用户的本地知识管理图谱（PKM）。

此外，MCP 协议本身被定义为解决“N×M 整合难题”的标准接口（犹如科技界的 USB-C 接口）。在我们的项目命名中，MCP 协议就是那个标准化的咖啡机手柄（Portafilter），它以统一的规格兼容了各种不同的外部数据（咖啡豆）与宿主模型（咖啡机）。

2. 版本号命名规范：A-Z 咖啡图谱

为了让系统的演进路径清晰且充满极客浪漫主义，系统的版本号（Release Version）将严格采用以英文字母 A 到 Z 顺序开头的、与咖啡相关的英文单词进行命名。每一个代号都将映射该版本核心突破的技术特征。

以下是规划中的 A-Z 核心版本迭代序列：

v1.x (A): Arabica (阿拉比卡 - 基础高品质咖啡树种)
v2.x (B): Bourbon (波旁 - 阿拉比卡经典优质变种)
v3.x (C): Cortado (可塔朵 - 浓缩与牛奶等比例混合的平衡咖啡)
v4.x (D): Drip (滴滤/手冲 - 依靠重力慢速萃取的方式)
v5.x (E): Espresso (意式浓缩 - 高压快速萃取的咖啡精华)
v6.x (F): Flat White (馥芮白/平白 - 奶泡更薄的浓缩奶咖)
v7.x (G): Geisha (瑰夏 - 具有极其复杂花果香的顶级咖啡品种)
v8.x (H): Honey Process (蜜处理 - 保留果胶层进行干燥的处理法)
v9.x (I): Ibrik (土耳其咖啡壶 - 最古老的不过滤煮沸法器具)
v10.x (J): Java (爪哇 - 印尼著名产区，也常作为咖啡的代名词)
v11.x (K): Kona (科纳 - 夏威夷顶级咖啡产区)
v12.x (L): Liberica (赖比瑞卡 - 世界第三大原生咖啡树种，风味独特)
v13.x (M): Macchiato (玛奇朵 - 意为“印记”，仅加少许奶泡的浓缩)
v14.x (N): Nitro (氮气冷萃咖啡 - 注入氮气带来绵密气泡口感的冷萃)
v15.x (O): Obata (奥巴塔 - 抗病虫害的优良阿拉比卡杂交品种)
v16.x (P): Peaberry (圆豆 - 单粒果实变异，风味更集中)
v17.x (Q): Q-Grader (咖啡品鉴师 - 国际认证的咖啡质量分级专家)
v18.x (R): Robusta (罗布斯塔 - 醇度厚重、抗虫害能力强的原生树种)
v19.x (S): Syphon (虹吸壶 - 利用水蒸气压力原理的冲煮器具)
v20.x (T): Typica (铁皮卡 - 最古老、最经典的阿拉比卡原生变种)
v21.x (U): Unwashed (日晒处理/非水洗 - 保留完整果实晒干的最古老处理法)
v22.x (V): V60 (V60滤杯 - 具有60度锥角的经典手冲器具)
v23.x (W): Washed (水洗处理 - 去除果肉与果胶后洗净风干的处理法)
v24.x (X): Xalapa (哈拉帕 - 墨西哥知名高海拔精品咖啡产区)
v25.x (Y): Yirgacheffe (耶加雪菲 - 以明亮柑橘花香闻名的埃塞俄比亚产区)
v26.x (Z): Zambia (赞比亚 - 极具潜力的非洲高海拔精品咖啡产地)

3. 分支与工程配置规范

为了将该命名规则严格落实到开发环节，团队需遵循以下工程配置标准：

环境变量注入：在工程的 package.json 及系统级 .env 文件中，需显式声明代号。
Git 分支管理：所有的 Release 发布分支需携带字母代号后缀，例如：release/v1.0-arabica, release/v2.1-bourbon。
架构图注规范：根据《图形即代码设计规范指南》，所有的系统架构 SVG 拓扑图中，右上角及面包屑导航的注释必须带有当前版本的咖啡代号，例如 Release: v1.0.0 (Arabica)。

这是一个非常必要的补充！在工程化实践中，虽然“A-Z咖啡代号”赋予了项目极客的浪漫主义色彩，但在底层的代码包管理（如 package.json）、Git 标签（Tag）以及依赖追踪中，计算机只认识严谨的数字。

我们需要将极客代号与业界标准的 语义化版本控制 (Semantic Versioning, SemVer) 完美缝合。

我为您拟定了一个全新的小节，建议将其作为 “3. 项目代码版本号 (SemVer) 规范” 插入到原文档中（原有的“3. 分支与工程配置规范”顺延为第 4 节）。您可以直接复制以下内容：

3. 项目代码版本号 (SemVer) 规范

本项目代码的基础版本号严格遵循 "语义化版本控制规范"，基本格式为 主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)。为了将工程实践与我们的项目文化结合，这三个维度的数字将与 A-Z 咖啡代号以及敏捷开发 (Agile) 的 Sprint 周期深度绑定：

主版本号 (MAJOR)：与 A-Z 咖啡图谱的大代号严格对应。
- 触发条件：当系统架构发生重大重构、API 发生不兼容变更，或核心业务理念发生代际升级时递增。
- 命名映射：v1.x.x 阶段的所有代码统称为 Arabica，当主版本号升级至 v2.x.x 时，代号整体更替为 Bourbon，以此类推。
次版本号 (MINOR)：与敏捷开发中的 Sprint（迭代冲刺周期） 强绑定。
- 触发条件：在一个主代号周期内，向下兼容地新增了核心功能或完成了新的 Sprint 目标。
- 命名映射：
  - Arabica Sprint 1 交付版本的基线为 v1.0.0。
  - Arabica Sprint 2 交付版本的基线为 v1.1.0。
修订号 (PATCH)：对应日常的缺陷修复与微调。
- 触发条件：进行了向下兼容的 Bug 修复、安全补丁更新或细微的性能优化（不包含新功能）。
- 命名映射：在 Sprint 1 (v1.0.0) 发布后，如果修复了一个路径防穿越的安全漏洞，版本号应升级为 v1.0.1。
预发布与环境后缀 (Prerelease Tags)：
- 在正式的 Release 发布之前，处于开发或测试阶段的代码，必须在版本号后通过连字符 - 追加状态标识。
- 示例：
  - v1.0.0-alpha.1（Sprint 1 的内部开发测试版）
  - v1.1.0-rc.1（Sprint 2 的 Release Candidate 发布候选版）

代码配置示例 (package.json)：

{
  "name": "@project-caffeine/mcp-server",
  "version": "1.0.0",
  "description": "Project Caffeine Arabica (Sprint 1) Release",
  "engines": {
    "node": ">=20.0.0"
  }
}

4. 分支与工程配置规范