mcpField
D
debug-flow

debug-flow

github.com/microsoft开发1.1k156 次安装今天更新
代码仓库

关于 debug-flow

用于排查 Power Automate 运行失败的技能，可追踪根因、提出针对性修复并重新测试。它通过 FlowAgent MCP 工具引导分析，并按需限制记录内容的读取范围。

主要功能

  1. 01查找流程和近期失败运行
  2. 02分类错误并追踪依赖链
  3. 03检查操作轨迹和限定范围的记录内容
  4. 04提出针对性修复并重新测试

适用场景

  1. 01调查失败或超时的流程
  2. 02定位循环中的失败迭代
  3. 03应用并验证操作级修复

MCP 相关

使用 FlowAgent MCP 工具检查、诊断、编辑和重新运行 Power Automate 流程。

安装

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

$npx skills add https://github.com/microsoft/power-platform-skills --skill debug-flow

安装后在 Claude Code 中输入/debug-flow确认已加载。

详细介绍

调试失败的流运行

你正在帮助用户调试一次失败的 Power Automate 流运行。

工具

此技能使用 FlowAgent MCP 工具。客户端会使用各自的前缀来显示这些工具——mcp__flowagent__<tool>（Claude Code）或 flowagent-<tool>（Copilot CLI）——因此，下文会用不带前缀的名称来指代它们 （例如 get_run_actions）。对于仅支持 CLI 的操作，或没有 MCP 工具可用时，请使用 CLI shell 命令（仅限本地引擎构建）。

工具用途
list_flows按名称查找流（使用 name 参数进行搜索）
get_run_history获取流的近期运行记录
diagnose_run一步完成：对失败的操作进行分类并提供修复建议
get_run_details获取特定运行的详细信息
get_run_actions获取操作级执行跟踪
get_run_action_content获取某个操作有界范围内记录的输入或输出
get_run_action_repetitions获取循环的迭代级详细信息（确定哪个迭代失败——传入循环内部的操作）
get_flow获取流定义以供参考
get_operation_details确认正确的操作类型／参数
edit_flow对某个操作／参数应用精准修复
update_flow替换整个定义（适用于大幅改写）
run_flow修复后重新运行（使用 wait: true 查看结果）
resubmit_run / cancel_run重新提交已修复的运行／取消卡住的运行

步骤

  1. 识别流程并运行

    • 解析 $ARGUMENTS，提取流程 ID 和可选的运行 ID。
    • 如果没有流程 ID，调用 list_flows 并传入 name 参数进行搜索。如果结果有歧义，请用户选择。
    • 如果没有运行 ID，调用 get_run_history 并查找最近一次失败的运行。
    • 用表格展示最近的运行：Run ID | Status | Start Time | Error

  2. 使用 diagnose_run 快速排查

    • 对该运行调用 diagnose_run——它会返回已分类的失败／超时操作，并为每项提供修复建议。以此作为排查起点。
    • 如需深入分析，还要并行获取：get_run_actions（完整跟踪记录）和 get_flow（定义上下文）。如果循环失败，对循环内的某个操作调用 get_run_action_repetitions，以找出失败的迭代。
    • 重复结果为 { action, count, truncated, repetitions }；count 是返回的数量，并非总数。如果 truncated 为 true，不要根据返回的子集推断其他内容不存在。
    • 需要已记录的有效负载时，使用 get_run_actions 并设置 includeSizes: true，然后调用 get_run_action_content，并传入操作名称以及 which: "inputs" 或 "outputs"。默认下载上限为 256000 字节；超出上限的结果会报告出来，而不会直接输出。仅获取诊断所需的内容，并避免在报告中复现敏感有效负载。

  3. 分析失败

    • 找出状态 != "Succeeded" 的操作
    • 沿 runAfter 依赖链追踪，区分根本原因和连锁失败：
      • 根本原因：依赖项均为 Succeeded，但自身失败的操作
      • 连锁失败：因某个依赖项失败而被跳过的操作
    • 报告根本原因操作及其：名称、类型、错误代码、错误消息

  4. 根本原因分类

    • 连接错误（AuthorizationFailed、ConnectionNotFound、InvokerConnectionOverrideFailed）：建议重新进行身份验证，或将连接源修复为 Embedded
    • 表达式错误（ExpressionEvaluationFailed、InvalidTemplate）：显示表达式，说明问题所在，并提出修复建议
    • API／外部错误（401/403/404/429/500+）：解释 HTTP 错误，并检查连接器状态
    • 参数错误（WorkflowOperationParametersRuntimeMissingValue）：必需参数缺失或为空。添加 null 检查：@if(empty(...), 'default', ...)
    • 超时（ActionTimedOut）：建议重试策略或拆分操作
    • 类型不匹配（InvalidOpenApiConnectionOperationType）：操作类型错误。调用 get_operation_details 查找正确的类型。

  5. 提出修复建议

    • 提供包含代码／表达式修改的具体修复方案。
    • 如果修复需要修改定义，提议使用 edit_flow 应用修改（仅修改单个操作／参数）；只有需要大幅重写时才使用 update_flow。

  6. 重新测试

    • 提议调用 run_flow 并设置 wait: true，以验证修复是否有效（或调用 resubmit_run，使用原运行的触发器输入重试）。
    • 报告结果：Succeeded/Failed，并附上操作详情。

输出格式

诊断摘要
  • 流程：[name]（[ID]）
  • 运行：[run ID] | [start time] | 状态：[status]
失败的操作
#Action状态错误代码错误消息
根本原因

[分类]：[说明]

修复

[包含代码的分步修复方案]

评论

支持 Markdown