一个可安装的 Node.js CLI，用于管理符合约定的 pnpm + nx monorepo 项目的构建/启动/数据库/部署等流程。
npm install @ranger1/dx一个可安装的 Node.js CLI，用于管理符合约定的 pnpm + nx monorepo 项目的构建/启动/数据库/部署等流程。
本工具通过项目内的 dx/config/* 配置文件来驱动命令执行：你可以把它理解成「带环境变量分层 + 校验 + 命令编排能力的脚本系统」。
必须全局安装，并始终使用最新版本：
``bash`
pnpm add -g @ranger1/dx@latest
安装后即可在任意目录使用：
`bash`
dx --help
dx status
升级到最新版本：
`bash`
pnpm update -g @ranger1/dx
- Node.js：>= 20
- 包管理器：pnpm（dx 内部会调用 pnpm）npx nx ...
- 构建系统：Nx（dx 默认命令配置里大量使用 ）dotenv-cli
- 环境加载：建议项目依赖 （dx 会用 pnpm exec dotenv ... 包裹命令来注入 .env.*）apps/backend
- 项目结构：推荐按 / apps/front / apps/admin-front 这类布局组织；如有自定义目录结构，请通过 dx/config/commands.json 适配
如果你的 monorepo 不完全一致，也能用：关键是你在 dx/config/commands.json 里把命令写成适配你项目的形式。
dx 会从当前目录向上查找 dx/config/commands.json 来定位项目根目录。
你需要在项目根目录提供：
`
dx/
config/
commands.json
env-layers.json
env-policy.jsonc
可选覆盖：
- 环境变量：DX_CONFIG_DIR=/abs/path/to/config
- 参数：
全局安装场景下，如果你不在项目目录内执行，也可以通过 DX_CONFIG_DIR / --config-dir 显式指定配置目录（目录下需要存在 commands.json）。
示例：
`bash在任意目录执行
dx --config-dir /path/to/your-repo/dx/config status
配置文件写法
$3
这是核心文件，定义了 dx 各命令要执行的 shell 命令，支持：
- 单命令：
- 并发：
- 串行：
- 环境分支：如 / build.backend.prod（dx 会根据 --dev/--prod/--staging/... 选择）
- dotenv 包裹：配置里带 "app": "backend" 时，dx 会按 env-layers.json 拼出 dotenv 层并用 pnpm exec dotenv ... -- 执行常见字段（单命令配置）：
`jsonc
{
"command": "npx nx build backend --configuration=production",
"app": "backend", // 可选：用于选择 dotenv 层，并决定需要校验的 env 变量组
"ports": [3000], // 可选：用于 start 类命令，冲突时自动清理
"description": "构建后端(生产环境)",
"dangerous": true, // 可选：危险操作需要确认
"skipEnvValidation": true, // 可选：跳过 env 校验（仍可加载 dotenv 层）
"env": { "NX_CACHE": "false" } // 可选：注入额外环境变量
}
`命令路径引用（并发/串行的 commands 数组）使用点号字符串，例如：
json
{ "concurrent": true, "commands": ["build.shared", "build.front.dev"] }
`$3
用于定义不同环境下加载哪些
文件（顺序 = 覆盖优先级）。格式：`json
{
"development": [".env.development", ".env.development.local"],
"staging": [".env.staging", ".env.staging.local"],
"production": [".env.production", ".env.production.local"],
"test": [".env.test", ".env.test.local"],
"e2e": [".env.e2e", ".env.e2e.local"]
}
`$3
统一的 env 策略配置（jsonc），同时覆盖：
- env 文件布局约束（禁用
/ .env.local；禁止子目录散落 .env*，仅允许少数特例路径）
- 机密键策略：机密 key 只能在 .env. 放真实值；对应的 .env. 必须存在同名 key 且为占位符 __SET_IN_env.local__
- 必填校验：按环境 + 按 target（端）定义 required keys，执行命令前校验是否缺失/仍为占位符target（端）不写死，由
定义；commands.json 里的 app 通过 env-policy.jsonc.appToTarget 映射到某个 target。注：
env-policy.jsonc 为必需配置；未提供时 dx 将直接报错。示例工程
查看
example/：包含一个最小可读的 dx/config 配置示例，以及如何在一个 pnpm+nx monorepo 中接入 dx。PR Review Loop（自动评审-修复闭环）
dx 内置一套 PR 评审自动化工作流：并行评审 → 聚合结论 → 生成修复清单 → 自动修复 → 再评审，最多循环 3 轮，用于让 PR 更快收敛。
$3
- PR 变更较大、想要更系统地覆盖安全/性能/可维护性问题
- 希望在 CI 通过的前提下，把评审建议落成可执行的修复清单（fixFile）
- 希望避免同一个问题在不同轮次被反复提出（通过 Decision Log 机制）
$3
在创建 PR 后执行：
`
/pr-review-loop --pr
更多命令说明见：
。提示：在创建 PR 的流程中也会给出快捷入口，见：
@opencode/commands/git-commit-and-pr.md。$3
- 预检（
pr-precheck）：先做编译/预检 gate，不通过则进入修复再预检（最多 2 次）
- 获取上下文（pr-context）：生成本轮上下文缓存 contextFile
- 并行评审（4 个 reviewer）： / claude-reviewer / gemini-reviewer / gh-thread-reviewer
- 聚合（）：合并各 reviewer 结果、去重、输出 fixFile，并发布本轮 Review Summary
- 修复（pr-fix）：按 fixFile 逐条修复（每条 findingId 单独 commit + push），输出 fixReportFile
- 发布修复报告（ 模式 B）：发布 Fix Report备注：每轮发布到 PR 的评论都会带
，用于幂等与避免反复采集机器人评论。$3
该流程的中间产物都写入项目内
./.cache/，并在 agent/命令之间传递 repo 相对路径：-
./.cache/pr-context-pr（contextFile）
- ./.cache/review-（reviewFile）
- ./.cache/fix-pr（fixFile）
- ./.cache/fix-report-pr（fixReportFile）$3
为了解决“第一轮拒绝的问题在后续轮次反复出现”的问题，PR Review Loop 使用 Decision Log 持久化每轮的决策：
- 文件：
./.cache/decision-log-pr
- 生成者： 在修复完成后创建/追加（append-only，禁止覆盖历史）
- 内容：记录每轮的 Fixed/Rejected，以及 essence（问题本质的一句话描述，用于后续智能匹配）在后续轮次：
- reviewers 若收到
decisionLogFile，必须读取并遵守：已修复不再提、已拒绝不再提（除非严重性升级）
- aggregate 在模式 A 中基于 LLM 对比 essence 做“问题本质相同”的判断，并生成 escalation_groups 入参给脚本升级质疑规则：只有当新 finding 的优先级比历史 rejected 高 ≥2 级（例如 P3→P1、P2→P0）时，才允许重新打开。
命令
dx 的命令由
dx/config/commands.json 驱动，并且内置了一些 internal runner（避免项目侧依赖任何 scripts/lib/*.js）：-
internal: sdk-build：SDK 生成/构建
- internal: backend-package：后端打包
- internal: start-dev：开发环境一键启动常用示例：
`bash
dx start backend --dev
dx start all
dx build backend --prod
dx build sdk --dev
dx db generate
dx db migrate --dev --name init
dx db deploy --prod -Y
dx deploy front --staging
dx lint
dx test e2e backend
`deploy 行为说明
从
起，dx deploy 不再在 dx 内部硬编码执行任何 nx build/sdk build 等前置步骤。- 需要的前置构建（例如
shared、api-contracts、OpenAPI 导出、后端构建等）应由项目自己的 Nx 依赖图（dependsOn/项目依赖）或 Vercel 的 buildCommand 负责。
- 这样 dx deploy 不会强依赖 apps/sdk 等目录结构，更容易适配不同 monorepo。依赖关系约定
dx 不负责管理「工程之间的构建依赖关系」。如果多个工程之间存在依赖（例如
front/admin 依赖 shared 或 api-contracts），必须由 Nx 的依赖图来表达并自动拉起：- 使用 Nx 的项目依赖（基于 import graph 或
implicitDependencies）
- 使用 nx.json 的 targetDefaults.dependsOn / targetDependenciesdx 只会执行你在
中配置的命令，不会在执行过程中额外硬编码插入依赖构建。给 Nx target 注入版本信息（可选）
本包提供
dx-with-version-env，用于在 nx:run-commands 中注入版本/sha/构建时间等环境变量：`json
{
"command": "dx-with-version-env --app front -- next build"
}
`支持的 app：
/ front / admin。约束与假设
当前版本面向 pnpm + nx 的 monorepo，默认假设：
- 使用 pnpm + nx
- 项目布局包含
apps/backend、apps/front、apps/admin-front（如有差异，通过 dx/config/commands.json 适配）
- 版本注入脚本 dx-with-version-env 默认支持 app: backend / front / admin发布到 npm（准备工作）
如果你准备公开发布：
1. 注意：npm 上的包名
很可能已被占用；更稳妥的是使用 scope（例如 @ranger1/dx）。
2. 发布前需要把 package.json 里的 private: true 去掉，并补全 version / license / repository 等字段。
3. 发布命令（公开包）：`bash
npm publish --access public --registry=https://registry.npmjs.org
``