docs(fix):更新Arabica Sprint2 README文件

Signed-off-by: gzkoala <guohao@gitconomy.org>
2026-03-06 15:51:02 +08:00
parent 56f391b860
commit 74a46c2102
1 changed files with 77 additions and 50 deletions
--- a/projects/arabica/src/sprint2/README.md
+++ b/projects/arabica/src/sprint2/README.md
@@ -1,44 +1,51 @@
 <!--
 ---
-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 Sprint2 QuickStart
+description: Project Caffeine Arabica Sprint2 的快速启动指南，涵盖基于 MCP stdio 架构的多维思维框架引擎、意图拆解工具、本地知识库集成及 Cherry Studio 客户端联调全流程。
+version: 1.0.0
+author: Gitconomy Research 郭晧
+date: 2026-03-06
+type: README / QuickStart
 tags:
  - Project Caffeine
  - MCP
  - stdio
  - Obsidian
-  - QuickStart
+  - Prompts
+  - Tools
+  - Resources
  - Cherry Studio
-license: "CC BY-SA 4.0"
+license: CC BY-SA 4.0
 ---
 -->
-# Project Caffeine - Arabica Sprint1 QuickStart
+# Project Caffeine - Arabica Sprint2 QuickStart

-## 1.  Sprint1 `0.1.0` 版本核心特性
+## 1. Sprint2 `0.1.1` 版本核心特性

- **零网络开销通信**：作为本地集成版本，本系统采用 `stdio` 传输协议，利用同一台机器上本地进程间的 stdin 和 stdout 管道进行直接通信，实现零网络传输开销。
+- **多维思维框架引擎**：从单一工具扩展为完整的 Prompts 原语支持，内置 **SCQA、5Whys、5W3H、SWOT、PESTLE** 六大经典思维框架。每个框架均包含角色化系统提示、参数模板及 Few-Shot 示例，强制约束大模型的思考路径，输出高质量结构化分析。

- **本地知识图谱接入**：无缝对接 Obsidia个人知识管理软件，让大模型能够直接读取你的本地知识库。
+- **意图拆解工具**：新增 `generate_search_queries` 工具，将用户自然语言查询自动拆解为 3～5 个专业检索词，支持后续联网搜索或知识库检索，提升信息获取精度。

- **内置 5 Whys 策略引擎**：引入经典的“5 Whys”思维框架挂载，强制约束大模型的思考路径，辅助其将模糊想法拆解为高精度的追问。
+- **本地知识库无缝接入**：保留 Sprint1 的资源能力，通过 `list_local_notes`、`read_local_note`、`save_note` 工具及动态资源模板，让大模型安全读写你的 Obsidian 知识库（Markdown 笔记），内置路径遍历防护。

- **沙箱隔离级安全防御**：默认将 AI 生成的指令视为不可信负载，通过底层机制阻断越权访问和路径遍历漏洞，确保本地文件系统的绝对安全。
+- **角色矩阵与动态系统提示**：引入 `personas.json` 角色配置，将思维框架与专业角色（如战略顾问、根因分析师）解耦，框架可通过 `persona` 字段引用角色系统提示，实现提示词复用与灵活定制。
+
+- **零开销 stdio 通信**：沿用纯本地 `stdio` 传输协议，无网络开销，保障数据隐私。
+
+- **沙箱隔离级安全防御**：所有文件操作均经过严格路径校验，杜绝路径遍历攻击。

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

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

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

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

 # 安装 Node.js 项目依赖
 npm install
@@ -48,70 +55,90 @@ npm install

 ## 3. 环境与路径配置

-为了让系统准确挂载你的知识库，请打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为你本机实际的 Markdown 文件夹绝对路径。
+打开 `src/services/resourceService.ts`，将 `OBSIDIAN_VAULT_PATH` 变量修改为你本机真实的 Markdown 笔记文件夹绝对路径。
+
+```typescript
+// 【⚠️ 重要配置】请修改为你电脑上真实的 Markdown 笔记文件夹绝对路径！
+const OBSIDIAN_VAULT_PATH = '/your/actual/vault/path';
+```
+
+---

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

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

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

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

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

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

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

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

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

 ---

-## 5. Sprint1 暴露的工具 (Tools)
+## 5. Sprint2 暴露的原语

-本服务端向支持 MCP 的 LLM 暴露了以下 3 个核心工具，赋予其检索本地数据与优化提示词的主动权：
+### 5.1 Prompts（思维框架模板）

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

+| 框架名称 | 描述 | 参数 |
+|----------|------|------|
+| `scqa` | SCQA 架构：情境、复杂化、问题、答案 | `situation`, `complication`, `question`, `answer` |
+| `5whys` | 5 Whys 根因分析 | `problem` |
+| `5w3h` | 5W3H 多维度拆解 | `topic` |
+| `swot` | SWOT 内外部环境分析 | `entity` |
+| `pestle` | PESTLE 宏观环境分析 | `domain` |

-## 6. Sprint1 暴露的资源 (Resources)
+客户端可通过 `prompts/list` 获取完整参数列表。

-资源（Resources）作为被动的静态上下文信息数据源，供客户端 UI 直接发现与提取：
+### 5.2 Tools（主动调用工具）

- **`obsidian-index`** (`obsidian://vault/index`): 向客户端暴露本地知识库的完整目录索引数据。
+| 工具名称 | 功能 | 参数 |
+|----------|------|------|
+| `list_local_notes` | 列出知识库中所有 `.md` 文件 | 无 |
+| `read_local_note` | 读取指定笔记内容 | `filename` |
+| `save_note` | 保存笔记到本地知识库 | `filename`, `content` |
+| `generate_search_queries` | 将查询拆解为专业检索词 | `query` |
+
+### 5.3 Resources（被动上下文）
+
+- **`note://local/{filename}`**：动态资源模板，客户端可浏览和读取知识库中的任意笔记文件，资源列表自动从目录生成。

 ---

-## 7. 客户端接入联调 (以 Cherry Studio 为例)
+## 6. 客户端接入联调（以 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` 需放在首位以开启调试)_
-
-3. 保存后确认状态灯变为绿色。
-
-4. 返回 VS Code，在侧边栏“运行和调试”中执行附加 (Attach)，即可对大模型发起的每一次工具调用进行完美断点拦截。
+1. 打开 Cherry Studio，进入 **设置 → MCP**。
+2. 添加新的 Server 配置：
+   - **名称**：`ProjectCaffeine-Sprint2`
+   - **Command**：`node`
+   - **Args**：`["--inspect=9230", "/home/wguo/Downloads/Project-Caffeine/projects/arabica/sprint2/dist/app.js"]`  
+     （`--inspect` 端口可自定义，用于 VS Code 调试）
+3. 保存后状态灯应为绿色。
+4. 若需调试，在 VS Code 中运行“附加到进程”（监听相应端口），即可拦截所有原语调用。

 ---

-## 8. Sprint1 文档
+## 7. Sprint2 文档

- Sprint1 [设计文档](./docs/arabica-sprint1-architecture-specification.md)  
- Sprint1 [开发文档](./docs/arabica-sprint1-development-specification.md)
+- Sprint2 [设计文档](./../../docs/design/arabica-sprint2-architecture-specification.md)  
+- Sprint2 [开发指南](./../../docs/design/arabica-srpint2-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.