service-itsm-incident-priority-configure

配置事件优先级矩阵（sf CLI）

为 Salesforce ITSM 配置事件优先级矩阵——根据事件的影响和紧急程度确定其优先级的网格。涵盖查看矩阵、启用／停用矩阵、新增／更改／移除／填充矩阵单元格、切换手动覆盖偏好设置，以及读取／设置默认（回退）优先级。

所有读取和写入操作都通过 sf CLI 执行，因此只要组织启用了事件管理许可证，此技能就适用于该组织。

写入操作具有幂等性（如果当前状态已符合目标状态，则跳过），此技能始终先读取，再写入，并且在进行任何更改之前，必须经过明确的确认写入检查点。

范围

• 范围内（仅限事件）：查看矩阵；启用／停用矩阵；新增、更改、移除或填充矩阵单元格；切换手动覆盖；读取／设置默认（回退）优先级。
• 范围外：Problem 和 ChangeRequest 矩阵；非 ITSM 优先级选项；SLA／里程碑／授权设置；启用事件管理本身。如果用户询问 Problem 或 ChangeRequest，请停止并说明这一点。

---

前提条件

1. sf CLI ≥ 2.60（使用 sf --version 验证）。
2. 目标组织已通过 sf 进行身份验证——运行 sf org list 后，其中一项应显示为 Connected。
3. 组织已启用事件管理——即 Service Cloud ITSM 事件功能的主偏好设置（Setup Discovery apiName = service-cloud-itsm-incident）。预检时通过 GET /services/data/v67.0/connect/setup/discovery/features 直接读取，并筛选 apiName == "service-cloud-itsm-incident"（此接口未公开主设置对应的 setup-org-preferences 端点——IncidentMgmtEnabled／ITSMIncidentMgmtEnabled 均返回 404）。如果 status != "ENABLED"，则内联委派给 service-itsm-incident-mgmt-configure 以启用该功能（该技能会针对同一路由自行执行先读取、再写入的流程，并要求确认写入），然后继续第 1 阶段。
4. 调用用户拥有 CustomizeApplication 权限（查看设置和设置管理员）。

如果不满足任何前提条件，CLI 会原样显示原始错误——不要捏造状态，显示原始错误并停止。

---

路由一览

每条路由都通过 sf CLI 调用。完整的方法 / 路径 / 请求体 / 响应详情、选项列表提取步骤和注意事项，请参阅 references/sf-cli-invocation.md。

事项	传输方式	HTTP 状态码
主 Incident Mgmt 偏好设置（读取）	使用 sf api request rest 对 /services/data/v67.0/connect/setup/discovery/features 执行 GET，筛选 apiName == "service-cloud-itsm-incident"，获取 status	200
矩阵启用标志（读取/写入）	使用 sf api request rest 请求 /services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled	200
手动覆盖（读取/写入）	使用 sf api request rest 请求 /services/data/v67.0/setup/org/preferences/IncPriorityOverrideEnabled	200
矩阵行（读取）	使用 sf data query --use-tooling-api 查询 ServiceOpPriorityConfig	200
矩阵行（添加）	使用 sf api request rest 对 /services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig 执行 POST	201
矩阵行（更改）	使用 sf api request rest 对 /services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig/<Id> 执行 PATCH	204
矩阵行（移除）	使用 sf data delete record --use-tooling-api 删除 ServiceOpPriorityConfig 中的记录	200
默认回退优先级（读取）	使用 sf api request rest 对 /services/data/v67.0/tooling/query/?q=...StandardValueSet... 执行 GET	200
默认回退优先级（写入）	对 StandardValueSet:IncidentPriority 执行 sf project retrieve start + 编辑 + sf project deploy start	deploy Succeeded
选项列表值（Incident）	使用 sf api request rest 对 /services/data/v67.0/sobjects/Incident/describe 执行 GET	200
Salesforce Go 步骤“完成”（写入，在执行变更后）	使用 sf api request rest 对 /services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/configuration/step/definePriorityMatrix/progress 执行 PUT	200

路径前缀至关重要——请勿移除。 Setup Connect API 路径必须以 /services/data/v67.0/ 开头。Tooling REST 路径必须以 /services/data/v67.0/tooling/ 开头。

---

澄清问题

只询问无法推断的信息：

• 使用哪个 org？ sf CLI 别名或用户名（--target-org <alias>）。默认使用该 org 的默认目标。
• 要执行什么操作？ 查看；启用 / 禁用矩阵；切换手动覆盖；设置默认优先级；添加 / 更改 / 移除单元格；填充完整矩阵。
• 添加 / 更改时： Impact + Urgency 坐标，以及对应的 Priority（根据获取的选项列表值进行验证）。
• 设置默认优先级时： 目标 Priority 值。如果用户未指定，则使用 org 当前启用的 Incident.Priority 选项列表值作为选项调用 AskUserQuestion——切勿猜测。

---

工作流

所有步骤都按顺序执行。始终先读取，再写入。 所有调用都通过 sf CLI 进行。

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

以下每项阶段 1 / 阶段 2 读取操作都带有如果已知则跳过条款。调用任何 sf 命令前，请检查本会话中较早的轮次是否已通过与当前 --target-org 关联的成功 sf 调用生成了相同事实（例如先前运行本技能，或在同一对话中较早调用 sf）。此处的会话上下文按 --target-org <alias> 区分，因此不同别名对应不同会话。明确的用户陈述不符合缓存条件——这些选项列表值、偏好布尔值、矩阵行和回退优先级都会用于阶段 4 修改时的客户端验证和重复项防止，因此错误或过时的用户陈述可能绕过这些保护措施，并创建无效或重复的行。如果唯一来源是用户陈述（或者你无法确定具体的先前 sf 响应），请重新读取。

• sf --version — 如果本会话已报告 CLI 版本，则跳过步骤 1。
• Incident describe（有效的 Impact / Urgency / Priority 选项列表） — 如果本会话已针对当前 --target-org 读取 Incident describe，且上下文中包含这三个选项列表，则跳过步骤 2 并复用它们。
• IncPriorityMatrixEnabled / IncPriorityOverrideEnabled 偏好值 — 如果本会话已读取其中任一值，且此后未执行 PATCH，则跳过其阶段 2 读取操作。
• ServiceOpPriorityConfig 行 — 如果本会话已读取当前组织的 Incident 行，且此后未对 ServiceOpPriorityConfig 执行 POST / PATCH / delete，则跳过步骤 5 并复用行列表。
• StandardValueSet:IncidentPriority 默认值 — 如果本会话已读取回退优先级，且此后未执行 StandardValueSet:IncidentPriority 部署，则跳过步骤 6。

不确定时，请重新检查。 只有当该事实明确存在于上下文中、--target-org 别名未变，且此后没有可能使其失效的阶段 4 写入操作（偏好 PATCH、ServiceOpPriorityConfig POST/PATCH/delete，或 StandardValueSet:IncidentPriority 部署）时，才跳过。对实时组织错误地跳过读取，比重新读取更糟。

阶段 1 — 预检

1. （如果本会话已报告 sf --version，则跳过——参见阶段 0。） 运行 sf --version，确认 CLI 可用。
2. 主 Incident Management 偏好项 — 直接读取 （仅当本会话已针对当前 --target-org 读取主偏好项，且其值为 ENABLED，并且本会话中没有其他写入操作可能将其切换时才跳过——参见阶段 0。） sf api request rest "/services/data/v67.0/connect/setup/discovery/features" --method GET --target-org <alias>。解析响应，并筛选 features[] 数组中 apiName == "service-cloud-itsm-incident" 的元素；读取其 status 字段。如果 status == "ENABLED"，继续步骤 3。如果 status != "ENABLED"，则内联委派给 service-itsm-incident-mgmt-configure 以启用主偏好项（该技能会针对同一路由自行执行写入前确认），然后重新读取本步骤，确认 status == "ENABLED" 后再继续。如果用户拒绝委派，则停止——主功能关闭时，Priority Matrix 无法运行。这是直接读取主偏好项，而非代理检查；接下来的 Incident describe 检查只是次级健全性检查，不是主状态信号。
3. （如果本会话上下文中已包含针对当前 --target-org 的 Incident describe——包括有效的 Impact / Urgency / Priority 选项列表——则跳过；参见阶段 0。） sf api request rest "/services/data/v67.0/sobjects/Incident/describe" --method GET --target-org <alias>。返回 200 且包含 Impact / Urgency / Priority 选项列表字段，即为次级健全性检查。提取有效的选项列表值，以供后续验证。如果 describe 响应很大，则分派一个子 Agent（haiku 层级）仅提取这三个选项列表。

阶段 2 — 显示当前状态（只读）

执行以下读取操作（预计均返回 200）：

3. （如果本会话中已读取当前 --target-org 的 IncPriorityMatrixEnabled，且之后未执行 PATCH，则跳过——参见阶段 0。） sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled" --method GET --target-org <alias> — 矩阵启用标志。响应体：{"isPreferenceEnabled": <bool>}。
4. （如果本会话中已读取当前 --target-org 的 IncPriorityOverrideEnabled，且之后未执行 PATCH，则跳过——参见阶段 0。） sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityOverrideEnabled" --method GET --target-org <alias> — 手动覆盖标志。响应体格式相同。
5. （如果本会话中已读取当前 --target-org 的 Incident ServiceOpPriorityConfig 行，且之后未对这个 SObject 执行 POST / PATCH / delete，则跳过——参见阶段 0。） 矩阵行 — sf data query --use-tooling-api --target-org <alias> --query "SELECT Id, DeveloperName, ReferenceObject, Urgency, Impact, Priority FROM ServiceOpPriorityConfig WHERE ReferenceObject = 'Incident'"。返回零行或多行。DeveloperName 为必填项，以便添加步骤生成新的唯一后缀。
6. （如果本会话中已读取 StandardValueSet:IncidentPriority 的默认值，且之后未执行过 StandardValueSet:IncidentPriority 部署，则跳过——参见阶段 0。） 默认回退优先级 — sf api request rest "/services/data/v67.0/tooling/query/?q=SELECT+Id,MasterLabel,Metadata+FROM+StandardValueSet+WHERE+MasterLabel='IncidentPriority'" --method GET --target-org <alias>。读取 records[0].Metadata.standardValue，找到 default: true 的条目，并取其 valueName——这就是回退优先级。

按照 Impact × Urgency 网格格式呈现这些行（参见 examples/render-matrix.md）。步骤 3–6 合起来构成“查看”操作和操作前快照。

重复坐标检测（对更改 / 移除至关重要）： 按 (ReferenceObject, Urgency, Impact) 对阶段 2 的行分组。如果任何一组包含多行，则矩阵中已有重复项（服务端不强制唯一性）。对于目标坐标重复的任何操作，暂停该事项的阶段 3——在用户明确指定 Id 或批准合并方案之前（参见 阶段 4 → 更改单元格 和 阶段 4 → 移除单元格），不要要求用户确认更改或移除。添加操作不受影响——阶段 4 的添加流程会拒绝任何快照中已存在的坐标。

阶段 3 — 确认目标（AskUserQuestion，任何写入前均必须执行）

将预期更改呈现为 (Concern: <before> → <after>)，并通过 AskUserQuestion 要求用户明确回答“是”。只有在用户明确回答“是”时才继续阶段 4。若回答“否”，则停止并报告当前状态，不执行写入。

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

先读取同一设置的当前值（阶段 2 涵盖此操作），与用户确认目标（阶段 3），然后执行操作。每项操作的有效负载格式和完整 CLI 调用见 examples/matrix-operations.md。

• 启用 / 禁用矩阵 — 对 IncPriorityMatrixEnabled 执行 sf api request rest PATCH，请求体为 {"desiredState": <bool>}。PATCH 响应会返回 {"isPreferenceEnabled": <bool>}；无需单独重新读取。
• 切换手动覆盖 — 对 IncPriorityOverrideEnabled 执行 sf api request rest PATCH，请求体为 {"desiredState": <bool>}。不会触及矩阵行或默认优先级。
• 添加单元格 — 对 /services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig 执行 sf api request rest POST，请求体为 {"ReferenceObject": "Incident", "Urgency": "<val>", "Impact": "<val>", "Priority": "<val>", "DeveloperName": "<unique>", "MasterLabel": "<same>"}。有效负载必须满足 ReferenceObject == "Incident" — 此 SObject 由 Problem / ChangeRequest 共用，且服务端接受任意字符串。请先根据获取的选项列表验证每个 Urgency / Impact / Priority — Tooling 端点不会强制执行选项列表验证。请根据阶段 2 的快照去重：服务端不会拒绝 (ReferenceObject, Urgency, Impact) 重复项，因此对同一坐标再次 POST 会静默保存为第二行，运行时会以不确定方式从中选择。
• 更改单元格 — 读取阶段 2 的行，查找匹配 (ReferenceObject=Incident, Urgency, Impact) 的行。如果恰好匹配一行，对 /services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig/<Id> 执行 sf api request rest PATCH，请求体为 {"Priority": "<new val>"}。如果没有匹配行，这是添加而非更改；请说明情况并询问用户。如果匹配多行（阶段 2 已检测到重复项），请勿执行操作 — 报告重复行及其 Id / DeveloperName / 当前 Priority，并要求用户指定要更改的确切 Id，或批准合并计划（删除多余行，然后更改保留行）。
• 移除单元格 — 读取阶段 2 的行，查找匹配 (ReferenceObject=Incident, Urgency, Impact) 的行。如果恰好匹配一行，执行 sf data delete record --sobject ServiceOpPriorityConfig --record-id <Id> --use-tooling-api --target-org <alias>。如果没有匹配行，直接结束并告知“没有要移除的内容”。如果匹配多行，请勿执行操作 — 报告重复项，并要求用户指定要移除的确切 Id，或明确确认“移除此坐标下的所有行”。
• 填充完整矩阵 — 参见 examples/seed-full-matrix.md。请先验证值，然后逐行 POST。
• 设置默认回退优先级 — 执行 sf project retrieve start --metadata "StandardValueSet:IncidentPriority" --target-org <alias>，编辑文件，将目标值设为 <default>true</default>，并将其他每个值设为 <default>false</default>，然后执行 sf project deploy start --metadata "StandardValueSet:IncidentPriority" --target-org <alias> --wait 10。在部署结果中确认状态为 Succeeded。

阶段 5 — 验证并呈现

7. 重新读取已修改的关注项（通过 Tooling SOQL 查询矩阵行；通过 StandardValueSet 查询默认优先级；PATCH 响应会回显偏好设置）。如果观察到的状态与请求的状态不符，则将其视为写入失败，并逐字报告服务器原始响应。
8. 仅当阶段 4 的功能性写入确实生效时，才将 Salesforce Go 步骤标记为 Done。“Define Priority Matrix”步骤由用户覆盖：它的勾选状态并非根据组织状态得出，因此仅配置矩阵不会自动将其标记为完成；必须写入完成状态。步骤 7 验证写入后，PUT 一次完成状态（references/sf-cli-invocation.md 路由 10；请求体 {"isComplete": true}，标志为 REQUIRED）。此操作沿用阶段 3 的确认——无需单独执行 AskUserQuestion。对于只读查看和幂等空操作，完全跳过。
9. 呈现变更前后状态（通过 examples/render-matrix.md 显示 Impact × Urgency 网格），并附上一行摘要（例如：Incident matrix: High/High → Critical added）。矩阵变更仅影响写入后创建的 Incidents；停用矩阵不会清除已存储的行或默认优先级。

---

规则 / 约束

约束	原因
所有操作均通过 sf CLI 执行	适用于启用了 Incident Management 的任何组织；无需额外设置
始终至少使用 API v67.0	Setup Connect API 偏好设置路由要求 v67+
写入前读取实时状态	阶段 2 的快照是确认提示、幂等性检查和阶段 5 验证的事实依据
任何修改前都必须经过确认后写入检查点	切换偏好设置或更改矩阵行会修改组织状态；用户必须批准确切的计划
幂等——如果当前状态已符合请求状态，则跳过写入	避免空操作写入；每项关注内容的精确匹配规则见 references/sf-cli-invocation.md
调用前，根据组织的实时选项列表验证每个 Impact、Urgency、Priority	Tooling REST 端点不会执行选项列表验证；运行时矩阵评估器会执行。跳过此验证会导致无效行进入矩阵
添加前，根据阶段 2 的快照在客户端去重	服务器不会强制执行 (ReferenceObject, Urgency, Impact) 唯一性——在相同坐标上再次 POST 会将另一行作为独立行持久化。客户端去重是防止单元格重复的唯一保护措施。
拒绝任何非 Incident 的 ReferenceObject（Problem、ChangeRequest 或其他值）	在网络协议层面，ServiceOpPriorityConfig 与 Problem / ChangeRequest 矩阵共用——服务器接受任何 ReferenceObject 字符串。仅由技能强制限定为 Incident。
更改 / 移除时，如果目标坐标对应多行，则不要调用——要求提供明确的 Id 或已确认的合并计划	服务器允许重复的 (ReferenceObject, Urgency, Impact) 行。任意选择“那一行的 Id”会修改其中一个重复项，而保留另一个，导致矩阵仍不确定。
准确报告 CLI 响应中的错误文本	CLI 会逐字显示底层错误消息
功能性写入后，PUT Salesforce Go 步骤进度以标记完成（路由 10）；查看 / 空操作时跳过	“Define Priority Matrix”步骤由用户覆盖——它的勾选状态并非根据组织状态得出，因此仅配置写入会导致 Go 清单仍无法完成

---

验证清单

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

• 第 1 阶段预检（针对 Incident describe 执行 sf api request rest）返回了 200，且 Impact / Urgency / Priority 选项列表处于启用状态；如果返回 404，则已展示原始错误并停止运行。
• 第 2 阶段对写入计划涉及的每项关注内容进行读取，均返回了 200（或已展示原始错误），并将每个观察到的值记录为“变更前”状态。对于 Change / Remove，第 2 阶段的行按 (ReferenceObject, Urgency, Impact) 分组，并向用户指出变更目标上的任何重复坐标——在通过明确的 Id 或已确认的合并计划解决重复问题之前，未执行任何 Change / Remove。
• 第 3 阶段写入确认通过 AskUserQuestion 展示了 (<concern>: <current> → <requested>)，且用户明确回复了“yes”——任何其他回复（沉默、“maybe”、“looks good”、隐式批准）都不会触发写入。
• 幂等性：如果当前状态已符合请求状态，则跳过该关注项的第 4 阶段，并报告为幂等空操作——未执行任何写入。
• 任何添加 / 更改载荷中的所有 Impact、Urgency、Priority 都已在发送前根据第 1 阶段的选项列表值进行验证。已在客户端根据第 2 阶段快照拦截 (ReferenceObject, Urgency, Impact) 上的重复项——服务端不会拒绝重复项。每个添加载荷的 ReferenceObject 均为 "Incident"。
• 第 4 阶段写入使用了 references/sf-cli-invocation.md 中的确切 CLI 调用；任何 4xx / 5xx（或非 Succeeded 的部署）都已展示原始响应并停止运行。
• 第 5 阶段验证重新读取了受影响的关注项；任何差异都已作为 write FAILED — server state differs from request 报告，并附上原始响应。
• 如果第 4 阶段的功能性写入已生效，则在验证后发送了 Go 步骤进度完成 PUT（路由 10）。对于仅查看的读取和幂等空操作，未发送完成 PUT。
• 最终报告包含变更前 / 变更后的 Impact × Urgency 网格，以及一行摘要。

---

参考文件索引

文件	阅读时机
references/sf-cli-invocation.md	确切的 sf CLI 调用、响应封装、选项列表提取、幂等规则和注意事项
examples/render-matrix.md	Impact × Urgency 网格布局
examples/matrix-operations.md	启用、覆盖、默认、添加 / 更改 / 移除的完整 CLI 调用模板
examples/seed-full-matrix.md	初始化完整矩阵（先验证选项列表值）