@ranger1/dx 0.1.97 → 0.1.99

package/README.md

@@ -4,6 +4,38 @@
 
 本工具通过项目内的 `dx/config/*` 配置文件来驱动命令执行：你可以把它理解成「带环境变量分层 + 校验 + 命令编排能力的脚本系统」。
 
+## 当前规范
+
+当前版本的 `dx` 已收敛到 strict 配置规范。
+
+这意味着：
+
+- 配置写错时直接报错，不再自动兼容旧写法
+- `help` 输出由 `dx/config/commands.json` 动态生成，不再依赖代码中的大段硬编码文案
+- 命令配置中的环境分支必须使用完整环境键
+
+当前推荐且受支持的环境键：
+
+- `development`
+- `staging`
+- `production`
+- `test`
+- `e2e`
+
+当前推荐且受支持的 CLI 环境标志：
+
+- `--dev`
+- `--staging`
+- `--prod`
+- `--test`
+- `--e2e`
+
+不再建议写法：
+
+- `dev` / `prod` 作为配置节点名
+- `--development` / `--production` / `--stage`
+- 任何旧配置回退、旧命令别名或自动输入修正
+
 ## 安装
 
 必须全局安装，并始终使用最新版本：
@@ -70,12 +102,14 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 
 ### 1) dx/config/commands.json
 
-这是核心文件，定义了 dx 各命令要执行的 shell 命令，支持：
+这是核心文件，定义了 dx 各命令要执行的 shell 命令，也承载帮助信息配置。
+
+它支持：
 
 - 单命令：`{ "command": "..." }`
-- 并发：`{ "concurrent": true, "commands": ["build.front.dev", "build.admin.dev"] }`
-- 串行：`{ "sequential": true, "commands": ["build.backend.prod", "build.sdk"] }`
-- 环境分支：如 `build.backend.dev` / `build.backend.prod`（dx 会根据 `--dev/--prod/--staging/...` 选择）
+- 并发：`{ "concurrent": true, "commands": ["build.front.development", "build.admin.development"] }`
+- 串行：`{ "sequential": true, "commands": ["build.backend.production", "build.sdk"] }`
+- 环境分支：如 `build.backend.development` / `build.backend.production`（dx 会根据 `--dev/--prod/--staging/...` 选择）
 - dotenv 包裹：配置里带 `"app": "backend"` 时，dx 会按 `env-layers.json` 拼出 dotenv 层并用 `pnpm exec dotenv ... -- <command>` 执行
 
 常见字段（单命令配置）：
@@ -95,9 +129,39 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 命令路径引用（并发/串行的 commands 数组）使用点号字符串，例如：
 
 ```json
-{ "concurrent": true, "commands": ["build.shared", "build.front.dev"] }
+{ "concurrent": true, "commands": ["build.shared", "build.front.development"] }
+```
+
+帮助配置示例：
+
+```json
+{
+  "help": {
+    "summary": "统一开发环境管理工具",
+    "globalOptions": [
+      { "flags": ["--dev"], "description": "使用 development 环境" },
+      { "flags": ["--prod"], "description": "使用 production 环境" }
+    ],
+    "commands": {
+      "start": {
+        "summary": "启动/桥接服务",
+        "notes": ["未指定 service 时默认使用开发套件，仅允许 --dev"],
+        "examples": [
+          { "command": "dx start backend --dev", "description": "启动后端开发服务" }
+        ]
+      }
+    }
+  }
+}
 ```
 
+约束：
+
+- 命令级帮助推荐放在 `help.commands.<command>`
+- target 级帮助推荐放在 `help.targets.<command>.<target>`
+- 帮助示例必须与真实命令树一致，不能写配置里不存在的 target
+- 运行时会校验 help 配置结构；坏配置会直接报错
+
 ### 2) dx/config/env-layers.json
 
 用于定义不同环境下加载哪些 `.env.*` 文件（顺序 = 覆盖优先级）。格式：
@@ -202,6 +266,15 @@ dx test e2e backend apps/backend/e2e/auth
 dx test e2e quantify apps/quantify/e2e/health/health.e2e-spec.ts
 ```
 
+关于 `help`：
+
+- `dx --help`
+- `dx help <command>`
+
+现在都优先从 `commands.json` 的 `help` 区域动态生成。
+
+如果某个命令还没有补充足够的 `help` 元数据，输出会回退到配置结构推导出的最小帮助，而不是旧的手写兼容文案。
+
 命令约束摘要：
 
 - 对声明了 `requiresPath: true` 的 E2E target，`dx test e2e <target>` 必须提供文件或目录路径，禁止无路径或 `all` 全量执行

package/lib/cli/dx-cli.js

@@ -164,8 +164,17 @@ class DxCli {
 
   // 检测并生成 Prisma Client
   async ensurePrismaClient() {
+    // 仅对真正安装了 @prisma/client 的项目执行检查。
+    // 依据「node_modules/@prisma/client/package.json 是否存在」判断项目是否使用 Prisma，
+    // 避免在纯文档站、纯前端等未引入 Prisma 的项目上误触发生成流程，
+    // 进而报出形如「未找到 db.generate 命令配置」的误导性错误。
+    const prismaClientDir = join(process.cwd(), 'node_modules', '@prisma', 'client')
+    if (!existsSync(join(prismaClientDir, 'package.json'))) {
+      return
+    }
+
     // pnpm 结构下检测 @prisma/client 生成的 default.js 文件
-    const prismaClientPath = join(process.cwd(), 'node_modules', '@prisma', 'client', 'default.js')
+    const prismaClientPath = join(prismaClientDir, 'default.js')
 
     if (!existsSync(prismaClientPath)) {
       const environment = this.determineEnvironment()

package/lib/cli/help-renderer.js

@@ -83,6 +83,8 @@ export function renderGlobalHelp(model = {}) {
   pushSection(lines, '选项:', normalizeArray(model.globalOptions).map(option => formatOption(option)))
   pushSection(lines, '示例:', normalizeArray(model.examples).map(example => formatExample(example)))
 
+  lines.push('', `运行 ${invocation} help <命令> 查看子命令的详细用法和示例`)
+
   return lines.join('\n')
 }
 

package/lib/validate-env.js

@@ -245,15 +245,31 @@ function isAllowedBySimpleGlob(path, globs) {
       if (glob === path) return true
       continue
     }
-    // Only support a single trailing '*' for now.
-    if (glob.endsWith('*')) {
-      const prefix = glob.slice(0, -1)
-      if (path.startsWith(prefix)) return true
-    }
+    if (globToRegex(glob).test(path)) return true
   }
   return false
 }
 
+function globToRegex(glob) {
+  let pattern = ''
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i]
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        pattern += '.*'
+        i += 1
+      } else {
+        pattern += '[^/]*'
+      }
+    } else if ('\\^$+?.()|[]{}'.includes(ch)) {
+      pattern += `\\${ch}`
+    } else {
+      pattern += ch
+    }
+  }
+  return new RegExp(`^${pattern}$`)
+}
+
 function findOverlaps(namedSets) {
   const seen = new Map()
   const overlaps = []

package/package.json

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

package/skills/autospec/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: autospec
+description: 设计文档到实施计划的全自动流水线。仅在用户显式调用时触发（如 /autospec），不通过关键词自动触发。将已讨论好的设计方案依次执行：写设计文档 → critic 审核修复 → 写实施计划 → critic 审核修复 → 自动开始 subagent-driven 执行 → git-pr-ship 交付 PR。
+---
+
+# spec-to-plan：设计文档 → 审核 → 实施计划 → 审核 → 执行 → 交付 PR
+
+六步全自动流水线。用户在 brainstorming 阶段讨论好目标和方案后显式调用，后续全部自动完成，无需人工干预。
+
+## 输入
+
+`/spec-to-plan <topic-slug>`
+
+- `topic-slug`：文件命名用，如 `chat-instruction-admin`
+- 当前对话中必须已包含充分的设计上下文（目标、方案、数据模型、API、技术决策等）
+
+## 输出
+
+- 审核后的设计文档：`docs/superpowers/specs/YYYY-MM-DD-<topic-slug>-design.md`
+- 审核后的实施计划：`docs/superpowers/plans/YYYY-MM-DD-<topic-slug>.md`
+- 自动进入 subagent-driven 执行模式
+
+## 执行流程
+
+严格按顺序执行五步，中间不暂停、不询问用户。
+
+---
+
+### Step 1：撰写设计文档
+
+从当前对话上下文中提取所有已确认的设计决策，写入设计文档。不臆造未讨论过的需求。
+
+**路径**：`docs/superpowers/specs/YYYY-MM-DD-<topic-slug>-design.md`
+
+**结构**（按需裁剪，无内容的章节不写）：
+
+```markdown
+# <功能名称>
+
+## 背景
+## 数据模型
+## API 设计
+## 缓存策略
+## 前端改造
+## 必要的集成步骤
+## Seed 数据
+## 模块结构
+## 不做的事
+```
+
+**自检**：写完后扫描——无 TBD/TODO、章节不矛盾、范围聚焦、无歧义。发现问题直接修。
+
+---
+
+### Step 2：审核设计文档
+
+派出 `oh-my-claudecode:critic` subagent 审核。
+
+**Prompt**：
+
+```
+请以挑刺的角度审核这份设计文档，结合项目实际代码验证每一个设计决策。
+
+文档路径：<spec-path>
+
+审核要点：
+1. 数据模型：字段命名、ID 策略、@map/@@map 是否匹配项目惯例
+2. 模块结构：目录组织是否与现有模块一致
+3. API 设计：路由前缀、鉴权、分页 DTO 继承是否符合惯例
+4. 缓存：CacheService 方法签名是否正确
+5. 前端：store 组织、API 调用模式、组件层级是否匹配实际代码
+6. 集成步骤：是否遗漏 ErrorCode、Swagger、RBAC、api-contracts、菜单注册等
+7. Seed：入口注册、幂等策略是否正确
+
+每个发现给出具体文件路径和代码证据。
+分为：错误（必须修复）、遗漏（建议补充）、建议（可选优化）。
+```
+
+**处理结果**：读取 critic 返回，逐一修复设计文档。错误和遗漏全部修复，建议类酌情采纳。不改变已与用户确认的设计决策，只修事实性错误和惯例偏差。
+
+---
+
+### Step 3：撰写实施计划
+
+基于审核后的设计文档写实施计划。
+
+**路径**：`docs/superpowers/plans/YYYY-MM-DD-<topic-slug>.md`
+
+**头部**（固定格式）：
+
+```markdown
+# <功能名称> Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task.
+
+**Goal:** 一句话
+**Architecture:** 2-3 句
+**Tech Stack:** 关键技术
+**Spec:** <spec-path>
+
+---
+```
+
+**Task 结构**：
+
+```markdown
+### Task N: <组件名>
+
+**Files:**
+- Create: `exact/path`
+- Modify: `exact/path`
+
+- [ ] **Step 1: 描述**
+（完整代码块）
+
+- [ ] **Step 2: 验证**
+Run: `命令`
+Expected: 预期
+
+- [ ] **Step 3: Commit**
+```
+
+**要求**：
+- 每步完整代码，禁止 TBD/TODO/"类似 Task N"
+- import 路径准确（基于 Step 2 审核已验证的惯例）
+- Task 按依赖顺序排列
+- 粒度 2-5 分钟每 Task
+
+**自检**：spec 每个章节有对应 Task、无占位符、类型和方法名前后一致。
+
+---
+
+### Step 4：审核实施计划
+
+派出 `oh-my-claudecode:critic` subagent 审核。
+
+**Prompt**：
+
+```
+请以挑刺的角度审核这份实施计划，结合项目实际代码验证每一个代码片段。
+
+计划路径：<plan-path>
+设计文档：<spec-path>
+
+审核要点：
+1. Import 路径：每个 import 在项目中是否真实存在
+2. 路由冲突：参数路由 (:id) 和固定路由的顺序
+3. API 方法名：Zodios 等生成的方法命名是否匹配惯例
+4. 测试基建：E2E setup 是否匹配项目 fixtures
+5. Seed 入口：注册方式是否匹配项目结构
+6. Store 注册：前端 store 根注册方式是否正确
+7. 页面路由：文件路径能否自动注册路由
+8. DTO/Exception：构造函数签名、方法名是否匹配实际 API
+9. 遗漏：spec 中的需求是否全部覆盖
+
+每个发现给出具体文件路径和代码证据。
+分为：错误（必须修复）、遗漏（建议补充）、建议（可选优化）。
+```
+
+**处理结果**：读取 critic 返回，逐一修复实施计划。错误和遗漏全部修复。
+
+---
+
+### Step 5：自动开始执行
+
+四步文档工作完成后，直接调用 `superpowers:subagent-driven-development` skill，传入实施计划路径，开始 Task-by-Task 的 subagent 执行。
+
+不询问用户选择执行方式，直接以 subagent-driven 模式启动。
+
+输出简短状态通知：
+
+```
+设计文档：<spec-path>（已审核修复）
+实施计划：<plan-path>（已审核修复，共 N 个 Task）
+正在以 subagent-driven 模式开始执行...
+```
+
+---
+
+### Step 6：调用 git-pr-ship 交付 PR
+
+subagent-driven 执行全部 Task 完成并通过验证后，直接调用 `git-pr-ship` skill，进入 PR 交付流程。
+
+前置条件（执行阶段应已满足，若未满足先补齐）：
+- 全部 Task 已完成并勾选
+- 代码变更已提交到当前功能分支
+- lint、构建、相关测试已通过
+
+不询问用户，直接以 `git-pr-ship` 流程收口：整理提交、推送分支、创建 PR。
+
+输出简短状态通知：
+
+```
+实施已全部完成并验证通过。
+正在调用 git-pr-ship 交付 PR...
+```
+
+## 注意事项
+
+- 设计文档内容完全来自对话上下文，不臆造未讨论过的需求
+- critic 修复只改事实错误和惯例偏差，不改变用户已确认的设计决策
+- 如果 critic 发现的问题数量极多（>10 个错误级），在修复后可考虑再跑一轮 critic 确认
+- 整个流程对用户透明——每步开始时输出一行状态（如"正在撰写设计文档..."），但不等待确认

package/skills/git-pr-ship/SKILL.md

@@ -15,6 +15,7 @@ description: PR 交付流程（仅限显式调用）
 - 禁止在 `main/master` 直接提交。
 - 每修复一个问题立即 commit 一次，禁止攒到最后一次性提交。
 - AI 自主判断是否拒绝修复某个问题，拒绝必须写明理由。
+- 扫描范围内顺便发现的历史遗留问题（非本次 PR 引入），视同本次问题一并修复，不以"历史遗留"或"超出本 PR 范围"为由跳过。但不主动扩大扫描范围去寻找无关问题。
 - 上次跑完测试/Lint 后如果改过代码，必须重跑验证。
 - 使用 heredoc 写 commit message 和 gh 命令的 body（禁止 `\n`）。
 - 零参数设计：所有信息从仓库状态、当前分支、gh CLI 自动获取，不接受手动参数。
@@ -281,10 +282,12 @@ Step 3: 运行关联测试（根据以下改动范围判断需要跑哪些）
 
 审查者 A — 代码质量与架构（派独立 subagent）：
 - 关注：架构合理性、SOLID 原则、错误处理、性能、安全
+- 审查 PR diff 涉及的文件时，如果顺便发现同一文件中的历史遗留问题，也一并报告（不主动扩大到 diff 之外的文件）
 - 输入：PR diff
 
 审查者 B — 逻辑缺陷与规范（派独立 subagent）：
 - 关注：逻辑缺陷、边界条件、命名规范、类型安全、测试覆盖
+- 审查 PR diff 涉及的文件时，如果顺便发现同一文件中的历史遗留问题，也一并报告（不主动扩大到 diff 之外的文件）
 - 输入：PR diff
 
 > **禁止使用 `code-review` 技能或 `oh-my-claudecode:code-reviewer` agent 来执行审查。** 这些工具内置了自动发 PR 评论的行为，会导致 PR 上出现多条重复审核报告。必须派独立 subagent，并在 prompt 中明确要求"只返回审查结果文本，禁止调用 gh pr comment 或以任何方式发布 PR 评论"。
@@ -292,12 +295,14 @@ Step 3: 运行关联测试（根据以下改动范围判断需要跑哪些）
 Subagent A prompt：
 ```
 作为资深架构师审查此 PR diff，关注架构、性能、安全问题。
+审查 diff 涉及的文件时，如果顺便发现同一文件中已有的历史遗留问题（非本次 diff 引入），也一并报告——不要因为是历史代码就忽略。但不要主动扩大到 diff 未涉及的文件。
 【重要】只返回审查结果文本给调用者。禁止调用 gh pr comment 或以任何方式直接往 PR 发评论——评论由主 agent 统一发布。
 ```
 
 Subagent B prompt：
 ```
 作为质量工程师审查此 PR diff，关注逻辑缺陷、边界条件、规范遵从。
+审查 diff 涉及的文件时，如果顺便发现同一文件中已有的历史遗留问题（非本次 diff 引入），也一并报告——不要因为是历史代码就忽略。但不要主动扩大到 diff 未涉及的文件。
 【重要】只返回审查结果文本给调用者。禁止调用 gh pr comment 或以任何方式直接往 PR 发评论——评论由主 agent 统一发布。
 ```
 
@@ -379,8 +384,8 @@ MSG
 对每个问题：
 
 1. **判断是否修复**：
-   - 修复：执行修改
-   - 拒绝：记录理由（如：误报、设计意图、超出本 PR 范围）
+   - 修复：执行修改（包括扫描过程中顺便发现的历史遗留问题，不以"非本次引入"为由跳过）
+   - 拒绝：记录理由（如：误报、设计意图如此）。"历史遗留"或"超出本 PR 范围"不是合法的拒绝理由
 
 2. **修复后立即 commit**（一个问题一个 commit）：
 

package/skills/git-release/SKILL.md

@@ -33,7 +33,7 @@ description: 在 Git 仓库中执行标准化版本发布流程并自动生成
 - `release/v1.2.3` -> `v1.2.3` -> `1.2.3`
 - `release/v1.2.3-beta.2` -> `v1.2.3-beta.2` -> `1.2.3-beta.2`
 7. 检查目标 tag 是否已存在：`git tag -l "v<VERSION>"`。
-8. 向用户确认版本号；若用户修改版本号，重新校验格式与 tag 冲突。
+8. 输出推断出的版本号，直接使用该版本号继续执行，无需等待用户确认。
 
 ### 二、更新版本号