nx-workspace

用途

该技能用于对 Nx 工作区进行只读探查，帮助理解工作区结构、项目配置、可用目标（target）以及项目之间的依赖关系。它适用于回答关于工作区、项目或任务的问题，也适用于 nx 命令执行失败时进行排查。

主要能力

• 列出项目：使用 nx show projects 列出工作区中的项目。
• 项目过滤：项目过滤语法（-p/--projects）可用于多个 Nx 命令，包括 nx run-many、nx release、nx show projects 等。过滤器支持显式名称、glob 模式、标签引用（如 tag:name）、目录以及否定（如 !project-name）。示例包括按 glob 模式过滤（apps/*、shared-*）、按标签过滤（tag:publishable、tag:publishable,!tag:internal）、按目标过滤（--withTarget build）、组合过滤（--type lib --withTarget test、--affected --exclude="-e2e"、-p "tag:scope:client,packages/"）以及否定模式（-p '!tag:private'、-p '!*-e2e'）。
• JSON 输出：支持 nx show projects --json。
• 项目配置：使用 nx show project <name> --json 获取项目的完整解析配置。注意不要直接读取 project.json，因为它只包含部分配置；nx show project --json 返回完整解析配置，包括来自插件的推断目标。可读取 node_modules/nx/schemas/project-schema.json 了解配置选项。支持用 jq 提取目标、目标键、项目元数据等。
• 目标信息：目标定义项目上可运行的任务。可列出目标、获取完整目标配置、查看执行器/命令、选项、输入/输出（用于缓存），并查找具有特定目标的项目（如 --withTarget serve、--withTarget e2e）。
• 工作区配置：直接读取 nx.json 获取工作区级配置，可读取 node_modules/nx/schemas/nx-schema.json。关键部分包括 targetDefaults、namedInputs、plugins、generators 等。
• 受影响项目：如果用户询问受影响项目，可参考受影响项目相关文档获取详细命令与示例。
• 常见探查模式：包括查询工作区内容、查询某项目的构建/测试/检查方式、查询某库的依赖方。
• 编程式回答：处理 nx CLI 结果时，使用命令行工具以编程方式计算答案，而非手动计数或解析输出。始终使用 --json 标志获取结构化输出，再用 jq、grep 等本地工具处理。示例包括统计项目数量、按模式过滤、获取受影响项目数组、获取目标名称、获取特定目标配置、获取标签、获取项目根目录、从项目图获取所有项目名、查找某项目的依赖、查找依赖某库的项目。

使用方式

注意：如果 nx 未全局安装，可能需要在命令前加 npx/pnpx/yarn。请检查 lockfile 以确定使用的包管理器。

常用命令：

• nx show projects
• nx show projects --json
• nx show project my-app --json
• nx show project my-app --json | jq '.targets'
• nx graph --print
• cat nx.json

适用场景

• 回答关于工作区、项目或任务的问题。
• 需要了解工作区项目列表、项目配置、目标与依赖关系时。
• nx 命令失败时进行排查。

故障排查

• “Cannot find configuration for task X:target”：可检查项目上存在哪些目标（nx show project X --json | jq '.targets | keys'），或检查是否有任何项目具有该目标（nx show projects --withTarget target）。
• “The workspace is out of sync”：可执行 nx sync；如果 sync 无法修复过期缓存，执行 nx reset。

限制

该技能提供的是只读探查，不修改工作区内容。