Exa MCP Server

# `exa-mcp-server` 项目开发指南 ## 目录 1. [项目概述](#1-项目概述) 2. [架构总览](#2-架构总览) 3. [开发环境搭建](#3-开发环境搭建) 4. [代码结构详解](#4-代码结构详解) 5. [核心模块深度解析](#5-核心模块深度解析) * [入口模块 (`src/index.ts`)](#入口模块-srcindexts) * [类型定义 (`src/types.ts`)](#类型定义-srctypests) * [工具模块 (`src/tools/`)](#工具模块-srctools) * [通用工具模块 (`src/utils/logger.ts`)](#通用工具模块-srcutilsloggerts) 6. [API 接口说明](#6-api-接口说明) * [Web Search Tool (`web_search_exa`)](#web-search-tool-web_search_exa) * [Company Research Tool (`company_research_exa`)](#company-research-tool-company_research_exa) * [Crawling Tool (`crawl_exa`)](#crawling-tool-crawl_exa) * [LinkedIn Search Tool (`linkedin_search_exa`)](#linkedin-search-tool-linkedin_search_exa) * [Deep Research Start Tool (`deep_research_start_exa`)](#deep-research-start-tool-deep_research_start_exa) * [Deep Research Check Tool (`deep_research_check_exa`)](#deep-research-check-tool-deep_research_check_exa) * [Exa Code Tool (`exa_code_exa`)](#exa-code-tool-exa_code_exa) 7. [构建/测试/部署流程](#7-构建测试部署流程) * [编译](#编译) * [测试](#测试) * [打包与部署](#打包与部署) 8. [贡献指南](#8-贡献指南) 9. [常见问题解答及故障排除](#9-常见问题解答及故障排除) 10. [未来改进方向](#10-未来改进方向) --- ## 1. 项目概述 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器端应用，它通过集成 Exa AI 的强大功能，为 MCP 客户端提供了一系列高级工具。这些工具包括网络搜索、网页抓取、深度研究、公司研究、LinkedIn 搜索以及代码上下文搜索。本项目旨在作为一个可扩展的平台，使 AI 模型能够通过结构化的 API 调用与外部世界进行交互，从而增强其信息获取和处理能力。 **核心目标：** * 提供一套标准化的接口，供 MCP 客户端调用 Exa AI 服务。 * 封装 Exa AI API 的复杂性，提供简洁易用的工具函数。 * 支持灵活的工具启用/禁用配置。 * 确保请求的类型安全和参数验证。 * 提供基础的日志记录和错误处理机制。 ## 2. 架构总览 `exa-mcp-server` 采用模块化设计，核心功能围绕 MCP 服务器和 Exa AI 工具进行组织。 **主要组成部分：** * **MCP Server (`src/index.ts`)**: 项目的入口点，负责初始化 MCP 服务器并注册所有启用的工具。 * **工具模块 (`src/tools/`)**: 包含所有 Exa AI 工具的具体实现，每个工具都封装了与 Exa AI API 的交互逻辑。 * **类型定义 (`src/types.ts`)**: 集中管理所有与 Exa AI API 交互相关的 TypeScript 类型和接口。 * **配置模块 (`src/tools/config.ts`)**: 定义 Exa AI API 的基本 URL、端点和默认参数。 * **日志模块 (`src/utils/logger.ts`)**: 提供统一的日志记录功能，便于请求追踪和问题诊断。 **架构概览（Mermaid 流程图）：** ```mermaid graph TD A[MCP Client] -->|Tool Call| B(MCP Server - src/index.ts) B -->|Config Check| C{Enabled Tool?} C -- No --> D[Tool Not Registered Error] C -- Yes --> E(Register Tool - e.g., registerWebSearchTool) E --> F[Tool Implementation - e.g., src/tools/webSearch.ts] F -->|Construct Exa API Request| G(Axios - HTTP Request) G -->|Send Request| H[Exa AI API - https://api.exa.ai] H -->|Exa API Response| G G -->|Process Response| F F -->|Format Result for MCP Client| I(Return to MCP Server) I --> J[MCP Server] J -->|Return Result| A F -- Logger (src/utils/logger.ts) --> K[Console/Error Log] ``` **数据流转核心逻辑：** 1. MCP 客户端通过 `stdio` 或 `shttp` 方式向 `exa-mcp-server` 发送工具调用请求。 2. `src/index.ts` 接收请求，并根据服务器配置检查请求的工具是否已启用。 3. 如果工具已启用，请求被路由到 `src/tools/` 目录下对应的工具实现。 4. 工具实现根据请求参数和 `src/tools/config.ts` 中的配置，构造一个发送给 Exa AI API 的 HTTP 请求。请求数据结构由 `src/types.ts` 严格定义，并通过 `Zod` 进行运行时验证。 5. `axios` 库负责发送 HTTP 请求到 Exa AI API，并处理响应。`src/utils/logger.ts` 会记录请求的生命周期。 6. Exa AI API 返回数据后，工具实现会解析响应，并将其格式化为 MCP 客户端期望的结构。 7. 格式化后的结果通过 MCP 服务器返回给客户端。如果发生错误，会返回包含 `isError: true` 标志的错误信息。 ## 3. 开发环境搭建 ### 3.1 前置条件 * **Node.js**: 版本 >= 18.0.0。推荐使用 nvm (Node Version Manager) 进行版本管理。 * **npm**: Node.js 安装时会自带 npm。 * **TypeScript**: 项目使用 TypeScript 编写。 * **Exa AI API Key**: 访问 Exa AI 服务需要一个有效的 API Key。 ### 3.2 环境设置步骤 1. **克隆代码库**: ```bash git clone https://github.com/your-repo/exa-mcp-server.git cd exa-mcp-server ``` 2. **安装依赖**: ```bash npm install ``` 这将安装 `package.json` 中定义的所有依赖项。 3. **配置 Exa AI API Key**: Exa AI API Key 应该通过环境变量 `EXA_API_KEY` 提供，而不是硬编码在代码中。 在开发环境中，你可以在项目根目录下创建一个 `.env` 文件（需要安装 `dotenv` 库来加载，但本项目目前未显式使用，通常直接从运行环境读取）： ``` EXA_API_KEY=your_actual_exa_api_key_here ``` 或者在运行命令时直接设置环境变量： ```bash EXA_API_KEY=your_actual_exa_api_key_here npm run start ``` **注意**: 永远不要将敏感的 API Key 直接提交到版本控制中。 4. **运行开发服务器 (可选，使用 `tsx` 进行热重载)**: 为了方便开发，你可以使用 `tsx` 直接运行 TypeScript 文件，它支持热重载。 ```bash # 如果未全局安装 tsx，可以运行 npx tsx src/index.ts ``` 或者通过 `package.json` 中定义的脚本： ```bash npm run dev # 如果有定义，目前package.json中没有此脚本，可自行添加 ``` ## 4. 代码结构详解 项目采用清晰的模块化结构，主要目录和文件如下： ``` exa-mcp-server/ ├── .github/ # GitHub Actions 配置文件 (如果存在) ├── .smithery/ # Smithery CLI 生成的构建产物目录 ├── src/ # 源代码目录 │ ├── index.ts # MCP 服务器入口点，工具注册逻辑 │ ├── types.ts # 全局类型定义，特别是 Exa AI API 相关的接口 │ ├── tools/ # Exa AI 工具实现目录 │ │ ├── companyResearch.ts # 公司研究工具 │ │ ├── config.ts # Exa AI API 配置，如 baseURL, endpoints │ │ ├── crawling.ts # 网页抓取工具 │ │ ├── deepResearchCheck.ts # 深度研究状态检查工具 │ │ ├── deepResearchStart.ts # 深度研究启动工具 │ │ ├── exaCode.ts # Exa 代码搜索工具 │ │ ├── linkedInSearch.ts# LinkedIn 搜索工具 │ │ └── webSearch.ts # 网络搜索工具 │ └── utils/ # 通用工具函数目录 │ └── logger.ts # 日志记录工具 ├── Dockerfile # Docker 容器化配置 ├── LICENSE # 项目许可证 ├── README.md # 项目 README 文件，包含基本使用说明 ├── package.json # 项目元数据和依赖管理 ├── package-lock.json # 锁定依赖版本 ├── server.json # MCP 服务器配置 (可能用于Smithery CLI) ├── smithery-example.json # Smithery 示例配置 ├── smithery.yaml # Smithery CLI 配置文件 └── tsconfig.json # TypeScript 编译器配置 ``` ## 5. 核心模块深度解析 ### 入口模块 [`src/index.ts`](src/index.ts) 这是 MCP 服务器的启动文件。它负责： * 导入 `@modelcontextprotocol/sdk/server/mcp.js` 中的 `McpServer` 类。 * 根据 `config.enabledTools` 数组动态注册各种 Exa AI 工具。 * 使用 `Zod` 定义和验证服务器的配置结构。 * 初始化 `McpServer` 实例并启动。 **关键代码片段：** ```typescript // src/index.ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { z } from 'zod'; import { registerWebSearchTool } from './tools/webSearch'; // ... 导入其他工具 const ServerConfigSchema = z.object({ // ... 配置定义 enabledTools: z.array(z.string()).default(['web_search_exa']), }); const config = ServerConfigSchema.parse(process.env); // 从环境变量解析配置 const server = new McpServer(); if (config.enabledTools.includes('web_search_exa')) { registerWebSearchTool(server); } // ... 根据配置注册其他工具 server.start(); ``` ### 类型定义 [`src/types.ts`](src/types.ts) 该文件是整个项目中数据模型的单一真相来源。它定义了所有与 Exa AI API 交互的请求和响应数据结构，以及工具的输入参数接口。这确保了类型安全，并在开发过程中提供了强大的代码提示。 **重要接口示例：** * `ExaSearchRequest`, `ExaSearchResult`: Exa AI 搜索 API 的请求和响应结构。 * `ExaCrawlRequest`: Exa AI 爬取 API 的请求结构。 * `DeepResearchRequest`, `DeepResearchStartResponse`, `DeepResearchCheckResponse`: 深度研究工具的请求和响应。 * `SearchArgs`: 通用搜索工具的输入参数接口。 ### 工具模块 (`src/tools/`) 此目录包含每个 Exa AI 工具的具体实现。每个文件通常导出一个 `register<ToolName>Tool` 函数，该函数接收 `McpServer` 实例作为参数，并使用 `server.registerTool()` 方法注册该工具。 **每个工具文件通常包含：** * **Zod Schema**: 定义工具的输入参数的运行时验证 Schema。 * **工具函数**: 核心逻辑，负责构造 Exa AI API 请求，调用 `axios` 发送请求，处理响应，并格式化结果。 * **错误处理**: 包含 `try-catch` 块，用于捕获和处理 API 调用过程中可能发生的错误。 **示例 (`src/tools/webSearch.ts`)：** ```typescript // src/tools/webSearch.ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { z } from 'zod'; import axios from 'axios'; import { API_CONFIG } from './config'; import { ExaSearchRequest, ExaSearchResult } from '../types'; import { createRequestLogger } from '../utils/logger'; const WebSearchArgsSchema = z.object({ query: z.string(), num_results: z.number().int().min(1).max(10).default(5), // ... 其他参数 }); export function registerWebSearchTool(server: McpServer) { server.registerTool({ name: 'web_search_exa', description: 'Searches the web using Exa AI.', parameters: WebSearchArgsSchema, handler: async (args, context) => { const logger = createRequestLogger(context.requestId, 'web_search_exa'); try { logger.log('Starting web search...'); const requestBody: ExaSearchRequest = { query: args.query, numResults: args.num_results, // ... 映射其他参数 }; const response = await axios.post<ExaSearchResult>( `${API_CONFIG.baseURL}${API_CONFIG.endpoints.search}`, requestBody, { headers: { 'x-api-key': process.env.EXA_API_KEY }, timeout: API_CONFIG.timeout, } ); logger.log('Web search completed.'); return { type: 'text', content: JSON.stringify(response.data.results), // 格式化结果 }; } catch (error) { logger.error('Web search failed:', error); return { type: 'text', content: `Error: ${error.message}`, isError: true, }; } }, }); } ``` ### 通用工具模块 [`src/utils/logger.ts`](src/utils/logger.ts) 提供了一个简单的、基于控制台的日志记录器。它支持记录请求的开始、中间状态、错误和完成，并包含 `requestId` 和 `toolName` 以便追踪。可以通过 `config.debug` 环境变量控制调试日志的输出。 ## 6. API 接口说明 本项目暴露的每个工具都对应 Exa AI 的一个特定功能。以下是主要工具的接口说明，包括其参数和预期返回值。 **通用返回结构：** 所有工具成功执行后，通常会返回一个包含 `type: "text"` 和 `content` 字段的对象。`content` 字段通常是 JSON 字符串，包含 Exa AI API 返回的原始数据或其精简版本。 如果发生错误，返回对象将包含 `isError: true` 和 `content` 中的错误信息。 ### Web Search Tool (`web_search_exa`) * **描述**: 使用 Exa AI 进行网络搜索。 * **参数**: * `query` (string, required): 搜索查询字符串。 * `num_results` (number, optional, default: 5): 返回的搜索结果数量 (1-10)。 * `start_published_date` (string, optional): 仅返回在此日期之后发布的页面 (ISO 8601 格式)。 * `end_published_date` (string, optional): 仅返回在此日期之前发布的页面 (ISO 8601 格式)。 * `domain` (string, optional): 仅搜索特定域名。 * `exclude_domains` (string[], optional): 排除特定域名。 * `category` (string, optional): 搜索特定类别的内容。 * `exclude_categories` (string[], optional): 排除特定类别的内容。 * `sort_by` (string, optional, default: "relevance"): 结果排序方式 ("relevance", "recency")。 * `highlights` (boolean, optional, default: false): 是否包含搜索结果中的高亮片段。 * `text` (boolean, optional, default: false): 是否包含搜索结果的纯文本内容。 * `url` (boolean, optional, default: false): 是否包含搜索结果的 URL。 * **返回值示例**: ```json [ { "title": "...", "url": "...", "publishedDate": "...", "highlights": ["..."], "text": "..." }, // ... 更多结果 ] ``` ### Company Research Tool (`company_research_exa`) * **描述**: 对特定公司进行研究。 * **参数**: * `company_name` (string, required): 公司名称。 * `num_results` (number, optional, default: 5): 返回的搜索结果数量 (1-10)。 * `highlights` (boolean, optional, default: false): 是否包含搜索结果中的高亮片段。 * `text` (boolean, optional, default: false): 是否包含搜索结果的纯文本内容。 * `url` (boolean, optional, default: false): 是否包含搜索结果的 URL。 * **返回值示例**: 同 `web_search_exa` 的结果结构，但内容侧重于公司信息。 ### Crawling Tool (`crawl_exa`) * **描述**: 抓取指定 URL 的内容。 * **参数**: * `url` (string, required): 要抓取的 URL。 * **返回值示例**: ```json { "url": "...", "title": "...", "text": "...", "html": "..." } ``` ### LinkedIn Search Tool (`linkedin_search_exa`) * **描述**: 在 LinkedIn 上搜索人物或公司。 * **参数**: * `query` (string, required): 搜索查询字符串。 * `search_type` (string, optional, default: "people"): 搜索类型 ("people", "companies")。 * `num_results` (number, optional, default: 5): 返回的搜索结果数量 (1-10)。 * **返回值示例**: ```json [ { "name": "...", "profileUrl": "...", "headline": "...", "company": "..." }, // ... 更多结果 ] ``` ### Deep Research Start Tool (`deep_research_start_exa`) * **描述**: 启动一个深度研究任务。 * **参数**: * `query` (string, required): 深度研究的查询字符串。 * **返回值示例**: ```json { "researchId": "unique_research_id", "status": "started", "message": "Deep research initiated." } ``` ### Deep Research Check Tool (`deep_research_check_exa`) * **描述**: 检查一个深度研究任务的状态和结果。 * **参数**: * `research_id` (string, required): 由 `deep_research_start_exa` 返回的研究 ID。 * **返回值示例**: * **进行中**: ```json { "researchId": "unique_research_id", "status": "in_progress", "progress": 50, "message": "Research is still ongoing." } ``` * **已完成**: ```json { "researchId": "unique_research_id", "status": "completed", "result": { "summary": "...", "sources": [ {"title": "...", "url": "..."}, // ... ] } } ``` * **失败**: ```json { "researchId": "unique_research_id", "status": "failed", "message": "Research failed due to an error." } ``` ### Exa Code Tool (`exa_code_exa`) * **描述**: 使用 Exa AI 进行代码上下文搜索。 * **参数**: * `query` (string, required): 代码搜索查询字符串。 * `num_results` (number, optional, default: 5): 返回的搜索结果数量 (1-10)。 * `repo_url` (string, optional): 限制搜索到特定的 GitHub 仓库 URL。 * **返回值示例**: ```json [ { "repo": "...", "path": "...", "language": "...", "code": "...", "highlights": ["..."] }, // ... 更多结果 ] ``` ## 7. 构建/测试/部署流程 ### 7.1 编译 项目使用 TypeScript 编写，需要编译成 JavaScript 才能运行。 * **TypeScript 编译器**: `tsc` * **`tsconfig.json` 配置**: * `target: ES2022`: 目标 JavaScript 版本。 * `module: Node16`: 模块系统。 * `moduleResolution: Node16`: 模块解析策略。 * `outDir: ./build`: 编译输出目录。 * **构建脚本 (`package.json`)**: * `"build:stdio"`: 构建用于 `stdio` 传输方式的 MCP 服务器。 * `"build:shttp"`: 构建用于 `shttp` 传输方式的 MCP 服务器。 * `"build"`: 默认执行 `build:shttp`。 * `"prepare"` 和 `"prepublishOnly"` 脚本也会执行 `build:stdio`，确保发布前代码已编译。 **执行编译**: ```bash npm run build # 或者针对特定传输方式 npm run build:stdio npm run build:shttp ``` 编译后的产物位于 `.smithery/index.cjs`。 ### 7.2 测试 **痛点**: 当前项目缺乏明确的自动化测试脚本 (`package.json` 中缺少 `test` 脚本)。 **建议**: * **单元测试**: 为每个工具函数和核心逻辑编写单元测试，确保其独立功能的正确性。推荐使用 `Jest` 或 `Vitest`。 * **集成测试**: 模拟 MCP 客户端调用，测试整个服务器到 Exa AI API 的集成流程。 * **端到端测试**: 在真实的部署环境中测试完整的用户场景。 ### 7.3 打包与部署 项目提供了 `Dockerfile` 支持 Docker 容器化部署。 **`Dockerfile` 概览**: * **多阶段构建**: 包含 `builder` 和 `runner` 两个阶段，以优化最终镜像大小。 * `builder` 阶段负责安装所有依赖并编译代码。 * `runner` 阶段只安装生产依赖，并将编译产物复制过来，生成一个精简的运行时镜像。 * **依赖安装**: * `builder`: `npm ci --ignore-scripts` (安装所有依赖) * `runner`: `npm ci --production --ignore-scripts` (只安装生产依赖) * **编译**: 在 `builder` 阶段执行 `npm run build`。 * **环境变量**: 强制要求通过 `ENV EXA_API_KEY=your-api-key-here` 设置 Exa AI API Key。**在实际部署时，务必替换为你的实际 API Key，或通过 Docker 运行时参数注入。** * **端口暴露**: 暴露端口 `3000`。 * **启动命令**: `ENTRYPOINT ["node", ".smithery/index.cjs"]` 启动编译后的服务器。 **部署步骤示例 (使用 Docker):** 1. **构建 Docker 镜像**: ```bash docker build -t exa-mcp-server . ``` 2. **运行 Docker 容器**: ```bash docker run -d -p 3000:3000 --name exa-mcp-instance -e EXA_API_KEY=your_actual_exa_api_key_here exa-mcp-server ``` 请将 `your_actual_exa_api_key_here` 替换为你的 Exa AI API Key。 ## 8. 贡献指南 我们欢迎社区对 `exa-mcp-server` 项目的贡献！请遵循以下指南： 1. **Fork 项目**: 在 GitHub 上 Fork `exa-mcp-server` 仓库。 2. **创建分支**: 从 `main` 分支创建新的功能分支 (`git checkout -b feature/your-feature-name`)。 3. **编码**: * 遵循现有的编码风格和 TypeScript 最佳实践。 * 确保所有新增或修改的代码都有相应的类型定义和 Zod Schema 验证。 * 为你的功能编写清晰的注释和文档。 4. **测试**: * **重要**: 为你的修改添加单元测试和/或集成测试。 * 运行现有测试 (如果已添加)。 5. **提交**: 使用有意义的提交信息 (`git commit -m "feat: Add new feature X"`)。 6. **推送**: 将你的分支推送到你的 Fork (`git push origin feature/your-feature-name`)。 7. **创建 Pull Request**: 向 `exa-mcp-server` 的 `main` 分支提交 Pull Request。请在 PR 描述中详细说明你的修改内容、解决的问题以及如何测试。 ## 9. 常见问题解答及故障排除 ### Q: 如何获取 Exa AI API Key？ A: 请访问 [Exa AI 官方网站](https://exa.ai/) 注册并获取你的 API Key。 ### Q: 服务器无法启动，提示 `EXA_API_KEY` 未定义。 A: 确保你已通过环境变量正确设置了 `EXA_API_KEY`。在开发环境中，可以在运行命令前设置，或在 `.env` 文件中定义。在 Docker 中，使用 `-e EXA_API_KEY=...` 参数。 ### Q: 某个工具调用失败，返回 `isError: true`。 A: 检查 `content` 字段中的错误信息，它通常包含 Exa AI API 返回的详细错误。 * **AxiosError**: 可能是网络问题、Exa AI API 不可用、API Key 无效或请求参数错误。检查你的网络连接和 API Key。 * **ZodError**: 表示你传递给工具的参数不符合预期的 Schema。检查你的输入参数。 * 查看 `src/utils/logger.ts` 产生的日志，它们会提供请求生命周期中的详细信息。 ### Q: 如何添加一个新的 Exa AI 工具？ A: 1. 在 `src/tools/` 目录下创建一个新的 TypeScript 文件 (例如 `src/tools/newTool.ts`)。 2. 在该文件中定义工具的 Zod Schema、实现与 Exa AI API 的交互逻辑，并导出一个 `registerNewTool` 函数。 3. 在 `src/index.ts` 中导入 `registerNewTool` 函数。 4. 在 `src/index.ts` 的 `ServerConfigSchema` 中添加新的工具名称到 `enabledTools` 的默认值或允许列表中。 5. 在 `src/index.ts` 中，根据 `config.enabledTools` 的条件判断，调用 `registerNewTool(server)` 来注册你的新工具。 ### Q: 如何启用或禁用特定的工具？ A: 服务器启动时会读取 `enabledTools` 配置。你可以在 `server.json` 或通过环境变量配置这个列表。例如，在 `server.json` 中： ```json { "enabledTools": ["web_search_exa", "crawling_exa"] } ``` 或者在运行命令时设置环境变量 `ENABLED_TOOLS='["web_search_exa", "crawling_exa"]'` (注意 JSON 字符串的转义)。 ### Q: Mermaid 图解析错误？ A: Mermaid 图对语法有严格要求，常见的错误及解决方案如下： | 问题类型 | 具体表现 | 导致错误信息 | 解决方案 | | :--- | :--- | :--- | :--- | | **节点文本中的双引号** | 在 `graph TD` 或 `graph LR` 图的节点文本 (`[]` 或 `()`) 中直接使用双引号，例如 `E[提交信息: "Initial commit: ..."]` | `Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', ..., got 'STRING'` (或类似指示引号位置的错误) | 移除节点文本中的双引号，使其成为纯文本。例如，改为 `E[提交信息: Initial commit: ...]` | | **节点文本中的括号 (歧义)** | 在 `graph TD` 或 `graph LR` 图的 `[]` 形状节点文本中包含括号 `()`，例如 `G[已修改文件 (2个)]`，或者在应该使用 `[]` 的地方错误使用了 `()` 定义节点 (如 `G1(models/...)`)。 | `Parse error: Expecting 'SQE', 'DOUBLECIRCLEEND', ..., got 'PS'` (PS 通常指 Parenthesis Start) | 将包含路径和描述的节点形状从圆角矩形 `()` 改为标准矩形 `[]`。同时，从 `[]` 形状的节点文本中移除可能引起冲突的括号及其内部数字，例如将 `G[已修改文件 (2个)]` 改为 `G[已修改文件]`。 | | **链接文本中的括号** | 在链接文本中使用了括号 `()`，例如 `A -->|Tool Call (e.g., web_search_exa)| B` | `Parse error: Expecting 'SQE', 'DOUBLECIRCLEEND', ..., got 'PS'` | 移除链接文本中的括号。例如，改为 `A -->|Tool Call| B`。 | | **subgraph 标题中的括号** | 在 `subgraph` 标题中使用了括号 `()`，例如 `subgraph 提交历史 (master分支)` | `Parse error: Expecting 'SEMI', 'NEWLINE', ..., got 'PS'` | 移除 `subgraph` 标题中的括号。例如，改为 `subgraph 提交历史 master分支`。 | | **gitGraph 图中不支持的注释** | 在 `gitGraph` 语法块内部使用 `comment:` 关键字进行注释，例如 `comment: "通过git reset --hard..."` | `Error: Parsing failed: Expecting token of type 'EOF' but found comment;` | `gitGraph` 语法不支持直接在内部使用 `comment:` 关键字。应将注释移到 Mermaid 代码块外部的文本说明中，或使用 `tag:` 属性关联到提交。 | | **链接文本定义语法错误** | 在定义链接文本时使用了冒号 `:`，例如 `A --> C : "Docker CLI Comman"` | `Expecting 'SEMI', 'NEWLINE', 'EOF', 'AMP', 'START_LINK', 'LINK', 'LINK_ID', got 'COLON'` | 将文本直接跟在箭头后面，用双引号包裹，例如 `A -- "Docker CLI Commands" --> B`，或者使用 `|` 符号，例如 `A -->|"Docker CLI Commands"| B` | | **节点定义后的分号** | `mermaid` 节点定义末尾存在分号，例如 `A[文本];` | `Parse error: Expecting ... got ';'` | 移除节点定义末尾的分号，例如 `A[文本]` | | **节点文本中的列表格式** | 节点文本中包含数字和点号，例如 `A[1. 文本]` | `Unsupported markdown: list` | 移除节点文本中的数字和点号，例如 `A[文本]` | | **浏览器缓存问题** | 修复语法后，Mermaid 图在浏览器中仍显示旧版本 | 浏览器缓存了旧的渲染结果 | 清除浏览器缓存，或者使用浏览器的无痕模式/隐私模式打开文件，强制浏览器重新加载最新内容。 | ## 10. 未来改进方向 基于代码库分析和痛点识别，以下是项目未来的改进方向： 1. **引入自动化测试框架**: 添加 Jest/Vitest 等测试框架，并为核心模块和工具函数编写单元测试和集成测试，提升代码质量和可维护性。 2. **增强配置管理**: 考虑使用更健壮的配置管理方案（如 `config` 库或更完善的 `.env` 处理），允许更灵活地管理 API Key、API URL 和其他运行时配置，而非硬编码 `API_CONFIG`。 3. **细化日志记录**: 引入更专业的日志库（如 `winston` 或 `pino`），支持不同日志级别、日志文件输出、日志轮转等功能，以适应生产环境的需求。 4. **API Key 安全管理**: 探索更安全的 API Key 管理方案，例如与云服务商的秘密管理服务集成，避免直接在 `Dockerfile` 中提示替换。 5. **异步操作取消机制**: 对于长时间运行的深度研究或其他异步任务，考虑实现明确的取消机制，允许客户端中断请求。 6. **更友好的错误信息**: 优化错误信息的结构和内容，使其对不同层级的用户（开发者、最终用户）更具可读性和可操作性。 7. **性能优化**: 对高并发或计算密集型操作进行性能分析和优化，例如使用连接池、缓存机制等。 8. **文档自动化**: 探索从代码注释（如 JSDoc）自动生成 API 文档的工具，减少手动维护文档的工作量。 9. **增加更多 Exa AI 工具**: 随着 Exa AI 功能的扩展，集成更多有用的工具。