版本控制和稳定性

UiPath CLI 1.0.0 遵循语义版本控制( MAJOR.MINOR.PATCH )。这将替换旧版.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已保留（目前 1.x 中没有命令会发出此参数），但已处理此参数的脚本将继续运行。

全局选项

--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

您可以覆盖特定工具的默认值：

uip tools install orchestrator-tool@1.0.2
uip tools update --name flow-tool --version 1.1.5

固定为何重要

工具通过受版本控制的 TypeScript 合同与主机通信（命令注册、输出格式化、遥测、上下文）。如果合同在次要版本之间发生更改，则主机和工具必须一起移动。版本固定默认值可以确保它们执行，而用户不必考虑。

频道

主机可识别工具上的 npm dist 标签：

• latest — 稳定行（没有传递标签时的默认设置）。
• beta — 在稳定线之前构建预览版。
• alpha — 抢先体验的不稳定版本。

uip tools install flow-tool@beta
uip tools update --name flow-tool --version alpha

频道是工具级别的，非主机级别的。您可以将稳定的主机与用于特定工作流的测试版工具混合使用 — 请注意，该组合尚未经过充分的测试。

基于命令的稳定性

单个命令和标志带有三个稳定性标签之一。它们可以在每个命令的参考页面的顶部找到。

标签	意义
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

这为您提供了一个可在上游版本发布后继续存在的可重现环境。在每次 CLI 提升后，使用管道的集成测试进行重新验证；请参阅发行说明，了解已知的Data形状更改。

对于开发者工作站：

npm install -g @uipath/cli@latest
uip tools update    # after each CLI upgrade

可重复性较低，但更方便。

弃用周期

当命令或标志消失时，路径为：

1. 已宣布弃用— 该命令在其参考页面中标记为Deprecated ，并且引入弃用的次要版本的发行说明中列出了该命令。记录了替换操作。
2. runtime 警告— uip <deprecated-command> ...继续工作，但在标准错误 (stderr) 上发出警告。使用标准输出的脚本不受影响。
3. 在下一个主要版本中删除—将在下一个主要版本提升时删除该命令。在弃用和删除之间至少有一个完整的主要周期— 对于受支持生命周期中的任何管道来说，该周期足够长。

运行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或更早版本