SuperAPI AI 工具集

sumsub-check-skills-version

编程与开发

查看项目

更新于 10-16 09:40

技能介绍

用途

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 文本由第一阶段生成、第二阶段重新输出,不要手写。