QoderWake 的 Skill 体系将功能拆分成独立模块，每个 Skill 都带有自己的版本号、来源仓库和依赖约束。更新 Skill 与升级主程序是两套流程，如果只点击顶部的升级按钮，很可能只更新了 QoderWake 核心，而已安装的 Skill 仍然停留在旧版本。要准确更新 Skill，需要先理解它的版本来源和更新入口。
Skill 的版本管理与更新来源
QoderWake 在安装 Skill 时，会为每个模块记录元数据，包括名称、当前版本、远程仓库地址、更新通道以及依赖的其他 Skill 最低版本。这些信息通常保存在用户目录下的 skill 配置文件中。更新操作的本质是用远程索引比对本地版本，如果发现远端存在更高版本，就下载对应压缩包，替换旧的模块目录，并执行迁移脚本。
本地 Skill 的版本并不会自动与远程保持同步。QoderWake 默认只会在启动时检查一次索引，如果索引缓存过期，即使远程已经发布了新版本，管理界面也可能不显示更新提示。因此，更新前先确认索引是否刷新，是很多更新失败问题的起点。可以使用下面的命令查看当前已安装 Skill 的详细版本信息：
qoderwake skill list --verbose # 输出示例： # http-server 1.4.2 installed remote: 1.5.0 # file-watcher 2.0.1 installed remote: 2.0.1 # database-link 0.9.8 installed remote: 1.0.0
从输出中可以看到哪些 Skill 存在可更新版本。如果 remote 版本高于 installed 版本，就说明需要执行更新。这个命令只是查看，不会修改任何文件，适合在更新前进行状态确认。
通过管理界面更新 Skill
最常用的更新方式是在 QoderWake 的管理面板中完成。打开主界面后，进入 Skill 管理或插件管理标签页，切换到已安装列表。列表右侧通常会显示可用更新数量。选中需要更新的 Skill，点击更新按钮即可开始下载和替换流程。
界面更新分为单个更新和全部更新两种模式。单个更新只处理你选中的 Skill，速度较快，适合只需要修复某个模块的场景。全部更新会遍历所有已安装 Skill，并同时检查依赖关系。如果某个 Skill 的新版本要求先升级另一个 Skill，QoderWake 会按照依赖顺序依次执行更新，而不是并行下载。全部更新完成后，通常需要重启或重载 QoderWake，让新版本模块被重新加载到运行时环境中。
如果希望 Skill 在有新版本时自动更新，可以修改 QoderWake 的配置文件。下面是一段 JSON 配置示例，开启自动更新并指定稳定通道：
{
"skill": {
"autoUpdate": true,
"updateChannel": "stable",
"notifyBeforeUpdate": true
}
}开启自动更新后，QoderWake 会在启动时检查远程索引，并在后台静默下载新版本。对于生产环境或重要项目，建议把 notifyBeforeUpdate 设为 true，这样每次自动更新前都会弹出确认提示，避免新版本引入不兼容变更导致工作流中断。
使用命令行更新 Skill
QoderWake 提供了完整的命令行工具，适合不打开图形界面的场景，也方便在脚本中批量执行更新。命令行更新 Skill 的基本语法是 qoderwake skill update，后面可以跟具体 Skill 名称、all 参数或者指定版本号。
更新单个 Skill 的命令如下：
# 更新指定名称的 Skill qoderwake skill update http-server # 更新所有已安装的 Skill qoderwake skill update --all # 更新到指定的历史版本 qoderwake skill update http-server --version 2.3.1
如果只想查看哪些 Skill 可以更新但不实际执行，可以加上 dry-run 参数。这个参数会输出更新计划，包括将要下载的版本、依赖变化以及是否需要重启，但不会修改任何本地文件。对于需要审计变更的用户来说，dry-run 是一个非常有用的安全选项。
命令行更新还支持指定更新通道。有些 Skill 同时维护 stable 和 beta 两个通道，默认情况下 CLI 只从 stable 通道获取更新。如果需要测试尚未正式发布的功能，可以使用 channel 参数切换到 beta 通道：
qoderwake skill update http-server --channel beta
切换通道时要注意，beta 版本可能包含未完成的功能或接口变更，升级后如果发现其他依赖 Skill 报错，可以重新执行一次带 stable 通道的更新来降级回正式版本。
更新失败的常见原因与修复
更新 Skill 时最常见的错误是权限不足。Windows 系统上，如果 QoderWake 安装在 C:\Program Files 等受保护目录，普通用户可能没有写入模块目录的权限。此时可以以管理员身份运行 QoderWake 或命令行工具，或者把 Skill 安装目录迁移到当前用户有完全控制权限的路径。Linux 系统下则需要检查 ~/.qoderwake/skills 目录的所有者是否与当前登录用户一致。
另一个高频问题是索引缓存过期。远程仓库已经发布了新版本，但本地索引还停留在上一次启动时的状态。解决方法是手动刷新索引，再重新执行更新：
# 刷新远程 Skill 索引 qoderwake skill refresh # 刷新后重新更新 qoderwake skill update --all
依赖冲突也会导致更新中断。例如某个 Skill 的新版本要求 database-link 不低于 1.0.0，但本地 database-link 仍然是 0.9.8。QoderWake 会先升级 database-link，再继续更新目标 Skill。如果依赖链中出现了循环依赖或版本不兼容，更新会终止并返回错误码。此时需要根据错误信息中列出的依赖树，手动移除冲突模块，或者使用强制更新参数跳过依赖检查。强制更新虽然可以继续安装，但可能导致运行时不稳定，仅在明确了解风险的情况下使用。
网络环境也会影响更新过程。如果 QoderWake 无法连接到远程仓库，更新会超时失败。可以在配置文件中设置代理服务器，或者手动下载 Skill 包后使用离线安装命令进行更新。离线更新命令与在线更新类似，只是把远程仓库地址替换为本地文件路径：
qoderwake skill update http-server --local ./http-server-2.3.1.zip
总结下来，更新 QoderWake 的 Skill 并不复杂，关键是先确认索引是否最新，再选择合适的更新入口，失败时优先检查权限、依赖和网络。掌握这些方法后，就可以在不影响主程序的情况下，始终保持各个 Skill 处于最新可用状态。