SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场writing-settings-forms

writing-settings-forms

办公与效率

查看项目

更新于 10-22 11:02

技能介绍

用途

writing-settings-forms 用于指导在 Celigo 中编写设置表单（settingsForm）。设置表单是 Celigo UI 渲染出来收集某个资源配置项的界面，决定哪些字段出现、字段的标签与选项、如何分组、何时显示。表单收集的值保存在同一资源的 settings 中，这正是运行时步骤读取的内容：模板中写 {{settings.flow.region}}，脚本中写 options.settings.flow.region。

承载表单的七个位置

表单可出现在七处，各自拥有独立的 settings：

  • 集成（Integration）
  • 集成的每个流组（flowGroupings[]）
  • 流（Flow）
  • 导出（Export，含 lookup）
  • 导入（Import）
  • 连接（Connection）
  • iClient

Integration App 的设置属于另一套机制，由其自身代码驱动。

表单不是什么

  • 不是校验：只有 UI 渲染表单并执行其规则。通过 API、CLI 或 MCP 写入 settings 时，给定对象会被直接存储——表单标记为必填的字段可以缺失，表单未定义的键会被保留，类型与选项不做检查。
  • 保存时不检查：布局条目或条件引用了表单中不存在的字段，会按原样存储。settingsForm 只保留 form 与 init，其他顶层键会被直接丢弃且不报错。
  • 不是步骤读取的内容：步骤读取的是 settings，而不是表单。新增字段在值写入 settings 之前对步骤毫无作用，因此写字段时应同时写入对应的值。

使用方式

该技能按“读取或修改什么”命名每个步骤，具体调用取决于访问账户的方式，需参阅对应参考文档：

  • Celigo MCP 工具（list_integrations、upsert_integration、upsert_flow、upsert_export 等）：表单只能通过整体替换的 upsert_* 工具写入，且无法运行 init 脚本或预览下拉框的导出。
  • celigo CLI。

读取资源只是读取；写入表单或其 settings 会更新资源，而完整更新会替换整个文档——省略 settingsForm 或 settings 的请求体会将其抹除。

作用域与读取路径

各作用域中，表单与值分别位于 settingsForm 与 settings，步骤读取方式为：

  • 集成：settings.integration.<name>，在该集成的所有流中可用
  • 流组：流组条目上的 settingsForm 与 settings，读取为 settings.flowGrouping.<name>
  • 流：settings.flow.<name>
  • 导出：settings.export.<name>，仅在该步骤
  • 导入：settings.import.<name>，仅在该步骤
  • 连接：settings.connection.<name>，在使用该连接的步骤中
  • iClient：settings.iClient.<name>，在其连接使用它的步骤中

作用域键是字面量：{{settings.region}}（不带作用域）以及由字段标签或分组名拼出的路径都会渲染为空。作用域之后按存储的 JSON 逐层展开，每个嵌套键增加一段路径。

步骤能看到哪些作用域取决于运行方式：

  • 流运行时给出完整链路：集成、流组、流、连接、iClient，以及该步骤自身的作用域。
  • API 或 Tool 中的步骤只得到自身作用域加连接和 iClient；集成、流组、流解析为空。
  • 单独运行的步骤（无父级的导出或导入调用）只得到自身作用域。

应选择所有读取该值的步骤共有的最窄作用域。

表单结构

settingsForm 包含 form（以及可选的 init）。form 下含 fieldMap 与 layout：

  • fieldMap 中每个条目定义一个字段，key、id、name 使用同一字符串。name 是值在 settings 下保存的键，id 供布局与条件引用。应使用不含点的普通键，因为 UI 会把 a.b 保存为嵌套对象却从扁平的 a.b 键读回，导致字段重新加载时为空。
  • 字段属性包括：type（控件类型）、label、description、helpText、required（仅阻止 UI 保存，API 写入不受限）、defaultValue、options（select、multiselect、radiogroup 的选项；toggle 使用裸 {label, value} 条目）、visibleWhen 等条件、omitWhenHidden（为 true 时隐藏字段的值不保存）。

字段类型

技能列出的类型包括：text（multiline、inputType、delimiter）、checkbox、toggle、select、radiogroup、multiselect、date、datetime、relativeuri、editor（json/xml/csv/text 模式）、keyvalue、staticMap、exportSelect，各类型对应其保存值形式（字符串、布尔、数组等）。

条件

条件规则形如 {"field": "<field id>", "is": [<values>]} 或 isNot。两个集合值按字符串比较。visibleWhen 在任一规则匹配时显示字段，visibleWhenAll 需全部匹配；requiredWhen / requiredWhenAll 与 disabledWhen / disabledWhenAll 类似地使字段必填或只读。规则内可嵌套 "AND" / "OR"。引用不存在的字段时，visibleWhen 视为匹配，而 requiredWhen 与 disabledWhen 视为不匹配。

布局

form.layout 负责排列字段；未被布局列出的字段不会显示。布局含 type、containers，以及可选的 fields。type 决定容器渲染方式：column（并排）、collapse（可折叠分区）、box（带边框分组）、indent（缩进分组）、tabWithoutSave 与 verticalTabWithoutSave（标签页）。每个容器有 label 与 fields，并可用自身 type 与 containers 再嵌套一层。

初始化脚本

settingsForm.init（{"_scriptId": "<scriptId>", "function": "<name>"}）在 UI 每次打开表单时运行脚本函数。UI 渲染函数返回的表单而非 settingsForm.form，再用 settings 填充值；抛出异常则在表单位置显示其消息。函数接收 options.resource、options.sandbox，集成与流组还会得到父资源（parentResource、grandparentResource）；options.license 与 options.parentLicense 仅在 Integration Apps 中出现。脚本必须属于本账户，否则返回 422。iClient 不支持 init：平台表单初始化路由仅服务集成、流组、流、导出、导入和连接，iClient 表单带 init 会显示错误，而其保存会不经检查地存储任意 _scriptId。目前没有 CLI 命令或 MCP 工具调用 init 路由，需自行构造 options 通过 JavaScript 处理器运行测试。

动态字段：exportSelect 与 staticMap

exportSelect 是选项来自内联导出（resource.virtual）的下拉框。导出是导出体而非引用，无法通过 id 指向已保存的导出；需在 virtual 中提供 adaptorType、适配器块与可选 transform，缺少 resource.virtual 时字段显示 "requires export resource."。_connectionId 默认取表单所在导出或导入的连接，其他作用域需自行设置。UI 在表单打开与刷新时预览导出，最多读取 100 条记录；无记录或返回非列表时显示 "expecting array. try transform?"。multiselect: true 允许多选并以数组保存。supportHandlebars: true 会在每次预览前把导出体作为模板渲染（transform、hooks、filter 除外），但模板上下文与运行时不同。refreshOptionsOnChangesTo 实现级联下拉，typeAheadSearch 支持边输入边搜索（300 毫秒后触发）。

staticMap 是两列表格，以行为数组保存在字段名下。keyName / valueName 命名列，keyLabel / valueLabel 为列标题。keyOptions / valueOptions 提供建议列表但仍可输入。keyResource / valueResource 用内联导出填充建议（不做模板化）；设置其一后两列均必填，除非 keyValueRequired: false。步骤读取整个数组。

构建流程

  1. 确定作用域：谁读取该值，表单就放在所有读取者共享的位置。
  2. 读取资源：读取完整的现有 settingsForm、当前 settings 及完整更新需回传的全部内容；流组的表单与值在其 flowGroupings[] 条目中。
  3. 编写字段：每个设置一个 fieldMap 条目，选择类型、配置选项与默认值等。

适用场景与限制

该技能适合需要为 Celigo 资源设计配置界面的开发与集成人员。主要限制包括：表单不提供保存时校验，不保证 settings 与表单一致；步骤只读 settings；API、CLI 或 MCP 写入会按原样存储；iClient 不支持 init；MCP 无法运行 init 脚本或预览下拉导出；完整更新会替换整个文档，需回传全部内容以免误删。