# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Removed
- **工具**：删除 fetch_and_summarize 和 batch_fetch 工具
- 简化架构，聚焦核心 web_search 功能
- 删除重复的抓取逻辑，统一使用 Creeper
- 相关文件：`src/tools/fetch-summary.ts`, `src/tools/batch-fetch.ts`, `src/services/fetcher.ts`
### Added
- **AI 智能过滤**：实现 LLM 驱动的搜索结果智能过滤
### Fixed
- **配置错误**：修复 LLM 智能过滤的 API 配置
- **调试配置**：修复 VS Code 调试配置中的 tsx 路径错误
- 相关文件：`.vscode/launch.json`
- 更正 FILTER_LLM_MODEL 为智谱格式 `glm-4.5-air`
- 确保与 FILTER_LLM_BASE_URL 的智谱 API 端点匹配
- 相关文件：`.env`
- 单次 LLM 调用同时完成主题分类和关联性过滤，成本优化
- 支持 10 种主题类型：编程、军事、政治、历史、科学、科技、娱乐、体育、金融、其他
- 返回 JSON 格式：`{"topic": "xxx", "keep": [1, 3, 5]}`
- 独立 LLM 配置，可与总结服务使用不同模型
- 相关文件：`src/services/filter-llm.ts`, `src/prompts/filter.ts`
- **主题驱动总结**：根据搜索主题自动选择最优总结提示词
- 编程类：保留代码、API 用法、版本兼容性信息
- 历史类：时间线、因果关系、争议观点
- 军事类：技术参数、客观事实
- 政治类：多元观点平衡、事实与观点区分
- 其他类型：science, technology, entertainment, sports, finance 等
- 相关文件：`src/prompts/summary/`（10 个主题文件）
- **提示词管理重构**：集中管理所有提示词到独立目录
- 创建 `src/prompts/` 目录，分类管理各类提示词
- 迁移现有提示词：总结提示词、Map-Reduce 提示词
- 实现主题提示词选择器函数
- 相关文件：`src/prompts/index.ts`, `src/prompts/map-reduce.ts`
- **环境变量扩展**：新增 LLM 过滤配置项
- `FILTER_LLM_ENABLED`：是否启用智能过滤（默认 false）
- `FILTER_LLM_API_KEY`：独立的过滤服务 API Key
- `FILTER_LLM_BASE_URL`：过滤服务 API 地址
- `FILTER_LLM_MODEL`：过滤使用的模型（可用轻量模型）
- `FILTER_LLM_TIMEOUT`：过滤请求超时时间
- 相关文件：`.env.example`, `src/utils/config.ts`
### Changed
- **重构**：Creeper 内容保存方式
- 将多文件保存模式重构为单文件保存模式
- 单次爬取的所有网页内容合并保存到一个 Markdown 文件
- 使用查询关键词作为文件名
- 移除原有的单页面保存逻辑
- 相关文件：`src/utils/file-saver.ts`, `src/services/creeper.ts`, `src/tools/web-search.ts`
### Fixed
- **输入验证**：修复 web_search 工具查询参数验证错误
- 增强字符串验证，拒绝空字符串和仅包含空格字符的查询
- 自动清理查询前后空格，提升用户体验
- 相关文件：`src/tools/web-search.ts`, `src/server.ts`
- **配置错误**：修复 Creeper 服务超时配置解析错误
- 将 `.env` 文件中的 `CREEPER_TIMEOUT=5 * 60 * 1000` 改为 `CREEPER_TIMEOUT=300000`
- 解决环境变量不支持数学表达式导致的超时时间为 0ms 的问题
- 修复系统不稳定、MCP Inspector 进程反复创建销毁的问题
- 相关文件：`.env`
- **代码结构**：修复提示词占位符重复定义和缺失问题
- 删除 `web-search.ts` 中重复的 `SEARCH_SUMMARY_PROMPT` 定义
- 从 `summarizer.ts` 导入提示词，遵循模块单一职责原则
- 确保提示词正确包含 `{content}` 占位符
- 相关文件：`src/services/summarizer.ts`, `src/tools/web-search.ts`
### Fixed
- **调试配置**：修复 VSCode 调试配置中 MCP Inspector 模块路径问题
- 将错误的本地路径 `${workspaceFolder}/node_modules/@modelcontextprotocol/inspector/dist/cli.js` 改为直接使用命令 `mcp-inspector`
- 添加环境变量文件加载，确保调试环境配置正确
- 相关文件：`.vscode/launch.json`, `.vscode/tasks.json`
### Fixed
- **类型错误**：修复 SummarizerService 调用返回类型不匹配问题
- 修复 `summarize()` 方法返回 `SummaryResponse` 而非直接字符串的问题
- 更新 `web-search.ts` 和 `map-reduce.ts` 中的所有调用方式
- 修复 `ResultFilter` 中 `maxResults` 属性重复指定的问题
- 相关文件：`src/tools/web-search.ts`, `src/utils/map-reduce.ts`, `src/services/filter.ts`
### Changed
- **架构重构**：替换 Tavily 为 SearXNG + Creeper 搜索方案
- 删除 Tavily MCP 客户端依赖，改为直接调用 SearXNG HTTP API
- 集成 Python Creeper 爬虫，支持动态渲染的网页内容获取
- 新增规则过滤器替代 LLM 过滤，节省调用成本
- 实现 Map-Reduce 智能总结策略，根据内容大小自动选择单次或分阶段总结
- 相关文件：`src/services/searxng.ts`, `src/services/creeper.ts`, `src/services/filter.ts`, `src/utils/map-reduce.ts`
- 删除文件：`src/services/tavily.ts`
### Added
- **SearXNG 集成**：实现 SearXNG 搜索服务
- 支持 JSON API 调用，获取结构化搜索结果
- 支持语言、时间范围、结果数量等参数配置
- 添加连接测试和错误处理机制
- 相关文件：`src/services/searxng.ts`
- **Creeper 集成**：实现 Python Creeper 子进程调用
- 支持批量 URL 爬取，并发数可配置
- 解析 JSON 输出，统一为 CreeperResult 格式
- 添加超时控制和进程管理
- 相关文件：`src/services/creeper.ts`
- **规则过滤器**：基于规则而非 LLM 的搜索结果过滤
- 支持域名黑白名单过滤
- 保留指定数量的高质量结果
- 白名单域名优先排序
- 相关文件：`src/services/filter.ts`
- **Map-Reduce 总结**：处理大量内容的智能总结
- 自动拆分大内容为小块（chunk）
- 并行提取每个网页的关键点（Map 阶段）
- 合并所有关键点生成最终总结（Reduce 阶段）
- 支持并发控制和超时管理
- 相关文件：`src/utils/map-reduce.ts`
- **测试用例**：添加 SearXNG 功能测试
- 创建完整的测试用例覆盖基本搜索、语言设置、时间范围、域名过滤等场景
- 测试错误处理和边界条件
- 相关文件：`tests/inspector/searxng.test.json`
### Changed
- **web_search 工具**：完全重写实现逻辑
- 输入参数更新：移除 search_depth，新增 language 和 time_range
- 执行流程：SearXNG 搜索 → 规则过滤 → Creeper 爬取 → 智能总结
- 根据内容总大小自动选择单次总结或 Map-Reduce 总结
- 优化输出格式，包含成功/失败来源统计
- 相关文件：`src/tools/web-search.ts`
- **配置系统**：更新环境变量配置
- 新增必需配置：SEARXNG_BASE_URL、CREEPER_PATH
- 新增可选配置：SEARXNG_TIMEOUT、CREEPER_CONCURRENCY、FILTER_MAX_RESULTS、DOMAIN_BLACKLIST、DOMAIN_WHITELIST、MAP_REDUCE_THRESHOLD 等
- 删除配置：TAVILY_MCP_PATH、TAVILY_API_KEY
- 更新配置结构，支持新服务的参数
- 相关文件：`src/utils/config.ts`, `src/types/index.ts`, `.env.example`
- **服务器初始化**：更新服务创建流程
- 删除 TavilyService，新增 SearXNGService 和 CreeperService
- 添加服务连接测试和警告机制
- 更新工具描述和输入 schema
- 相关文件：`src/server.ts`
### Fixed
- **数据处理**：修复 Tavily 搜索结果多数据解析问题
- 添加结构化文本解析逻辑，支持解析 Title/URL/Content 格式的多个搜索结果
- 修复之前只返回第一条搜索结果的问题，确保所有结果都能传递给 LLM
- 相关文件：`src/services/tavily.ts`
### Added
- **测试**：集成 MCP Inspector 测试框架
- 添加 `.mcp-inspector.json` 配置文件，支持自动化测试所有 MCP 工具
- 创建完整的测试用例集合覆盖所有工具功能
- 支持错误处理和边界条件测试
- 相关文件：`.mcp-inspector.json`, `tests/inspector/*`, `package.json`
### Added
- **可靠性**：实现 LLM 总结智能重试机制
- 添加指数退避重试逻辑，默认重试 2 次，等待时间递增（2秒、4秒）
- 实现智能错误分类：可重试错误（网络超时、连接中断、aborted）vs 不可重试错误（认证失败、请求格式错误）
- 增强超时配置，默认从 60 秒增加到 120 秒，可通过 `SUMMARY_TIMEOUT` 环境变量自定义
- 添加 `SUMMARY_MAX_RETRIES` 环境变量配置重试次数
- 相关文件：`src/services/summarizer.ts`, `src/utils/config.ts`, `src/types/index.ts`, `.env.example`
- **开发工具**：创建 MCP Inspector 启动脚本
- 创建 `test-server.js` 启动脚本，支持 MCP Inspector 测试环境
- 添加构建检查和错误处理，确保开发体验流畅
- 自动处理环境变量和进程管理，简化测试流程
- 相关文件：`test-server.js`, `.mcp-inspector.json`
- **用户体验**：修复 LLM 总结中缺少网页链接的问题
- 改进搜索总结提示词，使用明确的【来源编号】引用格式
- 优化搜索结果格式化，确保来源信息在总结内部被引用
- 改进最终输出格式，使用 Markdown 粗体和缩进提高来源信息的可读性
- 实现双重保障机制：总结内引用 + 独立来源列表
- 相关文件：`src/services/summarizer.ts`, `src/tools/web-search.ts`
### Fixed
- **URL**：修复 LLM API URL 拼接导致的 404 错误
- 修复代码中重复 `/v1` 路径段的问题，从 `${baseUrl}/v1/chat/completions` 改为 `${baseUrl}/chat/completions`
- 解决因 URL 构建错误导致的双重路径段问题（如 `https://api.deepseek.com/v1/v1/chat/completions`）
- 确保 web_search 工具的 LLM 总结功能正常工作
- 相关文件：`src/services/summarizer.ts`
- **协议**：修复 MCP 协议 JSON 解析错误
- 修复 dotenv v17.2.3 日志输出污染 MCP stdio 通信通道的问题
- 使用 `config({ quiet: true })` 禁用 dotenv 日志输出，确保 MCP 协议通信纯净
- 解决 SyntaxError: Unexpected token 'd', "[dotenv@17."... is not valid JSON 错误
- 相关文件：`src/index.ts`
- **API**：修复 LLM summarization 404 错误
- 更新 ModelScope API 端点从旧版本 `https://api-inference.modelscope.cn/v1/` 到 2025 年兼容端点 `https://dashscope.aliyuncs.com/compatible-mode`
- 解决因端点 URL 过期导致的 Request failed with status code 404 错误
- 更新 `.env.example` 提供多种 LLM 服务配置选项（DeepSeek 官方 API 和 ModelScope API）
- 相关文件：`.env`, `.env.example`
- **配置**：修复 MCP Inspector 配置文件格式错误
- 将配置键从 `servers` 改为 `mcpServers` 以符合 Inspector 规范
- 创建 `test-server.js` 包装脚本避免 npm 输出干扰 MCP 协议
- 相关文件：`.mcp-inspector.json`, `test-server.js`
- **环境变量**：修复缺失环境变量导致的启动失败
- 更新 `.env.example` 提供清晰的配置示例
- 在 `test-server.js` 中添加 .env 文件检查和友好错误提示
- 改进 README.md 的配置步骤说明
- 相关文件：`.env.example`, `test-server.js`, `README.md`
- **配置加载**：修复 .env 文件未被自动加载的问题
- 安装并配置 dotenv 包自动加载环境变量
- 在入口文件 src/index.ts 中添加 config() 调用
- 确保 .env 文件中的配置能被正确读取
- 相关文件：`package.json`, `src/index.ts`
- **工具名称**：修复 tavily-mcp 工具名称不匹配问题
- 将调用从 `tavily_search` 改为 `tavily-search` 以匹配 tavily-mcp 的实际工具名称
- 更新相关文档中的工具名称引用
- 解决 "MCP error -32601: Unknown tool" 错误
- 相关文件：`src/services/tavily.ts`, `docs/features/tavily-mcp-client.md`
- **LLM 处理逻辑**：修复 web_search 工具未触发 LLM 处理的问题
- 优化判断条件：内容长度超过阈值、多个结果或单个长结果都会触发 LLM 总结
- 将单个结果触发阈值从 50000 字符降低到 1000 字符，提高 LLM 处理频率
- 添加详细日志记录触发原因（content too long/multiple results/single long result）
- 相关文件：`src/tools/web-search.ts`
### Changed
- **Tavily 集成方式**：从直接调用 Tavily HTTP API 改为通过 MCP 客户端调用 tavily-mcp 服务
- 新增 `TAVILY_MCP_PATH` 环境变量配置 tavily-mcp 路径
- TavilyService 改为 MCP Client 实现，支持 `connect()` 和 `disconnect()` 生命周期管理
- 服务器启动时自动连接 tavily-mcp，退出时自动断开
- 相关文件：`src/services/tavily.ts`, `src/server.ts`, `src/utils/config.ts`
## [0.1.0] - 2025-12-04
### Added
- 初始化 Web Analysis MCP 项目
- 实现三个核心 MCP 工具：`web_search`、`fetch_and_summarize`、`batch_fetch`
- 集成 Tavily 搜索 API 和 DeepSeek LLM 总结服务
- 配置管理、日志和缓存工具模块
