From b553eea1830349e665ac5d569ddc92d69f1c15f0 Mon Sep 17 00:00:00 2001 From: gzkoala Date: Mon, 2 Mar 2026 11:24:00 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(add):=E6=96=B0=E5=A2=9EProject=20Caffe?= =?UTF-8?q?ine=E4=BB=A3=E7=A0=81=E7=BC=96=E5=86=99=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: gzkoala --- ...caffeine-coding-specification-guidelnes.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 docs/guide/project-caffeine-coding-specification-guidelnes.md diff --git a/docs/guide/project-caffeine-coding-specification-guidelnes.md b/docs/guide/project-caffeine-coding-specification-guidelnes.md new file mode 100644 index 0000000..8bcdb24 --- /dev/null +++ b/docs/guide/project-caffeine-coding-specification-guidelnes.md @@ -0,0 +1,167 @@ +--- +title: "Project Caffeine 代码编写规范指南" +description: "为 Project Caffeine 项目开发人员提供一致的编码风格、系统架构指引和最佳实践的规范文档" +type: "Guide" +version: "v0.1.0" +file: project-caffeine-coding-specification-guidelines.md +author: "Gitconomy Research-郭晧" +date: 2026-03-02 +tags: + - Project Caffeine + - 代码规范 + - TypeScript + - MCP + - Node.js +license: "CC BY-SA 4.0" +status: "Active" +--- +# Project Caffeine 代码编写指南 +## 1. 目的与概述 + +本代码编写规范旨在为 **Project Caffeine** 项目的开发人员提供一致的编码风格和最佳实践，确保代码的可读性、可维护性和团队协作的效率。遵循这些规范将有助于提升代码质量、减少错误并优化开发过程。 + +--- + +## 2. 技术栈与工程化基础 + +所有代码必须遵循清晰、简洁、结构化的原则，并基于以下核心技术栈构建： + +- **核心语言**：所有核心功能必须使用 TypeScript 编写。强烈建议优先使用 TypeScript，以利用其静态类型检查减少运行时错误。 +- **运行环境**：服务端必须使用 Node.js (LTS v20+)。需确保高效的异步执行和非阻塞 I/O 操作。 +- **工程架构**：采用原生 npm Workspaces 进行 Monorepo（单体仓库）包管理。必须在根目录统一管控共享的 JSON-RPC Schema 与多个微服务子包。 + +--- + +## 3. 代码风格与命名规则 + +## 3.1 格式与排版 + +- **缩进**：使用 **2 个空格**作为缩进（严禁使用 Tab）。 +- **行长度**：每行代码的字符数应不超过 **120 个字符**，避免横向滚动条，便于阅读和维护。 +- **文件结尾**：每个文件的结尾必须保留一个空行。 +- **函数复杂度**：长函数或复杂逻辑必须拆分为多个函数，确保每个函数的职责单一。 + +## 3.2 命名规范 + +- **变量与函数**：使用 `camelCase`（小驼峰命名法），如 `userProfile`, `generateReport`。 +- **类与接口**：使用 `PascalCase`（大驼峰命名法），如 `UserService`, `ReportGenerator`。 +- **常量**：使用 `UPPER_SNAKE_CASE`（全大写蛇形命名法），如 `MAX_RETRIES`, `API_TIMEOUT`。 +- **文件与目录**：使用 `kebab-case`（短横线命名法），如 `user-service.ts`, `data-fetcher.ts`。 + +--- + +## 4. 注释与文档 + +每个模块、类和复杂函数必须包含文件头部文档或块级注释，简要说明其作用。必须使用标准的 **JSDoc** 格式来解释功能、参数和返回值： + +```TypeScript +/** + * 计算两个数的和。 + * @param {number} a - 第一个加数。 + * @param {number} b - 第二个加数。 + * @returns {number} - 返回两数之和。 + */ +function add(a: number, b: number): number { + return a + b; +} +``` +--- + +## 5. 开源许可证声明 + +**所有源代码文件的顶部必须包含开源相关的版权信息与 SPDX 格式的许可证标识。** 本项目源代码统一采用 **MIT 许可证**。在每个 `.ts` 或者 `。js` 文件头部必须添加如下块级注释： + +```plaintext +/** + * Project Caffeine + * Copyright (c) 2025-2026 Gitconomy Research + * + * SPDX-License-Identifier: MIT + */ +``` +为了保障代码的可追溯性并尊重每一位开发者的劳动成果，当新的团队成员或开源社区开发者对该文件进行了**实质性修改或重构**时，应当在头部的 `Contributors` 列表中追加自己的信息。 + +在每个 `.ts` 或 `.js` 文件头部，必须添加如下块级注释模板： + + +```plaintext +/** + * Project Caffeine + * Copyright (c) 2025-2026 Gitconomy Research + * + * SPDX-License-Identifier: MIT + * + * Contributors: + * - 郭晧 (Initial Author) + * - [新贡献者姓名/ID] <[联系邮箱]> ([简述贡献内容，例如：重构了 LRU 缓存模块 / 2026-03]) + * - [其他贡献者姓名] <[联系邮箱]> ([例如：修复了 MCP 握手超时的 Bug / 2026-04]) + */ +``` + +--- + +## 6. 目录结构与模块化解耦 + +系统应保持高度的模块化，功能模块应独立且彼此解耦。建议采用以下标准目录结构： + +- `/src/controllers`：控制器，处理传入的 JSON-RPC 或 HTTP 请求。 +- `/src/services`：服务层，包含核心的 MCP 业务逻辑。 +- `/src/models`：数据模型与 Schema 定义。 +- `/src/routes`：路由定义（适用于 HTTP+SSE 传输模式）。 +- `/src/utils`：跨模块共享的工具函数。 +- `/config`：环境与系统配置文件。 +- `/tests`：单元测试与集成测试文件。 + +--- + +## 7. MCP 协议与核心原语 + +系统全面采用 JSON 格式作为基础数据承载体，并依赖 **JSON-RPC 2.0** 协议规范来管理消息交换。 + +- **传输层**：本地服务必须采用 STDIO 协议进行无网络开销的直接通信。云端部署则采用 HTTP + SSE 模式。 +- **Tools (工具)**：暴露给 LLM 的操作必须通过 `tools/list` 注册，并包含严谨的 `inputSchema`。 +- **Resources (资源)**：被动的静态上下文数据需通过 `resources/list` 和 `resources/read` 暴露。 +- **Prompts (提示词)**：作为复用模板，通过 `prompts/list` 暴露，指导模型构造标准化交互结构。 + +--- + +## 8. 异常处理与日志记录 + +## 7.1 错误捕获与响应 + +- 在业务逻辑中，必须使用 `try-catch` 语句来捕获和处理可能的错误。 +- 对于 HTTP/SSE 传输层，遇到预期错误需返回适当的 HTTP 状态码（如 400 错误请求、404 未找到资源）。对于不可预见的严重异常，返回 500 错误。 +- 在 MCP 协议层，所有错误必须被标准封装为 JSON-RPC 错误对象，并返回给客户端。 + +## 7.2 日志系统 + +- 必须使用成熟的日志库（如 `winston` 或 `log4js`）来记录事件。 +- 明确日志级别：`info`（正常操作流程）、`warn`（潜在问题）、`error`（系统异常）。 +- 记录重要事件（如用户操作、API 调用），以便追踪、审计和发现模型幻觉。 +- **安全红线**：绝对禁止在生产环境日志中记录敏感信息（如用户密码、API 密钥、未脱敏的凭证）。 + +--- + +## 8. 性能优化与上下文管理 + +- **异步编程**：必须使用 `async/await` 或 `Promise` 处理网络与文件 I/O，确保不阻塞 Node.js 事件循环。 +- **语义分块**：对于长篇文档的读取，服务端必须在本地完成文本解析与切割，仅将高度相关的片段同步给客户端，防止 LLM Token 耗尽。 +- **缓存与数据库**：对于频繁查询的数据，采用 LRU（最近最少使用）缓存策略或引入外部缓存（如 Redis）以减少负载。同时需使用合适的索引、查询优化和分页技术，避免数据库性能瓶颈。 + + +--- + +## 9. 安全性与权限管控 + +协议必须遵循“零信任架构原则”，将 AI 生成的指令视为不可信负载。 + +- **数据加密**：敏感信息必须加密存储，使用 `bcrypt` 或 `argon2` 进行密码哈希处理。 +- **认证与授权**：系统通信应使用 JWT 或 OAuth 2.0/2.1 进行认证，并采用作用域限定防止令牌滥用。 +- **Roots 隔离**：必须实现 Roots（根目录）机制，服务端依据宿主应用传递的 URI 列表划定沙箱，阻断越权访问和路径遍历漏洞。 +- 定期进行安全审计，确保代码没有易受攻击的注入漏洞。 + +--- + +## 许可声明 + +本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research. From e65288fde2bc64b961227a1ef7652130c7079483 Mon Sep 17 00:00:00 2001 From: gzkoala Date: Mon, 2 Mar 2026 12:51:41 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(update):=E6=9B=B4=E6=96=B0Project=20Ca?= =?UTF-8?q?ffeine=20=E9=A1=B9=E7=9B=AE=E5=91=BD=E5=90=8D=E5=92=8C=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=8F=B7=E8=A7=84=E8=8C=83=E6=8C=87=E5=8D=97=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: gzkoala --- ...t-caffeine-version-name-convetion-guide.md | 86 +++++++++++++++++-- 1 file changed, 77 insertions(+), 9 deletions(-) diff --git a/docs/guide/project-caffeine-version-name-convetion-guide.md b/docs/guide/project-caffeine-version-name-convetion-guide.md index 02da7ea..31bf717 100644 --- a/docs/guide/project-caffeine-version-name-convetion-guide.md +++ b/docs/guide/project-caffeine-version-name-convetion-guide.md @@ -1,19 +1,22 @@ # 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. From 3683a6e05993ffa8ad4948b08a70b5e4f218a68f Mon Sep 17 00:00:00 2001 From: gzkoala Date: Mon, 2 Mar 2026 12:53:34 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(update):=E6=9B=B4=E6=96=B0Project=20Ca?= =?UTF-8?q?ffeine=20=E9=A1=B9=E7=9B=AE=E4=BB=A3=E7=A0=81=E7=BC=96=E5=86=99?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: gzkoala --- docs/guide/project-caffeine-coding-specification-guidelnes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guide/project-caffeine-coding-specification-guidelnes.md b/docs/guide/project-caffeine-coding-specification-guidelnes.md index 8bcdb24..6aef4e4 100644 --- a/docs/guide/project-caffeine-coding-specification-guidelnes.md +++ b/docs/guide/project-caffeine-coding-specification-guidelnes.md @@ -1,3 +1,4 @@ + # Project Caffeine 代码编写指南 ## 1. 目的与概述