用途
Sumsub 技能版本检查用于检测本地安装的 @sumsub/agent-skills 包与官方发布版本之间的版本漂移(version drift),以免过期的技能在无提示的情况下产生陈旧或错误的 Sumsub 行为。它应在任何 Sumsub 工作开始之前触发,例如首次调用 mcp__Sumsub_Dev__* 工具之前,或在引导用户完成任何 Sumsub 工作流(创建申请人、请求检查、读取交易、构建验证链接等)之前,也可在用户明确询问 Sumsub 技能是否最新时运行。
主要能力
该技能会比较本地版本与从 https://api.sumsub.com/llms.txt 中解析出的官方版本,并给出判定结果。其唯一的用户可见交付物是一行 headsup 提示。运行 check_version.sh 只会计算该提示;只有该行出现在给用户的回复中,技能才算完成工作。
脚本在标准输出中最多打印四行 key=value:
- local — 已安装版本(发布时写入 references/version.txt)。
- remote — 从官方 llms.txt 的 agent-skills-version: 行解析出的官方版本。
- status — 判定结果。
- headsup — 仅对非静默判定出现,即需要展示的精确 markdown 行。
判定结果含义:
| status | 是否出现 headsup | 含义 |
|---|---|---|
| UP_TO_DATE | 否 | 本地版本与发布版本一致,保持静默 |
| PATCH_BEHIND | 是 | 有补丁版本可用,展示提示后继续 |
| MINOR_BEHIND | 是 | 有次要版本可用,展示提示后继续 |
| MAJOR_BEHIND | 是 | 明显落后,行为可能已改变,展示提示后继续 |
| AHEAD | 是 | 本地比发布版本更新(可能是开发构建),展示提示后继续 |
| UNKNOWN | 否 | 远程不可达或无法解析,保持静默,绝不阻塞用户 |
使用方式
采用两阶段协议:
第一阶段 — 在任务前计算判定。运行:
bash ${CLAUDE_SKILL_DIR}/scripts/check_version.sh
它计算判定并缓存渲染好的 headsup。留意是否打印出 headsup= 行,但此时不要向用户写入任何内容。
第二阶段 — 最后渲染,再撰写回复。完成用户实际的 Sumsub 任务后,在撰写回复前的最后一个动作(在所有任务和所有其他工具调用之后)运行:
bash ${CLAUDE_SKILL_DIR}/scripts/render_headsup.sh
将其标准输出当作必须呈现的工具结果:如果打印出引用块,该引用块就是你回复的第一行,逐字、以 markdown 渲染;然后接任务答案。如果什么都没打印,就不要提版本。渲染步骤刻意作为最后一个工具调用,以便撰写回复时 headsup 是上下文中最新鲜的内容。
对于明确的“我的技能是最新的吗?”提问,没有其他任务,第一阶段已让 headsup 成为最新鲜输出,直接在回复开头展示即可,第二阶段渲染可跳过。
适用场景与限制
不应运行该检查的情况:用户询问非 Sumsub 工具或厂商(Onfido、Persona、Stripe 等),即使话题是 KYC;用户询问自己项目的通用包新鲜度(npm outdated、pip list --outdated 等);用户明确表示不是在问 Sumsub。也不要在无关回答后附加“顺便帮你检查 Sumsub 技能?”之类的旁注。
应运行的情况:每个会话在第一个 Sumsub 相关动作前运行一次;用户明确询问 Sumsub 技能是否最新时。同一会话内不要重复运行网络检查(check_version.sh),重复 curl 只会增加延迟而无价值。第二阶段的 render_headsup.sh 不重新检查,只重新输出缓存的判定;在发现漂移的会话中,只要产生 Sumsub 答案就必须执行。
该检查是非阻塞的,但这仅表示无需暂停或等待用户即可继续,并不意味着 headsup 可选或可跳过。请遵循两阶段协议,然后在同一回复中继续完成用户任务。
远程 URL 为 https://api.sumsub.com/llms.txt,无需凭证,是公开静态文件;可通过 SUMSUB_VERSION_URL 环境变量覆盖以用于测试。若官方来源迁移(主机变更或文件形态改变),可将 SUMSUB_VERSION_URL 设为新位置;脚本接受 agent-skills-version: 行(首选)、JSON 的 "version" 字段或裸 version: 行。
注意事项:永远不要因判定结果而阻塞用户请求;同一会话中不要展示 headsup 超过一次;绝不回显 local=/remote=/status=/headsup= 这些键本身;headsup 文本由第一阶段生成、第二阶段重新输出,不要手写。