rdev

rdev 用于“本地写代码，远程构建/运行”的开发方式。它把文件同步、远程命令、服务启动和 TUI 日志面板放在一个工具里，主要面向 Windows 本地编辑、Linux 服务器运行项目的场景。

核心能力

• rdev sync：同步一次。
• rdev up：持续监听文件变化并同步。
• rdev up --tui：打开同步、session、daemon 状态集成界面。
• rdev exec "cmd"：通过本地 daemon 复用 SSH 连接执行远程命令。
• rdev service start <name>：启动远端长期服务，ready 后退出，服务留在后台。
• rdev port <port>：查看远端端口占用，必要时显式 --kill。
• rdev why-ignore <path>：解释某个文件为什么没有同步。

安装

开发构建：

cargo build --release

安装到 Cargo bin：

cargo install --path . --force

如果只是替换当前机器上的版本，也可以直接复制 release 产物：

Copy-Item target\release\rdev.exe "$env:USERPROFILE\.cargo\bin\rdev.exe" -Force

开发版建议用单独名字，避免和正式项目里运行的 rdev.exe 混淆：

.\scripts\dev-release.ps1
J:\cargo-target\release\rdev-dev.exe doctor

远程 daemon/exec 改动可用 smoke 脚本验证。脚本使用当前目录的 .rdev/config.toml，会停止并重启当前项目 daemon：

.\scripts\smoke-daemon-exec.ps1 -RdevPath J:\cargo-target\release\rdev.exe

快速开始

在项目根目录初始化配置：

rdev init --host root@example.com --path /root/my-project

初始化或更新一个 profile：

rdev init --profile dev-a --host root@dev-a.example.com --port 2222 --path /root/my-project-dev-a

检查环境：

rdev doctor
rdev auth-check

常用启动方式：

rdev sync
rdev up
rdev up --tui

配置文件默认是：

.rdev/config.toml

配置示例

version = 1

[remote]
host = "root@example.com"
port = 22
path = "/root/my-project"
identity_file = ""
passphrase_env = ""

[sync]
local_path = "."
watch_dirs = ["."]
exclude = [".git", "target", "node_modules", "data", ".rdev", "dist", "build"]
use_gitignore = true
debounce_ms = 300
delete = true
full_sync_threshold = 32
backend = "auto"

[command]
default_shell = "bash"
remote_env = {}

[commands.backend-lint]
dir = "backend"
command = "cargo clippy --all-features -- -D warnings"

[services.backend]
dir = "backend"
command = "cargo run"
ready_pattern = "listening on"
url = "http://10.124.124.0:5150"

exclude 支持 ! 包含规则。下面表示排除任意路径下名为 data 的目录或文件，但保留任意路径下的 src/data：

exclude = ["data", "!src/data"]

多 Profile

同一项目目录可以配置多个远端环境。基础配置仍在 .rdev/config.toml，profile 放在 .rdev/profiles/<name>.toml：

# .rdev/config.toml
version = 1
default_profile = "dev-a"

[remote]
host = "root@example.com"
port = 22
path = "/root/my-project"

# .rdev/profiles/dev-a.toml
[remote]
host = "root@dev-a.example.com"
port = 2222
path = "/root/my-project-dev-a"

激活优先级：

rdev --profile dev-b ...
RDEV_PROFILE=dev-a
default_profile
旧单 profile 配置

PowerShell 中给后续 Codex/Claude CLI 继承：

$env:RDEV_PROFILE = "dev-a"
codex

用 init 创建 profile 时，如果基础配置不存在，rdev 会同时创建 .rdev/config.toml，并把第一个 profile 设为 default_profile。如果基础配置已经有默认 profile，新增 profile 不会覆盖它；需要切换默认值时加 --default-profile：

rdev init --profile dev-b --default-profile --host root@dev-b.example.com --path /root/my-project-dev-b

有 profile 时，本地 daemon、sync 状态、exec/TUI 日志会隔离到 .rdev/state/<profile>/ 和 .rdev/logs/<profile>/；远端 session/service 状态会隔离到远端项目的 .rdev/sessions/<profile>/、.rdev/services/<profile>/。

远程命令

优先用 exec：

rdev exec "pwd"
rdev exec "cargo test"
rdev exec backend-lint
rdev exec --summary "cargo test"

exec 会通过项目 daemon 复用 SSH 连接，适合 Codex、Claude Code 这类频繁执行命令的场景。--summary 会把完整日志写入 .rdev/logs/，终端只打印摘要。

需要在执行前确认本地是否有同步后的改动，可以加 --check-sync。它只给出警告，不阻止命令执行：

rdev exec --check-sync "cargo test"

run 是一次性 SSH 命令，不使用 daemon：

rdev run "pwd"

它适合偶尔执行，或者排查 daemon 本身问题。

命令别名用 alias set 管理：

rdev alias set backend-lint --dir backend -- cargo clippy --all-features -- -D warnings
rdev alias list
rdev alias delete backend-lint

alias 只会被 rdev exec <alias> 和 rdev run <alias> 展开，不接入 TUI。

TUI

启动：

rdev up --tui

常用命令：

new session web -- pnpm dev
new remote-session api -- cd backend && cargo run
ps
logs web
tail web
stop web
enter web
restart web
sync
daemon status
help
quit
quit!

常用快捷键：

Ctrl+1..9   切换 process
Ctrl+Up     聚焦上一个 process
Ctrl+Down   聚焦下一个 process
Ctrl+C      复制日志选区；聚焦 sync 时取消当前同步
Esc         关闭 help 或清空输入

TUI 里的 new remote-session 会在远端后台启动命令，并把输出写到远端 .rdev/sessions/<name>/output.log；本地 TUI 只通过 SSH 查看日志。同名远端进程还活着时会直接复用并重新接上日志，不会再启动一份。

enter [name|id] 只对本地 session 发送回车；remote-session 是日志查看面板，停止和重启用 stop / restart。

TUI 日志会同时写入 .rdev/logs/tui/。需要筛选大量日志时，直接用熟悉的命令查文件：

rg "error|panic" .rdev/logs/tui
bat .rdev/logs/tui/session-web.log

服务

service 适合给编程代理启动远端开发服务：本地命令等待 ready，ready 后退出 0，远端服务继续运行。

rdev service set backend --dir backend --ready "listening on" --url http://10.124.124.0:5150 -- cargo run
rdev service start backend
rdev service status backend
rdev service logs backend
rdev service stop backend

默认 start / wait 只输出低频心跳和 ready summary，不回放完整日志。需要实时看启动日志时加 --logs：

rdev service start --logs backend
rdev service wait --logs backend

ready 后会提示：

logs_command=rdev service logs backend
status_command=rdev service status backend
stop_command=rdev service stop backend

ready 超时返回 124，但不会停止远端服务。可以继续用 wait/status/logs/stop 处理。

同步后端

• backend = "auto"：默认推荐。全量同步走 russh + tar，增量同步走 russh-sftp。
• backend = "ssh"：显式使用内部 SSH 同步后端，行为与当前 auto 相同。
• backend = "rsync"：兼容旧配置。只有显式配置该后端时，doctor 才会检查本地和远端 rsync。

每次成功同步后，rdev 会在本地 .rdev/state/sync.json 记录同步状态。rdev status 会显示上次成功同步时间、本地同步根目录、远端目录，以及同步后又发生变化的文件数量。

TUI 的内置 SFTP 连接会缓存 russh 连接。连接失效时会清掉旧连接、重连一次并重试当前同步；如果重连仍失败，下一次手动 sync 会重新建连接。

监听模式下，如果一次待同步列表超过 full_sync_threshold，会直接改跑全量同步，避免大量文件逐个排队上传。设置为 0 可关闭这个自动切换。

排障

rdev doctor
rdev auth-check
rdev port 5150
rdev port 5150 --kill
rdev why-ignore path\to\file
rdev daemon status

port 默认只检查远端监听进程，不会杀进程。只有加 --kill 才会终止占用该端口的进程组。

why-ignore 会说明路径是 ignored 还是 included，以及命中了哪条 exclude/include 规则。

要求

本机：

• Rust toolchain
• 可用的 SSH 私钥，默认查找 ~/.ssh/id_ed25519 / ~/.ssh/id_rsa
• 如需指定私钥，在 .rdev/config.toml 的 [remote] 配置 identity_file

远端：

• SSH server
• sh
• tar
• 项目需要的语言工具链，例如 Rust、Node.js、pnpm 等

当前边界

• 只做本地到远端的 push 同步。
• 不支持双向同步。
• 不做完整交互式远程终端嵌入。
• 暂不提供远端 agent 服务。