diff --git a/projects/arabica/src/sprint3/README.md b/projects/arabica/src/sprint3/README.md index 15cae60..4537cad 100644 --- a/projects/arabica/src/sprint3/README.md +++ b/projects/arabica/src/sprint3/README.md @@ -1,44 +1,48 @@ -# 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.