new_org/Project-Caffeine
2
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(add):新增Project Caffeine项目Arabica Sprint1系统组件架构设计文档

Browse Source 
Signed-off-by: gzkoala <guohao@gitconomy.org>
This commit is contained in:
gzkoala
2026-03-01 18:39:42 +08:00
parent aa986c55a3
commit 4b6d9a8789
2 changed files with 438 additions and 556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
docs/design/project-caffeine-mvp-sprint1-architecture-design.md
View File

@@ -1,12 +1,14 @@
<!--
---
title: "提示词策略 MCP Server 原型设计文档"
description: "Project Caffeine 提示词策略 MCP Server 的最小可行性功能（MVP）原型设计，涵盖 5 Whys 模板调用、增强提示词合成及 Node.js 环境工作流验证"
type: "Architecture Design"
file: "project-caffeine-mvp-sprint1-architecture-design.md"
version: "v1.0.0 (Arabica)"
author: "Gitconomy Research-郭晧"
title: 提示词策略 MCP Server 原型设计文档
description: Project Caffeine 提示词策略 MCP Server 的最小可行性功能（MVP）原型设计，涵盖 5 Whys 模板调用、增强提示词合成及 Node.js 环境工作流验证
type: Architecture Design
file: project-caffeine-mvp-sprint1-architecture-design.md
version: v1.0.1 (Arabica)
author: Gitconomy Research-郭晧
date: 2026-03-1
last-update: 2026-03-01
update-description: 增加Cherry Stuio作为 MCP Client，上一版的设计还是基于传统的“AI Web 应用后端”，而不是严格意义上的 MCP 系统框架 。
tags:
- Project Caffeine
- MCP Server
@@ -15,8 +17,8 @@ tags:
- Prompt Strategy
- 5 Whys
- Node.js
license: "CC BY-SA 4.0"
status: "Active"
license: CC BY-SA 4.0
status: Active
---
-->
# Project Caffeine最小可行功能原型设计 —— 提示词策略MCP Server
@@ -27,39 +29,28 @@ status: "Active"
**关键功能**：
- **接收查询请求**：用户输入查询主题（如：“LLM在医疗中的应用瓶颈”），并发送请求到 **提示词策略MCP Server**。
- **5 Whys 模板**：通过 **5 Whys** 提示词模板分解查询，生成多层次的推理问题。
- **增强提示词生成**：根据查询主题和 **5 Whys** 的分解结果，生成增强的合成提示词。
- **推理请求**：将生成的提示词发送到大语言模型（如 **OpenAI GPT** 或类似模型）进行推理。
- **返回推理结果**：返回推理结果给用户，并展示深度的研究洞察。
- **工具注册 **：向 Cherry Studio 注册 `generate_5_whys` 能力。
- **接收工具调用请求**：通过 `stdio` 接收 Cherry Studio 传来的用户查询主题。
- **5 Whys 模板分解**：利用本地逻辑对查询进行分解，生成多层次的追问提示词。
- **资源暴露**：将本地的文档库、PDF 或特定数据以 MCP Resource 的形式暴露给 Client（Sprint2）。
---
### 2. 功能实现步骤说明
#### 2.1 接收查询请求
#### 2.1 客户端请求与工具分发
- 用户通过客户端向 **提示词策略MCP Server** 发送查询请求。
- 用户在 **Cherry Studio** 中输入查询意图（如：“分析LLM在医疗中的应用瓶颈”）。
- Cherry Studio 内部的大模型判断需要更深度的思考框架，主动向本 **MCP Server** 发起 `generate_5_whys` 的工具调用。
#### 2.2 生成 5 Whys 提示词
#### 2.2 生成 5 Whys 增强提示词
- **提示词策略MCP Server** 接收到查询后，利用 **5 Whys** 模板对查询进行分解。
- **MCP Server** 接收到参数后，执行本地 `promptService.js`，根据查询主题自动生成 5 个逐层递进的问题（5 Whys）。
- **5 Whys** 模板根据查询主题，自动生成多个深度的问题，逐步追溯问题的根本原因。
#### 2.3 结果返回与最终推理
#### 2.3 增强提示词生成
- 在 **5 Whys** 的基础上，系统生成增强的提示词，将其送入下游的大语言模型进行推理。
#### 2.4 推理请求与推理结果
- 将增强后的提示词发送给大语言模型，进行深度推理和分析。
- 大语言模型根据提示词生成分析结果，并将结果返回给 **提示词策略MCP Server**。
#### 2.5 返回推理结果
- **提示词策略MCP Server** 返回推理结果给用户，并展示生成的研究洞察。
- **MCP Server** 将生成的 5 Whys 数组作为工具执行结果，通过标准协议返回给 Cherry Studio。
- Cherry Studio 携带这些增强提示词再次请求大模型，生成最终的深度研究洞察，并展示给用户。
---
@@ -72,245 +63,139 @@ project-caffeine/
│
├── node_modules/ # 存放项目的依赖包
├── src/ # 源代码文件夹
│ ├── controllers/ # API 逻辑处理
│ │ ├── promptsController.js # 处理提示词策略相关请求
│ │ ├── modelController.js # 处理与大模型的推理请求
│ │ ├── resourcesController.js # 处理资源请求（新的资源部分）
│ ├── services/ # 业务逻辑层
│ │ ├── promptService.js # 处理 5 Whys 提示词生成
│ │ ├── inferenceService.js # 处理推理请求和结果
│ │ ├── resourceService.js # 处理资源数据交互（新的资源服务）
│ ├── models/ # 数据模型
│ │ └── queryModel.js # 用于表示请求体的数据模型
│ ├── routes/ # API 路由文件夹
│ │ └── apiRoutes.js # API 路由配置
│ ├── utils/ # 工具类函数
│ │ └── responseHandler.js # 处理API响应的工具函数
│ └── app.js # 主应用入口文件
│ ├── controllers/ # 逻辑路由分发层
│ │ ├── promptsController.js # 处理提示词 Tool 相关请求
│ │ └── resourcesController.js # 处理资源 Resource 请求
│ ├── services/ # 核心业务逻辑层
│ │ ├── promptService.js # 处理 5 Whys 提示词模板的生成算法
│ │ └── resourceService.js # 处理本地文件、知识库等资源读取逻辑
│ ├── models/ # 数据模型与校验
│ │ └── schemas.js # 基于 Zod 的参数校验定义
│ └── app.js # 主应用入口，初始化 MCP Server (stdio)
│
├── .vscode/ # IDE 调试配置
│ └── launch.json # 配置 Cherry Studio 联调附加(Attach)环境
├── config/ # 配置文件
│ ├── config.js # 项目配置文件，如环境变量等
│ └── apiConfig.js # 与API相关的配置
│
├── .env # 环境变量配置文件
├── package.json # 项目依赖和启动配置
│ └── config.js # 项目配置
├── .env # 环境变量配置 (不再需要 LLM API Key)
├── package.json # 项目依赖 (@modelcontextprotocol/sdk)
└── README.md # 项目说明文档
```
**各文件和文件夹的功能说明**：
- `src/`：包含项目的源代码，核心功能逻辑，包括控制器、服务、路由、模型等。
- `src/controllers/`：控制器负责接收请求并调用相应的服务，执行具体的业务逻辑。
- `src/services/`：服务层处理具体的业务逻辑，例如生成提示词、推理请求和资源访问等。
- `src/models/`：定义数据模型，用于标准化请求体和数据结构。
- `src/utils/`：工具类函数，帮助简化代码实现，例如统一响应格式的处理。
- `config/`：存放配置信息，包括环境变量配置和外部服务的 API 配置。
- **根目录**：包含项目的说明文档、环境配置文件等。
<br>
*表1-1：**Project Caffeine** 项目 MVP 系统文件和文件夹功能详细说明表格*
| **目录** | **文件名** | **作用** | **功能** |
| ---------------------- | ---------------------------- | ------------- | ------------------------------------------------------ |
| **`src/`** | **`app.js`** | 主应用程序入口文件 | 初始化 Express 应用，设置中间件，配置 API 路由并启动服务器。 |
| **`src/`** | **`apiRoutes.js`** | API 路由配置文件 | 定义项目的 API 路由，将请求分发到不同的控制器进行处理。 |
| **`src/controllers/`** | **`promptsController.js`** | 处理查询请求，生成提示词 | 接收查询请求，调用 **promptService.js** 生成提示词（如 **5 Whys** 模板）。 |
| **`src/controllers/`** | **`modelController.js`** | 处理推理请求，调用推理服务 | 将增强的提示词发送到大语言模型进行推理，获取推理结果并返回。 |
| **`src/controllers/`** | **`resourcesController.js`** | 处理与资源相关的请求 | 获取资源列表并返回（如学术数据库、PDF 文件、本地知识库）。 |
| **`src/services/`** | **`promptService.js`** | 提示词生成服务 | 根据查询生成 **5 Whys** 模板的提示词，增强查询深度。 |
| **`src/services/`** | **`inferenceService.js`** | 推理服务 | 与大语言模型交互，处理增强提示词并获取推理结果。 |
| **`src/services/`** | **`resourceService.js`** | 资源服务 | 管理外部资源，如学术数据库、PDF 文件、本地知识库等。 |
| **`src/models/`** | **`queryModel.js`** | 数据模型 | 用于表示请求体的数据模型，确保请求的格式和字段一致。 |
| **`src/utils/`** | **`responseHandler.js`** | 响应处理工具 | 处理 API 响应格式，标准化响应数据。 |
| **`config/`** | **`config.js`** | 项目配置文件 | 存储端口、API 密钥等项目的环境变量配置。 |
| **`config/`** | **`apiConfig.js`** | API 配置文件 | 存储与外部 API（如大语言模型和学术资源接口）相关的配置。 |
| **`public/`** | **`index.html`** | 静态资源文件 | 提供项目的主页或其他静态页面文件。 |
| **`config/`** | **`.env`** | 环境变量配置文件 | 存储敏感数据（如端口号、API 密钥）和配置项，确保应用正常运行。 |
| **`config/`** | **`package.json`** | 项目依赖配置 | 管理项目的依赖包、脚本命令和开发环境设置。 |
| **根目录** | **`README.md`** | 项目说明文档 | 提供项目的背景、功能、安装步骤和使用方法等信息。 |
| **目录** | **文件名** | **功能说明** |
| --- | --- | --- |
| **`src/`** | **`app.js`** | 实例化官方 `McpServer`，配置 `stdio` 传输层，向 Client 注册 Tools 和 Resources。 |
| **`src/controllers/`** | **`promptsController.js`** | 接收 `tools/call` 请求，调用 `promptService` 并格式化输出返回给 Client。 |
| **`src/controllers/`** | **`resourcesController.js`** | 处理 `resources/list` 和 `resources/read` 请求，返回资源数据。 |
| **`src/services/`** | **`promptService.js`** | 纯本地业务逻辑：根据入参字符串生成 **5 Whys** 数组结构。 |
| **`src/services/`** | **`resourceService.js`** | 本地文件系统交互：读取本地知识库（如 Obsidian）或指定目录文档。 |
| **`.vscode/`** | **`launch.json`** | 极其关键：配置 Node.js 的 `--inspect` 端口，实现基于 Cherry Studio 唤起时的断点联调。 |
### 3.2 系统模块架构说明
原型系统的主要模块包括：
- **Client Request** 发起请求，经过 **HTTP Request** 传递给后端。
- **app.js** 作为主控制器，分发请求到不同的路由处理器（**apiRoutes.js**）。
- **promptsController.js** 处理查询请求，生成提示词，调用 **promptService.js**。
- **modelController.js** 处理推理请求，将增强的提示词发送到大语言模型。
- **inferenceService.js** 负责与大语言模型交互，获取推理结果并返回。
- 配置信息存储在 **.env** 和 **config.js** 中，确保系统配置与环境的适配。
- **resourceService.js**：管理外部资源的获取和存储，如学术数据库、PDF 文档和本地知识库。这些资源将为推理模块提供必要的数据支持。
<br>
这些组件通过 **MCP 协议** 和 **JSON-RPC 2.0** 格式进行通信，确保系统的各个部分能够高效地协作，共同完成从查询处理到推理结果输出的全过程。
### 3.3 系统数据流示意
*图1-1：提示词策略 MCP Server 系统组件工作流架构图*
![提示词策略工作流](./../assets/images/prompt-strategy-mcp-server-prototype-architecture.svg)
通过 **MCP 协议**，整个系统模块能够协同工作，从用户输入的查询请求到最终的推理结果输出，确保整个流程的高效性与准确性。
1. **用户发起请求**：用户通过 **Client Request** 发起查询或推理请求。
2. **HTTP 请求传输**：请求通过 **HTTP Request** 传递到后端。
3. **请求路由**：**app.js** 将请求转发到 **apiRoutes.js**，并进一步分发到相应的控制器（如 **promptsController.js** 和 **modelController.js**）。
4. **提示词生成**：在 **promptsController.js** 中，查询请求被转交到 **promptService.js**，生成符合 **5 Whys** 模板的增强提示词。
5. **推理请求**：增强的提示词通过 **modelController.js** 传递给 **inferenceService.js**，与大语言模型交互。
6. **推理结果返回**：大语言模型返回推理结果，**inferenceService.js** 将结果传回 **modelController.js**，并最终返回给用户。
7. **资源获取**：在整个过程中，**resourceService.js** 提供外部资源（如学术文献、PDF 文件等）的访问，支持推理和查询过程的数据需求。
基于 Cherry Studio 和 MCP (Model Context Protocol) 架构的工作流分为七个关键步骤：
1. **用户发起提问**：用户首先在前端（Cherry Studio）输入自己的问题或查询需求。
2. **大模型决策调用工具**：Cherry Studio 作为 MCP 客户端，接收到用户提问后，其连接的大模型会对问题进行分析，并判断出需要调用系统注册的外部工具（如 5 Whys 分析法）来获取更好的提示词策略，而不是直接回答。
3. **发起工具调用请求 tools/call**：Cherry Studio 通过标准输入输出流（`stdio`）协议，向后端的 Project Caffeine MCP Server（基于 Node.js 构建）发送一个名为 `generate_5_whys` 的工具调用指令。
4. **本地生成 5 Whys 文本**：Project Caffeine MCP Server 接收到指令后，触发其内部的业务逻辑模块 `promptService.js`。该模块完全在本地运行，不依赖外部大模型，根据用户的初始问题自动生成 5 个逐层深入的追问（即 5 Whys 文本）。
5. **返回工具执行结果**：MCP Server 将生成的 5 Whys 文本打包成标准的结果格式，通过协议传回给 Cherry Studio。
6. **结合工具结果发起最终推理**：Cherry Studio 拿到这 5 个问题后，将其作为增强的上下文提示词，再次向大语言模型发起最终的深度推理请求，要求模型基于这些追问给出详尽的分析。
7. **渲染并呈现结果**：大模型完成最终推理后，Cherry Studio 将这部分内容进行界面渲染，最终向用户呈现一份高质量的“深度洞察报告”。
简单来说，这是一个“用户提问 -> 客户端大模型决定求助 -> 本地服务端生成分析框架 -> 客户端大模型根据框架给出深度回答”的完整闭环。
---
## 4. API 接口设计
## 4. MCP 标准通信接口设计 (协议级)
### 4.1 用户查询请求
基于 `@modelcontextprotocol/sdk`，底层的 JSON-RPC 通信由 SDK 接管。以下为逻辑层面的输入输出规约。
用户向 **提示词策略MCP Server** 发送查询请求，请求体包括查询主题。
### 4.1 Tool 注册声明 (`tools/list`)
##### 请求示例（`prompts.query`）
向 Client 声明具备的能力。
```json
{
"method": "prompts.query",
"params": {
"query": "中国开源人才的现状分析"
},
"id": "12345"
"name": "generate_5_whys",
"description": "使用 5 Whys 模板对用户查询进行深度分解，生成增强的提示词策略",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "用户需要分析的原始查询主题，例如：中国开源人才的现状分析"
}
},
"required": ["query"]
}
}
```
### 4.2 5 Whys 提示词模板生成
### 4.2 Tool 调用响应 (`tools/call`)
**提示词策略MCP Server** 将查询通过 **5 Whys** 模板进行处理，逐步分解问题，并生成增强的提示词。
##### 响应示例（`prompts.query`）
当 Client 传入 `query: "中国开源人才的现状分析"` 时，Server 返回的执行结果。
```json
{
"result": {
"enhanced_prompt": [
"为什么中国开源人才的培养面临困难？",
"为什么中国开源人才缺乏足够的行业经验？",
"为什么开源社区对中国人才的支持力度不足？",
"为什么中国开源人才的市场需求与供给不平衡？",
"为什么政策支持不足导致中国开源人才流失？"
]
},
"id": "12345"
"content": [
{
"type": "text",
"text": "[\n \"为什么中国开源人才的培养面临困难？\",\n \"为什么中国开源人才缺乏足够的行业经验？\",\n \"为什么开源社区对中国人才的支持力度不足？\",\n \"为什么中国开源人才的市场需求与供给不平衡？\",\n \"为什么政策支持不足导致中国开源人才流失？\"\n]"
}
]
}
```
### 4.3 推理请求
### 4.3 存储资源访问 (`resources/list` & `resources/read`)
生成的提示词将发送到大语言模型进行推理。推理请求会将增强的提示词作为输入。
允许 Cherry Studio 查阅本地文件上下文。
##### 请求示例（`model.infer`）
**资源列表响应示例 (`resources/list`):**
```json
{
"method": "model.infer",
"params": {
"prompts": [
"为什么中国开源人才的培养面临困难？",
"为什么中国开源人才缺乏足够的行业经验？",
"为什么开源社区对中国人才的支持力度不足？",
"为什么中国开源人才的市场需求与供给不平衡？",
"为什么政策支持不足导致中国开源人才流失？"
]
},
"id": "12345"
}
```
### 4.4 推理结果返回
大语言模型根据提示词生成推理结果，并将其返回给 **提示词策略MCP Server**，然后将结果发送回用户。
##### 响应示例（`model.infer`）
```json
{
"result": {
"analysis": [
"中国开源人才的培养面临困难，主要是由于缺乏行业经验和实践机会。",
"开源社区支持不足，导致中国开源人才的成长空间受限。",
"中国开源人才的市场需求与供给不平衡，缺乏足够的职业发展机会。",
"政策支持不足，导致许多开源人才选择离开或转向其他行业。",
"开源人才流失的原因之一是对本土开发环境和项目缺乏信任。"
]
},
"id": "12345"
}
```
### 4.5 存储资源访问
在 **MCP Server** 中，**Resource API** 用于提供系统需要访问的资源，允许 **MCP Client** 通过 **MCP Server** 获取和管理这些资源。
#### **请求示例（`resources/list`）**
获取可用资源列表的请求。
```json
{
"method": "resources.list",
"params": {},
"id": "1234"
}
```
#### **响应示例（`resources.list`）**
返回资源信息，包括学术数据库、PDF 文件、互联网资源等。
```json
{
"result": [
{
"resource_id": "academic_database",
"description": "学术数据库资源",
"type": "API",
"endpoint": "https://api.academicdb.com/v1/query"
},
{
"resource_id": "pdf_document",
"description": "PDF 文档资源",
"type": "File",
"file_path": "/path/to/document.pdf"
},
{
"resource_id": "local_kb",
"description": "本地知识库资源",
"type": "Directory",
"directory_path": "/path/to/obsidian/vault"
}
],
"id": "1234"
"resources": [
{
"uri": "file:///path/to/obsidian/vault/开源行业报告.md",
"name": "开源行业研究报告",
"mimeType": "text/markdown",
"description": "本地知识库中的开源行业深度分析文档"
}
]
}
```
---
## 5. **最小可行产品（MVP）开发环境**
## 5. 最小可行产品（MVP）开发环境
为了验证这一最小可行功能（MVP），开发环境应包括以下组件：
本阶段的开发环境高度依赖实际的 Client 联调：
- **Node.js**：用于后端服务开发，处理 API 请求和响应。
- **MCP 协议实现**：实现任务调度、数据传输和组件间通讯。
- **大语言模型**：可以使用开源模型（如 GPT-3、GPT-4）进行推理。
- **Express.js**：搭建一个轻量级的 Node.js 服务，处理请求和响应。
- **Postman 或 Curl**：用于模拟 API 请求和响应，进行接口测试。
* **Node.js (v18+)**：提供运行环境。
* **@modelcontextprotocol/sdk**：官方依赖，提供 `stdio` 传输支持。
* **Cherry Studio**：作为唯一指定测试 Client，配置为以 `command: node` 的方式启动 Server。
* **VS Code Attach 调试**：利用 `--inspect=9229` 参数，在 Cherry Studio 唤起 Server 后，通过 VS Code 附加到该进程实现源码级断点调试。
---
## 6. **部署与验证**
## 6. 部署与验证
1. **部署 API 服务**：使用 **Node.js** 和 **Express.js** 部署 **提示词策略MCP Server**。
2. **模拟查询请求**：使用 **Postman** 或 **Curl** 向服务发送模拟的查询请求，验证提示词生成是否正确。
3. **测试推理功能**：集成大语言模型的推理 API，确保生成的增强提示词能够正确传递并获得推理结果。
4. **返回结果验证**：确保推理结果能够返回，并符合预期的研究洞察。
1. **环境初始化**：安装 Node.js 依赖及 Zod 校验库。
2. **Client 配置**：在 Cherry Studio 的 MCP 设置中，添加名为 `ProjectCaffeine` 的 Server，指向本地的 `app.js` 绝对路径，并添加 `--inspect` 参数。
3. **断点监听**：在 VS Code 中启动 Attach 调试任务，等待 Cherry Studio 握手。
4. **触发验证**：在 Cherry Studio 对话框中要求模型“调用工具分析某问题”，观察 VS Code 是否成功捕获断点，并最终在 Cherry Studio 界面输出基于 5 Whys 增强的回答。
---