Project-Caffeine/projects/arabica/docs/design/arabica-sprint1-architecture-specification.md

PArabica Sprint1 系统架构设计说明

1. 原型设计概述

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

关键功能：

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

---

2. 功能实现步骤说明

sequenceDiagram
    participant User as 用户
    participant Client as Cherry Studio (MCP Client)
    participant LLM as 大语言模型
    participant Server as MCP Server (Project Caffeine)

    User->>Client: 1. 输入查询（如“分析LLM在医疗中的应用瓶颈”）
    Client->>LLM: 传递查询
    LLM-->>Client: 2. 决策需要深度思考框架，决定调用工具
    Client->>Server: 3. tools/call (generate_5_whys, query=...)
    Server->>Server: 4. promptService.js 本地生成 5 Whys 追问列表
    Server-->>Client: 5. 返回 5 Whys 数组
    Client->>LLM: 6. 将 5 Whys 作为上下文，发起最终推理请求
    LLM-->>Client: 返回深度分析结果
    Client-->>User: 7. 渲染并展示深度研究报告

基于 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 将这部分内容进行界面渲染，最终向用户呈现一份高质量的“深度洞察报告”。

---

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-2：Sprint 1 组件架构与数据流

Sprint 1 系统组件架构基于 MCP 协议构建了一个轻量级的提示词策略服务器。

核心组件包括：

• app.js 作为主入口，负责初始化 McpServer 实例并配置 stdio 传输层，向客户端（Cherry Studio）注册 generate_5_whys 工具；
• controllers/promptsController.js 接收并路由工具调用请求；
• services/promptService.js 实现本地业务逻辑，根据用户查询自动生成 5 Whys 逐层追问列表；
• models/schemas.js 基于 Zod 进行参数校验。

整个服务不依赖外部大模型，完全在本地运行，通过标准输入输出与客户端通信，形成“用户提问 → 客户端大模型决策 → 服务端生成框架 → 客户端大模型深度推理”的闭环工作流。该架构为后续扩展更多思维框架和资源访问奠定了坚实基础。

---

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. 部署与验证

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 增强的回答。

---

7. 总结

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

---

许可声明

本文档采用 知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0) 进行许可，© 2025-2026 Gitconomy Research.