Ever Gauzy 仓库的 Nx 开发协作规范与 Windows 代码搜索实践

• 后端
• 前端
• 企业应用
• MCP 服务

本篇技术指南以仓库根目录的 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 跑任务」的第一手证据：

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: true+codeCoverage: 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命令直接重定向到 Nx：

"ng": "cross-env NODE_ENV=development NODE_OPTIONS=--max-old-space-size=12288 yarn nx"

因此yarn ng serve gauzy实际执行的是yarn nx serve gauzy；yarn ng:prod build gauzy -c=production则是NODE_ENV=production下的yarn nx build gauzy -c=production。所有任务的解析、依赖排序、缓存判定都交给 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 应用有build（@angular-builders/custom-webpack:browser）、serve（@angular-builders/custom-webpack:dev-server，默认配置local，代理配置指向 apps/gauzy/proxy.conf.json）、desktop-ui、server-ui、test（@nx/jest:jest）等目标；apps/api/project.json 中 api 的build由@nx/webpack:webpack驱动（target=node、compiler=swc、showCircularDependencies=false），serve由@nx/js:node驱动（调试端口 9229）。
• nx_docs：用于查询 Nx 配置语法与最佳实践。当不确定inputs、namedInputs、cacheableOperations等语义时，文档工具优先于经验猜测。

以 packages/core/project.json 为例，可以看到一个库项目可以同时拥有非常多样的目标：build（@nx/js:tsc输出到dist/packages/core）、serve（nx:run-commands调用 nodemon + ts-node 监听packages/core/src）、test-postgres-migrations（nx:run-commands运行node --test .scripts/tenant-stripe-customer.postgres.test.cjs）、lint、test等。这类「同一项目多目标、多执行器」的复杂度，正是 AGENTS.md 建议先借助 MCP 工具看清结构、再动手的原因。

五、Nx 插件最佳实践：查阅 PLUGIN.md

AGENTS.md 补充了一条容易被忽略的插件准则：

对于 Nx 插件最佳实践，请查看node_modules/@nx/<plugin>/PLUGIN.md。并非所有插件都有该文件——没有就跳过，不要阻塞。

这条建议与 Ever Gauzy 实际使用的插件族高度相关。从各 project.json 的executor字段可以看到仓库横跨多类插件：@nx/angular（Angular 应用/库）、@nx/jest:jest（测试）、@nx/eslint:lint（静态检查）、@nx/webpack:webpack（api 服务打包）、@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 工具选择对照表（原文档完整继承）

三者并非竞争关系，而是分工关系：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:packages（nx 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 # 影响范围分析（基于 defaultBase=develop） yarn affected:apps yarn affected:libs yarn affected:build yarn affected:test

在 Windows 上进行上述任何开发前，请先确保搜索手段可靠（第 6 节）；在修改或分析代码时，始终通过nx触发任务，让 nx.json 中的缓存、依赖排序与affected计算发挥作用——这就是 Ever Gauzy 这套开发协作规范的核心价值所在。

• 后端
• 前端
• 企业应用
• MCP 服务