后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载本篇技术指南以仓库根目录的 AGENTS.md 为骨架系统讲解 Ever Gauzy 这一大型 Nx Monorepo 中「如何正确执行任务」「如何借助 Nx MCP 工具理解工作区」「如何在 Windows 下避免代码搜索漏文件」三组核心工程规范。读完本文你将掌握 Ever Gauzy 仓库中 build/lint/test/e2e 的标准命令形态、Nx 缓存与依赖编排的实际配置以及 Windows 环境下findstr /S与 ripgrep 的正确分工可直接用于日常开发和 AI Agent 协作。一、从 AGENTS.md 说起这份文件在规范什么AGENTS.md 位于仓库根目录是一份面向「在 Ever Gauzy 仓库中工作的 AI Agent以及人类开发者」的工程协作指南。它的结构非常有代表性顶部有一段被!-- nx configuration start--与!-- nx configuration end--注释包裹的自动更新区域由 Nx 工具链自动维护改动后会被覆盖因此该区域内容不应手工修改正文只聚焦两件事Nx 工作区中的任务执行总则与Windows 下的文件搜索注意事项。换句话说这份文件并没有介绍 ERP/CRM/HRM 业务功能而是把注意力全部放在「如何在一个庞大的 Nx Monorepo 里高效、正确地开发与检索代码」上。这与 Ever Gauzy 的仓库形态高度匹配——从文件清单可以看到仓库同时包含apps/gauzy 前端、api 服务、desktop 桌面端、worker 等应用与packages/core、contracts、ui-core 等数十个库以及packages/plugins/下大量可插拔插件没有统一的任务编排规范开发和自动化协作将寸步难行。二、Ever Gauzy 的 Nx Monorepo 骨架2.1 仓库布局与包管理Ever Gauzy 采用 Nx 管理的单仓库Monorepo同时通过 Lerna 做发布编排。根目录 lerna.json 明确声明useNx: true并列出被管理的包范围为apps/*、packages/*、packages/plugins/*npmClient 为yarn安装时使用--no-package-lock即依赖 yarn.lock。根 package.json 中private: true、license: AGPL-3.0所有任务脚本都以yarn nx ...形式存在印证了「Nx 是唯一任务入口」的设计。2.2 nx.json 里的关键全局配置根目录 nx.json 定义了整个工作区的行为是理解「为什么文档要求用 nx 跑任务」的第一手证据配置项值含义defaultProjectgauzy不带项目名执行nx命令时默认作用于 gauzy 前端应用defaultBasedevelopnx affected计算受影响范围时对比的基准分支parallel8最多并行执行 8 个任务useDaemontrue启用 Nx 守护进程加速增量计算useInferencePluginsfalse不启用推断插件任务完全由各项目 project.json 显式声明cli.packageManageryarnNx 内部调用包管理器时的选择cli.defaultCollectionnstudio/xplat生成器默认集合angular.json 的schematicCollections同样指向它namedInputs定义了三类输入集合default项目所有文件 sharedGlobals 工作区级配置、sharedGlobals根 package.json、tsconfig 系列、环境变量文件、Node 平台/架构/版本运行时探测等、production在 default 基础上排除所有*.spec.ts与*.test.ts。这些输入集合决定了 Nx 计算缓存命中时的「文件指纹」例如targetDefaults中build的inputs为[production, ^production]意味着测试文件的变更不会使生产构建缓存失效。targetDefaults则统一了各项目的任务行为build、lint、test、e2e均开启cache: true可复用本地/远程缓存build、nx/angular:package、nx/webpack:webpack、nx/js:tsc、angular-devkit/build-angular:application等均声明dependsOn: [^build]即先构建所有被依赖的项目这正是「在 Ever Gauzy 里直接运行底层工具会因依赖包未构建而失败」的根本原因nx/jest:jest配置了passWithNoTests: true并预置ci配置ci: truecodeCoverage: true。此外release.version.preVersionCommand为yarn nx run-many -t build发布前会先整体构建一次。三、总则让 nx 成为唯一任务入口AGENTS.md 给出的第一条、也是最核心的一条准则是当运行任务如 build、lint、test、e2e 等时始终优先通过nx即nx run、nx run-many、nx affected执行而不是直接使用底层工具链。这一条并非教条。仓库根 package.json 的脚本体系就是活生生的例子# 任意项目的构建/服务/测试统一走 nx yarn nx run-many -t build -c development -p api,gauzy # 等价于 yarn build yarn nx run-many -t build -c production -p api,gauzy # 等价于 yarn build:prod yarn nx affected:apps yarn nx affected:libs yarn nx affected:build yarn nx affected:e2e yarn nx affected:test yarn nx affected:lint yarn nx dep-graph # 可视化项目依赖图 yarn nx format:write # 统一格式化仓库甚至把ng命令直接重定向到 Nxng: cross-env NODE_ENVdevelopment NODE_OPTIONS--max-old-space-size12288 yarn nx因此yarn ng serve gauzy实际执行的是yarn nx serve gauzyyarn ng:prod build gauzy -cproduction则是NODE_ENVproduction下的yarn nx build gauzy -cproduction。所有任务的解析、依赖排序、缓存判定都交给 Nx 完成。为什么要这样做结合 2.2 节可以看到Ever Gauzy 的packages/core等库被apps/api等应用隐式依赖apps/api/project.json 中implicitDependencies: [core]应用构建前必须先构建依赖库。用nx run-many -t build时Nx 依据dependsOn: [^build]自动编排先后顺序并复用缓存直接webpack/tsc/ng build则完全没有这层保障还会绕过namedInputs的缓存指纹计算。同理nx affected只有通过 Nx 计算「自develop分支以来受影响的项目」才有意义。四、用 Nx MCP 工具理解与调试工作区AGENTS.md 强调你有权访问 Nx MCP 服务器应当善用其工具回答仓库相关问题时优先用nx_workspace了解整体架构在单个项目内工作时用nx_project_details分析项目结构与依赖遇到 Nx 配置或最佳实践疑问时用nx_docs获取最新权威文档而不是自行猜测。这些工具与仓库配置的对应关系非常清晰nx_workspace读取整个工作区的项目清单、任务图与依赖关系也可以用来获取 Nx 配置错误或项目图错误的具体报错AGENTS.md 明确建议用户遇到 Nx 配置或 project graph 错误时用nx_workspace获取错误信息。在 Ever Gauzy 中workspace 元信息由 nx.json、根 project.json含local-registry目标以及各应用的 project.json 共同组成。nx_project_details用于分析单个项目。例如 apps/gauzy/project.json 中 gauzy 应用有buildangular-builders/custom-webpack:browser、serveangular-builders/custom-webpack:dev-server默认配置local代理配置指向 apps/gauzy/proxy.conf.json、desktop-ui、server-ui、testnx/jest:jest等目标apps/api/project.json 中 api 的build由nx/webpack:webpack驱动targetnode、compilerswc、showCircularDependenciesfalseserve由nx/js:node驱动调试端口 9229。nx_docs用于查询 Nx 配置语法与最佳实践。当不确定inputs、namedInputs、cacheableOperations等语义时文档工具优先于经验猜测。以 packages/core/project.json 为例可以看到一个库项目可以同时拥有非常多样的目标buildnx/js:tsc输出到dist/packages/core、servenx:run-commands调用 nodemon ts-node 监听packages/core/src、test-postgres-migrationsnx:run-commands运行node --test .scripts/tenant-stripe-customer.postgres.test.cjs、lint、test等。这类「同一项目多目标、多执行器」的复杂度正是 AGENTS.md 建议先借助 MCP 工具看清结构、再动手的原因。五、Nx 插件最佳实践查阅 PLUGIN.mdAGENTS.md 补充了一条容易被忽略的插件准则对于 Nx 插件最佳实践请查看node_modules/nx/plugin/PLUGIN.md。并非所有插件都有该文件——没有就跳过不要阻塞。这条建议与 Ever Gauzy 实际使用的插件族高度相关。从各 project.json 的executor字段可以看到仓库横跨多类插件nx/angularAngular 应用/库、nx/jest:jest测试、nx/eslint:lint静态检查、nx/webpack:webpackapi 服务打包、nx/js:tsc与nx/js:node纯 TypeScript 库与 Node 服务、nx:run-commands任意命令封装。其中部分插件在安装后会在node_modules/nx/plugin/PLUGIN.md提供针对该插件的本地化最佳实践文档比通用文档更贴合当前安装版本适合作为权威参考同时也要接受「个别插件没有该文件」的现实以其他文档为准。六、Windows 下代码搜索ripgrep 可能静默漏文件AGENTS.md 用「IMPORTANT」级别强调了 Windows 环境的搜索陷阱内置的grep_search工具基于 ripgrep在 Windows 上可能静默漏掉文件——即使文件明显包含搜索词也会返回空结果。这可能与包含空格的工作区路径、过长路径或其他 Windows 特定问题有关。关键搜索务必用findstr /S交叉验证。6.1 推荐做法始终用 findstr /S 做完整搜索# 递归搜索 packages/ 下所有 .ts 文件 findstr /S /N searchTerm packages\*.ts # 忽略大小写搜索 findstr /S /N /I searchterm packages\*.ts # 跨全部源码目录搜索 findstr /S /N searchTerm packages\*.ts apps\*.ts参数说明/S递归遍历子目录/N输出行号/I忽略大小写。对 Ever Gauzy 这种源码分布在apps/、packages/、packages/plugins/三层目录的仓库一条findstr /S /N searchTerm packages\*.ts apps\*.ts就能覆盖绝大多数 TypeScript 源码。6.2 工具选择对照表原文档完整继承工具使用场景grep_search快速搜索——但关键结果务必用findstr验证findstr /S /N完整搜索——当完整性至关重要时使用find_by_name按文件名/模式查找文件三者并非竞争关系而是分工关系find_by_name解决「文件在哪」grep_search解决「快速定位」findstr /S /N解决「Windows 下结果可信」。实践中的正确姿势是先用grep_search快速试探凡涉及关键决策例如判断某个 API 是否被引用、某个配置项是否有消费者必须用findstr /S /N复核若二者结果不一致以findstr为准并排查路径空格等 Windows 因素。七、规范落地的日常命令速查综合 AGENTS.md 与根 package.json在 Ever Gauzy 仓库中的高频操作如下# 本地全栈开发api gauzy 前端同时启动 yarn start yarn start:watch # 额外包含 watch:packagesnx watch 自动重建依赖包 # 构建 yarn build # nx run-many -t build -c development -p api,gauzy yarn build:prod # nx run-many -t build -c production -p api,gauzy yarn build:gauzy # 仅前端 yarn build:api # 仅后端 # 测试 / 静态检查 / 依赖图 yarn test # 配置环境后 nx test yarn lint yarn dep-graph # 影响范围分析基于 defaultBasedevelop yarn affected:apps yarn affected:libs yarn affected:build yarn affected:test在 Windows 上进行上述任何开发前请先确保搜索手段可靠第 6 节在修改或分析代码时始终通过nx触发任务让 nx.json 中的缓存、依赖排序与affected计算发挥作用——这就是 Ever Gauzy 这套开发协作规范的核心价值所在。赞分享后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载相关推荐AGENTS.md 编码代理协作指南obsidian-copilot 仓库的 AI 辅助开发规范与实践AGENTS.md 编码代理协作指南obsidian copilot 仓库的 AI 辅助开发规范与实践 本文以仓库根目录的 AGENTS.md https:/AI 应用大模型AI Agent交互助手RAGDankMaterialShell 仓库开发协作指南从 AGENTS.md 到代码库实战规范DankMaterialShell 仓库开发协作指南从 AGENTS.md 到代码库实战规范 本文以 DankMaterialShellDMS仓库根目录的桌面应用JupyterLab 仓库 AI 代理开发协作指南基于 AGENTS.md 的源码级工作规范与实践JupyterLab 仓库 AI 代理开发协作指南基于 AGENTS.md 的源码级工作规范与实践 本文以 JupyterLab 仓库根目录下的 AGENTS前端后端数据科学开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考