@ranger1/dx 0.1.104 → 0.1.106

package/lib/codex-initial.js

@@ -6,6 +6,24 @@ import { logger } from './logger.js'
 
 const TEMP_DIR_PATTERN = /^\..+\.(tmp|backup)-\d+-\d+$/
 
+// 历史上曾在 skills/ 目录托管、但后续已删除的 skill 名称。
+// 来源：git log --all --diff-filter=A --name-only -- 'skills/*' | sed -n 's#^skills/\([^/]*\)/.*#\1#p' | sort -u
+// 再减去当前 skills/ 现存名单。
+// 这些名字需要在 ~/.agents、~/.claude、~/.codex 三处彻底清理（软链或真实目录都清）。
+// 将来从 skills/ 删除新的 skill 时，把它追加到这里即可。
+const DELETED_SKILLS = [
+  'autospec',
+  'backend-layering-audit-fixer',
+  'e2e-audit-fixer',
+  'env-accessor-audit-fixer',
+  'error-handling-audit-fixer',
+  'multi-pr-feature-delivery',
+  'naming-convention-audit',
+  'omc-reference',
+  'pagination-dto-audit-fixer',
+  'pr-ship',
+]
+
 async function collectSkillNames(dir) {
   const entries = await fs.readdir(dir, { withFileTypes: true })
   return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name)
@@ -51,6 +69,15 @@ async function pathExists(path) {
   }
 }
 
+async function lstatIfExists(path) {
+  try {
+    return await fs.lstat(path)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
 async function assertDirExists(path, label) {
   try {
     const st = await fs.stat(path)
@@ -58,6 +85,9 @@ async function assertDirExists(path, label) {
       throw new Error(`${label} 不是目录: ${path}`)
     }
   } catch (error) {
+    if (error?.message?.startsWith(`${label} 不是目录:`)) {
+      throw error
+    }
     const message = error?.message || String(error)
     throw new Error(`${label} 不存在或不可访问: ${path}\n${message}`)
   }
@@ -113,18 +143,42 @@ async function copyDirMerge({ srcDir, dstDir }) {
 }
 
 async function removeManagedNonSymlinkSkills(skillsDir, skillNames) {
+  for (const skillName of skillNames) {
+    const target = join(skillsDir, skillName)
+    const stat = await lstatIfExists(target)
+    if (!stat) continue
+    if (stat.isSymbolicLink()) continue
+    await fs.rm(target, { recursive: true, force: true })
+  }
+}
+
+// 彻底清理指定名称的 skill：无论是软链还是真实目录/文件都删除。
+// 用于历史上已从 skills/ 删除的 skill，需在各目标目录连根拔除。
+// 这是尽力而为的清理：单个名字清理失败（如权限问题）只记录并继续，
+// 不抛出，避免一个陈旧副本的异常阻断整个 skill 同步主流程。
+async function purgeSkills(skillsDir, skillNames) {
+  let purged = 0
+  let failed = 0
   for (const skillName of skillNames) {
     const target = join(skillsDir, skillName)
     let stat
     try {
-      stat = await fs.lstat(target)
+      stat = await lstatIfExists(target)
     } catch (error) {
-      if (error?.code === 'ENOENT') continue
-      throw error
+      logger.warn(`清理历史 skill 失败（跳过）: ${target} — ${error?.message || String(error)}`)
+      failed++
+      continue
+    }
+    if (!stat) continue
+    try {
+      await fs.rm(target, { recursive: true, force: true })
+      purged++
+    } catch (error) {
+      logger.warn(`清理历史 skill 失败（跳过）: ${target} — ${error?.message || String(error)}`)
+      failed++
     }
-    if (stat.isSymbolicLink()) continue
-    await fs.rm(target, { recursive: true, force: true })
   }
+  return { purged, failed }
 }
 
 async function removeStaleTempDirs(skillsDir) {
@@ -173,6 +227,12 @@ export async function runCodexInitial(options = {}) {
   await assertDirExists(srcSkillsDir, '模板目录 skills')
   const skillNames = await collectSkillNames(srcSkillsDir)
 
+  // 护栏：已删除名单不得与现存 skill 重叠，否则会把刚同步的 skill 又清掉（自相矛盾）。
+  const overlap = DELETED_SKILLS.filter((name) => skillNames.includes(name))
+  if (overlap.length > 0) {
+    throw new Error(`DELETED_SKILLS 与现存 skills/ 重叠，需修正名单: ${overlap.join(', ')}`)
+  }
+
   await ensureDir(codexSkillsDir)
   await ensureDir(claudeSkillsDir)
   await ensureDir(agentsSkillsDir)
@@ -180,6 +240,13 @@ export async function runCodexInitial(options = {}) {
   await removeManagedNonSymlinkSkills(codexSkillsDir, skillNames)
   await removeManagedNonSymlinkSkills(claudeSkillsDir, skillNames)
 
+  // 清理历史上已删除的 skill：在 agents/claude/codex 三处连根拔除（含 agents 真实副本与软链）。
+  // 先清 claude（指向 agents 的软链宿主），再清 agents/codex（真实副本），
+  // 避免中途失败时留下指向已删除 agents target 的悬空软链。
+  const purgeClaude = await purgeSkills(claudeSkillsDir, DELETED_SKILLS)
+  const purgeAgents = await purgeSkills(agentsSkillsDir, DELETED_SKILLS)
+  const purgeCodex = await purgeSkills(codexSkillsDir, DELETED_SKILLS)
+
   await removeStaleTempDirs(agentsSkillsDir)
   const copyStats = await copyDirMerge({ srcDir: srcSkillsDir, dstDir: agentsSkillsDir })
   await removeStaleTempDirs(agentsSkillsDir)
@@ -189,4 +256,11 @@ export async function runCodexInitial(options = {}) {
   logger.info(`agents skills: 覆盖复制 ${copyStats.fileCount} 个文件 -> ${agentsSkillsDir}`)
   logger.info(`claude skills: 已创建 ${skillNames.length} 个软链接 -> ${claudeSkillsDir}`)
   logger.info(`codex skills: 已清理 ${skillNames.length} 个包内托管 skill 的旧副本 -> ${codexSkillsDir}`)
+  logger.info(
+    `已删除 skill 清理: agents ${purgeAgents.purged} / claude ${purgeClaude.purged} / codex ${purgeCodex.purged}`,
+  )
+  const purgeFailed = purgeClaude.failed + purgeAgents.failed + purgeCodex.failed
+  if (purgeFailed > 0) {
+    logger.warn(`已删除 skill 清理: ${purgeFailed} 个目标清理失败（已跳过，详见上方告警）`)
+  }
 }

package/package.json

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

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

@@ -0,0 +1,98 @@
+---
+name: backend-audit-fixer
+description: 必须显式调用才触发
+---
+
+# 后端规范审计与修复（伞 skill）
+
+## 概览
+
+6 个后端审计维度的统一入口。规则太多，**一维度一 subagent，每次只跑一个**：用户每次选一个维度，派一个 subagent 只载那份 reference、只跑那个脚本，回来出该维度报告，再询问是否继续下一个。**不并行扇出、不一次跑全部。**
+
+默认只审计出报告；用户明确说"修复/直接改"才进落代码阶段。
+
+## 维度表
+
+| 维度 | reference | 脚本 | 规则来源 |
+|------|-----------|------|---------|
+| backend-layering | references/backend-layering.md | 无（纯 rg） | conventions §4/§5/§6 |
+| e2e | references/e2e.md | scripts/e2e_audit.py | ruler/e2e-audit.md |
+| env-accessor | references/env-accessor.md | scripts/env_accessor_audit.py | conventions §2 |
+| error-handling | references/error-handling.md | scripts/error_handling_audit.py | conventions §9 |
+| naming | references/naming.md | scripts/naming_audit.py（需先拼 config） | conventions §10 |
+| pagination-dto | references/pagination-dto.md | scripts/pagination_dto_audit.py | conventions §12 |
+
+## 执行流程
+
+### Step 1：询问要跑哪个维度
+
+**每次只跑一个维度。** 进入 skill 后：
+
+- 用户已点名某维度（"检查命名"/"分页规范"）→ 直接跑该维度，跳到 Step 2。
+- 用户说"全量审计/扫一遍/检查合规"或没点名 → **用纯文本列出下面 6 个维度的编号菜单**，让用户回复编号或维度名再继续。别默认全跑、别并行。
+
+> ⚠️ 不要用 AskUserQuestion 列维度：它每题最多 4 个选项，6 个维度会被截断。必须用文本菜单。
+
+```
+请选择要审计的维度（每次只跑一个，回复编号或名字）：
+1. backend-layering  — 三层架构/事务/Repository 越层（conventions §4/§5/§6）
+2. e2e               — E2E 中文标题/手工 JWT/请求 helper/fixture 复用（ruler/e2e-audit.md）
+3. env-accessor      — 业务代码直读 process.env（conventions §2）
+4. error-handling    — 裸 BadRequestException/无 code HttpException（conventions §9）
+5. naming            — 文件/文件夹命名规范（conventions §10）
+6. pagination-dto    — 分页 DTO 未继承基类/手工拼装分页返回（conventions §12）
+```
+
+### Step 2：派 1 个 subagent 跑选中的维度
+
+只为这一个维度派一个 subagent。prompt 模板：
+
+```
+你负责后端审计的「<维度名>」维度。
+1. 只读 ~/.claude/skills/backend-audit-fixer/references/<维度>.md
+2. 按其中说明运行该维度的脚本/命令（workspace=<绝对路径>）
+3. 不要读其他维度的 reference，不要跑其他维度的脚本
+4. 默认只审计，除非主任务明确要求修复
+5. 严格按 reference 末尾的 findings JSON 契约返回结果（把脚本原始输出归一化成该契约）
+```
+
+关键约定：
+- 脚本路径统一 `SKILL_HOME="${SKILL_HOME:-$HOME/.claude/skills}"` → `$SKILL_HOME/backend-audit-fixer/scripts/<name>.py`。
+- naming 维度特殊：subagent 要先分析项目拼 JSON config 再喂脚本（见 references/naming.md）。
+- backend-layering 无脚本：subagent 跑 rg + 读代码判定。
+
+### Step 3：出该维度报告
+
+subagent 把脚本原始输出**归一化**成自己 reference 末尾的 findings 契约返回（脚本原始 JSON 顶层结构各异，契约是统一汇报格式，非脚本原样输出）。主 agent 据此出该维度报告：
+
+```
+## <维度> 审计报告
+- 基础设施：...
+- 命中数：N
+- 规则分布：...
+
+### 详细列表
+（展开 violations，标注脚本结果 vs 源码复核）
+```
+
+区分清楚：脚本命中 vs 已抽样复核；src vs e2e（error-handling）；疑似误报标"脚本规则限制"。
+
+### Step 4：询问下一步
+
+出完报告后，用 AskUserQuestion 问用户：
+
+- 修复本维度（仅用户明确要求才落代码）
+- 跑下一个维度（回 Step 1 再选一个）
+- 结束
+
+**不要出完一个维度就自动跑下一个。** 每个维度之间都要停下来等用户决定。
+
+### 修复（仅用户明确要求）
+
+按维度修复，照该维度 reference 的修复策略改码。修复后该维度复扫确认归零，再跑项目验证命令（`dx lint` / `dx build` / 受影响测试）。作者 pass 改码、复扫 pass 验证分两 lane，别自审自批。
+
+## 注意
+
+- **每次只跑一个维度**，维度之间用 AskUserQuestion 停顿，不并行、不自动连跑。
+- 各 reference 自包含（触发/命令/规则/修复/排除/findings 契约），subagent 不需要回看本 SKILL.md。
+- 旧的 6 个独立 skill（*-audit-fixer）过渡期并存；新工作走本伞 skill。

package/skills/backend-audit-fixer/references/backend-layering.md

@@ -0,0 +1,103 @@
+# 维度：后端三层架构与事务规范（backend-layering）
+
+无脚本维度。subagent 跑 rg + 读命中代码判定。规则来源：`ruler/conventions.md` §4 NestJS/Prisma + §5/§6 事务规范。
+
+默认只输出审计结果与修复建议；用户明确要求时才自动修复。
+
+## 检查项
+
+### 分层架构
+
+| 编号 | 违规类型 | 说明 |
+|------|----------|------|
+| L1 | Service 直接访问数据库 | Service 注入 `PrismaService` 并调用 `this.prisma.*` |
+| L2 | Service 伪装为 Repository | Service 文件含 `getClient()` / `txHost.tx` 模式，实质是 Repository |
+| L3 | Service 死依赖 | Service 注入 `PrismaService` 但从未使用 |
+| L4 | Controller 跨层调用 | Controller 直接注入 Repository |
+
+### 事务规范
+
+| 编号 | 违规类型 | 说明 |
+|------|----------|------|
+| T1 | afterCommit 未被排空 | Controller 用 `@Transactional()` 但调用链中存在 `txEvents.afterCommit()` 回调（应改用 `@TransactionalWithAfterCommit()`） |
+| T2 | Service 违规传播类型 | Service 使用 `Propagation.Required` / `RequiresNew` / `Nested`（禁止 Service 自行创建事务） |
+| T3 | 直接 `prisma.$transaction()` | 绕过 `TransactionHost` 抽象 |
+| T4 | SSE/流式端点加事务装饰器 | `@Sse()` 或流式返回方法上有事务装饰器（会导致 afterCommit 提前排空） |
+| T5 | 非 HTTP 场景事务模式错误 | Subscriber/Scheduler 用 `@Transactional()` 而非 `txHost.withTransaction()` / `txEvents.withAfterCommit()` |
+| T6 | 非 HTTP 场景缺少 CLS 作用域 | Scheduler 调 `txHost.withTransaction()` 前未用 `cls.run()` 创建 CLS 作用域 |
+
+## 审计命令（并行执行）
+
+```bash
+# L1+L2+L3：Service 注入 PrismaService
+rg "PrismaService" apps/backend/src/modules --glob '*.service.ts' -l
+# L2：Service 含 Repository 模式
+rg "getClient|txHost\.tx" apps/backend/src/modules --glob '*.service.ts' -l
+# L4：Controller 注入 Repository
+rg "Repository" apps/backend/src/modules --glob '*.controller.ts' -l
+# T1：只用 @Transactional() 的 Controller 方法
+rg "@Transactional\(\)" apps/backend/src/modules --glob '*.controller.ts' -l
+# T2：Service 违规传播类型
+rg "Propagation\.(Required|RequiresNew|Nested)" apps/backend/src/modules --glob '*.service.ts' -l
+# T3：直接 prisma.$transaction()
+rg "prisma\.\$transaction" apps/backend/src/modules -l
+# T4：SSE 端点
+rg "@Sse\(\)" apps/backend/src/modules --glob '*.controller.ts' -l
+# T5：Subscriber/Scheduler 误用 @Transactional
+rg "@Transactional" apps/backend/src/modules --glob '*.subscriber.ts' --glob '*.task.ts' --glob '*.scheduler*.ts' -l
+# T6：Scheduler 用 txHost.withTransaction 但未包 cls.run
+rg "txHost\.withTransaction" apps/backend/src/modules --glob '*.scheduler*.ts' --glob '*.task.ts' -l
+```
+
+## 判定流程
+
+1. 跑审计命令收集命中文件。
+2. 分层：读构造函数+使用处判定：
+   - 注入 `PrismaService` 且有 `this.prisma.*` → **L1**
+   - 注入 `PrismaService`/`txHost` 且有 `getClient()` → **L2**
+   - 注入 `PrismaService` 但无任何 `this.prisma.*` → **L3**
+   - Controller import/注入 Repository → **L4**
+3. 事务：
+   - T1：对只用 `@Transactional()` 的 Controller，追踪其调用的 Service 方法是否存在 `txEvents.afterCommit()`
+   - T2/T3/T5：直接匹配即违规
+   - T4：对 `@Sse()` 方法查同方法上是否有事务装饰器
+   - T6：查 `txHost.withTransaction()` 是否在 `cls.run()` 回调内部
+4. 输出报告（按模块分组，标违规类型+行号）。
+
+## 修复策略
+
+- **L1**：DB 查询逻辑提取到 Repository，Service 改注入 Repository。
+- **L2**：文件重命名 `*.repository.ts`，类名 `*Repository`，更新所有引用与 Module providers。
+- **L3**：移除构造函数 `PrismaService` 注入及 import，跑 lint 确认无残留。
+- **L4**：Repository 调用下沉到 Service，Controller 改调 Service。
+- **T1**：`@Transactional()` → `@TransactionalWithAfterCommit()`（或确认无 afterCommit 则不改）。
+- **T2**：改 `Propagation.Mandatory` 或 `Supports`，事务边界上移到 Controller。
+- **T3**：改 `txHost.withTransaction()` 或由 Controller `@Transactional()` 声明边界。
+- **T4**：移除装饰器；如需事务在流式逻辑内用 `cls.run()` + `txHost.withTransaction()` 局部处理。
+- **T5**：Subscriber → `txEvents.withAfterCommit()`；Scheduler/Task → `cls.run()` + `txHost.withTransaction()`。
+- **T6**：外层包 `cls.run()`：
+  ```typescript
+  await this.cls.run(async () => {
+    await this.txHost.withTransaction(async () => { /* ... */ })
+  })
+  ```
+
+## 排除项
+
+- `*.repository.ts` 使用 `PrismaService` / `getClient()` / `txHost`（Repository 正常职责）
+- `prisma/` 基础设施文件（`prisma.service.ts` 等）
+- `common/` 事务基础设施（`TransactionEventsService`、`AfterCommitInterceptor` 等）
+- `*.spec.ts` / `e2e/` 测试文件
+- Subscriber/Scheduler 中通过 `txHost.withTransaction()` 管理事务（正确模式）
+
+## 返回给主 agent 的 findings
+
+```json
+{
+  "dimension": "backend-layering",
+  "infra_status": "n/a",
+  "total": 0,
+  "by_rule": {"L1":0,"L2":0,"L3":0,"L4":0,"T1":0,"T2":0,"T3":0,"T4":0,"T5":0,"T6":0},
+  "violations": [{"file":"","rule":"L1","line":0,"note":""}]
+}
+```

package/skills/backend-audit-fixer/references/e2e.md

@@ -0,0 +1,60 @@
+# 维度：E2E 测试可维护性（e2e）
+
+脚本：`scripts/e2e_audit.py`。规则来源：`ruler/e2e-audit.md`。
+
+默认只检测+插 TODO 注释，不动业务逻辑；自动修复仅对中文测试名做真实替换。
+
+## 触发场景
+
+- 检查 `apps/backend/e2e/**/*.e2e-spec.ts` 用例是否符合英文命名。
+- 识别直接操作 Prisma、手工 JWT、手工 API URL、手工请求实现，区分哪些改全局 fixture、哪些抽本地 helper。
+
+## 运行
+
+```bash
+SKILL_HOME="${SKILL_HOME:-$HOME/.claude/skills}"
+python "$SKILL_HOME/backend-audit-fixer/scripts/e2e_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo \
+  --output-json /tmp/audit-e2e.json
+```
+
+路径参数（全部可覆盖，禁止硬编码）：
+- `--workspace`：代码根目录，默认当前目录。
+- `--e2e-glob`：扫描模式，默认 `apps/backend/e2e/**/*.e2e-spec.ts`。
+- `--fixtures`：fixtures 路径，默认 `${workspace}/apps/backend/e2e/fixtures/fixtures.ts`。
+
+## 检查规则
+
+- `e2e-chinese`：`describe/it/test/context` 名称含中文字符。
+- `e2e-fixtures`：`prisma.user.*`、`prisma.userCredential.*`、`jwtService.sign/jwt.sign`、未用 `buildApiUrl()` 的 API URL 片段、未用 `createAuthRequest/createAdminAuthRequest/createPublicRequest` 的手工请求。
+- `e2e-local-helper`：其他 `prisma.*.create*` / `upsert` 重复实现，默认只建议当前文件内抽本地 helper，不上收全局 fixtures。
+
+## 修复策略
+
+1. 中文测试名：先翻译英文。可提供翻译映射后 `--apply`：
+   ```bash
+   python "$SKILL_HOME/backend-audit-fixer/scripts/e2e_audit.py" \
+     --workspace /Users/a1/work/ai-monorepo \
+     --translation-map /tmp/name-map.json --apply
+   ```
+   翻译三选一：`--translation-map`（JSON `{"中文":"English"}`，推荐）/ `--translate-service openai`（需 `OPENAI_API_KEY`）/ 不提供（仅输出不改写）。
+2. fixture 重复实现：自动加注释+替换建议，保留原逻辑。仅 `user`/`userCredential` 为全局 fixture 候选，其余建议本地 helper。
+3. 复扫确认无回归。
+
+## 注意
+
+- 扫描不改业务逻辑，只检测+可控注释插入。
+- fixture/请求构造类问题仅插 TODO 注释，不宣称已重构。
+- 翻译服务仅处理测试名称。
+
+## 返回给主 agent 的 findings
+
+```json
+{
+  "dimension": "e2e",
+  "total": 0,
+  "by_rule": {"e2e-chinese":0,"e2e-fixtures":0,"e2e-local-helper":0},
+  "violations": [{"file":"","rule":"e2e-chinese","line":0,"note":""}]
+}
+```
+通过标准：`count: 0` / `by_type: {}`。

package/skills/backend-audit-fixer/references/env-accessor.md

@@ -0,0 +1,73 @@
+# 维度：环境变量访问（env-accessor）
+
+脚本：`scripts/env_accessor_audit.py`。规则来源：`ruler/conventions.md` §2 环境变量访问。
+
+先扫 `process.env` 直读点，再判断是否已有统一 env 基础设施；有则复用迁移，缺则先补最小基础设施再收口。
+
+## 运行
+
+```bash
+SKILL_HOME="${SKILL_HOME:-$HOME/.claude/skills}"
+python "$SKILL_HOME/backend-audit-fixer/scripts/env_accessor_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo \
+  --output-json /tmp/audit-env.json
+```
+
+`rg` 快速复核：
+
+```bash
+rg "process\.env" apps/backend/src apps/backend/e2e \
+  --glob '!*env.accessor.ts' --glob '!*env.service.ts'
+```
+
+## 执行流程
+
+1. 扫 `apps/backend/src` 与 `apps/backend/e2e` 的 `process.env`。
+2. 仅排除真正封装文件：`env.accessor.ts`、`env.service.ts`。**不排除** `apps/backend/src/config/**`（`registerAs` 配置层也纳入审计）。
+3. 识别基础设施状态：是否存在 `createEnvAccessor` / `defaultEnvAccessor` / `EnvService` / `EnvModule` / `registerAs` 经统一入口读取。
+4. 按场景为每个直读点选迁移方式，不机械替换。
+5. 修复后复扫 + 补跑最小验证。
+
+## 修复准则
+
+- **配置层与 `registerAs`**：优先 `defaultEnvAccessor`；必须显式传环境对象时用 `createEnvAccessor(process.env)`；不再裸读。
+  ```typescript
+  import { registerAs } from '@nestjs/config'
+  import { defaultEnvAccessor } from '@/common/env/env.accessor'
+  const env = defaultEnvAccessor
+  export const redisConfig = registerAs('redis', () => ({
+    host: env.str('REDIS_HOST', 'localhost'),
+  }))
+  ```
+- **运行期服务/控制器/提供者**：注入 `EnvService`，用 `getString/getInt/getBoolean/isProd/isE2E` 等 typed getter；模块未暴露 `EnvModule` 先补依赖。
+- **独立脚本/CLI**：dotenv 装载后显式 `const env = createEnvAccessor(process.env)`。
+- **必须读原始值**：用 `EnvService.getAccessor().raw(key)` 或 accessor 的 `raw(key)`，并注释说明为何 typed getter 不适用。
+
+## 缺失基础设施时的补齐顺序
+
+见 [bootstrap-env-foundation.md](./bootstrap-env-foundation.md)。顺序：
+1. `env.accessor.ts`（`createEnvAccessor`/`defaultEnvAccessor`，支持 `str/bool/int/num/raw/appEnv/snapshot`）
+2. `env.service.ts`（包 `ConfigService` + typed getter）
+3. `env.module.ts`（暴露 `EnvService`）
+4. 配置层迁 `registerAs + defaultEnvAccessor`
+5. 运行期服务迁 `EnvService`
+6. 复扫剩余直读点
+
+优先复用现有命名/目录/模块结构。
+
+## 例外
+
+- `env.accessor.ts`/`env.service.ts` 本身允许访问 `process.env`。
+- 负责 dotenv 装载、环境注入、测试临时覆写的底层入口可保留少量受控访问。
+- 测试里显式设值视为受控例外，但优先复用公共 fixture/helper。
+
+## 返回给主 agent 的 findings
+
+```json
+{
+  "dimension": "env-accessor",
+  "infra_status": {"createEnvAccessor":false,"defaultEnvAccessor":false,"EnvService":false,"EnvModule":false},
+  "total": 0,
+  "violations": [{"file":"","line":0,"suggestion":""}]
+}
+```

package/skills/backend-audit-fixer/references/error-handling.md

@@ -0,0 +1,77 @@
+# 维度：错误处理（error-handling）
+
+脚本：`scripts/error_handling_audit.py`。规则来源：`ruler/conventions.md` §9 统一错误码。
+
+先判断是否已具备统一错误处理基础设施，再扫业务代码是否绕过 `DomainException` / `ErrorCode`。默认只输出审计+建议，用户明确要求才自动修复。
+
+## 扫描范围
+
+脚本不预设路径，需 `--src-dir` / `--e2e-dir` 显式传入。以下始终排除：
+单测 `*.spec.ts`/`*.test.ts`/`*.e2e-spec.ts`；测试辅助 `*.mock.ts`/`*.stub.ts`/`*.fixture.ts`/`fixtures/`/`test-utils/`/`testing/`/`__tests__/`；基础设施 `*/filters/`/`prisma/`/`scripts/`；异常定义 `*.exception.ts`；入口 `main.ts`。
+
+仅用户**明确要求**评估测试债务时才传 `--e2e-dir` + `--scope e2e`。
+
+## 运行
+
+步骤 0 先探索项目（识别生产代码与测试目录，monorepo 多服务各传一个 `--src-dir`）。
+
+```bash
+SKILL_HOME="${SKILL_HOME:-$HOME/.claude/skills}"
+python "$SKILL_HOME/backend-audit-fixer/scripts/error_handling_audit.py" \
+  --workspace "$PWD" \
+  --src-dir apps/backend/src \
+  --output-json /tmp/audit-error.json
+```
+
+仅在用户要求时审计测试代码：`--e2e-dir apps/backend/e2e --scope e2e`。
+
+## 识别四类问题
+
+1. 直接实例化 Nest 标准异常（`BadRequestException`、`HttpException` 等）。
+2. `throw new Error(...)` 或 `Promise.reject(new Error(...))`。
+3. 直接 `new DomainException(...)` 但 payload 未显式带 `code`。
+4. `DomainException` 直接返回中文 message。
+
+## 合法 raw-error 判定（强制复核，别原样转发脚本结果）
+
+脚本 `raw-error` 规则误报率极高（实测一次 18 命中，复核后 17 个是误报）。**每条 `raw-error` 命中必须打开源码定位，按下表判定 `real` 还是 `false-positive`，禁止把脚本命中直接当 violation 报、禁止给误报写"建议改 XXX"。** 下列模式属合法 raw-error，不算违规：
+
+| 合法模式 | 识别特征 | 实例 |
+|---------|---------|------|
+| 本地 catch 控制流 | `try` 内 `throw new Error` 紧接着被**同函数本地 `catch`** 捕获（吞掉 / 返回 null / 重试下一候选），不向 HTTP 上抛 | metadata 解析校验后 `catch { return null }`；候选循环 `lastError` 重试 |
+| 内部不变量断言 | programmer invariant / 生命周期断言，触发即代码 bug，非用户可达业务错误 | `called before onModuleInit`、`Character missing in RequestContext`、`rows must match delete window`、启动期常量自检 |
+| 运维脚本/非 HTTP 路径 | backfill、dry-run、CLI、Cron 等非 HTTP 业务请求路径的参数/SOP 校验 | `backfill window exceeds max`、`refuse to overwrite missing row` |
+| 控制流信号 | `Promise.race` 超时、迭代终止等把 Error 当信号用，非异常上抛 | `setTimeout(() => reject(new Error('timeout')))` |
+
+真违规特征：**走 HTTP 业务请求路径（Controller→Service→Repository）、资源不存在 / 参数非法 / 状态冲突等用户可达错误、错误会冒泡到响应**。这类才报 `real` 并建议领域异常。
+
+`domain-exception-missing-code` 同样要复核：若 `code` 是变量（如 `classify400()` 返回值）赋给 payload，脚本静态匹配不到但实际带了 code，属误报。
+
+## 修复准则（优先级固定）
+
+1. **优先复用现有领域异常**：模块 `exceptions/` 已有语义匹配类直接复用。
+2. **缺少则新增领域异常类**：在模块 `exceptions/` 下继承 `DomainException`，构造函数显式指定 `ErrorCode`，上下文放 `args`（不写死文案到 message），补最小单测。
+3. **临时直接用 DomainException**：仅在未抽专用类但必须推进时；payload 必含 `code`，`args` 保留排障上下文。
+4. **基础设施缺失判断**：无 `DomainException`/`ErrorCode` → 先补基础设施，别发散新增几十个本地异常；有 `DomainException` 无统一 `ErrorCode` → 先统一错误码源；有类有码缺结构化输出链路 → 先补过滤器/输出映射，保证 `code`/`args`/`requestId` 稳定透出。
+
+详见 [error-handling-standard.md](./error-handling-standard.md) 与 [error-handling-foundation-bootstrap.md](./error-handling-foundation-bootstrap.md)。
+
+## 注意
+
+- 明确区分 `src` 与 `e2e` 命中数量，别让测试噪音淹没生产风险。
+- 脚本结果与实际不一致时，抽样打开命中文件复核，别当绝对真相。
+- **每条命中必带 `verdict`**：`real`（已开源码确认走 HTTP 业务路径、用户可达错误）或 `false-positive`（命中"合法 raw-error 判定"表任一模式，`note` 写明哪类）。未开源码确认不准报 `real`。
+
+## 返回给主 agent 的 findings
+
+`total` 是脚本原始命中数；`real_total` 是复核后真违规数。两者都要给，让主 agent 看到误报比例。
+
+```json
+{
+  "dimension": "error-handling",
+  "infra_status": {"DomainException":false,"ErrorCode":false,"filter":false},
+  "src": {"total":0,"real_total":0,"by_rule":{}},
+  "e2e": {"total":0,"real_total":0,"by_rule":{}},
+  "violations": [{"file":"","scope":"src","rule":"","line":0,"verdict":"real|false-positive","note":"real 写建议领域异常；false-positive 写命中哪类合法模式"}]
+}
+```

package/skills/{naming-audit-fixer/references/fix-guide.md → backend-audit-fixer/references/naming-fix-guide.md}

@@ -78,14 +78,19 @@ dx build admin --dev
 | Hook .ts | camelCase | `useChat.ts` |
 | 路由文件 | 小写 | `page.tsx`, `layout.tsx` |
 | 目录 | kebab-case | `character/`（单数） |
-| ui/ | kebab-case | `button.tsx` |
+| ui/ | kebab-case（shadcn 原生，**豁免 PascalCase**） | `button.tsx` |
+| 点号描述符 | 保留，仅 base 段 kebab | `announcement-popup.storage.ts` ✅ |
 
-### Vite + React
+### Vite + React（admin-front）
 
-与 Next.js 相同，但无路由文件约束。
+组件/工具命名同 Next.js。但 **`pages/**` 走 vite-plugin-pages 文件路由**：文件名即 URL，`.tsx` 改名属破坏性，默认不动（见高风险注意）。
 
 ## 高风险操作注意
 
+- **vite-plugin-pages 文件路由（admin-front 最高危）**：`pages/**` 文件名即 URL。改名前 `rg "vite-plugin-pages|react-pages"`；命中则 `pages/**/*.tsx` 默认不改（改名 = 改 URL，且常无 import 纯靠路由存活，改完直接失联）。确需改：同步改 Pages `exclude` 或确认 URL 可变更并手测路由可达。
+- **点号是描述符不是违规**：§10 认可 `.storage`/`.toggle`/`.core` 等描述符点号。改名**只动 base 段大小写**，保留点号（`CharactersPane.sub-normalize.ts`→`characters-pane.sub-normalize.ts`，不要拍平成 `characters-pane-sub-normalize.ts`）。
+- **macOS 大小写不敏感**：`git mv MessageCenter message-center` 仅改大小写可能失败，需中间名过渡（`MessageCenter`→`message-center-tmp`→`message-center`）。
+- **深引用 vs barrel**：改目录名前先 `rg` 确认外部走深路径还是 barrel——别假设走 index.ts，本仓实测外部全是 `Dir/Component` 深引用、barrel 零外部消费。
 - **barrel export (index.ts)**：重命名后检查是否有 `export * from './old-name'`
 - **动态 import**：`import()` 表达式中的路径也需要更新
 - **tsconfig paths**：如果 tsconfig 中配置了路径别名指向具体文件，也需更新