工具（插件）

UiPath CLI 是一个小型主机，包含一组可安装的工具。每个工具都是普通的 npm 包，它向主机注册一个顶级命令（及其子命令）。这是了解uip运作方式为何的最重要概念 — 哪些内容会自动安装，哪些内容不会自动安装，版本如何保持同步，以及为何uip --help在不同的计算机上显示不同的命令。

主机和工具

主机（ @uipath/cli ，即uip可执行文件）仅拥有一小部分关注点：

• 身份验证（ uip login 、 uip logout 、 uip login status和uip login tenant … ）。
• 会话和凭据管理。
• 工具生命周期 ( uip tools list / search / install / update / uninstall )。
• 编码智能体技能 ( uip skills install / update / uninstall )。
• 模型上下文协议网桥 ( uip mcp )。
• Shell 补全安装 ( uip completion )。
• 全局选项（ --output 、 --output-filter 、 --log-level 、 --log-file ）和 JSON 输出信封。

涉及 UiPath 表层的所有内容（包括 Orchestrator、解决方案、智能体、流程、Maestro、RPA 打包、Test Manager、Integration Service、Data Fabric、Insights、Traces、DocsAI、API 工作流、垂直行业解决方案、编码智能体和编码 Apps），都位于主机按需加载的单独 npm 包。

拆分原因：

• 独立的发布节奏— 无需重新发布主机即可交付 Orchestrator 工具，反之亦然。
• 安装占用空间较小—仅运行测试管道的用户不需要磁盘上的流或 Maestro 工具。
• 稳定合同— 工具通过版本控制的编程接口（命令注册、输出信封、上下文、遥测）与主机通信，而不是通过共享内部组件通信。
• 启动速度更快— 延迟加载工具代码。主机执行最少的操作来解析 argv 并识别相关工具，然后需要该工具的捆绑包一次。

自动安装白名单

一组 UiPath 拥有的工具位于自动安装白名单中。主机通过命令别名识别它们，并将别名映射到 npm 包：

别名	包	长名称
or	@uipath/orchestrator-tool	Orchestrator
solution	@uipath/solution-tool	解决方案
resource	@uipath/resource-tool	资源
rpa	@uipath/rpa-tool	RPA（Studio 打包、分析器、还原）
agent	@uipath/agent-tool	代理
codedagent	@uipath/codedagent-tool	编码式智能体
codedapp	@uipath/codedapp-tool	编码应用程序
maestro	@uipath/maestro-tool	Maestro
tm	@uipath/test-manager-tool	Test Manager
is	@uipath/integrationservice-tool	Integration Service
vss	@uipath/vertical-solutions-tool	垂直解决方案
api-workflow	@uipath/api-workflow-tool	API 工作流
df	@uipath/data-fabric-tool	Data Fabric
insights	@uipath/insights-tool	Insights
traces	@uipath/traces-tool	追踪
docsai	@uipath/docsai-tool	DocsAI

主机将其他所有内容视为“非工具”。附带两个额外的工具，但需要显式安装 — 它们不在自动安装白名单中：

• 流（ @uipath/flow-tool ，别名flow ）— 在运行uip flow命令之前使用uip tools install @uipath/flow-tool安装。
• RPA 旧版（ @uipath/rpa-legacy-tool ，别名rpa-legacy ）— 仅适用于 Windows 的uipcli.exe包装器，用于尚未移植到跨平台rpa Studio 命令（“debug”、“validate”、“查找活动”、“查找包”、类型定义、包）。使用uip tools install @uipath/rpa-legacy-tool安装。请参阅uip rpa 旧版。

哪些内容会自动安装，哪些不会

未预安装任何内容。新的npm install -g @uipath/cli仅会将主机放置在磁盘上。

在计算机上安装工具的两种方法:

1. 首次使用时自动安装。首次调用前缀与白名单条目匹配的命令时（例如，安装 Orchestrator 工具之前的uip or folders list ），主机会从 npm 下载并安装@uipath/orchestrator-tool ，然后运行您的命令。后续调用将直接使用已安装的工具，因此第二次运行速度很快。

2. 显式安装。运行uip tools install <alias> （或完整包名称）。结束状态相同；由于不需要自动安装步骤，因此在运行时速度更快。请参阅UIP 工具参考。

在 CI 运行程序和离线环境中使用显式安装，以便确定构建时间，并且作业中的第一个命令不会支付一次性下载成本。有关完整的权衡取舍，请参阅安装指南的自动安装部分。

备注：

目前无法禁用自动安装。没有可以跳过它的环境变量或标志 — 甚至CI=true也没有。实用的解决方法是预安装您会使用的工具；当工具已存在时，自动安装不会执行任何操作。在未来的 MINOR 版本中，这种情况可能会发生变化。

UiPath CLI 1.x不支持第三方工具。主机在安装时根据白名单进行验证，因此uip tools install my-company/some-tool会失败，并显示ValidationError 。公共扩展机制可能会出现在更高版本中；目前， uip仅加载上表中的工具。

工具在磁盘上的驻留位置

工具安装到 CLI 入口脚本、以 npm 为前缀的@uipath/文件夹中：

• 如果您全局安装了@uipath/cli ( npm install -g @uipath/cli )，则会在其旁边的$(npm root -g)/@uipath/<tool-name>/处全局安装工具。
• 如果您将 CLI 安装到本地项目中（在包中的npm install @uipath/cli中），则工具会在该项目的node_modules/@uipath/<tool-name>/中本地安装。

换句话说，工具遵循 CLI：全局 CLI、全局工具；本地 CLI、本地工具。此操作会自动处理，您无需将任何作用域标志传递给uip tools install 。

运行uip tools list以查看安装了哪些工具及其版本。运行npm root -g以查找计算机上的全局安装路径。

版本解决 — 工具跟踪主机

默认情况下，每个工具版本都固定到 CLI 的 major.minor 行。当您使用 CLI 1.0.x运行uip tools install or时，主机将解析版本以1.0.开头的最新@uipath/orchestrator-tool并安装。运行uip tools update时，每个已安装的工具都将升级到最新版本，仍在 CLI 的 major.minor 行中。

实际后果：

• 将 CLI 升级到新的次要版本分为两步。在npm install -g @uipath/cli@1.1.0之后运行uip tools update ，将每个已安装的工具升级到 1.1.x行。
• 固定 CLI 可有效固定所有工具。npm install -g @uipath/cli@1.0.3 ，然后使用uip tools update会在任何计算机上生成一组确定的工具版本。
• 主机和工具一起发布兼容的协议更改。针对 1.1.x 版本构建的工具可能会调用 1.0.x允许 CLI + 工具混合版本存在加载主机无法理解的工具的风险。

您可以覆盖默认设置，并显式安装特定的工具版本：

uip tools install orchestrator-tool@1.2.3
uip tools update --name @uipath/orchestrator-tool --version 1.2.5

频道（ alpha 、 beta ）通过 npm 的 dist-tag 机制获得支持，例如uip tools install orchestrator-tool@beta会选取最新的 Beta 版版本。稳定工具中的预览版命令均已独立标记；请参阅版本控制和稳定性。

提示：

要在部署后验证计算机上有哪些工具版本， uip tools list --output json会打印每个已安装工具的名称、版本和命令前缀。将此与已知良好的快照进行比较，以捕获偏差。

主机如何加载工具

uip <alias> …运行时：

1. 主机读取 argv，去除全局标志（ --output 、 --log-level等），并将第一个非标志令牌识别为潜在的工具别名。
2. 如果别名与已安装的工具匹配，主机将按需加载该工具，并要求它注册其子命令。
3. 如果别名位于白名单中，但未安装该工具，主机将运行自动安装（见上文），然后转到步骤 2。
4. 如果别名不在白名单中，并且不是可识别的主机命令，则主机将失败并显示“未知命令”，并打印使用情况。

这就是整个加载模型。没有插件清单，没有注册表配置文件，没有用户可编辑的列表。主机包中内置的白名单是事实来源。

后续内容

• UIP 工具参考— 每个uip tools命令的完整语法和示例。
• 安装 UiPath CLI — 安装主机；工具将跟踪。
• 控制工具自动安装— 不可选择退出的现实以及 CI 的安装前解决方法。
• 管理工具和技能— 日常工作流（升级、固定版本、检查偏差）。
• 技能— 用于教编码智能体使用uip并行系统。技能不是工具， uip skills是单独的命令组。
• 版本控制和稳定性— 如何在语义化版本下协调主机和工具版本。