forked from ceshi_org/Project-Caffeine
docs(update):更新Porject Caffeine系统开发指南文档
Signed-off-by: gzkoala <guohao@gitconomy.org>
This commit is contained in:
parent
634b54f8f6
commit
7b664bb836
|
|
@ -1,12 +1,14 @@
|
|||
<!--
|
||||
---
|
||||
title: "Project Caffeine系统开发指南"
|
||||
type: "Development Guide"
|
||||
file: "project-caffeine-development-framewok-guide.md"
|
||||
description: "个人级研报智能体系统架构与开发规范指南"
|
||||
version: "v0.1.0 (Arabica)"
|
||||
author: "Gitconomy Research-郭晧"
|
||||
title: Project Caffeine系统开发指南
|
||||
description: 个人级研报智能体系统架构与开发规范指南
|
||||
type: Development Guide
|
||||
file: project-caffeine-development-framewok-guide.md
|
||||
version: v1.1.0 (Arabica)
|
||||
author: Gitconomy Research-郭晧
|
||||
date: 2026-02-28
|
||||
last-update: 2026-03-08
|
||||
update-description: 更新系统架构、工具链以及其他相关的设计说明
|
||||
tags:
|
||||
- Project Caffeine
|
||||
- MCP
|
||||
|
|
@ -14,8 +16,8 @@ tags:
|
|||
- 系统架构
|
||||
- PKM
|
||||
- 知识管理
|
||||
license: "CC BY-SA 4.0"
|
||||
status: "Active"
|
||||
license: CC BY-SA 4.0
|
||||
status: Active
|
||||
---
|
||||
-->
|
||||
# Project Caffeine系统开发指南
|
||||
|
|
@ -52,142 +54,38 @@ MCP与传统的应用程序编程接口（API）以及消息队列等技术在
|
|||
|
||||
|
||||
|
||||
MCP的系统总体架构采用严格分层的客户端-服务端（Client-Server）模型，旨在实现传输机制与数据处理逻辑的彻底解耦。该架构由三大核心组件构成：
|
||||
### 3.1 系统分层架构设计
|
||||
|
||||
1. **宿主应用程序（Host Application）**：直接与用户交互并承载大语言模型的环境（如Claude Desktop、Cursor IDE等）。
|
||||
系统由四个核心物理与逻辑区域组成，通过标准协议进行通信：
|
||||
|
||||
2. **MCP客户端（MCP Client）**：无缝嵌入在宿主应用程序中，负责维持与外部服务端的连接，执行能力协商，并将宿主的意图翻译为符合MCP规范的协议消息。
|
||||
- **控制器层**：`promptsController`、`toolsController`、`resourcesController` 接收 MCP 请求，进行参数校验（Zod），调用对应的服务模块，并格式化响应。保持薄控制器原则，业务逻辑全部下沉到服务层。
|
||||
- **服务层**：按功能拆分为 `literature`、`prompt`、`cot`、`resource` 四个子目录，每个子目录下包含该功能相关的多个服务文件。服务之间可通过导入直接调用，例如 `promptService` 可以调用 `intentService` 生成检索词，再调用 `literatureService` 执行检索。
|
||||
- **模型层**：集中存放 TypeScript 类型定义和 Zod Schema，包括文献格式、框架定义、工具参数等，确保类型安全并在整个项目内共享。
|
||||
- **工具层**：提供跨模块复用的工具函数，如 HTTP 客户端、YAML 生成、路径安全校验、日志等。
|
||||
|
||||
3. **MCP服务端（MCP Server）**：轻量级的外部程序，专门负责连接特定的数据源或执行特定的计算任务，通过标准接口向AI应用暴露上下文和工具。
|
||||
### 3.2 MCP 三大核心原语分工
|
||||
|
||||
系统框架严格遵循 MCP 规范，将功能划分为 Tools、Prompts 和 Resources 三大部分：
|
||||
|
||||
**数据流管理**：用户发起请求 $\rightarrow$ AI模型推理决定调用外部能力 $\rightarrow$ MCP客户端打包 JSON-RPC 请求 $\rightarrow$ MCP服务端执行逻辑并返回标准 JSON 结构 $\rightarrow$ 客户端将上下文注入模型 $\rightarrow$ 模型生成最终响应。
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据标准化
|
||||
|
||||
系统全面采用 JSON 格式作为基础数据承载体，并依赖 **JSON-RPC 2.0** 协议规范来管理消息交换。MCP规范设定了三种核心的系统原语：
|
||||
|
||||
- **工具（Tools）**：允许AI应用执行具体操作（如文件读写、API调用）。服务端通过 `tools/list` 暴露工具元数据，包含严谨的 `inputSchema`。
|
||||
|
||||
- **资源（Resources）**：提供被动上下文信息的数据源。通过 `resources/list` 发现，通过 `resources/read` 提取内容。
|
||||
|
||||
- **提示词（Prompts）**：作为可复用的模板，帮助模型构造标准化的交互结构。通过 `prompts/list` 和 `prompts/get` 进行流转。
|
||||
|
||||
|
||||
为保证数据兼容性，系统需对通用 JSON 进行深度扩展（如类似 JSON-LD 或结构化 BibTeX 的标准），确保输入模式和生成数据结构在底层LLM切换时保持绝对一致性。
|
||||
|
||||
---
|
||||
|
||||
## 5. 模型定义与行为规范
|
||||
|
||||
在复杂的智能体架构中，模型的行为必须遵循预设的结构与功能规范。
|
||||
|
||||
- **结构与功能定义**：系统通常通过“提示词策略服务端”注入静态思维框架（如SWOT分析、思维链CoT推理），强制模型按照标准逻辑结构进行逐步推理。可加入学术质量控制逻辑（如强制引文密度验证）。
|
||||
|
||||
- **采样（Sampling）机制**：MCP引入的反向调用机制。允许服务端主动请求LLM的推理能力来指导后续操作（如调用 `sampling/createMessage`）。任何涉及采样的递归行为都必须受到严格管控，并在应用层确保人在回路的二次确认机制。
|
||||
|
||||
---
|
||||
|
||||
## 6. 通信协议设计
|
||||
|
||||
根据系统应用场景的不同，通信协议的选择主要集中在两种官方支持的标准之上：
|
||||
|
||||
|**传输协议**|**运行机制**|**安全性与效率特征**|**适用场景**|
|
||||
|**原语名称**|**核心职责 (Core Responsibility)**|**典型工具与指令示例**|**所属 Server 角色**|
|
||||
|---|---|---|---|
|
||||
|**STDIO**|利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信。|零网络传输开销，不经过网卡，提供最优延迟和效率。无需复杂加密握手。|本地集成的桌面应用程序（如Claude Desktop, Cursor）及容器内部的Sidecar服务。|
|
||||
|**HTTP + SSE**|客户端通过 HTTP POST 发送请求，服务端通过 Server-Sent Events 流式下发响应。|依赖 HTTPS/TLS 保障安全，支持标准 Token 认证。效率依赖网络带宽与延迟优化。|云端部署的远程MCP服务端、微服务架构及跨物理机器访问的连接器。|
|
||||
|**Tools (工具)**|**动作执行者**：暴露给模型的主动操作，负责与外部学术 API 通信或执行本地文件 I/O。|`search_academic_literature`, `save_to_local_vault`|**S1: 执行者 (Executor)**|
|
||||
|**Prompts (提示词)**|**策略军师**：提供结构化的思维框架模板，用于指导大模型进行意图拆解与深度推理。|`5W3H`, `SCQA`, `5 Whys`, `generate_search_queries`|**S2: 军师 (Strategist)**|
|
||||
|**Resources (资源)**|**数据管家**：被动的静态上下文数据源，允许模型以只读方式挂载本地知识库内容。|`vault://local_literature/`, `note://local/`|**S1/S3: 数据管家/分析师**|
|
||||
|
||||
所有通信均封装在 JSON-RPC 2.0 信封内，通过初始化握手（`initialize`）进行双向的能力协商，并支持动态状态更新（如 `notifications/tools/list_changed`）。
|
||||
### 3.3原语协同逻辑要点
|
||||
|
||||
拓扑图展示了系统内部的协同工作流：
|
||||
|
||||
1. **动态策略驱动**：当用户输入模糊主题时，系统首先调用 **Prompts 原语** 中的 `generate_search_queries` 将意图降维并转化为专业检索词。
|
||||
2. **物理链路执行**：大模型根据拆解后的 Query，通过 **Tools 原语** 调用外部 API（如 arXiv）并执行“双轨制落盘”，将 JSON 数据转化为带有 YAML 元数据的 Markdown 文件。
|
||||
3. **知识闭环构建**：在递归深挖阶段，模型通过 **Resources 原语** 回读已保存在本地知识库中的文献卡片，确保后续的推理基于已获知的“先验知识（Learnings）”。
|
||||
|
||||
---
|
||||
|
||||
## 7. 上下文管理机制
|
||||
## 4. 系统工作流
|
||||
|
||||
构建科学的上下文管理机制是MCP系统设计的核心要务，以应对大模型的上下文窗口限制。
|
||||
|
||||
- **生命周期管理**：连接瞬间注入环境配置；多轮调用中动态更新；任务完成时显式终止销毁，防止内存泄漏。
|
||||
|
||||
- **LRU 缓存策略**：对于高频读写的中间结果，采用最近最少使用缓存策略。结合**哈希映射**（保证查找时间复杂度为 $\mathcal{O}(1)$）和**双向链表**（管理生命周期与数据逐出）。
|
||||
|
||||
- **语义分块（Semantic Chunking）**：对于长篇文档，服务端在本地完成文本解析与向量切割，仅将统计学上高度相关的片段异步同步给客户端，避免 Token 极度消耗。
|
||||
|
||||
---
|
||||
|
||||
## 8. 安全性和权限管理
|
||||
|
||||
协议遵循**零信任架构原则**，默认将AI生成的指令视为不可信负载。
|
||||
|
||||
- **加密与验证**：远程连接强制 HTTPS/TLS 1.2+。官方推荐基于 **OAuth 2.1** 的授权流，并采用如 `mcp:read_database` 形式的作用域限定防止令牌滥用。
|
||||
|
||||
- **Roots（根目录）机制**：从系统底层阻断越权访问和路径遍历漏洞。由宿主应用在初始化时传递明确的 URI 列表划定“活动沙箱”。服务端目录访问控制系统会依据 Roots 边界直接拒绝越权请求。
|
||||
|
||||
---
|
||||
|
||||
## 9. 性能优化和可扩展性
|
||||
|
||||
- **处理效率**：MCP服务端必须引入全面的异步处理模型（如 asyncio 或 Node.js 非阻塞事件流），结合代理层 LRU 缓存拦截重复请求。
|
||||
|
||||
- **网络传输**：利用 MCP JSON-RPC 协议中原生的数组分片流式返回能力，将长文本数据切片持续推送，降低首字节时间（TTFB）。
|
||||
|
||||
- **架构扩展**：引入负载均衡与水平扩展技术。云端部署可采用 Docker + Kubernetes (HPA)。针对海量异构数据，应部署独立域的多个无状态MCP服务端并结合聚合网关进行调度。
|
||||
|
||||
---
|
||||
|
||||
## 10. 系统维护和更新
|
||||
|
||||
- **版本控制策略**：当服务端发生破坏性更新时，应当在 `tools/list` 响应中并行提供新旧两套 Schema，直至宿主模型的 Prompt 被完全升级。
|
||||
|
||||
- **热部署（Hot Deployment）**：协议原生支持热更新。服务端逻辑变动时可发送 `list_changed` 通知，客户端会在后台透明重新拉取最新状态。
|
||||
|
||||
- **容错和恢复**：建立异常捕获与重试机制。利用本地轻量级数据库（如SQLite）作为事务日志，在崩溃恢复后回放状态。
|
||||
|
||||
---
|
||||
|
||||
## 11. 系统部署与运维
|
||||
|
||||
- **部署方式**：Docker 容器是封装事实标准。可结合标准化 AI 伪制品清单格式（如 `ara.json`）实现公有云自动化编排与部署。
|
||||
|
||||
- **可观测性**：部署 Prometheus + Grafana 进行系统指标监控。引入专门针对大模型和 MCP 工具监控的分析平台（如 Agnost AI）深度剖析调用频次与失败率。
|
||||
|
||||
- **日志管理**：使用 ELK 协议栈收集 JSON-RPC 往来报文，用于追踪错误栈、发现模型幻觉及优化提示词。
|
||||
|
||||
---
|
||||
|
||||
## 12. 开发工具链和环境配置
|
||||
|
||||
*图：1-2：Project Caffeine开发框架与技术栈架构图*
|
||||
|
||||
|
||||
|
||||
为确保系统的高并发处理能力与协议严谨性，Project Caffeine 采用以下核心开发框架与技术标准：
|
||||
|
||||
* **核心语言与运行环境**：采用 TypeScript 与 Node.js (LTS v20+)。MCP服务端必须引入全面的异步处理模型（如 Node.js 非阻塞事件流）以应对高吞吐量的数据解析。
|
||||
* **MCP 协议与 SDK**：统一使用官方针对 TypeScript 提供的标准 SDK，深度封装底层 JSON-RPC 2.0 报文解析与状态机管理。
|
||||
* **工程化与 Monorepo**：采用原生 npm Workspaces 进行包管理，在根目录统一管控共享的 JSON-RPC Schema 与多个微服务子包，实现依赖隔离与跨服务快速编译。
|
||||
* **通信传输层 (MVP 阶段)**：采用 STDIO 协议，利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信，无需复杂加密握手，实现零网络传输开销。
|
||||
* **集成开发环境 (IDE)**：采用 Visual Studio Code (VS Code) 作为核心开发工具。需配合安装相关的 MCP 扩展插件，支持在编写代码时直接进行对话联调与协议协议测试。
|
||||
* **安全与环境管控**：协议遵循零信任架构原则，默认将AI生成的指令视为不可信负载。敏感凭证严禁硬编码，必须通过 `.env.example` 模板化并在运行环境中安全注入。
|
||||
|
||||
---
|
||||
|
||||
## 13. 测试与调试
|
||||
|
||||
绝不能仅停留在“感觉测试（Vibe-Testing）”层面，必须实施严密的自动化分级测试体系：
|
||||
|
||||
|**测试层级**|**测试框架与工具推荐**|**核心目标与执行策略**|
|
||||
|---|---|---|
|
||||
|**单元测试**|Mocha, Chai, PyTest, Jest|脱离LLM环境，确保模块独立功能绝对正确（覆盖率>80%），验证是否能正确拒绝非法输入。|
|
||||
|**集成测试**|MCP Inspector, mcpjam|测试协议合规性。模拟握手与协商，通过浏览器 UI 手动验证或自动化集成交互测试。|
|
||||
|**性能测试**|k6 Load Testing|评估高并发请求下的生存能力，验证 P99 响应时间及内存泄漏监控。|
|
||||
|**安全与调试**|Chrome DevTools, OWASP|实施 SQL/命令注入及路径遍历安全审计。提供内存检查与日志调试功能定位异常。|
|
||||
|
||||
---
|
||||
|
||||
## 14. 系统工作流
|
||||
|
||||
*图1-3：Project Caffeine MCP 系统工作流逻辑示意图*
|
||||
*图1-2：Project Caffeine MCP 系统工作流逻辑示意图*
|
||||
|
||||
|
||||
|
||||
|
|
@ -240,17 +138,230 @@ MCP的系统总体架构采用严格分层的客户端-服务端（Client-Server
|
|||
- 对提示词或任务描述的优化建议。
|
||||
系统会根据反馈调整模型的推理过程或检索策略，以改进后续任务的处理效果。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 15. 文档与支持
|
||||
## 5. 开发工具链和环境配置
|
||||
|
||||
优秀的MCP系统配备多维度文档：
|
||||
### 5.1 技术栈与工程化基础
|
||||
|
||||
- **开发者文档**：架构图、API契约、安装配置指南及常见问题解答（FAQ）。
|
||||
*图：1-3：Project Caffeine开发框架与技术栈架构图*
|
||||
|
||||
- **AI 模型文档**：`tools/list` 响应中的 `description` 字段必须经过精细的提示词工程打磨，消除歧义。利用 `prompts/list` 暴露预置最佳实践，提供少样本（Few-shot）学习参考。
|
||||
|
||||
|
||||
| 层次 | 技术选型 |
|
||||
| ------------ | ---------------------------------------------------------- |
|
||||
| **核心语言** | TypeScript（所有核心功能强制使用） |
|
||||
| **运行环境** | Node.js LTS v20+（异步非阻塞 I/O） |
|
||||
| **协议层** | MCP SDK（`@modelcontextprotocol/sdk`），支持 `stdio` 与 `SSE` 传输 |
|
||||
| **包管理** | npm（单体仓库，单一 `package.json`） |
|
||||
| **校验工具** | Zod（运行时类型校验与参数验证） |
|
||||
| **HTTP 客户端** | axios（封装学术 API 调用，支持重试与速率限制） |
|
||||
| **日志工具** | winston / log4js（生产级日志记录） |
|
||||
| **测试工具** | Jest + k6（单元测试与负载压测） |
|
||||
| **调试工具** | VS Code 断点调试（通过 `--inspect` 挂载） |
|
||||
### 5.2 模块划分与代码组织
|
||||
|
||||
```
|
||||
project-caffeine/
|
||||
├── src/
|
||||
│ ├── controllers/ # 请求控制器
|
||||
│ │ ├── promptsController.ts # 处理 prompts/list, prompts/get
|
||||
│ │ ├── toolsController.ts # 处理 tools/list, tools/call
|
||||
│ │ └── resourcesController.ts # 处理 resources/list, resources/read
|
||||
│ ├── services/ # 核心业务逻辑（按功能模块划分）
|
||||
│ │ ├── literature/ # 文献查询模块（原 S1）
|
||||
│ │ │ ├── literatureService.ts # 学术 API 调用、聚合
|
||||
│ │ │ ├── storageService.ts # 文献转 Markdown、文件写入
|
||||
│ │ │ └── index.ts
|
||||
│ │ ├── prompt/ # 提示词策略模块（原 S2）
|
||||
│ │ │ ├── promptService.ts # 框架加载、消息组装
|
||||
│ │ │ ├── intentService.ts # 意图拆解、检索词生成
|
||||
│ │ │ └── index.ts
|
||||
│ │ ├── cot/ # CoT 推理模块（原 S3，规划中）
|
||||
│ │ │ ├── synthesisService.ts # 文献合成、报告生成
|
||||
│ │ │ ├── qualityService.ts # 引用校验、时效检查
|
||||
│ │ │ └── index.ts
|
||||
│ │ └── resource/ # 本地资源管理（通用）
|
||||
│ │ └── resourceService.ts # 笔记列表、读取、保存
|
||||
│ ├── models/ # 数据模型与 Zod 校验
|
||||
│ │ ├── schemas.ts # 统一校验 Schema
|
||||
│ │ ├── literatureSchema.ts # 文献 JSON 定义
|
||||
│ │ └── frameworks/ # 思维框架 JSON 定义
|
||||
│ │ ├── 5w3h.json
|
||||
│ │ ├── scqa.json
|
||||
│ │ └── ...
|
||||
│ ├── utils/ # 通用工具函数
|
||||
│ │ ├── apiClients.ts # HTTP 客户端封装
|
||||
│ │ ├── yamlHelper.ts # YAML Frontmatter 生成
|
||||
│ │ ├── pathSafety.ts # 路径安全校验
|
||||
│ │ └── logger.ts # 日志工具
|
||||
│ └── app.ts # 入口文件：初始化 MCP Server，注册原语
|
||||
├── config/
|
||||
│ └── config.ts # 环境配置加载
|
||||
├── .env.example # 环境变量示例
|
||||
├── package.json # 项目依赖
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 系统设计补充
|
||||
### 6.1 数据标准化
|
||||
|
||||
系统全面采用 JSON 格式作为基础数据承载体，并依赖 **JSON-RPC 2.0** 协议规范来管理消息交换。MCP规范设定了三种核心的系统原语：
|
||||
|
||||
- **工具（Tools）**：允许AI应用执行具体操作（如文件读写、API调用）。服务端通过 `tools/list` 暴露工具元数据，包含严谨的 `inputSchema`。
|
||||
|
||||
- **资源（Resources）**：提供被动上下文信息的数据源。通过 `resources/list` 发现，通过 `resources/read` 提取内容。
|
||||
|
||||
- **提示词（Prompts）**：作为可复用的模板，帮助模型构造标准化的交互结构。通过 `prompts/list` 和 `prompts/get` 进行流转。
|
||||
|
||||
|
||||
为保证数据兼容性，系统需对通用 JSON 进行深度扩展（如类似 JSON-LD 或结构化 BibTeX 的标准），确保输入模式和生成数据结构在底层LLM切换时保持绝对一致性。
|
||||
|
||||
### 6.2 通信协议设计
|
||||
|
||||
根据系统应用场景的不同，通信协议的选择主要集中在两种官方支持的标准之上：
|
||||
|
||||
|**传输协议**|**运行机制**|**安全性与效率特征**|**适用场景**|
|
||||
|---|---|---|---|
|
||||
|**STDIO**|利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信。|零网络传输开销，不经过网卡，提供最优延迟和效率。无需复杂加密握手。|本地集成的桌面应用程序（如Claude Desktop, Cursor）及容器内部的Sidecar服务。|
|
||||
|**HTTP + SSE**|客户端通过 HTTP POST 发送请求，服务端通过 Server-Sent Events 流式下发响应。|依赖 HTTPS/TLS 保障安全，支持标准 Token 认证。效率依赖网络带宽与延迟优化。|云端部署的远程MCP服务端、微服务架构及跨物理机器访问的连接器。|
|
||||
|
||||
所有通信均封装在 JSON-RPC 2.0 信封内，通过初始化握手（`initialize`）进行双向的能力协商，并支持动态状态更新（如 `notifications/tools/list_changed`）。
|
||||
|
||||
### 6.3 上下文管理机制
|
||||
|
||||
构建科学的上下文管理机制是MCP系统设计的核心要务，以应对大模型的上下文窗口限制。
|
||||
|
||||
- **生命周期管理**：连接瞬间注入环境配置；多轮调用中动态更新；任务完成时显式终止销毁，防止内存泄漏。
|
||||
|
||||
- **LRU 缓存策略**：对于高频读写的中间结果，采用最近最少使用缓存策略。结合**哈希映射**（保证查找时间复杂度为 $\mathcal{O}(1)$）和**双向链表**（管理生命周期与数据逐出）。
|
||||
|
||||
- **语义分块（Semantic Chunking）**：对于长篇文档，服务端在本地完成文本解析与向量切割，仅将统计学上高度相关的片段异步同步给客户端，避免 Token 极度消耗。
|
||||
|
||||
### 6.4 安全性和权限管理
|
||||
|
||||
协议遵循**零信任架构原则**，默认将AI生成的指令视为不可信负载。
|
||||
|
||||
- **加密与验证**：远程连接强制 HTTPS/TLS 1.2+。官方推荐基于 **OAuth 2.1** 的授权流，并采用如 `mcp:read_database` 形式的作用域限定防止令牌滥用。
|
||||
|
||||
- **Roots（根目录）机制**：从系统底层阻断越权访问和路径遍历漏洞。由宿主应用在初始化时传递明确的 URI 列表划定“活动沙箱”。服务端目录访问控制系统会依据 Roots 边界直接拒绝越权请求。
|
||||
|
||||
### 6.5性能优化和可扩展性
|
||||
|
||||
- **处理效率**：MCP服务端必须引入全面的异步处理模型（如 asyncio 或 Node.js 非阻塞事件流），结合代理层 LRU 缓存拦截重复请求。
|
||||
|
||||
- **网络传输**：利用 MCP JSON-RPC 协议中原生的数组分片流式返回能力，将长文本数据切片持续推送，降低首字节时间（TTFB）。
|
||||
|
||||
- **架构扩展**：引入负载均衡与水平扩展技术。云端部署可采用 Docker + Kubernetes (HPA)。针对海量异构数据，应部署独立域的多个无状态MCP服务端并结合聚合网关进行调度。
|
||||
|
||||
### 6.6 系统维护和更新
|
||||
|
||||
- **版本控制策略**：当服务端发生破坏性更新时，应当在 `tools/list` 响应中并行提供新旧两套 Schema，直至宿主模型的 Prompt 被完全升级。
|
||||
|
||||
- **热部署（Hot Deployment）**：协议原生支持热更新。服务端逻辑变动时可发送 `list_changed` 通知，客户端会在后台透明重新拉取最新状态。
|
||||
|
||||
- **容错和恢复**：建立异常捕获与重试机制。利用本地轻量级数据库（如SQLite）作为事务日志，在崩溃恢复后回放状态。
|
||||
|
||||
### 6.7 系统部署与运维
|
||||
|
||||
- **部署方式**：Docker 容器是封装事实标准。可结合标准化 AI 伪制品清单格式（如 `ara.json`）实现公有云自动化编排与部署。
|
||||
|
||||
- **可观测性**：部署 Prometheus + Grafana 进行系统指标监控。引入专门针对大模型和 MCP 工具监控的分析平台（如 Agnost AI）深度剖析调用频次与失败率。
|
||||
|
||||
- **日志管理**：使用 ELK 协议栈收集 JSON-RPC 往来报文，用于追踪错误栈、发现模型幻觉及优化提示词。
|
||||
|
||||
---
|
||||
|
||||
## 7. 调试与测试
|
||||
|
||||
### 7.1 调试配置
|
||||
|
||||
单体架构下调试更加简便：
|
||||
- 在 VS Code 中配置 `launch.json`，直接启动 `src/app.ts`，并附加 `--inspect` 参数，即可实现源码级断点。
|
||||
- 由于所有代码在一个进程中，可以统一设置断点，无需跨服务追踪。
|
||||
- 调试日志统一输出到 `stderr`（通过 `console.error` 或日志库），避免干扰 MCP 的 `stdout` 通信。
|
||||
|
||||
### 7.2 测试策略
|
||||
|
||||
| **测试层级** | **测试框架与工具推荐** | **核心目标与执行策略** |
|
||||
| --------- | ------------------------- | -------------------------------------------- |
|
||||
| **单元测试** | Mocha, Chai, PyTest, Jest | 脱离LLM环境，确保模块独立功能绝对正确（覆盖率>80%），验证是否能正确拒绝非法输入。 |
|
||||
| **集成测试** | MCP Inspector, mcpjam | 测试协议合规性。模拟握手与协商，通过浏览器 UI 手动验证或自动化集成交互测试。 |
|
||||
| **性能测试** | k6 Load Testing | 评估高并发请求下的生存能力，验证 P99 响应时间及内存泄漏监控。 |
|
||||
| **安全与调试** | Chrome DevTools, OWASP | 实施 SQL/命令注入及路径遍历安全审计。提供内存检查与日志调试功能定位异常。 |
|
||||
|
||||
_详见[Project Caffeine 项目代码测试规范指南](./../guides/project-caffeine-code-testing-specification-guide.md)_
|
||||
|
||||
---
|
||||
|
||||
## 8. 部署与运行
|
||||
|
||||
### 8.1 本地部署
|
||||
|
||||
```bash
|
||||
git clone <repository>
|
||||
cd project-caffeine
|
||||
npm install
|
||||
cp .env.example .env # 编辑配置文件，填入 API 密钥和本地知识库路径
|
||||
npm run build # 编译 TypeScript
|
||||
```
|
||||
|
||||
在支持 MCP 的客户端（如 Cherry Studio）中导入以下json配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"Project Caffeine": {
|
||||
"isActive": true,
|
||||
"name": "Project Caffeine",
|
||||
"type": "stdio",
|
||||
"description": "",
|
||||
"baseUrl": "",
|
||||
"command": "node",
|
||||
"args": [
|
||||
"--inspect=9229",
|
||||
"/home/wguo/Downloads/Project-Caffeine/projects/arabica/sprint2/dist/app.js"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
_`app.ts`文件需要根据每版本输入完整的绝对路径_
|
||||
|
||||
### 8.2 远程部署（SSE 模式）
|
||||
|
||||
若需部署为远程服务，可在 `app.ts` 中增加对 `SSE` 传输的支持，通过环境变量切换传输方式。部署时需配置反向代理（如 Nginx）和负载均衡，并确保安全认证（如 JWT）。
|
||||
|
||||
---
|
||||
|
||||
## 9. 编码规范与文档规范
|
||||
|
||||
### 9.1 编码规范
|
||||
|
||||
- **命名**：变量/函数使用 `camelCase`，类/接口使用 `PascalCase`，常量使用 `UPPER_SNAKE_CASE`，文件/目录使用 `kebab-case`。
|
||||
- **缩进**：2 个空格，禁止 Tab。
|
||||
- **注释**：所有模块、类、复杂函数必须使用 JSDoc 注释。
|
||||
- **类型**：优先使用 TypeScript 严格模式，所有 API 输入输出均需 Zod 校验。
|
||||
- **错误处理**：服务层抛出具体错误，控制器捕获后返回标准 MCP 错误响应（包含 `isError: true`）。
|
||||
- **安全**：文件操作必须进行路径遍历校验（使用 `path.resolve` + 检查前缀，或 `path.relative` 验证）。
|
||||
|
||||
_详见 [Project Caffeine 代码编写规范指南](./../guides/project-caffeine-coding-specification-guide.md)_
|
||||
|
||||
### 9.2 文档规范
|
||||
|
||||
- **YAML Frontmatter**：所有 Markdown 文档顶部必须包含元数据（标题、描述、版本、作者、日期、标签、许可证）。
|
||||
- **文档类型**：README、设计文档、开发指南、用户指南、API 文档、更新日志等分类存放于 `docs/` 目录。
|
||||
- **图表**：核心架构图必须使用可 diff 的 SVG（嵌入 Markdown），并添加纯白背景防止深色模式反色。
|
||||
- **写作风格**：中立客观，避免翻译腔，使用主动语态，段落首句为中心句。
|
||||
|
||||
_详见[Project Caffeine文档编写规范指南](./../guides/project-caffeine-documentation-specification-guide.md)_
|
||||
|
||||
- **社区支持**：建立 Git 仓库、论坛及 Wiki，共享复杂实现方案并组织可用性培训。
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
title: "Project Caffeine 代码编写规范指南"
|
||||
description: "为 Project Caffeine 项目开发人员提供一致的编码风格、系统架构指引和最佳实践的规范文档"
|
||||
type: "Guide"
|
||||
version: "v0.1.0"
|
||||
file: project-caffeine-coding-specification-guidelines.md
|
||||
version: "v1.0.0"
|
||||
file: project-caffeine-coding-specification-guide.md
|
||||
author: "Gitconomy Research-郭晧"
|
||||
date: 2026-03-02
|
||||
tags:
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
# Project Caffeine 文档编写规范指南
|
||||
|
||||
## 1. 目的与概述
|
||||
|
||||
本文档编写规范旨在为 **Project Caffeine** 项目的全体成员提供统一的文档撰写标准。通过标准化的元数据管理、文档结构梳理、Markdown 排版、技术写作规范以及版本控制，确保所有输出的工程文档、架构设计与迭代规划具备高度的可读性、一致性与可追溯性。
|
||||
|
||||
## 2. 文档头部元数据规范 (YAML Frontmatter)
|
||||
|
||||
结合本项目的工程化管理要求，**所有 Markdown 文档的最顶部必须包含标准化的 YAML Frontmatter 元数据块**，以便于文档站点的解析、版本检索与资产归档。
|
||||
|
||||
必须包含以下核心字段：
|
||||
|
||||
- **`title`**：文档的正式标题。
|
||||
- **`description`**：用 1-2 句话高度概括文档的核心主旨与意图。
|
||||
- **`type`**：文档的类型界定（如 `README`, `System Development Guide`, `Roadmap` 等）。
|
||||
- **`version`**：严格遵循“版本号 + 咖啡代号 + 里程碑”格式（例如 `v1.0.0 (Arabica) - MVP` 或 `Sprint 1`）。
|
||||
- **file**：文件名
|
||||
- **`author`**：统一署名为 **Gitconomy Research**。
|
||||
- **`date`**：遵循 `YYYY-MM-DD` 的 ISO 标准格式。
|
||||
- **`tags`**：提取核心技术栈与概念标签（如 `Project Caffeine`, `MCP`, `Deep Research` 等）。
|
||||
- **`license`**：声明为 `CC BY-SA 4.0`。
|
||||
- **`status`**：（可选）标注文档的生命周期状态（如 `Active`, `Design and Planning` 等）。
|
||||
|
||||
## 3. 文档类型与结构建议
|
||||
|
||||
为了确保各类工程文档的逻辑完整性与结构一致性，项目内的核心文档应当遵循以下分类及标准结构框架进行编写：
|
||||
|
||||
### 3.1 文档类型与用途
|
||||
|
||||
项目文档按用途分为以下几类，主要存放于仓库的 `docs/` 目录下：
|
||||
|
||||
|类型|说明|示例路径|
|
||||
|:--|:--|:--|
|
||||
|**README**|项目总体介绍、快速开始、核心特性、状态徽章等。每个主要模块/子包应有自己的 README。|`/README.md` `/packages/server/README.md`|
|
||||
|**设计文档**|记录架构决策、模块设计、协议交互、数据流等，用于指导开发和评审。|`/docs/design/`|
|
||||
|**开发指南**|面向开发者的环境搭建、编码规范、测试指南、调试技巧等。|`/docs/development/`|
|
||||
|**用户指南**|面向最终用户的使用说明、配置示例、FAQ 等。|`/docs/user/`|
|
||||
|**API 文档**|MCP 服务暴露的 tools（工具）、prompts（提示词）、resources（资源）的详细说明，包括 JSON-RPC 参数、返回值、示例。|`/docs/api/`|
|
||||
|**贡献指南**|如何提交 Issue、PR，代码规范，文档规范，行为准则等。|`/CONTRIBUTING.md`|
|
||||
|**更新日志**|记录版本变更，遵循 Keep a Changelog 格式。|`/CHANGELOG.md`|
|
||||
|
||||
> **注意**：每个文档顶部必须包含标准化的 YAML front matter（详见第 2 节），以便机器读取元数据。
|
||||
|
||||
### 3.2 README 主文档
|
||||
|
||||
README 是项目或子包的门面，必须清晰传达项目的核心定位与接入方式，包含以下标准模块：
|
||||
|
||||
- **项目标题与徽章**：显示构建状态、协议、核心技术栈及目标版本。
|
||||
- **项目概述**：简述项目功能、核心价值与适用场景。
|
||||
- **系统架构**：放置核心的架构图或拓扑图，概述系统组件及其职责。
|
||||
- **技术栈与开发环境**：
|
||||
- 核心语言与运行环境（要求使用 TypeScript 与 Node.js LTS v20+）。
|
||||
- 依赖管理（明确标明是否采用 Monorepo / 原生 npm Workspaces）。
|
||||
- 协议与 SDK 说明（如 MCP 协议与 JSON-RPC 2.0 标准规范）。
|
||||
- 安全与环境要求（如配置隔离与“零信任架构原则”）。
|
||||
- **开发路线图**：按 MVP 或 Sprint 分阶段展示任务、目标及关键功能（如 Arabica Sprint 1 阶段特性）。
|
||||
- **参与方式**：Issue 提交规范、PR 流程以及讨论参与指引。
|
||||
- **AI 生成内容声明**：明确提示用户系统生成的报告需人工核验，仅供参考。
|
||||
- **许可证说明**：明确采用双轨制许可，即源代码通常采用 **MIT License**，而文档与研究成果采用 **CC BY-SA 4.0** 协议。
|
||||
|
||||
### 3.3 设计文档
|
||||
|
||||
用于详细阐述某一具体微服务或核心逻辑（如提示词策略 Server、资源读取模块），必须包含：
|
||||
|
||||
- **文档标题与版本信息**。
|
||||
- **模块概述**：说明该模块的具体功能、作用及与其他系统组件的交互关系。
|
||||
- **系统架构图/流程图**：直观展示数据与控制流向。
|
||||
- **接口定义与通信协议**：如 stdio 或 HTTP+SSE 的传输层约定。
|
||||
- **数据结构与格式**：如基于 **JSON-RPC 2.0** 的 schema 定义与验证规则。
|
||||
- **核心算法或逻辑描述**：如针对长文本的语义分块（Semantic Chunking）策略或缓存机制。
|
||||
- **配置示例与部署说明**：指引如何修改环境路径与启动系统。
|
||||
- **注意事项与最佳实践**：如代码防范越权访问、性能优化红线等。
|
||||
|
||||
### 3.4 图表与示意图
|
||||
|
||||
文档中的视觉资产需遵循以下存放与引用规范：
|
||||
|
||||
- **格式要求**：首选使用原生 **SVG** 代码，在特定场景下可使用高分辨率 **PNG**。若采用 SVG，必须支持通过 Git 进行 diff 比对。
|
||||
- **命名与文件夹组织**：图表文件必须存放在规定的资源目录中，遵循 `docs/assets/images/<模块名称>-<内容>.svg` 或对应的后缀格式。
|
||||
- _示例_：`docs/assets/images/project-caffeine-system-topology.svg`。
|
||||
- **图文对应**：所有图表下方必须配备简短的说明（Caption），确保图表与其解释的上下文内容紧密对应。
|
||||
|
||||
## 4. 结构与格式
|
||||
|
||||
我们使用标准的 Markdown 进行编写。
|
||||
|
||||
### 4.1 文件命名
|
||||
|
||||
文档文件命名推荐使用清晰的中文标题或英文 **kebab-case（短横线命名法）**，如 `project-caffeine-readme.md`，以保持与工程代码文件目录的命名风格统一。
|
||||
|
||||
### 4.2 章节标题的结构
|
||||
|
||||
- 使用 ATX 风格的标题（`#`）。
|
||||
- 文档主标题使用 H1（`#`），章节标题从 H2（`##`）开始。
|
||||
- 标题应简洁明了，采用**句首大写 (Sentence case)**，除非是专有名词。
|
||||
|
||||
### 4.3 章节标题的语法规范
|
||||
|
||||
#### H1: 主标题——副标题
|
||||
|
||||
1. **结构**：**主标题 + 副标题**
|
||||
2. **要求**：主标题是文章或章节的核心主题，副标题进一步解释或细化主标题，提供更多上下文或具体内容。主副标题之间可以使用破折号连接。
|
||||
|
||||
#### H2: 定语 + 助词 + 名词
|
||||
|
||||
1. **结构**：**定语 + 助词 + 名词**
|
||||
2. **要求**：H2标题通常作为章节标题，简洁地描述章节的核心内容。使用定语修饰名词，使标题具有具体性和引导性，助词（如“的”）连接定语与名词。
|
||||
|
||||
#### H3和H4: 谓语 + 宾语
|
||||
|
||||
1. **结构**：**谓语 + 宾语**
|
||||
2. **要求**：H3和H4标题通常用于小节或细节部分，强调动作（谓语）和受动者（宾语）。这种结构使得标题更加具体，直接描述某个操作、过程或事件。
|
||||
|
||||
### 4.4 列表 (Lists)
|
||||
|
||||
- **无序列表**：使用减号 `-`。列表项如果是一句完整的话，以句号结尾；如果是短语，则不需要。
|
||||
- **有序列表**：仅在步骤有严格顺序时使用数字列表。
|
||||
|
||||
### 4.5 表格
|
||||
|
||||
- 使用标准Markdown表格语法。
|
||||
- 表格前后留一空行。
|
||||
- 表头与内容之间必须有分隔行。
|
||||
- 尽量保持列对齐以提高可读性。
|
||||
|
||||
### 4.6 链接与图片
|
||||
|
||||
- 使用相对路径引用仓库内图片。
|
||||
- 外部链接应提供完整URL，包括https://前缀。
|
||||
- 提供清晰的alt 文本，兼顾无障碍与 LLM 理解。
|
||||
|
||||
### 4.7 强调
|
||||
|
||||
- **粗体 (`text`)**：用于强调关键概念、新的术语定义或需要用户特别注意的UI元素。**不要滥用**，满篇粗体等于没有重点。
|
||||
- _斜体 (`*text*`)_：用于书籍、文章标题，或表示语气的强调。
|
||||
- `行内代码 (Inline Code)`：用于正文中的命令、文件名、分支名、路径或配置项。
|
||||
|
||||
## 5. 技术写作规范
|
||||
|
||||
这是体现专业性的核心区域。
|
||||
|
||||
### 5.1 代码块 (Code Blocks)
|
||||
|
||||
所有代码块必须指定语言标记，以便正确高亮。
|
||||
|
||||
- **命令行操作**：使用 `bash` 或 `sh`。
|
||||
- 命令的输出结果**不**带 `$` 符号。
|
||||
- 需要用户替换的部分使用尖括号 `<placeholder>` 包裹。
|
||||
- **配置文件**：使用 `gitconfig`、`yaml`、`json` 等对应格式。
|
||||
- **文件内容示例**：如果只是展示文本内容，可以使用 `text`。
|
||||
|
||||
### 5.2 标点符号
|
||||
|
||||
- 使用全角中文标点符号（，。！？：；“”‘’（））。
|
||||
- 中英文混排时，英文与中文之间应保留一个空格（此项通常由排版引擎自动处理，但在 Markdown 源码中手动添加可以提高可读性）。
|
||||
|
||||
## 6. 文字风格规范指南
|
||||
|
||||
### 6.1 文字的情绪化与中立性
|
||||
|
||||
在编写文档时，我们应避免使用情绪化或带有政治色彩的语言。这不仅是为了确保技术的客观性，也是为了尊重读者的多元背景和文化视角。以下是一些具体的规范：
|
||||
|
||||
1. **避免带有攻击性或情绪化的语言**：我们的目标是帮助读者理解技术，而非通过情绪化的语言来引导思维。避免过于夸张、激烈的表述。
|
||||
2. **避免政治性语言和隐含的偏见**：在技术文档中，避免任何可能引发争议的政治色彩和社会偏见。
|
||||
3. **避免过于主观或过度的情感表达**：文档应该以冷静、客观的语气提供信息，而不是通过情感化的语言来影响读者的判断。
|
||||
4. **简洁明了，避免冗长和情绪化的描述**：避免描述性语言过于冗长或情感化的调调。尽量做到简洁直接，保持专业性。
|
||||
|
||||
### 6.2 专业性和清晰度
|
||||
|
||||
1. **保持语气的中立性**：所有表达应当中立、平衡，避免偏袒或倾向某一方的语气。专业的写作风格是直接、简洁和清晰的，不带有个人情绪色彩。
|
||||
2. **使用简洁明了的句式**：使用清晰的句式，避免过于复杂的结构。尽量使每个句子都传达一个清晰的想法，避免无谓的修饰和修辞手法。
|
||||
|
||||
### 6.3 拒绝“翻译腔”
|
||||
|
||||
这是我们文字风格的第一大敌。我们在编写或翻译内容时，必须符合中文的自然表达习惯。
|
||||
|
||||
1. **减少“被”字句**：英文习惯用被动语态，而中文习惯用主动语态。
|
||||
2. **警惕“的”字风暴**：过多的“的”字会让句子变得粘连、拖沓。尝试通过重组句子来消除不必要的“的”。
|
||||
3. **避免生硬的从句**：不要试图在一个长句中保留英文的所有修饰成分。将长句拆分为短句，符合中文的“流水句”特征。
|
||||
|
||||
### 6.4 词汇的选择
|
||||
|
||||
1. **动词的力量**：使用精准、有力的动词，避免使用“进行”、“作出了”等万能动词。
|
||||
2. **术语的“中文本地化”**：除非是专有名词（如 Rebase, Cherry-pick 这种很难翻译传神的），否则尽量使用标准的中文术语，但要标注英文原词。
|
||||
- **首次出现**：暂存区 (Staging Area)
|
||||
- **后续使用**：暂存区
|
||||
|
||||
### 6.5 中英文混排与标点符号
|
||||
|
||||
1. **空格规范**：**汉字与英文、汉字与数字之间，必须保留一个空格。**
|
||||
2. **标点符号**：
|
||||
- **全角标点**：中文句子中，必须使用全角标点（，。！？：；（））。
|
||||
- **英文标点**：只有在行内代码（Inline Code）或英文专业术语（如 `user.name`）中才使用半角标点。
|
||||
- **空格禁忌**：全角标点与汉字或英文之间，**不需要**添加空格。
|
||||
|
||||
### 6.6 标题与段落
|
||||
|
||||
1. **标题即论点**：标题不应只是名词，最好是动宾结构或完整的论点，让读者只看目录就能懂大意。
|
||||
2. **倒金字塔结构**：段落的第一句必须是**中心句 (Topic Sentence)**。先说结论，再展开解释，最后给例子。不要让读者读到最后一行才知道这一段想说什么。
|
||||
|
||||
## 7. 图形即代码 (Diagram as Code) 集成规范
|
||||
|
||||
文档中嵌入的架构图、时序图等图形资产，必须严格遵循《图形即代码设计规范指南》：
|
||||
|
||||
- **格式要求**：所有核心图表必须是可内嵌于 Markdown 的原生 **SVG** 代码，并支持通过 Git 进行 diff 比对与历史追溯。
|
||||
- **兼容性与背景**：为防止 Git 平台深色模式下的反色问题与 XSS 清洗，**推荐在 SVG 最底层放置纯白背景**（`<rect width="100%" height="100%" fill="#FFFFFF" />`），且**严禁包含 `<script>` 标签或外部图像/字体引用**。
|
||||
- **响应式适配**：SVG 必须使用 `viewBox` 属性定义坐标系，并将宽高设置为 `100%`，确保在 Markdown 容器内流畅等比缩放。
|
||||
|
||||
## 8. 术语与内容结构统一
|
||||
|
||||
- **MCP 协议原语**：在文档中描述系统能力时，需统一使用标准术语。例如，暴露给模型的主动操作必须统一称为 **Tools (工具)**；静态上下文数据源统一称为 **Resources (资源)**；复用模板称为 **Prompts (提示词)**。
|
||||
|
||||
## 9. 版权与许可声明
|
||||
|
||||
为了保障知识产权与开源精神的传承，**每一份标准文档的末尾，必须固定包含以下完全一致的版权与开源许可证声明**：
|
||||
|
||||
> ## 许可声明
|
||||
>
|
||||
> 本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research。
|
||||
Loading…
Reference in New Issue