celltypeAgent 1.0.1

统一的细胞类型分析工具包，集成四个专业Agent提供完整的细胞类型注释流程

CellType MCP Server - 统一配置版本

这是一个重新整理和统一管理的 CellType MCP Server 项目，集成了四个专业的细胞类型分析 Agent，采用统一的配置管理和输出目录结构。

🏗️ 项目架构

celltype-mcp-server/
├── config/                     # 统一配置系统
│   ├── __init__.py
│   ├── global_config.py        # 全局配置管理器
│   ├── paths_config.py         # 路径配置
│   ├── unified_logger.py       # 统一日志管理
│   └── celltypeAgent_config.json   # 项目设置文件
├── outputs/                    # 统一输出目录
│   ├── cache/                  # 缓存文件
│   │   ├── celltypeMainagent/
│   │   ├── celltypeSubagent/
│   │   ├── celltypeDataAgent/
│   │   └── celltypeAppAgent/
│   ├── logs/                   # 日志文件
│   ├── results/                # 分析结果
│   └── downloads/              # 下载的数据库文件
├── examples/                   # 统一示例目录
│   ├── main_example.py         # MainAgent 示例
│   ├── subagent_example.py     # SubAgent 示例
│   ├── data_example.py         # DataAgent 示例
│   ├── app_example.py          # AppAgent 示例
│   ├── run_all_examples.py     # 交互式示例运行器
│   └── README.md               # 示例文档
├── celltypeMainagent/          # 主调度 Agent
├── celltypeSubagent/           # 基础数据服务 Agent
├── celltypeDataAgent/          # 数据处理 Agent
├── celltypeAppAgent/           # 应用级注释 Agent
└── manage.py                   # 项目管理工具

🚀 快速开始

1. 环境设置

# 设置 API 密钥
export OPENAI_API_KEY="your-api-key-here"
export OPENAI_API_BASE="https://api.openai.com/v1"  # 可选
export OPENAI_MODEL="gpt-4"                         # 可选

# 安装依赖
pip install colorama  # 用于彩色输出

2. 项目管理

# 检查项目状态
python manage.py status

# 检查依赖环境
python manage.py deps

# 查看当前配置
python manage.py config

# 运行示例
python manage.py examples

# 清理输出目录
python manage.py clean

# 查看磁盘使用
python manage.py disk

# 备份配置
python manage.py backup

# 查看帮助
python manage.py help

3. 运行示例

有两种方式运行示例：

方式一：使用项目管理工具

python manage.py examples

方式二：直接运行统一示例器

python examples/run_all_examples.py

方式三：运行单个示例

python examples/main_example.py      # MainAgent 示例
python examples/subagent_example.py  # SubAgent 示例
python examples/data_example.py      # DataAgent 示例
python examples/app_example.py       # AppAgent 示例

🧬 Agent 功能

celltypeMainagent

• 作用: 主调度器，统一工作流编排
• 功能: 协调其他 Agent，管理复杂分析流程
• 输出: 整合的分析结果和报告

celltypeSubagent

• 作用: 基础数据服务，提供基因信息查询和富集分析
• 功能: NCBI 基因查询、CellMarker/PanglaoDB 数据库查询、基因富集分析
• 输出: 基因信息、细胞类型标记、富集结果

celltypeDataAgent

• 作用: 数据处理专家，支持多种数据格式转换和预处理
• 功能: RDS/H5AD/H5/CSV/JSON 格式支持、数据质量控制、格式转换
• 输出: 标准化的数据文件

celltypeAppAgent

• 作用: 应用级注释，集成多种细胞类型注释算法
• 功能: SingleR、scType、CellTypist 注释，智能算法选择
• 输出: 细胞类型注释结果

⚙️ 配置管理

统一配置文件

项目使用 config/celltypeAgent_config.json 作为统一配置文件：

{
  "llm": {
    "model": "gpt-4",
    "api_base": null,
    "api_key": null,
    "max_tokens": 4000,
    "temperature": 0.3
  },
  "project": {
    "language": "zh",
    "enable_streaming": true,
    "enable_logging": true,
    "cache_expiry_days": 30
  },
  "agents": {
    "celltypeMainagent": {"enabled": true, "timeout": 30},
    "celltypeSubagent": {"enabled": true, "timeout": 30},
    "celltypeDataAgent": {"enabled": true, "timeout": 30},
    "celltypeAppAgent": {"enabled": true, "timeout": 30}
  }
}

环境变量优先级

环境变量会覆盖配置文件设置：

• OPENAI_API_KEY → llm.api_key
• OPENAI_API_BASE → llm.api_base
• OPENAI_MODEL → llm.model
• CELLTYPE_LANGUAGE → project.language

📁 输出管理

目录结构

所有输出都统一保存在 outputs/ 目录下：

• cache/: 各 Agent 的缓存文件，按 Agent 名称分类
• logs/: 日志文件，自动生成带时间戳的文件名
• results/: 分析结果，支持多种格式
• downloads/: 下载的数据库和参考文件

文件命名规范

• 日志文件: {agent_name}_{timestamp}.log
• 结果文件: {agent_name}_{session_id}_{type}.{ext}
• 缓存文件: 按数据库和功能分类存储

🔧 依赖要求

Python 依赖

pip install colorama pathlib dataclasses typing

R 环境 (AppAgent 需要)

install.packages(c("SingleR", "scType", "celldx"))

CellTypist (AppAgent 需要)

pip install scanpy celltypist

🚨 注意事项

1. API 密钥安全: 不要在代码中硬编码 API 密钥，使用环境变量
2. 文件权限: 确保 outputs/ 目录有写权限
3. 磁盘空间: 数据库缓存可能占用较大空间，注意磁盘容量
4. 网络连接: 首次运行需要下载数据库文件
5. R 环境: AppAgent 的某些功能需要 R 环境支持

📞 故障排除

常见问题

1. 配置加载失败

   python manage.py status  # 检查项目状态
   python manage.py config  # 查看配置详情
   

2. Agent 初始化失败

   python manage.py deps    # 检查依赖
   

3. 输出目录问题

   python manage.py clean   # 清理输出目录
   python manage.py disk    # 查看磁盘使用
   

4. 示例运行失败

   • 检查 API 密钥设置
   • 确认所有依赖已安装
   • 查看 outputs/logs/ 目录下的详细日志

支持

如果遇到问题，请检查：

1. outputs/logs/ 目录下的详细日志
2. config/celltypeAgent_config.json 配置是否正确
3. 环境变量是否已正确设置
4. 必要的依赖是否已安装

🔄 版本信息

• 版本: 1.0.0 (统一配置版本)
• 更新日期: 2025-09-17
• 主要改进:
  • 统一配置管理系统
  • 集中式输出目录
  • 标准化的示例和文档
  • 项目管理工具
  • 向后兼容的 Agent 接口