@ranger1/dx 0.1.9 → 0.1.11

package/README.md

@@ -6,10 +6,10 @@
 
 ## 安装
 
-全局安装（推荐）：
+必须全局安装，并始终使用最新版本：
 
 ```bash
-pnpm add -g @ranger1/dx
+pnpm add -g @ranger1/dx@latest
 ```
 
 安装后即可在任意目录使用：
@@ -19,11 +19,10 @@ dx --help
 dx status
 ```
 
-项目内安装（可选，如果你更希望锁定版本）：
+升级到最新版本：
 
 ```bash
-pnpm add -D @ranger1/dx
-pnpm exec dx --help
+pnpm update -g @ranger1/dx
 ```
 
 ## 使用条件（必须满足）
@@ -32,7 +31,7 @@ pnpm exec dx --help
 - 包管理器：pnpm（dx 内部会调用 `pnpm`）
 - 构建系统：Nx（dx 默认命令配置里大量使用 `npx nx ...`）
 - 环境加载：建议项目依赖 `dotenv-cli`（dx 会用 `pnpm exec dotenv ...` 包裹命令来注入 `.env.*`）
-- 项目结构：默认按 `apps/backend` / `apps/front` / `apps/admin-front` / `apps/sdk` 这类布局编写命令配置
+- 项目结构：推荐按 `apps/backend` / `apps/front` / `apps/admin-front` 这类布局组织；如有自定义目录结构，请通过 `dx/config/commands.json` 适配
 
 如果你的 monorepo 不完全一致，也能用：关键是你在 `dx/config/commands.json` 里把命令写成适配你项目的形式。
 
@@ -123,7 +122,7 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 
 target（端）不写死，由 `env-policy.jsonc.targets` 定义；`commands.json` 里的 `app` 通过 `env-policy.jsonc.appToTarget` 映射到某个 target。
 
-注：若未提供 `env-policy.jsonc`，dx 会继续使用旧的 `required-env.jsonc` / `local-env-allowlist.jsonc` / `exempted-keys.jsonc` 逻辑（兼容模式）。
+注：`env-policy.jsonc` 为必需配置；未提供时 dx 将直接报错。
 
 ## 示例工程
 
@@ -159,6 +158,15 @@ dx test e2e backend
 - 需要的前置构建（例如 `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` / `targetDependencies`
+
+dx 只会执行你在 `dx/config/commands.json` 中配置的命令，不会在执行过程中额外硬编码插入依赖构建。
+
 ## 给 Nx target 注入版本信息（可选）
 
 本包提供 `dx-with-version-env`，用于在 `nx:run-commands` 中注入版本/sha/构建时间等环境变量：
@@ -176,7 +184,7 @@ dx test e2e backend
 当前版本面向 pnpm + nx 的 monorepo，默认假设：
 
 - 使用 pnpm + nx
-- 项目布局包含 `apps/backend`、`apps/front`、`apps/admin-front`、`apps/sdk`（如果你的命令配置不依赖这些目录，可自行调整）
+- 项目布局包含 `apps/backend`、`apps/front`、`apps/admin-front`（如有差异，通过 `dx/config/commands.json` 适配）
 - 版本注入脚本 `dx-with-version-env` 默认支持 app: `backend` / `front` / `admin`
 
 ## 发布到 npm（准备工作）

package/lib/backend-package.js

@@ -239,18 +239,11 @@ class BackendPackager {
   async prepareEnvSnapshot() {
     logger.info('校验并快照环境变量')
     const policy = loadEnvPolicy(envManager.configDir)
-    let requiredVars = []
-    if (policy) {
-      const targetId = resolvePolicyTargetId(policy, 'backend')
-      if (!targetId) {
-        throw new Error(
-          'env-policy.jsonc 已启用，但缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）',
-        )
-      }
-      requiredVars = resolveTargetRequiredVars(policy, targetId, this.layerEnv)
-    } else {
-      requiredVars = envManager.getRequiredEnvVars(this.layerEnv, 'backend')
+    const targetId = resolvePolicyTargetId(policy, 'backend')
+    if (!targetId) {
+      throw new Error('缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）')
     }
+    const requiredVars = resolveTargetRequiredVars(policy, targetId, this.layerEnv)
     const collected = envManager.collectEnvFromLayers('backend', this.layerEnv)
     const effectiveEnv = { ...collected, ...process.env }
     const { valid, missing, placeholders } = envManager.validateRequiredVars(

package/lib/cli/commands/ai.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+import { logger } from '../../logger.js'
+import { confirmManager } from '../../confirm.js'
+import { getPassthroughArgs } from '../args.js'
+
+function ensureOpencodeAvailable() {
+  const result = spawnSync('opencode', ['--version'], { stdio: 'ignore' })
+  if (result?.error?.code === 'ENOENT') {
+    return { ok: false, reason: 'missing' }
+  }
+  return { ok: true }
+}
+
+function resolveAiConfig(cli, name) {
+  const raw = cli.commands?.ai?.[name]
+  if (!raw) return null
+
+  const environment = cli.determineEnvironment()
+  const envKey = cli.normalizeEnvKey(environment)
+  let config = raw
+
+  // 允许按环境分支（保持与 build/start/export 一致）
+  if (typeof config === 'object' && config && !config.promptFile && !config.command) {
+    if (config[envKey]) config = config[envKey]
+    else if (envKey === 'staging' && config.prod) config = config.prod
+    else config = config.dev || config
+  }
+
+  return config
+}
+
+export async function handleAi(cli, args = []) {
+  const name = args[0]
+  if (!name) {
+    const names = Object.keys(cli.commands?.ai || {})
+    logger.error('请指定 ai 任务名称')
+    logger.info(`用法: ${cli.invocation} ai <name> [-- <opencode flags>...]`)
+    if (names.length > 0) {
+      logger.info(`可用任务: ${names.join(', ')}`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  const config = resolveAiConfig(cli, name)
+  if (!config) {
+    const names = Object.keys(cli.commands?.ai || {})
+    logger.error(`未找到 ai 任务配置: ${name}`)
+    if (names.length > 0) {
+      logger.info(`可用任务: ${names.join(', ')}`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  const availability = ensureOpencodeAvailable()
+  if (!availability.ok) {
+    logger.error('未找到 opencode 可执行文件（PATH 中不存在 opencode）')
+    logger.info('请先安装并确保 `opencode --version` 可用')
+    process.exitCode = 1
+    return
+  }
+
+  const promptFile = config?.promptFile
+  if (!promptFile) {
+    logger.error(`ai.${name} 缺少 promptFile 配置（指向一个 .md 文件）`)
+    process.exitCode = 1
+    return
+  }
+
+  const promptPath = resolve(process.cwd(), String(promptFile))
+  if (!existsSync(promptPath)) {
+    logger.error(`未找到提示词文件: ${promptFile}`)
+    logger.info(`解析后的路径: ${promptPath}`)
+    process.exitCode = 1
+    return
+  }
+
+  let promptText = ''
+  try {
+    promptText = readFileSync(promptPath, 'utf8')
+  } catch (error) {
+    logger.error(`读取提示词文件失败: ${promptFile}`)
+    logger.error(error?.message || String(error))
+    process.exitCode = 1
+    return
+  }
+
+  // 固定全权限：这会让 opencode 在当前目录拥有 bash/edit 等工具的自动执行权
+  if (!cli.flags.Y) {
+    const confirmed = await confirmManager.confirmDangerous(
+      `ai.${name}（将以 OPENCODE_PERMISSION="allow" 运行，全权限）`,
+      '当前目录',
+      false,
+    )
+    if (!confirmed) {
+      logger.info('操作已取消')
+      return
+    }
+  }
+
+  const model = config?.model ? String(config.model) : null
+  const agent = config?.agent ? String(config.agent) : null
+  const format = config?.format ? String(config.format) : null
+  const attach = config?.attach ? String(config.attach) : null
+
+  const passthrough = getPassthroughArgs(cli.args)
+  const configPassthrough = Array.isArray(config?.passthrough)
+    ? config.passthrough.map(v => String(v))
+    : []
+
+  const opencodeArgs = ['run']
+  if (model) opencodeArgs.push('--model', model)
+  if (agent) opencodeArgs.push('--agent', agent)
+  if (format) opencodeArgs.push('--format', format)
+  if (attach) opencodeArgs.push('--attach', attach)
+  if (configPassthrough.length > 0) opencodeArgs.push(...configPassthrough)
+  if (Array.isArray(passthrough) && passthrough.length > 0) opencodeArgs.push(...passthrough)
+  opencodeArgs.push(promptText)
+
+  logger.step(`ai ${name}`)
+  logger.command(`opencode ${opencodeArgs.filter(a => a !== promptText).join(' ')} <prompt-from-file>`)
+
+  await new Promise(resolvePromise => {
+    const child = spawn('opencode', opencodeArgs, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        // OpenCode expects OPENCODE_PERMISSION to be JSON (it JSON.parse's the value).
+        OPENCODE_PERMISSION: '"allow"',
+      },
+    })
+
+    const forwardSignal = signal => {
+      try {
+        child.kill(signal)
+      } catch {}
+    }
+
+    const onSigint = () => forwardSignal('SIGINT')
+    const onSigterm = () => forwardSignal('SIGTERM')
+    process.on('SIGINT', onSigint)
+    process.on('SIGTERM', onSigterm)
+
+    const cleanup = () => {
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+    }
+
+    child.on('error', error => {
+      cleanup()
+      logger.error(error?.message || String(error))
+      process.exitCode = 1
+      resolvePromise()
+    })
+
+    child.on('exit', code => {
+      cleanup()
+      if (typeof code === 'number' && code !== 0) {
+        process.exitCode = code
+      }
+      resolvePromise()
+    })
+  })
+}

package/lib/cli/dx-cli.js

@@ -33,6 +33,7 @@ import { handlePackage } from './commands/package.js'
 import { handleExport } from './commands/export.js'
 import { handleContracts } from './commands/contracts.js'
 import { handleRelease } from './commands/release.js'
+import { handleAi } from './commands/ai.js'
 
 class DxCli {
   constructor(options = {}) {
@@ -67,6 +68,7 @@ class DxCli {
       export: args => handleExport(this, args),
       contracts: args => handleContracts(this, args),
       release: args => handleRelease(this, args),
+      ai: args => handleAi(this, args),
     }
 
     this.flagDefinitions = FLAG_DEFINITIONS
@@ -221,18 +223,11 @@ class DxCli {
       if (process.env.CI !== '1') {
         const effectiveEnv = { ...process.env, ...layeredEnv }
         const policy = loadEnvPolicy(envManager.configDir)
-        let requiredVars = []
-        if (policy) {
-          const targetId = resolvePolicyTargetId(policy, 'backend')
-          if (!targetId) {
-            throw new Error(
-              'env-policy.jsonc 已启用，但缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）',
-            )
-          }
-          requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
-        } else {
-          requiredVars = envManager.getRequiredEnvVars(environment, 'backend')
+        const targetId = resolvePolicyTargetId(policy, 'backend')
+        if (!targetId) {
+          throw new Error('缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）')
         }
+        const requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
         if (requiredVars.length > 0) {
           const { valid, missing, placeholders } = envManager.validateRequiredVars(
             requiredVars,
@@ -304,7 +299,8 @@ class DxCli {
       // - help: printing help should never require env vars.
       // - status: should be available even when env is incomplete.
       // - release: only edits package.json versions.
-      const skipStartupChecks = new Set(['help', 'status', 'release'])
+      // - ai: wraps external opencode CLI, should not require project deps/prisma/env.
+      const skipStartupChecks = new Set(['help', 'status', 'release', 'ai'])
       if (skipStartupChecks.has(this.command)) {
         await this.routeCommand()
         return

package/lib/cli/help.js

@@ -2,115 +2,124 @@ import { getPackageVersion } from '../version.js'
 
 export function showHelp() {
   const version = getPackageVersion()
-  console.log(`
-DX CLI v${version} - 统一开发环境管理工具
-
-用法:
-  dx <命令> [选项] [参数...]
-
-命令:
-  start [service] [环境标志]  启动/桥接服务
-    service: backend, front, admin, all, dev, stack, stagewise-front, stagewise-admin (默认: dev)
-    stack: PM2 交互式服务栈管理（推荐）- 同时启动三个服务并提供交互式命令
-    环境标志: --dev, --staging, --prod, --test, --e2e（支持别名 --development、--production 等）
-    说明: 传入 --staging 时会加载 '.env.staging(.local)' 层，同时复用生产构建/启动流程
-
-  build [target] [环境标志]   构建应用
-    target: backend, shared, front, admin, mobile, all, sdk, affected (默认: all)
-    环境标志: --dev, --staging, --prod, --test, --e2e（未指定时默认 --dev）
-
-  deploy <target> [环境标志]  部署前端到 Vercel
-    target: front, admin, telegram-bot, all
-    环境标志: --dev, --staging, --prod（默认 --staging）
-
-  install                  安装依赖（使用 frozen-lockfile 确保版本一致）
-
-  package backend [环境标志]  构建后端部署包（生成 backend-<version>-<sha>.tar.gz）
-    环境标志: --dev, --staging, --prod, --test, --e2e（默认 --dev）
-    产物位置: dist/backend/backend-*.tar.gz
-    内含: dist/、node_modules(生产依赖)、prisma/、config/.env.runtime、bin/start.sh
-
-  db [action] [环境标志]      数据库操作
-    action: generate, migrate, deploy, reset, seed, format, script
-    用法示例:
-      dx db migrate --dev --name add_user_table   # 创建新的迁移（开发环境需指定名称）
-      dx db deploy --dev                          # 应用开发环境已有迁移
-      dx db deploy --prod                         # 生产环境迁移（复用 deploy 流程，需确认）
-      dx db script fix-email-verified-status --dev  # 运行数据库脚本（开发环境）
-      dx db script fix-pending-transfer-status --prod  # 运行数据库脚本（生产环境，需确认）
-      dx db script my-script --dev -- --arg1 --arg2  # 向脚本传递额外参数（-- 后面的部分）
-
-  test [type] [target] [path] [-t pattern]  运行测试
-    type: e2e, unit (默认: e2e)
-    target: backend, all (默认: all)
-    path: 测试文件路径 (可选，仅支持e2e backend)
-    -t pattern: 指定测试用例名称模式 (可选，需要和path一起使用)
-
-  worktree [action] [num...] Git Worktree管理
-    action: make, del, list, clean
-    num: issue编号 (make时需要1个，del时支持多个)
-    支持批量删除: dx worktree del 123 456 789
-    支持非交互式: dx worktree del 123 -Y
-  注意：该封装与原生 git worktree 行为不同，勿混用
-
-  lint                   运行代码检查
-
-  contracts [generate]       导出后端 OpenAPI 并生成 Zod 合约（packages/api-contracts）
-
-  release version <semver>   统一同步 backend/front/admin-front 的版本号
-
-  clean [target]         清理操作
-    target: all, deps (默认: all)
-
-  cache [action]         缓存清理
-    action: clear (默认: clear)
-
-  status                 查看系统状态
-
-选项:
- --dev, --development   使用开发环境
- --prod, --production   使用生产环境
-  --staging, --stage    使用预发环境（加载 .env.staging*.，复用生产流程）
-  --test                 使用测试环境
-  --e2e                  使用E2E测试环境
-  -Y, --yes              跳过所有确认提示
-   -v, --verbose          详细输出
-   -h, --help             显示此帮助信息
-  -V, --version          显示版本号
-
-示例:
-  dx start stack            # PM2 交互式服务栈（推荐）- 同时管理三个服务
-  dx start backend --dev    # 启动后端开发服务
-  dx start front --dev      # 启动用户前端开发服务
-  dx start admin --dev      # 启动管理后台开发服务
-  dx start all              # 同时启动所有开发服务（默认 --dev）
-  dx build all --prod       # 构建所有应用(生产环境)
-  dx db deploy --dev       # 应用开发环境数据库迁移
-  dx db reset --prod -Y     # 重置生产数据库(跳过确认)
-  dx test e2e backend                           # 运行后端E2E测试
-  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts  # 运行单个E2E测试文件
-  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts -t "should list all activity definitions"  # 运行特定测试用例
-  dx deploy front --staging # 部署前端到 Vercel（staging）
-  dx worktree make 88       # 为issue #88创建worktree
-  dx worktree del 88        # 删除issue #88的worktree
-  dx worktree del 88 89 90 -Y  # 批量删除多个worktree（非交互式）
-  dx worktree list          # 列出所有worktree
-  dx clean deps             # 清理并重新安装依赖
-  dx cache clear            # 清除 Nx 与依赖缓存
-  dx contracts              # 导出 OpenAPI 并生成 Zod 合约
-  dx release version 1.2.3  # 同步 backend/front/admin-front 版本号
-
-  # Stagewise 桥接（固定端口，自动清理占用）
-  dx start stagewise-front      # 桥接 front: 3001 -> 3002（工作目录 apps/front）
-  dx start stagewise-admin      # 桥接 admin-front: 3500 -> 3501（工作目录 apps/admin-front）
-
-  # Start 用法示例
-  dx start backend --prod       # 以生产环境变量启动后端
-  dx start backend --dev        # 以开发环境变量启动后端
-  dx start backend --e2e        # 以 E2E 环境变量启动后端
-
-
-`)
+  const lines = [
+    '',
+    `DX CLI v${version} - 统一开发环境管理工具`,
+    '',
+    '用法:',
+    '  dx <命令> [选项] [参数...]',
+    '',
+    '命令:',
+    '  start [service] [环境标志]  启动/桥接服务',
+    '    service: backend, front, admin, all, dev, stack, stagewise-front, stagewise-admin (默认: dev)',
+    '    stack: PM2 交互式服务栈管理（推荐）- 同时启动三个服务并提供交互式命令',
+    '    环境标志: --dev, --staging, --prod, --test, --e2e（支持别名 --development、--production 等）',
+    "    说明: 传入 --staging 时会加载 '.env.staging(.local)' 层，同时复用生产构建/启动流程",
+    '',
+    '  build [target] [环境标志]   构建应用',
+    '    target: backend, shared, front, admin, mobile, all, sdk, affected (默认: all)',
+    '    环境标志: --dev, --staging, --prod, --test, --e2e（未指定时默认 --dev）',
+    '',
+    '  deploy <target> [环境标志]  部署前端到 Vercel',
+    '    target: front, admin, telegram-bot, all',
+    '    环境标志: --dev, --staging, --prod（默认 --staging）',
+    '',
+    '  install                  安装依赖（使用 frozen-lockfile 确保版本一致）',
+    '',
+    '  package backend [环境标志]  构建后端部署包（生成 backend-<version>-<sha>.tar.gz）',
+    '    环境标志: --dev, --staging, --prod, --test, --e2e（默认 --dev）',
+    '    产物位置: dist/backend/backend-*.tar.gz',
+    '    内含: dist/、node_modules(生产依赖)、prisma/、config/.env.runtime、bin/start.sh',
+    '',
+    '  db [action] [环境标志]      数据库操作',
+    '    action: generate, migrate, deploy, reset, seed, format, script',
+    '    用法示例:',
+    '      dx db migrate --dev --name add_user_table   # 创建新的迁移（开发环境需指定名称）',
+    '      dx db deploy --dev                          # 应用开发环境已有迁移',
+    '      dx db deploy --prod                         # 生产环境迁移（复用 deploy 流程，需确认）',
+    '      dx db script fix-email-verified-status --dev  # 运行数据库脚本（开发环境）',
+    '      dx db script fix-pending-transfer-status --prod  # 运行数据库脚本（生产环境，需确认）',
+    '      dx db script my-script --dev -- --arg1 --arg2  # 向脚本传递额外参数（-- 后面的部分）',
+    '',
+    '  test [type] [target] [path] [-t pattern]  运行测试',
+    '    type: e2e, unit (默认: e2e)',
+    '    target: backend, all (默认: all)',
+    '    path: 测试文件路径 (可选，仅支持e2e backend)',
+    '    -t pattern: 指定测试用例名称模式 (可选，需要和path一起使用)',
+    '',
+    '  worktree [action] [num...] Git Worktree管理',
+    '    action: make, del, list, clean',
+    '    num: issue编号 (make时需要1个，del时支持多个)',
+    '    支持批量删除: dx worktree del 123 456 789',
+    '    支持非交互式: dx worktree del 123 -Y',
+    '  注意：该封装与原生 git worktree 行为不同，勿混用',
+    '',
+    '  lint                   运行代码检查',
+    '',
+    '  contracts [generate]       导出后端 OpenAPI 并生成 Zod 合约（packages/api-contracts）',
+    '',
+    '  release version <semver>   统一同步 backend/front/admin-front 的版本号',
+    '',
+    '  clean [target]         清理操作',
+    '    target: all, deps (默认: all)',
+    '',
+    '  cache [action]         缓存清理',
+    '    action: clear (默认: clear)',
+    '',
+    '  status                 查看系统状态',
+    '',
+    '  ai <name>               运行一个预配置的 opencode 任务（从 commands.json 读取）',
+    '    透传: -- 后的参数将原样传给 opencode run',
+    '',
+    '选项:',
+    ' --dev, --development   使用开发环境',
+    ' --prod, --production   使用生产环境',
+    '  --staging, --stage    使用预发环境（加载 .env.staging*.，复用生产流程）',
+    '  --test                 使用测试环境',
+    '  --e2e                  使用E2E测试环境',
+    '  -Y, --yes              跳过所有确认提示',
+    '   -v, --verbose          详细输出',
+    '   -h, --help             显示此帮助信息',
+    '  -V, --version          显示版本号',
+    '',
+    '示例:',
+    '  dx start stack            # PM2 交互式服务栈（推荐）- 同时管理三个服务',
+    '  dx start backend --dev    # 启动后端开发服务',
+    '  dx start front --dev      # 启动用户前端开发服务',
+    '  dx start admin --dev      # 启动管理后台开发服务',
+    '  dx start all              # 同时启动所有开发服务（默认 --dev）',
+    '  dx build all --prod       # 构建所有应用(生产环境)',
+    '  dx db deploy --dev       # 应用开发环境数据库迁移',
+    '  dx db reset --prod -Y     # 重置生产数据库(跳过确认)',
+    '  dx test e2e backend                           # 运行后端E2E测试',
+    '  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts  # 运行单个E2E测试文件',
+    '  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts -t "should list all activity definitions"  # 运行特定测试用例',
+    '  dx deploy front --staging # 部署前端到 Vercel（staging）',
+    '  dx worktree make 88       # 为issue #88创建worktree',
+    '  dx worktree del 88        # 删除issue #88的worktree',
+    '  dx worktree del 88 89 90 -Y  # 批量删除多个worktree（非交互式）',
+    '  dx worktree list          # 列出所有worktree',
+    '  dx clean deps             # 清理并重新安装依赖',
+    '  dx cache clear            # 清除 Nx 与依赖缓存',
+    '  dx contracts              # 导出 OpenAPI 并生成 Zod 合约',
+    '  dx release version 1.2.3  # 同步 backend/front/admin-front 版本号',
+    '',
+    '  dx ai review',
+    '  dx ai review -- --share --title "my run"',
+    '',
+    '  # Stagewise 桥接（固定端口，自动清理占用）',
+    '  dx start stagewise-front      # 桥接 front: 3001 -> 3002（工作目录 apps/front）',
+    '  dx start stagewise-admin      # 桥接 admin-front: 3500 -> 3501（工作目录 apps/admin-front）',
+    '',
+    '  # Start 用法示例',
+    '  dx start backend --prod       # 以生产环境变量启动后端',
+    '  dx start backend --dev        # 以开发环境变量启动后端',
+    '  dx start backend --e2e        # 以 E2E 环境变量启动后端',
+    '',
+    '',
+  ]
+
+  console.log(lines.join('\n'))
 }
 
 export function showCommandHelp(command) {
@@ -248,6 +257,38 @@ release 命令用法:
 `)
       return
 
+    case 'ai':
+      console.log(
+        [
+          '',
+          'ai 命令用法:',
+          '  dx ai <name> [-- <opencode flags>...]',
+          '',
+          '说明:',
+          '  - 从 dx/config/commands.json 的 ai.<name> 读取一个固定配置并执行 opencode run',
+          '  - 本次运行固定注入 OPENCODE_PERMISSION="allow"（全权限）',
+          '',
+          'commands.json 示例:',
+          '  {',
+          '    "ai": {',
+          '      "review": {',
+          '        "promptFile": "./prompts/review.md",',
+          '        "model": "openai/gpt-4.1",',
+          '        "agent": "general",',
+          '        "format": "default",',
+          '        "passthrough": ["--share"]',
+          '      }',
+          '    }',
+          '  }',
+          '',
+          '示例:',
+          '  dx ai review',
+          '  dx ai review -- --title "my run"',
+          '',
+        ].join('\n'),
+      )
+      return
+
     default:
       showHelp()
   }

package/lib/env-policy.js

@@ -28,9 +28,11 @@ export function loadEnvPolicy(configDir) {
 
   const policyPath = join(configDir, DEFAULT_POLICY_PATH)
   if (!existsSync(policyPath)) {
-    cachedPolicy = null
-    cachedPolicyDir = configDir
-    return null
+    throw new Error(
+      `缺少配置文件 ${DEFAULT_POLICY_PATH}。
+请在目标工程根目录创建 dx/config/${DEFAULT_POLICY_PATH}（或用 DX_CONFIG_DIR / --config-dir 指定配置目录）。
+当前配置目录: ${configDir}`,
+    )
   }
 
   let parsed

package/lib/env.js

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import stripJsonComments from 'strip-json-comments'
 
 function resolveProjectRoot() {
   return process.env.DX_PROJECT_ROOT || process.cwd()
@@ -16,7 +15,6 @@ export class EnvManager {
     this.projectRoot = resolveProjectRoot()
     this.configDir = resolveConfigDir()
     this.envLayers = this.loadEnvLayers()
-    this.requiredEnvConfig = null
     this.latestEnvWarnings = []
 
     // APP_ENV → NODE_ENV 映射（用于运行时行为和工具链，如 Nx/Next）
@@ -103,43 +101,6 @@ export class EnvManager {
     return layers.map(layer => layer.replace('{app}', app))
   }
 
-  loadRequiredEnvConfig() {
-    if (this.requiredEnvConfig) return this.requiredEnvConfig
-    const configPath = join(this.configDir, 'required-env.jsonc')
-    if (!existsSync(configPath)) {
-      this.requiredEnvConfig = { _common: [] }
-      return this.requiredEnvConfig
-    }
-
-    try {
-      const raw = readFileSync(configPath, 'utf8')
-      const sanitized = stripJsonComments(raw)
-      this.requiredEnvConfig = JSON.parse(sanitized || '{}') || { _common: [] }
-    } catch (error) {
-      throw new Error(`无法解析 required-env.jsonc: ${error.message}`)
-    }
-    return this.requiredEnvConfig
-  }
-
-  getRequiredEnvVars(environment, appType = null) {
-    const config = this.loadRequiredEnvConfig()
-    const base = Array.isArray(config._common) ? config._common : []
-    const envSpecific = Array.isArray(config[environment]) ? config[environment] : []
-
-    // 按应用类型添加对应的环境变量组
-    let appSpecific = []
-    if (appType) {
-      const appTypes = Array.isArray(appType) ? appType : [appType]
-      for (const type of appTypes) {
-        if (Array.isArray(config[type])) {
-          appSpecific = appSpecific.concat(config[type])
-        }
-      }
-    }
-
-    return Array.from(new Set([...base, ...envSpecific, ...appSpecific]))
-  }
-
   // 构建dotenv命令参数
   buildEnvFlags(app, environment) {
     return this.getResolvedEnvLayers(app, environment)

package/lib/exec.js

@@ -80,7 +80,7 @@ export class ExecManager {
        const policy = loadEnvPolicy(envManager.configDir)
        let requiredVars = []
 
-       if (!isCI && policy && app) {
+       if (!isCI && app) {
          const targetId = resolvePolicyTargetId(policy, app)
          if (!targetId) {
            throw new Error(
@@ -88,12 +88,6 @@ export class ExecManager {
            )
          }
          requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
-       } else if (!policy) {
-         // Backward-compatible behavior
-         // CI 环境跳过后端环境变量校验（CI 中 build backend 只生成 OpenAPI，不需要数据库连接）
-         // 根据 app 参数确定需要检查的环境变量组
-         const appType = isCI ? null : (app === 'backend' ? 'backend' : app ? 'frontend' : null)
-         requiredVars = envManager.getRequiredEnvVars(environment, appType)
        }
 
        if (requiredVars.length > 0) {

package/lib/validate-env.js

@@ -16,21 +16,7 @@ const EXTRA_ENV_IGNORED_DIRS = new Set([
   '.schaltwerk',
 ])
 const EXTRA_ENV_ALLOWED_PATHS = new Set(['docker/.env', 'docker/.env.example'])
-const LOCAL_ALLOWLIST_CONFIG = join(CONFIG_DIR, 'local-env-allowlist.jsonc')
-const EXEMPTED_KEYS_CONFIG = join(CONFIG_DIR, 'exempted-keys.jsonc')
 const ENV_EXAMPLE_FILE = join(ROOT_DIR, '.env.example')
-const PLACEHOLDER_TOKEN = '__SET_IN_env.local__'
-
-const LOCAL_ENV_FILES = [
-  '.env.development.local',
-  '.env.production.local',
-  '.env.test.local',
-  '.env.e2e.local',
-  '.env.staging.local',
-]
-
-let cachedAllowlist = null
-let cachedExemptedKeys = null
 
 export function validateEnvironment() {
   if (!process.env.NODE_ENV) {
@@ -47,15 +33,8 @@ export function validateEnvironment() {
   enforceRootOnlyEnvFiles(policy)
   enforceGlobalLocalFileProhibited()
 
-  if (policy) {
-    enforceSecretPolicy(policy)
-    enforceEnvExamplePolicy(policy)
-  } else {
-    // Backward-compatible behavior
-    enforceLocalSecretWhitelist()
-    enforceNonLocalSecretPlaceholders()
-    enforceEnvExampleSecrets()
-  }
+  enforceSecretPolicy(policy)
+  enforceEnvExamplePolicy(policy)
 
   return { nodeEnv: process.env.NODE_ENV, appEnv: process.env.APP_ENV }
 }
@@ -114,36 +93,6 @@ function enforceRootOnlyEnvFiles(policy) {
   }
 }
 
-function enforceLocalSecretWhitelist() {
-  const allowlist = loadLocalAllowlist()
-  const errors = []
-
-  for (const file of LOCAL_ENV_FILES) {
-    const fullPath = join(ROOT_DIR, file)
-    if (!existsSync(fullPath)) continue
-
-    const entries = parseEnvFile(fullPath)
-    const invalidKeys = []
-
-    for (const key of entries.keys()) {
-      if (!allowlist.has(key)) {
-        invalidKeys.push(key)
-      }
-    }
-
-    if (invalidKeys.length > 0) {
-      errors.push(`${file}: ${invalidKeys.join(', ')}`)
-    }
-  }
-
-  if (errors.length > 0) {
-    const message = errors.join('\n')
-    throw new Error(
-      `检测到 *.local 文件包含非白名单键:\n${message}\n请将这些键迁移到对应的 .env.<env> 文件，仅保留白名单内的机密信息在 *.local 中。`,
-    )
-  }
-}
-
 function enforceGlobalLocalFileProhibited() {
   const legacyLocal = join(ROOT_DIR, '.env.local')
   if (existsSync(legacyLocal)) {
@@ -320,80 +269,6 @@ function findOverlaps(namedSets) {
   return overlaps
 }
 
-function enforceNonLocalSecretPlaceholders() {
-  const allowlist = loadLocalAllowlist()
-  const exemptedKeys = loadExemptedKeys()
-  const violations = []
-
-  for (const file of listRootEnvFiles()) {
-    if (file === '.env.example') continue
-    if (file.includes('.local')) continue
-
-    const fullPath = join(ROOT_DIR, file)
-    if (!existsSync(fullPath)) continue
-
-    const entries = parseEnvFile(fullPath)
-
-    for (const [key, value] of entries.entries()) {
-      if (!allowlist.has(key)) continue
-      if (exemptedKeys.has(key)) continue // 豁免的键允许使用非占位符值
-
-      const normalized = value.trim()
-      if (normalized !== PLACEHOLDER_TOKEN) {
-        violations.push(`${file}: ${key}`)
-      }
-    }
-  }
-
-  if (violations.length > 0) {
-    const message = violations.join('\n')
-    throw new Error(
-      `检测到非 *.local 文件包含敏感键但未使用占位符 ${PLACEHOLDER_TOKEN}:\n${message}\n` +
-        `请仅在 .env.<env>.local 系列中设置真实值，并在其他文件中使用占位符。`,
-    )
-  }
-}
-
-function enforceEnvExampleSecrets() {
-  if (!existsSync(ENV_EXAMPLE_FILE)) return
-
-  const allowlist = loadLocalAllowlist()
-  const entries = parseEnvFile(ENV_EXAMPLE_FILE)
-  const disallowedKeys = []
-  const invalidPlaceholders = []
-
-  for (const [key, value] of entries.entries()) {
-    const normalized = value.trim()
-
-    if (!allowlist.has(key)) {
-      disallowedKeys.push(key)
-      continue
-    }
-
-    if (normalized !== PLACEHOLDER_TOKEN) {
-      invalidPlaceholders.push(key)
-    }
-  }
-
-  if (disallowedKeys.length > 0) {
-    throw new Error(
-      `.env.example 仅允许包含 scripts/config/local-env-allowlist.jsonc 中的键，检测到非法键: ${disallowedKeys.join(', ')}`,
-    )
-  }
-
-  if (invalidPlaceholders.length > 0) {
-    throw new Error(
-      `.env.example 中以下键未使用占位符 ${PLACEHOLDER_TOKEN}: ${invalidPlaceholders.join(', ')}`,
-    )
-  }
-}
-
-function listRootEnvFiles() {
-  return readdirSync(ROOT_DIR, { withFileTypes: true })
-    .filter(entry => entry.isFile() && entry.name.startsWith('.env'))
-    .map(entry => entry.name)
-}
-
 function parseEnvFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   const map = new Map()
@@ -415,57 +290,4 @@ function parseEnvFile(filePath) {
   return map
 }
 
-function loadLocalAllowlist() {
-  if (cachedAllowlist) return cachedAllowlist
-
-  if (!existsSync(LOCAL_ALLOWLIST_CONFIG)) {
-    throw new Error('缺少配置文件 scripts/config/local-env-allowlist.jsonc，请补充后重试')
-  }
-
-  const raw = readFileSync(LOCAL_ALLOWLIST_CONFIG, 'utf8')
-  const sanitized = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
-  const parsed = JSON.parse(sanitized || '{}') || {}
-
-  const allowedValues = Array.isArray(parsed.allowed) ? parsed.allowed : []
-  if (allowedValues.length === 0) {
-    throw new Error('local-env-allowlist.jsonc 中的 allowed 不能为空，请至少保留一个键')
-  }
-
-  const invalid = allowedValues.filter(
-    value => typeof value !== 'string' || value.trim().length === 0,
-  )
-  if (invalid.length > 0) {
-    throw new Error('local-env-allowlist.jsonc.allowed 中存在非法键，请使用非空字符串')
-  }
-
-  cachedAllowlist = new Set(allowedValues)
-  return cachedAllowlist
-}
-
-function loadExemptedKeys() {
-  if (cachedExemptedKeys) return cachedExemptedKeys
-
-  // 如果豁免配置文件不存在，返回空集合（可选配置）
-  if (!existsSync(EXEMPTED_KEYS_CONFIG)) {
-    cachedExemptedKeys = new Set()
-    return cachedExemptedKeys
-  }
-
-  const raw = readFileSync(EXEMPTED_KEYS_CONFIG, 'utf8')
-  const sanitized = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
-  const parsed = JSON.parse(sanitized || '{}') || {}
-
-  const exemptedValues = Array.isArray(parsed.exempted) ? parsed.exempted : []
-  
-  const invalid = exemptedValues.filter(
-    value => typeof value !== 'string' || value.trim().length === 0,
-  )
-  if (invalid.length > 0) {
-    throw new Error('exempted-keys.jsonc.exempted 中存在非法键，请使用非空字符串')
-  }
-
-  cachedExemptedKeys = new Set(exemptedValues)
-  return cachedExemptedKeys
-}
-
 export default { validateEnvironment }

package/package.json

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