uipath-rpa

UiPath RPA Assistant

创建、编辑、管理、验证、构建、运行、调试、测试和发布 UiPath 编码（C#）及 XAML 自动化流程。一套 UIA 活动集适用于 Windows/macOS、桌面/网页、带锚点的严格/模糊选择器、Computer Vision 和语义匹配；uia-configure-target 用于选择路由并在路由之间自动回退。

务必读取引用的文件。 本 SKILL.md 为你提供导航，不可替代引用文件。当规则、任务导航条目或章节指向某个文件时，操作前请打开并完整阅读；不要使用 grep、略读、运行 --help 或以已有知识代替。目录可能会指定定向查找（例如，运行 Grep ^## 查找目录，或运行 <command> --help 查看标志）；只需阅读匹配的章节。指向某个章节的引用（file.md § Section）表示读取该章节，直到下一个同级标题。跳过或只读部分引用内容通常会导致构建/运行时错误。

何时使用此技能

适用于项目、工作流、测试、源文件、配置、依赖项、活动、验证/构建/运行/调试、断言、Integration Service 连接器，以及桌面/网页 UI 自动化。

UIA 先决条件

UIA 工作需要安装不低于最低版本的 UiPath.UIAutomation.Activities。版本、检查、发现/安装命令，以及升级同意矩阵（绝不可在未告知的情况下安装或升级 UIA）仅见 uia-starter-guide.md § UIA Prerequisites；不要硬编码版本。

前置条件：项目上下文

开始工作前，检查项目目录中的 .claude/rules/project-context.md。如果文件存在且内容仍是最新的，则继续。如果文件缺失或过时，请运行跳过门槛检查；只有在未触发跳过条件时，才执行 environment-setup.md § Project Context Discovery：元数据注释数与当前计数的对比、60–70% 阈值、全新项目/空项目/未改动脚手架的跳过门槛、特定宿主的发现 Agent 选项，以及 context-files:/SKIP: 处理方式。Agent 会写入上下文文件；不要重新读取或改写这些文件。每个会话最多派发一次发现任务——重用正在运行的 Agent 或其生成的结果；后续步骤若要求发现项目上下文，应整合之前派发的任务，绝不能再启动第二个。如果触发跳过门槛，则不要使用发现 Agent；请在构建后按照该章节自行编写两个上下文文件。

步骤 0：解析 PROJECT_DIR

创建/修改任何内容之前，请使用 environment-setup.md § Step 0.1 解析项目。查找 project.json 以确定 {projectRoot}；标准流程无需检查 Studio Desktop。首次调用 uip rpa 时，它会自动启动无头 Studio（UiPath.Studio.Helm NuGet）。只有执行 files diff 和 focus-activity 时才需要 Studio Desktop。编码 UI 的 ObjectRepository.cs（Descriptors.*）会在某个 [Workflow]/[TestCase] .cs 文件存在后，于按文件执行 validate 时重新生成（§ Capture-First Fast Path step 2；coded/operations-guide.md § Configure UI Targets）。

项目类型检测

解析 PROJECT_DIR 后，先检查 project.json 中的 targetFramework：

• "Legacy" 或旧项目中缺少该字段：Legacy 模式。停止并遵循 references/legacy/legacy-mode-guide.md。使用独立的 uip rpa-legacy、.NET Framework 4.6.1、不带“X”的经典活动以及 mscorlib；现代规则不适用。
• "Windows" 或 "Portable"：现代模式；使用 uip rpa。Windows 表示仅限现代 Windows，不是 Windows-Legacy。

仅在 Legacy 模式下使用 uip rpa-legacy，绝不能因为 uip rpa 不可用而使用它；它可能以退出码 0 打包现代项目，因此应修复 uip rpa。

现代模式：编码工作流 = .cs 中有 [Workflow]/[TestCase]，且除脚手架生成的 Main.xaml 外没有工作流 .xaml；XAML 工作流 = 有工作流 .xaml，且没有编码工作流 .cs；两者都有 = 混合模式，请参阅 coded-vs-xaml-guide.md 并按请求选择；两者都没有 = 新项目，默认使用 XAML。只有在明确提出“coded”“.cs”“C# workflow”“coded test case”或触发编码专属条件（DTO/自定义模型/可进行单元测试的业务逻辑）时，才切换到编码模式。否则，“创建工作流”“自动化 X”“构建自动化”均指 XAML。通过任务导航进行处理；Legacy 遵循其指南。

创作模式选择

沿用现有模式；新建或有歧义的工作默认使用 XAML。只有在用户明确提出，或符合下表中的编码专属条件时，才切换到编码模式。

场景	模式	原因
标准 RPA（Excel、电子邮件、文件操作）	XAML（默认）	直接支持活动，无需编写代码
UI 自动化	XAML（默认）	完整支持活动；也可通过 uiAutomation 服务使用编码模式
Integration Service 连接器（XAML）	XAML	IS 连接器活动使用 XAML 专属的动态活动配置
子任务没有匹配的活动	编码回退	编写一个小型 .cs 文件，通过 XAML 中的 Invoke Workflow File 调用
复杂数据转换、HTTP、解析	编码	相比嵌套的 XAML 活动，C# 更自然
想要调用 PowerShell 脚本	编码	优先使用编码工作流。如果确实需要 PS（管理 cmdlet、现有 .ps1），请使用 InvokePowerShell<T> 活动——绝不要使用 Invoke Process + powershell.exe。请参阅 powershell-interop-guide.md
自定义数据模型 / DTO	编码源文件	XAML 无法定义类型——使用纯 .cs 文件，无需 CodedWorkflow 基类
带断言的单元测试	编码测试用例	使用 [TestCase] 实现 Arrange/Act/Assert
在 Studio Web 中编辑的项目，包括 Flow 解决方案启动的流程	XAML，VB 表达式	Studio Web 无法打开包含编码工作流或 C# 表达式的项目（通用规则 2a）
用户明确要求编码 / XAML	用户选择	绝不要质疑明确的偏好

UI 自动化边界

对于打开应用 / 浏览器、点击、输入、抓取可见 UI 内容、提交表单或验证 UI 状态，只能使用 UiPath UIA：XAML NApplicationCard 加 UIA 活动；编码模式下使用 uiAutomation.Open/Attach 加对象存储库描述符；或者，在包的编码创作指南 § Selector-Only Targets 允许的情况下，使用 CLI 捕获的选择器，通过 TargetAppModel / Target.FromSelector（编码模式）。不得替换为 InvokeCode、PowerShell、Selenium、Playwright、CDP、原始 DOM JavaScript、HTTP 表单提交或外部浏览器驱动程序。编码回退仅适用于非 UI 辅助操作。如果目标配置不可用，请使用文档说明的 UIA 指示路径，绝不要采用外部捷径。

在进行任何 UIA 操作前，请阅读 {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md § Mandatory: Generate Targets Before Writing Any UI Code；根据规则 7 完整阅读该部分。该指南规定了禁止使用的工具列表、仅限 UIA 的探索方式，以及 InvokeJS/InjectJsScript 的例外范围。

占位符选择器存根模式（无法访问实时应用时）

无法访问实时应用时，应生成带占位符选择器字符串和 TODO Indicate 标记的真实 UIA 活动，绝不能使用 Log 存根：使用真实的 NTypeInto、NClick、NGetText、NApplicationCard 等；将 TODO Indicate 放在 XAML DisplayName 中，或放在相邻的代码注释 // TODO[Indicate] 中。此模式适用于 XAML 和代码；请阅读 uia-starter-guide.md § 占位符选择器存根模式。此模式无需 UIA 包或 CLI。不要创建 UI 步骤仅用于记录意图的工作流。混合编排方式为 Main.xaml → InvokeWorkflowFile → 代码辅助程序；完整流程图、InvokeCode 提取规则和模式请参阅 coded-vs-xaml-guide.md。

捕获优先快速路径

对于对话框／表单自动化，或根据手动步骤编写的 UI 测试，请将编写前置内容推迟到捕获之后：

1. 根据规则 7，完整阅读 uia-starter-guide.md、UIA 包核心指南，以及其中要求阅读的目标捕获编排参考资料。
2. 仅限代码：在首次调用 uip rpa（包括窗口基线）之前，安装所有所需的活动包，并编写一个空的 [Workflow] public void Execute() { } 类（命名空间遵循规则 17）。首次加载宿主时会对 .local/.codedworkflows/ 创建快照；若未安装包或未编写存根，可能会遇到 CS0246 'CodedWorkflow'。运行 uip rpa project close --project-dir "<PROJECT_DIR>" 可清除该快照。之后的 validate 只会刷新 ObjectRepository.cs；CodedWorkflow.cs 服务访问器和 workflows.X 跨调用仍为首次加载时的快照，因此，之后安装包或新增被跨调用的工作流时需要重新生成；参阅 coded/operations-guide.md § 配置 UI 目标。
3. 按照包指南中的“窗口基线”操作：列出一次顶层窗口，并决定是否启动应用。
4. 从 Test Manager、PDD 或脚本中整理手动步骤。将每个“Click/Enter/Select/Verify”映射到一个 OR 元素，按屏幕分组（包指南 § 从手动测试步骤捕获），并立即决定每个元素和屏幕的名称——捕获时照原样使用这些名称。
5. 使用 uia-configure-target 按屏幕逐一捕获，并推进屏幕（包指南 § 多步 UI 流程）；仅在屏幕边界处编写内容，绝不要在同一屏幕的调用之间编写。
6. 整合已分发的上下文发现（最多一次，绝不再次启动），完整阅读对应模式的编写指南，然后编写并验证。仅限代码：验证一次以重新生成 ObjectRepository.cs，阅读该文件，并将每个目标引用为 Descriptors.<App>.<Screen>.<Element>；使用该文件中的成员名称，绝不要使用捕获时的 OR 名称；该文件缺失时，绝不要按字符串目标名称编写。

如果任务没有 UI 界面（数据转换、IS 连接器调用、无头文件／电子邮件自动化），请跳过此路径。如果任务有 UI 界面，但没有可供捕获的实时应用（未安装应用、没有 GUI、捕获工作推迟给开发人员），也请跳过此路径——改用 § 占位符选择器存根模式。窗口基线并不能证明应用／GUI 存在；请另行确认或询问。

会话预热

预计需要调用多次重量级 uip rpa 时，请在会话开始时于后台运行：

uip rpa activities find --query log --output json > /dev/null 2>&1 &

首次重量级调用约需 22s，validate／build／run／activities get-default-xaml／analyzer-rules list 会共享此开销；预计只有零次或一次重量级调用时，请跳过。在 Windows PowerShell 中，使用 Start-Process powershell.exe -ArgumentList ...（而不是 pwsh），因为 & 不会在后台运行；绝不要对 uip 或任何 .ps1 使用 Start-Process -FilePath（Notepad 会打开它们）。

关键规则

通用规则为 1–12。编码规则 13–19 见 coded/codedworkflow-reference.md § Critical Rules — Coded。XAML 规则独立编号为 16–24/25：16–21a 和 24–25 见 xaml/xaml-basics-and-rules.md § Critical Rules — XAML，22–23 见下文。[Coded]/[XAML] 用于区分重复编号；交叉引用（“Common Rule 10”“Rule 21”“Rule 24”）始终指向唯一编号的规则。

通用规则（两种模式均适用）

1. 绝不在未确认项目不存在时创建项目。 检查明确指定的路径、项目名称，然后检查 CWD 中的 project.json；仅当没有匹配项且用户明确要求创建时才创建。

2. 始终使用 uip rpa init；绝不手动编写 project.json 或脚手架。运行 init 前，如果用户指定了模板（“REFramework”“基于 X 模板”）或行业/领域模式（SAP、ERP、银行、主机），运行 uip rpa templates search --query "<term>" --output json，并遵循 environment-setup.md § Template selection：绝不默默选择 Marketplace；展示候选项并询问用户；如果 Official 和 Marketplace 都有匹配项，则询问用户。 2a. 每次运行 uip rpa init 都必须明确传入 --target-framework 和 --expression-language，绝不能省略。 创建后两者均不可更改（规则 23）；省略 --target-framework 会默默创建 Windows 项目。对于跨平台/非 Windows 运行环境（Linux、容器、无服务器）或 Studio Web，选择 Portable；对于使用仅限 Windows 功能（Excel COM、经典 Office、WPF / PresentationFramework、仅限 Windows 的 UIA）的 Windows 运行环境或 Studio Desktop，选择 Windows（Studio Web 无法编辑 Windows 项目）。Studio Web 仅在所有工作流均为使用 VB 表达式的 XAML 时接受 Portable。出现的错误为 20042 Project has coded workflows 和 20021 ... unsupported programming language: CSharp，此时项目只能在 Studio Desktop 中打开。要求同时满足跨平台运行环境和仅限 Windows 的功能，属于矛盾需求——应明确指出。Windows - Legacy 是最后手段（用户明确要求或确实需要 .NET 4.6.1；绝不能仅因使用 VB.NET 或非“X”经典活动就推断需要）——应在 Legacy 模式下创建，而不是使用现代 init。没有明确信息时，通过 AskUserQuestion 询问选择 Windows 还是跨平台，并围绕运行环境主机来表述。--expression-language 默认值为 VisualBasic；仅在用户明确要求时使用 CSharp。init 会写入已安装 Studio 的 dotNetVersion；不受支持的机器人版本会在运行活动前报错：Error converting value "<VERSION>" to type 'UiPath.Shared.DotNetVersion'；此时将 dotNetVersion 设为机器人版本（拒绝 net10.0 时使用 net8.0），然后重新构建并发布。

3. 分阶段验证。 每次创建或编辑后，运行 uip rpa validate --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json，直到错误数为 0；每轮只修复一项。所有修改过的文件均通过验证后，运行 uip rpa build "<PROJECT_DIR>" --output json，直到构建无错误。validate 会检查 XAML 结构、引用和架构；build 会检查所有项目工作流、分析器规则和打包流程。两者的分工见 cli-reference.md § What each phase covers。如果 build 报错，请从构建的详细日志中找到每条错误对应的文件，并对其重新运行 validate --file-path，以检查编译错误。每个文件的验证循环和单独的构建循环最多尝试 5 次。冒烟测试不能代替构建；构建通过后，优先使用 run --skip-build（cli-reference.md § Smoke Test）。不要将 uip rpa analyzer-rules list 作为编写前置步骤；仅在收到请求或反复违反某类规则后使用（不带范围的调用可能需要一分钟或更久；cli-reference.md § analyzer-rules list）。警告不影响交付：只要 validate 和 build 均无错误，即可交付；仅在收到请求或警告可能影响验收时调查。按规则 ID 报告警告数量；不要为警告消耗验证尝试次数。预期的 UIA 警告（verification-feature、Automation Hub URL、重复显示名称）见 cli-reference.md § Expected non-defect warnings。完整阅读错误信息。参见 cli-reference.md § Validation Iteration Loop。

4. 始终验证所有修改过的文件，并在声明完成前确认项目构建成功。 仅验证通过并不足够；对于有可观察输出的工作流，最后运行一次 run 并检查输出（execution-maps-guide.md § Gate ≠ runtime proof）。 4a. 使用文件工具：Write 完整写入每个 .xaml/.cs 文件，之后再用 Edit 修改；绝不使用脚本/模板生成工作流文件：验证和修复必须针对单个文件进行，并且 Edit 可以保留对象库链接，重新生成则不行。对于相似文件，可并行执行多个 Write，使用辅助工作流，或复制已验证的文件后再用 Edit 修改差异。 4b. 只编写可调用的单元：提取重复使用或可独立阅读的代码组；单个活动或简短赋值应内联。不要仅为传递参数而封装单个活动。活动所需的作用域（应用程序卡片、附加操作）不是提取代码的理由：在步骤处打开作用域，并围绕连续操作同一窗口的步骤。

5. 对于 Orchestrator 集成、UIA 和文档，优先使用 UiPath 内置活动；对于纯转换、HTTP 和解析，使用原生 .NET/第三方程序包。

6. 使用相关活动或服务之前，务必确保所需程序包依赖项已写入 project.json。 6a. 序列化之前，只移除 uip rpa cleanup --dry-run 列出的未使用依赖项（cli-reference.md § packages install）；程序包可能是某些功能的唯一提供方，例如 IntelligentOCR.StudioWeb 中的 MergePDFs。编写活动标签前，运行 uip rpa activities find --query "<verb>" --output json，使用返回的 ClassName，绝不根据显示名称推导标签（common-pitfalls.md § Common Activity Name Confusions）。

7. [UIA] 使用任何 UIA 活动之前（<uix:N*>、uiAutomation.* 或 Descriptors.*），必须分两步读取 references/uia-starter-guide.md，不得直接完整读取：先用 Grep 搜索 ^## Conditional Policies，再从该行开始使用 Read 并设置 limit；仅在适用时加载条件策略章节。然后完整读取程序包核心指南，并在编写前，按照其 § Documentation 的指引，完整读取相应模式的编写指南。“简单” UI 也不例外。绝不手写选择器；只能使用 uia-configure-target；仅编写选择器的代码可跳过 OR 注册，但不能跳过捕获。迁移例外见 uia-starter-guide.md § Placeholder-Selector Stub Pattern。先验证前置条件（规则 7a）；缺少程序包指南即未达到最低要求。入门指南规定了运行/调试、运行时选择器恢复、存根交付物和 UI Library 发布流程。 7a. [UIA] 在使用 uia-configure-target 之前，先验证前置条件。 按照 uia-starter-guide.md § UIA Prerequisites 操作，包括取得许可；如果程序包版本低于最低要求，或缺少核心指南，则无法使用 uip rpa uia，捕获/指示也依赖它。请求安装/升级；如果用户拒绝或无法安装/升级，则使用带有 TODO Indicate 的真实占位活动，不得改用其他路径。只有在存在兼容程序包、但捕获无法识别元素时，才允许仅使用指示；在计划标题中记录 UI capture: indication-only。如果扫描持续失败，必须先排除 Windows 处于锁定/非交互状态的可能（若显示 LogonUI，先解锁）；只有在已解锁的交互式会话中仍失败，才使用占位活动。

8. 以编程方式解析 CLI 输出时，始终使用 --output json。 8a. run/debug start 的判定依据是 Data——绝不能仅依据外层 Result，也绝不能依据日志行的级别。根据键识别后端。无头 Helm：Data = {output, hasErrors, errorMessage, profiling, debugState, debugDetails}；只有在 hasErrors 为 false、errorMessage 为 null，且 debugState 为 null 或 "Completed" 时才算通过。run 出错时，外层 Result: "Failure"，Message 中包含 JSON 字段；debug start 出错时，返回 Result: "Success"、debugState: "Suspended"，异常信息位于 debugDetails 中；请取消或继续运行中的会话。Studio Desktop：Data = {output, errors, logEntries, debugState}；只有在 errors 为空且 output 为 "Session ended" 时才算通过。缺少入口点时，可能返回 Result: "Success"、空的 errors，以及 output: "Failed to open the file <path>"；两项条件必须同时满足。把 Result: "Success" 当作通过判定，会导致两个后端上的故障工作流都被误报为成功。成功的工作流也可能输出 Error/Warning 级别的日志消息；这些是工作流数据，并不表示失败。请读取打印出的信封：对 run/debug start 不要使用 --output-filter（如果筛选条件指定了当前后端不存在的键，则工作流运行后调用仍会失败），也绝不要使用 | tail/| head；Helm 日志位于信封之前，Desktop 的 logEntries 可能很长。参见 cli-reference.md § Capturing the verdict、cli-reference.md § Reading run / debug results 和 debugging.md § Output Format。

9. 如需利用/复用共享库，请搜索租户源——不要搜索本地文件系统或 NuGet.org，也不要循环尝试关键词组合：uip or libraries list --limit 500 --output-filter "<JMESPath>" --output json。如果筛选结果为空，请使用其回退分支，绝不要更换关键词继续搜索。如果 SDD 记录了 §16 “Shared libraries referenced”，或用户先前表示不使用共享库，则跳过。请遵循 tenant-library-search-guide.md。

10. 在 project.json → designOptions.fileInfoCollection 中注册每个测试用例，适用于 XAML 和代码两种形式。必需键、GUID 格式、架构、dataVariationFilePath 和代码形式的 publishAsTestCase 见 references/testing-guide.md § project.json Registration 和 assets/json-template.md。

11. 测试用例采用 Given-When-Then 结构；参见 references/testing-guide.md § XAML Test Case Structure，其中的导言会指引你查看代码形式对应的 coded/operations-guide.md。

12. 使用 uip rpa activities find --query "<event>" --output json 识别触发器，并读取 isTrigger 和 triggerType。集成触发器（true、"integration"）必须置于 Main.xaml 根 Sequence 的首位，绝不能放在 ui:TriggerScope 中；将 Result 绑定到工作流作用域变量，并将其余内容用作处理程序。IS 程序包（Mail/GSuite/O365/Salesforce/Jira/Slack/ServiceNow/任何 *.IntegrationService.Activities）必须设置 ConnectionId；Orchestrator 原生的 TimeTrigger、QueueTrigger、ManualTrigger 则不需要。本地触发器（true、"local"）可在新作业中置于根节点首位，也可在进程内机器人中置于 <ui:TriggerScope.Triggers> 中，并将处理程序放在 <ui:TriggerScope.Action> 中；两种放置方式都有效——请根据运行时模型选择；不需要连接资产。对于未知类型（例如未来的 "scheduled"），必须查阅随附文档并询问用户。不要自行假定放置位置。现有 TriggerScope 内容必须是本地触发器；如果其中存在集成触发器，则该工作流有误——请告知用户。根节点内容可以是任一类型，因此请检查 triggerType。有关示例、SchedulingMode 参考、触发器活动目录，以及编辑现有 ui:TriggerScope 工作流的步骤，请参见 trigger-pattern-guide.md。

目标预检（两种模式）

**Studio Web 交付的是 Solution，而不是裸项目。**Studio Web 仅接收 Solution；在 SW 的任一工作区标签页中，裸项目文件夹都不可见。相关信号：“Studio Web”“SW”“上传到 Web”“浏览器编辑器”“云工作区编辑”。照常构建，然后交由 uipath-solution 处理：uip solution init <NAME> → uip solution projects import "<PROJECT_DIR>" --solutionFile <SOLUTION>.uipx → uip solution upload "<SOLUTION_DIR>"。交付 Solution。裸项目仍可用于本地 uip rpa run 和 Orchestrator uip rpa pack → uip rpa publish。

执行规范（两种模式）

执行直至完成；计划任务尚未完成时，不要宣称工作已完成。如果引用或发现了 docs/plans/*.md，请在开始工作前以及每个检查点阅读其标题。Execution autonomy: autonomous 表示持续执行，直至每个复选框都变为 [x]，或出现明确的计划停止条件。interactive 或没有计划时，请自行判断并确认重要决策。汇报前，重新阅读并列出所有未勾选的复选框；除非出现停止条件，否则继续执行。成本、调用次数、暂停、部分可用性和复杂性都不是停止条件。已做出的计划决策具有权威性。如果计划已指定结构、文件数量、选择器策略或捕获方式，不要通过 AskUserQuestion 询问这些问题。

错误处理（两种模式）

对失败后需要区别处理的每次外部交互使用 Try/Catch；将输入错误归类为 BusinessRuleException（不重试，需要人工处理），将瞬时故障归类为系统异常（重试后再升级处理）。在处理方式有差异的地方捕获，不要围绕每个活动都添加捕获；UI 活动本身已会等待，并在出现“找不到元素”时失败，因此不要用 Check App State 对其进行保护（UIA 包指南中的 不必要的 Check App State）。不要对纯逻辑代码一概使用 Try/Catch，也不要让 Catch 留空。使用 Rethrow，不要使用 Throw New Exception(ex.Message)，以保留堆栈跟踪。开始韧性处理前，请通读references/error-handling-guide.md，了解异常分类、Retry Scope 次数/间隔、ContinueOnError、屏幕截图、Global Exception Handler 框架/注册/判定、状态恢复、事务边界、避免重复创建/部分写入的幂等/补偿写入、脱敏，以及队列/Retry-Scope/GEH/作业各层的重试责任归属。

执行图（两种模式）

每次构建/编辑都遵循 execution-maps-guide.md：该指南规定了助手轮次的批处理方式（新建项目 ≤5，现有项目改造 ≤5；包括陷阱审查轮次）。在一个轮次内，使用 && 在同一个 Bash 中串联有依赖关系的 uip 调用；并行执行互不依赖的 Bash/Read/Edit；只有在需要标准输出或突变结果时才拆分。规则 21 的卡片外发现要并行展开：所有 K 个 find 并行，然后读取所有 K 份文档，再执行所有 K 个 get-default-xaml——绝不一次只执行一个活动。不要跨越 templates search → init、同意/AskUserQuestion，或 UIA 状态推进/指示进行批处理；这些操作必须遵循 UIA 指南中针对每个屏幕的关卡。

编码专属规则

13–19. [Coded] 在任何编码工作流、测试用例或源文件开始之前，通读 coded/codedworkflow-reference.md § Critical Rules — Coded。同一文件还包含 § Coded Quick Reference（文件类型、服务到包的映射、模板）和 § Task Navigation — Coded。

XAML 专属规则

16–21a、24–25. [XAML] XAML 的关键规则见 xaml/xaml-basics-and-rules.md § Critical Rules — XAML — 下方规则 22 要求完整阅读该文件；在开展任何 XAML 工作前，你就必须先读完该文件，其中包含这些规则。该文件还包含 XAML 任务导航和快速参考。 22. [XAML] 生成或编辑任何 XAML 前，必须完整阅读 references/xaml/xaml-basics-and-rules.md — 在整个流程的第一轮中，与卡片阅读一并执行一次完整的 Read（在此之前不进行任何查找；该文件仅包含必读内容）。 每项操作／活动对应的目录（编辑操作、参考示例）位于 references/xaml/xaml-editing-catalog.md，仅按条目加载 — 使用 Grep ^###，再 Read 与当前操作／活动匹配的条目；不确定时就读。然后，在首次执行 Write／Edit 前，对照 references/xaml/common-pitfalls.md 检查计划。 common-pitfalls.md 是由互不依赖的注意事项章节组成的目录 — 不要从头到尾通读：列出其标题（对该文件执行 Grep ^## — 也在第一轮中执行，无需先有任何输出），然后在下一轮 Read 所有标题与即将编写的工作流中的活动、属性或功能相匹配的章节。不确定某章节是否适用时就读。这是编写时的关卡，不只是用于排查问题 — 先查阅该文件，比之后调试 validate 无法发现的问题更省事。轮次安排固定，由 execution-maps-guide.md 指定：标题列表在 T1 中，章节 Read 在 T2 中，因此这道关卡只需一轮，不必为每个文件都执行一次 grep→Read。 23. [XAML] 绝不更改现有的 expressionLanguage 或 targetFramework。根据通用规则 2a，这两项不可变，且适用于整个项目。不要就地转换；请确认并遵循 environment-setup.md § Project Conversion：先备份，再执行全新的 init，重新创建所有工作流，仅在用户同意后删除备份。

任务导航

我需要……	模式	阅读以下内容
使用 Legacy	Legacy	legacy/legacy-mode-guide.md — 入门指南。以下现代模式规则不适用。
规划构建回合	两者	execution-maps-guide.md — 任何构建／编辑流程都先阅读此文档
选择代码／XAML 或混合模式	两者	coded-vs-xaml-guide.md → environment-setup.md § Designing Project Structure
创建项目	两者	environment-setup.md § Step 0.3
任何 XAML 编写／编辑任务（工作流、测试用例、Flowchart/StateMachine/LRW、常见活动、Data Fabric、IS 连接器、触发器、XAML 故障排查）	XAML	xaml/xaml-basics-and-rules.md — 阅读规则 22；其余内容参阅 § Critical Rules — XAML 和 § Task Navigation — XAML
任何代码编写／编辑任务（工作流、测试用例、源文件、IS 连接器、NuGet、API 发现、代码故障排查）	Coded	coded/codedworkflow-reference.md — 其余内容参阅 § Critical Rules — Coded 和 § Task Navigation — Coded
数据驱动测试	两者	testing-guide.md § Data-Driven Testing 以及规则 10
Test Manager 设置	两者	cli-reference.md § Test Manager — uip rpa tm connect / set-default-project
错误处理／弹性（Try/Catch、Retry Scope、BusinessRuleException、ContinueOnError、出错时截图、Global Exception Handler、恢复应用状态、事务边界、幂等性／避免重复创建、队列与本地重试的归属）	两者	error-handling-guide.md
UI 自动化	两者	UIA 包指南 {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md
共享 OR 选择器／UI 库	两者	uia-starter-guide.md § Object Repository as a Published UI Library
运行／调试 UIA	两者	uia-starter-guide.md § Running UI Automation Workflows
操作捕获的控件	两者	UIA 包指南 § Control-Specific Interaction Patterns
Excel/Word/Mail 等	两者	.local/docs/packages/{PackageId}/，备用路径为 references/activity-docs/{PackageId}/{closest}/
操作数据（DataTable/LINQ、字符串、RegEx、DateTime、集合、JSON）	两者	data-manipulation-guide.md
检查 IS 触发器生命周期	两者	trigger-pattern-guide.md § Connection Handling 和 § Server-Side Filtering
构建／运行／验证	两者	cli-reference.md — 按命令分类的目录，切勿从头到尾阅读：Grep ^## ，阅读所用命令的章节以及 § Reading run / debug results
分析缓慢的工作流／验证 UI 自动化的正确性	两者	debugging.md § Profiling Workflow Performance
在远程计算机上设计／调试／运行（Orchestrator 无人值守机器人 — Live Authoring 与 Remote Run Only、remote configure/status/start/stop、--remote 调试／运行、文件传输、远程 shell 命令）	两者	remote-session-guide.md
打包／发布	两者	cli-reference.md § Pack & Publish to Orchestrator
分析器规则	两者	cli-reference.md § analyzer-rules list
查找租户库	两者	tenant-library-search-guide.md
编写／发布库	两者	library-authoring-guide.md
调用 PowerShell	两者	powershell-interop-guide.md
Data Fabric 实体	两者	cli-reference.md § Data Fabric Entities
项目结构	两者	environment-setup.md § Project Structure Reference

模式包

XAML 规则、快速参考、导航、创作、结构以及逐项编辑目录：xaml/xaml-basics-and-rules.md 和 xaml/xaml-editing-catalog.md。编码规则、快速参考、文件类型、服务/包映射、模板、导航和基类：coded/codedworkflow-reference.md。

解析包和活动文档

步骤 1 — 确保已安装该包

检查 project.json 依赖项。查询时始终使用 --include-prerelease；预览版可能包含必需的活动、签名和文档。如果已安装，请记录其版本并查询可用版本。如果存在更新的稳定版/预览版，请告知用户：说明已安装的版本、最新可用版本，以及较新的包能为活动生成提供最佳支持；询问是否升级；切勿强制升级。如果已经是最新版本，继续执行步骤 2。如果尚未安装，请安装查询返回的最新版本（允许预览版）：

uip rpa packages versions --package-id <PackageId> --include-prerelease --project-dir "<PROJECT_DIR>" --output json
uip rpa packages install --packages 'id=<PackageId>,version=<LATEST_VERSION>' --project-dir "<PROJECT_DIR>" --output json

步骤 2 — 查找活动文档

首先直接读取 {PROJECT_DIR}/.local/docs/packages/{PackageId}/activities/<Activity>.md；直接读取失败即为存在性检查。Glob/Grep 会跳过被 git 忽略的 .local/，不能证明任何内容；使用 ls 列出确切目录。切勿遍历目录树。如果不存在，请使用 references/activity-docs/{PackageId}/ 下最接近已安装版本的文件夹。

UI 自动化参考

技能参考负责前置条件/版本门控、运行/调试编排、占位交付物和 UI 库发布。已安装的 UIA 包 {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ 负责创作、捕获、CLI 语法、活动属性、编码 API、运行时恢复以及其捆绑的 uia-configure-target；它与版本同步，发生差异时以该包为准。

对于 UIA，首先阅读 uia-starter-guide.md。该包的 ui-automation-guide.md 是完整入口，并指向目标捕获、任务指南、CLI 清单、活动属性、编码 API、恢复和捆绑技能；请通过确切路径的 ls 或直接读取来验证，切勿使用 Glob/Grep。

完成输出

在报告“完成”之前，验证计划是否已完成：重新阅读 docs/plans/*.md；如果是自主执行且仍有未勾选项，且没有停止条件，则继续；如果因停止条件而停止，请指出该条件；如果是交互式执行，请报告状态。仅保存符合 execution-maps-guide.md § Cross-session memory 要求的记忆模式；对于卡片涵盖的活动，首次尝试即通过所有检查不符合任何保存条件。如果存在持久记忆，请在最后一轮并行写入符合条件的记忆、上下文文件和报告；之后不得再运行任何操作。

完成后，请报告：

1. 已完成的工作 — 创建、编辑和删除的文件路径。

2. 验证状态 — 每个已修改文件的 validate 结果，以及项目级 uip rpa build 结果。只有两者都干净，才能声称已验证；如果自上次编辑后未运行构建，请说明这一点。

3. 计划完成情况 — 已勾选的 [x] 任务和每个剩余的 [ ] 任务，并注明其停止条件条目或“尚未到达”。

4. 如何运行 — 适用的 uip rpa run 或 uip rpa debug start 命令。

5. 后续步骤 — 连接、OR 元素、占位内容及其他后续操作。

6. 遇到问题？ — 如果发生问题，请说明：“如果遇到异常，请使用 /uipath-feedback 发送报告。”

除非所有计划任务都已勾选，否则不要说“已完成”、“完成了”、“结束了”或“自动化已构建”；否则请说“部分完成”、“停在 ”或“受 阻止”。