AionUi Renderer 层架构指南：packages/desktop/src/renderer 的目录规范、UI 体系与编码约定

AionUi Renderer 层架构指南packages/desktop/src/renderer 的目录规范、UI 体系与编码约定【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi导读本文基于 AionUi 仓库中.claude/skills/architecture/references/renderer.md架构参考文档系统梳理 Electron 桌面端 Renderer渲染进程层的目录组织、UI 组件库选型、CSS 约定、Hooks/Utils 按业务域分组、页面模块结构以及共享代码的晋升规则。读完本文你将掌握在 AionUi 的 Renderer 层新增页面、组件、Hook 或工具函数时应当遵循的目录命名与放置规范理解base/与业务组件分层、平台目录acp/、codex/、gemini/的映射关系并能在实际开发中直接套用这些约定写出与现有代码库风格一致的代码。Renderer 层在整个项目中的位置AionUi 是本地优先local-first的开源桌面应用其桌面端代码位于packages/desktop/内部按 Electron 的多进程模型拆分为src/common/、src/preload/、src/process/与src/renderer/四大区域。其中Renderer 层packages/desktop/src/renderer/承担了全部 UI 职责——所有页面、组件、Hook、Context、客户端服务、工具函数、全局样式与静态资源都从这里进入打包产物。从源码结构可以推断AionUi 的 Renderer 层采用Vite React Arco Design UnoCSS的技术栈package.json 声明了arco-design/web-react^2.66.1作为组件库icon-park/react^1.4.2作为图标库unocss^66.3.3与unocss-preset-extra作为原子化 CSS 引擎index.html 是 Vite 的 HTML 入口其中内联脚本会同步从localStorage恢复__aionui_theme主题避免首帧主题闪烁theme flashmain.tsx 是 React 挂载与应用的引导入口。该目录布局由.claude/skills/architecture/references/renderer.md明确定义是 AionUi 前端开发者在提交代码前应遵守的架构契约。根目录标准布局10 项上限Renderer 根目录被严格约束为最多 3 个入口文件 7 个目录 10 个条目防止根目录膨胀失控packages/desktop/src/renderer/ ├── index.html # Vite HTML 入口 ├── main.tsx # React 挂载 应用引导bootstrap ├── types.d.ts # 全局环境类型声明ambient type declarations ├── pages/ # 页面级模块业务代码放在这里 ├── components/ # 共享 UI 组件跨多个页面复用 ├── hooks/ # 共享 React Hooks支持业务域子目录 ├── context/ # 全局 React Context ├── services/ # 客户端服务 i18n ├── utils/ # 工具函数 类型 常量 ├── styles/ # 全局样式 主题配置 └── assets/ # 静态资源 —— Vite 解析为带 hash 的 URL对照当前仓库实际目录renderer 根目录可以看到实际落地了assets/、components/、hooks/、pages/、services/、styles/、utils/等核心目录同时存在api/、theme/、pet/等业务扩展目录——这体现了目录规范服务于业务、允许按需生长的务实原则。不该出现在 Renderer 根目录的内容文档明确划出了三条红线CSS 文件→ 必须进入styles/组件文件.tsx→ 必须进入components/或pages/单文件目录→ 合并进相近的目录禁止为一个文件单开目录。UI 组件库与图标规范Renderer 层在 UI 选型上执行单一来源策略组件优先使用arco-design/web-react的 Arco 组件而不是自己封装原生标签图标全部来自icon-park/react仓库中的 IconParkHOC.tsx 即是对 IconPark 图标做统一高阶封装HOC的实现证据交互元素禁用裸 HTMLbutton、input、select等交互标签一律使用 Arco 等价组件如Button、Input、Select以保证主题、键盘导航、无障碍与多语言行为一致布局标签不受限div、span、section等布局标签可以自由使用。在 main.tsx 中可以印证 Arco 的深度集成应用不仅引入了ConfigProvider、Modal、Typography等组件还导入了arco-design/web-react/dist/css/arco.css全局样式并按zh-CN、zh-TW、ja-JP、ko-KR、en-US、tr-TR、ru-RU、pt-BR、de-DE、es-ES、fr-FR等语言注入 Arco 官方 localecompleteArcoLocale函数还会把缺失的Calendar、DatePicker、Form、ColorPicker片段用英文 locale 补齐ko-KR、tr-TR等即走此路径保证每个语言的 locale 都满足完整类型结构。CSS 约定UnoCSS 优先语义 Token 至上优先级金字塔优先使用 UnoCSS 工具类如flex items-center gap-8px直接写在 className 上复杂/可复用样式使用 CSS ModulesComponentName.module.css组件禁止使用普通.css文件语义化颜色 Token只能使用 uno.config.ts 中定义的 token如text-t-primary、bg-base、border-b-base或 CSS 变量禁止硬编码颜色唯一例外是CssThemeSettings/presets/主题预设目录内联样式仅允许用于动态计算的值Arco 样式覆写只能在组件自身的 CSS Module 中通过:global(.arco-xxx)完成禁止创建全局覆写文件全局样式只能放在packages/desktop/src/renderer/styles/当前仓库此处有arco-override.css、layout.css、markdown.css、themes/等。语义 Token 体系uno.config.ts 实况uno.config.ts 集中定义了完整的语义化颜色体系供 Renderer 层所有组件引用文字色text-t-primary--text-primary、text-t-secondary、text-t-tertiary、text-t-disabled语义状态色bg-primary、bg-success、bg-warning、bg-danger、bg-info同时支持text-/border-前缀背景色阶bg-base、bg-1到bg-10、bg-hover、bg-active数字键同时支持bg-*与border-*如border-1边框色border-b-base、border-b-light、border-b-1、border-b-2、border-b-3品牌色brand、brand-light、brand-hover以及 AOU 品牌色阶aou-1到aou-10组件专用色message-user、message-tips、workspace-btn等。uno.config.ts 还通过自定义规则桥接了 Arco Design 官方色板text-1~text-4、bg-fill-1~bg-fill-4、border-arco-1~border-arco-4、bg-primary-light-1~-light-4、bg-primary-1~-9、bg-popup等并定义了flex-centershortcut 与animate-wiggle动画规则。preflight 中把全局border-width归零、border-color设为transparent正是为了修复幽灵框单边 border 工具类回退到medium宽度显形与黑边border-color 回退到currentColor两类经典问题。components/固定层与业务层components/采用双层结构固定层Fixed layer——base/只放通用 UI 原语Modal、Select、ScrollArea 等不允许包含业务逻辑不允许依赖应用特定 Context不得依赖业务代码。当前仓库的 components/base/ 完美印证了这一点AionModal.tsx、AionSelect.tsx、AionScrollArea.tsx、AionSteps.tsx、AionCollapse.tsx、AionSearchInput.tsx、ModalWrapper.tsx、StepsWrapper.tsx等均是 Arco 组件的轻量再封装原语通过index.ts统一对外导出FeedbackButton.tsx、ButlerDiagnoseButton.tsx等按钮级组件也沉淀在此层。业务层Business layer——按业务域小写划分子目录packages/desktop/src/renderer/components/ ├── base/ # UI 原语 ├── chat/ # 会话/消息域 ├── agent/ # Agent 选择/配置 ├── settings/ # 设置域 ├── layout/ # 窗口框架与布局 ├── media/ # 文件预览、图片查看器 └── ... # 按需新增业务域当前仓库的 components/ 下确实存在base/、chat/、agent/、settings/、layout/、media/、workspace/等业务域目录与文档结构一一对应。其中chat/域包含AtFileMenu、AtSessionMenu、EmojiPicker、SendBox、SlashCommandMenu、SpeechInputButton、ThoughtDisplay等会话相关组件。约束根目录直接子项 ≤ 10base/不能依赖业务逻辑单页面组件 → 放到pages/PageName/components/不要提升到共享层。目录命名规则当同一业务域出现≥ 2 个共享组件时才创建子目录单个组件可以留在components/根目录直到出现第二个同域组件再下沉。hooks/与utils/按业务域分组分组阈值子项超过 10 个时必须按业务域分子目录通用 Hook / 工具函数留在根目录。hooks/推荐结构hooks/ ├── agent/ # Agent/model —— useModelProviderList、useAgentReadinessCheck ├── chat/ # 聊天/消息 —— useAutoTitle、useSendBoxDraft、useSlashCommands ├── file/ # 文件/工作区 —— useDragUpload、useOpenFileSelector ├── mcp/ # MCP 相关 ├── ui/ # 通用 UI —— useAutoScroll、useDebounce、useResizableSplit ├── system/ # 系统级 —— useDeepLink、useTheme、usePwaMode └── index.ts # 公共再导出可选当前仓库 hooks/ 落地了agent/、assistant/、chat/、config/、context/、file/、mcp/、system/、ui/等目录。以 hooks/chat/ 为例包含useAutoScroll.ts、useAutoTitle.ts、useSendBoxDraft.ts、useSlashCommands.ts、useSlashCommandController.ts、useSessionMentionSearch.ts、useTypingAnimation.ts等与文档中的命名示例高度吻合hooks/ui/ 则有useDebounce.ts、useThrottle.ts、useResizableSplit.tsx、useTextSelection.ts等通用 UI Hook。此外hooks/context/存放全局 Context如AuthContext、ThemeContext、FeedbackContext、ConversationHistoryContext均在 main.tsx 中被引入。utils/推荐结构utils/ ├── file/ # 文件处理 —— base64、fileType、download ├── workspace/ # 工作区 —— workspace、workspaceEvents、workspaceFs ├── chat/ # 聊天/消息 —— chatMinimapEvents、diffUtils、latexDelimiters ├── model/ # 模型/Agent —— agentLogo、modelCapabilities、modelContextLimits ├── theme/ # 主题/样式 —— customCssProcessor、themeCssSync ├── ui/ # 通用 UI —— clipboard、focus、siderTooltip、HOC ├── common.ts # 杂项工具 ├── emitter.ts └── platform.ts当前仓库 utils/ 落地了chat/、file/、model/、theme/、ui/、workspace/等子目录根目录保留common.ts、emitter.ts、platform.ts、url.ts、navigation.ts、appRestart.ts等通用工具与文档完全一致。utils/ui/runtimePatches更是在 main.tsx 中被作为运行时补丁提前导入。页面模块结构Page Module Structure每个页面模块使用PascalCase命名内部子目录采用精确命名、按需创建PageName/ # PascalCase ├── index.tsx # 入口必填 ├── components/ # 页面私有组件小写分类目录 │ ├── FeatureA.tsx # 简单子组件 │ └── FeatureB/ # 复杂子组件PascalCase │ └── index.tsx ├── hooks/ # 页面私有 Hooks ├── contexts/ # 页面私有 React Context ├── utils/ # 页面私有工具 ├── types.ts └── constants.ts原则只创建你真正需要的子目录并且必须使用这些确切的名字。页面级目录命名规范类型约定示例分类目录标准角色小写components/、hooks/、context/、utils/功能模块业务PascalCaseGroupedHistory/、Workspace/、Preview/平台目录小写acp/、codex/、gemini/镜像packages/desktop/src/process/agent/官方示例结构packages/desktop/src/renderer/ ├── components/ # 分类目录 → 小写 │ ├── SettingsModal/ # 组件 → PascalCase │ └── EmojiPicker/ # 组件 → PascalCase ├── pages/ # 分类目录 → 小写 │ ├── settings/ # 顶层页面 → 小写路由段 │ │ ├── CssThemeSettings/ # 功能模块 → PascalCase │ │ └── McpManagement/ # 功能模块 → PascalCase │ └── conversation/ # 顶层页面 → 小写 │ ├── GroupedHistory/ # 功能模块 → PascalCase │ ├── Workspace/ # 功能模块 → PascalCase │ ├── acp/ # 平台目录 → 小写 │ └── components/ # 分类目录 → 小写 └── hooks/ # 分类目录 → 小写当前仓库 pages/ 下存在conversation/、settings/、cron/、guid/、login/、team/等顶层页面其中conversation/内部承载了Preview/、GroupedHistory/等功能模块与文档规范一致。共享代码 vs 页面私有代码作用域存放位置仅被一个页面使用pages/PageName/components/、hooks/等页面私有目录被多个页面使用packages/desktop/src/renderer/components/、packages/desktop/src/renderer/hooks/晋升规则Promotion rule代码一律先放在页面私有位置只有当出现第二个消费者consumer时才提升到共享层。这条规则保证了共享层不会出现只有一处使用的孤儿组件是控制 Renderer 层复杂度持续可控的关键机制。组件入口点Component Entry Points目录型组件必须有index.tsx作为公共入口禁止从目录外部直接 import 目录内部文件必须走index.tsx。该约定在 components/base/index.ts 中落地所有 base 原语组件通过该 index 统一导出外部只允许引用目录公共入口。实践建议如何在 Renderer 层新增一个功能综合文档与仓库源码在 AionUi 的 Renderer 层新增功能时推荐按以下步骤操作判断作用域功能只属于单个页面 → 直接放进pages/PageName/对应私有目录components/、hooks/、utils/会被多个页面复用 → 放到共享层并确认当前组件是否触发第二个消费者晋升条件选择 UI 载体交互元素一律使用arco-design/web-react组件图标使用icon-park/react或复用IconParkHOC封装先尝试 UnoCSS 工具类完成布局处理样式简单样式用 UnoCSS 工具类如flex items-center gap-8px复杂样式写ComponentName.module.css颜色必须使用 uno.config.ts 中的语义 Token禁止硬编码色值需要覆写 Arco 样式时在该组件自身的 CSS Module 内用:global(.arco-xxx)遵守目录命名组件/页面/功能模块用 PascalCase分类目录用全小写平台相关目录acp/、codex/、gemini/镜像packages/desktop/src/process/agent/的命名控制根目录规模任何层级的目录直接子项超过约 10 个时按业务域拆分单文件目录一律合并提供公共入口目录型组件必须在index.tsx暴露公共 API外部不得直接引用内部文件全局样式不入组件除非放packages/desktop/src/renderer/styles/否则不要写全局 CSS 文件。总结AionUi 的 Renderer 层架构规范是一套自洽且可执行的目录即架构约定根目录 10 项上限保证入口清晰base/与业务域双层组件结构划清了原语与业务的边界Hooks/Utils 按业务域分组配合 10 子项阈值控制目录膨胀页面模块的精确命名分类小写、功能 PascalCase、平台小写让路由段、功能模块与 Agent 平台目录一眼可辨共享代码的第二消费者晋升规则则从机制上杜绝了共享层的孤儿代码。配合 Arco Design 组件库、IconPark 图标库、UnoCSS 语义 Token 与 CSS Modules 的四层样式策略Renderer 层能够在长期迭代中保持一致的视觉语言与可维护性。上述约定全部可以在当前仓库的 renderer.md 架构文档与packages/desktop/src/renderer/的实际代码中得到相互印证。【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考