一句话先讲清
OpenCove 不是纯前端，是 Electron 本地开发工作台
React 负责画布界面；Electron 承接本机能力；PTY/Worker/CLI 跑终端、Agent 和自动化；SQLite 做本地持久化。
只改 UI，像前端；碰终端、文件、Agent、Worker、持久化，就进入桌面系统开发。
1. 架构怎么跑
用户拖拽节点、输入命令、启动 Codex/Claude Code
↓
Renderer：React + Vite画布、节点、面板、交互状态；这是最像前端的部分
↓ IPC 白名单
Preload Bridge通过 window.opencoveApi 暴露安全 API，Renderer 不能直接碰 Node
↓
Electron Main窗口、IPC、文件系统、Git、Clipboard、生命周期管理
↙ ↓ ↘
SQLite 持久化工作区、节点、恢复状态、终端输出等 local-first 数据
PTY Hostnode-pty 跑真实 shell / Agent CLI，隔离 native 风险
Worker / Web UI / CLI无桌面或自动化场景，提供 server/control surface 能力
理解重点：React 只是显示层；难点在多进程、本机能力、终端会话、状态恢复和安全边界。
2. 技术栈用了什么，为什么用
Electron桌面壳
让 Web UI 拿到本机文件、窗口、进程、系统能力，跨 macOS/Windows/Linux。
代价：包体和内存更大，IPC/安全边界复杂。
React 19 + ViteUI/HMR
复杂画布和节点 UI 开发效率高，HMR 反馈快。
代价：大画布性能和状态拆分要管住。
TypeScript类型边界
IPC、DTO、状态模型很多，类型能降低跨层错配。
代价：抽象设计不好会变成负担。
SQLite + better-sqlite3本地持久化
local-first、离线可用、恢复速度快，适合工作区状态。
代价：schema/migration/recovery 要严谨；native addon 增加打包坑。
xterm.js + node-pty真实终端
能运行 Codex/Claude Code 这类终端式 Agent，不只是模拟输出。
代价：PTY 跨平台差异、resize、崩溃隔离都很麻烦。
ZustandUI store
轻量管理 Renderer 展示状态。
代价：不能让 UI store 变成持久化事实 owner。
Playwright + Vitest验证
复杂交互、恢复、终端行为需要自动化回归。
代价：E2E 慢，但这类产品绕不开。
3. 这种架构的优势和劣势
优势
本地优先真实终端跨平台Web UI 效率适合多 Agent
- 能直接接本机项目、Git、文件系统和终端。
- 比纯 Web 更适合 AI Coding 工作流。
- 空间画布能同时看多个 Agent 的上下文。
劣势
Electron 重PTY 坑多IPC 安全复杂测试成本高
- 多进程和状态 owner 一旦混乱，会很难修。
- 终端/Worker/Agent 都是长生命周期，高风险。
- 跨平台打包、native addon、权限问题多。
4. 你做小功能优化，怎么选
低风险优先
- Renderer 展示层：按钮、空状态、hover、布局、复制提示。
- 文案/i18n：中英文同步，避免硬编码。
- 文档：CLI/Worker 安装说明、常见坑。
第一次别先碰
- PTY spawn/resize/lifecycle。
- SQLite schema / migration / recovery。
- Worker stop/start、Control Surface、IPC 权限。
- WSL/SSH/ACP 这种跨边界大功能。
首个 PR 的策略：只做一件事，小范围、可截图、可测试、容易 review。