From 8213ae9a5590775b0544a0f5689a0f212a7333bd Mon Sep 17 00:00:00 2001 From: iomgaa Date: Sat, 23 Aug 2025 00:20:41 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=88=9D=E5=A7=8B=E5=8C=96MedResearche?= =?UTF-8?q?r=E9=A1=B9=E7=9B=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加项目配置文件（pyproject.toml） - 添加Python版本配置（.python-version） - 添加项目文档（README.md, CLAUDE.md） - 添加Git配置（.gitignore） --- .gitignore | 11 ++ .python-version | 1 + CLAUDE-temp.md | 283 ++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 212 ++++++++++++++++++++++++++++++++++++ README.md | 0 pyproject.toml | 7 ++ 6 files changed, 514 insertions(+) create mode 100644 .gitignore create mode 100644 .python-version create mode 100644 CLAUDE-temp.md create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 pyproject.toml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..578f33c --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +# Python-generated files +__pycache__/ +*.py[oc] +build/ +dist/ +wheels/ +*.egg-info + +# Virtual environments +.venv +.claude diff --git a/.python-version b/.python-version new file mode 100644 index 0000000..24ee5b1 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/CLAUDE-temp.md b/CLAUDE-temp.md new file mode 100644 index 0000000..36cc442 --- /dev/null +++ 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，提炼通用规则 +- 用户可随时提出规范优化建议 \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ff5b8e8 --- /dev/null +++ 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 + ``` +3. 运行项目 + ``` + uv run + ``` +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指导规范定义"怎么理解和修改代码" +- 发生冲突时，编程规范优先 + + + + + + + + diff --git a/README.md b/README.md new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..fe2ef94 --- /dev/null +++ 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 = []