workbuddy自定义skill中断本质是环境、依赖、权限或输入结构偏差。需依次定位日志错误行、验证并补装沙箱依赖、核对权限路径、校验input_schema、清除context_snapshots缓存。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy自定义Skill执行到一半突然中断并报错，常见表现为日志停在某一步、返回空响应、或抛出ModuleNotFoundError/PermissionError/JSONDecodeError等异常，本质是运行环境、依赖、权限或输入结构出了偏差。
先定位错误源头在哪一行
打开WorkBuddy管理控制台→【技能管理】→点击目标Skill右侧的【执行日志】按钮→选择【最近一次执行】→滚动查看日志末尾。重点关注以ERROR或Exception开头的行，以及紧随其后的Traceback堆栈——最后一行通常就是实际崩溃点。
若日志里出现FileNotFoundError: xxx.skill.json，说明技能文件路径被移动或重命名；若出现ModuleNotFoundError: no module named 'openpyxl'，说明依赖没装进沙箱环境；若看到PermissionError: [Errno 13] Permission denied，大概率是安全沙箱拦截了脚本对本地目录的访问。
检查依赖是否真装进了沙箱环境
WorkBuddy v4.24+启用安全沙箱后，【全局pip安装的包默认不可见】，Skill脚本运行时只能访问沙箱内独立的Python环境。
方法一：用命令行验证依赖是否存在
在终端中执行：workbuddy skill exec --dry-run /path/to/your.skill.json，观察是否报ModuleNotFoundError。若报错，说明该依赖未注入沙箱。
方法二：手动补装（推荐）
找到Skill目录下的requirements.txt（若无则新建），写入缺失模块名，例如：requests==2.31.0openpyxl>=3.1.2
然后执行：python -m pip install -r /path/to/your_skill_dir/requirements.txt --target "%APPDATA%\Tencent\WorkBuddy\Sandbox\site-packages"（Windows）或--target "~/Library/Application Support/com.tencent.workbuddy/Sandbox/site-packages"（macOS）。
这一步必须做，否则即使你本地pip list里有openpyxl，Skill也调不到。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
确认权限模式与授权路径是否匹配
第一步：点击会话界面底部的【权限选项】→确认当前是「安全沙箱」还是「完全访问权限」。
第二步：若为沙箱模式，进入【设置】→【文件系统授权】→检查已授权路径是否覆盖Skill中脚本要读写的目录。例如脚本要处理D:\data\input.xlsx，但授权列表里只有D:\data\，那就没问题；若只写了D:\，反而可能因路径过宽被沙箱拒绝。
第三步：重点核对路径写法——【授权路径必须以斜杠结尾，且不能包含通配符或正则】。错误示例：/home/user（缺末尾/）、/home/user/*.csv（含*）、s3://bucket（未完整写出路径）。正确写法：/home/user/、s3://bucket/reports/。
若脚本尝试访问未授权路径，沙箱会在日志中记录Blocked access to /xxx by sandbox policy，此时必须手动添加对应路径并重启WorkBuddy。
验证输入数据结构是否符合Skill预期
很多Skill在YAML定义中声明了input_schema，要求传入JSON必须含file_path或sheet_name等字段。若用户直接拖入Excel却没指定sheet，或用API调用时漏传{"mode": "batch"}，Skill解析payload时就会卡在第一步。
方法一：查看Skill根目录下的skill.yaml，搜索input_schema字段，确认必填项。
方法二：在触发指令末尾加--debug-input参数，例如：提取销售表中的客户电话 --debug-input
WorkBuddy将输出实际接收到的结构化输入，对照schema逐项比对字段名和类型。
若发现字段缺失，立即补全；若字段存在但值为null或空字符串，需检查前端是否误传了空值。
强制清除上下文缓存重置运行环境
步骤一：关闭WorkBuddy客户端
步骤二：Windows用户删除%APPDATA%\Tencent\WorkBuddy\Runtime\context_snapshots\目录下全部文件
步骤三：macOS用户删除~/Library/Application Support/com.tencent.workbuddy/Runtime/context_snapshots/目录下全部文件
步骤四：重启WorkBuddy，等待首次启动完成（约5秒）
这一步能清除残留的损坏token序列和异常状态快照，解决因前次中断导致的后续请求持续失败问题。不执行此步，有时重装Skill或改代码都无效。
