<!--
---
title: "Project Caffeine - Arabica Sprint1 QuickStart"
description: "Project Caffeine Arabica Sprint1 的快速启动指南，涵盖基于 MCP stdio 架构的零网络开销部署、Obsidian 本地知识库接入、5 Whys 策略引擎配置及 Cherry Studio 客户端联调全流程。"
version: "1.0.0"
author: "Gitconomy Research郭晧"
date: "2026-03-01"
type: "README / QuickStart"
tags:
  - Project Caffeine
  - MCP
  - stdio
  - Obsidian
  - QuickStart
  - Cherry Studio
license: "CC BY-SA 4.0"
---
-->
# Project Caffeine - Arabica Sprint1 QuickStart

## 1. Arabica v0.0.1(Sprint1)版本核心特性

- **零网络开销通信**：作为本地集成版本，本系统采用 `stdio` 传输协议，利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信，实现零网络传输开销。

- **本地知识图谱接入**：无缝对接 Obsidia个人知识管理软件，让大模型能够直接读取你的本地知识库。

- **内置 5 Whys 策略引擎**：引入经典的“5 Whys”思维框架挂载，强制约束大模型的思考路径，辅助其将模糊想法拆解为高精度的追问。

- **沙箱隔离级安全防御**：默认将 AI 生成的指令视为不可信负载，通过底层机制阻断越权访问和路径遍历漏洞，确保本地文件系统的绝对安全。

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

**📌 重要说明**：Sprint 的迭代代码不会直接合并到`master` 分支。为了获取 Sprint1 的完整代码，你需要在克隆时指定对应的特性分支 (`feature/arabica-sprint-1`)：

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

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

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

---

## 3. 环境与路径配置

为了让系统准确挂载你的知识库，请打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为你本机实际的 Markdown 文件夹绝对路径。

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

项目采用 TypeScript 开发，底层依靠 Node.js 运行，因此必须先将 `.ts` 源码编译为 `.js` 文件。Sprint1的项目目录已经包含编译过的 `.js` 文件（/dist目录)，可以直接快速测试运行。

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

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

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

    你**不需要**在终端里输入 `npm run start`。只要确保 `dist/app.js` 文件存在，当你在 Cherry Studio 或 Claude Desktop 等客户端中配置好绝对路径并打开开关时，客户端会在系统后台自动唤起并接管这个 Node 进程。

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

    如果你正在修改源码，并希望配合 VS Code 进行断点联调，请在终端中保持运行以下命令：

    _(此命令会在后台实时监控代码改动。当你按 `Ctrl+S` 保存代码后，只需在 Cherry Studio 中将 Server 开关关闭再打开，即可瞬间应用最新的代码逻辑！)_

---

## 5. Sprint1 暴露的工具 (Tools)

本服务端向支持 MCP 的 LLM 暴露了以下 3 个核心工具，赋予其检索本地数据与优化提示词的主动权：

- **`list_local_notes`**: 扫描本地知识库目录，返回所有 `.md` 格式的文献与笔记列表，帮助大模型确立探索边界。
- **`read_local_note`**: 深度读取指定 Markdown 文件的原文，将本地知识库的物理边界转化为大模型内存中的上下文。
- **`generate_5_whys`**: 针对用户宽泛的研究主题，强制模型连续追问五次“为什么”，层层递进剥离问题的表象，寻找最底层的学术痛点。


## 6. Sprint1 暴露的资源 (Resources)

资源（Resources）作为被动的静态上下文信息数据源，供客户端 UI 直接发现与提取：

- **`obsidian-index`** (`obsidian://vault/index`): 向客户端暴露本地知识库的完整目录索引数据。

---

## 7. 客户端接入联调 (以 Cherry Studio 为例)

Sprint1 采用纯本地 `stdio` 架构，推荐使用 VS Code 配合客户端进行源码级联调：

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

2. 添加一个新的 Server 配置：

    - **名称**: `ProjectCaffeine-Sprint1`
    - **Command**: `node`
    - **Args**: `[--inspect=9229", /你的实际克隆路径/Project-Caffeine/projects/arabica/sprint1/dist/app.js]` _(⚠️ 必须为编译后的 js 文件绝对路径，且 `--inspect` 需放在首位以开启调试)_

或者通过导入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，在侧边栏“运行和调试”中执行附加 (Attach)，即可对大模型发起的每一次工具调用进行完美断点拦截。

---

## 8. Sprint1 文档

| **版本**                                               | **开发目标**                                                                       | **设计文档**                                                                                           | 开发文档                                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`v0.0.1`](./README.md) | 部署基于 Node.js 开发环境，验证 MCP 协议组件间通讯、大语言模型推理等基本运行环境。<br>            | [Arabicat Sprint1系统设计文档](./../../docs/design/arabica-sprint1-architecture-specification.md) | [Arabicat Sprint1系统开发文档](./../../docs/design/arabica-sprint1-development-specification.md) |

---

## 许可声明

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