05 · 架构
运行时生命周期与内部机制
一个托管运行时把三样东西绑在同一个运行时 id 下:一条 SSH(Secure Shell)转发、一个 Python sidecar(每个运行时一个 helper 进程),以及 Virtuoso CIW(Command Interpreter Window)里的一个守护进程。这一整套由 Host —— 插件的 Node.js 侧 —— 持有,而不是某个会话。运行时活在插件进程里,存活时间比启动它的会话更长,并显示在右侧边栏面板中。本章说明每个状态的含义、隧道由谁管理、helper 继承什么环境,以及文件存放在哪里。
状态与对象
运行时的 state 只回答一个问题:这个连接现在能用吗?status 动作以紧凑投影给出答案。启动返回同一份快照,面板只是把它渲染出来。
| 状态 | 含义 |
|---|---|
stopped | 没有运行时:既没有转发,也没有 sidecar 进程。 |
starting | 隧道与 sidecar 正在启动。 |
connecting | sidecar 正在连接守护进程,或正在为它部署。 |
waiting | 隧道已建立,但守护进程还没有应答。 |
running | 守护进程有应答,execute_skill("1+1") 经由它返回。 |
error | 启动、健康检查或运行时操作失败。 |
needs-trust | 主机提供了未知 SSH 密钥。在你确认指纹之前,运行时保持停止。 |
停止是一个短暂过渡。运行时拆除自己的 worker、sidecar 和转发期间,快照状态是 stopping。它不是常驻状态。
守护进程与连接状态
状态只告诉你连接断了,不告诉你断在哪一层。所以每份快照都另外带一个 daemon 对象,面板把它作为一个独立标签显示在连接状态旁边。这个值在启动时来自 connect 握手;即便运行时已经停止,测试 也会探测它。
| 守护进程状态 | 证明什么 |
|---|---|
ready | 已签名的 bridge 守护进程应答了能力握手。 |
no-response | 守护进程端口在 TCP 层可达,但后面的 bridge 不应答。 |
auth-failed | 存在 bridge 守护进程,但它拒绝本客户端的 token。 |
unreachable | 配置的守护进程端口上没有任何应答。 |
unknown | 探测尚未得出结论。 |
同一组取值也会以 connectionStatus 出现在运行时快照里:ready、no-response、auth-failed、unreachable 或 unknown。另一个字段 daemonProbe 给出部署侧的结论:no-listener、legacy,以及守护进程是否已签名。要不要重新部署,就看这个结论。
挂接到已签名的守护进程
固定端口启动先探测守护进程端口,之后才部署。如果这个账号的守护进程以已签名的能力握手应答,运行时就挂接它并跳过部署,在快照里报告 attach.attached 和复用的 setup 路径。这种情况下插件不准备暂存根目录,所以坏掉的暂存根目录挡不住正在运行的实例。连接侧的说明见 部署前挂接。
生命周期
start 打开托管转发并连接 sidecar;restart 重新执行这一流程,subInstance 指定一个已配置的工作目录子实例。带 waitMs 的 status 会等启动落定,不会只返回一个 starting 快照。固定端口启动停在 waiting 也可能是有意为之:网络侧已经通了,只是 CIW 还没加载准备好的 setup。
重连或普通重启不会部署文件,也不会在 CIW 里重新加载 setup。只有 deploy_daemon 会准备 bootstrap。加载仍要由人在目标空闲 CIW 里完成。
健康检查循环
Host 的健康循环每 20 秒向每个处于 running、waiting 或 error 的运行时的 sidecar 请求一次状态。这个循环不向 CIW 写入任何内容:除非打开 settings.logToCiw,否则一直是 log_to_ciw=False。它还能捕获漏掉的子进程事件,所以转发退出时即使没有通知,插件也能发现。
守护进程一恢复应答,waiting 就转为 running。循环同时记下远端项目工作目录,并清除 setup 提示。原本 running 的运行时一旦不再应答,就退回 waiting,由弹窗检查接手。
弹窗检查
守护进程不应答时,Host 会检查 X11 弹窗,并把结果写进快照:状态里带弹窗标题,面板显示警告,提示你到 Virtuoso 里点击或回答弹窗后刷新。提示不会建议你重装守护进程或重新加载 setup。守护进程探测已经报 no-listener 时,插件会跳过这项检查,因为那种情况不可能是弹窗造成的。
守护进程原本健康、后来才停止应答时,面板报的是守护进程丢失的原因,而不是首次安装的提示。setup 毕竟已经加载过一次,这时候该看的是 CIW 本身。
进程级运行时
运行时是进程级的。它们跨会话切换、fork 和子智能体会话存活,profile 里每个会话都连到同一个活动 bridge。禁用或卸载插件、DSH 退出,或者执行 stop 动作时,它们才会停止。
进程崩溃可能留下一条孤儿转发。插件从 virtuoso-bridge 的状态文件和自己的隧道记录里找出它:orphans 列出这些转发,stop_orphan 停止其中一条,运行时面板也给出同样的控件。
Host 托管的隧道
固定端口的远程连接,SSH 转发由 Host 自己打开,不交给 Python sidecar —— 交给 sidecar 就多出一个不受管的 ssh.exe。只有自己持有子进程,插件才能拿到就绪信号、选定本地端口,并让所有 helper 共用同一条转发。本节讲的就是这个设计。
ssh 子进程
lib/tunnel.js 把 ssh -N -L 当成一个隐藏、非 detached 的子进程启动,再用子进程事件跟踪它。
ssh -v -N -L 65123:127.0.0.1:65123 -l designer virtuoso01.example.com
真实命令还会传 -o BatchMode=yes、连接超时、ControlMaster=no / ControlPath=none / ControlPersist=no、ExitOnForwardFailure=yes,以及 ServerAliveInterval=30 与 ServerAliveCountMax=3。另外还带 -F(生成的配置)、-i(identity file)和 -J(jump host)。
非 detached 是有意为之。Windows 上,隐藏的非 detached 子进程会保留一个隐藏控制台,而它隐式的 ProxyJump 或 ProxyCommand 子进程会继承这个控制台。把隧道设成 detached,恰恰会让这个孙进程弹出可见的控制台窗口。
就绪判定来自 OpenSSH 自己的详细日志行 Entering interactive session。插件不会靠探测转发端口来判断就绪。隧道断开时,子进程一退出就立刻上报。
本地端口分配
插件先在两个回环协议族上都做一次绑定测试,再确定本地端口。OpenSSH 会为 -L 同时绑定 IPv4 和 IPv6 回环,所以即使端口只在 ::1 上被占用,也不能用。connection.localPort 空闲时优先采用;OpenSSH 仍绑定失败时,启动会换个端口重试,而不是让运行时失败。
接管 shim
sidecar 和每个脚本 helper 都会拿到 VB_PLUGIN_TUNNEL_OWNER=plugin、隧道 PID,以及本地与远端端口。runtime/vb_plugin_env.py 在 isolate_runtime_env() 里安装接管 shim。此后上游 SSHClient 直接采用这条转发,用 PID 判断存活,需要时就抛出错误,而不是再启动一个 ssh.exe。shim 在脚本正文执行之前就安装好,即使脚本从不调用 connect()。没有 Host 开关时,测试与健康检查 helper 拒绝自建转发;Host 负责关闭隧道。
ssh.exe 不会随脚本、健康检查或连接测试增多。脚本也无法拆除 sidecar 正在用的那条转发。
先发现,再转发
数据目录的 tunnels/ 下存着一条小记录,DSH 进程崩溃之后,Host 仍能靠它发现自己托管的转发。面板会显示隧道状态、PID,以及 localhost:port → remote 这一对。
自动会话连接在打开隧道之前,先执行一遍和 instances 动作相同的只读实例发现。这样 Host 转发到的实例,就是 sidecar 将要选定的那个。发现结果不唯一时(多个活动实例又没有已保存的选择),启动会失败并列出候选,而不是转发到错误的 CIW。
面板与端点
两个面板,一个同源端点。两个界面读同一份状态,谁也不留第二份副本。
配置页
左侧边栏入口打开整页配置视图,默认显示 服务器连接。环境、默认设置、存储和活动默认折叠,需要时再展开。环境设置连同来源与安装日志,只在展开或环境不健康时才显示。这一页管理长期配置:安装与修复、连接卡、凭据、工作目录子实例,以及缓存目录。
运行时面板
右侧标签固定为 dsh-virtuoso-bridge。内容包括:
- 环境:仅在环境未就绪时显示,并提供 打开设置 提示。
- 服务器连接:每项带启动/停止、状态和详情折叠。
- 智能体活动:当前会话的智能体置顶并高亮。每个智能体的 history 独立折叠,运行中的工具始终可见,不活跃的智能体仍以灰色列出。
- 连接 pill:与 最近使用 同一行,这个智能体连接过的每个服务器各一个。不活跃超过 10 分钟就变灰。超过 30 分钟只从 pill 里移除,智能体行仍然保留。
- 存储:一行显示大小与剩余空间摘要。完整路径、大小和清理列表在配置页。
单击展开或折叠智能体 history。双击在主视图里打开对应的 DSH 会话。
Composer 控件
Composer 控件是 VB 图标加一个状态点,没有文字。已连接时是绿色,等待或阻塞时是黄色,出错时是红色。会话有调用正在执行时,状态点呼吸绿色。Session 没有活动运行时(running、waiting、starting 或 connecting)时,这个控件不显示,没有 bridge 的 Session 输入框保持简洁。
Dashboard 端点
两个界面都读同源端点 /__dsh/virtuoso-bridge,走 SSE 流。Host 通过 ctx.inject(['webServer']) 注册这条路由,所以即使冷启动时 webserver 晚于功能插件激活,路由依然存在。
浏览器端从仅回环可读的 /bootstrap 取到 { token, origin, basePath }。它先试注入的 origin,再试页面自己的 origin,并在 404 或 token 过期后重试。端点要求每进程 token,或本机同源请求。跨站请求即使来自 127.0.0.1,端点也会拒绝。
把 Web server 绑到非回环地址,暴露的不只是这个端点,而是整个 DSH 界面。保持默认的回环绑定。升级插件后刷新页面,让浏览器用上当前 bundle。
隔离
运行时不能继承你或另一套 bridge 安装早先保存的内容。插件在进程边界上强制这一点。连接侧的规则见 凭据与认证。
运行时环境
插件从不复制你的 ~/.virtuoso-bridge/.env;导入 virtuoso_bridge 之前,插件用一个空的运行时 env 文件把每个 Python helper 与这个文件隔开。范围覆盖部署、发现、SSH 测试、sidecar、shell 探测和脚本,所以对这个运行时来说,保存的连接才是准绳。helper 以 -E -s 从插件 venv 启动,不继承 PYTHONPATH、PYTHONHOME、VIRTUAL_ENV,也拿不到环境里已有的 VB_* 值。第二套本地 virtuoso-bridge 安装无法改变插件调用的行为。
venv 校验
只要导入的 virtuoso_bridge 不是来自插件 venv,venv 探测会拒绝报告就绪。唯一例外是显式配置的 editable 本地 checkout:那种情况下 venv 就是有意指向这个来源的。
生成的 SSH 配置
生成的每个运行时 SSH 配置,按 profile 和连接 SSH 相关字段的摘要做内容寻址。因此工具调用无法删除或修改正在运行的隧道所用的配置文件。编辑连接会生成新文件,活动转发继续用自己的那一份。
守护进程 token 存在 DSH credentials 服务里,是一条 grant 记录。它在 UI 里只写,经 sidecar 的环境传入;连接 JSON 和日志里都不会出现,面板也从不返回。
数据、缓存与存储
插件把持久状态和可丢弃产物分开存放。数据目录放运行时再启动所需的内容,缓存目录放可以重建或清理的内容。两个路径及各自的覆盖方式见 数据目录。
| 项目 | 位置 |
|---|---|
| Python venv | 数据目录 |
settings.json 与插件日志 | 数据目录 |
已安装的 bridge 文档:skills/、README.md、AGENTS.md | 数据目录,instructions/ |
| Host 托管转发的隧道记录 | 数据目录,tunnels/ |
| pip wheel、git checkout、脚本 job、大型结果 | 缓存目录 |
缓存路径留空就使用数据目录。修改路径不会移动已有文件,运行时面板会立即显示新路径。
配置页的 存储 列出每项缓存的名称、路径、字节数、文件数、剩余空间,以及逐项清理按钮。右侧面板只保留一行大小和剩余空间摘要。
下一章
运维一章把这些内部机制变成决策:相信哪个状态、什么时候部署,以及问题走完检查清单仍未解决时该提交什么。