Files

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

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

2026-03-01 18:39:42 +08:00

10 KiB

Raw Blame History

Project Caffeine最小可行功能原型设计 —— 提示词策略MCP Server

1. 原型设计概述

功能目标：实现一个最简化的 提示词策略MCP Server，当用户发起查询时，系统能够调用 5 Whys 模板对查询进行分解，生成增强的提示词，并将其发送到大模型进行推理。

关键功能：

**工具注册 **：向 Cherry Studio 注册 generate_5_whys 能力。
接收工具调用请求：通过 stdio 接收 Cherry Studio 传来的用户查询主题。
5 Whys 模板分解：利用本地逻辑对查询进行分解，生成多层次的追问提示词。
资源暴露：将本地的文档库、PDF 或特定数据以 MCP Resource 的形式暴露给 Client（Sprint2）。

2. 功能实现步骤说明

2.1 客户端请求与工具分发

用户在 Cherry Studio 中输入查询意图（如：“分析LLM在医疗中的应用瓶颈”）。
Cherry Studio 内部的大模型判断需要更深度的思考框架，主动向本 MCP Server 发起 generate_5_whys 的工具调用。

2.2 生成 5 Whys 增强提示词

MCP Server 接收到参数后，执行本地 promptService.js，根据查询主题自动生成 5 个逐层递进的问题（5 Whys）。

2.3 结果返回与最终推理

MCP Server 将生成的 5 Whys 数组作为工具执行结果，通过标准协议返回给 Cherry Studio。
Cherry Studio 携带这些增强提示词再次请求大模型，生成最终的深度研究洞察，并展示给用户。

3. 系统组件架构设计

3.1 Project Caffeine 系统原型项目结构说明

project-caffeine/
│
├── node_modules/                    # 存放项目的依赖包
├── src/                             # 源代码文件夹
│   ├── 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                    # 项目配置
├── .env                             # 环境变量配置 (不再需要 LLM API Key)
├── package.json                     # 项目依赖 (@modelcontextprotocol/sdk)
└── README.md                        # 项目说明文档

各文件和文件夹的功能说明：

表1-1：Project Caffeine 项目 MVP 系统文件和文件夹功能详细说明表格

目录	文件名	功能说明
`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 系统模块架构说明

图1-1：提示词策略 MCP Server 系统组件工作流架构图

基于 Cherry Studio 和 MCP (Model Context Protocol) 架构的工作流分为七个关键步骤：

用户发起提问：用户首先在前端（Cherry Studio）输入自己的问题或查询需求。
大模型决策调用工具：Cherry Studio 作为 MCP 客户端，接收到用户提问后，其连接的大模型会对问题进行分析，并判断出需要调用系统注册的外部工具（如 5 Whys 分析法）来获取更好的提示词策略，而不是直接回答。
发起工具调用请求 tools/call：Cherry Studio 通过标准输入输出流（stdio）协议，向后端的 Project Caffeine MCP Server（基于 Node.js 构建）发送一个名为 generate_5_whys 的工具调用指令。
本地生成 5 Whys 文本：Project Caffeine MCP Server 接收到指令后，触发其内部的业务逻辑模块 promptService.js。该模块完全在本地运行，不依赖外部大模型，根据用户的初始问题自动生成 5 个逐层深入的追问（即 5 Whys 文本）。
返回工具执行结果：MCP Server 将生成的 5 Whys 文本打包成标准的结果格式，通过协议传回给 Cherry Studio。
结合工具结果发起最终推理：Cherry Studio 拿到这 5 个问题后，将其作为增强的上下文提示词，再次向大语言模型发起最终的深度推理请求，要求模型基于这些追问给出详尽的分析。
渲染并呈现结果：大模型完成最终推理后，Cherry Studio 将这部分内容进行界面渲染，最终向用户呈现一份高质量的“深度洞察报告”。

简单来说，这是一个“用户提问 -> 客户端大模型决定求助 -> 本地服务端生成分析框架 -> 客户端大模型根据框架给出深度回答”的完整闭环。

4. MCP 标准通信接口设计 (协议级)

基于 @modelcontextprotocol/sdk，底层的 JSON-RPC 通信由 SDK 接管。以下为逻辑层面的输入输出规约。

4.1 Tool 注册声明 (`tools/list`)

向 Client 声明具备的能力。

{
  "name": "generate_5_whys",
  "description": "使用 5 Whys 模板对用户查询进行深度分解，生成增强的提示词策略",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "用户需要分析的原始查询主题，例如：中国开源人才的现状分析"
      }
    },
    "required": ["query"]
  }
}

4.2 Tool 调用响应 (`tools/call`)

当 Client 传入 query: "中国开源人才的现状分析" 时，Server 返回的执行结果。

{
  "content": [
    {
      "type": "text",
      "text": "[\n  \"为什么中国开源人才的培养面临困难？\",\n  \"为什么中国开源人才缺乏足够的行业经验？\",\n  \"为什么开源社区对中国人才的支持力度不足？\",\n  \"为什么中国开源人才的市场需求与供给不平衡？\",\n  \"为什么政策支持不足导致中国开源人才流失？\"\n]"
    }
  ]
}

4.3 存储资源访问 (`resources/list` & `resources/read`)

允许 Cherry Studio 查阅本地文件上下文。

资源列表响应示例 (resources/list):

{
  "resources": [
    {
      "uri": "file:///path/to/obsidian/vault/开源行业报告.md",
      "name": "开源行业研究报告",
      "mimeType": "text/markdown",
      "description": "本地知识库中的开源行业深度分析文档"
    }
  ]
}

5. 最小可行产品（MVP）开发环境

本阶段的开发环境高度依赖实际的 Client 联调：

Node.js (v18+)：提供运行环境。
@modelcontextprotocol/sdk：官方依赖，提供 stdio 传输支持。
Cherry Studio：作为唯一指定测试 Client，配置为以 command: node 的方式启动 Server。
VS Code Attach 调试：利用 --inspect=9229 参数，在 Cherry Studio 唤起 Server 后，通过 VS Code 附加到该进程实现源码级断点调试。

6. 部署与验证

环境初始化：安装 Node.js 依赖及 Zod 校验库。
Client 配置：在 Cherry Studio 的 MCP 设置中，添加名为 ProjectCaffeine 的 Server，指向本地的 app.js 绝对路径，并添加 --inspect 参数。
断点监听：在 VS Code 中启动 Attach 调试任务，等待 Cherry Studio 握手。
触发验证：在 Cherry Studio 对话框中要求模型“调用工具分析某问题”，观察 VS Code 是否成功捕获断点，并最终在 Cherry Studio 界面输出基于 5 Whys 增强的回答。

7. 总结

本设计说明提供了 Project Caffeine 的 提示词策略MCP Server 最小可行功能的开发框架，包括 5 Whys 模板生成、增强提示词的合成、推理请求与返回等关键功能。通过实现这一功能，可以验证整个系统的基本运行环境，确保 MCP协议 的各个组件能够顺利协同工作。

10 KiB Raw Blame History Unescape Escape