feat: 初始化MedResearcher项目

- 添加项目配置文件(pyproject.toml)
- 添加Python版本配置(.python-version)
- 添加项目文档(README.md, CLAUDE.md)
- 添加Git配置(.gitignore)
This commit is contained in:
iomgaa 2025-08-23 00:20:41 +08:00
commit 8213ae9a55
6 changed files with 514 additions and 0 deletions

11
.gitignore vendored Normal file
View File

@ -0,0 +1,11 @@
# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info
# Virtual environments
.venv
.claude

1
.python-version Normal file
View File

@ -0,0 +1 @@
3.13

283
CLAUDE-temp.md Normal file
View File

@ -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提炼通用规则
- 用户可随时提出规范优化建议

212
CLAUDE.md Normal file
View File

@ -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指导规范定义"怎么理解和修改代码"
- 发生冲突时,编程规范优先

0
README.md Normal file
View File

7
pyproject.toml Normal file
View File

@ -0,0 +1,7 @@
[project]
name = "medresearcher"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []