Splunk Setup Page Builder 是来自 splunk/splunk-agent-skills 的技能，用于为 Splunk 应用或附加组件构建首次运行设置页面。该页面在用户首次启动应用时显示，收集应用运行所需的配置，例如端点 URL、API 令牌、功能开关等，并避免使用已废弃的 setup.xml 机制。
用途
当用户构建的 Splunk 应用或附加组件需要用户先提供配置才能运行，且希望提供规范的“Set up your app”体验而非安装后手动编辑 .conf 文件时，使用此技能。常见配置包括 API 端点、凭证或令牌，以及一小组功能设置。技能明确不适用于使用 default/setup.xml 的场景，因为该机制已废弃，在 Splunk Cloud Platform 和搜索头集群上不受支持，并且会直接导致 Splunk AppInspect 的云检查（check_setup_xml_in_default）失败。任何需要首次运行配置且希望兼容 Cloud 的应用，都必须改用通过 app.conf 的 [install] is_configured 和 [ui] setup_view 连接的设置视图（Simple XML 或 React）。
前提条件
需要一个 Splunk 应用目录，可以是已有应用，也可以是用 default/app.conf、default/data/ui/ 和 metadata/default.meta 新建的应用。目标平台为 Splunk Enterprise 9.x+ 或等效版本的 Splunk Cloud Platform。编写文件不需要本地 Splunk 实例，但验证时必须安装到真实实例中。本地需安装 splunk-appinspect 用于静态校验（pip install splunk-appinspect；macOS 上可能还需要 brew install libmagic 才能正常导入）。
架构与存储
技能给出了应用目录结构，包含 app.manifest、default/app.conf、default/data/ui/views/ 下的设置视图和 home.xml、nav/default.xml、metadata/default.meta、appserver/static/ 下的 JavaScript 与 CSS，以及 README/ 下的 .conf.spec 文件。存储后端按字段类型区分：非敏感设置（URL、开关、间隔等）使用内置 configurations REST 集合，写入自定义的 <name>.conf 文件，无需自定义 Python REST 处理器，开箱即用且 Cloud 安全；敏感信息（令牌、密码、API 密钥）使用 storage/passwords，由 Splunk 加密存入 passwords.conf，绝不可将敏感信息写入普通 conf 文件，否则会成为 AppInspect 失败项并带来真实安全风险。
工作流
技能将工作流分为多个步骤。首先收集需求，确认应用 id 与目录、哪些字段是非敏感设置与敏感信息及其名称、类型、必填性与校验规则，以及应用是否已有其他视图、是否已有设置页面。然后配置 app.conf，设置 is_configured、package id、ui 的 setup_view、launcher 信息以及每个自定义 conf 文件对应的 [triggers] reload 行。接着构建设置视图（Simple XML 加 JavaScript），使用 Splunk JS SDK，技能建议直接复制 references/setup-page.js 并适配字段名与校验，不要从零重写 SDK 连接逻辑。之后再添加最小化的 home 视图与导航，避免用户在设置完成后落入实例上其他共享仪表板。随后在 metadata/default.meta 中设置权限，需包含 sc_admin。再添加 app.manifest，最后为自定义设置文件编写 .conf.spec 文档。
已知缺陷
技能指出两个经端到端测试发现的真实问题。第一是仅检查存在或前缀的弱校验：例如 /^https?:/// 会认为没有主机名的 http:// 是有效 URL，修复方式是要求主机名，如 /^https?://[^\s]+..+/i，并应对每个字段按实际格式编写真正的模式或范围校验。第二是不要在提交时以 is_configured 作为保存门槛：Splunk 官方示例会在提交处理顶部检查 is_configured，若已为 1 则直接跳过保存并重载跳转，这会导致用户后续重新打开设置页面轮换令牌或更改设置时输入被静默丢弃。提交处理必须无条件执行保存逻辑，不得添加任何形式的提前退出保护。
验证
技能强调静态分析不足以证明正确性，需要同时进行 AppInspect 检查（test 与 precert 模式，期望 0 错误/失败）和真实 Splunk 实例的手动验证。手动验证至少包括：全新安装且 is_configured=0 时确认跳转到设置页面；必填字段为空时确认校验阻止提交且不发出 REST 调用；提交满足“非空”但不符合真实格式校验的值时确认仍被拒绝；以及提交有效值。未经明确确认，不得安装或重新配置生产或共享 Splunk 实例，也不应要求用户提供原始 Splunk 管理员凭证。
使用限制
该技能保持范围聚焦于构建设置页面本身。相邻需求应路由到其他技能，例如应用打包与生命周期咨询、共享知识对象治理、HEC 数据摄入设置与排障、字段提取与 CIM 映射或即席 SPL，以及一般 Splunk 产品问题。自定义 conf 文件的类型与约束不会被 configurations REST 端点强制执行，客户端 JS 校验仅改善设置页面体验，任何后续消费这些值的后端代码或模块化输入都必须重新校验。