@ranger1/dx 0.1.112 → 0.1.114

package/README.md

@@ -48,6 +48,7 @@ pnpm add -g @ranger1/dx@latest
 
 ```bash
 dx --help
+dx --version
 dx status
 ```
 
@@ -202,6 +203,23 @@ dx 的命令由 `dx/config/commands.json` 驱动，并且内置了一些 interna
 - `internal: start-dev`：开发环境一键启动
 - `internal: pm2-stack`：PM2 交互式服务栈（支持端口清理/缓存清理配置）
 
+内置命令入口速览：
+
+- `dx start [target]`：启动开发服务；未指定 target 时默认使用 `start.development`
+- `dx build [target]`：按当前环境构建；未指定 target 时默认 `all`
+- `dx test [unit|e2e] <target> [path...]`：运行测试；unit 自动使用 `--test` 环境，e2e 自动使用 `--e2e` 环境
+- `dx db <generate|migrate|deploy|reset|seed|format|script>`：数据库相关命令；`migrate` 仅允许 `--dev`
+- `dx deploy <target>`：部署目标；普通 Vercel target 默认 `--staging`，`backend-artifact-deploy` 默认 `--dev`
+- `dx lint [--fix]`：运行 lint；`--fix` 会透传给下游 runner
+- `dx install`：执行项目配置的安装命令
+- `dx clean [target]` / `dx cache clear`：执行清理类命令，危险操作会要求确认
+- `dx package backend [--skip-build]`：使用内置后端打包 runner
+- `dx worktree <make|del|list|clean>`：管理 issue worktree；这是 dx 封装，不等同于原生 `git worktree`
+- `dx export <target>`：执行配置化导出命令
+- `dx contracts [generate|pull]`：导出 OpenAPI 并生成 `packages/api-contracts` 下的 Zod 合约（需要目标工程具备对应结构）
+- `dx release version <version>`：同步更新常见 app 包版本号
+- `dx initial`：同步包内 skills 到本机 agent 目录
+
 常用示例：
 
 ```bash
@@ -214,11 +232,25 @@ dx db migrate --dev --name init
 dx db deploy --prod -Y
 dx deploy front --staging
 dx deploy backend --prod
+dx install
 dx lint
+dx lint --fix
+dx test unit backend apps/backend/src/modules/user/user.service.spec.ts
 dx test e2e backend apps/backend/e2e/auth
 dx test e2e quantify apps/quantify/e2e/health/health.e2e-spec.ts
+dx db script fix-email-verified-status --dev -- --dry-run
+dx package backend --prod --skip-build
+dx worktree make 88 --base main
+dx cache clear -Y
 ```
 
+测试命令默认并行度：
+
+- `dx test unit ...` 会自动追加 `--maxWorkers=8`
+- `dx test e2e ...` 会自动追加 `--workers=8`
+- 如果命令配置或 `--` 透传参数里已经指定了对应 worker 参数，dx 不会重复追加；例如 `dx test e2e backend apps/backend/e2e/auth -- --workers=2`
+- 如果 unit 命令或对应 `apps/<target>/package.json` 的 `scripts.test` 已使用 Jest `--runInBand`，dx 不会追加 `--maxWorkers=8`，避免触发 Jest 互斥参数错误
+
 关于 `dx initial`：
 
 - `dx initial` 会把 npm 包内置的 `skills/` 覆盖同步到 `~/.agents/skills`。
@@ -239,10 +271,15 @@ dx test e2e quantify apps/quantify/e2e/health/health.e2e-spec.ts
 
 - 对声明了 `requiresPath: true` 的 E2E target，`dx test e2e <target>` 必须提供文件或目录路径，禁止无路径或 `all` 全量执行
 - `dx test e2e all` 不受支持，必须显式指定 target 和路径
+- `dx test unit ...` 默认使用 8 个 worker；`dx test e2e ...` 默认使用 8 个 worker；可通过 `--` 透传参数覆盖；unit 检测到 Jest `--runInBand` 时不会追加 `--maxWorkers`
+- `dx db migrate --dev` 必须通过 `--name` 或 `-n` 指定迁移名，禁止依赖 Prisma 交互式输入
 - `dx db migrate` 仅允许在 `--dev` 环境创建迁移；非开发环境请使用 `dx db deploy`
+- `dx db generate/migrate/deploy/reset/seed/script` 会禁用 Nx 缓存，避免命中缓存后未实际执行
+- `dx deploy` 仅支持 `--dev`、`--staging`、`--prod`，不支持 `--test` / `--e2e`
 - `dx start` 未指定服务时默认是开发套件，仅允许 `--dev`
 - `dx start` 下的单层目标（如 `stagewise-front`）默认仅支持 `--dev`
 - `dx build` 显式传入环境标志时，必须是该 target 实际支持的环境
+- `dx worktree` 是 dx 的 issue worktree 封装，与原生 `git worktree` 行为不同，不要混用
 
 ### `dx start stack` 配置详解（PM2 交互式服务栈）
 

package/lib/cli/commands/core.js

@@ -5,6 +5,8 @@ import { confirmManager } from '../../confirm.js'
 import { execManager } from '../../exec.js'
 import { showHelp, showCommandHelp } from '../help.js'
 
+const DEFAULT_TEST_WORKERS = 8
+
 export function handleHelp(cli, args = []) {
   if (args[0]) showCommandHelp(args[0], cli)
   else showHelp(cli)
@@ -177,6 +179,11 @@ export async function handleTest(cli, args) {
     logger.step(`运行 ${type} 测试`)
   }
 
+  testConfig = {
+    ...testConfig,
+    command: appendDefaultTestWorkers(cli, testConfig.command, type),
+  }
+
   await cli.executeCommand(testConfig)
 }
 
@@ -208,6 +215,63 @@ function shouldUseDirectPathArg(command) {
   )
 }
 
+function appendDefaultTestWorkers(cli, command, type) {
+  const flag = getDefaultWorkerFlag(type)
+  if (!flag) return command
+
+  const text = String(command || '').trim()
+  if (!text || hasWorkerFlag(text, flag)) return command
+  if (type === 'unit' && commandUsesRunInBand(cli, text)) return command
+
+  if (isNodeEvalCommandWithoutArgSeparator(text)) {
+    return `${text} -- ${flag}=${DEFAULT_TEST_WORKERS}`
+  }
+
+  return `${text} ${flag}=${DEFAULT_TEST_WORKERS}`
+}
+
+function getDefaultWorkerFlag(type) {
+  if (type === 'e2e') return '--workers'
+  if (type === 'unit') return '--maxWorkers'
+  return null
+}
+
+function hasWorkerFlag(command, flag) {
+  const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(^|[\\s'"])${escapedFlag}(=|\\s|['"]|$)`).test(String(command || ''))
+}
+
+function hasRunInBandFlag(command) {
+  return /(^|[\s'"])(--runInBand|--run-in-band|-i)(=|\s|['"]|$)/.test(String(command || ''))
+}
+
+function commandUsesRunInBand(cli, command) {
+  if (hasRunInBandFlag(command)) return true
+
+  const script = resolveNxUnitPackageTestScript(cli, command)
+  return hasRunInBandFlag(script)
+}
+
+function resolveNxUnitPackageTestScript(cli, command) {
+  const projectRoot = cli?.projectRoot || process.cwd()
+  const nxResolution = extractNxTarget(command, ['test'])
+  if (!nxResolution?.project) return null
+
+  const packagePath = join(projectRoot, 'apps', nxResolution.project, 'package.json')
+  if (!existsSync(packagePath)) return null
+
+  try {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf8'))
+    return typeof pkg?.scripts?.test === 'string' ? pkg.scripts.test : null
+  } catch {
+    return null
+  }
+}
+
+function isNodeEvalCommandWithoutArgSeparator(command) {
+  return /(^|\s)node\s+-e\s/.test(String(command || '')) && !/\s--(\s|$)/.test(String(command || ''))
+}
+
 function normalizeUnitTestPathForCommand(cli, command, testPath) {
   const rawPath = String(testPath || '')
   if (!rawPath) return rawPath

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.112",
+  "version": "0.1.114",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/doctor/SKILL.md

@@ -22,7 +22,8 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 - `agent-browser` 可用，且 Chromium/浏览器依赖已安装到可运行状态。
 - `rg`（rip grep）可用。
 - `gh`（GitHub CLI）可用；若当前工作流需要 GitHub 操作，还应完成认证。
-- `rtk` 可用，并且已分别完成 Codex CLI 与 Claude Code 的初始化。
+- `rtk` 可用，且明确是 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)；不能把其他同名二进制当作通过。
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 已分别完成 Codex CLI 与 Claude Code 的初始化。
 - 常用 PATH 配置在当前 shell 中可生效；若需要持久化，说明写入了哪个 shell 配置文件。
 
 ## 执行原则
@@ -41,7 +42,7 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
    - 当前 shell 与 PATH
    - `python3`、`python`、`node`、`npm`、`pnpm`、`dx`、`agent-browser`、`rg`、`gh`、`rtk` 的存在性与版本
    - `gh` 的认证状态（例如 `gh auth status`）
-   - `rtk` 对 Codex CLI 与 Claude Code 的初始化状态
+   - `rtk` 是否为 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)，以及它对 Codex CLI 与 Claude Code 的初始化状态
 2. 对照目标状态判断缺口。
 3. 制定最小修复动作并执行。
 4. 每次修复后重新验证相关项。
@@ -56,9 +57,10 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 - 每个目标命令的版本或基本健康输出。
 - `dx` 的初始化结果或当前初始化状态。
 - `gh --version` 能正常运行；若需要 GitHub 操作，`gh auth status` 应显示可用账号，否则报告未认证原因。
-- `rtk --version` 与 `rtk gain` 能正常运行。
-- `rtk` 的 Codex CLI 初始化必须有明确证据。优先使用 `rtk init --show --codex`，确认全局或本地 Codex 配置已包含 `RTK.md` 与 `AGENTS.md` 引用；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
-- `rtk` 的 Claude Code 初始化必须有明确证据。优先使用 `rtk init --show --agent claude`，确认 Claude Code hook、`RTK.md`、`CLAUDE.md` 引用与 `settings.json` hook 配置处于健康状态；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
+- `rtk` 必须确认来源为 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)。至少用 `rtk --version`、`rtk --help`、安装来源或命令特征交叉验证；若发现同名非 rtk-ai/rtk 工具，判定为未通过。
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 `rtk gain` 能正常运行。
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 Codex CLI 初始化必须有明确证据。优先使用 `rtk init --show --codex`，确认全局或本地 Codex 配置已包含 `RTK.md` 与 `AGENTS.md` 引用；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) 的 Claude Code 初始化必须有明确证据。优先使用 `rtk init --show --agent claude`，确认 Claude Code hook、`RTK.md`、`CLAUDE.md` 引用与 `settings.json` hook 配置处于健康状态；若当前 `rtk` 版本命令不同，使用等价的只读检查并在报告中说明。
 - `agent-browser` 是否能找到并使用已安装的浏览器依赖。
 - 对未通过项给出失败原因、已尝试动作和下一步建议。