QoderWake_Skill启用失败怎么排查？

QoderWake配置的Skill未生效，通常是因为路径、命名或定义文件不符合规范。本文将从三个核心方面，逐一排查并解决该问题。

确认Skill文件存放路径是否符合规范

QoderWake只扫描特定目录下的Skill，且路径层级不可省略。必须将Skill文件夹完整置于~/.config/qoderwake/skills/（Linux/macOS）或%USERPROFILE%.configqoderwakeskills（Windows）下，不能放在子目录如skills/custom/或skills-backup/中。

打开终端或命令提示符，执行：ls -l ~/.config/qoderwake/skills/（macOS/Linux）或dir "%USERPROFILE%.configqoderwakeskills"（Windows），确认目标Skill文件夹直接列在该目录下，而非嵌套在其他文件夹内。

若路径中含中文、空格或特殊符号（如括号、&、#），QoderWake会静默跳过整个文件夹——请立即将其重命名为纯英文+下划线组合，例如web_scraping_v2，不要用网页抓取_测试版或my-skill(1)。

检查Skill文件夹结构与命名一致性

每个Skill必须是一个独立文件夹，且文件夹名必须与内部skill.yaml（或skill.json）中定义的id字段值完全一致，包括大小写和连字符。

进入该Skill文件夹，用文本编辑器打开skill.yaml，查找id:行，例如：id: data_cleaner_pro；再确认当前文件夹名是否也叫data_cleaner_pro。二者任意一处拼写偏差（比如data-cleaner-pro或DataCleanerPro），Skill即无法注册。

这一步操作起来很简单，直接比对两处字符串是否逐字符相同即可。不一致就立刻重命名文件夹，别改yaml里的id——QoderWake强制以文件夹名为唯一标识。

验证Skill定义文件语法与必填字段

方法一：用YAML校验工具快速检测

将skill.yaml全文粘贴至在线YAML校验器（如yamllint.com），确认无缩进错误、冒号后缺失空格、布尔值未小写等基础语法问题。特别注意triggers和actions字段不能为空数组，至少保留一个合法条目，否则引擎判定为无效Skill而丢弃。

方法二：手动检查三个强制字段

打开skill.yaml，确保同时存在以下三项且非空：

• ①

  id
  ：与文件夹名100%一致；
• ②

  version
  ：格式为X.Y.Z，如1.0.0，不能是v1.0或1.0；
• ③

  triggers
  ：至少包含一个有效触发器对象，例如：- type: keyword, value: "清理数据"。若此处写成triggers: []或直接删掉该字段，Skill不会被加载。

重启QoderWake并观察加载日志

第一步：彻底终止所有QoderWake进程。Windows执行taskkill /f /im qoderwake.exe，macOS/Linux执行pkill -f qoderwake。

第二步：清空运行时缓存。删除~/.config/qoderwake/cache/（或%USERPROFILE%.configqoderwakecache）整个文件夹。

第三步：以调试模式启动服务，实时捕获加载行为：qoderwake start --debug。

第四步：在终端输出中搜索loading skill关键词。若看到loading skill data_cleaner_pro → OK，说明已成功加载；若完全没出现该行，或出现skip invalid skill: data_cleaner_pro，则回到前三个步骤逐项复查。

常见问题与解决方案

• Q: 我的Skill文件夹路径正确，但日志中仍然没有加载记录？
  
  A: 请检查skill.yaml文件中的id字段是否与文件夹名完全一致，包括大小写。同时，确认triggers字段不为空，且至少包含一个有效触发器。

• Q: 我使用了中文文件夹名，但QoderWake没有报错？
  
  A: QoderWake会静默跳过包含中文、空格或特殊符号的文件夹。请立即将文件夹重命名为纯英文+下划线组合，如web_scraping_v2。

• Q: 重启服务后，如何确认Skill是否已加载？
  
  A: 在调试模式下启动服务，并在终端输出中搜索loading skill关键词。若看到loading skill [你的Skill名称] → OK，则表示加载成功。