docs(add):新增Arabica Sprint2 系统组件架构设计说明文档
Signed-off-by: gzkoala <guohao@gitconomy.org>
This commit is contained in:
gzkoala
@@ -0,0 +1,278 @@
|
||||
---
|
||||
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-1：Sprint 2 组件架构与数据流*
|
||||
|
||||
|
||||
|
||||
架构图中的核心数据链路包含以下四个关键环节：
|
||||
|
||||
- **发起框架请求**：客户端（如 Cherry Studio）接收用户的自然语言查询后，大语言模型会自主决策并向服务端发起 `prompts/get` 请求，以获取最匹配的静态思维框架模板（例如 SCQA 框架）。
|
||||
- **分发提示词模板**：服务端的 `promptsController.js` 负责接收请求，并通过更新后的 `promptService.js` 从新增的 `src/models/frameworks/` 目录中加载对应的框架 JSON 定义，将其作为增强提示词下发给客户端。
|
||||
- **执行意图拆解**：大模型在进行初步推理时，可通过调用新增的 `generate_search_queries` 工具来深化研究广度。此时，`toolsController.js` 会将请求路由分发至专属的 `intentService.js`，由该服务将用户的原始模糊查询精准拆解为 3-5 个专业检索词。
|
||||
- **约束结构化输出**：系统通过在提示词模板的系统消息（System Prompt）中注入多智能体角色矩阵雏形与少样本（Few-Shot）示例，强制约束大模型结合生成的检索词与分析框架，最终输出符合标准规范的深度 Markdown 报告。
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user