@ranger1/dx 0.1.85 → 0.1.87

package/README.md

@@ -199,11 +199,13 @@ dx deploy front --staging
 dx deploy backend --prod
 dx lint
 dx test e2e backend apps/backend/e2e/auth
+dx test e2e quantify apps/quantify/e2e/health/health.e2e-spec.ts
 ```
 
 命令约束摘要：
 
-- `dx test e2e backend` 必须提供文件或目录路径，禁止无路径全量执行
+- 对声明了 `requiresPath: true` 的 E2E target，`dx test e2e <target>` 必须提供文件或目录路径，禁止无路径或 `all` 全量执行
+- `dx test e2e all` 不受支持，必须显式指定 target 和路径
 - `dx db migrate` 仅允许在 `--dev` 环境创建迁移；非开发环境请使用 `dx db deploy`
 - `dx start` 未指定服务时默认是开发套件，仅允许 `--dev`
 - `dx start` 下的单层目标（如 `stagewise-front`）默认仅支持 `--dev`
@@ -343,6 +345,14 @@ dx deploy backend --prod --skip-migration
           "installCommand": "pnpm install --prod --no-frozen-lockfile --ignore-workspace",
           "prismaGenerate": true,
           "prismaMigrateDeploy": true
+        },
+        "verify": {
+          "healthCheck": {
+            "url": "http://127.0.0.1:3005/api/v1/health",
+            "timeoutSeconds": 10,
+            "maxWaitSeconds": 24,
+            "retryIntervalSeconds": 2
+          }
         }
       }
     }
@@ -365,6 +375,56 @@ dx deploy backend --prod --skip-migration
 - 所有本地路径字段都会被解析为相对项目根目录，并且必须留在项目根目录内；例如 `build.distDir`、`runtime.prismaSchemaDir`、`artifact.outputDir` 不能通过 `../` 逃逸到仓库外。
 - `remote.baseDir` 必须是绝对路径，并且只能包含 `/`、字母、数字、`.`、`_`、`-`；不要使用空格或 shell 特殊字符。
 
+部署后验活与成功摘要：
+
+- `dx deploy backend` 在远端启动完成后，会继续校验 `current` 软链接是否切到本次 release。
+- 如果 `startup.mode` 是 `pm2`，还会校验 PM2 进程是否存在，以及 PM2 中的 `APP_ENV` / `NODE_ENV` 是否与部署环境一致。
+- 如果配置了 `verify.healthCheck`，dx 会在远端对健康检查地址做重试探测；适合处理不同项目启动时间不一致的问题。
+- 成功后，dx 会在本地 CLI 回显一段摘要，默认包含：
+  - release 版本名
+  - current 当前指向的 release 目录
+  - service/status
+  - APP_ENV / NODE_ENV
+  - health 地址
+
+示例成功输出：
+
+```text
+✅ 后端部署成功: backend-v0.0.24-20260313-174425
+🚀 [deploy-summary] current=/opt/work/noveai/releases/backend-v0.0.24-20260313-174425
+🚀 [deploy-summary] service=noveai-backend status=online
+🚀 [deploy-summary] APP_ENV=staging NODE_ENV=production
+🚀 [deploy-summary] health=http://127.0.0.1:3005/api/v1/health
+```
+
+`verify.healthCheck` 配置说明：
+
+- `url`：健康检查地址。未配置时，dx 会跳过 health check，但仍会执行 `current` / PM2 验活。
+- `timeoutSeconds`：单次 `curl` 请求超时。
+- `maxWaitSeconds`：从启动后开始，health check 最长等待多久；超过这个时间仍未成功则失败。
+- `retryIntervalSeconds`：两次 health check 之间的等待间隔。
+
+推荐配置：
+
+```json
+{
+  "verify": {
+    "healthCheck": {
+      "url": "http://127.0.0.1:3005/api/v1/health",
+      "timeoutSeconds": 10,
+      "maxWaitSeconds": 24,
+      "retryIntervalSeconds": 2
+    }
+  }
+}
+```
+
+说明：
+
+- `timeoutSeconds` 控制“单次请求能等多久”。
+- `maxWaitSeconds` 控制“服务从启动到 ready 最多允许多久”。
+- `retryIntervalSeconds` 越小，ready 后越快通过；越大，请求频率越低。
+
 SSH 认证说明：
 
 - `dx deploy backend` 当前直接调用系统 `ssh` / `scp`，不会单独解析 `sshKey`、`identityFile` 之类的 dx 配置项。

package/codex/skills/e2e-audit-fixer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: e2e-audit-fixer
+description: 对 backend 的 E2E 用例进行中文名称、通用 fixture 重复实现与测试请求构建规范检查，并按可配置路径输出修复建议与可选自动修复。适用于需要审计或修复 E2E 测试中的中文用例名、手工请求构造、手工 JWT、以及本应复用通用测试基建的重复实现。
+---
+
+# E2E 测试可维护性检查与修复
+
+## 触发场景
+
+- 需要检查 `apps/backend/e2e/**/*.e2e-spec.ts` 的 E2E 用例是否符合英文命名规范。
+- 需要识别直接操作 Prisma、手工 JWT、手工 API URL、手工请求实现，并区分哪些适合改用全局通用 fixture，哪些更适合抽成本地 helper。
+- 需要一次性生成问题清单并按规则应用可控修复。
+
+## 准备
+
+执行前确认项目有可读权限，并准备以下路径参数（全部可覆盖，避免硬编码）：
+
+1. `--workspace`：代码根目录，默认当前目录。
+2. `--e2e-glob`：扫描文件模式，默认 `apps/backend/e2e/**/*.e2e-spec.ts`。
+3. `--fixtures`：fixtures 文件路径，默认 `${workspace}/apps/backend/e2e/fixtures/fixtures.ts`。
+
+## 执行流程
+
+1. 先扫描问题：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+python "$CODEX_HOME/skills/e2e-audit-fixer/scripts/e2e_e2e_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo
+```
+
+2. 生成输出 JSON 用于复核：
+
+```bash
+python "$CODEX_HOME/skills/e2e-audit-fixer/scripts/e2e_e2e_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo \
+  --output-json /tmp/e2e-audit.json
+```
+
+3. 按修复策略应用：
+
+   1. 中文测试名：先翻译为英文。可直接提供翻译映射：
+
+   ```bash
+   python "$CODEX_HOME/skills/e2e-audit-fixer/scripts/e2e_e2e_audit.py" \
+     --workspace /Users/a1/work/ai-monorepo \
+     --translation-map /tmp/name-map.json \
+     --apply
+   ```
+
+   2. fixture 重复实现：自动加注释提示并给出替换建议，保留原有逻辑不变。仅 `user` / `userCredential` 作为全局通用 fixture 候选，其余默认建议抽成本地 helper。
+
+4. 必要时清理：对比扫描结果再次运行，确保无回归。
+
+## 检查规则（脚本输出）
+
+- `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. `--translation-map`：JSON 映射文件 `{ "中文原文": "English text" }`（推荐，稳定、可审计）。
+2. `--translate-service openai`：提供 `OPENAI_API_KEY` 后自动调用 OpenAI 批量翻译。
+3. 不提供翻译参数：仅输出中文字符串与建议，不改写文件。
+
+## 注意
+
+- 扫描不改变业务逻辑，只做问题检测与可控注释插入。
+- 自动修复默认只对中文测试名称做真实替换。
+- `user` / `userCredential` 以外的重复造数默认视为“本地 helper 候选”，不默认建议进入全局 fixtures。
+- fixture 与请求构造类问题仅插入 TODO 注释，不宣称已完成重构。
+- 翻译服务仅处理测试名称，不处理其他文本。
+- 扫描路径来源全部来自参数，不会固定死为 `apps/backend/e2e/**/*.e2e-spec.ts`。

package/codex/skills/e2e-audit-fixer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "E2E Audit Fixer"
+  short_description: "扫描 E2E 测试中文名称、手工请求与重复实现，并输出可控修复建议"
+  default_prompt: "使用 $e2e-audit-fixer 对 E2E 测试进行 e2e-chinese 与 e2e-fixtures 检查，并按修复建议输出可执行改动。"

package/codex/skills/e2e-audit-fixer/scripts/e2e_e2e_audit.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python3
+"""
+E2E 检查与修复脚本（中文测试名 + fixtures 重复实现模式）
+默认扫描 backend e2e 用例文件，可通过参数传入扫描路径与 fixtures 路径。
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional
+
+
+CHINESE = re.compile(r"[\u4e00-\u9fff]")
+TITLE_PATTERN = re.compile(
+    r"\b(?P<kind>describe|it|test|context)\s*\(\s*(?P<quote>[`'\"])(?P<name>(?:(?!(?P=quote)).)*?[\u4e00-\u9fff].*?)(?P=quote)",
+    re.IGNORECASE,
+)
+PRISMA_PATTERN = re.compile(r"\bprisma\.(?P<model>\w+)\.(?P<method>create|createMany|createManyAndReturn|upsert)\s*\(")
+JWT_PATTERN = re.compile(r"\b(?:jwtService|jwt)\.sign\s*\(")
+AUTH_REQUEST_PATTERN = re.compile(r"\b(?:request|supertest)\s*\(\s*app\.getHttpServer\(\)\s*\)")
+API_URL_PATTERN = re.compile(r"[`'\"]([^`'\"]*/api/[^`'\"]*)[`'\"]")
+REQUEST_CALL_PATTERN = re.compile(r"\b(?:request|supertest|axios|fetch|got)\s*\(")
+MANUAL_REQUEST_PATTERN = re.compile(r"\.(?:get|post|put|patch|delete|head)\(\s*[`'\"]")
+TOP_LEVEL_HELPER_PATTERN = re.compile(
+    r"^\s*(?:export\s+)?(?:(?:async\s+)?function\s+(?P<fn>[A-Za-z_][A-Za-z0-9_]*)\s*\(|const\s+(?P<const>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{)"
+)
+TOP_LEVEL_HELPER_START_PATTERN = re.compile(
+    r"^\s*(?:export\s+)?const\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:async\s*)?\("
+)
+TOP_LEVEL_FUNCTION_START_PATTERN = re.compile(
+    r"^\s*(?:export\s+)?(?:async\s+)?function\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\b"
+)
+HELPER_NAME_PREFIXES = ("create", "ensure", "seed", "build", "find", "get", "reset", "wait", "pick")
+
+
+KNOWN_FIXTURE_TOOLS: Dict[str, str] = {
+    "user": "createUserRecord",
+    "usercredential": "createUserCredentialRecord",
+}
+
+ISSUE_TYPES = {
+    "e2e-chinese": "E2E 测试名称包含中文字符",
+    "prisma-create": "直接操作 prisma.create 族接口",
+    "e2e-local-helper": "重复造数更适合抽成本地 helper",
+    "jwt-sign": "手动创建 JWT Token",
+    "manual-api-url": "手工拼接 API URL（未使用 buildApiUrl）",
+    "manual-auth-request": "手工创建 HTTP 请求（未使用 createAuthRequest 系列）",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="E2E 规则扫描与可控修复")
+    parser.add_argument("--workspace", default=".", help="扫描根目录（默认当前目录）")
+    parser.add_argument(
+        "--e2e-glob",
+        default="apps/backend/e2e/**/*.e2e-spec.ts",
+        help="扫描 glob 模式，默认 apps/backend/e2e/**/*.e2e-spec.ts",
+    )
+    parser.add_argument(
+        "--fixtures",
+        default=None,
+        help="fixtures 文件路径（默认 workspace/apps/backend/e2e/fixtures/fixtures.ts）",
+    )
+    parser.add_argument("--output-json", default=None, help="导出结果路径（JSON）")
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="输出格式（默认 text）",
+    )
+    parser.add_argument("--apply", action="store_true", help="启用可控修复（中文名称替换、TODO 注入）")
+    parser.add_argument("--translation-map", default=None, help="中文->英文 JSON 映射文件路径")
+    parser.add_argument(
+        "--translate-service",
+        choices=["none", "openai"],
+        default="none",
+        help="无映射时可用 openai 进行批量翻译",
+    )
+    parser.add_argument("--openai-key", default=None, help="OPENAI API Key（默认读取环境变量 OPENAI_API_KEY）")
+    parser.add_argument(
+        "--openai-model",
+        default="gpt-4o-mini",
+        help="OpenAI Chat Completions model，默认 gpt-4o-mini",
+    )
+    parser.add_argument(
+        "--openai-endpoint",
+        default="https://api.openai.com/v1/chat/completions",
+        help="OpenAI 兼容端点",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="应用修复时仅预览")
+    return parser.parse_args()
+
+
+def load_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def write_text(path: Path, text: str, dry_run: bool) -> None:
+    if dry_run:
+        return
+    path.write_text(text, encoding="utf-8")
+
+
+def has_chinese(text: str) -> bool:
+    return CHINESE.search(text) is not None
+
+
+def parse_fixture_exports(path: Optional[Path]) -> List[str]:
+    if not path or not path.exists():
+        return []
+    text = load_text(path)
+    pattern = re.compile(r"\bexport\s+(?:async\s+)?(?:function|const)\s+([A-Za-z_][A-Za-z0-9_]*)")
+    return sorted(set(pattern.findall(text)))
+
+
+def build_issue(path: Path, line: int, kind: str, detail: str, suggestion: str, snippet: str = "") -> Dict:
+    return {
+        "path": str(path),
+        "line": line,
+        "type": kind,
+        "kind_cn": ISSUE_TYPES.get(kind, kind),
+        "detail": detail,
+        "suggestion": suggestion,
+        "snippet": snippet,
+    }
+
+
+def suggest_for_model(model: str, fixtures: List[str]) -> str:
+    key = model.replace("_", "").lower()
+    exact_match = KNOWN_FIXTURE_TOOLS.get(key)
+    if exact_match:
+        if exact_match in fixtures:
+            return f"建议替换为 {exact_match}()"
+        return f"建议在 fixtures.ts 新增并复用 {exact_match}()"
+    return "建议在当前测试文件内抽成本地 helper；不要默认上收为全局 fixture"
+
+
+def scan_file(path: Path, fixtures: List[str]) -> List[Dict]:
+    text = load_text(path)
+    lines = text.splitlines()
+    issues: List[Dict] = []
+    helper_lines = collect_local_helper_lines(lines)
+
+    for i, line in enumerate(lines, start=1):
+        for match in TITLE_PATTERN.finditer(line):
+            name = match.group("name")
+            if has_chinese(name):
+                issues.append(
+                    build_issue(
+                        path=path,
+                        line=i,
+                        kind="e2e-chinese",
+                        detail=f"检测到含中文标题: {name}",
+                        suggestion="将中文标题翻译为英文（如 should ...）。",
+                        snippet=match.group(0),
+                    )
+                )
+
+        for match in PRISMA_PATTERN.finditer(line):
+            if i in helper_lines:
+                continue
+            model = match.group("model")
+            suggestion = suggest_for_model(model, fixtures)
+            issue_type = "prisma-create" if model.replace("_", "").lower() in KNOWN_FIXTURE_TOOLS else "e2e-local-helper"
+            issues.append(
+                build_issue(
+                    path=path,
+                    line=i,
+                    kind=issue_type,
+                    detail=f"发现直接调用 prisma.{model}.create 族实现",
+                    suggestion=suggestion,
+                    snippet=line.strip(),
+                )
+            )
+
+        if JWT_PATTERN.search(line):
+            issues.append(
+                build_issue(
+                    path=path,
+                    line=i,
+                    kind="jwt-sign",
+                    detail="发现手工调用 jwt.sign",
+                    suggestion="建议使用 generateTestJwtToken(app, ...) 替代。",
+                    snippet=line.strip(),
+                )
+            )
+
+        if API_URL_PATTERN.search(line):
+            if ("buildApiUrl(" not in line) and (REQUEST_CALL_PATTERN.search(line) or MANUAL_REQUEST_PATTERN.search(line)):
+                issues.append(
+                    build_issue(
+                        path=path,
+                        line=i,
+                        kind="manual-api-url",
+                        detail="发现 /api/ 片段未经过 buildApiUrl",
+                        suggestion="建议使用 buildApiUrl(path) 统一拼接。",
+                        snippet=line.strip(),
+                    )
+                )
+
+        if "app.getHttpServer()" in line and REQUEST_CALL_PATTERN.search(line):
+            issues.append(
+                build_issue(
+                    path=path,
+                    line=i,
+                    kind="manual-auth-request",
+                    detail="发现 app.getHttpServer() 直接请求调用",
+                    suggestion="建议优先使用 createAuthRequest(app, ...)、createAdminAuthRequest(app, ...) 或 createPublicRequest(app)。",
+                    snippet=line.strip(),
+                )
+            )
+
+    return issues
+
+
+def collect_local_helper_lines(lines: List[str]) -> set[int]:
+    helper_lines: set[int] = set()
+    idx = 0
+    total = len(lines)
+
+    while idx < total:
+        line = lines[idx]
+        match = TOP_LEVEL_HELPER_PATTERN.match(line)
+        multiline_match = TOP_LEVEL_HELPER_START_PATTERN.match(line)
+        function_start_match = TOP_LEVEL_FUNCTION_START_PATTERN.match(line)
+        if not match:
+            if multiline_match:
+                name = multiline_match.group("name") or ""
+                if not name.startswith(HELPER_NAME_PREFIXES):
+                    idx += 1
+                    continue
+
+                probe = idx
+                arrow_line = line
+                while probe + 1 < total and "=>" not in arrow_line:
+                    probe += 1
+                    arrow_line = lines[probe]
+
+                if "=>" not in arrow_line:
+                    idx += 1
+                    continue
+
+                block_start = probe
+                end = probe + 1
+
+                if "{" not in arrow_line:
+                    while end <= total and not lines[end - 1].strip().endswith((")", "})", "})", ");", "),")):
+                        end += 1
+                    for lineno in range(idx + 1, min(end, total) + 1):
+                        helper_lines.add(lineno)
+                    idx = end
+                    continue
+
+                brace_depth = arrow_line.count("{") - arrow_line.count("}")
+                while end < total and brace_depth > 0:
+                    brace_depth += lines[end].count("{") - lines[end].count("}")
+                    end += 1
+
+                for lineno in range(idx + 1, min(end, total) + 1):
+                    helper_lines.add(lineno)
+                idx = end
+                continue
+            if function_start_match:
+                name = function_start_match.group("name") or ""
+                if not name.startswith(HELPER_NAME_PREFIXES):
+                    idx += 1
+                    continue
+
+                probe = idx
+                signature_line = line
+                while probe + 1 < total and "{" not in signature_line:
+                    probe += 1
+                    signature_line = lines[probe]
+
+                if "{" not in signature_line:
+                    idx += 1
+                    continue
+
+                brace_depth = signature_line.count("{") - signature_line.count("}")
+                end = probe + 1
+                while end < total and brace_depth > 0:
+                    brace_depth += lines[end].count("{") - lines[end].count("}")
+                    end += 1
+
+                for lineno in range(idx + 1, min(end, total) + 1):
+                    helper_lines.add(lineno)
+                idx = end
+                continue
+            idx += 1
+            continue
+
+        name = match.group("fn") or match.group("const") or ""
+        if not name.startswith(HELPER_NAME_PREFIXES):
+            idx += 1
+            continue
+
+        brace_depth = line.count("{") - line.count("}")
+        start = idx + 1
+        end = start
+        probe = idx
+
+        while probe + 1 < total and brace_depth > 0:
+            probe += 1
+            brace_depth += lines[probe].count("{") - lines[probe].count("}")
+            end = probe + 1
+
+        for lineno in range(start, end + 1):
+            helper_lines.add(lineno)
+
+        idx = probe + 1
+
+    return helper_lines
+
+
+def load_translation_map(path: Optional[str]) -> Dict[str, str]:
+    if not path:
+        return {}
+    map_path = Path(path)
+    if not map_path.exists():
+        return {}
+    data = json.loads(map_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): str(v) for k, v in data.items()}
+
+
+def translate_batch_openai(texts: Iterable[str], api_key: str, model: str, endpoint: str) -> Dict[str, str]:
+    items = list(dict.fromkeys([t for t in texts if t.strip()]))
+    if not items:
+        return {}
+
+    prompt = (
+        "You are a strict technical translator for test titles.\n"
+        "Translate each input string to concise English test-case style.\n"
+        "Only output JSON object: {\"translations\": {\"原文\": \"译文\", ...}}."
+    )
+    payload = {
+        "model": model,
+        "temperature": 0.2,
+        "messages": [
+            {"role": "system", "content": prompt},
+            {"role": "user", "content": json.dumps(items, ensure_ascii=False)},
+        ],
+    }
+
+    req = urllib.request.Request(
+        endpoint,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r:
+            data = json.loads(r.read().decode("utf-8"))
+        content = data["choices"][0]["message"]["content"]
+        parsed = json.loads(content)
+        return parsed.get("translations", {})
+    except (urllib.error.URLError, KeyError, ValueError):
+        return {}
+
+
+def infer_translation_map(issues: List[Dict], translation_map: Dict[str, str], use_openai: bool, args: argparse.Namespace) -> Dict[str, str]:
+    if translation_map:
+        return translation_map
+    if not use_openai:
+        return {}
+
+    need = sorted(
+        {
+            i["detail"].split(": ", 1)[1]
+            for i in issues
+            if i["type"] == "e2e-chinese" and ": " in i["detail"]
+        }
+    )
+    api_key = args.openai_key or os.environ.get("OPENAI_API_KEY")
+    if not api_key or not need:
+        return {}
+    remote = translate_batch_openai(need, api_key=api_key, model=args.openai_model, endpoint=args.openai_endpoint)
+    return remote
+
+
+def apply_fixes(path: Path, issues: List[Dict], translations: Dict[str, str], dry_run: bool) -> Dict[str, int]:
+    if not issues:
+        return {"changed": 0, "title_fixed": 0, "todo_injected": 0}
+
+    lines = path.read_text(encoding="utf-8").splitlines()
+    added = {"changed": 0, "title_fixed": 0, "todo_injected": 0}
+    issue_lines = sorted(issues, key=lambda i: i["line"], reverse=True)
+    for issue in issue_lines:
+        idx = issue["line"] - 1
+        if idx < 0 or idx >= len(lines):
+            continue
+        line = lines[idx]
+        if issue["type"] == "e2e-chinese" and "检测到含中文标题" in issue["detail"]:
+            name = issue["detail"].replace("检测到含中文标题: ", "")
+            target = translations.get(name)
+            if not target:
+                comment = f"{line}\n// TODO(e2e-chinese): 当前无翻译映射，后续替换为英文。"
+                if "e2e-chinese" not in lines[max(0, idx - 1)]:
+                    lines[idx] = comment
+                    added["changed"] += 1
+                    added["todo_injected"] += 1
+                continue
+            replaced = TITLE_PATTERN.sub(
+                lambda m: (
+                    f"{m.group('kind')}({m.group('quote')}{target}{m.group('quote')}"
+                    if m.group("name") == name
+                    else m.group(0)
+                ),
+                line,
+                count=1,
+            )
+            if replaced != line:
+                lines[idx] = replaced
+                added["changed"] += 1
+                added["title_fixed"] += 1
+            continue
+
+        if issue["type"] in {"prisma-create", "jwt-sign", "manual-api-url", "manual-auth-request"}:
+            prefix = " " * (len(line) - len(line.lstrip(" ")))
+            todo = f"{prefix}// TODO(e2e-fixtures): {issue['suggestion']}"
+            if idx > 0 and todo.strip() == lines[idx - 1].strip():
+                continue
+            lines.insert(idx, todo)
+            added["changed"] += 1
+            added["todo_injected"] += 1
+
+    if added["changed"] > 0:
+        write_text(path, "\n".join(lines) + "\n", dry_run)
+    return added
+
+
+def main() -> None:
+    args = parse_args()
+    workspace = Path(args.workspace).resolve()
+    fixtures_path = Path(args.fixtures or (workspace / "apps" / "backend" / "e2e" / "fixtures" / "fixtures.ts"))
+    fixture_exports = parse_fixture_exports(fixtures_path)
+
+    glob_pattern = str(workspace / args.e2e_glob)
+    files = sorted(glob.glob(glob_pattern, recursive=True))
+    if not files:
+        print("未发现匹配文件，请检查 workspace/e2e-glob 参数。")
+        return
+
+    total: List[Dict] = []
+    for item in files:
+        total.extend(scan_file(Path(item), fixture_exports))
+
+    total = sorted(total, key=lambda x: (x["path"], x["line"], x["type"]))
+    translation_map = load_translation_map(args.translation_map)
+    remote_translations = infer_translation_map(total, translation_map, args.translate_service == "openai", args)
+    if not translation_map:
+        translation_map = remote_translations
+
+    output = {
+        "summary": {
+            "count": len(total),
+            "by_type": {t: sum(1 for i in total if i["type"] == t) for t in sorted({i["type"] for i in total})},
+            "fixtures_file": str(fixtures_path),
+            "fixtures_exports": fixture_exports,
+        },
+        "issues": total,
+    }
+
+    if args.output_json:
+        Path(args.output_json).write_text(json.dumps(output, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    if args.format == "json":
+        if args.output_json:
+            print(f"已导出: {args.output_json}")
+        else:
+            print(json.dumps(output, ensure_ascii=False, indent=2))
+    else:
+        print(f"扫描根目录: {workspace}")
+        print(f"扫描范围: {args.e2e_glob}")
+        print(f"fixtures 文件: {fixtures_path}")
+        print(f"问题总数: {len(total)}")
+        for t in sorted({i["type"] for i in total}):
+            print(f"- {t}: {sum(1 for i in total if i['type'] == t)}")
+        print("")
+        for issue in total[:300]:
+            print(f"{issue['path']}:{issue['line']} [{issue['type']}]")
+            print(f"  {issue['detail']}")
+            print(f"  建议: {issue['suggestion']}")
+            if issue["snippet"]:
+                print(f"  片段: {issue['snippet']}")
+        if len(total) > 300:
+            print(f"... 省略其余 {len(total) - 300} 条，建议加参数 output-json 落盘复核")
+
+    if args.apply:
+        by_path: Dict[str, List[Dict]] = {}
+        for issue in total:
+            by_path.setdefault(issue["path"], []).append(issue)
+
+        stats = {"changed_files": 0, "changed": 0, "title_fixed": 0, "todo_injected": 0}
+        for path_str, issues in by_path.items():
+            rst = apply_fixes(Path(path_str), issues, translation_map, args.dry_run)
+            if rst["changed"] > 0:
+                stats["changed_files"] += 1
+            stats["changed"] += rst["changed"]
+            stats["title_fixed"] += rst["title_fixed"]
+            stats["todo_injected"] += rst["todo_injected"]
+
+        if args.dry_run:
+            print(f"\n预演完成（未落盘）: {stats}")
+        else:
+            print(f"\n已应用修复: {stats}")
+
+
+if __name__ == "__main__":
+    main()