chore: 补齐工作流闭环自检

README.md

@@ -155,6 +155,7 @@ pnpm run admin-login -- --url http://127.0.0.1:5999/#/auth/login
 - 改 KtTable、BlogArgon、AdminAuth、QQBot、FF14Plugin、NapCatLogin、SystemLog、Knife4jSwagger、FnosK8s 前调用 `kt_component_workflow`，先看专项禁区。
 - 不确定任务边界时调用 `kt_guardrails`，先拿到“能做什么、不能做什么、怎么验证”。
 - 验证前调用 `kt_suggest_verification`，避免盲跑全量构建。
+- API/Jest 验证建议使用 `pnpm exec jest --runInBand`；指定测试文件时使用 `pnpm exec jest --runInBand --runTestsByPath test/path.spec.ts`，不要把 Jest 参数写成 `pnpm test` 的错误透传形式。
 - 页面测试前调用 `kt_create_page_test_case`，再执行 Playwright/浏览器测试。
 - Admin 页面测试前可先执行 `pnpm run admin-login -- --url <Admin登录页>` 固化登录态，输出的 `storageState` 可作为后续 Playwright 用例前置状态。
 - 接口改动后调用 `kt_api_test_plan`，并真实请求一次接口。

src/selfTest.ts

@@ -75,6 +75,18 @@ export async function runSelfTest(): Promise<void> {
     throw new Error('refactor guardrail self-check failed');
   }
 
+  const apiVerification = buildVerificationPlan({
+    changeType: 'api',
+    project: 'api',
+  });
+  const apiVerificationCommands = apiVerification.commands.join('\n');
+  if (
+    !apiVerificationCommands.includes('pnpm exec jest --runInBand') ||
+    apiVerificationCommands.includes('passWithNoTests')
+  ) {
+    throw new Error('API Jest verification command self-check failed');
+  }
+
   const closeoutNeedsUpgrade = buildWorkstreamCloseout({
     problemRecords: ['Jenkins 状态需要结合日志和 K8s 状态确认。'],
     reusablePatterns: ['deploy-observation'],
@@ -209,6 +221,7 @@ export async function runSelfTest(): Promise<void> {
     reviewCliParser,
     reviewClassifier,
     refactorGuardrails,
+    apiVerification,
     businessTestPlan: buildBusinessTestPlan({
       flow: 'system-log-visualization',
     }),

src/tools/verification.ts

@@ -37,7 +37,8 @@ export function buildVerificationPlan(input: VerificationPlanInput): Verificatio
   if (project.alias === 'api') {
     if (scripts.lint) commands.push(`${packageManager} run lint`);
     if (scripts.test && ['api', 'backend', 'general', 'refactor'].includes(changeType)) {
-      commands.push(`${packageManager} test -- --passWithNoTests`);
+      commands.push(getJestCommand(packageManager));
+      notes.push('Jest 指定文件验证用 `pnpm exec jest --runInBand --runTestsByPath test/path.spec.ts`，不要写成 pnpm test 参数透传。');
     }
     if (['api', 'backend'].includes(changeType)) {
       notes.push('接口改动需要本地启动或复用本地服务，真实调用对应接口一次。');
@@ -91,3 +92,10 @@ export function buildVerificationPlan(input: VerificationPlanInput): Verificatio
     repoType,
   };
 }
+
+function getJestCommand(packageManager: string) {
+  if (packageManager === 'pnpm') return 'pnpm exec jest --runInBand';
+  if (packageManager === 'yarn') return 'yarn jest --runInBand';
+  if (packageManager === 'bun') return 'bun test';
+  return 'npx jest --runInBand';
+}