🆘 Khy-OS 紧急恢复卡片（出事时翻这一页就够）#

写给慌乱中的维护者（也许不是工程师，也许半夜一个人）。

这一页不需要你懂代码。每种「坏了」都给两条路：先双击、敲不动再复制命令。
每条命令都能直接复制到终端运行。记不住没关系——把这一页存成书签即可。

黄金法则三句话：

1. 先留证再动手：任何修复前，先「导出诊断日志」，免得越修越查不清。
2. 改之前先备份：更新/回滚前先「备份关键数据配置」。
3. 拿不准就回滚：回滚是设计得最安全的一步——未确认绝不动你的代码。

0. 万能两步（不知道哪坏了，先做这两步）#

诊断日志会同时生成人读版 .md 和机读版 .json，落在 maintenance/logs/。
求助时：.md 发给维护者看，.json 发给 AI 助手解析。两份都不含密钥，可放心外发。

1. CLI 坏了（khy 敲了没反应 / 提示 command not found）#

khy 这个简写入口可能掉了，但后备入口几乎总能用——它直接调后端，不依赖简写：

# 主路径（简写，可能已坏）：
khy --version
# 后备路径（直连后端，绕过简写）：
node services/backend/bin/khy.js --version

• 后备入口能打印版本 → 简写坏了而已，重装一次：双击 维护-一键重装依赖，或

node maintenance/lib/ops.js reinstall。

• 后备入口也没反应 → 多半是依赖坏了，同样先「一键重装依赖」；仍不行就导出诊断日志发出去。

记住：本卡片里所有 node maintenance/lib/ops.js ... 命令都不经过 khy 简写，
所以即使简写彻底坏了，这些救援命令照样能跑。

2. 更新坏了（更新完整个跑不起来）#

按顺序，能停在哪步就停在哪步：

1. 先留证：双击 维护-导出诊断日志（或 node maintenance/lib/ops.js diagnostics）。
2. 快速烟雾测试看命脉断在哪：双击 维护-快速烟雾测试更新发布回滚后，或

node maintenance/lib/ops.js smoke。它几秒钟告诉你哪条命脉断了，并给「下一步」。

1. 依赖坏了（找不到模块/import 报错）→ 双击 维护-一键重装依赖。
2. 还不行就回滚到上一个好版本（见第 4 节）。

3. 发布坏了（构建/上传 PyPI 出错）#

node maintenance/lib/ops.js post-verify   # 发布后验证：版本一致 + dist 产物 + twine check

或双击 维护-发布后验证。它会逐项告诉你哪不对、怎么修：

• 版本号不一致 → 按 AGENTS.md 的「Version Sync」把三处改齐（pyproject / __init__ / package.json）。
• dist 下没产物 → 先双击 维护-一键构建发布产物。
• twine check 没过 → 看输出里产物元数据问题。

全绿之后，登记这个好版本免去日后记忆：双击 维护-登记最近稳定版免记忆回滚，或
node maintenance/lib/ops.js bless。它把当前 version/commit/tag/产物校验值写进
maintenance/stable-release.json，以后回滚自动用它。

4. 回滚到上一个好版本（升级搞砸了的救命操作）#

这是设计得最安全的一步：工作区不干净会拒绝、未输入 y 绝不改动你的代码
（有自动化测试守着这条性质）。

# 先备份，再回滚：
node maintenance/lib/ops.js backup
node maintenance/lib/ops.js rollback           # 交互确认，输入 y 才真的切

双击版：先 维护-备份关键数据配置，再 维护-回滚到最近稳定版本。

• 提示「工作区有未提交改动」→ 它在保护你的改动。先 git stash（暂存），再重跑回滚。
• 回滚后 → 双击 维护-一键健康体检 确认可用；想回到最新开发线：git checkout <你原来的分支>。

回滚目标从哪来？优先 maintenance/stable-release.json 登记的版本（见第 3 节的 bless）；
没登记就自动退回到仓库里最高的版本标签。你不必记住版本号。

5. 双击入口也坏了（选单打不开 / 提示找不到清单）#

双击启动器背后有备用救援清单 maintenance/rescue-catalog.json 兜底——
主清单（维护映射表 / tasks.json）被改坏时会自动回退，所以入口一般不会整体失效。
看到窗口里出现「维护清单回退」字样属正常兜底，不是失败。

主清单修好后，刷新一次救援清单：

npm run maintenance:generate

连 Node 都找不到（双击毫无反应）→ 安装 Node 20+（https://nodejs.org）后重试。

6. 日志/求助寄到哪#

• 诊断文件：maintenance/logs/diagnostics-<时间戳>.md（人读）和 .json（机读）。
• 每次双击的运行日志：maintenance/logs/ 下带时间戳的文件（窗口结尾会打印路径）。
• 求助时把上面的文件整个发出去，并说一句「我双击了哪个文件 / 跑了哪条命令」。

日志含平台和每一步成败，足够维护者或 AI 定位。这些文件不含 API 密钥，可放心外发。

7. 速查表（一页全在这）#

更系统的说明见同目录 KHY-OS-传承书.md。这一页只为慌乱时快速止血。