From 74a46c2102b00d9c16d39d0fbb62e89d39522b2c Mon Sep 17 00:00:00 2001 From: gzkoala Date: Fri, 6 Mar 2026 15:51:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(fix):=E6=9B=B4=E6=96=B0Arabica=20Sprint2?= =?UTF-8?q?=20README=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: gzkoala --- projects/arabica/src/sprint2/README.md | 127 +++++++++++++++---------- 1 file changed, 77 insertions(+), 50 deletions(-) diff --git a/projects/arabica/src/sprint2/README.md b/projects/arabica/src/sprint2/README.md index 15cae60..2c0af2b 100644 --- a/projects/arabica/src/sprint2/README.md +++ b/projects/arabica/src/sprint2/README.md @@ -1,44 +1,51 @@ -# 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.