需要创建或更新 Sumsub…

当用户要通过 Sumsub API 创建、配置或更新 POA preset（地址证明文档类型、有效期、POI-as-POA、跨校验、国家覆盖）时，用本技能生成并提交 preset。

适用场景

解决思路

1. 先确认目标 level 已有 PROOF_OF_RESIDENCE（或 PROOF_OF_RESIDENCE2/3/4）步骤；POA preset 只有挂到至少一个 level 的此类 docset 才生效。若用户尚未创建或描述包含 POA 步骤的 level，先提示，不要孤立创建预设。
2. 创建新 preset：POST /resources/api/agent/poaStepSettings；body 不得包含 id（由服务端分配）。
3. 更新已有 preset：PATCH /resources/api/agent/poaStepSettings；body 必须包含 id 字段（不是放在 URL）。
4. 回读单个 preset：GET /resources/api/agent/poaStepSettings/{id}，用于核验落库内容，以及从已知 id 解析 name。
5. 确认调用方具备权限 manageClientSettings；body 使用 POA preset schema，仅提交 client-settable 字段（clientId、createdAt、createdBy、modifiedAt、审计轨迹等由服务端管理并在响应中回显）。
6. 创建后通过编辑 level 接线：在任一 PROOF_OF_RESIDENCE doc-set 上设置 requiredIdDocs.docSets[].poaStepSettingsId = "<新 id>"。
7. 认证按 Sumsub authentication reference 对每个请求签名；若遇 401 Invalid signature，阅读 sumsub-api-auth skill。
8. 仅使用 sandbox App Token；不要接受或使用 production App Token。若用户提供生产 token，拒绝并要求其在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成 sandbox pair（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。
9. Token + secret 只显示一次，关闭对话框前复制两者；helper script 会拒绝不以 sbx: 开头的 token。
10. 配置环境变量：SUMSUB_APP_TOKEN（如 sbx:...）、SUMSUB_SECRET_KEY（配对 secret）、SUMSUB_BASE（可选，默认 https://api.sumsub.com）。
11. 若用户已在对话中提供凭据则复用；否则运行前只询问一次；绝不把 secret 回显出去。
12. 处理 tenant entitlements：POA preset 创建历史上受 POA entitlement 限制，但实际 API 对多数租户接受写入；不要把缺失当作 blocker。
13. 调用 sumsub-check-permissions，检查 allowedChecks，仅作诊断参考。
14. 若 allowedChecks 中存在 POA，继续。
15. 若缺失 POA，仍然继续，并用一行用户可见提示说明文档化 entitlement 未列出；不要暂停等待确认，因为真正无权限时 Sumsub 会自行拒绝，POST 的 4xx 更有信息量。
16. 若 POST 返回提及 entitlement 的 4xx，逐字展示错误 body，并建议联系 CSM / Sumsub support。
17. Procedure 第 0 步：获取 tenant entitlements（见上）。
18. Procedure 第 1 步：把用户意图翻译成 compact spec；多数用户描述“接受什么”（bank statements、utility bills）和“多久有效”（validity in months），映射到 providers 键、subTypes、validMonths。
19. Procedure 第 2 步：校验 name 非空；includedCountries 和 excludedCountries 不能同时设置；每个 provider key 是 PoaCompanyContactType；每个 subTypes 条目是 PoaSubType；每个国家代码是 ISO-3166-1 alpha-3 大写；crossValidator.fuzzyThreshold 在 [0, 1]。
20. Procedure 第 3 步：用 ${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py 生成 payload（compact spec 从 stdin 输入 -> 完整 payload 从 stdout 输出）。
21. Procedure 第 4a 步：新 preset 用 ${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh 发送 POST；payload 必须不带 id。
22. Procedure 第 4b 步：更新已有 preset 先用 ${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh GET 当前状态让用户看到 diff，再用 ${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh 发送 PATCH；payload 必须包含 preset 的 id。
23. Procedure 第 5 步：从响应 body 读取 id 和 clientId，构造 dashboard link：https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&sbx=true；其中 sbx=true 指向 Sandbox workspace，是所有 skill 共享的 canonical sandbox link 参数。
24. Procedure 第 6 步：报告时先给人类可读信息；最后才给 id 作为下一 API 调用要传的值：包含 name 和国家范围（incl/excl）+ per-country override countries；简要总结接受内容（覆盖的 provider types、默认有效期）；dashboard link 作为 clickable markdown link；最后一行 `Preset ID for level wiring: <id>`。
25. 构造 compact spec 时使用 JSON 或 YAML，字段包括 name、desc、最多设置 includedCountries 或 excludedCountries 之一、settings（acceptMultiplePages、acceptDocScreenshot、requireCountryMatch、useIssueDateForExpiry、validMonths、addressTypes、acceptableLanguages、providers、poiAsPoa、crossValidator）以及 byCountry 覆盖。
26. providers 的键为 PoaCompanyContactType：bank、utilityProvider、governmentOrganization、mobileOperator、other。
27. providers.<key>.subTypes[] 可用值：statement、voterRegistration、taxBill、telecom、utilityBill、bankStatement、bankLetter、lease、universityLetter、employmentLetter、other。
28. addressTypes[] 可用值：dwelling、poBox、poBoxSpecialCountries。
29. poiAsPoa.allowedTypes[] 使用标准 IdDocType：PASSPORT、ID_CARD、RESIDENCE_PERMIT、DRIVERS（其他少见）。
30. crossValidator.nameMode 可用值：strict、weakContainment、def、ai、fuzzy、containment、fuzzyContainment。
31. crossValidator.addressMode 可用值：strict、fuzzy。
32. 配置 provider 时可按需使用 validMonths、acceptUnconventional、subTypes、allowedOrgs.names、allowedOrgs.websites、forbiddenDocumentNames、forbiddenOrgNames、forbiddenOrgWebsites；allowedOrgs 仅在 acceptUnconventional=true 时使用。
33. 配置 poiAsPoa 时可使用 enabled（acceptPoiAsPoa）、sameDoc（acceptSamePoiAsPoa）、validMonths、allowedTypes。
34. 配置 crossValidator 时可使用 nameMode、addressMode、fuzzyThreshold、ignoreMiddleName、ignoreFixedInfo。
35. 配置 byCountry 覆盖时使用与 settings 同 shape；只需设置要覆盖的键，其余回落到全局 settings。
36. 成功时输出：name、国家范围、per-country override countries、接受内容摘要、dashboard link、最后单独一行 `Preset ID (for level wiring / future PATCH): <id>`。
37. 失败时输出 HTTP status + Sumsub 的 description/errorName；builder 会提前用精确消息拒绝无效 enum / 不可能组合。
38. 所有面向用户的消息中，preset 在行文中用 name 指代（如 “POA — 60 days”），不要用 id；id 只出现在最后专用行（`Preset ID for level wiring: <id>`），因为用户需要复制到 level 的 poaPresetId/poaStepSettingsId。
39. 当本技能被 level skill 链式调用接入 PROOF_OF_RESIDENCE 步骤时，level skill 的 pre-POST summary 也应通过 name 指代该 preset。
40. Hand-off 到 sumsub-create-level：把返回的 id 传给 level 的 PROOF_OF_RESIDENCE doc-set；level skill 暴露友好字段 poaPresetId 或 canonical 字段 poaStepSettingsId，例如 {"type":"PROOF_OF_RESIDENCE","docTypes":["UTILITY_BILL","BANK_STATEMENT"],"poaPresetId":"<id from this skill>"}。
41. 可参考 examples/minimal.json、examples/eu-bank-friendly.json、examples/per-country-tight.json，以及 references/poa-preset-schema.md 获取完整 schema、所有 enum 和 gotchas。

适用边界 · 注意事项

• 不要用于把 preset 挂到 level；应改用 sumsub-create-level 在 level 上设置 poaStepSettingsId。
• 不要用于非 POA 预设（cross-check presets、permission presets 等）。
• 不要使用 production App Token；仅使用 sandbox token（sbx: 开头）。