refactor: checker 模块内聚化 — 每个 checker 自包含于独立目录

将 checker 架构重构为完全内聚模式：每个 checker 目录包含自身的
types、schema、validate、execute、expect 和 index，新增 checker
只需创建一个目录并在 runner/index.ts 添加一行注册。

主要变更：
- runner/shared/ 拆分：断言基础设施迁入 checker/expect/，
  body.ts 迁入 http/，text.ts 迁入 command/
- config-contract/ 重命名为 schema/，schema.ts → builder.ts
- size.ts + parseDuration 合并为 utils.ts
- 顶层 types.ts 改为 base interface + index signature，
  checker 专属类型下沉到各自 types.ts
- runner/index.ts 改为显式数组注册模式
- 更新 DEVELOPMENT.md 项目结构和开发新 Checker 指南

src/server/checker/runner/http/body.ts

@@ -0,0 +1,210 @@
+import { DOMParser } from "@xmldom/xmldom";
+import * as cheerio from "cheerio";
+import * as xpath from "xpath";
+
+import type { ExpectResult } from "../../expect/types";
+import type { BodyRule, CssRule, JsonRule, XpathRule } from "./types";
+
+import { errorFailure, mismatchFailure } from "../../expect/failure";
+import { applyOperator, evaluateJsonPath } from "../../expect/operator";
+
+export function checkBodyExpect(body: string, rules?: BodyRule[]): ExpectResult {
+  if (!rules || rules.length === 0) return { failure: null, matched: true };
+
+  for (let i = 0; i < rules.length; i++) {
+    const result = checkSingleBodyRule(body, rules[i]!, i);
+    if (!result.matched) return result;
+  }
+
+  return { failure: null, matched: true };
+}
+
+function checkCssRule(body: string, rule: CssRule, rulePath: string): ExpectResult {
+  const { attr, selector, ...operators } = rule;
+  const fullPath = `${rulePath}.css(${selector}${attr ? `@${attr}` : ""})`;
+
+  let $: cheerio.CheerioAPI;
+  try {
+    $ = cheerio.load(body);
+  } catch {
+    return {
+      failure: errorFailure("body", fullPath, "failed to parse HTML"),
+      matched: false,
+    };
+  }
+
+  const el = $(selector);
+  const opKeys = Object.keys(operators);
+
+  if (opKeys.length === 0) {
+    if (attr !== undefined) {
+      if (el.attr(attr) === undefined) {
+        return {
+          failure: mismatchFailure("body", fullPath, "attr present", undefined, `attribute ${attr} not found`),
+          matched: false,
+        };
+      }
+      return { failure: null, matched: true };
+    }
+    if (el.length === 0) {
+      return {
+        failure: mismatchFailure("body", fullPath, "element found", "no match", `selector ${selector} not found`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+
+  if (operators.exists === true) {
+    if (el.length === 0) {
+      return {
+        failure: mismatchFailure("body", fullPath, true, false, `selector ${selector} not found`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+  if (operators.exists === false) {
+    if (el.length > 0) {
+      return {
+        failure: mismatchFailure("body", fullPath, false, true, `selector ${selector} exists`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+
+  if (el.length === 0) {
+    return {
+      failure: mismatchFailure("body", fullPath, "element found", "no match", `selector ${selector} not found`),
+      matched: false,
+    };
+  }
+
+  const actual = attr ? el.attr(attr) : el.text();
+  const matched = applyOperator(actual ?? "", operators);
+  if (!matched) {
+    return {
+      failure: mismatchFailure("body", fullPath, operators, actual, `css selector ${selector} mismatch`),
+      matched: false,
+    };
+  }
+  return { failure: null, matched: true };
+}
+
+function checkJsonRule(body: string, rule: JsonRule, rulePath: string): ExpectResult {
+  const { path, ...operators } = rule;
+  const fullPath = `${rulePath}.json(${path})`;
+
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return {
+      failure: errorFailure("body", fullPath, "body is not valid JSON"),
+      matched: false,
+    };
+  }
+
+  const actual = evaluateJsonPath(json, path);
+  const opKeys = Object.keys(operators);
+
+  if (opKeys.length === 0) {
+    if (actual === undefined) {
+      return {
+        failure: mismatchFailure("body", fullPath, "defined", actual, `path ${path} is undefined`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+
+  const matched = applyOperator(actual, operators);
+  if (!matched) {
+    return {
+      failure: mismatchFailure("body", fullPath, operators, actual, `json path ${path} mismatch`),
+      matched: false,
+    };
+  }
+  return { failure: null, matched: true };
+}
+
+function checkSingleBodyRule(body: string, rule: BodyRule, index: number): ExpectResult {
+  const rulePath = `body[${index}]`;
+
+  if ("contains" in rule) {
+    const matched = body.includes(rule.contains);
+    if (!matched) {
+      return {
+        failure: mismatchFailure("body", rulePath, rule.contains, body, `body does not contain "${rule.contains}"`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+
+  if ("regex" in rule) {
+    const matched = new RegExp(rule.regex).test(body);
+    if (!matched) {
+      return {
+        failure: mismatchFailure("body", rulePath, `/${rule.regex}/`, body, `body does not match /${rule.regex}/`),
+        matched: false,
+      };
+    }
+    return { failure: null, matched: true };
+  }
+
+  if ("json" in rule) {
+    return checkJsonRule(body, rule.json, rulePath);
+  }
+
+  if ("css" in rule) {
+    return checkCssRule(body, rule.css, rulePath);
+  }
+
+  if ("xpath" in rule) {
+    return checkXpathRule(body, rule.xpath, rulePath);
+  }
+
+  return { failure: null, matched: true };
+}
+
+function checkXpathRule(body: string, rule: XpathRule, rulePath: string): ExpectResult {
+  const { path, ...operators } = rule;
+  const fullPath = `${rulePath}.xpath(${path})`;
+
+  let doc: ReturnType<DOMParser["parseFromString"]>;
+  try {
+    doc = new DOMParser().parseFromString(body, "text/xml");
+  } catch {
+    return {
+      failure: errorFailure("body", fullPath, "failed to parse XML/HTML"),
+      matched: false,
+    };
+  }
+
+  const nodes = xpath.select(path, doc as unknown as Node);
+  if (!nodes || !Array.isArray(nodes) || nodes.length === 0) {
+    return {
+      failure: mismatchFailure("body", fullPath, "node found", "no match", `xpath ${path} not found`),
+      matched: false,
+    };
+  }
+
+  const node = nodes[0]!;
+  const actual = node.nodeValue ?? (node as unknown as Element).textContent ?? "";
+  const opKeys = Object.keys(operators);
+
+  if (opKeys.length === 0) {
+    return { failure: null, matched: true };
+  }
+
+  const matched = applyOperator(actual, operators);
+  if (!matched) {
+    return {
+      failure: mismatchFailure("body", fullPath, operators, actual, `xpath ${path} mismatch`),
+      matched: false,
+    };
+  }
+  return { failure: null, matched: true };
+}

src/server/checker/runner/http/execute.ts

@@ -1,14 +1,15 @@
 import { isError } from "es-toolkit";
 
-import type { CheckResult, HttpTargetConfig, ResolvedHttpTarget, ResolvedTarget, TargetConfig } from "../../types";
+import type { CheckResult, RawTargetConfig, ResolvedTargetBase } from "../../types";
 import type { Checker, CheckerContext, CheckerValidationInput, ResolveContext } from "../types";
+import type { HttpExpectConfig, HttpTargetConfig, ResolvedHttpTarget } from "./types";
 
-import { parseSize } from "../../size";
-import { checkBodyExpect } from "../shared/body";
-import { checkDuration } from "../shared/duration";
-import { errorFailure, mismatchFailure } from "../shared/failure";
-import { httpCheckerSchemas } from "./contract";
+import { checkDuration } from "../../expect/duration";
+import { errorFailure, mismatchFailure } from "../../expect/failure";
+import { parseSize } from "../../utils";
+import { checkBodyExpect } from "./body";
 import { checkHeaders, checkStatus } from "./expect";
+import { httpCheckerSchemas } from "./schema";
 import { validateHttpConfig } from "./validate";
 
 const CHARSET_RE = /charset="?([^";\s]+)"?/i;
@@ -22,7 +23,7 @@ export class HttpChecker implements Checker {
 
   readonly type = "http";
 
-  async execute(target: ResolvedTarget, ctx: CheckerContext): Promise<CheckResult> {
+  async execute(target: ResolvedTargetBase, ctx: CheckerContext): Promise<CheckResult> {
     const t = target as ResolvedHttpTarget;
     const timestamp = new Date().toISOString();
     const expect = t.expect;
@@ -116,15 +117,17 @@ export class HttpChecker implements Checker {
     }
   }
 
-  resolve(target: TargetConfig, context: ResolveContext): ResolvedTarget {
-    const t = target as TargetConfig & { http: HttpTargetConfig; type: "http" };
-    const httpDefaults = context.defaults.http;
+  resolve(target: RawTargetConfig, context: ResolveContext): ResolvedTargetBase {
+    const t = target as RawTargetConfig & { http: HttpTargetConfig; type: "http" };
+    const httpDefaults = context.defaults["http"] as
+      | undefined
+      | { headers?: Record<string, string>; maxBodyBytes?: string; method?: string };
 
     const method = t.http.method ?? httpDefaults?.method ?? "GET";
     const maxBodyBytes = parseSize(t.http.maxBodyBytes ?? httpDefaults?.maxBodyBytes ?? "100MB");
 
     return {
-      expect: target.expect,
+      expect: target.expect as HttpExpectConfig | undefined,
       group: target.group ?? "default",
       http: {
         body: t.http.body,
@@ -142,7 +145,7 @@ export class HttpChecker implements Checker {
     } satisfies ResolvedHttpTarget;
   }
 
-  serialize(target: ResolvedTarget): { config: string; target: string } {
+  serialize(target: ResolvedTargetBase): { config: string; target: string } {
     const t = target as ResolvedHttpTarget;
     return {
       config: JSON.stringify({

src/server/checker/runner/http/expect.ts

@@ -1,8 +1,8 @@
-import type { HeaderExpect } from "../../types";
-import type { ExpectResult } from "../shared/duration";
+import type { ExpectResult } from "../../expect/types";
+import type { HeaderExpect } from "./types";
 
-import { mismatchFailure } from "../shared/failure";
-import { applyOperator } from "../shared/operator";
+import { mismatchFailure } from "../../expect/failure";
+import { applyOperator } from "../../expect/operator";
 
 export function checkHeaders(
   headers: Record<string, string>,

src/server/checker/runner/http/index.ts

@@ -0,0 +1 @@
+export { HttpChecker } from "./execute";

src/server/checker/runner/http/schema.ts

@@ -9,7 +9,7 @@ import {
   sizeSchema,
   statusCodePatternSchema,
   stringMapSchema,
-} from "../../config-contract/fragments";
+} from "../../schema/fragments";
 
 export const httpCheckerSchemas: CheckerSchemas = {
   config: Type.Object(

src/server/checker/runner/http/types.ts

@@ -0,0 +1,59 @@
+import type { ExpectOperator, ResolvedTargetBase } from "../../types";
+
+export type BodyRule =
+  | { contains: string }
+  | { css: CssRule }
+  | { json: JsonRule }
+  | { regex: string }
+  | { xpath: XpathRule };
+
+export type CssRule = ExpectOperator & { attr?: string; selector: string };
+
+export type HeaderExpect = ExpectOperator | string;
+
+export interface HttpDefaultsConfig {
+  headers?: Record<string, string>;
+  maxBodyBytes?: string;
+  method?: string;
+}
+
+export interface HttpExpectConfig {
+  body?: BodyRule[];
+  headers?: Record<string, HeaderExpect>;
+  maxDurationMs?: number;
+  status?: Array<number | string>;
+}
+
+export interface HttpTargetConfig {
+  body?: string;
+  headers?: Record<string, string>;
+  ignoreSSL?: boolean;
+  maxBodyBytes?: string;
+  maxRedirects?: number;
+  method?: string;
+  url: string;
+}
+
+export type JsonRule = ExpectOperator & { path: string };
+
+export interface ResolvedHttpConfig {
+  body?: string;
+  headers: Record<string, string>;
+  ignoreSSL: boolean;
+  maxBodyBytes: number;
+  maxRedirects: number;
+  method: string;
+  url: string;
+}
+
+export interface ResolvedHttpTarget extends ResolvedTargetBase {
+  expect?: HttpExpectConfig;
+  group: string;
+  http: ResolvedHttpConfig;
+  intervalMs: number;
+  name: string;
+  timeoutMs: number;
+  type: "http";
+}
+
+export type XpathRule = ExpectOperator & { path: string };

src/server/checker/runner/http/validate.ts

@@ -1,15 +1,26 @@
-import type { ConfigValidationIssue } from "../../config-contract/issues";
+import { DOMParser } from "@xmldom/xmldom";
+import * as xpath from "xpath";
+
+import type { ConfigValidationIssue } from "../../schema/issues";
 import type { CheckerValidationInput } from "../types";
 
-import { issue, joinPath } from "../../config-contract/issues";
-import { parseSize } from "../../size";
-import { validateBodyRules, validateOperatorObject } from "../shared/validate";
+import { isPlainRecord, validateOperatorObject } from "../../expect/validate-operator";
+import { BodyRuleTypeKeys, OperatorKeys } from "../../schema/fragments";
+import { issue, joinPath } from "../../schema/issues";
+import { parseSize } from "../../utils";
 
 const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+const OPERATOR_KEY_SET = new Set<string>(OperatorKeys);
+
+export function validateBodyRules(body: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (!Array.isArray(body)) return [issue("invalid-type", path, "必须为数组", targetName)];
+  return body.flatMap((rule, index) => validateSingleBodyRule(rule, `${path}[${index}]`, targetName));
+}
 
 export function validateHttpConfig(input: CheckerValidationInput): ConfigValidationIssue[] {
   const issues: ConfigValidationIssue[] = [];
-  const defaults = isRecord(input.defaults) && isRecord(input.defaults["http"]) ? input.defaults["http"] : undefined;
+  const defaults =
+    isPlainRecord(input.defaults) && isPlainRecord(input.defaults["http"]) ? input.defaults["http"] : undefined;
 
   if (isSizeInput(defaults?.["maxBodyBytes"])) {
     issues.push(...validateSizeValue(defaults["maxBodyBytes"], "defaults.http.maxBodyBytes"));
@@ -17,7 +28,7 @@ export function validateHttpConfig(input: CheckerValidationInput): ConfigValidat
 
   for (let i = 0; i < input.targets.length; i++) {
     const target = input.targets[i] as unknown;
-    if (!isRecord(target)) continue;
+    if (!isPlainRecord(target)) continue;
     if (target["type"] !== "http") continue;
     issues.push(...validateHttpTarget(target, `targets[${i}]`));
   }
@@ -25,6 +36,43 @@ export function validateHttpConfig(input: CheckerValidationInput): ConfigValidat
   return issues;
 }
 
+export function validateJsonPath(path: string, rulePath: string, targetName?: string): ConfigValidationIssue[] {
+  if (!path.startsWith("$.") || path.length <= 2) {
+    return [issue("invalid-jsonpath", joinPath(rulePath, "path"), '必须为以 "$." 开头的有效 JSONPath', targetName)];
+  }
+  const issues: ConfigValidationIssue[] = [];
+  const segments = path.slice(2).split(".");
+  for (const seg of segments) {
+    if (seg === "") {
+      issues.push(issue("invalid-jsonpath", joinPath(rulePath, "path"), "包含空段", targetName));
+    }
+    const bracketMatch = /^(.+?)\[(\d+)\]$/.exec(seg);
+    if (bracketMatch?.[1]!.trim() === "") {
+      issues.push(issue("invalid-jsonpath", joinPath(rulePath, "path"), "数组访问缺少属性名", targetName));
+    }
+  }
+  return issues;
+}
+
+function collectOperatorObject(
+  object: Record<string, unknown>,
+  allowedKeys: Set<string>,
+  path: string,
+  targetName?: string,
+): { issues: ConfigValidationIssue[]; operators: Record<string, unknown> } {
+  const issues: ConfigValidationIssue[] = [];
+  const operators: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(object)) {
+    if (allowedKeys.has(key)) continue;
+    if (OPERATOR_KEY_SET.has(key)) {
+      operators[key] = value;
+    } else {
+      issues.push(issue("unknown-field", joinPath(path, key), "是未知字段", targetName));
+    }
+  }
+  return { issues, operators };
+}
+
 function getTargetName(target: Record<string, unknown>): string | undefined {
   return typeof target["name"] === "string" ? target["name"] : undefined;
 }
@@ -33,22 +81,35 @@ function isNonNegativeFiniteNumber(value: unknown): boolean {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function isSizeInput(value: unknown): value is number | string {
   return typeof value === "number" || typeof value === "string";
 }
 
+function validateCssRule(rule: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (!isPlainRecord(rule)) return [issue("invalid-type", path, "必须为对象", targetName)];
+  const issues: ConfigValidationIssue[] = [];
+  if (typeof rule["selector"] !== "string" || rule["selector"].trim() === "") {
+    issues.push(issue("invalid-type", joinPath(path, "selector"), "必须为非空字符串", targetName));
+  }
+  if ("attr" in rule && typeof rule["attr"] !== "string") {
+    issues.push(issue("invalid-type", joinPath(path, "attr"), "必须为字符串", targetName));
+  }
+  const result = collectOperatorObject(rule, new Set(["attr", "selector"]), path, targetName);
+  issues.push(
+    ...result.issues,
+    ...validateOperatorObject(result.operators, path, targetName, { requireAtLeastOne: false }),
+  );
+  return issues;
+}
+
 function validateHttpExpect(target: Record<string, unknown>, path: string): ConfigValidationIssue[] {
   const targetName = getTargetName(target);
   const expect = target["expect"];
-  if (expect === undefined || expect === null || !isRecord(expect)) return [];
+  if (expect === undefined || expect === null || !isPlainRecord(expect)) return [];
   const issues: ConfigValidationIssue[] = [];
   const expectPath = joinPath(path, "expect");
 
-  if (isRecord(expect["headers"])) {
+  if (isPlainRecord(expect["headers"])) {
     for (const [key, value] of Object.entries(expect["headers"])) {
       if (typeof value === "string") continue;
       issues.push(...validateOperatorObject(value, joinPath(joinPath(expectPath, "headers"), key), targetName));
@@ -74,7 +135,7 @@ function validateHttpTarget(target: Record<string, unknown>, path: string): Conf
   const issues: ConfigValidationIssue[] = [];
   const targetName = getTargetName(target);
   const http = target["http"];
-  if (!isRecord(http)) {
+  if (!isPlainRecord(http)) {
     issues.push(issue("required", joinPath(path, "http"), "缺少 http.url 字段", targetName));
     issues.push(...validateHttpExpect(target, path));
     return issues;
@@ -107,6 +168,61 @@ function validateHttpTarget(target: Record<string, unknown>, path: string): Conf
   return issues;
 }
 
+function validateJsonRule(rule: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (!isPlainRecord(rule)) return [issue("invalid-type", path, "必须为对象", targetName)];
+  const issues: ConfigValidationIssue[] = [];
+  if (typeof rule["path"] !== "string") {
+    issues.push(issue("invalid-type", joinPath(path, "path"), "必须为字符串", targetName));
+  } else {
+    issues.push(...validateJsonPath(rule["path"], path, targetName));
+  }
+  const result = collectOperatorObject(rule, new Set(["path"]), path, targetName);
+  issues.push(
+    ...result.issues,
+    ...validateOperatorObject(result.operators, path, targetName, { requireAtLeastOne: false }),
+  );
+  return issues;
+}
+
+function validateRegexRule(rule: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (typeof rule !== "string") return [issue("invalid-type", path, "必须为字符串", targetName)];
+  try {
+    new RegExp(rule);
+    return [];
+  } catch {
+    return [issue("invalid-regex", path, "正则不合法", targetName)];
+  }
+}
+
+function validateSingleBodyRule(rule: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (!isPlainRecord(rule)) return [issue("invalid-type", path, "必须为对象", targetName)];
+  const found = BodyRuleTypeKeys.filter((type) => type in rule);
+  if (found.length === 0) return [issue("missing-body-rule", path, "缺少支持的规则类型", targetName)];
+  if (found.length > 1) return [issue("multiple-body-rules", path, "只能配置一种规则类型", targetName)];
+
+  const ruleType = found[0]!;
+  const issues: ConfigValidationIssue[] = [];
+  for (const key of Object.keys(rule)) {
+    if (key !== ruleType) issues.push(issue("unknown-field", joinPath(path, key), "是未知字段", targetName));
+  }
+  if (issues.length > 0) return issues;
+
+  switch (ruleType) {
+    case "contains":
+      return typeof rule["contains"] === "string"
+        ? []
+        : [issue("invalid-type", joinPath(path, "contains"), "必须为字符串", targetName)];
+    case "css":
+      return validateCssRule(rule["css"], joinPath(path, "css"), targetName);
+    case "json":
+      return validateJsonRule(rule["json"], joinPath(path, "json"), targetName);
+    case "regex":
+      return validateRegexRule(rule["regex"], joinPath(path, "regex"), targetName);
+    case "xpath":
+      return validateXpathRule(rule["xpath"], joinPath(path, "xpath"), targetName);
+  }
+}
+
 function validateSizeValue(value: number | string, path: string, targetName?: string): ConfigValidationIssue[] {
   try {
     parseSize(value);
@@ -137,3 +253,24 @@ function validateStatusValues(values: unknown[], path: string, targetName?: stri
   }
   return issues;
 }
+
+function validateXpathRule(rule: unknown, path: string, targetName?: string): ConfigValidationIssue[] {
+  if (!isPlainRecord(rule)) return [issue("invalid-type", path, "必须为对象", targetName)];
+  const issues: ConfigValidationIssue[] = [];
+  if (typeof rule["path"] !== "string" || rule["path"].trim() === "") {
+    issues.push(issue("invalid-type", joinPath(path, "path"), "必须为非空字符串", targetName));
+  } else {
+    try {
+      const doc = new DOMParser().parseFromString("<x/>", "text/xml");
+      xpath.select(rule["path"], doc as unknown as Node);
+    } catch {
+      issues.push(issue("invalid-xpath", joinPath(path, "path"), "xpath 不合法", targetName));
+    }
+  }
+  const result = collectOperatorObject(rule, new Set(["path"]), path, targetName);
+  issues.push(
+    ...result.issues,
+    ...validateOperatorObject(result.operators, path, targetName, { requireAtLeastOne: false }),
+  );
+  return issues;
+}