Remote Build
面向 AI agent 的远程编译插件：本机（Windows）通过 OpenSSH（ssh.exe）驱动远程 Linux 服务器执行构建命令，为 AI agent 提供可自动化触发、可判断成败的远程执行能力，不绑定特定平台或工具链。
能力一览
| 能力 |
入口 |
面向对象 |
| 服务器参数设置 |
侧边栏（Activity Bar） |
人 |
| 远程交互式命令行 |
终端 Profile |
人 |
| 自动化触发与分析 |
CLI |
AI agent |
三个入口共用同一套配置解析规则。
配置
配置跟着工程目录走：每个工程在自己的根目录下放一份 .vscode/remote-build.json，打开哪个工程就用哪份，切工程不用改配置。
{
"host": "192.168.55.100[my build server]",
"sshPath": "",
"init": "source ~/.bashrc",
"cwd": "/home/ubuntu/sdk",
"cmds": [
"cmake --build ... --target proj1 -j",
"cmake --build ... --target proj2 -j"
]
}
| 字段 |
说明 |
host |
SSH 别名（~/.ssh/config）或主机名，必填 |
sshPath |
ssh.exe 路径；留空自动探测（Windows 默认 C:\Windows\System32\OpenSSH\ssh.exe） |
init |
远程命令前 source 的片段，如 source ~/.bashrc 加载工具链环境 |
cwd |
服务器工程目录（对应 --cwd），所有命令共用 |
cmds |
有序的编译命令列表，build 时按顺序执行；可只填一条 |
解析顺序
按顺序取第一个命中的，三个入口规则一致：
| 优先级 |
来源 |
scope |
| 1 |
--config <file> 或环境变量 REMOTE_BUILD_CONFIG |
explicit |
| 2 |
从起点目录逐级向上找到的第一份 .vscode/remote-build.json |
project |
| 3 |
~/.remote-build.json |
global |
| 4 |
内置默认值 |
global + Exists: false |
- 起点目录：VS Code 用当前工作区文件夹，CLI 用
process.cwd()。向上查找不设边界，所以把工程的子目录当工作区打开、或在子目录里跑 CLI，都能找到工程配置。
- 家目录那份
~/.remote-build.json 是兜底：该目录下没有工程配置时用它，单次远程命令不必先建工程文件。原有配置无需迁移。
- 文件之间不继承：工程文件是一份完整配置，五个字段各写各的；内置默认值只用于补齐缺失字段（比如不写
init 会拿到 source ~/.bashrc），永远不会拿全局文件去补工程文件。
- 用
remote-build config 可随时查看当前命中的是哪个文件、scope 是什么。
.vscode/remote-build.json 默认可以随仓库提交、供团队共用同一台构建服务器；不想共享就把它加进 .gitignore。
使用方式
1. 侧边栏：服务器参数设置
活动栏点 Remote Build 图标：
- SSH host 是下拉列表，选项直接取自
~/.ssh/config 的 Host 条目（含 192.168.26.200[Telink-SDK] 这类把昵称嵌进 Host 名的写法），点开即选，也可以手输。
- Project directory 右边的 Browse 按钮会连上服务器逐级浏览目录，选中即回填，不用手敲路径（需先填 host）。
- Build commands 按顺序执行，可增删、上下调序。
改完点 Save。保存规则：该工程已有 .vscode/remote-build.json 就读它、也写回它；没有的话，表单先显示全局配置作参考，一旦点 Save 就落成这个工程的本地配置，此后该工程默认读本地那份。表单底部的提示行会写明当前保存到哪。
这样每个工程的 cwd / cmds 各存各的，切工程不会再互相覆盖。想回到"用全局配置"，删掉该工程的 .vscode/remote-build.json 即可。
2. 终端：远程命令行
终端面板「+」下拉 → Remote Build → 基于当前工程配置的 host 开一个到服务器的交互式 SSH 命令行窗口。
该条目出现的前提：package.json 的 contributes.terminal 声明的 id 必须与 registerTerminalProfileProvider 的 id 一致，且当前工程的配置里已填 host（否则 provider 返回空、profile 不显示）。
终端的 shellArgs 在打开时就固定了，换工程后已开的终端不会自动切换目标，需要新开一个。
3. CLI：AI agent 自动化触发与分析
CLI 面向 AI agent 编程全流程：agent 调用它远程执行构建 / 测试命令，并以退出码、超时标记、stdout/stderr 分离判断成败。
# ① Windows（推荐）：把 CLI 目录加入 PATH 后，任意目录直接调用
remote-build build [--timeout <ms>] [--config <file>] [--project <dir>]
remote-build run --cmd "<command>" [--cwd "<dir>"] [--timeout <ms>] [--config <file>] [--project <dir>]
remote-build init [--project <dir>] [--force]
remote-build config [--config <file>] [--project <dir>]
# ② 不经 PATH —— PowerShell（~ 不展开，用 $HOME）
node "$HOME\.remote-build\cli.js" build [--timeout <ms>] [--config <file>] [--project <dir>]
node "$HOME\.remote-build\cli.js" run --cmd "<command>" [--cwd "<dir>"] [--timeout <ms>] [--config <file>] [--project <dir>]
node "$HOME\.remote-build\cli.js" init [--project <dir>] [--force]
node "$HOME\.remote-build\cli.js" config [--config <file>] [--project <dir>]
# ③ 不经 PATH —— Git Bash（~ 可展开）
node ~/.remote-build/cli.js build [--timeout <ms>] [--config <file>] [--project <dir>]
node ~/.remote-build/cli.js run --cmd "<command>" [--cwd "<dir>"] [--timeout <ms>] [--config <file>] [--project <dir>]
node ~/.remote-build/cli.js init [--project <dir>] [--force]
node ~/.remote-build/cli.js config [--config <file>] [--project <dir>]
# ④ 本地开发：构建后直接用 dist/ 下的 CLI
node dist/cli.js build [--timeout <ms>] [--config <file>] [--project <dir>]
node dist/cli.js run --cmd "<command>" [--cwd "<dir>"] [--timeout <ms>] [--config <file>] [--project <dir>]
node dist/cli.js init [--project <dir>] [--force]
node dist/cli.js config [--config <file>] [--project <dir>]
参数：
| 参数 |
说明 |
--config <file> |
直接指定配置文件，跳过全部查找（scope = explicit）。等价于环境变量 REMOTE_BUILD_CONFIG |
--project <dir> |
指定向上查找的起点目录，默认 process.cwd() |
--force |
init 时覆盖已存在的工程配置 |
--timeout <ms> |
超时，超时返回 124 |
init 在 <dir>/.vscode/remote-build.json 创建工程配置，种子取自创建当下生效的那份配置（是一次性拷贝，之后两份各管各的，不存在运行时继承）。已存在时须加 --force。它是侧边栏 Create project config 的非交互版本，供 agent 脚本化配置新工程。
将 CLI 目录加入用户 PATH（一次性，新开终端生效）：
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";$env:USERPROFILE\.remote-build", "User")
约定：
- 退出码 = 远程命令退出码（agent 据此判断成败）
- 超时返回 124
- stdout / stderr 分离，便于 agent 解析
build 按 cmds 顺序逐条执行，任一失败即停止并返回该退出码config 首行固定为 Config file: <路径>，其后是 Scope: / Exists:，便于脚本抓取
扩展每次激活会把编译好的 CLI（cli.js + core/）和一个 Windows 包装脚本 remote-build.cmd 复制到 ~/.remote-build/，因此 vsix 安装后无需源码即可从命令行调用。
Git Bash 提示：--cwd 以 / 开头的绝对路径会被 MSYS 转成 Windows 路径而失效，用双斜杠 //home/... 规避。
常见问题
换了 host 之后 Browse 打不开
表单里的 Project directory 常常是从全局配置带过来的，可能属于另一台服务器。换了 host 之后这个路径在新机器上并不存在，直接 cd 会失败。
现在 Browse 会自动回退到新服务器的 home 目录并提示你（"<旧路径>" is not on this host, starting from <新 home>），不会卡住打不开。挑到正确目录后保存即可。
Browse 点了没反应 / 报 Permission denied (publickey,password)
Browse 和 CLI 都是非交互执行，ssh 带 -o BatchMode=yes 运行，不会弹密码提示，只认密钥。某个 Host 没配好密钥时就会认证失败——插件会直接说明原因，不会再干等到超时。
自己排查：
ssh -o BatchMode=yes "<host>" true
| 报错 |
怎么办 |
Permission denied |
把本机公钥加到服务器 ~/.ssh/authorized_keys，或在 ~/.ssh/config 给该 Host 加 IdentityFile ~/.ssh/id_rsa |
Host key verification failed |
先在终端手动 ssh "<host>" 接受一次指纹 |
Cannot resolve / Cannot reach |
主机名、端口、网络不通 |
| 确实超时 |
ssh 在等一个永远不会来的输入，同上先用 BatchMode 自查 |
需要交互式密码登录的服务器，用终端 Profile 打开（终端面板「+」→ Remote Build）——那是真正的交互式 ssh，不受 BatchMode 限制。
目录结构
src/core/config.ts 配置解析：工程优先 / 全局兜底 / 读写
src/core/remote.ts spawn ssh.exe 执行远程命令；列举远端目录
src/core/sshHosts.ts 解析 ~/.ssh/config 的 Host 列表（侧边栏下拉）
src/workspace.ts 当前工作区判定（仅 VS Code，不随 CLI 落位）
src/configWebview.ts 侧边栏配置表单（Webview）
src/extension.ts 入口：侧边栏视图 + 终端 profile + CLI 落位
src/cli.ts CLI（run / config）
media/remote-build.svg 活动栏图标
media/icon.png 扩展图标（Marketplace，128×128 PNG）
构建 & 打包
npm install
npm run build
npm run package # 先 tsc 编译到 dist/，再打包产出 windows-remote-build-1.0.2.vsix
发布到 Marketplace
前置：package.json 已配置 publisher / repository / license / icon。
npx vsce login Aaronlu2026 # 输入 Azure DevOps PAT（scope: Marketplace > Manage）
npx vsce publish # 重新校验 + 打包 + 上传
PAT 在 https://dev.azure.com/<组织>/_usersSettings/tokens 生成。扩展 name 在 Marketplace 全局唯一，被占用会报 already exists，需改名后重新打包。
前置要求
- Windows 自带 OpenSSH 客户端（
ssh.exe），或系统 PATH 上有 ssh。
- 目标服务器已配好 SSH 别名（
~/.ssh/config），免密登录（authorized_keys）已就绪。
