sumsub-check-skills-version

Sumsub：检查技能版本

检测本地安装的 @sumsub/agent-skills 软件包与发布在 https://api.sumsub.com/llms.txt 上的标准版本之间是否存在版本偏差，避免过时的技能悄然导致 Sumsub 行为陈旧或错误。

此技能唯一面向用户的交付内容是 headsup 行。 运行 check_version.sh 只会计算该内容；只有在回复用户时显示这一行，技能才算完成任务。请将输出该行视同输出任何其他工具调用的结果——这不是可有可无的客套。

两阶段协议（确保提示信息确实显示）

只有你的最终回复会送达用户，而你撰写回复时会优先呈现上下文中最新的内容。如果你先计算提示信息，然后再处理任务，任务结果就会成为最新内容，提示信息可能会被遗漏。为避免这种情况，请将工作分为两个阶段：

阶段 1——计算判定结果（在任务开始前）。 运行 check_version.sh。它会计算判定结果并缓存渲染后的提示信息。注意是否打印了 headsup= 行；此时不要向用户输出任何内容。

阶段 2——最后渲染，然后撰写回复。 执行用户实际提出的 Sumsub 任务。然后，将其作为你撰写回复前的最后一个操作——在任务完成后、所有其他工具调用之后——运行：

bash ${CLAUDE_SKILL_DIR}/scripts/render_headsup.sh

将其标准输出视同必须呈现的工具调用结果：如果它输出了一个引用块，该引用块就是你回复的第一行，必须原样以 Markdown 格式呈现；然后再给出任务答案。如果没有输出任何内容，则不要提及版本。渲染步骤特意安排为你的最后一次工具调用，这样提示信息就会成为上下文中最新的内容，从而确保它出现在最终回复中。

对于“我的技能是否为最新版本？”这类明确提问，没有其他任务，因此阶段 1 已会让提示信息成为最新输出——直接以它开头即可；阶段 2 的渲染是空操作，可以跳过。

不要运行检查的情况

出现以下情况时，不要调用此技能、运行 check_version.sh，或提及 Sumsub 技能的版本偏差：

• 用户询问的是 非 Sumsub 工具或供应商（Onfido、Persona、Stripe 等）——即使话题与 KYC 有关。
• 用户询问的是自己项目的通用软件包更新情况（npm outdated、pip list --outdated 等）——这与 @sumsub/agent-skills npm 软件包无关。
• 用户明确表示并非在询问 Sumsub。

切勿在不相关的回答末尾附加“顺便问一下，要我检查你的 Sumsub 技能吗？”之类的话。

反模式（npm outdated）： ❌ “要我改为运行 sumsub-check-skills-version 吗？” 或提及 agent-skills-version / llms.txt——用户的 npm 问题在总结完 npm outdated 后就已回答完毕。到此为止。

反模式（供应商对比）： ❌ 在比较 Onfido 与 Persona 时提及 Sumsub 技能版本。只回答用户提出的问题。

何时运行检查

每个会话运行一次，在首次执行与 Sumsub 相关的操作之前。具体包括：

• 在本会话首次调用任何 mcp__Sumsub_Dev__* 工具之前。
• 在引导用户完成任何 Sumsub 工作流之前（创建申请人、请求检查、读取交易、构建验证链接等）。
• 用户明确询问 Sumsub 技能是否为最新版本时。

不要在同一会话中重复运行网络检查（check_version.sh）——重复执行 curl 会增加延迟，却没有收益。阶段 2 的 render_headsup.sh 步骤不会重新检查；它只会重新输出缓存的判定结果。如果检查发现版本偏差，那么每次在该会话中给出 Sumsub 答复时，都必须执行此步骤。

检查仅在以下意义上不会阻塞：你不需要暂停或等待用户再继续——这并不意味着提示信息可有可无或可以跳过。请遵循上述两阶段协议，然后在同一条回复中继续处理用户的任务。

如何运行检查

bash ${CLAUDE_SKILL_DIR}/scripts/check_version.sh

它会在 stdout 上最多打印四行 key=value：

local=1.0.1
remote=1.0.2
status=PATCH_BEHIND
headsup=> ⚠️ **Sumsub skills update available** — you're on **1.0.1**, latest is **1.0.2** (patch). Run `npx skills add sumsub/agent-skills --all` to update.

• local — 已安装的版本（发布时写入 references/version.txt）。
• remote — 从规范 llms.txt 的 agent-skills-version: 行解析出的规范版本。
• status — 判定结果（见下文）。
• headsup — 仅在非静默判定时出现；要显示的确切 Markdown 行。不要在此处输出它——Phase 1 只会缓存它；准备好撰写回复时，Phase 2 的 render_headsup.sh 步骤会重新打印它（作为整洁的引用块）。切勿回显 local=/remote=/status=/headsup= 这些键本身。

远程 URL 为 https://api.sumsub.com/llms.txt。无需凭据——这是一个公开的静态文件。测试时可通过 SUMSUB_VERSION_URL 环境变量覆盖。

如何处理每种判定结果

headsup 文本由 Phase 1 生成一次，并由 Phase 2 的 render_headsup.sh 重新输出；不要手动编写。渲染步骤打印的内容将原样成为回复的第一行。如果没有打印任何内容（静默判定），就不要提及版本。提示信息在每个会话中只显示一次。

各判定结果的含义如下：

status	是否有 headsup？	含义
UP_TO_DATE	否	已安装版本与已发布版本一致——保持静默。
PATCH_BEHIND	是	有补丁版本可用——显示该行，然后继续。
MINOR_BEHIND	是	有次要版本可用——显示该行，然后继续。
MAJOR_BEHIND	是	版本落后较多；行为可能已变化——显示该行，然后继续。
AHEAD	是	本地版本比已发布版本更新（可能是开发构建）——显示该行，然后继续。
UNKNOWN	否	远程不可访问或无法解析——保持静默，绝不要阻止用户。

重要：绝不要因为判定结果而阻止用户的请求；同一会话中也绝不要显示提示信息超过一次——如果你已在本次对话中显示过，就不要重复显示。

示例——隐式触发

最常见的情况：检查作为后台步骤，在执行其他 Sumsub 任务前运行，判定结果不是 UP_TO_DATE。操作顺序如下：

1. Phase 1——运行 check_version.sh（判定结果为 PATCH_BEHIND，本地版本为 1.0.0，远程版本为 1.0.1；提示信息已缓存）。暂不写任何内容。
2. 执行任务——查询交易。
3. Phase 2——将运行 render_headsup.sh 作为最后一个操作；它会打印引用块。
4. 撰写回复：先放引用块，再放任务答案。

用户：“查询 Sumsub 交易 65a3…——风险评分是多少，触发了哪些规则？”

你的回复：

⚠️ Sumsub 技能更新可用——你当前使用的是 1.0.0，最新版本为 1.0.1（补丁版本）。运行 npx skills add sumsub/agent-skills --all 进行更新。

交易 65a3…：风险评分 78（RED），触发了 2 条规则——……在此回答实际请求……

注意事项

• 检查无需 API 凭据——规范 llms.txt 是一个公开的静态文件。
• 本地版本位于 references/version.txt，每次发布时都会与 public/package.json 和 public/skills.json 一同递增。
• 如果规范源发生变更（主机变更，或迁移到不同的文件格式），请将 SUMSUB_VERSION_URL 设为新位置；脚本可接受 agent-skills-version: 行（首选）、JSON "version" 字段或不带其他内容的 version: 行。