uipath-solution

UiPath Solution — uip solution 生命周期

通过 uip solution CLI 界面创建、打包、发布、部署和管理 UiPath Solution 包（.uipx）。一个 Solution 会将多个自动化项目（流程、测试、Agent 项目、API 工作流）打包成一个可部署单元。库不属于其中之一——它会单独发布，至多声明为 Library 资源（开发 Solution § 步骤 2）。

使用 CLI。不要自行编写 Solution 操作的 REST 请求。 手动编写 HTTP 调用会遗漏 X-UIPATH-OrganizationUnitId 文件夹请求头、OData 筛选器格式、分页信封、pipelinesInstall 部署语义、重试行为，以及 Result/Code/Data 输出约定。CLI 是事实来源。

平台支持。 Solutions 可在 Automation Cloud 和自托管 Automation Suite 2.2510.0 及更高版本上运行；不支持 Standalone Orchestrator。可用项目类型因 AS 版本而异（Maestro 仅从自托管版本 2.2510.2 开始支持）。兼容性矩阵和按版本划分的项目类型表 → Solution 概览 — 平台可用性。

何时使用此技能

• 用户有一个 .uipx Solution，想要打包／发布／部署／激活／上传

• 用户想要创建新的 Solution（uip solution init）、添加或移除项目，或刷新 Solution 资源

• 用户想要处理 Studio Web 中已有的 Solution，或将其移至其他组织或租户——从 uip solution download 开始（从现有 Solution 开始）

• 用户要求设置 CI/CD 流水线，以构建、发布和部署 UiPath Solution

• 用户提到部署配置、环境晋级或激活已部署的 Solution

• 技能或主 Agent 检测到 .uipx 文件并将用户引导至此处

以下情况请跳过此技能：

• 任务是 PDD → SDD 架构／设计（sdd.md / pdd.md）——加载 uipath-planner。
• 可部署对象是单个非 Solution 包（例如一次性 RPA 库或 coded app）——这些对象使用 uip rpa publish / uip codedapp publish，并转至 uipath-platform 或相应的专用技能。
• 任务是非 Solution 的 Orchestrator 工作（文件夹、作业、资产、队列、IS 连接）——加载 uipath-platform。

CLI 界面探测

在会话中首次运行 uip solution … 命令前，探测 solution 界面，以判断 CLI 使用重命名前还是重命名后的命令：

uip solution init --help --output json

• 结果为 Success → 使用重命名后的 CLI（默认）。按参考文档使用命令和标志。

• 出现 unknown command／非零退出码 → 使用重命名前的 CLI。每次调用前都按下表转换。如后续出现 unknown command 错误，请重新探测。

• 出现 command not found / uip: not found / 'uip' is not recognized → 未安装 CLI。告知用户运行官方安装程序（macOS/Linux 上运行 curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash；Windows PowerShell 中运行 irm https://download.uipath.com/uipath-cli/install.ps1 | iex），然后运行 uip login；在这些步骤成功前中止操作。

重命名后（默认）	重命名前的等效命令
uip solution init <NAME>	uip solution new <NAME>
uip solution deploy run --parent-folder-path <PATH>	uip solution deploy run --folder-path <PATH>
uip solution deploy run --parent-folder-key <KEY>	uip solution deploy run --folder-key <KEY>
uip solution projects <VERB>	uip solution project <VERB>（重命名后单数形式仍可用，但已隐藏并弃用）
uip solution resources <VERB>	uip solution resource <VERB>
uip solution projects import <PATH>	uip solution project import --source <PATH>

所有其他 solution 子命令（pack、publish、deploy activate/status/uninstall、upload、resources …、projects add/remove/list）在两个界面中均未更改。

关键规则

1. 在会话中首次运行 uip solution 命令前，先探测 CLI 命令界面。 运行 uip solution init --help --output json。Success = 重命名后的 CLI（默认）；unknown command = 重命名前的 CLI——请按照上方的回退表进行转换。之后遇到任何 unknown command 错误时，都要重新探测。
2. 对于需要解析输出的 uip solution 命令，始终使用 --output json。JSON 格式紧凑且稳定；在非交互式运行中默认使用。
3. 始终使用 CLI，绝不要为解决方案操作自行编写 REST 请求。手写 HTTP 调用会遗漏 X-UIPATH-OrganizationUnitId 标头、OData 筛选器格式、分页封装，以及 pipelinesInstall 部署语义。只有在确认没有任何 uip solution 命令可执行该任务后，才使用 REST。
4. 绝不要手动编辑 resources/solution_folder/。它由 uip solution projects add / import 自动生成，并由 projects remove 自动清理。手动编辑会导致其与 .uipx 不同步，并引发静默故障。参见 scenarios/manual-edits.md。
5. .uipx 和 resources/solution_folder/ 中的项目集合必须始终一致。对比二者是检测状态损坏最快的方法。如果二者不一致，请通过 uip solution projects add/remove 修复，绝不要直接编辑任一侧。
6. 在执行 pack 或 upload 前运行 uip solution resources refresh。打包的工件文件和 userProfile/<userId>/debug_overwrites.json 必须反映当前云端状态。跳过刷新会导致发布过期的绑定。
7. 在解决方案内部创作的 AppV2 编码应用会注册到 .uipx 中。uip codedapp init 是解决方案端的脚手架入口点，请从**.uipx 解决方案内部运行它。它会写入 project.uiproj（ProjectType: "AppV2"）和 webAppManifest.json，将源文件放在 source/dist/ 下，并自动注册为 Type: "AppV2"，生成 resources/solution_folder/app/{Coded,CodedAction}/。uip solution projects add / uip solution projects import 也可处理现有的 AppV2 文件夹：二者都会读取 webAppManifest.config.isActionApp，以选择 Coded / CodedAction 子类型（对于没有清单的旧版文件夹，默认为 Coded）。uip solution pack 会将其打包；uip solution deploy run 会对其进行预配。独立编码应用遵循不同的**生命周期：使用 npx create-vite@latest（而非 uip codedapp init）搭建脚手架，在项目根目录下保留扁平的 dist/，并通过 uip codedapp pack → uip codedapp publish → uip codedapp deploy 进行部署。参见 /uipath:uipath-coded-apps。
8. 每次 CLI 修改后都要验证工件。读取 project.json、.uipx 或 uip solution deploy status 的输出，不要轻信退出代码。验证是额外步骤，不能取代用户要求的只读列表命令。如果用户要求显示或列出已注册项目、解决方案资源、软件包、部署或状态，请运行对应的 uip solution ... list/status --output json 命令，然后仅将检查文件作为次要的健全性检查。
9. 处于 Draft 状态的部署是失败的部署，不是等待中的部署。验证拒绝了某项资源，安装也未完成；它不会自行推进，也无法激活。查看失败原因：由于每次部署都会等待其运行结果，所有 Feed 上的失败详情中的 Instructions 都会包含 Validation: / Conflicts:；使用 deploy config set / link 修复后，使用相同的 --name 和 --package-version，通过 deploy run --config-file <file> 重新运行。草稿存在期间，它会占用该部署：任何其他版本都会被拒绝，包括 deploy upgrade，除非通过上述方式完成草稿，或将其丢弃（使用 deploy upgrade <draft-key> --discard-draft，或在 Orchestrator 中删除草稿）。若要查看该部署，请使用相同的 Feed 标志运行 deploy list；不指定 Feed 时会按租户范围查询，且完全不会显示 Personal Workspace 或文件夹 Feed 的条目。参见 A deploy that stops in Draft。
10. 用链接替换已安装资源时，必须获得明确同意。当 deploy run 配置文件（deploy config link）或 deploy upgrade 中的新版本链接了部署已安装的资源时，服务器会删除已安装的副本及其数据。较新的服务器会先询问，而较新的 CLI 版本随后会停止并显示 Deploying '<name>' will permanently delete … installed resource(s) replaced by links: <kind> '<name>', …（deploy upgrade 时显示 Upgrading …；ErrorCode: invalid_argument，这些资源也会出现在 Data.PermanentDeletionResources 中）。此时没有安装任何内容，且本次尝试会保留为待处理草稿。这不是需要修复的配置错误：只有在用户希望删除这些副本及其数据时才予以确认，然后使用 --acknowledge-permanent-deletion 重新运行相同的命令；对于 deploy upgrade，绝不要同时使用 --discard-draft，因为这会丢弃待确认的链接。若要保留副本，请运行 deploy config unlink <file> <resource> 并重新运行（deploy run），或运行 deploy upgrade <draft-key> --discard-draft（deploy upgrade）。--yes 不代表此处所需的同意。参见 Replacing an installed resource with a link。
11. 绝不要自行在 deploy uninstall 中传入 --force。它会发送 forceUninstall: true，放弃尚未完成的作业，并永久删除被链接替换的已安装资源及其数据（它也会代替 --yes）。当卸载失败并显示 Message "…this deployment has uncompleted jobs; --force uninstalls anyway" 或 "…permanently deletes these resources and their data: '', …"（Data.JobsNotInFinalState、Data.PermanentDeletionResources、Retry: RetryWillNotFix）时，请向用户说明原因，只有在用户明确接受后才添加 --force。若要绕过 "…errors that --force cannot get past"（Retry: RetryLater），绝不要添加它；应在 Orchestrator 中解决该问题，然后不带 --force 重新运行。参见 When the uninstall is refused。
12. 要将部署提升到多个环境，请使用 uip login tenant set <tenant> 切换租户，并通过 --config-file <path> 传入每个环境对应的部署配置。同一个已打包的 .uipx 可部署到 dev/staging/prod，环境差异由目标租户和配置文件决定（使用 deploy config get 生成，再通过 config set / config link 编辑），而不是由不同的软件包决定。没有 -c <CONFIG_KEY> 标志。

工作流

UiPath 解决方案的典型生命周期：

1. init / project add  → Create solution, register projects (.uipx + resources/solution_folder/)
2. resources refresh   → Sync bundled artefacts and debug overwrites with cloud state
3. (optional) restore  → Resolve NuGet deps in place (incl. authenticated Orchestrator feeds); login first
4. pack                → Produce deployable .zip package
5. login               → uip login (if not already authenticated)
6. publish             → Upload packed solution to UiPath
7. deploy run          → Promote to Orchestrator (auto-activates by default)
8. (optional) activate → Use --skip-activate on deploy, then activate explicitly

restore 是一种优化手段，并非必需步骤。 pack 会在内部还原依赖项，因此只有在希望提前解析依赖项时，单独执行 restore 才有用——最常见的情况是在 CI 中（login → restore → pack），以便在耗时更长的打包开始前，快速发现源中缺少依赖项。restore 只接受 <solutionPath>（包含 .uipx 的解决方案目录，或 .uis 文件），会就地解析依赖项，且不会生成包。要访问私有 Orchestrator 源，它需要经过身份验证的会话，因此请先运行 uip login。

解决方案流程中的 AppV2 编码应用通过 uip solution 处理，而不是直接使用 uip codedapp。 当编码应用项目在 .uipx 中包含 Type: "AppV2" 时，uip solution pack 会将其 .nupkg 打包，uip solution deploy run 会在部署文件夹中对其进行配置——无需单独执行 uip codedapp pack / publish / deploy 步骤。独立编码应用（通过 npx create-vite 在任何解决方案之外创建，项目根目录下有扁平的 dist/，且没有 project.uiproj / webAppManifest.json）则使用直接的 codedapp 流程。有关独立应用生命周期，以及如何通过 uip codedapp init 在解决方案中创作 AppV2 项目，请参阅 uipath-coded-apps。

同一源代码的两种不同分发路径：

• pack → publish → deploy run — 将带版本号的包发布到 Orchestrator。
• upload — 将解决方案推送到 Studio Web，仅用于基于浏览器的调试。不会生成已发布的包，也不能通过 deploy run 进行部署。

身份验证是前提条件。开始任何工作前，请检查 uip login status --output json；如果尚未登录，请让用户运行 uip login（交互式浏览器流程）。有关完整的身份验证选项（交互式 OAuth、客户端凭据、切换租户），请参阅 uipath-platform。

此技能是由 SDD 驱动的构建流程的最后一步：uipath-planner 生成 SDD 并导出任务列表后，实施专家会构建项目，随后在此处打包并交付 .uipx。

从现有解决方案开始

如果解决方案已存在于 Studio Web 中，请下载其源代码，而不是重新创建：

uip solution download <solution-id> --destination <dir> --extract --output json

• <solution-id> 是 Studio Web 解决方案 GUID。如果用户尚未提供，请向其索取。
• 在 Data.ExtractedTo 中工作。该目录包含 .uipx 和项目文件夹。请先阅读其中的 AGENTS.md / CLAUDE.md；如果存档中没有这些文件，--extract 会添加它们。请解压到新建或空的文件夹中：--extract 会覆盖现有文件，因此在已编辑过的副本上重新运行会丢失这些修改。请先与用户确认。
• 解压后的 .uipx 会保留 Studio Web 的 SolutionId，而 uip solution upload 会覆盖你当前登录的组织中具有该 ID 的解决方案；如果不存在，则会导入一个新解决方案（开发解决方案 § 上传如何根据云端内容决定导入还是覆盖）。若要将解决方案移至其他组织或租户，请登录该组织或租户后执行 upload，或在那里依次执行 pack → publish → deploy run。

参考导航

文件	用途
解决方案概述	什么是解决方案、.uipx 清单、文件结构、生命周期图、命令树

| 开发解决方案 | uip solution init / project add / import / remove / resources refresh / resources add / resources remove / resources edit；经过实际验证的注意事项 |

| 打包与部署 | restore / pack / publish / deploy run / feeds list，指定非租户 feed（--feed / --personal-workspace）、部署配置、CI/CD 流水线模式 | | 激活与管理 | deploy activate / status / upgrade / uninstall / delete、原地版本升级、环境管理 | | 场景索引 | 失败模式和边缘情况——手动编辑、共享资源、虚拟资源、名称冲突 |

反模式

1. 为 pack、publish、deploy run 或 activate 手动编写 REST 调用。 uip solution CLI 能正确处理身份验证、文件夹标头、流水线语义和分页。只有在确认没有命令能完成任务后，才考虑使用 REST。
2. 直接编辑 resources/solution_folder/。 此目录会自动生成和清理。手动编辑会导致其与 .uipx 不同步。请改用 uip solution projects add/remove。
3. 在 pack 或 upload 前跳过 uip solution resources refresh。 这会打包过时的绑定和调试覆盖状态。
4. 对已在 .uipx 中注册的 AppV2 项目运行 uip codedapp pack / publish / deploy。 注册为 Type: "AppV2" 后，编码应用就属于该解决方案——由 uip solution pack / uip solution publish / uip solution deploy run 处理。直接运行 uip codedapp publish 会绕过解决方案的部署配置（外部客户端 ID、路由名称、操作架构），并创建重复注册。只有对使用 npx create-vite 搭建的独立编码应用，才直接使用 uip codedapp（目录树中没有 .uipx，也没有 project.uiproj / webAppManifest.json）。
5. 为每个环境创建新的 .uipx，而不是使用部署配置。 同一个打包后的解决方案可以通过每个环境各自的 --config-file 部署到开发/预发布/生产环境（并通过 uip login tenant set 指定目标租户）。为不同环境使用不同的 .uipx 文件会破坏版本跟踪。
6. 将 uip solution upload（Studio Web）用作部署途径。 上传仅用于基于浏览器的调试——它不会生成已发布的包，也无法通过 deploy run 推广。实际部署请使用 pack → publish → deploy run。upload 还会将解决方案放入 Studio Web 的 Cloud workspace 选项卡，而非 Local 选项卡；SW 的 Local 选项卡是无法通过 uip solution 访问的独立注册项。
7. 仅凭退出代码判断变更结果。 务必检查产物（project.json、.uipx、部署状态）——非零退出代码可能表示仅完成了部分操作，而零退出代码也可能掩盖警告。