uipath-feedback

UiPath 反馈

使用 uip feedback send 向 UiPath 发送结构化错误报告或改进建议，并自动收集故障排查信息。

设计原则：尽量减少交互。 Agent 已经能从对话中了解出了什么问题。不要重复询问已知信息。唯一必须的交互是在发送前确认。

重要规则

1. 尽量减少用户交互。 如果对话中已有足够的上下文（错误、用户正在进行的操作、出了什么问题），就直接确认并发送。只有在确实无法判断发生了什么时才询问澄清问题。
2. 未经用户明确确认，绝不发送。 始终显示预览并等待用户回复“是”。
3. 绝不包含秘密、令牌、凭据或客户数据。 发送前清理所有收集的内容。
4. 绝不包含完整对话历史。 用 2-3 句话总结相关上下文。示例提示词（步骤 2e）是精选的最多 5 条内容，而不是对话记录。
5. 对 uip feedback send 使用 --output json，以便以编程方式解析结果。
6. 如果 uip feedback send 失败，将报告保存到 ./feedback-report.md，以免用户丢失已收集的上下文。

工作流

步骤 1 -- 检查前置条件

uip --version 2>&1

结果	操作
输出版本信息	继续执行步骤 2
uip: command not found	告知用户运行官方安装程序：在 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。停止。
其他错误	显示错误。停止。

步骤 2 -- 检查并收集信息（静默执行，不与用户交互）

自动收集所有上下文。静默执行以下子步骤。

2a. 检测所属领域

领域（对应哪个产品）将作为标题标签和用于筛选的 Jira 标签。根据用户在本次对话中最后运行的 uip <verb> 识别领域。如果无法识别 uip 命令，则依次根据工作目录和对话上下文判断。命令/信号 → 领域的对应关系如下：

最后运行的命令/信号	领域
uip rpa …，或 project.json + *.cs/*.xaml	RPA
uip maestro flow …，或 *.flow 文件	Flow
uip maestro bpmn …，或 *.bpmn 文件	BPMN
uip maestro case …，或 caseplan.case / caseplan.json	Case
uip <agent…>，或包含 uipath 的 pyproject.toml / agent.json	Agents
uip codedapp …，或 app.config.json / action-schema.json	CodedApps
uip api-workflow …	ApiWorkflow
uip df …	DataFabric
uip solution …，或 *.uipx	Solution
uip tm …（Test Manager）	Test
uip tasks …	Tasks
uip admin …	Admin
uip gov …	Governance
其他情况（uip login、通用 Orchestrator / Integration Service / 平台）	Platform

如果无法确定，请根据对话推断。不要询问用户——选择最合适的领域。

可选的 CLI 与 Skill 标记。 仅在能明确判断属于其中一种情况时，添加第二个标签，以便分流人员分派报告：

• CLI -- uip 命令崩溃、返回错误输出，或缺少动词/标志。
• Skill -- 按照此技能的说明操作，但说明有误、容易误导或有所遗漏。

如果原因混杂或不明确，则省略此标签——不要勉强猜测。

2b. 收集环境信息

uip --version 2>&1
uip login status --output json 2>&1
uip tools list 2>&1

从登录状态中仅提取：tenantName、organizationName、baseUrl。删除其他所有内容。

从工具列表中提取每行工具的 name 和 version。

2c. 捕获特定技能的故障排查信息

区域	要捕获的内容	限制
Flow	uip maestro flow validate <file> --output json、.flow 文件内容、目录列表	.flow：前 150 行；目录：最多 30 个条目
RPA（.cs 或 .xaml）	project.json 依赖项、uip rpa validate --output json、工作流文件列表（.cs 和／或 .xaml）	文件列表：最多 20 个文件；project.json：仅依赖项部分；失败的工作流：前 150 行
Agents	pyproject.toml、bindings.json（隐去连接值）、目录列表	bindings.json：隐去所有值；目录：最多 30 个条目
CodedApps	package.json（仅名称、版本和依赖项）、.uipath/ 列表	package.json：仅名称 + 版本 + 依赖项
其他（Platform、Solution、Admin，…）	仅 uip login status --output json 输出	从输出中移除令牌

2d. 捕获失败的命令

查看当前对话，找出最近一次失败的 CLI 命令。如果可以识别，请捕获：

• 完整命令
• 该命令的 stderr/stdout 输出（截断至 100 行）

如果无法识别，请跳过此部分。

2e. 捕获示例提示词

从对话中选出 3-5 条用户提示词，展示用户尝试完成的任务。这些内容能让问题分诊人员了解回顾总结无法提供的信息：用户的真实措辞。

选择规则：

• 优先选择表达意图的提示词（“构建一个……的流程”“我需要……”“帮我……”）或描述故障的提示词（“这个坏了”“结果不对”）。
• 保留原文措辞，不得改写。改写会丢失重要信息。适用清理规则。
• 跳过填充内容（“好的”“谢谢”“再试一次”）。
• 如果实质性提示词少于 3 条，请提供现有内容。不要凑数。
• 最多 5 条提示词。所有提示词的总长度不得超过 1000 个字符。超过 200 个字符的单条提示词需截断，并加上 ... [truncated]；保留最有信息量的部分。
• 如果没有实质性提示词，请在步骤 3 中完全省略 ## Sample prompts 部分。

2f. 会话回顾总结

回顾完整对话，并进行结构化自我评估。这是反馈中最有价值的部分——它能为问题分诊人员提供任何手动提交的错误报告都无法提供的上下文。

简洁回答每个问题（每题 1-3 句）。引用本次会话中的实际工具名称、错误、命令和文件。

1. 意图：用户想要构建／编辑／修复什么？从一开始目标是否明确？
2. 结果：实际交付了什么，与请求相比如何？完整 / 部分 / 失败。
3. 工具与技能缺口：调用了哪些无用的工具或 CLI 命令？哪些本应调用却没有调用？是否出现故障或采用了变通方法？
4. 阻碍：Agent 在哪里卡住、重试或误解了 UiPath 约定？进行了多少轮生成-验证-修复？
5. 最重要的 3 项改进：哪些技能／工具方面的改动对本次会话帮助最大？

2g. 自动检测类型和优先级

类型——根据对话中的信号判断：

类型	信号
bug（默认）	错误消息、崩溃、“无法运行”“坏了”、运行时故障、意外行为
improvement	“如果能……就好了”“应该支持……”“缺少功能”“建议”“技能给了我错误指引”“没有用于 X 的命令”、功能请求

存在歧义时，默认选择 bug。

优先级——根据对话中的信号判断：

优先级	信号
critical	完全阻碍用户、数据丢失、安全问题、CLI 因堆栈跟踪而崩溃
normal（默认）	某项功能损坏或缺失，但有变通方法
minor	外观问题、锦上添花的改进、输出中的错别字、影响较小的问题

存在歧义时，默认选择 normal。

2h. 清理所有内容

继续之前，请将下方清理规则中的所有规则应用于每一项捕获的内容。

2i. 仅当上下文不足时

如果 Agent 确实无法判断发生了什么（例如，用户在对话中没有任何前文的情况下输入了 /uipath-feedback），请提出一个结构化问题：

我会向 UiPath 发送反馈。请告诉我：

1. 您想做什么？
2. 发生了什么？
3. 这是一个 Bug，还是改进建议？

否则，直接跳到步骤 3。

步骤 3 —— 构建并确认（仅限用户交互）

标题格式

[<Area>] short description

• <Area> —— 步骤 2a 中的区域标签：RPA、Flow、BPMN、Case、Agents、CodedApps、ApiWorkflow、DataFabric、Solution、Platform、Tasks、Test、Admin、Governance。
• 仅当步骤 2a 明确判断属于其中一种时，才可在区域后添加 [CLI] 或 [Skill] 标签：[<Area>] [CLI] … 或 [<Area>] [Skill] …。
• 标题中不要添加类型（Bug/Improvement）——这是问题类型，通过 --type 设置。

示例：[RPA] uip rpa run fails when project.json has no dependencies · [Flow] [Skill] Flow skill should list IxP models before adding an extraction node

CLI 会从标题开头的这些 [Tag] 片段中提取 Jira 标签，因此这些标签既会显示在标题中，也可用于筛选，无需额外标志。

描述正文

构建 --description 内容：

## What happened
{User's problem -- in their own words or summarized from conversation}

## Sample prompts
1. "{prompt 1 -- verbatim, sanitized}"
2. "{prompt 2 -- verbatim, sanitized}"
3. "{prompt 3 -- verbatim, sanitized}"

## Error
{The actual error message or validation output -- if available, otherwise omit this section}

## Environment
- Area: {area}
- uip version: {version}
- CLI tools: {name version, name version, ...}
- OS: {os info}
- Tenant: {tenant} ({org})

## Troubleshooting
- Project type: {detected type}
- Key files: {list of relevant project files found}
- Last failed command: {command + truncated output}

## Session retrospective
- **Intent**: {what the user was trying to do}
- **Outcome**: {Full | Partial | Failed -- what was delivered vs requested}
- **Tool & Skill Gaps**: {tools/commands that failed, were missing, or needed workarounds}
- **Friction**: {where the agent got stuck, retried, or misunderstood conventions}
- **Top 3 Improvements**: {specific skill/tool changes that would have helped most}

格式规则

1. 每个章节标题都使用 ## （两个井号和一个空格）。绝对不要使用编号列表、字母或粗体文本作为章节分隔符。
2. 使用上方模板中的准确章节名称。不要重命名、改写或添加章节。
3. 每个 ## 标题前后都必须各有一个空行。
4. 无序列表使用 -。
5. 章节正文中的编号项使用 1.、2. 等，并单独成行。不要转义句点。
6. 不要转义 Markdown 字符。不要使用 \*、\#、\-、\.。写成 **粗体**，不要写成 \*\*粗体\*\*。
7. 描述必须是纯 Markdown。不要使用 Jira wiki 标记、HTML 或 ADF——CLI 会在发送时将此 Markdown 转换为跟踪系统的原生格式（Jira wiki 标记），以确保正确呈现。
8. 不要在描述正文中包含用户的电子邮件。仅通过 --email 标志传递。

格式良好的描述示例

## What happened
When running `uip maestro flow validate` on a flow with nested loops, the CLI returned a generic "expression error" with no line number or variable name, making it impossible to locate the issue.

## Sample prompts
1. "Build a flow that iterates over invoice line items and flags duplicates."
2. "Now add a nested loop to compare each item against the prior month's list."
3. "I keep getting 'currentItem is not defined' — which variable should I use inside the nested loop?"
4. "Run validate again and just tell me which line is broken."

## Error
ExpressionError: Invalid expression at unknown location — currentItem is not defined

## Environment
- Area: Flow
- uip version: 0.1.20
- CLI tools: docsai-tool 0.1.12
- OS: Windows 11 Enterprise 10.0.26100
- Tenant: demo (aro)

## Troubleshooting
- Project type: Flow (.flow)
- Key files: MyProcess.flow
- Last failed command: uip maestro flow validate MyProcess.flow --output json

## Session retrospective
- **Intent**: Build a flow that iterates over invoice line items and flags duplicates
- **Outcome**: Partial — flow runs but the nested loop variable reference fails at runtime
- **Tool & Skill Gaps**: (1) uip maestro flow validate gave no location info for expression errors. (2) No way to inspect available variables inside a loop scope.
- **Friction**: Agent tried 8 generate-validate-fix cycles guessing the correct variable name. The error message never identified which expression failed.
- **Top 3 Improvements**: (1) Include expression location (line/node) in validation errors. (2) Add a CLI command to list variables in scope at a given point. (3) Document loop variable naming conventions in the Flow skill.

将完整描述截断至最多 4000 个字符。如有截断，请注明。

准备附件

将相关项目文件的净化副本写入临时目录：

mkdir -p "${TMPDIR:-${TMP:-/tmp}}/uip-feedback-attachments"

根据检测到的区域复制并净化文件：

• Flow：.flow 文件
• RPA：project.json、出错的工作流文件（.cs 或 .xaml）
• Agents：pyproject.toml、bindings.json（已脱敏）
• CodedApps：package.json

最多 10 个文件，每个文件最大 10MB。超出限制的文件请跳过。

显示预览并确认

向用户显示：

**Type:** bug
**Priority:** normal
**Title:** [Flow] [CLI] Expression error in nested loop currentItem
**Description:** (first 3 lines...)
**Attachments:** MyFlow.flow, project.json

Send this to UiPath? (yes/no)

用户可以在确认前调整类型、优先级或标题（标题包含区域标签和可选的 CLI 或 Skill 标签）。未经明确的“是”，绝不要发送。

Step 4 -- 发送反馈

切勿将多行描述直接内联为 --description "…" 参数。 在 Windows PowerShell 中，原生命令的参数序列化器会破坏多行值（以 - 开头的行会作为选项传递给 CLI → ValidationError）。务必通过 --description-file 传递正文。

1. 使用 Write 工具（而非 shell heredoc——heredoc 仅适用于 bash，在 PowerShell 中会失败）将经过清理的描述正文写入临时文件。使用操作系统临时目录中的绝对路径，例如 <temp>/uip-feedback/description.md。
2. 调用 CLI，并使用 --description-file 指向该文件：

uip feedback send \
  --type "<bug|improvement>" \
  --title "<TITLE>" \
  --description-file "<TEMP>/uip-feedback/description.md" \
  --priority "<critical|normal|minor>" \
  --attachment <FILE1> <FILE2> \
  --output json

--description-file 会从磁盘读取正文，因此不受 shell 引号影响，并且在 PowerShell、cmd 和 bash 中的行为一致。（如果 CLI 版本较旧，不支持此标志，则改为通过 stdin 传入正文；不要将其内联。）

标题（--title）较短且为单行，因此内联传入是安全的。标题开头的 [Tag] 部分（区域，以及可选的 [CLI]/[Skill] 标记）会自动成为 Jira 标签，无需额外标志。

如果 uip login status 中有电子邮箱，请添加 --email "<EMAIL>"。CLI 会将其写入问题的 Environment 字段，而不会放入描述正文。

解析 JSON 输出。成功后，向用户显示确认信息，并附上返回的任何参考 ID。

正确诊断失败。 如果 ValidationError 指向你未传入的选项（例如，它抱怨 - 或项目符号行），这是 shell 引号问题，而不是 CLI 缺陷——你内联了多行值。请改用 --description-file；不要报告 CLI 已损坏，也不要用相同的内联调用重试。

备用方案： 仅当 --description-file 确实失败时（网络、身份验证或实际 CLI 错误），才使用描述正文将完整反馈保存到 ./feedback-report.md，并告知用户："无法自动发送。报告已保存到 feedback-report.md。"

清理临时附件：

rm -rf "${TMPDIR:-${TMP:-/tmp}}/uip-feedback-attachments"

Step 5 -- 报告结果

成功时：

Feedback sent successfully.
- Reference: {reference ID from JSON response, if available}
- Type: {bug|improvement}
- Title: {title}

回退到文件时：

Could not send feedback automatically.
- Report saved to: ./feedback-report.md
- You can submit it manually or retry with `/uipath-feedback` later.

无论成功还是失败，都务必清理临时附件。

清理规则

将内容加入描述或附件之前，务必先应用以下规则：

1. 剔除机密信息。 删除匹配以下内容的行（不区分大小写）：token、secret、password、apiKey、credentials、authorization、Bearer、client_secret、connection_string
2. 隐藏路径中的个人身份信息。 将主目录前缀替换为 ~（例如，C:\Users\john.doe\projects\ -> ~/projects/）。将 URL 或路径中的用户名替换为 <USER>
3. 隐藏 GUID。 在连接/绑定字段中，将值替换为 <REDACTED>
4. 截断长内容。 对超过 150 行的文件，保留前 100 行 + ... [truncated N lines] ... + 最后 30 行。描述全文最多 4000 个字符
5. 绝不包含： ~/.uipath/.auth、.env、.git/config、包含机密信息的环境变量、完整对话历史
6. 绝不包含客户数据。 除非项目文件中的组织标识是通过 uip login status 获取的租户/组织，否则请剔除其中的客户名称、电子邮箱和组织专属标识符
7. 清理示例提示词。 将规则 1–3 和 6 应用于每条捕获的提示词，然后再将其加入 ## Sample prompts。将客户名称、电子邮箱、项目代号、账户 ID、工单 ID、内部 URL，以及暴露用户名的文件路径替换为 <REDACTED>。如果清理提示词会导致其失去有效信息（提示词主要由客户专属数据构成），则丢弃该提示词，并从 Step 2e 中另选一条。若提示词中包含机密信息，即使由用户输入，也绝不要逐字引用。

不要做什么

1. 不要询问你已经知道答案的问题。 如果对话中包含错误、上下文以及用户当时正在做什么——只需确认并发送。
2. 不要包含原始对话记录。 ## What happened 应为 2-3 句话的摘要。## Sample prompts 应是根据步骤 2e 精选的最多 5 条内容，而不是对话记录。
3. 未经确认不要发送。 始终先预览。
4. 不要包含机密、凭据或个人身份信息（PII）。 如有疑问，请先编辑隐去。
5. 不要附加未经清理的文件。 附加前务必移除敏感内容。
6. 用户说“不”后不要重试。 尊重用户的决定。询问他们是否想调整内容或彻底取消。
7. 未经展示，不要修改用户的描述。 预览内容就是约定内容。
8. 不要重复发送反馈。 如果用户已在本次会话中就同一问题发送过反馈，继续操作前先确认他们是否要再次发送。
9. 不要使用编号列表作为章节标题。 章节必须使用 ## Header 格式。写成 1. What happened 2. Error 3. Environment 会导致 Jira 问题难以阅读。
10. 不要将用户邮箱写入描述正文。 只能通过 --email 标志传递。将其包含在描述中会违反清理规则 #6。