uipath-maestro-case

UiPath Case Management 编写助手

根据 sdd.md 构建 UiPath Case Management 定义。将租户资源解析到 tasks/registry-resolved.json，然后使用 uip maestro case sdd convert 生成 caseplan.case，并依据适用的各插件 JSON 配方补全文档无法确定的内容。SDD 就是计划——不存在中间计划文件，而转换得到的 caseplan.case 也不是计划文件：它本身就是产物，是从 SDD 推导而来，并非对 SDD 的复述。

**编写不变量：**绝不使用会修改内容的 uip maestro case 命令（cases|stages|tasks|*-conditions ... add|update|remove，包括 tasks add-connector），也不要通过 --help 探索这些命令。CLI 仅用于搭建脚手架、读取元数据、验证/调试、运行时操作以及解决方案同步/上传。只有在需要精确语法时，才查阅 case-commands.md。CLI 是否可用或是否要求最终执行 validate，都不能凌驾于此规则之上。

如果不存在 sdd.md，案例设计只能由 uipath-planner 负责，它会在本次对话中运行 Case Design Lane。本技能绝不独立进行设计。该流程采用最佳假设设计，依次执行 Listen → Sketch → 完整的设计时租户资源解析、强制的其他路径审查，以及以决策为先的八部分 Case Review。用户对 Build 的回答即为同意；流程会写入符合模板的 sdd.md，然后本技能立即继续执行

uip solution init、Phase 1，

以及后续阶段。定稿 sdd.draft.md 时也适用相同的交接方式。绝不覆盖现有的 sdd.md。

**范围：**基于 sdd.md 的全新构建，以及针对现有 caseplan.case 的棕地定向编辑；参见 references/brownfield.md。对于 Studio Web 案例，先使用 uip solution download 或 solution projects resync 拉取当前服务端状态，以免发布时覆盖服务端更改。

何时使用此技能

适用于：

• 根据 sdd.md 构建 Case Management 项目。
• 在没有 SDD 时创建案例；在本次对话中将设计交由 uipath-planner 处理。
• 根据 SDD 生成实施任务。
• 根据明确意图编辑现有的 caseplan.case：更改阶段/任务、条件或触发器。
• 咨询案例 JSON 架构、节点、转换、任务、规则、SLA 或运行时案例实例。

不适用于 .xaml → uipath-rpa、.flow → uipath-maestro-flow，或案例上下文之外的独立 Agent/API/流程。

关键规则

1. **设计交接与 SDD 权威性。**如果不存在 sdd.md，必须立即在本次对话中调用 uipath-planner 的 Case Design Lane，然后才能阅读参考资料或运行租户命令。不要在此处自行设计访谈、设计子 Agent、通用 Build Plan 审批流程，也不要执行仅限设计的行为。该流程的单次 Case Review 必须恰好包含以下部分：案例概览；主要旅程；已考虑的其他路径；SLA 与升级；规则与结果；资源与集成及其设计时解析结果；我做出的决定；审查标记。内容须列出每个阶段/任务、类型、激活/分组方式、必需状态、路由/结果及 SLA 上下文；sdd.md 则单独包含完整的数据契约、变量以及任务输入/输出。Build 选项须纳入规则 12，Build 回答是唯一的同意。在批准之前，每个 selected-tasks-completed 选择器都必须解析到同一阶段中的非临时兄弟任务。该流程会尽早写入 sdd.md，然后本技能运行

uip solution init <SolutionName> 和 Phase 1 无需再次提示，除非用户明确要求。仅限设计的请求按规则 3 的设计专用例外，在 sdd.md 之后停止。如果要定稿 sdd.draft.md，请使用快速通道，并将目标基本文件名设为 sdd.md。绝不要覆盖 sdd.md。 2. SDD 是设计完成后的唯一输入，跨会话亦如此。 信任用户提供或先前写入的 sdd.md；不要验证、补齐缺失内容或默默推断。在设计获批的同一对话中，使用写入该文件的内存模型，而不要在阶段中途重新读取——但规则 8 的第 2 阶段和第 3 阶段入口检查点除外，这些检查点始终会重新读取，因为上下文可能已经压缩。构建阶段遇到歧义时，使用 AskUserQuestion。在读取未被监控写入的 SDD 之前，先读取前 40 行作为凭据：其中必须同时包含 `` 标记和 Template validation 标题值 passed。否则，必须返回规划器的模板合规检查清单。 3. 第 1 阶段注册表门禁。

运行 uip login status --output json，然后 uip maestro case registry pull，在检查缓存、沿用已有结果、解析或执行 Phase 1 写入之前运行。每个会话最多拉取一次，除非用户在 Rule 18 的空查询门控处选择 Force pull and re-resolve，或 sdd resolve 报告缓存过期（见下文）。如果本会话中运行了规划器通道，且拉取成功并写入了 SDD，则复用缓存。根据该通道在上下文中得出的解析结果，采用仅验证规划：将其原样保存到 tasks/registry-resolved.json，抽查缓存条目，执行门控决策，并且仅重新解析过期或缺失的条目。否则运行完整门控。登录或拉取失败会停止 Phase 1。除上述快速路径外，使用 uip maestro case sdd resolve "<SDD_PATH>" --out tasks/registry-resolved.json --output json 进行解析：它会为每种任务类型选择索引，执行精确名称搜索和文件夹缩小范围，并在一次调用中为每项任务写入 Rule 10 台账。当其 Data.Warnings 报告缓存过期时（Data.Scope.cache.stale: true），无需询问，运行一次 uip maestro case registry pull --force --output json，然后再次运行 sdd resolve。普通拉取会复用任何未满 24 小时的缓存，因此只有 --force 才会刷新缓存；该警告正是缓存过期的证据，否则 --force 会要求确认。如果强制拉取后缓存仍然过期，请报告这一情况并继续。绝不要手动编写该台账——解析命令不到一秒就能写入，而实测手动编写约需 50 秒，且会将同一轮随后绑定的资源记录为 selected: null。Data.Unresolved[] 是唯一剩余工作，且仅对此进行手动处理：absent 条目须先执行 registry-discovery.md 的跨类型回退和解决方案内同类项检查，再进入 Rule 18 的门控；ambiguous 条目——存在多个精确名称匹配项，但 SDD 中的文件夹无法缩小范围——绝不能通过任选其一来确定：它与 absent 条目一样进入 Rule 18 的门控；若没有答案，则保持为 <UNRESOLVED> 并成为占位符。对于这些手动查询，uip maestro case registry search "<Name>" --type <type> --output json 和 ~/.uip/case-resources/<type>-index.json 返回相同记录，但结构不同：索引文件是扁平的 camelCase 对象列表（entityKey、folders）；registry search 则将每个匹配项包装为 Data.Resources[] = {ResourceType, Resource: {…}}，并使用 PascalCase 键（EntityKey、Folders）。如果 CLI 将 sdd resolve 报告为未知命令（ErrorCode: "invalid_argument"，退出码为 3），则按照 registry-discovery.md 手动解析每项任务，并用一句话说明。成功拉取之前，缓存文件缺失属于刷新前置条件失败，绝不能视为零匹配；只有成功后，精确名称匹配为空或索引缺失时，才可进入空查询处理。以 SDD 为准；拉取只会刷新发现数据。规划器通道负责设计时解析：在首次出现绑定租户的工作时按需启动登录和拉取，通过一次批量 Case Review 门控解析身份，并记录 SDD 单元格及其解析台账。此处不进行架构发现。 **仅进行设计的例外情况：**如果明确要求在 sdd.md 或 sdd.draft.md 处停止，不涉及 caseplan.case、解决方案或构建，则不要运行租户注册表、连接、架构或用户发现命令。保留预期名称，将身份标记为 <UNRESOLVED>，并在回复中说明待延后的接线工作——绝不能写入替代计划文件。此例外不适用于用户要求解析资源／身份、刷新注册表、替换过期审计、生成 tasks/registry-resolved.json 或 tasks/recipients-resolved.json 的情况；此时应运行常规门禁、解析身份、写入台账，并在 Phase 2 之前停止。 4. **先转换，再编写。在 Phase 2 开始时、完成 Rule 3 注册表门禁后，使用 uip maestro case sdd convert "<SDD_PATH>" --resolved tasks/registry-resolved.json --out "<SolutionName>/<ProjectName>/<PLAN_FILE>" --output json 生成计划，其中 <PLAN_FILE> 是 case init 创建的计划文件（Rule 14：caseplan.case；若 CLI 版本早于 .case 命名，则为 caseplan.json）。计划文件位于更深两级的目录中——它应放在 Rule 24 创建的项目目录内，绝不能放在解决方案根目录，也不能与 sdd.md 放在同一目录。若文件放得过浅，要么所有 grader、validate、bindings sync 和 solution pack 查找的位置都没有计划文件，要么会出现两个 caseplan.case 文件，导致构建目标不明确。caseplan.case 的大部分内容由 SDD 决定；一次性推导优于逐项重新推导，而手动编写解析器已能输出的内容既耗时，又容易偏离文档。其 Data.Unresolved[] 就是待办清单：resource-binding 在 Phase 1 绑定时解决，output-type 在 uip maestro case splice --described（Step 9.8）时解决，connector-context 在 Check 12 时解决；它只是下限，绝不是上限：它只列出 convert 知道自己跳过的内容，不会列出它错误输出的内容。它未列出的已知缺口：每个 jsonSchema 变量都会带有 body: null；请根据 SDD 中对应的行，按照 global-vars/impl-json.md § jsonSchema type 填写 body 和 _jsonSchema。Data.Unresolved[] 是所有剩余工作的完整清单。**只需查看一次生成的计划，解决其中的条目，然后停止；不要重新推导、复核或重读 convert 已经输出的内容所对应的参考资料。已进入转换后计划的结构即已确定——重新审查它所耗费的成本超过了整个转换节省的成本。**在编写任何元素之前先进行转换。**先按 Rule 24 搭建项目骨架——case init 不接受非空目录，因此先转换会导致项目缺少 project.uiproj，且清单未注册。然后立即运行 convert；切勿先手动构建阶段、任务、条件或变量，再运行 convert。完整流程（包括必做的任务入口规则检查，此项不会被上游步骤捕获）见 references/phased-execution.md。

版本防护。 如果 CLI 将 sdd 或 convert 报告为未知命令（ErrorCode: "invalid_argument"，退出码为 3），请手动编写 Phase 2，并用一行说明，然后继续。没有该说明的退出码 3 是真正的失败，不是回退方案。切勿安装、重新安装或更改 CLI。

5. 解析读取必须使用 --output json。

6. 编写内容时参考插件文档，不要用它来核对 convert 输出。 规划期间，cat 对应的插件 planning.md。执行期间，在手动编写或修复插件结构之前，先 cat 该插件的 impl-json.md：包括 Data.Unresolved[] 指定的结构（规则 4）、步骤 12 报告的所有结构，以及任何 sdd convert 未涵盖的插件结构。转换后的计划中已有的结构无需读取 impl-json.md：这是 convert 生成的，规则 4 已足以判定，打开对应的配方会导致读取整个文件，却不会改变任何内容。无论打开什么，都按规则 25 阅读所需章节；切勿猜测 JSON 结构。

7. 构建结果必须完整保留 SDD 内容。 切勿编写中间计划文件：sdd.md 就是计划，重新表述会导致偏离。caseplan.case 结尾必须为 SDD 中的每个阶段、任务、触发器、条件、SLA 规则、变量和参数各包含一个元素，包括显式默认值——其中大部分由 sdd convert 生成（规则 4），其余在之后补齐；本规则要求的是最终产物包含这些内容，而非手动编写每个元素。原样保留每条有效的显式规则／选择器；拒绝并修复无效的 selected-tasks-completed 选择器。将阶段或任务的 **Description:** 行逐字复制到元素的 description；只有当该区块没有 **Description:** 时，才在其中使用 **Design Rationale:**。其他设计原理、SLA 原理，以及条件路由／激活原理，都写入 build-issues.md；当元素没有 description 槽位时，**Description:** 也写入该文件。保留每一行 Inputs、绑定模式和值。原样保留 JSON 对象字面量：将其作为原生对象或 JSON 编码字符串写入 input.value；仅当 SDD 中明确写出 =js:／=jsonString: 时才添加。按照 plugins/variables/io-binding/planning.md 投影 Outputs，并保留运算符和操作数。SDD 输出行必须包含 -> 或 =；通过 schema 发现的裸输出不是 SDD 编写的行。切勿简化名称相同的 -> 行；greeting -> greeting 与通过 schema 发现的裸 greeting 不同。— 占位符不是操作数。对于无法识别或含义不明确的行，请使用 AskUserQuestion；切勿悄然省略。从头重新生成全新构建；棕地编辑则保留 ID。每个任务节点都必须具有自己的 entryConditions，根据其 SDD Entry Condition 表和 Activation Mode 推导——逐个任务编写，切勿只为一组相似任务编写一次；validate 只会发出 Task has no entry rules 警告，而遗漏规则会导致 case debug 无限期挂起。请参阅 references/implementation.md。

   完成标准是 --strict --sdd，绝不能是默认配置文件的 Valid。 在步骤 12 运行 uip maestro case validate <caseplan.case> --strict --sdd sdd.md，并在报告构建完成前，关闭每一项 STRICT_SDD_* 发现项和 sdd convert 的每一项 Data.Unresolved[] 条目。对于缺少阶段、任务、条件、SLA 规则和输出类型的计划，普通 validate 仍会返回 Valid；绝不能把这个 Valid 报告为构建结果。

8. 构建关卡。 第 1 阶段会自动进入第 2 阶段。只有当请求明确表示仅做设计、仅做第 1 阶段、先审核，或不要构建时，才在完成解析后停止。在第 2 阶段和第 3 阶段入口处重新读取 sdd.md 和 tasks/registry-resolved.json——上下文可能已经压缩。

9. 未解析的资源。 绝不伪造 ID。在 tasks/registry-resolved.json 中保留 <UNRESOLVED: ...>。占位任务包含 type、displayName、结构字段和 data: {}；条件仍引用其 TaskId。占位事件触发器保留其渲染字段及 data.inputs，其中仅包含 sdd convert 输出的 serviceType、entryPointId 和 objectName 上下文条目（即 SDD Source）；追加其 entry-points.json 条目，但不创建触发器边。参见 references/placeholder-tasks.md 和 impl-json.md § Placeholder fallback。

10. 解析审计。 tasks/registry-resolved.json 为每个任务保存一个对象，包含精确键 stage、task、taskType、cacheFile、searchQuery、matches、selected 和 rationale，以及已解析的 I/O／审核元数据。uip maestro case sdd resolve --out 会写入此文件（规则 3）：一个对象，其 resolved 数组包含这些条目，并与 unresolved 和 scope 并列。保留此结构——绝不重新包装、进一步嵌套或手动扁平化。 使用方会搜索这些条目，但搜索有深度限制：找不到的台账与没有台账无法区分，因此有理由的占位项会验证失败，而不是发出警告。解析会将每个资源记录为规范化的 {name, identifierField, identifier, folder}；从这些字段读取任务标识，不要将缓存对象重新复制到这些字段中。台账中的其他内容都使用 Edit 添加到所属条目：gateDecision、下文的标识槽标记、wiringNotes，以及触发器和连接器绑定条件各自的条目；resolve 不会覆盖这些内容。同一会话的规划器台账则按原样持久化（规则 3），不论其初始结构如何；使用方会同时读取两者。仅当用户回答了设计阶段的资源关卡时才添加 gateDecision；默认延后时不添加。matches 是刷新缓存中的完整精确名称集合；经过真实的空查找后，selected 是匹配项或 null。真实未命中——即 resolve 在 unresolved[] 中列出的条目，或手动查找结果为空的条目——还必须包含其任务类型对应的标识槽：非连接器任务使用 taskTypeId，连接器任务和触发器使用 typeId / connectionId，并填入规则 9 要求的 <UNRESOLVED: <reason>> 文本。wait-for-timer 条目不会运行任何租户资源，resolve 会将其记录为 selected: null；它绝不是未命中项，无需标记。连接器条目由连接器流程解析（connector-integration.md），而不是由 resolve 解析，因此其标记取决于该流程的结果——resolve 将其记为 selected: null 仅表示 resolve 没有查找它。单独的 selected: null 并不能记录未命中：第 2 阶段会读取标记，并据此输出占位项而不是获取架构。同一会话的规划器台账按原样持久化，随后根据规则 3 验证／扩展。解析台账和 registry-resolved.json 仅供机器使用——绝不向用户展示，包括在 Case Review 中。

11. 跨任务引用。 使用 "Stage Name"."Task Name".output_name 和 plugins/variables/io-binding/impl-json.md 中的通用输出引用 ID 算法。使用源输出的 .id；只有没有 .id 的自定义 = 输出才使用已验证根配套项的 .id。绝不使用重新赋值的输出的 .var。对于连接器任务，使用 uip maestro case spec 发现名称；对于非连接器任务，使用 uip maestro case tasks describe。在较大的 =js: 表达式中，使用 vars.$xref('Stage','Task','output')，并在步骤 11.5 解析。参见 references/bindings-and-expressions.md。

12. 构建审核偏好。 在旅程开始时记录一次。设计交接会将其纳入 Case Review 的构建选项（Build it — straight through 或 Build it — pause at the build preview）；提供的 SDD 则会在路线图之后询问一次。非交互运行和未提供偏好的恢复运行默认直接继续。在第 2 阶段到第 3 阶段的转换处，先尝试 validate --skeleton-v2；仅当响应明确表示 v2 未知／不受支持时，通常是 invalid_argument／退出码 3，才回退一次到旧版 --skeleton。仅有退出码 3 不足以作为回退依据；真实的 v2 错误会被报告。验证发现项不会阻止此建议性关卡。直接继续时无需提示。暂停到预览时，遵循 references/phased-execution.md：通过 AskUserQuestion 询问 Publish for review / Skip publish and continue / Abort；选择发布后，刷新资源，使用必需的筛选条件上传，在后续提问前打印 DesignerUrl，然后询问 Continue to implementation / Abort。第 4 阶段的重试耗尽、第 5 阶段、第 6 阶段、第 7 阶段，以及修复第 6 阶段问题后进行的任何重新发布，始终是硬性停止点。

13. 绝不自动调试或发布到 Orchestrator。 uip maestro case debug 会执行真实的电子邮件、消息和 API 调用。第 7 阶段（case pack → solution pack → solution publish）会将内容发布到租户。两项操作都各自需要通过 AskUserQuestion 征得同意。

14. 制品 I/O。 计划文件是 caseplan.case。 将你创建的计划命名为 caseplan.case，入口点需命名为 caseplan.case.bpmn，包描述符中也需包含这两个文件。如果项目中已有另一个 Studio Web 名称的计划——例如 caseplan.json、case.stage.json、default.stage.json，包括旧版 case init 创建的计划——那么该文件就是计划：写入并验证它，绝不要在旁边再创建第二个计划文件，因为 CLI 和 Studio Web 只读取当前存在的最新名称，而且 case pack 会拒绝入口点指向另一计划的 sidecar。在 case init 不可用、且 T01 直接 JSON 脚手架创建项目时（规则 24），CLI 早于 .case 支持，因此应将该计划命名为 caseplan.json。本技能中提到的每个 caseplan.case 都指该文件。对于 caseplan.case、sdd.md、sdd.draft.md、tasks/registry-resolved.json、tasks/trigger-spec-cache.json、tasks/spec-cache.<elementId>.json、id-map.json、entry-points.json 和 build-issues.md，只能使用你所用环境的文件工具（bindings_v2.json 是例外：由 uip maestro case bindings sync 生成；绝不手动写入。caseplan.case 也有一个指定生成器——第 2 阶段开始时，uip maestro case sdd convert --out 会根据 sdd.md 输出初始计划；之后的每次编辑都和其他文件一样使用 Write/Edit。tasks/registry-resolved.json 也有指定生成器——uip maestro case sdd resolve --out 在第 1 阶段写入该文件（规则 3）；之后每次添加内容都使用 Edit。tasks/spec-cache.<elementId>.json 是第三个例外：将 uip maestro case spec --output json 的输出重定向到该文件，因为手动复制数十 KB 的响应会静默丢失子树。此重定向仅写入一次，是本规则唯一允许的重定向；之后绝不编辑该文件，也绝不将输出重定向到其他受管制的制品。每个事件触发器都使用 Write/Edit 将其 T 编号键合并到 tasks/trigger-spec-cache.json）：仅使用 Write / Edit（或 apply_patch``）修改。**禁令只针对写入途径。** 绝不通过脚本修改这些文件：不得使用 sed -i、perl -pi、awk、jq、Python 或 Node 重写、shell 重定向、tee、cp、mv、install、rsync，也不得使用任何由 Agent 编写的脚本，包括在 /tmp下的脚本。**读取不受限制**——允许对这些制品及~/.uip/case-resources/使用cat、sed -n、head、rg、jq投影和python3 -c读取。本规则禁止用脚本编写或编辑制品，绝不禁止检查；caseplan 自身的检查命令是uip maestro case validate --strict --sdd（规则 7）。如果 caseplan.case 超过约 30 KB，应按照 [case-editing-operations.md](references/case-editing-operations.md) 中的预览／详情节奏读取，而不是一次性读取全部内容。允许使用 Bash 进行只读检查、无文件系统访问的 UUID v4 生成、CLI 元数据查询、validate、format、bindings sync、splice、sdd parse、sdd resolve、sdd convert、debug，以及 solution 脚手架／上传。带前缀的 ID 在行内选取。**以美化格式写入 caseplan.case，并在每次写入后运行 uip maestro case format "<caseplan.case path>" --output json**——这是唯一允许的重新格式化操作。紧凑格式的计划不能用 Edit/apply_patch修补；而且每个已发现的perl -pi/sed -i` 违规都始于紧凑格式文件。关于 format 的精确输出及幂等性，参见 case-commands.md § uip maestro case format。

15. 可运行资源和 sidecar。 第 4 阶段之前，即使跳过发布、调试或资源刷新，也要运行步骤 12 的检查 7、9、11 和 12。非空的 selected 资源不得变成占位项：保留 data.name 和 data.folderPath 以及完整的根绑定，使用 uip maestro case bindings sync 重新生成 sidecar，并确保其 resourceKey 与自身默认值一致，绝不能复制租户标识／UUID。每项检查的范围和修复方式见 implementation.md § Step 12。每个连接器上下文的 connection 条目都必须解析为已声明的 Connection 根绑定——连接器任务通过 uip maestro case splice 获取该绑定；该命令会在一次调用中写入 =bindings.<id> 引用，以及从保存的规格中取得的两个根绑定；事件触发器节点和连接器绑定规则则在同一次编辑中获取规格中的 =bindings.<id> 引用，以及 ConnectionId 和 FolderKey 根绑定；将连接 ID 放在 folderKey 中，或连接器的 bindings[] 中没有 Connection 绑定，都是永远无法解析的资源。完成标准遵循规则 7 的 --strict --sdd；每个阶段使用的配置、不得串联规则，以及 CLI 1.202 版本检查，见 case-commands.md § uip maestro case validate。修复不匹配项并重新检查；如果仍有问题，必须在第 4 阶段之前停止。每次 resources refresh 之前都重复检查 7。只要计划绑定了连接器连接，就运行 uip solution resources refresh——不只是上传或调试前；并且每次上传或调试前都要再次运行：此命令会生成 resources/*/connection/*.json；如果不运行，验证通过的计划打包后仍会生成无法连接的解决方案（bindings-v2-sync.md）。上传标志和 DesignerUrl 报告方式见 phased-execution.md § Phase 5。

16. 交接约定。 在本次对话中调用 uipath-planner 的 Case Design Lane，绝不能将其作为子 Agent 调用。它负责设计、解析、审核和 SDD 编写；本技能从解决方案初始化处继续。面向用户的语言应呈现为一段连贯流程，绝不提及交接。如果不可用，用一句话说明，请求 sdd.md 或经批准的粘贴设计，然后停止。跨产品规划仍以纯文本建议的形式提供给规划器。在读取未观察到的 SDD 前，应用规则 2 的收据抽查。

17. 封闭的任务类型。 caseplan.case 任务的 type 必须恰好是以下之一：process、agent、rpa、action、api-workflow、function、business-rule、case-management、execute-connector-activity、flow-process、http-request、document-extraction、wait-for-connector、external-agent、external-workflow、wait-for-timer。绝不能使用插件文件夹名或 CLI 名称、wait-for-event，或其他杜撰的值。不受支持的类型仍然不受支持。参见 references/case-schema.md 和插件索引。

18. 空查找关卡。 如果同一会话的台账中有用户填写的 gateDecision，就直接执行，不要再次询问：resolve-at-build → 使用占位项；create-during-build → 内联创建；pick:<name> → 绑定该资源。缺少决策表示默认延后，不代表同意；运行完整关卡。对于零个匹配项，使用一次批量 AskUserQuestion，按 (name,type) 分组，提供：Force pull and re-resolve；Use placeholders for all；并且仅当存在可创建的资源且支持 registry --local 时，提供 Create missing resources inline。对于多个精确名称匹配项，如果 SDD 中的文件夹未能缩小范围，绝不要按位置选取：缓存按租户注册资源的顺序列出，因此第一个资源是最早部署的那个——通常是其他团队的测试资源或调试副本。在同一批问题中询问要使用哪个候选项，每个候选项提供一个以其文件夹命名的选项，并提供 Use a placeholder；如果用户未回答或处于非交互模式，则保留为 <UNRESOLVED>。仅创建用户选中的 agent、api-workflow 或 business-rule 资源，并调用 uipath-agents、uipath-api-workflow 或 uipath-rules；绝不能根据 SDD 内容推断用户同意创建。其他未命中的类型只能使用占位项。具有相同 I/O 的选定资源可以共用一次构建；I/O 不同则在后续拆分，并由锚定项保留名称；更新 SDD 需要权限。参见 registry-discovery.md § 1c、Create-on-Missing 和 § MUST Confirm。

19. 布局。 仅输出顶层 layout: {}。不要输出节点 position、style、measured、width、height、zIndex，也不要输出边 data.waypoints；不得计算位置。

20. 全局输出 ID。 在第 3 阶段结束时运行一次步骤 12 的检查 8。此项检查为必需项；除非通过，否则不得进入第 4 阶段，也不得用 CLI validate 替代。

21. 不手动编写边。 将 schema.edges 保持为 []；绝不编写 TriggerEdge/Edge 对象。阶段流转由条件提供；第一个阶段使用 case-entered。只读边的结构见 case-schema.md Appendix。

22. 全局事件和 SLA 响应。 将全局外部事件建模为一个中断式次要阶段的 wait-for-connector 条目。明确选择 SLA 响应：notify-only、start-task、enter-stage、exit-stage 或 exit-case。start-task 响应应放在后续任务自身的 sla-status-change 条目上，而不是阶段条目上。是否中断取决于活动工作是停止、暂停还是重新路由；并行监督使用 Interrupting: No，且仍属于次要阶段。sla-status-change 要指定 slaId；只有风险响应才添加 escalationId。如果没有明确指定响应，则风险和违约都作为通知处理。不要在多个主要阶段重复规则。参见 references/sla-response-shapes.md 和 SLA 响应映射。

23. 形式参数 ID。 variables.inputs[].id 和 variables.outputs[].id 必须是由 v 加 8 个字符组成的合成 ID，且不能与 name/var 相同；绝不能复制配套项的名称。在第 3 阶段结束时运行一次步骤 12 的检查 10，并以非交互方式重新生成不合规的 ID。CLI validate 不会检查这一项。参见 global-vars/impl-json.md § Formal-arg slot ID format。

24. 先使用 uip solution init 搭建框架，再在解决方案目录中运行 uip maestro case init。 先运行 cd <SolutionDir>；在 uip solution init 后使用 && 链接命令并不满足此要求，会将项目创建在解决方案目录之外，并自动再搭建一个解决方案。确认 Data.SolutionRegistration.Status 为 Registered 或 AlreadyRegistered。仅当 case init 不可用时，才使用 implementation.md § Step 6 中的 T01 直接 JSON 搭建方法。参阅 case-commands.md § case init。

25. 进行变更前，先阅读该变更所依据的内容。 在首次使用参考资料中的结构、过程、约束或验证规则进行 Write/Edit 之前，先完整阅读说明该内容的章节：通过章节标题（参考资料中的标题，或搜索该术语）找到章节，然后从该标题读到下一个同级标题。无需通读整个文件，也无需出现文件中的 `` 标记。例外——棕地操作指南： 如果某项编辑由 edit-recipes-guide.md 中的操作指南涵盖，只需阅读该指南；仅当指南提及其他参考资料时才需阅读。仅搜索到匹配项、凭记忆判断或参考同级章节均不满足要求。如果所读章节指向另一个章节，也要阅读该章节。上下文压缩后，或无法访问先前的阅读内容时，重新打开相关章节。

26. 标签和任务名称必须唯一。 阶段 data.label 值在整个案例中必须唯一；任务 displayName 值在所有阶段中必须唯一，区分精确内容且不修剪空格，并且不得包含 :。缺少显示名称时，将使用资源名称，并参与唯一性检查。条件 displayName 值在整个案例的四个条件范围内必须唯一，但前端自带的默认名称除外（Entry rule <N>、Exit rule <N>、Completion rule <N>、Stage complete、Stage exit、Tasks completed rule、Previous task completed）。这些名称可以重复，且绝不重新编号。你自己创建的名称，按每种标签类型使用整个案例统一的计数器编号，绝不要按阶段或任务分别编号（case-schema.md § Condition name uniqueness）。在 Phase 1 中分配名称；之后重命名会影响 SDD、计划、ID 映射和以名称为键的引用。

路由

条件	流程
新建案例，已提供 SDD、没有 caseplan，或根据规范重建	绿地： 如有需要，先交接，然后执行 Phases 1–7
已有 caseplan，且意图是定向编辑	棕地： 跳过交接和 Phases 1–7；使用 brownfield.md

棕地流程仍要求拉取最新状态、获得调试许可和 Orchestrator 发布许可，并沿用 Phase 5–7 的约定。

面向用户的路线图

路由完成后、开始详细工作前，只输出一次，不超过五行。不要透露阶段、模式、文件名或实现细节。

• 没有 SDD 的新案例： 1. 我会阅读你的请求并做出设计决策，同时核查你的 UiPath 租户。 2. 提供一份审核材料：案例概览、主要流程、其他路径、SLA 响应、业务规则、资源以及我做出的每项决策——由你确认或修正。 3. 我会不中断地构建和验证，并将完整的技术设计文档保存在旁边供参考。 4. 在任何运行或发布之前，我会暂停并征求你的决定。
• 有 SDD 的新案例： 1. 阅读设计并核实可用的 UiPath 资源。 2. 只问一个问题：直接完成构建，还是在构建过程中暂停并预览？ 3. 制定计划、构建并验证，之后不再打断你。 4. 在任何运行或发布之前，我会暂停并征求你的决定。
• 定向编辑： 1. 拉取最新案例。 2. 应用所请求的变更。 3. 验证更新后的案例。 4. 在运行或发布任何内容之前先询问。

工作流

先确定前置决策，然后自动运行，直到需要征求同意时为止：

需要时进行设计交接 → 阶段 1 规划 → 阶段 2 原型设计 → 阶段 3 实施 → 阶段 4 验证 → 阶段 5 发布 → 阶段 6 调试 → 阶段 7 发布到 Orchestrator。

开始执行时，在交接开始或阶段 1 开始时，展示一次下方对应的启动说明。状态文本必须遵守 Anti-patterns 中的限制。

绿地项目启动说明：

下面是我构建此案例的方式，以及需要您决定的事项：

• 规划 — 我会根据规格草拟任务计划并继续执行；如果您想先审阅，请提前告知。
• 原型设计 — 我会构建可供审阅的案例流程（阶段、任务、触发器、规则、SLA／升级；连接器规则使用存根）。是否在此暂停，以便在 Studio Web 中预览，由您提前决定——开始时只询问一次，构建过程中不会再问。
• 实施 — 我会连接任务输入／输出、连接器架构和已确定的连接器规则详情。
• 验证 — 我会运行验证并修复错误。
• 发布（可选）— 是否上传到 Studio Web，由您决定。
• 调试（可选）— 是否实际运行案例（发送实时邮件／API 调用），由您决定。
• 发布到 Orchestrator（可选）— 是否将案例发布到 Orchestrator，由您决定。

交接时，在前面加上：首先，我会根据您提供的信息设计案例——同时检查您的 UiPath 租户——并展示一份以决策为先的审阅材料，其中包含案例概览、主要流程、其他路径、SLA 响应、业务规则、资源和每项已做出的决策；您确认一次后，我就开始构建；完整的技术设计文档（sdd.md）会保存在旁边供参考。

棕地项目请使用 references/brownfield.md 中的简短引导流程。

设计交接

触发条件是二选一：如果解析后的路径下不存在 basename 包含 sdd 的 .md 文件，则进行交接。如果提示中指定了另一个 SDD basename，请使用 Read + Write 将其复制到 ./sdd.md；不要调用该流程。如果没有指定 .md 文件名，则使用 ./sdd.md。Case Review 之前不要读取规划／插件参考文件，也不要运行租户命令。对于明确要求只做设计、不构建的请求，获得批准后写入 sdd.md，不要使用插件参考、架构、注册表、连接或用户发现，然后停止——不要用计划文件代替构建。由规划器负责的草稿和 sdd-viewer.html 由规划器保管。如果无法使用，请求提供 SDD 并停止。

阶段 1 — 解析

阅读 references/planning.md，以生成：

• tasks/registry-resolved.json：完整的解析审计——仅包含租户身份信息，绝不复制 SDD 的结构或契约。
• 如果在规则 18 中选择 Create：通过允许的子 Agent 路径，将选定的 Agent／API 工作流／业务规则作为解决方案内的同级项构建，确保解决方案存在，注册它们，刷新资源，重新发现并绑定。请参阅 registry-discovery.md § Create-on-Missing。

tasks/ 与 sdd.md 位于同一目录，不得放在解决方案／项目内。除非请求明确要求在构建前停止，否则自动进入阶段 2。先重新读取 sdd.md 和记录文件。

阶段 2 — 原型设计

阅读 references/implementation.md 和 references/phased-execution.md。遵循步骤 6–11.9：

1. 步骤 6：运行 uip solution init，然后在解决方案目录内运行 uip maestro case init（规则 24），接着将 caseplan 转换为计划文件，并使用 case init 生成种子：sdd convert --out（规则 4）。如果已安装的 CLI 没有 case init 或 sdd convert，则使用 plugins/case/impl-json.md 中的 T01 直接 JSON 操作方案作为后备；无论哪种情况，都以此作为根结构的参考。

2. 步骤 6.1：手动、定时器和事件触发器，包括规则 9 占位符；记录触发器 ID。

3. 步骤 6.2：全局变量和参数；In 参数中的 elementId 引用由 sourceTriggers 指定的触发器，若其为空，则引用主触发器。

4. 步骤 6.3：按照 entry-points-sync.md，根据声明的 In/Out 参数同步 entry-points.json。逐字节照抄该参考中的 job-attachment definitions 块——准确复现其中 MimeType.description 的内部引号（单个 \" 转义）；切勿再次转义为 (\\") 或调整引号配对，否则 JSON 会损坏。

5. 步骤 7：阶段。

6. 步骤 9：任务结构；非连接器任务必须包含完整的 data.inputs[]，其值为空；连接器任务只包含 typeId/connectionId；未解析的资源使用占位符。

7. 步骤 11：SLA/升级对象，使用稳定 ID。

8. 步骤 10：所有四种条件作用域；无论解析结果如何，连接器等待条件都使用规范桩。

9. 步骤 11.9：信息性骨架验证，并遵循规则 12 的后备行为。

10. 应用阶段 2→3 的偏好设置。Preview 分支使用资源刷新、经过筛选的解决方案上传、打印 DesignerUrl，以及规定的继续执行确认门；Abort 则写入 build-issues.md 并退出。

阶段 3 — 实现

重新阅读 SDD 的任务详细信息块、tasks/registry-resolved.json 和 caseplan.case（步骤 9.6），然后遵循步骤 9.7、9.8、10.5 和 11.5：

1. 使用 uip maestro case spec 解析连接器架构/默认值。
2. 使用 io-binding/impl-json.md 为所有任务类别绑定 I/O。
3. 原位升级已解析且绑定连接器的条件桩；未解析的连接器保留桩并报告。
4. 解析表达式中的 vars.$xref 标记。
5. 执行已解析资源的生成、保留、resourceKey 和连接器完整性检查。

阶段 3 检查通过后，直接进入阶段 4。

阶段 4 — 验证

在阶段 3 边界运行一次步骤 12。该步骤执行检查 1–15，包括检查 7 旁车文件一致性、检查 8 全局输出 ID 唯一性、检查 9 资源生成/保留、检查 10 形式参数 ID、检查 11 resourceKey 一致性、检查 12 连接器完整性，以及检查 15：每个任务都必须带有非空入口规则（validate 仅会在缺少规则时发出警告）。然后运行完整的 uip maestro case validate。最多重试三次，每次重试前都必须先编辑；第三次失败时，使用 AskUserQuestion 强制停止，并提供以下选项：Retry with fix / Pause for manual edit / Abort。使用步骤 12.1 总结 build-issues.md。

阶段 5 — 发布

提供完成报告，然后使用 AskUserQuestion 强制停止，并提供以下选项：Publish to Studio Web / Skip to Debug（步骤 13）。选择发布后，刷新资源并使用强制输出筛选条件上传，打印 DesignerUrl，然后无论结果如何都继续进入阶段 6。

阶段 6 — 调试

使用 AskUserQuestion 强制停止（步骤 15），并提供以下选项：Run debug session / Continue to publish。选择 Run 后，刷新资源，运行 uip maestro case debug，并在完成后循环询问，直到选择 Continue to publish。绝不自动运行调试。

阶段 7 — 发布到 Orchestrator

硬停止式 AskUserQuestion（步骤 16）：Publish to Orchestrator / Done。选择发布后，按顺序运行：

1. uip solution resources refresh
2. uip maestro case pack <SolutionDir>/<ProjectName> <SolutionDir>/dist --output json
3. uip solution pack <SolutionDir> <SolutionDir>/dist --output json
4. uip solution publish <packagePath> --wait --output json

必须运行 case pack，因为它会创建 caseplan.case.bpmn；validate 不会创建。发布 solution pack 的 .zip，而不是 case 的 .nupkg；从 Data.Packages 读取 <packagePath>，切勿猜测。选择 Done 退出。

参考导航

需求	参考
不使用 SDD 进行设计	uipath-planner Case Design Lane；规则 16
从 SDD 解析资源	references/planning.md
从 SDD 构建 caseplan	references/implementation.md
编辑现有项目	references/brownfield.md；常见编辑：references/edit-recipes-guide.md
阶段约定	references/phased-execution.md
编辑操作	references/case-editing-operations.md
架构	references/case-schema.md
允许使用的 CLI	references/case-commands.md
故障排除	references/troubleshooting-guide.md
注册表解析	references/registry-discovery.md
绑定/表达式	references/bindings-and-expressions.md
连接器集成	references/connector-integration.md
Case 规范输入详情	references/case-spec-input-details.md
占位符	references/placeholder-tasks.md
绑定 sidecar	references/bindings-v2-sync.md
清理孤立的解决方案资源	bindings-v2-sync.md § 清理孤立的解决方案资源
入口点	references/entry-points-sync.md
SLA 响应	references/sla-response-shapes.md

插件索引

结构： case/planning.md、stages/planning.md、sla/planning.md、global-vars/planning.md、io-binding/planning.md 和 logging/impl-json.md。

任务：

Schema type / SDD 值	插件规划参考	CLI 描述类型
process	process	process
agent	agent	agent
rpa	rpa	rpa
action	action	action
api-workflow	api-workflow	api-workflow
function	function	function
business-rule	business-rule	business-rule
case-management	case-management	case-management
execute-connector-activity	connector-activity	connector-activity
flow-process	flow-process	flow-process
http-request	http-request	—（由 sdd convert 写入）
document-extraction	document-extraction	—（由 sdd convert 写入）
wait-for-connector	connector-trigger	connector-trigger
external-agent	connector-activity § External agents and automations	external-agent
external-workflow	connector-activity § External agents and automations	external-workflow
wait-for-timer	wait-for-timer	wait-for-timer

Schema-kebab 是唯一的 JSON 值；插件名称与 CLI 名称不能互换。不受支持的类型包括 wait-for-event。

触发器： manual、timer 和 event。

条件： stage-entry-conditions、stage-exit-conditions、task-entry-conditions 和 case-exit-conditions。

任何条件范围内绑定连接器的规则都需要使用 case spec --type trigger 构建 rule.uipath；即使 CLI validate 通过，Studio Web 中的裸连接器规则仍然无效。请参阅 connector-trigger-impl.md。

反模式

• 不要让常规阶段缺少入口条件。第一个阶段使用 case-entered；其他每个常规阶段都需要一个可到达的前置阶段。边已废弃。对此，validate 会报错（CASE_MGMT_STAGE_ENTRY_CONDITION_MISSING）。
• 不要在此处进行设计，不要在 Case Review 批准前启动 Phase 1，也不要根据摘要版 SDD 构建。规划器负责设计、其他路径分析和模板规范符合性。
• 不要在每个元素之后验证，也不要在中间没有编辑的情况下验证两次。Phase 2 的验证仅供参考；Phase 4 的验证具有权威性，会运行 --strict——不要以默认配置文件下的 Valid 作为完成标准。
• 不要编写 tasks/tasks.md、T 编号任务列表，或任何其他对 SDD 的复述。SDD 就是计划；Phase 2 会通过 sdd convert（规则 4）从中生成 caseplan.case 并完成其余内容，Step 12 的 validate --strict --sdd sdd.md 会据此审查产物。生成的 caseplan.case 是产物，不是复述——此禁令针对文字计划，绝不针对转换器的输出。
• 绝不要一次 Write 写完整个 caseplan.case：sdd convert 会生成该文件，此后的每项更改都必须通过定向 Edit 进行，并保留未修改的同级内容。中断后要重新读取计划和 sdd.md。仍需要写入操作的情况——brownfield 小节重写、case init 不可用时的脚手架——其写入节奏见 case-editing-operations.md § Per-section batch write contract。
• 不要在工具调用之间单独输出旁白。将状态说明与下一次工具调用合并；普通文本控制在 200 tokens 以内；允许列表中的启动说明、硬停止前置说明、完成报告、DesignerUrl 输出和验证摘要控制在 500 tokens 以内。不要使用 Building、Composing、Writing、Drafting、Generating、Now I'll、Next、Approach、Strategy、Plan、Let me 或同义表达来宣布即将执行的操作。
• 保留任务的顺序语义。顺序模式使用有序的 data.tasks 集合，并为每项任务设置一个 runs-sequentially 规则；不要同时添加 current-stage-entered。只有独立工作才使用并行的 current-stage-entered，只有必须汇聚的任务才使用 selected-tasks-completed。事件触发的任务使用事件/条件规则；手动触发/临时任务使用一条 adhoc 规则、isRequired: false，且不添加其他入口事件。adhoc 是激活模式，不是任务类型。
• 将次级阶段建模为中断式异常通道：case-management:Stage、data.stageType: "secondary"、isRequired: false，并在阶段和入口上设置 Interrupting: Yes。仅并行 SLA 监督使用 Interrupting: No。使用 return-to-origin；不要将次级阶段连接成常规流程，也不要将其计入必需完成项。
• 不要在主要阶段之间重复全局事件或 SLA 规则。完成 Case 需要根级 metadata.caseExitRules[] 规则，并设置 marksCaseComplete: true；仅完成阶段并不足够。未完成 Case 的结果使用 marksCaseComplete: false。
• 不要编辑生成的 caseplan.case.bpmn；不要将 caseplan.case 放在 content/ 下；不要伪造条件 SLA 表达式语法——对于没有命名空间的 =js: 标识符，validate --strict 会报错（STRICT_JS_UNKNOWN_IDENTIFIER）；在执行解析条件前，用自然语言描述条件。
• 不要将 tasks/ 放入解决方案/项目中；它应与 sdd.md 并列。
• 除规则 16 的设计交接，以及规则 18 通过门控选择的内联 Agent/API 工作流/业务规则创建外，不要自动调用其他技能。不要为设计、草稿定稿或仅包含计划的文档启动子 Agent。
• 不要读取已安装的 CLI 来解读其自身输出。validate 的发现会指出元素路径和修复方法；修复应在 caseplan 中，或在负责该结构的参考文档中，而不是在 node_modules/@uipath/**/dist 中。检索打包代码块，或用 node -e 重新实现比对逻辑来预测结果，都会把轮次预算耗在工具上，而不是计划上——某个夜间任务曾在这方面耗掉 151 条命令中的 56 条，最终超时。如果重新读取指定元素及其参考文档后仍不清楚某项发现，就按消息所指内容进行修复并继续；如果问题仍然出现，请通过 /uipath-feedback 报告。
• 遇到问题时使用 uipath-feedback。

遇到问题？ 使用 /uipath-feedback 发送报告。