All your AI agent sessions in one place — browse, search, resume. Rust + GPUI.
Rust
//! 远程 host 的会话聚合(SSH,2026-09-01 阶段 1)。
//!
//! 形态:**同步到本地缓存,而不是远程直读**——`rsync` 把远程 home 下的会话
//! 数据树按白名单镜像到 `<索引库目录>/remotes/<host>/`,缓存树保持远程 home
//! 的相对布局,由 `adapters::remote::RemoteAdapter`(装饰器)以各家
//! `with_custom_root` 挂进 roster。adapter/解析器/FTS 对远程零感知。
//!
//! shell out 到系统 `ssh`/`rsync` 而不用 SSH 库:`~/.ssh/config` 的别名、
//! ProxyJump、IdentityAgent、ControlMaster 全部免费继承。`BatchMode=yes`
//! 确保 GUI 进程(无 TTY)绝不挂在交互认证上——密钥要么已在 agent 里,
//! 要么明确失败并把 stderr 记进 `remote_hosts.last_sync_error`。
//!
//! 一次同步 = **先探测再镜像**:`ssh host sh -c '…'` 逐个 `[ -e ]` 白名单
//! 路径,只把远端真实存在的交给 `rsync -R --delete`,远端整个不存在的在
//! 缓存里就地删掉。不能把整张白名单直接喂 rsync(2026-09-02 本机实测):
//! ①openrsync(macOS 15+ 的 /usr/bin/rsync)做发送端时,某个源连父目录
//! 都不存在会让它中止整份文件列表,排在后面的源全部静默不传,退出码却
//! 只是 23;②rsync 家族只要发送端遇到任何 I/O 错误(缺源即算)就整体跳过
//! 删除阶段——没有哪台机器各家全装,`--delete` 就永远不会生效。
//!
//! 同步跑在**独立于扫描的线程**(Workbench::spawn_remote_sync):本地扫描
//! 不等网络,不可达 host 只拖慢自己;缓存落盘由 watcher 增量收编,同步
//! 完成事件再补一轮增量兜底。
//!
//! 白名单只含**会话数据与其侧档**,绝不同步凭证(`.claude` 顶层、
//! `.codex/auth.json`、`.gemini/oauth_creds.json`、opencode 的 auth.json
//! 都不在名单上)。新增 adapter 必须在 `REMOTE_LAYOUTS` 补一行,契约测试
//! 卡全家覆盖。
use crate::db::Store;
use crate::models::AgentId;
use crate::services::terminal::sh_quote;
use std::path::{Path, PathBuf};
/// 一家 agent 在远程 home 下的数据布局。
pub struct RemoteAgentLayout {
pub agent: AgentId,
/// 缓存树内交给 `with_custom_root` 的目录(相对缓存根 = 相对远程 home)。
/// 必须选"整形判据在目录**不存在**时也落到正确形态"的那一层——同步是
/// 异步的,实例构造时缓存树可能还没落盘(各家判据见其 with_custom_root)
pub mount: &'static str,
/// rsync 白名单源(相对远程 home 的 POSIX 路径;目录整树,文件单拉)。
/// SQLite 库连 `-wal` 一起拉(数据在 wal 里),`-shm` 是运行时产物不拉
///(缺了 sqlite_ro 的 copy 梯度兜底)。字符集限 `[A-Za-z0-9._/-]`——
/// 它们不加引号直接进探测脚本(sh -c 单引号串内)与 rsync 源参数(单测卡)
pub sync_paths: &'static [&'static str],
/// rsync `--exclude` 模式(按文件名匹配,作用于整次同步)。凭证与本家不读的
/// 大索引写在自己这一行——不放全局列表,新增带凭证的 agent 在这里声明
pub exclude: &'static [&'static str],
}
/// 同步的各家的远程布局。远程主机按 Linux/macOS 默认路径假设(两平台一致,
/// 均为 home 相对;OpenCode 的 XDG 变体、CODEX_HOME 这类 env 覆盖在远端
/// 探测不到,阶段 1 不支持非默认远程布局)。
pub const REMOTE_LAYOUTS: &[RemoteAgentLayout] = &[
RemoteAgentLayout {
agent: AgentId::ClaudeCode,
mount: ".claude/projects",
sync_paths: &[".claude/projects"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Codex,
// home 形态:sessions/archived_sessions/state_5.sqlite 全相对派生
mount: ".codex",
sync_paths: &[
".codex/sessions",
".codex/archived_sessions",
".codex/state_5.sqlite",
".codex/state_5.sqlite-wal",
// 记忆:用户级 Markdown 与逐线程的整合库(list_memories 读);全局指令
// AGENTS.md 与 rules/*.rules 同属 home 直属、不是凭证
".codex/memories",
".codex/memories_1.sqlite",
".codex/memories_1.sqlite-wal",
".codex/AGENTS.md",
".codex/rules",
],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Qoder,
mount: ".qoder/projects",
sync_paths: &[".qoder/projects"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Copilot,
// 目录层:db = <mount>/session-store.db(is_file 判据对未同步目录失真)
mount: ".copilot",
sync_paths: &[".copilot/session-store.db", ".copilot/session-store.db-wal"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Cursor,
// 只覆盖 CLI 源。Cursor 还有一个 IDE 源(adapters/cursor_ide.rs,
// `globalStorage/state.vscdb`),**不在远程同步范围内**:本表每个
// AgentId 一行、create_remote_adapters 按 agent 取首个模板,同家第二
// 个源拿不到自己的行;且该库路径含空格,过不了下方
// `sync_paths_are_shell_safe`(路径不加引号直接进 sh -c 与 rsync)。
// 要补齐得先给同步管线加引用机制,是独立改动(2026-09-14 review)
mount: ".cursor/projects",
sync_paths: &[".cursor/projects"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Opencode,
// custom_db_paths 对目录给出 stable + next 两个固定候选
mount: ".local/share/opencode",
sync_paths: &[
".local/share/opencode/opencode.db",
".local/share/opencode/opencode.db-wal",
".local/share/opencode/opencode-next.db",
".local/share/opencode/opencode-next.db-wal",
],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Kiro,
mount: ".kiro/sessions/cli",
sync_paths: &[".kiro/sessions/cli"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Gemini,
// tmp 层:projects.json 由 parent 派生(.gemini 顶层有凭证,不整树同步)
mount: ".gemini/tmp",
sync_paths: &[".gemini/tmp", ".gemini/projects.json"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Pi,
mount: ".pi/agent/sessions",
sync_paths: &[".pi/agent/sessions"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Omp,
mount: ".omp/agent/sessions",
sync_paths: &[".omp/agent/sessions"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Grok,
// sessions 目录名判据 → home=parent,summary/chat_history 都在树内
mount: ".grok/sessions",
sync_paths: &[".grok/sessions"],
// Grok 自家的搜索索引库,量大且 Wake 不读
exclude: &["session_search.sqlite*"],
},
RemoteAgentLayout {
agent: AgentId::Kimi,
mount: ".kimi-code/sessions",
sync_paths: &[".kimi-code/sessions", ".kimi-code/session_index.jsonl"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Antigravity,
// `.gemini` 层:with_custom_root 按目录名认出整套布局(会话索引 + 三个 app 数据
// 目录下的 brain 转录),未同步时目录还不存在也不失真。brain 只拉会话目录,
// 浏览器子代理的临时录屏不拉;凭证(oauth_creds.json 等)不在白名单里
mount: ".gemini",
sync_paths: &[
".gemini/antigravity-cli/conversation_summaries.db",
".gemini/antigravity-cli/conversation_summaries.db-wal",
".gemini/antigravity/brain",
".gemini/antigravity-ide/brain",
".gemini/antigravity-cli/brain",
],
exclude: &["brain/tempmediaStorage"],
},
RemoteAgentLayout {
agent: AgentId::Dsh,
mount: ".dsh/sessions",
sync_paths: &[".dsh/sessions"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Hermes,
// 库所在目录层:db = <mount>/state.db(profiles 多档案不同步)
mount: ".hermes",
sync_paths: &[".hermes/state.db", ".hermes/state.db-wal"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Openclaw,
// agents/<id>/ 整树,exclude 挡掉每个 agent 目录里的凭证:auth-profiles.json
// 与 openclaw-agent.sqlite(库内 auth_profile_store 表存着 API key/OAuth
// token,会话与凭证同库,只能整库不拉)——远程 OpenClaw 因此只覆盖旧版
// sessions/*.jsonl 转录
mount: ".openclaw/agents",
sync_paths: &[".openclaw/agents"],
exclude: &["auth-profiles.json", "openclaw-agent.sqlite*"],
},
RemoteAgentLayout {
agent: AgentId::Codebuddy,
mount: ".codebuddy/projects",
sync_paths: &[".codebuddy/projects"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Workbuddy,
mount: ".workbuddy/projects",
sync_paths: &[".workbuddy/projects"],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Zcode,
// home 形态:cli/db/db.sqlite、v2/tasks-index.sqlite 与 cli/memories 全相对
// 派生。只拉两个库文件 + 记忆目录(里面只有 Markdown)——凭证
// (v2/credentials.json)与网络 CA 私钥(v2/certs/)不在白名单里就不会被碰
mount: ".zcode",
sync_paths: &[
".zcode/cli/db/db.sqlite",
".zcode/cli/db/db.sqlite-wal",
".zcode/v2/tasks-index.sqlite",
".zcode/v2/tasks-index.sqlite-wal",
".zcode/cli/memories",
],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::CraftAgents,
// 工作区集合层(远端建在默认位置之外的工作区同步不到)。只要每个会话的
// session.jsonl 与 meta/ 里的回合锚点:工作区的 sources/ 是源配置(可能带 OAuth
// client secret;凭证本体 credentials.enc 在 home 直属、不在白名单里),
// automations.json 可能带 webhook 头;会话目录里的附件 / 下载 / 数据 / 长回复 /
// 计划 / 缩小过的图片(tmp)/ 源服务存下的大响应(responses)与引擎原料
// (.pi-sessions、.pi-agent——Pi 的 agentDir 默认放 auth.json)量大且不读。模式带
// 层级:不带 `/` 的 rsync 模式按文件名全树匹配,`data` / `sources` 这种泛名会把
// 同名的工作区整个漏掉(默认位置下叫 "Data" 的工作区目录就是 data/)
mount: ".craft-agent/workspaces",
sync_paths: &[".craft-agent/workspaces"],
exclude: &[
"workspaces/*/sources",
"workspaces/*/skills",
"workspaces/*/automations.json",
"workspaces/*/events.jsonl",
"workspaces/*/sessions/*/attachments",
"workspaces/*/sessions/*/downloads",
"workspaces/*/sessions/*/data",
"workspaces/*/sessions/*/long_responses",
"workspaces/*/sessions/*/plans",
"workspaces/*/sessions/*/tmp",
"workspaces/*/sessions/*/responses",
"workspaces/*/sessions/*/.pi-sessions",
"workspaces/*/sessions/*/.pi-agent",
"session.jsonl.tmp",
],
},
RemoteAgentLayout {
agent: AgentId::Devin,
// `cli/sessions.db` 是会话与正文的唯一来源(转录也在库里,transcripts/
// 是导出副本不拉);凭证在 ~/.config/devin 下、不在数据根里,
// session_locks/_versions/logs 不进白名单
mount: ".local/share/devin",
sync_paths: &[
".local/share/devin/cli/sessions.db",
".local/share/devin/cli/sessions.db-wal",
],
exclude: &[],
},
RemoteAgentLayout {
agent: AgentId::Kilo,
// **只覆盖旧版扩展**:Remote-SSH 下扩展跑在远端,任务目录落在远端的
// vscode-server 用户数据里。新版的 `.local/share/kilo/kilo.db` 不拉——Kilo 每次
// 启动都把 auth.json 里的 API key / 登录 token 对账进同一个库的 credential 表,
// 还有存 access / refresh token 的 account 表;SQLite 是整文件,拉会话就得连凭证
// 一起拷到本机(OpenClaw 的库同样因此不拉)。globalStorage 的 state.vscdb
// 也不拉(里面有加密的 secret:// 项),缺 history_item.json 的老任务改从正文推
// 标题与工作区。挂载点按目录名(扩展 id)定形,不看存在性
mount: ".vscode-server/data/User/globalStorage/kilocode.kilo-code",
sync_paths: &[".vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks"],
// 每个任务目录里的 checkpoints/ 是整份影子 git 仓库,量大且不读
exclude: &["kilocode.kilo-code/tasks/*/checkpoints"],
},
];
/// 有意不做远程同步的家:不进 REMOTE_LAYOUTS,也就没有远程实例。覆盖测试要求每家在两张表里
/// 恰好出现一次——新加的家漏写白名单在测试里爆,而不是静默不同步
pub const NOT_SYNCED: &[AgentId] = &[
// 本机那份是云端对话的缓存:另一台机器上的 app 缓存着同一批对话,同步过来同一个对话会按 host
// 各列一遍(副本去重的域含 host)。缓存目录名带空格是次要的,白名单补上引号也不该同步
AgentId::GrokBot,
// 会话只在 mimocode.db 里,同一个库还有存 access / refresh token 的 account 表;SQLite 是
// 整文件,拉会话就得连凭证一起拷到本机(Kilo 新版的 kilo.db 与 OpenClaw 的库同样因此不拉)
AgentId::MimoCode,
];
/// host 名合法性:进 session key 作中段(不能有 ':')、直接作为 ssh/rsync
/// 目标(不能以 '-' 开头——那会被当作命令行选项,是参数注入面)。允许
/// `user@host`、别名、IPv4;IPv6 字面量请在 `~/.ssh/config` 里包一个别名。
pub fn valid_host_name(name: &str) -> bool {
name.starts_with(|c: char| c.is_ascii_alphanumeric())
&& name
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-' | '@'))
}
/// 删掉 `remotes/` 下不再对应任何已配置 host 的缓存目录。同步进行中被
/// Remove 的 host,其 rsync 无法取消、会把刚删的目录写回——每轮同步收工
/// 后按配置表裁决一次,幂等自愈(该目录树只有 Wake 自己写)。
pub fn purge_orphan_caches(store: &Store) {
let Some(db_dir) = store.db_dir() else { return };
let known: std::collections::HashSet<String> = store
.list_remote_hosts()
.unwrap_or_default()
.into_iter()
.map(|h| h.name)
.collect();
let Ok(entries) = std::fs::read_dir(remotes_dir(&db_dir)) else {
return;
};
for entry in entries.flatten() {
let name = entry.file_name();
if name.to_str().is_none_or(|n| !known.contains(n)) {
let _ = std::fs::remove_dir_all(entry.path());
}
}
}
/// 全部镜像的根:`<索引库目录>/remotes/`
fn remotes_dir(db_dir: &Path) -> PathBuf {
db_dir.join("remotes")
}
/// 单 host 的缓存树(各 host 挂在 `<索引库目录>/remotes/<host>/` 下)。
pub fn host_cache_dir(db_dir: &Path, host: &str) -> PathBuf {
remotes_dir(db_dir).join(host)
}
/// 全部镜像(`<db 目录>/remotes/`)的磁盘占用。Settings → Data 的 Storage 行把它
/// 并进索引库的大小——"Wake 在这台机器上占了多少盘"得含镜像(0.4.0 遗留)。
/// 逐文件 stat,几千个文件也是毫秒级;调用方别放进每帧的 render,目录不存在即 0
pub fn cache_bytes(db_dir: &Path) -> u64 {
walkdir::WalkDir::new(remotes_dir(db_dir))
.into_iter()
.filter_map(Result::ok)
.filter(|e| e.file_type().is_file())
.filter_map(|e| e.metadata().ok())
.map(|m| m.len())
.sum()
}
/// ssh 的批处理选项:探测与 rsync 的 `-e` 同一份——认证/超时行为两步一致,
/// 探测过了 rsync 就不会再卡在认证上
const SSH_OPTS: [&str; 2] = ["-oBatchMode=yes", "-oConnectTimeout=10"];
/// 白名单全部 sync_paths,按 REMOTE_LAYOUTS 顺序(探测脚本、rsync 源列表、
/// 缺席清理三处同序)
fn all_sync_paths() -> impl Iterator<Item = &'static str> {
REMOTE_LAYOUTS
.iter()
.flat_map(|layout| layout.sync_paths.iter().copied())
}
/// 远端存在性探测的 ssh 参数(不含程序名)。远端命令是一整条
/// `sh -c '…'`:ssh 把它交给登录 shell 再解析,单引号串在 fish/csh 里同样
/// 原样传给 sh,循环语法不依赖登录 shell 方言(quote 走 terminal::sh_quote,
/// 与本地/远程 resume 命令同一实现)。存在的路径按行回显;循环体用 if 而非
/// `&&`,末项缺席不会把命令退出码带成非零——非零退出只表示 ssh 本身失败
///(认证/不可达/远端无 sh)。
fn probe_args(host: &str) -> Vec<String> {
let list = all_sync_paths().collect::<Vec<_>>().join(" ");
let script =
format!("for p in {list}; do if [ -e \"$p\" ]; then printf \"%s\\n\" \"$p\"; fi; done");
SSH_OPTS
.iter()
.map(|s| s.to_string())
.chain([host.to_string(), format!("sh -c {}", sh_quote(&script))])
.collect()
}
/// 探测输出 → 白名单顺序的存在路径。只认与白名单**逐字相等**的行:远端
/// rc 文件的 echo、MOTD、警告之类都不能变成 rsync 的源参数。
fn present_remote_paths(stdout: &str) -> Vec<&'static str> {
let lines: std::collections::HashSet<&str> = stdout.lines().map(str::trim).collect();
all_sync_paths().filter(|p| lines.contains(p)).collect()
}
/// 单 host 的 rsync 参数(不含程序名),`paths` 是探测确认存在的源。纯函数,
/// 单测卡命令形状。`-R`(--relative)让 `host:./<相对路径>` 在目标重建相对
/// 布局;`--delete` 让远程删除传播到缓存(watcher 收 Remove 后清库内行)——
/// 它只作用于各源树**内部**,整棵源消失由 sync_host 的缺席清理负责。
fn rsync_args(host: &str, paths: &[&str]) -> Vec<String> {
// -a enables special files. Override it afterwards: sockets/FIFOs carry no
// session data, and recreating sockets under a long cache path can exceed
// sun_path and abort openrsync's receiver (#47).
let mut args = vec![
"-az".to_string(),
"-R".to_string(),
"--delete".to_string(),
"--no-specials".to_string(),
];
args.extend(
REMOTE_LAYOUTS
.iter()
.flat_map(|l| l.exclude.iter())
.map(|pat| format!("--exclude={pat}")),
);
args.extend([
"--timeout=120".to_string(),
"-e".to_string(),
format!("ssh {}", SSH_OPTS.join(" ")),
]);
args.extend(paths.iter().map(|path| format!("{host}:./{path}")));
// 目标由子进程的 cwd 指定。Windows 的 C:\... / C:/... 会被 rsync
// 当作 host:path,与远端源一起触发 "both be remote" (#56)。
args.push(".".to_string());
args
}
/// 同步指定 host(调用方给"全部启用的"或单个新加的)。**绝不 panic、绝不
/// Err**——任何失败只记进 `remote_hosts.last_sync_error`,面板展示,后续
/// 扫描照常消费既有缓存。各 host 的同步彼此独立(纯网络等待),并行跑,
/// 总耗时 = 最慢一台而非各台之和;状态写库经 write Mutex 天然串行。
pub fn sync_hosts(store: &Store, names: &[String]) {
let Some(db_dir) = store.db_dir() else {
return;
};
std::thread::scope(|scope| {
for name in names {
let dest = host_cache_dir(&db_dir, name);
scope.spawn(move || {
// 已入库的 host 也再卡一道:老库可能被未来版本写入过更宽的名字
let error = if valid_host_name(name) {
sync_host(name, &dest).err()
} else {
Some("invalid host name".to_string())
};
let _ = store.record_remote_sync(name, error.as_deref());
});
}
});
}
/// 单 host 的一次同步:探测 → 缺席清理 → rsync。探测失败即整体失败,缓存
/// 一字不动(不能把"连不上"当成"远端空了"去清缓存)。探测到 rsync 之间隔着
/// 一次握手,远端 agent 恰好在这个空档退出会把 `-wal` 之类删掉,rsync 对
/// 命令行源 link_stat 失败报 23 且整轮跳过 --delete——只含 ENOENT 的 23
/// 重探一轮再镜像(第二轮拿到的源集合已经是消失后的),第二轮结果照实报。
fn sync_host(host: &str, dest: &Path) -> Result<(), String> {
if let Err(e) = std::fs::create_dir_all(dest) {
return Err(format!("cannot create cache dir {}: {e}", dest.display()));
}
let mut retried = false;
loop {
let present = probe_remote(host)?;
// 远端整个不存在的白名单项(该家卸了、库被清了):镜像也删。rsync 的
// --delete 只作用于它拿到的源树内部,整棵源消失只有这里能传播
for path in all_sync_paths() {
if !present.contains(&path) {
remove_cached(&dest.join(path))?;
}
}
if present.is_empty() {
return Ok(());
}
match run_rsync(host, dest, &present) {
Ok(()) => return Ok(()),
Err(RsyncError::SourcesVanished(_)) if !retried => retried = true,
Err(RsyncError::SourcesVanished(msg) | RsyncError::Other(msg)) => return Err(msg),
}
}
}
/// 删缓存里的一个白名单项(目录整树 / 单文件),不存在即无事;删不掉(权限、
/// 锁着的库文件、瞬时 I/O 错误)要当同步失败上报——否则远端已删的会话留在
/// 缓存和索引里,面板却显示同步成功
fn remove_cached(path: &Path) -> Result<(), String> {
let not_found = |e: &std::io::Error| e.kind() == std::io::ErrorKind::NotFound;
let meta = match std::fs::symlink_metadata(path) {
Ok(m) => m,
Err(e) if not_found(&e) => return Ok(()),
Err(e) => {
return Err(format!(
"cannot inspect stale cache {}: {e}",
path.display()
))
}
};
let removed = if meta.is_dir() {
std::fs::remove_dir_all(path)
} else {
std::fs::remove_file(path)
};
match removed {
Ok(()) => Ok(()),
Err(e) if not_found(&e) => Ok(()),
Err(e) => Err(format!("cannot remove stale cache {}: {e}", path.display())),
}
}
/// 起 ssh 探测。ssh 非零退出(255 = 连接/认证失败)整体报错,stderr 末几行
/// 是用户能看懂的原话("Permission denied (publickey)"、"Host key
/// verification failed")
fn probe_remote(host: &str) -> Result<Vec<&'static str>, String> {
let output = run_tool("ssh", "OpenSSH", &probe_args(host), None)?;
classify("ssh", &output, &[])?;
Ok(present_remote_paths(&String::from_utf8_lossy(
&output.stdout,
)))
}
enum RsyncError {
/// 只含 ENOENT 的 exit 23:探测过的源在传输前消失(附 rsync 原话,
/// 调用方重探失败时照实报)
SourcesVanished(String),
Other(String),
}
/// 起 rsync。源已经过探测,缺源不再是常态:0 = 全量成功;24(传输中源文件
/// 消失,agent 正在写,下轮自愈)算软成功;23 是"部分传输失败"泛码——错误
/// 行全是 ENOENT 时是探测后消失的源,交调用方重探,权限/读错误同样报 23,
/// 照常报错(记成功会隐藏真实缺数据)。
fn run_rsync(host: &str, dest: &Path, paths: &[&str]) -> Result<(), RsyncError> {
let output = run_tool("rsync", "rsync", &rsync_args(host, paths), Some(dest))
.map_err(RsyncError::Other)?;
if output.status.code() == Some(23) && only_missing_sources(&output.stderr) {
return Err(RsyncError::SourcesVanished(exit_error("rsync", &output)));
}
classify("rsync", &output, &[24]).map_err(RsyncError::Other)
}
/// rsync 的错误行是否**全部**是"源不存在"。GNU rsync 报
/// `rsync: [sender] link_stat "…" failed: No such file or directory (2)`,
/// openrsync 报 `rsync(pid): error: …: (l)stat: No such file or directory`;
/// 总结行(some files/attrs were not transferred)不算错误行;一行错误都
/// 没有的 23 不认(形状未知,当真错误报)
fn only_missing_sources(stderr: &[u8]) -> bool {
let stderr = String::from_utf8_lossy(stderr);
let mut errors = stderr
.lines()
.filter(|l| l.contains("rsync") && (l.contains("error") || l.contains("failed")))
.filter(|l| !l.contains("some files/attrs were not transferred"))
.peekable();
errors.peek().is_some() && errors.all(|l| l.contains("No such file or directory"))
}
/// 起一个外部工具:程序不在 PATH → 安装提示,起不来 → 原因;退出码不在这里
/// 裁决(见 classify),调用方还要看原始 stderr
fn run_tool(
bin: &str,
install_hint: &str,
args: &[String],
working_dir: Option<&Path>,
) -> Result<std::process::Output, String> {
let mut command = std::process::Command::new(bin);
command.args(args).stdin(std::process::Stdio::null());
if let Some(dir) = working_dir {
// 每个 host 并行同步,只能设置子进程 cwd,不能改整个 Wake 进程的 cwd。
command.current_dir(dir);
}
let output = command.output();
match output {
Ok(o) => Ok(o),
// Remove host 可能同时删掉缓存目录;这种启动失败不是缺少 rsync。
Err(e)
if e.kind() == std::io::ErrorKind::NotFound && working_dir.is_none_or(Path::is_dir) =>
{
Err(format!(
"{bin} not found on PATH — install {install_hint} to sync remote hosts"
))
}
Err(e) => Err(format!("failed to run {bin}: {e}")),
}
}
/// 退出码归类:{0} ∪ `soft_ok` 通过,其余给 exit_error
fn classify(bin: &str, output: &std::process::Output, soft_ok: &[i32]) -> Result<(), String> {
match output.status.code() {
Some(0) => Ok(()),
Some(c) if soft_ok.contains(&c) => Ok(()),
_ => Err(exit_error(bin, output)),
}
}
/// `<bin> exited with N: <stderr 末几行>`——ssh/rsync 都把决定性错误留在
/// 最后,字符封顶防单行巨量输出
fn exit_error(bin: &str, output: &std::process::Output) -> String {
let stderr = String::from_utf8_lossy(&output.stderr);
let mut lines: Vec<&str> = stderr.trim().lines().rev().take(3).collect();
lines.reverse();
let tail: String = lines.join("; ").chars().take(500).collect();
match output.status.code() {
Some(c) => format!("{bin} exited with {c}: {tail}"),
None => format!("{bin} terminated by signal: {tail}"),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn only_missing_sources_recognizes_both_rsync_dialects() {
// GNU rsync(Linux 远端做发送端,经本地客户端转出)
let gnu = b"rsync: [sender] link_stat \"/home/u/.codex/state_5.sqlite-wal\" failed: No such file or directory (2)\n\
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1338)\n";
assert!(only_missing_sources(gnu));
// openrsync(macOS 远端做发送端)
let openrsync =
b"rsync(63771): error: .codex/state_5.sqlite-wal: (l)stat: No such file or directory\n";
assert!(only_missing_sources(openrsync));
// 混进一条权限错误就不算"只是消失"
let mixed = b"rsync: [sender] link_stat \"/x\" failed: No such file or directory (2)\n\
rsync: [sender] send_files failed to open \"/y\": Permission denied (13)\n";
assert!(!only_missing_sources(mixed));
// 一行错误都没有的 23:形状未知,不认
assert!(!only_missing_sources(b""));
assert!(!only_missing_sources(
b"rsync error: some files/attrs were not transferred (code 23)\n"
));
}
#[test]
fn remove_cached_reports_failures_but_not_absence() {
let dir = tempfile::tempdir().unwrap();
// 不存在:无事
assert_eq!(remove_cached(&dir.path().join("nope")), Ok(()));
// 文件与目录都删得掉
let file = dir.path().join("f");
std::fs::write(&file, b"x").unwrap();
assert_eq!(remove_cached(&file), Ok(()));
assert!(!file.exists());
let sub = dir.path().join("d/e");
std::fs::create_dir_all(&sub).unwrap();
assert_eq!(remove_cached(&dir.path().join("d")), Ok(()));
assert!(!sub.exists());
// 路径穿过一个普通文件(ENOTDIR):不是"不存在",必须报错。Windows 对
// 这种路径报 ERROR_PATH_NOT_FOUND → NotFound,函数按约定当作缺席返回
// Ok,断言只在 POSIX 上成立(CI windows-2022 自 v0.4.0 起因此红)
#[cfg(not(windows))]
{
std::fs::write(&file, b"x").unwrap();
let err = remove_cached(&file.join("child")).unwrap_err();
assert!(err.contains("cannot inspect stale cache"), "{err}");
}
}
#[test]
fn layouts_cover_every_agent_exactly_once() {
// 新增 agent 忘了补远程布局表,这里就是第一道报警
let mut seen = std::collections::HashSet::new();
for layout in REMOTE_LAYOUTS {
assert!(
seen.insert(layout.agent),
"duplicate layout {:?}",
layout.agent
);
assert!(!layout.sync_paths.is_empty());
for path in layout.sync_paths {
assert!(!path.starts_with('/'), "sync path must be home-relative");
assert!(!path.contains(".."));
}
assert!(!layout.mount.starts_with('/'));
}
for agent in NOT_SYNCED {
assert!(
seen.insert(*agent),
"{agent:?} is both synced and not synced"
);
}
for agent in AgentId::ALL {
assert!(seen.contains(&agent), "missing remote layout for {agent:?}");
}
}
#[test]
fn host_name_validation_blocks_injection() {
assert!(valid_host_name("devbox"));
assert!(valid_host_name("[email protected]"));
assert!(valid_host_name("my-host.example.com"));
assert!(valid_host_name("a"));
// 选项注入与 key 分隔符
assert!(!valid_host_name("-oProxyCommand=evil"));
assert!(!valid_host_name(""));
assert!(!valid_host_name("host:22"));
assert!(!valid_host_name("host name"));
assert!(!valid_host_name("host/../x"));
assert!(!valid_host_name(".hidden"));
}
#[test]
fn sync_paths_are_shell_safe() {
// 白名单路径不加引号直接进探测脚本(sh -c 单引号串内)与 rsync 源参数
for path in all_sync_paths() {
assert!(
path.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '/' | '-')),
"sync path {path:?} needs quoting"
);
}
// 凭证绝不在名单上
assert!(!all_sync_paths().any(|p| p.contains("auth.json") || p.contains("oauth_creds")));
}
#[test]
fn probe_args_shape() {
let args = probe_args("devbox");
assert_eq!(
args[..3].to_vec(),
["-oBatchMode=yes", "-oConnectTimeout=10", "devbox"]
);
// 一整条 sh -c '…':每个白名单路径都在 for 列表里,循环体按行回显存在项
let script = &args[3];
assert!(script.starts_with("sh -c 'for p in "));
for path in all_sync_paths() {
assert!(
script.contains(&format!(" {path} ")) || script.contains(&format!(" {path};")),
"{path} 不在探测列表里"
);
}
assert!(script.ends_with("; do if [ -e \"$p\" ]; then printf \"%s\\n\" \"$p\"; fi; done'"));
}
#[test]
fn present_remote_paths_keeps_only_whitelist_in_layout_order() {
// 乱序、重复、rc 文件的杂音、白名单项的父目录/子路径、绝对路径都要滤掉
let out = "Welcome to devbox\n.grok/sessions\n.codex/sessions\n.codex\n\
.codex/sessions\n .claude/projects \n.claude/projects/evil\n/etc/passwd\n";
assert_eq!(
present_remote_paths(out),
vec![".claude/projects", ".codex/sessions", ".grok/sessions"]
);
assert!(present_remote_paths("").is_empty());
}
#[test]
fn rsync_args_shape() {
let present = [".claude/projects", ".codex/state_5.sqlite"];
let args = rsync_args("devbox", &present);
assert_eq!(args[0], "-az");
let archive = args.iter().position(|a| a == "-az").unwrap();
let no_specials = args.iter().position(|a| a == "--no-specials").unwrap();
assert!(
no_specials > archive,
"--no-specials must follow -a, which enables special files"
);
assert!(args.contains(&"-R".to_string()));
assert!(args.contains(&"--delete".to_string()));
assert!(args
.iter()
.any(|a| a == "ssh -oBatchMode=yes -oConnectTimeout=10"));
// 只有探测确认存在的源,且都是 host:./ 锚定的 home 相对路径
let sources: Vec<&str> = args
.iter()
.filter(|a| a.starts_with("devbox:"))
.map(String::as_str)
.collect();
assert_eq!(
sources,
vec![
"devbox:./.claude/projects",
"devbox:./.codex/state_5.sqlite"
]
);
// 目标在最后
assert_eq!(args.last().unwrap(), ".");
// 各家声明的 exclude 全部落到命令行(OpenClaw 的凭证靠它挡)。`/` 在字符集里:
// exclude 是单独一个 argv 交给本地 rsync、经协议传给发送端,不过任何 shell;
// 带层级的模式(Craft 的 workspaces/*/sources)只匹配那一层,不误伤同名目录
for pat in REMOTE_LAYOUTS.iter().flat_map(|l| l.exclude.iter()) {
assert!(
args.contains(&format!("--exclude={pat}")),
"{pat} 未进 rsync 参数"
);
assert!(
pat.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-' | '*' | '/')),
"exclude {pat:?} needs quoting"
);
assert!(
!pat.starts_with('/'),
"exclude {pat:?} 锚在传输根上,别家的树对不上"
);
}
assert!(args.contains(&"--exclude=openclaw-agent.sqlite*".to_string()));
assert!(args.contains(&"--exclude=workspaces/*/sources".to_string()));
}
}