@deepstorm/cli 0.9.2 → 0.10.0

package/dist/skills/reef-style-backend/variants/nodejs/quick-reference.md

@@ -0,0 +1,116 @@
+# 后端编码快速参考 — Node.js / NestJS
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> 跨维度规范（适用所有后端代码）：
+> - [API 规范](api-spec.md) — RESTful 命名、统一响应体、OpenAPI、版本策略
+> - [依赖管理规范](dependency-management.md) — 版本一致性、CVE
+> - [异常处理深度规范](exception-handling.md) — 异常层次、错误码、全局过滤
+> - [安全红线](security-redlines.md) — P0/P1 安全规则（必须遵守）
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 模块结构 | 每个业务模块一个 NestJS Module，独立 Controller/Service/DTO/Entity |
+| 依赖注入 | 构造函数注入，`@Injectable()` 装饰器，禁止 `@Inject()` 字段注入 |
+| 参数验证 | DTO 使用 `class-validator` 装饰器（`@IsNotEmpty`、`@IsString`） |
+| 响应格式 | 统一使用 Controller 返回值，禁止在 Service 中直接返回 Response 对象 |
+| 异步处理 | 所有数据库/IO 操作用 `async/await`，禁止裸 `.subscribe()` 或 `.then()` |
+| 配置管理 | 使用 `@nestjs/config` 的 `ConfigService`，禁止 `process.env` 直读（测试不可 mock） |
+| 异常处理 | 使用 NestJS 全局异常过滤器（`ExceptionFilter`），禁止在 Controller 中 try-catch 吞异常 |
+| 日志 | 使用 `@nestjs/common` 的 `Logger`，构造函数中注入：`private readonly logger = new Logger(XxxService.name)` |
+| 类型安全 | 禁止 `any` 类型，优先用 `unknown` + 类型守卫 |
+| 模块注册 | 动态模块用 `forRoot()/forFeature()` 模式，禁止在 Module 中直接 `new Provider()` |
+
+## 代码风格
+
+### LLM 常犯错误
+
+- DTO 验证装饰器必须与 Swagger 装饰器同时存在（`@ApiProperty()` + `@IsString()`），禁止遗漏 Swagger
+- Controller 方法用 `@HttpCode()` 显式声明状态码，不依赖默认 200
+- Service 方法中数据库查询用 `findFirstOrThrow()` / `findUniqueOrThrow()` 替代手动 `if (!result) throw`
+- Prisma 事务用 `$transaction` 包裹，禁止手动 `prisma.$executeRaw` 拼事务
+- 枚举值用 `@nestjs/common` 的 `EnumValidationPipe` 校验，禁止手动 `if (!Object.values(E).includes(v))`
+- 不在 Controller 中直接实例化 Service（由 DI 注入），不在 Service 中直接实例化 Repository（由 DI 注入）
+- 所有 `catch` 块不能为空：要么 `throw` 重新抛出，要么 `this.logger.error()` + 返回 fallback
+
+### TypeScript Decorator 使用规范
+
+| 组件类型 | 必用装饰器 | 说明 |
+|---------|-----------|------|
+| Controller | `@Controller('prefix')`、`@Get()`/`@Post()`/`@Put()`/`@Delete()` | 路由定义 |
+| DTO | `@ApiProperty()`、`@IsString()`/`@IsNumber()`/`@IsOptional()` | 验证 + Swagger |
+| Service | `@Injectable()` | DI 可注入 |
+| Module | `@Module()` | NestJS 模块定义 |
+| Entity (Prisma) | 使用 Prisma Schema 定义，不额外装饰 | TypeScript 类型由 `prisma generate` 生成 |
+
+### 控件能力声明模式
+
+NestJS 中通过 Interface 和 Provider 令牌实现能力声明：
+
+```typescript
+// 定义能力接口
+export interface ToolCapability {
+  readonly name: string;
+  supports(context: ExecutionContext): boolean;
+  execute(input: unknown): Promise<unknown>;
+}
+
+// 注册 Provider
+@Module({
+  providers: [
+    { provide: 'TOOL_CAPABILITIES', useClass: TextToolCapability, multi: true },
+  ],
+})
+export class ToolsModule {}
+```
+
+## 注释规则
+
+| 文件类型 | 注释要求 |
+|---------|---------|
+| **Entity / Prisma Schema** | Prisma Schema 中每个 model 加 `/// 注释`；生成类型不修改 |
+| **DTO** | 类 JSDoc `/** 用途说明 */`；字段装饰器自带文档（`@ApiProperty({ description: '...' })`） |
+| **Service** | 每个 public 方法加 JSDoc `/** 功能、@param、@returns */` |
+| **Controller** | 每个端点加 `@ApiOperation({ summary: '...', description: '...' })` |
+| **Module** | 类 JSDoc `/** 模块职责 */`；`@Module({})` 中 imports/providers/exports 按字母排序 |
+
+## 项目目录结构
+
+```
+src/
+├── main.ts                   # 入口文件
+├── app.module.ts             # 根模块
+├── app.controller.ts         # 根 Controller（健康检查）
+├── prisma/
+│   ├── prisma.module.ts      # Prisma 全局模块
+│   └── prisma.service.ts     # Prisma Client 封装
+├── modules/
+│   └── {module}/
+│       ├── {module}.module.ts
+│       ├── {module}.controller.ts
+│       ├── {module}.service.ts
+│       ├── dto/
+│       │   ├── create-{entity}.dto.ts
+│       │   └── update-{entity}.dto.ts
+│       └── entities/
+│           └── {entity}.entity.ts   # Prisma 生成类型的二次封装（可选）
+├── common/
+│   ├── filters/              # 全局异常过滤器
+│   ├── pipes/                # 全局管道
+│   ├── interceptors/         # 全局拦截器
+│   └── guards/               # 全局守卫
+└── config/
+    └── configuration.ts      # 配置模块
+```
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| 循环依赖 | Module A imports Module B，Module B imports Module A | 用 `forwardRef(() => ModuleB)` |
+| 异步初始化 | Service 的 `constructor` 中 await Prisma 连接 | 实现 `OnModuleInit` 接口，在 `onModuleInit()` 中初始化 |
+| 环境变量直读 | `process.env.DB_URL` 在代码中硬编码 | 通过 `ConfigService.get('DB_URL')` 读取 |
+| DTO 缺少装饰器 | `class-validator` 装饰器缺失导致验证不生效 | 每个 DTO 字段同时加 `@ApiProperty()` 和验证装饰器 |
+| 事务边界 | 事务内调用外部 HTTP 服务 | Prisma `$transaction` 中禁止非数据库操作 |

package/dist/skills/sweep-init/SKILL.md

@@ -103,107 +103,21 @@ E2E_PATH=$(cat .deepstorm/settings.json 2>/dev/null | grep -o '"e2eProjectPath"[
 
 ---
 
-### 步骤 2：创建项目目录结构
+### 步骤 2+3：创建项目目录与配置文件
 
-在 `{TARGET_DIR}` 下创建 E2E 测试项目的目录骨架。
-
-#### 目录结构（当 TARGET_DIR 为 `"."` 时）
-
-```
-.
-├── flows/                       # 测试意图文档目录
-│   ├── topology.yaml            # 功能模块拓扑定义（待用户编辑）
-│   └── reports/                 # 执行报告持久化目录
-├── scripts/
-│   └── flow-selector.mjs        # 层级选择工具（预置）
-├── .env                         # 环境变量（gitignored，即模板）
-├── package.json                 # 依赖声明
-└── tsconfig.json                # TypeScript 配置
-```
-
-> 如果 TARGET_DIR 为 `"e2e"`，以上所有文件在 `e2e/` 下生成。如果框架为 `playwright`，还会额外生成 `playwright.config.ts`。
-
-#### 执行
+使用 `init-project.mjs` 一键创建目录结构并生成所有配置文件：
 
 ```bash
-# 计算目标目录：TARGET_DIR 为 "." 时用当前目录，否则用 TARGET_DIR
-if [ "$TARGET_DIR" != "." ]; then
-  mkdir -p "$TARGET_DIR"/flows "$TARGET_DIR"/flows/reports "$TARGET_DIR"/scripts
-  echo "📂 将在 $TARGET_DIR/ 目录下生成 E2E 测试项目"
-else
-  mkdir -p flows flows/reports scripts
-fi
-```
-
----
-
-### 步骤 3：生成项目配置文件（框架感知）
-
-根据步骤 0 读取的框架配置，在 `{TARGET_DIR}` 下生成对应的配置文件。
-
-> 所有文件写入路径以 `{TARGET_DIR}` 为前缀。当 `TARGET_DIR` 为 `"."` 时，路径不变。
-
-#### 3.1 package.json
-
-写入基础 `package.json`。如果框架为 `playwright`，包含 Playwright 依赖：
-
-```json
-{
-  "name": "sweep-e2e",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "playwright test",
-    "report": "playwright show-report"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.50.0",
-    "@inquirer/checkbox": "^4.0.0",
-    "@types/node": "^22.0.0"
-  }
-}
-```
-
-> 当 E2E 框架未知或未配置时，`package.json` 中仅包含 `@inquirer/checkbox` 和 `@types/node` 依赖，**不包含** `@playwright/test`。
-
-#### 3.2 框架配置文件
-
-**当框架为 `playwright` 时**，写入 `{TARGET_DIR}/playwright.config.ts`，包含多环境 baseURL 设置：
-
-```ts
-import { defineConfig } from '@playwright/test';
-
-export default defineConfig({
-  use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
-  },
-  timeout: 30000,
-  retries: 0,
-  reporter: [['line'], ['html', { outputFolder: 'flows/reports' }]],
-  projects: [
-    { name: 'chromium', use: { browserName: 'chromium' } },
-  ],
-});
+node packages/sweep/skills/sweep-init/scripts/init-project.mjs \
+  --dir "$TARGET_DIR" \
+  --framework "$(node scripts/env-manager.mjs --framework | node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).framework || ''")"
 ```
 
-**当框架未知或未配置时**，跳过框架配置文件的生成，输出提示："框架未配置，请运行 deepstorm setup 并选择 E2E 框架。"
-
-#### 3.3 tsconfig.json
-
-写入 TypeScript 配置（框架无关）：
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true
-  }
-}
-```
+脚本会自动：
+- 创建 `flows/`、`flows/reports/`、`scripts/` 目录
+- 生成 `package.json`（含框架对应依赖）、`tsconfig.json`、`playwright.config.ts`（仅 playwright）
+- 不覆盖已有的 `topology.yaml`
+- 执行 `npm install`
 
 ---
 
@@ -312,38 +226,11 @@ cat .mcp.json 2>/dev/null | grep -c "deepstorm-playwright"
 
 #### 8.1 写入 e2eProjectPath 到 settings.json
 
-将 `sweep.e2eProjectPath` 写入 `.deepstorm/settings.json`。**不再创建 `.sweep-init` 标记文件。**
-
-```bash
-# 值由步骤 0A 确定：
-#   独立项目 → "."
-#   混放项目 → 用户选择的路径（如 "e2e"）
-```
-
-写入后的 settings.json 结构示例：
-
-```json
-{
-  "sweep": {
-    "e2eFramework": "playwright",
-    "e2eProjectPath": "e2e",
-    "environments": { ... }
-  }
-}
-```
-
-#### 8.2 安装依赖
-
 ```bash
-# 在目标目录中执行 npm install
-if [ "$TARGET_DIR" != "." ]; then
-  cd "$TARGET_DIR" && npm install
-else
-  npm install
-fi
+node scripts/env-manager.mjs --set-e2e-path "$TARGET_DIR"
 ```
 
-#### 8.3 输出完成信息
+#### 8.2 输出完成信息
 
 ```
 ✅ Sweep E2E 测试项目初始化完成！

package/dist/skills/sweep-init/scripts/init-project.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+/**
+ * init-project.mjs
+ * 初始化 E2E 测试项目骨架。
+ *
+ * 用法:
+ *   node init-project.mjs                 # 在当前目录
+ *   node init-project.mjs --dir e2e       # 指定子目录
+ *   node init-project.mjs --framework playwright
+ *   node init-project.mjs --help
+ */
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+// ── Template writers ──────────────────────────────────────────────
+
+function writePackageJson(targetDir, framework) {
+  const deps = {
+    '@inquirer/checkbox': '^4.0.0',
+    '@types/node': '^22.0.0',
+  };
+  if (framework === 'playwright') {
+    deps['@playwright/test'] = '^1.50.0';
+  }
+  const scripts = { report: 'playwright show-report' };
+  if (framework === 'playwright') {
+    scripts.test = 'playwright test';
+  }
+
+  writeFileSync(join(targetDir, 'package.json'), JSON.stringify({
+    name: 'sweep-e2e',
+    version: '1.0.0',
+    private: true,
+    type: 'module',
+    scripts,
+    devDependencies: deps,
+  }, null, 2) + '\n');
+}
+
+function writePlaywrightConfig(targetDir) {
+  writeFileSync(join(targetDir, 'playwright.config.ts'), [
+    "import { defineConfig } from '@playwright/test';",
+    '',
+    'export default defineConfig({',
+    '  use: {',
+    "    baseURL: process.env.BASE_URL || 'http://localhost:3000',",
+    '  },',
+    '  timeout: 30000,',
+    '  retries: 0,',
+    "  reporter: [['line'], ['html', { outputFolder: 'flows/reports' }]],",
+    '  projects: [',
+    "    { name: 'chromium', use: { browserName: 'chromium' } },",
+    '  ],',
+    '});',
+    '',
+  ].join('\n'));
+}
+
+function writeTsconfig(targetDir) {
+  writeFileSync(join(targetDir, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'bundler',
+      strict: true,
+      esModuleInterop: true,
+    },
+  }, null, 2) + '\n');
+}
+
+function writeTopologyYaml(targetDir) {
+  writeFileSync(join(targetDir, 'flows', 'topology.yaml'), [
+    '# flows/topology.yaml',
+    'name: E2E 测试拓扑',
+    'version: 1',
+    'modules:',
+    '  - name: example',
+    '    description: 示例模块',
+    '    children:',
+    '      - name: feature1',
+    '        description: 功能 1',
+    '        features: []',
+    '',
+  ].join('\n'));
+}
+
+// ── Main ──────────────────────────────────────────────────────────
+
+export function initProject(opts = {}) {
+  const {
+    framework = null,   // 'playwright' | null
+    dir = '.',
+  } = opts;
+
+  const targetDir = resolve(process.cwd(), dir);
+  const flowsDir = join(targetDir, 'flows');
+  const reportsDir = join(flowsDir, 'reports');
+  const scriptsDir = join(targetDir, 'scripts');
+
+  // 创建目录
+  mkdirSync(flowsDir, { recursive: true });
+  mkdirSync(reportsDir, { recursive: true });
+  mkdirSync(scriptsDir, { recursive: true });
+
+  // 写入配置文件
+  writePackageJson(targetDir, framework);
+  writeTsconfig(targetDir);
+
+  if (framework === 'playwright') {
+    writePlaywrightConfig(targetDir);
+  }
+
+  if (!existsSync(join(flowsDir, 'topology.yaml'))) {
+    writeTopologyYaml(targetDir);
+  }
+
+  // npm install
+  try {
+    execSync('npm install', {
+      cwd: targetDir,
+      stdio: 'pipe',
+      timeout: 60000,
+    });
+  } catch {
+    // npm install 失败不阻塞
+  }
+
+  const created = [
+    'flows/', 'flows/reports/', 'scripts/',
+    'package.json', 'tsconfig.json',
+  ];
+  if (framework === 'playwright') created.push('playwright.config.ts');
+  if (!existsSync(join(flowsDir, 'topology.yaml'))) {
+    created.push('flows/topology.yaml');
+  }
+
+  return { dir: targetDir, created, framework };
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────
+
+if (import.meta.filename === process.argv[1]) {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(`
+init-project.mjs — E2E 测试项目初始化
+
+用法:
+  node init-project.mjs                         当前目录
+  node init-project.mjs --dir e2e               指定子目录
+  node init-project.mjs --framework playwright   指定框架
+  node init-project.mjs --help
+`);
+    process.exit(0);
+  }
+
+  const dirIdx = process.argv.indexOf('--dir');
+  const fwIdx = process.argv.indexOf('--framework');
+  const result = initProject({
+    dir: dirIdx >= 0 ? process.argv[dirIdx + 1] : '.',
+    framework: fwIdx >= 0 ? process.argv[fwIdx + 1] : null,
+  });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/dist/skills/sweep-run/SKILL.md

@@ -58,52 +58,28 @@ node scripts/env-manager.mjs --framework
 
 ### 步骤 1：检查初始化状态与路径导航
 
-从 `.deepstorm/settings.json` 读取 `sweep.e2eProjectPath`，确定 E2E 测试项目的位置，如非根目录则自动切换。支持从子目录向上查找以兼容用户在 E2E 项目子目录中执行的情况。
+从 `.deepstorm/settings.json` 读取 `sweep.e2eProjectPath`，确定 E2E 测试项目的位置。
 
 ```bash
-# 向上查找 .deepstorm/settings.json
-DEEPSTORM_DIR=""
-CUR="$PWD"
-while [ "$CUR" != "/" ]; do
-  if [ -f "$CUR/.deepstorm/settings.json" ]; then
-    DEEPSTORM_DIR="$CUR"
-    break
-  fi
-  CUR=$(dirname "$CUR")
-done
-
-if [ -n "$DEEPSTORM_DIR" ]; then
-  E2E_PATH=$(grep -o '"e2eProjectPath"[^,]*' "$DEEPSTORM_DIR/.deepstorm/settings.json" | head -1 | cut -d'"' -f4)
-else
-  E2E_PATH=""
-fi
+node scripts/env-manager.mjs --project-root
+# 输出: {"found":true,"path":"/abs/path/to/project"}
 ```
 
 #### 1.1 配置存在 → 路径导航
 
-- **WHEN** `E2E_PATH` 不为空
-- **THEN** 判断路径值。注意 `E2E_PATH` 是基于 `DEEPSTORM_DIR`（settings.json 所在目录）的相对路径，若当前在子目录则需拼接：
+- **WHEN** `--project-root` 输出 `found: true`
+- **THEN** 读取 `sweep.e2eProjectPath`：
   ```bash
-  if [ "$E2E_PATH" != "." ]; then
-    # 若从子目录找到的 settings.json，E2E_PATH 相对于 DEEPSTORM_DIR
-    TARGET_DIR="$E2E_PATH"
-    if [ -n "$DEEPSTORM_DIR" ] && [ "$DEEPSTORM_DIR" != "$PWD" ]; then
-      TARGET_DIR="$DEEPSTORM_DIR/$E2E_PATH"
-    fi
-    if [ -d "$TARGET_DIR" ]; then
-      echo "📂 切换到 E2E 项目目录: $E2E_PATH"
-      cd "$TARGET_DIR"
-    else
-      echo "❌ E2E 项目目录不存在: $E2E_PATH，请重新运行 /sweep-init"
-      exit 1
-    fi
-  fi
+  E2E_PATH=$(grep -o '"e2eProjectPath"[^,]*' \
+    "$(node scripts/env-manager.mjs --project-root | \
+      node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).path")/.deepstorm/settings.json" \
+    | head -1 | cut -d'"' -f4)
   ```
 
 #### 1.2 配置不存在 → 报错退出
 
-- **WHEN** `E2E_PATH` 为空
-- **THEN** 提示"❌ 未检测到 E2E 项目。请先运行 /sweep-init 初始化。"并退出
+- **WHEN** `--project-root` 输出 `found: false`
+- **THEN** 提示"❌ 未检测到深风项目。请先运行 deepstorm setup。"并退出
 
 ---
 

package/dist/skills/sweep-run/scripts/env-manager.mjs

@@ -20,8 +20,8 @@
  *   import { resolveEnv, listEnvs, readFramework, checkMcpAvailable } from './env-manager.mjs'
  */
 
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, sep } from 'node:path';
 
 // ── Path helpers (lazy, respect process.cwd() changes) ────────────
 
@@ -217,6 +217,55 @@ export function readFramework() {
 
 // ── MCP availability ──────────────────────────────────────────────
 
+// ── Project root discovery ──────────────────────────────────────────
+
+/**
+ * Walk up from startDir to find .deepstorm/settings.json
+ *
+ * @param {string} [startDir] - defaults to process.cwd()
+ * @returns {string|null} resolved dir containing settings.json, or null
+ */
+export function resolveProjectRoot(startDir) {
+  let dir = startDir ? resolve(startDir) : process.cwd();
+  while (true) {
+    if (existsSync(resolve(dir, '.deepstorm', 'settings.json'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Write or update a key in .deepstorm/settings.json.
+ *
+ * @param {string} keyPath dot-separated path, e.g. "sweep.e2eProjectPath"
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function writeDeepstormConfig(keyPath, value) {
+  const filePath = resolve(process.cwd(), '.deepstorm', 'settings.json');
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const config = JSON.parse(content);
+    const keys = keyPath.split('.');
+    let obj = config;
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!obj[keys[i]] || typeof obj[keys[i]] !== 'object') {
+        obj[keys[i]] = {};
+      }
+      obj = obj[keys[i]];
+    }
+    obj[keys[keys.length - 1]] = value;
+    writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if the required MCP service is configured in .mcp.json.
  *
@@ -263,6 +312,26 @@ if (process.argv[1] === import.meta.filename) {
     process.exit(0);
   }
 
+  if (args.includes('--project-root')) {
+    const startIdx = args.indexOf('--project-root');
+    const startDir = startIdx + 1 < args.length ? args[startIdx + 1] : undefined;
+    const result = resolveProjectRoot(startDir);
+    if (result) {
+      console.log(JSON.stringify({ found: true, path: result }));
+    } else {
+      console.log(JSON.stringify({ found: false }));
+    }
+    process.exit(0);
+  }
+
+  if (args.includes('--set-e2e-path')) {
+    const idx = args.indexOf('--set-e2e-path');
+    const path = idx + 1 < args.length ? args[idx + 1] : '.';
+    const ok = writeDeepstormConfig('sweep.e2eProjectPath', path);
+    console.log(JSON.stringify({ ok, path }));
+    process.exit(0);
+  }
+
   // Default: resolve env
   const envFlag = args.find(a => a.startsWith('--env='));
   const envName = envFlag ? envFlag.split('=')[1] : undefined;