feat: add example scripts and update documentation for CLI usage; introduce example1_cli.py and example_server.py, along with example.sh for environment setup and command execution

Author: Dramwig

docs/readme_en.md

@@ -1,3 +1,5 @@
+<!-- v0.1.2 -->
+
 <div align="center">
   <img src="./fig/logo.png" width="50%" alt="FlowLine" />
 
@@ -51,7 +53,7 @@ The system uses a list file (`.xlsx`、 `.csv` or `.json` format) to define task
 <details>
 <summary>Example and Explanation</summary>
 
-Example files: [`test/todo.xlsx`](./test/todo.xlsx), [`test/todo.csv`](./test/todo.csv),[`test/todo.json`](./test/todo.json), which can be constructed using the example program [`test/task_builder.py`](./test/task_builder.py).
+Example files: [`test/example1_todo.xlsx`](./test/example1_todo.xlsx), [`test/example1_todo.csv`](./test/example1_todo.csv),[`test/example1_todo.json`](./test/example1_todo.json), which can be constructed using the example program [`test/task_builder.py`](./test/task_builder.py).
 
 | *name*    | lr    | batch_size | *run_num* | *need_run_num* | *cmd*       |
 | --------- | ----- | ---------- | --------- | -------------- | ----------- |
@@ -88,7 +90,7 @@ if __name__ == "__main__":
         args = " ".join([f"--{k} {v}" for k, v in param_dict.items()])
         return cmd + args
 
-    run_cli(func, "test/todo.xlsx")
+    run_cli(func, "test/example1_todo.xlsx")
 ```
 
 * `param_dict`: Dictionary built from current Excel row (keys=column names, values=cell content)
@@ -182,7 +184,7 @@ Besides CLI, you can use the Web GUI for **real-time monitoring and dynamic inte
 #### 1. Start Backend API Service
 Run the Flask backend:
 ```bash
-python main_server.py
+python test/example_server.py
 ```
 
 #### 2. Start Frontend Service

example.sh

@@ -0,0 +1,14 @@
+# 先进入虚拟环境
+conda activate <你的虚拟环境名称>
+export PYTHONPATH=/home/me/project/flowline/ # 【可能需要修改】
+      # 因为example放在了test目录下，所以需要设置PYTHONPATH
+      # 正常情况下，cli/server在项目根目录下，所以不需要设置PYTHONPATH
+
+# 命令行调用示例
+
+python test/example1_cli.py
+python test/example2_cli.py
+
+# 集成式服务器
+python test/example_server.py # 启动服务器
+cd web && python -m http.server 8000 # 在【新的终端】，启动前端静态文件服务器

readme.md

@@ -1,4 +1,4 @@
-<!-- # FlowLine -->
+<!-- v0.1.3 -->
 
 <div align="center">
   <img src="./docs/fig/logo.png" width="50%" alt="FlowLine" />
@@ -29,10 +29,12 @@ FlowLine 是一个用于 **GPU资源管理** 和 **并发指令流调度** 的
 
 ## Updates
 
-* 2025.09.09: 新增用户自定义 GPU 优先级排序功能，通过 `user_cmp` 参数传入自定义排序函数，详见 [main_cli.py](./main_cli.py) 示例。
+* 2025.09.09: 新增用户自定义 GPU 优先级排序功能，通过 `user_cmp` 参数传入自定义排序函数，详见 [example1_cli.py](./test/example1_cli.py) 示例。
 
 ## 🚀 快速使用指南
 
+> 更精炼的， [example.sh](./example.sh) 给出了所有示例。
+
 ### 🖥️ 使用命令行接口（CLI 模式）
 
 #### 1. 安装方式
@@ -51,7 +53,7 @@ pip install fline
 pip install -e <flowline库路径>
 ```
 
-> 注：请确保你已安装 `pandas`、`psutil`、`openpyxl` 等`requirements.txt`内的基本依赖。
+> 注：请确保你已安装 `pandas`、`psutil`、`openpyxl` 等`requirements.txt`内的基本依赖。如果只用 CLI 方式可以不用安装 flash 相关包。
 
 #### 2. 编写任务控制表
 
@@ -60,7 +62,7 @@ pip install -e <flowline库路径>
 <details>
 <summary>示例和说明</summary>
 
-示例文件：[`test/todo.xlsx`](./test/todo.xlsx)、[`test/todo.csv`](./test/todo.csv)、[`test/todo.json`](./test/todo.json)， 可以通过运行[`test/task_builder.py`](./test/task_builder.py)示例构造程序构造。
+示例文件：[`test/example1_todo.xlsx`](./test/example1_todo.xlsx)、[`test/example1_todo.csv`](./test/example1_todo.csv)、[`test/example1_todo.json`](./test/example1_todo.json)， 可以通过运行[`test/task_builder.py`](./test/task_builder.py)示例构造程序构造。
 
 | *name*    | lr    | batch\_size |*run\_num*|*need\_run\_num*| *cmd*       |
 | --------- | ----- | ----------- | -------- | -------------- | ----------- |
@@ -88,26 +90,18 @@ pip install -e <flowline库路径>
 <details>
 <summary>示例和说明</summary>
 
-详见 [main_cli.py](./main_cli.py) 示例。主要部分如下：
+详见 [example1_cli.py](./test/example1_cli.py) 示例。主要部分如下：
 
 ```python
 def func(dict, gpu_id, sorted_gpu_ids):
-    print(sorted_gpu_ids)
     return "CUDA_VISIBLE_DEVICES="+str(gpu_id)+" python -u test/test.py "+ " ".join([f"--{k} {v}" for k, v in dict.items()])
 
-def cmp(info1, info2):
-    if info1.free_memory > info2.free_memory:
-        return -1
-    elif info1.free_memory < info2.free_memory:
-        return 1
-    else:
-        return 0
-
 if __name__ == "__main__":
-    # run_cli(func, "test/todo.csv") 
-    run_cli(func, "test/todo.csv", user_cmp=cmp) # user_cmp可选
+    run_cli(func, "test/example1_todo.xlsx") 
 ```
 
+对于直接执行完整命令的需求，见 [example2_cli.py](./test/example2_cli.py)。
+
 * `dict` 是由 Excel 中当前任务行构造出的字典，键为列名，值为单元格内容；
 * `gpu_id` 是系统动态分配的 GPU 编号，保证任务不冲突，其此刻一定满足显存空间最小限制；
 * `sorted_gpu_ids`（可选）是经过优先级排序后的可用 GP U序列，为可能的多 GPU 任务适配；
@@ -161,10 +155,10 @@ log/
 
 #### 4. 运行程序后输入`run`开始运行任务流
 
-运行 `main_cli.py` 启动程序：
+运行 `example1_cli.py` 启动程序：
 
 ```bash
-python main_cli.py
+python test/example1_cli.py
 ```
 
 <details>
@@ -227,10 +221,10 @@ python main_cli.py
 
 ### 1. 启动后端 API 服务
 
-后端为 Flask 应用，运行 `main_server.py` 启动服务：
+后端为 Flask 应用，运行 `example_server.py` 启动服务：
 
 ```bash
-python main_server.py
+python test/example_server.py
 ```
 
 ### 2. 启动前端界面服务

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 import os
 
-base_version = "0.1.1"
+base_version = "0.1.2"
 build_timestamp = os.getenv('BUILD_TIMESTAMP', None)
 
 if build_timestamp:

main_cli.py test/example1_cli.pymain_cli.py renamed to test/example1_cli.py

@@ -1,8 +1,10 @@
 # 命令行调用示例
-
 from flowline import run_cli
 
 def func(dict, gpu_id, sorted_gpu_ids):
+    # ! 这里需要修改为你的命令
+    # 示例： 这里通过字典 dict 读出参数，所以需要使用 " ".join([f"--{k} {v}" for k, v in dict.items()]) 将参数拼接起来
+    # 对于直接执行完整命令的需求，见 example2_cli.py
     return "CUDA_VISIBLE_DEVICES="+str(gpu_id)+" python -u test/test.py "+ " ".join([f"--{k} {v}" for k, v in dict.items()])
 
 def cmp(info1, info2):
@@ -14,7 +16,8 @@ def cmp(info1, info2):
         return 0
 
 if __name__ == "__main__":
-    # run_cli(func, "test/todo.csv") 
-    run_cli(func, "test/todo.csv", user_cmp=cmp) # user_cmp可选
+    # ! 这里需要修改为你的任务配置文件路径
+    run_cli(func, "test/example1_todo.csv", user_cmp=cmp) 
+    # user_cmp 可选 e.g. run_cli(func, "test/example1_todo.xlsx") 
 
 # 如果出现异常进程，可以使用 pkill -9 python 杀死所有进程

test/todo.csv test/example1_todo.csvtest/todo.csv renamed to test/example1_todo.csv

@@ -0,0 +1,11 @@
+from flowline.api import run_cli
+
+def func(dict, gpu_id, sorted_gpu_ids):
+    # ! 这里需要修改为你的命令
+    # 示例： 这里是直接读出命令 mycmd 而不是使用参数，所以直接返回 dict["mycmd"]
+    return "CUDA_VISIBLE_DEVICES="+str(gpu_id)+" "+dict["mycmd"]+" --discribe "+'"'+dict["description"]+'"'
+
+if __name__ == "__main__":
+    run_cli(func, "trash/todo.csv") 
+    
+# 如果出现异常进程，可以使用 pkill -9 python 杀死所有进程

test/todo.json test/example1_todo.jsontest/todo.json renamed to test/example1_todo.json

@@ -0,0 +1,13 @@
+description,mycmd,run_num,need_run_num,name,cmd
+Resnet50+自蒸馏 weather训练,python train.py train multi_resnet50_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.02  --use-self False,0,1,Task:0,No command
+Resnet50+自蒸馏 weather训练,python train.py train multi_resnet50_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.02,0,1,Task:1,No command
+Resnet50+频域Attention weather训练,python train.py train Spec_Resnet50_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --use-self False  --lr 0.02,0,1,Task:2,No command
+Ours-small weather训练 （Resnet50+频域Attention+自蒸馏）,python train.py train Spec_Resnet50_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.001 --alpha 0.1  --temperature  1,0,1,Task:3,No command
+Resnet101+自蒸馏 weather训练,python train.py train multi_resnet101_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.02  --use-self False,0,1,Task:4,No command
+Resnet101+自蒸馏 weather训练,python train.py train multi_resnet101_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100  --lr 0.02,0,1,Task:5,No command
+Resnet101+频域Attention weather训练,python train.py train Spec_Resnet101_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --use-self False  --lr 0.001,0,1,Task:6,No command
+Ours-base weather训练,python train.py train Spec_Resnet101_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.005,0,1,Task:7,No command
+Resnet152+自蒸馏 weather训练,python train.py train multi_resnet152_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100  --lr 0.02  --use-self False,0,1,Task:8,No command
+Resnet152+自蒸馏 weather训练,python train.py train multi_resnet152_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100  --lr 0.02,0,1,Task:9,No command
+Resnet152+频域Attention weather训练,python train.py train Spec_Resnet152_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.001  --use-self False,0,1,Task:10,No command
+Ours-large weather训练,python train.py train Spec_Resnet152_kd --data-dir /home/me/datasets/weather --dataset weather --batch-size 4 --print-freq 100 --lr 0.001,0,1,Task:11,No command