uipath-connector-builder

连接器构建器

使用 uip is connectors builder 在磁盘上创作 UiPath Integration Service 连接器，然后通过父级 uip is connectors 执行 import + publish。连接器是一个 periodic-* 仓库（官方连接器使用 periodic-uipath-{vendor}-{product}；自定义连接器使用 periodic-design-{org}-{slug}；init 会根据 --name + --organization 推导出 design-{org}-{slug} 元素键），其核心是 app/element/element.json、standard-resources/*.json 和 JavaScript hooks/。连接器封装仅返回 JSON 的 REST API——不支持 SOAP、GraphQL 或 XML。术语：创作时使用的名词是活动（映射到 element.json 资源和一个 standard-resource 文件）。

何时使用此技能

• 根据供应商的 API 文档创建新连接器（init → auth → activities → validate → import → publish）。
• 编辑现有连接器：添加活动、字段、参数、方法或钩子。
• 配置或切换身份验证方式（OAuth2、PKCE、客户端凭证、API 密钥、基本身份验证、JWT、AWS v4 等）。
• 编写或修复 JavaScript 请求／响应钩子。
• 为现有活动接入轮询或 webhook 触发器。
• 调试 element.json／standard-resource 文件中的连接器、活动、钩子或触发器问题。
• 发布前进行验证，或向租户拉取／推送设计连接器。

关键规则

1. 编辑前先检查。 对任何现有连接器，先运行 builder inspect，了解身份验证、配置、活动、钩子和触发器。切勿盲目编辑。切勿臆造配置键、活动路径或 ID——先读取状态（inspect、activity list、state query）。
2. 结束前先验证。 每个工作流结束时以及每次修复后都运行 builder validate——它会运行完整的定期检查集，失败时以非零状态码退出。如果失败，读取报告中指出的字段，修复该条目，然后重新验证。针对同一错误失败 3 次后就停止，并展示 validate 输出——不要继续猜。不要只看“0 errors”就停下：也要阅读 WARNINGS——它们指出仍会随连接器交付的实际缺陷，可能导致连接器只完成了一半（例如没有字段的活动、失效的 SR 链接）。除非你能说明某条警告为何可以接受，否则必须修复。
3. auth set 负责所有身份验证。 它一次调用即可写入配置项、authentication.type / typeOauth / authenticationTypes，以及令牌刷新资源。也在此处定义作用域（--scope、--scope-options、--required-scopes、--preselected-scopes）——没有单独的作用域命令。init --auth oauth2|customApiKey 是创建时常见情况的内联简写；其他所有情况都通过 auth set 处理。切勿通过 state patch 手动拼接身份验证。
4. activity create 一次调用会写入两处内容——标准资源文件，以及每个方法对应的一条 element.json 条目。在已有活动上重新运行时会追加/合并。仅对不需要 SR 文件的系统资源传入 --skip-sr（或使用 auth system create）。只有对于确实按 ID 操作的端点，才建模 GETBYID / PATCH / PUT / DELETE——绝不能用于搜索。按 ID 操作的 /{id} 路径参数会自动添加：GETBYID 始终添加；PATCH / PUT / DELETE 仅在该活动属于 CRUD（也包含 GET / GETBYID）时添加；仅写入/操作类活动则保留其基础路径。按 ID 操作的路径令牌与主键是两回事——请求离开我们这边之前会替换路径令牌（供应商看不到其名称），而主键是从供应商响应中读取的字段名称。--vendor-path 末尾的 {token} 不会被用作主键；请传入 --primary-key <供应商响应中的键>。
5. state patch 会替换指针所指向的整个节点（不会合并）。 如需修改单个字段：先用 state query 查询条目，编辑后再用 state patch 写回完整对象。element-metadata.json 没有可寻址的子路径——必须整体读取并写回。指针中的活动路径需进行 URL 编码：/contacts → %2Fcontacts。创建内容时使用专用的编写命令，不要用 state patch。
6. 连接器定位。 Builder 命令会先从当前工作目录向上查找，再扫描紧邻的子目录，最后回退到 init 在其运行目录中写入的 .uip-connector.json 标记——因此在同一目录运行后续命令时，即使旁边还有其他连接器目录，也会自动操作最近一次 init 的连接器。要覆盖此行为，或从其他位置操作时，请传入 --connector-dir <PATH>。import 也会以相同方式读取 --connector-dir（其中应是包含 app/element/element.json 的连接器根目录）；但对于 download，它指定的是写入下载连接器的输出目录。例外——init 不会扫描子目录（否则可能定位到同级连接器并悄悄对其进行编辑/重命名）：要创建连接器，请在全新/空目录中运行 init（仅包含连接器子目录的目录——例如 /tmp——会创建新连接器，不会深入子目录编辑）；要编辑连接器，请在连接器目录内运行，或传入 --connector-dir。
7. 输出采用 {Result, Code, Data} 信封格式。 添加 --output json 以便解析。失败时以非零状态码退出。切勿抑制 stderr。
8. import / download / publish，以及创建连接器时的 init，都需要 uip login。 在从租户拉取/推送任何内容之前先完成身份验证。新连接器的键 design-{org}-{slug} 中的组织来自已登录会话，因此未登录时创建连接器的 init 会报错。让它自动推导组织；不要传入猜测的 --organization（错误的组织会写入键中，直到导入/发布时才以不匹配的形式显现）——--organization <slug> 仅用于已知组织的离线/CI 构建。
9. 绝不要回显、记录或硬编码密钥。 密钥配置项（客户端密钥、API 密钥、密码、令牌）由 auth set 加密写入（encrypt: true）——大多数为 PASSWORD 字段，但有些（OAuth 令牌、服务账号 JSON）会加密为 TEXTFIELD / TEXTAREA。最终用户在连接时提供真实凭据；连接器只保存身份验证类型、端点 URL 和作用域。所有示例命令都使用占位符。
10. 优先使用内置功能，而非钩子。 编写 JS 前，请查阅决策表（references/hooks.md §“先做决定：使用钩子还是内置功能？”）——只有在没有声明式功能可实现时，才用钩子处理转换、编排或推导。每个活动、方法和阶段分别使用一个钩子文件；钩子在 Denali 中运行（支持现代 JS，并可通过 require('axios') 进行辅助调用），且每条路径都必须以 done() 结束。
11. Windows + Git Bash：先禁用 MSYS 路径转换。 在 Git Bash 中，任何以 / 开头的参数都会在 CLI 接收到之前被改写为 Windows 路径——--vendor-path /latest 会以 C:/Program Files/Git/latest 的形式写入 element.json，validate 会通过，连接器也会发布，但直到针对供应商发出请求时才会失败，而且本地没有任何线索。每个 Shell 只需导出一次 MSYS_NO_PATHCONV=1 和 MSYS2_ARG_CONV_EXCL='*'（或在每条 builder 命令前添加它们）。这会影响所有路径选项——--vendor-path、--resource-path、--method-vendor-path、--reference-path、--validation-vendor-path、--path、--polling-url。加引号也无济于事（Shell 移除引号后才会执行改写）。如果连接器中已有被篡改的路径，请用 state patch 修复。
12. 为每个活动编写字段架构——activity create 不会推断字段。 没有字段的活动在 Studio Web 中会呈现为输入单个原始 JSON 请求体并输出原始 JSON，没有任何类型化输入/输出——这是一个只完成了一半的连接器，但它仍能通过验证并发布，因此很容易漏掉（这是反复出现的问题：“已经验证通过并发布了”，却跳过了架构）。运行 activity create 后，始终根据供应商文档中的架构定义请求/响应字段——要么在 activity create 中传入 --fields-file <json> 一次性提供完整架构，要么用 activity field create 逐个添加。对于没有字段的活动，validate 会发出 WARNING——必须修复。绝不要将包含无字段活动的连接器报告为“已完成”；如果确实有意采用原始请求体直通，请明确说明。
13. 图标在深色背景上必须清晰可见。 app/element/image.svg 是连接器在 Studio Web 中使用的图标。builder validate 不会检查这一点（仅在文件缺失时发出警告），但如果图标的墨色与 Studio Web 深色背景（#1F1F1F）对比度低于 1.5:1，定期构建就会失败——例如黑色标志或没有 fill 的形状。添加或替换图标时，请根据 references/icon.md 中的规则进行检查。使用 @media (prefers-color-scheme: dark) 规则或 fill="currentColor" 修复黑色墨色。绝不要给品牌标志重新着色。

连接设计（主机、区域、发现的值）

在搭建脚手架之前，先决定每个连接值如何传递到请求中——这是最常导致返工的问题：

• 一个配置驱动主机，而不是三个 URL。 当基础主机、令牌主机和授权主机包含相同的连接专属部分（实例名称、区域、数据中心或工作区）时，只提供一个配置，并将其模板化后用于每个 URL：init --base-url 'https://{instance}.../api' + auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'。CLI 会自动创建一个可填写的 {instance} 字段，用于解析这三个 URL（参见 references/configuration.md §模板化主机）。不要将 base.url/oauth.token.url/oauth.authorization.url 作为单独的连接字段公开。
• 值开放 → TEXTFIELD；固定选项 → COMBO。 自由填写的实例／工作区／账户名称应作为自动创建的模板化 TEXTFIELD——这是合理且常见的设计，并非异味。只有数据中心／环境确实是固定列表时，才使用 COMBO（通过 state patch 将已创建的条目修改为 type:COMBO 并添加 options，其 value 可以是主机片段本身）。
• 先推导或发现，再向用户询问。 如果连接专属值（API 主机、组织／账户 ID）会在令牌响应中返回，或可通过已认证的调用发现，就应获取该值，而不是添加手动填写的字段——但前提是确实需要该值且能够获取；默认情况下，单个模板化配置更简单，因此无需在普通字段足以解决问题时过度设计发现流程。令牌响应中的主机 → 使用 postRequest hook 验证（https + 主机允许列表，绝不记录令牌），并通过 done({configuration}) 持久化——示例：references/hooks.md §“模式：基础 URL …”。可发现的 ID → 使用 onProvision 系统资源，在建立连接时调用查询接口（references/system-resources.md）。
• 面向用户的配置需要说明。 每个 configScreenType:"pre" 或 "pre-optional" 字段都应有 hintText，提供示例或说明值的查找位置。为每个在连接表单中可见的字段提供提示（validate 目前不会检查这一点），例如实例／工作区 ID、租户主机，以及令牌类型专属凭据。
• 多数据中心 OAuth： 账户／令牌主机本身会随区域变化——也要将区域配置模板化并用于 --token-url/--authorization-url，而不只是基础 URL。

工作流

每个工作流都是一组有序、可直接复制粘贴的命令。使用占位符（<ORG>、https://api.example.com）——绝不要使用真实密钥。

新建连接器（完整生命周期）

# 0. Log in FIRST. The key `design-{org}-{slug}` takes its org from your logged-in
#    session, so `init` (create) ERRORS if you're not logged in. Let it derive the
#    org — do NOT guess --organization (a wrong org bakes into the key and only
#    surfaces, mismatched, at import). --organization <slug> is for offline/CI only.
uip login status            # check Data.Status == "Logged in" — NOT the envelope
                            # Result/exit, which is "Success" even when the session
                            # is dead (refresh-failed / expired). (`init` create
                            # itself re-checks the live login status and blocks.)

# 1. Scaffold the shell. --name is required when creating; key + folder are derived
#    (the org comes from your login — see step 0).
uip is connectors builder init --name 'Acme Widgets' \
  --description 'Acme Widgets connector' --categories 'CRM,Sales and marketing' \
  --base-url https://api.acme.com --auth oauth2 \
  --authorization-url https://acme.com/oauth/authorize \
  --token-url https://acme.com/oauth/token --scope 'read write'
#   --categories must be approved DISPLAY-NAME values (e.g. 'CRM', 'Sales and marketing',
#   'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like `crm,sales`.
#   Validated at init AND `validate`: wrong case is canonicalized, an unknown value fails fast
#   and the error lists the approved enum. init seeds element-metadata.json:latestVersion = "1.0.0".

# 2. Add an activity (writes element.json entries + standard-resources/accounts.json).
uip is connectors builder activity create --name accounts --vendor-path /v1/accounts \
  --methods GET,GETBYID,POST,PATCH,DELETE --primary-key id --has-ceql

# 3. Author the field schema — REQUIRED, not optional (Rule 12). `activity create`
#    does NOT infer fields; without this the activity ships as a raw JSON body and
#    `validate` warns. Pass `--fields-file <json>` on `activity create` for the whole
#    schema at once, or add fields one at a time with `field create`
#    (visibility flags apply to every --method listed; re-runs merge):
uip is connectors builder activity field create --resource accounts --name email \
  --type string --method GET --method POST --response

# 4. Replace the placeholder app/element/image.svg with the vendor's logo, and check
#    it stays visible on a dark surface (Rule 13). validate does not check this.

# 5. Validate — must be 0 errors AND no unresolved warnings (fieldless activity,
#    broken SR link) before import.
uip is connectors builder validate

# 6. Import (create-or-update on the tenant) then publish.
uip login
uip is connectors import
uip is connectors publish --wait        # blocks until SUCCESS; live in Studio Web then
                                        # (fire-and-forget without --wait: allow ~5-10 min)

发布全新的连接器无需 --version（init 已将版本设为 1.0.0）。重新发布现有连接器则需要更高版本——提高 element-metadata.json:latestVersion（或传入 --version 1.0.1）；服务器会拒绝相同版本。

向现有连接器添加活动

uip is connectors builder inspect --output json     # map what exists first
# research the vendor API, then:
uip is connectors builder activity create --name contacts --vendor-path /v1/contacts \
  --methods GET,GETBYID,POST --primary-key id --fields-file ./contacts-fields.json
uip is connectors builder activity field create --resource contacts --name status \
  --type string --method GET --response --searchable
uip is connectors builder activity hook create --resource-name contacts --method GET \
  --hook-type postRequest --custom-code-file ./contacts-postRequest.js   # optional response shaping (you write the JS)
uip is connectors builder validate

添加轮询触发器

trigger create 会创建 POLLING 触发器。目标活动必须已存在且有 SR 文件（否则 trigger create 会直接失败）。

uip is connectors builder activity list --output json    # confirm the activity exists
uip is connectors builder trigger create --resource-name accounts --event-kind polling \
  --updated-date-field LastModifiedDate --id-field Id     # seeds the event config + hasEvents flag
uip is connectors builder validate

每个 --event-kind 都必须指定 --updated-date-field——该命令始终会创建轮询循环。--event-kind polling|webhook|all（默认为 polling）仅用于选择配置组；webhook/all 会添加 webhook 配置键，但不会实现事件传递。Webhook 事件传递、轮询与 webhook 的语义，以及各标志的默认值均见 references/events.md。

自定义精选活动

默认情况下，activity create 会自动将每个方法精选为独立的 Studio 活动（使用 --no-curate 可关闭此功能）。仅在需要覆盖生成的 name/displayName，或为使用 --no-curate 的方法创建精选活动时，才使用 method curate。 通用 CRUD 活动始终与精选活动分开存在：List/Get/Create/Update/Delete Records 允许用户选择任何支持相应方法的对象。添加可精选/可列表的对象时，不要移除这些活动，也不要将其报告为污染；应在通用对象选择器旁添加精选服务操作。

uip is connectors builder activity method curate --resource cases --method GET \
  --display-name 'Get Support Request'
uip is connectors builder activity field create --resource cases --name subject --type string \
  --method GET --response --response-curated --design-position primary
uip is connectors builder validate

调试

uip is connectors builder inspect --output json
# state patch REPLACES the node — query the WHOLE entry, change ONLY the field at fault, patch it ALL back:
uip is connectors builder state query element.json/configuration/oauth.token.url --output json
uip is connectors builder state patch element.json/configuration/oauth.token.url \
  --value '<full entry from the query above, with defaultValue corrected>'
uip is connectors builder validate

对于在连接时确定的基础 URL 或 ID：如果令牌调用会返回该值，请使用令牌响应 postRequest hook；如果必须在身份验证后发现该值，请使用 onProvision 系统资源。验证该值，然后使用 done({configuration}) 持久化——不要使用 state patch，因为它会在构建时将一个连接的值写入所有连接。完整做法：references/hooks.md §“模式：基础 URL …”；排查清单：references/debugging.md。

命令索引

uip is connectors                      # tenant/catalog + design-connector lifecycle (needs `uip login`)
  list | get <key> | swagger <key> | export <key> | audit-logs | event-operations
  download <key> | import | publish | publish-status <id> | probe
  builder                              # author a connector ON DISK
    init                               # create-or-EDIT the connector shell in ONE verb
                                       #   (folds the old scaffold / metadata / global / base+pagination preset)
        preset apply --kind base|pagination
        header delete <vendorName>
    auth     set | get | system (create|list)
    activity create | list | get | delete
             field  (create|list|get|delete)
             method (get|set|curate)
             param  (create|list|get|delete)
             hook   (create|list|get|delete)
    trigger  create                    # --event-kind polling|webhook|all (folds the event preset + polling)
    inspect                            # read-only whole-connector rollup
    validate                           # full check set; exits non-zero on failure
    state    query <pointer> | patch <pointer>

publish 会返回一个 PublishId；--wait 会轮询至 SUCCESS/FAILURE（通过 --timeout-seconds 设置超时，默认值为 600）；之后可通过 publish-status <id>（位置参数）查看状态。状态枚举：IN_PROGRESS | SUCCESS | FAILURE。

参考文档导航

详细内容位于 references/ 中——每篇文档均可独立阅读。SKILL.md 负责工作流、命令索引和上述规则；参考文档不得重复这些内容。始终最新的标志来源是 uip is connectors builder <noun> <verb> --help。

任务 → 阅读此文档	参考文档
什么是连接器、文件布局、CRUD/精选/HTTP 活动模型	references/overview.md
连接器图标（image.svg）：周期性构建如何判断其在深色表面上的可见性，以及修复方法	references/icon.md
element.json 内部结构：顶层字段、resources[]、parameters[]、值插值、hook 顺序	references/element-json.md
标准资源文件：链接、metadata.method、精选、字段（可见性/设计/可搜索）	references/standard-resources.md
configuration[] 条目：widget 类型、屏幕类型、各身份验证的键集合、分页及事件键	references/configuration.md
身份验证设置：全部 19 种身份验证类型（包括 JWT Bearer 声明、FPS、none）以及 OAuth/JWT 作用域范围	references/auth.md
身份验证系统资源：auth-validation、onProvision/onDelete、OAuth 令牌覆盖	references/system-resources.md
何时编写 hook，何时使用内置功能（决策表 + 推荐/应避免的模式）、执行顺序、上下文变量、done()、命名	references/hooks.md
轮询和 webhook 触发器：配置键、event.poller.configuration 架构	references/events.md
调试身份验证/活动/hook/触发器/分页问题（工作流 + 排查清单）	references/debugging.md

反模式

1. 未先运行 builder inspect 就开始编辑（规则 1）——你会自行编造不存在的键或路径。
2. 用 state patch 手动处理身份验证，而不是使用 auth set（规则 3）——这会导致身份验证区块前后不一致。
3. 使用不完整的值编辑配置项（规则 5）——state patch 会替换整个节点，丢弃未提供的字段。先查询完整配置项，再将完整对象写回。
4. 本想创建一个独立活动，却用已存在的名称重新运行 activity create——这是幂等的新增或更新操作，会合并到同名活动中（追加方法；除非指定 --overwrite-fields，否则保留现有字段定义）；它不会报错，因此名称错误时会静默合并，而不会发出警告。
5. 将 GETBYID 用于搜索或列表端点（规则 4）——按 ID 查询的动词会自动添加 /{id} 参数；仅将其用于真正的单条记录读取。
6. 在示例中填入真实密钥，或以为连接器会存储密钥（规则 9）——密钥是加密字段（通常为 PASSWORD），在建立连接时提供。
7. 重新发布却不提升版本号——服务端会拒绝相同版本号；请提升 latestVersion 或传入 --version。
8. 编造 --categories 的值——值必须来自已批准的枚举；validate 会报告可用列表。
9. 为内置功能已能完成的任务编写钩子（规则 10；hooks.md §“Recognizing an avoidable hook”），或遗漏末尾的 done()，导致钩子无法返回。
10. 使用已移除的命令——没有 connector scaffold/inspect/validate 封装命令（请直接使用 init/inspect/validate），也没有 global/metadata/config/resource*/event polling add/auth scope/remote*/describe/reference。
11. 字段命名——尤其是主键——时，使用 URL 路径标记或自定义约定，而不是供应商实际返回的键。响应字段会按名称与供应商原始 JSON 匹配，因此名称错误会导致活动输出为空，且任何层都不会报错（standard-resources.md §fields）。
12. 活动没有字段却宣称连接器已“完成”（规则 12）——activity create 会写入端点、方法和身份验证信息，但不会写入字段架构；没有 field create / --fields-file 的活动在 Studio 中只会显示原始 JSON 正文，并触发 validate 警告。完成前先定义字段，切勿将 0 个错误但带有警告的验证结果视为通过。
13. 发布黑色或未填充的图标（规则 13）——它能通过 validate，但随后会在 Studio Web 的深色背景上消失，并导致定期构建失败。请添加 prefers-color-scheme: dark 规则或使用 currentColor。