uipath-insights

推理预算

• 根据步骤难度调整推理力度，并优先采取行动。对于机械性步骤，如果某条命令已经能完成任务，就运行命令并查看输出，而不是重新推导。
• 将深入、延展的推理留给无法通过命令判断的事项：数据对用户意味着什么、失败率是否重要，以及证据无法证明什么。
• 这些规则都不能成为缩短答案的理由。完成任务要求的每个步骤；预算规则与完整性发生冲突时，以完整性为先。这些规则旨在减少返工，而非减少必要工作。

工作方式

• 先理解，再决定。 行动前先阅读此 SKILL.md 和 Shared Workflow 中的子命令表，然后根据命令的实际作用制定计划，而不是凭猜测行事。
• 预先规划完整流程。 运行任何命令前，先列出完整步骤。关键规则 2 禁止在同一条 shell 命令行中串联 uip insights 子命令，因此应批量处理，选择一个能涵盖整个问题的命令，而不是逐个执行相关子命令。
• 每项输入只检查一次。 阅读指南或响应一次，并依据已获取的内容开展工作。切勿逐字段重新打开文件，也不要重新运行输出已在上下文中的命令。
• 不要重复工作。 如果输入和相关状态未变，就不要重新运行命令；也不要重新阅读已在上下文中且未变的指南或 SKILL.md。
• 代码只写一次并重复使用。 不要粘贴功能相近的内联 python3 -c 或 jq 代码，以计算子命令已经返回的内容。
• 尽量精简输出。 优先使用经过筛选的结果，而不是原始响应。需要读取较大的完整正文时，将其写入文件并检查文件。
• 不做不必要的事。 除非当前确实需要，否则不要调用工具、阅读指南或将结果载入上下文。这条规则约束你读取什么，不约束你必须运行哪些命令。

UiPath Insights

使用 uip insights 进行作业、队列和机器监控，发现监控范围，只读检查警报，读取 Insights RBAC 信息，以及读取、创建、更新、删除和复制 Maestro 流程仪表板。运行命令前，请先阅读与任务相关的指南。

适用场景

• 跨租户、文件夹或流程检查作业运行状况、成功率、失败次数或处理时间
• 查看作业随时间变化的趋势，或比较两个时间段
• 查找失败最多的流程，以及反复出现的失败原因
• 判断作业是否卡住、待处理或仍在运行
• 查找用于限定查询范围的确切文件夹键、流程名称、队列名称或机器名称
• 查看队列项目吞吐量、积压、SLA 风险、失败原因，或重试项目的处理结果
• 查看机器运行状况：运行时分布、当前状态和槽位、可用性随时间的变化、故障排名或运行时分钟数
• 查看现有警报、警报配置、警报是否触发，或触发后的警报如何送达
• 查看谁拥有租户的 Insights 访问权限、有哪些角色及其权限，以及哪些组拥有这些角色
• 查看 Maestro 流程的 Monitoring 选项卡所显示的内容：已保存的仪表板或模板、保存其上的全局筛选条件，或创建、更改、移除或复制该仪表板
• 查看 Insights 是否仍可访问组织的导出目标，以及现有的导出配置
• 查看现有哪些 Looker 时代的 Insights 仪表板、某个仪表板的嵌入 URL，或嵌入式仪表板无法加载的原因

关键规则

1. 使用 --output json。 jobs 命令返回 { Result, Code, Data }。每个 jobs investigate 调查手册都会添加 Instructions；七个普通 jobs 读取命令中也有四个会添加该字段（top-failures、failures-by-reason、process-details、failure-details），此外还有 filter-* 命令、queues 和 machines 命令、告警命令、仪表板命令，以及两个 looker-dashboards 命令；filter-*、除 summary 以外的每个 queues 命令、除 runtime-mix 以外的每个 machines 命令、alerts list、alert-history list、dashboard-filters list、export-configurations list 和 looker-dashboards list 还会添加 Pagination；而 dashboards 的任何操作都不会添加该字段，export-configurations verify 也不会；该操作只添加 Instructions，因为它返回组织拥有的所有配置，且无法分页。解释时请原样引用这些 Instructions。失败信封包含 Result、Message、Instructions、ErrorCode 和 Retry，不包含 Code 和 Data。HTTP 失败还会包含 Context，其中有 httpStatus、endpoint，有时还会有 requestId 和 retryAfter；如果请求发送前就发生失败，则不包含 Context。CLI 的 JSON 输出中，Data 内的键采用 PascalCase，因此应读取 CompletedJobs 和 FolderName，而不是 completedJobs 或 folderName。jobs 读取命令会将响应投影为具名列，而不是打印后端宽泛的 DTO，因此你从 API 中记得的字段可能会使用更清晰的名称，也可能根本不存在；jobs 指南列出了每种读取命令会输出的内容。RBAC 读取命令会打印经过安全筛选的投影，其中隐藏了身份字段，输出格式对此没有影响：完整视图通过每个类别对应的具名 include 标志启用，因此这些命令也应使用 --output json。
2. 每次调用只运行一个子命令，并且要直接写出。 一次 shell 调用只运行一个 uip insights 命令，不执行其他操作。不要串联、循环或参数化这些命令：不允许使用 && 或 ; 串联、不允许用换行分批执行、不允许使用 for 循环，也不允许用 shell 变量保存子命令名称或标志值。先通过单独的命令解析纪元时间戳等值，再传入字面数字。绝不要将 $(date ...) 或 $VAR 写入标志值。
3. 只能使用指南中记录的标志。 身份、组织和租户信息来自当前活动会话。任何租户标志都已弃用，并且在 filter-* 命令中会被直接拒绝，因此不要使用。如果某个筛选条件不在指南的共享选项列表中，它就不存在。
4. 普通读取命令必须指定时间范围，且不同命令类别的单位不同。 对七个普通 jobs 读取命令，传入 --time-range <minutes>（60 = 1h、1440 = 24h、10080 = 7d、43200 = 30d），或者同时传入 --started-after 和 --started-before，值为纪元毫秒。queues 和 machines 命令使用相同的两个标志，单位也与 jobs 相同。alert-history 命令也需要时间范围，但其绝对时间边界使用 --since 和 --until，单位为纪元秒。省略时间范围会在本地被拒绝：普通 jobs 读取命令返回 Result: Failure 并以 1 退出，queues、machines 和 alert-history 以 3 退出。queues 和 machines 的服务端还会将时间窗口限制为 30 天；何时会触发该限制以及 CLI 如何报告，由各类别指南的规则 2 说明。每个 jobs investigate 调查手册都设有默认窗口，若窗口超出其处理能力，则会返回 Result: ValidationError 并以 3 退出。filter-* 命令、三个告警定义读取命令、仪表板命令、export-configurations 命令和 looker-dashboards 命令不接受时间标志。
5. 先运行 summary，再深入查询。 完成任务所需的范围发现后，调查作业时先运行 uip insights jobs summary 查看总数，调查队列时先运行 uip insights queues summary，然后再运行针对性的子命令。摘要提供分母，让故障数量更有意义。machines 类别没有摘要：要调查机器，请运行 uip insights machines runtime-mix 查看整个租户的运行时分布；如果问题涉及某台指定机器的当前状态，则运行 uip insights machines details。
6. 将空数据视为有范围限制的证据。 结果为空可能是所选时间窗口、近期活动窗口、调用方可见范围或租户配置所致。对于告警读取，还可能是授权过滤所致；所有告警定义读取命令都只返回有效定义。这些情况都不能证明某项资源或事件从未存在。
7. 使用 CLI，而不是原始 Insights API。 CLI 负责身份验证、租户路由、验证、安全响应投影和错误处理。
8. 不要自动重试。 根据 Retry 分支处理：RetryWillNotFix 表示应修复原因；RetryLater 表示报告情况并停止。401 表示需要新会话，403 表示权限边界，404 可能受租户范围或可见性范围限制。各指南会说明对应命令的错误格式。
9. 绝不要自行运行 uip login。 该命令会打开交互式浏览器流程，导致会话挂起。报告身份验证状态，并向用户提供要运行的确切命令，然后停止。
10. 通过发现获取标识符，不要猜测。 使用 references/filter-discovery-guide.md 确定监控范围；告警和传递项 ID 应取自列表结果或用户提供的信息。得出资源不存在的结论前，先翻阅所有结果页。
11. 将原因调试交由其他工具处理。 Insights 可以指出哪些作业、进程和队列发生故障，以及哪些原因反复出现，但无法解释单个作业或队列项的异常，也无法说明如何修复。报告相关原因后，指出应使用 uipath-troubleshoot 查明原因，并使用 uipath-rpa 或 uipath-agents 进行修复。
12. 仅以只读方式访问告警。 告警指南中的六个只读子命令就是全部获准操作范围。修改告警定义或传递项（包括其接收者、类型和配置）都必须在 Insights UI 中进行：请说明这一点，不要提议代为修改。无论通过何种方式进行修改，都必须遵守此规则，因此不要通过 SDK、原始 HTTP 调用或其他技能访问告警路由。
13. 分别报告告警触发和传递情况。 历史记录中的一行只能证明告警已触发，不能证明通知已发送或收到；任何告警读取命令都无法确认通知已收到。
14. 不要在生成的任何内容中透露告警接收者数据，包括粘贴的 JSON。报告传递项时，只说明其类型和接收者数量；对于“通知了谁？”这类问题，只回答数量。不要点名接收者、引用原始告警查询 JSON、枚举传递渠道设置，也不要使用其他命令或技能将数量对应到具体姓名。
15. 仅以只读方式访问 Insights RBAC。 RBAC 指南中的六个只读子命令就是全部获准操作范围。创建用户、更改角色或分配访问权限都应在其他位置完成：请说明这一点，不要提议代为操作。无论通过何种方式进行更改，都必须遵守此规则，因此不要通过 SDK、原始 HTTP 调用或其他技能访问 RBAC 路由。
16. 不要在生成的任何内容中透露 Insights 身份数据，包括粘贴的 JSON。按名称和数量概述用户与群组。用户和群组读取命令中的 --include-email，以及角色读取命令中的 --include-resource，会启用电子邮件地址、嵌套角色 ID 和角色资源字符串的输出；除非用户要求其中某个字段，否则不要启用这些标志，只有在用户明确要求时才引用相应标志。将标识符作为命令参数传入不属于信息披露；此规则约束的是你写出的内容。
17. 通过制品通道创建仪表板文件，绝不要使用重定向输出。 使用 dashboards get --output-file <path> 读取仪表板，编辑该 camelCase 文件，再将其传给 dashboards create --file 或 dashboards update --file。--backup-file 和 copy 的 --output-file 也遵循同一约定。重定向的 CLI JSON 使用 PascalCase 且带有包装结构，相关命令会拒绝此类文件。
18. 仪表板写入操作只发送一次，结果未知时绝不要重新发送。 先读取目标位置：如果已有已保存的仪表板，此任务应视为更新而非创建；如果是通过名称解析得到的进程键，则必须先取得用户确认，之后才能写入。遇到 unknown_error 时，读取目标位置或该 ID，并按照写入指南的错误表以及信封自身的 Instructions，根据 Message 和读取结果作出判断；RetryLater 只有在读取之后才能再次发送，而被拒绝的文件从未发送，因此应修复后再发送。更新时传入从最新进程键读取结果获得的 --expected-version，并说明该检查仅为尽力而为，因为路由没有版本前置条件。删除时绝不省略 --backup-file 和用户的明确请求；也绝不要在创建被拒、更新失败或 copy 目标已被占用后通过删除来重新开始。报告成功时，应说明数据已持久化且已回读，但渲染情况未经检查。

共享工作流

1. 如果任务会调用 UiPath Cloud，请检查当前登录状态：

   uip login status --output json
   

2. 阅读下方任务导航表为此任务指定的指南；如果表中注明无需阅读，则不阅读其他指南。

3. 调查作业时，请运行一个 uip insights jobs investigate playbook，而不要自行执行整套命令链。调用所需的一切信息都在下表中：如果表格已解答问题，就不要打开 playbook 指南。

   问题	Playbook	标志
   自动化运行状况如何，成功率是多少？	health	window（默认值为 1440，最大值为 43200）
   哪些流程失败了，原因是什么？	failing	window（默认值为 43200，最大值为 43200）
   为什么某个指定流程会失败？	process	--process-name <name>（必填，单个值），window（默认值为 1440，最大值为 43200）
   作业是否卡住、待处理或仍在运行？	stuck	window（默认值为 1440，最大值为 43200）
   这一时段比前一时段更好还是更差？	compare	window（默认值为 10080，最大值为 21600）
   按文件夹名称限定范围的作业运行状况	folder	--folder-name <name>（必填），window（默认值为 1440，最大值为 43200）

   Playbook 只能采用一种 window 形式：--time-range <minutes>，或同时使用 --started-after 和 --started-before（值为 epoch 毫秒）。它会拒绝同时使用这两种形式、window 超出上述最大值，以及绝对下限早于 30 个完整自然日的情况。每次拒绝都在本地处理，返回 Result: ValidationError 和退出码 3，且不会发送请求。普通的 jobs 读取不会执行这些检查：它允许同时使用这两种形式，并会将过宽或过期的下限转发给服务端，由服务端截断，但不会说明这一点。compare 的最大值是其他 playbook 的一半，因为它会读取两个相邻且长度相同的时段，而且两者都必须处于服务端 30 天的上限内。每个 playbook 都会自行解析 window 边界，因此绝不要用 date 来构造边界。每个 playbook 还接受 --timezone-offset <minutes>，用于将时间分桶的时间戳偏移到客户端时区。

   不同 playbook 的范围筛选条件有所不同。health、failing、stuck 和 compare 接受可重复指定的 --folder-key、--process-name 和 --machine-name。process 接受 --folder-key 和 --machine-name，以及其专属的 --process-name；由于答案只针对一个流程，因此该参数只能指定一个值。folder 接受 --process-name 和 --machine-name，不接受 --folder-key，因为 --folder-name 会解析为单个 key。每个 playbook 返回的封装结构都与其他命令相同，即 { Result, Code, Data }，其中包含一个 Instructions 字符串，列出其数值的注意事项：请在说明中引用这些内容。

   如果 investigate 报告 unknown command，说明已安装的 CLI 版本早于该功能。请告知用户升级（npm i -g @uipath/cli），并在本次运行中改用 references/investigation-playbook-guide.md 中的编号命令链。

4. 其他情况下，运行子命令并解析 Data 获取结果。对于列表子命令，还需读取 Pagination，以确认列表是否完整。

   指定某个子命令，或要求运行所有子命令，均表示运行七个普通的 jobs 读取：请运行这些读取。Playbook 用于回答问题，不能替代指定的读取，也不等同于“运行所有子命令”。如果调用方需要未投影且未截断的正文，普通读取也是获取原始响应的方式。

默认使用当前的 Production 会话。只有用户明确指定其他环境或范围时，才更改权限、组织或租户。请提供命令让用户运行，而不要自行运行：

uip login --authority https://cloud.uipath.com --tenant MyTenant   # named environment
uip login tenant set MyTenant                                      # same environment, different tenant

任务导航

用户的任务	优先阅读
检查作业运行状况、成功率、趋势、失败、卡住的作业，或比较不同时段	无需阅读。运行 Shared Workflow 第 3 步中的 jobs investigate playbook。只有在没有适用的 playbook，或 CLI 缺少相应动词时，才阅读 references/investigation-playbook-guide.md
选择 Jobs 子命令、标志、时间范围，或解读响应字段	references/jobs-commands-guide.md
查询可见的文件夹、流程、队列或机器，或查找用于筛选的确切文件夹键、流程名称或机器名称	references/filter-discovery-guide.md
报告队列项目总数、SLA 风险、状态随时间的变化、失败或重试结果	references/queue-monitoring-guide.md
报告机器运行时分布、状态和槽位、可用时间段、故障排名或运行时长（分钟）	references/machine-monitoring-guide.md
检查警报定义、警报功能权限、触发历史或传递元数据	references/alerts-reads-guide.md
检查 Insights 用户、角色或组	references/rbac-reads-guide.md
查看 Maestro 流程的监控仪表板、仪表板定义或其中存储的全局筛选器	references/dashboard-reads-guide.md
创建、更新、删除或复制 Maestro 流程的监控仪表板	references/dashboard-writes-guide.md
报告现有的统一导出配置，或 Insights 是否仍能访问其目标位置	references/export-configurations-guide.md
列出 Looker 时代的 Insights 仪表板，或为其中一个生成嵌入 URL	references/looker-dashboards-guide.md

只阅读任务所需的指南。若作业调查需要先确定文件夹、流程或机器，则先读筛选指南，再读作业指南。若队列问题提到了队列名称，则先读筛选指南以确定确切名称，再读队列指南。若机器问题提到了机器名称，则先读筛选指南以确定确切名称，再读机器指南。机器指南还列出了五种机器类型标签；filter-machines list 不会报告这些标签。警报问题只需阅读警报指南；该指南涵盖完整的定义、历史记录和传递流程。Insights 访问问题只需阅读 RBAC 指南。仪表板问题需要阅读仪表板读取指南；任何写入操作还需随后阅读写入指南：流程键由用户提供，或通过 uip maestro bpmn processes list 获取，并且没有任何 filter-* 命令可以发现仪表板。

适用范围

uip insights 提供八组命令：jobs、queues、machines、filter-* 发现命令、警报读取命令（alerts、alert-history、alert-deliveries）、RBAC 读取命令（users、roles、groups）、Maestro 仪表板命令（dashboards、dashboard-filters）、统一导出读取命令（export-configurations），以及 Looker 时代的仪表板读取命令（looker-dashboards）。jobs 系列包含七个读取命令，以及 jobs investigate；每次调用都会运行一套完整的调查流程。如果请求需要其他功能，请说明当前不可用，不要猜测子命令。

请求	路由
列出或获取单个作业及其当前状态。Insights 保存的是一段时间窗口内的历史聚合数据，而不是实时作业记录	uipath-platform（uip or jobs list --state）
启动、停止、重启单个 Orchestrator 作业，或查看其日志	uipath-platform
诊断特定作业错误的根本原因	uipath-troubleshoot
修复导致故障的工作流或 Agent	uipath-rpa 或 uipath-agents
列出、添加、重试或删除单个队列项目	uipath-platform；queues 仅汇总报告队列项目，不会更改任何项目
任何警报或投递写入操作（见关键规则 12）	Insights UI；不属于已提供的 uip insights 功能
创建、编辑或删除机器，或管理其运行时	uipath-platform；machines 仅报告机器信息，不会更改任何机器
以容量百分比表示的机器或机器人利用率，或根据时间窗口内的运行时计算出的平均并发数或“机器人当量”数量	不属于已提供的 uip insights 功能；machines utilization 报告的是运行时长（分钟），没有容量分母，而用时间窗口去除运行时长会凭空假设一个分母
查看 Maestro 流程的监控仪表板或其保存的全局筛选条件	references/dashboard-reads-guide.md
创建、更新、删除或复制 Maestro 流程的监控仪表板（见关键规则 17 和 18）	references/dashboard-writes-guide.md
让 Insights 根据文本提示词生成仪表板（产品自带的生成特性）	Insights UI；不属于已提供的 uip insights 功能。根据用户描述编写定义，请参阅写入指南
任何 Insights RBAC 写入操作，例如分配角色（见关键规则 15）	Insights UI；不属于已提供的 uip insights 功能
在 Insights 之外管理组织级用户账户、群组或角色	uipath-admin
创建、编辑或删除统一导出配置，或设置新的导出目标	Insights 管理 UI；不属于已提供的 uip insights 功能
为什么导出内容不再送达目标位置	首先参阅 references/export-configurations-guide.md，确认 Insights 是否仍能访问目标位置；然后使用 uipath-troubleshoot 排查目标端问题
列出 Looker 时代的 Insights 仪表板，或获取其嵌入 URL	references/looker-dashboards-guide.md
创建、更新、删除、导出或复制 Looker 时代的仪表板	Insights UI；不属于已提供的 uip insights 功能

反模式

• 不要在 jobs 命令、任何 dashboards 动词或 looker-dashboards get-embed-url 中添加 --limit 或 --offset，这些命令均不接受这两个参数。在仪表板命令中，只有 dashboard-filters list 和 looker-dashboards list 支持分页。每份指南都会列出哪些命令支持分页。
• 不要重复使用示例中的标识符。文件夹键、流程名称、机器名称和队列名称应来自 filter-* 结果或用户；异常原因应来自 failures-by-reason 行；Maestro 流程键应来自用户或 uip maestro bpmn processes list；仪表板 ID 应来自 dashboards get、dashboards create 或 dashboards copy 结果。
• 不要将空的或值为 false 的警报结果视为证明。说明它排除了什么，以及仍有哪些可能性。
• 除非用户询问安全视图未提供的字段，否则不要在 RBAC 读取操作中传递 --include-email 或 --include-resource。
• 不要向任何 export-configurations 命令传递连接字符串、访问密钥或 API 密钥。verify <id> 使用 Insights 已存储的凭据，且没有任何命令会接收此类凭据。
• 除了在答复中，不要粘贴生成的 Looker 嵌入 URL。它是按用户签名的凭据，不是链接。

完成时的输出

结束时说明答案、查询的时间范围、当前组织和租户，以及应用的筛选条件。对于列表结果，说明是否已获取所有分页。对于权限受限或为空的结果，说明该结果能证明什么、不能证明什么。