<!--
---
title: "Project Caffeine - Arabica v0.0.3 QuickStart"
description: "提供 Arabica v0.0.3 (Sprint 3) 版本的快速上手指南，包括核心特性、环境配置、工具接口及客户端接入步骤。"
type: "README"
version: "v1.0.0 (Arabica) - Sprint 3"
file: "README.md"
author: "Gitconomy Research-郭晧"
date: "2026-03-11"
tags:
  - "Project Caffeine"
  - "Arabica"
  - "Sprint 3"
  - "QuickStart"
  - "MCP"
  - "Tools"
  - "Cherry Studio"
license: "CC BY-SA 4.0"
status: "Active"
---
-->
# Project Caffeine - Arabica v0.0.3 QuickStart

# 1. Arabica v0.0.3 版本核心特性

`arabica v0.0.3` (Sprint 3) 版本的 5 大核心特性：

- **全自动意图驱动路由**：系统架构发生“智能升维”，全面废弃了向客户端 UI 暴露的 Prompts（提示词）原语。大模型现在通过完整的系统提示词上下文，自主理解用户意图（如：查询文献、调用框架分析、保存内容），并在后台全自动调度 `search_arxiv`、`fetch_framework_template` 等专用工具，实现了**全自然语言驱动**的交互体验。
- **学术文献检索与解析**：新增 `search_arxiv` 原子工具，无缝集成 arXiv 官方 API。系统底层自动处理了极其复杂的 XML 解析与数据清洗工作，将杂乱的学术元数据（标题、摘要、链接）按需提取，并转化为大模型极度易读的 Markdown 纯文本列表，极大提升了系统的专业研究检索能力。
- **抗死循环框架引擎**：针对大模型在读取复杂 JSON 思维框架模板时极易陷入“工具疯狂调用死循环”的痛点，系统进行了底层防呆重构。将框架获取下放为私有后台工具 `fetch_framework_template`，在代码底层**主动剥离 JSON 外壳**，并强制向大模型注入“🛑 立即停止调用工具，直接输出报告”的最高优先级系统指令，确保大模型稳定输出分析。
- **高容错落盘兜底机制**： 重构了 `save_note` 工具，彻底解决了大模型在保存上万字长篇分析报告时频发的“JSON 转义崩溃（AI_JSONParseError）”问题。系统将工具的入参校验宽容度放宽至 `z.any()`，并在 Controller 底层通过 `JSON.stringify` 实施自动序列化兜底，确保无论大模型传参格式多混乱，都能 100% 安全平滑地写入本地 Obsidian 知识库。
- **坚固的越权防线与沙箱隔离**： 在系统提示词与底层逻辑中设定了**“绝对红线”：严禁大模型在未经用户明确自然语言授权（如主动回复“保存”或“是的”）前，私自执行任何写盘操作。同时，系统完整保留并强化了本地知识库读写过程中的路径防穿越（Path Traversal）安全机制。

---

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

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

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

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

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

---

## 3. 环境与路径配置

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

---

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

项目采用 TypeScript 开发，运行前必须将源码编译为 `.js` 文件。

```bash
npm build
```

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

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

    您**不需要**在终端里输入任何启动命令。只需在 Cherry Studio 等客户端中配置好 `dist/app.js` 的绝对路径并开启开关，客户端会自动唤起并托管 Node 进程。

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

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

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


---

## 5. Sprint3 核心工具 (Tools) 接口

本服务端向支持 MCP 的大语言模型暴露以下 5 个高度内聚的核心工具：

_(注：Sprint 2 中的 MCP Prompts 原语已在本次迭代中废弃，功能收口至 `fetch_framework_template` 工具中实现智能化调度。)_

---

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

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

2. 添加新的 Server 配置：

    - **名称**：`ProjectCaffeine-Sprint3`

    - **Command**：`node`

    - **Args**：`[--inspect=9229, /您的绝对路径/Project-Caffeine/projects/arabica/sprint3/dist/app.js]`

        （`--inspect` 端口可自定义，用于 VS Code 调试）


**💡 [必看] 系统提示词配置指南**

为了让大模型完美理解并调度 Sprint 3 的意图引擎，**您必须**在 Cherry Studio 的“助手”设置中，将“系统提示词”设定为 Sprint 3 专属的**意图映射规则**。这是激活全自动路由的关键。

```markdown
# Role
你是一个基于意图识别的智能研究助手。你拥有多个专用工具，必须严格根据用户的自然语言意图来选择相应的动作，绝不能自作主张越权操作。

# Intent & Action Mapping (意图与动作映射)

## 意图 1：查询 / 检索学术文献
- **触发条件**：用户明确表示想要检索、查询论文或文献。
- **执行动作**：调用 `search_arxiv` 进行检索 -> 清晰排版展示结果 -> 主动询问：“是否需要将以上文献搜索结果保存到本地？”

## 意图 2：框架分析
- **触发条件**：用户要求使用思维框架（如 SWOT, SCQA, PESTLE 等）进行分析。
- **执行动作**：调用 `fetch_framework_template` 获取模板 -> 按模板输出详细分析 -> 主动询问：“分析完毕，是否需要将此分析结果保存成笔记？”

## 意图 3：保存内容（写盘）
- **触发条件**：用户明确回复“保存”、“需要”等确认指令。
- **执行动作**：调用 `save_note` 工具 -> 传入刚刚生成的全文内容并保存 -> 告知成功。

## 意图 4：本地笔记分析
- **触发条件**：用户要求查询、分析或结合本地的笔记内容。
- **执行动作**：
  1. 调用 `list_local_notes` 获取本地笔记列表。
  2. 根据文件名，调用 `read_local_note` 读取匹配笔记的具体内容。
  3. 基于读取的内容为用户输出综合分析报告。
  4. 主动询问：“分析完毕，是否需要将此综合分析结果保存到本地？”

# 🚫 绝对红线 (核心禁忌)
1. **禁止越权保存**：绝不允许在没有主动询问并获得用户明确同意的情况下，私自调用 `save_note` 工具！
2. **禁止瞎编框架**：进行框架分析前，必须先调用工具获取框架模板。
```

---

## 7. Sprint3 文档

| **版本**                  | **开发目标**                                                                                     | **设计文档**                                                                                   | 开发文档                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| [`v0.0.3`](./README.md) | 构建文献查询 Server，集成学术 API 实现基础外围检索能力，并开发双轨制数据落盘模块，将离散的 JSON 数据转换为带有标准 YAML 元数据的本地化 Markdown 文件。 | [Arabica Sprint3系统设计文档](./../../docs/design/arabica-sprint3-architecture-specification.md) | [Arabica Sprint3系统开发文档](./../../docs/design/arabica-sprint3-development-specification.md) |


---

## 许可声明

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