yystopf/Project-Caffeine
1
0
Fork 0
forked from new_org/Project-Caffeine
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(update):更新Arabica Sprint3 README文件

Browse Source 
Signed-off-by: gzkoala <guohao@gitconomy.org>
This commit is contained in:
gzkoala
2026-03-11 13:33:51 +08:00
parent e0891bec49
commit f5c4222b31
1 changed files with 92 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
projects/arabica/src/sprint3/README.md
View File

@@ -1,44 +1,48 @@
<!--
---
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"
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
- MCP
- stdio
- Obsidian
- QuickStart
- Cherry Studio
- "Project Caffeine"
- "Arabica"
- "Sprint 3"
- "QuickStart"
- "MCP"
- "Tools"
- "Cherry Studio"
license: "CC BY-SA 4.0"
status: "Active"
---
-->
# Project Caffeine - Arabica Sprint1 QuickStart
# Project Caffeine - Arabica v0.0.3 QuickStart
## 1. Sprint1 `0.1.0` 版本核心特性
# 1. Arabica `v0.0.3` 版本核心特性
- **零网络开销通信**：作为本地集成版本，本系统采用 `stdio` 传输协议，利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信，实现零网络传输开销。
`arabica v0.0.3` (Sprint 3) 版本的 5 大核心特性：
- **本地知识图谱接入**：无缝对接 Obsidia个人知识管理软件，让大模型能够直接读取你的本地知识库。
- **内置 5 Whys 策略引擎**：引入经典的“5 Whys”思维框架挂载，强制约束大模型的思考路径，辅助其将模糊想法拆解为高精度的追问。
- **沙箱隔离级安全防御**：默认将 AI 生成的指令视为不可信负载，通过底层机制阻断越权访问和路径遍历漏洞，确保本地文件系统的绝对安全。
- **全自动意图驱动路由**：系统架构发生“智能升维”，全面废弃了向客户端 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. 克隆仓库与获取分支代码
**📌 重要说明**：Sprint 的迭代代码不会直接合并到`master` 分支。为了获取 Sprint1 的完整代码，你需要在克隆时指定对应的特性分支 (`feature/arabica-sprint-1`)：
**📌 重要说明**：`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
git clone -b feature-arabica-sprint-1 https://gitlink.org.cn/Gitconomy/Project-Caffeine.git
# 进入 Sprint1 的独立工作目录
cd Project-Caffeine/projects/arabica/sprint1
# 进入 Sprint2 的独立工作目录
cd Project-Caffeine/projects/arabica/sprint3
# 安装 Node.js 项目依赖
npm install
@@ -48,70 +52,102 @@ npm install
## 3. 环境与路径配置
为了让系统准确挂载你的知识库，请打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为你本机实际的 Markdown 文件夹绝对路径。
打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为您本机真实的 Markdown 笔记文件夹绝对路径。
---
## 4. 编译与工作流说明
项目采用 TypeScript 开发，底层依靠 Node.js 运行，因此必须先将 `.ts` 源码编译为 `.js` 文件。Sprint1的项目目录已经包含编译过的 `.js` 文件（/dist目录)，可以直接快速测试运行。
项目采用 TypeScript 开发，运行前必须将源码编译为 `.js` 文件。
**⚠️ 极其重要的运行说明 (必读)：**
```bash
npm build
```
基于 MCP 的 `stdio` 架构特性，本程序**不需要**你手动启动独立的后台服务。请根据你的使用场景选择工作流：
基于 MCP 的 `stdio` 架构，本程序**不需要**手动启动独立后台服务。请根据使用场景选择工作流：
- **🟢 日常使用 (生产模式)**
你**不需要**在终端里输入 `npm run start`。只要确保 `dist/app.js` 文件存在，当你在 Cherry Studio 或 Claude Desktop 等客户端中配置好绝对路径并打开开关时，客户端会在系统后台自动唤起并接管这个 Node 进程。
您**不需要**在终端里输入任何启动命令。只需在 Cherry Studio 等客户端中配置好 `dist/app.js` 的绝对路径并开启开关，客户端会自动唤起并托管 Node 进程。
- **🛠️ 开发与调试 (实时监听模式)**
如果你正在修改源码，并希望配合 VS Code 进行断点联调，请在终端中保持运行以下命令：
如需修改源码并配合 VS Code 断点调试，请保持终端运行：
代码保存后自动编译，在 Cherry Studio 中将 Server 开关关闭再打开，即可应用最新代码。
_(此命令会在后台实时监控代码改动。当你按 `Ctrl+S` 保存代码后，只需在 Cherry Studio 中将 Server 开关关闭再打开，即可瞬间应用最新的代码逻辑！)_
---
## 5. Sprint1 暴露的工具 (Tools)
## 5. Sprint3 核心工具 (Tools) 接口
本服务端向支持 MCP 的 LLM 暴露了以下 3 个核心工具，赋予其检索本地数据与优化提示词的主动权：
本服务端向支持 MCP 的大语言模型暴露以下 5 个高度内聚的核心工具：
- **`list_local_notes`**: 扫描本地知识库目录，返回所有 `.md` 格式的文献与笔记列表，帮助大模型确立探索边界。
- **`read_local_note`**: 深度读取指定 Markdown 文件的原文，将本地知识库的物理边界转化为大模型内存中的上下文。
- **`generate_5_whys`**: 针对用户宽泛的研究主题，强制模型连续追问五次“为什么”，层层递进剥离问题的表象，寻找最底层的学术痛点。
## 6. Sprint1 暴露的资源 (Resources)
资源（Resources）作为被动的静态上下文信息数据源，供客户端 UI 直接发现与提取：
- **`obsidian-index`** (`obsidian://vault/index`): 向客户端暴露本地知识库的完整目录索引数据。
_(注：Sprint 2 中的 MCP Prompts 原语已在本次迭代中废弃，功能收口至 `fetch_framework_template` 工具中实现智能化调度。)_
---
## 7. 客户端接入联调 (以 Cherry Studio 为例)
## 6. 客户端接入联调（以 Cherry Studio 为例）
Sprint1 采用纯本地 `stdio` 架构，推荐使用 VS Code 配合客户端进行源码级联调：
1. 打开 Cherry Studio，进入 **设置 → MCP**。
1. 打开 Cherry Studio，进入 **设置 -> MCP**。
2. 添加新的 Server 配置：
2. 添加一个新的 Server 配置：
- **名称**：`ProjectCaffeine-Sprint3`
- **名称**: `ProjectCaffeine-Sprint1`
- **Command**: `node`
- **Args**: `["--inspect=9229", "/你的实际克隆路径/Project-Caffeine/projects/arabica/sprint1/dist/app.js"]` _(⚠️ 必须为编译后的 js 文件绝对路径，且 `--inspect` 需放在首位以开启调试)_
- **Command**：`node`
3. 保存后确认状态灯变为绿色。
- **Args**：`[--inspect=9229, /您的绝对路径/Project-Caffeine/projects/arabica/sprint3/dist/app.js]`
4. 返回 VS Code，在侧边栏“运行和调试”中执行附加 (Attach)，即可对大模型发起的每一次工具调用进行完美断点拦截。
（`--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. **禁止瞎编框架**：进行框架分析前，必须先调用工具获取框架模板。
```
---
## 8. Sprint1 文档
## 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) |
- Sprint1 [设计文档](./docs/arabica-sprint1-architecture-specification.md)
- Sprint1 [开发文档](./docs/arabica-sprint1-development-specification.md)
---
## 许可声明
本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research.
本文档采用 **知识共享署名-相同方式共享 4.0 国际许可协议 (CC BY-SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research.