04 · 实践
智能体工作流
这些配方用的 API 都随 virtuoso-bridge-lite 一起发布。它们让 Maestro 运行全程可观察,回答对话框前先看清内容,结果不确定时也不必重跑工作。
工作原则
插件只暴露 bridge,逻辑仍由 bridge 负责。不要新增插件侧的 Maestro runner、job store、dialog manager、history manager、点数计数器或调度器。下面的每个配方都使用现有入口:MaestroJobManager、client.dialogs、x11.dismiss_window、保存和 history 调用,以及 job 策略调用。
调用之前,先从已安装的包里读出准确签名。virtuoso_bridge_api 的 describe 动作由已安装的 bridge 作答,所以你能看到实际存在哪些方法。配方如果需要 bridge 不具备的能力,就把这个缺口报出来。不要在 bridge 之外再包一层原始 Cadence SKILL(Virtuoso 的脚本语言)或 shell 命令。
已安装的 bridge 是签名和行为的唯一依据。先描述目标,再调用。不要猜测标志、方法名或返回结构。
长时间 Maestro 运行
Maestro 运行可能比单次工具调用持续更久,守护进程也可能中途重启。这种情况用 MaestroJobManager:它只提交一次 job,之后持续观察即可。
from virtuoso_bridge.virtuoso.maestro.jobs import MaestroJobManager
mgr = MaestroJobManager.from_client(client)
job = mgr.submit(session="mySession", run_id="run-001", timeout=180)
status = mgr.status(job) # poll this; it is persisted locally/remotely
print(status)
print(mgr.log(job, lines=80))
submit会先预检对话框守卫,并记录未知结果,而不是提交两次。- 重连或守护进程重启后,用
mgr.list()或mgr.load(run_id)加mgr.reconcile(job)重新建立观察,然后再重试。 - 这套 API 没有 job 取消方法,不要自己造一个。
- 提交前保存已修改的 setup:
client.maestro.save_setup(lib, cell, session=session)。
连接丢失意味着结果未知。先核对现有 job,再做决定。再次提交同一运行可能重复工作。
对话框
检查和守卫都是现成的 API。先只读检查,再为你要处理的那个窗口准备一张关闭 ticket。
report = client.dialogs.inspect(pid=client.remote_virtuoso_pid)
report = client.dialogs.enable_guard(pid=client.remote_virtuoso_pid,
protect_inflight=True)
ticket = client.dialogs.prepare_close(
report.dialogs[0].window_id,
expected_title=report.dialogs[0].title,
)
client.dialogs.close() 发送的是窗口管理器的关闭动作,不能用来回答对话框的 Yes/No。
对于明确授权的 Yes/No/OK 动作,使用现有 X11 helper:
from virtuoso_bridge.virtuoso import x11
results = x11.dismiss_window(
client.ssh_runner,
"<remote-user>",
window_id,
action="alt-y", # alt-y, alt-n, alt-o, enter, escape
display=":0",
pid=client.remote_virtuoso_pid,
)
print(results) # closure_confirmed / still_mapped
动作有 alt-y、alt-n、alt-o、enter 和 escape。结果报告 closure_confirmed 或 still_mapped。结果不确定时,不要重复输入。
- 先只读检查。
- 对含义不明确的对话框,先展示预览并询问用户。
- 未经授权,绝不要回答仿真启动或保存对话框。
- 确认关闭;结果不确定时不要重复输入。
远端运行时启动时,插件会先预部署并校验 X11 helper。之后如果又缺失,直接调用现成的 x11.dismiss_window API 即可。helper 上传本来就属于 virtuoso-bridge,不是插件新加的函数。
history 与 setup 冲突
| 信号 | 含义 | 动作 |
|---|---|---|
EXPLORER-2406 | 请求的 history 名称已存在。 | 不要重新提交。检查现有 history,然后使用 history API 或显式 SKILL 重命名。 |
MaestroMonteCarloError: unsaved or unknown setup changes | Maestro 设置已修改但未保存,或状态未知。 | 调用 client.maestro.save_setup(...),然后重试。 |
history 相关的现有调用有 get_history、lock_history、unlock_history 和 set_history_lock。锁定的 history 可能让下一次 ADE Explorer(Analog Design Environment Explorer)运行复用它的名称。只有确认旧结果安全后,才解锁或重命名。
锁定的 history 会影响下一次 ADE Explorer 运行。先检查现有 history,确认旧结果安全后再解锁或重命名。
大运行与策略
warnWhenSimsExceed 问题是 Cadence 策略,不是 bridge 失败。检查对话框,把问题展示给用户。只在获得授权后回答。
并行执行时,使用现有的 Maestro job 策略 API:maeGetJobPolicy / maeSetJobPolicy,或 client.maestro.set_job_policy。不要新增插件调度器。大运行前确认实际点数和主机容量。如果不熟悉策略签名,先描述 client.maestro。
脚本来源:文件或内联代码
virtuoso_bridge_script 的 run 动作只接受一种来源:内联 code,或指向 Python 文件的 path。job 相互独立,因此不存在固定的临时脚本。按调用选择合适的方式。
- 用普通文件工具在工作区写入
batch.py。 - 用
path: "batch.py"运行它。每次运行都会把当前文件复制到新的 job 目录。 - 失败或测量后编辑文件,然后再次运行。下一次运行会读取编辑后的内容。
如果这段脚本以后还要复用,这个循环通常比重发脚本体更省。代码留在工作区里可审查,改一处也不必重发整个脚本。一次性探测用内联代码更简单。
连接启动
读运行时状态,别从单条日志猜。virtuoso_bridge_runtime 的 status 动作报告 stage、daemon、daemonProbe、setupHint、attach 和 error。这些状态名会指出缺失的是哪一层,因此不必盲目重新部署或重启。
- 仅在状态为
waiting时执行打印的load("...")行。此时 SSH(Secure Shell)登录和隧道已就绪,CIW(Virtuoso Command Interpreter Window)尚未加载 setup。在 setup 加载前,守护进程端口上没有应答。 - 启动固定端口连接,让探测挂接已签名的守护进程。
attach.attached会记录这次复用,不需要部署或加载 CIW。 daemonProbe报no-listener或legacy时,执行deploy_daemon,再在目标空闲 CIW 里加载返回的那一行,然后重新启动。重连或重启不会部署文件,也不会重新加载 setup。- 把超时的浏览器请求当作待定,而不是失败。部署通过 SSH 运行,可能超出较短的状态轮询预算。部署错误会带上
errorCode、path和hint。插件会创建账号主目录下缺失的暂存根目录。其他位置缺失的路径,错误信息会给出所需的mkdir -p -m 700。 - 没有运行中的运行时也要做这些检查时,执行
test_connection。它报告 SSH、远端 Python、暂存根目录和守护进程。
首次 IL 加载如果失败并报 load: can't access file - ~/...,说明带 ~ 的路径传到了 Virtuoso —— load() 不会展开 ~。在远端账号上使用绝对 remoteScratchRoot,或保留 ~/ 让插件解析。部署和客户端/IL 上传永远不会把 ~ 传给 load()。
CIW 诊断
先读 CIW 块。CDF 回调失败、*WARNING* 行和 SKILL *Error* 文本都落在那里,而不是返回值里,所以这个块往往能解释为什么一次调用“什么都没发生”。
virtuoso_bridge_api 的 call 和已结束的 virtuoso_bridge_script job,会在调用期间 CIW 有输出时附加这个块。工具参考说明了块的结构、采集的局限和 ciwReport 开关。
块缺失或太晚时,显式读取 CIW。先强制刷出警告端口,再 tail 最新的会话日志:
client.execute_skill('warn("") getWarn()')
log = client.run_shell_command(
'set log = `ls -t ~/CDS.log* | head -1` ; tail -n 40 "$log"')
print(log.output)
run_shell_command 在 Virtuoso 进程环境中运行 csh,因此 .output 包含这个命令的 stdout 和 stderr。不要每次调用都这样轮询。自动附加的 CIW 块更省。
失败规则
- 套接字错误或守护进程掉线意味着结果未知,而不是失败。用
MaestroJobManager的 status 或 reconcile 检查 job,并在主机侧检查 history。绝不自动重新提交。 - 模态对话框可能阻塞 SKILL,而仿真仍在运行。用 X11 带外检查对话框。不要因为一次 SKILL 轮询超时就重启守护进程或重新提交。
- 优先使用现有的结构化 API,不要靠内省包源码或原始 shell 去猜。
连接在运行中途掉线时,真实的状态是未知。重试前先核对 job 或检查 history,并报告实际观察到的内容。