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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtr-cli
-Version: 0.1.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
@@ -25,7 +25,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=12.0.0
 Description-Content-Type: text/markdown
 
-# MTRemote (mtr)
+# MTRemote (mtr-cli)
 
 MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行工具。它允许你在本地修改代码，通过简单的 `mtr` 前缀，自动将代码同步到远端 GPU 服务器并执行命令，同时保留本地的交互体验（实时日志、颜色高亮、Ctrl+C 支持）。
 
@@ -48,20 +48,30 @@ MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行
 推荐使用 `uv` 或 `pipx` 安装：
 
 ```bash
-uv tool install mtremote
+uv tool install mtr-cli
 # 或者
-pip install mtremote
+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`。
 
@@ -129,7 +139,7 @@ Options:
   --to TEXT                Local destination path for download (optional)
   --enable-log             Enable logging to file
   --log-level TEXT         Log level: DEBUG/INFO/WARNING/ERROR [default: INFO]
-  --log-file PATH          Custom log file path (default: ~/.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)
+  --log-file PATH          Custom log file path (default: ./.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)
   --init                   Initialize configuration file
   --help                   Show this message and exit
 ```
@@ -192,9 +202,12 @@ sudo yum install sshpass
 使用 `--get` 参数可以从远端服务器下载文件或文件夹到本地：
 
 ```bash
-# 下载文件到当前目录
+# 下载文件（绝对路径）
 mtr --get /remote/path/to/file.txt
 
+# 下载文件（相对路径，基于 remote_dir）
+mtr --get checkpoints/model.pt
+
 # 下载文件到指定位置
 mtr --get /remote/path/to/file.txt --to ./local/path/
 
@@ -205,6 +218,10 @@ mtr --get /remote/path/to/checkpoints/ --to ./backups/
 mtr --no-sync --get /remote/path/to/file.txt
 ```
 
+**路径解析规则**：
+- **绝对路径**（以 `/` 开头）：直接使用指定的完整路径
+- **相对路径**：自动拼接 `remote_dir`，例如配置 `remote_dir: "/workdir/project"`，执行 `--get checkpoints/model.pt` 将下载 `/workdir/project/checkpoints/model.pt`
+
 **配置下载目录**：
 可以在配置文件中设置默认下载位置：
 
@@ -235,7 +252,7 @@ mtr --enable-log python train.py
 mtr --enable-log --log-level DEBUG python train.py
 
 # 查看日志
-cat ~/.mtr/logs/mtr_20260128_171216.log
+cat ./.mtr/logs/mtr_20260128_171216.log
 ```
 
 日志文件按会话独立生成，格式为 `mtr_YYYYMMDD_HHMMSS.log`，包含：

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

@@ -1,4 +1,4 @@
-# MTRemote (mtr)
+# MTRemote (mtr-cli)
 
 MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行工具。它允许你在本地修改代码，通过简单的 `mtr` 前缀，自动将代码同步到远端 GPU 服务器并执行命令，同时保留本地的交互体验（实时日志、颜色高亮、Ctrl+C 支持）。
 
@@ -21,20 +21,30 @@ MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行
 推荐使用 `uv` 或 `pipx` 安装：
 
 ```bash
-uv tool install mtremote
+uv tool install mtr-cli
 # 或者
-pip install mtremote
+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`。
 
@@ -102,7 +112,7 @@ Options:
   --to TEXT                Local destination path for download (optional)
   --enable-log             Enable logging to file
   --log-level TEXT         Log level: DEBUG/INFO/WARNING/ERROR [default: INFO]
-  --log-file PATH          Custom log file path (default: ~/.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)
+  --log-file PATH          Custom log file path (default: ./.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)
   --init                   Initialize configuration file
   --help                   Show this message and exit
 ```
@@ -165,9 +175,12 @@ sudo yum install sshpass
 使用 `--get` 参数可以从远端服务器下载文件或文件夹到本地：
 
 ```bash
-# 下载文件到当前目录
+# 下载文件（绝对路径）
 mtr --get /remote/path/to/file.txt
 
+# 下载文件（相对路径，基于 remote_dir）
+mtr --get checkpoints/model.pt
+
 # 下载文件到指定位置
 mtr --get /remote/path/to/file.txt --to ./local/path/
 
@@ -178,6 +191,10 @@ mtr --get /remote/path/to/checkpoints/ --to ./backups/
 mtr --no-sync --get /remote/path/to/file.txt
 ```
 
+**路径解析规则**：
+- **绝对路径**（以 `/` 开头）：直接使用指定的完整路径
+- **相对路径**：自动拼接 `remote_dir`，例如配置 `remote_dir: "/workdir/project"`，执行 `--get checkpoints/model.pt` 将下载 `/workdir/project/checkpoints/model.pt`
+
 **配置下载目录**：
 可以在配置文件中设置默认下载位置：
 
@@ -208,7 +225,7 @@ mtr --enable-log python train.py
 mtr --enable-log --log-level DEBUG python train.py
 
 # 查看日志
-cat ~/.mtr/logs/mtr_20260128_171216.log
+cat ./.mtr/logs/mtr_20260128_171216.log
 ```
 
 日志文件按会话独立生成，格式为 `mtr_YYYYMMDD_HHMMSS.log`，包含：

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.1.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__/"
@@ -73,7 +78,7 @@ def _init_config():
 @click.option("--init", is_flag=True, help="Initialize a configuration file in current directory")
 @click.option("--enable-log", is_flag=True, help="Enable logging to file")
 @click.option("--log-level", default="INFO", help="Log level (DEBUG/INFO/WARNING/ERROR)")
-@click.option("--log-file", help="Path to log file (default: ~/.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)")
+@click.option("--log-file", help="Path to log file (default: ./.mtr/logs/mtr_YYYYMMDD_HHMMSS.log)")
 @click.option("--get", "remote_get_path", help="Remote path to download from")
 @click.option("--to", "local_dest_path", help="Local destination path for download (optional)")
 @click.argument("command", nargs=-1, type=click.UNPROCESSED)
@@ -86,9 +91,9 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
     # Setup logging if enabled
     if enable_log:
         if not log_file:
-            # Generate default log file path: ~/.mtr/logs/mtr_YYYYMMDD_HHMMSS.log
+            # Generate default log file path: ./.mtr/logs/mtr_YYYYMMDD_HHMMSS.log
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-            log_dir = os.path.expanduser("~/.mtr/logs")
+            log_dir = os.path.join(os.getcwd(), ".mtr/logs")
             log_file = os.path.join(log_dir, f"mtr_{timestamp}.log")
 
         try:
@@ -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")
@@ -238,6 +265,13 @@ def cli(server, sync, dry_run, tty, init, enable_log, log_level, log_file, remot
 
     # 3. Download from remote (if --get is specified)
     if remote_get_path:
+        # Resolve relative remote path from remote_dir
+        if not remote_get_path.startswith("/"):
+            if not remote_dir:
+                click.secho("Error: 'remote_dir' is required for relative --get path.", fg="red", err=True)
+                sys.exit(1)
+            remote_get_path = os.path.join(remote_dir, remote_get_path)
+
         # Resolve local destination path
         if cli_dest:
             local_dest = cli_dest
@@ -253,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"))
 
@@ -266,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(
@@ -277,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(
@@ -291,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.1.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):