feat: 初始化MedResearcher项目

- 添加项目配置文件（pyproject.toml） - 添加Python版本配置（.python-version） - 添加项目文档（README.md, CLAUDE.md） - 添加Git配置（.gitignore）
2025-08-23 00:20:41 +08:00 · 2025-08-23 00:20:41 +08:00 · 8213ae9a55
commit 8213ae9a55
6 changed files with 514 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.claude
--- a/.python-version
+++ b/.python-version
@ -0,0 +1 @@
+3.13
--- a/CLAUDE-temp.md
+++ b/CLAUDE-temp.md
@ -0,0 +1,283 @@
+# AI指导规范构建任务 - 深度分析
+
+## 任务理解
+用户希望为MedResearcher项目构建一套完整的AI协作指导规范，核心思想是"充分讨论后再修改"，以避免代码难以维护。
+
+## 核心设计理念
+1. **讨论优先**：任何修改前必须充分讨论，达成共识
+2. **上下文明确**：不仅指出需要什么，更要具体到哪个文件的哪个函数
+3. **渐进式实施**：通过子任务分解，逐步完成复杂需求
+4. **可追溯性**：所有决策和修改都有明确记录
+
+## 详细工作流程设计
+
+### 阶段1：需求理解与记录（必须执行）
+**触发条件**：用户提出任何代码修改需求
+
+**具体步骤**：
+1. **立即**在CLAUDE-temp.md中撰写：
+   ```markdown
+   ## 任务理解
+   原始需求：[用户的原话]
+   我的理解：[用我的话重述一遍]
+   
+   ## 收集的上下文
+   ### 相关文件和函数
+   - `papers_crawler.py::line_45-67::fetch_papers()` - 当前的爬取实现
+   - `config.py::line_12-15::RETRY_CONFIG` - 现有重试配置
+   
+   ### 现有代码分析
+   [贴出关键代码片段并分析]
+   
+   ### 潜在影响
+   - 影响文件：papers_crawler.py, test_crawler.py
+   - 影响功能：论文爬取的稳定性
+   - 风险评估：可能影响爬取速度
+   
+   ## 任务复杂度判断
+   - [ ] 单一功能修改，影响1-2个函数 → 简单任务
+   - [x] 需要修改3个以上函数或添加新模块 → 复杂任务
+   ```
+
+2. **等待用户反馈**：
+   - "理解正确" → 继续阶段2
+   - "理解有偏差" → 修正理解，重新记录
+   - "补充需求" → 更新CLAUDE-temp.md
+
+### 阶段2：任务规划（根据复杂度差异化）
+
+**简单任务处理**：
+- **判断标准**：
+  - 修改不超过2个函数
+  - 不需要新建文件
+  - 逻辑改动在50行以内
+- **严格要求**：绝对不允许拆分子任务
+- **直接输出**：一个完整的执行计划
+
+**复杂任务处理**：
+- **判断标准**：
+  - 修改3个以上函数
+  - 需要新建模块或文件
+  - 涉及多个功能模块交互
+- **拆分原则**：
+  - 必须拆分为3-5个子任务（不能少于3个，不能多于5个）
+  - 每个子任务可独立验证
+  - 子任务之间有清晰的依赖关系
+- **拆分示例**：
+  ```
+  子任务1：创建重试机制基础设施
+  子任务2：集成重试机制到爬虫
+  子任务3：添加重试相关配置
+  子任务4：更新错误处理逻辑
+  子任务5：添加重试日志记录
+  ```
+
+### 阶段3：计划确认与正式化（用户确认后执行）
+
+**创建CLAUDE-plan.md，严格按照以下格式**：
+
+#### 简单任务格式：
+```markdown
+## 任务：[具体任务名称]
+创建时间：2025-08-22 10:30
+
+### 目标
+[30-50字描述要实现的功能，必须具体且可验证]
+
+### 所需上下文
+- `papers_crawler.py::45-67行::fetch_papers()` - 需要添加异常处理
+- `papers_crawler.py::120-135行::parse_response()` - 需要理解返回格式
+- `config.py::全文` - 了解现有配置结构
+
+### 拟修改内容
+1. 修改 `papers_crawler.py::fetch_papers()` 第50-55行 - 添加try-except块
+2. 修改 `papers_crawler.py::fetch_papers()` 第65行 - 添加重试逻辑
+3. 修改 `config.py` 末尾 - 添加RETRY_TIMES常量
+
+### 测试指令
+```bash
+# 主功能测试
+uv run papers_crawler.py --keyword "machine learning" --limit 5
+
+# 异常情况测试（模拟网络错误）
+uv run papers_crawler.py --test-mode --simulate-error
+```
+
+### 验收标准
+- [ ] 正常爬取功能不受影响
+- [ ] 网络异常时能正确重试
+- [ ] 日志正确记录重试次数
+```
+
+#### 复杂任务格式：
+```markdown
+## 任务：[具体任务名称]
+创建时间：2025-08-22 10:30
+
+### 总体目标
+[50-100字描述整体要实现的功能]
+
+### 子任务分解
+
+#### 子任务1：[名称]
+**目标**：[20-30字描述]
+
+**所需上下文**：
+- `papers_crawler.py::45-67行::fetch_papers()` - 理解当前实现
+- `utils/__init__.py::全文` - 确认工具模块结构
+
+**拟修改内容**：
+- 新建 `utils/retry.py` - 创建RetryDecorator类
+- 修改 `utils/__init__.py` - 导出retry装饰器
+
+**测试指令**：
+```bash
+# 单元测试
+python -c "from utils.retry import retry; print('导入成功')"
+```
+
+#### 子任务2：[名称]
+[格式同上]
+
+### 整体验收标准
+- [ ] 所有子任务独立测试通过
+- [ ] 集成测试：完整流程测试通过
+- [ ] 性能测试：重试不影响正常爬取速度
+```
+
+### 阶段4：实施与验证（严格按计划执行）
+
+**执行要求**：
+1. **开始前确认**：
+   - 再次阅读CLAUDE-plan.md
+   - 确认所有依赖文件存在
+   - 确认测试环境就绪
+
+2. **执行中记录**：
+   - 在CLAUDE-activeContext.md实时更新进度
+   - 遇到计划外情况立即停止并讨论
+
+3. **完成后验证**：
+   - 运行所有测试指令
+   - 检查验收标准
+   - 记录任何偏差或问题
+
+## Memory Bank系统设计
+
+### 文件结构
+```
+/docs/
+├── CLAUDE-temp.md          # 临时讨论和分析
+├── CLAUDE-plan.md          # 当前任务的正式计划
+├── CLAUDE-activeContext.md # 会话状态和进度跟踪
+├── CLAUDE-patterns.md      # 项目代码模式记录
+├── CLAUDE-decisions.md     # 重要决策和理由记录
+├── CLAUDE-troubleshooting.md # 问题和解决方案库
+└── CLAUDE-config-variables.md # 配置变量参考
+```
+
+### 使用原则
+1. **docs/CLAUDE-temp.md**：
+   - 每次新任务开始时清空或归档
+   - 用于快速记录和思考
+   - 不需要结构化
+
+2. **docs/CLAUDE-plan.md**：
+   - 结构化的任务计划
+   - 用户确认后才写入
+   - 作为实施的指导文档
+
+3. **docs/CLAUDE-activeContext.md**：
+   - 记录当前进度
+   - 标记已完成/进行中/待完成
+   - 会话恢复时的参考
+
+### Memory Bank更新机制
+
+**使用专门的SubAgent管理**：
+```
+Task: memory-bank-updater
+Description: "更新Memory Bank文件"
+Prompt: "任务已完成，请更新以下Memory Bank文件：
+1. CLAUDE-activeContext.md - 标记任务完成，记录最终状态
+2. CLAUDE-patterns.md - 如有新的代码模式，记录下来
+3. CLAUDE-decisions.md - 记录本次任务的关键决策
+4. CLAUDE-troubleshooting.md - 如遇到问题，记录解决方案
+5. CLAUDE-config-variables.md - 如有新配置，更新文档
+
+具体完成内容：[任务摘要]
+遇到的问题：[如有]
+采用的解决方案：[如有]"
+```
+
+**调用时机**：
+- 每个任务完成后必须调用
+- 遇到重要决策时调用
+- 发现新的最佳实践时调用
+
+## 工具使用优化原则
+
+### 1. 批量操作原则
+**场景**：需要读取多个文件或执行多个独立搜索时
+**做法**：
+```python
+# 同时执行多个工具调用
+parallel_calls = [
+    Read("papers_crawler.py"),
+    Read("pdf_parser.py"),
+    Grep("retry", "*.py"),
+    LS("./utils/")
+]
+```
+**禁止**：顺序执行可并行的操作
+
+### 2. 上下文管理策略
+**主上下文保留**：
+- 用户对话
+- 关键决策点
+- 当前任务计划
+
+**委托给subagent**：
+- 大规模代码搜索："搜索所有使用requests库的地方"
+- 代码模式分析："分析项目中的错误处理模式"
+- 依赖关系梳理："找出papers_crawler.py的所有依赖"
+
+**subagent使用示例**：
+```
+Task: code-searcher
+Prompt: "在整个项目中搜索所有异常处理相关的代码，
+        重点关注papers_crawler.py和pdf_parser.py，
+        总结当前的错误处理模式和改进建议"
+```
+
+### 3. 文件操作最佳实践
+**读取顺序**：
+1. 先读CLAUDE-activeContext.md（如果存在）了解当前状态
+2. 读取主文件了解整体结构
+3. 读取相关依赖文件
+
+**修改原则**：
+- 优先使用Edit而非Write
+- 使用MultiEdit处理同文件多处修改
+- 新文件创建需明确理由
+
+## 与现有编程规范的协同
+
+### 层次关系
+1. **编程规范**（已在CLAUDE.md中定义）：
+   - 定义"怎么写代码"
+   - 包括：命名、注释、代码风格等
+
+2. **AI指导规范**（本规范）：
+   - 定义"怎么理解和修改代码"
+   - 包括：工作流程、沟通方式、工具使用等
+
+### 执行优先级
+1. 遵守编程规范的硬性要求（如单次修改限制）
+2. 按AI指导流程进行任务
+3. 发生冲突时，编程规范优先
+
+## 规范更新机制
+- 每次遇到新的最佳实践，记录到CLAUDE-patterns.md
+- 定期回顾CLAUDE-troubleshooting.md，提炼通用规则
+- 用户可随时提出规范优化建议
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,212 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。
+
+## 技术栈
+1. 后端编程语言：Python
+2. python管理器：uv
+3. 爬虫工具：Crawl4AI
+
+## 各个模块的主文件
+1. 论文爬取主文件: papers_crawler.py
+2. pdf解析主文件: pdf_parser.py
+3. 实验运行主文件: experiment_runner.py
+
+## 开发注意事项
+
+### 必须遵循的编程规范
+
+1. **注释和文档规范**
+   - 所有注释使用中文
+   - 关键代码逻辑必须添加行内注释
+   - 所有函数和类必须添加docstring，说明功能、参数和返回值
+   - 复杂算法需要详细说明思路
+
+2. **命名规范**
+   - 变量名、函数名：使用 snake_case
+   - 类名：使用 PascalCase
+   - 常量：使用 UPPER_SNAKE_CASE
+   - 禁止使用中文变量名
+
+3. **代码修改限制**
+   - 单次修改不超过200行代码
+   - 单次修改不超过3个文件
+   - 严格遵循最小修改原则
+   - 绝对不允许修改与指定任务无关的代码
+   - 每次修改只针对当前任务的必要部分
+   - 优先修改而非新建：能通过修改解决的问题不新建文件
+
+4. **代码风格规范**
+   - 单行代码长度限制：120字符
+   - 使用类型提示（type hints）提高代码可读性
+   - 导入语句按照：标准库 → 第三方库 → 本地模块 的顺序排列
+
+5. **错误处理和日志**
+   - 必须使用 try-except 进行全面的错误捕获
+   - 使用 logging 模块替代 print 进行日志输出
+   - 日志级别：开发时使用DEBUG，生产环境使用INFO
+   - 绝对不允许填写任何默认值或假设值
+   - 出现错误时应抛出明确的异常信息，便于问题排查
+   - 宁可程序报错，也不要用默认值掩盖潜在问题
+
+6. **依赖管理**
+   - 优先使用标准库
+   - 新增第三方依赖时需在注释中说明用途
+   - 使用 uv 管理所有依赖
+
+7. **资源管理**
+   - 文件操作必须使用 with 语句
+   - 网络请求设置合理超时（建议30秒）
+   - 大文件使用流式处理避免内存溢出
+
+8. **Git提交规范**
+   - commit message 格式：`<类型>: <描述>`
+   - 类型包括：feat(新功能)、fix(修复)、refactor(重构)、docs(文档)、test(测试)
+
+9. **测试规范**
+   - 不允许撰写独立的测试用例文件或测试代码
+   - 通过直接运行对应的主文件（papers_crawler.py、pdf_parser.py 或 experiment_runner.py）进行功能测试
+   - 主文件的 `if __name__ == "__main__":` 块中应包含基本的功能调用示例
+   - 函数可以被其他模块调用，不一定要在主文件中直接调用
+   - 作为MVP项目，重点关注理想情况下的功能实现，而非鲁棒性
+   
+   **修改前验证**：
+   ```bash
+   # 确保现有功能正常
+   uv run <主文件>.py --test-mode
+   ```
+   
+   **修改后验证**：
+   ```bash
+   # 功能测试
+   uv run <主文件>.py --test-mode
+   # 语法检查
+   python -m py_compile <修改的文件>.py
+   # 如有类型提示，运行类型检查
+   mypy <修改的文件>.py --ignore-missing-imports
+   ```
+
+### 代码组织原则
+- 新功能优先集成到现有主文件中
+- 只有在功能独立且复杂时才创建新的模块文件
+- 保持代码结构简洁，避免过度模块化
+
+## uv常用指令
+1. 初始化项目
+   ```
+   uv init
+   ```
+2. 安装依赖
+   ```
+   uv add <package-name>
+   ```
+3. 运行项目
+   ```
+   uv run <script-name>
+   ```
+4. 打包项目
+   ```
+   uv build
+   ```
+
+## AI协作指导规范
+
+### 核心理念
+- **讨论优先**：任何修改前必须充分讨论，达成共识
+- **上下文明确**：具体到文件、行号和函数名
+- **渐进式实施**：通过子任务分解，逐步完成复杂需求
+- **可追溯性**：所有决策和修改都有明确记录
+
+### 工作流程
+
+#### 阶段1：需求理解与记录（必须执行）
+用户提出需求后，立即在`docs/CLAUDE-temp.md`中记录：
+- 原始需求和我的理解
+- 相关文件和函数（具体到行号）
+- 现有代码分析
+- 潜在影响评估
+- 任务复杂度判断（简单/复杂）
+
+#### 阶段2：任务规划
+**简单任务**（修改≤2个函数，≤50行）：
+- 严禁拆分子任务
+- 直接形成单一执行计划
+
+**复杂任务**（修改≥3个函数或需新建文件）：
+- 必须拆分为3-5个子任务
+- 每个子任务可独立验证
+- 按依赖关系排序
+
+#### 阶段3：计划正式化
+用户确认后，在`docs/CLAUDE-plan.md`中记录详细计划：
+- 任务目标（30-50字）
+- 所需上下文（文件::行号::函数名）
+- 拟修改内容（具体到行）
+- 测试指令
+- 验收标准
+
+#### 阶段4：实施与验证
+- 严格按计划执行
+- 在`docs/CLAUDE-activeContext.md`实时更新进度
+- 遇到计划外情况立即停止并讨论
+- 完成后运行所有测试指令
+
+### Memory Bank系统
+
+#### 文件结构
+```
+/docs/
+├── CLAUDE-temp.md          # 临时讨论和分析
+├── CLAUDE-plan.md          # 当前任务计划
+├── CLAUDE-activeContext.md # 会话状态跟踪
+├── CLAUDE-patterns.md      # 代码模式记录
+├── CLAUDE-decisions.md     # 决策记录
+├── CLAUDE-troubleshooting.md # 问题解决方案
+└── CLAUDE-config-variables.md # 配置变量参考
+```
+
+#### 更新机制
+每个任务完成后，使用专门的SubAgent更新Memory Bank， SubAgent为memory-bank-synchronizer：
+```
+Task: memory-bank-synchronizer
+功能: 更新所有Memory Bank文件，记录任务成果、决策和经验
+```
+
+### 工具使用原则
+
+1. **批量操作**：多个独立操作必须同时执行
+2. **上下文管理**：
+   - 主上下文：用户对话、决策、当前计划
+   - SubAgent：大规模搜索、模式分析、依赖梳理
+3. **文件操作**：
+   - 优先Edit而非Write
+   - 同文件多处修改用MultiEdit
+   - 新文件需明确理由
+
+### TodoWrite工具使用
+**强制使用场景**：
+- 任务包含3个以上步骤
+- 复杂任务的子任务追踪
+- 用户明确要求
+
+**状态管理**：
+- 同时只能有1个in_progress
+- 完成立即标记completed
+- 遇阻标记pending并说明
+
+### 与编程规范的关系
+- 编程规范定义"怎么写代码"
+- AI指导规范定义"怎么理解和修改代码"
+- 发生冲突时，编程规范优先
+
+
+
+
+
+
+
+
--- a/README.md
+++ b/README.md
--- a/pyproject.toml
+++ b/pyproject.toml
@ -0,0 +1,7 @@
+[project]
+name = "medresearcher"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []