swai 0.1.1
thuway ai tools
License: Apache License 2.0
Requires Python: >=3.8

# SWAI — Thuway AI 命令行工具

## 1. 介绍
SWAI 提供一套简洁的命令行工具，用于与 Thuway AI 平台进行交互。你可以使用它完成用户登录、任务提交、任务列表查询、取消任务与下载结果等常见操作。

当前命令行支持的任务类型包含 `swbind` 与 `swdocking`。就代码实现而言，提交流程已打通；默认参数解析仍处于演示状态（Demo），后续可按需扩展真实业务参数。

## 2. 功能特性
- **登录鉴权**: API Key 登录，一次登录长久使用。
- **任务提交**: 一条命令提交任务到平台，支持选择任务类型与订阅完成邮件。
- **任务查询**: 按状态、类型、数量上限或任务 ID 查看任务列表。
- **取消任务**: 通过任务 ID 取消正在排队或运行的任务。
- **结果下载**: 通过任务 ID 下载任务结果到本地文件。

## 3. 安装

### 3.1 安装anaconda

- linux系统

```bash
# 下载anaconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 安装anaconda
bash Miniconda3-latest-Linux-x86_64.sh -b -f -c
source ~/.bashrc
```

- windows

点击下载并安装 `https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe`

### 3.2 验证安装是否正确

在windows cmd或命令行中执行

```bash
python
```

如果出现类似下列信息，说明安装成功
```bash
Python 3.13.5 | packaged by Anaconda, Inc. | (main, Jun 12 2025, 16:09:02) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
```

### 3.3 配置国内镜像源

官方python镜像源由于网络原因，下载第三方包速度慢，因此需配置国内镜像源，在windows cmd或命令行中执行

```bash
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/pro
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
```

### 3.4 创建swai_env虚拟环境

在windows cmd或命令行中执行

```bash
conda create -n swai_env python=3.10
conda activate swai_env
pip install git+https://gitee.com/cool_c0de/AutoDockTools_py3.git
pip install swai
conda install openbabel 
```

`swai_env` 是创建的虚拟环境名称，虚拟环境使用python3.10版本，支持最低版本为3.8

### 3.5 验证安装是否成功

在windows cmd或命令行中执行

```bash
conda activate swai_env
swai deps
```

如果显示 `All dependence found` 说明安装成功，否则请按照提示完成修复

## 4. 快速开始

4.1 查看帮助
```bash
swai help
# 或
swai -h
```

4.2 登录（首次使用必须先登录）
```bash
swai login <YOUR_API_KEY>
```

`<YOUR_API_KEY>` 是用户使用系统的密钥，在[ThuwayAI平台](http://116.62.154.188:8081/) 注册账号后，可在`个人主页`获取`访问令牌`

4.3 提交任务

提交任务，需要针对不同任务类型指定的数据格式，具体处理方式 见  [数据处理](./dataprocess.md) 页面

```bash
swai submit -t {swbind|swdocking} -i <task_input_file.zip> -d "task description"
```

说明：

| 参数 | 说明 | 是否必需 | 示例 |
|------|------|----------|------|
| `-t`, `--task_type` | 任务类型，支持 swbind、swdocking | 是 | -t swbind |
| `-i`, `--task_input` | 任务输入文件路径 | 是 | -i input.zip |
| `-d`, `--description` | 任务提交记录 | 是 | -d "demo" |
<!-- | `--subscribe_email` | 开启该参数，任务完成后邮件通知 | 否 | `--subscribe_email` | -->

示例
```bash
# 提交swbind任务
swai submit -t swbind -i D:/workspace/swbind-input.zip -d "swbind demo"
```

4.4 查询任务

```bash
# 按条件筛选
swai list [-s {queued,running,done,failed,cancelled,all}] [-t {swbind,swdocking,all}] [-l <limit>]

## 示例
swai list -s done -t swdocking -l 1

# 按任务 ID 精确查询
swai list -i <task_id>

## 示例
swai list -i swdocking123456
```

说明：

| 参数 | 说明 | 是否必需 | 默认值 | 示例 |
|------|------|----------|--------|------|
| `-s`, `--status` | 任务状态过滤，可选：queued、running、done、failed、cancelled、all | 否 | all | -s running |
| `-t`, `--task_type` | 任务类型过滤，可选：swbind、swdocking、all | 否 | all | -t swbind |
| `-l`, `--limit` | 返回任务数量上限 | 否 | 50 | -l 10 |
| `-i`, `--task_id` | 指定任务 ID 精确查询 | 否 | 无 | -i swdocking123456 |


4.5 取消任务

```bash
# 取消id为<task_id>的任务
swai cancel <task_id>

## 示例
swai cancel swdocking123456
```



4.6 下载结果
```bash
# 下载id为<task_id>的结果，可通过`-o`参数指定下载路径
swai download <task_id> [-o <output_file>]

## 示例
swai download swdocking123456 -o result.zip
```

不指定 `-o/--output` 时，默认保存为 `<task_id>.zip`。




## 5. 常见问题
- 网络错误：若提示连接失败，请检查网络或服务端地址是否可达。
- 登录失败：若提示 API Key 错误，请确认密钥是否正确且已在平台开通权限。
- 无法下载：确保任务状态为 `done`，且已成功登录（本地存在缓存的 API Key）。


## 6. 许可证
本项目采用 Apache License 2.0 许可。