# Creeper 批量保存增强功能 - 需求文档
> 生成时间：2025-12-05
> 基于项目：Web Analysis MCP
> 技术栈：TypeScript + Node.js + MCP SDK
---
## 项目概况
**技术栈**：TypeScript + Node.js + MCP SDK + Zod
**架构模式**：分层架构（工具层、服务层、工具类）
**代码风格**：CamelCase 命名约定 / JSDoc 注释风格
---
## 改动点
### 要实现什么
- **核心功能 1**：将单次爬取的所有网页内容合并保存到一个 Markdown 文件中
- **核心功能 2**：使用查询关键词作为保存文件名
- **核心功能 3**：替换现有的多文件保存模式
### 与现有功能的关系
- **依赖现有模块**：
- `FileSaver` 类 - 重构为单文件保存模式
- `CreeperService` - 修改批量爬取逻辑
- `web-search.ts` - 传递查询关键词给保存逻辑
- **集成位置**：
- `src/utils/file-saver.ts` - 重构为单文件保存
- `src/services/creeper.ts:91` - 修改文件保存调用
- `src/tools/web-search.ts:91` - 传递查询参数
### 新增依赖
无需新增依赖（使用现有的 fs.promises 和 path 模块）
---
## 实现方案
### 需要修改的文件
```
src/utils/file-saver.ts # 修改内容：重构为单文件保存模式
src/services/creeper.ts # 修改内容：支持传递查询关键词
src/tools/web-search.ts # 修改内容：传递查询关键词给 Creeper
```
### 需要新增的文件
```
tests/features/creeper-batch-save/ # ⚠️ 测试文件必须保存在 tests/ 目录下
├── batch-save.test.json # MCP Inspector 测试用例
└── integration.test.md # 集成测试文档
```
### 实施步骤
**步骤 1：重构 FileSaver 类**
- [ ] 移除现有的 `saveContent` 方法（单文件保存）
- [ ] 将 `saveBatch` 方法重构为保存所有内容到单个文件
- [ ] 实现基于查询关键词的文件名生成逻辑
- [ ] 实现内容合并逻辑（保持每个页面的元数据）
**步骤 2：修改 CreeperService**
- [ ] 修改 `crawl` 方法签名，支持接收查询关键词参数
- [ ] 更新文件保存调用，使用新的单文件保存模式
- [ ] 移除原有的多文件保存逻辑
**步骤 3：更新工具层**
- [ ] 修改 `web-search.ts` 传递查询关键词给 Creeper
- [ ] 确保查询关键词安全传递和文件名清理
**步骤 5：测试**
- [ ] 创建 MCP Inspector 测试用例
- [ ] 测试单文件保存功能
- [ ] 测试文件名生成（特殊字符处理）
- [ ] **回归测试现有功能**（必须！）
**步骤 6：文档更新**（必须执行）
| 文档 | 需要更新 | 不需要更新 |
|------|----------|-----------|
| **CHANGELOG.md** | ✅ 新增批量保存功能 | - |
| **README.md** | ❓ 功能对用户可见 | - |
| **CLAUDE.md** | ✅ 文件保存行为变更 | - |
**CHANGELOG.md 更新**：
```markdown
### Changed
- **重构**：Creeper 内容保存方式
- 将多文件保存模式重构为单文件保存模式
- 单次爬取的所有网页内容合并保存到一个 Markdown 文件
- 使用查询关键词作为文件名
- 移除原有的单页面保存逻辑
- 相关文件：`src/utils/file-saver.ts`, `src/services/creeper.ts`
```
**步骤 7：提交代码**（必须执行）
```bash
git add .
git commit -m "refactor: 重构 Creeper 内容保存为单文件模式
- 移除原有的多文件保存逻辑
- 重构 FileSaver 类为单文件保存模式
- 修改 CreeperService 支持查询关键词传递
- 更新 web-search 工具传递查询参数
- 所有爬取内容现在合并保存到单个文件
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
**步骤 8：自我检查**
- [ ] 新功能是否按需求正常工作
- [ ] 现有功能是否正常（未被破坏）
- [ ] CHANGELOG.md 是否已更新
- [ ] README.md 是否按标准判断并更新
- [ ] CLAUDE.md 是否按标准判断并更新
- [ ] "实现步骤"与"需要修改/新增的文件"是否一致
- [ ] 所有相关文件是否已提交
---
## 使用方式
### API 调用示例
```typescript
// 单文件保存模式（新的默认行为）
const results = await creeperService.crawl(
urls,
saveToFile: true, // 启用保存
queryKeyword: 'Node.js' // 查询关键词作为文件名
);
// 保存结果示例：
// temp/2025-12-05/Node.js.md (包含所有爬取内容)
```
### 配置项
```typescript
// FileSaver 配置（简化后）
{
fileSave: {
enabled: true, // 启用文件保存
saveDir: 'temp', // 保存目录
organization: 'date' | 'flat', // 文件组织方式
}
}
```
### 输出文件格式
```markdown
# Node.js 搜索结果
**查询关键词**: Node.js
**爬取时间**: 2025-12-05T10:30:00.000Z
**包含页面**: 5 个
---
## 页面 1: Node.js 官方下载
**来源**: https://nodejs.org/en/download
**标题**: Node.js - Download
**爬取时间**: 2025-12-05T10:30:05.000Z
[页面内容...]
---
## 页面 2: Node.js 教程
**来源**: https://www.runoob.com/nodejs/nodejs-tutorial.html
**标题**: Node.js 教程 | 菜鸟教程
**爬取时间**: 2025-12-05T10:30:08.000Z
[页面内容...]
```
---
## 注意事项
**技术风险**：
- 文件名长度限制：查询关键词过长需要截断
- 特殊字符处理：确保文件名在不同操作系统下有效
- 文件大小控制：大量内容可能产生大文件
**破坏性变更**：
- ❌ 破坏性变更：移除原有的多文件保存模式
- 现有依赖 saveContent 的代码需要更新
- 文件保存行为完全改变
**性能考虑**：
- 批量保存减少文件 I/O 次数
- 内存使用：需要在内存中合并所有内容
- 建议对大型内容集合谨慎使用
