Craft Agents ESLint自定义规则实践：no-localstorage等规则如何防止架构腐化

Craft Agents ESLint自定义规则实践no-localstorage等规则如何防止架构腐化【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-ossCraft Agents 是一款开源的 AI Agent 协作桌面应用。它的 Electron 客户端内置了一整套 ESLint 自定义规则如 no-localstorage、no-hardcoded-z-index用机器可执行的检查来替代口头约定从根源上防止大型前端项目的架构腐化。本文将带你逐个看懂这些规则的设计思路与落地方式。为什么需要 ESLint 自定义规则通用的 ESLint 规则只能发现语法层面的问题而架构腐化往往来自更隐蔽的坏习惯有人随手用localStorage存了个配置设置就散落在浏览器沙箱里有人直接写死navigator.platform判断系统跨平台兼容性悄悄埋雷有人硬编码zIndex: 9999层级系统彻底失控。Craft Agents 的做法是把团队的架构约定写成自定义 ESLint 规则让违规代码在保存时就被拦截。规则集中放在 apps/electron/eslint-rules/ 目录统一注册到 eslint.config.mjs。规则一no-localstorage —— 统一持久化出口这是最典型的防腐化规则。no-localstorage.cjs 会拦截所有localStorage.getItem()、window.localStorage等写法并给出明确指引请把设置存到~/.craft-agent/preferences.json通过window.electronAPI.readPreferences/writePreferences读写。文件头部的注释把设计动机写得明明白白基于文件的配置可迁移、可手动编辑、集中管理、便于调试。该规则还做了精细的 AST 判断——既拦截成员表达式访问也拦截把localStorage直接当参数传递的写法同时放过纯类型引用避免误报。它背后的偏好 API 实现在 packages/shared/src/config/preferences.ts规则报错信息会直接指向这个文件开发者看到报错就知道去哪修。规则二no-direct-navigation-state —— 收敛导航状态no-direct-navigation-state.cjs 只针对AppShell.tsx一个文件禁止在点击回调里直接调用setSidebarMode()必须走navigate(routes.xxx())。这样能保证三件事URL 与深度链接一致、历史记录支持前进后退、进入新视图自动选中第一项。规则内部还处理了 ESLint 9 移除context.getAncestors()的兼容问题通过sourceCode.getAncestors()白名单放行事件监听器内部的合法调用。规则三跨平台规则 —— 消灭隐性兼容 Bugno-direct-platform-check.cjs禁止直接读navigator.platform强制使用/lib/platform导出的isMac / isWindows / isLinux / PATH_SEP并对规则真相源platform.ts本身豁免。no-hardcoded-path-separator.cjs捕获filePath.startsWith(dir /)这类在 Windows 上必然出错的写法引导使用pathStartsWith()工具函数。这两条规则的共同点是错误信息不只要报错了还要报应该怎么改、去哪个模块改。规则四样式与交互一致性规则UI 层的腐化往往最直观。Electron 应用中还配置了两条样式规则craft-styles/no-hardcoded-z-indexno-hardcoded-z-index.cjs拦截zIndex: 400这类字面量只允许 CSS 变量 token如var(--z-floating-menu, 400)或命名常量。craft-styles/no-nonstandard-shadowsno-nonstandard-shadows.cjs只放行配置中列出的shadow-minimal、shadow-modal-small等白名单阴影类保证视觉质感统一。UI 共享包 packages/ui/eslint-rules/ 里还有更细粒度的no-floating-z-tokens-in-island.cjs专门约束标注岛组件必须使用--z-island专属 token防止浮层层级互相打架。架构边界的守护者no-restricted-imports在 eslint.config.mjs 中除了自定义规则还利用内置的no-restricted-imports划出了后端抽象边界主进程代码禁止直接import具体的 Agent 提供方 SDK如 claude-agent、pi-agent必须经由craft-agent/shared/agent/backend的统一抽象层。这等于用 ESLint 强制了依赖倒置——未来更换或新增 Agent 后端时上层代码一行都不用改。类似地craft-links/no-direct-file-openno-direct-file-open.cjs禁止渲染进程直接调用openFile()确保文件打开一律经过链接拦截器从而支持应用内预览。规则如何生效配置即策略所有规则在 eslint.config.mjs 中以 flat config 格式注册到craft-agent、craft-platform、craft-styles等命名空间插件下并按严重级别分档规则级别守护的架构约定no-direct-navigation-stateerror导航走统一路由no-localstoragewarn持久化走文件配置no-direct-platform-checkerror平台检测单一出口no-hardcoded-path-separatorwarn跨平台路径安全no-hardcoded-z-indexerror层级 token 化no-nonstandard-shadowserror带白名单阴影样式统一值得一提的是配置中还保留了受控例外清单少量未完成迁移的文件被显式列出并关闭阴影规则迁移完成后即可移除。这种默认严格、例外显式化的策略比一刀切更容易在真实项目中落地。给项目的启示Craft Agents 的实践给出了一套可复用的防腐化方法论约定要可执行写进代码评审的口头约定不如一条 100 行的自定义规则报错即指引错误信息里直接给出正确写法和目标模块路径规则源码中随处可见 Use xxx instead按模块分层治理packages/shared/eslint-rules/ 的no-inline-source-auth-check与 Electron 侧规则复用同一份逻辑保证共享包与客户端遵循同一套架构原则例外要显式化白名单和例外文件都写在配置里迁移进度一目了然配套单测如 no-hardcoded-z-index.test.ts 为规则本身编写测试确保检查逻辑不失效。对新手来说这套机制的学习成本很低——你只需要运行一次 lint就能顺着报错信息读懂整个项目的架构约定。这正是自定义 ESLint 规则最有价值的地方它不只是查错的工具更是团队架构知识的活文档。总结Craft Agents 用 no-localstorage、no-direct-navigation-state、no-hardcoded-z-index 等十余条自定义 ESLint 规则把统一持久化、统一导航、统一层级、抽象后端等架构原则固化进了开发流程。规则源码集中、错误信息友好、例外显式可控这套实践对任何正在长大的前端项目都有很强的参考价值。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考