forked from new_org/Project-Caffeine
170 lines
7.3 KiB
Markdown
170 lines
7.3 KiB
Markdown
<!--
|
||
---
|
||
title: "Project Caffeine 代码编写规范指南"
|
||
description: "为 Project Caffeine 项目开发人员提供一致的编码风格、系统架构指引和最佳实践的规范文档"
|
||
type: "Guide"
|
||
version: "v1.0.0"
|
||
file: project-caffeine-coding-specification-guide.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:
|
||
* - 郭晧 <guohao@gitconomy.org> (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.
|