# biobee-workflow

**Repository Path**: bee19940901/workflow

## Basic Information

- **Project Name**: biobee-workflow
- **Description**: BioBee生信云调度工具
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BioBee Workflow

生物信息学工作流管理 CLI 工具，用于管理和执行生物信息学分析流程。支持多环境配置、模块化工具集成、任务执行与状态跟踪。

## ✨ 功能特性

- 🎯 **多环境支持**：Local（本地开发）和 Dev（服务器环境）无缝切换，通过环境变量或标记文件配置
- 🛠️ **模块化设计**：支持添加各种生物信息学分析工具，易于扩展新模块
- 📝 **配置管理**：集中配置管理，避免硬编码，支持动态加载环境配置
- 🚀 **任务执行**：支持单命令执行和批量并行执行，自动生成 shell 脚本
- 📊 **状态跟踪**：通过 `.ok` 文件自动跟踪任务执行状态，支持跳过已成功任务
- 🔧 **灵活配置**：支持环境变量、配置文件、命令行参数多种配置方式
- 📈 **日志管理**：详细的日志记录和错误追踪，支持控制台彩色输出和文件日志
- ⚡ **高性能**：支持多进程并行执行，充分利用多核 CPU

## 🚀 快速开始

### 环境要求

- Python >= 3.10
- 依赖管理工具：pip 或 uv

### 安装

```bash
# 克隆项目
git clone https://gitee.com/bee19940901/biobee.git
cd biobee/workflow

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

# 安装项目（开发模式）
pip install -e .

# 或安装开发依赖（包含测试和代码检查工具）
pip install -e '.[dev-tools]'
```

### 验证安装

```bash
# 查看帮助
workflow --help

# 查看版本和当前环境
workflow --version

# 列出所有可用命令
workflow --list
```

## ⚙️ 配置

### 配置文件

项目支持两种配置方式：

1. **Python 配置文件**（当前使用）：直接修改 `src/workflow/config/local.py` 和 `src/workflow/config/dev.py` 中的路径变量
2. **TOML 配置文件**（规划中）：在 `pyproject.toml` 的 `[tool.workflow.env]` 部分配置（尚未实现）

### 环境切换

```bash
# 方式1：环境变量（临时切换）
WORKFLOW_ENV=dev workflow --version

# 方式2：标记文件（永久切换）
touch .workflow_dev  # 切换到 dev 环境
rm .workflow_dev    # 切换回 local 环境

# 方式3：命令行参数（部分命令支持）
workflow MedTool PanCancer run -e dev -c config.json
```

### Python 配置文件示例

**本地环境配置** (`src/workflow/config/local.py`)：

```python
from pathlib import Path

RSCRIPT = "/Users/bee/workspace/software/bin/micromamba run -n R Rscript "
PYTHON3 = "/Users/bee/workspace/data/biobee/venv/bin/python3"
ANALYSIS = Path("/Users/bee/workspace/repos/biobee/analysis")
```

**开发环境配置** (`src/workflow/config/dev.py`)：

```python
from pathlib import Path

RSCRIPT = "mamba run -n r-base Rscript"
PYTHON3 = "mamba run -n python-venv python3"
ANALYSIS = Path("/data/biobee/analysis")
```

### 分析配置示例

运行 PanCancer 分析需要一个 JSON 配置文件，示例 `config.json`：

```json
{
  "taskDir": "/path/to/task_directory",
  "outputDir": "/path/to/task_directory/output",
  "taskType": "PanCancer",
  "projectType": "MedTool"
}
```

## 📖 使用指南

### 基本命令

```bash
# 查看全局帮助
workflow --help

# 查看 MedTool 模块帮助
workflow MedTool --help

# 查看 PanCancer 子命令帮助
workflow MedTool PanCancer --help
```

### PanCancer 分析

```bash
# 运行 PanCancer 分析（使用本地环境）
workflow MedTool PanCancer run -e local -c config.json

# 运行 PanCancer 分析（使用开发环境）
workflow MedTool PanCancer run -e dev -c config.json
```

### 执行流程

1. 根据指定的环境加载配置（RSCRIPT、ANALYSIS 路径等）
2. 解析 JSON 配置文件，获取任务目录、输出目录等信息
3. 构建 R 脚本执行命令
4. 生成 shell 脚本并保存到 `log/run.sh`
5. 执行脚本，输出日志到 `log/run.log`
6. 任务成功后创建 `.ok` 标记文件
7. 压缩输出结果（生成 png.zip 和 result.zip）

### 任务状态管理

- 每次任务执行成功后会创建 `.ok` 标记文件
- 如果 `.ok` 文件已存在且 `skip` 参数为 True，则会跳过执行
- 可以通过删除 `.ok` 文件强制重新执行任务

## 🏗️ 项目结构

```
workflow/
├── pyproject.toml               # 项目配置和依赖
├── README.md                   # 中文文档
├── README.en.md               # 英文文档
├── .gitignore                 # Git 忽略规则
├── LICENSE                    # MIT 许可证
├── src/workflow/
│   ├── cli.py                # CLI 入口，Typer 应用
│   ├── __init__.py
│   ├── config/               # 配置模块
│   │   ├── __init__.py
│   │   ├── local.py          # 本地环境配置
│   │   └── dev.py           # 开发环境配置
│   ├── util/                 # 工具模块
│   │   ├── __init__.py
│   │   ├── runner.py        # Shell 命令执行器
│   │   ├── logger.py        # 日志管理器
│   │   └── checker.py       # 文件检查工具
│   └── MedTool/             # 医学工具模块
│       ├── __init__.py
│       └── PanCancer.py     # PanCancer 分析命令
└── tests/                    # 测试目录（待完善）
```

## 🔧 开发指南

### 开发环境设置

```bash
# 安装开发依赖
pip install -e '.[dev-tools]'

# 代码格式化和检查
ruff check --fix    # 自动修复可修复的问题
ruff format         # 格式化代码

# 运行测试
pytest
```

### 添加新模块

1. 在 `src/workflow/` 下创建新模块目录，如 `NewTool/`
2. 创建 `__init__.py` 和命令模块文件
3. 在模块的 `__init__.py` 中创建 Typer 应用并注册到主 CLI

示例：

```python
# src/workflow/NewTool/__init__.py
import typer

app = typer.Typer(name="NewTool", help="New tool description")

# 注册子命令
from .new_command import app as new_command_app
app.add_typer(new_command_app, name="command")

# src/workflow/cli.py 中添加
from workflow import NewTool
app.add_typer(NewTool.app, name="NewTool")
```

### 添加新命令

参考 `PanCancer.py` 的实现：

```python
import typer

app = typer.Typer(name="CommandName")

@app.command()
def run(
    param1: str = typer.Option(..., help="参数说明"),
    param2: int = typer.Option(1, help="可选参数")
):
    """命令描述"""
    # 命令逻辑
    pass
```

### 配置管理

- 本地环境配置：`src/workflow/config/local.py`
- 开发环境配置：`src/workflow/config/dev.py`
- 通过环境变量 `WORKFLOW_ENV` 切换配置

## 📝 日志说明

日志系统基于 Python logging 和 Rich 库，提供：

- 彩色控制台输出（支持 traceback 高亮）
- 文件日志（可选）
- 多级别日志：DEBUG、INFO、WARNING、ERROR
- 自动记录执行状态和错误信息

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进项目。

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 使用 Black 或 Ruff 格式化代码
- 遵循 PEP 8 规范
- 添加适当的类型注解
- 编写清晰的文档字符串

## 📄 许可证

本项目基于 MIT 许可证开源，详情请参阅 [LICENSE](LICENSE) 文件。

## 📞 联系方式

- 作者：Liang Bing
- 邮箱：believer19940901@gmail.com
- 项目仓库：https://gitee.com/bee19940901/biobee

## 🙏 致谢

感谢所有为本项目做出贡献的开发者和用户。