sumsub-create-cross-check-preset

Sumsub — 创建 / 更新交叉核验预设

⚠️ 运行此技能前请阅读。

Sumsub 的默认交叉核验预设已针对转化率和通过率的最佳平衡进行调整。**大多数客户端不应覆盖此预设。**如果用户没有明确指出想要更改的具体比对规则，请停止并说明：

“交叉核验规则已配置为实现最佳通过率。 我们强烈建议保留默认设置。请告诉我你需要的具体调整（例如‘允许地址模糊匹配’或‘忽略中间名’），我们会创建最小范围的覆盖设置。”

只有在用户提出具体、明确的调整要求时才继续。

什么是交叉核验预设

交叉核验预设用于控制 Sumsub 如何比对**身份证明（POI）文件上的姓名和地址，与地址证明（POA）**文件上的相同字段。该预设决定是否接受细微差异（“Jonathan”与“Jon”、“Apt 4”与“Apartment 4”），或将其标记为不匹配。

不要与 PoA 预设的 crossValidator 混淆。sumsub-create-poa-preset 技能有一个名为 crossValidator 的内部区块（PoaDocumentSettings 上的 CrossValidatorSettings），其中包含 nameMode / addressMode / fuzzyThreshold——这是针对同一比对的单个 PoA 预设覆盖设置。工作区级别的 CrossCheckPreset（即本技能）会在没有适用的 PoA 预设覆盖设置时提供默认值。当某个 PoA 预设设置了 crossValidator，该设置对由此预设处理的文件生效。

有两种预设模式：

• basic — 本技能创建的模式。从少量枚举值中选择 nameComparisonMode 和 addressComparisonMode，并可选择忽略标志。适用于绝大多数用户。
• advanced — 手动配置每条规则。公共 API 不支持此模式（POST 返回 403 Forbidden — Advanced cross-check presets cannot be managed via API）。必须在仪表板中完成配置。

端点

方法	路径	用途
POST	/resources/api/agent/crossCheckPresets	创建新预设。请求正文不得包含 id。
PATCH	/resources/api/agent/crossCheckPresets	更新现有预设。请求正文必须包含 id。
GET	/resources/api/agent/crossCheckPresets/{id}	读取一个预设（验证实际生效的配置；从已知 id 解析 title）。

所有端点都需要 manageClientSettings 权限。请求正文结构遵循交叉核验预设架构——仅包含客户端可设置的字段。

身份验证 — App Token + 密钥（仅限沙盒环境）

本技能会调用 Sumsub 公共 API，并根据身份验证参考文档为每个请求签名。完整的工作原理说明位于 sumsub-api-auth 技能中——如果遇到 401 Invalid signature，请阅读该技能。

**⚠️ 仅限沙盒令牌。**请勿在此处接受或使用生产环境 App Token——交叉核验规则会影响工作区中的每次验证。如果用户提供生产环境令牌，请拒绝使用，并请他们在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成一对沙盒凭据（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。令牌和密钥只会显示一次——关闭对话框前请复制两者。辅助脚本会强制执行此要求——不接受以 sbx: 开头的令牌以外的令牌。

变量	示例
SUMSUB_APP_TOKEN	sbx:... — 从仪表板获取的沙盒 App Token。
SUMSUB_SECRET_KEY	创建令牌时显示一次的配对密钥。
SUMSUB_BASE	可选。默认为 https://api.sumsub.com。

如果用户已在对话中提供凭据，请重复使用；否则在运行前询问一次。切勿将密钥原样回复给用户。

流程

1. 确认必要性 — 用一句话重述用户的请求，并再次建议保留默认设置。如果用户指定了明确的调整项，则继续；否则停止。
2. 将用户意图转换为精简规范（见下文）。将用户的要求映射到 nameComparisonMode / addressComparisonMode / 忽略标志。
3. 验证 — title 不得为空（≤256 个字符）；mode 必须为 basic（API 禁止使用 advanced）；每个比较模式都必须是有效枚举值。
4. 生成载荷 — 将精简规范通过标准输入传给 ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py → 完整载荷从标准输出输出。
5. 创建还是更新：
   • 新预设 — 通过 ${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh 发送 POST 请求。载荷不得包含 id。
   • 更新现有预设 — 先通过 ${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh 发送 GET 请求，让用户查看差异，然后通过 ${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh 发送 PATCH 请求。载荷必须包含 id。
6. GET 预设并核实实际生效的内容。
7. 报告 — 先给出易读摘要，最后给出 id：
   • title 和一行说明相对于默认值做了哪些调整。
   • 提醒：“建议使用默认交叉核验规则，以获得最高的通过率；你现在已针对这些比较覆盖默认规则——请在投入生产前监控转化情况。”
   • 最后一行：Preset ID (for level wiring / future PATCH): <id>。

精简规范格式（通过标准输入传入 JSON 或 YAML）

title: "Strict address, lenient name"
description: "Allow nickname variants but require exact address."

mode: basic                          # ONLY basic — advanced is forbidden via API
basicSettings:
  nameComparisonMode: weakContainment  # one of: strict | weakContainment | def | ai
  addressComparisonMode: strict        # one of: strict | fuzzy
  ignoreMiddleNameMismatch: true
  ignoreProvidedInfoMismatch: false    # if true, don't flag user-typed info that disagrees with the doc

比较模式说明

nameComparisonMode：

• strict — 必须完全匹配。
• weakContainment — 基于词元的包含匹配（例如，“Jon Smith” ⊆ “Jonathan Andrew Smith”）。
• def — Sumsub 推荐的默认值，在严格度与转化率之间取得平衡。
• ai — 基于 ML 的比较，可容忍常见变体和音译差异。

addressComparisonMode：

• strict — 字符级匹配（规范化后）。
• fuzzy — 可容忍缩写和词序差异。

已弃用的值（姓名比较中的 fuzzy、containment、fuzzyContainment）无法通过此技能使用。

输出

成功时，先给出易读信息：

• title 和一行说明相对于工作区默认值做了哪些调整。
• 提醒：“建议使用默认交叉核验规则，以获得最高的通过率；你现在已覆盖默认规则——请在投入生产前监控转化情况。”
• 最后一行：Preset ID (for level wiring / future PATCH): <id>。

失败时：提供 HTTP 状态码，以及 Sumsub 的 description / errorName。常见原因：

• 403 Advanced cross-check presets cannot be managed via API — mode: advanced 只能通过控制台管理。请切换为 basic 模式。
• 400 并附带验证消息 — 某个比较模式枚举值有误（例如，姓名模式使用了已弃用的 fuzzy / containment / fuzzyContainment）。

示例

• examples/strict-name-only.json — 收紧姓名匹配，地址保留默认设置。
• examples/lenient-for-emerging-markets.json — 地址使用模糊匹配、姓名使用 ai，并忽略中间名不匹配。

后续步骤 — 将预设关联到级别

交叉核验预设的作用范围为工作区。默认预设会自动应用于每个级别；如果你创建了自定义预设，则必须通过在级别上设置 crossCheckPresetId，将其关联到特定级别。 这可以通过 sumsub-create-level（或通过 sumsub-api-generic 直接对级别发送 PATCH 请求）完成。

另请参阅

• references/cross-check-preset-schema.md — 完整架构、所有枚举值和注意事项。
• Sumsub 交叉核验文档。