service-itsm-incident-mgmt-configure

配置 ITSM 事件管理（主开关）

读取并切换 Salesforce ITSM 组织中的事件管理主开关。这是组织级开关，用于开启或关闭事件管理。启用后，服务器端也会启用其子功能，因此只需对主开关执行一次操作即可完成全面启用。

写入操作具有幂等性（当前状态已与请求状态一致时会跳过），此技能始终会先读取再写入，并且在任何变更之前都必须经过明确的确认后写入检查点。

此技能控制的内容

偏好设置（Setup 界面标签）	是否在范围内
事件管理启用状态（主开关）	是 — 读取并切换
事件默认字段验证、子事件自动关闭、Email-to-Incident 子开关、事件优先级矩阵、问题/变更/案例管理、ITSM External Client App 设置	否

有关主开关读取和写入的准确 URL、数据格式及完整示例，请参阅 references/mcp-invocation.md。

范围

• 范围内：读取并切换事件管理主偏好设置。
• 范围外：事件默认字段验证（IncidentValidationsEnabled）；事件优先级矩阵配置；子事件自动关闭和 Email-to-Incident 子开关；问题管理；变更管理；案例管理；ITSM External Client App 设置；其他 ITSM 偏好设置（IncidentTriageAgentEnabled、IncAssignWithAgentEnabled、AssignedGroupValidationEnabled）；广播频道偏好设置；创建或配置 Incident、Problem 或 ChangeRequest 记录。

---

前置条件

在此技能能够对 headless-360 调用任何内容之前，必须配置目标组织和 MCP 客户端。如果未满足其中任一条件，工具在首次调用时会返回 401、403 或 404；不得捏造状态——应原样呈现错误并停止。

1. 在组织上激活服务器：Setup → MCP Servers → headless-360 → Activate。激活最长可能需要约 2 分钟。
2. 配置 External Client App：组织中需有一个 ECA，包含 OAuth 作用域 mcp_api 和 refresh_token，启用基于 JWT 的访问令牌，并要求 PKCE。ECA 传播最长可能需要 30 分钟。
3. API v67.0+：此技能使用的读取和写入路由需要此版本。
4. MCP 客户端注册：客户端（adk-eval / Claude Code）有一个 additionalServers.headless-360 条目，指向正确的环境 URL（参阅 references/mcp-invocation.md）。

如果任何前置条件未满足，工具会返回以下错误之一：

• 401 Unauthorized → ECA 尚未传播、作用域错误或令牌已过期。
• 403 Forbidden → 用户缺少权限，或组织缺少 IncidentMgmt.orgHasITSMOrgPermission。
• 404 Not Found → 组织上未激活服务器。

请逐字报告原始响应，不要猜测哪个前置条件未满足。

---

架构 — 配置如何工作

步骤	操作	工具
预检	确认目标路由可访问	describe、dispatch_readonly
读取架构	获取读取和写入的请求/响应约定	describe
读取当前状态	获取主偏好设置的当前状态	dispatch_readonly
决定操作	查看 / 启用 / 禁用 — 根据提示词推断	—
写入确认	显示 (status: current → requested)，并要求明确回复“是”	—
应用更改	通过写入路由启用或禁用主设置	dispatch
验证	重新读取并与请求的状态进行比较	dispatch_readonly

幂等性：在第 3 阶段读取后，如果当前状态已符合请求的状态，则跳过第 5 阶段，并将操作视为无操作。references/mcp-invocation.md 说明了确切的状态字段和匹配规则。

只读工具选择：读取时使用 dispatch_readonly。写入时使用 dispatch。服务端会拒绝通过 dispatch_readonly 执行变更操作。

请求格式：dispatch 和 dispatch_readonly 都接受 {"url": "/services/data/...", "method": "GET|POST|PATCH|...", "body"?: {...}, "query_params"?: {...}}。确切的请求/响应格式请参阅 references/mcp-invocation.md；运行时调用 describe 进行确认。

---

澄清问题

只询问对话上下文中尚未提供的信息：

字段	说明	默认值
请求的方向	明确指定 enable / disable（或 on / off）	必须 — 不设默认值；如果用户只说了“toggle”而未指定方向，则询问方向
确认写入	执行任何 dispatch 变更前，必须明确回复“是”	必须 — 参见第 4 阶段

如果用户只说了“toggle”而未指定方向，请在第 4 阶段前询问方向。不要根据当前状态推断方向。

---

工作流

所有步骤均在 headless-360 MCP 服务上执行；工具命名空间为 mcp__headless-360__<tool-name>。

阶段 0 — 复用会话已有信息

下面每项预检读取都带有如果已知则跳过条款。调用任何读取端点之前，请检查本会话中较早的轮次是否已通过与当前组织关联的成功工具响应，得出相同事实（例如此前调用此技能、父级编排器执行的实时读取，或本轮较早的 dispatch_readonly）。 明确的用户陈述不能替代对主偏好设置的实时读取——用户的说法可能已过时或有误，而此技能依赖该读取结果作为确认负载和阶段 6 幂等性验证的真实依据。若唯一信息来源是用户陈述，请重新读取。

• 主读写路由的 describe — 如果本会话中已针对当前组织获取请求／响应架构，则跳过阶段 1 和阶段 2，并复用缓存的架构。describe 输出在单个会话内保持稳定。
• 当前主偏好设置状态 — 如果本会话中已通过成功的 dispatch_readonly 响应读取当前组织的主 IncidentMgmtEnabled 值（即此技能此前运行的阶段 3 结果，或父级编排器已要求我们检查），则跳过阶段 3，并复用记录的“之前”值。用户口头声称开关处于开启或关闭状态，不符合缓存资格。

不确定时，重新检查。 只有当较早的信息在上下文中明确无误，且组织未发生切换时，才跳过——headless-360 MCP 会话通过 JWT 绑定到一个组织，因此只有会话在对话中途重新认证时才可能切换组织。如果用户暗示组织不同，或无法确认较早信息来自哪个组织，请重新执行读取。注意：本会话中任何可能切换主设置的其他 dispatch 写入（此技能的阶段 5，或通过其他工具进行的管理员更改）也会使缓存失效——请重新读取。对实时组织执行写入时，错误地跳过读取比重复读取更糟。

阶段 1 — 预检（discover / describe）

1. （如果本会话中已验证操作架构，则跳过——参见阶段 0。） 对读／写路由调用 describe（如果操作 ID 未知，则使用类似 "ITSM incident management setup discovery" 的查询调用 discover）。确认操作存在，且其参数架构与 references/mcp-invocation.md 匹配。
2. 如果任何工具调用返回 401 / 403 / 404，请停止并提供原始错误——组织或客户端配置不正确（参见前提条件）。

阶段 2 — 加载架构（describe）

3. （如果本会话中每项操作的架构都已缓存，则跳过——参见阶段 0。） 对调用将使用的每项操作调用 describe，并缓存返回的请求／响应架构。不要根据参考文档硬编码参数结构——请从 describe 读取；文档只是工作预期，运行时契约以 describe 返回的内容为准。

阶段 3 — 读取当前状态（dispatch_readonly）

4. （如果本会话中已读取此组织的当前主状态，且之后没有写入将其切换，则跳过——参见阶段 0。） 使用 references/mcp-invocation.md 中记录的读取路由，读取主偏好设置的当前状态。将该值记录为阶段 4 确认和阶段 6 验证所需的“之前”状态。

   对于仅查看请求，请在阶段 3 后停止，并转到阶段 7 进行报告。

阶段 4 — 决定操作并确认后写入（任何写入操作均必需）

5. 根据用户的提示决定操作（查看／启用／禁用）。如果用户只说“切换”，但未说明方向，请先询问方向。

6. 通过 AskUserQuestion 以 (Master Incident Management: <current> → <requested>) 的格式展示目标负载。必须明确收到“是”后才能继续。仅在明确收到“是”时才继续阶段 5。 如果答复为“否”，则停止并报告当前状态，不执行写入。

阶段 5 — 应用更改（仅查看时跳过）

7. 应用 references/mcp-invocation.md 中的幂等规则：如果当前状态已与请求状态一致，则跳过阶段 5，并将操作标记为幂等空操作。

8. 否则，使用 references/mcp-invocation.md 中记录的启用或停用路由，通过 dispatch 发送写入请求。启用主开关会在服务端启动 Incident Management 子功能，无需单独调用来开启这些功能。停用主开关会使这些子功能保持其最后设置的值。

9. 出错时（4xx、5xx），逐字记录原始响应并停止。

阶段 6 — 验证（dispatch_readonly）

10. 重新执行阶段 3 的读取，并根据 references/mcp-invocation.md 中的规则与请求状态进行比较。如果两者不一致，则视为写入失败，并逐字报告原始服务端响应。

阶段 7 — 报告

11. 提供更改前后的摘要：
    • 查看：Master Incident Management: <current-status>。
    • 切换：Master Incident Management: <before> → <after>，并给出判定结果 SUCCEEDED / ALREADY-<state> / FAILED。
    • 阶段 6 不匹配时：write FAILED — server state differs from request. Server response: <verbatim>。

---

规则 / 约束

约束	原因
所有操作均通过四个托管的 headless-360 工具执行	托管 MCP 是必需的传输方式
在调用 dispatch / dispatch_readonly 前，通过 describe 读取各操作的参数架构	运行时契约以 describe 的返回内容为准；不要硬编码
读取时使用 dispatch_readonly；写入时使用 dispatch	服务端会拒绝通过 dispatch_readonly 执行变更操作
始终设置/要求 API v67.0 或更高版本	读取和写入路由要求 v67+
写入前读取实时状态	阶段 3 的获取结果是确认提示、幂等检查和阶段 6 验证的事实来源
任何 dispatch 变更操作前，必须通过确认后写入检查点	切换此偏好设置会修改组织状态；用户必须批准确切计划
幂等 — 当前状态已与请求状态一致时，跳过 dispatch	避免无操作写入；确切的匹配规则见 references/mcp-invocation.md
报告 MCP 工具响应中的确切错误文本	服务端会逐字返回底层错误消息
阶段 1 中出现 401 / 403 / 404 时，停止并显示原始错误	只能通过原始响应诊断失败的前置条件
不要在 dispatch 参数中放入 orgId 或 Core URL	服务端会根据请求中的 JWT 颁发者确定目标组织

验证清单

在报告任何变更已完成之前，请确认以下各项。如果有任何一项未勾选，请勿报告成功，而应说明缺少什么。

• 第 1 阶段预检（describe / discover）返回了该操作，且没有返回 401 / 403 / 404；如果返回了其中任何错误，则已呈现原始错误并停止运行。
• 第 3 阶段针对主偏好的读取返回了状态，并已将该值记录为“变更前”状态。
• 第 4 阶段写入确认通过 AskUserQuestion 呈现了 (Master Incident Management: <current> → <requested>)，且用户明确回复了“yes”——收到其他任何回复（沉默、“maybe”、“looks good”或隐式批准）时均未发起写入。
• 幂等性：如果当前状态已与请求的状态一致，则已跳过第 5 阶段，并将本次运行报告为幂等空操作——未发出 dispatch 写入请求。
• 第 5 阶段写入使用了 dispatch（而非 dispatch_readonly），并采用 references/mcp-invocation.md 中的线级格式；遇到任何 4xx / 5xx 时，已呈现原始响应并停止运行。
• 第 6 阶段验证重新执行了第 3 阶段的读取，且写入后的状态与用户批准的目标一致；任何差异均已报告为 write FAILED — server state differs from request。
• 最终报告列出了主偏好的变更前/后状态，并给出判定 SUCCEEDED / ALREADY-<state> / FAILED。

---

参考文件索引

文件	何时阅读
references/mcp-invocation.md	主偏好的精确读取和写入工具调用格式、在 mcp-config.json 中为 headless-360 注册 MCP 客户端的步骤、External Client App 设置检查清单（mcp_api scope、PKCE、JWT）、Headless-360 错误分类，以及启用/禁用的完整示例