architecture

架构技能

为 Electron 多进程项目确定正确的文件放置和结构。

详细参考

• 渲染进程层（组件、hooks、utils、pages、CSS）：references/renderer.md
• 主进程与共享层（bridges、services、worker、preload）：references/process.md
• 项目根目录与 monorepo 布局（目录结构、迁移状态）：references/project-layout.md

---

决策树 — 新代码应该放在哪里？

Is it UI (React components, hooks, pages)?
  └── YES → packages/desktop/src/renderer/              → see references/renderer.md

Is it an IPC handler responding to renderer calls?
  └── YES → packages/desktop/src/process/bridge/        → see references/process.md

Is it business logic running in the main process?
  └── YES → packages/desktop/src/process/services/      → see references/process.md

Is it an AI platform connection (API client, message protocol)?
  └── YES → packages/desktop/src/process/agent/<platform>/

Is it a background task that runs in a worker thread?
  └── YES → packages/desktop/src/process/worker/

Is it used by BOTH main and renderer processes?
  └── YES → packages/desktop/src/common/

Is it an HTTP/WebSocket endpoint?
  └── YES → packages/desktop/src/process/webserver/

Is it a plugin/extension resolver or loader?
  └── YES → packages/desktop/src/process/extensions/

Is it a messaging channel (Lark, DingTalk, Telegram)?
  └── YES → packages/desktop/src/process/channels/

---

进程边界规则

硬性规则 — 违反它们会导致运行时崩溃。

进程	可以使用	不能使用
主进程（packages/desktop/src/process/）	Node.js、Electron 主进程 API、fs、path、child_process	DOM API（document、window、React）
渲染进程（packages/desktop/src/renderer/）	DOM API、React、浏览器 API	Node.js API（fs、path）、Electron 主进程 API
Worker（packages/desktop/src/process/worker/）	Node.js API	DOM API、Electron API
Preload（packages/desktop/src/preload/）	contextBridge、ipcRenderer	DOM 操作、Node.js fs

跨进程通信：

• 主进程 ↔ 渲染进程：通过 packages/desktop/src/preload/ + packages/desktop/src/process/bridge/*.ts 进行 IPC
• 主进程 ↔ Worker：通过 packages/desktop/src/process/worker/WorkerProtocol.ts 进行 fork 协议通信

// NEVER in renderer
import { something } from '@process/services/foo'; // crashes at runtime

// Use IPC instead
const result = await window.api.someMethod(); // goes through preload

---

命名约定

目录

范围	约定	原因
渲染进程组件/模块目录	PascalCase	React 约定 — 目录名 = 组件名
其他所有内容	小写	Node.js 约定
分类目录（所有位置）	小写	components/、hooks/、utils/、services/
平台目录（所有位置）	小写	acp/、codex/、gemini/ — 跨进程一致性

快速判断：“位于 packages/desktop/src/renderer/ 内，并且代表特定的组件/功能（而非分类）？” → PascalCase。否则 → 小写。

文件

内容	约定	示例
React 组件、类	PascalCase	SettingsModal.tsx、CronService.ts
Hooks	camelCase，带 use 前缀	useTheme.ts、useCronJobs.ts
工具函数、辅助函数	camelCase	formatDate.ts、cronUtils.ts
入口点	index.ts / index.tsx	基于目录的模块必需
配置、类型、常量	camelCase	types.ts、constants.ts
样式	kebab-case 或 Name.module.css	chat-layout.css

---

结构规则

1. 目录大小限制：直接子项最多 10 个。接近上限时按职责拆分为子目录。
2. 禁止单文件目录：合并到父目录或相关目录。
3. 单文件与目录：如果某个组件需要私有的子组件或 hook，则转换为包含 index.tsx 的目录。
4. 页面私有优先：代码从 pages/<PageName>/ 开始。只有当出现第二个使用方时，才提升为共享代码。

测试文件映射

测试在 tests/ 子目录中镜像源文件：

源文件	测试
packages/desktop/src/process/services/CronService.ts	tests/unit/cronService.test.ts
packages/desktop/src/renderer/hooks/ui/useAutoScroll.ts	tests/unit/useAutoScroll.dom.test.ts
packages/desktop/src/process/extensions/ExtensionLoader.ts	tests/unit/extensions/extensionLoader.test.ts

当 tests/unit/ 的直接子项超过 10 个时，按与源文件结构匹配的子目录进行分组。

---

快速检查清单

• 代码位于正确的进程目录中（无跨进程导入）
• 渲染进程代码不使用 Node.js API
• 主进程代码不使用 DOM API
• 新的 IPC 通道通过 preload.ts 桥接
• 渲染进程组件/模块目录使用 PascalCase；分类目录使用小写
• 平台目录一律使用小写
• 基于目录的模块具有 index.tsx / index.ts 入口点
• 页面私有代码位于 pages/<PageName>/ 下，而非共享目录中
• 没有单文件目录
• 没有目录的直接子项超过 10 个
• 新的源文件被自动纳入覆盖率统计 — 验证它们未在 vitest.config.ts → coverage.exclude 中被意外排除
• 新的服务将纯逻辑与 IO 分离