<!--
---
title: Project Caffeine - Arabica Sprint2 QuickStart
description: Project Caffeine Arabica Sprint2 的快速启动指南，涵盖基于 MCP stdio 架构的多维思维框架引擎、意图拆解工具、本地知识库集成及 Cherry Studio 客户端联调全流程。
version: 1.0.0
author: Gitconomy Research 郭晧
date: 2026-03-06
type: README / QuickStart
tags:
  - Project Caffeine
  - MCP
  - stdio
  - Obsidian
  - Prompts
  - Tools
  - Resources
  - Cherry Studio
license: CC BY-SA 4.0
---
-->
# Project Caffeine - Arabica Sprint2 QuickStart

## 1. Sprint2 `0.0.2` 版本核心特性

- **多维思维框架引擎**：从单一工具扩展为完整的 Prompts 原语支持，内置 **SCQA、5Whys、5W3H、SWOT、PESTLE** 六大经典思维框架。每个框架均包含角色化系统提示、参数模板及 Few-Shot 示例，强制约束大模型的思考路径，输出高质量结构化分析。

- **意图拆解工具**：新增 `generate_search_queries` 工具，将用户自然语言查询自动拆解为 3～5 个专业检索词，支持后续联网搜索或知识库检索，提升信息获取精度。

- **本地知识库无缝接入**：保留 Sprint1 的资源能力，通过 `list_local_notes`、`read_local_note`、`save_note` 工具及动态资源模板，让大模型安全读写你的 Obsidian 知识库（Markdown 笔记），内置路径遍历防护。

- **角色矩阵与动态系统提示**：引入 `personas.json` 角色配置，将思维框架与专业角色（如战略顾问、根因分析师）解耦，框架可通过 `persona` 字段引用角色系统提示，实现提示词复用与灵活定制。

- **零开销 stdio 通信**：沿用纯本地 `stdio` 传输协议，无网络开销，保障数据隐私。

- **沙箱隔离级安全防御**：所有文件操作均经过严格路径校验，杜绝路径遍历攻击。

---

## 2. 克隆仓库与获取分支代码

**📌 重要说明**：Sprint2 的迭代代码位于独立特性分支 `feature/arabica-sprint-2`。克隆时请指定该分支：

```bash
# 直接克隆指定的 feature 分支
git clone -b feature-arabica-sprint-2 https://gitlink.org.cn/Gitconomy/Project-Caffeine.git

# 进入 Sprint2 的独立工作目录
cd Project-Caffeine/projects/arabica/sprint2

# 安装 Node.js 项目依赖
npm install
```

---

## 3. 环境与路径配置

打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为你本机真实的 Markdown 笔记文件夹绝对路径。

```typescript
// 【⚠️ 重要配置】请修改为你电脑上真实的 Markdown 笔记文件夹绝对路径！
const OBSIDIAN_VAULT_PATH = '/your/actual/vault/path';
```

---

## 4. 编译与工作流说明

项目采用 TypeScript 开发，必须先将 `.ts` 源码编译为 `.js` 文件。Sprint2 的 `dist/` 目录已包含预编译文件，可直接用于生产测试。

**⚠️ 极其重要的运行说明 (必读)：**

基于 MCP 的 `stdio` 架构，本程序**不需要**手动启动独立后台服务。请根据使用场景选择工作流：

- **🟢 日常使用 (生产模式)**

  你**不需要**在终端里输入 `npm run start`。只需在 Cherry Studio 或 Claude Desktop 等客户端中配置好 `dist/app.js` 的绝对路径并开启开关，客户端会自动唤起并托管 Node 进程。

- **🛠️ 开发与调试 (实时监听模式)**

  如需修改源码并配合 VS Code 断点调试，请保持终端运行：

  ```bash
  npm run watch   # 或 tsc --watch
  ```

  代码保存后自动编译，在 Cherry Studio 中将 Server 开关关闭再打开，即可应用最新代码。

---

## 5. Sprint2 暴露的原语

### 5.1 Prompts（思维框架模板）

本服务端向支持 MCP 的 LLM 暴露以下 6 个 Prompt 模板，用于引导模型进行结构化思考：

| 框架名称 | 描述 | 参数 |
|----------|------|------|
| `scqa` | SCQA 架构：情境、复杂化、问题、答案 | `situation`, `complication`, `question`, `answer` |
| `5whys` | 5 Whys 根因分析 | `problem` |
| `5w3h` | 5W3H 多维度拆解 | `topic` |
| `swot` | SWOT 内外部环境分析 | `entity` |
| `pestle` | PESTLE 宏观环境分析 | `domain` |

客户端可通过 `prompts/list` 获取完整参数列表。

### 5.2 Tools（主动调用工具）

| 工具名称 | 功能 | 参数 |
|----------|------|------|
| `list_local_notes` | 列出知识库中所有 `.md` 文件 | 无 |
| `read_local_note` | 读取指定笔记内容 | `filename` |
| `save_note` | 保存笔记到本地知识库 | `filename`, `content` |
| `generate_search_queries` | 将查询拆解为专业检索词 | `query` |

### 5.3 Resources（被动上下文）

- **`note://local/{filename}`**：动态资源模板，客户端可浏览和读取知识库中的任意笔记文件，资源列表自动从目录生成。

---

## 6. 客户端接入联调（以 Cherry Studio 为例）

1. 打开 Cherry Studio，进入 **设置 → MCP**。

2. 添加新的 Server 配置：
   - **名称**：`ProjectCaffeine-Sprint2`
   - **Command**：`node`
   - **Args**：`[--inspect=9229, /home/wguo/Downloads/Project-Caffeine/projects/arabica/sprint2/dist/app.js]`  
     （`--inspect` 端口可自定义，用于 VS Code 调试）

或者通过导入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": {}
    }
  }
}
```

3. 保存后状态灯应为绿色。

4. 若需调试，在 VS Code 中运行“附加到进程”（监听相应端口），即可拦截所有原语调用。

---

## 7. Sprint2 文档

| **版本**                                               | **开发目标**                                                                       | **设计文档**                                                                                           | 开发文档                                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`v0.0.2`](./README.md) | 基于 Sprint 1 原型，扩展为支持 MCP Prompts 原语的多框架引擎，实现意图拆解工具与本地知识库集成，构建模块化、可扩展的提示词策略服务器。 | [Arabica Sprint2系统设计文档](./../../docs/design/arabica-sprint2-architecture-specification.md) | [Arabica Sprint2系统开发文档](./../../docs/design/arabica-sprint2-development-specification.md) |

---

## 许可声明

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