工具（插件）

UiPath CLI 中的工具架构，介绍可安装的 npm 包如何使用新的顶层命令扩展主机。

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 (jobs, folders, processes, packages, machines, users, roles, licenses, assets, queues, storage buckets, libraries, triggers, webhooks)
solution	@uipath/solution-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
rpa-legacy	@uipath/rpa-legacy-tool	RPA Legacy — Windows-only wrapper around uipcli.exe for the Studio commands not yet ported to the cross-platform rpa tool (debug, validate, find-activities, find-package, type-definition, package). See uip rpa-legacy.
eval	@uipath/eval-tool	Runtime evaluation of deployed packages against an Orchestrator process — evaluators, eval sets, evaluations, schedules. Standalone package, not a sub-command of or.
platform	@uipath/platform-tool	Platform — tenant licensing, user bundles, group rules, consumables
admin	@uipath/admin-tool	Admin — users, groups, robot accounts, external apps, SMTP, authorization, IP restriction, organizations, tenants, VPN gateways, resource catalog, audit
gov	@uipath/gov-tool	Governance — AOps policies, access policies, compliance packs
agenthub	@uipath/agenthub-tool	AgentHub — MCP server registrations, tools, remote A2A agents
ah	@uipath/automation-hub-tool	Automation Hub — ideas, pipeline, taxonomy, users
aops	@uipath/aops-tool	StudioAdmin AOps — connections, repos, projects, solutions, pipelines, executions
coder	@uipath/coder-tool	Coder — AI coding agent (Preview build only)
context-grounding	@uipath/context-grounding-tool	Context Grounding — Python bridge
conversational	@uipath/conversational-tool	Conversational — chat, agents, conversation history, trunks
function	@uipath/function-tool	Functions — build, serve, publish JS/TS and Python Functions
guardrails	@uipath/guardrails-tool	Guardrails — BYO guardrail configurations, AI Trust Layer
ixp	@uipath/ixp-tool	IXP — Intelligent Document Processing (projects, taxonomy, documents, deployments)
llm-configuration	@uipath/llmgw-tool	LLM Configuration — BYO LLM connections, AI Trust Layer. Note the package name (llmgw-tool) does not match the alias.
llm-gateway	@uipath/llm-gateway-tool	LLM Gateway — list available models. A separate package from llm-configuration above, despite the similar name.
model-hub	@uipath/model-hub-tool	Model Hub — LLM Gateway routing configuration
pm	@uipath/pm-tool	Process Mining — apps, transformations, data ingestion
tasks	@uipath/tasks-tool	Action Center tasks — catalogs, comments, labels, metadata, data

The host treats everything else as not-a-tool. This table matches the current TOOLS_WHITELIST exactly — every entry has a reference page on this site. @uipath/flow-tool and @uipath/case-tool are deliberately absent: they are not independently whitelisted, but dependencies that @uipath/maestro-tool imports directly to register its flow and case branches (see the note on About UiPath CLI).

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

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

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

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

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

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

备注：

CI=true does not disable auto-install — that variable is not consulted anywhere in the auto-install path. The real opt-out is UIPATH_CLI_DISABLE_AUTOINSTALL=true, which turns off implicit tool installs entirely, including the daily per-tool freshness check (see Version resolution below). Without it, the pragmatic workaround is still to pre-install the tools you know you'll use — auto-install is a no-op when the tool is already present.

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

Preview builds are not selected with an npm dist-tag like @beta on the install command — that syntax doesn't exist. Instead, the CLI-wide release channel is a config setting, core.updateChannel, managed with uip config:

uip config set updateChannel preview   # opt into preview tool builds
uip tools install orchestrator-tool    # now resolves the preview line

uip config set updateChannel stable    # switch back

updateChannel is one of stable (default) or preview; a third, unadvertised dev channel exists for CLI builds published from main. Preview commands within an otherwise-stable tool are labeled independently; see Versioning and stability.

The CLI also keeps itself and its tools fresh automatically. Once a day, the first eligible uip command checks for a newer CLI version on the configured channel and re-executes itself on it if one exists (never crossing a new MAJOR version unattended); separately, each installed tool is refreshed to the latest version on the CLI's own line the first time you use it each day. Both checks fail closed rather than silently skip if they can't complete. Disable both with UIPATH_CLI_DISABLE_VERSION_SYNC=true. To freeze the version line yourself instead of tracking "latest," pin it with uip config set version <major.minor[.patch]> — see uip config for the exact version/updateChannel contract.

提示：

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

主机如何加载工具

uip <alias> …运行时：

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

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

后续内容

• UIP 工具参考— 每个uip tools命令的完整语法和示例。
• 安装 UiPath CLI — 安装主机；工具将跟踪。
• Controlling tool auto-install — UIPATH_CLI_DISABLE_AUTOINSTALL and the pre-install workaround for CI.
• 管理工具和技能— 日常工作流（升级、固定版本、检查偏差）。
• 技能— 用于教编码智能体使用uip并行系统。技能不是工具， uip skills是单独的命令组。
• 版本控制和稳定性— 如何在语义化版本下协调主机和工具版本。