AionUi 协作开发指南面向人类与 AI Agent 的统一工程规范解读【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi本指南以仓库根目录的 AGENTS.md 为骨架结合 CONTRIBUTING.md、docs/contributing/file-structure.md、docs/contributing/development.md、.claude/skills/技能体系与justfile、vitest.config.ts等工程配置系统解读 AionUi 的代码规范、架构约束、测试标准与提交流程。读完本文你将掌握在 AionUi 多进程 Electron 仓库中正确地放置新文件、遵守命名与样式规范、通过 lint/format/typecheck/i18n 校验门禁并安全地完成just push与 PR 提交流程。AionUi 是一个将命令行 AI Agent 包装为现代化聊天界面的开源项目技术栈为 Electron React 19 TypeScript Vite/UnoCSS better-sqlite3测试框架为 Vitest 4。它的特殊之处在于贡献者既包括人类也包括各类 AI Agent。为此仓库在根目录维护了一份AGENTS.md把过程边界、命名、样式、i18n、测试、提交门禁等规则压缩成一份可被 Agent 直接执行的工程宪章。本文逐一展开这些规则并下沉到源码与配置文件给出可验证的依据。一、File Directory Structure目录即架构1.1 目录大小上限≤ 10 个直接子项AGENTS.md规定每个目录的直接子项文件 子目录不应超过 10 个新建或大规模重组的目录必须满足该约束。这条规则在 docs/contributing/file-structure.md 中有更完整的展开当tests/unit/超过 10 个直接子项时按源码结构归入子目录如tests/unit/extensions/渲染层的components/、hooks/、utils/根目录同样必须保持 ≤ 10 个直接子项超限后按业务领域分组chat/、agent/、settings/、layout/、media/等渲染层根目录被严格限定为3 个入口文件 7 个目录 10 项的标准布局。这条规则的深层动机是可导航性一个目录子项超过 10 个后人类和 Agent 都难以快速理解其职责边界而目录名如bridge/、services/、database/本身就是架构文档。1.2 命名规范速查内容约定示例React 组件 / 类PascalCaseButton.tsx、Modal.tsx、CronService.ts工具函数camelCaseformatDate.ts、cronUtils.tsHookscamelCase use前缀useTheme.ts、useCronJobs.ts常量文件camelCase内部值用 UPPER_SNAKE_CASEconstants.ts类型文件camelCasetypes.ts样式文件kebab-case 或ComponentName.module.csschat-layout.css未使用参数前缀__index目录命名存在双生态约定渲染层packages/desktop/src/renderer/沿用 React 生态的 PascalCase目录名 组件名其余一切主进程、common 层沿用 Node.js 生态的 lowercasecomponents/、hooks/、utils/、services/这类类别目录一律 lowercase平台目录acp/、codex/、gemini/等即使在渲染层内也必须 lowercase以与src/process/agent/platform/跨进程保持一致。文档给出了一条快速判断口诀该目录是否位于src/renderer/内并且代表一个具体组件或功能模块而非类别是 → PascalCase否 → lowercase。1.3 主进程内部的类型化命名主进程模块遵循更细的类型命名模式见 docs/contributing/file-structure.md类型模式示例IPC BridgedomainBridge.tscronBridge.ts、webuiBridge.tsServiceNameService.tsCronService.ts、McpService.tsInterfaceINameService.tsIConversationService.tsRepositoryNameRepository.tsSqliteConversationRepository.ts这与仓库实际结构吻合packages/desktop/src/process/下包含bridge、services、backend、startup等目录预加载层packages/desktop/src/preload/提供main.ts、petPreload.ts等入口。二、UI 与 CSSArco 组件 语义化主题 Token2.1 组件与图标来源AGENTS.md明确 UI 组件库为arco-design/web-react图标库为icon-park/react并有一条硬性约束禁止使用原生交互 HTMLbutton、input、select等必须使用对应 Arco 组件Button、Input、Select、Modal。纯布局/语义标签div、span、section、nav、main不受限。这条规则在 docs/contributing/file-structure.md 中被列为硬性要求并在AGENTS.md的 Hard blockers 中再次出现——新增 UI 中出现原生交互 HTML 属于硬性阻断项会直接导致 PR 被拒。2.2 CSS 三层策略优先 UnoCSS 原子类简单样式用flex items-center gap-8px复杂/可复用样式用 CSS ModulesComponentName.module.css禁止为组件样式使用裸.css文件颜色只用语义化 token来自uno.config.ts如text-t-primary、bg-base、border-b-base或 CSS 变量禁止硬编码颜色值如#86909C、rgb(0,0,0)。唯一例外是CssThemeSettings/presets/下的主题预设文件——它们本身就是 token 的定义者。此外行内样式style{{}}仅允许用于动态计算值宽度、位置Arco 主题覆盖集中在 packages/desktop/src/renderer/styles/arco-override.css组件作用域的 Arco 覆盖用 CSS Module 配合:global()全局样式只允许放在packages/desktop/src/renderer/styles/仓库中可见MIGRATION.md、arco-override.css、colors.ts、layout.css、markdown.css、themes/。2.3 格式化规则Oxfmt兼容 Prettier单元素数组若可在一行放得下 → 内联[{ id: a, value: b }]多行数组/对象要求尾逗号字符串统一使用单引号。这些规则由bun run formatoxfmt自动执行bun run format:check用于只读校验。三、TypeScript 与 i18n类型安全与国际化红线3.1 TypeScript 严格模式严格模式开启禁止any、禁止隐式返回路径别名/*、process/*、renderer/*对应 vitest.config.ts 中/ → packages/desktop/src、process/ → packages/desktop/src/process、renderer/ → packages/desktop/src/renderer的别名解析测试环境与运行时保持一致优先type而非interface遵循 Oxlint 配置代码注释使用英文公共函数写 JSDoc。3.2 i18n所有面向用户的文本必须走 keyAGENTS.md要求新增或修改面向用户的文本必须使用 i18n key禁止硬编码字符串。语言与模块的单一事实来源是 packages/desktop/src/common/config/i18n-config.json——当前支持 13 种语言zh-CN、en-US、ja-JP、zh-TW、ko-KR、tr-TR、ru-RU、uk-UA、pt-BR、de-DE、es-ES、fr-FR、fa-IR参考语言为en-US共 19 个模块common、agentMode、conversation、settings、cron、agent、team、pet等。完整的 i18n 工作流在.claude/skills/i18n/SKILL.md中定义核心要点Key 结构代码中使用命名空间点号记法t(module.key)或t(module.nested.key)key 命名用 camelCase可复用文本放common模块所有语言都要加新 key 必须同步到supportedLanguages中的每一个语言目录缺失任一语言会导致node scripts/check-i18n.js在 CI 中失败校验顺序先bun run i18n:types重新生成i18n-keys.d.ts自动生成、禁止手改再node scripts/check-i18n.js校验结构与类型同步硬编码检测JSX 中禁止出现硬编码的中英文如spanDelete/span、{name || 新对话}必须改为{t(common.delete)}、{name || t(conversation.newConversation)}代码注释、console.log、内部常量字符串属于例外插值与富文本变量用t(cron.taskCount, { count: 5 })复杂标记用Trans组件zh-TW 维护多数词条可从 zh-CN 自动转换但「视频→影片」「软件→軟體」「信息→訊息」「默认→預設」等需要人工核对。四、Architecture双进程边界是运行时安全线4.1 两类进程API 永不相混AGENTS.md用一张表划定了硬边界进程路径限制Main主进程packages/desktop/src/process/禁止 DOM APIRenderer渲染进程packages/desktop/src/renderer/禁止 Node.js API跨进程通信必须经过 IPC bridgepackages/desktop/src/preload/主进程侧对应packages/desktop/src/process/bridge/*.ts。违反边界会造成运行时崩溃——例如在渲染进程里import { something } from process/services/foo会直接 crash正确做法是通过 preload 暴露的window.api.someMethod()走 IPC。从源码结构看仓库实际落地了这一边界packages/desktop/src/process/主进程业务bridge/、services/、backend/、startup/、feedback/、pet/、utils/可以自由使用 Node.js/Electron APIpackages/desktop/src/renderer/React 界面979 个文件只能访问 DOM/browser APIpackages/desktop/src/preload/contextBridge层是 main ↔ renderer 之间唯一的 IPC 通道packages/desktop/src/common/跨进程共享的类型、适配器与工具100 个.ts文件不归属任何单一进程。.claude/skills/architecture/SKILL.md还给出了新代码放哪儿的决策树UI →renderer/IPC handler →process/bridge/主进程业务逻辑 →process/services/AI 平台连接 →process/agent/platform/后台任务 →process/worker/双进程共用 →common/HTTP/WebSocket 端点 →process/webserver/插件加载器 →process/extensions/消息通道飞书/钉钉/Telegram→process/channels/。4.2 服务可测试性规则docs/contributing/file-structure.md 进一步规定 Service 必须分离纯逻辑与 IO纯逻辑数据转换、校验、格式化→ 独立函数不引入fs/db/netIO 操作读文件、查库、发 HTTP→ 薄封装在 Service 类或 Repository 中依赖以构造器/函数参数注入而非模块内部直接 import。// ❌ 难以测试——必须 mock 整个模块 import { db } from process/database; function getConversation(id: string) { return db.query(SELECT * FROM conversations WHERE id ?, id); } // ✅ 易于测试——注入依赖 function getConversation(repo: IConversationRepository, id: string) { return repo.findById(id); }对既有代码允许vi.mock()新代码则优先参数注入。五、TestingVitest 4 与 80% 覆盖率目标AGENTS.md指定测试框架为Vitest 4配置见 vitest.config.ts项目覆盖率目标为≥ 80%普通改动应为变更行为补充聚焦测试。5.1 双环境测试矩阵vitest.config.ts 用 Vitest 4 的 projects 特性划分两个环境环境适用场景文件命名对应 include 规则node主进程、工具函数、Service*.test.tstests/unit/**/*.test.ts、tests/integration/**等jsdomDOM/浏览器相关代码*.dom.test.ts(x)tests/unit/**/*.dom.test.ts(x)超时设定为CI 环境 30s、本地 10s注释说明 CI runner 尤其是 windows-2022 渲染重组件可能超过本地 10s 预算。覆盖率的include覆盖packages/desktop/src/**/*.{ts,tsx}新文件自动纳入覆盖统计只有入口文件index.ts、preload.ts、shim、纯类型、静态资源等明确排除。5.2 测试文件镜像源码结构测试文件必须镜像其被测源码的路径见 docs/contributing/file-structure.md源码测试packages/desktop/src/process/services/CronService.tstests/unit/cronService.test.tspackages/desktop/src/renderer/hooks/ui/useAutoScroll.tstests/unit/useAutoScroll.dom.test.tspackages/desktop/src/process/extensions/ExtensionLoader.tstests/unit/extensions/extensionLoader.test.ts仓库tests/unit/下的实测布局chat/、conversation/、renderer/、settings/、theme/等子目录正是这一规则的落地结果。质量规则细节在.claude/skills/testing/SKILL.md先列出最高风险场景依赖返回undefined/抛错、边界情况、生产环境最可能坏的地方并描述行为而非代码结构。5.3 常用测试命令bun run test # 运行全部测试vitest run bun run test:watch # 监听模式 bun run test:coverage # 带覆盖率报告 bun run test:contract # 契约测试 bun run test:integration # 集成测试 bun run test:e2e # Playwright 端到端测试justfile中还有just test-coverage、just e2e-test先打包再跑 Playwright等封装。六、Workflow从开发到推送的完整门禁6.1 范围与强制执行Scope EnforcementAGENTS.md定义了四类规则理解它们对 Agent 协作至关重要Hard blockers硬性阻断进程边界违规、TypeScript 报错、测试失败、不安全的 IPC 使用、新增/修改的面向用户文本缺少 i18n、新 UI 中出现原生交互 HTMLCurrent-change requirements本次变更要求命名、CSS、文件放置、测试、文档、目录大小、单文件目录规则只适用于本次变更创建或实质性修改的文件Ratchet rules棘轮规则已有的目录大小或单文件目录违规不需要在普通功能开发中清理但本次变更不得使其更糟No scope expansion禁止范围蔓延除非用户明确要求实现计划与评审不得为清理工作额外创建任务、阶段或验收标准。另外docs/superpowers/被有意 gitignore供本地 Superpowers 规范和计划使用不得强制 add 或提交其中的文件。6.2 开发中的自动修复三连bun run lint:fix # 自动修复 lintoxlint bun run format # 自动格式化所有文件oxfmt bunx tsc --noEmit # 验证无类型错误如果改动触及packages/desktop/src/renderer/、locales/或packages/desktop/src/common/config/i18n还需依次执行bun run i18n:types node scripts/check-i18n.js注意i18n:types必须先于check-i18n.js——后者会校验重新生成的i18n-keys.d.ts是否同步。6.3 推送门禁just push而非git pushAGENTS.md明确规定AI Agent 未经明确要求不得推送推送时必须使用just push永远不要用裸git pushjust push # lint → format-check → typecheck → test → git push just push -u origin feat/branch # 相同检查附带额外 git push 参数从 justfile 源码看push配方串联了lint-strict fmt-check typecheck i18n-check test五个前置任务任一步失败都会中止推送。针对 AI Agent 有一条特别提示just push的 lint 使用--quiet只有 error 才会导致失败项目存在大量历史 lintwarning它们不代表失败——判断成功要看退出码而不是输出量。6.4 PR 前可选严格检查prek 复刻 CI 流水线# 一次性安装 npm install -g j178/prek # 运行复刻 CI 全部检查含所有文件类型的 EOF/行尾空白检查 prek run --from-ref origin/main --to-ref HEADprek是只读的——只报告不修复。若报告问题先运行上面的自动修复命令提交后重跑。开发指南还建议用prek install安装 git hooks 做提交前自动检查。6.5 Commit 与 PR 格式Commit 消息与 PR 标题必须遵循 Conventional Commit 格式type(scope): subject允许的 typefeat、fix、perf、refactor、docs、style、chore、test、ci、build。其中feat/fix/perf/refactor/docs会进入 changelogstyle/chore/test/ci/build隐藏。示例fix(preview): restore local html loadingfeat(workspace): add file preview shortcutsdocs(contributing): document pr title format开 PR 时使用 .github/pull_request_template.md 填写正文并诚实勾选检查项只勾选真正运行或验证过的。严禁添加 AI 签名Co-Authored-By、Generated with 等。CONTRIBUTING.md 还补充了原子 PR规则每个 PR 必须恰好包含一个不可再分解的功能或 bug 修复——团队聊天滚动修复 Sentry 用户追踪 office 预览性能优化应拆成 3 个 PR。不遵守时维护者可能关闭并要求重新提交或 cherry-pick 有价值的部分你的署名保留在 git 历史中。七、Skills Index把规范变成可调用的技能AGENTS.md末尾维护了一张技能索引表这些技能存放在.claude/skills/下其规范适用于所有Agent 和贡献者Skill用途触发时机architecture所有进程类型的文件与目录结构约定创建文件、新增模块、架构决策i18n国际化工作流与标准新增/修改面向用户的文本、改动locales/或 i18n 配置testing测试工作流与质量标准写测试、改运行时行为、修 bug、声称行为已验证bump-version版本号升级工作流更新 package.json、检查、分支、PR、tag 发布升版本、/bump-version这些技能文件.claude/skills/architecture/SKILL.md、.claude/skills/i18n/SKILL.md、.claude/skills/testing/SKILL.md、.claude/skills/bump-version/SKILL.md相当于可执行的规范模块例如 architecture 技能内置了新代码去哪决策树与进程边界速查表i18n 技能内置了先读 i18n-config.json → 检查既有 key → 选模块 → 全语言补 key → 生成类型 → 校验的六步工作流。这种文档规范 技能化封装的组合正是 AionUi 面向 AI 协作时代的设计规范不止给人读还要能被人形或 AI 形态的贡献者按步骤执行。八、本地开发环境速览配套依据虽然AGENTS.md主体是协作规范但它引用 docs/contributing/development.md 作为环境前提。开发 AionUi 需要 Node.js 22、bun、Rust stable Cargo用于构建本地 AionCore 后端二进制以及prekPR 检查器。开发模式启动命令为cd AionUi bun install bun run start # Electron 桌面开发模式自动拉起 aioncore 后端构建与分发命令bun run dist、bun run dist:win、bun run build-mac等以及 WebUI 模式bun run webui、bun run webui:remote的具体清单都在开发指南中可作为理解AGENTS.md所引用工程上下文的补充。结语AGENTS.md的价值不在于罗列了多少条规则而在于它把 AionUi 这个多进程 Electron 项目中最容易出错、最难事后修复的约束——进程边界、命名一致性、i18n 完整性、推送门禁——前置成了硬阻断项。对参与该项目的任何贡献者无论人类还是 AI掌握本文梳理的这四件事即可安全起步新代码放对目录并遵守命名第四节架构决策树 第一节命名表、UI 只走 Arco 与语义 token第二节、面向用户的文本必走 i18n第三节、推送前过just push门禁并遵守 Conventional Commit第六节。更深层的规范细节可随时回到AGENTS.md引用的 docs/contributing/file-structure.md、CONTRIBUTING.md 与.claude/skills/技能目录继续查阅。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考