-
Notifications
You must be signed in to change notification settings - Fork 3
Issues Summary
🌐 Language: English | 中文
This page summarizes recurring problem patterns from KinetAios development (v1.0.0 → v1.6.0, 116 fix commits). It exists to help contributors avoid repeating the same mistakes.
| Category | Fixes | Severity |
|---|---|---|
| CSS / Layout | ~30 | 🔴 Highest |
| Plugin system | ~18 | 🔴 Highest |
| Screenshot / Voice / Media | ~10 | 🟡 Medium |
| Feature interaction / Logic | ~10 | 🟡 Medium |
| Model / API config | ~8 | 🟡 Medium |
| Security / Robustness | ~6 | 🟠 Medium-High |
| Visual Inspector | 4 | 🟡 Medium |
| i18n | ~4 | 🟢 Low |
| CI / Packaging | ~5 | 🟢 Low |
Symptom: switching tabs in settings caused the panel width to jump.
Root cause: #settings-view and #settings both had overflow-y: auto. The outer scrollbar appeared/disappeared based on content length, causing width changes. scrollbar-gutter: stable was only on the inner element.
Fix: outer #settings-view → overflow: hidden; only inner #settings scrolls with scrollbar-gutter: stable.
Lesson: One scroll container per scroll chain. Never nest two overflow-y: auto elements.
Symptom: panel appeared in wrong position, chat area compressed.
Root cause: #town-view had display: flex which overrode .view { display: none }. Also, #town-panel inside #main (a flex column) interfered with layout despite position: fixed.
Fix: moved #town-panel and #town-backdrop out of #main to #app level. #town-view respects the generic .view display rules.
Lesson: position: fixed elements should still be placed outside flex containers to avoid rendering edge cases.
Symptom: plugin panel blank, loading stuck forever, elements invisible.
Root cause: polling field name mismatch, Excalidraw element schema mismatch, CDN load failure, CSP blocking scripts.
Fix: switched from polling to event push, used convertToExcalidrawElements, iframe isolation for CSP.
Lesson: test each integration point independently. Don't assume third-party APIs work.
Symptom: clicks not responding, IPC delays, AI no response.
Root cause: IPC round-trip between renderer and main was unreliable for real-time interaction.
Fix: moved overlay to renderer layer, used webview.executeJavaScript directly, bypassed main process IPC.
Lesson: for real-time UI interaction, stay in the renderer process. Avoid IPC for latency-sensitive operations.
Symptom: channel text appeared centered instead of left-aligned.
Root cause: #conv-list > li:not(.sb-proj) lacked flex-direction: row, so align-items: center from a parent rule caused horizontal centering.
Fix: added flex-direction: column explicitly.
Lesson: always check inherited flex properties when debugging alignment. Flex properties cascade.
Several commits claimed "彻底修复" (completely fixed) only to be followed by another fix for the same issue. This indicates insufficient verification.
Improvement: always verify in the running app before claiming a fix is complete. Don't write "彻底修复" in commit messages.
30+ fixes were CSS layout issues: flex nesting, overflow nesting, position: fixed vs flex interaction, scrollbar-gutter.
Improvement: establish a standard "scroll container" pattern — one overflow-y: auto + scrollbar-gutter: stable per scroll chain. Document the layout rules.
Every security audit found new issues: SSRF, timing attacks, listener leaks, argument injection, regex injection.
Improvement: consider security from the design phase. Don't rely on post-hoc audits.
Visual Inspector, brainstorm plugin, and remote task button all required IPC communication rewrites.
Improvement: design the "who sends, who receives, who handles errors" flow before coding. Don't code first and rework later.
See ISSUES_SUMMARY.md in the repo root for the complete 116-fix breakdown.