docs(add):新增Arabica Sprint3 MCP Inspector测试说明文档

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

projects/arabica/docs/test/arabica-sprint3-mcp-inspector-testing-specification.md

@@ -0,0 +1,175 @@
+---
+title: Arabica v0.0.3 MCP Inspector 测试指南
+description: 指导开发人员使用官方 MCP Inspector 工具对 Project Caffeine v0.0.3 版本的核心原语（Tools、Resources）进行标准化的交互联调与测试。
+type: Test Guide
+version: v0.0.3 (Arabica)
+file: arabica-v0.0.3-mcp-inspector-test-guide.md
+author: Gitconomy Research-郭晧
+date: 2026-03-10
+tags:
+  - Project Caffeine
+  - MCP
+  - MCP Inspector
+  - 测试指南
+license: CC BY-SA 4.0
+status: Active
+---
+# Project Caffeine Arabica v0.0.3 MCP Inspector 测试指南
+
+## 1. 测试目的的概述
+
+本文档旨在为开发人员提供一份标准化的操作指南，使用官方的 **MCP Inspector** 工具对 Project Caffeine (v0.0.3) 的底层协议接口进行独立测试。通过脱离具体的大模型客户端（如 Claude Desktop），我们可以直接验证系统暴露的 Tools（工具）与 Resources（资源）原语的逻辑正确性、参数校验机制以及边缘异常处理能力。
+
+## 2. 测试环境的准备
+
+### 2.1 配置系统的环境变量
+
+在启动测试之前，必须确保本地环境中的配置项已正确挂载。请在项目根目录的 `src/.env` 文件中检查以下关键路径，确保其指向本地真实的测试用例目录：
+
+```bash
+# 必须配置为本地真实存在的目录，且具备读写权限
+OBSIDIAN_VAULT_PATH=/真实的/本地/测试目录/MyVault
+LITERATURE_STORAGE_PATH=/真实的/本地/测试目录/MyVault
+````
+
+## 2.2 构建并启动检查器
+
+Project Caffeine 的服务端运行依赖于编译后的 JavaScript 代码。请在终端中依次执行以下命令，完成项目的构建并通过 `npx` 启动官方的 MCP Inspector：
+
+Bash
+
+```bash
+# 1. 编译 TypeScript 源码
+npm run build
+
+# 2. 启动 MCP Inspector 并挂载编译后的入口文件
+npx @modelcontextprotocol/inspector node dist/app.js
+```
+
+启动成功后，终端将输出一个本地调试地址（通常为 `http://localhost:5173`）。请在浏览器中打开该地址，进入 MCP Inspector 的可视化调试界面。
+
+## 3. 核心原语的测试流程
+
+在 MCP Inspector 的 Web 界面中，您将看到系统成功连接的标识 `Project-Caffeine-Arabica-Intent-Mode (v0.0.3)`。接下来，请依次对以下核心功能模块进行拨测。
+
+## 3.1 执行文献检索工具测试 (Tools)
+
+系统通过 `search_arxiv` 工具提供外部学术数据的抓取能力。
+
+1. **定位工具**：在左侧面板选择 **Tools** 选项卡，在列表中找到并选中 `search_arxiv`。
+    
+2. **输入参数**：在参数输入框中填入合法的 JSON 负载：
+    
+    JSON
+    
+    ```bash
+    {
+      "query": "Large Language Models in Healthcare"
+    }
+    ```
+    
+3. **发起调用**：点击 **Run Tool** 按钮。
+    
+4. **验证结果**：
+    
+    - **预期成功**：右侧响应区应返回状态 `isError: false`，且 `content` 数组中包含格式化好的文献标题、链接与摘要列表。
+        
+    - **预期异常**：若输入空的 `query`，系统应触发 Zod 校验拦截，提示“需要检索的学术核心关键字”。
+        
+
+## 3.2 执行思维框架获取测试 (Tools)
+
+系统将静态思维模板通过 `fetch_framework_template` 工具暴露给大模型。
+
+1. **定位工具**：在 Tools 列表中选中 `fetch_framework_template`。
+    
+2. **输入参数**：
+    
+    JSON
+    
+    ```bash 
+    {
+      "framework_name": "scqa"
+    }
+    ```
+    
+3. **发起调用**：点击 **Run Tool** 按钮。
+    
+4. **验证结果**：
+    
+    - **预期成功**：响应文本中应包含“【🛑 最高优先级的底层执行指令 🛑】”以及 SCQA 框架的系统设定与结构要求。
+        
+    - **边缘测试**：尝试输入未注册的框架（如 `abcd`），系统应返回软拦截提示：“未找到框架 abcd。系统支持的框架有: swot, scqa, pestle, 5w3h, 5whys”。
+        
+
+## 3.3 执行双轨制落盘与读取测试 (Tools)
+
+验证系统对本地文件系统的 I/O 控制与路径安全防范。
+
+1. **保存笔记测试 (`save_note`)**：
+    
+    - 构造参数：`{ "filename": "inspector_test.md", "content": "## 测试数据\n这是由 Inspector 写入的测试内容。" }`
+        
+    - 执行后，检查本地 `OBSIDIAN_VAULT_PATH` 目录下是否成功生成了 `inspector_test.md` 文件。
+        
+2. **防穿越安全红线测试 (`save_note`)**：
+    
+    - 构造参数：`{ "filename": "../hacked.md", "content": "危险载荷" }`
+        
+    - **验证预期**：系统必须返回 `isError: true`，并明确提示“无效的文件名，不允许访问上层目录”。
+        
+3. **列出笔记测试 (`list_local_notes`)**：
+    
+    - 直接运行该工具（无需参数）。系统应返回刚才创建的 `inspector_test.md`。
+        
+4. **读取笔记测试 (`read_local_note`)**：
+    
+    - 构造参数：`{ "filename": "inspector_test.md" }`。
+        
+    - 系统应正确返回刚写入的 Markdown 文本内容。
+        
+
+## 3.4 验证本地静态资源挂载 (Resources)
+
+Resources 原语用于将本地知识库作为被动只读资源暴露，以便大模型在对话上下文中作为附件引用。
+
+1. **获取资源列表**：
+    
+    - 在左侧面板切换至 **Resources** 选项卡。
+        
+    - 点击 **List Resources**，系统应返回由 `note://local/` 协议开头的资源列表，且列表中应包含 `note://local/inspector_test.md`。
+        
+2. **读取特定资源**：
+    
+    - 选中 `note://local/inspector_test.md`。
+        
+    - 点击 **Read Resource** 按钮。
+        
+    - **验证结果**：响应区应成功解码 URI 参数，并返回该文件的原始内容文本。
+        
+
+## 4. 常见问题与排错方案
+
+## 4.1 解决连接超时的异常
+
+如果 MCP Inspector 在启动后长时间处于 `Connecting...` 状态，请排查以下可能：
+
+- **检查编译产物**：确认 `npm run build` 是否成功执行，`dist/app.js` 文件是否存在。
+    
+- **检查端口占用**：MCP Inspector 默认使用 `5173` 端口，若端口被占用，可通过环境变量更换端口。
+    
+
+## 4.2 解决本地路径挂载失败的异常
+
+当调用 `save_note` 抛出文件写入失败时：
+
+- **检查环境配置**：确认 `.env` 文件中的 `OBSIDIAN_VAULT_PATH` 路径是否拼写正确，且必须为绝对路径。
+    
+- **检查目录权限**：确保当前运行 Node.js 进程的用户对该绝对路径具有完全读写权限。
+    
+
+---
+
+## 许可声明
+
+本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research。