01 · 安装
开始使用
本章带你从一个空的 DeepSeek Harness(DSH)profile 走到正常运行的 bridge:安装 bundle、创建隔离 Python 环境、保存连接,再在空闲 CIW(Virtuoso 命令解释窗口)中加载守护进程 setup。每个 profile 只需做一次,之后的会话复用同一个托管运行时。
环境要求
插件装在一个 DSH profile 里,通过 SSH(Secure Shell)连接 Virtuoso,在 CIW 内运行 SKILL(Cadence 的脚本语言)。环境要求每个 profile 检查一次即可,不必每个会话重复。插件不含 Cadence 或 Spectre 许可,也不含仿真硬件。
| 要求 | 为什么需要 |
|---|---|
| DeepSeek Harness 0.2.2 系列、Cordis 4.x | Host 端、Client 面板和工具注册都针对这套 API。插件已在 DSH 0.2.2-rc.1 / Cordis 4.1 上验证。 |
| Node.js | Host 端运行在 DSH 自带的 Node.js 运行时上,无需单独安装。 |
| Python 3.9+ | 用于创建存放 virtuoso-bridge-lite 的隔离 venv。可执行文件可通过 source.pythonPath / settings.pythonPath 配置。 |
| Python 包索引访问 | 首次安装会用 pip 下载 bridge 源码及其依赖。之后的启动直接复用 venv。 |
PATH 中的 git |
git checkout 与 git 仓库两种来源模式需要它。npm 安装既不需要 git,也不需要 submodule。 |
PATH 中的 OpenSSH ssh 可选 |
推荐。缺少时安装会暂停,经你确认后才只用内置 Paramiko 后端继续。 |
| 可访问的 SSH 主机和运行中的 Virtuoso CIW | 实际 SKILL 操作需要:运行时与 CIW 内的守护进程通信。 |
OpenSSH 是默认后端。没有 ssh 的主机可以改用 Paramiko,但安装要经你确认才继续。测试与运行时用同一后端,所以后端是连接级配置,不随单次调用改变。
安装 bundle
插件是 DSH bundle 包,以公开 scoped 包 @nekomona/dsh-virtuoso-bridge 发布。
从 npm 安装 推荐
让智能体安装这个 bundle,或用插件管理器的 install_bundle 指定包名:
Install the DSH bundle @nekomona/dsh-virtuoso-bridge.
发布包内含插件所装 virtuoso-bridge-lite/ 的打包子集:pyproject.toml、README.md、AGENTS.md、LICENSE、mcp_server.py、src/** 和 skills/**,另有 virtuoso-bridge-lite.pin.json。所以插件只需创建 venv,再从这份源码 pip 安装。不需要 submodule,也不需要 Python checkout。
从 git checkout 安装
只有开发插件本身时才用 checkout。先带 submodule 一起 clone;如果 clone 时漏了 --recurse-submodules,就补一次初始化,再通过 DSH 安装这个本地 bundle:
git clone --recurse-submodules https://github.com/nekomona/dsh-virtuoso-bridge.git <plugin-directory>
git submodule update --init virtuoso-bridge-lite
把插件 bundle 安装到 <plugin-directory>,例如让智能体执行。安装后刷新一次 DSH 页面,更新浏览器端 bundle。安装前就打开的页面仍能通过 loopback 的 panel-token bootstrap 恢复,但只有刷新才能加载最新的 Client bundle。
数据目录
运行时、设置、venv 和插件日志都在 profile 的数据目录下。默认设置 里的缓存目录存放 pip wheel、git checkout、脚本 job 和大型结果。
%USERPROFILE%\.dsh\virtuoso-bridge\<profile>\
settings.json
venv\
instructions\ installed upstream skills, README.md and AGENTS.md
tunnels\ Host-owned tunnel records
<profile> 默认为 default。要覆盖它,可用 Host 进程导出的 $DSH_PROFILE,或 config.dataDir、VB_PLUGIN_DATA_DIR。
内置源码安装的是固定到精确提交的 virtuoso-bridge-lite/ git submodule:1f186abfbb3d658211743cd707f3156ed2f59a87,日期与许可记录在 virtuoso-bridge-lite.pin.json。.gitmodules 不声明 branch,上游 main 再怎么更新,也改不了已装好的源码。不要执行 git submodule update --remote:它是唯一会跟随移动分支的命令。
创建环境
在左侧边栏的全局面板列表里打开 dsh-virtuoso-bridge 配置 入口(VB 图标,在插件与自动化任务旁边)。整页配置面板默认显示 服务器连接。环境、默认设置、存储和活动默认折叠,需要时再展开。
- venv 缺失时用 安装。已存在时用 诊断。
⋯菜单包含 修复 和 更新。- 来源与安装日志(折叠)包含来源模式、Python 可执行文件、本地仓库路径或 git URL/ref、pin JSON、安装日志和后端详情。
安装会创建一个私有 venv,并完成以下步骤:
- 安装工具及其依赖;
- 默认安装 SSH extra(
paramiko+PySocks); - 用
runtime/vb_probe.py验证import virtuoso_bridge。
也可以调用 virtuoso_bridge_setup 的 install 或 update 动作。只想用 Paramiko 时,要传 confirm: true。preflight 动作报告可用的后端和 extra 定义。
Python 可执行文件通过 source.pythonPath 或 settings.pythonPath 配置。来源选择和 pythonPath 一起保存。安装和更新会先保存当前可见的来源草稿,确保实际使用所选来源。
如果 ssh 不在 PATH 中,安装会暂停,经你确认后才只用 Paramiko 后端继续。virtuoso_bridge_setup 的 install 动作也需要同样的确认,不会静默回退。
helper 以 -E -s 从插件 venv 启动,不继承 PYTHONPATH、PYTHONHOME、VIRTUAL_ENV,也不继承环境里已有的 VB_* 值。如果导入的 virtuoso_bridge 不是来自插件 venv,探测会拒绝报告就绪,唯一例外是显式配置的 editable 本地 checkout。插件绝不会复制用户的 ~/.virtuoso-bridge/.env。
选择来源模式
三种模式位于同一张环境卡。模式和 pythonPath 一起保存。更新 会沿用所选模式。
| 模式 | 来源 | 刷新行为 |
|---|---|---|
| 内置源码 默认 | 来自本插件、固定版本的 virtuoso-bridge-lite/ git submodule;不访问工具仓库。 |
使用固定提交。submodule 缺失或未初始化时会直接报错,提示执行 git submodule update --init virtuoso-bridge-lite(并给出固定提交)。npm 用户不会遇到这种状态。 |
| 本地开发仓库 | 从 source.localRepoPath 以 editable 方式安装。 |
代码修改在下次运行时启动时生效。打包元数据变化时用 修复 重新安装。 |
| Git 仓库 | 按 source.repoUrl、source.gitRef 克隆到 profile 数据目录后安装。 |
更新 会重新拉取这个 ref。 |
无论哪种模式,首次安装时 pip 都需要正常的包索引。不同的只是工具仓库的访问方式。
保存连接并启动
连接是运行时启动所依据的地址和权限。固定端口守护进程和自动会话守护进程查找端点的方式不同,连接与凭据 一章专门讲这个选择。
- 在 服务器连接 里新增一行,或让智能体调用
virtuoso_bridge_runtime的save_connection。新增一行或修改现有行的 SSH 目标,都会请求用户批准,除非会话具备完全权限。 - 点击 启动,或调用
start动作。固定端口启动会先探测配置的守护进程端口;若有已签名的守护进程应答,运行时直接挂接,跳过部署。 - 读取运行时状态,而不是只看一行日志。
- 状态为
waiting时,在目标空闲 CIW 中执行打印出的load("...")行。健康轮询随后把运行时转为running;守护进程一应答,加载提示即消失。
运行时会报告 starting、connecting、waiting 和 running。停在 waiting,说明网络侧已经通了,只差 CIW 去加载那行打印出来的 setup;到了 running,说明守护进程已经应答。运行时 列出全部状态,包括 needs-trust 和 error。
load("/path/to/virtuoso_setup.il")
路径以部署时打印出来的为准。直接复制那一行,别手敲路径。Host 每 20 秒检查一次状态;守护进程没应答时,还会检查 X11 弹窗。
部署只准备并上传 bootstrap,然后打印 load("...") 行。加载这一步要由人在空闲 CIW 中完成。重连或普通重启不会部署文件,也不会重新加载 setup。在你加载 setup 之前,运行时一直停在 waiting。
验证首次运行
virtuoso_bridge_runtime 的 status 动作返回一份紧凑摘要:环境就绪情况、连接端点、运行时状态、守护进程与实例状态、已关联智能体,以及正在执行的操作。冗长的安装日志、来源与 venv 调试路径、隧道内部信息和完整 traceback 都留在 UI 里;完整状态以 UI 为准。
| 字段 | 何时读取 |
|---|---|
setup.installed、setup.venvReady | 确认环境就绪。值为 false 时先安装或诊断,不要先怀疑主机。 |
state、connectionStatus | 读取运行时阶段和连接判定:ready、no-response、auth-failed、unreachable 或 unknown。 |
daemon、daemonProbe | 查看配置端口上有什么应答:探测状态 ready、no-listener、legacy、auth、timeout。 |
setupHint | 找到 load("...") 行。仅在首次就绪前存在,守护进程响应后消失。 |
instance | 自动会话:选中的端口、Virtuoso pid、work_dir 和用户。 |
attach | 固定模式:挂接了已签名守护进程、跳过部署时,给出 attached、port 和 setupPath。 |
health、dialog、errorSummary | 守护进程是否响应、阻塞弹窗的标题,以及失败的阶段、消息和提示。 |
agents、activeActions | 哪些会话已关联,哪些操作仍在运行。 |
然后用最小的调用证明守护进程有应答:
virtuoso_bridge_api({
action: "call",
target: "client",
method: "execute_skill",
args: ["1+1"],
description: "Check the daemon answers"
})
running 表示 execute_skill("1+1") 已通过守护进程返回结果。如果调用有返回值但 CIW 打印了警告,先读结果附带的 CIW 块,再断定调用没生效。
测试 报告四层结果:SSH、远端 Python、暂存根目录和守护进程端口;运行时停止时也能执行。启动 负责隧道和 sidecar。连接检查的细节见 连接与凭据。
完整状态在右侧边栏的 dsh-virtuoso-bridge 标签里:连接状态、守护进程与健康摘要、远端项目工作目录、弹窗警告和智能体活动。composer 状态点已连接时为绿色,等待或阻塞时为黄色,出错时为红色;会话有操作正在执行时呼吸绿色。会话没有活动运行时,不显示状态点。
带 waitMs 的 status 会等进行中的启动落定,或等到预算耗尽。启动后的下一步通常就是这种带等待的 status,而不是 sleep。
后续步骤
接着读 连接与凭据,了解字段和主机密钥信任;读 智能体工具,了解工具能力。运行时 一章讲状态与架构。
本章正本:docs/plugin-guide.md 第 3–7 节;根目录的 README.md 只是简介。