diff --git a/docs/features/smart-routing.mdx b/docs/features/smart-routing.mdx index f92de11..f85294d 100644 --- a/docs/features/smart-routing.mdx +++ b/docs/features/smart-routing.mdx @@ -362,6 +362,129 @@ Smart Routing now supports group-scoped searches, allowing you to limit tool dis +### Progressive Disclosure Mode + +Progressive Disclosure is an optimization feature that reduces token usage when working with Smart Routing. When enabled, the tool discovery workflow changes from a 2-step to a 3-step process. + + + + By default, Smart Routing returns full tool information including complete parameter schemas in `search_tools` results. This can consume significant tokens when dealing with tools that have complex input schemas. + + **Progressive Disclosure** changes this behavior: + - `search_tools` returns only tool names and descriptions (minimal info) + - A new `describe_tool` endpoint provides full parameter schema on demand + - `call_tool` executes the tool as before + + This approach is particularly useful when: + - Working with many tools with complex schemas + - Token usage optimization is important + - AI clients need to browse many tools before selecting one + + + + Enable Progressive Disclosure through the Settings page or environment variable: + + **Via Settings UI:** + 1. Navigate to Settings → Smart Routing + 2. Enable the "Progressive Disclosure" toggle + 3. The change takes effect immediately + + **Via Environment Variable:** + ```bash + SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true + ``` + + + + When Progressive Disclosure is **disabled** (default), Smart Routing provides two tools: + + **Workflow:** `search_tools` → `call_tool` + + | Tool | Purpose | + |------|---------| + | `search_tools` | Find tools by query, returns full tool info including `inputSchema` | + | `call_tool` | Execute a tool with the provided arguments | + + This mode is simpler but uses more tokens due to full schemas in search results. + + + + When Progressive Disclosure is **enabled**, Smart Routing provides three tools: + + **Workflow:** `search_tools` → `describe_tool` → `call_tool` + + | Tool | Purpose | + |------|---------| + | `search_tools` | Find tools by query, returns only name and description | + | `describe_tool` | Get full schema for a specific tool (new) | + | `call_tool` | Execute a tool with the provided arguments | + + **Example workflow:** + 1. AI calls `search_tools` with query "file operations" + 2. Results show tool names and descriptions (minimal tokens) + 3. AI calls `describe_tool` for a specific tool to get full `inputSchema` + 4. AI calls `call_tool` with the correct arguments + + This mode reduces token usage by only fetching full schemas when needed. + + + + **Standard Mode search_tools response:** + ```json + { + "tools": [ + { + "name": "read_file", + "description": "Read contents of a file", + "inputSchema": { + "type": "object", + "properties": { + "path": { "type": "string", "description": "File path to read" }, + "encoding": { "type": "string", "default": "utf-8" } + }, + "required": ["path"] + } + } + ] + } + ``` + + **Progressive Disclosure Mode search_tools response:** + ```json + { + "tools": [ + { + "name": "read_file", + "description": "Read contents of a file" + } + ], + "metadata": { + "progressiveDisclosure": true, + "guideline": "Use describe_tool to get the full parameter schema before calling." + } + } + ``` + + **describe_tool response:** + ```json + { + "tool": { + "name": "read_file", + "description": "Read contents of a file", + "inputSchema": { + "type": "object", + "properties": { + "path": { "type": "string", "description": "File path to read" }, + "encoding": { "type": "string", "default": "utf-8" } + }, + "required": ["path"] + } + } + } + ``` + + + {/* ### Basic Usage Connect your AI client to the Smart Routing endpoint and make natural language requests: diff --git a/docs/zh/features/smart-routing.mdx b/docs/zh/features/smart-routing.mdx index 40e9b64..2de0a7b 100644 --- a/docs/zh/features/smart-routing.mdx +++ b/docs/zh/features/smart-routing.mdx @@ -64,17 +64,181 @@ description: '使用向量语义搜索的 AI 工具发现系统' ``` + # 搜索所有服务器 http://localhost:3000/mcp/$smart + + # 在特定分组内搜索 + http://localhost:3000/mcp/$smart/{group} ``` ``` + # 搜索所有服务器 http://localhost:3000/sse/$smart + + # 在特定分组内搜索 + http://localhost:3000/sse/$smart/{group} ``` +### 分组范围的智能路由 + +智能路由支持分组范围的搜索，允许您将工具发现限制在特定分组内的服务器： + + + + 将您的 AI 客户端连接到特定分组的智能路由端点： + + ``` + http://localhost:3000/mcp/$smart/production + ``` + + 此端点只会搜索属于 "production" 分组的服务器中的工具。 + + **优势：** + - **聚焦结果**：只返回相关服务器的工具 + - **更好的性能**：减少搜索空间以加快查询速度 + - **环境隔离**：将开发、预发布和生产工具分开 + - **访问控制**：根据用户权限限制工具发现 + + + + 当使用 `$smart/{group}` 时： + + 1. 系统识别指定的分组 + 2. 获取属于该分组的所有服务器 + 3. 将工具搜索过滤到仅限那些服务器 + 4. 返回限定在该分组服务器范围内的结果 + + 如果分组不存在或没有服务器，搜索将不返回任何结果。 + + + +### 渐进式披露模式 + +渐进式披露是一个优化功能，可以减少使用智能路由时的 Token 消耗。启用后，工具发现工作流从 2 步变为 3 步。 + + + + 默认情况下，智能路由在 `search_tools` 结果中返回完整的工具信息，包括完整的参数模式。当处理具有复杂输入模式的工具时，这会消耗大量 Token。 + + **渐进式披露** 改变了这种行为： + - `search_tools` 只返回工具名称和描述（最少信息） + - 新的 `describe_tool` 端点按需提供完整的参数模式 + - `call_tool` 像以前一样执行工具 + + 这种方法特别适用于： + - 处理具有复杂模式的大量工具 + - Token 使用优化很重要的场景 + - AI 客户端需要浏览多个工具后再选择 + + + + 通过设置页面或环境变量启用渐进式披露： + + **通过设置界面：** + 1. 导航到 设置 → 智能路由 + 2. 启用"渐进式披露"开关 + 3. 更改立即生效 + + **通过环境变量：** + ```bash + SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true + ``` + + + + 当渐进式披露**禁用**（默认）时，智能路由提供两个工具： + + **工作流：** `search_tools` → `call_tool` + + | 工具 | 用途 | + |------|------| + | `search_tools` | 按查询查找工具，返回包含 `inputSchema` 的完整工具信息 | + | `call_tool` | 使用提供的参数执行工具 | + + 这种模式更简单，但由于搜索结果中包含完整模式，会使用更多 Token。 + + + + 当渐进式披露**启用**时，智能路由提供三个工具： + + **工作流：** `search_tools` → `describe_tool` → `call_tool` + + | 工具 | 用途 | + |------|------| + | `search_tools` | 按查询查找工具，只返回名称和描述 | + | `describe_tool` | 获取特定工具的完整模式（新增） | + | `call_tool` | 使用提供的参数执行工具 | + + **示例工作流：** + 1. AI 使用查询 "文件操作" 调用 `search_tools` + 2. 结果显示工具名称和描述（最少 Token） + 3. AI 为特定工具调用 `describe_tool` 获取完整的 `inputSchema` + 4. AI 使用正确的参数调用 `call_tool` + + 这种模式通过仅在需要时获取完整模式来减少 Token 使用。 + + + + **标准模式 search_tools 响应：** + ```json + { + "tools": [ + { + "name": "read_file", + "description": "读取文件内容", + "inputSchema": { + "type": "object", + "properties": { + "path": { "type": "string", "description": "要读取的文件路径" }, + "encoding": { "type": "string", "default": "utf-8" } + }, + "required": ["path"] + } + } + ] + } + ``` + + **渐进式披露模式 search_tools 响应：** + ```json + { + "tools": [ + { + "name": "read_file", + "description": "读取文件内容" + } + ], + "metadata": { + "progressiveDisclosure": true, + "guideline": "使用 describe_tool 获取完整的参数模式后再调用。" + } + } + ``` + + **describe_tool 响应：** + ```json + { + "tool": { + "name": "read_file", + "description": "读取文件内容", + "inputSchema": { + "type": "object", + "properties": { + "path": { "type": "string", "description": "要读取的文件路径" }, + "encoding": { "type": "string", "default": "utf-8" } + }, + "required": ["path"] + } + } + } + ``` + + + {/* ## 性能优化 ### 嵌入缓存 diff --git a/frontend/src/contexts/SettingsContext.tsx b/frontend/src/contexts/SettingsContext.tsx index 49153ca..0f26686 100644 --- a/frontend/src/contexts/SettingsContext.tsx +++ b/frontend/src/contexts/SettingsContext.tsx @@ -33,6 +33,7 @@ interface SmartRoutingConfig { openaiApiBaseUrl: string; openaiApiKey: string; openaiApiEmbeddingModel: string; + progressiveDisclosure: boolean; } interface MCPRouterConfig { @@ -180,6 +181,7 @@ export const SettingsProvider: React.FC = ({ children }) openaiApiBaseUrl: '', openaiApiKey: '', openaiApiEmbeddingModel: '', + progressiveDisclosure: false, }); const [mcpRouterConfig, setMCPRouterConfig] = useState({ @@ -238,6 +240,7 @@ export const SettingsProvider: React.FC = ({ children }) openaiApiKey: data.data.systemConfig.smartRouting.openaiApiKey || '', openaiApiEmbeddingModel: data.data.systemConfig.smartRouting.openaiApiEmbeddingModel || '', + progressiveDisclosure: data.data.systemConfig.smartRouting.progressiveDisclosure ?? false, }); } if (data.success && data.data?.systemConfig?.mcpRouter) { diff --git a/frontend/src/pages/SettingsPage.tsx b/frontend/src/pages/SettingsPage.tsx index c7acaeb..f294757 100644 --- a/frontend/src/pages/SettingsPage.tsx +++ b/frontend/src/pages/SettingsPage.tsx @@ -1425,6 +1425,24 @@ const SettingsPage: React.FC = () => { +
+
+

+ {t('settings.progressiveDisclosure')} +

+

+ {t('settings.progressiveDisclosureDescription')} +

+
+ + updateSmartRoutingConfig('progressiveDisclosure', checked) + } + /> +
+