跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
法律与合规

architecture

Project architecture and file structure conventions for all process types. Use when: (1) Creating new files or modules, (2) Deciding where code should go, (3) Converting single-file components to directories, (4) Reviewing code for structure compliance, (5) Adding new bridges, services, agents, or workers.

iOfficeAI · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add iOfficeAI/AionUi --skill architecture

技能说明


name: architecture description: | Project architecture and file structure conventions for all process types. Use when: (1) Creating new files or modules, (2) Deciding where code should go, (3) Converting single-file components to directories, (4) Reviewing code for structure compliance, (5) Adding new bridges, services, agents, or workers.

Architecture Skill

Determine correct file placement and structure for an Electron multi-process project.

Detailed References

  • Renderer layer (components, hooks, utils, pages, CSS): references/renderer.md
  • Main process & shared layer (bridges, services, worker, preload): references/process.md
  • Project root & monorepo layout (directory structure, migration status): references/project-layout.md

Decision Tree — Where Does New Code Go?

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/

Process Boundary Rules

Hard rules — violating them causes runtime crashes.

ProcessCan useCannot use
Main (packages/desktop/src/process/)Node.js, Electron main APIs, fs, path, child_processDOM APIs (document, window, React)
Renderer (packages/desktop/src/renderer/)DOM APIs, React, browser APIsNode.js APIs (fs, path), Electron main APIs
Worker (packages/desktop/src/process/worker/)Node.js APIsDOM APIs, Electron APIs
Preload (packages/desktop/src/preload/)contextBridge, ipcRendererDOM manipulation, Node.js fs

Cross-process communication:

  • Main ↔ Renderer: IPC via packages/desktop/src/preload/ + packages/desktop/src/process/bridge/*.ts
  • Main ↔ Worker: fork protocol via packages/desktop/src/process/worker/WorkerProtocol.ts
// NEVER in renderer
import { something } from '@process/services/foo'; // crashes at runtime

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

Naming Conventions

Directories

ScopeConventionReason
Renderer component/module dirsPascalCaseReact convention — dir name = component name
Everything elselowercaseNode.js convention
Categorical dirs (everywhere)lowercasecomponents/, hooks/, utils/, services/
Platform dirs (everywhere)lowercaseacp/, codex/, gemini/ — cross-process consistency

Quick test: "Inside packages/desktop/src/renderer/ AND represents a specific component/feature (not a category)?" → PascalCase. Otherwise → lowercase.

Files

ContentConventionExamples
React components, classesPascalCaseSettingsModal.tsx, CronService.ts
HookscamelCase with use prefixuseTheme.ts, useCronJobs.ts
Utilities, helperscamelCaseformatDate.ts, cronUtils.ts
Entry pointsindex.ts / index.tsxRequired for directory-based modules
Config, types, constantscamelCasetypes.ts, constants.ts
Styleskebab-case or Name.module.csschat-layout.css

Structural Rules

  1. Directory size limit: Max 10 direct children. Split into subdirectories by responsibility when approaching.
  2. No single-file directories: Merge into parent or related directory.
  3. Single file vs directory: If a component needs a private sub-component or hook, convert to a directory with index.tsx.
  4. Page-private first: Start code in pages/<PageName>/. Promote to shared only when a second consumer appears.

Test File Mapping

Tests mirror source files in tests/ subdirectories:

SourceTest
packages/desktop/src/process/services/CronService.ts`tests/
阅读完整来源 ↗