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

> 写给**慌乱中的维护者**（也许不是工程师，也许半夜一个人）。
>
> 这一页不需要你懂代码。每种「坏了」都给两条路：**先双击、敲不动再复制命令**。
> 每条命令都能直接复制到终端运行。**记不住没关系——把这一页存成书签即可。**
>
> 黄金法则三句话：
> 1. **先留证再动手**：任何修复前，先「导出诊断日志」，免得越修越查不清。
> 2. **改之前先备份**：更新/回滚前先「备份关键数据配置」。
> 3. **拿不准就回滚**：回滚是设计得最安全的一步——未确认绝不动你的代码。

---

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

| 想干什么 | 双击（不必懂命令） | 或复制这条命令 |
| --- | --- | --- |
| 先体检看哪红了 | `维护-一键健康体检` | `node services/backend/bin/khy.js health` |
| 留证求助 | `维护-导出诊断日志` | `node maintenance/lib/ops.js diagnostics` |

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

---

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

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

```bash
# 主路径（简写，可能已坏）：
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`。它几秒钟告诉你哪条命脉断了，并给「下一步」。
3. **依赖坏了**（找不到模块/import 报错）→ 双击 `维护-一键重装依赖`。
4. **还不行就回滚**到上一个好版本（见第 4 节）。

---

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

```bash
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` 绝不改动你的代码
（有自动化测试守着这条性质）。

```bash
# 先备份，再回滚：
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）被改坏时会自动回退，所以入口一般不会整体失效。
看到窗口里出现「维护清单回退」字样属正常兜底，不是失败。

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

```bash
npm run maintenance:generate
```

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

---

## 6. 日志/求助寄到哪

- **诊断文件**：`maintenance/logs/diagnostics-<时间戳>.md`（人读）和 `.json`（机读）。
- **每次双击的运行日志**：`maintenance/logs/` 下带时间戳的文件（窗口结尾会打印路径）。
- 求助时把上面的文件**整个发出去**，并说一句「我双击了哪个文件 / 跑了哪条命令」。
  日志含平台和每一步成败，足够维护者或 AI 定位。**这些文件不含 API 密钥，可放心外发。**

---

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

| 症状 | 双击 | 命令（不经 `khy` 简写，最抗坏） |
| --- | --- | --- |
| 不知哪坏了 | `维护-一键健康体检` | `node services/backend/bin/khy.js health` |
| 求助留证 | `维护-导出诊断日志` | `node maintenance/lib/ops.js diagnostics` |
| 查命脉断在哪 | `维护-快速烟雾测试更新发布回滚后` | `node maintenance/lib/ops.js smoke` |
| `khy` 没反应 | `维护-一键重装依赖` | `node services/backend/bin/khy.js --version` |
| 依赖坏了 | `维护-一键重装依赖` | `node maintenance/lib/ops.js reinstall` |
| 改前备份 | `维护-备份关键数据配置` | `node maintenance/lib/ops.js backup` |
| 升级搞砸回滚 | `维护-回滚到最近稳定版本` | `node maintenance/lib/ops.js rollback` |
| 发布出错 | `维护-发布后验证` | `node maintenance/lib/ops.js post-verify` |
| 登记好版本 | `维护-登记最近稳定版免记忆回滚` | `node maintenance/lib/ops.js bless` |
| 双击入口坏了 | （主清单修好后）`维护-更新项目到最新` | `npm run maintenance:generate` |

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