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 提示。
{"action": "status", "waitMs": 15000}
{"action": "start", "connection": "lab-virtuoso"}
waitMs 是 status、start 和 ping 的等待预算(默认 15000)。status 会等待进行中的启动稳定下来,或在预算耗尽时返回待定快照。
实例与子实例
启用 autoSessions 后,守护进程的端口由操作系统分配,连接绑定到发现的实例,而不是固定端口。instances 只做只读发现。在 select_instance 保存端口之前,插件不会选中任何实例。没有选择或匹配到多个实例时,调用会失败并列出可用实例,而不是静默自选。
{"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 重启后无法被发现。
{"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 | 列出定义这个方法的各个目标。 |
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 侧操作的超时。
{"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 这套约定:
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 传入;这样改一行后下一次运行即生效,不必重发整个脚本体。只探一次的工作,用内联代码更简单。
{"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 后端继续。
{"action": "install", "confirm": true}
CIW 诊断
先读 CIW 块,别急着猜调用为什么没生效。virtuoso_bridge_api 的 call 和已结束的 virtuoso_bridge_script job,会在调用期间 CIW 有输出时附加一段紧凑的 CIW 块:
--- 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 — 放到:
<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 会一直等到启动落定,这样下一步就不会抢在状态稳定之前。