service-itsm-teams-coordinate

ITSM 版 Microsoft Teams — 端到端设置自动化

通过一个连续流程完成 Microsoft Teams 员工服务（ITSM） 的全部设置。 将每个阶段委派给相应的专用子技能，但由你负责掌控 顺序，并在 不中途征求许可 的情况下完成所有阶段。仅在确实需要人工操作时暂停，其他情况一律不停。

目标

引导用户从零开始，在一次操作流程中完成可用的 Teams ITSM 集成（IT Desk + IT Service、Swarming，以及——如果用户需要——嵌入式 Agentforce Agent）。子技能负责提供经过验证的 API 详情；本技能负责统筹并按顺序运行这些技能，管理交接。

核心操作规则——持续运行，仅在必要时暂停

除非用户必须提供信息或执行平台外操作，否则全程执行，不得中途暂停。 不要在各阶段之间重新展示选项菜单，不要在每个阶段结束后询问“要继续吗？”，也不要让用户点击本技能的子技能可通过 API 操作的 Setup 开关。直接进入下一阶段，并在过程中报告进度。

整个流程恰好有 三处必须暂停 和 一个分支：

• 暂停 1 — Azure/Entra 应用（阶段 2）：向用户提供应用注册说明，并 等待 用户注册应用并提供凭据。Salesforce API 无法完成此操作。Client ID 和 Tenant ID 是非机密标识符，可以在聊天中提供；Client Secret 是机密凭据——绝不可在对话中索要。 Agent 应向用户提供一条精确的复制粘贴命令，将密钥写入被 gitignore 忽略的密钥文件（! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written），并从该文件读取。保留开头的 !——它会在当前会话的 Bash 中运行该命令，以便文件持久保存。Agent 绝不会打印、回显或记录该值。
• 暂停 2 — 安装 IT Desk 应用（阶段 3）：提供 Microsoft Marketplace 链接，并 等待 用户回复 “installed”。没有 API 可以将 Teams 应用安装到租户目录中。
• 暂停 3 — 安装 IT Service 应用（阶段 4）：与暂停 2 相同，适用于 IT Service 应用。
• 分支 — IT Service Agentforce Agent（阶段 7）：IT Desk Agent 会自动运行，但 IT Service 嵌入式 Agent 尚待处理；询问用户是否要执行此操作，只有在用户回答是时才运行阶段 8。

如果用户在暂停点没有回应，就停止并等待——不要编造值，也不要跳过后续步骤。其他所有阶段转换均自动进行。

每个阶段内，一次只执行一项操作。 子技能会调用真实的、会改变状态的 API；执行一项操作，确认成功后再继续——绝不要将多个会改变状态的调用批量放入同一个并行区块。“不中途暂停”指的是阶段之间没有 许可关卡，并不意味着并行执行写入操作。

流程（按顺序运行）

阶段 1 — 启用 Teams for Employee Service Go 功能

仅调用 service-itsm-teams-configure 执行功能启用部分（其步骤 1–3）：启用 service-cloud-itsm-teams-integration，并确认 ITSMTeamsEnabled 的值为 true。报告进度，然后直接继续阶段 2——此处 不要 停止。

阶段 2 — Microsoft Entra 应用 + Named Credentials ⟶ HALT 1

仍在 service-itsm-teams-configure（其步骤 4a）中：向用户提供准确的 Azure/Entra 应用注册操作步骤，包括其中列出的 Microsoft Graph 权限，并在用户提供凭据前暂停。Client ID 和 Tenant ID 是非机密标识符，可在聊天中接收。**Client Secret 属于机密：绝不要在对话中索要。**向用户提供一条准确的复制粘贴命令，将其写入已加入 gitignore 的机密文件 （! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written），并从该文件读取。保留开头的 ! — 它会在此会话的 Bash 中运行该命令，使文件得以持久保存。绝不要打印或回显该值。标识符一经提供且机密已写入文件，就立即：

• 自行通过 API将这些值写入 MSTeamsSetupClientCredentialsEC Named Credential 和 microsoft_auth_provider Auth Provider — 不要进行任何手动操作（子技能的步骤 5 及其 azure-credential-population 参考中包含准确的 API 请求体）。在调用时从文件读取机密 — 不要将原始值内联到任何日志文本中。
• 向用户提供静态的 Grant Admin Consent 链接，并注册首选站点（子步骤 5）。 然后自动继续阶段 3。

阶段 3 — 设置 IT Desk（服务人员端） ⟶ HALT 2

调用 service-itsm-teams-itdesk-configure。完整执行其检查清单：

• （通过 API）启用 OrgHasITSMFulfillerTeams 组织偏好设置。
• 管理用户访问权限 — 为已确认的用户分配服务人员权限集： TeamsForITSrvcsUser + MicrosoftGraphAccess，以及 API Enabled 登录权限集 （通常为 Teams_Employee_ApiAccess）— 登录必需，不可省略。
• 启用 Swarming — 此阶段包含 service-itsm-swarming-configure （启用 service-cloud-swarming 并设置 SWARM_COLLABORATION_TOOL = "Teams"）。
• 向用户提供 IT Desk Microsoft Marketplace 链接 + 帮助文档，并说明用户的 Azure 账户电子邮件必须与 Salesforce 用户的电子邮件/Username 匹配（SSO 会将 MS UPN 解析为 Username），然后在用户回复 "installed." 前暂停。随后继续阶段 4。

阶段 4 — 设置 IT Service（员工端） ⟶ HALT 3

调用 service-itsm-teams-itservice-configure。完整执行其检查清单：

• （通过 API）启用 OrgHasEmployeeServiceTeams 组织偏好设置。
• 管理用户访问权限 — 为已确认的 UEL 用户分配员工权限集： TeamsForEmployeeUser（对话框只会分配此权限集 — 不包括 MicrosoftGraphAccess），以及子技能的登录前提要求中的 API Enabled 登录权限集。
• （通过 API）选择 Digital Experience Site（SLACK_PREFERRED_SITE）。
• 向用户提供 IT Service Microsoft Marketplace 链接 + 帮助文档，再次说明电子邮件必须匹配，并在用户回复 "installed." 前暂停。随后继续阶段 5。

阶段 5 — 请用户验证登录

请用户在 Teams 中打开 IT Desk 应用，使用服务人员凭据登录；再打开 IT Service 应用，使用 UEL/员工凭据登录，并确认两者均能正常加载。如果任一登录失败，则在继续之前转至 service-itsm-teams-debug 执行登录通过/失败诊断。

阶段 6 — 告知用户 IT Desk 的 “Ask Agentforce” Agent 会自动运行

确认 IT Desk 登录成功后，告知用户 IT Desk 的 Ask Agentforce 会自动运行 — 服务人员端无需进一步设置。

阶段 7 — 提供 IT Service Agentforce Agent 选项 ⟶ 分支

告知用户 IT Service 端仍有待完成的工作：嵌入式 Agentforce Agent（“Ask AI Agent”）在构建其消息通道 + Key Set + Embedded Service Deployment 前不会回复。 询问用户是否要现在设置（使用 AskUserQuestion）。如果用户回答否，则进入完成摘要。如果用户回答是，则执行阶段 8。

阶段 8 — 构建 IT Service 嵌入式 Agent（仅当用户回答“是”时）

调用 service-itsm-teams-employee-agent-configure。它会完全通过 API 构建 Web 消息渠道（启用 用户验证 + JWKS_URL 密钥集）、Teams_AgentForce 嵌入式服务部署（发布）、路由流，以及门户用户的 Agent 访问权限集。然后告知用户，请从全新的 Teams 聊天中重新测试，确认 Agent 是否回复。

每个阶段结束后

• 报告子技能的实际判定结果，绝不要假定为“已完成”。 只有子技能明确报告成功，阶段才算完成。如果子技能报告受阻（最常见的情况是阶段 2 中 Entra 应用尚未注册，或因等待“已安装”而暂停），则将该阶段保持为 Blocked/等待中，并停在暂停点；不要标记为已完成，也不要跳过该阶段。
• 不要重新提供菜单。说明刚刚完成了什么、接下来要做什么，然后继续执行。
• 报告要简洁——总结，不要照录。 在阶段进度表中为每个阶段提供一行状态，另外最多补充一句简短说明；不要粘贴子技能的 API 请求/响应正文、工具调用日志或逐步内部操作——这些细节由子技能负责记录，在此重述是报告冗长、信息量低的最大原因。读者需要知道发生了什么以及接下来要做什么，而不是重放每一次调用。

完成摘要

流程结束时（阶段 7 回答“否”、阶段 8 完成，或用户选择不解决的硬性阻塞），总结每个阶段的实际状态。标题规则：所有阶段均已完成 → Complete；任何阶段仍处于受阻/等待状态 → Incomplete (action required)，并注明确切的后续步骤；否则 → Finished。

规则

• 设置标题中始终显示“(via service-itsm-teams-coordinate)”。
• 连续运行各阶段；只有 HALT 1–3 和阶段 7 分支可以暂停等待用户交互。
• 如果子技能可以通过 API 切换 Setup 选项，绝不要要求用户手动点击（功能启用、组织偏好设置、权限集分配、数字站点、命名凭据）。
• 绝不要捏造暂停点所需的值（Azure 凭据、“已安装”）或子技能的成功结果；必须等待实际回复。
• 将每个阶段委派给对应的子技能；不要在此处内联重写子技能的 API 逻辑。
• 在整个对话中跟踪进度——不要重新运行已完成的阶段。
• 任何输出中都不要显示 Salesforce 记录 ID——只显示便于阅读的名称。
• 在阶段 3 和 4，始终附上 Azure 邮箱必须与 Salesforce 邮箱一致的说明及 marketplace 链接，因为不匹配是常见的静默登录失败原因。

验证清单

发送任何进度消息或摘要之前，请确认：

• 标题行以 (via service-itsm-teams-coordinate) 结尾。
• 流程连续运行——除三个指定的暂停点和阶段 7 分支外，阶段之间没有添加权限关卡。
• 每个阶段的状态均反映子技能的实际判定结果（In progress、Blocked/等待中或 Done）——不是硬编码的默认值。
• 等待暂停点（Azure 凭据、“已安装”）的阶段显示为等待中，绝不能显示为 Done。
• 阶段 3 和 4 均提供了 marketplace 链接以及邮箱必须匹配的说明。
• 阶段 7 分支以是/否问题的形式提出，且只有在用户明确回答“是”时才运行阶段 8。
• 下一步操作委派给子技能；绝不在此处内联配置功能。
• 输出中没有 Salesforce 记录 ID——只显示便于阅读的名称。

参考文件索引

文件	何时阅读
examples/output-templates.md	进度和完成摘要文本块