UiPath CLI 语义版本控制合同，涵盖主要更改、次要更改和补丁更改，以及主机/工具兼容性矩阵。
UiPath CLI 遵循语义版本控制( MAJOR.MINOR.PATCH )，在版本 1.197.0 中正式发布。这将替换旧版.NET CLI 使用的基于日历的方案（2023.10、2024.10、2025.10）。此页面是合同 — 从一个版本到下一个版本您可以依赖的内容、可以更改的内容，以及主机和工具版本如何保持同步。
语义化版本在实践中的含义
| 嵌入 | 当它发生时 | 哪些内容可能会发生变化 |
|---|---|---|
主要（ 1.x.x → 2.0.0 ） | 对命令名称、标志语义或 JSON 信封的重大更改。 | 命令可能会被重命名或删除；标志可能已重命名或含义发生变化；信封的顶级字段可能会更改形状。发布任何主要版本之前，都有一个完整的弃用周期——已弃用的命令在上一个主要版本的最终次要版本中继续运行。 |
次要( 1.0.x → 1.1.0 ) | 新命令、新工具、新标志、新子命令。 | 仅在命令界面具有附加性。但是，JSON 信封内的Data的形式是特定于命令的，并且可能会发生变化— 添加了新字段，偶尔会重命名或嵌套字段。解析特定字段名称的脚本应在出现轻微变化时重新验证。 |
修补( 1.0.0 → 1.0.1 ) | 错误修复。 | 无记录的行为变化。更改行为的补丁将被视为补丁本身的错误报告。 |
没有--preview标志（与 Azure CLI 不同）。预览状态的命令已在其参考页面中标记，在次要版本中可能会发生变化，不会发出警告 — 请参阅下面的每个命令的稳定性。
稳定合同
以下内容在 MINOR 或 PATCH 版本中不会发生变化。根据这些概念自由编写脚本。
信封字段
每个命令都会在标准输出上发出一个信封，其中包含以下顶级字段：
| 字段 | 稳定性 | 意义 |
|---|---|---|
Result | 稳定 | Success、 Failure 、 ConfigError 、 AuthenticationError 、 ValidationError 、 TimeoutError 。 |
Code | 在“MAJOR”内稳定 | 特定于命令的成功标识符（ FolderList 、 SolutionPack等）。新代码可能会出现在新命令的次要版本中。 |
Data | 特定于命令 | 每个命令定义的有效负载形状。可能会在次要版本中添加字段。在极少数情况下，字段可能会在 MINOR 中重命名 — 查看发布说明。 |
Message, Instructions | 稳定 | 人类可读的错误文本。内容可能会因版本而异；状态和角色不会更改。 |
Context, Log | 稳定 | 可选字段。状态稳定。 |
详细信息请参阅信封输出格式。
退出代码
五层退出代码合同（0/1/2/3/4，加上用于用户取消的130 ）在主要版本中保持稳定。4 今天仅由 uip tm perf-scenario execute --wait 超时发出；更多长时间运行的命令可能会采用它，因此请将其作为“超时”进行处理。
全局选项
--output 、 --output-filter 、 --log-level 、 --log-file — 这四个标志在 MINOR 颠倒过程中保持稳定。可能会添加新的全局选项；如果没有主要版本，现有版本将不会被重命名或删除。
标准输出/标准错误分隔
标准输出是信封； STderr 是日志、进度和面向人的错误文本。这种分离情况适用于每个命令、每种格式和每个版本。
主机和工具版本
主机（ @uipath/cli 、 uip可执行文件）和每个工具（例如@uipath/orchestrator-tool ）作为独立的 npm 包发布，每个包都有自己的语义版本。它们经过协调，以便1.0.x版本的主机可以运行1.0.x的工具。
默认版本解决方案
当您在没有显式版本的情况下运行uip tools install <alias>时，主机会选择 MAJOR.MINOR 与 CLI 当前的 MAJOR.MINOR 行匹配的最新工具版本。将 CLI 从1.0.x升级到1.1.0 ，然后运行uip tools update会将每个已安装的工具转到1.1.x行。
npm install -g @uipath/cli@1.1.0
uip tools update # all tools → latest 1.1.x
npm install -g @uipath/[email protected]
uip tools update # all tools → latest 1.1.x
您可以覆盖特定工具的默认值：
uip tools install orchestrator-tool@1.0.2
uip tools update --name maestro-tool --version 1.1.5
uip tools install [email protected]
uip tools update --name maestro-tool --version 1.1.5
固定为何重要
工具通过受版本控制的 TypeScript 合同与主机通信（命令注册、输出格式化、遥测、上下文）。如果合同在次要版本之间发生更改，则主机和工具必须一起移动。版本固定默认值可以确保它们执行，而用户不必考虑。
更新渠道
主机及其工具解析到的内部版本由频道管理——这是一个 CLI 主机级别的设置，而不是在安装命令中传递的每个工具的 npm 标签。存在三个渠道：stable（默认）、preview 和隐藏的 dev。使用 uip config 进行设置：
uip config set updateChannel preview # persistent, affects every uip invocation
uip update --channel preview # one invocation only
uip config set updateChannel stable # back to stable
uip config set updateChannel preview # persistent, affects every uip invocation
uip update --channel preview # one invocation only
uip config set updateChannel stable # back to stable
每个渠道都映射到一个真实的 npm dist-标签：
| 频道 | 发布时间 | 注册表 | 距离标签 |
|---|---|---|---|
stable | 手动发布运行时间 release/* | npmjs | latest （对于低于 previous 的向后移植，则为 latest） |
preview | 推送到 release/* | npmjs，已镜像到 GitHub 包 | preview |
dev | 推送到 main | 仅限 GitHub 包 | dev |
系统接受 dev (uip config set updateChannel dev)，但系统会有意将 --help 和“有效值”排除在外列表 — 其存在，是因为 -dev.* CLI 在自己的行中解析工具，而不是作为选择加入的频道。
直接固定确切的预发行版本仍然适用于一次性版本 (uip tools install [email protected])，但 updateChannel 才是管理持续解决问题的因素 — 取消固定的 uip tools update 或自动安装始终会根据频道重新解析，而不是您添加的标签通过了一次。请参阅uip config以获取完整的updateChannel / version密钥引用。
自动更新
如果放任不管，uip 会不断地使自身处于最新状态 — 这默认情况下会发生，无需选择加入。
每日 CLI 同步
每天一次，第一个符合条件的命令会在已解析的频道上检查较新的 CLI 版本，安装该版本，刷新技能，并在新版本上重新执行原始命令— 以透明方式在调用中进行。它仅写入到 标准错误 (交互式终端上的微调框) 中，而永远不会更改命令的退出代码。手动 uip update 永远不会受到此每日门限的限制。
它永远不会在无人值守的情况下跨越“主要”版本。在没有版本固定的情况下，每日同步上限为其已在运行的“主要”版本 — 将 2.0.0 发布到 latest 不会在一夜之间静默升级 1.x 安装。它会宣布其拒绝的新版本，以便您可以有意选择加入：
uip update # explicit, unrestricted — crosses the major
uip config set version 2.0 # or pin the new line instead
uip update # explicit, unrestricted — crosses the major
uip config set version 2.0 # or pin the new line instead
同步会自动跳过某些上下文（CI 环境变量身份验证、单一存储库签出、Studio 捆绑安装、update/login/logout/mcp/completion/config/skills/help 动词，--version/--help，确切的 core.version 固定），并且可以通过以下方式完全关闭：
export UIPATH_CLI_DISABLE_VERSION_SYNC=true
export UIPATH_CLI_DISABLE_VERSION_SYNC=true
状态追踪~/.uipath/version-sync.json； uip login 从未涉及它。
每个工具的每日检查
另外，工具谓词每天第一次运行时，CLI 在运行 CLI 的 major.minor 行上为该工具执行一次注册表查找，并在加载工具之前安装最新的匹配内部版本 — 无需重新执行，因为工具会在同一个流程。此检查失败已关闭：如果查找或安装失败，则系统不会运行该命令（ Failure结果会要求您检查连接并重试），而无需风险运行过时的工具。UIPATH_CLI_DISABLE_VERSION_SYNC 和 UIPATH_CLI_DISABLE_AUTOINSTALL 都跳过此检查；确切的 core.version PIN 码也是如此。
基于命令的稳定性
单个命令和标志带有三个稳定性标签之一。它们可以在每个命令的参考页面的顶部找到。
| 标签 | 意义 |
|---|---|
| GA （默认；未标记） | 该命令包含在上述语义化版本合同中。它不会在主要版本中重命名或删除。 |
| 预览 | 该命令正在积极开发中。标志、默认值和输出形状可以在没有重大变化的情况下发生变化，不过重大变化的情况很少见，并且会在发布说明中宣布。仅当您准备在每个版本上重新验证时在生产中使用。 |
| 已弃用 | 计划在下一个主要版本中删除该命令。它会在 1.x 版本中继续运行，并在 STDERR 上发出警告。使用弃用说明中列出的后备方案。 |
这与 gcloud 使用的约定相同。UiPath CLI 不会将“预览”命令门控在“选择加入”标志后面，它们在--help中可见且可调用。
固定建议
对于 CI 管道：
# pin host version
npm install -g @uipath/cli@1.0.0
# pin each tool you use
uip tools install @uipath/orchestrator-tool@1.0.2 \
@uipath/solution-tool@1.0.1
# pin host version
npm install -g @uipath/[email protected]
# pin each tool you use
uip tools install @uipath/[email protected] \
@uipath/[email protected]
这为您提供了一个可在上游版本发布后继续存在的可重现环境。在每次 CLI 提升后，使用管道的集成测试进行重新验证；请参阅发行说明，了解已知的Data形状更改。
对于开发者工作站：
npm install -g @uipath/cli@latest
uip tools update # after each CLI upgrade
npm install -g @uipath/cli@latest
uip tools update # after each CLI upgrade
可重复性较低，但更方便。
弃用周期
当命令或标志消失时，路径为：
- 已宣布弃用— 该命令在其参考页面中标记为
Deprecated，并且引入弃用的次要版本的发行说明中列出了该命令。记录了替换操作。 - runtime 警告—
uip <deprecated-command> ...继续工作，但在标准错误 (stderr) 上发出警告。使用标准输出的脚本不受影响。 - 在下一个主要版本中删除—将在下一个主要版本提升时删除该命令。在弃用和删除之间至少有一个完整的主要周期— 对于受支持生命周期中的任何管道来说，该周期足够长。
运行uip <command> --help以查看某个命令是否已弃用；标签将显示在摘要中。
数据形状发生变化时
由于Data是特定于命令的，并且可能在 MINOR 版本中进行更改，因此提取特定字段 ( --output-filter "Data.Jobs[0].Key" ) 的管道是最受 MINOR 影响的管道。两种缓解措施：
- 在 CI 中固定
@uipath/cli（见上文）。验证新形状的时间由您选择。 - 防御性查询— 优先使用尽可能允许缺失字段 (
Data.Jobs[0].Key || '') 的 JMESPath 表达式；升级前请查看发行说明。
MINOR 中很少出现破坏性的Data形状更改，在更改的命令下的发行说明中标记为[Data shape] 。
观察变更位置
- 发行说明— 每个版本添加的命令、更改的标志和形状变化的摘要。
uip --version和uip tools list— 计算机上当前安装的内容。跨环境进行比较，以捕获偏差。- npm — 发布者上每个工具的包都会在其中列出分布式标签和发布历史记录。
另请参阅
- 输出格式— 合同描述的信封形状。
- 退出代码— 五层合同。
- 工具（插件） — 版本固定支持的主机工具模型。
- 发行说明— 更改内容和时间。
- 从旧版 .NET CLI 迁移— 如果您使用
2025.10或更早版本