远程开发目标

将一份检出代码镜像到 Linux、macOS 或 Windows 设备，并通过 yarn dev 或 yarn tui 运行原生开发守护进程。

借助远程开发目标，你可以只用一份本地 Stack 检出，就能驱动其他设备构建原生的 Kaiwu 守护进程。Stack 使用 Mutagen 进行单向源码同步，并在每个目标上复用现有的 Stack 开发生命周期。

这一机制专为维护者设计：只需编辑一份检出，即可将 macOS、Linux 和 Windows 守护进程同时接入同一个开发服务器。

前置要求

在运行 yarn dev 或 yarn tui 的计算机上：

安装 Mutagen，并确保 mutagen 位于 PATH 中；
为每个目标配置免交互 OpenSSH 访问；
启动 TUI 之前，先接受每个目标的 SSH 主机密钥。

在各个目标上：

运行 OpenSSH 服务器；
安装 Node.js 和 Corepack；
预留足够的磁盘空间，用于存放源码镜像、目标本地依赖项以及构建产物。

Stack 不会主动安装或更新宿主机的 SSH 服务器、Node.js、Corepack 或 Mutagen CLI。这些都属于设备层面的前置依赖。项目启动时，Mutagen 会自动通过 SSH 安装自身轻量的同步代理。

在不变更目标状态的前提下进行验证：

hstack dev-targets doctor linux --stack=repo-dev

doctor 会检查本地 Mutagen CLI、免密 SSH 以及远程 Node.js/Corepack 的可用性。省略目标名称时，将检查该栈配置的所有目标。

添加与管理目标

目标配置的作用域限定在栈级别，保存在：

~/.Kaiwu/stacks/<stack>/dev-targets.json

请使用命令行操作，不要直接编辑 JSON 文件：

hstack dev-targets path --stack=repo-dev
hstack dev-targets list --stack=repo-dev
hstack dev-targets show linux --stack=repo-dev

添加 Linux 或 macOS 目标：

hstack dev-targets add linux \
  --stack=repo-dev \
  --platform=posix \
  --ssh=Kaiwu-stack-linux \
  --repo-dir=/home/dev/Kaiwu \
  --cli-home-dir=/home/dev/.Kaiwu/dev-targets/repo-dev-linux

使用正斜杠路径添加 Windows 目标：

hstack dev-targets add windows \
  --stack=repo-dev \
  --platform=windows \
  --ssh=Kaiwu-stack-windows \
  --repo-dir=C:/Users/dev/Kaiwu \
  --cli-home-dir=C:/Users/dev/.Kaiwu/dev-targets/repo-dev-windows

--ssh 可以是普通的 OpenSSH 别名，也可以是 user@host。如果目标使用的是自动生成或隔离的 SSH 配置，请传入其绝对路径：

hstack dev-targets add linux \
  --stack=repo-dev \
  --platform=posix \
  --ssh=lima-Kaiwu \
  --ssh-config-file=/absolute/path/to/lima/ssh.config \
  --lima-instance=Kaiwu-linux \
  --lima-home=/absolute/path/to/lima-home \
  --repo-dir=/home/dev/Kaiwu \
  --cli-home-dir=/home/dev/.Kaiwu/dev-targets/repo-dev-linux

同时指定这两个 Lima 选项时，Stack 会在准备 SSH 前执行 limactl start。TUI 退出时不会停止虚拟机，以便保留目标本地的依赖项与构建缓存。

添加与现有目标同名的目标会覆盖原有配置。若要删除目标，请运行：

hstack dev-targets remove windows --stack=repo-dev

在源码检出目录中，可以使用等效的仓库级快捷命令：

yarn dev-targets list
yarn dev-targets add ...
yarn dev-targets show linux
yarn dev-targets doctor
yarn dev-targets remove linux

仓库本地的包装脚本会自动选择该检出对应的 Stack。

自动启动流程

配置了至少一个目标时，yarn dev 和 yarn tui 会先启动本地服务器、守护进程与 Expo。随后，远程准备流程会在后台独立运行：

校验本地安装的 Mutagen CLI；
创建 Mutagen one-way-replica 项目，并将所有会话置于暂停状态；
分别启动各目标配置的 Lima 实例，并通过 SSH 创建相应目录；
恢复并刷新该目标的 Mutagen 会话；
基于同步过去的 lockfile 安装目标本地依赖项；
将当前 Stack 守护进程的访问密钥复制到目标专用的 CLI 主目录下；
建立 SSH 反向隧道，连接到已在运行的本地 Stack 服务器；
沿用仅守护进程的 hstack dev --watch 生命周期，启动远程检出。

某个目标不可用或响应变慢，既不会拖延 Expo、中止本地 Stack，也不会阻塞其他就绪的目标。失败信息会显示在该目标的窗格中，本地 Stack 和其他目标仍可正常使用。在 Windows 上安装依赖项遇到临时包管理器错误时会自动重试，重试失败后才会将目标标记为失败。

每个远程守护进程都会在各自的操作系统上从源码构建，并获得独立的设备标识。它与本地守护进程连接到同一个 Stack 服务器；Stack 不会复制本地的设备标识或通用设置。

TUI 新增了以下内容：

一个 mutagen sync 窗格，用于显示同步输出与状态；
每个目标各有一个 remote ⟦K11⟧ 窗格，用于显示依赖项、构建、守护进程和重连的输出。

停止 TUI 会终止其远程工作进程并销毁生成的 Mutagen 项目。目标本地的依赖项和构建缓存均会保留，供下次运行使用。

若只想运行本地 Stack：

yarn dev --no-dev-targets
yarn tui --no-dev-targets

同步策略

一切以本地检出为准。请勿直接编辑远程镜像：Mutagen 可能会覆盖目标上的修改。

Stack 会排除版本控制元数据及目标本地产物，例如 .git、node_modules、dist、.project、.Kaiwu、覆盖率输出、Rust 目标文件、CocoaPods 以及已知的审查/构建产物。依赖项与构建产物均由各个操作系统独立生成。

初次同步与依赖项安装可能需要一些时间。启动完成后，源码变动将以增量方式同步，每个远程守护进程都会监听并构建各自的目标本地镜像。

平台说明

Lima

配合 --ssh-config-file 使用 Lima 生成的 SSH 配置。如果需要 Stack 自动启动该实例，请添加 --lima-instance 和 --lima-home。虚拟机内仍须安装 Node.js 和 Corepack；hstack dev-targets doctor 会在完整 TUI 启动前对其进行验证。

Windows

请使用 Windows OpenSSH 服务器，并在目标路径中使用正斜杠。Stack 发送的是编码后的 PowerShell 命令，因此路径中可以包含空格。

对于管理员账户，Windows OpenSSH 可能会读取 C:\ProgramData\ssh\administrators_authorized_keys，而不是用户的 .ssh\authorized_keys。请务必确认所配置的别名可以免交互运行：

ssh -o BatchMode=yes Kaiwu-stack-windows "echo ok"

Mutagen 官方文档指出，与 Windows OpenSSH 服务器配合使用时，数据流可能会变慢或卡顿。在将其用于无人值守的 QA 之前，请先用 doctor 验证真实目标，并完整跑通一次 yarn tui 同步。

故障排查

找不到 Mutagen： 在本地安装 Mutagen，并确认 mutagen version 能正常运行。
SSH 认证失败： 确保所配置的别名可以通过 BatchMode=yes 正常连接；TUI 无法响应密码或主机密钥提示。
Node.js/Corepack 检查失败： 在目标上安装它们，然后重新运行 doctor。
某个目标今天不想启动： 使用 --no-dev-targets，或直接从该栈的配置中将其移除。
同步诊断： 查看 mutagen sync TUI 窗格，并直接使用标准的 mutagen 命令行。Stack 特意将 Mutagen 的控制权留给用户。

On this page