Files

gzkoala 1f09296e12 docs(update):更新Arabica Sprint3 相关文档

Signed-off-by: gzkoala <guohao@gitconomy.org>

2026-03-11 14:13:42 +08:00

6.4 KiB

Raw Permalink Blame History

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)：

# 直接克隆指定的 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 配合客户端进行源码级联调：

打开 Cherry Studio，进入 设置 -> MCP。
添加一个新的 Server 配置：
- 名称: ProjectCaffeine-Sprint1
- Command: node
- Args: [--inspect=9229", /你的实际克隆路径/Project-Caffeine/projects/arabica/sprint1/dist/app.js] (⚠️ 必须为编译后的 js 文件绝对路径，且 --inspect 需放在首位以开启调试)

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

保存后确认状态灯变为绿色。
返回 VS Code，在侧边栏“运行和调试”中执行附加 (Attach)，即可对大模型发起的每一次工具调用进行完美断点拦截。

8. Sprint1 文档

版本	开发目标	设计文档	开发文档
`v0.0.1`	部署基于 Node.js 开发环境，验证 MCP 协议组件间通讯、大语言模型推理等基本运行环境。	Arabicat Sprint1系统设计文档	Arabicat Sprint1系统开发文档

6.4 KiB Raw Permalink Blame History Unescape Escape