在 Sumsub 沙箱中配置 KYT 交易监控规则、标签…

通过 Sumsub API 创建/修改 KYT 交易监控规则，并串联标签、申请人评分与风险等级阈值。

适用场景

解决思路

1. 创建或修改规则前，先运行 sumsub-check-permissions 获取 allowedChecks 的键作为租户权限；按规则 types 对照权限表检查，若该类型对应的任一键都不存在则停止，不要构建或 POST 该规则，并告知用户联系 CSM 或 Sumsub 支持；若权限请求本身失败（非 200 或超时），警告用户无法验证权限但仍继续。
2. 判断模式：修改模式——用户提供规则 name（不可变 slug）或足够上下文，运行 bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh 按 name 或 title 找到规则并保存完整文档，向用户展示现有 conditionEl、score、action、types，只收集要改的字段，跳到步骤 2a；创建模式——运行同一脚本检查标题冲突（服务器每次 POST 都会创建重复项，无去重），若已有同名标题规则则提议跳过创建改为修改现有规则。
3. 把用户意图翻译为紧凑规格，逐条收集：title（≤128 字符，必填）、types（一个或多个交易类型）、条件的自然语言描述（用于生成 conditionEl）、score（整数，默认 0# ）、action（score | onHold | awaitUser | reject），以及可选的 desc、tags、bundleName、priority、stopOnMatch、sourceKeys。
4. 若规则 conditionEl 会引用 clientLists.<name>，先用 bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh <listName> 验证每个列表存在：HTTP 200 表示存在可继续；HTTP 404 表示不存在，用 bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh <listName> 创建（POST 幂等）；在所有引用的 client list 确认前不要进入验证或规则创建。
5. 生成 conditionEl：按 references/kyt-rule-schema.md 的类型定义构造 SumScript 布尔表达式；不要猜测字段路径，只使用 schema 中确认的字段，写表达式前验证从根到叶的路径；默认货币金额检查用 data.info.amountInDefaultCurrency（归一化金额）而非 data.info.amount（源货币金额），除非用户明确要求按源货币过滤；scheduledEvent 类型不用 conditionEl 触发，改用 noEventTrigger；多分支评分用 conditionEl 内的 addScoreIf，并把 payload 级 score 设为 0、action 设为 score。
6. 验证已内置于 POST：服务器在创建调用时校验 conditionEl 语法，无需单独预检；若校验失败服务器返回 HTTP 400 及错误信息，修正表达式后重新 POST。
7. 构建 payload：创建模式只含必填字段 title、types（至少 1 个值），eval 规则在相关时包含 conditionEl、score、action，绝不发送 id 或 name（服务器分配）；修改模式（新修订）包含 "name": "<existing-slug>" 和 "id": null（显式 null，表示创建新修订而非新规则，绝不用空字符串 ""，否则 Jackson 会以无效 ObjectId 拒绝并返回 HTTP 400），从现有规则文档携带所有未改字段，只改用户要求的字段，title 和 types 仍必填。
8. 两种模式都始终遵守：绝不发送服务器分配或审计字段 clientId、actual、revision、时间戳（createdAt、modifiedAt、archivedAt）、作者字段；绝不发送 scope 或 bgCheckTargets（服务器管理的许可控制字段）；创建模式绝不发送 dryRun 或 disabled（服务器初始化为 true 和 false）；修改模式从现有规则文档携带 dryRun 和 disabled（服务器用发送值在修订间保留规则的当前激活与测试模式状态）；省略空的可选容器 sourceKeys: []、caseAction: {}、applicantChange: {}、applicantActions: {"actions": {}}、varDefinitions: {"definitions": []}、varValues: {"values": {}}；不要把 scheduledEvent 与其他交易类型混用。
9. 在 POST 前向用户展示每个 payload 并请求明确确认。
10. 通过 bash ${CLAUDE_SKILL_DIR}/scripts/post_kyt_rule.sh < payload.json 逐条 POST 规则（一次一条）；检查退出码：Exit 0 表示 HTTP 200，响应体是创建的 KytTxnRuleView，进入步骤 7；Exit 1 表示 HTTP 4xx/5xx，响应体含错误信息，原样呈现、修正表达式后重新 POST。后端也会执行权限门禁：错误 No allowed transaction types found 表示租户未获所发 types 的许可，告知用户其 allowedChecks 启用了哪些类型并建议联系 CSM，不要静默切换类型；错误 Unable to enable a rule without a specified condition 表示规则需要 conditionEl（或 scheduledEvent 的 noEventTrigger）。每条规则最多 10 次 POST 尝试，第 10 次仍失败则标记该规则为失败、记录最后错误信息并继续下一条，不要中止整批，在步骤 9 报告所有失败规则。
11. 通过 bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rule.sh {id} 逐条 GET 回创建的规则，对比 conditionEl 和关键字段与发送内容，报告任何差异。
12. 为每条规则构建仪表盘链接：https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&sbx=true，name 和 clientId 来自 POST 响应体，渲染为可点击的 markdown 链接。
13. 报告：每条规则以人类可读标题开头，包含 title 和自动生成的 name（短不可变 slug）、状态 testMode（必须在仪表盘激活才能生效）、types、action、score、可点击的仪表盘链接、规则 id 单独一行；对耗尽 10 次尝试的规则在 Failed rules 部分报告标题和最后的 HTTP 400 错误信息；原样呈现 4xx 错误。
14. 配置标签：用 echo '{"tag": {"name": "HighValue", "styleClass": "red", "color": "#FF000080", "scorable": true, "scoreWeight": 1.0}}' | bash scripts/post_kyt_tag.sh 创建或更新标签（color 必须为 8 位十六进制，需 manageKytSettings），再用 bash scripts/get_kyt_tags.sh 读回确认。
15. 配置申请人评估：用 GET /resources/api/agent/tm/settings/applicantAssessment 读取当前配置，用 PATCH 替换配置，payload 含 scores 数组（每项有客户端分配的稳定 id、tag、includeInTotalScore、scoreWeight）和 companyBeneficiarySettings 数组（beneficiaryType 与 weight）；有效 beneficiaryType 值：shareholder、representative、director、ubo、companyOfficer、secretary、founder、investor、legalAdvisor、authorizedSignatory、trustee、trustBeneficiary、trustSettlor、trustProtector、payer。
16. 配置风险等级阈值：用 GET /resources/api/agent/tm/settings/riskLevel 读取，用 PATCH 替换，body 至少 2 项，每项含 label（≤256）、rangeFrom（≥0）、styleClass（grey、black、blue、green、cyan、teal、lime、yellow、orange、volcano、red、pink、fuchsia、purple、purpleLight 之一），需 manageKytSettings。
17. 在规则 payload 中加 tags 数组把规则匹配连接到评估：规则匹配时标签应用到申请人，其权重计入风险分。
18. 修改现有规则时：用 get_kyt_rules.sh 配合 python3 按 name 或 title 子串查找规则，向用户展示当前 conditionEl、score、action、types；取现有规则文档只应用用户要求的改动，设 "id": null、保留 "name": "<slug>"、剥离服务器管理字段（clientId、actual、revision、scope、bgCheckTargets、时间戳、作者字段）、保留 dryRun 和 disabled；若 conditionEl 改变，POST 会自动校验，HTTP 400 则修正后重发（同样 10 次上限）；POST 后响应含新 id、旧 name、revision 号及所有字段，用新 id GET 回验证，仪表盘链接用旧 name，报告新 revision 号及更新字段。
19. 配置定时规则：types 必须恰好为 ["scheduledEvent"]，不能与其他类型组合；必须包含 applicantChange 或 applicantActions（至少一个）；conditionEl 可选（用于二次过滤而非主触发）；noEventTrigger.type 为 byLevelName（某等级已批准申请人，审查后 N 天）或 byCustomExpression（自由格式申请人过滤表达式）。
20. 配置匹配时自动创建合规案件：在规则 payload 加 caseAction，含 createCase: true、groupByType（byRule 每条规则一个案件，或 byApplicant 每个申请人一个案件、交易分组）、blueprintId（可选，省略用默认案件模板）、priority、deadlineHours。
21. 使用客户端列表：GET 需 seeClientLists 权限，POST 需 manageClientLists 权限；GET 返回 403 表示缺少 seeClientLists，POST 返回 403 表示缺少 manageClientLists，两种情况都告知用户缺失权限并停止；在 conditionEl 中用 clientLists.<listName> 精确名称引用；列表内容只能在 Sumsub 仪表盘（KYT → Client Lists）管理，API 端点只创建空列表。
22. 认证：仅使用沙箱 App Token（以 sbx: 开头），拒绝生产 App Token 并要求用户在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成沙箱对（Connect Sumsub to your AI agent -> Build & configure -> Generate token）；环境变量 SUMSUB_APP_TOKEN、SUMSUB_SECRET_KEY、可选 SUMSUB_BASE（默认 https://api.sumsub.com）；若用户已在对话中提供凭据则复用，否则运行前询问一次，绝不回显 secret。

适用边界 · 注意事项

• 不要用于申请人等级、问卷、PoA 预设、工作流或非交易监控任务。
• 不要使用生产 App Token，仅限沙箱 token（sbx: 开头）。
• 当请求的交易类型未获授权（该类型对应行中没有任何键出现在 allowedChecks 中）时不要构建或 POST 该规则，也不要提供其他交易类型作为变通。