uipath-human-in-the-loop

Name: uipath-human-in-the-loop
Author: uipath

github.com/uipath开发17554 次安装今天更新

代码仓库

关于 uipath-human-in-the-loop

用于识别流程中的人工决策点，并为自动化添加人工参与步骤的 UiPath 技能。支持 Flow、Maestro、Case Management 和低代码 Agent，并依据流程情境设计任务结构。

主要功能

01识别人工决策节点
02通过对话设计任务结构
03支持 Flow 和 Maestro
04支持 Case 与 Agent
05提供决策记录指引

适用场景

01添加发票或采购审批
02升级处理低置信度结果
03审核 Agent 生成的通信内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/uipath/skills --skill uipath-human-in-the-loop

安装后在 Claude Code 中输入/uipath-human-in-the-loop确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

decision-capture-action-app-guide.md

hitl-casetask-action.md

hitl-node-apptask.md

hitl-node-coded-action-app.md

hitl-node-quickform.md

hitl-patterns.md

详细介绍

UiPath 人机协同助手

识别业务流程何时需要人工决策点，通过对话设计任务架构，并将 HITL 节点接入自动化流程——Flow、Maestro、Case Management 或 Agent。

**编码 Agent：**如需在编码 Agent 中接入 HITL，请使用 uipath-agents 技能——参见 skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md。

何时使用此技能

用户描述了审批关卡——发票审批、录用通知书审核、合规签核、采购订单授权
用户描述了异常升级——“如果置信度较低，就升级给人工处理”、欺诈警报审核
用户描述了回写验证——“Agent 写入 ServiceNow / SAP / CRM 前由人工审批”
用户描述了数据补充——人工填写自动化无法确定的缺失字段
用户描述了Agent 输出审核——“发送前审核 AI 生成的邮件 / RCA / 摘要”
用户描述了IT 变更或访问审批——CAB 关卡、运行手册签核、访问权限配置审核
用户描述了HR 或合同工作流——录用通知书审核、合同审批、解雇签核
用户描述了金融交易审批——付款放行、价格覆盖、超限费用
用户描述了客户沟通审批——Agent 起草的回复需经人工签核后才能发送
用户明确要求添加 HITL 节点、人工审核步骤或 Action Center 任务
用户正在构建任何必须由人工操作后流程才能继续的自动化
用户要求采集或记录决策（或将其馈送到 Decision Ledger），或者审核者确认或更正提案：使用以下引导式决策体验

引导式决策体验（选择启用）。 仅当请求要求采集决策，或描述审核者确认或更正提案时，才需在设计 Coded Action App 架构、QuickForm 或文档验证任务前阅读 references/decision-capture-action-app-guide.md。其他请求跳过此步骤，按常规路径构建。该指南根据请求设置开关：用户要求采集决策，或审核者确认或更正 Agent 或自动化提出的内容时，开启此开关。开启后，会在作者自有字段旁添加一组固定的决策字段，并将 UI 切换为每种界面各自的一种简洁布局（包含理由及权重菜单、不预先选择任何选项、随决策变化的最终详情、由理由组合而成的说明、带作用范围的“下次”选项，以及折叠的记录），且不会重命名作者的字段。QuickForm 会通过一个函数，为每个选择字段添加可选的 Why。绝不要询问是否启用；如果你主动开启了它，只需用一句话说明。

**不要将此技能用于：**在运行时管理、重新分配、升级或监控现有 Action Center 任务——这些操作请使用 uipath-tasks 技能。回答运行时任务管理问题时，只提供管理指导。切勿建议后续添加 HITL 节点、流程或自动化——即使提到了延迟或升级也不例外。

完整的业务模式识别指南请参见 references/hitl-patterns.md。

关键规则

切勿等待用户确认架构。 根据提示词和任何上游 .flow/caseplan.case 数据设计架构，编写节点，并在最终报告中醒目标明所选架构，方便用户之后调整。征求用户意见绝不是继续操作的前提——如果用户在场并提供了意见，就加以采用，但不要等待用户回复。只有在请求确实模糊到无法做出任何合理推断时，才停止并说明尚待确定的事项。（如果提示词已经指定字段、结果和输出结构，就绝不会模糊到无法处理。）
为 QuickForm 的每个结果连接其对应端口。 QuickForm 节点为每个结果都设有一个输出句柄，名称为 outcome-<outcome.id>——绝不是单一的 completed 句柄。outcome-completed 是占位符，仅在结果数为 0 的架构中存在；一旦 inputs.schema.outcomes 中有任何条目（包括随附的默认结果 Submit），它就会消失。HITL 节点只要有任何结果端口未连接，就会导致流程在该分支上永久阻塞。基于应用的（coded-action-app）节点则不同：无论应用自身有哪些结果，其端口始终为静态的 completed——不要向基于应用的节点添加 inputs.schema 块，否则会错误地将其切换为根据结果生成的端口。两种节点类型都绝不使用 output、success 或其他名称。
向现有流程中插入节点时，始终添加定义条目。 编写节点前，检查 workflow.definitions[] 中是否存在所选路径对应的 nodeType（QuickForm 为 "uipath.human-in-the-loop.quick-form"，基于应用的节点为 "uipath.human-in-the-loop.coded-action-app"）。如果不存在，就追加完整的定义条目及其 handleConfiguration 块。跳过定义会导致运行时无法识别节点句柄，连线检查也会失败。
添加节点后，重新生成 variables.nodes。 替换整个 workflow.variables.nodes 数组——不要追加。算法请参阅参考文档。
每次更改后都要验证。 写入节点和边后，运行 uip maestro flow validate <file> --output json。uip CLI 不接受 --format；使用该选项会产生 error: unknown option '--format'，并以退出代码 3 结束。
添加节点前先读取现有 .flow 文件。 了解已有节点，以及 HITL 检查点在流程中的位置。
每种节点类型只添加一次定义条目。 检查 workflow.definitions——如果其中已有 nodeType 匹配的条目，就不要重复添加。
生成新 ID 前先检查现有节点 ID。 从 .flow 文件读取 workflow.nodes[*].id，并选用下一个可用的后缀（例如 invoiceReview1，然后是 invoiceReview2）。
验证失败时绝不要报告已完成。 如果 uip maestro flow validate 返回错误，就根据 JSON 输出进行诊断并修复，然后再向用户报告。
通过 field.id 而非 field.variable 访问输出字段。 运行时结果对象以字段 ID 作为键——$vars.<nodeId>.output.<fieldId>。variable 属性只会创建工作流全局别名；它不会更改节点输出对象中的键，也不是下游脚本读取值的方式。
- 错误：$vars.legalApproval——这是全局别名路径，不是脚本访问路径
- 错误：$vars.<nodeId>.output.legalApproval——这里错误地使用了变量名称作为键
- 正确：$vars.<nodeId>.output.approved——使用 field.id（"approved"）作为键在每个下游脚本中，都应使用 $vars.<nodeId>.output.<fieldId>，其中 <fieldId> 是你在架构中为字段指定的 id——绝不要使用 variable 名称。
输入字段绑定路径使用上游输出键，而不是 HITL 字段自身的 id。 两者各不相同：HITL 字段 id 用于标识表单字段（始终为小写）；绑定路径键则是上游脚本 return 语句中使用的名称（保留驼峰命名）。如果脚本返回 { supplierName: "Acme" }，正确的绑定是 vars.fetchSupplier.output.supplierName——写成 suppliername（字段 id）会生成运行时不存在的路径。表单字段将为空；flow validate 不会检测到此问题。始终从上游脚本源代码中确定绑定键，而不是从你设计的 HITL 架构中推断。
下游脚本必须访问 $vars.<nodeId>.output。 HITL 节点之后运行的任何脚本节点都必须读取 $vars.<nodeId>.output（结果对象）——不能只依赖 $vars.<nodeId>.status。具体示例：const output = $vars.reviewNode1.output; const reason = output.reason;。即使主要路由使用 status，这也是必需的。
当请求要求记录决策，或审核人员确认或更正某项提议时，编写 Coded Action App 的 action-schema.json、QuickForm 架构或文档验证架构之前，先阅读引导式决策指南。首先打开 references/decision-capture-action-app-guide.md；该指南会根据请求设置决策开关，并在开关开启时列出需要添加的字段（proposedOutcome、proposedBy、involvement、nextTimeOptions、conditionOptions、含 weight 的 reasons、含 byDecision 的 fields，以及输出 rationaleText、decidingReasons、nextTimeScope、changes、record）。不查阅指南就编写架构会遗漏这些字段。指南还列出了应用必须遵循的 Human Context Capture 原则，以及 Coded Action App 必须包含的 @uipath/intrinsic-signals 标记和 intrinsicSignals 输出。对于其他请求，不要打开该指南：构建普通架构和应用，不添加任何决策字段。

步骤 0 — 解析 `uip` 二进制文件

UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip
$UIP --version

如果找不到普通的 uip 命令，后续所有命令中都用 $UIP 替代 uip。

**本地开发说明：**如果在 uipcli 仓库中操作，请将 uip 替换为 bun run start。

步骤 1 — 检测界面类型并查找 Flow 文件

按顺序运行以下检查：

# Check for a .flow file (Flow project)
find . -name "*.flow" -maxdepth 4 | head -5

# Check for a Case Management project — detect by content marker, not by filename.
# Project files are flat in the project dir (no content/ dir on disk). The generated
# sibling caseplan.case.bpmn carries the same marker; these patterns skip it. Edit caseplan.case.
find . -maxdepth 4 \( -iname "*.json" -o -iname "*.case" \) -print0 2>/dev/null | xargs -0 grep -l '"case-management:root"' 2>/dev/null | head -3

# Check for agent.json (Low-Code Agent project)
find . -name "agent.json" -maxdepth 4 | head -3

# Check for Maestro .bpmn (Maestro process)
find . -name "*.bpmn" -maxdepth 4 | head -3

找到	界面类型	添加 HITL 的方式

| .flow.ts 或 .flow 文件 | Flow | 通过 uipath-maestro-flow 技能，在 <Name>.flow.ts 中使用 hitl(...) 编写（hitl.md）；切勿将节点 JSON 写入已编译的 .flow——compile 会覆盖它 |

**Flow 界面（.flow.ts、.flow 或新建 Flow）——默认情况：到此为止。**将 HITL 请求交给 uipath-maestro-flow 技能处理：该技能会在 <Name>.flow.ts 中编写 hitl(...)（先反编译现有 .flow），然后进行编译（hitl.md）。切勿读取或手动编辑已编译的 .flow；下一次 compile 会覆盖它。以下步骤 2–6 适用于 Case、低代码 Agent 和 Maestro 界面。

如果用户提到了特定文件路径，请直接使用该路径。

如果不存在 .flow 文件且界面类型为 Flow，请优先搭建解决方案——Flow 项目必须位于解决方案内：

# Probe the solution verb once per session before scaffolding:
#   uip solution init --help --output json
# Success → use `solution init` (post-rename, default).
# `unknown command` → CLI predates the rename; substitute `uip solution new <SolutionName>` below.

uip solution init <SolutionName> --output json
cd <SolutionName> && uip maestro flow init <ProjectName>
# Creates: <SolutionName>/<ProjectName>/<ProjectName>.flow

Flow 文件路径为 <SolutionName>/<ProjectName>/<ProjectName>.flow（双层嵌套）。<SolutionName>/ 是解决方案目录（包含 .uipx 文件）；其中的 <ProjectName>/ 是 Flow 项目。按照惯例，<SolutionName> 和 <ProjectName> 通常是同一个字符串，但它们是两个不同的搭建参数。在解决方案外运行 uip maestro flow init 会自动为你搭建 <ProjectName>Solution/<ProjectName>/；先运行 uip solution init 则可自行指定解决方案名称（否则默认使用 <ProjectName>Solution）。传入 --skip-solution-registration 会留下单层的 <ProjectName>/<ProjectName>.flow 布局，导致 Studio Web 上传、打包和下游工具无法正常工作。

步骤 2 — 阅读业务上下文

阅读现有的 .flow 文件，了解当前节点和边。对 .flow 文件路径使用 Read 工具，然后确定：

位置——人工决策点应放在哪里（位于哪个现有节点之后）
人工需要查看的内容——上游节点生成的数据
人工必须返回的内容——下游节点需要的数据
可采取的操作——命名的结果按钮
表单类型：QuickForm（内联架构，节点类型为 uipath.human-in-the-loop.quick-form）还是 AppTask（已部署的代码应用，节点类型为 uipath.human-in-the-loop.coded-action-app）？

第 2b 步 — 主动建议 HITL

如果用户没有明确提到 HITL，请先扫描业务描述，查找以下信号，再继续：

信号	模式	人工检查点的重要性
“Agent 写入”“更新”或“发布到”外部系统	回写验证	防止向生产系统写入错误内容
“如果置信度较低”“不确定时”“边缘情况”	异常升级	Agent 无法自主解决
“批准”“审核”“签字确认”“四眼原则”	审批关卡	业务或合规要求
“补全缺失内容”“验证提取结果”“更正”	数据补充	自动化生成的数据不完整
“合规”“监管”“审计跟踪”	合规检查点	必须由人工签字确认

绝不要因此停下流程。 如果信号十分明确（明确要求批准、审核或签字确认），请添加 HITL 步骤并说明已添加，按以下格式表述：

“我注意到，你的描述中提到 [引用描述中的具体内容]。这是一个[模式名称]——如果没有人工审核，[简要说明可能造成的后果]。我会在此处插入一个 Human-in-the-Loop 步骤，让[人工角色]能够在自动化[继续/写入/发送]之前[执行操作]。”

说完后直接继续设计架构，不要等待回复。在最终报告中显著记录此决定，以便用户如有异议时移除此步骤。只有当信号确实含糊不清时（而不只是“没有明确提到 HITL”——上面的信号表本身就是判断是否含糊不清的依据），才跳过添加此步骤，并报告尚待决定的事项。

示例：

用户：“构建一个自动化流程，读取支持工单，使用 AI 生成 RCA，并更新 ServiceNow 中的工单。”

Agent：“我注意到，该自动化流程会将 AI 生成的内容直接写回 ServiceNow。这属于回写验证模式——如果 RCA 有误且无人审核，错误数据就会进入生产工单。我会插入一个 Human-in-the-Loop 步骤，让支持主管在应用更新前审核 RCA，并可选择进行编辑。”

第 3 步 — 选择任务类型

不同界面支持的选项有所不同。 不要在此停下流程——选择最符合界面和业务描述的选项，说明你的选择，然后继续。只有当用户实际在场且可以回复时才提问；在非交互式运行中，请自行推断并继续。

界面：Flow

根据以下信号推断合适的选项并说明你的选择——不要先搜索注册表，也不要等待用户选择后再继续。

#	选项	节点类型	描述
1	QuickForm	`uipath.human-in-the-loop.quick-form`	内嵌类型化表单——Action Center 根据你在此设计的架构渲染字段
2	New Coded Action App	`uipath.human-in-the-loop.coded-action-app`	在解决方案中搭建新的 React + TypeScript 应用——完全控制 UI
3	Existing Deployed App	`uipath.human-in-the-loop.coded-action-app`	引用已部署到 Orchestrator 的应用

默认选项：QuickForm。 除非请求明确提到已部署的应用、编码操作应用或自定义 UI 要求，否则选择 QuickForm——这些是唯一指向选项 2 或 3 的信号。说明你的选择，不要提问：“我会使用 QuickForm——它是内嵌式的，无需部署步骤，适用于大多数审批和审核任务。之后如有需要，你可以换成 Coded Action App 或现有已部署应用。”

所选选项	后续步骤
引导式决策体验（请求要求记录决策，或审核者更正提案）	阅读引导式决策体验，添加决策字段和引导式布局，然后将其接入为 New Coded Action App
QuickForm	阅读如何编写 QuickForm HITL 节点中的步骤 1–2，然后继续步骤 4
New Coded Action App	阅读如何搭建新的 Coded Action App，了解步骤 4c 的详情，然后继续步骤 4
Existing Deployed App — 请求中必须已指明应用	阅读如何接入现有已部署的 Action App，了解步骤 4b 的详情，然后继续步骤 4

回退规则——绝不要因此停下，改用备用方案并说明你的处理方式：

路径	阻碍	响应
Existing Deployed App	在 Orchestrator 中找不到应用，或未提供应用名称	回退到 QuickForm 并继续。说明：“我找不到（或未收到）已部署应用的名称，因此改用了 QuickForm。告诉我实际应用的名称，我就会替换它。”
New Coded Action App	源路径中没有 `dist/` 构建产物	回退到 QuickForm 并继续。说明：“源文件夹中还没有 `dist/` 构建产物，因此我暂时接入了 QuickForm——运行构建，然后在准备好后让我替换为 Coded Action App。”
New Coded Action App	未提供源路径	回退到 QuickForm 并继续。说明：“未提供应用源代码路径，因此我现在使用 QuickForm 接入了检查点。告诉我应用代码的位置，我就会将其替换为 Coded Action App。”
任何自定义应用	身份验证已过期（API 调用返回 401）	回退到 QuickForm 并继续。说明：“会话似乎已过期，因此我使用了 QuickForm，没有停下来重新进行身份验证。运行 `uip login`，准备好后让我替换为该应用。”

Surface: 案例

根据以下描述推断正确选项——不要先拉取注册表，也不要等用户选择后再继续。

#	选项	特征	描述
1	QuickForm（基于文件的架构）	独立的 `<TaskLabel>.hitl.json` 文件 + 操作任务中的 `hitlType: "quick"` 上下文条目	在与 `caseplan.case` 同目录的 `.hitl.json` 文件中定义结构化表单字段。Action Center 在运行时渲染字段。无需部署应用。
2	基于应用的操作任务	`data.name` 和 `data.folderPath` 为 `=bindings.<id>` 引用 + `data.actionCatalogName`	使用已部署的 Action Center 应用，并包含自定义输入／输出字段。要求该应用已存在于 Orchestrator 中。

默认：QuickForm。 除非请求明确指定了已部署的 Action Center 应用，否则选择 QuickForm。说明你的选择，不要提问：“我会使用 QuickForm——它设置最快，支持结构化表单字段，而且不需要部署应用。之后如果需要自定义 UI 布局，你可以升级为基于应用的任务。”

构建时与设计时。 案例管理中的 QuickForm 必须支持双向往返：此处写入的 JSON 是 Studio Web 案例设计器在设计时读取的内容，也是 uip maestro case validate 和 Action Center 在构建时使用的内容。写入后务必验证。

所选选项	后续步骤
QuickForm（基于文件的架构）	阅读 references/hitl-casetask-action.md — 路径 1，然后继续执行步骤 4
基于应用的操作任务 — 请求必须已指定应用	阅读 references/hitl-casetask-action.md — 路径 2，然后继续执行步骤 4

回退规则——绝不要因此停下，改为回退并说明处理方式：

路径	阻碍	响应
基于应用	在注册表或 `action-apps-index.json` 中找不到应用，或未提供应用名称	回退到 QuickForm 并继续。说明：“我没能找到（或没有收到）该应用，因此改用了 QuickForm。告诉我一个真实的应用名称，我就会替换进去。”
QuickForm	架构设计未通过验证（例如字段 ID 重复、缺少主要结果）	根据验证器的错误自行修复架构并重新验证。应用步骤 4b 中的检查。在最终报告中说明修复内容——不要暂停并先重新展示架构。
任意	身份验证已过期（API 调用返回 401）	回退到 QuickForm 并继续。说明：“会话似乎已过期，因此我改用了 QuickForm，没有停下来重新进行身份验证。运行 `uip login`，准备好后再让我替换为该应用。”

步骤 4 — 通用配置

绝不要因此停下——没有可用答案时，使用指定的默认值，将其写入节点，并在最终报告中注明默认值，以便用户更改。

| 超时 | 默认值：24 小时。如果描述说明或暗示了其他时长，则使用该时长。 | | 优先级 | 默认值：Low。如果描述说明或暗示存在紧迫性（例如“高优先级”“紧急”“时间敏感”），则相应使用 High 或 Medium。将选定值写入节点的 priority 字段——仅询问问题还不够；必须将该值写入节点。 |

步骤 4b — 架构设计韧性（QuickForm — 流程与案例）

设计架构时，在写入前应用以下检查——根据关键规则 1，不要等待用户确认。这同样适用于流程 QuickForm 节点和案例 QuickForm 操作任务——二者使用相同的 fields[] + outcomes[] 结构，以及相同的 direction 语义。

字段方向

根据人工如何处理该字段来选择方向：

信号	方向
“可以查看”“显示给”“只读”“显示”“供审核者参考的上下文”	`input`
“填写”“输入”“键入”“选择”“必须作出的决定”“批准”	`output`
“可以编辑”“可以更正”“预填但可编辑”“审核者可以调整的建议值”	`inOut`

inOut 表示该字段会根据上游节点预先填充，且人工可以在提交前修改。运行时会像输出字段一样，通过 $vars.<nodeId>.output.<fieldId> 暴露该字段。

字段类型

使用适合该字段的 JS/JSON 类型：string、number、boolean、date 或 file。这些是唯一有效值——不要使用 text。Case 还支持 datetime（不同于 date，用于完整的日期和时间值）——请参阅 hitl-casetask-action.md 中 Case 专用的类型表。

架构描述模糊或不完整

如果用户说“随便添加几个字段”或“按你认为合适的来”之类的话：

根据 .flow 文件（Flow）中可见的上游数据和下游需求，或根据 caseplan.case 中上游任务的 outputs[] 和 root.data.uipath.variables（Case），推断合理的默认值。
写入前明确展示建议的架构：“这是我建议的方案——如果你想修改，请告诉我。”
如果没有可绑定的上游数据（仅包含触发器的 Flow；或这是第一个任务的 Case），则只使用输出方向字段，并注明：“没有可供提取数据的上游值，因此审核者需要从头填写所有字段。”

字段标签为空会阻止验证

inputs.schema.fields 中的每个字段都必须有非空的 label。对于 label 为空或仅包含空白字符的每个字段，flow validate 都会发出 HITL_QUICK_FORM_FIELD_LABEL_REQUIRED（错误级别）——在填写所有标签之前，Debug 和 Publish 都会被阻止。切勿生成 "label": "" 的字段，也不要省略 label 键。

步骤 5 — 直接编写节点

界面：Flow — QuickForm（仅内联架构）

直接将节点 JSON 写入 workflow.nodes，将定义添加到 workflow.definitions（仅添加一次），将边连接到 workflow.edges，并重新生成 workflow.variables.nodes。默认使用直接 JSON。

节点 JSON、定义条目、边格式、variables.nodes 算法和四个完整示例：如何编写 QuickForm HITL 节点

**CLI（可选）：**仅当用户明确请求 CLI 命令时：

uip maestro flow hitl add <path/to/file.flow> \
  --label "<TaskLabel>" \
  --priority <Low|Medium|High> \
  --assignee <email-or-group> \
  --schema '<json>' \
  --output json

CLI 会自动写入节点、添加定义条目并更新 variables.nodes。返回后，为每个结果连接一个 outcome-<outcome.id> 端口。

写入后，进行验证：

uip maestro flow validate <file> --output json

界面：Flow — Coded Action App（新建内联）

必须先完成步骤 4c——确认应用名称、定位解决方案目录、确定 SDK tarball 并设计和确认架构。

搭建项目目录及所有源文件，将项目添加到解决方案，写入解决方案资源文件，然后编写 HITL 节点（类型为 uipath.human-in-the-loop.coded-action-app），其中 inputs.app 引用新应用（由于该应用尚未部署，appSystemName: null）。

完整的项目模板、UUID 生成、解决方案 CLI 命令、资源文件模板、节点 JSON 和创建后的构建步骤：如何搭建新的 Coded Action App

写入后，进行验证：

uip maestro flow validate <file> --output json

界面：Flow — AppTask（仅限已部署的操作应用）

必须先完成步骤 4b——解析应用并检索配置。然后：

解析解决方案上下文（.uipx 文件），写入解决方案资源文件，注册应用引用，合并 debug_overwrites.json，然后写入节点 JSON（类型为 uipath.human-in-the-loop.coded-action-app），并从步骤 3b 的配置填充 inputs.app。

应用搜索/选择、检索配置、资源文件写入、包含 appInputBindings 的完整节点 JSON：如何连接现有的已部署操作应用

写入后，进行验证：

uip maestro flow validate <file> --output json

界面：Case

读取上述检测找到的计划文件，以确定目标阶段：caseplan.case，或者在由较旧 CLI 搭建的项目中使用 caseplan.json。编辑并验证该文件；切勿在其旁边新建第二个计划。直接将 action 任务写入 stage.data.tasks[lane][]。直接写入 JSON 是唯一受支持的方法——uipath-maestro-case 技能没有 hitl CLI 子命令（与 Flow 的 uip maestro flow hitl add 不同）。

完整参考：references/hitl-casetask-action.md——三种任务 JSON 结构（QuickForm、通用型、基于应用）、字段参考、受派人处理、写入后验证，以及下游输出访问方式。

在步骤 3 中选择的路径写入内容

QuickForm 一个 <TaskLabel>.hitl.json 架构文件（包含 direction 和 outcomes[] 的统一 fields[]）+ caseplan.case 中的 action 任务，其中 data.context[hitlType].value: "quick"、_schemaFileId（占位 UUID）和 hitlSchemaId（与 .hitl.json 中的 schemaId 相匹配）。data.inputs[] 和 data.outputs[] 为空数组。不添加 root.data.uipath.bindings[] 条目。写入前应用步骤 4b 的架构设计检查。

基于应用 Action 任务，其 data.actionCatalogName、data.name 和 data.folderPath 均为 =bindings.<id> 引用。添加 2 个根级绑定。

写入后，进行验证（构建时检查——报告成功前必须通过）：

uip maestro case validate <caseplan.case> --output json

此技能在 Case 界面中唯一使用的 uip maestro case CLI 是 uip maestro case validate。所有创作操作均直接修改 JSON。

界面：Low-Code Agent

Low-Code Agent 升级 CLI（uip agent escalation add）目前仍在开发中。该功能发布前，请手动配置：

agent.json 升级条目：

{
  "escalations": [
    {
      "name": "<escalation-name>",
      "inputSchema":  { "inputs": [...], "inOuts": [...] },
      "outputSchema": { "outputs": [...], "outcomes": [...] }
    }
  ]
}

Agent 源代码（Python）：

from uipath.sdk import interrupt, CreateTask

response = interrupt(CreateTask(
    escalation_name="<escalation-name>",
    data={ "fieldName": value }
))
# response contains the human's outputs and chosen outcome

界面：Maestro

Maestro BPMN 流程同时支持 QuickForm 和 coded-action-app HITL 节点。uipath.human-in-the-loop.quick-form 和 uipath.human-in-the-loop.coded-action-app 在 BPMN 验证器（bpmn-spec.json）中注册为注册表快捷名称——它们是调色板/发现标识符，而不是要写入的字面 XML。Maestro 没有专用 CLI 子命令（与 Flow 的 uip maestro flow hitl add 不同）——请将节点直接写入 .bpmn XML。

已确认的节点结构（已通过对 Studio Web 中一个可正常编辑的 QuickForm 任务进行真实 BPMN 流程直接复现验证）：

<bpmn:task id="Activity_InvoiceApproval" name="Invoice Approval">
  <bpmn:extensionElements>
    <uipath:activity version="v1">
      <uipath:type value="Actions.HITL" version="v2" />
      <uipath:context>
        <uipath:input name="hitlType" type="string" value="quick" />
        <uipath:input name="taskTitle" type="string" value="Please review this invoice and approve or reject" />
        <uipath:input name="labels" type="string" />
        <uipath:input name="priority" type="string" value="Medium" />
        <uipath:input name="actionCatalogName" type="string" />
        <uipath:input name="enableActionableNotifications" type="boolean" value="false" />
        <uipath:input name="assignmentCriteria" type="string" />
        <uipath:input name="recipient" type="json" />
        <uipath:input name="_schemaFileId" type="string" value="<see file-id callout below>" />
        <uipath:input name="hitlSchemaId" type="string" value="<matches schemaId in the .hitl.json sidecar>" />
        <uipath:inputSchema type="jsonSchema"><![CDATA[{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"invoiceid":{"type":"string","title":"Invoice ID"},"amount":{"type":"number","title":"Amount"}},"required":[]}]]></uipath:inputSchema>
      </uipath:context>
      <uipath:input name="HitlTaskArguments" type="json" target="bodyField"><![CDATA[{"invoiceid":"INV-1001","amount":500}]]></uipath:input>
      <uipath:output name="Action" type="string" source="=Action" var="invoiceDecision" options="[{&#34;value&#34;:&#34;Approve&#34;,&#34;label&#34;:&#34;Approve&#34;},{&#34;value&#34;:&#34;Reject&#34;,&#34;label&#34;:&#34;Reject&#34;}]" />
    </uipath:activity>
  </bpmn:extensionElements>
  <bpmn:incoming>edge_into_task</bpmn:incoming>
  <bpmn:outgoing>edge_out_of_task</bpmn:outgoing>
</bpmn:task>

容易出错的几点：

元素是 bpmn:task，不是 bpmn:UserTask。 bpmn-spec.json 中通用的 Actions.HITL XML 模板使用 bpmn:UserTask 和 version="v1"——该模板适用于基于应用／编码操作应用的路径（其 context 字段为 appId、appVersion、actions、key、taskTitle）。从 Studio Web 导出的实际 QuickForm 任务是普通的 bpmn:task，带有 uipath:type value="Actions.HITL" version="v2"。QuickForm 使用上面的结构；基于应用的任务使用规范中的模板。
<uipath:inputSchema>（<uipath:context> 的最后一个子元素）和 <uipath:input name="HitlTaskArguments">（与 <uipath:context> 同级，而非位于其中）都是必需的。 缺少它们时，Studio Web 中的“编辑架构”画布完全无法打开——已通过直接复现确认。这与 Case 界面的 data.inputSchema／data.inputs[] 要求一致——平行的 Case 结构和逐字段说明请参见 hitl-casetask-action.md § Step 3。
Action 输出需要匹配的流程级变量声明——在流程顶层的 <uipath:variables version="v1"> 块中添加 <uipath:inputOutput id="<varId>" name="Action" type="string" elementId="<taskId>" />。
必须有单独的 <TaskLabel>.hitl.json 伴随文件，其结构与 Case 界面相同（title、带有 direction／可选 colSpan／binding 或 variable 的 fields[]、不含 action 键的 outcomes[]、schemaId）——确切结构请参见 hitl-casetask-action.md § Step 2；两个界面的结构完全相同。
不能凭空填写 _schemaFileId——这是由服务分配的外键，不是可以自行编造的 UUID。 占位值会导致“编辑架构”静默失败（Studio Web 内部的 FileOperations/File/Rename 调用返回 404，已通过直接复现确认）。目前没有可解析该 ID 的 uip CLI 命令。绝不要因此停下工作。 写入一个新的 UUID v4 占位值，完成节点其余部分，验证后继续——不要自行尝试在线协调，也不要停下来询问。请在最终报告中明确说明：“此任务的架构使用了占位 _schemaFileId，因此目前无法在 Studio Web 中打开其‘编辑架构’画布。要使其可编辑，需要解析 Studio Web 在上传 .hitl.json 后分配的实际文件 ID（GET /api/Project/{projectId}/FileOperations/Structure），并通过针对单个文件的更新将其写回（PUT /api/Project/{projectId}/FileOperations/File/{fileId}）——不能再次执行整个项目的 uip solution upload，因为这会重新推送每个文件，并为每个文件生成全新的随机文件 ID，从而撤销修复。如果你希望该架构能在 Studio Web 中编辑，请让我来完成这项协调。”这是产品／工具链中真实存在的缺口，用户之后可以处理，不应在当前任务中解决。
即使逻辑上的 bpmn:sequenceFlow 已经存在，也必须有图交换边，连接线才能渲染。 每个 bpmn:sequenceFlow 都需要在 bpmndi:BPMNPlane 中有一个匹配的 bpmndi:BPMNEdge（带有两个 di:waypoint 点，并与源／目标形状的连接边对齐）——省略它会导致节点在逻辑上相连，但在画布上看起来互不连接。已通过直接复现确认。

按照 Step 4b 设计架构——根据 Critical Rule 1，绝不要等待用户而停下——并在连接节点时频繁验证（uip maestro bpmn validate <file>.bpmn --output json），以便立即发现结构错误，而不是等到部署时才发现。在 Maestro 中，outputs／inOuts 中的字段名必须与声明的流程变量名称和类型完全一致。

步骤 6 — 向用户报告

完成接线后：

插入的内容 — 节点 ID、标签、插入位置
架构摘要 — 人工将看到哪些内容（input 方向的字段）、需要填写哪些内容（output/inOut 方向的字段），以及需要点击哪些内容（结果）。对于已部署的 action app，请在此处展示 retrieve-configuration API 响应中的 actionSchema。
已接线的边 — 哪些句柄连接到了哪些节点；哪些句柄尚未接线
运行时变量 — $vars.<nodeId>.output（对象）和 $vars.<nodeId>.status（字符串），以及如何在下游引用它们
验证结果 — 通过或需要修复的错误
生产就绪说明：
- QuickForm：打包解决方案后即可部署。无需额外的构建步骤。
- 新建的 Coded Action App：必须构建应用（在应用源代码目录中运行 npm run build）并打包解决方案，然后才能在生产环境中使用该 HITL 任务。在首次部署分配系统名称之前，应用的 appSystemName 将显示为 null。
- 现有的已部署应用：可立即部署 — 应用已上线。
下一步 — 准备就绪后，通过 uipath-development skill 打包并发布

参考资料

如何编写 QuickForm HITL 节点 — 用户在步骤 3 中确认使用 QuickForm 后阅读。涵盖完整的节点 JSON、定义条目、边接线、variables.nodes 重新生成算法，以及四个完整的架构示例。
如何接入现有的已部署 Action App — 用户在步骤 3 中选择现有的已部署应用后阅读。涵盖通过 Orchestrator API 查找应用、inputs.app 字段映射、appInputBindings 和解决方案资源文件。
如何搭建新的 Coded Action App — 用户希望在解决方案中构建新的 React 应用时阅读。涵盖完整的项目模板、UUID 生成、解决方案 CLI 命令，以及创建后的构建步骤。
引导式决策体验 — 仅在请求要求捕获决策或审核者纠正提案时阅读；根据请求判断是否启用引导式决策体验。涵盖切换开关、捕获深度如何随重要程度调整、除作者自身字段外添加的决策字段、后端记录的内容，以及捕获布局。
HITL 业务模式识别 — 在步骤 2 / 步骤 2b 阅读，以识别流程是否需要人工检查点以及适用的模式。包含主动建议的措辞，以及不应建议 HITL 的情况。
Action Center URL 模式（位于 uipath-tasks skill 中）— 在向用户提供任何 Action Center 任务 URL 前阅读。涵盖缺少租户 slug 的反模式，以及 API 主机与 UI 主机之间的映射。
Case Action Task (HITL) — Case 界面：action task JSON、QuickForm 与基于应用的路径、.hitl 文件格式、上下文条目、字段绑定，以及下游输出访问。

支持 Markdown

登录后评论

基本信息

作者: uipath
仓库: uipath/skills
分类: 开发
安装次数: 54
GitHub Stars: 175

报告问题

uipath-human-in-the-loop

关于 uipath-human-in-the-loop

主要功能

适用场景

安装

包含的文件

详细介绍

UiPath 人机协同助手

何时使用此技能

关键规则

步骤 0 — 解析 uip 二进制文件

步骤 1 — 检测界面类型并查找 Flow 文件

步骤 2 — 阅读业务上下文

第 2b 步 — 主动建议 HITL

第 3 步 — 选择任务类型

界面：Flow

Surface: 案例

步骤 4 — 通用配置

步骤 4b — 架构设计韧性（QuickForm — 流程与案例）

字段方向

字段类型

架构描述模糊或不完整

字段标签为空会阻止验证

步骤 5 — 直接编写节点

界面：Flow — QuickForm（仅内联架构）

界面：Flow — Coded Action App（新建内联）

界面：Flow — AppTask（仅限已部署的操作应用）

界面：Case

界面：Low-Code Agent

界面：Maestro

步骤 6 — 向用户报告

参考资料

评论

步骤 0 — 解析 `uip` 二进制文件