service-itsm-teams-debug

排查 Microsoft Teams for Employee Service（ITSM）问题

当有人报告 Microsoft Teams for Employee Service 出现故障时——无法登录、选项卡无法加载、功能未显示、Agentforce Agent 没有回复、群组协作或 SSO 出现问题——此技能会连接到组织，针对具体问题运行通过/失败检查清单，并报告每项设置的实际值，以及修正错误设置的确切 Setup 路径。它用有针对性的验证诊断，取代“手动检查每项设置”。

所有读取操作都通过 headless-360 分派（查询使用 dispatch_readonly，仅在可选的群组协作令牌清除操作中使用 dispatch）。无需组织密码。

范围

• **包含：**诊断已尝试配置、但运行失败的 Teams ITSM。根据报告的问题匹配相应检查清单，并检查所需的确切设置（CORS、External Client App、功能开关、PSL、配置文件会话设置、身份验证提供程序、命名凭据、消息传递渠道、Agentforce Agent）。
• **不包含：**首次启用（使用 service-itsm-teams-configure / -itservice-configure / -itdesk-configure）、从头构建嵌入式 Agent（使用 service-itsm-teams-employee-agent-configure），以及非 Teams 的 Salesforce 调试。

**默认情况下为只读。**每项检查都是 dispatch_readonly 查询——运行完整检查清单不会更改任何内容。唯一会更改状态的操作是在最后执行的可选群组协作 OAuth 令牌清除，且仅在用户明确确认后进行。

---

第 1 步 — 确认问题并收集信息

如果用户尚未提供，请询问其问题描述。使用 references/configuration-checklists.md 中的功能对照表，将问题匹配到相应检查清单。

有些问题需要额外信息——请一开始就询问：

问题类型	需要收集的额外信息
通用“登录”问题（未说明应用）	询问使用哪个应用——IT Desk 还是 IT Service
IT Desk 登录	最终用户的 Salesforce 用户名（无法登录的用户）
IT Service 登录	**CCP 还是 UEL 用户？**然后询问该最终用户的 Salesforce 用户名
Agentforce 没有回复	Employee Experience Site URL
群组协作	最终用户的用户名；Azure AD Tenant ID（可选——用于启用 Azure 应用检查）
SSO	Azure AD Tenant ID（可选）；也可询问使用哪个应用及最终用户的用户名

在获得该检查清单所需的必填信息之前，不要运行 Agent 专属检查（例如，登录问题不得跳过询问最终用户的用户名——缺少该信息时，按用户检查的结果为 MANUAL_CHECK_REQUIRED）。

第 2 步 — 匹配检查清单

从功能对照表中选择检查清单，然后按照 references/configuration-checklists.md 中的顺序运行检查：

症状	检查清单
IT Desk 登录	LOGIN_DESK
IT Service 登录 — UEL 用户	LOGIN_SERVICE_UEL
IT Service 登录 — CCP 用户	LOGIN_SERVICE_CCP
通用登录（应用未知）	LOGIN（然后询问使用哪个应用）
功能未显示 / 未启用	MSTEAMS_CORE
选项卡无法加载（CI Hub、Service Catalog、Employee Enablement、My Assets）	TAB_LOADING
Lightning 应用未嵌入 / 选项卡为空白	LIGHTNING_OUT
Agentforce Agent 没有回复	AGENTFORCE
群组协作	SWARMING
单点登录	SSO（如果已说明应用，还要运行该应用对应的登录检查清单）

如果 SSO 问题中已说明应用，请同时运行 SSO 检查清单和匹配的登录检查清单（LOGIN_DESK / LOGIN_SERVICE_CCP / LOGIN_SERVICE_UEL）——重复的检查只需运行一次。

第 3 步 — 运行检查

通过 dispatch_readonly 执行每项检查的查询（查询和 API 字段详见参考文档）。为每项检查记录：状态和从组织中实际读取的已配置值。

状态	显示为	含义
OK	OK	配置正确
MISCONFIGURED / MISSING / DISABLED / ERROR	FAIL	需要修复 — 包含参考文档中的准确 Setup 路径
MANUAL_CHECK_REQUIRED	MANUAL	需要手动验证（或缺少可选输入，例如 Tenant ID/用户名）— 绝不能显示为 FAIL

第 4 步 — 报告

使用全部四列 — #、Check、Status、Configured Value（绝不能省略已配置值）— 呈现表格，并为任何失败的检查附上包含修复方法的 Action Required 说明。最后用一行摘要：N passed | N failed | N require manual verification。

• **全部通过：**告知用户 Salesforce 后端配置正确；如果问题仍然存在，请重新加载 Teams 应用（点击 IT Desk/IT Service 应用上的 ⋯ → Reload app）。
• **有任何失败：**不要添加重新加载提示 — 每项检查中的 Action Required 步骤就是修复方法。

完整的报告呈现规则、特殊情况说明、报告布局示例，以及可选的清除 Swarming OAuth 令牌步骤，请参阅 references/report-generation.md。

---

注意事项（已验证）

问题	详情
Teams ECA 的 DeveloperName 是 ServiceCloudTeamsEca	登录检查要查找的 External Client App 是 ServiceCloudTeamsEca。（按组织打包的实例可能会显示为相关名称，例如 ServiceCloudMSTeamsEca；请匹配支持 Teams 登录的 ECA，如果缺少该应用，则按“关闭再重新开启该功能”处理。）
“Allow OAuth for employees” 读取时仅限 Metadata API，更改时仅限 Setup UI	通过 SOAP listMetadata(ProfileSessionSetting) → 对包含 unified 的 fullName 执行 readMetadata；字段为 allowOauthForEmployees（true=已启用，false=已禁用，缺失=从未配置）。它不在 Profile describe 中，也无法通过 REST/Tooling 查询。要设置此项，请前往 Setup → Profiles → （员工配置文件） → Session Settings。仅限 UEL 用户。
CORS 检查读取 IsOauthCorsPolicyEnabled，允许的源读取 CorsWhitelistEntry.UrlPattern	必须同时包含 https://cdn.scs.static.lightning.force.com 和 https://teams.cloud.microsoft。
通过 FulfillerApp permissions Connect API 读取功能开关	GET /connect/it-service/permissions/FulfillerApp 会返回组织/用户功能标志；FUNCTIONALITY_NOT_ENABLED 错误表示组织级别的 IServiceItsmTeamsFamily 系列功能已关闭。
Agentforce 用户验证字段需要 SOAP v62+	SOAP v60 会静默省略 MessagingChannel.embeddedConfig（authMode、messagingAuthorizations.*）；请使用 v62+。
必须使用版本前缀	headless-360 dispatch/dispatch_readonly 无法解析 API 版本 — 始终传入完整的 /services/data/vXX.0/... 前缀。

相关技能

技能	何时改用
service-itsm-teams-configure	首次启用基础 Teams Go 页面开关、Azure/Entra 应用、Named Credential 和扩展注册
service-itsm-teams-itservice-configure	完成 IT Service（员工）启用清单
service-itsm-teams-itdesk-configure	完成 IT Desk（服务处理人员）启用清单 + Swarming 协作工具
service-itsm-teams-employee-agent-configure	从头构建嵌入式 Agentforce Agent，使其能在 Teams 中回复
service-itsm-channels-coordinate	Teams、Slack、Swarming、Notifications、Portal 的顶层菜单