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 命令。

现有 API 优先

已安装的 bridge 是签名和行为的唯一依据。先描述目标,再调用。不要猜测标志、方法名或返回结构。

长时间 Maestro 运行

Maestro 运行可能比单次工具调用持续更久,守护进程也可能中途重启。这种情况用 MaestroJobManager:它只提交一次 job,之后持续观察即可。

提交一次,持久观察PYTHON
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。

检查、守卫、准备PYTHON
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:

授权回答PYTHON
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。结果不确定时,不要重复输入。

  1. 先只读检查。
  2. 对含义不明确的对话框,先展示预览并询问用户。
  3. 未经授权,绝不要回答仿真启动或保存对话框。
  4. 确认关闭;结果不确定时不要重复输入。

远端运行时启动时,插件会先预部署并校验 X11 helper。之后如果又缺失,直接调用现成的 x11.dismiss_window API 即可。helper 上传本来就属于 virtuoso-bridge,不是插件新加的函数。

history 与 setup 冲突

信号含义动作
EXPLORER-2406请求的 history 名称已存在。不要重新提交。检查现有 history,然后使用 history API 或显式 SKILL 重命名。
MaestroMonteCarloError: unsaved or unknown setup changesMaestro 设置已修改但未保存,或状态未知。调用 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 相互独立,因此不存在固定的临时脚本。按调用选择合适的方式。

  1. 用普通文件工具在工作区写入 batch.py。
  2. 用 path: "batch.py" 运行它。每次运行都会把当前文件复制到新的 job 目录。
  3. 失败或测量后编辑文件,然后再次运行。下一次运行会读取编辑后的内容。

如果这段脚本以后还要复用,这个循环通常比重发脚本体更省。代码留在工作区里可审查,改一处也不必重发整个脚本。一次性探测用内联代码更简单。

连接启动

读运行时状态,别从单条日志猜。virtuoso_bridge_runtime 的 status 动作报告 stage、daemon、daemonProbe、setupHint、attach 和 error。这些状态名会指出缺失的是哪一层,因此不必盲目重新部署或重启。

  1. 仅在状态为 waiting 时执行打印的 load("...") 行。此时 SSH(Secure Shell)登录和隧道已就绪,CIW(Virtuoso Command Interpreter Window)尚未加载 setup。在 setup 加载前,守护进程端口上没有应答。
  2. 启动固定端口连接,让探测挂接已签名的守护进程。attach.attached 会记录这次复用,不需要部署或加载 CIW。
  3. daemonProbe 报 no-listener 或 legacy 时,执行 deploy_daemon,再在目标空闲 CIW 里加载返回的那一行,然后重新启动。重连或重启不会部署文件,也不会重新加载 setup。
  4. 把超时的浏览器请求当作待定,而不是失败。部署通过 SSH 运行,可能超出较短的状态轮询预算。部署错误会带上 errorCode、path 和 hint。插件会创建账号主目录下缺失的暂存根目录。其他位置缺失的路径,错误信息会给出所需的 mkdir -p -m 700。
  5. 没有运行中的运行时也要做这些检查时,执行 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 最新的会话日志:

显式读取 CIWPYTHON
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,并报告实际观察到的内容。