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（作业、文件夹、流程、包、计算机、用户、角色、许可证、资产、队列、存储桶、库、触发器、Webhook） |
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 旧版 — 仅适用于 Windows 的 uipcli.exe 包装器，用于尚未移植到跨平台 rpa 的 Studio 命令（“调试”、“验证”、“查找活动”、“查找包”、“类型定义”、“包”）。请参阅uip rpa 旧版。 |
eval | @uipath/eval-tool | 对照 Orchestrator 流程对已部署的包进行运行时评估（评估程序、评估集、评估、计划）。独立包，不是 or 的子命令。 |
platform | @uipath/platform-tool | 平台 — 租户许可、用户捆绑包、组规则、消耗性资源 |
admin | @uipath/admin-tool | 管理员 — 用户、组、机器人帐户、外部应用程序、SMTP、授权、IP 限制、组织、租户、VPN 网关、资源目录、审核 |
gov | @uipath/gov-tool | 监管 — AOps 策略、访问策略、合规包 |
agenthub | @uipath/agenthub-tool | AgentHub — MCP 服务器注册、工具、远程 A2A 智能体 |
ah | @uipath/automation-hub-tool | Automation Hub — 概念、管道、分类、用户 |
aops | @uipath/aops-tool | StudioAdmin AOps — 连接、存储库、项目、解决方案、管道、执行 |
coder | @uipath/coder-tool | Coder — AI 编码智能体（仅限预览版） |
context-grounding | @uipath/context-grounding-tool | 上下文基础 — Python Bridge |
conversational | @uipath/conversational-tool | 对话 — 聊天、智能体、对话历史记录、中继 |
function | @uipath/function-tool | 函数 — 构建、服务和发布 JS/TS 和 Python 函数 |
guardrails | @uipath/guardrails-tool | 防护栏 — BYO 防护栏配置、AI Trust Layer |
ixp | @uipath/ixp-tool | IXP — 智能文档处理（项目、分类、文档、部署） |
llm-configuration | @uipath/llmgw-tool | LLM 配置 — BYO LLM 连接、AI Trust Layer。请注意，包名称 (llmgw-tool) 与别名不匹配。 |
llm-gateway | @uipath/llm-gateway-tool | LLM 网关 — 列出可用模型。尽管名称相似，但与上述 llm-configuration 不同。 |
model-hub | @uipath/model-hub-tool | 模型中心 — LLM 网关路由配置 |
pm | @uipath/pm-tool | Process Mining — 应用程序、转换、数据提取 |
tasks | @uipath/tasks-tool | Action Center 任务 — 目录、注释、标签、元数据、数据 |
主机将其他所有内容视为“非工具”。此表格与当前的 TOOLS_WHITELIST 完全匹配 — 在此网站上的每个条目都有一个参考页面。有意缺少@uipath/flow-tool和@uipath/case-tool ：它们未独立列入白名单，而是@uipath/maestro-tool直接导入以注册其flow和case分支的依赖项（请参阅关于 UiPath CLI 的说明）。
哪些内容会自动安装，哪些不会
未预安装任何内容。新的npm install -g @uipath/cli仅会将主机放置在磁盘上。
在计算机上安装工具的两种方法:
-
首次使用时自动安装。首次调用前缀与白名单条目匹配的命令时（例如，安装 Orchestrator 工具之前的
uip or folders list），主机会从 npm 下载并安装@uipath/orchestrator-tool，然后运行您的命令。后续调用将直接使用已安装的工具，因此第二次运行速度很快。 -
显式安装。运行
uip tools install <alias>（或完整包名称）。结束状态相同；由于不需要自动安装步骤，因此在运行时速度更快。请参阅UIP 工具参考。
在 CI 运行程序和离线环境中使用显式安装，以便确定构建时间，并且作业中的第一个命令不会支付一次性下载成本。有关完整的权衡取舍，请参阅安装指南的自动安装部分。
CI=true不禁用自动安装— 不会在自动安装路径中的任何位置查阅该变量。实际的退出选项为UIPATH_CLI_DISABLE_AUTOINSTALL=true ，该参数会完全关闭隐式工具安装，包括每天检查每个工具的新鲜度（请参阅下面的版本解决方案）。如果没有它，实用的解决方法仍然是预安装您知道会使用的工具——当工具已经存在时，自动安装不是一个操作。
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/[email protected]之后运行uip tools update，将每个已安装的工具升级到 1.1.x行。 - 固定 CLI 可有效固定所有工具。
npm install -g @uipath/[email protected]，然后使用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
uip tools install [email protected]
uip tools update --name @uipath/orchestrator-tool --version 1.2.5
未选择在安装命令中使用 npm dist 标签（例如@beta的预览版本 — 该语法不存在。相反，CLI 范围内的发布通道是一个配置设置core.updateChannel ，使用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
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 为 stable（默认）或 preview 之一；对于从 dev 发布的 CLI 内部版本，存在第三个未公告的 main 渠道。方面稳定的工具中的预览命令是独立的；请参阅版本控制和稳定性。
CLI 还会自动使自身及其工具保持最新状态。每天一次，第一个符合条件的 uip 命令会在配置的通道上检查较新的 CLI 版本，如果存在，则在该命令上重新执行自身（永远不会在无人值守的情况下跨越新的“主要”版本）；单独来说，当您每天第一次使用时，每个已安装的工具都会在 CLI 自己的行中刷新为最新版本。如果无法完成，这两项检查将无法关闭，而不是静默跳过。使用 UIPATH_CLI_DISABLE_VERSION_SYNC=true 禁用两者。要自行冻结版本行而不是跟踪“最新”，请使用uip config set version <major.minor[.patch]>固定 — 请参阅uip config ，了解确切的version / updateChannel合同。
要在部署后验证计算机上有哪些工具版本， uip tools list --output json会打印每个已安装工具的名称、版本和命令前缀。将此与已知良好的快照进行比较，以捕获偏差。
主机如何加载工具
uip <alias> …运行时：
- 主机读取 argv，去除全局标志（
--output、--log-level等），并将第一个非标志令牌识别为潜在的工具别名。 - 如果别名与已安装的工具匹配，主机将按需加载该工具，并要求它注册其子命令。
- 如果别名位于白名单中，但未安装该工具，主机将运行自动安装（见上文），然后转到步骤 2。
- 如果别名不在白名单中，并且不是可识别的主机命令，则主机将失败并显示“未知命令”，并打印使用情况。
这就是整个加载模型。没有插件清单，没有注册表配置文件，没有用户可编辑的列表。主机包中内置的白名单是事实来源。