sumsub-conformance

Sumsub — 一致性核查（法规 ↔ 已部署配置）

沿着实时配置图追踪法规中的每项要求，并逐项回答：**是否收集？→ 是否评分？→ 是否执行？**它揭示了一个其他工具都无法发现的核心问题——已收集但未执行：配置收集并评估法规所需的数据，却没有据此采取行动（例如，对适当性问卷进行了评分，却从未据此进行路由）。

这是一个**差距提示助手，不是合规保证。**它会确定性地核查可由配置表示的部分，并如实界定其余部分（语义意图 = 需判断；SDK／平台结果 = 不在范围内）。请让人工签字确认。

适用场景

• 现有客户：“这是我们的法规，这是我们的租户——实际执行了哪些要求？”
• 使用 create-* 技能配置 Sumsub 的新客户：补齐生成 → 验证闭环——组装后的配置是否确实执行了其旨在满足的法规要求？

端点（只读）

全部通过 scripts/sumsub_curl.sh（App-Token HMAC）调用。resolve_graph.sh 会封装这些端点：

用途	方法 + 路径
层级（查找目标）	GET /resources/applicants/-/levels
工作流（自动查找引用该层级的工作流）	GET /resources/api/applicantWorkflows + GET /resources/api/applicantWorkflows/{id}
问卷内容 + 分数	GET /resources/api/questionnaires/{id}
地址证明 / 交叉核对预设	GET /resources/api/poaStepSettings/{id} · GET /resources/api/crossCheckPresets/{id}
权限（allowedChecks 键）	GET /resources/api/agent/settings/bgCheckTargets

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

此技能调用 Sumsub 公共 API，并按照身份验证参考为每个请求签名。工作原理说明见 sumsub-api-auth。

**⚠️ 仅限沙盒令牌。**虽然是只读操作，但仍请注意：不要接受生产环境的 App Token。如果用户提供了生产令牌，请拒绝并要求提供沙盒令牌和密钥对，地址为 https://cockpit.sumsub.com/checkus/home?sbx=true（将 Sumsub 连接到 AI Agent -> 构建与配置 -> 生成令牌）。该辅助脚本会拒绝不以 sbx: 开头的令牌。

变量	示例
SUMSUB_APP_TOKEN	sbx:...
SUMSUB_SECRET_KEY	配对密钥
SUMSUB_BASE / SUMSUB_ENV=dev	可选；dev 指向 dev-api.sumsub.com（内部环境）。

流程

使用脚本——不要手动重做确定性步骤。 这项技能的核心在于解析结果和判定是确定性的，无需每次都凭肉眼重新推导：

• 只能通过 resolve_graph.sh 解析图。 不要直接调用 /resources/... 端点、手动列出各级内容，也不要自行去掉 HTTP <code> 尾标——脚本会完成这些操作并输出一张干净的图。
• 如果无法解析图，就停止——绝不要绕过故障。 resolve_graph.sh 返回 401/403、404 或 0 levels / "level not found"，都表示无法继续运行。明确说明故障（可能是令牌错误／非沙盒令牌，或级别名称错误），然后停止。不要修改 resolve_graph.sh（或任何脚本）来绕过错误、添加按 ID 回退、改试其他端点，或以其他方式临时拼凑图；也绝不要根据不完整或替代图生成报告、分组计数或 CONFORMANT 判定。没有解析出的图，就没有发现结果。
• 只能根据 trace.py / report.py 推导判定。 不要凭肉眼查看工作流／问卷 JSON，然后自行判断“已强制执行／未强制执行”——这会重新引入偏差和幻觉。COLLECTED-NOT-ENFORCED 发现必须由引擎生成。
• 如果脚本已经运行，就信任其输出——不要通过手动 API 调用再次验证。
• 要在 Map 步骤检查图，请运行 python3 scripts/graph_summary.py "$CONFIG"。 不要手动遍历图 JSON：questionnaires/poaPresets/crossCheckPresets 是以 ID 为键的字典（遍历时会得到 ID 字符串 → 'str' has no attribute 'get'），而 entitlements 是一个列表。graph_summary.py 会正确打印所需的各分区／项目索引和分数。 Agent 的判断仅适用于两个步骤：摄取（阅读法规）和映射（将要求与已部署的配置元素匹配——问题、docSets、字段、国家、entitlements）。其他所有工作都由脚本完成。

工件——必须遵守的存放位置和命名规则。 每次运行都必须将工件写入源法规文件所在的同一目录，并根据其文件主名（不含扩展名）命名。绝不要保存到当前工作目录，也不要擅自更改命名。开始时一次性推导出确切路径：

eval "$(python3 scripts/artifact_paths.py "<path/to/RegFile.pdf>")"
#  $REQUIREMENTS = <dir>/<stem>_regulations.json   （在步骤 1 和 3 中构建的要求）
#  $CONFIG       = <dir>/<stem>_config.json         （步骤 2 中 resolve_graph 的输出）
#  $REPORT       = <dir>/<stem>_report.md           （步骤 6 中渲染的报告）

例如：Level4regulations.pdf → Level4regulations_regulations.json、Level4regulations_config.json、Level4regulations_report.md。在下文步骤中按原样使用 $REQUIREMENTS / $CONFIG / $REPORT。

1. 摄取法规（判决书）。只需使用 Read 工具阅读文档——它原生支持读取 PDF（渲染页面并提取文本），因此无需安装任何内容。 对于超过约 10 页的 PDF，请按页码范围分段使用 Read（Read 工具的 pages 参数，每次调用不超过 20 页）。视觉阅读的效果与文本提取器相当或更好——它能保留纯文本提取会丢失的表格、标题和版式。可选，仅当已安装且绝不会成为阻碍时： pypdf/pdftotext 可一次性提取篇幅较长、文本密集的 PDF；scripts/render_regulation.py（PyMuPDF）可预先将扫描版／纯图像 PDF 渲染为 PNG，以便明确控制 DPI——参见 references/conformance-method.md 第 1 步。如果缺少某个库，直接使用 Read 阅读 PDF 即可。 然后提取要求，并根据 references/requirements-schema.md 将其写入 $REQUIREMENTS（源文件旁的 <stem>_regulations.json——参见上文的 Artifacts 规则）：每项格式为 {id, source, text, type, enforceable, …}。务必记录 source——即原始文档中的引用位置（章节编号／标题／页码，例如 "§5.9.2"、"Section 2 — Scoring Result"、"p.21"）；报告会以此为开头，使发现项能追溯到法规，而非某个人为设定的 id。对于由 SDK／平台／CRM 承载的结果，将 enforceable 标记为 sdk|platform。 向用户展示提取出的要求，并在追踪前征求确认——这是风险最高的一步。
2. 解析已部署的图谱（确定性操作）。运行 bash scripts/resolve_graph.sh <levelNameOrId> > "$CONFIG" （级别 + 带分数的问卷 + 预设 + 自动发现的工作流 + 权限）。这条命令可替代手动列出级别／curl／剥离 HTTP trailer——不要手动执行这些操作。
3. 映射（判断）。首先检查图谱：运行 python3 scripts/graph_summary.py "$CONFIG"——它会打印带有 [section]/[item] 索引和选项分数的问卷、docSets、APPLICANT_DATA 字段、地理区域、权限及工作流（不要手动遍历 JSON）。然后为每项要求选择合适的 type 并填写其 match——并非所有内容都是问卷问题。 各类型的 match 结构见 references/requirements-schema.md：
   • 问卷问题／分数 → match: {questionnaire, section, item}（加上 expectScores）；
   • 收集的文档 → match: {docSet: "IDENTITY", types: [...]}；
   • 申请人数据字段存在 → type: data-field，match: {field: "dob"} / {fields: [...]}；
   • 国家允许列表／受限司法管辖区 → type: country-eligibility，match: {mustHaveAllowlist: true} / {mustExclude: [...]}；
   • 自拍活体检测 → type: liveness，match: {}；
   • 已配置的能力 → type: entitlement，match: {entitlement: "WATCHLISTS"}；
   • 筛查／路由结果 → 设置具有区分性的 enforcementSignal（不要使用通用标记）。 务必保守：如果不确定某项是否存在，将 match: null（→ MISSING），不要猜测。
4. 追踪（确定性操作）。运行 python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" → 发现项会分类为 MISSING / SCORING-MISMATCH / COLLECTED-NOT-ENFORCED / NOT-CONFIG-REPRESENTABLE / CONFORMANT，每项均包含证据和 basis（确定性或判断）。分类结论由此得出——不要自行阅读工作流 JSON 来判断“已执行／未执行”。
5. （可选）配置卫生检查子步骤。 将同一图谱传入随附的 lint 工具，在检查符合性时发现可能不易察觉的配置错误（权限缺失、预设／问卷引用无效、SDK 已弃用、AML 提供商无效）；权限会直接从图谱中读取： bash scripts/resolve_graph.sh <level> | python3 scripts/lint_config.py。规则目录见 references/lint-rules.md（根据 references/rules.json 生成）。
6. 报告——使用规范格式化工具渲染到 $REPORT，不要手动排版。 格式固定，确保每次运行的输出一致： python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" | python3 scripts/report.py --date <today> > "$REPORT" → Markdown 报告，包含状态标题、固定的分类计数表、按固定顺序分组的发现项（每项均包含证据和 basis），以及固定的注意事项页脚。原样呈现 $REPORT。不要用文字重新概述——过去的运行结果之所以不同，就是因为这样做。（trace.py 的 JSON 是供工具使用的另一种规范格式——如果机器端需要消费，请将其与其他文件一同保存。）

它不做什么（请明确说明）

• 不保证合规，也不能替代合规官。
• 不会验证超出存在性、评分和路由强制执行范围的语义正确性 （例如，问题的措辞在法律上是否充分，需要由人判断）。
• 无法验证 SDK／平台／CRM 的结果（披露弹窗、演示账户、只读模式、 25%／10% 限制、CRM 时间戳）——这些都归入 NOT-CONFIG-REPRESENTABLE。

防护措施

• 将确定性事实与判断分开（basis 字段）。切勿将映射推测当作已验证的发现。
• 追踪仅遍历要求 → 部署——绝不会将已部署的问题标记为“多余”（以避免此类误报）。如需报告多余问题，务必将其作为明确的提示说明。
• enforcementSignal 必须具有区分性——通用令牌（country）会匹配兜底边，导致错误地判定为 CONFORMANT。请参阅 references/requirements-schema.md。
• **如实失败——切勿绕过解析失败。**如果 resolve_graph.sh 返回身份验证错误、404 或 0 levels，请停止并报告。不要修改脚本来绕过错误，也不要根据不完整的图伪造报告（参见 Procedure 提示框）。

另请参阅

• references/requirements-schema.md — 要求模型与分类。
• references/conformance-method.md — 五个步骤、防护措施与范围。
• references/lint-rules.md — 随附的卫生检查规则目录（子流程）。
• sumsub-analyze-regulation — 反向流程（法规 → 构建计划）。

示例（examples/）

• sample-requirements.json + sample-graph.json — 合成示例，涵盖所有分类（用于运行 test_trace.py）。
• fiu-india-vasp-mapped.json + vasp-graph.json — 将广泛的 AML 指南映射到假设的 VASP 级别；内容自包含，可离线配套追踪： python3 scripts/trace.py --requirements examples/fiu-india-vasp-mapped.json --graph examples/vasp-graph.json | python3 scripts/report.py。
• cfd-requirements.json — 真实的 CFD／MiFID 要求（针对实时 cfd-onboarding-eu 图运行）。
• fiu-india-requirements.json — 该广泛指南在摄取阶段的输出（映射前）。
• audit-input{,-dirty}.json — 卫生检查器测试样例（用于运行 test_lint.py）。