# @ai-workbench/connect 中文文档 规范地址：https://npmcn.com/package/%40ai-workbench/connect/ 版本：0\.7\.39 npm 元数据更新时间：2026-11-07T08:03:02.795Z 中文译文更新时间：2026-11-07T08:03:34.554Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ai-workbench/connect 原文对照：https://npmcn.com/package/%40ai-workbench/connect/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.5 MB，129 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=24\.13\.1 - 运行依赖：1 个 - peer 依赖：@deepseek-ai/cordis ^4\.0\.4，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-host-directory-picker-native \>=0\.2\.0-rc\.2 \<0\.3\.0-0 - 首次发布：2026-10-21T16:00:51.950Z - 最新版本发布：2026-11-07T08:03:02.633Z - 近 30 天下载量：4123（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：25（近 12 个月 25 个） ## 中文简介 查看远程主机连接状态并管理 Claude/Codex 登录。 ## 安装 ```sh npm install @ai-workbench/connect ``` 也可以使用：`pnpm add @ai-workbench/connect`、`yarn add @ai-workbench/connect`、`bun add @ai-workbench/connect` ## README 员工一次安装：在官方 DSH「插件 → 添加插件」输入 `@ai-workbench/workbench`。已分装 network、connect、remote-agent 的，先移除三者，再装总包。 本轮总包0.1.5精确锁定 network 0.4.11 / connect 0.7.39 / remote-agent 0.8.30；管理员按[总包发版说明](https://npmcn.com/package/%40ai-workbench/connect/packages/workbench/README.md)重新生成并核验固定 tgz 与 SHA。工人不 publish。 connect 0.7.39：DSH 版本声明由精确版本改为范围 `>=0.2.0-rc.2 <0.3.0-0`（peer 与 `engines.dsh` 同值），不再随 DSH 小版本被拒装。 connect 0.7.37：高级内容沿主体原生行与官方折叠/按钮；导入实际请求覆盖入网激活到连接确认，期间中性显示，结束后保留最终失败原因，不加延时。总包0.1.3按已发布的N0.4.9/L0.7.37/X0.8.29生成。 单独安装 connect：在官方 DSH「插件 → 添加插件」中选择编排已核验的 tgz 绝对路径，或输入编排已发布的精确包版本。发布由编排执行。 # 远程主机连接插件（L） 员工按插件名安装/更新，沿官方pnpm的24小时成熟期；未满24小时选已成熟旧版。不预置 `@ai-workbench/*` 发布时间例外，不改员工profile。验收或紧急修复由编排提供精确版本，兼容子包同批发布。历史D17诊断仍留在docs/evidence，旧scope例外不再是当前安装前置。 ## 0.7.36 · 设置、身份复用和工作位置 重装后重新导入同一资料，源authkey已被N按合同清理时，L仍把不含authKeyFile的配置交N.activate，由N先验证已保存身份。L不读身份/journal或密钥字节；只有N明确NEED\_ENROLLMENT才显示缺凭据，密钥明确拒绝才要求领取新凭据，空/权限/链接异常仍拒绝。N的配置路径/摘要、nodeName和默认值变更可能ENROLLMENT\_MISMATCH，本单不迁移或绕过它；真实重装由编排leo复验。 设置页沿原生通用设置的标题/灰字说明/右侧官方按钮和细分隔线，摘要为一行说明；登录内容与一次粘贴协议保留，高级使用官方DisclosureRow默认折叠。 S0.4.25资料可含workspaceSources=\["host","local"\]、\["host"\]或\["local"\]。L只保存/呈现该非秘密字段，缺字段按两者显示，不补写旧源包/旧登记。添加工作区只显示允许来源，单来源直接进入并灰字说明。**这是员工界面限制，不是安全边界**；不改变既有工作区、后端选择/主机/session/bridge/policy或执行能力，不改X/N/S。 ## TLS证书错误导致安装或组件下载失败（D25） 员工看到此类失败时：**连接被截获，可能连不上主机。** 官方插件安装尚未成功时，L还没有运行，无法接管或替换官方pnpm错误；请把官方安装界面的报错交给管理员。0.7.30已删除登录组件下载；本节仅保留官方插件安装时的诊断。 管理员识别：保留pnpm报错原文，特别是 `CERT_HAS_EXPIRED`（常伴 `certificate has expired`）、`UNABLE_TO_VERIFY_LEAF_SIGNATURE`（日志可能只显示 `UNABLE_TO_VERIFY…`，常伴 `unable to verify the first certificate`）、`SELF_SIGNED_CERT_IN_CHAIN`、`DEPTH_ZERO_SELF_SIGNED_CERT` 或 `ERR_TLS_CERT_ALTNAME_INVALID`。这些分别提示证书有效期、信任链或目标域名验证失败；错误码本身不能证明网络截获，也可能是服务端证书、设备时间或本机信任链问题。 在**出现问题的员工网络**，由管理员执行以下只读诊断；员工不需安装工具或填写技术参数。这只查看npm站点公开证书，不下载或安装软件： ```sh openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org -showcerts -verify_return_error /ai-workbench-connect/ssh/m-<本次随机目录>/c`；L 根、ssh 父目录及随机目录均为当前用户独占 0700，拒绝符号链接或宽权限。SSH 以当前 profile 为 cwd，ControlPath 使用该 profile 内的相对路径，避免长路径超过 macOS Unix socket 路径长度；不借用其他插件、profile 或员工的 master。当前目标完整参数变化、连接 instance/epoch/phase 变化、取消当次请求、profile 卸载会使旧浏览流失效；关闭只操作本实例的精确目录/master，不扫描或删除其他 socket。浏览进程随当前 profile 浏览连接存活，无后台轮询、总时限或自动重放；关闭目录弹窗本身不结束 profile 连接。 每页返回后在主机内预取本页可读且可进入的直接子目录首屏，只一层，不递归、不读取文件内容。单页仍按 `workspaceLocations.pageSize` 分页；预取缓存合计沿用 `commandOutputMaxBytes` 字节预算，放不下的不缓存，不截断页面。缓存仅存当前浏览进程内，下一页/目录切换会替换，创建、连接失效或卸载会清除。下一次实际点击先重验缓存目标的规范路径、身份、权限与目录时间戳，并刷新本页子条目的身份/权限；变化时重新列当前路径，预取失败也在实际点击时鲜查，不拿旧错误/旧规范路径替代。传输或协议错误明确失败，不换路径、不降级代理、不重试。 ## 0.7.30 · 默认浏览器登录 在设置 → 远程主机连接点「登录 Claude」，插件用系统默认浏览器打开主机官方CLI生成的授权页。完成网页登录后，在Claude页面复制授权码，回到「Claude（远程主机）」行粘贴并点「完成登录」。码仅在本次内存与受保护POST正文、SSH stdin中交接，不写进命令参数、日志或状态。码不属于本次登录则明确失败；主机未确认成功时说明失败，可立即重发。登录失败后重新查官方状态，未登录重新显示按钮；无法核实保留入口并先检查再授权。 Codex保持官方设备码登录，设备码在本设置行显示，网页用系统默认浏览器打开。取消、断线或本次结束只清本次CLI与输入状态，不关闭员工浏览器。删除Electron登录小窗口、独立userDataDir、下载/缓存/ZIP/来源/进度/IPC设置；不自动删除旧员工缓存。无新设置，仍保留 `helper.remoteKillGraceMs=1000` 与 `helper.loginOutputMaxBytes=1048576` 两个主机CLI预算。0.7.31仅支持Mac，直接用系统 `/usr/bin/open` 和独立URL参数打开默认浏览器；公开state/code\_challenge允许放argv，授权码仍只经stdin交主机CLI。非Mac返回现有平台不支持失败。 登录状态属于主机系统用户；第二台设备先检查，已登录直接使用，未知不启动授权。只在本人点击且确认未登录后发起，本次CLI/PKCE/state/stdin独立；无主机全局锁、1455监听或额外隧道。Codex设备码有效期由官方CLI管理，插件不加总授权超时或重试。 ## 0.7.25 · owner减法 工作区只有本机或远程主机两种来源。每轮开始核实一次当前位置，提交前核一次会话与位置；目录或连接本轮失败，恢复后下一轮照常核实，不保存永久撤销/失败锁存。换来源需要新会话；旧测试会话不迁移。 本插件不执行任何Git操作，也不要求所选文件夹是仓库；不默认创建同名主机目录。旧映射确认、首次说明回执、每轮持久接纳账本和详情送达闸门已删除。 「会话技术详情」展开读取本profile的ai-workbench-connect/conversation.log本机日志。记录尽力而为，失败只留一行说明，不影响用户轮；无逐条回执、分页列表、送达核对、第二套连接前详情或覆盖官方Config的管理员设置面板。调用方先脱敏，不写凭据。 持续断线显示已持续的分钟数和“网络恢复后会自动重连；你可以先检查本机网络”，不再按30秒升级找管理员。只有明确需要管理员处理的原因才作对应说明。已删administratorAfterMs和详情maxEventBytes/pageSize孤儿设置；其他Config不变。 ## 统一目录选择器（0.7.24） 在 DSH 的“添加工作区”中直接选择本机或远程主机，两个目标使用相同的目录浏览/上级/选定操作。默认打开上次成功选定的目标和目录；无历史时是本机用户根目录，切换到远程时是主机员工用户根目录。目录失效会在选择器中说明并回到该目标用户根目录；连接失败保留具体原因。取消和浏览不会改记忆；正在提交选定位置时会明确提示并等待保存结果。 选择远程目录无需准备本机文件夹。插件在当前 profile 的 `ai-workbench-connect/remote-workspaces/<完整SHA256>` 建立空的本机身份映射，远端名称和文件不变，不同步、不存员工文件。注册原生工作区和持久绑定主机来源成功后才交给 DSH。成功映射保留；删除工作区或卸载不自动删除目录和旧历史。添加失败只影响本次，不保存失败锁存或 pending。若原生工作区列表有残留条目，员工可在 DSH 原生工作区管理中删除后重新选择，不要求管理员。插件不调用无条件删除；失败后保留私有唯一映射供下次显式选择复用，不自动删除目录，也不阻断下次选择。设置“远程主机连接 → 工作区文件来源”仍用于管理、刷新和查看错误，不自动改绑已有工作区。 具名设置 `workspaceLocations.pickerSlotPriority` 默认 `-10`，可在官方插件 Config 改为安全负整数。官方原生流程为 `0`，数值更低者显示；同优先级或被其他插件遮蔽会在本插件设置中明确提示。沿用 `workspaceLocations.pageSize`（默认100）、`enrollmentMetadataMaxBytes` 和 `commandOutputMaxBytes`，没有新增时间阈值、重试或目录数量上限。现有来源、原子提交、主机身份/目录复核与 pending 执行阻断是不可关闭的正确性要求。 ## 0.7.26 · 复用现成目录选择 本机通过官方 desktop.pick（与 DSH 添加工作区相同）或官方 uiWorkspace.pickDirectory 打开系统目录框，不再渲染本机目录列表。编排已裁定：本机起始目录由系统记忆，官方 API 不支持指定。不为指定起始目录另写界面或绕过官方 API。远程仍读取上次主机目录，无历史从员工主目录开始。browse 包仅导出插件 apply/inject，内部浏览组件不公开，故插件保留远程数据浏览并沿用 DSH 的面包屑、目录列表、新建文件夹、打开/取消文案；只在显式创建时建一层，不自动建目录或执行 Git。不替换 desktop directoryPicker、不改 DSH core。 安装仅用官方插件管理或应用自带 dsh plugin --profile desktop add；装后核 profile 的 node\_modules/@deepseek-ai 不存在，且 .plugin-manager/logs 有本次记录。禁止 profile 直接 npm install。 ## 0.7.27 · N0.4.9 精简消费 仅 N 明确返回 ENROLLMENT\_KEY\_REJECTED 时显示“开通链接已失效，请向管理员领取新的。”；ENROLLMENT\_REJECTED 表示已存设备身份失效，普通网络故障不冒充密钥作废。N 自己处理入网恢复；L 删除结果未知死映射、经主机下载/登录代理声明与适配。 不再生成 network.downloadMaxRedirects、network.proxyListen、network.httpMaxResponseHeaderBytes。读取已开通旧员工记录时仅在内存比较中忽略对应退役字段，不覆盖原记录/私有配置、不改变 N 使用的摘要；有效连接目标和设置仍须匹配。没有新增设置。 显式选本机直接打开官方系统选择框；首次打开仅通过既有 browse 读取上次设备目标，本机分支不列目录、不读上次本机路径。系统返回路径后才取得选择令牌并登记。本机起始目录由系统记忆，官方 API 不支持指定。远程保持上次位置→员工主目录。删掉目录响应额外核验层，失败按普通操作失败显示；下载进行中只留一句进度。 ### 设置页与登录交互（0.7.33） “远程主机连接”跟随 DSH 当前界面语言，显示连接资料、公司主机连接、Codex、Claude四项真实状态及剩余步骤。已导入后显示员工标识，不再要求重复领取资料；检查中不显示可以开始使用。目录选择器、工作区文件来源和技术详情收在默认折叠的“高级”中。 登录区内联显示完整可选中/复制的公开链接；系统打开默认浏览器较慢或失败时，仍可复制链接自行打开，也可点打开按钮。Codex显示官方CLI提供的一次性设备码和复制按钮；没有verification\_uri\_complete时只用CLI原基础链接，不拼接附码URL。Claude粘贴框为等宽文本、适应可用宽度，不限制授权码长度，粘贴去首尾空白，空值不能提交。授权码仍只经受保护POST正文和主机CLI stdin交接，不写日志/状态/argv。成功自动收起；本次失败说明原因并可重新发起。不新增设置、检查、轮询、重试或时限。 ## 常见问题 ### @ai-workbench/connect 是什么？ 查看远程主机连接状态并管理 Claude/Codex 登录。 ### 如何安装 @ai-workbench/connect？ 在项目目录运行 npm install @ai-workbench/connect，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.4）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-host-directory-picker-native（\>=0\.2\.0-rc\.2 \<0\.3\.0-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @ai-workbench/connect 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @ai-workbench/connect 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @ai-workbench/connect 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24\.13\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @ai-workbench/connect 可以商用吗？ @ai-workbench/connect 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @ai-workbench/connect 的下载量有多少？ 根据 npm 官方下载统计，@ai-workbench/connect 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,123 次，日均约 137 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ai-workbench/connect 还在维护吗？ 最新版本 0\.7\.39 发布于 2026/11/07（今天）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。