From 7b664bb8368c09673129cf510126a3e7a6e89484 Mon Sep 17 00:00:00 2001 From: gzkoala Date: Sun, 8 Mar 2026 19:37:49 +0800 Subject: [PATCH] =?UTF-8?q?docs(update):=E6=9B=B4=E6=96=B0Porject=20Caffei?= =?UTF-8?q?ne=E7=B3=BB=E7=BB=9F=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: gzkoala --- ...ct-caffeine-development-framework-guide.md | 387 +++++++++++------- ...ffeine-code-testing-specification-guide.md | 0 ...ct-caffeine-coding-specification-guide.md} | 4 +- ...feine-documentation-specification-guide.md | 219 ++++++++++ ...t-caffeine-version-name-convetion-guide.md | 0 5 files changed, 470 insertions(+), 140 deletions(-) rename docs/{guide => guides}/project-caffeine-code-testing-specification-guide.md (100%) rename docs/{guide/project-caffeine-coding-specification-guidelines.md => guides/project-caffeine-coding-specification-guide.md} (98%) create mode 100644 docs/guides/project-caffeine-documentation-specification-guide.md rename docs/{guide => guides}/project-caffeine-version-name-convetion-guide.md (100%) diff --git a/docs/design/project-caffeine-development-framework-guide.md b/docs/design/project-caffeine-development-framework-guide.md index f01d8cc..566183f 100644 --- a/docs/design/project-caffeine-development-framework-guide.md +++ b/docs/design/project-caffeine-development-framework-guide.md @@ -1,12 +1,14 @@ # Project Caffeine系统开发指南 @@ -52,142 +54,38 @@ MCP与传统的应用程序编程接口（API）以及消息队列等技术在 ![系统网络拓扑图](./../assets/images/figure01-mcp-system-topology.svg) -MCP的系统总体架构采用严格分层的客户端-服务端（Client-Server）模型，旨在实现传输机制与数据处理逻辑的彻底解耦。该架构由三大核心组件构成： +### 3.1 系统分层架构设计 -1. **宿主应用程序（Host Application）**：直接与用户交互并承载大语言模型的环境（如Claude Desktop、Cursor IDE等）。 +系统由四个核心物理与逻辑区域组成，通过标准协议进行通信： -2. **MCP客户端（MCP Client）**：无缝嵌入在宿主应用程序中，负责维持与外部服务端的连接，执行能力协商，并将宿主的意图翻译为符合MCP规范的协议消息。 +- **控制器层**：`promptsController`、`toolsController`、`resourcesController` 接收 MCP 请求，进行参数校验（Zod），调用对应的服务模块，并格式化响应。保持薄控制器原则，业务逻辑全部下沉到服务层。 +- **服务层**：按功能拆分为 `literature`、`prompt`、`cot`、`resource` 四个子目录，每个子目录下包含该功能相关的多个服务文件。服务之间可通过导入直接调用，例如 `promptService` 可以调用 `intentService` 生成检索词，再调用 `literatureService` 执行检索。 +- **模型层**：集中存放 TypeScript 类型定义和 Zod Schema，包括文献格式、框架定义、工具参数等，确保类型安全并在整个项目内共享。 +- **工具层**：提供跨模块复用的工具函数，如 HTTP 客户端、YAML 生成、路径安全校验、日志等。 -3. **MCP服务端（MCP Server）**：轻量级的外部程序，专门负责连接特定的数据源或执行特定的计算任务，通过标准接口向AI应用暴露上下文和工具。 +### 3.2 MCP 三大核心原语分工 +系统框架严格遵循 MCP 规范，将功能划分为 Tools、Prompts 和 Resources 三大部分： -**数据流管理**：用户发起请求 $\rightarrow$ AI模型推理决定调用外部能力 $\rightarrow$ MCP客户端打包 JSON-RPC 请求 $\rightarrow$ MCP服务端执行逻辑并返回标准 JSON 结构 $\rightarrow$ 客户端将上下文注入模型 $\rightarrow$ 模型生成最终响应。 - ---- - -## 4. 数据标准化 - -系统全面采用 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切换时保持绝对一致性。 - ---- - -## 5. 模型定义与行为规范 - -在复杂的智能体架构中，模型的行为必须遵循预设的结构与功能规范。 - -- **结构与功能定义**：系统通常通过“提示词策略服务端”注入静态思维框架（如SWOT分析、思维链CoT推理），强制模型按照标准逻辑结构进行逐步推理。可加入学术质量控制逻辑（如强制引文密度验证）。 - -- **采样（Sampling）机制**：MCP引入的反向调用机制。允许服务端主动请求LLM的推理能力来指导后续操作（如调用 `sampling/createMessage`）。任何涉及采样的递归行为都必须受到严格管控，并在应用层确保人在回路的二次确认机制。 - ---- - -## 6. 通信协议设计 - -根据系统应用场景的不同，通信协议的选择主要集中在两种官方支持的标准之上： - -|**传输协议**|**运行机制**|**安全性与效率特征**|**适用场景**| +|**原语名称**|**核心职责 (Core Responsibility)**|**典型工具与指令示例**|**所属 Server 角色**| |---|---|---|---| -|**STDIO**|利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信。|零网络传输开销，不经过网卡，提供最优延迟和效率。无需复杂加密握手。|本地集成的桌面应用程序（如Claude Desktop, Cursor）及容器内部的Sidecar服务。| -|**HTTP + SSE**|客户端通过 HTTP POST 发送请求，服务端通过 Server-Sent Events 流式下发响应。|依赖 HTTPS/TLS 保障安全，支持标准 Token 认证。效率依赖网络带宽与延迟优化。|云端部署的远程MCP服务端、微服务架构及跨物理机器访问的连接器。| +|**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: 数据管家/分析师**| -所有通信均封装在 JSON-RPC 2.0 信封内，通过初始化握手（`initialize`）进行双向的能力协商，并支持动态状态更新（如 `notifications/tools/list_changed`）。 +### 3.3原语协同逻辑要点 + +拓扑图展示了系统内部的协同工作流： + +1. **动态策略驱动**：当用户输入模糊主题时，系统首先调用 **Prompts 原语** 中的 `generate_search_queries` 将意图降维并转化为专业检索词。 +2. **物理链路执行**：大模型根据拆解后的 Query，通过 **Tools 原语** 调用外部 API（如 arXiv）并执行“双轨制落盘”，将 JSON 数据转化为带有 YAML 元数据的 Markdown 文件。 +3. **知识闭环构建**：在递归深挖阶段，模型通过 **Resources 原语** 回读已保存在本地知识库中的文献卡片，确保后续的推理基于已获知的“先验知识（Learnings）”。 --- -## 7. 上下文管理机制 +## 4. 系统工作流 -构建科学的上下文管理机制是MCP系统设计的核心要务，以应对大模型的上下文窗口限制。 - -- **生命周期管理**：连接瞬间注入环境配置；多轮调用中动态更新；任务完成时显式终止销毁，防止内存泄漏。 - -- **LRU 缓存策略**：对于高频读写的中间结果，采用最近最少使用缓存策略。结合**哈希映射**（保证查找时间复杂度为 $\mathcal{O}(1)$）和**双向链表**（管理生命周期与数据逐出）。 - -- **语义分块（Semantic Chunking）**：对于长篇文档，服务端在本地完成文本解析与向量切割，仅将统计学上高度相关的片段异步同步给客户端，避免 Token 极度消耗。 - ---- - -## 8. 安全性和权限管理 - -协议遵循**零信任架构原则**，默认将AI生成的指令视为不可信负载。 - -- **加密与验证**：远程连接强制 HTTPS/TLS 1.2+。官方推荐基于 **OAuth 2.1** 的授权流，并采用如 `mcp:read_database` 形式的作用域限定防止令牌滥用。 - -- **Roots（根目录）机制**：从系统底层阻断越权访问和路径遍历漏洞。由宿主应用在初始化时传递明确的 URI 列表划定“活动沙箱”。服务端目录访问控制系统会依据 Roots 边界直接拒绝越权请求。 - ---- - -## 9. 性能优化和可扩展性 - -- **处理效率**：MCP服务端必须引入全面的异步处理模型（如 asyncio 或 Node.js 非阻塞事件流），结合代理层 LRU 缓存拦截重复请求。 - -- **网络传输**：利用 MCP JSON-RPC 协议中原生的数组分片流式返回能力，将长文本数据切片持续推送，降低首字节时间（TTFB）。 - -- **架构扩展**：引入负载均衡与水平扩展技术。云端部署可采用 Docker + Kubernetes (HPA)。针对海量异构数据，应部署独立域的多个无状态MCP服务端并结合聚合网关进行调度。 - ---- - -## 10. 系统维护和更新 - -- **版本控制策略**：当服务端发生破坏性更新时，应当在 `tools/list` 响应中并行提供新旧两套 Schema，直至宿主模型的 Prompt 被完全升级。 - -- **热部署（Hot Deployment）**：协议原生支持热更新。服务端逻辑变动时可发送 `list_changed` 通知，客户端会在后台透明重新拉取最新状态。 - -- **容错和恢复**：建立异常捕获与重试机制。利用本地轻量级数据库（如SQLite）作为事务日志，在崩溃恢复后回放状态。 - ---- - -## 11. 系统部署与运维 - -- **部署方式**：Docker 容器是封装事实标准。可结合标准化 AI 伪制品清单格式（如 `ara.json`）实现公有云自动化编排与部署。 - -- **可观测性**：部署 Prometheus + Grafana 进行系统指标监控。引入专门针对大模型和 MCP 工具监控的分析平台（如 Agnost AI）深度剖析调用频次与失败率。 - -- **日志管理**：使用 ELK 协议栈收集 JSON-RPC 往来报文，用于追踪错误栈、发现模型幻觉及优化提示词。 - ---- - -## 12. 开发工具链和环境配置 - -*图：1-2：Project Caffeine开发框架与技术栈架构图* - -![系统技术架构图](./../assets/images/figure02-mcp-tech-stack-framework.svg) - -为确保系统的高并发处理能力与协议严谨性，Project Caffeine 采用以下核心开发框架与技术标准： - -* **核心语言与运行环境**：采用 TypeScript 与 Node.js (LTS v20+)。MCP服务端必须引入全面的异步处理模型（如 Node.js 非阻塞事件流）以应对高吞吐量的数据解析。 -* **MCP 协议与 SDK**：统一使用官方针对 TypeScript 提供的标准 SDK，深度封装底层 JSON-RPC 2.0 报文解析与状态机管理。 -* **工程化与 Monorepo**：采用原生 npm Workspaces 进行包管理，在根目录统一管控共享的 JSON-RPC Schema 与多个微服务子包，实现依赖隔离与跨服务快速编译。 -* **通信传输层 (MVP 阶段)**：采用 STDIO 协议，利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信，无需复杂加密握手，实现零网络传输开销。 -* **集成开发环境 (IDE)**：采用 Visual Studio Code (VS Code) 作为核心开发工具。需配合安装相关的 MCP 扩展插件，支持在编写代码时直接进行对话联调与协议协议测试。 -* **安全与环境管控**：协议遵循零信任架构原则，默认将AI生成的指令视为不可信负载。敏感凭证严禁硬编码，必须通过 `.env.example` 模板化并在运行环境中安全注入。 - ---- - -## 13. 测试与调试 - -绝不能仅停留在“感觉测试（Vibe-Testing）”层面，必须实施严密的自动化分级测试体系： - -|**测试层级**|**测试框架与工具推荐**|**核心目标与执行策略**| -|---|---|---| -|**单元测试**|Mocha, Chai, PyTest, Jest|脱离LLM环境，确保模块独立功能绝对正确（覆盖率>80%），验证是否能正确拒绝非法输入。| -|**集成测试**|MCP Inspector, mcpjam|测试协议合规性。模拟握手与协商，通过浏览器 UI 手动验证或自动化集成交互测试。| -|**性能测试**|k6 Load Testing|评估高并发请求下的生存能力，验证 P99 响应时间及内存泄漏监控。| -|**安全与调试**|Chrome DevTools, OWASP|实施 SQL/命令注入及路径遍历安全审计。提供内存检查与日志调试功能定位异常。| - ---- - -## 14. 系统工作流 - -*图1-3：Project Caffeine MCP 系统工作流逻辑示意图* +*图1-2：Project Caffeine MCP 系统工作流逻辑示意图* ![MCP工作流程图](./../assets/images/figure03-mcp-logic-architecture.svg) @@ -240,17 +138,230 @@ MCP的系统总体架构采用严格分层的客户端-服务端（Client-Server - 对提示词或任务描述的优化建议。 系统会根据反馈调整模型的推理过程或检索策略，以改进后续任务的处理效果。 + --- -## 15. 文档与支持 +## 5. 开发工具链和环境配置 -优秀的MCP系统配备多维度文档： +### 5.1 技术栈与工程化基础 -- **开发者文档**：架构图、API契约、安装配置指南及常见问题解答（FAQ）。 +*图：1-3：Project Caffeine开发框架与技术栈架构图* -- **AI 模型文档**：`tools/list` 响应中的 `description` 字段必须经过精细的提示词工程打磨，消除歧义。利用 `prompts/list` 暴露预置最佳实践，提供少样本（Few-shot）学习参考。 +![系统技术架构图](./../assets/images/figure02-mcp-tech-stack-framework.svg) + +| 层次 | 技术选型 | +| ------------ | ---------------------------------------------------------- | +| **核心语言** | 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 项目代码测试规范指南](./../guides/project-caffeine-code-testing-specification-guide.md)_ + +--- + +## 8. 部署与运行 + +### 8.1 本地部署 + +```bash +git clone +cd project-caffeine +npm install +cp .env.example .env # 编辑配置文件，填入 API 密钥和本地知识库路径 +npm run build # 编译 TypeScript +``` + +在支持 MCP 的客户端（如 Cherry Studio）中导入以下json配置： + +```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 代码编写规范指南](./../guides/project-caffeine-coding-specification-guide.md)_ + +### 9.2 文档规范 + +- **YAML Frontmatter**：所有 Markdown 文档顶部必须包含元数据（标题、描述、版本、作者、日期、标签、许可证）。 +- **文档类型**：README、设计文档、开发指南、用户指南、API 文档、更新日志等分类存放于 `docs/` 目录。 +- **图表**：核心架构图必须使用可 diff 的 SVG（嵌入 Markdown），并添加纯白背景防止深色模式反色。 +- **写作风格**：中立客观，避免翻译腔，使用主动语态，段落首句为中心句。 + +_详见[Project Caffeine文档编写规范指南](./../guides/project-caffeine-documentation-specification-guide.md)_ -- **社区支持**：建立 Git 仓库、论坛及 Wiki，共享复杂实现方案并组织可用性培训。 --- diff --git a/docs/guide/project-caffeine-code-testing-specification-guide.md b/docs/guides/project-caffeine-code-testing-specification-guide.md similarity index 100% rename from docs/guide/project-caffeine-code-testing-specification-guide.md rename to docs/guides/project-caffeine-code-testing-specification-guide.md diff --git a/docs/guide/project-caffeine-coding-specification-guidelines.md b/docs/guides/project-caffeine-coding-specification-guide.md similarity index 98% rename from docs/guide/project-caffeine-coding-specification-guidelines.md rename to docs/guides/project-caffeine-coding-specification-guide.md index 6aef4e4..37dc9c4 100644 --- a/docs/guide/project-caffeine-coding-specification-guidelines.md +++ b/docs/guides/project-caffeine-coding-specification-guide.md @@ -3,8 +3,8 @@ title: "Project Caffeine 代码编写规范指南" description: "为 Project Caffeine 项目开发人员提供一致的编码风格、系统架构指引和最佳实践的规范文档" type: "Guide" -version: "v0.1.0" -file: project-caffeine-coding-specification-guidelines.md +version: "v1.0.0" +file: project-caffeine-coding-specification-guide.md author: "Gitconomy Research-郭晧" date: 2026-03-02 tags: diff --git a/docs/guides/project-caffeine-documentation-specification-guide.md b/docs/guides/project-caffeine-documentation-specification-guide.md new file mode 100644 index 0000000..5e6db26 --- /dev/null +++ b/docs/guides/project-caffeine-documentation-specification-guide.md @@ -0,0 +1,219 @@ +# Project Caffeine 文档编写规范指南 + +## 1. 目的与概述 + +本文档编写规范旨在为 **Project Caffeine** 项目的全体成员提供统一的文档撰写标准。通过标准化的元数据管理、文档结构梳理、Markdown 排版、技术写作规范以及版本控制，确保所有输出的工程文档、架构设计与迭代规划具备高度的可读性、一致性与可追溯性。 + +## 2. 文档头部元数据规范 (YAML Frontmatter) + +结合本项目的工程化管理要求，**所有 Markdown 文档的最顶部必须包含标准化的 YAML Frontmatter 元数据块**，以便于文档站点的解析、版本检索与资产归档。 + +必须包含以下核心字段： + +- **`title`**：文档的正式标题。 +- **`description`**：用 1-2 句话高度概括文档的核心主旨与意图。 +- **`type`**：文档的类型界定（如 `README`, `System Development Guide`, `Roadmap` 等）。 +- **`version`**：严格遵循“版本号 + 咖啡代号 + 里程碑”格式（例如 `v1.0.0 (Arabica) - MVP` 或 `Sprint 1`）。 +- **file**：文件名 +- **`author`**：统一署名为 **Gitconomy Research**。 +- **`date`**：遵循 `YYYY-MM-DD` 的 ISO 标准格式。 +- **`tags`**：提取核心技术栈与概念标签（如 `Project Caffeine`, `MCP`, `Deep Research` 等）。 +- **`license`**：声明为 `CC BY-SA 4.0`。 +- **`status`**：（可选）标注文档的生命周期状态（如 `Active`, `Design and Planning` 等）。 + +## 3. 文档类型与结构建议 + +为了确保各类工程文档的逻辑完整性与结构一致性，项目内的核心文档应当遵循以下分类及标准结构框架进行编写： + +### 3.1 文档类型与用途 + +项目文档按用途分为以下几类，主要存放于仓库的 `docs/` 目录下： + +|类型|说明|示例路径| +|:--|:--|:--| +|**README**|项目总体介绍、快速开始、核心特性、状态徽章等。每个主要模块/子包应有自己的 README。|`/README.md` `/packages/server/README.md`| +|**设计文档**|记录架构决策、模块设计、协议交互、数据流等，用于指导开发和评审。|`/docs/design/`| +|**开发指南**|面向开发者的环境搭建、编码规范、测试指南、调试技巧等。|`/docs/development/`| +|**用户指南**|面向最终用户的使用说明、配置示例、FAQ 等。|`/docs/user/`| +|**API 文档**|MCP 服务暴露的 tools（工具）、prompts（提示词）、resources（资源）的详细说明，包括 JSON-RPC 参数、返回值、示例。|`/docs/api/`| +|**贡献指南**|如何提交 Issue、PR，代码规范，文档规范，行为准则等。|`/CONTRIBUTING.md`| +|**更新日志**|记录版本变更，遵循 Keep a Changelog 格式。|`/CHANGELOG.md`| + +> **注意**：每个文档顶部必须包含标准化的 YAML front matter（详见第 2 节），以便机器读取元数据。 + +### 3.2 README 主文档 + +README 是项目或子包的门面，必须清晰传达项目的核心定位与接入方式，包含以下标准模块： + +- **项目标题与徽章**：显示构建状态、协议、核心技术栈及目标版本。 +- **项目概述**：简述项目功能、核心价值与适用场景。 +- **系统架构**：放置核心的架构图或拓扑图，概述系统组件及其职责。 +- **技术栈与开发环境**： + - 核心语言与运行环境（要求使用 TypeScript 与 Node.js LTS v20+）。 + - 依赖管理（明确标明是否采用 Monorepo / 原生 npm Workspaces）。 + - 协议与 SDK 说明（如 MCP 协议与 JSON-RPC 2.0 标准规范）。 + - 安全与环境要求（如配置隔离与“零信任架构原则”）。 +- **开发路线图**：按 MVP 或 Sprint 分阶段展示任务、目标及关键功能（如 Arabica Sprint 1 阶段特性）。 +- **参与方式**：Issue 提交规范、PR 流程以及讨论参与指引。 +- **AI 生成内容声明**：明确提示用户系统生成的报告需人工核验，仅供参考。 +- **许可证说明**：明确采用双轨制许可，即源代码通常采用 **MIT License**，而文档与研究成果采用 **CC BY-SA 4.0** 协议。 + +### 3.3 设计文档 + +用于详细阐述某一具体微服务或核心逻辑（如提示词策略 Server、资源读取模块），必须包含： + +- **文档标题与版本信息**。 +- **模块概述**：说明该模块的具体功能、作用及与其他系统组件的交互关系。 +- **系统架构图/流程图**：直观展示数据与控制流向。 +- **接口定义与通信协议**：如 stdio 或 HTTP+SSE 的传输层约定。 +- **数据结构与格式**：如基于 **JSON-RPC 2.0** 的 schema 定义与验证规则。 +- **核心算法或逻辑描述**：如针对长文本的语义分块（Semantic Chunking）策略或缓存机制。 +- **配置示例与部署说明**：指引如何修改环境路径与启动系统。 +- **注意事项与最佳实践**：如代码防范越权访问、性能优化红线等。 + +### 3.4 图表与示意图 + +文档中的视觉资产需遵循以下存放与引用规范： + +- **格式要求**：首选使用原生 **SVG** 代码，在特定场景下可使用高分辨率 **PNG**。若采用 SVG，必须支持通过 Git 进行 diff 比对。 +- **命名与文件夹组织**：图表文件必须存放在规定的资源目录中，遵循 `docs/assets/images/<模块名称>-<内容>.svg` 或对应的后缀格式。 + - _示例_：`docs/assets/images/project-caffeine-system-topology.svg`。 +- **图文对应**：所有图表下方必须配备简短的说明（Caption），确保图表与其解释的上下文内容紧密对应。 + +## 4. 结构与格式 + +我们使用标准的 Markdown 进行编写。 + +### 4.1 文件命名 + +文档文件命名推荐使用清晰的中文标题或英文 **kebab-case（短横线命名法）**，如 `project-caffeine-readme.md`，以保持与工程代码文件目录的命名风格统一。 + +### 4.2 章节标题的结构 + +- 使用 ATX 风格的标题（`#`）。 +- 文档主标题使用 H1（`#`），章节标题从 H2（`##`）开始。 +- 标题应简洁明了，采用**句首大写 (Sentence case)**，除非是专有名词。 + +### 4.3 章节标题的语法规范 + +#### H1: 主标题——副标题 + +1. **结构**：**主标题 + 副标题** +2. **要求**：主标题是文章或章节的核心主题，副标题进一步解释或细化主标题，提供更多上下文或具体内容。主副标题之间可以使用破折号连接。 + +#### H2: 定语 + 助词 + 名词 + +1. **结构**：**定语 + 助词 + 名词** +2. **要求**：H2标题通常作为章节标题，简洁地描述章节的核心内容。使用定语修饰名词，使标题具有具体性和引导性，助词（如“的”）连接定语与名词。 + +#### H3和H4: 谓语 + 宾语 + +1. **结构**：**谓语 + 宾语** +2. **要求**：H3和H4标题通常用于小节或细节部分，强调动作（谓语）和受动者（宾语）。这种结构使得标题更加具体，直接描述某个操作、过程或事件。 + +### 4.4 列表 (Lists) + +- **无序列表**：使用减号 `-`。列表项如果是一句完整的话，以句号结尾；如果是短语，则不需要。 +- **有序列表**：仅在步骤有严格顺序时使用数字列表。 + +### 4.5 表格 + +- 使用标准Markdown表格语法。 +- 表格前后留一空行。 +- 表头与内容之间必须有分隔行。 +- 尽量保持列对齐以提高可读性。 + +### 4.6 链接与图片 + +- 使用相对路径引用仓库内图片。 +- 外部链接应提供完整URL，包括https://前缀。 +- 提供清晰的alt 文本，兼顾无障碍与 LLM 理解。 + +### 4.7 强调 + +- **粗体 (`text`)**：用于强调关键概念、新的术语定义或需要用户特别注意的UI元素。**不要滥用**，满篇粗体等于没有重点。 +- _斜体 (`*text*`)_：用于书籍、文章标题，或表示语气的强调。 +- `行内代码 (Inline Code)`：用于正文中的命令、文件名、分支名、路径或配置项。 + +## 5. 技术写作规范 + +这是体现专业性的核心区域。 + +### 5.1 代码块 (Code Blocks) + +所有代码块必须指定语言标记，以便正确高亮。 + +- **命令行操作**：使用 `bash` 或 `sh`。 + - 命令的输出结果**不**带 `$` 符号。 + - 需要用户替换的部分使用尖括号 `` 包裹。 +- **配置文件**：使用 `gitconfig`、`yaml`、`json` 等对应格式。 +- **文件内容示例**：如果只是展示文本内容，可以使用 `text`。 + +### 5.2 标点符号 + +- 使用全角中文标点符号（，。！？：；“”‘’（））。 +- 中英文混排时，英文与中文之间应保留一个空格（此项通常由排版引擎自动处理，但在 Markdown 源码中手动添加可以提高可读性）。 + +## 6. 文字风格规范指南 + +### 6.1 文字的情绪化与中立性 + +在编写文档时，我们应避免使用情绪化或带有政治色彩的语言。这不仅是为了确保技术的客观性，也是为了尊重读者的多元背景和文化视角。以下是一些具体的规范： + +1. **避免带有攻击性或情绪化的语言**：我们的目标是帮助读者理解技术，而非通过情绪化的语言来引导思维。避免过于夸张、激烈的表述。 +2. **避免政治性语言和隐含的偏见**：在技术文档中，避免任何可能引发争议的政治色彩和社会偏见。 +3. **避免过于主观或过度的情感表达**：文档应该以冷静、客观的语气提供信息，而不是通过情感化的语言来影响读者的判断。 +4. **简洁明了，避免冗长和情绪化的描述**：避免描述性语言过于冗长或情感化的调调。尽量做到简洁直接，保持专业性。 + +### 6.2 专业性和清晰度 + +1. **保持语气的中立性**：所有表达应当中立、平衡，避免偏袒或倾向某一方的语气。专业的写作风格是直接、简洁和清晰的，不带有个人情绪色彩。 +2. **使用简洁明了的句式**：使用清晰的句式，避免过于复杂的结构。尽量使每个句子都传达一个清晰的想法，避免无谓的修饰和修辞手法。 + +### 6.3 拒绝“翻译腔” + +这是我们文字风格的第一大敌。我们在编写或翻译内容时，必须符合中文的自然表达习惯。 + +1. **减少“被”字句**：英文习惯用被动语态，而中文习惯用主动语态。 +2. **警惕“的”字风暴**：过多的“的”字会让句子变得粘连、拖沓。尝试通过重组句子来消除不必要的“的”。 +3. **避免生硬的从句**：不要试图在一个长句中保留英文的所有修饰成分。将长句拆分为短句，符合中文的“流水句”特征。 + +### 6.4 词汇的选择 + +1. **动词的力量**：使用精准、有力的动词，避免使用“进行”、“作出了”等万能动词。 +2. **术语的“中文本地化”**：除非是专有名词（如 Rebase, Cherry-pick 这种很难翻译传神的），否则尽量使用标准的中文术语，但要标注英文原词。 + - **首次出现**：暂存区 (Staging Area) + - **后续使用**：暂存区 + +### 6.5 中英文混排与标点符号 + +1. **空格规范**：**汉字与英文、汉字与数字之间，必须保留一个空格。** +2. **标点符号**： + - **全角标点**：中文句子中，必须使用全角标点（，。！？：；（））。 + - **英文标点**：只有在行内代码（Inline Code）或英文专业术语（如 `user.name`）中才使用半角标点。 + - **空格禁忌**：全角标点与汉字或英文之间，**不需要**添加空格。 + +### 6.6 标题与段落 + +1. **标题即论点**：标题不应只是名词，最好是动宾结构或完整的论点，让读者只看目录就能懂大意。 +2. **倒金字塔结构**：段落的第一句必须是**中心句 (Topic Sentence)**。先说结论，再展开解释，最后给例子。不要让读者读到最后一行才知道这一段想说什么。 + +## 7. 图形即代码 (Diagram as Code) 集成规范 + +文档中嵌入的架构图、时序图等图形资产，必须严格遵循《图形即代码设计规范指南》： + +- **格式要求**：所有核心图表必须是可内嵌于 Markdown 的原生 **SVG** 代码，并支持通过 Git 进行 diff 比对与历史追溯。 +- **兼容性与背景**：为防止 Git 平台深色模式下的反色问题与 XSS 清洗，**推荐在 SVG 最底层放置纯白背景**（``），且**严禁包含 `