<!--
---
title: Arabica Sprint12系统架构设计说明
description: Project Caffeine 提示词策略 MCP Server Sprint 2 架构设计，聚焦于 MCP Prompts 原语接入、多维思维框架组装及底层角色矩阵设计。
version: v1.0.0 (Arabica) - Sprint 2
author: Gitconomy Research-郭晧
date: 2026-03-05
type: Architecture Design
file: project-caffeine-mvp-sprint2-architecture-design.md
tags:
  - Project Caffeine
  - MCP Server
  - Sprint 2
  - Prompt Strategy
  - Prompts
  - Node.js
license: CC BY-SA 4.0
status: Active
---
-->
# Arabica Sprint2 系统架构设计说明

## 1. Sprint2 设计概述

**Sprint 1** 实现了基于 **5 Whys** 的单一思维框架工具调用，验证了 MCP 协议下本地策略服务与大模型协同的可行性。  

**Sprint 2** 的核心目标是将提示词策略 Server（S2）从“单点工具”升级为“多维思维框架引擎”，通过引入 MCP 的 **Prompts 原语**，将多种经典思维框架（5W3H、SCQA、SWOT、PESTLE 等）作为可复用的模板暴露给大模型，并开发意图拆解工具，使系统能够自动将用户模糊的自然语言查询拆解为专业检索词，从而大幅提升研究的广度与深度。

**关键功能**：

- **Prompts 原语接入**：实现 `prompts/list` 和 `prompts/get` 接口，向客户端（Cherry Studio）注册多个静态思维框架模板。
- **多维思维框架库**：内置 5W3H、SCQA、SWOT、PESTLE 等框架，每个框架包含结构化提示词模板。
- **意图拆解工具**：开发 `generate_search_queries` 工具，将用户原始查询拆解为 3~5 个专业检索词，用于后续文献检索（Sprint 3）。
- **角色矩阵与输出规范**：设计多智能体角色矩阵雏形，并在提示词中通过 Few-Shot 示例约束输出格式（如强制 Markdown 结构）。

---

## 2. 功能实现步骤说明

典型用户查询流程（参见图 2-1）：

```mermaid
sequenceDiagram
    participant User as 用户
    participant Client as Cherry Studio (MCP Client)
    participant LLM as 大模型
    participant S2 as 提示词策略 Server (S2)

    User->>Client: 输入查询Q
    Client->>LLM: 传递查询Q
    LLM->>Client: 决策需要思维框架
    Client->>S2: prompts/get (框架=SCQA)
    S2-->>Client: 返回SCQA模板
    Client->>LLM: 组合模板+Q，请求推理
    LLM->>Client: 需要检索词，调用工具
    Client->>S2: tools/call (generate_search_queries, query=Q)
    S2->>S2: 意图拆解逻辑
    S2-->>Client: 返回检索词列表
    Client->>LLM: 提供检索词，继续推理
    LLM-->>Client: 生成深度报告
    Client-->>User: 展示结果
```

1. **用户输入自然语言查询**（如“分析新能源汽车行业竞争格局”）。
2. **Cherry Studio 内大模型决策**：判断需要调用多维思维框架辅助分析。
3. **客户端发起 `prompts/get` 请求**：选择合适的思维框架（例如 SCQA），获取模板内容。
4. **客户端组合提示词**：将模板与用户查询结合，形成增强提示词。
5. **大模型初步推理**：可能识别出需要更专业的检索词，于是调用 `generate_search_queries` 工具。
6. **服务端执行意图拆解**：`intentService` 根据查询生成检索词列表。
7. **工具结果返回**：客户端获得检索词，可结合文献查询 Server（Sprint 3）进行下一步检索。
8. **最终推理与输出**：大模型利用框架模板和检索结果生成结构化深度报告。

---

## 3. 系统组件架构设计

### 3.1 项目结构更新（基于 Sprint 1）

```markdown
project-caffeine/
│
├── src/
│   ├── controllers/
│   │   ├── promptsController.js       # 处理 prompts/list 和 prompts/get
│   │   ├── toolsController.js         # 处理工具调用（含原有5Whys+新增意图拆解）
│   │   └── resourcesController.js     # （保留，Sprint3扩展）
│   ├── services/
│   │   ├── promptService.js           # 升级：管理多框架模板库，根据框架名返回结构化提示词
│   │   ├── intentService.js           # 新增：意图拆解逻辑，生成检索词
│   │   └── resourceService.js         # （保留）
│   ├── models/
│   │   ├── schemas.js                 # Zod校验（新增prompts参数校验）
│   │   └── frameworks/                # 思维框架定义目录
│   │       ├── 5w3h.json
│   │       ├── scqa.json
│   │       ├── swot.json
│   │       └── pestle.json
│   └── app.js                          # 主入口：注册 Prompts 和 Tools
│
├── .vscode/launch.json                  # 调试配置（不变）
├── config/config.js                     # 配置（可扩展框架路径）
└── package.json                         # 依赖（不变）
```


*表 2-1：Sprint 2 新增/修改文件说明*

|文件/目录|类型|功能说明|
|---|---|---|
|`src/controllers/promptsController.js`|新增|处理 `prompts/list` 和 `prompts/get` 请求，调用 `promptService` 获取模板|
|`src/services/intentService.js`|新增|实现 `generate_search_queries` 工具的核心逻辑：基于规则或小模型将自然语言拆解为检索词|
|`src/models/frameworks/`|新增|存放各思维框架的 JSON 定义，包含名称、描述、模板内容、参数占位符等|
|`src/services/promptService.js`|修改|从静态文件加载框架库，提供 `listFrameworks()` 和 `getFramework(name, params)` 方法|
|`src/controllers/toolsController.js`|修改|增加对 `generate_search_queries` 的路由分发|
|`src/models/schemas.js`|修改|增加 `generate_search_queries` 的输入参数校验（如 `query` 字符串）|

### 3.2 系统模块架构图

*图 2-2：Sprint 2 组件架构与数据流*

![Sprint2组件架构图](./../../../../docs/assets/images/arabica-srpint2-architecture-design.svg)

Sprint 2 系统组件架构在 Sprint 1 的基础上，将提示词策略 Server（S2）从单一工具升级为多维思维框架引擎。核心组件包括：

- 控制器层：新增 promptsController.js 专门处理 MCP Prompts 原语（prompts/list 和 prompts/get），toolsController.js 扩展支持 generate_search_queries 工具调用。

- 服务层：promptService.js 升级为多框架管理器，从 models/frameworks/ 目录加载 JSON 定义的思维模板（5W3H、SCQA、SWOT、PESTLE 等）；新增 intentService.js 实现意图拆解逻辑，将自然语言查询转化为专业检索词。

- 模型层：schemas.js 增加 Prompts 参数和意图拆解工具的 Zod 校验；frameworks/ 目录以 JSON 形式存放各框架的元数据、模板内容和角色定义。

- 主入口：app.js 同时注册 Prompts 和 Tools 能力，通过 stdio 与客户端通信。

该架构的核心数据链路分为四步：客户端通过 prompts/get 获取匹配的思维框架模板；服务端返回结构化提示词；大模型在推理中可调用 generate_search_queries 获取检索词；最终通过模板内嵌的系统消息（含角色矩阵和 Few-Shot 示例）约束输出格式，生成符合规范的深度报告。这一设计为后续文献检索（Sprint 3）和递归深度研究奠定了坚实的“大脑”基础。

---

## 4. MCP 标准通信接口设计

### 4.1 Prompts 原语

**`prompts/list` 响应示例**  
向客户端声明可用的思维框架列表：

```json
{
  "prompts": [
    {
      "name": "5w3h",
      "description": "5W3H 分析法：从 What、Why、Who、When、Where、How、How much、How feel 八个维度拆解问题",
      "arguments": [
        {
          "name": "topic",
          "description": "需要分析的主题",
          "required": true
        }
      ]
    },
    {
      "name": "scqa",
      "description": "SCQA 架构：Situation、Complication、Question、Answer，适用于问题分析与方案构建",
      "arguments": [
        {
          "name": "situation",
          "description": "背景描述",
          "required": true
        }
      ]
    },
    {
      "name": "swot",
      "description": "SWOT 分析：Strengths、Weaknesses、Opportunities、Threats",
      "arguments": [
        {
          "name": "entity",
          "description": "分析对象（企业、项目等）",
          "required": true
        }
      ]
    },
    {
      "name": "pestle",
      "description": "PESTLE 宏观环境分析：Political、Economic、Social、Technological、Legal、Environmental",
      "arguments": [
        {
          "name": "domain",
          "description": "行业或领域",
          "required": true
        }
      ]
    }
  ]
}
```


**`prompts/get` 请求与响应示例**  
客户端请求 `scqa` 框架，并提供参数：

```json
// 请求
{
  "name": "scqa",
  "arguments": {
    "situation": "新能源汽车行业竞争日益激烈"
  }
}
// 响应
{
  "description": "SCQA 分析框架",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "请使用 SCQA 架构分析以下情境：\n情境 (Situation)：新能源汽车行业竞争日益激烈。\n\n请依次构建：\n1. 复杂化 (Complication)：指出情境中存在的矛盾或挑战。\n2. 问题 (Question)：基于复杂化提炼出核心问题。\n3. 答案 (Answer)：提出解决问题的初步方案或分析路径。\n\n输出格式要求：使用 Markdown 标题分节，每个部分至少 200 字。"
      }
    }
  ]
}
```

### 4.2 新增 Tool：`generate_search_queries`

**工具声明 (`tools/list` 追加)**

```json
{
  "name": "generate_search_queries",
  "description": "将用户的自然语言查询拆解为 3-5 个专业的学术检索词，用于后续文献检索",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "用户的原始查询语句，例如：新能源汽车电池回收技术难点"
      }
    },
    "required": ["query"]
  }
}
```

**工具调用响应 (`tools/call`)**

```json
// 请求参数
{
  "query": "新能源汽车电池回收技术难点"
}
// 响应
{
  "content": [
    {
      "type": "text",
      "text": "[\"动力电池梯次利用技术\", \"废旧锂离子电池回收工艺\", \"电池拆解自动化\", \"有价金属提取效率\", \"环保法规与回收成本\"]"
    }
  ]
}
```

### 4.3 角色矩阵与输出规范（内置于 Prompt 模板）

在每个思维框架的模板中，通过系统消息（System Prompt）注入角色定义和输出格式要求。例如在 SWOT 模板中：

```json
{
  "role": "system",
  "content": {
    "type": "text",
    "text": "你是一位资深的战略分析顾问，擅长使用 SWOT 框架进行竞争态势分析。请严格按照以下结构输出 Markdown 报告：\n# SWOT 分析报告：{entity}\n## 1. 优势 (Strengths)\n- 内部积极因素...\n## 2. 劣势 (Weaknesses)\n- 内部消极因素...\n## 3. 机会 (Opportunities)\n- 外部积极因素...\n## 4. 威胁 (Threats)\n- 外部消极因素...\n\n每个要点必须附上简要论证，报告总字数不低于 800 字。"
  }
}
```

---

## 5. 总结

Sprint 2 通过接入 MCP `Prompts` 原语，扩展了系统的多维思维框架，为大模型提供了结构化的推理模板。通过拆解用户意图，系统能够更高效地生成标准化的响应内容，推动开源协作流程的自动化与优化。随着 Sprint 2 的完成，系统将在后续迭代中逐步完善与扩展，推动开源项目管理和协作效率的提升。

---

## 许可声明

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