ServiceNow SDK Setup
ServiceNow SDK（now-sdk）CLI 用于脚手架、构建和部署 Fluent DSL 应用。本技能适用于任何 SDK 安装、项目创建、认证或环境校验任务。
参考文件
只读取与当前任务相关的文件，不要在会话开始时预加载全部参考。
- references/setup-workflows.md：脚手架新项目、配置认证、转换已有应用或诊断环境问题时阅读
- references/auth-profiles.md：配置 Basic 或 OAuth 认证、管理命名别名或向命令传递 --auth 时阅读
- references/init-templates.md：选择项目模板或传递非交互式 init 标志时阅读
- references/convert-existing-app.md：从 XML 元数据或 Update Set 转换已有应用时阅读
- references/third-party-libraries.md：向 SDK 项目添加 npm 包时阅读
- references/js-modules-types.md：在 src/server/ 使用 JS 模块、在服务端模块使用 TypeScript，或使用 @servicenow/glide 类型定义时阅读
- references/cli-reference.md：查找 auth、init、build、install、download 或 dependencies 命令的标志时阅读
脚本
- scripts/check-environment.sh：在开始 SDK 工作前校验开发环境。在 CI 流水线中使用 --offline。
硬性规则
- 先阅读再建议。给出设置说明前，始终阅读 references/setup-workflows.md。不要依赖记忆中的命令语法——SDK 命令会随版本变化。
- 使用 now-sdk auth --add，而非 auth save 或 login。auth save 不存在，login 已弃用。正确命令是 now-sdk auth --add <url> --alias <name>。
- 始终使用命名别名。用 now-sdk auth --add <url> --alias dev——别名允许管理多个实例。
- 不理解用例时不要选择模板。遵循下方脚手架行为中的发现流程。只有在两次未获回答的提示后才回退到 typescript.basic。
- 范围前缀来自 now.config.json。在完成设置后协助编写 Fluent DSL 代码时，提示用户激活 sn-sdk-fluent 技能。
- 绝不在未成功构建前运行 install。now-sdk install 会部署 dist/ 中的内容。未先执行 now-sdk build 就运行，会静默推送过时或缺失的产物。部署前构建必须干净完成。
- 部署前始终验证认证。OAuth 令牌会静默过期。每次部署前运行 now-sdk auth --list 并确认正确的别名为活动状态。部署中途的认证失败难以诊断。
- sys_app.do 是应用记录，而非运行中的 UI。部署后，install 输出中的链接指向应用记录。实时 UI URL 是 .now.ts 源码中 UiPage() 调用定义的 endpoint 值，例如 https://<instance>.service-now.com/<endpoint>.do。
按任务类型的行为
新项目脚手架
先阅读 references/setup-workflows.md 和 references/init-templates.md，然后执行以下流程：
步骤 1 — 实例 URL 若尚未提供，询问：
"你的 ServiceNow 实例 URL 是什么？（例如 https://dev12345.service-now.com）"
步骤 2 — 认证
推荐 OAuth。询问："OAuth（推荐）还是 Basic auth？"
重要：OAuth 需要交互式终端输入——Claude Code 无法处理。参见 references/cli-reference.md → auth --add（令牌刷新）中的终端变通方案。
用户确认认证成功后，用以下命令验证：now-sdk auth --list
步骤 3 — 要构建什么 用一个带示例的问题引导回答：
"你在构建什么？例如：
- 业务规则、脚本包含、流程、Service Portal 组件 → typescript.basic
- 带自定义 React UI 页面的应用 → typescript.react
- 带自定义 Vue UI 页面的应用 → typescript.vue"
若用户回答 → 映射到正确模板，用一句话说明理由，与用户确认，然后执行脚手架。
若无回答 → 再问一次："需要自定义 UI，还是仅服务端？"
若仍无回答 → 使用 typescript.basic 并说明："采用 typescript.basic——适用于一切服务端场景。之后可用 partial.typescript.react 添加 React。"
步骤 4 — 脚手架
now-sdk init
--template <chosen-template>
--appName "<App Name>"
--packageName <package-name>
--scopeName <x_scope_name>
--auth dev
然后：npm install
步骤 5 — 交接
"项目已就绪。激活 sn-sdk-fluent 技能即可开始编写 .now.ts 文件。"
认证设置（独立）
阅读 references/setup-workflows.md 第 2 节（配置认证）
确定 Basic 还是 OAuth——推荐 OAuth
完整的标志参考和别名管理见 references/auth-profiles.md。
OAuth 需要交互式终端输入——Claude Code 无法处理。参见 references/cli-reference.md → auth --add（令牌刷新）中的终端变通方案。
验证命令：now-sdk auth --list
转换已有应用
阅读 references/setup-workflows.md 第 3 节（转换已有应用）
完整的 5 步工作流与注意事项见 references/convert-existing-app.md。
完整走过工作流：init --from → transform → build → install
构建与部署
部署前检查清单——务必先逐项完成：
- now-sdk auth --list → 确认正确的别名被标记为默认
- 确保源码变更已保存且完整
- 运行 build——必须干净成功后才能继续
执行顺序——绝不跳过或重排：
npm run build # now-sdk build —— 类型检查 + 打包 npm run deploy # now-sdk install —— 推送产物到实例
部署后验证——始终确认正确版本已上线：
- 打开 https://<instance>.service-now.com/sys_app.do?sys_id=<scopeId>（scopeId 在 now.config.json 中）
- 确认版本与刚部署的一致
- 确认状态为 Active
- 若任一不符，在实例上检查 sys_app_install_log 中的错误
部署后查找实时 UI URL： install 输出显示的是 sys_app.do 链接——那是应用记录，不是运行中的 UI。获取实时 URL 的方法：
- 打开 .now.ts 源文件中的 UiPage() 定义
- 读取 endpoint 值（例如 x_snc_myapp_portal.do）
- 实时 URL：https://<instance>.service-now.com/<endpoint>.do
指定目标实例：
now-sdk install --auth <alias> # 覆盖默认别名
常见故障与修复：
- 症状：部署中途认证错误。原因：OAuth 令牌过期。修复：OAuth 令牌刷新需要交互式输入——参见 references/cli-reference.md → auth --add（令牌刷新）中的终端变通方案，然后重试部署。
- 症状："Could not determine app installation status"。原因：上传处理器未返回 tracker ID；SDK 的 sys_upgrade_history 轮询在 30 秒后超时。修复：使用 --reinstall：now-sdk install --auth <alias> --reinstall。该命令先卸载，再通过 tracker 路径干净重装。
- 症状：安装成功但 UI 显示旧代码。原因：构建被跳过或产物过时。修复：重新运行 npm run build 然后 npm run deploy。
- 症状：类型检查错误阻断构建。原因：源码中的 TypeScript 错误。修复：修复报告的错误——不要绕过。
- 症状：安装时范围冲突。原因：另一应用占用了该范围。修复：检查 sys_app 中冲突的范围，解决后再重试。
环境校验
引导用户运行 scripts/check-environment.sh --offline（若在 CI 中）或不带标志（同时检查连接）。
解读 JSON 输出并解释任何失败的检查项。