功能指南
SSH 远程开发
把远程服务器上的项目当本地项目用
Yoda 可以通过 SSH 挂载远程服务器上的项目，体验与本地对等：worktree、PTY 终端、agent 执行、diff 审查均可用。
SSH 远程开发处于早期阶段，部分特性尚未经过充分测试。遇到问题请到 GitHub Issues 反馈。
添加远程项目
- 新建项目时选择 SSH 来源
- 填写主机、端口、用户名
- 选择认证方式：
- SSH Agent（推荐）—— 使用本机 ssh-agent 中的密钥
- 私钥文件 —— 指定密钥路径
- 密码 —— 直接输入
凭据存储在操作系统钥匙串中（macOS Keychain / Windows Credential Manager），不会写进 Yoda 的数据库。
远程 worktree
远程任务的 worktree 创建在远程项目目录下：
<project>/.yoda/worktrees/<task-slug>/.yoda.json 的 preservePatterns、scripts.setup 等机制同样生效——记得把它提交到仓库里，远程 worktree 才能自动准备好环境。
前提条件
- 远程主机可以 SSH 登录，且装有 git
- 要在远程跑 agent，Runtime CLI 必须装在远程主机上并完成认证（Yoda 在远程 PTY 中启动它）
排查
| 症状 | 排查方向 |
|---|---|
| 连接失败 | 先用终端 ssh user@host 验证连通性与 host key |
| 认证失败 | ssh-agent 是否有密钥（ssh-add -l）；密钥权限是否 600 |
| agent 检测不到 | 远程 shell 的 PATH 是否包含 CLI；非交互式 shell 不加载 .bashrc 的问题 |
| worktree 创建失败 | 远程项目目录的写权限；git 版本是否过旧 |