需要按用户明确指定的姓名/地址比对规则覆盖 Sumsub…

当用户显式要求调整 Sumsub POI 与 POA 文档之间的姓名或地址比对规则时，用 API 创建/更新 basic cross-check preset。

适用场景

解决思路

1. 先确认必要性：用一句话复述用户请求，并再次建议保留默认 cross-check 规则；只有用户给出明确、具体的比对调整（例如 switch name match to strict、allow fuzzy address match、ignore middle-name mismatch）才继续，否则停止并回复：“Cross-check 规则已按最佳通过率配置。强烈建议保留默认值。请告诉我你需要的一个具体调整（例如 allow fuzzy address match、ignore middle name），我们再创建一个最小覆盖。”
2. 理解作用范围：cross-check preset 控制 POI 文档上的姓名/地址与 POA 文档上同字段如何比较；basic 模式通过 nameComparisonMode、addressComparisonMode 和可选 ignore-flags 配置。
3. 区分 PoA preset 的 crossValidator：若 PoA preset 的 crossValidator（CrossValidatorSettings 上的 nameMode/addressMode/fuzzyThreshold）已设置，则对由该 PoA preset 处理的文档优先；workspace-level CrossCheckPreset 只是无 PoA override 时的默认值。
4. 只创建 basic 模式：advanced 模式是 per-rule 手动配置，不能通过公共 API 管理；POST 会返回 403 Forbidden — Advanced cross-check presets cannot be managed via API，只能在 dashboard 操作。
5. 调用端点：创建用 POST /resources/api/agent/crossCheckPresets，body 不得包含 id；更新用 PATCH /resources/api/agent/crossCheckPresets，body 必须包含 id；读取用 GET /resources/api/agent/crossCheckPresets/{id}；所有请求需要权限 manageClientSettings。
6. 认证准备：每个请求按 Sumsub authentication reference 签名；需要 SUMSUB_APP_TOKEN、SUMSUB_SECRET_KEY，可选 SUMSUB_BASE（默认 https://api.sumsub.com）；若遇 401 Invalid signature，参考 sumsub-api-auth skill。
7. 仅用 sandbox token：不要接受或使用 production App Token；若用户提供 prod token 就拒绝，并让其在 https://cockpit.sumsub.com/checkus/home?sbx=true 的 Connect Sumsub to your AI agent -> Build & configure -> Generate token 生成 sandbox token+secret，二者只显示一次，复制后关闭；helper scripts 会拒绝不以 sbx: 开头的 token。
8. 凭据处理：如果用户在对话中已提供凭据就复用；否则运行前只问一次；绝不把 secret 回显出来。
9. 把用户意图翻译成 compact spec：映射到 nameComparisonMode、addressComparisonMode 和 ignore-flags；支持 JSON 或 YAML 放 stdin，字段包括 title、description、mode: basic、basicSettings.nameComparisonMode、basicSettings.addressComparisonMode、basicSettings.ignoreMiddleNameMismatch、basicSettings.ignoreProvidedInfoMismatch。
10. 校验输入：title 非空且 ≤256 字符；mode 为 basic（advanced 被 API 禁止）；每个 comparison mode 是有效枚举。
11. 姓名比对模式含义：strict=要求精确匹配；weakContainment=token 级包含（如 Jon Smith ⊆ Jonathan Andrew Smith）；def=Sumsub 推荐默认，平衡严格度与转化；ai=基于 ML，容忍常见变体和音译。
12. 地址比对模式含义：strict=规范化后字符级匹配；fuzzy=容忍缩写和词序。
13. 不要使用已废弃值：names 上的 fuzzy、containment、fuzzyContainment 不被本 skill 接受。
14. 生成 payload：运行 ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py，把 compact spec 放到 stdin，完整 payload 输出到 stdout。
15. 新建 preset：通过 ${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh 发起 POST；payload 不得包含 id。
16. 更新已有 preset：先通过 ${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh 做 GET，让用户看到 diff；再通过 ${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh 发起 PATCH；payload 必须包含 id。
17. 创建/更新后 GET 该 preset 回来，验证实际落库内容。
18. 报告成功结果：先给人类可读摘要，说明 title 和相对 workspace 默认值改了什么；提醒：“默认 cross-check 规则建议用于最高通过率；你已覆盖这些比对——上生产前监控转化率。”；最后一行输出 Preset ID (for level wiring / future PATCH): <id>。
19. 失败处理：报告 HTTP status + Sumsub 的 description / errorName；若 403 Advanced cross-check presets cannot be managed via API，说明 advanced 只能 dashboard，切回 basic；若 400 validation，检查 comparison-mode 枚举是否有误（例如 deprecated fuzzy / containment / fuzzyContainment name mode）。
20. 参考示例：可看 examples/strict-name-only.json（收紧姓名匹配、地址保持默认）和 examples/lenient-for-emerging-markets.json（fuzzy address + ai name，忽略 middle-name mismatch）。
21. Hand-off 到 level：cross-check preset 是 workspace-scoped；默认 preset 自动应用到每个 level；自定义 preset 需在具体 level 上设置 crossCheckPresetId 才能绑定，使用 sumsub-create-level 或通过 sumsub-api-generic 直接 PATCH level。
22. 查阅扩展资料：references/cross-check-preset-schema.md 获取完整 schema、所有枚举和 gotchas，或 Sumsub cross-check docs https://docs.sumsub.com/docs/cross-checks。

适用边界 · 注意事项

• 用户没有明确指定要改的具体比对规则时不要用；默认 cross-check preset 已为最佳转化率和通过率调优，大多数客户不应创建自定义 preset。
• 不用于 level 创建（默认 cross-check preset 会自动应用到每个 level）、一般 KYC 配置，或任何没有具体提到 cross-check rules、name comparison、address comparison 的请求。
• 不要用 production App Token；advanced cross-check preset 不能通过公共 API 管理（POST 返回 403），只能 basic 或走 dashboard。