mtr-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{mtr_cli-0.2.0 → mtr_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtr-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: A CLI tool for seamless local development and remote execution on GPU servers.
 Project-URL: Homepage, https://github.com/lecoan/mtremote
 Project-URL: Repository, https://github.com/lecoan/mtremote
@@ -57,11 +57,21 @@ pip install mtr-cli
 
 MTRemote 需要以下系统命令：
 
-| 命令 | 用途 | 安装方式 |
-|------|------|----------|
-| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` |
-| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 |
-| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) |
+| 命令 | 用途 | 安装方式 | 版本要求 |
+|------|------|----------|----------|
+| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` | - |
+| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 | **≥ 3.1.0** (TTY 进度显示需要) |
+| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) | - |
+
+**注意**：macOS 自带的 rsync 版本较旧（2.6.9），不支持 TTY 模式下的进度显示。建议通过 Homebrew 安装新版：
+
+```bash
+# macOS 用户建议升级 rsync
+brew install rsync
+
+# 验证版本
+rsync --version  # 应显示 3.1.0 或更高版本
+```
 
 **注意**：交互式 Shell 功能（如 `mtr bash`, `mtr ipython`）**必须**安装 `ssh`。密码认证**必须**安装 `sshpass`。
 

{mtr_cli-0.2.0 → mtr_cli-0.3.0}/README.md

@@ -30,11 +30,21 @@ pip install mtr-cli
 
 MTRemote 需要以下系统命令：
 
-| 命令 | 用途 | 安装方式 |
-|------|------|----------|
-| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` |
-| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 |
-| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) |
+| 命令 | 用途 | 安装方式 | 版本要求 |
+|------|------|----------|----------|
+| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` | - |
+| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 | **≥ 3.1.0** (TTY 进度显示需要) |
+| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) | - |
+
+**注意**：macOS 自带的 rsync 版本较旧（2.6.9），不支持 TTY 模式下的进度显示。建议通过 Homebrew 安装新版：
+
+```bash
+# macOS 用户建议升级 rsync
+brew install rsync
+
+# 验证版本
+rsync --version  # 应显示 3.1.0 或更高版本
+```
 
 **注意**：交互式 Shell 功能（如 `mtr bash`, `mtr ipython`）**必须**安装 `ssh`。密码认证**必须**安装 `sshpass`。
 

mtr_cli-0.3.0/docs/intro-to-mtr.md

@@ -0,0 +1,180 @@
+# mtr-cli：远程训练框架开发的工作流优化
+
+## 背景与问题
+
+在训练框架开发过程中，我们面临一个结构性矛盾：代码开发在本地进行，但功能验证必须在远程 GPU/NPU 集群上完成。这种"本地-远程"的割裂带来了三个核心问题。
+
+### 网络与环境隔离
+
+训练集群通常部署在内网或隔离环境中，无法直接访问外部网络。这导致依赖安装困难，而训练框架的依赖链本身就很复杂（PyTorch、DeepSpeed、Megatron 等）。环境配置耗时较长，一旦集群环境需要重建，成本很高。
+
+### 多集群切换成本高
+
+框架开发需要在 GPU 集群和 NPU 集群之间频繁切换验证。每次切换涉及代码同步、路径检查、环境确认等重复性操作。虽然启动方式统一使用 torchrun，但不同集群的节点地址、Python 环境路径等配置存在差异，需要反复适配。
+
+### AI Agent 集成受限
+
+训练任务在远程集群执行时，代码报错和异常堆栈输出在远程终端。AI Agent 无法直接访问这些信息，开发者需要手动复制粘贴错误内容，打断开发流程。Agent 无法实时感知执行状态，失去了即时辅助调试的能力。
+
+## 解决方案：mtr-cli
+
+mtr-cli 采用"本地开发，远程执行"的架构，在保持本地开发体验的同时，实现与远程集群的无缝集成。
+
+### 核心功能
+
+**智能代码同步**
+
+支持 rsync（增量同步，速度快）和 SFTP（兼容性好）两种引擎。自动过滤 .git、__pycache__ 等无需同步的文件，避免大数据集误传。
+
+**多集群配置管理**
+
+通过配置文件集中管理多个训练集群：
+
+```yaml
+servers:
+  gpu-cluster:
+    host: "gpu-node-01"
+    user: "dev"
+    remote_dir: "/data/train-project"
+    
+  npu-cluster:
+    host: "npu-node-01"
+    user: "dev"
+    remote_dir: "/home/dev/project"
+```
+
+集群切换通过命令行参数完成：
+
+```bash
+# GPU 集群执行
+mtr -s gpu-cluster torchrun --nproc_per_node=8 train.py
+
+# NPU 集群执行
+mtr -s npu-cluster torchrun --nproc_per_node=8 train.py
+```
+
+**实时流式输出**
+
+远程训练日志实时回显至本地终端，包括 loss 曲线、吞吐量、显存占用等关键指标。代码异常时，堆栈信息直接显示在本地，AI Agent 可即时获取并分析。支持交互式命令（vim、ipython 等）。
+
+## 应用场景
+
+**分布式训练框架开发**
+
+在本地完成数据并行或模型并行逻辑的实现后，需要上多卡环境验证。传统流程涉及打包代码、scp 传输、ssh 登录、路径定位、执行运行等多个步骤。使用 mtr-cli 可简化为：
+
+```bash
+mtr torchrun --nproc_per_node=8 train.py
+```
+
+代码自动同步，远程执行，日志实时回传。
+
+**跨硬件平台验证**
+
+框架在 GPU 环境验证通过后，需要在 NPU 环境测试兼容性。传统方式需要重复环境配置和代码同步流程。使用 mtr-cli 只需切换服务器参数：
+
+```bash
+mtr -s npu-cluster torchrun --nproc_per_node=8 train.py
+```
+
+**即时调试**
+
+训练脚本执行过程中发生异常，报错信息和堆栈直接输出在本地终端。AI Agent 实时获取错误内容，可立即进行分析和建议，无需手动复制粘贴。
+
+## 收益分析
+
+- **时间效率**：消除手动 scp/rsync 和反复 ssh 登录的操作 overhead
+- **认知负担**：本地维护单一的代码库和配置，远程仅作为计算资源
+- **AI 辅助能力**：Agent 可获取完整执行日志，恢复实时调试辅助
+- **流程一致性**：屏蔽 GPU/NPU 后端差异，提供统一的开发体验
+
+## 快速开始
+
+### 安装
+
+推荐使用 uv 安装（更快、更可靠）：
+
+```bash
+uv pip install mtr-cli
+```
+
+或使用 pip：
+
+```bash
+pip install mtr-cli
+```
+
+### 初始化配置
+
+在项目目录下运行初始化命令，生成默认配置文件：
+
+```bash
+mtr --init
+```
+
+这会创建 `.mtr/config.yaml` 文件，包含默认配置模板。根据你的集群信息编辑该文件：
+
+```yaml
+servers:
+  dev-gpu:
+    host: "192.168.1.10"
+    user: "dev"
+    key_filename: "~/.ssh/id_rsa"
+    remote_dir: "/data/project"
+    sync: "rsync"
+```
+
+### 执行命令
+
+配置完成后，在项目根目录执行：
+
+```bash
+# 使用默认服务器
+mtr python train.py
+
+# 指定服务器
+mtr -s dev-gpu torchrun --nproc_per_node=8 train.py
+```
+
+完整 workflow：
+
+```bash
+# 1. 安装
+uv pip install mtr-cli
+
+# 2. 进入项目目录
+cd my-project
+
+# 3. 初始化配置
+mtr --init
+# 编辑 .mtr/config.yaml 添加服务器信息
+
+# 4. 运行
+mtr python train.py
+```
+
+### 常用参数
+
+```bash
+# 指定服务器
+mtr -s gpu-cluster python train.py
+
+# 跳过代码同步（仅执行命令）
+mtr --no-sync python train.py
+
+# 预览将要执行的命令（不实际运行）
+mtr --dry-run python train.py
+
+# 强制禁用 TTY（用于日志记录场景）
+mtr --no-tty python train.py
+
+# 启用日志记录
+mtr --enable-log python train.py
+
+# 从远程下载文件
+mtr --get /remote/path/to/file.txt --to ./local/file.txt
+```
+
+---
+
+mtr-cli 的目标是将远程训练的日常操作自动化，使开发者能够专注于框架本身，而非环境切换的繁琐流程。

{mtr_cli-0.2.0 → mtr_cli-0.3.0}/mtr/cli.py

@@ -15,6 +15,11 @@ defaults:
   # 选项: "rsync" (推荐), "sftp"
   sync: "rsync"
 
+  # 是否尊重 .gitignore 文件（仅 rsync 模式支持）
+  # 设置为 true 时，rsync 会自动读取项目根目录的 .gitignore 并排除匹配的文件
+  # SFTP 模式不支持此选项，如启用会报错
+  respect_gitignore: true
+
   exclude:
     - ".git/"
     - "__pycache__/"
@@ -186,6 +191,9 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
         # Resolve exclude
         exclude = config.global_defaults.get("exclude", []) + server_conf.get("exclude", [])
 
+        # Get respect_gitignore setting
+        respect_gitignore = config.get_respect_gitignore()
+
         # Determine engine
         engine = server_conf.get("sync", config.global_defaults.get("sync", "rsync"))
 
@@ -199,6 +207,7 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                 password=password,
                 port=port,
                 exclude=exclude,
+                respect_gitignore=respect_gitignore,
             )
         elif engine == "sftp":
             syncer = SftpSyncer(
@@ -210,6 +219,7 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                 password=password,
                 port=port,
                 exclude=exclude,
+                respect_gitignore=respect_gitignore,
             )
         else:
             click.secho(
@@ -225,11 +235,28 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                     logger.info(f"[DryRun] Would sync {local_dir} -> {remote_dir}", module="mtr.sync")
                 else:
                     if is_interactive and console:
-                        with console.status("[bold blue]Syncing code...", spinner="dots"):
-                            syncer.sync()
+                        # TTY mode: single line real-time update using Rich Live
+                        from rich.live import Live
+                        from rich.text import Text
+
+                        with Live(Text("Starting sync...", style="blue"), refresh_per_second=10) as live:
+
+                            def show_sync_progress(filename):
+                                # Get relative path for cleaner display
+                                rel_path = os.path.relpath(filename, local_dir)
+                                live.update(Text(f"Syncing: {rel_path}", style="blue"))
+
+                            syncer.sync(show_progress=True, progress_callback=show_sync_progress)
+                            live.update(Text("Sync completed!", style="green"))
                     else:
+                        # no_tty mode: print each file on new line
+                        def show_sync_progress(filename):
+                            rel_path = os.path.relpath(filename, local_dir)
+                            click.echo(f"Syncing: {rel_path}")
+
                         click.secho("Syncing code...", fg="blue")
-                        syncer.sync()
+                        syncer.sync(show_progress=True, progress_callback=show_sync_progress)
+                        click.secho("Sync completed!", fg="green")
                     logger.info(f"Sync completed: {local_dir} -> {remote_dir}", module="mtr.sync")
             except SyncError as e:
                 logger.error(f"Sync failed: {e}", module="mtr.sync")
@@ -260,6 +287,9 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
         # Resolve exclude
         exclude = config.global_defaults.get("exclude", []) + server_conf.get("exclude", [])
 
+        # Get respect_gitignore setting
+        respect_gitignore = config.get_respect_gitignore()
+
         # Determine engine
         engine = server_conf.get("sync", config.global_defaults.get("sync", "rsync"))
 
@@ -273,6 +303,7 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                 password=password,
                 port=port,
                 exclude=exclude,
+                respect_gitignore=respect_gitignore,
             )
         elif engine == "sftp":
             syncer = SftpSyncer(
@@ -284,6 +315,7 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                 password=password,
                 port=port,
                 exclude=exclude,
+                respect_gitignore=respect_gitignore,
             )
         else:
             click.secho(
@@ -298,12 +330,27 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
                 logger.info(f"[DryRun] Would download {remote_get_path} -> {local_dest}", module="mtr.sync")
             else:
                 if is_interactive and console:
-                    with console.status(f"[bold blue]Downloading {remote_get_path}...", spinner="dots"):
-                        syncer.download(remote_get_path, local_dest)
+                    # TTY mode: single line real-time update using Rich Live
+                    from rich.live import Live
+                    from rich.text import Text
+
+                    with Live(Text("Starting download...", style="blue"), refresh_per_second=10) as live:
+
+                        def show_download_progress(filename):
+                            live.update(Text(f"Downloading: {filename}", style="blue"))
+
+                        syncer.download(
+                            remote_get_path, local_dest, show_progress=True, progress_callback=show_download_progress
+                        )
+                        live.update(Text("Download completed!", style="green"))
                     console.print(f"✅ [green]Downloaded:[/green] {remote_get_path} -> {local_dest}")
                 else:
+                    # no_tty mode: print each file on new line
+                    def show_download_progress(filename):
+                        click.echo(f"Downloading: {filename}")
+
                     click.secho(f"Downloading {remote_get_path}...", fg="blue")
-                    syncer.download(remote_get_path, local_dest)
+                    syncer.download(remote_get_path, local_dest, show_progress=True, progress_callback=show_download_progress)
                     click.secho(f"Download completed: {local_dest}", fg="green")
                 logger.info(f"Download completed: {remote_get_path} -> {local_dest}", module="mtr.sync")
         except SyncError as e:

{mtr_cli-0.2.0 → mtr_cli-0.3.0}/mtr/config.py

@@ -19,6 +19,20 @@ class Config:
     server_config: Dict[str, Any]
     global_defaults: Dict[str, Any]
 
+    def get_respect_gitignore(self) -> bool:
+        """Get respect_gitignore setting, default True.
+
+        Priority: server config > global defaults > True (default)
+        """
+        # Check server config first
+        if "respect_gitignore" in self.server_config:
+            return self.server_config["respect_gitignore"]
+        # Then check global defaults
+        if "respect_gitignore" in self.global_defaults:
+            return self.global_defaults["respect_gitignore"]
+        # Default to True
+        return True
+
 
 class ConfigLoader:
     def __init__(self, config_path: Optional[str] = None):