mtr-cli 0.1.0__tar.gz

mtr_cli-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Deps
+node_modules/
+
+.mtr
+
+# Debug logs
+debug.log
+*.log

mtr_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types: [yaml]
+        name: Format YAML

mtr_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

mtr_cli-0.1.0/AGENTS.md

@@ -0,0 +1,85 @@
+MTRemote (mtr) 需求规格与设计文档
+1. 项目概述
+MTRemote 是一个用于 AI Infra 开发的 CLI 工具，旨在简化“本地开发、远端执行”的工作流。它允许开发者在本地修改代码，通过简单的命令前缀 mtr，自动将代码同步到远端服务器并在其上执行命令，同时保持本地的交互体验。
+2. 核心功能需求
+2.1 多服务器配置与管理
+*   多环境支持：支持在配置文件中定义多个服务器节点（如 dev-gpu, prod-train）。
+*   默认服务器策略：
+    1.  若 CLI 指定 -s/--server，使用指定服务器。
+    2.  若未指定，检查配置中是否存在 default 字段。
+    3.  若无 default 字段，自动选择 servers 列表中的第一个定义的服务器。
+*   认证管理：支持在配置文件中显式指定 SSH 私钥路径 (key_filename) 或 密码 (password)，不依赖系统 SSH Agent。
+2.2 智能代码同步 (Sync Engine)
+*   双引擎支持：
+    *   *Rsync (推荐)*：调用系统 rsync 命令，通过 SSH 隧道传输，支持增量同步，速度快。
+    *   *SFTP (兼容)*：基于 paramiko 实现的纯 Python 同步，用于无 rsync 的环境。
+*   可配置性：支持在全局或单台服务器级别指定同步引擎。
+*   文件过滤：支持忽略特定文件（如 .git, __pycache__），支持 .mtrignore 或配置字段。
+2.3 远程执行 (Remote Execution)
+*   命令透传：mtr python train.py --lr 0.01 -> 远端执行 python train.py --lr 0.01。
+*   环境上下文：支持指定远程工作目录 (remote_dir)。
+*   实时流式输出：远端的 stdout 和 stderr 必须实时回显到本地，支持颜色代码。
+*   交互性：支持 PTY 分配，允许运行交互式命令（如 ipython, pdb）。
+---
+3. 系统设计与模块划分
+我们将系统划分为四个核心模块，这也将是 TDD 的测试边界：
+3.1 配置模块 (mtr.config)
+负责加载、合并和校验配置。
+*   输入：CLI 参数、./.mtr/config.yaml、~/.config/mtr/config.yaml。
+*   逻辑：
+    *   配置层级合并（Project Config 覆盖 User Config）。
+    *   解析服务器列表，确定 Target Host。
+*   *数据结构 (Config Schema)*：
+        defaults:
+      sync: "rsync" # or "sftp"
+      exclude: [".git", "__pycache__"]
+    servers:
+      gpu-01: # 第一个即为隐式默认
+        host: "192.168.1.10"
+        user: "dev"
+        key_filename: "~/.ssh/id_rsa"
+        remote_dir: "/data/codes/project_x"
+      
+      fallback-node:
+        host: "10.0.0.5"
+        user: "dev"
+        password: "secret_password"
+        sync: "sftp" # 覆盖默认配置
+    
+3.2 连接模块 (mtr.ssh)
+负责底层的 SSH 连接管理。
+*   基于 paramiko 封装。
+*   提供 connect(), exec_command_stream() 接口。
+*   处理连接异常和认证失败。
+3.3 同步模块 (mtr.sync)
+定义 BaseSyncer 抽象基类，统一接口 sync(local_dir, remote_dir, exclude_list)。
+*   RsyncSyncer: 构造 subprocess 调用系统命令。
+*   SftpSyncer: 遍历文件树，对比 mtime/size，使用 paramiko sftp 上传。
+3.4 CLI 入口 (mtr.cli)
+*   基于 click 库。
+*   负责参数解析、调用 Config -> Connect -> Sync -> Exec 流程。
+---
+4. TDD 测试策略与目录规划
+在编写任何业务代码前，我们将按照以下结构建立测试目录。
+4.1 测试目录结构
+tests/
+├── __init__.py
+├── conftest.py             # 通用 Fixtures (模拟配置文件、模拟文件系统)
+├── unit/                   # 单元测试 (Mock 外部依赖)
+│   ├── test_config.py      # 重点：测试配置加载优先级、默认服务器选择逻辑
+│   ├── test_sync_rsync.py  # 测试 Rsync 命令生成逻辑 (不实际传输)
+│   ├── test_sync_sftp.py   # 测试文件过滤逻辑、差异对比逻辑 (Mock SFTP)
+│   └── test_ssh.py         # 测试 SSH 客户端封装 (Mock paramiko)
+└── integration/            # 集成/功能测试
+    └── test_cli_flow.py    # 测试 CLI 参数解析与流程串联
+4.2 关键测试用例 (Test Cases)
+1. 配置加载测试 (test_config.py)
+*   test_load_default_server_explicit: 当配置中有 default 字段时，应选中该 Server。
+*   test_load_default_server_implicit_first: 当无 default 字段时，应选中 servers 列表的第一个。
+*   test_server_override: CLI -s 参数应覆盖配置文件的默认值。
+*   test_auth_config: 验证 Key 和 Password 都能被正确读取。
+2. 同步逻辑测试 (test_sync_*.py)
+*   test_rsync_command_generation: 验证生成的 rsync 命令是否包含正确的 exclude 参数和路径。
+*   test_sftp_should_sync: 给定本地和远端文件状态（大小/时间），验证 should_sync 逻辑是否正确判断需要更新的文件。
+3. SSH 执行测试 (test_ssh.py)
+*   test_exec_stream: Mock paramiko 的 stdout，验证回调函数能否正确接收流式数据。

mtr_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Yang Xiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mtr_cli-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: mtr-cli
+Version: 0.1.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
+Author: lecoan
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: paramiko>=2.11.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=12.0.0
+Description-Content-Type: text/markdown
+
+# MTRemote (mtr)
+
+MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行工具。它允许你在本地修改代码，通过简单的 `mtr` 前缀，自动将代码同步到远端 GPU 服务器并执行命令，同时保留本地的交互体验（实时日志、颜色高亮、Ctrl+C 支持）。
+
+## 🚀 核心特性
+
+*   **多服务器管理**：通过配置文件管理多个 GPU 节点，支持默认服务器 (Implicit/Explicit)。
+*   **智能同步引擎**：
+    *   **Rsync (推荐)**：调用系统 `rsync`，支持增量同步，速度极快。支持 `sshpass` 自动处理密码认证。
+    *   **SFTP (兼容)**：纯 Python 实现，适用于无 `rsync` 的环境，配置简单。
+*   **双向同步**：支持从远端下载文件/文件夹到本地（`--get` 参数）。
+*   **双模式交互 (Dual-Mode Interaction)**：
+    *   **交互模式 (Interactive)**：自动检测 TTY，支持 PTY 分配、Raw Mode、Rich UI 动画。完美支持 `vim`, `ipython`, `pdb`, `htop`。
+    *   **批处理模式 (Batch)**：当被脚本调用或重定向时自动切换。禁用 PTY 和动画，输出纯净文本，适合 AI Agent 集成或 CI/CD。
+*   **环境预设 (Pre-cmd)**：支持在执行命令前自动加载环境（如 `conda activate`, `source .env`）。
+*   **调试日志**：可选的文件日志系统，按会话独立存储，便于排查问题。
+*   **零侵入**：只需在现有命令前加上 `mtr`。
+
+## 📦 安装
+
+推荐使用 `uv` 或 `pipx` 安装：
+
+```bash
+uv tool install mtremote
+# 或者
+pip install mtremote
+```
+
+### 系统依赖
+
+MTRemote 需要以下系统命令：
+
+| 命令 | 用途 | 安装方式 |
+|------|------|----------|
+| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` |
+| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 |
+| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) |
+
+**注意**：交互式 Shell 功能（如 `mtr bash`, `mtr ipython`）**必须**安装 `ssh`。密码认证**必须**安装 `sshpass`。
+
+## 🛠️ 快速开始
+
+### 1. 初始化配置
+
+在你的项目根目录下运行：
+
+```bash
+mtr --init
+```
+
+这将在 `.mtr/config.yaml` 生成配置文件。
+
+### 2. 编辑配置
+
+编辑 `.mtr/config.yaml`，填入你的服务器信息：
+
+```yaml
+defaults:
+  sync: "rsync"  # 或 "sftp"
+  exclude: [".git/", "__pycache__/"]
+  download_dir: "./downloads"  # 默认下载位置（可选）
+
+servers:
+  gpu-node:
+    host: "192.168.1.100"
+    user: "your_username"
+    key_filename: "~/.ssh/id_rsa"
+    remote_dir: "/home/your_username/projects/my-project"
+    download_dir: "./backups/gpu"  # 该服务器的下载位置（可选，覆盖默认值）
+    pre_cmd: "source ~/.bashrc && conda activate pytorch_env"
+```
+
+### 3. 运行命令
+
+现在，你可以在本地直接运行远程命令：
+
+```bash
+# 同步代码并在 gpu-node 上运行 python train.py
+mtr python train.py --epochs 10
+
+# 进入远程交互式 Shell (支持 Tab 补全和颜色)
+mtr bash
+
+# 使用 ipython 调试
+mtr ipython
+
+# 指定特定服务器
+mtr -s prod-node python train.py
+```
+
+## 📖 命令行选项
+
+```bash
+mtr [OPTIONS] COMMAND [ARGS...]
+
+Options:
+  -s, --server TEXT        Target server alias
+  --sync / --no-sync       Enable/Disable code sync [default: True]
+  --dry-run                Print commands without executing
+  --tty / --no-tty         Force enable/disable TTY [default: True]
+  --get TEXT               Remote path to download from
+  --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)
+  --init                   Initialize configuration file
+  --help                   Show this message and exit
+```
+
+### 常用选项示例
+
+```bash
+# 禁用同步，直接执行命令
+mtr --no-sync python script.py
+
+# 强制批处理模式（无颜色、无动画）
+mtr --no-tty python train.py > output.log
+
+# 启用调试日志
+mtr --enable-log --log-level DEBUG python train.py
+
+# 指定自定义日志路径
+mtr --enable-log --log-file ./debug.log python train.py
+```
+
+## 📖 高级用法
+
+### 1. 强制批处理模式 (--no-tty)
+如果你在终端中运行但希望获得纯文本输出（不想要进度条或颜色控制字符），可以使用 `--no-tty`：
+
+```bash
+mtr --no-tty python train.py > log.txt
+```
+
+### 2. 使用 SFTP 模式
+如果本地或远程无法使用 rsync，可以在配置中指定 `sync: sftp`：
+
+```yaml
+servers:
+  win-server:
+    host: "10.0.0.9"
+    sync: "sftp"
+    password: "secret_password"
+```
+
+### 3. 密码认证
+支持 SSH 密码认证，但推荐使用 SSH Key。
+*   **交互式 Shell**: 使用 `sshpass` 包装 `ssh -t` 命令。
+*   **SFTP**: 原生支持密码。
+*   **Rsync**: 需要本地安装 `sshpass` 工具才能使用密码认证。
+
+**密码认证依赖**: 使用密码认证时，必须安装 `sshpass`:
+```bash
+# macOS
+brew install hudochenkov/sshpass/sshpass
+
+# Ubuntu/Debian
+sudo apt-get install sshpass
+
+# CentOS/RHEL
+sudo yum install sshpass
+```
+
+### 4. 从远端下载文件 (--get)
+使用 `--get` 参数可以从远端服务器下载文件或文件夹到本地：
+
+```bash
+# 下载文件到当前目录
+mtr --get /remote/path/to/file.txt
+
+# 下载文件到指定位置
+mtr --get /remote/path/to/file.txt --to ./local/path/
+
+# 下载整个文件夹
+mtr --get /remote/path/to/checkpoints/ --to ./backups/
+
+# 跳过上传同步，仅下载
+mtr --no-sync --get /remote/path/to/file.txt
+```
+
+**配置下载目录**：
+可以在配置文件中设置默认下载位置：
+
+```yaml
+defaults:
+  download_dir: "./downloads"  # 默认下载位置
+
+servers:
+  gpu-node:
+    host: "192.168.1.100"
+    download_dir: "./backups/gpu"  # 该服务器的下载位置（覆盖默认值）
+```
+
+**路径解析优先级**：
+1. `--to` 参数指定的路径
+2. 服务器配置中的 `download_dir`
+3. 默认配置中的 `download_dir`
+4. 当前工作目录
+
+### 5. 调试日志 (--enable-log)
+当遇到问题需要排查时，可以启用文件日志：
+
+```bash
+# 启用 INFO 级别日志（默认）
+mtr --enable-log python train.py
+
+# 启用 DEBUG 级别日志（更详细）
+mtr --enable-log --log-level DEBUG python train.py
+
+# 查看日志
+cat ~/.mtr/logs/mtr_20260128_171216.log
+```
+
+日志文件按会话独立生成，格式为 `mtr_YYYYMMDD_HHMMSS.log`，包含：
+- 命令启动参数
+- 配置加载过程
+- SSH 连接状态
+- 文件同步详情
+- 命令执行结果
+
+## 🤖 AI Agent 集成指南
+
+MTRemote 非常适合作为 AI Agent (如 OpenCode, LangChain Agents) 的底层执行工具。
+
+### 为什么适合 Agent?
+1.  **自动同步**：Agent 只需要修改本地文件，`mtr` 负责将修改“热更新”到运行环境。
+2.  **纯净输出**：使用 `--no-tty` 参数，`mtr` 会禁用 ANSI 颜色代码、进度条动画和交互式 Shell 提示符，只返回最纯粹的 stdout/stderr。这大大降低了 Agent 解析日志的难度。
+3.  **状态透传**：`mtr` 的退出代码 (Exit Code) 与远程命令完全一致。Agent 可以通过 `$?` 判断远程任务是否成功。
+
+### 推荐调用方式
+
+Agent 在调用 `mtr` 时，**强烈建议**始终加上 `--no-tty` 参数。
+
+```python
+import subprocess
+
+def run_remote_command(cmd):
+    # 使用 --no-tty 确保输出无干扰
+    full_cmd = ["mtr", "--no-tty"] + cmd.split()
+    
+    result = subprocess.run(
+        full_cmd, 
+        capture_output=True, 
+        text=True
+    )
+    
+    if result.returncode != 0:
+        return f"Error: {result.stderr}"
+    return result.stdout
+
+# 示例：Agent 修改完代码后运行测试
+output = run_remote_command("python tests/test_model.py")
+```
+
+## 📖 配置详解
+
+请参考 [examples/config.yaml](examples/config.yaml) 获取完整的配置示例。
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 PR！
+
+---
+License: MIT

mtr_cli-0.1.0/README.md

@@ -0,0 +1,264 @@
+# MTRemote (mtr)
+
+MTRemote 是一个专为 AI Infra 和 Python/C++ 混合开发设计的命令行工具。它允许你在本地修改代码，通过简单的 `mtr` 前缀，自动将代码同步到远端 GPU 服务器并执行命令，同时保留本地的交互体验（实时日志、颜色高亮、Ctrl+C 支持）。
+
+## 🚀 核心特性
+
+*   **多服务器管理**：通过配置文件管理多个 GPU 节点，支持默认服务器 (Implicit/Explicit)。
+*   **智能同步引擎**：
+    *   **Rsync (推荐)**：调用系统 `rsync`，支持增量同步，速度极快。支持 `sshpass` 自动处理密码认证。
+    *   **SFTP (兼容)**：纯 Python 实现，适用于无 `rsync` 的环境，配置简单。
+*   **双向同步**：支持从远端下载文件/文件夹到本地（`--get` 参数）。
+*   **双模式交互 (Dual-Mode Interaction)**：
+    *   **交互模式 (Interactive)**：自动检测 TTY，支持 PTY 分配、Raw Mode、Rich UI 动画。完美支持 `vim`, `ipython`, `pdb`, `htop`。
+    *   **批处理模式 (Batch)**：当被脚本调用或重定向时自动切换。禁用 PTY 和动画，输出纯净文本，适合 AI Agent 集成或 CI/CD。
+*   **环境预设 (Pre-cmd)**：支持在执行命令前自动加载环境（如 `conda activate`, `source .env`）。
+*   **调试日志**：可选的文件日志系统，按会话独立存储，便于排查问题。
+*   **零侵入**：只需在现有命令前加上 `mtr`。
+
+## 📦 安装
+
+推荐使用 `uv` 或 `pipx` 安装：
+
+```bash
+uv tool install mtremote
+# 或者
+pip install mtremote
+```
+
+### 系统依赖
+
+MTRemote 需要以下系统命令：
+
+| 命令 | 用途 | 安装方式 |
+|------|------|----------|
+| `ssh` | 交互式 Shell (TTY) | macOS/Linux 自带，或 `brew install openssh` |
+| `rsync` | 快速文件同步 (推荐) | macOS/Linux 自带 |
+| `sshpass` | 密码认证 (可选) | `brew install hudochenkov/sshpass/sshpass` (macOS) / `apt install sshpass` (Ubuntu) |
+
+**注意**：交互式 Shell 功能（如 `mtr bash`, `mtr ipython`）**必须**安装 `ssh`。密码认证**必须**安装 `sshpass`。
+
+## 🛠️ 快速开始
+
+### 1. 初始化配置
+
+在你的项目根目录下运行：
+
+```bash
+mtr --init
+```
+
+这将在 `.mtr/config.yaml` 生成配置文件。
+
+### 2. 编辑配置
+
+编辑 `.mtr/config.yaml`，填入你的服务器信息：
+
+```yaml
+defaults:
+  sync: "rsync"  # 或 "sftp"
+  exclude: [".git/", "__pycache__/"]
+  download_dir: "./downloads"  # 默认下载位置（可选）
+
+servers:
+  gpu-node:
+    host: "192.168.1.100"
+    user: "your_username"
+    key_filename: "~/.ssh/id_rsa"
+    remote_dir: "/home/your_username/projects/my-project"
+    download_dir: "./backups/gpu"  # 该服务器的下载位置（可选，覆盖默认值）
+    pre_cmd: "source ~/.bashrc && conda activate pytorch_env"
+```
+
+### 3. 运行命令
+
+现在，你可以在本地直接运行远程命令：
+
+```bash
+# 同步代码并在 gpu-node 上运行 python train.py
+mtr python train.py --epochs 10
+
+# 进入远程交互式 Shell (支持 Tab 补全和颜色)
+mtr bash
+
+# 使用 ipython 调试
+mtr ipython
+
+# 指定特定服务器
+mtr -s prod-node python train.py
+```
+
+## 📖 命令行选项
+
+```bash
+mtr [OPTIONS] COMMAND [ARGS...]
+
+Options:
+  -s, --server TEXT        Target server alias
+  --sync / --no-sync       Enable/Disable code sync [default: True]
+  --dry-run                Print commands without executing
+  --tty / --no-tty         Force enable/disable TTY [default: True]
+  --get TEXT               Remote path to download from
+  --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)
+  --init                   Initialize configuration file
+  --help                   Show this message and exit
+```
+
+### 常用选项示例
+
+```bash
+# 禁用同步，直接执行命令
+mtr --no-sync python script.py
+
+# 强制批处理模式（无颜色、无动画）
+mtr --no-tty python train.py > output.log
+
+# 启用调试日志
+mtr --enable-log --log-level DEBUG python train.py
+
+# 指定自定义日志路径
+mtr --enable-log --log-file ./debug.log python train.py
+```
+
+## 📖 高级用法
+
+### 1. 强制批处理模式 (--no-tty)
+如果你在终端中运行但希望获得纯文本输出（不想要进度条或颜色控制字符），可以使用 `--no-tty`：
+
+```bash
+mtr --no-tty python train.py > log.txt
+```
+
+### 2. 使用 SFTP 模式
+如果本地或远程无法使用 rsync，可以在配置中指定 `sync: sftp`：
+
+```yaml
+servers:
+  win-server:
+    host: "10.0.0.9"
+    sync: "sftp"
+    password: "secret_password"
+```
+
+### 3. 密码认证
+支持 SSH 密码认证，但推荐使用 SSH Key。
+*   **交互式 Shell**: 使用 `sshpass` 包装 `ssh -t` 命令。
+*   **SFTP**: 原生支持密码。
+*   **Rsync**: 需要本地安装 `sshpass` 工具才能使用密码认证。
+
+**密码认证依赖**: 使用密码认证时，必须安装 `sshpass`:
+```bash
+# macOS
+brew install hudochenkov/sshpass/sshpass
+
+# Ubuntu/Debian
+sudo apt-get install sshpass
+
+# CentOS/RHEL
+sudo yum install sshpass
+```
+
+### 4. 从远端下载文件 (--get)
+使用 `--get` 参数可以从远端服务器下载文件或文件夹到本地：
+
+```bash
+# 下载文件到当前目录
+mtr --get /remote/path/to/file.txt
+
+# 下载文件到指定位置
+mtr --get /remote/path/to/file.txt --to ./local/path/
+
+# 下载整个文件夹
+mtr --get /remote/path/to/checkpoints/ --to ./backups/
+
+# 跳过上传同步，仅下载
+mtr --no-sync --get /remote/path/to/file.txt
+```
+
+**配置下载目录**：
+可以在配置文件中设置默认下载位置：
+
+```yaml
+defaults:
+  download_dir: "./downloads"  # 默认下载位置
+
+servers:
+  gpu-node:
+    host: "192.168.1.100"
+    download_dir: "./backups/gpu"  # 该服务器的下载位置（覆盖默认值）
+```
+
+**路径解析优先级**：
+1. `--to` 参数指定的路径
+2. 服务器配置中的 `download_dir`
+3. 默认配置中的 `download_dir`
+4. 当前工作目录
+
+### 5. 调试日志 (--enable-log)
+当遇到问题需要排查时，可以启用文件日志：
+
+```bash
+# 启用 INFO 级别日志（默认）
+mtr --enable-log python train.py
+
+# 启用 DEBUG 级别日志（更详细）
+mtr --enable-log --log-level DEBUG python train.py
+
+# 查看日志
+cat ~/.mtr/logs/mtr_20260128_171216.log
+```
+
+日志文件按会话独立生成，格式为 `mtr_YYYYMMDD_HHMMSS.log`，包含：
+- 命令启动参数
+- 配置加载过程
+- SSH 连接状态
+- 文件同步详情
+- 命令执行结果
+
+## 🤖 AI Agent 集成指南
+
+MTRemote 非常适合作为 AI Agent (如 OpenCode, LangChain Agents) 的底层执行工具。
+
+### 为什么适合 Agent?
+1.  **自动同步**：Agent 只需要修改本地文件，`mtr` 负责将修改“热更新”到运行环境。
+2.  **纯净输出**：使用 `--no-tty` 参数，`mtr` 会禁用 ANSI 颜色代码、进度条动画和交互式 Shell 提示符，只返回最纯粹的 stdout/stderr。这大大降低了 Agent 解析日志的难度。
+3.  **状态透传**：`mtr` 的退出代码 (Exit Code) 与远程命令完全一致。Agent 可以通过 `$?` 判断远程任务是否成功。
+
+### 推荐调用方式
+
+Agent 在调用 `mtr` 时，**强烈建议**始终加上 `--no-tty` 参数。
+
+```python
+import subprocess
+
+def run_remote_command(cmd):
+    # 使用 --no-tty 确保输出无干扰
+    full_cmd = ["mtr", "--no-tty"] + cmd.split()
+    
+    result = subprocess.run(
+        full_cmd, 
+        capture_output=True, 
+        text=True
+    )
+    
+    if result.returncode != 0:
+        return f"Error: {result.stderr}"
+    return result.stdout
+
+# 示例：Agent 修改完代码后运行测试
+output = run_remote_command("python tests/test_model.py")
+```
+
+## 📖 配置详解
+
+请参考 [examples/config.yaml](examples/config.yaml) 获取完整的配置示例。
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 PR！
+
+---
+License: MIT