setup

首次设置指南

你正在帮助一位不熟悉技术的用户首次让 Power Automate 插件运行起来。请保持友好，使用通俗易懂的语言，绝不要假设他们了解终端命令。一次只引导他们完成一个步骤。

步骤 1：检查 Node.js

在后台运行：

node --version 2>&1

• 如果成功（输出类似 v18.x.x 或更高版本）：告诉他们“Node.js 已安装”，然后继续。
• 如果失败或版本低于 18：告诉他们需要安装 Node.js 18 或更高版本。询问他们使用的操作系统，然后提供最简单的安装说明：
  • Windows：“访问 https://nodejs.org，下载 LTS 版本并运行安装程序。一路点击 Next 即可。”
  • Mac：“打开 Terminal 并运行：brew install node”（或者引导他们访问 nodejs.org）
  • 安装完成后，使用 node --version 重新检查。

步骤 2：检查 Azure CLI

在后台运行：

az --version 2>&1

• 如果成功：告诉他们“Azure CLI 已安装”，然后继续。
• 如果失败：告诉他们需要安装 Azure CLI。询问他们使用的操作系统：
  • Windows：“以管理员身份打开 PowerShell 并运行：winget install Microsoft.AzureCLI”，或者引导他们访问 https://aka.ms/installazurecliwindows
  • Mac：“brew install azure-cli”
  • 安装完成后，使用 az --version 重新检查。

步骤 3：Azure 登录

检查用户是否已登录：

az account show --output json 2>&1

• 如果成功（显示帐户信息）：告诉用户当前登录的帐户（显示 user.name 字段），并询问这是否是正确的帐户。
• 如果失败：告诉用户“我们来登录 Azure。”然后运行：

  az login
  

  这会打开浏览器。告诉用户：“浏览器窗口应该会打开。请使用你的工作帐户登录，也就是你用于 Power Automate 的帐户。” 登录完成后，再次运行 az account show，确认登录成功。

验证令牌访问权限 — 及早发现权限问题。

首先确认用户使用的是哪个 Azure 云，因为 Power Automate 资源 URL 因云而异，不能假设使用商用云对应的 URL （GCC High / DoD 租户使用该 URL 会失败）：

az cloud show --query name -o tsv

az cloud show	Power Automate 资源
AzureCloud（商用）	https://service.flow.microsoft.com
AzureCloud + GCC 租户	https://gov.service.flow.microsoft.us
AzureUSGovernment（GCC High）	https://high.service.flow.microsoft.us
AzureUSGovernment（DoD）	必须使用经过操作员验证的 PA_FLOW_RESOURCE 值；没有内置受众

az cloud show 无法区分商用云和 GCC，也无法区分 GCC High 和 DoD — 对于这些情况，请显式设置 PA_CLOUD=gcc / PA_CLOUD=dod。

DoD 端点主机使用 appsplatform.us，但这并不能确定令牌受众 （App ID URI）。设置 PA_CLOUD=dod 时，FlowAgent 要求提供明确且经过操作员验证的 PA_FLOW_RESOURCE，否则配置会失败。不要根据主机名猜测受众；请获取该租户对应的正确值。

然后请求与之匹配的资源的令牌，例如，商用云：

az account get-access-token --resource https://service.flow.microsoft.com --output json 2>&1

FlowAgent 本身也会以相同方式自动检测云；你可以通过 PA_CLOUD=commercial|gcc|gcchigh|dod 覆盖 检测结果。

• 如果成功：继续下一步。
• 如果因 "AADSTS65002" 失败（GCC High 中较常见）：Azure CLI 应用未在该云中获得 Power Automate 资源的 预授权。这不是许可证问题。请注册具有 Power Automate（Flow 服务）委托权限的公用客户端应用，并设置 PA_CLIENT_ID=<app-id>；之后，flow 命令会使用该应用。
• 如果因其他任何 "AADSTS" 错误失败：用户的帐户可能无权访问 Power Automate。告诉用户：“你的 Azure 帐户似乎无权访问 Power Automate。请联系 IT 管理员，确认你拥有 Power Automate 许可证。”
• 如果因其他错误失败：显示错误，并建议用户联系 IT 支持。
• 如果用户使用主权云且连接管理命令失败：保留原始错误并检查其代码。AADSTS650057 可能表示资源无效或缺少应用授权；AADSTS65001 可能需要管理员同意。 找不到应用或同意失败时，可能需要注册授权适当的公用客户端应用，并设置 PA_CLIENT_ID=<app-id>。网络、租户选择和会话过期错误需要采用不同的解决方法。不要根据云名称推断缺少预授权，也不要将所有其他错误代码都归类为无关问题。

登录特定账户

连接管理会与 az 分开进行身份验证——它使用自己的 MSAL 会话和独立的本地令牌缓存，因此 az login / az account set 不会切换它使用的账户。

以下三个工具涵盖相关操作：

工具	用途
list_accounts	查看缓存账户列表、effectiveConnectivityIdentity 和 nextSignIn 设置。非活动租户缓存不算身份不匹配。不会获取令牌。
switch_account	保存首选 username，或省略该参数以清除首选项。检查 preferencePersisted 和 nextSignIn：环境变量覆盖仍会生效。
whoami / doctor	比较有效的 Connectivity 用户名和租户与 Azure CLI 中的身份，包括同一租户中的不同用户。

当连接工具因 ServiceToServiceEnvironmentNotFound 失败时， 请先检查身份，再假定环境不存在。list_accounts 会区分有效账户与历史缓存账户。有效账户的用户名或租户不同表示身份不匹配；仅有未使用租户的缓存则不算。 switch_account 会清除缓存的登录信息，并记录用于重新验证的首选用户名。这并不能证明后续登录成功，也不能证明环境权限正确。

switch_account 不会更改 Azure CLI 身份。az 由你自行设置； 如果两者不一致，工具会明确指出，而不会悄悄重定向其中一个。 reconnect 会保留已记录的首选项——它会删除凭据，而首选项表达的是意向，并非凭据。 它会等待待处理的令牌获取和缓存清理完成，然后清除所有 Azure CLI 资源以及 Connectivity 的内存中令牌。 清理失败会报错，而不会视为已完成切换：请解决缓存访问问题后重试。 如果重置失败，请勿假定凭据已更改。

交互式登录时，FlowAgent 默认强制显示账户选择器，因此绝不会悄悄使用浏览器中当前已登录的账户。有两个覆盖选项：

变量	效果
PA_LOGIN_HINT=<upn>	预先选择该账户。由于目标账户已指定，因此不显示选择器。
PA_NO_ACCOUNT_PICKER=1	恢复普通浏览器 SSO。适用于不想多点一下的单账户用户。

优先级从高到低为：PA_LOGIN_HINT、switch_account 首选项、PA_NO_ACCOUNT_PICKER，然后是选择器。 例如，即使 switch_account 设置的用户名为 B，只要设置了 PA_LOGIN_HINT=A，目标账户仍为 A。省略用户名只会清除已存储的首选项； 不会覆盖 PA_LOGIN_HINT 或 PA_NO_ACCOUNT_PICKER。在这些情况下，响应会报告有效设置，而不会承诺显示账户选择器。

步骤 4：检查 FlowAgent 工具是否已接入

该插件通过 FlowAgent MCP 服务与 Power Automate 通信，该服务在插件的 .mcp.json 中注册为 flowagent，并会自动启动。.mcp.json 通过一个小型 Node 引导程序加载捆绑的 server/mcp.mjs，该程序会解析插件的安装目录（PLUGIN_ROOT，否则为 CLAUDE_PLUGIN_ROOT，再否则为当前目录），并在找不到捆绑文件时输出可执行的错误提示。

• 如果工具列表中出现 flowagent-* / mcp__flowagent__* 工具：告诉用户“Power Automate 工具已连接”，然后继续。

• 如果缺少这些工具：说明 MCP 服务尚未注册。自动修复：

  1. 定位已安装插件的 MCP 捆绑文件。 这只会匹配 power-automate 插件目录中的捆绑文件，因此不会误选其他插件的 MCP 服务：

     node -e "const fs=require('fs'),p=require('path'),d=p.join(process.env.HOME||process.env.USERPROFILE,'.copilot','installed-plugins');const find=(dir)=>{let out=[];for(const e of fs.readdirSync(dir,{withFileTypes:true})){const f=p.join(dir,e.name);if(e.isDirectory()){try{out=out.concat(find(f))}catch{}}else if(e.name==='mcp.mjs'&&p.basename(p.dirname(dir))==='power-automate'){out.push(dir)}}return out};try{const hits=find(d);if(hits.length===1)console.log(JSON.stringify({found:true,serverDir:hits[0],mcpMjs:p.join(hits[0],'mcp.mjs')}));else if(hits.length>1)console.log(JSON.stringify({found:false,reason:'multiple power-automate bundles',candidates:hits}));else console.log(JSON.stringify({found:false}))}catch(e){console.log(JSON.stringify({found:false,error:e.message}))}"
     

     如果提示 multiple power-automate bundles，请列出候选项，并询问用户要注册哪一个，而不是自行猜测。

  2. 如果只找到一个，读取 ~/.copilot/mcp-config.json，添加 flowagent MCP 条目，然后写回文件：

     node -e "const fs=require('fs'),p=require('path');const home=process.env.HOME||process.env.USERPROFILE;const cfgPath=p.join(home,'.copilot','mcp-config.json');let cfg;try{cfg=JSON.parse(fs.readFileSync(cfgPath,'utf8'))}catch{cfg={mcpServers:{}}};if(!cfg.mcpServers)cfg.mcpServers={};if(cfg.mcpServers.flowagent){console.log('already registered');process.exit(0)}const d=p.join(home,'.copilot','installed-plugins');const find=(dir)=>{let out=[];for(const e of fs.readdirSync(dir,{withFileTypes:true})){const f=p.join(dir,e.name);if(e.isDirectory()){try{out=out.concat(find(f))}catch{}}else if(e.name==='mcp.mjs'&&p.basename(p.dirname(dir))==='power-automate'){out.push(dir)}}return out};const hits=find(d);if(hits.length!==1){console.log(hits.length?'ambiguous: '+JSON.stringify(hits):'mcp.mjs not found');process.exit(1)}const mcpPath=p.join(hits[0],'mcp.mjs');cfg.mcpServers.flowagent={command:'node',args:[mcpPath]};fs.writeFileSync(cfgPath,JSON.stringify(cfg,null,2)+'\n');console.log('registered flowagent MCP at '+mcpPath)"
     

  3. 告诉用户重启 Agent（Copilot CLI：/restart；Claude Code：重启进程）。重启后，应该会出现 flowagent-* 工具。

  4. 如果未找到（尚未安装插件）：告诉用户先安装插件：

     /plugin marketplace add microsoft/power-platform-skills
     

     然后选择 power-automate，并再次运行 /setup。

第 5 步：冒烟测试

通过列出用户的环境，验证整个流程是否正常运行：

• 首选：调用 list_environments 工具。

• 如果 MCP 工具不可用：运行 node <path-to-plugin>/server/mcp.mjs 确认打包的 MCP 服务能正常启动，然后修复插件安装或 .mcp.json 配置，再重试。

• 如果返回了环境：成功！告诉他们：

  • “一切运行正常！以下是你的 Power Automate 环境：”
  • 用一个简单的表格展示环境（名称、位置）。
  • 如果有多个环境，询问他们主要使用哪一个，并建议将其设为默认环境（使用 set_current_env 工具，或询问“将我的默认环境设为 ”）。
  • 告知他们有哪些可用技能：
    • /browse-flows — 浏览你的流程
    • /create-flow — 创建新流程
    • /debug-flow — 修复故障流程

• 如果失败：检查错误。常见问题：

  • 身份验证错误 → 返回第 3 步
  • 未找到工具 → 返回第 4 步
  • 网络错误 → 询问他们是否使用了企业代理/VPN

语气指南

• 使用“我们”的说法：“我们来检查一下是否安装了 Node.js”
• 庆祝小小的成功：“太好了，Node.js 已就绪！”
• 不要一次性列出所有步骤——每次只进行一步，并在继续之前确认
• 如果遇到问题，不要慌张——用通俗易懂的语言解释出了什么问题以及该怎么做
• 不要直接向用户展示原始 JSON 错误，而不解释其含义