03 · API

智能体工具

四个工具把智能体接到已安装的 bridge 上。一个管理运行时和连接,一个描述并调用 Python API,一个执行批处理脚本,一个安装并修复环境。

四个工具

四个工具都注册在 Host 上,profile 的每个会话都能使用。运行时是进程级的:fork、新会话或子智能体会话共用同一条隧道和同一个守护进程。

工具一句话用途何时使用
virtuoso_bridge_runtime管理隧道、守护进程和已保存的服务器连接。需要状态、启动/停止、健康测试、实例发现或守护进程部署时。
virtuoso_bridge_api描述并调用任意公开的 virtuoso-bridge 目标。已知需要的 bridge 方法,希望做一次结构化调用时。
virtuoso_bridge_script在全新的 Python 虚拟环境(venv)进程中运行 Python,可直接使用已连接客户端。工作需要循环、多次调用、测量或持久化结果时。
virtuoso_bridge_setup安装、更新、诊断并配置隔离的 venv。环境缺失、损坏,或你刻意改动过环境时。

这些工具不新增 Maestro runner、job store、dialog manager、history manager 或调度器。它们只是 bridge 和 Host 托管运行时之上的一层轻量封装。上游已有的能力通过 describe 和 call 访问,而不是通过插件包装。

运行时工具

virtuoso_bridge_runtime 接受一个必填的 action,以及对应动作所需的参数。connection 传 id 或名称,省略则用默认连接。runtime(rt_...)在一条连接有多个运行时时指定其中一个。SSH(Secure Shell)隧道和 sidecar 也由这个工具管理。

动作作用
status返回环境、连接、运行时、已关联智能体和运行中动作的紧凑投影。
list返回 profile 中每个连接和运行时的同样投影。
start创建或复用托管的 SSH 隧道,连接 sidecar,并在有已签名守护进程应答时挂接它。
stop拆除这个运行时的隧道和 sidecar。
restart停止并再次启动运行时。它不会部署文件,也不会重新加载 CIW(Virtuoso Command Interpreter Window)中的 setup。
ping向运行中的 sidecar 请求新的状态快照。
connections列出已保存的连接配置。
save_connection根据 connectionConfig 创建或更新连接,凭据通过只写的 secret 传入。
delete_connection删除已保存的连接。
test_connection返回 SSH、远端 Python、暂存根目录和守护进程的分层健康报告。
instances发现自动会话实例,可用 timeoutSec 设置预算(默认 20)。
select_instance在重启前把发现的守护进程 port 保存到连接上。
deploy_daemon准备并上传账号 bootstrap,然后返回其 load("...") 行。
detect_shell在 csh 和 sh 下运行 Cadence 环境脚本,并缓存能提供 virtuoso 的那种 shell。
host_key探测 SSH 主机密钥,报告指纹、已知和未知条目以及冲突。
trust_host把一个经用户确认的 fingerprint 写入 known_hosts,并且只接受全新探测实际提供的密钥。
orphans列出更早的 DeepSeek Harness(DSH)进程崩溃后遗留的隧道。
stop_orphan停止其中一条遗留隧道。

紧凑状态投影

status 和 list 返回的是紧凑投影,不是面板上的完整状态。投影覆盖环境就绪情况与来源、SSH 后端、连接端点、运行时状态和阶段,也覆盖 daemon 状态(ready、no-response、auth-failed、unreachable、unknown)和 daemonProbe 结果。其余部分包括选中的 instance(端口、Virtuoso pid、工作目录)、attach.attached、setupHint、错误、已关联智能体和运行中动作。

冗长的安装日志、来源与 venv 调试路径、隧道内部信息和完整 traceback 都留在 UI 里,完整状态以 UI 为准。固定端口启动挂接到存活守护进程时,会报告 attach.attached。setupHint 只在首次就绪之前出现,所以健康的连接不会显示 CIW 提示。

状态,然后启动JSON
{"action": "status", "waitMs": 15000}
{"action": "start", "connection": "lab-virtuoso"}

waitMs 是 status、start 和 ping 的等待预算(默认 15000)。status 会等待进行中的启动稳定下来,或在预算耗尽时返回待定快照。

实例与子实例

启用 autoSessions 后,守护进程的端口由操作系统分配,连接绑定到发现的实例,而不是固定端口。instances 只做只读发现。在 select_instance 保存端口之前,插件不会选中任何实例。没有选择或匹配到多个实例时,调用会失败并列出可用实例,而不是静默自选。

发现并选择JSON
{"action": "instances", "connection": "lab-virtuoso", "timeoutSec": 20}
{"action": "select_instance", "connection": "lab-virtuoso", "port": 65142}
{"action": "restart", "connection": "lab-virtuoso"}

工作目录子实例通过 start 或 restart 上的 subInstance 启动,取值可以是 id、名称或绝对远端工作目录。每个子实例有自己的 VBL(virtuoso-bridge-lite)profile 和 sidecar,插件按工作目录发现它。所以一条连接就能覆盖多个项目 CIW,不用给每个都分配固定端口。workDir 按绝对远端工作目录过滤发现结果。

部署与测试

固定端口的 start 会先探测守护进程端口,并挂接已签名的守护进程,所以守护进程还活着时,你既不用部署也不用加载 setup。deploy_daemon 不建立连接,只准备生成的账号 bootstrap:它不启动隧道或守护进程,也从不加载 SKILL(Virtuoso 的脚本语言)。

远端 bundle 与当前不一致时,普通部署不会覆盖它。结果会报告两个版本,replace: true 是明确的升级路径。通过 daemonSetup 配置或由 virtuoso-bridge install-daemon 安装的共享 setup 对客户端只读,客户端无法替换。固定端口旧版部署会带上 recommendedAutoSessions,因为这类守护进程在 CIW 重启后无法被发现。

显式替换JSON
{"action": "deploy_daemon", "connection": "lab-virtuoso", "replace": true}

test_connection 返回结构化报告,包含 ssh、remotePython、scratchRoot,以及签名或未签名的 daemon 探测。运行时停止时也能执行。它不是 SSH ping,也从不部署或创建暂存根目录;只有 SSH 和已签名守护进程同时通过,卡片才把目标标为就绪。运行时已启动时,测试复用其 Host 托管隧道;运行时停止时,测试打开一条短命的探测隧道。Paramiko 会话从不启动 ssh.exe。

连接写入与批准

id 和 name 都匹配不上现有连接时,save_connection 新建一行。不带 id 而用已有名称保存,则更新那一行,不新建重复行,结果给出 created 或 updated。host、user、sshPort、jumpHost/jumpUser 或角色主机一变,插件就把现有行重定向到新目标。

创建连接或修改现有行的 SSH 目标,都属于工作区之外的修改。保存的连接是一项长期授权,启动它会在对应账号上打开 shell、Python 和 SKILL。所以工具要通过 DSH 权限卡片请求批准,除非会话具备 完全权限。批准被拒绝或不可用即为终态。SSH 目标不变、只改备注、暂存根目录、子实例或环境的保存,不需要提示。

固定模式下,port 留空会从 SSH 用户名派生每个用户专属的稳定守护进程端口(SHA-1,范围 65000–65499)。自动模式下不使用 port,保持未设置。守护进程 token 只写:通过 secret 传入,存储在 DSH credentials 服务中,而不是连接 JSON。

不要绕过拒绝

如果批准被拒绝或不可用,请在配置页创建连接。不要手动编辑插件设置来绕过权限卡片。

API 工具

virtuoso_bridge_api 让你读 bridge、调 bridge 都不用猜签名。describe 分三个层级,另支持按方法名查找。返回直接来自已安装版本,所以不升级插件也能看到较新的 layout、Maestro 和对话框辅助方法。

描述形式返回
describe返回紧凑索引,包含目标、有文档的类和描述提示。
describe target=client.schematic把这个目标的方法列为 name(signature) -> return,附简短摘要、属性和子目标。
describe target=client.schematic method=open_window只返回一个方法,含完整 docstring 和参数表。
describe method=open_window列出定义这个方法的各个目标。
描述,然后调用TEXT
virtuoso_bridge_api action=describe
virtuoso_bridge_api action=describe target=client.layout
virtuoso_bridge_api action=describe target=client.schematic method=open_window
virtuoso_bridge_api action=describe method=open_window

插件不会截断超出内联预算(约 14,000 字符)的答案。完整负载以 JSON 写入 <cache dir>/results/,回复末尾给出文件路径。读取或 grep 之后,用 virtuoso_bridge_setup action=clear_cache cache=results 清理。较大的 call 结果遵循同样的规则。

可调用目标

call 在某个公开目标上调用一个方法:

  • client — 已连接的客户端本身,包括 execute_skill 和 run_shell_command。
  • client.schematic、client.layout、client.library、client.symbol — 设计类目标。
  • client.maestro、client.sos — Maestro 与 SOS 目标。
  • client.dialogs、client.requests — 对话框与请求目标。
  • spectre — Spectre 目标。

参数按位置放在 args,按名称放在 kwargs。复杂值使用显式标记:{"$type":"path","value":"/projects/example/x.il"} 表示远端路径,{"$type":"bytes","data":"<base64>"} 表示字节。VirtuosoResult、SimulationResult 等 dataclass 结果会转换为 JSON。timeoutSec 限定 bridge 侧操作的超时。

通过 API 执行 SKILLJSON
{"action": "call",
 "target": "client",
 "method": "execute_skill",
 "args": ["1+1"],
 "description": "Check the daemon answers",
 "timeoutSec": 60}

call 可以带一行可选的 description,用作工具卡标签。每次调用都会渲染成与脚本运行相同的可展开代码卡。execute_skill 调用把 SKILL 源码显示为代码。其他调用显示参数。两张卡都带有 dsh-virtuoso-bridge 徽标。

脚本工具

virtuoso_bridge_script 在一个全新的 venv 进程里运行 Python,绝不在 sidecar 里运行。所以批处理脚本出错,也不会破坏连接。脚本使用 connect()、emit() 和 result 这套约定:

脚本约定PYTHON
import virtuoso_bridge as vb
client = connect()          # reuse the running tunnel/daemon
emit({"progress": 0.5})     # structured progress
result = {"done": True}     # persisted as result.json

一次运行只接受一种来源:内联 code,或指向 Python 文件的 path。相对 path 以 Session 工作目录为基准,正好指向普通文件工具刚写下的文件。每次运行都把文件的当前内容复制到自己的 job 目录,所以代码修改在下一次运行时才生效。job 之间彼此独立,没有固定的临时脚本。

动作作用
run启动 job,并在它仍在运行时返回 Running 和它的 id。
status返回完整 job 快照,包括增量 stdout 和 stderr。
list列出近期 job。
cancel取消 job。

job 带 id、状态、增量 stdout 和 stderr,支持硬超时和取消。一个会话启动的 job,另一个会话也能轮询。插件启动时会索引最近 40 个 job 目录。

每次调用都需要一行简短的 description,用作工具调用标签和 history 标题。成功运行返回 Success 和 result。运行中的 job 返回 Running 和它的 id。失败返回错误和 id。插件不暴露内部路径、代码预览、状态记录和自动连接字段。

合并探测

一个较大的脚本胜过多次小运行。把要做的读取、修改和检查都放进一个脚本体,再打印测量结果。如果这段工作以后还要复用,就存成工作区文件,用 path 传入;这样改一行后下一次运行即生效,不必重发整个脚本体。只探一次的工作,用内联代码更简单。

可复用文件JSON
{"action": "run", "path": "batch.py",
 "description": "Measure open schematic windows",
 "timeoutSec": 600}

安装工具

virtuoso_bridge_setup 管理隔离 venv、来源和缓存。status 和 preflight 只返回决定下一步所需的事实。完整安装日志、来源详情和存储列表留在配置页。

动作作用
status报告安装状态、来源模式、venv、SSH 后端和缓存目录。
preflight在安装前报告支持的 SSH 后端和 extra 定义。
install创建或修复 venv,并安装选中的来源。
update从当前来源重新安装,并再次拉取 git 来源。
diagnose返回显式的插件调试报告,包含 Host 自检。
configure持久化运行时默认设置,例如 Python 可执行文件和缓存目录。
set_source选择内置来源、本地开发仓库或指定 ref 的 git 仓库。
caches列出缓存项及其路径、大小和文件数。
clear_cache清理一个缓存:pip、sources、jobs、results 或 logs。

安装默认包含 SSH extra(paramiko 加 PySocks),并从插件 venv 验证 import virtuoso_bridge。如果 PATH 中没有 OpenSSH,install 会停止并返回确认请求。用 confirm: true 重试,即可只用 Paramiko 后端继续。

无 OpenSSH 时安装JSON
{"action": "install", "confirm": true}

CIW 诊断

先读 CIW 块,别急着猜调用为什么没生效。virtuoso_bridge_api 的 call 和已结束的 virtuoso_bridge_script job,会在调用期间 CIW 有输出时附加一段紧凑的 CIW 块:

附加的 CIW 块TEXT
--- CIW: 1 warning, 1 error, 1 output line (41 other lines) ---
*WARNING* (DB-270212): dbOpenCellViewByType: ...
CDF: An error occurred when evaluating callback.

块头统计警告数、错误数和输出行数,并标出共享 CIW 日志里其余的部分。采集只是尽力而为:本地 Windows Virtuoso、缺少 /proc 或通道繁忙,都可能跳过采集,所以块缺失并不等于 CIW 没有输出。警告从 SKILL 警告端口刷出,块则读自会话的 CDS.log。Virtuoso 的日志写入器会批量输出文本,因此某一行可能要晚一次调用才出现;失败的调用和已结束的脚本 job 都会先短暂等待再读取。

捕获到的一行可能来自用户,也可能来自别的工具。把它当 CIW 输出看,不要当作所属结果的证据。采集绝不会让调用失败;在配置页取消勾选 将 CIW 的警告/错误随结果一并报告(ciwReport)即可关闭。块缺失时,显式读取 CIW 的方法见 工作流配方。

已安装技能

安装会把上游文档 — skills/、README.md 和 AGENTS.md — 放到:

指令目录TEXT
<dataDir>/instructions/

插件在 DSH 技能目录里注册 virtuoso-bridge 技能,把这个目录作为 resource base,并列出每个已安装的 SKILL.md。系统提示给出同一个绝对路径,并要求智能体在发出 bridge 命令前先读匹配的技能或参考。智能体不要凭猜测编写 virtuoso-bridge CLI 标志。连接、部署、自动会话和实例选择这类操作,读 skills/virtuoso/references/connection.md。

重新安装或更新 bridge 即可刷新已安装文档。安装还会放入 references/agent-workflows.md,这是现有 VBL API 之上的简短封装指南。

批量处理

每次额外调用都是一次往返。用少数几次大调用代替很多次小调用:

  • 把探测合并到一个脚本。把需要的读取、编辑和检查放进一个脚本体,并打印测量结果。
  • 只描述一次。读取目标的签名,然后调用。不要每一步都重新发现同一个方法。
  • 用脚本代替重复调用。一个在客户端上循环的 job 胜过十次独立的 call。
  • 让大答案变成文件。过大的答案会写入 <cache dir>/results/。直接 grep 文件,而不是再次询问。
先读状态再行动

运行时操作可能还在进行。带 waitMs 的 status 会一直等到启动落定,这样下一步就不会抢在状态稳定之前。