用途
该技能用于在 Sumsub 工作区中创建或更新交叉核对预设（cross-check preset）。交叉核对预设控制 Sumsub 如何比较身份证件（POI，proof-of-identity）文档上的姓名和地址与地址证明（POA，proof-of-address）文档上的相同字段，决定细微差异（如「Jonathan」与「Jon」、「Apt 4」与「Apartment 4」）是被接受还是被标记为不匹配。
重要提示：Sumsub 默认的交叉核对预设经过调优，能在转化率与审批率之间取得最佳平衡。大多数客户不应覆盖它。如果用户没有指出具体的比较规则调整需求，应停止并说明默认规则已为最佳审批率配置，建议保留默认；只有用户提出具体、明确的调整（例如「允许地址模糊匹配」「忽略中间名」）时，才创建最小化覆盖。
与 PoA 预设的区别
不要与 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 权限。请求体为交叉核对预设 schema，仅包含客户端可设置字段。
认证（仅沙箱）
该技能调用公开 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。
如果用户已在对话中提供凭据，可复用；否则运行前询问一次。切勿回显密钥。
操作流程
- 确认必要性 —— 用一句话复述用户请求，并重申保留默认的建议。若用户有具体明确的调整则继续，否则停止。
- 将用户意图转换为紧凑规格（见下），映射到 nameComparisonMode / addressComparisonMode / 忽略标志。
- 校验 —— title 非空（≤256 字符）；mode 为 basic（advanced 通过 API 被禁止）；每个比较模式都是有效枚举值。
- 生成请求体 —— 用紧凑规格作为 stdin 运行 ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py，完整请求体输出到 stdout。
- 创建与更新：
- 新预设 —— 通过 ${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。
- GET 回来后核验落地结果。
- 报告 —— 先给出人类可读摘要，最后以 id 结尾：title 以及一句话说明相对默认调整了什么；提醒「默认交叉核对规则推荐用于最高审批率，你现已覆盖这些比较 —— 上线生产前请监控转化率」；最后一行：Preset ID (for level wiring / future PATCH): <id>。
紧凑规格格式（stdin 上的 JSON 或 YAML）
title: "Strict address, lenient name" description: "Allow nickname variants but require exact address."
mode: basic # 仅 basic —— advanced 通过 API 被禁止 basicSettings: nameComparisonMode: weakContainment # 之一：strict | weakContainment | def | ai addressComparisonMode: strict # 之一：strict | fuzzy ignoreMiddleNameMismatch: true ignoreProvidedInfoMismatch: false # 若为 true，不标记用户输入信息与文档不一致的情况
比较模式含义
nameComparisonMode：
- strict —— 要求精确匹配。
- weakContainment —— 词元级包含（例如「Jon Smith」⊆「Jonathan Andrew Smith」）。
- def —— Sumsub 推荐默认；在严格与转化之间平衡。
- ai —— 基于机器学习的比较；容忍常见变体和音译。
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 —— 完整 schema、所有枚举、注意事项。
- Sumsub 交叉核对文档。