Skip to content

TOOLS.md

Latest commit

 

History

History
346 lines (262 loc) · 7.97 KB

TOOLS.md

File metadata and controls

346 lines (262 loc) · 7.97 KB

MCP 工具详解

本文档详细介绍 NeuroSpec 提供的所有 MCP 工具及其参数。

目录

interact - 智能交互

让 AI 能够与用户进行富文本交互，收集用户反馈。

参数

参数 类型 必填 说明
message string ✅ 要显示的消息内容
predefined_options string[] ❌ 预定义的选项列表
is_markdown boolean ❌ 是否渲染 Markdown（默认 true）

请求示例

{
  "message": "## 检测到多个实现方案\n\n请选择您偏好的方式：\n\n1. **方案A**: 使用现有库，开发速度快\n2. **方案B**: 自定义实现，灵活性高",
  "predefined_options": [
    "✅ 方案A: 使用现有库",
    "🔧 方案B: 自定义实现",
    "📋 需要更多信息"
  ],
  "is_markdown": true
}

响应格式

{
  "user_input": "用户的自由输入文本",
  "selected_options": ["用户选择的选项"],
  "images": [
    {
      "data": "base64编码的图片数据",
      "media_type": "image/png"
    }
  ],
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "uuid",
    "source": "popup"
  }
}

使用场景

  • 确认操作：在执行危险操作前询问用户
  • 选择方案：让用户在多个技术方案中选择
  • 收集信息：获取额外的上下文信息
  • 图片输入：用户可以拖拽截图提供视觉参考

最佳实践

{
  "message": "## 🚨 NSP 施工图\n\n**修改范围**: 3 个文件\n**风险等级**: 低\n\n```json\n{\"files\": [\"a.rs\", \"b.rs\"]}\n```\n\n确认执行？",
  "predefined_options": ["✅ 确认执行", "❌ 取消", "📝 修改方案"],
  "is_markdown": true
}

memory - 记忆管理

存储和召回项目级的开发规则、偏好和上下文。

操作类型

Action 说明
remember 存储新记忆
recall 召回相关记忆
update 更新现有记忆
delete 删除记忆
list 列出所有记忆

remember - 存储记忆

{
  "action": "remember",
  "content": "本项目使用 4 空格缩进，禁止使用 any 类型",
  "category": "rule",
  "project_path": "/path/to/project"
}

参数说明：

参数 类型 必填 说明
action string ✅ 固定为 remember
content string ✅ 记忆内容
category string ✅ 分类：rule/preference/pattern/context
project_path string ❌ 项目路径（自动检测 Git 根目录）

recall - 召回记忆

{
  "action": "recall",
  "context": "代码风格相关规则",
  "project_path": "/path/to/project"
}

参数说明：

参数 类型 必填 说明
action string ✅ 固定为 recall
context string ❌ 上下文关键词（用于语义匹配）
project_path string ❌ 项目路径

记忆分类

Category 说明 示例
rule 开发规则 "禁止使用 eval()"
preference 用户偏好 "偏好使用 Tailwind CSS"
pattern 代码模式 "使用 Repository 模式访问数据"
context 项目上下文 "技术栈：Vue 3 + Rust"

列出记忆

{
  "action": "list",
  "category": "rule",
  "project_path": "/path/to/project",
  "page": 1,
  "page_size": 20
}

search - 代码搜索

使用本地索引（Tantivy + Tree-sitter）和 ripgrep 提供的统一搜索引擎，支持：

  • 全文搜索 (Text)
  • 符号搜索 (Symbol)
  • 结构概览 (Structure / StructureOnly)
  • SmartStructure（结构感知搜索，推荐给 LLM）

参数

参数 类型 必填 说明
query string ✅ 搜索查询；在 SmartStructure 下推荐自然语言描述
project_root_path string ❌ 项目根路径（自动检测 Git 根或 CWD）
mode string ❌ 低层搜索模式：text / symbol / structure（兼容旧调用，不推荐直接设置）
profile object ❌ 高层搜索策略：smart_structure / structure_only（推荐）

高层 profile 模式（推荐）

SmartStructure - 结构感知搜索（推荐默认）

特点：

  • 使用本地索引 + scope / max_results 对结果做结构感知过滤
  • 在结果中附带「匹配分布」「关键符号」等结构视角汇总
  • 当无结果时自动回退到项目结构概览（内部走 StructureOnly）

请求示例：

{
  "project_root_path": "/path/to/project",
  "query": "修复用户认证逻辑",
  "profile": {
    "smart_structure": {
      "scope": { "kind": "project" },
      "max_results": 15
    }
  }
}

scope 可选值：

  • project：全项目（默认）
  • folder：仅在指定文件夹下搜索（支持相对路径）
  • file：仅在指定文件内搜索
  • symbol：预留，用于将来结合符号索引做更精细的过滤

StructureOnly - 仅结构概览

用于快速建立对项目的宏观认识或在 SmartStructure 0 结果时作为回退：

{
  "project_root_path": "/path/to/project",
  "profile": {
    "structure_only": {
      "max_depth": 3,
      "max_nodes": 100
    }
  }
}

返回内容包括：

  • 语言分布
  • 模块/目录树（按深度裁剪）
  • 依赖关系概览（在启用 experimental-neurospec 时）
  • 关键符号/入口点

低层 mode 模式（兼容保留）

text - 全文搜索

{
  "query": "用户认证逻辑",
  "mode": "text",
  "project_root_path": "/path/to/project"
}

返回与查询语义相关的代码片段。

symbol - 符号搜索

{
  "query": "handleLogin",
  "mode": "symbol",
  "project_root_path": "/path/to/project"
}

精确查找函数、类、变量定义。

structure - 项目结构（legacy）

{
  "query": "",
  "mode": "structure",
  "project_root_path": "/path/to/project"
}

等价于 profile = { "structure_only": { ... } } 的旧模式，仅在 profile 未设置时生效。

响应格式

[Index: ✅ Ready | Files: 1234]
Found 5 relevant snippets (Mode: Text):

### 📄 `src/auth/login.rs` (Score: 0.95)
📍 impl AuthService → login
📝 `pub async fn login(&self, credentials: Credentials) -> Result<Token>`
```rust
pub async fn login(&self, credentials: Credentials) -> Result<Token> {
    // 验证用户凭据
    let user = self.user_repo.find_by_email(&credentials.email).await?;
    // ...
}


### 索引机制

- **首次搜索**：自动建立索引（10-30秒）
- **增量更新**：检测文件变化，自动更新索引（<1秒）
- **缓存位置**：`%LOCALAPPDATA%/neurospec/search_index/`

---

## 高级工具

> ⚠️ 以下工具为实验性功能

### neurospec_graph_impact_analysis

分析符号的依赖影响范围，用于重构前评估。

```json
{
  "symbol_name": "UserService",
  "project_root": "/path/to/project",
  "depth": 2
}

neurospec_refactor_rename

跨文件安全重命名符号。

{
  "old_name": "getUserById",
  "new_name": "findUserById",
  "file_path": "src/services/user.rs",
  "kind": "function",
  "project_root": "/path/to/project"
}

工具组合使用

典型工作流

  1. 召回记忆 → 了解项目规范
  2. 搜索代码 → 定位相关代码
  3. 交互确认 → 展示方案并获取确认
  4. 执行修改 → 按照确认的方案执行
  5. 存储记忆 → 记录新的规则/模式

示例

AI: 调用 memory.recall() 获取项目规则
AI: 调用 search() 查找相关代码
AI: 调用 interact() 展示修改方案
用户: 选择"确认执行"
AI: 执行代码修改
AI: 调用 memory.remember() 存储新发现的模式

如需了解更多，请参考 架构文档。