Files

gzkoala 3a437eb739 docs(update):更新Porject Caffeine系统开发指南文档

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

2026-03-08 19:59:30 +08:00

22 KiB

Raw Permalink Blame History

Project Caffeine系统开发指南

1. 概述与定义

在人工智能迅速发展的现代技术生态中，大语言模型（LLM）与外部数据源、计算工具以及系统工作流的集成，长期面临着被称为“N \times M 整合难题”的指数级扩展困境。如果存在 N 个独立的人工智能应用程序和 M 个不同的数据源，传统的集成方式需要构建和维护 N \times M 个定制的连接器，这不仅导致了团队间工作的大量重复，也使得安全治理和系统扩展变得异常困难。

Model Context Protocol (MCP) 的出现，正是为了解决这一根本性问题。MCP被定义为一种开源的标准协议，旨在为人工智能应用程序提供与外部系统进行安全、双向通信的通用标准化接口，其在系统架构中的角色类似于电子设备领域的“USB-C接口”。通过引入这一标准化中间层，MCP将原本复杂的指数级集成负担简化为 N + M 的线性结构。

MCP与传统的应用程序编程接口（API）以及消息队列等技术在技术机制和哲学理念上存在着本质的区别与深刻的联系：

与传统API的区别：传统的API（如RESTful接口）是为人类开发者构建的，假设调用者完全理解系统的底层逻辑。相比之下，MCP是专门为人工智能模型设计的，假设调用者是一个具备高级推理能力但不可信任的智能系统。传统API暴露静态端点，而MCP暴露具备丰富语义和严格数据类型定义的“能力”，并附带结构化的 JSON Schema 来“教导”模型如何安全使用。
与消息队列的区别：消息队列（如Kafka或RabbitMQ）主要用于解耦系统、处理单向传递与削峰填谷。MCP则是基于客户端-服务端架构的同步、上下文感知协议。MCP通过增加一层智能推理层，赋予了系统动态工具发现、上下文注入和复杂工作流编排的能力。

2. 系统需求分析

在设计和开发基于MCP的系统之前，必须对系统的功能需求、性能需求、用户体验需求以及其所处的特定应用环境进行详尽的分析与界定。核心目标是构建一个能够从简单的信息检索工具演变为具备递归推理和自主探索能力的复杂智能引擎。

功能需求：系统必须能够实现从初步查询、文档语义分块、洞察提取、质量评估到知识盲点探究的完整闭环。系统需动态发现和执行外部工具，并在本地存储标准化数据结构（如带有YAML元数据的Markdown文件），以融合个人知识管理（PKM）。
性能需求：MCP系统必须直面LLM固有的“上下文窗口限制”。系统需要通过文件系统级别的工具发现、语义分块算法以及并发限制和重试机制，实现按需加载和高效的数据截断，确保处理大规模数据时的低延迟与高吞吐量。
应用场景与用户体验：在企业级环境中，需确保信息流的跨平台互操作性和极高的安全性；在物联网或机器学习场景中，核心痛点在于上下文的持久化和跨会话记忆保持。必须提供具备“人在回路（Human-in-the-loop）”干预能力的用户体验机制。

3. 架构设计

图1-1：研报智能体 MCP 系统网络拓扑图

3.1 系统分层架构设计

系统由四个核心物理与逻辑区域组成，通过标准协议进行通信：

控制器层：promptsController、toolsController、resourcesController 接收 MCP 请求，进行参数校验（Zod），调用对应的服务模块，并格式化响应。保持薄控制器原则，业务逻辑全部下沉到服务层。
服务层：按功能拆分为 literature、prompt、cot、resource 四个子目录，每个子目录下包含该功能相关的多个服务文件。服务之间可通过导入直接调用，例如 promptService 可以调用 intentService 生成检索词，再调用 literatureService 执行检索。
模型层：集中存放 TypeScript 类型定义和 Zod Schema，包括文献格式、框架定义、工具参数等，确保类型安全并在整个项目内共享。
工具层：提供跨模块复用的工具函数，如 HTTP 客户端、YAML 生成、路径安全校验、日志等。

3.2 MCP 三大核心原语分工

系统框架严格遵循 MCP 规范，将功能划分为 Tools、Prompts 和 Resources 三大部分：

原语名称	核心职责 (Core Responsibility)	典型工具与指令示例	所属 Server 角色
Tools (工具)	动作执行者：暴露给模型的主动操作，负责与外部学术 API 通信或执行本地文件 I/O。	`search_academic_literature`, `save_to_local_vault`	S1: 执行者 (Executor)
Prompts (提示词)	策略军师：提供结构化的思维框架模板，用于指导大模型进行意图拆解与深度推理。	`5W3H`, `SCQA`, `5 Whys`, `generate_search_queries`	S2: 军师 (Strategist)
Resources (资源)	数据管家：被动的静态上下文数据源，允许模型以只读方式挂载本地知识库内容。	`vault://local_literature/`, `note://local/`	S1/S3: 数据管家/分析师

3.3原语协同逻辑要点

拓扑图展示了系统内部的协同工作流：

动态策略驱动：当用户输入模糊主题时，系统首先调用 Prompts 原语 中的 generate_search_queries 将意图降维并转化为专业检索词。
物理链路执行：大模型根据拆解后的 Query，通过 Tools 原语 调用外部 API（如 arXiv）并执行“双轨制落盘”，将 JSON 数据转化为带有 YAML 元数据的 Markdown 文件。
知识闭环构建：在递归深挖阶段，模型通过 Resources 原语 回读已保存在本地知识库中的文献卡片，确保后续的推理基于已获知的“先验知识（Learnings）”。

4. 系统工作流

图1-2：Project Caffeine MCP 系统工作流逻辑示意图

以下步骤构成了整个系统的工作流程，从用户输入研究主题开始，到生成并优化最终的深度研究报告，整个过程依靠 MCP协议 和多台 MCP Server 的协同工作，确保高效处理复杂的研究任务并生成有价值的报告。

步骤 1: 用户输入

研究人员通过 MCP客户端 向系统提交研究主题或任务指令。用户输入的研究问题可以是一个模糊的主题，系统将根据该主题进行后续处理。

步骤 2: MCP协议层传输

用户输入的研究任务通过 MCP协议层 使用 stdio 或 SSE 协议传输。这一层负责将任务请求从客户端传递到不同的 MCP Server，并确保数据格式一致。

步骤 3: 请求解析与任务分配

在 MCP协议层，请求被解析并分配给不同的子模块（MCP Server）。根据请求的类型，系统将决定任务被发送到哪一台服务器进行处理。通常包括：

文献查询MCP Server：负责从学术数据库获取相关文献。
提示词策略MCP Server：负责优化和生成检索策略。
CoT多步推理MCP Server：进行复杂的推理操作，生成深度的研究报告。

步骤 4: 任务调度与数据获取

每个 MCP Server 在接收到任务后，会开始执行与外部资源的交互。任务可以涉及以下几个方面：

文献查询MCP Server 从如 Google Scholar、PubMed、arXiv 等数据库中查询相关文献。
CoT推理MCP Server 进行推理，分析文献数据，生成相关洞察。

步骤 5: 外部资源集成

MCP Server 将通过多种外部基础设施获取和处理数据，这包括：

学术数据库：如 PubMed、arXiv 等提供的文献数据。
互联网资源：如 PDF 文件和 HTML 网页，为文献抓取和深度分析提供原始资料。
本地知识库：如 Obsidian 或 Logseq，用于存储分析和文献数据。

步骤 6: 数据存储与整理

在任务完成后，所有检索到的文献数据和生成的分析结果都将被整理并存储。数据将保存为结构化的 YAML 或 Markdown 文件，并存储在本地知识库中，便于后续查找和分析。

步骤 7: 生成深度报告

在 CoT多步推理MCP Server 完成文献数据分析和推理后，系统生成一份带有引用和结构化内容的深度研究报告。报告会采用标准化的学术格式（如摘要、引言、方法、结论等）。

步骤 8: 用户反馈与优化

用户可以对报告进行反馈，系统将根据用户的反馈进行相应的调整和优化。反馈可以包括：

对报告内容的修改建议。
对提示词或任务描述的优化建议。
系统会根据反馈调整模型的推理过程或检索策略，以改进后续任务的处理效果。

5. 开发工具链和环境配置

5.1 技术栈与工程化基础

图：1-3：Project Caffeine开发框架与技术栈架构图

层次	技术选型
核心语言	TypeScript（所有核心功能强制使用）
运行环境	Node.js LTS v20+（异步非阻塞 I/O）
协议层	MCP SDK（`@modelcontextprotocol/sdk`），支持 `stdio` 与 `SSE` 传输
包管理	npm（单体仓库，单一 `package.json`）
校验工具	Zod（运行时类型校验与参数验证）
HTTP 客户端	axios（封装学术 API 调用，支持重试与速率限制）
日志工具	winston / log4js（生产级日志记录）
测试工具	Jest + k6（单元测试与负载压测）
调试工具	VS Code 断点调试（通过 `--inspect` 挂载）

5.2 模块划分与代码组织

project-caffeine/
├── src/
│   ├── controllers/               # 请求控制器
│   │   ├── promptsController.ts    # 处理 prompts/list, prompts/get
│   │   ├── toolsController.ts      # 处理 tools/list, tools/call
│   │   └── resourcesController.ts  # 处理 resources/list, resources/read
│   ├── services/                   # 核心业务逻辑（按功能模块划分）
│   │   ├── literature/              # 文献查询模块（原 S1）
│   │   │   ├── literatureService.ts   # 学术 API 调用、聚合
│   │   │   ├── storageService.ts      # 文献转 Markdown、文件写入
│   │   │   └── index.ts
│   │   ├── prompt/                   # 提示词策略模块（原 S2）
│   │   │   ├── promptService.ts       # 框架加载、消息组装
│   │   │   ├── intentService.ts       # 意图拆解、检索词生成
│   │   │   └── index.ts
│   │   ├── cot/                       # CoT 推理模块（原 S3，规划中）
│   │   │   ├── synthesisService.ts     # 文献合成、报告生成
│   │   │   ├── qualityService.ts       # 引用校验、时效检查
│   │   │   └── index.ts
│   │   └── resource/                  # 本地资源管理（通用）
│   │       └── resourceService.ts       # 笔记列表、读取、保存
│   ├── models/                       # 数据模型与 Zod 校验
│   │   ├── schemas.ts                  # 统一校验 Schema
│   │   ├── literatureSchema.ts          # 文献 JSON 定义
│   │   └── frameworks/                  # 思维框架 JSON 定义
│   │       ├── 5w3h.json
│   │       ├── scqa.json
│   │       └── ...
│   ├── utils/                         # 通用工具函数
│   │   ├── apiClients.ts                # HTTP 客户端封装
│   │   ├── yamlHelper.ts                # YAML Frontmatter 生成
│   │   ├── pathSafety.ts                # 路径安全校验
│   │   └── logger.ts                    # 日志工具
│   └── app.ts                          # 入口文件：初始化 MCP Server，注册原语
├── config/
│   └── config.ts                        # 环境配置加载
├── .env.example                          # 环境变量示例
├── package.json                          # 项目依赖
├── tsconfig.json                         # TypeScript 配置
└── README.md                             # 项目说明

6. 系统设计补充

6.1 数据标准化

系统全面采用 JSON 格式作为基础数据承载体，并依赖 JSON-RPC 2.0 协议规范来管理消息交换。MCP规范设定了三种核心的系统原语：

工具（Tools）：允许AI应用执行具体操作（如文件读写、API调用）。服务端通过 tools/list 暴露工具元数据，包含严谨的 inputSchema。
资源（Resources）：提供被动上下文信息的数据源。通过 resources/list 发现，通过 resources/read 提取内容。
提示词（Prompts）：作为可复用的模板，帮助模型构造标准化的交互结构。通过 prompts/list 和 prompts/get 进行流转。

为保证数据兼容性，系统需对通用 JSON 进行深度扩展（如类似 JSON-LD 或结构化 BibTeX 的标准），确保输入模式和生成数据结构在底层LLM切换时保持绝对一致性。

6.2 通信协议设计

根据系统应用场景的不同，通信协议的选择主要集中在两种官方支持的标准之上：

传输协议	运行机制	安全性与效率特征	适用场景
STDIO	利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信。	零网络传输开销，不经过网卡，提供最优延迟和效率。无需复杂加密握手。	本地集成的桌面应用程序（如Claude Desktop, Cursor）及容器内部的Sidecar服务。
HTTP + SSE	客户端通过 HTTP POST 发送请求，服务端通过 Server-Sent Events 流式下发响应。	依赖 HTTPS/TLS 保障安全，支持标准 Token 认证。效率依赖网络带宽与延迟优化。	云端部署的远程MCP服务端、微服务架构及跨物理机器访问的连接器。

所有通信均封装在 JSON-RPC 2.0 信封内，通过初始化握手（initialize）进行双向的能力协商，并支持动态状态更新（如 notifications/tools/list_changed）。

6.3 上下文管理机制

构建科学的上下文管理机制是MCP系统设计的核心要务，以应对大模型的上下文窗口限制。

生命周期管理：连接瞬间注入环境配置；多轮调用中动态更新；任务完成时显式终止销毁，防止内存泄漏。
LRU 缓存策略：对于高频读写的中间结果，采用最近最少使用缓存策略。结合哈希映射（保证查找时间复杂度为 $\mathcal{O}(1)$）和双向链表（管理生命周期与数据逐出）。
语义分块（Semantic Chunking）：对于长篇文档，服务端在本地完成文本解析与向量切割，仅将统计学上高度相关的片段异步同步给客户端，避免 Token 极度消耗。

6.4 安全性和权限管理

协议遵循零信任架构原则，默认将AI生成的指令视为不可信负载。

加密与验证：远程连接强制 HTTPS/TLS 1.2+。官方推荐基于 OAuth 2.1 的授权流，并采用如 mcp:read_database 形式的作用域限定防止令牌滥用。
Roots（根目录）机制：从系统底层阻断越权访问和路径遍历漏洞。由宿主应用在初始化时传递明确的 URI 列表划定“活动沙箱”。服务端目录访问控制系统会依据 Roots 边界直接拒绝越权请求。

6.5性能优化和可扩展性

处理效率：MCP服务端必须引入全面的异步处理模型（如 asyncio 或 Node.js 非阻塞事件流），结合代理层 LRU 缓存拦截重复请求。
网络传输：利用 MCP JSON-RPC 协议中原生的数组分片流式返回能力，将长文本数据切片持续推送，降低首字节时间（TTFB）。
架构扩展：引入负载均衡与水平扩展技术。云端部署可采用 Docker + Kubernetes (HPA)。针对海量异构数据，应部署独立域的多个无状态MCP服务端并结合聚合网关进行调度。

6.6 系统维护和更新

版本控制策略：当服务端发生破坏性更新时，应当在 tools/list 响应中并行提供新旧两套 Schema，直至宿主模型的 Prompt 被完全升级。
热部署（Hot Deployment）：协议原生支持热更新。服务端逻辑变动时可发送 list_changed 通知，客户端会在后台透明重新拉取最新状态。
容错和恢复：建立异常捕获与重试机制。利用本地轻量级数据库（如SQLite）作为事务日志，在崩溃恢复后回放状态。

6.7 系统部署与运维

部署方式：Docker 容器是封装事实标准。可结合标准化 AI 伪制品清单格式（如 ara.json）实现公有云自动化编排与部署。
可观测性：部署 Prometheus + Grafana 进行系统指标监控。引入专门针对大模型和 MCP 工具监控的分析平台（如 Agnost AI）深度剖析调用频次与失败率。
日志管理：使用 ELK 协议栈收集 JSON-RPC 往来报文，用于追踪错误栈、发现模型幻觉及优化提示词。

7. 调试与测试

7.1 调试配置

单体架构下调试更加简便：

在 VS Code 中配置 launch.json，直接启动 src/app.ts，并附加 --inspect 参数，即可实现源码级断点。
由于所有代码在一个进程中，可以统一设置断点，无需跨服务追踪。
调试日志统一输出到 stderr（通过 console.error 或日志库），避免干扰 MCP 的 stdout 通信。

7.2 测试策略

测试层级	测试框架与工具推荐	核心目标与执行策略
单元测试	Mocha, Chai, PyTest, Jest	脱离LLM环境，确保模块独立功能绝对正确（覆盖率>80%），验证是否能正确拒绝非法输入。
集成测试	MCP Inspector, mcpjam	测试协议合规性。模拟握手与协商，通过浏览器 UI 手动验证或自动化集成交互测试。
性能测试	k6 Load Testing	评估高并发请求下的生存能力，验证 P99 响应时间及内存泄漏监控。
安全与调试	Chrome DevTools, OWASP	实施 SQL/命令注入及路径遍历安全审计。提供内存检查与日志调试功能定位异常。

详见Project Caffeine 项目代码测试规范指南

8. 部署与运行

8.1 本地部署

git clone <repository>
cd project-caffeine
npm install
cp .env.example .env   # 编辑配置文件，填入 API 密钥和本地知识库路径
npm run build          # 编译 TypeScript

在支持 MCP 的客户端（如 Cherry Studio）中导入以下json配置：

{
  "mcpServers": {
    "Project Caffeine": {
      "isActive": true,
      "name": "Project Caffeine",
      "type": "stdio",
      "description": "",
      "baseUrl": "",
      "command": "node",
      "args": [
        "--inspect=9229",
        "/home/wguo/Downloads/Project-Caffeine/projects/arabica/sprint2/dist/app.js"
      ],
      "env": {}
    }
  }
}

app.ts文件需要根据每版本输入完整的绝对路径

8.2 远程部署（SSE 模式）

若需部署为远程服务，可在 app.ts 中增加对 SSE 传输的支持，通过环境变量切换传输方式。部署时需配置反向代理（如 Nginx）和负载均衡，并确保安全认证（如 JWT）。

9. 编码规范与文档规范

9.1 编码规范

命名：变量/函数使用 camelCase，类/接口使用 PascalCase，常量使用 UPPER_SNAKE_CASE，文件/目录使用 kebab-case。
缩进：2 个空格，禁止 Tab。
注释：所有模块、类、复杂函数必须使用 JSDoc 注释。
类型：优先使用 TypeScript 严格模式，所有 API 输入输出均需 Zod 校验。
错误处理：服务层抛出具体错误，控制器捕获后返回标准 MCP 错误响应（包含 isError: true）。
安全：文件操作必须进行路径遍历校验（使用 path.resolve + 检查前缀，或 path.relative 验证）。

详见 Project Caffeine 代码编写规范指南

9.2 文档规范

YAML Frontmatter：所有 Markdown 文档顶部必须包含元数据（标题、描述、版本、作者、日期、标签、许可证）。
文档类型：README、设计文档、开发指南、用户指南、API 文档、更新日志等分类存放于 docs/ 目录。
图表：核心架构图必须使用可 diff 的 SVG（嵌入 Markdown），并添加纯白背景防止深色模式反色。
写作风格：中立客观，避免翻译腔，使用主动语态，段落首句为中心句。

详见Project Caffeine文档编写规范指南

22 KiB Raw Permalink Blame History Unescape Escape