<!-- 文档分类: IMPL-RPT-015 | 阶段: 实现 | 原路径: docs/指南/修复记录时间线.md -->
# KHY OS 修复记录时间线

> 作用：汇总项目中的重大修复、事故复盘与关键稳定性修正，方便快速回溯“问题是什么、什么时候修、修到了哪篇文档”
> 更新时间：2026-06-10

---

## 一、收录范围

本页只收录对以下维度有明显影响的修复：

1. 终端交互与交付体验
2. AI 网关稳定性与超时机制
3. 认证、会话、兼容性冲突
4. 守护进程、端口发现、运行时可达性
5. 导致严重故障的事故复盘

不收录普通功能迭代、一般性优化和纯规划路线图。

> **另一类 bug 见 [IMPL-RPT-032]**：根因隐蔽、修复方法可迁移的一类（TUI vs 经典 REPL 界面漂移、
> half-wired 半接线、幽灵显示、前端「按类别聚合」的结构陷阱）。本页收 P0/P1 硬故障，
> [IMPL-RPT-032] 收「有学习价值」的定位法与套路。

---

## 二、时间线总表

| 日期 | 级别 | 主题 | 核心问题 | 文档 |
|------|------|------|---------|------|
| 2026-06-10 | P1 | 网关 IDE 适配器可用性严格化 | Cursor/Windsurf/Warp 未安装却显示「可用」；可用性只看 token、从不 AND 安装+真实登录 | [网关适配器可用性严格化](%5BIMPL-RPT-010%5D%20网关适配器可用性严格化-本地安装与登录-2026-06-10.md) |
| 2026-05-31 | P0 | 终端提示符泄漏与交付空行修复 | `❯` busy prompt 泄漏到正式输出前缀；执行过程与正文粘连 | [终端提示符泄漏与交付空行修复](%5BIMPL-RPT-019%5D%20终端提示符泄漏与交付空行修复-2026-05-31.md) |
| 2026-05-29 | P0 | 网关断链问题修复 | 多层 idle watchdog、错误分类过激、SSE 尾包丢失导致“经常断链” | [网关传输韧性修复](%5BIMPL-RPT-020%5D%20网关传输韧性修复-2026-05-29.md) |
| 2026-05-27 | P0 | KHY 与 Claude Code 认证冲突修复 | KHY 向 Claude 设置中注入本地 key，污染外部 Anthropic 登录态，触发 401 | [KHY Claude 认证冲突修复](%5BIMPL-RPT-013%5D%20khy-claude-认证冲突修复.md) |
| 2026-05-25 | P1 | Trae 官方登录态扫描修复 | 无法识别官方 IDE 加密登录态，端点候选错误，导致状态误判与调用失败 | [Trae 适配器官方扫描修复](%5BIMPL-RPT-014%5D%20trae-适配器-官方扫描修复-2026-05-25.md) |
| 2026-05-21 | P1 | 守护进程端口发现修复 | 多入口启动后端口漂移，但下游仍硬连 9090，导致白屏、504、WS 失败 | [守护进程端口发现修复](%5BIMPL-RPT-017%5D%20守护进程端口发现修复.md) |
| 2026-05-19 | P1 | 网关超时优化与 REPL 输入框边框修复 | `/gateway` 卡住过久；REPL 输入边框首次后消失 | [网关超时与帧修复](%5BIMPL-RPT-021%5D%20网关超时与帧修复.md) |
| 2026-05-24 | P1 | 剪贴板粘贴修复 | 终端粘贴内容被自动发送给 AI，用户无法编辑后再提交 | [剪贴板粘贴修复](%5BIMPL-RPT-016%5D%20剪贴板粘贴修复.md) |
| 2026-05-09 | P0 事故 | 终端崩溃事后分析 | ISO 构建中断后清理逻辑破坏宿主机 `/dev` 与 `/dev/pts` | [终端崩溃事后分析](../08_MGMT_项目管理/%5BMGMT-OTHER-002%5D%20事后分析-终端崩溃-2026-05-09.md) |

---

## 三、阶段观察

### 2026-05-09 → 2026-05-19

这一阶段的重点是**防止系统级和交互级的硬故障**：

- 先处理了最严重的宿主终端破坏事故
- 随后开始修复 `/gateway` 卡死和 REPL 输入边框错乱

关键词：

- mount/cleanup 安全
- timeout 上限
- 终端输入框稳定性

### 2026-05-21 → 2026-05-27

这一阶段的重点是**连通性与兼容性**：

- daemon 端口漂移后的发现机制
- 第三方 IDE / Claude / Trae 的认证与登录态兼容

关键词：

- runtime 发现文件
- 外部认证保护
- 加密 artifact 识别

### 2026-05-29 → 2026-05-31

这一阶段的重点是**AI 交付链路韧性与终端交付质量**：

- 先修网关断链、尾包丢失、误熔断
- 再修终端 busy prompt 泄漏与“过程/正文”边界不清

关键词：

- sliding idle timeout
- SSE flush
- scrollback 纯净
- delivery boundary

---

## 四、按问题类型归档

### 4.1 终端 / CLI 显示

- [终端提示符泄漏与交付空行修复](%5BIMPL-RPT-019%5D%20终端提示符泄漏与交付空行修复-2026-05-31.md)
- [网关超时与帧修复](%5BIMPL-RPT-021%5D%20网关超时与帧修复.md)
- [剪贴板粘贴修复](%5BIMPL-RPT-016%5D%20剪贴板粘贴修复.md)
- [终端崩溃事后分析](../08_MGMT_项目管理/%5BMGMT-OTHER-002%5D%20事后分析-终端崩溃-2026-05-09.md)

### 4.2 网关 / 传输 / 超时

- [网关传输韧性修复](%5BIMPL-RPT-020%5D%20网关传输韧性修复-2026-05-29.md)
- [网关超时与帧修复](%5BIMPL-RPT-021%5D%20网关超时与帧修复.md)

### 4.3 认证 / 登录态 / 外部兼容

- [网关适配器可用性严格化](%5BIMPL-RPT-010%5D%20网关适配器可用性严格化-本地安装与登录-2026-06-10.md)
- [KHY Claude 认证冲突修复](%5BIMPL-RPT-013%5D%20khy-claude-认证冲突修复.md)
- [Trae 适配器官方扫描修复](%5BIMPL-RPT-014%5D%20trae-适配器-官方扫描修复-2026-05-25.md)

### 4.4 运行时发现 / 端口 / 守护进程

- [守护进程端口发现修复](%5BIMPL-RPT-017%5D%20守护进程端口发现修复.md)

---

## 五、当前高频修复主题

从现有记录看，项目中的“大修复”主要集中在四类：

1. **终端渲染状态机不稳定**
   - prompt、frame、paste、正文边界、scrollback
2. **网关链路过于激进**
   - 硬超时、误判断链、错误分类放大
3. **多入口运行时缺少统一发现机制**
   - 实际端口变化后，下游消费者感知不到
4. **外部工具/IDE 的登录态边界不清**
   - KHY 注入行为覆盖或污染用户自己的认证配置

这四类问题在后续开发中应被视为高风险区。

---

## 六、维护约定

后续新增重大修复文档时，建议同时做三件事：

1. 在对应文档中写清：
   - 问题现象
   - 根因
   - 修复方案
   - 验证结果
2. 在 [文档索引](../08_MGMT_项目管理/%5BMGMT-OTHER-003%5D%20索引.md) 的“修复记录”中补入口
3. 在本页“时间线总表”顶部追加一行

推荐字段：

| 字段 | 说明 |
|------|------|
| 日期 | 修复落地日期 |
| 级别 | `P0` / `P1` / `事故` |
| 主题 | 一句话命名 |
| 核心问题 | 最直接的用户可见症状 |
| 文档 | 详细修复报告链接 |

---

## 七、使用方式

如果你是：

- **开发者**：先看本页定位历史修复，再进具体报告看实现细节
- **回归测试人员**：优先看最近两周的 P0/P1 修复，构造复现场景
- **产品/验收人员**：从“核心问题”列判断某次修复是不是用户真实痛点

本页不代替详细修复报告，它是项目级“修复导航页”。
