必须将旧版自定义技能插件升级至V2.1运行时，否则会出现静默异常；需确认SDK版本为v1.x或未标注即须迁移；推荐执行qclawctl migrate-skill --all自动升级，或手动修改manifest.json中runtime、permission_scope及context_lifetime字段；重构上下文生命周期逻辑，替换ctx.save()为ctx.lifetime.set()，改用ctx.state.set()替代ctx.memory赋值，并确保回调函数第二参数为ExecutionContext实例；最后通过控制台日志验证加载状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
QClaw V2 Skills SDK协议断层升级指南【详解】要求你将旧版自定义技能插件迁移到V2.1运行时，否则会出现技能调用无响应、参数解析失败、权限校验被拒等静默异常，这些故障不会报错提示，只会让指令卡在路由层直接丢弃。
确认当前Skills插件版本兼容性
打开QClaw设置页→点击“技能管理中心”→展开任意已安装的本地Skill条目，查看右下角显示的“SDK Version”。若为v1.x或未标注版本号，则必须升级；【v2.0以下插件在V2.1运行时中默认禁用，不会加载，也不会报错】。这一步不能跳过，因为QClaw V2启动时会自动过滤不匹配的插件，你根本看不到它们出现在技能列表里。
升级Skills插件至v2.1运行时
方法一：使用官方迁移脚本（推荐）
在终端中执行：qclawctl migrate-skill --all。该命令会自动扫描~/.qclaw/skills/目录下所有插件，识别v1.x结构，重写manifest.json中的runtime字段为"v2.1"，并补全新增的permission_scope和context_lifetime字段。迁移完成后，插件根目录会生成.migrated_v2.1标记文件。
方法二：手动修改manifest.json
用文本编辑器打开插件根目录下的manifest.json，将"runtime": "v1.3"（或其他旧值）改为"runtime": "v2.1"；在permissions数组中，必须显式声明所需权限，例如{"type": "file_read", "scope": "user_documents"}；【缺少permission_scope字段会导致插件加载失败且无日志输出】；保存后重启QClaw。
重构Skills中的上下文生命周期逻辑
第一步：定位所有含ctx.save()或this.context.persist()的代码段。
第二步：将原调用替换为ctx.lifetime.set("short")（适用于单次任务）、ctx.lifetime.set("medium")（适用于跨轮对话）、ctx.lifetime.set("long")（仅限白名单技能，需单独申请）。
第三步：删除所有对ctx.memory对象的直接赋值操作——V2.1已废弃该接口，改用ctx.state.set(key, value)存入沙箱隔离状态池。
第四步：检查所有回调函数签名，确保第二个参数为ExecutionContext实例而非旧版Context，否则路由层无法注入正确上下文快照。
验证升级后的Skills是否生效
重启QClaw后，在微信端发送指令“测试我的天气插件”，观察控制台日志。若看到[SKILL] weather-v2.1 loaded, scope: user_location即表示加载成功；若仍无任何日志输出，说明插件未被识别，请返回第二步检查manifest.json中id字段是否与目录名完全一致（区分大小写、不可含空格）。
