mcpField
A
app-summary

app-summary

github.com/happy-technologies-llc开发4141 次安装2 天前更新
代码仓库

关于 app-summary

用于生成现有 ServiceNow 应用结构化摘要的技能，适合开发者和管理员。它整理数据模型、脚本、访问控制、依赖关系和应用健康信息，支持评审、升级与团队入职。

主要功能

  1. 01检查应用元数据与作用域
  2. 02盘点表、字段和脚本
  3. 03审查 ACL 与应用角色
  4. 04梳理依赖和集成
  5. 05评估应用复杂度与健康状况

适用场景

  1. 01为应用升级做准备
  2. 02为团队入职整理应用文档
  3. 03评估技术债务或应用整合对象

MCP 相关

使用 SN-Query-Table 和 SN-Get-Record 等 ServiceNow MCP 工具检索应用元数据与构件。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/happy-technologies-llc/happy-platform-skills --skill app-summary

安装后在 Claude Code 中输入/app-summary确认已加载。

详细介绍

ServiceNow 应用摘要

概述

此技能涵盖如何为现有 ServiceNow 应用生成全面摘要，包括：

  • 应用范围和元数据分析
  • 表结构和数据模型文档
  • 脚本清单（业务规则、客户端脚本、脚本包含项、UI 操作）
  • ACL 和角色分析
  • 依赖关系和集成映射
  • 配置工件清单
  • 应用健康状况和复杂度评估

使用场景： 应用组合审查期间、升级或迁移之前、开发者入职时、生成文档时、评估技术债务时，或评估应用是否适合整合时。

前提条件

  • 角色： admin、application_developer，或对 sys_scope 和 sys_metadata 的读取权限
  • 访问权限： sys_scope、sys_app、sys_metadata、sys_db_object、sys_dictionary、sys_script 表
  • 知识： ServiceNow 应用模型、作用域应用结构
  • 相关技能： 完成 genai/app-generation，了解应用结构

流程

步骤 1：识别应用

按名称查找应用：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_scope
  query: nameLIKE[app_name]^active=true
  fields: sys_id,name,scope,short_description,version,vendor,vendor_prefix,sys_created_on,sys_updated_on
  limit: 10

REST 替代方案：

curl -u "$SN_USER:$SN_PASS" \
  "$SN_INSTANCE/api/now/table/sys_scope?sysparm_query=nameLIKE[app_name]^active=true&sysparm_fields=sys_id,name,scope,short_description,version,vendor&sysparm_limit=10" \
  -H "Accept: application/json"

列出所有自定义作用域应用：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_scope
  query: scopeSTARTSWITHx_^active=true
  fields: sys_id,name,scope,version,vendor,sys_created_on
  limit: 100
步骤 2：获取应用元数据

检索完整的应用详情：

MCP 方式：

Tool: SN-Get-Record
Parameters:
  table_name: sys_scope
  sys_id: [scope_sys_id]

REST 替代方案：

curl -u "$SN_USER:$SN_PASS" \
  "$SN_INSTANCE/api/now/table/sys_scope/[scope_sys_id]" \
  -H "Accept: application/json"

检查 sys_app 中的其他元数据：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_app
  query: scope=[scope_name]
  fields: sys_id,name,version,short_description,template,active
  limit: 1
步骤 3：盘点所有应用工件

按类型统计所有工件的数量：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_metadata
  query: sys_scope=[scope_sys_id]
  fields: sys_id,sys_class_name,sys_name,sys_created_on
  limit: 500

REST 替代方案：

curl -u "$SN_USER:$SN_PASS" \
  "$SN_INSTANCE/api/now/table/sys_metadata?sysparm_query=sys_scope=[scope_sys_id]&sysparm_fields=sys_id,sys_class_name,sys_name&sysparm_limit=500" \
  -H "Accept: application/json"

按 sys_class_name 对结果分组，以生成工件摘要：

Artifact Inventory:
  sys_db_object (Tables): X
  sys_dictionary (Fields): X
  sys_script (Business Rules): X
  sys_script_client (Client Scripts): X
  sys_script_include (Script Includes): X
  sys_ui_action (UI Actions): X
  sys_ui_page (UI Pages): X
  sys_security_acl (ACLs): X
  sys_properties (Properties): X
  sys_ui_form_section (Form Sections): X
  ...
步骤 4：分析表结构

获取应用中的所有表：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_db_object
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,label,super_class,is_extendable,number_ref,sys_created_on
  limit: 50

获取每个表的字段定义：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_dictionary
  query: name=[table_name]^sys_scope=[scope_sys_id]^elementISNOTEMPTY
  fields: element,column_label,internal_type,max_length,mandatory,reference,unique,active
  limit: 100

REST 替代方案：

curl -u "$SN_USER:$SN_PASS" \
  "$SN_INSTANCE/api/now/table/sys_dictionary?sysparm_query=name=[table_name]^sys_scope=[scope_sys_id]^elementISNOTEMPTY&sysparm_fields=element,column_label,internal_type,max_length,mandatory,reference&sysparm_limit=100" \
  -H "Accept: application/json"

获取表记录数（评估数据量）：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_table_rotation
  query: name=[table_name]
  fields: name,max_size,size
  limit: 1
步骤 5：盘点脚本

获取业务规则：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_script
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,collection,when,order,active,action_insert,action_update,action_delete
  limit: 100

获取客户端脚本：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_script_client
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,table,type,fieldname,active,ui_type
  limit: 100

获取脚本包含项：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_script_include
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,api_name,client_callable,active,access
  limit: 100

获取 UI 脚本：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_ui_script
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,global,active,ui_type
  limit: 50
步骤 6：分析 ACL 和角色

获取应用角色：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_user_role
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,description,assignable_by
  limit: 50

获取 ACL 规则：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_security_acl
  query: sys_scope=[scope_sys_id]^active=true
  fields: sys_id,name,operation,type,admin_overrides,condition,advanced
  limit: 100

REST 替代方案：

curl -u "$SN_USER:$SN_PASS" \
  "$SN_INSTANCE/api/now/table/sys_security_acl?sysparm_query=sys_scope=[scope_sys_id]^active=true&sysparm_fields=sys_id,name,operation,type,admin_overrides&sysparm_limit=100" \
  -H "Accept: application/json"
步骤 7：映射依赖关系

检查脚本中的跨作用域引用：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_scope_privilege
  query: source_scope=[scope_sys_id]^ORtarget_scope=[scope_sys_id]
  fields: sys_id,source_scope,target_scope,type,operation,status
  limit: 50

检查集成（REST 消息、SOAP 等）：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_rest_message
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,rest_endpoint,authentication_type
  limit: 20

检查计划作业：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sysauto_script
  query: sys_scope=[scope_sys_id]
  fields: sys_id,name,active,run_type,run_period
  limit: 20
步骤 8：分析 UI 配置

获取 UI 操作：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_ui_action
  query: sys_scope=[scope_sys_id]^active=true
  fields: sys_id,name,table,action_name,client,form_button,list_button
  limit: 50

获取导航模块：

MCP 方式：

Tool: SN-Query-Table
Parameters:
  table_name: sys_app_module
  query: sys_scope=[scope_sys_id]
  fields: sys_id,title,link_type,name,query,order
  limit: 30
步骤 9：汇编应用摘要

生成结构化摘要报告：

Application Summary: [App Name]
================================================
Scope: [scope_name]
Version: [version]
Vendor: [vendor]
Created: [date] | Last Updated: [date]
Description: [short_description]

ARTIFACT INVENTORY:
  Tables: [count]
  Fields: [count]
  Business Rules: [count] (active: X, inactive: Y)
  Client Scripts: [count]
  Script Includes: [count]
  UI Actions: [count]
  ACL Rules: [count]
  Roles: [count]
  Properties: [count]
  Scheduled Jobs: [count]
  REST Messages: [count]
  Total Artifacts: [count]

TABLE STRUCTURE:
  [Table 1 Name] ([Label])
    - Extends: [parent table]
    - Fields: [count]
    - Key Fields: [list of mandatory/unique fields]
  [Table 2 Name] ([Label])
    ...

SCRIPT INVENTORY:
  Business Rules:
    - [Rule Name] on [Table] ([when], order [N]) - [Active/Inactive]
  Client Scripts:
    - [Script Name] on [Table] ([type]) - [Active/Inactive]
  Script Includes:
    - [Include Name] (client_callable: [yes/no]) - [Active/Inactive]

SECURITY MODEL:
  Roles:
    - [Role Name]: [Description]
  ACLs:
    - [Table].[Operation]: [Conditions/Roles]

DEPENDENCIES:
  Cross-scope references: [list]
  Integrations: [list]
  Scheduled Jobs: [list]

COMPLEXITY ASSESSMENT:
  - Table Count: [Low/Medium/High]
  - Script Density: [Low/Medium/High]
  - Integration Points: [count]
  - Overall Complexity: [Low/Medium/High]

工具用法

操作MCP 工具REST 端点
查找应用SN-Query-TableGET /api/now/table/sys_scope
获取应用元数据SN-Get-RecordGET /api/now/table/sys_scope/{sys_id}
列出所有工件SN-Query-TableGET /api/now/table/sys_metadata
获取表SN-Query-TableGET /api/now/table/sys_db_object
获取字段SN-Query-TableGET /api/now/table/sys_dictionary
获取业务规则SN-Query-TableGET /api/now/table/sys_script
获取客户端脚本SN-Query-TableGET /api/now/table/sys_script_client
获取脚本包含项SN-Query-TableGET /api/now/table/sys_script_include
获取 ACLSN-Query-TableGET /api/now/table/sys_security_acl
获取角色SN-Query-TableGET /api/now/table/sys_user_role

最佳实践

  • 从 sys_metadata 开始： 这能最快概览某个范围内的所有构件
  • 按类型对构件分组： 使用 sys_class_name 高效地分类和统计构件
  • 检查启用与停用状态： 已停用的构件可能意味着存在技术债务或已弃用的功能
  • 检查脚本复杂度： 脚本较长或数量较多，说明这些区域可能需要重构
  • 梳理所有集成： 跨范围和外部集成对于评估升级影响至关重要
  • 记录未编写文档的应用： 许多自定义应用缺少文档；概要可以弥补这一缺口
  • 比较版本： 如果存在多个版本，请比较各版本的构件数量
  • 识别孤立构件： 查找引用已不存在的表或字段的脚本
  • 评估测试覆盖率： 检查该范围内是否包含 ATF（自动化测试框架）测试
  • 检查更新集： 检查 sys_update_set 中的部署历史

故障排查

找不到应用

症状： 查询 sys_scope 时没有结果 原因：

  1. 应用是全局范围插件，而非范围应用
  2. 应用名称与范围名称不同
  3. 应用已停用 解决方案：
Tool: SN-Query-Table
Parameters:
  table_name: sys_scope
  query: nameLIKE[partial_name]^ORscopeLIKE[partial_name]
  fields: sys_id,name,scope,active
  limit: 20
元数据计数不完整

症状： sys_metadata 返回的构件少于预期 原因： 某些构件可能未扩展 sys_metadata，或者查询限制过低 解决方案： 提高限制，并检查范围之外的构件：

Tool: SN-Query-Table
Parameters:
  table_name: sys_metadata
  query: sys_scope=[scope_sys_id]
  fields: sys_id,sys_class_name
  limit: 1000
无法确定表关系

症状： 存在引用字段，但关系不明确 解决方案： 专门查询引用字段对应的 sys_dictionary：

Tool: SN-Query-Table
Parameters:
  table_name: sys_dictionary
  query: name=[table_name]^internal_type=reference
  fields: element,column_label,reference
  limit: 50
范围权限错误

症状： 无法访问其他范围内的构件 原因： 未授予跨范围访问权限 解决方案：

Tool: SN-Query-Table
Parameters:
  table_name: sys_scope_privilege
  query: target_scope=[scope_sys_id]^status=allowed
  fields: source_scope,target_scope,type,operation
  limit: 20

示例

示例 1：概述自定义 HR 应用
# Step 1: Find the application
Tool: SN-Query-Table
Parameters:
  table_name: sys_scope
  query: nameLIKEHR Onboarding
  fields: sys_id,name,scope,version,vendor
  limit: 5
# Result: sys_id = "scope123", scope = "x_acme_hr_onboard"

# Step 2: Get all artifacts
Tool: SN-Query-Table
Parameters:
  table_name: sys_metadata
  query: sys_scope=scope123
  fields: sys_id,sys_class_name,sys_name
  limit: 500

# Step 3: Get tables
Tool: SN-Query-Table
Parameters:
  table_name: sys_db_object
  query: sys_scope=scope123
  fields: sys_id,name,label,super_class
  limit: 20

# Step 4: Get scripts
Tool: SN-Query-Table
Parameters:
  table_name: sys_script
  query: sys_scope=scope123
  fields: sys_id,name,collection,when,active
  limit: 100
示例 2：比较两个应用版本
# Get artifacts for version 1.0
Tool: SN-Query-Table
Parameters:
  table_name: sys_metadata
  query: sys_scope=[scope_v1_sys_id]
  fields: sys_id,sys_class_name
  limit: 500

# Get artifacts for version 2.0
Tool: SN-Query-Table
Parameters:
  table_name: sys_metadata
  query: sys_scope=[scope_v2_sys_id]
  fields: sys_id,sys_class_name
  limit: 500

# Compare artifact counts by type between versions
示例 3：识别特定供应商的所有应用
Tool: SN-Query-Table
Parameters:
  table_name: sys_scope
  query: vendor=Happy Technologies LLC^active=true
  fields: sys_id,name,scope,version,sys_created_on
  limit: 50

相关技能

  • genai/app-generation - 根据需求生成新应用
  • development/code-review - 检查应用脚本的质量
  • development/code-assist - 为现有应用生成新脚本
  • admin/update-set-management - 打包和部署应用
  • security/acl-management - 详细分析 ACL

评论

支持 Markdown