Copilot Studio MCP

Copilot Studio MCP

一个 MCP 服务，让编码 Agent（VS Code 中的 GitHub Copilot、Claude Code 或任何其他 MCP 客户端）能够直接在编辑器中构建、测试、发布和维护 Microsoft Copilot Studio Agent。

Agent 会成为一个由 YAML 文件组成的文件夹，你可以阅读、比较差异并提交。该服务按照 Copilot Studio VS Code 扩展的方式写入此文件夹，通过官方 Power Platform CLI（pac）将其与实时 Agent 同步，并调用 Power Platform、Dataverse、BAP、Power Automate 和 DirectLine API，处理 CLI 未覆盖的内容：评估、聊天、云端流、门户差异和对话记录。未经你批准，任何内容都不会进入实时环境；如果还有选项未确定，工具会提出问题，而不是直接失败。

你可以用它做什么

你的目标	执行的操作	阅读
新建 Agent 并使其上线	在解决方案中创建 Agent，生成说明，添加知识、主题和工具，进行审查、验证、推送、发布并与其对话	构建新 Agent
修改现有 Agent	将其克隆到文件中，编辑或移除组件，进行审查，合并同事所做的更改，然后推送	处理现有 Agent
为 Agent 添加可调用的内容	根据环境中的实际情况选择连接器操作、MCP 服务、云端流、AI Builder 提示词或其他 Agent	为 Agent 添加工具
确认 Agent 是否正常工作	与已发布的 Agent 聊天，运行可重复的对话测试，以及查看包含逐个用例结果的评估运行	发布和测试
从真实用户那里学习	查看对话记录、会话结果、升级率，并利用真实问题构建回归测试集	从生产对话中学习
避免覆盖同事在门户中的更改	查看上次同步后门户中的更改，阻止可能产生冲突的推送，并进行合并	保持工作区与门户同步
无需手写 Logic Apps JSON 即可编写 Power Automate 流	根据步骤组合定义、创建流、绑定其连接、启用流并查看运行历史记录	构建云端流
找出流不断失败的原因	解析失败的连接器操作背后的实际错误，与成功的运行进行差异比较，并查看失败集中出现的位置	构建云端流
部署到测试和生产环境	拉取整个解决方案，映射连接和变量，按 1:1 部署并发布；或使用管道	将解决方案部署到其他环境
验证各阶段是否一致	为各个环境创建快照、进行比较，并在管道中设置差异门禁	比较 DTAP 中的各个环境
管理租户	管理环境、安全角色、DLP、租户设置、文件备份、团队入职，以及 Microsoft 365 Agent 目录	管理租户

完整工具列表请见 docs/tools.md，流程图请见 docs/flows.md；两者均包含在 npm 包的 docs/ 目录中。本页末尾的参考章节介绍了该服务可写入的 Agent 设置、身份验证和权限、配置、限制，以及该服务与 Microsoft 自己的 pac MCP 服务有何不同。

状态

早期版本。实际完成验证的内容：

• 离线：针对编译输出运行了 251 项单元测试，另有一个打包预言机，会将每个创作工具的 YAML 通过 pac copilot init 和 pac copilot pack 往返处理。
• 针对真实租户（2026-09-08，docs/live-verification.md 的 A 到 F 阶段）：连接器注册表、pac connection list 的布局、pac copilot clone 及其同步元数据、漂移检测和 cs_push 冲突拒绝，以及端到端的评估流程，包括门户的 CSV 导入格式和指标状态字符串。门户创建的 Agent 验证结果干净，因此 cs_validate 不会对真实内容产生误报。这次运行还发现了一个真实问题：pac copilot publish 会打印“Failed to publish”并以 0 退出，因此发布失败曾被报告为成功。现已修复。
• 尚未完成实时验证：转录工具、快速模式下的 cs_check_drift、cs_chat、Dataverse 的 listBots 路径、在环境之间移动解决方案，以及流程生成器生成的所有流程（目前还没有将任何流程导入环境）。

docs/verify.md 简要列出了仍未解决的问题，docs/STATUS.md 则是完整记录。确认任何会写入内容的操作前，请先阅读试运行说明。

设置

前提条件

• Node.js 20+。
• .NET 10 SDK 和 Power Platform CLI：dotnet tool install --global Microsoft.PowerApps.CLI.Tool。如果 SDK 位于用户配置文件目录中，请将 DOTNET_ROOT 设为该目录；如果 ~/.dotnet 目录存在，服务会默认使用该目录。
• 为所用环境创建一个 pac 身份验证配置文件，在终端中执行一次：pac auth create --environment <id or URL>。所有通过 pac 执行的操作（创建、克隆、拉取、推送、发布、解决方案、管理）都会使用该配置文件，并采用 Microsoft 自有的第一方应用。
• 对于基于 API 的工具（环境、评估、聊天、流程、漂移、转录）：在会话中通过 cs_login 使用 Entra 登录。默认情况下无需应用注册；身份验证和应用注册会说明何时需要注册，以及应用必须具备哪些权限。

安装和注册

该服务发布在 npm 上，名称为 copilot-studio-mcp，因此通常无需安装：将 MCP 客户端指向 npx，首次启动时会获取此软件包。

此外还有一个 VS Code 扩展 vscode-extension/，它会向 VS Code 的 MCP 主机注册此服务，并将下方的环境变量作为设置提供。它将服务及其 依赖项打包在 VSIX 中，因此首次启动无需 npm，也无需联网。使用 cd vscode-extension && npm install && npm run package 构建；使用 code --install-extension copilot-studio-mcp-<version>.vsix 安装生成的 .vsix。

VS Code，可从终端操作，也可手动编辑 .vscode/mcp.json（工作区）或用户级 mcp.json：

code --add-mcp '{"name":"copilot-studio","command":"npx","args":["-y","copilot-studio-mcp"]}'

{
  "servers": {
    "copilot-studio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "copilot-studio-mcp"],
      "env": { "CPS_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Claude Code（用户范围）：

claude mcp add-json copilot-studio '{"type":"stdio","command":"npx","args":["-y","copilot-studio-mcp"]}' --scope user

Mistral Vibe，在 ~/.vibe/config.toml（或 $VIBE_HOME/config.toml）中配置；工作目录中的 ./.vibe/config.toml 优先级更高。Vibe 默认只给服务 10 秒启动时间，而在企业网络中首次通过 npx 获取软件包可能会超过此时间，因此请全局安装并使用 node 运行入口文件（通过 npm root -g 查找目录）。在 Windows 上，路径请使用单引号：TOML 会将双引号中的反斜杠视为转义字符，而 "C:\Users\..." 不是有效的 TOML。

[[mcp_servers]]
name = "copilot-studio"
transport = "stdio"
command = "node"
args = ['C:\Users\<you>\AppData\Roaming\npm\node_modules\copilot-studio-mcp\dist\index.js']
startup_timeout_sec = 60   # default 10
tool_timeout_sec = 300     # default 60; solution exports and evaluation runs take longer

使用 npm install -g copilot-studio-mcp 并设置 "command": "copilot-studio-mcp"，可避免 npx 的启动 开销。此服务已发布到 MCP Registry，名称为 io.github.jgt87/copilot-studio-mcp。VS Code 的 MCP 图库（扩展视图，搜索 @mcp）通过 GitHub MCP Registry 获取其中的内容。若要从克隆的仓库运行，请参阅开发。

环境变量均为可选项，详见配置。

第一个会话

1. cs_init。 报告 pac 和 .NET 的状态、pac 配置文件及当前启用的配置文件、MSAL 登录状态、 当前生效的写入策略、找到的工作区以及该工作区的后续步骤。它还会返回工具预设菜单；使用 较小模型时，请选择一个（参阅 在较小模型上运行）。
2. 需要云工具时，调用 cs_login。 此调用会在服务所在环境中打开浏览器，并在 15 秒内返回； 如果届时登录尚未完成，会返回包含 URL 的 status: pending，你可以自行打开该 URL；下一次云工具调用 （或 cs_login_status）会获取令牌。这样一来，即使客户端限制了工具调用时长，或服务运行在无法启动 浏览器的环境中，也能完成登录。如果租户允许，还可以使用设备代码（mode: device_code）作为替代方式； 许多租户会通过条件访问策略阻止此方式。
3. 需要针对某项任务的操作指南，而不是自行设计步骤时，调用 cs_guide <topic>： getting-started、instructions、knowledge、tools、topics、evaluations、 publish-and-test、drift、transcripts、solutions、administration、troubleshooting。 每份指南都会列出各步骤所用的工具、无法自动化的门户操作，以及工作区的后续步骤。六个 MCP 提示词 （新建 Agent、添加知识、添加工具、编写说明、审阅并推送、检查偏移）会在将提示词显示为命令的客户端中， 封装相同的操作指南。

在任何变更前先审批

服务器绝不会自行更改正在运行的 Copilot Studio 环境。所有可能执行此类操作的工具 （cs_push、cs_publish、cs_run_evaluation、cs_import_solution、cs_deploy_solution、 带环境参数的 cs_create_agent、删除工具、会写入内容的流程和管理工具，以及会更改环境的 pac 封装工具）都会返回一份试运行，说明它将执行什么；在再次调用并传入 confirm: true 之前，不会进行任何其他操作。在 MCP 握手中，系统会指示调用方 Agent 向你展示这份试运行，并且只有在你同意后才传入 confirm；一次审批只适用于一次调用。

在磁盘上更改 Agent 时也采用相同方式，理由也相同：无意中进行的编辑很容易做出，却很难 察觉。首次调用 cs_add_topic、cs_add_knowledge_source、cs_add_tool、 cs_add_flow、cs_add_trigger、cs_add_variable、cs_edit_topic、cs_edit_tool、 cs_edit_knowledge、cs_update_settings、cs_update_agent 和 cs_generate_instructions 时，都不会写入任何内容。它们会返回变更内容——新建文件会完整 展示，编辑文件则会展示相对于当前内容的差异；再次以 confirm: true 进行同一调用时， 才会写入这些内容。审查、验证和描述操作都是只读的，也不会请求审批。

文本字段会单独计算，因为仅靠差异无法说明它们的变更情况：预览会显示字符数以及产品限制 的剩余容量；如果编辑内容会超出限制，就会直接拒绝，而不是等到推送时才失败。这些字段 的限制并不相同——instructions 最多容纳 8000 个字符，而 Settings > Responses > "Response formatting" 框（responseInstructions）最多只能容纳 500 个字符。

如需强制锁定，可在服务器环境中设置 CPS_READ_ONLY=1：届时不会注册会更改环境的工具， 因此无法通过任何确认触及环境；创作、验证、审查和只读工具仍可正常工作。cs_init 会报告 当前模式以及被禁用的工具。若某个声明了 confirm 的工具未列入该清单， test/policy.test.js 就会失败，确保这两层策略不会出现偏差。

以下三种行为会在每个工作流中出现：

• 提问，而不是报错。 如果调用无法继续，因为某项内容尚未确定（例如使用哪个连接器、 执行哪个操作或选择哪个 Agent），工具会返回 needsInput: true，说明需要什么、原因、 服务器能够列出时提供实际选项，以及可用于列出更多选项的工具。不会写入任何内容；调用方 Agent 会询问你，然后再次调用。所有客户端都支持此机制，包括不支持 MCP elicitation 的 客户端。
• 耗时较长的调用会在后台运行。 MCP 客户端会将工具调用限制在约一分钟内。可能运行更久 的工具（cs_pull_solution、cs_create_auth_profile、环境预配、所有 pac 封装工具）都接受 background: true，会立即返回 jobId；cs_job_status 则会从可在服务器重启后保留的 磁盘记录中报告各阶段和结果。工具会在启动任务前判断是否允许进行任何更改，因此确认约定 不受影响。
• 写入操作绝不重试。 如果读取操作遇到传输错误或 429/5xx 错误，会采用退避策略重试， 并遵循 Retry-After；发布或导入操作若发生超时，可能已经执行，因此只会报告结果，不会 再次执行。

两个账户：创建者和管理员

创建 Agent 和管理租户通常使用不同的账户。pac 每台机器只保留一个活动身份验证配置，因此请为每个账户创建一个配置，并让服务器进行切换：

pac auth create --name maker --environment <environment id or url>
pac auth create --name admin --environment <environment id or url>

或者，在会话中调用 cs_create_auth_profile，传入 name、environment 和 background: true，因为 pac 会打开自己的浏览器并等待登录（cs_job_status 会报告配置何时创建）。cs_list_auth_profiles 会显示配置及当前活动配置。

核心同步和解决方案工具使用 CPS_PAC_PROFILE；管理员命令和租户备份使用 CPS_ADMIN_PROFILE；每个 pac 封装器和 cs_pac 也都接受显式指定的 profile。服务器选择配置时，会在之后恢复先前的配置；进程中的每次 pac 调用共用一个队列，因此多步操作（引导、解决方案拉取与部署、快照）会在整个运行期间锁定该配置。其他服务器实例和终端中的 pac 命令不受此协调机制管理。API 工具使用的 MSAL 登录则是独立于 pac 的另一套机制。

构建新的 Agent

从空文件夹开始，直到发布一个可以与之对话的 Agent。每个步骤都是一次工具调用；会更改环境的步骤会先显示试运行结果。

1. 选择环境。 调用 cs_list_environments（需要 cs_login），或从 Copilot Studio URL 获取环境 ID。
2. 选择或创建解决方案。 cs_list_solutions 会显示现有解决方案；只要解决方案是非托管的，且使用其发布者前缀，就可以使用现有解决方案。若要为你的 Agent 创建一个解决方案：cs_create_solution uniqueName=contoso_Agents publisherPrefix=contoso confirm=true。解决方案是之后导出并导入以将 Agent 移至测试和生产环境的单位，因此值得专门选择，而不是让每个 Agent 都各自创建一个解决方案。
3. 在其中创建 Agent。 cs_create_agent name="Contoso Support" publisherPrefix=contoso projectDir=./contoso-support environment=<id> solutionName=contoso_Agents confirm=true（添加 createSolution=true，即可一并完成第 2 步）。服务器会在本地通过 pac copilot init 搭建脚手架，以解决方案名称打包并导入，然后将线上 Agent 克隆回来，使 projectDir 成为一个已连接同步的工作区，其中包含默认系统主题。若不指定 environment，则只会创建本地脚手架；它可以打包设置、Agent 和主题，但不能打包知识、工具或流。 省略 publisherPrefix 或 projectDir 后，工具会询问，而不是猜测；它会列出环境中的发布者（如果你指定了解决方案，还会列出该解决方案的发布者允许使用的前缀），并建议使用以 Agent 命名的文件夹。前缀值得一问：它会成为 Agent 所有组件架构名称的一部分（contoso_contososupport.topic.Greeting），之后无法更改，除非重新创建这些组件；而且它必须与 Agent 所属解决方案的发布者匹配。
4. 说明 Agent 的用途。 cs_generate_instructions purpose="Answer IT questions and create ServiceNow tickets" audience="Employees" tone="Friendly, brief" boundaries=["never reset passwords"] modelName="Agent instructions" 会通过 AI Builder 提示词起草指令（cs_list_prompts 会显示环境中的提示词；如果没有，请先在 AI Builder 中创建一个“write agent instructions”提示词）。检查草稿，然后再次调用并设置 apply=true，将其写入 agent.mcs.yml；之后可通过设置 refine=true 和 changeRequest 来修改现有内容。你也可以自行编写指令并使用 cs_update_agent，它还可以设置响应指令和模式、对话历史、功能、安全审核、模型及对话开场白（完整字段映射）。
5. 为它提供所需内容。 使用 cs_add_knowledge_source 添加公共网站、SharePoint、Graph 连接器或上传的文件；使用 cs_add_topic 创建基于触发短语以及消息、问题、条件、设置变量、重定向、HTTP、流、生成式答案（可选限定到指定知识源）、自适应卡片、转接和结束节点的确定性对话；使用 cs_add_tool 添加 Agent 应调用的任何工具（参阅工具工作流）。 cs_add_trigger 和 cs_add_variable 用于处理事件触发器和全局变量。
6. 检查并验证。 cs_review_agent 会对整个工作区进行基于规则的检查，并给出 10 分制评分：检查是否缺少升级处理或后备方案、工具描述是否薄弱、触发短语是否重叠、私有知识是否缺少身份验证，以及文件中是否包含机密信息。每项发现都会注明规则和修复方法。接着，cs_validate 会根据创作架构（744 个定义）检查每个文件，并进行跨文件检查：是否存在没有绑定对象的连接引用、不存在的目录操作，以及指向不存在主题的重定向。它还会拦截一些错误：推送时不会报错、但会导致错误存储的问题，例如拉取后遗留的合并冲突标记（推送时只保留标记前的文本）、遗留的 <AGENT_SCHEMA> 占位符、pac 不接受的文件名和架构名称，以及超过 200 个的触发短语。此外，它还会警告未加引号的 # 导致文本被截断、结束节点之后仍有节点、缺少 = 的公式、没有提交操作的自适应卡片，以及包含句点的主题名称；这些问题会导致解决方案无法导出。
7. 推送。 cs_push confirm=true 相当于门户中的“保存”：草稿 Agent 现在会显示你的主题、知识和工具。试运行会先执行验证和快速漂移检查；如果同事自上次拉取后在门户中修改了同一组件，推送将被拒绝。使用连接引用的工具需要在门户中执行一个步骤：在 Agent 的“工具”下打开该工具，点击“连接”，然后运行 cs_pull 以拉取绑定。
8. 发布并与其对话。 运行 cs_publish confirm=true，然后运行 cs_chat utterance="my laptop is slow"。测试工作流会将其转化为可重复执行的检查。

flowchart TD
    A["cs_init"] --> B["cs_list_solutions<br/>pick one, or cs_create_solution"]
    B --> C["cs_create_agent<br/>environment + solutionName + confirm"]
    C --> D["cs_generate_instructions<br/>AI Builder prompt, then apply"]
    D --> E["cs_add_topic / cs_add_knowledge_source / cs_add_tool<br/>(cs_list_connectors, cs_describe_connector)"]
    E --> R["cs_review_agent"]
    R --> H["cs_validate"]
    H -- errors --> E
    H -- clean --> I["cs_push confirm"]
    I --> J{"tool needs a connection?"}
    J -- yes --> J1["portal: authorise once"] --> J2["cs_pull"] --> K
    J -- no --> K["cs_publish confirm"]
    K --> L["cs_chat"]

GitHub Copilot harness Agent（通过 cs_create_agent 并设置 authoringMode: cli-copilot 创建）提供的功能较精简：初始化、打包、导入、指令和聊天。主题和评估属于标准 harness 功能。

开发现有 Agent

大多数 Agent 已经存在，通常是在门户中创建的。工作流程是克隆、修改、审查、合并、推送。

1. 克隆。 通过 pac 或 Dataverse 调用 cs_list_agents，然后运行 cs_clone_agent bot=<id or schema name> outputDir=./support-agent。结果是一个已连接同步的工作区，其中包含 agent.mcs.yml、settings.mcs.yml、topics/、knowledge/、actions/、trigger/、 variables/、workflows/ 以及连接引用。cs_describe_workspace 会汇总其中的内容， 并在最后给出后续步骤。
2. 修改。 可以按名称、文件名或路径查找组件。cs_edit_topic 可修改触发短语、优先级和节点 （按位置或 id）；cs_edit_tool 可修改说明、输入和连接；cs_edit_knowledge 可修改网站或 触发条件；cs_remove_component 可删除主题、知识源、工具、触发器或变量，并清理没有其他 组件使用的连接引用，同时指出留下的任何失效重定向。cs_update_agent 和 cs_update_settings 用于修改 Agent 自身的设置。添加组件的方式与新建 Agent 流程相同。 每次修改都会保留扩展要求的文件头。
3. 审查并合并。 运行 cs_review_agent，然后运行 cs_pull，将同事在门户中所做的修改拉取下来 （pac 的三方合并），接着运行 cs_validate。
4. 推送。 运行 cs_push confirm=true。如果门户修改和本地编辑涉及同一个组件，推送会被阻止； cs_pull 可以解决冲突，force: true 则会覆盖冲突。
5. 提交。 将工作区保存在 git 中，并在每次拉取后提交（工具结果会提醒你）。这样，门户中的 漂移会以差异的形式显示，供你审查：接受该差异意味着提交，拒绝则意味着推送本地版本。

在此工作流程之外：cs_delete_agent 和 cs_delete_solution 可从环境中删除内容（需使用 confirm）；cs_extract_agent_template 和 cs_create_agent_from_template 可将 Agent 转换为 模板，以便创建更多 Agent；cs_extract_translations 和 cs_merge_translations 可完成本地化往返流程 （支持 .resx 或 .json，并可使用 whatIf）；cs_quarantine_agent 可将 Agent 停用并恢复。

为 Agent 添加工具

Copilot Studio Agent 可以调用环境中的任何连接器（包括一千多个 Microsoft 发布的连接器和自定义连接器）、通过连接器公开的 MCP 服务、云流、AI Builder 提示词、其他 Agent，以及少数其他类型。服务端通过 YAML 架构了解类型，通过环境了解实例；只有环境才能知道其中有哪些实例。

1. 查找连接器。 cs_list_connectors search=ServiceNow 会列出环境的连接器注册表，也就是门户中“添加工具”显示的同一份列表，并标出 MCP 服务。如果尚未登录，则会回退到根据公开连接器参考生成的离线种子数据（将显示名称映射到 shared_ ID，不含操作）：这只是起点，并不能证明你有权使用该连接器。
2. 查找操作。 cs_describe_connector connector=shared_service-now operation=incident 会将连接器的 OpenAPI 定义转换为操作，列出 operationId、必需和可选参数以及响应字段；x-ms-agentic-protocol: mcp-streamable-1.0 表示 MCP 端点。定义会缓存在 .cs-catalog/<environment>/ 中，以便后续调用离线进行。
3. 添加工具。 cs_add_tool 接受连接器操作、MCP 服务、云流、AI Builder 提示词（cs_list_prompts 可列出这些提示词）、已连接的 Agent 或子 Agent 的类型化规范，也接受用于其他类型的 raw 类型（AI 插件、Bot Framework 技能、客户端操作、计算机操作 Agent）。如果定义已缓存，它会检查 operationId，根据操作的必需参数填入自动输入，并将 YAML 写入 actions/，同时创建连接引用存根。如果你还没有指定连接器或操作，调用会以问题的形式返回排名靠前的候选项。
4. 在门户中连接一次。 连接是经授权的链接，只有门户才能创建（唯一例外是服务主体 Dataverse 连接，可通过 cs_create_connection 创建）。运行 cs_push 后，在 Agent 的“工具”下打开该工具，点击“连接”，然后运行 cs_pull。cs_validate 会警告操作不在缓存定义中的工具文件；cs_review_agent 会标记描述不足以让编排器选中工具的情况。

单元测试会比较架构中的工具类型列表与服务端的类型表，因此，若架构更新引入了新类型，在该类型完成分类前，构建就会失败。作为工具的流要么是脚手架（cs_add_flow，实验性），要么是通过流生成器构建并在 Agent 中引用的真实流。

发布和测试

1. 发布。 cs_publish confirm=true 相当于“发布”按钮，可通过 pac copilot publish 或 Dataverse PvaPublish 操作发布，并轮询直到 publishedon 发生变化。

2. 聊天。 cs_chat utterance="..." 会向已发布的 Agent 发送一条话语并返回回复；将 conversationId 传回即可继续下一轮。使用 transport: auto 时，服务端会读取 Agent 的身份验证模式：无身份验证和手动身份验证的 Agent 通过 DirectLine 进行通信（已发布 Agent 的令牌端点允许匿名访问，因此无需应用）；集成了 Entra 身份验证的 Agent 则通过 Copilot Studio 客户端 SDK 进行通信，并需要你自己的应用 ID 和 CopilotStudio.Copilots.Invoke 范围（clientId 或 CPS_CLIENT_ID）。

3. 让测试可重复。 cs_run_conversation_tests 会通过相同的聊天路径运行包含话语和预期结果的 YAML 文件，并报告失败项。预期结果涵盖措辞和 Agent 的行为：usedTool、notUsedTool、usedTopic、notUsedTopic 和 citedKnowledge 会从活动中读取主题、工具和知识归属信息，因此测试可以区分真正调用了工具和只是读起来像正确答案的回复。每个结果以及每条 cs_chat 回复都会报告观测到的主题、工具和引用；如果某项预期结果无法判定（活动中没有归属信息），会说明原因，而不会因此判定 Agent 失败。归属信息的键名来自文档，尚未通过实时验证；docs/test-verification.md 是用于确认这些键名的操作手册。

4. 评估。 门户的 Evaluation 功能会针对 Agent 运行一组测试问题，并为每个答案评分。其 API 唯一无法完成的操作是创建测试集，因此流程如下：

   • cs_create_test_set_csv suggestFromWorkspace=true 会按照门户的导入格式写入 CSV（最多 100 个案例），并以你的主题和知识为种子。
   • 在门户的 Evaluation 选项卡中导入一次。
   • 运行 cs_list_test_sets，然后运行 cs_run_evaluation confirm=true wait=true，再运行 cs_get_evaluation_run 查看按通过和失败分类的单个案例结果；使用 cs_list_evaluation_runs 查看历史记录。

flowchart TD
    A["cs_create_test_set_csv"] --> B["portal: Evaluation > Import CSV"]
    B --> C["cs_list_test_sets"] --> D["cs_run_evaluation confirm wait"]
    D --> E["cs_get_evaluation_run"] --> F{"failures?"}
    F -- yes --> G["fix topics / instructions / knowledge"] --> H["cs_push confirm"] --> D
    F -- no --> I["cs_publish confirm"]

从生产对话中学习

人们开始使用 Agent 后，对话记录便是测试案例以及 Agent 无法回答的问题的最佳来源。Copilot Studio 会将每个会话存储在 Dataverse 的 conversationtranscript 表中；服务端会读取该表，但绝不会写入。

• cs_list_transcripts 会列出指定时间段内的会话：时间、轮次数、首个问题、触发的主题和工具，以及会话的结束方式。
• cs_get_transcript 会返回某个会话的完整轮次列表，并列出每轮对应的主题和工具。
• cs_summarize_transcripts 会汇总指定时间段：结果、升级率、未匹配任何主题的会话、热门主题和工具，以及导致失败的问题。
• cs_test_set_from_transcripts 会根据用户实际提出的问题生成 Evaluation 导入 CSV，并优先纳入失败案例，让下一次评估运行覆盖出错的情况。

Copilot Studio 不会报告对话是否成功。结果由此服务端根据对话记录判定（升级、Agent 表示无法回答，或用户发言后没有回复）；resolved 表示没有任何标记将该会话判定为失败，并不代表用户满意。每个结果都会重申这一注意事项，而 cs_guide transcripts 会介绍从汇总到单条对话记录，再到回归测试集的完整流程。对话记录包含用户对 Agent 说的话，因此，已登录用户需要拥有可读取该表的角色权限，且结果属于客户数据。尚未在实时租户中验证。

保持工作区与门户同步

克隆 Agent 后，创建者仍可在 Copilot Studio 中继续编辑；平台不会阻止他们，也不会发送通知。门户中的每次编辑都会写入 Dataverse 行：用于设置和指令的 bot 行，以及每个主题、知识源、工具、触发器和变量各自对应的一个 botcomponent 行；每行都带有修改时间戳和修改者。服务器会利用这些行在无需重新扫描的情况下检测偏差，并在需要查看详细信息时通过克隆来确认。

1. 同步标记。 cs_clone_agent、cs_pull、cs_push 和 cs_create_agent（带有 environment）会写入 .mcs/cs-sync.json：其中包含每个工作区文件的指纹；如果缓存了 Dataverse 登录信息，还会包含每个组件的修改时间戳。cs_describe_workspace 会显示上次同步时间。
2. 快速检查。 cs_check_drift（默认 mode: quick）会读取 bot 行及其组件行，并与标记进行比较：哪些组件在门户中被修改、添加或删除，由谁在何时修改，Agent 设置是否有变更，以及实时 Agent 是否存在未发布的更改。每个组件都会映射到其工作区文件；如果该文件也在本地发生了更改，则该条目属于冲突。只需几秒，无需 pac；需要 cs_login。
3. 完整检查。 cs_check_drift mode=full 会运行 pac copilot clone，克隆到临时文件夹，然后根据标记从三个方面对每个文件进行分类：local-modified、remote-modified、both-modified（冲突），以及任一侧新增或删除的文件，并提供统一差异。快速检查报告偏差且你想查看确切内容时，或没有 Dataverse 登录信息时（只需要 pac 配置文件），请使用此模式。上传的知识文件会在此处检查，快速检查不会检查这些文件。
4. 推送前检查。 cs_push 的试运行包含快速检查，因此调用方会在确认前看到“自上次拉取后，Copilot Studio 中有三个组件发生了更改”。使用 confirm 时，如果门户更改和本地编辑涉及同一组件，推送会被阻止；使用 cs_pull（pac 的三方合并）可解决冲突，force: true 则会覆盖此限制。
5. 以 Git 作为记录账本。 每次 cs_pull 后都要提交；cs_check_drift 会报告工作区是否位于仓库中，以及有多少文件尚未提交。

限制。快速检查无法检测连接（预期创建者会连接工具，且所有比较都会忽略连接 ID）、上传的知识文件、通道配置或安全组。如果标记没有每个组件的基线（同步时没有 Dataverse 登录信息），则会回退到同步时间并留出两分钟余量，因此同步后立即进行的编辑会被视为同步本身的一部分。组件查询尚未在实时环境中验证；请参阅 docs/STATUS.md。

构建云端流

流与主题一样，基于步骤规范构建，因此无需手写 Logic Apps JSON。cs_build_flow_definition 会在本地组合定义，并连同所需的连接引用一起返回；cs_create_flow 接受相同的规范，并在环境或解决方案中创建流；cs_update_flow 接受该规范并替换现有非托管流的定义，同时保留其连接引用。

规范由一个触发器和按顺序运行的步骤组成：

触发器	用途
agent（默认）	Copilot Studio Agent 作为工具调用的流，包含类型化输入和响应
manual、http	由人员或 HTTP 请求启动
recurrence	定时计划
connector	连接器事件，例如创建 Dataverse 行
raw	以原文形式编写的其他任意触发器
步骤	生成内容
---	---
connector	连接器操作（OpenApiConnection），包含其参数和连接引用
http	HTTP 调用
condition、foreach、scope	分支、循环和分组，包含各自的嵌套步骤
initializeVariable、setVariable、compose	变量和中间值
terminate	以指定状态结束运行
response	Agent 可调用的流程或 HTTP 流程返回的内容（提供 outputs 时会自动添加）
raw	其他任意操作，按原样写入

构建器会串联 runAfter，使每个步骤都等待上一步完成；按照 Power Automate 的方式规范化操作名称，并为每个使用的连接器收集一个连接引用，在各步骤间复用。表达式使用 Logic Apps 表达式，而不是 Power Fx：@{triggerBody()?['orderId']}、@body('List_rows')?['value']。连接器 ID 和操作 ID 来自 cs_list_connectors 和 cs_describe_connector；操作的参数与连接器步骤的 parameters 完全一致。

构建器周边的工具：cs_list_flows 显示环境中的流程及其状态、所有者和连接引用；cs_get_flow 返回某个流程的完整定义；cs_delete_flow 永久删除流程；cs_list_flow_runs、cs_get_flow_run 和 cs_run_flow 用于读取运行历史记录，并通过 Power Automate 服务启动手动运行（需要单独登录：cs_login scope='flow'；登录用户必须是该流程的所有者或共同所有者）。

绑定连接。 连接引用用于指定连接器；连接则是某个人授权使用该连接器的账户。在两者关联之前，流程无法运行。cs_bind_flow_connection 用于关联两者：如果只有一个引用和一个可用连接，只需提供流程 ID；如果有多个可选项，工具会询问你选择哪一个。该工具会写入流程所使用的两种结构之一：在解决方案之外构建的流程会直接指定其连接，而从解决方案导入的流程则指向 connectionreference 行；设置 activate: true 会在同一次调用中启用流程。绑定连接后，cs_set_flow_state 可单独启用流程。

查明运行失败的原因。 运行列表只会显示某次运行失败，不会提供更多信息。

工具	说明
cs_explain_flow_run	这次运行为什么失败？ 失败的连接器操作本身不会携带错误消息——消息位于操作的输出中，需通过一个几天后就会过期的链接获取。此工具会获取该消息，判断故障来自连接器、表达式还是超时，并将操作的输入与它之前运行的操作的输出一起显示。
cs_compare_flow_runs	昨天还好好的。 将失败的运行与最近一次成功运行进行差异比较，并指出两次运行从哪个操作开始出现分歧。设置 compareTriggerData: true 后，工具会报告触发器载荷中哪些键不同（仅显示键名，绝不显示值），从而区分输入错误和流程故障。某个操作只出现在其中一次运行中，意味着流程定义本身发生了变化。
cs_analyze_flow_health	有时会失败。 显示失败率、时长中位数和第 90 百分位数，以及失败发生在哪些操作上。若大多数失败都由一个操作引起，说明该步骤存在故障；若失败分散在多个操作中，则可能是连接、限流或被调用的系统出了问题。

触发器失败意味着流程根本没有运行，因此故障出在触发器的连接或参数上，而非逻辑本身。运行详情会过期：输入和输出只保留有限时间，因此应趁失败记录尚未过期时进行诊断。

有两件事构建器无法替你完成。目标环境中必须先存在连接本身，之后才能绑定它们；这就是新建流程时会将其设为关闭状态的原因。此外，流程定义遵循 Logic Apps 架构和导出的解决方案，而非经过验证的往返流程，因此导入后应先在 Power Automate 中打开，确认结构无误后再使用。

将解决方案发布到另一个环境

每个 Agent 的同步始终绑定到该 Agent 所属的环境。迁移到测试或生产环境，需要先导出并导入解决方案；服务器会依次执行拉取、生成设置文件和部署。

1. 查看要迁移的内容。 依次运行 cs_list_solutions 和 cs_describe_solution，导出、解包并盘点其中的 Agent、机器人组件、流、连接引用、环境变量和自定义连接器。
2. 拉取解决方案。 cs_pull_solution 会以非托管和托管形式导出解决方案，将其解包到 src/，写入部署时读取的清单 solution.json，创建 deployment-settings.json，并将每个 Agent 克隆到 agents/。完整拉取需要几分钟，因此请传入 background: true，然后使用 cs_job_status 跟踪状态；结果也会写入目标目录中的 pull-job.json。
3. 映射目标环境。 在目标环境中运行 cs_list_connections，查看其中现有的连接；cs_create_deployment_settings 会将每个连接引用映射到相应连接，为目标环境设置环境变量值，并为每个 Agent 设置可使用它的 Entra 安全组。
4. 部署。 cs_deploy_solution confirm=true 会使用设置文件将解决方案导入目标环境，并对每个 Agent 运行 pac copilot publish（publishAgents 默认开启）。如果有任何连接引用尚未映射，该工具会拒绝导入；传入 allowUnmapped: true 可跳过此限制。如果你手动编辑了 src/，请先运行 cs_pack_solution。

同一流程中的质量检查和其他选项：cs_check_solution 会在部署前运行 Solution Checker；cs_set_solution_version、cs_solution_online_version 和 cs_upgrade_solution 用于管理发行版本号和分阶段升级；cs_publish_customizations 会发布环境中的所有自定义项；cs_list_pipelines 和 cs_deploy_pipeline 使用 Power Platform 管道，而非直接导入；cs_init_solution_project、cs_clone_solution、cs_sync_solution、cs_add_solution_reference 和 cs_add_solution_license 用于维护纳入源代码管理的解决方案项目（.cdsproj）；cs_add_solution_component 会将现有组件添加到解决方案中。

没有任何工具会一并迁移的内容

在将副本称为“1:1”之前，请先规划好以下事项：

• **连接不属于解决方案的一部分。**解决方案会携带连接引用；连接本身（指向 SharePoint、Outlook、Dataverse、MCP 服务等的已授权链接）必须已在目标环境中存在，并由用户在该环境中创建并授予同意。 cs_create_connection 是唯一例外，且仅支持服务主体 Dataverse 连接。使用 allowUnmapped: true 时，工具会保持未绑定状态，直到有人在目标门户中将其绑定。
• **如果无法解析连接引用，云端流会以关闭状态导入。**绑定连接后，cs_list_flows 会显示哪些流尚未激活，然后使用 cs_set_flow_state 逐一启用；此步骤无需使用门户。
• **环境变量需要设置目标值。**设置文件会列出所有变量；如果将某个值留空，目标环境会继承解决方案中的默认值，而这通常是开发环境的值。
• **Agent 的使用权限按环境设置。**设置文件包含一个 CopilotAgents 部分，其中每个 Agent 都有一个 AadGroupId（已通过 pac 2.11.2 验证）。将其映射到目标环境的 Entra 组（在 cs_create_deployment_settings 中使用 copilotAgents），或在导入后通过目标门户设置访问权限；全零 ID 表示未设置组。
• **部分 Agent 内容位于解决方案之外。**上传的知识文件、用作知识来源的 Dataverse 表、SharePoint 权限以及渠道配置（Teams、Web、Microsoft 365 Copilot）都因环境而异。导入后，请检查知识来源，并在目标门户中重新发布到各个渠道。
• 托管与非托管。cs_pull_solution 会同时导出两者。向下游环境部署托管解决方案，仅将非托管解决方案用于开发；在目标环境中导入托管解决方案后，无法直接编辑。
• 按 Agent 同步不会跨环境进行。cs_clone_agent 或 cs_pull_solution 创建的工作区只会推送回源环境。编辑 agents/<name> 工作区，将更改推送到源环境，然后重新拉取并部署解决方案。

比较 DTAP 各环境

当同一解决方案依次部署到开发、测试、验收和生产环境时，需要确认每个阶段是否仍保留了上一阶段的内容。平台不支持跨环境差异比较，但所有输入都可以访问，因此服务器会将每个环境捕获到一个快照文件夹中，并在离线状态下比较快照。

1. 使用 cs_snapshot_environment 为每个阶段创建快照（也可以使用 cs_compare_environments 一次完成，该工具接受按顺序排列的环境链，并比较每对相邻环境）。快照文件夹包含：

   snapshots/TEST/
     snapshot.json         label, environment, time, solution version and managed flag,
                           agents with publish state, flows, connection references,
                           environment variables, notes
     agents/<Agent name>/  the agent as YAML, from pac copilot clone
   

   Agent 会被克隆，而不是作为解决方案导出，因为无法从测试或生产环境导出托管解决方案。Flows、连接引用、环境变量和发布状态来自 Dataverse；使用 cs_login 登录后会将这些内容纳入快照，否则快照会注明已跳过这些内容。

2. 使用 cs_compare_snapshots 比较相邻阶段（DEV 与 TEST、TEST 与 ACC、ACC 与 PROD）。每次比较都会生成 <A>-vs-<B>.md 和 .json。

3. 查看结论。 报告以 DRIFT 或 no drift 开头，随后列出差异、预期差异，以及各层的表格，其中包含发生变化的 Agent 文件的统一差异。

4. 采取行动。 Agent YAML 存在差异，意味着后续阶段落后了，或文件曾被直接修改：请按照上述解决方案流程重新部署。未绑定的连接引用、缺失的 Flow 或没有值的变量属于部署设置问题：请修复设置文件并重新部署。

5. 保留历史记录。 快照文件夹是普通文件；将其提交到版本控制（不包含 .mcs/ 状态），即可为每个阶段保留时间线。

哪些情况算作差异，以及哪些属于阶段之间的预期差异：

层	差异	预期差异（会报告，但不算作差异）
解决方案	版本不同，或某个阶段缺少解决方案	后续阶段为托管，开发环境为非托管
Agent YAML（主题、指令、知识、工具、触发器、变量）	规范化后，文件有任何更改、新增或删除	connectionreferences.mcs.yml 中的 ID、审计信息、版本字段和连接 ID（比较前会移除）
发布状态	任一阶段在上次发布后有修改（存在未发布的更改）
Flows	某个阶段缺少 Flow，或开关状态不同
连接引用	缺失、连接器不同，或某个阶段未绑定	各阶段绑定到不同的连接
环境变量	缺失，或某个阶段没有值	各阶段的值不同（只有设置 strictVariables 时才算作差异）
身份验证模式	各阶段之间不同

流水线关卡。 cs_compare_snapshots 和 cs_compare_environments 接受 failOnDrift；此时工具结果会报错，脚本化 MCP 客户端或流水线步骤可以据此将作业标记为失败。以下是将 TEST 部署到 ACC 前的典型关卡：

cs_snapshot_environment label=TEST environment=<test id> dir=snapshots/TEST solution=<name>
cs_snapshot_environment label=ACC  environment=<acc id>  dir=snapshots/ACC  solution=<name>
cs_compare_snapshots a=snapshots/TEST b=snapshots/ACC failOnDrift=true

注意事项：所有阶段都必须能通过当前活动的 pac 身份验证配置文件访问（对于跨租户的环境链，请在各阶段之间运行 pac auth select，并逐个创建快照）；pac copilot clone 能否在托管 Agent 上成功，尚未经过实时验证（备选方案是通过 Dataverse Web API 读取相同的组件定义）；上传的知识文件和通道配置仅会列出名称和大小；如果未登录 Dataverse，比较内容仅包括解决方案版本和 Agent YAML，报告会注明这一点。

管理租户

管理操作以管理员帐户运行（两个帐户）：传入 profile，或设置一次 CPS_ADMIN_PROFILE。每项变更都会经过相同的试运行和 confirm；重置、删除、复制和还原会销毁或覆盖整个环境，试运行会说明将丢失哪些内容。

• 将配置备份到文件。 cs_backup_tenant 会将整个租户配置写入一个文件夹：租户设置、环境、DLP 策略、环境组、服务主体、已注册应用程序、模板，以及每个环境的详细信息、解决方案、Agent、连接、安全角色和平台备份。原始输出会与解析后的行一同保留；如果某项捕获失败，会将其隔离，确保其余备份仍能完成。

• 读取和更改租户。 环境及其进行中的操作、租户设置（读取到 JSON 文件、修改一项）、DLP 策略（哪些连接器可以组合使用）、环境组、安全角色、服务主体和已注册应用程序、托管环境治理、管理模式和备份保留策略，以及环境生命周期：创建、复制、备份、还原、重置、删除。每项操作对应一个 cs_admin_* 工具 （列表）。

• 为团队在新环境中完成入驻。 使用 cs_admin_create_environment（耗时较长；将它与 background: true 和 cs_job_status 配合使用），然后通过 CSV 使用 cs_admin_assign_users：

  UPN,Security Roles,Business Unit
  [email protected],"System Customizer,Basic User",Sales
  [email protected],Environment Maker,
  

  pac 每次调用只能处理一位用户和一个角色，因此这份名单需要调用五次；该工具会展开名单，在试运行中显示每一组用户和角色，并在一次审批下执行。各行彼此独立，因此即使 UPN 输入有误，也会报告错误并继续处理其余行。如果名单实际是一个组，优先使用 cs_admin_assign_group：将 Entra 组绑定到角色只需调用一次，无论组内有多少人，新成员加入后也会继承访问权限。角色名称按环境区分（对新环境运行 cs_admin_list_security_roles 查询）；尚未在该环境中完成预配的用户无法在该环境中分配角色。

• Microsoft 365 Agent 目录。 cs_list_agents 会读取一个环境的 bots 表，并止步于 Power Platform 的边界。目录（Microsoft Graph，需要通过 cs_login scope='graph' 单独登录）覆盖整个租户，可回答 cs_publish 之后的问题：Agent 是否真的触达了任何人？cs_list_org_agents 会报告每个 Agent 可供哪些人使用、部署位置以及是否被阻止，并可按平台、主机、元素类型或最后修改日期筛选；cs_get_org_agent 会完整返回一个条目；cs_block_org_agent 可为租户中的所有人阻止某个 Agent，或解除阻止；cs_reassign_org_agent 可在原所有者离职时将其移交给新所有者（两者都需要 confirm）。需要 Microsoft Agent 365 许可证，仅支持全球云，尚未在实时租户上验证；阻止和重新分配功能仅存在于 Graph beta 中。

所有没有专属工具的 pac 命令都可以通过 cs_pac 使用：只读命令会立即运行，其余命令会返回试运行结果，并需要 confirm。Copilot Studio 之外的 pac 命令组（application、canvas、catalog、code、data、managed-identity、model、modelbuilder、package、pages、pcf、plugin、power-fx、telemetry、test、tool）特意保留在 pac 中。

此服务可写入的 Agent 设置

Agent 的设置存储在两个文件中，服务会读取、验证并推送这两个文件。下表将门户中显示的内容映射到写入该内容的字段和工具参数。此处所有操作都会更改本地文件，更改前会显示预览，并且只有在 confirm: true 时才会写入；cs_push 会应用更改，cs_publish 会使其生效。产品将 instructions 限制为 8000 个字符，预览中会统计字符数。

agent.mcs.yml（Agent 定义），由 cs_update_agent 写入：

门户	字段	参数
指令	instructions	instructions、appendInstructions（或 cs_generate_instructions）
响应：答案的措辞和格式（“响应格式”）	responseInstructions	responseInstructions、appendResponseInstructions——500 个字符，预览中会统计字符数
响应：响应模式	defaultResponseMode	defaultResponseMode：Auto、ThinkDeeper、QuickResponse
Agent 可见的对话历史	historyType	history：none 或 conversation，以及 historyMessages
功能：网页浏览、代码解释器、图像生成、Teams / SharePoint / 电子邮件 / 会议 / 人员搜索	gptCapabilities	capabilities（只会更改你传入的开关）
通用知识：模型是否可以超出你的知识来源回答	aISettings.useModelKnowledge	useModelKnowledge
内容审核	aISettings.contentModeration	contentModeration：Minimum 到 Maximum
文件分析、语义搜索	aISettings.isFileAnalysisEnabled、aISettings.isSemanticSearchEnabled	isFileAnalysisEnabled、isSemanticSearchEnabled
模型	aISettings.model.modelNameHint	modelNameHint
对话开场白	conversationStarters	conversationStarters、addConversationStarters
显示名称	displayName	displayName

系统会根据创作架构检查值，因此如果响应模式或审核级别不在允许范围内，系统会拒绝写入。

settings.mcs.yml（Agent 的运行方式），由 cs_update_settings 使用点路径写入，例如 {"configuration.settings.GenerativeActionsEnabled": true}：

门户	路径
生成式编排开启或关闭	configuration.settings.GenerativeActionsEnabled
身份验证	authenticationMode（None、Integrated、Manual）、authenticationTrigger、accessControlPolicy
语言	language
Agent 可由其他 Agent 调用	configuration.isAgentConnectable
分析、电话、语音、网络	configuration.analyticsSettings、isTelephonyEnabled、botSpeechSettings、networkSettings

cs_update_settings 会拒绝更改 authoringModel、recognizer.kind 和 template，因为工具依赖这些字段。cs_lookup_schema 会显示架构允许的其他字段，cs_validate 会检查你手动写入的内容。

需要注意的是：这些字段名来自创作架构，而不是通过实时 Agent 往返获取的，因此门户控件与字段之间的映射是推断得出的。如需确认，可在门户中设置一项，然后运行 cs_clone_agent 并进行比较。

身份验证和应用注册

此服务使用 MSAL 公共客户端（交互式浏览器或设备代码）为用户登录。它从不使用客户端密钥，因此所需的每项权限都是以已登录用户身份运行的委托权限。下文仅列出 Microsoft 提供的应用程序权限，供基于相同 API 构建无头流水线的人员参考。有关 cs_login 在 MCP 客户端中的行为，请参阅首次会话。

你需要注册自己的应用吗？

情况	是否需要注册应用？
pac 命令（cs_create_agent、cs_clone_agent、cs_pull、cs_push、cs_pack、通过 pac 使用的 cs_publish、full 模式下的 cs_check_drift、所有 cs_*_solution 工具，以及所有 pac 包装器）	否。pac auth create 使用 Microsoft 自己的第一方应用登录。
使用默认客户端 ID 的云工具（cs_list_environments、通过 Dataverse 使用的 cs_list_agents、通过 Dataverse 使用的 cs_publish、cs_check_drift、评估、用于无身份验证或手动身份验证 Agent 的 cs_chat）	否。该服务使用第一方 VS Code 客户端 ID 51f81489-12ee-4a9e-aaae-a2591f45987d，此 ID 已获授权访问 Power Platform API、Dataverse 和 Power Apps 服务。Microsoft 自己的 Copilot Studio 工具也使用同一 ID。
相同的工具，但你的租户阻止了该 ID（应用同意策略、条件访问、“需要用户分配”）	是。创建下方所述的注册，并设置 CPS_CLIENT_ID。
使用了 集成身份验证（Entra SSO） 的 Agent 的 cs_chat	始终需要。第一方 ID 不包含面向第三方的 CopilotStudio.Copilots.Invoke 权限。将 clientId 传递给 cs_chat，或设置 CPS_CLIENT_ID。
无头 CI（服务主体，无用户）	此服务目前不支持（仅限公共客户端）。对于管道，请将 pac auth create --applicationId ... --clientSecret ... 与 Dataverse 应用程序用户配合使用，或使用分配了 RBAC 角色的服务主体访问 Power Platform API。

你自己的应用注册所需的权限（Entra ID > 应用注册 > API 权限 >“我的组织使用的 API”）：

使用者	在 Entra 中选择的 API	权限	委托式还是应用程序权限	备注
cs_chat（传输方式为 sdk，Entra SSO Agent）	Power Platform API（应用 ID 8578e004-a5c6-46e7-913e-12f58912df43）	CopilotStudio.Copilots.Invoke	此服务使用委托式权限。机密客户端（Microsoft 365 Agents SDK）有同名的应用程序权限；此处不使用。	通常需要管理员同意。重定向 URI 为 http://localhost（移动和桌面应用程序）。
cs_list_test_sets、cs_run_evaluation、cs_get_evaluation_run、cs_list_evaluation_runs、cs_download_evaluation_snapshot	Power Platform API	令牌范围 https://api.powerplatform.com/.default。评估终结点仅声明 .default；权限参考中没有更细粒度的评估权限。	仅限委托式权限。Power Platform API 没有应用程序权限；服务主体通过 RBAC 角色获得访问权限。	已使用 Microsoft 自有工具和第一方 ID 验证。尚未使用自定义注册进行验证；如果调用返回 403，登录用户需要拥有该 Agent 的创建者访问权限。
cs_list_environments、自动查找 Dataverse URL、cs_list_connectors、cs_describe_connector、cs_bind_flow_connection 中的连接查找	PowerApps Service（应用 ID 475226c6-020e-4fb2-8a90-7a972cbfc1d4）	User（“访问 Power Apps Service API”）	委托式。	调用 BAP 环境 API（api.bap.microsoft.com）、连接器注册表和连接列表（api.powerapps.com）。列出连接会显示登录用户在该环境中可见的所有连接，包括其他人的连接；绑定连接后，流程将以该连接所有者的身份运行。
cs_list_agents（通过 dataverse）、cs_publish（通过 dataverse）、cs_create_agent 提供为可选项的发布者和解决方案查找、cs_chat 中的身份验证模式检测、cs_check_drift（快速模式）、cs_push 中的偏移预检、cs_clone_agent / cs_pull / cs_push 记录的组件标记、流程工具（cs_list_flows、cs_get_flow、cs_create_flow、cs_update_flow、cs_set_flow_state、cs_delete_flow 和 cs_bind_flow_connection 中的 Dataverse 部分）以及对话记录工具（cs_list_transcripts、cs_get_transcript、cs_summarize_transcripts、cs_test_set_from_transcripts）	Dynamics CRM（Dataverse，应用 ID 00000007-0000-0000-c000-000000000000）	user_impersonation	委托式。没有应用程序权限；服务器到服务器访问 Dataverse 意味着每个环境都需要具有安全角色的应用程序用户。	用户仍需要一个能够读取和发布 Bot 的 Dataverse 安全角色（System Customizer 或 Copilot Studio 创建者角色）。偏移检查只读取 bot 和 botcomponent 表，所有创建者角色都可以读取；它们绝不会写入 Dataverse。cs_create_agent 读取 publishers（以及具名解决方案的发布者），只是为了提供实际前缀而非猜测；如果读取失败，只会导致无法提供这些选项，不影响工具本身。对话记录工具会读取 conversationtranscript，其中保存着用户实际对 Agent 说的话：该表比其他表更敏感，因此登录用户需要具有允许读取此表的角色，且结果应视为客户数据。如果工作区的同步元数据中没有 Dataverse URL，则会通过上方的 PowerApps Service 权限查找该 URL。
cs_list_flow_runs、cs_get_flow_run、cs_run_flow、cs_explain_flow_run、cs_compare_flow_runs、cs_analyze_flow_health	Microsoft Flow（Power Automate 服务，应用 ID 7df0a125-d3be-4c96-aa54-591f83ff541c）	User（令牌范围 https://service.flow.microsoft.com/.default，可使用 CPS_FLOW_SCOPE 覆盖）	委托式。	这是一个不同于 Dataverse 和 Power Platform API 的独立资源，因此需要单独同意：使用 cs_login scope='flow' 登录。登录用户必须是该流程的所有者或共同所有者。终结点和范围取自 Power Automate 门户调用的服务，尚未在租户环境中验证。诊断工具还会跟随服务为操作的输入和输出返回的 SAS 签名内容链接；获取这些内容时不会携带 Bearer 令牌，因为链接有自己的签名，且几天后会过期。
cs_list_org_agents、cs_get_org_agent	Microsoft Graph（应用 ID 00000003-0000-0000-c000-000000000000）	CopilotPackages.Read.All（可使用 CPS_GRAPH_SCOPE 覆盖范围）	此服务使用委托式权限；读取操作有同名的应用程序权限。	Microsoft 365 Agent 目录，又是一个不同的资源：使用 cs_login scope='graph' 登录。需要 Microsoft Agent 365 许可证，且仅限全球云（不支持 GCC、DoD 或 21Vianet）。读取 /v1.0/copilot/admin/catalog/packages。尚未在实际租户中验证。
cs_block_org_agent、cs_reassign_org_agent	Microsoft Graph	CopilotPackages.ReadWrite.All（可使用 CPS_GRAPH_WRITE_SCOPE 覆盖）	仅限委托式权限。Microsoft 对这两个操作不提供应用程序权限。	许可证和云环境限制同上；使用 cs_login scope='graph_write' 登录。这些操作仅存在于 /beta，因此无论读取操作使用哪个版本，它们都固定使用该版本。屏蔽操作在整个租户范围内生效，并会立即影响所有用户。尚未在实际租户中验证。
cs_get_connector_consent_bypass、cs_set_connector_consent_bypass、cs_download_channel_manifest	Power Platform API	令牌范围 https://api.powerplatform.com/.default；参考文档未声明更细粒度的权限。	仅限委托式权限。	与评估操作使用相同的资源。同意绕过是 Agent 上的管理员设置，因此写入（以及可能的读取）需要 Power Platform 或 Copilot Studio 管理员角色；下载清单需要创建者访问权限，并且 Agent 已发布到 Microsoft 365 / Teams 通道。这三个操作均遵循已发布的参考文档，尚未在实际租户中验证。
cs_chat，用于无身份验证或手动身份验证的 Agent（DirectLine）	无	无	不适用	已发布 Agent 的 DirectLine 令牌终结点无需身份验证。
pac 交互式登录	无	无	不适用	Microsoft 自有应用；pac auth create --environment <id>。
自行注册的步骤：

1. Entra ID > 应用注册 > 新注册。选择单租户。在 身份验证 下添加平台 移动和桌面应用程序，并将重定向 URI 设为 http://localhost（MSAL 在 cs_login 交互式登录时使用的环回地址）。如果计划在 cs_login 中使用 mode: device_code，请将 允许公共客户端流 设为“是”。
2. 添加表格中的权限。如果按名称或上述 ID 搜索时没有出现 Power Platform API，说明你的租户中缺少其服务主体；请使用 az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43（或 New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43）创建该主体，然后再次搜索。
3. 为租户 授予管理员同意，或让每位用户在首次登录时进行交互式同意。
4. 将 ID 写入 MCP 服务环境变量：CPS_CLIENT_ID=<application (client) id> 和 CPS_TENANT_ID=<directory (tenant) id>。cs_chat 也接受每次调用传入的 clientId。

配置

所有环境变量均为可选：

变量	作用
CPS_WORKSPACE	要启动时进入的 Agent 工作区（VS Code：${workspaceFolder}）；否则，服务会在当前目录、一个子目录或某个祖先目录中查找标记文件
CPS_TENANT_ID、CPS_CLIENT_ID	cs_login 使用的 Entra 租户和应用注册；默认租户为 organizations，默认客户端为第一方 VS Code ID
CPS_ENVIRONMENT_ID、CPS_ENVIRONMENT_URL、CPS_AGENT_ID	当工作区未携带同步元数据时，云端工具使用的默认值；优先使用显式参数，其次是工作区元数据，再其次是这些变量，最后进行 BAP 查找
CPS_PAC_PROFILE、CPS_ADMIN_PROFILE	用于创建者命令和管理命令的 pac 身份验证配置文件（两个账户）
CPS_READ_ONLY	禁用所有会更改环境的工具（更改前审批）
CPS_TOOLS、CPS_TOOLS_EXCLUDE	精简工具列表：预设值和以逗号分隔、支持 * 通配符的名称（见下文）
CPS_FLOW_SCOPE、CPS_GRAPH_SCOPE、CPS_GRAPH_WRITE_SCOPE	覆盖 Power Automate 服务和 Microsoft Graph 的令牌范围
CPS_CACHE_DIR、PAC_PATH、DOTNET_ROOT	令牌缓存位置、pac 可执行文件、.NET 根目录

在较小模型上运行

完整工具列表包含 148 个工具，在开始任何工作前就约有 50k tokens 的架构定义。前沿模型可以应对；较小的模型则会把大部分上下文花在菜单上，并且更难从中做出选择。可在服务的环境中将 CPS_TOOLS 设为某个预设，也可以让用户在会话期间选择：cs_init 会返回一个 toolPresets 区块，其中包含问题、选项表和每个预设的实时计数，而 cs_set_tool_preset 会应用选择。

预设	工具数	使用场景
full（默认）	148	所有工具；适合大模型，或尚不清楚任务需要什么的情况
core	34	构建或修改一个 Agent 并使其上线：通常首选
authoring	25	仅编写和检查文件；无需登录，也不会触及任何环境
admin	49	以管理员帐户管理租户，并包含 cs_backup_tenant
solutions	25	拉取、部署和比较解决方案，并绑定导入后仍处于关闭状态的流程

不会移除任何工具：预设只会更改提供哪些工具；cs_init、cs_guide、cs_set_tool_preset 和 cs_job_status 在所有预设下都会保留，因此会话随时可以改变选择。cs_pac 包含在 core、admin 和 solutions 中，因此即使某个预设隐藏了某条 pac 命令，仍然可以使用它；而且 cs_init 会说明缺少的工具是被隐藏了，而非不存在。预设可以彼此组合，也可以与 glob 模式组合：CPS_TOOLS=core,cs_admin_*，或 CPS_TOOLS_EXCLUDE=cs_*_pipeline,cs_env_*,cs_*_auth_profile。切换时，SDK 会发送 notifications/tools/list_changed，因此支持该通知的客户端会立即看到更短的列表；缓存列表的客户端则需要重启。运行时切换只能缩小启动时注册的工具范围，因此如果希望可以选择所有预设，请不要设置 CPS_TOOLS。

检查模型是否选对了工具

这么长的工具列表会带来路由问题：描述会决定“昨晚我的流程为什么失败了？”会被路由到 cs_explain_flow_run，还是其他回答不同问题的工具。该软件包附带了检查工具，因此你可以用自己的预设、自己的模型和自己的表述来衡量，而不必盲信这里的数字：

npx copilot-studio-mcp-routing-eval --dry-run                       # free: shows the corpus and the cost
npx copilot-studio-mcp-routing-eval --preset core --repeat 3 --yes
npx copilot-studio-mcp-routing-eval --cases ./my-questions.json --yes

它会按照客户端所见的方式，将工具列表逐条呈现给模型，并对第一个被命名的工具评分。--cases 可以指定你自己的文件，其格式与随附的 reference/routing-cases.json 相同，这正是关键所在：用户实际提出的问题比这里随附的问题更有参考价值。设置 ANTHROPIC_API_KEY 后，它会调用 Messages API，并将工具列表作为缓存前缀；每次运行只需花费几美分。若未设置，则会回退到 claude CLI，并使用该机器已有的登录信息。无论哪种方式，每次运行都会针对每个案例调用一次模型并产生实际费用，因此除非使用 --yes，否则不会执行任何操作。

请使用 --repeat 3 进行评估，绝不要只运行一次。 在 Haiku 4.5 上的测量结果显示，相同构建的不同运行之间，得分会相差两个案例；而且三分之一的案例每次都会给出不同答案。单次运行很容易让你误以为某项改动有所帮助，实际上并非如此。报告会区分始终路由错误的案例（值得采取措施）和结果反复变化的案例（无法证明任何结论）。

握手说明是为较小模型编写的：每行一条规则，每条指令前都有明确的触发条件，并设有一个章节列出首次实际运行中发现的问题（调用在客户端约 60 秒的限制处被截断、服务器二进制文件过时导致工具缺失、云工具因未登录而失败、pac 报告失败但退出码为 0），以及每种问题的对应处理方法。

可以和不可以实现的功能

能力	方式	状态
将 Agent 保存为文件并双向同步	pac copilot init / clone / pull / push / pack / publish	官方，正式发布
将主题、知识、工具、触发器和流程保存为 YAML	使用 VS Code 扩展的工作区布局和 pac copilot push	官方
本地验证	使用 microsoft/skills-for-copilot-studio（MIT）中的 JSON schema + 结构检查	此服务
运行评估并读取结果	Power Platform API makerevaluation 端点	官方，正式发布，标准测试框架
与已发布的 Agent 聊天	DirectLine v3（无身份验证 / 手动身份验证的 Agent）或 Copilot Studio 客户端 SDK（Entra SSO）	官方
发布	pac copilot publish 或 Dataverse PvaPublish	官方
读取、创建、更改和删除云端流程	Dataverse workflow 行（定义位于 clientdata）	官方 API，实时数据结构尚未验证
绑定流程的连接	clientdata 连接引用，或通过解决方案导入的流程所对应的 connectionreference 行	官方 API，实时数据结构尚未验证
流程运行历史记录、启动一次运行	Power Automate Process Simple API	门户调用的服务，尚未实时验证
解释失败的运行、与成功的运行进行比较、评估流程的可靠性	同一 API 的逐次运行操作路由，以及它返回的 SAS 签名内容链接	此服务，尚未实时验证
上次同步后门户中的变更	将 bot 和 botcomponent 行与本地同步标记进行比较	此服务
将租户配置保存为文件	使用 pac admin 读取命令将配置写入文件夹	此服务

此服务会设法绕过以下硬性限制，而不是将其隐藏：

1. 无法通过 API 创建评估测试集。 cs_create_test_set_csv 会写入门户导入的 CSV（最多 100 个用例）；导入一次后，运行和结果均可自动处理。
2. 连接器、MCP 和提示词工具需要由门户授权的连接。 cs_add_tool 会写入 YAML 和连接引用存根，并返回门户操作步骤。 唯一例外是服务主体 Dataverse 连接，可通过 cs_create_connection 创建。出于同样的限制，新建的云端流程会默认为关闭状态：先绑定其 连接，再调用 cs_set_flow_state。
3. 评估和主题 YAML 是标准测试框架功能。 GitHub Copilot 测试框架的 Agent （--authoring-mode cli-copilot）仅支持 init / pack / import / instructions / chat。
4. Copilot Studio 不会报告对话是否成功。 对话记录工具会根据活动推断结果。请将比率视为排查线索，并在采取行动前阅读对话记录。
5. 从未连接到环境的工作区打包内容较少。 已在 pac 2.11.2 中验证：在未使用 --environment 的情况下通过 pac copilot init 创建工作区后，运行 pac copilot pack 只会打包 settings、Agent 和主题，并会拒绝 knowledge/、actions/、tools/、 trigger/、variables/、workflows/ 和 connectionreferences.mcs.yml。这些文件夹需在已连接同步的工作区（通过 clone 创建，或通过 init 并指定环境创建）中使用 pac copilot push 处理。创作工具会在你处于仅支持打包的工作区时发出提示。

它与 Microsoft 自有的 pac MCP 服务有何不同

Power Platform CLI 内置了一个 MCP 服务（pac copilot mcp --run，预览版，名为 “Power Platform Management MCP Server”）。它是 pac 本身的自然语言前端：其中每个 工具都会运行一条 pac 命令。在 pac 2.11.2 上探测到它提供 70 个工具，其中恰好只有一个 与 Copilot Studio 有关（copilot_publish）；51 个工具用于租户管理、托管标识、 模型驱动应用和生成的页面、Power Pages、代码应用及代码生成。

	pac MCP server（pac copilot mcp）	copilot-studio-mcp（本仓库）
用途	通过自然语言运行 pac 命令；管理租户和环境	在编辑器中构建、测试、发布和维护 Copilot Studio Agent
Copilot Studio 命令	仅 copilot_publish	init、clone、pull、push、pack、publish、status、list、delete、模板、翻译、隔离、AI Builder 指令
创作	无	以 YAML 编写主题、知识源、工具（连接器／MCP／流／提示词／Agent）、触发器、变量和 Agent 自身设置；支持次日编辑和移除；架构验证（744 个定义）；基于规则的审查并提供评分
测试	无	评估测试集和运行（Power Platform API）、通过 DirectLine 或客户端 SDK 进行聊天、本地对话测试、生产转录记录
ALM	解决方案列表、导出、导入、检查	使用部署设置文件拉取整个解决方案并按原样重新部署；Solution Checker、版本控制、分阶段升级、管道、DTAP 快照和比较
漂移	无	自上次同步以来门户中的更改（快速 Dataverse 检查、完整克隆差异），以及遇到冲突时会阻止操作的推送预检
安全性	服务中没有试运行模式；唯一的关卡是客户端的审批提示	每个会更改环境的工具都会先返回试运行结果，直到设置 confirm: true；日志和结果中的机密会被遮蔽；CPS_READ_ONLY 会完全隐藏写入工具
租户管理	将管理命令作为原生工具提供	管理命令，以及 cs_backup_tenant 和名册引导流程，使用单独的管理员身份验证配置运行
云流	除原始 pac 外无其他功能	列出、读取、创建、重建、启用或关闭、查看运行历史记录，以及基于步骤的定义构建器
指引	工具描述	握手过程中的使用说明、cs_guide 操作指南、MCP 提示词、每个工作区的后续步骤，以及提供实际选项而非参数错误的问题
其他 pac 组	将 managed-identity、model、pages、code、modelbuilder 作为原生工具提供	可通过 cs_pac 访问（只读命令会立即运行，其他命令需要 confirm）
登录	pac auth 配置文件	pac auth 配置文件，另加 MSAL，用于 pac 未涵盖的 API（评估、Dataverse 读取、环境、聊天）
工具列表	固定	可通过预设和 CPS_TOOLS／CPS_TOOLS_EXCLUDE 按客户端进行精简

两者都是 stdio 服务，可以并排注册：pac 的服务用于租户管理，本服务用于 Agent 工作。需要 注意的一点是：pac 的服务在启动时会向 stdout 输出一行非 JSON 内容，严格的 MCP 客户端可能会拒绝它。

来源：Use Power Platform CLI with built-in MCP server 以及对 pac 2.11.2 的 tools/list 探测（2026-09-07）。

它们如何协同工作

flowchart LR
    VS["VS Code / GitHub Copilot"] --> TOOLS
    CC["Claude Code"] --> TOOLS
    subgraph SERVER["copilot-studio-mcp"]
        TOOLS["MCP tool call"] --> SYNC["Sync layer: pac copilot, pac solution, pac admin"]
        TOOLS --> AUTH["Authoring layer: YAML + schema validation, flow builder"]
        TOOLS --> CLOUD["Cloud layer: evaluations, publish, chat, flows, drift"]
    end
    AUTH --> WS["Agent workspace on disk: topics, knowledge, actions, workflows"]
    SYNC --> WS
    SYNC --> DV["Dataverse / Copilot Studio"]
    SYNC --> BACKUP["Tenant backup and solution folders on disk"]
    CLOUD --> PPAPI["Power Platform API"]
    CLOUD --> DV
    CLOUD --> FLOW["Power Automate service: flow runs"]
    CLOUD --> DL["Published agent: DirectLine or SDK"]

使用真实租户进行验证

云端工作流基于文档和已发布的架构构建；阶段 A 至 F 于 2026-09-08 首次进行了线上验证。docs/verify.md 是当前的后续事项清单。 docs/live-verification.md 是完整的运行手册：阶段 A 至 D 仅执行读取操作，无需触碰租户即可解决大部分未决问题；阶段 E 至 G 会执行写入操作，并会明确说明。docs/verification-template.md 是需要填写的结果文件，scripts/redact-verification.mjs 会将 GUID、组织 URL、电子邮件地址和令牌替换为稳定的假名，以便在公共仓库中分享结果。 docs/STATUS.md 是完整的历史记录。docs/test-verification.md 是反馈闭环的运行手册（静态检查、行为测试、对话记录、完成闭环）；其阶段 1 用于确认实时活动是否包含对话测试读取的主题、工具和引用归属信息。

开发

git clone https://github.com/jgt87/copilot-studio-mcp.git
cd copilot-studio-mcp
npm install
npm run build                 # dist/index.js is the server: register it as "command": "node", "args": ["<repo>/dist/index.js"]
npm test                      # build + unit tests (fixtures, no network)
node scripts/smoke.mjs        # drive the built server over stdio
node scripts/oracle-pack.mjs  # pac copilot init + authoring tools + pac copilot pack

reference/bot.schema.yaml-authoring.json 和 reference/templates 来自 microsoft/skills-for-copilot-studio（MIT 许可，参见 reference/LICENSE.skills-for-copilot-studio.txt）。 test/fixtures/pac-* 下的测试夹具由 pac copilot init 生成。

采用 MIT 许可。