> 🌐 Language: [English](Issues-Summary) | **中文**

# 已知问题与经验教训

本页总结 KinetAios 开发中的反复问题模式(v1.0.0 → v1.6.0,116 个 fix commit)。帮助贡献者避免重蹈覆辙。

## 数据概览

| 类别 | 修复次数 | 严重度 |
|---|---|---|
| CSS / 布局 | ~30 | 🔴 最高 |
| 插件系统 | ~18 | 🔴 最高 |
| 截图 / 语音 / 媒体 | ~10 | 🟡 中 |
| 功能交互 / 逻辑 | ~10 | 🟡 中 |
| 模型 / API 配置 | ~8 | 🟡 中 |
| 安全 / 健壮性 | ~6 | 🟠 中高 |
| Visual Inspector | 4 | 🟡 中 |
| i18n | ~4 | 🟢 低 |
| CI / 打包 | ~5 | 🟢 低 |

## 五大反复问题

### 1. 设置页 tab 切换宽度跳变(7 轮!)

**症状**:设置页切换 tab 时面板宽度跳变。

**根因**:`#settings-view` 和 `#settings` 两层都设了 `overflow-y: auto`。外层滚动条根据内容长度出现/消失,导致宽度变化。`scrollbar-gutter: stable` 只在内层。

**修复**:外层 `#settings-view` → `overflow: hidden`;只让内层 `#settings` 滚动 + `scrollbar-gutter: stable`。

**教训**:**一条滚动链上只用一层 `overflow-y: auto`。** 永远不要嵌套两个 `overflow-y: auto`。

### 2. Town panel 定位(5 轮)

**症状**:面板位置不对,chat 区域被压缩。

**根因**:`#town-view` 的 `display: flex` 覆盖了 `.view { display: none }`。`#town-panel` 在 `#main`(flex column)内,虽然有 `position: fixed` 仍干扰布局。

**修复**:把 `#town-panel` 和 `#town-backdrop` 从 `#main` 移到 `#app` 层。`#town-view` 遵循通用 `.view` display 规则。

**教训**:`position: fixed` 元素仍应放在 flex 容器之外,避免渲染边界问题。

### 3. brainstorm 插件(5 轮)

**症状**:插件面板空白,loading 永久卡住,元素不可见。

**根因**:轮询字段名不匹配、Excalidraw 元素 schema 不匹配、CDN 加载失败、CSP 阻止脚本。

**修复**:轮询改事件推送,用 `convertToExcalidrawElements`,iframe 隔离解决 CSP。

**教训**:逐个集成点独立测试。不要假设第三方 API 能正常工作。

### 4. Visual Inspector(4 轮)

**症状**:点击无响应,IPC 延迟,AI 无响应。

**根因**:renderer 和 main 之间的 IPC 往返对实时交互不可靠。

**修复**:overlay 移到 renderer 层,直接用 `webview.executeJavaScript`,绕过主进程 IPC。

**教训**:实时 UI 交互应留在 renderer 进程。延迟敏感操作避免走 IPC。

### 5. 侧边栏频道文字居中(3 轮)

**症状**:频道文字显示为居中而非左对齐。

**根因**:`#conv-list > li:not(.sb-proj)` 缺少 `flex-direction: row`,父规则的 `align-items: center` 导致水平居中。

**修复**:显式加 `flex-direction: column`。

**教训**:**调试对齐问题时检查继承的 flex 属性**。flex 属性会级联。

## 问题模式

### 模式 1:"彻底修复"后再次修复

多个 commit 声称"彻底修复",下个 commit 又修同一问题。说明验证不足。

**改进**:在运行中的 app 里验证后再声称修复完成。不要在 commit message 里写"彻底修复"。

### 模式 2:CSS 布局知识薄弱

30+ 个修复是 CSS 布局问题:flex 嵌套、overflow 嵌套、`position: fixed` 与 flex 干扰、`scrollbar-gutter`。

**改进**:建立标准"滚动容器"模式——每条滚动链一层 `overflow-y: auto` + `scrollbar-gutter: stable`。文档化布局规则。

### 模式 3:补丁式安全修复

每次安全审查都发现新问题:SSRF、计时攻击、监听器泄漏、参数注入、正则注入。

**改进**:设计阶段就考虑安全。不要依赖事后审计。

### 模式 4:IPC 通信架构反复

Visual Inspector、brainstorm 插件、远程任务按钮都需要 IPC 通信重写。

**改进**:编码前先设计"谁发、谁收、谁兜底"的流程。不要先写再推翻。

## 完整列表

见 repo 根目录的 `ISSUES_SUMMARY.md` 获取完整 116 个 fix 的分类明细。