diff --git a/projects/arabica/docs/deisgn/arabica-sprint1-architecture-specification.md b/projects/arabica/docs/deisgn/arabica-sprint1-architecture-specification.md index e966d5c..02b23d9 100644 --- a/projects/arabica/docs/deisgn/arabica-sprint1-architecture-specification.md +++ b/projects/arabica/docs/deisgn/arabica-sprint1-architecture-specification.md @@ -4,11 +4,11 @@ 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) +version: v1.0.2 (Arabica) author: Gitconomy Research-郭晧 date: 2026-03-1 -last-update: 2026-03-01 -update-description: 增加Cherry Stuio作为 MCP Client，上一版的设计还是基于传统的“AI Web 应用后端”，而不是严格意义上的 MCP 系统框架 。 +last-update: 2026-03-05 +update-description: 更新Sprint1 数据流示意图和架构图的说明描述。 tags: - Project Caffeine - MCP Server @@ -21,7 +21,7 @@ license: CC BY-SA 4.0 status: Active --- --> -# Arabica Sprint1 系统架构设计说明 +# PArabica Sprint1 系统架构设计说明 ## 1. 原型设计概述 @@ -38,19 +38,34 @@ status: Active ### 2. 功能实现步骤说明 -#### 2.1 客户端请求与工具分发 -- 用户在 **Cherry Studio** 中输入查询意图（如：“分析LLM在医疗中的应用瓶颈”）。 -- Cherry Studio 内部的大模型判断需要更深度的思考框架，主动向本 **MCP Server** 发起 `generate_5_whys` 的工具调用。 +```mermaid +sequenceDiagram + participant User as 用户 + participant Client as Cherry Studio (MCP Client) + participant LLM as 大语言模型 + participant Server as MCP Server (Project Caffeine) -#### 2.2 生成 5 Whys 增强提示词 + 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. 渲染并展示深度研究报告 +``` -- **MCP Server** 接收到参数后，执行本地 `promptService.js`，根据查询主题自动生成 5 个逐层递进的问题（5 Whys）。 +基于 Cherry Studio 和 MCP (Model Context Protocol) 架构的工作流分为七个关键步骤： -#### 2.3 结果返回与最终推理 - -- **MCP Server** 将生成的 5 Whys 数组作为工具执行结果，通过标准协议返回给 Cherry Studio。 -- Cherry Studio 携带这些增强提示词再次请求大模型，生成最终的深度研究洞察，并展示给用户。 +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 将这部分内容进行界面渲染，最终向用户呈现一份高质量的“深度洞察报告”。 --- @@ -86,33 +101,30 @@ project-caffeine/ *表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 唤起时的断点联调。 | +| **目录** | **文件名** | **功能说明** | +| ---------------------- | ---------------------------- | --------------------------------------------------------------- | +| **`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 系统组件工作流架构图* +*图 1-2：Sprint 1 组件架构与数据流* -![提示词策略工作流](./../../../../docs/assets/images/prompt-strategy-mcp-server-prototype-architecture.svg) +![Sprint1组件架构图](./../../../docs/assets/images/arabica-srpint1-architecture-design.svg) +Sprint 1 系统组件架构基于 MCP 协议构建了一个轻量级的提示词策略服务器。 -基于 Cherry Studio 和 MCP (Model Context Protocol) 架构的工作流分为七个关键步骤： +核心组件包括： +- `app.js` 作为主入口，负责初始化 `McpServer` 实例并配置 `stdio` 传输层，向客户端（Cherry Studio）注册 `generate_5_whys` 工具； +- `controllers/promptsController.js` 接收并路由工具调用请求； +- `services/promptService.js` 实现本地业务逻辑，根据用户查询自动生成 5 Whys 逐层追问列表； +- `models/schemas.js` 基于 Zod 进行参数校验。 -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 将这部分内容进行界面渲染，最终向用户呈现一份高质量的“深度洞察报告”。 - -简单来说，这是一个“用户提问 -> 客户端大模型决定求助 -> 本地服务端生成分析框架 -> 客户端大模型根据框架给出深度回答”的完整闭环。 +整个服务不依赖外部大模型，完全在本地运行，通过标准输入输出与客户端通信，形成“用户提问 → 客户端大模型决策 → 服务端生成框架 → 客户端大模型深度推理”的闭环工作流。该架构为后续扩展更多思维框架和资源访问奠定了坚实基础。 ---