更新 / 配置异常（omc-doctor 诊断）

你会遇到什么

升级后行为异常、配置冲突、命令报错。改不动、跑不动，也不知道哪里不对。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

版本间配置/迁移差异、旧配置残留——升级后旧配置和新版本对不上，行为就乱了。

这类工具升级的"行为异常"几乎都是配置 schema 漂移：新版本改了配置的字段结构或语义（比如某条规则从"全局生效"改成"按项目生效"），而你磁盘上的旧配置还是老格式。工具不会自动迁移未知字段——能读的字段继续读，读不了的静默忽略，于是出现"配置还在，但行为变了"的诡异现象。

omc-doctor 的价值就是把"静默忽略"变成"显式报告"：它逐项体检配置、版本、环境，把不匹配点直接列出来，省掉你逐条对比新老文档的功夫。

所以升级后先跑诊断，比翻 changelog 快得多。

一步步来

1. 跑 omc-doctor — 必做

omc-doctor

内置诊断，直接指出问题点（CSDN 2026-04 案例路径）。

2. 按诊断结果修配置 — 排查

必要时重装对齐版本：

npm i -g oh-my-claude-sisyphus@5.0.0

3. 反馈时保留诊断输出 — 排查

omc-doctor 输出含版本号与 node 版本，反馈问题时一并附上。

怎么确认修好了

诊断无异常（预期形态）：

omc-doctor → 各检查项通过/无 ERROR

命令行为恢复正常。

其它环境的表现

症状

升级后行为异常、配置冲突、命令报错。

原因

版本间配置/迁移差异；旧配置残留。

解法

1. 跑 omc-doctor（内置诊断）看问题点。
2. 按诊断结果修配置；必要时 npm i -g oh-my-claude-sisyphus@5.0.0 重装对齐版本。
3. 保留 omc-doctor 输出再反馈问题（含版本号与 node 版本）。