add-mcscopilot

📋 共享说明：shared-instructions.md - 跨领域注意事项。

添加 Microsoft Copilot Studio

工作流

1. 检查 Memory Bank → 2. 添加连接器 → 3. 配置 → 4. 构建 → 5. 更新 Memory Bank

---

第 1 步：检查 Memory Bank

按照 shared-instructions.md 检查是否存在 memory-bank.md。

第 2 步：添加连接器

首先，查找连接 ID（参见 connector-reference.md）：

运行 /list-connections 技能。在输出中查找 Microsoft Copilot Studio 连接。如果不存在，请引导用户使用特定环境的 Connections URL 创建连接——根据上下文中的活动环境 ID（来自 power.config.json 或之前的步骤）构建该 URL：https://make.powerapps.com/environments/<environment-id>/connections → + 新建连接 → 搜索连接器 → 创建。

pa app add data-source --connector microsoftcopilotstudio -c <connection-id>

第 3 步：配置

询问用户要调用哪个 Copilot Studio Agent，以及需要哪些操作。

Agent 设置前提条件（用户必须在 Copilot Studio 中手动完成的步骤）：

1. 发布 Agent：在 Copilot Studio 中，点击 Channels → 选择 Teams → 添加到 Teams → 点击 Publish。
2. 获取 Agent 名称：在 Channels 下，点击“Web app”。连接字符串 URL 中包含 Agent 名称。示例：https://...api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/cr3e1_myAgent/conversations?...——Agent 名称为 cr3e1_myAgent。

ExecuteCopilotAsyncV2 -- 执行 Agent 并等待响应：

使用 ExecuteCopilotAsyncV2 操作（路径：/proactivecopilot/executeAsyncV2）。这是唯一能可靠地同步返回 Agent 响应的端点。它与 Power Automate 的“执行 Agent 并等待”操作使用的是同一个端点。

const result = await MicrosoftCopilotStudioService.ExecuteCopilotAsyncV2({
  message: "Your prompt or data here", // Can be a JSON string
  notificationUrl: "https://notificationurlplaceholder" // Required by API but unused; any URL works
});

// Response structure:
// result.responses — Array of response strings from the agent
// result.conversationId — The conversation ID
// result.lastResponse — The last response from the agent
// result.completed — Boolean indicating if the agent finished

**重要：**Agent 通常会以 JSON 字符串的形式返回响应。解析 responses 数组以提取有用数据：

const agentResponse = result.responses?.[0];
if (agentResponse) {
  const parsed = JSON.parse(agentResponse);
  // Extract specific fields, e.g., parsed.trend_summary
}

使用 Grep 在生成的服务文件中查找特定方法（生成的文件可能非常大——参见 connector-reference.md）。

已知问题

• ExecuteCopilot（/execute）——仅触发执行，不等待结果，只返回 ConversationId，不返回实际响应。请勿使用。
• ExecuteCopilotAsync（/executeAsync）——会返回 502“Cannot read server response”错误。请勿使用。
• 对话轮次模型（/conversations/{ConversationId}）——只有在 /execute 之后才能使用，而该操作不会提供响应。请勿使用。
• 响应字段大小写不一致——检查所有变体：conversationId、ConversationId、conversationID。

第 4 步：构建

npm run build

继续之前，请修复 TypeScript 错误。暂时不要部署。

第 5 步：更新 Memory Bank

在 memory-bank.md 中更新：已添加的连接器、已配置的 Agent 名称、已配置的操作、构建状态。