AionUi 功能开发规范面向 AI 协作的功能需求模板与工程实践指南【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi本文围绕 AionUi 仓库中的 .aionui/FEATURE_DEV_TEMPLATE.md 展开系统讲解 AionUi基于 Electron 37 React 19 TypeScript 的本地优先 AI Cowork 桌面应用在面向 AI 描述功能开发需求时的标准化模板从功能概述、开发规范、实现架构到验收标准的完整填写方法与工程约定。读完本文你将掌握 AionUi 的进程分层、Bridge IPC 通信模式、命名与文件位置规范、国际化 Key 设计等核心开发约定并能在实际仓库中快速定位对应源码进行验证。1. 模板的定位让 AI 准确理解 AionUi 的功能需求.aionui/FEATURE_DEV_TEMPLATE.md是 AionUi 面向 AI 协作开发的一等公民工程资产。它的核心目的并非写给人类开发者的普通 PRD而是用于规范化向 AI 描述功能开发需求确保 AI无论是 IDE 中的编码助手还是独立 Agent能够准确理解任务并遵循项目既有约定从而减少需求模糊 → 实现偏差 → 返工的协作损耗。模板本身定义了完整的章节骨架功能概述用结构化字段说清做什么、给谁用、数据怎么流开发规范把 AionUi 的技术栈、命名、文件位置、代码风格、质量要求、禁止事项固化下来作为 AI 的行为约束实现架构要求填写涉及的分层架构、待新增/修改文件、IPC 通道设计、状态管理方案与 i18n Key验收标准从功能、边界情况、兼容性、代码质量四个维度给出可勾选的验收清单参考资料引导开发者列出项目中可参考的类似实现与依赖模块方便 AI按图索骥。这种模板 仓库源码的组合拳使得 AI 在开发时既能看到需求全貌又能通过相对路径直达既有实现是 AionUi 开源协作模式包括其 WebUI / Web-CLI / ACP 等多入口形态下保证代码一致性的关键机制。2. 功能概述结构化描述需求的第一步2.1 基本信息字段模板要求先填写四个维度的基本信息前两项决定了功能在仓库中的落点字段填写要点仓库中的对应关系功能名称简洁命名后续文件名、组件名、i18n key 都以此为锚点如conversation.export.*一类 key 前缀所属模块Agent 层 / 对话系统 / 预览系统 / 设置系统 / 工作区 / 其他对应 renderer/pages 下的页面目录涉及进程主进程(process) / 渲染进程(renderer) / WebServer / Worker对应 process 与 renderer 两大源码根功能描述1-3 句话说清核心目的与价值—2.2 用户场景与数据流模板要求用触发 → 过程 → 结果三段式描述用户场景触发: [用户如何触发此功能] 过程: [系统如何响应] 结果: [功能完成后的状态]并用输入/输出表定义数据流边界方向数据类型说明输入输出这套描述方式对 AI 特别友好它把何时调用、中间经历了什么、最终返回什么翻译成了可测试的行为契约直接为后续验收标准中的功能验收条目提供输入。3. 开发规范AionUi 的工程约束全集3.1 技术栈约束与仓库源码逐项对应模板将技术栈锁定如下我们可以在仓库 package.json 与 packages/desktop 中逐项验证技术项模板声明仓库实际版本/证据框架Electron 37 React 19 TypeScript 5.8package.json 中electron: ^37.10.3、react: ^19.1.0、typescript: ^5.8.3UI 库Arco Design (arco-design/web-react)已在 package.json 依赖中确认组件封装见 components/base如AionModal.tsx、AionSelect.tsx图标Icon Park (icon-park/react)依赖确认渲染层封装见 components/IconParkHOC.tsxCSSUnoCSS 原子化样式package.json 中unocss: ^66.3.3根目录配置见 uno.config.ts状态管理React ContextAuthContext / ConversationContext / ThemeContext / LayoutContext源码中 Context 实际位于 hooks/contextAuthContext.tsx、ThemeContext.tsx、LayoutContext.tsx、NavigationHistoryContext.tsx、ConversationHistoryContext.tsx等页面级 Context 散见于pages/**/context/IPC 通信项目内置 bridge 系统见下文第 4 节核心实现为 common/platform/bridge.ts国际化i18next react-i18next依赖确认语言包位于 renderer/services/i18n/locales共 13 种语言数据库better-sqlite3package.json 中better-sqlite3: ^12.4.1值得注意的是模板中提示的目录结构如src/process/bridge、src/common/在仓库中实际落在 packages/desktop/src 之下——AionUi 采用 monorepo 组织桌面端、Web 宿主、Web-CLI 分别位于packages/desktop、packages/web-host、packages/web-cli。阅读模板时需将src/前缀理解为packages/desktop/src/。3.2 命名规范从命名即可推断职责模板给出了一张命名速查表这些约定在仓库源码中都能找到实例类型规范模板示例仓库实例React 组件PascalCaseMessageList.tsx,FilePreview.tsxrenderer/pages/conversation/Messages/MessageList.tsxHooksuse前缀 PascalCaseuseAutoScroll.ts,useColorScheme.tshooks/chat/useAutoScroll.ts 与 pages/conversation/Messages/useAutoScroll.tsBridge 文件功能名 BridgeconversationBridge.ts,databaseBridge.tsprocess/bridge 下 12 个文件applicationBridge.ts、themeBridge.ts、updateBridge.ts、notificationBridge.ts等Service 文件功能名 ServiceWebuiService.tsrenderer/services/FileService.ts、SpeechToTextService.ts等接口类型I前缀ICreateConversationParams,IResponseMessagecommon/adapter/ipcBridge.ts 中的IStartOnBootStatus、IConfirmation等类型别名T前缀或直接命名TChatConversation,PresetAgentType同文件中大量TConversationRuntimeSummary、TProviderWithModel常量UPPER_SNAKE_CASEMAX_RETRY_COUNTprocess/bridge/applicationBridge.ts 中的START_ON_BOOT_WINDOWS_ARG工具函数camelCaseformatMessage,parseResponse—3.3 文件位置规范新增文件该放哪模板给出了完整的目录蓝图。结合仓库现状真实布局为packages/desktop/src/ ├── common/ # 跨进程共享模块adapter / api / chat / config / platform / theme / types / utils │ ├── platform/bridge.ts # Bridge 系统核心 │ └── adapter/ipcBridge.ts # IPC Bridge → HTTP/WS 适配层通道定义集中地 ├── process/ # Electron 主进程 │ ├── bridge/ # IPC 桥接定义12 个 Bridge 文件 │ ├── backend/ # 后端启动相关 │ ├── services/ # 主进程业务服务 │ ├── startup/ # 启动流程 │ └── utils/ # 主进程工具zoom、gpuRecovery、initStorage 等 ├── renderer/ # React 渲染进程 │ ├── components/ # 可复用 UI 组件base / chat / layout / media / settings / workspace │ ├── hooks/ # 自定义 Hooksagent / assistant / chat / config / context / file / mcp / system / ui │ ├── pages/ # 页面组件conversation / cron / guid / login / settings / team 等 │ ├── services/ # 前端服务FileService、SpeechToTextService、i18n 等 │ └── utils/ # 前端工具函数 └── types.d.ts # 类型声明模板中提到的src/agent/acp/codex/gemini 代理、src/webserver/WebUI 模式路由、src/worker/在当前仓库中已演化为独立包或调整位置Agent 相关类型集中在common/types/agent/WebServer 能力由 packages/web-host 提供。开发新功能时应优先按上述真实目录就近放置并保持渲染层放 renderer、主进程逻辑放 process、跨进程共享放 common的边界。3.4 代码风格Prettier 配置模板固化了 Prettier 配置semi: true、单引号含 JSX、ES5 尾随逗号、2 空格缩进、括号内空格、箭头函数恒括号、LF 换行。这是 AI 生成代码时的格式基准也是npm run lint当前仓库为oxlint的配套约定。3.5 质量要求与禁止事项质量要求勾选清单TypeScript 类型完整避免使用any使用 bridge 系统进行 IPC 通信实现错误边界处理支持国际化使用 i18next 的t()函数深色/浅色主题兼容响应式布局适配禁止事项❌❌ 直接使用ipcMain/ipcRenderer必须通过 bridge 系统❌ 在渲染进程直接访问 Node.js API❌ 硬编码中文/英文文本需使用 i18n key❌ 使用内联样式应使用 UnoCSS 类名❌ 在组件中直接操作 DOM使用 React ref❌ 忽略 TypeScript 错误ts-ignore其中必须通过 bridge 系统是 AionUi 最核心的架构红线下一节深入剖析其实现。4. 实现架构Bridge 通信系统的源码级原理4.1 三层分层架构模板给出的分层架构图与实际实现一致┌─────────────────────────────────────────────────────────┐ │ 用户界面 (UI) │ │ React 组件 / Hooks / Context │ └─────────────────────┬───────────────────────────────────┘ │ IPC Bridge ┌─────────────────────▼───────────────────────────────────┐ │ 主进程 (Main) │ │ Bridge → Service → Database / External API │ └─────────────────────┬───────────────────────────────────┘ │ ┌─────────────────────▼───────────────────────────────────┐ │ 数据层 (Data) │ │ SQLite / LocalStorage / External Services │ └─────────────────────────────────────────────────────────┘渲染进程不直接触达 Node.js API 与数据库一切经由 Bridge 转发到主进程。值得注意的是AionUi 在 common/adapter/ipcBridge.ts 中实现了IPC Bridge → HTTP/WS adapter的转换层除窗口控制、原生对话框、自动更新、CDP、深链等 Electron 原生操作外大量原 IPC 通道被替换为路由到 aioncore 的 REST/WebSocket 调用。这意味着 Bridge 通道的消费端既可以是 Electron IPC也可以是 HTTP/WS 传输——这也是 AionUi 能同时支撑桌面端与 WebUI 形态的底层原因。4.2 Bridge 核心原语Provider 与 Emitter模板要求新增 IPC 通道时遵循如下模式// src/process/bridge/[功能]Bridge.ts import { bridge } from /common/platform/bridge; export const [功能名] { // Provider 模式: 请求-响应 (类似 HTTP 请求) [方法名]: bridge.buildProviderTResponse, TParams([通道名]), // Emitter 模式: 事件流 (用于流式数据) [事件名]: bridge.buildEmitterTData([通道名].stream), }; // 使用示例: // 渲染进程调用: const result await [功能名].[方法名].request(params); // 渲染进程监听: [功能名].[事件名].on((data) { ... });模板中的request(params)对应源码中的invoke。我们可以在 common/platform/bridge.ts 中看到这两个原语的真实实现buildProviderData, Params(key)返回{ provider(handler), invoke(params) }两个端点invoke生成唯一请求 IDcreateRequestId以通道名 随机十六进制后缀组成通过subscribe-${key}事件发出{ id, data }并挂起一个 Promise 等待subscribe.callback-${key}${id}的回传从而实现类似 HTTP 的请求-响应语义bridge.tsprovider(handler)通过subscribe(key, handler)注册服务端处理函数。buildEmitterParams(key)返回{ on(callback), emit(params) }提供一对多的流式事件通道bridge.ts。此外on()还内置了interceptor拦截器机制普通通道的监听回调会先经过interceptors数组的异步校验subscribe*前缀通道除外这为权限控制、审计、统一鉴权预留了扩展点bridge.ts。4.3 真实 Bridge 实例themeBridge模板中的功能名 Bridge命名与实际实现完全一致。以 process/bridge/themeBridge.ts 为例它演示了主进程如何作为哑中继完成主题的跨窗口广播export function initThemeBridge(): void { // Renderer publishes a resolved theme → cache it and re-broadcast to all windows. ipcBridge.theme.setActive.provider(async (resolved: Theme) { cachedTheme resolved; ipcBridge.theme.changed.emit(resolved); listeners.forEach((l) l(resolved)); }); // A freshly-loaded window (e.g. pet) pulls the current theme on load. ipcBridge.theme.requestCurrent.provider(async () cachedTheme); }这段代码同时用到了 ProvidersetActive接收渲染进程发布的主题、requestCurrent响应新窗口的拉取请求与 Emitterchanged将主题变更广播给所有窗口是理解Provider 请求响应、Emitter 事件流两种模式如何协作的最佳范本。4.4 通道定义的集中地ipcBridge 适配层实际的通道类型定义集中在 common/adapter/ipcBridge.ts约 2500 行它导出了IConfirmation、IStartOnBootStatus、TChatConversation、Assistant、ITeamRunEvent等大量I/T前缀类型覆盖对话、团队、助手、Provider、配置等全部业务域。新增 IPC 通道时除了在process/bridge/下新增 Bridge 文件还需要在此处同步登记通道类型确保渲染进程与主进程共享同一份类型契约。4.5 状态管理设计与国际化 Key 设计状态管理模板要求明确四选一——复用现有 Context / 新增 Context / 仅组件内部状态useState/useReducer/ 需要持久化存储。AionUi 的全局 Context 集中于 hooks/context页面级 Context 则就近放置如pages/conversation/Preview/context/PreviewContext.tsx、pages/team/hooks/TeamPermissionContext.tsx新功能应优先复用而不是另起炉灶。国际化 Key模板给出 Key 命名规范[模块].[功能].[描述]及示例{ conversation.export.title: 导出对话, conversation.export.success: 导出成功, conversation.export.error: 导出失败 }仓库实际采用按模块拆分语言文件的组织方式语言包位于 renderer/services/i18n/locales每种语言zh-CN、en-US、zh-TW、ja-JP、ko-KR、de-DE、es-ES、fa-IR、fr-FR、pt-BR、ru-RU、tr-TR、uk-UA共 13 种下再按conversation.json、settings.json、team.json、mcp.json等模块分文件。例如 zh-CN/conversation.json 中实际存在export、exportDialogTitle、exportDialogSingleDescription等 key与模板[模块].[功能].[描述]的命名约定一脉相承。模板中标注zh-CN / en-US 必须仓库的实际语言覆盖已远超此要求开发时仍应保证至少这两份语言文件同步更新。5. 验收标准功能完成的判定依据模板从四个维度定义验收功能验收逐条列出具体功能点如点击导出按钮显示导出选项菜单。边界情况明确异常场景的处理如导出失败、空对话、并发操作。兼容性验收macOS 正常运行Windows 正常运行深色模式显示正确浅色模式显示正确多语言切换正常代码质量npm run lint无错误仓库实际为oxlint见 package.json scriptsnpm run build构建成功当前为electron-vite build打包链路TypeScript 无类型错误无 console.log 遗留这一节的价值在于把完成从主观判断变成可勾选的客观清单AI 在交付前可自行对照自检。6. 参考资料与完整使用示例模板要求开发者填写三类参考资料帮助 AI 找到抄作业的坐标类似功能参考列出项目中的类似实现如Markdown 导出、PDF 预览依赖的现有模块列出需要调用的接口/组件/Hook外部依赖如需引入新依赖需说明版本、用途与必要性——这是对依赖膨胀的显式闸门。完整示例对话导出 PDF模板内置的示例演示了上述所有章节如何落到一个真实功能上对话导出 PDF基本信息功能名对话导出 PDF所属模块勾选对话系统涉及进程勾选主进程 渲染进程。用户场景触发: 用户点击对话页面右上角的导出按钮选择导出为 PDF 过程: 系统收集对话内容渲染为 HTML转换为 PDF 结果: 弹出保存对话框用户选择保存位置后生成 PDF 文件文件规划进程文件路径操作说明主进程src/process/bridge/exportBridge.ts新增PDF 导出 IPC 通道定义主进程src/process/services/ExportService.ts新增PDF 生成逻辑渲染进程src/renderer/pages/conversation/components/ChatHeader.tsx修改添加导出下拉菜单渲染进程src/renderer/hooks/useExportPdf.ts新增导出功能 Hook功能验收点击导出按钮显示导出选项菜单选择 PDF 后弹出保存对话框生成的 PDF 包含完整对话内容代码块保留语法高亮样式图片正确嵌入 PDF类似功能参考useExportMarkdown.ts参考导出流程、PdfViewer.tsx参考 PDF 处理。值得一提的是导出对话在 AionUi 中已是真实功能仓库的conversation.json语言包中存在exportDialogTitle导出话题及导出为 JSON Markdown 并打包 ZIP的描述文案说明模板示例的功能方向与项目路线一致读者可以将模板示例作为理解仓库现有导出实现的入口。7. 模板维护约定与团队协同模板末尾记录了维护元信息创建日期 2025-01-27、适用版本 AionUi v0.x并约定如需更新模板请同步修改本文件并通知团队成员。这意味着该模板是一份活的规范当 AionUi 的技术栈如当前 Electron ^37 / React 19 / TypeScript ^5.8 / better-sqlite3 ^12.4.1或目录结构如src/演化为packages/desktop/src/发生演进时模板本身也必须随之更新否则 AI 会基于过时约束生成不兼容代码。模板文件与 AGENTS.md、CLAUDE.md、CONTRIBUTING.md 共同构成 AionUi 的 AI 协作知识底座其中模板聚焦单次功能开发任务的结构化描述而 docs/contributing/file-structure.md 等文档则负责更宏观的工程背景说明。结语让 AI 从会写代码到写对代码AionUi 的FEATURE_DEV_TEMPLATE.md提供了一种可复用的工程实践用结构化的需求模板 明确的工程约束 可直达的源码坐标把 AI 的能力约束在项目既定的架构轨道上。对于开发者而言遵循该模板填写需求等于同时完成了需求分析、技术设计、文件规划和验收定义四件事对于 AI 而言模板中的命名规范、Bridge 模式、i18n Key 设计与禁止事项就是一份高质量的系统提示词。两者结合才能在 Electron React 的复杂桌面应用中稳定地产出符合 AionUi 工程基因的代码。如需进一步深入可对照阅读 common/platform/bridge.tsBridge 内核、common/adapter/ipcBridge.ts通道类型契约、process/bridge/themeBridge.tsBridge 实战范例以及 renderer/services/i18n/locales国际化组织方式。【免费下载链接】AionUi免费、本地、开源的 24/7 全天候 Cowork 应用以及适用于 Gemini CLI、Claude Code、Codex、OpenCode、Qwen Code、Goose CLI、Auggie 等的 OpenClaw | 喜欢就点star吧项目地址: https://gitcode.com/iOfficeAI/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考