@ranger1/dx 0.1.91 → 0.1.92

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

@@ -0,0 +1,481 @@
+---
+name: git-pr-ship
+description: PR 交付流程（仅限显式调用）
+---
+
+# PR Ship — 提交 · 审查 · 修复 · 交付
+
+## 概览
+
+一条命令完成：`Commit -> PR -> (Lint->Build->Test // 代码审查) -> 逐项修复 -> 推送 -> 下一轮`，最多三轮审查。
+
+## 执行原则
+
+- 全程中文输出。
+- 禁止在 `main/master` 直接提交。
+- 每修复一个问题立即 commit 一次，禁止攒到最后一次性提交。
+- AI 自主判断是否拒绝修复某个问题，拒绝必须写明理由。
+- 上次跑完测试/Lint 后如果改过代码，必须重跑验证。
+- 使用 heredoc 写 commit message 和 gh 命令的 body（禁止 `\n`）。
+- 零参数设计：所有信息从仓库状态、当前分支、gh CLI 自动获取，不接受手动参数。
+
+## 输入
+
+```
+/pr-ship    # 唯一入口，全自动
+```
+
+---
+
+## 阶段一：状态检测
+
+并行执行：
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline -n 5
+git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "no-upstream"
+git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo "origin/main"
+git log origin/main..HEAD --oneline
+git diff --stat origin/main...HEAD
+gh pr list --head "$(git branch --show-current)" --json number,url --limit 1
+```
+
+**自动获取上下文**：
+- Issue ID：从当前分支名提取（如 `feat/3606-xxx` -> `#3606`），或从最近 commit message 的 `Refs: #xxx` 提取
+- PR 编号：通过 `gh pr list --head <当前分支>` 获取已有 PR
+
+**决策规则：**
+
+| 条件 | 行动 |
+|------|------|
+| 已有 PR 存在 | 跳转阶段四（审查循环） |
+| 工作树有改动 | 执行完整流程（阶段二 -> 三 -> 四） |
+| 工作树干净且有未推送提交 | 跳转阶段三（PR 创建） |
+| 工作树干净且无差异 | 输出"无需提交"，结束 |
+
+---
+
+## 阶段二：Issue · 分支 · Commit
+
+### 2.1 Issue 创建
+
+若从分支名或 commit 中已提取到 Issue ID，跳过创建。
+
+收集上下文：
+
+```bash
+git diff --stat
+git diff          # 读取完整 diff 以理解改动内容
+```
+
+分析改动后创建 Issue：
+
+```bash
+gh issue create \
+  --title "[模块] 变更摘要" \
+  --label label1 --label label2 \
+  --body-file - <<'MSG'
+## 背景
+[为什么要做这个改动]
+
+## 变更内容
+- [具体改动点1]
+- [具体改动点2]
+
+## 影响范围
+[哪些模块/接口/页面受影响]
+
+## 验证方式
+- [ ] 验证项1
+- [ ] 验证项2
+MSG
+```
+
+### 2.2 分支处理
+
+若当前在 `main/master`，必须切新分支：
+
+```bash
+git switch -c <type>/<issue-id>-<slug>
+```
+
+分支前缀遵循仓库约定：`feat/` `fix/` `refactor/` `docs/` `chore/` `test/`；Codex 会话使用 `codex/` 前缀。
+
+### 2.3 Commit
+
+```bash
+git add -A
+git diff --cached --stat
+```
+
+生成 commit（分析 diff 后写出精确描述）：
+
+```bash
+git commit -F - <<'MSG'
+<type>: <概要>
+
+变更说明：
+- <改动点1：具体描述做了什么、为什么>
+- <改动点2>
+
+Refs: #<issue-id>
+MSG
+```
+
+提交后确认：
+
+```bash
+git status
+git log -1 --oneline
+```
+
+---
+
+## 阶段三：PR 创建
+
+### 3.1 推送
+
+```bash
+git push -u origin HEAD
+```
+
+### 3.2 变更分析
+
+收集完整差异信息以生成详细 PR 描述：
+
+```bash
+git log origin/main..HEAD --oneline
+git diff origin/main...HEAD --stat
+git diff origin/main...HEAD    # 完整 diff，用于分析改动细节
+```
+
+### 3.3 创建 PR
+
+PR 描述必须让审查者无需看代码就能理解改动的目的和方式：
+
+```bash
+gh pr create --base main \
+  --title "<type>: <概要>" \
+  --body-file - <<'MSG'
+## 变更目的
+
+[一段话说清楚：为什么做这个改动，解决了什么问题]
+
+## 主要改动
+
+### [模块/文件组1]
+- [改动描述：做了什么 + 为什么这样做]
+- [改动描述]
+
+### [模块/文件组2]
+- [改动描述]
+
+## 影响范围
+
+- **API 变更**：[有/无，如有列出端点]
+- **数据库变更**：[有/无，如有说明迁移]
+- **向后兼容**：[是/否，如否说明破坏点]
+
+## 验证情况
+
+- [x] 本地验证通过的项目
+- [ ] 待 CI 验证的项目
+
+## 关联
+
+Closes: #<issue-id>
+MSG
+```
+
+记录 PR 编号（`PR_NUMBER`），后续阶段使用。
+
+---
+
+## 阶段 3.5：合并冲突检测
+
+在进入审查循环之前，检查 PR 是否与目标分支存在合并冲突：
+
+```bash
+git fetch origin main
+git merge --no-commit --no-ff origin/main
+```
+
+- 如果无冲突：`git merge --abort`（撤回试探性合并），继续阶段四
+- 如果有冲突：
+  1. `git merge --abort` 撤回
+  2. 执行 `git merge origin/main`，解决所有冲突
+  3. 解决后 commit：
+     ```bash
+     git add -A
+     git commit -F - <<'MSG'
+     merge: 解决与 main 的合并冲突
+
+     - <冲突文件及解决方式>
+
+     Refs: #<issue-id>
+     MSG
+     ```
+  4. 推送：`git push`
+  5. 标记 `CODE_CHANGED_SINCE_LAST_CHECK=true`
+
+---
+
+## 阶段四：审查修复循环（最多 3 轮）
+
+循环变量：`ROUND=1`，`MAX_ROUNDS=3`，`CODE_CHANGED_SINCE_LAST_CHECK=true`
+
+### 4.1 验证流水线与代码审查（并行启动）
+
+仅在 `CODE_CHANGED_SINCE_LAST_CHECK=true` 时执行验证流水线。
+
+> **关键约束：所有子任务（验证流水线 subagent、审查者 A、审查者 B）只向主 agent 返回结果文本，禁止自行调用 `gh pr comment` 或任何方式直接发布 PR 评论。** 只有主 agent 在 4.3 才发布唯一的一条汇总报告。违反此约束会导致 PR 上出现多条重复审核报告。
+
+**两条并行主线同时启动：**
+
+---
+
+**主线 A：验证流水线（派 subagent 执行，串行有错即停）**
+
+必须派一个独立 subagent（后台运行）来执行整条流水线。不要在主 agent 里直接跑 bash 命令——主 agent 容易只跑第一步就被其他任务打断。subagent 有独立上下文，会严格按顺序跑完全部步骤。
+
+Subagent prompt 模板：
+
+```
+你是验证流水线执行者。严格按顺序执行以下步骤，任一步骤失败立即停止，不执行后续步骤。
+
+【重要】你只负责执行验证并返回结果文本。禁止调用 gh pr comment 或以任何方式直接往 PR 发评论——评论由主 agent 统一发布。
+
+Step 1: 运行 dx lint
+- 如果失败：记录所有 lint 错误，停止，返回结果
+- 如果通过：继续
+
+Step 2: 运行 dx build affected --dev
+- 如果失败：记录构建错误，停止，返回结果
+- 如果通过：继续
+
+Step 3: 运行关联测试（根据以下改动范围判断需要跑哪些）
+- 后端改动（apps/backend/）：识别受影响的 E2E 测试文件/目录 -> dx test e2e backend <file-or-dir>；识别受影响的 *.spec.ts -> 按文件运行
+- 前端改动（apps/front/）：dx test unit front
+- 管理端改动（apps/admin-front/）：dx test unit admin
+- 如果没有相关改动的测试：跳过本步骤
+
+最终返回格式：
+- 执行到第几步
+- 每步的通过/失败状态
+- 失败步骤的完整错误输出
+```
+
+任何失败都记为 **严重问题**。流水线完成后设置 `CODE_CHANGED_SINCE_LAST_CHECK=false`。
+
+---
+
+**主线 B：代码审查**
+
+审查策略根据轮次和改动规模动态调整：
+
+**第一轮：双源审查（必须）**
+
+同时派出两个独立审查者，从不同角度审查：
+
+审查者 A — 代码质量与架构（派独立 subagent）：
+- 关注：架构合理性、SOLID 原则、错误处理、性能、安全
+- 输入：PR diff
+
+审查者 B — 逻辑缺陷与规范（派独立 subagent）：
+- 关注：逻辑缺陷、边界条件、命名规范、类型安全、测试覆盖
+- 输入：PR diff
+
+> **禁止使用 `code-review` 技能或 `oh-my-claudecode:code-reviewer` agent 来执行审查。** 这些工具内置了自动发 PR 评论的行为，会导致 PR 上出现多条重复审核报告。必须派独立 subagent，并在 prompt 中明确要求"只返回审查结果文本，禁止调用 gh pr comment 或以任何方式发布 PR 评论"。
+
+Subagent A prompt：
+```
+作为资深架构师审查此 PR diff，关注架构、性能、安全问题。
+【重要】只返回审查结果文本给调用者。禁止调用 gh pr comment 或以任何方式直接往 PR 发评论——评论由主 agent 统一发布。
+```
+
+Subagent B prompt：
+```
+作为质量工程师审查此 PR diff，关注逻辑缺陷、边界条件、规范遵从。
+【重要】只返回审查结果文本给调用者。禁止调用 gh pr comment 或以任何方式直接往 PR 发评论——评论由主 agent 统一发布。
+```
+
+**第二轮及以后：按需降级**
+
+根据上一轮修复情况自主决策审查力度：
+
+- 单源审查（默认）：改动较小、仅修复 Minor 问题、或改动集中在少数文件 -> 派一个 subagent 即可
+- 双源审查：改动较大、涉及核心逻辑修改、或上一轮有 Critical 修复引入新代码 -> 仍派两个 subagent
+
+同样，后续轮次的审查 subagent 也必须遵守"只返回结果文本、禁止发 PR 评论"的约束。
+
+是否进行第二轮/第三轮审查也需自主判断：
+- 上一轮全部修复且改动简单（仅格式/命名调整）-> 可以跳过后续审查，直接进入最终验证
+- 上一轮有 Critical/Major 修复 -> 应进入下一轮审查
+
+---
+
+主线 A 和主线 B 同时启动，等待全部完成后进入 4.2。
+
+### 4.2 问题汇总与去重
+
+收集所有来源的问题：
+- Lint 错误（来自主线 A Step 1）
+- 构建失败（来自主线 A Step 2）
+- 测试失败（来自主线 A Step 3，列出失败的用例名和错误信息）
+- 审查者 A 的发现
+- 审查者 B 的发现（如有）
+
+**去重规则**：
+- 同一文件同一行的相同类型问题 -> 合并，保留描述更详细的那条
+- 同一根因导致的多个测试失败 -> 合并为一条，附带所有失败用例名
+- 两个审查者指出的同一问题 -> 合并，综合两者描述
+
+为每个问题分配严重级别：
+- **Critical**：构建失败、测试失败、安全漏洞、数据丢失风险
+- **Major**：逻辑缺陷、错误处理缺失、性能问题
+- **Minor**：命名不规范、代码风格、文档缺失
+
+### 4.3 发布审核报告到 PR
+
+如果没有任何问题，跳转到"审查通过"流程（4.6）。
+
+将汇总结果作为 PR 评论发布：
+
+```bash
+gh pr comment <PR_NUMBER> --body-file - <<'MSG'
+## 审核报告（第 N 轮）
+
+### 概要
+- Critical：X 个
+- Major：Y 个
+- Minor：Z 个
+
+### Critical 问题
+| # | 来源 | 文件:行号 | 描述 |
+|---|------|-----------|------|
+| 1 | Lint/构建/测试 | path/to/file:42 | 描述 |
+
+### Major 问题
+| # | 来源 | 文件:行号 | 描述 |
+|---|------|-----------|------|
+| 1 | 审查者A | path/to/file:10 | 描述 |
+
+### Minor 问题
+| # | 来源 | 文件:行号 | 描述 |
+|---|------|-----------|------|
+| 1 | 审查者B | path/to/file:5 | 描述 |
+
+---
+*审查工具：dx lint -> dx build -> dx test + 代码审查*
+MSG
+```
+
+### 4.4 逐项修复
+
+按严重级别从高到低处理每个问题。
+
+对每个问题：
+
+1. **判断是否修复**：
+   - 修复：执行修改
+   - 拒绝：记录理由（如：误报、设计意图、超出本 PR 范围）
+
+2. **修复后立即 commit**（一个问题一个 commit）：
+
+```bash
+git add <修改的文件>
+git commit -F - <<'MSG'
+fix: 修复审查问题 #<问题编号> — <简要描述>
+
+- <具体改动说明>
+
+Refs: #<issue-id>
+MSG
+```
+
+3. 标记 `CODE_CHANGED_SINCE_LAST_CHECK=true`
+
+### 4.5 发布修复报告 + 推送
+
+推送所有修复 commit：
+
+```bash
+git push
+```
+
+发布修复报告到 PR：
+
+```bash
+gh pr comment <PR_NUMBER> --body-file - <<'MSG'
+## 修复报告（第 N 轮）
+
+### 已修复
+| # | 问题 | 修复方式 | Commit |
+|---|------|----------|--------|
+| 1 | [问题描述] | [修复说明] | abc1234 |
+
+### 拒绝修复
+| # | 问题 | 理由 |
+|---|------|------|
+| 1 | [问题描述] | [拒绝理由：如误报/设计意图/超出范围] |
+
+### 统计
+- 总问题数：X
+- 已修复：Y
+- 拒绝修复：Z
+MSG
+```
+
+### 4.6 决定是否下一轮
+
+**审查通过条件**（满足任一即结束）：
+- 本轮零问题
+- 已达到 `MAX_ROUNDS`（3 轮）
+- 所有问题均已修复且改动简单（仅格式/命名），无需再审
+
+**继续下一轮条件**（同时满足）：
+- `ROUND < MAX_ROUNDS`
+- 本轮有修复过代码（`CODE_CHANGED_SINCE_LAST_CHECK=true`）
+- 存在 Critical 或 Major 级别的修复（可能引入新问题）
+
+若继续：`ROUND += 1`，回到 4.1。
+
+若结束且 `CODE_CHANGED_SINCE_LAST_CHECK=true`：执行最终验证——按串行顺序跑 `dx lint` -> `dx build affected --dev` -> 关联测试，有错即停。有失败则修复并 commit/push，无失败则完成。
+
+---
+
+## 阶段五：完成输出
+
+```
+PR Ship 完成！
+
+- Issue: #<ID> <标题>
+- PR: #<PR_NUMBER> <链接>
+- 审查轮数：N
+- 总提交数：X（初始 + 修复）
+- 问题统计：发现 A 个 / 修复 B 个 / 拒绝 C 个
+
+状态：✓ Lint 通过 ✓ 构建通过 ✓ 测试通过 ✓ 审查完成
+```
+
+---
+
+## 失败与中断
+
+如果任何阶段不可恢复地失败，输出：
+
+- 停止阶段
+- 已完成列表
+- 阻塞原因
+- 建议的人工介入方式
+
+## 质量检查清单
+
+- PR 描述让审查者无需看代码就能理解改动
+- 每个 commit message 精确描述改动内容和原因
+- 审核报告中相同问题已合并
+- 每个修复都是独立 commit
+- 拒绝修复的问题都有理由
+- 最终状态：Lint/构建/测试全部通过

package/skills/naming-audit-fixer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: naming-audit-fixer
+description: 审计并修复任意 JS/TS 项目的文件和文件夹命名规范。由模型判断框架、源码目录和自定义约定，再调用脚本执行扫描。当用户提到"命名规范"、"文件命名检查"、"naming convention"、"rename files"、"文件名不规范"、"命名审计"，或讨论文件/文件夹命名最佳实践时触发。即使用户只是问"检查一下命名"也应触发。
+---
+
+# 文件/文件夹命名规范审计与修复
+
+模型负责决策（判断框架、确定扫描范围、识别项目自定义约定），脚本负责执行（按规则遍历文件树、匹配违规、输出报告）。
+
+## 执行流程
+
+```
+模型分析项目 → 生成扫描配置 → 调用脚本 → 解读报告 → 展示给用户 → [用户确认] → 分批修复
+```
+
+### Step 1: 分析项目（模型完成）
+
+阅读以下文件来判断项目技术栈和目录结构：
+
+1. **`package.json`**（根目录和各 app 目录）— 识别依赖的框架
+2. **`pnpm-workspace.yaml`** 或 `package.json` 的 `workspaces` 字段 — 确定 monorepo 结构
+3. **`tsconfig.json`** — 确认源码目录（`rootDir`、`include`）
+4. **`CLAUDE.md` / `AGENTS.md`** — 识别项目自定义命名约定（优先级最高）
+5. **项目目录结构**（`ls` 快速浏览）— 确认实际源码位置
+
+根据分析结果，确定：
+- 每个 app 使用什么框架
+- 每个 app 的源码根目录
+- 是否有 Next.js app 目录（路由文件豁免需要）
+- 需要额外跳过的目录（如 `generated/`、`__generated__/`）
+- 需要额外豁免的文件（如项目特有的入口文件）
+
+### Step 2: 生成扫描配置并调用脚本
+
+构造 JSON 配置，通过 stdin 传给脚本：
+
+```bash
+echo '{
+  "scans": [
+    {
+      "root": "apps/backend/src",
+      "framework": "nestjs",
+      "extra_skip_dirs": [],
+      "extra_ok_files": []
+    },
+    {
+      "root": "apps/backend/e2e",
+      "framework": "nestjs",
+      "extra_skip_dirs": [],
+      "extra_ok_files": []
+    },
+    {
+      "root": "apps/front/src",
+      "framework": "nextjs-react",
+      "app_dir": "app",
+      "extra_skip_dirs": [],
+      "extra_ok_files": []
+    },
+    {
+      "root": "apps/admin/src",
+      "framework": "react",
+      "extra_skip_dirs": [],
+      "extra_ok_files": []
+    }
+  ]
+}' | python ~/.claude/skills/naming-audit-fixer/scripts/audit_naming.py
+```
+
+**配置字段说明：**
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `root` | 是 | 要扫描的目录（相对于项目根目录） |
+| `framework` | 是 | 命名规则集，见下方 |
+| `app_dir` | 否 | Next.js app 目录名（默认 `app`），仅 `nextjs-react` 需要 |
+| `extra_skip_dirs` | 否 | 额外要跳过的目录名 |
+| `extra_ok_files` | 否 | 额外要豁免的文件名 |
+
+**支持的 framework 值：**
+
+| 值 | 适用场景 | 核心规则 |
+|----|---------|---------|
+| `nestjs` | NestJS 后端 | `kebab-name.type.ts`，目录 kebab-case |
+| `nextjs-react` | Next.js + React | .tsx PascalCase，.ts kebab-case，路由文件豁免 |
+| `react` | React SPA / Vite | .tsx PascalCase，.ts kebab-case |
+| `vue` | Vue | .vue PascalCase 或 kebab-case，.ts kebab-case |
+| `angular` | Angular | `kebab-name.type.ts`，类似 NestJS |
+| `generic-ts` | 通用 TypeScript | 全 kebab-case |
+
+### Step 3: 解读并展示报告
+
+脚本输出 JSON，包含：
+- `total_violations` — 违规总数
+- `summary_by_rule` — 按规则分类的计数
+- `violations[]` — 每条违规（path / rule / current / suggested）
+- `fix_plan[]` — 可执行的 `git mv` 命令
+
+向用户展示：
+1. 按规则分类的汇总表
+2. 按目录分组的详细列表（当前名 → 建议名）
+3. 询问是否进入修复
+
+**不要在审计阶段自动改代码。**
+
+### Step 4: 修复（用户确认后）
+
+阅读 [references/fix-guide.md](./references/fix-guide.md) 获取详细步骤。要点：
+
+1. **目录优先** — 先 `git mv` 重命名目录
+2. **按模块分批** — 每次处理一个模块下的文件
+3. **同步引用** — 每次重命名后用 Grep 找所有 import/require 引用，用 Edit 更新
+4. **检查 barrel** — 更新 `index.ts` 的 re-export
+5. **增量验证** — 每个模块改完跑 lint + build
+6. **最终测试** — 全部完成后跑受影响的测试
+
+## 命名规则速查
+
+### NestJS
+
+| 正确 | 错误 | 原因 |
+|------|------|------|
+| `send-message.request.dto.ts` | `send.message.request.dto.ts` | name 部分用连字符 |
+| `ai-model/` | `ai.model/` | 目录用 kebab-case |
+| `message-not-found.exception.ts` | `message.not.found.exception.ts` | name 部分用连字符 |
+
+### Next.js + React
+
+| 文件类型 | 规范 | 示例 |
+|---------|------|------|
+| 组件 .tsx | PascalCase | `ChatPanel.tsx` |
+| 工具 .ts | kebab-case | `sort-mappings.ts` |
+| Hook .ts | camelCase | `useChat.ts` |
+| 路由文件 | 小写（豁免） | `page.tsx`, `layout.tsx` |
+| 目录 | kebab-case | `character/` |
+
+### Vue
+
+| 文件类型 | 规范 | 示例 |
+|---------|------|------|
+| 组件 .vue | PascalCase 或 kebab-case | `UserCard.vue` 或 `user-card.vue` |
+| 工具 .ts | kebab-case | `format-date.ts` |
+
+## 注意事项
+
+- **项目约定优先**：如果 CLAUDE.md / AGENTS.md 定义了自己的命名规范，以项目为准
+- 脚本结果可能有误报，展示前应抽查
+- 目录重命名影响大，建议单独 commit
+- 入口文件、声明文件、动态路由自动豁免
+- `node_modules/`、`dist/`、`migrations/` 等自动跳过