update-set-workflow

用途

Update Set Workflow 是面向 ServiceNow 开发的更新集管理技能。更新集（Update Set）在 ServiceNow 开发中是强制要求：没有更新集，变更不会被跟踪，也无法部署到其他实例。该技能还带有强制机制——当会话中没有活动更新集时，配置写入会在工具层被阻止。遇到该阻止时，应先询问用户是否将工作捕获到命名更新集中，然后调用一次 snow_ensure_active_update_set({ name }) 并重试；只有当用户明确拒绝跟踪时，才用 __skipUpdateSet: true 重新发起一次调用，该选择会在本次会话剩余时间内被记住。

主要能力

在任何开发之前，始终创建或确保有一个活动更新集。典型流程为：

检查当前更新集：

var current = await snow_update_set_query({ action: "current" })

如果没有更新集或正在使用 Default，则创建一个：

if (!current || current.name === "Default") {
  await snow_update_set_manage({
    action: "create",
    name: "Feature: [Descriptive Name]",
    description: "What and why this change is being made",
  })
}

此时可以安全地进行变更，所有变更都会被跟踪。
完成后完成更新集：

await snow_update_set_manage({
  action: "complete",
  update_set_id: current.sys_id,
})

命名规范

类型	格式	示例
Feature	`Feature: [Name]`	`Feature: Incident Auto-Assignment`
Bug Fix	`Fix: [Issue]`	`Fix: Approval Email Not Sending`
Enhancement	`Enhancement: [Name]`	`Enhancement: Dashboard Performance`
Hotfix	`Hotfix: [Issue]`	`Hotfix: Critical Login Bug`

更新集生命周期

In Progress —— 活动状态，接收变更
Complete —— 可供导出/提升
Ignore —— 变更不会被提升（用于实验）

会被跟踪的内容

更新集自动捕获以下变更：

表和列
Business Rules
Script Includes
Client Scripts
UI Policies 和 Actions
Workflows 和 Flow Designer flows
Service Portal widgets 和 pages
ACLs 和安全规则
系统属性
计划任务
以及更多……

不会被跟踪的内容

数据记录（数据请使用 Import Sets）
记录上的附件
用户会话信息
部分系统表（sys_user 等）

更新集的 MCP 工具

// 创建新更新集
snow_update_set_manage({
  action: "create",
  name: "Feature: My Feature",
  description: "Description of changes",
})

// 切换到已有更新集
snow_update_set_manage({
  action: "switch",
  update_set_id: "sys_id_here",
})

// 获取当前更新集
snow_update_set_query({ action: "current" })

// 完成更新集
snow_update_set_manage({
  action: "complete",
  update_set_id: "sys_id_here",
})

// 将更新集导出为 XML
snow_update_set_manage({
  action: "export",
  update_set_id: "sys_id_here",
})

最佳实践

一个功能一个更新集——不要混入无关变更
使用描述性名称——清楚说明更新集包含什么
完成后及时完成——不要无限期保持更新集打开
完成前先测试——验证所有变更正常工作
绝不使用 Default——始终创建命名更新集

OAuth 上下文与更新集跟踪

Serac 使用 OAuth 服务账号认证。所有 API 调用以 OAuth 服务账号身份运行，而不是你的 UI 用户。更新集必须对进行变更的用户是“当前”的——对于 API 变更，这意味着对服务账号是当前的。

两个上下文：

┌─────────────────────────────────────────────────────────────┐
│ YOUR UI SESSION (when you log in to ServiceNow UI)         │
│ User: john.doe                                              │
│ Current Update Set: [Whatever you selected in the UI]      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ SERAC OAUTH SESSION (API calls)                             │
│ User: oauth.service.account                                 │
│ Current Update Set: [Set via Update Set tools]             │
│ ← All Serac changes are tracked here                        │
└─────────────────────────────────────────────────────────────┘

auto_switch —— 跟踪所必需：

auto_switch=true（默认）—— 更新集被设为服务账号的当前更新集，所有变更都会被跟踪 ✅
auto_switch=false —— 变更不会被跟踪。仅用于查询/分析，绝不用于开发。

要点：

✅ 更新集确实会被创建——它们存在于 ServiceNow 中
✅ 当 auto_switch=true 时变更确实会被跟踪——所有 Serac 产物自动进入更新集
❌ 除非提供 servicenow_username 参数（这也会使其成为该 UI 用户的当前更新集），否则在你的 UI 会话中不可见
✅ 部署仍然有效——更新集可以正常导出/导入
⚠️ 不要为开发任务禁用 auto_switch

何时使用 servicenow_username：可选。当你希望更新集同时在你的 UI 会话中显示为当前更新集时，传入你的 ServiceNow 用户名——当你同时在 ServiceNow UI 和 Serac 中工作，并希望两处看到同一个更新集被选中时会很方便。它不影响跟踪；跟踪由 auto_switch 决定。

适用场景

适用于在 ServiceNow 上进行开发、需要跟踪配置变更并部署到其他实例的场景，尤其是通过 Serac 的 OAuth 服务账号进行 API 变更时。

限制

数据记录、记录附件、用户会话信息以及部分系统表（如 sys_user）不会被更新集跟踪。auto_switch=false 时变更不会被跟踪，仅可用于查询和分析。